@staix/agent-hub 0.12.19 → 0.12.21

package/docs/operations.md

@@ -1,8 +1,25 @@
 # Operations guide
 
-This guide describes ahub 0.12.19 and control protocol 15. Live verification
+This guide describes ahub 0.12.21 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
@@ -23,15 +40,88 @@ 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. 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
-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
+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 `...`. In Tasks, TITLE takes the rest and the STAGE
+meter keeps a fixed column at the right edge.
+
+| Panel | Columns |
+|---|---|
+| Peers | PEER STATE MODE LINK Q ! REVIEW PAUSE QUOTA MODEL |
+| Approvals | ID PEER LEFT TITLE |
+| Tasks | ID STATE OWNER REVIEWER CLASS AGE TITLE STAGE |
+| Queue | ID PEER STATE REV AGE |
+
+The MODE column appears only when at least one peer has a non-`ask` mode.
+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`, `m` 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, allow
+decisions and a never-ask permission mode 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. Full task and queue reads run only in panels; stream progress uses the existing
+status state counts and never fetches the board. Leaving restores
 the terminal and returning from panels replays the bounded stream buffer.
 
+The Tasks panel summarizes the whole public board with an approved/all fraction,
+a 20-cell ASCII bar and state counts. Proposed tasks with unapproved or missing
+`after` dependencies count as waiting; PII stubs count normally. Each task has a
+four-cell stage meter (proposed, in progress, review, approved). Changes requested
+returns to in progress and uses `!` plus the failure tone. Narrow panels retain
+the fraction/bar before optional counts, which appear in fixed importance order:
+changes requested, review, waiting, in progress, proposed, then unknown when nonzero. Narrow widths drop
+only the suffix. Bar cells and percentages round down so open tasks never imply
+completion. Stream `tasks N/M approved` lives on the approvals footer line, leaving the
+peer/queue footer line intact. Operator notices or an already-full approvals line
+take precedence over this optional count. A brief notice hides it only until the
+notice's ten-second TTL expires, then the retained known count returns on redraw; the scroll
+region starts at row 1 to preserve terminal scrollback. All existing status state
+counts contribute to its total, including an unfamiliar state. Until a successful
+status read it says loading; later failures preserve the prior count with a notice.
+Panels retain their existing full-board refresh and loading/error handling.
+
+The dashboard Task board shows the same shared public-board progress model,
+including state counts, waiting, stacked segments and a labeled four-stage track
+per row. Filtering rows does not filter overall progress. The existing signature guard
+updates the live region only when progress changes. The stacked SVG fills the
+section width; its text legend carries every state count. Theme offers System,
+Light and Dark; it is applied before first paint and stored in a host-scoped loopback cookie
+(`Path=/`, `SameSite=Strict`, one-year lifetime), shared across dashboard ports.
+Blocked cookie access defaults to System on reload and never prevents operation. System follows
+OS color preference through CSS. Both inline scripts and the style retain CSP
+hashes; there are no external chart/theme assets. Live theme/readability inspection
+is tracked in `docs/smoke.md` and remains unverified until performed.
+
 Console color policy is `--color=auto|always|never`, with `auto` as the default.
 Auto enables color only when both input and output are TTYs, `TERM` is not
 `dumb`, and `NO_COLOR` is empty or absent. Explicit `always` overrides these
@@ -45,12 +135,31 @@ 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 |
+| Stream peer names | Claude bright blue (94), Codex bright cyan (96); all others default | Fixed map, no hashing or themes |
+| Stream `task` keyword | Magenta | Task event keyword |
+| Stream numbers | Bold default foreground (1) | Percentages, durations and measured times |
+| Stream issue references | Underlined default foreground (4) | `#232` |
+| Stream task references | Magenta underlined (4;35) | `#1` following `task`/`Task`, `[task #1]`, `[review #1]` |
 
 Offline peers, primary titles, action details and message body lines keep the
 terminal's default foreground. Labels and prompts remain readable without
-color. Stream styling applies only to the header, using structured event data;
-message text cannot choose a color. A local denial is shown as requested, not
+color. Stream styling applies only to meaningful tokens in the first line: peer names,
+`task`, numbers and references. Ordinary words keep the default foreground.
+Task prefixes and bracketed `[review #N]` identify task references
+case-insensitively; prose `review #N` and other `#N` tokens are issue references. Legacy assign/which notices lack typed reference
+ranges and use the issue tone until structured spans identify them. The dated
+#239 palette reserves green/yellow/red for states, cyan for navigation and
+blue/cyan for Claude/Codex. Tokens use plain magenta, underlining and bold default
+foreground; no token SGR equals a state or peer SGR. The `task` keyword is never
+bold. Only hub-written peer slots are colored, not title words or decline reasons.
+State words and structural markers retain their event tone. Numeric-looking
+identifiers stay plain. Wrapped headers normalize tabs before tokenization; plain headers preserve
+their original tabs with color enabled or disabled.
+A projection miss on the first physical header keeps only structural tones.
+A missed continuation and every following continuation are fully plain; their
+text cannot supply structural tones. Projection carries its span index forward
+instead of rescanning earlier spans for every line. Bodies and command output stay plain. A local denial is shown as requested, not
 as a confirmed receipt; a remote answered closure has no option-kind metadata
 and is not guessed to be a denial. A fixed palette is applied after terminal
 control sanitization. Width, clipping, wrapping and cursor placement use plain
@@ -70,8 +179,8 @@ recorded separately in the smoke ledger; fake-terminal tests establish policy,
 geometry, sanitization and restoration only.
 
 The command input accepts existing status, board, task, review, say, pause,
-resume, budget, queue, permit, ask, remember, route, turns, undo, check-path and
-report operations. It executes an argument vector with closed stdin. Lifecycle,
+resume, budget, queue, permit, permission, ask, remember, route, turns, undo,
+check-path and report operations. It executes an argument vector with closed stdin. Lifecycle,
 launch, nested console, setup, UI, logs and tail commands are refused.
 
 ## Conducting a team from Claude Code or Codex
@@ -118,9 +227,11 @@ off withdraws pending feed notices.
 
 For a Claude conductor, `ahub claude` also observes native session and turn
 boundaries when facts injection and task-idle sweeps are off. Keep the managed
-hooks enabled to measure completion and supervision usage. Passing your own
-`--settings` takes precedence and produces a warning when it replaces that
-observation. The launcher records its private session identity in ordinary
+hooks enabled to measure completion and supervision usage. Your own
+`--settings` (given once, a JSON object or file) keeps that observation: the
+launcher adds the hub's hooks to its hooks and warns only that the status line
+tee is off; one that sets `disableAllHooks` is refused. The launcher records its
+private session identity in ordinary
 terminals too; this does not grant terminal-recovery authority.
 Ordinary Claude sessions with turn-free facts or task-idle sweeps enabled get the
 same session/start observation. Other ordinary launches remain non-opt-in.
@@ -157,7 +268,8 @@ may request an approval.
 
 `.agenthub/config.json` can be committed and shared. The fields that choose
 what the hub runs, which files it sends as credentials, where task text goes,
-or how far the local worker's sandbox reaches (`kimi_cmd`, `codex_bin`,
+how far the local worker's sandbox reaches, or how often a peer asks before it
+acts (`kimi_cmd`, `permission_modes`, `codex_bin`,
 `pi.cmd`, `checks`, `mlx.bin`, `mlx.runtimeDir`, `mlx.modelPath`, `omniroute.urls`,
 `omniroute.access_hosts`, the `omniroute` key files, `memory.worker_url`,
 `local.read_allow`, `local.bash_network`, `local.network_allow`) are machine-local:
@@ -305,7 +417,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
@@ -327,7 +442,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
@@ -336,12 +452,43 @@ offered to nobody, cannot be claimed, accepted or marked done, and `ahub route
 explain <id>` says what it waits for. When the last one is approved, the task
 goes through assignment like a new one; if the hub stopped before it got that
 far, the task is offered within a minute of a peer that can take it attaching
-to the next run.
+to the next run. An offer is used up only by an assignment, after an approval
+and on the timer alike. If no peer can take it or a ready/assignment write fails,
+the task stays eligible; the timer adds no history or notices while nobody can
+take it.
 `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.
@@ -393,6 +540,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
@@ -400,6 +554,37 @@ turn, otherwise the peer's only `in_progress` task. Everything else is reported
 unattributed, and records from before 0.12.18 as a separate bucket; neither is
 redistributed (rules: [events](events.md#per-task-usage-reports)).
 
+## Research records
+
+With `"research": { "enabled": true }` in `.agenthub/config.json` (off by default), the hub keeps one record per
+approved task in `~/.agenthub/research/`, shared by every project that opts in: outcome, review rounds, rework, failed
+checks, tokens and time per peer and model, never task or message text ([schema](research.md)).
+
+```bash
+ahub research --since 30d          # success, first-pass, rework and check-failure rates; tokens and wall time per task
+ahub research --all --json         # every opted-in project on this machine
+ahub research export --format csv  # the records, for your own analysis
+ahub research backfill             # build this project's records once from events.jsonl
+ahub task label 12 reverted        # a later verdict (ok, regressed, reverted, incomplete, wrong, abandoned)
+```
+
+## Benchmarks
+
+In a git repository kept for benchmarks (`"bench": { "enabled": true }` in its `.agenthub/config.json`, a clean tree),
+`ahub bench` runs a suite of tasks against the peers attached to its hub and compares configurations: pass rate, first
+pass, tokens and wall time per attempt, with bootstrap intervals between arms. Each attempt resets the tree to the
+task's commit, so never enable it in a project you work in. The project must be the root of its repository with
+nothing tracked under `.agenthub/`, and the suite file lives outside its tree ([suite format and store](bench.md)).
+
+```bash
+ahub bench run ../suites/suite.json --arm baseline --repeat 5   # a person's: resets the tree, proposes the tasks
+ahub bench status                                     # the run in progress
+ahub bench compare baseline ripwire-on                # arms side by side, inconclusive below 5 attempts each
+ahub bench export --format csv
+```
+
+The dashboard's Benchmarks section shows the latest runs and, per suite with two or more arms, the comparison.
+
 ## Turns and undo
 
 In a git work tree the hub snapshots the project's tracked and unignored files (the
@@ -509,8 +694,9 @@ stays the default until an evaluation says otherwise (`docs/cooperbench.md`).
   held.
 - Verified context path. A hub-launched Claude session (`ahub claude`) gets the
   hub's hook before and after every tool call and at the end of each turn, in
-  its `--settings` next to the status line tee (a `--settings` of your own turns
-  them off). Codex gets context by steer into its running turn. Until a fact or a
+  its `--settings` next to the status line tee (a `--settings` of your own keeps
+  them, added to its own hooks, and loses only the tee). Codex gets context by
+  steer into its running turn. Until a fact or a
   one-line probe has been read back, the peer counts as unverified: for Claude
   the row Claude Code writes in its transcript for the hook's additional
   context, matched by tool use id and the offer's id; for Codex the steered
@@ -655,6 +841,83 @@ stays the default until an evaluation says otherwise (`docs/cooperbench.md`).
   turns the stale-notice drop off, for a controlled comparison only (the #106
   ablation in `docs/cooperbench.md`); the hub logs it at start.
 
+## Permission modes for running peers
+
+Use a plain terminal to inspect or change a running peer:
+
+```bash
+ahub permission
+ahub permission local ask-when-needed
+ahub permission kimi never-ask --yes
+ahub permission kimi ask
+```
+
+In the console Peers panel, `m` opens the three modes. Never-ask requires `y`,
+even for a typed command carrying --yes. Its confirmation says whether the peer
+uses its own tools outside the hub sandbox (Kimi), the hub sandbox/path guard/
+denylist (Pi and local), or native vendor boundaries (Claude and Codex).
+
+| Peer | ask-when-needed | never-ask | ask |
+| --- | --- | --- | --- |
+| Kimi Code CLI | ACP yolo | ACP auto | ACP default |
+| Codex | on-request for every outgoing turn/start | never for every outgoing turn/start | Restore the known native policy once, then stop overriding |
+| Claude | Allow resolving project file tools outside .agenthub/.git/.claude/.codex/.qwen/.kimi/.pi/.mcp.json | Hook allow for every tool | No hook decision |
+| Pi and local | Grant write/edit outside native agent configuration paths; read never asks; shell/git writes ask | Grant each tool once within the existing sandbox/guard | Normal approval handling |
+
+Kimi's map applies only to the actual Kimi Code CLI identity, not another ACP
+agent configured in kimi_cmd. Qwen and other ACP agents start fresh/resumed
+unmanaged without mode changes or mode-based startup refusals; runtime changes
+are refused until their own map exists.
+A set_mode timeout leaves the peer offline with mode unknown; inspect and
+restart before using it. Missing ids and refused startup changes name the mode.
+The benign Kimi live check verifies file edits and harmless shells in both
+modes without requests; risky-action behavior remains unverified.
+
+Claude's hook is installed in every managed launch. File grants use canonical
+real paths under the authenticated project root. Missing targets, symlink
+escapes, metadata directories and uncertain wildcard targets leave the native
+rules in charge. Grep/Glob path-bearing filters cannot bypass the exclusions.
+Other tools retain native decisions, which may already allow a harmless shell.
+Permission-only PreToolUse never marks Claude busy; former observation hooks
+retain their native-turn role. Settings are passed as a 0600 state file retained
+until that native launch exits. Live/unknown previous launchers keep their files;
+verified dead wrapper and native identities permit crash cleanup. Without
+separate native identity proof, old settings remain for manual inspection. Settings carry
+no inline caller values in argv. Status reports an unverified Claude hook as
+unverified. Unattended native sessions cannot take a runtime mode; restart
+without that native flag. Codex must be behind the hub proxy, and returning to
+ask requires a known native approval baseline. An offline or absent peer accepts
+`ahub permission <peer> ask` to clear its hub choice. Codex --unattended launch
+is refused under a non-ask choice; clear it with `ahub permission codex ask`
+first. A pending never-ask default cannot be confirmed for an unattended launch.
+
+Project defaults use permission_modes in .agenthub/config.json or
+.agenthub/config.local.json. Keys merge per peer; a local ask overrides the
+same peer's earlier default, while an empty local block preserves it. Every
+non-ask default start logs its mode and contributing filename. Automatic
+config effects stop at ask-when-needed. Git-tracked defaults are ignored and never
+offered for confirmation. Never-ask from an applied untracked file starts in ask
+and appears as a pending source-labelled console question at hub start.
+Only its separate console y enables that default; there is no boot --yes
+bypass. Only explicit n declines and keeps ask for that hub. Esc defers without declining
+and leaves approval keys usable; a refused y is not reoffered until its state changes. A successful runtime change removes that pending default. Runtime choices expire when the hub
+stops, and a later restart asks again for a never-ask config default.
+
+The CLI marker and console-role checks are operating policy, not a hostile-agent
+boundary. An agent able to run unrestricted shells may clear its markers,
+use --yes, or read the control token and act as the console. Hub tools,
+conductor operations and ordinary agent messages have no direct mode-changing
+or startup-confirmation operation, but those checks do not contain such a
+shell. Review the boundaries in [security](security.md) before choosing a mode.
+Modes never alter native sandboxes, hub path guards or denylists.
+
+Permission mode starts reconcile the current operator choice after native startup before bus delivery. Each non-ask start logs the mode and its config or runtime source. Dropped git-tracked defaults never appear as startup confirmations. Non-Kimi ACP peers run unmanaged, preserving their native fresh/resumed mode; permission commands refuse changes until a vendor map exists.
+
+Status shows non-ask modes and pending defaults, and each runtime change emits
+permission_mode (peer/from/to) with no tool arguments under events schema 1.
+The optional control requests preserve PROTOCOL; an older hub answers unknown
+and the CLI advises upgrading.
+
 ## Approvals and pauses
 
 Inspect permission requests in the terminal:
@@ -673,8 +936,8 @@ ahub permit <request-id> allow
 
 Use the exact option shown by `ahub tail`; do not approve an unresolved or
 unexpected request. On macOS a waiting request also raises a desktop
-notification that names the peer and, for Kimi, the tool, never what it would
-run. An unanswered request is cancelled after `approvals.timeout_s` (default
+notification that names the peer and, for Kimi and the local worker, the tool,
+never what it would run. An unanswered request is cancelled after `approvals.timeout_s` (default
 120, 30 to 3600) in `.agenthub/config.json`, and the console and log say so.
 Set `approvals.notify` to `false` to turn notifications off; a hub started
 without a project config file raises none. While Kimi waits for an answer its
@@ -734,12 +997,39 @@ has only `ahub status`, `ahub tail` and the task board.
 
 Resolution requires the current observed revision. A retry closes the old
 record and creates one linked attempt. Stale or conflicting resolutions fail.
+A refused or failed resolution puts back only that peer's queue and preface
+and keeps every pause, including budget and conductor holds. A storage failure
+stops the bus; a validation refusal leaves it running under the existing holds.
 If dispatching or accepted work has an uncertain outcome after a crash,
 the system marks it `needs_review`. Establish evidence before choosing
 `completed`, `retry`, or `discard`. Timeouts,
 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:
@@ -764,6 +1054,95 @@ 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`, and `hub.pid` from a
+  hub of 0.12.20 or older) a hub left when it did not stop cleanly, once no
+  process behind it is alive (a pid that now belongs to another process counts
+  as gone when the manifest carries the hub's signature, from 0.12.21);
+- 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
@@ -792,21 +1171,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 through 0.12.19), 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 0.12.21), 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.19 ahub upgrade --to 0.12.19 --dry-run
-bunx --package @staix/agent-hub@0.12.19 ahub upgrade --to 0.12.19 --yes
+bunx --package @staix/agent-hub@0.12.21 ahub upgrade --to 0.12.21 --dry-run
+bunx --package @staix/agent-hub@0.12.21 ahub upgrade --to 0.12.21 --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 through 0.12.19 (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 and 0.12.21 (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 |
 
@@ -838,17 +1217,19 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.19 --dry-run
+ahub upgrade --to 0.12.21 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.19 --yes
+ahub upgrade --to 0.12.21 --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
@@ -904,6 +1285,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.
 
@@ -911,6 +1306,170 @@ 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 when the operation's
+  coordinator is older than 0.12.21, 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), `resume`
+  starts it again from the operation's snapshot while the project's state
+  directory still holds it: it records the restart (status shows `restarts`),
+  closes the terminals the dead hub's peers were restored into (or finds them
+  gone), and relaunches those peers against the new hub, a session you had
+  accepted instead of the original included. A launcher still running from
+  the dead hub, or a session attached without an id, stops it until you end
+  that session. A target that dies again in the same `resume` stops it with the
+  restart count; look at its `hub.log` before resuming again. Without the
+  snapshot, or for an operation started by a coordinator older than 0.12.21,
+  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`. A record file that parses but holds a row that cannot
+  be evaluated (a hand edit, a damaged or a future layout) is read the same way
+  for the peer that row may belong to, and `ahub codex`, `ahub claude` and
+  `ahub pi --mode tui` write such rows back unchanged: fix or remove that row,
+  then `resume`. A launcher recorded by 0.12.12 or older is read with its own
+  unpinned signature too, so it counts as running when this command runs in
+  the same time zone and locale as the launcher did. `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. From
+  0.12.21 a hub's manifest and registry claim and a runner's record carry the
+  owner's process signature, so a pid that a reboot handed to another process
+  reads as gone by itself. Records written by 0.12.20 or older carry none and
+  are judged by their pid alone: if that pid now belongs to another process,
+  move the stale `status.json` and `hub.pid` aside together (with only one of
+  them gone the other still reads as an owner), 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.
+  An unsigned registry claim of such a hub, whose pid now belongs to another
+  process, still reads as starting, and no command clears it: after `ps -p
+  <pid> -o command=` shows that the process is not an `ahub ... daemon` of that
+  project, clear it with `sqlite3 ~/.agenthub/registry.db "UPDATE projects SET
+  instance_id = NULL, pid = NULL, claimed_at = NULL WHERE id = '<project id>'
+  AND pid = <pid>"` (`ahub projects --json` shows the id). 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. Once a stop-and-archive is recorded,
+  only the command `next` names continues it. On an operation whose
+  coordinator predates these commands it also marks the receipt `schema: 2`,
+  which every older release refuses before it acts: an older global `ahub
+  recovery resume` still prints "scheduled", but its runner exits without
+  touching the operation, and an older `ahub recovery abort` refuses with
+  "unsupported operation receipt". 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
@@ -1037,9 +1596,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
@@ -1112,8 +1708,8 @@ The hooks return no facts in advisory mode. A native Stop establishes an idle
 boundary; a subsequent PreToolUse marks activity. A delivery acknowledgement or
 task approval does not establish native idle. Restart the daemon and relaunch
 Claude after enabling the sweep so its session receives the hooks. A caller's
