@staix/agent-hub 0.27.0 → 0.29.0

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.27.0 and control protocols 16 through 17. Live verification
+This guide describes ahub 0.29.0 and control protocols 16 through 17. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -355,6 +355,24 @@ 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.
 
+For an active session, `hub_delivery_resolve { delivery_id, revision, action, reason }`
+settles only its own `needs_review` row, including while busy (#1079). Get the
+observed revision from the bounded held-row metadata returned with `hub_inbox`.
+Use `completed` after handling the delivery, or `discard` when it should not be
+acted on, with a nonempty reason. The journal records the recipient actor and
+reason. Another peer's row, a stale revision, remote-room disposition, active
+`dispatching`/`accepted` rows, a paused or held peer, recovery, shutdown or storage
+holds, and a reason that is private or sensitive all refuse. A row that carries an
+invocation stays person-only (`ahub queue show <id>`, then `ahub queue resolve
+<id>`), because the invocation may still be running. This never retries a message, changes a task
+role or cancels the native turn; recipient retry keeps its existing one-use rules.
+
+An explicit `hub_inbox` read can return newly queued messages behind a held row
+and name the retained hold. It does not return the held originals, settle them
+or release automatic delivery. Recovery, pause, lifecycle and storage fences
+still apply. A delivery-only peer with no active turn still needs the person to
+resolve its hold.
+
 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.
 
@@ -384,11 +402,18 @@ behavior is unchanged. `ahub queue resolve ... [--revision N]` uses the supplied
 revision instead of a fresh show. A `queued` delivery was never handed to its peer, so it can be discarded while the peer is busy (a pull-only TUI is busy most of
 the time); `dispatching` and `accepted` deliveries stay refused, and `retry` keeps its rules. A refused resolution names its cause (`active delivery`, `peer busy`,
 `stale revision`, `unknown delivery`, `already resolved`, `queued delivery is already scheduled`, `recipient queue is full`, `delivery journal unavailable`), never one
-generic sentence (#713).
-
-`ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes] [--json]` clears one peer's backlog and is for the person or the configured conductor (any other agent identity is
-refused, and a remote `peer@label` queue is the person's only). Without `--yes` it only says how many deliveries it would discard; with `--yes` it discards each queued (default) or `needs_review` delivery of that peer through the
-same resolution as `queue resolve --action discard`, each recorded with the reason, and prints `discarded N of M` with the causes of any it could not discard. Only the
+generic sentence (#713). A failed row that a resolution already settled (for
+example the parent of a retry, whose redelivery is a separate row) is refused as
+`already resolved`, never `stale revision`. `ahub queue show` on a failed row says
+that nothing is left to do, or, if the row is unsettled, prints the `ahub queue
+resolve <id> --action discard|completed` command (#1098).
+
+`ahub queue discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes] [--json]` clears one peer's backlog and is for the person or the configured conductor (any other agent identity is
+refused, and a remote `peer@label` queue is the person's only). Without `--yes` it only says how many deliveries it would discard; with `--yes` it discards each delivery of that peer through the
+same resolution as `queue resolve --action discard`, each recorded with the reason, and prints `discarded N of M` with the causes of any it could not discard. With no `--state` it takes the peer's queued rows and its
+failed rows that no resolution has settled yet (#1096); `needs_review` rows need an explicit `--state needs_review`, and `--state` names exactly one kind. A failed row ran nothing, so it can be discarded while its peer is busy.
+The new request form needs the `queue_discard_states` hub feature: against an older hub the CLI sends nothing for `failed` or for the default and says to upgrade, because that hub would discard queued rows instead.
+`ahub queue list` hides rows a resolution already settled (for example the parent of a retry), prints how many on stderr, and `--all` shows them. Only the
 named peer's queue is read, so other peers are untouched; it is refused while recovery or shutdown holds queue mutations. In the console Queue panel, `D` on a row opens
 the same command for that row's peer, asks for a reason, then a `y` that names the count. No task is cancelled and no native turn is stopped.
 
@@ -973,7 +998,48 @@ ahub up
 ```
 
 `ahub init` writes the project configuration and managed instruction blocks.
-Run it after an upgrade when those blocks need refreshing. `ahub setup`
+Run it after an upgrade when those blocks need refreshing.
+
+Settings flags (#1100) set the main project settings without a file edit.
+`--agents <a,b,...|none>` (`start.agents`) and `--autonomy inherit|off` (whether a
+new project inherits the machine autonomy preset) go to the untracked
+`config.local.json`. `--sdlc off|advise|enforce` sets `mode` in `sdlc.toml` (`off`
+writes no file on a new project). `--coordination advisory|turn-free`,
+`--memory`/`--no-memory`, `--snapshots`/`--no-snapshots` and `--pi`/`--no-pi` set
+their keys in `config.json`. On an existing project only a flag you give changes
+anything: `--dry-run` shows each change as `old -> new` (`--dry-run --json` adds a
+`settings` array), and a value equal to the current one is a no-op. An invalid
+value, or a flag given twice with different values, is refused with the allowed
+values, and nothing is written. Executables, secrets, models, providers, instances
+and permissions have no flags; they stay file edits.
+
+A person at a terminal who runs `ahub init` on a new project with no flag that
+sets anything and no `--yes` is asked each setting in turn (#1065 T2): profile,
+the agents `ahub up` starts, design specs and their review mode, SDLC mode,
+coordination, shared memory, snapshots, the Pi peer, the machine autonomy
+preset, the release guard, and shadow history (asked in a folder with no Git
+work tree, and kept for an existing shadow repository, never in a Git
+repository). Each question is one line, the label, the choices and the default in
+brackets. Enter keeps the default and sets nothing; an answer is an explicit
+choice, exactly as the equivalent flag is, so the files written are the files
+the same flags write. A wrong answer asks again and is never guessed, and three
+wrong answers refuse the prompt. The plan follows, in the words `--dry-run`
+prints (including the machine autonomy preset a new project inherits, unless
+the answer was `off`), and `Write this? [y/N]` decides: N, an empty answer, Ctrl-C and Ctrl-D
+write nothing. Only the console role at a terminal (stdin and stdout) is asked:
+an agent identity is refused before `init` runs, a `--live-test` delegation, a
+pipe and `--dry-run` are never asked, and `--yes` takes the defaults. A flag of
+any kind (`--agents`, `--coordination`, `--profile`, `--shadow` and the rest)
+means the person has chosen, so nothing is asked and the flags apply alone. An
+existing project is never asked. The questions are built from the init settings
+table (`INIT_SETTINGS`), so a setting added there is asked without another
+change, and `test/init-prompt.test.ts` fails when the two disagree. The default
+in each bracket is read from where the writer gets it (`templates/config.json`,
+the loader's own defaults), and that test reads every one back through the
+loaders after a flagless `ahub init`, so a changed default cannot leave the
+prompt showing one value while Enter writes another. `--dry-run` and the
+prompt's plan take the machine-autonomy row from the same helper
+(`autonomyInheritanceChange`). `ahub setup`
 installs or updates the Claude plugin and a project-neutral PreToolUse hook in each
 Claude configuration home in use (see "Machine autonomy and Claude homes"), and
 registers the acon console plugin (see "acon console plugin"). Keep `ahub console` open when a local worker
@@ -1021,6 +1087,34 @@ the sandbox either. `git add`, `commit`, `stash` and `checkout` work, and
 signs with a key under `~/.ssh` or `~/.gnupg` fails, because the sandbox cannot
 read those directories. Run a refused command yourself, in a terminal.
 
+A task can declare what it needs (#1081): `hub_task_propose {needs_network: true}` or `{needs_worktree: true}`, and
+`ahub task propose --needs-network` or `--needs-worktree`. Only an explicit `true` sets either, and the hub never
+infers a need from the title. A declared need keeps the task away from a peer that cannot meet it: automatic
+routing, a reservation, `ahub task assign` and `hub_task_accept` all refuse it before any write, and
+`ahub route explain <id>` prints the cause for that peer. It is offered to a peer that can meet the need.
+
+- `needs_network` is for work that fetches from a package registry, runs `git fetch` or `git push`, or calls an API.
+  A hub-sandboxed peer (Pi, the local worker) has none while `local.bash_network` is off: `no network: local.bash_network
+  is off ...`.
+- `needs_worktree` is for work that must run in its own git worktree on a task branch (the repository rule). A
+  hub-sandboxed peer cannot run `git worktree add`, because it writes under the git common directory and runs outside
+  the sandbox by design (#270), so since #1115 the hub makes the worktree for it at `.worktrees/<peer>-<task>` on the
+  branch `task/<task>-<peer>`, before the accept write. The peer edits files there and does not run git; at
+  `hub_task_done` the hub stages, commits and pushes the branch. The capability is true only where the hub can make
+  the worktree. Otherwise it is false and the refusal says why and what to do: `no worktree: the hub cannot make a task
+  worktree for it: the project is not a git repository; run git init there, ...`. A refused accept creates nothing,
+  so no empty branch ref is left behind (the Pi accepts of #621 and #565 left two). Declining or cancelling removes
+  the worktree and its empty branch; one with uncommitted changes is kept and reported. The sandbox profile is not
+  changed (docs/security.md, "Hub-made task worktree").
+
+A peer whose capability the hub cannot tell is never refused on this ground. Work that declares no need is routed as
+before, with one exception (#1129): write-class work (`implement`, `bulk_edit`) is treated as needing a worktree
+whether or not it is flagged, because a hub-sandboxed owner cannot commit (#1123) and the hub commits in its worktree.
+Such work is never offered to a hub-sandboxed peer on a project where the hub cannot make a worktree, and
+`ahub route explain` says `no worktree` and the cause; `test`, `summarize`, `triage`, `review` and `plan` get none,
+and neither does a PII task. The other flags are a person's or a planner's statement about the work, so an unflagged
+task can still reach a peer that cannot meet them.
+
 Network is off unless `local.bash_network` says otherwise. With `true` it goes
 only through the hub's egress proxy on a loopback port (0.11): commands get
 `HTTPS_PROXY` and the other proxy variables, the proxy opens HTTPS (`CONNECT`,
@@ -1098,7 +1192,7 @@ assignment skips it until a delivery completes; inspect `ahub route explain` for
 reason. A task owned by a peer whose task delivery exhausts retries is escalated with
 that delivery's error, and the console is notified.
 
-A delivery in `needs_review` holds later deliveries to that peer. The console announces
+A delivery in `needs_review` holds automatic later deliveries to that peer; an explicit `hub_inbox` read may read new queued work behind it without releasing or replaying the hold (#1079). The console announces
 the hold once, and status, task assignment and route explanations name its delivery id.
 Inspect it with `ahub queue show <id>` and explicitly choose `completed`, `retry` or
 `discard` through `ahub queue resolve`. Reassignment or approval of its task never
@@ -1124,6 +1218,95 @@ Pi 0.86 assistant usage is forwarded at `message_end`, including tool-loop messa
 and recorded before settlement. If a model supplies no usable count, `ahub report`
 says `tokens not reported`; the hub does not estimate usage from text length.
 
+## Control write outcomes and safe retries (#1078)
+
+A daemon advertising `tool_write_idempotency` accepts a top-level control
+`requestId` for `hub_task_propose` and `hub_review`. This key is independent of
+transport `rid` and MCP JSON-RPC IDs. The proposal and review MCP tools expose optional `request_id`:
+omit it for a new call; after an unknown outcome, reuse the echoed key with the
+same arguments. The channel removes this transport argument before task
+validation. A new JSON-RPC ID does not change an explicitly supplied retry key. In-process tool calls (the local worker and Pi) refuse `request_id`: replay keys need the control-protocol transport.
+
+Read `hub_task_list` for an uncertain proposal, `hub_task_show` for an uncertain
+verdict, or `ahub queue show <delivery-id>` (person/conductor) for a delivery.
+Call again only if the task, verdict or completion is absent. For a proposal or
+review retry, copy the returned `request_id`; do not invent a fresh key. An
+in-flight retry joins the original execution. A retained result is the receipt
+of that call, rather than a fresh statement of the task's current state.
+
+`outcome: unknown` means a sent call may already have applied, including after a
+timeout, cancellation or lost connection. `outcome: refused` means this attempt
+did not run (for example an invalid key, insufficient authority or full actor
+window); it does not undo an earlier attempt. Known task permission/validation
+errors retain their specific error. Explicit retries are refused before sending
+to older daemons that do not advertise the feature.
+
+Each authenticated actor has its own 512-entry, 15-minute replay window across
+its operations and launch generations. One actor filling that window does not
+block another. Replies are capped at 64 KiB and cached overlap metadata checks
+up to 64 current task references. Expired/foreign-instance IDs refuse without
+applying again; restart recovery uses board reads. `delivery_complete` uses the
+existing journal idempotence keyed by delivery ID and the live socket/generation,
+so settlement consumes no replay-window capacity. `hub_delivery_done` takes only
+its delivery ID and generation; it has no request key argument.
+
+The latency receipt and its synthetic-only scope are in
+[control-write verification](verification/2026-11-02-control-write-outcomes.md).
+
+
+## Control write timing and loop delay (#1126)
+
+After upgrading to a release containing #1126 and restarting through the normal
+upgrade workflow, `ahub status --full` shows aggregate control-write timing
+counters. An older hub omits them. They are process-local diagnostics, reset at
+restart, not durable success receipts or a count of unique business effects.
+This feature does not change a request timeout or make a retry safe.
+
+A slow tracked operation (at least 1,000 ms on a monotonic clock) writes a
+`control_write_slow` JSON record to hub.log. The record contains a closed request
+kind, an optional public task number, elapsed time, outcome and phase durations.
+`returned`/`threw` describes the handler, not business success or whether a write applied.
+Client-side timing is opt-in with `AHUB_CONTROL_WRITE_TIMING=1` in the client or
+MCP server environment. Its slow records go to stderr, never stdout, and omit task
+numbers because the client has no authoritative privacy view. No request/rid,
+actor/session identifier, path, task text, argument, external output or error
+message enters a timing record. Host privacy is checked again before logging.
+An unresolved task identity (including a noncanonical string id) suppresses daemon
+diagnostics while the operation keeps its normal validation and behavior.
+
+The daemon samples its event loop every 100 ms. A missed tick delayed by at least
+250 ms can write `control_write_loop_delay`, including bounded observed spans.
+Recently completed synchronous intervals are retained so a span that blocked the
+loop can be identified after its callback has returned. An open asynchronous span
+is only a concurrent wait, not proof that it occupied the CPU; untracked occupancy
+is reported as unknown. Background snapshot, queue/status and memory boundaries
+use the fixed `background` kind rather than inventing a tool request.
+
+Per observer, retained work is capped at 128 operations, 256 active span registrations, 512
+recent intervals and 8 emitted phase/span items. Phase totals use only the closed
+phase set; a full active-registration map never discards a finished phase or recent
+synchronous interval. There is no per-request cutoff that can hide a late block.
+The slow and loop categories each allow at most one line per second, with a shared
+60-line/minute ceiling; each JSON record is at most 2,048 UTF-8 bytes. Dropped work
+and logs are counted. Normal ring rotation and settle-time cleanup are excluded
+from the full-status dropped total. A stopped probe cannot be started again. Nested durations are not additive. Status counters include
+background observations and do not identify a blocking cause on their own.
+
+Unanswered diagnostic requests expire after five monotonic minutes, reclaiming
+their operation and span slots without cancelling the underlying work or changing
+its eventual result. Full status lists `expired` separately from capacity/log drops
+and normal ring rotation. Argument screening starts only after socket admission;
+model-input diagnostic screens run once only when tracing can admit the observation.
+
+Board-write, queue/status, memory and external-call phases locate an observed
+boundary; they do not weaken its existing authority, privacy or execution gates.
+The probe is unref'd and stopped at daemon shutdown or failed startup. The
+[historical window correlation](verification/2026-11-03-control-write-stall-windows.md)
+separates one 60-second all-event gap from review waits with continuing periodic
+callbacks. The instrumentation is intended to diagnose the next naturally
+occurring stall; it has not been run against the live daemon by that task.
+
+
 ## A two-agent task and review
 
 Choose an owner explicitly, then inspect the reviewer selected by the project
@@ -1307,6 +1490,18 @@ take it.
 for. Dependencies are fixed when a task is proposed and can only name tasks that
 already exist, so they cannot form a cycle.
 
+`hub_task_list` pages (#1083), because a 628-task board was 2.4 MB and over every agent tool-output limit.
+An agent's reply is `{tasks, total, next?}`: newest updated first (ties by id, descending), at most `limit`
+rows (default 50, 1 to 200), each compact (`id`, `state`, `owner`, `reviewer`, `title`). Pass `next` back as
+`cursor` for the following page; the cursor is the last row's `updated.id`, so a task that changes between
+calls neither repeats nor skips an older row, and the last page has no `next`. `ids` (1 to 200 distinct task
+numbers) returns the full public row of exactly those tasks, in the order given, and cannot be combined with
+`limit` or `cursor`; `detail: true` returns full rows for a page. `state`, `ready` and `release` filter before
+paging. PII tasks stay `[pii]` stubs in every form. Every refusal names its cause and what to pass instead.
+The person's console keeps the full bare array unless it names `limit`, `cursor`, `ids` or `detail`, so
+`ahub board`, `ahub tasks` and their `--json` output are unchanged. A peer that read the whole board as a
+bare array (the benchmark runner did) reads `tasks` instead, or asks for its task by `ids`.
+
 An owner named for a task that waits (`owner` with `after`, `--owner` with
 `--after`) is its reserved owner: the task still waits, and when it is ready
 routing offers it to that peer first, not to the first idle peer of the class.
@@ -2062,6 +2257,16 @@ A newly initialized `ahub init` project inherits a trusted machine opt-in and sa
 
 `ahub setup` selects the explicit `CLAUDE_CONFIG_DIR`, otherwise an existing default Claude home (or the not-yet-created default when no other home is selected), plus distinct homes proven in use by live registered Claude launcher records. It does not scan arbitrary profile directories. Each native plugin command receives that home's environment. One confirmation covers plugin setup and a project-neutral PreToolUse hook while preserving unrelated hooks and statusLine settings. The profile fallback requires the inherited hub state and peer identity and does nothing for a managed launch that already has its session hook, preventing duplicate delivery. Installing a hook proves configuration, not live enforcement.
 
+Setup manages only the user-scope `agent-hub@agent-hub` plugin row (`claude
+plugin install|uninstall ... --scope user`). A project- or local-scope row of that
+plugin is kept and named in a notice (`... plugin row preserved ...; setup never
+removes non-user scopes`). While such a row exists, setup is blocked rather than
+removing an agent-hub marketplace that points at another source (#1073). The
+semver check on installed plugin versions applies only to agent-hub rows, so
+another plugin recorded with a git SHA no longer fails the inventory (#1074). When
+a Claude home step fails, setup still records the `start.agents` answer before it
+reports the failure.
+
 `ahub autonomy status [--json]` includes the machine default and each discovered Claude home's plugin/hook state. Missing, unsafe, stale, unavailable or incomplete evidence is explicit; a missing selected home is reported without starting a native inventory command that could create it. The native Orca zero-prompt receipt remains T4.
 
 
@@ -2489,6 +2694,100 @@ Rules:
 - Person only: an agent shell or a hub tool is refused (`ahub settings edit` is a console command in the identity gate, and the three control requests answer only the console role). Recovery or shutdown holds every edit.
 - The hub must run this release: an older hub answers `unknown message` and the command says to upgrade and restart it.
 
+## Design spec inspection
+
+`ahub specs list` discovers Markdown specs whose flat frontmatter names an `id`
+and `type`. `ahub specs covers <file...>` finds their path scopes.
+`ahub specs check` validates graph links, types and stamps without a daemon;
+it prints nothing and exits 0 when there are no specs or stamped documents.
+`--json` returns structured reports, and `--require-fresh` also fails on stale
+documents. `--base <ref>` reports changed paths whose covering spec stayed
+unchanged without making that report an error.
+
+The `specs` config block defaults to
+`{ "enabled": true, "review": "report", "roots": [], "stamps_file": "" }`.
+Roots are repository-relative directories; an empty list scans the repository.
+The optional stamps file uses the schema of `docs/verified.json` for other
+documents. A scan stops at 2,000 Markdown files and 8 KiB of frontmatter per
+file; a truncated report names `specs.roots` as the way to narrow the scan.
+Symlinked files are skipped. Freshness counts commits touching covered paths
+since the stamp and detects uncommitted changes without running Git filters
+or external diffs. These commands never refresh a stamp.
+
+The Switches settings `specs.enabled` and `specs.review` are machine-local
+settings, and the specs config fields are tier 2 structural settings. Setting
+`specs.enabled` to false suppresses this machine's notices and status summary,
+leaving the shared config unchanged. Explicit CLI and `hub_specs` inspection
+still work when notices are disabled.
+
+`ahub init --specs` (the default) and `--no-specs` set the shared key
+`specs.enabled` and add or remove the `AGENT_HUB_SPECS` instruction block in
+`AGENTS.md` (the text is `templates/specs.block.md`). `--spec-review
+off|report|require` sets `specs.review`. Both are rows of the init settings
+table: on an existing project an explicit flag shows as one old -> new row in
+`--dry-run`, a flag equal to the current value is a no-op, and a plain `ahub
+init` follows the project's `specs.enabled` (on unless the project set it to false):
+it adds or refreshes the block when specs are on and removes it when they are off. Text outside
+the markers is never touched. A block with only one of its two markers is
+refused, naming the cause, and nothing is written.
+
+`ahub specs stamp <id-or-document...> [--yes]` is a person's record that they
+reviewed a spec or a stamped document against HEAD. It is person only: an agent
+identity is refused before the command runs (it is a console command, and
+`--live-test` delegation refuses it too), and a run with no terminal is refused
+even with `--yes`. It shows `old -> new` per document, asks, and then changes
+only the spec's `verified-against` line (adding it before the closing `---` when
+absent) or the document's `verifiedAgainst` value in the stamps file, keeping
+every other byte, the line endings, a byte order mark and the file mode. The new
+stamp is the full HEAD SHA. It is refused, writing nothing for any target, while
+a document's covered paths have uncommitted changes, when the document has no
+paths, when a document's frontmatter cannot take a stamp, or when a name matches
+no or several documents; all refusals are listed together, and a document that
+cannot be stamped is refused before the question is asked. The answer may take
+minutes, so after it HEAD, each covered path's state and every target file's
+bytes are checked again, and any change refuses the whole run: what you approved
+is what is written. Removing the instruction block with `--no-specs` takes out
+only the block and one separating blank line, so the whitespace of the text
+around it is kept. Stamping changes a working-tree file: review the diff and commit it.
+Agents never edit `verified-against`. `docs/verified.json` is still restamped
+only in a release PR (AGENTS.md "Verified stamps").
+
+`scripts/check-docs.mjs` stays a self-contained Node script, because the release
+workflow runs it on Node without Bun or an install and `src/hub/specs.ts` is
+TypeScript that depends on repository packages. `test/check-docs-parity.test.ts`
+holds it to the same state, commit count and dirty flag as the shared engine on
+the same stamps.
+
+Task proposal and acceptance replies name the specs covering the task's refs
+paths. At completion the hub reads spec metadata from the submitted commit,
+compares the host-verified changed-file inventory with those scopes, and adds
+`spec not updated: <id>` and `spec errors: <n>` to the result and review brief.
+Dirty spec edits in another checkout do not satisfy this check. `report` records
+the report; `off` suppresses task notices. Under `require`, unchanged covering
+specs must be updated or named in `spec_ack`, for example
+`[{ "id": "bus", "reason": "Only an internal allocation changed; the contract is unchanged." }]`.
+Acknowledgements are screened, recorded at the exact head, and shown to the
+reviewer. A new head invalidates the old report. Unknown or truncated coverage
+cannot satisfy `require`; a refusal names the next step. A call accepts up to
+20 acknowledgements; larger changes can update the specs or split the task.
+Tasks without a submitted commit or with no changed files have no coverage
+obligation. Existing spec errors are reported on tasks touching covered paths
+or spec documents. A privacy change during a check suppresses its spec report
+without discarding the check result. If an applicable review policy changes
+to `require` while that check runs, the pass is retained and the owner is
+asked to refile completion under the current policy.
+
+`hub_specs` offers read-only `check` and `covers` actions with at most 20 report
+items. These explicit reads and status inspect the daemon checkout; task notices
+inspect the owner's execution root and completion reports inspect its submitted
+commit. Immutable Markdown blobs are read in bounded batches and parsed results
+are cached by object id across submitted heads. PII tasks and private turns do not publish spec paths through task
+notices. Completion snapshots skip Git symlinks and cap each committed spec
+body at 4 MiB; an incomplete read stays unknown. Status shows a specs count,
+error count and stale count only when specs or stamped documents exist, with
+one hint when the specs instruction block is missing. Empty projects stay
+silent.
+
 ## Start modes: TUI by default, headless as opt-in
 
 A peer that has a TUI the hub attaches to starts in it by default (issue #269).
@@ -2502,6 +2801,19 @@ A peer that has a TUI the hub attaches to starts in it by default (issue #269).
 | jcode (optional) | `tui` on the hub-owned ACP session (`ahub jcode`) | `ahub jcode --mode headless`, or `peers.jcode.start_mode: headless` |
 | local | headless (hub-native) | not applicable |
 
+Daemon-owned peer launches, native version-helper probes and process-table helpers drop
+every inherited `ORCA_*` variable. They pass `CLAUDE_CONFIG_DIR` and `CODEX_HOME` through
+unchanged; Claude uses the former and Codex the latter, while other peers ignore
+selectors they do not own. The hub does not choose a different account,
+synthesize a home, or copy native credentials. A person-started native process
+launched from `ahub claude`, `ahub codex`, `ahub kimi` or another native launcher
+keeps its pane's `ORCA_*` context while its own peer markers replace inherited
+agent identity. Manager and person console wrappers keep their existing
+environment, routing and recovery rules. Adapter-owned fresh homes take
+precedence; Pi's fixed environment carries `CODEX_HOME` but not
+`CLAUDE_CONFIG_DIR`, and the local worker's fixed shell environment carries
+neither.
+
 - **You type the command:** `ahub pi` opens Pi's TUI in that terminal.
   `--headless` and the start mode setting are the two ways to ask for the
   background peer. `ahub settings set peers.pi.start_mode headless` writes the
@@ -2520,7 +2832,14 @@ A peer that has a TUI the hub attaches to starts in it by default (issue #269).
      `{command}` is quoted for a POSIX shell; `{title}` and `{cwd}` are raw,
      so give each an argv element of its own.
   2. Orca, when the hub runs in an Orca worktree or an earlier `ahub <peer>`
-     launch of this project recorded one (the path recovery uses).
+     launch of this project recorded one (the path recovery uses). The terminal opens in the
+     Orca worktree whose root is exactly this project's root, found with `orca
+     worktree list` (#1105); it never uses the worktree of whichever terminal
+     started the hub, which is another project's after `ahub --project`, a
+     dashboard manager start or an upgrade. The start is refused, naming the cause
+     and `terminal.open` as the alternative, when Orca cannot list its worktrees,
+     has no worktree with this root, has more than one, or cut its list off at 500
+     rows first.
 - **No provider:** the start is refused with the command to run by hand. It is
   never downgraded to headless. `ahub settings` lists each start mode, and the
   dashboard's Start control says which mode a start will use and where its
@@ -2920,6 +3239,13 @@ the history entry reads `by: hub` with that planner and the reason
 is paused for recovery pulls nothing, also when the setting is turned off or recovery begins while a pull is already waiting on its screening: that pull writes nothing, and a recovery waits for pulls in flight. A committed `config.json` cannot turn it on: like
 the other machine-local policies it is ignored there with a log line.
 
+A backlog or unowned proposed card whose `plannedStart` is still in the future is
+not started automatically (#1092). Until that time the hub sends no
+`backlog_ready` line, makes no auto-pull, makes no ready-queue or queue-pressure
+owner offer, and the task sweep reports no stall. Planner grooming lists the card
+as `scheduled`. The card becomes eligible at the planned start itself. A planner's
+explicit pull or a person's assignment is unchanged.
+
 ## Resetting a project's hub
 
 `ahub reset` returns a project's hub to a clean state. Without `--yes` it is a
@@ -3126,7 +3452,7 @@ version is older than the selected running daemon; it installs nothing.
 | Runtime | Control protocol window | Legacy status field |
 | --- | --- | --- |
 | 0.12.20 through 0.25.0 | 16 only | `protocol: 16` |
-| 0.26.0 through 0.27.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
+| 0.26.0 through 0.29.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
 
 New clients choose the highest common protocol. The runtime supports N-1, so the
 published protocol-16 client and channel plugin remain usable; unrelated feature
@@ -3731,6 +4057,20 @@ crash of one is not reported this way.
 - Codex's app-server died with the hub; run `ahub codex` again. Claude Code's
   plugin reconnects by itself while that session is open.
 
+The report in `ahub status` shows only what still stands (#1082), worked out when
+status is asked and not frozen at startup. A line that asks something of a peer
+(`run ahub codex again`, `reconnects by itself`, a Pi that is still down) goes as
+soon as that peer is attached again, whoever attached it. The headline's count of
+deliveries still in `needs_review` counts only the ones this crash left, read
+live, so it equals what `ahub queue list` shows for them and falls as each is
+resolved. At zero the count and its pointer to the queue are gone and the headline
+(`the previous hub run stopped without shutting down`) stays as the record that a
+crash was found. Lines that say what recovery found or did (`kimi resumed`,
+`pi not resumed`, `pi.auto_start started a fresh session`) are history and stay for
+the run. The hub log keeps every line as it was written. A row that becomes
+`needs_review` later in the run is in `ahub queue list` and is not part of this
+count.
+
 ## Evidence and limits
 
 The 0.6.4 release has real measurements in [the smoke checklist](smoke.md):
@@ -4081,7 +4421,7 @@ has appeared for `AHUB_CHECK_QUIET_S` seconds (300 by default, set to 300 in CI)
 slow suite that is still passing tests is never cut. `scripts/progress-tee.sh` passes bun's
 output through unchanged and appends one byte to a progress file for each of those lines;
 the watchdog polls that file's size. On a stop it prints where the run is and the process
-table below it first. `AHUB_CHECK_HANG_S` (960 by default) is only the backstop for a run
+table below it first. `AHUB_CHECK_HANG_S` (2250 by default, sized in #1086 from two measured full runs on dgx02 of 1483 s and 1487 s of test time, 1.5 times the longer; it was 960) is only the backstop for a run
 that keeps printing results while hung; hosted CI sets 1500 on Linux inside a 35-minute
 job limit (#378, #593, #752, task 516). The macOS leg runs as four shards (#548): `AHUB_CHECK_SHARD=i/n`
 makes `scripts/check.sh` run slice `i` of the full suite through `bun test --shard=i/n --timings=scripts/test-timings.json`, which puts
@@ -4409,6 +4749,16 @@ Use `ahub roster add jcode`, then `ahub jcode [--model <alias>] [--provider-prof
 
 The native TUI opens only after Jcode has saved the selected session. On 0.98.1, `session/new` does not save it; the first real hub turn does. The launcher prints `jcode's TUI opens after its first hub turn; send it work, or Ctrl-C` once and waits for the same owned launch's saved session. Send Jcode work from the hub, or press Ctrl-C to end only the wait. No artificial prompt is sent. A console `peer_start` uses a terminal provider to run the same launcher, even while ACP is running; a conductor or dashboard start of an attached Jcode answers `already` and opens nothing (#559). Without a provider, run its displayed command in your own terminal. Options with no terminal need that manual path.
 
+A refused TUI launch names its cause and the next step (#1093): Jcode was
+restarted during the launch, its owned server is not running, its private socket
+was replaced, no session has been reported yet, the saved session failed the hub's
+safety check, the hub is busy stopping or recovering, Jcode is not running under
+this hub, or the project MCP entry is stale. The daemon logs only the cause code,
+never a path or id. After a crash or controlled recovery a Jcode whose start mode
+is `tui` runs headless. Until a TUI launch is served, `ahub status` and the
+launcher say `jcode is running headless after recovery; run ahub stop jcode, then
+ahub jcode to get its TUI back`.
+
 `ahub jcode --dry-run` stays pure and redacted. A person's `--print-command` can show the actual top-level native argv and closed native environment for an already-saved running session; it starts nothing, and like the launch it names a `--model`, `--provider-profile` or `--session-id` that differs from the running session (#574). The private socket/session tuple is not returned to hub tools or status. Native saved-session evidence is read-only and capped at 32 MiB; unsafe, mismatched or larger evidence refuses the TUI launch.
 
 A busy jcode takes an `important` message into its running turn (#572): the hub sends it as a soft interrupt through jcode's own private server socket, which jcode injects at its next tool boundary, so the message no longer waits for the turn to end. The hub never cancels a turn to deliver. Headless Kimi and Qwen have no such path: an `important` message waits, and `ahub status` and the console show `important messages waiting on a busy ACP peer for N min` once it has waited past `budget.stale_min`, so you can decide to stop the peer.
@@ -4690,6 +5040,14 @@ admission reads, and the split changes no admission decision. An older hub shows
 acceptance and self-claim in every lifecycle mode, so 0 refuses new acceptances; a
 current owner's redo of sent-back work keeps its slot (#481 S9).
 
+A refusal at the limit separates what the owner carries from what it was only offered (#1080):
+`planner WIP capacity for codex: limit 2; open tasks #621, #624 (accepted #621; offered, not yet accepted #624); <next step>`.
+An `urgent` task (priority 0, or the `urgent` signal) that is the owner's own offer may take back the
+newest offers the owner has not accepted, only as many as it needs, when that is all that keeps it at the
+limit. The hub returns each one ownerless to To Do (history `unassigned`, by the hub, naming the urgent
+task; a planner-pulled offer also loses the reservation that counted toward the owner's WIP), withdraws its offer, and tells the planners and the console. After the displacement the hub checks that the owner is under its limit and refuses the accept with the cause and a next step if not. It never takes back accepted work,
+another urgent offer, a person-pinned offer or an offer with work evidence, and a refusal changes nothing.
+
 Pending unowned, unstarted pull can be undone at its latest owned revision via
 `hub_backlog_undo` or the existing planning undo control, restoring its earlier
 reservation. An ordinary return to Backlog also restores the pre-pull reservation unless a later explicit reservation edit superseded it. Normal release routing offers work only while that reserved peer
@@ -5073,7 +5431,7 @@ A reviewer has a review scope (#852): `full` (reads the code, runs the affected
 
 Start them with `ahub claude --as claude-review`, `ahub codex --as codex-review` and `ahub kimi --as kimi-review`; stop with `ahub stop <id>`. For the Claude and Codex reviewers the command asks the running hub to start the reviewer and returns: nothing runs in that terminal, it takes no launch arguments, and `--print-command` or `--dry-run` prints a hub-start note instead of a launch (#720). Fresh Claude and Codex variants share the project checkout; the Kimi variant runs in a clean temporary working directory and reviews only the screened brief and host facts. All fresh variants refuse a custom worktree or permission mode. Codex and Kimi require `review_mode: "fresh"`; without it, an existing headless instance with the reviewer role keeps its native app-server/ACP behavior, worktree and permission options and does not join this pool. Claude retains its task 223 automatic headless-reviewer declaration. The agy reviewer slot remains automatically unavailable (`agy is an implementer peer (#485)`). A failed or unsupported fresh start never downgrades to a native continuing session. Ordinary implementer instances retain their own adapters. The default logical pool order is Claude, Codex, Kimi. Only configured kinds with at least one declared reviewer count as slots, including declared ones that are offline, paused, quota-limited or failing, so availability never renumbers them; configured kinds with no declaration are listed after the walk as `no declared reviewer`. `review.rerotate` defaults to false. Pool selection starts at PR number modulo the number of declared kind slots, or task id when there is no PR, then skips the implementer's family and unavailable candidates. Delta review prefers the preceding eligible independent family in a fresh child. A preceding same-family fallback does not outrank a newly available independent family. `ahub route explain` shows the same pure walk.
 
-Codex requires a verified `codex-cli` (0.146.0, 0.163.0 or 0.164.0) or one the person trusts on this machine, and a passing bounded runtime receipt before its model child starts. 0.146.0 and 0.163.0 passed the [2026-10-22 model-free production admission](verification/2026-10-22-codex-reviewer-isolation.md) and 0.164.0 the [2026-10-24 one](verification/2026-10-24-codex-0164-reviewer-isolation.md); 0.166.0 passed the [2026-10-31 model-free procedure](verification/2026-10-31-codex-0166-reviewer-isolation.md), but its [one authorized model review](verification/2026-10-31-codex-0166-reviewer-tool-call.md) missed the required synthetic marker in the persisted verdict, so the version remains unverified and its proposed verified bump was reverted. A refusal names the installed and verified versions. Either set `codex_bin` to a verified executable, or run `ahub agents trust codex-review <version>`: trust lifts only the version pin, and every proof below still runs before each child (#691). Each launch approves exactly `hub_review` and `hub_task_show` per tool (`approval_mode = "approve"`), never through a server-wide default: without it Codex 0.164.0 listed the tools but refused the call, so reviews ended with no verdict (#783). A model-free receipt proves the inventory, not that a verdict reaches the hub; a [model-backed 0.164.0 run](verification/2026-10-25-codex-0164-reviewer-tool-call.md) recorded one verdict through that path. The producer checks native binary/config stability, configured MCP inventory with only the two hub tools, effective Apps/plugins/hooks disablement, an explicit empty legacy `notify` command and a named filesystem profile. Apps needs separate feature readback because configured inventory omits runtime connectors. Web search is requested disabled; its effective turn mode is not read back and managed requirements can select Cached (see the verification ceiling). Each launch proves public-read, exact/glob/symlink private-denial, standard host credential denial and write-denial in temporary fixtures. Standard credential and configured tool-home/XDG subtrees are denied independently of project `local.deny`. Its sandboxed shell is filesystem read-only with private paths denied and network configured disabled; it is not Claude's Read/Grep/Glob-only tool whitelist. No credential home is copied.
+Codex requires a verified `codex-cli` (0.146.0, 0.163.0, 0.164.0 or 0.166.0) or one the person trusts on this machine, and a passing bounded runtime receipt before its model child starts. 0.146.0 and 0.163.0 passed the [2026-10-22 model-free production admission](verification/2026-10-22-codex-reviewer-isolation.md) and 0.164.0 the [2026-10-24 one](verification/2026-10-24-codex-0164-reviewer-isolation.md); 0.166.0 passed the [2026-10-31 model-free procedure](verification/2026-10-31-codex-0166-reviewer-isolation.md). Its [first authorized model review](verification/2026-10-31-codex-0166-reviewer-tool-call.md) missed a marker hidden by the fixture's accepted plan, so that admission was reverted. After a committed model-free envelope regression and a fixture correction, the separately authorized [2026-11-02 single model review](verification/2026-11-02-codex-0166-reviewer-tool-call.md) persisted one approved verdict with the required marker and exact head; 0.166.0 is now verified. A refusal names the installed and verified versions. Either set `codex_bin` to a verified executable, or run `ahub agents trust codex-review <version>`: trust lifts only the version pin, and every proof below still runs before each child (#691). Each launch approves exactly `hub_review` and `hub_task_show` per tool (`approval_mode = "approve"`), never through a server-wide default: without it Codex 0.164.0 listed the tools but refused the call, so reviews ended with no verdict (#783). A model-free receipt proves the inventory, not that a verdict reaches the hub; a [model-backed 0.164.0 run](verification/2026-10-25-codex-0164-reviewer-tool-call.md) recorded one verdict through that path. The producer checks native binary/config stability, configured MCP inventory with only the two hub tools, effective Apps/plugins/hooks disablement, an explicit empty legacy `notify` command and a named filesystem profile. Apps needs separate feature readback because configured inventory omits runtime connectors. Web search is requested disabled; its effective turn mode is not read back and managed requirements can select Cached (see the verification ceiling). Each launch proves public-read, exact/glob/symlink private-denial, standard host credential denial and write-denial in temporary fixtures. Standard credential and configured tool-home/XDG subtrees are denied independently of project `local.deny`. Its sandboxed shell is filesystem read-only with private paths denied and network configured disabled; it is not Claude's Read/Grep/Glob-only tool whitelist. No credential home is copied.
 
 Kimi requires a compat-admitted Kimi Code on the hub's PATH (receipt-verified 2.2.0, 2.3.0, 2.3.1, 2.3.2 and 2.4.1), signed in through its managed OAuth provider, and a passing runtime preparation before each child; an unverified/untrusted version or a failed preparation is unavailable with its reason. The [2.3.0](verification/2026-10-22-kimi-qwen-compat.md), [2.3.1](verification/2026-10-25-kimi-231-reviewer-compat.md), [2.3.2](verification/2026-10-26-kimi-232-reviewer-compat.md) and [2.4.1](verification/2026-10-31-kimi-241-reviewer-compat.md) receipts are model-free and do not verify real login/provider readiness. Each review runs a new `kimi -p` child without Seatbelt, in a private `KIMI_CODE_HOME` with managed-provider-only config, a clean temporary working directory and an empty skills directory. Its agent may call only `hub_review` and `hub_task_show`, through a task-bound loopback MCP session that never carries the hub's control token, and has no native read, file or shell tool: it reviews the screened brief and host facts only. Its `credentials/`, `oauth/` and `device_id` link to the person's native Kimi files, so it shares the native login, refresh lock and the Kimi account's budget; no token is copied. A stop revokes its verdict authority first, then waits briefly while an OAuth refresh holds the lock; a forced stop mid-refresh may require a native re-login. The Kimi backend records no measured token counts here, so its usage stays unknown; the 2.3.0 receipt makes no usage claim. This is a native tool-authority boundary, not filesystem or network isolation.
 

package/docs/profiles.md

@@ -54,6 +54,7 @@
 # Project profile overrides
 
 - Acceptance criteria are profile-independent (#507b): a task's recorded criteria checklist (docs/sdlc.md, Acceptance-criteria checklist) is listed in every profile's review request, ahead of the profile's `review_checklist` lines, and an unmet item that starts with a criterion id names it; a profile only changes the wording of its checklist, never the criteria or their ids.
+- Every shipped profile's `review_checklist` carries one error-message item (#1095): the reviewer names each new or changed error, refusal or failure message that lacks its cause or its next step. Because `review_checklist` replaces as a unit, a project that sets its own `profile_overrides.review_checklist`, and a pack (whose rubric lines become that override), does not get the item unless it adds one. The shipped lists are what a project without an override sees.
 - Recurring unmet criteria become a candidate, never a change (#514a): when reviews name the same criterion id unmet on at least 3 tasks of one profile and class within 30 days, and those tasks make up at least 2 separate pieces of work (tasks sharing a PR or a branch count once), the hub files one backlog card with the `profile_overrides.review_checklist` line to consider. The line is text, and nothing applies it on its own. By hand: `profile_overrides` is not machine-local, so you choose the shared `.agenthub/config.json` (every checkout) or `config.local.json` (this machine), and add the line to your current checklist because `review_checklist` replaces as a unit. With the command (#514b): `ahub learn list` shows the open cards, `ahub learn accept <id>` adds that one line to your current checklist in `.agenthub/config.local.json` (this machine only, never the shared or any tracked file) through the settings writer, closes the card, and says it applies after a restart; `ahub settings undo` puts the previous file back; `ahub learn reject <id>` only closes the card. The line is rebuilt from the key line of the card and the board's own evidence, never parsed from the card text. Person only: an agent shell and the configured conductor are refused. PII tasks and evidence-only verdicts never count.
 - `profile_overrides` in shared/local config selects project data over the chosen shipped profile. `classes`, `role_text` and `catalog_roles` maps merge by key across layers; `plan_keys`, `agents`, `example_checks` and `review_checklist` replace as units. A local `profile` selects the active base for both init and native contracts.
 - Classes may add or remap profile aliases to existing base classes. Existing base names keep their meanings; class maps are bounded to 32 override entries. Task storage and route explanations preserve the alias, including a dev custom alias, while routing/budgets/checks use its base. Other tasks under custom dev data retain the selected profile semantics too, so document sections do not become whole-path overlaps. Unmodified dev rows retain their old shape.

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the channel plugin and a pr
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.27.0
+bun add -g github:STAIxBWLB/agent-hub#v0.29.0
 ahub setup
 ```
 
@@ -31,6 +31,20 @@ move a running project to a newer release later, run `ahub upgrade` in a
 terminal in that project: it reviews the plan with you, applies it and follows
 it; other projects keep their version.
 
+## Upgrading to 0.29.0
+
+Upgrade every `amem` that shares your memory home together with the hub: the hub now exact-pins `@staix/agent-mem` 0.20.0, and an `amem` 0.19.0 hook or CLI cannot drain 0.20.0's new hook spool records and can retire them after seven days (#1131). Formats, shards, candidates and indexes are unchanged.
+
+A hub-sandboxed peer (Pi, the local worker) can no longer commit, branch, tag, stash, switch, merge, rebase or reset, nor `git add` in a linked worktree: the sandbox refuses writes to refs, HEAD, packed-refs and worktree admin files (#1123). Instead the hub makes a task worktree for its write work (`implement`, `bulk_edit`) at accept and commits and pushes it at `hub_task_done` (#1115, #1129). Where the hub cannot make one (no git repository, no first commit, or a repository config that names a helper, filter or include), that work is not offered to Pi or the local worker, and an assignment to them is refused with the cause; run `git init` and make a first commit, or give the work to Claude, Codex or Kimi.
+
+`ahub status --full` shows control-write timing counters, and a slow control write or a blocked event loop leaves a metadata-only record in `hub.log` (#1126). Set `AHUB_CONTROL_WRITE_TIMING=1` for client-side timing on stderr.
+
+## Upgrading to 0.28.0
+
+`ahub init` now takes flags for the main project settings (#1100, #1107): `--agents <a,b,...|none>`, `--sdlc off|advise|enforce`, `--coordination advisory|turn-free`, `--memory`/`--no-memory`, `--snapshots`/`--no-snapshots`, `--pi`/`--no-pi`, `--specs`/`--no-specs`, `--spec-review off|report|require` and, for a new project only, `--autonomy inherit|off`. On an existing project only a flag you give changes anything, `--dry-run` shows each change as old -> new, and an invalid value is refused with the allowed values. Run at a terminal on a new project with none of these flags and no `--yes`, `ahub init` asks each setting with its default in brackets and shows the plan before it writes anything; `--yes` takes the defaults, and a pipe, a peer or `--dry-run` is never asked (#1110). Design specs are new and on by default (#1097, #1102, #1107). A design spec is a Markdown file with `id` and `type` frontmatter. `ahub specs list|check|covers` reads the specs and checks their links and freshness without a daemon, agents get the read-only `hub_specs`, and `ahub status` adds a specs line when the project has specs. `ahub specs stamp` is your own record, made at a terminal, that you reviewed a spec against HEAD (see [design spec inspection](operations.md#design-spec-inspection)). The next `ahub init` in an existing project adds an `AGENT_HUB_SPECS` block to `AGENTS.md` unless the project set `specs.enabled` to false; `ahub init --no-specs` turns specs off and removes the block.
+
+Agents now read the task board in pages: `hub_task_list` returns 50 compact rows by default with a `next` cursor, and `ids` or `detail: true` give full rows (#1083); `ahub board` from your terminal is unchanged. A task can declare `needs_network` or `needs_worktree` (`ahub task propose --needs-network|--needs-worktree`), and such work is no longer offered to a peer that cannot meet the need, such as a sandboxed Pi or local worker (#1081). An urgent task can take back offers its owner never accepted when they are all that fill its WIP limit (#1080). When the reply to a `hub_task_propose` or `hub_review` is lost, the call reports `outcome: unknown` with a `request_id` to reuse, so a retry does not file a duplicate (#1078). A busy agent can settle its own `needs_review` delivery with `hub_delivery_resolve`, and `hub_inbox` reads new messages queued behind a held one (#1079). `ahub queue discard --peer <id>` without `--state` now also clears the peer's unsettled failed deliveries, `--state failed` names failed deliveries alone, and `ahub queue list` hides rows a resolution already settled unless `--all` (#1103). Crash-recovery notices in `ahub status` clear once their condition is gone (#1082), and a start refused during a recovery hold says why and what to run (#1104). A backlog card with a planned start is not offered before that date (#1092). Agents the hub starts no longer inherit the Orca pane's routing (#1094), and their Orca terminals open in the project root's worktree (#1105). A Jcode session that recovery restarted headless gets its TUI back with `ahub stop jcode`, then `ahub jcode` (#1093). `ahub setup` keeps plugin rows it did not install (#1073, #1074). The reviewer checklist in the shipped profiles now asks that error messages state the cause and the next step; a profile override or a pack replaces that checklist and does not get the new item (#1109). Codex 0.166.0 is now a verified reviewer version (#1071), and the hub exact-pins `@staix/agent-mem` 0.19.0, which shares its index and hook records with 0.18.0 (#1072). As for 0.27.0, update the global CLI and the plugin yourself afterwards with `bun add -g @staix/agent-hub@0.28.0`, then `ahub setup`, and restart Claude sessions so they load the 0.28.0 plugin, which adds `hub_specs` and `hub_delivery_resolve`.
+
 ## Upgrading to 0.27.0
 
 Nothing changes until you use something new. Release consent can now come from your explicit instruction to the conductor: say in its own session which release to ship (for example "release 0.27.0"), and the configured conductor runs `ahub sdlc authorize-release <version>` for you, under the same admission as `sdlc merge`; you can still run it yourself. The approval keeps every binding it had (exact commit, version, origin and fresh docs; a restart revokes it), its record names who ran it, and a hub message, task text, review note, file or another peer's relay never counts as the instruction (#1063, #1066). Research experiments gain a read and a write: `ahub study experiments` and `hub_experiment_show` read a campaign's attempts, one attempt or one comparison (#602), and an owner records protocols, plans, attempts, events and receipts with `hub_experiment_record`, refused during a private turn (#615). Concurrent starts of one project no longer fail on a `runtime.json` replaced while it was being read (#616). As for 0.26.0, update the global CLI and the plugin yourself afterwards: `bun add -g @staix/agent-hub@0.27.0`, then `ahub setup`.
@@ -157,7 +171,7 @@ The restarted Claude planner gets the release-train tools (`hub_release_new`, `h
 
 Jcode must be 0.98.0 or later, below 1.0.0; 0.94.0 is no longer accepted, so `ahub doctor` fails its Jcode row for an older install and the peer does not start (#529). Every owned jcode process runs with `JCODE_NO_TELEMETRY=1`.
 
-Since 0.12.37 the hub opens a split memory home through its shards (#534); the current exact `@staix/agent-mem` pin is 0.18.0. Before anyone runs `amem migrate --shards` on a memory home, every hub using that home must run 0.12.37 or later: an older hub does not see the split and keeps writing the old layout. `ahub memory profile-check` is split-aware and compares each hub with its own project's shard (#536). See [memory profiles and rollout](memory.md#selected-memory-profile).
+Since 0.12.37 the hub opens a split memory home through its shards (#534); the current exact `@staix/agent-mem` pin is 0.20.0. Before anyone runs `amem migrate --shards` on a memory home, every hub using that home must run 0.12.37 or later: an older hub does not see the split and keeps writing the old layout. `ahub memory profile-check` is split-aware and compares each hub with its own project's shard (#536). See [memory profiles and rollout](memory.md#selected-memory-profile).
 
 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:
 
@@ -181,6 +195,8 @@ ahub console       # use in another terminal if up used --no-console; Tab opens
 ahub kimi          # Kimi in its own pull-only TUI; --mode headless for the hub-driven peer
 ```
 
+On a new project at a terminal, `ahub init` first asks each main setting (profile, agents, specs, SDLC mode, coordination, memory, snapshots and the rest) with its default in brackets. Enter keeps a default, and nothing is written until you answer y to the plan. `ahub init --yes` takes every default without asking.
+
 `ahub up` also starts a default set of agents, `claude` and `codex` unless you choose others, each in a terminal the hub opens (`terminal.open`, or Orca). It prints one line per agent, and an agent it cannot open is named with the command to run yourself (`ahub claude`, `ahub codex`). Choose the set once with `ahub setup --agents kimi,codex` (or answer the question in `ahub setup`), change one project with `ahub settings set start.agents <a,b>`, and skip it for a run with `ahub up --no-agents`. Without a terminal provider nothing is opened and the hub keeps running; start them by hand:
 
 ```bash
@@ -230,7 +246,7 @@ 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.18.0 core, including deterministic capture; no claude-mem worker is needed. 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. Since agent-mem 0.7.0, `amem review` also accepts candidates on a selected generation.
+The hub exact-pins the first-party `@staix/agent-mem` 0.20.0 core, including deterministic capture; no claude-mem worker is needed. 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. Since agent-mem 0.7.0, `amem review` also accepts candidates on a selected generation.
 
 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.