@aragon-agent/cli 0.6.3 → 0.6.7

package/CHANGELOG.md

@@ -9,6 +9,148 @@ were written.
 
 ### Added
 
+- **`system/init` now lists what this build can do.** A new optional
+  `capabilities: string[]` field, carrying `["interrupt"]` for this release.
+
+  A wrapper cannot tell by observation whether an interrupt will settle
+  gracefully or kill the process outright, and guessing wrong costs the user
+  their conversation. Rather than have callers compare version numbers — which
+  breaks on forks, prereleases, and version shapes nobody anticipated — the
+  build now says so itself, in an event that already arrives on every start.
+  Absent on older builds, and absence should be read as "no", never as
+  "probably".
+
+  Additive, so `schemaVersion` does not move. Consumers that do not know the
+  field ignore it, exactly as the schema contract asks.
+
+- **The composer understands pasting.** Until now it did not have the concept at
+  all: every byte the terminal delivered on stdin was a keystroke, and a
+  clipboard block is thousands of bytes arriving in an unpredictable number of
+  chunks. Three separate failures fell out of that one omission, and on Windows
+  you hit all three at once.
+
+  A carriage return that landed alone in a chunk **sent the half-finished
+  message** — a fifteen-line paste could arrive as a dozen separate messages,
+  interleaved with the agent's replies. A carriage return in the middle of a
+  chunk was inserted into the draft as a literal `\r`, which the terminal obeyed
+  by **overwriting the row it was drawn on**. And a paste that survived both grew
+  the composer to the height of the pasted text, pushing the transcript out of a
+  frame whose row accounting still believed the composer was three rows tall.
+
+  Pasting now works the way it reads:
+
+  - **A paste never submits.** Line breaks become buffer newlines, exactly one
+    per source line break, `CRLF` and lone `CR` alike.
+  - **A short paste appears verbatim.** At or below 6 lines and 400 characters it
+    is inserted as-is, indentation intact, and renders exactly like typed text.
+  - **A large paste collapses to a placeholder** — `[Pasted text #1 +218 lines]`
+    — which occupies one line, carries its own size in its label, deletes as a
+    single unit (one `Backspace`, and `Ctrl+W` / `Ctrl+U` / `Ctrl+K` cannot leave
+    half of one behind), and expands back to the full text the moment you send.
+    The model receives every byte; the composer never has to draw them.
+  - **No pasted byte is executed as a terminal control.** `\r`, `\x1b`, NUL, DEL
+    and the C1 range are stripped from the payload — never from your keystrokes,
+    so `Ctrl+A` and Escape are untouched.
+  - **The composer has a ceiling.** A draft of any length occupies at most 3 / 6 /
+    10 rows depending on terminal height, scrolls internally to keep the caret
+    visible, shows how many rows are hidden above and below, and reports its true
+    height to the layout budget. Four hundred presses of `Shift+Enter` were
+    already able to destroy the frame; they no longer are.
+  - **A submitted message cannot make the transcript unresponsive.** A user entry
+    renders at most 40 rows plus a `... +N more lines` tail. The full text is kept
+    and the exit transcript is uncapped.
+
+  On terminals that support it, detection is **exact**: aragon asks for bracketed
+  paste (`DECSET 2004`) in full-screen mode and reads the markers the terminal
+  wraps your paste in. Where that is unavailable — inline mode, an old Windows
+  console — a heuristic on chunk shape catches the same cases, and it needs no
+  cooperation from the terminal at all. Both feed one code path.
+
+  Turn it off with `--no-paste`, `ARAGON_PASTE=0`, or
+  `aragon config set paste false`; the input path is then byte-for-byte what
+  0.6.2 did.
+
+### Fixed
+
+- **`{"type":"interrupt"}` now really does settle the run — on every platform.**
+  The stdin interrupt frame used to raise a SIGINT at our own process. On POSIX
+  that reaches the runner's terminator and the run winds down properly: it
+  breaks out of the loop, persists the session, and emits `result` with the
+  usage and cost. On Windows, Node does not deliver a self-directed SIGINT to
+  its own handlers — the process simply terminated with exit code 1, having run
+  none of it.
+
+  For anyone using `aragon exec` interactively that difference was invisible,
+  because an interrupt there is usually the last thing that happens. It is not
+  invisible to a **wrapper** that interrupts a turn and then respawns on the same
+  `--session-id` to keep the conversation going: on Windows it silently got back
+  a session missing everything since the previous save. `exec/index.ts` has
+  carried a comment about that caller for some time ("PERSIST FIRST, ANNOUNCE
+  SECOND … a caller that reads `result` and immediately respawns with the same
+  `--session-id` must not race the writer"), so the intent was there; the path
+  just could not be reached on Windows.
+
+  The frame now calls the runner directly instead of going through a signal.
+  POSIX behaviour is byte-for-byte unchanged — the same code runs, with the same
+  `stopReason`, the same exit code 130, and the same two-second window in which a
+  second signal still forces an immediate exit.
+
+- **A pasted API key is stored correctly again.** Ink broadcasts each stdin chunk
+  to every mounted input handler, so the settings screen, the question overlay
+  and the plan-review feedback field all see what the composer sees. Without
+  this, a ~100-character key pasted into Settings would have been stored wrapped
+  in invisible framing bytes, masked on screen by the password dots, and would
+  have failed to authenticate on every request afterwards with nothing anywhere
+  explaining why.
+
+- **`--no-mouse` still writes no mouse sequence.** Paste support installs a
+  stdin filter, and `paste` defaults to on, so the filter now exists in sessions
+  that disabled the mouse. Whether the mouse is on is a separate question from
+  whether the stream is wrapped, and the four places that used to conflate them
+  now ask the right one: `aragon --no-mouse` writes no `?1000h`, no `?1006h` and
+  no `?1002h`, leaves your terminal's own click-drag selection alone, and reports
+  `/mouse` as off — while pasting still works.
+
+### Changed
+
+- **Auto-compaction no longer reports compactions that did not happen.** A long
+  unattended run used to print a red `context not compacted #2: nothing_to_drop`
+  card into the transcript. The card was accurate; nobody had asked for it.
+  Auto-compaction evaluates itself at every turn boundary, and a checkpoint that
+  looks at the history and finds nothing worth dropping has changed nothing,
+  called nothing and spent nothing — a smoke alarm announcing "no fire" twice an
+  hour, in error colours, with a machine reason attached.
+
+  A compaction now announces itself **if and only if it commits to doing work**.
+  That is a position in the control flow, not a list of reason strings: everything
+  decided before the first spend is silent, and everything decided after it —
+  including every failure, the truncation fallback, an Esc, and a host fault — is
+  as loud as it ever was. A declined `pressure` checkpoint is now
+  indistinguishable from a turn on which the threshold was never crossed.
+
+  **`/compact` and overflow recovery are unchanged.** A compaction you asked for
+  is owed an answer, and a reactive compaction running after the provider has
+  already refused your request is the one moment the diagnosis matters most. Both
+  still report on every outcome.
+
+  **Quiet, not unrecorded.** Every attempt is still written to the diagnostic log
+  (its `compaction` line gains an `announced` field, so `announced: false` is one
+  grep), still charged to the anti-loop guards, and still counted by
+  `/compact status` — which now reads
+  `This session: 1 compaction (2 checkpoints declined), 94.2k tokens reclaimed`
+  when checkpoints declined, and is byte-identical to before when none did. If
+  declines keep happening, the self-disable notice still says so out loud, once,
+  naming the cause and the remedies. Card numbers are also contiguous again: `#N`
+  counts compactions that ran, not checkpoints that fired.
+
+  **Behaviour change for wrapper scripts.** A declined `pressure` compaction no
+  longer emits a `{ type: 'compaction', subtype: 'start' | 'end' }` pair on the
+  `--output-format json` stream, and no longer prints `[compaction] skipped:` on
+  `-p` stderr. The pairs stay balanced, so only consumers counting *attempts* are
+  affected; the diagnostic log reports those more accurately.
+
+### 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.**

package/README.md

@@ -413,6 +413,8 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/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 |
+| `/context` | What the context gauge is showing: occupancy split into measured and estimated, the window and **where it came from**, how stale the measurement is, compaction's actual state, and what the session-spend readout includes |
+| `/bg [list\|logs <id> [n]\|stop <id\|all>\|status]` | Background services: what is running, its log tail, and how to stop it. `list` is the default |
 | `/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 |
@@ -437,10 +439,12 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `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) |
+| `Esc` ×2 | **Force-stop** a run that did not abort: kills the shell command it is blocked on and returns the view to `idle`. The second press only does anything while the run is *still* running, so in a healthy run it is a no-op |
+| `Ctrl+C` | Stop the background **services** the agent started, when there are any. It does not arm exit |
+| `Ctrl+C` ×2 | Exit (first press warns), once no services are running |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
 | `Ctrl+T` | Show / hide thinking (**off by default**). In inline mode it applies to the live entry and everything drawn after it — settled entries are already in your terminal's scrollback and cannot be repainted |
