@aragon-agent/cli 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -5,6 +5,154 @@ All notable changes to `@aragon-agent/cli` are documented here. Entries at
 — those releases really were published under that name, so they are left as they
 were written.
 
+## Unreleased
+
+### Added
+
+- **Context compaction, hardened — the trigger now counts the whole history, the
+  recent turns can no longer wedge a run, sub-agents get the same protection, and
+  a compaction is no longer irreversible.**
+
+  **The trigger was systematically late.** It fired on the provider's reported
+  usage for the PREVIOUS request, read at a checkpoint that runs AFTER the current
+  turn's tool results were appended — and tool results are the largest single
+  increment in this loop (100 KB per call, several per turn, ~25 k tokens each).
+  A session reading 88 % could be sending 110 %. Occupancy is now the measured
+  base PLUS an estimate of everything appended since that measurement, and the
+  status gauge reads the same number the trigger does, on every turn — including
+  the turns where a guard declines to compact, which is exactly when the number
+  matters most.
+
+  **The recent turns can no longer wedge a run.** Every previous rung of the
+  ladder operated on the head of the conversation. When the RETAINED tail was what
+  did not fit, each rung reported success or "nothing to drop" while the history
+  stayed un-sendable and the run died. Oversized `tool_result` bodies inside the
+  retained turns are now clipped, oldest first, only when the alternative is a
+  request the provider cannot accept. Nothing is removed — no message, no
+  tool-call id, no role — so a valid history stays valid. Every clip is announced
+  in the text the model reads, at the exact place the data went, and on the card,
+  in `/compact status`, on the JSON stream and in the archive.
+
+  **Sub-agents compact their own history** (`compaction.subagents`, default
+  `true`). A `task` child is bounded by 24 turns and fifteen minutes, and when one
+  overflowed its entire history was discarded and the dispatch reached the lead as
+  one partial sentence. Children run under tighter bounds than the lead: two
+  retained turns, at most two compactions, the fast tier preferred, and failure
+  forced to truncate because nobody is watching a background worker. No transcript
+  card — the lead's transcript describes the lead's context. Set
+  `compaction.subagents: false` to restore the previous behaviour exactly.
+
+  **A compaction is no longer irreversible** (`compaction.archive`, default
+  `true`). The dropped messages are written verbatim to `~/.aragon/compaction/`
+  before the splice is adopted. `/compact history` lists this run's archives,
+  `/compact show <n>` prints one's metadata and summary — never message bodies.
+  The directory is shared by every `aragon` on the machine, so files carry a
+  per-process run id and retention is two-tier: 20 files per run by count, plus a
+  seven-day sweep across all runs, so one session can never prune a live
+  neighbour's work. Writing is best-effort: a failure is logged and never affects
+  the compaction. This is deliberately **not** undo — restoring an over-full
+  history restores the condition that triggered the compaction.
+
+  **The long moment is legible.** The live card counts elapsed seconds and says
+  `esc to cancel`, which `AgentController.abort()` has always made true and no
+  surface has ever stated. A compaction that could only clip says so and names no
+  model, because none was called.
+
+  Two new config keys (`compaction.subagents`, `compaction.archive`), two new
+  environment variables (`ARAGON_COMPACTION_SUBAGENTS`,
+  `ARAGON_COMPACTION_ARCHIVE`), two new `/compact` verbs (`history`, `show <n>`),
+  and two new settings-screen rows. No flags were added.
+
+- **Context compaction — a long run no longer dies when the window fills, and it
+  is ON by default.** A session's conversation only grows: nothing anywhere
+  removed a message, so a 40-turn tool-heavy run had exactly one ending available
+  to it once the context window filled — an HTTP 400 and a banner reading
+  *"Context length exceeded — start a new conversation with /reset."* The
+  product's answer to running out of context was "throw away everything you were
+  doing."
+
+  Now, at **90 %** occupancy, the run pauses at a turn boundary, hands the older
+  part of the history to a summarizer, and swaps it for a structured record. Your
+  original task stays **verbatim**, the most recent turns stay **verbatim**, and
+  the run continues in the same loop with the same tools, the same todo list and
+  the same working directory.
+
+  **This changes behaviour for existing users, in the direction of not dying.**
+  `--no-compaction`, or `compaction.enabled: false`, restores the old behaviour
+  exactly: no manager is constructed, nothing is subscribed, no registry is
+  allocated, and a full window ends the run as it did before. Both flag forms are
+  declared, so a stored `false` survives a run that passes no flags.
+
+  Three ways it fires. **Proactively** on measured occupancy — the case that
+  happens almost every time. **Reactively** when the provider returns
+  `context_overflow` anyway, because the model is not in the static window table
+  or you are pointed at a proxy in front of a smaller one: one compaction, one
+  re-send, run continues. And **manually**, via `/compact`, which runs
+  immediately when idle and queues to the next turn boundary when running.
+
+  The trigger has two terms. 90 % of a 200 k window leaves 20 k, which is plenty;
+  90 % of a 32 k window leaves 3.2 k, which is less than a single `max_tokens` of
+  8192 — the request is already impossible. So compaction also fires whenever the
+  remaining headroom drops below one full response.
+
+  **The default summarizer is your own model, and that costs real money.**
+  `compaction.useFastTier` is `true`, but it is a *preference*: the fast tier is
+  off unless you configured it, so out of the box the first compaction is a
+  ~30 k-token call on the session's own model. It happens at most 5 times per
+  run, the alternative is losing the run entirely, and the spend is visible — in
+  the session total, priced with the summarizer's own table, and reported as
+  `pricing unknown` rather than `$0.00` when that table has never seen the model.
+  Configure the fast tier to make it cheap.
+
+  Summarization fails sometimes. The ladder is one retry (on your **main** model
+  if the first attempt used the fast tier), then a **truncation** that says so on
+  the card, on the JSON event stream, and inside the block the model itself
+  reads. `compaction.onFailure: "stop"` makes the other trade.
+
+  Four guards stop it looping on your money: never two on consecutive turns,
+  never more than 5 per run, a progress requirement, and a self-disable after two
+  no-progress attempts with a notice naming the cause and the fix. The guards are
+  **trigger-aware** — the reactive path stays armed even after a self-disable,
+  because a compaction answering a request the provider has already refused is
+  the difference between a live run and a dead one.
+
+  Three UI surfaces: `Compacting context…` on the activity row while it runs, a
+  `compacting` chip plus threshold-aligned gauge colours as state, and a
+  transcript card with the before/after counts, the summarizer, the duration and
+  an expandable summary as the record. The gauge falls **immediately** rather
+  than waiting for the next turn. `/compact status` is the guaranteed surface at
+  any width.
+
+  New: `compaction` config section (6 keys), `--compaction` / `--no-compaction` /
+  `--compaction-threshold`, `ARAGON_COMPACTION*` (3 vars), `/compact` (6 forms),
+  three settings-screen rows, a `compaction` event on the `aragon exec` JSON
+  stream (`EXEC_SCHEMA_VERSION` **unchanged** — adding an event type never bumps
+  it), and two stderr lines under `-p`.
+
+### Changed
+
+- **The context gauge now counts cache tokens**, through the same
+  `occupiedTokens` the compaction trigger reads. Anthropic reports `input_tokens`
+  *excluding* cached tokens and puts them in two separate fields, so the old
+  `inputTokens + outputTokens` silently under-reported occupancy for anyone
+  behind a caching gateway. That was already a defect in the number on the status
+  bar; it becomes a much worse one the moment a trigger fires on a different
+  number from the one you are watching.
+
+- **`context_overflow` now names `/compact` alongside `/reset`.** That remedy
+  list was complete until this release, because throwing the conversation away
+  really was the only exit.
+
+### Known limitation
+
+- **A summarizer that is 90 % faithful will, eventually, drop something the run
+  needed,** and no amount of prompt engineering closes that. The design bounds it
+  — verbatim task, verbatim recent turns, a block that tells the model the record
+  is partial, and three surfaces that make it visible so a human can step in —
+  but it does not eliminate it. That is inherent to compaction as a technique, it
+  is the same trade Claude Code and Codex make, and it is preferable by a wide
+  margin to the previous behaviour, which was to lose the entire run.
+
 ## 0.6.0
 
 ### Added
