@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/team/model.d.ts

@@ -1,104 +0,0 @@
-/**
- * `resolveSubagentModel` — THE single authority on which model a team child
- * runs (subagent-model-and-question-controls §3.3).
- *
- * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
- *
- * EVERY CONSUMER READS THE CHILD'S MODEL THROUGH THIS FUNCTION AND NOWHERE
- * ELSE — `createSubagent`, the `task` report header and the settings root row —
- * following the `resolveFastTier` precedent one directory over: three call
- * sites each recomputing "which model do children run on?" from raw
- * config keys is exactly how the report ends up naming a model the children
- * silently fell back from.
- *
- * IT IS RE-RUN ON EVERY DISPATCH AND EVERY RENDER, NOT ONCE (rule 8 / RV-3 of
- * the fast tier, inherited here): `team.model`, the fast tier and the profile
- * library are all LIVE keys a settings save (the `Subagent model` row), `/fast
- * off` or a kit can rewrite mid-session. A resolution captured at construction would be a
- * resolution describing a session that no longer exists.
- *
- * A CHILD IS NEVER LEFT WITHOUT A MODEL (D-4). Every failure mode — fast tier
- * off, profile deleted, profile key missing — degrades to the MAIN connection
- * with a `fallbackReason`, so a dispatch cannot fail because its model setting
- * went stale. The reason is disclosed, never swallowed: the report header and
- * the settings summary line both render it.
- */
-import type { ModelCost, ModelRef, ThinkingLevel, TokenUsage } from '@aragon-agent/core';
-import type { ModelProfile, ModelRole } from '../config/model-profiles.js';
-import type { CliConfig } from '../config/schema.js';
-/** Which model children run on. `main` is the default and the historical behavior. */
-export type SubagentModelMode = 'main' | 'fast' | 'profile';
-/** Why a non-main request degraded to the main model (D-4 disclosure). */
-export type SubagentFallbackReason = 
-/** `team.model='fast'` but `resolveFastTier` is not ok (off, unconfigured, no key). */
-'fast_unavailable'
-/** `modelProfileId` is absent from the library (deleted, or never existed). */
- | 'profile_missing'
-/** The entry exists but carries no key of its own and the shared layer has none. */
- | 'profile_no_key';
-/** In-memory resolution; recomputed per dispatch/render, never persisted (§6.3). */
-export interface SubagentModelResolution {
-    /** The user's requested mode, verbatim from config (UI highlight reads this). */
-    mode: SubagentModelMode;
-    /** The mode actually in effect; `'main'` whenever a fallback fired. */
-    effective: SubagentModelMode;
-    /** The connection children will use. On fallback, exactly the main connection. */
-    ref: ModelRef;
-    /** main/profile take `config.thinkingLevel`; fast takes `config.fast.thinkingLevel`. */
-    thinkingLevel: ThinkingLevel;
-    /** The role controller key resolution uses: main/profile `'main'`, fast `'fast'`. */
-    keyRole: ModelRole;
-    /** The profile entry a `profile` request hit, dedicated key included; else null. */
-    profile: ModelProfile | null;
-    /** Present only when `effective !== mode`. */
-    fallbackReason?: SubagentFallbackReason;
-}
-/** What `priceTeamUsage` needs from the controller: the lead's table and the lookup. */
-export interface TeamPriceBook {
-    /** The lead's own price table (`main` mode prices at exactly this). */
-    mainCost: ModelCost | undefined;
-    isPriced: (ref: ModelRef) => boolean;
-    costFor: (ref: ModelRef) => ModelCost | undefined;
-}
-/**
- * USD for one child `usage` event, at the model the children ACTUALLY ran.
- *
- * The status bar and the dispatch report must agree, so both price through the same
- * resolution: under the default `main` mode this is the lead's table (byte parity),
- * otherwise the fast / profile model's. A model no table prices contributes ZERO rather
- * than a fabricated figure (C-11 / RV-4), where the report says `pricing unknown`.
- */
-export declare function priceTeamUsage(resolution: SubagentModelResolution, usage: TokenUsage, book: TeamPriceBook): number;
-/** The `AgentController.hasApiKey` shape, injected so there is one key resolver. */
-export type HasApiKey = (providerId: string, role?: ModelRole) => boolean;
-/** The lead-layer key resolver `resolveSubagentKey` falls back to. */
-export type SharedKeyResolver = (providerId: string, role: ModelRole) => string | undefined;
-/**
- * Resolve the model every child of the NEXT dispatch will run on.
- *
- * Pure, synchronous, no IO — testable as a matrix over config fixtures.
- *
- * @param config The live effective config. Read fresh; never snapshot it.
- * @param hasKey `AgentController.hasApiKey`, which already resolves the
- *   config-file key, the provider environment variable and the one-shot
- *   `--api-key` override. Injected rather than reimplemented for the reason
- *   `resolveFastTier` records: a second key resolver is a second answer to
- *   "why does it say no key?".
- */
-export declare function resolveSubagentModel(config: CliConfig, hasKey: HasApiKey): SubagentModelResolution;
-/**
- * The key a CHILD resolves for a provider, profile-aware (§3.3 / I-4).
- *
- * A profile's dedicated key is visible ONLY here: it never reaches env,
- * `config.apiKeys` or a log line. While the resolution's profile is bound and
- * the provider matches it, the entry key takes priority over the shared layer;
- * every other provider (and every non-profile mode) resolves through the
- * lead's own resolver at `resolution.keyRole` — which is what keeps a `fast`
- * child entitled to the fast-role key and a `main` child to the main one.
- *
- * @param config The live config (carried for parity with the resolver pair).
- * @param resolution A fresh `resolveSubagentModel` output.
- * @param providerId The provider the child needs a key for.
- * @param shared The lead-layer resolver (`controller.resolveKey`).
- */
-export declare function resolveSubagentKey(config: CliConfig, resolution: SubagentModelResolution, providerId: string, shared: SharedKeyResolver): string | undefined;

