@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/config/schema.js

@@ -1,1377 +0,0 @@
-/**
- * Config schema — the persisted config-file shape, the in-memory effective
- * config, sane defaults, and small validation/masking helpers.
- *
- * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
- * invariant).
- */
-import { isAbsolute } from 'node:path';
-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';
-import { DEFAULT_GOVERNANCE_CONFIG } from './governance-config.js';
-// Governance mode (governance-mode 11.1): defined in its own file so this one does not grow.
-export { clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, } from './governance-config.js';
-// ---------------------------------------------------------------------------
-// Provider set — only the adapter-backed providers are usable at run time (R5).
-// ---------------------------------------------------------------------------
-/**
- * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
- * registers only three adapters. Running a model whose provider has no adapter
- * throws `Unknown LLM provider`, so the CLI only ever offers these three.
- */
-export const ADAPTER_PROVIDERS = ['anthropic', 'openai', 'google'];
-export function isAdapterProvider(id) {
-    return ADAPTER_PROVIDERS.includes(id);
-}
-// ---------------------------------------------------------------------------
-// Thinking levels
-// ---------------------------------------------------------------------------
-export const THINKING_LEVELS = [
-    'off',
-    'minimal',
-    'low',
-    'medium',
-    'high',
-    'xhigh',
-];
-export function isThinkingLevel(v) {
-    return typeof v === 'string' && THINKING_LEVELS.includes(v);
-}
-export function clampThinkingLevel(v, fallback) {
-    return isThinkingLevel(v) ? v : fallback;
-}
-// ---------------------------------------------------------------------------
-// Theme
-// ---------------------------------------------------------------------------
-export const THEME_NAMES = ['auto', 'warm', 'cool', 'light'];
-/** The v0.3.0 name for what is now `cool`. Accepted forever as an alias. */
-export const LEGACY_DARK_THEME = 'dark';
-export function isThemeName(v) {
-    return typeof v === 'string' && THEME_NAMES.includes(v);
-}
-/**
- * THE single gate for every theme write (spec §4.5 / R-4).
- *
- * All three write paths funnel through here — config resolution (`load.ts`),
- * `aragon config set theme`, and the `/theme` slash command — which is why the
- * `dark -> cool` migration lives here and nowhere else. Putting it in a
- * `load.ts` normalization step instead would migrate what users *read* but not
- * what they *write*, producing the worst kind of bug: "the flag works but the
- * setting won't stick."
- *
- * An unrecognized value still falls back silently (plus a warn toast at the call
- * site). Turning that into a hard exit would be an unannounced breaking change
- * and would not match `clampThinkingLevel` / `clampTranscriptWindow`.
- */
-export function clampTheme(v, fallback) {
-    if (v === LEGACY_DARK_THEME)
-        return 'cool';
-    return isThemeName(v) ? v : fallback;
-}
-// ---------------------------------------------------------------------------
-// Density / hints (v0.4.0)
-// ---------------------------------------------------------------------------
-export const SCROLL_MODES = ['native', 'app'];
-export const DEFAULT_SCROLL_MODE = 'native';
-export function clampScrollMode(v, fallback) {
-    if (typeof v !== 'string')
-        return fallback;
-    const normalized = v.trim().toLowerCase();
-    return normalized === 'native' || normalized === 'app' ? normalized : fallback;
-}
-export const DENSITY_MODES = ['comfortable', 'compact'];
-export function clampDensity(v, fallback) {
-    return v === 'comfortable' || v === 'compact' ? v : fallback;
-}
-/**
- * Submissions after which the composer hint collapses to `? help` (§4.6).
- * Only the IDLE hint fades; the running hint carries the abort key and is
- * always shown in full.
- */
-export const HINT_FADE_AFTER = 8;
-// ---------------------------------------------------------------------------
-// Defaults
-// ---------------------------------------------------------------------------
-export const CONFIG_VERSION = 1;
-export const DEFAULT_MODEL = 'claude-sonnet-4-5-20250929';
-/** Per-tool executor ceiling (§3.8). Headroom for typical installs/builds. */
-export const DEFAULT_TOOL_TIMEOUT_MS = 180_000;
-/** Extra margin so idle timeout is strictly greater than the tool ceiling. */
-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 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;
-/**
- * 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 = 1000;
-export const MIN_TRANSCRIPT_WINDOW = 50;
-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));
-}
-// ---------------------------------------------------------------------------
-// Context window override (context-usage-gauge-accuracy §3.6 / W5)
-// ---------------------------------------------------------------------------
-/**
- * Bounds for a hand-supplied context window.
- *
- * The floor is roughly the smallest window any current model ships with; the
- * ceiling is well above the largest, and both exist to keep a typo (a missing
- * or an extra zero) from producing a gauge that is permanently red or
- * permanently flat.
- */
-export const MIN_CONTEXT_WINDOW = 8_000;
-export const MAX_CONTEXT_WINDOW = 5_000_000;
-/**
- * THE single gate for every `contextWindow` read AND write.
- *
- * TRI-STATE, AND `null` MUST PASS STRAIGHT THROUGH (RV-12). `null` means AUTO -
- * take the model table's number, or the 128k placeholder. Clamping it into
- * `[8000, ...]` yields 8000, which removes "auto" from the config permanently
- * and presents to the user as an 8k denominator with a permanently red bar and
- * no visible source. `maxTokens` above is the existing tri-state precedent and
- * this deliberately copies its shape rather than inventing a second convention.
- */
-export function clampContextWindow(v, fallback) {
-    if (v === null)
-        return null;
-    if (v === undefined || v === '')
-        return fallback;
-    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
-    if (!Number.isFinite(n) || n <= 0)
-        return fallback;
-    return Math.min(MAX_CONTEXT_WINDOW, Math.max(MIN_CONTEXT_WINDOW, Math.floor(n)));
-}
-/**
- * Parse text typed into the settings screen or the profile editor for a
- * context window (profile-context-window §5.3).
- *
- * THE MIRROR OF `parseMaxTokensInput` BELOW, down to the tri-state shape: it
- * distinguishes AUTO from "the user typed nonsense", which `clampContextWindow`
- * cannot - a typo must change NOTHING rather than silently discard the number
- * the user meant to set. `''` / `'auto'` / `'0'` are AUTO (`isAutoToken`);
- * a digit run is clamped through THE single gate; anything else is invalid.
- */
-export function parseContextWindowInput(raw) {
-    const trimmed = String(raw ?? '').trim();
-    if (isAutoToken(trimmed))
-        return { kind: 'auto' };
-    if (!/^\d+$/.test(trimmed))
-        return { kind: 'invalid' };
-    const value = clampContextWindow(trimmed, null);
-    if (value === null)
-        return { kind: 'invalid' };
-    return { kind: 'value', value, clamped: value !== Number.parseInt(trimmed, 10) };
-}
-/**
- * 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);
-}
-// ---------------------------------------------------------------------------
-// Frame diffing (tui-input-flicker-fix §5.1)
-//
-// TWO TROUBLESHOOTING SWITCHES, in the same class as `historyEnabled`: neither
-// appears on the settings overlay, because a user who needs them is debugging a
-// terminal, not adjusting a preference.
-// ---------------------------------------------------------------------------
-/**
- * Repaint only the frame lines that changed (full-screen only).
- *
- * ON by default, and `--no-diff-render` restores today's byte stream EXACTLY —
- * the interposer is not constructed at all, so a regression on an exotic
- * terminal is one flag away from being neutralised (§3.5 rung 2).
- */
-export const DEFAULT_DIFF_RENDER = true;
-/**
- * Wrap each repaint batch in DEC 2026 begin/end synchronized update.
- *
- * ON by default with NO capability probe (§3.3): terminals that do not implement
- * mode 2026 parse the CSI sequence, find an unknown private mode and discard it,
- * so a false positive costs nothing — and a false negative costs nothing either,
- * because the frame differ already removes the flicker on its own.
- */
-export const DEFAULT_SYNC_OUTPUT = true;
-// ---------------------------------------------------------------------------
-// Selection + scroll follow (tui-selection-and-scroll-follow §6.1)
-// ---------------------------------------------------------------------------
-/**
- * Drag-select + copy, and — because §4.4.1 gates `\x1b[?1002h` on exactly this
- * value — whether motion reporting is requested from the terminal at all.
- *
- * That gating is what makes `false` BYTE-IDENTICAL to a pre-feature session
- * rather than merely equivalent (AC-8 / D-15). Ignored when `mouse` is false,
- * since there is no capture to select with.
- */
-export const DEFAULT_MOUSE_SELECT = true;
-/**
- * Idle delay before a paused viewport returns to the newest line, in ms.
- *
- * Five seconds is chosen to be LONGER than a glance and SHORTER than a read.
- * `0` disables auto-resume entirely, and it is a real value rather than a
- * sentinel-shaped default: `shouldArmResume` refuses on it before any timer is
- * created (AC-9), so the revert for Rule B is one config key.
- *
- * NO CLI FLAG (§6.1). It is a comfort preference, set once
- * (`aragon config set scrollResumeMs 8000`) and then forgotten — the same
- * argument this file already makes for `historyEnabled`. Adding a flag for every
- * scalar is how a CLI ends up with sixty of them.
- */
-export const DEFAULT_SCROLL_RESUME_MS = 5000;
-const SCROLL_RESUME_RANGE = { min: 0, max: 120_000 };
-/**
- * `clampIntAllowingZero`, and the choice is load-bearing: `clampInt` delegates to
- * `coercePositiveInt`, which returns the FALLBACK for `n <= 0` — so `0` would
- * silently become 5000 and the documented off switch would not be an off switch.
- * Exactly the trap `retry.maxRetries` needed this helper for.
- */
-export function clampScrollResumeMs(v, fallback) {
-    return clampIntAllowingZero(v, fallback, SCROLL_RESUME_RANGE);
-}
-// ---------------------------------------------------------------------------
-// Plan mode (plan-mode §4.4)
-//
-// THREE FLAT KEYS, not a nested `planMode` object. `store.ts` documents that its
-// nested-object merge is hand-written and capped at one level; three scalars do
-// not justify a second `clampXConfig` gate plus two more merge sites, and flat
-// keys mean `store.ts` needs ZERO changes.
-//
-// ONE OF THOSE KEYS IS GONE: `planModeMaxAskRounds` capped `ask_user` at four
-// rounds per turn. There is no cap any more, so there is no number to store, no
-// range to clamp and nothing to configure. It is retired through
-// `RETIRED_CONFIG_KEYS` below rather than defaulted to a large number — a
-// ninety-nine in the config file is the same second source of truth as a four.
-// ---------------------------------------------------------------------------
-/**
- * Ceiling on ONE human wait, in ms. Thirty minutes is far outside "the user
- * went to get coffee", but a ceiling has to exist: an unattended terminal must
- * not wedge a CI job or a stale ssh session forever.
- *
- * THIS IS NOT A ROUND LIMIT and the distinction matters. It bounds a single wait
- * (liveness); it says nothing about how many times the model may ask.
- */
-export const DEFAULT_PLAN_HUMAN_TIMEOUT_MS = 1_800_000;
-const HUMAN_TIMEOUT_RANGE = { min: 60_000, max: 7_200_000 };
-export function clampHumanTimeout(v, fallback) {
-    return clampInt(v, fallback, HUMAN_TIMEOUT_RANGE);
-}
-export const SKILLS_INTEGRITY_MODES = ['off', 'warn', 'strict'];
-export function clampSkillsIntegrity(v, fallback) {
-    return typeof v === 'string' && SKILLS_INTEGRITY_MODES.includes(v)
-        ? v
-        : fallback;
-}
-export const SKILLS_TOOL_POLICY_MODES = ['off', 'warn', 'enforce'];
-export function isSkillsToolPolicyMode(v) {
-    return typeof v === 'string' && SKILLS_TOOL_POLICY_MODES.includes(v);
-}
-export function clampSkillsToolPolicy(v, fallback) {
-    return isSkillsToolPolicyMode(v) ? v : fallback;
-}
-export const DEFAULT_ALLOWED_SKILL_HOSTS = [
-    'github.com',
-    'raw.githubusercontent.com',
-    'codeload.github.com',
-    'gitlab.com',
-    'objects.githubusercontent.com',
-];
-export const DEFAULT_SKILLS_CONFIG = {
-    enabled: true,
-    disabled: [],
-    requireApproval: true,
-    allowedHosts: DEFAULT_ALLOWED_SKILL_HOSTS,
-    projectDirs: ['.aragon/skills', '.claude/skills'],
-    trustedProjectDirs: [],
-    catalogMaxBytes: 6000,
-    bodyMaxBytes: 30_000,
-    integrity: 'warn',
-    usageTracking: true,
-    toolPolicy: 'enforce',
-    // ON by default: the capability this key controls is the feature's whole point,
-    // and it costs zero model calls (local matching over in-memory records).
-    triage: true,
-};
-const CATALOG_BYTES_RANGE = { min: 500, max: 40_000 };
-/**
- * Upper bound is 50 000, NOT the 90 000 an earlier draft used.
- * `SKILL_RESULT_MAX_BYTES` is 60 000 and must also fit the file list and the
- * head/tail guidance; 50 000 leaves that margin. A 90 000-CHARACTER body is
- * 270 000 bytes of CJK, which `ToolExecutor` would chop mid-tag (D19).
- */
-const BODY_BYTES_RANGE = { min: 1000, max: 50_000 };
-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;
-    const out = v.filter((item) => typeof item === 'string' && item.trim().length > 0);
-    return out.map((s) => s.trim());
-}
-function bool(v, fallback) {
-    return typeof v === 'boolean' ? v : fallback;
-}
-/**
- * THE single gate for every skills-config read AND write (§10.3.1).
- *
- * Shared by `loadConfig()`, `loadPersistedConfig()` and `updatePersistedConfig()`
- * on purpose: hardening only the read path would leave a corrupt value on disk
- * that silently reverts to a default on every launch — the failure looks like
- * "my setting won't stick" with no error anywhere.
- */
-export function clampSkillsConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    return {
-        enabled: bool(src.enabled, DEFAULT_SKILLS_CONFIG.enabled),
-        disabled: stringArray(src.disabled, DEFAULT_SKILLS_CONFIG.disabled),
-        requireApproval: bool(src.requireApproval, DEFAULT_SKILLS_CONFIG.requireApproval),
-        allowedHosts: stringArray(src.allowedHosts, DEFAULT_SKILLS_CONFIG.allowedHosts),
-        projectDirs: stringArray(src.projectDirs, DEFAULT_SKILLS_CONFIG.projectDirs),
-        trustedProjectDirs: stringArray(src.trustedProjectDirs, DEFAULT_SKILLS_CONFIG.trustedProjectDirs),
-        catalogMaxBytes: clampInt(src.catalogMaxBytes, DEFAULT_SKILLS_CONFIG.catalogMaxBytes, CATALOG_BYTES_RANGE),
-        bodyMaxBytes: clampInt(src.bodyMaxBytes, DEFAULT_SKILLS_CONFIG.bodyMaxBytes, BODY_BYTES_RANGE),
-        integrity: clampSkillsIntegrity(src.integrity, DEFAULT_SKILLS_CONFIG.integrity),
-        usageTracking: bool(src.usageTracking, DEFAULT_SKILLS_CONFIG.usageTracking),
-        toolPolicy: clampSkillsToolPolicy(src.toolPolicy, DEFAULT_SKILLS_CONFIG.toolPolicy),
-        triage: bool(src.triage, DEFAULT_SKILLS_CONFIG.triage),
-    };
-}
-export const DEFAULT_SKILLS_RUNTIME = { forcedSkills: [], approveAll: false };
-const DEFAULT_MAX_LOG_FILE_BYTES = 5 * 1024 * 1024;
-const LOG_FILE_BYTES_RANGE = { min: 64 * 1024, max: 256 * 1024 * 1024 };
-const LOG_MAX_FILES_RANGE = { min: 1, max: 200 };
-const LOG_PREVIEW_CHARS_RANGE = { min: 0, max: 8192 };
-export const DEFAULT_LOG_CONFIG = {
-    level: 'info',
-    toFile: true,
-    dir: '',
-    maxFileBytes: DEFAULT_MAX_LOG_FILE_BYTES,
-    maxFiles: 10,
-    redactSecrets: true,
-    previewChars: 512,
-};
-/**
- * Coerce a log directory. Anything relative is discarded (falling back to
- * `<home>/logs`) rather than resolved: a relative path would silently mean a
- * different directory for every working directory the CLI is launched from, and
- * `debug`-level files carry prompt text (R-13).
- */
-function logDir(v, fallback) {
-    if (typeof v !== 'string')
-        return fallback;
-    const trimmed = v.trim();
-    if (trimmed.length === 0)
-        return '';
-    return isAbsolute(trimmed) ? trimmed : fallback;
-}
-/**
- * THE single gate for every log-config read AND write, exactly like
- * `clampSkillsConfig`: hardening only the read path leaves a bad value on disk
- * that reverts on every launch, which presents as "my setting won't stick".
- *
- * `previewChars` uses its own coercion because `coercePositiveInt` rejects `0`,
- * and `0` is a legitimate value here — it means "record that content existed,
- * but none of it".
- */
-export function clampLogConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    const preview = typeof src.previewChars === 'number' || typeof src.previewChars === 'string'
-        ? Number.parseInt(String(src.previewChars), 10)
-        : Number.NaN;
-    return {
-        level: clampLogLevel(src.level, DEFAULT_LOG_CONFIG.level),
-        toFile: bool(src.toFile, DEFAULT_LOG_CONFIG.toFile),
-        dir: logDir(src.dir, DEFAULT_LOG_CONFIG.dir),
-        maxFileBytes: clampInt(src.maxFileBytes, DEFAULT_LOG_CONFIG.maxFileBytes, LOG_FILE_BYTES_RANGE),
-        maxFiles: clampInt(src.maxFiles, DEFAULT_LOG_CONFIG.maxFiles, LOG_MAX_FILES_RANGE),
-        redactSecrets: bool(src.redactSecrets, DEFAULT_LOG_CONFIG.redactSecrets),
-        previewChars: Number.isFinite(preview)
-            ? Math.min(LOG_PREVIEW_CHARS_RANGE.max, Math.max(LOG_PREVIEW_CHARS_RANGE.min, preview))
-            : 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,
-    // 8 IS THE DEFAULT, 10 IS THE CEILING, and they are not the same number
-    // (subagent-fanout D-1 / D-2). `maxConcurrent` moves WITH `maxSubagents`
-    // because a wider population behind a 3-wide pool shows the user nothing:
-    // children 4..8 simply queue (`team-bus.test.ts` records the queued phase).
-    maxSubagents: 8,
-    maxConcurrent: 8,
-    // 0 = NO LIMIT. Subagents run under the same regime as the lead: no
-    // wall clock, no turn cap; only the idle watchdog and the user's Esc.
-    subagentTimeoutMs: 0,
-    dispatchTimeoutMs: 0,
-    maxTurnsPerSubagent: 0,
-    // The dispatch supervisor, default ON (team-overseer): ceilings become
-    // inspections; the fast-tier supervisor decides what to do.
-    overseer: true,
-    // 0 = the structural cadence default (300 s). See the field docstring.
-    overseerIntervalMs: 0,
-    // The parity default: children run the lead's own model until the user
-    // says otherwise (AC-1 - an upgraded config behaves exactly as before).
-    model: 'main',
-    modelProfileId: null,
-};
-const SUBAGENTS_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
-const CONCURRENT_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
-// `min: 0` is the documented OFF SWITCH for each bound, so these MUST use
-// `clampIntAllowingZero`: plain `clampInt` folds `0` back to the fallback
-// ("my setting won't stick"), the exact trap `scrollResumeMs` records above.
-const SUBAGENT_TIMEOUT_RANGE = { min: 0, max: 1_800_000 };
-const DISPATCH_TIMEOUT_RANGE = { min: 0, max: 3_600_000 };
-const OVERSEER_INTERVAL_RANGE = { min: 0, max: 3_600_000 };
-const TURNS_RANGE = { min: 0, 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: clampIntAllowingZero(src.subagentTimeoutMs, DEFAULT_TEAM_CONFIG.subagentTimeoutMs, SUBAGENT_TIMEOUT_RANGE),
-        dispatchTimeoutMs: clampIntAllowingZero(src.dispatchTimeoutMs, DEFAULT_TEAM_CONFIG.dispatchTimeoutMs, DISPATCH_TIMEOUT_RANGE),
-        maxTurnsPerSubagent: clampIntAllowingZero(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
-        overseer: bool(src.overseer, DEFAULT_TEAM_CONFIG.overseer),
-        overseerIntervalMs: clampIntAllowingZero(src.overseerIntervalMs, DEFAULT_TEAM_CONFIG.overseerIntervalMs, OVERSEER_INTERVAL_RANGE),
-        // typo-changes-nothing, the discipline every enum clamp here follows: a
-        // hand-edited `model: 'fats'` resolves to 'main' (the parity default)
-        // rather than invalidating the file or refusing to launch. A bad
-        // `modelProfileId` (wrong type, or over the 128-codepoint budget
-        // `model-profiles.ts::validText` defines) is nulled the same way;
-        // reference EXISTENCE stays a resolution-time concern (D-4).
-        model: src.model === 'fast' || src.model === 'profile' ? src.model : 'main',
-        modelProfileId: typeof src.modelProfileId === 'string' && src.modelProfileId.length > 0
-            && [...src.modelProfileId].length <= 128
-            ? src.modelProfileId
-            : null,
-        // TRANSPARENT, and only ever `true` (subagent-fanout D-3 / R-6). The flag is
-        // not a setting: it is the one-shot marker the migration leaves behind, so a
-        // clamp that dropped it would re-migrate the user on every launch. Written
-        // as a spread rather than `=== true ? true : undefined` so the key stays
-        // ABSENT (not `undefined`) in the clamped result - `toEqual(DEFAULT_TEAM_CONFIG)`
-        // and the on-disk shape both depend on that.
-        ...(src.fanoutMigrated === true ? { fanoutMigrated: true } : {}),
-    };
-}
-/**
- * The team ceilings cli <= 0.6.16 (7a6bf5630) persisted as its OWN defaults:
- * every user who touched team mode back then still carries this exact triple
- * in config.json, because `resolveTeamConfig` merges file values verbatim and
- * no migration ever rewrote them. They are the kill ceilings behind F-8's
- * "first block all failed" dispatches, so loading rewrites them to 0 (= no
- * ceiling, the shipped default since 2ff15a9c3).
- *
- * EXACT-EQUALITY ONLY: a value that differs was a deliberate user choice and
- * survives untouched. The price of that test is that a user who hand-types
- * 300000 today is migrated to 0 too - the accepted trade, and the safe
- * direction (no ceiling, not a cliff).
- */
-export const LEGACY_TEAM_CEILING_DEFAULTS = {
-    subagentTimeoutMs: 300_000,
-    dispatchTimeoutMs: 900_000,
-    maxTurnsPerSubagent: 24,
-};
-/**
- * The `{ key: 0 }` patch for legacy-default-equal ceilings, or `null` when
- * nothing matches. Pure on purpose: `loadConfig` decides WHERE the patch is
- * applied and persisted; this function only answers WHICH keys match, so the
- * equality test lives beside the constants it reads.
- */
-export function legacyTeamCeilingPatch(raw) {
-    if (!raw || typeof raw !== 'object')
-        return null;
-    const src = raw;
-    const patch = {};
-    let matched = false;
-    for (const key of Object.keys(LEGACY_TEAM_CEILING_DEFAULTS)) {
-        if (src[key] === LEGACY_TEAM_CEILING_DEFAULTS[key]) {
-            patch[key] = 0;
-            matched = true;
-        }
-    }
-    return matched ? patch : null;
-}
-/**
- * The fan-out defaults cli <= 0.6.x persisted as its OWN defaults
- * (subagent-fanout F-2 / R-1).
- *
- * THE SAME TRAP AS THE CEILINGS ABOVE, ONE SECTION OVER. `mergePersistedConfig`
- * writes the WHOLE `team` section on every save, so a user who has ever touched
- * any setting carries this exact pair in `config.json` - changing
- * `DEFAULT_TEAM_CONFIG` alone would never reach them, and they would keep
- * seeing "only 3 subagents at once" for ever.
- */
-export const LEGACY_TEAM_FANOUT_DEFAULTS = {
-    maxSubagents: 5,
-    maxConcurrent: 3,
-};
-/**
- * The `{ maxSubagents, maxConcurrent, fanoutMigrated }` patch for the legacy
- * default pair, or `null` when nothing matches (subagent-fanout D-3).
- *
- * EXACT-EQUALITY ONLY, the rule `legacyTeamCeilingPatch` records: a value that
- * differs was a deliberate user choice and survives untouched. Two differences
- * from that function, both deliberate:
- *
- *  - `fanoutMigrated: true` short-circuits to `null`. That is what makes "the
- *    user changed their mind and went back to 5/3" stick: without it the next
- *    launch would migrate them again, every launch, for ever.
- *  - `maxConcurrent` is allowed to be ABSENT as well as 3, because a
- *    hand-written section may name only one key and a half-written pair is
- *    still the legacy intent, not a user decision.
- *
- * Pure on purpose: `loadConfig` decides WHERE the patch is applied and
- * persisted; this function only answers WHICH keys match, so the equality test
- * lives beside the constants it reads.
- */
-export function legacyTeamFanoutPatch(raw) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return null;
-    const src = raw;
-    if (src.fanoutMigrated === true)
-        return null;
-    if (src.maxSubagents !== LEGACY_TEAM_FANOUT_DEFAULTS.maxSubagents)
-        return null;
-    if (src.maxConcurrent !== undefined
-        && src.maxConcurrent !== LEGACY_TEAM_FANOUT_DEFAULTS.maxConcurrent)
-        return null;
-    return {
-        maxSubagents: DEFAULT_TEAM_CONFIG.maxSubagents,
-        maxConcurrent: DEFAULT_TEAM_CONFIG.maxConcurrent,
-        fanoutMigrated: true,
-    };
-}
-export const DEFAULT_TODO_CONFIG = {
-    enabled: true,
-    panel: true,
-    followThrough: 'notify',
-    acceptance: true,
-};
-/**
- * There is no enum helper in this file, so this follows the `isThinkingLevel`
- * shape already here rather than inventing a second idiom.
- */
-const FOLLOW_THROUGH_MODES = ['notify', 'auto', 'off'];
-function followMode(value, fallback) {
-    return typeof value === 'string' && FOLLOW_THROUGH_MODES.includes(value)
-        ? value
-        : fallback;
-}
-/**
- * THE single gate for every todo-config read AND write, mirroring
- * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` 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".
- */
-export function clampTodoConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    return {
-        enabled: bool(src.enabled, DEFAULT_TODO_CONFIG.enabled),
-        panel: bool(src.panel, DEFAULT_TODO_CONFIG.panel),
-        // CLAMPED TO THE DEFAULT, NEVER REJECTED — the discipline every other key in
-        // this file follows, and the trade round 1 already made for `--thinking`.
-        // `ARAGON_TODO_FOLLOW=garbage` therefore resolves to `'notify'` and throws
-        // nothing (AC-5).
-        followThrough: followMode(src.followThrough, DEFAULT_TODO_CONFIG.followThrough),
-        // The fourth key needs nothing beyond this line: no migration, because
-        // `CONFIG_VERSION` is only stamped and never branched, and an old file reaches
-        // the new default through `{ ...DEFAULT, ...partial } + clamp`.
-        acceptance: bool(src.acceptance, DEFAULT_TODO_CONFIG.acceptance),
-    };
-}
-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',
-    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),
-        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),
-    };
-}
-// ---------------------------------------------------------------------------
-// Auto-update (cli-auto-update §4.1)
-//
-// The EIGHTH nested section in the persisted config, after `apiKeys`, `skills`,
-// `log`, `team`, `todo`, `retry` and `fast` — and, like all of them, SCALARS
-// ONLY, exactly one level deep. `store.ts` merges these sections BY HAND and
-// that merge is only correct while nesting stays flat (C-5).
-//
-// BOTH OF `store.ts`'s MERGES MUST LEARN ABOUT THIS SECTION, AND THE OMISSION IS
-// SILENT (C-4 / R-10). `config set update.mode notify` sends
-// `{ update: { mode: 'notify' } }`; without the write merge the shallow
-// top-level spread REPLACES the whole section and `checkIntervalMs`, `registry`
-// and `distTag` silently revert on disk. This package has paid for that twice
-// already — `todo` P0-1 and `fast` R-10 — which is why it is written down a
-// third time rather than assumed to be common knowledge.
-//
-// FOUR KEYS AND NO MORE (D-16). `mode` covers on / notify / off; a fifth key
-// (`autoInstall`) would be a second way to say the same thing, and two ways to
-// express one setting is how they end up disagreeing.
-// ---------------------------------------------------------------------------
-/** `auto` installs; `notify` only reports; `off` disables the subsystem. */
-export const UPDATE_MODES = ['auto', 'notify', 'off'];
-export function isUpdateMode(v) {
-    return typeof v === 'string' && UPDATE_MODES.includes(v);
-}
-export const DEFAULT_UPDATE_CONFIG = {
-    mode: 'auto',
-    // FOUR HOURS, in ms. `checkIntervalMs` and not `checkIntervalHours` (D-17):
-    // every other duration in this config is in ms (`toolTimeoutMs`,
-    // `idleTimeoutMs`, `team.dispatchTimeoutMs`, `retry.initialDelayMs`), and one
-    // unit per file is worth more than one shorter number.
-    checkIntervalMs: 14_400_000,
-    registry: '',
-    distTag: 'latest',
-};
-/** 15 minutes to 7 days. The floor is a politeness bound on the registry. */
-const UPDATE_INTERVAL_RANGE = { min: 900_000, max: 604_800_000 };
-/** npm's own dist-tag grammar, loosely: no slashes, no spaces, no `@`. */
-const DIST_TAG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
-/**
- * THE single gate for every update-config read AND write, mirroring
- * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
- * / `clampRetryConfig` / `clampFastConfig` for the reason all six 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".
- *
- * `registry` is CLAMPED TO `''` rather than rejected when it is not an
- * `http(s):` URL. `''` means "derive it" (§3.3), which is the safe reading of a
- * typo — the alternative is a background timer that throws on a value the user
- * cannot see it reading.
- */
-export function clampUpdateConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    const registry = text(src.registry, DEFAULT_UPDATE_CONFIG.registry);
-    const distTag = text(src.distTag, DEFAULT_UPDATE_CONFIG.distTag);
-    return {
-        mode: isUpdateMode(src.mode) ? src.mode : DEFAULT_UPDATE_CONFIG.mode,
-        checkIntervalMs: clampInt(src.checkIntervalMs, DEFAULT_UPDATE_CONFIG.checkIntervalMs, UPDATE_INTERVAL_RANGE),
-        registry: isRegistryUrl(registry) ? registry : DEFAULT_UPDATE_CONFIG.registry,
-        distTag: DIST_TAG_RE.test(distTag) ? distTag : DEFAULT_UPDATE_CONFIG.distTag,
-    };
-}
-function isRegistryUrl(raw) {
-    if (raw.length === 0)
-        return false;
-    try {
-        const url = new URL(raw);
-        // `http:` is accepted for a LAN mirror; nothing else is a registry.
-        return url.protocol === 'https:' || url.protocol === 'http:';
-    }
-    catch {
-        return false;
-    }
-}
-export const DEFAULT_COMPACTION_CONFIG = {
-    enabled: true,
-    threshold: 0.9,
-    warnThreshold: 0.75,
-    keepRecentTurns: 4,
-    useFastTier: true,
-    onFailure: 'stop',
-    subagents: true,
-    archive: true,
-};
-const THRESHOLD_RANGE = { min: 0.5, max: 0.95 };
-const WARN_THRESHOLD_FLOOR = 0.4;
-/** The gap the warn mark must stay below the trigger by. */
-const WARN_THRESHOLD_GAP = 0.05;
-const KEEP_RECENT_TURNS_RANGE = { min: 1, max: 20 };
-const COMPACTION_FAILURE_MODES = ['truncate', 'stop'];
-/**
- * Round a ratio to two decimals — the precision a percentage actually has.
- *
- * BINARY FLOATING POINT MAKES `0.95 - 0.05` EQUAL `0.8999999999999999`, and both
- * numbers here are produced by subtraction (`threshold - WARN_THRESHOLD_GAP`) and
- * by division (`parseThresholdInput` turning `90` into `90/100`). Without this,
- * `aragon config list` shows a seventeen-digit value for a setting the user typed
- * as `90%`, and `config.json` records one — which looks like corruption and
- * invites a hand-edit that the clamp then has to defend against.
- *
- * Two decimals is exact for every value the range can hold: the clamp is
- * `[0.5, 0.95]` and the UI reads it as a whole percentage.
- */
-function ratio(value) {
-    return Math.round(value * 100) / 100;
-}
-function failureMode(value, fallback) {
-    return typeof value === 'string' && COMPACTION_FAILURE_MODES.includes(value)
-        ? value
-        : fallback;
-}
-/**
- * THE single gate for every compaction-config read AND write, mirroring the six
- * clamps above for the reason all of them 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".
- *
- * THE ORDER IS FIXED AND IT MATTERS (§4.2 / P2-5). `threshold` is clamped to
- * `[0.5, 0.95]` FIRST, then `warnThreshold` to
- * `[0.4, clampedThreshold - 0.05]`. The other order lets a file holding
- * `{threshold: 0.6, warnThreshold: 0.9}` produce a warn mark ABOVE the trigger —
- * a gauge that turns amber after it has already gone red. Both bounds of the
- * second range stay reachable at the extremes: `threshold` floored at `0.5`
- * gives `warnThreshold` a range of `[0.4, 0.45]`.
- */
-export function clampCompactionConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    const threshold = ratio(clampNumber(src.threshold, DEFAULT_COMPACTION_CONFIG.threshold, THRESHOLD_RANGE));
-    const warnCeiling = ratio(threshold - WARN_THRESHOLD_GAP);
-    return {
-        enabled: bool(src.enabled, DEFAULT_COMPACTION_CONFIG.enabled),
-        threshold,
-        warnThreshold: ratio(clampNumber(src.warnThreshold, DEFAULT_COMPACTION_CONFIG.warnThreshold, {
-            min: Math.min(WARN_THRESHOLD_FLOOR, warnCeiling),
-            max: warnCeiling,
-        })),
-        keepRecentTurns: clampInt(src.keepRecentTurns, DEFAULT_COMPACTION_CONFIG.keepRecentTurns, KEEP_RECENT_TURNS_RANGE),
-        useFastTier: bool(src.useFastTier, DEFAULT_COMPACTION_CONFIG.useFastTier),
-        // CLAMPED TO THE DEFAULT, NEVER REJECTED — the discipline every other key in
-        // this file follows. `ARAGON_COMPACTION_ON_FAILURE=garbage` resolves to
-        // `truncate` and throws nothing.
-        onFailure: failureMode(src.onFailure, DEFAULT_COMPACTION_CONFIG.onFailure),
-        subagents: bool(src.subagents, DEFAULT_COMPACTION_CONFIG.subagents),
-        archive: bool(src.archive, DEFAULT_COMPACTION_CONFIG.archive),
-    };
-}
-export const DEFAULT_BASH_CONFIG = {
-    background: true,
-    autoBackground: true,
-    startupSettleMs: 4000,
-    readyTimeoutMs: 60_000,
-};
-const STARTUP_SETTLE_RANGE = { min: 500, max: 30_000 };
-const READY_TIMEOUT_RANGE = { min: 5_000, max: 600_000 };
-/**
- * THE single gate for every bash-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".
- *
- * CLAMPED, NEVER REJECTED — the discipline every other key in this file follows.
- * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
- */
-export function clampBashConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    return {
-        background: bool(src.background, DEFAULT_BASH_CONFIG.background),
-        autoBackground: bool(src.autoBackground, DEFAULT_BASH_CONFIG.autoBackground),
-        startupSettleMs: clampInt(src.startupSettleMs, DEFAULT_BASH_CONFIG.startupSettleMs, STARTUP_SETTLE_RANGE),
-        readyTimeoutMs: clampInt(src.readyTimeoutMs, DEFAULT_BASH_CONFIG.readyTimeoutMs, READY_TIMEOUT_RANGE),
-    };
-}
-export const DEFAULT_JOBS_CONFIG = {
-    enabled: true,
-    waitSeconds: 30,
-    stallSeconds: 300,
-    persistLog: true,
-    noticeSteer: true,
-};
-const WAIT_SECONDS_RANGE = { min: 5, max: 60 };
-const STALL_SECONDS_RANGE = { min: 30, max: 3600 };
-/**
- * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`
- * and the four sections before it.
- *
- * THE ELEVENTH SECTION, AND THE FIRST ONE THAT `config set` CAN REACH BY
- * NESTED KEY (§6.5). Every key is a SCALAR and the section is ONE level deep,
- * because `runConfigGet` splits on a single dot - a `jobs.mirror.enabled` would
- * resolve to `undefined` and the setting would silently never apply.
- */
-export function clampJobsConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    return {
-        enabled: bool(src.enabled, DEFAULT_JOBS_CONFIG.enabled),
-        waitSeconds: clampInt(src.waitSeconds, DEFAULT_JOBS_CONFIG.waitSeconds, WAIT_SECONDS_RANGE),
-        stallSeconds: clampInt(src.stallSeconds, DEFAULT_JOBS_CONFIG.stallSeconds, STALL_SECONDS_RANGE),
-        persistLog: bool(src.persistLog, DEFAULT_JOBS_CONFIG.persistLog),
-        noticeSteer: bool(src.noticeSteer, DEFAULT_JOBS_CONFIG.noticeSteer),
-    };
-}
-export const DEFAULT_PROMPTS_CONFIG = {
-    enabled: true,
-    insertMode: 'insert',
-};
-const PROMPT_INSERT_MODES = ['insert', 'replace'];
-/**
- * THE single gate for every `prompts` read AND write, like the eleven sections
- * above it.
- *
- * An unrecognized `insertMode` falls back to `insert` rather than to `replace`,
- * and that direction is deliberate: a typo must never silently start DISCARDING
- * what the user has already typed into the composer.
- */
-export function clampPromptsConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    const mode = typeof src.insertMode === 'string' ? src.insertMode.trim().toLowerCase() : '';
-    return {
-        enabled: bool(src.enabled, DEFAULT_PROMPTS_CONFIG.enabled),
-        insertMode: PROMPT_INSERT_MODES.includes(mode)
-            ? mode
-            : DEFAULT_PROMPTS_CONFIG.insertMode,
-    };
-}
-export const DEFAULT_TASK_SUMMARY_CONFIG = {
-    enabled: true,
-    fallback: true,
-};
-/**
- * THE single gate for every `taskSummary` read AND write, like the twelve sections
- * above it.
- *
- * BOTH DEFAULTS ARE `true`, AND THE DIRECTION MATTERS: a corrupt or hand-edited
- * section must not silently switch off a feature the user asked for, and - more
- * importantly - it must not switch off the FLOOR, which is the only thing standing
- * between a failed call and an empty header cell.
- */
-export function clampTaskSummaryConfig(raw) {
-    const src = (raw && typeof raw === 'object' ? raw : {});
-    return {
-        enabled: bool(src.enabled, DEFAULT_TASK_SUMMARY_CONFIG.enabled),
-        fallback: bool(src.fallback, DEFAULT_TASK_SUMMARY_CONFIG.fallback),
-    };
-}
-/**
- * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
- *
- * `null` RATHER THAN A CLAMPED DEFAULT, because this is a COMMAND argument and
- * not a config value: `/compact threshold banana` must say so rather than
- * silently setting 0.9 and reporting success.
- */
-export function parseThresholdInput(raw) {
-    const trimmed = raw.trim().replace(/%$/, '');
-    if (trimmed.length === 0)
-        return null;
-    const n = Number.parseFloat(trimmed);
-    if (!Number.isFinite(n))
-        return null;
-    // `90` means 90 %, `0.9` means 0.9. The ambiguity is only at `1`, which is
-    // above the clamp ceiling either way.
-    const ratio = n > 1 ? n / 100 : n;
-    if (ratio <= 0 || ratio > 1)
-        return null;
-    return ratio;
-}
-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,
-    // AUTO. The model table is right for every listed model, and a default number
-    // here would be the same fabricated denominator this key exists to correct.
-    contextWindow: null,
-    theme: 'auto',
-    reducedMotion: false,
-    exitTranscript: true,
-    transcriptWindow: DEFAULT_TRANSCRIPT_WINDOW,
-    transcriptRetain: DEFAULT_TRANSCRIPT_RETAIN,
-    renderGovernor: DEFAULT_RENDER_GOVERNOR,
-    maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
-    diffRender: DEFAULT_DIFF_RENDER,
-    scrollMode: DEFAULT_SCROLL_MODE,
-    syncOutput: DEFAULT_SYNC_OUTPUT,
-    confirmTools: false,
-    toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
-    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
-    apiKeys: {},
-    historyEnabled: true,
-    density: 'comfortable',
-    hints: true,
-    mouse: true,
-    mouseSelect: DEFAULT_MOUSE_SELECT,
-    paste: true,
-    keyboardEnhancement: true,
-    scrollResumeMs: DEFAULT_SCROLL_RESUME_MS,
-    planModeDefault: false,
-    planModeHumanTimeoutMs: DEFAULT_PLAN_HUMAN_TIMEOUT_MS,
-    skills: DEFAULT_SKILLS_CONFIG,
-    log: DEFAULT_LOG_CONFIG,
-    team: DEFAULT_TEAM_CONFIG,
-    // The load path's first spread is what supplies the section to a user with no
-    // `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,
-    // And one section later again, for the third time. Without this line a user
-    // whose `config.json` predates auto-update resolves `config.update.mode` to
-    // `undefined`, which is neither `'auto'` nor `'off'` — so the §3.8 gate
-    // (`cfg.update.mode !== 'off'`) would read TRUE and the feature would be on
-    // for a reason nobody could point at.
-    update: DEFAULT_UPDATE_CONFIG,
-    // And one section later again, for the fourth time. Without this line a user
-    // whose `config.json` predates compaction resolves `config.compaction.enabled`
-    // to `undefined`, which is FALSY — so a feature that is `true` by default would
-    // arrive OFF for every existing user, which is the one direction this
-    // particular default must never fail in.
-    compaction: DEFAULT_COMPACTION_CONFIG,
-    // And one section later again, for the fifth time. `bash.background` is `true`
-    // by default, so a `config.json` predating this feature resolving it to
-    // `undefined` would arrive with background services OFF for every existing
-    // user — the same direction the compaction line above must never fail in.
-    bash: DEFAULT_BASH_CONFIG,
-    // And one section later again, for the sixth time, and this one would fail
-    // in the WORSE direction: every key in `jobs` is `true` or positive by
-    // default, so a `config.json` predating this feature resolving `config.jobs`
-    // to `undefined` would throw on `config.jobs.waitSeconds` at construction
-    // rather than quietly disabling something.
-    jobs: DEFAULT_JOBS_CONFIG,
-    // And one section later again, for the seventh time, and this one has BOTH
-    // failure directions at once: `prompts.enabled` is `true` by default, so a
-    // `config.json` predating this feature would resolve it to `undefined` (falsy)
-    // and arrive with the key silently off - while
-    // `prompts.insertMode` would be `undefined`, which is neither `'insert'` nor
-    // `'replace'` and would make `planPromptFill` fall through to its `replace`
-    // branch. That branch discards the user's own words, so the miss would be a data
-    // loss rather than a missing hint.
-    prompts: DEFAULT_PROMPTS_CONFIG,
-    // And one section later again, for the eighth time - and this one has a silent
-    // DATA-LOSS-shaped miss: `taskSummary.enabled` and `.fallback` are both `true` by
-    // default, and `App` reads `cfg.taskSummary?.fallback !== false` at call time. A
-    // `config.json` predating this feature would resolve them to `undefined`, which
-    // happens to behave like the defaults in those two readers but NOT in
-    // `config list`, so the file would report a section it never wrote. One line
-    // here, like the seven above it.
-    taskSummary: DEFAULT_TASK_SUMMARY_CONFIG,
-    // And one section later again. Without this line a `config.json` predating governance
-    // resolves `governance` to `undefined`; every reader would then disagree with `config list`.
-    governance: DEFAULT_GOVERNANCE_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;
-}
-/**
- * Config keys whose MEANING was removed, mapped to the explanation a user gets if
- * they still try to set one.
- *
- * SEPARATE FROM `LEGACY_STATE_KEYS`, because the disposition differs: those keys'
- * values were MOVED somewhere else, while these have nowhere to go — the feature
- * they configured no longer exists. Merging the two lists would erase that
- * difference at exactly the moment someone is reading the file to find out what
- * happened to their setting.
- *
- * Stripped on the READ side for the same reason `stripLegacyStateKeys` is:
- * `loadPersistedConfig()` merges `{ ...DEFAULT_CONFIG, ...partial }`, so a key
- * left on disk rides that spread into memory and `updatePersistedConfig` writes it
- * straight back. The user deletes the line, launches once, and watches it return.
- */
-export const RETIRED_CONFIG_KEYS = {
-    planModeMaxAskRounds: 'ask_user has no round limit any more, so this key is gone. Nothing to set; ' +
-        'the next config write removes it from config.json.',
-};
-/**
- * THE single gate that keeps retired keys out of `config.json`. Applied on the
- * read side, so it is self-healing: every write is read-strip-merge-write, and a
- * hand-edited file, a downgrade to an older CLI and back, or a half-finished
- * migration all converge on a clean file at the next write.
- */
-export function stripRetiredConfigKeys(raw) {
-    const out = { ...raw };
-    for (const key of Object.keys(RETIRED_CONFIG_KEYS))
-        delete out[key];
-    return out;
-}
-// ---------------------------------------------------------------------------
-// Coercion / validation helpers
-// ---------------------------------------------------------------------------
-/** Coerce an arbitrary value into a positive integer, or `undefined`. */
-function coerceTokenCount(v) {
-    if (v === null || v === undefined || v === '')
-        return undefined;
-    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
-    if (!Number.isFinite(n) || n <= 0)
-        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 === '')
-        return fallback;
-    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
-    if (!Number.isFinite(n) || n <= 0)
-        return fallback;
-    return Math.floor(n);
-}
-/**
- * Mask a secret for display: keep a short prefix + suffix, redact the middle.
- * A short/empty key is fully redacted so the length is not leaked.
- *
- * The glyphs are parameters with ASCII defaults (spec §4.1 tier B). This module
- * has no terminal capabilities to consult, and the result is rendered in the
- * settings screen — which on a legacy `cmd.exe` used to show two question-mark
- * boxes where the redaction dots belonged. The UI passes its resolved glyphs;
- * every other caller gets output that is safe anywhere.
- */
-export function maskSecret(key, opts = {}) {
-    const maskChar = opts.maskChar ?? '*';
-    const ellipsis = opts.ellipsis ?? '...';
-    if (!key)
-        return '(not set)';
-    const trimmed = key.trim();
-    if (trimmed.length <= 8)
-        return maskChar.repeat(4);
-    return `${trimmed.slice(0, 3)}${ellipsis}${trimmed.slice(-4)}`;
-}