@@ -84,6 +232,74 @@ were written.
 
 ## Unreleased
 
+### Added
+
+- **Drag the mouse to select text, and release to copy it.** Full-screen mode
+  takes the alternate screen, turns on mouse reporting so the wheel can scroll a
+  transcript the terminal no longer knows how to scroll, and draws every row
+  itself. Each of those is right on its own; together they took your terminal's
+  own drag-to-select away and put nothing in its place. The only thing shipped
+  in its place was a one-line notice naming a bypass key that is Shift on some
+  emulators, Fn on others and a preference elsewhere — a workaround, told once,
+  in a line that scrolls away.
+
+  Press the left button and drag: the cells you drag across are highlighted as
+  you go, and releasing copies exactly them. The copy goes out over **OSC 52**
+  first, so it reaches the clipboard of the machine you are *sitting at* rather
+  than the one you are ssh'd into, with the platform clipboard binary attempted
+  alongside it for terminals that ignore the sequence. Neither mechanism is
+  detectable, so the toast names what was sent rather than claiming a success it
+  cannot verify. `/copy` now goes through the same path and gained ssh support on
+  the way.
+
+  The highlight is painted in the frame pipeline rather than in React, so a drag
+  costs one to three re-addressed rows instead of a re-render of the whole tree,
+  and the text that is copied is read from the same mirrored rows the highlight
+  was painted over — what you see is what you get by construction, not by a
+  staleness check that can be wrong.
+
+  Two switches, both reversible without a restart: `/mouse off` hands the mouse
+  back to your terminal for the session (and says plainly that the wheel goes
+  inert while it is off), `/mouse on` takes it back, and
+  `aragon config set mouseSelect false` keeps wheel scrolling while leaving
+  drag-select off — which also stops the CLI asking the terminal for motion
+  reports at all, so that session puts exactly the bytes on the wire that it did
+  before this release. `--no-mouse` remains the switch that captures nothing.
+
+### Changed
+
+- **Scrolling up now actually stops the transcript.** The viewport followed the
+  newest output by holding a *fixed distance from the bottom*, so scrolling up
+  during a run did not pause anything: twelve new rows of output moved the
+  window twelve rows down, and whatever you had scrolled up to read slid off the
+  top while you were reading it. The faster the agent talked, the faster your
+  reading position ran away.
+
+  While you are scrolled up, the transcript is now anchored to the **content**:
+  new output accumulates below the window instead of dragging the window along
+  with it, and the rows on screen hold still. After five seconds with no
+  scrolling the viewport returns to the newest line by itself — but only if
+  something actually arrived while you were paused, so reading a *finished*
+  transcript is never interrupted by a jump to a bottom that has not moved.
+  Every gesture restarts the countdown, a selection drag suspends it, and
+  `aragon config set scrollResumeMs 0` turns the return off entirely
+  (`ARAGON_SCROLL_RESUME_MS` sets it too).
+
+  The number the hint shows means something sharper as a result: it is now
+  literally "rows of newer output below your reading position", which is what
+  `PgDn` traverses and what the status bar's `↑N` has always shown.
+
+- **The "N new lines · PgDn" hint moved inside the input box.** It used to be
+  rendered as the viewport's own last row, which spent a line of your transcript
+  on chrome at exactly the moment the transcript was longest — and, because the
+  hint's presence shrank the viewport, it fed back into the very number it was
+  displaying. It is now a right-aligned chip on the composer's input row, inside
+  the border, where it costs no rows at all. The chip sits in a fixed-width cell
+  so the number gaining a digit cannot re-wrap a draft, it never truncates (the
+  draft wraps first), and unlike the teaching row below the box it neither fades
+  with experience nor disappears on a short terminal: how far behind you are is
+  state, not a tutorial.
+
 ### Fixed
 
 - **The working spinner no longer disappears when an ack takes its row.** Steer a