-| `Ctrl+O` | Expand / collapse the most recent tool card — including its diff |
+| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail |
 | `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
 | `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
 | Mouse wheel | Scroll the transcript (or the open overlay). On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
@@ -450,6 +454,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
 | `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
 | `Up` / `Down` | Move between draft lines; recall prompt history at the edges |
+| Paste | Inserted as-is up to 6 lines / 400 chars; larger collapses to `[Pasted text #1 +15 lines]`, which deletes as one unit and expands in full when you send. `--no-paste` restores the pre-0.6.3 behaviour |
 | `?` | Open help (empty input) |
 
 In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
@@ -795,7 +800,8 @@ ask — and the agent writes the finished plan as its final message in markdown.
 For work with three or more distinct steps the agent keeps a **visible plan**:
 it writes a checklist with the `todo_write` tool, marks exactly one item as in
 progress, and ticks it off before starting the next. In full-screen mode that
-list is rendered as a right-hand rail, about a fifth of the terminal wide.
+list is rendered as a right-hand rail, targeting 15% of the terminal width
+(14–36 columns, including its separator and padding).
 
 ```
   transcript ...                            | TODO             2/7
@@ -803,8 +809,7 @@ list is rendered as a right-hand rail, about a fifth of the terminal wide.
                                             |
                                             | v  1 Read the reducer
                                             | v  2 Design the store
-                                            | >  3 Wiring the rail into
-                                            |      AppShell
+                                            | >  3 Wiring the rail...
                                             | o  4 Add the panel-rows test
                                             | o  5 Update the README
                                             |      +2 more
@@ -828,7 +833,7 @@ not also tell the model may change it — except you, saying so:
   conversation has just been replaced.
 - A finished plan is dropped at the START of your next message, so you still get
   to see `7/7 done`. An unfinished one survives "continue" / "now do the rest",
-  and is dropped after three unrelated turns rather than holding a fifth of the
+  and is dropped after three unrelated turns rather than holding part of the
   screen for the rest of the session.
 
 ### When a run ends with steps left
@@ -884,11 +889,19 @@ planning discipline and hides the column — which is what you want with a scree
 reader, and what `--no-todo-panel` does for a whole session. Under `-p` the plan
 is written to stderr as `[todo] 3/7 <step>` lines, suppressed by `--quiet`.
 
-The rail is not mounted below 80 columns, while an overlay is open, in inline
-mode, or when the viewport is too short to say anything useful; the transcript
-keeps at least 62 columns at every width. In those cases the counter appears in
-the status bar instead, and the checklist is still written into the transcript
-as one card per turn.
+右栏从 76 列开始显示，正文至少保留 62 列；100 列终端使用 15 列右栏。
+已有任务时，团队面板按实际行数占用空间，补全菜单的边框和提示也计入预算。
+例如 100×20、团队占 8 行时，TODO 仍以 4 行紧凑视图显示。
+
+剩余 3–5 行时保留标题、完成计数、当前任务与合并提示 `-A +B`：
+`-9 +10` 表示上方隐藏 9 项、下方隐藏 10 项。6 行起使用常规视图；
+所有任务各占一行，全文仍可在正文任务卡片中查看。进度条需要至少 20 列、8 行。
+输入增长导致空间不足时团队先折叠为摘要；菜单不足 3 行时隐藏，其候选不会拦截输入。
+
+低于 76 列、共享区域不足 3 行、打开 overlay、显式关闭面板、没有任务或
+inline 模式时不显示右栏。低于 12 行使用原有小终端提示；扩大窗口后自动恢复。
+inline 仍使用上文的单行任务条。`/todo status` 中的 `Panel: on` 仅表示配置开启，
+实际可见性还取决于数据和窗口空间；可以通过该命令区分未生成计划与暂时隐藏。
 
 ## Built-in tools
 
@@ -908,6 +921,94 @@ delegation tool (see below). `--no-team` removes it again.
 With todo planning on — also the default — one more is added: `todo_write`, the
 planning tool (see above). `--no-todo` removes it again.
 
+With background services on — also the default — two more are added:
+`bash_output` and `bash_kill` (see below), and `bash` itself gains a `background`
+parameter. `bash.background: false` removes all three again.
+
+## Background services
+
+The agent can write a web app; it also has to be able to **run** one. A command
+that never exits on its own — `npm run dev`, `uvicorn main:app`, `vite`,
+`docker compose up`, `tsc --watch` — is not a hung tool, it is a server, and
+running it in the foreground stalls the turn until the tool timeout kills it
+three minutes later.
+
+So those commands are **supervised** instead. `bash` gains one optional
+parameter:
+
+```jsonc
+{ "command": "npm run dev", "background": true }
+```
+
+`true` supervises it, `false` never does, and **omitting it lets the runtime
+decide** from the command itself — a closed allowlist over the leading token and
+the script name (`npm|pnpm|yarn|bun run dev|start|serve|watch|preview`,
+`next dev`, `vite`, `nuxt dev`, `ng serve`, `nodemon`, `tsc --watch`, `uvicorn`,
+`gunicorn`, `flask run`, `manage.py runserver`, `rails server`, `php -S`,
+`cargo watch`, `docker compose up` without `-d`, `tail -f`, `watch `). It never
+fires on a chained command, because a chain's tail is what you actually wanted
+the result of, and `npm run build` and `npm test` are deliberately not on it.
+
+A supervised launch returns as soon as there is something true to say — the
+**first** of ready, exited, or four seconds — so a server that crashes on boot is
+reported in 400 ms with the stack in the result rather than after a three-minute
+stall:
+
+```
+$ npm run dev
+[background] service s1 started (pid 24188)
+[ready] http://localhost:3000  (detected from output after 1.4s)
+[log tail]
+  > next dev
+    - Local:  http://localhost:3000
+Read more with bash_output({ service: "s1" }); stop it with bash_kill({ service: "s1" }).
+```
+
+Readiness is a URL the server printed, or one TCP connect to a port the command
+named — and if that port was **already answering before the launch**, the probe
+is switched off and the card says so, rather than calling somebody else's server
+yours. A process that stays up without listening on anything (`tsc --watch`) is
+reported as `running`, which is the honest third answer.
+
+Each service gets a transcript card and a `svc N` chip in the status bar. Two
+tools read and stop them:
+
+- `bash_output({ service, since? })` — the log tail and the current status.
+  `since` is the cursor the previous call returned, so a watcher can be read
+  incrementally. The tail is a bounded in-memory ring of 200 rows; there are no
+  log files on disk.
+- `bash_kill({ service })` — stop one, or `"all"`.
+
+**Services do not survive the CLI.** Quitting, `Ctrl+C`, `SIGTERM` and a crash
+all reap the tree on a best-effort basis; there is no daemon, no PID file and no
+reattach across launches. A `SIGKILL` of aragon itself is unrecoverable by
+construction, and if a stop cannot confirm the process is gone it says
+`may have left a detached child` rather than claiming success.
+
+From your side there are two keys and one command: `Ctrl+C` stops every live
+service (and does *not* arm exit), `/bg` lists them, and `/bg logs s1` prints a
+tail without going through the model.
+
+### Turning it off
+
+```jsonc
+// ~/.aragon/config.json
+{ "bash": { "background": false } }
+```
+
+`ARAGON_BASH_BACKGROUND=0` does the same for one run;
+`ARAGON_BASH_AUTO_BACKGROUND=0` keeps the tools but stops the classifier firing
+on a command that did not ask. With `background: false` the build behaves exactly
+as it did before this feature existed — no `background` parameter, no extra
+tools, no prompt block, no chip.
+
+Two things are **not** governed by that switch, because they are fixes rather
+than features. `bash` now always settles: it returns when the process exits
+rather than when its output stream closes, so a command that detaches a
+grandchild can no longer leave the turn pending forever, and it is handed a
+closed stdin so a command that prompts fails instead of blocking on a read
+nobody will answer. And `Esc` twice always force-stops, whatever the flag says.
+
 ## Team subagents
 
 The agent can hand parts of a job to short-lived **subagents** that run in
@@ -1119,6 +1220,84 @@ 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.
 
+## The context gauge
+
+The right end of the status bar answers one question: **how full is the context,
+out of how much.**
+
+```
+[####----] 43%  86.0k/200.0k   total 1.2M^ 48.0k v   $3.21   12 tok/s  1m02s
+            ^        ^         ^
+            |        |         +-- session spend, prompt side / output side
+            |        +-- occupied / window
+            +-- the two together, as a percentage
+```
+
+The readouts drop as the terminal narrows, in that order of priority:
+
+| Columns | Right cluster |
+|---|---|
+| >= 96 | `[####----] 43%  86.0k/200.0k  total 1.2M^ 48.0k v  $3.21` |
+| 72-95 | `[####----] 43%  86.0k/200.0k  $3.21` |
+| 60-71 | `[####----] 43%  $3.21` |
+| < 60 | `43%  $3.21` |
+
+**Two different markers, because there are two different things to doubt.**
+
+- `~` sits on the **percentage** and means the *numerator* is partly a guess:
+  either no completed turn has reported usage yet (right after `/resume`, or
+  right after a compaction), or tool results have been appended since the last
+  measurement and their size is estimated.
+- `?` sits on the **window** and means the *denominator* is a guess: the model is
+  not in the built-in table, so a flat 128 000 was substituted. See
+  `contextWindow` below.
+
+**The percentage keeps moving during a turn.** Every tool result nudges it,
+whether or not compaction is enabled — it is not a compaction feature, and a
+session started with `--no-compaction` gets the same live reading. After
+`/resume` the gauge shows the restored session's real occupancy immediately,
+without sending anything.
+
+### `/context`
+
+The gauge is a bar and a rounded percentage; `/context` is the full answer, at
+any width, in any mode:
+
+```
+Context
+  Occupancy      43%   86.2k of 200.0k   [measured 85.1k + 1.1k estimated]
+  Window         200000   from the model table
+  Since measured 1.1k estimated tokens appended since the last provider-reported usage
+  Compaction     on - triggers at 90% (amber at 75%), 2 this session, 118.0k reclaimed
+  Session spend  1.2M in (incl. 940.0k cache read, 12.0k cache write) / 48.2k out, $3.21
+                 includes subagent, fast-tier and compaction spend,
+                 not just this conversation
+```
+
+Two lines are worth reading closely. **`Window`** always names where the number
+came from — the model table, your own `contextWindow`, or the invented
+placeholder — because those are indistinguishable everywhere else. And
+**`Compaction`** reports what is actually true of this session, including
+`off - not registered for this session (started with --no-compaction)`; it never
+promises a threshold that nothing will act on.
+
+### `contextWindow`
+
+When the model is not in the built-in table — a custom `baseUrl`, a self-hosted
+id, something released last week — the denominator is a **fabricated** 128 000
+and the percentage is meaningless. Correct it:
+
+```bash
+aragon config set contextWindow 1000000   # persisted; prints "Set contextWindow = 1000000"
+aragon config set contextWindow auto      # back to the model table / placeholder
+ARAGON_CONTEXT_WINDOW=1000000 aragon      # one session
+```
+
+Values are clamped to `[8000, 5000000]`; `auto` (the default) is stored as
+`null`. Setting it removes the `?` marker, because you have asserted the number —
+and `/context` still shows that it came from you, which is what makes a wrong
+value findable.
+
 ## Context compaction
 
 A long agentic run fills the model's context window. Before this existed, the
@@ -1215,7 +1394,10 @@ Three surfaces, each answering something the others cannot:
 - **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.
+  derived rather than measured. The colours follow your configured thresholds
+  whenever compaction is **enabled**, even if no summarizer model currently
+  resolves; after `/compact off` they fall back to the generic 60 / 85, because
+  colouring by a rescue that is not coming is worse than not colouring at all.
 - **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.
@@ -1228,7 +1410,9 @@ 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.
+after the fact. For the gauge specifically, [`/context`](#the-context-gauge) is
+the equivalent — and it works in a session that never registered compaction at
+all.
 
 ### When the RECENT turns are what does not fit
 
@@ -1609,6 +1793,8 @@ env / `.env` → CLI flags**.
   reasoning blocks), `ARAGON_LIVE_TOOL_OUTPUT` (`0` keeps a running tool card to
   one line),
   `ARAGON_MAX_TOKENS` (a number, or `auto` / `0` for the per-model ceiling),
+  `ARAGON_CONTEXT_WINDOW` (a number, or `auto`; the denominator the context
+  gauge measures against),
   `ARAGON_THEME`,
   `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
   `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
@@ -1636,6 +1822,7 @@ env / `.env` → CLI flags**.
 | Config key | Default | Meaning |
 | --- | --- | --- |
 | `maxTokens` | `64000` | Output token cap, clamped to `[256, 200000]`. `null` means **auto** — use each model's own ceiling, never above 64000. Absent means the default. See [Output token limits](#output-token-limits). |
+| `contextWindow` | `null` | The window the context gauge measures against, clamped to `[8000, 5000000]`. `null` means **auto** — the built-in model table, or a fabricated 128000 for a model it has never seen. Set it when the gauge shows `?` on the denominator. See [The context gauge](#the-context-gauge). |
 | `showThinking` | `false` | Draw the reasoning the model returns. `thinkingLevel` is the effort the provider is asked to **spend**; this is whether the terminal **shows** it. Off by default: a settled turn that thought leaves one muted `thought for 12s` row in its place, so nothing is hidden silently. |
 | `liveToolOutput` | `true` | Draw up to eight sanitised rows of a **running** tool's output on its card, plus a `no output for Ns` row when the child goes quiet. On by default, unlike `showThinking`: this ADDS the information a long `bash` call otherwise hides, and its cost is bounded by construction — eight rows per call, sixteen calls, whatever the command emits. Turn it off and the card is a single `running` row again, with no store allocated and no recorder attached. |
 | `fullscreen` | `true` | Use the full-screen TUI (still subject to the automatic downgrades). Setting it to `false` opts out permanently; leaving it `true` is *not* a force — only `--fullscreen` / `ARAGON_FULLSCREEN=1` override the heuristics. |
@@ -1647,6 +1834,7 @@ env / `.env` → CLI flags**.
 | `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
 | `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
 | `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
+| `paste` | `true` | Recognise pasted text before Ink's key parser sees it: line breaks become buffer newlines instead of fifteen separate messages, control bytes are stripped instead of overwriting the row they land on, and a paste above 6 lines or 400 characters collapses to a one-line placeholder that expands when you send. `false` treats pasted bytes as keystrokes, which is what 0.6.2 did. |
 | `historyEnabled` | `true` | Record submitted prompts to `prompt-history.jsonl` for `↑` recall. Setting it to `false` stops new writes; it does not delete what is already stored (that is `aragon history clear --yes`) and does not stop reading. See [Prompt history](#prompt-history). |
 | `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
 | `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |
@@ -1712,6 +1900,8 @@ ARAGON_MAX_TOKENS=32000 aragon       # env layer, between the flag and the file
 aragon config set maxTokens 32000    # persisted; prints "Set maxTokens = 32000"
 aragon config set maxTokens auto     # persisted as null
 aragon config set maxTokens default  # back to 64000
+aragon config set contextWindow 1000000  # the gauge's denominator
+aragon config set contextWindow auto     # back to the model table
 aragon config get maxTokens          # "64000" | "auto"
 ```
 

package/dist/agent/controller.d.ts

@@ -15,9 +15,12 @@ import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
+import { ProcSupervisor } from '../proc/supervisor.js';
+import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
-import type { FastEventListener } from '../fast/types.js';
-import type { CompactionEventListener, CompactionSnapshot } from '../compaction/types.js';
+import type { FastEventListener, FastSnapshot } from '../fast/types.js';
+import { ContextMeter, type ContextUsageListener } from '../compaction/meter.js';
+import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
@@ -176,6 +179,34 @@ export declare class AgentController {
     private readonly outputListeners;
     private readonly fast;
     private readonly compaction;
+    private readonly contextMeter;
+    private readonly procs;
+    /**
+     * The host's notice channel, kept so `prompt()`'s totality has somewhere to
+     * report to (I-8). Every other consumer reads `deps.notify` through a closure
+     * built in the constructor; this one is called from a method, which is why it
+     * needs a field.
+     */
+    private readonly notifyHostFn;
+    /** Whether the SERVICE half is on: tools, prompt block, `background` param. */
+    private readonly bashBackgroundRegistered;
+    /** Release the exit reaper. Called by `dispose()`. */
+    private readonly releaseSignalHook;
+    /**
+     * Bumped by `forceStop()`; captured by `App` when it subscribes to a run.
+     *
+     * THE VIEW AND THE ENGINE DELIBERATELY DISAGREE AFTER A FORCE-STOP (D-10 /
+     * I-7). Rung two dispatches `runEnd` locally so the composer is usable
+     * immediately, but the engine keeps unwinding and keeps EMITTING -
+     * `turn_start`, `tool_call_start`, `turn_end`, `agent_end` - and
+     * `runStart`/`turnStart` would set `status: 'running'` again, bouncing the
+     * view straight back out of the `idle` the user was just given and appending
+     * entries to a transcript they believe is finished. `App` drops every event
+     * whose generation is stale, which is the same shape as `abortRequested`
+     * above and exists for the same reason: the loop legitimately emits after an
+     * abort lands.
+     */
+    private runGen;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -234,7 +265,97 @@ export declare class AgentController {
      * never rejects, so callers must not treat resolution as success.
      */
     prompt(text: string): Promise<void>;
+    /**
+     * Wait for the engine to unwind, bounded.
+     *
+     * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
+     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * alone would hang here for as long as it hangs there. The budget is the two
+     * graces a wedged `bash` can legitimately spend, plus the executor's own.
+     */
+    private waitForEngineIdle;
+    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    private startPrompt;
     abort(): void;
+    /**
+     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * (§3.6 / G3).
+     *
+     * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
+     *
+     *   1. `abort()` - everything it does today, unchanged.
+     *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
+     *      child. THIS is what actually unblocks a wedged `await tool.execute`;
+     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      precisely the tools that ignore it.
+     *   3. `runGen += 1` - so `App` can drop the events the engine will keep
+     *      emitting while it unwinds (I-7). Without it the view bounces straight
+     *      back out of the `idle` the user was just given.
+     *   4. IT DOES NOT TOUCH BACKGROUND SERVICES. `Esc` interrupts the AGENT;
+     *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
+     *      sentences and it is exactly the kind of thing a later reader will
+     *      "fix" by making this kill everything - which would mean a user who
+     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      had been working against for an hour. It is invariant I-4.
+     *
+     * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
+     * constructed; with services off its foreground registry is all there is, and
+     * that is the half this method uses.
+     */
+    forceStop(): void;
+    /**
+     * The current run generation (I-7).
+     *
+     * `App` captures it when it subscribes to a run and drops every engine event
+     * whose generation is stale. Same shape as the `abortRequested` guard the fast
+     * reviewer already uses, and for the same reason: the loop legitimately emits
+     * after an abort lands.
+     */
+    get runGeneration(): number;
+    /** Whether `bash_output` / `bash_kill` are in `this.tools`. Fixed at construction. */
+    isBackgroundRegistered(): boolean;
+    /**
+     * Subscribe to the CLI-local `ProcEvent` stream.
+     *
+     * Returns a live unsubscribe even when services are off, because the
+     * supervisor exists either way - the contract `subscribeTeam` /
+     * `subscribeTodos` / `subscribeFast` / `subscribeToolOutput` already set. With
+     * services off nothing is ever emitted, so an unconditional subscription in
+     * `App` costs one `Set` entry.
+     */
+    subscribeProc(listener: ProcEventListener): () => void;
+    getServiceSnapshot(id: string): ServiceSnapshot | undefined;
+    listServices(): ServiceSnapshot[];
+    /** `starting | ready | running`. Drives the status chip and the Ctrl+C rung. */
+    liveServiceCount(): number;
+    readServiceLog(id: string, since?: number): ReturnType<ProcSupervisor['read']>;
+    /**
+     * Stop one service, or every service when `id` is `'all'`.
+     *
+     * The GRACEFUL ladder (`SIGTERM` -> `SIGKILL` after `stopGraceMs`), because
+     * this path has a live event loop to run it on. `reapServicesSync` is the
+     * other one, and it is the only one an exit path may use.
+     */
+    stopService(id: string): Promise<ServiceSnapshot[]>;
+    /**
+     * Rung one of `Ctrl+C`: stop every live service (§3.6 / G4).
+     *
+     * `force: true` means `reapSync()` SEMANTICS - immediate `SIGKILL`, no
+     * `stopGraceMs` - and is what `doExit` uses, because `doExit` awaits nothing
+     * and must not start (§3.6 step 3). The graceful ladder belongs to `Ctrl+C`,
+     * `bash_kill` and `/bg stop`.
+     */
+    stopAllServices(opts?: {
+        force?: boolean;
+    }): Promise<ServiceSnapshot[]>;
+    /**
+     * The synchronous reaper (I-9).
+     *
+     * Exposed so `doExit` can call it without awaiting anything. It is also what
+     * the signal hook registered in the constructor calls, and it is idempotent -
+     * which it has to be, since a normal quit reaches it twice.
+     */
+    reapServicesSync(): void;
     steer(text: string): void;
     followUp(text: string): void;
     isRunning(): boolean;
@@ -493,6 +614,41 @@ export declare class AgentController {
      * `subscribeTodos` already set.
      */
     subscribeFast(listener: FastEventListener): () => void;
+    /**
+     * The FIFTH thin forwarder: the current fast-tier snapshot, or `null` when
+     * this session never registered a tier at all
+     * (web-use-tier-cooperation-and-control-closure §4.2.1).
+     *
+     * `null` and "a snapshot with `live: false`" are different answers and callers
+     * depend on the difference: the first means "there is no tier here", the
+     * second means "there is one and it is not usable right now".
+     *
+     * Deliberately NOT folded into the existing `review_end` event: that shape is
+     * consumed by `App` too, and this round promised to be purely additive.
+     */
+    fastSnapshot(): FastSnapshot | null;
+    /**
+     * Subscribe to occupancy publications. Returns an unsubscribe function.
+     *
+     * THE SOLE UPSTREAM OF `ViewState.context` (I-1). The gauge used to have two
+     * writers - `turnEnd` and a `contextTokensEstimated` dispatch fired from two
+     * places in `App` - which is the entire cause of P0-1: both wrote in the same
+     * synchronous fan-out and the second one won, restoring the pre-compaction
+     * figure one statement after the bar had correctly fallen. One writer makes
+     * that class of bug unrepresentable rather than merely fixed.
+     */
+    subscribeContextUsage(listener: ContextUsageListener): () => void;
+    /**
+     * Occupancy right now, re-measuring if the history has moved.
+     *
+     * `/context` READS THIS AND NOT `getCompactionSnapshot().pressure` (RV-8). The
+     * latter returns `offCompactionSnapshot()`'s hardcoded zero pressure when
+     * compaction was never registered, so a report built on it would read 0 % for
+     * precisely the sessions this feature exists to fix.
+     */
+    getContextUsage(): ContextUsageSnapshot;
+    /** The meter itself, for the wiring's single-instance assertion and tests. */
+    getContextMeter(): ContextMeter;
     /** Whether a `ContextManager` exists at all. Fixed at construction. */
     isCompactionRegistered(): boolean;
     /** Whether it will actually fire. Flipped live by `/compact on|off`. */