@staix/agent-hub 0.12.31 → 0.12.32

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

@@ -3056,3 +3056,207 @@ Evidence: `docs/verification/2026-10-17-418-probes.md`. The feasibility probe is
 - Cancellation releases overlap/reservation participation and sends each distinct former owner/reviewer one stop notice. Its trusted cancellation revision marker keeps that stop notice relevant; earlier notices for the cancelled task become moot under #434. The classifier never uses timestamps alone to identify the stop notice. Dependents keep waiting and receive the cancelled-dependency cause. List, show, explain, dashboard and release projections treat cancellation as closed, retaining the current privacy screen and distinguishing cancellation from successful approval.
 - The daemon advertises `task_cancel` in hello and status features. Current clients refuse cancellation without that feature. Upgrade and restart persist the verified target's exported features with its immutable root/digest before prepare, including cached targets, and reuse that receipt on resume after verifying the same bytes. A legacy staged receipt without feature evidence is probed only while a project is not yet past commit; fully committed projects do not require another probe. This preserves #215: a transient probe failure cannot refuse a target that was already staged with verified evidence. Preflight checks only uncommitted sources and refuses a target lacking `task_cancel` while cancelled rows exist. Source prepare/commit recheck before holds/snapshots and around asynchronous work; cancellation cannot write through recovery preparation. Refusals name task ids and never rewrite rows. An older binary started manually can misclassify cancelled rows as open or fail to move them; this is the explicit unsupported compatibility ceiling. Never map cancellation to approval.
 - The post-release live step remains separate: do not cancel the historical task or enable the project's sweep from implementation tests. AC7 needs installed-runtime receipts.