package/README.md

@@ -14,10 +14,14 @@ steer / configure the session — all without leaving the terminal.
 
 Node **≥ 18**, any platform.
 
-**On Windows, `Shift+Tab` and the mouse wheel additionally need Node ≥ 22.17.0
-(or ≥ 24.2.0).** Everything else — the agent loop, every tool, skills, teams,
-`aragon -p` — works exactly the same on Node 18 and 20, which is why `engines`
-stays at `>=18` rather than locking those users out.
+**On Windows with Node < 22.17.0 (or 24.0/24.1), aragon turns the missing
+console flag on itself at startup**, which restores `Shift+Tab` on most
+machines. Where that is blocked — a locked-down PowerShell, an old console
+host — **`Ctrl+P` toggles the mode instead**; it is bound on every platform and
+does not depend on the console mode, the Node version, or anything else.
+Everything else — the agent loop, every tool, skills, teams, `aragon -p` — works
+exactly the same on Node 18 and 20, which is why `engines` stays at `>=18`
+rather than locking those users out.
 
 The reason is not the terminal emulator and not a setting: on Windows both
 `Shift+Tab` (`CSI Z`) and mouse reporting exist only while the console input
@@ -27,9 +31,14 @@ itself, and that translation has no entry for `Shift+Tab` (it arrives as a
 plain `Tab`) and discards mouse records outright. Node 20 is the current
 Windows default LTS, so this is a common configuration rather than an exotic
 one — it is why the same build behaves differently on two machines. Below that
