@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/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/model/team/timeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-child event ring behind the Agents board's `timeline` section
+ * (tui-subagent-panel §4.5).
+ *
+ * WHY A RING ON THE RUN rather than a second store: a `SubagentRun` already IS "one
+ * child's projection", and every UI surface reads it through `publish()`. A separate
+ * store would be a second authority for the same subject and would have to be
+ * subscribed to separately - and the four collection points below are all single
+ * funnels that already exist (§4.5.2).
+ *
+ * FIVE KINDS, NOT EVERY TURN (D-12). A turn marker per turn would fill twenty-four
+ * slots in a long task and push out the tool calls, which are the part a reader cannot
+ * reconstruct from the report. Phase changes are visible in the board's `state` field
+ * in real time, so they do not need history.
+ *
+ * BOUNDED AND PURE. `appendTimeline` returns a NEW array (never mutates the old one),
+ * drops the oldest entry past `TEAM_LIMITS.timelineEntries`, and clamps every line to
+ * `TEAM_LIMITS.timelineTextChars`. Purity is what lets `publish()`'s shallow copy hold
+ * a stable snapshot without knowing this module exists (AC-25).
+ *
+ * ASCII ONLY: `src/team/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE TEXT IS ALWAYS BUILT FROM `describeToolActivity` / `sanitizeActivity`, never
+ * from raw tool arguments (D-11 / P1-4). That is the boundary that keeps a
+ * `write_file` body, a `bash` transcript or a child's prompt out of a surface that is
+ * one `JSON.stringify` from a log.
+ */
+import type { SubagentPhase, SubagentRun } from './types.js';
+export type TimelineKind = 'tool' | 'retry' | 'compact' | 'overseer' | 'settle';
+export interface TimelineEntry {
+    kind: TimelineKind;
+    /** Absolute epoch ms, the same units as `startedAt` / `endedAt` / `lastIntervention.at`. */
+    at: number;
+    /** Already sanitized + clamped: at most `TEAM_LIMITS.timelineTextChars` characters. */
+    text: string;
+    /** Whether the tool call succeeded (`tool` only). */
+    ok?: boolean;
+    /** How long the tool call took in ms (`tool` only). */
+    ms?: number;
+}
+export declare function isTerminalPhase(phase: SubagentPhase): boolean;
+/**
+ * Append one event, returning a NEW array. The oldest entry is dropped once the ring
+ * is full, so the array's length is bounded by `max` for every possible input.
+ */
+export declare function appendTimeline(prev: readonly TimelineEntry[] | undefined, entry: TimelineEntry, max?: number): TimelineEntry[];
+/**
+ * The terminal event for one ATTEMPT, or `null` when there is nothing to record yet.
+ *
+ * WHY THIS IS CALLED FROM `publish()` AND NOT FROM `settlePhase` (§4.5.2 / RV-P1-3):
+ * `settlePhase` covers the retry loop's exit only, and two paths set a terminal phase
+ * directly - the worker's "never started" abort and the cold-start backoff abort. Those
+ * are exactly the children whose explanation a reader needs most, and hanging the
+ * settle entry on `settlePhase` alone would leave them with no last event.
+ *
+ * IDEMPOTENCE IS KEYED ON THE ATTEMPT, not on "the last entry is a settle" (I-14): a
+ * retry re-stamps `startedAt`, so a new attempt legitimately earns a second terminal
+ * entry, while a repeated `publish()` of the same attempt adds nothing.
+ */
+export declare function settleTimelineEntry(run: SubagentRun, at: number): TimelineEntry | null;
+/**
+ * The run as a reader should see it: unchanged, or with its attempt's terminal event
+ * appended once. Called from `publish()`, which is every state change's single exit
+ * (§4.5.2) and therefore covers the two paths that set a terminal phase directly.
+ *
+ * ADDED TO THE EMITTED SNAPSHOT, NEVER TO THE LIVE RUN (this is the part `publish()`
+ * makes subtle). `subagent.ts` calls `onUpdate` with a COPY of the run, so writing the
+ * entry onto the object `publish()` receives would be lost - and because
+ * `settleTimelineEntry` uses the live timeline as its idempotence key, a lost write
+ * means every later publish of the same settled child appends another `settle` row to
+ * the ring. Keeping the live run untouched makes the entry a property of the VIEW:
+ * exactly one terminal event per attempt, however many frames are published.
+ */
+export declare function withSettleEntry(run: SubagentRun, at: number): SubagentRun;

package/dist/model/team/timeline.js

@@ -0,0 +1,101 @@
+/**
+ * The per-child event ring behind the Agents board's `timeline` section
+ * (tui-subagent-panel §4.5).
+ *
+ * WHY A RING ON THE RUN rather than a second store: a `SubagentRun` already IS "one
+ * child's projection", and every UI surface reads it through `publish()`. A separate
+ * store would be a second authority for the same subject and would have to be
+ * subscribed to separately - and the four collection points below are all single
+ * funnels that already exist (§4.5.2).
+ *
+ * FIVE KINDS, NOT EVERY TURN (D-12). A turn marker per turn would fill twenty-four
+ * slots in a long task and push out the tool calls, which are the part a reader cannot
+ * reconstruct from the report. Phase changes are visible in the board's `state` field
+ * in real time, so they do not need history.
+ *
+ * BOUNDED AND PURE. `appendTimeline` returns a NEW array (never mutates the old one),
+ * drops the oldest entry past `TEAM_LIMITS.timelineEntries`, and clamps every line to
+ * `TEAM_LIMITS.timelineTextChars`. Purity is what lets `publish()`'s shallow copy hold
+ * a stable snapshot without knowing this module exists (AC-25).
+ *
+ * ASCII ONLY: `src/team/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE TEXT IS ALWAYS BUILT FROM `describeToolActivity` / `sanitizeActivity`, never
+ * from raw tool arguments (D-11 / P1-4). That is the boundary that keeps a
+ * `write_file` body, a `bash` transcript or a child's prompt out of a surface that is
+ * one `JSON.stringify` from a log.
+ */
+import { TEAM_LIMITS } from './limits.js';
+/** The phases that end an attempt. Used by the settle-idempotence rule below. */
+const TERMINAL_PHASES = new Set(['done', 'failed', 'aborted']);
+export function isTerminalPhase(phase) {
+    return TERMINAL_PHASES.has(phase);
+}
+/** Clamp one line to the display budget. Collapses whitespace for the same reason. */
+function clampText(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length <= TEAM_LIMITS.timelineTextChars)
+        return flat;
+    return `${flat.slice(0, TEAM_LIMITS.timelineTextChars - 3)}...`;
+}
+/**
+ * Append one event, returning a NEW array. The oldest entry is dropped once the ring
+ * is full, so the array's length is bounded by `max` for every possible input.
+ */
+export function appendTimeline(prev, entry, max = TEAM_LIMITS.timelineEntries) {
+    const limit = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : TEAM_LIMITS.timelineEntries;
+    const next = [...(prev ?? []), { ...entry, text: clampText(entry.text) }];
+    return next.length > limit ? next.slice(next.length - limit) : next;
+}
+/** The first line of a multi-line answer, clamped - a timeline entry is one line. */
+function head(text) {
+    if (text === undefined || text.length === 0)
+        return '';
+    return clampText(text);
+}
+/**
+ * The terminal event for one ATTEMPT, or `null` when there is nothing to record yet.
+ *
+ * WHY THIS IS CALLED FROM `publish()` AND NOT FROM `settlePhase` (§4.5.2 / RV-P1-3):
+ * `settlePhase` covers the retry loop's exit only, and two paths set a terminal phase
+ * directly - the worker's "never started" abort and the cold-start backoff abort. Those
+ * are exactly the children whose explanation a reader needs most, and hanging the
+ * settle entry on `settlePhase` alone would leave them with no last event.
+ *
+ * IDEMPOTENCE IS KEYED ON THE ATTEMPT, not on "the last entry is a settle" (I-14): a
+ * retry re-stamps `startedAt`, so a new attempt legitimately earns a second terminal
+ * entry, while a repeated `publish()` of the same attempt adds nothing.
+ */
+export function settleTimelineEntry(run, at) {
+    if (!isTerminalPhase(run.phase))
+        return null;
+    const attemptStart = run.startedAt ?? 0;
+    const last = run.timeline?.[run.timeline.length - 1];
+    if (last?.kind === 'settle' && last.at >= attemptStart)
+        return null;
+    const text = run.phase === 'done'
+        ? `done: ${head(run.summary)}`.trim()
+        : run.phase === 'failed'
+            ? `failed: ${head(run.error)}`.trim()
+            : 'aborted';
+    return { kind: 'settle', at, text };
+}
+/**
+ * The run as a reader should see it: unchanged, or with its attempt's terminal event
+ * appended once. Called from `publish()`, which is every state change's single exit
+ * (§4.5.2) and therefore covers the two paths that set a terminal phase directly.
+ *
+ * ADDED TO THE EMITTED SNAPSHOT, NEVER TO THE LIVE RUN (this is the part `publish()`
+ * makes subtle). `subagent.ts` calls `onUpdate` with a COPY of the run, so writing the
+ * entry onto the object `publish()` receives would be lost - and because
+ * `settleTimelineEntry` uses the live timeline as its idempotence key, a lost write
+ * means every later publish of the same settled child appends another `settle` row to
+ * the ring. Keeping the live run untouched makes the entry a property of the VIEW:
+ * exactly one terminal event per attempt, however many frames are published.
+ */
+export function withSettleEntry(run, at) {
+    const settle = settleTimelineEntry(run, at);
+    if (settle === null)
+        return run;
+    return { ...run, timeline: appendTimeline(run.timeline, settle) };
+}