+
+## Amendment: live configuration reload (issue #439)
+
+The daemon validates one captured candidate containing config.json, config.local.json,
+routing.toml and routing.local.toml before applying any part of it. Missing files use
+existing defaults; unreadable, malformed, unknown or invalid configuration refuses the
+whole candidate. The accepted routing snapshot remains authoritative until another
+complete candidate succeeds; last-good parser fallbacks never authorize a reload.
+Settings writes, undo, explicit `ahub settings reload`, dashboard reload and debounced
+file changes share this path. One invalid candidate produces one bounded notice naming
+the file/key and validation error, without echoing configuration values.
+
+Every setting and configuration block has one apply class. Leaf rules override block
+rules. `live` changes future decisions immediately; `next use` changes the next task,
+request, batch or peer start; `restart` retains the running value and reports its key
+and reason. The registry exposes the running and file values separately.
+
+| Apply class | Configuration |
+|---|---|
+| live | runtime permission choices, authorized roster changes, roles/planner/conductor, instruction-file protection, approvals.notify, research.enabled, snapshots.enabled/keep, task_sweep, tasks.wip_limits, capabilities, routing classes/stay_switch/signals/constraints/hub_routes/max_switch_prefill_tokens |
+| next use | permission_modes and catalog_roles at the next peer start; peers.*.start_mode and native launch argv; coordination for newly created tasks; task release/review policy; new approval timeouts; bus batch/admission limits; budget/context/inference/limits; peer watchdog and step limits; recovery and experiment decisions; memory brief/injection/suggestion limits |
+| next use | pi.auto_start changes a later startup/recovery auto-start decision; reloading it never starts or replaces a running peer |
+| restart | memory.enabled/native/worker_url/short_ttl_days/sync_interval_min: open consumers, selected profile binding, client and sync timer must be quiesced together |
+| next use | routing targets/routes/local selection at the next local peer or sidecar creation; existing native sessions retain their model contract |
+| restart | pi.dgx_coding/dgx_fast and routing.pi: model catalogue and context publication belong to the existing Pi relay; a reload must not replace a live native relay |
+| restart | omniroute: credential and gateway clients are bound to relay ownership |
+| restart | mlx: model/runtime ownership and device resources belong to the running instance |
+| restart | checks: bounded runner and completion-check execution contracts are constructed together |
+| restart | pii, data and local deny/read/network policy: existing native sessions and generated sandbox/proxy contracts must not acquire a different trust boundary mid-session |
+| restart | profile/profile_overrides and text_projection: session tool schemas, role/profile contracts and converter/cache ownership are bound at startup |
+| restart | terminal.open: the terminal provider is supplied by the daemon lifecycle |
+| restart | bench.enabled: the benchmark execution environment is selected before work starts |
+
+Listener ports and the state directory are startup options rather than editable
+settings; their already-bound sockets and state ownership require a new daemon.
+Changing the external memory selector likewise requires the existing quiesce/reopen
+lifecycle and is never a hot reload or automatic migration.
+
+Trust is checked against the actual source files and their last accepted raw layers,
+not against a scratch project's Git status. Effective guarded changes are also
+checked when unchanged raw declarations acquire different Git provenance. A
+settings ticket never authorizes command/policy fields outside the editable registry.
+Changed MACHINE_LOCAL values and raising
+registry values are refused from tracked or unverifiable files. Ordinary dashboard
+and watcher authority cannot adopt a raise hidden in an unrelated local edit. A
+settings session or terminal may adopt an untracked value within its existing
+settings authority; neither bypasses the tracked-file rule or the never-ask and
+roster confirmation/lifecycle fences. Runtime permission mutation still uses
+permissionChange/changePermission exclusively.
+
+A sweep reload validates its next-pass policy and reschedules its timer without
+changing a pass already in progress. Bus scheduling changes retain queued originals,
+prefaces, manual pauses, recovery holds and inflight delivery. Coordination preference
+is pinned when a task is created (including split children); changing it neither
+retroactively silences an existing task nor lifts an existing silent cohort. Current
+PII and capability fences remain authoritative. Snapshot enablement applies to a
+later turn; a running turn retains its capture decision and is never stopped.
+
+The console's sixth Settings tab reads the same registry as the dashboard. It edits
+through the authenticated daemon client: value, preview, nonempty bounded reason,
+then explicit y; undo also previews and confirms. Stale preview replies cannot arm a
+write, and pasted confirmation text never executes one. The daemon accepts additive
+settings_reload and undo-preview requests only from console roles. The dashboard's
+setting_reload action uses its existing authenticated session; manager forwarding
+has ordinary authority. No client writes configuration files directly. Pending
+restart keys and reasons appear in status, console and dashboard. These requests and
+optional projections are additive; older daemons refuse unknown requests and the
+control protocol remains 16.
+
+### Reload authority and publication scope (#439 review amendment)
+
+Malformed syntax, unknown keys and invalid values still refuse the complete candidate
+before any publication. A valid but unauthorized key is different: retain that key's
+accepted value, report its name and reason, and continue applying independently
+eligible changes. A refused key never wedges an unrelated setting write.
+
+An individual setting write or undo publishes only its named registry path. Its
+preview and confirmation do not authorize other edits in either config file or either
+routing file. This includes catalog guidance: only the named peer is prepared (#295).
+Unapplied edits remain pending for a later explicit reload; accepting another key must
+not acknowledge them in the accepted source baseline.
+
+Privacy tightening is automatic from tracked or untracked files: enabling local PII
+constraints/screening, adding PII patterns, removing nonholder role memberships and narrowing an explicit capability list cannot
+be mistaken for a raise. Deleting a restricted capability entry restores the default of all capabilities and is a guarded widening. Roster membership changes always use their named confirmation and peer lifecycle, even when removing a peer; generic reload never bypasses those steps. Registered floors and known semantic reductions in admission
+or permission likewise remain available without authorizing a wider policy. Other
+agent-relevant policy, including limits, supervision feed, inference, review and crash
+resume, receives a per-key authority check even outside the settings registry.
+
+`ahub settings reload` is the explicit adoption path for guarded file edits. The daemon
+first returns the exact guarded keys and a confirmation token bound to the candidate
+bytes and accepted configuration revision. The person reviews that list and confirms
+from an interactive terminal; only then may the same candidate be adopted. Changed
+bytes or accepted state invalidate the token. An ordinary watcher or dashboard never
+confirms a raise; a settings session remains restricted to registry keys. Tracked or
+unverifiable MACHINE_LOCAL command and credential declarations cannot become trusted
+through confirmation. Refusal notices name each key and say to review and run
+`ahub settings reload` or revert the file; tracked machine-local declarations also
+require moving the declaration to an untracked machine-local source.
+
+Coordination pinning is local to a daemon lifetime. A setting reload preserves each
+existing task's captured mode and existing cohort silence; a daemon restart re-pins
+retained task rows to the startup mode. This is an explicit compatibility ceiling,
+not durable task metadata or a migration.
+
+Inheritance and undo use the actual destination source trust. They may restore an unchanged effective startup value after explicit consent, but a shadowed edit that was never authorized is not an accepted fallback. New lower-layer raises remain refused even when an unchanged local overlay previously hid them.
+
+Reserved prototype path components are refused throughout nested routing extension tables before publication. Configuration path writes never traverse inherited object properties.
+
+Switchyard targets/routes and hub-route dictionaries retain opaque quoted keys, including dots. Each dictionary is one guarded value for reload confirmation and publication; privacy fields and ordinary registry settings retain leaf-level decisions.
+
+### Settled authority and reviewable confirmation (#439 round-2 amendment)
+
+A role-list subset is automatic only when the settled planner and conductor holder
+sets stay unchanged. Removing the last explicit planner can hand that authority to
+the automatic fallback; removing a settled holder therefore requires guarded
+confirmation even though the raw role list shrinks. The same pure role resolver
+serves publication and the authority comparison.
+
+The console preview shows a complete bounded before -> after value for every guarded
+key, including full executable argv, and describes any settled holder change. Values
+stay out of notices and events. A value that cannot fit the review budget is retained
+with an actionable rejection, never silently truncated and authorized. Each before
+or after representation is at most 16 KiB, an effect description at most 2 KiB, and
+the complete confirmation at most 128 KiB.
+
+The confirmation token proves candidate/state freshness. It does not independently
+prove a person's presence: console-role authority is the existing server trust
+boundary, while the CLI enforces interactive TTY, explicit y and the deadline.
+The roster exact-key mutation guard observes admission while teardown is held,
+before reload can repair a wrong whole-roster assignment. The roster authority seed
+covers the dashboard authority boundary; its separate leaf check is defence in depth.
+
+Console undo binds its confirmation to the previewed setting key and the SHA-256
+of the exact undo record. A changed or missing record refuses without writing;
+same-key replacement also invalidates the preview. These optional request fields
+preserve protocol 16 for older direct CLI clients. The Settings panel never forces
+a busy roster removal: it names `ahub roster remove <peer> --now` and the active-turn
+stop/detach consequence so the person can make that choice explicitly in the CLI.
+
+
+### Adapter registry A1 (#451)
+
+A1 introduces API 1 definitions for the seven existing kinds and separates a peer
+id from its adapter kind through `kindOf`, `definitionOf` and `familyOf`. With no
+instance declarations, only builtin ids resolve. A suffix is never guessed. This
+phase does not enable instance configuration, account changes or new native modes.
+Existing external-client admission and lazy roster behaviour remain unchanged.
+
+Qwen is the first migrated ACP kind. Its definition owns the existing headless
+launch/factory, exact 0.25.0 identity, permission-mode mapping and session rules.
+The direct `AcpPeer` `qwen025` option and public helper exports remain compatible;
+legacy benchmark ACP without that flag stays unmanaged. Other kinds retain their
+existing runtime paths until A2; their registry metadata is not proof of a running
+or authenticated native client.
+Unmigrated definitions delegate launch plans to the existing CLI and keep existing
+runtime permission handlers authoritative. Claude, Pi and local keep empty partial
+native-mode maps where API 1 cannot express their scoped write/edit hooks; this is
+an A1 compatibility ceiling, not an unmanaged policy or a refusal. A2 must migrate
+those handlers and their representation before interpreting a missing mapping.
+Display-only permission grants remain exact copies of the existing explanations.
+The bounded Qwen doctor CLI-version probe and its 0.25.0 pin remain unchanged in
+the transitional guard baseline. A2 moves all version probes together and amends
+`VersionContext` once; A1 adds no observed-version input or native readiness claim.
+The native Kimi mode-id constant moves to a dependency-free leaf while its public
+re-export remains intact, so either registry-first or definition-first imports work.
+
+Two additive fields complete source inputs omitted from the A0 type sketch:
+
+- `LaunchContext.nativeCommand?: readonly string[]` carries the already-validated
+  native argv, including wrapper arguments. Only core config or the existing
+  redacted preview supplies it; definitions never load daemon config or recover
+  commands from environment text. Model tool schemas do not expose this field.
+- `permission.grants?: Partial<Record<PermissionMode, string>>` carries existing
+  operator explanations as static data. It changes no approval decision, scope or
+  native mode. The frozen `CreateContext` and transport-specific options stay intact.
+
+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
+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
+Qwen-capable target appear unsupported.
+
+The reviewed inventory distinguishes the historical grep from AST nodes: at
+`71253098`, the same AST scanner counts 364 sites in 142 groups (222 comparisons,
+19 closed-list imports, 123 vendor literals). At A1's main base `4bcf62fa`, it counts
+395 in 156 groups. The first A1 snapshot has 382 in 155 groups: thirteen Qwen/raw
+watch comparisons are removed, and the seven-entry role object becomes a
+seven-entry legacy-order list whose role values come from the registry. No raw
+Qwen comparison remains outside the native definitions. The initial baseline is
+reviewed data, never regenerated by the test; changes brought by a newer main
+must be reconciled explicitly before this first baseline ships.
+
+Before the first A1 review, main `b9efa131` merged #463. Its recovery guidance and
+reattach logic add 33 sites in 16 groups, with 19 changed baseline entries. The
+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.

package/docs/specs/2026-09-20-upgrade-recovery-design.md

@@ -514,6 +514,7 @@ Cells show action -> next receipt status. Fresh-session eligibility is marked fr
 | Target stopped or changed | block -> unchanged |
 | Running target, other session not allowed | block -> unchanged |
 | Absent receipt | unstarted; initial launch is handled by the runtime outside this receipt table |
+| Done, running target, no attached session, gone launchers and positively gone saved terminal (#463 supplemental evidence) | reattach -> failed; one recorded-session repair, no fresh-session choice |
 
 Running target, no attached session (either allowOther value):
 
@@ -658,3 +659,193 @@ front end to the commands above, never a second coordinator.
 - Out of scope: a hub-side interrupt of a running turn (the running source may
   be older and would not know the request), and answering approvals from the
   screens.
+
+
+### Post-restore detachment and recorded-session reattachment (#463)
+
+A done restore receipt remains done for an offline peer unless both independent
+proofs hold on the same running target instance: every relevant launcher is gone,
+including older target instances, and the exact saved terminal is positively
+orphaned or missing. Disconnection alone, an unreadable or truncated inventory,
+unknown launch records, changed terminal identity and a different attached session
+never authorize a replacement.
+
+The pure restore table has one additional rule: done + running target + no attached
+session + gone launchers + positively gone saved terminal proposes reattach ->
+failed. The original 540 cells with no new evidence remain unchanged. Before
+returning the block, the runtime saves a per-project, per-peer reattachment marker
+with the accepted done binding, detection time, fixed cause `detached after restore`
+and state `ready`, plus the failed restore receipt and `started` project phase.
+The blocked operation identifies that project and peer structurally, never by
+parsing error text.
+
+Resume reuses the ordinary restore path with that accepted conversation, session
+file, backend and model. Before any new terminal effect the marker becomes
+`attempted`. Chosen waiting bindings remain durable and reuse the existing 600 s
+attachment bound; an interruption cannot grant another create. A second detach or
+an exhausted attempt blocks with its recorded cause. These repairs default to
+recorded-session-only continuity: no automatic fresh/zero-turn replacement is
+introduced. Only the explicit missing-history exception below permits a person
+to select a replacement. Strict session/file checks remain for repairs;
+ordinary verified-empty Pi attachments retain their pre-existing id-only rules.
+When `recordRestart` retires a known done or waiting binding from a dead target,
+it clears that binding's repair fence. The normal #225 relaunch preserves its
+accepted conversation and a new target gets its own repair allowance. The additive
+per-peer `repairedSessions: true` provenance survives this fence reset and repeated
+restarts. It authorizes no creation: accepted done/retired bindings remain the
+session source, and fresh-session choices and zero-turn substitutions remain
+excluded automatically for that repaired conversation. A person may explicitly
+choose `dispose --fresh-session` for a failed repaired Codex or Claude conversation only after
+the coordinator records a typed positive missing-transcript/rollout observation
+bound to the accepted session, and disposal rechecks that same recorded store as
+missing before writing the loss and audit. Found, unreadable, malformed or absent
+evidence never permits this choice. The choice records the accepted conversation
+as lost; it does not run a terminal. The receipt also records
+`freshOverride {peer, evidence, checked, at}`, exposed in person status and the
+archive summary. New missing observations and overrides include `checkedPath`: the
+exact Claude transcript file or recursively searched Codex sessions directory.
+The lookup and display share the same captured-environment/default-home path
+resolver; this is evidence of that checked location, not proof of every native
+store layout. Refusals name the checked location as well. Resume retains the existing launcher fences,
+close-before-create and waiver rules. An uncertain
+creation with no durable selected binding does not gain a second creation by
+merely losing the target. Database contention retains its typed retryable outcome.
+
+Repaired missing-history disposal is never delegated under `--live-test`.
+Because ordinary #408 fresh disposal uses the same argv and remains delegable,
+the CLI first classifies the already-loaded receipt read-only. An unreadable,
+unparseable or unclassifiable receipt, including a peer absent from its projects,
+refuses delegation. A repaired override is refused before runner/lock acquisition
+or coordinator mutation. Core repeats the trusted per-invocation delegation
+check before the lock and after its under-claim read. No model/request field
+can grant person authority, and no new public waiver flag is introduced.
+
+Pi remains excluded from fresh-session under #215. For a positively missing
+accepted Pi session file, blocked guidance prints the operation's
+`recovery dispose <id> --stop-and-archive --reason <text>` command and then
+`ahub --project <root> pi`. The normal Pi start retires a proven-unresumable
+archived bookmark without falling back fresh in that same start; its notice
+guides a subsequent normal start. The Pi fresh-session refusal itself prints
+the same stop-and-archive and project-scoped start commands. Unreadable or invalid
+evidence stays held.
+
+The person-only `ahub recovery reattach <operation> <peer>` is admitted only for
+that operation's current structured reattachment block. It claims the existing
+runner fence, rechecks the held target and restores only the selected peer. It
+accepts no session override, performs no release or installation, and leaves the
+remaining operation for resume. Agent shells and live-test delegation cannot
+invoke this person decision. Person status and block guidance list the recorded
+Codex thread, Pi session file and Claude session with quoted commands from the
+operation's coordinator.
+
+Status guidance, the archive summary and the Pi continuity bookmark share one
+accepted-binding resolver: restored done/waiting, then a validated reattachment
+marker, then a decoded retired binding for this peer and project, then the plan.
+A malformed retained binding is unavailable, never permission to fall back to an
+older conversation. This includes the accepted Pi file, backend and model after
+a #225 target restart.
+
+Stop and archive retains the operation's accepted session identities. After a
+confirmed owned target stop and snapshot archive, it may write one private,
+project-bound Pi continuity bookmark. The next normal `pi.auto_start` passes that
+recorded identity through the existing start-mode and lifecycle path; it never
+falls back fresh because a bookmark is invalid or unreadable. The bookmark is
+consumed only after authenticated attachment proves the same session and file,
+not merely after opening a terminal. Atomic compare/consume cannot remove a newer
+operation's bookmark. No global operation-directory scan or native probe is used
+to discover sessions. The person summary distinguishes historical target startup,
+plugin installation and the remaining global CLI installation, and continues to
+say abandoned, not completed or rolled back.
+
+A missing, expired, unreadable or foreign snapshot prevents a continuity bookmark,
+not stop-and-archive itself. Disposal records a per-project continuity warning and
+still releases its machine lock. An actual rename failure of this operation's own
+snapshot retains the existing failure and retry path. Optional bookmark storage
+failure is recorded as unavailable rather than blocking this last-resort exit.
+
+A valid bookmark is archived with a structured reason under its exact CAS when a
+different authenticated Pi session becomes the saved crash record, its recorded
+session is proven unresumable, or a later recovery successfully releases the
+project. Unknown I/O or provider failures do not prove an unresumable session.
+Malformed or unverifiable bookmark evidence remains fail-closed. The TUI resume
+argv carries `--session-file` when available, otherwise `--session-id`, never both.
+
+### Continuity retirement follow-up (#463)
+
+An externally retired or replaced bookmark invalidates the daemon's cached copy.
+A failed compare-and-swap re-reads the private bookmark; absence drops the old
+in-memory selection, while newer or unreadable evidence remains distinct from
+absence. Session recording writes `sessions.json` only when its serialized peers
+change. Settlement may use an already durable unchanged crash record but may not
+retire continuity before that record was successfully written. No offline-Pi event
+forces a redundant write. A header whose session id disagrees with the selected
+bookmark is `bookmark_mismatch` (bookmark inconsistent), not evidence that the
+session itself cannot resume. Archival remains non-destructive and never starts
+a fresh session.
+
+Repeated Pi continuity settlement storage failures back off for 30 seconds for
+the same bookmark digest and authenticated peer generation/metadata. A new
+digest or authenticated identity can retry immediately; successful settlement
+clears the failure. An unchanged failure logs once, without session-file churn.
+
+## Recovery presentation (#466)
+
+Interactive upgrade and recovery screens reuse the console's Span tones, paint,
+measured wrapping and resolveColor precedence. Auto uses TTY and environment
+rules; explicit always has exactly the console's behaviour, including on a pipe.
+Default and never retain existing piped, dry-run, status and dispose JSON bytes.
+Raw JSON, including [j] and --json, bypasses paint and width handling. Human plan,
+progress, error, menu and summary lines fit the measured terminal width.
+The #272 simulated-TTY golden moves to this #466 presentation contract; its
+restart identity, board and non-TTY byte assertions remain unchanged.
+
+Only nextChoices supplies operation actions. Presentation may annotate a choice
+as recommended or disabled, but cannot create an action, bypass a refusal or run
+a driver. Enter defaults only to a read-only action; applying, resuming or
+reattaching requires the explicit action key. Preserve the full human wait
+condition from nextChoices, replacing only its retained status command in normal
+output. Existing commands through io.run remain the only mutation path. A
+destructive choice names its stop/abandon consequence before confirmation. Resume
+really runs stage again, labelled "checking retained release"; the screen reports
+only work observed on that attempt and keeps internal coordinator paths verbose.
+
+Operation receipts may add read-only wait timing metadata with ISO waitStartedAt,
+deadlineAt and waitEndedAt values. The coordinator records them at the actual
+prepare and awaitAttachment wait boundaries. They do not set or extend any
+deadline, change controls, alter the 540-cell transition oracle or its supplemental
+matrix, or turn unknown evidence into a decision. Older receipts say "timing
+unknown"; updatedAt is never substituted for the actual wait start.
+Each new runner attempt clears the previous timing projection before observing
+its own waits, so a resumed step cannot display a previous wait as current.
+
+Preservation errors carry a typed cause from the exact queue, manual-pause,
+task-board and budget integrity comparisons. What/Why/What-to-do is rendered from
+that cause and recorded recovery guidance, never inferred by parsing a combined
+error string. A read-only end-inspection port may supply current runtime state to
+the human summary; a failed readback is unknown. Summary rendering performs no
+lifecycle action and distinguishes recorded installation effects from current
+runtime observations. Older readers ignore the optional presentation metadata.
+
+Current native terminal, session, launcher, target and attachment-timeout guards
+may record a closed presentation cause containing only the actual IDs, states
+and wait window observed at that guard. A repair wrapper retains only a proven
+inner presentation error. Generic errors and lookalike objects remain untyped;
+their messages are never classification input. This metadata changes no guard,
+error message, restoration receipt transition or permission to create a terminal.
+
+Presentation timing writes are best-effort observations: retain their in-memory
+values, log a fixed warning on a metadata write failure and continue. Ordinary
+receipt/effect writes remain authoritative and fail normally. A newly observed
+blocked or completed step with no measured start has unknown elapsed time, never
+an invented zero. Waiting prints on a changed condition plus at most one elapsed
+tick per minute. Screen-owned recovery children keep stdout quiet on capable
+coordinators so the parent alone renders progress and outcome. All external
+renderer values containing line breaks or controls are visibly quoted before
+wrapping; they cannot become new column-zero guidance. Colour flags follow the
+console grammar exactly: a single `--color=<mode>`, never a bare or repeated flag.
+
+Recovery authorization and the presentation parser share the pure
+`recoveryPresentationFlag` classifier. Authorization identifies the action after
+skipping the accepted one-shot presentation flags (`--json`, `--verbose`, `--color=<mode>`). Such flags never hide
+person-only reattachment from agent or live-test refusal checks; normalization
+confers no authority and unknown flags still fail the command parser.

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

@@ -0,0 +1,54 @@
+# 0.12.32 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.32, control protocol 16 (`src/hub/control-client.ts`), from merged main `2b2d6d2d67d3ed54a94fab19b5745e20a779b7d5`. The candidate includes all 9 PRs merged since `v0.12.31`: #465, #467, #468, #470, #471, #472, #473, #474 and #475. The exact first-party memory pin remains `@staix/agent-mem` 0.3.1.
+
+- The upgrade runs with the target release's own coordinator (`bunx --package @staix/agent-hub@0.12.32 ahub upgrade`), so an upgrade into 0.12.32 already uses the #463 reattach and continuity changes and the #466 screens.
+- #439 live settings reload ships with per-key trust: a write or undo publishes only its own key, guarded or machine-local file edits are adopted only by a confirmed terminal `ahub settings reload`, and a change of the settled planner or conductor holders is guarded. The native real-terminal console leg (#439 AC5) is not verified here.
+- #451 A1 (adapter registry) is a refactor with no intended behaviour change; the registry guard baseline is 415 sites in 171 groups at the candidate.
+- agent-mem main contains the curated shard migration (agent-mem#15 T2), which is not released. agent-hub still opens memory through `new MemoryStore()` (`src/hub/memory-profile.ts`); task #175 must land before any agent-mem release that ships T2, and the person must not run `amem migrate --shards` before then.
+- Still open: a real Orca upgrade exercising `ahub recovery reattach` (#463), installed managed-Pi #418 AC8 (#142) and #438 AC7.
+
+## Document review
+
+The initial `node scripts/check-docs.mjs --require-fresh` reported 13 stale documents. Each was compared against its covered source changes from its prior stamp through the candidate, then against the release metadata. Symbols and limits were checked in the source, not inferred from commit messages. No document review is deferred. The models note was already fresh and keeps its stamp.
+
+| Document | Prior source stamp | Review result | Checked claims and correction |
+| --- | --- | --- | --- |
+| `README.md` | `6637a383c3f46ae173b14268d29c8b0d306eac95` | corrected | Status 0.12.32 and protocol 16; the Jcode MCP refresh is scoped to upgrades from 0.12.30 or earlier (`src/cli/jcode-mcp.ts` last changed in 0.12.31); live settings reload; the unreleased shard migration warning; the verification link and open legs. |
+| `docs/quickstart.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | `v0.12.32` examples, the target coordinator and `ahub recovery reattach`, `ahub settings reload` in the working-day table, and the dashboard reload button. |
+| `docs/security.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | Memory pin 0.3.1; the Pi continuity bookmark record; dashboard reload and ordinary-session floors; reload trust (watched files, per-key provenance, automatic privacy tightening, confirmed terminal reload only); live-test refusals for reattach and the repaired fresh-session dispose. |
+| `docs/operations.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | 0.12.32 header and upgrade examples, protocol 16 covering 0.12.20 through 0.12.32, the console Settings panel, the ordinary dashboard settings authority, the repaired-session fresh dispose and the Pi bookmark. |
+| `docs/agent-notes/README.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | unchanged | Console tab 6 and the settings editor do not affect the exact-row navigation rule; the cited tests and verification file exist. |
+| `docs/agent-notes/adapters.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | `KIMI_MODE_IDS` location; a reloaded permission default only through `applyPendingPermissionDefault`; adding a native peer through an `AdapterDefinition`; the registry guard baseline only shrinks; watchdog reload; typed Pi session failures. |
+| `docs/agent-notes/benchmarks.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | unchanged | The covered changes only move Qwen identity and mode ids into definitions and add Pi session error classes; the benchmark rules still match. |
+| `docs/agent-notes/budget.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | unchanged | The budget, statusline, journal, restart and context-window sources are unchanged; the bus and daemon changes do not touch budget rules. |
+| `docs/agent-notes/bus.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | Reloaded batching and queue limits only through `Bus.configureScheduling`, affecting later batching and admission only. |
+| `docs/agent-notes/daemon.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | `reloadConfig` as the only publication path with scoped writes, per-key trust, guarded holder changes, the reload token and undo identity; the Pi bookmark exception scoped to `pi.auto_start`; `reattachRecovery`; the #466 presentation rules. Four new source files added to its scope. |
+| `docs/agent-notes/local-worker.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected (ASCII only) | One existing em-dash replaced; the sandbox, path and permission rules are unchanged. |
+| `docs/agent-notes/tasks.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | `resolveSettledRoles`; the coordination mode captured per task at creation, cohorts within one mode, and the restart re-pin; `src/hub/settled-roles.ts` added to its scope. |
+| `docs/agent-notes/tests.md` | `56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c` | corrected | The registry guard scans `src/` against the committed baseline, and no test writes or regenerates it. |
+
+`AGENTS.md` area notes and `docs/verified.json` paths now include `src/hub/config-reload.ts`, `src/hub/config-apply.ts`, `src/hub/recovery-continuity.ts` and `src/cli/recovery-presentation-options.ts` (daemon) and `src/hub/settled-roles.ts` (tasks). 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
+
+GitHub readback found a successful `check.yml` run at each PR's final head. Both OS check jobs, all four seeded shards and the `seeded guards` aggregate succeeded for every row. These prior PR gates do not replace the release candidate's own exact-head CI.
+
+| PR | Final head | CI run |
+| --- | --- | --- |
+| [#465](https://github.com/STAIxBWLB/agent-hub/pull/465) | `fcb27ca4af74bef6b264af9bf9f3e0490a824971` | [39025787130](https://github.com/STAIxBWLB/agent-hub/actions/runs/39025787130) |
+| [#467](https://github.com/STAIxBWLB/agent-hub/pull/467) | `94a52afb4638e687049c13ef0c27dc4a66483355` | [39027067759](https://github.com/STAIxBWLB/agent-hub/actions/runs/39027067759) |
+| [#468](https://github.com/STAIxBWLB/agent-hub/pull/468) | `de30d9e3518da40546a900d3e0940dc882179e6d` | [39028179223](https://github.com/STAIxBWLB/agent-hub/actions/runs/39028179223) |
+| [#470](https://github.com/STAIxBWLB/agent-hub/pull/470) | `17c593b7e04ee82f789525552b8b6e0f922d8c8f` | [39039356493](https://github.com/STAIxBWLB/agent-hub/actions/runs/39039356493) |
+| [#471](https://github.com/STAIxBWLB/agent-hub/pull/471) | `04f55cd942533e7b49c00f5e2d941e42e448fbd5` | [39046673325](https://github.com/STAIxBWLB/agent-hub/actions/runs/39046673325) |
+| [#472](https://github.com/STAIxBWLB/agent-hub/pull/472) | `e214fc9ec7306e88b9906ff3847fdda4f3227785` | [39049995436](https://github.com/STAIxBWLB/agent-hub/actions/runs/39049995436) |
+| [#473](https://github.com/STAIxBWLB/agent-hub/pull/473) | `11fe040e500bf65d3e9c38792a2e05f5fd338bae` | [39056391496](https://github.com/STAIxBWLB/agent-hub/actions/runs/39056391496) |
+| [#474](https://github.com/STAIxBWLB/agent-hub/pull/474) | `cfcd087452e8afe7215039168cbd535ef8088765` | [39063863001](https://github.com/STAIxBWLB/agent-hub/actions/runs/39063863001) |
+| [#475](https://github.com/STAIxBWLB/agent-hub/pull/475) | `1abbaebe235ccfd4ea30ee2c6961ad55f51aec3a` | [39066256392](https://github.com/STAIxBWLB/agent-hub/actions/runs/39066256392) |
+
+- Generated assets: `bun install --frozen-lockfile` and `bun run build` ran locally at `6883f4d8`. The only change to `plugins/agent-hub/server.js` and the plugin manifest is the version string 0.12.31 -> 0.12.32; 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/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "6637a383c3f46ae173b14268d29c8b0d306eac95",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -62,7 +62,7 @@
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -74,7 +74,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -86,7 +86,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -98,7 +98,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -131,11 +131,15 @@
         "src/hub/start-mode.ts",
         "src/hub/terminal-open.ts",
         "src/hub/recovery-error.ts",
-        "src/hub/db-timeout.ts"
+        "src/hub/db-timeout.ts",
+        "src/hub/config-reload.ts",
+        "src/hub/config-apply.ts",
+        "src/hub/recovery-continuity.ts",
+        "src/cli/recovery-presentation-options.ts"
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
@@ -155,7 +159,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -168,11 +172,12 @@
         "src/hub/conductor.ts",
         "src/hub/supervision.ts",
         "src/hub/tool-refusal.ts",
-        "src/hub/daemon.ts"
+        "src/hub/daemon.ts",
+        "src/hub/settled-roles.ts"
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -191,7 +196,7 @@
       ]
     },
     "docs/agent-notes/README.md": {
-      "verifiedAgainst": "56ae16dfd69d3c72bcc1f4efdabbda1905f75b9c",
+      "verifiedAgainst": "cf3026feab218207f0c21b300552eada0d5be227",
       "paths": [
         "src/cli/console-state.ts",
         "src/cli/attention.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.31",
+  "version": "0.12.32",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "bun": ">=1.4.2"
   },
   "dependencies": {
-    "@staix/agent-mem": "0.3.0"
+    "@staix/agent-mem": "0.3.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.31",
+  "version": "0.12.32",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",