@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/config/schema.d.ts

@@ -5,7 +5,7 @@
  * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
  * invariant).
  */
-import { type ThinkingLevel } from '@aragon-agent/core';
+import { type RetryPolicy, type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
 import type { FollowThroughMode } from '../todo/types.js';
 /**
@@ -64,15 +64,40 @@ export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
  */
 export declare const PROMPT_HISTORY_CAP = 100;
 /**
- * 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
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export declare const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export declare const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
-export declare const MAX_TRANSCRIPT_WINDOW = 2000;
+export declare const MAX_TRANSCRIPT_WINDOW = 20000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export declare const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export declare const MIN_TRANSCRIPT_RETAIN = 200;
+export declare const MAX_TRANSCRIPT_RETAIN = 20000;
+export declare function clampTranscriptRetain(v: unknown, fallback: number): number;
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export declare const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export declare const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+export declare function clampMaxRenderInterval(v: unknown, fallback: number): number;
 /** `ask_user` calls allowed per user turn. */
 export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
@@ -274,12 +299,171 @@ export declare const DEFAULT_TODO_CONFIG: TodoConfig;
  * setting won't stick".
  */
 export declare function clampTodoConfig(raw: unknown): TodoConfig;
+export interface RetryConfig {
+    /**
+     * The user's switch. KEPT SEPARATE FROM `maxRetries: 0` on purpose: `enabled`
+     * survives round-tripping through the settings screen, while `maxRetries: 0` is
+     * what `toRetryPolicy` produces from it. Folding them would make
+     * `/retry off; /retry on` forget the user's chosen count.
+     */
+    enabled: boolean;
+    /** Retries AFTER the initial attempt. `0` is the kill switch, not a typo. */
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    /** Growth factor. THE ONLY FLOAT KEY in this section. */
+    multiplier: number;
+    jitter: boolean;
+    respectRetryAfter: boolean;
+    /** Wall-clock budget from the first failure of one request. */
+    maxElapsedMs: number;
+    /** Allow a restart after content has already streamed to the transcript. */
+    onPartialStream: boolean;
+}
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * `hardMaxRetries` re-exported rather than re-spelled, for the reason
+ * `HARD_MAX_SUBAGENTS` records: the ceiling is enforced in TWO places — here on
+ * the config value, and again by `normalizePolicy` inside the engine — and two
+ * copies of the same 20 is exactly how a hand-edited `config.json` ends up able
+ * to raise a ceiling the mechanism fixed.
+ */
+export declare const HARD_MAX_RETRIES: 20;
+/**
+ * THE single gate for every retry-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those 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".
+ *
+ * Three invariants live inside the gate:
+ *
+ *  - `maxDelayMs = max(maxDelayMs, initialDelayMs)` — a ceiling under the floor
+ *    makes the ladder a flat line and the countdown a lie.
+ *  - `multiplier` goes through `clampNumber`, not `clampInt`: `2.5` is a
+ *    legitimate factor and `coercePositiveInt` would floor it to 2.
+ *  - `maxRetries` goes through `clampIntAllowingZero`. THIS IS THE ONE THAT SHIPS
+ *    BROKEN WITHOUT IT (R-16): `clampInt` returns the fallback for `n <= 0`, so
+ *    `clampRetryConfig({ maxRetries: 0 })` would yield 10 — the maximum instead
+ *    of the minimum, silently, for the key that gates the whole feature.
+ *
+ * `maxElapsedMs` intentionally keeps plain `clampInt`: its floor is 10 000, so it
+ * has no `0` to express.
+ */
+export declare function clampRetryConfig(raw: unknown): RetryConfig;
+/**
+ * `RetryConfig` (user intent) -> `RetryPolicy` (engine policy), or `null` for
+ * "the user said no".
+ *
+ * `null` rather than a policy with `maxRetries: 0` because `ProviderRegistry`
+ * short-circuits on a null policy and returns the adapter's iterator DIRECTLY —
+ * an opted-out session is then allocation-identical to a pre-feature build.
+ *
+ * TOTAL, AND IT ACCEPTS A MISSING SECTION. `loadConfig` always supplies one, but
+ * a `CliConfig` built by hand — every controller test in this package does exactly
+ * that, and so would an embedder — legitimately omits it, and a `TypeError` from a
+ * pure translation function is the wrong way to find out. Routing through
+ * `clampRetryConfig` also means an out-of-range hand-built value can never reach
+ * the engine, which is the same "one gate, both directions" rule every other
+ * section in this file follows.
+ */
+export declare function toRetryPolicy(cfg: RetryConfig | undefined): RetryPolicy | null;
+export interface FastConfig {
+    /**
+     * Resolve the tier at all. Defaults to FALSE (R-d).
+     *
+     * OFF IS BYTE-IDENTICAL (I-2): with this false the system prompt, `task`'s
+     * schema, the tool array, the transcript, the status bar and the request
+     * payloads are exactly what a pre-feature build produces.
+     */
+    enabled: boolean;
+    /** `''` INHERITS the main provider — what makes `fast.model` alone a complete
+     *  configuration for the common "same vendor, cheaper model" case. */
+    provider: string;
+    /** The fast model id. Empty means NOT CONFIGURED, never "same as main": that
+     *  distinction is what keeps R-e (opt in to fast == main) from being
+     *  indistinguishable from a typo (D-4). */
+    model: string;
+    /** `''` inherits only when the provider matches — a base URL belongs to one
+     *  API, so a fast tier on a different vendor must not borrow it. */
+    baseUrl: string;
+    /** Applied to fast-tier children and to the review call. Defaults to `'off'`:
+     *  a "fast" model asked to think for 32 768 tokens is not fast (D-13). */
+    thinkingLevel: ThinkingLevel;
+    /** Allow `model: "fast"` on `task`. */
+    delegate: boolean;
+    /** Run the periodic asynchronous review. */
+    review: boolean;
+    /** Completed turns between reviews. */
+    reviewEveryTurns: number;
+    /** Turn frames included in one digest. */
+    reviewContextTurns: number;
+    /** Ceiling on an injected critique, in characters. */
+    reviewMaxChars: number;
+    /**
+     * Reviews STARTED per session, across all runs (fast-model-tier-hardening
+     * §4.1 / W1).
+     *
+     * The one bound on spend the user never asked for. `reviewEveryTurns`
+     * controls the PACE; this controls the TOTAL — and the two are different
+     * questions, because a session is not one run. `reviewsThisRun` is reset by
+     * every user message, so thirty messages buys thirty runs' worth of reviews
+     * with nothing counting across them.
+     *
+     * DENOMINATED IN REVIEWS, NOT CURRENCY (D-H1). The fast tier is by
+     * construction the likeliest place in the product to name a model the static
+     * cost table has never seen, and `buildRuntimeModel` prices exactly those at
+     * zero (C-11) — so a dollar budget would silently never trigger for the
+     * configuration that most needs it. A count is exact for every model, and
+     * because per-review cost is already bounded on both sides (a 4 000-char
+     * digest in, 512 tokens out), `count x bound` is an honest ceiling.
+     */
+    reviewMaxPerSession: number;
+}
+export declare const DEFAULT_FAST_CONFIG: FastConfig;
+/**
+ * THE single gate for every fast-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those four 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".
+ *
+ * `provider` is CLAMPED TO `''` rather than rejected when it names something
+ * with no adapter. `''` means "inherit the main provider", which is the safe
+ * reading of a typo — and `resolveFastTier` reports `no_adapter` for the case a
+ * user really did configure a dead vendor as the MAIN one.
+ */
+export declare function clampFastConfig(raw: unknown): FastConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
     model: string;
     baseUrl: string | null;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Whether the terminal DRAWS the reasoning that came back
+     * (agent-activity-presentation §4.1).
+     *
+     * ADJACENT TO `thinkingLevel` AND DELIBERATELY NAMED DIFFERENTLY: that key is
+     * the effort the provider is asked to SPEND, this one is whether the transcript
+     * shows it. They are one word apart in the config file and must never be
+     * confused, which is why the flag is `--show-thinking` rather than the shorter
+     * `--thinking` the existing key already resembles.
+     */
+    showThinking: boolean;
+    /**
+     * Whether a RUNNING tool card draws a bounded tail of its live output
+     * (agent-activity-presentation-live §4.1).
+     *
+     * DEFAULT `true`, unlike `showThinking` next door (D-28). That key hides
+     * information by default because reasoning is noise most of the time; this one
+     * ADDS the information the requirement asks for, and its cost is bounded by
+     * construction -- eight rows per call, sixteen calls, whatever the command
+     * emits. It exists as a KILL SWITCH, not as an opt-in: "a build's output
+     * redraws the transcript" is exactly the kind of change a user on a slow SSH
+     * link may want off.
+     */
+    liveToolOutput: boolean;
     /**
      * Output token cap.
      *
@@ -300,8 +484,14 @@ export interface PersistedConfig {
     fullscreen: boolean;
     /** Replay a plain-text session summary after leaving the alternate screen. */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /** Entries kept in `ViewState`; older ones are dropped and counted (L1). */
+    transcriptRetain: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -322,7 +512,8 @@ export interface PersistedConfig {
     hints: boolean;
     /**
      * Enable SGR mouse reporting in full-screen mode so the wheel scrolls the
-     * region under the pointer (mouse-wheel-region-routing §5.7).
+     * transcript, whatever row the pointer is on (wheel-scrolls-transcript-only
+     * §4.1).
      *
      * A PLAIN BOOLEAN, not a `fullscreen`-style tri-state: there are no
      * heuristics for an explicit `true` to override (D-10).
@@ -342,6 +533,10 @@ export interface PersistedConfig {
     team: TeamConfig;
     /** Todo planning. The FIFTH nested object; scalars only (see TodoConfig). */
     todo: TodoConfig;
+    /** API retry. The SIXTH nested object; scalars only (see RetryConfig). */
+    retry: RetryConfig;
+    /** Fast model tier. The SEVENTH nested object; scalars only (see FastConfig). */
+    fast: FastConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -373,6 +568,28 @@ export interface CliConfig {
     model: string;
     baseUrl?: string;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Seeds `ViewState.thinkingVisible` on the first frame (§4.1 / P1-2).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`. `App` reads `cfg.*`,
+     * where `cfg` is a `CliConfig`; a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` — and never reach
+     * `initialViewState`. `--show-thinking` and `ARAGON_SHOW_THINKING` would parse
+     * and be discarded. Nothing would fail; the setting would simply do nothing.
+     */
+    showThinking: boolean;
+    /**
+     * Whether `AgentController` allocates the live-output store and binds
+     * `recordOutput` (agent-activity-presentation-live §4.1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason its
+     * neighbour records one comment up: the controller reads `config.*`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` -- and never reach
+     * the constructor. `--live-tool-output` and `ARAGON_LIVE_TOOL_OUTPUT` would
+     * parse and be discarded, with nothing failing.
+     */
+    liveToolOutput: boolean;
     /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
     theme: ThemeName;
@@ -390,8 +607,30 @@ export interface CliConfig {
     fullscreen?: boolean;
     /** Replay a plain-text summary on exit (full-screen only — see §4.4). */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /**
+     * Entries kept in `ViewState` (L1).
+     *
+     * Resolved to be `>= transcriptWindow`: retaining fewer entries than the
+     * window can scroll to would silently make part of the window unreachable.
+     */
+    transcriptRetain: number;
+    /**
+     * What the user actually asked `transcriptRetain` to be, present ONLY when
+     * that value had to be raised (§5.1).
+     *
+     * A setting ignored without a word is the one failure mode this feature is
+     * not allowed to add: the eco chip, `/perf` and the dropped-entry line all
+     * exist so that nothing it does happens unannounced, and a config key
+     * overwritten in silence would be the exception. `undefined` means nothing
+     * was overridden, which is every default session.
+     */
+    transcriptRetainRequested?: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -446,6 +685,30 @@ export interface CliConfig {
      * must call `setTodoConfig` as well as persisting (P1-2).
      */
     todo: TodoConfig;
+    /**
+     * Resolved API-retry settings (llm-api-retry-backoff §6.2).
+     *
+     * Unlike `team.enabled` / `todo.enabled` this decides NOTHING at construction
+     * time: the policy lives on the `ProviderRegistry` and `setRetryConfig()`
+     * replaces it live, so `/retry off` takes effect in the running session. That is
+     * why the controller has no `retryRegistered` twin of the two flags above.
+     */
+    retry: RetryConfig;
+    /**
+     * Resolved fast-tier settings (fast-model-tier §4.2).
+     *
+     * `enabled` here decides `fastRegistered` — whether `task`'s schema carries a
+     * `model` property at all — which happens once at construction and can never
+     * be undone (C-2). The live on/off switch `/fast` flips is a separate flag on
+     * `FastWiring`.
+     *
+     * THE OTHER NINE KEYS ARE READ LIVE, and that is not the same statement.
+     * `provider` / `model` / `baseUrl` feed `resolveFastTier`, which is re-run on
+     * every config mutation (§3.2 rule 8 / RV-3) because `''` INHERITS from
+     * `config.provider` / `config.baseUrl` and those are rewritten by `/model`,
+     * `/provider`, `/reload` and the settings screen.
+     */
+    fast: FastConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -6,7 +6,7 @@
  * invariant).
  */
 import { isAbsolute } from 'node:path';
-import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, } from '@aragon-agent/core';
+import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_RETRY_POLICY, MIN_MAX_OUTPUT_TOKENS, RETRY_LIMITS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 // ---------------------------------------------------------------------------
@@ -98,18 +98,52 @@ export const DEFAULT_IDLE_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS + IDLE_TIMEOUT_MA
  */
 export const PROMPT_HISTORY_CAP = 100;
 /**
- * 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
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export const MIN_TRANSCRIPT_WINDOW = 50;
-export const MAX_TRANSCRIPT_WINDOW = 2000;
+export const MAX_TRANSCRIPT_WINDOW = 20_000;
 export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export const MIN_TRANSCRIPT_RETAIN = 200;
+export const MAX_TRANSCRIPT_RETAIN = 20_000;
+export function clampTranscriptRetain(v, fallback) {
+    const n = coercePositiveInt(v, fallback);
+    return Math.min(MAX_TRANSCRIPT_RETAIN, Math.max(MIN_TRANSCRIPT_RETAIN, n));
+}
+// ---------------------------------------------------------------------------
+// Adaptive render governor (tui-render-performance L4 / R7)
+// ---------------------------------------------------------------------------
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+const RENDER_INTERVAL_RANGE = { min: 33, max: 1000 };
+export function clampMaxRenderInterval(v, fallback) {
+    return clampInt(v, fallback, RENDER_INTERVAL_RANGE);
+}
 // ---------------------------------------------------------------------------
 // Plan mode (plan-mode §4.4)
 //
@@ -179,6 +213,46 @@ function clampInt(v, fallback, range) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(range.max, Math.max(range.min, n));
 }
+/**
+ * `clampInt` for a key whose range legitimately includes ZERO.
+ *
+ * `clampInt` delegates to `coercePositiveInt`, which returns the FALLBACK for
+ * `n <= 0` — so a range whose floor is `0` cannot express `0` through it, and the
+ * value silently becomes the default. That trap is invisible at the call site and
+ * is what `retry.maxRetries` needs this helper for: `0` is that key's documented
+ * floor and its kill switch, and four documented controls send it
+ * (`/retry max 0`, `--retry-max 0`, `ARAGON_RETRY_MAX=0`,
+ * `aragon config set retry.maxRetries 0`). Through `clampInt` all four would set
+ * the MAXIMUM instead of the minimum, with no error anywhere.
+ *
+ * Own coercion: `Number.parseInt`, reject only non-finite and negative, then
+ * floor and clamp.
+ */
+function clampIntAllowingZero(v, fallback, range) {
+    if (v === null || v === undefined || v === '')
+        return clampToRange(fallback, range);
+    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return clampToRange(fallback, range);
+    return clampToRange(Math.floor(n), range);
+}
+/**
+ * `clampInt` for a key that is legitimately a FLOAT.
+ *
+ * `coercePositiveInt` floors, and `2.5` is a legitimate backoff factor — the same
+ * coercion trap `clampIntAllowingZero` above closes for `0`, one type over.
+ */
+function clampNumber(v, fallback, range) {
+    if (v === null || v === undefined || v === '')
+        return clampToRange(fallback, range);
+    const n = typeof v === 'number' ? v : Number.parseFloat(String(v));
+    if (!Number.isFinite(n))
+        return clampToRange(fallback, range);
+    return clampToRange(n, range);
+}
+function clampToRange(n, range) {
+    return Math.min(range.max, Math.max(range.min, n));
+}
 function stringArray(v, fallback) {
     if (!Array.isArray(v))
         return fallback;
@@ -346,12 +420,169 @@ export function clampTodoConfig(raw) {
         followThrough: followMode(src.followThrough, DEFAULT_TODO_CONFIG.followThrough),
     };
 }
+export const DEFAULT_RETRY_CONFIG = {
+    enabled: true,
+    maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
+    initialDelayMs: DEFAULT_RETRY_POLICY.initialDelayMs,
+    maxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,
+    multiplier: DEFAULT_RETRY_POLICY.multiplier,
+    jitter: DEFAULT_RETRY_POLICY.jitter,
+    respectRetryAfter: DEFAULT_RETRY_POLICY.respectRetryAfter,
+    maxElapsedMs: DEFAULT_RETRY_POLICY.maxElapsedMs,
+    onPartialStream: DEFAULT_RETRY_POLICY.onPartialStream,
+};
+/**
+ * `hardMaxRetries` re-exported rather than re-spelled, for the reason
+ * `HARD_MAX_SUBAGENTS` records: the ceiling is enforced in TWO places — here on
+ * the config value, and again by `normalizePolicy` inside the engine — and two
+ * copies of the same 20 is exactly how a hand-edited `config.json` ends up able
+ * to raise a ceiling the mechanism fixed.
+ */
+export const HARD_MAX_RETRIES = RETRY_LIMITS.hardMaxRetries;
+/** FLOOR 0 — and `clampIntAllowingZero` is what makes that reachable. */
+const RETRY_MAX_RANGE = { min: 0, max: HARD_MAX_RETRIES };
+const RETRY_INITIAL_DELAY_RANGE = { min: 100, max: 30_000 };
+const RETRY_MAX_DELAY_RANGE = { min: 1000, max: RETRY_LIMITS.absoluteMaxDelayMs };
+const RETRY_MULTIPLIER_RANGE = { min: 1, max: 5 };
+const RETRY_ELAPSED_RANGE = { min: 10_000, max: 1_800_000 };
+/**
+ * THE single gate for every retry-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those 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".
+ *
+ * Three invariants live inside the gate:
+ *
+ *  - `maxDelayMs = max(maxDelayMs, initialDelayMs)` — a ceiling under the floor
+ *    makes the ladder a flat line and the countdown a lie.
+ *  - `multiplier` goes through `clampNumber`, not `clampInt`: `2.5` is a
+ *    legitimate factor and `coercePositiveInt` would floor it to 2.
+ *  - `maxRetries` goes through `clampIntAllowingZero`. THIS IS THE ONE THAT SHIPS
+ *    BROKEN WITHOUT IT (R-16): `clampInt` returns the fallback for `n <= 0`, so
+ *    `clampRetryConfig({ maxRetries: 0 })` would yield 10 — the maximum instead
+ *    of the minimum, silently, for the key that gates the whole feature.
+ *
+ * `maxElapsedMs` intentionally keeps plain `clampInt`: its floor is 10 000, so it
+ * has no `0` to express.
+ */
+export function clampRetryConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const initialDelayMs = clampInt(src.initialDelayMs, DEFAULT_RETRY_CONFIG.initialDelayMs, RETRY_INITIAL_DELAY_RANGE);
+    const maxDelayMs = Math.max(initialDelayMs, clampInt(src.maxDelayMs, DEFAULT_RETRY_CONFIG.maxDelayMs, RETRY_MAX_DELAY_RANGE));
+    return {
+        enabled: bool(src.enabled, DEFAULT_RETRY_CONFIG.enabled),
+        maxRetries: clampIntAllowingZero(src.maxRetries, DEFAULT_RETRY_CONFIG.maxRetries, RETRY_MAX_RANGE),
+        initialDelayMs,
+        maxDelayMs,
+        multiplier: clampNumber(src.multiplier, DEFAULT_RETRY_CONFIG.multiplier, RETRY_MULTIPLIER_RANGE),
+        jitter: bool(src.jitter, DEFAULT_RETRY_CONFIG.jitter),
+        respectRetryAfter: bool(src.respectRetryAfter, DEFAULT_RETRY_CONFIG.respectRetryAfter),
+        maxElapsedMs: clampInt(src.maxElapsedMs, DEFAULT_RETRY_CONFIG.maxElapsedMs, RETRY_ELAPSED_RANGE),
+        onPartialStream: bool(src.onPartialStream, DEFAULT_RETRY_CONFIG.onPartialStream),
+    };
+}
+/**
+ * `RetryConfig` (user intent) -> `RetryPolicy` (engine policy), or `null` for
+ * "the user said no".
+ *
+ * `null` rather than a policy with `maxRetries: 0` because `ProviderRegistry`
+ * short-circuits on a null policy and returns the adapter's iterator DIRECTLY —
+ * an opted-out session is then allocation-identical to a pre-feature build.
+ *
+ * TOTAL, AND IT ACCEPTS A MISSING SECTION. `loadConfig` always supplies one, but
+ * a `CliConfig` built by hand — every controller test in this package does exactly
+ * that, and so would an embedder — legitimately omits it, and a `TypeError` from a
+ * pure translation function is the wrong way to find out. Routing through
+ * `clampRetryConfig` also means an out-of-range hand-built value can never reach
+ * the engine, which is the same "one gate, both directions" rule every other
+ * section in this file follows.
+ */
+export function toRetryPolicy(cfg) {
+    const safe = clampRetryConfig(cfg);
+    if (!safe.enabled || safe.maxRetries <= 0)
+        return null;
+    return {
+        maxRetries: safe.maxRetries,
+        initialDelayMs: safe.initialDelayMs,
+        maxDelayMs: safe.maxDelayMs,
+        multiplier: safe.multiplier,
+        jitter: safe.jitter,
+        respectRetryAfter: safe.respectRetryAfter,
+        maxElapsedMs: safe.maxElapsedMs,
+        onPartialStream: safe.onPartialStream,
+    };
+}
+export const DEFAULT_FAST_CONFIG = {
+    // R-d, and the one default in this file that is a REQUIREMENT rather than a
+    // judgement: a feature that silently spends money on a second provider is not
+    // a default (D-3).
+    enabled: false,
+    provider: '',
+    model: '',
+    baseUrl: '',
+    thinkingLevel: 'off',
+    delegate: true,
+    review: true,
+    reviewEveryTurns: 5,
+    reviewContextTurns: 3,
+    reviewMaxChars: 280,
+    // 40 is roughly 200 reviewed turns at the default cadence: comfortably past a
+    // full working session, short of a runaway (D-H2).
+    reviewMaxPerSession: 40,
+};
+const REVIEW_EVERY_RANGE = { min: 1, max: 50 };
+const REVIEW_CONTEXT_RANGE = { min: 1, max: 10 };
+const REVIEW_CHARS_RANGE = { min: 80, max: 600 };
+/** No "unlimited" sentinel: a magic `0` reads as "disabled" to the next person
+ *  who meets it, and 500 is already past any session a human sits through. */
+const REVIEW_SESSION_RANGE = { min: 1, max: 500 };
+/** Trim a string field, falling back when the value is not a string at all. */
+function text(v, fallback) {
+    return typeof v === 'string' ? v.trim() : fallback;
+}
+/**
+ * THE single gate for every fast-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those four 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".
+ *
+ * `provider` is CLAMPED TO `''` rather than rejected when it names something
+ * with no adapter. `''` means "inherit the main provider", which is the safe
+ * reading of a typo — and `resolveFastTier` reports `no_adapter` for the case a
+ * user really did configure a dead vendor as the MAIN one.
+ */
+export function clampFastConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const provider = text(src.provider, DEFAULT_FAST_CONFIG.provider);
+    return {
+        enabled: bool(src.enabled, DEFAULT_FAST_CONFIG.enabled),
+        provider: provider.length === 0 || isAdapterProvider(provider) ? provider : '',
+        model: text(src.model, DEFAULT_FAST_CONFIG.model),
+        baseUrl: text(src.baseUrl, DEFAULT_FAST_CONFIG.baseUrl),
+        thinkingLevel: clampThinkingLevel(src.thinkingLevel, DEFAULT_FAST_CONFIG.thinkingLevel),
+        delegate: bool(src.delegate, DEFAULT_FAST_CONFIG.delegate),
+        review: bool(src.review, DEFAULT_FAST_CONFIG.review),
+        reviewEveryTurns: clampInt(src.reviewEveryTurns, DEFAULT_FAST_CONFIG.reviewEveryTurns, REVIEW_EVERY_RANGE),
+        reviewContextTurns: clampInt(src.reviewContextTurns, DEFAULT_FAST_CONFIG.reviewContextTurns, REVIEW_CONTEXT_RANGE),
+        reviewMaxChars: clampInt(src.reviewMaxChars, DEFAULT_FAST_CONFIG.reviewMaxChars, REVIEW_CHARS_RANGE),
+        reviewMaxPerSession: clampInt(src.reviewMaxPerSession, DEFAULT_FAST_CONFIG.reviewMaxPerSession, REVIEW_SESSION_RANGE),
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
     model: DEFAULT_MODEL,
     baseUrl: null,
     thinkingLevel: 'off',
+    // Off by default — the product default this whole round exists to establish
+    // (D-1). One config key restores the old behaviour permanently.
+    showThinking: false,
+    // ON by default (D-28), and the OPPOSITE of the key above it on purpose: this
+    // one shows work that is otherwise invisible for the whole duration of the
+    // most expensive thing the agent does.
+    liveToolOutput: true,
     // 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,
@@ -360,6 +591,9 @@ export const DEFAULT_CONFIG = {
     fullscreen: true,
     exitTranscript: true,
     transcriptWindow: DEFAULT_TRANSCRIPT_WINDOW,
+    transcriptRetain: DEFAULT_TRANSCRIPT_RETAIN,
+    renderGovernor: DEFAULT_RENDER_GOVERNOR,
+    maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
@@ -378,6 +612,15 @@ export const DEFAULT_CONFIG = {
     // `todo` key at all, so this line is as required as the two merges in
     // `store.ts` (P0-1).
     todo: DEFAULT_TODO_CONFIG,
+    // Same requirement one section later: without this line a user with no `retry`
+    // key resolves `config.retry` to `undefined` and `toRetryPolicy` throws.
+    retry: DEFAULT_RETRY_CONFIG,
+    // And one section later again: the load path's first spread is what supplies
+    // `fast` to a user whose `config.json` predates this feature, which is every
+    // existing user. Without it `config.fast.enabled` reads `undefined`, which is
+    // falsy and so LOOKS correct — right up until `/fast on` writes a section that
+    // has no other keys in it (P0-1's shape, one feature later).
+    fast: DEFAULT_FAST_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake