@staix/agent-hub 0.26.0 → 0.28.0

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.26.0 and control protocols 16 through 17. Live verification
+This guide describes ahub 0.28.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,26 @@ 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 create one, because `git worktree add` writes under the git common directory and runs
+  outside the sandbox by design (#270): `no worktree: git worktree add runs outside the sandbox; ...`. A refused
+  accept creates nothing, so no empty branch ref is left behind (the Pi accepts of #621 and #565 left two). Having
+  the hub create the worktree and add it to a sandboxed peer's writable roots would move the sandbox write
+  boundary (a commit writes under `.git/worktrees` and `.git/objects`), so it is the separate spec issue #1115.
+
+A peer whose capability the hub cannot tell is never refused on this ground, and work that declares no need is
+routed as before. The flags are a person's or a planner's statement about the work, so an unflagged task can still
+reach a peer that cannot do it.
+
 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 +1184,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 +1210,41 @@ 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).
+
 ## A two-agent task and review
 
 Choose an owner explicitly, then inspect the reviewer selected by the project
@@ -1307,6 +1428,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.
@@ -1488,6 +1621,7 @@ ahub study approve rc-0123456789ab 2         # person only: create the unit task
 ahub study show [rc-0123456789ab]            # list campaigns (50 per page, --after continues) or one projection
 ahub study close rc-0123456789ab 2 --reason "answered"
 ahub study approve-protocol <64-hex hash>    # person only: approve one exact experiment protocol
+ahub study experiments --campaign rc-0123456789ab [--after 50]   # read the recorded attempts (also --attempt ra-... or --plan <hash> --baseline ra-... --variant ra-...)
 ```
 
 - **Contract.** The JSON names the question, scope, exclusions, registered source ids, 1 to 32 units
@@ -1518,8 +1652,33 @@ ahub study approve-protocol <64-hex hash>    # person only: approve one exact ex
 - **Experiments.** Protocols, comparison plans and attempts are stored with their provenance (`declared`,
   `host-observed` from a check receipt or a hub-hashed deliverable), and `ahub study approve-protocol` binds an
   approval to one exact protocol hash and its evaluator; a changed protocol needs its own approval. The hub
-  never ranks results. This release has no hub tool or CLI that records experiments; they are host storage
-  for the slices that follow.
+  never ranks results. The current in-progress owner of a bound unit task records inert data through
+  `hub_experiment_record`: `kind` is `protocol`, `plan`, `attempt`, `event` or `receipt`, using the existing
+  protocol/attempt/event/plan envelope or `{ kind: "receipt", receipt, signature }` for a signed runner receipt.
+  The person may relay a signed receipt through the authenticated console connection; this does not grant
+  agents person authority or allow a person to bypass the current task/source/campaign checks. Every PII turn
+  refuses the tool. It returns only record metadata (kind, ids/hashes, sequence and receipt id as applicable),
+  and neither starts an experiment nor signs or verifies a receipt in the relay. Existing host evidence and
+  signature verification remain inside `Tasks`. Read records with `ahub study experiments` or
+  `hub_experiment_show` (see Experiment readback below).
+- **Experiment readback (#602, #932 T3).** `ahub study experiments --campaign <id>` lists a campaign's attempts
+  (50 rows a page, `--after <cursor>` continues), `--attempt <ra-id>` shows one, and `--plan <hash> --baseline
+  <ra-id> --variant <ra-id>` shows one comparison under a recorded plan. `hub_experiment_show` takes the same three
+  forms and is a read for every local peer. It runs no command and reads no file; it renders what
+  `Tasks.experimentShow` already returns. Every value says where it came from: `declared` (the agent's own word),
+  `host-observed` (a check receipt or a hub-hashed deliverable), `runner-attested` (a signature-verified runner
+  receipt) or `person-attested`. A declared value is never shown as observed, a metric or output the hub could not
+  read is `unknown`, sealing is `declared` and `isolation unverified` unless a runner receipt supplies the
+  evidence, and failed, cancelled and unknown attempts stay in the counts at the top. A repeat is never an
+  independent reproduction, and a comparison whose fixed inputs, evaluator, split or metric units differ, or that
+  changes an undeclared factor, reads `no: <field> differs` and is shown, never ranked. A private campaign, task or
+  source shows ids, counts and states only. **Optional rerun checklist** (written for a person, never run by the
+  hub): a person who wants stronger evidence reruns the protocol themselves, then attaches it through the existing
+  paths and no new one: a check on the task (`hub_check_start`, #513 and the remote runner #793) makes the end
+  event's exit status `host-observed`; an output file named in an `output` event is hashed by the hub (#509) and
+  stays `unknown` when it is missing or denied; a registered runner's signed receipt (#1050) is the only source of
+  `runner-attested` sealing and isolation. Without one of these the experiment is reported as declared and
+  unverified, which is not the same as wrong.
 - **Privacy.** A campaign whose parent task is PII, or that names a private source, is private: every view keeps
   ids, counts, states and provenance and stubs its text as `[pii]`. Study tool arguments and results are kept out
   of hub-managed memory capture.
@@ -2036,6 +2195,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.
 
 
@@ -2463,6 +2632,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).
@@ -2476,6 +2739,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
@@ -2494,7 +2770,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
@@ -2894,6 +3177,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
@@ -3100,7 +3390,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 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
+| 0.26.0 through 0.28.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
@@ -3705,6 +3995,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):
@@ -4055,7 +4359,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
@@ -4383,6 +4687,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.
@@ -4664,6 +4978,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
@@ -5047,7 +5369,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.
 
@@ -5092,7 +5414,7 @@ blocks that undo until the identity and workspace can be reviewed.
 
 ## Release approval and optional tag guard
 
-Run `ahub sdlc authorize-release <version>` from the running daemon's release-candidate checkout in a person's terminal after committed documentation is fresh. The receipt binds commit, package version, remote identity and the docs verdict. Agents and delegated live-test calls cannot authorize. The daemon keeps approval only in memory and logs metadata for audit; restart requires a new approval. The read-only `ahub sdlc release <owner/repo>` report shows its receipt, retaining native-verification blockers.
+Run `ahub sdlc authorize-release <version>` from the running daemon's release-candidate checkout after committed documentation is fresh. The person may run it directly; the unique configured conductor may run it only on the person's explicit instruction in its own session naming the release. A hub message, task text, review note, file or peer relay never qualifies. Other peers, child `toolsOwner` sessions, private or PII turns, and delegated `--live-test` calls cannot authorize. The receipt binds commit, package version, remote identity and the docs verdict; its `by` and the audit name the actual asker. The daemon keeps approval only in memory; restart requires a new approval. The read-only `ahub sdlc release <owner/repo>` report shows its receipt, retaining native-verification blockers.
 
 `ahub init --release-guard` installs a managed Git pre-push guard and release instructions (`--dry-run --json` previews them). It preserves an existing default hook as `pre-push.agent-hub-original` and passes original argv/stdin to it only after approval matches. Unknown or mismatched `v*` tag pushes fail closed, including when the daemon is down. Non-version branch pushes remain independent of the daemon. Custom `core.hooksPath` and linked/hardlinked hook files require manual integration. Re-run init after changing the Bun/package location. The person's `git push --no-verify` remains an explicit bypass; agents are instructed never to use it.
 

package/docs/profiles.md

@@ -22,6 +22,7 @@
 - Example deterministic check: `bun /path/to/agent-hub/scripts/check-citations.ts report.md references.bib`. It checks bracketed Markdown `[@key; @other]` keys against BibTeX entry keys, with 256 KiB/4 MiB input caps. It performs no fetch, validates no source quality and is not a full Markdown/BibTeX parser. A missing key exits 1. A resolved bibliography is one check, not proof that claims are supported.
 - Keep a person's sign-off as the final review. The live three-source/two-agent example remains unverified and was not run during solo implementation.
 - A multi-unit study (#930, #601) goes through `ahub study`: the person (or a configured planner with `hub_study_draft` / `hub_study_revise`) stores a contract as a draft, only the person approves it with `ahub study approve <id> <revision>`, which creates one task per unit, and anyone reads coverage with `ahub study show [<id>]` or `hub_study_show`. A unit owner records `hub_study_handoff` with evidence for every source the unit names, or `insufficientEvidence`; a done task is not a handoff, and an incomplete handoff does not close a discovery round. A private campaign, task or source shows ids, counts and states only.
+- Experiment attempts recorded on a study unit are read with `ahub study experiments --campaign <id>` (or `--attempt`, or `--plan` with `--baseline` and `--variant`) and `hub_experiment_show`. Each value shows its source: `declared` is the agent's own word, and only `host-observed`, `runner-attested` or `person-attested` rows are evidence, none of which proves the science. A rerun by a person attaches through an existing check, a hashed output file or a registered runner's signed receipt, as the checklist in `docs/operations.md` ("Experiment readback") says; without one the experiment stays declared and its sealing unverified. The synthetic CPU-only fixture is `test/research-experiments-fixture.test.ts`; no account, GPU or native model has run an experiment here.
 - The deterministic three-source, two-peer example (`test/study-daemon.test.ts`, "three-source, two-peer example"): one contract names sources S0, S1 and S2 and two discovery units, `alpha` (S0 and S1, owned by codex) and `beta` (S2, an independent check, owned by kimi). After `ahub study approve` both units read `none` and `0/2 covered`, `0/1 covered`. A handoff for S0 only moves `alpha` to `incomplete` with `1/2 covered`. A handoff for both S0 and S1, and one for S2, make both `complete` and the discovery round complete. Another peer's handoff for `alpha` is refused. This runs with fake peers: it shows the hub's rules, not that a native model follows the guidance.
 
 # General project example
@@ -53,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.26.0
+bun add -g github:STAIxBWLB/agent-hub#v0.28.0
 ahub setup
 ```
 
@@ -31,6 +31,16 @@ 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.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`.
+
 ## Upgrading to 0.26.0
 
 `ahub upgrade` now upgrades one project: the one in the current directory, or the one `--project <path|id>` names; other projects keep their running version (#1039, #1045). From a 0.25.0 CLI, run it in the project directory, since 0.25.0 refuses `--project` for upgrade; it hands over to the 0.26.0 coordinator as before. It no longer updates the global CLI or the shared Claude plugin: run `bun add -g @staix/agent-hub@0.26.0` and then `ahub setup` yourself, and `ahub doctor` warns while either is older than a running daemon. The daemon speaks control protocol 17 and still accepts 16, so a 0.25.0 plugin keeps connecting. Each project keeps its verified runtime across stop and start; start it with a 0.26.0 or later CLI, because an older CLI ignores that record (#1052). A daemon refuses a `hub.db` in a newer format and names the version it needs. `ahub up` now also starts `claude` and `codex` (see [First session](#first-session)): `ahub setup` asks once which agents (`--agents <a,b>`, `none` for no agent), `ahub settings set start.agents <a,b>` changes one project, and `ahub up --no-agents` skips them for one run; a restart, recovery or upgrade relaunch starts none (#1046). An owner can re-file `hub_task_done` on an approved, unmerged task with a new head, which sends it back to review, and a reviewer can withdraw an approval with `changes_requested` (#1049). Signed external runner receipts for research attempts are opt-in: the person registers a runner under `research.runners` in untracked `.agenthub/config.local.json` (#1050). Restart Claude sessions so they load the 0.26.0 plugin.
@@ -153,7 +163,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.19.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:
 
@@ -177,6 +187,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
@@ -226,7 +238,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.19.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.