@aragon-agent/cli 0.5.2 → 0.5.4

package/dist/config/schema.js

@@ -6,7 +6,9 @@
  * invariant).
  */
 import { isAbsolute } from 'node:path';
+import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
+import { TEAM_LIMITS } from '../team/limits.js';
 // ---------------------------------------------------------------------------
 // Provider set — only the adapter-backed providers are usable at run time (R5).
 // ---------------------------------------------------------------------------
@@ -88,9 +90,13 @@ export const DEFAULT_TOOL_TIMEOUT_MS = 180_000;
 export const IDLE_TIMEOUT_MARGIN_MS = 30_000;
 /** Watchdog idle timeout (§3.8) — must stay ≥ toolTimeout so long tools survive. */
 export const DEFAULT_IDLE_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS + IDLE_TIMEOUT_MARGIN_MS;
-/** Cap on persisted prompt history / recent-model MRU lists. */
+/**
+ * Cap on the recall list.
+ *
+ * The list itself now lives in `<home>/prompt-history.jsonl`; this constant is
+ * consumed by `config/prompt-history.ts`, not by the UI.
+ */
 export const PROMPT_HISTORY_CAP = 100;
-export const RECENT_MODELS_CAP = 10;
 /**
  * How many trailing entries the full-screen viewport renders (invariant I-3).
  * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
@@ -260,13 +266,61 @@ export function clampLogConfig(raw) {
             : DEFAULT_LOG_CONFIG.previewChars,
     };
 }
+/**
+ * The requirement's ceiling on the fan-out (R-g).
+ *
+ * Re-exported from `TEAM_LIMITS` rather than re-spelled, because it is enforced
+ * in TWO places — here on the config value, and again in
+ * `normalizeSubagentSpecs` on what the model asked for — and two copies of the
+ * same 10 is exactly how a hand-edited `config.json` ends up being able to raise
+ * a ceiling the requirement fixed.
+ */
+export const HARD_MAX_SUBAGENTS = TEAM_LIMITS.hardMaxSubagents;
+export const DEFAULT_TEAM_CONFIG = {
+    enabled: true,
+    maxSubagents: 5,
+    maxConcurrent: 3,
+    subagentTimeoutMs: 300_000,
+    dispatchTimeoutMs: 900_000,
+    maxTurnsPerSubagent: 24,
+};
+const SUBAGENTS_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
+const CONCURRENT_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
+const SUBAGENT_TIMEOUT_RANGE = { min: 30_000, max: 1_800_000 };
+const DISPATCH_TIMEOUT_RANGE = { min: 60_000, max: 3_600_000 };
+const TURNS_RANGE = { min: 4, max: 100 };
+/**
+ * THE single gate for every team-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` for the reason those two record:
+ * hardening only the read path leaves a bad value on disk that reverts to the
+ * default on every launch, which presents to the user as "my setting won't
+ * stick".
+ *
+ * `maxConcurrent` is additionally capped at `maxSubagents`: a pool wider than
+ * the population it draws from is not wrong so much as meaningless, and letting
+ * the two disagree would make the panel's `n/m` readout confusing for no gain.
+ */
+export function clampTeamConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const maxSubagents = clampInt(src.maxSubagents, DEFAULT_TEAM_CONFIG.maxSubagents, SUBAGENTS_RANGE);
+    return {
+        enabled: bool(src.enabled, DEFAULT_TEAM_CONFIG.enabled),
+        maxSubagents,
+        maxConcurrent: Math.min(maxSubagents, clampInt(src.maxConcurrent, DEFAULT_TEAM_CONFIG.maxConcurrent, CONCURRENT_RANGE)),
+        subagentTimeoutMs: clampInt(src.subagentTimeoutMs, DEFAULT_TEAM_CONFIG.subagentTimeoutMs, SUBAGENT_TIMEOUT_RANGE),
+        dispatchTimeoutMs: clampInt(src.dispatchTimeoutMs, DEFAULT_TEAM_CONFIG.dispatchTimeoutMs, DISPATCH_TIMEOUT_RANGE),
+        maxTurnsPerSubagent: clampInt(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
     model: DEFAULT_MODEL,
     baseUrl: null,
     thinkingLevel: 'off',
-    maxTokens: null,
+    // The engine owns this number; spelling it here again is how the CLI and the
+    // provider adapters end up disagreeing about what "the default" is.
+    maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
     theme: 'auto',
     reducedMotion: false,
     fullscreen: true,
@@ -276,24 +330,56 @@ export const DEFAULT_CONFIG = {
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
     apiKeys: {},
-    recentModels: [],
-    promptHistory: [],
+    historyEnabled: true,
     density: 'comfortable',
     hints: true,
     mouse: true,
-    mouseNoticeSeen: false,
-    submitCount: 0,
     planModeDefault: false,
     planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,
     planModeHumanTimeoutMs: DEFAULT_PLAN_HUMAN_TIMEOUT_MS,
     skills: DEFAULT_SKILLS_CONFIG,
     log: DEFAULT_LOG_CONFIG,
+    team: DEFAULT_TEAM_CONFIG,
 };
+/**
+ * Runtime state that used to be stored in `config.json` by mistake
+ * (config-state-separation §4.5). Each one now lives in its own file:
+ * `promptHistory` → `prompt-history.jsonl`, `submitCount` / `mouseNoticeSeen`
+ * → `state.json`, and `recentModels` was dead — nothing ever wrote it.
+ */
+export const LEGACY_STATE_KEYS = [
+    'promptHistory',
+    'submitCount',
+    'mouseNoticeSeen',
+    'recentModels',
+];
+/**
+ * THE single gate that keeps those keys out of `config.json`, and the one thing
+ * in this change that cannot be skipped.
+ *
+ * `loadPersistedConfig()` merges `{ ...DEFAULT_CONFIG, ...partial }` where
+ * `partial` is the raw parse of whatever is on disk. Removing the fields from
+ * the interface therefore removes NOTHING from the file: the keys ride through
+ * the spread and `updatePersistedConfig` writes them straight back. The user
+ * deletes `promptHistory` by hand and watches it grow back.
+ *
+ * Applied on the READ side on purpose, which is what makes it self-healing:
+ * every write goes read-strip-merge-write, so a hand-edited file, a downgrade
+ * to 0.5.x and back, or a half-finished migration all converge on a clean file
+ * at the next write. Same shape as `clampSkillsConfig` / `clampLogConfig` —
+ * one door for both directions.
+ */
+export function stripLegacyStateKeys(raw) {
+    const out = { ...raw };
+    for (const key of LEGACY_STATE_KEYS)
+        delete out[key];
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Coercion / validation helpers
 // ---------------------------------------------------------------------------
 /** Coerce an arbitrary value into a positive integer, or `undefined`. */
-export function coerceMaxTokens(v) {
+function coerceTokenCount(v) {
     if (v === null || v === undefined || v === '')
         return undefined;
     const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
@@ -301,6 +387,74 @@ export function coerceMaxTokens(v) {
         return undefined;
     return Math.floor(n);
 }
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
+export function coerceMaxTokens(v) {
+    return coerceTokenCount(v);
+}
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export const MAX_TOKENS_RANGE = {
+    min: MIN_MAX_OUTPUT_TOKENS,
+    max: ABSOLUTE_MAX_OUTPUT_TOKENS,
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export function isAutoToken(v) {
+    if (v === 0)
+        return true;
+    if (typeof v !== 'string')
+        return false;
+    const trimmed = v.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'auto' || trimmed === '0';
+}
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export function clampMaxTokens(v) {
+    const n = coerceTokenCount(v);
+    if (n === undefined)
+        return undefined;
+    return Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, n));
+}
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export function parseMaxTokensInput(raw) {
+    const trimmed = String(raw ?? '').trim();
+    if (isAutoToken(trimmed))
+        return { kind: 'auto' };
+    if (!/^\d+$/.test(trimmed))
+        return { kind: 'invalid' };
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return { kind: 'invalid' };
+    const value = Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, parsed));
+    return { kind: 'value', value, clamped: value !== parsed };
+}
+/** The product default, re-exported so the CLI never spells the number itself. */
+export const DEFAULT_MAX_TOKENS = DEFAULT_MAX_OUTPUT_TOKENS;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export function coercePositiveInt(v, fallback) {
     if (v === null || v === undefined || v === '')

package/dist/config/store.js

@@ -14,7 +14,23 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+/**
+ * Normalize `maxTokens` for both directions of the config file.
+ *
+ * `null` MEANS AUTO and must survive untouched; a number is clamped to the
+ * accepted range; anything else on a hand-edited file (a string, a float, a
+ * negative) becomes AUTO rather than a silent default. Same discipline as
+ * `clampSkillsConfig` — read AND write pass through one gate, or a bad value on
+ * disk reverts on every launch and presents as "my setting won't stick".
+ */
+function normalizeMaxTokens(v) {
+    if (v === undefined)
+        return DEFAULT_CONFIG.maxTokens;
+    if (v === null || isAutoToken(v))
+        return null;
+    return clampMaxTokens(v) ?? null;
+}
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -82,19 +98,30 @@ export function writeConfigFile(config) {
  * Unlike `readConfigFile`, this always returns a complete `PersistedConfig`.
  */
 export function loadPersistedConfig() {
-    const partial = readConfigFile().config ?? {};
+    // STRIP BEFORE THE SPREAD, not after. `partial` is the raw file, so any
+    // `promptHistory` / `submitCount` / `mouseNoticeSeen` / `recentModels` left
+    // on disk would otherwise ride the spread into `merged` and be written back
+    // out by `updatePersistedConfig` — the "I deleted it and it grew back" bug
+    // that `stripLegacyStateKeys` exists to make impossible (§4.5).
+    const partial = stripLegacyStateKeys(readConfigFile().config ?? {});
     return {
         ...DEFAULT_CONFIG,
         ...partial,
         version: CONFIG_VERSION,
+        // Own-property aware, because `null` is the value we need to preserve: a
+        // spread cannot tell "the key is absent" (⇒ the default) from "the key is
+        // null" (⇒ AUTO), and those are different settings.
+        maxTokens: Object.prototype.hasOwnProperty.call(partial, 'maxTokens')
+            ? normalizeMaxTokens(partial.maxTokens)
+            : DEFAULT_CONFIG.maxTokens,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
-        recentModels: partial.recentModels ?? [],
-        promptHistory: partial.promptHistory ?? [],
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
         skills: clampSkillsConfig({ ...DEFAULT_CONFIG.skills, ...(partial.skills ?? {}) }),
         // `log` is the third. Same one-level rule, same merge.
         log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
+        // `team` is the fourth. Same one-level rule, same merge.
+        team: clampTeamConfig({ ...DEFAULT_CONFIG.team, ...(partial.team ?? {}) }),
     };
 }
 /**
@@ -126,12 +153,21 @@ export function updatePersistedConfig(patch) {
         ...current,
         ...patch,
         version: CONFIG_VERSION,
+        // The write half of the gate: without it `config set maxTokens 900000` puts
+        // a number on disk that the read path silently rewrites on every launch.
+        maxTokens: Object.prototype.hasOwnProperty.call(patch, 'maxTokens')
+            ? normalizeMaxTokens(patch.maxTokens)
+            : current.maxTokens,
         apiKeys: { ...current.apiKeys, ...(patch.apiKeys ?? {}) },
         skills: clampSkillsConfig({ ...current.skills, ...(patch.skills ?? {}) }),
         // Without this line, changing the log level from the settings screen would
         // replace the whole section and quietly revert `maxFiles`, `previewChars`
         // and — worst of all — `redactSecrets`.
         log: clampLogConfig({ ...current.log, ...(patch.log ?? {}) }),
+        // The fourth section, and it needs the merge for the same reason: `/team max
+        // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
+        // turn into "changing the fan-out width silently reverted every timeout".
+        team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/config/ui-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+export declare const UI_STATE_FILENAME = "state.json";
+export declare const UI_STATE_SCHEMA = 1;
+export interface UiState {
+    schema: number;
+    /** Lifetime submit count; drives the composer hint fade (`HINT_FADE_AFTER`). */
+    submitCount: number;
+    /** Whether the one-shot "hold Shift to select text" notice has been shown. */
+    mouseNoticeSeen: boolean;
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export declare function loadUiState(): UiState;
+export declare function readSubmitCount(): number;
+/** Increment, persist, and return the new value. */
+export declare function bumpSubmitCount(): number;
+export declare function getMouseNoticeSeen(): boolean;
+export declare function setMouseNoticeSeen(seen: boolean): void;
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export declare function importLegacyUiState(patch: Partial<Pick<UiState, 'submitCount' | 'mouseNoticeSeen'>>): void;
+/** Test-only: forget the cached state. */
+export declare function resetUiStateForTests(): void;

package/dist/config/ui-state.js

@@ -0,0 +1,149 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import process from 'node:process';
+import { getHomeRoot, getUiStatePath } from './app-paths.js';
+export const UI_STATE_FILENAME = 'state.json';
+export const UI_STATE_SCHEMA = 1;
+const DEFAULT_UI_STATE = {
+    schema: UI_STATE_SCHEMA,
+    submitCount: 0,
+    mouseNoticeSeen: false,
+};
+let memory = null;
+function coerceCount(value) {
+    const n = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_UI_STATE.submitCount;
+    return Math.floor(n);
+}
+/**
+ * Per-field tolerance: one nonsense value must not take the other field with
+ * it. A wrong SCHEMA is different — the shape is no longer known, so the whole
+ * object falls back (the rule `skills/usage.ts` already follows).
+ */
+function readFromDisk() {
+    const path = getUiStatePath();
+    if (!existsSync(path))
+        return { ...DEFAULT_UI_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { ...DEFAULT_UI_STATE };
+        if (parsed.schema !== UI_STATE_SCHEMA)
+            return { ...DEFAULT_UI_STATE };
+        return {
+            schema: UI_STATE_SCHEMA,
+            submitCount: coerceCount(parsed.submitCount),
+            mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
+                ? parsed.mouseNoticeSeen
+                : DEFAULT_UI_STATE.mouseNoticeSeen,
+        };
+    }
+    catch {
+        return { ...DEFAULT_UI_STATE };
+    }
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export function loadUiState() {
+    if (memory === null)
+        memory = readFromDisk();
+    return memory;
+}
+/**
+ * Atomic write: temp file, rename, re-chmod.
+ *
+ * `mkdirSync` first for the reason spelled out in `prompt-history.ts`: `<home>`
+ * is not guaranteed to exist, and without it the counter would silently never
+ * persist on a fresh install that also turned file logging off (RV-2).
+ * The `chmodSync` matches `store.ts` — rename does not preserve mode on every
+ * platform (RV-6).
+ */
+function writeToDisk(state) {
+    const path = getUiStatePath();
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the value simply stays in memory (C2).
+        }
+    }
+}
+function update(patch) {
+    const next = { ...loadUiState(), ...patch, schema: UI_STATE_SCHEMA };
+    memory = next;
+    writeToDisk(next);
+    return next;
+}
+export function readSubmitCount() {
+    return loadUiState().submitCount;
+}
+/** Increment, persist, and return the new value. */
+export function bumpSubmitCount() {
+    return update({ submitCount: readSubmitCount() + 1 }).submitCount;
+}
+export function getMouseNoticeSeen() {
+    return loadUiState().mouseNoticeSeen;
+}
+export function setMouseNoticeSeen(seen) {
+    update({ mouseNoticeSeen: seen });
+}
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export function importLegacyUiState(patch) {
+    const current = loadUiState();
+    const next = {};
+    if (patch.submitCount !== undefined &&
+        current.submitCount === DEFAULT_UI_STATE.submitCount) {
+        next.submitCount = coerceCount(patch.submitCount);
+    }
+    if (patch.mouseNoticeSeen !== undefined &&
+        current.mouseNoticeSeen === DEFAULT_UI_STATE.mouseNoticeSeen) {
+        next.mouseNoticeSeen = patch.mouseNoticeSeen === true;
+    }
+    if (Object.keys(next).length === 0)
+        return;
+    update(next);
+}
+/** Test-only: forget the cached state. */
+export function resetUiStateForTests() {
+    memory = null;
+}

package/dist/logging/install.d.ts

@@ -161,3 +161,88 @@ export type AgentLogEvent = {
  * (or a future second controller) read another's clock.
  */
 export declare function attachAgentEvents(logger: Logger, controller: AgentEventSource): () => void;
+/**
+ * What `attachTeamEvents` needs from a controller. Structural for the same
+ * reason `AgentEventSource` is, and OPTIONAL on the method: a controller built
+ * with team mode off has no runtime and therefore no events.
+ */
+export interface TeamEventSource {
+    subscribeTeam?(listener: (event: TeamLogEvent) => void): () => void;
+}
+/** The five members of the CLI-local `TeamEvent` union, as this module reads them. */
+export type TeamLogEvent = {
+    type: 'dispatch_start';
+    dispatchId: string;
+    requested: number;
+    specs?: Array<{
+        label?: string;
+        description?: string;
+        prompt?: string;
+    }>;
+} | {
+    type: 'agent_update';
+    dispatchId: string;
+    run?: {
+        label?: string;
+        phase?: string;
+        lastTool?: string;
+    };
+} | {
+    type: 'usage';
+    dispatchId: string;
+    label?: string;
+    usage?: unknown;
+} | {
+    type: 'message';
+    dispatchId: string;
+    message?: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        body?: string;
+    };
+} | {
+    type: 'dispatch_end';
+    dispatchId: string;
+    outcome?: {
+        startedAt?: number;
+        endedAt?: number;
+        aborted?: boolean;
+        runs?: Array<{
+            phase?: string;
+            error?: string;
+            filesTouched?: string[];
+        }>;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+        };
+    };
+};
+/**
+ * Record a dispatch's lifecycle.
+ *
+ * WITHOUT THIS, A DISPATCH LEAVES NO TRACE IN THE LOG AT ALL (P1-2 / R-19).
+ * `TeamEvent` is deliberately CLI-local (D-10), so `attachAgentEvents` cannot
+ * see it — which is the wrong outcome for the one feature in this CLI that runs
+ * five agents the user cannot watch, and whose only other artefact is a report
+ * written by the thing that failed. A separate function rather than a branch in
+ * `attachAgentEvents` (D-19): the two consume different unions and want
+ * different level policies.
+ *
+ * TWO RULES, BOTH ABOUT NOT TURNING A LOG INTO A LIABILITY:
+ *
+ *  - A subagent's PROMPT and its SUMMARY are `trace` only, and go through the
+ *    same redaction every other record does. A `prompt` is up to 8 000
+ *    characters of whatever the lead decided to say; at `debug` it would
+ *    dominate the file.
+ *  - A `team_send` BODY is never recorded at any level. The subject is enough to
+ *    reconstruct who talked to whom and when, which is the diagnostic question;
+ *    the body is user content that reached no other sink.
+ *
+ * `agent_update` is recorded on PHASE TRANSITIONS ONLY, not on the 120 ms
+ * coalescer tick: that throttle exists to protect React, and five children at
+ * eight events a second each is 40 lines a second of noise that would push the
+ * retention window down to minutes.
+ */
+export declare function attachTeamEvents(logger: Logger, controller: TeamEventSource): () => void;