-version aragon says so at startup and turns mouse reporting off rather than
-asking for reports that can never arrive; use `/plan` to switch mode and
-`Shift+↑` / `Shift+↓` to scroll until you upgrade.
+version aragon sets `ENABLE_VIRTUAL_TERMINAL_INPUT` itself, from a short
+PowerShell helper, right after it puts the console into raw mode — the flag is a
+property of the console, not of Node, so any process attached to it can turn it
+on. When that works, `Shift+Tab` arrives as `CSI Z` again and mouse reporting
+goes back on with it — the wheel should follow by the same route, though only
+the key has been measured. When it does not work, aragon says so at startup and
+turns mouse reporting off rather than asking for reports that can never arrive;
+`Ctrl+P` and `/plan` switch mode, and `Shift+↑` / `Shift+↓` scroll.
 
 ## Install
 
@@ -368,6 +377,8 @@ below works there too, in either position — `aragon --model m exec "…"` and
 | `--fast-model <id>` | The fast model id. Implies nothing about `--fast` on its own |
 | `--fast-provider <id>` | Provider for the fast model. Absent inherits the main provider |
 | `--fast-review <n\|off>` | Turns between automatic fast reviews, or `off` |
+| `--compaction` / `--no-compaction` | Compact the conversation when the context window fills, or never. **On** by default — see **Context compaction** |
+| `--compaction-threshold <n>` | Occupancy that triggers compaction for this run: `0.9` or `90%`, clamped to `[0.5, 0.95]` |
 | `--no-skills` | Disable the skill system entirely (no catalog, no skill tools) |
 | `--skill <name>` | Force-load a skill's full body for this run (repeatable) |
 | `--skills-yes` | Approve skill installs for this run (CI / headless) |
@@ -401,6 +412,7 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>\|delegate on\|off]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
+| `/compact [status\|on\|off\|threshold <n>\|keep <n>\|history\|show <n>\|<instructions>]` | Context compaction: occupancy and this session's totals, the on/off switch, when it fires, how much it keeps. With free text, compacts now and tells the summarizer what to pay attention to |
 | `/update [status\|now\|skip\|off]` | Auto-update: what is running, what is available, where it came from, when it looks again. `now` forces a check past the throttle; `skip` declines the offered version until a newer one appears |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
@@ -422,7 +434,8 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | --- | --- |
 | `Enter` | Submit (idle) / queue a steering message (running) |
 | `Alt+Enter` / `Shift+Enter` | Insert a newline |
-| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
+| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
+| `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Esc` | Abort the run / close an overlay / close a popup |
 | `Ctrl+C` ×2 | Exit (first press warns) |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
@@ -747,17 +760,28 @@ it is an informed act rather than a stray keypress.
 
 ### If `Shift+Tab` does nothing
 
