@staix/agent-hub 0.12.27 → 0.12.29

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the previous repository, archived on 2026-09-30 when this repository's history was rewritten; the one exception is the open smoke-check issue, formerly #12, which moved here as #1. Numbers in newer entries refer to this repository.
 
+## 0.12.29
+
+- Let an explicitly authorized agent run live verification through `ahub --live-test`, with operational console authority scoped to the invocation and its ahub continuations, the initiating peer retained in a mandatory delegation audit, and ordinary agent permissions unchanged (#408).
+
+- Remove the site caveat card accent edge and refresh the #273 live-verification ledger, including the machine-wide upgrade isolation requirements (#406, #273).
+
+## 0.12.28
+
+- Recover an offline Pi owner with person-selected preserved history via `ahub pi --replace-session --session-file`, retaining prior identity metadata and queued work while refusing live owners and unsettled effects (#403).
+
+- Tell a pull-only session (a Kimi TUI, a Claude session without pushes) that important messages are waiting: the hub sends an advisory count over its control link and every hub tool result but `hub_inbox` ends with it until a read drains them; `hub_inbox` replies also carry the important count. Make `scripts/check.sh` take a heavy-job slot shared by every worktree of the repo, so a second gate waits (bounded by `AHUB_CHECK_LOCK_WAIT_S`) and names the holder instead of overlapping (#398).
+
 ## 0.12.27
 
 - Refine the dashboard Office view with an intrinsic 12 px/unit scale, 1 px non-scaling hairlines and padded room cards in flat and isometric themes, and un-nest the desk More control into a separately reconciled sibling button so screen readers can reach it (#394).

package/README.md

@@ -4,7 +4,7 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 hub-owned local-LLM worker, with optional Qwen Code and Jcode support, collaborate as peers in independent project directories, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.12.27, control protocol 16. Durable delivery records distinguish queued
+Status: 0.12.29, control protocol 16. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -33,7 +33,7 @@ cd <your project> && ahub init && ahub up
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.27 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.12.29 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -81,7 +81,7 @@ an N-peer message bus and attaches each agent through its native control surface
 | --- | --- | --- | --- |
 | Claude Code | channel plugin push (`notifications/claude/channel`) under `ahub claude`; otherwise tools-only, read with `hub_inbox` | MCP tools | queued by Claude Code, grouped on next turn; tools-only: queued at the hub |
 | Codex | app-server `turn/start` (idle) / `turn/steer` (busy) | proxy intercepts `item/agentMessage` | steer or queue |
-| Kimi Code | ACP `session/prompt` | ACP `session/update` stream | queue (`turn.agent_busy`) |
+| Kimi Code | TUI: pull with `hub_inbox`; headless: ACP `session/prompt` | TUI: `hub_send`; headless: ACP `session/update` stream | TUI: hub queue with important-count hints; headless: queue (`turn.agent_busy`) |
 | Pi | RPC or managed native TUI extension | hub-approved tools | queued until `agent_settled` |
 | Local worker | hub-native agent loop | hub-native | hub-owned |
 

package/docs/agent-notes/bus.md

@@ -14,6 +14,7 @@ Scope: delivery, digests and condensation, reply addressing, priority and limits
 - A reply is addressed, never broadcast. An adapter that answers a delivery passes `to: replyAudience(envs)`; anything else with an `inReplyTo` inherits that envelope's sender. Leaving `to` empty fans the message out to every peer.
 - `digest` is not a peer: addressing a reply at the envelopes the peer was handed sends it nowhere once a delivery was condensed. The bus resolves `digest` back through `lastDelivery.originals`; anything else that reads a reply's `to` has to do the same.
 - A pull-only peer (a Claude session without channel pushes or Kimi in its own TUI) is never drained; `Bus.pull` hands it what one push would take. Drain and pull share `held()` (recovery, an uncertain delivery, any pause, the lifecycle `deliveryHeld` fence) and `remember()` (so `reply_to` resolves), and a drain rechecks `deliverable()` after condensing because such a session can take the peer meanwhile. A pull is journaled `completed` in the same transaction as the bus snapshot, never `accepted`; a failed one puts back only that peer's queue and preface and never reloads the snapshot.
+- The `onImportantQueued` nudge for a pull-only peer (#398) is advisory: it never dequeues, steers, journals or settles, and a throw from it never stops an enqueue.
 - `resolveDelivery` mutates queues in place; a refused or failed resolution puts back only that peer's queue and preface and keeps every pause. Never reload a snapshot on a live bus.
 - `restore` takes queued work from the journal, never from the committed snapshot once the journal has state (an empty journal, revision 0, is seeded from the commit): from the commit only an empty queue key is carried over, for an offline peer whose key no delivery ever persisted (#234). Never resurrect a non-empty queue from it.
 - The journal's owner check (`rejectLiveOwner` in `delivery-journal.ts`) judges the manifest pid with `processLiveness` and its `pidSignature`, never a bare probe (rule: `daemon.md`).

package/docs/agent-notes/daemon.md

@@ -1,5 +1,8 @@
 # Daemon, control protocol and recovery
 
+- For explicitly user-authorized live verification, use the per-invocation CLI delegation in `docs/security.md` §Agent CLI identity and conductor authority; keep caller markers and record native evidence separately from fixtures.
+- Keep `export const LIVE_TEST_SUPPORTED = true;` in `src/cli/identity.ts`: delegated recovery staging reads this declaration before any source effect.
+
 - Console attention navigation selects a delivery only by an exact visible row id. A missing id or row prints read-only guidance; never select by peer or fall back to the first Queue row.
 
 Scope: the operator console, control WS and its protocol, state files, the dashboard listener and settings, the Claude channel's reconnect, `ahub setup`, git snapshots, upgrade and recovery. Read before editing `src/cli/console.ts`, `src/cli/console-state.ts`, `src/cli/attention.ts`, `src/ui/needs.ts`, `src/hub/daemon.ts`, `src/hub/ui.ts`, `src/hub/settings.ts`, `src/hub/control-client.ts`, `src/adapters/claude-channel.ts`, `src/hub/restart.ts`, `src/hub/recovery-store.ts`, `src/hub/snapshots.ts`, `src/hub/manager.ts`, `src/hub/lifecycle.ts`, `src/hub/crash.ts`, `src/hub/start-mode.ts`, `src/hub/terminal-open.ts`, `src/hub/recovery-error.ts`, `src/hub/db-timeout.ts`, `src/cli/setup.ts`, `src/cli/upgrade*.ts`, `src/cli/terminal-recovery.ts`, `src/cli/recovery-package.ts` or `src/cli/facts-hook.ts`, or before adding a native peer.

package/docs/agent-notes/tests.md

@@ -14,5 +14,6 @@ Scope: tests, fakes and the test gate. Read before adding or changing a test or
 - A request that a test expects a stop or shutdown to cut gets its rejection handler where the request is created, never after the awaited teardown: a late `catch` races the reset and the run fails on an unhandled rejection.
 - Run `bun scripts/seeded-check.ts` before reporting the seeded-guard gate complete. Keep the `scripts/seeds.json` cases sequential; require the same named test green before its seeded assertion fails. Seed rot, survivors, setup/compiler failures, timeout/watchdog termination and process leaks fail the gate. Never run the full seed runner from a unit test or mutate the source checkout; inspect preserved failed fixtures before removing them. CI runs this in the required Linux `seeded guards` job after the ordinary check, separately from `scripts/check.sh`.
 
+- `scripts/check.sh` holds the repo's heavy-job slot (`<git common dir>/ahub-heavy.lock`, #398) for the whole run, so a test never runs the real gate; `test/check-lock.test.ts` runs a copy in a scratch repo.
 - The whole-suite watchdog is `AHUB_CHECK_HANG_S` (default in `scripts/check.sh`, hosted macOS value in `.github/workflows/check.yml`; #378, macOS CI hit it while tests still passed): raise it only when the suite was still progressing at the cutoff, never for a hung test, and keep the per-test 20 s timeout.
 - A seed's named test must run on Linux, where the seeded job runs: a darwin-only test reports no result there and fails the job (#382). Cover a macOS-only protection with its regression test instead.

package/docs/operations.md

@@ -1,8 +1,46 @@
 # Operations guide
 
-This guide describes ahub 0.12.27 and control protocol 16. Live verification
+This guide describes ahub 0.12.29 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
+## Agent-operated live verification
+
+When the user explicitly authorizes a live test, its agent may run console
+commands using `ahub --live-test [--project <path|id>] <command> [args...]`.
+For example, `ahub --live-test --project <scratch-path> ui --no-open` starts the
+real dashboard listener and prints its one-time link without opening a browser.
+`ahub --project <scratch-path> --live-test reset --all --yes` exercises reset on
+that selected disposable project. The global options precede the command and
+may appear in either order; a flag after the command is not delegation.
+
+This grants console authority for operational console-class and peer-lifecycle conductor-class commands, including destructive actions, for one
+invocation and its ahub continuations. Use only the user-authorized targets and
+commands; destructive live checks belong in disposable projects. Existing
+project discovery still applies: initialize the scratch folder as its own Git
+repository before `ahub init`, then confirm `status --json` reports that exact
+`cwd` before any destructive check.
+Existing confirmations, process ownership checks, native identity fences and recovery
+locks still apply. Do not remove agent markers. The initiating peer and command
+label are audited before effects; an unavailable audit blocks delegation. A new
+unflagged invocation has ordinary peer authority again. Native tools launched
+by the command keep their own peer identity and receive no delegation flag.
+Allowed-class commands keep peer identity and permissions even with the flag:
+`--live-test say` sends as the peer. Peer starts, pause and resume may use
+delegated console authority. Flagged task assign/escalate refuse; omit the flag
+to use the ordinary actor-preserving conductor path when the peer has that role.
+Person verdicts and user-authored workflow writes are not delegated. Dashboard
+sessions issued through the flag retain operational controls but refuse message
+and task/planning content writes. Use native peer tools for agent-authored work.
+
+Use a CLI/coordinator containing this feature throughout the experiment. Older
+daemons do not understand the new delegated audit outcome; run the candidate
+daemon to capture its delegated event and console notice. This policy does not
+change external computer-use restrictions. Recovery staging refuses old targets
+without live-test support before source effects. Delegated headless recovery restores through the ordinary target CLI, carrying
+its operationId on the delegated console connection; existing native ownership
+and session-identity checks remain. Record actual observations in the
+smoke ledger; the presence of this option proves no outstanding #273 live leg.
+
 ## Command output
 
 `ahub status`, `board`, `budget`, `doctor`, `projects`, `queue list`, `turns` and `report` print shared console tables and labelled details.
@@ -1289,7 +1327,9 @@ reporting, and shares results explicitly with `hub_send`. Status, the console an
 the dashboard show `pull-only`, the waiting count and the last inbox read. Messages
 and important markers do not push or interrupt it. There is no hub busy state,
 watchdog, console approval, hub permission mode, context reading, automatic quota
-pause/handoff, shared final answer or session resume. Read quota and approve tools
+pause/handoff, shared final answer or session resume. When important messages are
+waiting, every other hub tool result ends with a line saying how many, so the model
+reads `hub_inbox` before starting long local work (#398). Read quota and approve tools
 in Kimi's own TUI; a person can pause the hub queue by hand. End the native terminal
 session there, not with `ahub stop kimi`.
 
@@ -1619,21 +1659,21 @@ section is what they run.
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.27), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.29), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.27 ahub upgrade --to 0.12.27 --dry-run
-bunx --package @staix/agent-hub@0.12.27 ahub upgrade --to 0.12.27 --yes
+bunx --package @staix/agent-hub@0.12.29 ahub upgrade --to 0.12.29 --dry-run
+bunx --package @staix/agent-hub@0.12.29 ahub upgrade --to 0.12.29 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.27 (protocol 16) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.29 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -1665,14 +1705,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.27 --dry-run
+ahub upgrade --to 0.12.29 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.27 --yes
+ahub upgrade --to 0.12.29 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -2354,6 +2394,13 @@ test files twenty times on macOS, in its own concurrency group; it does not repl
 `scripts/check.sh` stops a suite still running after `AHUB_CHECK_HANG_S` seconds
 (600 by default); hosted macOS CI sets 780 inside the unchanged 15-minute job
 limit (#378).
+The gate holds `<git common dir>/ahub-heavy.lock` across every worktree of a
+repository. A second gate waits up to `AHUB_CHECK_LOCK_WAIT_S` (1800 seconds by
+default; 0 fails immediately) and names the holder. A holder whose PID is gone
+is reaped. This filesystem slot works without a running hub; it covers this
+gate, not arbitrary build commands. PID reuse can retain a stale slot, and two
+waiters reaping the same dead owner can race; broader scheduling remains an
+operator responsibility (#398).
 
 ## Preview initialization and native launch
 
@@ -2453,6 +2500,31 @@ terminal exits, a requested stop (`ahub stop pi`), requested shutdown and
 recovery operations suppress this restart. Crash recovery's #66
 recorded-session/fresh-start choices are unchanged.
 
+### Explicit Pi history replacement
+
+If an offline Pi owner has no verified persisted resume state, inspect the old
+session and any partial work, then select a preserved file explicitly:
+
+```sh
+ahub pi --replace-session --session-file <managed-file>
+```
+
+The file must be inside this project's `.agenthub/state/pi-sessions/` and its
+session header must identify the same project. The selected session keeps its
+existing identity. This is a person-only recovery action; default restart never
+selects another session or infers that missing history was empty. A session id
+alone is insufficient. Add `--headless` to run the selected history in background.
+`--print-command` validates flags without checking the live owner or changing it.
+
+Replacement requires an existing offline owner whose native process is proven
+gone, with settled tools, receipts and approvals, outside a recovery operation.
+An unclaimed pending TUI launch uses the ordinary restart path instead. Before
+revoking the old owner, the hub durably saves private previous/selected session
+metadata in `pi-session-replacements/` beside `pi-sessions/`. Failed validation or
+record storage leaves the old owner intact. All session files, queued work and
+journal records remain. Uncertain effects are never retried by this selection;
+inspect and reconcile them before continuing.
+
 ### Pi/local unanswered approvals
 
 An expired Pi/local request says "approval expired: no person answered". The
@@ -2522,8 +2594,10 @@ An idle Pi with no message/file yet records its live empty-session proof before
 stopping, so its next start resumes that identity. A Pi stopped after its first
 prompt was accepted but before history was persisted is not treated as empty:
 its delivery is held, and another start refuses until resume history is verified.
-Inspect and settle the held delivery before deliberately replacing that unpersisted
-session by restarting the hub; the stop never silently chooses a fresh session.
+Inspect and settle the held delivery before selecting preserved history through
+[explicit Pi history replacement](#explicit-pi-history-replacement). The stop
+never silently chooses a fresh session; replacement requires an offline, settled
+owner and a validated managed session file.
 
 A pull-only Kimi TUI has no controlled restore or resume. While it is attached,
 upgrade/restart planning stops before effects and asks the person to end Kimi in

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.27
+bun add -g github:STAIxBWLB/agent-hub#v0.12.29
 ahub setup
 ```
 

package/docs/security.md

@@ -71,10 +71,35 @@ or the native Claude/Codex shell marker when the hub marker is absent. It connec
 as that peer in tools mode. Messages and task changes retain that actor;
 `say` defaults to status priority and important messages still require the peer's
 capability. Conflicting or malformed markers fail closed. There is no `--as-user`.
-Human-only operations are refused before connecting, including permission answers
+By default, console operations are refused before connecting, including permission answers
 and permission modes, queue resolution, budget overrides, benchmark runs, research
 backfill and task labels, stopping a peer (`ahub stop`), lifecycle and recovery
 operations, and `ask`.
+For live verification explicitly authorized by the user, an agent may invoke
+`ahub --live-test [--project <path|id>] <command> [args...]`. The flag delegates
+the existing console authority for console-class operations and conductor-class peer starts/holds, including approvals,
+settings, roster and lifecycle operations. It does not restrict effects to a
+scratch project: the agent must stay within the authorized commands and targets.
+Malformed or conflicting caller markers still refuse. The original peer and
+closed command label are recorded with outcome `delegated` before execution;
+if that audit cannot be written, the command refuses. The current daemon emits
+`agent_cli` with `delegated: true` and `refused: false`. Allowed-class commands retain the peer identity and capability checks, including
+messages, proposals and reviews. Peer starts, pause and resume may delegate
+operational console authority; task assign/escalate under the flag refuse. `--as-user`, person task labels,
+person-authored planning/release/memory/goal writes, SDLC record, benchmark run
+and the pet composer are refused. No argument text is copied into this audit.
+Delegated dashboard restrictions are bound to its server-issued ticket/session:
+operational settings/start/stop controls remain, but message, proposal and
+workflow-history actions refuse even if the body tries to clear the restriction.
+The flag is not stored in settings or exported to native agent children. Ahub's
+own daemon launch, console subprocesses, recovery runner, interactive follow-up commands and upgrade coordinator
+handover carry it explicitly in argv. Each new top-level invocation needs its
+own flag. An older CLI does not support it; use a candidate with this feature
+for the continuation too. Staging rejects a target without the pinned
+`LIVE_TEST_SUPPORTED` declaration before preparation or commit, including a
+previously cached stage. Delegated headless-native restoration uses the ordinary target CLI with its
+operationId through that operational console authority. Native and TUI
+restoration keep their existing identity and ownership checks. External computer-use restrictions remain unchanged.
 The operator uses a plain terminal or `ahub console`. A Claude `!` command that
 inherits the agent markers follows the same rule. The console strips control
 sequences from agent and daemon text before it quotes forged headers, and its

package/docs/smoke.md

@@ -2,6 +2,60 @@
 
 `scripts/check.sh` covers everything against fakes. The legs below need real accounts and an interactive terminal, so they are run by hand and recorded here.
 
+## Issue #273 operator execution plan (2026-10-16)
+
+The [execution plan and blocker record](verification/2026-10-16-273-live-verification.md)
+maps the outstanding issue entries to their procedures and required observations.
+The installed CLI and running project daemon both reported 0.12.28. This is an
+environment readback only. No outstanding live leg passed in this session:
+the installed 0.12.28 CLI refused `ahub ui` from Codex, and LCU refused Terminal access.
+These are dated observations. From 0.12.29, authorized agents use the audited
+`--live-test` route described below and in the execution plan; the external LCU
+restriction remains separate. The operator initially chose procedure preparation;
+#273 remains open.
+
+## Agent-operated verification (#408)
+
+For user-authorized live checks, the candidate CLI supports
+`ahub --live-test [--project <path|id>] <command> [args...]`, using audited console
+authority for that invocation. Follow [the operating procedure](operations.md#agent-operated-live-verification)
+and record each actual result below. References to a person in historical
+procedures describe their original authority requirement; an explicitly
+authorized agent may now execute those CLI steps through this option. Native
+account readiness, real terminal/browser observations, sign-off requirements and
+external computer-use restrictions still apply. No pending #273 item is checked
+by adding this path.
+
+2026-10-16, macOS, candidate CLI/source `40d13bc4`, daemon 0.12.28/protocol 16:
+an actual Codex-marked shell with a separate hub home and disposable Git project
+ran delegated `init`, `up --no-console`, `ui --no-open`, `permission pi ask`,
+`kill` and `reset --all --yes`, all exit 0. Unflagged `status --json` reported
+the exact scratch cwd. The dashboard URL returned HTTP
+200 and HTML; no browser or ticket/session exchange was performed in that shell run. The daemon recorded
+`agent_cli` events for init/up/daemon/ui/permission with peer `codex`,
+`delegated: true` and `refused: false`. The reset archive mode was 0700 and the
+scratch daemon was stopped. This verifies the delegated CLI path, without
+claiming a model turn, terminal look, conversation restoration or the complete
+#214/#273 live criteria. The automated console-subprocess and recovery-target
+checks remain separate fixture evidence.
+
+2026-10-16 review follow-up, source `fcbb18ec`: the same isolated Git scratch
+project was started from a Codex-marked shell. Flagged `say` produced a bus
+envelope from `codex`; person task-label writing refused. A delegated dashboard
+ticket exchanged for a session with HTTP 200, its snapshot returned HTTP 200,
+and a send action trying `liveTest: false` returned HTTP 403. The scratch daemon
+was stopped (kill exit 0). This was an actual CLI/HTTP run, without a model turn
+or browser visual inspection.
+
+Task #65 follow-up, source `5fbe50b6`: operational peer starts, pause and resume
+may delegate console authority; allowed-class messages/proposals/reviews retain
+the peer, while flagged task assign/escalate refuse. The temporary headless
+staging ceiling is removed. The recovery driver -> real target CLI -> scripted
+control server regression verifies headless Pi mode, saved sessionId,
+operationId, console hello and initiating-peer audit (225 related tests passed).
+This is fixture/CLI proof, not an actual native Pi restoration; that live leg
+remains owed in #273.
+
 ## Hub memory (#258)
 
 Not run yet (2026-10-12). Source and fakes cover tiers, the graph, retrieval, sync between two simulated homes and a bare remote, leases, import and suggestions (`test/memory-*.test.ts`).

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

@@ -1947,10 +1947,17 @@ task list polling does not. `hub_status` stays conductor-only.
   proposer as the actor with reason `manual` (on the `reassigned` or `reserved`
   entry), and writes no conduct audit event; during a PII turn it is refused
   like the conductor's.
+## Amendment: delegated agent live verification (#408)
+
+- Decision, 2026-10-16: an agent explicitly authorized by the user to perform a live test may use the global `--live-test` flag, before the command and in either order with `--project`. Duplicate global options refuse. Default command classification and malformed/conflicting identity refusals stay unchanged.
+- Console-class operations and conductor-class peer starts/pause/resume may use console authority after the original caller is validated; allowed-class commands retain peer identity and capability checks. Flagged task assign/escalate refuse rather than writing user-attributed history. A mandatory ids-only audit records its peer, closed command label and `delegated` outcome before execution. The daemon emits an `agent_cli` event with `delegated: true`, `refused: false`, and a console notice naming the peer. User impersonation, person labels and person-authored workflow writes refuse. Delegated dashboard tickets/sessions allow operational controls but refuse user-attributed content and history actions on both project and unified surfaces; request bodies cannot widen the session.
+- This is a user-authorized operating policy, not a sandbox or authenticated grant. It includes console mutations and requires the agent to remain within the authorized targets and operations. Command-specific confirmations, process ownership, provider identity and recovery locks still apply.
+- No settings/environment opt-in persists. Native argv does not receive the flag. Ahub's own daemon launch, console subprocesses, recovery runner, interactive continuation commands and newer-version coordinator handover carry it explicitly; older CLIs cannot accept it. The recovery driver's target CLI environment preserves the initiating peer for its delegation audit. Staging checks the target's pinned LIVE_TEST_SUPPORTED declaration before its cached-stage return and before prepare/commit; unsupported old targets refuse without source effects. Headless-native restoration uses the ordinary target CLI with the operationId on its delegated console connection; no headless staging ceiling is added. External computer-use policies remain outside this change. No #273 live success is inferred from this implementation.
+
 ## Amendment: ahub reset (issue #214)
 
 `ahub reset [--all] [--yes]` returns a project's hub to a clean state. It is
-human-only (the CLI identity gate refuses it from an agent shell) and a dry run
+console-only by default (explicit authorized delegation is described in #408) and a dry run
 unless `--yes`: the dry run reads `hub.db` read-only (with `immutable=1` when
 `hub.db-wal` or `-shm` is absent, so it creates neither) and prints delivery ids,
 peer names and counts per category, never task or message text. With `--yes`
@@ -2879,3 +2886,38 @@ open detail; disappearance/project reset closes it. Back restores compact mode,
 and state/peer/release filters remain active in focus. Attention targets exact
 visible row ids with heading guidance when absent. No new route, API request,
 timer, source text/ref/history projection or external asset is introduced.
+
+
+## Explicit offline Pi history selection (#403)
+
+A person may run `ahub pi --replace-session --session-file <managed-file>` only
+for an existing offline, settled Pi owner with a proven-gone native process.
+Pending tools, receipts, approvals and recovery hold replacement. The console
+control path alone authorizes this operation; peer and conductor tools cannot
+supply that authority. Validate the selected managed path and project/session
+header before any prior owner teardown, then durably write private previous
+and selected metadata. Retain all session files, queues and journal records.
+Start the selected persisted identity through the existing permission policy
+and verified teardown. There is no automatic fallback, implicit empty-session
+proof or effect retry; ordinary restart and captureResume remain strict.
+
+## Amendment: pull-only latency (#398)
+
+A pull-only peer learns of important work only when its model calls a hub tool,
+and repo-heavy work was coordinated over chat it read too late.
+
+- When an `important` envelope is queued for a pull-only peer, the bus calls the
+  advisory `onImportantQueued` hook and the daemon sends that peer's control
+  socket `{t:"queued", queued, important}`, as it does when a pull-only session
+  attaches with important work already queued. It is not a delivery: nothing is
+  dequeued, steered, journaled or settled, and the queue still waits for
+  `hub_inbox`. The `inbox` reply adds `waitingImportant`.
+- The plugin caches the counts and appends one line naming the important count
+  to every hub tool result except `hub_inbox` until a read reports none. An older
+  plugin ignores the unknown push; an older hub never sends it.
+- `scripts/check.sh` takes a heavy-job slot, a directory in the git common dir
+  shared by every worktree, before any step. A second gate waits up to
+  `AHUB_CHECK_LOCK_WAIT_S` (1800 s; 0 fails at once) and names the holder; a
+  holder whose pid is gone is reaped. The slot works with no hub running. It is
+  not bus-visible; moving it into the hub is the upgrade if pid reuse or reap
+  races bite.

package/docs/verification/2026-10-16-0.12.29.md

@@ -0,0 +1,25 @@
+# 0.12.29 release verification
+
+This record covers release preparation and source review. Publication and installation receipts are recorded separately after their gates succeed.
+
+## Candidate
+
+0.12.29 carries PR #409 (#408), the site correction in PR #406 and the #273 execution-plan corrections in PR #407. Control protocol remains 16.
+
+- Explicit `--live-test` delegation permits operational console and peer lifecycle actions with a mandatory initiating-peer audit. Allowed agent commands retain their peer identity; person-attributed writes refuse under delegation.
+- Dashboard delegation is bound to the issued session and checked server-side. Recovery refuses unsupported target packages before effects; supported headless restores use the ordinary target CLI with the recovery operation id.
+- The #273 ledger includes the current native checks and makes machine-wide upgrade isolation explicit. No native leg is marked passed by these preparation changes.
+
+## Document review
+
+Security, Operations and the design specification describe the reviewed delegation boundary. README, Quickstart and the current Operations examples name 0.12.29. The stale area notes are checked against the CLI identity, console, recovery, dashboard and audit changes; their existing rules remain applicable. Document stamps name the release preparation commit, which must remain an ancestor of the merge commit.
+
+## Recorded checks
+
+- PR #409 head a8b9a56b: independent source review and board tasks #64/#65 approved. Exact-head Ubuntu and macOS full gates passed (`check: OK`); the headless restoration regression is fixture/CLI proof, not native Pi restoration.
+- Original PR #407 head c637a088: Ubuntu, macOS and seeded guards passed in CI run 38791043404. The corrected execution plan was independently reviewed at 780853b6.
+- The final release head requires its own Ubuntu/macOS `scripts/check.sh` and seeded guards before merging. Committed document freshness and stamp ancestry are checked again before tagging. The release workflow requires green CI for the identical tree before npm publication.
+
+## Not verified by this record
+
+Native, account, visual and research checks remain tracked in #273 and #1. Package publication, global CLI/plugin installation and running-hub upgrade are separate operational results; this preparation record does not claim them.

package/docs/verification/2026-10-16-273-live-verification.md

@@ -0,0 +1,150 @@
+# Issue #273 operator execution plan
+
+## Scope and dated observations
+
+- Date: 2026-10-16, Asia/Seoul.
+- Initial observation source: main `426bab99`, release 0.12.28, protocol 16. The following CLI refusals describe that installed version, before #408.
+- Issue #273 was read live, including its 2026-10-14 additions at initial preparation; the matrix below was refreshed for the five 2026-10-16 additions before release. Every checkbox remained unchecked.
+- `ahub --version` returned `0.12.28`.
+- `ahub status --json` returned daemon version `0.12.28`, protocol `16`, `stopping: false`, Claude idle, Codex busy, Kimi offline and Pi idle. These are status observations, not model-delivery or restoration receipts.
+- `ahub ui` exited 1 with `ahub: codex cannot run ahub ui; the person runs it in ahub console or a terminal`.
+- LCU app selection for `com.apple.Terminal` returned `Computer Use is not allowed to use the app 'com.apple.Terminal' for safety reasons.` No Terminal inspection or input occurred.
+- The operator selected procedure and blocker preparation before live execution. No identity markers were removed, no console connection was impersonated, and no lifecycle, reset, roster, quota or provider experiment was run.
+
+## Supported execution route and remaining boundaries
+
+From 0.12.29, an explicitly authorized agent runs operational CLI steps with
+`ahub --live-test <command> [args...]`, including `init`, `up`, `console`,
+`settings`, `reset`, `upgrade`, `recovery` and roster operations. Follow
+[Agent-operated live verification](../operations.md#agent-operated-live-verification).
+Record the initiating peer and the mandatory delegation audit (`agent_cli`
+event or retained CLI audit), alongside the command and operational receipts.
+The original 0.12.28 refusal above is historical evidence, not a current CLI
+blocker. Identity markers remain intact; the supported option supplies authority.
+
+Allowed-class commands retain the agent's peer identity, including messaging
+and review verdicts. The flag refuses person-attributed writes, including
+`--as-user`, task labels, task assign/escalate and planning/memory writes.
+Delegated dashboard sessions permit operational controls but refuse sending,
+proposals and person-attributed planning/history actions; changing a request body
+cannot remove that restriction. Exercises requiring those actions or a person's
+sign-off need the ordinary authorized actor path and cannot be completed merely
+by adding the flag.
+
+LCU's Terminal denial is a separate external computer-use restriction and remains
+in force. CLI delegation does not grant Terminal app access or prove native
+visual, account or accessibility observations. Record any inaccessible native
+surface as unverified while continuing reachable authorized CLI checks.
+
+## Execution order
+
+Use a disposable Git project under the workspace scratchpad, outside this
+checkout, and initialize its own Git boundary before `ahub init`. An authorized
+agent runs `ahub --live-test init`, reviews the resulting configuration and starts
+it with `ahub --live-test up`. Record its absolute path, project id and delegation
+audit. Keep destructive recovery/reset experiments separate from the project
+used for browser and model checks. Recovery can hold a machine-wide lock, so
+inspect `ahub --live-test recovery status` before starting an operation and wait
+for unrelated operations to finish. Upgrade isolation has the additional
+machine-wide and shared-configuration requirements below.
+
+Use installed, authenticated native tools. Record each version before its first
+turn. Do not change credentials, buy access or exhaust quota to produce a result.
+Do not run another session's stop or reset. Keep identity fencing in effect and
+use the documented delegation route rather than removing identity markers.
+
+1. Run reachable operational checks through `ahub --live-test`; retain their delegation audits and readbacks. Inspect terminal/dashboard rendering only through an available permitted native surface.
+2. Run native messaging and role/planner exercises on the disposable project using the ordinary peer or person path as required by attribution; the delegation flag does not authorize person-content writes.
+3. Run roster and recovery experiments with disposable conversations only, using the delegated operational CLI route and recording native continuity separately.
+4. Run the real repository SDLC cycle only with an explicitly selected issue and release window, retaining required person verdicts.
+5. Record each result in `docs/smoke.md`, retaining any unverified remainder and external blocker.
+
+## Required observations by issue entry
+
+All rows below are pending. A procedure reference is not evidence of execution.
+Section names refer to [the smoke checklist](../smoke.md).
+
+| Entry | Procedure or setup | Evidence required before checking the issue box |
+| --- | --- | --- |
+| #201 AC2/AC7, #213 AC7 | Console layout and readability | Light/dark terminal, stream and panels; terminal name, dimensions, readable text and observed clipping |
+| #205 AC3 | Claude without channel evidence | Managed Claude push and settlement beside plain Claude tools-only; correlated message and settlement ids |
+| #206 AC4 | Upgrade procedure below | Two distinct releases, unmanaged Claude marked reconnect-only, same native conversation after reconnect |
+| #214 AC6 | ahub reset on a scratch project | Both reset scopes, queue/board checks, archive permissions and restored board, same project id |
+| #215 AC6 | Expired-lease procedure below | Real expired lease and missing transcript, daemon/CLI/lock/project/archive outcomes, completion or audited disposition |
+| #225 AC9 | Target-crash procedure below | Target killed after peers-restored, supported resume, original conversation and restart count readback |
+| #269 AC10 | Settings from the dashboard and the terminal, parts 1-2 | Light/dark, phone width and keyboard path; actual Orca and terminal.open launches with native Pi attached |
+| #285 phase 1 | Record table, #285 live item 1 | Real Kimi turn, status context source/value, usage_update timing relative to correlated prompt result |
+| #284 phase 1 | One-shot command output | status/board/budget/doctor, light/dark, 80 and wider columns, console rendering and full suggested ids |
+| #298 | Unified dashboard slow start | Real browser unconfirmed text, 30-second hold and keyboard focus after Start; a deterministic slow native start is a prerequisite |
+| #296 | Ending Codex turn | Correlated native turn/steer response, elapsed time and exact refusal; a successful steer alone does not prove refusal matching |
+| #315 Codex | Live roster return | Removal exit, printed resume command, restored same thread and peer reattachment |
+| #315 Pi | Live roster return | Retained terminal/process, admission refused off roster, same TUI reattaches; prepare blocked until retained TUI ends |
+| #316 trust and ingestion | Kimi TUI pull mode | Actual trust screen, project MCP tools and model-visible managed instructions/tool descriptions |
+| #316 messaging/discovery | Kimi TUI pull mode | Correlated hub_inbox/hub_send exchange with another peer; trusted project and overlay discovery |
+| #316 headless return | Kimi TUI pull mode | TUI to headless to TUI, session/config restoration readback; argv fixtures are insufficient |
+| #256 identity/modes | Qwen Code 0.25.0 production peer | Real ACP supported identity and advertised modes; stop on CLI/ACP mismatch |
+| #256 native provider | Qwen Code 0.25.0 production peer | Actual model identity, delivery, exact tool call/result and mode confirmation |
+| #256 stop/recovery | Qwen Code 0.25.0 production peer | Owned stop and controlled/crash recovery retain the recorded conversation |
+| #256 quota | Observe an organic refusal only | Version and exact sanitized native refusal; unknown remains failed delivery |
+| #259 AC11 | Research-profile exercise | Two native agents, three sources, configured routing/classes, plans, role/tool ingestion, deterministic citations and person sign-off |
+| #259 converters | Intended formats and configured converters | Actual conversion, review and undo previews; timing, caps and named-only fallback |
+| #259 guidance | Same native profile sessions | Native profile/custom-stage guidance retention; preserve separate #295 and research measurements |
+| #257 AC6 | SDLC gates | Real repository issue through merge/release under advise; issue/PR/head ids, gate blockers and release report |
+| #295 AC16 | Native role/task cycle | Role text ingestion, retention after actual compaction, assignment/reassignment notice and review duty |
+| #280 AC11 | Console attention, Global attention status, Approved character, Dashboard character | Per-phase light/dark, tmux, colour off, blocks/ascii and actual dashboard look |
+| #263 AC11 | Planning and release controls | Native planner creates two releases; planned/actual dates read back |
+| #263 board/intake | Project board | Desktop/phone browser against real hub, permission/state readback and actual GitHub issue intake |
+| #306 | Observe an organic Kimi weekly/monthly refusal only | CLI version and exact sanitized prefix; do not deliberately consume quota |
+| #403 | Offline Pi preserved-history recovery | Actual selected native session restored with identity/queue retained; a live owner refused |
+| #398 | Pull-only important-message advisory | Real Kimi TUI and plain Claude see the tool-result advisory; hub_inbox drains it |
+| #391 pet lifecycle | Standalone pet window | Actual stop changes it to Offline and host exits; native screenshots of states |
+| #391 dashboard CSP | Split dashboard views | Browser-console capture of CSP behavior, separate from the earlier owner browser look |
+| #394 VoiceOver | Office desk More control | Native VoiceOver traversal; DOM/click/Enter/Space regressions remain separate |
+
+## Upgrade with unmanaged Claude (#206)
+
+1. An authorized operator starts the disposable project on a known older release, records its version/project id and attaches an unmanaged Claude session using the documented plain-Claude tools-only setup. Record its native session id and a harmless conversation marker.
+2. Use an isolated test environment for the hub home/registry and shared Claude plugin setup. Upgrade is machine-wide, even when invoked from the scratch cwd: it plans all registered running projects and changes the shared package/plugin; `--project` does not scope it. Run the target coordinator with `ahub --live-test upgrade --to 0.12.29 --dry-run` and retain the complete plan. Verify every planned root is a disposable fixture, record the shared CLI/plugin fate, and confirm the intended unmanaged Claude is reconnect-only. Stop without applying if any non-disposable project or shared setup is in scope. A separate AGENTHUB_HOME alone does not isolate the shared plugin; use a dedicated native configuration/test environment too.
+3. The authorized agent applies that same target with `ahub --live-test upgrade --to 0.12.29 --yes` after reviewing the plan (a person may use the ordinary interactive path). Retain the delegation audit. Record operation id, source and target versions, terminal fate and plugin reconnect outcome. Do not substitute a restart at the same version.
+4. Read back `ahub status`, the original native session id and marker, and one correlated hub message receipt. Record whether a second terminal appeared or a conversation was replaced.
+5. Capture final operation and lock status. A refusal or failed reconnect is a failed leg, with its exact wording; it is not a pass based on the dry-run plan.
+
+## Expired preparation lease with missing Codex transcript (#215)
+
+This needs an isolated failure-injection setup before it is executable. There is
+no public `ahub recovery prepare` CLI. Do not invent one or edit production
+recovery JSON to claim a native reproduction. `test/upgrade.test.ts`,
+`expiredLease`, is a scripted-driver fixture and is only a setup reference.
+
+1. Give disposable Codex its own native session store and complete a harmless turn so its transcript exists. Record project id, daemon instance, native thread id and transcript path. Keep the original transcript outside the fixture's missing-path condition; never remove a production transcript.
+2. In a controlled scratch-only harness, stop the coordinator after real source preparation and before commit, preserving its operation receipt. Record the daemon's preparation, terminal close receipts and runner identity. The harness and its pause point must be reviewed before use.
+3. Make only the disposable transcript unavailable and allow the real preparation lease to expire. Confirm expiry from the daemon log/readback rather than changing a clock or receipt timestamp.
+4. The authorized agent runs `ahub --live-test recovery status <operation-id>` and the supported next action it offers. Capture the exact missing-session refusal. Restore the disposable transcript and resume, or use the offered audited disposition with a reason. Do not force a fresh conversation and label it restoration.
+5. Record daemon and CLI outcomes, operation/lock state, project id before/after, archive paths and modes, and the final continuity or lostContinuity disposition. Preserve failed intermediate receipts.
+
+## Target crash after peers-restored (#225)
+
+1. In a separate disposable project, establish native conversations with harmless markers and start a controlled recovery. Save its operation id and source conversation ids.
+2. Observe the real `peers-restored` phase before release. A controlled pause at that boundary is required: if the operation already completed, this run cannot demonstrate this failure point. Do not fabricate the phase by editing a receipt.
+3. Verify the target pid belongs to this disposable project's daemon and record its instance id. The authorized operator ends only that target daemon through a permitted process-control surface. Record native launcher/process state after the exit.
+4. Run `ahub --live-test recovery status <operation-id>`, then its offered `ahub --live-test recovery resume <operation-id>`. Retain the delegation audits. If a surviving launcher blocks it, end the identified disposable launcher as instructed and retry the supported action.
+5. Verify the new target instance, recorded restart count, same native conversations and markers, no duplicate terminal, final operation status and lock release. A missing snapshot or failed native resume remains a failure, with the precise refusal and the supported disposition recorded.
+
+## Recording and closure
+
+For each execution record: date/time, source commit, hub/native versions, project
+id, exact command or interaction, expected observation, actual observation,
+correlated ids, sanitized evidence path and pass/fail/unverified verdict. Record
+partial success at the substep level. Keep raw tokens, cookies, private task text
+and account details out of committed evidence.
+
+On a confirmed defect, preserve its failure wording and open a linked defect
+issue within the user's authorized scope. Check a #273 item only after its dated
+record covers the entire item, or a failed run is recorded with a linked defect.
+Environment/tool restrictions remain unverified prerequisites. They do not meet
+the issue's failed-product-run alternative. #273 cannot close from this plan.
+
+The initial preparation ran no full check or native model turn. Its original
+commit c637a088 subsequently passed Ubuntu/macOS full gates and seeded guards
+in CI run 38791043404. The release candidate must earn its own exact-head checks;
+none of those automated results completes a live leg.