package/dist/model/team/types.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Runtime shapes for team mode (team-subagents §5.1 / §5.2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `TeamEvent` is a CLI-LOCAL stream and must stay that way (D-10 / I-5).
+ * `packages/core` freezes its runtime export list (`public-api.test.ts`) and
+ * forbids host coupling (`no-host-coupling.test.ts`); adding a member to core's
+ * `AgentEvent` union would break the first and teach core about a host shape
+ * (`SubagentRun`) it has no business defining. The whole feature therefore
+ * changes ZERO files under `packages/core/` (AC-12).
+ */
+import type { TokenUsage } from '@aragon-agent/core';
+import type { ActivityArgs } from './activity.js';
+import type { TimelineEntry } from './timeline.js';
+import type { GovernanceSpecExt } from '../governance/types.js';
+/** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
+export interface SubagentSpec {
+    /** Slug, unique within the dispatch. Shown in the panel, the report and logs. */
+    label: string;
+    /** <= TEAM_LIMITS.descriptionChars. What this subagent is for. */
+    description: string;
+    /** <= TEAM_LIMITS.promptChars. Self-contained: the child sees no history. */
+    prompt: string;
+    /**
+     * Force the plan-mode gate on for this child regardless of session mode.
+     * TIGHTENING ONLY (D-13): there is no field anywhere that gives a child more
+     * permission than the session it was spawned from.
+     */
+    readOnly: boolean;
+    /**
+     * Set only by the governance engine (governance-mode section 8.3). Its presence is what
+     * `isGovernedDispatch` reads to keep a governed dispatch out of the transcript.
+     */
+    governance?: GovernanceSpecExt;
+}
+export type SubagentPhase = 'queued' | 'starting' | 'thinking' | 'tool' | 'waiting' | 'done' | 'failed' | 'aborted';
+/** Live, mutable record of one child. Projected into the UI and the report. */
+export interface SubagentRun {
+    label: string;
+    description: string;
+    phase: SubagentPhase;
+    startedAt?: number;
+    endedAt?: number;
+    turns: number;
+    toolCalls: number;
+    lastTool?: string;
+    usage: TokenUsage;
+    /**
+     * Paths seen going through `write_file` / `edit_file`, deduped and capped at
+     * `TEAM_LIMITS.filesTouchedMax`.
+     *
+     * BEST-EFFORT BY CONSTRUCTION: a child that writes through `bash` is invisible
+     * here. The conflict warning in the report says "review before trusting
+     * either" rather than claiming completeness, and that wording is load-bearing
+     * (R-2).
+     */
+    filesTouched: string[];
+    messagesSent: number;
+    /** The child's final assistant text. The only thing the lead sees of its work. */
+    summary?: string;
+    error?: string;
+    /** Hit `team.maxTurnsPerSubagent` and was stopped mid-work. */
+    truncated?: boolean;
+    /**
+     * Compactions this child performed on its OWN history
+     * (context-auto-compaction-hardening §3.4.4 / W3).
+     *
+     * OPTIONAL, so every existing construction site and fixture compiles
+     * unchanged. Absent and `0` mean the same thing to every reader.
+     */
+    compactions?: number;
+    /**
+     * Prose the child is writing right now, sanitized and clamped to
+     * `TEAM_LIMITS.activityChars`. Set only between tool calls; cleared on
+     * `turn_start`, on `tool_execution_start` and on `tool_execution_end` so it
+     * can never describe work the child has already finished.
+     *
+     * THE CLAMP HERE IS A STORAGE CEILING, NOT A COLUMN WIDTH (P0-1). The panel
+     * re-clamps to `activityBudget(cols)` at render. Do not "simplify" by clamping
+     * to the display budget here: this value has no terminal.
+     *
+     * NEVER LOGGED and never persisted: it is ephemeral by construction and a
+     * resumed session has no live dispatch.
+     */
+    activity?: string;
+    /**
+     * The five argument fields any of the nine known tools might want to show,
+     * picked at capture time by `pickActivityArgs` and elided to
+     * `TEAM_LIMITS.activityArgChars` each.
+     *
+     * A PICKED SUBSET, NOT `event.args` (P1-4). The run is shallow-copied into the
+     * live snapshot and into every `agent_update` event by `publish()`, and again
+     * into `DispatchOutcome.runs` by `dispatch()`, which `TeamCard` holds in the
+     * transcript for the session. Holding `event.args` would mean holding
+     * `write_file`'s `content` - a whole file, unbounded - along all of those
+     * paths, and would put a file body one `JSON.stringify` from a log.
+     *
+     * Stored unformatted because the PANEL owns the wide/narrow decision and it is
+     * the only object that knows the terminal width. A formatted string here would
+     * bake one terminal's width into a value the report and the headless writer
+     * also read.
+     *
+     * Cleared on `turn_start` and `tool_execution_end` (P1-5).
+     */
+    activityArgs?: ActivityArgs;
+    /** `team_wait` calls refused as unanswerable (F-3). Pulled from the bus on
+     *  `tool_execution_end`, the same way `messagesSent` is. */
+    blockedWaits?: number;
+    /** Cold-start retries spent (F-4). 0 or absent for the overwhelming majority
+     *  of runs; `1` at most under `TEAM_LIMITS.maxColdStartRetries`. */
+    retries?: number;
+    /**
+     * Whether the error that ended this attempt was transport-level and
+     * retryable, read structurally off `LLMError.retryable`.
+     *
+     * NOT RENDERED ANYWHERE. It exists so `TeamRuntime` can decide without
+     * re-parsing `run.error`, which is a human-facing sentence produced by
+     * `formatStreamError` and must never become a machine-readable contract.
+     */
+    retryable?: boolean;
+    /**
+     * The child's LIVE API-retry state (llm-api-retry-backoff §6.10), or absent when
+     * it is not in a backoff.
+     *
+     * THIS EXISTS BECAUSE A CHILD'S RETRY IS OTHERWISE INVISIBLE (R-14). Subagents
+     * inherit the lead's retry policy for free — `TeamRuntime` reuses the lead's
+     * registry instance — but a child's `retry_scheduled` goes to that CHILD's own
+     * `Agent` listeners and never reaches the lead's `ViewState`. Without this field
+     * a subagent spending three minutes in backoff shows no card, no chip and no
+     * countdown: the dispatch simply appears hung, which is the single worst reading
+     * of a mechanism whose whole claim is that waiting is now legible.
+     *
+     * The fix uses the channel that already exists rather than inventing a second
+     * card: `TeamCard` and `transcript-text` already render one row per child, and
+     * this rides on it. `ViewState.retry` stays LEAD-ONLY, and the lead's status-bar
+     * chip is deliberately NOT driven by children — `agents 3/5` already reports the
+     * dispatch, and a second aggregate would put two numbers on the bar that
+     * disagree about what "3" means.
+     *
+     * EPHEMERAL, exactly like `activity` and `activityArgs`: cleared on the child's
+     * next `turn_end` or terminal error, never persisted, and a settled team entry
+     * keeps only what the run finally did.
+     *
+     * NO `resumeAt`, DELIBERATELY, and this is the one place §6.10's sketch is not
+     * followed. A countdown needs something to re-render it, and nothing does: the
+     * team row is drawn from `agent_update`, a child in backoff emits exactly ONE
+     * event for the whole wait, and the lead's 1 Hz `retryTick` is gated on the
+     * LEAD's own `state.retry`. A `7s` that never changed for thirty seconds is a
+     * worse readout than no number at all — it reads as a hung countdown, which is
+     * precisely the impression this row exists to remove. The counter alone is
+     * honest and is what AC-34 asserts.
+     */
+    retry?: {
+        attempt: number;
+        maxRetries: number;
+    };
+    /**
+     * Supervisor inspections this child received (team-overseer). Optional so
+     * every existing fixture compiles; absent and `0` read the same.
+     */
+    interventions?: number;
+    /**
+     * Supervisor-driven rebuilds this child went through (team-overseer). The
+     * run object survives a rebuild with the same label, so this is where the
+     * report reads "this row is the Nth body of the same brief".
+     */
+    replacements?: number;
+    /**
+     * The most recent supervisor decision applied to this child
+     * (subagent-overseer-v2 section 6). TRANSIENT, never persisted - the
+     * same rule as `activity` / `activityArgs`; a resumed session has no
+     * live dispatch. The strip that enforces it is `PERSIST_STRIP_FIELDS` in
+     * `team/settled.ts` (tui-subagent-panel §4.5.4): it stays on the settled run,
+     * because the card's badge and the supervision report read it there, and the
+     * SAVE boundary is where it is removed.
+     *
+     * `at` is ABSOLUTE epoch ms, the same units as `startedAt` / `endedAt`
+     * (R-P2-3), so the panel renders `nudged 2m` with one subtraction and
+     * no second clock convention. `reasonHead` <= 60 chars, for the UI
+     * badge line only.
+     */
+    lastIntervention?: {
+        action: OverseerAction;
+        at: number;
+        reasonHead: string;
+    };
+    /**
+     * The last `TEAM_LIMITS.timelineEntries` (24) events of this child
+     * (tui-subagent-panel §4.5 / §7).
+     *
+     * EPHEMERAL, on exactly the same terms as `activity` / `activityArgs` / `retry`, and
+     * guaranteed by TWO independent strips (`team/settled.ts`): `settledRun()` at the
+     * dispatch exit and `stripEphemeralRuns()` in `saveSession`'s chain. One gate is not
+     * enough - the live entry's runs are written by `teamUpdate` during a dispatch, so a
+     * checkpoint or an exit flush would otherwise carry the ring to disk (§4.5.4).
+     *
+     * NEVER persisted, never in `aragon exec`'s stream either: `exec/runner.ts`'s
+     * `emitTeam` builds its events from an explicit field list, so a new run field cannot
+     * leak into `stream-json` (AC-22).
+     *
+     * `at` is ABSOLUTE epoch ms (the units of `startedAt` / `lastIntervention.at`), and
+     * each `text` is already sanitized and clamped, so appending is the only write and
+     * `appendTimeline` is the only appender.
+     */
+    timeline?: TimelineEntry[];
+}
+/** What the supervisor may do with one inspected child. */
+export type OverseerAction = 'wait' | 'nudge' | 'replace' | 'abandon';
+/**
+ * One supervisor decision, already normalized and clamped.
+ *
+ * Produced ONLY by `normalizeOverseerDecision` (repair, never reject): an
+ * unparseable or out-of-budget model answer becomes `wait` with the default
+ * interval, because supervision must not kill a healthy child.
+ */
+export interface OverseerDecision {
+    action: OverseerAction;
+    /** <= TEAM_LIMITS.overseerReasonChars. Why, for the report and the log. */
+    reason: string;
+    /** `nudge` only: <= TEAM_LIMITS.overseerGuidanceChars. Steered into the child. */
+    guidance?: string;
+    /** Model-chosen next check, clamped to the structural range. */
+    nextCheckMs?: number;
+}
+/** One supervisor intervention, as recorded on the outcome and rendered. */
+export interface OverseerIntervention {
+    label: string;
+    at: number;
+    action: OverseerAction;
+    reason: string;
+    /**
+     * What the trigger was: event stall, wall-clock check, the child's turn
+     * cap (F-8 A'2 - an inspection the supervisor then ruled on), post-mortem,
+     * or the supervisor going QUIET (subagent-overseer-v2 D-10) - the look
+     * budget ran out and supervision stopped waking this child. A VALUE OF
+     * THE UNION, never a reason prefix: a human-readable sentence is not a
+     * machine contract (the `run.error` rule).
+     */
+    trigger: 'silence' | 'clock' | 'turncap' | 'postmortem' | 'quiet';
+}
+/**
+ * A terminal supervisor decision handed to the WORKER LOOP, which is the only
+ * place a child's `prompt()` is awaited and therefore the only place a
+ * lifecycle change can be applied without orphaning the replacement (I-OV1).
+ *
+ * Set by `TeamRuntime` on the handle, then `handle.abort()`; consumed and
+ * left in place (never cleared) by `runOne` after the await resolves.
+ */
+export interface OverseerVerdict {
+    action: 'replace' | 'abandon';
+    reason: string;
+    guidance?: string;
+}
+/** One message on the team bus. */
+export interface TeamMessage {
+    from: string;
+    to: string;
+    subject: string;
+    body: string;
+    at: number;
+}
+/** Everything one dispatch produced. The sole input to `buildDispatchReport`. */
+export interface DispatchOutcome {
+    dispatchId: string;
+    runs: SubagentRun[];
+    /** Specs the model asked for, BEFORE the cap — the "n of m requested" line. */
+    requested: number;
+    startedAt: number;
+    endedAt: number;
+    aborted: boolean;
+    /** Messages addressed to `lead`; surfaced in their own report section. */
+    leadMail: TeamMessage[];
+    /**
+     * Every supervisor decision that was applied (team-overseer), in order.
+     * Bounded by the per-child inspection budget; rendered as the report's
+     * Overseer section so the lead can see WHO was nudged or replaced and why.
+     */
+    interventions?: OverseerIntervention[];
+    /**
+     * Summed across all children. Real spend; it must reach the status bar
+     * (§3.9). Every child runs the LEAD's model (main-agent parity), so one
+     * total priced at the lead's table is the honest accounting.
+     */
+    usage: TokenUsage;
+    /**
+     * The supervisor's own fast-tier spend for this dispatch
+     * (subagent-overseer-v2 D-7). Absent when nothing supervised the
+     * dispatch; read straight off the provider at dispatch end so there is
+     * exactly one accounting of it.
+     */
+    overseerUsage?: TokenUsage;
+    /** Inspection calls made, including ones that failed softly. */
+    overseerCalls?: number;
+    /**
+     * EDGE-LATCHED, once per dispatch (D-10): the fast tier was missing at
+     * least one cadence tick and the children waited UNASSISTED - announced,
+     * never killed. The per-child wait events of a degraded tick
+     * deliberately do NOT enter `interventions`; this flag plus the tick
+     * count below are the report's aggregate note.
+     */
+    overseerDegraded?: boolean;
+    /** How many cadence ticks ran unassisted (the aggregate note's number). */
+    overseerDegradedTicks?: number;
+}
+/**
+ * What the UI renders: a cheap immutable projection, rebuilt per event.
+ *
+ * Held in `ViewState.team` and NEVER persisted — a resumed session has no live
+ * dispatch, and pretending otherwise is what P1-5 is about.
+ */
+export interface TeamSnapshot {
+    dispatchId: string;
+    active: boolean;
+    runs: SubagentRun[];
+    requested: number;
+    startedAt: number;
+    messageCount: number;
+    lastMessage?: TeamMessage;
+}
+/**
+ * The CLI-local event stream. `TeamRuntime` emits; `AgentController.subscribeTeam`
+ * forwards; `App`, `runHeadless` and `attachTeamEvents` consume.
+ */
+export type TeamEvent = {
+    type: 'dispatch_start';
+    dispatchId: string;
+    requested: number;
+    specs: SubagentSpec[];
+} | {
+    type: 'agent_update';
+    dispatchId: string;
+    run: SubagentRun;
+} | {
+    type: 'usage';
+    dispatchId: string;
+    label: string;
+    usage: TokenUsage;
+} | {
+    type: 'message';
+    dispatchId: string;
+    message: TeamMessage;
+} | {
+    type: 'overseer';
+    dispatchId: string;
+    label: string;
+    decision: OverseerDecision;
+    trigger: OverseerIntervention['trigger'];
+} | {
+    type: 'dispatch_end';
+    dispatchId: string;
+    outcome: DispatchOutcome;
+};
+export type TeamEventListener = (event: TeamEvent) => void;

package/dist/model/team/types.js

@@ -0,0 +1,13 @@
+/**
+ * Runtime shapes for team mode (team-subagents §5.1 / §5.2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `TeamEvent` is a CLI-LOCAL stream and must stay that way (D-10 / I-5).
+ * `packages/core` freezes its runtime export list (`public-api.test.ts`) and
+ * forbids host coupling (`no-host-coupling.test.ts`); adding a member to core's
+ * `AgentEvent` union would break the first and teach core about a host shape
+ * (`SubagentRun`) it has no business defining. The whole feature therefore
+ * changes ZERO files under `packages/core/` (AC-12).
+ */
+export {};