package/dist/team/model.js

@@ -1,150 +0,0 @@
-/**
- * `resolveSubagentModel` — THE single authority on which model a team child
- * runs (subagent-model-and-question-controls §3.3).
- *
- * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
- *
- * EVERY CONSUMER READS THE CHILD'S MODEL THROUGH THIS FUNCTION AND NOWHERE
- * ELSE — `createSubagent`, the `task` report header and the settings root row —
- * following the `resolveFastTier` precedent one directory over: three call
- * sites each recomputing "which model do children run on?" from raw
- * config keys is exactly how the report ends up naming a model the children
- * silently fell back from.
- *
- * IT IS RE-RUN ON EVERY DISPATCH AND EVERY RENDER, NOT ONCE (rule 8 / RV-3 of
- * the fast tier, inherited here): `team.model`, the fast tier and the profile
- * library are all LIVE keys a settings save (the `Subagent model` row), `/fast
- * off` or a kit can rewrite mid-session. A resolution captured at construction would be a
- * resolution describing a session that no longer exists.
- *
- * A CHILD IS NEVER LEFT WITHOUT A MODEL (D-4). Every failure mode — fast tier
- * off, profile deleted, profile key missing — degrades to the MAIN connection
- * with a `fallbackReason`, so a dispatch cannot fail because its model setting
- * went stale. The reason is disclosed, never swallowed: the report header and
- * the settings summary line both render it.
- */
-import { computeCost } from '../agent/usage.js';
-import { resolveFastTier } from '../fast/resolve.js';
-/**
- * USD for one child `usage` event, at the model the children ACTUALLY ran.
- *
- * The status bar and the dispatch report must agree, so both price through the same
- * resolution: under the default `main` mode this is the lead's table (byte parity),
- * otherwise the fast / profile model's. A model no table prices contributes ZERO rather
- * than a fabricated figure (C-11 / RV-4), where the report says `pricing unknown`.
- */
-export function priceTeamUsage(resolution, usage, book) {
-    if (resolution.effective === 'main')
-        return computeCost(usage, book.mainCost);
-    return book.isPriced(resolution.ref) ? computeCost(usage, book.costFor(resolution.ref)) : 0;
-}
-function mainRef(config) {
-    return {
-        providerId: config.provider,
-        modelId: config.model,
-        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
-    };
-}
-function fallbackToMain(config, mode, fallbackReason) {
-    // THE ALWAYS-USABLE ANSWER (D-4): whatever the user asked for that could not
-    // resolve, the caller still gets a working connection — the same provider,
-    // model, base URL and thinking level the lead itself runs on.
-    return {
-        mode,
-        effective: 'main',
-        ref: mainRef(config),
-        thinkingLevel: config.thinkingLevel,
-        keyRole: 'main',
-        profile: null,
-        fallbackReason,
-    };
-}
-/**
- * Resolve the model every child of the NEXT dispatch will run on.
- *
- * Pure, synchronous, no IO — testable as a matrix over config fixtures.
- *
- * @param config The live effective config. Read fresh; never snapshot it.
- * @param hasKey `AgentController.hasApiKey`, which already resolves the
- *   config-file key, the provider environment variable and the one-shot
- *   `--api-key` override. Injected rather than reimplemented for the reason
- *   `resolveFastTier` records: a second key resolver is a second answer to
- *   "why does it say no key?".
- */
-export function resolveSubagentModel(config, hasKey) {
-    // `clampTeamConfig` guarantees the enum on every read and write path, so the
-    // default `'main'` here is belt-and-braces rather than a real branch.
-    const mode = config.team.model ?? 'main';
-    if (mode === 'fast') {
-        const tier = resolveFastTier(config, hasKey);
-        if (tier.ok) {
-            return {
-                mode,
-                effective: 'fast',
-                ref: tier.ref,
-                thinkingLevel: config.fast.thinkingLevel,
-                keyRole: 'fast',
-                profile: null,
-            };
-        }
-        return fallbackToMain(config, mode, 'fast_unavailable');
-    }
-    if (mode === 'profile') {
-        // A missing library, a missing id and a dangling id are one outcome
-        // (D-4): degrade to main and say so. Reference EXISTENCE is deliberately
-        // not validated in `clampTeamConfig` — resolution is where it belongs.
-        const id = config.team.modelProfileId;
-        const entry = id
-            ? config.modelProfiles?.entries.find((candidate) => candidate.id === id)
-            : undefined;
-        if (!entry)
-            return fallbackToMain(config, mode, 'profile_missing');
-        // The dedicated entry key wins; without one the shared layer must have a
-        // key for the entry's provider, or the child could not authenticate at all.
-        if (!entry.apiKey && !hasKey(entry.provider, 'main')) {
-            return fallbackToMain(config, mode, 'profile_no_key');
-        }
-        return {
-            mode,
-            effective: 'profile',
-            ref: {
-                providerId: entry.provider,
-                modelId: entry.model,
-                ...(entry.baseUrl ? { baseUrl: entry.baseUrl } : {}),
-            },
-            thinkingLevel: config.thinkingLevel,
-            keyRole: 'main',
-            profile: entry,
-        };
-    }
-    return {
-        mode: 'main',
-        effective: 'main',
-        ref: mainRef(config),
-        thinkingLevel: config.thinkingLevel,
-        keyRole: 'main',
-        profile: null,
-    };
-}
-/**
- * The key a CHILD resolves for a provider, profile-aware (§3.3 / I-4).
- *
- * A profile's dedicated key is visible ONLY here: it never reaches env,
- * `config.apiKeys` or a log line. While the resolution's profile is bound and
- * the provider matches it, the entry key takes priority over the shared layer;
- * every other provider (and every non-profile mode) resolves through the
- * lead's own resolver at `resolution.keyRole` — which is what keeps a `fast`
- * child entitled to the fast-role key and a `main` child to the main one.
- *
- * @param config The live config (carried for parity with the resolver pair).
- * @param resolution A fresh `resolveSubagentModel` output.
- * @param providerId The provider the child needs a key for.
- * @param shared The lead-layer resolver (`controller.resolveKey`).
- */
-export function resolveSubagentKey(config, resolution, providerId, shared) {
-    void config; // parity parameter: the pair reads one config, the key does not need it
-    if (resolution.profile && providerId === resolution.ref.providerId) {
-        return resolution.profile.apiKey ?? shared(providerId, 'main');
-    }
-    return shared(providerId, resolution.keyRole);
-}

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

@@ -1,48 +0,0 @@
-/**
- * `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

@@ -1,75 +0,0 @@
-/**
- * `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/timeline.d.ts

@@ -1,74 +0,0 @@
-/**
- * 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/team/timeline.js

@@ -1,101 +0,0 @@
-/**
- * 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) };
-}