@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/config/cli-commands.d.ts

@@ -1,6 +1,6 @@
 /**
- * `aragon config get | list | edit | home`, plus the `log.*` and `team.*`
- * branches of `config set`.
+ * `aragon config get | list | edit | home`, plus the `log.*`, `team.*`,
+ * `retry.*`, `fast.*` and `update.*` branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -21,6 +21,39 @@ export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "
  * `Set team.enabled = false`.
  */
 export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent"];
+/**
+ * Config keys under `retry.` that `aragon config set` accepts
+ * (llm-api-retry-backoff §8.2).
+ *
+ * Handled here rather than in `cli.tsx`'s switch for the reason this module's
+ * header gives about `log.*` and `team.*`: that switch is past this package's
+ * complexity ceiling, and a key added to the membership set but forgotten in the
+ * switch falls through every case, writes nothing, and still prints
+ * `Set retry.maxRetries = 0`.
+ */
+export declare const RETRY_CONFIG_SET_KEYS: readonly ["retry.enabled", "retry.maxRetries", "retry.initialDelayMs", "retry.maxDelayMs", "retry.multiplier", "retry.jitter", "retry.respectRetryAfter", "retry.maxElapsedMs", "retry.onPartialStream"];
+/**
+ * Config keys under `fast.` that `aragon config set` accepts (fast-model-tier
+ * §4.2).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * three sets above each record: a generic setter would write `fast` as a FLAT
+ * string key (`"fast.model": "haiku"` at the top level of the file), the section
+ * would silently never take effect, and `config set` would still print
+ * `Set fast.model = haiku`.
+ */
+export declare const FAST_CONFIG_SET_KEYS: readonly ["fast.enabled", "fast.provider", "fast.model", "fast.baseUrl", "fast.thinkingLevel", "fast.delegate", "fast.review", "fast.reviewEveryTurns", "fast.reviewContextTurns", "fast.reviewMaxChars", "fast.reviewMaxPerSession"];
+/**
+ * Config keys under `update.` that `aragon config set` accepts (cli-auto-update
+ * §4.1).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * four sets above each record: a generic setter would write `update` as a FLAT
+ * string key (`"update.mode": "notify"` at the top level of the file), the
+ * section would silently never take effect, and `config set` would still print
+ * `Set update.mode = notify`.
+ */
+export declare const UPDATE_CONFIG_SET_KEYS: readonly ["update.mode", "update.checkIntervalMs", "update.registry", "update.distTag"];
 /**
  * Translate a `log.*` dotted key into a patch, or `null` for anything else.
  *
@@ -43,6 +76,50 @@ export declare function applyLogConfigSet(key: string, value: string): Partial<P
  * won't stick". `clampTeamConfig` is the one gate both directions pass through.
  */
 export declare function applyTeamConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `retry.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `retry` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the retry count would silently reset `respectRetryAfter` and `jitter`.
+ *
+ * `maxRetries` GOES THROUGH `clampRetryConfig`, NOT `coercePositiveInt`, and that
+ * is not a style choice (R-16): `coercePositiveInt` returns its fallback for
+ * `n <= 0`, so `config set retry.maxRetries 0` would write **10** — the maximum
+ * instead of the kill switch, silently. The whole section is routed through the
+ * one gate so no key here can pick up the wrong coercion later; the caller echoes
+ * the STORED value, which is what makes an out-of-range input visible.
+ */
+export declare function applyRetryConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `fast.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `fast` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the cadence would silently switch the whole tier off (R-10).
+ *
+ * EVERY NUMERIC AND ENUM KEY ROUTES THROUGH `clampFastConfig`, not through
+ * `coercePositiveInt` or a local parse, for the reason `applyRetryConfigSet`
+ * records: one gate for both directions means no key here can pick up a
+ * different coercion later, and `config set fast.reviewEveryTurns 400` writes
+ * the clamped 50 while the caller echoes the STORED value (AC-13).
+ */
+export declare function applyFastConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate an `update.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `update` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the mode would silently reset the interval, the registry mirror and
+ * the dist-tag (C-4 / R-10).
+ *
+ * EVERY KEY ROUTES THROUGH `clampUpdateConfig`, not through a local parse, for
+ * the reason `applyRetryConfigSet` and `applyFastConfigSet` both record: one
+ * gate for both directions means no key here can pick up a different coercion
+ * later, and `config set update.checkIntervalMs 5` writes the clamped 900000
+ * while the caller echoes the STORED value (AC-20).
+ */
+export declare function applyUpdateConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says

package/dist/config/cli-commands.js

@@ -1,6 +1,6 @@
 /**
- * `aragon config get | list | edit | home`, plus the `log.*` and `team.*`
- * branches of `config set`.
+ * `aragon config get | list | edit | home`, plus the `log.*`, `team.*`,
+ * `retry.*`, `fast.*` and `update.*` branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -13,7 +13,7 @@ import process from 'node:process';
 import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptHistoryPath, getUiStatePath, isHomeOverridden, } from './app-paths.js';
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
-import { coercePositiveInt, maskSecret, DEFAULT_TEAM_CONFIG, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_UPDATE_CONFIG, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -43,6 +43,66 @@ export const TEAM_CONFIG_SET_KEYS = [
     'team.dispatchTimeoutMs',
     'team.maxTurnsPerSubagent',
 ];
+/**
+ * Config keys under `retry.` that `aragon config set` accepts
+ * (llm-api-retry-backoff §8.2).
+ *
+ * Handled here rather than in `cli.tsx`'s switch for the reason this module's
+ * header gives about `log.*` and `team.*`: that switch is past this package's
+ * complexity ceiling, and a key added to the membership set but forgotten in the
+ * switch falls through every case, writes nothing, and still prints
+ * `Set retry.maxRetries = 0`.
+ */
+export const RETRY_CONFIG_SET_KEYS = [
+    'retry.enabled',
+    'retry.maxRetries',
+    'retry.initialDelayMs',
+    'retry.maxDelayMs',
+    'retry.multiplier',
+    'retry.jitter',
+    'retry.respectRetryAfter',
+    'retry.maxElapsedMs',
+    'retry.onPartialStream',
+];
+/**
+ * Config keys under `fast.` that `aragon config set` accepts (fast-model-tier
+ * §4.2).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * three sets above each record: a generic setter would write `fast` as a FLAT
+ * string key (`"fast.model": "haiku"` at the top level of the file), the section
+ * would silently never take effect, and `config set` would still print
+ * `Set fast.model = haiku`.
+ */
+export const FAST_CONFIG_SET_KEYS = [
+    'fast.enabled',
+    'fast.provider',
+    'fast.model',
+    'fast.baseUrl',
+    'fast.thinkingLevel',
+    'fast.delegate',
+    'fast.review',
+    'fast.reviewEveryTurns',
+    'fast.reviewContextTurns',
+    'fast.reviewMaxChars',
+    'fast.reviewMaxPerSession',
+];
+/**
+ * Config keys under `update.` that `aragon config set` accepts (cli-auto-update
+ * §4.1).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * four sets above each record: a generic setter would write `update` as a FLAT
+ * string key (`"update.mode": "notify"` at the top level of the file), the
+ * section would silently never take effect, and `config set` would still print
+ * `Set update.mode = notify`.
+ */
+export const UPDATE_CONFIG_SET_KEYS = [
+    'update.mode',
+    'update.checkIntervalMs',
+    'update.registry',
+    'update.distTag',
+];
 function isTrue(value) {
     return value === 'true' || value === '1';
 }
@@ -112,6 +172,128 @@ export function applyTeamConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `retry.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `retry` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the retry count would silently reset `respectRetryAfter` and `jitter`.
+ *
+ * `maxRetries` GOES THROUGH `clampRetryConfig`, NOT `coercePositiveInt`, and that
+ * is not a style choice (R-16): `coercePositiveInt` returns its fallback for
+ * `n <= 0`, so `config set retry.maxRetries 0` would write **10** — the maximum
+ * instead of the kill switch, silently. The whole section is routed through the
+ * one gate so no key here can pick up the wrong coercion later; the caller echoes
+ * the STORED value, which is what makes an out-of-range input visible.
+ */
+export function applyRetryConfigSet(key, value) {
+    const patch = (retry) => ({ retry });
+    const clampOne = (field) => {
+        const merged = clampRetryConfig({ ...DEFAULT_RETRY_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'retry.enabled':
+            return patch({ enabled: isTrue(value) });
+        case 'retry.maxRetries':
+            return patch(clampOne('maxRetries'));
+        case 'retry.initialDelayMs':
+            return patch(clampOne('initialDelayMs'));
+        case 'retry.maxDelayMs':
+            return patch(clampOne('maxDelayMs'));
+        case 'retry.multiplier':
+            return patch(clampOne('multiplier'));
+        case 'retry.jitter':
+            return patch({ jitter: isTrue(value) });
+        case 'retry.respectRetryAfter':
+            return patch({ respectRetryAfter: isTrue(value) });
+        case 'retry.maxElapsedMs':
+            return patch(clampOne('maxElapsedMs'));
+        case 'retry.onPartialStream':
+            return patch({ onPartialStream: isTrue(value) });
+        default:
+            return null;
+    }
+}
+/**
+ * Translate a `fast.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `fast` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the cadence would silently switch the whole tier off (R-10).
+ *
+ * EVERY NUMERIC AND ENUM KEY ROUTES THROUGH `clampFastConfig`, not through
+ * `coercePositiveInt` or a local parse, for the reason `applyRetryConfigSet`
+ * records: one gate for both directions means no key here can pick up a
+ * different coercion later, and `config set fast.reviewEveryTurns 400` writes
+ * the clamped 50 while the caller echoes the STORED value (AC-13).
+ */
+export function applyFastConfigSet(key, value) {
+    const patch = (fast) => ({ fast });
+    const clampOne = (field) => {
+        const merged = clampFastConfig({ ...DEFAULT_FAST_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'fast.enabled':
+            return patch({ enabled: isTrue(value) });
+        case 'fast.provider':
+            return patch(clampOne('provider'));
+        case 'fast.model':
+            return patch(clampOne('model'));
+        case 'fast.baseUrl':
+            return patch(clampOne('baseUrl'));
+        case 'fast.thinkingLevel':
+            return patch(clampOne('thinkingLevel'));
+        case 'fast.delegate':
+            return patch({ delegate: isTrue(value) });
+        case 'fast.review':
+            return patch({ review: isTrue(value) });
+        case 'fast.reviewEveryTurns':
+            return patch(clampOne('reviewEveryTurns'));
+        case 'fast.reviewContextTurns':
+            return patch(clampOne('reviewContextTurns'));
+        case 'fast.reviewMaxChars':
+            return patch(clampOne('reviewMaxChars'));
+        case 'fast.reviewMaxPerSession':
+            return patch(clampOne('reviewMaxPerSession'));
+        default:
+            return null;
+    }
+}
+/**
+ * Translate an `update.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `update` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the mode would silently reset the interval, the registry mirror and
+ * the dist-tag (C-4 / R-10).
+ *
+ * EVERY KEY ROUTES THROUGH `clampUpdateConfig`, not through a local parse, for
+ * the reason `applyRetryConfigSet` and `applyFastConfigSet` both record: one
+ * gate for both directions means no key here can pick up a different coercion
+ * later, and `config set update.checkIntervalMs 5` writes the clamped 900000
+ * while the caller echoes the STORED value (AC-20).
+ */
+export function applyUpdateConfigSet(key, value) {
+    const patch = (update) => ({ update });
+    const clampOne = (field) => {
+        const merged = clampUpdateConfig({ ...DEFAULT_UPDATE_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'update.mode':
+            return patch(clampOne('mode'));
+        case 'update.checkIntervalMs':
+            return patch(clampOne('checkIntervalMs'));
+        case 'update.registry':
+            return patch(clampOne('registry'));
+        case 'update.distTag':
+            return patch(clampOne('distTag'));
+        default:
+            return null;
+    }
+}
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says

package/dist/config/env.d.ts

@@ -5,11 +5,23 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
+ *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
  *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
- *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR,
- *     ARAGON_TRANSCRIPT_RETAIN, ARAGON_RENDER_GOVERNOR,
- *     ARAGON_MAX_RENDER_INTERVAL_MS.
+ *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
+ *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
+ *     ARAGON_LOG_LEVEL,
+ *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
+ *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_UPDATE.
+ *
+ * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
+ * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
+ * §3.3 puts them BELOW `config.update.registry` in precedence — the opposite of
+ * the env-beats-file rule this file implements. Writing them into `partial`
+ * would silently invert that order and make a config-file mirror unreachable on
+ * any machine where npm exports its own registry (which is every machine npm
+ * runs a script on).
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never

package/dist/config/env.js

@@ -5,11 +5,23 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
+ *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
  *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
- *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR,
- *     ARAGON_TRANSCRIPT_RETAIN, ARAGON_RENDER_GOVERNOR,
- *     ARAGON_MAX_RENDER_INTERVAL_MS.
+ *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
+ *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
+ *     ARAGON_LOG_LEVEL,
+ *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
+ *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_UPDATE.
+ *
+ * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
+ * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
+ * §3.3 puts them BELOW `config.update.registry` in precedence — the opposite of
+ * the env-beats-file rule this file implements. Writing them into `partial`
+ * would silently invert that order and make a config-file mirror unreachable on
+ * any machine where npm exports its own registry (which is every machine npm
+ * runs a script on).
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -61,6 +73,27 @@ export function readEnvConfig() {
     if (process.env.ARAGON_THINKING) {
         partial.thinkingLevel = clampThinkingLevel(process.env.ARAGON_THINKING.trim(), 'off');
     }
+    // Parsed by the POSITIVE list, like ARAGON_FULLSCREEN: anything else is left
+    // ABSENT so the config file underneath still wins.
+    const showThinking = process.env.ARAGON_SHOW_THINKING?.trim().toLowerCase();
+    if (showThinking !== undefined && showThinking.length > 0) {
+        partial.showThinking =
+            showThinking === '1' ||
+                showThinking === 'true' ||
+                showThinking === 'on' ||
+                showThinking === 'yes';
+    }
+    // The same positive-list parse as its neighbour, and the same "a non-empty
+    // value is an ANSWER" rule -- which is what lets `ARAGON_LIVE_TOOL_OUTPUT=0`
+    // turn a default-ON feature off (agent-activity-presentation-live §4.1).
+    const liveToolOutput = process.env.ARAGON_LIVE_TOOL_OUTPUT?.trim().toLowerCase();
+    if (liveToolOutput !== undefined && liveToolOutput.length > 0) {
+        partial.liveToolOutput =
+            liveToolOutput === '1' ||
+                liveToolOutput === 'true' ||
+                liveToolOutput === 'on' ||
+                liveToolOutput === 'yes';
+    }
     // `auto` / `0` mean AUTO (`null`); a number is clamped to the accepted range.
     // Anything else is LEFT ABSENT rather than written as `null`: a typo here used
     // to become AUTO and silently discard the number in the config file under it,
@@ -179,6 +212,113 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.todo = section;
     }
+    // ARAGON_RETRY=0 is the kill switch for API retry; ARAGON_RETRY_MAX=<n>
+    // overrides the count. Parsed by the POSITIVE list, exactly as
+    // ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO
+    // are — NOT by `envBool` below, which uses a negative list.
+    //
+    // TWO VARS ONLY, and no third for the delays: every env var in this file exists
+    // because a flag and a config file are BOTH unreachable in the channel it
+    // serves, and nobody tunes a backoff multiplier from a container entrypoint.
+    //
+    // `>= 0`, NOT `> 0`, and the difference is the whole point (R-16).
+    // `ARAGON_TEAM_MAX` above guards `parsed > 0`, which is right for a fan-out
+    // width and wrong here: `0` is this key's documented floor AND its kill switch,
+    // so a `> 0` guard would drop `ARAGON_RETRY_MAX=0` on the floor and leave the
+    // user with the default 10. "Left ABSENT when unparseable" still holds and
+    // still matters — an unparseable value must not look permanently supplied, or
+    // the config file can never win again.
+    const retry = process.env.ARAGON_RETRY?.trim().toLowerCase();
+    const retryMax = process.env.ARAGON_RETRY_MAX?.trim();
+    if ((retry !== undefined && retry.length > 0) || (retryMax !== undefined && retryMax.length > 0)) {
+        const section = {};
+        if (retry !== undefined && retry.length > 0) {
+            section.enabled = retry === '1' || retry === 'true' || retry === 'on' || retry === 'yes';
+        }
+        if (retryMax !== undefined && retryMax.length > 0) {
+            const parsed = Number.parseInt(retryMax, 10);
+            if (Number.isFinite(parsed) && parsed >= 0)
+                section.maxRetries = parsed;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract `partial.skills` / `partial.log` / `partial.team` rely on.
+        if (Object.keys(section).length > 0)
+            partial.retry = section;
+    }
+    // ARAGON_FAST=1 turns the fast model tier on; the other three name it
+    // (fast-model-tier §4.3). Parsed by the POSITIVE list, exactly as
+    // ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO /
+    // ARAGON_RETRY are — NOT by `envBool` below, whose NEGATIVE list disagrees with
+    // it on values like `ARAGON_FAST=disable`.
+    //
+    // FOUR VARS, AND DELIBERATELY NO `ARAGON_FAST_REVIEW_EVERY` / `_MAX_CHARS` /
+    // `_DELEGATE` (D-14). The rule this file states is that an environment variable
+    // exists only where a flag AND a config file are BOTH unreachable — a
+    // container, an ssh session, being spawned by another tool. "Which model, and
+    // is it on" passes that test; tuning a review cadence does not, and every key
+    // that fails it is documentation debt plus a fifth place for the value to
+    // disagree with itself.
+    //
+    // ONE ACCUMULATED SECTION, ASSIGNED ONCE — the shape the `team`, `todo` and
+    // `retry` branches above all use, and NOT four `if` blocks each assigning
+    // `partial.fast`. THE CAST IS WHAT WOULD MAKE THAT MISTAKE SILENT: a second
+    // assignment compiles clean and drops `enabled`, so
+    // `ARAGON_FAST=1 ARAGON_FAST_MODEL=x` would quietly resolve with the tier off
+    // (the P1-4 defect this file records for `todo`).
+    const fast = process.env.ARAGON_FAST?.trim().toLowerCase();
+    const fastProvider = process.env.ARAGON_FAST_PROVIDER?.trim();
+    const fastModel = process.env.ARAGON_FAST_MODEL?.trim();
+    const fastBaseUrl = process.env.ARAGON_FAST_BASE_URL?.trim();
+    if ((fast !== undefined && fast.length > 0) ||
+        (fastProvider !== undefined && fastProvider.length > 0) ||
+        (fastModel !== undefined && fastModel.length > 0) ||
+        (fastBaseUrl !== undefined && fastBaseUrl.length > 0)) {
+        const section = {};
+        if (fast !== undefined && fast.length > 0) {
+            section.enabled = fast === '1' || fast === 'true' || fast === 'on' || fast === 'yes';
+        }
+        if (fastProvider !== undefined && fastProvider.length > 0)
+            section.provider = fastProvider;
+        if (fastModel !== undefined && fastModel.length > 0)
+            section.model = fastModel;
+        if (fastBaseUrl !== undefined && fastBaseUrl.length > 0)
+            section.baseUrl = fastBaseUrl;
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract the four sections above rely on.
+        if (Object.keys(section).length > 0)
+            partial.fast = section;
+    }
+    // ARAGON_UPDATE=0|off|false turns auto-update off; `notify` reports without
+    // installing; 1|on|true|yes turns it on (cli-auto-update §4.2).
+    //
+    // A TRI-STATE, so it is parsed by an EXPLICIT POSITIVE LIST PER OUTCOME rather
+    // than by the boolean positive list its neighbours use — and emphatically not
+    // by `envBool` below, whose NEGATIVE list would resolve `ARAGON_UPDATE=disable`
+    // to `true`.
+    //
+    // ANYTHING UNRECOGNISED IS LEFT ABSENT, which is the invariant this file
+    // states three times over (`ARAGON_TEAM_MAX`, `ARAGON_RETRY_MAX`,
+    // `ARAGON_MAX_TOKENS`): a value that resolves to a default looks PERMANENTLY
+    // SUPPLIED, and the config file underneath can then never win again. For a
+    // kill switch that is the worst possible failure — `ARAGON_UPDATE=disabled`
+    // would read as "on" while the user believes they turned it off.
+    //
+    // `ARAGON_TODO_FOLLOW` is the tri-state precedent: the recognised string is
+    // written through and `clampUpdateConfig` stays the single gate, so there is
+    // never a second validator that can disagree with the first.
+    const update = process.env.ARAGON_UPDATE?.trim().toLowerCase();
+    if (update !== undefined && update.length > 0) {
+        const mode = update === '0' || update === 'false' || update === 'off' || update === 'no'
+            ? 'off'
+            : update === 'notify'
+                ? 'notify'
+                : update === '1' || update === 'true' || update === 'on' || update === 'yes'
+                    ? 'auto'
+                    : undefined;
+        if (mode !== undefined) {
+            partial.update = { mode };
+        }
+    }
     // Render bounds (tui-render-performance §5.3). Same channel story as
     // ARAGON_FULLSCREEN: a container or a wrapper that owns argv can reach neither
     // a flag nor a config file, and a session that freezes is exactly the case

package/dist/config/load.d.ts

@@ -27,6 +27,13 @@ export interface CliFlags {
     compact?: boolean;
     /** `--hints` ⇒ true, `--no-hints` ⇒ false, absent ⇒ undefined. */
     hints?: boolean;
+    /** `--show-thinking` ⇒ true, `--no-show-thinking` ⇒ false, absent ⇒ undefined. */
+    showThinking?: boolean;
+    /**
+     * `--live-tool-output` ⇒ true, `--no-live-tool-output` ⇒ false, absent ⇒ undefined
+     * (agent-activity-presentation-live §4.1).
+     */
+    liveToolOutput?: boolean;
     /** `--mouse` ⇒ true, `--no-mouse` ⇒ false, absent ⇒ undefined. */
     mouse?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
@@ -99,6 +106,65 @@ export interface CliFlags {
     renderGovernor?: boolean;
     /** `--max-render-interval <ms>` — the governor ceiling for this run (L4). */
     maxRenderInterval?: string | number;
+    /**
+     * `--retry` ⇒ true, `--no-retry` ⇒ false, absent ⇒ undefined
+     * (llm-api-retry-backoff §6.2).
+     *
+     * DECLARED AS A PAIR, for the reason `--todo-panel` and `--render-governor`
+     * each record: `retry.enabled` is PERSISTED, so a lone `--no-retry` would make
+     * commander default `opts.retry` to `true` and silently overwrite a stored
+     * `enabled: false` on every run that passed no flag at all.
+     */
+    retry?: boolean;
+    /**
+     * `--retry-max <n>` — override `retry.maxRetries` for this run (still clamped).
+     *
+     * `0` IS A LEGITIMATE VALUE HERE and is the flag's kill switch, which is why
+     * `resolveRetryConfig` tests `!== undefined` rather than truthiness and why the
+     * clamp is `clampIntAllowingZero`.
+     */
+    retryMax?: string | number;
+    /**
+     * `--fast` ⇒ true, `--no-fast` ⇒ false, absent ⇒ undefined
+     * (fast-model-tier §4.3).
+     *
+     * DECLARED AS A PAIR — MANDATORY (C-9), for the reason `--team`,
+     * `--todo-panel`, `--render-governor` and `--retry` each record in turn.
+     * `fast.enabled` is PERSISTED and defaults to `false`, so a lone `--fast`
+     * would be indistinguishable from silence and the DEFAULT-OFF guarantee (R-d)
+     * would depend on a commander detail.
+     */
+    fast?: boolean;
+    /** `--fast-model <id>` — implies nothing about `enabled` on its own. */
+    fastModel?: string;
+    /** `--fast-provider <id>` — `''` (absent) inherits the main provider. */
+    fastProvider?: string;
+    /**
+     * `--fast-review <n|off>` — `off` sets `fast.review: false`, a number sets
+     * `reviewEveryTurns`.
+     *
+     * ONE FLAG FOR TWO KEYS, and deliberately: "how often" and "at all" are one
+     * decision to a user, and a separate `--no-fast-review` would be a fifth pair
+     * to keep in step with `toFlags`.
+     */
+    fastReview?: string;
+    /**
+     * `--update` ⇒ true, `--no-update` ⇒ false, absent ⇒ undefined
+     * (cli-auto-update §4.2).
+     *
+     * DECLARED AS A PAIR — MANDATORY (C-11), for the reason `--team`,
+     * `--todo-panel`, `--render-governor`, `--retry` and `--fast` each record in
+     * turn. `update.mode` is PERSISTED and defaults to `'auto'`, so a lone
+     * `--no-update` would make commander default `opts.update` to `true` and
+     * silently overwrite a stored `off` on every run that passed no flag at all —
+     * i.e. the kill switch would un-set itself.
+     *
+     * A BOOLEAN FOR A TRI-STATE KEY, deliberately: the flag is a SESSION override
+     * and `notify` is a preference, not something a user reaches for once. `true`
+     * maps to `'auto'`, `false` to `'off'`; `notify` is reachable through the
+     * config file and `ARAGON_UPDATE=notify`.
+     */
+    update?: boolean;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime