@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/ui/App.js

@@ -11,14 +11,15 @@ import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { initialViewState, reduceEvent, viewReducer, } from '../agent/reducer.js';
 import { mergeDeltas } from '../agent/coalesce.js';
 import { computeCost } from '../agent/usage.js';
+import { isApproximate } from '../compaction/pressure.js';
 import { parseMaxTokensInput, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from '../config/schema.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { appendPrompt, loadPromptHistory } from '../config/prompt-history.js';
-import { bumpSubmitCount, setMouseNoticeSeen, setVtInputNoticeSeen } from '../config/ui-state.js';
+import { bumpSubmitCount, setMouseNoticeVersion, setVtInputNoticeVersion, } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret } from '../logging/secret-registry.js';
 import { detectCapabilities } from './capabilities.js';
-import { useStartupNotices } from './use-startup-notices.js';
+import { useStartupNotices, MOUSE_NOTICE_VERSION, VT_INPUT_NOTICE_VERSION, } from './use-startup-notices.js';
 import { getTheme } from './theme.js';
 import { pickGlyphs } from './glyphs.js';
 import { Header } from './Header.js';
@@ -60,14 +61,15 @@ import { publishExitSnapshot } from './exit-snapshot.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
 import { helpRows } from './overlays/HelpOverlay.js';
 import { ModelPicker } from './overlays/ModelPicker.js';
-import { SettingsScreen, fastSettingsFrom, readFastSettings, } from './overlays/SettingsScreen.js';
+import { SettingsScreen, compactionSettingsFrom, fastSettingsFrom, readCompactionSettings, readFastSettings, } from './overlays/SettingsScreen.js';
 import { ConfirmDialog } from './overlays/ConfirmDialog.js';
 import { QuestionOverlay } from './overlays/QuestionOverlay.js';
 import { PlanReviewOverlay } from './overlays/PlanReviewOverlay.js';
 import { CommandRegistry, runSlashInput } from '../commands/registry.js';
 import { registerBuiltinCommands } from '../commands/builtins.js';
 import { makeSkillsCommand, registerSkillCommands } from '../commands/skills.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { MODE_LABEL, MODE_TOGGLE_KEYS, nextMode } from '../agent/agent-mode.js';
+import { emptyTailState } from './layout/follow-state.js';
 /**
  * Decide what the `Max tokens` field means, WITHOUT letting a bad value in it
  * discard the rest of the form.
@@ -110,7 +112,7 @@ export function resolveSettingsMaxTokens(raw, previous) {
 function seedViewState(thinkingVisible) {
     return initialViewState({ thinkingVisible });
 }
-export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, }) {
+export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, terminal, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const fullscreen = mode === 'fullscreen';
@@ -133,6 +135,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // function reference.
     const [state, dispatch] = useReducer(viewReducer, cfg.showThinking, seedViewState);
     const [elapsedMs, setElapsedMs] = useState(0);
+    /**
+     * Forces the render that re-reads `Date.now()` for the live compaction card
+     * while the run is IDLE (hardening W5). The value itself is never read - the
+     * card's elapsed figure is derived from `nowSec` like the running tool card's.
+     */
+    const [, setCompactionClock] = useState(0);
     const [confirmState, setConfirmState] = useState(null);
     /**
      * The updater's latest snapshot, or `null` while there is no service
@@ -152,6 +160,15 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const [scrollIntent, setScrollIntent] = useState();
     const [pinToBottomNonce, setPinToBottomNonce] = useState(0);
     const [scrolledLines, setScrolledLines] = useState(0);
+    /**
+     * True while a selection drag holds the viewport
+     * (tui-selection-and-scroll-follow §4.3.1 / §4.4).
+     *
+     * REACT STATE RATHER THAN A REF, because `ScrollViewport` has to re-arm its
+     * resume timer on both edges and a ref cannot drive an effect. The controller
+     * is the owner; this is a mirror, pushed by `onHoldChange`.
+     */
+    const [selectionHold, setSelectionHold] = useState(false);
     // I-5 (§4.13): Ctrl+L cannot repaint by writing escapes — Ink dedupes
     // identical output twice over — so it bumps this instead, and StatusBar turns
     // it into a one-byte, zero-width change that both dedupe gates let through.
@@ -211,6 +228,16 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
      * would make reading the render budget cost a render.
      */
     const mountedCount = useRef(0);
+    /**
+     * Rows the transcript has appended AT ITS TAIL — Rule A's only legal input
+     * (tui-selection-and-scroll-follow §4.3.1a).
+     *
+     * Owned here because it has TWO readers one level down each: `TranscriptList`
+     * writes it during its render, and `ScrollViewport` reads it in the layout
+     * effect that runs afterwards. A ref rather than state, exactly like
+     * `mountedCount` above and for the same reason.
+     */
+    const tailSink = useRef(emptyTailState());
     // --- Follow-through (todo-plan-followthrough §3.4). ---------------------
     //
     // THREE REFS AND NO VIEW STATE, DELIBERATELY (§5.2). Every field added to
@@ -604,6 +631,97 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             }
         });
     }, [controller]);
+    // --- Compaction event stream (context-auto-compaction §5.2). -------------
+    //
+    // A SIXTH SUBSCRIPTION, for the reason the team, todo and fast ones record:
+    // `CompactionEvent` is deliberately not a member of core's `AgentEvent` union,
+    // so it cannot arrive through `controller.subscribe`.
+    //
+    // AND IT IS THE **SOLE** DISPATCHER OF THE FIVE COMPACTION ACTIONS (D-20 /
+    // P1-6). `reduceEvent` gains no cases for core's `compaction_start` /
+    // `compaction_end` — its `default: return []` is already correct for them —
+    // because one compaction arriving through two channels is two transcript cards
+    // and a doubled `tokensReclaimed`, with nothing naming the authority. This
+    // stream is the right authority because it is strictly richer: the wiring IS
+    // the `ContextManager`, so it knows the summarizer's model, its cost and the
+    // session totals, and it learns `applied` by subscribing to the core event one
+    // layer earlier.
+    //
+    // `subscribeCompaction` returns a no-op unsubscribe when compaction was off at
+    // construction, so this can subscribe unconditionally and an ordinary session
+    // pays one closure for the whole run.
+    useEffect(() => {
+        // Seed the chip and the gauge marks from the snapshot resolved at
+        // construction, so a compaction-enabled session shows them on the FIRST
+        // frame rather than after the first turn.
+        if (controller.isCompactionRegistered()) {
+            dispatch({ type: 'compactionSnapshot', snapshot: controller.getCompactionSnapshot() });
+        }
+        return controller.subscribeCompaction((event) => {
+            switch (event.type) {
+                case 'compaction_start':
+                    dispatch({
+                        type: 'compactionStart',
+                        index: event.index,
+                        trigger: event.trigger,
+                        model: event.model,
+                    });
+                    break;
+                case 'compaction_end': {
+                    dispatch({ type: 'compactionEnd', record: event.record });
+                    // THE GAUGE MUST FALL IMMEDIATELY (§6.2 / AC-5), and it must fall to a
+                    // number in the SAME UNIT as the one it replaces (P1-11). The value
+                    // being overwritten came from `occupiedTokens(usage)` — a provider
+                    // measurement that includes the tool schemas — while
+                    // `record.tokensAfter` comes from core's `estimatePromptTokens`, which
+                    // never counts them. Writing the raw estimate makes the bar fall too
+                    // far and then visibly climb again on the next `turn_end` for no reason
+                    // the user can see, which is the same is-this-thing-working doubt the
+                    // immediate drop exists to prevent, one turn later.
+                    if (event.record.applied) {
+                        const offset = controller.getCompactionSnapshot().pressure.estimateOffset ?? 0;
+                        dispatch({ type: 'contextTokensEstimated', tokens: event.record.tokensAfter + offset });
+                    }
+                    break;
+                }
+                case 'usage': {
+                    // Compaction spend is REAL SPEND at the SUMMARIZER's price (§6.4 /
+                    // AC-15), which may be neither the lead's nor the fast tier's — so the
+                    // ref is ASKED FOR rather than assumed. `getModelInfo()` here would
+                    // price a Haiku summarization at the lead's Opus rates, which is the
+                    // same class of lie as the `$0.00` `pricingUnknown` exists to prevent,
+                    // just in the other direction.
+                    const snapshot = controller.getCompactionSnapshot();
+                    const ref = controller.getCompactionSummarizerRef();
+                    const costDelta = snapshot.pricingUnknown || !ref
+                        ? 0
+                        : computeCost(event.usage, controller.getModelInfoFor(ref).cost);
+                    dispatch({ type: 'compactionUsage', usage: event.usage, costDelta });
+                    break;
+                }
+                case 'snapshot':
+                    dispatch({ type: 'compactionSnapshot', snapshot: event.snapshot });
+                    // ONE NUMBER ON SCREEN AND IN THE TRIGGER (R-11 / hardening §3.2.4).
+                    // The checkpoint's occupancy is a measured base PLUS an estimate of
+                    // what was appended after it, and without this the gauge would still
+                    // show the bare base from the last `turn_end` - so a user watching
+                    // 76 % would see compaction fire and conclude the feature is broken.
+                    //
+                    // `contextTokensEstimated` IS REUSED RATHER THAN A SECOND WRITER ADDED:
+                    // it is the one existing action for "this figure is derived", and it
+                    // already sets the `~`. Gated on `isApproximate`, which is precisely
+                    // the case it was built for - a wholly measured figure belongs to
+                    // `turnEnd`.
+                    if (isApproximate(event.snapshot.pressure)) {
+                        dispatch({
+                            type: 'contextTokensEstimated',
+                            tokens: event.snapshot.pressure.occupied,
+                        });
+                    }
+                    break;
+            }
+        });
+    }, [controller]);
     // --- Live tool output (agent-activity-presentation-live §3.3.2). --------
     //
     // A FIFTH SUBSCRIPTION, and THE ONE THAT DOES GO THROUGH THE STREAMING
