@staix/agent-hub 0.12.20 → 0.12.21

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.20 and control protocol 16. 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
@@ -49,15 +49,17 @@ 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 `...`.
+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 LINK Q ! REVIEW PAUSE QUOTA MODEL |
+| Peers | PEER STATE MODE LINK Q ! REVIEW PAUSE QUOTA MODEL |
 | Approvals | ID PEER LEFT TITLE |
-| Tasks | ID STATE OWNER REVIEWER CLASS AGE 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
@@ -83,14 +85,43 @@ 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`
+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 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
+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
@@ -105,11 +136,30 @@ management or the final reset. Invalid values fail before connecting.
 | 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, 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
@@ -129,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
@@ -177,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.
@@ -216,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:
@@ -399,7 +452,10 @@ 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
@@ -498,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
@@ -607,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
@@ -753,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:
@@ -771,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
@@ -832,6 +997,9 @@ 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,
@@ -910,8 +1078,10 @@ The runtime reset (the default):
 - 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;
+- 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.
@@ -1001,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), 15 (0.12.17 through 0.12.19) or 16 (0.12.20), 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.20 ahub upgrade --to 0.12.20 --dry-run
-bunx --package @staix/agent-hub@0.12.20 ahub upgrade --to 0.12.20 --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), 0.12.20 (protocol 16) | 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 |
 
@@ -1047,14 +1217,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.20 --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.20 --yes
+ahub upgrade --to 0.12.21 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
@@ -1179,14 +1349,22 @@ next actions").
   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.
+  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), 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.
+- 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
@@ -1220,7 +1398,13 @@ next actions").
   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
+  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
@@ -1234,12 +1418,22 @@ next actions").
   <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
+  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
@@ -1249,7 +1443,13 @@ next actions").
   `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
+  `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
@@ -1508,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
@@ -1634,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.

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.20
+bun add -g github:STAIxBWLB/agent-hub#v0.12.21
 ahub setup
 ```
 
@@ -50,13 +50,14 @@ ahub say @kimi "run the tests and report"          # one peer
 
 ## The local worker
 
-`local` needs an OpenAI-compatible gateway. Put yours in `.agenthub/config.json`:
+`local` needs an OpenAI-compatible gateway. Put yours in `.agenthub/config.local.json`
+(machine-local, kept out of git by `ahub init`):
 
 ```json
 { "omniroute": { "urls": ["http://your-gateway:20128/v1"], "api_key_file": "/path/to/key" } }
 ```
 
-or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local] fixed_model`). Then `ahub local`. It works only inside the project, asks before it writes or runs anything (`ahub permit <id> allow`), and everything it executes is sandboxed.
+or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local] fixed_model`). Then `ahub local`. It works only inside the project, asks before it writes or runs anything (`ahub permit <id> allow`) unless you chose a permission mode for it (`ahub permission`), and everything it executes is sandboxed.
 
 ## Commands of a working day
 
@@ -74,11 +75,12 @@ More: `ahub help`. How it is built and why: [`docs/specs/2026-09-19-agent-hub-de
 ## Browser dashboard
 
 After `ahub up`, run `ahub ui` to open the local dashboard. It refreshes the
-conversation stream, peer queues, task board, budget windows and approvals every
-second. No build step, web server command or browser extension is needed.
+conversation stream, peer queues, task board, budget windows, approvals and
+benchmark runs every second. No build step, web server command or browser
+extension is needed.
 
 Use the page to pause/resume a peer, send a console message, propose/assign tasks,
-and allow/deny agent permission requests. Local-worker requests show no tool
+and allow/deny agent permission requests. Local-worker and Pi requests show no tool
 contents: inspect them with `ahub tail`, then use `ahub permit <id> <option>` to
 allow. They can be denied on the page. PII task details remain available only via
 `ahub task show <id>` in the terminal.
@@ -88,10 +90,10 @@ within 60 seconds. A session expires after one hour; run `ahub ui` again. Restar
 the daemon invalidates all links and sessions. The UI listener is started only on
 request, binds loopback and stops with the daemon. Remote access is not supported.
 
-The stream retains the latest 200 events since the dashboard listener was started;
-it does not load historical logs. An unopened dashboard has no listener or event
-buffer. A paused budget window cannot be overridden on the page; the CLI's
-`ahub budget resume <peer>` remains the explicit override.
+The stream retains the latest 200 events since the daemon started; it does not
+load historical logs. An unopened dashboard has no listener. A paused budget
+window cannot be overridden on the page; the CLI's `ahub budget resume <peer>`
+remains the explicit override.
 
 
 ## Concurrent project development (0.4.0)