@staix/agent-hub 0.12.43 → 0.12.45

package/CHANGELOG.md

@@ -2,9 +2,44 @@
 
 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
-
-- Incoming HEAD moves during open turns no longer produce false concurrent-edit warnings or attributed undo paths; bounded per-worktree reflog evidence distinguishes them from peer commits and sequencer replay changes, which stay attributed unless ambiguous. Rebase/pull --rebase start checkout is incoming; uncommitted edits carried through autostash or checkout -m are never excluded. Real concurrent change sets publish at most one notice per affected task; snapshot Git work shares a 250 ms burst budget and records unknown boundaries on exhaustion. Status reuses a checkout-branch probe only within the current synchronous burst. Pi terminal reconciliation uses the bounded existing owner monitor instead of spawning `ps` on every read; effect admission and teardown still verify fresh process identity (#576).
+## 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).
+
+- Add project-local config-only ACP adapters: optional headless kinds stay off roster by default, with pinned native identity, strict resume identity, owned-group admission and optional mapped or read-only native modes. Grok live verification remains pending; the generic path does not by itself verify Grok support (#451, #486). Adapter role defaults cannot appoint a conductor; explicit project role policy remains available. Unknown fields in `peers.<id>` now refuse daemon startup as well as strict reload.
+- `ahub permission` and `ahub settings` reach the running hub even when `.agenthub/config.local.json` does not parse, and `ahub settings undo` asks for the peer-id confirmation of a configured kind's roster undo (#638 follow-up).
+- agy no longer shows Claude's context reading, session or transcript usage as its own: Claude state files are read only for Claude peers, and the shared file-name helper refuses any other id (#624). An upgrade no longer refuses a planned fresh start of a `codex-<name>` instance, and native observation uses the sending peer's own roles.
+- Owner turns that write nothing are flagged: two completed `implement` or `bulk_edit` owner turns in a row with no recorded writes or task-tool effects raise a planner notice, and a done report with no writes since acceptance says so in its review request (`task_sweep.no_writes_turns`, default 2, 0 disables). Evidence that cannot be proven, such as private turns, work under `.worktrees` or a recorded branch, PR or head, stays unknown and never counts as empty (#498).
+- In the agy TUI the hub tools can be missing on the first turn: the launcher says so and the `AGENTS.md` block tells agents to use them from the next turn instead of reporting the hub unavailable; run `ahub init` to refresh the block (#607).
+- An invalid `kimi_cmd` releases the Kimi TUI admission instead of holding it (#549).
+- Codex shows a fixed `unidentified-cancellation` status notice in `ahub status`, the console and the dashboard while its offline latch holds; verified reattachment or TUI detach clears it (#451).
+- The recovery lease logs its release retry once per failure streak instead of once a second (#479).
+- Add "Adding an AI Tool" guide (`docs/adding-an-ai-tool.md`) documenting Adapter API 1 definitions, transport selection, and the conformance test kit (#451 A5).
+- Adapter declarations now refuse ordinary agy extra instances at config load; they previously loaded as inert pull-only extras. Fresh-reviewer metadata remains unavailable (#451, #625).
+- Qwen context occupancy is now unknown until a native source is verified; it no longer inherits Kimi's usage parser (#451, #625).
+- When the hub itself starts headless Kimi or Qwen it also opens `ahub watch <peer>` through the terminal provider, a fixed command opened at most once per 30 s; with no provider or a failing one the start still succeeds and the watch command is reported (#286 AC10).
 
 ## 0.12.43
 

package/README.md

@@ -5,7 +5,7 @@ Codex, Kimi Code, Pi and a hub-owned local worker (Qwen Code, Jcode and Antigrav
 optional) share a message bus and a task board per project and one memory on the
 machine, each attached through its own native interface.
 
-Status: 0.12.43, control protocol 16. Bun + TypeScript, one loopback daemon per
+Status: 0.12.45, control protocol 16. Bun + TypeScript, one loopback daemon per
 project. Site: [agent-hub.staix.net](https://agent-hub.staix.net).
 
 ## What it does today
@@ -88,14 +88,14 @@ keeps headless startup. On 0.12.39 the TUI launcher stopped after the first hub
 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).
+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). Since 0.12.45 the dashboard has a sidebar or tabs, view keys `1`-`7`, a task side sheet, a Plan sheet for the board forms and loading, empty and disconnected states (#469); a person can add a bundled ACP adapter module, pinned by `sha256` in untracked `.agenthub/config.local.json` and imported only by the daemon at startup, and module CI gets the `@staix/agent-hub/conformance` kit (#451); reviews take structured findings, and in SDLC enforce an open Important finding or a changed file outside the plan refuses approval until fixed, amended or accepted by the person with `ahub sdlc accept-departure` (#481); and `ahub roster remove` deletes the roster key of an instance no longer declared (#225).
 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.43.md) for the live legs
+See [release verification](docs/verification/2026-10-22-0.12.45.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

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

@@ -0,0 +1,228 @@
+# Adding an AI Tool (Adapter Guide)
+
+This guide documents how to add an AI coding agent or tool to **agent-hub** as an adapter. agent-hub treats every agent as a peer in a shared project directory, coordinating through messages, task board assignments, shared memory, and lifecycle gates.
+
+Under **Adapter API 1** (issue #451), every tool is integrated as an `AdapterDefinition`. The core daemon, task board, and CLI interact only through this typed contract, without hard-coded vendor name comparisons.
+
+---
+
+## 1. Architecture & Principles
+
+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. (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.
+   - **Process Isolation**: Spawns must run in their own process groups and are stopped as a whole group by the hub.
+
+---
+
+## 2. Choosing a Transport
+
+agent-hub supports five transport architectures (`transport` in `AdapterDefinition`):
+
+| Transport | Description | Best Suited For | Examples |
+| :--- | :--- | :--- | :--- |
+| **`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`) |
+| **`hub-native`** | Direct in-process or local sandbox execution | Custom on-prem models, sandboxed local worker, or Pi RPC bridge | `local`, `pi` |
+
+### Generic ACP vs. Dedicated Adapter
+
+* **Generic ACP (Config-only)**: A3 supports project-local standard ACP (stdio JSON-RPC) definitions without extending the builtin registry. Native support still requires a verified foreground contract and isolated T0 receipt.
+* **Dedicated Adapter**: Current builtin mechanism where each tool exports an `AdapterDefinition` under `src/adapters/` with its transport, hooks, and launch plans.
+
+---
+
+## 3. AdapterDefinition Fields Reference
+
+An adapter exports an object conforming to `AdapterDefinition` in `src/adapters/registry-types.ts`. Read that type as the source of truth: most blocks are declared inline there, so there are no separate `Adapter*Definition` types to import, and some members are required. Its top-level fields are:
+
+- Required: `api` (always `1`), `kind`, `displayName`, `family`, `transport`, `roles`, `trust` (`onPrem`, `hubSandboxed`), `start`, `identity` (`mcp`), `permission`, `session`, `turnEnd`, `cli`, `display`.
+- Optional: `optional`, `defaultOnRoster`, `enabledSwitchStartOnly`, `instances`, `attach`, `reporting`, `routing`, `budget`, `configuration`, `capabilities`, `hooks`, `reviewerVariant`, `reviewer`.
+- Registry load runs `assertDefinitionCoherence` (`src/adapters/registry.ts`) on every definition and reviewer variant, so an incoherent combination fails at load, not at run time.
+
+### Key Sub-Objects
+
+#### `start`
+Defines how the agent process is started and commanded:
+* `forms`: `["tui"]`, `["headless"]`, or `["tui", "headless"]`.
+* `defaultForm`: The default startup mode.
+* `launch(ctx)`: Generates the `LaunchPlan` (command, argv, environment variables, launch metadata).
+* `create(ctx)`: Factory constructing the `PeerAdapter` instance for driven daemon peers.
+* `conductorStartable`: Boolean indicating if `ahub up` or conductor can spawn this peer automatically.
+* `ownedFlags`: CLI flags owned by this tool's launcher.
+
+#### `identity`
+Defines how the hub MCP server identity reaches the tool:
+* `"acp-session"`: Sent in `session/new` `mcpServers` parameter.
+* `"project-file"`: Written into workspace plugin or config files (e.g. `.agents/plugins/agent-hub/mcp_config.json`).
+* `"channel-plugin"`: Provided by an installed MCP bundle.
+* `"env"`: Passed via environment variables.
+
+#### `permission`
+Maps hub permission modes (`ask`, `ask-when-needed`, `never-ask`) to native flags or ACP mode IDs:
+* `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:
+* `idField`: `"sessionId"` or `"threadId"`.
+* `currentId(peer)`: Extracts the active session or thread ID from a running adapter.
+* `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.
+* `reader`: `QuotaReader` extracting usage windows from native status outputs.
+* `context`: `ContextReader` measuring token occupancy against window limits.
+
+---
+
+## 4. Config-Only Generic ACP Adapters (#451 A3)
+
+Declare `adapters.<kind>` only in a Git-confirmed untracked `.agenthub/config.local.json`. The declaration is wholly machine-local authority and cannot override builtin kinds or select executable modules. Its `transport` is `acp`; it names a command, optional argv, display name and default roles, with optional native identity, permission-mode mappings and read-only mode. Adapter defaults cannot appoint the conductor. A project captures its catalog at startup, so declaration changes require restart.
+
+Configured kinds are headless and off roster by default. Before a start can succeed, the native initialize name/version must match the configured pin and the spawned process group must be positively owned. Resume also requires an exact session/load echo. Missing native permission mappings mean unmanaged policy; missing usage/context sources remain exempt/unknown. Titles do not auto-approve tools, and read-only mode requires both native acknowledgement and host mutation fences.
+
+Grok declarations require explicit `--no-leader`, since native defaults can inherit ambient `[cli] use_leader`. Grok 1.0.62 remains unsupported: its isolated probe lacked initialize identity and refused session creation. The [T0 receipt](verification/2026-10-21-grok-config-acp-t0.md) records the remaining evidence. The full A3 schema and proof boundary are in the [spec amendment](specs/2026-09-19-agent-hub-design.md#amendment-config-only-acp-adapters-a3-451-486).
+
+---
+
+## 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:
+
+```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
+```
+
+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 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
+bun test test/conformance
+
+# Run conformance for a specific kind
+bun test test/conformance/acp.test.ts
+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. 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).
+
+---
+
+## 7. Review & Verification Checklist
+
+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**: 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.
+- [ ] **Conformance Kit Passes**: `bun test test/conformance` passes with zero regressions and no silent skips.
+- [ ] **Documentation Freshness**: Run `node scripts/check-docs.mjs` and update verified stamps in `docs/verified.json`.

package/docs/agent-notes/README.md

@@ -15,3 +15,17 @@ Background behind some of the rules, moved from the top-level README on 2026-10-
   `docs/verification/2026-10-03-0.12.6.md`); minimal reproductions did not hang, so
   the full trigger is not pinned down. On Bun 1.4.2 the next test still starts there
   (#121, checked directly); the spin was not reproduced on demand on either version.
+
+The #451 predicate and identity-lookup moves exposed unbound names in a VM fixture
+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).