@staix/agent-hub 0.12.18 → 0.12.20

package/docs/operations.md

@@ -1,8 +1,25 @@
 # Operations guide
 
-This guide describes ahub 0.12.18 and control protocol 15. Live verification
+This guide describes ahub 0.12.20 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
+## Command help
+
+`ahub help`, `ahub --help` and `ahub -h` print the commands grouped by section;
+`ahub help <command>` prints only that command's entries, and so does
+`ahub <command> -h` (or `--help`) when the flag is the only argument; anywhere else
+it is an ordinary argument, and `ahub claude` and `ahub codex` pass it on to the
+agent. An unknown command
+prints `unknown command "<name>"; run ahub help` and exits non-zero. Usages start
+at two spaces and descriptions at one fixed column, wrapped at word boundaries to
+the terminal width, read as at least 80 and at most 100 columns.
+
+Help uses the console palette: section headings bold cyan, `ahub <command>` words
+cyan, arguments and descriptions the terminal's default foreground. It has no
+`--color` flag: color is on only when standard output is a terminal, `TERM` is
+not `dumb` and `NO_COLOR` is empty or absent. Pipes and redirects get plain text
+without escape sequences, laid out for 80 columns.
+
 ## Operator console and panels
 
 `ahub console` combines the existing tail stream with peer, quota, approval-age
@@ -17,11 +34,59 @@ approval titles are terminal-only; expiry and answers from another console remov
 the pending item. Approval audit records contain id, peer, option kind, response
 time and answering surface, without the title.
 
-Tab toggles stream and panels; `ahub console --panels` starts in panels. Peers,
-Approvals, Tasks, Queue and Events support arrow keys or j/k, Enter for detail,
-Escape to return and `?` for help. `:` enters a command. Assignment, delivery
-resolution and allow decisions require confirmation; delivery resolution requires
-a reason. Tasks use the same public redaction as the board. Panels need at least
+Pi's write, edit, bash and git write requests also offer `Always allow <tool>
+until Pi restarts`. It allows later calls of that tool by the running Pi without
+asking, under the same path guard and sandbox; a Pi restart or replacement, or a
+hub restart, drops it. The hub log records each granted call by tool name only.
+The dashboard can only deny Pi's requests.
+
+Tab toggles stream and panels; `ahub console --panels` starts in panels. A panel
+screen has a header (the project's directory name, then the tabs), the panel and
+a three-line footer, separated by ASCII `-` rules; the stream has one rule above
+its footer. The active tab is bracketed, as in `[2 Approvals]`, so it reads
+without color. The Approvals tab counts pending requests and the Queue tab
+counts `needs_review` deliveries, in the attention and failure tones.
+
+Peers, Approvals, Tasks and Queue are tables with a header row. A column is as
+wide as its widest cell, up to a third of the terminal; the last column takes
+the rest and is cut with `...`.
+
+| Panel | Columns |
+|---|---|
+| Peers | PEER STATE LINK Q ! REVIEW PAUSE QUOTA MODEL |
+| Approvals | ID PEER LEFT TITLE |
+| Tasks | ID STATE OWNER REVIEWER CLASS AGE TITLE |
+| Queue | ID PEER STATE REV AGE |
+
+Zero counters and unknown values read `-`. Durations read `45s`, `12m`, `3h05m`
+or `2d03h`; quota resets and budget pauses read `in 2h13m`, and a pause by the
+console user reads `user`. When a peer's status carries #205's optional
+`toolsOnly` field (a Claude session attached without channel pushes), LINK reads
+`tools-only`. Below the Approvals table, a rule and the selected
+request: its title, its allow options numbered as `a` offers them, and `d deny`.
+A title too long for the panel is marked `(more)` in the label column; Enter
+shows it whole. `d deny` always shows; options that do not fit are counted on a
+`(more)` line. The first request is selected when it arrives; `[` and `]` (or
+j/k in the panel) select another. `a`, `d` and `v` act on the selected request
+only: when it closes, the selection clears with a notice instead of moving to
+another request, and a request that arrives later waits for `[` or `]`. Moving
+the selection cancels a pending allow choice or confirmation; the choice prompt
+names its request. Agent-written text below a field, and option names in
+prompts, are quoted unless they are a single word starting with a letter, so
+punctuation, a newline or a bare number in them cannot imitate the console's own
+structure. Under the `?` key table only `?`, Escape and `q` act.
+
+Arrow keys or j/k move, Enter opens a detail of labeled fields (relative times,
+never JSON), Escape returns, and `?` shows the keys grouped by panel; in the
+stream, `?` prints that table and `v` prints the selected request as its push
+showed it. The footer's last line lists only the keys that act in the current
+mode, panel and state. A notice shows on the footer's second line until the next
+key or for about ten seconds: errors and refusals (a refused command, a request
+error, the size refusal) in the failure tone, notices that only inform (a closed
+or missing selection) in the attention tone. With a detail open, `p`, `r` and `a`
+act on the item the detail shows. `:` enters a command; its output lines
+start at column 4, as message bodies do. Assignment, delivery resolution and
+allow decisions require confirmation; delivery resolution requires a reason. Tasks use the same public redaction as the board. Panels need at least
 80 columns by 24 rows; smaller terminals stay in stream mode. Task and queue
 polling runs only while the corresponding panel is visible. Leaving restores
 the terminal and returning from panels replays the bounded stream buffer.
@@ -39,7 +104,7 @@ management or the final reset. Invalid values fail before connecting.
 | Success and availability | Green | Idle peer, approved task |
 | Waiting and attention | Yellow | Busy/paused peer, pending approval, confirmation, review/ready task, important priority |
 | Failure and intervention | Red | Failed/check-failed task, undeliverable/overflow, `needs_review` queue, denial request or expired/cancelled approval |
-| Metadata | Bright black | Ages and remaining approval time |
+| Metadata | Bright black | Ages, remaining approval time and rules |
 
 Offline peers, primary titles, action details and message body lines keep the
 terminal's default foreground. Labels and prompts remain readable without
@@ -299,7 +364,10 @@ the routing configuration.
 A review request carries a checklist: map the changed signatures and call sites
 to the task's plan (without one, to its detail, which the request then
 includes), read the check result, and list what is
-unmet (`hub_review` takes `unmet`, `ahub review ... --unmet <item>`). The hub
+unmet (`hub_review` takes `unmet`, `ahub review ... --unmet <item>`). A reviewer
+that missed the request, and the owner, read the done summary and check result
+with `hub_task_show {id}`: the task's public view with its history, as the
+conductor sees it, and only a stub for a PII task. Other peers are refused. The hub
 records how each review turned out, per implementer, reviewer and class:
 approved; caught (changes were requested and the owner's redo was approved);
 contradicted (within a week, work on the same file or symbol failed its check
@@ -321,7 +389,8 @@ one line with its next message, the plan included, at no turn of its own. When a
 task is done (after its check passes, when one is configured), the owners of
 open tasks on the same paths or symbols get a message with the changed files,
 the plan's signatures and the first line of the summary, each left out when it
-matches a PII pattern; nobody else does. PII
+matches a PII pattern (the summary also when `signals.pii_screen = "local"` did
+not clear it); nobody else does. PII
 tasks are left out on both sides.
 
 A task can wait for others: `hub_task_propose` takes `after: [ids]` (`ahub task
@@ -334,8 +403,36 @@ to the next run.
 `ahub board --ready` and
 `hub_task_list {ready: true}` list the proposed tasks with nothing left to wait
 for. Dependencies are fixed when a task is proposed and can only name tasks that
-already exist, so they cannot form a cycle. A waiting task cannot name an owner;
-use `ahub task assign` once it is ready. An owner offline longer than `tasks.release_after_min`
+already exist, so they cannot form a cycle.
+
+An owner named for a task that waits (`owner` with `after`, `--owner` with
+`--after`) is its reserved owner: the task still waits, and when it is ready
+routing offers it to that peer first, not to the first idle peer of the class.
+A reserved owner that is offline, paused, failing, not attached or excluded is
+passed over: routing proceeds as usual, the console and hub.log say which
+reservation was passed over and why, and the assignment's history note keeps
+it, unless it is no news (the reserved peer is the owner the task moves away
+from, or it already refused the task). A peer the task was declined for (by
+itself or by the console) or escalated away from after repeated
+changes_requested or by hand stays excluded on every later reroute; an owner
+released as gone, or moved by the hub after a failed delivery or inference, is
+excluded only from that move and may get the task again from its reservation
+later. Your own `ahub task assign` is not blocked by those exclusions, and it
+drops the agent's reservation. The PII constraint and capability limits
+still apply, so a PII task goes to `local` or nobody whoever was reserved.
+`ahub task assign` on a task that waits changes its reserved owner instead of
+handing it over. `ahub route explain <id>` names the reserved owner; once the
+task is ready it also says whether routing would honor the reservation now, and
+why not.
+
+The peer that proposed a task may redirect it with `hub_task_assign` while it
+is `proposed` and nobody ever accepted it, without the conductor role (handing
+it to another peer needs `assign` when the proposer has a capabilities list).
+Once it was accepted, even if a decline or release later put it back in
+`proposed`, or after a person assigned or reserved it from the console (also
+once the hub carried that out), only the conductor and the console move it.
+
+An owner offline longer than `tasks.release_after_min`
 (default 30, `0` turns it off) in `.agenthub/config.json` loses its open tasks
 to a peer routing can give them to; with nobody to take them they stay, and a
 paused peer or a hub in a recovery operation is left alone.
@@ -387,6 +484,13 @@ ahub report --by task           # tokens, turns and wall time per task and class
 ahub export --since 24h         # the raw events as JSON lines, for your own analysis
 ```
 
+Per peer and model route, `ahub report` also counts model changes between consecutive
+decisions, how many of them landed inside tool loops and, with `stay_switch` on, sessions
+and the planner's switches (#197). With `stay_switch = "off"` session boundaries are not
+recorded; `shadow` routes exactly as `off` does, so it is the baseline to compare `enforce` with.
+A route event records the decision, so a load-moved request that its MLX fallback served counts
+as a change to `dgx/fast`; the relay's request journal records which backend served it.
+
 `ahub report` counts the same overlap warnings as `scripts/overlaps.ts`, from the
 structured events instead of log lines. `--by task` uses the task each usage and
 token record was attributed to when it was written: the delivery that started the
@@ -734,6 +838,30 @@ the system marks it `needs_review`. Establish evidence before choosing
 disconnects, cancellation, and partial effects are uncertain; do not replay
 them automatically.
 
+### Claude sessions without channel pushes
+
+Only `ahub claude` starts Claude Code with the development-channel flag. A
+Claude session started another way (plain `claude`, an IDE) keeps the hub tools
+but cannot show pushes, so it attaches tools-only (protocol 16, issue #205):
+
+- Its messages stay queued. `ahub status` shows `queued N` and `tools-only:
+  messages wait for hub_inbox; for pushes restart Claude with ahub claude`; the
+  console footer shows `tools-only: ahub claude` and the dashboard shows the
+  status line.
+- The session reads them with `hub_inbox`, at most ten messages at a time plus
+  the hub's recall note when one waits (it says how many still wait). Each read is one `completed` delivery (`read through
+  hub_inbox` in `ahub queue list`); nothing is ever `accepted`, and the session
+  has no `hub_delivery_done`. A read the model never saw (the tool call was
+  cancelled, the plugin died) cannot be retried: `ahub queue show <id>` of the
+  `completed` row prints the messages to send again.
+- Whatever holds pushes holds `hub_inbox` too (`needs_review`, recovery,
+  `ahub pause`, a budget pause, a conductor hold): it reads nothing and says
+  which hold applies.
+- Restarting Claude with `ahub claude` takes the peer over and pushes what still
+  waits; the plain session stands by. The other way round, a plain session
+  started while an `ahub claude` session holds the peer stands by and attaches
+  only after that session leaves.
+
 ## Graceful shutdown
 
 Before stopping, let active turns and approvals settle when possible:
@@ -758,6 +886,93 @@ so a restarted hub never launches beside a survivor. A hub whose project root
 or state directory was deleted stops itself within about 10 seconds; the
 dashboard manager does the same when its home directory vanishes.
 
+## Resetting a project's hub
+
+`ahub reset` returns a project's hub to a clean state. Without `--yes` it is a
+dry run: it lists what it would settle, clear, archive and keep, by delivery
+id, peer name and count, never task or message text, and changes nothing.
+With `--yes` it first stops a running hub the way `ahub kill` does, then acts.
+
+```bash
+ahub reset              # dry run, runtime scope
+ahub reset --yes        # runtime reset
+ahub reset --all        # dry run, full reset
+ahub reset --all --yes  # full reset
+```
+
+The runtime reset (the default):
+
+- discards every `queued` and `needs_review` delivery with reason `reset`
+  through the delivery journal, one `resolution_history` entry each. Work
+  that was dispatching or accepted when the hub stopped is held as
+  `needs_review` first, so it is discarded too;
+- clears manual peer holds (`ahub pause`), budget pauses and conductor holds;
+- drops the agent session resume pointers `sessions.json`,
+  `claude-session.json` and `claude-context.json`, so the next launch starts
+  new agent sessions. Pi transcripts under `pi-sessions/` stay;
+- removes the manifest (`status.json`, `control-token`, `hub.pid`) a hub left
+  when it did not stop cleanly, once no process behind it is alive;
+- keeps the board (tasks, reviews, outcomes, turns, touches), `hub.log`,
+  `events.jsonl` and `cli-audit/`, recovery records, execution budgets,
+  configuration and files the hub does not own.
+
+The full reset (`--all`) moves the whole state directory, unchanged, to
+`.agenthub/archive/state-<UTC time>/` (mode 0700) and starts an empty state
+directory holding only `project.json`, so the project keeps its id and
+registration; the next `ahub up` starts with an empty board and queue.
+`.agenthub/config.json`, `config.local.json` and `routing.toml` live outside
+the state directory and are not touched. The archive keeps the task text,
+PII included, so it stays in the project: the reset writes
+`.agenthub/archive/.gitignore` (`*`) so git ignores it, and the local
+worker's and Pi's denylist (file tools, sandbox, memory capture) covers
+`.agenthub/archive` as it covers `.agenthub/state`. Turn snapshots leave the
+archive out as they leave the state out. Nothing deletes or prunes
+archives; removing one is a manual act.
+
+To restore an archive, stop the hub, move the current state directory into
+the archive too (where git and the local worker's denylist cover it), then move
+the archive back:
+
+```bash
+ahub kill
+mv .agenthub/state .agenthub/archive/state-$(date -u +%Y%m%dT%H%M%SZ)
+mv .agenthub/archive/state-<UTC time> .agenthub/state
+ahub up
+```
+
+Only a person runs `ahub reset`: an agent shell is refused before anything
+happens, as for `kill`, `restart` and `upgrade`. It is refused, with nothing
+changed:
+
+- while an upgrade or recovery operation is open (the machine's recovery lock,
+  or a running hub that reports an unreleased recovery);
+- when no registration matches this project and state directory. A running
+  hub must then be stopped with its matching CLI; a stopped project is
+  registered again by `ahub up` (then `ahub reset --yes` stops it first). When
+  the project is registered with another state directory, the error names
+  `ahub --project <id> reset` instead;
+- when the hub's ownership cannot be verified, as `ahub kill` refuses it;
+- for `--all`, when the state directory is not `<root>/.agenthub/state`
+  (`AGENTHUB_STATE_DIR` or a symlink elsewhere): archive such a directory by
+  hand after `ahub kill`;
+- for `--all`, when `.agenthub/archive` is a symlink or not your own
+  directory, or its `.gitignore` is not a regular file: anything with write
+  access to the project could otherwise send `hub.db` out of it. Inspect and
+  remove what is there, then run the reset again.
+
+After stopping the hub the reset holds the project's registry claim, the one a
+daemon takes to run, until it is done, so no hub starts under it; a hub that
+started in between makes it stop with nothing reset; a crashed hub's leftover
+manifest does not count as one. If a step fails after the stop, the error says
+how far it got: rerun `ahub reset --yes` to finish a runtime reset (every step
+can run again), unless the error says the state cannot be read (a damaged
+`hub.db` or journal fails the same way every time): `ahub reset --all --yes`
+archives such a state directory as it is. A full reset names the archive once
+the state directory has moved.
+It never touches claude-mem: notes saved with `hub_remember` are shared memory,
+not hub state. Claude Code sessions attached to the hub lose their hub session;
+relaunch them with `ahub claude`.
+
 ## Orphaned daemons
 
 Daemons from before those guards, or daemons whose project directory was
@@ -786,21 +1001,21 @@ Rows without a live process are stale registrations; forget them with
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15) 14 (0.12.16) or 15 (0.12.17 and 0.12.18), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.18 ahub upgrade --to 0.12.18 --dry-run
-bunx --package @staix/agent-hub@0.12.18 ahub upgrade --to 0.12.18 --yes
+bunx --package @staix/agent-hub@0.12.20 ahub upgrade --to 0.12.20 --dry-run
+bunx --package @staix/agent-hub@0.12.20 ahub upgrade --to 0.12.20 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 and 0.12.18 (protocol 15) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -832,17 +1047,19 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.18 --dry-run
+ahub upgrade --to 0.12.20 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.18 --yes
+ahub upgrade --to 0.12.20 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
+ahub recovery dispose <operation-id> --fresh-session <peer> --reason <text>
+ahub recovery dispose <operation-id> --stop-and-archive --reason <text>
 ```
 
 The coordinator commits only once the source is quiet: no turn running, no
@@ -898,6 +1115,20 @@ Kimi and local sessions may start fresh with preserved routing and task context.
 A Claude session that never persisted a transcript (zero turns) also starts fresh:
 there is nothing to resume, so the upgrade accepts the new session id; a session
 with a transcript must come back with its original id.
+A Claude session that `ahub claude` did not launch in a recorded Orca terminal
+(a plain `claude`, or one whose launcher has ended) is planned as
+reconnect-only: the plan lists it under `reconnectOnly`, and the command prints
+`<project>: claude is reconnect-only` on stderr. Nothing in its terminal is
+closed or relaunched, a `claude-session.json` left by an earlier launch is never
+used as its target, and the plan does not show that record's id. Its plugin
+reconnects to the new hub by itself (the coordinator waits up to 90 seconds) and
+keeps the plugin version it started with until that Claude session restarts.
+The target release must read recovery waivers; staging refuses one that does
+not, before any runtime changes. Across a control-protocol change it cannot
+reconnect; the plan then names a
+blocker: end the session, or relaunch it with `ahub claude` in Orca, and make a
+new plan. A refused `--yes`, and every dry-run, prints each blocker on its own
+`ahub: blocker:` line before the final one.
 Previously stopped projects stay stopped; only the reviewed running projects
 are upgraded.
 
@@ -905,6 +1136,140 @@ Do not run an upgrade with an incompatible active protocol, an unverified
 terminal binding, or an unresolved operation lock. Dry-run performs no package,
 plugin, daemon, or terminal mutation.
 
