@staix/agent-hub 0.12.29 → 0.12.31

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.29 and control protocol 16. Live verification
+This guide describes ahub 0.12.31 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -123,8 +123,13 @@ 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
 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
@@ -176,6 +181,68 @@ decisions and a never-ask permission mode require confirmation; delivery resolut
 status state counts and never fetches the board. Leaving restores
 the terminal and returning from panels replays the bounded stream buffer.
 
+Tasks and Queue selections follow the selected id across refreshes. If that row
+disappears, no replacement row inherits the action. Task actions also bind the
+row's `flowRevision` (its history length); queue actions bind the delivery
+revision. The id and revision in a row-started command cannot be edited. Peer,
+reason and the final role/action remain editable, and the confirmation names the
+validated result. An older hub without `flowRevision` refuses revision-bound task
+row actions instead of silently running them unchecked.
+
+In Tasks, `a` assigns the owner in ordinary open states and the reviewer in
+`in_review`; a waiting task says when assignment is a reservation. `u` unassigns
+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.
+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
+equivalent. Owner removal is allowed in `proposed`, `in_progress` and
+`changes_requested`, returns active work to `proposed`, and clears any owner
+reservation. It is refused in `in_review`, `approved` and `backlog`. Reviewer
+removal retains the state, including `in_review`, and refuses to remove the human
+reviewer of PII work. No replacement is routed and no native process or external
+effect is rolled back. A person-unassigned task stays out of automatic owner
+offers across dependency release, planner-pull processing, release timers and
+restarts until an explicit assignment or reservation. The later unassign also
+fences planner undo, so undo and re-pull cannot restore the removed reservation.
+Former queued assignment or review requests are withdrawn without resolving
+uncertain deliveries, and the former agent loses current authority. A withdrawal
+notice uses delivery evidence or that peer's own accept/self-claim after the
+latest assignment; another owner's in-progress state or an earlier acceptance
+does not count. Withdrawing an unread queue alone sends none. If a later person
+assignment supersedes an escalation or offline relay, the stale success result
+and decision note are suppressed, but the former owner is still told the current
+owner and to stop working.
+
+`ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]` uses a
+checked console operation when a revision is present. Without it, existing CLI
+behavior is unchanged. `ahub queue resolve ... [--revision N]` uses the supplied
+revision instead of a fresh show. Revision mismatches and superseded post-await
+publications fail without a board or delivery side effect; a reviewer-only change
+keeps a valid owner assignment but refreshes its reviewer content.
+
 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
@@ -388,9 +455,157 @@ The Stop hook acknowledgement is not a counted completion. The daemon checks the
 native transcript after the hook can return; missing or changed-session evidence
 stays unknown.
 
