@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/config/cli-commands.js

@@ -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 { clampFastConfig, clampRetryConfig, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_UPDATE_CONFIG, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampCompactionConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_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 = [
@@ -103,6 +103,33 @@ export const UPDATE_CONFIG_SET_KEYS = [
     'update.registry',
     'update.distTag',
 ];
+/**
+ * Config keys under `compaction.` that `aragon config set` accepts
+ * (context-auto-compaction §4.2).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * five sets above each record: a generic setter would write `compaction` as a
+ * FLAT string key (`"compaction.enabled": "false"` at the top level of the
+ * file), the section would silently never take effect, and `config set` would
+ * still print `Set compaction.enabled = false`.
+ *
+ * THIS SET IS WHAT MAKES THE KILL SWITCH REACHABLE FROM A SCRIPT. `config list`
+ * enumerates the section dynamically and so shows these keys whether they are
+ * here or not; `config set` does not, so without this block
+ * `aragon config set compaction.enabled false` fails with "Unknown config key"
+ * while the key is visibly listed one command over. Manual-test row 9 — the
+ * persisted-off-survives-a-flagless-run check — runs exactly that command.
+ */
+export const COMPACTION_CONFIG_SET_KEYS = [
+    'compaction.enabled',
+    'compaction.threshold',
+    'compaction.warnThreshold',
+    'compaction.keepRecentTurns',
+    'compaction.useFastTier',
+    'compaction.onFailure',
+    'compaction.subagents',
+    'compaction.archive',
+];
 function isTrue(value) {
     return value === 'true' || value === '1';
 }
@@ -294,6 +321,55 @@ export function applyUpdateConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `compaction.*` dotted key into a patch, or `null` for anything
+ * else (context-auto-compaction §4.2).
+ *
+ * EVERY KEY ROUTES THROUGH `clampCompactionConfig`, not through a local parse,
+ * for the reason `applyRetryConfigSet`, `applyFastConfigSet` and
+ * `applyUpdateConfigSet` all record: one gate for both directions means no key
+ * here can pick up a different coercion later, and `config set
+ * compaction.threshold 0.2` writes the clamped `0.5` while the caller echoes the
+ * STORED value.
+ *
+ * `threshold` and `warnThreshold` additionally accept a PERCENTAGE, because that
+ * is the unit the status bar shows and `/compact threshold` accepts.
+ *
+ * A VALUE THE PARSER REJECTS RESOLVES TO THE DEFAULT, NOT TO THE CURRENT SETTING
+ * — the same thing `config set retry.maxRetries banana` does, because `clampOne`
+ * merges the field onto `DEFAULT_COMPACTION_CONFIG` before clamping it. That is
+ * the house behaviour and it is not silent: `cli.tsx` echoes the STORED value, so
+ * a typo prints the number that was actually written rather than the one that was
+ * typed. Unlike the settings screen and `/compact threshold`, both of which
+ * genuinely ignore an unparseable value, this surface has no third state.
+ */
+export function applyCompactionConfigSet(key, value) {
+    const patch = (compaction) => ({ compaction });
+    const clampOne = (field, raw = value) => {
+        const merged = clampCompactionConfig({ ...DEFAULT_COMPACTION_CONFIG, [field]: raw });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'compaction.enabled':
+            return patch(clampOne('enabled', isTrue(value)));
+        case 'compaction.threshold':
+            return patch(clampOne('threshold', parseThresholdInput(value) ?? undefined));
+        case 'compaction.warnThreshold':
+            return patch(clampOne('warnThreshold', parseThresholdInput(value) ?? undefined));
+        case 'compaction.keepRecentTurns':
+            return patch(clampOne('keepRecentTurns'));
+        case 'compaction.useFastTier':
+            return patch(clampOne('useFastTier', isTrue(value)));
+        case 'compaction.onFailure':
+            return patch(clampOne('onFailure'));
+        case 'compaction.subagents':
+            return patch(clampOne('subagents', isTrue(value)));
+        case 'compaction.archive':
+            return patch(clampOne('archive', isTrue(value)));
+        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

@@ -14,7 +14,10 @@
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
  *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
  *     ARAGON_DIFF_RENDER, ARAGON_SYNC_OUTPUT,
- *     ARAGON_UPDATE.
+ *     ARAGON_UPDATE,
+ *     ARAGON_COMPACTION, ARAGON_COMPACTION_THRESHOLD,
+ *     ARAGON_COMPACTION_KEEP_TURNS, ARAGON_COMPACTION_SUBAGENTS,
+ *     ARAGON_COMPACTION_ARCHIVE.
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
  * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because

package/dist/config/env.js

@@ -14,7 +14,10 @@
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
  *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
  *     ARAGON_DIFF_RENDER, ARAGON_SYNC_OUTPUT,
- *     ARAGON_UPDATE.
+ *     ARAGON_UPDATE,
+ *     ARAGON_COMPACTION, ARAGON_COMPACTION_THRESHOLD,
+ *     ARAGON_COMPACTION_KEEP_TURNS, ARAGON_COMPACTION_SUBAGENTS,
+ *     ARAGON_COMPACTION_ARCHIVE.
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
  * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
@@ -34,7 +37,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
-import { clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, } from './schema.js';
+import { clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, parseThresholdInput, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
  * process env wins — dotenv never overrides already-set variables).
@@ -127,6 +130,29 @@ export function readEnvConfig() {
     if (mouse !== undefined && mouse.length > 0) {
         partial.mouse = mouse === '1' || mouse === 'true' || mouse === 'on' || mouse === 'yes';
     }
+    // ARAGON_MOUSE_SELECT=0 turns drag-select off while leaving the wheel alone —
+    // the third rung of the mouse ladder (`--no-mouse` is the first two). Parsed by
+    // the POSITIVE list, exactly as its neighbour above is.
+    const mouseSelect = process.env.ARAGON_MOUSE_SELECT?.trim().toLowerCase();
+    if (mouseSelect !== undefined && mouseSelect.length > 0) {
+        partial.mouseSelect =
+            mouseSelect === '1' ||
+                mouseSelect === 'true' ||
+                mouseSelect === 'on' ||
+                mouseSelect === 'yes';
+    }
+    // ARAGON_SCROLL_RESUME_MS=<n> — idle delay before a paused viewport returns to
+    // the newest line; `0` disables auto-resume. THE ONLY CHANNEL BESIDES THE
+    // CONFIG FILE, because §6.1 gives this key no CLI flag on purpose. `load.ts`
+    // clamps it to [0, 120000]; a non-numeric value is LEFT ABSENT rather than
+    // written, so a typo falls through to the config file underneath instead of
+    // silently replacing it (the rule `ARAGON_MAX_TOKENS` above already follows).
+    const scrollResume = process.env.ARAGON_SCROLL_RESUME_MS?.trim();
+    if (scrollResume !== undefined && scrollResume.length > 0) {
+        const n = Number.parseInt(scrollResume, 10);
+        if (Number.isFinite(n) && n >= 0)
+            partial.scrollResumeMs = n;
+    }
     // ARAGON_PLAN=1 starts the session in PLAN mode — the same channel story as
     // ARAGON_FULLSCREEN, for terminals reached through a wrapper that owns argv.
     const plan = process.env.ARAGON_PLAN?.trim().toLowerCase();
@@ -289,6 +315,70 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.fast = section;
     }
+    // ARAGON_COMPACTION=0 turns context compaction off; the other two tune it
+    // (context-auto-compaction §4.3). Parsed by the POSITIVE list, exactly as
+    // ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO /
+    // ARAGON_RETRY / ARAGON_FAST are — NOT by `envBool` below, whose NEGATIVE list
+    // disagrees with it on values like `ARAGON_COMPACTION=disable`.
+    //
+    // THREE VARS, AND DELIBERATELY NO `ARAGON_COMPACTION_ON_FAILURE` /
+    // `_USE_FAST_TIER` / `_WARN_THRESHOLD`. 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.
+    // "Is it on, when does it fire, and how much does it keep" passes that test;
+    // "what should it do if the summarizer 500s" 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 four branches above
+    // all use, and NOT three `if` blocks each assigning `partial.compaction`. THE
+    // CAST IS WHAT WOULD MAKE THAT MISTAKE SILENT: a second assignment compiles
+    // clean and drops `enabled`.
+    const compaction = process.env.ARAGON_COMPACTION?.trim().toLowerCase();
+    const compactionThreshold = process.env.ARAGON_COMPACTION_THRESHOLD?.trim();
+    const compactionKeepTurns = process.env.ARAGON_COMPACTION_KEEP_TURNS?.trim();
+    // The two hardening kill switches (context-auto-compaction-hardening §4.3).
+    // They pass the same test the three above do: both name a behaviour that a
+    // container or an automated harness may need to switch off with no flag and no
+    // config file in reach - sub-agent compaction because it changes what a
+    // dispatch costs, and the archive because it writes conversation content to
+    // disk in an environment that may not permit it.
+    const compactionSubagents = process.env.ARAGON_COMPACTION_SUBAGENTS?.trim().toLowerCase();
+    const compactionArchive = process.env.ARAGON_COMPACTION_ARCHIVE?.trim().toLowerCase();
+    const positive = (v) => v === '1' || v === 'true' || v === 'on' || v === 'yes';
+    if ((compaction !== undefined && compaction.length > 0) ||
+        (compactionThreshold !== undefined && compactionThreshold.length > 0) ||
+        (compactionKeepTurns !== undefined && compactionKeepTurns.length > 0) ||
+        (compactionSubagents !== undefined && compactionSubagents.length > 0) ||
+        (compactionArchive !== undefined && compactionArchive.length > 0)) {
+        const section = {};
+        if (compaction !== undefined && compaction.length > 0) {
+            section.enabled = positive(compaction);
+        }
+        if (compactionSubagents !== undefined && compactionSubagents.length > 0) {
+            section.subagents = positive(compactionSubagents);
+        }
+        if (compactionArchive !== undefined && compactionArchive.length > 0) {
+            section.archive = positive(compactionArchive);
+        }
+        if (compactionThreshold !== undefined && compactionThreshold.length > 0) {
+            // Left ABSENT on a bad value rather than clamped to a default, so a typo
+            // falls through to the config layer instead of masking it for the session.
+            const parsed = parseThresholdInput(compactionThreshold);
+            if (parsed !== null)
+                section.threshold = parsed;
+        }
+        if (compactionKeepTurns !== undefined && compactionKeepTurns.length > 0) {
+            const n = Number.parseInt(compactionKeepTurns, 10);
+            if (Number.isFinite(n) && n > 0)
+                section.keepRecentTurns = n;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract the five sections above rely on.
+        if (Object.keys(section).length > 0) {
+            partial.compaction = 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).
     //

package/dist/config/load.d.ts

@@ -36,6 +36,19 @@ export interface CliFlags {
     liveToolOutput?: boolean;
     /** `--mouse` ⇒ true, `--no-mouse` ⇒ false, absent ⇒ undefined. */
     mouse?: boolean;
+    /**
+     * `--mouse-select` ⇒ true, `--no-mouse-select` ⇒ false, absent ⇒ undefined
+     * (tui-selection-and-scroll-follow §6.1).
+     *
+     * DECLARED AS A PAIR, and carried through `toFlags`, for the reason the
+     * `mouse` note above it records: a flag that reaches neither `CliFlags` nor
+     * `toFlags` is inert with no compile error and no runtime error. `mouseSelect`
+     * is additionally PERSISTED and defaults to `true`, so a lone
+     * `--no-mouse-select` would make commander default `opts.mouseSelect` to
+     * `true` — indistinguishable from silence, and silently overriding a stored
+     * `false` on every run (the `--todo-panel` trap).
+     */
+    mouseSelect?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
     skills?: boolean;
     /** `--skill <name>` ×N — force Level 2 injection for this run. */
@@ -178,6 +191,24 @@ export interface CliFlags {
      * config file and `ARAGON_UPDATE=notify`.
      */
     update?: boolean;
+    /**
+     * `--compaction` ⇒ true, `--no-compaction` ⇒ false, absent ⇒ undefined
+     * (context-auto-compaction §4.3).
+     *
+     * DECLARED AS A PAIR — MANDATORY (C-13 / P1-5), for the reason `--team`,
+     * `--todo-panel`, `--render-governor`, `--retry`, `--fast` and `--update` each
+     * record in turn, and this one shares the WORST polarity with `--update`:
+     * `compaction.enabled` is PERSISTED and defaults to `true`, so a lone
+     * `--no-compaction` would make commander default `opts.compaction` to `true`,
+     * at which point the flag is indistinguishable from its own default and
+     * silently overwrites a stored `false` on EVERY run that passed no flag at all.
+     *
+     * That would make R-12's whole mitigation ("one config key restores the old
+     * behaviour exactly") FALSE — for a feature that spends the user's money.
+     */
+    compaction?: boolean;
+    /** `--compaction-threshold <0..1|N%>` — session override for `threshold`. */
+    compactionThreshold?: string;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -59,6 +59,38 @@ function resolveMouse(flags, env, file) {
         return file.mouse;
     return DEFAULT_CONFIG.mouse;
 }
+/**
+ * Drag-select: flag › env › file › default `true`
+ * (tui-selection-and-scroll-follow §6.1).
+ *
+ * SHAPED EXACTLY LIKE `resolveMouse` above, deliberately and not by copy-paste
+ * habit: it has the same four layers, the same "a persisted `true` is a value
+ * and not an opinion" property, and the same env var story. Reaching for the
+ * `hints` shape instead — `flags.x !== undefined ? … : file.x ?? DEFAULT`, which
+ * reads NO ENV AT ALL — would ship `ARAGON_MOUSE_SELECT` as documented-but-dead,
+ * which is precisely the failure the note above `resolveMouse` records for
+ * `ARAGON_MOUSE`.
+ */
+function resolveMouseSelect(flags, env, file) {
+    if (flags.mouseSelect !== undefined)
+        return flags.mouseSelect;
+    if (env.mouseSelect !== undefined)
+        return env.mouseSelect;
+    if (file.mouseSelect !== undefined)
+        return file.mouseSelect;
+    return DEFAULT_CONFIG.mouseSelect;
+}
+/**
+ * Idle scroll-resume delay: env › file › default 5000, clamped to [0, 120000].
+ *
+ * NO FLAG LAYER, and the absence is the design rather than an omission (§6.1):
+ * this key has no `--scroll-resume-ms`, so `CliFlags` carries no field for one
+ * and a resolver that read it would be reading a value nothing can ever set.
+ */
+function resolveScrollResumeMs(env, file) {
+    const raw = env.scrollResumeMs ?? file.scrollResumeMs;
+    return clampScrollResumeMs(raw, DEFAULT_CONFIG.scrollResumeMs);
+}
 /**
  * Resolve whether logs reach a file: flag › env › an explicit `false` in the
  * file › default `true`.
@@ -208,6 +240,33 @@ function resolveUpdateConfig(flags, env, file) {
         ...(flags.update !== undefined ? { mode: flags.update ? 'auto' : 'off' } : {}),
     });
 }
+/**
+ * Merge the `compaction` section across all four layers (defaults › file › env ›
+ * flags), context-auto-compaction §4.3.
+ *
+ * `!== undefined` ON `flags.compaction`, WHICH IS THE WHOLE POINT (C-13 / P1-5).
+ * The rule `resolveTeamConfig`, `resolveTodoConfig`, `resolveRetryConfig`,
+ * `resolveFastConfig` and `resolveUpdateConfig` each state once: commander
+ * materialises a lone `--no-compaction` as `opts.compaction = true` when the flag
+ * is absent, so a truthiness check cannot tell `--no-compaction` from "not
+ * passed" — and here the damage runs in the worst direction, silently re-enabling
+ * a subsystem the user turned off, on every flagless run, for a feature that
+ * spends money.
+ *
+ * `--compaction-threshold` is PARSED rather than spread, because `90%` and `0.9`
+ * are both legitimate spellings and a typo must change NOTHING rather than
+ * resolve to a default (`parseThresholdInput` returns `null`).
+ */
+function resolveCompactionConfig(flags, env, file) {
+    const thresholdFlag = flags.compactionThreshold !== undefined ? parseThresholdInput(flags.compactionThreshold) : null;
+    return clampCompactionConfig({
+        ...DEFAULT_CONFIG.compaction,
+        ...(file.compaction ?? {}),
+        ...(env.compaction ?? {}),
+        ...(flags.compaction !== undefined ? { enabled: flags.compaction } : {}),
+        ...(thresholdFlag !== null ? { threshold: thresholdFlag } : {}),
+    });
+}
 /**
  * Resolve the adaptive render governor: flag › env › file › default `true`
  * (tui-render-performance L4).
@@ -460,6 +519,8 @@ export function loadConfig(flags = {}) {
         density,
         hints,
         mouse: resolveMouse(flags, env.partial, file),
+        mouseSelect: resolveMouseSelect(flags, env.partial, file),
+        scrollResumeMs: resolveScrollResumeMs(env.partial, file),
         // From `<home>/state.json`, not the config file — see `ui-state.ts`.
         submitCount: readSubmitCount(),
         startInPlanMode,
@@ -483,6 +544,7 @@ export function loadConfig(flags = {}) {
         retry: resolveRetryConfig(flags, env.partial, file),
         fast: resolveFastConfig(flags, env.partial, file),
         update: resolveUpdateConfig(flags, env.partial, file),
+        compaction: resolveCompactionConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,

package/dist/config/schema.d.ts

@@ -115,6 +115,36 @@ export declare const DEFAULT_DIFF_RENDER = true;
  * because the frame differ already removes the flicker on its own.
  */
 export declare const DEFAULT_SYNC_OUTPUT = true;
+/**
+ * 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 declare 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 declare const DEFAULT_SCROLL_RESUME_MS = 5000;
+/**
+ * `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 declare function clampScrollResumeMs(v: unknown, fallback: number): number;
 /** `ask_user` calls allowed per user turn. */
 export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
@@ -489,6 +519,94 @@ export declare const DEFAULT_UPDATE_CONFIG: UpdateConfig;
  * cannot see it reading.
  */
 export declare function clampUpdateConfig(raw: unknown): UpdateConfig;
+export type CompactionFailureMode = 'truncate' | 'stop';
+export interface CompactionConfig {
+    /**
+     * Whether a `ContextManager` is constructed at all. Default TRUE.
+     *
+     * THE ONLY KEY IN THIS SECTION THAT DEFAULTS ON, AND THE ONLY ONE READ ONCE AT
+     * CONSTRUCTION — the `team.enabled` / `todo.enabled` / `fast.enabled` rule.
+     *
+     * IT DEFAULTS TO `true` UNLIKE EVERY OTHER OPTIONAL SUBSYSTEM HERE, and that is
+     * deliberate (D-16): `fast.enabled` and `team.enabled` default off because they
+     * ADD behaviour the user did not ask for. This one REMOVES a failure the user
+     * did not ask for — without it, the answer to a full context window is a dead
+     * run. Byte-identity is still honoured: `--no-compaction` constructs no
+     * manager, subscribes nothing, allocates no registry, and leaves the engine
+     * loop with `ctx.contextManager === undefined`.
+     */
+    enabled: boolean;
+    /** Occupancy ratio that triggers compaction. Read LIVE. */
+    threshold: number;
+    /**
+     * Where the status-bar gauge turns amber.
+     *
+     * CLAMPED JOINTLY WITH `threshold`, AND THE ORDER IS FIXED — see
+     * `clampCompactionConfig`. "Jointly" is not an instruction.
+     */
+    warnThreshold: number;
+    /** Complete turns kept verbatim in the tail. Read LIVE. */
+    keepRecentTurns: number;
+    /**
+     * Summarize with the fast tier when it resolves. Default TRUE.
+     *
+     * A PREFERENCE, NOT THE COMMON PATH (P2-8). `resolveFastTier` returns
+     * `{ok:false, reason:'disabled'}` on `fast.enabled !== true` alone, and
+     * `fast.enabled` defaults to `false` — so out of the box the summarizer is the
+     * SESSION'S OWN MODEL, and the first compaction is a ~30 k-token call on it.
+     */
+    useFastTier: boolean;
+    /** What happens when summarization fails outright. See §3.7 rungs 3 / 4. */
+    onFailure: CompactionFailureMode;
+    /**
+     * Give `task` children their own compaction
+     * (context-auto-compaction-hardening §3.4 / W3). Default TRUE.
+     *
+     * IT REVERSES D-15, WHOSE PREMISE IS MEASURABLY FALSE at the configured bounds:
+     * `team.maxTurnsPerSubagent` is 24 and `team.dispatchTimeoutMs` is 900 000, and
+     * 24 turns over fifteen minutes is the same profile as the lead run this
+     * feature exists for. When a child overflows today its history is discarded and
+     * the lead receives one partial sentence for the whole dispatch.
+     *
+     * `false` REPRODUCES ROUND 1 EXACTLY: `subagent.ts` spreads no `contextManager`
+     * key at all, so the child's loop gate tests an absent field.
+     */
+    subagents: boolean;
+    /**
+     * Write the dropped messages to `<home>/compaction/` before adopting a splice
+     * (context-auto-compaction-hardening §3.5 / W4). Default TRUE.
+     *
+     * NOT UNDO (§12): restoring an over-full history restores the condition that
+     * triggered the compaction. This is fidelity on disk, so "the summary is wrong
+     * and the agent proceeded on a false record" becomes something a human can
+     * check rather than something they must accept.
+     */
+    archive: boolean;
+}
+export declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
+/**
+ * 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 declare function clampCompactionConfig(raw: unknown): CompactionConfig;
+/**
+ * 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 declare function parseThresholdInput(raw: string): number | null;
 export interface PersistedConfig {
     version: number;
     provider: string;
@@ -578,6 +696,14 @@ export interface PersistedConfig {
      * heuristics for an explicit `true` to override (D-10).
      */
     mouse: boolean;
+    /**
+     * Drag-select + copy in full-screen mode (tui-selection-and-scroll-follow
+     * §6.1). Ignored when `mouse` is false; also decides whether `?1002h` is
+     * written at all, so `false` is byte-identical to a pre-feature session.
+     */
+    mouseSelect: boolean;
+    /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
+    scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
     planModeDefault: boolean;
     /** `ask_user` rounds allowed per user turn; clamped to [1, 10]. */
@@ -598,6 +724,8 @@ export interface PersistedConfig {
     fast: FastConfig;
     /** Auto-update. The EIGHTH nested object; scalars only (see UpdateConfig). */
     update: UpdateConfig;
+    /** Context compaction. The NINTH nested object; scalars only (see CompactionConfig). */
+    compaction: CompactionConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -727,6 +855,19 @@ export interface CliConfig {
      * only). Resolved by `resolveMouse` in `load.ts`.
      */
     mouse: boolean;
+    /**
+     * Whether this session may drag-select and copy.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `diffRender` above records at length: `runInteractive` reads
+     * `config.mouseSelect` — where `config` is a `CliConfig` — to decide the
+     * `?1002h` write, the controller and the `decorate` hook. A key added to the
+     * persisted shape alone would round-trip through `config set`, appear in
+     * `config list`, and never reach a single one of them.
+     */
+    mouseSelect: boolean;
+    /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
+    scrollResumeMs: number;
     /**
      * Whether this session opens in PLAN mode.
      *
@@ -800,6 +941,24 @@ export interface CliConfig {
      * and be discarded, with no compile error and no runtime error.
      */
     update: UpdateConfig;
+    /**
+     * Resolved context-compaction settings (context-auto-compaction §4.2).
+     *
+     * `enabled` here decides whether `AgentController` CONSTRUCTS a
+     * `CompactionWiring` at all, which is what makes `false` byte-identical to a
+     * pre-feature build: no manager is passed to `new Agent({...})`, nothing is
+     * subscribed, no registry is allocated, and the loop's checkpoint is one `if`
+     * against an absent field. The other five keys are read LIVE on every use, so
+     * `/compact threshold 0.8` takes effect in the running session.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking`, `liveToolOutput`, `diffRender`, `mouseSelect` and `update`
+     * each record above: the controller and the compactor read `config.compaction`,
+     * where `config` is a `CliConfig`, so a key added to the persisted shape alone
+     * would round-trip through `config set`, appear in `config list` — and never
+     * reach either of them.
+     */
+    compaction: CompactionConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *