@staix/agent-hub 0.12.44 → 0.13.0

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.43 and control protocol 16. Live verification
+This guide describes ahub 0.13.0 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -61,7 +61,7 @@ smoke ledger; the presence of this option proves no outstanding #273 live leg.
 
 ## Command output
 
-`ahub status`, `board`, `budget`, `doctor`, `projects`, `queue list`, `turns` and `report` print shared console tables and labelled details.
+`ahub status`, `board`, `budget`, `doctor`, `projects`, `queue list`, `turns`, `report` and `usage` print shared console tables and labelled details.
 `status --all` uses the projects table. `queue show`, `models status` and `budget execution status` show labelled fields; add `--json` for the raw fetched document.
 `report --by task` keeps the attribution and coverage sentences with section headings and aligned counters.
 Use `--json` for scripts; it returns the fetched data without color, and `status --json` keeps its existing document.
@@ -141,6 +141,30 @@ its footer. The active tab is bracketed, as in `[2 Approvals]`, so it reads
 without color. The Approvals tab counts pending requests and the Queue tab
 counts `needs_review` deliveries, in the attention and failure tones.
 
+Tab `7 Usage` (#683 U3, key `7`; Left and Right wrap as Settings does, so the `1`..`5` cycle is unchanged) lists each peer with the tokens of today (the UTC day),
+the last seven UTC days and its lifetime, the current budget pause, its quota windows with their reset time, and its last reset. Every number names its
+source (`native`: the provider's own total, `hub`: what the hub counted for a peer that reports none, `at least`: a partial sum); a counter nobody reported
+is `unknown` and a period with no records is `no records`, never 0. Enter opens a peer: today, 7 days and lifetime with input, output, cache read, cache
+write and the hub count each on its own, and the last three resets. The task selected in Tasks when you press `7` is shown below the table with its tokens
+per peer (`#id [pii]` for a private task, never a title). The panel asks the hub's `usage` op only while it is open, and a refusal shows as
+`usage unavailable`. The numbers come from the roll-up of `ahub usage`, so the console and the CLI agree. A request folds the event log first, within 250 ms;
+when a very large log is not folded yet the answer carries `behind: true`, the panel says `still catching up` and `ahub usage` prints a warning on stderr, so a partial number is never shown as the whole.
+
+Reviewing from the console (#711): on a task in review in Tasks (a selected row, or the open task detail), `r` asks which verdict first on the prompt line,
+`review #372 "<title>": a approve  c request changes  Esc cancel` (the title is quoted and cut, a private task shows `[pii]`). `a` puts `review 372 approved ` on
+the input line with a guide line above it (`Enter approves #372. You can type a note first. Esc cancels.`); `c` puts `review 372 changes_requested ` there and
+asks for what to fix (`Say what to fix, then Enter. Esc cancels.`): Enter with no note is refused in the console with `say what to fix before requesting
+changes`, and nothing reaches the hub. The footer says `r approve or request changes`, and `your review: r approve or request changes` when the reviewer is
+`user`, also while the task detail is open. When the command finishes the console shows `#372 approved` or `#372 changes requested`, or the CLI's refusal verbatim
+as a failure notice, in panels mode too. A task that left review while the choice was open says `#372 is no longer in review (<state>)` and nothing is
+prefilled. The console runs `ahub review` as the person; the hub still decides who may review, and nothing about authority changed.
+
+An agent shell (a `!` command inside a Claude or Codex session, or any shell with `AGENTHUB_PEER_ID`, `CLAUDECODE` or `CODEX_THREAD_ID` set) runs as that agent, not as
+you. When the hub refuses it something only the person or the task's own reviewer may do, stderr adds one line: `This shell runs as agent "claude" (AGENTHUB_PEER_ID
+and CLAUDECODE are set), not as you. Run the command in your own terminal, or use the ahub console: Tasks, select #372, r.` The refusal and the authority are the
+same as before, and the console identity never gets the line. The hub's notice that a task waits for your review now names the console path as well as
+`ahub review N approved|changes_requested [note]`.
+
 The console attention companion (#280) shows waiting, blocked, review, working,
 idle or asleep with separate action/watch counts. Outside the Tasks table, `n` selects the exact approval,
 held queue or review row, or prints applicable guidance; it never answers a
@@ -175,10 +199,10 @@ the stream; only the header is tab-flattened before tokenizing. Body lines retai
 the previous rendering and stay plain, as does command output; colour never changes
 what the panel's text says.
 
-Peers, Approvals, Tasks, Queue and Settings are tables with a header row. A column is as
+Peers, Approvals, Tasks, Queue, Settings and Usage are tables with a header row. A column is as
 wide as its widest cell, up to a third of the terminal; the last column takes
 the rest and is cut with `...`. In Tasks, TITLE takes the rest and the STAGE
-meter keeps a fixed column at the right edge.
+meter keeps a fixed column at the right edge. In Usage, LAST RESET is the column that gives way on a narrow terminal.
 
 | Panel | Columns |
 |---|---|
@@ -188,6 +212,7 @@ meter keeps a fixed column at the right edge.
 | Tasks, backlog view (`b`) | ID PRI RESERVED DEPS CLASS AGE TITLE |
 | Queue | ID PEER STATE REV AGE |
 | Settings | GROUP KEY VALUE SOURCE APPLIES |
+| Usage | PEER TODAY 7D LIFETIME PAUSE QUOTA LAST RESET |
 
 In Tasks, `b` toggles open work and backlog. The backlog heading counts its rows;
 rows sort by rank, then id. PRI shows priority/rank, RESERVED the reserved peer,
@@ -320,7 +345,21 @@ owner and to stop working.
 `ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]` uses a
 checked console operation when a revision is present. Without it, existing CLI
 behavior is unchanged. `ahub queue resolve ... [--revision N]` uses the supplied
-revision instead of a fresh show. Revision mismatches and superseded post-await
+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 only (an agent identity is
+refused). 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
+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.
+
+Completed-change notices (`Task #N (owner X) is done and touches your open ...`, #713) go one per recipient per done, naming all of that recipient's overlapping tasks, and
+only for tasks the recipient has accepted (in progress, in review or changes requested): an offered or proposed task gets none, since its offer or its accept already shows the
+current board. A newer notice for the same done task replaces the queued, undelivered one for that recipient (a `superseded completed-change notice` discard in the journal), so
+a task that is sent back and done again three times leaves one queued notice, the newest. Revision mismatches and superseded post-await
 publications fail without a board or delivery side effect; a reviewer-only change
 keeps a valid owner assignment but refreshes its reviewer content.
 
@@ -635,6 +674,79 @@ Private envelopes and PII tasks stay redacted. Local-worker and Pi tool details
 allow decisions stay in `ahub tail` / `ahub permit`; the page can deny them.
 No dashboard port is opened until requested. See [the session security model](security.md#local-dashboard-sessions-issue-6).
 
+### Dashboard design tokens (#469 R1)
+
+The page's style block starts with one token block that owns every colour, the 4px spacing scale (4, 8, 12, 16, 24, 32), the
+type scale (12, 13, 14, 16, 20) and the radius rule: 6px for controls, 10px for surfaces (panels, cards, the dialog), full
+radius for chips and avatars. Neutrals are one cool family with three surface levels (page, panel, raised) and one accent for
+primary actions, focus and selection; the state colours keep their meaning. The dark values are written twice, once for
+`data-theme="dark"` and once for the system preference, and a test keeps the two identical. Two shadows exist for raised
+elements only (`--shadow-2` is the dialog's; `--shadow-1` waits for the board cards in R3). Each peer colour has a light and a
+dark variant of one hue, generated from the registry's colour by `peerPaletteThemeCss` (`src/ui/peer-palette.ts`) so it clears
+3:1 on every surface. System fonts only. The layout, the views, the keys and the behaviour are unchanged by R1; the contrast
+test (`test/office-view.test.ts`) covers the text pairs, the accent, the dots, disabled controls and every peer colour in both
+themes. The Office scene keeps its own rules until R5.
+
+### Dashboard app shell and keys (#469 R2)
+
+From 1024px up, a sticky top bar holds the project context, the connection status (a coloured dot and its text, green when live
+and red when disconnected or closed), the attention badge, the theme switch and a shortcuts button; the seven views sit in a
+left sidebar with an icon and a label, and the approval count still rides on Agents. Below 1024px the same nav is one row of
+tabs that scrolls sideways inside itself, so the page never scrolls sideways. The view names, their order, the
+`agent-hub-view` cookie and every id are unchanged.
+
+Keys: `1` to `7` switch to Board, Office, Stream, Agents, Message, Memory and Settings, `?` opens the key list, and `Esc` closes
+the key list or the task detail (both are native dialogs). View keys are ignored while you type in an input, a textarea or a
+select, with Ctrl, Alt or Cmd held, and while a dialog is open. Icons come from one inline SVG sprite of nine Tabler icons;
+the MIT notice is in `THIRD_PARTY_NOTICES.md`. Nothing is fetched and no package is added.
+
+### Dashboard board, side sheets and the Plan sheet (#469 R3)
+
+A board card shows the title (two lines at most), the owner as a round avatar in the peer colour with its initial, one badge that
+holds the state and the priority ("in review P1") and the release when there is one. Everything else moved to the task detail,
+which keeps the same dialog and opens as a sheet pinned to the right edge (full screen below 600px). The detail groups its
+lines into Status, People, Dates and Links, and leaves out a group with nothing in it. Pull, Assign, the Ready and Waiting
+subheads, "Show N older" and drag and drop are unchanged.
+
+The five board forms (plan a task, split a backlog task, releases, delivery evidence, propose a task) are in a Plan sheet, opened by
+the Plan button in the board toolbar. It is a native dialog, so `Esc` closes it, and view keys do nothing while it is open. The
+fields, ids and actions are the ones the forms had. The sheets slide in on `transform` and `opacity` and not at all when the
+system asks for reduced motion.
+
+### Dashboard Agents, Stream, Memory, Settings, Message and the Office colours (#469 R4, R5)
+
+Agents: a peer is one row with its name and state, a summary line (queued messages and "Working on #n" or "No active task") and a
+single "Details" fold that holds the diagnostic lines it used to list. A status notice stays visible outside the fold. Approvals
+stay first. Stream: one aligned row per event (time, kind, sender, body in monospace); the filter chips and Follow latest sit in
+the section head, above the scrolling list. Memory: result rows show title, kind and age, the selected row is marked with an accent
+edge, and the graph and the detail pane use the colour tokens. Settings: each group is a section with a short header, a key that waits
+for a restart carries a "restart pending" badge, and "Pending restart" shows a count; the text lines, Preview, Save and Undo are as
+they were. Message uses the shared form styles.
+
+Icons replace the symbol glyphs: the star mark, the stream arrow and the Office "checking" mark are sprite icons (twelve Tabler icons
+in all), and the Office draws each condition (idle, busy, offline, paused, waiting on approval) as a shape (ring, disc, cross, bars, raised hand)
+next to its words. Condition names are unchanged. The Office scene names its colours only through the same tokens as the rest of the page, and the
+contrast test checks every token an Office rule uses, in both themes.
+
+### Dashboard keyed rendering, motion and states (#469 R6)
+
+The page still polls `/snapshot` once a second and still skips a redraw when a container's JSON did not change. What changed is how
+a changed container is redrawn: task cards, peer rows and memory rows are kept per id. A card, row or memory entry whose own data
+did not change keeps its DOM node, so hover, an open "Details" fold and a focused card survive a poll that changed something
+else. One that changed is replaced by a fresh node, and if it held focus the focus moves to the replacement. A card that moves to
+another column fades in; one that disappears is simply removed.
+
+Motion moves `transform` and `opacity` only, 120 to 200 ms, ease-out: button press, a short fade when you switch views, a card
+arriving in a column, the toast, and the side sheets. The Office keeps its own motion. Nothing new loops. With the system setting
+"reduce motion" every transition and animation in the page is off.
+
+States: until the first snapshot arrives, after a project switch too, the board and the peer list show grey blocks shaped like them. Each empty view says what
+fills it and the command that does it (`ahub task propose`, `ahub claude` or `ahub codex`, `ahub say`, `ahub permit`, `ahub
+remember`, `ahub goal new`). When a poll fails the connection status turns red, the content dims to 60 percent but stays readable,
+and a line at the top gives the time of the last snapshot and says polling continues. Notices are a stack of up to four toasts in
+the bottom corner (`aria-live="polite"`): a success fades after 4 seconds (and stays under reduce motion), an error stays until
+you press Dismiss.
+
 ## Multiple projects and worktrees
 
 Version 0.4.0 adds one independent hub per repository or Git worktree.
@@ -894,6 +1006,57 @@ conductor sees it, and only a stub for a PII task. Other peers are refused. Each
 request also carries the hub's review brief for the task's commit: reviewable and
 excluded files with reasons, the `REVIEW.md` and `ahub-review-rules` rules read at
 the merge base, and a cross-check list; `ahub review brief <id>` prints it.
+Optional code facts (#682) add per-file observed symbol names, kinds and spans,
+plus changed/planned, changed/not-planned and planned/not-seen lists. Install
+ripwire 0.6.7 on the daemon's host PATH to enable them; missing, unsupported,
+failed, busy or timed-out reads show `unknown` and never stop the review request.
+Each native call is capped at 5 s, output is capped, and successful values are
+cached by repo, commit and query. PII tasks never query it; displayed names use
+the hub's public metadata screen. It always analyzes a disposable raw-blob
+snapshot, never main or a dirty/untracked owner tree, and removes that worktree
+after the owned process stops. No heavy slot is acquired. Trees beyond the
+regular-file/4096-file/32-MiB bounds remain unknown.
+
+Ripwire 0.6.7 omits deleted definitions and does not classify change kinds, so
+all symbol rows say `change: unknown`; planned/not-seen is not proof of no
+change. Graph name-only matches are hidden as ambiguous, and graph count floors
+remain explicit. The file-based coverage gate is unchanged. A future both-tree
+inventory or bounded base/head probes can improve this advice after dogfooding.
+
+At completion, optional symbol advice also becomes a head-bound task observation
+(`#684` phase 2a). Console task detail and the UI task snapshot expose the
+screened IDs, paths, names and kinds, without source/spans or internal repository
+keys. Public reads re-screen current policy; PII stores nothing. Unknown or
+stale evidence remains unavailable. Completion prepares this optional data even
+without a reviewer, without adding a review gate. Foreign-repository tasks stay
+unknown until the brief can independently bind its analysis repository.
+
+In the console, Enter on a task in Tasks shows a `symbols` block after its plan (#684 phase 2b): each observed changed symbol is `matching` the plan or
+`unplanned`, and each planned symbol that nothing changed under is `untouched`, with the counts and the head they were observed at. The match rule is the review
+brief's own (a pair of qualified names must be equal, otherwise the last segments are). Without code facts it reads `changed symbols: unknown (no code facts)`;
+an incomplete observation says an untouched symbol may have changed; a private task shows nothing. Names are quoted like every agent-written string, at most 40 are
+listed and the rest are counted. The block is advice: deleted definitions are not reported, so it never proves a plan was or was not followed.
+
+Task detail also shows an `overlaps` block (#379), using the hub's read-only
+`symbolOverlaps` projection of its existing open-task/other-owner overlap selection.
+Each row names the other task ID and screened shared paths. A row says "same file,
+different symbols" only when the same current screened predicate used by completion
+notices establishes observed disjointness; otherwise it remains an ordinary overlap.
+The block states "observed names only, deleted definitions may be missing". PII tasks
+are excluded on both sides by their markers, even if the routing locality limit is
+disabled. No pair result is stored, and the console never infers
+one from its own plan or receipt. Missing fields on older hubs show no block; an
+empty list says `none`. At most 40 pairs and 40 paths per pair are listed, with
+omitted counts. Related-note counts remain a later slice.
+
+When both tasks have complete public observations and non-empty disjoint sets
+for every exact shared file, a completed-change notice says "same file, different
+symbols" with the observed-name/deleted-definition ceiling. It still tells the
+recipient to check the completed work. Missing or partial evidence keeps the
+ordinary notice; plan-time overlap and coverage gates are unchanged. The receipt
+keeps one current head, with at most 500 entries and 64 KiB total. This is the
+data slice; the formatted Code panel and memory links follow separately.
+
 `hub_review` takes `coverage {reviewed, skipped}`: in enforce an approval that leaves
 a reviewable path unaccounted is refused, and advise notes the gap in the verdict
 (#520). The hub
@@ -1027,8 +1190,14 @@ ahub report --since 7d          # turns, busy time and tokens per peer, messages
 ahub report --since 7d --json   # the same numbers as JSON
 ahub report --by task           # tokens, turns and wall time per task and class, with the unattributed share
 ahub export --since 24h         # the raw events as JSON lines, for your own analysis
+ahub report --dogfood [--since 7d|<iso>] [--json]   # read-only scorecard: flow, quality, cost, delivery, performance, adoption
 ```
 
+`ahub report --dogfood` (#687) reads the event log, `hub.log`, the board and the delivery journal in `hub.db`, up to 16 recently merged
+PRs through `gh`, and the feature table in `docs/dogfood.md`. It covers the last seven days by default, takes no `--by`, and prints the same
+document as `--json` with `unknown` in place of null; missing or truncated evidence is unknown, never 0. It exports ids, timestamps and counts
+only and runs no model. Its bounds and the weekly routine are in [dogfood](dogfood.md#weekly-scorecard).
+
 Per peer and model route, `ahub report` also counts model changes between consecutive
 decisions, how many of them landed inside tool loops and, with `stay_switch` on, sessions
 and the planner's switches (#197). With `stay_switch = "off"` session boundaries are not
@@ -1036,6 +1205,41 @@ recorded; `shadow` routes exactly as `off` does, so it is the baseline to compar
 A route event records the decision, so a load-moved request that its MLX fallback served counts
 as a change to `dgx/fast`; the relay's request journal records which backend served it.
 
+The event log also keeps the history of limits (#683). Each Codex update that adds tokens writes a
+`usage` event with source `codex_appserver` next to the existing `tokens` event, split into input, cached
+input, output and reasoning, so re-sent cached context is visible. A budget pause writes `budget_pause`
+and its end `budget_resume`, with the window, the reset time and who ended it (`hub`, or `person` for an
+`ahub budget resume`). A window's reset writes `quota_reset` when its `resetsAt` moves forward or its `used`
+falls by 0.5 or more inside one window id, once per peer, window and `resetsAt`. These events hold ids and
+numbers only, add no protocol version and are ignored by a reader that does not know them. `ahub report`
+does not show them: `ahub usage` and `ahub usage limits` read them (below), and the console's Usage tab shows each peer's last resets (#683 U3). A dashboard usage view is pending (U4).
+
+`ahub usage` reads the same events from an incremental roll-up in `hub.db` instead of rescanning the log (#683):
+
+```bash
+ahub usage [--since 7d|<iso>] [--by peer|task|issue|pr|release|day|model] [--json]
+ahub usage limits [--peer <id>] [--limit <n>] [--json]   # current quota windows, plus the newest 200 (up to 5000) pauses, resumes and resets
+ahub usage total [--json]                  # lifetime development tokens since the first event, per peer and overall
+```
+
+The daemon folds `events.jsonl` into `usage_rollup`, `token_rollup` and `limit_events` from a stored byte offset, at most 8 MiB per pass and
+only whole lines, and each pass commits its rows and the new offset together, so a crash repeats a pass and never half-applies one. A rebuild
+from byte 0 gives the same rows (tested). A log that was replaced by a shorter one is folded again from the start. On this project's 47 MB,
+238k-line log the first fold took about 170 ms and a `usage` command about 95 ms, against about 150 ms for `ahub report --by task`, which
+rescans the whole file on each call.
+`issue`, `pr` and `release` are the board's current links of each task, read when you ask, so a task linked later is counted under its issue
+for the history it already spent. A task with no link, and a record with no task, are `unattributed`.
+
+Every number names its source: `native` (the provider's own counter), `hub count` (the hub's own `tokens` increments, which cover peers that
+report no usage record, such as Jcode and Kimi), or `unknown`. Unknown is never shown as 0. `TOTAL` includes cache reads and `WITHOUT CACHE`
+removes them; Claude's total is the sum of its four reported counters because its transcript carries none (`ahub report` still shows it as unknown), and a source whose input already
+contains the cached part (Codex, the gateway) gets no derived total. A lifetime total that mixes a native and a hub-counted peer is labelled
+`hub count`. When a peer is unknown the overall figure is `partial, at least`: a lower bound that leaves the named peers out, never a sum that counts them
+as 0 (it is `unknown` when no peer is known). The overall `WITHOUT CACHE` is unknown unless every peer's cache split is known.
+`usage limits` shows the newest 200 events and says `N older events are not shown` when it cuts (`--limit <n>`, up to 5000, shows more). A pause that the events
+never ended and the hub no longer holds (cleared by `ahub reset`, which keeps the log as it was) shows as `pause ended, end unknown`, not as open. A private task shows its id and `[pii]`, never
+a title. The person and a configured planner may read usage, in the console, the dashboard control link or the CLI; every other agent is refused.
+
 `ahub report` counts the same overlap warnings as `scripts/overlaps.ts`, from the
 structured events instead of log lines. `--by task` uses the task each usage and
 token record was attributed to when it was written: the delivery that started the
@@ -1301,7 +1505,10 @@ stays the default until an evaluation says otherwise (`docs/cooperbench.md`).
   file that falls out of the 64 a peer touched is named until the peer reads
   that back. Only regular files
   of 256 KB or less inside the project are read, re-resolved at every read and
-  opened without following links; larger ones are named without a diff. Facts never go through the bus or the delivery journal;
+  opened without following links; larger ones are named without a diff, compared
+  by size and modification time, or by their bytes while written in the last 2 s
+  (4 MiB or less each, 16 MiB per store per event-loop turn), since a same-size
+  rewrite within one filesystem timestamp tick keeps the stat. Facts never go through the bus or the delivery journal;
   `events.jsonl` records `fact`, `fact_ack` and `capability` events with bytes
   and latencies.
 - Integration. A member's `hub_task_done` is a completion intent. The member
@@ -1375,6 +1582,14 @@ stays the default until an evaluation says otherwise (`docs/cooperbench.md`).
   turns the stale-notice drop off, for a controlled comparison only (the #106
   ablation in `docs/cooperbench.md`); the hub logs it at start.
 
+## Always-ask action policy foundation (#636)
+
+The classifier, local configuration and session budget counter are available in source. Adapter enforcement is pending: each peer's `ahub status` row says `always-ask not enforceable: adapter integration pending`. A default-on policy does not add a pre-tool check to a native CLI by itself.
+
+Only ignored, untracked `.agenthub/config.local.json` can hold `action_policy`. Its optional keys are `enabled` (default true), `always_ask` (a distinct subset of publish, external-write, destroy, install; default all), and `budgets` (per-class integers 0..1000; defaults 1, 5, 3, 2 respectively). Shared `config.json` cannot set this policy and gets no confirmation offer. A tracked or unknown-trust local file is ignored. Use `ahub settings set action_policy.enabled <true|false>` or `ahub settings set action_policy.budgets.<class> <n>` for registered settings; change `always_ask` in the local file and use the existing confirmed terminal reload. Policy publication invalidates cached grants and pending approval challenges. Startup currently reads the untracked local policy without a retained confirmation; this ceiling must be addressed before the adapter gates ship (#312/#313).
+
+The ledger asks first and after the approved class budget is spent. Adapter integrations must request that class allowance explicitly; an ordinary one-time answer does not seed the cache, and a cached budget never suppresses a prompt required by the native mode. One approval includes its own invocation; budget zero asks for every invocation. A fresh native session resets counters, and status polls do not bind sessions. Unknown command syntax retains native permission handling. This foundation never changes a sandbox or bypasses a denied permission; per-adapter enforcement tests land with their integrations.
+
 ## Permission modes for running peers
 
 Use a plain terminal to inspect or change a running peer:
@@ -1714,7 +1929,11 @@ entries and fields. It contains machine paths and the peer identity, not a token
 with a warning. `--print-command` shows the change and command without writing.
 The configured `kimi_cmd` must be a single executable or end in exactly `acp`;
 the TUI uses the executable or drops that final word. Other wrappers are refused
-with the headless command rather than guessed.
+with the headless command rather than guessed. The launcher uses the running
+hub's `kimi_cmd`; when that value has no TUI form, the refusal says so, since an
+edited file value waits for `ahub settings reload`.
+
+After three empty inbox reads within ten minutes by a pull-only peer with no assigned task or review, the hub adds polling advice and one console notice per streak (peer id and counts only); a delivery or assignment resets it, and restart clears the in-memory counters.
 
 The TUI is pull-only. Its model reads `hub_inbox` at the start of work, between
 steps of longer work and before reporting, and shares results, and mid-work
@@ -1725,7 +1944,9 @@ and important markers do not push or interrupt it. There is no hub busy state,
 watchdog, console approval, hub permission mode, context reading, automatic quota
 pause/handoff, shared final answer or session resume. When important messages are
 waiting, every other hub tool result ends with a line saying how many, so the model
-reads `hub_inbox` before starting long local work (#398). Read quota and approve tools
+reads `hub_inbox` before starting long local work (#398). One `hub_inbox` read drains the queue oldest first up to
+64 KiB of rendered text and, when more waits, ends with `N more waiting: call hub_inbox again before you start work` (#713).
+Read quota and approve tools
 in Kimi's own TUI; a person can pause the hub queue by hand. End the native terminal
 session there, not with `ahub stop kimi`.
 
@@ -1895,8 +2116,9 @@ but cannot show pushes, so it attaches tools-only (protocol 16, issue #205):
   `messages wait for hub_inbox; for pushes restart Claude with ahub claude`; the
   console footer shows `tools-only: ahub claude` and the dashboard shows the
   status line.
-- The session reads them with `hub_inbox`, at most ten messages at a time plus
-  the hub's recall note when one waits (it says how many still wait). Each read is one `completed` delivery (`read through
+- The session reads them with `hub_inbox`, which drains the queue oldest first (important messages marked, as ever) up to 64 KiB of rendered text plus
+  the hub's recall note when one waits (#713; a push peer's digest is still ten items). When more is waiting the result ends
+  `N more waiting: call hub_inbox again before you start work`. Each read is one `completed` delivery (`read through
   hub_inbox` in `ahub queue list`); nothing is ever `accepted`, and the session
   has no `hub_delivery_done`. A read the model never saw (the tool call was
   cancelled, the plugin died) cannot be retried: `ahub queue show <id>` of the
@@ -1934,7 +2156,7 @@ bridge currently receives no positive per-server activation signal.
 
 A Claude session started with `ahub claude` receives pushes when it is idle. While it is busy:
 
-- Every hub tool result carries fresh counts, `(N queued hub message(s), M important hub message(s) waiting: call hub_inbox before starting long local work)`, when important work waits. A zero count clears an earlier hint.
+- Every hub tool result carries fresh counts, `(N queued hub message(s), M important hub message(s) waiting: call hub_inbox before starting long local work)`, when important work waits. A zero count clears an earlier hint. Under a delivery hold that refuses pulls, the counts and held rows stay but the `hub_inbox` advice is dropped.
 - `hub_inbox` reads the daemon queue (and any local failed-push buffer) in a channel session too. A read is one `completed` delivery, like a tools-only read; holds refuse it the same way.
 - An important message is pushed into the running turn (steered) instead of waiting for the turn to end. Mid-turn reading was verified on Claude Code 2.1.302; an older client that drops it leaves the delivery `accepted` until a person resolves it. Ordinary messages still wait for the idle push or `hub_inbox`.
 - Do not use `[FYI]` for PR ready, done, submitted, ruling-needed, blocker or changed-contract messages: they need action. `hub_task_done` and `hub_review` already notify their recipients.
@@ -2106,6 +2328,22 @@ killed.
 Rows without a live process are stale registrations; forget them with
 `ahub projects remove <id>`.
 
+## Agent CLI versions
+
+Agent CLIs update themselves often, and a hub release cannot follow every one. One policy decides each gated CLI: the Codex and Kimi fresh reviewers, Jcode, agy and Qwen (#691).
+
+- `ahub agents [--json]` lists each gated CLI with its version, verdict and verified versions.
+  - **verified:** a receipt exists.
+  - **in-line:** untested, inside the compatible line that a contract gate (Jcode, agy) declares; it starts with a note.
+  - **trusted:** you accepted this exact version on this machine.
+  - **refused:** the reason names the installed and verified versions and the command that admits it.
+  - **unknown:** the CLI is not on PATH, or its version could not be read.
+- `ahub agents trust <id> <version>` accepts one untested version on this machine (`~/.agenthub/agent-compat.json`); `--revoke` undoes it. Only the person can run it; agent shells are refused.
+  - For the reviewers, trust lifts only the version pin. The MCP inventory, Apps/plugins/hooks readback, sandbox denial fixtures and binary fence still run before every child, and a failed leg still refuses.
+  - What trust cannot prove is printed when you trust.
+- `ahub doctor` shows one line for each installed CLI that is not on a verified version.
+- A weekly workflow (`.github/workflows/agent-compat.yml`) compares the latest npm versions of Codex, Kimi Code and Qwen Code with the verified sets, keeps one `agent-compat` issue up to date while one is ahead and closes it when none is. The next step for each listed version is a model-free receipt in `docs/verification/`, then adding it to `verified` in the same PR. Jcode and agy are not watched.
+
 ## Upgrade and crash recovery
 
 On a terminal, one command reviews, applies and follows an upgrade:
@@ -3271,7 +3509,7 @@ that the file is untracked; a dropped value is reported by the settings result.
 
 ## SDLC artifact receipts and gates
 
-The playbook lifecycle (#257, #481) is off without `.agenthub/sdlc.toml`. When enabled its stages are intent, spec, plan, build, test, review, merge, release and maintain, grouped as Plan, Design, Build, Test, Deploy and Maintain. Advise shows blockers; enforce checks implemented head-bound review and approval gates. Stored implement/verify receipts read as build/test; new enabled receipts use canonical ids. See [the SDLC contract](sdlc.md) for gates, required check names, local receipts, console-only readbacks and the S0-S8 delivery table. A person accepts a spec issue with `ahub sdlc accept <task> --issue <n>` (S1). The planner records plan reviews with review and CI scope (`hub_plan_review`, `ahub sdlc plan-review`) and grooms with `ahub backlog groom`; `ahub backlog return <task> <revision> <reason>` returns accepted, untouched work (S9). `ahub sdlc costs [owner/repo]` reports review rounds and CI runs of merged PRs without writing the board (S10). S11 release trains ship in 0.12.37 (see [release scheduling](#planner-release-scheduling)). S2-S7 and a full live advise/release cycle remain pending. Owners/reviewers record bounded identities through `hub_sdlc_record`; these grant no additional authority. Off output, receipt and schema shapes stay unchanged.
+The playbook lifecycle (#257, #481) is off without `.agenthub/sdlc.toml`. When enabled its stages are intent, spec, plan, build, test, review, merge, release and maintain, grouped as Plan, Design, Build, Test, Deploy and Maintain. Advise shows blockers; enforce checks implemented head-bound review and approval gates. Stored implement/verify receipts read as build/test; new enabled receipts use canonical ids. See [the SDLC contract](sdlc.md) for gates, required check names, local receipts, console-only readbacks and the S0-S8 delivery table. A person accepts a spec issue with `ahub sdlc accept <task> --issue <n>` (S1). The planner records plan reviews with review and CI scope (`hub_plan_review`, `ahub sdlc plan-review`) and grooms with `ahub backlog groom`; `ahub backlog return <task> <revision> <reason>` returns accepted, untouched work (S9). `ahub sdlc costs [owner/repo]` reports review rounds and CI runs of merged PRs without writing the board (S10). S11 release trains ship in 0.12.37 (see [release scheduling](#planner-release-scheduling)). S3 structured review findings (an open Important finding blocks approval in enforce; `max_nits` in `sdlc.toml` caps nits) and S2 literal-path plan conformance with the person-only `ahub sdlc accept-departure <task> <head> <reason...>` are in source; see [findings](sdlc.md#structured-review-findings-481-s3) and [plan conformance](sdlc.md#plan-conformance-481-s2). S4-S7 and a full live advise/release cycle remain pending. Owners/reviewers record bounded identities through `hub_sdlc_record`; these grant no additional authority. Off output, receipt and schema shapes stay unchanged.
 ## Optional Qwen Code peer
 
 Select Qwen per project with `ahub roster add qwen`; it defaults off and is absent
@@ -3280,11 +3518,12 @@ starts its ACP peer. `--print-command` previews; TUI is refused until #286's
 verification. `ahub stop qwen` stops the owned process group. A conductor may start
 it only through the selected roster and existing capabilities.
 
-The supported native ACP identity is qwen-code 0.25.0. A CLI version label alone
+Receipt-verified native ACP identities are qwen-code 0.25.0 and 0.26.0 ([dated receipt](verification/2026-10-22-kimi-qwen-compat.md)). A CLI version label alone
 is insufficient: startup verifies its native identity/version and advertised mode
-ids before any prompt. The observed local installation reports CLI 0.25.0 while
-its package/ACP source says 0.24.1; do not call that installation ready. Configure
-`qwen_cmd` only in untracked config.local.json with a verified 0.25.0 executable.
+ids before any prompt. The earlier local installation reported CLI 0.25.0 while
+its package/ACP source said 0.24.1; that was not a ready identity. The 0.26.0 receipt
+used a private prefix and did not upgrade PATH. Configure `qwen_cmd` only in
+untracked config.local.json with a receipt-verified executable.
 The provider's tunnel/relay, if needed, must already be available. Startup cannot
 prove network readiness from a version command.
 
@@ -3316,11 +3555,11 @@ TUI input may interleave with an ACP turn; there is no single-writer guard. Clos
 After upgrading to the recipient-retry release, a Jcode project MCP entry written before `AGENTHUB_DELIVERY_ONLY` was added is intentionally stale. Once per project, the person runs `ahub jcode --mode headless` before using conductor/dashboard starts. The launcher rewrites only the owned entry with the delivery-only marker, preserving foreign entries and refusing collisions; recovery relaunches already use this CLI path. Readiness checks never rewrite the file, and an explicit false marker or any other drift remains refused. Until that rewrite, daemon starts keep their actionable stale-entry refusal rather than advertising a retry tool Jcode cannot use.
 
 
-Native policy is unmanaged and has NO hub sandbox; no permission_modes.jcode or runtime mode mapping is invented. Quota and consumption remain unknown. Supported versions run from 0.98.0 up to, not including, 1.0.0 (#529). Every owned jcode process (version probe, daemon, ACP and TUI) runs with `JCODE_NO_TELEMETRY=1`. Native session/load (verified on 0.94.0 and 0.98.1) cannot prove identity, so attached Jcode blocks controlled recovery before effects and crash recovery asks for deliberate native reopening. A requested load without an echoed identity refuses; no fresh session is presented as restored. Provider/tool/native teardown receipts remain unverified in the pinned contract report.
+Native policy is unmanaged and has NO hub sandbox; no permission_modes.jcode or runtime mode mapping is invented. Quota and consumption remain unknown. Supported versions run from 0.98.0 up to, not including, 1.0.0 (#529); another version is refused before the owned daemon starts, with the version named and the trust command (#691). Every owned jcode process (version probe, daemon, ACP and TUI) runs with `JCODE_NO_TELEMETRY=1`. Native session/load (verified on 0.94.0 and 0.98.1) cannot prove identity, so attached Jcode blocks controlled recovery before effects and crash recovery asks for deliberate native reopening. A requested load without an echoed identity refuses; no fresh session is presented as restored. Provider/tool/native teardown receipts remain unverified in the pinned contract report.
 
 ## Optional Antigravity (agy) peer
 
-Antigravity is optional and off roster by default. Use `ahub roster add agy`, then run `ahub agy` in a terminal: it runs the Antigravity CLI as a fresh pull-only TUI in that terminal. It accepts the 1.4.x line: 1.4.2 is the verified version, any other 1.4.x launches with a stderr warning (agy updates itself), and other versions are refused (#589). The running hub must advertise `native_hook_launch`; an older hub refuses before any write with an upgrade-or-restart remedy. Only the person's launcher starts it: conductor starts are refused, there is no controlled restore or resume, and a declared agy extra instance is refused when the config loads (#625). Headless/print, resume (`--conversation`, `--continue`, `--new`), `--mode`, `--dangerously-skip-permissions` and `--unattended` are refused until their native mapping is verified; `--print-command` previews without writing.
+Antigravity is optional and off roster by default. Use `ahub roster add agy`, then run `ahub agy` in a terminal: it runs the Antigravity CLI as a fresh pull-only TUI in that terminal. It accepts the 1.4.x line: 1.4.2 is the verified version, any other 1.4.x launches with a stderr warning (agy updates itself), and other versions are refused (#589) unless the person trusts that exact version with `ahub agents trust agy <version>` (#691). The running hub must advertise `native_hook_launch`; an older hub refuses before any write with an upgrade-or-restart remedy. Only the person's launcher starts it: conductor starts are refused, there is no controlled restore or resume, and a declared agy extra instance is refused when the config loads (#625). Headless/print, resume (`--conversation`, `--continue`, `--new`), `--mode`, `--dangerously-skip-permissions` and `--unattended` are refused until their native mapping is verified; `--print-command` previews without writing.
 
 The launcher writes exactly `plugin.json`, `mcp_config.json` and `hooks.json` in `.agents/plugins/agent-hub/`, refusing linked or foreign entries before any write, and removes only its own matching files when the TUI ends. It never writes project-level `.agents/hooks.json` or the person's `~/.gemini` settings. Run `ahub init` afterwards to ignore the untracked plugin directory; a tracked plugin is written with a warning. The native model sees the hub tools under the server name `agent-hub_agent-hub`.
 
@@ -3366,11 +3605,15 @@ Extra instances use the existing `instances` block. For example, `"myagent-revie
 
 Configured kinds are cloud peers and never receive PII work. Quota and context are unknown, and a kind with no budget source is exempt from quota accounting, so pause it by hand if its provider refuses. After a crash the hub resumes a recorded session through `session/load` only when the agent echoes the same id, and it never reuses a recorded model. Controlled recovery (`ahub upgrade`, `restart`, `recovery`) refuses a running configured kind: stop it, then start it again with its session id. While the project declares adapters, the upgrade or restart target must advertise `configured_acp`.
 
+## External adapter modules (#451 A4)
+
+A bundled adapter module is authorized by the person with `adapter_modules` (at most 16 rows of `path` and `sha256`) in an untracked `.agenthub/config.local.json`; in `config.json` or a tracked file it is ignored with a notice, and settings never edit it. Only daemon startup imports a module: settings, reload, previews and CLI reads never do, so a change needs a restart. The module must be a single self-contained ESM file inside the project (no symlinked, world-writable or oversized file) whose bytes match the pin, and it may import only Node/Bun builtins and `@staix/agent-hub/adapter`; the scanner also refuses any `require`, `eval` or `Function` word token. Each import must settle within 2 s. A module that fails any check is refused on its own, with a bounded reason in the status reply, while startup and the other adapters continue; its roster row stays inert. A loaded kind is headless, cloud (never PII), off roster until `ahub roster add <kind>`, and has no controlled recovery: stop it and start it again with its recorded session id. While modules are declared, the upgrade or restart source and target must advertise `external_adapter_modules`. Bundling, the accepted definition subset and the conformance kit (`@staix/agent-hub/conformance`, for module CI only) are in [Adding an AI tool](adding-an-ai-tool.md#5-external-adapter-modules-451-a4). A pin authorizes code that runs with the daemon's rights; it is not a sandbox ([security](security.md)).
+
 # Headless ACP watch (#286)
 
 - A person opens `ahub watch kimi` or `ahub watch qwen` in a second terminal. `--no-thoughts` hides thought items; `--color=auto|always|never` controls colour. `q` or Ctrl+C leaves the view, keeping the peer running. Answer approvals in `ahub console` or with `ahub permit`.
 - Watch replays bounded memory history from this daemon, then displays live updates. It is the hub's read-only view, with no prompt input. It does not read native session files.
-- Kimi's default is its own pull-only TUI (#316). Watch requires `ahub kimi --mode headless`; its own TUI remains visible in its native terminal. Qwen requires roster participation and verified ACP 0.25.0. `ahub qwen --mode tui` remains refused.
+- Kimi's default is its own pull-only TUI (#316). Watch requires `ahub kimi --mode headless`; its own TUI remains visible in its native terminal. Qwen requires roster participation and a receipt-verified ACP identity. `ahub qwen --mode tui` remains refused.
 - Protocol stays 16; a same-protocol older daemon answers the new request as unknown, which the CLI reports. Since 0.12.44 a headless start that the hub itself makes for Kimi or Qwen opens this view automatically through the terminal provider (see Start modes; #286).
 - Native T0 limits: [ACP watch verification](verification/2026-10-11-acp-watch-t0.md).
 
@@ -3801,8 +4044,62 @@ restart the hub. For example, a reviewer can use:
 
 Start them with `ahub codex --as codex-review` and
 `ahub kimi --as kimi-review`. Codex keeps its native TUI and its own hub-owned
-app-server proxy; extra Kimi, Qwen, Pi and local instances use headless starts.
-Extra Jcode instances are unavailable. An extra Claude instance is a reviewer or
+app-server proxy; extra Kimi, Qwen, Jcode, Pi and local instances use headless starts.
+Extra Jcode instances are supported (#685), in `.agenthub/config.local.json` only:
+
+```json
+{
+  "instances": {
+    "jcode-claude": { "kind": "jcode", "roles": ["verifier"], "jcode_home": "/Users/you/.agenthub/jcode/claude",
+                      "provider": "claude", "model": "claude-sonnet-5-5" },
+    "jcode-local":  { "kind": "jcode", "roles": ["verifier"], "jcode_home": "/Users/you/.agenthub/jcode/local",
+                      "provider_profile": "onprem" }
+  }
+}
+```
+
+`jcode_home` is required, absolute, and must differ from the base `jcode_home`, from
+every other instance's and from any directory inside or around them, however it is
+spelled: a symlink, a system alias such as `/tmp` and `/private/tmp`, or a case-only
+alias is the same home (the hub refuses the configuration at startup otherwise). At most 8 Jcode instances are accepted per
+project. `provider`, `model` and `provider_profile` are optional and passed to Jcode
+as `-p`, `--model` and `--provider-profile` exactly as written; any other field is
+refused, and these fields are never editable from settings.
+
+You authenticate inside Jcode, never in the hub. Run Jcode's own setup against each
+home (provider login, API key, an OpenAI-compatible base URL such as the on-prem
+gateway, a provider profile), and initialize that home's MCP store with Jcode's own
+client, as for the base peer. The hub never reads, writes, copies or injects a model
+credential, a key, a token or a provider URL, and never creates the home. Its only
+start preflight is read-only: the home must exist as a directory you own, otherwise
+the start is refused and nothing runs. A Jcode sign-in failure appears as the start
+or turn error, with bounded text. An instance reports tokens only if Jcode itself
+does; until then they show `unknown`, never 0.
+
+Each instance owns its private `jcode serve` and `jcode acp` pair, socket, roster row
+and launch record, and acts as its own peer id (for example `jcode-local`), never as
+`jcode`. Start it with `ahub jcode --as jcode-local` (headless; an instance has no
+TUI) and stop it with `ahub stop jcode-local`: the base Jcode and every other instance
+keep running. An extra implementer needs the same managed worktree as every extra
+implementer (`worktree: ".worktrees/jcode-local"`). Every instance is a cloud peer
+(`trust.onPrem` is false), whatever provider you configured: it never receives PII
+work. `ahub status` and the dashboard show the provider, model and profile as
+declared, and `ahub doctor` lists the MCP servers each rostered instance's home would
+load.
+
+Upgrade note (#368): the project's `.jcode/mcp.json` entry for Jcode no longer names
+`AGENTHUB_PEER_ID`, because the file is shared by every Jcode in the project and Jcode
+gives an entry's own env precedence over the process env. Each hub-started Jcode now
+supplies its own peer id and a launch id, and the hub admits a hub-tools connection
+for Jcode only with the launch id of that peer's current owned launch. After
+upgrading, `ahub status` and `ahub doctor` report the Jcode MCP entry as not ready
+once (`jcodeMcpReady` is false for the old entry): run `ahub jcode` once and it
+rewrites its own entry, or follow the remedy text the start refusal shows. A Jcode you
+run yourself in this project outside the hub has no peer id: its hub tools refuse
+every call with that reason and never default to `jcode`, and a process that only
+sets `AGENTHUB_PEER_ID` without an owned launch is refused by the hub.
+
+An extra Claude instance is a reviewer or
 planner you start yourself: declare it with `roles` only (for example
 `"claude-review": { "kind": "claude", "roles": ["reviewer"] }`, no `start_mode` or
 `worktree`) and run `ahub claude --as claude-review` in a terminal. It keeps its own
@@ -3819,7 +4116,9 @@ the builder's summary or agent chat, and the board records its verdicts as
 the planner reviews and the task's assignment note says `reviewer=planner (fallback)`.
 A missing
 `peer_instances` feature on an old daemon or upgrade target requires a supporting
-version before launching or restoring extras.
+version before launching or restoring extras. An older recovery source without it
+is refused only while a declared instance is live or unreadable; a source whose
+status shows every declared id offline proceeds.
 
 ### Fresh reviewer pool (#519)
 
@@ -3838,9 +4137,9 @@ From 0.12.37 reviews can rotate across fresh headless Claude and Codex reviewers
 
 Start them with `ahub claude --as claude-review`, `ahub codex --as codex-review` and `ahub kimi --as kimi-review`; stop with `ahub stop <id>`. 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 #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 an installed 0.146.0 executable and a passing bounded runtime receipt before its model child starts. Use the existing `codex_bin` setting to select a supported host executable when PATH resolves another version. PATH 0.163.0 has no receipt in this slice and remains unavailable. The producer checks native binary/config stability, configured MCP inventory with only the two hub tools, effective Apps/plugins/hooks disablement 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 or 0.163.0) or one the person trusts on this machine, and a passing bounded runtime receipt before its model child starts. Both verified versions passed the [2026-10-22 model-free production admission](verification/2026-10-22-codex-reviewer-isolation.md). 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). 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 Kimi Code 2.2.0 on the hub's PATH, signed in through its managed OAuth provider, and a passing runtime preparation before each child; any other version or a failed preparation is unavailable with its reason. 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. Kimi's print output carries no token counts, so its usage stays unknown. This is a native tool-authority boundary, not filesystem or network isolation.
+Kimi requires a compat-admitted Kimi Code on the hub's PATH (receipt-verified 2.2.0 and 2.3.0), 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 receipt](verification/2026-10-22-kimi-qwen-compat.md) is model-free and does 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.
 
 A dangling or unreadable standard/configured credential root makes the Codex reviewer unavailable with only its path class in the reason (for example `~/.docker` or `$DOCKER_CONFIG`, never an expanded path or contents); repair the root and start the reviewer again.
 
@@ -3854,11 +4153,19 @@ An additional implementer must have an existing registered Git worktree and
 attached branch at `.worktrees/<instance-id>`, named explicitly by `worktree` in
 its declaration. The hub validates it and does not create it in this phase.
 Reviewer instances may share the checkout, or name their own validated worktree.
-The execution directory is separate from the canonical hub project. An Orca
+The execution directory is separate from the canonical hub project. Resolving it
+(at an extra-instance start and for a turn undo) makes up to four git calls that
+share one 5 s allowance; when it runs out the start refuses with `Git workspace
+evidence unavailable`. An Orca
 terminal may belong to either that canonical project or the instance's execution
 worktree; recovery preserves its exact recorded grouping and live launcher.
 Changing or removing the declaration invalidates its saved extra-instance
-binding. Do not infer ownership from a native-kind label alone.
+binding; the recovery screen and `--verbose` receipt still show what was recorded
+for it. A roster key left by an undeclared instance (`codex-2`) loads as inert and
+`ahub roster remove codex-2` deletes it from `.agenthub/config.local.json`; a key
+held only in the shared `config.json` is refused with a request to edit that file.
+Any other unknown roster key is still an unsupported peer. Do not infer ownership
+from a native-kind label alone.
 
 A routing preference for a kind chooses among its instances using current load
 and WIP. A manual instance id remains exact. Reviewers from the same kind share
@@ -3873,6 +4180,14 @@ CLI checks the saved workspace against the current declaration again before any
 context change or file restoration. Removing the declaration intentionally
 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.
+
+`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.
+
+For `gh release create` and `npm publish`, use the exact literal command after `ahub sdlc release-guard --`. This preflight reads evidence and never executes the command. New GitHub tags require an explicit full commit target; alternate-repository, workspace/archive and bulk target forms refuse. GitHub/npm adapter enforcement is deferred to #312/#313. This consent record does not certify a tarball, native acceptance or live publication. Detailed limits: [S6 authorization](sdlc.md#person-release-authorization-481-s6).
+
 ## Planner release scheduling
 
 Use `ahub sdlc train report <release-id>` for scope readiness and recorded release metrics. The planner creates future release rows, activates one train, and assigns tasks through the release-only hub tools. A due date requests a cut review; it never clears unfinished work. Move missed tasks to the next row with a reason, then use `ahub sdlc train cut <release-id> <revision>` from the person's terminal or `hub_release_cut` as the planner. The cut retains a short host admission lease through freeze and defers on held gate slots or unknown/quota-limited peer windows with a real quota source. Accounts without a quota reader (Kimi included when `kimi_tokens_5h` is zero) report `no quota source`; manual and budget-record pauses still defer. It does not run release preparation or publish anything. Schedule bundle/check/docs work under separate heavy admission and retain the person's native verification, authorization and upgrade window. A hotfix records its enumerated cause and keeps every gate.
@@ -3886,3 +4201,11 @@ If Codex is offline with `statusNotice.code = unidentified-cancellation`, the hu
 could not identify a cancelled native turn. Reattach the native session before
 further hub delivery. A late completion keeps this hold; verified native
 reattachment or TUI detachment clears it. The notice contains fixed guidance, without native ids.
+
+## Roles per SDLC stage (#525, planned)
+
+The design for planner, implementer and reviewer instances per stage is in the spec section "Amendment: roles per SDLC stage (#525)". Nothing in it is available yet. Each implementation slice (525-1 to 525-6) adds its operator steps here when it ships. Until then, the instance rules in "Additional headless peer instances" above are current. The planned changes an operator will see:
+
+- A Claude instance with `["implementer"]` and a `worktree`, as a terminal instance (started with `ahub claude --as <id>`) or as `start_mode: "headless"` (`permission_mode` `ask` or `ask-when-needed`; `never-ask` refused).
+- The `planner` setting accepts a list of peers or instance ids; each task records its own planner, and only that planner or the person runs planner tools on it.
+- A reviewer is never a peer that implemented the task, and a plan's author does not record its own plan review while another planner is available.