+## Pi with DGX and MLX
+
+Pi is optional. Install Pi separately and set `pi.enabled` to `true` in
+`.agenthub/config.json`. Set `pi.auto_start` to `true` to start it with the hub.
+Pi starts in its TUI by default; `ahub pi --headless`, or the start mode
+setting (`ahub settings set peers.pi.start_mode headless`), asks for the
+background peer instead. The project uses its existing OmniRoute connection for DGX;
+`pi.dgx_coding` and `pi.dgx_fast` select the gateway's configured model IDs.
+
+```bash
+ahub models setup       # prepare bounded Qwen3.5 4B MLX in an existing Ollama service
+ahub models start       # verify loopback Ollama/model readiness (no daemon spawn)
+ahub models status
+ahub pi --headless --backend auto
+ahub say @pi "Read the project and summarize the next small implementation task"
+ahub pi                # its TUI in this terminal; an idle headless session moves into it
+```
+
+The default routing template assigns implementation, bulk edits and tests to
+DGX, and summaries/triage to MLX. Pi and the existing local worker take priority
+before cloud peers; planning and final review stay with Claude/Codex. Existing
+projects keep their routing file, so add `pi` to the relevant `peers` lists and
+set `pi_backend = "dgx"` or `"mlx"` for each class. PII tasks remain local-worker
+only. `--backend dgx` or `--backend mlx` explicitly pins a Pi session's backend.
+
+Pi connects to an authenticated relay with model aliases `dgx/coding`,
+`dgx/fast`, and `mlx/fast`; upstream gateway credentials stay in the hub.
+Its managed tools use the existing path guards, shell sandbox and terminal
+approval flow. Keep `ahub console` open to approve write/edit/shell operations:
+a request nobody answers expires, and two in a row end Pi's turn.
+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
+`OLLAMA_KEEP_ALIVE` (five minutes is the tested setting). `models setup`
+prepares `agenthub-fast-mlx:4b-8k` from `qwen3.5:4b-mlx`, with an 8K total
+context and a 2K output cap. The relay budgets input separately at 6,000
+estimated tokens and serializes local requests across project hubs.
+
+`models status` distinguishes model availability from memory residency.
+`models stop` refuses to unload an externally managed Ollama model: other
+clients may be using it. Ollama owns idle eviction; stopping a hub never
+kills Ollama. The OpenAI compatibility endpoint does not enforce a request
+`keep_alive` field, so configure the server and verify its expiry readback.
+The relay can fall back to DGX before streaming starts as before. See the
+[Ollama migration procedure](#ollama-mlx-migration-issue-51)
+for existing Python runtime/configuration cleanup and rollback.
+
+A project has one managed Pi session owner. Mode changes require the agent to
+settle and preserve the session file. Before the first generation, a live source
+verified to be empty can instead retain its exact session ID without a file.
+Missing history from a nonempty session blocks handover. Protocol 9 adds Pi
+recovery metadata. Protocol 10, released in 0.7.0, adds durable delivery
+receipts and conservative queue recovery; it is verified live (see the
+[smoke checklist](smoke.md)).
+Older protocol hubs still require their matching CLI and an attended bootstrap.
+
+## Local dashboard
+
+With a running daemon, `ahub ui` opens a local dashboard for messages, peer states
+and queues, the task board, budget windows, pending approvals and this machine's
+benchmark runs. Use `ahub ui --no-open` to print a single-use link when the
+browser cannot be opened.
+Open the link within 60 seconds; the browser session lasts one hour.
+
+The dashboard can send console messages, propose and assign tasks, pause or resume
+peers, answer approvals, start a peer in its start mode and show the settings.
+An ordinary session changes the safe switches and lowers a mode to `ask`; the
+rest needs `ahub ui --settings` or `ahub settings` in a terminal. See
+[Settings](#settings-from-the-dashboard-and-the-terminal) and
+[Start modes](#start-modes-tui-by-default-headless-as-opt-in).
+Budget pauses still require the terminal override.
+Private envelopes and PII tasks stay redacted. Local-worker and Pi tool details and
+allow decisions stay in `ahub tail` / `ahub permit`; the page can deny them.
+No dashboard port is opened until requested. See [the session security model](security.md#local-dashboard-sessions-issue-6).
+
+## Multiple projects and worktrees
+
+Version 0.4.0 adds one independent hub per repository or Git worktree.
+Subdirectory commands resolve to that project; symlink aliases resolve to the same
+hub. Explicit selection works from any directory:
+
+```bash
+ahub --project /path/to/project-a init
+ahub --project /path/to/project-b init
+ahub --project /path/to/project-a up
+ahub --project /path/to/project-b up
+ahub projects
+ahub status --all
+ahub --project /path/to/project-a codex
+ahub ui --all
+```
+
+The unified dashboard lists registered roots and opens their boards, streams,
+messages, approvals and budgets. It can start hubs and stop a selected hub after
+confirmation. Its Start control opens a peer's TUI only through a terminal provider
+(`terminal.open` or Orca); without one, launch Claude/Codex TUIs from a terminal. The manager stays available
+when a project stops; `ahub ui --all --stop` stops only the manager. Existing
+`ahub ui` still opens the current project's dashboard.
+
+`ahub projects --json` returns machine-readable live status. Use a listed ID or a
+path with `--project`; the selector must precede the command. `ahub projects remove
+<id>` forgets a stopped registration without deleting project data. A moved root
+gets a new registration. Missing roots remain visible until removed.
+
+Runtime state stays in each project's `.agenthub/state/`. The machine registry is
+`~/.agenthub/registry.db`; existing `ports.json` allocations are imported once.
+`AGENTHUB_HOME` selects an isolated machine registry (also used by tests). An
+inherited state directory from a different project cannot redirect a new CLI
+invocation. Explicit custom state requires a matching project marker or the
+initialization pair `AGENTHUB_PROJECT_DIR` / `AGENTHUB_STATE_DIR`.
+
+Manager-started hubs use attended mode and project configuration, including
+credential-file references. They do not inherit the launching project's gateway
+URL/key overrides. Native memory remains shared according to claude-mem aliases;
+worktrees recall their parent and composite identity. A shared-alias notice does
+not mean that task boards or agent sessions are shared. Provider quota readings
+may describe the same account and should not be added across projects.
+
+Before upgrading an older hub, inspect the plan with the matching CLI.
+Incompatible or unverified processes are shown explicitly and are never killed by
+PID-name matching. See the operations guide and the
+[multi-project specification](specs/2026-09-19-multi-project-design.md).
+
 ## Install and start
 
-Use Bun 1.3 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
@@ -472,8 +687,9 @@ does not list), needs its directory in `local.read_allow`, for example
 hub's tools: list a peer and it keeps only the capabilities named, from
 `propose` (`hub_task_propose`), `assign` (proposing with another peer as owner),
 `remember` (the `hub_remember` tool; the notes the hub itself keeps of done
-summaries and review verdicts are not gated) and `important` (`[IMPORTANT]`
-messages). For example `"capabilities": { "local": ["propose", "remember"] }`.
+summaries and review verdicts are not gated), `memory_correct` (propose a local correction candidate for person review), `memory_read`
+(`hub_memory_search`, `hub_memory_show`, `hub_memory_graph`) and `important`
+(`[IMPORTANT]` messages). For example `"capabilities": { "local": ["propose", "remember"] }`.
 A peer that is not listed keeps all of them, a listed peer whose value is not a
 list gets none, and an unknown capability name grants nothing; `hub.log` says
 so for each, and logs every refusal (`capabilities:`). A refused tool call says
@@ -523,8 +739,7 @@ resolves an uncertain delivery automatically. The same rule holds on every path
 assigns a task (#297): once the move is saved on the board, a failed delivery prints
 exactly one console notice ("the move is saved... delivery is not confirmed"), printed
 where the error is thrown, and the caller (a peer in its turn, or the CLI) still gets
-its error. Two exceptions, by construction: a move superseded while the assignment was being prepared, meaning a later history entry that moves or settles the task (another assignment, an unassign, the owner's accept, done, approval, close; the hub's quiet bookkeeping such as a late check result or a reviewer change does not supersede), is
-the caller's error as before, with no notice naming either owner; and a claim is its own hand-over, so its
+its error. Two exceptions, by construction: a move superseded while the assignment was being prepared, meaning a later history entry that moves or settles the task (another assignment, an unassign, the owner's accept, done, approval, close; the hub's quiet bookkeeping such as a late check result or a reviewer change does not supersede), returns the current task without a failed tool call and with no notice naming either owner; and a claim is its own hand-over, so its
 accepted write and line stay outside the delivery rule (its overlap and routing announcements to earlier
 owners are deliveries and share it). The repair is always
 to look for a queued or needs_review delivery with
@@ -735,7 +950,7 @@ ahub task label 12 reverted        # a later verdict (ok, regressed, reverted, i
 
 ## Hub memory
 
-The hub keeps its own memory in `~/.agenthub/memory/` beside claude-mem ([how it works](memory.md)): notes saved
+The hub opens the selected memory profile under `memoryHome()` (default `~/.agenthub/memory/`) beside claude-mem ([how it works](memory.md)): notes saved
 against an open task are short-term; when the task is approved its decisions, contracts and fails become long-term.
 Task briefs, session-start recall and `ahub ask` read it first, and the dashboard has a Memory section.
 
@@ -748,6 +963,20 @@ ahub memory forget 1a2b3c4d              # a person's; also promote, demote, sup
 
 `"memory": { "native": false }` in `.agenthub/config.json` turns it off for a project.
 
+The exact-pinned `@staix/agent-mem` 0.3.0 resolves `AMEM_HOME`, then `$AGENTHUB_HOME/memory`, then `~/.agenthub/memory`. An absent `M/profile.json` selects shared v1; an explicit generation selects `M/generations/G` with the package's readonly legacy bridge. All daemon memory consumers and the hub memory/goal CLI use that selected profile. Invalid metadata or a missing selected generation makes native memory unavailable while the bus and board continue; there is no fallback to legacy writes. Inspect the daemon's memory binding/availability before interpreting missing memory as an empty store.
+
+The daemon checks its selector at hub operation entry and before candidate/counter writes. It does not hot-switch handles or provide an atomic fence against selection changes during an in-flight core call. Quiesce consumers and close their handles before migration or selection changes; reopen through the supported session-preserving lifecycle afterward. Candidate/counter storage remains `M/candidates.db`, independent of `G`; `amem review` on a generation is still refused. Every running hub using this home needs an authenticated receipt: a matching ready binding, or a generation-capable unbound receipt (`disabled` when native memory is off, `unavailable` when opening failed) proving it holds no memory handle. An unbound daemon and zero running hubs are quiesced for memory; a stale bound handle, unreadable registry or unknown runtime is not ready. Existing JSON memory/goal results remain unchanged; the additive binding receipt belongs to daemon status, profile-check and the decay object. This source integration does not authorize installing a new runtime, migrating real memory, restarting sessions or claiming real-machine sync/capture receipts. Migration/deactivation and their limits belong to [agent-mem](https://github.com/STAIxBWLB/agent-mem); see [the hub profile contract](memory.md#selected-memory-profile).
+
+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 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.
+
+Review candidates and rendered/delivered/cited counters stay in machine-local `M/candidates.db`, outside sync, import, recall, briefs, ask and graph evidence. Public changes-requested reviews with unmet items may propose a fail candidate; missing cause/retry details stay unknown. Shared-v1 acceptance is a person's `amem review` action with its TTY/policy checks; selected generations still refuse that command. Read-time `(stale?)` hints and plan-fail advice never change stored rows or task authority. Structured fail notes are validated against 4000 UTF-8 bytes before screening or writes, with no silent truncation.
+
+Recall presentation omits generated task-approval outcome notes and shows only nonempty reasons from generated changes-requested notes; an ordinary decision that merely resembles a header stays visible. Contracts and fails remain eligible. Capped recall lines preserve memory headers and end at word boundaries, and one delivery deduplicates ids across restored/current prefaces and shared note lines. Stored notes and brief evidence are unchanged; platform recall retains its budget split.
+
 Between your machines, through a private git remote, with long-term tasks that span them:
 
 ```bash
@@ -1229,6 +1458,7 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
 | Start | `pi.auto_start` | `config.local.json` | next hub start |
 | 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 |
+| 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
@@ -1322,8 +1552,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
@@ -1527,6 +1759,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
@@ -1659,21 +1913,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.29), 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.31), 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.29 ahub upgrade --to 0.12.29 --dry-run
-bunx --package @staix/agent-hub@0.12.29 ahub upgrade --to 0.12.29 --yes
+bunx --package @staix/agent-hub@0.12.31 ahub upgrade --to 0.12.31 --dry-run
+bunx --package @staix/agent-hub@0.12.31 ahub upgrade --to 0.12.31 --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.29 (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.31 (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 |
 
@@ -1705,14 +1959,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.29 --dry-run
+ahub upgrade --to 0.12.31 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.29 --yes
+ahub upgrade --to 0.12.31 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -1777,7 +2031,11 @@ release. The global CLI is promoted last.
 
 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. If Claude shows its development-channel confirmation screen, confirm it in
+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 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:
@@ -1897,7 +2155,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
@@ -1907,7 +2166,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
@@ -1945,6 +2208,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.
@@ -2274,6 +2542,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
@@ -2287,6 +2571,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
   }
@@ -2298,6 +2583,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
@@ -2379,13 +2666,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;
@@ -2662,6 +2951,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)
@@ -2790,7 +3082,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.