@staix/agent-hub 0.12.44 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the previous repository, archived on 2026-09-30 when this repository's history was rewritten; the one exception is the open smoke-check issue, formerly #12, which moved here as #1. Numbers in newer entries refer to this repository.
 
+## Unreleased
+
+## 0.13.0
+
+- Add the #636 action-policy foundation: a pure classifier, machine-local always-ask configuration, session-bound approval budgets and explicit per-peer enforcement status. Adapter pre-tool gates remain pending; status reports that limit instead of claiming protection.
+- Person-only release approval binds the candidate commit, version and fresh docs; an opt-in init-written Git tag pre-push guard refuses missing or mismatched approval and preserves existing hooks (#481 S6).
+- Bug-labelled tasks gain source-labelled red-first receipts and PR test-integrity readbacks. Enforce blocks review and approval when proof is missing/unknown or a pre-existing test is modified/deleted; advise shows the findings. Status and merge queues retain private metadata screening (#481 S4).
+- Version policy for native agent CLIs (#691): one verified/in-line/trusted/refused decision in `src/adapters/compat.ts` for the Codex and Kimi reviewers, Jcode, agy and Qwen; `ahub agents [--json]` shows it and the person-only `ahub agents trust <id> <version> [--revoke]` accepts an untested version on this machine; refusals name the version and the trust command; a weekly workflow reports upstream drift. Receipts add Codex reviewer 0.163.0 (#697), Kimi reviewer 2.3.0 and Qwen Code 0.26.0 (#714).
+- Extra Jcode instances with their own home, socket and state; hub tools are bound to an owned launch (#685).
+- Usage: ledger events for Codex usage breakdown, budget pause/resume and derived quota resets (#683 U1); an incremental roll-up in `hub.db`, the `usage` control op and `ahub usage [limits|total]` (U2); the console Usage panel (tab `7`) with windows, pauses, last resets and tokens per peer and per selected task (U3).
+- Code structure (#682, #684): optional bounded code facts from ripwire 0.6.7 in the review brief (observed symbols, unknown change kinds, deleted definitions not covered); head-bound task symbol observations kept apart from the task row and dropped on a head, repository or privacy change; the console task detail shows changed symbols (matching, unplanned, untouched) and screened overlaps, and a completed-change notice says `same file, different symbols` only on complete disjoint evidence; plan symbols match by normalized name across overlap notices, grooming and the review brief (#682 phase 1b).
+- SDLC: the hub links lifecycle issue and PR identity from what it can verify (#694); test integrity for bug fixes with red-first receipts and modified pre-existing test detection (#481 S4); `ahub report --dogfood`, a bounded weekly scorecard of real use (#687), with CI flow measured per recorded PR head (#704); a profile-selected review checklist and hub tool descriptions (#507).
+- Console review guidance (#711): `r` on a task in review asks `a approve` or `c request changes`, shows a guide line, refuses an empty changes note and shows the result; an agent shell refused a person-only action is told why; the user-reviewed done notice names the console path.
+- Pull-only peers catch up (#713): `hub_inbox` drains up to 64 KiB oldest first and says how many are waiting; completed-change notices are one per recipient per done, a newer one supersedes the queued one, and none go to unaccepted work; a queued delivery can be discarded while its peer is busy; refusals name their cause; the person's `ahub queue discard --peer <id> --reason <text> [--yes]` and the console Queue `D` clear a backlog. Empty pull-only polling is detected (#681).
+- Fixes: a check's exit and pipes are read through Bun.spawn so an early exit is not lost (#558); snapshot attribution survives own-commit rebases and long reflogs (#612); readiness respects the reserved owner's WIP cap (#655); host timeout kill markers are preserved in the sandbox (#700); the Codex reviewer disables legacy notify (#697).
+- Retired as announced (#481): `sdlc.workflow` (gsd-lite) no longer loads, and the `phase` receipt name is refused; record a `criteria` checklist with `hub_sdlc_record` instead. `local.bash_network: "direct"` still works and still warns; its removal moves to a later release.
+- Releases: a release with any feature bumps the minor version; a fix-only release bumps the patch.
+
+## 0.12.45
+
+The dashboard is redesigned (#469), a machine-local, content-pinned adapter module can add an ACP agent (#451 A4), the peer lists and the CLI surface come from the adapter definitions (#625), and reviews gain structured findings with an Important gate (#481 S3) and plan conformance with a person-only departure acceptance (#481 S2).
+
+- Load external adapter modules: `adapter_modules: [{ path, sha256 }]` in an untracked `.agenthub/config.local.json` names a self-contained ESM bundle that the daemon imports at startup from its hash-checked bytes, with `@staix/agent-hub/adapter` bound to the running hub. A module is refused on its own (bad pin, unsupported import, an import that does not settle within 2 s) while the builtins start; the CLI only sees bounded metadata. `@staix/agent-hub/adapter` and `@staix/agent-hub/conformance` are published for module authors. A pin authorizes code to run with daemon privileges; it is not a sandbox (#451 A4, #648, #653).
+- The peer lists (`KNOWN_PEERS`, `OPTIONAL_PEERS`, `START_MODE_PEERS`, role, help and planner order) and each builtin's `ahub <kind>` entry, preview and help usage come from the adapter definitions; the orders shown are unchanged (#625, #656). The daemon reads optional peer capability members for session generation and permission mode instead of checking peer classes (#625, #667).
+- `hub_review` and `ahub review --findings` take structured findings (id, pass, severity, disposition). In enforce, an open Important finding blocks approval and carries across later heads until a reviewer marks it fixed or false_positive or the person accepts it with a rationale; a supplied head must be the task's current head, and a finding id seen on a second task proposes one backlog card for an AGENTS.md or area-note amendment. `sdlc.max_nits` sets the nit cap (default 5) (#481 S3, #652, #657).
+- Plan conformance: a task plan may carry `proof` and `risks`, and review, status and the merge queue compare the PR's changed files with the plan's literal file or directory entries (renames and copies read as unknown). In enforce, a departure needs an amended plan or the person's `ahub sdlc accept-departure <task> <head> <reason...>`, which binds the repository, PR, head, file inventory, plan and repository scope and expires on restart (#481 S2, #665).
+- Review readiness keeps a lost reuse proof apart from quiet review drift, a delayed check that is refused tells its owner, and review-thread authors other than the person count as pending bot comments (#230, #641, #643, #644).
+- A large file rewritten with the same size within one filesystem tick on Linux is now seen as changed: facts compare a recently written file by its bytes, within a bounded budget (#428, #646).
+- When `ahub kimi --mode tui` fails because the running hub's retained `kimi_cmd` has no TUI form, the error says the command is the running hub's and that the file's value waits for `ahub settings reload` (#654, #658).
+- The daemon's snapshot Git budget reads an injectable clock, a host-only `snapshotClock` option, so a test can hold it fixed and a slow CI disk cannot spend the 250 ms before a turn's end evidence is read (an exhausted budget records an unknown tree, and an unknown tree restarts the empty-turn stall count: the intermittent #661 failure of the #498 stall test). Nothing in the shipped daemon sets it, no configuration key or tool reaches it, and the share stays 250 ms.
+- The dashboard board gets simpler cards (title, owner avatar, one state and priority badge, release), a task detail that opens as a right-hand sheet with its lines grouped into Status, People, Dates and Links, and a Plan sheet that holds the five board forms (plan, split, releases, delivery evidence, propose) with the fields and actions they had (#469 R3).
+- The dashboard gets an app shell: from 1024px a sticky top bar and a left sidebar, below it a row of tabs that scrolls inside itself so the page never scrolls sideways; the connection status shows a coloured dot; keys `1`-`7` switch views, `?` lists the keys and `Esc` closes a sheet, ignored while typing; navigation icons come from an inline sprite of nine Tabler icons (MIT notice in `THIRD_PARTY_NOTICES.md`). View names, order, the cookie and ids are unchanged (#469 R2).
+- The dashboard's style block is rewritten around one token block (colour, a 4px spacing scale, a type scale, a 6/10/full radius rule and two shadows), the dead rules are gone, the indigo accent replaces green for primary actions, focus and selection, and every peer colour has a light and a dark variant. The layout, views and behaviour are unchanged, and the contrast test now also covers the accent, dots, disabled controls and the peer palette in both themes (#469 R1).
+- The dashboard's Agents rows become a summary line plus one folded details block, the Stream gets aligned event rows with its filters above the list, Memory rows and detail use the colour tokens, Settings groups are sections with a "restart pending" badge and Message uses the shared form styles. The star, arrow, checking and Office condition glyphs become Tabler icons and drawn shapes next to their words (three more icons, twelve in all), the Office scene's colours are checked through the same tokens in the contrast test, and a test now fails if a listed glyph comes back (#469 R4, R5).
+- The dashboard keeps task cards, peer rows and memory rows per id across a poll, so hover, an open fold and a focused card survive an update that changed something else. It gets quiet motion on `transform` and `opacity` only (press, view fade, card arrival, toast, sheets) that is off under reduced motion, first-load skeletons for the board and the peers, empty views that name their command, a disconnected state with the time of the last snapshot, and notices as an `aria-live` toast stack where errors stay until dismissed and a success fades after 4 s (#469 R6).
+- A board card's one badge now also says when the task is overdue or its check is running ("in progress P2, overdue, check running"), in its text and in the card's accessible name, instead of a second and third badge. An overdue card turns the badge warn unless the state is already an error, and the task detail keeps its own Overdue and Check running lines (#293).
+- The dashboard keeps its first-load skeletons for the board and the peers after a project switch until that project's first snapshot renders (a slow or failed first snapshot no longer reads as "No project selected", which is now only for no running project), and a toast that is dismissed, expires or is pushed out no longer takes keyboard focus from another toast's Dismiss button (#469 R6 follow-ups).
+- Four #450 I2 follow-ups: the interactive recovery screen and `--verbose` receipt now show a restored extra's recorded outcome after its declaration was revoked instead of throwing "invalid restore receipt"; a roster key left by an undeclared instance (`codex-2`) loads as inert and `ahub roster remove codex-2` deletes it, while any other unknown key is still an unsupported peer (only a kind that can declare an instance counts: `roster.jcode-worker` stays a typo). A key that lives only in the shared `.agenthub/config.json` is refused with "edit .agenthub/config.json" instead of reporting a removal that changes nothing, and the removal says "stale roster key removed" instead of a roster state; the `peer_instances` refusal text and the spec say it applies only while a declared instance may be live, and ask to end the extra sessions before removing a declaration; and the git calls behind an extra-instance start share one 5 s allowance instead of 5 s each (#225).
+- A Claude channel tool result no longer tells a session to call `hub_inbox` while a delivery hold refuses its pulls (the counts and held rows stay), and a `hub_inbox` result states the queued count once (#221). Documented limit: mid-turn steer of a push-capable Claude session was proven only on Claude Code 2.1.302.
+
 ## 0.12.44
 
 A standard ACP agent can join a project from config alone (#451 A3), adapter definitions become the single dispatch point (#451 A2b), agy stops reading Claude's state files (#624), and owner turns that write nothing are flagged (#498).

package/README.md

@@ -1,139 +1,106 @@
 # agent-hub
 
-A hub on one developer's machine where coding agents work as a team: Claude Code,
-Codex, Kimi Code, Pi and a hub-owned local worker (Qwen Code, Jcode and Antigravity
-optional) share a message bus and a task board per project and one memory on the
-machine, each attached through its own native interface.
+A hub on your own machine where coding agents work together as one team. Claude
+Code, Codex, Kimi Code, Pi and a hub-owned local worker (plus Qwen Code, Jcode and
+Antigravity if you want them) share a message bus, a task board and a memory, each
+connected through its own native interface.
 
-Status: 0.12.44, control protocol 16. Bun + TypeScript, one loopback daemon per
+Status: 0.13.0, control protocol 16. Bun + TypeScript, one loopback daemon per
 project. Site: [agent-hub.staix.net](https://agent-hub.staix.net).
 
-## What it does today
-
-- **Peers, not a pipeline.** Every agent can message the others, and the hub
-  delivers to each through its native surface (Claude channel plugin, Codex
-  app-server, ACP, Pi RPC or TUI). Messages are batched into digests, priorities
-  decide what interrupts a turn, and delivery is durable across restarts.
-- **A shared task board.** Tasks are proposed, accepted, done and reviewed through
-  hub tools. `routing.toml` assigns owners by task class, roles split planning,
-  implementation and review, and a designated planner can be changed live.
-  Cause-deduplicated stalls and unread pull-only offers need attention; cancellation
-  closes work without approving it or releasing its dependents. Owners of
-  overlapping work in the same repository are told what changed.
-- **Shared memory.** Decisions, contracts, fails and findings go to the hub's own
-  store through the exact-pinned first-party `@staix/agent-mem` library (short-
-  and long-term tiers, a typed graph, git sync between machines),
-  next to optional claude-mem capture. Entries belong to their project unless
-  saved as shared, which makes them readable from every project on the machine.
-  Agents get memory as a recall preface, as briefs on a task, and through bounded
-  `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools. Agents
-  can propose corrections; candidates stay outside evidence until a person acts.
-- **Local and remote models.** Pi and the local worker run on DGX or local MLX
-  through an authenticated relay; in-process hub routes select models by task
-  through a self-hosted OmniRoute gateway. Tasks flagged as PII stay on the on-prem
-  worker.
-- **Guard rails.** The local worker and Pi run in a sandbox, and by default their
-  writes and shell commands wait for the person's approval; a permission mode
-  the person picks (`ask-when-needed`, `never-ask`) skips some or all prompts.
-  Budgets pause a peer before it runs out of quota, and recovery never replays
-  an effect whose outcome is unknown.
-- **Operations.** A terminal console and a local dashboard, one hub per
-  repository or worktree with a machine-wide view, and `ahub upgrade` that carries
-  running sessions across versions. Settings reload without a restart where their
-  apply class allows; guarded values wait for a person's confirmed
-  `ahub settings reload` in a terminal. The console supports revision-checked task
-  assignment/unassignment, delivery-queue resolution, per-peer planner WIP limits
-  and backlog management from the Tasks tab. Peers with independent
-  tool turns can request one uncertain redelivery; the delivery-only local worker
-  and headless ACP peers leave held deliveries for the person to resolve.
+## Quick start
 
-## Where it is going
-
-- **Curated memory** ([#412](https://github.com/STAIxBWLB/agent-hub/issues/412)).
-  The memory core now lives in [agent-mem](https://github.com/STAIxBWLB/agent-mem)
-  (`@staix/agent-mem`, with the `amem` CLI), which agent-hub uses as its one
-  exact-pinned first-party dependency. Next, memory becomes curated rather than
-  captured: compression, removal, correction
-  and failure-driven management, each shipped only after its contract and a
-  measurement.
-- **Every peer able to do its share** ([#418](https://github.com/STAIxBWLB/agent-hub/issues/418)).
-  Bounded task-spec reads and opt-in isolated checks are implemented. Installed
-  managed-Pi verification (AC8) remains open; source and CI results do not certify
-  that live runtime.
-- **Measured, not assumed.** Add-ons and memory are kept or dropped by controlled
-  comparisons ([#248](https://github.com/STAIxBWLB/agent-hub/issues/248),
-  [#258](https://github.com/STAIxBWLB/agent-hub/issues/258)).
+You need [Bun](https://bun.sh) 1.4.2 or later on PATH.
 
-## Install
+```bash
+bun add -g @staix/agent-hub && ahub setup
+cd <your project> && ahub init && ahub up   # daemon plus the operator console
+```
 
-Requires [Bun](https://bun.sh) 1.4.2 or later on PATH.
+Then start the agents you use, one terminal each, and talk to them:
 
 ```bash
-bun add -g @staix/agent-hub && ahub setup
-cd <your project> && ahub init && ahub up
+ahub claude                                  # Claude Code with the hub channel
+ahub codex                                   # Codex TUI, attached through the hub
+ahub say "Each of you: reply with your name."
+ahub ui                                      # the web dashboard
 ```
 
-`ahub init --dry-run --json` shows what init would write first. While hubs run,
-`ahub upgrade` moves them to the latest release.
-
-After upgrading from 0.12.30 or earlier, run `ahub jcode --mode headless` once in each
-project that uses Jcode to refresh its owned MCP entry before conductor or dashboard
-starts of Jcode. The entry's format is unchanged in 0.12.37; a daemon start that still
-reports the entry missing or stale is fixed by the same command, which since 0.12.36
-writes the running hub's own plugin bundle (#502). Since 0.12.37 the hub accepts jcode
-0.98.0 or later, below 1.0.0, and no longer 0.94.0 (#529).
-Since 0.12.39 `ahub jcode` opens Jcode's native TUI on the hub-owned ACP session by
-default (#464); `--mode headless` or `ahub settings set peers.jcode.start_mode headless`
-keeps headless startup. On 0.12.39 the TUI launcher stopped after the first hub turn;
-0.12.40 opens it again (#564). On 0.12.40 `ahub codex` in a recorded Orca terminal
-failed with `invalid remote address`; 0.12.41 starts it again (#586). Since 0.12.42
-`ahub agy` accepts the Antigravity CLI 1.4.x line (1.4.2 verified; other patches warn),
-because agy updates itself and 0.12.41 refused 1.4.3 (#589). Since 0.12.43 agy's native reads are recorded as peer facts on 1.4.2 and 1.4.3 (#555); 1.4.3 stays unverified, and in its TUI the hub tools appear from the second turn (#267, #607). Since 0.12.44 a headless Kimi or Qwen start made by the hub also opens `ahub watch <peer>` through the terminal provider (#286), an owner turn streak with no recorded writes raises a planner notice (`task_sweep.no_writes_turns`, default 2, 0 disables; #498), a declared agy extra instance is refused at config load (#625), and a standard ACP agent can join a project as a config-only adapter declared in untracked `.agenthub/config.local.json`: headless, off roster by default and pinned to its native identity (#451).
-Cancellation needs a daemon advertising `task_cancel`; controlled downgrades
-refuse while cancelled rows exist. Live-test delegated CLI commands need a daemon
-advertising `cli_audit_delegated` and refuse with an upgrade remedy otherwise
-(#410). For local/Pi implementation, opt in to an available
-`checks.runner = "container"`; issue-backed owners also need authenticated
-spec access. PII work and designated reviewers retain their separate exemptions.
-See [release verification](docs/verification/2026-10-21-0.12.44.md) for the live legs
-still open, including #418 AC8, #438 AC7, the native console settings leg (#439 AC5),
-real upgrades with reattach (#463) and with a managed terminal and cancelled tasks
-(#478), a live headless Claude review (#223), a Claude session over 32 MiB (#517), a
-live fresh Codex review (#519), a live split of a real memory home (#536), the live
-agy TUI/account leg (#485, hub task #251), Kimi's interactive-TUI coexistence and
-usage checks (#533), Jcode's TUI with a personal account, a real provider and hub-tool
-calls (#464), a live Jcode tool call held past the inactivity watchdog (#542), a live
-steer of a busy Jcode turn (#572) and a real upgrade that exercises the terminal owner
-record (#482).
-
-Before migrating a memory home with `amem`, upgrade every hub using that home to
-0.12.30 or later, check `ahub memory profile-check`, then quiesce and close all memory
-consumers. Shared v1 remains the default; installing this release does not migrate
-data. The curated shard migration (`amem migrate --shards`, agent-mem 0.4.0) needs
-every hub using that home to run 0.12.37 or later, which opens memory through shards
-(#534). An older hub (0.12.36 or earlier, agent-mem 0.3.1) does not detect the
-split: it keeps reading and writing the old layout, and its writes reach the shards
-only through `amem migrate --shards --resume`. Upgrade or stop every such hub before
-splitting. `ahub memory profile-check` is split-aware (#536). See [memory profiles and rollout](docs/memory.md#selected-memory-profile).
+`ahub init --dry-run --json` shows what init would write. The
+[Quickstart](docs/quickstart.md) walks through a first session and a working day.
+
+## What you get
+
+- **Peers, not a pipeline.** Any agent can message the others. Messages are batched
+  into digests, priorities decide what interrupts a turn, and delivery survives
+  restarts.
+- **A shared task board.** Work is proposed, accepted, done and reviewed through hub
+  tools. Roles split planning, implementation and review, `routing.toml` picks
+  owners by task class, and owners of overlapping work are told what changed.
+- **Shared memory.** Decisions, contracts, fails and findings are kept through the
+  first-party [`@staix/agent-mem`](https://github.com/STAIxBWLB/agent-mem) library
+  (short- and long-term tiers, a typed graph, git sync between machines). Agents get
+  it as a recall preface, as briefs on a task, and through bounded search tools.
+- **Local and on-prem models.** Pi and the local worker can run on DGX or local MLX
+  through an authenticated relay. Tasks marked as PII stay on the on-prem worker.
+- **Guard rails.** The local worker and Pi run in a sandbox, and their writes and
+  shell commands wait for your approval unless you choose a looser permission mode.
+  Budgets pause an agent before it runs out of quota, and recovery never replays an
+  effect whose outcome is unknown.
+- **Operations.** A terminal console and a local dashboard, one hub per repository or
+  worktree with a machine-wide view, live settings reload, token usage and quota
+  history (`ahub usage`), and `ahub upgrade`, which carries running sessions across
+  versions.
+
+## Upgrading
+
+Run `ahub upgrade` while your hubs are running. Read the notes for your version in
+the [Quickstart](docs/quickstart.md) ("Upgrading to ...") and the
+[Changelog](CHANGELOG.md) first: some releases need a one-time step, such as
+refreshing an agent's MCP entry.
+
+Agent CLIs update themselves. `ahub agents` shows which installed versions the hub
+accepts, and `ahub agents trust <id> <version>` accepts an untested one on this
+machine.
+
+Before you migrate a memory home with `amem`, read
+[memory profiles and rollout](docs/memory.md#selected-memory-profile). Every hub that
+uses the home must run a version that understands the new layout.
+
+## Where it is going
+
+- **Curated memory** ([#412](https://github.com/STAIxBWLB/agent-hub/issues/412)):
+  compression, removal, correction and failure-driven management, each shipped only
+  after its contract and a measurement.
+- **Every agent able to do its share** ([#418](https://github.com/STAIxBWLB/agent-hub/issues/418)).
+- **Measured, not assumed.** Add-ons and memory are kept or dropped by controlled
+  comparisons ([#248](https://github.com/STAIxBWLB/agent-hub/issues/248),
+  [#258](https://github.com/STAIxBWLB/agent-hub/issues/258)).
+
+Live checks that still need a real account or a person are listed in the
+[release verification report](docs/verification/2026-10-23-0.13.0.md) and the
+[smoke checklist](docs/smoke.md).
 
 ## Documentation
 
-- [Quickstart](docs/quickstart.md): install, the first session, a working day
-- [Operations guide](docs/operations.md): console, task flow, Pi and models, dashboard, projects, upgrade and recovery
-- [Hub memory](docs/memory.md) and [agent-mem](https://github.com/STAIxBWLB/agent-mem)
-- [Security notes](docs/security.md): what the hub defends and what it does not
-- [Design spec](docs/specs/2026-09-19-agent-hub-design.md): how it is built and why
-- [Smoke checklist](docs/smoke.md): what has been verified against real agents
-- [Changelog](CHANGELOG.md), [Contributing](CONTRIBUTING.md)
+| Read | For |
+| --- | --- |
+| [Quickstart](docs/quickstart.md) | install, the first session, a working day, upgrade notes |
+| [Operations guide](docs/operations.md) | console, task flow, Pi and models, dashboard, projects, upgrade and recovery |
+| [Hub memory](docs/memory.md) | how memory is stored, shared and recalled |
+| [Security notes](docs/security.md) | what the hub defends and what it does not |
+| [Design spec](docs/specs/2026-09-19-agent-hub-design.md) | how it is built and why |
+| [Smoke checklist](docs/smoke.md) | what has been verified against real agents |
+| [Changelog](CHANGELOG.md), [Contributing](CONTRIBUTING.md) | releases and how to contribute |
 
-`AGENTS.md` and [`docs/agent-notes/`](docs/agent-notes/) hold the rules coding
-agents follow when they work on this repository.
+Coding agents that work on this repository follow [`AGENTS.md`](AGENTS.md) and
+[`docs/agent-notes/`](docs/agent-notes/).
 
 ## Origin
 
 The first idea came from [agent-bridge](https://github.com/raysonmeng/agent-bridge),
-which lets Claude Code and Codex talk to each other. agent-hub has since grown
-into a different system with its own goals and shares no code with it.
+which lets Claude Code and Codex talk to each other. agent-hub has since grown into a
+different system with its own goals and shares no code with it.
 
 ## License
 

package/THIRD_PARTY_NOTICES.md

@@ -17,3 +17,32 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+## Tabler Icons
+
+The inline icon sprite in `src/ui/index.html` (the dashboard's navigation, help, close, star, arrow and checking icons) contains the SVG
+path data of twelve icons from Tabler Icons (outline set, 24x24, stroke 2), copied unchanged from https://github.com/tabler/tabler-icons:
+`layout-kanban`, `building-store`, `activity`, `users`, `message`, `brain`, `settings`, `help`, `x`, `star`, `arrow-right` and
+`refresh`. No Tabler package is installed or bundled.
+
+MIT License
+
+Copyright (c) 2020-2026 Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/adding-an-ai-tool.md

@@ -10,7 +10,7 @@ Under **Adapter API 1** (issue #451), every tool is integrated as an `AdapterDef
 
 1. **One Definition per Kind**: Each tool is identified by a unique `kind` (e.g., `codex`, `kimi`, `agy`, `claude`, `jcode`, `pi`, `local`, `qwen`). Its capabilities, transport, launch argv, permission mappings, and recovery contracts are encapsulated in an `AdapterDefinition`.
 2. **Core Independence**: Core daemon logic (`src/hub/daemon.ts`), task management (`src/hub/tasks.ts`), and routing (`src/hub/routing.ts`) inspect definition fields (such as `transport`, `identity`, `attach`, `budget`), never raw vendor names.
-3. **Strict Conformance**: Every builtin adapter must run the conformance test kit (`test/conformance/`). Unsupported legs must provide explicit, documented reasons rather than silent test skips. (External adapter enrollment lands with A4.)
+3. **Strict Conformance**: Every builtin adapter must run the conformance test kit (`test/conformance/`). Unsupported legs must provide explicit, documented reasons rather than silent test skips. (A4 exports the same callable contracts for external package CI.)
 4. **Trust & Security Boundaries**:
    - **On-prem vs. Cloud**: `trust.onPrem` controls whether private/PII tasks may be routed to the agent. A cloud agent (`trust.onPrem: false`) never receives PII task text or memory entries.
    - **Path Protection**: Any workspace configuration directory owned by the agent (e.g., `.agents/`, `.codex/`) must be listed in `AGENT_CONFIG_SEGMENTS` (`src/hub/permission-mode.ts`) so agents cannot self-modify their own hooks or plugins.
@@ -24,7 +24,7 @@ agent-hub supports five transport architectures (`transport` in `AdapterDefiniti
 
 | Transport | Description | Best Suited For | Examples |
 | :--- | :--- | :--- | :--- |
-| **`acp`** | Agent Client Protocol over stdio JSON-RPC | Agents implementing the standard ACP specification | Kimi, Qwen |
+| **`acp`** | Agent Client Protocol over stdio JSON-RPC | Agents implementing the standard ACP specification | Kimi, Qwen, Jcode |
 | **`codex-appserver`** | Bidirectional JSON-RPC with proxy intercept and thread tracking | Tools with structured thread resume and proxy-injectable RPC | Codex |
 | **`claude-channel`** | MCP plugin running inside the host agent with WebSocket control link | Agents with native plugin systems that push notifications | Claude Code |
 | **`ws-pull`** | Workspace MCP plugin connecting to daemon WebSocket; pull-only message inbox | Agents with local plugin discovery and interactive TUIs | Google Antigravity (`agy`) |
@@ -65,9 +65,11 @@ Defines how the hub MCP server identity reaches the tool:
 
 #### `permission`
 Maps hub permission modes (`ask`, `ask-when-needed`, `never-ask`) to native flags or ACP mode IDs:
-* `grants`: Record mapping `PermissionMode` to native argument/mode string.
-* `unmanaged`: String explanation if native permissions are unmanaged by the hub.
-* `unmanagedForms`: Start forms where permissions remain unmanaged (e.g. `["tui"]`).
+* `grants`: the text that says what each hub mode does for this kind (`ahub permission` and the settings preview show it). It is a description, not the native flag: the native mode id or policy is applied by the adapter (an ACP mode id, Codex's `approvalPolicy`).
+* `genericAcp`: for a configured ACP kind, the validated `modes` (hub mode to ACP mode id) and `readOnly` id that the runtime and the instance ceiling both read.
+* `unmanaged`, `unmanagedNote`, `unmanagedStatusNote`: why the hub cannot manage native permissions, when it cannot.
+* `unmanagedForms`: start forms where permissions remain unmanaged (e.g. `["tui"]`).
+* `trackUnattended`: the daemon records whether a start was `--unattended` and refuses a second start with a different setting while one is in progress (Codex).
 
 #### `session`
 Controls session restoration, thread continuity, and crash recovery:
@@ -76,6 +78,18 @@ Controls session restoration, thread continuity, and crash recovery:
 * `resumeArgv(binding, fresh)`: Builds CLI arguments to resume a persisted session.
 * `transcriptPath(binding)`: Resolves local transcript file path for audit/usage tracking.
 
+#### `projection`
+Where the kind sits in the host's derived lists: `roleRank`, `startRank`, `helpRank` and `plannerEligible`. `KNOWN_PEERS`, `OPTIONAL_PEERS`, `START_MODE_PEERS`, `ROLE_ORDER`, `HELP_ORDER` and `PLANNER_PEERS` are derived from `ADAPTERS` and these ranks (`deriveAdapterLists`). The only hand-kept lists are the cross-release copies in `src/hub/peer-catalog.ts` (`KNOWN_PEERS`, `OPTIONAL_PEERS`) and `src/hub/start-mode.ts` (`START_MODE_PEERS`, for a dual-form kind): a new native kind is added there too, and `test/registry-guard.test.ts` fails until those copies equal the derived lists. A configured or external definition cannot set `projection`.
+
+#### `cli`
+The `ahub <kind>` surface: `command`, `startWords(form)`, and for a fixed builtin `entry` (the launcher and whether it needs lifecycle admission), `preview`, `usage` (help lines) and `launchConfigKeys`. `builtinCliEntries(definitions)` projects the entries; no configuration or module can register one.
+
+#### `instances` and `attach`
+`instances.mode` is `headless` (needs a headless `start.create` factory) or `external` (a channel instance started from the person's terminal). A kind with no `instances` policy (Jcode) takes no extra instance, and `validateInstances` refuses a declaration of one. `attach` holds the pull-only forms, external-hello admission and the refusal texts for a TUI that attaches without a driven peer.
+
+#### Peer capability members
+The runtime peer (`PeerAdapter`, `src/hub/peers.ts`) exposes optional members that the daemon reads instead of checking its class (#625 phase 6): `sessionGeneration` (native session identity: absent keeps the owner-token fallback, present but undefined is unknown and refuses bounded checks), `checkpointUsesSessionGeneration` (opt out of generation-fenced checkpoints, as Pi does), `permissionModeState` (the effective native approval state, or `unknown` / `unmanaged`) and `setPermissionMode(mode)` (resolves only after the native side acknowledges). Native safety proofs (Codex proxy and restoration, Claude launch generation) stay in the daemon.
+
 #### `budget`
 Defines quota and context window consumption readers:
 * `account`: Account identifier for quota grouping.
@@ -94,20 +108,94 @@ Grok declarations require explicit `--no-leader`, since native defaults can inhe
 
 ---
 
-## 5. Planned: External Adapter Modules (#451 A4)
+## 5. External Adapter Modules (#451 A4)
+
+A person can authorize a bundled adapter in an untracked
+`.agenthub/config.local.json`:
+
+```json
+{
+  "adapter_modules": [
+    { "path": ".agenthub/adapters/my-tool.mjs", "sha256": "<64 hex digits from the exact bundle>" }
+  ]
+}
+```
+
+The daemon imports the module at startup. Settings, reload, previews and ordinary
+CLI reads never import it. A changed declaration requires restart; it cannot be
+written through a hub tool or Settings. The CLI sees only the running daemon's
+bounded kind and display name. Tracked/shared/cloned configuration cannot enable
+code. A wrong hash, API mismatch, builtin collision, symlink component, path
+outside the project, nonregular/world-writable file, oversized file or unsupported
+module construct refuses loading without exposing source text in the error.
+
+Publish a single self-contained ESM JavaScript bundle. Bundle third-party
+implementation into that file; do not add runtime dependencies to the hub.
+Runtime imports may use Node/Bun builtins except `bun:ffi` and `bun:test`, plus
+`@staix/agent-hub/adapter`, bound to the running daemon's own SDK rather than
+project packages. `/conformance` is available to module CI, not runtime modules.
+Relative or other package imports, dynamic imports, require (including
+`import.meta.require`), eval and Function-based loading
+are refused. The scanner also refuses any `require`, `eval` or `Function` word token, including non-loading uses such as `o.require` or `instanceof Function`. String literal contents are not word tokens. The scan is conservative, not a sandbox. Authorized module code runs
+with daemon privileges; inspect the full bundle before recording its hash. Each import must settle within two seconds or that module is refused while startup continues. This deadline stops waiting; it does not cancel module code or undo its side effects.
+Dependencies must be ESM-only. The loader verifies the captured original bytes,
+rewrites only scanned SDK imports to host-owned file URLs, and imports that result
+rather than reopening a mutable source path after the hash check. A refused
+module appears in bounded status diagnostics while other adapters keep working.
+Its roster row stays inert; CLI config reads also retain inert unknown rows when
+trusted module declarations exist but daemon metadata is unavailable.
+
+The module exports `definition` with `api: ADAPTER_API`. Import the version,
+`AcpPeer`, `BasePeer` and definition/context types from
+`@staix/agent-hub/adapter`. The initial executable subset uses a headless ACP
+factory, its own kind/family, `optional: true`, `defaultOnRoster: false` and
+`trust: { onPrem: false, hubSandboxed: false }`. Preserve the host's factory
+options and instance id when constructing the transport. Supply a launch plan,
+start/identity/session/CLI/display metadata and only supported native mode
+mappings; no mapping means unmanaged. By default the host disables native
+hub-tool title auto-approval for external kinds. A cooperating module must preserve
+that factory option; approved module code runs with daemon privileges, so this is
+a host default rather than isolation from a module that overrides its options. The loader refuses fixed-builtin capabilities and unsupported
+fields rather than silently ignoring them. See `validateExternalDefinition` for
+the exact accepted subset.
+
+External kind instances are explicitly unsupported in A4. Follow-up board task
+#287 owns execution roots, CLI identity and recovery for them. Broadening the
+module transport beyond the existing headless ACP host port also needs a reviewed
+host contract (#625 phase 6); selecting a different native engine is not a generic extension.
+
+For example, bundle an ESM definition with its dependencies and record its digest:
 
-Support for loading adapter definitions from external modules outside the core repository is planned as board task #135. As decided in issue #451 (P3), external modules will be governed by strict trust rules:
+```bash
+bun build ./adapter.ts --target bun --format esm --external @staix/agent-hub/adapter --outfile .agenthub/adapters/my-tool.mjs
+shasum -a 256 .agenthub/adapters/my-tool.mjs
+```
 
-* **Machine-Local Only**: Loaded exclusively from local files specified in local configuration; never from repository tracking or network URLs.
-* **Content-Hash Pinning**: Explicit SHA-256 hash pinning to prevent unauthorized tampering.
-* **Person Authority**: Enabling external modules requires explicit human authorization.
-* **Conformance Requirement**: External modules must pass the conformance kit before admission.
+Enable its roster row only after loading it and exercising the applicable
+conformance contracts. Source and target recovery runtimes must advertise
+`external_adapter_modules`; old runtimes cannot preserve the verified catalog.
 
 ---
 
 ## 6. The Conformance Kit
 
-The conformance kit (`test/conformance/`) validates that an adapter satisfies hub invariants:
+The exported Bun kit (`@staix/agent-hub/conformance`) supplies callable transport
+registrations, `createFromDefinition`, `registerConformance`, explicit unsupported
+leg validation and immutable `fakePaths`. Importing it starts no fake transport;
+call a registration in your own Bun test file. The hub's `test/conformance/`
+wrappers run the same implementation against every applicable builtin.
+
+An external adapter test imports its definition and calls
+`registerConformance` with its real factory and a fake transport fixture. ACP
+adapters also call `registerAcpConformance({ definition, ... })`; unsupported native
+approval, mode or quota legs require concrete reasons, never silent skips. Other
+exports cover Codex, owned ACP, Pi, local and external-channel fixture contracts.
+Those exports do not grant an external runtime access to a builtin-only engine.
+The shipped fake assets live under `src/adapters/conformance/fakes`, so package CI needs
+no development-tree files. Native account/TUI probes remain separate from these
+synthetic protocol contracts.
+
+The kit validates that an adapter satisfies hub invariants:
 
 ```bash
 # Run the complete conformance suite
@@ -120,7 +208,7 @@ bun test test/conformance/agy.test.ts
 
 ### Invariants Verified by the Kit:
 1. **Enrollment & Coherence (`enrollment.test.ts`)**: Every definition in `ADAPTERS` and reviewer variant must be enrolled. A kind without kit coverage needs a reason in `UNSUPPORTED` (`test/conformance/enrollment.ts`), and an ACP kind that skips one of the shared `ACP_LEGS` needs a reason per leg in `UNSUPPORTED_LEGS`.
-2. **Delivery Occupancy**: Sending messages updates driven peer state to `busy` synchronously, delivering digests reliably.
+2. **Delivery Occupancy**: Sending messages updates driven peer state to `busy` synchronously, delivering digests reliably. A channel peer whose native hooks own occupancy (Claude) stays idle on insertion by design.
 3. **Recovery Metadata Hygiene**: No prompt text or credentials leaked into `recoveryMetadata`.
 4. **Watchdog Cancellation & Generation Fencing**: Expiry of the turn watchdog cancels prompts cleanly and generation fences prevent stale late answers from publishing.
 5. **Teardown & Cleanup**: When an adapter is stopped (`peer.stop()`), all owned child processes in the process group stop with it (the peer reaches offline).
@@ -132,7 +220,7 @@ bun test test/conformance/agy.test.ts
 When adding or updating an adapter, verify each item before opening a PR:
 
 - [ ] **T0 Receipt Recorded**: Document native CLI version, observed hook payloads, and protocol outputs in `docs/verification/YYYY-MM-DD-<kind>-t0.md`.
-- [ ] **Registered in ADAPTERS**: Added to `src/adapters/registry.ts` with explicit `displayName`, `family`, `transport`, and `trust`.
+- [ ] **Registered in ADAPTERS**: the definition is declared under `src/adapters/definitions/` (or its own directory) with explicit `displayName`, `family`, `transport`, `trust` and `projection`, and listed in `ADAPTERS` (`src/adapters/registry.ts`). The peer lists are derived from it. The hand-kept cross-release copies in `src/hub/peer-catalog.ts` and `src/hub/start-mode.ts` and the pinned tests listed in `docs/agent-notes/adapters.md` change with it, and the PR names them as expected test changes.
 - [ ] **Config Path Protection**: Agent configuration directories added to `AGENT_CONFIG_SEGMENTS` in `src/hub/permission-mode.ts`.
 - [ ] **PII Safety Verified**: Cloud models have `trust.onPrem: false`; verify PII markers refuse routing to this peer.
 - [ ] **Process Group Teardown**: Daemon-spawned processes use process groups and exit cleanly on stop.

package/docs/agent-notes/README.md

@@ -20,3 +20,18 @@ The #451 predicate and identity-lookup moves exposed unbound names in a VM fixtu
 that extracts daemon closures. Reconnecting imported helpers and deterministic
 identity ports preserved the fixture's existing assertions; changing the asserted
 behavior would have hidden the missing dependency.
+
+Background moved out of the area notes for 0.12.45:
+
+- Instance execution git budget (#225, daemon.md): `resolveInstanceExecutionCwd` runs synchronously on the daemon's event loop (an extra-instance start, `turn_revert`) with up to four git calls, measured at about 15 ms on a warm local repository. One shared 5 s allowance holds the loop at most 5 s, not 4 x 5 s. It stays synchronous because the CLI and recovery callers are; an async twin for the two daemon call sites is the upgrade if a typical resolution ever costs more than a few ms.
+- Claude steer version gate (#493, #221, daemon.md): mid-turn consumption of a steered important message was proven only on Claude Code 2.1.302 (`docs/verification/2026-10-18-493-claude-busy-channel.md`); on an older client a dropped mid-turn notification stays `accepted` until a person resolves it. The hello does not carry the client version, and the oldest working version is unknown, so a gate would be a guess that could disable a working path.
+- Planner reservation and done gates (tasks.md): in #378 a same-value planner write laundered a person's reservation; in #382 advise recorded overlapping dones, and an owner could neither relink a PR nor be stopped from carrying a head to a new PR.
+- Process-tree stops (adapters.md): three review rounds of #113 found snapshot gaps while the tree ran (groups of its own, an unreadable first read, a child started during the grace period).
+- Local worker (local-worker.md): a bare `private/` deny entry once denied all of `/private/var`; `existsSync` made a dangling link look like a new file, so a write landed at its target.
+- Suite watchdog (tests.md): macOS CI hit `AHUB_CHECK_HANG_S` while tests still passed (#378, #593).
+
+Background moved out of the area notes for 0.13.0:
+
+- Jcode MCP entry (#685, adapters.md): jcode gives an MCP entry's own env precedence over the process env (probed on 0.99.0), so a peer id in the shared `.jcode/mcp.json` entry would make every extra instance act as `jcode`.
+- Bulk queue discard (#713, bus.md): a queued row with no journal record of its own carries the journal's global revision, which every discard moves, so a revision read once at the start goes stale after the first discard.
+- Usage roll-up (#683 U2, budget.md): a pass cap smaller than one log line once hung the fold.