@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/cli.js

@@ -23,11 +23,11 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -47,10 +47,14 @@ import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
+import { forceWindowsVtInput } from './ui/win-vt-force.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
 import { pickGlyphs } from './ui/glyphs.js';
+import { getTheme } from './ui/theme.js';
+import { copyText } from './ui/clipboard.js';
+import { createSelectionController, } from './ui/selection/selection-controller.js';
 import { DENY_ALL_HUMAN_INPUT } from './tools/human-input.js';
 // A VALUE import, and the one deliberate exception to the paragraph above
 // (cli-auto-update-hardening P2-7). `boot/guard.js` statically pulls
@@ -104,6 +108,11 @@ function toFlags(opts) {
         // Without this line the flag never reaches `CliFlags` and `--no-mouse` is
         // inert — a failure with no compile error and no runtime error (P1-2).
         mouse: opts.mouse,
+        // Site three of three for `--mouse-select` / `--no-mouse-select` — NINE
+        // features, one trap. A flag needs the `.option()` declaration below, a field
+        // on `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
+        // exists because `--no-mouse` shipped inert once already.
+        mouseSelect: opts.mouseSelect,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
@@ -170,6 +179,15 @@ function toFlags(opts) {
         // means `--no-update` reports nothing, does nothing, and leaves the updater
         // running.
         update: opts.update,
+        // Site three of three for `--compaction` / `--no-compaction` — NINE
+        // features, one trap. A flag needs the `.option()` declaration below, a field
+        // on `CliFlags`, AND a line here; miss this one and the flag is inert with no
+        // compile error and no runtime error. It bites here for the same reason it
+        // does one field up: this is the KILL SWITCH for a feature that spends the
+        // user's money on a summarizer, so a missing line means `--no-compaction`
+        // reports nothing, does nothing, and leaves compaction armed.
+        compaction: opts.compaction,
+        compactionThreshold: opts.compactionThreshold,
     };
 }
 // ---------------------------------------------------------------------------
