@staix/agent-hub 0.12.33 → 0.12.35

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -374,7 +374,7 @@ Assignment is a pure function of `routing.toml`, the task's signals and the peer
 "skip_local"`, `pii = "local_only"`); `ahub route explain <id | --class <c> <title>>` runs the
 same function and prints its trace: signals, every candidate with the reason it was kept
 or skipped, owner, reviewer and route. `local` uses the class's `route` / `fixed_model` for a
-task turn and `[local]` otherwise. Verification failure (tests fail, review `changes_requested` twice) escalates
+task turn and `[local]` otherwise. Verification failure (tests fail, review `changes_requested` `tasks.escalate_after` times in a row, default 3, #488) escalates
 the task to the next peer in `escalate_to`; Switchyard handles per-call escalation
 inside a peer.
 
@@ -573,7 +573,7 @@ AGENTS.md, REVIEW.md
    `end_turn`, never lost.
 3. `[STATUS]` messages from one peer are batched into one digest per recipient.
 4. A task proposed by Claude, accepted by Codex, marked done, is auto-routed to the
-   reviewer; `changes_requested` twice escalates per `routing.toml`.
+   reviewer; `tasks.escalate_after` consecutive `changes_requested` (default 3) escalate per `routing.toml`.
 5. `ahub local` completes a `bulk_edit` task; OmniRoute log shows the request with the
    per-peer token and `x-omniroute-provider: vllm`; `ahub route explain` shows the
    chosen route.
@@ -1837,7 +1837,8 @@ push `accepted` and show none of them.
   selection excludes pull-only peers; only explicit role-specific naming or an
   honored owner reservation permits assignment.
 - `hub_inbox` sends `inbox`. The daemon answers "not attached yet; retry"
-  between welcome and attach, and refuses it for a session with pushes.
+  between welcome and attach. Since #493 the current channel owner may also
+  explicitly pull its queued work, including while its native turn is busy.
   `Bus.pull` is held by every hold a drain respects (`Bus.held`: recovery, an
   uncertain delivery, a console, budget or conductor pause), though unlike a
   drain it does not wait for the peer to be idle; a held pull journals nothing
@@ -1876,6 +1877,45 @@ push `accepted` and show none of them.
 - Control protocol 16 adds the hello `channel` field and `inbox`. Recovery
   sources add protocol 15 (0.12.17 through 0.12.19); the transition from a real
   0.12.19 hub is not yet proven.
+
+## Amendment: channel queue visibility and explicit pull (issue #493)
+
+- A channel session's `hub_inbox` reads the daemon queue through the same
+  authenticated `peer` socket as a tools-only Claude session. The daemon checks
+  current socket ownership and the shared roster, pause, recovery, lifecycle and
+  uncertain-delivery holds. It does not require an idle native turn. Tools-role
+  sockets cannot consume another transport's queue.
+- `Bus.pull` claims one batch synchronously and completes it with its bus
+  checkpoint in the existing journal transaction. A later idle drain or another
+  concurrent inbox call cannot hand those originals out again. Existing accepted
+  pushes remain independent; a pull does not complete them. The hand-out-before-
+  model-read ceiling documented above remains. Framing, `sanitize`, public PII
+  projections and task-offer read evidence retain their existing paths.
+- The plugin also returns its existing bounded local buffer of failed pushes
+  without journal ids. Journaled failed pushes stay in `needs_review`; the plugin
+  never consumes them from this local buffer. A daemon refusal or an unavailable
+  connection cannot prevent reading that local fallback.
+- `delivery_holds` adds optional same-peer `queued` and `important` counts, with
+  no bodies or caller-selected target. Every agent-hub tool-call result can show
+  fresh counts when important work waits. Channel and tools-mode sessions remain
+  silent when an older daemon supplies no counts. Plain pull-only sessions keep
+  their old advisory nudge compatibility. A current zero clears old nudges;
+  unavailable metadata never changes a saved result or its effect classification.
+  Inbox replies show counts without suggesting a repeated refused read, and a
+  tools-mode hint does not grant an inbox capability to that transport.
+- `[FYI]` remains record-only. PR ready, done or submitted, ruling-needed,
+  blocker and changed-contract/path messages require an unmarked or important
+  update. `hub_task_done` and `hub_review` already notify the assigned audience;
+  an extra chat with the same outcome is unnecessary.
+- Native busy-notification evidence and the decision about channel steering are
+  recorded separately in `docs/verification/2026-10-18-493-claude-busy-channel.md`.
+  Claude Code 2.1.302 / Sonnet 5.5 returned the random notification token before
+  the original interactive turn ended. Push-capable `WsPeer` therefore exposes
+  important-only steer through the existing journal/generation-bound push path;
+  detach and pull-only attach remove that capability. Ordinary messages remain
+  queued while busy. A notification write alone is not proof that the native
+  model saw it; the earlier print-mode probe was inconclusive.
+
 ## Amendment: owner and reviewer read their task (issue #208)
 
 `hub_task_show` stays a conductor tool, and a task's current owner and current
@@ -2398,7 +2438,7 @@ the queue.
 - Tasks owns optional board artifact receipts and every mutation. Repository, issue/PR ids, claimed local result/head and a reviewed full SHA are distinct from fresh external evidence. Only the owner/reviewer/person records; only the reviewer/person binds a review head. Invalid identities, unsupported externally supplied facts and private-turn cloud records are refused before effects.
 - Enforce rechecks the current PR head, successful required checks, local receipt on that head, GitHub review and complete unresolved-thread readback before approval. Missing/unknown data blocks, a new head invalidates derived readiness, and changes requested needs no green CI. Advise exposes gates without additional blocks; off retains existing transitions. Historical board approval is not approval of a new head.
 - CLI sdlc status/explain reads bounded structured metadata, not remote bodies. Shared console/dashboard views expose unknown external evidence and the next actor/action; they cannot certify freshness. No merge/release authority is granted.
-- Custom definitions, full merge/release presentation, gsd-lite and a native advise cycle remain pending; see docs/sdlc.md.
+- Later custom definitions and read-only merge/release reports are described below. #481 supersedes the original lifecycle vocabulary and workflow option; a full native advise cycle remains pending. See docs/sdlc.md.
 ## Amendment: optional Qwen Code 0.25.0 ACP peer (#256)
 
 - `qwen` joins the known catalog with default participation off. Only the project's roster selects it; no second enabled switch or default routing preference is added. Its flow roles default to implementer/verifier, which is guidance, not a claim of native reliability.
@@ -2422,9 +2462,9 @@ the queue.
 - Activity contains delivery ids/senders, message/thought chunks, bounded tool summaries, plans, permission request/outcome ids and turn end. It never enters persistent events/logs, UI, tools or cloud memory. Existing final answers still travel through the answer bus.
 - Kimi TUI defaults remain pull-only. Qwen TUI and native visualizer support remain gated by unverified T0 checks. See [verification](../verification/2026-10-11-acp-watch-t0.md).
 
-# gsd-lite amendment, 2026-10-11 (#257)
+# Historical workflow amendment, 2026-10-11 (#257, superseded by #481)
 
-- Optional workflow none|gsd-lite, none by default, uses existing SDLC receipts and Tasks authority. A reviewer/person-owned checklist stores bounded criterion ids, hashed evidence refs and verified/failed/unverified claims bound to the reviewed head.
+- The original optional workflow selector used existing SDLC receipts and Tasks authority; its current replacement is the #481 amendment below. A reviewer/person-owned checklist stores bounded criterion ids, hashed evidence refs and verified/failed/unverified claims bound to the reviewed head.
 - Existing task/predecessor ids must match current Tasks.after edges; missing/cyclic/private cross-links are refused before effects. Imports do not change task ownership, reservations or dependencies.
 - Required unknown/failed criteria and stale heads keep readiness false. Advise remains nonblocking; enforce adds these only to existing approval gates. Route explain, console/dashboard lifecycle views and read-only hashed exports derive the same board/config state. No second writable workflow store, automatic advance, permissions, merge/release or study execution.
 
@@ -2508,12 +2548,12 @@ pii.paths and data.readonly accept exact paths/subtrees and *, ? and whole-segme
 
 ## Amendment: custom lifecycle data (#257)
 
-Optional ordered stage definitions map at most 32 bounded ids to the existing seven semantic bases, existing actor guidance and closed issue/pr/local/review/checks/phase entry/exit gates. Explicit after edges name at most eight earlier configured ids; missing/self/forward/cyclic references refuse. Review and merge base destinations are required by existing Tasks completion transitions. Built-in names cannot change base. Existing holder/person authority and the full approval floor remain; enforce additionally checks an explicit custom stage-change actor without granting a new caller authority. Off/advise preserve claim behavior. Config-aware receipts, projections and every managed native/local task schema use the same stage ids. Historical removed definitions remain unknown, not silently remapped. No new state, executable gate, auto-advance, merge, release, import authority or native success is introduced.
+Optional ordered stage definitions map at most 32 bounded ids to the semantic bases, existing actor guidance and closed entry/exit gates (updated to nine bases and the criteria gate by #481 below). Explicit after edges name at most eight earlier configured ids; missing/self/forward/cyclic references refuse. Review and merge base destinations are required by existing Tasks completion transitions. Built-in names cannot change base. Existing holder/person authority and the full approval floor remain; enforce additionally checks an explicit custom stage-change actor without granting a new caller authority. Off/advise preserve claim behavior. Config-aware receipts, projections and every managed native/local task schema use the same stage ids. Historical removed definitions remain unknown, not silently remapped. No new state, executable gate, auto-advance, merge, release, import authority or native success is introduced.
 
 
 ### Custom lifecycle review corrections (#257)
 
-Phase gates require gsd-lite phase views at configuration validation. Authenticated daemon status gains optional lifecycleStages metadata, with no protocol bump. Separate MCP tools lists use that active snapshot; a live legacy daemon without the field keeps seven stages, while unknown/unavailable metadata withholds the lifecycle-record tool. Editing project data during a live daemon no longer changes its advertised stage ids.
+The original phase gate validation is superseded by the criteria gate and compatibility window in #481 below. Authenticated daemon status gains optional lifecycleStages metadata, with no protocol bump. Separate MCP tools lists use that active snapshot; a live legacy daemon without the field keeps seven stages, while unknown/unavailable metadata withholds the lifecycle-record tool. Editing project data during a live daemon no longer changes its advertised stage ids.
 
 
 ## Backlog foundation (#263)
@@ -3237,8 +3277,8 @@ The guard inventories AST comparisons, closed-list imports and vendor literals,
 including inline dashboard scripts, under stable file/symbol scopes. Its reviewed
 A1 baseline records the current source, rather than claiming the old A0 grep's
 265 line matches equal AST node counts. A new group, count growth or stale entry
-fails; later phases may only shrink this baseline. Only real, unshadowed registry
-resolver imports exempt kind-aware comparisons. Native adapter implementations and
+fails; later phases may only shrink this baseline. A1 originally exempted kind-aware comparisons from real, unshadowed registry
+resolver imports; the A2 amendment below counts them instead. Native adapter implementations and
 explicit non-peer config semantics remain the narrow exceptions. Existing literal
 catalog exports used by older recovery source probes are retained until their
 replacement compatibility proof is available; a refactor must not silently make a
@@ -3260,3 +3300,360 @@ same scanner reports 428/172 on that main and 415/171 on the combined A1 source.
 Every added or increased baseline entry matches that main-only delta; A1 still
 removes thirteen sites and one group. This explicit reconciliation precedes the
 first shipped baseline and does not permit later phases to grow it.
+
+## Adapter registry A2 amendment (#451)
+
+A2 counts native-name comparisons even when a trusted registry resolver supplies
+its left or right operand. These sites use the `kind-aware-comparison` inventory
+pattern and the same lexical file/symbol group as a raw comparison, including
+switch cases. Replacing a raw comparison with `kindOf` or `definitionOf(...).kind`
+therefore does not shrink a baseline group. Alias and shadowing checks remain in
+force. The pre-existing kind-aware preview site is counted explicitly; the A1
+source has 415 other sites plus that one site. A2 removes the transitional
+baseline by migrating policy, rather than by adding resolver exemptions.
+
+Session metadata distinguishes native resume arguments from daemon startup
+restoration. `session.resumeById` means that recovery passes the verified native
+session id to the start command (Qwen). `session.restoreOnStart` means that the
+daemon restores recorded startup options before automatic startup (Pi). Neither
+flag proves that a conversation can be resumed or permits a fresh replacement.
+Crash recovery tests `resumeById` and uses `crashIdentity`; transport choice or the
+presence of a factory does not establish that capability.
+
+A2 preserves literal `KNOWN_PEERS` and `OPTIONAL_PEERS` exports in
+`peer-catalog.ts` for released coordinators that inspect their source. The guard
+records these exact file/symbol exceptions separately with the reason
+"cross-release source probe", and tests their values against the typed registry
+catalog. The same exception preserves `start-mode.ts`'s literal `START_MODE_PEERS`, which released coordinators inspect before restoring Kimi headlessly. The three probes are counted separately (5 + 2 + 3 sites). The native vendor baseline is otherwise empty. A retained coordinator's
+existing source probe must accept the A2 target; no unsupported-target ceiling is
+introduced. ponytail: retire these compatibility literals only after a separately
+approved minimum supported upgrade source no longer reads them.
+
+Native recovery hooks return read-only facts over the existing narrow DTOs.
+`zeroTurn({ stateDir, binding, phase })` reads Codex's existing event proof only
+for planning, and Claude's existing transcript absence only for attachment or
+verification. `restoreArgs(peer)` and `recoveryRefusal(peer)` are pure over the
+captured peer. `personFresh` and `missingEvidence` are policy data, not authority.
+`resumeArgv(binding, fresh)` returns the CLI tail; the coordinator supplies the
+interpreter, entrypoint and project prefix and retains all receipt, repair,
+waiver and unknown-state decisions. The restore oracle, supplemental matrix and
+transition code remain byte-unchanged.
+
+Quota and context readers are pure normalizers:
+`QuotaReader.read(value: unknown): UsageWindow[]` and
+`ContextReader.read(value: unknown, sessionId: string, measuredAt: number): ContextReading`.
+They preserve the existing malformed-input results. The coordinator still binds
+transport generation, native session and measurement time before reporting.
+Palette data additionally carries optional `tone` and `ansi`, preserving the
+existing terminal palette and rendered CSS bytes.
+
+P4 conformance is transport-specific. Delivery-only native drivers set busy
+synchronously at admission; pull-only WebSocket peers receive no unsolicited
+delivery or busy mutation; Claude push keeps its existing receipt/native-start
+busy contract. Native production behavior does not change to satisfy a generic
+conformance case. The kit also covers the existing generation fences, process
+groups, approvals, quota refusals, mode acknowledgement/timeout and recovery
+contracts for each applicable transport, with explicit unsupported outcomes.
+
+`resumeArgv` accepts the existing `SessionRef` (session id/file, backend and model),
+which withholds terminal and launch identity from a pure argument formatter.
+`recoveryRefusal(peer, phase?: "plan" | "restore")` defaults to planning and keeps
+both existing phase-specific native messages. Fixed private compatibility data
+`legacyTargetSupport` and `legacyHeadlessArgv` name only the existing catalog or
+start-mode literal exports; their old read points and regexes are unchanged.
+
+`start.daemonPort` is a closed, data-only engine tag (`codex-appserver`, `acp`,
+`owned-acp`, `pi-rpc`, `local-worker`), required when `start.create` exists. Unknown
+values are refused at registry load. Channel/pull definitions without a factory
+leave it absent. Typed registry-owned wrappers retain the existing `DaemonPorts`
+union; core selects the engine and retains lifecycle/authentication closures,
+while the definition factory remains the only native constructor.
+
+The trusted CLI host may supply `LaunchContext.pi` using the existing Pi builder
+options, extension path and live bridge port/token. A redacted preview supplies
+only redacted placeholders; bridge tokens never reach previews, logs or events.
+`LaunchPlan.env` preserves Pi's existing child environment. Definitions never
+load daemon config or infer executable commands from environment text.
+`VersionContext` adds `observedVersion`, `nativeCommand` and `projectRoot` once:
+the host still performs each probe, while definitions validate or display it.
+`cli.authority` and `cli.personOnlyFlags` can only restrict existing authority;
+identity.ts stays authoritative and missing/unknown metadata retains today's
+rule. `start.passthrough` is data only. The MCP hook is a pure plan over the
+existing project/state/server-entrypoint/form tuple; every write, ordering fence
+and finally cleanup remains in the CLI host.
+
+### A2 internal native host projections (2026-10-18)
+
+The remaining AST inventory after the first A2 checkpoint has 260 policy sites in
+113 lexical groups. Native CLI entrypoints and previews, configuration validators,
+settings rows, plugin inventory and recovery presentation need explicit definition
+projections in addition to the original frozen transport factory hooks. These are
+moves of existing built-in policy, with the same host-owned effects, argv, ordering,
+errors, privacy, permission and timing fences. They add no instance support,
+capability or native behavior.
+
+Private, statically imported built-in preview helpers implement the frozen
+`start.launch` / `publicLaunch` redaction path. They preserve current validation,
+JSON order and placeholders, and cannot execute a native process, connect to
+control, allocate runtime state or write authoritative state. They are not public
+`AdapterDefinition` / `NativeHooks` extension points; configuration cannot register
+a helper. Person CLI entrypoints are relocated into a fixed private built-in
+dispatcher for C1, without adding a public `cli.run` or `NativeHooks` callback.
+The dispatcher cannot load external modules or accept caller-selected callbacks;
+its typed context contains only the original CLI host operations. Identity,
+command access, live-test delegation, audit and project/lifecycle admission remain
+in the host before dispatch, and each moved body retains its native effects,
+ordering, errors, environment and cleanup. Doctor projections carry existing probe
+metadata; the host retains probe execution and output. Configuration projections receive the current validator vocabulary and
+return the existing schema/settings entries. Recovery projections carry the current
+crash plan, continuity decoder/bookmark and unrecorded-terminal classification.
+Reporting flags, tool classification, recall source and display tones are semantic
+data; a consumer must not replace raw comparisons with kind-name wrappers or
+constant aliases. Plugin inventory takes the existing home/cwd/env context and
+returns the existing typed Addon rows, correcting the unused string-array
+placeholder. Arbitrary daemon callbacks and caller-chosen executables, paths,
+permissions or policy remain forbidden. External module publication/validation is
+still A4 and must freeze its accepted subset separately.
+
+Claude's channel is native-hook-driven: delivery insertion remains idle until an
+authenticated native-start observation. Its conformance case asserts that behavior;
+transport adapters retain the synchronous-busy requirement. Unsupported native
+quota or process ownership is an explicit applicability result, never synthetic
+success. Every applicable P4 behavior is exercised with the real adapter and fake
+transport, without changing existing assertions or claiming live-account evidence.
+
+The P4 late-result probe exposed an existing Codex watchdog defect on the unchanged
+54e631d8 adapter: a completed agent message could refill the answer after watchdog
+invalidation, then its stale turn completion could broadcast it without its former
+audience. A2 repairs this intended generation fence in source. It discards answer
+notifications without an active turn and notifications naming an inactive turn,
+retains the legacy unknown-turn compatibility path, and clears expired deltas.
+The new probe keeps its strict no-message/needs-review assertions. Supported native
+RPC behavior, approvals, quota classification and existing tests stay unchanged.
+
+The watchdog fence also covers acceptance before a queued `turn/started` report
+and unanswered hub `turn/start` RPCs. Cancelled named ids remain retired until their
+exact completion or session teardown; late acknowledgements cannot restore a
+cancelled audience or relabel uncertainty as `failed_safe`. Ordinary legacy
+unknown-id starts keep their fallback. After an invalidation with no provable
+native identity, unnamed lifecycle reports cannot be safely attributed: keep the
+peer offline and require a verified reattachment rather than guess a new turn.
+
+### A2 daemon semantic projections (2026-10-18)
+
+The daemon constructs every native driver through `start.create` and the fixed,
+transport-typed `DAEMON_PORTS` wrappers. Protocol lifecycle dispatch may select the
+actual engine; provider policy does not select an unrelated capability as an alias
+for a kind. Existing host callbacks retain their original effect authority,
+privacy, owner checks, ordering and timing.
+
+The internal definitions additionally carry the existing start-only enable-switch
+membership rule, exclusive-start refusal, tool-refresh requirement, explicit
+headless-mode argument, attached-worker reconfiguration rule, dashboard start
+command and pure ACP argv builder. Attach metadata serializes recovery launch
+identity and carries the existing pull-only admission and status guidance.
+Permission status text is separate from the existing permission refusal text;
+`permission.trackUnattended` keeps native unattended ownership accounting distinct
+from protocol dispatch.
+Budget metadata names the soft-token reset on resume. Session metadata declares
+native conversation revert support; the host still checks the actual driver and
+latest turn and owns the pause while reverting. CLI metadata formats retained
+terminal and roster-return notices and supplies the existing preview argument
+tail. These fields only move native policy, preserving existing output bytes and
+behavior. The version hook consumes the already frozen `observedVersion` and peer
+fields; the daemon retains the bounded native transcript probe.
+
+The doctor command consumes fixed built-in metadata and pure observed-value
+projections exported through the registry. Native tool order, plugin probe argv,
+optional roster checks, section/severity, recovery identity fields and legacy
+capture labels stay in the built-in implementation. The CLI retains every spawn,
+source-verification, connection, gateway and memory effect in its existing order
+and privacy boundary. This private data adds no public definition member,
+executable callback or configurable probe; unknown names retain their existing
+Hub/unknown classification.
+
+A2 reanchors thirteen seeded mutants to the same moved semantic guards: explicit Pi
+roster precedence, supported roster keys, retained-terminal result text, Kimi TUI
+recovery refusal and admission cleanup, Qwen opt-in/session/crash resume, planning
+reservation support, active Kimi TUI settings floor, live headless Kimi watch,
+disabled Codex plugins and bounded
+regular-file tooling reads. Seed ids and test targets remain unchanged; the other
+406 seed objects remain byte-identical. The mutation pairs must still demonstrate
+green production behavior and failure with that guard removed.
+
+The final A2 AST inventory is empty for core policy: zero sites and zero lexical
+groups. The reviewed policy baseline is explicitly `[]`; it is never generated
+from source during tests. Three cross-release literal probes remain separate
+(`KNOWN_PEERS` five, `OPTIONAL_PEERS` two, `START_MODE_PEERS` three). Precise
+screening-provider/lifecycle enum false positives remain scoped by file, symbol
+and AST shape; negative fixtures still catch vendor comparisons in those scopes.
+
+Quota participation and execution-budget instrumentation are independent.
+`budget.quotaExempt` preserves native quota exemption while retaining `account`
+and instrumented execution limits: local sets it, Pi does not. Registered kinds
+without budget metadata remain quota-exempt; external ids retain manual quota
+accounting. The A1 named compatibility metadata export preserves its original
+wrapper plans and observable shape, while the registry consumes separate native
+runtime definitions. Native display constants retain reference identity; private
+stream tone selection does not add fields to that observable display object.
+
+Configurable start-mode fallback reads the registered definition's default form,
+retaining explicit overrides and existing unknown-id behavior. The Kimi default
+mutant changes that native metadata from TUI to headless, so the original default
+assertion observes it directly; it does not remove a settings row or mutate the
+retained cross-release source literal.
+
+A2 preserves the recovery tests' assertion contract while reconnecting their
+execution harnesses to production code. The Pi CLI parser harness imports its
+extracted pure parser rather than extracting a removed main.ts declaration.
+The reattach parser VM receives the real registry resolver, and the attachment
+wait VM receives the real exported session-field resolver. Every existing
+`expect` line in these three files remains byte-identical; no fallback, mock
+policy, weaker condition or changed expected result is introduced.
+
+### A2 round-1 parity and capability-scope constraints
+
+Quota handoff uses the registry's native platform projection, preserving exactly
+Claude, Codex, Kimi, Qwen and Jcode. The per-delivery `recallInjected` flag remains
+independent: adding Kimi/Jcode handoff platforms does not make their own sessions
+part of injected-platform exclusion.
+
+Routing reads on-prem trust for PII admission. Legacy fixed-model/relay policy,
+local-allowed refusal text, context handling, preference tier, relay ordering and
+trace labels are native definition data. Host routing and task flow retain their
+existing policy calculations, messages and candidate ordering (including class
+fallback duplicates). This native routing data is not an external configuration
+surface.
+
+Registry loading calls `assertNativeCapabilityScope` before publication. A
+non-builtin definition cannot declare `start.acpCommand`, `attach.admission`,
+`budget.resetSoftTokensOnResume`, `session.crashIdentity`, a `pi-rpc` daemon port,
+or the native `routing` policy block. Fixed builtin membership is object identity,
+not a caller-supplied kind name. Current consumers combine these fields with fixed-builtin assumptions or
+host-global native state; generic shapes are follow-up work before A3/A4 loading. Other ordinary ACP
+metadata remains valid.
+
+The Qwen conductor refusal uses the original generic CLI text. Pi terminal
+observation reads only observed top-level/nested session-file metadata, never
+launch `args.sessionFile`. Pi TUI recovery bindings preserve the captured
+`CLAUDE_CONFIG_DIR` fallback while retaining Codex's `CODEX_HOME` selection.
+
+The guard resolves immutable peer-id constant aliases and supplied-source
+import/reexport bindings through lexical symbols before classifying comparisons.
+Shadowed and unrelated bindings remain independent; named non-peer enum exceptions
+keep their exact scope. It performs no filesystem or package lookup.
+
+## Amendment: playbook lifecycle and criteria checklist, 2026-10-18 (#481 S0/S8)
+
+- The AI-Native SDLC Playbook supplies the built-in stage model of an enabled lifecycle: intent (Plan), spec (Design), plan and build (Build), test (Test), review, merge and release (Deploy), maintain (Maintain). `mode` advise or enforce without `stages` selects this list. Off (no file, or `mode = "off"`) keeps the seven #257 stages, so its config, receipts, `hub_sdlc_record` schema and status output stay byte for byte. An explicit #257 list still loads: off keeps it as written, and an enabled lifecycle keeps its order under canonical ids (spec, plan, build, review, test, merge, release). Any other list needs definitions.
+- Valid bases are the nine playbook stages plus the #257 names `implement` and `verify`, which mean build and test. A stored `implement` or `verify` receipt resolves to `build` or `test` in a playbook config; a write with the old id stores the id the config lists. Custom definitions keep loading with their old base names; a playbook-only built-in id (intent, build, test, maintain) cannot take another base. The test base takes the reviewer actor, like verify. Status carries `playbook` (the playbook stage) whenever the mode is not off; the dashboard shows it beside the stage.
+- The head-bound acceptance-criteria checklist (`criteria` in a receipt) belongs to the Compliance pass. It keeps id, head, 1..32 criteria with required, result and hashed refs, reviewer- or person-only writes and the reviewed-head binding; criterion ids may name issue AC ids (`AC8b`). Once recorded it adds its blockers in any enabled lifecycle; off ignores it unless the retired setting below asks for it. A `criteria` entry or exit gate needs no workflow selector: a missing checklist is a blocker the reviewer can clear.
+- Checklist task import is removed. A non-empty `tasks` list is refused before any write; dependencies stay with `Tasks.after` (`ahub task propose --after`). A receipt stored under `phase` reads as criteria, and its task list is shown with a note and never gates readiness. Board split-undo still treats such a stored list as a reference.
+- Deprecation window (constant `RETIRED_WORKFLOW_FROM`, 0.13.0): before it, `workflow = "none"` loads silently, `workflow = "gsd-lite"` loads with a `hub.log` warning and requires a criteria checklist on every task, the `phase` gate loads as an alias of `criteria` with a warning, and the `phase` receipt name is accepted silently. From 0.13.0 each is refused with a field-level reason; the aliases and their tests are then deleted.
+- Tool schema: when the mode is not off, daemon status carries `lifecycleCriteria: true`, and every managed surface (the channel and tools MCP servers and the local worker) advertises `criteria` instead of `phase` in `hub_sdlc_record`. Custom stage ids and the checklist rename are independent: off and older daemons, custom stage lists included, keep `phase`, because they accept only it. That off schema changes once, when the alias is removed at `RETIRED_WORKFLOW_FROM`.
+- `ahub sdlc export`: a plain off lifecycle (no retired setting) keeps the #257 export bytes (schema 1, `workflow: "none"`, `phase: null`). An enabled or retired-setting lifecycle emits schema 2: sanitized state (id, state, stage, criteria view or a private stub), `stateHash` and `sourceHash`, without the workflow field. In off, a `phase` receipt write also keeps its #257 bytes (`tasks: []`); task import stays retired in every mode, so a non-empty list is refused.
+- Contract amendment, seeds (419 before and after: 414 byte-unchanged, 3 modified, 2 removed, 2 added; the registry baseline is unchanged). Modified, each with the same id, test file, test name and mutation intent: `workflow-reviewer-only` (the criteria/phase check), plus `override-local-schema` and `lifecycle-native-schema`. The person approved the last two on 2026-10-18, because the `lifecycleCriteria` plumbing changed their call sites. Removed with the code they mutated: `workflow-exact-after` and `lifecycle-phase-view-required`. Added for the new guards: `criteria-task-import-retired` and `sdlc-workflow-window-closes`. Tests that pinned the retired gsd-lite behaviour (task import, phase naming, the workflow projection, the implement id stored in an enabled config) are amended in the same PR; every other test is unchanged.
+- S0/S8 implement none of S1-S7 and S9-S11. The issue stays the spec, Tasks owns mutations and GitHub owns PR, check and tag facts.
+## Headless peer instances I2 amendment (#450)
+
+`instances` is a person-authored, machine-local object in an untracked
+`.agenthub/config.local.json`. Each additional `<kind>-<name>` id names its kind
+explicitly and may set `roles`, `start_mode`, `permission_mode` and `worktree`.
+The bound catalog belongs to one project/daemon; there is no process-global
+registration or suffix inference. Declarations are validated before trust
+filtering, cloned and frozen, and limited to 64 additional ids of at most 32
+ASCII characters. Settings cannot create or modify declarations. Identity,
+execution directory and account membership are restart-bound; a live reload
+cannot publish their derived defaults ahead of that restart.
+
+I2 accepts definitions with a native headless factory and environment or ACP
+session MCP identity. Additional Claude/channel peers belong to I3. Jcode's
+project-file MCP identity is not isolated by this phase and is refused for extra
+instances. Additional instances start headlessly; the existing Codex native TUI
+still initializes and attaches to its instance's own app-server proxy. The hub
+never initializes that app-server on the TUI's behalf. `ahub <kind> --as <id>`
+selects the declared identity; selection is removed from native passthrough.
+Missing `peer_instances` evidence on an old daemon/upgrade target is a refusal
+before instance runtime effects, rather than a guess that the instance is a base
+peer.
+
+Each additional implementer requires an explicit registered Git worktree at
+`<project>/.worktrees/<id>` with an attached branch. I2 creates no worktree or
+branch; I4 owns automatic worktree orchestration. A supplied reviewer worktree
+is checked by the same real-path, repository and registration boundary. Without
+a supplied directory, a reviewer may share the project checkout. The native
+process executes in that directory while its MCP environment retains the
+canonical project's hub binding. Launch/restore receipts keep canonical
+`projectRoot`, optional extra-instance `executionCwd` and observed `terminalRoot`
+separate. The terminal grouping root may be only that project root or the
+verified execution directory; exact live launcher, handle, incarnation and
+worktree evidence is still required. Native kind metadata alone never binds an
+extra instance. Revoked declarations or changed directories refuse reuse.
+Effective roles resolve from declaration roles, exact-id policy roles, kind policy
+roles, then definition defaults; launch validation uses the same order.
+
+I2 recovery ceiling: a recovering extra Codex launcher records its launch row only
+after the authenticated start response supplies its execution-root binding. Until
+then, the coordinator retains durable pending terminal-creation and attachment-wait
+evidence; it never records an assumed checkout. Base Codex pre-start recording is
+unchanged. Earlier recording for extras requires independently verified exact-instance
+execution-root evidence. Past-commit resumes do not repeat pre-commit instance
+compatibility checks. Abort and stop-and-archive validate historical receipt structure
+and authenticated runtime ownership independently of mutable declarations; restore,
+fresh and reattach retain current declaration authority.
+
+Routing expands a kind preference to its declared members and considers idle
+state, board WIP and queued load with stable ties. Exact manual candidates,
+reservations and nominations stay exact ids. Assignment and explain use the same
+pure decision and name the chosen instance. Reviewer independence compares
+families (the kind); an eligible other family takes precedence even when busy.
+Only when no other family is eligible may an assignment use its own family,
+recording `sameFamilyFallback=true` in assignment history. This independence rule
+also applies to an explicit same-family reviewer nomination. A declared owner of
+implement, bulk-edit or test work requires the current implementer role and positive
+host evidence tied to the actual adapter generation started in a verified noncanonical
+worktree; a role-only reload cannot promote a canonical reviewer process. External
+ids, including console recipients, retain their existing admission and explicit
+nomination behavior without acquiring native metadata or automatic kind expansion.
+
+Quota readings, pause records and reset windows are shared by the definition's
+account (one account per kind in I2). Member telemetry retains its exact reporter
+id, native context remains per instance, and the shared account's quota pause,
+checkpoint, handoff and reset notice cover all its members. Existing manual
+pauses remain in force. A startup migration conservatively merges old alias
+pause rows, retaining their provenance and moves; no pause is discarded.
+Per-instance ports, native session paths, Pi tool ledgers and model relay
+callbacks do not borrow another instance's process or conversation.
+
+Worktree facts and native turn snapshots use the validated execution checkout,
+while task and turn ids remain in the canonical hub database. An additive
+`turn_workspaces` receipt stores the exact extra-instance root and its snapshot
+fields atomically with turn creation. The legacy `turns` snapshot fields remain
+unknown for those rows, so an older CLI cannot restore their files into the
+canonical checkout. New readers hydrate the same public turn shape from the
+receipt. An absent receipt preserves historical external-peer undo behavior;
+an existing receipt requires the current trusted declaration and the same
+validated root before context changes or file restoration. Pruning a turn also
+prunes its workspace receipt. Review projections resolve converter programs, task
+paths and private-path policy in the execution checkout while their sandbox denies
+other canonical project file data, including when read_allow encloses that project.
+Overlap refusal remains conservative across
+separate worktrees; it may refuse an undo rather than assume independence.
+
+The I2 seed contract amendment re-anchors only `roster-r-pi-override`,
+`roster-r-catalog`, `roster-result-stop-text`, `roster-detached-pi-recovery`,
+`data-pi-factory-wire`, `projection-local-trust`,
+`planning-reservation-supported` and `planner-reserved-status-row` to the
+contextual resolver, aggregate Pi ledger, execution directory and declared-id
+forms. Each keeps its id and named test and removes the same guarantee. The
+projection mutant still removes only `text_projection`; the status mutant still
+removes only reservations. The other 411 seeds and registry baseline are
+unchanged. The PR records every old and new search/replacement and its clean
+and mutant result, per the reviewer's explicit ruling.
+
+## Amendment: roster membership in status, 2026-10-18 (#484)
+
+- The authenticated `status` reply carries `roster: {peer, on}[]` for every supported peer, optional peers included, with the same `on` that `ahub roster list` shows. The field is additive, with no protocol bump; older CLIs ignore it.
+- Launchers that check membership before starting (`ahub jcode`, `ahub kimi --mode tui`) read it through `rosterInStatus` in `src/hub/status-roster.ts` (no imports, so the registry's native CLI entries add no cycle). A reply without the field (an older hub) is unknown: the launcher stops with an upgrade-or-restart remedy and starts nothing. It never reads unknown as off (the jcode bug) or as on (the dead kimi guard; daemon admission still refused off-roster Kimi, so that one was harmless).
+- `settings_get` stays console-only.
+- With declared headless instances, status includes each startup-bound extra id as well as every built-in and optional peer, with its own roster membership. No undeclared suffix acquires a row.

package/docs/verification/2026-10-18-0.12.34.md

@@ -0,0 +1,48 @@
+# 0.12.34 release verification
+
+This record covers release preparation and source review. It does not claim publication, installation, a running-hub restart or native/live acceptance.
+
+## Candidate
+
+Version 0.12.34, control protocol 16 (`src/hub/control-client.ts`), from merged main `f1c4140032d81f4840941a91137e9ab593349d9f`. The candidate includes the three PRs merged since `v0.12.33`: #487 (#451 A2), #491 (#488) and #492 (#485 S0). The exact first-party memory pin remains `@staix/agent-mem` 0.3.1.
+
+- #451 A2 moves built-in native policy behind the adapter registry. Native behaviour is unchanged except the disclosed Codex watchdog fence: late results of a cancelled turn are dropped, and a cancellation without a verified native id takes Codex offline until reattach. The round-2 delta reviews (task #132 review note) diffed base and head probe output (permission, start, roster, palette, crash plans, launch env, previews, `routing.assign` over 3,840 inputs) and found no other difference. The registry guard baseline is `[]`.
+- #488 replaces the fixed two-rejection escalation with `tasks.escalate_after` (default 3, live). Upgrading changes the default behaviour; `docs/quickstart.md` says how to keep two.
+- #485 S0 protects `.agent`, `_agents`, `_agent`, `.gemini` and `.grok` like other agent configuration directories. Scoped grants under them now ask.
+- Still open: live native clients, installed managed-Pi #418 AC8 (#142) and #438 AC7.
+
+## Document review
+
+`node scripts/check-docs.mjs --require-fresh` reported 14 stale documents. Each was compared with its covered source changes from its stamp to the candidate by two read-only reviews, one for the user documents and one for the agent notes. Symbols, paths and limits were checked in the source. No document review is deferred.
+
+| Document | Review result | Checked claims and correction |
+| --- | --- | --- |
+| `README.md` | corrected | Status 0.12.34; the Jcode MCP entry is byte-identical (moved into a definition); the verification link and open legs. |
+| `docs/quickstart.md` | corrected | `v0.12.34` install; the upgrade section for the escalation default (#488) and the new protected directories (#485). |
+| `docs/operations.md` | corrected | 0.12.34 header, protocol 16 range and upgrade examples; escalation via `tasks.escalate_after`; the Claude ask-when-needed protected list; the Codex watchdog fence and offline latch. |
+| `docs/security.md` | corrected | The protected agent configuration list and the #485 directories with their look-alike rule. |
+| `docs/agent-notes/README.md` | unchanged | Background only; the console tone lookup change touches no rule. |
+| `docs/agent-notes/adapters.md` | corrected | `session.zeroTurn` replaces `codexZeroTurn`; registry lists and cross-release literals; the empty guard baseline and alias resolution; native capability scope. Paths now include the registry guard test and baseline. |
+| `docs/agent-notes/benchmarks.md` | unchanged | The Pi command now comes from its definition with the same value. |
+| `docs/agent-notes/budget.md` | corrected | Context readers in `native-context.ts`; checkpoint requests keyed on `budget.checkpoint`; `QUOTA_HANDOFF_PLATFORMS`; quota exemption rules. Scope and paths include the moved readers and the registry. |
+| `docs/agent-notes/bus.md` | unchanged | Bus, journal and deferred-hub sources are unchanged; daemon changes swap peer names for definition fields only. |
+| `docs/agent-notes/daemon.md` | corrected | The registry's `KNOWN_PEERS`; the recovery literal probes; scope and paths include the moved recovery, policy, config and CLI definition modules. |
+| `docs/agent-notes/local-worker.md` | unchanged | `grantablePath` and grant rules hold with the larger protected set. |
+| `docs/agent-notes/models.md` | unchanged | Tool classification now reads `hooks.classifyTool` with the same result. |
+| `docs/agent-notes/tasks.md` | corrected | The PII gate by `trust.onPrem`; `escalateAfter()` read per verdict. Paths include `builtin-metadata.ts` and `src/hub/bus.ts` (`pendingEnvelopes`, backlog #193). |
+| `docs/agent-notes/tests.md` | corrected | Guard failures move policy into a definition, and the baseline stays `[]`; conformance records unsupported cases explicitly. |
+
+`AGENTS.md` area notes list the new definition modules for Budget and Daemon and recovery. A separate manifest commit restamps the reviewed documents against the reviewed source; it does not stamp itself. The release PR must use a merge commit, and committed freshness is rerun on main before tagging.
+
+## Recorded checks
+
+| PR | Final head | CI run |
+| --- | --- | --- |
+| [#487](https://github.com/STAIxBWLB/agent-hub/pull/487) | `60e7f61fd9d6f3f0b15fe94d2baf69e32a504f97` | [39100633474](https://github.com/STAIxBWLB/agent-hub/actions/runs/39100633474) |
+| [#491](https://github.com/STAIxBWLB/agent-hub/pull/491) | `4af794fadfb00d3357c9e3e8011513bff4669f8e` | [39103534833](https://github.com/STAIxBWLB/agent-hub/actions/runs/39103534833) |
+| [#492](https://github.com/STAIxBWLB/agent-hub/pull/492) | `5895e3aa88a9b7f9f395680cb3818ba2ec942901` | [39105301256](https://github.com/STAIxBWLB/agent-hub/actions/runs/39105301256) |
+
+Each PR passed an OCR delegation review by Claude subagents at its final head, and its exact-head CI passed on both OSes with all four seeded shards. #491's macOS job hit the known 20 s `checks.test.ts` flake once; only that job was re-run, and it passed. These prior PR gates do not replace the release candidate's own exact-head CI.
+
+- Generated assets: `bun install --frozen-lockfile` and `bun run build` ran locally at `74899a40`. The only change to `plugins/agent-hub/server.js` and the plugin manifest is the version string 0.12.33 -> 0.12.34; the release PR's CI checks bundle freshness.
+- The release PR's own exact-head CI and the release workflow's tag checks are recorded on the PR and the tag, not here.

package/docs/verification/2026-10-18-0.12.35.md

@@ -0,0 +1,49 @@
+# 0.12.35 release verification
+
+This record covers release preparation and source review. It does not claim publication, installation, a running-hub restart or native/live acceptance.
+
+## Candidate
+
+Version 0.12.35, control protocol 16 (unchanged), from merged main `ac6ff4e382abcec45b5dffcc1fc85f402383dccf`. The person directed the release on 2026-10-18, first so that #493 takes effect, then to ship all open PRs once merged.
+
+- #493 (PR #495): a busy `ahub claude` session reads its queue with `hub_inbox`, sees fresh queued and important counts, and receives important messages mid-turn; `[FYI]` is forbidden for actionable messages.
+- #484 (PR #500): `status` carries roster membership, and `ahub jcode` and `ahub kimi --mode tui` read it; an older hub is unknown, not off.
+- #219 task (PR #499): the protected-segment grant test no longer grows with the set (test-only).
+- #450 I2 (PR #497): declared headless peer instances with their own native and MCP identity, worktree execution roots for extra implementers, kind routing across instances, and account-shared quota.
+- #481 S0+S8 (PR #496): the playbook lifecycle as the enabled default, gsd-lite retired into the `criteria` checklist, and a deprecation window until 0.13.0. Off keeps its #257 bytes.
+- Still open (unchanged): live native clients, installed managed-Pi #418 AC8 (#142), #438 AC7, the native console settings leg (#439 AC5), a real upgrade with reattach (#463), a real upgrade with a managed terminal and cancelled rows (#478), and the live advise cycle of #481 AC9.
+- New open legs:
+  - After installation, a busy `ahub claude` session reads its queue with `hub_inbox` and sees a steered important message before its turn ends (#493 D3, installed).
+  - A live run of two instances of one kind (#450 I4, #138).
+
+## Reviews
+
+| PR | Final head | Review | CI |
+| --- | --- | --- | --- |
+| #495 (#493) | 3730bf20 | planner plus an independent OCR pass | exact head, success |
+| #500 (#484) | b4a1bd6b | codex, approved | exact head, success |
+| #499 (#219) | a67fd222 | codex, approved | exact head, success |
+| #497 (#450 I2) | 254ba163 | two fresh-context reviews (round 1: changes requested, B1-B5); round-2 fresh review, approved; merge-delta review | exact head, success (macOS watchdog job rerun once) |
+| #496 (#481 S0+S8) | b1120f96 | codex: round 1 five P2s, round 2 one P1 (off-mode PII screen), round 3 approved | exact head, success (macOS #463 attach-timeout job rerun once; passes locally) |
+
+## Document review
+
+Round 1 checked 10 documents against #495, round 2 against #499 and #500, and round 3 13 stale documents against #497 and #496, read by a fresh-context reviewer and applied by the planner.
+
+| Document | Result | Checked claims and correction |
+| --- | --- | --- |
+| `README.md` | corrected (round 1) | Status 0.12.35; the Jcode entry sentence's version; the verification link. Nothing #497 or #496 invalidates. |
+| `docs/quickstart.md` | corrected | `v0.12.35` install. Upgrade paragraphs for #493 (session restart), #484, the #481 deprecation (`workflow`, the `phase` gate, `criteria` receipts) and #450 I2 instances. |
+| `docs/operations.md` | corrected (rounds 1 and 2) | Busy channel sessions; the Jcode roster read. The #497 instance and #496 lifecycle sections match the code. |
+| `docs/security.md` | corrected | `instances` is machine-local (read only from an untracked `config.local.json`) and refused from every surface; extras accept only `headless`. |
+| `docs/sdlc.md` | corrected | The off schema-1 export, and the `phase` tool schema of off or older daemons. |
+| `docs/specs/2026-09-19-agent-hub-design.md` | corrected | The #481 deprecation bullet: only `workflow = "gsd-lite"` and the `phase` gate warn; the `phase` receipt name is accepted silently. |
+| `docs/agent-notes/tasks.md` | corrected | `checklistOf` screening and off compatibility; instance id resolution and family fallback; owner isolation proof. |
+| `docs/agent-notes/budget.md` | corrected | Account-keyed quota, pause, checkpoint and handoff with per-member fanout; scope includes `instance-budget.ts`. |
+| `docs/agent-notes/daemon.md` | corrected | Startup-bound declarations, execution roots, instance recovery and undo; scope includes the instance modules. |
+| `docs/agent-notes/adapters.md` | corrected | Spawn identity per instance; an ACP kind only from the host declaration. |
+| `docs/agent-notes/local-worker.md` | corrected | Scope includes the sandbox root in `instance-execution.ts`; no rule changed. |
+| `docs/agent-notes/bus.md` | corrected (round 1) | Channel pull while busy; `WsPeer.steer` scope. No #497/#496 rule. |
+| `docs/agent-notes/tests.md`, `benchmarks.md`, `README.md` | unchanged | #497/#496 touched only shared paths; no rule is wrong. |
+
+`AGENTS.md` area notes and their `docs/verified.json` paths now list `instances.ts`, `instance-config.ts`, `instance-execution.ts` and `instance-budget.ts`. A separate manifest commit restamps the reviewed documents. The release PR must be merged with a merge commit so the stamps stay ancestors of the tag.