-**On Windows, check your Node version first: `node -v`.** Below 22.17.0 (or on
-24.0/24.1) the key never reaches aragon as `Shift+Tab` at all — it arrives as an
-ordinary `Tab`, so it does not switch mode, and with the `/` palette or an `@`
-popup open it completes that entry over your draft instead. The mouse wheel is
-dead for the same reason. See [Requirements](#requirements); aragon reports this
-once at startup when it detects it.
+**Press `Ctrl+P`.** It is the same toggle and it does not depend on any of the
+machinery below.
 
-Otherwise: some multiplexers and remote-desktop stacks never send `CSI Z`.
-Either way `/plan`, `/plan on`, `/plan off` and `/plan status` are first-class
-equivalents, and `--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the
-startup case.
+To find out why, run this in the same terminal, press `Shift+Tab` once, then
+`Ctrl+C`:
+
+```powershell
+node -e "process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',b=>{console.log(b.toString('hex'));if(b[0]===3)process.exit(0)})"
+```
+
+| It prints | What it means |
+| --- | --- |
+| `09` | The console is swallowing the modifier — the key is arriving as an ordinary `Tab`. Check `node -v`: below 22.17.0 (or on 24.0/24.1) this is expected, and aragon's own attempt to fix it was blocked. See [Requirements](#requirements) |
+| `1b5b5a` | The key reaches the process fine, so something inside aragon is eating it — most often an overlay is open, or the run is still going and the switch is pending (the status bar shows `BUILD → PLAN`) |
+| nothing | Your terminal, multiplexer or remote-desktop stack never sent it; some never send `CSI Z` at all |
+
+On the first row the wheel is dead for the same reason, and with the `/` palette
+or an `@` popup open the stray `Tab` completes that entry over your draft.
+
+`/plan`, `/plan on`, `/plan off` and `/plan status` are first-class equivalents
+in every case, and `--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the
+startup case. `aragon doctor` reports this machine's answer as `vt-input`.
 
 ### Headless
 
@@ -1095,6 +1119,205 @@ it for a background advisory is how an unrequested call ends up competing with
 you for a rate-limited provider's quota. The review's own wall-clock bound is
 20 s.
 
+## Context compaction
+
+A long agentic run fills the model's context window. Before this existed, the
+only ending available to it at that point was an HTTP 400 and a banner telling
+you to start over — which threw away everything the run had done.
+
+Now the CLI **compacts** instead. When the conversation occupies **90 %** of the
+window, the run pauses at a turn boundary, hands the older part of the history to
+a summarizer, and swaps it for a structured record. Your original task stays
+**verbatim**, the most recent turns stay **verbatim**, and the run continues in
+the same loop with the same tools, the same todo list and the same working
+directory. Nothing about the session restarts.
+
+**It is on by default**, unlike every other optional subsystem here, and that is
+deliberate: the fast tier and team mode *add* behaviour you did not ask for,
+while this one *removes* a failure you did not ask for. `--no-compaction` or
+`compaction.enabled: false` restores the old behaviour exactly — no manager is
+constructed, nothing is subscribed, and a full window ends the run as it did
+before.
+
+### What actually happens
+
+1. **Proactively**, when measured occupancy crosses the threshold. This is the
+   case that fires almost every time.
+2. **Reactively**, when the provider returns `context_overflow` anyway — because
+   the model's context window is not in the static table, or you are pointed at a
+   proxy in front of a smaller model. One compaction, one re-send, run continues.
+   The engine allows exactly one of these per turn.
+3. **Manually**, with `/compact`. While the agent is idle it runs immediately;
+   while it is running it queues and fires at the next turn boundary.
+
+The trigger has **two** terms, and the second one is not belt-and-braces: 90 % of
+a 200 k window leaves 20 k, which is plenty, but 90 % of a 32 k window leaves
+3.2 k — less than a single `max_tokens` of 8192, so the request is already
+impossible. Compaction therefore also fires whenever the remaining headroom drops
+below one full response.
+
+### Which model summarizes, and what it costs
+
+**By default, your own model.** `compaction.useFastTier` is `true`, but it
+describes a *preference*: the fast tier only resolves when you have configured
+it, and it is off by default. So out of the box the first compaction is a
+~30 k-token call **on the session's own model** — real money on a frontier model,
+spent by a feature that is on by default.
+
+Three things make that the right trade rather than a hidden cost. It happens at
+most 5 times per run. The alternative is losing the entire run. And the spend is
+visible: it goes into the session total, it is priced with the *summarizer's* own
+table, and `/compact status` reports `pricing unknown` rather than `$0.00` when
+the model is not in that table.
+
+To make it cheap, configure the fast tier (`/fast on`, `/fast model <cheap-id>`).
+The transcript card then names the cheap model.
+
+### When it cannot summarize
+
+Summarization is a network call and it will sometimes fail. The ladder is: one
+retry — on your **main** model if the first attempt used the fast tier, because
+"a fast model that cannot summarize" is the likeliest single failure — and then,
+by default, a **truncation**: the same cut, the same verbatim task, and a block
+that says plainly that the dropped messages were not summarized. That is
+announced on the card, in the transcript, on the JSON event stream and inside the
+block the model itself reads.
+
+Truncation loses information, and it is still the default, because an unattended
+`aragon exec` that wedges on an unrecoverable 400 loses the whole run.
+`compaction.onFailure: "stop"` makes the other trade: the history is left alone,
+an error names your exits, and the next request will probably fail — which is
+what you asked for by setting it.
+
+### It will not loop on your money
+
+Four independent guards: never two compactions on consecutive turns, never more
+than 5 per run, a splice that does not project a real reclaim does not count as
+progress, and two consecutive no-progress compactions **switch the proactive
+trigger off for the session** with a notice naming the cause and the fix.
+
+The guards are trigger-aware. A *pressure* compaction that reclaims little has
+spent money to buy two turns and should stop. An *overflow* compaction that
+reclaims little is the difference between a live run and a dead one, because the
+provider has already refused the request — so the reactive path stays armed even
+after a self-disable, and an overflow attempt may halve `keepRecentTurns` for
+itself, which is the one lever that can make a too-large tail fit.
+
+### What you see
+
+Three surfaces, each answering something the others cannot:
+
+- **While it runs** — the activity row reads `Compacting context…`. It outranks
+  the tool name and the rotating phrase, because compaction happens between
+  turns and the phrase would otherwise claim the model is thinking. The
+  transcript card counts the seconds and tells you `esc to cancel`, which has
+  always been true and was never said.
+- **As state** — a `compacting` chip in the status bar, and the context gauge's
+  colours aligned to your own thresholds. The gauge **falls immediately** after a
+  compaction rather than waiting for the next turn, with a `~` while the value is
+  derived rather than measured.
+- **As a record** — a transcript card with the before/after message and token
+  counts, the summarizer, the duration, and the summary itself. `Ctrl+O` expands
+  it.
+
+**What a red gauge means:** the trigger is `>= threshold` while the red band is
+`> threshold`, so any occupancy that would paint red has already triggered
+compaction and the bar repaints downward in the same frame. Red is therefore only
+ever visible when compaction did **not** or **could not** run — it is off, it
+self-disabled, or the ladder ran out.
+
+`/compact status` is the guaranteed surface: the chip drops on a narrow terminal
+and the card scrolls away, but the command answers at any width, in any mode,
+after the fact.
+
+### When the RECENT turns are what does not fit
+
+Every rung above operates on the **head** of the conversation. When the retained
+tail is the problem — a few turns each carrying several 100 KB tool results —
+each of those rungs reports success or "nothing to drop" while the history stays
+un-sendable.
+
+The last rung clips oversized `tool_result` bodies **inside the retained turns**,
+oldest first, stopping the moment the request fits. Nothing is removed: no
+message, no tool-call id, no role — so a history that was structurally valid
+before is still valid after. Every clip is announced **in the text the model
+reads**, at the exact place the data went:
+
+```
+[... 214003 characters removed by context compaction ...]
+```
+
+A model that sees that knows the output is partial and can re-run the tool. It is
+also stated on the transcript card, in `/compact status`, on the JSON event
+stream and in the archive. When clipping is the **only** thing that happened, the
+card says so and names no model, because none was called.
+
+### Sub-agents get the same protection
+
+A `task` child is bounded by `team.maxTurnsPerSubagent` (24) and
+`team.dispatchTimeoutMs` (15 minutes) — the same profile as a lead run that fills
+a window. When a child overflowed, its history was discarded and the whole
+dispatch reached you as one partial sentence.
+
+Children now compact their own history, under tighter bounds: **two** retained
+turns instead of four, at most **two** compactions per child instead of five, the
+fast tier preferred whenever it resolves, and `onFailure` forced to `truncate`
+because nobody is watching a background worker. There is no transcript card for a
+child — the lead's transcript describes the lead's context. Turn it off with
+`compaction.subagents: false`.
+
+### A compaction is no longer irreversible
+
+Before a splice is adopted, the dropped messages are written verbatim to
+`~/.aragon/compaction/` — metadata, the summary, and the messages themselves.
+
+`/compact history` lists **this run's** archives, newest first, with the path of
+each. `/compact show <n>` prints one archive's metadata and its stored summary;
+it never prints message bodies, because a single archive can be megabytes and the
+transcript is not a pager. The directory is shared by every `aragon` on the
+machine, so files carry a per-process run id: another terminal's compactions are
+counted in one trailing line rather than listed as yours.
+
+Retention is two-tier and bounded: the newest 20 files **of this run**, plus a
+seven-day sweep across all runs. Writing is best-effort — a failure is logged and
+never affects the compaction. `compaction.archive: false` turns it off and writes
+nothing.
+
+This is **not undo**: restoring an over-full history restores the condition that
+triggered the compaction, and the next request fails. It is fidelity on disk, so
+"the summary was wrong and the agent proceeded on a false record" is something
+you can check rather than something you have to accept.
+
+### Configuration
+
+```jsonc
+{
+  "compaction": {
+    "enabled": true,          // false restores the pre-feature behaviour exactly
+    "threshold": 0.9,         // [0.5, 0.95]
+    "warnThreshold": 0.75,    // [0.4, threshold - 0.05]; where the gauge turns amber
+    "keepRecentTurns": 4,     // [1, 20] complete turns kept verbatim
+    "useFastTier": true,      // summarize with the fast tier WHEN it resolves
+    "onFailure": "truncate",  // or "stop"
+    "subagents": true,        // give `task` children their own compaction
+    "archive": true           // write the dropped messages to ~/.aragon/compaction
+  }
+}
+```
+
+Environment: `ARAGON_COMPACTION=0|1`, `ARAGON_COMPACTION_THRESHOLD`,
+`ARAGON_COMPACTION_KEEP_TURNS`, `ARAGON_COMPACTION_SUBAGENTS`,
+`ARAGON_COMPACTION_ARCHIVE`.
+
+### The part that cannot be fixed
+
+A summarizer that is 90 % faithful will, eventually, drop something the run
+needed. No amount of prompt engineering closes that. What this design does is
+bound it: your task is verbatim, the recent turns are verbatim, the block tells
+the model the record is partial, and three surfaces make it visible so you can
+step in. That is the same trade Claude Code and Codex make, and it is preferable
+by a wide margin to the alternative, which is losing the entire run.
+
 ## Skills
 
 A skill is a reusable expert procedure stored on disk: a directory containing a

package/dist/agent/agent-mode.d.ts

@@ -28,6 +28,45 @@ export declare const MODE_LABEL: Record<AgentMode, string>;
  * and nothing else. Two ship today (§1 non-goals).
  */
 export declare function nextMode(current: AgentMode): AgentMode;
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export declare const MODE_TOGGLE_KEYS: {
+    readonly primary: "shift+tab";
+    readonly fallback: "ctrl+p";
+};
 /** The two tools that only exist because a human is attached. */
 export declare const PLAN_TOOL_NAMES: readonly ["ask_user", "submit_plan"];
 /**

package/dist/agent/agent-mode.js

@@ -30,6 +30,42 @@ export function nextMode(current) {
     const index = AGENT_MODES.indexOf(current);
     return AGENT_MODES[(index + 1) % AGENT_MODES.length];
 }
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export const MODE_TOGGLE_KEYS = { primary: 'shift+tab', fallback: 'ctrl+p' };
 /** The two tools that only exist because a human is attached. */
 export const PLAN_TOOL_NAMES = ['ask_user', 'submit_plan'];
 /**