@aragon-agent/cli 0.6.2 → 0.6.4

package/README.md

@@ -377,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) |
@@ -410,6 +412,8 @@ 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 |
+| `/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 |
@@ -434,10 +438,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) |
@@ -447,6 +453,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` /
@@ -905,6 +912,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
@@ -1116,6 +1211,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
@@ -1445,6 +1739,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. |

package/dist/agent/controller.d.ts

@@ -9,14 +9,17 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
-import type { CliConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
+import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
 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 { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
@@ -174,6 +177,34 @@ export declare class AgentController {
     private readonly toolOutputs;
     private readonly outputListeners;
     private readonly fast;
+    private readonly compaction;
+    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`.
@@ -232,7 +263,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;
@@ -491,6 +612,77 @@ export declare class AgentController {
      * `subscribeTodos` already set.
      */
     subscribeFast(listener: FastEventListener): () => void;
+    /** Whether a `ContextManager` exists at all. Fixed at construction. */
+    isCompactionRegistered(): boolean;
+    /** Whether it will actually fire. Flipped live by `/compact on|off`. */
+    isCompactionEnabled(): boolean;
+    /**
+     * Flip the live switch.
+     *
+     * A NO-OP WHEN NOTHING IS REGISTERED, and `/compact` reports that honestly by
+     * checking `isCompactionRegistered()` first — the `/fast on` and `/team on`
+     * shape. `enabled` decides whether the wiring EXISTS, which happens once at
+     * construction and cannot be undone: a session that started with no manager
+     * would have to be given one mid-flight, and the `Agent` has no setter for it
+     * on purpose (§3.2).
+     */
+    setCompactionEnabled(enabled: boolean): void;
+    getCompactionConfig(): CompactionConfig;
+    /**
+     * Adopt a new compaction config for this session.
+     *
+     * THE `onConfigChanged` CALL IS NOT OPTIONAL, for the reason `setFastConfig`
+     * records: a persist without it reports success and changes nothing visible
+     * until relaunch, because the chip and `/compact status` read a snapshot.
+     */
+    setCompactionConfig(patch: Partial<CompactionConfig>): CompactionConfig;
+    /** Everything `/compact status`, the settings row and the chip read. */
+    getCompactionSnapshot(): CompactionSnapshot;
+    /**
+     * The `ModelRef` the next compaction would summarize with, or `null`.
+     *
+     * IT IS CARRIED, NEVER RE-DERIVED, and that is the whole reason it exists. The
+     * summarizer is the fast tier when `useFastTier` is on AND the tier resolves,
+     * and the session's own model otherwise — a combination no caller can
+     * reconstruct from `CliConfig` without re-implementing `resolveFastTier`, and
+     * one that a plausible guess (`fast.enabled ? fast.provider : provider`) gets
+     * WRONG whenever `fast.enabled` is true and `compaction.useFastTier` is false.
+     * Pricing the spend against the wrong provider looks up a model the static
+     * table has never seen, which prices it at `$0.00` — the C-11 / RV-4 lie, on
+     * the one feature that spends money without being asked (AC-15).
+     */
+    getCompactionSummarizerRef(): ModelRef | null;
+    /**
+     * This run's archive key, or `null` when compaction is unregistered
+     * (context-auto-compaction-hardening §3.5 / W4).
+     *
+     * `/compact history` and `/compact show` scope themselves to it, so a second
+     * `aragon` in another terminal is invisible here rather than interleaved with
+     * this one's compactions.
+     */
+    getCompactionRunId(): string | null;
+    /** Ask for a compaction at the next turn boundary (§4.4 / D-17). */
+    queueCompaction(instructions?: string): void;
+    /**
+     * The IDLE `/compact` path (§4.4 / D-25).
+     *
+     * IT VALIDATES BEFORE IT SPLICES. `CompactionWiring.compactNow` runs
+     * `validateHistory` itself and refuses on failure, because with no loop running
+     * the engine's own gate is unreachable and D-4 declares that gate
+     * unbypassable. `replaceMessages` validates NOTHING.
+     */
+    compactNow(instructions?: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Subscribe to the CLI-local compaction event stream.
+     *
+     * Returns a no-op unsubscribe when compaction was off at construction, so
+     * every caller can subscribe unconditionally — the contract `subscribeTeam`,
+     * `subscribeTodos` and `subscribeFast` already set.
+     */
+    subscribeCompaction(listener: CompactionEventListener): () => void;
     /** List usable tools (name + description) for the /tools command. */
     listTools(): AgentTool[];
 }