@staix/agent-hub 0.27.0 → 0.29.0

package/docs/design/adapters.md

@@ -0,0 +1,76 @@
+---
+id: adapters
+type: module
+title: Native Adapters and Spawned Agents
+status: draft
+parent: agent-hub-architecture
+paths:
+  - src/adapters/**
+  - src/pi/**
+  - src/hub/peers.ts
+  - src/hub/permission-mode.ts
+  - src/hub/tool-refusal.ts
+  - src/hub/child-process.ts
+  - src/hub/lifecycle.ts
+  - src/hub/start-mode.ts
+  - src/hub/terminal-open.ts
+  - src/memory/capture.ts
+  - src/hub/native-hook-launch.ts
+  - src/hub/peer-catalog.ts
+  - src/cli/configured-acp-entry.ts
+  - src/cli/agy-mcp.ts
+  - src/cli/kimi-mcp.ts
+  - src/cli/jcode-mcp.ts
+  - scripts/benchmarks/teardown.ts
+  - src/hub/action-enforce.ts
+  - src/hub/read-only-shell.ts
+  - src/hub/read-only-shell-proof.ts
+  - src/hub/operational-authority.ts
+  - src/hub/permission-payload.ts
+  - src/hub/claude-shell-wrapper.ts
+  - src/hub/task-shell-command.ts
+  - src/hub/task-shell-default.ts
+  - src/hub/task-shell-proof.ts
+  - src/hub/task-shell-sandbox.ts
+  - src/cli/claude-shell-wrapper.ts
+covers: [adapters]
+tags: [agent-hub, dogfood]
+---
+
+# Native Adapters and Spawned Agents
+
+This module records how vendor protocols meet the hub. For operational rules see the [adapter](../agent-notes/adapters.md), [daemon](../agent-notes/daemon.md), [local-worker](../agent-notes/local-worker.md), and [model](../agent-notes/models.md) notes, and the [new-adapter guide](../adding-an-ai-tool.md).
+
+## Registry and host boundary
+
+Each peer kind is described by an `AdapterDefinition` in the registry. Per-kind launch, protocol, and permission details stay with that definition; the daemon consumes registry fields rather than spreading vendor-name branches through policy. `PeerAdapter` is the runtime interface for delivery, turn state, permission acknowledgement, lifecycle, and optional host evidence. The host owns identity, admission, audits, task role checks, and effects; an adapter reports facts but cannot certify its own authority. This keeps a new transport from changing common policy accidentally ([#451](https://github.com/STAIxBWLB/agent-hub/issues/451), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625)).
+
+Optional ports have explicit meaning: absent keeps the generic path, while present-but-unknown refuses where the port gates a safety decision. Native evidence stays with the party that can observe it: the daemon retains host launch and socket-generation records, while a protocol adapter retains in-protocol evidence such as a thread's native sandbox or approval state. This prevents a configured adapter from asserting proof it does not possess ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625)).
+
+Adapters translate different interaction surfaces without changing the peer's task identity. Claude's plugin channel connects through MCP and the hub control service; Codex is proxied through app-server; ACP peers share an ACP transport; Pi uses its extension bridge. Kimi defaults to a pull-only TUI, with headless ACP as a separate selected form under the same peer id. The TUI does not inherit headless push, session, or recovery behavior. Keeping forms distinct lets the hub preserve the native user interaction model while enforcing one role and delivery policy ([#316](https://github.com/STAIxBWLB/agent-hub/issues/316), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625)).
+
+## Permissions, execution, and process ownership
+
+Permission modes control whether native actions prompt; they do not widen a sandbox or path grant. The local worker's file tools use path guards, and its command tools run through the host's OS sandbox. Vendor-native tools use their vendor/runtime permission and isolation boundaries; the hub does not claim to confine every ACP or TUI tool. This distinction prevents an approval-mode setting from being mistaken for filesystem or network confinement ([#242](https://github.com/STAIxBWLB/agent-hub/issues/242), [#39](https://github.com/STAIxBWLB/agent-hub/issues/39), [#270](https://github.com/STAIxBWLB/agent-hub/issues/270)).
+
+When the hub starts a child, the host constructs its environment, binds its launch and generation, and owns its process-group lifecycle. Stop and recovery require current evidence for the process actually started; a PID, adapter label, successful start call, or stale session record is not enough. This keeps teardown from signaling a person's unrelated process and prevents a late native callback from acquiring a replaced session's authority ([#115](https://github.com/STAIxBWLB/agent-hub/issues/115), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625)).
+
+Permission decisions are bound to the authenticated caller and current session. A hub CLI call inside an agent session acts as that peer, not as the person; role and task checks still apply at each tool boundary. Permission modes are person-controlled, and a conductor role does not grant them. This avoids turning a received message into user consent ([#193](https://github.com/STAIxBWLB/agent-hub/issues/193), [#242](https://github.com/STAIxBWLB/agent-hub/issues/242)).
+
+## Model, account, and memory boundaries
+
+Subscription-based native CLIs keep their own account authentication; those credentials are not pooled through the hub. Hub-owned inference, including internal summaries and local-worker model calls, uses the in-process model route and OmniRoute provider boundary. Prompt text may inform configured routing, but it cannot grant credential access or replace host routing policy. This separates native subscription identity from hub service credentials ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+The PII screen is distinct from ordinary optional inference. It may use an on-device model; a gateway screen requires positive on-campus admission and `onCampusOnly`. If no allowed path returns a closed `clear` or PII verdict before the deadline, the result is unknown and handled as private. This keeps network and model uncertainty from becoming a disclosure ([#198](https://github.com/STAIxBWLB/agent-hub/issues/198)).
+
+Runtime memory capture and recall use the in-process `@staix/agent-mem` package, screened and invoked by host integration. claude-mem is off by default and import-only; there is no worker HTTP or model-summary path in the runtime. This avoids a parallel capture route with different privacy checks ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752), [agent-mem#13](https://github.com/STAIxBWLB/agent-mem/issues/13)).
+
+## Compatibility and external modules
+
+Native CLI compatibility is centralized in `compat.ts`. Each gated operation asks that policy for a verified, in-contract, person-trusted, or refused result; person trust for one exact version does not skip a separate isolation or runtime proof. This lets upstream versions change without turning an untested protocol assumption into support ([#691](https://github.com/STAIxBWLB/agent-hub/issues/691)).
+
+External adapter modules are an explicit, person-owned, machine-local opt-in. The daemon verifies and pins the captured bundle at startup, then admits only the bounded headless ACP instance contract through host-managed launch and current-owner checks. Module code runs in the daemon trust domain; pinning is integrity evidence, not a sandbox. Modules cannot supply native reviewer engines, proof ports, permission callbacks, provider selectors, or arbitrary recovery authority. This ceiling limits what imported code can claim and prevents live reload from replacing the executable catalog ([#754](https://github.com/STAIxBWLB/agent-hub/issues/754)).
+
+## Evidence boundary
+
+Compatibility probes and fake transports verify source contracts, not an account login, live model turn, native permission prompt, or operating-system isolation. Those receipts remain separate because protocol inventory alone cannot prove runtime behavior ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#754](https://github.com/STAIxBWLB/agent-hub/issues/754)).

package/docs/design/agent-hub-architecture.md

@@ -0,0 +1,67 @@
+---
+id: agent-hub-architecture
+type: architecture
+title: Agent Hub Architecture
+status: draft
+parent: agent-hub
+paths:
+  - src/hub/daemon.ts
+  - src/hub/peers.ts
+  - src/hub/envelope.ts
+  - src/hub/tasks.ts
+  - src/hub/board.ts
+  - src/hub/routing.ts
+  - src/hub/bus.ts
+  - src/hub/delivery-journal.ts
+  - src/hub/hub-tools.ts
+  - src/hub/recovery-store.ts
+  - src/hub/recovery-continuity.ts
+  - src/adapters/registry.ts
+  - src/adapters/registry-types.ts
+  - src/omniroute/client.ts
+  - src/models/route/runtime.ts
+  - src/memory/client.ts
+  - src/local/sandbox.ts
+covers: [architecture]
+tags: [agent-hub, dogfood]
+---
+
+# Agent Hub Architecture
+
+The [design ledger](../specs/2026-09-19-agent-hub-design.md) records history; current operational rules live in the [AGENTS.md area notes](../../AGENTS.md#area-notes), including the [task](../agent-notes/tasks.md), [bus](../agent-notes/bus.md), [adapter](../agent-notes/adapters.md), [daemon](../agent-notes/daemon.md), [model](../agent-notes/models.md), and [local-worker](../agent-notes/local-worker.md) notes.
+
+## Runtime and peer boundary
+
+`src/hub/daemon.ts` is the project runtime's composition root. It owns the local control service, peer registry, `Bus`, `Tasks`, configuration, policy admission, and recovery coordination. A project has one local daemon and task board; its peers communicate through that daemon. The boundary keeps transport code from becoming a second source of role or recovery authority ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#900](https://github.com/STAIxBWLB/agent-hub/issues/900)).
+
+`PeerAdapter` in [peers.ts](../../src/hub/peers.ts) is the shared native-runtime interface. Fixed adapters translate host lifecycle, messages, permissions, and delivery receipts into it; daemon-owned policy decides what those facts permit. Claude's plugin channel uses MCP over stdio and the authenticated control connection, Codex uses the app-server proxy, and Kimi supports a pull-only TUI by default or explicitly selected headless ACP mode. Keeping protocol translation outside task policy prevents vendor-specific branches there ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#316](https://github.com/STAIxBWLB/agent-hub/issues/316)).
+
+External adapter modules are opt-in, pinned at startup, and limited to the accepted headless ACP contract; a module does not gain a generic native lifecycle or sandbox authority. That limit exists because imported code executes in the daemon's trust domain, so source pinning and an explicit capability ceiling are necessary ([#754](https://github.com/STAIxBWLB/agent-hub/issues/754)).
+
+The control WebSocket binds to loopback, requires a per-run token and rejects browser-origin requests. That token is not an OS security boundary against a same-user process that can read it. The agent-session identity path classifies CLI calls as the acting peer rather than the person, so received text cannot grant the person's authority. This keeps caller identity honest without claiming a hostile-process boundary ([#193](https://github.com/STAIxBWLB/agent-hub/issues/193)).
+
+Authority is role-scoped: the person retains decisions requiring judgment or consent; one configured conductor may perform audited operations within its project; ordinary peers receive role- and task-bound operations. Release consent remains person-originated: the person may record it, or the conductor may record it only on the person's explicit instruction in that session. That provenance is cooperative, not daemon-verifiable; model text, tasks, reviews, files, and peer relays do not count. This prevents task content from silently becoming authorization ([#812](https://github.com/STAIxBWLB/agent-hub/issues/812), [#481](https://github.com/STAIxBWLB/agent-hub/issues/481), [#787](https://github.com/STAIxBWLB/agent-hub/issues/787), [#1063](https://github.com/STAIxBWLB/agent-hub/issues/1063)).
+
+Native tools keep their vendor permission and execution boundaries. The local worker applies path and permission checks to its tools, and runs command execution through a host-supported sandbox; the hub does not sandbox vendor-native tools or claim all ACP commands are isolated. This avoids confusing a hub permission mode with execution confinement ([#39](https://github.com/STAIxBWLB/agent-hub/issues/39), [#270](https://github.com/STAIxBWLB/agent-hub/issues/270)).
+
+## Board, assignment, and delivery
+
+`Tasks` is the task state machine and policy boundary; `Board` is its SQLite persistence. Proposals, assignments, acceptance, completion, and review flow through `Tasks`, which checks roles, state, privacy, and revisions before writes. Pure candidate selection keeps route explanations aligned with actual assignment. This prevents adapters or CLIs bypassing invariants with direct board writes ([#424](https://github.com/STAIxBWLB/agent-hub/issues/424), [#481](https://github.com/STAIxBWLB/agent-hub/issues/481)).
+
+The message bus is separate from task state. `Bus` frames and routes envelopes; `DeliveryJournal` records transport attempts, acknowledgements, and uncertain outcomes. A delivery receipt does not mean its task was accepted, completed, or approved. Uncertain sends remain inspectable rather than silently replayed, and an explicit inbox pull records returned messages. This prevents transport retry from becoming a task transition ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37), [#493](https://github.com/STAIxBWLB/agent-hub/issues/493)).
+
+Encrypted rooms are an optional message transport between project hubs. They do not federate task boards, roles, approvals, or memory; each receiving project makes its own local admission decision. This prevents a remote room membership from becoming local authority ([#446](https://github.com/STAIxBWLB/agent-hub/issues/446)).
+
+## Models and memory
+
+Peer selection, hub-owned model routing, and provider access are distinct layers. Task routing chooses a peer; the in-process route selects a model for hub-owned inference; OmniRoute owns provider keys, provider fallback, and usage. Native CLIs retain their own account and provider configuration; subscription OAuth credentials are not pooled through the gateway. The former Switchyard sidecar is retired; routing now runs in process. This keeps provider credentials and fallback policy in one gateway while avoiding a second routing service ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+The hub's portable memory storage, sync, indexing, and project helpers come from the pinned first-party `@staix/agent-mem` package. `src/memory/` and `Tasks` provide hub-specific capture, recall, privacy screening, task briefs, and shared notes. Runtime memory is in-process: there is no claude-mem worker HTTP client or model summarizer. claude-mem is an off-by-default, import-only source. This removes a second capture path while keeping caller authority and task privacy in the hub ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752), [agent-mem#13](https://github.com/STAIxBWLB/agent-mem/issues/13)).
+
+## Privacy and recovery
+
+Privacy decisions are made at hub boundaries, not delegated to model routing. A private task or turn is represented by a private envelope and a restricted public view; task text is screened before it enters memory, shared notices, or model calls. The PII screen can run on-device; its gateway path requires positive campus admission, so an unknown network result is not treated as safe. This makes each downstream observer consume the same host decision rather than infer privacy from a label or vendor ([#198](https://github.com/STAIxBWLB/agent-hub/issues/198), [#752](https://github.com/STAIxBWLB/agent-hub/issues/752)).
+
+Recovery is a coordinated daemon operation over separately persisted board, delivery, and native-session evidence. A restart or upgrade can continue only with compatible feature evidence from the verified target and host-held proofs that still match the project and actor. Adapters report native evidence; they do not certify their own recovery authority. This avoids treating a stale status file or an unverified receipt as proof that a native process is safe to resume ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#900](https://github.com/STAIxBWLB/agent-hub/issues/900)).
+
+The architecture does not claim that a fixture proves a real provider account, native session, campus network, or operating-system sandbox. Those are distinct runtime evidence and remain separate from source-level and automated checks ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#754](https://github.com/STAIxBWLB/agent-hub/issues/754)).

package/docs/design/agent-hub.md

@@ -0,0 +1,52 @@
+---
+id: agent-hub
+type: goal
+title: Agent Hub Product Goal
+status: draft
+depends-on: []
+references: [agent-hub-architecture]
+implements: []
+covers: [product-goal]
+tags: [agent-hub, dogfood]
+paths:
+  - README.md
+  - package.json
+---
+
+# Agent Hub Product Goal
+
+agent-hub coordinates native coding agents and hub-owned workers as peers in a project. It gives the person one visible record of work, messages, review and intervention while preserving each tool's native interaction and account boundary. The product reduces coordination loss without treating an agent's assertion as authority or proof.
+
+This draft distills the Context, Decisions and Risks in the [historical design ledger](../specs/2026-09-19-agent-hub-design.md). The [[agent-hub-architecture]] spec describes the current system boundaries. Agent-facing procedures remain in [AGENTS.md and its area notes](../../AGENTS.md#area-notes); the ledger retains superseded decisions and their history.
+
+## Scope
+
+The core loop is to propose and assign work, exchange addressed messages while peers may be busy or offline, preserve delivery uncertainty, gather implementation and review evidence, and return decisions to the person. CLI, console, dashboard and native tools expose the same project authority. Multiple projects can run their own hubs; opt-in messages between hubs do not create a shared board or approval domain ([#19](https://github.com/STAIxBWLB/agent-hub/issues/19), [#446](https://github.com/STAIxBWLB/agent-hub/issues/446)).
+
+The hub also owns a local worker and optional model calls for its own inference. It does not replace every native agent with that loop, pool subscription credentials, or make native behavior identical across vendors. Native adapters preserve those differences behind explicit contracts ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+## Product decisions
+
+| Current rule | Reason and deciding issue |
+| --- | --- |
+| The issue is the change spec, the board is task authority, and GitHub is authority for PRs, checks and tags. | Separate records prevent a chat claim or stale local view from becoming lifecycle proof ([#481](https://github.com/STAIxBWLB/agent-hub/issues/481)). |
+| Peers use native adapters with host-owned admission and lifecycle boundaries. | New tools can participate without moving privileged policy into vendor-specific transports ([#451](https://github.com/STAIxBWLB/agent-hub/issues/451), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625)). |
+| Messages have durable delivery evidence, and uncertain attempts are distinct from task completion. | A restart, failed notification or retry must not silently repeat work or approve a task ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37), [#1079](https://github.com/STAIxBWLB/agent-hub/issues/1079)). |
+| Hub-owned traffic uses in-process model routes and OmniRoute; native subscription traffic keeps its native authentication. | This separates peer policy, per-call model selection and provider credentials without a second routing sidecar ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)). |
+| Host policy screens private task and turn text before shared projection, memory or model use, with positive campus admission where PII-sensitive inference requires it. | A missing network fact or a model-selected destination is not privacy authorization ([#198](https://github.com/STAIxBWLB/agent-hub/issues/198), [#230](https://github.com/STAIxBWLB/agent-hub/issues/230)). |
+| Portable memory comes from exact-pinned first-party amem; the hub keeps caller and privacy policy. Legacy claude-mem is import-only. | One storage core avoids competing memory implementations and dependence on an external worker for runtime recall and capture ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752)). |
+| Code review, automated checks, hosted CI and native/live verification remain distinct evidence. | A code-only reviewer or a passing fixture cannot certify a real account, sandbox or provider interaction ([#852](https://github.com/STAIxBWLB/agent-hub/issues/852)). |
+| Ordinary peer, configured conductor and person authority are different; release consent originates in the person's explicit decision. | Model output and relayed peer messages cannot grant privileged operational or release authority ([#812](https://github.com/STAIxBWLB/agent-hub/issues/812), [#1063](https://github.com/STAIxBWLB/agent-hub/issues/1063)). |
+
+## Risks and limits
+
+- Native protocols, flags and permission surfaces change independently. Adapter isolation and version-scoped evidence reduce the impact; they do not establish universal enforcement or support for an unverified version ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#888](https://github.com/STAIxBWLB/agent-hub/issues/888)).
+- A transport can fail after effects occur. Durable uncertainty, recipient inspection and bounded request-key replay reduce duplicate effects without claiming durable exactly-once execution across restarts ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37), [#1078](https://github.com/STAIxBWLB/agent-hub/issues/1078)).
+- Untrusted peer or room text can request actions or carry private data. Framing, host authority, path/permission boundaries and privacy screening constrain that input; room membership itself confers no local privileges ([#446](https://github.com/STAIxBWLB/agent-hub/issues/446)).
+- Memory and model infrastructure can be unavailable or stale. Optional recall and inference are separate from the authoritative message/task records, so their output or failure does not become task evidence ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752), [#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+## Success and evidence
+
+Product evidence separates source/fixture coverage from installed-hub and native use. The [dogfood scorecard](../dogfood.md) records which features actually run here and the metric that demonstrates them; unverified use stays unverified ([#687](https://github.com/STAIxBWLB/agent-hub/issues/687)).
+
+The design-spec pilot is bounded to this goal, the architecture and the bus, task-board and adapters modules. Its four-week report targets at least 70% of PRs touching pilot paths also updating the owning spec, zero schema errors on main and zero stale documents after release review/restamping. Notice noise and contradictions are recorded before recommending broader coverage or require mode. These are pilot targets, not results established by this draft ([#1064](https://github.com/STAIxBWLB/agent-hub/issues/1064)).

package/docs/design/bus.md

@@ -0,0 +1,48 @@
+---
+id: bus
+type: module
+title: Message Bus and Delivery
+status: draft
+parent: agent-hub-architecture
+paths:
+  - src/hub/bus.ts
+  - src/hub/envelope.ts
+  - src/hub/limits.ts
+  - src/hub/delivery-journal.ts
+  - src/hub/delivery-superseded.ts
+  - src/hub/deferred-hub.ts
+  - src/cli/reset.ts
+  - src/hub/inference.ts
+covers: [bus]
+tags: [agent-hub, dogfood]
+---
+
+# Message Bus and Delivery
+
+The bus carries bounded messages among peers in one project. Its operational contracts are in the [bus note](../agent-notes/bus.md); this spec records the design reasons behind them.
+
+## Message contract
+
+An envelope binds a sender, kind, priority, trace and hop count to a body and optional recipients, references, and privacy marker. An omitted recipient list means broadcast, while a reply inherits its addressee; malformed recipient input is refused rather than changed into a broadcast. This prevents a typo in a directed message from widening its audience ([#963](https://github.com/STAIxBWLB/agent-hub/issues/963)).
+
+Replies keep the highest hop from the delivery they answer, including when the peer received a condensed digest. The hop cap therefore cannot be reset through a summary or relay ([#546](https://github.com/STAIxBWLB/agent-hub/issues/546)). Message bodies are framed as untrusted peer or hub text, not a new authority source; private envelopes remain private in logs and public views ([#193](https://github.com/STAIxBWLB/agent-hub/issues/193), [#198](https://github.com/STAIxBWLB/agent-hub/issues/198)).
+
+The bus applies limits to a sender, sender-recipient pair, important messages, and repeated content before queueing. An important message consumes scarce attention because it can steer a busy turn; refusals cost no rate token and name the retry boundary ([#38](https://github.com/STAIxBWLB/agent-hub/issues/38)).
+
+## Queues and delivery outcomes
+
+The in-memory bus schedules messages; `DeliveryJournal` durably records an individual transport attempt and the original envelopes behind any rendered output. A peer receipt such as `accepted` or `completed` describes transport, not the corresponding task's acceptance, completion, or approval. That separation lets a timeout or restart remain explicitly uncertain without inventing a task outcome ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37)).
+
+Push peers receive bounded batches. Condensation is optional, excludes important, remote, and invocation messages, and keeps `originals` separate from `out` so replies, safe failures, and recovery still refer to what the peer was actually given. On an eligible safe retry, a failed batch falls back to individual envelopes, and a previously failed envelope goes alone so a poison item cannot block its neighbors. These bounds preserve queue progress when summarization or one recipient fails ([#713](https://github.com/STAIxBWLB/agent-hub/issues/713), [#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+Pull-only peers catch up oldest-first under a byte budget, but the first envelope always goes even when it exceeds that budget so one oversized item cannot starve the queue; push peers use the digest batch limit. Pull records returned envelopes as completed at handout because the tool result is the readback, not a later native receipt. A busy Claude channel can also pull its own messages through `hub_inbox`; that avoids making a long-running turn an unbounded queue lock ([#493](https://github.com/STAIxBWLB/agent-hub/issues/493), [#713](https://github.com/STAIxBWLB/agent-hub/issues/713)).
+
+Delivery uncertainty normally holds the original and is never an automatic replay. The narrow exception is a hub-authored presence or workflow notice proven moot by current task evidence; mixed, unknown, or requested-stop rows remain held. This removes stale notices without treating arbitrary peer messages as seen ([#434](https://github.com/STAIxBWLB/agent-hub/issues/434)). Safe pre-acceptance failures may retry within a bounded attempt policy; uncertain results remain `needs_review` until an explicit resolution. A peer may retry only its own eligible row and only once per immutable retry lineage; an invocation uses its own ledger and is not replayed as an ordinary message retry ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37), [#991](https://github.com/STAIxBWLB/agent-hub/issues/991)).
+
+A peer may settle its own local `needs_review` row as completed or discard while busy, with the observed revision and a public-safe reason; this records a delivery decision and never changes task state or redelivers the original. Another peer, a remote-room actor, or an active `dispatching`/`accepted` row remains refused. Invocation-bearing rows also remain person-settled because a transport action cannot assert the outcome of an invoked operation. `hub_inbox` may pass a `needs_review` hold to return newer queued messages and bounded id/revision metadata naming the held row, while leaving the uncertain originals held. Pause, recovery, lifecycle, storage, and active-delivery fences still apply. This lets the current recipient make progress without treating uncertain work as delivered ([#1079](https://github.com/STAIxBWLB/agent-hub/issues/1079), [#445](https://github.com/STAIxBWLB/agent-hub/issues/445), [#991](https://github.com/STAIxBWLB/agent-hub/issues/991)).
+
+Invocation requests and results are single-envelope deliveries, not digest material. A reply is correlated to the request handed to that peer and is captured by the invocation path before ordinary publishing; uncertain outcomes stay with the invocation ledger because a missing result cannot be inferred from a transport receipt ([#445](https://github.com/STAIxBWLB/agent-hub/issues/445), [#991](https://github.com/STAIxBWLB/agent-hub/issues/991)).
+
+## Cross-project transport
+
+Encrypted rooms add a screened message transport between local project hubs. Room identity, deadlines, and remote provenance stay bound to each delivery; traffic is not merged into a shared board. A separately pinned read-only invocation relay cannot transfer task or approval authority. This keeps remote delivery from acquiring the receiving project's roles or memory ([#941](https://github.com/STAIxBWLB/agent-hub/issues/941), [#992](https://github.com/STAIxBWLB/agent-hub/issues/992)).

package/docs/design/task-board.md

@@ -0,0 +1,86 @@
+---
+id: task-board
+type: module
+title: Task Board
+status: draft
+parent: agent-hub-architecture
+depends-on: []
+references: [bus, adapters]
+implements: []
+covers: [task-board]
+tags: [agent-hub, dogfood]
+paths:
+  - src/hub/tasks.ts
+  - src/hub/sdlc-metrics.ts
+  - src/hub/board.ts
+  - src/hub/routing.ts
+  - src/hub/task-sweep.ts
+  - src/hub/settled-roles.ts
+  - src/hub/conductor.ts
+  - src/hub/supervision.ts
+  - src/hub/hub-tools.ts
+  - src/hub/tool-refusal.ts
+  - src/hub/review-brief.ts
+  - src/hub/review-scope.ts
+  - src/hub/reviewer-pool.ts
+  - src/hub/reviewer-pool-config.ts
+  - src/hub/release-admission.ts
+  - src/hub/main-checkout.ts
+  - src/hub/checks.ts
+  - src/hub/task-repository.ts
+  - src/hub/no-writes.ts
+  - src/hub/review-findings.ts
+  - src/hub/workflow.ts
+  - src/hub/deliverables.ts
+  - src/hub/deliverable-files.ts
+  - src/hub/plan-conformance.ts
+  - src/hub/sdlc-merge.ts
+  - src/hub/sdlc-mirror.ts
+  - src/hub/ci-watch.ts
+  - src/hub/research-campaign.ts
+  - src/hub/research-experiments.ts
+  - src/hub/research-runner.ts
+  - src/hub/task-approval.ts
+  - src/hub/schedules.ts
+  - src/hub/folder-trigger.ts
+  - src/hub/handoff.ts
+  - src/cli/handoff-args.ts
+  - src/cli/handoff-output.ts
+  - src/hub/task-list-page.ts
+---
+
+# Task Board
+
+The task board is the shared record of work and its authority, not a transcript of peer claims. This module refines [[agent-hub-architecture]] and separates task transitions from [[bus]] delivery and [[adapters]] runtime facts. Current operational rules are in the [task area note](../agent-notes/tasks.md); the [historical ledger](../specs/2026-09-19-agent-hub-design.md) retains earlier decisions.
+
+## Authority and state
+
+`Tasks` mediates task proposals, planning, owner/reviewer changes, acceptance, completion and review. `Board` persists the rows, history and typed evidence in SQLite; transport, CLI and UI layers do not independently apply task transitions. The issue remains the change spec and GitHub remains authority for PR/check/tag facts. Separating these authorities prevents a chat claim or adapter callback from bypassing task policy ([#481](https://github.com/STAIxBWLB/agent-hub/issues/481)).
+
+A command is authorized against the current actor, role, task state and revision. An asynchronous operation can lose authority while preparing evidence, so write boundaries recheck current scope. Console actions bind the selected task ID and its observed flow revision, rather than an unstable list position. The reason is to keep an approved action attached to the row and state the person actually saw ([#424](https://github.com/STAIxBWLB/agent-hub/issues/424), [#525](https://github.com/STAIxBWLB/agent-hub/issues/525)).
+
+Owner, reviewer and planner are distinct responsibilities. A reservation or offer is not acceptance; a completed delivery is not task completion. A saved assignment and the attempt to notify its recipient also remain separate facts, so failed notification cannot erase a committed role change or manufacture a second one ([#297](https://github.com/STAIxBWLB/agent-hub/issues/297), [#525](https://github.com/STAIxBWLB/agent-hub/issues/525)).
+
+## Selection and admission
+
+`routing.ts` selects candidates as a pure function over declared policy and current facts. `Tasks` applies admission and writes through the same selection rules used by route explanation. Roster, roles, privacy, availability, capability evidence and WIP remain explicit inputs, which prevents explanations and actual offers from becoming separate policies ([#525](https://github.com/STAIxBWLB/agent-hub/issues/525), [#418](https://github.com/STAIxBWLB/agent-hub/issues/418)).
+
+Automatic offer and backlog paths respect `plannedStart`; a future card becomes eligible at its boundary through existing sweep/release passes. Explicit person/planner authority is separate. This avoids offering scheduled work early without taking away deliberate manual control ([#1076](https://github.com/STAIxBWLB/agent-hub/issues/1076)).
+
+Urgent acceptance can reclaim only enough unaccepted, unstarted, non-pinned and non-urgent offers to fit the limit. It does so after other admission checks and immediately before the accept write; if insufficient, it reclaims none. Accepted work is never displaced merely to satisfy a new urgent request, because an offer and an active commitment have different costs ([#1080](https://github.com/STAIxBWLB/agent-hub/issues/1080)).
+
+## Completion, review and evidence
+
+Completion binds the submitted full head and any verified deliverable records. It may run a configured check before requesting review. A review records a verdict against that evidence; it does not itself merge a PR. An unmerged approved task can receive a new owner submission, superseding the earlier review binding rather than treating old approval as authority for changed code ([#1047](https://github.com/STAIxBWLB/agent-hub/issues/1047)). A re-file cannot silently inherit an old head after the linked PR moves, and an approval with no supplied head refuses known-stale evidence. Refusals name the recorded and supplied or read heads and direct the owner to re-file `hub_task_done` with the new full SHA in `refs.commit`; summary text is not head evidence. This prevents stale approval from being presented as review of changed code ([#1121](https://github.com/STAIxBWLB/agent-hub/issues/1121)).
+
+Review independence and declared scope are different controls. Selection excludes conflicts using current implementation history; a `code` reviewer supplies code findings, while full test/CI proof belongs to the merger's gate. Evidence-only inability to run tests is not a code defect. This keeps valuable sandboxed review without inventing CI evidence or accepting self-review ([#744](https://github.com/STAIxBWLB/agent-hub/issues/744), [#852](https://github.com/STAIxBWLB/agent-hub/issues/852)).
+
+Task text and private-turn words can reach owners, reviewers, overlap notices and memory. Public views use the host's current privacy projection; PII tasks remain stubs for unauthorized observers, and private turns cannot write ordinary shared task text. The projection belongs at the shared boundary because filtering individual callers would leave another observer exposed ([#198](https://github.com/STAIxBWLB/agent-hub/issues/198), [#230](https://github.com/STAIxBWLB/agent-hub/issues/230)).
+
+## Read models and policy extensions
+
+Agent list reads return bounded, newest-updated compact pages built from public rows, with a keyset cursor and explicit detail/ID reads. Console compatibility is separate. Pagination is not a frozen snapshot during concurrent edits; its purpose is bounded communication without bypassing private-row projection ([#1083](https://github.com/STAIxBWLB/agent-hub/issues/1083)).
+
+Lifecycle policy can be off, advisory or enforced; this is separate from always-applicable role and privacy invariants. Plans, cost/check scope, review findings and external evidence retain their own typed provenance. Research campaigns and experiments likewise distinguish declared, host-observed and runner-attested facts instead of promoting prose to a signed result ([#481](https://github.com/STAIxBWLB/agent-hub/issues/481), [#932](https://github.com/STAIxBWLB/agent-hub/issues/932), [#1018](https://github.com/STAIxBWLB/agent-hub/issues/1018)). Detailed research contracts remain in the [campaign design](../specs/2026-11-01-research-campaigns-design.md).
+
+When the specs policy is enabled, covering design specs participate in proposal/accept notices and completion/review reports. Report mode informs; require mode needs an updated spec or a recorded acknowledgement for each applicable unchanged spec. Commitless and verified no-change work remains quiet, and private evidence is withheld rather than exposed to satisfy a report. These modes preserve owner choice while making design drift visible ([#1064](https://github.com/STAIxBWLB/agent-hub/issues/1064)).

package/docs/dogfood.md

@@ -13,7 +13,7 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Distinguishable sessions and sender provenance (#1036, `session_identity`) | on after release and upgrade: a connection that names a peer id but is not that peer's current session is a distinct `<peer>~<origin>` session that can send and read, holds none of the peer's roles and replaces nobody; the channel plugin binds to its own project; every envelope and attach event records the connection. Nothing is refused to a connection that worked before. The recovery label `session_identity` applies once an unsettled delivery holds a session's message | `grep '"session":true' .agenthub/state/events.jsonl` lists every message a foreign session sent, with its minted id and no path or text; a recipient's header shows `from "claude~<id>"` for it; test/identity-provenance.test.ts (AC1, AC3, AC4, recovery label) and test/identity-channel-project.test.ts (AC2, real plugin against a new and an old hub) hold it. Not authentication: a same-user process can always act as the user |
 | Cross-project task handoff with state follow-back (#604, `task_handoff`) | on after release and upgrade: `ahub task handoff` and `hub_task_handoff` register work for another registered project that runs agent-hub on this machine as an ownerless proposal on its board; the requesting peer is told each state change as a `kind: task` message. Nothing is queued, and the origin has no authority there | `ahub board --handoffs` lists what this project handed over with the last state each target reported; `ahub board` and `ahub task show` in the target name the origin project and peer; test/handoff-daemon.test.ts runs two real daemons (AC1 to AC5 and the recovery label), test/handoff-core.test.ts and test/handoff-board.test.ts hold the pure core and the tables |
 | Staged project upgrades (#1039) | off: available for the person to upgrade projects independently; this development hub is not upgraded by a fixture | test/published-protocol-compat.test.ts uses the published 0.25.0 client/plugin and reverse daemon; test/staged-upgrade.test.ts checks independent holds and scoped effects; test/staged-runtime-daemon.test.ts checks a real release-root daemon after mutable install removal; test/board-schema-guard.test.ts checks named pre-effect refusal and WAL metadata; `test/project-runtime.test.ts` and `test/project-runtime-lifecycle.test.ts` cover updated resolver retention/refusal and real lifecycle/dashboard routing with synthetic captured daemons; `test/runtime-capture-prune.test.ts` covers references, bounded retention and publication races; `test/upgrade-stopped-project.test.ts` verifies no preservation for stopped projects. These fixtures do not prove published pre-0.26 CLI behavior |
-| Approval head binding and re-review (#1047) | off until release and project upgrade; fixture evidence only, this PR does not change the running hub | `test/task-review-refile.test.ts` covers owner re-submit, reviewer withdrawal, legacy verdict heads, merged/cancelled refusals and held-screen races; `test/sdlc-queue.test.ts` and `test/sdlc-merge.test.ts` reject stale approval at queue and dispatch. `ahub task show <id> --json` exposes `approval.head`, `latestHead`, `mismatch` and `current`; verdict history retains `reviewedHead` |
+| Approval head binding and re-review (#1047, #1121) | source/fixture coverage; the #1121 stale-head protections and actionable refusals await release and upgrade; live re-file verification not run | `test/review-head-binding.test.ts` covers both-head refusals, moved-PR commitless re-files and omitted-head stale approvals; `test/task-review-refile.test.ts` covers owner re-submit, reviewer withdrawal, legacy verdict heads, merged/cancelled refusals and held-screen races; `test/sdlc-queue.test.ts` and `test/sdlc-merge.test.ts` reject stale approval at queue and dispatch. `ahub task show <id> --json` exposes `approval.head`, `latestHead`, `mismatch` and `current`; verdict history retains `reviewedHead` |
 | Default agent set started by `ahub up` (#608, `start.agents`) | off here: this repository's agents are started by their own terminals; it is a machine-local setting and a committed config cannot turn it on. On for a person who runs `ahub setup` and `ahub up` on a project that lists agents. | each `ahub up` prints one line per agent (started, already attached, or the refusal with the manual command); the `peer_start` replies in `hub.log` and the terminal provider's recorded starts show whether a listed agent attached, and `ahub status` shows its state after |
 | `ahub down` (counterpart of `ahub up`) | on: an alias of `ahub kill` for stopping this project's hub | the person stops the hub with `ahub down` and `ahub status` then reports it stopped; test/identity.test.ts keeps it person-only (`console`) and labelled `down`, and test/help.test.ts holds its help entry |
 | Encrypted rooms (#446 X1) | off; source-only crypto/wire, with no broker, room link, invitation CLI or delivery enabled | real WebCrypto vectors and negative wire fixtures; atomic memory fake ports establish ordering only; durable X3 state and the X7 two-machine person receipt remain unverified |
@@ -47,16 +47,18 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Floor policy (#999 T3, `action_policy.floor`) | source and test after merge and release; off here (a person turns it on in the untracked `config.local.json`), and the running hub takes it after upgrade | `test/action-floor.test.ts` (every allowed, asked and opaque case, status guard rows) and `test/daemon-action-floor.test.ts` (the Pi permit path through the real daemon: allowed calls run with no prompt, force and default-branch pushes, tags, `gh release`, `--admin` and other repositories ask); T4's live receipt records it under Orca |
 | Confirmation-point inventory (#999 T0) | source and test coverage; `ahub autonomy status` reads the inventory after this feature is released, with no default prompt change from the data alone | `test/confirmation-matrix.test.ts`: every adapter-catalog kind has a tool-approval and a classed-action row per environment, kinds facts equal the definitions, cited source lines exist; the `unknown` rows are the list T4's live receipt must close |
 | Project autonomy preset (#999 T1) | off on this repository until released and explicitly enabled by the person; project scope only | focused person-only, retained-consent, metadata-independent off and authenticated/fallback preset undo tests; the preset writes `action_policy.floor` (#999 T3) and off removes it; status separates current modes from desired defaults and reads each floor class from the host verdict (`floorEnforcement`), naming the unverified guard where the hub does not see the call first; the Orca zero-prompt native task remains T4 |
-| Machine autonomy and used Claude homes (#999 T2) | off until released and explicitly opted in by the person; no real home is changed by fixture tests | trusted-default/unsafe-default startup consent, all-project preview/apply, init inheritance with unchanged absent-file ask defaults, and isolated per-home plugin/hook setup/status tests; metric: applied/refused registered targets and missing/unknown discovered-home states; native Orca receipt remains T4 |
+| Machine autonomy and used Claude homes (#999 T2) | off until released and explicitly opted in by the person; no real home is changed by fixture tests | trusted-default/unsafe-default startup consent, all-project preview/apply, init inheritance with unchanged absent-file ask defaults, and isolated per-home plugin/hook setup/status tests; #1069 covers preserving project/local plugin rows while configuring only user scope, plus recording `start.agents` after a failed home step; metric: applied/refused registered targets and missing/unknown discovered-home states; native Orca receipt remains T4 |
 | Read-time memory code neighbours (#684 phase 4) | off until released; dashboard toggle is opt-in | derived call edges with current SHA; attached fail/decision brief coverage; explicit unknown/truncated results; unchanged authoritative memory log bytes |
 | Canonical memory symbol anchors (#684 phase 3) | off until released; optional `doctor --stale-anchors` report only | actual-symbol completion anchors versus plan guesses; symbol-related earlier notes at memory hop two; stale/unknown/truncated report counts; zero note mutations during inspection |
 | Symbol preparation and historical recall (#684 phase 3 follow-ups) | off until release | exists calls per no-reviewer completion; raw-signature fail recall; indexed-definition/unknown labels; unchanged note/candidate bytes and neutral cleanup failures |
 | Overlap notices | on; plan symbols match by normalized name (arguments stripped, a bare name matches the last segment, two qualified names must be equal; #682 phase 1b) | `ahub report`: overlap warnings, task pairs; false-overlap rate, and symbol-only matches on bare common names (#682) |
 | Backlog phase grooming and issue planning (#759) | off until released and the running hub supports the new planning fields; relinks for cards #138/#287 remain a post-landing planner action | related-phase duplicate count; unrelated same-issue duplicate controls; planning revisions with `fields: ["sdlc"]` or `[]`; old spec acceptance absent after relink/undo |
 | Planner WIP caps and backlog pull (#655, #718) | on (`tasks.wip_limits.codex = 2`); reserved-pull handoff on after release; the active / review-wait / reserved split (#784) shows in `ahub status`, the console Peers detail and the dashboard legend after release | `ahub status` split per peer (a full cap held by review-wait shows as such); board history/offer readback: reserved `backlog pulled` -> `assigned` -> `accepted` for the same peer; stale or unowned offers, capacity refusals and held-ready entries |
+| Planned backlog starts (#1076) | source/fixture coverage; active after release and hub upgrade | future planned cards appear as `scheduled` in planner grooming; no auto-pull, `backlog_ready` notice or ready-queue owner offer before `plannedStart`; exact-boundary and after-date eligibility; queue-pressure origins remain retryable until due |
 | Task sweep (stalls, idle owners) | on | stall and sweep events per week |
 | Turn-free coordination | off: experimental; needs a separate measured trial | coordination events, conflict notices |
 | Pull-only peers (agy) | on; `hub_inbox` drains to 64 KiB (#713) | unread offers, empty-inbox polling (#681); queued count and oldest queued age per pull-only peer in `ahub status`; reads that said `N more waiting` |
+| Bulk clear of failed queue rows and the settled-row filter (#1096, `queue_discard_states`) | on after release and upgrade: `ahub queue discard --peer <id>` also takes the peer's unsettled failed rows and `ahub queue list` hides settled rows (`--all` shows them); fixture coverage only (`test/queue-discard.test.ts`: real daemon and CLI, a fake old hub for the capability refusal). A person using it on a real backlog is not yet recorded | `ahub queue discard --peer` runs that name a failed count, `queue list` stderr lines `N settled deliveries hidden`, and the failed-row count per peer in `ahub status` falling after a discard; a refusal that names `queue_discard_states` means an older hub is still running |
 | Completed-change notices, grouped and superseding (#713) | on after release; accepted tasks only | queued `is done and touches` notices per peer (one per done, not per task and per repeat); `superseded completed-change notice` discards; `ahub queue discard` uses |
 
 ## Review and lifecycle
@@ -85,7 +87,7 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Merge-time PR readback, release metrics and security-scan baseline (#481 S7, AC12) | source and fixture coverage with a fake gh and real train transitions; the readback is on wherever auto merge is `on`, release metrics need shipped trains with recorded history, and the security scan and its bands stay off here until `[security_scan]` and `[bands.security_open_alerts]` are set | `cost` on merge records, `ahub sdlc metrics` review/CI-at-merge rows, the releases row of `ahub sdlc release`, `security_scans` rows and `security_open_alerts` cards |
 | Required checks | advise (`check (ubuntu-latest)`, `check (macos-latest)`, `seeded guards`) | first-pass CI rate, same-head reruns (`hub_sdlc_costs`) |
 | Seed anchor diagnostics (#684) | on in the seeded checker; exact-match failure remains mandatory | missing anchors report the base commit, enclosing symbol and current file/line or explicit unknown; `test/seeded-check.test.ts` |
-| Release authorization (#481 S6, #1063) | fixture coverage; delegated live consent awaits release and project upgrade | `test/sdlc-release-authorization.test.ts` and flow fixtures retain exact candidate/docs/origin/restart bindings and record the actual user/conductor actor; agent-read and floor fixtures refuse other peers, private turns and live-test; no fixture authorizes a live release |
+| Release authorization (#481 S6, #1063, #1120) | fixture coverage; delegated live consent awaits release and project upgrade | `test/sdlc-release-authorization.test.ts` and flow fixtures retain exact candidate/docs/origin/restart bindings and record the actual user/conductor actor; agent-read and floor fixtures refuse other peers, private turns and live-test; `test/runtime-capture-checker.test.ts` proves a real capture carries the documentation checker and that a missing or failing one is refused as its own cause, not as stale documentation; no fixture authorizes a live release |
 | SDLC metrics and control bands (#481 S7) | `ahub sdlc metrics` on; bands off until `[bands]` is set in `.agenthub/sdlc.toml`, and they write cards only in advise or enforce (in off the report still shows tiers). Completion checks are off here, so `first_pass_check` and the PR-based figures read unknown | its own report; breach episodes per week by tier, and band cards the planner accepted rather than dropped |
 | Fresh headless reviewers (#223, #519) | configured here (`codex-review`); per-tool approval correction and no-verdict diagnostics/re-offer (#783) take effect after release and upgrade | reviews by fresh sessions, findings they add; a per-review start failure names a closed cause class (#722): `ahub status` reviewer line and hub.log `[cause: ...]`, with the share of failures that are `unknown`; stale admission skips and current-policy `no_verdict` reroutes leave the reviewer available (#781); a real `hub_review` verdict per verified backend/version, beyond inventory-only proof; bounded refusal diagnostics, confirmed re-offers without queue holds, and uncertain fallback holds |
 | Completion checks per class | off: the implementer already runs `scripts/check.sh`; a hub-run copy would double the heavy-slot use | time to verdict when on |
@@ -133,12 +135,27 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | PII routing | on | PII tasks and where they ran |
 | External module-kind instances (#754) | off here: no person-pinned module with an explicit headless-instance opt-in is configured | fake mixed builtin/module starts, current-owner and MCP refusal counters, retained stopped bindings and no-import source/target fences (`test/external-instance-*.test.ts`); native/account receipts remain unmeasured |
 | Multiple Jcode instances (#685) | pending | turns per instance |
+| Jcode TUI refusal causes and the recovery hint (#1085) | on for the base jcode wherever `roster.jcode` is on; fixture coverage only (fake jcode server drives each cause class, a resumed session and the status hint). A live recovery of a real jcode under a person's home is unverified and is not run here | hub.log lines `native_tui_launch jcode refused: <code>` per class (a class that dominates names the real failure), and `ahub status` showing the `jcode is running headless after recovery` line only until a ready TUI launch is served |
+| Peer terminals open in the target project's Orca worktree (#1089) | on wherever a TUI start opens a terminal through Orca; fixture coverage only (a fake `orca` CLI answers `worktree list` and records every call: a start from another project's terminal, refusals for no match, a parent or child root, an archived entry, two matches, a cut-off list and an Orca failure). Run against a real second project in Orca is unverified and not run here (no live panes) | hub.log lines `the hub opened no watch pane (Orca has no worktree whose root is this project's root ...)` and `ahub start` refusals that name the same cause, and no `ahub <peer>` failing its project-root readback after a hub-made start |
+| Crash-recovery notices that clear (#1082) | on after release and upgrade, for the first crash a hub recovers from after that; fixture coverage only (`test/crash-notices.test.ts`: a real daemon over a planted crashed run, peers attached through the bus, rows resolved through the control path). A real `kill -9` recovery on a project with live peers is not recorded here | the `crash` lines of `ahub status --json` after every peer is attached and the held rows are resolved (expected: the headline only); the headline count against `ahub queue list` for the crash's own rows; any `run ahub ... again` line still showing next to an attached peer |
+| Urgent accept takes back unaccepted offers; WIP refusal splits accepted from offered (#1080) | on after release and upgrade; fixture coverage only (`test/urgent-wip.test.ts`: a real `Tasks` over a real board, an owner at its limit with one accepted task and offers). A live urgent task for a busy owner is not recorded here | task history: `unassigned` by `hub` with a `displaced by urgent task` note; the planner notice `was taken back from`; any `planner WIP capacity` refusal that still reads as one undivided list of open tasks |
+| Declared needs keep work from a peer that cannot do it (#1081: `needs_network`, `needs_worktree`) | on after release and upgrade, for tasks proposed with `needs_network` or `needs_worktree` (or `--needs-network`, `--needs-worktree`); fixture coverage only (`test/routing-network-needs.test.ts` and `test/routing-worktree-needs.test.ts`: routing, `route explain`, explicit assignment, a reservation, accept with a rostered fake Pi and Codex, and a real git repo showing a refused accept creates no branch ref; `test/capabilities-network-worktree.test.ts`: a real daemon's per-peer capabilities). A real Pi or local worker offered flagged work is not recorded here. A hub-made worktree for a sandboxed peer (#1115) is covered by fixtures only (`test/task-worktree.test.ts`: real git, a bare origin, the hub's commit and push, a moved branch or HEAD refused, the path policy, decline and cancel cleanup; `test/task-worktree-sandbox.test.ts`: the real `sandbox-exec` profile, unchanged, with the peer editing and the hub's commit after (the peer's own commit failing is asserted in `test/sandbox-git-refs.test.ts`, #1123); `test/task-worktree-tasks.test.ts`: accept, refusal, decline, cancel and the done hand-off through `Tasks`), so it is on after release and upgrade, for flagged work offered to Pi or local in a git repository with a GitHub origin, and its metric is a Pi or local task whose branch was committed and pushed by the hub and reviewed, with no `.git` write attempt from the sandbox (expected: none) and no empty `task/*` refs left by a declined or cancelled one | `ahub route explain` lines `skipped, no network` and `skipped, no worktree` for Pi or local; Pi or local declines of work that needed the network or a worktree (expected: none once the task is flagged); empty branch refs left by a declined Pi or local task (expected: none for flagged tasks); unflagged tasks that were declined for a missing worktree or registry, which show the planner is not flagging them |
+| Sandbox refuses `.git` ref, HEAD and worktree writes (#1123) | on after release and upgrade for the local worker and Pi (hub sandbox); fixture coverage under the real `sandbox-exec` only (`test/sandbox-git-refs.test.ts`: the main checkout, a hub-made worktree, a worktree beside its project, a bare repository's worktree, a submodule, a nested one and a linked worktree's, folded names, projects below directories named like the rules; `test/sandbox.test.ts` and `test/tools.test.ts` rewritten where they asserted a sandboxed commit). It needs macOS, so the Linux gate skips it. A real Pi or local worker task is not recorded here; since #1129 a sandboxed task of a write class gets the hub's worktree and commit whether or not it is flagged | a Pi or local write-class task that ends with uncommitted edits in the main checkout (expected: none, the hub made it a worktree), the local `git` tool's `the sandbox does not let you move a branch` note in turn results, and any `Operation not permitted` on a `.git/refs`, `HEAD` or `worktrees` path from a command that should not need it |
+| Hub worktree and commit for every write-class task of a hub-sandboxed owner (#1129) | on after release and upgrade, for `implement` and `bulk_edit` work offered to Pi or the local worker in a git repository, whether or not the task says `needs_worktree`; fixture coverage only (`test/task-worktree-tasks.test.ts`: an unflagged implement and bulk_edit task get the worktree at accept, the hub commits it at `hub_task_done`, decline and cancel clear it, read-only classes and PII tasks get none, a self-claim makes it; `test/routing-worktree-needs.test.ts`: write-class work is not offered where the hub cannot make a worktree and the trace names the cause, read-only classes are not refused; `test/pi-daemon.test.ts` runs a real Pi accept in a repository). A real Pi or local worker task through a whole accept, edit and done is not recorded here | write-class tasks owned by Pi or local whose `hub_task_done` carries a hub commit and branch (expected: all of them); `ahub route explain` lines `skipped, no worktree` for Pi or local on write-class work outside a git repository (expected there, with the cause), write-class tasks that stay with Claude or Codex because the hub could not make a worktree (the cost of this rule: watch whether it starves Pi), and empty `task/*` refs left by a declined or cancelled one (expected: none) |
+| Paged `hub_task_list` (#1083) | on after release and upgrade, for agents (an agent session's `ahub board` follows the pages); the person's console and `ahub board` from a terminal keep the bare array. Fixture coverage only (`test/task-list-page.test.ts`: a real daemon with 600 seeded tasks; `test/board-agent-paged.test.ts`: the real `ahub board` and `--columns` under an agent identity over a two-page board). A real conductor session reading the live board is not recorded here | the size of a conductor's `hub_task_list` result on the live board (expected: under 64 KB, a `next` cursor while more exist); a page walk that ends with no task repeated; `ahub board` run from an agent shell listing as many tasks as `ahub board` from a terminal; any peer or script that still fails parsing `hub_task_list` as a bare array |
+| `ahub init` guided prompt (#1065 T2) | on wherever a person runs `ahub init` at a terminal on a new project with no flag and no `--yes`; fixture coverage only (the real CLI under a scripted pty in a temporary HOME: `test/init-prompt.test.ts`). A person answering it on a real new project is not yet recorded and not run here | `ahub init` runs by a person that end with `wrote ...` after the plan, against runs that end `nothing was written` (N, Ctrl-C, Ctrl-D, three bad answers); no `Write this?` line in any log of a peer, live-test or piped run; the settings a person changes from the default, per question |
+| `ahub init` settings flags (#1065 T1) | on wherever a person runs `ahub init`, new or existing project; fixture coverage only (the real CLI against scratch projects and a scratch hub home). The guided prompt (T2) and the specs rows (T3) are not built, and a person using the flags on a real project is not yet recorded | each `--dry-run --json` `settings` row is a change a person asked for (key, file, old and new value), `ahub init` refusals name the allowed values, and `git diff` of `.agenthub/config.json` after an init with flags shows only the named keys |
 | Jcode usage and context readings (#801) | source/fixture coverage and one isolated live probe of 0.99.1 against a fake gateway (docs/verification/2026-10-28-jcode-0.99.1-usage.md); a real account and provider remain unverified; no native quota reader (Jcode gives no window length) | `ahub status` and the dashboard show `jcode_usage_update` occupancy, `ahub usage` and `ahub report` rows for source `jcode_acp`, and `ahub budget` still says `no reading` for Jcode |
 
 ## Operations
 
 | Feature | State here | Measured by |
 | --- | --- | --- |
+| `ahub init --specs/--no-specs/--spec-review` and person-only `ahub specs stamp` (#1064 T3) | on after release: a new or existing project gets the specs block by default; no repository design specs or stamps are recorded with it here yet; fixture coverage only (real CLI against scratch repositories: `test/init-specs.test.ts`, `test/specs-stamp.test.ts`, `test/check-docs-parity.test.ts`). A person stamping a real spec in a terminal is unverified and not run here (no live terminal session) | `ahub init --dry-run --json` `settings` rows for `specs.enabled` and `specs.review`; the specs block present in `AGENTS.md` of projects where `specs.enabled` is true and absent where it is false; `specs stamp` runs that end with `stamped N documents` against refusals for uncommitted covered paths; no `verified-against` change authored by an agent (`git log -p` on spec files) |
+| Per-call write outcomes (#1078) | source/fixture coverage; installed-hub activation and the reported live 35-45 s stall remain unverified | `test/tool-request.test.ts`, `test/control-client.test.ts` and real daemon/channel fixtures count one effect per request ID, preserve pending joins and reject changed scope/payload; the 600-task synthetic p95 receipt is `docs/verification/2026-11-02-control-write-outcomes.md` |
+| Control-write timing and event-loop delay (#1126) | source and isolated fixture coverage; live activation and cause of the reported stall remain unverified | `test/control-write-trace.test.ts` pins metadata/privacy/caps, lazy screens, five-minute diagnostic expiry and completed-span correlation; `test/control-write-telemetry.test.ts` checks admission before scanning, forces a blocked real daemon write and checks phase logs/status counters; historical UTC windows are in `docs/verification/2026-11-03-control-write-stall-windows.md` |
+| Recipient settlement and inbox reads behind held rows (#1079) | source/fixture coverage; installed-hub activation and a live busy-peer settlement remain unverified | `test/recipient-settlement.test.ts` checks busy own-row completed/discard with reason and revision, foreign-row refusal and queued reads behind an unchanged held row; pause/recovery/lifecycle fences remain covered |
+| Design spec inspection and task notices (#1064 T1/T2) | source/fixture coverage only; no repository design specs configured yet; dogfood drafts follow in later phases | `test/specs.test.ts` checks graph/freshness and empty-project silence; `test/specs-tasks.test.ts` checks report/require, head-bound acknowledgements and privacy; committed-head inspection fixtures exclude dirty/main-checkout bypasses; adoption metrics are the counts of `spec not updated` reports, acknowledged reasons and unchanged-spec refusals |
 | Screened room chat and person inbox (#446 X4/X5/X5b) | default off here; requires person enrollment/exposure; console panel 8 and dashboard Agents remain metadata-only; person CLI alone can show one inbox body; real two-machine/account leg remains unverified | signed completed (admitted) versus immutable completed (inbox); once-only inbound count, body-free metadata/list JSON, framed/control-stripped person show, done/discard/expiry purge and fixed stored-byte cap/age refusals, post-ack retries; 1,100-row complete-list ceiling; no broadcast/roles/board/body telemetry, key/storage creation from status or mixed-version success claim; existing restart/binding/disposition regressions |
 | Capability discovery (#445 C1) | off here until a person shares an entry: nothing is listed without `invocation.share` in `.agenthub/config.local.json`; Kimi 2.3.2, Qwen 0.26.1 and Codex 0.166.0 list, every other version lists nothing; the live listing under a real login and a Codex 0.166.0 install remain unverified (the C0 probes used fixture homes); invoking is C2 | `ahub capabilities --json` per-peer entry counts and share states; `hub_capabilities` calls (the `capabilities_list` and tool lines in the hub log) against the count of shared entries; a peer on an unprobed version showing zero entries is the pin working, not a fault |
 | Capability invocations (#445 C2/C3) | off here until a person shares a capability; read needs no approval, write/external require task scope and allow-once approval for each call; unattended refuses effects. Stand-in round trips and approval/audit/hold tests are the verification target; live Kimi/Qwen/Codex receipts remain C4 | `invocation` events and rows by outcome (completed, refused, failed, expired, timeout, needs_review), approval ids and task audit entries, result bytes, time from queue to settle; a read that times out against a live peer is the signal to look at that peer, not at the hub |
@@ -173,6 +190,7 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Upgrade and recovery | on, per release | upgrade receipts in `docs/verification/` |
 | acon console plugin (#935) | off here until a person runs `ahub setup` after the release and `acon ui` on this machine; the plugin registers per agenthub home, not per repository | `acon plugins` shows `ahub verified`; the console's agent-hub panel shows this repository's live board, and an approval answered from the console inbox appears in hub.log as `answered option allow_once by dashboard`. Space (#1012): adopted with the plugin, no separate switch; acon's Space view (Flat, Room, 3D) shows this repository's peers as actors (state and marks matching the dashboard's office), the board columns as queue/work/review/done zones with the same counts, and overlap links plus message arcs (broadcasts to every other desk) as links; clicking an actor or card opens this project's agents or board panel |
 | Agent CLI version policy and trust (#691) | on after the release: Codex 0.163.0 verified by the [2026-10-22 receipt](verification/2026-10-22-codex-reviewer-isolation.md) and 0.164.0 by the [2026-10-24 receipt](verification/2026-10-24-codex-0164-reviewer-isolation.md); Kimi 2.3.0 and Qwen 0.26.0 verified by the [model-free receipt](verification/2026-10-22-kimi-qwen-compat.md), Kimi 2.3.1 by the [2026-10-25 model-free receipt](verification/2026-10-25-kimi-231-reviewer-compat.md) and 2.3.2 by the [2026-10-26 one](verification/2026-10-26-kimi-232-reviewer-compat.md), with account/provider live legs unverified; agy 1.4.4 in-line | model-free isolation receipts, `ahub agents` verdicts, versions trusted per machine, lead time from an `agent-compat` issue to a receipt |
+| Peer child environment isolation (#1077) | source and fixture coverage; no native account or Orca session used | daemon peer children, version probes and process-table helpers contain no `ORCA_*`; person-owned native launches keep their fixture pane's `ORCA_*` context while replacing agent identity; explicit Claude/Codex selectors pass through where the adapter inherits them; preload clears ambient selectors without changing fixture home bytes |
 | Qwen's own TUI over dual output (#286 Part 3) | off here: this repository's hub runs no Qwen peer (roster.qwen is off), and the limits (a hub deny ends the turn without an answer; a stalled turn is stopped only with Esc in the Qwen terminal) are for the person at that terminal to accept. Verified on Qwen 0.26.1 under an isolated HOME by the [2026-10-25 receipt](verification/2026-10-25-qwen-dual-output-t0.md); the live account leg is the person's | `test/qwen-dual.test.ts` against a fake dual-output Qwen; in real use `ahub status` stalled/detached notices per peer and the `needs_review` count of Qwen deliveries (an Esc or an exited terminal ends a turn that way; a deny completes) |
 | Benchmarks (#251, #637) | off: `bench.enabled = false`. The task-routing gate (#637 part 1) is on in CI for every PR: `routing-receipt` fails a change to `templates/routing.toml` without a matching receipt; the model-routing gate (#637 part 2) is the second step of the same workflow: `scripts/check-model-routing-receipt.ts` fails a change to the model-routing keys without a matching `-modelrouting-` receipt, and wants a by-hand `--live` half when an alias or judge moves | bench receipts; `docs/verification/*-routing-*.md` and `*-modelrouting-*.md` receipts; a `routing-eval` check run on every PR with `eval_pass_rate=` and `eval_suite=` in its title (name it as `eval_check` to make it the eval gate); `bun scripts/benchmarks/routing-gate.ts` and `model-routing-gate.ts` print the default's numbers (100% on both splits); the live half (served model ids) has not been run against a gateway yet |
 | Disposable smoke runner (#787 Q2) | off on this repository: it refuses this checkout; use a new temporary fixture; real-account Q2 remains unverified | sanitized receipt checks/counts/timings, zero owned survivors on timeout; fake transport tests are separate |