+### A partial operation
+
+`ahub recovery status <operation-id>` reads the receipt without changing it:
+its phase, step and error; `runner`, which says whether a runner process holds
+the operation now (`running` with its pid, or `none`; `stale` marks a receipt
+that says running with no runner behind it); each project's phase and effect
+receipts (`closed:<peer>`, `restored:<peer>` as `done`, `pending` or `failed`);
+whether the shared plugin and the global CLI were installed; and `next`, the
+commands that apply now, read from every source the operation has not stopped
+yet (every error of `resume` ends with the same list). `resume` is left out
+when it can never get past: a source replaced by another instance, or a
+prepared source that stopped before any commit request. It shows no task or
+message text. `resume` does not
+start a second runner while one is alive. Every `next` entry and error names the
+operation's own coordinator, `bun <preserved source>/src/cli/main.js recovery
+...`: in the middle of an upgrade the global `ahub` may still be the older
+release, whose `recovery` lacks these commands. Copy that command line. When
+an older coordinator started the operation, `dispose` is named from the running
+release, which has it. What
+each receipt allows, given what is live, is tabulated in the recovery spec
+(`docs/specs/2026-09-20-upgrade-recovery-design.md`, "Receipts, evidence and
+next actions").
+
+- The source hold lapses after 10 minutes. A later `resume` prepares the same
+  source again and checks its peers again, keeping the receipts, so no terminal
+  is closed twice. It refuses, naming the next step, when the source daemon was
+  replaced, when another operation holds it, or when a peer changed: a peer whose
+  terminal the operation closed must stay closed, a session that joined since
+  must end, every other one must keep its conversation. With nothing closed yet,
+  `abort` cancels the operation (also once its hold has lapsed, or when another
+  daemon or operation holds the source, which it leaves alone) so a new plan
+  can be made, also after a source crashed before any commit was requested
+  (`resume` then stops, as there is nothing to start from, and names abort, or
+  stop-and-archive once anything was done); it
+  refuses while a prepared source cannot be read (its hold may still stand),
+  once a commit request may have been sent (or, for an operation from
+  an older coordinator, which records no such thing, while a prepared source is
+  not running), and once any project has effects the way out is
+  stop-and-archive. `next` offers abort only where abort would succeed, and
+  `resume` (and `--fresh-session`, which resume carries out) only where it can
+  get past what is live: not past a replaced or missing source, a source that
+  crashed before any commit request, a refusal at staging (the target release
+  or the preserved source can never change back), a hub of another control
+  protocol, a target that stopped after it started, or a stopped hub without
+  the operation's restart snapshot.
+  A second `resume` while its own hold still stands checks the peers again
+  before it closes anything.
+- When a target hub dies after it started (a crash or a reboot), restarting it
+  from its snapshot is not supported in this release (its peers would have to
+  be relaunched against the new hub): `resume` is not offered and the way out
+  is stop-and-archive.
+- A Codex conversation comes back only when a rollout file naming its thread
+  exists under `sessions/` of the store the restored terminal uses (the
+  recorded `CODEX_HOME`, else `~/.codex`). Codex writes that file with the
+  first message, so a thread the hub saw Codex start, with no turn on it since,
+  is listed under `freshStart` and restarts as a new session, with nothing to
+  lose; the command says so. A thread with turns, or one whose start the hub's
+  log does not show (it was resumed, or the hub is older), blocks the plan when
+  it has no rollout, and so does a store that cannot be read (unknown, not
+  missing). The coordinator checks again before closing the terminal and before
+  creating the new one. To continue without such a conversation, end that Codex
+  session and close its Orca terminal, then `resume`; it stops at restoring
+  Codex, where `--fresh-session codex` below is the way on.
+- A restored terminal runs its launch in a login shell, so the coordinator
+  watches the launcher, not the terminal: once `ahub codex`, `ahub claude` or
+  `ahub pi` has recorded itself there and its process is gone, or Orca no longer
+  lists that terminal at all, the restoration failed (found within one 5-second
+  wait). A launcher whose process cannot be read counts as running, never as
+  gone. One that dies before recording itself leaves no record to read, and
+  what happens next depends on whether Orca reports the bare login shell it
+  returned to as TUI-idle, which is not verified. If it does, the coordinator
+  stops at once with "original session restoration needs manual verification"
+  (the terminal cannot be mapped to the session). If it does not, it stops with
+  the same error after the 10-minute wait. Either way the receipt stays
+  `pending`; close that terminal in Orca (or wait, if the session may still
+  attach), then `resume`: with no live launcher and no attached session it
+  records `restored:<peer>` `failed` and lists the failed-restoration choices.
+  A `failed` receipt never counts as restored.
+  `resume` settles a `pending` or `failed` receipt by what is live: the planned
+  session attached is the restoration, a launcher still running is waited for,
+  and no second terminal is opened while one may run. A target hub that cannot
+  be read counts as unknown, never as "nothing attached", and so does a launcher
+  record file that cannot be read: `resume` then stops without changing any
+  receipt; when the record file is what cannot be read, inspect it and move it
+  aside, then `resume`. `resume` is refused while a stop-and-archive is partway. A lifecycle command refused by the lock names
+  the operation's own `status` command, which lists what to do next.
+- `ahub recovery dispose <operation-id> --fresh-session <peer> --reason <text>`
+  applies to a Codex or Claude peer whose restoration failed (Pi is refused: a
+  restored hub resumes Pi's recorded session). It records the lost session or
+  thread id (status shows it under `lostContinuity`) and resumes: the peer
+  starts without its old conversation, and the rest is verified as usual.
+- `ahub recovery dispose <operation-id> --stop-and-archive --reason <text>`
+  abandons the operation. It checks every project first and refuses while a
+  hub is unreachable, starting, stopping or of another control protocol; `next`
+  then says `wait until <project>'s hub settles, then ... recovery status
+  <id>` instead of offering it. A hub that never answers (its pid is alive,
+  nothing replies): take the `pid` from that project's
+  `.agenthub/state/status.json`, check with `ps -p <pid> -o command=` that it
+  is that project's hub daemon, end it by hand, then run `status` again. If
+  that pid now belongs to another process (reused after a reboot), move the
+  stale `status.json` aside instead, then run `status` again; likewise when
+  `next` says `wait: runner <pid>` and that pid is not an `ahub recovery-run`
+  process, move the operation's `~/.agenthub/recovery/<id>.json.runner.db`
+  aside, then run `status` again. A
+  project whose directory is
+  gone is only recorded (`ahub doctor --orphans` lists a hub left running
+  there). It records its decision before it acts. It releases a source hold of
+  its own (that hub keeps running), stops a target hub it started and has not
+  released (one an older coordinator started is stopped at that release's
+  control protocol), moves that operation's
+  `restart.json` aside as `restart.abandoned.<hash>.json` and leaves any other
+  hub running; only then is the operation recorded `cancelled` and the lock
+  released. If it fails partway it keeps the lock, records what it did, and
+  `resume` refuses until you run it again. Queued messages are not delivered
+  from the archived file; a 0.7.0 or later hub reloads the queues it kept in
+  `hub.db` when it starts again. Terminals it closed stay closed: start those
+  sessions again by hand. Replacement terminals it opened stay open but have
+  no hub: Claude's plugin reconnects once a hub runs, Codex needs `ahub codex`
+  again.
+  Start a project whose target ran with that release's CLI (`bunx --package
+  @staix/agent-hub@<version> ahub up`), since it may have changed the task
+  database. The global CLI was not promoted.
+- Both choices are for a person in a terminal; an agent shell is refused, and
+  the reason is kept in the operation's audit. Run each with the command
+  `next` or the error prints: the operation's own coordinator, or the release
+  you are running when that coordinator predates these commands (its `resume`
+  still runs the old runner, and `next` says what that runner cannot do).
+  `--fresh-session` never applies to such an operation: its runner never
+  records a restoration as `failed`.
+  `--fresh-session` is not offered when the target release cannot read recovery
+  waivers, since it could never release a new session; `status` says so in
+  `freshSession`. A runner record that cannot be read shows as `unknown`, and
+  `resume`, `abort` and `dispose` are refused until it can be read.
+
 ### After an unplanned stop
 
 While it runs, the hub keeps each attached peer's session identity in
@@ -1031,9 +1396,46 @@ PII calls require a positively confirmed campus gateway immediately before trans
 PII turns never enter shared history, memory capture, or progress observation.
 The `route`, `advisor`, `progress` and `stuck` events contain identifiers and aggregates only.
 
+Session-aware stay/switch (#197) covers `hub/auto` and `stage` routes. The top-level
+`routing.toml` key `stay_switch` is `off`, `shadow` (default: route events record what the
+planner would do, routing unchanged) or `enforce`. Enforced, a hard override (compaction,
+critical failure, repeated failure) escalates at once; a tool-result turn keeps the
+session's tier; other changes wait for the next user turn, and a de-escalation whose
+conversation is larger than `max_switch_prefill_tokens` (default 32000) stays; a PII route
+has no such bound, so its size never shows in a decision. A capable
+hold then lasts at least until the next user turn; `hold_turns` can extend it past that
+turn. A tier whose backend
+cannot hold the conversation is never chosen; no route summarizes or trims the history.
+
 Pi exposes `hub/auto` for stage routing when available. Fixed `dgx/coding`, `dgx/fast`
 and `mlx/fast` aliases still pin the backend. Automatic MLX selection admits the complete
 input, tool schemas and requested output within the configured context window.
+A `hub/auto` request bound for MLX has two candidates, MLX and its `dgx/fast` fallback; load
+and cooldowns only change their order, never remove one (#199). A fixed alias (`mlx/fast`,
+`pi_backend = "mlx"`) keeps its backend first as before. `dgx/fast` goes first when MLX is
+cooling down (route event `source: "cooldown"`). Load moves are opt-in until they are
+measured: with `[pi] efficient_wait_ms` set (0 to 119999; 0 tries once; read when the hub
+first starts Pi, like `dgx_max_context_tokens`, so a change takes a hub restart), a request
+whose MLX slot is still busy after that wait goes to `dgx/fast` first (`source: "load"`), and
+so does an enforced tool loop pinned to it (`source: "pin"`); without it nothing moves for load. `dgx/fast`
+never goes first while it is cooling down, or while its own last dispatch failed in any way,
+an error status or a failed stream included, until it succeeds or 30 s pass (`ahub status`:
+`last dispatch failed, no load moves until ...`). No load move or pin happens while the request
+runs under an execution budget, and enforced, a load move happens only at a user turn. A moved
+attempt gets 15 s to its response headers after the gateway lookup (OmniRoute's own probe,
+up to two 4 s rounds when no gateway is cached) and is then abandoned for MLX, which serves
+with the usual slot wait. The bound ends with the headers: a stream that stalls or fails
+after them is not retried on MLX, and a failed one marks `dgx/fast` failing (a client that
+disconnects does not). Each backend is tried once per request, so with moves on, a moved attempt
+cut at 15 s followed by an MLX slot that stays busy past 120 s fails the request (502), where
+without moves the request would have waited for MLX and then had `dgx/fast` with its full
+deadline; this is part of what the opt-in accepts until #199 AC5 measures it. After three
+consecutive transport or startup failures outside a cooldown (a failure more than 10 min after
+the last counted one starts the count over), a relay alias cools down for 30 s, doubling up to
+5 min. A busy MLX slot and timeouts cut short by an execution budget never count; any HTTP
+answer, a success or an error status, proves the transport works and ends the streak and the
+cooldown. `ahub status` shows `cooling down until ...` on the backend line and `events.jsonl`
+records `cooldown` events.
 Progress judgements suggest reassignment; they never change task ownership.
 
 ## Disable local MLX while keeping remote auto routing

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.18
+bun add -g github:STAIxBWLB/agent-hub#v0.12.20
 ahub setup
 ```