@staix/agent-hub 0.27.0 → 0.28.0

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)).
+
+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

@@ -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
@@ -133,12 +135,24 @@ 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, and a hub-made worktree for a sandboxed peer is not built (#1115) | `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 |
+| 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` |
+| 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 +187,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 |