@staix/agent-hub 0.12.30 → 0.12.32

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.30 and control protocol 16. Live verification
+This guide describes ahub 0.12.32 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -120,17 +120,22 @@ sounds on an action-count transition from zero, at most once per minute, never
 for a message alone. Plain mode prints the line only when the action count changes.
 Messages addressed to `user` remain attention items until the next key. Drawing
 adds no timer, network request or writable settings path.
-Tabs change with the digits 1 to 5 or with Left and Right (wrapping at both
+The operational tabs change with digits 1 to 5 or Left and Right (wrapping at both
 ends), never while a command is being edited or a choice is open; under a
 confirmation an arrow dismisses it like any key but y, without moving a tab. A pasted
-chunk can only edit the command line, but a read that holds nothing but arrow
-sequences is that many key presses, so a held key repeats its tab move. In the Events
+chunk can only edit the command line, but a read that holds nothing but arrow or
+Home/End sequences is that many key presses, so a held key repeats its move. Home
+or `<` jumps to a panel's first row and End or `>` to its last; the Events tab
+follows new events while the last row is selected and stays on a row you moved to.
+`w` opens the dashboard and `o` the pet window; `:ui --all` and `:pet --window --close`
+work on the command line too. In the Peers tab the planner's row reads `(planner)`, and
+`l` then `y` makes the selected peer the planner (`ahub settings set planner <peer>`). In the Events
 tab a row's header line is tokenized and coloured exactly as the same event in
 the stream; only the header is tab-flattened before tokenizing. Body lines retain
 the previous rendering and stay plain, as does command output; colour never changes
 what the panel's text says.
 
-Peers, Approvals, Tasks and Queue are tables with a header row. A column is as
+Peers, Approvals, Tasks, Queue and Settings 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.
@@ -141,6 +146,7 @@ meter keeps a fixed column at the right edge.
 | Approvals | ID PEER LEFT TITLE |
 | Tasks | ID STATE OWNER REVIEWER CLASS AGE TITLE STAGE |
 | Queue | ID PEER STATE REV AGE |
+| Settings | GROUP KEY VALUE SOURCE APPLIES |
 
 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`
@@ -189,7 +195,27 @@ In Tasks, `a` assigns the owner in ordinary open states and the reviewer in
 the corresponding role, and `r` reviews only in `in_review`. In Queue, `r`
 prefills `discard` for a queued row and `retry` for a needs_review row, with the
 action still editable before confirmation. `completed` is never the default.
-Every resolution needs a reason. Queue `discard` removes queued originals or
+Status, console notices and `route explain` show every held row with its id, sender, kind and age. The hub completes rows made entirely of superseded hub workflow notices or presence items, recording an ids-only reason and the hub actor. Mixed messages, live task notices and unknown references remain held. A Claude session without channel support safely returns unseen pushes for `hub_inbox`; a thrown notification write remains uncertain.
+
+Claude channel/pull sessions, Codex and Pi may call `hub_delivery_retry { delivery_id }` for their own
+`needs_review` row once. Its tool results show held-row count, ids, senders,
+kinds and age, never message bodies or task text (up to 32 rows/4 KiB, with an
+explicit truncation notice). The redelivery starts with a fixed warning that
+the earlier attempt is uncertain and its effects must be checked before acting.
+The warning fits within the existing journal body limit. If needed, only the rendered copy is clipped at a Unicode character boundary and ends with an explicit cut marker; the original message is retained. Consumed-retry proof follows every coalesced original atomically with a successful checkpoint, surviving safe failure, stale removal, pruning and restart.
+
+Any earlier explicit retry in the same recipient's lineage, including a person's
+retry, leaves a later hold for the person. A busy peer's request only requeues
+the originals; delivery waits for idle and retains all pauses and recovery holds.
+Hub presence prefaces are mutable context, so they do not consume or inherit a
+message's retry allowance and never receive the uncertain-retry warning.
+The tool cannot complete or discard a row. If a recovery snapshot lacks retry
+history, or older pruned retry records cannot be mapped, the affected message
+lineages require a person; unrelated new messages retain the one-retry option.
+
+The local worker and headless ACP peers, including Jcode, receive tools only inside a delivered turn. A hold prevents that turn, so these delivery-only transports do not offer recipient retry; their held hints ask the person to resolve the row. Ordinary messages stay queued. This restriction follows the current transport, not the vendor name: Kimi TUI remains pull-only and can request its one retry.
+
+Every console resolution needs a reason. Queue `discard` removes queued originals or
 settles a needs_review receipt; it never cancels a task or native turn.
 
 `ahub task unassign <id> [--role owner|reviewer] [--revision N]` is the terminal
@@ -464,6 +490,26 @@ Tool-call receipts survive daemon restart; an interrupted operation with an
 unknown outcome must be reconciled before repeating it. Cancelling a Pi turn
 does not automatically hand its task to a cloud peer.
 
+For assigned, non-private work, `hub_task_spec` reads the named GitHub issues
+through the hub's authenticated, bounded read path. `hub_check_start` runs an
+exact Git ref's permitted tests or typecheck in the opt-in isolated container
+runner (`checks.runner: "container"`); `hub_check_result` and `hub_check_cancel`
+read or cancel that owned run. Missing spec/check capability refuses the
+assignment early; it never grants host commands, credentials or broader sandbox
+access. Receipts distinguish exact source/tree/lockfile, platform, exit and
+uncertain or cancelled outcomes. See [bounded spec and check access](security.md#bounded-task-specs-and-isolated-checks-418)
+for the authorization and resource bounds.
+
+Retention bounds inactive valid check receipts to 200 records and the newest 20
+full outputs, excluding active runs. Full output is also consumed by the owner
+result read or expires after 24 hours.
+Malformed or unreadable receipts are a retention exception: their receipt bytes,
+output and staging stay for inspection, with ID-only warnings separate from
+unknown container-owner warnings. Maintenance skips them while continuing valid
+retention; it never deletes an unknown container. See the security contract for
+the same-user parent-swap cleanup limitation. These source guarantees do not
+establish the separate native macOS acceptance leg.
+
 The `mlx/fast` alias now defaults to an externally managed Ollama MLX backend.
 Install and start Ollama separately, with `OLLAMA_NO_CLOUD=1`,
 `OLLAMA_NUM_PARALLEL=1`, `OLLAMA_MAX_LOADED_MODELS=1`, and a finite
@@ -559,7 +605,8 @@ PID-name matching. See the operations guide and the
 
 ## Install and start
 
-Use Bun 1.4.2 or newer. Install the released package and install its Claude
+Use Bun 1.4.2 or newer. Source checks and CI use the version pinned in
+`.bun-version` (currently 1.4.2). Install the released package and install its Claude
 channel plugin:
 
 ```bash
@@ -923,7 +970,7 @@ The daemon checks its selector at hub operation entry and before candidate/count
 
 Run `ahub memory profile-check [--json]` from the person's terminal for the read-only preflight. It identifies live registry owners by signed process identity and authenticated daemon replies, then reports their loaded memory package and bound home/profile. The receipt names the current `AGENTHUB_HOME` registry scope; zero results establish no live daemon in that inventory, not system-wide process absence. Inventory and check separate custom registries too when they share `AMEM_HOME`. A missing or unreadable runtime receipt never counts as a different home or permission to migrate.
 
-Before real migration, first upgrade every hub sharing the home to 0.12.30. Obtain positive ready or unbound/quiesced receipts in every relevant registry; then quiesce consumers and close bound handles before changing the selector. A matching ready handle proves compatibility but is still an open handle. Verify synthetic cross-writes before the separately approved real migration, then reopen through the supported session-preserving lifecycle afterward. Merely installing this release does not authorize migration or provide live capture/device-sync evidence.
+Before real migration, first upgrade every hub sharing the home to 0.12.30 or later. Obtain positive ready or unbound/quiesced receipts in every relevant registry; then quiesce consumers and close bound handles before changing the selector. A matching ready handle proves compatibility but is still an open handle. Verify synthetic cross-writes before the separately approved real migration, then reopen through the supported session-preserving lifecycle afterward. Merely installing this release does not authorize migration or provide live capture/device-sync evidence.
 
 Managed agents read through `hub_memory_search`, `hub_memory_show` and `hub_memory_graph`, with the server's project identity, the `memory_read` capability and current privacy screening. They cannot supply another project; private turns are refused. The tools bound UTF-8 input/output, screen before counts and truncation, and exclude their arguments/results from hub-managed capture. `hub_memory_correct` has its own `memory_correct` capability and records a screened correction candidate, not a note change. See [the complete memory contract](memory.md) for caps and refusal semantics.
 
@@ -1390,6 +1437,16 @@ override them.
 
 ## Settings from the dashboard and the terminal
 
+In `ahub console`, press `6` for Settings. Existing operational-tab arrow cycling
+is unchanged; from Settings, Left returns to Events and Right to Peers. Select a
+row and press `e` to edit: value, daemon preview, nonempty reason, then `y`. Press
+`u` to preview and confirm undo. Undo binds the key and exact undo-record digest;
+if another write replaces that record, preview again. For busy roster removal,
+the panel names `ahub roster remove <peer> --now`, which explicitly stops an owned
+runtime or detaches a native session during its active turn; the panel does not force it.
+Esc cancels, and pasted confirmation text cannot
+write. This panel uses the current authenticated daemon connection.
+
 The dashboard's Settings section and `ahub settings` show and change the same
 closed list of settings (issue #269). Run them from a plain terminal:
 
@@ -1401,17 +1458,22 @@ ahub settings set routing.classes.implement.peers codex,kimi,pi
 ahub settings set permission_modes.kimi ask-when-needed
 ahub settings set research.enabled inherit   # remove the machine-local value
 ahub settings undo                 # put back the file the last write changed
+ahub settings reload               # validate and apply the complete four-file candidate
 ahub ui --settings                 # dashboard with a 15-minute settings session
 ```
 
 | Group | Keys | Stored in | Applies |
 | --- | --- | --- | --- |
 | Permissions | `permission.<peer>` (the mode now) | the running hub only | at once |
-| Permissions | `permission_modes.<peer>` (the mode at hub start) | `config.local.json` | next hub start |
+| Permissions | `permission_modes.<peer>` (the default mode) | `config.local.json` | next peer start |
 | Start | `peers.pi.start_mode`, `peers.codex.start_mode`, `peers.kimi.start_mode` (`tui` or `headless`) | `config.local.json` | that peer's next start |
-| Start | `pi.auto_start` | `config.local.json` | next hub start |
+| Start | `pi.auto_start` | `config.local.json` | next startup/recovery auto-start decision; never starts a peer merely on reload |
 | Routing | `routing.stay_switch`, `routing.classes.<class>.peers`, `.escalate_to`, `.route`, `.pi_backend` | `routing.local.toml` | at once |
-| Switches | `research.enabled`, `approvals.notify`, `snapshots.enabled`, `coordination` | `config.local.json` | next hub start |
+| Switches | `research.enabled`, `approvals.notify`, `snapshots.enabled` | `config.local.json` | live, without disturbing an active turn |
+| Switches | `coordination` | `config.local.json` | newly created tasks only |
+| Switches | `task_sweep.enabled`, `.auto_reassign`, `.interval_s`, `.unaccepted_min`, `.idle_min`, `.review_min`, `.ready_min`, `.ladder_min` | `config.local.json` | live; reschedules the sweep timer |
+| Routing | `tasks.wip_limits.<peer>` | `config.local.json` | live |
+| Roles | `planner` (the one peer that plans) | `config.local.json` | at once |
 
 - Writes go only to `.agenthub/config.local.json` and `.agenthub/routing.local.toml`,
   the machine-local files (`ahub init` ignores both in git). The shared
@@ -1423,8 +1485,28 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
   file each value comes from. `--preview`, and the dashboard's Preview button,
   show `ahub route explain` for the open tasks before and after, or what a
   permission mode grants, and save nothing.
-- A row shows the value in force, its source file, when it applies, and for a
-  value read at hub start what the next start will read (`Pending restart`).
+- A row shows running and file values, source and apply class (`live`, `next use`,
+  or `restart`). Pending restart keys and reasons also appear in status, console
+  and dashboard, including startup-only blocks outside the editable registry.
+- Settings writes and undo, the dashboard Reload configuration button and
+  `ahub settings reload` use one complete validation/apply path. Debounced changes
+  of config.json, config.local.json, routing.toml and routing.local.toml use it too,
+  including atomic file replacement. Invalid candidates apply nothing and emit
+  one bounded error notice. Valid but unauthorized keys retain their accepted value and are reported per key; other eligible changes still apply. Recovery/shutdown hold reloads.
+- Individual writes and undo publish only the named setting. Other file edits remain unapplied.
+- `ahub settings reload` lists guarded keys with complete before -> after values (including full argv) and any planner/conductor holder effect. It requires an interactive terminal and exact `y` within 30 seconds before adopting them. Oversized previews remain unapplied and must be split or reduced. Candidate bytes or accepted state changes invalidate that confirmation. Watchers and ordinary dashboard reloads never confirm a raise.
+- Privacy tightening (local PII constraints/screening, added PII patterns, nonholder role reductions and explicit capability-list narrowing) is automatic, including tracked files. A planner/conductor holder change is guarded even when a role list shrinks; deleting a restricted capability entry restores all capabilities and is guarded. Reload checks the actual files' Git provenance. Changed machine-local or raising
+  values from tracked/unverifiable files are refused; an ordinary dashboard or
+  watcher cannot adopt unrelated raising local edits. A settings session cannot
+  adopt routing fields outside its editable registry. Existing confirmation and
+  roster lifecycle fences remain; use the confirmed roster setting for membership.
+Pi relay model aliases (`pi.dgx_coding`, `pi.dgx_fast`) and `routing.pi` retain their running values until restart, because existing native sessions use the published relay catalogue and context contract. Routing policy changes apply to future decisions; local model/target changes apply at the next peer or sidecar creation.
+
+- Runtime/client ownership still requires restart for memory handles and sync,
+  gateway/MLX, runner/check commands, profile/tool contracts, converters, existing
+  session privacy/sandbox policies, the terminal provider and benchmark environment.
+  The exhaustive reasons are in the issue #439 spec amendment. A pending file value
+  is not applied to the running consumer. Coordination creation pins last for the daemon lifetime; a restart re-pins retained rows to its startup mode.
 - `ahub settings undo` (the dashboard's "Undo last write") puts back the one
   previous version of the file the last write changed. It refuses when that
   file was edited since, and when it would put a stored never-ask back (set it
@@ -1437,10 +1519,11 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
   `.agenthub/routing.local.toml`: run `ahub init` again, or add it. A
   `permission_modes` value is read only from a file git confirms nobody
   committed (config trust); where the hub will not read what was written, the
-  reply and the Settings row say so.
+  reload refuses the guarded candidate and the Settings row identifies the file.
 - Authority: a dashboard opened with `ahub ui` reads settings, lowers a mode to
-  `ask`, turns `pi.auto_start` off, sets a start mode back to `tui` and changes
-  the Switches group. Everything
+  `ask`, turns `pi.auto_start` off, sets a start mode back to `tui`, sets a WIP
+  limit to 0, turns `task_sweep.enabled` or `.auto_reassign` off and changes
+  the other Switches. Everything
   else needs `ahub ui --settings`, whose session may raise for 15 minutes, or
   `ahub settings` in a terminal. `never-ask` needs the peer id typed in the
   dashboard, or `--yes` in the terminal, and a stored never-ask default still
@@ -1505,8 +1588,10 @@ The configured `kimi_cmd` must be a single executable or end in exactly `acp`;
 the TUI uses the executable or drops that final word. Other wrappers are refused
 with the headless command rather than guessed.
 
-The TUI is pull-only. Its model reads `hub_inbox` at the start of work and before
-reporting, and shares results explicitly with `hub_send`. Status, the console and
+The TUI is pull-only. Its model reads `hub_inbox` at the start of work, between
+steps of longer work and before reporting, and shares results, and mid-work
+blockers or changed contracts, explicitly with `hub_send` addressed with `to`
+(progress-only notes `[FYI]`). Status, the console and
 the dashboard show `pull-only`, the waiting count and the last inbox read. Messages
 and important markers do not push or interrupt it. There is no hub busy state,
 watchdog, console approval, hub permission mode, context reading, automatic quota
@@ -1710,6 +1795,28 @@ 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.
 
+## The planner (#455)
+
+One peer plans: it proposes and splits tasks, grooms the backlog and gets the
+backlog and sweep notices. `ahub status` prints it with its source, the
+dashboard's Agents view shows a Planner badge, and the console marks its row.
+
+- `setting`: `planner` in `.agenthub/config.json` or `config.local.json` (the
+  machine's file wins). That peer is the only planner; every other peer loses
+  the role. It is one of `claude`, `codex`, `kimi`, `qwen` or `jcode`: the
+  hub-sandboxed `pi` and `local` never plan.
+- `roles`: with no `planner` key, the `roles` planners stand. That is `claude`
+  by default.
+- `automatic`: when no rostered peer holds the role, the hub gives it to the
+  first rostered peer of that list. It recomputes this at start and after
+  each roster change, and writes nothing to disk.
+
+Change it with `ahub settings set planner codex`, the dashboard Settings row
+(a settings session, `ahub ui --settings`) or `l` in the console. Planning
+authority and the backlog notices move at once. The new planner's role text
+updates at its next start. `ahub settings undo` puts the previous planner
+back. Agents cannot change it.
+
 ## Resetting a project's hub
 
 `ahub reset` returns a project's hub to a clean state. Without `--yes` it is a
@@ -1842,21 +1949,21 @@ section is what they run.
 
 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 through 0.12.30), 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 through 0.12.32), 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.30 ahub upgrade --to 0.12.30 --dry-run
-bunx --package @staix/agent-hub@0.12.30 ahub upgrade --to 0.12.30 --yes
+bunx --package @staix/agent-hub@0.12.32 ahub upgrade --to 0.12.32 --dry-run
+bunx --package @staix/agent-hub@0.12.32 ahub upgrade --to 0.12.32 --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 through 0.12.30 (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 through 0.12.32 (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 |
 
@@ -1888,17 +1995,18 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.30 --dry-run
+ahub upgrade --to 0.12.32 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.30 --yes
+ahub upgrade --to 0.12.32 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
+ahub recovery reattach <operation-id> codex|claude|pi
 ahub recovery dispose [<operation-id>] --fresh-session <peer> --reason <text>
 ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>
 ```
@@ -1962,7 +2070,9 @@ A lost commit or start reply is reconciled against the actual daemon identity,
 package digest, terminal binding, and phase receipt. An uncertain terminal
 creation is never repeated blindly. Recovery retains the exact-pinned first-party memory package with the preserved runtime, includes its identity and bytes in the digest, and refuses missing, symlinked or changed retained dependencies instead of resolving a mutable ancestor/global installation. It does not copy the full dependency tree.
 
-After creating a managed terminal, the coordinator saves its binding before waiting up to 90 seconds for authenticated attachment to the expected target hub and conversation. An idle terminal alone is not attachment proof. Timeout retains the terminal and its diagnostic receipt; resume waits on that same binding rather than opening a duplicate. The zero-turn Claude exception still applies only when no original transcript exists. If Claude shows its development-channel confirmation screen, confirm it in
+After creating a managed terminal, the coordinator saves its exact handle, incarnation and worktree before waiting up to 600 seconds (10 minutes) for authenticated attachment to the expected target hub and conversation. A pending or failed creation receipt also waits when the current target has a verified live launcher; its saved binding retains the pending/failed origin across interruption. An idle terminal alone is not attachment proof. Without a current launch record, a confirmed-ended row for another terminal and an attached session still reporting no id keep the chosen terminal waiting within the same bound; a late matching record continues that wait. Live replacement and unreadable records still block. Only non-offline session ids count, and older-instance launchers are checked before declaring a launch gone. Timeout retains the binding and diagnostic receipt; resume waits on that same binding rather than opening a duplicate.
+
+The wait checks the selected launcher's signed identity on each poll. When that exact launcher exits and the target confirms no session or other live launcher, a pending-origin wait (including a new terminal) records failure and offers the failed-restoration choices, including fresh-session for Codex or Claude. A failed-origin wait returns to its existing retry path. A replacement terminal, missing or unreadable launcher identity, unreadable target or different attached conversation blocks without treating unknown as gone. Success clears the waiting origin and preserves exact terminal/session revalidation. A launcher from an older target instance still blocks without another terminal. The 10-minute limit matches terminal creation readiness; terminal idle can precede native resume and MCP handshake completion. The zero-turn Claude exception still applies only when no original transcript exists. If Claude shows its development-channel confirmation screen, confirm it in
 the captured terminal, then run `ahub recovery resume <operation-id>`; resume must not open a duplicate terminal.
 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:
@@ -1997,6 +2107,16 @@ through a pipe, the JSON plan, the `ahub: blocker:` lines and the exit codes are
 unchanged. The screens add no way to change an operation: every choice runs one
 of the commands in this section for you, so that command's refusals decide.
 
+The screens use the console palette and `--color=auto|always|never`, with the
+same `NO_COLOR` and `TERM=dumb` precedence. Auto colours a suitable TTY; explicit
+always has the console's override behaviour. Raw JSON bypasses colour and width
+handling. Default and never preserve the existing pipe, dry-run, status and
+dispose output byte for byte. Presentation flags go after the command, for
+example `ahub recovery --color=never` or
+`ahub recovery status <operation-id> --json`. An explicit `--json` returns only
+the raw document, without a human suffix. `upgrade --json` reviews a JSON plan;
+`--yes` is still needed to apply it without the interactive review.
+
 The plan screen lists each project with its hub version and, per attached peer,
 its state, how it runs (`TUI` in a terminal the plan bound to its session,
 `headless` as the hub's own process, `own` for a session the hub did not
@@ -2029,23 +2149,35 @@ plan shows the ended agents as offline.
 
 After apply the command stays attached and prints each step as the receipt
 records it, and while a source is being prepared, what it still waits for.
+Each reported step has a status mark and elapsed observation time. Resume lists
+only steps observed on that attempt and says `resuming from ...` once. Its stage
+step really runs again and is labelled `checking retained release`. Waits use
+the coordinator's actual recorded start and deadline, for example
+`[waiting] alpha: restoring Codex and Pi sessions (waiting 2m10s of 10m)`.
+Older receipts without timing metadata say `timing unknown`; updatedAt is never
+used as a substitute. Timing-only save failures log a warning and do not fail
+the operation. Stable waits print only on change and at most once per minute.
+Approval waits point to `ahub console`; native attachment waits point to the
+recorded launch and conversation. Korean text and
+long paths wrap to the measured width on plan, progress and menu screens.
 Enter opens the operation's screen while the runner works on. Ctrl+C leaves the
 command, at any prompt and while following, and never stops the runner: the
-`left:` line names the command that comes back to the screen, with the
-operation's own coordinator, because the installed `ahub` is the older release
-until the upgrade ends. A Ctrl+C between `a` and the start of the operation
+`left:` line names `ahub recovery status <operation-id>`. Use `--verbose` for
+the internal command with the operation's retained coordinator, because the
+installed `ahub` may still be the older release until the upgrade ends. A Ctrl+C between `a` and the start of the operation
 starts nothing. A prompt for a reason that is answered with
 Ctrl+C or the end of input ends nothing.
 
 The operation's screen also opens first whenever an operation holds the lock,
 and for bare `ahub recovery`. It shows the phase and step, each project's phase
-and effect receipts and the error, then the choices that `status` lists under
+and human outcome labels, then What happened / Why / What to do and the choices that `status` lists under
 `next` for the same receipt and live state:
 
 | Key | Runs | Offered when |
 | --- | --- | --- |
 | `r` | `recovery resume`, then follows | resume can get past what is live |
 | `c` | `recovery abort` | no runtime was stopped and no terminal effect or commit request is recorded |
+| `a` | `recovery reattach <id> <peer>` | the recorded detached session is eligible for reattachment |
 | `f` | `recovery dispose --fresh-session <peer>`, after a reason | a Codex or Claude restoration failed |
 | `e` | `recovery dispose --stop-and-archive`, after a confirmation and a reason | every unverified project reads as running, stopped or missing |
 | `x` | `e`, then the reset below | as `e` |
@@ -2055,6 +2187,26 @@ When more than one restoration failed, the second and later peers get
 `f-<peer>`. `s` refreshes the screen, `j` prints the receipt as JSON and `q`
 leaves the operation as it is.
 
+The marked recommendation is a read-only Enter default: refresh the plan, follow
+an active runner, read the receipt or refresh the operation. Apply, resume and
+reattach require their explicit keys; buffered Enter never starts them. Unknown failures recommend
+reading `j` before retrying effects. A wait whose runner cannot be verified is
+shown disabled with its reason, and cannot run a command. Stop, archive, reset
+and fresh-session choices carry a warning and name the consequence before the
+person confirms. Raw receipt keys and the original recorded error are available
+with `j` or `--verbose`. The four preservation failures name the actual failed
+queue, manual-pause, board or budget comparison; an older untyped cause remains
+unknown rather than being guessed from its text.
+
+Completion and stop-and-archive use a human summary on a TTY. It separates the
+outcome, recorded plugin/global installation effects, remaining work and the
+per-peer session commands. An optional fresh read-only inspection names the
+current hub version; a failed reading says `runtime unknown`, never a guessed
+version from the plan. The summary performs no lifecycle action. Use `j` or
+`--json` for the full receipt; JSON is intentionally exempt from human wrapping.
+For a long command, copy the exact single-line value from `j` or the status JSON;
+the width-wrapped human preview is for reading.
+
 While a runner is only waiting for its source to get quiet (step `prepare`, no
 effect recorded), `c` stops that runner and then aborts. It is offered only for
 a runner whose claim carries a process signature that still matches; a claim
@@ -2082,7 +2234,8 @@ or cancel and upgrade later.
 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`);
+receipts (`closed:<peer>` as `done` or `pending`; `restored:<peer>` as
+`pending`, `waiting:pending`, `waiting:failed`, `done` 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
@@ -2092,7 +2245,11 @@ 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
+release, whose `recovery` lacks these commands. The published 0.12.30 CLI also
+mislabels tagged waiting receipts as done and can hide the fresh-session choice,
+even when its status command exists. Use the printed preserved-source
+coordinator for status, resume and disposition; do not decide from that older
+CLI's receipt display. 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
@@ -2130,6 +2287,11 @@ next actions").
   use its offered `ahub recovery resume <id>`. Resume rechecks the source and
   reconciles a commit that may already have been requested. A busy read while
   that committed source is stopping stays inside the existing shutdown wait.
+  A resumed prepared receipt with `commitSent` also polls an unavailable source
+  within the 30-second shutdown bound, including initial database contention,
+  without sending another commit, re-preparing or closing terminals again. Only
+  confirmed `stopped` permits target startup; a replacement instance refuses, and
+  expiry retains the prepared receipt and the same operation for another resume.
   A stop-and-archive that meets contention instead says to retry that
   disposition; resume remains refused while abandonment is partway. Successful
   abort, fresh-session choice and disposal clear the earlier failure annotation.
@@ -2198,11 +2360,23 @@ next actions").
   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 reattach <operation-id> codex|claude|pi` is person-only, including during live verification: an agent shell cannot delegate it. Name the operation and exactly one peer; session, backend, model and terminal overrides are not accepted. Use the exact operation-coordinator command printed by status or its blocked guidance. It repairs only that peer and leaves the operation blocked; run the offered `recovery resume` command to continue the remaining steps.
+  The CLI delegates only when the retained coordinator supports reattach. An existing older coordinator without that action uses this release's implementation instead; a missing receipt, retained coordinator path or coordinator file prints inspection/recovery guidance and starts no session.
+  A peer that attached and later went offline can be re-restored once when its saved terminal is positively orphaned or missing and no current or older operation launcher may still run. The recorded session id and Pi session file stay fixed; the new terminal binding is saved before waiting for authenticated attachment. A second detach blocks. An unreadable terminal, changed incarnation or worktree, disconnected-only evidence, truncated inventory or live/unknown launcher does not authorize another terminal.
+  Recovery status names the saved Codex thread, Pi session file and Claude session, the terminal evidence, and the applicable reattach command. A different attached conversation remains a strict refusal.
 - `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.
+  A session the operation already reattached keeps that repaired provenance
+  across target restarts and is never replaced automatically. Its
+  loss can be accepted only after the restoration reported the recorded Claude
+  transcript or Codex rollout as positively missing, naming the checked path;
+  dispose checks that path again before saving the choice and otherwise refuses
+  with "recorded conversation is not positively missing". Under `--live-test`
+  this repaired-session choice is refused even where an ordinary fresh session
+  may be delegated.
 - `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`
@@ -2249,7 +2423,8 @@ next actions").
   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.
+  database. The global CLI was not promoted. The archive summary distinguishes completed target startup and plugin installation from remaining global CLI installation, and prints recorded-session commands: `ahub codex resume <thread-id>`, `ahub pi --session-file <path>`, and the Claude reconnect command. On the next `ahub up`, `pi.auto_start` resumes the archived operation's recorded Pi session rather than choosing a fresh conversation. Unknown or conflicting archived identity refuses that automatic resume.
+  That session is kept as a bookmark, `.agenthub/state/recovery-continuity.json`. When its session file can no longer be resumed or does not match it, the hub archives the bookmark and starts no fresh session in that start; the error names `ahub pi --mode <mode> --session-file <managed-file>` for choosing one. An invalid or unreadable bookmark, or session storage that cannot be verified, starts nothing, keeps the bookmark and prints the `mv -n` command that archives it after inspection. The bookmark is retired once Pi attaches with a different authenticated session.
 - 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
@@ -2459,6 +2634,22 @@ the capability is absent. It never rewrites these settings. Explicit
 refused before any local startup. Re-enable MLX or explicitly migrate the
 recorded launch before recovery.
 
+## Task stalls and cancellation
+
+A ready task with an ineligible reservation, no eligible peer or a cancelled dependency shows an ids-only stall cause in status and the Tasks panel. The hub reports a cause once, repeating only when the cause changes or the task is re-planned. It directs ownerless advice to the designated planner's next bounded preface and the configured supervision stream, otherwise the person's attention list; it does not create an extra ordinary turn beside backlog batching. Configure the missing capability, assign another eligible peer, re-plan or cancel the task as appropriate; a reservation never bypasses routing guards.
+
+An offer to a pull-only peer adds an advisory "open <peer>: task #N is waiting for it" attention item. It clears when that exact offer is accepted, declined, superseded or genuinely delivered and settled to the addressed peer. Another inbox read, an accepted-only receipt or a person's queue completion does not prove it was read. The attention item survives peer detach and daemon restart using the saved offer's pull-only flag; it does not alter delivery state.
+
+The person can retain superseded work as closed history:
+
+```sh
+ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]
+```
+
+The console also offers cancellation with the selected task's flow revision. Approved tasks cannot be cancelled. The planner's `hub_task_cancel` tool is limited to its own unaccepted backlog/proposed work; previously accepted work requires the person. Cancellation sends the former owner/reviewer a stop notice, releases overlap/reservation participation and keeps dependents blocked with a cancelled-dependency notice. It does not stop a native turn, delete a worktree or write an outcome memory note. Cancelled work is closed history, counted separately from approved work; it does not satisfy an approval dependency. A still-running private turn keeps its privacy fence after cancellation. Use the displayed revision to avoid acting on a task that changed while it was selected.
+
+The daemon advertises `task_cancel`; a current CLI refuses cancellation against older daemons. Recovery retains verified target features beside its immutable root/digest, reuses them on resume and checks only sources not yet past commit; a legacy receipt without that evidence needs a target probe only before commit. Upgrade/restart refuses a target without this feature while cancelled rows exist and names their ids. No cancelled row is rewritten as approved. An old binary launched by hand remains unsupported: it can count cancelled work as open or fail to move it. Use a compatible coordinator instead. Live task cancellation and sweep enablement are separate post-release operations.
+
 ## Task idle sweep
 
 The between-turn task sweep (#186) is disabled by default. Set `task_sweep` in
@@ -2472,6 +2663,7 @@ The between-turn task sweep (#186) is disabled by default. Set `task_sweep` in
     "unaccepted_min": 60,
     "idle_min": 120,
     "review_min": 120,
+    "ready_min": 60,
     "ladder_min": 30,
     "auto_reassign": false
   }
@@ -2483,6 +2675,8 @@ at least 1; timeouts are bounded to the platform timer limit. Each threshold
 measures time since the last real task history event. A ladder record does not
 refresh that activity; a new event resets the ladder even at the same timestamp.
 
+Ready proposed tasks without an owner use `ready_min` and the `ready-unassigned` ladder; unresolved or cancelled dependencies do not become ready. A person's unassignment suppresses this automatic ladder until a later explicit assignment or reservation. Planner-pulled work keeps its reserved peer and current WIP/hold admission; an unavailable or full reservation never selects another worker.
+
 The first overdue sweep sends the assigned owner or reviewer one normal task
 reminder. After `ladder_min`, the next sweep notifies the console and available
 planner-role peers. After another interval it reports a reassignment suggestion
@@ -2564,13 +2758,15 @@ registry directories and a scrubbed environment. The normal 20-second test timeo
 both legs. Successful fixtures are removed; a failed pair prints its preserved
 fixture location with test and leak evidence for inspection.
 
-The required Linux CI job `seeded guards` follows the ordinary checks; it does not
-repeat on macOS or run recursively inside `bun test`. The runner reports every
+CI runs the pairs as four Linux shards (`bun scripts/seeded-check.ts --shard i/4`,
+every fourth pair, still sequential within a shard) beside the ordinary checks; the
+required job `seeded guards` passes only when all four shards passed (#457). The pairs
+do not repeat on macOS or run recursively inside `bun test`. The runner reports every
 pair's elapsed seconds and the total runtime. A green ordinary check alone does
 not prove these pairs.
 
-The full CI gate tests the PR head tree on Linux and macOS, followed by the
-sequential seeded-guard job. Main and release jobs reuse only a successful full
+The full CI gate tests the PR head tree on Linux and macOS, with the seeded-guard
+shards running at the same time. Main and release jobs reuse only a successful full
 PR or push check with the identical Git tree and all three successful jobs. An absent or
 unreadable result runs the main gate again and refuses release. A manual
 `prepare_bundle` dispatch builds reviewable plugin assets without publishing;
@@ -2847,6 +3043,9 @@ Qwen controlled recovery and automatic crash resume load the recorded conversati
 
 Use ahub roster add jcode, then ahub jcode --mode headless [--model <alias>] [--provider-profile <name>]. The person launcher configures only agent-hub-jcode in .jcode/mcp.json; run ahub init afterwards to ignore the untracked machine-path file. Conductor/dashboard starts read that entry without editing it. Preview starts nothing, and ahub stop jcode stops only the owned private daemon/ACP groups. jcode_cmd, jcode_home and jcode_provider_profile are machine-local and never editable from settings.
 
+After upgrading to the recipient-retry release, a Jcode project MCP entry written before `AGENTHUB_DELIVERY_ONLY` was added is intentionally stale. Once per project, the person runs `ahub jcode --mode headless` before using conductor/dashboard starts. The launcher rewrites only the owned entry with the delivery-only marker, preserving foreign entries and refusing collisions; recovery relaunches already use this CLI path. Readiness checks never rewrite the file, and an explicit false marker or any other drift remains refused. Until that rewrite, daemon starts keep their actionable stale-entry refusal rather than advertising a retry tool Jcode cannot use.
+
+
 Native policy is unmanaged and has NO hub sandbox; no permission_modes.jcode or runtime mode mapping is invented. Quota and consumption remain unknown. Version 0.94.0 cannot prove native session/load identity, so attached Jcode blocks controlled recovery before effects and crash recovery asks for deliberate native reopening. A requested load without an echoed identity refuses; no fresh session is presented as restored. Provider/tool/native teardown receipts remain unverified in the pinned contract report.
 
 # Headless ACP watch (#286)
@@ -2975,7 +3174,7 @@ Create a phase with `ahub release new <name> <goal> <order>`, inspect `list` or
 `show`, and set planned start/cut/ship with `plan <name> <revision> <dates-json>`.
 `activate`, `freeze`, `ship` and `drop` need its current revision. Only a person
 freezes, ships, drops or edits frozen scope. Ship records the first ship time
-only after every member is approved or moved out; it runs no tag or publish.
+only after every member is approved, cancelled or moved out; it runs no tag or publish.
 The dashboard shows phase progress, blocking dependencies, dates and remaining
 work. Actual task dates come from execution/review/approval history, never input.
 

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.30
+bun add -g github:STAIxBWLB/agent-hub#v0.12.32
 ahub setup
 ```
 
@@ -30,6 +30,21 @@ and upgrade or crash recovery, see the [operations guide](operations.md). To
 move running projects to a newer release later, run `ahub upgrade` in a
 terminal: it reviews the plan with you, applies it and follows it.
 
+## Upgrading to 0.12.32
+
+The upgrade runs with the target release's own coordinator. If the operation blocks because a restored Codex, Claude or Pi terminal disappeared, the person runs `ahub recovery reattach <operation-id> codex|claude|pi` to relaunch that peer with its recorded session (one relaunch per receipt), then `ahub recovery resume` to finish.
+
+From 0.12.30 or earlier, existing Jcode project MCP entries need one refresh before conductor or dashboard starts. Once per project, the person runs:
+
+```bash
+ahub jcode --mode headless
+ahub init
+```
+
+The first command starts Jcode and rewrites only the hub-owned `agent-hub-jcode` entry in `.jcode/mcp.json`, adding its delivery-only marker. Foreign or overriding entries refuse instead of being overwritten. `ahub init` keeps an untracked machine-path file out of git; review a tracked file deliberately. Daemon readiness checks never rewrite this entry. See [Jcode operations](operations.md#optional-jcode-peer).
+
+Task owners running as Pi or `local` need the isolated test capability for non-PII `implement`, `test` and `bulk_edit` work. A person sets `checks.runner` to `"container"` in untracked `.agenthub/config.local.json`; the Apple container service and pinned image must also be available. Issue-backed owners additionally need spec access. Manual messages remain available, and PII work retains its local-only routing. See [bounded check requirements](security.md#bounded-task-specs-and-isolated-checks-418) before enabling the runner.
+
 ## First session
 
 In your project directory, one terminal each:
@@ -68,6 +83,9 @@ or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local]
 | `ahub say [@peer] <text>` | talk; start with `[STATUS]` to let it batch, `[FYI]` for the record only |
 | `ahub task propose [--class <c>] <title>` | put work on the board; the hub picks an owner and a reviewer, and the class if you name none |
 | `ahub board` | who has what; `ahub task show <id>` for one task |
+| `ahub task cancel <id> --reason <text>` | close obsolete work without approving it or stopping a native turn |
+| `ahub settings set planner <peer>` | pin the planner; status reports whether it came from settings, roles or the automatic choice |
+| `ahub settings reload` | apply edited config files without a restart; guarded values wait for your `y` in this terminal, and restart-only keys stay pending |
 | `ahub status` | peers, queues, pauses; `ahub budget` for quota windows |
 | `ahub memory profile-check` | a person's read-only check of running memory bindings in the current registry |
 | `ahub ask <question>` | what the board, shared memory and the log say, with the ids the answer rests on |
@@ -78,9 +96,9 @@ More: `ahub help`. How it is built and why: [`docs/specs/2026-09-19-agent-hub-de
 
 ## Shared memory
 
-The hub exact-pins the first-party `@staix/agent-mem` 0.3.0 core. Existing shared-v1 memory remains the default; upgrading does not migrate it. Managed agents use screened `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools, or propose a correction with `hub_memory_correct`; only a person accepts candidates through the supported `amem review` path. Generation candidate acceptance is still refused.
+The hub exact-pins the first-party `@staix/agent-mem` 0.3.1 core. Existing shared-v1 memory remains the default; upgrading does not migrate it. Managed agents use screened `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools, or propose a correction with `hub_memory_correct`; only a person accepts candidates through the supported `amem review` path. Generation candidate acceptance is still refused.
 
-Before any real generation migration, upgrade every hub sharing that memory home to 0.12.30 and check its authenticated binding with `ahub memory profile-check` in each custom registry. Ready bindings prove compatibility, not an atomic live cutover: quiesce consumers and close their handles before migrating, then reopen through the supported session-preserving lifecycle. Invalid or changed profiles disable native memory without falling back to legacy writes; the bus and board continue. See [memory operations](operations.md#hub-memory) for the remaining rollout gates.
+Before any real generation migration, upgrade every hub sharing that memory home to 0.12.30 or later and check its authenticated binding with `ahub memory profile-check` in each custom registry. Ready bindings prove compatibility, not an atomic live cutover: quiesce consumers and close their handles before migrating, then reopen through the supported session-preserving lifecycle. Invalid or changed profiles disable native memory without falling back to legacy writes; the bus and board continue. See [memory operations](operations.md#hub-memory) for the remaining rollout gates.
 
 ## Browser dashboard
 
@@ -95,8 +113,9 @@ 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. The page also starts a peer in its start
 mode (a TUI opens in a terminal when the hub has a terminal provider) and shows
-the settings; raising one needs `ahub ui --settings` or `ahub settings` in a
-terminal. See the operations guide, "Settings from the dashboard and the
+the settings with a Reload configuration button; raising one needs `ahub ui --settings`
+or `ahub settings` in a terminal, and guarded values from an edited file need
+`ahub settings reload` there. See the operations guide, "Settings from the dashboard and the
 terminal" and "Start modes".
 
 `ahub ui --no-open` prints a one-time link instead of launching a browser. Open it