@@ -285,6 +303,69 @@ function makeExecController(flags, deps) {
  */
 const FRAME_FALLBACK_NOTICE = 'Frame diffing lost sync with the terminal and fell back to a full repaint. ' +
     'If the display looks wrong, restart with `--no-diff-render`.';
+/**
+ * Make this console deliver `CSI Z`, on a Node that will not do it for us
+ * (shift-tab-mode-toggle-still-dead-on-windows, C1).
+ *
+ * Returns whether the console now reports; never throws. `false` means nothing
+ * changed and the session runs exactly as it did before this feature existed,
+ * with `MODE_TOGGLE_KEYS.fallback` carrying the mode toggle instead.
+ *
+ * RAW MODE IS RAISED HERE, AND THE ORDER IS THE ENTIRE MECHANISM. libuv rewrites
+ * the whole console mode on every raw-mode TRANSITION, and its pre-22.17 path
+ * does not know about this bit - so setting the bit first and letting Ink raise
+ * raw mode afterwards clears it again, measured (analysis section 3.3). Raising
+ * it first inverts that: `uv_tty_set_mode` returns early when the mode is
+ * unchanged, so Ink's own `setRawMode(true)` at mount is a no-op and the bit
+ * survives to the first keypress.
+ *
+ * That same asymmetry is why there is no restore call anywhere. Ink lowers raw
+ * mode when it unmounts, and that transition IS the restore - it is the only
+ * thing that ever clears the bit, since neither Windows nor the console does
+ * (section 3.5b). The `exit` hook exists for the paths that never unmount
+ * (`taskkill`, a closed terminal window, a crash), which are exactly the
+ * unattended ones where a console left in VT-input mode has nobody to notice.
+ *
+ * WHY THIS RUNS BEFORE `render()` rather than from an effect inside `App`: the
+ * answer gates `wantMouse`, which decides the `?1000h` write and the filter
+ * BEFORE Ink mounts. Learning the truth one tick too late would mean the wheel
+ * stays off for the whole session on a console we just repaired.
+ */
+function forceVtInputForThisConsole() {
+    if (process.platform !== 'win32' || !process.stdin.isTTY)
+        return false;
+    const logger = getLogger();
+    try {
+        process.stdin.setRawMode(true);
+    }
+    catch (err) {
+        // A TTY that refuses raw mode is not a console we can repair; C2 carries it.
+        logger.warn('cli', 'vt_input_rawmode_failed', { error: err.message });
+        return false;
+    }
+    process.on('exit', () => {
+        try {
+            process.stdin.setRawMode(false);
+        }
+        catch {
+            /* Stream already torn down — nothing left to restore. */
+        }
+    });
+    const result = forceWindowsVtInput();
+    if (result.ok) {
+        logger.info('cli', 'vt_input_forced', { before: result.before, after: result.after });
+        return true;
+    }
+    // Constrained Language Mode kills `Add-Type`, an old conhost drops the bit it
+    // does not implement, and `wrong_console` means we configured somebody else's
+    // console. All three are ordinary on the fleets this bug keeps landing on, so
+    // they degrade in silence and only the log says which one happened.
+    logger.warn('cli', 'vt_input_force_failed', {
+        reason: result.reason,
+        ...(result.detail ? { detail: result.detail } : {}),
+    });
+    return false;
+}
 /**
  * The interactive TUI — and the ONLY place that may touch the screen.
  *
@@ -339,7 +420,15 @@ function runInteractive(flags, extras = {}) {
     // filter itself, and the `mouseSource` prop that decides whether the user is
     // advised about a mode that is not running. Wiring any of them separately
     // re-opens the gap where the app claims a capability it does not have.
-    const vtInputSupported = supportsWindowsVtInput(process.platform, process.versions.node);
+    //
+    // AND `vtInputSupported` IS NOW A MEASUREMENT, NOT A PREDICTION
+    // (shift-tab-mode-toggle-still-dead-on-windows, C1). It used to be exactly
+    // `supportsWindowsVtInput(...)` - "is this Node new enough to turn the bit on
+    // for us?". We now turn it on ourselves when it is not, so continuing to gate
+    // on the Node version would switch the wheel off, and keep the warning up, on
+    // a console this process just repaired.
+    const vtInputByNode = supportsWindowsVtInput(process.platform, process.versions.node);
+    const vtInputSupported = vtInputByNode || forceVtInputForThisConsole();
     const wantMouse = mode === 'fullscreen' &&
         config.mouse &&
         !!process.stdout.isTTY &&
@@ -349,6 +438,20 @@ function runInteractive(flags, extras = {}) {
         ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
         : null;
     const disposeMouse = () => mouseFilter?.dispose();
+    // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
+    //
+    // ONE EXPRESSION, READ BY FOUR THINGS, and that is the same discipline
+    // `wantMouse` above follows for the same reason: the `?1002h` write, the
+    // controller, the differ's `decorate` hook and the startup notice must never
+    // disagree about whether drag-select is running. With it false the session is
+    // byte-identical to a pre-feature build — no extra escape on the wire (AC-8),
+    // no controller, no `decorate`, no mirror.
+    const wantSelect = mouseFilter !== null && config.mouseSelect;
+    const selectionBridge = {
+        controller: null,
+        onCopied: null,
+        requestRedraw: null,
+    };
     // --- Frame differ (tui-input-flicker-fix §3.2 / §4.2). -------------------
     //
     // FULL-SCREEN ONLY, and that is invariant I-3 rather than caution: inline mode
@@ -371,6 +474,25 @@ function runInteractive(flags, extras = {}) {
             // edge inside the differ: a notice per fallback would be a repaint
             // storm triggered by a repaint problem (§5.6).
             onFirstFallback: () => console.warn(FRAME_FALLBACK_NOTICE),
+            // ABSENT ENTIRELY without drag-select, not a no-op function: the
+            // differ's identity path then allocates nothing and copies nothing,
+            // which is what makes `mouseSelect: false` a statement about the code
+            // rather than about how cheap an empty function is.
+            ...(wantSelect
+                ? {
+                    decorate: (lines) => selectionBridge.controller?.decorate(lines) ?? lines,
+                    // P1-7: a pass-through frame writes the RAW Ink frame verbatim,
+                    // so the highlight is wiped off the terminal while the
+                    // controller still believes it is painted. Deferred out of the
+                    // current stack because this fires from inside `transform`,
+                    // which is inside Ink's own `stdout.write`.
+                    onInvalidate: () => {
+                        const controller = selectionBridge.controller;
+                        if (controller)
+                            setImmediate(() => controller.clear());
+                    },
+                }
+                : {}),
         }))
         : null;
     // `null` when no writer was built, so `/perf` can say "diff render off" rather
@@ -406,8 +528,9 @@ function runInteractive(flags, extras = {}) {
     if (mode === 'fullscreen') {
         // `mouse` here means "a filter is installed", NOT "the user wants mouse
         // support" — see `AltScreenOptions`. `screen.ts` must never derive it for
-        // itself, or a later refactor re-opens the gap I-8 closes.
-        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null });
+        // itself, or a later refactor re-opens the gap I-8 closes. `motion` carries
+        // the same discipline for `?1002h`: already decided, never re-derived.
+        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null, motion: wantSelect });
         const restore = () => screen?.restore();
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
@@ -444,6 +567,115 @@ function runInteractive(flags, extras = {}) {
     // `CI` is excluded on top of the two TTY tests because a CI runner with a pty
     // allocated is otherwise a machine that silently mutates its own global
     // toolchain mid-pipeline (D-11).
+    // --- The foreign-write door (§4.4.5). ------------------------------------
+    //
+    // Where bytes that are OURS but are NOT a frame go — today, the OSC 52
+    // clipboard sequence. THREE SHAPES, ONE DOOR, and the third one is the reason
+    // this is a resolved value rather than an inline arrow:
+    //
+    //  * with the differ in front of stdout it MUST be `frameWriter.writeForeign`,
+    //    which invalidates the cache and skips the fallback accounting — through
+    //    the proxy the same bytes are an unrecognised chunk, which is
+    //    `passThrough(true)`, which prints `FRAME_FALLBACK_NOTICE` at a user who
+    //    did nothing but copy something (P1-6);
+    //  * without one — `--no-diff-render`, and inline mode, which never builds a
+    //    differ at all — stdout IS the real stream, so a direct write is both safe
+    //    and what §4.4.5 prescribes. OSC 52 emits no newline, so Ink's own line
+    //    accounting is untouched and there is nothing to invalidate;
+    //  * on a non-TTY there is no terminal to accept it, so the door is ABSENT.
+    //
+    // It must never be a function that accepts a chunk and writes NOWHERE.
+    // `copyText` reports `'osc52'` whenever its door took the text, so a silent
+    // no-op door — which `frameWriter?.writeForeign(chunk)` is under
+    // `--no-diff-render` — makes the toast name a mechanism that was never
+    // attempted. Naming the mechanism honestly is the entire reason that return
+    // value exists (R-7), and a door that lies is worse than no door.
+    const writeForeign = frameWriter
+        ? (text) => frameWriter.writeForeign(text)
+        : process.stdout.isTTY
+            ? (text) => {
+                try {
+                    process.stdout.write(text);
+                }
+                catch {
+                    // A closed or broken stdout must never turn a copy into a crash.
+                }
+            }
+            : null;
+    // --- The selection controller (§4.4). ------------------------------------
+    //
+    // BUILT AFTER `enterAltScreen` AND BEFORE `render()`. After, because it must
+    // not exist on a session that never asked the terminal to report motion;
+    // before, because `decorate` is read by the differ from the very first frame
+    // Ink produces.
+    //
+    // `mouseCaptured` is the run-time answer for `/mouse`, and it lives here rather
+    // than inside `screen.ts`'s closure because `App` needs to READ it and the
+    // handle's own flag is private (it has to be — `restore()` reads it, and
+    // exposing a setter would be a second way to get the two out of step).
+    let mouseCaptured = mouseFilter !== null;
+    if (wantSelect && mouseFilter) {
+        selectionBridge.controller = createSelectionController({
+            source: mouseFilter.source,
+            // The frame writer is absent under `--no-diff-render`, where there is no
+            // cache to repaint from at all; the controller then falls back to asking
+            // `App` for a React redraw on every drag flush, which is slower and
+            // correct. That is rung 2 of the fail-safe ladder doing its job.
+            repaint: () => frameWriter?.repaint() ?? false,
+            requestRedraw: () => selectionBridge.requestRedraw?.(),
+            // `?? undefined` and not a wrapper: `copyText` skips OSC 52 entirely when
+            // it has no door, and reports `'native'`/`'none'` accordingly.
+            copy: (text) => copyText(text, writeForeign ?? undefined),
+            onCopied: (via, lines, chars) => selectionBridge.onCopied?.(via, lines, chars),
+            // Read at PAINT time, not captured: `/theme` rebuilds the theme mid-session.
+            theme: () => getTheme(config.theme, detectCapabilities(process.env, process.stdout)),
+            caps: detectCapabilities(process.env, process.stdout),
+            cols: () => process.stdout.columns ?? 80,
+            // The STATIC half of the gate. The dynamic half — "no overlay is open" —
+            // belongs to `App`, which owns that state and calls `setEnabled`.
+            isSelectable: () => mouseCaptured,
+        });
+    }
+    const disposeSelection = () => {
+        selectionBridge.controller?.dispose();
+        selectionBridge.controller = null;
+    };
+    /**
+     * The terminal-facing services `App` cannot build for itself (§4.4).
+     *
+     * PRESENT IN INLINE MODE TOO, and only for the foreign-write door: §4.4.5
+     * routes `/copy` through `ui/clipboard.ts` precisely so it gains OSC 52 — the
+     * one mechanism that reaches the clipboard of the machine the USER is sitting
+     * at over SSH — and gating the whole bridge on full-screen would have handed
+     * that back only to full-screen users while the command is available in both.
+     * Every OTHER field stays absent there, so the inline tree is unchanged: there
+     * is no filter, hence no `setMouseCapture` and no `ctx.mouse`; `mouseSelect`
+     * is `wantSelect`, which is already false without one; and there is no
+     * controller, so no `selection`.
+     */
+    const terminalBridge = mode === 'fullscreen' || writeForeign
+        ? {
+            mouseSelect: wantSelect,
+            ...(mouseFilter
+                ? {
+                    setMouseCapture: (on) => {
+                        screen?.setMouseCapture(on);
+                        mouseCaptured = on;
+                        // A released mouse cannot be dragging, and a selection left
+                        // painted over a screen the terminal is now selecting on its
+                        // own would be two highlights claiming the same rows.
+                        if (!on)
+                            selectionBridge.controller?.clear();
+                    },
+                    isMouseCaptured: () => mouseCaptured,
+                }
+                : {}),
+            // The same door the controller copies through, so `/copy` and a
+            // drag-release can never disagree about which stream OSC 52 goes to.
+            ...(writeForeign ? { writeForeign } : {}),
+            ...(selectionBridge.controller ? { selection: selectionBridge } : {}),
+        }
+        : undefined;
     const updateBridge = { service: null, onAttach: null };
     let updateService = null;
     const updateEligible = !!process.stdout.isTTY &&
@@ -456,7 +688,7 @@ function runInteractive(flags, extras = {}) {
         // the same tree on every machine — reading `process.versions.node` from
         // a component would make the notice appear or vanish according to which
         // Node the developer happened to have installed.
-        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined }), 
+        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, terminal: terminalBridge }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -525,6 +757,11 @@ function runInteractive(flags, extras = {}) {
         .waitUntilExit()
         .then(() => {
         screen?.restore();
+        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // and after `restore()` for the reason that call records: the terminal must
+        // stop reporting first, and anything already in flight is still consumed by
+        // a live filter.
+        disposeSelection();
         disposeMouse();
         // BOTH BRANCHES, the same discipline `controller.dispose()` and
         // `updateService?.dispose()` already follow. It drops the `'resize'`
@@ -549,6 +786,11 @@ function runInteractive(flags, extras = {}) {
     })
         .catch(() => {
         screen?.restore();
+        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // and after `restore()` for the reason that call records: the terminal must
+        // stop reporting first, and anything already in flight is still consumed by
+        // a live filter.
+        disposeSelection();
         disposeMouse();
         disposeFrameWriter();
         controller.dispose();
@@ -665,6 +907,11 @@ const CONFIG_SET_KEYS = new Set([
     // falls through every case, writes nothing, and still prints
     // `Set mouse = false` (P1-2) -- exactly what happened to `density`/`hints`.
     'mouse',
+    // Both cased in the switch below, for the reason the note above `mouse`
+    // records: a key listed here but absent there writes nothing and still prints
+    // `Set mouseSelect = false`.
+    'mouseSelect',
+    'scrollResumeMs',
     'historyEnabled',
     'planModeDefault',
     'planModeMaxAskRounds',
@@ -691,6 +938,11 @@ const CONFIG_SET_KEYS = new Set([
     ...FAST_CONFIG_SET_KEYS,
     // `update.*` keys are handled by `applyUpdateConfigSet`, same reasoning again.
     ...UPDATE_CONFIG_SET_KEYS,
+    // `compaction.*` keys are handled by `applyCompactionConfigSet`, same
+    // reasoning again — and this set is what makes the kill switch reachable from
+    // a script at all: `config list` enumerates the section dynamically and so
+    // shows these keys whether they are here or not, while `config set` does not.
+    ...COMPACTION_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -777,6 +1029,18 @@ function runConfigSet(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.update[field])}\n`);
         return;
     }
+    const compactionPatch = applyCompactionConfigSet(key, value);
+    if (compactionPatch) {
+        // Echoed from the STORED value, so `config set compaction.threshold 0.2`
+        // prints the clamped 0.5 rather than reporting a number that was never
+        // written — the rule `team.*`, `retry.*`, `fast.*` and `update.*` each state
+        // above. It matters most for `warnThreshold`, which is clamped against the
+        // stored `threshold` and so can move for a reason the caller cannot see.
+        const merged = updatePersistedConfig(compactionPatch);
+        const field = key.slice('compaction.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.compaction[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -842,6 +1106,16 @@ function runConfigSet(key, value) {
         case 'mouse':
             patch.mouse = value === 'true' || value === '1';
             break;
+        case 'mouseSelect':
+            patch.mouseSelect = value === 'true' || value === '1';
+            break;
+        // Clamped rather than rejected, for the same reason `planModeDefault` below
+        // records: hardening only the READ path leaves a bad value on disk that
+        // reverts to the default on every launch, which presents as "my setting
+        // won't stick". `0` is a legal value here and its documented off switch.
+        case 'scrollResumeMs':
+            patch.scrollResumeMs = clampScrollResumeMs(value, DEFAULT_SCROLL_RESUME_MS);
+            break;
         // Turning this off stops new prompts being recorded; it does NOT delete
         // what is already in `prompt-history.jsonl` (that is `aragon history clear`).
         case 'historyEnabled':
@@ -1100,6 +1374,13 @@ function buildProgram() {
         // Positive form first, same tri-state reason as `--fullscreen` above.
         .option('--mouse', 'Wheel scrolls the transcript (full-screen mode)')
         .option('--no-mouse', 'Leave the mouse to the terminal (the wheel does nothing)')
+        // Positive form FIRST, for the tri-state reason `--fullscreen` records
+        // below: `mouseSelect` is 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 that passes no flag at all.
+        .option('--mouse-select', 'Drag with the mouse to select text; releasing copies it')
+        .option('--no-mouse-select', 'Keep wheel scrolling, but leave drag-select off')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
         // "no opinion" must stay distinguishable from "force it".
@@ -1156,6 +1437,16 @@ function buildProgram() {
         // feature that installs software would quietly un-set itself (C-11).
         .option('--update', 'Check for and install updates in the background (the default)')
         .option('--no-update', 'Disable auto-update for this session')
+        // BOTH FORMS, positive first, for the reason recorded eight times above —
+        // and this pair shares `--update`'s polarity, which is the worst one.
+        // `compaction.enabled` is PERSISTED and defaults to `true`, so a lone
+        // `--no-compaction` would make commander default `opts.compaction` to `true`
+        // and silently overwrite a stored `false` on EVERY run that passed no flag at
+        // all: the kill switch for a feature that spends the user's money on a
+        // summarizer would quietly un-set itself (C-13 / P1-5).
+        .option('--compaction', 'Compact the conversation when the context window fills (the default)')
+        .option('--no-compaction', 'Never compact; a full context window ends the run as before')
+        .option('--compaction-threshold <n>', 'Occupancy that triggers compaction for this run: 0.9 or 90% (0.5-0.95)')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')

package/dist/commands/builtins.js

@@ -3,10 +3,8 @@
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
  * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
-import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
-import process from 'node:process';
 import { resolveOutputTokens } from '@aragon-agent/core';
 import { clampThinkingLevel, clampTheme, isAdapterProvider, isThemeName, parseMaxTokensInput, ADAPTER_PROVIDERS, DEFAULT_MAX_TOKENS, HARD_MAX_RETRIES, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
 import { computeCost, formatCost, formatTokens } from '../agent/usage.js';
@@ -16,7 +14,9 @@ import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { getLogger } from '../logging/logger.js';
+import { copyText } from '../ui/clipboard.js';
 import { perfCommand } from './perf.js';
+import { runCompactCommand } from '../compaction/command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
  *
@@ -801,8 +801,21 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /retry [show|on|off|max <n>].`);
         },
     },
+    {
+        // REGISTRATION ONLY. The body lives in `compaction/command.ts` because this
+        // file is already past the 1000-line guideline and `/compact` has six forms
+        // plus the longest status report in the package (C-16 / P1-12).
+        name: 'compact',
+        description: 'Context compaction: status | on | off | threshold <n> | keep <n> | <instructions>',
+        run: (ctx) => runCompactCommand(ctx),
+    },
     {
         name: 'expand',
+        // DELIBERATELY LEFT TOOL-ONLY, and the asymmetry with Ctrl+O is a decision
+        // rather than an oversight (§6.3). Its description says "a recent tool card",
+        // it takes an N-from-last index over tool cards specifically, and widening it
+        // would change what `/expand 3` means for every existing user. Ctrl+O is the
+        // general expansion surface — that is where `'compaction'` was added.
         description: 'Expand / collapse a recent tool card (default: last)',
         run: (ctx) => {
             const toolEntries = ctx.state.entries.filter((e) => e.kind === 'tool');
@@ -942,8 +955,60 @@ const COMMANDS = [
                 ctx.notify('warn', 'No assistant message to copy.');
                 return;
             }
-            const ok = copyToClipboard(last.text);
-            ctx.toast(ok ? 'success' : 'warn', ok ? 'Copied to clipboard.' : 'Clipboard not available.');
+            // ROUTED THROUGH `ui/clipboard.ts` (§4.4.5). The duplicate spawn helper this
+            // command used to own is gone, and the command gained SSH support on the
+            // way: OSC 52 reaches the clipboard of the machine the USER is sitting at,
+            // which the local `pbcopy` never could.
+            //
+            // `ctx.writeForeign` and not `stdout.write` — see the field's comment.
+            const via = copyText(last.text, ctx.writeForeign);
+            if (via === 'none') {
+                ctx.toast('warn', 'Clipboard not available.');
+                return;
+            }
+            // NAMES THE MECHANISM RATHER THAN CLAIMING SUCCESS: neither path is
+            // detectable, and tmux without `set -g set-clipboard on` swallows OSC 52
+            // silently (R-7).
+            ctx.toast('success', via === 'osc52' ? 'Sent to the terminal clipboard.' : 'Sent to the system clipboard.');
+        },
+    },
+    {
+        name: 'mouse',
+        description: 'Release the mouse to the terminal, or take it back',
+        run: (ctx) => {
+            const port = ctx.mouse;
+            if (!port) {
+                // Inline mode, `--no-mouse`, a non-TTY, or a console that cannot deliver
+                // reports. Saying so beats pretending to toggle something that is not on.
+                ctx.notify('info', 'The mouse is not captured in this session, so there is nothing to release.');
+                return;
+            }
+            const arg = ctx.args.trim().toLowerCase();
+            if (arg === 'off') {
+                port.setCapture(false);
+                // NAMING THE COST IS THE HONEST THING TO DO, and it is one clause. The
+                // wheel goes INERT rather than back to scrolling: alternate scroll is
+                // saved and disabled alongside the capture, because otherwise every notch
+                // becomes a burst of arrow keys that `PromptInput` reads as prompt-history
+                // recall (I-10 / P1-1).
+                ctx.toast('info', 'Mouse released to the terminal - the wheel will not scroll. /mouse on gives it back.');
+                return;
+            }
+            if (arg === 'on') {
+                port.setCapture(true);
+                ctx.toast('info', 'Mouse captured - the wheel scrolls the transcript again.');
+                return;
+            }
+            const captured = port.captured();
+            const lines = [
+                `Mouse capture: ${captured ? 'on' : 'off'}`,
+                `  drag-select  ${port.selectEnabled() ? 'on' : 'off (mouseSelect is false)'}`,
+                '  /mouse off   hand the mouse to your terminal for this session',
+                '  /mouse on    take it back',
+                '  --no-mouse   never capture it (also ARAGON_MOUSE=0)',
+                '  aragon config set mouseSelect false   keep the wheel, drop drag-select',
+            ];
+            ctx.notify('info', lines.join('\n'));
         },
     },
     {
@@ -1006,22 +1071,7 @@ export const BUILTIN_COMMAND_NAMES = COMMANDS.flatMap((c) => [
     c.name,
     ...(c.aliases ?? []),
 ]).sort();
-/** Best-effort clipboard copy via the platform's clipboard CLI. */
-function copyToClipboard(text) {
-    const cmd = process.platform === 'win32'
-        ? { file: 'clip', args: [] }
-        : process.platform === 'darwin'
-            ? { file: 'pbcopy', args: [] }
-            : { file: 'xclip', args: ['-selection', 'clipboard'] };
-    try {
-        const child = spawn(cmd.file, cmd.args, { stdio: ['pipe', 'ignore', 'ignore'] });
-        child.on('error', () => {
-            /* swallow — clipboard is best-effort */
-        });
-        child.stdin?.end(text);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// The `copyToClipboard` helper that used to live here moved into
+// `ui/clipboard.ts` (tui-selection-and-scroll-follow §4.4.5), unchanged, so that
+// `/copy` and the drag-select release share ONE clipboard path instead of two
+// that can drift.

package/dist/commands/registry.d.ts

@@ -87,6 +87,33 @@ export interface CommandContext {
         effective: AgentMode;
         pending: AgentMode | null;
     };
+    /**
+     * Mouse capture, for `/mouse` (tui-selection-and-scroll-follow §6.2 / G3).
+     *
+     * OPTIONAL, and legitimately absent: inline mode, `--no-mouse`, a non-TTY, a
+     * Windows console that cannot deliver reports, and every test that builds this
+     * context by literal. `/mouse` has to have something honest to say when it is
+     * missing, which is the same reason `update` above it is optional.
+     */
+    mouse?: MouseCommandPort;
+    /**
+     * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
+     *
+     * NOT `process.stdout.write`. In full-screen mode stdout is a `Proxy` in front
+     * of the frame differ, and an unrecognised chunk there is counted as a foreign
+     * write and prints a diagnostic at the user the first time they copy anything
+     * (P1-6). Absent in inline mode and with `--no-diff-render`, where the real
+     * stream is handed over directly.
+     */
+    writeForeign?: (text: string) => void;
+}
+/** What `/mouse` can see and do. Read at command time, never captured. */
+export interface MouseCommandPort {
+    /** Whether the CLI is holding the mouse right now. */
+    captured(): boolean;
+    /** Whether drag-select is on for this session (`mouseSelect`). */
+    selectEnabled(): boolean;
+    setCapture(on: boolean): void;
 }
 export interface SlashCommand {
     name: string;