@@ -647,6 +765,17 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         const id = setInterval(() => setElapsedMs(Date.now() - startedAt), 200);
         return () => clearInterval(id);
     }, [state.status]);
+    // --- Live compaction elapsed tick (hardening §3.6 / W5). ---------------
+    //
+    // ONLY WHILE A CARD IS LIVE AND THE RUN IS NOT, so an ordinary session has no
+    // timer and an in-loop compaction reuses the 200 ms elapsed ticker rather than
+    // adding a second one. 1 Hz, because the card shows whole seconds.
+    useEffect(() => {
+        if (state.compactionEntryId === undefined || state.status === 'running')
+            return undefined;
+        const id = setInterval(() => setCompactionClock(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, [state.compactionEntryId, state.status]);
     // --- Retry countdown tick (llm-api-retry-backoff §6.5). ----------------
     //
     // ONLY WHILE A BACKOFF IS ACTUALLY WAITING, and the effect's teardown clears it —
@@ -697,9 +826,17 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // so on a console that reports nothing there is no source and no advice.
     useStartupNotices(dispatch, {
         enabled: !!mouseSource,
+        // NOT re-derived here (see `MouseNoticeOptions`): `cli.tsx` computes
+        // `mouseFilter !== null && cfg.mouseSelect` once and four things read it,
+        // so a second derivation is a second chance for them to disagree.
+        selectEnabled: terminal?.mouseSelect ?? false,
         // `state.json`, not `config.json`: whether a one-shot notice has been shown
         // is bookkeeping, and the comment on the old persisted key said so.
-        onSeen: () => setMouseNoticeSeen(true),
+        //
+        // THE VERSION, NOT `true` (P1-8). The gate compares against
+        // `MOUSE_NOTICE_VERSION`, so storing anything else either replays the
+        // notice forever or silences a future revision of the text.
+        onSeen: () => setMouseNoticeVersion(MOUSE_NOTICE_VERSION),
     }, 
     // Present only when `loadConfig` had to raise the user's own
     // `transcriptRetain` to `transcriptWindow` (tui-render-performance §5.1).
@@ -707,7 +844,10 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         ? { requested: cfg.transcriptRetainRequested, resolved: cfg.transcriptRetain }
         : undefined, 
     // Its own one-shot key, NOT `mouseNoticeSeen`: everyone this notice is for
-    // has already run aragon at least once and already has that flag set.
+    // has already run aragon at least once and already has that flag set. That
+    // key is now a VERSION for the same reason, one turn later — the audience
+    // for the text that finally names the fallback key is, again, exactly the
+    // set of users who already have the old flag on disk.
     //
     // `fullscreen` goes with it because only half of the damage is mode-
     // independent: `Shift+Tab` is broken either way, but inline never asked for
@@ -717,7 +857,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         ? {
             nodeVersion: vtInputWarning.nodeVersion,
             fullscreen,
-            onSeen: () => setVtInputNoticeSeen(true),
+            onSeen: () => setVtInputNoticeVersion(VT_INPUT_NOTICE_VERSION),
         }
         : undefined);
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
@@ -885,6 +1025,83 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // every render and defeat the ref guard's purpose rather than its mechanism.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [updateSnapshot?.phase, updateSnapshot?.latestVersion]);
+    // --- Selection (tui-selection-and-scroll-follow §4.4). -------------------
+    //
+    // The controller is built by `cli.tsx` before `render()`, so what it is
+    // missing when it starts is exactly the two things that only exist once this
+    // component is mounted: somewhere to put a toast, and a way to ask for a React
+    // redraw when the frame differ has no cache to repaint from. Both are assigned
+    // here and cleared on unmount, the same shape `updateBridge` uses.
+    const selectionBridge = terminal?.selection;
+    useEffect(() => {
+        if (!selectionBridge)
+            return undefined;
+        selectionBridge.onCopied = (via, lines, chars) => {
+            // IT NAMES THE MECHANISM RATHER THAN CLAIMING SUCCESS (R-7). Neither OSC 52
+            // nor a spawned `xclip` is detectable: tmux without `set -g set-clipboard
+            // on` swallows the first silently, and the second is best-effort by
+            // construction. A toast that said "copied successfully" would be guessing.
+            const noun = lines === 1 ? 'line' : 'lines';
+            if (via === 'none') {
+                toast('warn', 'Nothing could be copied - no clipboard mechanism is available.');
+                return;
+            }
+            const how = via === 'osc52' ? 'terminal clipboard' : 'system clipboard';
+            toast('success', `Sent ${lines} ${noun} (${chars} chars) to the ${how}.`);
+        };
+        // I-5 of `frame-differ.ts`: writing escapes here would be a foreign write.
+        // The nonce is the carrier Ctrl+L already uses (§4.13).
+        selectionBridge.requestRedraw = () => setRedrawNonce((n) => n + 1);
+        const unsubscribe = selectionBridge.controller?.onHoldChange(setSelectionHold);
+        return () => {
+            selectionBridge.onCopied = null;
+            selectionBridge.requestRedraw = null;
+            unsubscribe?.();
+        };
+        // `toast` is a stable dispatch wrapper; depending on it would rebuild this
+        // subscription on every render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [selectionBridge]);
+    const selectionController = selectionBridge?.controller ?? null;
+    /**
+     * I-9, the DERIVED half — and the one that matters (D-14 / P1-4).
+     *
+     * `shiftUp` changes exactly when the rows on screen move: a wheel notch, a key,
+     * PgDn, the bottom snap, `pinToBottomNonce`, the idle auto-resume, a height
+     * correction above the reading position. An enumerated list of gestures was
+     * already incomplete on the day it was written — it missed this feature's OWN
+     * auto-resume, which would have left a five-second-old highlight sitting over
+     * rows that had scrolled out from under it — and a derived condition cannot be
+     * forgotten by the next person who adds a way to move the viewport.
+     *
+     * Rule A holds `shiftUp` CONSTANT while a drag is in progress, which is why a
+     * selection survives output streaming in below it and only that.
+     *
+     * Referentially stable, because `ScrollViewport` publishes it from an effect
+     * keyed on the callback.
+     */
+    const onViewportShiftChange = useCallback(() => {
+        selectionController?.clear();
+    }, [selectionController]);
+    // I-9, the ENUMERATED half. `shiftUp` covers every movement of the rows and is
+    // wired straight into `ScrollViewport` below; these three are the cases that
+    // change the screen while leaving `shiftUp` untouched — a key that scrolls
+    // nothing, an overlay swap, and a re-wrap (P1-7).
+    useEffect(() => {
+        if (!selectionController)
+            return;
+        // Screen coordinates stop meaning anything the moment every line re-wraps,
+        // and a resize is exactly that (N6).
+        selectionController.clear();
+    }, [selectionController, rows, cols]);
+    useEffect(() => {
+        if (!selectionController)
+            return;
+        // An overlay replaces the viewport, so a selection over it would be a
+        // highlight over rows that are no longer there (N4).
+        selectionController.setEnabled(state.overlay === null);
+        selectionController.clear();
+    }, [selectionController, state.overlay]);
     const persistConfig = (patch) => {
         try {
             updatePersistedConfig(patch);
@@ -948,6 +1165,19 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // cache, and `/update` would report "disabled" on a session where it is on.
         // `?? undefined` because the bridge holds `null` and the port is optional.
         update: updateBridge?.service ?? undefined,
+        // Read at command time so `/mouse` reports the LIVE state rather than
+        // whatever it was when this closure was first built — `/mouse off` followed
+        // by a bare `/mouse` has to say "off".
+        ...(terminal?.setMouseCapture
+            ? {
+                mouse: {
+                    captured: () => terminal.isMouseCaptured?.() ?? true,
+                    selectEnabled: () => terminal.mouseSelect,
+                    setCapture: (on) => terminal.setMouseCapture?.(on),
+                },
+            }
+            : {}),
+        ...(terminal?.writeForeign ? { writeForeign: terminal.writeForeign } : {}),
     });
     /**
      * Submitting a prompt no longer touches `config.json` at all — it appends one
@@ -1076,6 +1306,23 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         const fastPatch = readFastSettings(values);
         controller.setFastConfig(fastPatch);
         patch.fast = fastPatch;
+        // --- Context compaction (context-auto-compaction §4.5) ------------------
+        //
+        // THE SAME SETTER-AND-PERSIST PAIR, and the same reason. `setCompactionConfig`
+        // additionally re-emits the snapshot, which is what moves the status chip and
+        // the gauge's marks without waiting for the next turn.
+        //
+        // `enabled` here flips the LIVE switch only. Whether the wiring exists at all
+        // was decided at construction and cannot be undone in this session (§3.2), so
+        // a user who turns it ON in a `--no-compaction` session gets the persisted
+        // value for next launch and nothing this session — which is exactly what
+        // `/compact on` reports in words.
+        const compactionPatch = readCompactionSettings(values);
+        controller.setCompactionConfig(compactionPatch);
+        if (compactionPatch.enabled !== undefined) {
+            controller.setCompactionEnabled(compactionPatch.enabled);
+        }
+        patch.compaction = compactionPatch;
         persistConfig(patch);
         getLogger().reconfigure({ ...controller.getConfig().log, level: values.logLevel });
         dispatch({ type: 'setOverlay', overlay: null });
@@ -1149,6 +1396,16 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     }, []);
     // --- Global keys -------------------------------------------------------
     useInput((input, key) => {
+        // I-9, the third clear trigger, and FIRST IN THE HANDLER so no `return`
+        // below can skip it. Any key at all drops the selection: most of them move
+        // the rows, and the ones that do not have still ended the gesture. It is
+        // also the way out of a `hold` that lost its release (I-11), alongside the
+        // watchdog.
+        //
+        // `Esc` IS DELIBERATELY NOT GIVEN A SECOND MEANING (§4.4.6). It aborts a
+        // run, and an emergency exit is the last key that should silently absorb a
+        // press; it clears the selection here like every other key and nothing more.
+        selectionController?.clear();
         if (key.ctrl && (input === 'c' || input === 'C')) {
             if (ctrlCArmed.current) {
                 doExit();
@@ -1196,7 +1453,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // AFTER the overlay block, and with an EXPLICIT guard rather than relying on
         // ordering: that block only `return`s for the keys it recognizes, and
         // everything else falls through (AC-P2).
-        if (key.tab && key.shift) {
+        //
+        // TWO KEYS, ONE BRANCH (shift-tab-mode-toggle-still-dead-on-windows, C2).
+        // `Ctrl+P` is not a Windows-only alias bolted on beside the real binding: it
+        // is the rung that survives when `Shift+Tab` cannot be delivered at all, and
+        // it shares this branch precisely so the two can never drift into different
+        // behaviour. See `MODE_TOGGLE_KEYS` for why this key and not another.
+        if ((key.tab && key.shift) || (key.ctrl && (input === 'p' || input === 'P'))) {
             if (stateRef.current.overlay)
                 return;
             applyMode(nextMode(controller.getAgentMode()));
@@ -1257,13 +1520,21 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // `team` joins `tool` here (team-subagents §6.3): a dispatch card collapses
             // its per-agent summaries behind the same key, and `toggleExpand` is keyed
             // on entry id so it needs no change.
+            // `compaction` joins `tool` and `team` here (context-auto-compaction §6.3 /
+            // C-15 / P1-8). `expandedToolIds` is keyed by entry id so the STORAGE was
+            // already generic — but both surfaces that CHOOSE a target filter by kind,
+            // and without this the compaction card renders its own `ctrl+o to expand`
+            // hint, the keystroke silently expands an older tool card instead, and
+            // nothing errors. AC-21 is the assertion that the hint does not lie.
             const last = [...stateRef.current.entries]
                 .reverse()
-                .find((e) => e.kind === 'tool' || e.kind === 'team');
+                .find((e) => e.kind === 'tool' || e.kind === 'team' || e.kind === 'compaction');
             if (last)
                 dispatch({ type: 'toggleExpand', id: last.id });
+            // WIDENED FROM `No tool output to expand.`: with three expandable kinds the
+            // old wording would be wrong in two of the three empty cases.
             else
-                toast('info', 'No tool output to expand.');
+                toast('info', 'Nothing to expand.');
             return;
         }
         if (key.escape) {
@@ -1323,6 +1594,10 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // every single turn, which is the one moment this feature exists to make feel
     // calm.
     const running = state.status === 'running';
+    // The live compaction card's clock (hardening W5). While the run is going the
+    // 200 ms elapsed ticker already causes the render that re-reads this; an IDLE
+    // `/compact` has no ticker at all, which is what `compactionClock` is for.
+    const compactionLive = state.compactionEntryId !== undefined;
     if (running && runStartedAt.current === 0)
         runStartedAt.current = Date.now();
     if (!running && runStartedAt.current !== 0)
@@ -1348,7 +1623,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // that re-reads it — so no timer is added (D-36 / E-15). Seconds rather than
     // milliseconds because `ToolCard` is `React.memo`'d with the default
     // comparator; `Transcript` passes it on only to running tool entries.
-    const nowSec = running ? Math.floor(Date.now() / 1000) : undefined;
+    const nowSec = running || compactionLive ? Math.floor(Date.now() / 1000) : undefined;
     // Row budget for the viewport and everything sized against it (§4.2a). The
     // inline path has no fixed frame, hence no height to fit into: `Infinity`
     // tells `OverlayFrame` to render everything and show no position indicator.
@@ -1416,6 +1691,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // The four fast rows, seeded through the pure mapper so the screen and
             // the save handler cannot disagree about what `(inherit)` means.
             ...fastSettingsFrom(cfg.fast),
+            ...compactionSettingsFrom(cfg.compaction),
         }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onSave: handleSettingsSave, 
         // Read from `cfg` (render scope, re-read every frame), so `/retry off`
         // while the screen is open shows the new value on the next paint.
@@ -1491,12 +1767,22 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         viewportRows: fullscreen ? viewportBudget : rows,
         offset: scrolledLines,
     };
-    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, cols: contentCols, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps, windowSize: transcriptWindow, cols: contentCols, heights: heights, mountedSink: mountedCount })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps }), overlayNode] }));
+    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, onViewportShiftChange: onViewportShiftChange, tailRowsRef: tailSink, hold: selectionHold, resumeMs: cfg.scrollResumeMs, showScrollIndicator: true, cols: contentCols, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps, windowSize: transcriptWindow, cols: contentCols, heights: heights, mountedSink: mountedCount, tailSink: tailSink })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps }), overlayNode] }));
     // The completion popup lives inside the bottom chrome and can add up to 9
     // rows; unbounded, it pushes the status bar past the frame height where
     // `overflow: hidden` clips it away (R-14 / M-14). Cap it against the viewport.
     const popupMaxRows = fullscreen ? Math.max(1, viewportBudget - 4) : undefined;
-    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, popupMaxRows: popupMaxRows, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
+    // WHICH KEY THE HINT ROW NAMES (shift-tab-mode-toggle-still-dead-on-windows,
+    // C3-1). Derived from `vtInputWarning` rather than from a probe of its own,
+    // because that prop is already the single answer to "can this console deliver
+    // `CSI Z`?" — `cli.tsx` computes it AFTER trying to force the bit on, so a
+    // machine we just repaired is told to press `shift+tab` and a machine we could
+    // not repair is told to press the key that provably survives.
+    //
+    // Both keys always WORK (they share one branch in the input handler); this
+    // only decides which one the user is taught.
+    const modeToggleKey = vtInputWarning ? MODE_TOGGLE_KEYS.fallback : MODE_TOGGLE_KEYS.primary;
+    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, modeToggleKey: modeToggleKey, popupMaxRows: popupMaxRows, scrolledLines: scrolledLines, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
     return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, header: header, viewport: viewport, team: state.team ? (_jsx(TeamPanel, { snapshot: state.team, rows: rows, cols: cols, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null, rail: showRail && state.todos ? (_jsx(TodoPanel, { snapshot: state.todos, width: railWidth, rows: railRows, running: running, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null, strip: showStrip && state.todos ? (_jsx(TodoStrip, { snapshot: state.todos, cols: cols, theme: theme, caps: caps })) : null, toast: _jsx(BottomStatusRow, { mode: mode, toasts: state.toasts, 
             // `!overlayNode` suppresses the line while an overlay owns the screen:
             // the full-screen branch replaces the whole viewport with the overlay,
@@ -1509,7 +1795,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // SIGNAL IS DERIVED FROM (D-4): inlining it here again is how the two
             // drift apart, and the drift is silent in whichever branch is not
             // edited.
-            activity: activityVisible ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, theme: theme, caps: caps })) : null, 
+            activity: activityVisible ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, 
+                // THE ROW MUST NEVER SAY SOMETHING FALSE (§6.1). Compaction runs
+                // BEFORE `turn_start`, so `status` is `'running'` with no tool in
+                // flight — precisely the window in which the rotating phrase
+                // would claim the model is thinking while it is actually waiting
+                // on a 30k-token summarization.
+                compacting: state.compaction?.inFlight === true, theme: theme, caps: caps })) : null, 
             // THE FORM THE LIFE SIGNAL TAKES WHEN A TOAST HAS THE ROW
             // (`activity-spinner-vanishes-behind-toast`). Passed UNCONDITIONALLY:
             // `BottomStatusRow` reads it only when `activity` above is non-null,
@@ -1529,7 +1821,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // branch replaces the whole viewport with the overlay, and an update
             // notice under a settings screen is noise attached to a surface it is
             // not visible on.
-            update: updateSnapshot && !overlayNode && shouldRenderUpdateLine(updateSnapshot) ? (_jsx(UpdateLine, { snapshot: updateSnapshot, compact: cols < UPDATE_LIMITS.statusCompactCols, theme: theme, caps: caps })) : null, theme: theme }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ecoRung: governor.rung, ...(state.team
+            update: updateSnapshot && !overlayNode && shouldRenderUpdateLine(updateSnapshot) ? (_jsx(UpdateLine, { snapshot: updateSnapshot, compact: cols < UPDATE_LIMITS.statusCompactCols, theme: theme, caps: caps })) : null, theme: theme }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, contextEstimated: state.contextTokensEstimated, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ecoRung: governor.rung, ...(state.team
                 ? {
                     teamActive: {
                         running: state.team.runs.filter((r) => r.phase !== 'queued' && r.phase !== 'done' &&
@@ -1539,7 +1831,15 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
                 }
                 : {}), ...(state.todos && !showRail
                 ? { todoActive: { done: state.todos.doneCount, total: state.todos.total } }
-                : {}), ...(state.fast?.live ? { fastActive: { inFlight: state.fast.inFlight } } : {}), ...(state.retry
+                : {}), ...(state.fast?.live ? { fastActive: { inFlight: state.fast.inFlight } } : {}), ...(state.compaction?.live
+                ? {
+                    compactionActive: { inFlight: state.compaction.inFlight },
+                    gaugeMarks: {
+                        warn: cfg.compaction.warnThreshold * 100,
+                        high: cfg.compaction.threshold * 100,
+                    },
+                }
+                : {}), ...(state.retry
                 ? {
                     retryActive: {
                         attempt: state.retry.attempt,

package/dist/ui/Composer.d.ts

@@ -34,10 +34,35 @@ export interface ComposerProps {
     hintsEnabled: boolean;
     /** Mirror of the controller's effective mode; drives the chip and the border. */
     agentMode: AgentMode;
+    /**
+     * Which key this hint should NAME for the mode toggle
+     * (shift-tab-mode-toggle-still-dead-on-windows, C3-1).
+     *
+     * A PROP RATHER THAN A CONSTANT because on some consoles the constant is a
+     * lie. This row used to render `shift+tab` unconditionally, with no link to
+     * the capability check three files away, so the machines where that key is
+     * swallowed were the ones being told to press it - permanently, on every
+     * frame, while the one warning they got scrolled out of the transcript
+     * minutes earlier (analysis section 3.7). Defaults to the primary key, which
+     * is what every unaffected machine renders.
+     */
+    modeToggleKey?: string;
     popupMaxRows?: number;
+    /**
+     * Rows of newer output below the viewport, forwarded to the input row's chip
+     * (tui-selection-and-scroll-follow §4.2 / G7).
+     *
+     * IT IS STATE, NOT A FADEABLE HINT, and it therefore does NOT pass through the
+     * `showHint` / `hintsEnabled` gate below. Those two govern the teaching row —
+     * which retires keys the user has demonstrably learned and is dropped outright
+     * on a short terminal — and "you are 12 rows behind the newest output" is
+     * neither learnable nor optional. Same argument that keeps `esc abort`
+     * un-faded in `hintText`.
+     */
+    scrolledLines?: number;
     theme: Theme;
     caps: TermCapabilities;
     onSubmit: (text: string) => void;
     onHelp?: () => void;
 }
-export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;
+export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, modeToggleKey, popupMaxRows, scrolledLines, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;

package/dist/ui/Composer.js

@@ -21,7 +21,7 @@ import { pickGlyphs } from './glyphs.js';
 import { HINT_FADE_AFTER } from '../config/schema.js';
 import { PromptInput } from './PromptInput.js';
 import { ModeChip } from './ModeChip.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { MODE_LABEL, MODE_TOGGLE_KEYS, nextMode } from '../agent/agent-mode.js';
 /**
  * Build the hint row.
  *
@@ -32,7 +32,7 @@ import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
  * Progressive disclosure is for teaching discoverable things, not for retiring
  * an emergency exit (§4.6 / A-14 / M-10b).
  */
-function hintText(running, submitCount, glyphs, mode) {
+function hintText(running, submitCount, glyphs, mode, toggleKey) {
     const dot = ` ${glyphs.midDot} `;
     if (running) {
         return [`${glyphs.enterKey} steer`, 'esc abort', `ctrl+c${glyphs.times}2 exit`].join(dot);
@@ -40,7 +40,7 @@ function hintText(running, submitCount, glyphs, mode) {
     // The hint names the DESTINATION, not the current state — the correct label
     // for a toggle affordance, and the reason the mode word here is the OPPOSITE
     // of the one on the chip beside it.
-    const toggle = `shift+tab ${MODE_LABEL[nextMode(mode)].toLowerCase()}`;
+    const toggle = `${toggleKey} ${MODE_LABEL[nextMode(mode)].toLowerCase()}`;
     // The faded form KEEPS the mode toggle. Progressive disclosure exists to
     // retire things the user has demonstrably learned, and `submitCount` counts
     // submissions — a user can send fifty messages without ever discovering
@@ -56,7 +56,7 @@ function hintText(running, submitCount, glyphs, mode) {
         '? help',
     ].join(dot);
 }
-export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }) {
+export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, modeToggleKey = MODE_TOGGLE_KEYS.primary, popupMaxRows, scrolledLines = 0, theme, caps, onSubmit, onHelp, }) {
     const [hasDraft, setHasDraft] = useState(false);
     const onDraftChange = useCallback((next) => setHasDraft(next), []);
     // Plan mode inserts ONE branch, above `draft` and below `running`. The
@@ -73,8 +73,8 @@ export function Composer({ isActive, running, history, commands, cwd, showHint,
                     : theme.idleBorder ?? theme.border;
     const glyphs = pickGlyphs(caps);
     const visible = showHint && hintsEnabled;
-    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange }), visible && (
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange, scrolledLines: scrolledLines }), visible && (
             // The chip rides the EXISTING hint row rather than adding one, so it
             // costs zero rows on a 24-row terminal.
-            _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode) })] }))] }));
+            _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode, modeToggleKey) })] }))] }));
 }