-`--settings` still wins: the launcher warns that native idle observation is off,
-and the sweep cannot verify that Claude session between turns.
+`--settings` keeps them: the launcher adds the hub's hooks to the caller's and
+warns only that the status line tee is off.
 
 `auto_reassign: true` explicitly allows an available alternative owner selected
 under the existing routing, role and PII constraints to receive the task at step
@@ -1238,3 +1834,28 @@ Quota pause and task handoff are separate; a context checkpoint neither pauses
 nor hands work over. Continue normally or deliberately restart into a fresh
 session with your chosen checkpoint as preface. No automatic restart or native
 compaction override is performed.
+
+## Pi tool refusals, exit causes and idle automatic restart
+
+Pi hub-task/conductor refusals proven before any task or board effect return
+their original `error:` text and are recorded as completed tool receipts.
+PII screening and its telemetry record may precede the refusal. An uncertain
+post-effect or storage failure remains pending: inspect it before repeating an
+action. Old pending receipts carry no proof of a past refusal and stay pending
+across startup. Conductor assignment and escalation entry checks explicitly opt
+into refusal typing; internal escalation after a saved review remains generic.
+
+Pi exit records show code or signal, turn/tool activity, whether teardown was
+expected, startup status, and the last tool's name without arguments. An
+unobserved native-terminal exit records unknown OS status. The console notice
+gives the next action, usually `ahub pi`, or says why automatic start is held.
+A requested replacement says the new owner is starting; internal failure
+teardown directs session inspection rather than claiming a person requested it.
+
+With `pi.auto_start`, an unexpectedly idle headless Pi is resumed on its
+verified persisted session once. The 60-second retry window rearms when the
+attempt settles; a second exit inside that window stays offline. Missing or
+invalid session history has no fresh fallback; inspect it before running
+`ahub pi`. Active turns/tools, failed startup, a superseded owner, native
+terminal exits, requested shutdown and recovery operations suppress this
+restart. Crash recovery's #66 recorded-session/fresh-start choices are unchanged.