@staix/agent-hub 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the
 
 ## Unreleased
 
+## 0.34.0
+
+- `ahub upgrade` no longer dead-ends on Orca panes that are orphaned but still connected after an Orca restart (#1246, PR #1249, task 760). The `terminal-orphaned` blocker names the peer, project and handle and the refresh key (`[r]` on the plan, `[s]` on an open operation). The interactive plan screen offers `[t] reattach N orphaned terminals`: after the person picks it, it runs `orca terminal switch` only for the panes the plan verified (same identity, still orphaned and connected, no project or machine recovery hold), bounds every Orca call and the confirmation poll by 5 s, and plans again. Nothing else is mutated; `--dry-run`, a pipe and `--yes` never switch a pane. A live Orca restart remains unverified.
+- `ahub setup` keeps dotfiles-managed and other symlinked installs on their stable path (#1245, PR #1250, task 759). Marketplace and Claude profile hook paths use a verified lexical PATH alias (at most eight links, accepted only when it resolves to the executing package) and the matching PATH Bun, instead of versioned `tools/ahub/<version>` or `Cellar/bun/<version>` paths. A stale managed profile hook is replaced in place and managed duplicates are dropped; unrelated settings are preserved. A refused marketplace replacement names every non-user plugin row, warns when a project row's path is `$HOME`, and names the person-owned remedy; non-user rows are never removed automatically. `ahub doctor` also inspects the existing default Claude home read-only and names the per-home setup command for a stale hook. Upgrade and doctor advice resolves the global CLI from PATH `ahub`, giving `bun add -g` only for a Bun-global install and generic advice without a path otherwise.
+- Quickstart: a section for dotfiles-managed installs (PR #1247): update with `dot ai family install ahub --version <version>`, then `ahub setup`; roll back with `dot ai rollback ahub`; keep one copy; and the 0.33.0-and-earlier workarounds for the marketplace refusal and the stale profile hook.
+- Compat receipt automation audit (#1248 T0, PR #1251, task 761): a data-only manifest (`scripts/compat-receipts/manifest.json`) classifies every leg of every current COMPAT receipt with its source quote, runner OS, exact acquisition recipe and `autoAdmit` policy eligibility, plus an audit report and an operations table. No COMPAT, harness, workflow, trust or verified version changes; the CI token route for CI-opened PRs stays the person's choice.
+
+- 0.34.0 N-1: published 0.33.0, the latest 0.33.x patch, with exact agent-mem 0.22.1 and control protocol 17 (descriptor floor 16). The release N-1 fixture and matrix pin it; the separate protocol-16 fixture stays 0.25.0.
+  - Wire and protocol: unchanged. No control message, room header, codec or MCP tool schema changed since 0.33.0. A published 0.33.0 broker relays codec presence, so upgraded members negotiate codecs through it; the broker test that asserted the codec-less 0.32.0 broker now asserts this.
+  - Files and format floors: hub.db remains schema 2, RoomStore remains schema 5, and the hub still exact-pins agent-mem 0.22.1, the same core as N-1; no memory layout or format floor changes.
+  - CLI: `ahub upgrade` adds the interactive `[t]` key and new blocker wording; `ahub setup` and `ahub doctor` change which paths they write and print. A 0.33.0 CLI keeps its own behavior against a 0.34.0 hub: no new flag, command or JSON field is required. Rollback: 0.33.0 setup matches its profile hook by exact command text, so after a rollback it does not recognize the hook 0.34.0 wrote and adds its own beside it (source reading, not a run); 0.34.0 setup later collapses both into one.
+  - Evidence ceiling: the N-1 fixture uses the unmodified published 0.33.0 package for control/plugin and isolated broker/member tests. These claims do not establish real-account inference, a live Orca restart, a real dotfiles install or two-machine operation; the release verification report records execution results separately.
+
 ## 0.33.0
 
 - Exact-pin the first-party agent-mem core to 0.22.1 (PR #1243, task 754). It includes the upstream strict-host TOML serialization fix and adds no runtime dependency. Placement activation and writer renewal remain opt-in person commands; a pin upgrade does not activate a home or add the hub's missing fresh placement-attestation integration.

package/README.md

@@ -5,7 +5,7 @@ Code, Codex, Kimi Code, Pi and a hub-owned local worker (plus Qwen Code, Jcode a
 Antigravity if you want them) share a message bus, a task board and a memory, each
 connected through its own native interface.
 
-Status: 0.33.0, control protocol 17 (accepts 16). Bun + TypeScript, one loopback daemon per
+Status: 0.34.0, control protocol 17 (accepts 16). Bun + TypeScript, one loopback daemon per
 project. Site: [agent-hub.staix.net](https://agent-hub.staix.net).
 
 ## Quick start
@@ -143,7 +143,7 @@ uses the home must run a version that understands the new layout.
   [#258](https://github.com/STAIxBWLB/agent-hub/issues/258)).
 
 Live checks that still need a real account or a person are listed in the
-[release verification report](docs/verification/2026-11-06-0.33.0.md) and the
+[release verification report](docs/verification/2026-11-07-0.34.0.md) and the
 [smoke checklist](docs/smoke.md).
 
 ## Documentation

package/docs/dogfood.md

@@ -55,7 +55,7 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Floor policy (#999 T3, `action_policy.floor`) | source and test after merge and release; off here (a person turns it on in the untracked `config.local.json`), and the running hub takes it after upgrade | `test/action-floor.test.ts` (every allowed, asked and opaque case, status guard rows) and `test/daemon-action-floor.test.ts` (the Pi permit path through the real daemon: allowed calls run with no prompt, force and default-branch pushes, tags, `gh release`, `--admin` and other repositories ask); T4's live receipt records it under Orca. `2>/dev/null`-style redirects to `/dev/null` and `/dev/tty` no longer classify as destroy (#725, #1193; `/dev/stdout`, `/dev/stderr` and `/dev/fd/<n>` stay destroys because on Linux they reopen and truncate the file fd 1 or 2 already points at): active after release and plugin upgrade, unverified in a live agent-research session; the metric is the count of `always-ask: destroy` prompts on commands that only redirect to `/dev/null` or `/dev/tty`, which should reach zero, and `test/action-class.test.ts` (the `#725 device redirect` rows, including the four aliases, `/dev/fd/3` and lookalikes) |
 | Confirmation-point inventory (#999 T0) | source and test coverage; `ahub autonomy status` reads the inventory after this feature is released, with no default prompt change from the data alone | `test/confirmation-matrix.test.ts`: every adapter-catalog kind has a tool-approval and a classed-action row per environment, kinds facts equal the definitions, cited source lines exist; the `unknown` rows are the list T4's live receipt must close |
 | Project autonomy preset (#999 T1) | off on this repository until released and explicitly enabled by the person; project scope only | focused person-only, retained-consent, metadata-independent off and authenticated/fallback preset undo tests; the preset writes `action_policy.floor` (#999 T3) and off removes it; status leads with a peer table separating current modes from desired defaults, groups identical floor verdicts and unknowns once with peer lists (#1137), and reads each floor class from the host verdict (`floorEnforcement`), naming the unverified guard where the hub does not see the call first; the Orca zero-prompt native task remains T4 |
-| Machine autonomy and used Claude homes (#999 T2) | off until released and explicitly opted in by the person; no real home is changed by fixture tests | trusted-default/unsafe-default startup consent, all-project preview/apply, init inheritance with unchanged absent-file ask defaults, and isolated per-home plugin/hook setup/status tests; #1069 covers preserving project/local plugin rows while configuring only user scope, plus recording `start.agents` after a failed home step; metric: applied/refused registered targets and missing/unknown discovered-home states; native Orca receipt remains T4 |
+| Machine autonomy and used Claude homes (#999 T2) | off until released and explicitly opted in by the person; no real home is changed by fixture tests | trusted-default/unsafe-default startup consent, all-project preview/apply, init inheritance with unchanged absent-file ask defaults, and isolated per-home plugin/hook setup/status tests; #1069 covers preserving project/local plugin rows while configuring only user scope, plus recording `start.agents` after a failed home step; metric: applied/refused registered targets and missing/unknown discovered-home states; #1245 fixtures cover a verified current alias surviving A-to-B upgrades without marketplace removal, exactly one managed hook, actionable non-user-row refusals, stale-hook doctor warnings in an unselected default home, and PATH-selected global CLI update advice with a pure handoff doctor pointer; real-home setup remains unverified for that change; native Orca receipt remains T4 |
 | Read-time memory code neighbours (#684 phase 4) | off until released; dashboard toggle is opt-in | derived call edges with current SHA; attached fail/decision brief coverage; explicit unknown/truncated results; unchanged authoritative memory log bytes |
 | Canonical memory symbol anchors (#684 phase 3) | off until released; optional `doctor --stale-anchors` report only | actual-symbol completion anchors versus plan guesses; symbol-related earlier notes at memory hop two; stale/unknown/truncated report counts; zero note mutations during inspection |
 | Symbol preparation and historical recall (#684 phase 3 follow-ups) | off until release | exists calls per no-reviewer completion; raw-signature fail recall; indexed-definition/unknown labels; unchanged note/candidate bytes and neutral cleanup failures |
@@ -217,6 +217,7 @@ agent-hub is developed with agent-hub. This page lists every feature, whether it
 | Plain corpus evidence in ask and task briefs (#510b) | off here until a person configures plain `corpus.paths`; vaults remain refused; no corpus body is written to amem | `note:<path>#heading` ids in ask evidence or public task briefs; PII/deny and stale-context refusal regressions |
 | acon inbox snapshot speed and bound (#727, #1196) | on after release and `ahub setup`: the acon plugin asks every running project at once (not one after another), shares one computation among concurrent polls, serves a result younger than 1 s as it is and one up to 10 s old at once while one refresh runs, drops the cache on any action, waits at most 2 s for a project and keeps that project's last rows meanwhile, and returns at most 50 items (decisions first, then reviews, results, candidates, alerts) with a `more` count. Measured on the owner's Mac before the change: 2.5 s for 434 B in the console, 0.84 s median when run alone here, against a 2 s `pollMs`. Unverified: the owner's live console p95 after the change | the inbox `snapshot` wall time seen from the acon console on the owner's Mac (target p95 under 1 s), `test/acon-inbox-727.test.ts` (parallel asking, one computation for 20 callers, cache and background refresh, invalidation by an action, the 50-item bound and `more`, the project budget and a p95 over a five-project fleet), and the uncached median over this machine's real registry (0.84 s before, 0.37 s after) |
 | Global CLI and plugin step after `ahub upgrade` (#718, #1179) | on after release: a completed or scheduled upgrade ends with `bun add -g @staix/agent-hub@<version>` and `ahub setup` when the global CLI or the shared Claude plugin is older than the daemon it installed (a handed-over upgrade speaks for the older CLI that started it), and says nothing when both are current or the plugin cannot be read; `release-prepare` writes the same step into every new `Upgrading to <v>` note and `release-tag` refuses a release without it. Unverified: a live handed-over upgrade on the owner's Mac, where the old CLI starts the new coordinator through `bun x` | the upgrade's own output on the owner's Mac after the next release, whether `ahub doctor` still warns afterwards (it should not once the person followed the step), `test/runtime-version-warning.test.ts`, `test/upgrade-interactive.test.ts`, `test/upgrade-cli.test.ts` (a real hub with a fake `claude` and `npm`), `test/release-prepare.test.ts` and `test/release-tag.test.ts` |
+| Confirmed reattach of orphaned-but-connected Orca terminals in `ahub upgrade` (#1246) | on after release: the interactive plan screen offers `[t]` when the plan verified a pane as orphaned and connected, switches exactly those handles with `orca terminal switch`, polls each for at most 5 s and plans again; the blocker names the peer, project, handle and `[r] refresh`. Unverified: a live Orca restart on the owner's Mac (fixtures use a fake Orca) | count `[t]` uses against hand-typed `orca terminal switch` calls after an Orca restart (the latter should reach zero), and how often a pane is still orphaned at the 5 s bound (raise the bound if it is common); `test/terminal-recovery.test.ts`, `test/upgrade-interactive.test.ts` |
 | Hard-coded values inventory ratchet (#719, #1180) | on now: `scripts/check.sh` runs `bun scripts/inventory-hardcoded-values.ts --check`, so a new constant must be classified in `scripts/inventory-hardcoded-values.classifications.json` before it merges, and the 1222 keys still unclassified sit in `scripts/inventory-hardcoded-values.baseline.json`, which only shrinks. This does not close #1180: those 1222 are classified later in reviewed batches (`docs/verification/2026-11-05-hardcoded-values-ratchet.md`) | the unknown-key count (the baseline's length) falling to 0 over the follow-up batches and `check: OK` staying green with no key added to the baseline, `test/inventory-hardcoded-values.test.ts` |
 
 ## Decisions

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.33.0 and control protocols 16 through 17. Live verification
+This guide describes ahub 0.34.0 and control protocols 16 through 17. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -2317,16 +2317,53 @@ A newly initialized `ahub init` project inherits a trusted machine opt-in and sa
 
 `ahub setup` selects the explicit `CLAUDE_CONFIG_DIR`, otherwise an existing default Claude home (or the not-yet-created default when no other home is selected), plus distinct homes proven in use by live registered Claude launcher records. It does not scan arbitrary profile directories. Each native plugin command receives that home's environment. One confirmation covers plugin setup and a project-neutral PreToolUse hook while preserving unrelated hooks and statusLine settings. The profile fallback requires the inherited hub state and peer identity and does nothing for a managed launch that already has its session hook, preventing duplicate delivery. Installing a hook proves configuration, not live enforcement.
 
+Setup preserves a stable package alias from the `ahub` executable on PATH only
+when its bounded symlink chain (at most eight leaf links) ends at this running
+package's `src/cli/main.js`. A versioned install can therefore keep its `current`
+parent alias in marketplace and profile-hook paths across upgrades. Another copy
+on PATH, a missing target or an unproven alias uses the resolved running package
+instead. The hook uses the PATH spelling of `bun` only when it resolves to the
+same runtime as this process; otherwise it keeps the observed runtime path.
+
+The generated single-command profile-hook shape identifies managed entries,
+including entries from an older install whose script is now missing. Setup
+replaces the first managed entry in place and removes duplicate managed entries,
+preserving that entry's matcher/timeout metadata, unrelated hook commands and
+statusLine.
+Doctor reports missing managed script or runtime paths in every home it inspects.
+Its read-only inventory also includes an existing default Claude home even when
+`CLAUDE_CONFIG_DIR` selected another home for setup; that inspection neither
+selects the default home for writes nor repairs it automatically. Run setup for
+the intended home to refresh its managed hook.
+
 Setup manages only the user-scope `agent-hub@agent-hub` plugin row (`claude
 plugin install|uninstall ... --scope user`). A project- or local-scope row of that
 plugin is kept and named in a notice (`... plugin row preserved ...; setup never
 removes non-user scopes`). While such a row exists, setup is blocked rather than
 removing an agent-hub marketplace that points at another source (#1073). The
-semver check on installed plugin versions applies only to agent-hub rows, so
+refusal names every blocking row's scope, projectPath, version and installPath.
+Hub-launched Claude sessions load their plugin from the hub's release runtime,
+not those plugin-cache rows; standalone sessions may still use them. Back up the
+selected home's `plugins/installed_plugins.json`, review every listed row, and
+manually remove only rows confirmed stale and unused while preserving all other
+rows; then rerun `ahub setup`. For a project row whose projectPath is `$HOME`, do
+not run `claude plugin uninstall --scope project` from `$HOME`: its project
+settings path is also the default home's `~/.claude/settings.json`. Setup leaves
+these non-user rows unchanged on refusal. The semver check on installed plugin versions applies only to agent-hub rows, so
 another plugin recorded with a git SHA no longer fails the inventory (#1074). When
 a Claude home step fails, setup still records the `start.agents` answer before it
 reports the failure.
 
+Updating a project's daemon does not update the global CLI or shared plugin.
+When a global CLI update is needed, upgrade and doctor guidance resolves the
+`ahub` package on PATH independently of the executing staged daemon or `bun x`
+coordinator. Outside a proven Bun-global prefix it names that installation path:
+update it using the method that installed it, then run `ahub setup`. A Bun-global
+command is suggested only for a PATH-selected package verified inside that prefix.
+An unknown PATH installation gets generic update advice without an inferred path.
+Handoff wire-version refusals keep fixed guidance to update the older hub and the
+global CLI the way it was installed; `ahub doctor` names the exact step.
+
 `ahub autonomy status [--json]` includes the machine default and each discovered Claude home's plugin/hook state. Missing, unsafe, stale, unavailable or incomplete evidence is explicit; a missing selected home is reported without starting a native inventory command that could create it. The native Orca zero-prompt receipt remains T4.
 
 
@@ -3495,6 +3532,25 @@ Agent CLIs update themselves often, and a hub release cannot follow every one. O
   - **Maintenance loop (#843):** the daily upstream watch is the trigger; `ahub doctor` is the local drift notice for versions installed on a machine, and the hub itself tells the planner (below). The planner files one receipt task per (id, version): the implementer repeats the procedure in the entry's last `docs/verification/` receipt, writes a new one, and adds the version to `verified` in that same PR; the next release ships the bump. A person's `ahub agents trust` stays the stopgap that keeps a machine running meanwhile, and the person may revoke it once the bump lands.
   - **Local drift notice (#843 AC3):** at hub start and once a day the daemon reads each gated CLI's installed version with the probe `ahub agents` uses (no network, no install). For every installed CLI on a version that is not `verified` (in-line, trusted or refused) the effective planner gets one notice per (id, version): the id, the version, the state and the last receipt path, nothing the CLI printed. A CLI that is not installed, or whose version cannot be read, is not drift. The marker is kept per (id, version, planner) in `hub.db` (`agent_drift_notices`), so a restart repeats nothing, a planner whose notice could not be queued (or who joins later) is retried alone without telling the others again, and a new version is a new notice; with no rostered planner nothing is recorded. `ahub status` shows one `agent CLI drift` attention line per drifted id until the installed version is verified.
 
+### Receipt automation audit (#1248 T0)
+
+The data-only [manifest](../scripts/compat-receipts/manifest.json) and [per-leg audit](verification/2026-11-07-compat-receipt-audit-1248.md) classify all current COMPAT receipts. Every leg carries a source section and exact excerpt. `autoAdmit` is policy eligibility after every required check and artifact binding passes, not a runnable harness or a version admission. Native Mac arm64 requirements remain; Linux fixture/source-check feasibility does not replace native platform evidence. Changed security-source regions require human review rather than an automatic diff-only pass.
+
+| COMPAT id | CI repeat and other required scope | Install method | autoAdmit |
+| --- | --- | --- | --- |
+| `pi` | Linux host permission/version fixtures; Mac RPC extension, SDK and tool receipts; Mac arm64 native | npm exact | `true` |
+| `claude-implementer` | Mac Write/Bash/rewrite transport and wrapper controls, synthetic provider; Mac arm64 native | npm exact; native-installer receipt boundary | `true` |
+| `codex-review` | Linux source comparison; Mac production metadata and native sandbox controls; Person-authorized model-backed tool call | npm exact | `false` |
+| `kimi-review` | Linux source comparison; Mac private config/broker/native allowlist controls; Mac arm64 native | GitHub asset + SHA-256 | `true` |
+| `jcode` | Linux source comparison; Mac serve/ACP/MCP and fixed-stream steering; Mac arm64 native | GitHub asset + SHA256SUMS | `true` |
+| `agy` | Mac CLI, synthetic MCP/hooks and Seatbelt controls; Interactive TUI/launcher nonce; no public install source | Unavailable | `false` |
+| `qwen` | Mac ACP/permission and install replay; recorded Linux run is additional; Mac arm64 repetition required | npm exact | `true` |
+| `qwen-dual` | Version/file-source checks are partial only; Real gateway model and PTY; OS not recorded | npm exact; historical artifact gap | `false` |
+
+Optional model/TUI behavior explicitly left unverified by a model-free receipt is not a new admission leg. `codex-review` requires its separately authorized model-backed tool-call proof. `agy` has no public install source. `qwen-dual` requires real-model and TUI work and its current receipt does not name the OS. The manifest records acquisition metadata separately from historical native-binary evidence; no CLI installation or COMPAT change is made by this audit.
+
+For CI-opened PRs, the person still chooses between explicit `check.yml` dispatch with GITHUB_TOKEN and a GitHub App installation token. Dispatch avoids an additional App secret but needs Actions write permission in the publisher and exact-head evidence; it does not run the separate PR-only closing-refs/routing-receipt workflows. An App token lets normal PR events start checks, with person-owned scoped credentials confined to the publisher. Neither route is enabled here. Current [GitHub documentation](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) also describes approval-required PR runs for GITHUB_TOKEN automation; that is not unattended CI. See the audit for permissions, queue and gate trade-offs.
+
 ## Upgrade and crash recovery
 
 ### Side by side project versions (#1039)
@@ -3569,7 +3625,7 @@ or the plugin is older than the daemon it installed (#1179). It prints nothing w
 | Runtime | Control protocol window | Legacy status field |
 | --- | --- | --- |
 | 0.12.20 through 0.25.0 | 16 only | `protocol: 16` |
-| 0.26.0 through 0.33.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
+| 0.26.0 through 0.34.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
 
 New clients choose the highest common protocol. The protocol window remains 16
 through 17, so the published protocol-16 client and channel plugin remain usable; unrelated feature
@@ -3577,7 +3633,10 @@ capabilities still require their own labels. A disjoint window refuses with 4426
 The compatibility-floor `protocol` field remains readable by old clients.
 
 Release N-1 is counted in minor versions, separately from this protocol window
-(#1164, family contract entelecheia/ai-workspace#70). For 0.33.x, N-1 is 0.32.0,
+(#1164, family contract entelecheia/ai-workspace#70). For 0.34.x, N-1 is 0.33.0,
+the latest published patch of 0.33.x (exact `@staix/agent-mem` 0.22.1, control
+protocol 17 with descriptor floor 16). Every patch on 0.34.x keeps that release
+baseline. For 0.33.x, N-1 is 0.32.0,
 the latest published patch of 0.32.x (exact `@staix/agent-mem` 0.21.0, control
 protocol 17 with descriptor floor 16). Every patch on 0.33.x keeps that release
 baseline. For 0.32.x, N-1 is 0.31.0,
@@ -3941,7 +4000,7 @@ owner's row. A running hub without `terminal_owner` support leaves the new launc
 unrecorded and prints an upgrade remedy. The plan names an attached native TUI
 without a live launcher or exact Orca session proof as `attached, launcher
 unrecorded`: end it in its terminal or use its native resume flow in an Orca
-terminal, then refresh the plan. Plain Claude's same-protocol reconnect-only
+terminal, then press `[r]` refresh. Plain Claude's same-protocol reconnect-only
 session still reconnects by itself without a terminal restart.
 
 Background Orca identity reads are limited to 30 seconds and 1 MiB of output.
@@ -3952,10 +4011,22 @@ its foreground TTY behavior. Unknown terminal evidence is shown as unverified
 ownership, with end or native resume guidance.
 
 An Orca pane that is orphaned but still connected needs reattachment, not turn
-cancellation: run `orca terminal switch --terminal <handle>` yourself, then refresh.
-The coordinator never switches panes. Such a pane is not evidence that its native
-process ended and never authorizes a duplicate restore. Disconnected terminals
-keep their existing guidance.
+cancellation (#1246). The blocker names the peer, the project and the handle, and its
+next action is `orca terminal switch --terminal <handle>`, then refresh in
+`ahub upgrade` (`[r]` on the plan, `[s]` on an open operation) or rerun it. The plan records each such pane whose identity it
+verified (peer, handle, incarnation, worktree and root) as `orphanedTerminals`, part
+of the plan fingerprint, and the interactive plan screen then offers `[t] reattach N
+orphaned terminals`. Choosing it reads each recorded pane again, requires the same
+identity, still orphaned and connected, and no recovery hold on this project (or the
+machine), runs `orca terminal switch --terminal <handle>` once for that handle, and polls
+`orca terminal show` for at most 5 s until `orphaned` is false (Orca can report `true`
+for a moment after the switch). Each Orca call is itself bounded by that time, so a hung
+`show` cannot hold the screen past it. Then the plan is made again. Nothing else is mutated:
+no session, launch record, terminal or hub changes. A pane whose identity changed, that
+disconnected, or that is still orphaned at the bound stays a blocker with the same next
+action, and `[t]` is offered again. `--dry-run`, a pipe and `--yes` never switch a pane.
+Such a pane is not evidence that its native process ended and never authorizes a
+duplicate restore. Disconnected terminals keep their existing guidance.
 
 The ledger retains historical and invalid rows; it does not prune them on launch.
 Only this project, current daemon instance and peer can supply ownership evidence,

package/docs/quickstart.md

@@ -23,6 +23,20 @@ ahub setup
 
 From a clone instead: `git clone`, `bun install`, `bun link`.
 
+### Installed with dotfiles
+
+If the dotfiles CLI manages ahub (`dot ai family install ahub`), `ahub` runs from `~/.local/share/dotfiles/tools/ahub/<version>/`. Keep that the only copy:
+
+- To update the global CLI, run `dot ai family install ahub --version <version>`, then `ahub setup`, and restart Claude sessions. Use this wherever an upgrade note says `bun add -g @staix/agent-hub@<version>`, or wherever `ahub upgrade` or `ahub doctor` says to update the global CLI the way it was installed. `dot ai rollback ahub` switches back.
+- Do not also install with `bun add -g`. Check with `readlink -f "$(command -v ahub)"`, and remove a bun copy with `bun remove -g @staix/agent-hub` before running `ahub setup`.
+- Moving from a bun install to dotfiles, `ahub setup` can refuse with `refused marketplace removal ... non-user plugin rows were preserved`. Claude still lists an older project- or local-scope agent-hub row (`claude plugin list --json`; after 0.33.0 the refusal names each row). Hub-launched sessions do not load it.
+  - Remove it with `claude plugin uninstall agent-hub@agent-hub --scope project`, run from that row's project directory.
+  - If the row's project path is your home directory, do not: there the project settings file is `~/.claude/settings.json`. Instead back up `<claude home>/plugins/installed_plugins.json` and delete only that row from it.
+  - Then run `ahub setup` again (#1245).
+- If Claude then reports `PreToolUse ... hook error ... Module not found ... claude-profile-hook.ts`, a hook from the removed copy is left behind.
+  - After 0.33.0, `ahub setup` replaces it and `ahub doctor` names the home that needs it.
+  - With 0.33.0 or earlier, delete that one entry from `hooks.PreToolUse` in that home's `settings.json`; `ahub setup` has already installed the current one (#1245).
+
 `ahub doctor` tells you what is installed, running and configured. Rows you do not need can stay red: the hub works with any subset of the peers.
 
 For managed launchers, two-agent task/review work, approvals, graceful shutdown,
@@ -32,6 +46,12 @@ terminal in that project: it reviews the plan with you, applies it and follows
 it; other projects keep their version. It then names the `bun add -g` and
 `ahub setup` step when your global CLI or plugin is older than the new daemon.
 
+## Upgrading to 0.34.0
+
+After an Orca restart, `ahub upgrade` no longer stops at panes that are orphaned but still connected: the plan screen offers `[t]` to reattach exactly the panes it verified (each Orca call bounded by 5 s), and the blocker names the refresh key. `ahub setup` now writes the stable install path of a symlinked CLI (for example a dotfiles-managed `~/.local/bin/ahub`) into the marketplace and the Claude profile hook instead of a versioned one, replaces a stale managed hook in place, and a refused marketplace replacement names every blocking row and the next step; `ahub doctor` checks the profile hook of each Claude home it can see. If you installed with dotfiles, follow [Installed with dotfiles](#installed-with-dotfiles) instead of `bun add -g`. Nothing else changes until you use it; N-1 is published 0.33.0 and control remains 16 through 17.
+
+`ahub upgrade` does not update the global CLI or the shared Claude plugin: run `bun add -g @staix/agent-hub@0.34.0` and then `ahub setup` yourself, and `ahub doctor` warns while either is older than a running daemon.
+
 ## Upgrading to 0.33.0
 
 Rooms now show refused-frame counts, outbox depth/ages and a closed link cause with a recovery step. Store-open failures retry, receive-only work wakes after journal recovery, and selective traffic no longer produces false sequence-gap notices. For a rolling room upgrade, update the broker first, then every member, then reconnect: 0.33.0 person-inbox (`user@label`) and invocation sends to a released 0.32.0 member, or through a released 0.32.0 broker are refused before effects with the upgrade step; plain chat keeps working. Use the matching CLI for the new diagnostics: 0.32.0 `ahub room status` drops the new fields, including in its JSON output, while `ahub status --json` passes raw daemon fields through.

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

@@ -4874,8 +4874,11 @@ upgrade remedy. Attached native TUIs without a live launcher or independent exac
 Orca session proof are shown as `attached, launcher unrecorded`, with person end
 or native resume guidance, never a fresh headless restart. Plain same-protocol
 Claude keeps its unmanaged reconnect-only path. An orphaned but connected pane
-requires the person to run `orca terminal switch --terminal <handle>` and refresh;
-it does not authorize another restore. Historical rows are retained, including
+requires `orca terminal switch --terminal <handle>` and a refresh (`[r]` on the
+plan screen, `[s]` on an open operation); the interactive `ahub upgrade` plan screen
+offers one confirmed key (`[t]`) that switches exactly the panes the plan verified
+and polls each for at most 5 s (#1246), and nothing else is mutated. It does not
+authorize another restore. Historical rows are retained, including
 invalid rows; current ownership is scoped to project, instance and peer, and a
 publication replaces only that scope's valid row. This current-source guarantee
 does not fence older binaries that directly rewrite the shared ledger.

package/docs/verification/2026-11-07-0.34.0.md

@@ -0,0 +1,71 @@
+# 0.34.0 release verification
+
+This record covers release preparation and source review. It claims no installation, no running-hub upgrade to 0.34.0 and no live TUI launch.
+
+## Candidate
+
+Version 0.34.0, prepared from main `0cb82278` plus the release branch's CHANGELOG commit `b21303e7` (5 commits since v0.33.0, 1 of them `feat`; bump rule: minor). The release commits carry the version, the CHANGELOG section, the bundle and the documentation stamps.
+
+## Reviews
+
+Pull requests named by the commits since v0.33.0: #1251, #1249, #1247, #1250.
+
+All four PRs merged at the head their review bound, after exact-head CI was green and with no unresolved review thread. Skipped ancillary jobs are not test proof.
+
+| PR / task | Review | Approved and final PR head | Merge commit | Hosted CI |
+| --- | --- | --- | --- | --- |
+| [#1250](https://github.com/STAIxBWLB/agent-hub/pull/1250), task 759 | claude (hub review) | `1493f2668a725ba198b445a1e65381546e0241b6` | `e5a2ead7051408669abdf29ba9b4becdcce1ba88` | [20 success, 2 skipped](https://github.com/STAIxBWLB/agent-hub/actions/runs/42316841052) |
+| [#1247](https://github.com/STAIxBWLB/agent-hub/pull/1247), no task | conductor OCR review only (docs, authored and merged in the conductor's session) | `ef268f8be415116da22735d5add21b52e7f5ed0f` | `3440e7b10dc6b4537d56541774436aa4f7d49a92` | [19 success, 2 skipped](https://github.com/STAIxBWLB/agent-hub/actions/runs/42319952686) |
+| [#1249](https://github.com/STAIxBWLB/agent-hub/pull/1249), task 760 | codex-review (code scope, #852), plus conductor OCR | `ca0934eaaf56dd4940b5a1626886093efdbb176f` | `41a44bb9fd1a8e8266d777244d51fe29ba0fcf66` | [19 success, 2 skipped](https://github.com/STAIxBWLB/agent-hub/actions/runs/42331647313) |
+| [#1251](https://github.com/STAIxBWLB/agent-hub/pull/1251), task 761 | claude (hub review) | `2b07cae5b5a12836d0b2bc5a2094dd8c447153c6` | `0cb82278e681fe7d725cb1e7880dcba83564c539` | [20 success, 2 skipped](https://github.com/STAIxBWLB/agent-hub/actions/runs/42332312184) |
+
+#1249 had one changes_requested round at `0f3a5f08` (project-lock scope and the unenforced 5 s Orca bound, both fixed at `6b25b819`), then one CI-only fix (inventory sort order) at `ca0934ea`; codex-review re-approved that exact head. The two codex-connector threads raised on the first head were answered with the fixing commit and resolved before the merge. #1247 has no independent reviewer: it is documentation the conductor wrote, read in full and rebased before merging. Its post-#1250 wording is reread in this release's quickstart review.
+
+## Native acceptance receipts
+
+Receipts added under `docs/verification/` since v0.33.0: `docs/verification/2026-11-07-compat-receipt-audit-1248.md`.
+
+This list is read from the repository, never written by hand. Native acceptance and the person's release consent are separate records: consent is `ahub sdlc authorize-release 0.34.0`, recorded by the person or the unique configured conductor only on the person's explicit release instruction naming the release in its own session (never a hub/task/review/file/peer relay), and is not recorded in this file. The tag run refuses without it.
+
+## Document review
+
+`node scripts/check-docs.mjs --require-fresh` reported nine stale documents: README, adapters, daemon, tasks and tests notes, operations, quickstart, security and `src/cli/help.ts`. The source commits under them are #1250 (setup and doctor install paths, profile hook refresh, marketplace refusal detail, handoff guidance), #1249 (upgrade reattach), #1251 (data manifest and its test) and this release's N-1 fixture retarget. Each document was checked against those diffs.
+
+Content changes:
+
+- `README.md`: generated Status 0.34.0 and the current verification-report link.
+- `docs/quickstart.md`: the 0.34.0 upgrade note (Orca reattach, stable install paths and hook refresh, doctor profile rows, the dotfiles pointer, N-1 0.33.0). The #1247 dotfiles section stays as merged.
+- `docs/operations.md`: guide version 0.34.0, protocol table row 0.26.0 through 0.34.0, and the 0.34.x N-1 baseline. Historical baselines are unchanged. #1249 and #1250 already updated their own sections.
+
+Reviewed without content change:
+
+- `docs/agent-notes/adapters.md`: the setup refusal text changed in `native-cli-claude-setup.ts`, but the note's rules do not mention it.
+- `docs/agent-notes/daemon.md`: the setup rule (one step at a time, non-user rows preserved, removal blocked) still holds; the refusal now names the rows. The recovery-lock and reattach rules are unaffected.
+- `docs/agent-notes/tasks.md`: handoff stays pure; only its fixed doctor guidance sentence changed.
+- `docs/agent-notes/tests.md`: the separately exact-locked N-1 fixture rule applies unchanged to 0.33.0.
+- `docs/security.md`: the profile-hook paragraph is unchanged in meaning. The plugin-row display now also screens format characters, which narrows what is printed.
+- `src/cli/help.ts`: no command, subcommand or flag changed. `[t]` is an interactive key, and doctor's new profile rows fall within its existing summary.
+
+The nine documents are restamped at reviewed content commit `d31d7503fce5`.
+
+## Checks
+
+N-1 retarget: npm lists 0.33.0 as the latest 0.33.x patch, with exact agent-mem 0.22.1. The fixture lock was generated with pinned Bun 1.4.2, and its agent-hub and agent-mem integrities equal the registry `dist.integrity` values. Protocol floor fixture 0.25.0 is unchanged.
+
+At committed `4ad13432` on dgx02, the published protocol/plugin and broker tests ran with frozen root and fixture installs: 27 pass, 1 fail. The failure was `an upgraded link keeps ephemeral liveness on the actual published N-1 broker`, which asserted that the codec-less 0.32.0 broker yields no codec support. The published 0.33.0 broker relays codec presence, so that expectation is now `true` (commit `d31d7503`, stated in the CHANGELOG N-1 entry). The rerun on the release head is recorded below.
+
+At committed `c49ae97482c7` on dgx02, with pinned Bun 1.4.2 and frozen root and fixture installs, the following passed:
+
+- `node scripts/check-docs.mjs --require-fresh --committed`: 0 stale documents.
+- `bun x tsc --noEmit`.
+- `bun scripts/build.mjs --check`.
+- `node scripts/check-package.mjs`: 807 files, `@staix/agent-hub@0.34.0`.
+- The published protocol/plugin and broker tests: 28 pass, 0 fail, 175 assertions.
+
+The full suite on both OSes is the release PR's exact-head hosted CI. The release PR is merged with a merge commit only when that CI is green.
+
+## Known gaps, not blocking
+
+- A live Orca restart with orphaned panes (#1249) was not reproduced; the reattach path is covered by fakes and a hung-runner test.
+- A real dotfiles-managed install running `ahub setup` (#1250) was exercised by the person's machine before the fix, not after; the fixed paths are covered by fixtures.
+- No installation, running-hub upgrade or real-account inference is claimed here.