diff --git a/.env.example b/.env.example
index b9bfcada0e..c65a8c19e0 100644
--- a/.env.example
+++ b/.env.example
@@ -160,6 +160,11 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
 # Binary for an optional MCP server sidecar (e.g. buzz-dev-mcp for buzz-agent).
 # BUZZ_ACP_MCP_COMMAND=
 
+# Path to an optional version 1 JSON file defining additional stdio MCP servers.
+# This file may contain credentials. Keep it out of Git and restrict it to
+# its owner.
+# BUZZ_ACP_MCP_CONFIG=/absolute/path/to/mcp-servers.json
+
 # Number of parallel agent subprocesses (1–32).
 # BUZZ_ACP_AGENTS=1
 
diff --git a/.github/workflows/auto-tag-on-release-pr-merge.yml b/.github/workflows/auto-tag-on-release-pr-merge.yml
index db34fddc2c..f31d4b835f 100644
--- a/.github/workflows/auto-tag-on-release-pr-merge.yml
+++ b/.github/workflows/auto-tag-on-release-pr-merge.yml
@@ -4,7 +4,7 @@ name: Auto-tag on Release PR Merge
 # prefix; the main chart lane also auto-detects a Chart.yaml version bump so
 # a chart feature PR can publish its own new version when merged:
 #
-#   version-bump/<v>   → tag v<v>        → release.yml (desktop app)
+#   version-bump/<v>   → tag desktop-v<v>        → release.yml (desktop app)
 #   relay-release/<v>  → tag relay-v<v>  → docker.yml (relay image)
 #   chart-release/<v>  → tag chart-v<v>  → helm-chart.yml (main helm chart)
 #   push-chart-release/<v> → tag push-chart-v<v> → push-gateway-helm-chart.yml
@@ -35,6 +35,11 @@ permissions:
 
 jobs:
   auto-tag:
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: read
+      statuses: read
     if: >
       github.event.pull_request.merged == true &&
       github.event.pull_request.head.repo.full_name == github.repository
@@ -57,7 +62,7 @@ jobs:
           case "$BRANCH" in
             version-bump/*)
               VERSION="${BRANCH#version-bump/}"
-              TAG_PREFIX="v" ;;
+              TAG_PREFIX="desktop-v" ;;
             relay-release/*)
               VERSION="${BRANCH#relay-release/}"
               TAG_PREFIX="relay-v" ;;
@@ -85,9 +90,33 @@ jobs:
           {
             echo "enabled=true"
             echo "tag=${TAG_PREFIX}${VERSION}"
+            if [[ "$TAG_PREFIX" == desktop-v ]]; then
+              echo "target_sha=${{ github.event.pull_request.merge_commit_sha }}"
+              echo "desktop=true"
+            else
+              echo "target_sha=$GITHUB_SHA"
+              echo "desktop=false"
+            fi
           } >> "$GITHUB_OUTPUT"
           echo "Tagging ${TAG_PREFIX}${VERSION}"
 
+
+      - name: Verify immutable reviewed desktop candidate
+        if: steps.release.outputs.desktop == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release.outputs.tag }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          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 }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          VERSION="${VERSION#desktop-v}"
+          export VERSION
+          scripts/verify-desktop-release-merge.sh
+
       - name: Create release tagger token
         if: steps.release.outputs.enabled == 'true'
         id: release-tagger
@@ -102,21 +131,22 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.release-tagger.outputs.token }}
           TAG: ${{ steps.release.outputs.tag }}
+          TARGET_SHA: ${{ steps.release.outputs.target_sha }}
         run: |
           set -euo pipefail
           # Check gh's exit status, not its output. A missing ref returns a 404
           # JSON body on stdout, which must not be mistaken for an existing tag.
           if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" --silent 2>/dev/null; then
             EXISTING_SHA="$(gh api "repos/$GITHUB_REPOSITORY/commits/$TAG" --jq .sha)"
-            if [ "$EXISTING_SHA" = "$GITHUB_SHA" ]; then
-              echo "Tag $TAG already exists at $GITHUB_SHA — skipping tag creation"
+            if [ "$EXISTING_SHA" = "$TARGET_SHA" ]; then
+              echo "Tag $TAG already exists at $TARGET_SHA — skipping tag creation"
               exit 0
             else
-              echo "::error::Tag $TAG already exists at $EXISTING_SHA (expected $GITHUB_SHA)"
+              echo "::error::Tag $TAG already exists at $EXISTING_SHA (expected $TARGET_SHA)"
               exit 1
             fi
           fi
           gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
             -f ref="refs/tags/$TAG" \
-            -f sha="$GITHUB_SHA" \
+            -f sha="$TARGET_SHA" \
             --silent
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d4826d985f..d392170f6a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -76,6 +76,8 @@ jobs:
               - '.github/workflows/ci.yml'
       - name: Release workflow source contract
         run: scripts/test-release-ref-contract.sh
+      - name: Desktop release candidate contract
+        run: scripts/test-desktop-release-candidate.sh
       - name: Mobile release contract
         run: |
           scripts/test-mobile-release-contract.sh
@@ -690,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
@@ -702,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
@@ -737,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_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:
diff --git a/.github/workflows/desktop-release-candidate.yml b/.github/workflows/desktop-release-candidate.yml
new file mode 100644
index 0000000000..eddebea685
--- /dev/null
+++ b/.github/workflows/desktop-release-candidate.yml
@@ -0,0 +1,26 @@
+name: Desktop Release Candidate
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: 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:
+          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/release.yml b/.github/workflows/release.yml
index b87e9c8c08..7d5f3fbf40 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,14 +1,13 @@
 name: Release
 
+concurrency:
+  group: desktop-release-${{ github.ref }}
+  cancel-in-progress: false
+
 on:
   push:
     tags:
-      - 'v[0-9]*'
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Semver version matching the v-prefixed dispatch tag"
-        required: true
+      - 'desktop-v[0-9]*'
 
 jobs:
   # Shared setup: verify the immutable release tag, determine the version, and
@@ -19,23 +18,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
-      contents: write
+      contents: read
     outputs:
       version: ${{ steps.version.outputs.version }}
       source_sha: ${{ steps.source.outputs.source_sha }}
     steps:
       - name: Determine version
         id: version
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          INPUT_VERSION: ${{ inputs.version }}
-        run: |
-          if [[ "$EVENT_NAME" == "push" ]]; then
-            VERSION="${GITHUB_REF_NAME#v}"
-          else
-            VERSION="$INPUT_VERSION"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+        run: echo "version=${GITHUB_REF_NAME#desktop-v}" >> "$GITHUB_OUTPUT"
 
       - name: Validate version
         env:
@@ -56,42 +46,9 @@ jobs:
         env:
           VERSION: ${{ steps.version.outputs.version }}
         run: |
-          scripts/verify-release-ref.sh v "$VERSION"
+          scripts/verify-release-ref.sh desktop-v "$VERSION"
           echo "source_sha=$(git rev-parse 'HEAD^{commit}')" >> "$GITHUB_OUTPUT"
 
-      - name: Create versioned GitHub release
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          RELEASE_SHA=$(git rev-parse HEAD)
-          NOTES=""
-          if [[ -f CHANGELOG.md ]]; then
-            NOTES=$(awk "/^## v${VERSION}\$/{found=1; next} found && /^## v/{exit} found && !/^\$/" CHANGELOG.md)
-          fi
-          if [[ -z "$NOTES" ]]; then
-            NOTES="Buzz Desktop v${VERSION}"
-          fi
-          PRERELEASE_FLAGS=()
-          if [[ "$VERSION" =~ -(test|alpha|beta|rc)([.-]|$) ]]; then
-            PRERELEASE_FLAGS=(--prerelease --latest=false)
-          fi
-          gh release create "v${VERSION}" \
-            --target "$RELEASE_SHA" \
-            --title "Buzz Desktop v${VERSION}" \
-            --notes "$NOTES" \
-            "${PRERELEASE_FLAGS[@]}"
-
-      - name: Create rolling auto-update release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh release create buzz-desktop-latest \
-            --prerelease \
-            --title "Buzz Desktop Auto-Update" \
-            --notes "Rolling release for the Tauri auto-updater. Do not download manually — use the versioned release instead." \
-            2>/dev/null || true
-
   release:
     name: Release
     if: github.repository == 'block/buzz'
@@ -99,7 +56,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
       id-token: write # required by block/apple-codesign-action for OIDC
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
@@ -114,7 +71,7 @@ jobs:
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -272,13 +229,19 @@ jobs:
           fi
           echo "dmg=$DMG" >> "$GITHUB_OUTPUT"
 
-          # Find the updater .tar.gz and .sig
+          # Find the updater .tar.gz and .sig. Give each architecture a unique
+          # release basename before artifacts are merged by the final writer.
           ARCHIVE=$(find "$BUNDLE_DIR/macos" -name '*.tar.gz' ! -name '*.sig' -type f | head -1)
           SIG="${ARCHIVE}.sig"
           if [[ -z "$ARCHIVE" || ! -f "$SIG" ]]; then
             echo "::error::Updater archive or signature not found in $BUNDLE_DIR/macos"
             exit 1
           fi
+          RENAMED="$(dirname "$ARCHIVE")/Buzz_${VERSION}_aarch64.app.tar.gz"
+          mv "$ARCHIVE" "$RENAMED"
+          mv "$SIG" "${RENAMED}.sig"
+          ARCHIVE="$RENAMED"
+          SIG="${RENAMED}.sig"
           echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
           echo "archive_name=$(basename "$ARCHIVE")" >> "$GITHUB_OUTPUT"
           echo "sig=$SIG" >> "$GITHUB_OUTPUT"
@@ -289,23 +252,15 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload arm64 DMG to versioned GitHub release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DMG_PATH: ${{ steps.artifacts.outputs.dmg }}
-        run: gh release upload "v${VERSION}" "$DMG_PATH" --clobber
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Apple Silicon release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-macos-arm64
+          if-no-files-found: error
+          path: |
+            ${{ steps.artifacts.outputs.dmg }}
+            ${{ steps.artifacts.outputs.archive }}
+            ${{ steps.artifacts.outputs.sig }}
 
   release-macos-x64:
     name: Release macOS (Intel)
@@ -314,7 +269,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
       id-token: write # required by block/apple-codesign-action for OIDC
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
@@ -330,7 +285,7 @@ jobs:
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -443,6 +398,11 @@ jobs:
             echo "::error::Updater archive or signature not found in $BUNDLE_DIR/macos"
             exit 1
           fi
+          RENAMED="$(dirname "$ARCHIVE")/Buzz_${VERSION}_x64.app.tar.gz"
+          mv "$ARCHIVE" "$RENAMED"
+          mv "$SIG" "${RENAMED}.sig"
+          ARCHIVE="$RENAMED"
+          SIG="${RENAMED}.sig"
           echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
           echo "archive_name=$(basename "$ARCHIVE")" >> "$GITHUB_OUTPUT"
           echo "sig=$SIG" >> "$GITHUB_OUTPUT"
@@ -453,23 +413,15 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload Intel DMG to versioned GitHub release
-        run: gh release upload "v${VERSION}" "$DMG_PATH" --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DMG_PATH: ${{ steps.unsigned.outputs.dmg }}
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Intel macOS release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-macos-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.unsigned.outputs.dmg }}
+            ${{ steps.artifacts.outputs.archive }}
+            ${{ steps.artifacts.outputs.sig }}
 
   release-linux:
     name: Release Linux
@@ -480,7 +432,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
     env:
       # AppImage tools (linuxdeploy, appimagetool) are themselves AppImages.
       # Containers lack FUSE, so we must use the extract-and-run fallback.
@@ -555,7 +507,7 @@ jobs:
       - name: Verify tag-bound release source
         env:
           VERSION: ${{ needs.setup.outputs.version }}
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -689,29 +641,16 @@ jobs:
           SIG_PATH: ${{ steps.linux-artifacts.outputs.sig }}
 
       # NOTE: .deb is NOT auto-updatable (Tauri updater constraint — only AppImage supports it on Linux)
-      - name: Upload Linux artifacts to versioned GitHub release
-        env:
-          VERSION: ${{ needs.setup.outputs.version }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEB_PATH: ${{ steps.linux-artifacts.outputs.deb }}
-          APPIMAGE_PATH: ${{ steps.linux-artifacts.outputs.appimage }}
-        run: |
-          gh release upload "v$VERSION" \
-            "$DEB_PATH" \
-            "$APPIMAGE_PATH" \
-            --clobber
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.linux-artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.linux-artifacts.outputs.sig }}
+      - name: Stage Linux release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-linux-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.linux-artifacts.outputs.deb }}
+            ${{ steps.linux-artifacts.outputs.appimage }}
+            ${{ steps.linux-artifacts.outputs.archive }}
+            ${{ steps.linux-artifacts.outputs.sig }}
 
   release-windows:
     name: Release Windows
@@ -719,7 +658,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
       sig: ${{ steps.read-sig.outputs.sig }}
@@ -735,7 +674,7 @@ jobs:
 
       - name: Verify tag-bound release source
         shell: bash
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: dtolnay/rust-toolchain@e081816240890017053eacbb1bdf337761dc5582 # 1.95.0
         with:
@@ -745,7 +684,7 @@ jobs:
         with:
           node-version: 24.14.1
           # Disable dependency caching: a writable cache in this release workflow
-          # (contents: write, feeds a signed installer) is a poisoning vector. pnpm
+          # (contents: read, feeds a signed installer) is a poisoning vector. pnpm
           # install runs uncached below.
           package-manager-cache: false
 
@@ -827,25 +766,14 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload Windows installer to versioned GitHub release
-        shell: bash
-        run: gh release upload "v${VERSION}" "$EXE_PATH" --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          EXE_PATH: ${{ steps.artifacts.outputs.exe }}
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        shell: bash
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Windows release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-windows-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.artifacts.outputs.exe }}
+            ${{ steps.artifacts.outputs.sig }}
 
   assemble-manifest:
     name: Assemble multi-platform latest.json
@@ -853,7 +781,11 @@ jobs:
     if: |
       always() &&
       needs.setup.result == 'success' &&
-      github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
+      needs.release.result == 'success' &&
+      needs.release-macos-x64.result == 'success' &&
+      needs.release-linux.result == 'success' &&
+      needs.release-windows.result == 'success' &&
+      github.ref == format('refs/tags/desktop-v{0}', needs.setup.outputs.version)
     runs-on: ubuntu-latest
     needs: [setup, release, release-macos-x64, release-linux, release-windows]
     timeout-minutes: 10
@@ -870,7 +802,26 @@ jobs:
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
+
+      - name: Download staged release artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: desktop-release-*
+          path: staged-by-platform
+
+      - name: Flatten staged artifacts without basename collisions
+        run: |
+          set -euo pipefail
+          mkdir staged
+          while IFS= read -r -d '' file; do
+            name="$(basename "$file")"
+            [[ ! -e "staged/$name" ]] || {
+              echo "::error::release artifact basename collision: $name"
+              exit 1
+            }
+            cp "$file" "staged/$name"
+          done < <(find staged-by-platform -type f -print0)
 
       - name: Write signature files
         env:
@@ -899,7 +850,7 @@ jobs:
           write_sig "$RESULT_LINUX" linux-x86_64 "$SIG_LINUX"
           write_sig "$RESULT_WIN" windows-x86_64 "$SIG_WIN"
 
-      - name: Verify archive URLs are accessible
+      - name: Verify draft release has every updater archive
         env:
           RESULT_ARM64: ${{ needs.release.result }}
           RESULT_X64: ${{ needs.release-macos-x64.result }}
@@ -911,39 +862,19 @@ jobs:
           ARCHIVE_WIN: ${{ needs.release-windows.outputs.archive_name }}
         run: |
           set -euo pipefail
-          BASE="https://github.com/block/buzz/releases/download/buzz-desktop-latest"
-          ARCHIVES=()
-
-          add_archive() {
-            local result="$1" platform="$2" archive="$3"
-            if [[ "$result" == "success" ]]; then
-              [[ -n "$archive" ]] || { echo "::error::Missing archive name for successful platform: $platform"; exit 1; }
-              ARCHIVES+=("$archive")
-            fi
-          }
-
-          add_archive "$RESULT_ARM64" darwin-aarch64 "$ARCHIVE_ARM64"
-          add_archive "$RESULT_X64" darwin-x86_64 "$ARCHIVE_X64"
-          add_archive "$RESULT_LINUX" linux-x86_64 "$ARCHIVE_LINUX"
-          add_archive "$RESULT_WIN" windows-x86_64 "$ARCHIVE_WIN"
-
-          for name in "${ARCHIVES[@]}"; do
-            echo "Checking $BASE/$name ..."
-            success=false
-            for attempt in 1 2 3; do
-              if curl -fsI "$BASE/$name" > /dev/null 2>&1; then
-                success=true
-                break
-              fi
-              echo "Attempt $attempt failed for $name, retrying in 10s..."
-              sleep 10
-            done
-            if [ "$success" != "true" ]; then
-              echo "::error::Archive not accessible after 3 attempts: $BASE/$name"
-              exit 1
+          assets=$(find staged -type f -exec basename {} \;)
+          for spec in \
+            "$RESULT_ARM64:$ARCHIVE_ARM64" \
+            "$RESULT_X64:$ARCHIVE_X64" \
+            "$RESULT_LINUX:$ARCHIVE_LINUX" \
+            "$RESULT_WIN:$ARCHIVE_WIN"; do
+            result="${spec%%:*}"
+            archive="${spec#*:}"
+            if [[ "$result" == success ]]; then
+              [[ -n "$archive" ]] || { echo "::error::successful platform has no archive"; exit 1; }
+              grep -Fxq "$archive" <<<"$assets" || { echo "::error::draft release missing $archive"; exit 1; }
             fi
           done
-          echo "All archive URLs verified."
 
       - name: Generate unified latest.json
         env:
@@ -957,7 +888,7 @@ jobs:
           ARCHIVE_WIN: ${{ needs.release-windows.outputs.archive_name }}
         run: |
           set -euo pipefail
-          BASE="https://github.com/block/buzz/releases/download/buzz-desktop-latest"
+          BASE="https://github.com/block/buzz/releases/download/desktop-v${VERSION}"
           TRIPLES=()
 
           add_triple() {
@@ -977,6 +908,45 @@ jobs:
           bash desktop/scripts/generate-oss-latest-json.sh "$VERSION" "${TRIPLES[@]}" > latest.json
           cat latest.json
 
-      - name: Upload latest.json to rolling release
+      - name: Create or verify versioned draft
         run: |
-          gh release upload buzz-desktop-latest latest.json --clobber
+          set -euo pipefail
+          NOTES_FILE="${RUNNER_TEMP}/release-notes.md"
+          awk "/^## v${VERSION}\$/{found=1; next} found && /^## v/{exit} found" CHANGELOG.md > "$NOTES_FILE"
+          [[ -s "$NOTES_FILE" ]] || { echo "::error::missing non-empty changelog block for v${VERSION}"; exit 1; }
+          PRERELEASE_FLAGS=()
+          if [[ "$VERSION" == *-* ]]; then
+            PRERELEASE_FLAGS=(--prerelease --latest=false)
+          fi
+          if gh release view "desktop-v${VERSION}" >/dev/null 2>&1; then
+            EXISTING_SHA=$(gh release view "desktop-v${VERSION}" --json targetCommitish --jq .targetCommitish)
+            IS_DRAFT=$(gh release view "desktop-v${VERSION}" --json isDraft --jq .isDraft)
+            [[ "$EXISTING_SHA" == "${{ needs.setup.outputs.source_sha }}" ]] || {
+              echo "::error::existing release targets $EXISTING_SHA, not the immutable source"; exit 1;
+            }
+            if [[ "$IS_DRAFT" != true ]]; then
+              echo "already_published=true" >> "$GITHUB_ENV"
+            fi
+          else
+            gh release create "desktop-v${VERSION}" \
+              --draft \
+              --target "${{ needs.setup.outputs.source_sha }}" \
+              --title "Buzz Desktop v${VERSION}" \
+              --notes-file "$NOTES_FILE" \
+              "${PRERELEASE_FLAGS[@]}"
+          fi
+
+      - name: Upload complete artifact set to versioned draft
+        if: env.already_published != 'true'
+        run: |
+          mapfile -t files < <(find staged -type f -print)
+          [[ "${#files[@]}" -gt 0 ]] || { echo "::error::no staged release artifacts"; exit 1; }
+          gh release upload "desktop-v${VERSION}" "${files[@]}" --clobber
+
+      - name: Publish complete versioned release
+        if: env.already_published != 'true'
+        run: gh release edit "desktop-v${VERSION}" --draft=false
+
+      - name: Upload latest.json to rolling release last
+        if: ${{ !contains(needs.setup.outputs.version, '-') }}
+        run: gh release upload buzz-desktop-latest latest.json --clobber
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..1bf2efb66b
--- /dev/null
+++ b/.release/desktop-candidate.json
@@ -0,0 +1,8 @@
+{
+  "schema": 1,
+  "version": "0.5.3",
+  "base_sha": "54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a",
+  "previous_tag": "v0.5.2",
+  "tag": "desktop-v0.5.3",
+  "commit_count": 58
+}
diff --git a/AGENTS.md b/AGENTS.md
index 7ff0eb4d47..c2e4ddbf23 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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.
 
@@ -164,6 +168,8 @@ check existing reply handlers for the pattern.
 (`BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`) are auto-injected
 by the ACP harness into managed agent subprocesses. In development, set
 `BUZZ_PRIVATE_KEY` and `BUZZ_RELAY_URL` in your environment manually.
+Prefer `--private-key-file` / `--private-key-stdin` over `--private-key` on
+argv (shell history / `ps` leak — #4032).
 
 ### Building the CLI
 
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 90cbbac0cf..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`.
 
@@ -447,7 +447,7 @@ The subscriber uses a **dedicated** `redis::aio::PubSub` connection — not from
 
 **Reconnection:** exponential backoff 1s → 30s (`backoff_secs * 2`). Backoff resets to 1s only after a clean stream end, not on each reconnect attempt.
 
-**Presence:** `SET buzz:presence:{pubkey_hex} {status} EX 90` — 90-second TTL (3× the 30-second heartbeat interval). Single missed heartbeat does not cause presence flap.
+**Presence:** `SET buzz:presence:{pubkey_hex} {status} EX 180` — 180-second TTL (3× the 60-second heartbeat interval). Single missed heartbeat does not cause presence flap.
 
 **Typing indicators:**
 ```
@@ -797,7 +797,7 @@ Docker Compose provides the full local development stack. All services include h
 | Pattern | Type | TTL | Purpose |
 |---------|------|-----|---------|
 | `buzz:channel:{uuid}` | Pub/Sub channel | — | Event fan-out (single-community form; shared multi-community Redis must use `buzz:{community}:channel:{uuid}` or equivalent) |
-| `buzz:presence:{pubkey_hex}` | String | 90s | Online/away status (single-community form; shared multi-community Redis must scope by community) |
+| `buzz:presence:{pubkey_hex}` | String | 180s | Online/away status (single-community form; shared multi-community Redis must scope by community) |
 | `buzz:typing:{channel_uuid}` | Sorted Set | 60s | Active typers (5s window; shared multi-community Redis must scope by community) |
 
 ### Full-Text Search (Postgres FTS)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d83087fc26..71a4bbd449 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,73 @@
 # Changelog
 
+## 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 ea5b02aaab..fa02e17ce3 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",
@@ -897,7 +920,7 @@ name = "buzz-cli"
 version = "0.1.0"
 dependencies = [
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-persona",
  "buzz-sdk",
@@ -938,7 +961,7 @@ dependencies = [
 name = "buzz-core"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "hmac 0.13.0",
@@ -980,7 +1003,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 +1130,7 @@ dependencies = [
  "appattest",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "byteorder",
  "chrono",
  "getrandom 0.4.3",
@@ -1142,7 +1165,7 @@ dependencies = [
  "async-compression",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-audit",
  "buzz-auth",
  "buzz-conformance",
@@ -1252,7 +1275,7 @@ name = "buzz-test-client"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-media",
  "buzz-sdk",
@@ -1278,6 +1301,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 +1387,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 +1655,7 @@ dependencies = [
  "itoa",
  "rustversion",
  "ryu",
+ "serde",
  "static_assertions",
 ]
 
@@ -2153,6 +2216,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 +2714,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 +2777,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 +2793,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 +3117,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 +3195,7 @@ dependencies = [
 name = "git-credential-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "nostr",
  "serde_json",
  "zeroize",
@@ -3110,7 +3205,7 @@ dependencies = [
 name = "git-sign-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "libc",
@@ -3285,7 +3380,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",
@@ -3591,7 +3686,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 +3717,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core 0.61.2",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
@@ -4375,6 +4470,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 +4562,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 +4593,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 +4699,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 +4712,7 @@ dependencies = [
  "mesh-llm-types",
  "model-artifact",
  "nostr-sdk",
- "prost",
+ "prost 0.14.3",
  "rand 0.10.1",
  "rustls",
  "serde",
@@ -4647,7 +4801,7 @@ dependencies = [
  "argon2",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "chacha20poly1305",
  "chrono",
@@ -4696,7 +4850,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 +4891,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 +4939,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 +4976,7 @@ dependencies = [
  "anyhow",
  "hex",
  "iroh",
- "prost",
+ "prost 0.14.3",
  "serde_json",
  "sha2 0.10.9",
 ]
@@ -4953,7 +5107,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 +5145,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 +5312,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 +5440,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 +5601,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 +5703,7 @@ version = "0.44.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bech32",
  "bip39",
  "bitcoin_hashes",
@@ -5518,9 +5743,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "fb94d61a467a869a6790b907838a9bea82c813d567d9fcbac995f207be8cee4b"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -5949,7 +6174,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 +6189,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 +6202,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 +6221,7 @@ checksum = "56d658ba1faf63f7b9c492cfbe6e0ec365440a16132d3270c1065f7b33f1b638"
 dependencies = [
  "opentelemetry 0.32.0",
  "opentelemetry_sdk 0.32.1",
- "prost",
+ "prost 0.14.3",
  "tonic",
  "tonic-prost",
 ]
@@ -6078,6 +6303,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"
@@ -6259,6 +6502,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 +6644,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 +6710,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 +6895,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 +6912,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 +6945,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 +6980,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 +7075,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 +7407,7 @@ dependencies = [
  "thiserror 2.0.18",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7116,7 +7470,7 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7128,6 +7482,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 +7640,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 +7688,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 +7778,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 +7846,7 @@ dependencies = [
  "async-trait",
  "aws-creds",
  "aws-region",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "cfg-if 1.0.4",
  "futures-util",
@@ -7856,6 +8247,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"
@@ -8066,6 +8469,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 +8626,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 +8655,7 @@ dependencies = [
  "anyhow",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "blake3",
  "clap",
  "futures-util",
@@ -8337,6 +8762,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 +8802,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 +8908,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 +9049,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 +9304,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 +9378,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 +9530,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 +9698,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 +9799,7 @@ checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "h2",
  "http",
@@ -9200,7 +9828,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
- "prost",
+ "prost 0.14.3",
  "tonic",
 ]
 
@@ -9210,8 +9838,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",
 ]
 
@@ -9500,6 +10128,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 +10157,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 +10178,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 +10206,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 +11145,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 +11213,7 @@ checksum = "3e1e496dcbe6a09017acdfaf48e1a646735e7ff5b2a49e2c7e081cca77a59bc8"
 dependencies = [
  "anyhow",
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "clap",
  "crc32fast",
@@ -10585,7 +11250,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..3268cfaf8d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,6 +26,7 @@ members = [
     "crates/buzz-pair-relay",
     "crates/buzz-relay-mesh",
     "crates/buzz-dev-mcp",
+    "crates/buzz-voice",
     "examples/countdown-bot",
 ]
 exclude = ["desktop/src-tauri"]
diff --git a/Justfile b/Justfile
index a2fa408e7f..64a1f36daf 100644
--- a/Justfile
+++ b/Justfile
@@ -276,6 +276,7 @@ test-unit:
     #!/usr/bin/env bash
     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
@@ -725,7 +726,7 @@ bump-relay-version version:
     cargo update -p buzz-relay
     echo "Bumped buzz-relay to {{ version }} and regenerated Cargo.lock"
 
-# Open or update the desktop release PR (signed desktop app)
+# Open or update the desktop release PR from an immutable origin/main snapshot
 release-desktop *ARGS:
     #!/usr/bin/env bash
     set -euo pipefail
@@ -735,7 +736,7 @@ release-desktop *ARGS:
     else
         VERSION="$ARG"
     fi
-    just _release-pr desktop "$VERSION"
+    scripts/prepare-desktop-release.sh "$VERSION"
 
 # Open or update the relay release PR (ghcr.io/block/buzz image)
 release-relay *ARGS:
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 063b813e2c..e729f8b50c 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 | `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 and relay releases use metadata PRs. 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,12 +47,28 @@ or mobile GitHub Release.
 
 ### Desktop
 
-1. **`just release-desktop`** runs locally on `main`, creates or updates a
-   `version-bump/<version>` PR, bumps the desktop manifests, regenerates
-   lockfiles, and updates `CHANGELOG.md`.
-2. **Merge the PR.** `auto-tag-on-release-pr-merge` pushes `v<version>`.
-3. **The tag triggers `release.yml`.** It builds, signs, notarizes, and
-   publishes the desktop app for macOS and Linux.
+1. Run `just release-desktop <version>` from a clean, up-to-date `main` checkout.
+   The script fetches the current `origin/main`, regenerates
+   `version-bump/<version>` as one
+   deterministic candidate commit, records the frozen base and proposed
+   `desktop-v<version>` tag in `.release/desktop-candidate.json`, updates every
+   desktop manifest and lockfile, writes a full-SHA changelog, and opens or
+   updates the PR.
+2. Review the recorded base and candidate SHA, the complete changelog, and CI.
+   The required **Desktop Release Candidate** check validates the exact head.
+   Authorization is either an approval on that exact head or a permitted Default
+   ruleset bypass at merge time. Any regeneration changes the head and requires
+   the checks—and, for the review path, approval—to run again.
+3. **Squash merge** the PR. The protected branch must still be exactly the
+   recorded base; otherwise regenerate the candidate from current `main`.
+4. `auto-tag-on-release-pr-merge` verifies the frozen parent, full-tree identity,
+   required checks, and one of the two authorization paths, then tags the squash
+   commit as `desktop-v<version>`.
+5. The tag triggers `release.yml`. It builds and stages Apple Silicon and Intel
+   macOS, Windows, and Linux artifacts; publishes the versioned release only
+   after the complete set succeeds; then updates the rolling updater manifest
+   last for stable versions. A failed platform leaves no partially published
+   versioned release.
 
 ### Relay
 
@@ -144,12 +165,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 `v<version>` tag. Select that tag in the ref picker and
-provide the matching semver version without the `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.
@@ -171,7 +195,7 @@ for the private pipeline contract.
 
 Desktop publishes two GitHub releases:
 
-1. **`v<version>`**: the user-facing release with installers.
+1. **`desktop-v<version>`**: the user-facing release with installers.
 2. **`buzz-desktop-latest`**: the rolling auto-updater release.
 
 Mobile publishes only annotated `mobile-vX.Y.Z-rc.N` git tags. Store artifacts
@@ -184,9 +208,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 `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
@@ -204,20 +230,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
@@ -232,10 +265,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 approval when using the review path.
+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/SECURITY.md b/SECURITY.md
index 09ea73022b..9a0211a750 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -90,7 +90,10 @@ a rotated key from a leftover file.
 When no keyring backend is available (headless Linux with no Secret Service, for
 example), keys fall back to a `0o600` owner-only file. The `BUZZ_PRIVATE_KEY`
 environment variable, when set, always takes precedence over both stores — this
-is how harnessed agents and CI receive their identity.
+is how harnessed agents and CI receive their identity. The `buzz` CLI also
+accepts `--private-key-file` / `--private-key-stdin`; passing `--private-key` on
+argv is deprecated because the secret enters shell history and process listings
+(see #4032).
 
 ### Input Validation
 
diff --git a/VISION.md b/VISION.md
index b09f661ee3..900e5a9475 100644
--- a/VISION.md
+++ b/VISION.md
@@ -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..b02d1bc92d
--- /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 ninety 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. Ninety seconds of a 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/README.md b/crates/buzz-acp/README.md
index e6164b02dd..d5384df7e2 100644
--- a/crates/buzz-acp/README.md
+++ b/crates/buzz-acp/README.md
@@ -111,6 +111,7 @@ All configuration is via environment variables (or CLI flags — every env var h
 | `BUZZ_ACP_AGENT_COMMAND` | no | `goose` | Agent binary to spawn. |
 | `BUZZ_ACP_AGENT_ARGS` | no | `acp` | Agent arguments (comma-separated). |
 | `BUZZ_ACP_MCP_COMMAND` | no | `""` (empty) | Path to an optional MCP server binary to provide to the agent subprocess. |
+| `BUZZ_ACP_MCP_CONFIG` | no | `""` (empty) | Path to a version 1 JSON file defining additional stdio MCP servers. |
 | `BUZZ_ACP_IDLE_TIMEOUT` | no | `620` | Idle timeout: max seconds of silence before cancelling a turn. Resets on any agent stdout activity. |
 | `BUZZ_ACP_MAX_TURN_DURATION` | no | `7200` | Absolute wall-clock cap per turn (safety valve). |
 | `BUZZ_API_TOKEN` | no | — | API token (required if relay enforces token auth). |
@@ -119,6 +120,60 @@ All configuration is via environment variables (or CLI flags — every env var h
 
 **Legacy env vars:** `BUZZ_ACP_PRIVATE_KEY`, `BUZZ_ACP_API_TOKEN`, and `BUZZ_ACP_TURN_TIMEOUT` (replaced by `BUZZ_ACP_IDLE_TIMEOUT`) are still accepted as fallbacks.
 
+### Multiple MCP servers
+
+Use `--mcp-config <path>` or `BUZZ_ACP_MCP_CONFIG` to add named stdio MCP
+servers:
+
+```json
+{
+  "version": 1,
+  "servers": [
+    {
+      "name": "analytics",
+      "command": "/opt/mcp/analytics-server",
+      "args": ["--stdio"],
+      "env": {
+        "ANALYTICS_TOKEN": "replace-me"
+      }
+    }
+  ]
+}
+```
+
+The JSON is strict. The only top-level fields are `version` and `servers`.
+Each server has `name`, `command`, `args`, and `env`. Server names must be
+unique, contain 1 to 128 ASCII bytes using only letters, digits, `_`, or `-`,
+and cannot contain `__`. Names are checked across both structured entries and
+the legacy server.
+
+The config file is limited to 64 KiB. A harness can have at most 16 MCP
+servers in total, including the server from `BUZZ_ACP_MCP_COMMAND`. An
+unreadable file, malformed JSON, an unsupported version, an unknown field, or
+an invalid server entry stops startup. Buzz does not silently drop a server.
+
+`BUZZ_ACP_MCP_COMMAND` keeps its current behavior. It defines one privileged
+Buzz companion and receives the relay URL and Buzz identity credentials.
+For a structured server, Buzz puts only the values listed in its `env` object
+into the ACP `env` list. Protected Buzz identity and authentication keys are
+rejected. Buzz sends the list to the ACP adapter in `session/new`, and the
+adapter controls the MCP processes. Treat the adapter as a credential broker
+and use one you trust.
+
+The adapter still inherits the harness environment so its shell tools can use
+the `buzz` CLI. Some adapters may propagate inherited variables to MCP child
+processes. Per-server `env` entries are explicit configuration, not a process
+isolation boundary. Use a separate account, container, or credential-brokered
+service when the MCP process must not inherit adapter credentials.
+
+If the JSON contains secrets, keep it outside Git and restrict the file to its
+owner. On Unix:
+
+```bash
+chmod 600 /absolute/path/to/mcp-servers.json
+buzz-acp --mcp-config /absolute/path/to/mcp-servers.json
+```
+
 ### Parallel Agents & Heartbeat
 
 | Flag | Env Var | Default | Description |
diff --git a/crates/buzz-acp/src/acp.rs b/crates/buzz-acp/src/acp.rs
index 8a698954a0..cda640305d 100644
--- a/crates/buzz-acp/src/acp.rs
+++ b/crates/buzz-acp/src/acp.rs
@@ -20,6 +20,8 @@ use crate::usage::{TurnUsage, UsageTracker};
 /// Lines exceeding this limit are rejected to prevent OOM from rogue agents.
 const MAX_LINE_SIZE: usize = 10_000_000; // 10 MB
 
+const REDACTED_ENV_VALUE: &str = "[REDACTED]";
+
 /// An MCP server configuration passed to `session/new`.
 ///
 /// Corresponds to the `McpServerStdio` variant in the ACP schema.
@@ -114,13 +116,98 @@ pub enum AcpError {
 /// detail (e.g. a `data` field) is not lost.
 fn agent_error_from_json(error: &serde_json::Value) -> AcpError {
     let code = error.get("code").and_then(|c| c.as_i64()).unwrap_or(-32000);
-    let message = match error.get("message").and_then(|m| m.as_str()) {
+    let redacted_error = redact_wire_value(error);
+    let message = match redacted_error.get("message").and_then(|m| m.as_str()) {
         Some(m) => m.to_string(),
-        None => error.to_string(),
+        None => redacted_error.to_string(),
     };
     AcpError::AgentError { code, message }
 }
 
+fn contains_serialized_json_key(text: &str, key: &str) -> bool {
+    text.match_indices(key).any(|(start, _)| {
+        let bytes = text.as_bytes();
+        if start == 0 || bytes[start - 1] != b'"' {
+            return false;
+        }
+
+        let mut cursor = start + key.len();
+        while bytes.get(cursor) == Some(&b'\\') {
+            cursor += 1;
+        }
+        if bytes.get(cursor) != Some(&b'"') {
+            return false;
+        }
+        cursor += 1;
+        while bytes
+            .get(cursor)
+            .is_some_and(|byte| byte.is_ascii_whitespace())
+        {
+            cursor += 1;
+        }
+        bytes.get(cursor) == Some(&b':')
+    })
+}
+
+fn redact_wire_text(text: &str) -> &str {
+    let looks_like_serialized_mcp_config = contains_serialized_json_key(text, "mcpServers")
+        && contains_serialized_json_key(text, "env")
+        && contains_serialized_json_key(text, "value");
+    if looks_like_serialized_mcp_config {
+        REDACTED_ENV_VALUE
+    } else {
+        text
+    }
+}
+
+/// Return a logging-safe copy of an ACP wire value.
+///
+/// MCP environment values are needed by the adapter on the real wire, but
+/// must not reach tracing or observer frames.
+fn redact_wire_value(value: &serde_json::Value) -> serde_json::Value {
+    fn redact_in_place(value: &mut serde_json::Value) {
+        match value {
+            serde_json::Value::Array(values) => {
+                for value in values {
+                    redact_in_place(value);
+                }
+            }
+            serde_json::Value::Object(fields) => {
+                for (key, value) in fields {
+                    if key == "env" {
+                        if let serde_json::Value::Array(entries) = value {
+                            for entry in entries {
+                                if let serde_json::Value::Object(env_var) = entry {
+                                    if env_var.contains_key("value") {
+                                        env_var.insert(
+                                            "value".to_string(),
+                                            serde_json::Value::String(
+                                                REDACTED_ENV_VALUE.to_string(),
+                                            ),
+                                        );
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    redact_in_place(value);
+                }
+            }
+            serde_json::Value::String(text) => {
+                let observed = redact_wire_text(text);
+                if observed != text.as_str() {
+                    *text = observed.to_string();
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let mut redacted = value.clone();
+    redact_in_place(&mut redacted);
+    redacted
+}
+
 fn build_initialize_params() -> serde_json::Value {
     serde_json::json!({
         "protocolVersion": 2,
@@ -576,6 +663,14 @@ impl AcpClient {
 
     /// Emit a semantic event to the local observer feed, if enabled.
     pub fn observe(&self, kind: impl Into<String>, payload: serde_json::Value) {
+        if self.observer.is_none() {
+            return;
+        }
+        self.emit_observer(kind, redact_wire_value(&payload));
+    }
+
+    /// Emit an event whose payload is already a logging-safe copy.
+    fn emit_observer(&self, kind: impl Into<String>, payload: serde_json::Value) {
         if let Some(observer) = &self.observer {
             observer.emit(
                 kind,
@@ -771,7 +866,6 @@ impl AcpClient {
             "params": params,
         });
 
-        tracing::debug!(target: "acp::wire", "→ {}", &serde_json::to_string(&msg).unwrap_or_default());
         if let Err(e) = self.write_ndjson(&msg).await {
             self.last_prompt_id = None;
             self.current_hard_deadline = None;
@@ -1030,6 +1124,8 @@ impl AcpClient {
     /// (e.g., it's stuck or dead), the write would otherwise block forever.
     async fn write_ndjson(&mut self, value: &serde_json::Value) -> Result<(), AcpError> {
         const WRITE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+        let observed_value = redact_wire_value(value);
+        tracing::debug!(target: "acp::wire", "→ {observed_value}");
         let line = serde_json::to_string(value)?;
         tokio::time::timeout(WRITE_TIMEOUT, async {
             self.stdin.write_all(line.as_bytes()).await?;
@@ -1040,10 +1136,43 @@ impl AcpClient {
         .await
         .map_err(|_| AcpError::WriteTimeout(WRITE_TIMEOUT))?
         .map_err(AcpError::Io)?;
-        self.observe("acp_write", value.clone());
+        self.emit_observer("acp_write", observed_value);
         Ok(())
     }
 
+    /// Parse one non-empty agent stdout line and emit only a safe copy.
+    ///
+    /// Parse failures expose the line length and parser error, never the raw
+    /// line. Successful messages retain their raw value for protocol handling.
+    fn parse_inbound_line(&self, line: &str) -> Option<serde_json::Value> {
+        match serde_json::from_str(line) {
+            Ok(msg) => {
+                let observed_value = redact_wire_value(&msg);
+                tracing::debug!(target: "acp::wire", "← {observed_value}");
+                self.emit_observer("acp_read", observed_value);
+                Some(msg)
+            }
+            Err(error) => {
+                let line_length = line.len();
+                let error = error.to_string();
+                self.observe(
+                    "acp_parse_error",
+                    serde_json::json!({
+                        "lineLength": line_length,
+                        "error": error,
+                    }),
+                );
+                tracing::warn!(
+                    target: "acp::wire",
+                    line_length,
+                    error = %error,
+                    "failed to parse agent stdout as JSON; skipping"
+                );
+                None
+            }
+        }
+    }
+
     /// Default timeout for non-prompt RPCs (initialize, session/new, etc.).
     const REQUEST_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60);
 
@@ -1071,8 +1200,6 @@ impl AcpClient {
             "params": params,
         });
 
-        tracing::debug!(target: "acp::wire", "→ {}", &serde_json::to_string(&msg).unwrap_or_default());
-
         // Wrap write + read in a single timeout so a hung agent can't block forever.
         // We cannot use an async block that borrows `self` mutably across two awaits
         // inside timeout(), so we sequence them with early-return on timeout.
@@ -1136,7 +1263,6 @@ impl AcpClient {
             "params": params,
         });
 
-        tracing::debug!(target: "acp::wire", "→ (notification) {}", &serde_json::to_string(&msg).unwrap_or_default());
         self.write_ndjson(&msg).await?;
         Ok(())
     }
@@ -1177,27 +1303,10 @@ impl AcpClient {
                 continue;
             }
 
-            // Only log and reset idle after we have a valid non-empty line.
-            tracing::debug!(target: "acp::wire", "← {trimmed}");
-
-            let msg: serde_json::Value = match serde_json::from_str(trimmed) {
-                Ok(v) => v,
-                Err(e) => {
-                    self.observe(
-                        "acp_parse_error",
-                        serde_json::json!({
-                            "line": trimmed,
-                            "error": e.to_string(),
-                        }),
-                    );
-                    tracing::warn!(
-                        target: "acp::wire",
-                        "failed to parse line as JSON: {e} — skipping"
-                    );
-                    continue;
-                }
+            let msg = match self.parse_inbound_line(trimmed) {
+                Some(msg) => msg,
+                None => continue,
             };
-            self.observe("acp_read", msg.clone());
 
             // Check if this is a response to our expected request (has matching id
             // AND no `method` field — a `method` field means it's an agent-initiated
@@ -1422,11 +1531,6 @@ impl AcpClient {
                                 "method": method,
                                 "params": params,
                             });
-                            tracing::debug!(
-                                target: "acp::wire",
-                                "→ {}",
-                                serde_json::to_string(&msg).unwrap_or_default()
-                            );
                             match self.write_ndjson(&msg).await {
                                 Ok(()) => {
                                     pending_steer = Some((id, transport, req.ack_tx));
@@ -1501,26 +1605,10 @@ impl AcpClient {
                         continue;
                     }
 
-                    tracing::debug!(target: "acp::wire", "← {trimmed}");
-
-                    let msg: serde_json::Value = match serde_json::from_str(trimmed) {
-                        Ok(v) => v,
-                        Err(e) => {
-                            self.observe(
-                                "acp_parse_error",
-                                serde_json::json!({
-                                    "line": trimmed,
-                                    "error": e.to_string(),
-                                }),
-                            );
-                            tracing::warn!(
-                                target: "acp::wire",
-                                "failed to parse line as JSON: {e} — skipping"
-                            );
-                            continue;
-                        }
+                    let msg = match self.parse_inbound_line(trimmed) {
+                        Some(msg) => msg,
+                        None => continue,
                     };
-                    self.observe("acp_read", msg.clone());
 
                     let activity_now = Instant::now();
                     idle_deadline = activity_now + idle_timeout;
@@ -1546,7 +1634,7 @@ impl AcpClient {
                                             .get("code")
                                             .and_then(|c| c.as_i64())
                                             .unwrap_or(-1);
-                                        let message = error.to_string();
+                                        let message = redact_wire_value(error).to_string();
                                         crate::pool::SteerAck::Err(
                                             crate::pool::SteerError::AgentError { code, message },
                                         )
@@ -1714,6 +1802,7 @@ impl AcpClient {
         match update_type {
             "agent_message_chunk" => {
                 if let Some(text) = update["content"]["text"].as_str() {
+                    let text = redact_wire_text(text);
                     tracing::info!(target: "acp::stream", "{text}");
                 }
                 false
@@ -1727,6 +1816,8 @@ impl AcpClient {
                     .get("kind")
                     .and_then(|v| v.as_str())
                     .unwrap_or("unknown");
+                let title = redact_wire_text(title);
+                let kind = redact_wire_text(kind);
                 tracing::info!(target: "acp::tool", "tool_call: {title} ({kind})");
                 true
             }
@@ -1736,6 +1827,8 @@ impl AcpClient {
                     .and_then(|v| v.as_str())
                     .unwrap_or("?");
                 let status = update.get("status").and_then(|v| v.as_str()).unwrap_or("?");
+                let tool_id = redact_wire_text(tool_id);
+                let status = redact_wire_text(status);
                 tracing::info!(target: "acp::tool", "tool_call_update: {tool_id} → {status}");
                 false
             }
@@ -1745,6 +1838,7 @@ impl AcpClient {
             }
             "agent_thought_chunk" => {
                 if let Some(text) = update["content"]["text"].as_str() {
+                    let text = redact_wire_text(text);
                     tracing::debug!(target: "acp::thought", "{text}");
                 }
                 false
@@ -1754,7 +1848,12 @@ impl AcpClient {
                 // Logged for observability; UI surfacing is a follow-up.
                 let names: Vec<&str> = update["availableCommands"]
                     .as_array()
-                    .map(|cmds| cmds.iter().filter_map(|c| c["name"].as_str()).collect())
+                    .map(|cmds| {
+                        cmds.iter()
+                            .filter_map(|c| c["name"].as_str())
+                            .map(redact_wire_text)
+                            .collect()
+                    })
                     .unwrap_or_default();
                 tracing::info!(
                     target: "acp::update",
@@ -1781,9 +1880,10 @@ impl AcpClient {
                 if let Some(goose_meta) = meta {
                     match goose_meta.get("activeRunId") {
                         Some(serde_json::Value::String(run_id)) => {
+                            let observed_run_id = redact_wire_text(run_id);
                             tracing::debug!(
                                 target: "acp::update",
-                                "session_info_update: activeRunId={run_id}"
+                                "session_info_update: activeRunId={observed_run_id}"
                             );
                             self.active_run_id = Some(run_id.clone());
                         }
@@ -1802,6 +1902,7 @@ impl AcpClient {
             }
             "keepalive" => false,
             other => {
+                let other = redact_wire_text(other);
                 tracing::debug!(target: "acp::update", "session/update: {other}");
                 false
             }
@@ -1829,9 +1930,10 @@ impl AcpClient {
         match serde_json::from_value::<GooseSessionUpdateNotification>(params.clone()) {
             Ok(notif) => {
                 if let GooseSessionUpdateVariant::UsageUpdate(payload) = &notif.update {
+                    let observed_session_id = redact_wire_text(&notif.session_id);
                     tracing::debug!(
                         target: "acp::usage",
-                        session_id = %notif.session_id,
+                        session_id = %observed_session_id,
                         input = payload.accumulated_input_tokens,
                         output = payload.accumulated_output_tokens,
                         // A subset of `input`, logged so downstream accounting can
@@ -1845,9 +1947,11 @@ impl AcpClient {
                 }
             }
             Err(e) => {
+                let error = e.to_string();
+                let observed_error = redact_wire_text(&error);
                 tracing::debug!(
                     target: "acp::usage",
-                    "_goose/unstable/session/update: deserialization error: {e}"
+                    "_goose/unstable/session/update: deserialization error: {observed_error}"
                 );
             }
         }
@@ -2426,6 +2530,101 @@ mod tests {
         );
     }
 
+    #[test]
+    fn wire_redaction_covers_nested_env_values_without_changing_source() {
+        let source = serde_json::json!({
+            "method": "session/new",
+            "params": {
+                "mcpServers": [{
+                    "name": "analytics",
+                    "env": [
+                        {"name": "ANALYTICS_TOKEN", "value": "secret-one"},
+                        {"name": "EMPTY_VALUE", "value": ""}
+                    ]
+                }],
+                "nested": {
+                    "env": [{"name": "OTHER_TOKEN", "value": "secret-two"}]
+                },
+                "ordinary": {"value": "keep-me"}
+            }
+        });
+
+        let redacted = redact_wire_value(&source);
+
+        assert_eq!(
+            source["params"]["mcpServers"][0]["env"][0]["value"], "secret-one",
+            "the source value sent on the wire must stay unchanged"
+        );
+        assert_eq!(
+            redacted["params"]["mcpServers"][0]["env"][0]["value"],
+            REDACTED_ENV_VALUE
+        );
+        assert_eq!(
+            redacted["params"]["mcpServers"][0]["env"][1]["value"],
+            REDACTED_ENV_VALUE
+        );
+        assert_eq!(
+            redacted["params"]["nested"]["env"][0]["value"],
+            REDACTED_ENV_VALUE
+        );
+        assert_eq!(
+            redacted["params"]["ordinary"]["value"], "keep-me",
+            "value fields outside env arrays must remain visible"
+        );
+    }
+
+    #[test]
+    fn wire_redaction_suppresses_serialized_mcp_configs_without_broad_string_matching() {
+        let secret = "quote\" slash\\ newline\n snowman \u{2603}";
+        let request = serde_json::json!({
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "session/new",
+            "params": {
+                "mcpServers": [{
+                    "name": "analytics",
+                    "command": "analytics-mcp",
+                    "args": [],
+                    "env": [{"name": "ANALYTICS_TOKEN", "value": secret}]
+                }]
+            }
+        })
+        .to_string();
+        let mut serialized_levels = vec![request];
+        for _ in 0..3 {
+            let next = serde_json::to_string(
+                serialized_levels
+                    .last()
+                    .expect("at least one serialized request"),
+            )
+            .expect("serialize request again");
+            serialized_levels.push(next);
+        }
+        let source = serde_json::json!({
+            "echoes": serialized_levels
+                .iter()
+                .map(|request| format!("adapter rejected {request}; check configuration"))
+                .collect::<Vec<_>>(),
+            "ordinary": r#"invalid {"environment":"prod","value":"x"}"#,
+            "nearMiss": r#"invalid {"mcpServers":[],"envValue":"prod","value":"x"}"#,
+            "unrelated": "ordinary adapter error"
+        });
+        let original_source = source.clone();
+
+        let redacted = redact_wire_value(&source);
+
+        for echo in redacted["echoes"].as_array().expect("redacted echoes") {
+            assert_eq!(echo, REDACTED_ENV_VALUE);
+        }
+        assert_eq!(redacted["ordinary"], source["ordinary"]);
+        assert_eq!(redacted["nearMiss"], source["nearMiss"]);
+        assert_eq!(redacted["unrelated"], source["unrelated"]);
+        assert_eq!(
+            source, original_source,
+            "the protocol value must stay unchanged"
+        );
+    }
+
     #[test]
     fn session_prompt_request_format() {
         let prompt_text = "[Buzz @mention]\nChannel: test\nFrom: npub1...\nMessage: hello";
@@ -2852,6 +3051,74 @@ mod tests {
             .expect("failed to spawn test script")
     }
 
+    fn assert_safe_parse_error_event(observer: &ObserverHandle, raw_line: &str) {
+        let event = observer
+            .snapshot()
+            .into_iter()
+            .find(|event| event.kind == "acp_parse_error")
+            .expect("parse error observer event");
+        assert_eq!(
+            event.payload["lineLength"].as_u64(),
+            Some(raw_line.len() as u64)
+        );
+        assert!(event.payload["error"].is_string());
+        assert!(
+            event.payload.get("line").is_none(),
+            "the raw line field must not exist"
+        );
+        assert!(
+            !event.payload.to_string().contains(raw_line),
+            "the raw malformed line must not reach the observer"
+        );
+    }
+
+    #[tokio::test]
+    async fn regular_read_loop_reports_malformed_json_without_raw_line() {
+        let raw_line = "regular-loop-sensitive-malformed-json";
+        let script = format!(
+            "read -t 2 _REQ\nprintf '%s\\n' '{raw_line}'\nprintf '%s\\n' \
+             '{{\"jsonrpc\":\"2.0\",\"id\":0,\"result\":{{\"ok\":true}}}}'\nsleep 1"
+        );
+        let mut client = spawn_script(&script).await;
+        let observer = ObserverHandle::in_process();
+        client.set_observer(Some(observer.clone()), 0);
+
+        let result = client
+            .send_request("test/request", serde_json::json!({}))
+            .await
+            .expect("valid response after malformed line");
+        assert_eq!(result["ok"], true);
+        assert_safe_parse_error_event(&observer, raw_line);
+        client.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn idle_read_loop_reports_malformed_json_without_raw_line() {
+        let raw_line = "idle-loop-sensitive-malformed-json";
+        let script = format!(
+            "printf '%s\\n' '{raw_line}'\nprintf '%s\\n' \
+             '{{\"jsonrpc\":\"2.0\",\"id\":999,\"result\":{{\"ok\":true}}}}'\nsleep 1"
+        );
+        let mut client = spawn_script(&script).await;
+        let observer = ObserverHandle::in_process();
+        client.set_observer(Some(observer.clone()), 0);
+        let max_duration = std::time::Duration::from_secs(5);
+
+        let result = client
+            .read_until_response_with_idle_timeout(
+                "test",
+                999,
+                std::time::Duration::from_secs(1),
+                tokio::time::Instant::now() + max_duration,
+                max_duration,
+            )
+            .await
+            .expect("valid idle-loop response after malformed line");
+        assert_eq!(result["ok"], true);
+        assert_safe_parse_error_event(&observer, raw_line);
+        client.shutdown().await;
+    }
+
     /// Spawn a probe script whose file name carries a runtime identity (e.g.
     /// `hermes-acp`) and return the value of `var` as the child observed it.
     /// `<unset>` means the child did not receive the var.
@@ -3284,6 +3551,336 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn session_new_sends_real_mcp_env_but_observer_only_sees_redacted_values() {
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":2,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_secret_test","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        let observer = ObserverHandle::in_process();
+        client.set_observer(Some(observer.clone()), 0);
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let secret = "mcp-secret-must-not-reach-observer";
+        let response = client
+            .session_new_full(
+                "/tmp",
+                vec![McpServer {
+                    name: "analytics".into(),
+                    command: "analytics-mcp".into(),
+                    args: vec!["--stdio".into()],
+                    env: vec![EnvVar {
+                        name: "ANALYTICS_TOKEN".into(),
+                        value: secret.into(),
+                    }],
+                }],
+                None,
+                None,
+            )
+            .await
+            .expect("session/new should succeed");
+
+        assert_eq!(
+            response.raw["_receivedRequest"]["params"]["mcpServers"][0]["env"][0]["value"], secret,
+            "the adapter must receive the real MCP environment value"
+        );
+
+        let events = observer.snapshot();
+        let session_write = events
+            .iter()
+            .find(|event| event.kind == "acp_write" && event.payload["method"] == "session/new")
+            .expect("session/new write observer event");
+        assert_eq!(
+            session_write.payload["params"]["mcpServers"][0]["env"][0]["value"],
+            REDACTED_ENV_VALUE
+        );
+
+        let echoed_read = events
+            .iter()
+            .find(|event| {
+                event.kind == "acp_read"
+                    && event.payload["result"]["sessionId"] == "ses_secret_test"
+            })
+            .expect("session/new response observer event");
+        assert_eq!(
+            echoed_read.payload["result"]["_receivedRequest"]["params"]["mcpServers"][0]["env"][0]
+                ["value"],
+            REDACTED_ENV_VALUE
+        );
+
+        let serialized_events =
+            serde_json::to_string(&events).expect("serialize observer snapshot");
+        assert!(
+            !serialized_events.contains(secret),
+            "no observer frame may contain the real MCP environment value"
+        );
+        client.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn session_new_error_cannot_echo_serialized_mcp_config() {
+        let secret = "adapter-echo-secret";
+        let embedded_request = serde_json::json!({
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "session/new",
+            "params": {
+                "mcpServers": [{
+                    "name": "analytics",
+                    "command": "analytics-mcp",
+                    "args": [],
+                    "env": [{"name": "ANALYTICS_TOKEN", "value": secret}]
+                }]
+            }
+        })
+        .to_string();
+        let error_response = serde_json::json!({
+            "jsonrpc": "2.0",
+            "id": 1,
+            "error": {
+                "code": -32055,
+                "message": format!("adapter rejected {embedded_request}")
+            }
+        })
+        .to_string();
+        let script = format!(
+            "read -t 2 _init\n\
+             printf '%s\\n' '{{\"jsonrpc\":\"2.0\",\"id\":0,\"result\":{{\"protocolVersion\":2,\"agentCapabilities\":{{}}}}}}'\n\
+             read -t 2 _session\n\
+             printf '%s\\n' '{error_response}'\n\
+             sleep 1"
+        );
+        let mut client = spawn_script(&script).await;
+        let observer = ObserverHandle::in_process();
+        client.set_observer(Some(observer.clone()), 0);
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let result = client
+            .session_new_full(
+                "/tmp",
+                vec![McpServer {
+                    name: "analytics".into(),
+                    command: "analytics-mcp".into(),
+                    args: vec![],
+                    env: vec![EnvVar {
+                        name: "ANALYTICS_TOKEN".into(),
+                        value: secret.into(),
+                    }],
+                }],
+                None,
+                None,
+            )
+            .await;
+
+        match result {
+            Err(AcpError::AgentError { code, message }) => {
+                assert_eq!(code, -32055);
+                assert_eq!(message, REDACTED_ENV_VALUE);
+                assert!(!message.contains(secret));
+            }
+            Err(other) => panic!("expected redacted AgentError, got {other:?}"),
+            Ok(_) => panic!("expected session/new to return an error"),
+        }
+
+        client.observe(
+            "adapter_diagnostic",
+            serde_json::json!({"message": embedded_request}),
+        );
+        let serialized_events =
+            serde_json::to_string(&observer.snapshot()).expect("serialize observer snapshot");
+        assert!(!serialized_events.contains(secret));
+        assert!(serialized_events.contains(REDACTED_ENV_VALUE));
+        client.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn semantic_traces_cannot_echo_serialized_mcp_config() {
+        use std::io::Write;
+        use std::sync::{Arc, Mutex};
+
+        #[derive(Clone, Default)]
+        struct TraceCapture(Arc<Mutex<Vec<u8>>>);
+
+        struct TraceWriter(Arc<Mutex<Vec<u8>>>);
+
+        impl Write for TraceWriter {
+            fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+                self.0
+                    .lock()
+                    .expect("trace buffer lock")
+                    .extend_from_slice(bytes);
+                Ok(bytes.len())
+            }
+
+            fn flush(&mut self) -> std::io::Result<()> {
+                Ok(())
+            }
+        }
+
+        impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for TraceCapture {
+            type Writer = TraceWriter;
+
+            fn make_writer(&'a self) -> Self::Writer {
+                TraceWriter(self.0.clone())
+            }
+        }
+
+        let secret = "semantic-trace-secret";
+        let embedded_request = serde_json::json!({
+            "method": "session/new",
+            "params": {
+                "mcpServers": [{
+                    "env": [{"name": "ANALYTICS_TOKEN", "value": secret}]
+                }]
+            }
+        })
+        .to_string();
+        let update = serde_json::json!({
+            "jsonrpc": "2.0",
+            "method": "session/update",
+            "params": {
+                "update": {
+                    "sessionUpdate": "agent_message_chunk",
+                    "content": {"type": "text", "text": embedded_request}
+                }
+            }
+        });
+        let mut client = spawn_inert_client().await;
+        let trace = TraceCapture::default();
+        let subscriber = tracing_subscriber::fmt()
+            .without_time()
+            .with_ansi(false)
+            .with_max_level(tracing::Level::DEBUG)
+            .with_writer(trace.clone())
+            .finish();
+
+        tracing::subscriber::with_default(subscriber, || {
+            let _ = client.handle_session_update(&update);
+            client.handle_goose_usage_update(&serde_json::json!({
+                "params": {
+                    "sessionId": embedded_request,
+                    "update": {
+                        "sessionUpdate": "usage_update",
+                        "accumulatedInputTokens": 10,
+                        "accumulatedOutputTokens": 5,
+                        "accumulatedCachedInputTokens": null,
+                        "accumulatedCost": null
+                    }
+                }
+            }));
+            client.handle_goose_usage_update(&serde_json::json!({
+                "params": {
+                    "sessionId": "ordinary-session",
+                    "update": {
+                        "sessionUpdate": "usage_update",
+                        "accumulatedInputTokens": embedded_request,
+                        "accumulatedOutputTokens": 5,
+                        "accumulatedCachedInputTokens": null,
+                        "accumulatedCost": null
+                    }
+                }
+            }));
+        });
+
+        let output = String::from_utf8(trace.0.lock().expect("trace buffer lock").clone())
+            .expect("trace output should be UTF-8");
+        assert!(!output.contains(secret));
+        assert!(output.contains(REDACTED_ENV_VALUE));
+        client.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn structured_mcp_servers_survive_repeated_sessions_and_adapter_restart() {
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":2,"agentCapabilities":{}}}'
+            read -t 2 FIRST
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_first","_receivedRequest":'"$FIRST"'}}'
+            read -t 2 SECOND
+            echo '{"jsonrpc":"2.0","id":2,"result":{"sessionId":"ses_second","_receivedRequest":'"$SECOND"'}}'
+            sleep 1
+        "#;
+        let servers = vec![
+            McpServer {
+                name: "analytics".into(),
+                command: "/opt/MCP Servers/analytics,prod".into(),
+                args: vec!["--stdio".into(), "literal value".into()],
+                env: vec![EnvVar {
+                    name: "ANALYTICS_ENDPOINT".into(),
+                    value: "https://example.test/a=b".into(),
+                }],
+            },
+            McpServer {
+                name: "search".into(),
+                command: "/opt/search-mcp".into(),
+                args: vec![],
+                env: vec![],
+            },
+        ];
+
+        for _restart in 0..2 {
+            let mut client = spawn_script(script).await;
+            let observer = ObserverHandle::in_process();
+            client.set_observer(Some(observer.clone()), 0);
+            client
+                .initialize()
+                .await
+                .expect("initialize should succeed");
+
+            for expected_session_id in ["ses_first", "ses_second"] {
+                let response = client
+                    .session_new_full("/tmp", servers.clone(), None, None)
+                    .await
+                    .expect("session/new should succeed");
+                assert_eq!(response.session_id, expected_session_id);
+                let received = &response.raw["_receivedRequest"]["params"]["mcpServers"];
+                assert_eq!(received[0]["name"], "analytics");
+                assert_eq!(received[0]["command"], "/opt/MCP Servers/analytics,prod");
+                assert_eq!(
+                    received[0]["args"],
+                    serde_json::json!(["--stdio", "literal value"])
+                );
+                assert_eq!(received[0]["env"][0]["name"], "ANALYTICS_ENDPOINT");
+                assert_eq!(received[0]["env"][0]["value"], "https://example.test/a=b");
+                assert_eq!(received[1]["name"], "search");
+                assert_eq!(received[1]["command"], "/opt/search-mcp");
+            }
+
+            let writes = observer
+                .snapshot()
+                .into_iter()
+                .filter(|event| {
+                    event.kind == "acp_write" && event.payload["method"] == "session/new"
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(writes.len(), 2);
+            for write in writes {
+                let sent = &write.payload["params"]["mcpServers"];
+                assert_eq!(sent[0]["name"], "analytics");
+                assert_eq!(sent[0]["command"], "/opt/MCP Servers/analytics,prod");
+                assert_eq!(
+                    sent[0]["args"],
+                    serde_json::json!(["--stdio", "literal value"])
+                );
+                assert_eq!(sent[0]["env"][0]["name"], "ANALYTICS_ENDPOINT");
+                assert_eq!(sent[0]["env"][0]["value"], REDACTED_ENV_VALUE);
+                assert_eq!(sent[1]["name"], "search");
+                assert_eq!(sent[1]["command"], "/opt/search-mcp");
+            }
+            client.shutdown().await;
+        }
+    }
+
     #[tokio::test]
     async fn goose_system_prompt_request_uses_append_contract() {
         let script = r#"
@@ -4249,6 +4846,26 @@ mod tests {
         }
     }
 
+    #[test]
+    fn agent_error_from_json_redacts_mcp_env_before_display_or_turn_error() {
+        let secret = "agent-error-secret";
+        let error = serde_json::json!({
+            "code": -32002,
+            "data": {
+                "env": [{
+                    "name": "ANALYTICS_TOKEN",
+                    "value": secret
+                }]
+            }
+        });
+
+        let rendered = super::agent_error_from_json(&error).to_string();
+
+        assert!(!rendered.contains(secret));
+        assert!(rendered.contains(REDACTED_ENV_VALUE));
+        assert_eq!(error["data"]["env"][0]["value"], secret);
+    }
+
     #[test]
     fn agent_error_from_json_uses_message_field_when_present() {
         let error = serde_json::json!({"code": -32001, "message": "auth denied"});
diff --git a/crates/buzz-acp/src/config.rs b/crates/buzz-acp/src/config.rs
index dab61be30a..e93342bf19 100644
--- a/crates/buzz-acp/src/config.rs
+++ b/crates/buzz-acp/src/config.rs
@@ -3,7 +3,8 @@
 //! CLI-first: every option is a CLI flag with env var fallback.
 //! Config file (TOML) for complex subscription rules.
 
-use std::collections::{HashMap, HashSet};
+use std::collections::{BTreeMap, HashMap, HashSet};
+use std::io::Read;
 use std::path::PathBuf;
 
 use clap::Parser;
@@ -47,6 +48,250 @@ pub enum ConfigError {
     ConfigFile(String),
 }
 
+const MCP_CONFIG_VERSION: u32 = 1;
+const MCP_CONFIG_MAX_BYTES: u64 = 64 * 1024;
+const MCP_SERVER_MAX_COUNT: usize = 16;
+const MCP_SERVER_MAX_ARGS: usize = 128;
+const MCP_SERVER_MAX_ENV: usize = 128;
+const MCP_SERVER_NAME_MAX_BYTES: usize = 128;
+const PROTECTED_MCP_ENV_NAMES: [&str; 6] = [
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_API_TOKEN",
+    "BUZZ_ACP_PRIVATE_KEY",
+    "BUZZ_ACP_API_TOKEN",
+];
+
+/// One local stdio MCP server loaded from the structured MCP configuration.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ConfiguredMcpServer {
+    /// Stable ACP identifier for this server.
+    pub name: String,
+    /// Executable to invoke, passed directly without shell parsing.
+    pub command: String,
+    /// Arguments passed to the executable in their configured order.
+    pub args: Vec<String>,
+    /// Server-specific environment in deterministic key order.
+    #[serde(deserialize_with = "deserialize_mcp_env")]
+    pub env: BTreeMap<String, String>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct McpConfigDocument {
+    version: u32,
+    servers: Vec<ConfiguredMcpServer>,
+}
+
+fn deserialize_mcp_env<'de, D>(deserializer: D) -> Result<BTreeMap<String, String>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    struct EnvVisitor;
+
+    impl<'de> serde::de::Visitor<'de> for EnvVisitor {
+        type Value = BTreeMap<String, String>;
+
+        fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            formatter.write_str("an object containing unique environment variable names")
+        }
+
+        fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+        where
+            A: serde::de::MapAccess<'de>,
+        {
+            let mut env = BTreeMap::new();
+            let mut normalized_names = HashSet::new();
+            while let Some((key, value)) = map.next_entry::<String, String>()? {
+                if !normalized_names.insert(key.to_ascii_uppercase()) {
+                    return Err(serde::de::Error::custom(format!(
+                        "duplicate environment key '{key}'"
+                    )));
+                }
+                env.insert(key, value);
+            }
+            Ok(env)
+        }
+    }
+
+    deserializer.deserialize_map(EnvVisitor)
+}
+
+/// Derive the ACP name used by the legacy single-command MCP configuration.
+///
+/// This preserves the existing `build_mcp_servers` behavior so collision
+/// validation and runtime construction use the same name.
+pub fn legacy_mcp_server_name(command: &str) -> String {
+    std::path::Path::new(command)
+        .file_stem()
+        .and_then(|stem| stem.to_str())
+        .unwrap_or("mcp")
+        .to_string()
+}
+
+fn read_mcp_config(path: &std::path::Path) -> Result<Vec<u8>, ConfigError> {
+    let mut options = std::fs::OpenOptions::new();
+    options.read(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.custom_flags(nix::libc::O_NONBLOCK);
+    }
+    let file = options.open(path).map_err(|error| {
+        ConfigError::ConfigFile(format!(
+            "failed to open MCP config {}: {error}",
+            path.display()
+        ))
+    })?;
+    let metadata = file.metadata().map_err(|error| {
+        ConfigError::ConfigFile(format!(
+            "failed to inspect MCP config {}: {error}",
+            path.display()
+        ))
+    })?;
+    if !metadata.is_file() {
+        return Err(ConfigError::ConfigFile(format!(
+            "MCP config {} must be a regular file",
+            path.display()
+        )));
+    }
+    let mut content = Vec::new();
+    file.take(MCP_CONFIG_MAX_BYTES + 1)
+        .read_to_end(&mut content)
+        .map_err(|error| {
+            ConfigError::ConfigFile(format!(
+                "failed to read MCP config {}: {error}",
+                path.display()
+            ))
+        })?;
+    if content.len() as u64 > MCP_CONFIG_MAX_BYTES {
+        return Err(ConfigError::ConfigFile(format!(
+            "MCP config {} exceeds the {} byte limit",
+            path.display(),
+            MCP_CONFIG_MAX_BYTES
+        )));
+    }
+    Ok(content)
+}
+
+fn valid_mcp_server_name(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= MCP_SERVER_NAME_MAX_BYTES
+        && !name.contains("__")
+        && name
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
+}
+
+fn valid_mcp_env_name(name: &str) -> bool {
+    let mut bytes = name.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_alphabetic() || byte == b'_')
+        && bytes.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
+}
+
+fn load_mcp_config(
+    path: &std::path::Path,
+    legacy_mcp_command: &str,
+) -> Result<Vec<ConfiguredMcpServer>, ConfigError> {
+    let content = read_mcp_config(path)?;
+    let document: McpConfigDocument = serde_json::from_slice(&content).map_err(|error| {
+        ConfigError::ConfigFile(format!("invalid MCP config {}: {error}", path.display()))
+    })?;
+
+    if document.version != MCP_CONFIG_VERSION {
+        return Err(ConfigError::ConfigFile(format!(
+            "unsupported MCP config version {} (expected {})",
+            document.version, MCP_CONFIG_VERSION
+        )));
+    }
+
+    let legacy_count = usize::from(!legacy_mcp_command.is_empty());
+    if document.servers.len() + legacy_count > MCP_SERVER_MAX_COUNT {
+        return Err(ConfigError::ConfigFile(format!(
+            "too many MCP servers ({} structured + {legacy_count} legacy, max {MCP_SERVER_MAX_COUNT})",
+            document.servers.len()
+        )));
+    }
+
+    let legacy_name =
+        (!legacy_mcp_command.is_empty()).then(|| legacy_mcp_server_name(legacy_mcp_command));
+    let mut names = HashSet::with_capacity(document.servers.len());
+    for (index, server) in document.servers.iter().enumerate() {
+        if !valid_mcp_server_name(&server.name) {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server {} has invalid name '{}': use 1 to {MCP_SERVER_NAME_MAX_BYTES} ASCII letters, digits, underscores, or hyphens, without '__'",
+                index + 1,
+                server.name
+            )));
+        }
+        if !names.insert(server.name.as_str()) {
+            return Err(ConfigError::ConfigFile(format!(
+                "duplicate MCP server name '{}'",
+                server.name
+            )));
+        }
+        if legacy_name.as_deref() == Some(server.name.as_str()) {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server name '{}' collides with the legacy --mcp-command server",
+                server.name
+            )));
+        }
+        if server.command.is_empty() || server.command.contains('\0') {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server '{}' command must be nonempty and contain no NUL bytes",
+                server.name
+            )));
+        }
+        if server.args.len() > MCP_SERVER_MAX_ARGS {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server '{}' has too many arguments ({}, max {MCP_SERVER_MAX_ARGS})",
+                server.name,
+                server.args.len()
+            )));
+        }
+        if server.args.iter().any(|argument| argument.contains('\0')) {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server '{}' arguments must contain no NUL bytes",
+                server.name
+            )));
+        }
+        if server.env.len() > MCP_SERVER_MAX_ENV {
+            return Err(ConfigError::ConfigFile(format!(
+                "MCP server '{}' has too many environment entries ({}, max {MCP_SERVER_MAX_ENV})",
+                server.name,
+                server.env.len()
+            )));
+        }
+        for (key, value) in &server.env {
+            if !valid_mcp_env_name(key) {
+                return Err(ConfigError::ConfigFile(format!(
+                    "MCP server '{}' has invalid environment key '{key}'",
+                    server.name
+                )));
+            }
+            if PROTECTED_MCP_ENV_NAMES
+                .iter()
+                .any(|protected| key.eq_ignore_ascii_case(protected))
+            {
+                return Err(ConfigError::ConfigFile(format!(
+                    "MCP server '{}' may not configure protected environment key '{key}'",
+                    server.name
+                )));
+            }
+            if value.contains('\0') {
+                return Err(ConfigError::ConfigFile(format!(
+                    "MCP server '{}' environment value for '{key}' contains a NUL byte",
+                    server.name
+                )));
+            }
+        }
+    }
+
+    Ok(document.servers)
+}
+
 #[derive(Debug, Clone, PartialEq, clap::ValueEnum)]
 pub enum SubscribeMode {
     Mentions,
@@ -261,6 +506,10 @@ pub struct CliArgs {
     #[arg(long, env = "BUZZ_ACP_MCP_COMMAND", default_value = "")]
     pub mcp_command: String,
 
+    /// Path to a versioned JSON document defining additional local MCP servers.
+    #[arg(long, env = "BUZZ_ACP_MCP_CONFIG")]
+    pub mcp_config: Option<PathBuf>,
+
     /// Idle timeout: max seconds of silence before killing a turn.
     /// Resets on any agent stdout activity.
     #[arg(long, env = "BUZZ_ACP_IDLE_TIMEOUT")]
@@ -495,6 +744,8 @@ pub struct Config {
     pub agent_command: String,
     pub agent_args: Vec<String>,
     pub mcp_command: String,
+    /// Additional local MCP servers loaded once from `--mcp-config`.
+    pub configured_mcp_servers: Vec<ConfiguredMcpServer>,
     pub idle_timeout_secs: u64,
     pub max_turn_duration_secs: u64,
     pub agents: u32,
@@ -820,10 +1071,23 @@ pub fn propagate_legacy_env_vars() {
     }
 }
 
+/// Prepare environment fallbacks before Clap and Tokio read process state.
+///
+/// Deployment templates commonly render optional values as empty strings.
+/// Clap treats an empty value for `Option<PathBuf>` as an invalid supplied
+/// value, so normalize this one optional path to the same state as an unset
+/// variable before argument parsing starts.
+pub fn prepare_process_env() {
+    propagate_legacy_env_vars();
+    if std::env::var_os("BUZZ_ACP_MCP_CONFIG").is_some_and(|value| value.is_empty()) {
+        std::env::remove_var("BUZZ_ACP_MCP_CONFIG");
+    }
+}
+
 impl Config {
     pub fn from_cli() -> Result<Self, ConfigError> {
         // Legacy env-var propagation is intentionally NOT done here.
-        // Call `propagate_legacy_env_vars()` before the tokio runtime starts
+        // Call `prepare_process_env()` before the tokio runtime starts
         // (in the sync `fn main()` wrapper) — see Rust 2024 edition safety.
         let args = CliArgs::parse();
         Self::from_args(args)
@@ -906,6 +1170,10 @@ impl Config {
         }
 
         let agent_args = normalize_agent_args(&agent_command, args.agent_args);
+        let configured_mcp_servers = match args.mcp_config.as_deref() {
+            Some(path) => load_mcp_config(path, &args.mcp_command)?,
+            None => Vec::new(),
+        };
 
         if let Some(ref channels) = args.channels {
             for ch in channels {
@@ -1059,6 +1327,7 @@ impl Config {
             agent_command,
             agent_args,
             mcp_command: args.mcp_command,
+            configured_mcp_servers,
             idle_timeout_secs,
             max_turn_duration_secs,
             agents: args.agents,
@@ -1123,12 +1392,13 @@ impl Config {
             format!(" allowed_respond_to=[{}]", modes.join(","))
         };
         format!(
-            "relay={} pubkey={} agent_cmd={} {} mcp_cmd={} idle_timeout={}s max_turn={}s agents={} heartbeat={}s subscribe={:?} dedup={:?} meh={:?} ignore_self={} context_limit={} max_turns_per_session={} presence={} typing={} memory={} model={} permission_mode={} {}{}",
+            "relay={} pubkey={} agent_cmd={} {} legacy_mcp_server={} structured_mcp_servers={} idle_timeout={}s max_turn={}s agents={} heartbeat={}s subscribe={:?} dedup={:?} meh={:?} ignore_self={} context_limit={} max_turns_per_session={} presence={} typing={} memory={} model={} permission_mode={} {}{}",
             self.relay_url,
             self.keys.public_key().to_hex(),
             self.agent_command,
             self.agent_args.join(" "),
-            self.mcp_command,
+            !self.mcp_command.is_empty(),
+            self.configured_mcp_servers.len(),
             self.idle_timeout_secs,
             self.max_turn_duration_secs,
             self.agents,
@@ -1437,6 +1707,7 @@ mod tests {
             agent_command: "goose".into(),
             agent_args: vec!["acp".into()],
             mcp_command: "".into(),
+            configured_mcp_servers: Vec::new(),
             idle_timeout_secs: DEFAULT_IDLE_TIMEOUT_SECS,
             max_turn_duration_secs: DEFAULT_MAX_TURN_DURATION_SECS,
             agents: 1,
@@ -2899,6 +3170,414 @@ channels = "ALL"
         assert_eq!(compose_session_title(&agent, Some("buzz-dev")), agent);
     }
 
+    struct TempMcpConfig {
+        path: PathBuf,
+    }
+
+    impl TempMcpConfig {
+        fn write(content: &[u8]) -> Self {
+            let path =
+                std::env::temp_dir().join(format!("buzz-acp-mcp-config-{}.json", Uuid::new_v4()));
+            std::fs::write(&path, content).expect("write temporary MCP config");
+            Self { path }
+        }
+    }
+
+    impl Drop for TempMcpConfig {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_file(&self.path);
+        }
+    }
+
+    fn config_from_mcp_file(
+        file: &TempMcpConfig,
+        legacy_command: Option<&str>,
+    ) -> Result<Config, ConfigError> {
+        let mut argv = vec![
+            "buzz-acp".to_string(),
+            "--private-key".to_string(),
+            TEST_PRIVATE_KEY.to_string(),
+            "--mcp-config".to_string(),
+            file.path.display().to_string(),
+        ];
+        if let Some(command) = legacy_command {
+            argv.push("--mcp-command".to_string());
+            argv.push(command.to_string());
+        }
+        let args = CliArgs::try_parse_from(argv).expect("clap should parse MCP config arguments");
+        Config::from_args(args)
+    }
+
+    fn server_json(name: &str) -> serde_json::Value {
+        serde_json::json!({
+            "name": name,
+            "command": "mcp",
+            "args": [],
+            "env": {}
+        })
+    }
+
+    fn document_json(servers: Vec<serde_json::Value>) -> Vec<u8> {
+        serde_json::to_vec(&serde_json::json!({
+            "version": MCP_CONFIG_VERSION,
+            "servers": servers
+        }))
+        .expect("serialize MCP test document")
+    }
+
+    #[test]
+    fn structured_mcp_config_preserves_order_and_exact_values() {
+        let posix_command = "/Applications/Tool Suite/工具 mcp";
+        let windows_command = r"C:\Program Files\Agent Tools\server.exe";
+        let literal_metacharacters = r#"$HOME;$(echo nope)|&<>*?`literal`"#;
+        let file = TempMcpConfig::write(&document_json(vec![
+            serde_json::json!({
+                "name": "analytics-primary",
+                "command": posix_command,
+                "args": [
+                    "",
+                    "with spaces",
+                    "comma,value",
+                    "quote\"value",
+                    r"C:\data\reports",
+                    literal_metacharacters,
+                    "雪"
+                ],
+                "env": {
+                    "Z_LAST": "backslash\\quote\"雪",
+                    "A_FIRST": ""
+                }
+            }),
+            serde_json::json!({
+                "name": "windows_server",
+                "command": windows_command,
+                "args": ["--stdio"],
+                "env": {}
+            }),
+        ]));
+
+        let config = config_from_mcp_file(&file, None).expect("structured config should load");
+        assert_eq!(config.configured_mcp_servers.len(), 2);
+        assert_eq!(config.configured_mcp_servers[0].name, "analytics-primary");
+        assert_eq!(config.configured_mcp_servers[0].command, posix_command);
+        assert_eq!(
+            config.configured_mcp_servers[0].args,
+            vec![
+                "",
+                "with spaces",
+                "comma,value",
+                "quote\"value",
+                r"C:\data\reports",
+                literal_metacharacters,
+                "雪"
+            ]
+        );
+        assert_eq!(
+            config.configured_mcp_servers[0]
+                .env
+                .keys()
+                .map(String::as_str)
+                .collect::<Vec<_>>(),
+            vec!["A_FIRST", "Z_LAST"]
+        );
+        assert_eq!(
+            config.configured_mcp_servers[0].env["Z_LAST"],
+            "backslash\\quote\"雪"
+        );
+        assert_eq!(config.configured_mcp_servers[1].command, windows_command);
+    }
+
+    #[test]
+    fn summary_reports_only_structured_mcp_count() {
+        let secret_value = "value-that-must-not-be-logged";
+        let command = "/private/path/tool";
+        let file = TempMcpConfig::write(&document_json(vec![serde_json::json!({
+            "name": "safe",
+            "command": command,
+            "args": [],
+            "env": {"DOMAIN_TOKEN": secret_value}
+        })]));
+        let config =
+            config_from_mcp_file(&file, Some("/legacy/private/tool")).expect("config should load");
+
+        let summary = config.summary();
+        assert!(summary.contains("legacy_mcp_server=true"));
+        assert!(summary.contains("structured_mcp_servers=1"));
+        assert!(!summary.contains(secret_value));
+        assert!(!summary.contains(command));
+        assert!(!summary.contains("/legacy/private/tool"));
+        assert!(!summary.contains("DOMAIN_TOKEN"));
+    }
+
+    #[test]
+    fn legacy_mcp_name_matches_existing_file_stem_behavior() {
+        assert_eq!(
+            legacy_mcp_server_name("/opt/bin/my-mcp-server"),
+            "my-mcp-server"
+        );
+        assert_eq!(legacy_mcp_server_name("."), "mcp");
+        assert_eq!(legacy_mcp_server_name(""), "mcp");
+    }
+
+    #[test]
+    fn mcp_config_rejects_unreadable_file() {
+        let path = std::env::temp_dir().join(format!(
+            "buzz-acp-missing-mcp-config-{}.json",
+            Uuid::new_v4()
+        ));
+        let argv = vec![
+            "buzz-acp".to_string(),
+            "--private-key".to_string(),
+            TEST_PRIVATE_KEY.to_string(),
+            "--mcp-config".to_string(),
+            path.display().to_string(),
+        ];
+        let args = CliArgs::try_parse_from(argv).expect("clap should parse arguments");
+        let error = Config::from_args(args).expect_err("missing MCP config must fail");
+        assert!(error.to_string().contains("failed to open MCP config"));
+    }
+
+    #[test]
+    fn mcp_config_rejects_non_regular_files() {
+        let path = std::env::temp_dir().join(format!("buzz-acp-mcp-config-dir-{}", Uuid::new_v4()));
+        std::fs::create_dir(&path).expect("create temporary MCP config directory");
+
+        let error = read_mcp_config(&path).expect_err("directories must not be read as MCP config");
+        let _ = std::fs::remove_dir(&path);
+        assert!(error.to_string().contains("must be a regular file"));
+    }
+
+    #[test]
+    fn mcp_config_enforces_file_size_boundary() {
+        let base = document_json(Vec::new());
+        let mut at_limit = base.clone();
+        at_limit.resize(MCP_CONFIG_MAX_BYTES as usize, b' ');
+        let file = TempMcpConfig::write(&at_limit);
+        config_from_mcp_file(&file, None).expect("64 KiB MCP config should be accepted");
+
+        let mut over_limit = base;
+        over_limit.resize(MCP_CONFIG_MAX_BYTES as usize + 1, b' ');
+        let file = TempMcpConfig::write(&over_limit);
+        let error =
+            config_from_mcp_file(&file, None).expect_err("MCP config over 64 KiB must fail");
+        assert!(error.to_string().contains("65536 byte limit"));
+    }
+
+    #[test]
+    fn mcp_config_rejects_malformed_wrong_version_and_unknown_fields() {
+        let cases: Vec<(&str, Vec<u8>)> = vec![
+            ("malformed", br#"{"version":1,"servers":["#.to_vec()),
+            (
+                "wrong version",
+                br#"{"version":2,"servers":[]}"#.to_vec(),
+            ),
+            (
+                "unknown document field",
+                br#"{"version":1,"servers":[],"extra":true}"#.to_vec(),
+            ),
+            (
+                "unknown server field",
+                br#"{"version":1,"servers":[{"name":"one","command":"mcp","args":[],"env":{},"extra":true}]}"#.to_vec(),
+            ),
+            (
+                "missing required field",
+                br#"{"version":1,"servers":[{"name":"one","command":"mcp","env":{}}]}"#.to_vec(),
+            ),
+        ];
+
+        for (label, content) in cases {
+            let file = TempMcpConfig::write(&content);
+            assert!(
+                config_from_mcp_file(&file, None).is_err(),
+                "{label} should be rejected"
+            );
+        }
+    }
+
+    #[test]
+    fn mcp_config_validates_server_names_and_collisions() {
+        let invalid_names = vec![
+            String::new(),
+            "contains space".to_string(),
+            "contains.dot".to_string(),
+            "double__underscore".to_string(),
+            "unicodé".to_string(),
+            "a".repeat(MCP_SERVER_NAME_MAX_BYTES + 1),
+        ];
+        for invalid_name in invalid_names {
+            let file = TempMcpConfig::write(&document_json(vec![server_json(&invalid_name)]));
+            assert!(
+                config_from_mcp_file(&file, None).is_err(),
+                "invalid name {invalid_name:?} should fail"
+            );
+        }
+
+        let file = TempMcpConfig::write(&document_json(vec![
+            server_json("same"),
+            server_json("same"),
+        ]));
+        let error =
+            config_from_mcp_file(&file, None).expect_err("duplicate server name should fail");
+        assert!(error.to_string().contains("duplicate MCP server name"));
+
+        let file = TempMcpConfig::write(&document_json(vec![server_json("my-mcp-server")]));
+        let error = config_from_mcp_file(&file, Some("/opt/bin/my-mcp-server"))
+            .expect_err("legacy name collision should fail");
+        assert!(error.to_string().contains("collides"));
+    }
+
+    #[test]
+    fn mcp_config_limits_total_servers_including_legacy() {
+        let sixteen = (0..MCP_SERVER_MAX_COUNT)
+            .map(|index| server_json(&format!("server-{index}")))
+            .collect::<Vec<_>>();
+        let file = TempMcpConfig::write(&document_json(sixteen));
+        config_from_mcp_file(&file, None).expect("16 structured servers should be accepted");
+        assert!(
+            config_from_mcp_file(&file, Some("legacy-mcp")).is_err(),
+            "16 structured plus one legacy server should fail"
+        );
+
+        let seventeen = (0..=MCP_SERVER_MAX_COUNT)
+            .map(|index| server_json(&format!("server-{index}")))
+            .collect::<Vec<_>>();
+        let file = TempMcpConfig::write(&document_json(seventeen));
+        assert!(
+            config_from_mcp_file(&file, None).is_err(),
+            "17 structured servers should fail"
+        );
+    }
+
+    #[test]
+    fn mcp_config_enforces_argument_limit() {
+        let args = (0..MCP_SERVER_MAX_ARGS)
+            .map(|index| format!("arg-{index}"))
+            .collect::<Vec<_>>();
+        let file = TempMcpConfig::write(&document_json(vec![serde_json::json!({
+            "name": "limit",
+            "command": "mcp",
+            "args": args,
+            "env": {}
+        })]));
+        config_from_mcp_file(&file, None).expect("128 arguments should be accepted");
+
+        let args = (0..=MCP_SERVER_MAX_ARGS)
+            .map(|index| format!("arg-{index}"))
+            .collect::<Vec<_>>();
+        let file = TempMcpConfig::write(&document_json(vec![serde_json::json!({
+            "name": "over-limit",
+            "command": "mcp",
+            "args": args,
+            "env": {}
+        })]));
+        let error =
+            config_from_mcp_file(&file, None).expect_err("129 arguments should be rejected");
+        assert!(error.to_string().contains("too many arguments"));
+    }
+
+    #[test]
+    fn mcp_config_enforces_environment_limit() {
+        let env = (0..MCP_SERVER_MAX_ENV)
+            .map(|index| (format!("KEY_{index}"), format!("value-{index}")))
+            .collect::<BTreeMap<_, _>>();
+        let file = TempMcpConfig::write(&document_json(vec![serde_json::json!({
+            "name": "limit",
+            "command": "mcp",
+            "args": [],
+            "env": env
+        })]));
+        config_from_mcp_file(&file, None).expect("128 environment entries should be accepted");
+
+        let env = (0..=MCP_SERVER_MAX_ENV)
+            .map(|index| (format!("KEY_{index}"), format!("value-{index}")))
+            .collect::<BTreeMap<_, _>>();
+        let file = TempMcpConfig::write(&document_json(vec![serde_json::json!({
+            "name": "over-limit",
+            "command": "mcp",
+            "args": [],
+            "env": env
+        })]));
+        let error = config_from_mcp_file(&file, None)
+            .expect_err("129 environment entries should be rejected");
+        assert!(error.to_string().contains("too many environment entries"));
+    }
+
+    #[test]
+    fn mcp_config_rejects_invalid_duplicate_and_protected_env_names() {
+        for invalid_key in ["", "1STARTS_WITH_DIGIT", "BAD-NAME", "UNICODÉ"] {
+            let content = format!(
+                r#"{{"version":1,"servers":[{{"name":"one","command":"mcp","args":[],"env":{{"{invalid_key}":"value"}}}}]}}"#
+            );
+            let file = TempMcpConfig::write(content.as_bytes());
+            assert!(
+                config_from_mcp_file(&file, None).is_err(),
+                "invalid environment key {invalid_key:?} should fail"
+            );
+        }
+
+        for protected in PROTECTED_MCP_ENV_NAMES {
+            let lowercase = protected.to_ascii_lowercase();
+            let content = format!(
+                r#"{{"version":1,"servers":[{{"name":"one","command":"mcp","args":[],"env":{{"{lowercase}":"value"}}}}]}}"#
+            );
+            let file = TempMcpConfig::write(content.as_bytes());
+            let error = config_from_mcp_file(&file, None)
+                .expect_err("protected environment key should fail case-insensitively");
+            assert!(error.to_string().contains("protected environment key"));
+        }
+
+        for duplicate_env in [
+            r#"{"KEY":"one","KEY":"two"}"#,
+            r#"{"KEY":"one","key":"two"}"#,
+        ] {
+            let content = format!(
+                r#"{{"version":1,"servers":[{{"name":"one","command":"mcp","args":[],"env":{duplicate_env}}}]}}"#
+            );
+            let file = TempMcpConfig::write(content.as_bytes());
+            let error =
+                config_from_mcp_file(&file, None).expect_err("duplicate env key should fail");
+            assert!(error.to_string().contains("duplicate environment key"));
+        }
+    }
+
+    #[test]
+    fn mcp_config_rejects_empty_or_nul_process_values() {
+        let cases = vec![
+            serde_json::json!({
+                "name": "empty-command",
+                "command": "",
+                "args": [],
+                "env": {}
+            }),
+            serde_json::json!({
+                "name": "nul-command",
+                "command": "mc\u{0}p",
+                "args": [],
+                "env": {}
+            }),
+            serde_json::json!({
+                "name": "nul-arg",
+                "command": "mcp",
+                "args": ["ok", "bad\u{0}arg"],
+                "env": {}
+            }),
+            serde_json::json!({
+                "name": "nul-value",
+                "command": "mcp",
+                "args": [],
+                "env": {"DOMAIN_KEY": "bad\u{0}value"}
+            }),
+        ];
+
+        for server in cases {
+            let file = TempMcpConfig::write(&document_json(vec![server]));
+            assert!(
+                config_from_mcp_file(&file, None).is_err(),
+                "invalid process value should fail"
+            );
+        }
+    }
+
     /// Every arg whose env var name contains KEY/SECRET/TOKEN/PASSWORD/CRED/AUTH
     /// must set `hide_env_values = true` to prevent credential leakage in --help.
     #[test]
diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index 403512a322..10b2866586 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -1229,7 +1229,7 @@ impl Drop for RespawnGuard {
 // worker threads (Rust 2024 edition safety requirement).
 
 pub fn run() -> Result<()> {
-    config::propagate_legacy_env_vars();
+    config::prepare_process_env();
     tokio_main()
 }
 
@@ -4177,60 +4177,77 @@ async fn run_models(args: ModelsArgs) -> Result<()> {
 }
 
 fn build_mcp_servers(config: &Config) -> Vec<McpServer> {
-    if config.mcp_command.is_empty() {
-        return vec![];
-    }
-    vec![McpServer {
-        name: std::path::Path::new(&config.mcp_command)
-            .file_stem()
-            .and_then(|s| s.to_str())
-            .unwrap_or("mcp")
-            .to_string(),
-        command: config.mcp_command.clone(),
-        args: vec![],
-        env: {
-            let mut env = vec![
-                EnvVar {
-                    name: "BUZZ_RELAY_URL".into(),
-                    value: config.relay_url.clone(),
-                },
-                EnvVar {
-                    name: "BUZZ_PRIVATE_KEY".into(),
-                    // bech32 encoding of a valid secret key is infallible.
-                    // Panic here is correct: injecting a bogus secret would cause
-                    // delayed, hard-to-diagnose agent failures downstream.
-                    value: config
-                        .keys
-                        .secret_key()
-                        .to_bech32()
-                        .expect("secret key bech32 encoding should never fail"),
-                },
-            ];
-            // Forward BUZZ_AUTH_TAG (NIP-OA owner attestation credential)
-            // so the MCP server can attach it to every signed event.
-            if let Ok(auth_tag) = std::env::var("BUZZ_AUTH_TAG") {
-                if !auth_tag.is_empty() {
-                    env.push(EnvVar {
-                        name: "BUZZ_AUTH_TAG".into(),
-                        value: auth_tag,
-                    });
+    let mut servers = Vec::with_capacity(
+        usize::from(!config.mcp_command.is_empty()) + config.configured_mcp_servers.len(),
+    );
+
+    if !config.mcp_command.is_empty() {
+        servers.push(McpServer {
+            name: config::legacy_mcp_server_name(&config.mcp_command),
+            command: config.mcp_command.clone(),
+            args: vec![],
+            env: {
+                let mut env = vec![
+                    EnvVar {
+                        name: "BUZZ_RELAY_URL".into(),
+                        value: config.relay_url.clone(),
+                    },
+                    EnvVar {
+                        name: "BUZZ_PRIVATE_KEY".into(),
+                        // bech32 encoding of a valid secret key is infallible.
+                        // Panic here is correct: injecting a bogus secret would cause
+                        // delayed, hard-to-diagnose agent failures downstream.
+                        value: config
+                            .keys
+                            .secret_key()
+                            .to_bech32()
+                            .expect("secret key bech32 encoding should never fail"),
+                    },
+                ];
+                // Forward BUZZ_AUTH_TAG (NIP-OA owner attestation credential)
+                // so the MCP server can attach it to every signed event.
+                if let Ok(auth_tag) = std::env::var("BUZZ_AUTH_TAG") {
+                    if !auth_tag.is_empty() {
+                        env.push(EnvVar {
+                            name: "BUZZ_AUTH_TAG".into(),
+                            value: auth_tag,
+                        });
+                    }
                 }
-            }
-            // Forward the agent's display name so dev-mcp can use it as the git
-            // author name instead of the raw npub. Read from the process env
-            // rather than Config: this is a pass-through of a contract owned
-            // upstream, and absent simply means dev-mcp falls back to the npub.
-            if let Ok(display_name) = std::env::var("BUZZ_ACP_DISPLAY_NAME") {
-                if !display_name.is_empty() {
-                    env.push(EnvVar {
-                        name: "BUZZ_ACP_DISPLAY_NAME".into(),
-                        value: display_name,
-                    });
+                // Forward the agent's display name so dev-mcp can use it as the git
+                // author name instead of the raw npub. Read from the process env
+                // rather than Config: this is a pass-through of a contract owned
+                // upstream, and absent simply means dev-mcp falls back to the npub.
+                if let Ok(display_name) = std::env::var("BUZZ_ACP_DISPLAY_NAME") {
+                    if !display_name.is_empty() {
+                        env.push(EnvVar {
+                            name: "BUZZ_ACP_DISPLAY_NAME".into(),
+                            value: display_name,
+                        });
+                    }
                 }
-            }
-            env
-        },
-    }]
+                env
+            },
+        });
+    }
+
+    servers.extend(config.configured_mcp_servers.iter().map(|configured| {
+        McpServer {
+            name: configured.name.clone(),
+            command: configured.command.clone(),
+            args: configured.args.clone(),
+            env: configured
+                .env
+                .iter()
+                .map(|(name, value)| EnvVar {
+                    name: name.clone(),
+                    value: value.clone(),
+                })
+                .collect(),
+        }
+    }));
+
+    servers
 }
 
 #[cfg(test)]
@@ -4988,6 +5005,8 @@ mod observer_chunk_coalescer_tests {
 #[cfg(test)]
 mod build_mcp_servers_tests {
     use super::*;
+    use clap::Parser;
+    use std::collections::BTreeMap;
     use std::sync::Mutex;
 
     /// Env-var-touching tests must run serially — env vars are process-global.
@@ -5000,6 +5019,7 @@ mod build_mcp_servers_tests {
             agent_command: "goose".into(),
             agent_args: vec!["acp".into()],
             mcp_command: "test-mcp-server".into(),
+            configured_mcp_servers: Vec::new(),
             idle_timeout_secs: config::DEFAULT_IDLE_TIMEOUT_SECS,
             max_turn_duration_secs: config::DEFAULT_MAX_TURN_DURATION_SECS,
             agents: 1,
@@ -5038,6 +5058,44 @@ mod build_mcp_servers_tests {
         }
     }
 
+    fn configured_server(
+        name: &str,
+        command: &str,
+        args: &[&str],
+        env: &[(&str, &str)],
+    ) -> config::ConfiguredMcpServer {
+        config::ConfiguredMcpServer {
+            name: name.into(),
+            command: command.into(),
+            args: args.iter().map(|arg| (*arg).to_string()).collect(),
+            env: env
+                .iter()
+                .map(|(name, value)| ((*name).to_string(), (*value).to_string()))
+                .collect::<BTreeMap<_, _>>(),
+        }
+    }
+
+    struct TempMcpConfig {
+        path: std::path::PathBuf,
+    }
+
+    impl TempMcpConfig {
+        fn write(content: &[u8]) -> Self {
+            let path = std::env::temp_dir().join(format!(
+                "buzz-acp-mcp-build-test-{}.json",
+                uuid::Uuid::new_v4()
+            ));
+            std::fs::write(&path, content).expect("write temporary MCP config");
+            Self { path }
+        }
+    }
+
+    impl Drop for TempMcpConfig {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_file(&self.path);
+        }
+    }
+
     #[test]
     fn session_new_mcp_server_has_required_fields() {
         let config = test_config();
@@ -5152,6 +5210,167 @@ mod build_mcp_servers_tests {
         );
     }
 
+    #[test]
+    fn structured_servers_preserve_order_and_literal_values_without_legacy_credentials() {
+        let mut config = test_config();
+        config.mcp_command.clear();
+        config.configured_mcp_servers = vec![
+            configured_server(
+                "analytics",
+                "/opt/MCP Servers/analytics,prod",
+                &[
+                    "--stdio",
+                    "two words",
+                    "comma,value",
+                    "\"quoted\"",
+                    r"C:\Program Files\MCP\server.exe",
+                    "雪",
+                    "$(literal)",
+                    "`literal`",
+                    "a|b;c",
+                ],
+                &[
+                    ("ANALYTICS_ENDPOINT", "https://example.test/a=b"),
+                    ("LITERAL_VALUE", "$HOME;`id`|雪"),
+                ],
+            ),
+            configured_server("search", "/opt/search-mcp", &[], &[]),
+        ];
+
+        let servers = build_mcp_servers(&config);
+
+        assert_eq!(servers.len(), 2);
+        assert_eq!(servers[0].name, "analytics");
+        assert_eq!(servers[1].name, "search");
+        assert_eq!(servers[0].command, "/opt/MCP Servers/analytics,prod");
+        assert_eq!(
+            servers[0].args,
+            vec![
+                "--stdio",
+                "two words",
+                "comma,value",
+                "\"quoted\"",
+                r"C:\Program Files\MCP\server.exe",
+                "雪",
+                "$(literal)",
+                "`literal`",
+                "a|b;c",
+            ]
+        );
+        assert_eq!(
+            servers[0]
+                .env
+                .iter()
+                .map(|entry| (entry.name.as_str(), entry.value.as_str()))
+                .collect::<Vec<_>>(),
+            vec![
+                ("ANALYTICS_ENDPOINT", "https://example.test/a=b"),
+                ("LITERAL_VALUE", "$HOME;`id`|雪"),
+            ]
+        );
+        assert!(
+            servers[0].env.iter().all(|entry| !matches!(
+                entry.name.as_str(),
+                "BUZZ_PRIVATE_KEY" | "BUZZ_AUTH_TAG" | "BUZZ_RELAY_URL"
+            )),
+            "structured servers must receive only their declared environment"
+        );
+    }
+
+    #[test]
+    fn legacy_server_remains_first_when_structured_servers_are_present() {
+        let mut config = test_config();
+        config.configured_mcp_servers = vec![configured_server(
+            "analytics",
+            "/opt/analytics-mcp",
+            &["--stdio"],
+            &[("ANALYTICS_TOKEN", "opaque-test-token")],
+        )];
+
+        let servers = build_mcp_servers(&config);
+
+        assert_eq!(servers.len(), 2);
+        assert_eq!(servers[0].name, "test-mcp-server");
+        assert_eq!(servers[1].name, "analytics");
+        assert!(servers[0]
+            .env
+            .iter()
+            .any(|entry| entry.name == "BUZZ_PRIVATE_KEY"));
+        assert_eq!(
+            servers[1]
+                .env
+                .iter()
+                .map(|entry| (entry.name.as_str(), entry.value.as_str()))
+                .collect::<Vec<_>>(),
+            vec![("ANALYTICS_TOKEN", "opaque-test-token")]
+        );
+    }
+
+    #[test]
+    fn structured_json_reaches_initial_repeated_and_respawn_session_lists() {
+        let document = serde_json::json!({
+            "version": 1,
+            "servers": [
+                {
+                    "name": "analytics",
+                    "command": "/opt/MCP Servers/analytics,prod",
+                    "args": ["--stdio", "literal value"],
+                    "env": {
+                        "ANALYTICS_ENDPOINT": "https://example.test/a=b"
+                    }
+                },
+                {
+                    "name": "search",
+                    "command": "/opt/search-mcp",
+                    "args": [],
+                    "env": {}
+                }
+            ]
+        });
+        let file = TempMcpConfig::write(
+            &serde_json::to_vec(&document).expect("serialize MCP config fixture"),
+        );
+        let private_key = nostr::Keys::generate()
+            .secret_key()
+            .to_bech32()
+            .expect("encode temporary private key");
+        let args = config::CliArgs::try_parse_from([
+            "buzz-acp",
+            "--private-key",
+            private_key.as_str(),
+            "--mcp-command",
+            "/opt/buzz-dev-mcp",
+            "--mcp-config",
+            file.path.to_str().expect("temporary path is UTF-8"),
+        ])
+        .expect("parse MCP arguments");
+        let config = Config::from_args(args).expect("load structured MCP config");
+
+        let initial_session = build_mcp_servers(&config);
+        let repeated_session = initial_session.clone();
+        let respawned_session = repeated_session.clone();
+        let initial_json =
+            serde_json::to_value(&initial_session).expect("serialize initial MCP list");
+        let repeated_json =
+            serde_json::to_value(&repeated_session).expect("serialize repeated MCP list");
+        let respawned_json =
+            serde_json::to_value(&respawned_session).expect("serialize respawned MCP list");
+
+        assert_eq!(initial_json, repeated_json);
+        assert_eq!(initial_json, respawned_json);
+        assert_eq!(initial_json.as_array().map(Vec::len), Some(3));
+        assert_eq!(initial_json[0]["name"], "buzz-dev-mcp");
+        assert_eq!(initial_json[1]["name"], "analytics");
+        assert_eq!(initial_json[2]["name"], "search");
+        assert_eq!(
+            initial_json[1]["env"],
+            serde_json::json!([{
+                "name": "ANALYTICS_ENDPOINT",
+                "value": "https://example.test/a=b"
+            }])
+        );
+    }
+
     #[test]
     fn absolute_path_mcp_command_uses_file_stem_as_name() {
         let mut config = test_config();
@@ -5221,6 +5440,7 @@ mod error_outcome_emission_tests {
             agent_command: "true".into(),
             agent_args: vec![],
             mcp_command: "test-mcp-server".into(),
+            configured_mcp_servers: Vec::new(),
             idle_timeout_secs: config::DEFAULT_IDLE_TIMEOUT_SECS,
             max_turn_duration_secs: config::DEFAULT_MAX_TURN_DURATION_SECS,
             agents: 1,
diff --git a/crates/buzz-acp/src/pool.rs b/crates/buzz-acp/src/pool.rs
index d1e005cbcc..348bc138e4 100644
--- a/crates/buzz-acp/src/pool.rs
+++ b/crates/buzz-acp/src/pool.rs
@@ -19,6 +19,7 @@
 //!
 //! `AcpClient` is NOT Clone — ownership moves out on claim and back on return.
 
+use std::cmp::Reverse;
 use std::collections::{HashMap, HashSet};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -800,6 +801,9 @@ pub enum IdleSwitchResult {
 /// 2 × CONTEXT_FETCH_TIMEOUT + CONTEXT_FETCH_RETRY_DELAY ≈ 6.5 s.
 const CONTEXT_FETCH_TIMEOUT: Duration = Duration::from_millis(3_000);
 
+/// Short, single-attempt timeout for best-effort exact truncated-thread counts.
+const CONTEXT_COUNT_TIMEOUT: Duration = Duration::from_millis(500);
+
 /// Delay between the first failed context fetch and the single retry.
 const CONTEXT_FETCH_RETRY_DELAY: Duration = Duration::from_millis(500);
 
@@ -2600,7 +2604,14 @@ async fn fetch_conversation_context(
     let last_event = batch.events.last()?;
     let tags = crate::queue::parse_thread_tags(&last_event.event);
     if let Some(root_id) = tags.root_event_id {
-        return fetch_thread_context(batch.channel_id, &root_id, limit, &ctx.rest_client).await;
+        return fetch_thread_context(
+            batch.channel_id,
+            &root_id,
+            limit,
+            ctx.agent_keys.public_key(),
+            &ctx.rest_client,
+        )
+        .await;
     }
 
     // DM non-reply: fetch recent conversation history.
@@ -2762,12 +2773,48 @@ async fn fetch_prompt_profile_lookup(
 }
 
 /// Fetch thread context via Nostr query: root event by ID + replies by `#e` tag.
+///
+/// The reply query intentionally requests one more reply than the configured
+/// display window. That sentinel event lets the prompt say `N of M, truncated`
+/// when the relay has more thread history, instead of reporting the capped page
+/// as the total. When the window is full, a best-effort `/count` attempts to
+/// improve that lower-bound total; because it is a separate racy request, the
+/// result is clamped to the sentinel-proven minimum. The query also asks for the
+/// agent's newest reply separately so the next prompt can include the agent's
+/// own prior turn even in busy threads where the recent-message window would
+/// otherwise push it out.
 async fn fetch_thread_context(
     channel_id: Uuid,
     root_event_id: &str,
     limit: u32,
+    agent_pubkey: nostr::PublicKey,
     rest: &RestClient,
 ) -> Option<ConversationContext> {
+    fetch_thread_context_with(
+        channel_id,
+        root_event_id,
+        limit,
+        agent_pubkey,
+        |filters| async move { rest.query(&filters).await },
+        |filters| async move { rest.count(&filters).await },
+    )
+    .await
+}
+
+async fn fetch_thread_context_with<Query, QueryFut, Count, CountFut>(
+    channel_id: Uuid,
+    root_event_id: &str,
+    limit: u32,
+    agent_pubkey: nostr::PublicKey,
+    query: Query,
+    count: Count,
+) -> Option<ConversationContext>
+where
+    Query: Fn(Vec<nostr::Filter>) -> QueryFut,
+    QueryFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+    Count: Fn(Vec<nostr::Filter>) -> CountFut,
+    CountFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+{
     use nostr::{Alphabet, SingleLetterTag};
 
     // Defense-in-depth: validate hex event ID.
@@ -2786,7 +2833,8 @@ async fn fetch_thread_context(
     let h_tag = SingleLetterTag::lowercase(Alphabet::H);
     let ch_str = channel_id.to_string();
 
-    // Two filters: (1) root event by ID, (2) replies with #e=root + #h=channel.
+    // Three filters: (1) root event by ID, (2) recent replies with #e=root +
+    // #h=channel plus a sentinel, and (3) the agent's newest reply for pinning.
     let root_filter = nostr::Filter::new().id(nostr::EventId::from_hex(root_event_id).ok()?);
     let replies_filter = nostr::Filter::new()
         .kinds([
@@ -2795,16 +2843,23 @@ async fn fetch_thread_context(
         ])
         .custom_tags(e_tag, [root_event_id])
         .custom_tags(h_tag, [ch_str.as_str()])
-        .limit(limit as usize);
+        .limit(limit.saturating_add(1) as usize);
+    let agent_reply_filter = replies_filter.clone().author(agent_pubkey).limit(1);
 
-    fetch_with_retry(|| async {
+    let context = fetch_with_retry(|| async {
         match timeout(
             CONTEXT_FETCH_TIMEOUT,
-            rest.query(&[root_filter.clone(), replies_filter.clone()]),
+            query(vec![
+                root_filter.clone(),
+                replies_filter.clone(),
+                agent_reply_filter.clone(),
+            ]),
         )
         .await
         {
-            Ok(Ok(json)) => parse_nostr_thread_response(json, root_event_id),
+            Ok(Ok(json)) => {
+                parse_nostr_thread_response_with_meta(json, root_event_id, limit, &agent_pubkey)
+            }
             Ok(Err(e)) => {
                 tracing::warn!(
                     channel_id = %channel_id,
@@ -2823,7 +2878,75 @@ async fn fetch_thread_context(
             }
         }
     })
-    .await
+    .await;
+
+    let mut parsed = context?;
+
+    if matches!(
+        parsed.context,
+        ConversationContext::Thread {
+            truncated: true,
+            ..
+        }
+    ) {
+        let replies_count_filter = replies_filter.clone().limit(0);
+        if let Some(total) = fetch_thread_total(
+            channel_id,
+            &replies_count_filter,
+            parsed.root_present,
+            &count,
+        )
+        .await
+        {
+            if let ConversationContext::Thread {
+                total: context_total,
+                ..
+            } = &mut parsed.context
+            {
+                let sentinel_minimum = *context_total;
+                // `/count` is a separate best-effort request after the message
+                // query. If replies are deleted between the two, the exact count
+                // can fall below the already-proven sentinel minimum; never
+                // render impossible labels like `13 of 12 messages, truncated`.
+                *context_total = total.max(sentinel_minimum);
+            }
+        }
+    }
+
+    Some(parsed.context)
+}
+
+/// Best-effort exact thread size for truncated context labels.
+async fn fetch_thread_total<Count, CountFut>(
+    channel_id: Uuid,
+    replies_filter: &nostr::Filter,
+    root_present: bool,
+    count: &Count,
+) -> Option<usize>
+where
+    Count: Fn(Vec<nostr::Filter>) -> CountFut,
+    CountFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+{
+    let replies_count =
+        match timeout(CONTEXT_COUNT_TIMEOUT, count(vec![replies_filter.clone()])).await {
+            Ok(Ok(json)) => json.get("count").and_then(|v| v.as_u64())?,
+            Ok(Err(e)) => {
+                tracing::debug!(
+                    channel_id = %channel_id,
+                    "thread context count failed; using sentinel minimum: {e}"
+                );
+                return None;
+            }
+            Err(_) => {
+                tracing::debug!(
+                    channel_id = %channel_id,
+                    "thread context count timed out; using sentinel minimum"
+                );
+                return None;
+            }
+        };
+
+    Some(replies_count as usize + usize::from(root_present))
 }
 
 /// Fetch DM context via Nostr query: recent messages in channel by `#h` tag.
@@ -2976,48 +3099,110 @@ fn json_to_context_message(obj: &serde_json::Value) -> Option<ContextMessage> {
 
 /// Parse a Nostr query response (array of events) into thread context.
 ///
-/// Separates the root event (matching `root_event_id`) from replies, sorts
-/// chronologically by `created_at`.
+/// Separates the root event (matching `root_event_id`) from replies, keeps the
+/// newest `limit` replies returned by the sentinel query, then sorts the
+/// displayed window chronologically for the prompt. If the agent's newest reply
+/// is outside that window, keep it instead of the oldest displayed reply so the
+/// next prompt always includes the agent's most recent prior turn.
+#[cfg(test)]
 fn parse_nostr_thread_response(
     json: serde_json::Value,
     root_event_id: &str,
+    limit: u32,
+    agent_pubkey: &nostr::PublicKey,
 ) -> Option<ConversationContext> {
+    parse_nostr_thread_response_with_meta(json, root_event_id, limit, agent_pubkey)
+        .map(|parsed| parsed.context)
+}
+
+struct ParsedThreadContext {
+    context: ConversationContext,
+    root_present: bool,
+}
+
+fn parse_nostr_thread_response_with_meta(
+    json: serde_json::Value,
+    root_event_id: &str,
+    limit: u32,
+    agent_pubkey: &nostr::PublicKey,
+) -> Option<ParsedThreadContext> {
     let events = json.as_array()?;
+    let agent_pubkey_hex = agent_pubkey.to_hex();
     let mut root_msg = None;
     let mut reply_msgs = Vec::new();
+    let mut seen_reply_ids = HashSet::new();
 
     for ev in events {
         let ev_id = ev.get("id").and_then(|v| v.as_str()).unwrap_or("");
         if let Some(msg) = json_to_context_message(ev) {
             if ev_id == root_event_id {
                 root_msg = Some(msg);
-            } else {
+            } else if seen_reply_ids.insert(ev_id.to_string()) {
+                let is_agent = msg.pubkey.eq_ignore_ascii_case(&agent_pubkey_hex);
                 reply_msgs.push((
+                    ev_id.to_string(),
                     ev.get("created_at").and_then(|v| v.as_u64()).unwrap_or(0),
+                    is_agent,
                     msg,
                 ));
             }
         }
     }
 
-    // Sort replies chronologically.
-    reply_msgs.sort_by_key(|(ts, _)| *ts);
+    let root_present = root_msg.is_some();
+    let fetched_total = reply_msgs.len() + usize::from(root_present);
+    let newest_agent_reply = reply_msgs
+        .iter()
+        .filter(|(_, _, is_agent, _)| *is_agent)
+        .max_by_key(|(_, ts, _, _)| *ts)
+        .cloned();
+
+    let truncated = reply_msgs.len() > limit as usize;
+    if truncated {
+        // The relay returns limited REQ results newest-first. Sort explicitly so
+        // the sentinel we drop is the oldest reply in the fetched window, not an
+        // arbitrary last element if the HTTP bridge ever changes iteration order.
+        reply_msgs.sort_by_key(|(_, ts, _, _)| Reverse(*ts));
+        reply_msgs.truncate(limit as usize);
+    }
+
+    if let Some(agent_reply) = newest_agent_reply {
+        let agent_reply_already_displayed =
+            reply_msgs.iter().any(|(id, _, _, _)| *id == agent_reply.0);
+        if !agent_reply_already_displayed {
+            reply_msgs.sort_by_key(|(_, ts, _, _)| *ts);
+            if let Some(oldest) = reply_msgs.first_mut() {
+                *oldest = agent_reply;
+            }
+        }
+    }
+
+    // Sort displayed replies chronologically.
+    reply_msgs.sort_by_key(|(_, ts, _, _)| *ts);
 
     let mut messages = Vec::new();
     if let Some(root) = root_msg {
         messages.push(root);
     }
-    messages.extend(reply_msgs.into_iter().map(|(_, msg)| msg));
+    messages.extend(reply_msgs.into_iter().map(|(_, _, _, msg)| msg));
 
-    let total = messages.len();
     if messages.is_empty() {
         return None;
     }
 
-    Some(ConversationContext::Thread {
-        messages,
-        total,
-        truncated: false, // query returns all within limit
+    let total = if truncated {
+        fetched_total // all distinct fetched replies plus the root are proven visible history
+    } else {
+        messages.len()
+    };
+
+    Some(ParsedThreadContext {
+        context: ConversationContext::Thread {
+            messages,
+            total,
+            truncated,
+        },
+        root_present,
     })
 }
 
@@ -3439,7 +3624,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 {
@@ -3457,7 +3646,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)
@@ -4204,6 +4399,572 @@ mod tests {
         assert!(parse_dm_response(json, 12).is_none());
     }
 
+    #[test]
+    fn test_parse_nostr_thread_response_marks_query_window_truncated() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let agent_hex = agent.public_key().to_hex();
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": agent_hex,
+                "content": "newest agent reply",
+                "created_at": 4000
+            },
+            {
+                "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "pubkey": "humanpub",
+                "content": "middle reply",
+                "created_at": 3000
+            },
+            {
+                "id": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "pubkey": "oldpub",
+                "content": "sentinel omitted reply",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert_eq!(messages.len(), 3); // root + 2 displayed replies
+                assert_eq!(total, 4); // root + displayed replies + sentinel
+                assert!(truncated);
+                assert_eq!(messages[0].content, "root");
+                assert_eq!(messages[1].content, "middle reply");
+                assert_eq!(messages[2].content, "newest agent reply");
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "sentinel omitted reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[test]
+    fn test_parse_nostr_thread_response_not_truncated_below_limit() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": "replypub",
+                "content": "reply",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert_eq!(messages.len(), 2);
+                assert_eq!(total, 2);
+                assert!(!truncated);
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[test]
+    fn test_parse_nostr_thread_response_keeps_agent_reply_outside_recent_window() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let agent_hex = agent.public_key().to_hex();
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": "humanpub",
+                "content": "newer human reply",
+                "created_at": 5000
+            },
+            {
+                "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "pubkey": "humanpub",
+                "content": "middle human reply",
+                "created_at": 4000
+            },
+            {
+                "id": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "pubkey": "humanpub",
+                "content": "oldest displayed reply without agent pin",
+                "created_at": 3000
+            },
+            {
+                "id": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+                "pubkey": agent_hex,
+                "content": "agent reply outside recent window",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread { messages, .. } => {
+                assert_eq!(messages.len(), 3); // root + 2 displayed replies
+                assert_eq!(messages[0].content, "root");
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "agent reply outside recent window"));
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newer human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "oldest displayed reply without agent pin"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_uses_exact_count_when_above_sentinel_minimum() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let agent_pubkey = agent.public_key();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent_pubkey,
+            move |filters| {
+                assert_thread_query_filters(&filters, channel_id, root_id, agent_pubkey, 3);
+                std::future::ready(Ok(json.clone()))
+            },
+            move |filters| {
+                assert_thread_count_filter(&filters, channel_id, root_id);
+                std::future::ready(Ok(json!({ "count": 6 })))
+            },
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 7); // 6 replies + root
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_does_not_add_missing_root_to_exact_count() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 6 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 2);
+                assert_eq!(total, 6);
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_clamps_count_below_sentinel_minimum() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 1 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 4); // root + displayed replies + sentinel minimum
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_preserves_sentinel_minimum_when_count_fails() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Err(crate::relay::RelayError::Http("boom".into()))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 4); // count failure leaves parser's sentinel minimum intact
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_deduplicates_and_pins_agent_reply() {
+        let agent = Keys::generate();
+        let agent_hex = agent.public_key().to_hex();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newer human reply",
+                5000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle human reply",
+                4000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                &agent_hex,
+                "agent reply outside recent window",
+                2000
+            ),
+            // Same event as the separately fetched author-filtered result; the
+            // parser should deduplicate it before pinning.
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                &agent_hex,
+                "agent reply outside recent window",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 3 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(total, 4);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(
+                    messages
+                        .iter()
+                        .filter(|msg| msg.content == "agent reply outside recent window")
+                        .count(),
+                    1,
+                    "separate agent-reply query must not duplicate the same event"
+                );
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newer human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_uses_distinct_fetched_replies_as_minimum() {
+        let agent = Keys::generate();
+        let agent_hex = agent.public_key().to_hex();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest human reply",
+                5000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle human reply",
+                4000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel human reply",
+                3000
+            ),
+            thread_event(
+                "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+                &agent_hex,
+                "older distinct agent reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Err(crate::relay::RelayError::Http("boom".into()))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(
+                    total, 5,
+                    "root plus all four distinct fetched replies prove the lower bound"
+                );
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "older distinct agent reply"));
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newest human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "sentinel human reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    fn assert_thread_query_filters(
+        filters: &[nostr::Filter],
+        channel_id: Uuid,
+        root_id: &str,
+        agent_pubkey: nostr::PublicKey,
+        reply_limit: u64,
+    ) {
+        assert_eq!(
+            filters.len(),
+            3,
+            "root, recent replies, and agent reply filters"
+        );
+
+        let root = serde_json::to_value(&filters[0]).expect("serialize root filter");
+        assert_eq!(root.get("ids"), Some(&json!([root_id])));
+        assert!(root.get("limit").is_none());
+
+        let replies = serde_json::to_value(&filters[1]).expect("serialize replies filter");
+        assert_eq!(replies.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(replies.get("#e"), Some(&json!([root_id])));
+        assert_eq!(replies.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(replies.get("limit"), Some(&json!(reply_limit)));
+        assert!(replies.get("authors").is_none());
+
+        let agent = serde_json::to_value(&filters[2]).expect("serialize agent filter");
+        assert_eq!(agent.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(agent.get("#e"), Some(&json!([root_id])));
+        assert_eq!(agent.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(agent.get("authors"), Some(&json!([agent_pubkey.to_hex()])));
+        assert_eq!(agent.get("limit"), Some(&json!(1)));
+    }
+
+    fn assert_thread_count_filter(filters: &[nostr::Filter], channel_id: Uuid, root_id: &str) {
+        assert_eq!(filters.len(), 1, "count should query only matching replies");
+
+        let count = serde_json::to_value(&filters[0]).expect("serialize count filter");
+        assert_eq!(count.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(count.get("#e"), Some(&json!([root_id])));
+        assert_eq!(count.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(count.get("limit"), Some(&json!(0)));
+        assert!(count.get("ids").is_none());
+        assert!(count.get("authors").is_none());
+    }
+
+    fn thread_event(id: &str, pubkey: &str, content: &str, created_at: u64) -> serde_json::Value {
+        json!({
+            "id": id,
+            "pubkey": pubkey,
+            "content": content,
+            "created_at": created_at
+        })
+    }
+
     #[test]
     fn test_json_to_context_message_integer_timestamp() {
         let obj = json!({
@@ -5271,10 +6032,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.
@@ -5305,10 +6068,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.
@@ -5340,10 +6105,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.
@@ -5375,10 +6142,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.
@@ -5407,10 +6176,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,
         };
 
@@ -5454,10 +6225,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,
         };
 
@@ -5497,6 +6270,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)
diff --git a/crates/buzz-acp/src/relay.rs b/crates/buzz-acp/src/relay.rs
index c8312cc61e..aea5cee077 100644
--- a/crates/buzz-acp/src/relay.rs
+++ b/crates/buzz-acp/src/relay.rs
@@ -405,6 +405,19 @@ impl RestClient {
             .map_err(|e| RelayError::Http(e.to_string()))
     }
 
+    /// Count events via the HTTP bridge: `POST /count` with NIP-98 auth.
+    ///
+    /// Accepts a slice of `nostr::Filter` (serialized as JSON array).
+    /// Returns the bridge response as a `serde_json::Value` (usually `{ "count": n }`).
+    pub async fn count(&self, filters: &[nostr::Filter]) -> Result<Value, RelayError> {
+        let body_bytes = serde_json::to_vec(filters)
+            .map_err(|e| RelayError::Http(format!("filter serialize error: {e}")))?;
+        let resp = self.bridge_post("/count", &body_bytes).await?;
+        resp.json()
+            .await
+            .map_err(|e| RelayError::Http(e.to_string()))
+    }
+
     /// Submit a signed event via the HTTP bridge: `POST /events` with NIP-98 auth.
     ///
     /// The event must already be signed. Returns the relay response JSON.
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-acp/tests/config_env.rs b/crates/buzz-acp/tests/config_env.rs
new file mode 100644
index 0000000000..177ac3fea5
--- /dev/null
+++ b/crates/buzz-acp/tests/config_env.rs
@@ -0,0 +1,21 @@
+use std::process::Command;
+
+#[test]
+fn empty_mcp_config_environment_value_is_treated_as_unset() {
+    let output = Command::new(env!("CARGO_BIN_EXE_buzz-acp"))
+        .env("BUZZ_ACP_MCP_CONFIG", "")
+        .args(["--private-key", "not-a-valid-nostr-key"])
+        .output()
+        .expect("run buzz-acp");
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(!output.status.success());
+    assert!(
+        stderr.contains("configuration error: failed to parse nostr keys"),
+        "empty optional MCP config should reach normal configuration validation: {stderr}"
+    );
+    assert!(
+        !stderr.contains("a value is required for '--mcp-config"),
+        "empty optional MCP config must not fail Clap parsing: {stderr}"
+    );
+}
diff --git a/crates/buzz-agent/README.md b/crates/buzz-agent/README.md
index f138e4a4f1..5d942777d5 100644
--- a/crates/buzz-agent/README.md
+++ b/crates/buzz-agent/README.md
@@ -163,6 +163,67 @@ Everything is environment variables. No flags, no config files. (We are a subpro
 | `BUZZ_AGENT_MAX_LINE_BYTES` | `4194304` | 4 MiB. Hard cap on inbound JSON-RPC frames. |
 | `BUZZ_AGENT_MAX_HISTORY_BYTES` | `1048576` | 1 MiB. Old turns are evicted past this. |
 | `BUZZ_AGENT_MAX_TOOL_RESULT_TEXT_BYTES` | `51200` | 50 KiB. Per-result cap on tool-output text; oversize is middle-elided (head + tail kept) with an inline marker. Images are exempt. |
+| `BUZZ_AGENT_REQUIRE_REPLY` | `0` (`1` on mesh) | `1` enables the [reply guard](#reply-guard) — remind the model to publish when a turn is about to end with nothing posted to Buzz. Desktop defaults it to `1` for Buzz shared-compute agents. |
+
+
+## Reply Guard
+
+Off by default, except on Buzz shared-compute (mesh) agents, where Buzz Desktop
+sets `BUZZ_AGENT_REQUIRE_REPLY=1` automatically. With it enabled, a turn that is
+about to end without any recognized attempt to post to Buzz gets a reminder that
+its assistant text is invisible to humans, and is rerolled.
+
+This exists because a Buzz agent's reasoning and tool output are not shown to
+anyone. A turn that does real work and never posts is a silent failure — the
+requester waits on a result that was produced and thrown away.
+
+Mesh agents get it by default because they run on small local models, which are
+the ones most likely to do the work and then end the turn without publishing it.
+Setting `BUZZ_AGENT_REQUIRE_REPLY=0` on the agent, persona, or global env opts a
+mesh agent back out; the default never overrides an explicit value.
+
+**Advisory, never a trap.** At most two reminders, then the turn ends whether or
+not anything was published. The guard catches accidental omission; it does not
+compel speech. The reminder text explicitly licenses silence, because the
+built-in system prompt says publishing is optional and silence is often the
+correct outcome.
+
+**Recognition contract.** A turn counts as having replied when it issues a call
+that:
+
+- resolves to a registered, non-hook tool (a hallucinated tool name is rejected
+  at preflight and never runs, so it must not disarm the guard),
+- whose qualified name ends in `__shell` — i.e. the bare tool name is exactly
+  `shell`, which is `buzz-dev-mcp`'s shell tool and any other server's, and
+- whose `command` argument contains `messages send` or `reactions add`.
+
+`messages send` also covers `messages send-diff`. Reactions count because the
+built-in prompt directs agents to react rather than post a bare
+acknowledgement, so nagging an agent that reacted would punish documented
+behavior.
+
+Detection is checked **after** the per-turn tool-call cap
+(`MAX_TOOL_CALLS_PER_TURN`) is applied: a publish-shaped call that was discarded
+never ran.
+
+**It recognizes an attempt, not a successful publish.** Only the command text is
+inspected, never the exit status. A send that fails still satisfies the guard —
+which is fine, since a failed send already returns a non-zero exit and error
+JSON to the model, louder feedback than a reminder.
+
+**Known limits**, both deliberate. A command assembled at runtime (`$CMD`) or
+buried in a wrapper script is missed, so that turn is reminded despite having
+posted. Text that merely quotes a send (`echo "buzz messages send"`) matches, so
+that turn is not reminded. Missing a real post is the expensive direction, and
+substring matching is the forgiving one there. Neither edge is pinned by a test;
+the matcher is free to improve.
+
+**Budget.** Reminders ride the existing `_Stop` gate and share
+`BUZZ_AGENT_STOP_MAX_REJECTIONS` — the outer cap on every end-turn objection.
+At the default 3 both reminders fit; at 1 only one does; at 0 the guard is off
+along with the hooks. A round carrying both a `_Stop` hook objection and a
+reminder costs one rejection and delivers both texts. This is not a new
+lifecycle hook — see [MCP_DRIVEN_HOOKS.md](../../docs/MCP_DRIVEN_HOOKS.md).
 
 
 ## Providers
diff --git a/crates/buzz-agent/src/agent.rs b/crates/buzz-agent/src/agent.rs
index 48d4ea3b02..8e14fee195 100644
--- a/crates/buzz-agent/src/agent.rs
+++ b/crates/buzz-agent/src/agent.rs
@@ -21,6 +21,80 @@ use crate::wire::{self, WireSender};
 const ERROR_REFLECTION_SUFFIX: &str =
     "\n\n[Reflect] Before retrying, identify the cause and change your approach.";
 
+/// 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
+/// published: the guard exists to catch accidental omission, not to compel
+/// speech. The shared `stop_max_rejections` budget can cut this lower — see
+/// [`Config::require_reply`](crate::config::Config::require_reply).
+const MAX_REPLY_NAGS: u32 = 2;
+
+/// Server label on the synthetic reply-guard objection.
+///
+/// Not a real MCP server. It rides the same tool-result path as `_Stop` hook
+/// output, so the model sees `{hook, server, text}` attribution naming the
+/// in-process guard rather than an MCP server that could be impersonated.
+const REPLY_GUARD_SERVER: &str = "buzz-agent";
+
+/// Reminder text emitted when a turn is about to end with nothing published.
+///
+/// Explicitly licenses silence. The base prompt tells agents that publishing is
+/// optional and "silence is usually correct"; a reminder that argued otherwise
+/// would fight that instruction and make agents chattier.
+const REPLY_GUARD_NAG: &str = "You are about to end this turn without calling `buzz messages send`. \
+Your assistant text and reasoning are never shown to anyone — if you did work, found an answer, \
+or hit a blocker that someone is waiting on, it exists only if you publish it. \
+If you already posted, or if silence is genuinely correct for this turn, ignore this and end your turn.";
+
+/// Whether `call` is a recognized attempt to publish a reply to Buzz.
+///
+/// Recognizes an *attempt*, not a successful publish: the command text is
+/// inspected, never the exit status. That is deliberate — a send that fails
+/// already returns a non-zero exit and error JSON to the model, which is louder
+/// feedback than the reminder this gates.
+///
+/// `has` + `!is_hook` are the same checks the dispatcher uses to accept a call
+/// (see `execute_calls`), so a hallucinated `fake__shell` — rejected at preflight
+/// and never executed — cannot disarm the guard. They must stay *before*
+/// [`is_reply_shaped`]: together with them, and only with them, the `__shell`
+/// suffix is exactly equivalent to "the bare tool name is `shell`".
+fn is_buzz_reply_call(call: &ToolCall, mcp: &McpRegistry) -> bool {
+    mcp.has(&call.name) && !mcp.is_hook(&call.name) && is_reply_shaped(&call.name, &call.arguments)
+}
+
+/// Whether a tool name and arguments have the shape of a Buzz publish command.
+///
+/// Split from [`is_buzz_reply_call`] only so the matcher is testable without a
+/// live [`McpRegistry`]; callers must apply the registry checks first.
+///
+/// On the name: `ends_with("__shell")` is exact rather than approximate *given*
+/// those checks. Registration rejects `__` in both server names and bare tool
+/// names, and qualified names are `{server}__{bare}`, so a trailing `__shell` can
+/// only straddle the separator if the bare name starts with `_` — which `is_hook`
+/// already excludes. Dropping the separator would not be exact: `powershell` and
+/// `noshell` both end in `shell`.
+///
+/// On the command: a deliberately coarse substring test, scoped to the structured
+/// `command` field so unrelated metadata — a `description` that quotes a send —
+/// cannot suppress the guard, and a non-string `command` is rejected rather than
+/// coerced. Known limits, both accepted: a command assembled at runtime (`$CMD`)
+/// or hidden in a wrapper script is missed, and text that merely quotes a send
+/// (`echo "buzz messages send"`) matches. Missing a real post is the expensive
+/// direction, and substring matching is the more forgiving one there.
+fn is_reply_shaped(name: &str, arguments: &serde_json::Value) -> bool {
+    name.ends_with("__shell")
+        && arguments
+            .get("command")
+            .and_then(|v| v.as_str())
+            .is_some_and(|cmd| {
+                // `messages send` also covers `messages send-diff`. `reactions
+                // add` counts because the base prompt directs agents to react
+                // rather than post a bare acknowledgement, so nagging an agent
+                // that reacted would punish documented-correct behavior.
+                cmd.contains("messages send") || cmd.contains("reactions add")
+            })
+}
+
 pub struct RunCtx<'a> {
     pub cfg: &'a Config,
     /// Effective model for this session. Usually equals `cfg.model`; overridden
@@ -102,6 +176,14 @@ impl RunCtx<'_> {
         // session) so a stubborn exchange can't permanently disable the stop
         // guard for a long-lived session; `max_rounds` still caps the loop.
         let mut stop_rejections = 0u32;
+        // Reply-guard state for this prompt. `prompt()` *is* the turn, so
+        // locals here are per-turn by construction — same shape as
+        // `stop_rejections` above.
+        //
+        // Named for what it proves: a *recognized attempt* to publish, not a
+        // successful publish. See `is_buzz_reply_call`.
+        let mut buzz_reply_call_seen = false;
+        let mut reply_nags = 0u32;
         loop {
             if self.cfg.max_rounds > 0 && round >= self.cfg.max_rounds {
                 return Ok(StopReason::MaxTurnRequests);
@@ -264,7 +346,7 @@ impl RunCtx<'_> {
                     if stop_rejections >= self.cfg.stop_max_rejections {
                         return Ok(stop);
                     }
-                    let objections = self
+                    let mut objections = self
                         .mcp
                         .call_hooks(
                             "_Stop",
@@ -273,6 +355,17 @@ impl RunCtx<'_> {
                             &self.cfg.hook_servers,
                         )
                         .await;
+                    // Reply guard shares this gate and this budget, so a round
+                    // carrying both a hook objection and a reply reminder costs
+                    // one rejection and delivers both texts.
+                    if self.cfg.require_reply
+                        && !buzz_reply_call_seen
+                        && reply_nags < MAX_REPLY_NAGS
+                    {
+                        reply_nags += 1;
+                        objections
+                            .push((REPLY_GUARD_SERVER.to_string(), REPLY_GUARD_NAG.to_string()));
+                    }
                     if !objections.is_empty() {
                         stop_rejections = stop_rejections.saturating_add(1);
                         push_hook_outputs_as_tool_results(self.history, "_Stop", &objections);
@@ -290,6 +383,11 @@ impl RunCtx<'_> {
                 );
                 calls.truncate(MAX_TOOL_CALLS_PER_TURN);
             }
+            // Deliberately after truncation: a publish-shaped call that was
+            // discarded never runs, so it must not suppress the reminder.
+            if self.cfg.require_reply && !buzz_reply_call_seen {
+                buzz_reply_call_seen = calls.iter().any(|c| is_buzz_reply_call(c, self.mcp));
+            }
             self.history.push(HistoryItem::Assistant {
                 text: response.text,
                 tool_calls: calls.clone(),
@@ -799,6 +897,88 @@ mod tests {
     use super::*;
     use serde_json::json;
 
+    /// 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]
+    fn reply_shape_matches_documented_send_forms() {
+        for cmd in [
+            "buzz messages send --channel X --content Y",
+            "buzz --relay wss://r messages send --channel X --content Y",
+            "/abs/path/buzz messages send",
+            "printf 'hi' | buzz messages send --content -",
+            "buzz messages send-diff --diff -",
+            "buzz reactions add --event E --emoji +",
+            // Assembled through another shell: rev 3's tokenizer missed this.
+            r#"sh -c "buzz messages send --channel X""#,
+        ] {
+            assert!(
+                is_reply_shaped("dev__shell", &json!({ "command": cmd })),
+                "expected {cmd:?} to count as a publish attempt"
+            );
+        }
+    }
+
+    /// Commands that do real work but do not reply in the originating
+    /// conversation must still be nagged.
+    #[test]
+    fn reply_shape_rejects_non_reply_commands() {
+        for cmd in [
+            "buzz messages get --channel X",
+            "buzz channels list",
+            "buzz reactions remove --event E",
+            "buzz pr open --title T",
+            "buzz social publish --content hi",
+            "buzz notes set --name n",
+            "cargo test -p buzz-agent",
+        ] {
+            assert!(
+                !is_reply_shaped("dev__shell", &json!({ "command": cmd })),
+                "expected {cmd:?} not to count as a publish attempt"
+            );
+        }
+    }
+
+    /// The `__` separator is load-bearing: `ends_with("shell")` alone would
+    /// accept any registered tool whose name merely ends in those letters, and
+    /// `has()` proves registration, not the bare name.
+    #[test]
+    fn reply_shape_requires_the_qname_separator() {
+        let args = json!({ "command": "buzz messages send --channel X" });
+        for name in [
+            "dev__powershell",
+            "dev__noshell",
+            "shell",
+            "dev__send_message",
+        ] {
+            assert!(
+                !is_reply_shaped(name, &args),
+                "{name} must not satisfy the shell-tool check"
+            );
+        }
+        assert!(is_reply_shaped("dev__shell", &args));
+        assert!(is_reply_shaped("buzz-dev-mcp__shell", &args));
+    }
+
+    /// Only the field that carries the executable command counts. Searching
+    /// serialized arguments instead would let arbitrary metadata disarm the
+    /// guard, turning a description into an attempted send.
+    #[test]
+    fn reply_shape_reads_only_the_command_field() {
+        assert!(!is_reply_shaped(
+            "dev__shell",
+            &json!({ "description": "buzz messages send --channel X" })
+        ));
+        assert!(!is_reply_shaped(
+            "dev__shell",
+            &json!({ "workdir": "buzz messages send" })
+        ));
+        // Malformed `command` is rejected, not coerced — and must not panic.
+        assert!(!is_reply_shaped("dev__shell", &json!({ "command": 42 })));
+        assert!(!is_reply_shaped("dev__shell", &json!({ "command": null })));
+        assert!(!is_reply_shaped("dev__shell", &json!({})));
+        assert!(!is_reply_shaped("dev__shell", &json!("not an object")));
+    }
+
     /// A9 regression: `reasoning_details` contributes real bytes to
     /// `estimated_bytes` (see `types.rs::HistoryItem::size_with`), so a
     /// history item carrying a large opaque reasoning array must actually
diff --git a/crates/buzz-agent/src/config.rs b/crates/buzz-agent/src/config.rs
index a0e64f1a9d..afbda5379d 100644
--- a/crates/buzz-agent/src/config.rs
+++ b/crates/buzz-agent/src/config.rs
@@ -720,6 +720,16 @@ pub struct Config {
     /// Maximum `_Stop` rejections per prompt. Default 3. Set to 0 to
     /// disable `_Stop` hooks entirely (agent always honors end_turn).
     pub stop_max_rejections: u32,
+    /// Remind the model to publish when a turn is about to end without any
+    /// recognized attempt to post to Buzz. Default off; opt in per agent with
+    /// `BUZZ_AGENT_REQUIRE_REPLY=1`.
+    ///
+    /// Advisory only: at most `MAX_REPLY_NAGS` reminders (see `agent.rs`),
+    /// then the turn ends regardless. Bounded by the same
+    /// `stop_max_rejections` budget as `_Stop` hooks, which is the outer cap on
+    /// all end-turn objections — at the default 3 both reminders fit; at 1 only
+    /// one does; at 0 the guard is off with the hooks.
+    pub require_reply: bool,
     /// Hook server allowlist. See [`HookServers`] for variant semantics.
     /// Default (env unset/empty) is `None` — hooks are off unless the
     /// operator explicitly opts in.
@@ -851,6 +861,7 @@ impl Config {
             max_parallel_tools: parse_env("BUZZ_AGENT_MAX_PARALLEL_TOOLS", 8usize)?,
             hook_timeout: Duration::from_millis(parse_env("BUZZ_AGENT_HOOK_TIMEOUT_MS", 2500u64)?),
             stop_max_rejections: parse_env("BUZZ_AGENT_STOP_MAX_REJECTIONS", 3u32)?,
+            require_reply: parse_env("BUZZ_AGENT_REQUIRE_REPLY", 0u8)? != 0,
             hook_servers: parse_hook_servers_env("MCP_HOOK_SERVERS"),
             hints_enabled: parse_env("BUZZ_AGENT_NO_HINTS", 0u8)? == 0,
             thinking_effort: parse_thinking_effort(env("BUZZ_AGENT_THINKING_EFFORT").as_deref())?,
@@ -893,6 +904,7 @@ impl Config {
             max_parallel_tools: 1,
             hook_timeout: Duration::from_secs(1),
             stop_max_rejections: 0,
+            require_reply: false,
             hook_servers: HookServers::None,
             hints_enabled: false,
             thinking_effort: None,
diff --git a/crates/buzz-agent/src/llm.rs b/crates/buzz-agent/src/llm.rs
index f595a165e5..73c7e1faf2 100644
--- a/crates/buzz-agent/src/llm.rs
+++ b/crates/buzz-agent/src/llm.rs
@@ -2355,6 +2355,7 @@ mod tests {
             max_parallel_tools: 1,
             hook_timeout: Duration::from_secs(1),
             stop_max_rejections: 0,
+            require_reply: false,
             hook_servers: HookServers::None,
             api_key: "key".into(),
             model: "model".into(),
diff --git a/crates/buzz-agent/tests/bin/fake_mcp.rs b/crates/buzz-agent/tests/bin/fake_mcp.rs
index 0bbd1d3478..5b660da48c 100644
--- a/crates/buzz-agent/tests/bin/fake_mcp.rs
+++ b/crates/buzz-agent/tests/bin/fake_mcp.rs
@@ -33,6 +33,11 @@
 //!                            — expose a `_PostCompact` hook tool
 //!   FAKE_MCP_POSTCOMPACT_TEXT=text
 //!                            — `_PostCompact` returns this (default: "")
+//!   FAKE_MCP_SHELL_TOOL=1    — expose a tool whose bare name is `shell`
+//!                              (registered as `<server>__shell`), taking a
+//!                              `command` string. Lets a test drive the
+//!                              reply guard's recognition of a real,
+//!                              registered shell tool.
 
 use std::io::{BufRead, Write};
 
@@ -76,6 +81,7 @@ fn make_tools(
     desc: &str,
     include_stop_hook: bool,
     include_post_compact_hook: bool,
+    include_shell_tool: bool,
 ) -> Vec<Value> {
     let mut tools: Vec<Value> = (0..count)
         .map(|i| {
@@ -100,6 +106,17 @@ fn make_tools(
             "inputSchema": { "type": "object", "properties": {} },
         }));
     }
+    if include_shell_tool {
+        tools.push(json!({
+            "name": "shell",
+            "description": "run a shell command",
+            "inputSchema": {
+                "type": "object",
+                "properties": { "command": { "type": "string" } },
+                "required": ["command"],
+            },
+        }));
+    }
     tools
 }
 
@@ -136,6 +153,7 @@ fn main() {
     let stop_count_limit: usize = env_usize("FAKE_MCP_STOP_COUNT", usize::MAX);
     let mut stop_calls_seen: usize = 0;
     let post_compact_hook = env_flag("FAKE_MCP_POSTCOMPACT_HOOK");
+    let shell_tool = env_flag("FAKE_MCP_SHELL_TOOL");
     let post_compact_text = std::env::var("FAKE_MCP_POSTCOMPACT_TEXT").unwrap_or_default();
 
     // Use a channel-based stdin reader so notifications (which carry no id)
@@ -206,7 +224,13 @@ fn main() {
                 write_response(
                     id,
                     json!({
-                        "tools": make_tools(tool_count, &desc, stop_hook, post_compact_hook)
+                        "tools": make_tools(
+                            tool_count,
+                            &desc,
+                            stop_hook,
+                            post_compact_hook,
+                            shell_tool,
+                        )
                     }),
                 );
             }
diff --git a/crates/buzz-agent/tests/regressions.rs b/crates/buzz-agent/tests/regressions.rs
index 2e0b579c84..abb4f7b311 100644
--- a/crates/buzz-agent/tests/regressions.rs
+++ b/crates/buzz-agent/tests/regressions.rs
@@ -1819,3 +1819,465 @@ async fn cancel_sends_notifications_cancelled_to_any_mcp_server() {
     let _ = std::fs::remove_file(&call_received_marker);
     h.shutdown().await;
 }
+
+// ---------------------------------------------------------------------------
+// Reply guard (`BUZZ_AGENT_REQUIRE_REPLY`)
+//
+// The guard reminds the model to publish when a turn is about to end without
+// any recognized attempt to post to Buzz. It rides the existing `_Stop` gate
+// and shares its rejection budget, so most of these tests count LLM calls:
+// each reminder costs exactly one extra round.
+// ---------------------------------------------------------------------------
+
+/// Number of reply-guard reminders present in one captured LLM request.
+///
+/// A reminder is a tool-role message whose JSON body is attributed to the
+/// in-process guard (`server: "buzz-agent"`) at the `_Stop` hook point — the
+/// same lower-trust shape as real hook output.
+fn reply_nag_count(request: &Value) -> usize {
+    request["messages"]
+        .as_array()
+        .map(|msgs| {
+            msgs.iter()
+                .filter(|m| {
+                    m["role"] == "tool"
+                        && serde_json::from_str::<Value>(m["content"].as_str().unwrap_or(""))
+                            .map(|p| p["hook"] == "_Stop" && p["server"] == "buzz-agent")
+                            .unwrap_or(false)
+                })
+                .count()
+        })
+        .unwrap_or(0)
+}
+
+/// A publish-shaped call to a real registered shell tool.
+fn openai_shell_send(id: &str) -> Value {
+    openai_tool_call(
+        id,
+        "fake__shell",
+        json!({ "command": "buzz messages send --channel c --content hi" }),
+    )
+}
+
+/// Run one prompt to completion, answering any permission requests, and
+/// return the final response.
+async fn prompt_to_completion(h: &mut Harness, sid: &str) -> Value {
+    let p = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"go"}]}),
+        )
+        .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!(p) {
+            return v;
+        }
+    }
+}
+
+/// Default off: a silent turn ends on the first end_turn with no extra round.
+/// This is the invariant that keeps the feature free for everyone who hasn't
+/// opted in.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_off_by_default() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn(&llm.url).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "guard must be inert when unset, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// `BUZZ_AGENT_REQUIRE_REPLY=0` is off too — the toggle is numeric, so a
+/// literal `0` must not read as "set, therefore on".
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_explicit_zero_is_off() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "0")]).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "REQUIRE_REPLY=0 must behave as off, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// Opted in and silent: exactly two reminders, then the turn is allowed to
+/// end. The guard is advisory — it must never trap a turn.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_nags_twice_then_lets_the_turn_end() {
+    // Budget defaults to 3, so the cap that stops the loop here is
+    // MAX_REPLY_NAGS = 2, not the rejection budget.
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("silent-3"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "1")]).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "expected 2 reminders then end_turn (3 LLM calls), got {}",
+        captured.len()
+    );
+    assert_eq!(
+        reply_nag_count(&captured[0]),
+        0,
+        "reminder before any end_turn"
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    assert_eq!(reply_nag_count(&captured[2]), 2);
+
+    // The reminder must name the command it wants and license silence, so it
+    // cannot fight the base prompt's "silence is usually correct".
+    let msgs = captured[2]["messages"].as_array().unwrap();
+    let nag = msgs
+        .iter()
+        .filter_map(|m| serde_json::from_str::<Value>(m["content"].as_str().unwrap_or("")).ok())
+        .find(|p| p["server"] == "buzz-agent")
+        .expect("reminder body");
+    let text = nag["text"].as_str().unwrap_or("");
+    assert!(
+        text.contains("buzz messages send"),
+        "reminder should name the command: {text}"
+    );
+    assert!(
+        text.contains("silence is genuinely correct"),
+        "reminder must license silence: {text}"
+    );
+    h.shutdown().await;
+}
+
+/// A real publish attempt through a registered shell tool satisfies the guard:
+/// no reminder, no extra round.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_satisfied_by_registered_shell_send() {
+    let llm = spawn_capturing_llm(vec![
+        openai_shell_send("tc1"),
+        openai_text("posted"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "1")]).await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[("FAKE_MCP_TOOL_COUNT", "1"), ("FAKE_MCP_SHELL_TOOL", "1")],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        2,
+        "a recognized send must not be nagged, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 0);
+    h.shutdown().await;
+}
+
+/// A publish-shaped call to a shell tool that is *not registered* never runs —
+/// preflight rejects it — so it must not disarm the guard. This is what the
+/// `has`/`is_hook` checks in the predicate buy.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_ignores_unregistered_shell_tool() {
+    // FAKE_MCP_SHELL_TOOL is absent, so `fake__shell` is a hallucination.
+    let llm = spawn_capturing_llm(vec![
+        openai_shell_send("tc1"),
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(&mut h, &[("FAKE_MCP_TOOL_COUNT", "1")]).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "expected the hallucinated call to still be nagged, got {} LLM calls",
+        captured.len()
+    );
+    let msgs = captured[1]["messages"].as_array().unwrap();
+    assert!(
+        msgs.iter()
+            .any(|m| m["role"] == "tool"
+                && m["content"].as_str().unwrap_or("").contains("unknown tool")),
+        "expected preflight to reject the call: {msgs:?}"
+    );
+    assert_eq!(reply_nag_count(&captured[2]), 1);
+    h.shutdown().await;
+}
+
+/// A publish-shaped call discarded by the per-turn tool-call cap never runs,
+/// so it must not suppress the reminder either. Pins the check's placement
+/// after `calls.truncate(MAX_TOOL_CALLS_PER_TURN)`.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_ignores_calls_lost_to_the_turn_cap() {
+    // 64 filler calls (the cap) followed by the publish attempt, which is
+    // therefore truncated away. The shell tool *is* registered here, so only
+    // the placement — not tool identity — can explain the reminder.
+    let mut calls: Vec<Value> = (0..64)
+        .map(|i| {
+            json!({
+                "id": format!("c{i}"),
+                "type": "function",
+                "function": { "name": "fake__tool_0", "arguments": "{}" },
+            })
+        })
+        .collect();
+    calls.push(json!({
+        "id": "c-send",
+        "type": "function",
+        "function": {
+            "name": "fake__shell",
+            "arguments": json!({ "command": "buzz messages send --channel c --content hi" })
+                .to_string(),
+        },
+    }));
+    let truncated_send = json!({
+        "id": "cc-trunc", "object": "chat.completion", "model": "fake-model",
+        "choices": [{
+            "index": 0,
+            "message": { "role": "assistant", "content": null, "tool_calls": calls },
+            "finish_reason": "tool_calls",
+        }],
+    });
+    let llm = spawn_capturing_llm(vec![
+        truncated_send,
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[("FAKE_MCP_TOOL_COUNT", "1"), ("FAKE_MCP_SHELL_TOOL", "1")],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "a truncated send must still be nagged, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[2]), 1);
+    h.shutdown().await;
+}
+
+/// The shared `_Stop` rejection budget is the outer cap: at 1 the guard gets
+/// one reminder instead of two. Documented degradation, not a bug.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_bounded_by_stop_rejection_budget() {
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        2,
+        "budget 1 must allow exactly one reminder, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    h.shutdown().await;
+}
+
+/// Budget 0 disables every objection at the gate, including this one.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_off_when_stop_budget_is_zero() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "budget 0 must disable the guard, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// The two axes are independent inside one shared budget: a round carrying
+/// both a `_Stop` hook objection and a reminder costs one rejection and
+/// delivers both texts, and once the reminders are spent the hook objection
+/// continues alone.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_combines_with_stop_hook_objection() {
+    // The hook objects on its first 3 calls, then clears. Reminders stop
+    // after 2, so round 3 must carry the hook text and no new reminder.
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("silent-3"),
+        openai_text("silent-4"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("MCP_HOOK_SERVERS", "fake"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "10"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[
+            ("FAKE_MCP_TOOL_COUNT", "1"),
+            ("FAKE_MCP_STOP_HOOK", "1"),
+            ("FAKE_MCP_STOP_TEXT", "you have open todos"),
+            ("FAKE_MCP_STOP_COUNT", "3"),
+        ],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        4,
+        "expected 3 objecting rounds then a clear end, got {}",
+        captured.len()
+    );
+
+    let hook_objections = |req: &Value| -> usize {
+        req["messages"]
+            .as_array()
+            .map(|msgs| {
+                msgs.iter()
+                    .filter(|m| {
+                        m["content"]
+                            .as_str()
+                            .unwrap_or("")
+                            .contains("you have open todos")
+                    })
+                    .count()
+            })
+            .unwrap_or(0)
+    };
+
+    // Round 2 carries one of each — a single rejection bought both texts.
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    assert_eq!(hook_objections(&captured[1]), 1);
+    // Round 4: the hook objected three times, the guard only twice.
+    assert_eq!(reply_nag_count(&captured[3]), 2);
+    assert_eq!(hook_objections(&captured[3]), 3);
+    h.shutdown().await;
+}
+
+/// An unparseable toggle is a startup error, not a silent default. `parse_env`
+/// is generic over `FromStr`, so this also pins the numeric type: a `bool`
+/// field would have rejected the documented `1`.
+#[test]
+fn reply_guard_rejects_unparseable_toggle() {
+    let out = std::process::Command::new(env!("CARGO_BIN_EXE_buzz-agent"))
+        .env("BUZZ_AGENT_PROVIDER", "openai")
+        .env("OPENAI_COMPAT_API_KEY", "test")
+        .env("OPENAI_COMPAT_MODEL", "fake-model")
+        .env("BUZZ_AGENT_REQUIRE_REPLY", "true")
+        .stdin(Stdio::null())
+        .output()
+        .expect("run buzz-agent");
+    assert!(
+        !out.status.success(),
+        "expected a config error exit, got {:?}",
+        out.status
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("BUZZ_AGENT_REQUIRE_REPLY"),
+        "expected the offending key in the error, got: {stderr}"
+    );
+}
diff --git a/crates/buzz-cli/README.md b/crates/buzz-cli/README.md
index a2dcdce6d2..6fd214925c 100644
--- a/crates/buzz-cli/README.md
+++ b/crates/buzz-cli/README.md
@@ -10,16 +10,26 @@ cargo install --path crates/buzz-cli
 
 ## Authentication
 
-| Env Var | Mode | Use Case |
-|---------|------|----------|
-| `BUZZ_PRIVATE_KEY` | NIP-98 Schnorr signature | Agents with a keypair |
+| Source | Mode | Use Case |
+|--------|------|----------|
+| `BUZZ_PRIVATE_KEY` | NIP-98 Schnorr signature | Agents with a keypair (preferred) |
+| `--private-key-file PATH` | same | Secrets on disk (mode `0600`) |
+| `--private-key-stdin` | same | Piping from a password manager |
+| `--private-key` | same | **Deprecated** — leaks into shell history and `ps` |
 
 ```bash
 # Private key identity (NIP-98 signed requests)
 export BUZZ_PRIVATE_KEY="nsec1..."
 buzz channels list
+
+# Or keep the secret out of argv / the environment of child processes:
+buzz --private-key-file ~/.config/buzz/nsec channels list
+printf '%s' "$NSEC" | buzz --private-key-stdin channels list
 ```
 
+Do not pass `--private-key nsec1...` on the command line — see
+[block/buzz#4032](https://github.com/block/buzz/issues/4032).
+
 ## Usage
 
 All output is JSON on stdout. Errors are JSON on stderr. Exit codes: 0=ok, 1=user error, 2=network, 3=auth, 4=other, 5=write conflict.
diff --git a/crates/buzz-cli/TESTING.md b/crates/buzz-cli/TESTING.md
index 77234b7faa..71503c61cc 100644
--- a/crates/buzz-cli/TESTING.md
+++ b/crates/buzz-cli/TESTING.md
@@ -76,6 +76,7 @@ Export:
 ```bash
 export BUZZ_RELAY_URL="http://localhost:3000"
 export BUZZ_PRIVATE_KEY="nsec1..."   # from the mint output
+# Prefer file/stdin in shared shells: buzz --private-key-file /tmp/nsec …
 ```
 
 ### Scope reference
diff --git a/crates/buzz-cli/src/commands/doctor.rs b/crates/buzz-cli/src/commands/doctor.rs
new file mode 100644
index 0000000000..df8cda75f8
--- /dev/null
+++ b/crates/buzz-cli/src/commands/doctor.rs
@@ -0,0 +1,645 @@
+//! `buzz doctor` — non-mutating preflight diagnostics.
+//!
+//! Unlike every other subcommand, doctor intentionally does NOT require
+//! credentials: missing or malformed config must surface as a check result
+//! (status `error`) rather than an argument-time usage failure. The command
+//! never publishes events and never mutates local or remote state;
+//! `--offline` runs only local checks and marks remote probes as skipped.
+//!
+//! Output is structured JSON on stdout:
+//!
+//! ```json
+//! {"status":"warning","checks":[{"id":"identity","status":"ok","message":"..."}]}
+//! ```
+//!
+//! Exit behavior distinguishes a failed required check from warnings:
+//! `0` when every applicable check is `ok` (warnings allowed),
+//! `3` when any check is `error` and at least one error is auth/identity,
+//! `2` when any check is `error` and all errors are relay/network, and
+//! `1` for any other failure mix.  Skipped checks never affect the exit
+//! code.  The human-readable `status` field is `ok`, `warning`, or `error`
+//! mirroring the worst check outcome.
+
+use serde::Serialize;
+use serde_json::json;
+
+use crate::client::{normalize_relay_url, BuzzClient};
+use crate::error::CliError;
+use crate::private_key::{self, PrivateKeyInputs};
+
+/// Status of a single doctor check.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "lowercase")]
+enum Status {
+    Ok,
+    Warning,
+    Error,
+    Skipped,
+}
+
+fn identity_from_inputs(inputs: PrivateKeyInputs) -> Result<nostr::Keys, CliError> {
+    let key = private_key::resolve_private_key(inputs)?;
+    nostr::Keys::parse(&key).map_err(|e| CliError::Key(format!("invalid private key: {e}")))
+}
+
+impl Status {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Warning => "warning",
+            Self::Error => "error",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+/// Serialisable form of one check for the JSON output.
+#[derive(Debug, Serialize)]
+struct Check {
+    id: &'static str,
+    status: Status,
+    message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    remediation: Option<String>,
+}
+
+impl Check {
+    fn ok(id: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            id,
+            status: Status::Ok,
+            message: message.into(),
+            remediation: None,
+        }
+    }
+
+    fn warning(id: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            id,
+            status: Status::Warning,
+            message: message.into(),
+            remediation: None,
+        }
+    }
+
+    fn error(id: &'static str, message: impl Into<String>, remediation: Option<&str>) -> Self {
+        Self {
+            id,
+            status: Status::Error,
+            message: message.into(),
+            remediation: remediation.map(str::to_string),
+        }
+    }
+
+    fn skipped(id: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            id,
+            status: Status::Skipped,
+            message: message.into(),
+            remediation: None,
+        }
+    }
+}
+
+/// Entry point invoked from `crate::run` before the credential gate.
+///
+/// The doctor never returns `Err` for missing configuration; it reports
+/// the problem as a check and exits non-zero via `run_from_args`.
+pub async fn run(
+    cli: &crate::Cli,
+    offline: bool,
+    private_key_from_argv: bool,
+) -> Result<(), CliError> {
+    let mut checks: Vec<Check> = Vec::new();
+
+    // ---- local checks ----
+
+    // `cli.relay` itself is a free-form string; canonicalize before probing
+    // so the rest of the doctor matches the rest of the CLI.
+    let relay_url_raw = cli.relay.clone();
+    let relay_url = normalize_relay_url(&relay_url_raw);
+    if relay_url.is_empty() {
+        checks.push(Check::error(
+            "relay_url",
+            "relay URL is empty",
+            Some("Set BUZZ_RELAY_URL or pass --relay"),
+        ));
+    } else if !(relay_url.starts_with("http://") || relay_url.starts_with("https://")) {
+        checks.push(Check::error(
+            "relay_url",
+            format!(
+                "relay URL {:?} is not an http(s) URL after canonicalization",
+                relay_url
+            ),
+            Some("Use http:// or https://; ws:// and wss:// are rewritten automatically"),
+        ));
+    } else {
+        checks.push(Check::ok(
+            "relay_url",
+            format!("relay URL canonicalized to {}", relay_url),
+        ));
+    }
+
+    // identity check: parse the private key. Never echo the material.
+    let keys: Option<nostr::Keys> = match identity_from_inputs(PrivateKeyInputs {
+        private_key: cli.private_key.clone(),
+        private_key_file: cli.private_key_file.clone(),
+        private_key_stdin: cli.private_key_stdin,
+        private_key_from_argv,
+    }) {
+        Ok(k) => {
+            let pk = k.public_key().to_hex();
+            checks.push(Check::ok(
+                "identity",
+                format!("signing identity available: {pk}"),
+            ));
+            Some(k)
+        }
+        Err(e) => {
+            checks.push(Check::error(
+                "identity",
+                e.to_string(),
+                Some("Provide one private key via BUZZ_PRIVATE_KEY, --private-key-file, or --private-key-stdin"),
+            ));
+            None
+        }
+    };
+
+    // auth_tag check: parse only; never print the tag material.
+    let auth_tag: Option<nostr::Tag> = match cli.auth_tag.as_deref() {
+        None => {
+            checks.push(Check::ok(
+                "auth_tag",
+                "no BUZZ_AUTH_TAG set (optional; only required for delegated agents)",
+            ));
+            None
+        }
+        Some("") => {
+            checks.push(Check::ok(
+                "auth_tag",
+                "BUZZ_AUTH_TAG is empty (treated as unset)",
+            ));
+            None
+        }
+        Some(raw) => match buzz_sdk::nip_oa::parse_auth_tag(raw) {
+            Ok(tag) => match &keys {
+                Some(k) => match buzz_sdk::nip_oa::verify_auth_tag(raw, &k.public_key()) {
+                    Ok(_) => {
+                        checks.push(Check::ok(
+                            "auth_tag",
+                            "BUZZ_AUTH_TAG parsed and verified for this identity",
+                        ));
+                        Some(tag)
+                    }
+                    Err(e) => {
+                        checks.push(Check::error(
+                            "auth_tag",
+                            format!("BUZZ_AUTH_TAG failed verification: {e}"),
+                            Some("Re-issue the auth tag for the current identity"),
+                        ));
+                        None
+                    }
+                },
+                None => {
+                    // Cannot verify without an identity; report as warning.
+                    checks.push(Check::warning(
+                        "auth_tag",
+                        "BUZZ_AUTH_TAG present but cannot be verified without a valid identity",
+                    ));
+                    Some(tag)
+                }
+            },
+            Err(e) => {
+                checks.push(Check::error(
+                    "auth_tag",
+                    format!("BUZZ_AUTH_TAG is malformed: {e}"),
+                    Some("Re-export the auth tag JSON from the owning desktop"),
+                ));
+                None
+            }
+        },
+    };
+
+    // version check: always available, no I/O.
+    checks.push(Check::ok(
+        "version",
+        format!("buzz-cli {}", env!("CARGO_PKG_VERSION")),
+    ));
+
+    // ---- remote checks ----
+
+    if offline {
+        checks.push(Check::skipped("relay_reachable", "skipped (--offline)"));
+        checks.push(Check::skipped("nip11", "skipped (--offline)"));
+        checks.push(Check::skipped("auth_read", "skipped (--offline)"));
+        checks.push(Check::skipped("membership", "skipped (--offline)"));
+    } else {
+        run_remote_checks(
+            &relay_url,
+            keys.as_ref(),
+            auth_tag.as_ref(),
+            cli,
+            &mut checks,
+        )
+        .await;
+    }
+
+    // ---- output ----
+    emit_and_exit(&checks)
+}
+
+async fn run_remote_checks(
+    relay_url: &str,
+    keys: Option<&nostr::Keys>,
+    auth_tag: Option<&nostr::Tag>,
+    cli: &crate::Cli,
+    checks: &mut Vec<Check>,
+) {
+    // Build a client only when we have a parseable identity; local checks
+    // already reported the identity problem, so the remote probes degrade
+    // to skipped/errored rather than re-diagnosing it.
+    let authed_client: Option<BuzzClient> = match keys {
+        Some(k) => match BuzzClient::new(
+            relay_url.to_string(),
+            k.clone(),
+            auth_tag.cloned(),
+            cli.auth_tag.clone(),
+        ) {
+            Ok(c) => Some(c),
+            Err(e) => {
+                checks.push(Check::error(
+                    "relay_reachable",
+                    format!("failed to build HTTP client: {e}"),
+                    None,
+                ));
+                None
+            }
+        },
+        None => None,
+    };
+
+    // Unauthenticated reachability probe: try the public NIP-11 document.
+    // We do this with a bare reqwest client so that doctor works even when
+    // the identity is invalid — reachability is independent of auth.
+    // Track the outcome so we can avoid re-emitting the same error when
+    // the authed probe below also fails.
+    let relay_reachable = match probe_reachability(relay_url).await {
+        Ok(()) => {
+            checks.push(Check::ok(
+                "relay_reachable",
+                format!("relay at {relay_url} responded to an unauthenticated probe"),
+            ));
+            true
+        }
+        Err(msg) => {
+            checks.push(Check::error(
+                "relay_reachable",
+                msg,
+                Some("Check BUZZ_RELAY_URL, DNS, and network connectivity"),
+            ));
+            false
+        }
+    };
+
+    // NIP-11 probe. Public per spec; relay may also accept the metadata
+    // unauthenticated.  The same probe result feeds both the reachability
+    // message above (already emitted) and the parsed metadata here.
+    match fetch_nip11(relay_url).await {
+        Ok(doc) => {
+            let name = doc
+                .get("name")
+                .and_then(|v| v.as_str())
+                .unwrap_or("<unnamed>");
+            let supported = doc
+                .get("supported_nips")
+                .and_then(|v| v.as_array())
+                .map(|arr| arr.len())
+                .unwrap_or(0);
+            checks.push(Check::ok(
+                "nip11",
+                format!("NIP-11 document parsed: {name} (advertises {supported} NIPs)"),
+            ));
+        }
+        Err(msg) => {
+            checks.push(Check::error(
+                "nip11",
+                msg,
+                Some("Verify the relay exposes / (or /info) as application/nostr+json"),
+            ));
+        }
+    }
+
+    // Authenticated read probe + membership probe. Both require an identity;
+    // skip them cleanly if we don't have one rather than re-diagnosing.
+    match authed_client {
+        None => {
+            checks.push(Check::skipped(
+                "auth_read",
+                "skipped (no valid signing identity)",
+            ));
+            checks.push(Check::skipped(
+                "membership",
+                "skipped (no valid signing identity)",
+            ));
+        }
+        Some(client) => {
+            // auth_read: a small, bounded, read-only filter.  Using
+            // kinds:[39002] (#p=self) doubles as the membership probe.
+            let my_pk = client.keys().public_key().to_hex();
+            let filter = json!({
+                "kinds": [39002],
+                "#p": [my_pk],
+            });
+            match client.query_paginated(filter, 1).await {
+                Ok(events) => {
+                    checks.push(Check::ok("auth_read", "authenticated read succeeded"));
+                    // membership: any kind:39002 with #p=self means we're
+                    // a member of at least one channel.
+                    if events.is_empty() {
+                        checks.push(Check::warning(
+                            "membership",
+                            "identity is not a member of any channel visible to this relay",
+                        ));
+                    } else {
+                        checks.push(Check::ok(
+                            "membership",
+                            format!(
+                                "identity has membership in at least one channel (saw {} event(s))",
+                                events.len()
+                            ),
+                        ));
+                    }
+                }
+                // True auth rejection — either an explicit Auth variant or a
+                // relay 401/403 — classifies as auth (exit 3).
+                Err(e @ CliError::Auth(_))
+                | Err(
+                    e @ CliError::Relay {
+                        status: 401 | 403, ..
+                    },
+                ) => {
+                    checks.push(Check::error(
+                        "auth_read",
+                        format!("relay rejected authentication: {e}"),
+                        Some("Verify BUZZ_PRIVATE_KEY and BUZZ_AUTH_TAG"),
+                    ));
+                    checks.push(Check::skipped(
+                        "membership",
+                        "skipped (authentication failed)",
+                    ));
+                }
+                // Anything else — network/transport or non-401 relay — means
+                // the relay couldn't be queried authoritatively.  If the
+                // unauthenticated reachability probe already failed, the
+                // check list already carries that signal; don't double-report.
+                // Otherwise, this path means the relay was reachable publicly
+                // but rejected our authed call network-side: report as a
+                // relay-side failure (exit 2), NOT as an auth failure.
+                Err(e) => {
+                    if relay_reachable {
+                        checks.push(Check::error(
+                            "relay_reachable",
+                            format!("authenticated read failed: {e}"),
+                            Some("Check relay availability, DNS, and network connectivity"),
+                        ));
+                    }
+                    checks.push(Check::skipped(
+                        "auth_read",
+                        "skipped (relay unreachable for authenticated read)",
+                    ));
+                    checks.push(Check::skipped(
+                        "membership",
+                        "skipped (relay unreachable for authenticated read)",
+                    ));
+                }
+            }
+        }
+    }
+}
+
+/// Cheap reachability probe: GET `/` with the NIP-11 accept header.  We
+/// don't care about the body here; only that something HTTP 2xx came back.
+async fn probe_reachability(relay_url: &str) -> Result<(), String> {
+    let http = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(10))
+        .connect_timeout(std::time::Duration::from_secs(5))
+        .build()
+        .map_err(|e| format!("failed to build HTTP client: {e}"))?;
+    let resp = http
+        .get(relay_url)
+        .header("Accept", "application/nostr+json")
+        .send()
+        .await
+        .map_err(|e| format!("relay probe failed: {e}"))?;
+    if resp.status().is_success() {
+        Ok(())
+    } else {
+        Err(format!("relay returned HTTP {}", resp.status()))
+    }
+}
+
+/// Fetch and parse the relay's NIP-11 information document.
+///
+/// We reuse `get_public` so redirect, timeout, and TLS behavior matches
+/// the rest of the CLI.
+async fn fetch_nip11(relay_url: &str) -> Result<serde_json::Value, String> {
+    let http = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(10))
+        .connect_timeout(std::time::Duration::from_secs(5))
+        .build()
+        .map_err(|e| format!("failed to build HTTP client: {e}"))?;
+    // NIP-11 specifies GET on the relay URL itself with the metadata
+    // accept header.  The `get_public` helper on a constructed client does
+    // exactly this; we inline the call here so doctor does not need an
+    // authed `BuzzClient`.
+    let resp = http
+        .get(relay_url)
+        .header("Accept", "application/nostr+json")
+        .send()
+        .await
+        .map_err(|e| format!("NIP-11 probe failed: {e}"))?;
+    let status = resp.status();
+    let body = resp
+        .text()
+        .await
+        .map_err(|e| format!("failed to read NIP-11 body: {e}"))?;
+    if !status.is_success() {
+        return Err(format!("relay returned HTTP {status}"));
+    }
+    serde_json::from_str(&body).map_err(|e| format!("NIP-11 document was not valid JSON: {e}"))
+}
+
+/// Aggregate after running all checks and return the process-level
+/// `CliError` (or `Ok` for success).
+///
+/// Mapping (exposed for tests via `decide_outcome`):
+/// - any `error` check mentioning `identity` or `auth_tag` or `auth_read` => `CliError::Auth` (exit 3)
+/// - any other `error` check                                            => `CliError::Relay` (exit 2)
+/// - no `error` but any `warning`                                       => `Ok(())` (exit 0)
+/// - all `ok` / `skipped`                                               => `Ok(())` (exit 0)
+fn emit_and_exit(checks: &[Check]) -> Result<(), CliError> {
+    let overall = if checks.iter().any(|c| c.status == Status::Error) {
+        "error"
+    } else if checks.iter().any(|c| c.status == Status::Warning) {
+        "warning"
+    } else {
+        "ok"
+    };
+
+    let doc = json!({
+        "status": overall,
+        "checks": checks.iter().map(|c| json!({
+            "id": c.id,
+            "status": c.status.as_str(),
+            "message": c.message,
+            "remediation": c.remediation,
+        })).collect::<Vec<_>>(),
+    });
+    println!("{doc}");
+
+    if overall == "ok" || overall == "warning" {
+        return Ok(());
+    }
+
+    // Distinguish credential-shaped failures from transport failures.
+    let mut has_auth_error = false;
+    let mut first_other_error: Option<&Check> = None;
+    for c in checks {
+        if c.status != Status::Error {
+            continue;
+        }
+        match c.id {
+            "identity" | "auth_tag" | "auth_read" => has_auth_error = true,
+            _ => {
+                if first_other_error.is_none() {
+                    first_other_error = Some(c);
+                }
+            }
+        }
+    }
+
+    if has_auth_error {
+        return Err(CliError::Auth(
+            "one or more doctor checks failed (see JSON output for details)".into(),
+        ));
+    }
+    if let Some(c) = first_other_error {
+        return Err(CliError::Relay {
+            status: 0,
+            body: format!("doctor check {} failed: {}", c.id, c.message),
+        });
+    }
+    Err(CliError::Other("one or more doctor checks failed".into()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::exit_code;
+    use std::io::Write;
+
+    fn check_with(id: &'static str, status: Status) -> Check {
+        Check {
+            id,
+            status,
+            message: String::new(),
+            remediation: None,
+        }
+    }
+
+    #[test]
+    fn identity_accepts_private_key_file() {
+        let mut file = tempfile::NamedTempFile::new().expect("temporary key file");
+        writeln!(file, "{}", "1".repeat(64)).expect("write key");
+
+        assert!(identity_from_inputs(crate::private_key::PrivateKeyInputs {
+            private_key_file: Some(file.path().to_path_buf()),
+            ..Default::default()
+        })
+        .is_ok());
+    }
+
+    #[test]
+    fn all_ok_emits_status_ok_and_exit_zero() {
+        let checks = vec![
+            check_with("relay_url", Status::Ok),
+            check_with("identity", Status::Ok),
+        ];
+        assert!(emit_and_exit(&checks).is_ok());
+    }
+
+    #[test]
+    fn warning_emits_warning_and_exit_zero() {
+        let checks = vec![
+            check_with("relay_url", Status::Ok),
+            check_with("membership", Status::Warning),
+        ];
+        assert!(emit_and_exit(&checks).is_ok());
+    }
+
+    #[test]
+    fn error_on_identity_maps_to_auth() {
+        let checks = vec![check_with("identity", Status::Error)];
+        let err = emit_and_exit(&checks).unwrap_err();
+        assert!(matches!(err, CliError::Auth(_)));
+        assert_eq!(exit_code(&err), 3);
+    }
+
+    #[test]
+    fn error_on_auth_read_maps_to_auth() {
+        let checks = vec![check_with("auth_read", Status::Error)];
+        let err = emit_and_exit(&checks).unwrap_err();
+        assert!(matches!(err, CliError::Auth(_)));
+        assert_eq!(exit_code(&err), 3);
+    }
+
+    #[test]
+    fn error_on_relay_reachable_maps_to_relay_exit_two() {
+        let checks = vec![check_with("relay_reachable", Status::Error)];
+        let err = emit_and_exit(&checks).unwrap_err();
+        assert!(matches!(err, CliError::Relay { status: 0, .. }));
+        assert_eq!(exit_code(&err), 2);
+    }
+
+    #[test]
+    fn error_mixed_auth_wins_over_relay() {
+        let checks = vec![
+            check_with("relay_reachable", Status::Error),
+            check_with("identity", Status::Error),
+        ];
+        let err = emit_and_exit(&checks).unwrap_err();
+        assert!(matches!(err, CliError::Auth(_)));
+    }
+
+    #[test]
+    fn skipped_checks_do_not_affect_outcome() {
+        let checks = vec![
+            check_with("relay_url", Status::Ok),
+            check_with("identity", Status::Ok),
+            check_with("auth_read", Status::Skipped),
+            check_with("membership", Status::Skipped),
+        ];
+        assert!(emit_and_exit(&checks).is_ok());
+    }
+
+    #[test]
+    fn json_shape_has_status_and_checks_array() {
+        // Serialise directly to avoid printing; validate the shape line by
+        // line rather than relying on `println!` output.
+        let checks = [check_with("identity", Status::Ok)];
+        let doc = serde_json::json!({
+            "status": "ok",
+            "checks": checks.iter().map(|c| serde_json::json!({
+                "id": c.id,
+                "status": c.status.as_str(),
+                "message": c.message,
+                "remediation": c.remediation,
+            })).collect::<Vec<_>>(),
+        });
+        assert_eq!(doc["status"].as_str(), Some("ok"));
+        let arr = doc["checks"].as_array().expect("checks is an array");
+        assert_eq!(arr.len(), 1);
+        assert_eq!(arr[0]["id"].as_str(), Some("identity"));
+        assert_eq!(arr[0]["status"].as_str(), Some("ok"));
+    }
+}
diff --git a/crates/buzz-cli/src/commands/mod.rs b/crates/buzz-cli/src/commands/mod.rs
index 8691590636..c1adddd4a2 100644
--- a/crates/buzz-cli/src/commands/mod.rs
+++ b/crates/buzz-cli/src/commands/mod.rs
@@ -2,6 +2,7 @@ pub mod agents;
 pub mod channel_templates;
 pub mod channels;
 pub mod dms;
+pub mod doctor;
 pub mod emoji;
 pub mod feed;
 pub mod issues;
diff --git a/crates/buzz-cli/src/lib.rs b/crates/buzz-cli/src/lib.rs
index 0726406d29..3c1285f372 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 private_key;
 mod validate;
 
 use clap::{Parser, Subcommand};
@@ -37,7 +38,11 @@ where
     // double-install returns Err and is harmless.
     let _ = rustls::crypto::ring::default_provider().install_default();
 
-    let cli = match Cli::try_parse_from(args) {
+    let argv: Vec<std::ffi::OsString> = args.into_iter().map(Into::into).collect();
+    let private_key_from_argv =
+        private_key::private_key_flag_on_argv(argv.iter().filter_map(|s| s.to_str()));
+
+    let cli = match Cli::try_parse_from(argv) {
         Ok(cli) => cli,
         Err(e) => {
             if e.use_stderr() {
@@ -50,7 +55,7 @@ where
             }
         }
     };
-    match run(cli).await {
+    match run(cli, private_key_from_argv).await {
         Ok(()) => 0,
         Err(e) => {
             error::print_error(&e);
@@ -68,9 +73,13 @@ Buzz CLI — interact with a Buzz relay
 
 Configuration (flags override env vars):
   BUZZ_RELAY_URL     Relay base URL        [default: http://localhost:3000]
-  BUZZ_PRIVATE_KEY   Nostr private key (hex or nsec)  [required]
+  BUZZ_PRIVATE_KEY   Nostr private key (hex or nsec)  [preferred over --private-key]
   BUZZ_AUTH_TAG      NIP-OA auth tag JSON  [optional]
 
+Identity secrets: prefer BUZZ_PRIVATE_KEY, --private-key-file, or
+--private-key-stdin. Passing --private-key on argv is deprecated (shell
+history / process listings).
+
 The 'pack' subcommand runs locally and does not require a relay connection.
 
 Exit codes: 0=ok  1=bad input  2=relay/network error  3=auth error  4=other  5=write conflict
@@ -81,10 +90,20 @@ struct Cli {
     #[arg(long, env = "BUZZ_RELAY_URL", default_value = "http://localhost:3000")]
     relay: String,
 
-    /// Nostr private key (hex or nsec). This is the CLI's identity.
+    /// Nostr private key (hex or nsec). Prefer `BUZZ_PRIVATE_KEY`,
+    /// `--private-key-file`, or `--private-key-stdin` — passing the secret on
+    /// argv leaks into shell history and `ps` (deprecated).
     #[arg(long, env = "BUZZ_PRIVATE_KEY", hide_env_values = true)]
     private_key: Option<String>,
 
+    /// Read the Nostr private key from a file (mode 0600 recommended).
+    #[arg(long, value_name = "PATH")]
+    private_key_file: Option<std::path::PathBuf>,
+
+    /// Read the Nostr private key from stdin (trim surrounding whitespace).
+    #[arg(long, default_value_t = false)]
+    private_key_stdin: bool,
+
     /// NIP-OA auth tag JSON (owner attestation). Injected into every signed event.
     #[arg(long, env = "BUZZ_AUTH_TAG", hide_env_values = true)]
     auth_tag: Option<String>,
@@ -236,6 +255,12 @@ enum Cmd {
     /// Community moderation — reports queue, bans, timeouts, audit trail
     #[command(subcommand)]
     Moderation(ModerationCmd),
+    /// Non-mutating preflight diagnostics for the CLI environment and relay
+    Doctor {
+        /// Run only local checks; mark remote checks as skipped
+        #[arg(long, default_value_t = false)]
+        offline: bool,
+    },
 }
 
 #[derive(Clone, Copy, clap::ValueEnum)]
@@ -1768,7 +1793,42 @@ pub enum ModerationCmd {
     },
 }
 
-async fn run(cli: Cli) -> Result<(), CliError> {
+/// 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, private_key_from_argv: bool) -> Result<(), CliError> {
     let relay_url = client::normalize_relay_url(&cli.relay);
 
     // Pack commands are local-only — no relay connection needed.
@@ -1779,26 +1839,47 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         };
     }
 
+    // Doctor runs its own credential/relay handling so that missing or
+    // malformed config surfaces as check results instead of argument-error
+    // exits.
+    if let Cmd::Doctor { offline } = cli.command {
+        return commands::doctor::run(&cli, offline, private_key_from_argv).await;
+    }
+
     // Auth: private key is required for all relay operations.
     // The keypair IS the identity — no tokens, no other auth.
-    let private_key_str = cli.private_key.ok_or_else(|| {
-        CliError::Auth("BUZZ_PRIVATE_KEY is required (use --private-key or set env var)".into())
+    let private_key_str = private_key::resolve_private_key(private_key::PrivateKeyInputs {
+        private_key: cli.private_key,
+        private_key_file: cli.private_key_file,
+        private_key_stdin: cli.private_key_stdin,
+        private_key_from_argv,
     })?;
     let keys = Keys::parse(&private_key_str)
         .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),
     };
@@ -1827,6 +1908,7 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         Cmd::Mem(sub) => commands::mem::dispatch(sub, &client).await,
         Cmd::Moderation(sub) => commands::moderation::dispatch(sub, &client, &cli.format).await,
         Cmd::Pack(_) => unreachable!("handled above"),
+        Cmd::Doctor { .. } => unreachable!("handled above"),
     }
 }
 
@@ -1835,6 +1917,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() {
@@ -1872,6 +1999,7 @@ mod tests {
             "canvas",
             "channels",
             "dms",
+            "doctor",
             "emoji",
             "feed",
             "issues",
diff --git a/crates/buzz-cli/src/private_key.rs b/crates/buzz-cli/src/private_key.rs
new file mode 100644
index 0000000000..2baa37470d
--- /dev/null
+++ b/crates/buzz-cli/src/private_key.rs
@@ -0,0 +1,184 @@
+//! Resolve the CLI identity secret without requiring it on argv.
+//!
+//! Prefer `BUZZ_PRIVATE_KEY`, `--private-key-file`, or `--private-key-stdin`.
+//! Bare `--private-key` remains accepted but warns: argv values land in shell
+//! history and process listings (see block/buzz#4032).
+
+use crate::error::CliError;
+use std::fs;
+use std::io::{self, Read};
+use std::path::Path;
+
+/// Sources that can supply the Nostr private key for relay commands.
+#[derive(Debug, Clone, Default)]
+pub struct PrivateKeyInputs {
+    /// Value from `--private-key` / `BUZZ_PRIVATE_KEY` (clap merges both).
+    pub private_key: Option<String>,
+    /// Path from `--private-key-file`.
+    pub private_key_file: Option<std::path::PathBuf>,
+    /// When true, read a single line/key from stdin (`--private-key-stdin`).
+    pub private_key_stdin: bool,
+    /// True when `--private-key` appeared on argv (not only via the env var).
+    pub private_key_from_argv: bool,
+}
+
+/// Resolve the private key string, applying preference order and deprecation.
+pub fn resolve_private_key(inputs: PrivateKeyInputs) -> Result<String, CliError> {
+    let mut sources = 0u8;
+    if inputs.private_key_file.is_some() {
+        sources += 1;
+    }
+    if inputs.private_key_stdin {
+        sources += 1;
+    }
+    if inputs.private_key.is_some() {
+        sources += 1;
+    }
+    if sources > 1 {
+        return Err(CliError::Usage(
+            "specify only one of --private-key-file, --private-key-stdin, or BUZZ_PRIVATE_KEY/--private-key"
+                .into(),
+        ));
+    }
+
+    if let Some(path) = inputs.private_key_file.as_deref() {
+        return read_private_key_file(path);
+    }
+
+    if inputs.private_key_stdin {
+        return read_private_key_stdin();
+    }
+
+    if let Some(key) = inputs.private_key {
+        if inputs.private_key_from_argv {
+            eprintln!(
+                "warning: --private-key puts the secret in shell history and process listings; \
+prefer BUZZ_PRIVATE_KEY, --private-key-file, or --private-key-stdin (see https://github.com/block/buzz/issues/4032)"
+            );
+        }
+        let trimmed = key.trim().to_owned();
+        if trimmed.is_empty() {
+            return Err(CliError::Auth(
+                "BUZZ_PRIVATE_KEY is empty (use --private-key-file, --private-key-stdin, or set env var)"
+                    .into(),
+            ));
+        }
+        return Ok(trimmed);
+    }
+
+    Err(CliError::Auth(
+        "BUZZ_PRIVATE_KEY is required (prefer --private-key-file / --private-key-stdin / env; \
+--private-key is deprecated)"
+            .into(),
+    ))
+}
+
+fn read_private_key_file(path: &Path) -> Result<String, CliError> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        if let Ok(meta) = fs::metadata(path) {
+            let mode = meta.permissions().mode() & 0o777;
+            if mode & 0o077 != 0 {
+                eprintln!(
+                    "warning: private key file {} is group/world-accessible (mode {:o}); prefer chmod 600",
+                    path.display(),
+                    mode
+                );
+            }
+        }
+    }
+
+    let contents = fs::read_to_string(path).map_err(|e| {
+        CliError::Auth(format!(
+            "failed to read --private-key-file {}: {e}",
+            path.display()
+        ))
+    })?;
+    let trimmed = contents.trim().to_owned();
+    if trimmed.is_empty() {
+        return Err(CliError::Auth(format!(
+            "--private-key-file {} is empty",
+            path.display()
+        )));
+    }
+    Ok(trimmed)
+}
+
+fn read_private_key_stdin() -> Result<String, CliError> {
+    let mut buf = String::new();
+    io::stdin()
+        .read_to_string(&mut buf)
+        .map_err(|e| CliError::Auth(format!("failed to read --private-key-stdin: {e}")))?;
+    let trimmed = buf.trim().to_owned();
+    if trimmed.is_empty() {
+        return Err(CliError::Auth(
+            "--private-key-stdin produced an empty key".into(),
+        ));
+    }
+    Ok(trimmed)
+}
+
+/// Detect whether `--private-key` was present on argv (vs env-only).
+pub fn private_key_flag_on_argv<I, S>(args: I) -> bool
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<str>,
+{
+    args.into_iter().any(|a| {
+        let a = a.as_ref();
+        a == "--private-key" || a.starts_with("--private-key=")
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::NamedTempFile;
+
+    #[test]
+    fn argv_detector_matches_flag_forms() {
+        assert!(private_key_flag_on_argv([
+            "buzz",
+            "--private-key",
+            "nsec1x"
+        ]));
+        assert!(private_key_flag_on_argv(["buzz", "--private-key=nsec1x"]));
+        assert!(!private_key_flag_on_argv(["buzz", "channels", "list"]));
+    }
+
+    #[test]
+    fn prefers_file_contents() {
+        let mut file = NamedTempFile::new().unwrap();
+        writeln!(file, "  nsec1filekey  ").unwrap();
+        let key = resolve_private_key(PrivateKeyInputs {
+            private_key_file: Some(file.path().to_path_buf()),
+            ..Default::default()
+        })
+        .unwrap();
+        assert_eq!(key, "nsec1filekey");
+    }
+
+    #[test]
+    fn rejects_multiple_sources() {
+        let err = resolve_private_key(PrivateKeyInputs {
+            private_key: Some("nsec1a".into()),
+            private_key_stdin: true,
+            ..Default::default()
+        })
+        .unwrap_err();
+        assert!(matches!(err, CliError::Usage(_)));
+    }
+
+    #[test]
+    fn env_value_without_argv_does_not_require_file() {
+        let key = resolve_private_key(PrivateKeyInputs {
+            private_key: Some("nsec1env".into()),
+            private_key_from_argv: false,
+            ..Default::default()
+        })
+        .unwrap();
+        assert_eq!(key, "nsec1env");
+    }
+}
diff --git a/crates/buzz-core/src/kind.rs b/crates/buzz-core/src/kind.rs
index afec52305a..b1be7c5038 100644
--- a/crates/buzz-core/src/kind.rs
+++ b/crates/buzz-core/src/kind.rs
@@ -182,29 +182,43 @@ pub const P_GATED_KINDS: &[u32] = &[
 /// or more than one `shared` tag) so no ambiguous heads can exist.
 pub const KIND_PERSONA: u32 = 30175;
 
-/// Returns `true` if `kind` uses the author-only-unless-shared read model
-/// (currently only `KIND_PERSONA` / 30175).
+/// Kinds that use the author-only-unless-shared read model.
 ///
 /// Events of these kinds may only be delivered to foreign readers when the
-/// event carries exactly `["shared", "true"]`. Used by all relay read
-/// chokepoints: REQ historical delivery, live fan-out, COUNT fallback,
-/// and the `ids`-lookup result gate.
-pub fn is_persona_shared_kind(kind: u32) -> bool {
-    kind == KIND_PERSONA
+/// event carries exactly `["shared", "true"]`. Every relay read chokepoint
+/// consults this set: REQ historical delivery, live fan-out, COUNT fallback,
+/// the `ids`-lookup result gate, both HTTP surfaces, and the pre-`LIMIT` SQL
+/// visibility pushdown in `buzz-db`.
+///
+/// Membership is a privacy decision, not a convenience: adding a kind here
+/// makes its events invisible to foreign readers until their author opts in,
+/// and the opt-in must be a `shared` TAG (not a content field) so that
+/// toggling it leaves content bytes — and any content hash derived from them —
+/// unchanged.
+///
+/// `KIND_TEAM` (30176) is deliberately NOT a member. Its writers never emit
+/// `shared`, so catalog opt-in semantics do not describe it; it needs
+/// owner-private read semantics instead, which is a separate change.
+pub const SHARED_GATED_KINDS: &[u32] = &[KIND_PERSONA, KIND_TEAM_CATALOG];
+
+/// Returns `true` if `kind` uses the author-only-unless-shared read model
+/// (see [`SHARED_GATED_KINDS`]).
+pub fn is_shared_gated_kind(kind: u32) -> bool {
+    SHARED_GATED_KINDS.contains(&kind)
 }
 
-/// Returns `true` if the event is a persona-shared-catalog kind AND the
-/// requester is NOT the author AND the event does NOT carry `["shared",
-/// "true"]`. All three conditions must hold to withhold the event.
+/// Returns `true` if the event is a shared-gated kind AND the requester is NOT
+/// the author AND the event does NOT carry `["shared", "true"]`. All three
+/// conditions must hold to withhold the event.
 ///
 /// This is the per-event gate used by REQ historical delivery, live fan-out,
 /// and COUNT fallback paths. It is intentionally independent of
-/// `is_author_only_event` — persona events with `["shared", "true"]` MUST
+/// `is_author_only_event` — shared-gated events with `["shared", "true"]` MUST
 /// reach foreign readers; stripping them at the author-only layer would break
 /// the catalog query.
-pub fn is_unshared_persona_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
+pub fn is_unshared_gated_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
     let kind = event.kind.as_u16() as u32;
-    if !is_persona_shared_kind(kind) {
+    if !is_shared_gated_kind(kind) {
         return false;
     }
     // Author reads are always allowed.
@@ -212,18 +226,23 @@ pub fn is_unshared_persona_event(event: &nostr::Event, requester_pubkey_bytes: &
         return false;
     }
     // Foreign reader: allowed only if the event is explicitly shared.
-    !persona_event_is_shared(event)
+    !event_is_shared(event)
 }
 
 /// Returns `true` if the event carries exactly one `["shared", "true"]` tag.
 ///
+/// Kind-agnostic: this is purely the tag-shape predicate. The kind check lives
+/// in [`is_shared_gated_kind`], so callers that need "is this event shared"
+/// for a kind they already know (e.g. a client deciding whether its own
+/// retained head is published) can use this directly.
+///
 /// Requires the tag to have exactly two elements so that a three-element shape
 /// like `["shared","true","extra"]` is NOT treated as shared. Ingest enforces
 /// the same exact shape, so a well-stored event either has no `shared` tag
 /// (author-only) or exactly one with precisely two elements and value `"true"`
 /// (community-readable). This helper fails closed on any non-exact shape
 /// independently of ingest guarantees.
-pub fn persona_event_is_shared(event: &nostr::Event) -> bool {
+pub fn event_is_shared(event: &nostr::Event) -> bool {
     let mut count = 0usize;
     for tag in event.tags.iter() {
         let parts = tag.as_slice();
@@ -258,6 +277,34 @@ pub const KIND_TEAM: u32 = 30176;
 /// since these events are world-readable on the relay.
 pub const KIND_MANAGED_AGENT: u32 = 30177;
 
+/// NIP-AP: Team Catalog projection (parameterized replaceable, owner-authored).
+///
+/// The shareable projection of a team, addressed by `(pubkey, kind, d_tag)`
+/// where `d_tag` is the team's stable id. Content is a versioned JSON body
+/// carrying sanitized team fields plus ordered, EMBEDDED member definition
+/// projections.
+///
+/// # Why this is not a `shared` tag on [`KIND_TEAM`]
+///
+/// A team's members live in kind 30175 events that are author-only unless
+/// individually shared, so a foreign reader of a shared team could never
+/// hydrate its members. This kind therefore embeds the member projections
+/// rather than referencing them: the share is atomic, it covers built-in
+/// members that have no 30175 head at all, it is immune to local-id/d-tag
+/// divergence, and an unshared 30175 stays private. Kind 30176's wire body is
+/// untouched, so device sync keeps its contract.
+///
+/// # Access control
+///
+/// Member of [`SHARED_GATED_KINDS`]: author-only unless the event carries
+/// exactly `["shared", "true"]`. Ingest additionally requires exactly one
+/// non-empty, bounded `d` tag — generic NIP-33 storage maps a missing `d` to
+/// the empty coordinate, which would collapse every team into one slot.
+///
+/// Content carries only sanitized fields: no env vars, no `respond_to`
+/// allowlist pubkeys, no source or local ids, no filesystem paths, no secrets.
+pub const KIND_TEAM_CATALOG: u32 = 30178;
+
 // NIP-56 reporting
 /// NIP-56: Report an event, pubkey, or blob to relay moderators (kind:1984).
 ///
@@ -562,6 +609,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,
@@ -586,6 +642,7 @@ pub const ALL_KINDS: &[u32] = &[
     KIND_PERSONA,
     KIND_TEAM,
     KIND_MANAGED_AGENT,
+    KIND_TEAM_CATALOG,
     KIND_REPORT,
     KIND_PRODUCT_FEEDBACK,
     KIND_NIP29_PUT_USER,
@@ -691,6 +748,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).
@@ -784,9 +842,11 @@ const _: () = assert!(is_replaceable(KIND_AGENT_PROFILE)); // 10100 ∈ 10000–
 const _: () = assert!(is_parameterized_replaceable(KIND_PERSONA)); // 30175 ∈ 30000–39999
 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_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
 
@@ -858,64 +918,68 @@ mod tests {
         }
     }
 
-    // ── persona_event_is_shared / is_unshared_persona_event ──────────────
+    // ── event_is_shared / is_unshared_gated_event ────────────────────────
 
-    fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
+    fn make_event_of_kind(kind: u32, tags: &[&[&str]]) -> nostr::Event {
         use nostr::{EventBuilder, Keys, Kind, Tag};
         let keys = Keys::generate();
         let tag_vec: Vec<Tag> = tags
             .iter()
             .map(|parts| Tag::parse(parts.iter().copied()).unwrap())
             .collect();
-        EventBuilder::new(Kind::Custom(KIND_PERSONA as u16), "")
+        EventBuilder::new(Kind::Custom(kind as u16), "")
             .tags(tag_vec)
             .sign_with_keys(&keys)
             .unwrap()
     }
 
+    fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
+        make_event_of_kind(KIND_PERSONA, tags)
+    }
+
     #[test]
-    fn persona_event_is_shared_true_tag() {
+    fn event_is_shared_true_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
-        assert!(persona_event_is_shared(&ev));
+        assert!(event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_no_tag() {
+    fn event_is_shared_no_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_wrong_value() {
+    fn event_is_shared_wrong_value() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "false"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_duplicate_shared_tags() {
+    fn event_is_shared_duplicate_shared_tags() {
         // Two ["shared","true"] tags → ambiguous; not considered shared.
         let ev =
             make_persona_event(&[&["d", "my-agent"], &["shared", "true"], &["shared", "true"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_three_element_tag_not_shared() {
+    fn event_is_shared_three_element_tag_not_shared() {
         // ["shared","true","extra"] — three elements — must NOT be treated as shared.
         // The helper fails closed on any non-exact shape independently of ingest guarantees.
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true", "extra"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_one_element_tag_not_shared() {
+    fn event_is_shared_one_element_tag_not_shared() {
         // ["shared"] — only one element — not shared (fails the == 2 check).
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn is_unshared_persona_event_author_always_allowed() {
+    fn is_unshared_gated_event_author_always_allowed() {
         // Even without a shared tag the event author should not be blocked.
         use nostr::{EventBuilder, Keys, Kind, Tag};
         let keys = Keys::generate();
@@ -924,32 +988,83 @@ mod tests {
             .sign_with_keys(&keys)
             .unwrap();
         let author_bytes = keys.public_key().to_bytes();
-        assert!(!is_unshared_persona_event(&ev, &author_bytes));
+        assert!(!is_unshared_gated_event(&ev, &author_bytes));
     }
 
     #[test]
-    fn is_unshared_persona_event_foreign_no_tag() {
+    fn is_unshared_gated_event_foreign_no_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"]]);
         let foreign = [0u8; 32];
-        assert!(is_unshared_persona_event(&ev, &foreign));
+        assert!(is_unshared_gated_event(&ev, &foreign));
     }
 
     #[test]
-    fn is_unshared_persona_event_foreign_shared_tag() {
+    fn is_unshared_gated_event_foreign_shared_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
         let foreign = [0u8; 32];
-        assert!(!is_unshared_persona_event(&ev, &foreign));
+        assert!(!is_unshared_gated_event(&ev, &foreign));
     }
 
     #[test]
-    fn is_unshared_persona_event_non_persona_kind_passthrough() {
+    fn is_unshared_gated_event_ungated_kind_passthrough() {
         use nostr::{EventBuilder, Keys, Kind};
         let keys = Keys::generate();
         let ev = EventBuilder::new(Kind::Custom(KIND_TEAM as u16), "")
             .sign_with_keys(&keys)
             .unwrap();
         let foreign = [0u8; 32];
-        // Non-persona kinds are never blocked by this gate.
-        assert!(!is_unshared_persona_event(&ev, &foreign));
+        // Kinds outside SHARED_GATED_KINDS are never blocked by this gate.
+        assert!(!is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_foreign_no_tag() {
+        // The gate must cover 30178 identically to 30175 — an unshared team
+        // catalog projection is author-only.
+        let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"]]);
+        let foreign = [0u8; 32];
+        assert!(is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_foreign_shared_tag() {
+        let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"], &["shared", "true"]]);
+        let foreign = [0u8; 32];
+        assert!(!is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_author_always_allowed() {
+        use nostr::{EventBuilder, Keys, Kind, Tag};
+        let keys = Keys::generate();
+        let ev = EventBuilder::new(Kind::Custom(KIND_TEAM_CATALOG as u16), "")
+            .tags(vec![Tag::parse(["d", "team-1"]).unwrap()])
+            .sign_with_keys(&keys)
+            .unwrap();
+        let author_bytes = keys.public_key().to_bytes();
+        assert!(!is_unshared_gated_event(&ev, &author_bytes));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_malformed_shared_tag_fails_closed() {
+        // A three-element `shared` tag can never be stored (ingest rejects it),
+        // but the read gate must independently treat it as NOT shared.
+        let ev = make_event_of_kind(
+            KIND_TEAM_CATALOG,
+            &[&["d", "team-1"], &["shared", "true", "extra"]],
+        );
+        let foreign = [0u8; 32];
+        assert!(is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn shared_gated_kinds_membership() {
+        assert!(is_shared_gated_kind(KIND_PERSONA));
+        assert!(is_shared_gated_kind(KIND_TEAM_CATALOG));
+        // 30176 has owner-private semantics, not catalog opt-in semantics: its
+        // writers never emit `shared`, so gating it here would hide every team
+        // from its own delegated readers.
+        assert!(!is_shared_gated_kind(KIND_TEAM));
+        assert!(!is_shared_gated_kind(KIND_MANAGED_AGENT));
     }
 }
diff --git a/crates/buzz-db/src/event.rs b/crates/buzz-db/src/event.rs
index 0e54196d11..a670a13402 100644
--- a/crates/buzz-db/src/event.rs
+++ b/crates/buzz-db/src/event.rs
@@ -11,12 +11,19 @@ use uuid::Uuid;
 
 use buzz_core::kind::{
     event_kind_i32, is_ephemeral, is_parameterized_replaceable, KIND_AUTH, KIND_EVENT_REMINDER,
-    KIND_HUDDLE_STARTED,
+    KIND_HUDDLE_STARTED, SHARED_GATED_KINDS,
 };
 use buzz_core::{CommunityId, StoredEvent};
 
 use crate::error::{DbError, Result};
 
+/// Largest page [`query_events`] will return when [`EventQuery::max_limit`] is
+/// unset — the effective ceiling on any client-requested `limit`.
+///
+/// This is the value the relay advertises as NIP-11 `limitation.max_limit`, so
+/// the advertised ceiling and the enforced one cannot drift.
+pub const DEFAULT_MAX_PAGE_LIMIT: i64 = 1_000;
+
 /// Optional filters for [`query_events`].
 #[derive(Debug, Clone)]
 pub struct EventQuery {
@@ -67,17 +74,19 @@ pub struct EventQuery {
     /// channel-less global events. Applied before SQL `LIMIT` so access-filtered
     /// historical pages have exact exhaustion semantics.
     pub channel_ids: Option<Vec<uuid::Uuid>>,
-    /// Override the default limit clamp (1000). Used by COUNT fallback path
-    /// which needs to fetch all matching events for post-filter counting.
-    /// When None, the default clamp of 1000 applies.
+    /// Override the default page clamp ([`DEFAULT_MAX_PAGE_LIMIT`]). Used by
+    /// the COUNT fallback path, which needs to fetch all matching events for
+    /// post-filter counting. When None, the default clamp applies.
     pub max_limit: Option<i64>,
-    /// Persona visibility reader: when set, append an SQL visibility clause
-    /// for kind 30175 before ORDER/LIMIT so private personas are excluded from
-    /// the candidate page rather than discarded after it.
+    /// Shared-gated visibility reader: when set, append an SQL visibility
+    /// clause for every kind in [`SHARED_GATED_KINDS`] before ORDER/LIMIT so
+    /// private events are excluded from the candidate page rather than
+    /// discarded after it.
     ///
-    /// The clause is: `AND (kind != 30175 OR pubkey = $reader OR tags @> ?)`,
-    /// where `?` is the JSONB literal `[["shared","true"]]`.  The GIN index on
-    /// `tags` (migration 0004, jsonb_path_ops) makes the containment check fast.
+    /// The clause is: `AND (kind NOT IN (...) OR pubkey = $reader OR tags @> ?)`,
+    /// where the `IN` list is [`SHARED_GATED_KINDS`] and `?` is the JSONB
+    /// literal `[["shared","true"]]`.  The GIN index on `tags` (migration 0004,
+    /// jsonb_path_ops) makes the containment check fast.
     ///
     /// NOTE: `tags @> '[["shared","true"]]'` uses JSONB containment, which
     /// matches any tag array that is a superset of `[["shared","true"]]` — it
@@ -85,7 +94,7 @@ pub struct EventQuery {
     /// 2` exact-shape check ensures such malformed tags are never stored, so the
     /// SQL pushdown is sound.  Keeping `event_visible_to_reader` as post-filter
     /// defense-in-depth catches any residual mismatch.
-    pub persona_reader: Option<Vec<u8>>,
+    pub shared_gated_reader: Option<Vec<u8>>,
 }
 
 impl EventQuery {
@@ -114,7 +123,7 @@ impl EventQuery {
             e_tags: None,
             channel_ids: None,
             max_limit: None,
-            persona_reader: None,
+            shared_gated_reader: None,
         }
     }
 }
@@ -355,7 +364,7 @@ pub(crate) async fn query_events_on(
         return Ok(vec![]);
     }
 
-    let clamp = q.max_limit.unwrap_or(1000);
+    let clamp = q.max_limit.unwrap_or(DEFAULT_MAX_PAGE_LIMIT);
     let limit_val = q.limit.unwrap_or(100).min(clamp);
     let offset_val = q.offset.unwrap_or(0);
 
@@ -512,25 +521,28 @@ pub(crate) async fn query_events_on(
         }
     }
 
-    // Persona visibility pushdown: exclude kind 30175 events that are neither
-    // authored by the reader nor explicitly shared.  Applied BEFORE ORDER/LIMIT
-    // so that a page of newer private personas does not push visible shared ones
-    // off the end of the result set (the catalog query pattern).
+    // Shared-gated visibility pushdown: exclude SHARED_GATED_KINDS events that
+    // are neither authored by the reader nor explicitly shared.  Applied BEFORE
+    // ORDER/LIMIT so that a page of newer private events does not push visible
+    // shared ones off the end of the result set (the catalog query pattern).
     //
-    // Clause: AND (kind != 30175 OR pubkey = $reader OR tags @> '[["shared","true"]]')
+    // Clause: AND (kind NOT IN (30175, 30178) OR pubkey = $reader
+    //              OR tags @> '[["shared","true"]]')
     //
     // The JSONB containment check is served by idx_events_tags_gin (migration
     // 0004, jsonb_path_ops).  `tags @> '[["shared","true"]]'` matches any array
     // that contains exactly the sub-array — a two-element `["shared","true"]`
-    // tag passes; a tag-absent event does not.  Because ingest now requires
-    // exactly two elements for the shared tag (parts.len() == 2), no stored
-    // event can carry a three-element superset.
-    if let Some(ref reader_bytes) = q.persona_reader {
-        let kind_30175: i32 = 30175;
+    // tag passes; a tag-absent event does not.  Because ingest requires exactly
+    // two elements for the shared tag (parts.len() == 2), no stored event can
+    // carry a three-element superset.
+    if let Some(ref reader_bytes) = q.shared_gated_reader {
         let shared_containment = serde_json::json!([["shared", "true"]]);
-        qb.push(format!(" AND ({col_prefix}kind != "));
-        qb.push_bind(kind_30175);
-        qb.push(format!(" OR {col_prefix}pubkey = "));
+        qb.push(format!(" AND ({col_prefix}kind NOT IN ("));
+        let mut sep = qb.separated(", ");
+        for kind in SHARED_GATED_KINDS {
+            sep.push_bind(*kind as i32);
+        }
+        qb.push(format!(") OR {col_prefix}pubkey = "));
         qb.push_bind(reader_bytes.clone());
         qb.push(format!(" OR {col_prefix}tags @> "));
         qb.push_bind(shared_containment);
@@ -777,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
@@ -785,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?;
 
diff --git a/crates/buzz-db/src/lib.rs b/crates/buzz-db/src/lib.rs
index 0c6ea36dac..9b26876747 100644
--- a/crates/buzz-db/src/lib.rs
+++ b/crates/buzz-db/src/lib.rs
@@ -55,7 +55,7 @@ pub mod user;
 pub mod workflow;
 
 pub use error::{DbError, Result};
-pub use event::{EventQuery, ReactionEventInsertOutcome};
+pub use event::{EventQuery, ReactionEventInsertOutcome, DEFAULT_MAX_PAGE_LIMIT};
 
 use chrono::{DateTime, Utc};
 use sqlx::postgres::{PgConnection, PgPoolOptions};
@@ -1813,16 +1813,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.
@@ -3988,8 +3999,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.
@@ -4085,6 +4121,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
@@ -5227,6 +5269,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() {
@@ -5780,15 +5891,21 @@ mod tests {
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn test_usage_metrics_lock_has_single_owner_and_releases_on_drop() {
-        let database_url =
-            std::env::var("TEST_DATABASE_URL").unwrap_or_else(|_| TEST_DB_URL.into());
-        let pool = PgPoolOptions::new()
-            .max_connections(2)
-            .connect(&database_url)
-            .await
-            .expect("connect to test DB");
+        // Use a private scratch database — not the shared TEST_DATABASE_URL.
+        // Postgres advisory locks are per-database; hardcoding the production
+        // USAGE_METRICS_LOCK_KEY (0x4255_5A5A_4D45_5452) on the shared test DB
+        // races any live buzz-relay on the same database (see #3619).
+        let admin_url = std::env::var("TEST_DATABASE_URL").unwrap_or_else(|_| TEST_DB_URL.into());
+        let admin = PgPoolOptions::new()
+            .max_connections(1)
+            .connect(&admin_url)
+            .await
+            .expect("connect admin to create scratch db");
+        let (pool, scratch_name) = create_scratch_db(&admin, "usage_metrics_lock").await;
         let first = Db::from_pool(pool.clone());
-        let second = Db::from_pool(pool);
+        let second = Db::from_pool(pool.clone());
+        // Same key as production (`buzz-relay` USAGE_METRICS_LOCK_KEY) — safe here
+        // because the scratch DB is empty of other holders.
         let key = 0x4255_5A5A_4D45_5452;
 
         let mut leader = first
@@ -5815,6 +5932,11 @@ mod tests {
                 .is_some(),
             "dropping the detached session releases its advisory lock"
         );
+
+        // Release any remaining session state before DROP DATABASE.
+        drop(first);
+        drop(second);
+        drop_scratch_db(&admin, pool, &scratch_name).await;
     }
 
     #[tokio::test]
@@ -7317,6 +7439,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/relay_members.rs b/crates/buzz-db/src/relay_members.rs
index 3805745f9b..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,
@@ -376,7 +403,7 @@ pub enum TransferResult {
 /// Default maximum number of communities a single pubkey can own. Enforced at
 /// the relay layer — the authoritative layer — so that concurrent transfers or
 /// transfer-vs-create races cannot both pass a preflight count.
-pub const MAX_COMMUNITIES_PER_OWNER: i64 = 3;
+pub const MAX_COMMUNITIES_PER_OWNER: i64 = 5;
 
 /// Effective per-owner community limit for this deployment.
 ///
diff --git a/crates/buzz-pubsub/src/lib.rs b/crates/buzz-pubsub/src/lib.rs
index eae8c5ef9e..4f1690beef 100644
--- a/crates/buzz-pubsub/src/lib.rs
+++ b/crates/buzz-pubsub/src/lib.rs
@@ -328,7 +328,7 @@ impl PubSubManager {
         publisher::publish_event(&self.pool, ctx, topic, event).await
     }
 
-    /// Set presence with 60s TTL. Call on connect and every 30s heartbeat.
+    /// Set presence with 180s TTL. Call on connect and every 60s heartbeat.
     pub async fn set_presence(
         &self,
         ctx: &TenantContext,
diff --git a/crates/buzz-pubsub/src/presence.rs b/crates/buzz-pubsub/src/presence.rs
index 178ba7550a..e0c9dfd6c9 100644
--- a/crates/buzz-pubsub/src/presence.rs
+++ b/crates/buzz-pubsub/src/presence.rs
@@ -1,7 +1,7 @@
 //! Presence tracking — online/away status with TTL.
 //!
-//! Stored as `SET buzz:{community}:presence:{pubkey_hex} "online" EX 90`.
-//! TTL is 3x the 30s heartbeat interval so a single missed heartbeat doesn't
+//! Stored as `SET buzz:{community}:presence:{pubkey_hex} "online" EX 180`.
+//! TTL is 3x the 60s heartbeat interval so a single missed heartbeat doesn't
 //! cause presence flap. Clean disconnect deletes immediately.
 
 use buzz_core::TenantContext;
@@ -12,8 +12,8 @@ use std::collections::HashMap;
 use crate::error::PubSubError;
 use crate::topic::BUZZ_PREFIX;
 
-/// 3x the 30s heartbeat — single missed heartbeat won't cause presence flap.
-pub const PRESENCE_TTL_SECS: u64 = 90;
+/// 3x the 60s heartbeat — single missed heartbeat won't cause presence flap.
+pub const PRESENCE_TTL_SECS: u64 = 180;
 
 /// Returns the Redis key for the presence entry of `pubkey` under `ctx`.
 pub fn presence_key(ctx: &TenantContext, pubkey: &PublicKey) -> String {
@@ -109,6 +109,12 @@ mod tests {
         TenantContext::resolved(CommunityId::from_uuid(Uuid::from_u128(id)), host)
     }
 
+    #[test]
+    fn presence_ttl_is_three_one_minute_heartbeat_windows() {
+        assert_eq!(PRESENCE_TTL_SECS, 180);
+        assert_eq!(PRESENCE_TTL_SECS, 3 * 60);
+    }
+
     #[test]
     fn test_presence_key_format() {
         let pubkey = make_pubkey();
diff --git a/crates/buzz-relay/src/api/bridge.rs b/crates/buzz-relay/src/api/bridge.rs
index 10461d8d46..a118ff453f 100644
--- a/crates/buzz-relay/src/api/bridge.rs
+++ b/crates/buzz-relay/src/api/bridge.rs
@@ -1236,10 +1236,10 @@ async fn query_events_authed(
             extract_channel_from_filter(filter),
             &accessible_channels,
         );
-        // Persona visibility pushdown: must mirror WS REQ so that a page of newer
-        // private personas does not starve older shared ones off the candidate page.
-        if crate::handlers::req::filter_can_match_persona_shared_kinds(filter) {
-            query.persona_reader = Some(pubkey_bytes.clone());
+        // Shared-gated visibility pushdown: must mirror WS REQ so that a page of
+        // newer private events does not starve older shared ones off the page.
+        if crate::handlers::req::filter_can_match_shared_gated_kinds(filter) {
+            query.shared_gated_reader = Some(pubkey_bytes.clone());
         }
 
         match extract_before_id(raw) {
@@ -1453,11 +1453,11 @@ async fn count_events_authed(
                     filter,
                     &authed_pubkey_hex,
                 );
-        // Force per-event fallback for filters that can match kind:30175 —
-        // the fast SQL count_events() path has no per-event gate and would
-        // over-count foreign unshared persona events (existence leak).
-        let needs_persona_filtering =
-            crate::handlers::req::filter_can_match_persona_shared_kinds(filter);
+        // Force per-event fallback for filters that can match a shared-gated
+        // kind — the fast SQL count_events() path has no per-event gate and
+        // would over-count foreign unshared events (existence leak).
+        let needs_shared_gate_filtering =
+            crate::handlers::req::filter_can_match_shared_gated_kinds(filter);
 
         // If filter targets a specific channel, verify access.
         if let Some(ch_id) = extract_channel_from_filter(filter) {
@@ -1472,10 +1472,10 @@ async fn count_events_authed(
                 tenant.community(),
             )
             .await;
-            // Persona visibility pushdown: same as REQ and /query paths, so the
-            // fallback's query_events call doesn't over-fetch private persona rows.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: same as REQ and /query paths, so
+            // the fallback's query_events call doesn't over-fetch private rows.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
                 !authors.is_empty()
@@ -1486,7 +1486,7 @@ async fn count_events_authed(
             if crate::handlers::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 match state.db.count_events_routed("bridge_count", &query).await {
                     Ok(n) => total += n as u64,
@@ -1541,10 +1541,10 @@ async fn count_events_authed(
             )
             .await;
             query.channel_ids = Some(accessible_channels.to_vec());
-            // Persona visibility pushdown: pre-filter before ORDER/LIMIT on the
-            // fallback query_events path.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: pre-filter before ORDER/LIMIT on
+            // the fallback query_events path.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
 
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
@@ -1556,7 +1556,7 @@ async fn count_events_authed(
             if crate::handlers::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 query.limit = None;
                 match state.db.count_events_routed("bridge_count", &query).await {
@@ -3042,6 +3042,27 @@ mod tests {
         assert_eq!(extract_page_offset(&raw, None), None);
     }
 
+    /// Offsets are sized from the *clamped* limit the DB will honor, not from
+    /// what the client asked for. `filter_to_query_params` clamps an absent or
+    /// over-ceiling `limit` to `DEFAULT_MAX_PAGE_LIMIT` (guarded in
+    /// `handlers::req::tests::req_filter_limit_clamps_to_advertised_nip11_max_limit`)
+    /// and that clamped value is what arrives here — so page N starts exactly
+    /// N-1 full pages in. Sizing from an unclamped limit would step past rows
+    /// the previous page never returned.
+    #[test]
+    fn extract_page_offset_sizes_pages_from_clamped_limit() {
+        let clamped = buzz_db::DEFAULT_MAX_PAGE_LIMIT;
+
+        assert_eq!(
+            extract_page_offset(&serde_json::json!({ "page": 2 }), Some(clamped)),
+            Some(clamped)
+        );
+        assert_eq!(
+            extract_page_offset(&serde_json::json!({ "page": 3 }), Some(clamped)),
+            Some(clamped * 2)
+        );
+    }
+
     #[test]
     fn extract_depth_limit_valid() {
         let raw = serde_json::json!({ "depth_limit": 3 });
diff --git a/crates/buzz-relay/src/api/git/transport.rs b/crates/buzz-relay/src/api/git/transport.rs
index 11c4f6d35b..f8e0300277 100644
--- a/crates/buzz-relay/src/api/git/transport.rs
+++ b/crates/buzz-relay/src/api/git/transport.rs
@@ -2795,10 +2795,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!(
diff --git a/crates/buzz-relay/src/api/media.rs b/crates/buzz-relay/src/api/media.rs
index fa0401bc26..0c28277e38 100644
--- a/crates/buzz-relay/src/api/media.rs
+++ b/crates/buzz-relay/src/api/media.rs
@@ -586,6 +586,22 @@ fn validate_media_path(sha256_ext: &str) -> Result<(), MediaError> {
 /// additional range requests.
 const MAX_RANGE_CHUNK: u64 = 16 * 1024 * 1024;
 
+/// CSP for a blob response, kept least-privilege while allowing browser-native
+/// viewers to load the response as their generated `<img>` or `<video>` source.
+///
+/// Chromium applies the blob response's CSP when a user navigates directly to
+/// an image or video URL. A bare `default-src 'none'` therefore blocks the
+/// browser-generated media element from loading the very response being viewed.
+fn blob_content_security_policy(content_type: &str) -> &'static str {
+    if content_type.starts_with("image/") {
+        "default-src 'none'; img-src 'self'"
+    } else if content_type.starts_with("video/") {
+        "default-src 'none'; media-src 'self'"
+    } else {
+        "default-src 'none'"
+    }
+}
+
 /// GET /media/{sha256_ext} — Blossom BUD-01 serve blob, with HTTP 206 range support.
 ///
 /// `sha256_ext` is either:
@@ -657,14 +673,16 @@ pub(crate) async fn serve_blob_for_tenant(
     };
 
     // Images and video render inline; generic files force download. This is the
-    // primary defence for non-previewable types — combined with `nosniff` and
-    // `CSP: default-src 'none'`, an attachment disposition prevents an uploaded
-    // file from ever executing or rendering as active content in the client.
+    // primary defence for non-previewable types — combined with `nosniff` and a
+    // restrictive CSP, an attachment disposition prevents an uploaded file from
+    // ever executing or rendering as active content in the client. Inline media
+    // gets only its own CSP source directive so direct browser navigation works.
     let disposition = if buzz_media::serve_inline(&content_type) {
         "inline"
     } else {
         "attachment"
     };
+    let content_security_policy = blob_content_security_policy(&content_type);
 
     let key = resolve_s3_key(&state.media_storage, tenant, sha256_ext).await?;
 
@@ -694,7 +712,7 @@ pub(crate) async fn serve_blob_for_tenant(
                 .header(header::CONTENT_LENGTH, total.to_string())
                 .header(header::CONTENT_DISPOSITION, disposition)
                 .header(header::CACHE_CONTROL, cache_control)
-                .header(header::CONTENT_SECURITY_POLICY, "default-src 'none'")
+                .header(header::CONTENT_SECURITY_POLICY, content_security_policy)
                 .header(header::X_CONTENT_TYPE_OPTIONS, "nosniff")
                 .header(header::ACCEPT_RANGES, "bytes")
                 .body(axum::body::Body::from_stream(stream))
@@ -736,7 +754,7 @@ pub(crate) async fn serve_blob_for_tenant(
                         .header(header::CONTENT_DISPOSITION, disposition)
                         .header(header::ACCEPT_RANGES, "bytes")
                         .header(header::CACHE_CONTROL, cache_control)
-                        .header(header::CONTENT_SECURITY_POLICY, "default-src 'none'")
+                        .header(header::CONTENT_SECURITY_POLICY, content_security_policy)
                         .header(header::X_CONTENT_TYPE_OPTIONS, "nosniff")
                         .body(axum::body::Body::from(chunk))
                         .map_err(|_| MediaError::Internal)?)
@@ -945,6 +963,30 @@ mod tests {
         assert!(should_stream_as_video(bytes));
     }
 
+    #[test]
+    fn inline_media_csp_allows_only_its_browser_native_viewer() {
+        assert_eq!(
+            blob_content_security_policy("video/mp4"),
+            "default-src 'none'; media-src 'self'"
+        );
+        assert_eq!(
+            blob_content_security_policy("image/png"),
+            "default-src 'none'; img-src 'self'"
+        );
+    }
+
+    #[test]
+    fn attachment_csp_keeps_all_resource_loading_disabled() {
+        assert_eq!(
+            blob_content_security_policy("application/pdf"),
+            "default-src 'none'"
+        );
+        assert_eq!(
+            blob_content_security_policy("application/octet-stream"),
+            "default-src 'none'"
+        );
+    }
+
     async fn test_state() -> Arc<AppState> {
         test_state_with_media_get_auth(false).await
     }
diff --git a/crates/buzz-relay/src/handlers/count.rs b/crates/buzz-relay/src/handlers/count.rs
index dfb44e152f..3eeab5e807 100644
--- a/crates/buzz-relay/src/handlers/count.rs
+++ b/crates/buzz-relay/src/handlers/count.rs
@@ -7,8 +7,8 @@ use tracing::warn;
 
 use crate::connection::{AuthState, ConnectionState};
 use crate::handlers::req::{
-    event_visible_to_reader, filter_can_match_persona_shared_kinds,
-    filter_can_match_result_gated_kinds, result_gated_count_safe_for_pushdown,
+    event_visible_to_reader, filter_can_match_result_gated_kinds,
+    filter_can_match_shared_gated_kinds, result_gated_count_safe_for_pushdown,
 };
 use crate::protocol::RelayMessage;
 use crate::state::AppState;
@@ -103,11 +103,11 @@ pub async fn handle_count(
         // fast-path count_events() cannot be used because it doesn't do
         // per-event author filtering.
         let needs_author_only_filtering = super::req::filter_can_match_author_only_kinds(filter);
-        // Determine if this filter can match kind 30175 (persona) — if so, the
-        // fast-path must be bypassed because it has no per-event shared-tag check.
-        // A fast count over 30175 would include foreign unshared persona events,
-        // leaking the existence of private agent activity.
-        let needs_persona_filtering = filter_can_match_persona_shared_kinds(filter);
+        // Determine if this filter can match a shared-gated kind (30175, 30178)
+        // — if so, the fast path must be bypassed because it has no per-event
+        // shared-tag check. A fast count over those kinds would include foreign
+        // unshared events, leaking the existence of private agent activity.
+        let needs_shared_gate_filtering = filter_can_match_shared_gated_kinds(filter);
         // Determine if this filter can match result-gated kinds (44200, 30622)
         // that require a per-event owner check. When the fast SQL path would
         // count matching rows without calling reader_authorized_for_event, a
@@ -157,10 +157,10 @@ pub async fn handle_count(
                 conn.tenant.community(),
             )
             .await;
-            // Persona visibility pushdown: pre-filter the fallback query_events
-            // candidate page before ORDER/LIMIT.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: pre-filter the fallback
+            // query_events candidate page before ORDER/LIMIT.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
                 !authors.is_empty()
@@ -171,7 +171,7 @@ pub async fn handle_count(
             if super::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 match state.db.count_events_routed("count_req", &query).await {
                     Ok(n) => total += n as u64,
@@ -230,9 +230,9 @@ pub async fn handle_count(
             )
             .await;
             query.channel_ids = Some(accessible_channels.to_vec());
-            // Persona visibility pushdown for the fallback query_events path.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown for the fallback query_events path.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
 
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
@@ -244,7 +244,7 @@ pub async fn handle_count(
             if super::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 query.limit = None; // COUNT doesn't need a row limit
                 match state.db.count_events_routed("count_req", &query).await {
diff --git a/crates/buzz-relay/src/handlers/event.rs b/crates/buzz-relay/src/handlers/event.rs
index 88dd5f5180..a9cdffcdec 100644
--- a/crates/buzz-relay/src/handlers/event.rs
+++ b/crates/buzz-relay/src/handlers/event.rs
@@ -7,7 +7,7 @@ use tracing::{debug, error, info, warn};
 
 use buzz_core::event::StoredEvent;
 use buzz_core::kind::{
-    event_kind_u32, is_ephemeral, is_unshared_persona_event, AUTHOR_ONLY_KINDS,
+    event_kind_u32, is_ephemeral, is_unshared_gated_event, AUTHOR_ONLY_KINDS,
     KIND_AGENT_OBSERVER_FRAME, KIND_GIFT_WRAP, KIND_PRESENCE_UPDATE,
 };
 use buzz_core::observer::{
@@ -151,10 +151,10 @@ pub async fn filter_fanout_by_access(
         matches
     };
 
-    // Persona shared-read gate (fan-out): kind 30175 events fan out to all
-    // connections only when carrying ["shared","true"]. Unshared personas
-    // are delivered only to the author's own connections, matching REQ semantics.
-    let matches = if buzz_core::kind::is_persona_shared_kind(event_kind_u32(&stored_event.event)) {
+    // Shared-read gate (fan-out): SHARED_GATED_KINDS events fan out to all
+    // connections only when carrying ["shared","true"]. Unshared ones are
+    // delivered only to the author's own connections, matching REQ semantics.
+    let matches = if buzz_core::kind::is_shared_gated_kind(event_kind_u32(&stored_event.event)) {
         let author = stored_event.event.pubkey.to_bytes();
         matches
             .into_iter()
@@ -167,7 +167,7 @@ pub async fn filter_fanout_by_access(
                     return true;
                 }
                 // Foreign connection: allowed only if the event is shared.
-                !is_unshared_persona_event(&stored_event.event, &pk)
+                !is_unshared_gated_event(&stored_event.event, &pk)
             })
             .collect()
     } else {
diff --git a/crates/buzz-relay/src/handlers/ingest.rs b/crates/buzz-relay/src/handlers/ingest.rs
index ee644d5a9b..fcd0d70728 100644
--- a/crates/buzz-relay/src/handlers/ingest.rs
+++ b/crates/buzz-relay/src/handlers/ingest.rs
@@ -28,12 +28,12 @@ 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_TEXT_NOTE, KIND_USER_STATUS,
-    KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER, RELAY_ADMIN_ADD_MEMBER, RELAY_ADMIN_CHANGE_ROLE,
-    RELAY_ADMIN_REMOVE_MEMBER, RELAY_ADMIN_SET_WORKSPACE_PROFILE,
+    KIND_STREAM_MESSAGE_V2, KIND_STREAM_REMINDER, KIND_TEAM, KIND_TEAM_CATALOG, KIND_TEXT_NOTE,
+    KIND_USER_STATUS, KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER, RELAY_ADMIN_ADD_MEMBER,
+    RELAY_ADMIN_CHANGE_ROLE, RELAY_ADMIN_REMOVE_MEMBER, RELAY_ADMIN_SET_WORKSPACE_PROFILE,
 };
 use buzz_core::tenant::TenantContext;
 use buzz_core::verification::verify_event;
@@ -214,7 +214,7 @@ fn required_scope_for_kind(kind: u32, event: &Event) -> Result<Scope, &'static s
         KIND_TEXT_NOTE | KIND_LONG_FORM => Ok(Scope::MessagesWrite),
         KIND_CONTACT_LIST | KIND_READ_STATE | KIND_USER_STATUS | KIND_AGENT_ENGRAM
         | KIND_EVENT_REMINDER | KIND_PERSONA | KIND_TEAM | KIND_MANAGED_AGENT
-        | super::push_lease::KIND_PUSH_LEASE => {
+        | KIND_TEAM_CATALOG | super::push_lease::KIND_PUSH_LEASE => {
             Ok(Scope::UsersWrite)
         }
         // NIP-AM: agent turn metrics are agent-authored global events (encrypted to owner).
@@ -301,6 +301,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
@@ -419,10 +422,12 @@ pub(crate) fn is_global_only_kind(kind: u32) -> bool {
             | KIND_AGENT_PROFILE
             // NIP-AP: persona definitions (30175): owner-authored, keyed by (pubkey, kind, d_tag).
             | KIND_PERSONA
-            // NIP-AP: team (30176) + managed-agent (30177) definitions: owner-authored,
-            // keyed by (pubkey, kind, d_tag). A stray `h` tag must not channel-scope them.
+            // NIP-AP: team (30176) + managed-agent (30177) definitions and the
+            // team-catalog projection (30178): owner-authored, keyed by
+            // (pubkey, kind, d_tag). A stray `h` tag must not channel-scope them.
             | KIND_TEAM
             | KIND_MANAGED_AGENT
+            | KIND_TEAM_CATALOG
             // NIP-34: git events use `a` tags (repo reference), not `h` tags (channel scope).
             // Parameterized replaceable kinds are keyed by (pubkey, kind, d_tag).
             | KIND_GIT_REPO_ANNOUNCEMENT
@@ -435,6 +440,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 —
@@ -1029,37 +1038,27 @@ fn validate_engram_envelope(event: &Event) -> Result<(), String> {
     Ok(())
 }
 
-/// Validate the envelope of a kind:30175 persona event.
-///
-/// Enforces:
-/// * exactly one `d` tag with a non-empty value matching the slug grammar
-///   `^[a-z0-9][a-z0-9_-]{0,63}$`.
-/// * at most one `shared` tag; if present, its value must be exactly `"true"`.
+/// Enforce the `shared`-tag shape shared by every kind in
+/// [`buzz_core::kind::SHARED_GATED_KINDS`]: at most one `shared` tag, and if
+/// present it must be exactly `["shared", "true"]`.
 ///
-/// Without the `d`-tag check, an empty d-tag collapses every persona into the
-/// `(pubkey, 30175, "")` slot — last-write-wins data loss.
+/// This ensures no ambiguous heads: either an event has no `shared` tag
+/// (author-only) or exactly `["shared", "true"]` (community-readable). Any
+/// other value (`"false"`, `"1"`, extra elements, duplicate tags) is rejected
+/// at ingest so read-path helpers — including the SQL-level `tags @>
+/// '[["shared","true"]]'` containment clause, which would otherwise match a
+/// three-element superset — can treat stored events as unambiguously one or the
+/// other.
 ///
-/// The `shared` tag rule ensures no ambiguous heads: either an event has no
-/// `shared` tag (author-only) or exactly `["shared", "true"]` (community-
-/// readable). Any other value (`"false"`, `"1"`, extra tags) is rejected at
-/// ingest so read-path helpers can treat stored events as unambiguously one or
-/// the other.
-fn validate_persona_envelope(event: &Event) -> Result<(), String> {
-    let mut d_tags: Vec<&str> = Vec::new();
+/// `label` names the kind in error messages (e.g. `"persona event"`).
+fn validate_shared_tag(event: &Event, label: &str) -> Result<(), String> {
     let mut shared_count = 0usize;
     for tag in event.tags.iter() {
         let parts = tag.as_slice();
-        if parts.len() >= 2 && parts[0].as_str() == "d" {
-            d_tags.push(&parts[1]);
-        }
         if !parts.is_empty() && parts[0].as_str() == "shared" {
-            // Exact shape required: ["shared", "true"] — exactly two elements,
-            // second element exactly "true". Extra elements are rejected so that
-            // a three-element tag like ["shared","true","extra"] cannot be stored
-            // and later misread as shared by the SQL-level visibility clause.
             if parts.len() != 2 || parts[1].as_str() != "true" {
                 return Err(format!(
-                    "persona event `shared` tag must be exactly [\"shared\",\"true\"] (got {:?})",
+                    "{label} `shared` tag must be exactly [\"shared\",\"true\"] (got {:?})",
                     parts.iter().map(|s| s.as_str()).collect::<Vec<_>>()
                 ));
             }
@@ -1068,39 +1067,380 @@ fn validate_persona_envelope(event: &Event) -> Result<(), String> {
     }
     if shared_count > 1 {
         return Err(format!(
-            "persona event must have at most one `shared` tag (got {shared_count})"
+            "{label} must have at most one `shared` tag (got {shared_count})"
         ));
     }
+    Ok(())
+}
+
+/// Return the event's single `d` tag value, requiring exactly one tag whose
+/// value is non-empty, at most 64 characters, and free of Unicode control
+/// characters and whitespace.
+///
+/// Without this check an empty `d` tag collapses every event of the kind into
+/// the `(pubkey, kind, "")` slot — last-write-wins data loss. The character
+/// bound keeps the value usable as a NIP-33 coordinate (`<kind>:<pubkey>:<d>`)
+/// and as a log field: an embedded newline or tab would break line-oriented
+/// consumers of both.
+///
+/// Tags are counted by their first element alone, so a valueless `["d"]`
+/// counts. Skipping it would let `["d"]` plus `["d", "team-1"]` pass the
+/// exactly-one rule, and a NIP-33 consumer that reads `["d"]` as an
+/// empty-valued first `d` tag would then address the event at `""` where this
+/// relay addresses it at `"team-1"`.
+///
+/// `label` names the kind in error messages (e.g. `"persona event"`).
+fn single_bounded_d_tag<'a>(event: &'a Event, label: &str) -> Result<&'a str, String> {
+    let d_tags: Vec<Option<&str>> = event
+        .tags
+        .iter()
+        .filter_map(|tag| {
+            let parts = tag.as_slice();
+            (parts.first().map(|name| name.as_str()) == Some("d"))
+                .then(|| parts.get(1).map(|value| value.as_str()))
+        })
+        .collect();
     if d_tags.len() != 1 {
         return Err(format!(
-            "persona event must have exactly one `d` tag (got {})",
+            "{label} must have exactly one `d` tag (got {})",
             d_tags.len()
         ));
     }
-    let d = d_tags[0];
+    let d = d_tags[0].unwrap_or_default();
     if d.is_empty() {
-        return Err("persona event `d` tag must not be empty".to_string());
+        return Err(format!("{label} `d` tag must not be empty"));
     }
-    // Slug grammar: ^[a-z0-9][a-z0-9_-]{0,63}$
-    if d.len() > 64 {
+    let char_count = d.chars().count();
+    if char_count > 64 {
         return Err(format!(
-            "persona event `d` tag too long ({} chars, max 64)",
-            d.len()
+            "{label} `d` tag too long ({char_count} chars, max 64)"
         ));
     }
+    if d.chars().any(|c| c.is_control() || c.is_whitespace()) {
+        return Err(format!(
+            "{label} `d` tag must not contain control characters or whitespace"
+        ));
+    }
+    Ok(d)
+}
+
+/// Validate the envelope of a kind:30175 persona event.
+///
+/// Enforces the shared-gated `shared`-tag shape ([`validate_shared_tag`]) plus
+/// exactly one `d` tag matching the persona slug grammar
+/// `^[a-z0-9][a-z0-9_-]{0,63}$`.
+fn validate_persona_envelope(event: &Event) -> Result<(), String> {
+    const LABEL: &str = "persona event";
+    validate_shared_tag(event, LABEL)?;
+    let d = single_bounded_d_tag(event, LABEL)?;
+    // Slug grammar: ^[a-z0-9][a-z0-9_-]{0,63}$
     let bytes = d.as_bytes();
     if !bytes[0].is_ascii_lowercase() && !bytes[0].is_ascii_digit() {
-        return Err(
-            "persona event `d` tag must start with a lowercase letter or digit".to_string(),
-        );
+        return Err(format!(
+            "{LABEL} `d` tag must start with a lowercase letter or digit"
+        ));
     }
     if !bytes[1..]
         .iter()
         .all(|&b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_' || b == b'-')
     {
-        return Err(
-            "persona event `d` tag must match [a-z0-9_-] after the first character".to_string(),
-        );
+        return Err(format!(
+            "{LABEL} `d` tag must match [a-z0-9_-] after the first character"
+        ));
+    }
+    Ok(())
+}
+
+/// Validate the envelope of a kind:30178 team-catalog event.
+///
+/// Enforces the shared-gated `shared`-tag shape ([`validate_shared_tag`]) plus
+/// exactly one non-empty, bounded `d` tag.
+///
+/// Deliberately NOT the persona slug grammar: a team's `d` tag is its stable
+/// local id, which is either a UUID or a built-in identifier such as
+/// `builtin-team:welcome` — the colon is not slug-legal, and rewriting ids to
+/// fit would break NIP-33 addressing against the team's own kind:30176 head.
+fn validate_team_catalog_envelope(event: &Event) -> Result<(), String> {
+    const LABEL: &str = "team-catalog event";
+    validate_shared_tag(event, LABEL)?;
+    single_bounded_d_tag(event, LABEL)?;
+    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(())
 }
@@ -2070,6 +2410,16 @@ async fn ingest_event_inner(
             .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
     }
 
+    if kind_u32 == KIND_TEAM_CATALOG {
+        validate_team_catalog_envelope(&event)
+            .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;
 
@@ -3597,6 +3947,24 @@ mod tests {
         assert!(err.contains("`d` tag"), "got: {err}");
     }
 
+    #[test]
+    fn persona_envelope_rejects_valueless_d_tag() {
+        // A lone ["d"] carries no value; it must fail as a missing value, not
+        // be skipped as though the event had no `d` tag at all.
+        let ev = make_persona(&[&["d"]]);
+        let err = validate_persona_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn persona_envelope_rejects_valueless_plus_valued_d_tags() {
+        // Counting only tags with a value would see one `d` here and accept the
+        // event, breaking the exactly-one rule.
+        let ev = make_persona(&[&["d"], &["d", "slug-a"]]);
+        let err = validate_persona_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
     #[test]
     fn persona_envelope_rejects_too_long() {
         let slug = "a".repeat(65);
@@ -3723,6 +4091,552 @@ mod tests {
         );
     }
 
+    // ─── team-catalog (30178) envelope tests ─────────────────────────────────
+
+    fn make_team_catalog(tags: &[&[&str]]) -> Event {
+        make_event_with_tags(
+            KIND_TEAM_CATALOG,
+            r#"{"v":1,"name":"Team","members":[]}"#,
+            tags,
+        )
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_uuid_d_tag() {
+        let ev = make_team_catalog(&[&["d", "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_builtin_colon_d_tag() {
+        // Built-in team ids carry a colon (`builtin-team:welcome`), which the
+        // persona slug grammar forbids. The catalog `d` tag must accept them so
+        // a built-in team can be shared under its real local id.
+        let ev = make_team_catalog(&[&["d", "builtin-team:welcome"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_shared_true() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_missing_d_tag() {
+        let ev = make_team_catalog(&[]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_empty_d_tag() {
+        // An empty d-tag collapses every team into the (pubkey, 30178, "") slot.
+        let ev = make_team_catalog(&[&["d", ""]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_duplicate_d_tags() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["d", "team-2"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_valueless_d_tag() {
+        // A lone ["d"] carries no value; it must fail as a missing value, not
+        // be skipped as though the event had no `d` tag at all.
+        let ev = make_team_catalog(&[&["d"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_valueless_plus_valued_d_tags() {
+        // Counting only tags with a value would see one `d` here and accept the
+        // event. A NIP-33 consumer that reads ["d"] as an empty-valued first
+        // `d` tag would then address this event at "" where we address it at
+        // "team-1".
+        let ev = make_team_catalog(&[&["d"], &["d", "team-1"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_bounds_d_tag_by_chars_not_bytes() {
+        // 64 multi-byte characters is 192 bytes; the documented bound is
+        // characters, so this must be accepted.
+        let d = "é".repeat(64);
+        assert!(d.len() > 64, "fixture must exceed the bound in bytes");
+        let ev = make_team_catalog(&[&["d", &d]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_too_long_d_tag() {
+        let d = "a".repeat(65);
+        let ev = make_team_catalog(&[&["d", &d]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("too long"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_max_length_d_tag() {
+        let d = "a".repeat(64);
+        let ev = make_team_catalog(&[&["d", &d]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_whitespace_d_tag() {
+        // A newline in the d-tag would break the NIP-33 coordinate and any
+        // line-oriented log consumer.
+        let ev = make_team_catalog(&[&["d", "team\n1"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("control characters"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_shared_false() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "false"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("\"true\""), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_shared_three_elements() {
+        // Same exact-shape rule as personas: a three-element tag would match the
+        // SQL containment clause `tags @> '[["shared","true"]]'` as a superset.
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true", "extra"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("[\"shared\",\"true\"]"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_duplicate_shared_tags() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true"], &["shared", "true"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("at most one"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_is_in_scope_allowlist() {
+        let dummy = make_dummy_event();
+        assert_eq!(
+            required_scope_for_kind(KIND_TEAM_CATALOG, &dummy).unwrap(),
+            Scope::UsersWrite,
+        );
+    }
+
+    #[test]
+    fn team_catalog_is_global_only() {
+        assert!(is_global_only_kind(KIND_TEAM_CATALOG));
+        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 51400452d7..2aed12cd7f 100644
--- a/crates/buzz-relay/src/handlers/req.rs
+++ b/crates/buzz-relay/src/handlers/req.rs
@@ -7,8 +7,8 @@ use tracing::{debug, warn};
 
 use buzz_core::filter::filters_match;
 use buzz_core::kind::{
-    is_unshared_persona_event, AUTHOR_ONLY_KINDS, KIND_AGENT_ENGRAM, KIND_AGENT_TURN_METRIC,
-    KIND_DM_VISIBILITY, KIND_PERSONA, P_GATED_KINDS, RESULT_GATED_KINDS,
+    is_unshared_gated_event, AUTHOR_ONLY_KINDS, KIND_AGENT_ENGRAM, KIND_AGENT_TURN_METRIC,
+    KIND_DM_VISIBILITY, P_GATED_KINDS, RESULT_GATED_KINDS, SHARED_GATED_KINDS,
 };
 use buzz_core::tenant::TenantContext;
 use buzz_db::EventQuery;
@@ -22,7 +22,6 @@ use crate::connection::{AuthState, ConnectionState};
 use crate::protocol::RelayMessage;
 use crate::state::AppState;
 
-const MAX_HISTORICAL_LIMIT: i64 = 2_000;
 const MAX_SUBSCRIPTIONS: usize = 1024;
 
 /// Maximum `query_events` calls in flight per multi-filter REQ / bridge query.
@@ -290,11 +289,11 @@ pub async fn handle_req(
             let mut params =
                 filter_to_query_params(filter, per_filter_channel, conn.tenant.community());
             apply_access_scope_to_query(&mut params, per_filter_channel, &accessible_channels);
-            // Persona visibility pushdown: set reader bytes so query_events appends
-            // the SQL visibility clause before ORDER/LIMIT, preventing newer private
-            // personas from starving older shared ones off the page.
-            if filter_can_match_persona_shared_kinds(filter) {
-                params.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: set reader bytes so query_events
+            // appends the SQL visibility clause before ORDER/LIMIT, preventing
+            // newer private events from starving older shared ones off the page.
+            if filter_can_match_shared_gated_kinds(filter) {
+                params.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             (idx, per_filter_channel, params)
         })
@@ -416,10 +415,24 @@ pub async fn handle_req(
     );
 }
 
-/// Handle a NIP-50 search REQ: query Postgres FTS, fetch full events, deliver results, EOSE.
-/// Search subscriptions are one-shot — no persistent subscription is registered.
+/// FTS candidate hits fetched per page. Pages are always full regardless of
+/// the requested limit — post-filtering discards an unpredictable share of
+/// hits, so the scan fetches candidates in full pages rather than sizing
+/// pages to the request.
+const SEARCH_PAGE_SIZE: u32 = 100;
+
 /// Maximum FTS pages to fetch per filter (prevents unbounded loops).
-const MAX_SEARCH_PAGES: u32 = 10;
+///
+/// Derived from the advertised page ceiling rather than fixed: the scan
+/// budget is a resource policy — at most one advertised page ceiling's worth
+/// of candidates per filter — and deriving it keeps the budget tracking the
+/// ceiling if the ceiling ever moves. This bounds candidates *scanned*, not
+/// events *emitted*: post-filtering (NIP-01 match, channel access, reader
+/// visibility, dedup) can discard any number of candidates, so a result
+/// smaller than the requested limit remains possible and is not a NIP-11
+/// violation — `max_limit` promises a clamp on the request, not a count in
+/// the response.
+const MAX_SEARCH_PAGES: u32 = (buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32).div_ceil(SEARCH_PAGE_SIZE);
 
 /// Resolve request-local channel access, repairing a stale cache-negative.
 ///
@@ -501,6 +514,8 @@ pub(crate) fn build_search_channel_scope_filter(
     })
 }
 
+/// Handle a NIP-50 search REQ: query Postgres FTS, fetch full events, deliver results, EOSE.
+/// Search subscriptions are one-shot — no persistent subscription is registered.
 #[allow(clippy::too_many_arguments)]
 async fn handle_search_req(
     sub_id: &str,
@@ -535,8 +550,8 @@ async fn handle_search_req(
 
         let limit = filter
             .limit
-            .map(|l| (l as u32).min(MAX_HISTORICAL_LIMIT as u32))
-            .unwrap_or(MAX_HISTORICAL_LIMIT as u32);
+            .map(|l| (l as u32).min(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32))
+            .unwrap_or(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32);
 
         if limit == 0 {
             continue; // NIP-01: limit 0 means "no results from this filter"
@@ -583,13 +598,11 @@ async fn handle_search_req(
         let since = filter.since.map(|s| s.as_secs() as i64);
         let until = filter.until.map(|u| u.as_secs() as i64);
 
-        // Paginate: keep fetching pages until we've emitted `limit` results
-        // or exhausted the search result set. This ensures post-filtering
-        // doesn't silently reduce the result count below the requested limit.
+        // Paginate: keep fetching pages until we've emitted `limit` results or
+        // exhausted the search result set. Post-filtering discards an unpredictable
+        // share of each page, so continuing past short yields gives the scan a
+        // chance — not a guarantee — of filling the requested limit.
         let mut emitted: u32 = 0;
-        // Always fetch full pages (100) regardless of limit — post-filtering
-        // may discard many hits, so we need headroom to fill the requested limit.
-        let per_page: u32 = 100;
 
         for page in 1..=MAX_SEARCH_PAGES {
             if emitted >= limit {
@@ -605,7 +618,7 @@ async fn handle_search_req(
                 since,
                 until,
                 page,
-                per_page,
+                per_page: SEARCH_PAGE_SIZE,
                 mode: buzz_search::SearchMode::FullText,
             };
 
@@ -617,9 +630,9 @@ async fn handle_search_req(
                 }
             };
 
-            // A short page is the last page: FTS returns up to `per_page` hits,
-            // so fewer than that means the result set is exhausted.
-            let exhausted = search_result.hits.len() < per_page as usize;
+            // A short page is the last page: FTS returns up to a full page of
+            // hits, so fewer than that means the result set is exhausted.
+            let exhausted = search_result.hits.len() < SEARCH_PAGE_SIZE as usize;
             let page_empty = search_result.hits.is_empty();
 
             let hit_ids: Vec<[u8; 32]> =
@@ -878,8 +891,8 @@ fn filter_to_query_params(
         .and_then(|u| chrono::DateTime::from_timestamp(u.as_secs() as i64, 0));
     let limit = filter
         .limit
-        .map(|l| (l as i64).min(MAX_HISTORICAL_LIMIT))
-        .unwrap_or(MAX_HISTORICAL_LIMIT);
+        .map(|l| (l as i64).min(buzz_db::DEFAULT_MAX_PAGE_LIMIT))
+        .unwrap_or(buzz_db::DEFAULT_MAX_PAGE_LIMIT);
 
     // Push author filter into SQL. Single-author uses the indexed `pubkey` column;
     // multi-author uses the `authors` IN-list pushdown added in the pure-nostr PR.
@@ -1137,19 +1150,20 @@ pub(crate) fn filter_can_match_author_only_kinds(filter: &Filter) -> bool {
     })
 }
 
-/// Returns `true` if the filter CAN match kind 30175 (persona) — meaning it
-/// either has no `kinds` constraint (wildcard) or explicitly includes 30175.
+/// Returns `true` if the filter CAN match any kind in [`SHARED_GATED_KINDS`] —
+/// meaning it either has no `kinds` constraint (wildcard) or explicitly includes
+/// one of them.
 ///
 /// Used by the COUNT handler to force the per-event fallback path, which calls
-/// `is_unshared_persona_event` on each row. The fast SQL `count_events()` path
+/// `is_unshared_gated_event` on each row. The fast SQL `count_events()` path
 /// has no per-event access check, so it would over-count foreign unshared
-/// persona events — leaking the existence of persona activity even without
-/// returning content.
-pub(crate) fn filter_can_match_persona_shared_kinds(filter: &Filter) -> bool {
-    filter
-        .kinds
-        .as_ref()
-        .is_none_or(|ks| ks.iter().any(|k| k.as_u16() as u32 == KIND_PERSONA))
+/// events — leaking the existence of private persona/team-catalog activity even
+/// without returning content.
+pub(crate) fn filter_can_match_shared_gated_kinds(filter: &Filter) -> bool {
+    filter.kinds.as_ref().is_none_or(|ks| {
+        ks.iter()
+            .any(|k| SHARED_GATED_KINDS.contains(&(k.as_u16() as u32)))
+    })
 }
 
 /// Returns `true` if the filter CAN match result-gated kinds — meaning it
@@ -1208,8 +1222,9 @@ pub(crate) fn is_author_only_event(event: &nostr::Event, requester_pubkey_bytes:
 ///
 /// 1. **Author-only kinds** (`AUTHOR_ONLY_KINDS`, e.g. kind 30300/30350): only
 ///    the author may read their own events.
-/// 2. **Persona shared-gate** (kind 30175 without `["shared","true"]`): the
-///    event is only visible to the author unless explicitly opted into sharing.
+/// 2. **Shared-gate** (`SHARED_GATED_KINDS`, e.g. kind 30175/30178 without
+///    `["shared","true"]`): the event is only visible to the author unless
+///    explicitly opted into sharing.
 /// 3. **Result-gated kinds** (kind 44200/30622 etc.): `reader_authorized_for_event`
 ///    carries the per-event ownership check.
 ///
@@ -1223,7 +1238,7 @@ pub(crate) fn event_visible_to_reader(event: &nostr::Event, requester_pubkey_byt
     if is_author_only_event(event, requester_pubkey_bytes) {
         return false;
     }
-    if is_unshared_persona_event(event, requester_pubkey_bytes) {
+    if is_unshared_gated_event(event, requester_pubkey_bytes) {
         return false;
     }
     let requester_pubkey_hex = hex::encode(requester_pubkey_bytes);
@@ -1416,6 +1431,83 @@ mod tests {
         )
     }
 
+    /// NIP-11 `limitation.max_limit` as this relay actually advertises it.
+    fn advertised_max_limit() -> i64 {
+        crate::nip11::RelayInfo::build(
+            None,
+            None,
+            false,
+            crate::config::DEFAULT_MAX_FRAME_BYTES,
+            None,
+        )
+        .limitation
+        .expect("limitation")
+        .max_limit
+        .expect("max_limit") as i64
+    }
+
+    #[test]
+    fn req_filter_limit_clamps_to_advertised_nip11_max_limit() {
+        let advertised = advertised_max_limit();
+
+        let community = buzz_core::tenant::CommunityId::from_uuid(uuid::Uuid::new_v4());
+
+        // A filter asking for more than the relay advertises is clamped down to
+        // exactly the advertised ceiling — the NIP-11 document is the promise,
+        // this is the enforcement.
+        let greedy = filter_to_query_params(
+            &Filter::new().limit(advertised as usize * 10),
+            None,
+            community,
+        );
+        assert_eq!(greedy.limit, Some(advertised));
+
+        // A filter with no `limit` gets the same ceiling, not something larger.
+        let unbounded = filter_to_query_params(&Filter::new(), None, community);
+        assert_eq!(unbounded.limit, Some(advertised));
+
+        // Neither sets `max_limit`, so `query_events` applies its own default
+        // clamp. That default must equal the advertised value too, or the
+        // clamp above would be undone one layer down.
+        assert_eq!(greedy.max_limit, None);
+        assert_eq!(unbounded.max_limit, None);
+        assert_eq!(buzz_db::DEFAULT_MAX_PAGE_LIMIT, advertised);
+
+        // Under-ceiling requests are honored verbatim.
+        let modest = filter_to_query_params(&Filter::new().limit(10), None, community);
+        assert_eq!(modest.limit, Some(10));
+    }
+
+    /// The NIP-50 search path clamps its emission target to the advertised
+    /// ceiling like every other REQ, but the number of candidates it will scan
+    /// is bounded a second time by the page budget. This pins the resource
+    /// policy: the budget covers exactly one advertised page ceiling's worth of
+    /// candidates — no less (a ceiling raise must not silently shrink the scan
+    /// relative to what clients may request) and no hand-tuned spare (the budget
+    /// must stay derived, not drift back into a magic number). It deliberately
+    /// does NOT claim search fills the emitted limit — post-filtering can
+    /// discard any number of candidates.
+    #[test]
+    fn search_scan_capacity_covers_advertised_nip11_max_limit() {
+        let advertised = advertised_max_limit();
+        let capacity = i64::from(MAX_SEARCH_PAGES) * i64::from(SEARCH_PAGE_SIZE);
+
+        assert!(
+            capacity >= advertised,
+            "NIP-50 scans at most {capacity} candidates ({MAX_SEARCH_PAGES} pages of \
+             {SEARCH_PAGE_SIZE}) but NIP-11 advertises {advertised} — the scan budget \
+             no longer covers the advertised ceiling"
+        );
+
+        // The budget is derived, not hand-tuned: one page under the derived
+        // count must be insufficient, or the ceiling could rise without the
+        // page count following it.
+        assert!(
+            capacity - i64::from(SEARCH_PAGE_SIZE) < advertised,
+            "scan budget has a spare page of slack — derive it from the ceiling"
+        );
+    }
+
     #[test]
     fn count_fallback_fetches_one_extra_candidate() {
         let mut query =
diff --git a/crates/buzz-relay/src/handlers/side_effects.rs b/crates/buzz-relay/src/handlers/side_effects.rs
index 65d04ef0ba..660a55fef3 100644
--- a/crates/buzz-relay/src/handlers/side_effects.rs
+++ b/crates/buzz-relay/src/handlers/side_effects.rs
@@ -2167,9 +2167,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/nip11.rs b/crates/buzz-relay/src/nip11.rs
index a8e397dd21..2575ddd7ba 100644
--- a/crates/buzz-relay/src/nip11.rs
+++ b/crates/buzz-relay/src/nip11.rs
@@ -89,6 +89,11 @@ pub struct RelayLimitation {
 
 /// Canonical `RelayLimitation` advertised by this relay.
 ///
+/// `max_limit` is [`buzz_db::DEFAULT_MAX_PAGE_LIMIT`], the same constant the
+/// REQ path clamps filter limits to, so the advertised ceiling and the
+/// enforced one cannot drift (see
+/// `handlers::req::tests::req_filter_limit_clamps_to_advertised_nip11_max_limit`).
+///
 /// `auth_required` is always `true`: the REQ, EVENT, and COUNT handlers
 /// unconditionally reject connections that are not in
 /// `AuthState::Authenticated`. This is independent of the REST API token
@@ -103,7 +108,7 @@ fn relay_limitation(max_message_length: usize) -> RelayLimitation {
         max_message_length: Some(max_message_length as u64),
         max_subscriptions: Some(1024),
         max_filters: Some(10),
-        max_limit: Some(10_000),
+        max_limit: Some(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32),
         max_subid_length: Some(256),
         min_pow_difficulty: None,
         auth_required: true,
diff --git a/crates/buzz-test-client/tests/e2e_persona.rs b/crates/buzz-test-client/tests/e2e_persona.rs
index b3b1f7f6b2..4f37e22e16 100644
--- a/crates/buzz-test-client/tests/e2e_persona.rs
+++ b/crates/buzz-test-client/tests/e2e_persona.rs
@@ -1324,7 +1324,7 @@ async fn test_persona_http_query_cross_author_gate() {
 ///
 /// A foreign authenticated caller counting `{kinds:[30175],authors:[victim]}`
 /// must count only shared heads — not unshared ones — on both the fast SQL
-/// path (prevented by `needs_persona_filtering`) and the fallback path.
+/// path (prevented by `needs_shared_gate_filtering`) and the fallback path.
 #[tokio::test]
 #[ignore]
 async fn test_persona_http_count_cross_author_gate() {
@@ -1403,7 +1403,7 @@ async fn test_persona_http_count_cross_author_gate() {
 /// event is returned.
 ///
 /// Verifies at `312014d5e`: this test fails there because `query_events` did
-/// not have the `persona_reader` SQL clause and the private rows starved the
+/// not have the `shared_gated_reader` SQL clause and the private rows starved the
 /// shared one off the page.
 #[tokio::test]
 #[ignore]
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_team_catalog.rs b/crates/buzz-test-client/tests/e2e_team_catalog.rs
new file mode 100644
index 0000000000..ce313d1fe9
--- /dev/null
+++ b/crates/buzz-test-client/tests/e2e_team_catalog.rs
@@ -0,0 +1,484 @@
+//! End-to-end tests for kind:30178 team-catalog events (NIP-AP).
+//!
+//! Kind 30178 is the shareable projection of a team. It joins kind:30175 in
+//! `SHARED_GATED_KINDS`, so these tests assert the wire behaviour of that gate
+//! at every read chokepoint (REQ, `ids` lookup, COUNT, live fan-out) plus the
+//! ingest envelope rules that make the gate sound:
+//! - Exactly one non-empty, bounded `d` tag — the team's stable local id, which
+//!   may contain a colon (`builtin-team:welcome`) unlike a persona slug.
+//! - `shared`, if present, is exactly `["shared", "true"]`.
+//!
+//! # Running
+//!
+//! Start the relay, then run:
+//!
+//! ```text
+//! RELAY_URL=ws://localhost:3000 cargo test --test e2e_team_catalog -- --ignored
+//! ```
+
+use std::time::Duration;
+
+use buzz_test_client::{BuzzTestClient, RelayMessage};
+use nostr::{Alphabet, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag, Timestamp};
+
+const TEAM_CATALOG_KIND: u16 = 30178;
+
+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-team-catalog-{name}-{}", uuid::Uuid::new_v4())
+}
+
+fn catalog_content(name: &str) -> String {
+    serde_json::json!({ "v": 1, "name": name, "members": [] }).to_string()
+}
+
+/// Build a kind:30178 event, optionally carrying the `["shared","true"]` opt-in.
+fn catalog_event(keys: &Keys, d_tag: &str, shared: bool) -> nostr::Event {
+    catalog_event_at(keys, d_tag, shared, Timestamp::now().as_secs())
+}
+
+/// Same as [`catalog_event`] with an explicit `created_at`, so NIP-33 head
+/// ordering is deterministic instead of resolved by event-id tie-break.
+fn catalog_event_at(keys: &Keys, d_tag: &str, shared: bool, created_at: u64) -> nostr::Event {
+    let mut tags = vec![Tag::parse(["d", d_tag]).unwrap()];
+    if shared {
+        tags.push(Tag::parse(["shared", "true"]).unwrap());
+    }
+    EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Test Team"),
+    )
+    .tags(tags)
+    .custom_created_at(Timestamp::from(created_at))
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+fn author_filter(author: &Keys) -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(TEAM_CATALOG_KIND))
+        .author(author.public_key())
+}
+
+fn coordinate_filter(author: &Keys, d_tag: &str) -> Filter {
+    author_filter(author).custom_tags(SingleLetterTag::lowercase(Alphabet::D), [d_tag])
+}
+
+fn d_tag_of(event: &nostr::Event) -> Option<&str> {
+    event.tags.iter().find_map(|t| {
+        let parts = t.as_slice();
+        if parts.first().map(|p| p.as_str()) != Some("d") {
+            return None;
+        }
+        Some(parts.get(1)?.as_str())
+    })
+}
+
+/// The author's own unshared projection round-trips at its NIP-33 coordinate.
+///
+/// The `d` tag is a UUID, matching the desktop team id — proof the envelope does
+/// NOT apply the persona slug grammar.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_publish_and_query_own_unshared() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let event = catalog_event(&keys, &d_tag, false);
+    let event_id = event.id;
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(ok.accepted, "relay rejected catalog event: {}", ok.message);
+
+    let sid = sub_id("own-unshared");
+    client
+        .subscribe(&sid, vec![coordinate_filter(&keys, &d_tag)])
+        .await
+        .expect("subscribe");
+    let events = client
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert_eq!(events.len(), 1, "author must see own unshared projection");
+    assert_eq!(events[0].id, event_id);
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// A built-in team id (`builtin-team:welcome`) is accepted as the `d` tag.
+///
+/// The colon is illegal in a persona slug; rewriting the id to fit would break
+/// NIP-33 addressing against the team's own kind:30176 head.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_accepts_builtin_colon_d_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = format!("builtin-team:{}", &uuid::Uuid::new_v4().to_string()[..8]);
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client
+        .send_event(catalog_event(&keys, &d_tag, true))
+        .await
+        .expect("send catalog");
+    assert!(
+        ok.accepted,
+        "relay rejected colon-bearing team id: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses an empty `d` tag: generic NIP-33 storage maps it to the empty
+/// coordinate, collapsing every team into one `(pubkey, 30178, "")` slot.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_empty_d_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client
+        .send_event(catalog_event(&keys, "", false))
+        .await
+        .expect("send catalog");
+    assert!(!ok.accepted, "empty d-tag must be rejected");
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses a valueless `["d"]` tag alongside a valued one. Counting only
+/// tags that carry a value would see exactly one `d` here and accept the event;
+/// a NIP-33 consumer that reads `["d"]` as an empty-valued first `d` tag would
+/// then address the event at `""` where this relay addresses it at the team id.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_valueless_plus_valued_d_tags() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let event = EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Two d tags"),
+    )
+    .tags(vec![
+        Tag::parse(["d"]).unwrap(),
+        Tag::parse(["d", d_tag.as_str()]).unwrap(),
+    ])
+    .sign_with_keys(&keys)
+    .unwrap();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(
+        !ok.accepted,
+        "a valueless `d` tag must count toward the exactly-one rule"
+    );
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses a malformed `shared` tag. A three-element tag would satisfy
+/// the SQL containment clause `tags @> '[["shared","true"]]'` as a superset
+/// while the in-process gate reads it as unshared — the two layers must agree,
+/// so such an event can never be stored.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_three_element_shared_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let event = EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Malformed"),
+    )
+    .tags(vec![
+        Tag::parse(["d", d_tag.as_str()]).unwrap(),
+        Tag::parse(["shared", "true", "extra"]).unwrap(),
+    ])
+    .sign_with_keys(&keys)
+    .unwrap();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(!ok.accepted, "three-element shared tag must be rejected");
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// REQ historical delivery: a foreign reader receives only shared projections,
+/// while the author receives both of their own.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_foreign_sees_only_shared() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let d_unshared = format!("priv-{}", uuid::Uuid::new_v4());
+    let d_shared = format!("pub-{}", uuid::Uuid::new_v4());
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let shared_event = catalog_event(&author_keys, &d_shared, true);
+    let shared_id = shared_event.id;
+    let ok = author
+        .send_event(catalog_event(&author_keys, &d_unshared, false))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared ingest rejected: {}", ok.message);
+    let ok = author.send_event(shared_event).await.expect("send shared");
+    assert!(ok.accepted, "shared ingest rejected: {}", ok.message);
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("fg-all");
+    foreign
+        .subscribe(&sid, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe");
+    let events = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert!(
+        !events
+            .iter()
+            .any(|e| d_tag_of(e) == Some(d_unshared.as_str())),
+        "foreign reader must NOT see the unshared projection"
+    );
+    assert!(
+        events.iter().any(|e| e.id == shared_id),
+        "foreign reader must see the shared projection"
+    );
+
+    let sid_author = sub_id("auth-all");
+    author
+        .subscribe(&sid_author, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe author");
+    let author_events = author
+        .collect_until_eose(&sid_author, Duration::from_secs(5))
+        .await
+        .expect("collect author");
+    assert!(
+        author_events.len() >= 2,
+        "author must see both own projections, got {}",
+        author_events.len()
+    );
+
+    author.disconnect().await.expect("disconnect author");
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// Knowing an event id does NOT grant access: `{ids:[unshared]}` returns nothing
+/// to a foreign reader.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_ids_lookup_unshared_returns_nothing_to_foreign() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let event = catalog_event(&author_keys, &uuid::Uuid::new_v4().to_string(), false);
+    let event_id = event.id;
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let ok = author.send_event(event).await.expect("send");
+    assert!(ok.accepted, "ingest rejected: {}", ok.message);
+    author.disconnect().await.expect("disconnect author");
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("ids-unshared");
+    foreign
+        .subscribe(&sid, vec![Filter::new().id(event_id)])
+        .await
+        .expect("subscribe");
+    let events = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert!(
+        events.is_empty(),
+        "ids-lookup of an unshared projection must return nothing, got {:?}",
+        events.iter().map(|e| e.id).collect::<Vec<_>>()
+    );
+
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// COUNT must take the per-event fallback for kind:30178 so the aggregate does
+/// not leak the existence of unshared projections.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_count_excludes_foreign_unshared() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let ok = author
+        .send_event(catalog_event(
+            &author_keys,
+            &uuid::Uuid::new_v4().to_string(),
+            false,
+        ))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared rejected: {}", ok.message);
+    let ok = author
+        .send_event(catalog_event(
+            &author_keys,
+            &uuid::Uuid::new_v4().to_string(),
+            true,
+        ))
+        .await
+        .expect("send shared");
+    assert!(ok.accepted, "shared rejected: {}", ok.message);
+    author.disconnect().await.expect("disconnect author");
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("count");
+    let count_msg = serde_json::json!(["COUNT", sid, author_filter(&author_keys)]);
+    foreign.send_raw(&count_msg).await.expect("send COUNT");
+
+    let count = match foreign.recv_event(Duration::from_secs(5)).await {
+        Ok(RelayMessage::Count { count, .. }) => count,
+        Ok(RelayMessage::Closed { message, .. }) => panic!("COUNT closed unexpectedly: {message}"),
+        Ok(other) => panic!("unexpected relay message for COUNT: {other:?}"),
+        Err(e) => panic!("unexpected error for COUNT: {e}"),
+    };
+    assert_eq!(
+        count, 1,
+        "foreign COUNT must see only the shared projection, got {count}"
+    );
+
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// Live fan-out honours the gate, and unsharing (a NIP-33 replacement that drops
+/// the `shared` tag) retracts the projection from foreign readers.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_live_fanout_and_unshare_retracts() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let d_tag = uuid::Uuid::new_v4().to_string();
+    let now = Timestamp::now().as_secs();
+    let (t0, t1, t2) = (now.saturating_sub(2), now.saturating_sub(1), now);
+
+    // Subscribe BEFORE publishing, scoped to this author so parallel tests
+    // publishing their own 30178s cannot trip the leak assertion.
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("fanout");
+    foreign
+        .subscribe(&sid, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe");
+    let _ = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("drain eose");
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+
+    // Unshared publish must NOT reach the foreign connection.
+    let ok = author
+        .send_event(catalog_event_at(&author_keys, &d_tag, false, t0))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared rejected: {}", ok.message);
+    match foreign.recv_event(Duration::from_millis(750)).await {
+        Err(buzz_test_client::TestClientError::Timeout) => {}
+        Ok(RelayMessage::Event { event, .. }) if event.kind == Kind::Custom(TEAM_CATALOG_KIND) => {
+            panic!("unshared projection leaked to foreign live subscription");
+        }
+        Ok(_) => {}
+        Err(e) => panic!("unexpected error awaiting fan-out: {e}"),
+    }
+
+    // Shared replacement MUST reach it.
+    let shared_event = catalog_event_at(&author_keys, &d_tag, true, t1);
+    let shared_id = shared_event.id;
+    let ok = author.send_event(shared_event).await.expect("send shared");
+    assert!(ok.accepted, "shared rejected: {}", ok.message);
+    let delivered = loop {
+        match foreign.recv_event(Duration::from_secs(5)).await {
+            Ok(RelayMessage::Event { event, .. }) if event.id == shared_id => break true,
+            Ok(_) => continue,
+            Err(buzz_test_client::TestClientError::Timeout) => break false,
+            Err(e) => panic!("unexpected error awaiting shared fan-out: {e}"),
+        }
+    };
+    assert!(
+        delivered,
+        "shared projection must fan out to foreign readers"
+    );
+
+    // Unshare: replace at the same coordinate without the tag. Subsequent
+    // foreign REQs must return nothing.
+    let ok = author
+        .send_event(catalog_event_at(&author_keys, &d_tag, false, t2))
+        .await
+        .expect("send unshare");
+    assert!(ok.accepted, "unshare rejected: {}", ok.message);
+
+    let sid_post = sub_id("post-unshare");
+    foreign
+        .subscribe(&sid_post, vec![coordinate_filter(&author_keys, &d_tag)])
+        .await
+        .expect("subscribe post");
+    let after = foreign
+        .collect_until_eose(&sid_post, Duration::from_secs(5))
+        .await
+        .expect("collect post");
+    assert!(
+        after.is_empty(),
+        "unsharing must retract the projection from foreign readers, got {} event(s)",
+        after.len()
+    );
+
+    author.disconnect().await.expect("disconnect author");
+    foreign.disconnect().await.expect("disconnect foreign");
+}
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/crates/buzz-voice/src/pocket_april.rs b/crates/buzz-voice/src/pocket_april.rs
new file mode 100644
index 0000000000..43826df5c9
--- /dev/null
+++ b/crates/buzz-voice/src/pocket_april.rs
@@ -0,0 +1,940 @@
+//! Native ONNX loader for Pocket TTS `english_2026-04`.
+//!
+//! The bundle uses SentencePiece, prepends a learned BOS voice embedding, and
+//! describes recurrent state tensors in `bundle.json`. This module supplies
+//! that frontend and state loop while reusing the ONNX Runtime linked by the
+//! Desktop speech stack.
+
+use std::borrow::Cow;
+use std::f32::consts::TAU;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use ort::session::{Session, SessionInputValue};
+use ort::value::{DynValue, Tensor};
+use rand::{Rng, RngExt};
+use sentencepiece_model::SentencePieceModel;
+use serde::Deserialize;
+use sherpa_onnx::LinearResampler;
+use tokenizers::models::unigram::Unigram;
+use tokenizers::pre_tokenizers::metaspace::{Metaspace, PrependScheme};
+use tokenizers::Tokenizer;
+
+use super::VoiceStyle;
+
+const FILE_BUNDLE: &str = "bundle.json";
+const FILE_MIMI_ENCODER: &str = "mimi_encoder.onnx";
+const FILE_TEXT_CONDITIONER: &str = "text_conditioner.onnx";
+const FILE_FLOW_MAIN_INT8: &str = "flow_lm_main_int8.onnx";
+const FILE_FLOW_INT8: &str = "flow_lm_flow_int8.onnx";
+const FILE_MIMI_DECODER_INT8: &str = "mimi_decoder_int8.onnx";
+
+const MODEL_LANGUAGE: &str = "english_2026-04";
+const DEFAULT_TEMPERATURE: f32 = 0.7;
+const EOS_LOGIT_THRESHOLD: f32 = -4.0;
+const DECODER_CHUNK_FRAMES: usize = 12;
+const TOKENS_PER_SECOND_ESTIMATE: f32 = 3.0;
+const GENERATION_SECONDS_PADDING: f32 = 2.0;
+
+#[derive(Debug, Deserialize)]
+struct Bundle {
+    schema_version: u32,
+    language: String,
+    sample_rate: usize,
+    frame_rate: f32,
+    samples_per_frame: usize,
+    latent_dim: usize,
+    conditioning_dim: usize,
+    insert_bos_before_voice: bool,
+    pad_with_spaces_for_short_inputs: bool,
+    remove_semicolons: bool,
+    model_recommended_frames_after_eos: Option<usize>,
+    max_token_per_chunk: usize,
+    tokenizer_file: String,
+    bos_before_voice_file: String,
+    flow_lm_state_manifest: Vec<StateSpec>,
+    mimi_state_manifest: Vec<StateSpec>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct StateSpec {
+    input_name: String,
+    output_name: String,
+    dtype: StateDtype,
+    shape: Vec<i64>,
+    fill: StateFill,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "lowercase")]
+enum StateDtype {
+    #[serde(rename = "float32")]
+    Float32,
+    #[serde(rename = "int64")]
+    Int64,
+    Bool,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "lowercase")]
+enum StateFill {
+    Empty,
+    Nan,
+    Ones,
+    Zeros,
+}
+
+struct StateValue {
+    spec: StateSpec,
+    value: DynValue,
+}
+
+struct CachedVoice {
+    samples_ptr: usize,
+    samples_len: usize,
+    sample_rate: i32,
+    embeddings: Vec<f32>,
+}
+
+pub(crate) struct AprilPocketTts {
+    bundle: Bundle,
+    tokenizer: Tokenizer,
+    bos_embedding: Vec<f32>,
+    mimi_encoder: Session,
+    text_conditioner: Session,
+    flow_main: Session,
+    flow: Session,
+    mimi_decoder: Session,
+    cached_voice: Option<CachedVoice>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AprilPreparedPrompt {
+    pub(crate) text: String,
+    pub(crate) frames_after_eos: usize,
+}
+
+pub(crate) fn prepare_april_prompt(input: &str) -> Option<AprilPreparedPrompt> {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    let mut cleaned = String::with_capacity(trimmed.len());
+    let mut last_was_space = false;
+    for ch in trimmed.chars() {
+        if ch.is_whitespace() {
+            if !last_was_space {
+                cleaned.push(' ');
+            }
+            last_was_space = true;
+        } else {
+            cleaned.push(ch);
+            last_was_space = false;
+        }
+    }
+
+    let first = cleaned.chars().next().expect("cleaned non-empty above");
+    if first.is_lowercase() {
+        let upper: String = first.to_uppercase().collect();
+        let mut iter = cleaned.chars();
+        iter.next();
+        cleaned = upper + iter.as_str();
+    }
+
+    let last = cleaned
+        .chars()
+        .next_back()
+        .expect("cleaned non-empty above");
+    if last.is_alphanumeric() {
+        cleaned.push('.');
+    }
+
+    let word_count = cleaned.split_whitespace().count();
+    Some(AprilPreparedPrompt {
+        text: cleaned,
+        // Mirror the bundle's upstream heuristic: three generated frames plus
+        // two trailing frames for short prompts, one plus two otherwise.
+        frames_after_eos: if word_count <= 4 { 5 } else { 3 },
+    })
+}
+
+impl AprilPocketTts {
+    pub(crate) fn load(dir: &Path, num_threads: usize) -> Result<Self, String> {
+        if num_threads == 0 {
+            return Err("Pocket TTS num_threads must be at least 1".to_string());
+        }
+        let bundle_path = dir.join(FILE_BUNDLE);
+        let bundle: Bundle = serde_json::from_slice(
+            &fs::read(&bundle_path)
+                .map_err(|err| format!("read {}: {err}", bundle_path.display()))?,
+        )
+        .map_err(|err| format!("parse {}: {err}", bundle_path.display()))?;
+
+        if bundle.schema_version != 2 {
+            return Err(format!(
+                "unsupported Pocket TTS bundle schema {} in {}",
+                bundle.schema_version,
+                bundle_path.display()
+            ));
+        }
+        if bundle.language != MODEL_LANGUAGE {
+            return Err(format!(
+                "expected Pocket TTS language {MODEL_LANGUAGE}, got {}",
+                bundle.language
+            ));
+        }
+        if bundle.sample_rate != 24_000
+            || bundle.frame_rate != 12.5
+            || bundle.samples_per_frame != 1_920
+            || bundle.latent_dim != 32
+            || bundle.conditioning_dim != 1024
+        {
+            return Err(format!(
+                "unexpected Pocket TTS dimensions: sample_rate={}, frame_rate={}, samples_per_frame={}, latent_dim={}, conditioning_dim={}",
+                bundle.sample_rate,
+                bundle.frame_rate,
+                bundle.samples_per_frame,
+                bundle.latent_dim,
+                bundle.conditioning_dim
+            ));
+        }
+        if !bundle.insert_bos_before_voice {
+            return Err("April Pocket TTS bundle must insert BOS before voice".to_string());
+        }
+        if bundle.pad_with_spaces_for_short_inputs
+            || bundle.remove_semicolons
+            || bundle.model_recommended_frames_after_eos.is_some()
+            || bundle.max_token_per_chunk != 50
+        {
+            return Err("unsupported April Pocket TTS prompt-policy metadata".to_string());
+        }
+
+        let tokenizer_path = dir.join(&bundle.tokenizer_file);
+        let tokenizer = load_tokenizer(&tokenizer_path)?;
+        let bos_path = dir.join(&bundle.bos_before_voice_file);
+        let bos_embedding = read_npy_f32(&bos_path)?;
+        if bos_embedding.len() != bundle.conditioning_dim {
+            return Err(format!(
+                "{} has {} values; expected {}",
+                bos_path.display(),
+                bos_embedding.len(),
+                bundle.conditioning_dim
+            ));
+        }
+
+        let flow_main = FILE_FLOW_MAIN_INT8;
+        let flow = FILE_FLOW_INT8;
+        let mimi_decoder = FILE_MIMI_DECODER_INT8;
+
+        Ok(Self {
+            // The INT8 layout quantizes only the three generation graphs;
+            // voice encoding and text conditioning remain full precision.
+            mimi_encoder: load_session(dir.join(FILE_MIMI_ENCODER), num_threads)?,
+            text_conditioner: load_session(dir.join(FILE_TEXT_CONDITIONER), num_threads)?,
+            flow_main: load_session(dir.join(flow_main), num_threads)?,
+            flow: load_session(dir.join(flow), num_threads)?,
+            mimi_decoder: load_session(dir.join(mimi_decoder), num_threads)?,
+            bundle,
+            tokenizer,
+            bos_embedding,
+            cached_voice: None,
+        })
+    }
+
+    pub(crate) fn split_prompt(
+        &self,
+        prepared: &AprilPreparedPrompt,
+    ) -> Result<Vec<String>, String> {
+        if self.token_count(&prepared.text)? <= self.bundle.max_token_per_chunk {
+            return Ok(vec![prepared.text.clone()]);
+        }
+
+        let mut chunks = Vec::new();
+        let mut current = String::new();
+        for word in prepared.text.split_whitespace() {
+            let candidate = if current.is_empty() {
+                word.to_string()
+            } else {
+                format!("{current} {word}")
+            };
+            if self.prepared_token_count(&candidate)? <= self.bundle.max_token_per_chunk {
+                current = candidate;
+                continue;
+            }
+            if !current.is_empty() {
+                chunks.push(std::mem::take(&mut current));
+            }
+
+            if self.prepared_token_count(word)? <= self.bundle.max_token_per_chunk {
+                current = word.to_string();
+                continue;
+            }
+
+            let mut fragment = String::new();
+            for ch in word.chars() {
+                let candidate = format!("{fragment}{ch}");
+                if !fragment.is_empty()
+                    && self.prepared_token_count(&candidate)? > self.bundle.max_token_per_chunk
+                {
+                    chunks.push(std::mem::take(&mut fragment));
+                }
+                fragment.push(ch);
+            }
+            current = fragment;
+        }
+        if !current.is_empty() {
+            chunks.push(current);
+        }
+
+        chunks
+            .into_iter()
+            .map(|text| {
+                let chunk = prepare_april_prompt(&text)
+                    .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+                let token_count = self.token_count(&chunk.text)?;
+                if token_count > self.bundle.max_token_per_chunk {
+                    return Err(format!(
+                        "Pocket TTS prompt chunk has {token_count} tokens; maximum is {}",
+                        self.bundle.max_token_per_chunk
+                    ));
+                }
+                Ok(chunk.text)
+            })
+            .collect()
+    }
+
+    pub(crate) fn synth_chunk(
+        &mut self,
+        prepared: &AprilPreparedPrompt,
+        style: &VoiceStyle,
+    ) -> Result<Vec<f32>, String> {
+        let voice_embeddings = self.voice_embeddings(style)?;
+        let mut flow_state = self.condition_voice(&voice_embeddings)?;
+        let token_ids = self
+            .tokenizer
+            .encode(prepared.text.as_str(), false)
+            .map_err(|err| format!("tokenize Pocket TTS prompt: {err}"))?
+            .get_ids()
+            .iter()
+            .copied()
+            .map(i64::from)
+            .collect::<Vec<_>>();
+        if token_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        if token_ids.len() > self.bundle.max_token_per_chunk {
+            return Err(format!(
+                "Pocket TTS prompt has {} tokens; split_text_into_chunks maximum is {}",
+                token_ids.len(),
+                self.bundle.max_token_per_chunk
+            ));
+        }
+
+        let token_count = token_ids.len();
+        let text_embeddings = self.text_embeddings(token_ids)?;
+        self.run_flow_main_prefix(&text_embeddings, &mut flow_state)?;
+        let max_frames = estimate_max_frames(token_count, self.bundle.frame_rate);
+        let latents =
+            self.generate_latents(max_frames, prepared.frames_after_eos, &mut flow_state)?;
+        self.decode_latents(&latents)
+    }
+
+    fn prepared_token_count(&self, text: &str) -> Result<usize, String> {
+        let prepared = prepare_april_prompt(text)
+            .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+        self.token_count(&prepared.text)
+    }
+
+    fn token_count(&self, text: &str) -> Result<usize, String> {
+        Ok(self
+            .tokenizer
+            .encode(text, false)
+            .map_err(|err| format!("tokenize Pocket TTS prompt: {err}"))?
+            .get_ids()
+            .len())
+    }
+
+    fn voice_embeddings(&mut self, style: &VoiceStyle) -> Result<Vec<f32>, String> {
+        let key = (
+            style.samples.as_ptr() as usize,
+            style.samples.len(),
+            style.sample_rate,
+        );
+        if let Some(cached) = &self.cached_voice {
+            if (cached.samples_ptr, cached.samples_len, cached.sample_rate) == key {
+                return Ok(cached.embeddings.clone());
+            }
+        }
+
+        let samples = if style.sample_rate == self.bundle.sample_rate as i32 {
+            style.samples.clone()
+        } else {
+            LinearResampler::create(style.sample_rate, self.bundle.sample_rate as i32)
+                .ok_or_else(|| {
+                    format!(
+                        "create Pocket TTS resampler {}Hz -> {}Hz",
+                        style.sample_rate, self.bundle.sample_rate
+                    )
+                })?
+                .resample(&style.samples, true)
+        };
+        let audio = Tensor::from_array((
+            vec![1_i64, 1, samples.len() as i64],
+            samples.into_boxed_slice(),
+        ))
+        .map_err(ort_error("create voice audio tensor"))?;
+        let outputs = self
+            .mimi_encoder
+            .run(ort::inputs!["audio" => audio])
+            .map_err(ort_error("run Mimi encoder"))?;
+        let (_, encoded) = outputs[0]
+            .try_extract_tensor::<f32>()
+            .map_err(ort_error("extract Mimi encoder output"))?;
+        if !encoded.len().is_multiple_of(self.bundle.conditioning_dim) {
+            return Err(format!(
+                "Mimi encoder returned {} values, not divisible by {}",
+                encoded.len(),
+                self.bundle.conditioning_dim
+            ));
+        }
+        let mut embeddings =
+            Vec::with_capacity(self.bos_embedding.len().saturating_add(encoded.len()));
+        embeddings.extend_from_slice(&self.bos_embedding);
+        embeddings.extend_from_slice(encoded);
+        self.cached_voice = Some(CachedVoice {
+            samples_ptr: key.0,
+            samples_len: key.1,
+            sample_rate: key.2,
+            embeddings: embeddings.clone(),
+        });
+        Ok(embeddings)
+    }
+
+    fn condition_voice(&mut self, embeddings: &[f32]) -> Result<Vec<StateValue>, String> {
+        let frames = embeddings.len() / self.bundle.conditioning_dim;
+        let sequence = Tensor::<f32>::new(
+            &ort::memory::Allocator::default(),
+            [1_i64, 0, self.bundle.latent_dim as i64],
+        )
+        .map_err(ort_error("create empty voice sequence"))?;
+        let text_embeddings = Tensor::from_array((
+            vec![1_i64, frames as i64, self.bundle.conditioning_dim as i64],
+            embeddings.to_vec().into_boxed_slice(),
+        ))
+        .map_err(ort_error("create voice embedding tensor"))?;
+        let mut state = initialize_state(&self.bundle.flow_lm_state_manifest)?;
+        let mut inputs = vec![
+            (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+            (
+                Cow::Borrowed("text_embeddings"),
+                SessionInputValue::from(text_embeddings),
+            ),
+        ];
+        append_state_inputs(&mut inputs, &state);
+        let mut outputs = self
+            .flow_main
+            .run(inputs)
+            .map_err(ort_error("condition Pocket TTS voice"))?;
+        replace_state_from_outputs(&mut state, &mut outputs)?;
+        Ok(state)
+    }
+
+    fn text_embeddings(&mut self, token_ids: Vec<i64>) -> Result<Vec<f32>, String> {
+        let tokens = Tensor::from_array((
+            vec![1_i64, token_ids.len() as i64],
+            token_ids.into_boxed_slice(),
+        ))
+        .map_err(ort_error("create token tensor"))?;
+        let outputs = self
+            .text_conditioner
+            .run(ort::inputs!["token_ids" => tokens])
+            .map_err(ort_error("run text conditioner"))?;
+        let (_, embeddings) = outputs[0]
+            .try_extract_tensor::<f32>()
+            .map_err(ort_error("extract text embeddings"))?;
+        Ok(embeddings.to_vec())
+    }
+
+    fn run_flow_main_prefix(
+        &mut self,
+        text_embeddings: &[f32],
+        state: &mut [StateValue],
+    ) -> Result<(), String> {
+        if !text_embeddings
+            .len()
+            .is_multiple_of(self.bundle.conditioning_dim)
+        {
+            return Err(format!(
+                "text conditioner returned {} values, not divisible by {}",
+                text_embeddings.len(),
+                self.bundle.conditioning_dim
+            ));
+        }
+        let frames = text_embeddings.len() / self.bundle.conditioning_dim;
+        let sequence = Tensor::<f32>::new(
+            &ort::memory::Allocator::default(),
+            [1_i64, 0, self.bundle.latent_dim as i64],
+        )
+        .map_err(ort_error("create empty text sequence"))?;
+        let text_embeddings = Tensor::from_array((
+            vec![1_i64, frames as i64, self.bundle.conditioning_dim as i64],
+            text_embeddings.to_vec().into_boxed_slice(),
+        ))
+        .map_err(ort_error("create text embedding tensor"))?;
+        let mut inputs = vec![
+            (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+            (
+                Cow::Borrowed("text_embeddings"),
+                SessionInputValue::from(text_embeddings),
+            ),
+        ];
+        append_state_inputs(&mut inputs, state);
+        let mut outputs = self
+            .flow_main
+            .run(inputs)
+            .map_err(ort_error("prime Pocket TTS text state"))?;
+        replace_state_from_outputs(state, &mut outputs)
+    }
+
+    fn generate_latents(
+        &mut self,
+        max_frames: usize,
+        frames_after_eos: usize,
+        state: &mut [StateValue],
+    ) -> Result<Vec<f32>, String> {
+        let mut current = vec![f32::NAN; self.bundle.latent_dim];
+        let mut latents = Vec::with_capacity(max_frames * self.bundle.latent_dim);
+        let mut eos_step = None;
+        let mut rng = rand::rng();
+
+        for step in 0..max_frames {
+            let sequence = Tensor::from_array((
+                vec![1_i64, 1, self.bundle.latent_dim as i64],
+                current.clone().into_boxed_slice(),
+            ))
+            .map_err(ort_error("create latent input"))?;
+            let text_embeddings = Tensor::<f32>::new(
+                &ort::memory::Allocator::default(),
+                [1_i64, 0, self.bundle.conditioning_dim as i64],
+            )
+            .map_err(ort_error("create empty text input"))?;
+            let mut inputs = vec![
+                (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+                (
+                    Cow::Borrowed("text_embeddings"),
+                    SessionInputValue::from(text_embeddings),
+                ),
+            ];
+            append_state_inputs(&mut inputs, state);
+            let mut outputs = self
+                .flow_main
+                .run(inputs)
+                .map_err(ort_error("run Pocket TTS Flow LM"))?;
+            let conditioning = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Flow LM conditioning"))?
+                .1
+                .to_vec();
+            let eos_logit = outputs[1]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Flow LM EOS logit"))?
+                .1
+                .first()
+                .copied()
+                .ok_or_else(|| "Flow LM returned empty EOS logit".to_string())?;
+            replace_state_from_outputs(state, &mut outputs)?;
+
+            if eos_logit > EOS_LOGIT_THRESHOLD && eos_step.is_none() {
+                eos_step = Some(step);
+            }
+            if eos_step.is_some_and(|eos| step >= eos + frames_after_eos) {
+                break;
+            }
+
+            let mut noise =
+                normal_noise(&mut rng, self.bundle.latent_dim, DEFAULT_TEMPERATURE.sqrt());
+            let conditioning = Tensor::from_array((
+                vec![1_i64, self.bundle.conditioning_dim as i64],
+                conditioning.into_boxed_slice(),
+            ))
+            .map_err(ort_error("create flow conditioning"))?;
+            let s = Tensor::from_array((vec![1_i64, 1], vec![0.0_f32].into_boxed_slice()))
+                .map_err(ort_error("create flow start tensor"))?;
+            let t = Tensor::from_array((vec![1_i64, 1], vec![1.0_f32].into_boxed_slice()))
+                .map_err(ort_error("create flow end tensor"))?;
+            let x = Tensor::from_array((
+                vec![1_i64, self.bundle.latent_dim as i64],
+                noise.clone().into_boxed_slice(),
+            ))
+            .map_err(ort_error("create flow noise tensor"))?;
+            let outputs = self
+                .flow
+                .run(ort::inputs![
+                    "c" => conditioning,
+                    "s" => s,
+                    "t" => t,
+                    "x" => x,
+                ])
+                .map_err(ort_error("run Pocket TTS flow"))?;
+            let flow = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Pocket TTS flow"))?
+                .1;
+            if flow.len() != noise.len() {
+                return Err(format!(
+                    "flow returned {} values; expected {}",
+                    flow.len(),
+                    noise.len()
+                ));
+            }
+            for (sample, delta) in noise.iter_mut().zip(flow) {
+                *sample += *delta;
+            }
+            current.clone_from(&noise);
+            latents.extend_from_slice(&noise);
+        }
+        Ok(latents)
+    }
+
+    fn decode_latents(&mut self, latents: &[f32]) -> Result<Vec<f32>, String> {
+        if latents.is_empty() {
+            return Ok(Vec::new());
+        }
+        if !latents.len().is_multiple_of(self.bundle.latent_dim) {
+            return Err(format!(
+                "latent buffer has {} values, not divisible by {}",
+                latents.len(),
+                self.bundle.latent_dim
+            ));
+        }
+        let frame_count = latents.len() / self.bundle.latent_dim;
+        let mut state = initialize_state(&self.bundle.mimi_state_manifest)?;
+        let mut audio = Vec::new();
+
+        for start in (0..frame_count).step_by(DECODER_CHUNK_FRAMES) {
+            let end = (start + DECODER_CHUNK_FRAMES).min(frame_count);
+            let values =
+                latents[start * self.bundle.latent_dim..end * self.bundle.latent_dim].to_vec();
+            let latent = Tensor::from_array((
+                vec![1_i64, (end - start) as i64, self.bundle.latent_dim as i64],
+                values.into_boxed_slice(),
+            ))
+            .map_err(ort_error("create Mimi latent tensor"))?;
+            let mut inputs = vec![(Cow::Borrowed("latent"), SessionInputValue::from(latent))];
+            append_state_inputs(&mut inputs, &state);
+            let mut outputs = self
+                .mimi_decoder
+                .run(inputs)
+                .map_err(ort_error("run Mimi decoder"))?;
+            let samples = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Mimi audio"))?
+                .1;
+            audio.extend_from_slice(samples);
+            replace_state_from_outputs(&mut state, &mut outputs)?;
+        }
+        Ok(audio)
+    }
+}
+
+fn load_session(path: PathBuf, num_threads: usize) -> Result<Session, String> {
+    if !path.is_file() {
+        return Err(format!("missing Pocket TTS file: {}", path.display()));
+    }
+    Session::builder()
+        .map_err(ort_error("create ONNX session builder"))?
+        .with_intra_threads(num_threads)
+        .map_err(|err| format!("configure ONNX intra-op threads: {err}"))?
+        .with_inter_threads(1)
+        .map_err(|err| format!("configure ONNX inter-op threads: {err}"))?
+        .commit_from_file(&path)
+        .map_err(|err| format!("load {}: {err}", path.display()))
+}
+
+fn load_tokenizer(path: &Path) -> Result<Tokenizer, String> {
+    let sentencepiece = SentencePieceModel::from_file(path)
+        .map_err(|err| format!("load {}: {err}", path.display()))?;
+    let trainer = sentencepiece
+        .trainer()
+        .ok_or_else(|| format!("{} has no SentencePiece trainer metadata", path.display()))?;
+    let normalizer = sentencepiece.normalizer().ok_or_else(|| {
+        format!(
+            "{} has no SentencePiece normalizer metadata",
+            path.display()
+        )
+    })?;
+    if normalizer.name() != "identity" {
+        return Err(format!(
+            "{} uses unsupported SentencePiece normalizer {:?}",
+            path.display(),
+            normalizer.name()
+        ));
+    }
+
+    let vocab = sentencepiece
+        .pieces()
+        .iter()
+        .map(|piece| (piece.piece().to_owned(), f64::from(piece.score())))
+        .collect();
+    let mut tokenizer = Tokenizer::new(
+        Unigram::from(
+            vocab,
+            Some(trainer.unk_id() as usize),
+            trainer.byte_fallback(),
+        )
+        .map_err(|err| format!("construct tokenizer from {}: {err}", path.display()))?,
+    );
+    // SentencePiece's identity normalizer still escapes spaces as U+2581 and
+    // prepends one marker to the input before unigram segmentation.
+    tokenizer.with_pre_tokenizer(Some(Metaspace::new('▁', PrependScheme::Always, false)));
+    Ok(tokenizer)
+}
+
+fn initialize_state(specs: &[StateSpec]) -> Result<Vec<StateValue>, String> {
+    specs
+        .iter()
+        .cloned()
+        .map(|spec| {
+            let len = shape_len(&spec.shape)?;
+            let value = match spec.dtype {
+                StateDtype::Float32 => {
+                    let fill = match spec.fill {
+                        StateFill::Nan => f32::NAN,
+                        StateFill::Empty | StateFill::Zeros => 0.0,
+                        StateFill::Ones => 1.0,
+                    };
+                    if len == 0 {
+                        Tensor::<f32>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty float state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create float state tensor"))?
+                            .into_dyn()
+                    }
+                }
+                StateDtype::Int64 => {
+                    let fill = i64::from(matches!(spec.fill, StateFill::Ones));
+                    if len == 0 {
+                        Tensor::<i64>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty integer state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create integer state tensor"))?
+                            .into_dyn()
+                    }
+                }
+                StateDtype::Bool => {
+                    let fill = matches!(spec.fill, StateFill::Ones);
+                    if len == 0 {
+                        Tensor::<bool>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty bool state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create bool state tensor"))?
+                            .into_dyn()
+                    }
+                }
+            };
+            Ok(StateValue { spec, value })
+        })
+        .collect()
+}
+
+fn append_state_inputs<'a>(
+    inputs: &mut Vec<(Cow<'a, str>, SessionInputValue<'a>)>,
+    state: &'a [StateValue],
+) {
+    for value in state {
+        inputs.push((
+            Cow::Borrowed(value.spec.input_name.as_str()),
+            SessionInputValue::from(&value.value),
+        ));
+    }
+}
+
+fn replace_state_from_outputs(
+    state: &mut [StateValue],
+    outputs: &mut ort::session::SessionOutputs<'_>,
+) -> Result<(), String> {
+    for value in state {
+        value.value = outputs
+            .remove(&value.spec.output_name)
+            .ok_or_else(|| format!("missing state output {}", value.spec.output_name))?;
+    }
+    Ok(())
+}
+
+fn shape_len(shape: &[i64]) -> Result<usize, String> {
+    shape.iter().try_fold(1_usize, |len, &dim| {
+        let dim = usize::try_from(dim).map_err(|_| format!("negative state dimension {dim}"))?;
+        len.checked_mul(dim)
+            .ok_or_else(|| format!("state shape overflows usize: {shape:?}"))
+    })
+}
+
+fn estimate_max_frames(token_count: usize, frame_rate: f32) -> usize {
+    ((token_count as f32 / TOKENS_PER_SECOND_ESTIMATE + GENERATION_SECONDS_PADDING) * frame_rate)
+        .ceil() as usize
+}
+
+fn normal_noise(rng: &mut impl Rng, len: usize, std_dev: f32) -> Vec<f32> {
+    let mut out = Vec::with_capacity(len);
+    while out.len() < len {
+        let u1 = rng.random::<f32>().max(f32::MIN_POSITIVE);
+        let u2 = rng.random::<f32>();
+        let radius = (-2.0_f32 * u1.ln()).sqrt() * std_dev;
+        out.push(radius * (TAU * u2).cos());
+        if out.len() < len {
+            out.push(radius * (TAU * u2).sin());
+        }
+    }
+    out
+}
+
+fn read_npy_f32(path: &Path) -> Result<Vec<f32>, String> {
+    let bytes = fs::read(path).map_err(|err| format!("read {}: {err}", path.display()))?;
+    if bytes.len() < 10 || &bytes[..6] != b"\x93NUMPY" {
+        return Err(format!("{} is not a NumPy array", path.display()));
+    }
+    let major = bytes[6];
+    let header_len_bytes = match major {
+        1 => 2,
+        2 | 3 => 4,
+        _ => {
+            return Err(format!(
+                "unsupported NumPy version {major} in {}",
+                path.display()
+            ))
+        }
+    };
+    let header_start = 8 + header_len_bytes;
+    if bytes.len() < header_start {
+        return Err(format!("truncated NumPy header in {}", path.display()));
+    }
+    let header_len = if header_len_bytes == 2 {
+        u16::from_le_bytes([bytes[8], bytes[9]]) as usize
+    } else {
+        u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]) as usize
+    };
+    let data_start = header_start
+        .checked_add(header_len)
+        .ok_or_else(|| format!("NumPy header overflow in {}", path.display()))?;
+    if data_start > bytes.len() {
+        return Err(format!("truncated NumPy data in {}", path.display()));
+    }
+    let header = std::str::from_utf8(&bytes[header_start..data_start])
+        .map_err(|err| format!("invalid NumPy header in {}: {err}", path.display()))?;
+    if !(header.contains("'descr': '<f4'") || header.contains("\"descr\": \"<f4\""))
+        || header.contains("fortran_order': True")
+        || header.contains("fortran_order\": true")
+    {
+        return Err(format!(
+            "{} must be a little-endian, C-order float32 NumPy array",
+            path.display()
+        ));
+    }
+    let data = &bytes[data_start..];
+    if data.len() % 4 != 0 {
+        return Err(format!("misaligned float32 data in {}", path.display()));
+    }
+    Ok(data
+        .chunks_exact(4)
+        .map(|chunk| f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]))
+        .collect())
+}
+
+fn ort_error(context: &'static str) -> impl FnOnce(ort::Error) -> String {
+    move |err| format!("{context}: {err}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shape_len_supports_empty_state_dimensions() {
+        assert_eq!(shape_len(&[1, 128, 0]).expect("shape"), 0);
+        assert_eq!(shape_len(&[2, 1, 8, 1000, 64]).expect("shape"), 1_024_000);
+    }
+
+    #[test]
+    fn normal_noise_has_requested_length() {
+        let mut rng = rand::rng();
+        assert_eq!(normal_noise(&mut rng, 1, 1.0).len(), 1);
+        assert_eq!(normal_noise(&mut rng, 32, 1.0).len(), 32);
+    }
+
+    #[test]
+    fn generation_frame_estimate_scales_with_token_count() {
+        assert_eq!(estimate_max_frames(3, 12.5), 38);
+        assert_eq!(estimate_max_frames(300, 12.5), 1_275);
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn tokenizer_matches_sentencepiece_reference_including_unknown_words() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let tokenizer =
+            load_tokenizer(&Path::new(&dir).join("tokenizer.model")).expect("load April tokenizer");
+        let cases: &[(&str, &[u32])] = &[
+            ("Yep.", &[2462, 263]),
+            ("Hello there.", &[2994, 310, 263]),
+            (
+                "quizzaciously xyzzy.",
+                &[
+                    260, 1157, 1818, 362, 1814, 323, 260, 568, 327, 1818, 327, 263,
+                ],
+            ),
+            ("I'm listening.", &[268, 264, 283, 260, 604, 273, 263]),
+        ];
+        for (text, expected) in cases {
+            let encoding = tokenizer.encode(*text, false).expect("tokenize");
+            assert_eq!(encoding.get_ids(), *expected, "{text}");
+        }
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn loader_splits_oversized_prompts_at_bundle_token_limit() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let engine = AprilPocketTts::load(Path::new(&dir), 1).expect("load April bundle");
+        let text = "This deliberately long sentence repeats ordinary English words so the exact SentencePiece token limit is exercised without relying on punctuation, and it keeps adding more material until the prompt must be divided into multiple independently safe generation chunks before the recurrent state cache can be exhausted.";
+        let prepared = prepare_april_prompt(text).expect("prepare prompt");
+        let chunks = engine.split_prompt(&prepared).expect("split prompt");
+
+        assert!(chunks.len() > 1);
+        assert!(chunks.iter().all(|chunk| {
+            engine.token_count(chunk).expect("tokenize chunk") <= engine.bundle.max_token_per_chunk
+        }));
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn gary_provost_long_sentence_respects_bundle_token_limit() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let engine = AprilPocketTts::load(Path::new(&dir), 1).expect("load April bundle");
+        let text = "And sometimes, when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is important.";
+        let prepared = prepare_april_prompt(text).expect("prepare prompt");
+        let chunks = engine.split_prompt(&prepared).expect("split long sentence");
+        let token_counts: Vec<_> = chunks
+            .iter()
+            .map(|chunk| engine.token_count(chunk).expect("count tokens"))
+            .collect();
+
+        assert_eq!(
+            chunks,
+            [
+                "And sometimes, when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the.",
+                "Impetus of a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is important.",
+            ]
+        );
+        assert_eq!(token_counts, [48, 44]);
+    }
+}
diff --git a/crates/buzz-voice/src/pocket_models.rs b/crates/buzz-voice/src/pocket_models.rs
new file mode 100644
index 0000000000..ba3f92849c
--- /dev/null
+++ b/crates/buzz-voice/src/pocket_models.rs
@@ -0,0 +1,137 @@
+//! Immutable capabilities for Buzz Desktop's April Pocket TTS bundle.
+
+/// Pinned upstream export repository.
+pub const APRIL_MODEL_ID: &str = "KevinAHM/pocket-tts-onnx";
+
+/// Pinned revision containing the `english_2026-04` bundle.
+pub const APRIL_MODEL_REVISION: &str = "58a6d00cf13d239b6748cb0769f35c580a8f606c";
+
+/// Language bundle selected from the pinned export.
+pub const APRIL_BUNDLE_ID: &str = "english_2026-04";
+
+/// Maximum input size declared by the April bundle.
+pub const APRIL_MAX_TOKEN_PER_CHUNK: usize = 50;
+
+/// One immutable artifact required by the April INT8 runtime.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PocketModelArtifact {
+    pub filename: &'static str,
+    pub sha256: &'static str,
+    pub size_bytes: u64,
+    pub quantized: bool,
+}
+
+/// 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],
+}
+
+const INT8_ARTIFACTS: [PocketModelArtifact; 8] = [
+    PocketModelArtifact {
+        filename: "bundle.json",
+        sha256: "bab643150f437f37df080a710520ff39ed9ebd9a339f8ebdc739f7eddfc28b3f",
+        size_bytes: 24_381,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "bos_before_voice.npy",
+        sha256: "f46edf4f7007b7ba4ea58831f49d003e59e167b4641c44bb3addfe9231a780b1",
+        size_bytes: 4_224,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "tokenizer.model",
+        sha256: "d461765ae179566678c93091c5fa6f2984c31bbe990bf1aa62d92c64d91bc3f6",
+        size_bytes: 59_339,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "flow_lm_main_int8.onnx",
+        sha256: "f9bd8106b79a0192c1c43399ab938fb24900a95c1c599870d75a884e99000116",
+        size_bytes: 76_341_079,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "flow_lm_flow_int8.onnx",
+        sha256: "3dd781ee5abee9e195320bf0106bebd6372a852b3b36352524ee78b40554635d",
+        size_bytes: 9_962_530,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "mimi_decoder_int8.onnx",
+        sha256: "3630450a3297a101792a6ac66619ebc70ab916b265e6220c2afaef8b1673f925",
+        size_bytes: 22_684_077,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "mimi_encoder.onnx",
+        sha256: "853e2ca623b8782d94c3745ec6133bfdff7ce33d9b11128bd29ea03f28d76e3d",
+        size_bytes: 39_768_446,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "text_conditioner.onnx",
+        sha256: "4ecee995fb69f85c7a7493d11f7b5ee15d9950facc7ab3f5c9c49ef1e03847bb",
+        size_bytes: 16_388_344,
+        quantized: false,
+    },
+];
+
+const INT8_COMPONENTS: [&str; 3] = ["flow_lm_main", "flow_lm_flow", "mimi_decoder"];
+
+/// Return immutable metadata for Buzz Desktop's April INT8 model.
+pub const fn april_model_info() -> PocketModelInfo {
+    PocketModelInfo {
+        bundle_id: APRIL_BUNDLE_ID,
+        source_model_id: APRIL_MODEL_ID,
+        revision: APRIL_MODEL_REVISION,
+        sample_rate: 24_000,
+        max_token_per_chunk: APRIL_MAX_TOKEN_PER_CHUNK,
+        artifacts: &INT8_ARTIFACTS,
+        quantized_components: &INT8_COMPONENTS,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn metadata_matches_pinned_int8_layout() {
+        let info = april_model_info();
+        assert_eq!(info.artifacts.len(), 8);
+        assert_eq!(
+            info.quantized_components,
+            ["flow_lm_main", "flow_lm_flow", "mimi_decoder"]
+        );
+        assert_eq!(
+            info.artifacts
+                .iter()
+                .map(|artifact| artifact.size_bytes)
+                .sum::<u64>(),
+            165_232_420
+        );
+        assert!(info
+            .artifacts
+            .iter()
+            .any(|artifact| { artifact.filename == "mimi_encoder.onnx" && !artifact.quantized }));
+        assert!(!info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "mimi_encoder_int8.onnx"));
+    }
+}
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/executor.rs b/crates/buzz-workflow/src/executor.rs
index e30541377e..17ede09804 100644
--- a/crates/buzz-workflow/src/executor.rs
+++ b/crates/buzz-workflow/src/executor.rs
@@ -509,6 +509,80 @@ fn resolve_send_message_channel(
     Ok(trigger_channel.trim().to_string())
 }
 
+/// Re-check a channel workflow owner's membership before an outbound webhook.
+///
+/// Workflow definitions outlive the event that created them. Without this
+/// check, removing a member from a private channel would not stop a workflow
+/// they created from sending future message contents to an external endpoint.
+/// The DB read is intentionally done at action time instead of relying on the
+/// relay membership cache so a completed removal takes effect before the next
+/// outbound request.
+async fn revalidate_webhook_owner_membership(
+    engine: &WorkflowEngine,
+    community_id: CommunityId,
+    run_id: Uuid,
+) -> Result<(), WorkflowError> {
+    let wf_run = engine
+        .db
+        .get_workflow_run(community_id, run_id)
+        .await
+        .map_err(|e| {
+            WorkflowError::WebhookError(format!(
+                "CallWebhook: failed to load workflow run {run_id}: {e}"
+            ))
+        })?;
+    let workflow = engine
+        .db
+        .get_workflow(community_id, wf_run.workflow_id)
+        .await
+        .map_err(|e| {
+            WorkflowError::WebhookError(format!(
+                "CallWebhook: failed to load workflow {}: {e}",
+                wf_run.workflow_id
+            ))
+        })?;
+
+    let Some(channel_id) = workflow.channel_id else {
+        return Ok(());
+    };
+
+    let owner_is_member = engine
+        .db
+        .is_member(community_id, channel_id, &workflow.owner_pubkey)
+        .await
+        .map_err(|e| {
+            WorkflowError::WebhookError(format!(
+                "CallWebhook: failed to re-check workflow owner membership: {e}"
+            ))
+        })?;
+
+    if owner_is_member {
+        return Ok(());
+    }
+
+    if let Err(e) = engine
+        .db
+        .set_workflow_enabled(community_id, workflow.id, false)
+        .await
+    {
+        warn!(
+            workflow_id = %workflow.id,
+            channel_id = %channel_id,
+            "CallWebhook: failed to disable workflow after owner membership loss: {e}"
+        );
+    } else {
+        info!(
+            workflow_id = %workflow.id,
+            channel_id = %channel_id,
+            "CallWebhook: disabled workflow after owner membership loss"
+        );
+    }
+
+    Err(WorkflowError::WebhookError(format!(
+        "CallWebhook: workflow owner is no longer a member of channel {channel_id}"
+    )))
+}
+
 /// Dispatch a resolved action and return its output.
 ///
 /// For MVP, most actions log their intent and return a success output.
@@ -622,6 +696,8 @@ pub async fn dispatch_action(
             headers,
             body,
         } => {
+            revalidate_webhook_owner_membership(engine, community_id, run_id).await?;
+
             let method_str = method.as_deref().unwrap_or("POST");
             info!(run_id = %run_id, step = step_id, "CallWebhook → {method_str} {url}");
 
@@ -1219,6 +1295,9 @@ async fn execute_steps(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use buzz_db::channel::{ChannelType, ChannelVisibility, MemberRole};
+    use buzz_db::{Db, DbConfig};
+    use nostr::Keys;
     use serde_json::json;
 
     fn make_trigger() -> TriggerContext {
@@ -1834,4 +1913,130 @@ mod tests {
                 .expect("override should be accepted");
         assert_eq!(resolved, override_channel_id.to_string());
     }
+
+    async fn setup_webhook_membership_test(
+    ) -> (WorkflowEngine, CommunityId, Uuid, Uuid, Vec<u8>, Vec<u8>) {
+        let database_url = std::env::var("BUZZ_TEST_DATABASE_URL")
+            .or_else(|_| std::env::var("DATABASE_URL"))
+            .unwrap_or_else(|_| "postgres://buzz:buzz_dev@localhost:5432/buzz".to_owned());
+        let db = Db::new(&DbConfig {
+            database_url,
+            min_connections: 0,
+            ..DbConfig::default()
+        })
+        .await
+        .expect("connect to test DB");
+        db.migrate().await.expect("run migrations");
+
+        let community = db
+            .ensure_configured_community(&format!(
+                "workflow-webhook-membership-{}.example",
+                Uuid::new_v4().simple()
+            ))
+            .await
+            .expect("create test community")
+            .id;
+        let channel_owner = Keys::generate().public_key().to_bytes().to_vec();
+        let workflow_owner = Keys::generate().public_key().to_bytes().to_vec();
+        db.ensure_user(community, &channel_owner)
+            .await
+            .expect("create channel owner");
+        db.ensure_user(community, &workflow_owner)
+            .await
+            .expect("create workflow owner");
+
+        let channel = db
+            .create_channel(
+                community,
+                "workflow-webhook-membership",
+                ChannelType::Stream,
+                ChannelVisibility::Private,
+                None,
+                &channel_owner,
+                None,
+            )
+            .await
+            .expect("create channel");
+        db.add_member(
+            community,
+            channel.id,
+            &workflow_owner,
+            MemberRole::Member,
+            Some(&channel_owner),
+        )
+        .await
+        .expect("add workflow owner");
+
+        let workflow_id = db
+            .create_workflow(
+                community,
+                Some(channel.id),
+                &workflow_owner,
+                "webhook-membership-test",
+                r#"{"trigger":{"on":"message_posted"},"steps":[]}"#,
+                &[0u8; 32],
+            )
+            .await
+            .expect("create workflow");
+        let run_id = db
+            .create_workflow_run(community, workflow_id, None, None)
+            .await
+            .expect("create workflow run");
+
+        (
+            WorkflowEngine::new(db, crate::WorkflowConfig::default()),
+            community,
+            channel.id,
+            run_id,
+            channel_owner,
+            workflow_owner,
+        )
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn webhook_owner_membership_revalidation_allows_current_member() {
+        let (engine, community, _channel_id, run_id, _channel_owner, _workflow_owner) =
+            setup_webhook_membership_test().await;
+
+        revalidate_webhook_owner_membership(&engine, community, run_id)
+            .await
+            .expect("current member should keep webhook access");
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn webhook_owner_membership_revalidation_disables_removed_owner() {
+        let (engine, community, channel_id, run_id, channel_owner, workflow_owner) =
+            setup_webhook_membership_test().await;
+        engine
+            .db
+            .remove_member(community, channel_id, &workflow_owner, &channel_owner)
+            .await
+            .expect("remove workflow owner");
+
+        let err = revalidate_webhook_owner_membership(&engine, community, run_id)
+            .await
+            .expect_err("removed owner must not keep webhook access");
+        assert!(
+            err.to_string().contains("no longer a member"),
+            "unexpected error: {err}"
+        );
+
+        let workflow_id = engine
+            .db
+            .get_workflow_run(community, run_id)
+            .await
+            .expect("load run")
+            .workflow_id;
+        let workflow = engine
+            .db
+            .get_workflow(community, workflow_id)
+            .await
+            .expect("load workflow");
+        assert!(
+            !workflow.enabled,
+            "workflow should be disabled after owner removal"
+        );
+    }
 }
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/desktop/package.json b/desktop/package.json
index 2226a0cb12..e8145f5468 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "buzz",
   "private": true,
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "scripts": {
     "dev": "vite",
diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index c79ef1bf9d..7ce7f48389 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -49,6 +49,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 +96,7 @@ export default defineConfig({
         "**/cold-switch-longtask.perf.ts",
         "**/timeline-no-shift.spec.ts",
         "**/human-edit-agent-content.spec.ts",
+        "**/empty-edit-delete.spec.ts",
         "**/reaction-order.spec.ts",
         "**/reaction-names.spec.ts",
         "**/inbox-reactions.spec.ts",
@@ -119,6 +121,7 @@ export default defineConfig({
         "**/nostr-bind.spec.ts",
         "**/mobile-pairing-qr.spec.ts",
         "**/profile-nsec-reveal.spec.ts",
+        "**/profile-backup-settings.spec.ts",
         "**/signout-confirmation.spec.ts",
         "**/agent-provider-dropdowns.spec.ts",
         "**/agent-lifecycle-feedback.spec.ts",
@@ -129,6 +132,7 @@ export default defineConfig({
         "**/harness-management.spec.ts",
         "**/harness-catalog-screenshots.spec.ts",
         "**/inline-custom-harness.spec.ts",
+        "**/huddle-transcription.spec.ts",
       ],
       use: {
         ...devices["Desktop Chrome"],
diff --git a/desktop/public/harness-logos/CREDITS.md b/desktop/public/harness-logos/CREDITS.md
index de4e003c3f..716c43e1ae 100644
--- a/desktop/public/harness-logos/CREDITS.md
+++ b/desktop/public/harness-logos/CREDITS.md
@@ -9,6 +9,7 @@ license permits redistribution.
 
 | File | Upstream | Commit | License | Source path | Modifications |
 |---|---|---|---|---|---|
+| `devin.svg` | [Cognition Devin documentation](https://docs.devin.ai/cli) | Retrieved 2026-07-27 | Cognition trademark; nominative use to identify the Devin harness | Official documentation `logo/favicon.svg` | Added the official black mark to a white square canvas so it remains legible in both app themes |
 | `hermes.png` | [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) | `6ad632b` | MIT © 2025 Nous Research | `website/static/img/logo.png` | Cropped the baked-in border frame, padded to square, resized to 64×64, quantised to a 16-colour palette |
 | `openclaw.svg` | [openclaw/openclaw](https://github.com/openclaw/openclaw) | `b06f40a` | MIT © 2026 OpenClaw Foundation | `ui/public/favicon.svg` | Removed the SMIL animation elements (renders the upstream rest pose statically — verified pixel-identical to the upstream frame at t=0); minified paths |
 | `omp.svg` | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) | `667111575ebba136dadfd6989379e7f67e0d40d9` | MIT © 2025 Mario Zechner; © 2025–2026 Can Bölük | `assets/icon.svg` | None |
diff --git a/desktop/public/harness-logos/devin.svg b/desktop/public/harness-logos/devin.svg
new file mode 100644
index 0000000000..e760797d68
--- /dev/null
+++ b/desktop/public/harness-logos/devin.svg
@@ -0,0 +1,4 @@
+<svg width="425" height="425" viewBox="0 0 425 425" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="425" height="425" fill="white"/>
+  <path d="M70 159.333V91.3471C70 88.3592 71.594 85.5983 74.1816 84.1044L133.043 50.1205C135.631 48.6265 138.819 48.6265 141.407 50.1205L200.269 84.1044C202.856 85.5983 204.45 88.3592 204.45 91.3471V126.068C204.708 137.606 210.806 148.734 221.531 154.926C232.256 161.117 244.942 160.834 255.063 155.289L285.132 137.929C287.719 136.435 290.907 136.435 293.495 137.929L352.357 171.913C354.944 173.406 356.538 176.167 356.538 179.155V247.123C356.538 250.111 354.944 252.872 352.357 254.366L293.495 288.35C290.907 289.844 287.719 289.844 285.132 288.35L255.306 271.13C245.146 265.456 232.344 265.117 221.534 271.358C210.809 277.55 204.711 288.678 204.453 300.215V334.926C204.453 337.914 202.859 340.675 200.271 342.169L141.41 376.153C138.822 377.647 135.634 377.647 133.046 376.153L74.1845 342.169C71.5969 340.675 70.0028 337.914 70.0028 334.926V266.959C70.0029 263.971 71.5969 261.21 74.1845 259.716L133.046 225.732C135.634 224.238 138.822 224.238 141.41 225.732L171.547 243.132C181.656 248.638 194.306 248.906 205.005 242.729C215.815 236.488 221.922 225.231 222.088 213.595C221.83 202.057 215.732 189.737 205.008 183.545C194.283 177.353 181.597 177.636 171.476 183.181L141.269 200.72C138.67 202.229 135.461 202.228 132.864 200.716L74.1576 166.562C71.5835 165.065 70 162.311 70 159.333Z" fill="black"/>
+</svg>
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/scripts/texture-card/generate-card-texture.mjs b/desktop/scripts/texture-card/generate-card-texture.mjs
index 75cc24e744..57ebc61a9b 100644
--- a/desktop/scripts/texture-card/generate-card-texture.mjs
+++ b/desktop/scripts/texture-card/generate-card-texture.mjs
@@ -12,83 +12,116 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const OUTPUT = path.resolve(
-  HERE,
-  "../../src/shared/ui/assets/card-texture.png",
-);
-
-// CSS-pixel source geometry. Screenshotting at DPR 2 produces a crisp asset.
-const CARD_SIZE = 640;
-const OUTSET = 96;
-const CAPTURE_SIZE = CARD_SIZE + OUTSET * 2;
+const OUTPUT_DIRECTORY = path.resolve(HERE, "../../src/shared/ui/assets");
 const DPR = 2;
 
 // Approved texture parameters, archived from the former runtime SVG filter.
-const BLUR = 66;
-const DILATE = Math.round(BLUR * 0.85);
 const THRESHOLD_BIAS = 0.302;
 const SLOPE = 8;
 const FREQUENCY = 0.999;
 const OCTAVES = 3;
 const SEED = 5315;
 
-await mkdir(path.dirname(OUTPUT), { recursive: true });
+const TEXTURES = [
+  {
+    filename: "card-texture.png",
+    color: "white",
+    cardSize: 640,
+    outset: 96,
+    blur: 66,
+    innerBand: 112,
+  },
+  {
+    filename: "card-texture-dark.png",
+    color: "#171b21",
+    cardSize: 640,
+    outset: 96,
+    blur: 66,
+    innerBand: 112,
+  },
+  {
+    filename: "card-texture-compact.png",
+    color: "white",
+    cardSize: 320,
+    outset: 24,
+    blur: 24,
+    innerBand: 44,
+  },
+  {
+    filename: "card-texture-dark-compact.png",
+    color: "#171b21",
+    cardSize: 320,
+    outset: 24,
+    blur: 24,
+    innerBand: 44,
+  },
+];
+
+await mkdir(OUTPUT_DIRECTORY, { recursive: true });
 
 const browser = await chromium.launch();
 try {
-  const page = await browser.newPage({
-    deviceScaleFactor: DPR,
-    viewport: { height: CAPTURE_SIZE, width: CAPTURE_SIZE },
-  });
+  for (const texture of TEXTURES) {
+    const captureSize = texture.cardSize + texture.outset * 2;
+    const dilate = Math.round(texture.blur * 0.85);
+    const output = path.join(OUTPUT_DIRECTORY, texture.filename);
+    const page = await browser.newPage({
+      deviceScaleFactor: DPR,
+      viewport: { height: captureSize, width: captureSize },
+    });
 
-  await page.setContent(`<!doctype html>
-    <style>
-      html, body { margin: 0; width: 100%; height: 100%; background: transparent; }
-      #stage { position: relative; width: ${CAPTURE_SIZE}px; height: ${CAPTURE_SIZE}px; }
-      #core {
-        position: absolute;
-        inset: ${OUTSET + BLUR / 2}px;
-        background: white;
-        filter: blur(${BLUR / 3}px);
-      }
-    </style>
-    <div id="stage">
-      <svg width="${CAPTURE_SIZE}" height="${CAPTURE_SIZE}" aria-hidden="true">
-        <defs>
-          <filter id="texture" x="0" y="0" width="100%" height="100%"
-                  filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
-            <feMorphology in="SourceAlpha" operator="dilate" radius="${DILATE}" result="squared" />
-            <feGaussianBlur in="squared" stdDeviation="${BLUR}" result="ramp" />
-            <feTurbulence type="fractalNoise" baseFrequency="${FREQUENCY}"
-                          numOctaves="${OCTAVES}" seed="${SEED}" result="grain" />
-            <feColorMatrix in="grain" result="grainAlpha" type="matrix"
-              values="0 0 0 0 0
-                      0 0 0 0 0
-                      0 0 0 0 0
-                      1 0 0 0 0" />
-            <feComposite in="ramp" in2="grainAlpha" operator="arithmetic"
-                         k1="0" k2="1" k3="-1" k4="${-THRESHOLD_BIAS}" result="dithered" />
-            <feComponentTransfer in="dithered" result="specks">
-              <feFuncA type="linear" slope="${SLOPE}" intercept="0" />
-            </feComponentTransfer>
-            <feFlood flood-color="white" result="white" />
-            <feComposite in="white" in2="specks" operator="in" />
-          </filter>
-        </defs>
-        <rect x="${OUTSET}" y="${OUTSET}" width="${CARD_SIZE}" height="${CARD_SIZE}"
-              fill="white" filter="url(#texture)" />
-      </svg>
-      <span id="core"></span>
-    </div>`);
+    await page.setContent(`<!doctype html>
+      <style>
+        html, body { margin: 0; width: 100%; height: 100%; background: transparent; }
+        #stage { position: relative; width: ${captureSize}px; height: ${captureSize}px; }
+        #core {
+          position: absolute;
+          inset: ${texture.outset + texture.blur / 2}px;
+          background: ${texture.color};
+          filter: blur(${texture.blur / 3}px);
+        }
+      </style>
+      <div id="stage">
+        <svg width="${captureSize}" height="${captureSize}" aria-hidden="true">
+          <defs>
+            <filter id="texture" x="0" y="0" width="100%" height="100%"
+                    filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+              <feMorphology in="SourceAlpha" operator="dilate" radius="${dilate}" result="squared" />
+              <feGaussianBlur in="squared" stdDeviation="${texture.blur}" result="ramp" />
+              <feTurbulence type="fractalNoise" baseFrequency="${FREQUENCY}"
+                            numOctaves="${OCTAVES}" seed="${SEED}" result="grain" />
+              <feColorMatrix in="grain" result="grainAlpha" type="matrix"
+                values="0 0 0 0 0
+                        0 0 0 0 0
+                        0 0 0 0 0
+                        1 0 0 0 0" />
+              <feComposite in="ramp" in2="grainAlpha" operator="arithmetic"
+                           k1="0" k2="1" k3="-1" k4="${-THRESHOLD_BIAS}" result="dithered" />
+              <feComponentTransfer in="dithered" result="specks">
+                <feFuncA type="linear" slope="${SLOPE}" intercept="0" />
+              </feComponentTransfer>
+              <feFlood flood-color="${texture.color}" result="surfaceColor" />
+              <feComposite in="surfaceColor" in2="specks" operator="in" />
+            </filter>
+          </defs>
+          <rect x="${texture.outset}" y="${texture.outset}" width="${texture.cardSize}" height="${texture.cardSize}"
+                fill="${texture.color}" filter="url(#texture)" />
+        </svg>
+        <span id="core"></span>
+      </div>`);
 
-  await page.locator("#stage").screenshot({
-    omitBackground: true,
-    path: OUTPUT,
-  });
+    await page.locator("#stage").screenshot({
+      omitBackground: true,
+      path: output,
+    });
+    await page.close();
+
+    console.log(`Generated ${output}`);
+    console.log(`Asset: ${captureSize * DPR}×${captureSize * DPR}px @${DPR}x`);
+    console.log(
+      `Runtime slice: ${(texture.outset + texture.innerBand) * DPR}px; outset: ${texture.outset}px`,
+    );
+  }
 } finally {
   await browser.close();
 }
-
-console.log(`Generated ${OUTPUT}`);
-console.log(`Asset: ${CAPTURE_SIZE * DPR}×${CAPTURE_SIZE * DPR}px @${DPR}x`);
-console.log(`Runtime slice: ${(OUTSET + 112) * DPR}px; outset: ${OUTSET}px`);
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index cd0fabb69f..00d3fba3b5 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -84,6 +84,7 @@ dependencies = [
  "cfg-if 1.0.4",
  "getrandom 0.3.4",
  "once_cell",
+ "serde",
  "version_check",
  "zerocopy",
 ]
@@ -707,6 +708,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.21.7"
@@ -731,6 +738,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"
@@ -1023,7 +1036,7 @@ dependencies = [
 
 [[package]]
 name = "buzz-desktop"
-version = "0.5.2"
+version = "0.5.3"
 dependencies = [
  "anyhow",
  "arboard",
@@ -1036,6 +1049,7 @@ dependencies = [
  "buzz-media",
  "buzz-persona",
  "buzz-sdk",
+ "buzz-voice",
  "bytes",
  "bzip2 0.6.1",
  "chrono",
@@ -1045,6 +1059,7 @@ dependencies = [
  "ed25519-dalek",
  "flate2",
  "futures-util",
+ "getrandom 0.2.17",
  "hex",
  "image",
  "infer",
@@ -1159,6 +1174,24 @@ dependencies = [
  "uuid",
 ]
 
+[[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"
@@ -1561,6 +1594,7 @@ dependencies = [
  "itoa",
  "rustversion",
  "ryu",
+ "serde",
  "static_assertions",
 ]
 
@@ -1812,6 +1846,16 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "crossbeam-epoch"
 version = "0.9.20"
@@ -2136,6 +2180,15 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "dary_heap"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "dasp_sample"
 version = "0.11.0"
@@ -2633,6 +2686,12 @@ version = "3.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dea2df4cf52843e0452895c455a1a2cfbb842a1e7329671acf418fdc53ed4c59"
 
+[[package]]
+name = "esaxx-rs"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6"
+
 [[package]]
 name = "euclid"
 version = "0.22.14"
@@ -2691,6 +2750,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"
@@ -4762,6 +4832,39 @@ version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
+[[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.118",
+]
+
+[[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"
@@ -4871,6 +4974,22 @@ dependencies = [
  "libc",
 ]
 
+[[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 = "markup5ever"
 version = "0.38.0"
@@ -4897,6 +5016,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"
@@ -4996,7 +5125,7 @@ dependencies = [
  "mesh-llm-types",
  "model-artifact",
  "nostr-sdk",
- "prost",
+ "prost 0.14.4",
  "rand 0.10.2",
  "rustls",
  "serde",
@@ -5134,7 +5263,7 @@ dependencies = [
  "opentelemetry",
  "opentelemetry-otlp",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "rand 0.10.2",
  "regex-lite",
  "reqwest 0.12.28",
@@ -5223,8 +5352,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.4",
+ "prost-build 0.14.4",
  "protoc-bin-vendored",
  "rmcp",
  "schemars 1.2.1",
@@ -5260,7 +5389,7 @@ dependencies = [
  "anyhow",
  "hex",
  "iroh",
- "prost",
+ "prost 0.14.4",
  "serde_json",
  "sha2 0.10.9",
 ]
@@ -5375,6 +5504,28 @@ dependencies = [
  "tracing",
 ]
 
+[[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.118",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -5520,6 +5671,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.118",
+]
+
 [[package]]
 name = "more-asserts"
 version = "0.3.1"
@@ -5647,6 +5820,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"
 version = "0.9.0"
@@ -6148,7 +6336,7 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
 dependencies = [
- "proc-macro-crate 2.0.2",
+ "proc-macro-crate 3.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.118",
@@ -6628,7 +6816,7 @@ dependencies = [
  "opentelemetry-http",
  "opentelemetry-proto",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "reqwest 0.12.28",
  "thiserror 2.0.18",
 ]
@@ -6643,7 +6831,7 @@ dependencies = [
  "const-hex",
  "opentelemetry",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "serde",
  "serde_json",
  "tonic",
@@ -6709,6 +6897,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_pipe"
 version = "1.2.3"
@@ -6936,6 +7142,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 2.14.0",
+]
+
 [[package]]
 name = "petgraph"
 version = "0.8.3"
@@ -7200,6 +7416,15 @@ 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"
@@ -7410,6 +7635,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.4"
@@ -7417,7 +7652,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "528ac67416ff8646872a3c02cad9cc4ee5dc9f9540c9b10771855c95cb2e5ae1"
 dependencies = [
  "bytes",
- "prost-derive",
+ "prost-derive 0.14.4",
+]
+
+[[package]]
+name = "prost-build"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be769465445e8c1474e9c5dac2018218498557af32d9ed057325ec9a41ae81bf"
+dependencies = [
+ "heck 0.5.0",
+ "itertools",
+ "log",
+ "multimap",
+ "once_cell",
+ "petgraph 0.7.1",
+ "prettyplease",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+ "regex",
+ "syn 2.0.118",
+ "tempfile",
 ]
 
 [[package]]
@@ -7430,15 +7685,28 @@ dependencies = [
  "itertools",
  "log",
  "multimap",
- "petgraph",
+ "petgraph 0.8.3",
  "prettyplease",
- "prost",
- "prost-types",
+ "prost 0.14.4",
+ "prost-types 0.14.4",
  "regex",
  "syn 2.0.118",
  "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.118",
+]
+
 [[package]]
 name = "prost-derive"
 version = "0.14.4"
@@ -7452,13 +7720,35 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[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.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f94967dc7688f3054c7fac87473ffae4cc4c3904800e2d9f5b857246d8963b0a"
 dependencies = [
- "prost",
+ "prost 0.14.4",
 ]
 
 [[package]]
@@ -7525,6 +7815,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 = "pxfm"
 version = "0.1.30"
@@ -7773,7 +8090,7 @@ dependencies = [
  "thiserror 2.0.18",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7836,7 +8153,7 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7845,6 +8162,43 @@ version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
 
+[[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 = "realfft"
 version = "3.5.0"
@@ -8657,6 +9011,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"
@@ -9089,8 +9455,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.4",
+ "prost-build 0.14.4",
  "protoc-bin-vendored",
  "serde",
 ]
@@ -9270,6 +9636,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 7.1.3",
+ "serde",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "sse-stream"
 version = "0.2.4"
@@ -9404,6 +9782,7 @@ dependencies = [
  "symphonia-bundle-flac",
  "symphonia-bundle-mp3",
  "symphonia-codec-aac",
+ "symphonia-codec-alac",
  "symphonia-codec-pcm",
  "symphonia-codec-vorbis",
  "symphonia-core",
@@ -9448,6 +9827,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"
@@ -9651,7 +10040,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]]
@@ -10226,7 +10615,7 @@ dependencies = [
  "anyhow",
  "base64 0.22.1",
  "bitflags 2.13.0",
- "fancy-regex",
+ "fancy-regex 0.11.0",
  "filedescriptor",
  "finl_unicode",
  "fixedbitset 0.4.2",
@@ -10389,6 +10778,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"
@@ -10722,7 +11144,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
- "prost",
+ "prost 0.14.4",
  "tonic",
 ]
 
@@ -10903,7 +11325,7 @@ checksum = "b8765b90061cba6c22b5831f675da109ae5561588290f9fa2317adab2714d5a6"
 dependencies = [
  "memchr",
  "nom 8.0.0",
- "petgraph",
+ "petgraph 0.8.3",
 ]
 
 [[package]]
@@ -11074,6 +11496,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-segmentation"
 version = "1.13.3"
@@ -11088,9 +11519,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"
@@ -11103,6 +11540,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"
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index 735a45c3b7..b80684f955 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -2,7 +2,7 @@
 
 [package]
 name = "buzz-desktop"
-version = "0.5.2"
+version = "0.5.3"
 description = "Buzz desktop app"
 authors = ["you"]
 edition = "2021"
@@ -86,7 +86,10 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_yaml = "0.9"
 toml = "0.8"
-nostr = { version = "0.44", features = ["nip44"] }
+nostr = { version = "0.44", features = ["nip44", "nip49"] }
+# OS-entropy source for backup passphrase generation (already in the tree as a
+# transitive dependency; pinned here for direct use).
+getrandom = "0.2"
 zeroize = "1"
 reqwest = { version = "0.13", features = ["json", "query", "stream", "blocking"] }
 rustls = { version = "0.23", default-features = false, features = ["aws_lc_rs", "std"] }
@@ -95,6 +98,7 @@ 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" }
 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 }
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/examples/pocket_bench.rs b/desktop/src-tauri/examples/pocket_bench.rs
deleted file mode 100644
index b4f5635a95..0000000000
--- a/desktop/src-tauri/examples/pocket_bench.rs
+++ /dev/null
@@ -1,116 +0,0 @@
-//! Cold-vs-warm latency bench for Pocket TTS.
-//!
-//! This duplicates the small config-building snippet from `huddle::pocket` so it
-//! doesn't depend on changing module visibility for a one-off dev tool.
-//! Keep in sync with `huddle::pocket::load_text_to_speech`.
-//!
-//! Run with the model files in a directory (defaults to /tmp/pocket-tts-bench):
-//!   cargo run --release --example pocket_bench
-//!   cargo run --release --example pocket_bench /path/to/pocket-tts
-
-use std::path::PathBuf;
-use std::time::Instant;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-const SAMPLE_RATE: u32 = 24_000;
-const TEST_TEXT: &str =
-    "Hello, this is a test of the new Pocket TTS engine running on sherpa-onnx.";
-
-fn main() {
-    let model_dir = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| "/tmp/pocket-tts-bench".to_string());
-    println!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let t0 = Instant::now();
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-    let load_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    println!("Engine load:      {load_ms:.1} ms");
-
-    let t0 = Instant::now();
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let samples = wave.samples().to_vec();
-    let sr = wave.sample_rate();
-    let voice_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    println!("Voice load:       {voice_ms:.1} ms");
-
-    let gen = || GenerationConfig {
-        speed: 1.05,
-        num_steps: 1,
-        silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-        reference_audio: Some(samples.clone()),
-        reference_sample_rate: sr,
-        ..Default::default()
-    };
-
-    let t0 = Instant::now();
-    let cold = engine
-        .generate_with_config(TEST_TEXT, &gen(), None::<fn(&[f32], f32) -> bool>)
-        .expect("cold synth");
-    let cold_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    let cold_audio_ms = (cold.samples().len() as f32 / SAMPLE_RATE as f32) * 1000.0;
-    let cold_rtf_x = cold_audio_ms / cold_ms;
-    println!(
-        "Cold synth:       {cold_ms:.1} ms  → {cold_audio_ms:.1} ms audio  → {cold_rtf_x:.2}× realtime"
-    );
-
-    let t0 = Instant::now();
-    let warm = engine
-        .generate_with_config(TEST_TEXT, &gen(), None::<fn(&[f32], f32) -> bool>)
-        .expect("warm synth");
-    let warm_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    let warm_audio_ms = (warm.samples().len() as f32 / SAMPLE_RATE as f32) * 1000.0;
-    let warm_rtf_x = warm_audio_ms / warm_ms;
-    println!(
-        "Warm synth:       {warm_ms:.1} ms  → {warm_audio_ms:.1} ms audio  → {warm_rtf_x:.2}× realtime"
-    );
-
-    let out_path = "/tmp/pocket_bench_out.wav";
-    let ok = sherpa_onnx::write(out_path, warm.samples(), SAMPLE_RATE as i32);
-    println!(
-        "Wrote {} ({} samples, ok={ok})",
-        out_path,
-        warm.samples().len()
-    );
-
-    let delta_ms = cold_ms - warm_ms;
-    let delta_pct = (delta_ms / warm_ms) * 100.0;
-    println!();
-    println!("Cold/warm delta:  {delta_ms:+.1} ms  ({delta_pct:+.1}%)");
-    println!(
-        "Decision: warmup {}.",
-        if delta_ms > 200.0 {
-            "RECOMMENDED — significant cold-call penalty"
-        } else if delta_ms > 50.0 {
-            "OPTIONAL — small cold-call penalty"
-        } else {
-            "UNNECESSARY — cold and warm essentially equal"
-        }
-    );
-}
diff --git a/desktop/src-tauri/examples/pocket_clip_probe.rs b/desktop/src-tauri/examples/pocket_clip_probe.rs
deleted file mode 100644
index ad8657599f..0000000000
--- a/desktop/src-tauri/examples/pocket_clip_probe.rs
+++ /dev/null
@@ -1,122 +0,0 @@
-//! Clipping probe for any fixed playback gain applied after Pocket TTS synth.
-//!
-//! Synthesises a spread of sentences (short/long, calm/energetic) and reports
-//! the raw peak of each, the post-gain peak, and the fraction of samples that
-//! would hit a ±1.0 clamp — i.e. how much a fixed gain would flat-top the
-//! waveform ("blown out" distortion).
-//!
-//! History: the production pipeline briefly shipped a fixed 9.3× gain
-//! calibrated on a single bench utterance that peaked at 0.076. This probe
-//! showed real output peaks at 0.4–0.97, so that gain clipped 13–34% of all
-//! samples (the 2026-06-12 "blown out" report). Production now applies no
-//! gain — run this probe before reintroducing one.
-//!
-//! Run with model files in ~/.buzz/models/pocket-tts (override with arg 1):
-//!   cargo run --release --example pocket_clip_probe
-
-use std::path::PathBuf;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-/// Candidate gain under test (the regressed production value).
-const GAIN: f32 = 9.3;
-
-const PROMPTS: &[&str] = &[
-    "Hello, this is a test of the new Pocket TTS engine running on sherpa-onnx.",
-    "Yep, I can hear you.",
-    "Absolutely! That sounds fantastic, let's do it right now!",
-    "The quick brown fox jumps over the lazy dog near the riverbank.",
-    "I found three problems in the code: a race condition, a memory leak, and an off-by-one error in the loop bounds.",
-    "No.",
-    "Warning! The build failed because seventeen tests crashed unexpectedly!",
-    "Sure, I can walk you through the whole pipeline step by step whenever you're ready.",
-];
-
-fn main() {
-    let model_dir = std::env::args().nth(1).unwrap_or_else(|| {
-        dirs::home_dir()
-            .expect("home dir")
-            .join(".buzz/models/pocket-tts")
-            .to_string_lossy()
-            .into_owned()
-    });
-    eprintln!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let voice_samples = wave.samples().to_vec();
-    let voice_sr = wave.sample_rate();
-
-    let gen = || GenerationConfig {
-        speed: 1.05,
-        num_steps: 1,
-        silence_scale: 1.0,
-        reference_audio: Some(voice_samples.clone()),
-        reference_sample_rate: voice_sr,
-        ..Default::default()
-    };
-
-    let _ = engine.generate_with_config("warmup.", &gen(), None::<fn(&[f32], f32) -> bool>);
-
-    println!(
-        "{:<46} | {:>8} | {:>9} | {:>9} | {:>10}",
-        "prompt", "raw peak", "raw RMS", "post-gain", "% clipped"
-    );
-    println!("{}", "-".repeat(95));
-
-    let mut worst_clip = 0.0f32;
-    for prompt in PROMPTS {
-        let out = engine
-            .generate_with_config(prompt, &gen(), None::<fn(&[f32], f32) -> bool>)
-            .expect("synth");
-        let samples = out.samples();
-
-        let peak = samples.iter().fold(0.0f32, |m, s| m.max(s.abs()));
-        let rms = (samples.iter().map(|s| s * s).sum::<f32>() / samples.len() as f32).sqrt();
-        let post = peak * GAIN;
-        let clipped = samples.iter().filter(|s| s.abs() * GAIN > 1.0).count();
-        let clip_pct = 100.0 * clipped as f32 / samples.len() as f32;
-        worst_clip = worst_clip.max(clip_pct);
-
-        let label: String = prompt.chars().take(44).collect();
-        println!("{label:<46} | {peak:>8.4} | {rms:>9.4} | {post:>9.3} | {clip_pct:>9.3}%");
-    }
-
-    println!();
-    println!(
-        "Verdict: worst-case clipped fraction {worst_clip:.3}% — {}",
-        if worst_clip > 0.1 {
-            "AUDIBLE DISTORTION LIKELY (gain too hot)"
-        } else if worst_clip > 0.0 {
-            "marginal — occasional transient clipping"
-        } else {
-            "no clipping at this gain"
-        }
-    );
-}
diff --git a/desktop/src-tauri/examples/pocket_onset_probe.rs b/desktop/src-tauri/examples/pocket_onset_probe.rs
deleted file mode 100644
index 05b4d0193c..0000000000
--- a/desktop/src-tauri/examples/pocket_onset_probe.rs
+++ /dev/null
@@ -1,149 +0,0 @@
-//! Onset-attenuation probe for Pocket TTS.
-//!
-//! Synthesises a handful of short sentences and dumps per-sentence onset
-//! statistics (samples[0], 1ms/5ms/20ms peak + RMS) so we can decide whether
-//! the production `apply_fades` 8 ms fade-in is masking real audio.
-//!
-//! Also writes the raw (un-faded, un-normalised) audio of each sentence to
-//! /tmp so they can be inspected in Audacity / aplay without rodio in the
-//! loop.
-//!
-//! Run with model files in /tmp/pocket-tts-bench (override with arg 1):
-//!   cargo run --release --example pocket_onset_probe
-//!   cargo run --release --example pocket_onset_probe /path/to/pocket-tts
-
-use std::path::PathBuf;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-const SAMPLE_RATE: u32 = 24_000;
-
-/// Test prompts chosen to span different onsets:
-/// - palatal glide 'Y' (soft onset)
-/// - voiceless fricative 'H' (very soft onset)
-/// - labio-velar glide 'W' (medium onset)
-/// - voiceless stop 'T' (hard onset)
-const PROMPTS: &[&str] = &[
-    "Yep, I can hear you.",
-    "Hello there friend.",
-    "What can I help with?",
-    "Try this experiment now.",
-];
-
-fn main() {
-    let model_dir = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| "/tmp/pocket-tts-bench".to_string());
-    eprintln!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let voice_samples = wave.samples().to_vec();
-    let voice_sr = wave.sample_rate();
-
-    // Warmup so we're not measuring cold-call jitter.
-    {
-        let cfg = GenerationConfig {
-            speed: 1.05,
-            num_steps: 1,
-            silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-            reference_audio: Some(voice_samples.clone()),
-            reference_sample_rate: voice_sr,
-            ..Default::default()
-        };
-        let _ = engine.generate_with_config("warmup.", &cfg, None::<fn(&[f32], f32) -> bool>);
-    }
-
-    println!(
-        "{:<28} | {:>10} | {:>10} {:>10} | {:>10} {:>10} | {:>10} {:>10}",
-        "prompt",
-        "samples[0]",
-        "peak@1ms",
-        "rms@1ms",
-        "peak@5ms",
-        "rms@5ms",
-        "peak@20ms",
-        "rms@20ms"
-    );
-    println!("{}", "-".repeat(120));
-
-    for prompt in PROMPTS {
-        // Mirror the production prompt-prep (capitalise + terminal punctuation).
-        // These prompts already have it, so this is just to match what
-        // sherpa-onnx sees in production.
-        let cfg = GenerationConfig {
-            speed: 1.05,
-            num_steps: 1,
-            silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-            reference_audio: Some(voice_samples.clone()),
-            reference_sample_rate: voice_sr,
-            ..Default::default()
-        };
-        let out = engine
-            .generate_with_config(prompt, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .expect("synth");
-        let samples = out.samples();
-
-        let n_1ms = (SAMPLE_RATE as f32 * 0.001) as usize;
-        let n_5ms = (SAMPLE_RATE as f32 * 0.005) as usize;
-        let n_20ms = (SAMPLE_RATE as f32 * 0.020) as usize;
-
-        let stats = |range: &[f32]| -> (f32, f32) {
-            if range.is_empty() {
-                return (0.0, 0.0);
-            }
-            let peak = range.iter().fold(0.0_f32, |a, &x| a.max(x.abs()));
-            let sumsq: f32 = range.iter().map(|x| x * x).sum();
-            let rms = (sumsq / range.len() as f32).sqrt();
-            (peak, rms)
-        };
-
-        let first = samples.first().copied().unwrap_or(0.0);
-        let (p1, r1) = stats(&samples[..n_1ms.min(samples.len())]);
-        let (p5, r5) = stats(&samples[..n_5ms.min(samples.len())]);
-        let (p20, r20) = stats(&samples[..n_20ms.min(samples.len())]);
-
-        println!(
-            "{:<28} | {:>10.6} | {:>10.6} {:>10.6} | {:>10.6} {:>10.6} | {:>10.6} {:>10.6}",
-            prompt, first, p1, r1, p5, r5, p20, r20
-        );
-
-        let safe: String = prompt
-            .chars()
-            .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
-            .collect();
-        let out_path = format!("/tmp/pocket_onset_{}.wav", &safe[..safe.len().min(24)]);
-        let _ = sherpa_onnx::write(&out_path, samples, SAMPLE_RATE as i32);
-        eprintln!(
-            "  → wrote {out_path} ({} samples = {:.3} s)",
-            samples.len(),
-            samples.len() as f32 / SAMPLE_RATE as f32
-        );
-    }
-}
diff --git a/desktop/src-tauri/examples/pocket_quality_ab.rs b/desktop/src-tauri/examples/pocket_quality_ab.rs
deleted file mode 100644
index 0c31f1c910..0000000000
--- a/desktop/src-tauri/examples/pocket_quality_ab.rs
+++ /dev/null
@@ -1,519 +0,0 @@
-//! Reproducible blind Pocket TTS quality corpus generator.
-//!
-//! Renders Buzz's production prompt preparation and post-processing across:
-//! INT8/FP32 × per-sentence/grouped generation. The generated filenames are
-//! deterministically blinded; keep `key.json` away from listeners until their
-//! scoring sheet is complete.
-//!
-//! Usage:
-//!   cargo run --release --example pocket_quality_ab -- \
-//!     <int8-model-dir> <fp32-model-dir> <output-dir> [--idle-minutes N --only ITEM]
-//!
-//! The optional idle run intentionally creates one engine per condition, warms
-//! all four, sleeps once, and then makes each clip the first generation after
-//! dormancy. It requires `--only` because only the first synthesis after an
-//! uninterrupted idle is a valid post-idle observation. Run each 5/15-minute
-//! item as a separate process.
-
-// Importing the production module also brings in runtime-only helpers that this
-// standalone corpus generator deliberately does not call.
-#![allow(dead_code)]
-
-#[path = "../src/huddle/pocket.rs"]
-mod production_pocket;
-#[path = "../src/huddle/preprocessing.rs"]
-mod production_preprocessing;
-
-use std::collections::HashMap;
-use std::fs;
-use std::path::{Path, PathBuf};
-use std::time::{Duration, Instant};
-
-use serde::Serialize;
-use sha2::{Digest, Sha256};
-use sherpa_onnx::{GenerationConfig, OfflineTts, OfflineTtsConfig, Wave};
-
-use production_pocket::{prepare_pocket_prompt, SAMPLE_RATE};
-use production_preprocessing::{preprocess_for_tts, split_sentences};
-
-const NUM_STEPS: i32 = 1;
-const SILENCE_SCALE: f32 = 1.0;
-const INTER_SENTENCE_SILENCE_SAMPLES: usize = SAMPLE_RATE as usize / 10;
-const LEAD_IN_SAMPLES: usize = SAMPLE_RATE as usize / 50;
-const FADE_OUT_SAMPLES: usize = SAMPLE_RATE as usize * 8 / 1000;
-const TARGET_RMS_DBFS: f32 = -23.0;
-const BLINDING_SEED: &str = "pocket-quality-2026-07-21-v1";
-
-const CORPUS: &[CorpusItem] = &[
-    CorpusItem { id: "short_one_word", kind: "short", text: "Yep." },
-    CorpusItem { id: "short_four_words", kind: "short", text: "Sounds good to me." },
-    CorpusItem {
-        id: "multi_relay_review",
-        kind: "multi-sentence",
-        text: "I looked at the relay code this morning. The lease logic is solid. There's one race in the worker claim path, though. I'll write it up and send you a patch.",
-    },
-    CorpusItem {
-        id: "multi_community_size",
-        kind: "multi-sentence",
-        text: "Great question. The answer is it depends on the community size. For small ones, keep it simple.",
-    },
-    CorpusItem {
-        id: "mixed_agent_message",
-        kind: "mixed",
-        text: "That's 42 open PRs right now — mostly small. I'll triage them after lunch.",
-    },
-];
-
-#[derive(Clone, Copy)]
-struct CorpusItem {
-    id: &'static str,
-    kind: &'static str,
-    text: &'static str,
-}
-
-#[derive(Clone, Copy, Debug, Serialize)]
-#[serde(rename_all = "snake_case")]
-enum Precision {
-    Int8,
-    Fp32,
-}
-
-#[derive(Clone, Copy, Debug, Serialize)]
-#[serde(rename_all = "snake_case")]
-enum Chunking {
-    PerSentence,
-    Grouped,
-}
-
-#[derive(Clone, Copy, Debug)]
-struct Condition {
-    precision: Precision,
-    chunking: Chunking,
-}
-
-const CONDITIONS: [Condition; 4] = [
-    Condition {
-        precision: Precision::Int8,
-        chunking: Chunking::PerSentence,
-    },
-    Condition {
-        precision: Precision::Int8,
-        chunking: Chunking::Grouped,
-    },
-    Condition {
-        precision: Precision::Fp32,
-        chunking: Chunking::PerSentence,
-    },
-    Condition {
-        precision: Precision::Fp32,
-        chunking: Chunking::Grouped,
-    },
-];
-
-#[derive(Serialize)]
-struct KeyFile {
-    warning: &'static str,
-    blinding_seed: &'static str,
-    target_rms_dbfs: f32,
-    items: Vec<KeyItem>,
-}
-
-#[derive(Serialize)]
-struct KeyItem {
-    id: String,
-    kind: String,
-    text: String,
-    clips: Vec<KeyClip>,
-}
-
-#[derive(Serialize)]
-struct KeyClip {
-    file: String,
-    precision: Precision,
-    chunking: Chunking,
-    cold_start: bool,
-    idle_minutes: Option<u64>,
-    synthesis_ms: u128,
-    audio_seconds: f32,
-}
-
-struct Voice {
-    samples: Vec<f32>,
-    sample_rate: i32,
-}
-
-struct Engine {
-    inner: OfflineTts,
-    voice: Voice,
-}
-
-fn main() -> Result<(), String> {
-    let mut args = std::env::args().skip(1);
-    let int8_dir = required_path(args.next(), "INT8 model directory")?;
-    let fp32_dir = required_path(args.next(), "FP32 model directory")?;
-    let output_dir = required_path(args.next(), "output directory")?;
-    let mut idle_minutes = None;
-    let mut only_item = None;
-    while let Some(arg) = args.next() {
-        match arg.as_str() {
-            "--idle-minutes" => {
-                idle_minutes = Some(
-                    args.next()
-                        .ok_or("--idle-minutes requires a value")?
-                        .parse::<u64>()
-                        .map_err(|e| format!("invalid idle minutes: {e}"))?,
-                );
-            }
-            "--only" => only_item = Some(args.next().ok_or("--only requires an item ID")?),
-            _ => return Err(format!("unknown argument: {arg}")),
-        }
-    }
-
-    if idle_minutes.is_some() && only_item.is_none() {
-        return Err("--idle-minutes requires --only so every clip is first-after-idle".into());
-    }
-    if let Some(ref requested) = only_item {
-        if !CORPUS.iter().any(|item| item.id == requested) {
-            return Err(format!("unknown corpus item for --only: {requested}"));
-        }
-    }
-
-    validate_model_dir(&int8_dir, Precision::Int8)?;
-    validate_model_dir(&fp32_dir, Precision::Fp32)?;
-    fs::create_dir_all(&output_dir).map_err(|e| e.to_string())?;
-
-    let mut engines = Vec::with_capacity(CONDITIONS.len());
-    for condition in CONDITIONS {
-        let dir = match condition.precision {
-            Precision::Int8 => &int8_dir,
-            Precision::Fp32 => &fp32_dir,
-        };
-        let engine = load_engine(dir, condition.precision)?;
-        // Production warms once before serving a real utterance. Cold cases use
-        // separate fresh engines below and deliberately skip this call.
-        synth_chunks(&engine, &["warmup".to_string()])?;
-        engines.push(engine);
-    }
-
-    if let Some(minutes) = idle_minutes {
-        eprintln!("All four warmed engines idle for {minutes} minute(s)…");
-        std::thread::sleep(Duration::from_secs(minutes * 60));
-    }
-
-    let mut key_items = Vec::new();
-    for item in CORPUS {
-        if only_item
-            .as_deref()
-            .is_some_and(|requested| requested != item.id)
-        {
-            continue;
-        }
-        let preprocessed = preprocess_for_tts(item.text);
-        let per_sentence: Vec<String> = split_sentences(&preprocessed)
-            .into_iter()
-            .filter(|s| !s.trim().is_empty())
-            .collect();
-        // These corpus texts are deliberately below the upstream ~50-token
-        // grouping target, so grouped mode is one exact generate() call.
-        let grouped = vec![per_sentence.join(" ")];
-        let item_dir = output_dir.join(item.id);
-        fs::create_dir_all(&item_dir).map_err(|e| e.to_string())?;
-        let clip_order = blinded_order(item.id);
-        let mut clips = Vec::new();
-
-        let mut rendered = Vec::new();
-        for (condition_index, engine) in engines.iter().enumerate() {
-            let condition = CONDITIONS[condition_index];
-            let chunks = match condition.chunking {
-                Chunking::PerSentence => &per_sentence,
-                Chunking::Grouped => &grouped,
-            };
-            let started = Instant::now();
-            let audio = synth_chunks(engine, chunks)?;
-            rendered.push((
-                condition_index,
-                condition,
-                audio,
-                started.elapsed().as_millis(),
-            ));
-        }
-        loudness_match_item(&mut rendered);
-        for (condition_index, condition, audio, synth_ms) in rendered {
-            let clip_number = clip_order[condition_index] + 1;
-            let file_name = format!("clip{clip_number}.wav");
-            write_wav(&item_dir.join(&file_name), &audio)?;
-            clips.push(KeyClip {
-                file: format!("{}/{file_name}", item.id),
-                precision: condition.precision,
-                chunking: condition.chunking,
-                cold_start: false,
-                idle_minutes,
-                synthesis_ms: synth_ms,
-                audio_seconds: audio.len() as f32 / SAMPLE_RATE as f32,
-            });
-        }
-        clips.sort_by(|a, b| a.file.cmp(&b.file));
-        key_items.push(KeyItem {
-            id: item.id.to_string(),
-            kind: item.kind.to_string(),
-            text: item.text.to_string(),
-            clips,
-        });
-    }
-
-    // Explicit fresh-engine cold-start clips for the two highest-signal texts.
-    // Idle runs intentionally omit them: they happen after the post-idle clips
-    // and add no valid idle observation.
-    for item in if idle_minutes.is_none() { CORPUS } else { &[] } {
-        if !matches!(item.id, "short_one_word" | "multi_relay_review") {
-            continue;
-        }
-        if only_item
-            .as_deref()
-            .is_some_and(|requested| requested != item.id)
-        {
-            continue;
-        }
-        let cold_id = format!("cold_{}", item.id);
-        let preprocessed = preprocess_for_tts(item.text);
-        let sentences: Vec<String> = split_sentences(&preprocessed)
-            .into_iter()
-            .filter(|s| !s.trim().is_empty())
-            .collect();
-        let grouped = vec![sentences.join(" ")];
-        let item_dir = output_dir.join(&cold_id);
-        fs::create_dir_all(&item_dir).map_err(|e| e.to_string())?;
-        let clip_order = blinded_order(&cold_id);
-        let mut clips = Vec::new();
-        let mut rendered = Vec::new();
-        for (condition_index, condition) in CONDITIONS.iter().copied().enumerate() {
-            let dir = match condition.precision {
-                Precision::Int8 => &int8_dir,
-                Precision::Fp32 => &fp32_dir,
-            };
-            let engine = load_engine(dir, condition.precision)?;
-            let chunks = match condition.chunking {
-                Chunking::PerSentence => &sentences,
-                Chunking::Grouped => &grouped,
-            };
-            let started = Instant::now();
-            let audio = synth_chunks(&engine, chunks)?;
-            rendered.push((
-                condition_index,
-                condition,
-                audio,
-                started.elapsed().as_millis(),
-            ));
-        }
-        loudness_match_item(&mut rendered);
-        for (condition_index, condition, audio, synth_ms) in rendered {
-            let clip_number = clip_order[condition_index] + 1;
-            let file_name = format!("clip{clip_number}.wav");
-            write_wav(&item_dir.join(&file_name), &audio)?;
-            clips.push(KeyClip {
-                file: format!("{cold_id}/{file_name}"),
-                precision: condition.precision,
-                chunking: condition.chunking,
-                cold_start: true,
-                idle_minutes: None,
-                synthesis_ms: synth_ms,
-                audio_seconds: audio.len() as f32 / SAMPLE_RATE as f32,
-            });
-        }
-        clips.sort_by(|a, b| a.file.cmp(&b.file));
-        key_items.push(KeyItem {
-            id: cold_id,
-            kind: "cold-start".to_string(),
-            text: item.text.to_string(),
-            clips,
-        });
-    }
-
-    let key = KeyFile {
-        warning: "DO NOT OPEN UNTIL LISTENING SCORES ARE FINAL",
-        blinding_seed: BLINDING_SEED,
-        target_rms_dbfs: TARGET_RMS_DBFS,
-        items: key_items,
-    };
-    fs::write(
-        output_dir.join("key.json"),
-        serde_json::to_vec_pretty(&key).map_err(|e| e.to_string())?,
-    )
-    .map_err(|e| e.to_string())?;
-    write_scoring_sheet(&output_dir, &key)?;
-    println!("Wrote blind corpus to {}", output_dir.display());
-    println!("Give listeners the WAV folders and SCORING.md; withhold key.json.");
-    Ok(())
-}
-
-fn required_path(value: Option<String>, label: &str) -> Result<PathBuf, String> {
-    value
-        .map(PathBuf::from)
-        .ok_or_else(|| format!("missing {label}"))
-}
-
-fn model_file(precision: Precision, base: &str) -> String {
-    match precision {
-        Precision::Int8 => format!("{base}.int8.onnx"),
-        Precision::Fp32 => format!("{base}.onnx"),
-    }
-}
-
-fn validate_model_dir(dir: &Path, precision: Precision) -> Result<(), String> {
-    for file in [
-        model_file(precision, "lm_main"),
-        model_file(precision, "lm_flow"),
-        "encoder.onnx".into(),
-        model_file(precision, "decoder"),
-        "text_conditioner.onnx".into(),
-        "vocab.json".into(),
-        "token_scores.json".into(),
-        "reference_sample.wav".into(),
-    ] {
-        if !dir.join(&file).is_file() {
-            return Err(format!("missing {}", dir.join(file).display()));
-        }
-    }
-    Ok(())
-}
-
-fn load_engine(dir: &Path, precision: Precision) -> Result<Engine, String> {
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-    let mut cfg = OfflineTtsConfig::default();
-    cfg.model.pocket.lm_main = Some(p(&model_file(precision, "lm_main")));
-    cfg.model.pocket.lm_flow = Some(p(&model_file(precision, "lm_flow")));
-    cfg.model.pocket.encoder = Some(p("encoder.onnx"));
-    cfg.model.pocket.decoder = Some(p(&model_file(precision, "decoder")));
-    cfg.model.pocket.text_conditioner = Some(p("text_conditioner.onnx"));
-    cfg.model.pocket.vocab_json = Some(p("vocab.json"));
-    cfg.model.pocket.token_scores_json = Some(p("token_scores.json"));
-    cfg.model.pocket.voice_embedding_cache_capacity = 16;
-    cfg.model.num_threads = 1;
-    cfg.model.debug = false;
-    let inner =
-        OfflineTts::create(&cfg).ok_or_else(|| format!("failed to create {precision:?} engine"))?;
-    let wave =
-        Wave::read(&p("reference_sample.wav")).ok_or("failed to read reference_sample.wav")?;
-    Ok(Engine {
-        inner,
-        voice: Voice {
-            samples: wave.samples().to_vec(),
-            sample_rate: wave.sample_rate(),
-        },
-    })
-}
-
-fn synth_chunks(engine: &Engine, chunks: &[String]) -> Result<Vec<f32>, String> {
-    let mut out = Vec::new();
-    for chunk in chunks {
-        let prepared = prepare_pocket_prompt(chunk).ok_or("empty prepared prompt")?;
-        let extra = prepared.max_frames.map(|max_frames| {
-            HashMap::from([(
-                "max_frames".to_string(),
-                serde_json::Value::from(max_frames),
-            )])
-        });
-        let cfg = GenerationConfig {
-            num_steps: NUM_STEPS,
-            silence_scale: SILENCE_SCALE,
-            reference_audio: Some(engine.voice.samples.clone()),
-            reference_sample_rate: engine.voice.sample_rate,
-            extra,
-            ..Default::default()
-        };
-        let audio = engine
-            .inner
-            .generate_with_config(&prepared.text, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .ok_or_else(|| format!("synthesis failed for {chunk:?}"))?;
-        let mut samples: Vec<f32> = audio.samples().iter().map(|s| s.clamp(-1.0, 1.0)).collect();
-        apply_fade_out(&mut samples);
-        out.extend(std::iter::repeat_n(0.0, LEAD_IN_SAMPLES));
-        out.extend(samples);
-        out.extend(std::iter::repeat_n(
-            0.0,
-            INTER_SENTENCE_SILENCE_SAMPLES - LEAD_IN_SAMPLES,
-        ));
-    }
-    Ok(out)
-}
-
-fn apply_fade_out(samples: &mut [f32]) {
-    let fade = FADE_OUT_SAMPLES.min(samples.len() / 2);
-    for i in 0..fade {
-        samples[samples.len() - 1 - i] *= i as f32 / fade as f32;
-    }
-}
-
-fn active_rms(samples: &[f32]) -> Option<f32> {
-    let (sum_squares, count) = samples
-        .iter()
-        .filter(|sample| sample.abs() > 1.0e-4)
-        .fold((0.0_f32, 0_usize), |(sum, count), sample| {
-            (sum + sample * sample, count + 1)
-        });
-    (count > 0).then(|| (sum_squares / count as f32).sqrt())
-}
-
-/// Attenuate every clip in one comparison set to the quietest active-speech RMS.
-/// This removes the louder-is-better confound without normalizing dynamics or
-/// claiming standards-compliant integrated LUFS. The dBFS value is a ceiling.
-fn loudness_match_item(rendered: &mut [(usize, Condition, Vec<f32>, u128)]) {
-    let ceiling = 10.0_f32.powf(TARGET_RMS_DBFS / 20.0);
-    let target = rendered
-        .iter()
-        .filter_map(|(_, _, samples, _)| active_rms(samples))
-        .fold(ceiling, f32::min);
-    for (_, _, samples, _) in rendered {
-        let Some(rms) = active_rms(samples) else {
-            continue;
-        };
-        let gain = (target / rms).min(1.0);
-        for sample in samples {
-            *sample *= gain;
-        }
-    }
-}
-
-fn blinded_order(item_id: &str) -> [usize; 4] {
-    let mut keyed: Vec<(usize, Vec<u8>)> = (0..4)
-        .map(|index| {
-            let digest = Sha256::digest(format!("{BLINDING_SEED}:{item_id}:{index}"));
-            (index, digest.to_vec())
-        })
-        .collect();
-    keyed.sort_by(|a, b| a.1.cmp(&b.1));
-    let mut condition_to_clip = [0; 4];
-    for (clip, (condition, _)) in keyed.into_iter().enumerate() {
-        condition_to_clip[condition] = clip;
-    }
-    condition_to_clip
-}
-
-fn write_wav(path: &Path, samples: &[f32]) -> Result<(), String> {
-    let path = path
-        .to_str()
-        .ok_or_else(|| format!("non-UTF8 path: {}", path.display()))?;
-    if sherpa_onnx::write(path, samples, SAMPLE_RATE as i32) {
-        Ok(())
-    } else {
-        Err(format!("failed to write {path}"))
-    }
-}
-
-fn write_scoring_sheet(output_dir: &Path, key: &KeyFile) -> Result<(), String> {
-    let mut sheet = String::from("# Pocket TTS blind listening sheet\n\nDo not open `key.json` until this sheet is complete. Rank best to worst; ties are allowed.\n\n");
-    for item in &key.items {
-        sheet.push_str(&format!(
-            "## {} ({})\n\n> {}\n\n",
-            item.id, item.kind, item.text
-        ));
-        sheet.push_str("Rank: `____ > ____ > ____ > ____`\n\n| Clip | seam | onset | garble | robotic | timbre | truncate | note |\n|---|---|---|---|---|---|---|---|\n");
-        for clip in 1..=4 {
-            sheet.push_str(&format!(
-                "| clip{clip} | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | |\n"
-            ));
-        }
-        sheet.push('\n');
-    }
-    fs::write(output_dir.join("SCORING.md"), sheet).map_err(|e| e.to_string())
-}
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_state.rs b/desktop/src-tauri/src/app_state.rs
index 94d162e620..fc90e6ab14 100644
--- a/desktop/src-tauri/src/app_state.rs
+++ b/desktop/src-tauri/src/app_state.rs
@@ -2,7 +2,7 @@ use std::{
     collections::HashMap,
     io::Write,
     sync::{
-        atomic::{AtomicBool, AtomicU16},
+        atomic::{AtomicBool, AtomicU16, AtomicU8},
         Arc, Mutex,
     },
 };
@@ -13,10 +13,15 @@ use tauri::{AppHandle, Manager};
 use tokio::sync::Mutex as AsyncMutex;
 
 use crate::huddle::HuddleState;
+pub(crate) use crate::identity_storage::{IdentityStorage, RecoveryState, ResolvedIdentity};
 use crate::managed_agents::config_bridge::SessionConfigCache;
 use crate::managed_agents::{ManagedAgentPairRuntime, ManagedAgentRuntimeKey};
+
 pub struct AppState {
     pub keys: Mutex<Keys>,
+    /// Durable backend holding `keys`. Updated after the key write and before
+    /// recovery flags are cleared so `get_identity` reports a consistent state.
+    pub(crate) identity_storage: AtomicU8,
     pub http_client: reqwest::Client,
     /// A no-redirect client for authenticated relay media fetches (download,
     /// clipboard copy, snapshot, editor). Every caller pre-validates the URL
@@ -48,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
@@ -178,19 +181,20 @@ pub fn build_media_fetch_client() -> reqwest::Result<reqwest::Client> {
 pub fn build_app_state() -> AppState {
     // Env var takes precedence (dev/CI). If absent, resolve_persisted_identity()
     // in setup() will replace the ephemeral placeholder with a persisted key.
-    let keys = match identity_from_env() {
+    let (keys, identity_storage) = match identity_from_env() {
         Some(keys) => {
             eprintln!(
                 "buzz-desktop: configured identity pubkey {}",
                 keys.public_key().to_hex()
             );
-            keys
+            (keys, IdentityStorage::Environment)
         }
-        None => Keys::generate(),
+        None => (Keys::generate(), IdentityStorage::Ephemeral),
     };
 
     AppState {
         keys: Mutex::new(keys),
+        identity_storage: AtomicU8::new(identity_storage as u8),
         http_client: reqwest::Client::builder()
             .resolve("localhost", std::net::SocketAddr::from(([127, 0, 0, 1], 0)))
             .pool_idle_timeout(std::time::Duration::from_secs(10))
@@ -213,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(),
@@ -366,9 +370,13 @@ pub fn resolve_persisted_identity(app: &AppHandle, state: &AppState) -> Result<(
     std::fs::create_dir_all(&data_dir).map_err(|e| format!("create app data dir: {e}"))?;
 
     let resolved = load_or_create_identity(&data_dir)?;
-    // Write keys before setting the recovery flags (Release) so any thread
-    // that reads a flag as false with Acquire is guaranteed to see the keys.
-    *state.keys.lock().map_err(|e| e.to_string())? = resolved.keys;
+    // Write keys and storage before setting the recovery flags (Release) so
+    // any thread that reads a flag as false with Acquire sees consistent data.
+    {
+        let mut active_keys = state.keys.lock().map_err(|e| e.to_string())?;
+        *active_keys = resolved.keys;
+        state.set_identity_storage(resolved.storage);
+    }
     state.identity_lost.store(
         resolved.recovery == RecoveryState::Lost,
         std::sync::atomic::Ordering::Release,
@@ -394,26 +402,6 @@ const IDENTITY_KEY_NAME: &str = "identity";
 /// keyring is merely unreachable (the key IS in the keyring, must NOT generate).
 const MIGRATION_MARKER_NAME: &str = "identity.migrated";
 
-/// Recovery state produced by identity resolution. `None` means the app has
-/// a real, usable identity. `Lost` means the keyring was reachable-but-empty
-/// despite a prior successful migration — the key vanished externally. `KeyringLocked`
-/// means the keyring is unreachable this boot but was used in the past
-/// (marker present, no file) — the key still exists but is temporarily
-/// inaccessible. Both non-`None` variants boot with an ephemeral key; the
-/// frontend shows a different recovery screen for each.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum RecoveryState {
-    None,
-    Lost,
-    KeyringLocked,
-}
-
-/// The output of identity resolution.
-struct ResolvedIdentity {
-    keys: Keys,
-    recovery: RecoveryState,
-}
-
 /// The keyring operations the identity resolution flow needs. Abstracted so the
 /// corrupt-keyring recovery decision ([`recover_from_keyring`]) can be
 /// unit-tested against a fake without touching the live OS keyring.
@@ -465,6 +453,7 @@ fn load_or_create_identity(data_dir: &std::path::Path) -> Result<ResolvedIdentit
         return Ok(ResolvedIdentity {
             keys,
             recovery: RecoveryState::None,
+            storage: IdentityStorage::LocalFile,
         });
     }
 
@@ -514,7 +503,7 @@ fn resolve_identity_with_store(
                                     // fails. A transient keyring failure must not abort
                                     // boot — the file key is safe and adoption retries next
                                     // boot when the keyring is reachable again.
-                                    if let Err(e) = persist_identity_to_keyring(
+                                    let storage = if let Err(e) = persist_identity_to_keyring(
                                         store,
                                         &file_keys,
                                         legacy_path,
@@ -524,10 +513,14 @@ fn resolve_identity_with_store(
                                             "buzz-desktop: keyring adoption of identity.key \
                                              failed ({e}); using file key, will retry next boot"
                                         );
-                                    }
+                                        IdentityStorage::LocalFile
+                                    } else {
+                                        IdentityStorage::SystemKeyring
+                                    };
                                     return Ok(ResolvedIdentity {
                                         keys: file_keys,
                                         recovery: RecoveryState::None,
+                                        storage,
                                     });
                                 }
                                 // Corrupt file — keyring is authoritative. Log before
@@ -567,6 +560,7 @@ fn resolve_identity_with_store(
                         return Ok(ResolvedIdentity {
                             keys: keyring_keys,
                             recovery: RecoveryState::None,
+                            storage: IdentityStorage::SystemKeyring,
                         });
                     }
                     // The corruption is in the KEYRING, not the file. Clear the
@@ -595,6 +589,7 @@ fn resolve_identity_with_store(
                     return Ok(ResolvedIdentity {
                         keys,
                         recovery: RecoveryState::None,
+                        storage: IdentityStorage::SystemKeyring,
                     });
                 }
             } else if migration_marker_path(data_dir).exists() {
@@ -615,6 +610,7 @@ fn resolve_identity_with_store(
                 return Ok(ResolvedIdentity {
                     keys: ephemeral,
                     recovery: RecoveryState::Lost,
+                    storage: IdentityStorage::Ephemeral,
                 });
             }
         }
@@ -643,20 +639,23 @@ fn resolve_identity_with_store(
                 return Ok(ResolvedIdentity {
                     keys: ephemeral,
                     recovery: RecoveryState::KeyringLocked,
+                    storage: IdentityStorage::Ephemeral,
                 });
             }
             let keys = load_file_or_generate(legacy_path, data_dir)?;
             return Ok(ResolvedIdentity {
                 keys,
                 recovery: RecoveryState::None,
+                storage: IdentityStorage::LocalFile,
             });
         }
     }
 
-    let keys = generate_and_persist(store, legacy_path, data_dir)?;
+    let (keys, storage) = generate_and_persist(store, legacy_path, data_dir)?;
     Ok(ResolvedIdentity {
         keys,
         recovery: RecoveryState::None,
+        storage,
     })
 }
 
@@ -682,6 +681,7 @@ fn recover_from_keyring(
             return Ok(ResolvedIdentity {
                 keys,
                 recovery: RecoveryState::None,
+                storage: IdentityStorage::SystemKeyring,
             });
         }
     }
@@ -699,13 +699,15 @@ fn recover_from_keyring(
         return Ok(ResolvedIdentity {
             keys: ephemeral,
             recovery: RecoveryState::Lost,
+            storage: IdentityStorage::Ephemeral,
         });
     }
     // No marker: genuine first launch with a corrupt keyring. Generate fresh.
-    let keys = generate_and_persist(store, legacy_path, data_dir)?;
+    let (keys, storage) = generate_and_persist(store, legacy_path, data_dir)?;
     Ok(ResolvedIdentity {
         keys,
         recovery: RecoveryState::None,
+        storage,
     })
 }
 
@@ -872,15 +874,16 @@ fn persist_imported_identity_impl(
     keys: &Keys,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<(), String> {
+) -> Result<IdentityStorage, String> {
     match persist_identity_to_keyring(store, keys, legacy_path, data_dir) {
-        Ok(()) => Ok(()),
+        Ok(()) => Ok(IdentityStorage::SystemKeyring),
         Err(e) => {
             eprintln!(
                 "buzz-desktop: keyring write failed during import ({e}), \
                  falling back to identity.key"
             );
-            save_key_file(legacy_path, keys)
+            save_key_file(legacy_path, keys)?;
+            Ok(IdentityStorage::LocalFile)
         }
     }
 }
@@ -892,7 +895,7 @@ pub(crate) fn persist_imported_identity(
     keys: &Keys,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<(), String> {
+) -> Result<IdentityStorage, String> {
     persist_imported_identity_impl(store, keys, legacy_path, data_dir)
 }
 
@@ -920,15 +923,6 @@ fn write_migration_marker(marker_path: &std::path::Path) -> Result<(), String> {
         .map_err(|e| format!("commit migration marker: {e}"))
 }
 
-/// Which backend [`store_key_preferring_keyring`] wrote to. The caller writes
-/// the migration marker only after a keyring success — on the file-fallback arm
-/// the key is on disk and a marker would wrongly trip the next Unreachable boot
-/// into failing closed.
-enum PersistBackend {
-    Keyring,
-    File,
-}
-
 /// Generate a fresh identity, persist it through the store, return it.
 ///
 /// On a keyring-backed persist no file is written, so a later
@@ -940,9 +934,10 @@ fn generate_and_persist(
     store: &impl IdentityKeyStore,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<Keys, String> {
+) -> Result<(Keys, IdentityStorage), String> {
     let keys = Keys::generate();
-    if let PersistBackend::Keyring = store_key_preferring_keyring(store, &keys, legacy_path)? {
+    let storage = store_key_preferring_keyring(store, &keys, legacy_path)?;
+    if storage == IdentityStorage::SystemKeyring {
         let marker_path = migration_marker_path(data_dir);
         if let Err(e) = write_migration_marker(&marker_path) {
             eprintln!(
@@ -956,7 +951,7 @@ fn generate_and_persist(
         "buzz-desktop: generated and saved identity pubkey {}",
         keys.public_key().to_hex()
     );
-    Ok(keys)
+    Ok((keys, storage))
 }
 
 /// Persist `keys` through the store, silently falling back to the `0o600` file
@@ -968,17 +963,17 @@ fn store_key_preferring_keyring(
     store: &impl IdentityKeyStore,
     keys: &Keys,
     legacy_path: &std::path::Path,
-) -> Result<PersistBackend, String> {
+) -> Result<IdentityStorage, String> {
     let nsec = keys
         .secret_key()
         .to_bech32()
         .map_err(|e| format!("encode nsec: {e}"))?;
     match store.store(IDENTITY_KEY_NAME, &nsec) {
-        Ok(()) => Ok(PersistBackend::Keyring),
+        Ok(()) => Ok(IdentityStorage::SystemKeyring),
         Err(keyring_err) => {
             eprintln!("buzz-desktop: keyring write failed ({keyring_err}), using file fallback");
             save_key_file(legacy_path, keys)?;
-            Ok(PersistBackend::File)
+            Ok(IdentityStorage::LocalFile)
         }
     }
 }
diff --git a/desktop/src-tauri/src/app_state_tests.rs b/desktop/src-tauri/src/app_state_tests.rs
index 485dfaea15..751bcf22e5 100644
--- a/desktop/src-tauri/src/app_state_tests.rs
+++ b/desktop/src-tauri/src/app_state_tests.rs
@@ -484,7 +484,7 @@ fn fresh_keyring_generate_writes_marker() {
     let resolved = resolve_identity_with_store(&store, &legacy_path, dir.path()).unwrap();
 
     // The key was stored in the keyring (not the file), and the marker marks it.
-    assert!(!legacy_path.exists());
+    assert!(!legacy_path.exists() && resolved.storage == IdentityStorage::SystemKeyring);
     assert!(migration_marker_path(dir.path()).exists());
     assert_eq!(
         store
@@ -541,7 +541,10 @@ fn fresh_generate_keyring_failure_falls_back_to_file_without_marker() {
     let from_file = load_key_file(&legacy_path).unwrap();
     assert_key_eq(&resolved.keys, &from_file);
     // No marker: the file is the authoritative store, not the keyring.
-    assert!(!migration_marker_path(dir.path()).exists());
+    assert!(
+        !migration_marker_path(dir.path()).exists()
+            && resolved.storage == IdentityStorage::LocalFile
+    );
 }
 
 // ── New tests for the three defects fixed in this PR ─────────────────────
@@ -786,10 +789,7 @@ fn persist_imported_identity_falls_back_to_file_on_keyring_failure() {
     let result = persist_imported_identity_impl(&store, &imported_keys, &legacy_path, dir.path());
 
     // The policy core handles the keyring failure — Ok, not Err.
-    assert!(
-        result.is_ok(),
-        "must not propagate keyring failure when file fallback succeeds"
-    );
+    assert_eq!(result.unwrap(), IdentityStorage::LocalFile);
 
     // Key is recoverable from the file on next boot.
     let from_file = load_key_file(&legacy_path).unwrap();
diff --git a/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt b/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt
new file mode 100644
index 0000000000..9ac732fe36
--- /dev/null
+++ b/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt
@@ -0,0 +1,1296 @@
+aardvark
+abandoned
+abbreviate
+abdomen
+abhorrence
+abiding
+abnormal
+abrasion
+absorbing
+abundant
+abyss
+academy
+accountant
+acetone
+achiness
+acid
+acoustics
+acquire
+acrobat
+actress
+acuteness
+aerosol
+aesthetic
+affidavit
+afloat
+afraid
+aftershave
+again
+agency
+aggressor
+aghast
+agitate
+agnostic
+agonizing
+agreeing
+aidless
+aimlessly
+ajar
+alarmclock
+albatross
+alchemy
+alfalfa
+algae
+aliens
+alkaline
+almanac
+alongside
+alphabet
+already
+also
+altitude
+aluminum
+always
+amazingly
+ambulance
+amendment
+amiable
+ammunition
+amnesty
+amoeba
+amplifier
+amuser
+anagram
+anchor
+android
+anesthesia
+angelfish
+animal
+anklet
+announcer
+anonymous
+answer
+antelope
+anxiety
+anyplace
+aorta
+apartment
+apnea
+apostrophe
+apple
+apricot
+aquamarine
+arachnid
+arbitrate
+ardently
+arena
+argument
+aristocrat
+armchair
+aromatic
+arrowhead
+arsonist
+artichoke
+asbestos
+ascend
+aseptic
+ashamed
+asinine
+asleep
+asocial
+asparagus
+astronaut
+asymmetric
+atlas
+atmosphere
+atom
+atrocious
+attic
+atypical
+auctioneer
+auditorium
+augmented
+auspicious
+automobile
+auxiliary
+avalanche
+avenue
+aviator
+avocado
+awareness
+awhile
+awkward
+awning
+awoke
+axially
+azalea
+babbling
+backpack
+badass
+bagpipe
+bakery
+balancing
+bamboo
+banana
+barracuda
+basket
+bathrobe
+bazooka
+blade
+blender
+blimp
+blouse
+blurred
+boatyard
+bobcat
+body
+bogusness
+bohemian
+boiler
+bonnet
+boots
+borough
+bossiness
+bottle
+bouquet
+boxlike
+breath
+briefcase
+broom
+brushes
+bubblegum
+buckle
+buddhist
+buffalo
+bullfrog
+bunny
+busboy
+buzzard
+cabin
+cactus
+cadillac
+cafeteria
+cage
+cahoots
+cajoling
+cakewalk
+calculator
+camera
+canister
+capsule
+carrot
+cashew
+cathedral
+caucasian
+caviar
+ceasefire
+cedar
+celery
+cement
+census
+ceramics
+cesspool
+chalkboard
+cheesecake
+chimney
+chlorine
+chopsticks
+chrome
+chute
+cilantro
+cinnamon
+circle
+cityscape
+civilian
+clay
+clergyman
+clipboard
+clock
+clubhouse
+coathanger
+cobweb
+coconut
+codeword
+coexistent
+coffeecake
+cognitive
+cohabitate
+collarbone
+computer
+confetti
+copier
+cornea
+cosmetics
+cotton
+couch
+coverless
+coyote
+coziness
+crawfish
+crewmember
+crib
+croissant
+crumble
+crystal
+cubical
+cucumber
+cuddly
+cufflink
+cuisine
+culprit
+cup
+curry
+cushion
+cuticle
+cybernetic
+cyclist
+cylinder
+cymbal
+cynicism
+cypress
+cytoplasm
+dachshund
+daffodil
+dagger
+dairy
+dalmatian
+dandelion
+dartboard
+dastardly
+datebook
+daughter
+dawn
+daytime
+dazzler
+dealer
+debris
+decal
+dedicate
+deepness
+defrost
+degree
+dehydrator
+deliverer
+democrat
+dentist
+deodorant
+depot
+deranged
+desktop
+detergent
+device
+dexterity
+diamond
+dibs
+dictionary
+diffuser
+digit
+dilated
+dimple
+dinnerware
+dioxide
+diploma
+directory
+dishcloth
+ditto
+dividers
+dizziness
+doctor
+dodge
+doll
+dominoes
+donut
+doorstep
+dorsal
+double
+downstairs
+dozed
+drainpipe
+dresser
+driftwood
+droppings
+drum
+dryer
+dubiously
+duckling
+duffel
+dugout
+dumpster
+duplex
+durable
+dustpan
+dutiful
+duvet
+dwarfism
+dwelling
+dwindling
+dynamite
+dyslexia
+eagerness
+earlobe
+easel
+eavesdrop
+ebook
+eccentric
+echoless
+eclipse
+ecosystem
+ecstasy
+edged
+editor
+educator
+eelworm
+eerie
+effects
+eggnog
+egomaniac
+ejection
+elastic
+elbow
+elderly
+elephant
+elfishly
+eliminator
+elk
+elliptical
+elongated
+elsewhere
+elusive
+elves
+emancipate
+embroidery
+emcee
+emerald
+emission
+emoticon
+emperor
+emulate
+enactment
+enchilada
+endorphin
+energy
+enforcer
+engine
+enhance
+enigmatic
+enjoyably
+enlarged
+enormous
+enquirer
+enrollment
+ensemble
+entryway
+enunciate
+envoy
+enzyme
+epidemic
+equipment
+erasable
+ergonomic
+erratic
+eruption
+escalator
+eskimo
+esophagus
+espresso
+essay
+estrogen
+etching
+eternal
+ethics
+etiquette
+eucalyptus
+eulogy
+euphemism
+euthanize
+evacuation
+evergreen
+evidence
+evolution
+exam
+excerpt
+exerciser
+exfoliate
+exhale
+exist
+exorcist
+explode
+exquisite
+exterior
+exuberant
+fabric
+factory
+faded
+failsafe
+falcon
+family
+fanfare
+fasten
+faucet
+favorite
+feasibly
+february
+federal
+feedback
+feigned
+feline
+femur
+fence
+ferret
+festival
+fettuccine
+feudalist
+feverish
+fiberglass
+fictitious
+fiddle
+figurine
+fillet
+finalist
+fiscally
+fixture
+flashlight
+fleshiness
+flight
+florist
+flypaper
+foamless
+focus
+foggy
+folksong
+fondue
+footpath
+fossil
+fountain
+fox
+fragment
+freeway
+fridge
+frosting
+fruit
+fryingpan
+gadget
+gainfully
+gallstone
+gamekeeper
+gangway
+garlic
+gaslight
+gathering
+gauntlet
+gearbox
+gecko
+gem
+generator
+geographer
+gerbil
+gesture
+getaway
+geyser
+ghoulishly
+gibberish
+giddiness
+giftshop
+gigabyte
+gimmick
+giraffe
+giveaway
+gizmo
+glasses
+gleeful
+glisten
+glove
+glucose
+glycerin
+gnarly
+gnomish
+goatskin
+goggles
+goldfish
+gong
+gooey
+gorgeous
+gosling
+gothic
+gourmet
+governor
+grape
+greyhound
+grill
+groundhog
+grumbling
+guacamole
+guerrilla
+guitar
+gullible
+gumdrop
+gurgling
+gusto
+gutless
+gymnast
+gynecology
+gyration
+habitat
+hacking
+haggard
+haiku
+halogen
+hamburger
+handgun
+happiness
+hardhat
+hastily
+hatchling
+haughty
+hazelnut
+headband
+hedgehog
+hefty
+heinously
+helmet
+hemoglobin
+henceforth
+herbs
+hesitation
+hexagon
+hubcap
+huddling
+huff
+hugeness
+hullabaloo
+human
+hunter
+hurricane
+hushing
+hyacinth
+hybrid
+hydrant
+hygienist
+hypnotist
+ibuprofen
+icepack
+icing
+iconic
+identical
+idiocy
+idly
+igloo
+ignition
+iguana
+illuminate
+imaging
+imbecile
+imitator
+immigrant
+imprint
+iodine
+ionosphere
+ipad
+iphone
+iridescent
+irksome
+iron
+irrigation
+island
+isotope
+issueless
+italicize
+itemizer
+itinerary
+itunes
+ivory
+jabbering
+jackrabbit
+jaguar
+jailhouse
+jalapeno
+jamboree
+janitor
+jarring
+jasmine
+jaundice
+jawbreaker
+jaywalker
+jazz
+jealous
+jeep
+jelly
+jeopardize
+jersey
+jetski
+jezebel
+jiffy
+jigsaw
+jingling
+jobholder
+jockstrap
+jogging
+john
+joinable
+jokingly
+journal
+jovial
+joystick
+jubilant
+judiciary
+juggle
+juice
+jujitsu
+jukebox
+jumpiness
+junkyard
+juror
+justifying
+juvenile
+kabob
+kamikaze
+kangaroo
+karate
+kayak
+keepsake
+kennel
+kerosene
+ketchup
+khaki
+kickstand
+kilogram
+kimono
+kingdom
+kiosk
+kissing
+kite
+kleenex
+knapsack
+kneecap
+knickers
+koala
+krypton
+laboratory
+ladder
+lakefront
+lantern
+laptop
+laryngitis
+lasagna
+latch
+laundry
+lavender
+laxative
+lazybones
+lecturer
+leftover
+leggings
+leisure
+lemon
+length
+leopard
+leprechaun
+lettuce
+leukemia
+levers
+lewdness
+liability
+library
+licorice
+lifeboat
+lightbulb
+likewise
+lilac
+limousine
+lint
+lioness
+lipstick
+liquid
+listless
+litter
+liverwurst
+lizard
+llama
+luau
+lubricant
+lucidity
+ludicrous
+luggage
+lukewarm
+lullaby
+lumberjack
+lunchbox
+luridness
+luscious
+luxurious
+lyrics
+macaroni
+maestro
+magazine
+mahogany
+maimed
+majority
+makeover
+malformed
+mammal
+mango
+mapmaker
+marbles
+massager
+matchstick
+maverick
+maximum
+mayonnaise
+moaning
+mobilize
+moccasin
+modify
+moisture
+molecule
+momentum
+monastery
+moonshine
+mortuary
+mosquito
+motorcycle
+mousetrap
+movie
+mower
+mozzarella
+muckiness
+mudflow
+mugshot
+mule
+mummy
+mundane
+muppet
+mural
+mustard
+mutation
+myriad
+myspace
+myth
+nail
+namesake
+nanosecond
+napkin
+narrator
+nastiness
+natives
+nautically
+navigate
+nearest
+nebula
+nectar
+nefarious
+negotiator
+neither
+nemesis
+neoliberal
+nephew
+nervously
+nest
+netting
+neuron
+nevermore
+nextdoor
+nicotine
+niece
+nimbleness
+nintendo
+nirvana
+nuclear
+nugget
+nuisance
+nullify
+numbing
+nuptials
+nursery
+nutcracker
+nylon
+oasis
+oat
+obediently
+obituary
+object
+obliterate
+obnoxious
+observer
+obtain
+obvious
+occupation
+oceanic
+octopus
+ocular
+office
+oftentimes
+oiliness
+ointment
+older
+olympics
+omissible
+omnivorous
+oncoming
+onion
+onlooker
+onstage
+onward
+onyx
+oomph
+opaquely
+opera
+opium
+opossum
+opponent
+optical
+opulently
+oscillator
+osmosis
+ostrich
+otherwise
+ought
+outhouse
+ovation
+oven
+owlish
+oxford
+oxidize
+oxygen
+oyster
+ozone
+pacemaker
+padlock
+pageant
+pajamas
+palm
+pamphlet
+pantyhose
+paprika
+parakeet
+passport
+patio
+pauper
+pavement
+payphone
+pebble
+peculiarly
+pedometer
+pegboard
+pelican
+penguin
+peony
+pepperoni
+peroxide
+pesticide
+petroleum
+pewter
+pharmacy
+pheasant
+phonebook
+phrasing
+physician
+plank
+pledge
+plotted
+plug
+plywood
+pneumonia
+podiatrist
+poetic
+pogo
+poison
+poking
+policeman
+poncho
+popcorn
+porcupine
+postcard
+poultry
+powerboat
+prairie
+pretzel
+princess
+propeller
+prune
+pry
+pseudo
+psychopath
+publisher
+pucker
+pueblo
+pulley
+pumpkin
+punchbowl
+puppy
+purse
+pushup
+putt
+puzzle
+pyramid
+python
+quarters
+quesadilla
+quilt
+quote
+racoon
+radish
+ragweed
+railroad
+rampantly
+rancidity
+rarity
+raspberry
+ravishing
+rearrange
+rebuilt
+receipt
+reentry
+refinery
+register
+rehydrate
+reimburse
+rejoicing
+rekindle
+relic
+remote
+renovator
+reopen
+reporter
+request
+rerun
+reservoir
+retriever
+reunion
+revolver
+rewrite
+rhapsody
+rhetoric
+rhino
+rhubarb
+rhyme
+ribbon
+riches
+ridden
+rigidness
+rimmed
+riptide
+riskily
+ritzy
+riverboat
+roamer
+robe
+rocket
+romancer
+ropelike
+rotisserie
+roundtable
+royal
+rubber
+rudderless
+rugby
+ruined
+rulebook
+rummage
+running
+rupture
+rustproof
+sabotage
+sacrifice
+saddlebag
+saffron
+sainthood
+saltshaker
+samurai
+sandworm
+sapphire
+sardine
+sassy
+satchel
+sauna
+savage
+saxophone
+scarf
+scenario
+schoolbook
+scientist
+scooter
+scrapbook
+sculpture
+scythe
+secretary
+sedative
+segregator
+seismology
+selected
+semicolon
+senator
+septum
+sequence
+serpent
+sesame
+settler
+severely
+shack
+shelf
+shirt
+shovel
+shrimp
+shuttle
+shyness
+siamese
+sibling
+siesta
+silicon
+simmering
+singles
+sisterhood
+sitcom
+sixfold
+sizable
+skateboard
+skeleton
+skies
+skulk
+skylight
+slapping
+sled
+slingshot
+sloth
+slumbering
+smartphone
+smelliness
+smitten
+smokestack
+smudge
+snapshot
+sneezing
+sniff
+snowsuit
+snugness
+speakers
+sphinx
+spider
+splashing
+sponge
+sprout
+spur
+spyglass
+squirrel
+statue
+steamboat
+stingray
+stopwatch
+strawberry
+student
+stylus
+suave
+subway
+suction
+suds
+suffocate
+sugar
+suitcase
+sulphur
+superstore
+surfer
+sushi
+swan
+sweatshirt
+swimwear
+sword
+sycamore
+syllable
+symphony
+synagogue
+syringes
+systemize
+tablespoon
+taco
+tadpole
+taekwondo
+tagalong
+takeout
+tallness
+tamale
+tanned
+tapestry
+tarantula
+tastebud
+tattoo
+tavern
+thaw
+theater
+thimble
+thorn
+throat
+thumb
+thwarting
+tiara
+tidbit
+tiebreaker
+tiger
+timid
+tinsel
+tiptoeing
+tirade
+tissue
+tractor
+tree
+tripod
+trousers
+trucks
+tryout
+tubeless
+tuesday
+tugboat
+tulip
+tumbleweed
+tupperware
+turtle
+tusk
+tutorial
+tuxedo
+tweezers
+twins
+tyrannical
+ultrasound
+umbrella
+umpire
+unarmored
+unbuttoned
+uncle
+underwear
+unevenness
+unflavored
+ungloved
+unhinge
+unicycle
+unjustly
+unknown
+unlocking
+unmarked
+unnoticed
+unopened
+unpaved
+unquenched
+unroll
+unscrewing
+untied
+unusual
+unveiled
+unwrinkled
+unyielding
+unzip
+upbeat
+upcountry
+update
+upfront
+upgrade
+upholstery
+upkeep
+upload
+uppercut
+upright
+upstairs
+uptown
+upwind
+uranium
+urban
+urchin
+urethane
+urgent
+urologist
+username
+usher
+utensil
+utility
+utmost
+utopia
+utterance
+vacuum
+vagrancy
+valuables
+vanquished
+vaporizer
+varied
+vaseline
+vegetable
+vehicle
+velcro
+vendor
+vertebrae
+vestibule
+veteran
+vexingly
+vicinity
+videogame
+viewfinder
+vigilante
+village
+vinegar
+violin
+viperfish
+virus
+visor
+vitamins
+vivacious
+vixen
+vocalist
+vogue
+voicemail
+volleyball
+voucher
+voyage
+vulnerable
+waffle
+wagon
+wakeup
+walrus
+wanderer
+wasp
+water
+waving
+wheat
+whisper
+wholesaler
+wick
+widow
+wielder
+wifeless
+wikipedia
+wildcat
+windmill
+wipeout
+wired
+wishbone
+wizardry
+wobbliness
+wolverine
+womb
+woolworker
+workbasket
+wound
+wrangle
+wreckage
+wristwatch
+wrongdoing
+xerox
+xylophone
+yacht
+yahoo
+yard
+yearbook
+yesterday
+yiddish
+yield
+yo-yo
+yodel
+yogurt
+yuppie
+zealot
+zebra
+zeppelin
+zestfully
+zigzagged
+zillion
+zipping
+zirconium
+zodiac
+zombie
+zookeeper
+zucchini
diff --git a/desktop/src-tauri/src/commands/agent_discovery.rs b/desktop/src-tauri/src/commands/agent_discovery.rs
index d6429e0454..cbbf4ce351 100644
--- a/desktop/src-tauri/src/commands/agent_discovery.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery.rs
@@ -236,10 +236,12 @@ pub async fn install_acp_runtime(
     // returns (Guard impl Drop) — so Phase 2's restart path runs outside
     // the guard and cannot re-enter the mutex.
     let runtime_id_clone = runtime_id.clone();
-    let install_result =
-        tokio::task::spawn_blocking(move || install_acp_runtime_blocking(&runtime_id_clone))
-            .await
-            .map_err(|e| format!("install task panicked: {e}"))??;
+    let app_clone = app.clone();
+    let install_result = tokio::task::spawn_blocking(move || {
+        install_acp_runtime_blocking(&runtime_id_clone, &app_clone)
+    })
+    .await
+    .map_err(|e| format!("install task panicked: {e}"))??;
 
     if !install_result.success {
         return Ok(install_result);
@@ -259,12 +261,21 @@ pub async fn install_acp_runtime(
         steps: install_result.steps,
         restarted_count,
         failed_restart_count,
+        log_path: install_result.log_path,
     })
 }
 
 /// Err(_) = infrastructure failure (panic, concurrency guard).
 /// Ok({success: false}) = an install step failed (stderr captured in steps).
-fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult, String> {
+///
+/// The reporter is built here rather than by the caller so this run's log
+/// session starts only once the concurrency guard is held and the runtime id is
+/// resolved to its canonical catalog form: a rejected install must not rotate a
+/// running one's log, and the log filename is derived from that id.
+fn install_acp_runtime_blocking(
+    runtime_id: &str,
+    app: &tauri::AppHandle,
+) -> Result<InstallRuntimeResult, String> {
     // Re-fetch the login-shell PATH so a Node.js installation that happened
     // after app launch (or after a previous failed install) is visible to this
     // run and to the subsequent discover_acp_providers call.
@@ -297,6 +308,8 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
     let runtime = crate::managed_agents::known_acp_runtime_exact(runtime_id)
         .ok_or_else(|| format!("unknown runtime: {runtime_id}"))?;
 
+    let reporter = InstallReporter::for_run(app, runtime.id);
+
     let mut steps = Vec::new();
 
     // Phase 1: Install CLI if missing and commands are available.
@@ -306,16 +319,11 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
     if let Some(cli) = runtime.underlying_cli {
         if crate::managed_agents::resolve_command(cli).is_none() {
             for cmd in runtime.cli_install_commands_for_os() {
-                let result = run_install_command_with_retry("cli", cmd);
+                let result = run_install_command_with_retry("cli", cmd, &reporter);
                 let success = result.success;
                 steps.push(result);
                 if !success {
-                    return Ok(InstallRuntimeResult {
-                        success: false,
-                        steps,
-                        restarted_count: 0,
-                        failed_restart_count: 0,
-                    });
+                    return Ok(reporter.failed(steps));
                 }
             }
         }
@@ -340,13 +348,8 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
             cmds.iter().any(|cmd| is_npm_global_install(cmd)) && managed_node_runtime_supported();
         if use_managed_npm {
             if let Err(step) = ensure_managed_node_runtime_blocking() {
-                steps.push(*step);
-                return Ok(InstallRuntimeResult {
-                    success: false,
-                    steps,
-                    restarted_count: 0,
-                    failed_restart_count: 0,
-                });
+                reporter.record_step(&mut steps, *step);
+                return Ok(reporter.failed(steps));
             }
         }
 
@@ -359,40 +362,31 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
                 Ok(Some(command)) => command,
                 Ok(None) => cmd.to_string(),
                 Err(step) => {
-                    steps.push(*step);
-                    return Ok(InstallRuntimeResult {
-                        success: false,
-                        steps,
-                        restarted_count: 0,
-                        failed_restart_count: 0,
-                    });
+                    reporter.record_step(&mut steps, *step);
+                    return Ok(reporter.failed(steps));
                 }
             };
 
-            let mut result = run_install_command_with_retry("adapter", &planned);
+            let mut result = run_install_command_with_retry("adapter", &planned, &reporter);
             if !result.success && result.hint.is_none() && is_npm_global_install(cmd) {
                 result.hint = npm_eacces_hint(&result.stderr, cmd);
             }
             let success = result.success;
             steps.push(result);
             if !success {
-                return Ok(InstallRuntimeResult {
-                    success: false,
-                    steps,
-                    restarted_count: 0,
-                    failed_restart_count: 0,
-                });
+                return Ok(reporter.failed(steps));
             }
         }
     }
 
-    post_install_verification::run(runtime_id, &mut steps);
+    post_install_verification::run(runtime_id, &mut steps, &reporter);
 
     Ok(InstallRuntimeResult {
         success: steps.iter().all(|step| step.success),
         steps,
         restarted_count: 0,
         failed_restart_count: 0,
+        log_path: reporter.log_path(),
     })
 }
 
@@ -1016,8 +1010,11 @@ fn build_install_command(command: &str) -> Result<std::process::Command, String>
 }
 
 // ── install command execution ─────────────────────────────────────────────────
+mod install_capture;
 mod install_exec;
+mod install_report;
 use install_exec::run_install_command_with_retry;
+use install_report::InstallReporter;
 
 // ── managed Node/npm runtime ──────────────────────────────────────────────────
 mod managed_node;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs b/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs
new file mode 100644
index 0000000000..903b68715a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs
@@ -0,0 +1,319 @@
+//! Bounded capture of an install command's output.
+//!
+//! One drain per stream feeds a [`Capture`], which holds two independently
+//! bounded views of the same bytes: a small one sized for an error toast and a
+//! large one sized for the install log file. Both are shared with the draining
+//! reader rather than returned by it, so whatever arrived before a stall is
+//! readable at the ceiling — exactly when the output matters most.
+
+use std::collections::VecDeque;
+use std::io::Read;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+/// How much of each end a capture keeps, and how it names what was cut.
+#[derive(Clone, Copy)]
+struct Caps {
+    head: usize,
+    tail: usize,
+    marker: fn(usize) -> String,
+}
+
+/// Sized for a UI error message: enough to identify the failure, small enough
+/// to read in a toast.
+const UI_CAPS: Caps = Caps {
+    head: 512,
+    tail: 1024,
+    marker: |omitted| format!("... ({omitted} bytes omitted) ..."),
+};
+
+/// Sized for the log file, where the budget is disk rather than screen. At this
+/// cap a real install log is complete in practice; the marker names the cases
+/// where it is not, so the file never implies completeness it does not have.
+const LOG_CAPS: Caps = Caps {
+    head: 128 * 1024,
+    tail: 128 * 1024,
+    marker: |omitted| format!("... [{omitted} bytes omitted at cap] ..."),
+};
+
+/// Bounded capture of one stream: its first `head` bytes, its last `tail`
+/// bytes, and the total byte count. Output of any size costs a fixed amount of
+/// memory, so an installer that prints megabytes cannot grow the process.
+struct BoundedOutput {
+    head: Vec<u8>,
+    tail: VecDeque<u8>,
+    total: usize,
+    caps: Caps,
+}
+
+type SharedOutput = Arc<Mutex<BoundedOutput>>;
+
+impl BoundedOutput {
+    fn shared(caps: Caps) -> SharedOutput {
+        Arc::new(Mutex::new(Self {
+            head: Vec::new(),
+            tail: VecDeque::new(),
+            total: 0,
+            caps,
+        }))
+    }
+
+    /// Absorb one read. Chunk boundaries are irrelevant to the result: the head
+    /// fills first, the remainder rolls through the tail window.
+    fn push(&mut self, chunk: &[u8]) {
+        self.total += chunk.len();
+        let head_room = self
+            .caps
+            .head
+            .saturating_sub(self.head.len())
+            .min(chunk.len());
+        let (head_part, tail_part) = chunk.split_at(head_room);
+        self.head.extend_from_slice(head_part);
+        self.tail.extend(tail_part);
+        while self.tail.len() > self.caps.tail {
+            self.tail.pop_front();
+        }
+    }
+
+    fn render(&self) -> String {
+        let tail: Vec<u8> = self.tail.iter().copied().collect();
+        if self.total <= self.caps.head + self.caps.tail {
+            // Nothing was dropped, so head followed by tail is the whole stream.
+            let mut whole = self.head.clone();
+            whole.extend_from_slice(&tail);
+            return decode(&whole);
+        }
+        // Both ends are cut at arbitrary byte offsets, so trim any partial
+        // character rather than emitting replacement chars, then drop the
+        // partial *token* each cut left behind. The marker counts every dropped
+        // byte, including both trims.
+        let head = erode_head(utf8_prefix(&self.head));
+        let tail = erode_tail(utf8_suffix(&tail));
+        let omitted = self.total - head.len() - tail.len();
+        format!(
+            "{}\n{}\n{}",
+            decode(head),
+            (self.caps.marker)(omitted),
+            decode(tail)
+        )
+    }
+}
+
+/// The two bounded views of one stream, filled by a single drain.
+pub(super) struct Capture {
+    ui: SharedOutput,
+    log: SharedOutput,
+}
+
+impl Capture {
+    pub(super) fn new() -> Self {
+        Self {
+            ui: BoundedOutput::shared(UI_CAPS),
+            log: BoundedOutput::shared(LOG_CAPS),
+        }
+    }
+
+    /// What the UI shows for this stream.
+    pub(super) fn ui(&self) -> String {
+        render(&self.ui)
+    }
+
+    /// What the install log records for this stream.
+    pub(super) fn log(&self) -> String {
+        render(&self.log)
+    }
+
+    fn push(&self, chunk: &[u8]) {
+        for sink in [&self.ui, &self.log] {
+            if let Ok(mut sink) = sink.lock() {
+                sink.push(chunk);
+            }
+        }
+    }
+}
+
+/// Called with each complete line an install prints, for the live output line
+/// in the UI. Shared across both drain threads of one attempt.
+pub(super) type LineObserver = Arc<dyn Fn(&str) + Send + Sync>;
+
+/// Render a capture even if its drain thread panicked mid-write — a poisoned
+/// lock must not cost the diagnostics.
+fn render(sink: &SharedOutput) -> String {
+    sink.lock().unwrap_or_else(|p| p.into_inner()).render()
+}
+
+/// Read `pipe` to EOF, feeding fixed-size chunks into `capture` and each
+/// complete line to `observer`. Read errors end the drain — a broken pipe means
+/// the child is gone and there is nothing left to capture.
+pub(super) fn drain_into(mut pipe: impl Read, capture: &Capture, observer: Option<&LineObserver>) {
+    let mut chunk = [0u8; 8192];
+    let mut lines = LineSplitter::default();
+    loop {
+        match pipe.read(&mut chunk) {
+            Ok(0) => return,
+            Ok(n) => {
+                capture.push(&chunk[..n]);
+                if let Some(observe) = observer {
+                    lines.feed(&chunk[..n], |line| observe(line));
+                }
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
+            Err(_) => return,
+        }
+    }
+}
+
+/// Reassembles lines from arbitrary read chunks. A partial trailing line is
+/// held until its newline arrives, so an observer only ever sees complete
+/// lines. The buffer is capped: a program that prints megabytes without a
+/// newline must not grow it without bound.
+#[derive(Default)]
+struct LineSplitter {
+    partial: Vec<u8>,
+}
+
+impl LineSplitter {
+    /// Longest line reassembled. Beyond this the excess is dropped, since the
+    /// consumer displays a single truncated line anyway.
+    const MAX_LINE: usize = 4096;
+
+    fn feed(&mut self, chunk: &[u8], mut emit: impl FnMut(&str)) {
+        for byte in chunk {
+            if *byte == b'\n' {
+                let line = String::from_utf8_lossy(&self.partial).trim().to_string();
+                self.partial.clear();
+                if !line.is_empty() {
+                    emit(&line);
+                }
+            } else if self.partial.len() < Self::MAX_LINE {
+                self.partial.push(*byte);
+            }
+        }
+    }
+}
+
+/// Rate limiter for the live output line: at most one event per
+/// `min_interval`.
+///
+/// A line arriving inside the window is *held* rather than dropped, and the
+/// newest held line replaces any older one. Dropping was wrong at two points:
+/// the last line of an attempt — typically the failure that caused the retry —
+/// vanished if it landed inside the window, and so did a new attempt's first
+/// line when it arrived within 250ms of the previous attempt's last.
+pub(super) struct Throttle {
+    min_interval: Duration,
+    state: Mutex<ThrottleState>,
+}
+
+#[derive(Default)]
+struct ThrottleState {
+    last_emitted: Option<Instant>,
+    pending: Option<String>,
+}
+
+impl Throttle {
+    pub(super) fn new(min_interval: Duration) -> Self {
+        Self {
+            min_interval,
+            state: Mutex::new(ThrottleState::default()),
+        }
+    }
+
+    /// Offer one line. `Some` means emit it now; `None` means it is held as the
+    /// newest pending line, to be emitted by [`Throttle::take_pending`] or
+    /// replaced by a line that supersedes it.
+    pub(super) fn offer(&self, line: &str, now: Instant) -> Option<String> {
+        let Ok(mut state) = self.state.lock() else {
+            return None;
+        };
+        if state
+            .last_emitted
+            .is_some_and(|prev| now.duration_since(prev) < self.min_interval)
+        {
+            state.pending = Some(line.to_string());
+            return None;
+        }
+        state.last_emitted = Some(now);
+        // Emitting a newer line makes the held one obsolete: the display shows
+        // one line, and it must be the latest.
+        state.pending = None;
+        Some(line.to_string())
+    }
+
+    /// Take the held line, if the window closed on one.
+    pub(super) fn take_pending(&self) -> Option<String> {
+        self.state.lock().ok()?.pending.take()
+    }
+
+    /// Open the window for a new attempt, so its first line is emitted
+    /// immediately instead of waiting out the previous attempt's window.
+    pub(super) fn restart(&self) {
+        if let Ok(mut state) = self.state.lock() {
+            *state = ThrottleState::default();
+        }
+    }
+}
+
+fn decode(bytes: &[u8]) -> String {
+    String::from_utf8_lossy(bytes).into_owned()
+}
+
+/// Drop a trailing partial UTF-8 sequence, keeping mid-stream invalid bytes for
+/// the lossy decode to mark.
+fn utf8_prefix(bytes: &[u8]) -> &[u8] {
+    match std::str::from_utf8(bytes) {
+        Ok(_) => bytes,
+        Err(e) if e.error_len().is_none() => &bytes[..e.valid_up_to()],
+        Err(_) => bytes,
+    }
+}
+
+/// Drop leading UTF-8 continuation bytes — at most three can precede a
+/// character start.
+fn utf8_suffix(bytes: &[u8]) -> &[u8] {
+    let start = bytes
+        .iter()
+        .take(3)
+        .take_while(|b| *b & 0b1100_0000 == 0b1000_0000)
+        .count();
+    &bytes[start..]
+}
+
+/// How far a cut edge looks for a token boundary. Sized past any credential
+/// shape worth protecting (an `nsec1` key is 63 bytes, registry tokens are
+/// shorter) and short enough that erosion costs a token rather than a chunk of
+/// output. A cut inside a longer whitespace-free run is left alone: erasing
+/// kilobytes of a single-token stream would cost more diagnostics than the
+/// fragment could leak.
+const MAX_ERODED_TOKEN: usize = 256;
+
+/// Drop the partial token a head cut left at its end.
+///
+/// Redaction runs on the rendered text and matches whole tokens: a prefixed
+/// secret up to the next whitespace, or an exact env value. A cut through the
+/// middle of a secret leaves a fragment that matches neither and therefore
+/// survives scrubbing, so the fragment is removed here instead — at the cut,
+/// where it is still identifiable as partial. The omitted-byte marker counts
+/// what this drops.
+fn erode_head(bytes: &[u8]) -> &[u8] {
+    let window = bytes.len().saturating_sub(MAX_ERODED_TOKEN);
+    match bytes[window..].iter().rposition(u8::is_ascii_whitespace) {
+        Some(last) => &bytes[..=window + last],
+        None => bytes,
+    }
+}
+
+/// Drop the partial token a tail cut left at its start — the direction that
+/// matters most, since a fragment there has lost the `nsec1`-style prefix the
+/// scrubber keys on. See [`erode_head`].
+fn erode_tail(bytes: &[u8]) -> &[u8] {
+    let window = MAX_ERODED_TOKEN.min(bytes.len());
+    match bytes[..window].iter().position(u8::is_ascii_whitespace) {
+        Some(first) => &bytes[first..],
+        None => bytes,
+    }
+}
+
+#[cfg(test)]
+#[path = "install_capture_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs
new file mode 100644
index 0000000000..8830f355df
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs
@@ -0,0 +1,437 @@
+use super::*;
+
+/// Feed `chunks` through a capture in order.
+fn capture_of(chunks: &[&[u8]]) -> Capture {
+    let capture = Capture::new();
+    for chunk in chunks {
+        capture.push(chunk);
+    }
+    capture
+}
+
+/// Render what the UI would show for a stream of `chunks`.
+fn ui(chunks: &[&[u8]]) -> String {
+    capture_of(chunks).ui()
+}
+
+// ── bounded capture ──────────────────────────────────────────────────────────
+
+/// Output within the cap is passed through byte-for-byte — no marker, no loss.
+#[test]
+fn test_capture_leaves_short_output_untouched() {
+    let short = "a".repeat(1536);
+
+    assert_eq!(ui(&[short.as_bytes()]), short);
+}
+
+/// Over the cap, both ends survive and the middle is replaced by a marker
+/// naming the omitted byte count — the head keeps the command's opening
+/// context and the tail keeps the error that usually trails.
+#[test]
+fn test_capture_over_cap_keeps_head_and_tail_with_marker() {
+    let input = format!(
+        "{}{}{}",
+        "H".repeat(512),
+        "M".repeat(4000),
+        "T".repeat(1024)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with(&"H".repeat(512)));
+    assert!(out.ends_with(&"T".repeat(1024)));
+    assert!(
+        out.contains("... (4000 bytes omitted) ..."),
+        "marker must name the omitted byte count, got: {out}"
+    );
+}
+
+/// The rendered result depends only on the byte stream, not on how the reads
+/// happened to split it — a real drain sees arbitrary chunk sizes.
+#[test]
+fn test_capture_is_independent_of_chunk_boundaries() {
+    let input = "x".repeat(9000);
+    let one_shot = ui(&[input.as_bytes()]);
+
+    let chunked: Vec<&[u8]> = input.as_bytes().chunks(7).collect();
+
+    assert_eq!(ui(&chunked), one_shot);
+}
+
+/// Truncation must not split a multi-byte character. Both cut points land
+/// mid-codepoint here; the partial bytes are dropped rather than decoded into
+/// replacement chars.
+#[test]
+fn test_capture_does_not_split_multibyte_characters() {
+    // "é" is 2 bytes, so every candidate cut index lands mid-character.
+    let input = "é".repeat(4000);
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.contains("bytes omitted"), "input must exceed the cap");
+    assert!(!out.contains('\u{fffd}'), "no replacement chars: {out}");
+}
+
+/// Memory stays flat regardless of how much the installer prints: the rendered
+/// UI result of a 4MiB stream is no larger than that of a 6KiB one.
+#[test]
+fn test_capture_of_huge_output_stays_bounded() {
+    let chunk = vec![b'z'; 8192];
+
+    let capture = Capture::new();
+    for _ in 0..512 {
+        capture.push(&chunk);
+    }
+
+    let out = capture.ui();
+    assert!(
+        out.len() < 2048,
+        "4MiB of output must render bounded, got {} bytes",
+        out.len()
+    );
+    assert!(out.contains("bytes omitted"));
+}
+
+// ── the log view is separately bounded ───────────────────────────────────────
+
+/// The log view holds output the UI view had to cut. A toast is capped for
+/// readability; the log file's budget is disk, and "Full log: {path}" has to
+/// point at more than the toast already showed.
+#[test]
+fn test_log_view_keeps_output_the_ui_view_truncates() {
+    let input = format!("start{}end", "m".repeat(64 * 1024));
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    assert!(
+        capture.ui().contains("bytes omitted"),
+        "64KiB must exceed the UI cap"
+    );
+    assert_eq!(
+        capture.log(),
+        input,
+        "the same output must be complete in the log view"
+    );
+}
+
+/// Even the log view is bounded — a runaway installer cannot fill the disk —
+/// and when it does cut, the record says so inline at the cap rather than
+/// implying completeness.
+#[test]
+fn test_log_view_is_bounded_and_marks_its_cap() {
+    let head = "H".repeat(128 * 1024);
+    let middle = "M".repeat(5000);
+    let tail = "T".repeat(128 * 1024);
+    let input = format!("{head}{middle}{tail}");
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    let out = capture.log();
+    assert!(
+        out.len() < 300 * 1024,
+        "output past the log cap must render bounded, got {} bytes",
+        out.len()
+    );
+    assert!(out.starts_with(&head), "the log head must survive intact");
+    assert!(out.ends_with(&tail), "the log tail must survive intact");
+    assert!(
+        out.contains("... [5000 bytes omitted at cap] ..."),
+        "a cut log record must name the cap inline, got the middle: {}",
+        &out[128 * 1024..(128 * 1024 + 64).min(out.len())]
+    );
+}
+
+/// The two views mark their cuts differently on purpose: the toast reads as
+/// prose, the log record reads as a machine-scannable annotation.
+#[test]
+fn test_ui_and_log_views_use_their_own_cap_markers() {
+    let input = "x".repeat(300 * 1024);
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    assert!(
+        capture.ui().contains("bytes omitted) ..."),
+        "the UI marker reads as prose: {}",
+        capture.ui()
+    );
+    assert!(capture.log().contains("bytes omitted at cap] ..."));
+}
+
+// ── line observation ─────────────────────────────────────────────────────────
+
+/// Collect the lines a drain over `chunks` reports.
+fn observed_lines(chunks: &[&[u8]]) -> Vec<String> {
+    let seen: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+    let observer: LineObserver = {
+        let seen = Arc::clone(&seen);
+        Arc::new(move |line: &str| seen.lock().unwrap().push(line.to_string()))
+    };
+    let bytes: Vec<u8> = chunks.concat();
+
+    drain_into(bytes.as_slice(), &Capture::new(), Some(&observer));
+
+    let observed = seen.lock().unwrap().clone();
+    observed
+}
+
+/// The observer sees complete lines, reassembled across the read boundaries
+/// that split them — a live output line must never show half a word.
+#[test]
+fn test_observer_reassembles_lines_split_across_reads() {
+    let lines = observed_lines(&[b"downloa", b"ding 40%\nunpack", b"ing\n"]);
+
+    assert_eq!(lines, vec!["downloading 40%", "unpacking"]);
+}
+
+/// A trailing line with no newline is never reported: it may still be growing,
+/// and showing a half-line as if complete is worse than showing the previous
+/// one.
+#[test]
+fn test_observer_withholds_a_line_that_has_no_newline_yet() {
+    let lines = observed_lines(&[b"complete\n", b"still-writing"]);
+
+    assert_eq!(lines, vec!["complete"]);
+}
+
+/// Blank lines carry nothing to display; progress output is full of them.
+#[test]
+fn test_observer_skips_blank_lines() {
+    let lines = observed_lines(&[b"a\n\n  \nb\n"]);
+
+    assert_eq!(lines, vec!["a", "b"]);
+}
+
+/// A pathological line with no newline must not grow the buffer without bound.
+#[test]
+fn test_observer_caps_a_pathologically_long_line() {
+    let huge = "x".repeat(100_000);
+
+    let lines = observed_lines(&[huge.as_bytes(), b"\n"]);
+
+    assert_eq!(lines.len(), 1);
+    assert!(
+        lines[0].len() <= LineSplitter::MAX_LINE,
+        "line must be capped, got {} bytes",
+        lines[0].len()
+    );
+}
+
+/// A drain with no observer still captures — the log and UI views do not
+/// depend on anyone watching.
+#[test]
+fn test_drain_captures_without_an_observer() {
+    let capture = Capture::new();
+
+    drain_into(b"hello\n".as_slice(), &capture, None);
+
+    assert_eq!(capture.ui(), "hello\n");
+}
+
+// ── throttle ─────────────────────────────────────────────────────────────────
+
+/// The first line goes out immediately, and one arriving inside the window is
+/// *held* rather than dropped: it becomes the pending line, so the newest output
+/// survives the rate limit instead of vanishing.
+#[test]
+fn test_throttle_emits_the_first_line_and_holds_the_next_in_window() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+
+    assert_eq!(throttle.offer("first", start), Some("first".to_string()));
+    assert_eq!(
+        throttle.offer("second", start + Duration::from_millis(100)),
+        None
+    );
+    assert_eq!(
+        throttle.take_pending(),
+        Some("second".to_string()),
+        "the line inside the window must be retained, not dropped"
+    );
+}
+
+/// A burst inside one window collapses to its newest line: the display shows a
+/// single line, so an older held line has no value once a newer one exists.
+#[test]
+fn test_throttle_keeps_only_the_newest_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("emitted", start);
+
+    throttle.offer("held-then-superseded", start + Duration::from_millis(50));
+    throttle.offer("newest", start + Duration::from_millis(100));
+
+    assert_eq!(throttle.take_pending(), Some("newest".to_string()));
+}
+
+/// Once the window passes, emission resumes and nothing is left pending — the
+/// emitted line *is* the newest, so holding it too would emit it twice.
+#[test]
+fn test_throttle_emits_again_after_the_window_and_clears_the_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+    throttle.offer("held", start + Duration::from_millis(50));
+
+    assert_eq!(
+        throttle.offer("later", start + Duration::from_millis(300)),
+        Some("later".to_string())
+    );
+
+    assert_eq!(
+        throttle.take_pending(),
+        None,
+        "a line emitted after the window supersedes the held one"
+    );
+}
+
+/// The window is measured from the last *emitted* line, not the last offer: a
+/// stream of held lines must not extend the silence.
+#[test]
+fn test_throttle_window_runs_from_the_last_emission() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+
+    assert_eq!(
+        throttle.offer("held", start + Duration::from_millis(200)),
+        None
+    );
+
+    assert_eq!(
+        throttle.offer("next", start + Duration::from_millis(260)),
+        Some("next".to_string()),
+        "a held line must not restart the window"
+    );
+}
+
+/// A pending line is taken once. Taking it twice would re-emit a line the
+/// display already shows.
+#[test]
+fn test_throttle_yields_a_held_line_only_once() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+    throttle.offer("held", start + Duration::from_millis(50));
+
+    assert_eq!(throttle.take_pending(), Some("held".to_string()));
+
+    assert_eq!(throttle.take_pending(), None);
+}
+
+/// Restarting opens the window immediately, which is what lets a new attempt's
+/// first line go out even when it arrives inside the previous attempt's window.
+/// It also discards a held line: that line belongs to the attempt that just
+/// ended, and the new attempt is about to clear the display.
+#[test]
+fn test_throttle_restart_opens_the_window_and_discards_the_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("previous attempt", start);
+    throttle.offer("held", start + Duration::from_millis(10));
+
+    throttle.restart();
+
+    assert_eq!(throttle.take_pending(), None);
+    assert_eq!(
+        throttle.offer("new attempt", start + Duration::from_millis(20)),
+        Some("new attempt".to_string())
+    );
+}
+
+// ── cut-edge erosion ─────────────────────────────────────────────────────────
+
+/// A secret cut in half by the head cap must not survive as a fragment.
+/// Redaction matches whole tokens — a prefixed secret up to the next whitespace
+/// — so `nsec1qqq…` cut mid-value would still be scrubbed, but the *tail* of
+/// that same value, having lost its prefix, would not be. Both cut edges drop
+/// their partial token for that reason.
+#[test]
+fn test_capture_drops_the_partial_token_at_each_cut_edge() {
+    // Positioned so the head cap lands inside the first secret and the tail cap
+    // inside the second.
+    let head_secret = "nsec1headsecretvalue";
+    let tail_secret = "nsec1tailsecretvalue";
+    let input = format!(
+        "{} {head_secret} {} {tail_secret} {}",
+        "h".repeat(500),
+        "m".repeat(4000),
+        "t".repeat(1010)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.contains("bytes omitted"), "input must exceed the cap");
+    for fragment in ["nsec1head", "secretvalue"] {
+        assert!(
+            !out.contains(fragment),
+            "a fragment of a cut token must not survive: {out}"
+        );
+    }
+}
+
+/// Erosion stops at the nearest whitespace, so it costs one partial token and
+/// not the surrounding output — the head's earlier lines and the tail's later
+/// ones are what make a truncated capture readable.
+#[test]
+fn test_capture_erosion_keeps_the_complete_tokens_around_the_cut() {
+    let input = format!(
+        "opening line
+{}
+cut-here-head{}cut-here-tail
+{}
+closing line
+",
+        "h".repeat(480),
+        "m".repeat(4000),
+        "t".repeat(980)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with("opening line\n"), "got: {out}");
+    assert!(out.ends_with("closing line\n"), "got: {out}");
+}
+
+/// A cut inside a whitespace-free run longer than the erosion window is left
+/// intact. Erosion is bounded on purpose: erasing kilobytes of a single-token
+/// stream — `npm` progress bars and base64 payloads both look like this — would
+/// cost more diagnostics than a fragment of one could leak.
+#[test]
+fn test_capture_of_one_giant_token_keeps_its_cut_edges() {
+    let input = "x".repeat(4000);
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with(&"x".repeat(512)), "got: {out}");
+    assert!(out.ends_with(&"x".repeat(1024)), "got: {out}");
+}
+
+/// The marker's byte count stays honest across erosion: what it names as omitted
+/// must equal the input minus what is actually shown, or a reader cannot trust
+/// the file to say how much is missing.
+#[test]
+fn test_capture_marker_counts_the_bytes_erosion_dropped() {
+    let input = format!(
+        "{} {} {}",
+        "h".repeat(600),
+        "m".repeat(4000),
+        "t".repeat(1100)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    let (head, rest) = out.split_once('\n').expect("a marker line");
+    let (marker, tail) = rest.split_once('\n').expect("a marker line");
+    let omitted: usize = marker
+        .trim_start_matches("... (")
+        .split_once(' ')
+        .expect("a byte count")
+        .0
+        .parse()
+        .expect("a byte count");
+    assert_eq!(
+        head.len() + omitted + tail.len(),
+        input.len(),
+        "shown + omitted must account for every input byte"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs b/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
index 63163ceadc..3b94f2ef8a 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
@@ -5,13 +5,46 @@
 //! `install_powershell_command`, `build_install_command`); this module owns
 //! only what happens once a `Command` exists.
 
-use std::io::Read;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
 
+use super::install_capture::{drain_into, Capture, LineObserver};
+use super::install_report::{InstallOutcome, InstallReporter};
 use crate::managed_agents::InstallStepResult;
 
 /// Maximum number of attempts for a transient-looking install command.
 const INSTALL_MAX_ATTEMPTS: u32 = 3;
 
+/// Absolute wall-clock ceiling for a single install command.
+///
+/// This is a ceiling, not an inactivity timeout: nothing observable
+/// distinguishes a hung installer from one silently transferring a large
+/// artifact (the Goose step downloads a ~79MB release asset with no progress
+/// output, and npm at its default log level prints only at the end), so silence
+/// alone never kills an install. The previous 300s wall killed
+/// slow-but-working installs — Windows Defender scanning every file npm
+/// extracts pushes past it routinely (#2401).
+///
+/// The cost of a larger ceiling: skipping onboarding does not cancel a running
+/// install and a per-runtime guard rejects a second one, so this is also the
+/// longest a user who skipped a genuinely *hung* install waits before Install
+/// works again in Settings. User-facing cancellation is the product-level fix.
+const INSTALL_TIMEOUT: Duration = Duration::from_secs(900);
+
+/// How long the group gets to exit on SIGTERM before the ceiling escalates to
+/// SIGKILL.
+#[cfg(unix)]
+const TERM_GRACE: Duration = Duration::from_secs(1);
+
+/// How long the ceiling waits after killing the install's process group —
+/// applied separately to reaping the killed child and to the output drains
+/// finishing. The kill closes the pipe write ends, so both normally complete
+/// within microseconds; the bound covers the cases where they don't (a process
+/// that escaped the group and still holds a pipe, or a termination that failed
+/// outright). Neither may hold the install — nor the per-runtime concurrency
+/// guard behind it — open past the ceiling.
+const POST_KILL_GRACE: Duration = Duration::from_secs(2);
+
 /// Run an install command, retrying transient failures with backoff.
 ///
 /// Runtime installs pull artifacts over the network — Goose's `curl … | bash`
@@ -22,10 +55,24 @@ const INSTALL_MAX_ATTEMPTS: u32 = 3;
 /// `INSTALL_MAX_ATTEMPTS` times. Failures with no exit code — a timeout or a
 /// shell that never spawned — are not retried, since re-running them just costs
 /// the user more time without a plausible path to success.
-pub(super) fn run_install_command_with_retry(step: &str, command: &str) -> InstallStepResult {
+///
+/// Every attempt is recorded through `reporter`, so the install log holds the
+/// full retry history even though the UI only ever sees the last attempt.
+pub(super) fn run_install_command_with_retry(
+    step: &str,
+    command: &str,
+    reporter: &InstallReporter,
+) -> InstallStepResult {
     run_install_with_retry(
         INSTALL_MAX_ATTEMPTS,
-        |_attempt| run_install_command(step, command),
+        |attempt| {
+            // Before the command spawns, so the previous attempt's last line
+            // stops being displayed for the whole backoff rather than until the
+            // new attempt happens to print something.
+            reporter.start_attempt();
+            let outcome = run_install_command(step, command, reporter.line_observer());
+            reporter.record_attempt(attempt, outcome)
+        },
         std::thread::sleep,
     )
 }
@@ -92,11 +139,15 @@ fn prepare_install_command(command: &str) -> Result<std::process::Command, Strin
     Ok(cmd)
 }
 
-fn run_install_command(step: &str, command: &str) -> InstallStepResult {
+fn run_install_command(
+    step: &str,
+    command: &str,
+    observer: Option<LineObserver>,
+) -> InstallOutcome {
     let mut cmd = match prepare_install_command(command) {
         Ok(cmd) => cmd,
         Err(hint) => {
-            return InstallStepResult {
+            return InstallOutcome::synthesized(InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
                 success: false,
@@ -104,11 +155,11 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
                 stderr: "no suitable shell found for install commands".to_string(),
                 exit_code: None,
                 hint: Some(hint),
-            };
+            });
         }
     };
 
-    let mut child = match cmd
+    let child = match cmd
         .stdin(std::process::Stdio::null())
         .stdout(std::process::Stdio::piped())
         .stderr(std::process::Stdio::piped())
@@ -116,7 +167,7 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
     {
         Ok(child) => child,
         Err(e) => {
-            return InstallStepResult {
+            return InstallOutcome::synthesized(InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
                 success: false,
@@ -124,146 +175,312 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
                 stderr: format!("failed to spawn shell: {e}"),
                 exit_code: None,
                 hint: None,
-            };
+            });
         }
     };
 
-    // Drain stdout/stderr on background threads to prevent pipe buffer deadlock.
+    await_install_child(step, command, child, INSTALL_TIMEOUT, observer)
+}
+
+/// Drain a spawned install child's output into bounded buffers and wait for it
+/// to exit, killing it at `timeout`.
+///
+/// Split from the spawn so the timing-sensitive half is testable without a real
+/// login shell: shell startup alone can outlast a short test ceiling on a
+/// loaded machine. Production always passes [`INSTALL_TIMEOUT`].
+fn await_install_child(
+    step: &str,
+    command: &str,
+    mut child: std::process::Child,
+    timeout: Duration,
+    observer: Option<LineObserver>,
+) -> InstallOutcome {
+    // Drain stdout/stderr on background threads to prevent pipe buffer
+    // deadlock. Each drain feeds a bounded capture the main thread can read at
+    // any time, so a timeout can still surface whatever the install printed
+    // before it stalled.
+    let stdout_capture = Arc::new(Capture::new());
+    let stderr_capture = Arc::new(Capture::new());
     let stdout_pipe = child.stdout.take();
     let stderr_pipe = child.stderr.take();
 
-    let stdout_thread = std::thread::spawn(move || {
-        let mut buf = String::new();
-        if let Some(mut pipe) = stdout_pipe {
-            let _ = pipe.read_to_string(&mut buf);
+    // One event stream carries every input the ceiling waits on, so the exit
+    // and the drains are governed by the same deadline instead of the exit
+    // releasing the drains from it.
+    let (events_tx, events) = std::sync::mpsc::channel();
+
+    std::thread::spawn({
+        let (capture, done, observer) = (
+            Arc::clone(&stdout_capture),
+            events_tx.clone(),
+            observer.clone(),
+        );
+        move || {
+            if let Some(pipe) = stdout_pipe {
+                drain_into(pipe, &capture, observer.as_ref());
+            }
+            let _ = done.send(Settled::Drained);
         }
-        buf
     });
-    let stderr_thread = std::thread::spawn(move || {
-        let mut buf = String::new();
-        if let Some(mut pipe) = stderr_pipe {
-            let _ = pipe.read_to_string(&mut buf);
+    std::thread::spawn({
+        let (capture, done) = (Arc::clone(&stderr_capture), events_tx.clone());
+        move || {
+            if let Some(pipe) = stderr_pipe {
+                drain_into(pipe, &capture, observer.as_ref());
+            }
+            let _ = done.send(Settled::Drained);
         }
-        buf
     });
 
     // Save the PID before moving `child` into the wait thread so we can
     // kill the process on timeout.
     let child_pid = child.id();
 
-    let (tx, rx) = std::sync::mpsc::channel();
-    let wait_thread = std::thread::spawn(move || {
-        let status = child.wait();
-        let _ = tx.send(status);
+    std::thread::spawn(move || {
+        let _ = events_tx.send(Settled::Exited(child.wait()));
     });
 
-    // 5-minute timeout for install commands.
-    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(300);
-    loop {
-        let remaining = deadline.saturating_duration_since(std::time::Instant::now());
-        if remaining.is_zero() {
-            // Timeout: kill the child process via its PID, then join all
-            // threads so nothing leaks.
-            #[cfg(unix)]
-            unsafe {
-                libc::kill(child_pid as i32, libc::SIGTERM);
-            }
-            #[cfg(windows)]
-            {
-                let _ = crate::managed_agents::taskkill_tree(child_pid);
-            }
-            drop(rx);
-            let _ = wait_thread.join();
-            let _ = stdout_thread.join();
-            let _ = stderr_thread.join();
-            return InstallStepResult {
+    // No thread is ever joined. Each sends its one event before exiting, so a
+    // join after a complete settle would add nothing — and a join before one
+    // would reintroduce the unbounded wait this loop exists to prevent.
+    let mut settle = Settle::default();
+    let ended = settle.collect(&events, Instant::now() + timeout);
+    if ended == Collected::Deadline {
+        // Ceiling reached: kill the install's whole process group — the install
+        // shell is a session leader (`setsid` in its `pre_exec`), so signalling
+        // only the leader would leave descendants running and holding the
+        // output pipes open.
+        //
+        // Whether the leader had already exited decides the verdict. If it had,
+        // only a descendant was holding a drain open: the install genuinely
+        // finished and its real status stands. If it had not, the install itself
+        // was still running and this is a timeout — the status the kill produces
+        // moments later describes the kill, not the install, so it is discarded.
+        let install_finished = settle.status.is_some();
+        terminate_install_group(child_pid);
+        // Reaping the child and finishing the drains share one bound. Both
+        // normally complete within microseconds of the kill, which closes the
+        // pipes; when they don't — a process that escaped the group still
+        // holding a pipe, or a termination that failed outright — waiting would
+        // defeat the very ceiling that fired and keep the per-runtime install
+        // guard behind it closed. Stragglers are detached instead; the captures
+        // are read under the lock either way.
+        settle.collect(&events, Instant::now() + POST_KILL_GRACE);
+        if !install_finished {
+            return failed_with_capture(
+                step,
+                command,
+                timeout_message(timeout),
+                &stdout_capture,
+                &stderr_capture,
+            );
+        }
+    }
+
+    match settle.status {
+        Some(Ok(status)) => InstallOutcome {
+            step: InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
-                success: false,
-                stdout: String::new(),
-                stderr: "install command timed out after 5 minutes".to_string(),
-                exit_code: None,
+                success: status.success(),
+                stdout: stdout_capture.ui(),
+                stderr: stderr_capture.ui(),
+                exit_code: status.code(),
                 hint: None,
-            };
-        }
+            },
+            log_stdout: stdout_capture.log(),
+            log_stderr: stderr_capture.log(),
+        },
+        Some(Err(e)) => failed_with_capture(
+            step,
+            command,
+            format!("failed to check process status: {e}"),
+            &stdout_capture,
+            &stderr_capture,
+        ),
+        // Every sender is gone without an exit ever arriving.
+        None => failed_with_capture(
+            step,
+            command,
+            "internal error: install wait ended without a status".to_string(),
+            &stdout_capture,
+            &stderr_capture,
+        ),
+    }
+}
 
-        match rx.recv_timeout(std::time::Duration::from_millis(200).min(remaining)) {
-            Ok(Ok(status)) => {
-                let _ = wait_thread.join();
-                let stdout = stdout_thread.join().unwrap_or_default();
-                let stderr_raw = stderr_thread.join().unwrap_or_default();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: status.success(),
-                    stdout: truncate_output(stdout),
-                    stderr: truncate_output(stderr_raw),
-                    exit_code: status.code(),
-                    hint: None,
-                };
-            }
-            Ok(Err(e)) => {
-                let _ = wait_thread.join();
-                let _ = stdout_thread.join();
-                let _ = stderr_thread.join();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: false,
-                    stdout: String::new(),
-                    stderr: format!("failed to check process status: {e}"),
-                    exit_code: None,
-                    hint: None,
-                };
-            }
-            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
-                // Still running; loop and check deadline again.
-                continue;
-            }
-            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
-                // wait_thread dropped sender without sending — shouldn't happen.
-                let _ = wait_thread.join();
-                let _ = stdout_thread.join();
-                let _ = stderr_thread.join();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: false,
-                    stdout: String::new(),
-                    stderr: "internal error: wait thread disconnected".to_string(),
-                    exit_code: None,
-                    hint: None,
-                };
+/// One input the ceiling waits on.
+enum Settled {
+    Exited(std::io::Result<std::process::ExitStatus>),
+    Drained,
+}
+
+/// How a bounded [`Settle::collect`] ended.
+#[derive(PartialEq, Debug)]
+enum Collected {
+    /// The child exited and both drains reached EOF.
+    Complete,
+    /// The deadline passed first.
+    Deadline,
+    /// Every sender is gone — a thread died without reporting.
+    Disconnected,
+}
+
+/// What the install has settled so far: the child's exit status once it is
+/// known, and how many of the two drains have reached EOF.
+///
+/// Collecting is resumable, so the ceiling can fold more events into the same
+/// state under a second, post-kill deadline.
+#[derive(Default)]
+struct Settle {
+    status: Option<std::io::Result<std::process::ExitStatus>>,
+    drained: usize,
+}
+
+impl Settle {
+    const DRAINS: usize = 2;
+
+    fn is_complete(&self) -> bool {
+        self.status.is_some() && self.drained >= Self::DRAINS
+    }
+
+    /// Fold events until the install has fully settled or `deadline` passes.
+    ///
+    /// The exit and the drains share one deadline deliberately: a shell can exit
+    /// while a descendant it left behind still holds the inherited output pipes,
+    /// and waiting on those drains outside the deadline would let such a
+    /// descendant outlast the ceiling — holding the per-runtime install guard,
+    /// which is the very failure the ceiling exists to prevent.
+    fn collect(
+        &mut self,
+        events: &std::sync::mpsc::Receiver<Settled>,
+        deadline: Instant,
+    ) -> Collected {
+        while !self.is_complete() {
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            match events.recv_timeout(remaining) {
+                Ok(Settled::Exited(status)) => self.status = Some(status),
+                Ok(Settled::Drained) => self.drained += 1,
+                Err(std::sync::mpsc::RecvTimeoutError::Timeout) => return Collected::Deadline,
+                Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
+                    return Collected::Disconnected
+                }
             }
         }
+        Collected::Complete
     }
 }
 
-/// Cap output to head + tail to avoid flooding the UI with large error dumps,
-/// while preserving the most useful parts of the output.
-fn truncate_output(s: String) -> String {
-    const HEAD: usize = 512;
-    const TAIL: usize = 1024;
-    const LIMIT: usize = HEAD + TAIL;
-    if s.len() <= LIMIT {
-        return s;
-    }
-    let head_end = floor_char_boundary(&s, HEAD);
-    let tail_start = floor_char_boundary(&s, s.len().saturating_sub(TAIL));
-    let omitted = tail_start - head_end;
-    format!(
-        "{}\n... ({omitted} bytes omitted) ...\n{}",
-        &s[..head_end],
-        &s[tail_start..]
-    )
+/// Kill the install's process group, escalating on the *tree's* liveness.
+///
+/// The install ceiling owns this rather than reusing
+/// `managed_agents::terminate_process`, which escalates to SIGKILL only while
+/// the group *leader* is still running: a descendant that ignores SIGTERM
+/// outlives the leader, keeps the output pipes open, and never receives the
+/// group SIGKILL. The ceiling's contract is that nothing survives it, and the
+/// shared helper's escalation is load-bearing for the agent stop/restore paths,
+/// so the stricter rule lives here instead of changing it for them.
+///
+/// Nothing is returned: every outcome — including a signal that could not be
+/// delivered at all — has the same handling, the bounded waits at the call
+/// site.
+#[cfg(unix)]
+fn terminate_install_group(pid: u32) {
+    signal_install_tree(pid, libc::SIGTERM);
+    let deadline = Instant::now() + TERM_GRACE;
+    while install_tree_is_alive(pid) {
+        if Instant::now() >= deadline {
+            signal_install_tree(pid, libc::SIGKILL);
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+}
+
+/// Signal every process in `pid`'s group, falling back to the leader alone when
+/// the group cannot be signalled — the leader may have changed groups, or macOS
+/// may refuse one member — since killing the install shell beats killing
+/// nothing.
+#[cfg(unix)]
+fn signal_install_tree(pid: u32, signal: i32) {
+    if unsafe { libc::kill(-(pid as i32), signal) } != 0 {
+        unsafe { libc::kill(pid as i32, signal) };
+    }
+}
+
+/// Whether anything the ceiling aimed at is still running: a member of the
+/// process group, or the leader itself.
+#[cfg(unix)]
+fn install_tree_is_alive(pid: u32) -> bool {
+    signal_reaches(-(pid as i32)) || signal_reaches(pid as i32)
+}
+
+/// `kill(target, 0)` distinguishes "nothing there" (`ESRCH`) from every other
+/// outcome. Anything ambiguous — notably `EPERM` for a member we may not
+/// signal — counts as alive, so an unclear answer escalates rather than
+/// declaring the tree dead.
+#[cfg(unix)]
+fn signal_reaches(target: i32) -> bool {
+    if unsafe { libc::kill(target, 0) } == 0 {
+        return true;
+    }
+    std::io::Error::last_os_error().raw_os_error() != Some(libc::ESRCH)
+}
+
+/// Windows has no process groups on this path: `terminate_process` runs
+/// `taskkill /T /F`, which is already tree-wide and unconditional, so there is
+/// no escalation to get wrong.
+#[cfg(not(unix))]
+fn terminate_install_group(pid: u32) {
+    let _ = crate::managed_agents::terminate_process(pid);
 }
 
-fn floor_char_boundary(s: &str, mut index: usize) -> usize {
-    index = index.min(s.len());
-    while index > 0 && !s.is_char_boundary(index) {
-        index -= 1;
+/// A failure carrying whatever the drains captured, with `reason` leading
+/// stderr so the surfaced message names the failure before the install's own
+/// output.
+fn failed_with_capture(
+    step: &str,
+    command: &str,
+    reason: String,
+    stdout: &Capture,
+    stderr: &Capture,
+) -> InstallOutcome {
+    InstallOutcome {
+        step: InstallStepResult {
+            step: step.to_string(),
+            command: command.to_string(),
+            success: false,
+            stdout: stdout.ui(),
+            stderr: lead_with_reason(&reason, stderr.ui()),
+            exit_code: None,
+            hint: None,
+        },
+        log_stdout: stdout.log(),
+        log_stderr: lead_with_reason(&reason, stderr.log()),
     }
-    index
+}
+
+/// Put `reason` ahead of the install's own stderr, so the surfaced message names
+/// the failure before the output. An empty capture leaves the reason alone,
+/// without a dangling separator.
+fn lead_with_reason(reason: &str, captured: String) -> String {
+    if captured.is_empty() {
+        reason.to_string()
+    } else {
+        format!("{reason}\n{captured}")
+    }
+}
+
+/// Name the limit that fired and its value, so a ceiling kill is
+/// distinguishable from the installer's own failure.
+fn timeout_message(timeout: Duration) -> String {
+    let secs = timeout.as_secs();
+    let limit = if secs >= 60 {
+        format!("{}-minute", secs / 60)
+    } else {
+        format!("{secs}-second")
+    };
+    format!("install command exceeded the {limit} ceiling and was terminated")
 }
 
 #[cfg(test)]
@@ -410,48 +627,304 @@ mod tests {
         assert_eq!(cmd.get_current_dir(), Some(expected.as_path()));
     }
 
-    // ── output truncation ─────────────────────────────────────────────────────
+    // ── install ceiling ───────────────────────────────────────────────────────
+
+    /// The ceiling is Will's ruling: 15 minutes, and the error names the limit
+    /// that fired so a ceiling kill is not mistaken for the installer's own
+    /// failure.
+    #[test]
+    fn test_ceiling_is_fifteen_minutes_and_error_names_it() {
+        assert_eq!(INSTALL_TIMEOUT, Duration::from_secs(900));
+        assert!(
+            timeout_message(INSTALL_TIMEOUT).contains("15-minute"),
+            "got: {}",
+            timeout_message(INSTALL_TIMEOUT)
+        );
+    }
+
+    /// Spawn `script` under `sh` as a process-group leader with piped output —
+    /// the same shape [`run_install_command`] hands to
+    /// [`await_install_child`], minus the login shell whose own startup can
+    /// outlast a short test ceiling.
+    #[cfg(unix)]
+    fn spawn_group_leader(script: &str) -> std::process::Child {
+        use std::os::unix::process::CommandExt;
+
+        let mut cmd = std::process::Command::new("/bin/sh");
+        cmd.arg("-c").arg(script);
+        unsafe {
+            cmd.pre_exec(|| {
+                libc::setsid();
+                Ok(())
+            });
+        }
+        cmd.stdin(std::process::Stdio::null())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .spawn()
+            .expect("sh must spawn")
+    }
+
+    /// A command killed by the ceiling must surface what it printed before
+    /// stalling — that partial output is the only evidence of where the install
+    /// got stuck — and must stay unretryable, since re-running a hang just
+    /// costs the user another ceiling.
+    #[cfg(unix)]
+    #[test]
+    fn test_ceiling_returns_captured_output_and_stays_unretryable() {
+        let child = spawn_group_leader("echo out-before-hang; echo err-before-hang >&2; sleep 60");
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
+
+        assert!(!result.success);
+        assert_eq!(result.exit_code, None, "a killed command has no exit code");
+        assert!(
+            !install_failure_is_retryable(result),
+            "a ceiling kill must not be retried"
+        );
+        assert!(
+            result.stdout.contains("out-before-hang"),
+            "stdout captured before the stall must survive, got: {:?}",
+            result.stdout
+        );
+        assert!(
+            result.stderr.contains("5-second ceiling"),
+            "stderr must name the ceiling that actually fired, got: {:?}",
+            result.stderr
+        );
+        assert!(
+            result.stderr.contains("err-before-hang"),
+            "stderr captured before the stall must survive, got: {:?}",
+            result.stderr
+        );
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "the ceiling must not wait on the hung command's own exit"
+        );
+        assert!(
+            outcome.log_stderr.contains("err-before-hang"),
+            "the log record of a ceiling kill must carry the output too, got: {:?}",
+            outcome.log_stderr
+        );
+    }
+
+    /// A failure whose stream captured nothing surfaces the reason alone — no
+    /// dangling separator from an empty capture.
+    #[test]
+    fn test_failure_with_no_captured_output_reports_only_the_reason() {
+        let result = failed_with_capture(
+            "cli",
+            "curl … | bash",
+            "boom".to_string(),
+            &Capture::new(),
+            &Capture::new(),
+        )
+        .step;
+
+        assert_eq!(result.stdout, "");
+        assert_eq!(result.stderr, "boom");
+    }
+
+    // ── post-kill settle bound ────────────────────────────────────────────────
+
+    /// A sender that never arrives — the shape of a failed termination, whose
+    /// child is never reaped — must not extend the wait past its deadline.
+    #[test]
+    fn test_settling_on_a_message_that_never_arrives_stops_at_the_deadline() {
+        let (_tx, events) = std::sync::mpsc::channel::<Settled>();
+
+        let started = Instant::now();
+        let ended = Settle::default().collect(&events, started + Duration::from_millis(200));
+
+        assert_eq!(ended, Collected::Deadline);
+        assert!(
+            started.elapsed() < Duration::from_secs(1),
+            "the wait must end at its deadline, took {:?}",
+            started.elapsed()
+        );
+    }
+
+    /// An exit alone is not a settle: the drains are inputs to the same wait, so
+    /// a shell that exited while a descendant holds a pipe still hits the
+    /// deadline instead of being released from it.
+    #[test]
+    fn test_exit_without_drains_still_hits_the_deadline() {
+        let (tx, events) = std::sync::mpsc::channel();
+        tx.send(Settled::Exited(Ok(exit_status_zero()))).unwrap();
+
+        let started = Instant::now();
+        let mut settle = Settle::default();
+        let ended = settle.collect(&events, started + Duration::from_millis(200));
+
+        assert_eq!(
+            ended,
+            Collected::Deadline,
+            "a leader exit must not complete the settle while a drain is outstanding"
+        );
+        assert!(settle.status.is_some(), "the exit status must be retained");
+        assert!(started.elapsed() < Duration::from_secs(1));
+    }
 
-    /// Output within the cap is passed through byte-for-byte — no marker, no loss.
+    /// The settle completes only when the exit and both drains have arrived, and
+    /// it is resumable: state folded under the first deadline carries into the
+    /// post-kill one.
     #[test]
-    fn test_truncate_output_leaves_short_output_untouched() {
-        let short = "a".repeat(1536);
+    fn test_settle_completes_on_exit_plus_both_drains_and_resumes() {
+        let (tx, events) = std::sync::mpsc::channel();
+        tx.send(Settled::Drained).unwrap();
+
+        let mut settle = Settle::default();
+        assert_eq!(
+            settle.collect(&events, Instant::now() + Duration::from_millis(50)),
+            Collected::Deadline
+        );
+
+        tx.send(Settled::Exited(Ok(exit_status_zero()))).unwrap();
+        tx.send(Settled::Drained).unwrap();
+
+        assert_eq!(
+            settle.collect(&events, Instant::now() + Duration::from_secs(5)),
+            Collected::Complete,
+            "the second collect must build on the first's state, not restart it"
+        );
+    }
 
-        assert_eq!(truncate_output(short.clone()), short);
+    /// Exit status of a trivially successful command, for driving `Settle`
+    /// without a real install.
+    fn exit_status_zero() -> std::process::ExitStatus {
+        std::process::Command::new("true")
+            .status()
+            .expect("run `true`")
     }
 
-    /// Over the cap, both ends survive and the middle is replaced by a marker
-    /// naming the omitted byte count — the head keeps the command's opening
-    /// context and the tail keeps the error that usually trails.
+    /// A shell can exit while a descendant it left behind still holds the
+    /// inherited output pipes. If the exit released the drains from the
+    /// deadline, that descendant would hold the install — and the per-runtime
+    /// concurrency guard behind it — open indefinitely, which is exactly the
+    /// failure the ceiling exists to prevent. The leader here exits in
+    /// milliseconds; only the descendant outlives the ceiling.
+    #[cfg(unix)]
     #[test]
-    fn test_truncate_output_keeps_head_and_tail_with_marker() {
-        let input = format!(
-            "{}{}{}",
-            "H".repeat(512),
-            "M".repeat(4000),
-            "T".repeat(1024)
+    fn test_promptly_exited_leader_with_a_pipe_holding_descendant_still_obeys_the_ceiling() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("lingering.pid");
+        let child = spawn_group_leader(&format!(
+            "sh -c 'echo $$ > {pid}; sleep 120' & exit 3",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(2), None);
+
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "a descendant holding the pipe must not outlast the ceiling, took {:?}",
+            started.elapsed()
         );
+        assert_eq!(
+            outcome.step.exit_code,
+            Some(3),
+            "the leader's real status outranks the ceiling's verdict once it is known"
+        );
+        // The deadline must still reach the kill on this path: a leader exit that
+        // skipped termination would leave the descendant running with the pipes
+        // open, which is the defect itself rather than a detail of it.
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "descendant {pid} survived — a leader exit must not skip the ceiling's kill"
+        );
+    }
 
-        let out = truncate_output(input);
+    /// Wait up to 3s for `pid` to disappear.
+    #[cfg(unix)]
+    fn await_death(pid: u32) -> bool {
+        for _ in 0..30 {
+            if !crate::managed_agents::process_is_running(pid) {
+                return true;
+            }
+            std::thread::sleep(Duration::from_millis(100));
+        }
+        false
+    }
+
+    /// Read the pid a test descendant recorded for itself.
+    #[cfg(unix)]
+    fn recorded_pid(pidfile: &std::path::Path) -> u32 {
+        for _ in 0..50 {
+            if let Ok(text) = std::fs::read_to_string(pidfile) {
+                if let Ok(pid) = text.trim().parse() {
+                    return pid;
+                }
+            }
+            std::thread::sleep(Duration::from_millis(100));
+        }
+        panic!("the descendant never recorded its pid at {pidfile:?}");
+    }
+
+    /// The install shell is a process-group leader, and its descendants inherit
+    /// the output pipes. Killing only the leader leaves them running and the
+    /// drains blocked on a pipe nobody will close, so the ceiling kills the
+    /// whole group.
+    #[cfg(unix)]
+    #[test]
+    fn test_ceiling_kills_descendants_holding_the_output_pipe() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("descendant.pid");
+        let child = spawn_group_leader(&format!(
+            "sh -c 'echo $$ > {pid}; sleep 60' & echo leader-up; sleep 60",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
 
-        assert!(out.starts_with(&"H".repeat(512)));
-        assert!(out.ends_with(&"T".repeat(1024)));
+        assert!(!result.success);
         assert!(
-            out.contains("... (4000 bytes omitted) ..."),
-            "marker must name the omitted byte count, got: {out}"
+            started.elapsed() < Duration::from_secs(30),
+            "the drains must not block on a descendant's inherited pipe"
+        );
+
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "descendant {pid} survived the ceiling kill — the group was not signalled"
         );
     }
 
-    /// Truncation must not split a multi-byte character. Cutting mid-codepoint
-    /// would panic on the slice; the boundary floor prevents it.
+    /// Escalation must key off the group, not the leader: a descendant that
+    /// ignores SIGTERM outlives the leader, and if SIGKILL is skipped because
+    /// the leader is gone it keeps running with the output pipes open — past the
+    /// ceiling, and past the concurrency guard that blocks the next install.
+    #[cfg(unix)]
     #[test]
-    fn test_truncate_output_does_not_split_multibyte_characters() {
-        // "é" is 2 bytes, so every candidate cut index lands mid-character.
-        let input = "é".repeat(4000);
+    fn test_ceiling_kills_sigterm_ignoring_descendant() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("stubborn.pid");
+        // An ignored disposition survives exec, so the descendant's own `sleep`
+        // ignores SIGTERM too — nothing in that subtree dies without SIGKILL.
+        let child = spawn_group_leader(&format!(
+            "sh -c 'trap \"\" TERM; echo $$ > {pid}; sleep 60' & echo leader-up; sleep 60",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
 
-        let out = truncate_output(input);
+        assert!(!result.success);
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "a SIGTERM-ignoring descendant must not hold the ceiling open"
+        );
 
-        assert!(out.contains("bytes omitted"), "input must exceed the cap");
-        assert!(!out.contains('\u{fffd}'), "no replacement chars: {out}");
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "SIGTERM-ignoring descendant {pid} survived — escalation followed the leader, not the group"
+        );
     }
 }
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report.rs
new file mode 100644
index 0000000000..24bcd3456a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report.rs
@@ -0,0 +1,595 @@
+//! Where an install's output goes: the install log file (complete history) and
+//! the live output line in the UI (current progress).
+//!
+//! Both destinations hang off the same drain seam in
+//! [`super::install_capture`], and both are best-effort: an install must never
+//! fail because a log write or an event emit did.
+//!
+//! [`InstallReporter`] owns two explicit lifecycles, because both the log and
+//! the live line are meaningless without a notion of "this run":
+//!
+//! * a **log session**, started once per run, which keeps the previous run's
+//!   file as `.1` and writes this run's header; and
+//! * a **live-event sequence**, monotonic across the whole install, which is
+//!   what lets the UI drop a superseded line. A per-command retry number
+//!   cannot do that job — it restarts at 1 for every step.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex, RwLock};
+use std::time::{Duration, Instant};
+
+use serde::Serialize;
+
+use super::install_capture::{LineObserver, Throttle};
+use crate::managed_agents::{InstallRuntimeResult, InstallStepResult};
+
+/// One install command's result: what the UI shows, and the log-scale copy of
+/// the same output for the log file.
+pub(super) struct InstallOutcome {
+    pub(super) step: InstallStepResult,
+    pub(super) log_stdout: String,
+    pub(super) log_stderr: String,
+}
+
+impl InstallOutcome {
+    /// A step Buzz synthesized rather than ran — a failed prerequisite, or the
+    /// post-install verification. Its own message is the whole record.
+    pub(super) fn synthesized(step: InstallStepResult) -> Self {
+        Self {
+            log_stdout: step.stdout.clone(),
+            log_stderr: step.stderr.clone(),
+            step,
+        }
+    }
+}
+
+/// Payload of the `acp-install-output` event.
+///
+/// `seq` is monotonic across the entire install, so the UI can drop a line a
+/// later step or attempt has already superseded. The retry number cannot serve
+/// as that key: it restarts at 1 for every step, so a step that succeeded on
+/// attempt 2 would make the next step's attempt-1 output look stale and freeze
+/// the display.
+///
+/// `line: None` is the *start signal*: an attempt is beginning and the displayed
+/// line must clear now. It is emitted unthrottled, because the point is that
+/// stale output stops being shown before the new work prints anything.
+#[derive(Serialize, Clone, Debug)]
+pub(super) struct InstallOutputEvent {
+    pub(super) runtime_id: String,
+    pub(super) seq: u64,
+    pub(super) line: Option<String>,
+}
+
+/// Emits one live output event. Boxed rather than holding an `AppHandle` so the
+/// reporter is constructible — and assertable — without a Tauri app.
+type EmitEvent = Arc<dyn Fn(InstallOutputEvent) + Send + Sync>;
+
+/// Literal secret values scrubbed out of everything this module publishes, in
+/// addition to the shapes [`crate::managed_agents::redact_secrets_with`]
+/// recognises on its own.
+type Secrets = Arc<Vec<String>>;
+
+/// At most four live-output events per second. Coalescing *holds* the newest
+/// line rather than dropping it: a burst that ends just before the window
+/// closes would otherwise leave the display showing a line the install had
+/// already moved past.
+const LIVE_LINE_INTERVAL: Duration = Duration::from_millis(250);
+
+pub(super) struct InstallReporter {
+    log: Option<InstallLog>,
+    /// `None` when nothing is listening, which is also what makes
+    /// [`InstallReporter::line_observer`] `None` — the drain then skips line
+    /// reassembly entirely instead of doing it for no one.
+    live: Option<Live>,
+    secrets: Secrets,
+}
+
+impl Drop for InstallReporter {
+    /// Serialise deactivation against in-flight publications: take the
+    /// exclusive lifecycle write lock, mark the run as inactive, and return —
+    /// all before the per-runtime concurrency guard releases.
+    ///
+    /// Every drain thread holds the shared read guard from its admission check
+    /// through its `(self.emit)(...)` call, so the write lock here blocks until
+    /// every in-flight publication has finished.  After this returns, `active`
+    /// is `false` under an exclusive write, and any thread that attempts a new
+    /// `offer` will read `false` under a read lock and return without emitting.
+    ///
+    /// The ordering guarantee: `reporter` is declared after `_guard` in
+    /// `install_acp_runtime_blocking` (line 311 vs line 306), so Rust drops
+    /// `reporter` first in reverse-declaration order — deactivation completes
+    /// before the runtime guard releases and a new install can start.
+    fn drop(&mut self) {
+        if let Some(live) = &self.live {
+            if let Ok(mut active) = live.lifecycle.write() {
+                *active = false;
+            }
+        }
+    }
+}
+
+impl InstallReporter {
+    /// The reporter a real install run uses: it starts this run's log session
+    /// and emits live output events through `app`.
+    ///
+    /// `runtime_id` must already be the canonical id from the runtime catalog —
+    /// the log path is built from it, so resolving it first is what keeps a raw
+    /// command argument out of a filename.
+    ///
+    /// A log that cannot be resolved or opened degrades to no log rather than
+    /// failing the install: a user with a broken app-data directory still needs
+    /// the install itself to work.
+    pub(super) fn for_run(app: &tauri::AppHandle, runtime_id: &str) -> Self {
+        // Read from the app's own package info rather than the frontend's
+        // `getVersion` plugin call: the header is written on the Rust side, and
+        // this cannot fail or be mocked out from under the log.
+        let app_version = app.package_info().version.to_string();
+        let log = crate::managed_agents::storage::install_log_path(app, runtime_id)
+            .ok()
+            .and_then(|path| InstallLog::start(&path, runtime_id, &app_version));
+        let app = app.clone();
+        let emit: EmitEvent = Arc::new(move |event| {
+            use tauri::Emitter;
+            let _ = app.emit("acp-install-output", event);
+        });
+        Self::new(runtime_id, log, Some(emit))
+    }
+
+    fn new(runtime_id: &str, log: Option<InstallLog>, emit: Option<EmitEvent>) -> Self {
+        // Snapshot the environment's secrets once, at construction: the install
+        // inherits this environment, so anything it echoes came from here.
+        Self::with_secrets(runtime_id, log, emit, env_secret_values())
+    }
+
+    /// The reporter over an explicit secret set, which is what makes the
+    /// scrubbing assertable: a test can name a proxy credential without
+    /// exporting a real `HTTPS_PROXY` into the process every HTTP client in the
+    /// suite would then read.
+    fn with_secrets(
+        runtime_id: &str,
+        log: Option<InstallLog>,
+        emit: Option<EmitEvent>,
+        secrets: Vec<String>,
+    ) -> Self {
+        let secrets: Secrets = Arc::new(secrets);
+        let live = emit.map(|emit| Live {
+            runtime_id: Arc::from(runtime_id),
+            emit,
+            throttle: Arc::new(Throttle::new(LIVE_LINE_INTERVAL)),
+            seq: Arc::new(AtomicU64::new(0)),
+            lifecycle: Arc::new(RwLock::new(true)),
+            secrets: Arc::clone(&secrets),
+        });
+        Self { log, live, secrets }
+    }
+
+    /// The log file to point the user at, or `None` when this run has no log —
+    /// the failure message then omits the pointer rather than naming a file
+    /// that does not exist.
+    pub(super) fn log_path(&self) -> Option<String> {
+        Some(self.log.as_ref()?.path.display().to_string())
+    }
+
+    /// A failed install carrying the steps recorded so far and the log holding
+    /// their full history. Every early return in the install shapes its result
+    /// here, so none can forget the log pointer the failure message needs.
+    pub(super) fn failed(&self, steps: Vec<InstallStepResult>) -> InstallRuntimeResult {
+        InstallRuntimeResult {
+            success: false,
+            steps,
+            restarted_count: 0,
+            failed_restart_count: 0,
+            log_path: self.log_path(),
+        }
+    }
+
+    /// Mark the start of one executed attempt: clear whatever line the previous
+    /// attempt left on screen, and start this attempt's clock.
+    ///
+    /// The clear is emitted unthrottled and reopens the rate window, so the new
+    /// attempt's first line cannot be swallowed by the previous attempt's.
+    /// Without this signal the prior attempt's last line — typically the failure
+    /// that caused the retry — sits under the spinner through the backoff and
+    /// through a silent next attempt.
+    pub(super) fn start_attempt(&self) {
+        if let Some(log) = &self.log {
+            log.mark_attempt_start();
+        }
+        if let Some(live) = &self.live {
+            live.throttle.restart();
+            live.publish(None);
+        }
+    }
+
+    /// Observer for one attempt's drains, or `None` when nothing is listening.
+    pub(super) fn line_observer(&self) -> Option<LineObserver> {
+        let live = self.live.clone()?;
+        Some(Arc::new(move |line: &str| live.offer(line)))
+    }
+
+    /// Record one executed attempt of a step, returning the step with secrets
+    /// scrubbed out of the output the UI will render.
+    ///
+    /// The scrub happens here rather than at the construction sites because
+    /// every executed step reaches the caller through this function — the
+    /// timeout path, the status-check failure, and the ordinary exit all build
+    /// their `InstallStepResult` straight from the captures.
+    pub(super) fn record_attempt(
+        &self,
+        attempt: u32,
+        outcome: InstallOutcome,
+    ) -> InstallStepResult {
+        // The drains are finished, so a line the throttle is still holding is
+        // this attempt's last and nothing is coming to replace it.
+        if let Some(live) = &self.live {
+            live.flush_pending();
+        }
+        self.write_record(Some(attempt), &outcome);
+        self.redacted_step(outcome.step)
+    }
+
+    /// Push a synthesized step onto `steps` and record it. Routing every step
+    /// through here is what keeps the log complete: a step that reaches the UI
+    /// without passing this function is invisible in the file.
+    pub(super) fn record_step(&self, steps: &mut Vec<InstallStepResult>, step: InstallStepResult) {
+        self.write_record(None, &InstallOutcome::synthesized(step.clone()));
+        steps.push(self.redacted_step(step));
+    }
+
+    /// Scrub the frontend-visible fields of a step. The failure message the UI
+    /// builds renders `stderr`/`stdout` and the hint verbatim, so they need the
+    /// same scrubbing as the log record and the live line — the log is not the
+    /// only place an install's output is read.
+    fn redacted_step(&self, mut step: InstallStepResult) -> InstallStepResult {
+        step.command = redact(&step.command, &self.secrets);
+        step.stdout = redact(&step.stdout, &self.secrets);
+        step.stderr = redact(&step.stderr, &self.secrets);
+        step.hint = step.hint.map(|hint| redact(&hint, &self.secrets));
+        step
+    }
+
+    /// Append one record. Best-effort by contract: a full disk or a revoked
+    /// permission degrades the diagnostics, it does not fail the install.
+    fn write_record(&self, attempt: Option<u32>, outcome: &InstallOutcome) {
+        let Some(log) = &self.log else {
+            return;
+        };
+        log.append(&render_record(
+            attempt,
+            log.take_attempt_elapsed(),
+            outcome,
+            &self.secrets,
+        ));
+    }
+}
+
+/// The shared half of the reporter — everything a drain thread's observer needs,
+/// owned rather than borrowed so an observer can outlive the call that made it.
+#[derive(Clone)]
+struct Live {
+    runtime_id: Arc<str>,
+    emit: EmitEvent,
+    throttle: Arc<Throttle>,
+    seq: Arc<AtomicU64>,
+    /// Lifecycle lock: `true` while the run is active, `false` once
+    /// `InstallReporter` has been dropped.
+    ///
+    /// Drain threads hold a **shared read guard** from the admission check
+    /// through the `(self.emit)(...)` call, making the admit-and-publish pair
+    /// atomic with respect to deactivation. `InstallReporter::drop` takes the
+    /// **exclusive write guard** and sets the value to `false`; this blocks
+    /// until every in-flight publication finishes, then prevents any new
+    /// publications from starting. The write lock is held only for the flag
+    /// store and is released before the per-runtime concurrency guard drops,
+    /// so its duration is bounded by the time a single `emit` call takes —
+    /// microseconds to low milliseconds for the Tauri IPC broadcast.
+    lifecycle: Arc<RwLock<bool>>,
+    secrets: Secrets,
+}
+
+impl Live {
+    /// Offer one drained line to the rate limiter, emitting it if the window is
+    /// open and holding it as the newest pending line if not.
+    ///
+    /// The read guard is held from the admission check through the emit call so
+    /// that `InstallReporter::drop`'s write lock must wait for any in-flight
+    /// publication to complete before deactivating.  This makes the
+    /// check-then-emit pair atomic with respect to shutdown.
+    fn offer(&self, line: &str) {
+        let Ok(guard) = self.lifecycle.read() else {
+            return;
+        };
+        if !*guard {
+            return;
+        }
+        if let Some(line) = self.throttle.offer(line, Instant::now()) {
+            self.publish_under_guard(line);
+        }
+        // `guard` drops here, releasing the read lock after publication.
+    }
+
+    fn flush_pending(&self) {
+        let Ok(guard) = self.lifecycle.read() else {
+            return;
+        };
+        if !*guard {
+            return;
+        }
+        if let Some(line) = self.throttle.take_pending() {
+            self.publish_under_guard(line);
+        }
+        // `guard` drops here, releasing the read lock after publication.
+    }
+
+    /// Emit `line` now, bypassing the rate window and the lifecycle lock.
+    ///
+    /// Only called from `InstallReporter` methods that run on the reporter
+    /// itself (never from detached drain threads), so no lifecycle guard is
+    /// needed — the reporter is alive by definition when its own methods run.
+    fn publish(&self, line: Option<String>) {
+        (self.emit)(InstallOutputEvent {
+            runtime_id: self.runtime_id.to_string(),
+            seq: self.seq.fetch_add(1, Ordering::Relaxed),
+            line: line.map(|line| redact(&line, &self.secrets)),
+        });
+    }
+
+    /// Publish `line` while already holding a read guard on `lifecycle`.  The
+    /// caller is responsible for checking `active` before calling this.
+    fn publish_under_guard(&self, line: String) {
+        (self.emit)(InstallOutputEvent {
+            runtime_id: self.runtime_id.to_string(),
+            seq: self.seq.fetch_add(1, Ordering::Relaxed),
+            line: Some(redact(&line, &self.secrets)),
+        });
+    }
+}
+
+/// This run's log file: one session, opened once, appended to per record.
+struct InstallLog {
+    path: PathBuf,
+    /// When the attempt currently running started, so its record can name its
+    /// own duration. A 15-minute ceiling is only diagnosable if the file says
+    /// how long each attempt actually took.
+    attempt_start: Mutex<Option<Instant>>,
+}
+
+impl InstallLog {
+    /// Start this run's session, or `None` if the file cannot be opened.
+    ///
+    /// Rotation happens here, once per run, rather than per record: a run either
+    /// gets its own file or it gets no log at all, so two runs are never
+    /// interleaved in one file.
+    ///
+    /// The header identifies the environment the run happened in, not just the
+    /// run: a Windows install failure and a macOS one on the same runtime are
+    /// different bugs, and a stale app version explains a failure that no longer
+    /// reproduces.
+    fn start(path: &Path, runtime_id: &str, app_version: &str) -> Option<Self> {
+        let mut file = crate::managed_agents::storage::start_install_log_session(path).ok()?;
+        let _ = file.write_all(
+            format!(
+                "=== install run runtime={runtime_id} app={app_version} os={} started={}\n",
+                std::env::consts::OS,
+                chrono::Utc::now().to_rfc3339()
+            )
+            .as_bytes(),
+        );
+        Some(Self {
+            path: path.to_path_buf(),
+            attempt_start: Mutex::new(None),
+        })
+    }
+
+    fn mark_attempt_start(&self) {
+        if let Ok(mut start) = self.attempt_start.lock() {
+            *start = Some(Instant::now());
+        }
+    }
+
+    /// How long the attempt being recorded ran, consumed so a later record
+    /// cannot reuse it. `None` for a synthesized step, which never ran.
+    fn take_attempt_elapsed(&self) -> Option<Duration> {
+        Some(self.attempt_start.lock().ok()?.take()?.elapsed())
+    }
+
+    fn append(&self, record: &str) {
+        if let Ok(mut file) = crate::managed_agents::storage::open_install_log_file(&self.path) {
+            let _ = file.write_all(record.as_bytes());
+        }
+    }
+}
+
+/// One self-contained record. Each is capped independently by the log-scale
+/// capture that produced it, so an early attempt that printed megabytes cannot
+/// push a later attempt — or the verification step that explains the failure —
+/// out of the file.
+fn render_record(
+    attempt: Option<u32>,
+    elapsed: Option<Duration>,
+    outcome: &InstallOutcome,
+    secrets: &Secrets,
+) -> String {
+    let step = &outcome.step;
+    let attempt = attempt.map_or_else(|| "-".to_string(), |n| n.to_string());
+    let exit = step
+        .exit_code
+        .map_or_else(|| "none".to_string(), |code| code.to_string());
+    let elapsed = elapsed.map_or_else(
+        || "-".to_string(),
+        |elapsed| format!("{:.1}s", elapsed.as_secs_f64()),
+    );
+    let mut record = format!(
+        "=== {} step={} attempt={attempt} success={} exit={exit} elapsed={elapsed}\n$ {}\n",
+        chrono::Utc::now().to_rfc3339(),
+        step.step,
+        step.success,
+        redact(&step.command, secrets),
+    );
+    for (label, text) in [
+        ("stdout", &outcome.log_stdout),
+        ("stderr", &outcome.log_stderr),
+    ] {
+        if !text.trim().is_empty() {
+            record.push_str(&format!("--- {label} ---\n{}\n", redact(text, secrets)));
+        }
+    }
+    if let Some(hint) = &step.hint {
+        record.push_str(&format!("--- hint ---\n{}\n", redact(hint, secrets)));
+    }
+    record
+}
+
+/// Scrub secrets before anything reaches disk or the UI. The log is written
+/// unattended and the live line is rendered verbatim, so scrubbing happens at
+/// the write, not at the read.
+fn redact(text: &str, secrets: &Secrets) -> String {
+    let extras: Vec<&str> = secrets.iter().map(String::as_str).collect();
+    crate::managed_agents::redact_secrets_with(text, &extras)
+}
+
+/// Values of environment variables whose *name* marks them as secret.
+///
+/// An install inherits Buzz's environment and installers echo it back — npm
+/// prints the resolved registry config on an auth failure, and a shell that
+/// traces its commands prints every expansion. Without this, only the
+/// hard-coded key shapes would be scrubbed, so a plain `NPM_TOKEN` or
+/// `ANTHROPIC_API_KEY` would land in the file in clear text.
+fn env_secret_values() -> Vec<String> {
+    secret_values_from(std::env::vars())
+}
+
+/// The secret-bearing part of each variable that carries one.
+///
+/// Split from [`env_secret_values`] so the classification is assertable without
+/// mutating the process environment — setting a real `HTTPS_PROXY` in a test
+/// would be read by every HTTP client the rest of the suite builds.
+///
+/// Three kinds of variable are recognised, because they need different
+/// treatment:
+///
+/// * **URL-valued variables**, where only the userinfo is the credential;
+/// * **exactly named credentials**, whose whole value is the secret; and
+/// * **name-marked secrets**, matched by a marker substring.
+fn secret_values_from(vars: impl IntoIterator<Item = (String, String)>) -> Vec<String> {
+    vars.into_iter()
+        .filter_map(|(name, value)| {
+            let name = name.to_ascii_uppercase();
+            if URL_CREDENTIAL_VAR_NAMES.contains(&name.as_str()) {
+                // Only the userinfo, so the endpoint itself stays named in the
+                // record: an install that fails against a proxy or a private
+                // registry is diagnosable only if the log still says which one
+                // it went through, and the host and port are not the secret.
+                // Redacting the whole value would erase that while protecting
+                // nothing more.
+                return url_userinfo(&value).map(str::to_string);
+            }
+            if SECRET_VAR_NAMES.contains(&name.as_str()) {
+                // Deliberately not subject to the 8-byte floor below: an exact
+                // name is a fact, not the guess the marker rule makes, so there
+                // is nothing for a floor to protect against. npm's one-time
+                // password is six digits and is a credential at that length —
+                // short, but still above the four-byte minimum
+                // [`crate::managed_agents::redact_secrets_with`] applies, so it
+                // survives to be scrubbed.
+                return (!value.is_empty()).then_some(value);
+            }
+            // A value under 8 bytes is more likely a flag like `true` or a
+            // version than a credential, and scrubbing those makes ordinary
+            // output unreadable.
+            (value.len() >= 8 && name_marks_secret(&name)).then_some(value)
+        })
+        .collect()
+}
+
+/// Variables whose value is a URL that may embed a credential in its userinfo.
+///
+/// npm's own `npm_config_*` aliases are here too: npm resolves them ahead of
+/// the conventional names and echoes the result from `npm config list`, and
+/// none of these names carries a marker [`name_marks_secret`] would catch.
+/// Matching is case-insensitive because the caller uppercases the name first,
+/// which is what npm's lowercase spelling needs.
+const URL_CREDENTIAL_VAR_NAMES: &[&str] = &[
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NPM_CONFIG_PROXY",
+    "NPM_CONFIG_HTTPS_PROXY",
+    "NPM_CONFIG_REGISTRY",
+];
+
+/// Variables whose whole value is a credential, recognised by exact name.
+///
+/// These are npm's supported credential settings, whose names carry no marker
+/// [`name_marks_secret`] would catch. They are listed exactly rather than
+/// matched on `KEY` or `AUTH` substrings: those occur throughout an ordinary
+/// environment, and scrubbing on them would delete unrelated values from the
+/// whole log.
+///
+/// * `NPM_CONFIG_KEY` — the PEM client key used to reach a registry.
+/// * `NPM_CONFIG__AUTH` — the base64 basic-auth blob (npm's own double
+///   underscore, matching the `_auth` setting).
+/// * `NPM_CONFIG_OTP` — the registry one-time password.
+const SECRET_VAR_NAMES: &[&str] = &["NPM_CONFIG_KEY", "NPM_CONFIG__AUTH", "NPM_CONFIG_OTP"];
+
+/// Whether an environment variable's name marks its value as a credential.
+///
+/// Keyed on the name because a secret's *value* has no reliable shape. The
+/// markers avoid substrings that occur in non-secret names: `AUTH` is left out
+/// because it matches `GIT_AUTHOR_NAME`, whose value is a person's name, and
+/// personal access tokens match on `_PAT` as a *suffix* rather than a substring
+/// — `contains("_PAT")` would match every `*_PATH` variable on the system and
+/// scrub directory names out of the whole log.
+fn name_marks_secret(name: &str) -> bool {
+    const SECRET_NAME_MARKERS: &[&str] = &[
+        "TOKEN",
+        "SECRET",
+        "PASSWORD",
+        "PASSWD",
+        "APIKEY",
+        "API_KEY",
+        "PRIVATE_KEY",
+        "ACCESS_KEY",
+        "CREDENTIAL",
+    ];
+    name.ends_with("_PAT")
+        || SECRET_NAME_MARKERS
+            .iter()
+            .any(|marker| name.contains(marker))
+}
+
+/// The `user:password` credential embedded in a URL, if it has one.
+///
+/// Parsed rather than pattern-matched so a URL with no credential — the common
+/// case — contributes nothing to scrub. The last `@` in the
+/// authority separates userinfo from host, so a password containing an
+/// encoded `@` still splits correctly.
+///
+/// A bare username with no password is not treated as a credential: it is not
+/// secret on its own, and scrubbing it would erase every occurrence of a word
+/// like `user` from the whole record.
+fn url_userinfo(value: &str) -> Option<&str> {
+    let authority = value
+        .split_once("://")?
+        .1
+        .split(['/', '?', '#'])
+        .next()
+        .unwrap_or_default();
+    let userinfo = authority.rsplit_once('@')?.0;
+    userinfo.contains(':').then_some(userinfo)
+}
+
+#[cfg(test)]
+#[path = "install_report_test_support.rs"]
+mod test_support;
+
+#[cfg(test)]
+#[path = "install_report_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "install_report_redaction_tests.rs"]
+mod redaction_tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs
new file mode 100644
index 0000000000..ce97559616
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs
@@ -0,0 +1,480 @@
+use super::test_support::*;
+use super::*;
+
+// ── redaction ────────────────────────────────────────────────────────────────
+
+/// Secrets that an installer echoed must not land on disk. The log is written
+/// unattended, so scrubbing happens at the write, not at the read.
+#[test]
+fn test_log_redacts_secrets_before_writing() {
+    let h = harness();
+    let leak = "npm ERR! token nsec1qqqqqqqqqqsecretvalue failed";
+
+    h.reporter.record_attempt(1, outcome("cli", false, leak));
+
+    let log = h.log_contents();
+    assert!(!log.contains("nsec1qqqqqqqqqqsecretvalue"), "got: {log}");
+    assert!(log.contains("[REDACTED]"), "got: {log}");
+}
+
+/// The environment's own secrets are scrubbed too, by *name* rather than shape.
+/// An install inherits Buzz's environment and installers echo it back — npm
+/// prints its resolved config on an auth failure — and a token with no
+/// recognizable prefix would otherwise reach the file verbatim.
+#[test]
+fn test_log_redacts_an_environment_secret_with_no_recognizable_prefix() {
+    let secret = "0e8f31c5a4b7d296e5f1a";
+    // Set before the reporter is built: the snapshot is taken at construction.
+    std::env::set_var("BUZZ_TEST_REGISTRY_TOKEN", secret);
+    let h = harness();
+    std::env::remove_var("BUZZ_TEST_REGISTRY_TOKEN");
+
+    h.reporter.record_attempt(
+        1,
+        outcome("cli", false, &format!("npm ERR! _authToken={secret}")),
+    );
+
+    let log = h.log_contents();
+    assert!(!log.contains(secret), "got: {log}");
+    assert!(log.contains("[REDACTED]"), "got: {log}");
+}
+
+/// A live line carries the same scrubbing as the log record. The line is
+/// rendered verbatim in the UI, so a leak there is as visible as one on disk.
+#[test]
+fn test_a_live_line_is_redacted_before_it_is_emitted() {
+    let h = harness();
+
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("fetching with token nsec1qqqqqqqqqqleaked");
+
+    let lines = h.lines();
+    assert_eq!(lines.len(), 1);
+    let line = lines[0].clone().expect("a line, not a clear signal");
+    assert!(!line.contains("nsec1qqqqqqqqqqleaked"), "got: {line}");
+    assert!(line.contains("[REDACTED]"), "got: {line}");
+}
+
+// ── proxy and PAT credentials ────────────────────────────────────────────────
+
+/// A proxy URL's password is a credential, but the proxy itself is diagnostic
+/// information: an install that fails behind a proxy is only debuggable if the
+/// record still says which proxy it went through. So the userinfo is scrubbed
+/// and the host is kept.
+#[test]
+fn test_proxy_userinfo_is_secret_but_the_proxy_host_is_not() {
+    let secrets = secret_values_from([(
+        "HTTPS_PROXY".to_string(),
+        "http://corpuser:hunter2pass@proxy.example:8080".to_string(),
+    )]);
+
+    assert_eq!(secrets, vec!["corpuser:hunter2pass"]);
+}
+
+/// A proxy with no credential contributes nothing — scrubbing a bare host would
+/// erase the proxy's name from every record while protecting nothing. A bare
+/// username is not a credential either, and scrubbing it would delete every
+/// occurrence of that word from the log.
+#[test]
+fn test_a_proxy_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "HTTP_PROXY".to_string(),
+            "http://proxy.example:8080".to_string(),
+        ),
+        (
+            "ALL_PROXY".to_string(),
+            "socks5://10.0.0.1:1080".to_string(),
+        ),
+        (
+            "HTTPS_PROXY".to_string(),
+            "http://user@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// npm reads its own `npm_config_*` aliases in preference to the conventional
+/// proxy variables and prints the resolved value back, so a credential set only
+/// under an alias would otherwise never enter the scrub list. npm spells them
+/// in lowercase, so both cases have to classify.
+#[test]
+fn test_npm_proxy_aliases_are_classified_in_either_case() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_proxy".to_string(),
+            "http://corpuser:lowerplain@proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_PROXY".to_string(),
+            "http://corpuser:upperplain@proxy.example:8080".to_string(),
+        ),
+        (
+            "npm_config_https_proxy".to_string(),
+            "http://corpuser:lowertls@proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_HTTPS_PROXY".to_string(),
+            "http://corpuser:uppertls@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert_eq!(
+        secrets,
+        vec![
+            "corpuser:lowerplain",
+            "corpuser:upperplain",
+            "corpuser:lowertls",
+            "corpuser:uppertls",
+        ]
+    );
+}
+
+/// The alias carries the same userinfo-only policy as the conventional names:
+/// a credential-less alias contributes nothing, so the proxy stays named in the
+/// record.
+#[test]
+fn test_an_npm_proxy_alias_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_proxy".to_string(),
+            "http://proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_HTTPS_PROXY".to_string(),
+            "http://user@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The classifier and the reporter have to agree: an alias credential that
+/// classifies but never reaches the scrub list still leaks. This drives the
+/// reporter with exactly what the classifier produced for an alias, and asserts
+/// the log and the returned step both come back clean.
+#[test]
+fn test_an_npm_alias_credential_is_redacted_from_the_log_and_the_returned_step() {
+    let password = "hunter2pass";
+    let h = harness_with_secrets(secret_values_from([(
+        "npm_config_proxy".to_string(),
+        format!("http://corpuser:{password}@proxy.example:8080"),
+    )]));
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stderr: format!(
+                    "npm ERR! proxy=http://corpuser:{password}@proxy.example:8080 tunneling failed"
+                ),
+                ..step("cli", false, "")
+            },
+            log_stdout: String::new(),
+            log_stderr: format!(
+                "npm config: proxy = http://corpuser:{password}@proxy.example:8080"
+            ),
+        },
+    );
+
+    let log = h.log_contents();
+    assert!(!log.contains(password), "log leaked the password: {log}");
+    assert!(
+        log.contains("proxy.example"),
+        "the proxy host is diagnostic and must survive: {log}"
+    );
+    assert!(
+        !returned.stderr.contains(password),
+        "the returned step leaked the password: {}",
+        returned.stderr
+    );
+}
+
+// ── npm's own credential settings ────────────────────────────────────────────
+
+/// npm accepts every one of its settings as an `npm_config_*` variable, so a
+/// registry client key, a basic-auth blob or a one-time password can arrive
+/// under a name that carries no marker. Their whole value is the credential —
+/// unlike a proxy, none of it is diagnostic — and npm spells them in lowercase.
+#[test]
+fn test_npm_credential_configs_are_secret_in_either_case() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_key".to_string(),
+            "-----BEGIN PRIVATE KEY-----lowerkey".to_string(),
+        ),
+        (
+            "NPM_CONFIG_KEY".to_string(),
+            "-----BEGIN PRIVATE KEY-----upperkey".to_string(),
+        ),
+        ("npm_config__auth".to_string(), "bG93ZXJhdXRo".to_string()),
+        ("NPM_CONFIG__AUTH".to_string(), "dXBwZXJhdXRo".to_string()),
+        ("npm_config_otp".to_string(), "618243".to_string()),
+        ("NPM_CONFIG_OTP".to_string(), "907154".to_string()),
+    ]);
+
+    assert_eq!(
+        secrets,
+        vec![
+            "-----BEGIN PRIVATE KEY-----lowerkey",
+            "-----BEGIN PRIVATE KEY-----upperkey",
+            "bG93ZXJhdXRo",
+            "dXBwZXJhdXRo",
+            "618243",
+            "907154",
+        ]
+    );
+}
+
+/// An unset-but-exported credential is empty, and an empty needle would match
+/// everywhere. The name being exact does not make a blank value a secret.
+#[test]
+fn test_an_empty_npm_credential_config_contributes_no_secret() {
+    let secrets = secret_values_from([
+        ("NPM_CONFIG_KEY".to_string(), String::new()),
+        ("npm_config_otp".to_string(), String::new()),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// A private registry's URL follows the proxy policy rather than the whole-value
+/// one: which registry an install talked to is exactly what a 401 or an ETIMEDOUT
+/// has to be read against, so only the userinfo is the secret.
+#[test]
+fn test_npm_registry_userinfo_is_secret_but_the_registry_host_is_not() {
+    let secrets = secret_values_from([(
+        "npm_config_registry".to_string(),
+        "https://builder:hunter2pass@registry.example/api/npm/".to_string(),
+    )]);
+
+    assert_eq!(secrets, vec!["builder:hunter2pass"]);
+}
+
+/// The public registry — and any private one reached with a token header rather
+/// than URL credentials — contributes nothing, so the registry stays named in
+/// the record.
+#[test]
+fn test_an_npm_registry_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_registry".to_string(),
+            "https://registry.npmjs.org/".to_string(),
+        ),
+        (
+            "NPM_CONFIG_REGISTRY".to_string(),
+            "https://builder@registry.example/api/npm/".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The credential settings are matched by exact name, never by a `KEY` or
+/// `AUTH` substring. Those occur throughout an ordinary environment on values
+/// that are paths, agent sockets and people's names, and scrubbing them would
+/// delete unrelated text from every record.
+#[test]
+fn test_key_and_auth_inside_a_variable_name_do_not_make_it_secret() {
+    let secrets = secret_values_from([
+        (
+            "SSH_AUTH_SOCK".to_string(),
+            "/tmp/ssh-agent.socket".to_string(),
+        ),
+        ("GIT_AUTHOR_NAME".to_string(), "Ada Lovelace".to_string()),
+        (
+            "KEYCHAIN".to_string(),
+            "/Users/dev/Library/login.keychain".to_string(),
+        ),
+        (
+            "NPM_CONFIG_KEYFILE".to_string(),
+            "/Users/dev/.npm/client.pem".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The wiring, not just the classification: npm prints its resolved config on an
+/// auth failure, so each of these has to be gone from the log and from the step
+/// the frontend renders. The one-time password is the interesting one — at six
+/// digits it is far shorter than any other secret here, and a value under four
+/// bytes is dropped by the shared redactor rather than scrubbed.
+#[test]
+fn test_npm_credential_configs_are_redacted_from_the_log_and_the_returned_step() {
+    let client_key = "-----BEGIN PRIVATE KEY-----MIIEvQIBADAN";
+    let auth = "YnVpbGRlcjpodW50ZXIycGFzcw==";
+    let otp = "618243";
+    let registry_password = "hunter2pass";
+    let h = harness_with_secrets(secret_values_from([
+        ("npm_config_key".to_string(), client_key.to_string()),
+        ("npm_config__auth".to_string(), auth.to_string()),
+        ("npm_config_otp".to_string(), otp.to_string()),
+        (
+            "npm_config_registry".to_string(),
+            format!("https://builder:{registry_password}@registry.example/api/npm/"),
+        ),
+    ]));
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stderr: format!("npm ERR! 401 otp={otp} _auth={auth}"),
+                ..step("cli", false, "")
+            },
+            log_stdout: format!("npm config: key = {client_key}"),
+            log_stderr: format!(
+                "npm config: registry = https://builder:{registry_password}@registry.example/api/npm/"
+            ),
+        },
+    );
+
+    let log = h.log_contents();
+    for secret in [client_key, auth, otp, registry_password] {
+        assert!(!log.contains(secret), "log leaked {secret}: {log}");
+    }
+    assert!(
+        log.contains("registry.example"),
+        "the registry host is diagnostic and must survive: {log}"
+    );
+    assert!(
+        !returned.stderr.contains(otp) && !returned.stderr.contains(auth),
+        "the returned step leaked a credential: {}",
+        returned.stderr
+    );
+}
+
+/// `*_PATH` variables must not be mistaken for personal access tokens. A
+/// `contains("_PAT")` rule would match `PATH` itself and scrub every directory
+/// name out of the log, which is why the rule matches `_PAT` as a suffix.
+#[test]
+fn test_a_path_variable_is_not_treated_as_a_personal_access_token() {
+    let secrets = secret_values_from([
+        ("PATH".to_string(), "/usr/local/bin:/usr/bin".to_string()),
+        ("GOPATH".to_string(), "/home/user/go".to_string()),
+        (
+            "CARGO_HOME_PATH".to_string(),
+            "/home/user/.cargo".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// Variables named as personal access tokens are secret by name, whatever shape
+/// their value has.
+#[test]
+fn test_pat_named_variables_are_secret() {
+    let secrets = secret_values_from([
+        (
+            "GITHUB_PAT".to_string(),
+            "ghp_abcdefghij0123456789".to_string(),
+        ),
+        (
+            "GH_PAT".to_string(),
+            "github_pat_abcdefghij0123".to_string(),
+        ),
+    ]);
+
+    assert_eq!(secrets.len(), 2, "got: {secrets:?}");
+}
+
+/// The whole point of the widening: a proxy password and a PAT that the
+/// installer echoed reach neither the log nor the live line.
+///
+/// Both are checked through the real reporter rather than the classifier, so
+/// this covers the wiring — a classifier that recognises a secret the reporter
+/// never consults would still leak.
+#[test]
+fn test_proxy_and_pat_credentials_are_redacted_from_the_log_and_the_live_line() {
+    let proxy_password = "hunter2pass";
+    let pat = "ghp_abcdefghij0123456789";
+    // The classifier's own tests cover recognising these under their real
+    // variable names; injecting the resulting secrets here keeps a live
+    // `HTTPS_PROXY` out of the process the rest of the suite shares.
+    let h = harness_with_secrets(vec![format!("corpuser:{proxy_password}"), pat.to_string()]);
+
+    h.reporter.record_attempt(
+        1,
+        outcome(
+            "cli",
+            false,
+            &format!(
+                "npm ERR! proxy=http://corpuser:{proxy_password}@proxy.example authToken={pat}"
+            ),
+        ),
+    );
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer(&format!("cloning https://{pat}@github.com/org/repo"));
+
+    let log = h.log_contents();
+    assert!(
+        !log.contains(proxy_password),
+        "log leaked the proxy password: {log}"
+    );
+    assert!(!log.contains(pat), "log leaked the PAT: {log}");
+    assert!(
+        log.contains("proxy.example"),
+        "the proxy host is diagnostic and must survive: {log}"
+    );
+
+    let line = h.lines().into_iter().flatten().next().expect("a live line");
+    assert!(!line.contains(pat), "live line leaked the PAT: {line}");
+    assert!(line.contains("[REDACTED]"), "got: {line}");
+}
+
+/// The third surface: the step returned to the frontend. `getInstallErrorMessage`
+/// renders the failing step's stderr verbatim, so a secret that the log and the
+/// live line both scrub would still reach the user through the error dialog.
+#[test]
+fn test_a_returned_step_is_redacted_before_the_frontend_renders_it() {
+    let pat = "ghp_abcdefghij0123456789";
+    let h = harness_with_secrets(vec![pat.to_string()]);
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stdout: format!("configuring remote with {pat}"),
+                stderr: format!("fatal: authentication failed for token {pat}"),
+                hint: Some(format!("check that {pat} has the repo scope")),
+                ..step("cli", false, "")
+            },
+            log_stdout: String::new(),
+            log_stderr: String::new(),
+        },
+    );
+
+    assert!(!returned.stdout.contains(pat), "got: {}", returned.stdout);
+    assert!(!returned.stderr.contains(pat), "got: {}", returned.stderr);
+    let hint = returned.hint.expect("a hint");
+    assert!(!hint.contains(pat), "got: {hint}");
+}
+
+/// A synthesized step reaches the frontend through the other funnel, and needs
+/// the same scrubbing — the managed-node prerequisite failures are built this
+/// way and carry whatever the underlying command printed.
+#[test]
+fn test_a_synthesized_step_is_redacted_before_it_reaches_the_caller() {
+    let pat = "ghp_abcdefghij0123456789";
+    let h = harness_with_secrets(vec![pat.to_string()]);
+    let mut steps = Vec::new();
+
+    h.reporter.record_step(
+        &mut steps,
+        InstallStepResult {
+            stderr: format!("npm ERR! 401 with {pat}"),
+            ..step("adapter", false, "")
+        },
+    );
+
+    assert_eq!(steps.len(), 1);
+    assert!(!steps[0].stderr.contains(pat), "got: {}", steps[0].stderr);
+    assert!(
+        steps[0].stderr.contains("[REDACTED]"),
+        "got: {}",
+        steps[0].stderr
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs
new file mode 100644
index 0000000000..17b2789560
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs
@@ -0,0 +1,106 @@
+//! Shared harness for the install-report test modules.
+//!
+//! The tests are split by concern — redaction in
+//! [`super::install_report_redaction_tests`], everything else in
+//! [`super::install_report_tests`] — and both drive the reporter through the
+//! same harness, so it lives here rather than in either of them.
+
+use super::*;
+use std::sync::Mutex;
+
+/// Stands in for the real `app.package_info().version`, which needs a Tauri app.
+pub(crate) const TEST_APP_VERSION: &str = "9.9.9";
+
+/// A reporter with a started log session in a temp dir, and the emitted events
+/// captured.
+pub(crate) struct Harness {
+    /// Kept alive so the log outlives the harness; a test that reuses the
+    /// directory for a second run takes it.
+    pub(crate) _dir: tempfile::TempDir,
+    pub(crate) log: PathBuf,
+    pub(crate) reporter: InstallReporter,
+    pub(crate) events: Arc<Mutex<Vec<InstallOutputEvent>>>,
+}
+
+pub(crate) fn harness() -> Harness {
+    harness_at(None)
+}
+
+/// A harness whose log lives in `dir`, or in a fresh temp dir when `dir` is
+/// `None`. Passing a directory lets a test seed a previous run's file first.
+pub(crate) fn harness_at(dir: Option<tempfile::TempDir>) -> Harness {
+    harness_inner(dir, None)
+}
+
+/// A harness whose reporter scrubs exactly `secrets`, so a proxy or PAT
+/// credential can be asserted without exporting it into the process.
+pub(crate) fn harness_with_secrets(secrets: Vec<String>) -> Harness {
+    harness_inner(None, Some(secrets))
+}
+
+fn harness_inner(dir: Option<tempfile::TempDir>, secrets: Option<Vec<String>>) -> Harness {
+    let dir = dir.unwrap_or_else(|| tempfile::tempdir().expect("tempdir"));
+    let log = dir.path().join("install-goose.log");
+    let events: Arc<Mutex<Vec<InstallOutputEvent>>> = Arc::new(Mutex::new(Vec::new()));
+    let emit: EmitEvent = {
+        let events = Arc::clone(&events);
+        Arc::new(move |event| events.lock().unwrap().push(event))
+    };
+    let started = InstallLog::start(&log, "goose", TEST_APP_VERSION);
+    Harness {
+        reporter: match secrets {
+            Some(secrets) => InstallReporter::with_secrets("goose", started, Some(emit), secrets),
+            None => InstallReporter::new("goose", started, Some(emit)),
+        },
+        _dir: dir,
+        log,
+        events,
+    }
+}
+
+/// A reporter with no log file and nothing listening — the degraded shape.
+pub(crate) fn silent_reporter() -> InstallReporter {
+    InstallReporter::new("goose", None, None)
+}
+
+pub(crate) fn step(name: &str, success: bool, stderr: &str) -> InstallStepResult {
+    InstallStepResult {
+        step: name.to_string(),
+        command: "curl … | bash".to_string(),
+        success,
+        stdout: String::new(),
+        stderr: stderr.to_string(),
+        exit_code: Some(if success { 0 } else { 1 }),
+        hint: None,
+    }
+}
+
+/// An executed attempt whose log copy differs from the UI copy — the real shape,
+/// since the two views are capped differently.
+pub(crate) fn outcome(name: &str, success: bool, log_stdout: &str) -> InstallOutcome {
+    InstallOutcome {
+        step: step(name, success, ""),
+        log_stdout: log_stdout.to_string(),
+        log_stderr: String::new(),
+    }
+}
+
+impl Harness {
+    pub(crate) fn log_contents(&self) -> String {
+        std::fs::read_to_string(&self.log).unwrap_or_default()
+    }
+
+    /// The emitted lines in order, with a clear signal rendered as `None`.
+    pub(crate) fn lines(&self) -> Vec<Option<String>> {
+        self.events
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|e| e.line.clone())
+            .collect()
+    }
+
+    pub(crate) fn events(&self) -> Vec<InstallOutputEvent> {
+        self.events.lock().unwrap().clone()
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs
new file mode 100644
index 0000000000..c286b618b6
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs
@@ -0,0 +1,564 @@
+use super::test_support::*;
+use super::*;
+use crate::commands::agent_discovery::install_capture::{drain_into, Capture};
+
+// ── the log records history the UI does not keep ─────────────────────────────
+
+/// Every attempt is recorded, not just the one the UI surfaces. Reproducing an
+/// install failure means seeing whether attempts 1 and 2 failed the same way.
+#[test]
+fn test_log_records_every_attempt_not_only_the_last() {
+    let h = harness();
+
+    h.reporter
+        .record_attempt(1, outcome("cli", false, "attempt-one-output"));
+    h.reporter
+        .record_attempt(2, outcome("cli", false, "attempt-two-output"));
+
+    let log = h.log_contents();
+    assert!(log.contains("attempt-one-output"), "got: {log}");
+    assert!(log.contains("attempt-two-output"), "got: {log}");
+    assert!(
+        log.contains("attempt=1") && log.contains("attempt=2"),
+        "got: {log}"
+    );
+}
+
+/// A first attempt that printed a huge amount must not push later records out of
+/// the file. Records are capped individually by the log-scale capture that
+/// produced them, so the run's total is bounded by steps × attempts × cap rather
+/// than by one runaway attempt.
+///
+/// The flood goes through a real [`Capture`] rather than straight into the
+/// record, so this exercises the cap that actually bounds a record.
+#[test]
+fn test_first_attempt_overflow_does_not_erase_later_records() {
+    let h = harness();
+    // Through the real drain, so the record is bounded by the cap that bounds a
+    // production record rather than by a string this test chose.
+    let capture = Capture::new();
+    drain_into(vec![b'F'; 4 * 1024 * 1024].as_slice(), &capture, None);
+
+    h.reporter
+        .record_attempt(1, outcome("cli", false, &capture.log()));
+    h.reporter
+        .record_attempt(2, outcome("cli", false, "second-attempt-detail"));
+    h.reporter.record_step(
+        &mut Vec::new(),
+        step("verify", false, "verification-detail"),
+    );
+
+    let log = h.log_contents();
+    assert!(
+        log.contains("bytes omitted at cap"),
+        "the flooded record must be marked as cut"
+    );
+    assert!(
+        log.contains("second-attempt-detail"),
+        "a later attempt must survive an earlier flood"
+    );
+    assert!(
+        log.contains("verification-detail"),
+        "the synthesized step explaining the failure must survive too"
+    );
+    assert!(
+        log.len() < 4 * 1024 * 1024,
+        "4MiB of first-attempt output must not reach the file, got {} bytes",
+        log.len()
+    );
+}
+
+/// A step Buzz synthesizes — a failed prerequisite, or post-install
+/// verification — reaches the log as well as the UI. `record_step` is the only
+/// path that guarantees this, which is why callers use it instead of
+/// `steps.push`.
+#[test]
+fn test_recording_a_synthesized_step_logs_it_and_keeps_it_for_the_ui() {
+    let h = harness();
+    let mut steps = Vec::new();
+
+    h.reporter
+        .record_step(&mut steps, step("verify", false, "still-not-usable"));
+
+    assert_eq!(steps.len(), 1, "the UI must still receive the step");
+    assert!(h.log_contents().contains("still-not-usable"));
+}
+
+// ── one file per run ─────────────────────────────────────────────────────────
+
+/// A run opens with a header naming the runtime and the environment the run
+/// happened in, so a file holding one run of several steps is identifiable as
+/// that run rather than a stream of records — and a failure report says which
+/// app version and OS produced it without a second round trip to the user.
+#[test]
+fn test_a_run_opens_with_a_header_naming_the_runtime_app_version_and_os() {
+    let h = harness();
+    let log = h.log_contents();
+
+    assert!(
+        log.starts_with(&format!(
+            "=== install run runtime=goose app={TEST_APP_VERSION} os={} started=",
+            std::env::consts::OS
+        )),
+        "got: {log}"
+    );
+}
+
+/// A new run does not append to the previous run's file: it starts a fresh one
+/// and keeps the previous as `.1`. Reading a log has to mean reading one run —
+/// records accumulated across runs are indistinguishable from retries within
+/// one.
+#[test]
+fn test_a_new_run_starts_a_fresh_file_and_keeps_the_previous_as_dot_one() {
+    let first = harness();
+    first
+        .reporter
+        .record_attempt(1, outcome("cli", false, "previous-run-output"));
+    let previous = first.log.clone();
+    let dir = first._dir;
+    drop(first.reporter);
+
+    let second = harness_at(Some(dir));
+    second
+        .reporter
+        .record_attempt(1, outcome("cli", false, "current-run-output"));
+
+    let log = second.log_contents();
+    assert!(log.contains("current-run-output"), "got: {log}");
+    assert!(
+        !log.contains("previous-run-output"),
+        "the new run's file must not carry the previous run's records: {log}"
+    );
+    let rotated = std::fs::read_to_string(previous.with_extension("log.1")).expect("read .1");
+    assert!(
+        rotated.contains("previous-run-output"),
+        "the previous run must remain readable as .1: {rotated}"
+    );
+}
+
+/// Each executed attempt records how long it ran. A 15-minute ceiling is only
+/// diagnosable if the file says which attempt consumed the time.
+#[test]
+fn test_an_executed_attempt_records_its_own_duration() {
+    let h = harness();
+
+    h.reporter.start_attempt();
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+    h.reporter
+        .record_step(&mut Vec::new(), step("verify", true, ""));
+
+    let log = h.log_contents();
+    assert!(
+        log.contains("attempt=1") && log.contains("elapsed=0."),
+        "an executed attempt must carry its duration: {log}"
+    );
+    assert!(
+        log.contains("attempt=- ") && log.contains("elapsed=-"),
+        "a synthesized step never ran, so it has no duration: {log}"
+    );
+}
+
+// ── the log pointer ──────────────────────────────────────────────────────────
+
+/// The path is available as soon as the run's session opens, because the file
+/// exists from that moment — the header is already in it. A failure before any
+/// step ran still points the user at a real file.
+#[test]
+fn test_log_path_is_available_from_the_start_of_the_run() {
+    let h = harness();
+
+    assert_eq!(h.reporter.log_path(), Some(h.log.display().to_string()));
+}
+
+/// A reporter with no log — an unresolvable app-data directory — records
+/// nothing and reports no path, but must not panic or fail the install.
+#[test]
+fn test_reporter_without_a_log_records_nothing_and_reports_no_path() {
+    let reporter = silent_reporter();
+    let mut steps = Vec::new();
+
+    reporter.start_attempt();
+    reporter.record_attempt(1, outcome("cli", false, "output"));
+    reporter.record_step(&mut steps, step("verify", false, "detail"));
+
+    assert_eq!(reporter.log_path(), None);
+    assert_eq!(steps.len(), 1, "the UI path is unaffected by a missing log");
+}
+
+/// A log path inside a directory that no longer exists cannot open a session, so
+/// the run degrades to no log rather than failing.
+#[test]
+fn test_an_unopenable_log_degrades_to_no_log() {
+    let path = PathBuf::from("/nonexistent-dir-for-test/install-goose.log");
+
+    assert!(InstallLog::start(&path, "goose", TEST_APP_VERSION).is_none());
+}
+
+// ── live output line ─────────────────────────────────────────────────────────
+
+/// Lines carry an install-wide monotonic sequence number, so the UI can order
+/// them across steps and attempts — which a per-step retry number cannot do.
+#[test]
+fn test_emitted_lines_carry_their_runtime_and_a_monotonic_sequence() {
+    let h = harness();
+
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("downloading");
+    h.reporter.start_attempt();
+
+    let events = h.events();
+    assert_eq!(events.len(), 2);
+    assert!(events.iter().all(|e| e.runtime_id == "goose"));
+    assert_eq!(events[0].line.as_deref(), Some("downloading"));
+    assert_eq!(events[0].seq, 0);
+    assert_eq!(
+        events[1].seq, 1,
+        "the clear signal takes the next sequence number, so it cannot be \
+         mistaken for a stale event"
+    );
+}
+
+/// Starting an attempt clears the display first: the previous attempt's last
+/// line is typically the failure that caused the retry, and leaving it under the
+/// spinner through the backoff shows the user the past as if it were current.
+#[test]
+fn test_starting_an_attempt_clears_the_displayed_line() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("download failed");
+
+    h.reporter.start_attempt();
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("download failed".to_string()), None],
+        "the attempt boundary must emit a clear"
+    );
+}
+
+/// The clear is not rate-limited, and it reopens the window: a new attempt's
+/// first line goes out immediately even if it arrives inside the previous
+/// attempt's window. This is the case the throttle used to swallow entirely.
+#[test]
+fn test_a_new_attempts_first_line_is_emitted_even_inside_the_previous_window() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("attempt one failed");
+
+    // No wait: the previous line was emitted microseconds ago, so this is well
+    // inside the 250ms window.
+    h.reporter.start_attempt();
+    observer("attempt two starting");
+
+    assert_eq!(
+        h.lines(),
+        vec![
+            Some("attempt one failed".to_string()),
+            None,
+            Some("attempt two starting".to_string()),
+        ]
+    );
+}
+
+/// A burst inside the window coalesces to one event, and the line it emits is
+/// the *newest* — the display shows current progress, not the line that happened
+/// to arrive when the window opened.
+#[test]
+fn test_a_burst_coalesces_to_the_newest_line_not_the_first() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+
+    observer("one");
+    observer("two");
+    observer("three");
+    // Ends the attempt, which is when a held line is known to be the last.
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("one".to_string()), Some("three".to_string())],
+        "the held line must be the newest, and it must not be lost"
+    );
+}
+
+/// The throttle is per install, not per stream: stdout and stderr of one attempt
+/// share one window, so an install printing on both does not double the event
+/// rate.
+#[test]
+fn test_both_streams_of_one_attempt_share_the_rate_window() {
+    let h = harness();
+    let stdout = h.reporter.line_observer().expect("an observer");
+    let stderr = h.reporter.line_observer().expect("an observer");
+
+    stdout("progress");
+    stderr("warning");
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("progress".to_string()), Some("warning".to_string())],
+        "the second stream's line is held, not emitted immediately, and not lost"
+    );
+}
+
+/// Nothing listening means no observer at all, so the drain skips line
+/// reassembly entirely rather than doing the work and discarding it.
+#[test]
+fn test_no_observer_when_nothing_is_listening() {
+    assert!(silent_reporter().line_observer().is_none());
+}
+
+// ── late-drain deactivation ──────────────────────────────────────────────────
+
+/// After the reporter is dropped (run settled), a drain thread that still holds
+/// a cloned observer must not be able to emit. The lifecycle lock is shared by
+/// reference with every `line_observer` clone, so taking the exclusive write
+/// lock in `Drop` — which waits out any in-flight read guards — ensures no
+/// late event can reach the listener.
+///
+/// The test resets the throttle via `start_attempt` before the late emit, so
+/// the late line would be emitted unconditionally without the lifecycle lock.
+#[test]
+fn test_a_detached_observer_cannot_emit_after_the_reporter_is_dropped() {
+    let h = harness();
+
+    // Simulate a drain thread: `line_observer` clones `Live` (owned, not
+    // borrowed), so the closure outlives the reporter.
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("before-settle");
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("before-settle".to_string())],
+        "a live observer must emit before the reporter drops"
+    );
+
+    // Open a fresh throttle window so the next offer would emit immediately —
+    // simulating the drain arriving after the 250ms rate window closed.
+    h.reporter.start_attempt();
+    let events = Arc::clone(&h.events);
+
+    // Drop the reporter — takes the exclusive lifecycle write lock, waits for
+    // any in-flight publications, then deactivates.
+    drop(h);
+
+    // A late offer after drop must be blocked by the deactivated lifecycle.
+    observer("late-drain-after-settle");
+
+    let lines: Vec<Option<String>> = events
+        .lock()
+        .unwrap()
+        .iter()
+        .map(|e| e.line.clone())
+        .collect();
+    assert_eq!(
+        lines,
+        // before-settle + the clear from start_attempt, no late line
+        vec![Some("before-settle".to_string()), None],
+        "a detached observer must not emit after the reporter is dropped"
+    );
+}
+
+/// Deterministic concurrency pin: proves that reporter deactivation cannot
+/// complete while a drain thread is in-flight between admission and publication.
+///
+/// The lifecycle `RwLock` enforces this: drain threads hold a shared read guard
+/// for the entire (check → emit) span, so `InstallReporter::drop`'s write lock
+/// blocks until every admitted publication finishes.
+///
+/// **How this test fails on the old atomic shape** (`dc6421ac4`): on that shape,
+/// `offer` loads `active` once as a plain atomic read and then calls `publish`
+/// independently. There is no shared lock, so `drop` (an atomic store) can
+/// complete while the thread is between the load and the emit — the test
+/// exposes this by asserting the write lock CANNOT be acquired while a reader
+/// holds a read guard. On the atomic shape the `lifecycle` field does not exist,
+/// so the entire serialisation contract is absent and the pin fails.
+#[test]
+fn test_deactivation_blocks_until_in_flight_publication_completes() {
+    // Build a reporter and grab a Live clone that represents a drain thread.
+    let h = harness();
+    let live_clone = {
+        // Extract the `Live` from a `line_observer` closure by temporarily
+        // building a second observer and using the lifecycle Arc directly.
+        h.reporter.line_observer().expect("observer");
+        // Clone the inner lifecycle from the reporter's `Live` via a
+        // white-box path: the test module is a child of install_report and
+        // can access private fields.
+        h.reporter
+            .live
+            .as_ref()
+            .expect("live exists")
+            .lifecycle
+            .clone()
+    };
+
+    // Phase 1: acquire the shared read guard (admission).
+    let guard = live_clone.read().expect("lifecycle read");
+    assert!(*guard, "lifecycle must be active at admission");
+
+    // Phase 2: while the read guard is held, a write lock must be blocked.
+    // This is the core serialisation invariant: `Drop` cannot complete until
+    // every admitted reader releases its guard.
+    assert!(
+        live_clone.try_write().is_err(),
+        "a write lock must not be acquirable while a read guard is held — \
+         Drop must block while a publication is in-flight"
+    );
+
+    // Phase 3: release the read guard (publication completed).
+    drop(guard);
+
+    // Phase 4: write lock is now available, and Drop can set active=false.
+    let mut write = live_clone.write().expect("lifecycle write");
+    *write = false;
+    drop(write);
+
+    // Phase 5: a new reader after deactivation sees active=false and returns.
+    let guard2 = live_clone.read().expect("lifecycle read");
+    assert!(
+        !*guard2,
+        "lifecycle must be inactive after deactivation — new admissions rejected"
+    );
+}
+
+/// Shared-consumer assertion: drive a potential late run-1 event AND run-2's
+/// events through the same `nextInstallOutputLine`-equivalent reducer and assert
+/// that run 2's output replaces — not revives — any stale run-1 state.
+///
+/// The frontend reduces events into a single consumer that resets to `null`
+/// when `isInstalling` goes false (i.e., when the run settles).  This test
+/// models that reset and verifies the full cross-run contract:
+///
+/// 1. Run 1 emits normally; the late drain is silenced by the lifecycle lock
+///    (no event with a high run-1 `seq` ever reaches the shared sink).
+/// 2. At run-1 settlement the consumer resets to `null`, exactly as the
+///    frontend hook does when `isInstalling` becomes false.
+/// 3. Run 2 starts, emits its `seq=0` clear and first line.  With a null-state
+///    consumer the reducer accepts both immediately — even if a late run-1
+///    event HAD arrived (it didn't), the reset would have cleared its seq.
+///
+/// **Why this test fails on the old atomic shape**: without the lifecycle lock,
+/// `obs1("late-run-one-drain")` emits a high-seq run-1 event into the shared
+/// sink.  That event arrives AFTER the consumer reset (its seq is accepted from
+/// a null state), leaving `{ seq: N, line: "late-run-one-drain" }` in the
+/// consumer.  Run 2 then emits `seq=0` and `seq=1`, both ≤ N, so they are
+/// rejected and the final state stays on run 1's output.
+#[test]
+fn test_run2_output_replaces_stale_run1_state_through_shared_consumer() {
+    // One shared event sink for all events from both runs, simulating the
+    // permanent frontend listener that receives all `acp-install-output` events.
+    let all_events: Arc<Mutex<Vec<InstallOutputEvent>>> = Arc::new(Mutex::new(Vec::new()));
+    // Track where run 1 settles so the consumer reset can be applied at the
+    // correct boundary in the fold below.
+    let run1_settle_len: Arc<Mutex<usize>> = Arc::new(Mutex::new(0));
+    let runtime_id = "goose";
+
+    // ── Run 1 ──────────────────────────────────────────────────────────────
+    let dir1 = tempfile::tempdir().expect("tempdir");
+    let log1 = dir1.path().join("install-goose.log");
+    let emit1: EmitEvent = {
+        let sink = Arc::clone(&all_events);
+        Arc::new(move |event| sink.lock().unwrap().push(event))
+    };
+    let reporter1 = InstallReporter::new(
+        runtime_id,
+        InstallLog::start(&log1, runtime_id, "1.0.0"),
+        Some(emit1),
+    );
+
+    reporter1.start_attempt();
+    let obs1 = reporter1.line_observer().expect("observer");
+    obs1("run-one-output");
+    reporter1.record_attempt(1, outcome("cli", true, "done"));
+
+    // Drop reporter1 — deactivates obs1 via the exclusive lifecycle write lock,
+    // which blocks until any in-flight read guard (publication) has released.
+    drop(reporter1);
+
+    // Record the sink length at settlement — this is the point where the
+    // frontend resets its consumer state to null (isInstalling = false).
+    *run1_settle_len.lock().unwrap() = all_events.lock().unwrap().len();
+
+    // A late drain from run 1 arrives after settlement.  With the lifecycle
+    // lock this is silenced.  Without the lock (old atomic shape) it would
+    // reach the sink with a high seq, poisoning the null-reset consumer before
+    // run 2 can emit its restarted seq=0.
+    // Reset the throttle so the offer would emit unconditionally if the lock
+    // were absent — this makes the mutation meaningful.
+    {
+        // We need a fresh throttle window.  Simulate by directly restarting
+        // via a new reporter to touch the shared Live (not possible after drop),
+        // so instead just call offer — the throttle holds the last emit time
+        // from flush_pending, which was microseconds ago.  Give the window time
+        // to expire so the offer fires immediately on the old atomic shape.
+        std::thread::sleep(Duration::from_millis(300));
+    }
+    obs1("late-run-one-drain");
+
+    // ── Run 2 ──────────────────────────────────────────────────────────────
+    let dir2 = tempfile::tempdir().expect("tempdir");
+    let log2 = dir2.path().join("install-goose.log");
+    let emit2: EmitEvent = {
+        let sink = Arc::clone(&all_events);
+        Arc::new(move |event| sink.lock().unwrap().push(event))
+    };
+    let reporter2 = InstallReporter::new(
+        runtime_id,
+        InstallLog::start(&log2, runtime_id, "1.0.0"),
+        Some(emit2),
+    );
+
+    reporter2.start_attempt();
+    let obs2 = reporter2.line_observer().expect("observer");
+    obs2("run-two-first-line");
+    reporter2.record_attempt(1, outcome("cli", true, "done"));
+
+    // ── Shared-consumer fold ────────────────────────────────────────────────
+    // Fold all emitted events through the nextInstallOutputLine reducer logic.
+    // At the run-1 settlement boundary, reset consumer to null — exactly as
+    // the frontend hook does when isInstalling becomes false.
+    struct State {
+        seq: u64,
+        line: Option<String>,
+    }
+    let settle_at = *run1_settle_len.lock().unwrap();
+    let events = all_events.lock().unwrap().clone();
+    let mut consumer: Option<State> = None;
+    for (i, event) in events.iter().enumerate() {
+        // Simulate frontend reset at run-1 settlement boundary.
+        if i == settle_at {
+            consumer = None;
+        }
+        if event.runtime_id != runtime_id {
+            continue;
+        }
+        if let Some(ref c) = consumer {
+            if event.seq <= c.seq {
+                continue; // reject stale / out-of-order
+            }
+        }
+        consumer = Some(State {
+            seq: event.seq,
+            line: event.line.clone(),
+        });
+    }
+
+    // The final consumer state must be run 2's first line.
+    //
+    // With the lifecycle lock: obs1("late-run-one-drain") emits nothing,
+    // so after the null reset only run-2 events arrive — run 2 wins cleanly.
+    //
+    // Without the lifecycle lock (old atomic shape): obs1 emits the late line
+    // with a high seq into the already-reset (null) consumer, consumer becomes
+    // { seq: N, line: "late-run-one-drain" }.  Run 2's seq=0/1 are both ≤ N
+    // and are rejected, leaving the final state on run 1's stale output.
+    let final_line = consumer
+        .as_ref()
+        .and_then(|s| s.line.as_deref())
+        .unwrap_or("<none>");
+    assert_eq!(
+        final_line, "run-two-first-line",
+        "run 2 must replace — not revive — stale run-1 state through the shared consumer; \
+         got: {final_line:?}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs b/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
index 3155104b56..535d4c9ecb 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
@@ -1,13 +1,19 @@
 use crate::managed_agents::{AcpAvailabilityStatus, InstallStepResult};
 
-pub(super) fn run(runtime_id: &str, steps: &mut Vec<InstallStepResult>) {
+use super::install_report::InstallReporter;
+
+pub(super) fn run(
+    runtime_id: &str,
+    steps: &mut Vec<InstallStepResult>,
+    reporter: &InstallReporter,
+) {
     // Observe PATH changes and binaries added after Buzz launched.
     crate::managed_agents::refresh_login_shell_path();
     crate::managed_agents::clear_resolve_cache();
 
     let availability = crate::managed_agents::discover_acp_runtime_availability(runtime_id);
     if let Some(failure) = failure(runtime_id, availability) {
-        steps.push(failure);
+        reporter.record_step(steps, failure);
     }
 }
 
diff --git a/desktop/src-tauri/src/commands/export_util.rs b/desktop/src-tauri/src/commands/export_util.rs
index 806f58d739..ded14679c1 100644
--- a/desktop/src-tauri/src/commands/export_util.rs
+++ b/desktop/src-tauri/src/commands/export_util.rs
@@ -1,16 +1,14 @@
 use tauri::AppHandle;
 use tauri_plugin_dialog::DialogExt;
 
-/// Show a save-file dialog with a custom filter and write `data` to the chosen
-/// path. Returns `Ok(true)` when the file was written, `Ok(false)` when the
-/// user cancelled the dialog.
-pub async fn save_bytes_with_dialog(
+/// Show a save-file dialog with a custom filter and return the chosen path,
+/// or `None` when the user cancelled. Selection only — no write.
+pub async fn pick_save_path(
     app: &AppHandle,
     suggested_filename: &str,
     filter_name: &str,
     extensions: &[&str],
-    data: &[u8],
-) -> Result<bool, String> {
+) -> Result<Option<std::path::PathBuf>, String> {
     let (tx, rx) = tokio::sync::oneshot::channel();
     app.dialog()
         .file()
@@ -23,12 +21,34 @@ pub async fn save_bytes_with_dialog(
     let selected = rx.await.map_err(|_| "dialog cancelled".to_string())?;
     let file_path = match selected {
         Some(p) => p,
-        None => return Ok(false),
+        None => return Ok(None),
     };
 
     let dest = file_path
         .as_path()
         .ok_or_else(|| "Save dialog returned an invalid path".to_string())?;
+    Ok(Some(dest.to_path_buf()))
+}
+
+/// Show a save-file dialog with a custom filter and write `data` to the chosen
+/// path. Returns `Ok(true)` when the file was written, `Ok(false)` when the
+/// 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`.
+pub async fn save_bytes_with_dialog(
+    app: &AppHandle,
+    suggested_filename: &str,
+    filter_name: &str,
+    extensions: &[&str],
+    data: &[u8],
+) -> Result<bool, String> {
+    let dest = match pick_save_path(app, suggested_filename, filter_name, extensions).await? {
+        Some(p) => p,
+        None => return Ok(false),
+    };
+
     std::fs::write(dest, data).map_err(|e| format!("Failed to write file: {e}"))?;
 
     Ok(true)
diff --git a/desktop/src-tauri/src/commands/identity.rs b/desktop/src-tauri/src/commands/identity.rs
index 2840c0ade6..33ecf3cfca 100644
--- a/desktop/src-tauri/src/commands/identity.rs
+++ b/desktop/src-tauri/src/commands/identity.rs
@@ -43,6 +43,7 @@ pub fn get_identity(state: State<'_, AppState>) -> Result<IdentityInfo, String>
     Ok(IdentityInfo {
         pubkey: pubkey_hex,
         display_name,
+        storage: state.identity_storage().as_str().to_string(),
         lost,
         locked,
         reset_failed,
@@ -194,14 +195,157 @@ pub fn get_nsec(state: State<'_, AppState>) -> Result<String, String> {
         .map_err(|error| format!("encode nsec: {error}"))
 }
 
+/// Generate a passphrase for a new encrypted backup (EFF short wordlist, OS
+/// entropy). `words` is clamped to the range allowed by `key_backup`;
+/// `separator` joins the words (defaults to a space).
+#[tauri::command]
+pub fn generate_backup_passphrase(
+    words: Option<u32>,
+    separator: Option<String>,
+) -> Result<String, String> {
+    crate::key_backup::generate_passphrase(
+        words.map_or(crate::key_backup::DEFAULT_PASSPHRASE_WORDS, |w| w as usize),
+        separator.as_deref().unwrap_or(" "),
+    )
+}
+
+/// Core of [`create_ncryptsec_backup`], factored so tests can drive it with a
+/// bare `AppState` + temp dir (and a fast scrypt tier) without an `AppHandle`.
+pub(crate) fn create_backup_with_log_n(
+    state: &AppState,
+    password: &str,
+    log_n: u8,
+) -> Result<String, String> {
+    if password.chars().count() < crate::key_backup::MIN_PASSPHRASE_LEN {
+        return Err(format!(
+            "passphrase must be at least {} characters",
+            crate::key_backup::MIN_PASSPHRASE_LEN
+        ));
+    }
+
+    // Serialize against import_identity/persist_current_identity: the blob
+    // must be derived from — and persisted for — one stable identity. Also
+    // caps KDF concurrency at one.
+    let _mutation_guard = state.identity_mutation.lock().map_err(|e| e.to_string())?;
+
+    // Recovery mode (lost/locked) → Err, same gate as signing.
+    let keys = state.signing_keys()?;
+
+    crate::key_backup::create_backup_blob(&keys, password, log_n)
+}
+
+/// Create a NIP-49 backup of the live identity in memory.
+///
+/// Encrypts under `password`, decrypt-verifies the fresh blob against the live
+/// pubkey, and returns the `ncryptsec1…` string for the native save flow. The
+/// body runs under `identity_mutation`, so identity changes cannot race the KDF.
+#[tauri::command]
+pub async fn create_ncryptsec_backup(
+    password: String,
+    app_handle: tauri::AppHandle,
+) -> Result<String, String> {
+    tokio::task::spawn_blocking(move || {
+        let password = zeroize::Zeroizing::new(password);
+        let state = app_handle.state::<AppState>();
+        create_backup_with_log_n(&state, &password, crate::key_backup::BACKUP_LOG_N)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
+}
+
+#[derive(Debug, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackupVerification {
+    pub pubkey: String,
+    pub npub: String,
+    pub matches_current_identity: bool,
+}
+
+fn verify_ncryptsec_backup_inner(
+    state: &AppState,
+    ncryptsec: &str,
+    password: &str,
+) -> Result<BackupVerification, String> {
+    let keys = crate::key_backup::decrypt_ncryptsec(ncryptsec, password)?;
+    let pubkey = keys.public_key();
+    let current = state.signing_keys()?.public_key();
+    Ok(BackupVerification {
+        pubkey: pubkey.to_hex(),
+        npub: pubkey
+            .to_bech32()
+            .map_err(|e| format!("encode backup identity: {e}"))?,
+        matches_current_identity: pubkey == current,
+    })
+}
+
+/// Decrypt and validate a NIP-49 backup without exposing its secret key.
+#[tauri::command]
+pub async fn verify_ncryptsec_backup(
+    ncryptsec: String,
+    password: String,
+    app_handle: tauri::AppHandle,
+) -> Result<BackupVerification, String> {
+    tokio::task::spawn_blocking(move || {
+        let password = zeroize::Zeroizing::new(password);
+        let state = app_handle.state::<AppState>();
+        verify_ncryptsec_backup_inner(&state, &ncryptsec, &password)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
+}
+
+/// 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.
+#[tauri::command]
+pub async fn save_ncryptsec_copy(
+    ncryptsec: String,
+    app_handle: tauri::AppHandle,
+) -> Result<Option<String>, String> {
+    // Reject anything that is not a valid encrypted-key blob — this command
+    // must not become a generic file writer.
+    crate::key_backup::parse_ncryptsec(&ncryptsec)?;
+    let normalized = ncryptsec.trim().to_string();
+
+    let dest = match crate::commands::export_util::pick_save_path(
+        &app_handle,
+        crate::key_backup::BACKUP_FILE_NAME,
+        "Password-protected key backup",
+        &["ncryptsec"],
+    )
+    .await?
+    {
+        Some(p) => p,
+        None => return Ok(None),
+    };
+
+    let dest_for_write = dest.clone();
+    tokio::task::spawn_blocking(move || {
+        crate::key_backup::write_backup_file(&dest_for_write, &normalized)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))??;
+
+    Ok(Some(dest.display().to_string()))
+}
+
 #[tauri::command]
 pub async fn import_identity(
     nsec: String,
+    password: Option<String>,
     app_handle: tauri::AppHandle,
 ) -> Result<IdentityInfo, String> {
     tokio::task::spawn_blocking(move || {
-        let trimmed = nsec.trim();
-        let keys = Keys::parse(trimmed).map_err(|e| format!("Invalid private key: {e}"))?;
+        // NIP-49 backups require a passphrase and decrypt entirely in Rust.
+        // Raw nsec/hex input follows the existing parser path unchanged.
+        let password = password.map(zeroize::Zeroizing::new);
+        let keys = crate::key_backup::recover_keys_from_input(
+            &nsec,
+            password.as_ref().map(|value| value.as_str()),
+        )?;
 
         // Serialize against persist_current_identity: hold this guard for the
         // full function body so a concurrent stale persist can't overwrite
@@ -216,30 +360,14 @@ pub async fn import_identity(
         std::fs::create_dir_all(&data_dir).map_err(|e| format!("create app data dir: {e}"))?;
         let key_path = data_dir.join("identity.key");
 
-        // Persist into the OS keyring first (store → read-back verify → marker →
-        // delete file). Falls back to the 0o600 file when the keyring is
-        // unavailable; returns Err only when both backends fail.
-        let store = crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
-        crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
-
-        // Update in-memory keys BEFORE clearing recovery flags. The Release
-        // stores below pair with Acquire loads in get_identity: a reader
-        // observing false is guaranteed to see the updated keys.
-        let pubkey = keys.public_key();
-        *state.keys.lock().map_err(|e| e.to_string())? = keys;
-
-        // Clear both recovery flags — an import is valid in either lost or
-        // keyring-locked state and resolves both. In the locked case the
-        // keyring is unreachable, so persist_imported_identity already fell
-        // back to identity.key; on the next Unreachable boot the file is
-        // loaded directly and when the keyring returns the adoption path
-        // picks it up.
-        state
-            .identity_lost
-            .store(false, std::sync::atomic::Ordering::Release);
-        state
-            .keyring_locked
-            .store(false, std::sync::atomic::Ordering::Release);
+        let (pubkey, storage) = commit_imported_identity(&state, &data_dir, keys, |keys| {
+            // Persist into the OS keyring first (store → read-back verify →
+            // marker → delete file). Falls back to the 0o600 file when the
+            // keyring is unavailable; returns Err only when both backends fail.
+            let store =
+                crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
+            crate::app_state::persist_imported_identity(store, keys, &key_path, &data_dir)
+        })?;
 
         let pubkey_hex = pubkey.to_hex();
         let display_name = truncated_display_name(&pubkey)?;
@@ -249,6 +377,7 @@ pub async fn import_identity(
         Ok(IdentityInfo {
             pubkey: pubkey_hex,
             display_name,
+            storage: storage.as_str().to_string(),
             lost: false,
             locked: false,
             reset_failed: false,
@@ -258,6 +387,69 @@ pub async fn import_identity(
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
 }
 
+/// Commit an imported identity: durably persist, swap in-memory keys, clear
+/// recovery flags, then remove the previous identity's stale app-managed
+/// backup. Caller must hold `state.identity_mutation`.
+///
+/// Ordering is the contract:
+///
+/// 1. `persist` runs FIRST. If it fails (`Err` from both keyring and file
+///    fallback), nothing has changed — the previous identity stays live in
+///    memory AND its valid canonical `identity.ncryptsec` stays on disk.
+/// 2. Only after durable persistence do we swap `state.keys` and clear the
+///    recovery flags.
+/// 3. Stale-backup cleanup runs LAST and is deliberately best-effort: at that
+///    point the import is durably committed, so reporting a cleanup failure
+///    as a command `Err` would claim a half-applied import that actually
+///    succeeded. The leftover blob is still passphrase-encrypted and is
+///    replaced by the next backup creation; we log and move on.
+fn commit_imported_identity(
+    state: &AppState,
+    data_dir: &std::path::Path,
+    keys: nostr::Keys,
+    persist: impl FnOnce(&nostr::Keys) -> Result<crate::app_state::IdentityStorage, String>,
+) -> Result<(nostr::PublicKey, crate::app_state::IdentityStorage), String> {
+    // Capture the previous pubkey up front for post-commit cleanup.
+    let previous_pubkey = state.keys.lock().map_err(|e| e.to_string())?.public_key();
+
+    let storage = persist(&keys)?;
+
+    // Update in-memory keys BEFORE clearing recovery flags. The Release
+    // stores below pair with Acquire loads in get_identity: a reader
+    // observing false is guaranteed to see the updated keys.
+    let pubkey = keys.public_key();
+    {
+        let mut active_keys = state.keys.lock().map_err(|e| e.to_string())?;
+        *active_keys = keys;
+        state.set_identity_storage(storage);
+    }
+
+    // Clear both recovery flags — an import is valid in either lost or
+    // keyring-locked state and resolves both. In the locked case the
+    // keyring is unreachable, so the persist step already fell back to
+    // identity.key; on the next Unreachable boot the file is loaded
+    // directly and when the keyring returns the adoption path picks it up.
+    state
+        .identity_lost
+        .store(false, std::sync::atomic::Ordering::Release);
+    state
+        .keyring_locked
+        .store(false, std::sync::atomic::Ordering::Release);
+
+    // Importing a different identity invalidates the app-managed backup: it
+    // encrypts the previous key and must not linger mislabeled. Best-effort
+    // per the ordering contract above.
+    if let Err(e) = crate::key_backup::cleanup_stale_backup(&previous_pubkey, &pubkey, data_dir) {
+        eprintln!(
+            "buzz-desktop: import committed, but stale key backup cleanup failed: {e}; \
+             the leftover identity.ncryptsec encrypts the PREVIOUS key and will be \
+             replaced by the next backup creation"
+        );
+    }
+
+    Ok((pubkey, storage))
+}
+
 /// Make the current ephemeral identity durable by persisting it to the OS
 /// keyring (or falling back to identity.key). This is called when the user
 /// chooses to start a new identity instead of re-importing their previous one
@@ -301,11 +493,12 @@ pub async fn persist_current_identity(
         let key_path = data_dir.join("identity.key");
 
         let store = crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
-        crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
+        let storage =
+            crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
 
-        // Keys are already the live identity — only clear identity_lost.
-        // Release pairs with Acquire in get_identity so readers see
-        // consistent state.
+        // Keys are already the live identity. Record where the durable write
+        // landed before clearing identity_lost.
+        state.set_identity_storage(storage);
         state
             .identity_lost
             .store(false, std::sync::atomic::Ordering::Release);
@@ -317,6 +510,7 @@ pub async fn persist_current_identity(
         Ok(IdentityInfo {
             pubkey: pubkey_hex,
             display_name,
+            storage: storage.as_str().to_string(),
             lost: false,
             locked: false,
             reset_failed: false,
@@ -589,3 +783,7 @@ mod nostr_identity_binding_tests {
         assert_eq!(error, "expires_at is expired");
     }
 }
+
+#[cfg(test)]
+#[path = "identity_key_backup_tests.rs"]
+mod identity_key_backup_tests;
diff --git a/desktop/src-tauri/src/commands/identity_key_backup_tests.rs b/desktop/src-tauri/src/commands/identity_key_backup_tests.rs
new file mode 100644
index 0000000000..c36af66879
--- /dev/null
+++ b/desktop/src-tauri/src/commands/identity_key_backup_tests.rs
@@ -0,0 +1,139 @@
+use super::{create_backup_with_log_n, verify_ncryptsec_backup_inner};
+use crate::app_state::build_app_state;
+use nostr::{Keys, ToBech32};
+
+/// Fast scrypt tier for tests; production uses BACKUP_LOG_N (18), covered
+/// once in key_backup_tests::round_trip_at_production_cost.
+const FAST_LOG_N: u8 = 16;
+const PASSWORD: &str = "correct horse battery";
+
+#[test]
+fn verification_returns_only_public_identity_and_match_status() {
+    let state = build_app_state();
+    let backup = create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).unwrap();
+    let result = verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+    assert_eq!(
+        result.pubkey,
+        state.keys.lock().unwrap().public_key().to_hex()
+    );
+    assert!(result.npub.starts_with("npub1"));
+    assert!(result.matches_current_identity);
+}
+
+#[test]
+fn verification_reports_valid_backup_for_a_different_identity() {
+    let state = build_app_state();
+    let other = Keys::generate();
+    let backup = crate::key_backup::create_backup_blob(&other, PASSWORD, FAST_LOG_N).unwrap();
+    let result = verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+    assert_eq!(result.pubkey, other.public_key().to_hex());
+    assert!(!result.matches_current_identity);
+}
+
+#[test]
+fn verification_rejects_wrong_password() {
+    let state = build_app_state();
+    let backup =
+        crate::key_backup::create_backup_blob(&Keys::generate(), PASSWORD, FAST_LOG_N).unwrap();
+    assert_eq!(
+        verify_ncryptsec_backup_inner(&state, &backup, "wrong password").unwrap_err(),
+        "wrong backup password or damaged key backup"
+    );
+}
+
+#[test]
+fn verification_accepts_maximum_supported_kdf_cost() {
+    let state = build_app_state();
+    let backup = crate::key_backup::create_backup_blob(
+        &Keys::generate(),
+        PASSWORD,
+        crate::key_backup::MAX_VERIFY_LOG_N,
+    )
+    .unwrap();
+    verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+}
+
+#[test]
+fn verification_rejects_unsupported_kdf_cost_before_decryption() {
+    let state = build_app_state();
+    let supported =
+        crate::key_backup::create_backup_blob(&Keys::generate(), PASSWORD, FAST_LOG_N).unwrap();
+    let encrypted = crate::key_backup::parse_ncryptsec(&supported).unwrap();
+    let mut payload = encrypted.as_vec();
+    payload[1] = crate::key_backup::MAX_VERIFY_LOG_N + 1;
+    let unsupported = nostr::nips::nip49::EncryptedSecretKey::from_slice(&payload)
+        .unwrap()
+        .to_bech32()
+        .unwrap();
+
+    let err = verify_ncryptsec_backup_inner(&state, &unsupported, PASSWORD).unwrap_err();
+    assert_eq!(
+        err,
+        format!(
+            "unsupported backup KDF cost: log_n {} exceeds maximum {}",
+            crate::key_backup::MAX_VERIFY_LOG_N + 1,
+            crate::key_backup::MAX_VERIFY_LOG_N
+        )
+    );
+}
+
+#[test]
+fn rejects_short_passphrase() {
+    let state = build_app_state();
+    let err = create_backup_with_log_n(&state, "short", FAST_LOG_N).unwrap_err();
+    assert!(err.contains("at least"), "{err}");
+}
+
+#[test]
+fn recovery_mode_blocks_backup_creation() {
+    let state = build_app_state();
+
+    state
+        .identity_lost
+        .store(true, std::sync::atomic::Ordering::Release);
+    assert!(
+        create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).is_err(),
+        "lost identity must not be backed up"
+    );
+    state
+        .identity_lost
+        .store(false, std::sync::atomic::Ordering::Release);
+
+    state
+        .keyring_locked
+        .store(true, std::sync::atomic::Ordering::Release);
+    assert!(
+        create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).is_err(),
+        "locked keyring must not be backed up"
+    );
+}
+
+/// Concurrent identity changes serialize with backup creation.
+#[test]
+fn concurrent_identity_swap_vs_backup_is_serialized() {
+    let state = std::sync::Arc::new(build_app_state());
+    let key_a = state.keys.lock().unwrap().clone();
+    let key_b = Keys::generate();
+
+    let swapper = {
+        let state = state.clone();
+        let key_b = key_b.clone();
+        std::thread::spawn(move || {
+            // Mirrors import_identity's locking: mutation guard held
+            // across the key swap.
+            let _guard = state.identity_mutation.lock().unwrap();
+            *state.keys.lock().unwrap() = key_b;
+        })
+    };
+
+    let backup = create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).unwrap();
+    swapper.join().unwrap();
+
+    let recovered = crate::key_backup::decrypt_ncryptsec(&backup, PASSWORD)
+        .unwrap()
+        .public_key();
+    assert!(
+        recovered == key_a.public_key() || recovered == key_b.public_key(),
+        "backup must match one coherent identity"
+    );
+}
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/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/personas/card.rs b/desktop/src-tauri/src/commands/personas/card.rs
new file mode 100644
index 0000000000..c516db1736
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card.rs
@@ -0,0 +1,972 @@
+//! `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())
+}
+
+/// 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 whether an OpenAI key would resolve for a card mint of agent `id`,
+/// using exactly the same env layering as `mint_agent_card`. Lets the mint
+/// dialog offer inline key setup BEFORE the user commits to a mint, instead
+/// of failing after the fact. Never returns the key itself.
+#[tauri::command]
+pub fn card_mint_key_status(
+    id: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<bool, 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_env_from_layers(
+        "OPENAI_API_KEY",
+        &global.env_vars,
+        &persona_env,
+        &record.env_vars,
+        std::env::var("OPENAI_API_KEY").ok(),
+    )
+    .is_some())
+}
+
+/// 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..ca69c43866
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card/tests.rs
@@ -0,0 +1,324 @@
+//! 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());
+}
+
+#[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/pending.rs b/desktop/src-tauri/src/commands/personas/pending.rs
index a4003329bc..cab5fababc 100644
--- a/desktop/src-tauri/src/commands/personas/pending.rs
+++ b/desktop/src-tauri/src/commands/personas/pending.rs
@@ -75,11 +75,11 @@ pub(super) fn prepare_persona_publication(
 }
 
 fn retained_persona_is_shared(row: Option<&RetainedEvent>) -> bool {
-    use buzz_core_pkg::kind::persona_event_is_shared;
+    use buzz_core_pkg::kind::event_is_shared;
     use nostr::JsonUtil;
 
     row.and_then(|retained| nostr::Event::from_json(&retained.raw_event).ok())
-        .is_some_and(|event| persona_event_is_shared(&event))
+        .is_some_and(|event| event_is_shared(&event))
 }
 
 /// Project each persona's catalog visibility from the active relay+owner
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 d23efe7730..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() {
@@ -685,7 +800,7 @@ fn retain_agent_pending(app: &AppHandle, state: &AppState, record: &ManagedAgent
 
 /// POST a pre-built signed engram event to the relay, authenticating as the
 /// new agent.
-async fn submit_engram_event(
+pub(crate) async fn submit_engram_event(
     state: &AppState,
     agent_keys: &nostr::Keys,
     event_json: &[u8],
@@ -695,6 +810,8 @@ async fn submit_engram_event(
     use crate::relay::build_nip98_auth_header_for_keys;
     use reqwest::Method;
 
+    crate::egress_guard::assert_no_key_backup_bytes(event_json, "persona snapshot engram submit")?;
+
     // Wait before signing: the relay enforces NIP-98 freshness (±60s) and the
     // gate may hold for up to MAX_HINT_SECONDS (300s). Building auth before the
     // wait produces a stale `created_at` that the relay will reject.
@@ -739,6 +856,35 @@ async fn submit_engram_event(
     Ok(())
 }
 
+// ── NIP-49 egress guard: boundary 7 (persona snapshot engram submit) ─────────
+
+#[cfg(test)]
+mod egress_guard_tests {
+    use super::submit_engram_event;
+
+    const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+    /// An engram body carrying an ncryptsec must be rejected by the guard
+    /// before any network I/O (the target port is a discard address; a guard
+    /// error — not a connection error — proves the abort ordering).
+    #[tokio::test]
+    async fn blocks_ncryptsec_before_network() {
+        let state = crate::app_state::build_app_state();
+        let keys = nostr::Keys::generate();
+        let body = format!("{{\"content\":\"{NCRYPTSEC}\"}}");
+        let err = submit_engram_event(
+            &state,
+            &keys,
+            body.as_bytes(),
+            "http://127.0.0.1:9/events",
+            None,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.contains("key-backup material"), "{err}");
+    }
+}
+
 #[cfg(test)]
 mod import_avatar_tests {
     use super::materialize_import_avatar;
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/team_snapshot.rs b/desktop/src-tauri/src/commands/team_snapshot.rs
index 91a0126f58..97cd11933d 100644
--- a/desktop/src-tauri/src/commands/team_snapshot.rs
+++ b/desktop/src-tauri/src/commands/team_snapshot.rs
@@ -895,7 +895,7 @@ fn retain_agent_pending(app: &AppHandle, state: &AppState, record: &ManagedAgent
 
 /// POST a pre-built signed engram event to the relay, authenticating as the
 /// new agent. Mirrors the same helper in `snapshot::import`.
-async fn submit_engram_event(
+pub(crate) async fn submit_engram_event(
     state: &AppState,
     agent_keys: &nostr::Keys,
     event_json: &[u8],
@@ -905,6 +905,8 @@ async fn submit_engram_event(
     use crate::relay::build_nip98_auth_header_for_keys;
     use reqwest::Method;
 
+    crate::egress_guard::assert_no_key_backup_bytes(event_json, "team snapshot engram submit")?;
+
     // Wait before signing: the relay enforces NIP-98 freshness (±60s) and the
     // gate may hold for up to MAX_HINT_SECONDS (300s). Building auth before the
     // wait produces a stale `created_at` that the relay will reject.
diff --git a/desktop/src-tauri/src/commands/team_snapshot/tests.rs b/desktop/src-tauri/src/commands/team_snapshot/tests.rs
index 0616411307..c9a6d8812a 100644
--- a/desktop/src-tauri/src/commands/team_snapshot/tests.rs
+++ b/desktop/src-tauri/src/commands/team_snapshot/tests.rs
@@ -733,3 +733,31 @@ fn full_rollback_at_teams_boundary_absent_agents_store() {
     assert!(!teams_path.exists());
     assert_eq!(errors.len(), 1, "only the teams-write error");
 }
+
+// ── NIP-49 egress guard: boundary 6 (team snapshot engram submit) ────────────
+
+mod egress_guard_boundary {
+    use super::super::submit_engram_event;
+
+    const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+    /// An engram body carrying an ncryptsec must be rejected by the guard
+    /// before any network I/O (the target port is a discard address; a guard
+    /// error — not a connection error — proves the abort ordering).
+    #[tokio::test]
+    async fn blocks_ncryptsec_before_network() {
+        let state = crate::app_state::build_app_state();
+        let keys = nostr::Keys::generate();
+        let body = format!("{{\"content\":\"{NCRYPTSEC}\"}}");
+        let err = submit_engram_event(
+            &state,
+            &keys,
+            body.as_bytes(),
+            "http://127.0.0.1:9/events",
+            None,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.contains("key-backup material"), "{err}");
+    }
+}
diff --git a/desktop/src-tauri/src/egress_guard.rs b/desktop/src-tauri/src/egress_guard.rs
new file mode 100644
index 0000000000..db58ddafa0
--- /dev/null
+++ b/desktop/src-tauri/src/egress_guard.rs
@@ -0,0 +1,58 @@
+//! Relay egress guard for NIP-49 key-backup material.
+//!
+//! The local `ncryptsec` backup (see [`crate::key_backup`]) must NEVER be
+//! transmitted to a relay. This module enforces that contract at runtime,
+//! fail-closed, at every relay-bound egress boundary:
+//!
+//! | # | Boundary | Site |
+//! |---|----------|------|
+//! | 1 | `submit_signed_event_at_with_keys` (funnel for `submit_event*`) | `relay/submit.rs` |
+//! | 2 | `sync_managed_agent_profile` | `relay.rs` |
+//! | 3 | pre-signed path into the boundary-1 funnel | `relay/submit.rs` |
+//! | 4 | `submit_signed_event_with_keys` | `relay.rs` |
+//! | 5 | huddle STT publisher | `huddle/pipeline.rs` |
+//! | 6 | `submit_engram_event` (team snapshot) | `commands/team_snapshot.rs` |
+//! | 7 | `submit_engram_event` (persona import) | `commands/personas/snapshot/import.rs` |
+//! | 8 | native websocket send loop (all webview relay WS) | `native_websocket.rs` |
+//!
+//! The inventory-completeness test in `egress_guard_tests.rs` asserts that
+//! every `/events` URL-construction site in the tree calls this guard, so a
+//! new submission path fails the build until it is wired.
+//!
+//! Scope: `ncryptsec1` only. The raw `nsec` intentionally transits the
+//! NIP-44-encrypted pairing session (NIP-AB payload_type "nsec"); guarding it
+//! here would break pairing. Raw-key DLP is separate policy work.
+
+/// Bech32 HRP of NIP-49 encrypted secret keys.
+const NCRYPTSEC_PREFIX: &str = "ncryptsec1";
+/// Bech32 also permits an ALL-UPPERCASE encoding of the same payload
+/// (BIP-173); an uppercased valid backup decodes identically, so the guard
+/// must reject it too. Mixed case is invalid bech32 and cannot decode — a
+/// substring matching either all-lower or all-upper prefix covers every
+/// decodable form.
+const NCRYPTSEC_PREFIX_UPPER: &str = "NCRYPTSEC1";
+
+/// Reject `text` if it contains NIP-49 key-backup material.
+///
+/// Returns `Err` when an `ncryptsec1…` (or uppercase `NCRYPTSEC1…`)
+/// substring is present. Callers MUST abort the network operation on `Err` —
+/// this is a fail-closed guard, not a warning.
+pub fn assert_no_key_backup(text: &str, context: &'static str) -> Result<(), String> {
+    if text.contains(NCRYPTSEC_PREFIX) || text.contains(NCRYPTSEC_PREFIX_UPPER) {
+        return Err(format!(
+            "blocked {context}: payload contains NIP-49 key-backup material \
+             (ncryptsec); the local key backup must never be transmitted to a relay"
+        ));
+    }
+    Ok(())
+}
+
+/// Byte-slice variant for callers that hold serialized bodies.
+pub fn assert_no_key_backup_bytes(body: &[u8], context: &'static str) -> Result<(), String> {
+    // ncryptsec is ASCII bech32; a UTF-8-lossy view preserves any occurrence.
+    assert_no_key_backup(&String::from_utf8_lossy(body), context)
+}
+
+#[cfg(test)]
+#[path = "egress_guard_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/egress_guard_tests.rs b/desktop/src-tauri/src/egress_guard_tests.rs
new file mode 100644
index 0000000000..f487c8ce16
--- /dev/null
+++ b/desktop/src-tauri/src/egress_guard_tests.rs
@@ -0,0 +1,446 @@
+use super::*;
+
+/// NIP-49 spec vector — a real ncryptsec blob for injection payloads.
+const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+fn assert_guard_error(err: &str) {
+    assert!(
+        err.contains("key-backup material"),
+        "expected the egress-guard error, got: {err}"
+    );
+}
+
+// ── Guard unit behavior ───────────────────────────────────────────────────────
+
+#[test]
+fn rejects_ncryptsec_anywhere_in_text() {
+    assert_guard_error(&assert_no_key_backup(NCRYPTSEC, "test").unwrap_err());
+    assert_guard_error(
+        &assert_no_key_backup(
+            &format!("{{\"content\":\"my backup: {NCRYPTSEC}\"}}"),
+            "test",
+        )
+        .unwrap_err(),
+    );
+}
+
+/// Bech32 permits an all-uppercase encoding of the same payload — an
+/// uppercased valid backup must not bypass the guard (text and bytes).
+/// Mixed case is invalid bech32 (cannot decode) and is deliberately not
+/// blocked.
+#[test]
+fn rejects_uppercase_ncryptsec() {
+    let upper = NCRYPTSEC.to_ascii_uppercase();
+    assert_guard_error(&assert_no_key_backup(&upper, "test").unwrap_err());
+    assert_guard_error(&assert_no_key_backup_bytes(upper.as_bytes(), "test").unwrap_err());
+    // Mixed case cannot decode; not blocked.
+    assert!(assert_no_key_backup("nCrYpTsEc1qgg9947r", "test").is_ok());
+}
+
+#[test]
+fn passes_clean_payloads_including_raw_nsec() {
+    assert!(assert_no_key_backup("hello world", "test").is_ok());
+    assert!(assert_no_key_backup("", "test").is_ok());
+    // Scope is ncryptsec1 ONLY: raw nsec intentionally transits the encrypted
+    // pairing session and must NOT be blocked (plan D4 / pairing.rs).
+    let nsec = nostr::ToBech32::to_bech32(nostr::Keys::generate().secret_key()).unwrap();
+    assert!(assert_no_key_backup(&nsec, "test").is_ok());
+    // Near-miss prefixes are not blocked.
+    assert!(assert_no_key_backup("ncryptsec", "test").is_ok());
+}
+
+#[test]
+fn byte_variant_matches_text_variant() {
+    assert_guard_error(&assert_no_key_backup_bytes(NCRYPTSEC.as_bytes(), "test").unwrap_err());
+    assert!(assert_no_key_backup_bytes(b"clean body", "test").is_ok());
+    // Invalid UTF-8 around an intact ncryptsec substring must still trip the
+    // guard (from_utf8_lossy preserves the ASCII run).
+    let mut body = vec![0xff, 0xfe];
+    body.extend_from_slice(NCRYPTSEC.as_bytes());
+    body.push(0xff);
+    assert_guard_error(&assert_no_key_backup_bytes(&body, "test").unwrap_err());
+}
+
+#[test]
+fn error_names_the_boundary_context() {
+    let err = assert_no_key_backup(NCRYPTSEC, "huddle STT publish").unwrap_err();
+    assert!(err.contains("huddle STT publish"), "{err}");
+}
+
+// ── Runtime injection per boundary ────────────────────────────────────────────
+//
+// Each test drives the real production function with an ncryptsec-bearing
+// payload and asserts the guard aborts the operation before any network I/O
+// (no listener exists at the target address; a distinctive guard error — not
+// a connection error — proves the abort happened first).
+//
+// Boundaries 6 and 7 (`submit_engram_event` twins) are module-private inside
+// `commands`; their injection tests live next to them:
+//   - commands/team_snapshot/tests.rs::egress_guard_boundary
+//   - commands/personas/snapshot/import.rs::egress_guard_tests
+
+/// Boundary 1: `relay/submit.rs` `submit_event_at_with_keys` (the funnel for
+/// all `submit_event*` variants).
+#[tokio::test]
+async fn boundary_submit_event_at_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let builder = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC);
+    let err = crate::relay::submit_event_at_with_keys(
+        builder,
+        &state,
+        "http://127.0.0.1:9", // discard port — must never be reached
+        &keys,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 2: `relay.rs` `sync_managed_agent_profile` (agent kind:0 profile).
+#[tokio::test]
+async fn boundary_sync_managed_agent_profile_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let err = crate::relay::sync_managed_agent_profile(
+        &state,
+        "ws://127.0.0.1:9",
+        &keys,
+        &format!("agent {NCRYPTSEC}"),
+        None,
+        None,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 3: `relay/submit.rs` `submit_signed_event_at_with_keys` — the
+/// pre-signed entry into the boundary-1 funnel (main's submit refactor
+/// replaced `relay.rs` `submit_signed_event` with this scoped form).
+#[tokio::test]
+async fn boundary_submit_signed_event_at_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let event = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC)
+        .sign_with_keys(&keys)
+        .unwrap();
+    let err = crate::relay::submit_signed_event_at_with_keys(
+        &event,
+        &state,
+        "http://127.0.0.1:9", // discard port — must never be reached
+        &keys,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 4: `relay.rs` `submit_signed_event_with_keys`.
+#[tokio::test]
+async fn boundary_submit_signed_event_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    *state.relay_url_override.lock().unwrap() = Some("ws://127.0.0.1:9".to_string());
+    let keys = nostr::Keys::generate();
+    let event = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC)
+        .sign_with_keys(&keys)
+        .unwrap();
+    let err = crate::relay::submit_signed_event_with_keys(&event, &state, &keys, None)
+        .await
+        .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 5: huddle STT publisher (`huddle/pipeline.rs`).
+#[test]
+fn boundary_huddle_stt_blocks_ncryptsec() {
+    let keys = nostr::Keys::generate();
+    let channel = uuid::Uuid::new_v4();
+    let builder =
+        crate::events::build_message(channel, NCRYPTSEC, None, &[], &[], &[], &[]).unwrap();
+    let err = crate::huddle::pipeline::sign_and_guard_stt_body(builder, &keys).unwrap_err();
+    assert_guard_error(&err);
+
+    // Clean transcripts pass through the same seam.
+    let builder =
+        crate::events::build_message(channel, "hello huddle", None, &[], &[], &[], &[]).unwrap();
+    assert!(crate::huddle::pipeline::sign_and_guard_stt_body(builder, &keys).is_ok());
+}
+
+/// Boundary 8: native websocket send loop — the single choke point for all
+/// webview-originated relay websocket frames.
+#[tokio::test]
+async fn boundary_native_websocket_blocks_ncryptsec() {
+    let manager = crate::native_websocket::WebSocketManager::default();
+    // Text frame: guard fires before the connection lookup, so no connection
+    // is needed — and the error must be the guard's, not "not found".
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Text(format!(
+            "[\"EVENT\",{{\"content\":\"{NCRYPTSEC}\"}}]"
+        )),
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+
+    // Binary frame variant.
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Binary(NCRYPTSEC.as_bytes().to_vec()),
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+
+    // Clean frames fall through to normal handling ("connection not found"
+    // here — the guard did not reject them).
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Text("[\"REQ\",\"sub\",{}]".to_string()),
+    )
+    .await
+    .unwrap_err();
+    assert!(err.contains("not found"), "{err}");
+}
+
+// ── Structural tripwires ──────────────────────────────────────────────────────
+
+fn src_rust_files() -> Vec<std::path::PathBuf> {
+    fn walk(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
+        for entry in std::fs::read_dir(dir).unwrap() {
+            let path = entry.unwrap().path();
+            if path.is_dir() {
+                walk(&path, out);
+            } else if path.extension().and_then(|e| e.to_str()) == Some("rs") {
+                out.push(path);
+            }
+        }
+    }
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+    let mut out = Vec::new();
+    walk(&root, &mut out);
+    out
+}
+
+/// Site-granular `/events` inventory: `(file suffix, expected non-comment
+/// `/events` occurrences, expected guard call sites — full-path calls into
+/// the egress-guard module)`.
+///
+/// Every entry pairs the URL-construction count with the guard-call count for
+/// that file, so BOTH of these fail the scan (not just a brand-new file):
+///   - adding an unguarded ninth `/events` site inside an already-listed file
+///     (count goes up without a matching table update), and
+///   - removing/refactoring away a guard call while its egress site remains.
+///
+/// Updating a row here is the deliberate act that must accompany wiring the
+/// guard + adding an injection test for the new site.
+const EVENTS_INVENTORY: &[(&str, usize, usize)] = &[
+    // Production egress boundaries (see egress_guard.rs table):
+    ("src/relay.rs", 2, 2),                             // boundaries 2, 4
+    ("src/relay/submit.rs", 1, 1),                      // boundaries 1 + 3 (shared funnel)
+    ("src/huddle/pipeline.rs", 1, 1),                   // boundary 5
+    ("src/commands/team_snapshot.rs", 1, 1),            // boundary 6
+    ("src/commands/personas/snapshot/import.rs", 2, 1), // boundary 7 + its in-file injection-test fixture URL
+    ("src/native_websocket.rs", 0, 2),                  // boundary 8 (WS frames; no events URL)
+    // Test-only fixtures — no production egress, no guard:
+    ("src/relay_admission.rs", 1, 0),
+    ("src/archive/mod_tests.rs", 1, 0),
+    ("src/managed_agents/persona_events/tests.rs", 1, 0),
+    ("src/commands/team_snapshot/tests.rs", 1, 0),
+    // Mock-relay route in its in-file tests; production publish goes through
+    // the guarded boundary-1 funnel (`submit_signed_event_at_with_keys`).
+    ("src/commands/personas/sharing.rs", 1, 0),
+];
+
+// Needles are assembled at runtime so this scan file itself contains no
+// contiguous match and needs no self-referential inventory row.
+fn events_needle() -> String {
+    ["/ev", "ents"].concat()
+}
+fn guard_needle() -> String {
+    ["egress_guard::", "assert_no_key_backup"].concat()
+}
+
+/// Pure scan core over `(relative path, content)` pairs. Returns violations;
+/// empty means every file matches its inventory row exactly (files absent
+/// from the table are expected to have zero `/events` sites and zero guard
+/// calls).
+fn events_inventory_violations(files: &[(String, String)]) -> Vec<String> {
+    let events = events_needle();
+    let guard = guard_needle();
+    let mut violations = Vec::new();
+
+    for (rel, content) in files {
+        let expected = EVENTS_INVENTORY
+            .iter()
+            .find(|(suffix, _, _)| rel.ends_with(suffix))
+            .map(|&(_, e, g)| (e, g))
+            .unwrap_or((0, 0));
+
+        let mut event_sites = Vec::new();
+        for (i, line) in content.lines().enumerate() {
+            if line.trim_start().starts_with("//") {
+                continue; // doc/comment mentions
+            }
+            if line.contains(&events) {
+                event_sites.push(format!("  {rel}:{}: {}", i + 1, line.trim()));
+            }
+        }
+        let guard_count = content.matches(&guard).count();
+
+        if (event_sites.len(), guard_count) != expected {
+            violations.push(format!(
+                "{rel}: found {} events-URL site(s) + {} guard call(s), inventory \
+                 expects {} + {}. Sites found:\n{}",
+                event_sites.len(),
+                guard_count,
+                expected.0,
+                expected.1,
+                if event_sites.is_empty() {
+                    "  (none)".to_string()
+                } else {
+                    event_sites.join("\n")
+                },
+            ));
+        }
+    }
+    violations
+}
+
+fn read_src_files() -> Vec<(String, String)> {
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    src_rust_files()
+        .into_iter()
+        .map(|path| {
+            let rel = path
+                .strip_prefix(root)
+                .unwrap()
+                .to_string_lossy()
+                .replace('\\', "/");
+            let content = std::fs::read_to_string(&path).unwrap();
+            (rel, content)
+        })
+        .collect()
+}
+
+/// Inventory completeness: every `/events` URL-construction site in
+/// `desktop/src-tauri/src` must match the site-granular inventory above. A
+/// future ninth submission path — in a NEW file or an ALREADY-LISTED one —
+/// fails this test until its guard is wired, its injection test exists, and
+/// its inventory row is updated.
+#[test]
+fn events_url_inventory_is_fully_guarded() {
+    let violations = events_inventory_violations(&read_src_files());
+    assert!(
+        violations.is_empty(),
+        "events-URL egress inventory drift — wire crate::egress_guard, add an \
+         injection test, then update EVENTS_INVENTORY:\n{}",
+        violations.join("\n")
+    );
+}
+
+/// Mutation-style proof of the tripwire's guarantee: an unguarded ninth
+/// `/events` site added to an already-inventoried file (relay.rs) is caught.
+#[test]
+fn inventory_scan_catches_new_site_in_allowlisted_file() {
+    let mut files = read_src_files();
+    let relay = files
+        .iter_mut()
+        .find(|(rel, _)| rel.ends_with("src/relay.rs"))
+        .expect("relay.rs must be in the scan set");
+    relay.1.push_str(&format!(
+        "\nfn sneaky_ninth_site(base: &str) -> String {{ format!(\"{{base}}{}\") }}\n",
+        events_needle()
+    ));
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations.iter().any(|v| v.contains("src/relay.rs")),
+        "an unguarded ninth events-URL site in relay.rs must trip the scan: {violations:?}"
+    );
+}
+
+/// The pairing also fires in reverse: a guard call deleted while its egress
+/// site remains is caught.
+#[test]
+fn inventory_scan_catches_removed_guard_call() {
+    let mut files = read_src_files();
+    let relay = files
+        .iter_mut()
+        .find(|(rel, _)| rel.ends_with("src/relay.rs"))
+        .expect("relay.rs must be in the scan set");
+    relay.1 = relay.1.replacen(&guard_needle(), "removed_guard", 1);
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations.iter().any(|v| v.contains("src/relay.rs")),
+        "a removed guard call in relay.rs must trip the scan: {violations:?}"
+    );
+}
+
+/// A brand-new file with an `/events` site (no inventory row) is caught.
+#[test]
+fn inventory_scan_catches_new_unlisted_file() {
+    let mut files = read_src_files();
+    files.push((
+        "src/brand_new_egress.rs".to_string(),
+        format!("let url = format!(\"{{}}{}\", base);", events_needle()),
+    ));
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations
+            .iter()
+            .any(|v| v.contains("src/brand_new_egress.rs")),
+        "{violations:?}"
+    );
+}
+
+/// Source allowlist: NIP-49 material handling is confined to the identity /
+/// backup / import / guard files. Anything else touching ncryptsec or the
+/// nip49 codec is structural drift.
+#[test]
+fn ncryptsec_handling_is_confined_to_allowlisted_files() {
+    let allowlist: &[&str] = &[
+        "src/key_backup.rs",
+        "src/key_backup_tests.rs",
+        "src/egress_guard.rs",
+        "src/egress_guard_tests.rs",
+        "src/commands/identity.rs",
+        "src/commands/identity_key_backup_tests.rs",
+        "src/lib.rs", // module registration + invoke handler
+        // boundary wiring (guard call sites name the module, not the codec):
+        "src/relay.rs",
+        "src/relay/submit.rs",
+        "src/huddle/pipeline.rs",
+        "src/commands/team_snapshot.rs",
+        "src/commands/team_snapshot/tests.rs",
+        "src/commands/personas/snapshot/import.rs",
+        "src/native_websocket.rs",
+    ];
+
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let mut violations = Vec::new();
+    for path in src_rust_files() {
+        let rel = path
+            .strip_prefix(root)
+            .unwrap()
+            .to_string_lossy()
+            .replace('\\', "/");
+        if allowlist.iter().any(|a| rel.ends_with(a)) {
+            continue;
+        }
+        let content = std::fs::read_to_string(&path).unwrap();
+        for needle in ["ncryptsec", "EncryptedSecretKey", "nip49"] {
+            if content.contains(needle) {
+                violations.push(format!("{rel}: contains {needle:?}"));
+            }
+        }
+    }
+    assert!(
+        violations.is_empty(),
+        "NIP-49 material outside allowlisted files:\n{}",
+        violations.join("\n")
+    );
+}
diff --git a/desktop/src-tauri/src/event_sync.rs b/desktop/src-tauri/src/event_sync.rs
index d9fe6acdb9..ee8e0d8b10 100644
--- a/desktop/src-tauri/src/event_sync.rs
+++ b/desktop/src-tauri/src/event_sync.rs
@@ -165,7 +165,7 @@ fn migrate_personas_in_dir_at(
         scoped_record.shared = existing
             .as_ref()
             .and_then(|row| nostr::Event::from_json(&row.raw_event).ok())
-            .is_some_and(|event| buzz_core_pkg::kind::persona_event_is_shared(&event));
+            .is_some_and(|event| buzz_core_pkg::kind::event_is_shared(&event));
         let event = build_persona_event(&scoped_record)
             .map_err(|e| format!("failed to build event for '{}': {e}", record.display_name))?
             .custom_created_at(monotonic_created_at(
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/agents.rs b/desktop/src-tauri/src/huddle/agents.rs
index 02c4045410..2de22f99d8 100644
--- a/desktop/src-tauri/src/huddle/agents.rs
+++ b/desktop/src-tauri/src/huddle/agents.rs
@@ -2,7 +2,8 @@
 //!
 //! Mental model:
 //!   add_agent_to_huddle → kind:9000 to ephemeral channel
-//!                       → kind:9000 to parent channel (best-effort)
+//!                       → preserve existing parent membership, or
+//!                         kind:9000 to parent channel (best-effort)
 //!
 //! ACP spawning is NOT needed here: the running agent process auto-subscribes
 //! when it receives the kind:9000 membership notification. Huddle-specific
@@ -11,7 +12,10 @@
 use serde::Serialize;
 use uuid::Uuid;
 
-use crate::{app_state::AppState, events, relay::submit_event};
+use crate::{
+    app_state::AppState, events, huddle::relay_api::fetch_channel_members_with_roles,
+    relay::submit_event,
+};
 
 // ── Constants ─────────────────────────────────────────────────────────────────
 
@@ -61,8 +65,9 @@ with the next one.
 /// The field exists for forward compatibility with future batch-add operations
 /// where partial success may be meaningful.
 ///
-/// `parent_added` reflects whether the parent-channel add succeeded;
-/// `parent_error` carries the error string when it didn't.
+/// `parent_added` reflects whether the parent already contained the agent or
+/// the parent-channel add succeeded; `parent_error` carries the error string
+/// when neither condition could be confirmed.
 #[derive(Debug, Serialize)]
 pub struct AgentAddResult {
     /// Always `true` — invariant guaranteed by [`add_agent_to_huddle`].
@@ -91,17 +96,33 @@ pub async fn add_agent_to_huddle(
     let add_eph = events::build_add_member(ephemeral_channel_id, agent_pubkey, Some("bot"))?;
     submit_event(add_eph, state).await?;
 
-    // 2. Add agent to parent channel — so agent has full context.
-    //    Best-effort: capture the error but don't propagate it.
-    let (parent_added, parent_error) = {
+    // 2. Preserve any active parent membership, regardless of role. Rewriting
+    //    an existing DM member as `bot` is both unnecessary and forbidden for
+    //    non-admins. Otherwise add the agent so it has full context.
+    //    Best-effort: capture a real error but don't propagate it.
+    let parent_channel_id_string = parent_channel_id.to_string();
+    let parent_already_contains_agent =
+        fetch_channel_members_with_roles(&parent_channel_id_string, state)
+            .await
+            .is_ok_and(|members| contains_member(&members, agent_pubkey));
+
+    let (parent_added, parent_error) = if parent_already_contains_agent {
+        (true, None)
+    } else {
         let add_parent = events::build_add_member(parent_channel_id, agent_pubkey, Some("bot"))?;
         match submit_event(add_parent, state).await {
             Ok(_) => (true, None),
             Err(e) => {
-                eprintln!(
-                    "buzz-desktop: add agent to parent channel failed (may already be member): {e}"
-                );
-                (false, Some(e))
+                let active_after_error =
+                    fetch_channel_members_with_roles(&parent_channel_id_string, state)
+                        .await
+                        .is_ok_and(|members| contains_member(&members, agent_pubkey));
+                if active_after_error {
+                    (true, None)
+                } else {
+                    eprintln!("buzz-desktop: add agent to parent channel failed: {e}");
+                    (false, Some(e))
+                }
             }
         }
     };
@@ -112,3 +133,26 @@ pub async fn add_agent_to_huddle(
         parent_error,
     })
 }
+
+fn contains_member(members: &[(String, Option<String>)], pubkey: &str) -> bool {
+    members
+        .iter()
+        .any(|(member_pubkey, _)| member_pubkey.eq_ignore_ascii_case(pubkey))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::contains_member;
+
+    #[test]
+    fn existing_parent_membership_is_preserved_regardless_of_role() {
+        let members = vec![
+            ("agent-member".to_owned(), Some("member".to_owned())),
+            ("agent-bot".to_owned(), Some("bot".to_owned())),
+        ];
+
+        assert!(contains_member(&members, "AGENT-MEMBER"));
+        assert!(contains_member(&members, "agent-bot"));
+        assert!(!contains_member(&members, "missing"));
+    }
+}
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/mod.rs b/desktop/src-tauri/src/huddle/mod.rs
index a815bf2d06..03264f80f4 100644
--- a/desktop/src-tauri/src/huddle/mod.rs
+++ b/desktop/src-tauri/src/huddle/mod.rs
@@ -23,6 +23,7 @@
 //!    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 agents;
 pub mod audio_output;
 pub mod jitter;
@@ -37,6 +38,9 @@ pub mod state;
 pub mod stt;
 pub mod transcription;
 pub mod tts;
+pub mod tts_settings;
+mod tts_voice_import;
+mod tts_voice_registry;
 pub mod wire;
 
 // ── Shared utilities ──────────────────────────────────────────────────────────
@@ -63,16 +67,25 @@ pub(super) fn drain_until_shutdown<T>(
 
 pub use state::{HuddleJoinInfo, HuddlePhase, HuddleState, VoiceInputMode};
 pub use transcription::{set_huddle_transcription_enabled, start_stt_pipeline};
+pub use tts_settings::set_tts_enabled;
 
 // ── Imports ───────────────────────────────────────────────────────────────────
 
-use std::sync::{atomic::Ordering, Arc};
+use std::sync::atomic::Ordering;
 use tauri::State;
 use uuid::Uuid;
 
 use crate::{app_state::AppState, events, relay::submit_event};
 
-use pipeline::{maybe_start_stt_pipeline, maybe_start_tts_pipeline, post_connect_setup};
+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::{
+    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,
@@ -186,7 +199,7 @@ pub async fn start_huddle(
     };
 
     // Transition to Creating.
-    {
+    let huddle_generation = {
         let mut hs = state.huddle()?;
         if hs.phase != HuddlePhase::Idle {
             return Err(format!(
@@ -194,9 +207,11 @@ pub async fn start_huddle(
                 hs.phase
             ));
         }
+        let generation = hs.begin_huddle_lifetime();
         hs.phase = HuddlePhase::Creating;
         hs.parent_channel_id = Some(parent_channel_id.clone());
-    }
+        generation
+    };
 
     let ephemeral_uuid = Uuid::new_v4();
     let ephemeral_channel_id = ephemeral_uuid.to_string();
@@ -259,27 +274,33 @@ pub async fn start_huddle(
     match result {
         Ok(successful_agents) => {
             // 5. Store active state.
-            {
+            let committed = {
                 let mut hs = state.huddle()?;
-                hs.phase = HuddlePhase::Connected;
-                hs.is_creator = true;
-                hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
-                // Only store agents that were successfully enrolled.
-                *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) =
-                    successful_agents.clone();
-                // Include the current user + successfully enrolled agents as participants.
-                // Use successful_agents (not member_pubkeys) so failed enrollments
-                // are not reflected in the participant list.
-                let own_pubkey = state
-                    .keys
-                    .lock()
-                    .map(|k| k.public_key().to_hex())
-                    .unwrap_or_default();
-                let mut participants = successful_agents.clone();
-                if !own_pubkey.is_empty() && !participants.contains(&own_pubkey) {
-                    participants.insert(0, own_pubkey);
+                if !hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Creating) {
+                    false
+                } else {
+                    hs.phase = HuddlePhase::Connected;
+                    hs.is_creator = true;
+                    hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
+                    *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) =
+                        successful_agents.clone();
+                    hs.maybe_auto_enable_transcription_for_agents();
+                    let own_pubkey = state
+                        .keys
+                        .lock()
+                        .map(|k| k.public_key().to_hex())
+                        .unwrap_or_default();
+                    let mut participants = successful_agents.clone();
+                    if !own_pubkey.is_empty() && !participants.contains(&own_pubkey) {
+                        participants.insert(0, own_pubkey);
+                    }
+                    hs.participants = participants;
+                    true
                 }
-                hs.participants = participants;
+            };
+            if !committed {
+                emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
+                return Err("huddle start was superseded".to_owned());
             }
 
             // 6. Notify frontend of state change.
@@ -287,16 +308,30 @@ pub async fn start_huddle(
 
             // 7. Hydrate members, download models, start pipelines (incl. audio relay).
             // Audio relay failure is fatal — no point in a huddle without audio.
-            if let Err(e) = post_connect_setup(&state, &ephemeral_channel_id).await {
-                // Rollback: audio relay failed after state was committed.
-                // Publish the terminal lifecycle event before archiving so
-                // other clients do not reconstruct a phantom active huddle.
-                emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
-                if let Ok(mut hs) = state.huddle_state.lock() {
-                    hs.reset_preserving_generation();
+            match post_connect_setup(&state, &ephemeral_channel_id, huddle_generation).await {
+                Ok(PostConnectOutcome::Ready) => {}
+                Ok(PostConnectOutcome::Stale) => {
+                    return Err("huddle start was superseded".to_owned());
+                }
+                Err(e) => {
+                    // Roll back only if this failed setup still owns the active
+                    // huddle. A stale failure must not tear down its replacement.
+                    let still_current = state
+                        .huddle()
+                        .map(|hs| hs.is_current_huddle(&ephemeral_channel_id, huddle_generation))
+                        .unwrap_or(false);
+                    if still_current {
+                        emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state)
+                            .await;
+                        if let Ok(mut hs) = state.huddle_state.lock() {
+                            if hs.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+                                hs.reset_preserving_generation();
+                            }
+                        }
+                        state.emit_huddle_state_changed();
+                    }
+                    return Err(e);
                 }
-                state.emit_huddle_state_changed();
-                return Err(e);
             }
 
             Ok(HuddleJoinInfo {
@@ -314,11 +349,11 @@ pub async fn start_huddle(
                     }
                 }
             }
-            // Reset state to Idle so the user can retry.
-            // Preserve session_generation so in-flight transcription tasks
-            // from a prior session still see a stale generation and exit.
+            // Reset only if this failed attempt still owns the Creating state.
             if let Ok(mut hs) = state.huddle_state.lock() {
-                hs.reset_preserving_generation();
+                if hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Creating) {
+                    hs.reset_preserving_generation();
+                }
             }
             Err(e)
         }
@@ -340,7 +375,7 @@ pub async fn join_huddle(
     state: State<'_, AppState>,
 ) -> Result<HuddleJoinInfo, String> {
     // Transition to Connecting.
-    {
+    let huddle_generation = {
         let mut hs = state.huddle()?;
         if hs.phase != HuddlePhase::Idle {
             return Err(format!(
@@ -348,10 +383,12 @@ pub async fn join_huddle(
                 hs.phase
             ));
         }
+        let generation = hs.begin_huddle_lifetime();
         hs.phase = HuddlePhase::Connecting;
         hs.parent_channel_id = Some(parent_channel_id.clone());
         hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
-    }
+        generation
+    };
 
     // Seed participant list with own pubkey as a fallback until relay responds.
     let own_pubkey = state
@@ -360,12 +397,20 @@ pub async fn join_huddle(
         .map(|k| k.public_key().to_hex())
         .unwrap_or_default();
 
-    {
+    let committed = {
         let mut hs = state.huddle()?;
-        hs.phase = HuddlePhase::Connected;
-        if !own_pubkey.is_empty() {
-            hs.participants = vec![own_pubkey];
+        if !hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Connecting) {
+            false
+        } else {
+            hs.phase = HuddlePhase::Connected;
+            if !own_pubkey.is_empty() {
+                hs.participants = vec![own_pubkey];
+            }
+            true
         }
+    };
+    if !committed {
+        return Err("huddle join was superseded".to_owned());
     }
 
     // Notify frontend of state change.
@@ -373,15 +418,25 @@ pub async fn join_huddle(
 
     // Hydrate members, download models, start pipelines (incl. audio relay).
     // Audio relay failure is fatal — no point in a huddle without audio.
-    if let Err(e) = post_connect_setup(&state, &ephemeral_channel_id).await {
-        // Rollback: audio relay failed after state was committed.
-        // Reset state to Idle so the user can retry. The ephemeral channel
-        // has a TTL and will expire — no manual archive needed for joiners.
-        if let Ok(mut hs) = state.huddle_state.lock() {
-            hs.reset_preserving_generation();
+    match post_connect_setup(&state, &ephemeral_channel_id, huddle_generation).await {
+        Ok(PostConnectOutcome::Ready) => {}
+        Ok(PostConnectOutcome::Stale) => {
+            return Err("huddle join was superseded".to_owned());
+        }
+        Err(e) => {
+            // Reset only the huddle lifetime that failed.
+            let mut did_reset = false;
+            if let Ok(mut hs) = state.huddle_state.lock() {
+                if hs.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+                    hs.reset_preserving_generation();
+                    did_reset = true;
+                }
+            }
+            if did_reset {
+                state.emit_huddle_state_changed();
+            }
+            return Err(e);
         }
-        state.emit_huddle_state_changed();
-        return Err(e);
     }
 
     Ok(HuddleJoinInfo {
@@ -675,123 +730,6 @@ pub fn push_audio_pcm(
     }
 }
 
-/// Hot-start: check if voice models just finished downloading during an active
-/// huddle and start the corresponding pipelines.
-///
-/// Called by the frontend on a timer or after model status changes. No-op if
-/// the huddle is not active or pipelines are already running.
-#[tauri::command]
-pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), String> {
-    let (is_active, ephemeral_channel_id) = {
-        let hs = state.huddle()?;
-        (
-            matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active),
-            hs.ephemeral_channel_id.clone(),
-        )
-    };
-
-    if !is_active {
-        return Ok(());
-    }
-
-    // Detect dead pipelines: if the worker thread has exited (init failure or crash),
-    // clear the pipeline handle so hot-start can retry on the next cycle.
-    {
-        let mut hs = state.huddle()?;
-        if let Some(ref p) = hs.stt_pipeline {
-            if p.is_finished() {
-                hs.stt_pipeline = None;
-            }
-        }
-        if let Some(ref p) = hs.tts_pipeline {
-            if p.is_finished() {
-                hs.tts_pipeline = None;
-            }
-        }
-    }
-    // Re-read after potential cleanup.
-    let (has_stt, has_tts, transcription_enabled) = {
-        let hs = state.huddle()?;
-        (
-            hs.stt_pipeline.is_some(),
-            hs.tts_pipeline.is_some(),
-            hs.transcription_enabled,
-        )
-    };
-
-    // Check if models just became ready (one-shot flags).
-    let stt_ready = models::global_model_manager()
-        .map(|m| m.take_stt_ready())
-        .unwrap_or(false);
-    let tts_ready = models::global_model_manager()
-        .map(|m| m.take_tts_ready())
-        .unwrap_or(false);
-
-    // Start TTS first (so STT can capture tts_cancel).
-    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}");
-        }
-    }
-
-    if transcription_enabled && !has_stt && (stt_ready || models::is_stt_ready()) {
-        if let Some(eph_id) = &ephemeral_channel_id {
-            if let Err(e) = maybe_start_stt_pipeline(&state, eph_id).await {
-                eprintln!("buzz-desktop: STT hotstart failed: {e}");
-            }
-        }
-    }
-
-    // Periodically refresh agent_pubkeys from relay membership.
-    // This catches mid-huddle agent additions/removals by other participants,
-    // keeping STT p-tags authoritative throughout the session.
-    // Throttled to every 15 s (not on every 5 s hotstart poll).
-    //
-    // NOTE: The frontend ALSO polls agent membership independently (every 10 s
-    // via get_huddle_agent_pubkeys). This is intentional — the two polls have
-    // different failure semantics:
-    //   - Rust (here): preserves stale list on failure (STT p-tags should not
-    //     disappear on a transient network blip).
-    //   - React (HuddleContext.tsx): clears list on failure (TTS authorization
-    //     must fail-closed — never speak from a stale agent list).
-    //
-    // On Ok: always replace (even with empty — agents may have been removed).
-    // On Err: preserve the existing list (transient failure shouldn't zero it).
-    if let Some(eph_id) = &ephemeral_channel_id {
-        let should_refresh = {
-            let hs = state.huddle()?;
-            match hs.last_agent_refresh {
-                None => true,
-                Some(t) => t.elapsed() >= std::time::Duration::from_secs(15),
-            }
-        };
-        if should_refresh {
-            // Fetch agents (for STT p-tags) and all members (for participant list).
-            // Sequential — tokio::join! requires the `macros` feature.
-            // Only update the throttle timestamp when at least one fetch succeeds,
-            // so transient failures retry immediately on the next poll cycle.
-            // Fetch both lists before acquiring the lock — no lock held across await.
-            let fresh_agents = fetch_channel_members(eph_id, Some("bot"), &state)
-                .await
-                .ok();
-            let fresh_members = fetch_channel_members(eph_id, None, &state).await.ok();
-
-            if fresh_agents.is_some() || fresh_members.is_some() {
-                let mut hs = state.huddle()?;
-                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());
-            }
-        }
-    }
-
-    Ok(())
-}
-
 /// Trigger a background download of voice models (Parakeet STT + Pocket TTS).
 ///
 /// Returns immediately — downloads run in tokio background tasks.
@@ -817,91 +755,90 @@ 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,
+    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);
 
     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()?;
+        hs.tts_pipeline
+            .as_ref()
+            .map(|pipeline| pipeline.text_sender())
+    };
+    let Some(sender) = 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, 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.
@@ -924,7 +861,7 @@ pub async fn add_agent_to_huddle(
 ) -> Result<agents::AgentAddResult, String> {
     validate_pubkey_hex(&agent_pubkey)?;
 
-    let (eph_id, parent_id) = {
+    let (eph_id, parent_id, huddle_generation) = {
         let hs = state.huddle()?;
         if !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active) {
             return Err("no active huddle".to_string());
@@ -948,7 +885,7 @@ pub async fn add_agent_to_huddle(
             .clone()
             .ok_or("no ephemeral channel")?;
         let parent = hs.parent_channel_id.clone().ok_or("no parent channel")?;
-        (eph, parent)
+        (eph, parent, hs.huddle_generation)
     };
 
     let eph_uuid = Uuid::parse_str(&eph_id).map_err(|e| e.to_string())?;
@@ -957,29 +894,30 @@ pub async fn add_agent_to_huddle(
     // Returns Err only if the ephemeral add fails — parent failure is in the result.
     let result = agents::add_agent_to_huddle(eph_uuid, parent_uuid, &agent_pubkey, &state).await?;
 
-    // Ephemeral add succeeded — safe to register for p-tagging.
-    // Clone the Arc first so we can drop the outer HuddleState lock before
-    // acquiring the inner pubkeys lock (avoids the E0597 borrow-checker error).
-    {
-        let agent_pubkeys_arc = {
-            let hs = state.huddle()?;
-            Arc::clone(&hs.agent_pubkeys)
-        };
-        let mut pubkeys = agent_pubkeys_arc.lock().unwrap_or_else(|e| e.into_inner());
+    // Ephemeral add succeeded — register it only if this is still the huddle
+    // that initiated the relay operation.
+    let transcription_auto_enabled = {
+        let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(&eph_id, huddle_generation) {
+            return Ok(result);
+        }
+        let mut pubkeys = hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner());
         if !pubkeys.contains(&agent_pubkey) {
             pubkeys.push(agent_pubkey.clone());
         }
-    }
+        drop(pubkeys);
+        if !hs.participants.contains(&agent_pubkey) {
+            hs.participants.push(agent_pubkey.clone());
+        }
+        hs.maybe_auto_enable_transcription_for_agents()
+    };
 
     // No guidelines re-post needed — the agent sees the original kind:48106
     // guidelines via EOSE replay when it subscribes to the ephemeral channel.
-
-    // Also add the agent to the visible participants list.
-    {
-        let mut hs = state.huddle()?;
-        if !hs.participants.contains(&agent_pubkey) {
-            hs.participants.push(agent_pubkey);
-        }
+    if transcription_auto_enabled {
+        start_auto_enabled_transcription(&state, &eph_id).await;
+    } else {
+        state.emit_huddle_state_changed();
     }
 
     Ok(result)
diff --git a/desktop/src-tauri/src/huddle/models.rs b/desktop/src-tauri/src/huddle/models.rs
index 169ddf66c0..f9f7065769 100644
--- a/desktop/src-tauri/src/huddle/models.rs
+++ b/desktop/src-tauri/src/huddle/models.rs
@@ -24,6 +24,14 @@ use std::sync::{Arc, Mutex, OnceLock};
 use serde::{Deserialize, Serialize};
 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 ────────────────────────────────────────────────────
 //
 // All model artifacts are verified against pinned SHA-256 hashes before
@@ -38,19 +46,15 @@ use sha2::{Digest, Sha256};
 /// Computed from a known-good download. Update when upgrading model versions.
 const STT_ARCHIVE_SHA256: &str = "17f945007b52ccd8b7200ffc7c5652e9e8e961dfdf479cefcabd06cf5703630b";
 
-/// HuggingFace base URL for the sherpa-onnx Pocket TTS fp32 repackage.
-///
-/// Pinned to commit 96d1e53ce3311ca6c2c6a35e2062d36b4cec6fa3
-/// (2026-02-10) for reproducible downloads.
-///
-/// fp32 (not int8): a direct same-runtime A/B (k2-fsa/sherpa-onnx#3172)
-/// found the ONNX int8 quantization audibly degraded Pocket TTS output and
-/// that fp32 "significantly improved quality even at 1 step". The runtime
-/// bundle grows from ~189 MB to ~473 MB; encoder, text conditioner, both
-/// JSON tables, and LICENSE are byte-identical between the two repos — only
-/// the three quantized sessions (lm_main, lm_flow, decoder) change.
-const POCKET_HF_BASE: &str =
-    "https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26/resolve/96d1e53ce3311ca6c2c6a35e2062d36b4cec6fa3";
+fn pocket_artifact_url(filename: &str) -> String {
+    format!(
+        "https://huggingface.co/{APRIL_MODEL_ID}/resolve/{APRIL_MODEL_REVISION}/onnx/{APRIL_BUNDLE_ID}/{filename}"
+    )
+}
+
+fn pocket_license_url() -> String {
+    format!("https://huggingface.co/{APRIL_MODEL_ID}/resolve/{APRIL_MODEL_REVISION}/onnx/LICENSE")
+}
 
 /// Reference voice WAV: "Mary (f, conversation)" from the Kyutai TTS demo
 /// voice set — VCTK speaker p333, ai-coustics-enhanced. Pinned to
@@ -64,20 +68,19 @@ const POCKET_HF_BASE: &str =
 const POCKET_REFERENCE_WAV_URL: &str =
     "https://huggingface.co/kyutai/tts-voices/resolve/323332d33f997de8394f24a193e1a76df720e01a/vctk/p333_023_enhanced.wav";
 
-/// SHA-256 hashes for individual Pocket TTS model files.
-/// Computed from known-good pinned downloads. Update when upgrading model versions.
-#[rustfmt::skip]
-const TTS_FILE_HASHES: &[(&str, &str)] = &[
-    ("decoder.onnx",          "f267880fde6c58b17b0a8f3647eaf8dcfad321f833f32d583ebc2fb2d1a15f10"),
-    ("encoder.onnx",          "e8f2f6d301ffb96e398b138a7dc6d3038622d236044636b73d920bab85890260"),
-    ("lm_flow.onnx",          "79c013a554a54e63319c33c0cc8830cbbedc9b7e448ae7e26f7923ae11f9873e"),
-    ("lm_main.onnx",          "255d1a9263c5abdf36034abfc19c11d21cc5f40f0f87d8361288e972cbd5c578"),
-    ("text_conditioner.onnx", "0b84e837d7bfaf2c896627b03e3f080320309f37f4fc7df7698c644f7ba5e6b1"),
-    ("vocab.json",            "6fb646346cf931016f70c4921aab0900ce7a304b893cb02135c74e294abfea01"),
-    ("token_scores.json",     "5be2f278caf9b9800741f0fd82bff677f4943ec764c356f907213434b622d958"),
-    ("LICENSE",               "fe7b4ce83b8381cc5b216bbb4af73c570688d1b819c73bbaed8ca401f4677cd6"),
-    ("reference_sample.wav",  "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f"),
-];
+const TTS_LICENSE_ARTIFACT: PocketModelArtifact = PocketModelArtifact {
+    filename: "LICENSE",
+    sha256: "fe7b4ce83b8381cc5b216bbb4af73c570688d1b819c73bbaed8ca401f4677cd6",
+    size_bytes: 18_655,
+    quantized: false,
+};
+
+const TTS_REFERENCE_ARTIFACT: PocketModelArtifact = PocketModelArtifact {
+    filename: "reference_sample.wav",
+    sha256: "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+    size_bytes: 639_084,
+    quantized: false,
+};
 
 // ── Model versioning ──────────────────────────────────────────────────────────
 //
@@ -92,15 +95,8 @@ const TTS_FILE_HASHES: &[(&str, &str)] = &[
 /// honest (each version tag identifies one specific set of model bytes).
 const STT_MODEL_VERSION: &str = "2";
 
-/// Model manifest version for Pocket TTS. Increment when upgrading model files.
-/// Bumped "1" → "2" when the bundled reference voice changed from KevinAHM's
-/// anonymous 16 kHz sample to Mary (VCTK p333, 32 kHz, ai-coustics-enhanced)
-/// from kyutai/tts-voices. The hash mismatch on `reference_sample.wav` would
-/// fail readiness on its own, but the manifest bump makes the re-download
-/// reason explicit and skips the failing-then-re-fetching transient state.
-/// Bumped "2" → "3" for the int8 → fp32 model swap (see `POCKET_HF_BASE`):
-/// existing int8 installs must re-download the suffixless fp32 sessions.
-const TTS_MODEL_VERSION: &str = "3";
+/// 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";
@@ -110,9 +106,9 @@ const MANIFEST_FILENAME: &str = ".buzz-model-manifest";
 /// Maximum expected STT archive size (200 MB — actual is ~100 MB).
 const MAX_STT_DOWNLOAD_BYTES: u64 = 200 * 1024 * 1024;
 
-/// Maximum expected Pocket TTS file size (400 MB per file — largest is
-/// `lm_main.onnx` at ~303 MB fp32).
-const MAX_TTS_FILE_BYTES: u64 = 400 * 1024 * 1024;
+/// Maximum expected Pocket TTS file size. The largest pinned INT8 artifact is
+/// `flow_lm_main_int8.onnx` at 76,341,079 bytes.
+const MAX_TTS_FILE_BYTES: u64 = 100 * 1024 * 1024;
 
 /// NVIDIA Parakeet TDT-CTC 110M (English, int8) — packaged for sherpa-onnx by
 /// k2-fsa. Single ONNX file (CTC head) + tokens.txt. Avg WER ~7.5% across
@@ -168,50 +164,29 @@ 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.
-
-ONNX export by KevinAHM: https://huggingface.co/KevinAHM/pocket-tts-onnx
-Sherpa-onnx repackage by csukuangfj / k2-fsa:
-https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26
-
-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] = &[
-    "decoder.onnx",
-    "encoder.onnx",
-    "lm_flow.onnx",
-    "lm_main.onnx",
+    "bundle.json",
+    "bos_before_voice.npy",
+    "flow_lm_main_int8.onnx",
+    "flow_lm_flow_int8.onnx",
+    "mimi_decoder_int8.onnx",
+    "mimi_encoder.onnx",
     "text_conditioner.onnx",
-    "vocab.json",
-    "token_scores.json",
+    "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,
 ];
 
@@ -404,6 +379,7 @@ struct ModelSlot {
     dir_name: &'static str,                  // subdir under ~/.buzz/models/
     expected_files: &'static [&'static str], // files required for "ready"
     version: &'static str,                   // manifest version; increment to force re-download
+    expected_size: fn(&str) -> Option<u64>,
     status: Arc<Mutex<ModelStatus>>,
     just_ready: Arc<AtomicBool>, // fires once when download completes
 }
@@ -418,11 +394,17 @@ impl ModelSlot {
             dir_name,
             expected_files,
             version,
+            expected_size: |_| None,
             status: Arc::new(Mutex::new(ModelStatus::NotDownloaded)),
             just_ready: Arc::new(AtomicBool::new(false)),
         }
     }
 
+    fn with_expected_sizes(mut self, expected_size: fn(&str) -> Option<u64>) -> Self {
+        self.expected_size = expected_size;
+        self
+    }
+
     fn model_dir(&self, models_dir: &Path) -> PathBuf {
         models_dir.join(self.dir_name)
     }
@@ -432,7 +414,17 @@ impl ModelSlot {
         std::fs::read_to_string(dir.join(MANIFEST_FILENAME))
             .map(|v| v.trim() == self.version)
             .unwrap_or(false)
-            && self.expected_files.iter().all(|f| dir.join(f).is_file())
+            && self.expected_files.iter().all(|filename| {
+                let path = dir.join(filename);
+                path.is_file()
+                    && (self.expected_size)(filename)
+                        .map(|expected| {
+                            path.metadata()
+                                .map(|metadata| metadata.len() == expected)
+                                .unwrap_or(false)
+                        })
+                        .unwrap_or(true)
+            })
     }
 
     fn dir_if_ready(&self, models_dir: &Path) -> Option<PathBuf> {
@@ -453,6 +445,39 @@ impl ModelSlot {
         self.just_ready.swap(false, Ordering::AcqRel)
     }
 
+    /// Recover or clean up the backup left by an interrupted atomic install.
+    fn recover_interrupted_install(&self, models_dir: &Path) {
+        let final_dir = self.model_dir(models_dir);
+        let backup_dir = final_dir.with_extension("old");
+        if !backup_dir.exists() {
+            return;
+        }
+        if self.is_ready(models_dir) {
+            if let Err(error) = std::fs::remove_dir_all(&backup_dir) {
+                eprintln!(
+                    "buzz-desktop: could not remove stale {} backup: {error}",
+                    self.dir_name
+                );
+            }
+            return;
+        }
+        if final_dir.exists() {
+            if let Err(error) = std::fs::remove_dir_all(&final_dir) {
+                eprintln!(
+                    "buzz-desktop: could not remove incomplete {} install: {error}",
+                    self.dir_name
+                );
+                return;
+            }
+        }
+        if let Err(error) = std::fs::rename(&backup_dir, &final_dir) {
+            eprintln!(
+                "buzz-desktop: could not restore interrupted {} install: {error}",
+                self.dir_name
+            );
+        }
+    }
+
     /// Spawn a background download task if not already ready or downloading.
     fn start_download<F, Fut>(
         &self,
@@ -511,6 +536,9 @@ impl ModelSlot {
             ));
         }
 
+        std::fs::write(source_dir.join(MANIFEST_FILENAME), self.version)
+            .map_err(|e| format!("write model manifest: {e}"))?;
+
         let final_dir = self.model_dir(models_dir);
         let backup_dir = final_dir.with_extension("old");
 
@@ -529,8 +557,6 @@ impl ModelSlot {
             return Err(format!("install new model: {e}"));
         }
 
-        std::fs::write(final_dir.join(MANIFEST_FILENAME), self.version)
-            .map_err(|e| format!("write model manifest: {e}"))?;
         let _ = tokio::fs::remove_dir_all(&backup_dir).await;
         if let Some(extra) = temp_cleanup {
             let _ = tokio::fs::remove_dir_all(extra).await;
@@ -542,6 +568,25 @@ impl ModelSlot {
     }
 }
 
+fn tts_expected_size(filename: &str) -> Option<u64> {
+    april_model_info()
+        .artifacts
+        .iter()
+        .find(|artifact| artifact.filename == filename)
+        .map(|artifact| artifact.size_bytes)
+        .or_else(|| {
+            [TTS_LICENSE_ARTIFACT, TTS_REFERENCE_ARTIFACT]
+                .iter()
+                .find(|artifact| artifact.filename == filename)
+                .map(|artifact| artifact.size_bytes)
+        })
+}
+
+fn tts_model_slot() -> ModelSlot {
+    ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION)
+        .with_expected_sizes(tts_expected_size)
+}
+
 // ── ModelManager ──────────────────────────────────────────────────────────────
 
 /// Manages download and location of STT/TTS model files.
@@ -561,11 +606,13 @@ impl ModelManager {
     /// Returns `None` if the home directory cannot be resolved.
     pub fn new() -> Option<Self> {
         let models_dir = dirs::home_dir()?.join(".buzz").join("models");
-        Some(Self {
+        let manager = Self {
             models_dir,
             stt: ModelSlot::new(STT_MODEL_DIR_NAME, STT_EXPECTED_FILES, STT_MODEL_VERSION),
-            tts: ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION),
-        })
+            tts: tts_model_slot(),
+        };
+        manager.tts.recover_interrupted_install(&manager.models_dir);
+        Some(manager)
     }
 
     // ── STT accessors ────────────────────────────────────────────────────────
@@ -638,8 +685,11 @@ impl ModelManager {
         }
     }
 
-    /// Start a background Pocket TTS download (~189 MB). No-op if already ready or downloading.
+    /// 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,
@@ -754,10 +804,10 @@ impl ModelManager {
     /// Download and verify the Pocket TTS model files from HuggingFace.
     ///
     /// Downloads files into `~/.buzz/models/pocket-tts/`:
-    ///   - five ONNX sessions (Pocket TTS + Mimi codec)
-    ///   - `vocab.json` / `token_scores.json` for sherpa-onnx text conditioning
+    ///   - 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> {
@@ -768,24 +818,18 @@ impl ModelManager {
         let temp_dir = self.models_dir.join("pocket-tts.tmp");
         fresh_temp_dir(&temp_dir).await?;
 
-        let model_files = [
-            "decoder.onnx",
-            "encoder.onnx",
-            "lm_flow.onnx",
-            "lm_main.onnx",
-            "text_conditioner.onnx",
-            "vocab.json",
-            "token_scores.json",
-            "LICENSE",
-        ];
-        let mut downloads: Vec<(String, &'static str)> = model_files
+        let mut downloads: Vec<(String, PocketModelArtifact)> = april_model_info()
+            .artifacts
             .iter()
-            .map(|filename| (format!("{POCKET_HF_BASE}/{filename}"), *filename))
+            .copied()
+            .map(|artifact| (pocket_artifact_url(artifact.filename), artifact))
             .collect();
-        downloads.push((POCKET_REFERENCE_WAV_URL.to_string(), "reference_sample.wav"));
+        downloads.push((pocket_license_url(), TTS_LICENSE_ARTIFACT));
+        downloads.push((POCKET_REFERENCE_WAV_URL.to_string(), TTS_REFERENCE_ARTIFACT));
         let total_files = downloads.len() as u32;
 
-        for (i, (url, filename)) in downloads.iter().enumerate() {
+        for (i, (url, artifact)) in downloads.iter().enumerate() {
+            let filename = artifact.filename;
             eprintln!("buzz-desktop: downloading Pocket TTS {filename} from {url}");
 
             let response = fetch_url(&http_client, url, filename)
@@ -822,16 +866,19 @@ impl ModelManager {
             })?;
             eprintln!("buzz-desktop: downloaded {bytes} bytes ({filename}), wrote to disk");
 
-            let expected = TTS_FILE_HASHES
-                .iter()
-                .find(|(n, _)| *n == *filename)
-                .map(|(_, hash)| *hash)
-                .ok_or_else(|| format!("missing expected hash for Pocket TTS file: {filename}"))?;
+            if bytes != artifact.size_bytes {
+                let _ = tokio::fs::remove_dir_all(&temp_dir).await;
+                return Err(format!(
+                    "Pocket TTS {filename} size check failed: expected {} bytes, got {bytes}",
+                    artifact.size_bytes
+                ));
+            }
             let actual = sha256_file(&dest).await?;
-            if actual != expected {
+            if actual != artifact.sha256 {
                 let _ = tokio::fs::remove_dir_all(&temp_dir).await;
                 return Err(format!(
-                    "Pocket TTS {filename} integrity check failed: expected {expected}, got {actual}"
+                    "Pocket TTS {filename} integrity check failed: expected {}, got {actual}",
+                    artifact.sha256
                 ));
             }
 
@@ -842,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,
@@ -931,24 +989,5 @@ pub fn is_tts_ready() -> bool {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn tts_readiness_requires_license_sidecar() {
-        let temp = tempfile::tempdir().expect("tempdir");
-        let slot = ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION);
-        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 {
-            std::fs::write(model_dir.join(file), b"test").expect("write expected file");
-        }
-        std::fs::write(model_dir.join(MANIFEST_FILENAME), TTS_MODEL_VERSION).expect("manifest");
-
-        assert!(slot.is_ready(temp.path()));
-
-        std::fs::remove_file(model_dir.join(TTS_LICENSE_FILE_NAME)).expect("remove sidecar");
-        assert!(!slot.is_ready(temp.path()));
-    }
-}
+#[path = "models_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/models_tests.rs b/desktop/src-tauri/src/huddle/models_tests.rs
new file mode 100644
index 0000000000..699ffbe459
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/models_tests.rs
@@ -0,0 +1,146 @@
+use super::*;
+
+fn create_ready_model_dir(root: &Path) -> PathBuf {
+    let model_dir = root.join(TTS_MODEL_DIR_NAME);
+    std::fs::create_dir_all(&model_dir).expect("create model dir");
+    for file in TTS_EXPECTED_FILES {
+        let path = model_dir.join(file);
+        let handle = std::fs::File::create(path).expect("create expected file");
+        if let Some(size) = tts_expected_size(file) {
+            handle.set_len(size).expect("size expected file");
+        } else {
+            std::fs::write(model_dir.join(file), b"test").expect("write expected file");
+        }
+    }
+    std::fs::write(model_dir.join(MANIFEST_FILENAME), TTS_MODEL_VERSION).expect("manifest");
+    model_dir
+}
+
+#[test]
+fn expected_files_match_april_int8_metadata() {
+    let mut expected = april_model_info()
+        .artifacts
+        .iter()
+        .map(|artifact| artifact.filename)
+        .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();
+    actual.sort_unstable();
+
+    assert_eq!(actual, expected);
+    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]
+fn tts_readiness_requires_license_sidecar() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+
+    assert!(slot.is_ready(temp.path()));
+
+    std::fs::remove_file(model_dir.join(TTS_LICENSE_FILE_NAME)).expect("remove sidecar");
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn tts_readiness_rejects_truncated_pinned_artifact() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+    let artifact = april_model_info().artifacts[0];
+
+    std::fs::OpenOptions::new()
+        .write(true)
+        .open(model_dir.join(artifact.filename))
+        .expect("open artifact")
+        .set_len(artifact.size_bytes - 1)
+        .expect("truncate artifact");
+
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn january_cache_is_not_ready_for_april_int8() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+    std::fs::create_dir_all(&model_dir).expect("create model dir");
+    for file in [
+        "decoder.onnx",
+        "encoder.onnx",
+        "lm_flow.onnx",
+        "lm_main.onnx",
+        "text_conditioner.onnx",
+        "vocab.json",
+        "token_scores.json",
+        "LICENSE",
+        "reference_sample.wav",
+        TTS_LICENSE_FILE_NAME,
+    ] {
+        std::fs::write(model_dir.join(file), b"january").expect("write January file");
+    }
+    std::fs::write(model_dir.join(MANIFEST_FILENAME), "3").expect("manifest");
+
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn interrupted_install_restores_backup_when_destination_is_missing() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert_eq!(
+        std::fs::read(temp.path().join(TTS_MODEL_DIR_NAME).join("sentinel"))
+            .expect("restored sentinel"),
+        b"previous"
+    );
+    assert!(!backup_dir.exists());
+}
+
+#[test]
+fn interrupted_install_replaces_incomplete_destination_with_backup() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&model_dir).expect("create incomplete destination");
+    std::fs::write(model_dir.join("incomplete"), b"april").expect("write incomplete file");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert_eq!(
+        std::fs::read(model_dir.join("sentinel")).expect("restored sentinel"),
+        b"previous"
+    );
+    assert!(!model_dir.join("incomplete").exists());
+    assert!(!backup_dir.exists());
+}
+
+#[test]
+fn ready_destination_removes_stale_backup() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert!(slot.is_ready(temp.path()));
+    assert!(model_dir.exists());
+    assert!(!backup_dir.exists());
+}
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 ceccedd8b6..fba5464a69 100644
--- a/desktop/src-tauri/src/huddle/pipeline.rs
+++ b/desktop/src-tauri/src/huddle/pipeline.rs
@@ -3,12 +3,16 @@
 //! 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;
+use tauri::State;
 use uuid::Uuid;
 
 use crate::app_state::AppState;
@@ -16,59 +20,228 @@ 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;
 
+pub(crate) enum PostConnectOutcome {
+    Ready,
+    Stale,
+}
+
+/// Hot-start: check if voice models just finished downloading during an active
+/// huddle and start the corresponding pipelines.
+///
+/// Called by the frontend on a timer or after model status changes. No-op if
+/// the huddle is not active or pipelines are already running.
+#[tauri::command]
+pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), String> {
+    let (is_active, ephemeral_channel_id, huddle_generation) = {
+        let hs = state.huddle()?;
+        (
+            matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active),
+            hs.ephemeral_channel_id.clone(),
+            hs.huddle_generation,
+        )
+    };
+
+    if !is_active {
+        return Ok(());
+    }
+
+    // Detect dead pipelines: if the worker thread has exited (init failure or crash),
+    // clear the pipeline handle so hot-start can retry on the next cycle.
+    {
+        let mut hs = state.huddle()?;
+        if let Some(ref p) = hs.stt_pipeline {
+            if p.is_finished() {
+                hs.stt_pipeline = None;
+            }
+        }
+        if let Some(ref p) = hs.tts_pipeline {
+            if p.is_finished() {
+                hs.tts_pipeline = None;
+            }
+        }
+    }
+    // Re-read after potential cleanup.
+    let (has_stt, has_tts, transcription_enabled) = {
+        let hs = state.huddle()?;
+        (
+            hs.stt_pipeline.is_some(),
+            hs.tts_pipeline.is_some(),
+            hs.transcription_enabled,
+        )
+    };
+
+    // Check if models just became ready (one-shot flags).
+    let stt_ready = models::global_model_manager()
+        .map(|m| m.take_stt_ready())
+        .unwrap_or(false);
+    let tts_ready = models::global_model_manager()
+        .map(|m| m.take_tts_ready())
+        .unwrap_or(false);
+
+    // Start TTS first (so STT can capture tts_cancel).
+    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}");
+        }
+    }
+    if transcription_enabled && !has_stt && (stt_ready || models::is_stt_ready()) {
+        if let Some(eph_id) = &ephemeral_channel_id {
+            if let Err(e) = maybe_start_stt_pipeline(&state, eph_id).await {
+                eprintln!("buzz-desktop: STT hotstart failed: {e}");
+            }
+        }
+    }
+
+    // Periodically refresh agent membership from the relay.
+    // This catches mid-huddle additions/removals by other participants, keeps
+    // STT p-tags authoritative, and auto-enables transcription when the first
+    // agent appears unless the user has already chosen a transcription state.
+    // Throttled independently from the more frequent hotstart poll.
+    //
+    // NOTE: The frontend ALSO polls agent membership independently via
+    // get_huddle_agent_pubkeys. This is intentional — the two polls have
+    // different failure semantics:
+    //   - Rust (here): preserves stale list on failure (STT p-tags should not
+    //     disappear on a transient network blip).
+    //   - React (HuddleContext.tsx): clears list on failure (TTS authorization
+    //     must fail-closed — never speak from a stale agent list).
+    //
+    // On Ok: always replace (even with empty — agents may have been removed).
+    // On Err: preserve the existing list (transient failure shouldn't zero it).
+    if let Some(eph_id) = &ephemeral_channel_id {
+        let should_refresh = {
+            let hs = state.huddle()?;
+            match hs.last_agent_refresh {
+                None => true,
+                Some(t) => t.elapsed() >= std::time::Duration::from_secs(15),
+            }
+        };
+        if should_refresh {
+            // Fetch agents (for STT p-tags) before all members (for participant
+            // list) so relay membership queries remain ordered.
+            // Only update the throttle timestamp when at least one fetch succeeds,
+            // so transient failures retry immediately on the next poll cycle.
+            // Fetch both lists before acquiring the lock — no lock held across await.
+            let fresh_agents = fetch_channel_members(eph_id, Some("bot"), &state)
+                .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
+            };
+            if transcription_auto_enabled {
+                start_auto_enabled_transcription(&state, eph_id).await;
+            }
+        }
+    }
+
+    Ok(())
+}
+
 pub(crate) async fn post_connect_setup(
     state: &AppState,
     ephemeral_channel_id: &str,
-) -> Result<(), String> {
+    huddle_generation: u64,
+) -> Result<PostConnectOutcome, String> {
+    {
+        let hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
+    }
+
     // Hydrate agent pubkeys and participants from relay in parallel
     // (authoritative — overrides local guesses).
     let (agents_result, all_members_result) = tokio::join!(
         fetch_channel_members(ephemeral_channel_id, Some("bot"), state),
         fetch_channel_members(ephemeral_channel_id, None, state),
     );
-    if let Ok(agents) = agents_result {
-        let hs = state.huddle()?;
-        *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
-    }
-
-    if let Ok(all_members) = all_members_result {
-        if !all_members.is_empty() {
-            let mut hs = state.huddle()?;
-            hs.participants = all_members;
+    let transcription_auto_enabled = {
+        let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
+        if let Ok(agents) = agents_result {
+            *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
+        }
+        if let Ok(all_members) = all_members_result {
+            if !all_members.is_empty() {
+                hs.participants = all_members;
+            }
         }
+        hs.maybe_auto_enable_transcription_for_agents()
+    };
+
+    if transcription_auto_enabled {
+        state.emit_huddle_state_changed();
     }
 
-    // Prepare TTS for agent voice. STT is transcript-specific and starts only
-    // when transcription is explicitly enabled.
+    // Prepare voice models. Agent presence may have auto-enabled transcription;
+    // explicit user choices remain authoritative.
     if let Some(mgr) = models::global_model_manager() {
         mgr.start_tts_download(state.http_client.clone());
+        if state.huddle()?.transcription_enabled {
+            mgr.start_stt_download(state.http_client.clone());
+        }
     }
 
     // Connect audio relay WebSocket (Opus encode/decode pipeline).
     // This is the core audio path — failure is fatal for the huddle.
     let parent_id = {
         let hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
         hs.parent_channel_id.clone()
     };
-    let (cancel, pcm_tx) =
-        relay_api::connect_audio_relay(ephemeral_channel_id, parent_id.as_deref(), state).await?;
+    let audio_result =
+        relay_api::connect_audio_relay(ephemeral_channel_id, parent_id.as_deref(), state).await;
     {
         let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            if let Ok((cancel, _)) = audio_result {
+                cancel.cancel();
+            }
+            return Ok(PostConnectOutcome::Stale);
+        }
+        let (cancel, pcm_tx) = audio_result?;
         hs.audio_ws_cancel = Some(cancel);
         hs.audio_relay_pcm_tx = Some(pcm_tx);
     }
 
-    // Start TTS immediately. STT/transcript posting is opt-in and starts only
-    // after the user explicitly enables transcription.
+    // Start TTS immediately, then STT when transcription is enabled either by
+    // the user or by authoritative agent membership.
+    if !state
+        .huddle()?
+        .is_current_huddle(ephemeral_channel_id, huddle_generation)
+    {
+        return Ok(PostConnectOutcome::Stale);
+    }
     if let Err(e) = maybe_start_tts_pipeline(state).await {
         eprintln!("buzz-desktop: TTS pipeline failed to start: {e}");
     }
+    if let Err(e) = maybe_start_stt_pipeline(state, ephemeral_channel_id).await {
+        eprintln!("buzz-desktop: STT pipeline failed to start: {e}");
+    }
 
-    Ok(())
+    Ok(PostConnectOutcome::Ready)
 }
 
 /// Attempt to start the STT pipeline if models are present.
@@ -83,12 +256,16 @@ pub(crate) async fn maybe_start_stt_pipeline(
     state: &AppState,
     ephemeral_channel_id: &str,
 ) -> Result<bool, String> {
-    {
+    let huddle_generation = {
         let hs = state.huddle()?;
-        if !hs.transcription_enabled {
+        if !hs.transcription_enabled
+            || !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            || hs.ephemeral_channel_id.as_deref() != Some(ephemeral_channel_id)
+        {
             return Ok(false);
         }
-    }
+        hs.huddle_generation
+    };
 
     if !models::is_stt_ready() {
         return Ok(false); // Models not downloaded yet — voice-only mode.
@@ -97,21 +274,29 @@ pub(crate) async fn maybe_start_stt_pipeline(
 
     let channel_uuid = parse_channel_uuid(ephemeral_channel_id)?;
 
-    // Atomically claim the construction slot (mirrors tts_starting pattern).
-    {
-        let hs = state.huddle()?;
-        if hs.stt_starting.swap(true, Ordering::AcqRel) {
-            return Ok(false); // Another caller is already constructing.
-        }
-    }
-
-    // Grab shared flags, agent pubkeys, and session generation from HuddleState.
+    // Atomically claim construction and grab shared state under one lock.
     // If replacing an existing pipeline, bump generation first so the old
     // transcription task's next POST sees a stale generation and exits.
     // Take the old pipeline OUT of the lock before dropping — Drop joins
     // the worker thread (~200ms) and must not block under the mutex.
-    let (tts_active, tts_cancel, agent_pubkeys_arc, session_gen, ptt_active_for_stt, old_stt) = {
+    let (
+        tts_active,
+        tts_cancel,
+        agent_pubkeys_arc,
+        session_gen,
+        expected_generation,
+        stt_starting,
+        ptt_active_for_stt,
+        old_stt,
+    ) = {
         let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(false);
+        }
+        if hs.stt_starting.swap(true, Ordering::AcqRel) {
+            return Ok(false);
+        }
+        let stt_starting = Arc::clone(&hs.stt_starting);
         // Invalidate any existing transcription task before replacing the pipeline.
         if hs.stt_pipeline.is_some() {
             hs.session_generation.fetch_add(1, Ordering::Release);
@@ -130,6 +315,8 @@ pub(crate) async fn maybe_start_stt_pipeline(
             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,
             old,
         )
@@ -144,13 +331,11 @@ pub(crate) async fn maybe_start_stt_pipeline(
     let (pipeline, text_rx) = match constructed {
         Ok(Ok(p)) => p,
         Ok(Err(e)) => {
-            let hs = state.huddle()?;
-            hs.stt_starting.store(false, Ordering::Release);
+            stt_starting.store(false, Ordering::Release);
             return Err(e);
         }
         Err(e) => {
-            let hs = state.huddle()?;
-            hs.stt_starting.store(false, Ordering::Release);
+            stt_starting.store(false, Ordering::Release);
             return Err(format!("spawn_blocking failed: {e}"));
         }
     };
@@ -158,10 +343,14 @@ pub(crate) async fn maybe_start_stt_pipeline(
 
     {
         let mut hs = state.huddle()?;
-        hs.stt_starting.store(false, Ordering::Release);
+        stt_starting.store(false, Ordering::Release);
         // Phase check: huddle may have been torn down during construction.
         if !hs.transcription_enabled
-            || !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            || !hs.is_current_transcription_generation(
+                ephemeral_channel_id,
+                huddle_generation,
+                expected_generation,
+            )
         {
             return Ok(false);
         }
@@ -172,6 +361,17 @@ pub(crate) async fn maybe_start_stt_pipeline(
     Ok(true)
 }
 
+/// Start STT after agent presence automatically enables transcription.
+pub(crate) async fn start_auto_enabled_transcription(state: &AppState, ephemeral_channel_id: &str) {
+    if let Some(manager) = models::global_model_manager() {
+        manager.start_stt_download(state.http_client.clone());
+    }
+    if let Err(error) = maybe_start_stt_pipeline(state, ephemeral_channel_id).await {
+        eprintln!("buzz-desktop: auto-enabled STT failed to start: {error}");
+    }
+    state.emit_huddle_state_changed();
+}
+
 /// Attempt to start the TTS pipeline if TTS models are present and TTS is enabled.
 ///
 /// Returns `Ok(true)` if the pipeline was started, `Ok(false)` if preconditions
@@ -192,10 +392,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 {
+        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);
@@ -206,18 +440,25 @@ 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,
+        )
     })
     .await;
     let pipeline = match constructed {
@@ -234,23 +475,104 @@ 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)
+/// has a directly testable seam: the NIP-49 egress guard runs here, before
+/// any bytes can reach the network.
+pub(crate) fn sign_and_guard_stt_body(
+    builder: nostr::EventBuilder,
+    keys: &nostr::Keys,
+) -> Result<Vec<u8>, String> {
+    let event = builder
+        .sign_with_keys(keys)
+        .map_err(|e| format!("sign event: {e}"))?;
+    let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "huddle STT publish")?;
+    Ok(body_bytes)
+}
+
 /// Spawn a tokio task that reads text_rx and posts kind:9 events.
 ///
 /// Fix 1: `agent_pubkeys_arc` is an `Arc<Mutex<Vec<String>>>` cloned from
@@ -310,14 +632,13 @@ pub(crate) fn spawn_transcription_task(
             // the kind event and build NIP-98 auth after the wait so both
             // timestamps are fresh — single clean order: wait → sign → auth → send.
             crate::relay_admission::wait_for_rate_limit().await;
-            let event = match builder.sign_with_keys(&keys) {
-                Ok(e) => e,
+            let body_bytes = match sign_and_guard_stt_body(builder, &keys) {
+                Ok(b) => b,
                 Err(e) => {
-                    eprintln!("buzz-desktop: STT sign event: {e}");
+                    eprintln!("buzz-desktop: STT publish: {e}");
                     continue;
                 }
             };
-            let body_bytes = event.as_json().into_bytes();
             let url = format!("{relay_base_url}/events");
             let auth_header = match crate::relay::build_nip98_auth_header_for_keys(
                 &keys,
@@ -357,3 +678,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/pocket.rs b/desktop/src-tauri/src/huddle/pocket.rs
index ee1faf928a..fd407103d1 100644
--- a/desktop/src-tauri/src/huddle/pocket.rs
+++ b/desktop/src-tauri/src/huddle/pocket.rs
@@ -1,654 +1,4 @@
-//! Pocket TTS engine wrapper around sherpa-onnx's `OfflineTts`.
-//!
-//! Pocket TTS is a small (~473 MB fp32 ONNX) zero-shot voice-cloning TTS
-//! model from Kyutai. It runs quickly on CPU via sherpa-onnx, replacing the
-//! previous Kokoro-82M engine that also required an espeak-free but
-//! lexicon-heavy G2P pipeline (Misaki + CMUdict).
-//!
-//! Full-precision fp32 sessions, not the ~189 MB int8 quantization we
-//! originally shipped: a direct same-runtime A/B (k2-fsa/sherpa-onnx#3172)
-//! found the int8 ONNX export audibly degraded output quality, and fp32
-//! "significantly improved quality even at 1 step".
-//!
-//! ## Attribution
-//!
-//! - **Model**: Kyutai *Pocket TTS* — Charles, Roebel, et al., 2026.
-//!   arXiv:2509.06926. Original repository: <https://huggingface.co/kyutai/pocket-tts>.
-//!   Licensed CC-BY-4.0.
-//! - **Mimi neural codec**: Kyutai, bundled in the same release. CC-BY-4.0.
-//! - **ONNX export**: KevinAHM —
-//!   <https://huggingface.co/KevinAHM/pocket-tts-onnx>. CC-BY-4.0.
-//! - **sherpa-onnx repackage**: csukuangfj / k2-fsa —
-//!   <https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26>.
-//!   Repackages KevinAHM's export with the file layout sherpa-onnx's
-//!   `OfflineTtsPocketModelConfig` expects. CC-BY-4.0.
-//! - **Reference voice WAV** (`reference_sample.wav`): the "Mary
-//!   (f, conversation)" preset from the Kyutai TTS demo
-//!   (<https://kyutai.org/tts>), which maps to `vctk/p333_023_enhanced.wav`
-//!   in <https://huggingface.co/kyutai/tts-voices>. CC-BY-4.0, base recording
-//!   from the VCTK corpus, enhanced by ai-coustics.
-//!
-//! Buzz ships these files unmodified; see the on-disk `MODEL_LICENSE.txt`
-//! sidecar written by `huddle::models` during install for the canonical
-//! CC-BY-4.0 §3(a)(1) attribution block.
-//!
-//! ## Engine-module contract (see `huddle::tts`)
-//!
-//! `pocket.rs` exposes a fixed surface used by `tts.rs`. Mirroring this
-//! contract is what lets the TTS pipeline stay engine-agnostic:
-//!
-//! - `SAMPLE_RATE: u32`             — engine output sample rate in Hz.
-//! - `DEFAULT_VOICE: &str`          — default voice name (without extension).
-//! - `VOICE_FILE_EXT: &str`         — extension for per-voice files on disk.
-//! - `load_text_to_speech(model_dir)`              → `Result<Engine, String>`
-//! - `load_voice_style(path)`                      → `Result<VoiceStyle, String>`
-//! - `Engine::synth_chunk(&self, text, lang, &VoiceStyle, steps)`
-//!   → `Result<Vec<f32>, String>`
-//!
-//! `lang` and `steps` are accepted for API compatibility with the previous
-//! Kokoro engine but are unused — Pocket TTS does its own language ID from
-//! the input text and is not a diffusion model (consistency LM, one step).
-//! There is no speed knob: sherpa-onnx's `GenerationConfig.speed` is only
-//! read by some model families (vits), never by the Pocket impl
-//! (`offline-tts-pocket-impl.h` — zero references), and upstream pocket-tts
-//! has no speed parameter either.
-
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-
-use sherpa_onnx::{GenerationConfig, OfflineTts, OfflineTtsConfig, Wave};
-
-// ── Engine-module contract: public consts ─────────────────────────────────────
-
-/// Pocket TTS emits 24 kHz mono PCM. Matches the previous Kokoro output rate,
-/// so the rodio sink and inter-sentence silence buffer in `tts.rs` remain valid.
-pub const SAMPLE_RATE: u32 = 24_000;
-
-/// Name (without extension) of the bundled reference voice. The model directory
-/// is expected to contain `<DEFAULT_VOICE>.<VOICE_FILE_EXT>` after install.
-pub const DEFAULT_VOICE: &str = "reference_sample";
-
-/// Voice files for Pocket TTS are reference audio (WAV). Distinct from the
-/// Kokoro `.bin` style vectors — the model conditions on raw waveform samples,
-/// not a precomputed embedding, so the extension change is honest.
-pub const VOICE_FILE_EXT: &str = "wav";
-
-// ── Tuning ────────────────────────────────────────────────────────────────────
-
-/// Single-threaded ONNX execution for predictable CPU contention with the STT
-/// pipeline. Matches `STT_NUM_THREADS` in `stt.rs`; raise only if a benchmark
-/// argues for it.
-const TTS_NUM_THREADS: i32 = 1;
-
-/// LRU cache size for cloned voice embeddings inside the sherpa-onnx engine.
-/// We bind to one voice per pipeline today, but the upstream example uses 16
-/// and the cost is negligible — keep room for future multi-voice support.
-const VOICE_EMBEDDING_CACHE_CAPACITY: i32 = 16;
-
-/// Pocket TTS is a consistency-based LM. Generation quality saturates at one
-/// denoising step — the upstream `GenerationConfig` default of 5 multiplies
-/// synthesis time by ~5× with no audible benefit on this model.
-const SYNTH_NUM_STEPS: i32 = 1;
-
-/// Leave the generated audio's silences untouched (1.0 is the identity).
-///
-/// sherpa-onnx's `ScaleSilence` (`offline-tts.cc`) is *not* pre/post padding
-/// control: it finds every interior silence run ≥ 0.2 s (|s| ≤ 0.01) and
-/// multiplies its length by this factor. The previous value of 0.0 — set
-/// under the mistaken belief it disabled lead-in/lead-out padding — deleted
-/// every natural pause inside an utterance: clause breaks, breaths, the gap
-/// after a comma. Words slammed together and endings cut abruptly. The
-/// reference Pocket TTS pipeline does not post-process silence at all;
-/// 1.0 restores parity.
-const SYNTH_SILENCE_SCALE: f32 = 1.0;
-
-/// sherpa-onnx upstream default for `max_frames` (LM steps), in
-/// `offline-tts-pocket-impl.h:Generate`. 500 steps ≈ 40 s of audio at the
-/// Mimi 12.5 Hz frame rate. Referenced only by the regression test below;
-/// production code path never raises (or even reads) this value — we just
-/// leave sherpa-onnx's own default in place by not setting the override.
-#[cfg(test)]
-const SHERPA_ONNX_MAX_FRAMES_DEFAULT: i32 = 500;
-
-/// Tight `max_frames` we ask for on short, padded prompts to bound the
-/// original "monster breathing" runaway. 100 LM steps ≈ 8 s of audio —
-/// roomy for any one-to-four-word utterance the user is likely to elicit
-/// while still well short of the 40 s upstream default. Chosen with slack so
-/// we never *truncate* a legitimate short reply.
-const SHORT_PROMPT_MAX_FRAMES: i32 = 100;
-
-/// Word-count threshold (inclusive) below which we pad the prompt with
-/// leading spaces and cap `max_frames` tighter than the upstream default.
-/// Matches upstream `pocket_tts.models.tts_model.prepare_text_prompt`. Above
-/// this threshold we leave sherpa-onnx's own defaults in place — overriding
-/// them caused the "first 'yep' is just static" regression seen on
-/// 2026-05-18, where dropping `frames_after_eos` below the upstream default
-/// of 3 clipped the leading audio of multi-clause sentences.
-const SHORT_PROMPT_WORD_THRESHOLD: usize = 4;
-
-/// Number of leading spaces prepended to short prompts. The upstream Python
-/// uses exactly 8 — keep parity rather than tuning blindly.
-///
-/// This is upstream's *only* mitigation for the FlowLM cold-start smear on
-/// short utterances (kyutai-labs/pocket-tts #91, #70): the autoregressive
-/// generation has a 2–3 step "settle" period where the first phoneme can be
-/// smeared. A previous revision added a sacrificial `". . "` prefix plus an
-/// amplitude-threshold trim to strip the rendered prefix from the output —
-/// but the trim's absolute threshold (0.02 against raw peaks of ~0.076) sat
-/// in soft-onset territory and could eat real word starts, and its tuning
-/// was calibrated against `silence_scale = 0.0` audio. Deleted in favour of
-/// upstream parity: accept the occasional smeared first syllable rather
-/// than risk trimming real speech.
-const SHORT_PROMPT_PAD_SPACES: usize = 8;
-
-/// sherpa-onnx's documented `frames_after_eos` default. We deliberately do
-/// *not* override this knob — the previous attempt to bump it for short
-/// inputs and lower it for long inputs lowered it below the upstream default
-/// of 3, which clipped the leading audio of multi-clause sentences (the
-/// "first 'yep' is static" regression). The constant exists only for the
-/// regression test below. Source: `offline-tts-pocket-impl.h:Generate`.
-#[cfg(test)]
-const SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT: i32 = 3;
-
-// ── ONNX file names (five Pocket TTS sessions plus two JSON tables) ───────────
-
-const FILE_LM_MAIN: &str = "lm_main.onnx";
-const FILE_LM_FLOW: &str = "lm_flow.onnx";
-const FILE_ENCODER: &str = "encoder.onnx";
-const FILE_DECODER: &str = "decoder.onnx";
-const FILE_TEXT_COND: &str = "text_conditioner.onnx";
-const FILE_VOCAB: &str = "vocab.json";
-const FILE_TOKEN_SCORES: &str = "token_scores.json";
-
-// ── Voice style ───────────────────────────────────────────────────────────────
-
-/// Loaded reference voice — normalised f32 PCM samples plus their sample rate.
-///
-/// Pocket TTS takes a reference waveform per generation call (not a
-/// precomputed style embedding), so we keep the samples in memory and clone
-/// the small `Vec` into each `GenerationConfig` rather than re-reading the
-/// WAV from disk on every sentence.
-#[derive(Debug, Clone)]
-pub struct VoiceStyle {
-    samples: Vec<f32>,
-    sample_rate: i32,
-}
-
-/// Load a reference voice WAV from disk.
-///
-/// Accepts any sample rate sherpa-onnx's `Wave::read` can decode — Pocket TTS
-/// resamples internally using `reference_sample_rate`. The bundled
-/// `reference_sample.wav` ("Mary" — VCTK p333, enhanced) is 32 kHz mono.
-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(),
-    })
-}
-
-// ── Engine ────────────────────────────────────────────────────────────────────
-
-/// Pocket TTS engine handle. Cheap to construct (one `OfflineTts::create`
-/// call). Owned by the TTS worker thread for the lifetime of a huddle session.
-///
-/// `OfflineTts` does not implement `Debug`, so we don't derive it here — the
-/// pipeline only needs to move the engine into the worker thread and call
-/// `synth_chunk` on it, never to print it.
-pub struct PocketTts {
-    inner: OfflineTts,
-}
-
-/// Build the Pocket TTS engine from the model directory installed by
-/// `huddle::models`. Returns `Err` if any expected ONNX or JSON file is
-/// missing — readiness is normally enforced by `is_tts_ready` upstream, but
-/// the check is repeated here so a manually-modified model dir produces a
-/// clear error string instead of an opaque sherpa-onnx `None`.
-pub fn load_text_to_speech(model_dir: &str) -> Result<PocketTts, String> {
-    let dir = PathBuf::from(model_dir);
-    for name in [
-        FILE_LM_MAIN,
-        FILE_LM_FLOW,
-        FILE_ENCODER,
-        FILE_DECODER,
-        FILE_TEXT_COND,
-        FILE_VOCAB,
-        FILE_TOKEN_SCORES,
-    ] {
-        let p = dir.join(name);
-        if !p.is_file() {
-            return Err(format!("missing Pocket TTS file: {}", p.display()));
-        }
-    }
-
-    let to_str = |name: &str| -> String { dir.join(name).to_string_lossy().into_owned() };
-
-    // Build the config by mutating defaults — mirrors `stt.rs` and stays
-    // resilient if sherpa-onnx adds unrelated model-family fields.
-    let mut cfg = OfflineTtsConfig::default();
-    cfg.model.pocket.lm_main = Some(to_str(FILE_LM_MAIN));
-    cfg.model.pocket.lm_flow = Some(to_str(FILE_LM_FLOW));
-    cfg.model.pocket.encoder = Some(to_str(FILE_ENCODER));
-    cfg.model.pocket.decoder = Some(to_str(FILE_DECODER));
-    cfg.model.pocket.text_conditioner = Some(to_str(FILE_TEXT_COND));
-    cfg.model.pocket.vocab_json = Some(to_str(FILE_VOCAB));
-    cfg.model.pocket.token_scores_json = Some(to_str(FILE_TOKEN_SCORES));
-    cfg.model.pocket.voice_embedding_cache_capacity = VOICE_EMBEDDING_CACHE_CAPACITY;
-    cfg.model.num_threads = TTS_NUM_THREADS;
-    // Explicit — defaults are not part of the API contract, and noisy debug
-    // logging in release builds would be expensive on every synthesized chunk.
-    cfg.model.debug = false;
-
-    let inner = OfflineTts::create(&cfg)
-        .ok_or_else(|| "OfflineTts::create returned None for Pocket TTS".to_string())?;
-    Ok(PocketTts { inner })
-}
-
-// ── Prompt preparation ────────────────────────────────────────────────────────
-
-/// Result of [`prepare_pocket_prompt`]: a synthesizer-ready prompt plus the
-/// per-call generation overrides derived from the original text.
-///
-/// `None` for either override means "leave sherpa-onnx's documented default
-/// in place". The pipeline only sets `max_frames` (and only for short
-/// padded inputs) so it can bound the original "monster breathing" runaway
-/// without disturbing the rest of the LM sampling envelope.
-#[derive(Debug, Clone, PartialEq)]
-pub(crate) struct PreparedPrompt {
-    /// Text to hand to `OfflineTts::generate_with_config`. Capitalized,
-    /// punctuation-terminated, and (for short inputs) left-padded with
-    /// spaces — upstream's mitigation for the FlowLM cold-start smear.
-    pub text: String,
-    /// Value to pass via `GenerationConfig.extra["max_frames"]`, or `None` to
-    /// keep the upstream default of 500 LM steps. We only override on short
-    /// padded prompts where we have a tight expectation on output length.
-    pub max_frames: Option<i32>,
-}
-
-/// Mirror of the *text-preparation* half of upstream
-/// `pocket_tts.models.tts_model.prepare_text_prompt`. Sherpa-onnx's C++
-/// Pocket TTS impl does not run these preparation steps, so short /
-/// unpunctuated / lowercase inputs can trigger up to 40 s of runaway
-/// generation when the EOS logit never crosses its threshold. We replicate
-/// the upstream Python recipe here:
-///
-/// 1. Collapse interior whitespace (already done by `preprocess_for_tts`, but
-///    cheap to re-check after sentence splitting).
-/// 2. Capitalize the first letter.
-/// 3. Append `.` if the text doesn't end in punctuation.
-/// 4. If fewer than five words, prepend `SHORT_PROMPT_PAD_SPACES` spaces
-///    (upstream's cold-start mitigation — see the constant's docstring) and
-///    return a tight [`SHORT_PROMPT_MAX_FRAMES`] cap so the LM can't run
-///    away if EOS still doesn't fire.
-///
-/// We do **not** override `frames_after_eos` — sherpa-onnx's default of 3
-/// is what we want. An earlier version set it to 1 on long inputs, which
-/// clipped the leading audio of multi-clause sentences ("first 'yep' is
-/// just static" regression). Tests `prepare_prompt_never_lowers_frames_…`
-/// lock this in.
-///
-/// Returns `None` only if the input is empty after trimming — caller should
-/// skip synthesis in that case.
-pub(crate) fn prepare_pocket_prompt(input: &str) -> Option<PreparedPrompt> {
-    let trimmed = input.trim();
-    if trimmed.is_empty() {
-        return None;
-    }
-
-    // Collapse stray double-spaces / embedded newlines that may slip past
-    // `preprocess_for_tts` when sentences are spliced back together.
-    let mut cleaned = String::with_capacity(trimmed.len());
-    let mut last_was_space = false;
-    for ch in trimmed.chars() {
-        let is_ws = ch.is_whitespace();
-        if is_ws {
-            if !last_was_space {
-                cleaned.push(' ');
-            }
-            last_was_space = true;
-        } else {
-            cleaned.push(ch);
-            last_was_space = false;
-        }
-    }
-
-    // Capitalize first character. Uses `to_uppercase` (multi-codepoint safe).
-    let first = cleaned.chars().next().expect("cleaned non-empty above");
-    if first.is_lowercase() {
-        let upper: String = first.to_uppercase().collect();
-        let mut iter = cleaned.chars();
-        iter.next();
-        cleaned = upper + iter.as_str();
-    }
-
-    // Ensure terminal punctuation. Anything not in `.!?;:,` gets a period.
-    // The upstream Python only checks `isalnum` → period, but for our agent
-    // text we already may end in `!` `?` `.` etc. — treat any of those as OK.
-    let last = cleaned
-        .chars()
-        .next_back()
-        .expect("cleaned non-empty above");
-    if !matches!(last, '.' | '!' | '?' | ';' | ':' | ',') {
-        cleaned.push('.');
-    }
-
-    // Word count of the *cleaned but not padded* text — padding is whitespace
-    // only and would just lie to the threshold check below.
-    let word_count = cleaned.split_whitespace().count();
-
-    let (final_text, max_frames) = if word_count <= SHORT_PROMPT_WORD_THRESHOLD {
-        let mut padded = String::with_capacity(cleaned.len() + SHORT_PROMPT_PAD_SPACES);
-        for _ in 0..SHORT_PROMPT_PAD_SPACES {
-            padded.push(' ');
-        }
-        padded.push_str(&cleaned);
-        (padded, Some(SHORT_PROMPT_MAX_FRAMES))
-    } else {
-        // For everything ≥5 words, fall back to upstream defaults. Overriding
-        // these is what caused the "first 'yep' is static" regression — the
-        // upstream LM has been tuned for `frames_after_eos = 3` and
-        // `max_frames = 500`, and there's no clear win in second-guessing.
-        (cleaned, None)
-    };
-
-    Some(PreparedPrompt {
-        text: final_text,
-        max_frames,
-    })
-}
-
-/// Build the `GenerationConfig.extra` HashMap from a [`PreparedPrompt`].
-///
-/// Centralised so the regression test below can assert that we **never**
-/// emit a `frames_after_eos` override — the previous attempt to override
-/// that knob (setting it to 1 for ≥5-word inputs) clipped the leading
-/// audio of multi-clause sentences (the "first 'yep' is static" bug on
-/// 2026-05-18). The upstream sherpa-onnx default of 3 is what we want, and
-/// the right way to keep it is to not set it at all.
-fn build_generation_extra(prepared: &PreparedPrompt) -> Option<HashMap<String, serde_json::Value>> {
-    prepared.max_frames.map(|mf| {
-        let mut h: HashMap<String, serde_json::Value> = HashMap::with_capacity(1);
-        h.insert("max_frames".to_string(), serde_json::Value::from(mf));
-        h
-    })
-}
-
-impl PocketTts {
-    /// Synthesise `text` with the given reference voice.
-    ///
-    /// `_lang` and `_steps` are accepted for API compatibility with the
-    /// previous Kokoro engine. Pocket TTS infers language from the input text
-    /// directly and is a one-step consistency model. Returns an empty buffer
-    /// for whitespace-only input.
-    pub fn synth_chunk(
-        &self,
-        text: &str,
-        _lang: &str,
-        style: &VoiceStyle,
-        _steps: usize,
-    ) -> Result<Vec<f32>, String> {
-        // Mirror upstream pocket-tts prompt prep — without this short or
-        // unpunctuated inputs can cause the LM's EOS logit to never trip,
-        // producing up to 40 s of "monster breathing" garbage on the first
-        // utterance. See `prepare_pocket_prompt` for the full recipe.
-        let prepared = match prepare_pocket_prompt(text) {
-            Some(p) => p,
-            None => return Ok(Vec::new()),
-        };
-
-        // Per-call generation hints sherpa-onnx forwards to
-        // `offline-tts-pocket-impl.h`. We only override `max_frames`, and
-        // only for short padded prompts where we have a tight expectation
-        // on output length — that bounds the original runaway without
-        // disturbing the rest of the LM sampling envelope. See
-        // `prepare_pocket_prompt` docs for the regression history.
-        let extra = build_generation_extra(&prepared);
-
-        let cfg = GenerationConfig {
-            num_steps: SYNTH_NUM_STEPS,
-            silence_scale: SYNTH_SILENCE_SCALE,
-            reference_audio: Some(style.samples.clone()),
-            reference_sample_rate: style.sample_rate,
-            extra,
-            // `speed` stays at its default: the Pocket impl never reads it
-            // (see the engine-contract note in the module docs).
-            ..Default::default()
-        };
-
-        // No progress callback — synthesis is fast enough that returning the
-        // whole buffer at once keeps the lookahead pipelining in `tts.rs`
-        // simple. `None::<fn(...) -> bool>` pins the callback type for the
-        // `generate_with_config` generic parameter.
-        let audio = self
-            .inner
-            .generate_with_config(&prepared.text, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .ok_or_else(|| {
-                format!(
-                    "Pocket TTS synthesis failed for text ({} chars)",
-                    prepared.text.len()
-                )
-            })?;
-
-        let sample_rate = audio.sample_rate();
-        if sample_rate != SAMPLE_RATE as i32 {
-            eprintln!(
-                "buzz-desktop: Pocket TTS returned unexpected sample rate {sample_rate}Hz \
-                 (expected {SAMPLE_RATE}Hz); playback speed may be wrong"
-            );
-        }
-
-        Ok(audio.samples().to_vec())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    // ── prepare_pocket_prompt ────────────────────────────────────────────────
-
-    #[test]
-    fn prepare_prompt_returns_none_for_empty_input() {
-        assert!(prepare_pocket_prompt("").is_none());
-        assert!(prepare_pocket_prompt("   ").is_none());
-        assert!(prepare_pocket_prompt("\n\t  ").is_none());
-    }
-
-    /// Helper: the exact leading sequence prepended to every short prompt —
-    /// 8 spaces of padding (upstream's cold-start mitigation).
-    /// Centralising this keeps the assertions readable.
-    fn short_prefix() -> String {
-        " ".repeat(SHORT_PROMPT_PAD_SPACES)
-    }
-
-    #[test]
-    fn prepare_prompt_pads_and_capitalizes_one_word() {
-        // The "yep" case Tyler hit in production — bare lowercase one-word
-        // utterance with no punctuation. Must be padded with the short-prompt
-        // space pad, capitalized, terminated, with a tight `max_frames` cap
-        // to bound runaway gen.
-        let out = prepare_pocket_prompt("yep").expect("non-empty");
-        assert_eq!(out.text, format!("{}Yep.", short_prefix()));
-        assert_eq!(out.max_frames, Some(SHORT_PROMPT_MAX_FRAMES));
-        const {
-            assert!(
-                SHORT_PROMPT_MAX_FRAMES < SHERPA_ONNX_MAX_FRAMES_DEFAULT,
-                "short cap must be tighter than the upstream default"
-            );
-        }
-    }
-
-    #[test]
-    fn prepare_prompt_preserves_existing_punctuation() {
-        let out = prepare_pocket_prompt("yes!").expect("non-empty");
-        assert_eq!(out.text, format!("{}Yes!", short_prefix())); // exclamation kept
-        let out = prepare_pocket_prompt("really?").expect("non-empty");
-        assert_eq!(out.text, format!("{}Really?", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_threshold_is_inclusive_at_four_words() {
-        // 4 words = short (padded + tight max_frames); 5 words = long
-        // (no padding, no overrides — upstream defaults stand).
-        let four = prepare_pocket_prompt("one two three four").expect("non-empty");
-        assert_eq!(
-            four.text,
-            format!("{}One two three four.", short_prefix()),
-            "four-word input should get exactly the space pad"
-        );
-        assert_eq!(four.max_frames, Some(SHORT_PROMPT_MAX_FRAMES));
-
-        let five = prepare_pocket_prompt("one two three four five").expect("non-empty");
-        assert!(
-            !five.text.starts_with(' '),
-            "five-word input should NOT be padded"
-        );
-        assert_eq!(
-            five.max_frames, None,
-            "long inputs must leave sherpa-onnx's max_frames default in place"
-        );
-    }
-
-    #[test]
-    fn prepare_prompt_does_not_pad_long_text() {
-        let long = "This is a longer sentence that the model should handle just fine.";
-        let out = prepare_pocket_prompt(long).expect("non-empty");
-        assert!(!out.text.starts_with(' '));
-        assert_eq!(out.max_frames, None);
-        assert!(out.text.ends_with('.'));
-    }
-
-    #[test]
-    fn prepare_prompt_collapses_whitespace() {
-        let out = prepare_pocket_prompt("Hello    world\n\nfriend").expect("non-empty");
-        // 3 words → short → padded. Interior whitespace collapsed.
-        assert_eq!(out.text, format!("{}Hello world friend.", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_does_not_double_capitalize_already_uppercase() {
-        let out = prepare_pocket_prompt("HELLO there").expect("non-empty");
-        assert_eq!(out.text, format!("{}HELLO there.", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_handles_non_ascii_first_letter() {
-        // Cyrillic lowercase 'д' → uppercase 'Д'. Must not panic / produce
-        // mojibake.
-        let out = prepare_pocket_prompt("дa").expect("non-empty");
-        assert!(out.text.contains("Дa."));
-    }
-
-    /// REGRESSION GUARD: short prompts must receive *only* whitespace
-    /// padding — no sacrificial text. A previous revision prepended a
-    /// `". . "` cold-start absorber and trimmed the rendered audio back out
-    /// with an amplitude threshold that could eat soft word onsets. If
-    /// non-whitespace ever reappears in the pad, the synth output will
-    /// contain audio for text the user never wrote.
-    #[test]
-    fn prepare_prompt_pad_is_whitespace_only() {
-        let out = prepare_pocket_prompt("I'm happy.").expect("non-empty");
-        let pad_len = out.text.len() - "I'm happy.".len();
-        assert!(
-            out.text[..pad_len].chars().all(|c| c == ' '),
-            "short-prompt pad must be spaces only, got {:?}",
-            &out.text[..pad_len]
-        );
-        assert_eq!(out.text, format!("{}I'm happy.", short_prefix()));
-    }
-
-    // ── build_generation_extra ───────────────────────────────────────────────
-    //
-    // These tests pin down a behaviour we've now regressed twice on:
-    //   1) Not padding/punctuating short inputs → 40 s of "monster breathing"
-    //      (pre-773a2a1).
-    //   2) Setting `frames_after_eos = 1` on long inputs → clipped leading
-    //      audio of multi-clause sentences, e.g. "Yep, I can hear you. …"
-    //      came out as a static burst (the 773a2a1 regression Tyler hit on
-    //      2026-05-18 ~14:30 UTC).
-    //
-    // The contract we enforce going forward: we **only** override
-    // `max_frames`, and only for ≤4-word inputs. Every other knob is left
-    // at sherpa-onnx's documented default (notably `frames_after_eos = 3`).
-
-    #[test]
-    fn build_extra_short_prompt_sets_only_max_frames() {
-        let prepared = prepare_pocket_prompt("yep").expect("non-empty");
-        let extra = build_generation_extra(&prepared).expect("short prompts get extra");
-        // Exactly one key — `max_frames` — and nothing else.
-        assert_eq!(extra.len(), 1, "extra has unexpected keys: {extra:?}");
-        assert_eq!(
-            extra.get("max_frames"),
-            Some(&serde_json::Value::from(SHORT_PROMPT_MAX_FRAMES))
-        );
-        assert!(
-            !extra.contains_key("frames_after_eos"),
-            "frames_after_eos must never be set — upstream default of {SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT} is what we want"
-        );
-    }
-
-    #[test]
-    fn build_extra_long_prompt_is_none() {
-        // ≥5 words: no extras at all. This is the key fix for the "first
-        // 'yep' in 'Yep, I can hear you. …' is static" regression — we
-        // were previously forcing `frames_after_eos = 1` on this path.
-        let prepared = prepare_pocket_prompt("Yep, I can hear you.").expect("non-empty");
-        assert_eq!(
-            build_generation_extra(&prepared),
-            None,
-            "long prompts must not override any LM knob"
-        );
-    }
-
-    #[test]
-    fn build_extra_never_lowers_frames_after_eos_for_any_word_count() {
-        // Sweep a range of prompt lengths and assert the `extra` map (when
-        // present) never carries a `frames_after_eos` override that's lower
-        // than the upstream sherpa-onnx default. Implemented as a structural
-        // check — we just never set the key — but worth a property test in
-        // case someone reintroduces the override in the future.
-        let prompts: &[&str] = &[
-            "hi",
-            "hi there",
-            "yes please",
-            "one two three four",
-            "one two three four five",
-            "a slightly longer reply, hopefully fine",
-            "This is a multi-clause sentence. It has two parts.",
-            "really really really really really long prompt with lots of words just to be sure",
-        ];
-        for &p in prompts {
-            let prepared = prepare_pocket_prompt(p).expect("non-empty");
-            if let Some(extra) = build_generation_extra(&prepared) {
-                if let Some(v) = extra.get("frames_after_eos") {
-                    let n = v.as_i64().expect("frames_after_eos should be int");
-                    assert!(
-                        n >= SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT as i64,
-                        "prompt {p:?} set frames_after_eos={n}, below upstream default of {SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT}"
-                    );
-                }
-            }
-        }
-    }
-
-    #[test]
-    fn short_prompt_max_frames_is_below_upstream_default() {
-        // Sanity: the override only ever *lowers* the cap, never raises it.
-        const {
-            assert!(SHORT_PROMPT_MAX_FRAMES < SHERPA_ONNX_MAX_FRAMES_DEFAULT);
-        }
-        // …and is still large enough for a one-to-four-word reply. At Mimi's
-        // 12.5 Hz frame rate, 100 frames = 8 s, which is roomy.
-        const {
-            assert!(SHORT_PROMPT_MAX_FRAMES >= 50, "would risk truncation");
-        }
-    }
-}
+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,
+};
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 876c2d688b..37eb3533f6 100644
--- a/desktop/src-tauri/src/huddle/state.rs
+++ b/desktop/src-tauri/src/huddle/state.rs
@@ -5,7 +5,7 @@
 
 use serde::{Deserialize, Serialize};
 use std::sync::{
-    atomic::{AtomicBool, AtomicU64},
+    atomic::{AtomicBool, AtomicU64, Ordering},
     Arc, Mutex,
 };
 
@@ -80,6 +80,15 @@ pub struct HuddleState {
     pub tts_enabled: bool,
     /// Whether STT transcript posting is enabled for this huddle.
     pub transcription_enabled: bool,
+    /// Whether the user has explicitly used the transcription control in this
+    /// huddle. Agent presence may auto-enable transcription only while this is
+    /// false, so membership refreshes never undo an explicit user choice.
+    ///
+    /// This is backend-only session state: keeping it in `HuddleState` makes it
+    /// survive frontend remounts and audio reconnects, while huddle teardown
+    /// resets it for the next session.
+    #[serde(skip)]
+    pub transcription_user_controlled: bool,
     /// Shared flag: true while TTS is playing audio.
     /// Shared with the STT pipeline for barge-in / echo gating.
     #[serde(skip)]
@@ -103,6 +112,10 @@ pub struct HuddleState {
     /// Used to throttle the refresh in check_pipeline_hotstart to every 15 s.
     #[serde(skip)]
     pub last_agent_refresh: Option<std::time::Instant>,
+    /// Monotonic identity for a local huddle lifetime. Unlike transcript
+    /// generation, this changes only when a new start/join attempt begins.
+    #[serde(skip)]
+    pub huddle_generation: u64,
     /// Session generation — incremented on every teardown. The transcription
     /// task captures this at spawn time and checks before each POST. If the
     /// generation has changed, the task silently drops the transcript.
@@ -157,11 +170,13 @@ impl Clone for HuddleState {
             is_creator: self.is_creator,
             tts_enabled: self.tts_enabled,
             transcription_enabled: self.transcription_enabled,
+            transcription_user_controlled: self.transcription_user_controlled,
             tts_active: Arc::clone(&self.tts_active),
             tts_cancel: Arc::clone(&self.tts_cancel),
             tts_starting: Arc::clone(&self.tts_starting),
             stt_starting: Arc::clone(&self.stt_starting),
             last_agent_refresh: self.last_agent_refresh,
+            huddle_generation: self.huddle_generation,
             session_generation: Arc::clone(&self.session_generation),
             voice_input_mode: self.voice_input_mode.clone(),
             ptt_active: Arc::clone(&self.ptt_active),
@@ -184,11 +199,13 @@ impl Default for HuddleState {
             is_creator: false,
             tts_enabled: true,
             transcription_enabled: false,
+            transcription_user_controlled: false,
             tts_active: Arc::new(AtomicBool::new(false)),
             tts_cancel: Arc::new(AtomicBool::new(false)),
             tts_starting: Arc::new(AtomicBool::new(false)),
             stt_starting: Arc::new(AtomicBool::new(false)),
             last_agent_refresh: None,
+            huddle_generation: 0,
             session_generation: Arc::new(AtomicU64::new(0)),
             voice_input_mode: VoiceInputMode::default(),
             ptt_active: Arc::new(AtomicBool::new(false)),
@@ -197,13 +214,247 @@ impl Default for HuddleState {
 }
 
 impl HuddleState {
+    /// Begin a new local huddle lifetime and return its identity.
+    pub(crate) fn begin_huddle_lifetime(&mut self) -> u64 {
+        self.huddle_generation = self.huddle_generation.wrapping_add(1);
+        self.huddle_generation
+    }
+
+    pub(crate) fn owns_huddle_lifetime(&self, huddle_generation: u64, phase: HuddlePhase) -> bool {
+        self.huddle_generation == huddle_generation && self.phase == phase
+    }
+
+    /// Whether an async result still belongs to the active huddle that
+    /// initiated it. The channel id is the huddle-session identity; transcript
+    /// generation changes within the same huddle must not invalidate it.
+    pub(crate) fn is_current_huddle(
+        &self,
+        ephemeral_channel_id: &str,
+        huddle_generation: u64,
+    ) -> bool {
+        matches!(self.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            && self.ephemeral_channel_id.as_deref() == Some(ephemeral_channel_id)
+            && self.huddle_generation == huddle_generation
+    }
+
+    /// Whether an STT construction still belongs to the current transcript
+    /// generation within the active huddle.
+    pub(crate) fn is_current_transcription_generation(
+        &self,
+        ephemeral_channel_id: &str,
+        huddle_generation: u64,
+        session_generation: u64,
+    ) -> bool {
+        self.is_current_huddle(ephemeral_channel_id, huddle_generation)
+            && self.session_generation.load(Ordering::Acquire) == session_generation
+    }
+
+    /// Invalidate in-flight transcription work and give the next constructor a
+    /// fresh sentinel that stale constructors cannot clear.
+    pub(crate) fn invalidate_transcription_pipeline(&mut self) {
+        self.session_generation.fetch_add(1, Ordering::Release);
+        self.stt_starting = Arc::new(AtomicBool::new(false));
+    }
+
+    /// Record an explicit transcription choice made through the existing user
+    /// control. Later agent membership refreshes must preserve this choice.
+    pub(crate) fn set_transcription_enabled_by_user(&mut self, enabled: bool) {
+        self.transcription_enabled = enabled;
+        self.transcription_user_controlled = true;
+    }
+
+    /// Enable transcription when an agent is present and the user has not
+    /// explicitly chosen a transcription state for this huddle.
+    ///
+    /// Returns true only for the transition from disabled to enabled, allowing
+    /// callers to start models/pipelines and emit state exactly once. Removing
+    /// the last agent deliberately leaves the current state unchanged.
+    pub(crate) fn maybe_auto_enable_transcription_for_agents(&mut self) -> bool {
+        let has_agent = !self
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .is_empty();
+        if has_agent && !self.transcription_user_controlled && !self.transcription_enabled {
+            self.transcription_enabled = true;
+            return true;
+        }
+        false
+    }
+
     /// Reset to default state while preserving the session generation counter.
     /// Used by start_huddle rollback, join_huddle rollback, and teardown_huddle
     /// to invalidate in-flight transcription tasks without losing the generation.
     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;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::atomic::Ordering;
+
+    use super::HuddleState;
+
+    fn set_agents(state: &HuddleState, agents: &[&str]) {
+        *state
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|error| error.into_inner()) =
+            agents.iter().map(|agent| (*agent).to_owned()).collect();
+    }
+
+    #[test]
+    fn first_agent_auto_enables_transcription_once() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+        assert!(state.transcription_enabled);
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+    }
+
+    #[test]
+    fn explicit_user_disable_is_not_undone_by_agent_presence() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+
+        state.set_transcription_enabled_by_user(false);
+
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+        assert!(!state.transcription_enabled);
+    }
+
+    #[test]
+    fn last_agent_leaving_preserves_current_transcription_state() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+
+        set_agents(&state, &[]);
+
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+        assert!(state.transcription_enabled);
+    }
+
+    #[test]
+    fn clone_preserves_user_control_across_frontend_state_reads() {
+        let mut state = HuddleState::default();
+        state.set_transcription_enabled_by_user(false);
+
+        let mut clone = state.clone();
+        set_agents(&clone, &["agent"]);
+
+        assert!(clone.transcription_user_controlled);
+        assert!(!clone.maybe_auto_enable_transcription_for_agents());
+    }
+
+    #[test]
+    fn stale_huddle_identity_is_rejected_after_replacement() {
+        let mut state = HuddleState {
+            phase: super::HuddlePhase::Active,
+            ephemeral_channel_id: Some("huddle-a".to_owned()),
+            ..HuddleState::default()
+        };
+        let huddle_generation = state.begin_huddle_lifetime();
+        let generation = state.session_generation.load(Ordering::Acquire);
+        assert!(state.is_current_huddle("huddle-a", huddle_generation));
+        assert!(state.is_current_transcription_generation(
+            "huddle-a",
+            huddle_generation,
+            generation
+        ));
+
+        state.session_generation.fetch_add(1, Ordering::Release);
+        assert!(state.is_current_huddle("huddle-a", huddle_generation));
+        assert!(!state.is_current_transcription_generation(
+            "huddle-a",
+            huddle_generation,
+            generation
+        ));
+
+        state.ephemeral_channel_id = Some("huddle-b".to_owned());
+
+        assert!(!state.is_current_huddle("huddle-a", huddle_generation));
+    }
+
+    #[test]
+    fn same_channel_rejoin_gets_a_new_huddle_lifetime() {
+        let mut state = HuddleState {
+            phase: super::HuddlePhase::Active,
+            ephemeral_channel_id: Some("huddle".to_owned()),
+            ..HuddleState::default()
+        };
+        let first_generation = state.begin_huddle_lifetime();
+        state.reset_preserving_generation();
+        state.phase = super::HuddlePhase::Active;
+        state.ephemeral_channel_id = Some("huddle".to_owned());
+        let second_generation = state.begin_huddle_lifetime();
+
+        assert_ne!(first_generation, second_generation);
+        assert!(!state.is_current_huddle("huddle", first_generation));
+        assert!(state.is_current_huddle("huddle", second_generation));
+    }
+
+    #[test]
+    fn superseded_create_cannot_commit_or_reset_replacement_lifetime() {
+        let mut state = HuddleState::default();
+        let first_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Creating;
+        assert!(state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Creating));
+
+        state.reset_preserving_generation();
+        let replacement_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Creating;
+
+        assert!(!state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Creating));
+        assert!(state.owns_huddle_lifetime(replacement_generation, super::HuddlePhase::Creating));
+    }
+
+    #[test]
+    fn superseded_join_cannot_commit_replacement_lifetime() {
+        let mut state = HuddleState::default();
+        let first_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Connecting;
+
+        state.reset_preserving_generation();
+        let replacement_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Connecting;
+
+        assert!(!state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Connecting));
+        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();
+        let stale_sentinel = std::sync::Arc::clone(&state.stt_starting);
+        stale_sentinel.store(true, Ordering::Release);
+
+        state.invalidate_transcription_pipeline();
+        state.stt_starting.store(true, Ordering::Release);
+        stale_sentinel.store(false, Ordering::Release);
+
+        assert!(state.stt_starting.load(Ordering::Acquire));
     }
 }
 
diff --git a/desktop/src-tauri/src/huddle/transcription.rs b/desktop/src-tauri/src/huddle/transcription.rs
index 0d752c1de7..5962f57cf4 100644
--- a/desktop/src-tauri/src/huddle/transcription.rs
+++ b/desktop/src-tauri/src/huddle/transcription.rs
@@ -1,5 +1,3 @@
-use std::sync::atomic::Ordering;
-
 use tauri::State;
 
 use crate::app_state::AppState;
@@ -15,10 +13,12 @@ use super::{models, pipeline::maybe_start_stt_pipeline};
 pub async fn start_stt_pipeline(state: State<'_, AppState>) -> Result<(), String> {
     let ephemeral_channel_id = {
         let mut hs = state.huddle()?;
-        hs.transcription_enabled = true;
-        hs.ephemeral_channel_id
+        let ephemeral_channel_id = hs
+            .ephemeral_channel_id
             .clone()
-            .ok_or("no active huddle — start or join a huddle first")?
+            .ok_or("no active huddle — start or join a huddle first")?;
+        hs.set_transcription_enabled_by_user(true);
+        ephemeral_channel_id
     };
 
     match maybe_start_stt_pipeline(&state, &ephemeral_channel_id).await {
@@ -41,14 +41,17 @@ pub async fn set_huddle_transcription_enabled(
 ) -> Result<(), String> {
     let (ephemeral_channel_id, old_stt) = {
         let mut hs = state.huddle()?;
-        hs.transcription_enabled = enabled;
+        let ephemeral_channel_id = hs
+            .ephemeral_channel_id
+            .clone()
+            .ok_or("no active huddle — start or join a huddle first")?;
+        hs.set_transcription_enabled_by_user(enabled);
 
         if enabled {
-            (hs.ephemeral_channel_id.clone(), None)
+            (ephemeral_channel_id, None)
         } else {
-            hs.session_generation.fetch_add(1, Ordering::Release);
-            hs.stt_starting.store(false, Ordering::Release);
-            (hs.ephemeral_channel_id.clone(), hs.stt_pipeline.take())
+            hs.invalidate_transcription_pipeline();
+            (ephemeral_channel_id, hs.stt_pipeline.take())
         }
     };
 
@@ -58,12 +61,10 @@ pub async fn set_huddle_transcription_enabled(
     drop(old_stt);
 
     if enabled {
-        let eph_id =
-            ephemeral_channel_id.ok_or("no active huddle — start or join a huddle first")?;
         if let Some(manager) = models::global_model_manager() {
             manager.start_stt_download(state.http_client.clone());
         }
-        if let Err(e) = maybe_start_stt_pipeline(&state, &eph_id).await {
+        if let Err(e) = maybe_start_stt_pipeline(&state, &ephemeral_channel_id).await {
             eprintln!("buzz-desktop: STT transcript start failed: {e}");
         }
     }
diff --git a/desktop/src-tauri/src/huddle/tts.rs b/desktop/src-tauri/src/huddle/tts.rs
index 63a435cd8e..c03589f9fe 100644
--- a/desktop/src-tauri/src/huddle/tts.rs
+++ b/desktop/src-tauri/src/huddle/tts.rs
@@ -35,10 +35,11 @@
 //! can gate microphone input while the agent is speaking.
 
 use std::{
+    collections::VecDeque,
     num::NonZero,
     path::PathBuf,
     sync::{
-        atomic::{AtomicBool, Ordering},
+        atomic::{AtomicBool, AtomicU64, Ordering},
         mpsc::{self, SyncSender},
         Arc, Mutex, MutexGuard, PoisonError,
     },
@@ -46,9 +47,21 @@ use std::{
     time::Duration,
 };
 
-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::*;
+
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 /// Maximum number of queued text items.
@@ -56,15 +69,15 @@ 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 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;
@@ -73,9 +86,8 @@ const SYNTH_STEPS: usize = 1;
 ///
 /// Applied only at the *end* of each synthesised sentence to eliminate the
 /// click that would otherwise occur when a non-zero waveform terminates
-/// abruptly. **No fade-in is applied** — see `apply_fade_out` for the
-/// rationale and `examples/pocket_onset_probe.rs` for the measurement that
-/// motivated removing the leading fade.
+/// abruptly. **No fade-in is applied** — see `apply_fade_out` for why preserving
+/// the leading waveform is important.
 const FADE_OUT_SAMPLES: usize = (SAMPLE_RATE as f64 * 0.008) as usize;
 
 /// Length of the zero-sample cushion prepended before each synthesized
@@ -101,19 +113,17 @@ const SENTENCE_LEAD_IN_SAMPLES: usize = (SAMPLE_RATE as f64 * 0.020) as usize;
 /// names chunk stitching as the reliability lever). Our previous
 /// sentence-per-call path created ~2–4× more seams than upstream.
 ///
-/// We don't ship the SentencePiece tokenizer, so 50 tokens is approximated
-/// with a character budget. The bundled 4k-entry vocab averages ~4 chars per
-/// token, but usage-weighted English text leans on short common tokens, so
-/// the effective ratio is ~2–4 chars/token and 200 chars ≈ 60–100 tokens —
-/// modestly above upstream's 50, deliberately: erring large means fewer
-/// seams, and even ~100 tokens is far below the model's 500-LM-step (~40 s)
-/// ceiling. Do not shrink this budget to chase an exact 50-token match.
+/// This character budget performs only coarse sentence packing. The April
+/// engine applies its SentencePiece tokenizer afterward and refines every
+/// result at the bundle's exact 50-token boundary.
 const MAX_CHUNK_CHARS: usize = 200;
 
 /// Silence inserted between sentences by the TTS pipeline (seconds).
 /// Injected as a silent buffer between each synthesized sentence chunk.
 const INTER_SENTENCE_SILENCE: f32 = 0.1;
 
+type WorkerControlState = (Arc<AtomicBool>, Arc<AtomicBool>, WorkerCancelSignals);
+
 // ── Public pipeline handle ────────────────────────────────────────────────────
 
 /// Handle to the running TTS pipeline.
@@ -122,7 +132,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>,
@@ -132,38 +142,25 @@ 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>,
+    /// 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.
-    ///
-    /// `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.
+    /// Spawn the TTS pipeline thread with a manifest-backed voice name.
     ///
-    /// `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>,
@@ -171,37 +168,56 @@ impl TtsPipeline {
         voice: &str,
         output_device: Option<String>,
     ) -> 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.
 
         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 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),
+                    ),
                     output_device,
+                    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,
+            voice_change_ack,
             thread: Some(handle),
         })
     }
@@ -211,14 +227,59 @@ impl TtsPipeline {
     /// 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}")
-        })
+        self.text_tx
+            .try_send(QueuedText {
+                generation: self.voice_generation.load(Ordering::Acquire),
+                route_id: 0,
+                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),
+        }
+    }
+
+    /// 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);
     }
 
@@ -244,40 +305,52 @@ 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>,
+    startup_tx: mpsc::SyncSender<Result<(), String>>,
 ) {
+    let (selected_voice, voice_generation, voice_change_ack) = voice_state;
+    let (tts_active, shutdown, cancel_signals) = 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;
+    }
 
     // ── 2b. Warmup inference ─────────────────────────────────────────────────
     // The first ONNX inference on any session is significantly slower than
@@ -285,15 +358,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"
             ),
         }
     }
@@ -306,8 +374,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;
         }
     };
@@ -315,14 +384,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;
         }
     };
@@ -346,10 +415,22 @@ 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 ───────────────────────────────────────────
     //
@@ -377,6 +458,7 @@ fn tts_worker(
     let monitor = {
         let player = Arc::clone(&player);
         let cancel = Arc::clone(&cancel);
+        let voice_cancel = Arc::clone(&voice_cancel);
         let tts_active = Arc::clone(&tts_active);
         let stop = Arc::clone(&monitor_stop);
         let player_ops = Arc::clone(&player_ops);
@@ -384,12 +466,12 @@ fn tts_worker(
             .name("tts-barge-in-monitor".into())
             .spawn(move || {
                 while !stop.load(Ordering::Acquire) {
-                    if cancel.load(Ordering::Acquire) {
+                    if cancel.load(Ordering::Acquire) || voice_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) {
+                        if cancel.load(Ordering::Acquire) || voice_cancel.load(Ordering::Acquire) {
                             // clear() pauses the persistent player; play()
                             // un-pauses (see handle_cancel_or_shutdown).
                             // Idempotent — safe to repeat every tick until
@@ -423,13 +505,45 @@ 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| {
+        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;
+        }
+        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 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) {
@@ -441,28 +555,47 @@ 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;
+        // Voice changes cancel the old utterance/queue and are observed here,
+        // before receiving subsequent text. A bad bundled asset falls back to
+        // Mary without discarding the already-warmed Pocket engine.
+        let voice_ready =
+            reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style);
+        acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+        if !voice_ready {
+            continue;
+        }
+
+        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);
+                        eprintln!(
+                            "buzz-desktop: tts stage=player status=drained route_id={last_route_id}"
+                        );
+                        first_append = true;
+                    }
+                    continue;
                 }
-                continue;
-            }
-            Err(mpsc::RecvTimeoutError::Disconnected) => break,
-        };
+                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) {
@@ -471,6 +604,30 @@ fn tts_worker(
             first_append = true;
             continue;
         }
+        let Some(queued_text) = queued_text else {
+            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;
+        }
+        let raw_text = queued_text.text;
+        let route_id = queued_text.route_id;
+        eprintln!("buzz-desktop: tts stage=synthesis status=started route_id={route_id}");
+
+        // The selected voice can change while this worker is blocked in
+        // recv_timeout. Reconcile again after receipt so the first message
+        // queued after an unpublished pipeline is installed cannot use the
+        // voice captured when construction began.
+        if !reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style) {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=failed reason=voice_unavailable route_id={route_id}"
+            );
+            continue;
+        }
 
         // If playback already drained while we were waiting for this item,
         // the agent is silent — release the mic gate BEFORE preprocessing/
@@ -482,37 +639,53 @@ fn tts_worker(
         // stays set across items.)
         if player.empty() && !first_append {
             tts_active.store(false, Ordering::Release);
+            eprintln!("buzz-desktop: tts stage=player status=drained route_id={last_route_id}");
             first_append = true;
         }
 
         // 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;
         }
 
         // Split into sentences, then group into synthesis chunks: the first
         // sentence stays alone (fast time-to-first-audio), the rest pack
-        // greedily up to MAX_CHUNK_CHARS. Each chunk is one `generate()`
-        // call; playback of chunk N overlaps synthesis of chunk N+1
-        // (lookahead pipelining). Grouping matches upstream's ~50-token
-        // chunking and halves the exposed prosody seams on multi-sentence
-        // replies — see MAX_CHUNK_CHARS.
+        // greedily up to MAX_CHUNK_CHARS. Playback of each model unit overlaps
+        // synthesis of the next one. The Pocket engine applies its exact
+        // 50-token split; keeping those units within one playback chunk avoids
+        // adding fades and pauses at token-only boundaries.
         let sentences: Vec<String> = split_sentences(&text)
             .into_iter()
             .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;
+        }
 
-        for chunk in &chunks {
+        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;
             }
 
@@ -521,53 +694,113 @@ fn tts_worker(
                 continue;
             }
 
-            match engine.synth_chunk(text, "en", &style, SYNTH_STEPS) {
-                Ok(samples) if !samples.is_empty() => {
-                    let mut audio = clamp_to_full_scale(samples);
-                    // Fade-out only — fading-in would attenuate the consonant
-                    // onset (see `apply_fade_out` docstring + the
-                    // 2026-05-18 "first little sound is missing" regression).
-                    apply_fade_out(&mut audio);
-
-                    // Build one contiguous buffer per synthesized sentence:
-                    // lead-in cushion + audio + trailing gap. Keeping this as
-                    // a single rodio source preserves the original queue/drain
-                    // semantics (one append per sentence) while still giving
-                    // every chunk a quiet device warm-up window.
-                    let buf =
-                        build_sentence_append_buffer(&mut first_append, audio, silence_buf_len);
-
-                    // 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).
+            let model_chunks = match engine.split_text_into_chunks(text) {
+                Ok(model_chunks) => model_chunks,
+                Err(_) => {
+                    eprintln!(
+                        "buzz-desktop: tts stage=synthesis status=failed reason=chunking route_id={route_id}"
+                    );
+                    synthesis_outcome = "failed";
+                    break 'playback_chunks;
+                }
+            };
+            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, &voice_cancel),
+                    &shutdown,
+                    &tts_active,
+                    (&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 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() => {
+                        if let Some(prepared) = playback_audio.push(
+                            samples,
+                            chunk_index,
+                            &mut first_append,
+                            silence_buf_len,
+                            player.empty(),
+                        ) {
+                            if !append_audio(prepared, route_id) {
+                                first_append = true;
+                                synthesis_outcome = "cancelled";
+                                break 'playback_chunks;
+                            }
+                            appended_audio = true;
+                            last_route_id = route_id;
+                        }
+                    }
+                    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;
                     }
-                    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}");
+            }
+            if let Some(prepared) =
+                playback_audio.finish(&mut first_append, silence_buf_len, player.empty())
+            {
+                if !append_audio(prepared, route_id) {
+                    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) {
@@ -582,6 +815,7 @@ fn tts_worker(
         let _ = handle.join();
     }
 
+    finish_voice_change_ack(&voice_change_ack);
     tts_active.store(false, Ordering::Release);
 }
 
@@ -595,13 +829,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();
@@ -609,7 +851,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
@@ -622,11 +886,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;
@@ -644,135 +903,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: Pocket TTS already emits speech-level audio
-/// (peaks 0.4–0.97, RMS ≈ −20 dBFS across varied sentences — measured by
-/// `examples/pocket_clip_probe`), matching the kyutai reference pipeline,
-/// which applies no output scaling. Two earlier gain stages were both
-/// regressions against that baseline: per-sentence peak normalization caused
-/// level pumping between sentences, and the fixed 9.3× gain that replaced it
-/// was calibrated on a single anomalously-quiet bench utterance (peak 0.076)
-/// and clipped 13–34% of samples on real speech ("blown out", 2026-06-12).
-/// The clamp alone remains as the 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
-///
-/// An earlier revision (pre 2026-05) symmetrically faded *in* over the same
-/// 8 ms window. That swallowed the leading consonant attack on every
-/// sentence — Pocket TTS produces real audio energy inside the first
-/// millisecond (RMS ≈ 0.02, peak ≈ 0.03 measured across four prompts in
-/// `examples/pocket_onset_probe.rs`), and a linear 0→1 ramp over 192 samples
-/// scales those onset samples by ≤50 % for the first ~4 ms. The result was
-/// the "first little sound or two is missing" regression heard on
-/// 2026-05-18.
-///
-/// 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 the single buffer appended to the rodio `Player` for one synthesised
-/// sentence.
-///
-/// Every sentence chunk 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.
-///
-/// `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,
-) -> Vec<f32> {
-    if *first_append {
-        *first_append = false;
-    }
-
-    let trailing_silence_len = silence_buf_len.saturating_sub(SENTENCE_LEAD_IN_SAMPLES);
-    let mut buf = Vec::with_capacity(SENTENCE_LEAD_IN_SAMPLES + audio.len() + trailing_silence_len);
-    buf.extend(std::iter::repeat_n(0.0_f32, SENTENCE_LEAD_IN_SAMPLES));
-    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 unsplit — Pocket TTS handles long
-/// single sentences fine (the ceiling is the 500-LM-step default), it's the
-/// *seams* we're minimizing.
-///
-/// 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_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_settings.rs b/desktop/src-tauri/src/huddle/tts_settings.rs
new file mode 100644
index 0000000000..1b378af823
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_settings.rs
@@ -0,0 +1,971 @@
+//! 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())
+}
+
+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,
+        )?;
+        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_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 7887f8bbdb..1908b096b1 100644
--- a/desktop/src-tauri/src/huddle/tts_tests.rs
+++ b/desktop/src-tauri/src/huddle/tts_tests.rs
@@ -9,6 +9,9 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
 
+#[path = "tts_tests/token_split.rs"]
+mod token_split;
+
 // ── Remote interrupt tracker ──────────────────────────────────────────────
 //
 // Models the per-peer frame counting logic in the recv task of
@@ -785,16 +788,6 @@ fn apply_fade_out_single_sample() {
     assert_eq!(samples[0], 1.0);
 }
 
-/// Sanity-check the per-sentence cushion length: 20 ms at 24 kHz must
-/// land at exactly 480 samples. This is a const computation, so the
-/// real value of this test is documenting *why* 20 ms was chosen — it
-/// covers a typical CoreAudio buffer turnover (256–1024 samples)
-/// without being audible as user-facing latency.
-#[test]
-fn sentence_lead_in_is_sane() {
-    assert_eq!(SENTENCE_LEAD_IN_SAMPLES, 480, "20 ms × 24 kHz");
-}
-
 // ── build_sentence_append_buffer tests ───────────────────────────────────
 
 /// REGRESSION: every chunk needs an onset cushion; synthesized chunks
@@ -812,6 +805,8 @@ fn lead_in_pad_is_present_for_every_sentence_chunk() {
             &mut first,
             vec![0.5_f32; SENTENCE_AUDIO_LEN],
             SILENCE_BUF_LEN,
+            true,
+            true,
         );
 
         assert_eq!(buf.len(), SENTENCE_AUDIO_LEN + SILENCE_BUF_LEN);
@@ -840,11 +835,11 @@ fn lead_in_pad_is_present_for_every_sentence_chunk() {
 #[test]
 fn build_sentence_append_buffer_flips_first_append() {
     let mut first = true;
-    let _ = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let _ = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(!first, "first call must flip the flag");
 
     // Subsequent call: still has a per-sentence lead-in, flag stays false.
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
     assert!(!first);
 }
@@ -853,7 +848,7 @@ fn build_sentence_append_buffer_flips_first_append() {
 #[test]
 fn first_sentence_leading_silence_is_exactly_lead_in() {
     let mut first = true;
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
     assert_eq!(buf[SENTENCE_LEAD_IN_SAMPLES], 0.5);
 }
@@ -863,8 +858,10 @@ fn first_sentence_leading_silence_is_exactly_lead_in() {
 fn sentence_gap_budget_is_preserved() {
     let mut first = true;
     let silence_buf_len = 2400;
-    let first_buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len);
-    let second_buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len);
+    let first_buf =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, true);
+    let second_buf =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, true);
 
     let first_tail = &first_buf[SENTENCE_LEAD_IN_SAMPLES + 100..];
     let second_lead = &second_buf[..SENTENCE_LEAD_IN_SAMPLES];
@@ -877,7 +874,7 @@ fn sentence_gap_budget_is_preserved() {
 #[test]
 fn sentence_append_buffer_is_one_contiguous_source() {
     let mut first = true;
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
 
     assert_eq!(buf.len(), 2400 + 100);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
@@ -949,9 +946,8 @@ fn chunk_grouping_packs_up_to_budget_then_spills() {
     assert_eq!(chunks[2], d);
 }
 
-/// A single sentence longer than the budget is passed through unsplit —
-/// long single sentences are fine (the LM cap bounds runaway); only seams
-/// are being minimized.
+/// A single sentence longer than the coarse budget is passed through here;
+/// the loaded April engine subsequently enforces its exact 50-token limit.
 #[test]
 fn chunk_grouping_oversized_sentence_passes_through() {
     let long = "word ".repeat(60).trim_end().to_string() + ".";
diff --git a/desktop/src-tauri/src/huddle/tts_tests/token_split.rs b/desktop/src-tauri/src/huddle/tts_tests/token_split.rs
new file mode 100644
index 0000000000..b9249c9afc
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_tests/token_split.rs
@@ -0,0 +1,24 @@
+use super::*;
+
+/// The onset cushion covers 20 ms at the production sample rate.
+#[test]
+fn sentence_lead_in_is_sane() {
+    assert_eq!(SENTENCE_LEAD_IN_SAMPLES, 480, "20 ms × 24 kHz");
+}
+
+/// Model-token splits remain contiguous: only the playback chunk as a whole
+/// receives its onset cushion and trailing sentence gap.
+#[test]
+fn token_split_units_do_not_add_sentence_boundary_padding() {
+    let mut first = true;
+    let silence_buf_len = 2400;
+    let first_unit =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, false);
+    let last_unit =
+        build_sentence_append_buffer(&mut first, vec![0.25; 100], silence_buf_len, false, true);
+
+    assert_eq!(first_unit.len(), SENTENCE_LEAD_IN_SAMPLES + 100);
+    assert_eq!(first_unit.last(), Some(&0.5));
+    assert_eq!(last_unit.first(), Some(&0.25));
+    assert_eq!(first_unit.len() + last_unit.len(), 200 + silence_buf_len);
+}
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..45662c9921
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs
@@ -0,0 +1,385 @@
+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)),
+        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,
+            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,
+            text: "old message".to_string(),
+        },
+        QueuedText {
+            generation: voice_generation.load(Ordering::Acquire),
+            route_id: 3,
+            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,
+        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,
+        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,
+        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),
+    };
+    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, "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));
+}
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..81b33672d3
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_transition.rs
@@ -0,0 +1,206 @@
+use std::{
+    collections::VecDeque,
+    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 CancelTextState<'a> = (
+    &'a mpsc::Receiver<QueuedText>,
+    &'a mut VecDeque<QueuedText>,
+    &'a mut Option<QueuedText>,
+);
+pub(super) type CancelSignals<'a> = (&'a AtomicBool, &'a AtomicBool);
+
+#[derive(Debug)]
+pub(super) struct QueuedText {
+    pub(super) generation: u64,
+    pub(super) route_id: u64,
+    pub(super) text: String,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct TtsTextSender {
+    pub(super) text_tx: SyncSender<QueuedText>,
+    pub(super) generation: u64,
+}
+
+impl TtsTextSender {
+    pub(crate) fn send(&self, route_id: u64, text: String) -> Result<(), String> {
+        self.text_tx
+            .send(QueuedText {
+                generation: self.generation,
+                route_id,
+                text,
+            })
+            .map_err(|error| error.to_string())
+    }
+}
+
+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 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}");
+}
diff --git a/desktop/src-tauri/src/identity_storage.rs b/desktop/src-tauri/src/identity_storage.rs
new file mode 100644
index 0000000000..b39c1a0331
--- /dev/null
+++ b/desktop/src-tauri/src/identity_storage.rs
@@ -0,0 +1,62 @@
+use nostr::Keys;
+
+use crate::app_state::AppState;
+
+/// Durable location of the active human identity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub(crate) enum IdentityStorage {
+    Ephemeral = 0,
+    SystemKeyring = 1,
+    LocalFile = 2,
+    Environment = 3,
+}
+
+impl IdentityStorage {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ephemeral => "ephemeral",
+            Self::SystemKeyring => "system-keyring",
+            Self::LocalFile => "local-file",
+            Self::Environment => "environment",
+        }
+    }
+
+    fn from_u8(value: u8) -> Self {
+        match value {
+            1 => Self::SystemKeyring,
+            2 => Self::LocalFile,
+            3 => Self::Environment,
+            _ => Self::Ephemeral,
+        }
+    }
+}
+
+impl AppState {
+    pub(crate) fn identity_storage(&self) -> IdentityStorage {
+        IdentityStorage::from_u8(
+            self.identity_storage
+                .load(std::sync::atomic::Ordering::Acquire),
+        )
+    }
+
+    pub(crate) fn set_identity_storage(&self, storage: IdentityStorage) {
+        self.identity_storage
+            .store(storage as u8, std::sync::atomic::Ordering::Release);
+    }
+}
+
+/// Recovery state produced by identity resolution.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RecoveryState {
+    None,
+    Lost,
+    KeyringLocked,
+}
+
+/// Identity and persistence metadata produced by startup resolution.
+pub(crate) struct ResolvedIdentity {
+    pub(crate) keys: Keys,
+    pub(crate) recovery: RecoveryState,
+    pub(crate) storage: IdentityStorage,
+}
diff --git a/desktop/src-tauri/src/key_backup.rs b/desktop/src-tauri/src/key_backup.rs
new file mode 100644
index 0000000000..f97bf95a67
--- /dev/null
+++ b/desktop/src-tauri/src/key_backup.rs
@@ -0,0 +1,234 @@
+//! NIP-49 encrypted local key backup.
+//!
+//! Creates a password-encrypted `ncryptsec` backup of the user's identity key
+//! for a user-selected local file. The blob is **local-only by contract**: it must
+//! never be transmitted to a relay on any path. That contract is enforced at
+//! runtime by [`crate::egress_guard`] (wired into every relay event-body
+//! constructor and the native websocket send loop) and structurally by the
+//! source-allowlist scan in this module's tests.
+//!
+//! Creation decrypt-verifies the fresh blob against the live identity before
+//! returning it. Portable copies use atomic, owner-only file writes.
+
+use nostr::nips::nip49::{EncryptedSecretKey, KeySecurity};
+use nostr::{FromBech32, Keys, ToBech32};
+
+/// Bech32 prefix of NIP-49 encrypted secret keys. Import routing is
+/// case-insensitive because bech32 permits all-uppercase encodings.
+pub const NCRYPTSEC_HRP: &str = "ncryptsec1";
+
+/// scrypt cost for new backups (2^18 — Gossip's desktop default, ~256 MiB).
+/// The blob self-describes its cost, so this can be raised later without
+/// breaking existing backups.
+pub const BACKUP_LOG_N: u8 = 18;
+
+/// Highest scrypt cost accepted when decrypting an untrusted backup.
+///
+/// NIP-49 intentionally leaves `log_n` client-selected. Capping it at the tier
+/// Buzz itself emits keeps generated and upstream-compatible lower-cost backups
+/// readable without allowing a crafted payload to request unbounded memory
+/// before password authentication.
+pub const MAX_VERIFY_LOG_N: u8 = BACKUP_LOG_N;
+
+/// Filename of the app-managed canonical backup inside the app data dir.
+pub const BACKUP_FILE_NAME: &str = "identity.ncryptsec";
+
+/// Default number of words in a generated backup passphrase. Three words
+/// from a 1296-word list ≈ 31 bits of entropy before the scrypt work factor.
+pub const DEFAULT_PASSPHRASE_WORDS: usize = 3;
+
+/// Bounds for the generator's word-count control. At the lower bound a draw
+/// can fall below [`MIN_PASSPHRASE_LEN`] (three 3-char words), so
+/// [`generate_passphrase`] re-draws until the phrase meets the minimum.
+pub const MIN_PASSPHRASE_WORDS: usize = 3;
+pub const MAX_PASSPHRASE_WORDS: usize = 10;
+
+/// EFF short wordlist 2.0 (1296 words, one per line).
+const WORDLIST: &str = include_str!("assets/eff_short_wordlist_2_0.txt");
+
+/// Minimum length for a user-chosen passphrase.
+pub const MIN_PASSPHRASE_LEN: usize = 12;
+
+/// Encrypt the identity secret key under `password` and verify the result.
+///
+/// Returns the bech32 `ncryptsec1…` string. The fresh blob is decrypted and
+/// its derived pubkey compared to the live identity **before** returning, so
+/// a returned blob is always provably recoverable with the same password.
+pub fn create_backup_blob(keys: &Keys, password: &str, log_n: u8) -> Result<String, String> {
+    let secret_key = keys.secret_key();
+
+    let encrypted = EncryptedSecretKey::new(secret_key, password, log_n, KeySecurity::Unknown)
+        .map_err(|e| format!("encrypt key backup: {e}"))?;
+
+    let ncryptsec = encrypted
+        .to_bech32()
+        .map_err(|e| format!("encode ncryptsec: {e}"))?;
+
+    // Integrity check: decrypt the fresh blob and confirm it recovers the
+    // exact live identity. A corrupted or mis-encrypted blob must never be
+    // shown to the user as a "backup". This is the second, deliberate KDF
+    // invocation of the one-artifact-per-action contract.
+    verify_backup_blob(&ncryptsec, password, &keys.public_key())?;
+
+    Ok(ncryptsec)
+}
+
+/// Decrypt `ncryptsec` with `password` and assert it recovers a key whose
+/// public key equals `expected_pubkey`.
+pub fn verify_backup_blob(
+    ncryptsec: &str,
+    password: &str,
+    expected_pubkey: &nostr::PublicKey,
+) -> Result<(), String> {
+    let encrypted = parse_ncryptsec(ncryptsec)?;
+    let recovered = encrypted
+        .decrypt(password)
+        .map_err(|e| format!("verify key backup (decrypt): {e}"))?;
+    let recovered_keys = Keys::new(recovered);
+    if recovered_keys.public_key() != *expected_pubkey {
+        return Err("verify key backup: decrypted key does not match identity".to_string());
+    }
+    Ok(())
+}
+
+/// Parse a bech32 `ncryptsec1…` string, rejecting anything that is not a
+/// structurally valid NIP-49 payload.
+pub fn parse_ncryptsec(input: &str) -> Result<EncryptedSecretKey, String> {
+    EncryptedSecretKey::from_bech32(input.trim()).map_err(|e| format!("invalid ncryptsec: {e}"))
+}
+
+/// Decrypt an `ncryptsec1…` string with `password` into identity keys.
+pub fn decrypt_ncryptsec(input: &str, password: &str) -> Result<Keys, String> {
+    let encrypted = parse_ncryptsec(input)?;
+    let log_n = encrypted.log_n();
+    if log_n > MAX_VERIFY_LOG_N {
+        return Err(format!(
+            "unsupported backup KDF cost: log_n {log_n} exceeds maximum {MAX_VERIFY_LOG_N}"
+        ));
+    }
+    let secret_key = encrypted
+        .decrypt(password)
+        .map_err(|_| "wrong backup password or damaged key backup".to_string())?;
+    Ok(Keys::new(secret_key))
+}
+
+/// Recover identity keys from either an encrypted NIP-49 backup or the raw
+/// nsec/hex formats accepted before encrypted imports were added.
+pub fn recover_keys_from_input(input: &str, password: Option<&str>) -> Result<Keys, String> {
+    let trimmed = input.trim();
+    let is_ncryptsec = trimmed
+        .get(..NCRYPTSEC_HRP.len())
+        .is_some_and(|prefix| prefix.eq_ignore_ascii_case(NCRYPTSEC_HRP));
+
+    if is_ncryptsec {
+        let password = password.ok_or_else(|| "key backup requires a password".to_string())?;
+        decrypt_ncryptsec(trimmed, password)
+    } else {
+        Keys::parse(trimmed).map_err(|e| format!("Invalid private key: {e}"))
+    }
+}
+
+/// Path of the canonical app-managed backup file.
+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
+/// `app_state::save_key_file`.
+pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
+    use atomic_write_file::AtomicWriteFile;
+    use std::io::Write;
+
+    let mut file = AtomicWriteFile::open(path)
+        .map_err(|e| format!("open backup file for atomic write: {e}"))?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(std::fs::Permissions::from_mode(0o600))
+            .map_err(|e| format!("set backup file permissions: {e}"))?;
+    }
+
+    file.write_all(ncryptsec.as_bytes())
+        .map_err(|e| format!("write backup file: {e}"))?;
+    file.commit()
+        .map_err(|e| format!("commit backup file: {e}"))?;
+
+    // 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}"))?;
+    if on_disk != ncryptsec {
+        return Err("backup file verification failed: on-disk bytes differ".to_string());
+    }
+
+    Ok(())
+}
+
+/// Delete the app-managed backup if present. Missing files are already clean.
+pub fn delete_backup_file(data_dir: &std::path::Path) -> Result<(), String> {
+    let path = backup_file_path(data_dir);
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("delete stale backup file: {e}")),
+    }
+}
+
+/// Remove the app-managed backup only when an import changes identities.
+pub fn cleanup_stale_backup(
+    previous: &nostr::PublicKey,
+    new: &nostr::PublicKey,
+    data_dir: &std::path::Path,
+) -> Result<(), String> {
+    if previous != new {
+        delete_backup_file(data_dir)?;
+    }
+    Ok(())
+}
+
+/// Generate a passphrase of `word_count` EFF short-wordlist words joined by
+/// `separator`, using OS entropy.
+///
+/// `word_count` is clamped to `MIN_PASSPHRASE_WORDS..=MAX_PASSPHRASE_WORDS`.
+/// Because a low-word-count draw can land under [`MIN_PASSPHRASE_LEN`]
+/// (e.g. three 3-char words), whole phrases below the minimum are rejected
+/// and re-drawn — the result always passes the same length gate applied to
+/// user-chosen passphrases. Uses rejection sampling for a uniform
+/// distribution over the 1296 words.
+pub fn generate_passphrase(word_count: usize, separator: &str) -> Result<String, String> {
+    let word_count = word_count.clamp(MIN_PASSPHRASE_WORDS, MAX_PASSPHRASE_WORDS);
+    let words: Vec<&str> = WORDLIST.lines().filter(|l| !l.is_empty()).collect();
+    if words.len() != 1296 {
+        return Err(format!(
+            "wordlist corrupted: expected 1296 words, found {}",
+            words.len()
+        ));
+    }
+
+    // At 3 words the under-length probability per draw is small, so a few
+    // attempts always suffice; the cap only guards against a logic bug
+    // becoming an infinite loop.
+    for _ in 0..128 {
+        let mut chosen: Vec<&str> = Vec::with_capacity(word_count);
+        while chosen.len() < word_count {
+            let mut buf = [0u8; 2];
+            getrandom::getrandom(&mut buf).map_err(|e| format!("entropy source: {e}"))?;
+            let value = u16::from_le_bytes(buf);
+            // Rejection sampling: accept only values below the largest
+            // multiple of 1296 that fits in u16 (65536 - 65536 % 1296 = 64800).
+            if value < 64800 {
+                chosen.push(words[(value as usize) % 1296]);
+            }
+        }
+        let phrase = chosen.join(separator);
+        if phrase.chars().count() >= MIN_PASSPHRASE_LEN {
+            return Ok(phrase);
+        }
+    }
+    Err("could not generate a passphrase meeting the minimum length".to_string())
+}
+
+#[cfg(test)]
+#[path = "key_backup_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/key_backup_tests.rs b/desktop/src-tauri/src/key_backup_tests.rs
new file mode 100644
index 0000000000..b9713201e1
--- /dev/null
+++ b/desktop/src-tauri/src/key_backup_tests.rs
@@ -0,0 +1,230 @@
+use super::*;
+
+/// NIP-49 spec vector (same as rust-nostr's upstream test): decrypts with
+/// password "nostr" at our call sites.
+const SPEC_NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+const SPEC_SECRET_HEX: &str = "3501454135014541350145413501453fefb02227e449e57cf4d3a3ce05378683";
+
+/// Fast scrypt tier for tests. log_n 18 is exercised once in
+/// `round_trip_at_production_cost`.
+const FAST_LOG_N: u8 = 16;
+
+// ── Codec ─────────────────────────────────────────────────────────────────────
+
+#[test]
+fn spec_vector_decrypts_at_our_call_site() {
+    let keys = decrypt_ncryptsec(SPEC_NCRYPTSEC, "nostr").unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+}
+
+#[test]
+fn round_trip_fast_tier() {
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "correct horse battery", FAST_LOG_N).unwrap();
+    assert!(blob.starts_with("ncryptsec1"));
+    let recovered = decrypt_ncryptsec(&blob, "correct horse battery").unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn round_trip_at_production_cost() {
+    // One log_n 18 round trip: proves the production constant works end to
+    // end (slow — several seconds — but deliberate; see plan D5).
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "production cost tier check", BACKUP_LOG_N).unwrap();
+    let recovered = decrypt_ncryptsec(&blob, "production cost tier check").unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn wrong_password_is_a_friendly_error() {
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "right password", FAST_LOG_N).unwrap();
+    let err = decrypt_ncryptsec(&blob, "wrong password").unwrap_err();
+    assert_eq!(err, "wrong backup password or damaged key backup");
+}
+
+#[test]
+fn nfkc_cross_form_passphrase_round_trips() {
+    // "é" composed (U+00E9) vs decomposed (e + U+0301): NIP-49 mandates NFKC
+    // normalization, so a passphrase entered in either form must decrypt.
+    let keys = Keys::generate();
+    let composed = "caf\u{00e9} passphrase";
+    let decomposed = "cafe\u{0301} passphrase";
+    assert_ne!(composed, decomposed);
+    let blob = create_backup_blob(&keys, composed, FAST_LOG_N).unwrap();
+    let recovered = decrypt_ncryptsec(&blob, decomposed).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn parse_rejects_garbage_and_wrong_hrp() {
+    assert!(parse_ncryptsec("garbage").is_err());
+    assert!(parse_ncryptsec("").is_err());
+    // Valid bech32, wrong HRP (an nsec is not an encrypted backup).
+    let nsec = Keys::generate().secret_key().to_bech32().unwrap();
+    assert!(parse_ncryptsec(&nsec).is_err());
+    // Truncated blob.
+    assert!(parse_ncryptsec(&SPEC_NCRYPTSEC[..SPEC_NCRYPTSEC.len() - 10]).is_err());
+}
+
+#[test]
+fn verify_backup_blob_catches_pubkey_mismatch() {
+    // Corrupted-blob simulation: the blob decrypts fine but recovers a key
+    // that is not the live identity — verification must fail.
+    let other = Keys::generate();
+    let blob = create_backup_blob(&other, "some password", FAST_LOG_N).unwrap();
+    let live = Keys::generate();
+    let err = verify_backup_blob(&blob, "some password", &live.public_key()).unwrap_err();
+    assert!(err.contains("does not match identity"), "{err}");
+}
+
+// ── Import key recovery ───────────────────────────────────────────────────────
+
+#[test]
+fn recover_keys_ncryptsec_happy_path() {
+    let keys = recover_keys_from_input(&format!("  {SPEC_NCRYPTSEC}\n"), Some("nostr")).unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+}
+
+#[test]
+fn recover_keys_ncryptsec_requires_password() {
+    let err = recover_keys_from_input(SPEC_NCRYPTSEC, None).unwrap_err();
+    assert_eq!(err, "key backup requires a password");
+}
+
+#[test]
+fn recover_keys_ncryptsec_wrong_password() {
+    let err = recover_keys_from_input(SPEC_NCRYPTSEC, Some("wrong")).unwrap_err();
+    assert_eq!(err, "wrong backup password or damaged key backup");
+}
+
+#[test]
+fn recover_keys_uppercase_ncryptsec_classifies_as_encrypted() {
+    let upper = SPEC_NCRYPTSEC.to_ascii_uppercase();
+    assert_eq!(
+        recover_keys_from_input(&upper, None).unwrap_err(),
+        "key backup requires a password"
+    );
+    let keys = recover_keys_from_input(&upper, Some("nostr")).unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+
+    let mut mixed = SPEC_NCRYPTSEC.to_string();
+    mixed.replace_range(0..1, "N");
+    let err = recover_keys_from_input(&mixed, Some("nostr")).unwrap_err();
+    assert!(err.contains("invalid ncryptsec"), "{err}");
+}
+
+#[test]
+fn recover_keys_raw_nsec_path_unchanged() {
+    let keys = Keys::generate();
+    let nsec = keys.secret_key().to_bech32().unwrap();
+    let recovered = recover_keys_from_input(&nsec, Some("ignored")).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+    let recovered = recover_keys_from_input(&nsec, None).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+    assert!(recover_keys_from_input("garbage", None).is_err());
+}
+
+// ── File lifecycle ────────────────────────────────────────────────────────────
+
+#[test]
+fn write_backup_file_persists_0600_and_verifies() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+
+    let on_disk = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(on_disk, SPEC_NCRYPTSEC);
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode();
+        assert_eq!(mode & 0o777, 0o600, "backup file must be owner-only");
+    }
+}
+
+#[test]
+fn write_backup_file_overwrites_atomically() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, "ncryptsec1old").unwrap();
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    assert_eq!(std::fs::read_to_string(&path).unwrap(), SPEC_NCRYPTSEC);
+    // No leftover temp files from the atomic write.
+    let entries: Vec<_> = std::fs::read_dir(dir.path())
+        .unwrap()
+        .map(|e| e.unwrap().file_name())
+        .collect();
+    assert_eq!(entries, vec![std::ffi::OsString::from(BACKUP_FILE_NAME)]);
+}
+
+#[test]
+fn delete_backup_file_is_idempotent() {
+    let dir = tempfile::tempdir().unwrap();
+    delete_backup_file(dir.path()).unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    delete_backup_file(dir.path()).unwrap();
+    assert!(!path.exists());
+}
+
+#[test]
+fn cleanup_stale_backup_removes_only_on_identity_change() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    let a = Keys::generate().public_key();
+    let b = Keys::generate().public_key();
+
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    cleanup_stale_backup(&a, &a, dir.path()).unwrap();
+    assert!(path.exists(), "same identity must keep the backup");
+
+    cleanup_stale_backup(&a, &b, dir.path()).unwrap();
+    assert!(
+        !path.exists(),
+        "identity change must remove the stale backup"
+    );
+}
+
+#[test]
+fn generated_passphrase_respects_word_count_and_separator() {
+    let words: std::collections::HashSet<&str> =
+        WORDLIST.lines().filter(|l| !l.is_empty()).collect();
+    assert_eq!(words.len(), 1296, "EFF short wordlist 2.0 has 1296 words");
+
+    for (count, separator) in [(3, "-"), (4, "-"), (6, " "), (5, "."), (10, "")] {
+        let phrase = generate_passphrase(count, separator).unwrap();
+        if separator.is_empty() {
+            // No separator to split on; length gate below still applies.
+        } else {
+            let parts: Vec<&str> = phrase.split(separator).collect();
+            assert_eq!(parts.len(), count);
+            for w in &parts {
+                assert!(words.contains(w), "unknown word {w:?}");
+            }
+        }
+        assert!(phrase.chars().count() >= MIN_PASSPHRASE_LEN);
+    }
+}
+
+#[test]
+fn generated_passphrase_clamps_word_count() {
+    // 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);
+    // Above the ceiling: clamped down to MAX_PASSPHRASE_WORDS.
+    let phrase = generate_passphrase(50, "-").unwrap();
+    assert_eq!(phrase.split('-').count(), MAX_PASSPHRASE_WORDS);
+}
+
+#[test]
+fn generated_passphrases_are_not_repeated() {
+    // 3 words × ~10.3 bits each — a collision across 8 draws would indicate a
+    // broken entropy source, not bad luck.
+    let mut seen = std::collections::HashSet::new();
+    for _ in 0..8 {
+        assert!(seen.insert(generate_passphrase(DEFAULT_PASSPHRASE_WORDS, "-").unwrap()));
+    }
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index c005d511e6..c4b733e3e0 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -4,9 +4,12 @@ mod archive;
 mod builderlab;
 mod commands;
 mod deep_link;
+mod egress_guard;
 mod event_sync;
 mod events;
 mod huddle;
+mod identity_storage;
+mod key_backup;
 mod linux_media;
 mod managed_agents;
 mod media_proxy;
@@ -62,10 +65,7 @@ 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 std::sync::{atomic::AtomicBool, atomic::Ordering, Arc};
 use tauri::{Emitter, Manager, RunEvent};
 #[cfg(target_os = "macos")]
 use tauri::{Listener, WindowEvent};
@@ -464,6 +464,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
@@ -669,6 +681,10 @@ pub fn run() {
             title_bar_double_click,
             get_identity,
             get_nsec,
+            generate_backup_passphrase,
+            create_ncryptsec_backup,
+            verify_ncryptsec_backup,
+            save_ncryptsec_copy,
             import_identity,
             persist_current_identity,
             get_profile,
@@ -832,6 +848,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 +892,12 @@ 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,
             speak_agent_message,
             add_agent_to_huddle,
             check_pipeline_hotstart,
diff --git a/desktop/src-tauri/src/linux_media.rs b/desktop/src-tauri/src/linux_media.rs
index c768e15422..240e2f8a77 100644
--- a/desktop/src-tauri/src/linux_media.rs
+++ b/desktop/src-tauri/src/linux_media.rs
@@ -22,17 +22,22 @@
 //! which is the backend WebKitGTK media capture is reliable on.
 
 /// The origin Tauri serves the packaged app from on Linux.
+/// Consumed only by linux-gated [`enable_media_capture`]; kept compiling on all
+/// platforms so the unit tests run everywhere.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 const PROD_ORIGIN: &str = "tauri://localhost";
 
 /// The Vite dev-server origin (`devUrl` in `tauri.conf.json`, `strictPort`
 /// 1420 in `vite.config.ts`). Only trusted in debug builds.
 #[cfg(debug_assertions)]
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 const DEV_ORIGIN: &str = "http://localhost:1420";
 
 /// Whether `uri` (the webview's current document URI) is a trusted app origin
 /// allowed to use mic/camera. Matches the origin exactly or as a path prefix so
 /// `tauri://localhost.evil.com` and `http://localhost:14200` do not slip
 /// through. Pure and platform-independent so it can be unit-tested everywhere.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 fn is_trusted_media_origin(uri: &str) -> bool {
     fn matches(uri: &str, origin: &str) -> bool {
         uri == origin
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 2a72af92d7..5debae41cb 100644
--- a/desktop/src-tauri/src/managed_agents/backend.rs
+++ b/desktop/src-tauri/src/managed_agents/backend.rs
@@ -286,7 +286,7 @@ fn redact_secrets(s: &str) -> String {
 /// (would match every short token in normal log output). Entries are
 /// applied in decreasing length order so superstrings get scrubbed before
 /// substrings — protects against partial overlap leaks.
-fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
+pub(crate) fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
     let mut result = s.to_string();
 
     // Extras: longest first to avoid partial-overlap leaks. We use
@@ -305,9 +305,23 @@ fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
 
     // Then prefix-based scrubbing. This loop *can* re-scan because each
     // replacement shortens the buffer past the matched prefix — the
-    // replacement marker `[REDACTED]` does not contain `nsec1` or
-    // `sprt_tok_`, so progress is guaranteed.
-    for prefix in &["nsec1", "sprt_tok_"] {
+    // replacement marker `[REDACTED]` contains none of these prefixes, so
+    // progress is guaranteed. Any prefix added here must preserve that.
+    //
+    // GitHub tokens are recognised by shape as well as by variable name: a
+    // token reaches output from outside our environment too — embedded in a
+    // git remote URL an installer echoes, say — where no name-based rule can
+    // see it.
+    for prefix in &[
+        "nsec1",
+        "sprt_tok_",
+        "ghp_",
+        "gho_",
+        "ghu_",
+        "ghs_",
+        "ghr_",
+        "github_pat_",
+    ] {
         while let Some(pos) = result.find(prefix) {
             let end = result[pos..]
                 .find(|c: char| c.is_whitespace() || c == '"' || c == '\'')
@@ -563,6 +577,29 @@ mod tests {
         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)`
diff --git a/desktop/src-tauri/src/managed_agents/discovery.rs b/desktop/src-tauri/src/managed_agents/discovery.rs
index c8a85be34a..8d1b8a5013 100644
--- a/desktop/src-tauri/src/managed_agents/discovery.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery.rs
@@ -10,8 +10,11 @@ use crate::managed_agents::{
     HarnessSource,
 };
 
+mod presets;
 mod runtime_metadata;
 
+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";
@@ -1436,225 +1439,6 @@ pub(crate) fn discover_acp_runtime_availability(runtime_id: &str) -> Option<AcpA
         .map(|partial| partial.entry.availability)
 }
 
-// ── Tier-2 preset harnesses ────────────────────────────────────────────────
-//
-// Static data for well-known ACP harnesses that have bundled logos and
-// verified command/args. PATH-probed at discovery time (Detected badge);
-// not editable or deletable by users. Logos are bundled assets referenced
-// by id in the frontend `RUNTIME_LOGOS` map.
-
-struct PresetHarness {
-    id: &'static str,
-    label: &'static str,
-    command: &'static str,
-    args: &'static [&'static str],
-    install_instructions_url: &'static str,
-    install_hint: &'static str,
-    /// Vendor CLI the ACP command wraps, when the preset is an adapter
-    /// (e.g. Amp's `amp-acp` wraps the separately-installed `amp` CLI).
-    /// Consulted only when the adapter is absent, so `AdapterMissing`
-    /// replaces the misleading `NotInstalled` when the CLI is present but
-    /// the adapter is not. Deliberately NOT fed through the builtins'
-    /// full `classify_runtime` predicate: that would flip
-    /// adapter-present/CLI-absent from today's `Available` to `CliMissing`
-    /// (unselectable), and presets carry a single flat `install_hint`, so
-    /// the `CliMissing` copy would tell the user to install the adapter
-    /// they already have. `None` when the command IS the vendor CLI.
-    underlying_cli: Option<&'static str>,
-}
-
-/// Build the catalog entry for one preset harness through an injectable
-/// resolver — the seam the preset loop consumes and tests bind.
-///
-/// Availability consumes only the adapter-missing arm of the builtin
-/// predicate: adapter presence alone decides `Available` (exactly today's
-/// behavior — an `amp-acp` without `amp` stays selectable), and
-/// `underlying_cli` is consulted only when the adapter is absent, to
-/// distinguish `AdapterMissing` (vendor CLI present) from `NotInstalled`
-/// (neither found). See the `underlying_cli` field doc for why the full
-/// `classify_runtime` predicate is deliberately not used here.
-fn preset_catalog_entry(
-    def: &PresetHarness,
-    resolve: impl Fn(&str) -> Option<PathBuf>,
-) -> AcpRuntimeCatalogEntry {
-    let (availability, command, binary_path) = match resolve(def.command) {
-        Some(path) => (
-            AcpAvailabilityStatus::Available,
-            Some(def.command.to_string()),
-            Some(path.display().to_string()),
-        ),
-        None => {
-            let underlying_cli_found = def
-                .underlying_cli
-                .map(|cli| resolve(cli).is_some())
-                .unwrap_or(false);
-            if underlying_cli_found {
-                (AcpAvailabilityStatus::AdapterMissing, None, None)
-            } else {
-                (AcpAvailabilityStatus::NotInstalled, None, None)
-            }
-        }
-    };
-    let underlying_cli_path = def
-        .underlying_cli
-        .and_then(resolve)
-        .map(|p| p.display().to_string());
-
-    let default_args = normalize_agent_args(
-        def.command,
-        def.args.iter().map(|s| s.to_string()).collect(),
-    );
-
-    AcpRuntimeCatalogEntry {
-        id: def.id.to_string(),
-        label: def.label.to_string(),
-        // No remote URL — all preset icons are bundled assets.
-        avatar_url: String::new(),
-        availability,
-        command,
-        binary_path,
-        default_args,
-        mcp_command: None,
-        model_env_var: None,
-        provider_env_var: None,
-        thinking_env_var: None,
-        install_hint: def.install_hint.to_string(),
-        install_instructions_url: def.install_instructions_url.to_string(),
-        can_auto_install: false,
-        // Kept false even for adapter presets: presets carry one flat
-        // install_hint (the adapter's), so the requiresExternalCli
-        // "CLI is missing" wording would pair the wrong noun with it.
-        // The builtin path, with per-availability hints, is the only
-        // consumer of the true case.
-        requires_external_cli: false,
-        underlying_cli_path,
-        node_required: false,
-        auth_status: AuthStatus::NotApplicable,
-        login_hint: None,
-        source: HarnessSource::Preset,
-        // Preset entries have static, non-editable env; definition_env is empty.
-        definition_env: Default::default(),
-    }
-}
-
-const PRESET_HARNESSES: &[PresetHarness] = &[
-    PresetHarness {
-        id: "cursor",
-        label: "Cursor",
-        command: "cursor-agent",
-        args: &["acp"],
-        install_instructions_url: "https://cursor.com/downloads",
-        install_hint: "Buzz talks to Cursor through the cursor-agent CLI's ACP mode.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "omp",
-        label: "Oh My Pi",
-        command: "omp",
-        args: &["acp"],
-        install_instructions_url: "https://github.com/can1357/oh-my-pi",
-        install_hint: "Buzz talks to Oh My Pi through its CLI's ACP mode (omp acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "grok",
-        label: "Grok Build",
-        command: "grok",
-        args: &["agent", "--always-approve", "stdio"],
-        install_instructions_url: "https://build.x.ai/docs",
-        install_hint: "Buzz talks to Grok Build through its CLI's agent stdio mode.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "opencode",
-        label: "OpenCode",
-        command: "opencode",
-        args: &["acp"],
-        install_instructions_url: "https://opencode.ai/docs",
-        install_hint: "Buzz talks to OpenCode through its CLI's ACP mode (opencode acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "kimi",
-        label: "Kimi Code",
-        command: "kimi",
-        args: &["acp"],
-        install_instructions_url: "https://kimi.ai/download",
-        install_hint: "Buzz talks to Kimi Code through its CLI's ACP mode (kimi acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "amp",
-        label: "Amp",
-        command: "amp-acp",
-        args: &[],
-        install_instructions_url: "https://github.com/tao12345666333/amp-acp",
-        install_hint: "Buzz talks to the Amp CLI through the amp-acp adapter. Follow the setup guide to install the adapter so the amp-acp command is on your PATH.",
-        underlying_cli: Some("amp"),
-    },
-    PresetHarness {
-        id: "hermes",
-        label: "Hermes Agent",
-        command: "hermes-acp",
-        args: &[],
-        install_instructions_url: "https://hermes-agent.nousresearch.com",
-        install_hint: "Buzz talks to Hermes Agent through its hermes-acp command.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "openclaw",
-        label: "OpenClaw",
-        command: "openclaw",
-        args: &["acp"],
-        install_instructions_url: "https://docs.openclaw.ai/start/getting-started",
-        install_hint: "Buzz talks to OpenClaw through its ACP mode (openclaw acp), which relies on the OpenClaw Gateway daemon. Follow the setup guide to install both.\n\n\
-            ⚠️  Execution-locus note: `openclaw acp` runs tools inside the \
-            OpenClaw Gateway daemon, not in the Desktop process. \
-            Desktop-injected BUZZ_* env vars are visible to the `openclaw` \
-            harness process itself, but do NOT automatically reach the \
-            Gateway's execution environment. If your tools or agent logic \
-            needs BUZZ_* credentials at execution time, set them on the \
-            Gateway's own environment separately.",
-        underlying_cli: None,
-    },
-];
-
-/// Return the static preset harness definitions as `HarnessDefinition` values.
-///
-/// Used by `warm_harness_registry_from_dir` to seed the loaded-harness registry
-/// at startup before the frontend triggers a full discovery run.
-pub(crate) fn preset_harness_definitions(
-) -> Vec<crate::managed_agents::custom_harnesses::HarnessDefinition> {
-    PRESET_HARNESSES
-        .iter()
-        .map(
-            |p| crate::managed_agents::custom_harnesses::HarnessDefinition {
-                id: p.id.to_string(),
-                label: p.label.to_string(),
-                command: p.command.to_string(),
-                args: p.args.iter().map(|s| s.to_string()).collect(),
-                env: std::collections::BTreeMap::new(),
-                install_instructions_url: p.install_instructions_url.to_string(),
-                install_hint: p.install_hint.to_string(),
-            },
-        )
-        .collect()
-}
-
-/// Return the static slice of preset harness IDs.
-///
-/// Used by `check_id_collision` in `custom_harnesses` to derive the reserved-ID
-/// set from the single source of truth (`PRESET_HARNESSES`) rather than a
-/// hand-maintained copy.  Adding a preset automatically reserves its ID.
-pub(crate) fn preset_harness_ids() -> &'static [&'static str] {
-    // `PRESET_HARNESSES` is `'static`; we project its `id` fields.
-    // Computed once via OnceLock to avoid repeated allocations on hot paths.
-    use std::sync::OnceLock;
-    static IDS: OnceLock<Vec<&'static str>> = OnceLock::new();
-    IDS.get_or_init(|| PRESET_HARNESSES.iter().map(|p| p.id).collect())
-        .as_slice()
-}
-
 /// Discover all ACP runtimes, optionally merging user-defined custom harnesses
 /// from `custom_harnesses_dir`.
 ///
diff --git a/desktop/src-tauri/src/managed_agents/discovery/presets.rs b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
new file mode 100644
index 0000000000..3622b21c4a
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
@@ -0,0 +1,335 @@
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use crate::managed_agents::{
+    AcpAvailabilityStatus, AcpRuntimeCatalogEntry, AuthStatus, HarnessSource,
+};
+
+use super::normalize_agent_args;
+
+/// Static data for a well-known tier-2 ACP harness.
+pub(super) struct PresetHarness {
+    pub(super) id: &'static str,
+    label: &'static str,
+    command: &'static str,
+    args: &'static [&'static str],
+    install_instructions_url: &'static str,
+    install_hint: &'static str,
+    /// Vendor CLI the ACP command wraps, when the preset is an adapter.
+    ///
+    /// Consulted only when the adapter is absent, so `AdapterMissing` replaces
+    /// `NotInstalled` when the CLI is present but the adapter is not. `None`
+    /// when the command is itself the vendor CLI.
+    underlying_cli: Option<&'static str>,
+}
+
+/// Build one preset catalog entry through an injectable command resolver.
+pub(super) fn preset_catalog_entry(
+    def: &PresetHarness,
+    resolve: impl Fn(&str) -> Option<PathBuf>,
+) -> AcpRuntimeCatalogEntry {
+    let (availability, command, binary_path) = match resolve(def.command) {
+        Some(path) => (
+            AcpAvailabilityStatus::Available,
+            Some(def.command.to_string()),
+            Some(path.display().to_string()),
+        ),
+        None => {
+            let underlying_cli_found = def
+                .underlying_cli
+                .map(|cli| resolve(cli).is_some())
+                .unwrap_or(false);
+            if underlying_cli_found {
+                (AcpAvailabilityStatus::AdapterMissing, None, None)
+            } else {
+                (AcpAvailabilityStatus::NotInstalled, None, None)
+            }
+        }
+    };
+    let underlying_cli_path = def
+        .underlying_cli
+        .and_then(resolve)
+        .map(|path| path.display().to_string());
+
+    AcpRuntimeCatalogEntry {
+        id: def.id.to_string(),
+        label: def.label.to_string(),
+        // No remote URL — all preset icons are bundled assets.
+        avatar_url: String::new(),
+        availability,
+        command,
+        binary_path,
+        default_args: normalize_agent_args(
+            def.command,
+            def.args.iter().map(|arg| arg.to_string()).collect(),
+        ),
+        mcp_command: None,
+        model_env_var: None,
+        provider_env_var: None,
+        thinking_env_var: None,
+        install_hint: def.install_hint.to_string(),
+        install_instructions_url: def.install_instructions_url.to_string(),
+        can_auto_install: false,
+        // Presets carry one flat install hint, so builtin external-CLI copy
+        // would name the wrong missing component for adapter presets.
+        requires_external_cli: false,
+        underlying_cli_path,
+        node_required: false,
+        auth_status: AuthStatus::NotApplicable,
+        login_hint: None,
+        source: HarnessSource::Preset,
+        definition_env: Default::default(),
+    }
+}
+
+pub(super) const PRESET_HARNESSES: &[PresetHarness] = &[
+    PresetHarness {
+        id: "devin",
+        label: "Devin",
+        command: "devin",
+        args: &["acp"],
+        install_instructions_url: "https://docs.devin.ai/cli",
+        install_hint: "Buzz talks to Devin through the official Devin CLI's ACP mode (devin acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "cursor",
+        label: "Cursor",
+        command: "cursor-agent",
+        args: &["acp"],
+        install_instructions_url: "https://cursor.com/downloads",
+        install_hint: "Buzz talks to Cursor through the cursor-agent CLI's ACP mode.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "omp",
+        label: "Oh My Pi",
+        command: "omp",
+        args: &["acp"],
+        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,
+    },
+    PresetHarness {
+        id: "grok",
+        label: "Grok Build",
+        command: "grok",
+        args: &["agent", "--always-approve", "stdio"],
+        install_instructions_url: "https://build.x.ai/docs",
+        install_hint: "Buzz talks to Grok Build through its CLI's agent stdio mode.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "opencode",
+        label: "OpenCode",
+        command: "opencode",
+        args: &["acp"],
+        install_instructions_url: "https://opencode.ai/docs",
+        install_hint: "Buzz talks to OpenCode through its CLI's ACP mode (opencode acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "kimi",
+        label: "Kimi Code",
+        command: "kimi",
+        args: &["acp"],
+        install_instructions_url: "https://kimi.ai/download",
+        install_hint: "Buzz talks to Kimi Code through its CLI's ACP mode (kimi acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "amp",
+        label: "Amp",
+        command: "amp-acp",
+        args: &[],
+        install_instructions_url: "https://github.com/tao12345666333/amp-acp",
+        install_hint: "Buzz talks to the Amp CLI through the amp-acp adapter. Follow the setup guide to install the adapter so the amp-acp command is on your PATH.",
+        underlying_cli: Some("amp"),
+    },
+    PresetHarness {
+        id: "hermes",
+        label: "Hermes Agent",
+        command: "hermes-acp",
+        args: &[],
+        install_instructions_url: "https://hermes-agent.nousresearch.com",
+        install_hint: "Buzz talks to Hermes Agent through its hermes-acp command.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "openclaw",
+        label: "OpenClaw",
+        command: "openclaw",
+        args: &["acp"],
+        install_instructions_url: "https://docs.openclaw.ai/start/getting-started",
+        install_hint: "Buzz talks to OpenClaw through its ACP mode (openclaw acp), which relies on the OpenClaw Gateway daemon. Follow the setup guide to install both.\n\n\
+            ⚠️  Execution-locus note: `openclaw acp` runs tools inside the \
+            OpenClaw Gateway daemon, not in the Desktop process. \
+            Desktop-injected BUZZ_* env vars are visible to the `openclaw` \
+            harness process itself, but do NOT automatically reach the \
+            Gateway's execution environment. If your tools or agent logic \
+            needs BUZZ_* credentials at execution time, set them on the \
+            Gateway's own environment separately.",
+        underlying_cli: None,
+    },
+];
+
+/// Return preset definitions for the spawn/readiness registry.
+pub(crate) fn preset_harness_definitions(
+) -> Vec<crate::managed_agents::custom_harnesses::HarnessDefinition> {
+    PRESET_HARNESSES
+        .iter()
+        .map(
+            |preset| crate::managed_agents::custom_harnesses::HarnessDefinition {
+                id: preset.id.to_string(),
+                label: preset.label.to_string(),
+                command: preset.command.to_string(),
+                args: preset.args.iter().map(|arg| arg.to_string()).collect(),
+                env: Default::default(),
+                install_instructions_url: preset.install_instructions_url.to_string(),
+                install_hint: preset.install_hint.to_string(),
+            },
+        )
+        .collect()
+}
+
+/// Return preset IDs from the catalog's single source of truth.
+pub(crate) fn preset_harness_ids() -> &'static [&'static str] {
+    static IDS: OnceLock<Vec<&'static str>> = OnceLock::new();
+    IDS.get_or_init(|| PRESET_HARNESSES.iter().map(|preset| preset.id).collect())
+        .as_slice()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use crate::managed_agents::{AcpAvailabilityStatus, AuthStatus, HarnessSource};
+
+    use super::{preset_catalog_entry, PresetHarness, PRESET_HARNESSES};
+
+    /// Amp-shaped preset: an ACP adapter wrapping a separately installed CLI.
+    const ADAPTER_PRESET: PresetHarness = PresetHarness {
+        id: "amp-test",
+        label: "Amp Test",
+        command: "amp-acp",
+        args: &[],
+        install_instructions_url: "https://example.com/install",
+        install_hint: "Install the amp-acp npm adapter.",
+        underlying_cli: Some("amp"),
+    };
+
+    #[test]
+    fn devin_preset_uses_official_native_acp_invocation() {
+        let preset = PRESET_HARNESSES
+            .iter()
+            .find(|preset| preset.id == "devin")
+            .expect("Devin preset should be present");
+
+        assert_eq!(preset.label, "Devin");
+        assert_eq!(preset.command, "devin");
+        assert_eq!(preset.args, &["acp"]);
+        assert_eq!(preset.underlying_cli, None);
+        assert_eq!(preset.install_instructions_url, "https://docs.devin.ai/cli");
+
+        let entry = preset_catalog_entry(preset, |command| {
+            (command == "devin").then(|| PathBuf::from("/usr/local/bin/devin"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("devin"));
+        assert_eq!(entry.default_args, vec!["acp"]);
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/devin"));
+        assert_eq!(entry.auth_status, AuthStatus::NotApplicable);
+        assert_eq!(entry.source, HarnessSource::Preset);
+
+        let missing_entry = preset_catalog_entry(preset, |_| None);
+        assert_eq!(
+            missing_entry.availability,
+            AcpAvailabilityStatus::NotInstalled
+        );
+        assert!(missing_entry.command.is_none());
+        assert_eq!(missing_entry.default_args, vec!["acp"]);
+    }
+
+    #[test]
+    fn devin_preset_is_exposed_in_the_runtime_catalog() {
+        use crate::managed_agents::custom_harnesses::registry_test_lock;
+
+        // Discovery touches process-global command-resolution and the loaded
+        // harness registry. Serialize with the other discovery tests.
+        let _path_guard = crate::managed_agents::lock_path_mutex();
+        let _registry_guard = registry_test_lock();
+
+        let entry = super::super::discover_acp_runtimes_from(None)
+            .into_iter()
+            .find(|entry| entry.id == "devin")
+            .expect("Devin preset should appear in the runtime catalog");
+
+        assert_eq!(entry.label, "Devin");
+        assert_eq!(entry.default_args, vec!["acp"]);
+        assert_eq!(entry.install_instructions_url, "https://docs.devin.ai/cli");
+        assert_eq!(entry.source, HarnessSource::Preset);
+    }
+
+    #[test]
+    fn adapter_missing_when_underlying_cli_present() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| {
+            (command == "amp").then(|| PathBuf::from("/usr/local/bin/amp"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::AdapterMissing);
+        assert!(entry.command.is_none());
+        assert!(entry.binary_path.is_none());
+        assert_eq!(
+            entry.underlying_cli_path.as_deref(),
+            Some("/usr/local/bin/amp")
+        );
+        assert!(!entry.requires_external_cli);
+        assert_eq!(entry.install_hint, "Install the amp-acp npm adapter.");
+    }
+
+    #[test]
+    fn not_installed_when_adapter_and_cli_are_missing() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |_| None);
+        assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
+        assert!(entry.underlying_cli_path.is_none());
+        assert!(!entry.requires_external_cli);
+    }
+
+    #[test]
+    fn available_when_adapter_and_cli_are_present() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| match command {
+            "amp-acp" => Some(PathBuf::from("/usr/local/bin/amp-acp")),
+            "amp" => Some(PathBuf::from("/usr/local/bin/amp")),
+            _ => None,
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("amp-acp"));
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
+        assert_eq!(
+            entry.underlying_cli_path.as_deref(),
+            Some("/usr/local/bin/amp")
+        );
+    }
+
+    #[test]
+    fn adapter_presence_is_enough_for_availability() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| {
+            (command == "amp-acp").then(|| PathBuf::from("/usr/local/bin/amp-acp"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("amp-acp"));
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
+        assert!(entry.underlying_cli_path.is_none());
+    }
+
+    #[test]
+    fn preset_without_underlying_cli_stays_simple() {
+        let preset = PresetHarness {
+            underlying_cli: None,
+            ..ADAPTER_PRESET
+        };
+        let entry = preset_catalog_entry(&preset, |_| None);
+        assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
+        assert!(!entry.requires_external_cli);
+        assert!(entry.underlying_cli_path.is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/discovery/tests.rs b/desktop/src-tauri/src/managed_agents/discovery/tests.rs
index 1b587dca0e..6fe6a77521 100644
--- a/desktop/src-tauri/src/managed_agents/discovery/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery/tests.rs
@@ -6,9 +6,9 @@ use super::{
     codex_adapter_is_outdated, create_time_agent_command_override, default_agent_command,
     effective_agent_command, find_nvm_default_bin, find_via_login_shell,
     is_login_shell_path_uninit, is_safe_nvm_tag, managed_agent_avatar_url, normalize_agent_args,
-    parse_semver_tag, preset_catalog_entry, probe_codex_acp_version, record_agent_command,
-    refresh_login_shell_path, try_record_agent_command, PresetHarness, BUZZ_AGENT_AVATAR_URL,
-    CLAUDE_CODE_AVATAR_URL, CODEX_AVATAR_URL, GOOSE_AVATAR_URL,
+    parse_semver_tag, probe_codex_acp_version, record_agent_command, refresh_login_shell_path,
+    try_record_agent_command, BUZZ_AGENT_AVATAR_URL, CLAUDE_CODE_AVATAR_URL, CODEX_AVATAR_URL,
+    GOOSE_AVATAR_URL,
 };
 use crate::managed_agents::AcpAvailabilityStatus;
 
@@ -187,90 +187,6 @@ fn classifies_cli_missing_when_adapter_found_but_cli_absent() {
     assert_eq!(path.as_deref(), Some("/opt/homebrew/bin/codex-acp"));
 }
 
-/// Amp-shaped preset: an ACP adapter (`amp-acp`) wrapping a separately
-/// installed vendor CLI (`amp`).
-const ADAPTER_PRESET: PresetHarness = PresetHarness {
-    id: "amp-test",
-    label: "Amp Test",
-    command: "amp-acp",
-    args: &[],
-    install_instructions_url: "https://example.com/install",
-    install_hint: "Install the amp-acp npm adapter.",
-    underlying_cli: Some("amp"),
-};
-
-#[test]
-fn preset_entry_adapter_missing_when_underlying_cli_present() {
-    // Vendor CLI resolves, adapter does not — the state Tyler's Amp
-    // hand-test hit. Must NOT degrade to the misleading NotInstalled.
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| {
-        (cmd == "amp").then(|| PathBuf::from("/usr/local/bin/amp"))
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::AdapterMissing);
-    assert!(entry.command.is_none());
-    assert!(entry.binary_path.is_none());
-    assert_eq!(
-        entry.underlying_cli_path.as_deref(),
-        Some("/usr/local/bin/amp")
-    );
-    assert!(!entry.requires_external_cli);
-    assert_eq!(entry.install_hint, "Install the amp-acp npm adapter.");
-}
-
-#[test]
-fn preset_entry_not_installed_when_both_missing() {
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |_| None);
-    assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
-    assert!(entry.underlying_cli_path.is_none());
-    assert!(!entry.requires_external_cli);
-}
-
-#[test]
-fn preset_entry_available_when_adapter_and_cli_present() {
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| match cmd {
-        "amp-acp" => Some(PathBuf::from("/usr/local/bin/amp-acp")),
-        "amp" => Some(PathBuf::from("/usr/local/bin/amp")),
-        _ => None,
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
-    assert_eq!(entry.command.as_deref(), Some("amp-acp"));
-    assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
-    assert_eq!(
-        entry.underlying_cli_path.as_deref(),
-        Some("/usr/local/bin/amp")
-    );
-}
-
-#[test]
-fn preset_entry_stays_available_when_adapter_present_but_cli_absent() {
-    // Wren's regression guard: today an `amp-acp` install without `amp`
-    // is Available and selectable. Feeding underlying_cli through the
-    // FULL classify_runtime predicate would flip this to CliMissing
-    // (unselectable, with backwards install copy) — the adapter-missing
-    // arm is the only one presets consume.
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| {
-        (cmd == "amp-acp").then(|| PathBuf::from("/usr/local/bin/amp-acp"))
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
-    assert_eq!(entry.command.as_deref(), Some("amp-acp"));
-    assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
-    assert!(entry.underlying_cli_path.is_none());
-}
-
-#[test]
-fn preset_entry_without_underlying_cli_stays_simple() {
-    // Most presets: the command IS the vendor CLI. No external-CLI flag,
-    // absent command means plain NotInstalled.
-    let preset = PresetHarness {
-        underlying_cli: None,
-        ..ADAPTER_PRESET
-    };
-    let entry = preset_catalog_entry(&preset, |_| None);
-    assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
-    assert!(!entry.requires_external_cli);
-    assert!(entry.underlying_cli_path.is_none());
-}
-
 fn persona_with_runtime(id: &str, runtime: Option<&str>) -> crate::managed_agents::AgentDefinition {
     crate::managed_agents::AgentDefinition {
         id: id.to_string(),
diff --git a/desktop/src-tauri/src/managed_agents/env_vars.rs b/desktop/src-tauri/src/managed_agents/env_vars.rs
index 592a5cbbd9..cf6ff52b4f 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars.rs
@@ -71,6 +71,7 @@ pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
     "BUZZ_ACP_AGENT_COMMAND",
     "BUZZ_ACP_AGENT_ARGS",
     "BUZZ_ACP_MCP_COMMAND",
+    "BUZZ_ACP_MCP_CONFIG",
     // 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.
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..26bf59118b 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
@@ -166,6 +166,7 @@ fn reserved_keys_include_code_execution_surface() {
         "BUZZ_ACP_AGENT_COMMAND",
         "BUZZ_ACP_AGENT_ARGS",
         "BUZZ_ACP_MCP_COMMAND",
+        "BUZZ_ACP_MCP_CONFIG",
     ] {
         assert!(is_reserved_env_key(key), "{key} should be reserved");
     }
diff --git a/desktop/src-tauri/src/managed_agents/mod.rs b/desktop/src-tauri/src/managed_agents/mod.rs
index be9b07cf11..772d707f27 100644
--- a/desktop/src-tauri/src/managed_agents/mod.rs
+++ b/desktop/src-tauri/src/managed_agents/mod.rs
@@ -1,6 +1,7 @@
 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 agent_env::{
     baked_build_env, build_buzz_agent_provider_defaults, discovery_env_with_baked_floor,
diff --git a/desktop/src-tauri/src/managed_agents/persona_events.rs b/desktop/src-tauri/src/managed_agents/persona_events.rs
index ea61a811db..6afc18a501 100644
--- a/desktop/src-tauri/src/managed_agents/persona_events.rs
+++ b/desktop/src-tauri/src/managed_agents/persona_events.rs
@@ -5,7 +5,7 @@
 
 use std::collections::BTreeMap;
 
-use buzz_core_pkg::kind::{persona_event_is_shared, KIND_PERSONA};
+use buzz_core_pkg::kind::{event_is_shared, KIND_PERSONA};
 use nostr::{EventBuilder, Kind, Tag};
 use serde::{Deserialize, Serialize};
 
@@ -192,7 +192,7 @@ pub fn persona_from_event(event: &nostr::Event) -> Result<AgentDefinition, Strin
         name_pool: content.name_pool,
         is_builtin: false,
         is_active: true,
-        shared: persona_event_is_shared(event),
+        shared: event_is_shared(event),
         source_team: None,
         source_team_persona_slug: Some(d_tag),
         catalog_source: None,
diff --git a/desktop/src-tauri/src/managed_agents/relay_mesh.rs b/desktop/src-tauri/src/managed_agents/relay_mesh.rs
index 327c106bc8..5c246feedc 100644
--- a/desktop/src-tauri/src/managed_agents/relay_mesh.rs
+++ b/desktop/src-tauri/src/managed_agents/relay_mesh.rs
@@ -47,6 +47,13 @@ pub fn apply_relay_mesh_env(
     // may deliberately choose a smaller cap or a different effort. This function
     // runs after those layers during readiness, so never clobber their values.
     insert_default_if_unset(env, "BUZZ_AGENT_MAX_OUTPUT_TOKENS", "4096");
+    // Mesh agents run on small local models, which are the ones most likely to
+    // do the work and then end the turn without publishing it — the failure the
+    // reply guard exists to catch. Everywhere else it stays opt-in and unset.
+    // A default, not policy: an explicit `0` from the agent/persona/global env
+    // survives (see `insert_default_if_unset`, and the copy-forward list in
+    // `relay_mesh_process_env` that preserves it through the spawn path).
+    insert_default_if_unset(env, "BUZZ_AGENT_REQUIRE_REPLY", "1");
     // Deliberately no BUZZ_AGENT_THINKING_EFFORT default: mesh translates
     // `reasoning_effort` into the chat template's `enable_thinking` flag, so any
     // value we pick overrides each model's own template default — and the right
@@ -80,7 +87,15 @@ pub fn relay_mesh_process_env(
     model: &str,
 ) -> std::collections::BTreeMap<String, String> {
     let mut env = std::collections::BTreeMap::new();
-    for key in ["BUZZ_AGENT_MAX_OUTPUT_TOKENS", "BUZZ_AGENT_THINKING_EFFORT"] {
+    for key in [
+        "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+        "BUZZ_AGENT_THINKING_EFFORT",
+        // Must be copied forward for the user's value to survive: this map is
+        // written onto the command *after* the layered user env, so a key absent
+        // here is re-defaulted by `apply_relay_mesh_env` below and an explicit
+        // `BUZZ_AGENT_REQUIRE_REPLY=0` would be silently overridden back to `1`.
+        "BUZZ_AGENT_REQUIRE_REPLY",
+    ] {
         if let Some(value) = effective_env.get(key) {
             env.insert(key.to_string(), value.clone());
         }
@@ -145,6 +160,78 @@ mod tests {
         );
     }
 
+    #[test]
+    fn native_provider_enables_reply_guard_by_default() {
+        let mut env = BTreeMap::new();
+        apply_relay_mesh_env(
+            &mut env,
+            Some(RELAY_MESH_PROVIDER_ID),
+            Some(RELAY_MESH_AUTO_MODEL_ID),
+        );
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("1"),
+            "mesh agents opt into the reply guard automatically"
+        );
+    }
+
+    #[test]
+    fn native_provider_preserves_explicit_reply_guard_opt_out() {
+        let mut env = BTreeMap::from([("BUZZ_AGENT_REQUIRE_REPLY".to_string(), "0".to_string())]);
+        apply_relay_mesh_env(
+            &mut env,
+            Some(RELAY_MESH_PROVIDER_ID),
+            Some(RELAY_MESH_AUTO_MODEL_ID),
+        );
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("0"),
+            "an explicit opt-out is a user decision, not a value to re-default"
+        );
+    }
+
+    #[test]
+    fn non_mesh_provider_leaves_reply_guard_unset() {
+        let mut env = BTreeMap::new();
+        apply_relay_mesh_env(&mut env, Some("anthropic"), Some("claude-haiku-4.5"));
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY"),
+            None,
+            "the guard stays opt-in everywhere except mesh"
+        );
+        assert!(env.is_empty(), "non-mesh providers get no mesh env at all");
+    }
+
+    /// The spawn path writes this map onto the command *after* the layered user
+    /// env, so an explicit opt-out only survives if it is copied forward. Without
+    /// the copy-forward, `apply_relay_mesh_env` re-defaults it to `1` here and
+    /// silently overrides the user at spawn while readiness still shows `0`.
+    #[test]
+    fn process_env_preserves_explicit_reply_guard_opt_out() {
+        let effective_env =
+            BTreeMap::from([("BUZZ_AGENT_REQUIRE_REPLY".to_string(), "0".to_string())]);
+
+        let env = relay_mesh_process_env(&effective_env, "Gemma-4");
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("0")
+        );
+    }
+
+    #[test]
+    fn process_env_enables_reply_guard_when_user_is_silent() {
+        let env = relay_mesh_process_env(&BTreeMap::new(), "Gemma-4");
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("1")
+        );
+    }
+
     #[test]
     fn process_env_seeds_controls_without_restoring_unrelated_credentials() {
         let effective_env = BTreeMap::from([
diff --git a/desktop/src-tauri/src/managed_agents/storage.rs b/desktop/src-tauri/src/managed_agents/storage.rs
index f6f89ed898..652bb9b9ea 100644
--- a/desktop/src-tauri/src/managed_agents/storage.rs
+++ b/desktop/src-tauri/src/managed_agents/storage.rs
@@ -52,6 +52,34 @@ fn managed_agents_logs_dir(app: &AppHandle) -> Result<PathBuf, String> {
     Ok(dir)
 }
 
+/// Install-log path for `runtime_id`, alongside the agent logs.
+pub fn install_log_path(app: &AppHandle, runtime_id: &str) -> Result<PathBuf, String> {
+    Ok(managed_agents_logs_dir(app)?.join(install_log_filename(runtime_id)?))
+}
+
+/// Filename for a runtime's install log, or an error for an id that must not
+/// become one.
+///
+/// The id is validated rather than trusted: ids reach this from user-defined
+/// custom harnesses as well as the catalog, and a `../` or a separator in one
+/// would place the log outside the logs directory. Rejecting beats sanitizing —
+/// a rejected id means no log, while a rewritten one could collide with another
+/// runtime's.
+fn install_log_filename(runtime_id: &str) -> Result<String, String> {
+    if runtime_id.is_empty() || !runtime_id.chars().all(is_safe_id_char) {
+        return Err(format!(
+            "unsafe runtime id for a log filename: {runtime_id}"
+        ));
+    }
+    Ok(format!("install-{runtime_id}.log"))
+}
+
+/// Characters allowed in a runtime id used as a filename. Excludes `/`, `\`,
+/// `:` and `.`, so no id can traverse or escape the logs directory.
+fn is_safe_id_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || c == '-' || c == '_'
+}
+
 pub fn managed_agent_log_path(app: &AppHandle, pubkey: &str) -> Result<PathBuf, String> {
     Ok(managed_agents_logs_dir(app)?.join(format!("{pubkey}.log")))
 }
@@ -632,6 +660,62 @@ pub(crate) fn open_log_file(path: &Path) -> Result<File, String> {
         .map_err(|error| format!("failed to open log file {}: {error}", path.display()))
 }
 
+/// Start a new install-log session at `path`: keep the previous run as
+/// `<path>.1` and return a freshly created, empty current file.
+///
+/// Rotating per *run* rather than by size is what bounds this file. A run
+/// writes one record per executed attempt, each capped by the log-scale
+/// capture, so one run's file is bounded by steps × attempts × cap and the
+/// history on disk is bounded at two runs. Size-triggered rotation could not
+/// promise either: it never replaced an existing `.1`, and on Windows —
+/// where rename does not replace its destination — it stopped working
+/// altogether once `.1` existed, leaving the current file to grow.
+///
+/// The old `.1` is therefore *removed* before the rename rather than renamed
+/// over. Every step is best-effort: a rotation that fails must not cost the
+/// user the install, so the session continues with a truncated current file.
+pub(crate) fn start_install_log_session(path: &Path) -> Result<File, String> {
+    if path.exists() {
+        let mut previous = path.as_os_str().to_owned();
+        previous.push(".1");
+        let previous = PathBuf::from(previous);
+        let _ = fs::remove_file(&previous);
+        let _ = fs::rename(path, &previous);
+    }
+    open_install_log(path, /* truncate */ true)
+}
+
+/// Open an install log for appending one more record to the current session.
+pub(crate) fn open_install_log_file(path: &Path) -> Result<File, String> {
+    open_install_log(path, /* truncate */ false)
+}
+
+/// Open an install log owner-only.
+///
+/// The mode is set *in the create* rather than chmod'd afterwards, so the file
+/// is never briefly group/world-readable. Install output can carry registry
+/// tokens and proxy credentials echoed by a failing installer, so the window
+/// matters even though it is short. An existing file's mode is left as-is —
+/// `OpenOptions::mode` only applies on creation, and silently re-tightening a
+/// file the user relaxed is not this function's call to make.
+fn open_install_log(path: &Path, truncate: bool) -> Result<File, String> {
+    let mut options = OpenOptions::new();
+    options.create(true);
+    if truncate {
+        options.write(true).truncate(true);
+    } else {
+        options.append(true);
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    options
+        .open(path)
+        .map_err(|error| format!("failed to open log file {}: {error}", path.display()))
+}
+
 pub(crate) fn append_log_marker(path: &Path, message: &str) -> Result<(), String> {
     let mut file = open_log_file(path)?;
     writeln!(file, "{message}").map_err(|error| format!("failed to write log marker: {error}"))
diff --git a/desktop/src-tauri/src/managed_agents/storage_tests.rs b/desktop/src-tauri/src/managed_agents/storage_tests.rs
index 73567bb915..9943c6b3ac 100644
--- a/desktop/src-tauri/src/managed_agents/storage_tests.rs
+++ b/desktop/src-tauri/src/managed_agents/storage_tests.rs
@@ -698,3 +698,135 @@ fn try_delete_agent_key_returns_result() {
     // team_snapshot::tests::rollback_aggregates_multiple_errors.
     let _: fn(&str) -> Result<(), String> = super::try_delete_agent_key;
 }
+
+// ── install logs ─────────────────────────────────────────────────────────────
+
+/// Install output can carry registry tokens and proxy credentials a failing
+/// installer echoed, and the file is written unattended. `0o600` must come from
+/// the create itself: a post-write `chmod` leaves a window where the umask
+/// decides, and a crash inside it leaves the log readable to other local users.
+#[cfg(unix)]
+#[test]
+fn install_log_is_created_owner_only_without_post_write_chmod() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut file = super::open_install_log_file(&path).expect("open install log");
+    file.write_all(b"npm ERR!\n").expect("write");
+
+    let mode = std::fs::metadata(&path)
+        .expect("metadata")
+        .permissions()
+        .mode()
+        & 0o777;
+    assert_eq!(mode, 0o600, "install logs must be owner-only");
+}
+
+/// A run starts a new current file and keeps the previous run as `.1`, so the
+/// two runs are never mixed and the history on disk stays bounded at two.
+#[test]
+fn install_log_session_keeps_the_previous_run_as_dot_one() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut first = super::start_install_log_session(&path).expect("first session");
+    first.write_all(b"run-one\n").expect("write");
+    let mut second = super::start_install_log_session(&path).expect("second session");
+    second.write_all(b"run-two\n").expect("write");
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read current"),
+        "run-two\n",
+        "the current file must hold only the newest run"
+    );
+    assert_eq!(
+        std::fs::read_to_string(dir.path().join("install-goose.log.1")).expect("read .1"),
+        "run-one\n",
+        "the previous run must be preserved as .1"
+    );
+}
+
+/// The third run must still rotate when `.1` already exists. Windows `rename`
+/// does not replace its destination, so a rename-only rotation silently stops
+/// working here and leaves the current file to grow across every later run —
+/// the old `.1` is removed first precisely so this cannot happen. Runs on the
+/// Windows target too: this is the path that fails there.
+#[test]
+fn install_log_session_replaces_an_existing_dot_one() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+    let rotated = dir.path().join("install-goose.log.1");
+    // Seed the state a rename-only rotation cannot get out of: both files exist.
+    std::fs::write(&path, b"previous-run\n").expect("seed current");
+    std::fs::write(&rotated, b"ancient-run\n").expect("seed .1");
+
+    let mut file = super::start_install_log_session(&path).expect("session");
+    file.write_all(b"fresh-run\n").expect("write");
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read current"),
+        "fresh-run\n",
+        "the current file must restart even when .1 was already present"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&rotated).expect("read .1"),
+        "previous-run\n",
+        ".1 must be replaced by the run that just ended, not kept"
+    );
+}
+
+/// Records written after the session starts append to it — a run's later
+/// records must not erase its earlier ones.
+#[test]
+fn install_log_appends_within_a_session() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut session = super::start_install_log_session(&path).expect("session");
+    session.write_all(b"header\n").expect("write");
+    for record in ["first\n", "second\n"] {
+        let mut file = super::open_install_log_file(&path).expect("open install log");
+        file.write_all(record.as_bytes()).expect("write");
+    }
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read back"),
+        "header\nfirst\nsecond\n"
+    );
+}
+
+/// A runtime id becomes part of a filename. Ids reach this from user-defined
+/// custom harnesses as well as the catalog, so anything that could traverse or
+/// escape the logs directory is rejected rather than sanitized — a rejected id
+/// simply means no log, while a silently rewritten one could collide with
+/// another runtime's log.
+#[test]
+fn install_log_filename_rejects_ids_that_would_escape_the_logs_dir() {
+    for id in [
+        "../../etc/passwd",
+        "goose/../../evil",
+        "sub/dir",
+        "back\\slash",
+        "with.dot",
+        "",
+    ] {
+        assert!(
+            super::install_log_filename(id).is_err(),
+            "id {id:?} must not be accepted as a filename component"
+        );
+    }
+}
+
+/// Ordinary catalog and custom-harness ids are accepted — the guard must not
+/// reject the ids it exists to serve.
+#[test]
+fn install_log_filename_accepts_ordinary_runtime_ids() {
+    for id in ["goose", "claude-code", "buzz_agent", "codex2"] {
+        assert_eq!(
+            super::install_log_filename(id).expect("id must be usable in a log filename"),
+            format!("install-{id}.log")
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/types.rs b/desktop/src-tauri/src/managed_agents/types.rs
index 3d8e0ed02b..fcd8b13fc9 100644
--- a/desktop/src-tauri/src/managed_agents/types.rs
+++ b/desktop/src-tauri/src/managed_agents/types.rs
@@ -587,7 +587,8 @@ pub struct ManagedAgentLogResponse {
 pub enum AcpAvailabilityStatus {
     Available,
     AdapterMissing,
-    /// Adapter binary is present but is from the deprecated package (< 1.0). Reinstall required.
+    /// Adapter binary is present but unsupported — either the deprecated
+    /// package or a version below the supported floor. Reinstall required.
     AdapterOutdated,
     CliMissing,
     NotInstalled,
@@ -701,6 +702,10 @@ pub struct InstallRuntimeResult {
     /// Number of agents whose stop succeeded but respawn failed.
     /// Mirrors `GlobalAgentConfigSaveResult.failed_restart_count`.
     pub failed_restart_count: u32,
+    /// Install log file for this run, when one was written. The UI surfaces it
+    /// on failure so a user can read the full retry history instead of only the
+    /// last step's truncated output. `None` when no log could be opened.
+    pub log_path: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize)]
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/models.rs b/desktop/src-tauri/src/models.rs
index 1d9747bc20..3f04d3d7a1 100644
--- a/desktop/src-tauri/src/models.rs
+++ b/desktop/src-tauri/src/models.rs
@@ -6,6 +6,8 @@ use serde::{Deserialize, Deserializer, Serialize};
 pub struct IdentityInfo {
     pub pubkey: String,
     pub display_name: String,
+    /// Durable location of the active identity key.
+    pub storage: String,
     /// True when the app booted with an ephemeral key because the OS keyring
     /// was empty despite a prior successful migration (key was externally
     /// deleted). The frontend routes to the nsec re-import step when true.
diff --git a/desktop/src-tauri/src/native_websocket.rs b/desktop/src-tauri/src/native_websocket.rs
index c0cf2e76f1..128f2df79d 100644
--- a/desktop/src-tauri/src/native_websocket.rs
+++ b/desktop/src-tauri/src/native_websocket.rs
@@ -24,7 +24,7 @@ type Id = u32;
 
 #[derive(Debug, Deserialize)]
 #[serde(tag = "type", content = "data")]
-enum WebSocketMessage {
+pub(crate) enum WebSocketMessage {
     Text(String),
     Binary(Vec<u8>),
     Ping(Vec<u8>),
@@ -33,7 +33,7 @@ enum WebSocketMessage {
 }
 
 #[derive(Debug, Deserialize)]
-struct CloseFramePayload {
+pub(crate) struct CloseFramePayload {
     code: u16,
     reason: String,
 }
@@ -82,7 +82,7 @@ struct ConnectionHandle {
 }
 
 #[derive(Clone)]
-struct WebSocketManager {
+pub(crate) struct WebSocketManager {
     connections: Arc<Mutex<HashMap<Id, Arc<ConnectionHandle>>>>,
     connect_cancel: Arc<Mutex<CancellationToken>>,
 }
@@ -182,11 +182,23 @@ async fn connect(
     open_connection(manager.inner(), &url, on_message).await
 }
 
-async fn send_message(
+pub(crate) async fn send_message(
     manager: &WebSocketManager,
     id: Id,
     message: WebSocketMessage,
 ) -> Result<(), String> {
+    // Egress guard: the NIP-49 local key backup must never reach a relay.
+    // This is the single choke point for all webview-originated websocket
+    // frames (see `crate::egress_guard`).
+    match &message {
+        WebSocketMessage::Text(text) => {
+            crate::egress_guard::assert_no_key_backup(text, "websocket text frame")?
+        }
+        WebSocketMessage::Binary(bytes) => {
+            crate::egress_guard::assert_no_key_backup_bytes(bytes, "websocket binary frame")?
+        }
+        _ => {}
+    }
     let handle = manager
         .connections
         .lock()
diff --git a/desktop/src-tauri/src/relay.rs b/desktop/src-tauri/src/relay.rs
index f896695624..71aa21c413 100644
--- a/desktop/src-tauri/src/relay.rs
+++ b/desktop/src-tauri/src/relay.rs
@@ -450,6 +450,7 @@ pub async fn sync_managed_agent_profile(
     let event = build_profile_event(agent_keys, display_name, avatar_url, auth_tag)?;
     let event_json = event.as_json();
     let body_bytes = event_json.into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "agent profile sync")?;
 
     let url = format!("{}/events", relay_http_base_url(relay_url));
     let auth = build_nip98_auth_header_for_keys(agent_keys, &Method::POST, &url, &body_bytes)?;
@@ -566,6 +567,7 @@ pub async fn submit_signed_event_with_keys(
     crate::relay_admission::wait_for_rate_limit().await;
     let url = format!("{}/events", relay_api_base_url_with_override(state));
     let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "signed event submit (keys)")?;
     let auth_header = build_nip98_auth_header_for_keys(keys, &Method::POST, &url, &body_bytes)?;
 
     let mut request = state
diff --git a/desktop/src-tauri/src/relay/submit.rs b/desktop/src-tauri/src/relay/submit.rs
index 2a42d86c2b..eaad29d3b1 100644
--- a/desktop/src-tauri/src/relay/submit.rs
+++ b/desktop/src-tauri/src/relay/submit.rs
@@ -25,6 +25,7 @@ pub async fn submit_signed_event_at_with_keys(
     crate::relay_admission::wait_for_rate_limit().await;
     let url = format!("{}/events", api_base_url.trim_end_matches('/'));
     let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "relay event submit")?;
     let auth_header = build_nip98_auth_header_for_keys(keys, &Method::POST, &url, &body_bytes)?;
 
     let response = state
diff --git a/desktop/src-tauri/src/reset.rs b/desktop/src-tauri/src/reset.rs
index d2e35e6839..18ddd80eb8 100644
--- a/desktop/src-tauri/src/reset.rs
+++ b/desktop/src-tauri/src/reset.rs
@@ -463,6 +463,26 @@ mod tests {
         assert_eq!(kc.delete_calls.get(), 1, "keychain deleted once");
     }
 
+    // ── NIP-49: the boot wipe destroys the app-managed key backup ─────────────
+
+    #[test]
+    fn test_wipe_removes_app_managed_key_backup() {
+        let tmp = TempDir::new().unwrap();
+        let app_data = make_app_data(&tmp);
+        let backup = crate::key_backup::backup_file_path(&app_data);
+        std::fs::write(&backup, b"encrypted-backup-bytes").unwrap();
+
+        write_sentinel(&app_data).unwrap();
+        let kc = FakeKeychain::ok();
+        let outcome = run_boot_reset_with_keychain(make_ctx(&app_data, &kc, false));
+
+        assert!(outcome.completed);
+        assert!(
+            !backup.exists(),
+            "sign-out wipe must destroy the app-managed key backup"
+        );
+    }
+
     // ── Test 3: keychain failure keeps sentinel ────────────────────────────────
 
     #[test]
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 2eba7815b2..1ff8bd20ef 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.3",
   "identifier": "xyz.block.buzz.app",
   "build": {
     "beforeDevCommand": {
diff --git a/desktop/src/app/App.tsx b/desktop/src/app/App.tsx
index 90b5bf5ebc..44618f2c72 100644
--- a/desktop/src/app/App.tsx
+++ b/desktop/src/app/App.tsx
@@ -56,6 +56,7 @@ import { WelcomeSetup } from "@/features/communities/ui/WelcomeSetup";
 import { CommunityApplyErrorScreen } from "@/features/communities/ui/CommunityApplyErrorScreen";
 import { CommunityChangeOverlay } from "@/features/communities/ui/CommunityChangeOverlay";
 import { setAvatarProfileSyncQueryClient } from "@/features/profile/avatarProfileSync";
+import { EncryptedBackupProvider } from "@/features/settings/EncryptedBackupProvider";
 import { createBuzzQueryClient } from "@/shared/api/queryClient";
 import { isSharedIdentity as isSharedIdentityCmd } from "@/shared/api/tauri";
 import { getProfile } from "@/shared/api/tauriProfiles";
@@ -270,9 +271,18 @@ function AppReady({
   }
 
   return (
-    <KnownAgentPubkeysProvider>
-      <RouterProvider router={router} />
-    </KnownAgentPubkeysProvider>
+    <EncryptedBackupProvider
+      onOpenSettings={() =>
+        void router.navigate({
+          to: "/settings",
+          search: { section: "profile" },
+        })
+      }
+    >
+      <KnownAgentPubkeysProvider>
+        <RouterProvider router={router} />
+      </KnownAgentPubkeysProvider>
+    </EncryptedBackupProvider>
   );
 }
 
diff --git a/desktop/src/app/AppHuddleBar.tsx b/desktop/src/app/AppHuddleBar.tsx
new file mode 100644
index 0000000000..9fa12d513f
--- /dev/null
+++ b/desktop/src/app/AppHuddleBar.tsx
@@ -0,0 +1,25 @@
+import type * as React from "react";
+
+import { HuddleBar } from "@/features/huddle";
+
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
+
+type AppHuddleBarProps = Pick<
+  React.ComponentProps<typeof HuddleBar>,
+  "onOpenThread" | "onVisibilityChange"
+>;
+
+export function AppHuddleBar({
+  onOpenThread,
+  onVisibilityChange,
+}: AppHuddleBarProps) {
+  return (
+    <AppProfilePanelProvider>
+      <HuddleBar
+        className="h-full"
+        onOpenThread={onOpenThread}
+        onVisibilityChange={onVisibilityChange}
+      />
+    </AppProfilePanelProvider>
+  );
+}
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.tsx b/desktop/src/app/AppShell.tsx
index b856434e61..4eb0a42bbe 100644
--- a/desktop/src/app/AppShell.tsx
+++ b/desktop/src/app/AppShell.tsx
@@ -63,7 +63,8 @@ import {
   type SettingsSection,
   isSettingsSection,
 } from "@/features/settings/ui/SettingsPanels";
-import { HuddleBar, HuddleProvider } from "@/features/huddle";
+import { HuddleProvider } from "@/features/huddle";
+import { AppHuddleBar } from "@/app/AppHuddleBar";
 import { useDueReminderBadgeCount } from "@/features/reminders/hooks";
 import { RemindMeLaterProvider } from "@/features/reminders/ui/RemindMeLaterProvider";
 import { useReminderNotifications } from "@/features/reminders/useReminderNotifications";
@@ -97,7 +98,7 @@ import { SidebarInset, SidebarProvider } from "@/shared/ui/sidebar";
 import { RelayConnectionOverlay } from "@/app/RelayConnectionOverlay";
 import { useSidebarRelayConnectionCard } from "@/features/sidebar/ui/useSidebarRelayConnectionCard";
 import { AppShellTrayMenu } from "@/app/useAppShellTrayMenu";
-
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
 const LazySettingsScreen = React.lazy(async () => {
   const module = await import("@/features/settings/ui/SettingsScreen");
   return { default: module.SettingsScreen };
@@ -160,7 +161,6 @@ export function AppShell() {
     ? locationSearchSection
     : DEFAULT_SETTINGS_SECTION;
   const startupReady = useDeferredStartup();
-
   const identityQuery = useIdentityQuery();
   const { mutedChannelIds, muteChannel, unmuteChannel } = useChannelMutes(
     identityQuery.data?.pubkey,
@@ -303,7 +303,6 @@ export function AppShell() {
       ? (channels.find((channel) => channel.id === targetChannelId) ?? null)
       : null;
   }, [channels, managedChannelId, selectedChannelId]);
-
   const {
     handleChannelNotification,
     handleDmNotification,
@@ -518,7 +517,6 @@ export function AppShell() {
     },
     [applyAgents, applyCanvas, createChannelMutation, goChannel],
   );
-
   const handleCreateForum = React.useCallback(
     async ({
       description,
@@ -586,7 +584,6 @@ export function AppShell() {
     },
     [goHome, hideDmMutation, selectedChannelId],
   );
-
   const handleOpenSettings = React.useCallback(
     (section: SettingsSection = DEFAULT_SETTINGS_SECTION) => {
       setIsChannelManagementOpen(false);
@@ -594,12 +591,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(
@@ -620,11 +615,8 @@ export function AppShell() {
     unreadChannelIds,
     unreadChannelNotificationCount,
   });
+  // Dispatch `buzz://message` deep links into the router.
   useMessageDeepLinks();
-  const handleOpenNewDm = React.useCallback(
-    () => void goNewMessage(),
-    [goNewMessage],
-  );
   const handleOpenCreateChannel = React.useCallback(
     () => setIsCreateChannelOpen(true),
     [],
@@ -657,7 +649,7 @@ export function AppShell() {
 
       if (key === "k" && event.shiftKey) {
         event.preventDefault();
-        handleOpenNewDm();
+        void goNewMessage();
         return;
       }
 
@@ -686,9 +678,9 @@ export function AppShell() {
     };
   }, [
     handleOpenBrowseChannels,
-    handleOpenNewDm,
     handleOpenCreateChannel,
     handleOpenSearch,
+    goNewMessage,
     goHome,
     settingsOpen,
   ]);
@@ -770,216 +762,224 @@ export function AppShell() {
                     />
                   ) : null}
                   <SidebarProvider className="min-h-0 flex-1 flex-col overflow-hidden">
-                    {!settingsOpen ? (
-                      <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
+                    <AppProfilePanelProvider>
+                      {!settingsOpen ? (
+                        <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}
+                            />
+                          </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
                             }
-                            isUpdatingDesktopNotifications={
-                              notificationSettings.isUpdatingDesktopEnabled
-                            }
-                            notificationErrorMessage={
-                              notificationSettings.errorMessage
-                            }
-                            notificationPermission={
-                              notificationSettings.permission
+                            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,
+                              });
+                              handleSwitchCommunity(id);
+                            }}
+                            onAddCommunityOpenChange={
+                              addCommunityDialog.onOpenChange
                             }
-                            notificationSettings={notificationSettings.settings}
-                            onClose={handleCloseSettings}
-                            onSectionChange={handleSettingsSectionChange}
-                            onSetDesktopNotificationsEnabled={
-                              notificationSettings.setDesktopEnabled
+                            onNewMessage={goNewMessage}
+                            onBackgroundClick={requestFocusedThreadClose}
+                            onCreateChannelOpenChange={setIsCreateChannelOpen}
+                            onOpenAddCommunity={addCommunityDialog.openDialog}
+                            onSendFeedback={() => setIsSendFeedbackOpen(true)}
+                            onUpdateCommunity={communitiesHook.updateCommunity}
+                            onRemoveCommunity={(id) =>
+                              void handleRemoveCommunity(id)
                             }
-                            onSetHomeBadgeEnabled={
-                              notificationSettings.setHomeBadgeEnabled
+                            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)
                             }
-                            onSetSlotAlertsEnabled={
-                              notificationSettings.setSlotAlertsEnabled
+                            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)
                             }
-                            onSetNotifyWhileViewing={
-                              notificationSettings.setNotifyWhileViewing
+                            onSetUserStatus={(text, emoji) =>
+                              setUserStatusMutation.mutate({ text, emoji })
                             }
-                            onSetAllSlotAlertsEnabled={
-                              notificationSettings.setAllSlotAlertsEnabled
+                            onClearUserStatus={() =>
+                              setUserStatusMutation.mutate({
+                                text: "",
+                                emoji: "",
+                              })
                             }
-                            onSetSoundForSlot={
-                              notificationSettings.setSoundForSlot
+                            profile={profileQuery.data}
+                            selfUserStatus={
+                              deferredPubkey
+                                ? (selfStatusQuery.data?.[
+                                    deferredPubkey.toLowerCase()
+                                  ] ?? undefined)
+                                : undefined
                             }
-                            section={settingsSection}
+                            selectedChannelId={selectedChannelId}
+                            selectedView={selectedView}
+                            unreadChannelIds={unreadChannelIds}
+                            unreadChannelCounts={unreadChannelCounts}
+                            mutedChannelIds={mutedChannelIds}
+                            onMuteChannel={muteChannel}
+                            onUnmuteChannel={unmuteChannel}
+                            starredChannelIds={starredChannelIds}
+                            onStarChannel={starChannel}
+                            onUnstarChannel={unstarChannel}
                           />
-                        </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,
-                            });
-                            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
+                          <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);
                           }
-                          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) {
+                        }}
+                        onDeleteActiveChannel={() => {
+                          setIsChannelManagementOpen(false);
                           setManagedChannelId(null);
-                        }
-                      }}
-                      onDeleteActiveChannel={() => {
-                        setIsChannelManagementOpen(false);
-                        setManagedChannelId(null);
-                        void goHome({ replace: true });
-                      }}
-                      onSelectChannel={(channelId) => {
-                        void goChannel(channelId);
-                      }}
-                    />
-                    <SendFeedbackController
-                      onOpenChange={setIsSendFeedbackOpen}
-                      open={isSendFeedbackOpen}
-                    />
+                          void goHome({ replace: true });
+                        }}
+                        onSelectChannel={(channelId) => {
+                          void goChannel(channelId);
+                        }}
+                      />
+                      <SendFeedbackController
+                        onOpenChange={setIsSendFeedbackOpen}
+                        open={isSendFeedbackOpen}
+                      />
+                    </AppProfilePanelProvider>
                   </SidebarProvider>
                 </div>
 
                 <div className="absolute inset-x-0 bottom-0 z-0 h-(--buzz-huddle-drawer-height)">
-                  <HuddleBar
-                    className="h-full"
+                  <AppHuddleBar
                     onOpenThread={(channelId, messageId) => {
                       void goChannel(channelId, {
                         messageId,
diff --git a/desktop/src/app/navigation/useAppNavigation.ts b/desktop/src/app/navigation/useAppNavigation.ts
index f928970610..d19ac03120 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(
@@ -303,6 +315,7 @@ export function useAppNavigation() {
     goProject,
     goProjects,
     goPulse,
+    goProfile,
     goSettings,
     goWorkflow,
     goWorkflows,
diff --git a/desktop/src/features/agents/cardMintStore.test.mjs b/desktop/src/features/agents/cardMintStore.test.mjs
new file mode 100644
index 0000000000..eb9c0f07b0
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.test.mjs
@@ -0,0 +1,170 @@
+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("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..0e4746d445
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.ts
@@ -0,0 +1,227 @@
+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();
+    }
+    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/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/useInstallOutputLine.test.mjs b/desktop/src/features/agents/lib/useInstallOutputLine.test.mjs
new file mode 100644
index 0000000000..d65583e00d
--- /dev/null
+++ b/desktop/src/features/agents/lib/useInstallOutputLine.test.mjs
@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { nextInstallOutputLine } from "./useInstallOutputLine.ts";
+
+function event(runtimeId, seq, line) {
+  return { runtime_id: runtimeId, seq, line };
+}
+
+test("nextInstallOutputLine: adopts the first line for the watched runtime", () => {
+  assert.deepEqual(
+    nextInstallOutputLine(null, event("goose", 0, "downloading"), "goose"),
+    { seq: 0, line: "downloading" },
+  );
+});
+
+test("nextInstallOutputLine: a later line replaces the current one", () => {
+  const current = { seq: 4, line: "downloading" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(current, event("goose", 5, "unpacking"), "goose"),
+    { seq: 5, line: "unpacking" },
+  );
+});
+
+test("nextInstallOutputLine: ignores a line from another runtime", () => {
+  const current = { seq: 1, line: "downloading" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("codex", 2, "other work"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: ignores an out-of-order line", () => {
+  const current = { seq: 7, line: "retrying" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("goose", 6, "stale line"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: ignores a replay of the current sequence number", () => {
+  const current = { seq: 7, line: "retrying" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("goose", 7, "duplicate"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: a null line clears the display", () => {
+  const current = { seq: 3, line: "download failed" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(current, event("goose", 4, null), "goose"),
+    { seq: 4, line: null },
+  );
+});
+
+test("nextInstallOutputLine: a later step's first line is adopted after a higher attempt", () => {
+  // The seq is install-wide: step 2 attempt 1 always follows step 1 attempt 2,
+  // which is exactly what an attempt-keyed comparison got wrong.
+  const current = { seq: 9, line: "step one, attempt two" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(
+      current,
+      event("goose", 10, "step two, attempt one"),
+      "goose",
+    ),
+    { seq: 10, line: "step two, attempt one" },
+  );
+});
+
+test("nextInstallOutputLine: a first event mid-install is adopted", () => {
+  assert.deepEqual(
+    nextInstallOutputLine(null, event("goose", 42, "downloading"), "goose"),
+    { seq: 42, line: "downloading" },
+  );
+});
diff --git a/desktop/src/features/agents/lib/useInstallOutputLine.ts b/desktop/src/features/agents/lib/useInstallOutputLine.ts
new file mode 100644
index 0000000000..9f50843fc7
--- /dev/null
+++ b/desktop/src/features/agents/lib/useInstallOutputLine.ts
@@ -0,0 +1,108 @@
+import * as React from "react";
+import { listen } from "@tauri-apps/api/event";
+
+/** Mirror of the Rust `InstallOutputEvent` payload (install_report.rs). */
+export type InstallOutputEvent = {
+  runtime_id: string;
+  /** Monotonic across the whole install, not per step or per attempt. */
+  seq: number;
+  /** Null is the start signal: clear the displayed line now. */
+  line: string | null;
+};
+
+/** The line being shown, and the sequence number that produced it. */
+export type InstallOutputState = {
+  seq: number;
+  line: string | null;
+};
+
+/**
+ * Fold one event into the displayed line.
+ *
+ * Events from another runtime are ignored — every install card listens to the
+ * same channel. So is an out-of-order event: emission is monotonic in `seq`, so
+ * a lower one has already been superseded. That matters at a retry boundary,
+ * where a line emitted just as the next attempt starts would otherwise sit
+ * under the spinner showing the failure the user already had.
+ *
+ * The ordering key is the install-wide `seq` rather than the attempt number,
+ * which restarts at 1 for every step: keyed on attempt, a step that succeeded on
+ * attempt 2 would make the next step's attempt-1 output look stale and freeze
+ * the display for the rest of the install.
+ */
+export function nextInstallOutputLine(
+  current: InstallOutputState | null,
+  event: InstallOutputEvent,
+  runtimeId: string,
+): InstallOutputState | null {
+  if (event.runtime_id !== runtimeId) return current;
+  if (current && event.seq <= current.seq) return current;
+  return { seq: event.seq, line: event.line };
+}
+
+/**
+ * The install command's most recent output line for `runtimeId`, or null when
+ * nothing is being shown — the install is not running, nothing has printed yet,
+ * or the backend cleared the line because a new attempt is starting.
+ *
+ * An install runs for up to 15 minutes with no other feedback than a spinner;
+ * this turns that wait into observable progress. The backend throttles
+ * emission, so this re-renders a few times a second at most.
+ *
+ * Pass `isInstalling` so the line clears when the install settles — a finished
+ * install must not leave its last line under a fresh Install button.
+ */
+export function useInstallOutputLine(
+  runtimeId: string,
+  isInstalling: boolean,
+): string | null {
+  const [state, setState] = React.useState<InstallOutputState | null>(null);
+
+  // Subscribed for this runtime's whole lifetime, not just while installing.
+  // The install command is invoked from the click handler, so the backend can
+  // emit the attempt-start clear and the first line before React commits
+  // `isInstalling` — and there is no replay, so a subscription that waited for
+  // that commit would lose those events permanently. A fast command's entire
+  // output is exactly what fits in that window.
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    (async () => {
+      try {
+        const stop = await listen<InstallOutputEvent>(
+          "acp-install-output",
+          (event) => {
+            if (cancelled) return;
+            setState((current) =>
+              nextInstallOutputLine(current, event.payload, runtimeId),
+            );
+          },
+        );
+        if (cancelled) {
+          stop();
+        } else {
+          unlisten = stop;
+        }
+      } catch {
+        // Event system unavailable (web/e2e) — the spinner shows alone.
+      }
+    })();
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [runtimeId]);
+
+  // `seq` is monotonic within one install and restarts at 0 for the next, so
+  // state must not outlive the run that produced it: a retained higher `seq`
+  // would make every event of the following install look superseded. Settling
+  // is the run boundary, so it is where the ordering key resets.
+  React.useEffect(() => {
+    if (!isInstalling) setState(null);
+  }, [isInstalling]);
+
+  // Events that arrive after the install settles — a drain flushing its last
+  // line — must not reappear under a fresh Install button, so the line is
+  // reported only while the install is running.
+  return (isInstalling ? state?.line : null) ?? null;
+}
diff --git a/desktop/src/features/agents/ui/AgentAiDefaults.tsx b/desktop/src/features/agents/ui/AgentAiDefaults.tsx
index a577113a0a..39b8d4af1d 100644
--- a/desktop/src/features/agents/ui/AgentAiDefaults.tsx
+++ b/desktop/src/features/agents/ui/AgentAiDefaults.tsx
@@ -28,6 +28,7 @@ export function formatAiDefaultsSummary({
 export function AgentAiDefaultsNotice({
   isConfigured = true,
   onEditDefaults,
+  onEditDefinition,
   triggerRef,
   explicitModel,
   explicitProvider,
@@ -37,6 +38,12 @@ export function AgentAiDefaultsNotice({
 }: {
   isConfigured?: boolean;
   onEditDefaults: () => void;
+  /**
+   * Set only when a linked definition owns these values, which is also when
+   * the surface's own model/provider controls are read-only. Without it the
+   * summary would name the values and offer no way to reach them.
+   */
+  onEditDefinition?: () => void;
   triggerRef?: React.Ref<HTMLButtonElement>;
   explicitModel: string;
   explicitProvider: string;
@@ -91,17 +98,36 @@ export function AgentAiDefaultsNotice({
           {model || "Not configured"}
         </dd>
       </dl>
-      <Button
-        className="h-auto px-0 py-1"
-        data-testid="edit-ai-defaults"
-        onClick={onEditDefaults}
-        ref={triggerRef}
-        size="xs"
-        type="button"
-        variant="link"
-      >
-        Edit global defaults
-      </Button>
+      {onEditDefinition ? (
+        <p className="text-xs text-muted-foreground">
+          Set on the agent definition and shared by every agent created from it.
+        </p>
+      ) : null}
+      <div className="flex flex-wrap items-center gap-3">
+        <Button
+          className="h-auto px-0 py-1"
+          data-testid="edit-ai-defaults"
+          onClick={onEditDefaults}
+          ref={triggerRef}
+          size="xs"
+          type="button"
+          variant="link"
+        >
+          Edit global defaults
+        </Button>
+        {onEditDefinition ? (
+          <Button
+            className="h-auto px-0 py-1"
+            data-testid="edit-agent-definition"
+            onClick={onEditDefinition}
+            size="xs"
+            type="button"
+            variant="link"
+          >
+            Edit agent definition
+          </Button>
+        ) : null}
+      </div>
     </div>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentCardMintDialog.tsx b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
new file mode 100644
index 0000000000..219de4aefa
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
@@ -0,0 +1,364 @@
+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 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";
+
+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 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. While
+  // unknown (loading/error) we show the normal mint form — the mint itself
+  // still fails cleanly if no key exists.
+  const keyStatusQuery = useQuery({
+    queryKey: ["cardMintKeyStatus", agentId],
+    queryFn: () => cardMintKeyStatus(agentId),
+  });
+  const needsKey = keyStatusQuery.data === false;
+
+  // 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: () => {
+      queryClient.setQueryData(["cardMintKeyStatus", agentId], true);
+      // 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("");
+      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>
+
+        {needsKey ? (
+          <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" />
+                One-time setup: OpenAI API key
+              </span>
+              <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 to your
+                agent defaults, so you only do this once.
+              </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">
+              <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>
+            </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>
+            <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/AgentInstanceEditDialog.tsx b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
index 79d1e9a790..dd775c1c9e 100644
--- a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
@@ -25,6 +25,7 @@ import { Dialog } from "@/shared/ui/dialog";
 import { Input } from "@/shared/ui/input";
 import { setManagedAgentAutoRestart } from "@/shared/api/tauriManagedAgents";
 import { EditAgentAdvancedFields } from "./EditAgentAdvancedFields";
+import { EditAgentModelField } from "./EditAgentModelField";
 import {
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
@@ -49,6 +50,7 @@ import {
 } from "./relayMeshModelPicker";
 import {
   computeEditAgentFormValidity,
+  definitionOwnsAiConfig,
   envVarsEqual,
   isEditAgentProviderSaveValid,
   resolveAgentCommandUpdate,
@@ -152,6 +154,12 @@ export function AgentInstanceEditDialog({
         : null,
     [agent.personaId, personasQuery.data],
   );
+  const aiConfigIsDefinitionOwned = definitionOwnsAiConfig(linkedPersona);
+  // Model and LLM provider stay visible when the definition owns them — the
+  // value is the answer to "what does this agent run on" — but read-only, and
+  // the summary below routes the edit to the definition dialog.
+  const aiFieldsDisabled =
+    updateMutation.isPending || aiConfigIsDefinitionOwned;
   const inheritedEnvVars = linkedPersona?.envVars ?? {};
   const [respondTo, setRespondTo] = React.useState<RespondToMode>(
     agent.respondTo,
@@ -589,13 +597,27 @@ export function AgentInstanceEditDialog({
     onOpenChange(next);
   }
 
-  const providerValid = isEditAgentProviderSaveValid({
-    llmProviderFieldVisible,
-    currentProvider: provider,
-    originalProvider: agent.provider,
-    globalProvider: inheritedProviderDefault.value,
-    originalRuntimeSupportsProvider,
-  });
+  // Definition-owned fields are edited in the definition dialog, which the
+  // caller opens; this form closes first so the two are never both mounted.
+  const handleEditLinkedPersona = onEditLinkedPersona
+    ? () => {
+        handleOpenChange(false);
+        onEditLinkedPersona();
+      }
+    : undefined;
+
+  // A field this form never sends cannot make it invalid. Switching harness
+  // can blank the provider draft, which would otherwise block Save on a
+  // read-only field the user has no way to repair.
+  const providerValid =
+    aiConfigIsDefinitionOwned ||
+    isEditAgentProviderSaveValid({
+      llmProviderFieldVisible,
+      currentProvider: provider,
+      originalProvider: agent.provider,
+      globalProvider: inheritedProviderDefault.value,
+      originalRuntimeSupportsProvider,
+    });
 
   const canSubmit =
     computeEditAgentFormValidity({
@@ -679,35 +701,34 @@ export function AgentInstanceEditDialog({
             ? parsedParallelism
             : undefined,
         // Linked instances defer model/provider/systemPrompt to the definition.
-        systemPrompt:
-          linkedPersona != null
-            ? undefined
-            : (systemPrompt.trim() || null) !== agent.systemPrompt
-              ? systemPrompt.trim() || null
-              : undefined,
-        model:
-          linkedPersona != null
-            ? undefined
-            : normalizedModel !== (agent.model ?? null)
-              ? normalizedModel
-              : undefined,
+        // Same predicate the controls above read, so a field can never be
+        // editable here and dropped on the wire.
+        systemPrompt: aiConfigIsDefinitionOwned
+          ? undefined
+          : (systemPrompt.trim() || null) !== agent.systemPrompt
+            ? systemPrompt.trim() || null
+            : undefined,
+        model: aiConfigIsDefinitionOwned
+          ? undefined
+          : normalizedModel !== (agent.model ?? null)
+            ? normalizedModel
+            : undefined,
         // Tri-state provider persistence keyed on providerRuntimeCapability:
         //   "capable"  → persist: value if changed, omit if unchanged.
         //   "locked"   → clear: send null if provider was set, else omit.
         //   "unknown"  → omit always (never send null for a transient state).
         // llmProviderFieldVisible is for UX visibility only; not used here.
-        provider:
-          linkedPersona != null
-            ? undefined
-            : providerRuntimeCapability === "capable"
-              ? normalizedSubmitProvider !== (agent.provider ?? null)
-                ? normalizedSubmitProvider
+        provider: aiConfigIsDefinitionOwned
+          ? undefined
+          : providerRuntimeCapability === "capable"
+            ? normalizedSubmitProvider !== (agent.provider ?? null)
+              ? normalizedSubmitProvider
+              : undefined
+            : providerRuntimeCapability === "locked"
+              ? (agent.provider ?? null) !== null
+                ? null
                 : undefined
-              : providerRuntimeCapability === "locked"
-                ? (agent.provider ?? null) !== null
-                  ? null
-                  : undefined
-                : undefined, // "unknown" → omit always
+              : undefined, // "unknown" → omit always
         envVars: envVarsEqual(submitEnvVars, agent.envVars)
           ? undefined
           : submitEnvVars,
@@ -887,13 +908,10 @@ export function AgentInstanceEditDialog({
               onUploadPendingChange={setIsAvatarUploadPending}
               onSelectAvatar={setAvatarUrl}
             />
-            {onEditLinkedPersona ? (
+            {handleEditLinkedPersona ? (
               <Button
                 className="w-full"
-                onClick={() => {
-                  handleOpenChange(false);
-                  onEditLinkedPersona();
-                }}
+                onClick={handleEditLinkedPersona}
                 size="sm"
                 type="button"
                 variant="outline"
@@ -1026,7 +1044,7 @@ export function AgentInstanceEditDialog({
                   )}
                 </label>
                 <PersonaDropdownField
-                  disabled={updateMutation.isPending}
+                  disabled={aiFieldsDisabled}
                   id="edit-agent-llm-provider"
                   onValueChange={handleProviderDropdownChange}
                   options={providerDropdownOptions}
@@ -1047,7 +1065,7 @@ export function AgentInstanceEditDialog({
                         "h-8 px-0 py-0 leading-6",
                         PERSONA_FIELD_CONTROL_CLASS,
                       )}
-                      disabled={updateMutation.isPending}
+                      disabled={aiFieldsDisabled}
                       id="edit-agent-custom-provider"
                       onChange={(event) => setProvider(event.target.value)}
                       placeholder="Custom provider ID"
@@ -1080,59 +1098,24 @@ export function AgentInstanceEditDialog({
             ) : null}
 
             {/* Model */}
-            <div className="space-y-1.5">
-              <label
-                className="text-sm font-medium text-foreground"
-                htmlFor="edit-agent-model"
-              >
-                Model
-                {modelRequired ? (
-                  <span className="ml-1 text-destructive" aria-hidden="true">
-                    *
-                  </span>
-                ) : (
-                  <span className={PERSONA_LABEL_OPTIONAL_CLASS}>Optional</span>
-                )}
-              </label>
-              <PersonaDropdownField
-                disabled={updateMutation.isPending || modelDiscoveryLoading}
-                id="edit-agent-model"
-                onValueChange={handleModelDropdownChange}
-                options={modelDropdownOptions}
-                placeholder="Default model"
-                value={modelSelectValue}
-              />
-              {showCustomModelInput ? (
-                <div
-                  className={cn(
-                    "mt-2 flex min-h-11 items-center px-3",
-                    PERSONA_FIELD_SHELL_CLASS,
-                  )}
-                >
-                  <Input
-                    aria-label="Custom model ID"
-                    autoCorrect="off"
-                    className={cn(
-                      "h-8 px-0 py-0 leading-6",
-                      PERSONA_FIELD_CONTROL_CLASS,
-                    )}
-                    disabled={updateMutation.isPending}
-                    id="edit-agent-custom-model"
-                    onChange={(event) => setModel(event.target.value)}
-                    placeholder="Custom model ID"
-                    value={model}
-                  />
-                </div>
-              ) : null}
-              {modelStatusMessage ? (
-                <p className="text-xs text-muted-foreground">
-                  {modelStatusMessage}
-                </p>
-              ) : null}
-            </div>
+            <EditAgentModelField
+              disabled={aiFieldsDisabled}
+              discoveryLoading={modelDiscoveryLoading}
+              isRequired={modelRequired}
+              model={model}
+              onCustomModelChange={setModel}
+              onModelValueChange={handleModelDropdownChange}
+              options={modelDropdownOptions}
+              selectValue={modelSelectValue}
+              showCustomModelInput={showCustomModelInput}
+              statusMessage={modelStatusMessage}
+            />
 
             <AgentAiDefaultsNotice
               onEditDefaults={() => setAiDefaultsOpen(true)}
+              onEditDefinition={
+                aiConfigIsDefinitionOwned ? handleEditLinkedPersona : undefined
+              }
               triggerRef={aiDefaultsTriggerRef}
               explicitModel={inheritedSubmission.model ?? ""}
               explicitProvider={inheritedSubmission.provider ?? ""}
diff --git a/desktop/src/features/agents/ui/AgentManagementDialogs.tsx b/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
index 604bf9f703..0d01cbbcd1 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";
 
@@ -55,6 +56,7 @@ export function AgentManagementDialogs() {
           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/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/EditAgentModelField.tsx b/desktop/src/features/agents/ui/EditAgentModelField.tsx
new file mode 100644
index 0000000000..9293fa149a
--- /dev/null
+++ b/desktop/src/features/agents/ui/EditAgentModelField.tsx
@@ -0,0 +1,94 @@
+import { cn } from "@/shared/lib/cn";
+import { Input } from "@/shared/ui/input";
+import { PersonaDropdownField } from "./PersonaDropdownField";
+import {
+  type PersonaDropdownOption,
+  PERSONA_FIELD_CONTROL_CLASS,
+  PERSONA_FIELD_SHELL_CLASS,
+  PERSONA_LABEL_OPTIONAL_CLASS,
+} from "./agentConfigOptions";
+
+/**
+ * Model field for the instance edit form — the counterpart to
+ * `PersonaModelField` on the definition form, split out of
+ * `AgentInstanceEditDialog` for the same reason that one is separate.
+ *
+ * `disabled` covers the custom-model escape hatch as well as the dropdown, so
+ * a caller that owns the value elsewhere (a linked definition) closes both
+ * ways in. `discoveryLoading` disables only the dropdown, whose options are
+ * what's still loading.
+ */
+export function EditAgentModelField({
+  disabled,
+  discoveryLoading,
+  isRequired,
+  model,
+  onCustomModelChange,
+  onModelValueChange,
+  options,
+  selectValue,
+  showCustomModelInput,
+  statusMessage,
+}: {
+  disabled: boolean;
+  discoveryLoading: boolean;
+  isRequired: boolean;
+  model: string;
+  onCustomModelChange: (value: string) => void;
+  onModelValueChange: (value: string) => void;
+  options: readonly PersonaDropdownOption[];
+  selectValue: string;
+  showCustomModelInput: boolean;
+  statusMessage: string | null;
+}) {
+  return (
+    <div className="space-y-1.5">
+      <label
+        className="text-sm font-medium text-foreground"
+        htmlFor="edit-agent-model"
+      >
+        Model
+        {isRequired ? (
+          <span className="ml-1 text-destructive" aria-hidden="true">
+            *
+          </span>
+        ) : (
+          <span className={PERSONA_LABEL_OPTIONAL_CLASS}>Optional</span>
+        )}
+      </label>
+      <PersonaDropdownField
+        disabled={disabled || discoveryLoading}
+        id="edit-agent-model"
+        onValueChange={onModelValueChange}
+        options={options}
+        placeholder="Default model"
+        value={selectValue}
+      />
+      {showCustomModelInput ? (
+        <div
+          className={cn(
+            "mt-2 flex min-h-11 items-center px-3",
+            PERSONA_FIELD_SHELL_CLASS,
+          )}
+        >
+          <Input
+            aria-label="Custom model ID"
+            autoCorrect="off"
+            className={cn(
+              "h-8 px-0 py-0 leading-6",
+              PERSONA_FIELD_CONTROL_CLASS,
+            )}
+            disabled={disabled}
+            id="edit-agent-custom-model"
+            onChange={(event) => onCustomModelChange(event.target.value)}
+            placeholder="Custom model ID"
+            value={model}
+          />
+        </div>
+      ) : null}
+      {statusMessage ? (
+        <p className="text-xs text-muted-foreground">{statusMessage}</p>
+      ) : null}
+    </div>
+  );
+}
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/definitionOwnedAiConfig.test.mjs b/desktop/src/features/agents/ui/definitionOwnedAiConfig.test.mjs
new file mode 100644
index 0000000000..915b22ffab
--- /dev/null
+++ b/desktop/src/features/agents/ui/definitionOwnedAiConfig.test.mjs
@@ -0,0 +1,116 @@
+/**
+ * Contract tests for definition-owned AI config on the instance edit form.
+ *
+ * #1968 made the linked definition authoritative for model, LLM provider, and
+ * system prompt: `resolve_effective_config` reads them from the definition and
+ * never consults the instance record. That commit changed the write path and
+ * left the instance form's Model and LLM provider dropdowns live, so editing
+ * them reported a successful save and changed nothing — the user had to find
+ * the definition dialog and set the same field a second time.
+ *
+ * The fix is one predicate feeding both seams. These tests pin that: if a
+ * future change re-derives either the omission or the control state from its
+ * own `linkedPersona != null` check, the two can drift apart again and this
+ * file fails.
+ */
+
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+import { definitionOwnsAiConfig } from "./personaRuntimeModel.ts";
+
+const dialogSource = await readFile(
+  new URL("./AgentInstanceEditDialog.tsx", import.meta.url),
+  "utf8",
+);
+const modelFieldSource = await readFile(
+  new URL("./EditAgentModelField.tsx", import.meta.url),
+  "utf8",
+);
+
+/** JSX wraps wherever the formatter decides; match on collapsed whitespace. */
+const collapsedDialog = dialogSource.replace(/\s+/g, " ");
+
+test("a linked definition owns the AI config", () => {
+  assert.equal(definitionOwnsAiConfig({ id: "persona-1" }), true);
+});
+
+test("a definition-less instance owns its own AI config", () => {
+  // Both absent forms: no personaId at all, and a personaId whose definition
+  // has not resolved (or no longer exists — an orphan still edits locally).
+  assert.equal(definitionOwnsAiConfig(null), false);
+  assert.equal(definitionOwnsAiConfig(undefined), false);
+});
+
+test("the submit path omits all three definition-owned fields", () => {
+  for (const field of ["systemPrompt", "model", "provider"]) {
+    assert.match(
+      collapsedDialog,
+      new RegExp(`${field}: aiConfigIsDefinitionOwned \\? undefined`),
+      `${field} must be omitted from UpdateManagedAgentInput when the definition owns it`,
+    );
+  }
+});
+
+test("no seam re-derives definition ownership on its own", () => {
+  // One call, at the top of the component. Everything else reads the result.
+  const derivations = dialogSource.match(/definitionOwnsAiConfig\(/g) ?? [];
+  assert.equal(derivations.length, 1);
+  assert.doesNotMatch(dialogSource, /linkedPersona != null/);
+});
+
+test("the shared disabled flag is the one the submit path reads", () => {
+  assert.match(
+    collapsedDialog,
+    /const aiFieldsDisabled = updateMutation\.isPending \|\| aiConfigIsDefinitionOwned;/,
+  );
+});
+
+test("every control for a definition-owned field is disabled with it", () => {
+  // The dropdown and its custom-value escape hatch, for both fields. Missing
+  // one of the four leaves a live control over a value the save discards.
+  // The model pair lives in EditAgentModelField, which the dialog hands the
+  // same flag; the assertion below pins that hand-off.
+  for (const [source, id, flag] of [
+    [collapsedDialog, "edit-agent-llm-provider", "aiFieldsDisabled"],
+    [collapsedDialog, "edit-agent-custom-provider", "aiFieldsDisabled"],
+    [modelFieldSource, "edit-agent-model", "disabled"],
+    [modelFieldSource, "edit-agent-custom-model", "disabled"],
+  ]) {
+    const controlAt = source.indexOf(`id="${id}"`);
+    assert.ok(controlAt > 0, `${id} not found`);
+    // `disabled` precedes `id` in every control in these files (props are
+    // alphabetized), so scan back to the start of the element.
+    const elementAt = source.lastIndexOf("<", controlAt);
+    assert.match(
+      source.slice(elementAt, controlAt),
+      new RegExp(`disabled=\\{[^}]*${flag}`),
+      `${id} must be disabled when the definition owns the value`,
+    );
+  }
+
+  assert.match(
+    collapsedDialog,
+    /<EditAgentModelField disabled=\{aiFieldsDisabled\}/,
+  );
+});
+
+test("a definition-owned provider never blocks Save", () => {
+  // Changing harness re-derives the provider draft and can blank it. With the
+  // provider control read-only that would be an unrepairable disabled Save on
+  // a value this form does not send at all.
+  assert.match(
+    collapsedDialog,
+    /const providerValid = aiConfigIsDefinitionOwned \|\| isEditAgentProviderSaveValid\(\{/,
+  );
+});
+
+test("the read-only summary offers a route to the definition", () => {
+  // A disabled control with no way to reach the real one is the same dead end
+  // in a different costume.
+  assert.match(
+    collapsedDialog,
+    /onEditDefinition=\{ aiConfigIsDefinitionOwned \? handleEditLinkedPersona : undefined \}/,
+  );
+});
diff --git a/desktop/src/features/agents/ui/personaRuntimeModel.ts b/desktop/src/features/agents/ui/personaRuntimeModel.ts
index 20d789c4eb..2851a6dc63 100644
--- a/desktop/src/features/agents/ui/personaRuntimeModel.ts
+++ b/desktop/src/features/agents/ui/personaRuntimeModel.ts
@@ -291,6 +291,26 @@ export function isEditAgentProviderSaveValid({
   );
 }
 
+/**
+ * Whether the linked definition — not this instance — owns model, LLM
+ * provider, and system prompt.
+ *
+ * `resolve_effective_config` reads those three from the definition for a
+ * linked instance and never consults the record's own bytes (#1968), so the
+ * instance submit path omits them and `update_managed_agent` drops them again
+ * server-side. An editable control for them on the instance form is therefore
+ * a control that reports a successful save and changes nothing.
+ *
+ * Presentation and omission must derive from THIS predicate, not from two
+ * independent `linkedPersona != null` checks — the dead-control bug it fixes
+ * was exactly the write path moving while the control stayed live.
+ */
+export function definitionOwnsAiConfig(
+  linkedPersona: unknown | null | undefined,
+): boolean {
+  return linkedPersona != null;
+}
+
 export function envVarsEqual(
   a: Record<string, string>,
   b: Record<string, string>,
diff --git a/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx b/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
index a907f87245..641b81490b 100644
--- a/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
+++ b/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
@@ -35,10 +35,12 @@ import {
   AuxiliaryPanelHeader,
   AuxiliaryPanelHeaderActions,
   AuxiliaryPanelHeaderGroup,
-  AuxiliaryPanelHeaderTitleBlock,
 } from "@/shared/layout/AuxiliaryPanel";
 import { Button } from "@/shared/ui/button";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { resolveUserLabel } from "@/features/profile/lib/identity";
+import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { normalizePubkey } from "@/shared/lib/pubkey";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -237,6 +239,15 @@ export function AgentSessionThreadPanel({
       ? `#${scopeChannelName}`
       : "1 channel"
     : "All channels";
+  const agentProfile = profiles?.[normalizePubkey(agent.pubkey)] ?? null;
+  const agentLabel = resolveUserLabel({
+    pubkey: agent.pubkey,
+    fallbackName: agent.name,
+    profiles,
+    preferResolvedSelfLabel: true,
+  });
+  const viewLabel = showRawFeed ? "Raw ACP activity" : "Activity";
+  const headerScopeLabel = `${viewLabel} · ${scopeLabel}`;
   const animateActivity = useTranscriptAnimationEnabled();
   const showTimestamps = useTranscriptTimestampsEnabled();
   async function handleInterruptTurn() {
@@ -417,19 +428,39 @@ export function AgentSessionThreadPanel({
         backButtonTestId="agent-session-back"
         onBack={onBack}
       >
-        <AuxiliaryPanelHeaderTitleBlock
-          subtitle={lastUpdatedLabel}
-          subtitleTitle={lastUpdatedTitle}
-          title={showRawFeed ? "Raw ACP Activity" : "Activity"}
+        <ProfileAvatar
+          avatarUrl={agentProfile?.avatarUrl ?? null}
+          className="size-9"
+          label={agentLabel}
+          testId="agent-session-agent-avatar"
         />
-        {/* Scope label: makes channel-targeted vs all-channels state obvious
-            (an all-channels pane can look "wrong" without it). */}
-        <span
-          className="min-w-0 shrink truncate text-xs text-muted-foreground"
-          data-testid="agent-session-scope-label"
-        >
-          {scopeLabel}
-        </span>
+        <div className="min-w-0 flex-1">
+          <h2
+            className="truncate text-sm font-semibold leading-5"
+            data-testid="agent-session-agent-name"
+            title={agentLabel}
+          >
+            {agentLabel}
+          </h2>
+          <div className="flex min-w-0 items-center gap-1 text-xs text-muted-foreground">
+            <p
+              className="min-w-0 flex-1 truncate"
+              data-testid="agent-session-scope-label"
+            >
+              {headerScopeLabel}
+            </p>
+            <span aria-hidden="true" className="shrink-0">
+              ·
+            </span>
+            <span
+              className="shrink-0"
+              data-testid="agent-session-recency-label"
+              title={lastUpdatedTitle}
+            >
+              {lastUpdatedLabel}
+            </span>
+          </div>
+        </div>
       </AuxiliaryPanelHeaderGroup>
       {agentHeaderActions}
     </>
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 c87617ce9b..7b9bf2b79f 100644
--- a/desktop/src/features/channels/ui/ChannelMembersBar.tsx
+++ b/desktop/src/features/channels/ui/ChannelMembersBar.tsx
@@ -11,9 +11,15 @@ import {
   useManagedAgentsQuery,
   useRelayAgentsQuery,
 } from "@/features/agents/hooks";
+import { mergeChannelKnownAgentPubkeys } from "@/features/agents/knownAgentPubkeys";
 import { requestOpenCreateAgent } from "@/features/agents/openCreateAgentEvent";
 import { useChannelMembersQuery } from "@/features/channels/hooks";
+import {
+  getDmHuddleMemberPubkeys,
+  hasOtherDmParticipant,
+} from "@/features/channels/lib/dmHuddleMembers";
 import { canStartHuddleInChannel } from "@/features/channels/lib/huddleAvailability";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
 import type { Channel } from "@/shared/api/types";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { Button } from "@/shared/ui/button";
@@ -64,6 +70,41 @@ export function ChannelMembersBar({
   const managedAgentsQuery = useManagedAgentsQuery();
   const relayAgentsQuery = useRelayAgentsQuery();
   const members = membersQuery.data ?? [];
+  const dmProfilesQuery = useUsersBatchQuery(
+    channel.channelType === "dm" ? channel.participantPubkeys : [],
+    { enabled: channel.channelType === "dm" },
+  );
+  const huddleAgentPubkeys = React.useMemo(() => {
+    const pubkeys = new Set(
+      mergeChannelKnownAgentPubkeys(
+        membersQuery.data,
+        managedAgentsQuery.data,
+        relayAgentsQuery.data,
+      ),
+    );
+    for (const [pubkey, profile] of Object.entries(
+      dmProfilesQuery.data?.profiles ?? {},
+    )) {
+      if (profile.isAgent) pubkeys.add(normalizePubkey(pubkey));
+    }
+    return pubkeys;
+  }, [
+    dmProfilesQuery.data?.profiles,
+    managedAgentsQuery.data,
+    membersQuery.data,
+    relayAgentsQuery.data,
+  ]);
+  const huddleMemberPubkeys = React.useMemo(
+    () => getDmHuddleMemberPubkeys(channel, huddleAgentPubkeys, currentPubkey),
+    [channel, currentPubkey, huddleAgentPubkeys],
+  );
+  const huddleMemberPubkeysPending =
+    hasOtherDmParticipant(channel, currentPubkey) &&
+    (membersQuery.isPending ||
+      managedAgentsQuery.isPending ||
+      relayAgentsQuery.isPending ||
+      dmProfilesQuery.isPending ||
+      dmProfilesQuery.isPlaceholderData);
   const memberCount = membersQuery.data?.length ?? channel.memberCount;
   const providers = React.useMemo(
     () =>
@@ -117,7 +158,7 @@ export function ChannelMembersBar({
         try {
           await startHuddle(
             channel.id,
-            [],
+            [...huddleMemberPubkeys],
             buildHuddleChannelName({
               channel,
               currentPubkey,
@@ -133,7 +174,9 @@ export function ChannelMembersBar({
         }
       }}
       renderMode={variant === "compact" ? "menu-item" : "button"}
-      startDisabled={!canStartHuddle || isStartingHuddle}
+      startDisabled={
+        !canStartHuddle || isStartingHuddle || huddleMemberPubkeysPending
+      }
     />
   );
 
diff --git a/desktop/src/features/channels/ui/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index 92fa172ff5..770c45e445 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -21,10 +21,7 @@ import {
   getDmHuddleMemberPubkeys,
   hasOtherDmParticipant,
 } from "@/features/channels/lib/dmHuddleMembers";
-import {
-  buildVideoReviewCommentsByRootId,
-  buildVideoReviewContextForMessage,
-} from "@/features/messages/lib/videoReviewContext";
+import { buildVideoReviewContextsByMessageId } from "@/features/messages/lib/videoReviewContext";
 import { useComposerHeightPadding } from "@/features/messages/ui/useComposerHeightPadding";
 import { UserProfilePanel } from "@/features/profile/ui/UserProfilePanel";
 import { ChannelFindBar } from "@/features/search/ui/ChannelFindBar";
@@ -39,6 +36,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 {
@@ -150,6 +148,7 @@ export const ChannelPane = React.memo(function ChannelPane({
   profilePanelTab,
   profilePanelView,
   targetMessageId,
+  threadAllMessages,
   threadHeadMessage,
   threadMessages,
   threadMessagesPending = false,
@@ -410,7 +409,11 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel?.id ?? null,
   );
   const hasComposerBotActivity = composerWorkingBotPubkeys.length > 0;
-  const hasComposerBottomActivity = hasComposerBotActivity || hasTypingActivity;
+  // Background card mints surface in the same rail ("Minting card…" chip),
+  // so they must also reserve the activity row.
+  const hasCardMintActivity = useCardMintJobs().length > 0;
+  const hasComposerBottomActivity =
+    hasComposerBotActivity || hasTypingActivity || hasCardMintActivity;
   const threadComposerBotTypingPubkeys = React.useMemo(() => {
     if (!openThreadHeadId) return [];
     return botTypingEntries
@@ -472,25 +475,26 @@ export const ChannelPane = React.memo(function ChannelPane({
     threadHeadMessage,
     threadMessages,
   });
-  const videoReviewCommentsByRootId = React.useMemo(
-    () => buildVideoReviewCommentsByRootId(messages),
-    [messages],
-  );
   const activeVideoReviewCommentSender = activeChannel?.archivedAt
     ? undefined
     : onSendVideoReviewComment;
-  const threadHeadVideoReviewContext = React.useMemo(() => {
-    if (!threadHeadMessage) {
-      return undefined;
+  const threadVideoReviewContextsByMessageId = React.useMemo(() => {
+    const messagesById = new Map(
+      messages.map((message) => [message.id, message]),
+    );
+    if (threadHeadMessage) {
+      messagesById.set(threadHeadMessage.id, threadHeadMessage);
+    }
+    for (const message of threadAllMessages) {
+      messagesById.set(message.id, message);
     }
 
-    return buildVideoReviewContextForMessage({
+    return buildVideoReviewContextsByMessageId({
       channelId: activeChannel?.id ?? null,
       channelName: activeChannel?.name,
       channelType: activeChannel?.channelType ?? null,
-      comments: videoReviewCommentsByRootId.get(threadHeadMessage.id) ?? [],
       isSendingVideoReviewComment: isSending,
-      message: threadHeadMessage,
+      messages: [...messagesById.values()],
       onSendVideoReviewComment: activeVideoReviewCommentSender,
       onToggleReaction,
       profiles,
@@ -499,10 +503,11 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel,
     activeVideoReviewCommentSender,
     isSending,
+    messages,
     onToggleReaction,
     profiles,
+    threadAllMessages,
     threadHeadMessage,
-    videoReviewCommentsByRootId,
   ]);
 
   const isOverlay = useIsThreadPanelOverlay();
@@ -676,6 +681,7 @@ export const ChannelPane = React.memo(function ChannelPane({
             onMarkUnread={onMarkUnread}
             onMarkRead={onMarkRead}
             onReply={activeChannel?.archivedAt ? undefined : onOpenThread}
+            onOpenThread={onOpenThread}
             channelName={activeChannel?.name}
             channelType={activeChannel?.channelType ?? null}
             isSendingVideoReviewComment={isSending}
@@ -876,7 +882,9 @@ export const ChannelPane = React.memo(function ChannelPane({
                 scrollTargetHighlights={!layoutScrollTargetId}
                 scrollTargetId={layoutScrollTargetId ?? threadScrollTargetId}
                 threadHead={threadHeadMessage}
-                threadHeadVideoReviewContext={threadHeadVideoReviewContext}
+                videoReviewContextsByMessageId={
+                  threadVideoReviewContextsByMessageId
+                }
                 widthPx={threadPanelWidthPx}
                 threadReplies={threadMessages}
                 threadRepliesPending={threadMessagesPending}
diff --git a/desktop/src/features/channels/ui/ChannelPane.types.ts b/desktop/src/features/channels/ui/ChannelPane.types.ts
index 5a27d85c4d..7257d8cd55 100644
--- a/desktop/src/features/channels/ui/ChannelPane.types.ts
+++ b/desktop/src/features/channels/ui/ChannelPane.types.ts
@@ -151,6 +151,7 @@ export type ChannelPaneProps = {
   profilePanelTab: ProfilePanelTab;
   profilePanelView: ProfilePanelView;
   threadHeadMessage: TimelineMessage | null;
+  threadAllMessages: TimelineMessage[];
   threadMessages: MainTimelineEntry[];
   threadMessagesPending?: boolean;
   threadPanelWidthPx: number;
diff --git a/desktop/src/features/channels/ui/ChannelScreen.tsx b/desktop/src/features/channels/ui/ChannelScreen.tsx
index 52b3ae7fb7..b4d33b4776 100644
--- a/desktop/src/features/channels/ui/ChannelScreen.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreen.tsx
@@ -48,6 +48,7 @@ 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 {
@@ -483,6 +484,9 @@ 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,
     handleCancelThreadReply,
@@ -506,6 +510,7 @@ export function ChannelScreen({
     markRevealedRepliesRead,
     openThreadHeadId: effectiveOpenThreadHeadId,
     onOptimisticOpenThreadHeadIdChange: setOptimisticOpenThreadHeadId,
+    onRequestEmptyEditDelete: setEmptyDeleteId,
     sendMessageMutation,
     setExpandedThreadReplyIds,
     setEditTargetId,
@@ -691,6 +696,7 @@ export function ChannelScreen({
       channelManagementOpen,
   );
   const displayedThreadHeadMessage = threadPanelData.threadHead;
+  const displayedThreadAllMessages = threadPanelData.messages;
   const displayedThreadMessages = threadPanelData.visibleReplies;
   const displayedThreadReplyTargetMessage = threadPanelData.replyTargetMessage;
   const displayedThreadFirstUnreadReplyId = displayedThreadHeadMessage
@@ -801,6 +807,19 @@ export function ChannelScreen({
           open={welcomeAgentCreate.isOpen}
           sendError={welcomeAgentCreate.error}
         />
+        <DeleteMessageConfirmDialog
+          onConfirm={() => {
+            if (emptyDeleteId) {
+              setEditTargetId(null);
+              void handleDelete({ id: emptyDeleteId });
+            }
+            setEmptyDeleteId(null);
+          }}
+          onOpenChange={(open) => {
+            if (!open) setEmptyDeleteId(null);
+          }}
+          open={emptyDeleteId !== null}
+        />
         <div
           className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden"
           ref={channelContentRef}
@@ -944,6 +963,7 @@ export function ChannelScreen({
                   firstUnreadMessageId={firstUnreadMessageId}
                   unreadCount={unreadCount}
                   targetMessageId={mainTimelineTargetMessageId}
+                  threadAllMessages={displayedThreadAllMessages}
                   threadHeadMessage={displayedThreadHeadMessage}
                   threadMessages={displayedThreadMessages}
                   threadMessagesPending={threadRepliesQuery.isPending}
diff --git a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
index a3a8a20231..4c545baf68 100644
--- a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
@@ -13,6 +13,7 @@ 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";
@@ -65,6 +66,7 @@ export function ChannelScreenHeader({
   const isGroupDm =
     activeChannel?.channelType === "dm" &&
     activeDmHeaderParticipants.length > 1;
+  const activeDmParticipant = activeDmHeaderParticipants[0] ?? null;
   const showJoinButton =
     activeChannel !== null &&
     !activeChannel.isMember &&
@@ -113,6 +115,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 +173,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/unreadReadMarker.test.mjs b/desktop/src/features/channels/unreadReadMarker.test.mjs
index e05e2ba0b2..6ea0916413 100644
--- a/desktop/src/features/channels/unreadReadMarker.test.mjs
+++ b/desktop/src/features/channels/unreadReadMarker.test.mjs
@@ -18,6 +18,7 @@ import {
 } from "./useUnreadChannels.ts";
 import {
   isChannelUnreadTriggerKind,
+  trackSeenEvent,
   withChannelTagFallback,
 } from "./useLiveChannelUpdates.ts";
 import {
@@ -90,6 +91,16 @@ test("live event with h tag is preserved", () => {
   assert.equal(withChannelTagFallback(message, "other-channel"), message);
 });
 
+test("notification event guard suppresses reconnect replay and stays bounded", () => {
+  const seen = new Set();
+
+  assert.equal(trackSeenEvent(seen, "event-a", 2), true);
+  assert.equal(trackSeenEvent(seen, "event-a", 2), false);
+  assert.equal(trackSeenEvent(seen, "event-b", 2), true);
+  assert.equal(trackSeenEvent(seen, "event-c", 2), true);
+  assert.deepEqual([...seen], ["event-b", "event-c"]);
+});
+
 test("dmHuddleStart_isDmOnlyUnreadTrigger", () => {
   assert.equal(
     isChannelUnreadTriggerKind(KIND_HUDDLE_STARTED, true),
diff --git a/desktop/src/features/channels/useChannelPaneHandlers.ts b/desktop/src/features/channels/useChannelPaneHandlers.ts
index 8c5f54fffc..53170257a4 100644
--- a/desktop/src/features/channels/useChannelPaneHandlers.ts
+++ b/desktop/src/features/channels/useChannelPaneHandlers.ts
@@ -25,6 +25,7 @@ export function useChannelPaneHandlers({
   getReplyDescendantIdsForMessage,
   markRevealedRepliesRead,
   onOptimisticOpenThreadHeadIdChange,
+  onRequestEmptyEditDelete,
   openThreadHeadId,
   sendMessageMutation,
   setExpandedThreadReplyIds,
@@ -45,6 +46,7 @@ export function useChannelPaneHandlers({
   onOptimisticOpenThreadHeadIdChange: React.Dispatch<
     React.SetStateAction<string | null | undefined>
   >;
+  onRequestEmptyEditDelete: (eventId: string) => void;
   openThreadHeadId: string | null;
   sendMessageMutation: ReturnType<typeof useSendMessageMutation>;
   setExpandedThreadReplyIds: React.Dispatch<React.SetStateAction<Set<string>>>;
@@ -154,6 +156,22 @@ export function useChannelPaneHandlers({
         return;
       }
 
+      // Clearing an edit to empty (no text, no attachments) is the keyboard
+      // shorthand for "Delete message". Rather than publish an empty edit,
+      // route it through the same "Delete message?" confirmation the Delete
+      // button shows. Keep edit mode active while the dialog is open so Cancel
+      // returns the user to the editor; edit mode is exited only once the
+      // deletion is confirmed (see ChannelScreen's onConfirm). Single decision
+      // point for both the main timeline and thread panel — both route
+      // edit-save through here.
+      const isEmptyDeletion =
+        content.trim().length === 0 &&
+        (mediaTags === undefined || mediaTags.length === 0);
+      if (isEmptyDeletion) {
+        onRequestEmptyEditDelete(eventId);
+        return;
+      }
+
       await editMutateRef.current({
         eventId,
         content,
@@ -162,7 +180,7 @@ export function useChannelPaneHandlers({
       });
       setEditTargetId(null);
     },
-    [setEditTargetId],
+    [onRequestEmptyEditDelete, setEditTargetId],
   );
 
   const handleOpenThread = React.useCallback(
diff --git a/desktop/src/features/channels/useLiveChannelUpdates.ts b/desktop/src/features/channels/useLiveChannelUpdates.ts
index aeb3abb905..800467b6ea 100644
--- a/desktop/src/features/channels/useLiveChannelUpdates.ts
+++ b/desktop/src/features/channels/useLiveChannelUpdates.ts
@@ -110,13 +110,19 @@ function isExternalMentionEvent(event: RelayEvent, currentPubkey: string) {
   );
 }
 
-function trackSeenEvent(seenEventIds: Set<string>, eventId: string): boolean {
+const SEEN_NOTIFICATION_EVENT_LIMIT = 5_000;
+
+export function trackSeenEvent(
+  seenEventIds: Set<string>,
+  eventId: string,
+  limit = 200,
+): boolean {
   if (seenEventIds.has(eventId)) {
     return false;
   }
 
   seenEventIds.add(eventId);
-  if (seenEventIds.size > 200) {
+  if (seenEventIds.size > limit) {
     const oldestEventId = seenEventIds.values().next().value;
     if (oldestEventId) {
       seenEventIds.delete(oldestEventId);
@@ -135,6 +141,11 @@ export function useLiveChannelUpdates(
   const normalizedCurrentPubkey =
     options.currentPubkey?.trim().toLowerCase() ?? "";
   const seenMentionEventIdsRef = React.useRef(new Set<string>());
+  // Reconnect replay overlaps each live filter by five seconds so no message is
+  // lost at the boundary. Keep one shared guard for every notification side
+  // effect: the same event can be replayed repeatedly while a relay flaps, and
+  // mention events also arrive through both the channel and mention filters.
+  const seenNotificationEventIdsRef = React.useRef(new Set<string>());
   const channelsInvalidateRef = React.useRef<TrailingDebounce | null>(null);
   if (channelsInvalidateRef.current === null) {
     channelsInvalidateRef.current = createTrailingDebounce(() => {
@@ -164,7 +175,6 @@ export function useLiveChannelUpdates(
       ),
     [channels],
   );
-  const seenDmEventIdsRef = React.useRef(new Set<string>());
   const dmSubscriptionStartedAtRef = React.useRef(0);
 
   // Reset subscription timestamp when identity changes.
@@ -181,44 +191,42 @@ export function useLiveChannelUpdates(
     [channels],
   );
 
-  const handleDmEvent = React.useEffectEvent((event: RelayEvent) => {
-    // Only human-visible message kinds should fire DM notifications.
-    if (!isDmNotifiableKind(event.kind)) {
-      return;
-    }
-
-    // Suppress backlog events that predate our subscription — these are
-    // historical replays, not live messages.
-    if (event.created_at < dmSubscriptionStartedAtRef.current) {
-      return;
-    }
+  const handleDmEvent = React.useEffectEvent(
+    (event: RelayEvent, isFirstNotificationDelivery: boolean) => {
+      // Only human-visible message kinds should fire DM notifications.
+      if (!isDmNotifiableKind(event.kind) || !isFirstNotificationDelivery) {
+        return;
+      }
 
-    const channelId = getChannelIdFromTags(event.tags);
-    if (!channelId) {
-      return;
-    }
+      // Suppress backlog events that predate our subscription — these are
+      // historical replays, not live messages.
+      if (event.created_at < dmSubscriptionStartedAtRef.current) {
+        return;
+      }
 
-    if (!isExternalMentionEvent(event, normalizedCurrentPubkey)) {
-      return;
-    }
+      const channelId = getChannelIdFromTags(event.tags);
+      if (!channelId) {
+        return;
+      }
 
-    const dmChannel = dmChannelMap.get(channelId);
-    if (!dmChannel) {
-      return;
-    }
+      if (!isExternalMentionEvent(event, normalizedCurrentPubkey)) {
+        return;
+      }
 
-    if (!trackSeenEvent(seenDmEventIdsRef.current, event.id)) {
-      return;
-    }
+      const dmChannel = dmChannelMap.get(channelId);
+      if (!dmChannel) {
+        return;
+      }
 
-    // Don't fire a notification for the channel the user is already viewing,
-    // unless the notify-while-viewing setting opts in.
-    if (channelId === activeChannelId && !options.notifyForActiveChannel) {
-      return;
-    }
+      // Don't fire a notification for the channel the user is already viewing,
+      // unless the notify-while-viewing setting opts in.
+      if (channelId === activeChannelId && !options.notifyForActiveChannel) {
+        return;
+      }
 
-    options.onDmMessage?.(event, dmChannel);
-  });
+      options.onDmMessage?.(event, dmChannel);
+    },
+  );
 
   const handleIncomingMessage = React.useEffectEvent((event: RelayEvent) => {
     const channelId = getChannelIdFromTags(event.tags);
@@ -226,12 +234,6 @@ export function useLiveChannelUpdates(
       return;
     }
 
-    // Track DM events even for the active channel so the dedup set stays
-    // current. The handler itself skips firing the notification callback
-    // when the user is already viewing the DM (unless opted in via
-    // notifyForActiveChannel).
-    handleDmEvent(event);
-
     if (!liveChannelIds.has(channelId)) {
       if (channelId !== activeChannelId) {
         invalidateChannelsDebounced();
@@ -263,9 +265,21 @@ export function useLiveChannelUpdates(
       isUnreadTriggerKind &&
       (normalizedCurrentPubkey.length === 0 ||
         event.pubkey.toLowerCase() !== normalizedCurrentPubkey);
+    const isFirstNotificationDelivery =
+      !isExternalTriggerEvent ||
+      trackSeenEvent(
+        seenNotificationEventIdsRef.current,
+        event.id,
+        SEEN_NOTIFICATION_EVENT_LIMIT,
+      );
     const isThreadedReply = isThreadReply(event.tags);
 
-    if (isExternalTriggerEvent) {
+    // DM alerts and every other notification side effect share this delivery
+    // decision, preventing a replayed event from escaping through a second
+    // callback path.
+    handleDmEvent(event, isFirstNotificationDelivery);
+
+    if (isExternalTriggerEvent && isFirstNotificationDelivery) {
       const shouldNotify = shouldNotifyForEvent(
         event,
         normalizedCurrentPubkey,
diff --git a/desktop/src/features/communities/hostedCommunityApi.ts b/desktop/src/features/communities/hostedCommunityApi.ts
index 16f9f92567..0aca17a17d 100644
--- a/desktop/src/features/communities/hostedCommunityApi.ts
+++ b/desktop/src/features/communities/hostedCommunityApi.ts
@@ -1,7 +1,7 @@
 import { invoke } from "@tauri-apps/api/core";
 
 export const HOSTED_COMMUNITY_SUFFIX = "communities.buzz.xyz";
-export const HOSTED_COMMUNITY_LIMIT = 3;
+export const HOSTED_COMMUNITY_LIMIT = 5;
 export const VALID_HOSTED_COMMUNITY_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 export type BuilderlabAuth = {
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/huddle/HuddleContext.tsx b/desktop/src/features/huddle/HuddleContext.tsx
index 804eb4bc0e..03620838a3 100644
--- a/desktop/src/features/huddle/HuddleContext.tsx
+++ b/desktop/src/features/huddle/HuddleContext.tsx
@@ -339,6 +339,28 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
     [],
   );
 
+  /**
+   * Clean up only this provider's media after its start token is superseded.
+   * The action that changed the token owns backend teardown; issuing a global
+   * leave here could terminate a replacement huddle started by a new provider.
+   */
+  const cleanupSupersededStart = React.useCallback(
+    (worklet: AudioWorkletHandle | null) => {
+      try {
+        worklet?.stop();
+      } catch {
+        /* best-effort */
+      }
+      workletRef.current = null;
+      rustActiveRef.current = false;
+      setLocalAudioTrack(null);
+      setMicConnected(false);
+      setEphemeralChannelId(null);
+      setActiveSpeakers([]);
+    },
+    [],
+  );
+
   /** Shared media setup: get mic, setup AudioWorklet, confirm active.
    *  Used by both startHuddle and joinHuddle after the Rust backend call succeeds. */
   const connectAndSetupMedia = React.useCallback(
@@ -443,7 +465,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           await connectAndSetupMedia(joinInfo, myToken);
         } catch (e) {
           if (e instanceof Error && e.message === "superseded") {
-            await cleanupFailedStart(workletRef.current, true);
+            cleanupSupersededStart(workletRef.current);
             return;
           }
           throw e;
@@ -466,7 +488,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, connectAndSetupMedia],
+    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
   );
 
   const joinHuddle = React.useCallback(
@@ -489,7 +511,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           await connectAndSetupMedia(joinInfo, myToken);
         } catch (e) {
           if (e instanceof Error && e.message === "superseded") {
-            await cleanupFailedStart(workletRef.current, false);
+            cleanupSupersededStart(workletRef.current);
             return;
           }
           throw e;
@@ -512,7 +534,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, connectAndSetupMedia],
+    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
   );
 
   useTtsSubscription(ephemeralChannelId, selfPubkeyRef);
diff --git a/desktop/src/features/huddle/components/HuddleBar.tsx b/desktop/src/features/huddle/components/HuddleBar.tsx
index 35d660e475..758726cf58 100644
--- a/desktop/src/features/huddle/components/HuddleBar.tsx
+++ b/desktop/src/features/huddle/components/HuddleBar.tsx
@@ -242,7 +242,10 @@ export function HuddleBar({
 
     // Primary: listen for Rust-emitted state change events
     listen<HuddleState>("huddle-state-changed", (event) => {
-      if (!cancelled) applyIncomingState(event.payload);
+      if (!cancelled) {
+        stateGenerationRef.current += 1;
+        applyIncomingState(event.payload);
+      }
     }).then((fn) => {
       if (cancelled) fn();
       else unlisten = fn;
@@ -757,14 +760,11 @@ export function HuddleBar({
                   transcriptionEnabled ? "Stop transcript" : "Start transcript"
                 }
                 aria-pressed={transcriptionEnabled}
-                className={cn(
-                  "buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md",
-                  transcriptionEnabled && "text-foreground",
-                )}
+                className="buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md"
                 onClick={() => void handleToggleTranscript()}
                 size="icon"
                 type="button"
-                variant={transcriptionEnabled ? "secondary" : "ghost"}
+                variant="ghost"
               >
                 <Captions className="h-4 w-4" />
               </Button>
diff --git a/desktop/src/features/huddle/components/ParticipantList.tsx b/desktop/src/features/huddle/components/ParticipantList.tsx
index c445711dfc..9454f51f5b 100644
--- a/desktop/src/features/huddle/components/ParticipantList.tsx
+++ b/desktop/src/features/huddle/components/ParticipantList.tsx
@@ -3,6 +3,7 @@ import * as React from "react";
 
 import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
@@ -86,19 +87,25 @@ export function HuddleParticipantsControl({
                 className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5"
                 key={pubkey}
               >
-                {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" />
-                )}
+                <UserProfilePopover
+                  pubkey={pubkey}
+                  triggerAriaLabel={`Open profile for ${displayName}`}
+                  triggerElement="span"
+                >
+                  {profile?.displayName || profile?.avatarUrl ? (
+                    <ProfileAvatar
+                      avatarUrl={profile.avatarUrl ?? null}
+                      label={profile.displayName || truncatePubkey(pubkey)}
+                      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" />
+                  )}
+                </UserProfilePopover>
 
                 <div className="min-w-0 flex-1">
                   <div className="truncate text-sm font-medium">
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..5a5a29afa5
--- /dev/null
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
@@ -0,0 +1,200 @@
+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) => Promise<void>,
+  onError: (error: unknown) => void,
+  initiallyEnabled = true,
+  onDrop: (routeId: number, reason: "disabled") => void = () => {},
+): {
+  enqueue: (text: string, routeId?: number) => "queued" | "disabled";
+  setEnabled: (enabled: boolean) => void;
+} {
+  let tail = Promise.resolve();
+  let enabled = initiallyEnabled;
+  let generation = 0;
+  return {
+    enqueue(text, routeId = 0) {
+      if (!enabled) return "disabled";
+      const queuedGeneration = generation;
+      tail = tail
+        .then(() => {
+          if (!enabled || generation !== queuedGeneration) {
+            onDrop(routeId, "disabled");
+            return;
+          }
+          return speak(text, routeId);
+        })
+        .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/useTtsSubscription.ts b/desktop/src/features/huddle/lib/useTtsSubscription.ts
index d534fc0166..64fb96efcd 100644
--- a/desktop/src/features/huddle/lib/useTtsSubscription.ts
+++ b/desktop/src/features/huddle/lib/useTtsSubscription.ts
@@ -1,13 +1,28 @@
 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;
+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 +35,8 @@ export function useTtsSubscription(
 
     let disposed = false;
     let cleanup: (() => void) | null = null;
+    let unlistenHuddleState: (() => void) | null = null;
+    let ttsStateKnown = false;
 
     // ── Agent identity (authoritative, fail-closed) ───────────────────────
     //
@@ -33,43 +50,156 @@ export function useTtsSubscription(
     let agentsLoaded = false;
     const agentPubkeys = new Set<string>();
 
-    async function loadAgentPubkeys() {
+    const speakInOrder = createOrderedSpeaker(
+      async (text, routeId) => {
+        if (!disposed) {
+          console.debug(
+            `[huddle] tts stage=invoke status=attempted route_id=${routeId}`,
+          );
+          try {
+            await invoke("speak_agent_message", { text, routeId });
+            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}`,
+        );
+      },
+    );
+
+    const deliver = ({
+      event,
+      routeId,
+    }: {
+      event: Parameters<typeof routeLiveAgentText>[0];
+      routeId: number;
+    }) => {
+      if (disposed) return;
+      if (!agentsLoaded) {
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=membership_unavailable route_id=${routeId}`,
+        );
+        return;
+      }
+      const result = routeLiveAgentText(
+        event,
+        agentPubkeys,
+        selfPubkeyRef.current,
+        ephemeralChannelId,
+        routeId,
+        speakInOrder.enqueue,
+      );
+      if (result === "queued") {
+        console.debug(
+          `[huddle] tts stage=eligibility status=accepted route_id=${routeId}`,
+        );
+      } else {
+        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);
 
+    // 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-only subscription ───────────────────────────────────────────
-    // subscribeToChannelLive uses `since: now` — the relay never sends
-    // historical backlog. Every event delivered is a live message.
+    // A limit:0 subscription receives future message fan-out while the relay
+    // returns no stored rows, including pre-join rows from the current second.
     // Event-ID dedup handles reconnect replay (same event arriving twice).
     const seenEventIds = new Set<string>();
     const seenOrder: string[] = [];
     const MAX_SEEN_EVENTS = 5000;
-
     relayClient
-      .subscribeToChannelLive(ephemeralChannelId, (event) => {
+      .subscribeLive(buildHuddleTtsLiveFilter(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).
+        // 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);
@@ -78,20 +208,15 @@ export function useTtsSubscription(
           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) {
@@ -106,7 +231,9 @@ export function useTtsSubscription(
 
     return () => {
       disposed = true;
+      speakInOrder.setEnabled(false);
       cleanup?.();
+      unlistenHuddleState?.();
       window.clearInterval(agentRefreshId);
     };
   }, [ephemeralChannelId, selfPubkeyRef]);
diff --git a/desktop/src/features/messages/lib/independentThreadPanel.ts b/desktop/src/features/messages/lib/independentThreadPanel.ts
index 4562928d8b..7652c2508c 100644
--- a/desktop/src/features/messages/lib/independentThreadPanel.ts
+++ b/desktop/src/features/messages/lib/independentThreadPanel.ts
@@ -11,16 +11,18 @@ export function buildIndependentThreadPanel(
   ...formatArgs: Tail<Parameters<typeof formatTimelineMessages>>
 ) {
   if (!rootId) {
-    return buildThreadPanelData([], null, replyTargetId, expandedReplyIds);
+    return {
+      ...buildThreadPanelData([], null, replyTargetId, expandedReplyIds),
+      messages: [],
+    };
   }
   const head = channelEvents.find((event) => event.id === rootId);
   const events = head ? [head, ...replyEvents] : replyEvents;
-  return buildThreadPanelData(
-    formatTimelineMessages(events, ...formatArgs),
-    rootId,
-    replyTargetId,
-    expandedReplyIds,
-  );
+  const messages = formatTimelineMessages(events, ...formatArgs);
+  return {
+    ...buildThreadPanelData(messages, rootId, replyTargetId, expandedReplyIds),
+    messages,
+  };
 }
 
 type Tail<T extends readonly unknown[]> = T extends readonly [
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
index dc33da4f8f..f17a53c661 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
@@ -23,6 +23,13 @@ test("estimateRowHeight: short text is near the floor", () => {
   assert.ok(h >= 60 && h < 120, `expected small, got ${h}`);
 });
 
+test("estimateRowHeight: continuation reserves its uniform padding", () => {
+  const h = estimateRowHeight(msg({ body: "hello" }), {
+    isContinuation: true,
+  });
+  assert.equal(h, 28);
+});
+
 test("estimateRowHeight: many lines reserve more", () => {
   const tall = estimateRowHeight(
     msg({ body: Array.from({ length: 20 }, (_, i) => `line ${i}`).join("\n") }),
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.ts b/desktop/src/features/messages/lib/rowHeightEstimate.ts
index f2fb268167..acefae95d4 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.ts
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.ts
@@ -26,13 +26,13 @@ const TEXT_LINE_HEIGHT = 20;
 const CODE_LINE_HEIGHT = 19;
 const CHARS_PER_LINE = 64; // rough wrap width at the timeline column
 const ROW_CHROME = 26; // author/time header + denser row padding
-const CONTINUATION_ROW_CHROME = 8; // dense row padding only; header/avatar are hidden
+const CONTINUATION_ROW_CHROME = 8; // uniform py-1 padding; header/avatar are hidden
 const MEDIA_BLOCK_MARGIN_TOP = 4; // image/video blocks use mt-1 in markdown
 const REACTION_ROW = 24;
 const PREVIEW_CARD = 70;
 const MESSAGE_ITEM_BOTTOM_PADDING = 10; // TimelineMessageList pb-2.5
 const MIN_ESTIMATE = 60; // never reserve less than the old flat floor
-const CONTINUATION_MIN_ESTIMATE = 34;
+const CONTINUATION_MIN_ESTIMATE = 28;
 
 function mediaHeightFromDim(dim: string | undefined): number {
   const dimensions = dimensionsFromDim(dim);
diff --git a/desktop/src/features/messages/lib/systemEventCopy.test.mjs b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
new file mode 100644
index 0000000000..eeed9d543c
--- /dev/null
+++ b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  describeChannelTextFieldChange,
+  toInlineName,
+} from "./systemEventCopy.ts";
+
+test("a set topic is quoted verbatim", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "Release planning"),
+    "changed the topic to “Release planning”",
+  );
+});
+
+test("a set purpose names the purpose, not the topic", () => {
+  assert.equal(
+    describeChannelTextFieldChange("purpose", "Where we ship from"),
+    "changed the purpose to “Where we ship from”",
+  );
+});
+
+// The relay reports a clear as a change carrying an empty string, so without
+// this branch the timeline reads: changed the topic to “”.
+test("an empty value reads as cleared, not as a change to empty quotes", () => {
+  for (const blank of ["", undefined, null]) {
+    assert.equal(
+      describeChannelTextFieldChange("topic", blank),
+      "cleared the topic",
+    );
+    assert.equal(
+      describeChannelTextFieldChange("purpose", blank),
+      "cleared the purpose",
+    );
+  }
+});
+
+test("a whitespace-only value reads as cleared", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "   \n\t "),
+    "cleared the topic",
+  );
+});
+
+test("surrounding whitespace is trimmed out of the quotes", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "  Release planning  "),
+    "changed the topic to “Release planning”",
+  );
+});
+
+test("no caption announces empty quotes", () => {
+  for (const value of ["", " ", null, undefined, "Real topic"]) {
+    for (const field of ["topic", "purpose"]) {
+      assert.doesNotMatch(
+        describeChannelTextFieldChange(field, value),
+        /“”|""/,
+        `${field} with ${JSON.stringify(value)} must not render empty quotes`,
+      );
+    }
+  }
+});
+
+test("the reader's own name is lowercase mid-sentence", () => {
+  // "added by You" next to an agent's "managed by you" was the inconsistency.
+  assert.equal(toInlineName("You", true), "you");
+});
+
+test("cleared and changed captions use the same noun", () => {
+  // Not "cleared the channel topic" against "changed the topic to …".
+  assert.match(describeChannelTextFieldChange("topic", ""), /\bthe topic\b/);
+  assert.match(
+    describeChannelTextFieldChange("topic", "Ship it"),
+    /\bthe topic\b/,
+  );
+  for (const value of ["", "Ship it"]) {
+    assert.doesNotMatch(
+      describeChannelTextFieldChange("topic", value),
+      /channel topic/,
+    );
+  }
+});
+
+test("every other name keeps its own capitalization", () => {
+  for (const name of [
+    "Alice Chen",
+    "you-know-who",
+    "Someone",
+    "npub1abc…def",
+  ]) {
+    assert.equal(toInlineName(name, false), name);
+  }
+});
+
+test("someone else whose display name is literally You is left alone", () => {
+  // The decisive case: the label is user-controlled, identity is not. Matching
+  // on the string would rewrite this person's name as if they were the reader.
+  assert.equal(toInlineName("You", false), "You");
+  assert.equal(toInlineName("Youssef", false), "Youssef");
+  assert.equal(toInlineName("You Know Who", false), "You Know Who");
+});
+
+test("the reader is lowercased whatever their profile name says", () => {
+  // Self resolution never consults the profile, but the rule keys on identity,
+  // so it does not matter what the label happens to be.
+  assert.equal(toInlineName("Alice Chen", true), "you");
+});
diff --git a/desktop/src/features/messages/lib/systemEventCopy.ts b/desktop/src/features/messages/lib/systemEventCopy.ts
new file mode 100644
index 0000000000..bae6abb09b
--- /dev/null
+++ b/desktop/src/features/messages/lib/systemEventCopy.ts
@@ -0,0 +1,59 @@
+/**
+ * Copy for channel system events (the "joined", "added by", "changed the
+ * topic" captions in the message timeline).
+ *
+ * These live outside `SystemMessageRow` so the wording is a pure function of
+ * the payload and can be asserted directly in tests. Only cases whose caption
+ * is plain text belong here — cases that interpolate a profile link build their
+ * JSX in the component.
+ */
+
+/** Curly quotes, so the caption matches the typography used elsewhere in chat. */
+const OPEN_QUOTE = "“";
+const CLOSE_QUOTE = "”";
+
+export type ChannelTextField = "topic" | "purpose";
+
+/**
+ * Caption for a channel topic or purpose change.
+ *
+ * Bare "the topic" rather than "the channel topic": this row only ever renders
+ * in a channel timeline, under that channel's own header, so naming the channel
+ * again is redundant — and it keeps the cleared and changed captions on the same
+ * noun instead of one saying "channel topic" and the other "topic".
+ *
+ * A blank value means the field was cleared: the relay reports a clear as a
+ * `topic_changed` / `purpose_changed` event carrying an empty string, not as a
+ * separate event type. Without this branch the timeline renders `changed the
+ * topic to ""`, which reads like the topic was set to two quote marks.
+ * Whitespace-only values are treated as cleared for the same reason.
+ */
+export function describeChannelTextFieldChange(
+  field: ChannelTextField,
+  value: string | null | undefined,
+): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return `cleared the ${field}`;
+  }
+  return `changed the ${field} to ${OPEN_QUOTE}${trimmed}${CLOSE_QUOTE}`;
+}
+
+/**
+ * Adjusts a resolved display name for use inside a sentence rather than in the
+ * name slot at the top of a row — "added by you", "removed you from the channel".
+ *
+ * `resolveUserLabel` returns "You" for the current user, which is right standing
+ * alone and wrong mid-phrase. Agent ownership already draws the same distinction
+ * from the other side: `formatOwnerLabel` returns lowercase "you" because it is
+ * only ever read as "managed by you".
+ *
+ * `isSelf` is the caller's pubkey comparison, not an inspection of `label`.
+ * Matching on the string would also rewrite a different person whose display
+ * name happens to be "You" — the label is user-controlled, identity is not.
+ * Every name that isn't the reader's own is a proper noun and is returned
+ * untouched.
+ */
+export function toInlineName(label: string, isSelf: boolean): string {
+  return isSelf ? "you" : label;
+}
diff --git a/desktop/src/features/messages/lib/videoReviewContext.test.mjs b/desktop/src/features/messages/lib/videoReviewContext.test.mjs
index de35d53ce3..8ecb5f5798 100644
--- a/desktop/src/features/messages/lib/videoReviewContext.test.mjs
+++ b/desktop/src/features/messages/lib/videoReviewContext.test.mjs
@@ -5,6 +5,7 @@ import {
   buildVideoReviewCommentsByRootId,
   buildVideoReviewCommentsForRoot,
   buildVideoReviewContextForMessage,
+  buildVideoReviewContextsByMessageId,
   hasVideoAttachment,
 } from "./videoReviewContext.ts";
 
@@ -209,3 +210,30 @@ test("buildVideoReviewContextForMessage posts against the source video", async (
     },
   ]);
 });
+
+test("buildVideoReviewContextsByMessageId includes video replies", () => {
+  const root = message({ id: "root", body: "Review request" });
+  const videoReply = message({
+    id: "video-reply",
+    body: "![video](https://relay/media/a.mp4)",
+    parentId: root.id,
+    rootId: root.id,
+  });
+  const comment = message({
+    id: "comment",
+    body: "[00:01] tighten this",
+    parentId: videoReply.id,
+    rootId: root.id,
+  });
+
+  const contexts = buildVideoReviewContextsByMessageId({
+    channelId: "channel",
+    messages: [root, videoReply, comment],
+  });
+
+  assert.deepEqual([...contexts.keys()], [videoReply.id]);
+  assert.deepEqual(
+    contexts.get(videoReply.id)?.comments.map((item) => item.id),
+    [comment.id],
+  );
+});
diff --git a/desktop/src/features/messages/lib/videoReviewContext.ts b/desktop/src/features/messages/lib/videoReviewContext.ts
index 8d0798db40..f605952f5a 100644
--- a/desktop/src/features/messages/lib/videoReviewContext.ts
+++ b/desktop/src/features/messages/lib/videoReviewContext.ts
@@ -148,3 +148,48 @@ export function buildVideoReviewContextForMessage({
     rootEventId: message.id,
   };
 }
+
+export function buildVideoReviewContextsByMessageId({
+  channelId,
+  channelName,
+  channelType,
+  isSendingVideoReviewComment = false,
+  messages,
+  onSendVideoReviewComment,
+  onToggleReaction,
+  profiles,
+}: {
+  channelId?: string | null;
+  channelName?: string;
+  channelType?: ChannelType | null;
+  isSendingVideoReviewComment?: boolean;
+  messages: TimelineMessage[];
+  onSendVideoReviewComment?: SendVideoReviewComment;
+  onToggleReaction?: ToggleMessageReaction;
+  profiles?: UserProfileLookup;
+}): ReadonlyMap<string, VideoReviewContext> {
+  const contexts = new Map<string, VideoReviewContext>();
+  if (!messages.some(hasVideoAttachment)) {
+    return contexts;
+  }
+
+  const commentsByRootId = buildVideoReviewCommentsByRootId(messages);
+  for (const message of messages) {
+    const context = buildVideoReviewContextForMessage({
+      channelId,
+      channelName,
+      channelType,
+      comments: commentsByRootId.get(message.id) ?? [],
+      isSendingVideoReviewComment,
+      message,
+      onSendVideoReviewComment,
+      onToggleReaction,
+      profiles,
+    });
+    if (context) {
+      contexts.set(message.id, context);
+    }
+  }
+
+  return contexts;
+}
diff --git a/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx b/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx
new file mode 100644
index 0000000000..9802f09efc
--- /dev/null
+++ b/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx
@@ -0,0 +1,53 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import { Button } from "@/shared/ui/button";
+
+/**
+ * The "Delete message?" confirmation. Single definition shared by every
+ * surface that deletes a message — the message action menu (MessageActionBar)
+ * and the empty-edit delete path (clearing an edit to empty and hitting accept
+ * routes here, so it prompts exactly like the menu's Delete does). `onConfirm`
+ * fires when the user presses Delete; the caller owns the actual deletion.
+ */
+export function DeleteMessageConfirmDialog({
+  open,
+  onOpenChange,
+  onConfirm,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <AlertDialog onOpenChange={onOpenChange} open={open}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete message?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This will permanently delete this message and cannot be undone.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel asChild>
+            <Button type="button" variant="outline">
+              Cancel
+            </Button>
+          </AlertDialogCancel>
+          <AlertDialogAction asChild>
+            <Button onClick={onConfirm} type="button" variant="destructive">
+              Delete
+            </Button>
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
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/MessageActionBar.tsx b/desktop/src/features/messages/ui/MessageActionBar.tsx
index ba45bc62fb..967e50f5d2 100644
--- a/desktop/src/features/messages/ui/MessageActionBar.tsx
+++ b/desktop/src/features/messages/ui/MessageActionBar.tsx
@@ -35,17 +35,8 @@ import { copyTextToClipboard } from "@/shared/lib/clipboard";
 import { emojiDisplayName } from "@/shared/lib/emojiName";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
 import { KIND_HUDDLE_STARTED } from "@/shared/constants/kinds";
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from "@/shared/ui/alert-dialog";
 import { Button } from "@/shared/ui/button";
+import { DeleteMessageConfirmDialog } from "./DeleteMessageConfirmDialog";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -277,35 +268,11 @@ function MoreActionsMenu({
       </DropdownMenu>
 
       {onDelete ? (
-        <AlertDialog
+        <DeleteMessageConfirmDialog
+          onConfirm={() => onDelete(message)}
           onOpenChange={setIsDeleteDialogOpen}
           open={isDeleteDialogOpen}
-        >
-          <AlertDialogContent>
-            <AlertDialogHeader>
-              <AlertDialogTitle>Delete message?</AlertDialogTitle>
-              <AlertDialogDescription>
-                This will permanently delete this message and cannot be undone.
-              </AlertDialogDescription>
-            </AlertDialogHeader>
-            <AlertDialogFooter>
-              <AlertDialogCancel asChild>
-                <Button type="button" variant="outline">
-                  Cancel
-                </Button>
-              </AlertDialogCancel>
-              <AlertDialogAction asChild>
-                <Button
-                  onClick={() => onDelete(message)}
-                  type="button"
-                  variant="destructive"
-                >
-                  Delete
-                </Button>
-              </AlertDialogAction>
-            </AlertDialogFooter>
-          </AlertDialogContent>
-        </AlertDialog>
+        />
       ) : null}
 
       {canReport ? (
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index df3a734cee..69e4ec67b5 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -513,10 +513,9 @@ function MessageComposerImpl({
     if (editTargetRef.current && onEditSaveRef.current) {
       if (isSendingRef.current || isUploadingRef.current) return;
       const currentPendingImeta = media.pendingImetaRef.current;
-      const hasMedia = currentPendingImeta.length > 0;
-      // Empty text + zero attachments is a no-op (don't let edit become an
-      // effective deletion).
-      if (!trimmed && !hasMedia) 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
diff --git a/desktop/src/features/messages/ui/MessageRow.tsx b/desktop/src/features/messages/ui/MessageRow.tsx
index 069232fde4..286526b658 100644
--- a/desktop/src/features/messages/ui/MessageRow.tsx
+++ b/desktop/src/features/messages/ui/MessageRow.tsx
@@ -88,6 +88,7 @@ export const MessageRow = React.memo(
     onMarkRead,
     onToggleReaction,
     onReply,
+    onOpenThread,
     onEntranceComplete,
     playEntrance = false,
     onUnfollowThread,
@@ -135,6 +136,7 @@ export const MessageRow = React.memo(
       remove: boolean,
     ) => Promise<void>;
     onReply?: (message: TimelineMessage) => void;
+    onOpenThread?: (message: TimelineMessage) => void;
     onUnfollowThread?: (message: TimelineMessage) => void;
     onEntranceComplete?: (messageId: string) => void;
     playEntrance?: boolean;
@@ -335,7 +337,7 @@ export const MessageRow = React.memo(
             <HuddleAttachment
               channelId={channelId}
               message={message}
-              onOpenThread={onReply}
+              onOpenThread={onOpenThread}
             />
           );
         default:
@@ -433,8 +435,8 @@ export const MessageRow = React.memo(
       <div
         aria-hidden="true"
         className={cn(
-          "flex w-9 shrink-0 items-start justify-end pt-0.5",
-          isThreadReplyLayout ? "min-h-9 self-start" : "self-stretch",
+          "flex w-9 shrink-0 justify-end items-start pt-0.5",
+          isThreadReplyLayout ? "self-start" : "self-stretch",
         )}
       >
         <MessageTimestamp
@@ -485,7 +487,9 @@ export const MessageRow = React.memo(
         className={cn(
           "absolute right-2 top-1 z-10 sm:pointer-events-none",
           actionBarPlacement === "floating"
-            ? "sm:top-0 sm:-translate-y-1/2"
+            ? isContinuation
+              ? "sm:-top-3 sm:-translate-y-1/2"
+              : "sm:top-0 sm:-translate-y-1/2"
             : "sm:top-1 sm:translate-y-0",
         )}
       >
diff --git a/desktop/src/features/messages/ui/MessageThreadPanel.tsx b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
index 08a57fa4c6..85a6f6b930 100644
--- a/desktop/src/features/messages/ui/MessageThreadPanel.tsx
+++ b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
@@ -108,7 +108,7 @@ type MessageThreadPanelProps = ThreadPanelLayoutProps & {
   threadUnreadCount?: number;
   threadReplyUnreadCounts?: ReadonlyMap<string, number>;
   threadTypingPubkeys: string[];
-  threadHeadVideoReviewContext?: VideoReviewContext;
+  videoReviewContextsByMessageId?: ReadonlyMap<string, VideoReviewContext>;
   activityAccessoryContent?: React.ReactNode;
   activityAccessoryVisible: boolean;
   widthPx: number;
@@ -221,7 +221,7 @@ export function MessageThreadPanel({
   scrollTargetId,
   scrollTargetHighlights = true,
   threadHead,
-  threadHeadVideoReviewContext,
+  videoReviewContextsByMessageId,
   threadReplies,
   threadRepliesPending = false,
   threadUnreadCount,
@@ -600,7 +600,9 @@ export function MessageThreadPanel({
               }
               profiles={profiles}
               showDepthGuides={shouldShowThreadBranchGuides}
-              videoReviewContext={threadHeadVideoReviewContext}
+              videoReviewContext={videoReviewContextsByMessageId?.get(
+                threadHead.id,
+              )}
             />
           </div>
         </div>
@@ -753,9 +755,13 @@ export function MessageThreadPanel({
                         onMarkUnread={onMarkUnread}
                         onMarkRead={onMarkRead}
                         onReply={onSelectReplyTarget}
+                        onOpenThread={onExpandReplies}
                         onToggleReaction={onToggleReaction}
                         profiles={profiles}
                         showDepthGuides={shouldShowThreadBranchGuides}
+                        videoReviewContext={videoReviewContextsByMessageId?.get(
+                          entry.message.id,
+                        )}
                       />
                       {entry.summary ? (
                         <MessageThreadSummaryRow
diff --git a/desktop/src/features/messages/ui/MessageTimeline.tsx b/desktop/src/features/messages/ui/MessageTimeline.tsx
index cc5fb1e3dc..954da08b01 100644
--- a/desktop/src/features/messages/ui/MessageTimeline.tsx
+++ b/desktop/src/features/messages/ui/MessageTimeline.tsx
@@ -84,6 +84,7 @@ type MessageTimelineProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -178,6 +179,7 @@ const MessageTimelineBase = React.forwardRef<
     onMarkUnread,
     onMarkRead,
     onReply,
+    onOpenThread,
     channelName,
     channelType,
     isSendingVideoReviewComment = false,
@@ -635,6 +637,7 @@ const MessageTimelineBase = React.forwardRef<
       onMarkUnread={onMarkUnread}
       onMarkRead={onMarkRead}
       onReply={onReply}
+      onOpenThread={onOpenThread}
       isSendingVideoReviewComment={isSendingVideoReviewComment}
       onSendVideoReviewComment={onSendVideoReviewComment}
       onStartReached={loadOlderViaVirtualizer}
diff --git a/desktop/src/features/messages/ui/SystemMessageRow.tsx b/desktop/src/features/messages/ui/SystemMessageRow.tsx
index 4410964dd9..c4637d2823 100644
--- a/desktop/src/features/messages/ui/SystemMessageRow.tsx
+++ b/desktop/src/features/messages/ui/SystemMessageRow.tsx
@@ -28,6 +28,10 @@ import {
 import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  describeChannelTextFieldChange,
+  toInlineName,
+} from "../lib/systemEventCopy";
 import { MessageAgentOwner } from "./MessageAgentOwner";
 import { MessageAuthorText, MessageHeaderRow } from "./MessageHeader";
 import { MessageTimestamp } from "./MessageTimestamp";
@@ -180,6 +184,29 @@ function resolveDisplayLabel(
   return resolveLabel(pubkey, currentPubkey, profiles);
 }
 
+function isSelfPubkey(
+  pubkey: string | undefined,
+  currentPubkey: string | undefined,
+): boolean {
+  return Boolean(
+    pubkey &&
+      currentPubkey &&
+      normalizePubkey(pubkey) === normalizePubkey(currentPubkey),
+  );
+}
+
+/** Same label as `resolveDisplayLabel`, adjusted for mid-sentence use. */
+function resolveInlineDisplayLabel(
+  pubkey: string | undefined,
+  currentPubkey: string | undefined,
+  profiles: UserProfileLookup | undefined,
+): string {
+  return toInlineName(
+    resolveLabel(pubkey, currentPubkey, profiles),
+    isSelfPubkey(pubkey, currentPubkey),
+  );
+}
+
 function isKnownAgentPubkey(
   pubkey: string | undefined,
   profiles: UserProfileLookup | undefined,
@@ -386,7 +413,7 @@ function MembershipPersonName({
       pubkey={pubkey}
       underlineOnHover
     >
-      {resolveDisplayLabel(pubkey, currentPubkey, profiles)}
+      {resolveInlineDisplayLabel(pubkey, currentPubkey, profiles)}
     </ProfileName>
   );
 }
@@ -497,12 +524,17 @@ function describeSystemEvent(
     currentPubkey,
     profiles,
   );
+  const inlineTargetLabel = resolveInlineDisplayLabel(
+    payload.target,
+    currentPubkey,
+    profiles,
+  );
   const actorName = (
     <ProfileName pubkey={payload.actor}>{actorLabel}</ProfileName>
   );
   const targetName = (
     <ProfileName highlight isAgent={isTargetAgent} pubkey={payload.target}>
-      {targetLabel}
+      {inlineTargetLabel}
     </ProfileName>
   );
   const membershipTitle = (
@@ -522,9 +554,13 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            was added by{" "}
+            added by{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
-              {resolveDisplayLabel(payload.actor, currentPubkey, profiles)}
+              {resolveInlineDisplayLabel(
+                payload.actor,
+                currentPubkey,
+                profiles,
+              )}
             </ProfileName>
             , along with{" "}
             <MemberNamesInlineList
@@ -566,9 +602,13 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            was added by{" "}
+            added by{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
-              {resolveDisplayLabel(payload.actor, currentPubkey, profiles)}
+              {resolveInlineDisplayLabel(
+                payload.actor,
+                currentPubkey,
+                profiles,
+              )}
             </ProfileName>
           </>
         ),
@@ -587,12 +627,12 @@ function describeSystemEvent(
     case "topic_changed":
       return {
         title: actorName,
-        action: <>changed the topic to &ldquo;{payload.topic}&rdquo;</>,
+        action: describeChannelTextFieldChange("topic", payload.topic),
       };
     case "purpose_changed":
       return {
         title: actorName,
-        action: <>changed the purpose to &ldquo;{payload.purpose}&rdquo;</>,
+        action: describeChannelTextFieldChange("purpose", payload.purpose),
       };
     case "channel_created":
       return {
diff --git a/desktop/src/features/messages/ui/TimelineMessageList.tsx b/desktop/src/features/messages/ui/TimelineMessageList.tsx
index 3c35cb6d43..89183d0856 100644
--- a/desktop/src/features/messages/ui/TimelineMessageList.tsx
+++ b/desktop/src/features/messages/ui/TimelineMessageList.tsx
@@ -22,11 +22,8 @@ import { THREAD_REPLY_ROW_MARGIN_INLINE_REM } from "@/features/messages/lib/thre
 import { buildMainTimelineEntries } from "@/features/messages/lib/threadPanel";
 import type { MainTimelineEntry } from "@/features/messages/lib/threadPanel";
 import type { ChannelWindowThreadSummary } from "@/features/messages/lib/channelWindowStore";
-import {
-  buildVideoReviewCommentsByRootId,
-  buildVideoReviewContextForMessage,
-  hasVideoAttachment,
-} from "@/features/messages/lib/videoReviewContext";
+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";
@@ -80,6 +77,7 @@ type TimelineMessageListProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -145,6 +143,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   isSendingVideoReviewComment = false,
   onSendVideoReviewComment,
   onToggleReaction,
@@ -170,40 +169,21 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       buildMainTimelineEntries(messages, undefined, threadSummaries, profiles),
     [mainEntries, messages, profiles, threadSummaries],
   );
-  const reviewCommentsByRootId = React.useMemo(
-    () =>
-      messages.some(hasVideoAttachment)
-        ? buildVideoReviewCommentsByRootId(messages)
-        : new Map<string, TimelineMessage[]>(),
-    [messages],
-  );
   // Contexts are memoized per message id so MessageRow/Markdown memo
   // comparisons hold across unrelated timeline re-renders (typing
   // indicators, presence updates) — a fresh context object per render would
   // defeat the memo and re-render every video message on every pass.
   const videoReviewContextById = React.useMemo(() => {
-    const contexts = new Map<
-      string,
-      NonNullable<ReturnType<typeof buildVideoReviewContextForMessage>>
-    >();
-    for (const message of messages) {
-      const comments = reviewCommentsByRootId.get(message.id) ?? [];
-      const context = buildVideoReviewContextForMessage({
-        channelId,
-        channelName,
-        channelType,
-        comments,
-        isSendingVideoReviewComment,
-        message,
-        onSendVideoReviewComment,
-        onToggleReaction,
-        profiles,
-      });
-      if (context) {
-        contexts.set(message.id, context);
-      }
-    }
-    return contexts;
+    return buildVideoReviewContextsByMessageId({
+      channelId,
+      channelName,
+      channelType,
+      isSendingVideoReviewComment,
+      messages,
+      onSendVideoReviewComment,
+      onToggleReaction,
+      profiles,
+    });
   }, [
     channelId,
     channelName,
@@ -213,7 +193,6 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
     onSendVideoReviewComment,
     onToggleReaction,
     profiles,
-    reviewCommentsByRootId,
   ]);
 
   // The flattened item stream, memoized on the entries and the unread boundary
@@ -278,6 +257,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
               onMarkRead={onMarkRead}
               onMarkUnread={onMarkUnread}
               onReply={onReply}
+              onOpenThread={onOpenThread}
               onToggleReaction={onToggleReaction}
               profiles={profiles}
               searchActiveMessageId={searchActiveMessageId}
@@ -309,6 +289,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       onMarkRead,
       onMarkUnread,
       onReply,
+      onOpenThread,
       onToggleReaction,
       profiles,
       ownerProfiles,
@@ -722,6 +703,7 @@ type MessageRowItemProps = Pick<
   | "onMarkUnread"
   | "onMarkRead"
   | "onReply"
+  | "onOpenThread"
   | "onToggleReaction"
   | "profiles"
   | "searchActiveMessageId"
@@ -760,6 +742,7 @@ function MessageRowItem({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   onToggleReaction,
   profiles,
   searchActiveMessageId,
@@ -778,7 +761,7 @@ function MessageRowItem({
   const canDelete = canManage && onDelete ? onDelete : undefined;
   const canEdit = canManage && onEdit ? onEdit : undefined;
 
-  if (summary && onReply) {
+  if (summary && onOpenThread) {
     const isHighlighted = message.id === highlightedMessageId;
     return (
       <div
@@ -813,6 +796,7 @@ function MessageRowItem({
           onMarkUnread={onMarkUnread}
           onToggleReaction={onToggleReaction}
           onReply={onReply}
+          onOpenThread={onOpenThread}
           onUnfollowThread={
             unfollowThreadById
               ? () => unfollowThreadById(message.id)
@@ -825,7 +809,7 @@ function MessageRowItem({
         <MessageThreadSummaryRow
           depth={message.depth}
           message={message}
-          onOpenThread={onReply}
+          onOpenThread={onOpenThread}
           showDepthGuides={false}
           summary={summary}
           summaryIndentOffsetRem={-THREAD_REPLY_ROW_MARGIN_INLINE_REM}
@@ -862,6 +846,7 @@ function MessageRowItem({
         onMarkUnread={onMarkUnread}
         onToggleReaction={onToggleReaction}
         onReply={onReply}
+        onOpenThread={onOpenThread}
         profiles={profiles}
         searchQuery={isSearchMatch ? searchQuery : undefined}
         showDepthGuides={false}
diff --git a/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs b/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs
new file mode 100644
index 0000000000..b570153185
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs
@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  MIN_PASSPHRASE_LEN,
+  downloadDisabled,
+  isEncrypting,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  effectivePassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+} from "./encryptedBackup.ts";
+const reduce = (events, from = initialEncryptedBackupState) =>
+  events.reduce(encryptedBackupReducer, from);
+test("password validation mirrors Rust character counting", () => {
+  assert.equal(passphraseIssue(""), null);
+  assert.match(passphraseIssue("short"), new RegExp(`${MIN_PASSPHRASE_LEN}`));
+  const emoji = "😀".repeat(MIN_PASSPHRASE_LEN);
+  assert.equal(passphraseIssue(emoji), null);
+  assert.equal(
+    effectivePassphrase(reduce([{ type: "set-passphrase", value: emoji }])),
+    emoji,
+  );
+});
+test("valid password requests encryption without copying it into events", () => {
+  const ready = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+  ]);
+  assert.equal(pendingEncryptPassphrase(ready), "one-two-three-four");
+  const started = reduce([{ type: "encrypt-started", requestId: 1 }], ready);
+  assert.equal(isEncrypting(started), true);
+  assert.equal(started.requestId, 1);
+  assert.equal(Object.hasOwn(started, "encryptingPassphrase"), false);
+});
+test("background encryption remains silent until download is clicked", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.passphrase, "one-two-three-four");
+  assert.equal(state.encrypted, "ncryptsec1abc");
+  assert.equal(state.ncryptsec, null);
+  assert.equal(state.savedPassword, false);
+  assert.equal(state.requestId, null);
+});
+test("stale async completions cannot replace current request", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "set-passphrase", value: "five-six-seven-eight" },
+    { type: "encrypt-started", requestId: 2 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1stale" },
+  ]);
+  assert.equal(state.requestId, 2);
+  assert.equal(state.encrypted, null);
+  assert.equal(state.passphrase, "five-six-seven-eight");
+});
+test("failure clears submitted password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(state.passphrase, "");
+  assert.equal(state.createError, "keychain unavailable");
+  assert.equal(state.downloadPending, false);
+  assert.equal(downloadDisabled(state), true);
+});
+test("queued download commits and clears password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("Back preserves blob for immediate re-download without password", () => {
+  const made = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+    { type: "download-clicked" },
+    { type: "back-to-password" },
+  ]);
+  assert.equal(made.ncryptsec, "ncryptsec1abc");
+  assert.equal(made.passphrase, "");
+  assert.equal(downloadDisabled(made), false);
+});
+test("starting over discards blob and invalidates late requests", () => {
+  const made = {
+    ...initialEncryptedBackupState,
+    ncryptsec: "ncryptsec1abc",
+    encrypted: "ncryptsec1abc",
+    savedPassword: true,
+    nextRequestId: 3,
+  };
+  const fresh = reduce([{ type: "start-new-backup" }], made);
+  assert.equal(fresh.ncryptsec, null);
+  assert.equal(fresh.nextRequestId, 4);
+  assert.equal(
+    reduce(
+      [
+        {
+          type: "encrypt-succeeded",
+          requestId: 2,
+          ncryptsec: "ncryptsec1stale",
+        },
+      ],
+      fresh,
+    ).ncryptsec,
+    null,
+  );
+});
diff --git a/desktop/src/features/onboarding/lib/encryptedBackup.ts b/desktop/src/features/onboarding/lib/encryptedBackup.ts
new file mode 100644
index 0000000000..2f7d4a0bb0
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/encryptedBackup.ts
@@ -0,0 +1,135 @@
+/** Pure state model for NIP-49 backup creation. */
+export const MIN_PASSPHRASE_LEN = 12;
+
+export type EncryptedBackupState = {
+  passphrase: string;
+  requestId: number | null;
+  nextRequestId: number;
+  encrypted: string | null;
+  createError: string | null;
+  downloadPending: boolean;
+  ncryptsec: string | null;
+  savedPassword: boolean;
+};
+
+export const initialEncryptedBackupState: EncryptedBackupState = {
+  passphrase: "",
+  requestId: null,
+  nextRequestId: 1,
+  encrypted: null,
+  createError: null,
+  downloadPending: false,
+  ncryptsec: null,
+  savedPassword: false,
+};
+
+export type EncryptedBackupEvent =
+  | { type: "set-passphrase"; value: string }
+  | { type: "encrypt-started"; requestId: number }
+  | { type: "encrypt-succeeded"; requestId: number; ncryptsec: string }
+  | { type: "encrypt-failed"; requestId: number; message: string }
+  | { type: "download-clicked" }
+  | { type: "back-to-password" }
+  | { type: "start-new-backup" };
+
+export function encryptedBackupReducer(
+  state: EncryptedBackupState,
+  event: EncryptedBackupEvent,
+): EncryptedBackupState {
+  switch (event.type) {
+    case "set-passphrase":
+      return {
+        ...state,
+        passphrase: event.value,
+        encrypted: null,
+        createError: null,
+      };
+    case "encrypt-started":
+      return {
+        ...state,
+        requestId: event.requestId,
+        nextRequestId: Math.max(state.nextRequestId, event.requestId + 1),
+        createError: null,
+      };
+    case "encrypt-succeeded":
+      if (event.requestId !== state.requestId) return state;
+      if (state.downloadPending) {
+        return {
+          ...state,
+          passphrase: "",
+          requestId: null,
+          encrypted: event.ncryptsec,
+          ncryptsec: event.ncryptsec,
+          downloadPending: false,
+          savedPassword: true,
+        };
+      }
+      return {
+        ...state,
+        requestId: null,
+        encrypted: event.ncryptsec,
+      };
+    case "encrypt-failed":
+      if (event.requestId !== state.requestId) return state;
+      return {
+        ...state,
+        passphrase: "",
+        requestId: null,
+        createError: event.message,
+        downloadPending: false,
+      };
+    case "download-clicked":
+      if (
+        state.ncryptsec ||
+        state.downloadPending ||
+        (!state.encrypted && !effectivePassphrase(state))
+      )
+        return state;
+      return state.encrypted
+        ? {
+            ...state,
+            ncryptsec: state.encrypted,
+            passphrase: "",
+            savedPassword: true,
+          }
+        : { ...state, downloadPending: true };
+    case "back-to-password":
+      return { ...state, createError: null };
+    case "start-new-backup":
+      return {
+        ...initialEncryptedBackupState,
+        nextRequestId: state.nextRequestId + 1,
+      };
+  }
+}
+
+export function passphraseIssue(passphrase: string): string | null {
+  if (passphrase.length === 0) return null;
+  return [...passphrase].length < MIN_PASSPHRASE_LEN
+    ? `Use at least ${MIN_PASSPHRASE_LEN} characters.`
+    : null;
+}
+export function effectivePassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  return [...state.passphrase].length < MIN_PASSPHRASE_LEN
+    ? null
+    : state.passphrase;
+}
+export function pendingEncryptPassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  if (state.savedPassword || state.encrypted || state.requestId !== null)
+    return null;
+  return effectivePassphrase(state);
+}
+export function isEncrypting(state: EncryptedBackupState): boolean {
+  return state.requestId !== null;
+}
+export function downloadDisabled(state: EncryptedBackupState): boolean {
+  if (state.savedPassword && state.ncryptsec) return false;
+  return (
+    state.downloadPending ||
+    (!state.encrypted && effectivePassphrase(state) === null)
+  );
+}
diff --git a/desktop/src/features/onboarding/lib/keyImportInput.test.mjs b/desktop/src/features/onboarding/lib/keyImportInput.test.mjs
new file mode 100644
index 0000000000..bc0bb4b4d7
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/keyImportInput.test.mjs
@@ -0,0 +1,73 @@
+/**
+ * Pure-logic tests for key-import input classification (nsec vs NIP-49
+ * ncryptsec) and submit gating.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { nsecEncode } from "nostr-tools/nip19";
+import { generateSecretKey } from "nostr-tools/pure";
+import {
+  classifyKeyImportInput,
+  isPlausibleNcryptsec,
+  keyImportSubmitEnabled,
+  NCRYPTSEC_ENCODED_LENGTH,
+} from "./keyImportInput.ts";
+
+// NIP-49 spec vector — structurally valid encrypted backup.
+const NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+const VALID_NSEC = nsecEncode(generateSecretKey());
+
+test("classify_by_hrp_with_whitespace_tolerance", () => {
+  assert.equal(classifyKeyImportInput(`  ${NCRYPTSEC}\n`), "ncryptsec");
+  assert.equal(classifyKeyImportInput(VALID_NSEC), "nsec");
+  assert.equal(classifyKeyImportInput("npub1whatever"), "unknown");
+  assert.equal(classifyKeyImportInput(""), "unknown");
+  // nsec must not be shadowed by the longer HRP check.
+  assert.equal(classifyKeyImportInput("nsec1"), "nsec");
+});
+
+test("uppercase_bech32_encoding_classifies_and_gates_like_lowercase", () => {
+  // Bech32 permits an all-uppercase encoding; it must route to the
+  // encrypted path (matching Rust) and be submit-plausible.
+  const upper = NCRYPTSEC.toUpperCase();
+  assert.equal(classifyKeyImportInput(upper), "ncryptsec");
+  assert.equal(isPlausibleNcryptsec(upper), true);
+  assert.equal(keyImportSubmitEnabled(upper, ""), false);
+  assert.equal(keyImportSubmitEnabled(upper, "hunter2hunter2"), true);
+  // Mixed case: routed encrypted (Rust reports the accurate error) but
+  // never plausible/submittable — mixed-case bech32 cannot decode.
+  const mixed = `N${NCRYPTSEC.slice(1)}`;
+  assert.equal(classifyKeyImportInput(mixed), "ncryptsec");
+  assert.equal(isPlausibleNcryptsec(mixed), false);
+  assert.equal(keyImportSubmitEnabled(mixed, "hunter2hunter2"), false);
+});
+
+test("plausible_ncryptsec_requires_complete_checksummed_nip49_payload", () => {
+  assert.equal(NCRYPTSEC.length, NCRYPTSEC_ENCODED_LENGTH);
+  assert.equal(isPlausibleNcryptsec(NCRYPTSEC), true);
+  assert.equal(isPlausibleNcryptsec(`  ${NCRYPTSEC}\n`), true);
+  assert.equal(isPlausibleNcryptsec(NCRYPTSEC.slice(0, -1)), false);
+  assert.equal(isPlausibleNcryptsec(`${NCRYPTSEC}q`), false);
+  // Same length and charset, but a changed checksum must not advance the UI.
+  assert.equal(isPlausibleNcryptsec(`${NCRYPTSEC.slice(0, -1)}q`), false);
+  // '1' and 'b' / 'i' / 'o' are not in the Bech32 data charset.
+  assert.equal(isPlausibleNcryptsec("ncryptsec1bio"), false);
+  assert.equal(isPlausibleNcryptsec("ncryptsec1"), false);
+  assert.equal(isPlausibleNcryptsec("ncryptsec1 with spaces"), false);
+});
+
+test("submit_gating_nsec_path_unchanged", () => {
+  assert.equal(keyImportSubmitEnabled(VALID_NSEC, ""), true);
+  assert.equal(keyImportSubmitEnabled("nsec1garbage", ""), false);
+  assert.equal(keyImportSubmitEnabled("", ""), false);
+});
+
+test("submit_gating_ncryptsec_requires_passphrase", () => {
+  assert.equal(keyImportSubmitEnabled(NCRYPTSEC, ""), false);
+  assert.equal(keyImportSubmitEnabled(NCRYPTSEC, "hunter2hunter2"), true);
+  // Structurally implausible blob never submits, passphrase or not.
+  assert.equal(keyImportSubmitEnabled("ncryptsec1bio", "hunter2"), false);
+});
diff --git a/desktop/src/features/onboarding/lib/keyImportInput.ts b/desktop/src/features/onboarding/lib/keyImportInput.ts
new file mode 100644
index 0000000000..0f6fc609ed
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/keyImportInput.ts
@@ -0,0 +1,127 @@
+/**
+ * Pure classification + submit gating for the key-import form, unit-testable
+ * without a DOM.
+ *
+ * `ncryptsec1…` is a NIP-49 encrypted backup: no npub preview is possible
+ * (the pubkey is inside the encrypted payload) and a passphrase is required.
+ * Password validation happens in Rust at decrypt time; this module performs
+ * the password-independent Bech32 and NIP-49 structure checks needed to decide
+ * when the form can safely switch modes.
+ */
+
+import { nsecToNpub } from "@/shared/lib/nostrUtils";
+
+export type KeyImportKind = "nsec" | "ncryptsec" | "unknown";
+
+const NCRYPTSEC_HRP = "ncryptsec";
+const NIP49_VERSION = 2;
+const NIP49_PAYLOAD_BYTES = 91;
+/** Current NIP-49 payloads encode to 162 characters including the checksum. */
+export const NCRYPTSEC_ENCODED_LENGTH = 162;
+const BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const BECH32_GENERATORS = [
+  0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3,
+] as const;
+
+function bech32Polymod(values: readonly number[]): number {
+  let checksum = 1;
+  for (const value of values) {
+    const high = checksum >>> 25;
+    checksum = ((checksum & 0x1ffffff) << 5) ^ value;
+    for (let index = 0; index < BECH32_GENERATORS.length; index += 1) {
+      if ((high >>> index) & 1) checksum ^= BECH32_GENERATORS[index];
+    }
+  }
+  return checksum >>> 0;
+}
+
+function expandBech32Hrp(hrp: string): number[] {
+  return [
+    ...Array.from(hrp, (character) => character.charCodeAt(0) >>> 5),
+    0,
+    ...Array.from(hrp, (character) => character.charCodeAt(0) & 31),
+  ];
+}
+
+function convertFiveBitWordsToBytes(words: readonly number[]): number[] | null {
+  let accumulator = 0;
+  let bitCount = 0;
+  const bytes: number[] = [];
+
+  for (const word of words) {
+    accumulator = (accumulator << 5) | word;
+    bitCount += 5;
+    while (bitCount >= 8) {
+      bitCount -= 8;
+      bytes.push((accumulator >>> bitCount) & 0xff);
+    }
+  }
+
+  // Bech32 conversion without padding permits fewer than five zero remainder
+  // bits. Any larger or non-zero remainder is not a canonical byte encoding.
+  if (bitCount >= 5 || ((accumulator << (8 - bitCount)) & 0xff) !== 0) {
+    return null;
+  }
+  return bytes;
+}
+
+export function classifyKeyImportInput(input: string): KeyImportKind {
+  const trimmed = input.trim();
+  // Case-insensitive on the HRP to match the Rust classifier: an uppercase
+  // valid backup routes to the encrypted path (and decodes there); mixed
+  // case routes there too and fails in Rust with the accurate error.
+  if (trimmed.slice(0, 10).toLowerCase() === "ncryptsec1") return "ncryptsec";
+  if (trimmed.startsWith("nsec1")) return "nsec";
+  return "unknown";
+}
+
+/**
+ * Password-independent NIP-49 validation used for the automatic UI transition.
+ * A candidate must have canonical casing and length, a valid Bech32 checksum,
+ * and the current 91-byte/version-2 NIP-49 payload shape.
+ */
+export function isPlausibleNcryptsec(input: string): boolean {
+  const trimmed = input.trim();
+  if (trimmed.length !== NCRYPTSEC_ENCODED_LENGTH) return false;
+  if (trimmed !== trimmed.toLowerCase() && trimmed !== trimmed.toUpperCase()) {
+    return false;
+  }
+
+  const normalized = trimmed.toLowerCase();
+  const separatorIndex = normalized.lastIndexOf("1");
+  if (
+    separatorIndex !== NCRYPTSEC_HRP.length ||
+    normalized.slice(0, separatorIndex) !== NCRYPTSEC_HRP
+  ) {
+    return false;
+  }
+
+  const encoded = normalized.slice(separatorIndex + 1);
+  const words = Array.from(encoded, (character) =>
+    BECH32_CHARSET.indexOf(character),
+  );
+  if (words.some((word) => word < 0) || words.length <= 6) return false;
+  if (bech32Polymod([...expandBech32Hrp(NCRYPTSEC_HRP), ...words]) !== 1) {
+    return false;
+  }
+
+  const payload = convertFiveBitWordsToBytes(words.slice(0, -6));
+  return (
+    payload?.length === NIP49_PAYLOAD_BYTES && payload[0] === NIP49_VERSION
+  );
+}
+
+/**
+ * Whether the import form's submit should be enabled.
+ * nsec: must derive an npub. ncryptsec: plausible blob + non-empty passphrase.
+ */
+export function keyImportSubmitEnabled(
+  input: string,
+  passphrase: string,
+): boolean {
+  const kind = classifyKeyImportInput(input);
+  if (kind === "ncryptsec") {
+    return isPlausibleNcryptsec(input) && passphrase.length > 0;
+  }
+  return nsecToNpub(input) !== null;
+}
diff --git a/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
new file mode 100644
index 0000000000..610c104d95
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
@@ -0,0 +1,130 @@
+import { FileKey2, LockKeyhole, LockOpen } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+
+import { cn } from "@/shared/lib/cn";
+
+const BACKUP_KEY_DOTS = [
+  "key-dot-1",
+  "key-dot-2",
+  "key-dot-3",
+  "key-dot-4",
+  "key-dot-5",
+  "key-dot-6",
+  "key-dot-7",
+  "key-dot-8",
+  "key-dot-9",
+] as const;
+
+const TIMELINE_CONNECTOR_DOTS = [
+  "connector-dot-1",
+  "connector-dot-2",
+  "connector-dot-3",
+  "connector-dot-4",
+] as const;
+
+const TIMELINE_DOT_INITIAL = { opacity: 0.35, scale: 0.85 };
+const TIMELINE_DOT_PULSE = {
+  opacity: [0.35, 1, 0.35],
+  scale: [0.85, 1.25, 0.85],
+};
+const TIMELINE_DOT_TRANSITION = {
+  duration: 0.7,
+  ease: "easeInOut" as const,
+  repeat: Number.POSITIVE_INFINITY,
+  repeatDelay: 1.2,
+};
+const TIMELINE_TOP_DOT_TRANSITIONS = TIMELINE_CONNECTOR_DOTS.map(
+  (_, index) => ({
+    ...TIMELINE_DOT_TRANSITION,
+    delay: index * 0.16,
+  }),
+);
+const TIMELINE_BOTTOM_DOT_TRANSITIONS = TIMELINE_CONNECTOR_DOTS.map(
+  (_, index) => ({
+    ...TIMELINE_DOT_TRANSITION,
+    delay: (index + TIMELINE_CONNECTOR_DOTS.length) * 0.16 + 0.24,
+  }),
+);
+
+/**
+ * Decorative timeline shared by backup creation and encrypted-backup restore.
+ * Backup creation reads key → password → lock; restore reads encrypted file →
+ * password → unlocked account. The password field is layered over the center.
+ */
+export function BackupPasswordTimeline({
+  className,
+  mode = "backup",
+}: {
+  className?: string;
+  mode?: "backup" | "restore";
+}) {
+  const reduceMotion = useReducedMotion() ?? false;
+
+  return (
+    <div
+      aria-hidden
+      className={cn(
+        "pointer-events-none absolute inset-0 [@media(max-height:40rem)]:hidden",
+        className,
+      )}
+      data-testid="backup-password-timeline"
+    >
+      {mode === "restore" ? (
+        <div
+          className="absolute left-1/2 top-0 -translate-x-1/2 text-foreground/85"
+          data-testid="restore-ncryptsec-affordance"
+        >
+          <FileKey2 className="size-10" />
+        </div>
+      ) : (
+        <div className="absolute inset-x-0 top-4 flex items-center justify-center gap-2">
+          {BACKUP_KEY_DOTS.map((dot) => (
+            <span
+              className="block size-2 rounded-full bg-foreground/85"
+              key={dot}
+            />
+          ))}
+        </div>
+      )}
+      <div
+        className={cn(
+          "absolute left-1/2 flex h-12 -translate-x-1/2 flex-col justify-between",
+          mode === "restore" ? "top-15" : "top-11",
+        )}
+      >
+        {TIMELINE_CONNECTOR_DOTS.map((dot, index) => (
+          <motion.span
+            animate={reduceMotion ? undefined : TIMELINE_DOT_PULSE}
+            className="block size-1.5 rounded-full bg-foreground/65"
+            initial={reduceMotion ? false : TIMELINE_DOT_INITIAL}
+            key={`top-${dot}`}
+            transition={
+              reduceMotion ? undefined : TIMELINE_TOP_DOT_TRANSITIONS[index]
+            }
+          />
+        ))}
+      </div>
+      <div className="absolute bottom-15 left-1/2 flex h-12 -translate-x-1/2 flex-col justify-between">
+        {TIMELINE_CONNECTOR_DOTS.map((dot, index) => (
+          <motion.span
+            animate={reduceMotion ? undefined : TIMELINE_DOT_PULSE}
+            className="block size-1.5 rounded-full bg-foreground/65"
+            initial={reduceMotion ? false : TIMELINE_DOT_INITIAL}
+            key={`bottom-${dot}`}
+            transition={
+              reduceMotion ? undefined : TIMELINE_BOTTOM_DOT_TRANSITIONS[index]
+            }
+          />
+        ))}
+      </div>
+      {mode === "restore" ? (
+        <LockOpen
+          className="absolute bottom-0 left-1/2 size-10 -translate-x-1/2 text-foreground/85"
+          data-testid="restore-unlock-icon"
+        />
+      ) : (
+        <LockKeyhole className="absolute bottom-0 left-1/2 size-10 -translate-x-1/2 text-foreground/85" />
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/BackupStep.tsx b/desktop/src/features/onboarding/ui/BackupStep.tsx
index ed2184baaa..99d9c6324d 100644
--- a/desktop/src/features/onboarding/ui/BackupStep.tsx
+++ b/desktop/src/features/onboarding/ui/BackupStep.tsx
@@ -1,183 +1,438 @@
-import { AlertTriangle, Info, RefreshCw } from "lucide-react";
+import { Check, Copy, Eye, EyeOff, Info, ShieldCheck } from "lucide-react";
+import { useReducedMotion } from "motion/react";
 import * as React from "react";
 
 import { getNsec } from "@/shared/api/tauriIdentity";
+import type { IdentityStorage } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { writeTextToClipboard } from "@/shared/lib/clipboard";
 import { Button } from "@/shared/ui/button";
+import { FuzzyLogo } from "@/shared/ui/buzz-logo/FuzzyLogo";
 import { Card } from "@/shared/ui/card";
 import { Spinner } from "@/shared/ui/spinner";
-import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
+import {
+  ONBOARDING_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
 import { OnboardingFooter } from "./OnboardingFooter";
 import {
   type OnboardingTransitionDirection,
   OnboardingSlideTransition,
 } from "./OnboardingSlideTransition";
-import { NsecMaskedDisplay } from "./NsecMaskedDisplay";
+import { ONBOARDING_KEY_TEXT_CLASS } from "./NsecMaskedDisplay";
 
 /**
- * Pure helper so the disabled logic can be unit-tested without a DOM.
- *
- * Disabled while loading (key not fetched yet) or after a failed load (only
- * the explicit "Skip for now" ghost advances past an error).
+ * How long the "Creating your identity key" loader holds the stage before the
+ * finished state fades in. Purely perceptual — the key already exists; the
+ * pause sells the creation moment.
  */
-export function backupNextDisabled({
-  isLoading,
-  loadError,
-}: {
-  isLoading: boolean;
-  loadError: string | null;
-}): boolean {
-  return isLoading || loadError !== null;
+const INTRO_HOLD_MS = 1400;
+
+/**
+ * The creation moment should only be sold once per app session. Module-level
+ * so remounts (e.g. navigating Back and returning to this step) skip the fake
+ * hold and show the finished state instantly.
+ */
+let introPlayed = false;
+
+const REVEAL_ANIMATION_CLASS =
+  "animate-in fade-in duration-700 motion-reduce:animate-none";
+
+const BACKUP_OPTION_CLASS =
+  "flex min-h-48 w-full flex-col items-start justify-start px-6 py-5 text-left text-foreground";
+
+/** Viewing the key never blocks onboarding — Next is always actionable. */
+export function backupNextDisabled(): boolean {
+  return false;
 }
 
 type BackupStepProps = {
   direction: OnboardingTransitionDirection;
+  identityStorage?: IdentityStorage;
   onBack: () => void;
   onNext: () => void;
+  onOpenPasswordBackup: () => void;
+  onShowOptions: () => void;
+  optionsExpanded: boolean;
+  returningFromSecurity: boolean;
 };
 
 /**
- * Onboarding backup step — shows the user their freshly created key so they
- * can save it somewhere safe. Only shown on the fresh-key path.
+ * Onboarding identity-key step — shows the freshly created key, then opens a
+ * dark backup-options state. Copy fetches the raw key only after an explicit
+ * click; password backup opens the separate security flow. Neither method
+ * blocks Next.
  */
-export function BackupStep({ direction, onBack, onNext }: BackupStepProps) {
+export function BackupStep({
+  direction,
+  identityStorage,
+  onBack,
+  onNext,
+  onOpenPasswordBackup,
+  onShowOptions,
+  optionsExpanded,
+  returningFromSecurity,
+}: BackupStepProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const [created, setCreated] = React.useState(introPlayed || reduceMotion);
+  const [copyState, setCopyState] = React.useState<
+    "idle" | "copying" | "copied"
+  >("idle");
+  const [copyError, setCopyError] = React.useState<string | null>(null);
   const [nsec, setNsec] = React.useState<string | null>(null);
-  const [isLoading, setIsLoading] = React.useState(true);
-  const [loadError, setLoadError] = React.useState<string | null>(null);
+  const [isRevealed, setIsRevealed] = React.useState(false);
   const cancelledRef = React.useRef(false);
+  const copiedTimerRef = React.useRef<number | null>(null);
 
-  const loadNsec = React.useCallback(async () => {
-    setIsLoading(true);
-    setLoadError(null);
-    try {
-      const value = await getNsec();
-      if (!cancelledRef.current) setNsec(value);
-    } catch (err) {
-      if (!cancelledRef.current)
-        setLoadError(
-          err instanceof Error
-            ? err.message
-            : "Failed to retrieve private key.",
-        );
-    } finally {
-      if (!cancelledRef.current) setIsLoading(false);
+  React.useEffect(() => {
+    if (introPlayed) return;
+    if (reduceMotion) {
+      introPlayed = true;
+      setCreated(true);
+      return;
     }
-  }, []);
+    const timer = window.setTimeout(() => {
+      introPlayed = true;
+      setCreated(true);
+    }, INTRO_HOLD_MS);
+    return () => window.clearTimeout(timer);
+  }, [reduceMotion]);
 
   React.useEffect(() => {
     cancelledRef.current = false;
-    void loadNsec();
     return () => {
       // Back-during-fetch: cancel any in-flight setState calls and clear the
       // nsec from memory on unmount (backup step is only on the fresh-key path).
       cancelledRef.current = true;
       setNsec(null);
+      if (copiedTimerRef.current !== null)
+        window.clearTimeout(copiedTimerRef.current);
     };
-  }, [loadNsec]);
+  }, []);
+
+  const copyKeyToClipboard = React.useCallback(async () => {
+    setCopyState("copying");
+    setCopyError(null);
+    try {
+      const value = nsec ?? (await getNsec());
+      await writeTextToClipboard(value);
+      if (cancelledRef.current) return;
+      setCopyState("copied");
+      if (copiedTimerRef.current !== null)
+        window.clearTimeout(copiedTimerRef.current);
+      copiedTimerRef.current = window.setTimeout(() => {
+        if (!cancelledRef.current) setCopyState("idle");
+      }, 2000);
+    } catch (err) {
+      if (cancelledRef.current) return;
+      setCopyState("idle");
+      setCopyError(
+        err instanceof Error ? err.message : "Failed to retrieve private key.",
+      );
+    }
+  }, [nsec]);
+
+  const toggleReveal = React.useCallback(async () => {
+    if (isRevealed) {
+      setIsRevealed(false);
+      return;
+    }
+    setCopyError(null);
+    try {
+      // The raw key enters the DOM only after this explicit reveal action.
+      const value = nsec ?? (await getNsec());
+      if (cancelledRef.current) return;
+      setNsec(value);
+      setIsRevealed(true);
+    } catch (err) {
+      if (cancelledRef.current) return;
+      setCopyError(
+        err instanceof Error ? err.message : "Failed to retrieve private key.",
+      );
+    }
+  }, [isRevealed, nsec]);
+
+  // Fixed-length decorative mask (nsec keys are 63 chars) so no key material
+  // is fetched just to render the blurred row. Bullets are joined with a
+  // zero-width space: WebKit won't line-break a run of U+2022 without an
+  // explicit break opportunity, so the masked row would overflow otherwise.
+  const maskedKey = React.useMemo(
+    () => Array.from({ length: nsec?.length ?? 63 }, () => "•").join("\u200b"),
+    [nsec],
+  );
+  const storageDescription =
+    identityStorage === "system-keyring"
+      ? "Buzz keeps your identity key in your system keychain. Your computer may ask for your password when Buzz needs to read the key."
+      : identityStorage === "local-file"
+        ? "Your system keychain wasn’t available, so Buzz keeps your identity key in a private file on this device."
+        : "Buzz keeps your identity key protected on this device. Make a separate backup in case you lose access.";
+  const storageTitle =
+    identityStorage === "system-keyring"
+      ? "Protected by your system keychain"
+      : identityStorage === "local-file"
+        ? "Stored in private device storage"
+        : "Protected in private device storage";
+  const introStorageDescription =
+    identityStorage === "system-keyring"
+      ? "Buzz keeps your identity key in your system keychain."
+      : identityStorage === "local-file"
+        ? "Buzz keeps your identity key in a private file on this device because the system keychain wasn’t available."
+        : "Your identity key is protected on this device.";
+
+  if (optionsExpanded) {
+    return (
+      <OnboardingSlideTransition
+        className="flex min-h-0 w-full flex-col items-center"
+        data-testid="onboarding-page-backup-options"
+        direction={direction}
+        effect={direction === "forward" ? "mask-reveal-up" : "line-slide"}
+        transitionKey={`backup-options-${direction}`}
+      >
+        <div className="flex w-full max-w-140 shrink-0 flex-col text-center">
+          <h1 className="text-title font-normal text-foreground">
+            Backup options
+          </h1>
+          <p className="mt-5 text-sm leading-6 text-foreground/75">
+            Your identity key works like a password for your Buzz account. Keep
+            a copy somewhere safe. You can create a backup file and lock it with
+            a password you can remember.
+          </p>
+        </div>
+
+        <div className="flex w-full max-w-260 flex-1 flex-col justify-center py-10">
+          <div
+            className="grid w-full grid-cols-1 gap-5 md:grid-cols-2 lg:grid-cols-3"
+            data-testid="backup-options"
+          >
+            <div
+              className={cn(BACKUP_OPTION_CLASS, "md:col-span-2 lg:col-span-1")}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">{storageTitle}</span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                {storageDescription}
+              </span>
+            </div>
+
+            <div
+              className={BACKUP_OPTION_CLASS}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">
+                Saved in your password manager
+              </span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                Copy your identity key, then save it in a password manager like
+                1Password.
+              </span>
+              <Button
+                className={cn(
+                  ONBOARDING_SECONDARY_CTA_CLASS,
+                  "mt-5 w-fit gap-2 px-5",
+                )}
+                data-testid="backup-copy-key"
+                disabled={copyState === "copying"}
+                onClick={() => void copyKeyToClipboard()}
+                type="button"
+                variant="ghost"
+              >
+                {copyState === "copying" ? (
+                  <Spinner className="h-4 w-4 border-2" />
+                ) : copyState === "copied" ? (
+                  <Check className="h-4 w-4" aria-hidden="true" />
+                ) : (
+                  <Copy className="h-4 w-4" aria-hidden="true" />
+                )}
+                {copyState === "copying"
+                  ? "Copying…"
+                  : copyState === "copied"
+                    ? "Copied to clipboard"
+                    : "Copy to clipboard"}
+              </Button>
+            </div>
+
+            <div
+              className={BACKUP_OPTION_CLASS}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">
+                Locked in a backup file
+              </span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                Create a backup file and choose a password you can remember.
+                You’ll need both to restore your account.
+              </span>
+              <Button
+                className={cn(
+                  ONBOARDING_SECONDARY_CTA_CLASS,
+                  "mt-5 w-fit gap-2 px-5",
+                )}
+                data-testid="backup-option-password"
+                onClick={onOpenPasswordBackup}
+                type="button"
+                variant="ghost"
+              >
+                <ShieldCheck className="h-5 w-5" aria-hidden="true" />
+                Create locked backup
+              </Button>
+            </div>
+          </div>
+
+          {copyError ? (
+            <p
+              className="mt-4 text-center text-sm text-destructive"
+              data-testid="backup-copy-error"
+            >
+              Could not retrieve your private key: {copyError}. You can continue
+              and find it later in Settings &gt; Profile &gt; Identity.
+            </p>
+          ) : null}
+        </div>
+      </OnboardingSlideTransition>
+    );
+  }
 
   return (
     <OnboardingSlideTransition
       className="flex min-h-0 w-full flex-col items-center"
       data-testid="onboarding-page-backup"
       direction={direction}
-      transitionKey={`backup-${direction}`}
+      effect={returningFromSecurity ? "mask-reveal-down" : "line-slide"}
+      transitionKey={`backup-${direction}-${returningFromSecurity ? "down" : "line"}`}
     >
       <div className="flex w-full max-w-[500px] shrink-0 flex-col text-center">
-        <h1 className="text-title font-normal text-foreground">
-          Your unique identity key has been created
+        {/* Plain string concat: cn()'s tailwind-merge misreads the custom
+            text-title size token as conflicting with text-foreground. */}
+        <h1
+          className={`text-title font-normal text-foreground ${REVEAL_ANIMATION_CLASS}`}
+          key={created ? "created" : "creating"}
+        >
+          {created
+            ? "Your unique identity key has been created"
+            : "Creating your identity key"}
         </h1>
-        <p className="mt-5 text-sm leading-6 text-foreground/80">
-          This key is stored in your system keychain, but save it some place
-          safe in case you ever need to restore your account.
-        </p>
-      </div>
-
-      <div className="flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10">
-        {isLoading ? (
-          <div className="flex items-center justify-center gap-2 py-6 text-sm text-foreground/70">
-            <Spinner className="h-4 w-4 border-2" />
-            Loading your private key…
-          </div>
-        ) : loadError ? (
-          <div className="mx-auto max-w-[500px] space-y-3 text-left">
-            <div
-              className="flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive"
-              data-testid="backup-load-error"
-            >
-              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
-              <span>
-                Could not retrieve your private key: {loadError}. You can
-                continue and find it later in Settings &gt; Profile &gt;
-                Identity.
-              </span>
-            </div>
-            <Button
-              className="h-8 gap-1.5 text-sm"
-              data-testid="backup-retry"
-              onClick={() => void loadNsec()}
-              size="sm"
+        {created ? (
+          <p
+            className={cn(
+              "mt-5 text-sm leading-6 text-foreground/80",
+              REVEAL_ANIMATION_CLASS,
+            )}
+          >
+            {introStorageDescription} You can continue now, or{" "}
+            <button
+              className="rounded-sm font-medium underline decoration-foreground/40 underline-offset-4 transition-colors hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+              data-testid="backup-options-link"
+              onClick={onShowOptions}
               type="button"
-              variant="outline"
             >
-              <RefreshCw className="h-3.5 w-3.5" />
-              Try again
-            </Button>
-          </div>
-        ) : nsec ? (
-          <Card className="w-full px-8 py-6" variant="textured">
-            <div className="mx-auto w-full max-w-[832px]">
-              <NsecMaskedDisplay nsec={nsec} variant="bare" />
-            </div>
-          </Card>
-        ) : (
-          <p className="text-center text-sm text-foreground/70">
-            No key available to back up.
-          </p>
-        )}
-
-        {nsec ? (
-          <p className="mx-auto mt-6 flex max-w-[440px] items-start justify-center gap-1.5 text-center text-xs leading-5 text-[var(--buzz-onboarding-backup-ink)]">
-            <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
-            <span>
-              Never share your private key. Anyone with this key can impersonate
-              you and access everything in your account.
-            </span>
+              review backup options
+            </button>{" "}
+            for ways to restore your account.
           </p>
         ) : null}
       </div>
 
-      <OnboardingFooter>
-        <Button
-          className={ONBOARDING_PRIMARY_CTA_CLASS}
-          data-testid="onboarding-next"
-          disabled={backupNextDisabled({ isLoading, loadError })}
-          onClick={onNext}
-          type="button"
+      {!created ? (
+        <div
+          className="flex w-full flex-1 items-center justify-center py-10"
+          data-testid="backup-intro-logo"
         >
-          Next
-        </Button>
+          <FuzzyLogo
+            ariaLabel="Creating your identity key"
+            className="w-20! text-foreground"
+            fuzz
+            loop
+            loopRestSeconds={0}
+          />
+        </div>
+      ) : (
+        <div
+          className={cn(
+            "flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10",
+            REVEAL_ANIMATION_CLASS,
+          )}
+        >
+          <div className="w-full">
+            <Card className="px-8 py-6" variant="textured">
+              <div className="mx-auto flex w-full min-w-0 max-w-[832px] items-center gap-4">
+                <div className="min-w-0 flex-1">
+                  <p
+                    className={cn(
+                      ONBOARDING_KEY_TEXT_CLASS,
+                      isRevealed && nsec
+                        ? "select-text"
+                        : "select-none blur-[4px]",
+                    )}
+                    data-testid="backup-key-value"
+                  >
+                    {isRevealed && nsec ? nsec : maskedKey}
+                  </p>
+                </div>
+                <Button
+                  aria-label={
+                    isRevealed ? "Hide private key" : "Reveal private key"
+                  }
+                  className="h-10 w-10 shrink-0 text-muted-foreground hover:text-foreground"
+                  data-testid="backup-key-reveal-toggle"
+                  onClick={() => void toggleReveal()}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff className="h-6 w-6" aria-hidden="true" />
+                  ) : (
+                    <Eye className="h-6 w-6" aria-hidden="true" />
+                  )}
+                </Button>
+              </div>
+            </Card>
+
+            {copyError ? (
+              <p
+                className="mt-4 text-center text-sm text-destructive"
+                data-testid="backup-copy-error"
+              >
+                Could not retrieve your private key: {copyError}. You can
+                continue and find it later in Settings &gt; Profile &gt;
+                Identity.
+              </p>
+            ) : null}
 
-        {loadError ? (
+            <p className="mx-auto mt-5 flex max-w-[440px] items-start justify-center gap-1.5 text-center text-xs leading-5 text-[var(--buzz-onboarding-backup-ink)]">
+              <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+              <span>
+                Never share your private key. Anyone with this key can
+                impersonate you and access everything in your account.
+              </span>
+            </p>
+          </div>
+        </div>
+      )}
+
+      {created ? (
+        <OnboardingFooter className={REVEAL_ANIMATION_CLASS}>
           <Button
-            className="h-9 rounded-full px-5 text-muted-foreground hover:text-accent-foreground"
-            data-testid="backup-skip"
+            className={ONBOARDING_PRIMARY_CTA_CLASS}
+            data-testid="onboarding-next"
+            disabled={backupNextDisabled()}
             onClick={onNext}
             type="button"
-            variant="ghost"
           >
-            Skip for now
+            Next
           </Button>
-        ) : null}
 
-        <Button
-          className="h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
-          data-testid="onboarding-back"
-          onClick={onBack}
-          type="button"
-          variant="ghost"
-        >
-          Back
-        </Button>
-      </OnboardingFooter>
+          <Button
+            className={ONBOARDING_SECONDARY_CTA_CLASS}
+            data-testid="onboarding-back"
+            onClick={onBack}
+            type="button"
+            variant="ghost"
+          >
+            Back
+          </Button>
+        </OnboardingFooter>
+      ) : null}
     </OnboardingSlideTransition>
   );
 }
diff --git a/desktop/src/features/onboarding/ui/BackupTestFlow.tsx b/desktop/src/features/onboarding/ui/BackupTestFlow.tsx
new file mode 100644
index 0000000000..9370d5c061
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/BackupTestFlow.tsx
@@ -0,0 +1,745 @@
+import { Check, CircleHelp, Eye, EyeOff, FileKey2, FileUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import {
+  getNsec,
+  verifyNcryptsecBackup,
+  type BackupVerification,
+} from "@/shared/api/tauriIdentity";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import { Card } from "@/shared/ui/card";
+import { Input } from "@/shared/ui/input";
+import { PubKey } from "@/shared/ui/PubKey";
+import { Spinner } from "@/shared/ui/spinner";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+
+type BackupTestStage = "drop" | "password" | "success";
+
+/**
+ * Durable progress through the test flow. Owned by the host so navigating
+ * away (e.g. onboarding Back) and returning doesn't force the user to
+ * re-drop the file. The password attempt is deliberately NOT part of this
+ * state — it lives only in short-lived component state and is cleared the
+ * moment it's submitted or the component unmounts.
+ */
+export type BackupTestProgress = {
+  stage: BackupTestStage;
+  /** Name of the accepted file once the drop check passed. */
+  fileName: string | null;
+  /** Contents of the accepted file, pending or past verification. */
+  ncryptsec: string | null;
+  /** The Rust-verified public identity once decryption succeeded. */
+  result: BackupVerification | null;
+};
+
+export const initialBackupTestProgress: BackupTestProgress = {
+  stage: "drop",
+  fileName: null,
+  ncryptsec: null,
+  result: null,
+};
+
+type BackupTestFlowProps = {
+  /** "spotlight" is the onboarding treatment; "boxed" fits settings cards. */
+  variant?: "spotlight" | "boxed";
+  /**
+   * When supplied, only this exact just-created file is accepted — the
+   * onboarding ceremony proves the user saved *that* backup. Without it the
+   * flow is a general-purpose tester for any key backup file.
+   */
+  expectedNcryptsec?: string;
+  /** Re-open the native save dialog for another copy of the backup file. */
+  onSaveCopy?: () => void;
+  isSaving?: boolean;
+  saveError?: string | null;
+  /** Optional onboarding footer target for the verification CTA. */
+  verifyButtonPortal?: HTMLElement | null;
+  /** Host-owned progress so it survives this component unmounting. */
+  progress: BackupTestProgress;
+  onProgressChange: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+  /** Fired once when the user completes the test successfully. */
+  onVerified?: () => void;
+};
+
+const BURST_EMOJIS = ["🎉", "✨", "🐝", "🍯", "🔑", "💛"] as const;
+const BURST_PARTICLE_COUNT = 18;
+const VERIFICATION_CONNECTOR_DOTS = [
+  "verification-dot-1",
+  "verification-dot-2",
+  "verification-dot-3",
+  "verification-dot-4",
+] as const;
+const VERIFICATION_DOT_ANIMATION = {
+  opacity: [0.35, 1, 0.35],
+  scale: [0.85, 1.25, 0.85],
+};
+const VERIFICATION_DOT_TRANSITION = {
+  duration: 0.7,
+  ease: "easeInOut" as const,
+  repeat: Number.POSITIVE_INFINITY,
+  repeatDelay: 1.2,
+};
+const PRIVATE_KEY_MASK = Array.from({ length: 63 }, () => "•").join("\u200b");
+
+type BurstParticle = {
+  id: number;
+  x: number;
+  y: number;
+  emoji: string;
+  delay: number;
+  scale: number;
+  rotate: number;
+};
+
+/**
+ * One-shot radial emoji burst behind the success badge. Purely decorative —
+ * skipped entirely under reduced motion.
+ */
+function SuccessBurst() {
+  const particles = React.useMemo<BurstParticle[]>(
+    () =>
+      Array.from({ length: BURST_PARTICLE_COUNT }, (_, i) => {
+        const angle =
+          (i / BURST_PARTICLE_COUNT) * Math.PI * 2 + Math.random() * 0.5;
+        const distance = 70 + Math.random() * 80;
+        return {
+          id: i,
+          x: Math.cos(angle) * distance,
+          y: Math.sin(angle) * distance,
+          emoji: BURST_EMOJIS[i % BURST_EMOJIS.length],
+          delay: Math.random() * 0.18,
+          scale: 0.8 + Math.random() * 0.7,
+          rotate: -120 + Math.random() * 240,
+        };
+      }),
+    [],
+  );
+
+  return (
+    <div
+      aria-hidden
+      className="pointer-events-none absolute inset-0 flex items-center justify-center overflow-visible"
+    >
+      {particles.map((particle) => (
+        <motion.span
+          animate={{
+            x: particle.x,
+            y: particle.y,
+            opacity: 0,
+            scale: particle.scale,
+            rotate: particle.rotate,
+          }}
+          className="absolute text-xl"
+          initial={{ x: 0, y: 0, opacity: 1, scale: 0.3, rotate: 0 }}
+          key={particle.id}
+          transition={{
+            duration: 0.9,
+            delay: particle.delay,
+            ease: "easeOut",
+          }}
+        >
+          {particle.emoji}
+        </motion.span>
+      ))}
+    </div>
+  );
+}
+
+function VerificationConnector({
+  delayOffset,
+  reduceMotion,
+}: {
+  delayOffset: number;
+  reduceMotion: boolean;
+}) {
+  return (
+    <div
+      aria-hidden
+      className="my-5 flex h-14 flex-col items-center justify-between py-1"
+    >
+      {VERIFICATION_CONNECTOR_DOTS.map((dot, index) => (
+        <motion.span
+          animate={reduceMotion ? undefined : VERIFICATION_DOT_ANIMATION}
+          className="block size-1.5 rounded-full bg-foreground/65"
+          initial={reduceMotion ? false : { opacity: 0.35, scale: 0.85 }}
+          key={dot}
+          transition={
+            reduceMotion
+              ? undefined
+              : {
+                  ...VERIFICATION_DOT_TRANSITION,
+                  delay:
+                    (VERIFICATION_CONNECTOR_DOTS.length -
+                      1 -
+                      index +
+                      delayOffset) *
+                    0.16,
+                }
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * "Test your backup" flow: the user drops a backup file onto a large
+ * dropzone, then enters its password. Verification is a real NIP-49 decrypt
+ * in Rust — the submitted password is cleared immediately after the result
+ * and only the derived public identity ever comes back.
+ */
+export function BackupTestFlow({
+  variant = "spotlight",
+  expectedNcryptsec,
+  onSaveCopy,
+  isSaving = false,
+  saveError,
+  verifyButtonPortal,
+  progress,
+  onProgressChange,
+  onVerified,
+}: BackupTestFlowProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const { stage, fileName, ncryptsec, result } = progress;
+  // True while a file drag is anywhere over the window — the drop overlay
+  // takes over the host surface only for the duration of the drag.
+  const [isWindowDragging, setIsWindowDragging] = React.useState(false);
+  const dragDepthRef = React.useRef(0);
+
+  React.useEffect(() => {
+    // dragenter/dragleave fire per nested element, so track depth to know
+    // when the drag has actually left the window.
+    const handleDragEnter = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes("Files")) return;
+      dragDepthRef.current += 1;
+      setIsWindowDragging(true);
+    };
+    const handleDragLeave = () => {
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      if (dragDepthRef.current === 0) setIsWindowDragging(false);
+    };
+    const handleDragEnd = () => {
+      dragDepthRef.current = 0;
+      setIsWindowDragging(false);
+    };
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDragEnd);
+    window.addEventListener("dragend", handleDragEnd);
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDragEnd);
+      window.removeEventListener("dragend", handleDragEnd);
+    };
+  }, []);
+
+  // The password attempt is component-local, never host state: it is cleared
+  // when verification is submitted and when this component unmounts.
+  const [attempt, setAttempt] = React.useState("");
+  const [error, setError] = React.useState<string | null>(null);
+  const [isVerifying, setIsVerifying] = React.useState(false);
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const [successNsec, setSuccessNsec] = React.useState<string | null>(null);
+  const [isSuccessNsecRevealed, setIsSuccessNsecRevealed] =
+    React.useState(false);
+  const [isLoadingSuccessNsec, setIsLoadingSuccessNsec] = React.useState(false);
+  const [successNsecError, setSuccessNsecError] = React.useState<string | null>(
+    null,
+  );
+  const fileInputRef = React.useRef<HTMLInputElement | null>(null);
+  const passwordInputRef = React.useRef<HTMLInputElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Opaque correlation id so a stale in-flight verification can't commit
+  // after "Use a different file" or unmount.
+  const requestRef = React.useRef(0);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      requestRef.current += 1;
+      setAttempt("");
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (stage === "password") passwordInputRef.current?.focus();
+  }, [stage]);
+
+  const handleFile = React.useCallback(
+    async (file: File) => {
+      let text: string;
+      try {
+        text = (await file.text()).trim();
+      } catch {
+        if (mountedRef.current) setError("Could not read that file.");
+        return;
+      }
+      if (!mountedRef.current) return;
+      if (!text.toLowerCase().startsWith("ncryptsec1")) {
+        setError(
+          expectedNcryptsec
+            ? "That doesn't look like your key backup. Choose the file you just downloaded."
+            : "That doesn't look like a key backup file.",
+        );
+        return;
+      }
+      if (expectedNcryptsec && text !== expectedNcryptsec.trim()) {
+        setError("That's a key backup, but not the one you just downloaded.");
+        return;
+      }
+      setError(null);
+      setAttempt("");
+      onProgressChange({
+        stage: "password",
+        fileName: file.name,
+        ncryptsec: text,
+        result: null,
+      });
+    },
+    [expectedNcryptsec, onProgressChange],
+  );
+
+  const handleVerify = React.useCallback(async () => {
+    if (!ncryptsec || !attempt || isVerifying) return;
+    const password = attempt;
+    const requestId = ++requestRef.current;
+    setIsVerifying(true);
+    setError(null);
+    setIsRevealed(false);
+    // Clear the attempt the moment it's handed to Rust — success or failure,
+    // the typed password never lingers in the field.
+    setAttempt("");
+    try {
+      const verified = await verifyNcryptsecBackup(ncryptsec, password);
+      if (!mountedRef.current || requestId !== requestRef.current) return;
+      onProgressChange((prev) => ({
+        ...prev,
+        stage: "success",
+        result: verified,
+      }));
+      onVerified?.();
+    } catch (err) {
+      if (mountedRef.current && requestId === requestRef.current)
+        setError(
+          err instanceof Error ? err.message : "Could not verify this backup.",
+        );
+    } finally {
+      if (mountedRef.current && requestId === requestRef.current)
+        setIsVerifying(false);
+    }
+  }, [attempt, isVerifying, ncryptsec, onProgressChange, onVerified]);
+
+  const toggleSuccessNsec = React.useCallback(async () => {
+    if (isSuccessNsecRevealed) {
+      setIsSuccessNsecRevealed(false);
+      return;
+    }
+    if (successNsec) {
+      setIsSuccessNsecRevealed(true);
+      return;
+    }
+    setIsLoadingSuccessNsec(true);
+    setSuccessNsecError(null);
+    try {
+      const value = await getNsec();
+      if (!mountedRef.current) return;
+      setSuccessNsec(value);
+      setIsSuccessNsecRevealed(true);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setSuccessNsecError(
+        err instanceof Error ? err.message : "Could not retrieve your key.",
+      );
+    } finally {
+      if (mountedRef.current) setIsLoadingSuccessNsec(false);
+    }
+  }, [isSuccessNsecRevealed, successNsec]);
+
+  const isSpotlight = variant === "spotlight";
+
+  if (stage === "success" && result) {
+    // The onboarding ceremony pins the exact file, so a success there is by
+    // construction the current identity — celebrate and move on. The general
+    // tester reports which identity the backup unlocks.
+    const isCeremony = Boolean(expectedNcryptsec);
+    return (
+      <div
+        className="relative flex flex-col items-center gap-4 py-4 text-center"
+        data-testid="backup-test-success"
+      >
+        {reduceMotion ? null : <SuccessBurst />}
+        <motion.div
+          animate={{ scale: 1, opacity: 1 }}
+          className="flex h-16 w-16 items-center justify-center rounded-full bg-primary text-primary-foreground"
+          initial={reduceMotion ? false : { scale: 0, opacity: 0 }}
+          transition={
+            reduceMotion
+              ? { duration: 0 }
+              : { type: "spring", stiffness: 380, damping: 18 }
+          }
+        >
+          <Check aria-hidden="true" className="h-8 w-8" strokeWidth={3} />
+        </motion.div>
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          initial={reduceMotion ? false : { opacity: 0, y: 8 }}
+          transition={
+            reduceMotion ? { duration: 0 } : { delay: 0.15, duration: 0.35 }
+          }
+        >
+          {isCeremony ? (
+            <div className="w-full max-w-140">
+              <p className="text-lg font-medium text-foreground">
+                Your backup works!
+              </p>
+              <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+                File and password verified. Keep them both somewhere safe —
+                that&apos;s all you need to restore your identity.
+              </p>
+              <div className="mx-auto mt-4 flex max-w-110 min-w-0 items-center gap-2 text-left">
+                <p
+                  className={cn(
+                    "min-w-0 flex-1 break-all font-mono text-base leading-6 wrap-anywhere",
+                    isSuccessNsecRevealed
+                      ? "select-text text-foreground"
+                      : "select-none blur-[2px] text-muted-foreground",
+                  )}
+                  data-testid="backup-success-nsec-value"
+                >
+                  {isSuccessNsecRevealed && successNsec
+                    ? successNsec
+                    : PRIVATE_KEY_MASK}
+                </p>
+                <Button
+                  aria-label={
+                    isSuccessNsecRevealed
+                      ? "Hide unlocked private key"
+                      : "Reveal unlocked private key"
+                  }
+                  className="size-9 shrink-0 text-muted-foreground hover:text-foreground"
+                  data-testid="backup-success-nsec-toggle"
+                  disabled={isLoadingSuccessNsec}
+                  onClick={() => void toggleSuccessNsec()}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isLoadingSuccessNsec ? (
+                    <Spinner className="size-4 border-2" />
+                  ) : isSuccessNsecRevealed ? (
+                    <EyeOff aria-hidden="true" className="size-4" />
+                  ) : (
+                    <Eye aria-hidden="true" className="size-4" />
+                  )}
+                </Button>
+              </div>
+              {successNsecError ? (
+                <p
+                  className="mt-2 text-xs text-destructive"
+                  data-testid="backup-success-nsec-error"
+                  role="alert"
+                >
+                  {successNsecError}
+                </p>
+              ) : null}
+            </div>
+          ) : (
+            <>
+              <p className="text-lg font-medium text-foreground">
+                This backup works
+              </p>
+              <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+                {result.matchesCurrentIdentity
+                  ? "It restores your current Buzz identity."
+                  : "It restores a different identity than the one signed in here."}
+              </p>
+              <div className="mt-3 flex justify-center">
+                <PubKey
+                  pubkey={result.pubkey}
+                  testId="backup-test-npub"
+                  variant="full"
+                />
+              </div>
+            </>
+          )}
+        </motion.div>
+        {isCeremony ? null : (
+          <Button
+            className="h-8 rounded-full px-4 text-xs text-muted-foreground hover:text-foreground"
+            data-testid="backup-test-another"
+            onClick={() => {
+              setError(null);
+              onProgressChange(initialBackupTestProgress);
+            }}
+            type="button"
+            variant="ghost"
+          >
+            Test another backup
+          </Button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "mx-auto w-full space-y-4",
+        isSpotlight ? "max-w-140" : "max-w-125",
+      )}
+      data-testid="backup-test-flow"
+    >
+      {stage === "drop" ? (
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          className="relative space-y-4"
+          initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+          key="drop"
+          transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+        >
+          <input
+            accept=".ncryptsec,text/plain"
+            className="sr-only"
+            data-testid="backup-test-file-input"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              // Allow re-selecting the same file after an error.
+              event.target.value = "";
+              if (file) void handleFile(file);
+            }}
+            ref={fileInputRef}
+            tabIndex={-1}
+            type="file"
+          />
+          <Button
+            className={cn(
+              "mx-auto",
+              isSpotlight
+                ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                : "h-9 px-6 text-primary-foreground",
+            )}
+            data-testid="backup-test-dropzone"
+            onClick={() => fileInputRef.current?.click()}
+            type="button"
+          >
+            <span className="font-medium text-sm">Select your backup file</span>
+          </Button>
+          {isWindowDragging ? (
+            /*
+             * Composer-style takeover: fills the nearest positioned host
+             * surface (the onboarding card / the settings backup row) and is
+             * itself the drop target, so anywhere on that surface accepts
+             * the file.
+             */
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer-only drop target; the select button is the keyboard-accessible path
+            <div
+              className="absolute inset-2 z-10 mt-0! flex items-center justify-center bg-primary/10 backdrop-blur-sm"
+              data-testid="backup-test-drop-overlay"
+              onDragOver={(event) => event.preventDefault()}
+              onDrop={(event) => {
+                event.preventDefault();
+                const file = event.dataTransfer.files?.[0];
+                if (file) void handleFile(file);
+              }}
+            >
+              <Card
+                className="flex-row items-center gap-2 px-10 py-8 text-sm font-semibold text-foreground"
+                textureSize="compact"
+                textureTone="dark"
+                variant="textured"
+              >
+                <FileUp aria-hidden="true" className="size-4" />
+                <span>Drop your backup file here</span>
+              </Card>
+            </div>
+          ) : null}
+          {error ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="backup-test-error"
+              role="alert"
+            >
+              {error}
+            </p>
+          ) : null}
+          {onSaveCopy ? (
+            <div className="flex flex-col items-center gap-2">
+              <Button
+                className={cn(
+                  "gap-1.5",
+                  isSpotlight
+                    ? ONBOARDING_SECONDARY_CTA_CLASS
+                    : "h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15",
+                )}
+                data-testid="encrypted-backup-save-copy"
+                disabled={isSaving}
+                onClick={onSaveCopy}
+                type="button"
+                variant="ghost"
+              >
+                {isSaving ? <Spinner className="h-4 w-4 border-2" /> : null}
+                Re-download backup
+              </Button>
+            </div>
+          ) : null}
+          {saveError ? (
+            <p className="text-center text-sm text-destructive">{saveError}</p>
+          ) : null}
+        </motion.div>
+      ) : (
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          className="space-y-4"
+          initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+          key="password"
+          transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+        >
+          {(() => {
+            const fileRow = (
+              <div
+                className="flex max-w-full items-center gap-3 rounded-2xl border border-foreground/15 bg-foreground/10 px-4 py-3 text-foreground shadow-sm animate-in fade-in slide-in-from-bottom-1 duration-300 motion-reduce:animate-none"
+                data-testid="backup-test-file-accepted"
+              >
+                <span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-foreground/10">
+                  <FileKey2
+                    aria-hidden="true"
+                    className="size-5 text-foreground/80"
+                  />
+                </span>
+                <span className="max-w-70 truncate font-mono text-sm">
+                  {fileName}
+                </span>
+              </div>
+            );
+            const passwordField = (
+              <div className="relative w-full">
+                <Input
+                  aria-label="Backup password"
+                  autoComplete="off"
+                  className={cn(
+                    "font-mono",
+                    isSpotlight
+                      ? "h-14 rounded-2xl border-black/20 bg-white px-14 text-center text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+                      : "h-10 bg-background pr-10",
+                  )}
+                  data-testid="backup-test-password"
+                  disabled={isVerifying}
+                  onChange={(event) => setAttempt(event.target.value)}
+                  onKeyDown={(event) => {
+                    if (event.key === "Enter") {
+                      event.preventDefault();
+                      void handleVerify();
+                    }
+                  }}
+                  placeholder="Your backup password"
+                  ref={passwordInputRef}
+                  type={isRevealed ? "text" : "password"}
+                  value={attempt}
+                />
+                <Button
+                  aria-label={isRevealed ? "Hide password" : "Reveal password"}
+                  className={cn(
+                    "absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+                    isSpotlight &&
+                      "text-black/55 hover:bg-black/5 hover:text-black/80",
+                  )}
+                  data-testid="backup-test-password-reveal-toggle"
+                  disabled={isVerifying}
+                  onClick={() => setIsRevealed((revealed) => !revealed)}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff aria-hidden="true" className="h-4 w-4" />
+                  ) : (
+                    <Eye aria-hidden="true" className="h-4 w-4" />
+                  )}
+                </Button>
+                {error ? (
+                  <p
+                    className="absolute left-1 top-full mt-1 text-xs text-destructive animate-in fade-in duration-200 motion-reduce:animate-none"
+                    data-testid="backup-test-error"
+                    role="alert"
+                  >
+                    {error}
+                  </p>
+                ) : null}
+              </div>
+            );
+            if (!isSpotlight) {
+              return (
+                <>
+                  {fileRow}
+                  <p className="text-center text-sm leading-6 text-muted-foreground">
+                    Enter the password to prove you can unlock this backup.
+                  </p>
+                  {passwordField}
+                </>
+              );
+            }
+            return (
+              <div className="flex w-full flex-col items-center">
+                <CircleHelp
+                  aria-hidden="true"
+                  className="size-10 text-foreground/85"
+                />
+                <VerificationConnector
+                  delayOffset={VERIFICATION_CONNECTOR_DOTS.length}
+                  reduceMotion={reduceMotion}
+                />
+                {passwordField}
+                <VerificationConnector
+                  delayOffset={0}
+                  reduceMotion={reduceMotion}
+                />
+                {fileRow}
+              </div>
+            );
+          })()}
+          {(() => {
+            const verifyButton = (
+              <Button
+                className={cn(
+                  "font-medium",
+                  isSpotlight
+                    ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                    : "h-9 px-6 text-sm text-primary-foreground",
+                )}
+                data-testid="backup-test-verify"
+                disabled={!attempt || isVerifying}
+                onClick={() => void handleVerify()}
+                type="button"
+              >
+                {isVerifying ? (
+                  <>
+                    <Spinner className="h-4 w-4 border-2" />
+                    Checking…
+                  </>
+                ) : (
+                  "Verify backup"
+                )}
+              </Button>
+            );
+            if (verifyButtonPortal === undefined) {
+              return (
+                <div className="flex justify-center pt-2">{verifyButton}</div>
+              );
+            }
+            return verifyButtonPortal
+              ? createPortal(verifyButton, verifyButtonPortal)
+              : null;
+          })()}
+        </motion.div>
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
index 4b729ab33f..98210c57cd 100644
--- a/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
@@ -160,6 +160,7 @@ export function CommunityOnboardingFlow({
     [],
   );
   const [isPending, setIsPending] = React.useState(false);
+  const checkedProfileTransactionRef = React.useRef<string | null>(null);
   const [starterChannelFailureCount, setStarterChannelFailureCount] =
     React.useState(0);
   const [deniedPubkey, setDeniedPubkey] = React.useState("");
@@ -283,6 +284,22 @@ export function CommunityOnboardingFlow({
   }, [isPending, update]);
 
   const isProfileStage = transaction?.stage === "profile";
+  React.useEffect(() => {
+    if (!isProfileStage || !transaction) return;
+    if (checkedProfileTransactionRef.current === transaction.id) return;
+
+    checkedProfileTransactionRef.current = transaction.id;
+    void getProfile()
+      .then((profile) => {
+        if (profile.hasProfileEvent) {
+          update({ stage: "team-intro", error: undefined }, transaction.id);
+        }
+      })
+      .catch(() => {
+        // Discovery is best-effort. Staying on the profile step preserves the
+        // existing path when the relay cannot answer the lookup.
+      });
+  }, [isProfileStage, transaction, update]);
   const isTeamStage =
     transaction?.stage === "team-intro" ||
     transaction?.stage === "finalizing" ||
diff --git a/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx b/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx
new file mode 100644
index 0000000000..3d69150049
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx
@@ -0,0 +1,139 @@
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+
+import { Button } from "@/shared/ui/button";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+import { OnboardingFooter } from "./OnboardingFooter";
+import {
+  type OnboardingTransitionDirection,
+  OnboardingSlideTransition,
+} from "./OnboardingSlideTransition";
+import {
+  type EncryptedBackupSession,
+  EncryptedBackupCreator,
+} from "./EncryptedBackupCreator";
+
+type DownloadKeyStepProps = {
+  direction: OnboardingTransitionDirection;
+  /** Backup state owned by the parent flow across the creation and test views. */
+  session: EncryptedBackupSession;
+  onBack: () => void;
+};
+
+/**
+ * Password-backup security subview within the identity-key onboarding step.
+ * The raw key never enters this component: Rust builds the NIP-49 payload
+ * locally and the native save dialog produces the user-owned file.
+ */
+export function DownloadKeyStep({
+  direction,
+  session,
+  onBack,
+}: DownloadKeyStepProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  // Once the encrypted payload is saved, the creator advances to its guided
+  // backup test while this surface keeps its own navigation.
+  const hasCreated = session.created;
+  const hasVerifiedBackup = session.verified;
+  const hasSelectedBackup = session.test.stage === "password";
+  const [primaryActionSlot, setPrimaryActionSlot] =
+    React.useState<HTMLElement | null>(null);
+
+  return (
+    <OnboardingSlideTransition
+      className="flex min-h-0 w-full flex-col items-center"
+      data-testid="onboarding-page-download"
+      direction={direction}
+      transitionKey={`download-${direction}`}
+    >
+      <motion.div
+        animate={{ opacity: 1, y: 0 }}
+        className="flex w-full max-w-[500px] shrink-0 flex-col text-center"
+        initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+        key={
+          hasVerifiedBackup
+            ? "success-heading"
+            : hasCreated
+              ? "test-heading"
+              : "password-heading"
+        }
+        transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+      >
+        {/* Plain string concat: cn()'s tailwind-merge misreads the custom
+            text-title size token as conflicting with text-foreground. */}
+        <h1 className="text-title font-normal text-foreground">
+          {hasVerifiedBackup
+            ? "Your backup is verified"
+            : hasSelectedBackup
+              ? "That’s your backup file"
+              : hasCreated
+                ? "Optionally, test your backup"
+                : "Backup your key with a password"}
+        </h1>
+        <p className="mt-5 text-sm leading-6 text-foreground/80">
+          {hasVerifiedBackup
+            ? "Your file and password can restore your identity."
+            : hasSelectedBackup
+              ? "Now enter your password to prove you can unlock it."
+              : hasCreated
+                ? "Learn how your backup works. Drop the file you just saved and unlock it with your password."
+                : "Keep the downloaded file private — you need both it and your password to restore your identity. Save the backup password somewhere safe; Buzz cannot reset it if lost."}
+        </p>
+      </motion.div>
+
+      <div className="flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10">
+        <div className="w-full">
+          <motion.div
+            animate={{ opacity: 1, y: 0 }}
+            initial={reduceMotion ? false : { opacity: 0, y: 12 }}
+            key={hasCreated ? "test-panel" : "password-panel"}
+            transition={{
+              delay: reduceMotion ? 0 : 0.12,
+              duration: reduceMotion ? 0 : 0.4,
+              ease: "easeOut",
+            }}
+          >
+            <div
+              className="mx-auto w-full max-w-140 px-6 py-5"
+              data-testid="backup-password-panel"
+            >
+              <EncryptedBackupCreator
+                createButtonClassName={ONBOARDING_SECURITY_PRIMARY_CTA_CLASS}
+                createButtonPortal={primaryActionSlot}
+                session={session}
+                variant="spotlight"
+                verifyButtonPortal={primaryActionSlot}
+              />
+            </div>
+          </motion.div>
+        </div>
+      </div>
+
+      <OnboardingFooter>
+        <div
+          className="flex justify-center"
+          data-testid={
+            hasCreated ? "onboarding-verify-slot" : "onboarding-create-slot"
+          }
+          ref={setPrimaryActionSlot}
+        />
+        <Button
+          className={
+            hasVerifiedBackup
+              ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+              : ONBOARDING_SECONDARY_CTA_CLASS
+          }
+          data-testid="onboarding-back"
+          onClick={onBack}
+          type="button"
+          variant="ghost"
+        >
+          {hasVerifiedBackup ? "Finish" : hasCreated ? "Skip for now" : "Back"}
+        </Button>
+      </OnboardingFooter>
+    </OnboardingSlideTransition>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx b/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx
new file mode 100644
index 0000000000..bb76166bd7
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx
@@ -0,0 +1,885 @@
+import { AlertTriangle, Eye, EyeOff, RefreshCw } from "lucide-react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import {
+  createNcryptsecBackup,
+  generateBackupPassphrase,
+  saveNcryptsecCopy,
+} from "@/shared/api/tauriIdentity";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import { Input } from "@/shared/ui/input";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { Spinner } from "@/shared/ui/spinner";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import {
+  downloadDisabled,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+  MIN_PASSPHRASE_LEN,
+  type EncryptedBackupEvent,
+  type EncryptedBackupState,
+} from "../lib/encryptedBackup";
+import {
+  type BackupTestProgress,
+  BackupTestFlow,
+  initialBackupTestProgress,
+} from "./BackupTestFlow";
+import { BackupPasswordTimeline } from "./BackupPasswordTimeline";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+
+/** Word-count bounds mirroring `key_backup.rs` (Rust clamps regardless). */
+const MIN_GENERATED_WORDS = 3;
+const MAX_GENERATED_WORDS = 10;
+const DEFAULT_GENERATED_WORDS = 3;
+
+const SEPARATOR_OPTIONS = [
+  { label: "Spaces", value: " " },
+  { label: "Hyphens", value: "-" },
+  { label: "Periods", value: "." },
+  { label: "Commas", value: "," },
+] as const;
+
+const DEFAULT_SEPARATOR = SEPARATOR_OPTIONS[0].value;
+
+/**
+ * Pause after the last keystroke before the background KDF starts, so typing
+ * past the minimum length doesn't launch an encryption per character.
+ */
+const ENCRYPT_DEBOUNCE_MS = 400;
+
+const PENDING_TICKER_MESSAGES = [
+  "Downloading once finished",
+  "Encrypting your password",
+  "Just a bit longer...",
+] as const;
+
+/** How long each ticker message holds before sliding to the next. */
+const PENDING_TICKER_INTERVAL_MS = 2500;
+
+/** Matches the `duration-300` slide transition on the ticker column. */
+const PENDING_TICKER_SLIDE_MS = 300;
+
+/**
+ * Vertical ticker for the queued-download button label — cycles through the
+ * pending messages by sliding a stacked column inside a one-line viewport.
+ * The column ends with a clone of the first message, so the wrap-around
+ * slides up from the bottom like every other step; once the clone settles,
+ * the column snaps (transition disabled) back to the real first row. All
+ * lines render at all times, so the button keeps the width of the longest
+ * message instead of resizing on each swap.
+ */
+function PendingDownloadTicker() {
+  // Index into the rendered column (messages + trailing clone of the first).
+  const [position, setPosition] = React.useState(0);
+  const [snap, setSnap] = React.useState(false);
+
+  React.useEffect(() => {
+    const timer = window.setInterval(
+      () => setPosition((current) => current + 1),
+      PENDING_TICKER_INTERVAL_MS,
+    );
+    return () => window.clearInterval(timer);
+  }, []);
+
+  // The clone is visually identical to the first message: once its slide-in
+  // finishes, jump back to the real first row without animating.
+  React.useEffect(() => {
+    if (position !== PENDING_TICKER_MESSAGES.length) return;
+    const timer = window.setTimeout(() => {
+      setSnap(true);
+      setPosition(0);
+    }, PENDING_TICKER_SLIDE_MS);
+    return () => window.clearTimeout(timer);
+  }, [position]);
+
+  // Re-enable the transition one frame after the snap has painted.
+  React.useEffect(() => {
+    if (!snap) return;
+    const raf = window.requestAnimationFrame(() => setSnap(false));
+    return () => window.cancelAnimationFrame(raf);
+  }, [snap]);
+
+  // The clone row duplicates the first message's text, so it carries its own
+  // stable key.
+  const column = [
+    ...PENDING_TICKER_MESSAGES.map((message) => ({ key: message, message })),
+    { key: "wrap-clone", message: PENDING_TICKER_MESSAGES[0] },
+  ];
+
+  return (
+    <span
+      aria-live="polite"
+      className="relative block h-5 overflow-hidden"
+      data-testid="encrypted-backup-pending-ticker"
+    >
+      <span
+        className={cn(
+          "block ease-out",
+          snap
+            ? "transition-none"
+            : "transition-transform duration-300 motion-reduce:transition-none",
+        )}
+        style={{ transform: `translateY(-${position * 1.25}rem)` }}
+      >
+        {column.map((row) => (
+          <span
+            className="flex h-5 items-center justify-center whitespace-nowrap"
+            key={row.key}
+          >
+            {row.message}
+          </span>
+        ))}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * Everything about an in-progress backup that must survive this component
+ * unmounting: the reducer state (short-lived passphrase + encrypted blob), whether the
+ * backup test passed, where the file was saved, the save-once guard, and the
+ * test-flow progress. Hosts that need the state to outlive the creator (the
+ * onboarding flow, where Back unmounts the step) call
+ * `useEncryptedBackupSession` at a longer-lived level and pass it down;
+ * otherwise the creator owns a private session internally.
+ */
+export type EncryptedBackupSession = {
+  state: EncryptedBackupState;
+  dispatch: React.Dispatch<EncryptedBackupEvent>;
+  /**
+   * True once the encrypted payload has been committed AND saved to disk.
+   * Derived so hosts (e.g. DownloadKeyStep) can branch on it without touching
+   * the blob itself — keeping them outside the ncryptsec confinement scan.
+   */
+  created: boolean;
+  /** True once the user has passed the backup test. */
+  verified: boolean;
+  setVerified: React.Dispatch<React.SetStateAction<boolean>>;
+  savedPath: string | null;
+  setSavedPath: React.Dispatch<React.SetStateAction<string | null>>;
+  /** The committed blob a save was already kicked off for (save-once guard). */
+  savedForRef: React.MutableRefObject<string | null>;
+  test: BackupTestProgress;
+  setTest: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+};
+
+/** Host-side state for `EncryptedBackupCreator` — see `EncryptedBackupSession`. */
+export function useEncryptedBackupSession(): EncryptedBackupSession {
+  const [state, dispatch] = React.useReducer(
+    encryptedBackupReducer,
+    initialEncryptedBackupState,
+  );
+  const [verified, setVerified] = React.useState(false);
+  const [savedPath, setSavedPath] = React.useState<string | null>(null);
+  const savedForRef = React.useRef<string | null>(null);
+  const [test, setTest] = React.useState<BackupTestProgress>(
+    initialBackupTestProgress,
+  );
+  return React.useMemo(
+    () => ({
+      state,
+      dispatch,
+      created: state.ncryptsec !== null && savedPath !== null,
+      verified,
+      setVerified,
+      savedPath,
+      setSavedPath,
+      savedForRef,
+      test,
+      setTest,
+    }),
+    [state, verified, savedPath, test],
+  );
+}
+
+/**
+ * Return to a secure saved-password placeholder. The encrypted blob survives
+ * for instant re-download, while no password or test attempt is retained.
+ */
+export function backupSessionToPasswordEntry(
+  session: EncryptedBackupSession,
+): void {
+  session.dispatch({ type: "back-to-password" });
+  session.setVerified(false);
+  session.setSavedPath(null);
+  session.setTest(initialBackupTestProgress);
+}
+
+/** Discard all backup-creation and verification progress. */
+export function resetEncryptedBackupSession(
+  session: EncryptedBackupSession,
+): void {
+  session.dispatch({ type: "start-new-backup" });
+  session.setVerified(false);
+  session.setSavedPath(null);
+  session.savedForRef.current = null;
+  session.setTest(initialBackupTestProgress);
+}
+
+type EncryptedBackupCreatorProps = {
+  /** "spotlight" is the onboarding treatment; "boxed" fits settings cards. */
+  variant?: "spotlight" | "boxed";
+  /**
+   * When set, the "Download" button is portaled into this element instead of
+   * rendering inline.
+   */
+  createButtonPortal?: HTMLElement | null;
+  /** Optional onboarding footer target for the guided-test verification CTA. */
+  verifyButtonPortal?: HTMLElement | null;
+  /** Extra classes for the "Download" button. */
+  createButtonClassName?: string;
+  /**
+   * Host-owned session so the backup state survives this component
+   * unmounting (onboarding Back navigation). Omitted = private session.
+   */
+  session?: EncryptedBackupSession;
+  /** Fired once the encrypted payload has been created (before saving). */
+  onCreated?: () => void;
+  /** Fired only after the encrypted key file has been saved successfully. */
+  onSaved?: (path: string) => void;
+  /** Whether creation continues into onboarding's guided test ceremony. */
+  guidedTest?: boolean;
+  /** Fired once when the user completes the backup test successfully. */
+  onVerified?: () => void;
+};
+
+/**
+ * 1Password-style memorable-password generator popover with word-count and
+ * separator fields, anchored to a refresh icon inset in the password field
+ * (the anchor assumes a `relative` parent). The first click opens the
+ * popover and generates; further clicks on the icon re-roll while the
+ * popover stays open — only click-outside or Esc closes it. There is no
+ * candidate preview: every generation writes the passphrase straight into
+ * the parent's password field via `onGenerated`.
+ */
+function PassphraseGeneratorPopover({
+  disabled = false,
+  onRequestGenerate,
+  onGenerated,
+  securityTheme = false,
+}: {
+  disabled?: boolean;
+  onRequestGenerate?: () => void;
+  onGenerated: (value: string) => void;
+  securityTheme?: boolean;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [words, setWords] = React.useState(DEFAULT_GENERATED_WORDS);
+  const [separator, setSeparator] = React.useState<string>(DEFAULT_SEPARATOR);
+  const [error, setError] = React.useState<string | null>(null);
+  const anchorRef = React.useRef<HTMLButtonElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Read via a ref so `generate` stays reference-stable even though parents
+  // pass an inline `onGenerated`. Otherwise each generated password would
+  // re-render the parent, rebuild `generate`, and re-fire the open/controls
+  // effect below — an infinite generate loop while the popover is open.
+  const onGeneratedRef = React.useRef(onGenerated);
+
+  React.useEffect(() => {
+    onGeneratedRef.current = onGenerated;
+  }, [onGenerated]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const generate = React.useCallback(async (wordCount: number, sep: string) => {
+    setError(null);
+    try {
+      const passphrase = await generateBackupPassphrase({
+        words: wordCount,
+        separator: sep,
+      });
+      if (mountedRef.current) onGeneratedRef.current(passphrase);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setError(
+        err instanceof Error ? err.message : "Failed to generate a password.",
+      );
+    }
+  }, []);
+
+  // Fill the password field on every open and whenever a control changes.
+  React.useEffect(() => {
+    if (open) void generate(words, separator);
+  }, [open, words, separator, generate]);
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      {/* Anchor (not Trigger): Radix triggers toggle on click, but repeat
+          clicks here must generate a fresh password while the popover stays
+          open. Only click-outside or Esc closes it. */}
+      <PopoverAnchor asChild>
+        <Button
+          aria-label="Generate a password"
+          className={cn(
+            "absolute right-9 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+            securityTheme &&
+              "text-black/55 hover:bg-black/5 hover:text-black/80",
+          )}
+          data-testid="backup-passphrase-generate"
+          disabled={disabled}
+          onClick={() => {
+            // The open effect below generates the first password; later
+            // clicks re-roll with the current controls.
+            if (onRequestGenerate) {
+              onRequestGenerate();
+              return;
+            }
+            if (!open) setOpen(true);
+            else void generate(words, separator);
+          }}
+          ref={anchorRef}
+          size="icon"
+          type="button"
+          variant="ghost"
+        >
+          <RefreshCw className="h-4 w-4" aria-hidden="true" />
+        </Button>
+      </PopoverAnchor>
+      <PopoverContent
+        align="end"
+        className="w-72 space-y-3 text-foreground"
+        onInteractOutside={(event) => {
+          // Clicking the anchor icon is "outside" the content — keep the
+          // popover open so that click re-rolls instead of closing.
+          if (
+            event.target instanceof Node &&
+            anchorRef.current?.contains(event.target)
+          ) {
+            event.preventDefault();
+          }
+        }}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+      >
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-words"
+          >
+            Words
+          </label>
+          <div className="flex flex-1 items-center justify-end gap-3">
+            <input
+              className="h-1.5 w-full max-w-30 cursor-pointer appearance-none rounded-full bg-foreground/15 accent-primary"
+              id="backup-passphrase-words"
+              data-testid="backup-passphrase-words"
+              max={MAX_GENERATED_WORDS}
+              min={MIN_GENERATED_WORDS}
+              onChange={(event) => setWords(Number(event.target.value))}
+              type="range"
+              value={words}
+            />
+            <span className="w-6 text-right text-sm tabular-nums text-foreground">
+              {words}
+            </span>
+          </div>
+        </div>
+
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-separator"
+          >
+            Separator
+          </label>
+          <select
+            className="h-8 rounded-lg border border-border bg-background px-2 text-sm text-foreground outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+            id="backup-passphrase-separator"
+            data-testid="backup-passphrase-separator"
+            onChange={(event) => setSeparator(event.target.value)}
+            value={separator}
+          >
+            {SEPARATOR_OPTIONS.map((option) => (
+              <option key={option.label} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {error ? (
+          <p
+            className="flex items-start gap-1.5 text-xs text-destructive"
+            data-testid="backup-passphrase-generate-error"
+          >
+            <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+            {error}
+          </p>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/**
+ * Password-first encrypted key download flow shared by onboarding and
+ * Settings. The raw private key never enters this component. Rust creates the
+ * NIP-49 payload locally, then the native save dialog produces the user-owned
+ * file.
+ *
+ * The flow is a single password input; a refresh icon inset in the field
+ * opens a 1Password-style generator popover (word count + separator).
+ * Encryption starts eagerly once the password is valid, so Download usually
+ * opens the save dialog instantly. Background encryption is silent; clicking
+ * mid-encryption reveals the queued-download ticker until the KDF finishes.
+ */
+export function EncryptedBackupCreator({
+  variant = "spotlight",
+  createButtonPortal,
+  verifyButtonPortal,
+  createButtonClassName,
+  session: sessionProp,
+  onCreated,
+  onSaved,
+  guidedTest = true,
+  onVerified,
+}: EncryptedBackupCreatorProps) {
+  // Hosts without a longer-lived session get a private one (settings card).
+  const fallbackSession = useEncryptedBackupSession();
+  const session = sessionProp ?? fallbackSession;
+  const { state, dispatch, savedPath, setSavedPath, savedForRef } = session;
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const [saveError, setSaveError] = React.useState<string | null>(null);
+  const [isSaving, setIsSaving] = React.useState(false);
+  const [confirmNewPassword, setConfirmNewPassword] = React.useState(false);
+  const mountedRef = React.useRef(true);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // A queued download locks the form — mask the password too so it isn't
+  // left readable on screen while the user waits for the save dialog.
+  React.useEffect(() => {
+    if (state.downloadPending) setIsRevealed(false);
+  }, [state.downloadPending]);
+
+  // Correlate KDF completion by an opaque request id. The password exists only
+  // in this short-lived effect closure and is cleared from reducer state once
+  // Rust returns; stale completions cannot commit.
+  const pendingPassphrase = pendingEncryptPassphrase(state);
+  const skipDebounce = state.downloadPending;
+  React.useEffect(() => {
+    if (!pendingPassphrase) return;
+    let cancelled = false;
+    const requestId = state.nextRequestId;
+    const start = () => {
+      if (cancelled) return;
+      dispatch({ type: "encrypt-started", requestId });
+      void createNcryptsecBackup(pendingPassphrase)
+        .then((ncryptsec) =>
+          dispatch({ type: "encrypt-succeeded", requestId, ncryptsec }),
+        )
+        .catch((err: unknown) =>
+          dispatch({
+            type: "encrypt-failed",
+            requestId,
+            message:
+              err instanceof Error
+                ? err.message
+                : "Failed to encrypt your key.",
+          }),
+        );
+    };
+    const timer = window.setTimeout(
+      start,
+      skipDebounce ? 0 : ENCRYPT_DEBOUNCE_MS,
+    );
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [dispatch, pendingPassphrase, skipDebounce, state.nextRequestId]);
+
+  // Download commit: fires once per committed blob, whether the commit was
+  // instant (encryption already done) or resolved a queued download. The flow
+  // only advances to the test view once the file is actually on disk — a
+  // canceled save dialog or a save failure rolls the commit back to the
+  // password form so "Download backup" can be clicked again.
+  React.useEffect(() => {
+    const ncryptsec = state.ncryptsec;
+    if (!ncryptsec || savedForRef.current === ncryptsec) return;
+    savedForRef.current = ncryptsec;
+    onCreated?.();
+    setIsSaving(true);
+    setSaveError(null);
+    const rollBack = () => {
+      savedForRef.current = null;
+      dispatch({ type: "back-to-password" });
+    };
+    void saveNcryptsecCopy(ncryptsec)
+      .then((path) => {
+        if (path) {
+          setSavedPath(path);
+          onSaved?.(path);
+        } else {
+          // User canceled the native save dialog — nothing was downloaded.
+          rollBack();
+        }
+      })
+      .catch((err: unknown) => {
+        rollBack();
+        if (mountedRef.current)
+          setSaveError(
+            err instanceof Error ? err.message : "Failed to save your key.",
+          );
+      })
+      .finally(() => {
+        if (mountedRef.current) setIsSaving(false);
+      });
+  }, [
+    dispatch,
+    onCreated,
+    onSaved,
+    savedForRef,
+    setSavedPath,
+    state.ncryptsec,
+  ]);
+
+  const handleSaveCopy = React.useCallback(async () => {
+    if (!state.ncryptsec || isSaving) return;
+    setIsSaving(true);
+    setSaveError(null);
+    try {
+      const path = await saveNcryptsecCopy(state.ncryptsec);
+      if (mountedRef.current && path) {
+        setSavedPath(path);
+        onSaved?.(path);
+      }
+    } catch (err) {
+      if (mountedRef.current)
+        setSaveError(
+          err instanceof Error ? err.message : "Failed to save your key.",
+        );
+    } finally {
+      if (mountedRef.current) setIsSaving(false);
+    }
+  }, [isSaving, onSaved, setSavedPath, state.ncryptsec]);
+
+  const { setVerified, test, setTest } = session;
+  const handleVerified = React.useCallback(() => {
+    setVerified(true);
+    onVerified?.();
+  }, [onVerified, setVerified]);
+
+  const issue = passphraseIssue(state.passphrase);
+  const showBackupTimeline =
+    variant === "spotlight" &&
+    !state.savedPassword &&
+    !state.createError &&
+    !saveError;
+
+  // The test view requires a successful save, not just a committed blob —
+  // while the native save dialog is open the password form stays put.
+  if (state.ncryptsec && savedPath && guidedTest) {
+    return (
+      <div data-testid="encrypted-backup-result">
+        <BackupTestFlow
+          isSaving={isSaving}
+          expectedNcryptsec={state.ncryptsec}
+          onProgressChange={setTest}
+          onSaveCopy={() => void handleSaveCopy()}
+          onVerified={handleVerified}
+          progress={test}
+          saveError={saveError}
+          variant={variant}
+          verifyButtonPortal={verifyButtonPortal}
+        />
+      </div>
+    );
+  }
+  // Without the guided test (settings), a completed save keeps the form
+  // visible in its saved-password state: masked input, instant re-download,
+  // and the change-password confirmation guarding any edit.
+
+  return (
+    <div
+      className={cn("mx-auto w-full max-w-[500px] space-y-3 text-left")}
+      data-testid="encrypted-backup-creator"
+    >
+      <div
+        className={cn(
+          "relative",
+          showBackupTimeline && "pb-32 pt-28 [@media(max-height:40rem)]:py-0",
+        )}
+      >
+        {showBackupTimeline ? <BackupPasswordTimeline /> : null}
+        <div className="relative z-10">
+          <Input
+            aria-label="Encryption password"
+            autoComplete="new-password"
+            autoFocus={variant === "spotlight"}
+            className={cn(
+              "font-mono",
+              variant === "spotlight"
+                ? "h-14 rounded-2xl border-black/20 bg-white px-20 text-center text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+                : "h-10 bg-background pr-19",
+            )}
+            data-testid="backup-passphrase-input"
+            disabled={state.downloadPending}
+            readOnly={state.savedPassword}
+            aria-describedby={
+              state.savedPassword
+                ? "backup-saved-password-description"
+                : undefined
+            }
+            onBeforeInput={(event) => {
+              if (state.savedPassword) {
+                event.preventDefault();
+                setConfirmNewPassword(true);
+              }
+            }}
+            onPaste={(event) => {
+              if (state.savedPassword) {
+                event.preventDefault();
+                setConfirmNewPassword(true);
+              }
+            }}
+            onChange={(event) =>
+              dispatch({ type: "set-passphrase", value: event.target.value })
+            }
+            onKeyDown={(event) => {
+              if (event.key !== "Enter" || event.nativeEvent.isComposing)
+                return;
+              event.preventDefault();
+              if (downloadDisabled(state) || isSaving) return;
+              if (state.savedPassword && state.ncryptsec) {
+                void handleSaveCopy();
+                return;
+              }
+              dispatch({ type: "download-clicked" });
+            }}
+            placeholder={
+              state.savedPassword
+                ? ""
+                : `Password (min ${MIN_PASSPHRASE_LEN} characters)`
+            }
+            type={isRevealed ? "text" : "password"}
+            value={state.passphrase}
+          />
+          {state.savedPassword ? (
+            <div
+              aria-hidden
+              className={cn(
+                "pointer-events-none absolute inset-y-0 left-3 flex items-center font-mono tracking-widest text-foreground",
+                variant === "spotlight" && "text-black/80",
+              )}
+              data-testid="backup-saved-password-mask"
+            >
+              ••••••••••••••••••••••••••••••••
+            </div>
+          ) : null}
+          {state.savedPassword ? (
+            <span className="sr-only" id="backup-saved-password-description">
+              Backup password saved; hidden for security.
+            </span>
+          ) : null}
+          <Button
+            aria-label={
+              state.savedPassword
+                ? "Change saved backup password"
+                : isRevealed
+                  ? "Hide password"
+                  : "Reveal password"
+            }
+            className={cn(
+              "absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+              variant === "spotlight" &&
+                "text-black/55 hover:bg-black/5 hover:text-black/80",
+            )}
+            data-testid="backup-passphrase-reveal-toggle"
+            disabled={state.downloadPending}
+            onClick={() =>
+              state.savedPassword
+                ? setConfirmNewPassword(true)
+                : setIsRevealed((revealed) => !revealed)
+            }
+            size="icon"
+            type="button"
+            variant="ghost"
+          >
+            {isRevealed ? (
+              <EyeOff className="h-4 w-4" aria-hidden="true" />
+            ) : (
+              <Eye className="h-4 w-4" aria-hidden="true" />
+            )}
+          </Button>
+          <PassphraseGeneratorPopover
+            disabled={state.downloadPending}
+            onRequestGenerate={
+              state.savedPassword
+                ? () => setConfirmNewPassword(true)
+                : undefined
+            }
+            onGenerated={(value) => {
+              dispatch({ type: "set-passphrase", value });
+              // A generated password must be visible so the user can save it.
+              setIsRevealed(true);
+            }}
+            securityTheme={variant === "spotlight"}
+          />
+          {issue ? (
+            <p
+              className="absolute left-1 top-full mt-1 animate-in text-xs text-muted-foreground fade-in slide-in-from-top-1 duration-200 motion-reduce:animate-none"
+              data-testid="backup-passphrase-issue"
+            >
+              {issue}
+            </p>
+          ) : null}
+        </div>
+      </div>
+
+      {state.savedPassword && state.ncryptsec && savedPath ? (
+        <div
+          className="space-y-1 text-center"
+          data-testid="encrypted-backup-created"
+        >
+          <p
+            className="text-xs text-muted-foreground"
+            data-testid="encrypted-backup-saved-path"
+          >
+            Backup saved to {savedPath}
+          </p>
+          <p className="text-xs leading-5 text-muted-foreground">
+            Your password isn't kept — download another copy anytime, or start
+            over to choose a new password.
+          </p>
+        </div>
+      ) : null}
+
+      {state.createError ? (
+        <p
+          className="text-center text-sm text-destructive"
+          data-testid="encrypted-backup-create-error"
+        >
+          {state.createError}
+        </p>
+      ) : null}
+
+      {saveError ? (
+        <p
+          className="text-center text-sm text-destructive"
+          data-testid="encrypted-backup-save-error"
+        >
+          {saveError}
+        </p>
+      ) : null}
+
+      {(() => {
+        // A queued download gets an explicit progress treatment. Background
+        // encryption stays silent until the user asks to download.
+        const createButton = (
+          <div className="relative">
+            {state.downloadPending || isSaving ? (
+              <Spinner
+                aria-label="Encrypting your key"
+                className="absolute right-full top-1/2 mr-3 h-4 w-4 -translate-y-1/2 border-2"
+                data-testid="encrypted-backup-encrypting"
+              />
+            ) : null}
+            <Button
+              className={cn("h-9 rounded-full px-6", createButtonClassName)}
+              data-testid="encrypted-backup-create"
+              disabled={downloadDisabled(state) || isSaving}
+              onClick={() =>
+                state.savedPassword && state.ncryptsec
+                  ? void handleSaveCopy()
+                  : dispatch({ type: "download-clicked" })
+              }
+              type="button"
+            >
+              {state.downloadPending ? (
+                <PendingDownloadTicker />
+              ) : state.savedPassword ? (
+                "Download backup again"
+              ) : (
+                "Backup key"
+              )}
+            </Button>
+          </div>
+        );
+        // `undefined` = inline (settings); `null` = slot not mounted yet
+        // (skip a frame rather than flashing the button inline).
+        if (createButtonPortal === undefined)
+          return <div className="flex justify-center">{createButton}</div>;
+        return createButtonPortal
+          ? createPortal(createButton, createButtonPortal)
+          : null;
+      })()}
+      <AlertDialog
+        open={confirmNewPassword}
+        onOpenChange={setConfirmNewPassword}
+      >
+        <AlertDialogContent
+          className={cn(
+            variant === "spotlight" && "buzz-onboarding-security-theme",
+          )}
+          data-testid="backup-change-password-dialog"
+          surface={variant === "spotlight" ? "textured" : "default"}
+          textureSize="compact"
+          textureTone={variant === "spotlight" ? "dark" : "light"}
+        >
+          <AlertDialogHeader>
+            <AlertDialogTitle>Create a new backup password?</AlertDialogTitle>
+            <AlertDialogDescription>
+              Starting over lets you pick a new password and download a fresh
+              backup file. Backups you saved earlier will still work — just use
+              the password you created them with.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel
+              className={
+                variant === "spotlight"
+                  ? ONBOARDING_SECONDARY_CTA_CLASS
+                  : undefined
+              }
+            >
+              Keep current backup
+            </AlertDialogCancel>
+            <AlertDialogAction
+              className={
+                variant === "spotlight"
+                  ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                  : undefined
+              }
+              data-testid="backup-start-new-password"
+              onClick={() => {
+                dispatch({ type: "start-new-backup" });
+                setSavedPath(null);
+                savedForRef.current = null;
+                setTest(initialBackupTestProgress);
+                setIsRevealed(false);
+              }}
+            >
+              Start with a new password
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx b/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
index 0376fc9709..a6a02f38c0 100644
--- a/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
+++ b/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
@@ -22,8 +22,8 @@ export function KeyringLockedScreen() {
   }, []);
 
   const handleImport = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       // Update the identity query cache so useIdentityQuery observers see
       // locked: false. The bootedLocked latch in hooks.ts will then route
       // to RelaunchRequiredScreen via bootedLocked && !identityLocked.
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index ca87c76636..cee17c68f8 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -1,20 +1,33 @@
 import * as React from "react";
 import type { QueryClient } from "@tanstack/react-query";
+import { ArrowUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
 
 import {
   getIdentity,
   importIdentity,
   persistCurrentIdentity,
 } from "@/shared/api/tauriIdentity";
+import type { IdentityStorage } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
 import { StartupWindowDragRegion } from "@/shared/ui/StartupWindowDragRegion";
 import { BackupStep } from "./BackupStep";
 import { DefaultConfigStep } from "./DefaultConfigStep";
+import { DownloadKeyStep } from "./DownloadKeyStep";
+import {
+  backupSessionToPasswordEntry,
+  resetEncryptedBackupSession,
+  useEncryptedBackupSession,
+} from "./EncryptedBackupCreator";
 import { IdentityKeyHelpDialog } from "./IdentityKeyHelpDialog";
 import { LandingBees } from "./LandingBees";
-import { NostrKeyImportForm } from "./NostrKeyImportForm";
+import {
+  NostrKeyImportForm,
+  type NostrKeyImportStage,
+} from "./NostrKeyImportForm";
 import {
   ONBOARDING_LANDING_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
   OnboardingChrome,
 } from "./OnboardingChrome";
 import { OnboardingFooterProvider } from "./OnboardingFooter";
@@ -28,6 +41,8 @@ export type MachineOnboardingPage =
   | "setup"
   | "config";
 
+type BackupSubview = "created" | "options" | "password";
+
 /** A pending navigation the parent should execute after RouterProvider mounts. */
 export type PostOnboardingNavigation = {
   to: string;
@@ -61,10 +76,27 @@ export function MachineOnboardingFlow({
   const [error, setError] = React.useState<string | null>(null);
   const [isPending, setIsPending] = React.useState(false);
   const [identityWasImported, setIdentityWasImported] = React.useState(false);
+  const [keyImportStage, setKeyImportStage] =
+    React.useState<NostrKeyImportStage>("key-entry");
   const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
     null,
   );
+  const [identityStorage, setIdentityStorage] = React.useState<
+    IdentityStorage | undefined
+  >();
   const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);
+  const [backupSubview, setBackupSubview] =
+    React.useState<BackupSubview>("created");
+  const [backupDirection, setBackupDirection] = React.useState<
+    "forward" | "backward"
+  >("forward");
+  const [returningFromSecurity, setReturningFromSecurity] =
+    React.useState(false);
+  // Owned here so switching between the yellow onboarding view and the dark
+  // security subview keeps the created backup, password, and test progress.
+  const backupSession = useEncryptedBackupSession();
+  const reduceMotion = useReducedMotion() ?? false;
+  const isSecuritySubview = page === "backup" && backupSubview !== "created";
   const handleReadyRuntimeIdsChange = React.useCallback(
     (runtimeIds: readonly string[]) => {
       setReadyRuntimeIds(Array.from(new Set(runtimeIds)));
@@ -79,6 +111,10 @@ export function MachineOnboardingFlow({
       const identity = await getIdentity();
       queryClient.setQueryData(["identity"], identity);
       setSelectedPubkey(identity.pubkey);
+      setIdentityStorage(identity.storage);
+      setBackupDirection("forward");
+      setReturningFromSecurity(false);
+      setBackupSubview("created");
       setPage("backup");
     } catch (cause) {
       setError(
@@ -101,6 +137,10 @@ export function MachineOnboardingFlow({
       const identity = await persistCurrentIdentity();
       queryClient.setQueryData(["identity"], identity);
       setSelectedPubkey(identity.pubkey);
+      setIdentityStorage(identity.storage);
+      setBackupDirection("forward");
+      setReturningFromSecurity(false);
+      setBackupSubview("created");
       setPage("backup");
     } catch (cause) {
       setError(
@@ -112,8 +152,8 @@ export function MachineOnboardingFlow({
   }, [queryClient]);
 
   const importExistingIdentity = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       continueWithIdentity(identity.pubkey);
       queryClient.setQueryData(["identity"], identity);
       setIdentityWasImported(true);
@@ -126,6 +166,8 @@ export function MachineOnboardingFlow({
   return (
     <div
       className={`buzz-onboarding-neutral-theme buzz-startup-shell flex max-h-dvh items-start justify-center overflow-x-hidden overflow-y-auto px-4 text-foreground ${
+        isSecuritySubview ? "buzz-onboarding-security-theme" : ""
+      } ${
         page === "identity"
           ? "buzz-onboarding-welcome py-8"
           : "pb-28 pt-[106px]"
@@ -134,7 +176,24 @@ export function MachineOnboardingFlow({
     >
       <StartupWindowDragRegion />
       {page === "identity" ? <LandingBees /> : null}
-      {page !== "identity" ? (
+      {isSecuritySubview ? (
+        <div className="fixed inset-x-0 top-8 z-20 flex justify-center px-6">
+          <Button
+            className={`${ONBOARDING_SECONDARY_CTA_CLASS} gap-2 px-5`}
+            data-testid="backup-return-to-onboarding"
+            onClick={() => {
+              setBackupDirection("backward");
+              setReturningFromSecurity(true);
+              setBackupSubview("created");
+            }}
+            type="button"
+            variant="ghost"
+          >
+            <ArrowUp className="h-4 w-4" aria-hidden="true" />
+            Return to onboarding
+          </Button>
+        </div>
+      ) : page !== "identity" ? (
         <OnboardingChrome
           current={page === "config" ? 4 : page === "setup" ? 3 : 2}
         />
@@ -178,9 +237,12 @@ export function MachineOnboardingFlow({
                       : "Create a new identity key"}
                 </Button>
                 <Button
-                  className="h-9 rounded-full bg-foreground/10 px-5 hover:bg-foreground/15"
+                  className={`${ONBOARDING_SECONDARY_CTA_CLASS} px-5`}
                   disabled={isPending}
-                  onClick={() => setPage("key-import")}
+                  onClick={() => {
+                    setKeyImportStage("key-entry");
+                    setPage("key-import");
+                  }}
                   type="button"
                   variant="ghost"
                 >
@@ -198,18 +260,31 @@ export function MachineOnboardingFlow({
               effect="fade"
               transitionKey="machine-key-import"
             >
-              <div className="shrink-0">
+              <motion.div
+                animate={{ opacity: 1, y: 0 }}
+                className="shrink-0"
+                initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+                key={keyImportStage}
+                transition={{
+                  duration: reduceMotion ? 0 : 0.3,
+                  ease: "easeOut",
+                }}
+              >
                 <h1 className="text-title font-normal text-foreground">
-                  {identityLost
-                    ? "Re-import your key"
-                    : "Enter your private key"}
+                  {keyImportStage === "backup-password"
+                    ? "Unlock your account"
+                    : identityLost
+                      ? "Re-import your key"
+                      : "Enter your private key"}
                 </h1>
                 <p className="mt-5 max-w-[440px] text-sm leading-6 text-foreground/80">
-                  {identityLost
-                    ? "Your identity is no longer in the system keyring. Re-import your nsec to restore it."
-                    : "If you already have a Buzz account, enter your private key below to get started."}
+                  {keyImportStage === "backup-password"
+                    ? "Enter your backup password to unlock your key and restore your identity."
+                    : identityLost
+                      ? "Your identity is no longer in the system keyring. Re-import your nsec to restore it."
+                      : "If you already have a Buzz account, enter your private key below to get started."}
                 </p>
-              </div>
+              </motion.div>
               <div className="buzz-onboarding-key-import-position w-full">
                 <NostrKeyImportForm
                   backLabel={identityLost ? "Start new identity" : "Back"}
@@ -219,21 +294,62 @@ export function MachineOnboardingFlow({
                       : () => setPage("identity")
                   }
                   onImport={importExistingIdentity}
+                  onStageChange={setKeyImportStage}
                   variant="spotlight"
                 />
               </div>
             </OnboardingSlideTransition>
           ) : page === "backup" ? (
-            <BackupStep
-              direction="forward"
-              onBack={() => setPage("identity")}
-              onNext={() => setPage("setup")}
-            />
+            backupSubview === "password" ? (
+              <DownloadKeyStep
+                direction={backupDirection}
+                onBack={() => {
+                  resetEncryptedBackupSession(backupSession);
+                  setBackupDirection("backward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("options");
+                }}
+                session={backupSession}
+              />
+            ) : (
+              <BackupStep
+                direction={backupDirection}
+                identityStorage={identityStorage}
+                onBack={() => setPage("identity")}
+                onNext={() => setPage("setup")}
+                onOpenPasswordBackup={() => {
+                  resetEncryptedBackupSession(backupSession);
+                  setBackupDirection("forward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("password");
+                }}
+                onShowOptions={() => {
+                  setBackupDirection("forward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("options");
+                }}
+                optionsExpanded={backupSubview === "options"}
+                returningFromSecurity={returningFromSecurity}
+              />
+            )
           ) : page === "setup" ? (
             <SetupStep
               actions={{
-                back: () =>
-                  setPage(identityWasImported ? "key-import" : "backup"),
+                // Fresh-key users return to whichever identity backup subview
+                // they used to reach setup; imported keys skip backup entirely.
+                back: () => {
+                  if (identityWasImported) {
+                    setKeyImportStage("key-entry");
+                    setPage("key-import");
+                    return;
+                  }
+                  if (backupSubview === "password") {
+                    backupSessionToPasswordEntry(backupSession);
+                  }
+                  setBackupDirection("backward");
+                  setReturningFromSecurity(false);
+                  setPage("backup");
+                },
                 next: (runtimeIds) => {
                   const ids = Array.from(runtimeIds);
                   setReadyRuntimeIds(ids);
diff --git a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
index daa3f007e9..59e5bfdb0b 100644
--- a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
+++ b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
@@ -3,21 +3,33 @@ import { Check, Eye, EyeOff, KeyRound } from "lucide-react";
 
 import { cn } from "@/shared/lib/cn";
 import { nsecToNpub } from "@/shared/lib/nostrUtils";
+import {
+  classifyKeyImportInput,
+  isPlausibleNcryptsec,
+  keyImportSubmitEnabled,
+} from "../lib/keyImportInput";
 import { Button } from "@/shared/ui/button";
 import { Card } from "@/shared/ui/card";
 import { Input } from "@/shared/ui/input";
 import { Spinner } from "@/shared/ui/spinner";
-import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
+import {
+  ONBOARDING_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+import { BackupPasswordTimeline } from "./BackupPasswordTimeline";
 import { OnboardingFooter } from "./OnboardingFooter";
 
 const NOSTR_KEY_FILE_MAX_BYTES = 1024;
 
+export type NostrKeyImportStage = "key-entry" | "backup-password";
+
 type NostrKeyImportFormProps = {
   backLabel?: string;
   disabled?: boolean;
   errorMessage?: string | null;
   onBack: () => void;
-  onImport: (nsec: string) => Promise<void>;
+  onImport: (nsec: string, password?: string) => Promise<void>;
+  onStageChange?: (stage: NostrKeyImportStage) => void;
   /** "spotlight" is the first-launch treatment: glowy centered input, no drop zone, pill buttons. */
   variant?: "default" | "spotlight";
 };
@@ -35,18 +47,24 @@ export function NostrKeyImportForm({
   errorMessage: externalErrorMessage = null,
   onBack,
   onImport,
+  onStageChange,
   variant = "default",
 }: NostrKeyImportFormProps) {
   const [nsecInput, setNsecInput] = React.useState("");
+  const [passphrase, setPassphrase] = React.useState("");
   const [isImporting, setIsImporting] = React.useState(false);
   const [importError, setImportError] = React.useState<string | null>(null);
   const [isDragging, setIsDragging] = React.useState(false);
   const [isRevealed, setIsRevealed] = React.useState(false);
   const inputRef = React.useRef<HTMLInputElement | null>(null);
+  const passphraseInputRef = React.useRef<HTMLInputElement | null>(null);
   const fileInputRef = React.useRef<HTMLInputElement | null>(null);
   const previewNpub = React.useMemo(() => nsecToNpub(nsecInput), [nsecInput]);
   const trimmedInput = nsecInput.trim();
   const hasInput = trimmedInput.length > 0;
+  const inputKind = classifyKeyImportInput(nsecInput);
+  const isEncryptedInput = inputKind === "ncryptsec";
+  const isPasswordStage = isPlausibleNcryptsec(nsecInput);
 
   // Masked-by-default must re-assert whenever the field empties: a sticky
   // reveal from a previous key must never apply to newly pasted content the
@@ -56,14 +74,33 @@ export function NostrKeyImportForm({
       setIsRevealed(false);
     }
   }, [hasInput]);
-  const isValid = previewNpub !== null;
+  // A stale passphrase must never ride along when the input stops being an
+  // encrypted backup (cleared field, or replaced with a raw nsec).
+  React.useEffect(() => {
+    if (!isPasswordStage) {
+      setPassphrase("");
+    }
+  }, [isPasswordStage]);
+  const isValid = keyImportSubmitEnabled(nsecInput, passphrase);
   const isInteractionDisabled = disabled || isImporting;
-  const showInvalidHint = hasInput && !isValid && trimmedInput.length >= 5;
+  const showInvalidHint =
+    hasInput &&
+    !isPasswordStage &&
+    previewNpub === null &&
+    trimmedInput.length >= 5;
   const errorMessage = importError ?? externalErrorMessage;
 
   React.useLayoutEffect(() => {
-    inputRef.current?.focus();
-  }, []);
+    if (isPasswordStage) {
+      passphraseInputRef.current?.focus();
+    } else {
+      inputRef.current?.focus();
+    }
+  }, [isPasswordStage]);
+
+  React.useEffect(() => {
+    onStageChange?.(isPasswordStage ? "backup-password" : "key-entry");
+  }, [isPasswordStage, onStageChange]);
 
   const openFilePicker = React.useCallback(() => {
     if (isInteractionDisabled) {
@@ -81,7 +118,7 @@ export function NostrKeyImportForm({
 
     if (file.size > NOSTR_KEY_FILE_MAX_BYTES) {
       setImportError(
-        "That file is too large to be a key. Drop a .key file or paste your nsec.",
+        "That file is too large to be a key backup or private key. Choose another file.",
       );
       return;
     }
@@ -108,9 +145,13 @@ export function NostrKeyImportForm({
       return;
     }
 
-    if (!previewNpub) {
+    if (!isValid) {
       setImportError(
-        "That doesn't look like a valid nsec. Paste an nsec1 key.",
+        isPasswordStage
+          ? "Enter the password for this key backup."
+          : isEncryptedInput
+            ? "That doesn't look like a complete ncryptsec backup."
+            : "That doesn't look like a valid nsec. Paste an nsec1 key.",
       );
       return;
     }
@@ -119,7 +160,7 @@ export function NostrKeyImportForm({
     setImportError(null);
 
     try {
-      await onImport(trimmedInput);
+      await onImport(trimmedInput, isPasswordStage ? passphrase : undefined);
     } catch (error) {
       setImportError(
         error instanceof Error ? error.message : "Couldn't import this key.",
@@ -127,7 +168,28 @@ export function NostrKeyImportForm({
     } finally {
       setIsImporting(false);
     }
-  }, [isInteractionDisabled, onImport, previewNpub, trimmedInput]);
+  }, [
+    isEncryptedInput,
+    isInteractionDisabled,
+    isPasswordStage,
+    isValid,
+    onImport,
+    passphrase,
+    trimmedInput,
+  ]);
+
+  const handleBack = React.useCallback(() => {
+    if (!isPasswordStage) {
+      onBack();
+      return;
+    }
+
+    setNsecInput("");
+    setPassphrase("");
+    setImportError(null);
+    setIsRevealed(false);
+    onStageChange?.("key-entry");
+  }, [isPasswordStage, onBack, onStageChange]);
 
   return (
     <form
@@ -137,221 +199,296 @@ export function NostrKeyImportForm({
         void handleSubmit();
       }}
     >
-      <div className="space-y-1.5 text-left">
-        <label
-          className={cn(
-            "text-sm font-medium text-foreground",
-            variant === "spotlight" && "sr-only",
-          )}
-          htmlFor="nostr-private-key"
-        >
-          Private key
-        </label>
-        {variant === "spotlight" ? (
-          <Card
-            className="w-full px-8 py-12"
-            data-testid="nostr-import-card"
-            variant="textured"
+      {!isPasswordStage ? (
+        <div className="space-y-1.5 text-left">
+          <label
+            className={cn(
+              "text-sm font-medium text-foreground",
+              variant === "spotlight" && "sr-only",
+            )}
+            htmlFor="nostr-private-key"
           >
-            <div className="relative w-full">
-              <Input
-                autoComplete="off"
-                autoCorrect="off"
-                // Symmetric px reserves the absolutely positioned toggle's
-                // footprint on BOTH sides, so the centered key text never
-                // runs under the eye control and stays optically centered.
-                className="h-[3.6875rem] rounded-none border-0 bg-transparent px-10 text-center font-mono !text-4xl text-[color:var(--buzz-onboarding-backup-ink)] shadow-none placeholder:text-foreground/30 focus-visible:ring-0"
-                data-testid="nostr-import-nsec-input"
-                id="nostr-private-key"
-                onChange={(event) => {
-                  setNsecInput(event.target.value);
-                  setImportError(null);
-                }}
-                placeholder="Enter your key here"
-                ref={inputRef}
-                spellCheck={false}
-                type={isRevealed ? "text" : "password"}
-                value={nsecInput}
-              />
-              {/* Absolutely positioned so appearing/disappearing never resizes
+            Private key
+          </label>
+          {variant === "spotlight" ? (
+            <Card
+              className="w-full px-8 py-12"
+              data-testid="nostr-import-card"
+              variant="textured"
+            >
+              <div className="relative w-full">
+                <Input
+                  autoComplete="off"
+                  autoCorrect="off"
+                  // Symmetric px reserves the absolutely positioned toggle's
+                  // footprint on BOTH sides, so the centered key text never
+                  // runs under the eye control and stays optically centered.
+                  className="h-[3.6875rem] rounded-none border-0 bg-transparent px-10 text-center font-mono !text-4xl text-[color:var(--buzz-onboarding-backup-ink)] shadow-none placeholder:text-foreground/30 focus-visible:ring-0"
+                  data-testid="nostr-import-nsec-input"
+                  id="nostr-private-key"
+                  onChange={(event) => {
+                    setNsecInput(event.target.value);
+                    setImportError(null);
+                  }}
+                  placeholder="Enter your key here"
+                  ref={inputRef}
+                  spellCheck={false}
+                  type={isRevealed ? "text" : "password"}
+                  value={nsecInput}
+                />
+                {/* Absolutely positioned so appearing/disappearing never resizes
                   the input or shifts its centered text; fades with hasInput. */}
-              <Button
-                aria-hidden={!hasInput}
-                aria-label={
-                  isRevealed ? "Hide private key" : "Reveal private key"
-                }
-                className={cn(
-                  "absolute right-8 top-1/2 h-10 w-10 -translate-y-1/2 text-muted-foreground transition-opacity duration-300 hover:bg-foreground/10 hover:text-foreground motion-reduce:transition-none",
-                  hasInput ? "opacity-100" : "pointer-events-none opacity-0",
-                )}
-                data-testid="nostr-import-reveal-toggle"
-                onClick={() => setIsRevealed((current) => !current)}
-                size="icon"
-                tabIndex={hasInput ? 0 : -1}
-                type="button"
-                variant="ghost"
-              >
-                {isRevealed ? (
-                  <EyeOff aria-hidden="true" className="h-6 w-6" />
-                ) : (
-                  <Eye aria-hidden="true" className="h-6 w-6" />
-                )}
-              </Button>
-            </div>
-          </Card>
-        ) : (
-          <Input
-            autoComplete="off"
-            autoCorrect="off"
-            className="h-10 bg-background"
-            data-testid="nostr-import-nsec-input"
-            id="nostr-private-key"
-            onChange={(event) => {
-              setNsecInput(event.target.value);
-              setImportError(null);
-            }}
-            placeholder="nsec1..."
-            ref={inputRef}
-            spellCheck={false}
-            type="password"
-            value={nsecInput}
-          />
-        )}
-      </div>
+                <Button
+                  aria-hidden={!hasInput}
+                  aria-label={
+                    isRevealed ? "Hide private key" : "Reveal private key"
+                  }
+                  className={cn(
+                    "absolute right-8 top-1/2 h-10 w-10 -translate-y-1/2 text-muted-foreground transition-opacity duration-300 hover:bg-foreground/10 hover:text-foreground motion-reduce:transition-none",
+                    hasInput ? "opacity-100" : "pointer-events-none opacity-0",
+                  )}
+                  data-testid="nostr-import-reveal-toggle"
+                  onClick={() => setIsRevealed((current) => !current)}
+                  size="icon"
+                  tabIndex={hasInput ? 0 : -1}
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff aria-hidden="true" className="h-6 w-6" />
+                  ) : (
+                    <Eye aria-hidden="true" className="h-6 w-6" />
+                  )}
+                </Button>
+              </div>
+            </Card>
+          ) : (
+            <Input
+              autoComplete="off"
+              autoCorrect="off"
+              className="h-10 bg-background"
+              data-testid="nostr-import-nsec-input"
+              id="nostr-private-key"
+              onChange={(event) => {
+                setNsecInput(event.target.value);
+                setImportError(null);
+              }}
+              placeholder="nsec1..."
+              ref={inputRef}
+              spellCheck={false}
+              type="password"
+              value={nsecInput}
+            />
+          )}
+        </div>
+      ) : null}
 
-      {variant === "spotlight" ? null : (
-        <>
-          <input
-            accept=".key,text/plain"
-            className="sr-only"
-            disabled={isInteractionDisabled}
-            onChange={(event) => {
-              void handleFiles(event.currentTarget.files);
-              event.currentTarget.value = "";
-            }}
-            ref={fileInputRef}
-            tabIndex={-1}
-            type="file"
-          />
+      {/* Hidden file input shared by both variants: the default drop zone and
+          the spotlight "Choose a backup file" button both open it. Accepts the
+          .ncryptsec backups our own save flow emits alongside raw .key files. */}
+      <input
+        accept=".key,.ncryptsec,text/plain"
+        className="sr-only"
+        data-testid="nostr-import-file-input"
+        disabled={isInteractionDisabled}
+        onChange={(event) => {
+          void handleFiles(event.currentTarget.files);
+          event.currentTarget.value = "";
+        }}
+        ref={fileInputRef}
+        tabIndex={-1}
+        type="file"
+      />
 
-          <button
-            className={cn(
-              "relative flex h-[120px] flex-col items-center justify-center gap-3 overflow-hidden rounded-xl border border-transparent bg-muted text-foreground transition-[background-color,border-color,box-shadow,color] duration-[250ms] ease-out hover:bg-muted/80 disabled:opacity-60",
-              isDragging &&
-                "border-primary bg-primary/10 text-primary ring-1 ring-primary/35 hover:bg-primary/10",
-            )}
-            data-dragging={isDragging ? "true" : undefined}
-            data-testid="nostr-import-drop"
+      {!isPasswordStage && variant === "spotlight" ? (
+        // First-launch/wiped-identity treatment: no drop zone, but the file
+        // path must still exist — a backup saved through the OS dialog is
+        // exactly what a wiped user returns with.
+        <div className="mt-2 text-center">
+          <Button
+            className={ONBOARDING_SECONDARY_CTA_CLASS}
+            data-testid="nostr-import-file-button"
             disabled={isInteractionDisabled}
             onClick={openFilePicker}
-            onDragEnter={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (!isInteractionDisabled) {
-                setIsDragging(true);
-              }
-            }}
-            onDragLeave={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (
-                event.currentTarget.contains(event.relatedTarget as Node | null)
-              ) {
-                return;
-              }
-              setIsDragging(false);
-            }}
-            onDragOver={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (!isInteractionDisabled) {
-                event.dataTransfer.dropEffect = "copy";
-              }
-            }}
-            onDrop={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              setIsDragging(false);
-              if (isInteractionDisabled) {
-                return;
-              }
-              void handleFiles(event.dataTransfer.files);
-            }}
             type="button"
+            variant="ghost"
           >
-            <span
-              aria-hidden="true"
-              className={cn(
-                "pointer-events-none absolute inset-0 rounded-[inherit] bg-primary/10 opacity-0 transition-opacity duration-[250ms] ease-out",
-                isDragging && "opacity-100",
-              )}
-            />
-            <KeyRound
-              className={cn(
-                "relative h-8 w-8 text-muted-foreground transition-colors duration-[250ms] ease-out",
-                isDragging && "text-primary",
-              )}
+            Choose a backup file
+          </Button>
+        </div>
+      ) : !isPasswordStage ? (
+        <button
+          className={cn(
+            "relative flex h-[120px] flex-col items-center justify-center gap-3 overflow-hidden rounded-xl border border-transparent bg-muted text-foreground transition-[background-color,border-color,box-shadow,color] duration-[250ms] ease-out hover:bg-muted/80 disabled:opacity-60",
+            isDragging &&
+              "border-primary bg-primary/10 text-primary ring-1 ring-primary/35 hover:bg-primary/10",
+          )}
+          data-dragging={isDragging ? "true" : undefined}
+          data-testid="nostr-import-drop"
+          disabled={isInteractionDisabled}
+          onClick={openFilePicker}
+          onDragEnter={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (!isInteractionDisabled) {
+              setIsDragging(true);
+            }
+          }}
+          onDragLeave={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (
+              event.currentTarget.contains(event.relatedTarget as Node | null)
+            ) {
+              return;
+            }
+            setIsDragging(false);
+          }}
+          onDragOver={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (!isInteractionDisabled) {
+              event.dataTransfer.dropEffect = "copy";
+            }
+          }}
+          onDrop={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            setIsDragging(false);
+            if (isInteractionDisabled) {
+              return;
+            }
+            void handleFiles(event.dataTransfer.files);
+          }}
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            className={cn(
+              "pointer-events-none absolute inset-0 rounded-[inherit] bg-primary/10 opacity-0 transition-opacity duration-[250ms] ease-out",
+              isDragging && "opacity-100",
+            )}
+          />
+          <KeyRound
+            className={cn(
+              "relative h-8 w-8 text-muted-foreground transition-colors duration-[250ms] ease-out",
+              isDragging && "text-primary",
+            )}
+          />
+          <span
+            className={cn(
+              "relative text-sm font-medium text-muted-foreground transition-colors duration-[250ms] ease-out",
+              isDragging && "text-primary",
+            )}
+          >
+            Drop a key here
+          </span>
+        </button>
+      ) : null}
+
+      {isPasswordStage ? (
+        <div
+          className="relative mx-auto w-full max-w-[500px] pb-32 pt-32 [@media(max-height:40rem)]:py-0"
+          data-testid="nostr-import-passphrase-section"
+        >
+          <BackupPasswordTimeline mode="restore" />
+          <label className="sr-only" htmlFor="nostr-import-passphrase">
+            Backup password
+          </label>
+          <div className="relative z-10">
+            <Input
+              autoComplete="current-password"
+              autoCorrect="off"
+              className="h-14 rounded-2xl border-black/20 bg-white px-12 text-center font-mono text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+              data-testid="nostr-import-passphrase"
+              id="nostr-import-passphrase"
+              onChange={(event) => {
+                setPassphrase(event.target.value);
+                setImportError(null);
+              }}
+              placeholder="Backup password"
+              ref={passphraseInputRef}
+              spellCheck={false}
+              type={isRevealed ? "text" : "password"}
+              value={passphrase}
             />
-            <span
-              className={cn(
-                "relative text-sm font-medium text-muted-foreground transition-colors duration-[250ms] ease-out",
-                isDragging && "text-primary",
-              )}
+            <Button
+              aria-label={isRevealed ? "Hide password" : "Reveal password"}
+              className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-black/55 hover:bg-black/5 hover:text-black/80"
+              data-testid="nostr-import-passphrase-reveal-toggle"
+              disabled={isInteractionDisabled}
+              onClick={() => setIsRevealed((current) => !current)}
+              size="icon"
+              type="button"
+              variant="ghost"
             >
-              Drop a key here
-            </span>
-          </button>
-        </>
-      )}
+              {isRevealed ? (
+                <EyeOff aria-hidden="true" className="h-4 w-4" />
+              ) : (
+                <Eye aria-hidden="true" className="h-4 w-4" />
+              )}
+            </Button>
+          </div>
+        </div>
+      ) : null}
 
-      <div
-        className={cn("min-h-8", variant === "spotlight" && "mt-6 text-center")}
-        data-testid="nostr-import-feedback"
-      >
-        {previewNpub ? (
-          variant === "spotlight" ? (
-            // Spotlight uses the backup step's quiet caption language:
-            // centered, unboxed, with the npub in the shared olive key ink.
-            <div
-              className="space-y-1 text-sm"
-              data-testid="nostr-import-npub-preview"
-            >
-              <p className="flex items-center justify-center gap-1.5 text-foreground">
-                <Check aria-hidden="true" className="h-4 w-4 shrink-0" />
-                Nostr identity found
-              </p>
-              <p className="break-all font-mono text-[color:var(--buzz-onboarding-backup-ink)]">
-                {previewNpub}
-              </p>
-            </div>
-          ) : (
-            <div
-              className="flex items-start gap-2 rounded-md border border-primary/30 bg-primary/5 px-3 py-2 text-xs"
-              data-testid="nostr-import-npub-preview"
-            >
-              <Check className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
-              <div className="min-w-0 space-y-0.5">
-                <p className="font-medium text-foreground">
-                  This will use this Nostr identity:
+      {!isPasswordStage || errorMessage ? (
+        <div
+          className={cn(
+            "min-h-8",
+            variant === "spotlight" && "mt-6 text-center",
+          )}
+          data-testid="nostr-import-feedback"
+        >
+          {!isPasswordStage && previewNpub ? (
+            variant === "spotlight" ? (
+              // Spotlight uses the backup step's quiet caption language:
+              // centered, unboxed, with the npub in the shared olive key ink.
+              <div
+                className="space-y-1 text-sm"
+                data-testid="nostr-import-npub-preview"
+              >
+                <p className="flex items-center justify-center gap-1.5 text-foreground">
+                  <Check aria-hidden="true" className="h-4 w-4 shrink-0" />
+                  Nostr identity found
                 </p>
-                <p className="break-all font-mono text-2xs text-muted-foreground">
+                <p className="break-all font-mono text-[color:var(--buzz-onboarding-backup-ink)]">
                   {previewNpub}
                 </p>
               </div>
-            </div>
-          )
-        ) : null}
+            ) : (
+              <div
+                className="flex items-start gap-2 rounded-md border border-primary/30 bg-primary/5 px-3 py-2 text-xs"
+                data-testid="nostr-import-npub-preview"
+              >
+                <Check className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+                <div className="min-w-0 space-y-0.5">
+                  <p className="font-medium text-foreground">
+                    This will use this Nostr identity:
+                  </p>
+                  <p className="break-all font-mono text-2xs text-muted-foreground">
+                    {previewNpub}
+                  </p>
+                </div>
+              </div>
+            )
+          ) : null}
 
-        {showInvalidHint && !errorMessage ? (
-          <p className="text-sm text-muted-foreground">
-            Waiting for a valid nsec1 key
-          </p>
-        ) : null}
+          {showInvalidHint && !errorMessage ? (
+            <p className="text-sm text-muted-foreground">
+              {isEncryptedInput
+                ? "Waiting for a complete ncryptsec backup"
+                : "Waiting for a valid nsec1 key"}
+            </p>
+          ) : null}
 
-        {errorMessage ? (
-          <p className="text-center text-sm text-destructive">{errorMessage}</p>
-        ) : null}
-      </div>
+          {errorMessage ? (
+            <p className="text-center text-sm text-destructive">
+              {errorMessage}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
 
       <OnboardingFooter>
         <Button
@@ -381,15 +518,15 @@ export function NostrKeyImportForm({
         <Button
           className={
             variant === "spotlight"
-              ? "h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
+              ? ONBOARDING_SECONDARY_CTA_CLASS
               : "h-10 w-full text-muted-foreground hover:text-accent-foreground"
           }
           disabled={isImporting}
-          onClick={onBack}
+          onClick={handleBack}
           type="button"
           variant="ghost"
         >
-          {backLabel}
+          {isPasswordStage ? "Back" : backLabel}
         </Button>
       </OnboardingFooter>
     </form>
diff --git a/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx b/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
index 111bdefd71..26f538da52 100644
--- a/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
+++ b/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
@@ -1,7 +1,23 @@
-import { Check, Copy, Eye, EyeOff } from "lucide-react";
+import { Check, Copy, Eye, EyeOff, MoreHorizontal } from "lucide-react";
 import * as React from "react";
 import { Button } from "@/shared/ui/button";
-import { writeTextToClipboard } from "@/shared/lib/clipboard";
+import {
+  copyTextToClipboard,
+  writeTextToClipboard,
+} from "@/shared/lib/clipboard";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+
+type NsecAction = {
+  icon?: React.ReactNode;
+  label: string;
+  onSelect: () => void;
+  testId?: string;
+};
 
 type NsecMaskedDisplayProps = {
   nsec: string;
@@ -12,6 +28,8 @@ type NsecMaskedDisplayProps = {
    * a backup (e.g. sign-out) gate on actual interaction with the key.
    */
   onKeyInteraction?: () => void;
+  /** Replaces the copy icon with an overflow menu containing Copy plus these actions. */
+  actions?: readonly NsecAction[];
 };
 
 export const ONBOARDING_KEY_FRAME_CLASS =
@@ -31,6 +49,7 @@ export function NsecMaskedDisplay({
   nsec,
   variant = "boxed",
   onKeyInteraction,
+  actions,
 }: NsecMaskedDisplayProps) {
   const [isRevealed, setIsRevealed] = React.useState(false);
   const [isCopied, setIsCopied] = React.useState(false);
@@ -58,6 +77,11 @@ export function NsecMaskedDisplay({
     copyTimerRef.current = setTimeout(() => setIsCopied(false), 2000);
   }
 
+  function handleMenuCopy() {
+    copyTextToClipboard(nsec);
+    onKeyInteraction?.();
+  }
+
   const isBare = variant === "bare";
   // Mask every character (no plaintext prefix leak), matching the real key's
   // length so toggling reveal never reflows the monospace text (no layout shift).
@@ -121,24 +145,60 @@ export function NsecMaskedDisplay({
               <Eye className={iconSize} aria-hidden="true" />
             )}
           </Button>
-          <Button
-            aria-label="Copy private key"
-            className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
-            data-testid="nsec-copy"
-            onClick={() => void handleCopy()}
-            size="icon"
-            type="button"
-            variant="ghost"
-          >
-            {isCopied ? (
-              <Check
-                className={`${iconSize} text-primary`}
-                aria-hidden="true"
-              />
-            ) : (
-              <Copy className={iconSize} aria-hidden="true" />
-            )}
-          </Button>
+          {actions?.length ? (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  aria-label="Private key actions"
+                  className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
+                  data-testid="nsec-actions"
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  <MoreHorizontal className={iconSize} aria-hidden="true" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="min-w-40!">
+                <DropdownMenuItem
+                  data-testid="nsec-copy"
+                  onSelect={handleMenuCopy}
+                >
+                  <Copy aria-hidden="true" />
+                  Copy
+                </DropdownMenuItem>
+                {actions.map((action) => (
+                  <DropdownMenuItem
+                    data-testid={action.testId}
+                    key={action.label}
+                    onSelect={action.onSelect}
+                  >
+                    {action.icon}
+                    {action.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) : (
+            <Button
+              aria-label="Copy private key"
+              className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
+              data-testid="nsec-copy"
+              onClick={() => void handleCopy()}
+              size="icon"
+              type="button"
+              variant="ghost"
+            >
+              {isCopied ? (
+                <Check
+                  className={`${iconSize} text-primary`}
+                  aria-hidden="true"
+                />
+              ) : (
+                <Copy className={iconSize} aria-hidden="true" />
+              )}
+            </Button>
+          )}
         </div>
       </div>
     </div>
diff --git a/desktop/src/features/onboarding/ui/OnboardingChrome.tsx b/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
index 936313bce0..7a52ae4999 100644
--- a/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
@@ -2,8 +2,8 @@ import { BuzzMark } from "@/shared/ui/buzz-logo/BuzzMark";
 
 /**
  * Positions in the first-launch flow: landing, identity/key, harness setup,
- * default config, community choice, community profile, meet the team. Used as
- * the default pagination length when a flow doesn't pass an explicit total.
+ * default config, community choice, community profile, meet the team. Password
+ * backup is an optional subview of identity/key, not another position.
  */
 export const TOTAL_ONBOARDING_PAGES = 7;
 
@@ -17,6 +17,9 @@ const ONBOARDING_CTA_SHAPE = "h-[2.375rem] rounded-full px-6";
  */
 export const ONBOARDING_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(--buzz-onboarding-cta-label)]`;
 
+/** Inverted primary action used only on dark backup-security surfaces. */
+export const ONBOARDING_SECURITY_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} bg-white text-black/80 hover:bg-white/90 hover:text-black`;
+
 /**
  * Primary-CTA styling for the landing screen only: the shared pill with the
  * chartreuse label (`--buzz-welcome-chartreuse`). The blue label is reserved
@@ -24,6 +27,10 @@ export const ONBOARDING_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(-
  */
 export const ONBOARDING_LANDING_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(--buzz-welcome-chartreuse)]`;
 
+/** Shared quiet pill for secondary actions throughout onboarding. */
+export const ONBOARDING_SECONDARY_CTA_CLASS =
+  "h-9 rounded-full bg-foreground/10 px-6 text-foreground hover:bg-foreground/15 hover:text-foreground";
+
 /**
  * Icon-control styling for onboarding surfaces that sit on the textured card:
  * olive backup ink (`--buzz-onboarding-backup-ink`) with a plain
@@ -34,6 +41,10 @@ export const ONBOARDING_LANDING_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(-
 export const ONBOARDING_INK_ICON_CLASS =
   "text-[color:var(--buzz-onboarding-backup-ink)] hover:bg-transparent hover:text-foreground";
 
+/** Icon controls on the dark noisy backup surfaces stay visually unboxed. */
+export const ONBOARDING_SECURITY_ICON_CLASS =
+  "text-muted-foreground hover:bg-transparent hover:text-foreground";
+
 /**
  * Shared onboarding chrome shown on every page after the landing screen: a
  * static Buzz mark pinned to the top-left, and a centered pagination track that
diff --git a/desktop/src/features/onboarding/ui/OnboardingFlow.tsx b/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
index 01a226e3de..a3653f750f 100644
--- a/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
@@ -388,8 +388,8 @@ export function OnboardingFlow({
   // key's relay profile reseeds the steps, and a key that already finished
   // onboarding on this machine skips straight into the app.
   const importExistingKey = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       relayClient.disconnect();
       queryClient.setQueryData(["identity"], identity);
       queryClient.removeQueries({ queryKey: profileQueryKey });
diff --git a/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx b/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
index 82d9a0213c..ba5d8b2c87 100644
--- a/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
@@ -14,6 +14,7 @@ export type OnboardingTransitionDirection = "forward" | "backward";
 export type OnboardingTransitionEffect =
   | "fade"
   | "line-slide"
+  | "mask-reveal-down"
   | "mask-reveal-up"
   | "none";
 
diff --git a/desktop/src/features/onboarding/ui/RuntimeIcon.tsx b/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
index f9c201d115..5b247c31f7 100644
--- a/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
+++ b/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
@@ -17,6 +17,7 @@ const RUNTIME_LOGOS: Record<string, string> = {
 // Public-path logos for bundled presets. Served from /harness-logos/ at runtime.
 // Keys match the preset `id` values emitted by the backend PRESET_HARNESSES.
 export const PRESET_LOGOS: Record<string, string> = {
+  devin: "/harness-logos/devin.svg",
   omp: "/harness-logos/omp.svg",
   grok: "/harness-logos/grok.svg",
   opencode: "/harness-logos/opencode.svg",
diff --git a/desktop/src/features/onboarding/ui/SetupStep.tsx b/desktop/src/features/onboarding/ui/SetupStep.tsx
index 843206aa70..911ddaf362 100644
--- a/desktop/src/features/onboarding/ui/SetupStep.tsx
+++ b/desktop/src/features/onboarding/ui/SetupStep.tsx
@@ -8,6 +8,7 @@ import {
   useConnectAcpRuntimeMutation,
   useInstallAcpRuntimeMutation,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import { describeResolvedCommand } from "@/features/agents/ui/agentUi";
 import type { AcpAuthMethod, AcpRuntimeCatalogEntry } from "@/shared/api/types";
 import { getInstallErrorMessage } from "@/shared/lib/installError";
@@ -483,6 +484,7 @@ function RuntimeCard({
   const installMutation = useInstallAcpRuntimeMutation();
   const installError = installResults[runtime.id]?.error ?? null;
   const isInstalling = installMutation.isPending;
+  const installOutputLine = useInstallOutputLine(runtime.id, isInstalling);
   const isAvailable = runtime.availability === "available";
   const isReady = runtimeIsReadyForOnboarding(runtime);
 
@@ -499,7 +501,7 @@ function RuntimeCard({
           [runtime.id]: result.success
             ? { error: null, success: true }
             : {
-                error: getInstallErrorMessage(result.steps),
+                error: getInstallErrorMessage(result),
                 success: false,
               },
         }));
@@ -542,7 +544,18 @@ function RuntimeCard({
           onInstall={handleInstall}
           runtime={runtime}
         />
-        {!isAvailable && runtimeDetailText(runtime) ? (
+        {isInstalling && installOutputLine ? (
+          // Takes the detail text's slot rather than adding a row: the card is
+          // fixed-height, and during an install the live line is the more
+          // useful of the two.
+          <p
+            aria-live="polite"
+            className="max-w-[13rem] truncate font-mono text-2xs leading-4 text-muted-foreground"
+            data-testid={`onboarding-runtime-install-output-${runtime.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : !isAvailable && runtimeDetailText(runtime) ? (
           <p
             aria-hidden={installError ? "true" : undefined}
             className={cn(
@@ -685,25 +698,28 @@ function SetupStepContent({
       />
 
       <OnboardingFooter>
-        <Button
-          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
-          data-testid="onboarding-setup-next"
-          disabled={readyRuntimeIds.length === 0}
-          onClick={() => actions.next(readyRuntimeIds)}
-          type="button"
-        >
-          Next
-        </Button>
-
-        <Button
-          className="h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15"
-          data-testid="onboarding-setup-skip"
-          onClick={() => actions.next([])}
-          type="button"
-          variant="ghost"
-        >
-          Skip for now
-        </Button>
+        {/* Relative row keeps the primary CTA truly centered while Skip
+            hangs off its right edge without shifting the center. */}
+        <div className="relative flex items-center justify-center">
+          <Button
+            className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+            data-testid="onboarding-setup-next"
+            disabled={readyRuntimeIds.length === 0}
+            onClick={() => actions.next(readyRuntimeIds)}
+            type="button"
+          >
+            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-setup-skip"
+            onClick={() => actions.next([])}
+            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"
diff --git a/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs b/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
index fa92214312..622db610aa 100644
--- a/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
+++ b/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
@@ -53,29 +53,11 @@ test("currentStep_falls_back_to_1_for_pages_outside_the_step_list", () => {
 });
 
 // ---------------------------------------------------------------------------
-// BackupStep gating: backupNextDisabled() pure helper
+// BackupStep gating: saving a password-protected backup is recommended, not required
 // ---------------------------------------------------------------------------
 
-test("backup_next_disabled_while_loading", () => {
-  // During a slow keychain read, Next must be blocked — user cannot race past
-  // the key display before it is shown.
-  assert.equal(backupNextDisabled({ isLoading: true, loadError: null }), true);
-});
-
-test("backup_next_disabled_on_load_error", () => {
-  // Error state: only the explicit "Skip for now" ghost advances; Next blocked.
-  assert.equal(
-    backupNextDisabled({ isLoading: false, loadError: "IPC error" }),
-    true,
-  );
-});
-
-test("backup_next_enabled_after_clean_load", () => {
-  // Key shown (or backend cleanly returned none) — user may proceed.
-  assert.equal(
-    backupNextDisabled({ isLoading: false, loadError: null }),
-    false,
-  );
+test("backup_next_is_always_enabled", () => {
+  assert.equal(backupNextDisabled(), false);
 });
 
 // ---------------------------------------------------------------------------
diff --git a/desktop/src/features/onboarding/ui/presetLogos.test.mjs b/desktop/src/features/onboarding/ui/presetLogos.test.mjs
index 0ff2193155..7a5df620da 100644
--- a/desktop/src/features/onboarding/ui/presetLogos.test.mjs
+++ b/desktop/src/features/onboarding/ui/presetLogos.test.mjs
@@ -24,15 +24,15 @@ const desktopRoot = path.resolve(
   "../../../..",
 );
 
-const discoveryRs = readFileSync(
-  path.join(desktopRoot, "src-tauri/src/managed_agents/discovery.rs"),
+const presetsRs = readFileSync(
+  path.join(desktopRoot, "src-tauri/src/managed_agents/discovery/presets.rs"),
   "utf8",
 );
 
-const presetBlock = discoveryRs.match(
+const presetBlock = presetsRs.match(
   /const PRESET_HARNESSES: &\[PresetHarness\] = &\[([\s\S]*?)\n\];/,
 );
-assert.ok(presetBlock, "could not locate PRESET_HARNESSES in discovery.rs");
+assert.ok(presetBlock, "could not locate PRESET_HARNESSES in presets.rs");
 
 const presetIds = [...presetBlock[1].matchAll(/^\s{8}id: "([^"]+)",$/gm)].map(
   (match) => match[1],
diff --git a/desktop/src/features/presence/hooks.ts b/desktop/src/features/presence/hooks.ts
index 5ba8683693..04936241df 100644
--- a/desktop/src/features/presence/hooks.ts
+++ b/desktop/src/features/presence/hooks.ts
@@ -11,14 +11,14 @@ import {
   mergePresenceUpdate,
   parseLivePresenceEvent,
   presenceQueryWantsPubkey,
+  PRESENCE_HEARTBEAT_INTERVAL_MS,
+  PRESENCE_TTL_SECONDS,
   resolveAutomaticPresenceStatus,
 } from "@/features/presence/lib/presence";
 import type { PresenceLookup, PresenceStatus } from "@/shared/api/types";
 
-const PRESENCE_HEARTBEAT_INTERVAL_MS = 30_000;
 const PRESENCE_STATUS_TICK_INTERVAL_MS = 30_000;
 const PRESENCE_ACTIVITY_THROTTLE_MS = 1_000;
-const PRESENCE_TTL_SECONDS = 90;
 const PRESENCE_PREFERENCE_STORAGE_KEY = "buzz-presence-preference";
 
 type PresencePreference = "auto" | "away" | "offline" | null;
diff --git a/desktop/src/features/presence/lib/presence.test.mjs b/desktop/src/features/presence/lib/presence.test.mjs
index c202dcb776..90a6ac524b 100644
--- a/desktop/src/features/presence/lib/presence.test.mjs
+++ b/desktop/src/features/presence/lib/presence.test.mjs
@@ -5,7 +5,9 @@ import {
   mergePresenceUpdate,
   parseLivePresenceEvent,
   presenceQueryWantsPubkey,
+  PRESENCE_HEARTBEAT_INTERVAL_MS,
   PRESENCE_IDLE_TIMEOUT_MS,
+  PRESENCE_TTL_SECONDS,
   resolveAutomaticPresenceStatus,
 } from "./presence.ts";
 
@@ -13,6 +15,15 @@ const WILL = "8e39cba681211b3782d0e4483e9343719b9b7be66515252da5491f26421896b1";
 const OTHER =
   "44b8e82baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
 
+test("presence heartbeat is one minute with a three-window TTL", () => {
+  assert.equal(PRESENCE_HEARTBEAT_INTERVAL_MS, 60_000);
+  assert.equal(PRESENCE_TTL_SECONDS, 180);
+  assert.equal(
+    PRESENCE_TTL_SECONDS,
+    3 * (PRESENCE_HEARTBEAT_INTERVAL_MS / 1000),
+  );
+});
+
 test("merge adds an absent pubkey going online (the core bug)", () => {
   const old = {};
   const next = mergePresenceUpdate(old, WILL, "online");
diff --git a/desktop/src/features/presence/lib/presence.ts b/desktop/src/features/presence/lib/presence.ts
index 34ac4fc353..5b1fdc21c5 100644
--- a/desktop/src/features/presence/lib/presence.ts
+++ b/desktop/src/features/presence/lib/presence.ts
@@ -36,6 +36,12 @@ export function mergePresenceUpdate(
   return { ...old, [pubkey]: status };
 }
 
+// Keep the local optimistic cache and relay expiry at three heartbeat windows.
+// The relay owns the authoritative TTL; deploy its TTL increase before shipping
+// a desktop build with a slower heartbeat.
+export const PRESENCE_HEARTBEAT_INTERVAL_MS = 60_000;
+export const PRESENCE_TTL_SECONDS = 3 * (PRESENCE_HEARTBEAT_INTERVAL_MS / 1000);
+
 // Away means "human not at the machine" (Slack/Discord semantics), never
 // "Buzz is not the focused window". OS-wide idle is authoritative when the
 // platform exposes it; otherwise fall back to in-app activity.
diff --git a/desktop/src/features/profile/ui/UserProfilePanel.tsx b/desktop/src/features/profile/ui/UserProfilePanel.tsx
index c1f713d230..af30728d6a 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,8 +951,11 @@ export function UserProfilePanel({
           updateManagedAgentMutation.isPending ||
           createAgentMutation.isPending
         }
+        linkedAgentPubkey={managedAgent?.pubkey ?? null}
         personaDialogState={personaDialogState}
         personaToDelete={personaToDelete}
+        personaToExportSnapshot={personaToExportSnapshot}
+        resolvedPersona={resolvedPersona}
         runtimes={acpRuntimesQuery.data ?? []}
         runtimesLoading={acpRuntimesQuery.isLoading}
         updateError={
@@ -942,22 +963,16 @@ export function UserProfilePanel({
             ? 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..057376a38c 100644
--- a/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
@@ -1,19 +1,11 @@
 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";
@@ -44,19 +36,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 +98,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 +213,7 @@ export function ProfileSummaryView({
   onOpenInstructions,
   onTabChange,
   onOpenDm,
+  onCreateCard,
   presenceStatus,
   profile,
   pubkey,
@@ -349,6 +345,7 @@ export function ProfileSummaryView({
         <ProfilePersonaPrimaryActions
           canEditAgent={canEditAgent}
           disabled={isAgentActionPending}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           onStartAgent={handleInstantiateAgent}
         />
@@ -356,6 +353,7 @@ export function ProfileSummaryView({
         <ProfilePrimaryActions
           canEditAgent={canEditAgent}
           followMutation={followMutation}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           agentActionDisabled={isAgentActionPending}
           agentActionLabel={
@@ -629,181 +627,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/UserProfilePersonaDialogs.tsx b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
index 5e468b5320..2de2e2f716 100644
--- a/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
@@ -4,36 +4,59 @@ 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,
   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;
   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>;
 }) {
   return (
@@ -67,6 +90,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 f2739088a6..da51ab1b88 100644
--- a/desktop/src/features/profile/ui/UserProfilePopover.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePopover.tsx
@@ -260,11 +260,18 @@ export function UserProfilePopover({
   const selfProfileQuery = useProfileQuery(open && showProfileActions);
   const isCurrentUserOwner = ownsAuthorAgent(profile, currentPubkey);
   const viewerIsOwner = isCurrentUserOwner || isOwner === true;
+  const showHuddleAction =
+    showHumanProfileActions ||
+    (showProfileActions &&
+      isBotProfile &&
+      viewerIsOwner &&
+      !isAgentClassificationPending);
   const showMessageAction =
     showProfileActions &&
     !isAgentClassificationPending &&
     (!isBotProfile || viewerIsOwner);
-  const showAnyProfileActions = showHumanProfileActions || showMessageAction;
+  const showAnyProfileActions =
+    showHumanProfileActions || showMessageAction || showHuddleAction;
   const canViewActivity =
     isBotProfile && viewerIsOwner && canOpenAgentActivity(pubkey);
   const presenceStatus = presenceQuery.data?.[pubkey.toLowerCase()];
@@ -356,7 +363,7 @@ export function UserProfilePopover({
   const handleHuddle = React.useCallback(async () => {
     if (
       !showProfileActions ||
-      !showHumanProfileActions ||
+      !showHuddleAction ||
       pendingAction !== null ||
       isStartingHuddle
     ) {
@@ -369,7 +376,7 @@ export function UserProfilePopover({
     try {
       const dm = await openDmMutation.mutateAsync({ pubkeys: [pubkey] });
       await goChannel(dm.id);
-      await startHuddle(dm.id, []);
+      await startHuddle(dm.id, isBotProfile ? [pubkey] : []);
       await queryClient.invalidateQueries({ queryKey: channelsQueryKey });
       if (isMountedRef.current) {
         setOpen(false);
@@ -389,7 +396,8 @@ export function UserProfilePopover({
     pendingAction,
     pubkey,
     queryClient,
-    showHumanProfileActions,
+    isBotProfile,
+    showHuddleAction,
     showProfileActions,
     startHuddle,
   ]);
@@ -722,7 +730,7 @@ export function UserProfilePopover({
                       Message
                     </Button>
                   ) : null}
-                  {showHumanProfileActions ? (
+                  {showHuddleAction ? (
                     <Button
                       className="min-w-0 flex-1"
                       data-testid={`user-profile-popover-huddle-${pubkey}`}
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/settings/EncryptedBackupProvider.tsx b/desktop/src/features/settings/EncryptedBackupProvider.tsx
new file mode 100644
index 0000000000..7375a85cfb
--- /dev/null
+++ b/desktop/src/features/settings/EncryptedBackupProvider.tsx
@@ -0,0 +1,251 @@
+import * as React from "react";
+import { toast } from "sonner";
+
+import {
+  createNcryptsecBackup,
+  saveNcryptsecCopy,
+} from "@/shared/api/tauriIdentity";
+import {
+  type EncryptedBackupEvent,
+  type EncryptedBackupState,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+  pendingEncryptPassphrase,
+} from "./lib/encryptedBackup";
+
+const ENCRYPT_DEBOUNCE_MS = 400;
+/** How long a completed encrypted backup remains available in memory. */
+export const BACKUP_AVAILABILITY_MS = 5 * 60 * 1000;
+const BACKUP_READY_TOAST_ID = "encrypted-key-backup-ready";
+
+type EncryptedBackupContextValue = {
+  state: EncryptedBackupState;
+  dispatch: React.Dispatch<EncryptedBackupEvent>;
+  backupAvailable: boolean;
+  availableUntil: number | null;
+  isSaving: boolean;
+  saveError: string | null;
+  downloadBackup: () => Promise<void>;
+  startNewBackup: () => void;
+};
+
+const EncryptedBackupContext =
+  React.createContext<EncryptedBackupContextValue | null>(null);
+
+export function EncryptedBackupProvider({
+  children,
+  onOpenSettings,
+}: {
+  children: React.ReactNode;
+  onOpenSettings: () => void;
+}) {
+  const [state, dispatch] = React.useReducer(
+    encryptedBackupReducer,
+    initialEncryptedBackupState,
+  );
+  const [availableUntil, setAvailableUntil] = React.useState<number | null>(
+    null,
+  );
+  const [isSaving, setIsSaving] = React.useState(false);
+  const [saveError, setSaveError] = React.useState<string | null>(null);
+  const autoSaveStartedForRef = React.useRef<string | null>(null);
+  const mountedRef = React.useRef(true);
+  const onOpenSettingsRef = React.useRef(onOpenSettings);
+
+  React.useEffect(() => {
+    onOpenSettingsRef.current = onOpenSettings;
+  }, [onOpenSettings]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (availableUntil === null) return;
+    const expiresIn = Math.max(0, availableUntil - Date.now());
+    const timer = window.setTimeout(() => {
+      autoSaveStartedForRef.current = null;
+      setAvailableUntil(null);
+      setSaveError(null);
+      dispatch({ type: "start-new-backup" });
+      toast.dismiss(BACKUP_READY_TOAST_ID);
+    }, expiresIn);
+    return () => window.clearTimeout(timer);
+  }, [availableUntil]);
+
+  const pendingPassphrase = pendingEncryptPassphrase(state);
+  const skipDebounce = state.downloadPending;
+  React.useEffect(() => {
+    if (!pendingPassphrase) return;
+    let started = false;
+    let cancelledBeforeStart = false;
+    const requestId = state.nextRequestId;
+    const start = () => {
+      if (cancelledBeforeStart) return;
+      started = true;
+      dispatch({ type: "encrypt-started", requestId });
+      void createNcryptsecBackup(pendingPassphrase)
+        .then((ncryptsec) => {
+          dispatch({ type: "encrypt-succeeded", requestId, ncryptsec });
+        })
+        .catch((err: unknown) => {
+          dispatch({
+            type: "encrypt-failed",
+            requestId,
+            message:
+              err instanceof Error
+                ? err.message
+                : "Failed to encrypt your key.",
+          });
+        });
+    };
+    const timer = window.setTimeout(
+      start,
+      skipDebounce ? 0 : ENCRYPT_DEBOUNCE_MS,
+    );
+    return () => {
+      if (!started) cancelledBeforeStart = true;
+      window.clearTimeout(timer);
+    };
+  }, [pendingPassphrase, skipDebounce, state.nextRequestId]);
+
+  React.useEffect(() => {
+    if (state.downloadPending) {
+      toast.loading("Preparing backup…", {
+        description: "You can close this window while Buzz finishes.",
+        duration: Number.POSITIVE_INFINITY,
+        id: BACKUP_READY_TOAST_ID,
+      });
+      return;
+    }
+    if (
+      state.createError &&
+      state.passphrase.length === 0 &&
+      !state.ncryptsec
+    ) {
+      toast.error("Couldn’t create backup", {
+        description: state.createError,
+        id: BACKUP_READY_TOAST_ID,
+      });
+    }
+  }, [
+    state.createError,
+    state.downloadPending,
+    state.ncryptsec,
+    state.passphrase.length,
+  ]);
+
+  const showAvailableToast = React.useCallback(
+    (description: string, error = false) => {
+      const options = {
+        action: {
+          label: "Open settings",
+          onClick: () => onOpenSettingsRef.current(),
+        },
+        description,
+        id: BACKUP_READY_TOAST_ID,
+      };
+      if (error) toast.error("Backup ready to download", options);
+      else toast.success("Backup ready to download", options);
+    },
+    [],
+  );
+
+  const saveBackup = React.useCallback(
+    async (ncryptsec: string) => {
+      if (isSaving) return;
+      setIsSaving(true);
+      setSaveError(null);
+      toast("Saving backup…", {
+        description: "The download window will open when it’s ready.",
+        id: BACKUP_READY_TOAST_ID,
+      });
+      try {
+        const path = await saveNcryptsecCopy(ncryptsec);
+        if (mountedRef.current) {
+          showAvailableToast(
+            path === null
+              ? "Your backup will be available to download for 5 minutes."
+              : "You can download another copy for 5 minutes.",
+          );
+        }
+      } catch (err) {
+        if (!mountedRef.current) return;
+        const message =
+          err instanceof Error ? err.message : "Failed to save your key.";
+        setSaveError(message);
+        showAvailableToast(
+          `${message} It will be available to download for 5 minutes.`,
+          true,
+        );
+      } finally {
+        if (mountedRef.current) setIsSaving(false);
+      }
+    },
+    [isSaving, showAvailableToast],
+  );
+
+  React.useEffect(() => {
+    const ncryptsec = state.ncryptsec;
+    if (!ncryptsec || autoSaveStartedForRef.current === ncryptsec) return;
+    autoSaveStartedForRef.current = ncryptsec;
+    setAvailableUntil(Date.now() + BACKUP_AVAILABILITY_MS);
+    void saveBackup(ncryptsec);
+  }, [saveBackup, state.ncryptsec]);
+
+  const downloadBackup = React.useCallback(async () => {
+    if (!state.ncryptsec) return;
+    await saveBackup(state.ncryptsec);
+  }, [saveBackup, state.ncryptsec]);
+
+  const startNewBackup = React.useCallback(() => {
+    autoSaveStartedForRef.current = null;
+    setAvailableUntil(null);
+    setSaveError(null);
+    toast.dismiss(BACKUP_READY_TOAST_ID);
+    dispatch({ type: "start-new-backup" });
+  }, []);
+
+  const value = React.useMemo<EncryptedBackupContextValue>(
+    () => ({
+      state,
+      dispatch,
+      backupAvailable:
+        state.savedPassword &&
+        state.ncryptsec !== null &&
+        availableUntil !== null,
+      availableUntil,
+      isSaving,
+      saveError,
+      downloadBackup,
+      startNewBackup,
+    }),
+    [
+      availableUntil,
+      downloadBackup,
+      isSaving,
+      saveError,
+      startNewBackup,
+      state,
+    ],
+  );
+
+  return (
+    <EncryptedBackupContext.Provider value={value}>
+      {children}
+    </EncryptedBackupContext.Provider>
+  );
+}
+
+export function useEncryptedBackup(): EncryptedBackupContextValue {
+  const value = React.useContext(EncryptedBackupContext);
+  if (!value) {
+    throw new Error(
+      "useEncryptedBackup must be used within EncryptedBackupProvider",
+    );
+  }
+  return value;
+}
diff --git a/desktop/src/features/settings/lib/encryptedBackup.test.mjs b/desktop/src/features/settings/lib/encryptedBackup.test.mjs
new file mode 100644
index 0000000000..306e937ec5
--- /dev/null
+++ b/desktop/src/features/settings/lib/encryptedBackup.test.mjs
@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  MIN_PASSPHRASE_LEN,
+  downloadDisabled,
+  isEncrypting,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  effectivePassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+} from "./encryptedBackup.ts";
+const reduce = (events, from = initialEncryptedBackupState) =>
+  events.reduce(encryptedBackupReducer, from);
+test("password validation mirrors Rust character counting", () => {
+  assert.equal(passphraseIssue(""), null);
+  assert.match(passphraseIssue("short"), new RegExp(`${MIN_PASSPHRASE_LEN}`));
+  const emoji = "😀".repeat(MIN_PASSPHRASE_LEN);
+  assert.equal(passphraseIssue(emoji), null);
+  assert.equal(
+    effectivePassphrase(reduce([{ type: "set-passphrase", value: emoji }])),
+    emoji,
+  );
+});
+test("valid password requests encryption without copying it into events", () => {
+  const ready = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+  ]);
+  assert.equal(pendingEncryptPassphrase(ready), "one-two-three-four");
+  const started = reduce([{ type: "encrypt-started", requestId: 1 }], ready);
+  assert.equal(isEncrypting(started), true);
+  assert.equal(started.requestId, 1);
+  assert.equal(Object.hasOwn(started, "encryptingPassphrase"), false);
+});
+test("background success retains the password without committing the download", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.passphrase, "one-two-three-four");
+  assert.equal(state.encrypted, "ncryptsec1abc");
+  assert.equal(state.ncryptsec, null);
+  assert.equal(state.savedPassword, false);
+  assert.equal(state.requestId, null);
+  assert.equal(downloadDisabled(state), false);
+});
+test("submit commits a completed preload immediately", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+    { type: "download-clicked" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("stale async completions cannot replace current request", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "set-passphrase", value: "five-six-seven-eight" },
+    { type: "encrypt-started", requestId: 2 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1stale" },
+  ]);
+  assert.equal(state.requestId, 2);
+  assert.equal(state.encrypted, null);
+  assert.equal(state.passphrase, "five-six-seven-eight");
+});
+test("failure clears submitted password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(state.passphrase, "");
+  assert.equal(state.createError, "keychain unavailable");
+  assert.equal(state.downloadPending, false);
+  assert.equal(downloadDisabled(state), true);
+});
+test("background failure stays silent until submit retries encryption", () => {
+  const failed = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(failed.passphrase, "one-two-three-four");
+  assert.equal(failed.createError, "keychain unavailable");
+  assert.equal(pendingEncryptPassphrase(failed), null);
+
+  const retrying = reduce([{ type: "download-clicked" }], failed);
+  assert.equal(retrying.createError, null);
+  assert.equal(retrying.downloadPending, true);
+  assert.equal(pendingEncryptPassphrase(retrying), "one-two-three-four");
+});
+test("queued download commits and clears password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("starting over discards blob and invalidates late requests", () => {
+  const made = {
+    ...initialEncryptedBackupState,
+    ncryptsec: "ncryptsec1abc",
+    encrypted: "ncryptsec1abc",
+    savedPassword: true,
+    nextRequestId: 3,
+  };
+  const fresh = reduce([{ type: "start-new-backup" }], made);
+  assert.equal(fresh.ncryptsec, null);
+  assert.equal(fresh.nextRequestId, 4);
+  assert.equal(
+    reduce(
+      [
+        {
+          type: "encrypt-succeeded",
+          requestId: 2,
+          ncryptsec: "ncryptsec1stale",
+        },
+      ],
+      fresh,
+    ).ncryptsec,
+    null,
+  );
+});
diff --git a/desktop/src/features/settings/lib/encryptedBackup.ts b/desktop/src/features/settings/lib/encryptedBackup.ts
new file mode 100644
index 0000000000..e54189769a
--- /dev/null
+++ b/desktop/src/features/settings/lib/encryptedBackup.ts
@@ -0,0 +1,143 @@
+/** Pure state model for NIP-49 backup creation. */
+export const MIN_PASSPHRASE_LEN = 12;
+
+export type EncryptedBackupState = {
+  passphrase: string;
+  requestId: number | null;
+  nextRequestId: number;
+  encrypted: string | null;
+  createError: string | null;
+  downloadPending: boolean;
+  ncryptsec: string | null;
+  savedPassword: boolean;
+};
+
+export const initialEncryptedBackupState: EncryptedBackupState = {
+  passphrase: "",
+  requestId: null,
+  nextRequestId: 1,
+  encrypted: null,
+  createError: null,
+  downloadPending: false,
+  ncryptsec: null,
+  savedPassword: false,
+};
+
+export type EncryptedBackupEvent =
+  | { type: "set-passphrase"; value: string }
+  | { type: "encrypt-started"; requestId: number }
+  | { type: "encrypt-succeeded"; requestId: number; ncryptsec: string }
+  | { type: "encrypt-failed"; requestId: number; message: string }
+  | { type: "download-clicked" }
+  | { type: "start-new-backup" };
+
+export function encryptedBackupReducer(
+  state: EncryptedBackupState,
+  event: EncryptedBackupEvent,
+): EncryptedBackupState {
+  switch (event.type) {
+    case "set-passphrase":
+      return {
+        ...state,
+        passphrase: event.value,
+        requestId: null,
+        encrypted: null,
+        createError: null,
+      };
+    case "encrypt-started":
+      return {
+        ...state,
+        requestId: event.requestId,
+        nextRequestId: Math.max(state.nextRequestId, event.requestId + 1),
+        createError: null,
+      };
+    case "encrypt-succeeded":
+      if (event.requestId !== state.requestId) return state;
+      return state.downloadPending
+        ? {
+            ...state,
+            passphrase: "",
+            requestId: null,
+            encrypted: event.ncryptsec,
+            ncryptsec: event.ncryptsec,
+            downloadPending: false,
+            savedPassword: true,
+          }
+        : {
+            ...state,
+            requestId: null,
+            encrypted: event.ncryptsec,
+          };
+    case "encrypt-failed":
+      if (event.requestId !== state.requestId) return state;
+      return state.downloadPending
+        ? {
+            ...state,
+            passphrase: "",
+            requestId: null,
+            createError: event.message,
+            downloadPending: false,
+          }
+        : {
+            ...state,
+            requestId: null,
+            createError: event.message,
+          };
+    case "download-clicked":
+      if (
+        state.ncryptsec ||
+        state.downloadPending ||
+        (!state.encrypted && !effectivePassphrase(state))
+      )
+        return state;
+      return state.encrypted
+        ? {
+            ...state,
+            ncryptsec: state.encrypted,
+            passphrase: "",
+            savedPassword: true,
+          }
+        : { ...state, createError: null, downloadPending: true };
+    case "start-new-backup":
+      return {
+        ...initialEncryptedBackupState,
+        nextRequestId: state.nextRequestId + 1,
+      };
+  }
+}
+
+export function passphraseIssue(passphrase: string): string | null {
+  if (passphrase.length === 0) return null;
+  return [...passphrase].length < MIN_PASSPHRASE_LEN
+    ? `Use at least ${MIN_PASSPHRASE_LEN} characters.`
+    : null;
+}
+export function effectivePassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  return [...state.passphrase].length < MIN_PASSPHRASE_LEN
+    ? null
+    : state.passphrase;
+}
+export function pendingEncryptPassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  if (
+    state.savedPassword ||
+    state.encrypted ||
+    state.requestId !== null ||
+    (state.createError !== null && !state.downloadPending)
+  )
+    return null;
+  return effectivePassphrase(state);
+}
+export function isEncrypting(state: EncryptedBackupState): boolean {
+  return state.requestId !== null;
+}
+export function downloadDisabled(state: EncryptedBackupState): boolean {
+  if (state.savedPassword && state.ncryptsec) return false;
+  return (
+    state.downloadPending ||
+    (!state.encrypted && effectivePassphrase(state) === null)
+  );
+}
diff --git a/desktop/src/features/settings/ui/BackupTestFlow.tsx b/desktop/src/features/settings/ui/BackupTestFlow.tsx
new file mode 100644
index 0000000000..65ef40a98a
--- /dev/null
+++ b/desktop/src/features/settings/ui/BackupTestFlow.tsx
@@ -0,0 +1,459 @@
+import { Check, Eye, EyeOff, FileKey2, FileUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+
+import {
+  verifyNcryptsecBackup,
+  type BackupVerification,
+} from "@/shared/api/tauriIdentity";
+import { Button } from "@/shared/ui/button";
+import { Input } from "@/shared/ui/input";
+import { PubKey } from "@/shared/ui/PubKey";
+import { Spinner } from "@/shared/ui/spinner";
+
+type BackupTestStage = "drop" | "password" | "success";
+
+/**
+ * Progress through the Settings backup-test flow. The password attempt is
+ * deliberately NOT part of this state — it lives only in short-lived
+ * moment it's submitted or the component unmounts.
+ */
+export type BackupTestProgress = {
+  stage: BackupTestStage;
+  /** Name of the accepted file once the drop check passed. */
+  fileName: string | null;
+  /** Contents of the accepted file, pending or past verification. */
+  ncryptsec: string | null;
+  /** The Rust-verified public identity once decryption succeeded. */
+  result: BackupVerification | null;
+};
+
+export const initialBackupTestProgress: BackupTestProgress = {
+  stage: "drop",
+  fileName: null,
+  ncryptsec: null,
+  result: null,
+};
+
+type BackupTestFlowProps = {
+  progress: BackupTestProgress;
+  onProgressChange: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+};
+
+const BURST_EMOJIS = ["🎉", "✨", "🐝", "🍯", "🔑", "💛"] as const;
+const BURST_PARTICLE_COUNT = 18;
+
+type BurstParticle = {
+  id: number;
+  x: number;
+  y: number;
+  emoji: string;
+  delay: number;
+  scale: number;
+  rotate: number;
+};
+
+/**
+ * One-shot radial emoji burst behind the success badge. Purely decorative —
+ * skipped entirely under reduced motion.
+ */
+function SuccessBurst() {
+  const particles = React.useMemo<BurstParticle[]>(
+    () =>
+      Array.from({ length: BURST_PARTICLE_COUNT }, (_, i) => {
+        const angle =
+          (i / BURST_PARTICLE_COUNT) * Math.PI * 2 + Math.random() * 0.5;
+        const distance = 70 + Math.random() * 80;
+        return {
+          id: i,
+          x: Math.cos(angle) * distance,
+          y: Math.sin(angle) * distance,
+          emoji: BURST_EMOJIS[i % BURST_EMOJIS.length],
+          delay: Math.random() * 0.18,
+          scale: 0.8 + Math.random() * 0.7,
+          rotate: -120 + Math.random() * 240,
+        };
+      }),
+    [],
+  );
+
+  return (
+    <div
+      aria-hidden
+      className="pointer-events-none absolute inset-0 flex items-center justify-center overflow-visible"
+    >
+      {particles.map((particle) => (
+        <motion.span
+          animate={{
+            x: particle.x,
+            y: particle.y,
+            opacity: 0,
+            scale: particle.scale,
+            rotate: particle.rotate,
+          }}
+          className="absolute text-xl"
+          initial={{ x: 0, y: 0, opacity: 1, scale: 0.3, rotate: 0 }}
+          key={particle.id}
+          transition={{
+            duration: 0.9,
+            delay: particle.delay,
+            ease: "easeOut",
+          }}
+        >
+          {particle.emoji}
+        </motion.span>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * "Test your backup" flow: the user drops a backup file onto a large
+ * dropzone, then enters its password. Verification is a real NIP-49 decrypt
+ * in Rust — the submitted password is cleared immediately after the result
+ * and only the derived public identity ever comes back.
+ */
+export function BackupTestFlow({
+  progress,
+  onProgressChange,
+}: BackupTestFlowProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const { stage, fileName, ncryptsec, result } = progress;
+  // True while a file drag is anywhere over the window — the drop overlay
+  // takes over the host surface only for the duration of the drag.
+  const [isWindowDragging, setIsWindowDragging] = React.useState(false);
+  const dragDepthRef = React.useRef(0);
+
+  React.useEffect(() => {
+    // dragenter/dragleave fire per nested element, so track depth to know
+    // when the drag has actually left the window.
+    const handleDragEnter = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes("Files")) return;
+      dragDepthRef.current += 1;
+      setIsWindowDragging(true);
+    };
+    const handleDragLeave = () => {
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      if (dragDepthRef.current === 0) setIsWindowDragging(false);
+    };
+    const handleDragEnd = () => {
+      dragDepthRef.current = 0;
+      setIsWindowDragging(false);
+    };
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDragEnd);
+    window.addEventListener("dragend", handleDragEnd);
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDragEnd);
+      window.removeEventListener("dragend", handleDragEnd);
+    };
+  }, []);
+
+  // The password attempt is component-local, never host state: it is cleared
+  // when verification is submitted and when this component unmounts.
+  const [attempt, setAttempt] = React.useState("");
+  const [error, setError] = React.useState<string | null>(null);
+  const [isVerifying, setIsVerifying] = React.useState(false);
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const fileInputRef = React.useRef<HTMLInputElement | null>(null);
+  const passwordInputRef = React.useRef<HTMLInputElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Opaque correlation id so a stale in-flight verification can't commit
+  // after "Use a different file" or unmount.
+  const requestRef = React.useRef(0);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      requestRef.current += 1;
+      setAttempt("");
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (stage === "password") passwordInputRef.current?.focus();
+  }, [stage]);
+
+  const handleFile = React.useCallback(
+    async (file: File) => {
+      let text: string;
+      try {
+        text = (await file.text()).trim();
+      } catch {
+        if (mountedRef.current) setError("Could not read that file.");
+        return;
+      }
+      if (!mountedRef.current) return;
+      if (!text.toLowerCase().startsWith("ncryptsec1")) {
+        setError("That doesn't look like a key backup file.");
+        return;
+      }
+      setError(null);
+      setAttempt("");
+      onProgressChange({
+        stage: "password",
+        fileName: file.name,
+        ncryptsec: text,
+        result: null,
+      });
+    },
+    [onProgressChange],
+  );
+
+  const handleVerify = React.useCallback(async () => {
+    if (!ncryptsec || !attempt || isVerifying) return;
+    const password = attempt;
+    const requestId = ++requestRef.current;
+    setIsVerifying(true);
+    setError(null);
+    setIsRevealed(false);
+    // Clear the attempt the moment it's handed to Rust — success or failure,
+    // the typed password never lingers in the field.
+    setAttempt("");
+    try {
+      const verified = await verifyNcryptsecBackup(ncryptsec, password);
+      if (!mountedRef.current || requestId !== requestRef.current) return;
+      onProgressChange((prev) => ({
+        ...prev,
+        stage: "success",
+        result: verified,
+      }));
+    } catch (err) {
+      if (mountedRef.current && requestId === requestRef.current)
+        setError(
+          err instanceof Error ? err.message : "Could not verify this backup.",
+        );
+    } finally {
+      if (mountedRef.current && requestId === requestRef.current)
+        setIsVerifying(false);
+    }
+  }, [attempt, isVerifying, ncryptsec, onProgressChange]);
+
+  if (stage === "success" && result) {
+    return (
+      <div
+        className="relative flex flex-col items-center gap-4 py-4 text-center"
+        data-testid="backup-test-success"
+      >
+        {reduceMotion ? null : <SuccessBurst />}
+        <motion.div
+          animate={{ scale: 1, opacity: 1 }}
+          className="flex h-16 w-16 items-center justify-center rounded-full bg-primary text-primary-foreground"
+          initial={reduceMotion ? false : { scale: 0, opacity: 0 }}
+          transition={
+            reduceMotion
+              ? { duration: 0 }
+              : { type: "spring", stiffness: 380, damping: 18 }
+          }
+        >
+          <Check aria-hidden="true" className="h-8 w-8" strokeWidth={3} />
+        </motion.div>
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          initial={reduceMotion ? false : { opacity: 0, y: 8 }}
+          transition={
+            reduceMotion ? { duration: 0 } : { delay: 0.15, duration: 0.35 }
+          }
+        >
+          <p className="text-lg font-medium text-foreground">
+            This backup works
+          </p>
+          <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+            {result.matchesCurrentIdentity
+              ? "It restores your current Buzz identity."
+              : "It restores a different identity than the one signed in here."}
+          </p>
+          <div className="mt-3 flex justify-center">
+            <PubKey
+              pubkey={result.pubkey}
+              testId="backup-test-npub"
+              variant="full"
+            />
+          </div>
+        </motion.div>
+        <Button
+          className="h-8 rounded-full px-4 text-xs text-muted-foreground hover:text-foreground"
+          data-testid="backup-test-another"
+          onClick={() => {
+            setError(null);
+            onProgressChange(initialBackupTestProgress);
+          }}
+          type="button"
+          variant="ghost"
+        >
+          Test another backup
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mx-auto w-full max-w-125 space-y-4"
+      data-testid="backup-test-flow"
+    >
+      {stage === "drop" ? (
+        <>
+          <input
+            accept=".ncryptsec,text/plain"
+            className="sr-only"
+            data-testid="backup-test-file-input"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              // Allow re-selecting the same file after an error.
+              event.target.value = "";
+              if (file) void handleFile(file);
+            }}
+            ref={fileInputRef}
+            tabIndex={-1}
+            type="file"
+          />
+          <button
+            className="mx-auto flex h-9 items-center justify-center rounded-full bg-primary px-6 text-center text-primary-foreground shadow transition-colors hover:bg-primary/90"
+            data-testid="backup-test-dropzone"
+            onClick={() => fileInputRef.current?.click()}
+            type="button"
+          >
+            <span className="text-sm font-medium">Select your backup file</span>
+          </button>
+          {isWindowDragging ? (
+            /*
+             * Composer-style takeover: fills the nearest positioned host
+             * surface (the settings backup row) and is
+             * itself the drop target, so anywhere on that surface accepts
+             * the file.
+             */
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer-only drop target; the select button is the keyboard-accessible path
+            <div
+              className="absolute inset-2 z-10 mt-0! flex items-center justify-center rounded-2xl border-2 border-dashed border-primary bg-primary/10 backdrop-blur-sm"
+              data-testid="backup-test-drop-overlay"
+              onDragOver={(event) => event.preventDefault()}
+              onDrop={(event) => {
+                event.preventDefault();
+                const file = event.dataTransfer.files?.[0];
+                if (file) void handleFile(file);
+              }}
+            >
+              <span className="flex items-center gap-2 rounded-full bg-foreground px-4 py-2 text-sm font-semibold text-background shadow-sm ring-1 ring-background/15">
+                <FileUp aria-hidden="true" className="size-4" />
+                <span>Drop your backup file here</span>
+              </span>
+            </div>
+          ) : null}
+          {error ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="backup-test-error"
+              role="alert"
+            >
+              {error}
+            </p>
+          ) : null}
+        </>
+      ) : (
+        <>
+          <div
+            className="flex items-center justify-center gap-2 text-sm text-foreground animate-in fade-in slide-in-from-bottom-1 duration-300 motion-reduce:animate-none"
+            data-testid="backup-test-file-accepted"
+          >
+            <FileKey2
+              aria-hidden="true"
+              className="h-4 w-4 text-muted-foreground"
+            />
+            <span className="max-w-70 truncate font-mono text-xs">
+              {fileName}
+            </span>
+            <Check aria-hidden="true" className="h-4 w-4 text-primary" />
+          </div>
+          <p className="text-center text-sm leading-6 text-muted-foreground">
+            That's the one. Now enter your password to prove you can unlock it.
+          </p>
+          <div className="relative">
+            <Input
+              aria-label="Backup password"
+              autoComplete="off"
+              className="h-10 bg-background pr-10 font-mono"
+              data-testid="backup-test-password"
+              disabled={isVerifying}
+              onChange={(event) => setAttempt(event.target.value)}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  void handleVerify();
+                }
+              }}
+              placeholder="Your backup password"
+              ref={passwordInputRef}
+              type={isRevealed ? "text" : "password"}
+              value={attempt}
+            />
+            <Button
+              aria-label={isRevealed ? "Hide password" : "Reveal password"}
+              className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+              data-testid="backup-test-password-reveal-toggle"
+              disabled={isVerifying}
+              onClick={() => setIsRevealed((revealed) => !revealed)}
+              size="icon"
+              type="button"
+              variant="ghost"
+            >
+              {isRevealed ? (
+                <EyeOff aria-hidden="true" className="h-4 w-4" />
+              ) : (
+                <Eye aria-hidden="true" className="h-4 w-4" />
+              )}
+            </Button>
+            {error ? (
+              <p
+                className="absolute left-1 top-full mt-1 text-xs text-destructive animate-in fade-in duration-200 motion-reduce:animate-none"
+                data-testid="backup-test-error"
+                role="alert"
+              >
+                {error}
+              </p>
+            ) : null}
+          </div>
+          <div className="flex items-center justify-center gap-3 pt-2">
+            <Button
+              className="h-9 rounded-full bg-primary px-6 text-sm font-medium text-primary-foreground shadow transition-colors hover:bg-primary/90"
+              data-testid="backup-test-verify"
+              disabled={!attempt || isVerifying}
+              onClick={() => void handleVerify()}
+              type="button"
+            >
+              {isVerifying ? (
+                <>
+                  <Spinner className="h-4 w-4 border-2" />
+                  Checking…
+                </>
+              ) : (
+                "Verify backup"
+              )}
+            </Button>
+            <Button
+              className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+              data-testid="backup-test-use-different-file"
+              disabled={isVerifying}
+              onClick={() => {
+                requestRef.current += 1;
+                setAttempt("");
+                setError(null);
+                setIsRevealed(false);
+                onProgressChange(initialBackupTestProgress);
+              }}
+              size="sm"
+              type="button"
+              variant="ghost"
+            >
+              Use a different file
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx b/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx
new file mode 100644
index 0000000000..fb20eb9c65
--- /dev/null
+++ b/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx
@@ -0,0 +1,375 @@
+import { AlertTriangle, Eye, EyeOff, RefreshCw } from "lucide-react";
+import * as React from "react";
+
+import { generateBackupPassphrase } from "@/shared/api/tauriIdentity";
+import { useEncryptedBackup } from "@/features/settings/EncryptedBackupProvider";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { downloadDisabled, MIN_PASSPHRASE_LEN } from "../lib/encryptedBackup";
+
+/** Word-count bounds mirroring `key_backup.rs` (Rust clamps regardless). */
+const MIN_GENERATED_WORDS = 3;
+const MAX_GENERATED_WORDS = 10;
+const DEFAULT_GENERATED_WORDS = 3;
+
+const SEPARATOR_OPTIONS = [
+  { label: "Spaces", value: " " },
+  { label: "Hyphens", value: "-" },
+  { label: "Periods", value: "." },
+  { label: "Commas", value: "," },
+] as const;
+
+const DEFAULT_SEPARATOR = SEPARATOR_OPTIONS[0].value;
+
+/**
+ * Indeterminate KDF progress. Scrypt does not expose intermediate progress,
+ * so randomized increments consume a shrinking fraction of the remaining
+ * distance. The bar moves quickly at first and can never reach completion.
+ */
+function FakeKdfProgressBar() {
+  const [progress, setProgress] = React.useState(0);
+
+  React.useEffect(() => {
+    let animationFrame = 0;
+    let nextAdvanceAt = 0;
+    const advance = (now: number) => {
+      if (now >= nextAdvanceAt) {
+        setProgress((current) => {
+          const remaining = 90 - current;
+          const fraction = 0.08 + Math.random() * 0.22;
+          return Math.min(90, current + Math.max(0.25, remaining * fraction));
+        });
+        nextAdvanceAt = now + 180 + Math.random() * 420;
+      }
+      animationFrame = window.requestAnimationFrame(advance);
+    };
+    animationFrame = window.requestAnimationFrame(advance);
+    return () => window.cancelAnimationFrame(animationFrame);
+  }, []);
+
+  return (
+    <div
+      aria-label="Encrypting your key"
+      aria-valuemax={100}
+      aria-valuemin={0}
+      aria-valuenow={Math.round(progress)}
+      className="h-2 w-full overflow-hidden rounded-full bg-muted"
+      data-testid="encrypted-backup-progress"
+      role="progressbar"
+    >
+      <div
+        className="h-full rounded-full bg-primary transition-[width] duration-300 ease-out motion-reduce:transition-none"
+        style={{ width: `${progress}%` }}
+      />
+    </div>
+  );
+}
+
+/**
+ * 1Password-style memorable-password generator popover with word-count and
+ * separator fields, anchored to a refresh icon inset in the password field
+ * (the anchor assumes a `relative` parent). The first click opens the
+ * popover and generates; further clicks on the icon re-roll while the
+ * popover stays open — only click-outside or Esc closes it. There is no
+ * candidate preview: every generation writes the passphrase straight into
+ * the parent's password field via `onGenerated`.
+ */
+function PassphraseGeneratorPopover({
+  disabled = false,
+  onRequestGenerate,
+  onGenerated,
+}: {
+  disabled?: boolean;
+  onRequestGenerate?: () => void;
+  onGenerated: (value: string) => void;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [words, setWords] = React.useState(DEFAULT_GENERATED_WORDS);
+  const [separator, setSeparator] = React.useState<string>(DEFAULT_SEPARATOR);
+  const [error, setError] = React.useState<string | null>(null);
+  const anchorRef = React.useRef<HTMLButtonElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Read via a ref so `generate` stays reference-stable even though parents
+  // pass an inline `onGenerated`. Otherwise each generated password would
+  // re-render the parent, rebuild `generate`, and re-fire the open/controls
+  // effect below — an infinite generate loop while the popover is open.
+  const onGeneratedRef = React.useRef(onGenerated);
+
+  React.useEffect(() => {
+    onGeneratedRef.current = onGenerated;
+  }, [onGenerated]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const generate = React.useCallback(async (wordCount: number, sep: string) => {
+    setError(null);
+    try {
+      const passphrase = await generateBackupPassphrase({
+        words: wordCount,
+        separator: sep,
+      });
+      if (mountedRef.current) onGeneratedRef.current(passphrase);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setError(
+        err instanceof Error ? err.message : "Failed to generate a password.",
+      );
+    }
+  }, []);
+
+  // Fill the password field on every open and whenever a control changes.
+  React.useEffect(() => {
+    if (open) void generate(words, separator);
+  }, [open, words, separator, generate]);
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      {/* Anchor (not Trigger): Radix triggers toggle on click, but repeat
+          clicks here must generate a fresh password while the popover stays
+          open. Only click-outside or Esc closes it. */}
+      <PopoverAnchor asChild>
+        <Button
+          aria-label="Generate a password"
+          className="absolute right-9 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+          data-testid="backup-passphrase-generate"
+          disabled={disabled}
+          onClick={() => {
+            // The open effect below generates the first password; later
+            // clicks re-roll with the current controls.
+            if (onRequestGenerate) {
+              onRequestGenerate();
+              return;
+            }
+            if (!open) setOpen(true);
+            else void generate(words, separator);
+          }}
+          ref={anchorRef}
+          size="icon"
+          type="button"
+          variant="ghost"
+        >
+          <RefreshCw className="h-4 w-4" aria-hidden="true" />
+        </Button>
+      </PopoverAnchor>
+      <PopoverContent
+        align="end"
+        className="w-72 space-y-3"
+        onInteractOutside={(event) => {
+          // Clicking the anchor icon is "outside" the content — keep the
+          // popover open so that click re-rolls instead of closing.
+          if (
+            event.target instanceof Node &&
+            anchorRef.current?.contains(event.target)
+          ) {
+            event.preventDefault();
+          }
+        }}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+      >
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-words"
+          >
+            Words
+          </label>
+          <div className="flex flex-1 items-center justify-end gap-3">
+            <input
+              className="h-1.5 w-full max-w-30 cursor-pointer appearance-none rounded-full bg-foreground/15 accent-primary"
+              id="backup-passphrase-words"
+              data-testid="backup-passphrase-words"
+              max={MAX_GENERATED_WORDS}
+              min={MIN_GENERATED_WORDS}
+              onChange={(event) => setWords(Number(event.target.value))}
+              type="range"
+              value={words}
+            />
+            <span className="w-6 text-right text-sm tabular-nums text-foreground">
+              {words}
+            </span>
+          </div>
+        </div>
+
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-separator"
+          >
+            Separator
+          </label>
+          <select
+            className="h-8 rounded-lg border border-border bg-background px-2 text-sm text-foreground outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+            id="backup-passphrase-separator"
+            data-testid="backup-passphrase-separator"
+            onChange={(event) => setSeparator(event.target.value)}
+            value={separator}
+          >
+            {SEPARATOR_OPTIONS.map((option) => (
+              <option key={option.label} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {error ? (
+          <p
+            className="flex items-start gap-1.5 text-xs text-destructive"
+            data-testid="backup-passphrase-generate-error"
+          >
+            <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+            {error}
+          </p>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/**
+ * Password-first encrypted key download flow for Settings. The raw private
+ * key never enters this component. Rust creates the
+ * NIP-49 payload locally, then the native save dialog produces the user-owned
+ * file.
+ *
+ * The flow is a single password input; a refresh icon inset in the field
+ * opens a 1Password-style generator popover (word count + separator).
+ * Encryption starts eagerly once the password is valid, so Download usually
+ * opens the save dialog instantly; clicking mid-encryption queues the
+ * download until the KDF finishes.
+ */
+export function EncryptedBackupCreator({
+  onOpenChange,
+  open,
+}: {
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+}) {
+  const { state, dispatch, isSaving, saveError } = useEncryptedBackup();
+  const [isRevealed, setIsRevealed] = React.useState(false);
+
+  // A queued download hides the form; mask the password before it can return
+  // in any error state.
+  React.useEffect(() => {
+    if (state.downloadPending) setIsRevealed(false);
+  }, [state.downloadPending]);
+
+  React.useEffect(() => {
+    if (state.ncryptsec) onOpenChange(false);
+  }, [onOpenChange, state.ncryptsec]);
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open={open}>
+      <DialogContent className="max-w-lg" data-testid="encrypted-backup-dialog">
+        <DialogHeader className="pr-8">
+          <DialogTitle>Create a key backup</DialogTitle>
+          <DialogDescription>
+            You can close this window while Buzz finishes the backup in the
+            background.
+          </DialogDescription>
+        </DialogHeader>
+        <div
+          className="w-full space-y-3 text-left"
+          data-testid="encrypted-backup-creator"
+        >
+          {state.downloadPending ? (
+            <FakeKdfProgressBar />
+          ) : !state.savedPassword ? (
+            <div className="relative">
+              <Input
+                aria-label="Encryption password"
+                autoComplete="new-password"
+                className="h-10 bg-background pr-19"
+                data-testid="backup-passphrase-input"
+                onChange={(event) =>
+                  dispatch({
+                    type: "set-passphrase",
+                    value: event.target.value,
+                  })
+                }
+                placeholder={`Password (min ${MIN_PASSPHRASE_LEN} characters)`}
+                type={isRevealed ? "text" : "password"}
+                value={state.passphrase}
+              />
+              <Button
+                aria-label={isRevealed ? "Hide password" : "Reveal password"}
+                className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+                data-testid="backup-passphrase-reveal-toggle"
+                onClick={() => setIsRevealed((revealed) => !revealed)}
+                size="icon"
+                type="button"
+                variant="ghost"
+              >
+                {isRevealed ? (
+                  <EyeOff className="h-4 w-4" aria-hidden="true" />
+                ) : (
+                  <Eye className="h-4 w-4" aria-hidden="true" />
+                )}
+              </Button>
+              <PassphraseGeneratorPopover
+                onGenerated={(value) => {
+                  dispatch({ type: "set-passphrase", value });
+                  // A generated password must be visible so the user can save it.
+                  setIsRevealed(true);
+                }}
+              />
+            </div>
+          ) : null}
+
+          {!state.downloadPending && !state.savedPassword ? (
+            <p className="text-xs leading-5 text-muted-foreground">
+              Keep the file private and save its password somewhere safe — Buzz
+              cannot reset it. Once ready, the backup remains available to
+              download for 5 minutes.
+            </p>
+          ) : null}
+
+          {state.createError && state.passphrase.length === 0 ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="encrypted-backup-create-error"
+            >
+              {state.createError}
+            </p>
+          ) : null}
+
+          {saveError ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="encrypted-backup-save-error"
+            >
+              {saveError}
+            </p>
+          ) : null}
+
+          {!state.downloadPending ? (
+            <div className="flex justify-end">
+              <Button
+                className="h-9 rounded-full px-6"
+                data-testid="encrypted-backup-create"
+                disabled={downloadDisabled(state) || isSaving}
+                onClick={() => dispatch({ type: "download-clicked" })}
+                type="button"
+              >
+                Backup key
+              </Button>
+            </div>
+          ) : null}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx b/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
index 2bc689e9e8..8511d26d57 100644
--- a/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
+++ b/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
@@ -6,6 +6,7 @@ import {
   useAcpRuntimesQuery,
   useInstallAcpRuntimeMutation,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import {
   getRuntimeDisplayLabel,
   RuntimeIcon,
@@ -399,13 +400,14 @@ function CatalogDetail({ entry }: { entry: AcpRuntimeCatalogEntry }) {
   const description = harnessDescription(entry.id);
   const isReady = entry.availability === "available";
   const docsUrl = entry.installInstructionsUrl.trim();
+  const installOutputLine = useInstallOutputLine(entry.id, install.isPending);
 
   function handleInstall() {
     setInstallError(null);
     install.mutate(entry.id, {
       onSuccess: (result) => {
         if (!result.success) {
-          setInstallError(getInstallErrorMessage(result.steps));
+          setInstallError(getInstallErrorMessage(result));
         }
       },
       onError: (error) => {
@@ -502,6 +504,16 @@ function CatalogDetail({ entry }: { entry: AcpRuntimeCatalogEntry }) {
           </div>
         ) : null}
 
+        {install.isPending && installOutputLine ? (
+          <p
+            aria-live="polite"
+            className="truncate rounded-lg border border-border/60 bg-muted/40 px-3 py-1.5 font-mono text-xs text-muted-foreground"
+            data-testid={`harness-catalog-install-output-${entry.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : null}
+
         {installError ? (
           <p className="whitespace-pre-line rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-1.5 text-sm text-destructive">
             {installError}
diff --git a/desktop/src/features/settings/ui/HarnessRow.tsx b/desktop/src/features/settings/ui/HarnessRow.tsx
index de6666b8c3..c0feef13cc 100644
--- a/desktop/src/features/settings/ui/HarnessRow.tsx
+++ b/desktop/src/features/settings/ui/HarnessRow.tsx
@@ -10,6 +10,7 @@ import {
   useManagedAgentsQuery,
   usePersonasQuery,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import { RuntimeIcon } from "@/features/onboarding/ui/RuntimeIcon";
 import type { AcpAuthMethod, AcpRuntimeCatalogEntry } from "@/shared/api/types";
 import { getInstallErrorMessage } from "@/shared/lib/installError";
@@ -324,6 +325,7 @@ export function HarnessRow({
   }, [resetEpoch]);
   const isInstalling = installMutation.isPending;
   const installError = installResult?.error ?? null;
+  const installOutputLine = useInstallOutputLine(runtime.id, isInstalling);
 
   const del = useDeleteCustomHarnessMutation();
   // Blast-radius data for the delete confirmation — only fetched while the
@@ -348,7 +350,7 @@ export function HarnessRow({
         } else {
           setInstallResult({
             success: false,
-            error: getInstallErrorMessage(result.steps),
+            error: getInstallErrorMessage(result),
           });
         }
       },
@@ -479,6 +481,15 @@ export function HarnessRow({
           </p>
         ) : null}
 
+        {isInstalling && installOutputLine ? (
+          <p
+            aria-live="polite"
+            className="mt-2 truncate rounded-lg border border-border/60 bg-background/60 px-3 py-1.5 font-mono text-xs text-muted-foreground"
+            data-testid={`doctor-runtime-install-output-${runtime.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : null}
         {installError ? (
           <p
             className="mt-2 whitespace-pre-line rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-1.5 text-sm text-destructive"
diff --git a/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx b/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx
new file mode 100644
index 0000000000..8eb0256a55
--- /dev/null
+++ b/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx
@@ -0,0 +1,215 @@
+import { Download, Eye, EyeOff, ShieldCheck } from "lucide-react";
+import * as React from "react";
+
+import { NsecMaskedDisplay } from "@/features/onboarding/ui/NsecMaskedDisplay";
+import {
+  BACKUP_AVAILABILITY_MS,
+  useEncryptedBackup,
+} from "@/features/settings/EncryptedBackupProvider";
+import {
+  BackupTestFlow,
+  initialBackupTestProgress,
+} from "@/features/settings/ui/BackupTestFlow";
+import { EncryptedBackupCreator } from "@/features/settings/ui/EncryptedBackupCreator";
+import { getNsec } from "@/shared/api/tauriIdentity";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+
+function BackupAvailabilityFill({
+  availableUntil,
+}: {
+  availableUntil: number;
+}) {
+  const [{ durationMs, initialWidth }] = React.useState(() => {
+    const remainingMs = Math.max(0, availableUntil - Date.now());
+    return {
+      durationMs: remainingMs,
+      initialWidth: Math.min(100, (remainingMs / BACKUP_AVAILABILITY_MS) * 100),
+    };
+  });
+  const [width, setWidth] = React.useState(initialWidth);
+
+  React.useEffect(() => {
+    const frame = window.requestAnimationFrame(() => setWidth(0));
+    return () => window.cancelAnimationFrame(frame);
+  }, []);
+
+  return (
+    <span
+      aria-hidden="true"
+      className="pointer-events-none absolute inset-y-0 left-0 bg-primary-foreground/15 transition-[width] ease-linear"
+      data-testid="encrypted-backup-availability-fill"
+      style={{
+        transitionDuration: `${durationMs}ms`,
+        width: `${width}%`,
+      }}
+    />
+  );
+}
+
+/**
+ * Collapsible private-key row with backup actions. The nsec is fetched only
+ * while expanded; encrypted backup state lives in the app-level provider.
+ */
+export function PrivateKeyBackupRow() {
+  const [isOpen, setIsOpen] = React.useState(false);
+  const [nsec, setNsec] = React.useState<string | null>(null);
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [loadError, setLoadError] = React.useState<string | null>(null);
+  const [createOpen, setCreateOpen] = React.useState(false);
+  const [testOpen, setTestOpen] = React.useState(false);
+  const [testProgress, setTestProgress] = React.useState(
+    initialBackupTestProgress,
+  );
+  const {
+    availableUntil,
+    backupAvailable,
+    downloadBackup,
+    isSaving,
+    startNewBackup,
+  } = useEncryptedBackup();
+  const fetchCancelledRef = React.useRef(false);
+
+  React.useEffect(() => {
+    return () => {
+      fetchCancelledRef.current = true;
+      setNsec(null);
+    };
+  }, []);
+
+  async function handleReveal() {
+    if (!isOpen) {
+      fetchCancelledRef.current = false;
+      setIsOpen(true);
+      setIsLoading(true);
+      setLoadError(null);
+      try {
+        const value = await getNsec();
+        if (!fetchCancelledRef.current) setNsec(value);
+      } catch (err) {
+        if (!fetchCancelledRef.current)
+          setLoadError(
+            err instanceof Error
+              ? err.message
+              : "Failed to retrieve private key.",
+          );
+      } finally {
+        if (!fetchCancelledRef.current) setIsLoading(false);
+      }
+      return;
+    }
+
+    fetchCancelledRef.current = true;
+    setNsec(null);
+    setIsOpen(false);
+  }
+
+  function handleCreateBackup() {
+    if (backupAvailable) startNewBackup();
+    setCreateOpen(true);
+  }
+
+  function handleTestOpenChange(open: boolean) {
+    setTestOpen(open);
+    if (!open) setTestProgress(initialBackupTestProgress);
+  }
+
+  return (
+    <>
+      <div className="px-4 py-3" data-testid="profile-private-key-row">
+        <div className="flex items-center justify-between gap-4">
+          <p className="text-sm font-medium">Private key</p>
+          <div className="flex shrink-0 items-center gap-2">
+            {backupAvailable ? (
+              <Button
+                className="relative overflow-hidden rounded-full"
+                data-testid="encrypted-backup-download"
+                disabled={isSaving}
+                onClick={() => void downloadBackup()}
+                type="button"
+              >
+                {availableUntil !== null ? (
+                  <BackupAvailabilityFill availableUntil={availableUntil} />
+                ) : null}
+                <span className="relative z-10">Download backup</span>
+              </Button>
+            ) : null}
+            <Button
+              aria-label={isOpen ? "Hide private key" : "Reveal private key"}
+              className="rounded-full"
+              data-testid="profile-private-key-toggle"
+              onClick={() => void handleReveal()}
+              type="button"
+              variant="secondary"
+            >
+              {isOpen ? (
+                <>
+                  <EyeOff className="h-4 w-4 shrink-0" />
+                  Hide
+                </>
+              ) : (
+                <>
+                  <Eye className="h-4 w-4 shrink-0" />
+                  Reveal
+                </>
+              )}
+            </Button>
+          </div>
+        </div>
+        {isOpen ? (
+          <div className="mt-2">
+            {isLoading ? (
+              <p className="text-sm text-muted-foreground">Loading…</p>
+            ) : loadError ? (
+              <p className="text-sm text-destructive">{loadError}</p>
+            ) : nsec ? (
+              <NsecMaskedDisplay
+                actions={[
+                  {
+                    icon: <Download aria-hidden="true" />,
+                    label: "Create backup",
+                    onSelect: handleCreateBackup,
+                    testId: "private-key-create-backup",
+                  },
+                  {
+                    icon: <ShieldCheck aria-hidden="true" />,
+                    label: "Test backup",
+                    onSelect: () => setTestOpen(true),
+                    testId: "private-key-test-backup",
+                  },
+                ]}
+                nsec={nsec}
+              />
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+      <EncryptedBackupCreator onOpenChange={setCreateOpen} open={createOpen} />
+      <Dialog onOpenChange={handleTestOpenChange} open={testOpen}>
+        <DialogContent className="max-w-lg" data-testid="backup-test-dialog">
+          <DialogHeader className="pr-8">
+            <DialogTitle>Test a key backup</DialogTitle>
+            <DialogDescription>
+              Confirm that a backup file and its password can unlock an
+              identity.
+            </DialogDescription>
+          </DialogHeader>
+          <BackupTestFlow
+            onProgressChange={setTestProgress}
+            progress={testProgress}
+          />
+          <p className="text-xs leading-5 text-muted-foreground">
+            Backups use the standard NIP-49 format, so this works for backups
+            from compatible Nostr apps too.
+          </p>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
diff --git a/desktop/src/features/settings/ui/ProfileSettingsCard.tsx b/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
index 8a1283b71c..b44abd303f 100644
--- a/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
+++ b/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
@@ -1,4 +1,4 @@
-import { Check, ChevronDown, Copy, Eye, EyeOff, Pencil } from "lucide-react";
+import { Check, ChevronDown, Copy, Pencil } from "lucide-react";
 import {
   AnimatePresence,
   LayoutGroup,
@@ -12,8 +12,6 @@ import {
   useProfileQuery,
   useUpdateProfileMutation,
 } from "@/features/profile/hooks";
-import { NsecMaskedDisplay } from "@/features/onboarding/ui/NsecMaskedDisplay";
-import { getNsec } from "@/shared/api/tauriIdentity";
 import { MaskedAvatarBadgeFrame } from "@/features/profile/ui/MaskedAvatarBadgeFrame";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
 import {
@@ -24,6 +22,7 @@ import { cn } from "@/shared/lib/cn";
 import { Input } from "@/shared/ui/input";
 import { Spinner } from "@/shared/ui/spinner";
 import { Textarea } from "@/shared/ui/textarea";
+import { PrivateKeyBackupRow } from "./PrivateKeyBackupRow";
 import { SettingsSectionHeader } from "./SettingsSectionHeader";
 import { SignOutSection } from "./SignOutSection";
 import { writeTextToClipboard } from "@/shared/lib/clipboard";
@@ -90,92 +89,6 @@ function IdentityRow({
   );
 }
 
-/**
- * Collapsible row that reveals the user's nsec on demand.
- * The nsec is fetched only when first expanded and cleared on collapse.
- */
-function NsecRevealRow() {
-  const [isOpen, setIsOpen] = React.useState(false);
-  const [nsec, setNsec] = React.useState<string | null>(null);
-  const [isLoading, setIsLoading] = React.useState(false);
-  const [loadError, setLoadError] = React.useState<string | null>(null);
-  // Guards against a late-resolving getNsec() repopulating state after Hide
-  // or after the settings panel unmounts.
-  const fetchCancelledRef = React.useRef(false);
-
-  React.useEffect(() => {
-    return () => {
-      fetchCancelledRef.current = true;
-      setNsec(null);
-    };
-  }, []);
-
-  async function handleReveal() {
-    if (!isOpen) {
-      fetchCancelledRef.current = false;
-      setIsOpen(true);
-      setIsLoading(true);
-      setLoadError(null);
-      try {
-        const value = await getNsec();
-        if (!fetchCancelledRef.current) setNsec(value);
-      } catch (err) {
-        if (!fetchCancelledRef.current)
-          setLoadError(
-            err instanceof Error
-              ? err.message
-              : "Failed to retrieve private key.",
-          );
-      } finally {
-        if (!fetchCancelledRef.current) setIsLoading(false);
-      }
-    } else {
-      // Cancel any in-flight fetch before clearing state.
-      fetchCancelledRef.current = true;
-      setNsec(null);
-      setIsOpen(false);
-    }
-  }
-
-  return (
-    <div className="px-4 py-3" data-testid="profile-private-key-row">
-      <div className="flex items-center justify-between gap-4">
-        <p className="text-sm font-medium">Private key</p>
-        <button
-          aria-label={isOpen ? "Hide private key" : "Reveal private key"}
-          className="inline-flex shrink-0 items-center gap-1.5 rounded-full bg-muted px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
-          data-testid="profile-private-key-toggle"
-          onClick={() => void handleReveal()}
-          type="button"
-        >
-          {isOpen ? (
-            <>
-              <EyeOff className="h-4 w-4 shrink-0" />
-              Hide
-            </>
-          ) : (
-            <>
-              <Eye className="h-4 w-4 shrink-0" />
-              Reveal
-            </>
-          )}
-        </button>
-      </div>
-      {isOpen ? (
-        <div className="mt-2">
-          {isLoading ? (
-            <p className="text-sm text-muted-foreground">Loading…</p>
-          ) : loadError ? (
-            <p className="text-sm text-destructive">{loadError}</p>
-          ) : nsec ? (
-            <NsecMaskedDisplay nsec={nsec} />
-          ) : null}
-        </div>
-      ) : null}
-    </div>
-  );
-}
-
 function EditProfileMetadataButton({
   label,
   testId,
@@ -883,7 +796,7 @@ export function ProfileSettingsCard({
                                 testId="profile-nip05"
                                 value={nip05Handle}
                               />
-                              <NsecRevealRow />
+                              <PrivateKeyBackupRow />
                             </div>
                           </details>
                         </div>
diff --git a/desktop/src/features/settings/ui/SettingsPanels.tsx b/desktop/src/features/settings/ui/SettingsPanels.tsx
index e74d1f3837..5c997efbc4 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 {
@@ -83,10 +84,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 +109,7 @@ export const DEFAULT_SETTINGS_SECTION: SettingsSection = "profile";
 const SETTINGS_SECTION_VALUES: readonly SettingsSection[] = [
   "profile",
   "notifications",
+  "voice",
   "experimental",
   "agents",
   "channel-templates",
@@ -167,6 +171,11 @@ export const settingsSections: SettingsSectionDescriptor[] = [
     label: "Notifications",
     icon: BellRing,
   },
+  {
+    value: "voice",
+    label: "Voice",
+    icon: Volume2,
+  },
   {
     value: "experimental",
     label: "Experiments",
@@ -807,6 +816,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..8613880571 100644
--- a/desktop/src/features/settings/ui/SettingsView.tsx
+++ b/desktop/src/features/settings/ui/SettingsView.tsx
@@ -58,6 +58,7 @@ const settingsNavGroups: Array<{
       "profile",
       "appearance",
       "notifications",
+      "voice",
       "shortcuts",
       "custom-emoji",
       "local-archive",
diff --git a/desktop/src/features/settings/ui/SignOutSection.tsx b/desktop/src/features/settings/ui/SignOutSection.tsx
index 8d4dc1c481..500875b6f0 100644
--- a/desktop/src/features/settings/ui/SignOutSection.tsx
+++ b/desktop/src/features/settings/ui/SignOutSection.tsx
@@ -31,13 +31,13 @@ export const SIGNOUT_CONFIRM_PHRASE = "wipe all my data";
  * Signing out wipes the identity key and all local data, so the confirm
  * dialog gates the delete button behind two explicit steps:
  *
- * 1. Back up the key — the nsec is shown inline (masked, with reveal/copy);
- *    the "I have saved my private key" checkbox unlocks only after the user
- *    actually reveals or copies the key.
+ * 1. Confirm recovery — Settings offers a tested password-protected backup;
+ *    the dialog also shows the raw nsec as a last-chance fallback, and the
+ *    user checks a box confirming they can restore their identity.
  * 2. Typed confirmation — the user must type the exact phrase
  *    "wipe all my data".
  *
- * Only when both gates pass does "Delete My Data" become clickable.
+ * Only when both gates pass does "Delete my data" become clickable.
  */
 export function SignOutSection() {
   const [isOpen, setIsOpen] = React.useState(false);
@@ -47,7 +47,6 @@ export function SignOutSection() {
   const [nsec, setNsec] = React.useState<string | null>(null);
   const [nsecError, setNsecError] = React.useState<string | null>(null);
   const [isNsecLoading, setIsNsecLoading] = React.useState(false);
-  const [hasInteractedWithKey, setHasInteractedWithKey] = React.useState(false);
   const [hasConfirmedBackup, setHasConfirmedBackup] = React.useState(false);
   // Guards against a late-resolving getNsec() repopulating state after the
   // dialog closes.
@@ -58,20 +57,13 @@ export function SignOutSection() {
   const isPhraseConfirmed =
     confirmText.trim().toLowerCase() === SIGNOUT_CONFIRM_PHRASE;
 
-  // The backup checkbox unlocks after real interaction with the key
-  // (reveal or copy). If the key cannot be loaded at all there is nothing to
-  // interact with — let the user proceed past the backup step rather than
-  // locking them out of sign-out entirely.
-  const isBackupGateSatisfied = hasConfirmedBackup;
-  const canConfirmBackup = hasInteractedWithKey || nsecError !== null;
-  const canDelete = isBackupGateSatisfied && isPhraseConfirmed && !isPending;
+  const canDelete = hasConfirmedBackup && isPhraseConfirmed && !isPending;
 
   function resetDialogState() {
     fetchCancelledRef.current = true;
     setNsec(null);
     setNsecError(null);
     setIsNsecLoading(false);
-    setHasInteractedWithKey(false);
     setHasConfirmedBackup(false);
     setConfirmText("");
   }
@@ -137,7 +129,8 @@ export function SignOutSection() {
           <h2 className="text-lg font-semibold tracking-tight">Sign out</h2>
           <p className="text-sm text-muted-foreground">
             Removes your identity key and all local app data from this device.
-            Back up your private key (nsec) first — this cannot be undone.
+            Before signing out, create and test a password-protected key backup
+            above — this cannot be undone.
           </p>
         </div>
         <Button
@@ -151,7 +144,7 @@ export function SignOutSection() {
           {isPending ? (
             <Spinner aria-label="Signing out" className="h-4 w-4 border-2" />
           ) : null}
-          {isPending ? "Signing out…" : "Sign Out"}
+          {isPending ? "Signing out…" : "Delete my data"}
         </Button>
       </div>
       <AlertDialog
@@ -175,7 +168,7 @@ export function SignOutSection() {
 
           <div className="space-y-3">
             <p className="text-sm font-medium">
-              1. Back up your private key (nsec)
+              1. Confirm you can restore your identity
             </p>
             {isNsecLoading ? (
               <p className="text-sm text-muted-foreground">Loading…</p>
@@ -187,10 +180,7 @@ export function SignOutSection() {
                 {nsecError}
               </p>
             ) : nsec ? (
-              <NsecMaskedDisplay
-                nsec={nsec}
-                onKeyInteraction={() => setHasInteractedWithKey(true)}
-              />
+              <NsecMaskedDisplay nsec={nsec} />
             ) : null}
             <label
               className="flex cursor-pointer items-start gap-2.5 text-sm has-[button:disabled]:cursor-not-allowed has-[button:disabled]:opacity-60"
@@ -201,19 +191,15 @@ export function SignOutSection() {
                 checked={hasConfirmedBackup}
                 className="mt-0.5"
                 data-testid="signout-backup-confirm"
-                disabled={!canConfirmBackup || isPending}
+                disabled={isPending}
                 id="signout-backup-confirm"
                 onCheckedChange={(checked) =>
                   setHasConfirmedBackup(checked === true)
                 }
               />
               <span>
-                I have saved my private key somewhere safe.
-                {!canConfirmBackup ? (
-                  <span className="block text-xs text-muted-foreground">
-                    Reveal or copy the key above first.
-                  </span>
-                ) : null}
+                I have tested a key backup or saved this private key somewhere
+                safe.
               </span>
             </label>
           </div>
@@ -257,7 +243,7 @@ export function SignOutSection() {
                   className="h-4 w-4 border-2"
                 />
               ) : null}
-              {isPending ? "Signing out…" : "Delete My Data"}
+              {isPending ? "Signing out…" : "Delete my data"}
             </Button>
           </AlertDialogFooter>
         </AlertDialogContent>
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/harnessCatalogCopy.ts b/desktop/src/features/settings/ui/harnessCatalogCopy.ts
index 79c55f0148..9a71ff70f9 100644
--- a/desktop/src/features/settings/ui/harnessCatalogCopy.ts
+++ b/desktop/src/features/settings/ui/harnessCatalogCopy.ts
@@ -36,7 +36,7 @@ const HARNESS_DESCRIPTIONS: Record<string, string> = {
   // https://moonshotai.github.io/kimi-cli/en/
   kimi: "A terminal coding agent for software development and command-line tasks.",
   // Sources: https://ampcode.com, https://ampcode.com/manual
-  amp: "A coding agent from Sourcegraph.",
+  amp: "The coding agent and development environment that runs anywhere and everywhere.",
   // Sources: https://github.com/NousResearch/hermes-agent,
   // https://hermes-agent.nousresearch.com/docs/
   hermes: "A general-purpose AI agent from Nous Research.",
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/shared/api/identityTypes.ts b/desktop/src/shared/api/identityTypes.ts
new file mode 100644
index 0000000000..9ae41d3345
--- /dev/null
+++ b/desktop/src/shared/api/identityTypes.ts
@@ -0,0 +1,28 @@
+export type IdentityStorage =
+  | "system-keyring"
+  | "local-file"
+  | "environment"
+  | "ephemeral";
+
+export type Identity = {
+  pubkey: string;
+  displayName: string;
+  /** Durable location of the active identity key. Older/mock bridges may omit
+   * this until they adopt identity storage reporting. */
+  storage?: IdentityStorage;
+  /** True when the app booted in "identity lost" recovery mode — the OS
+   * keyring was empty despite a prior successful migration. The frontend
+   * should route to nsec re-import instead of normal onboarding.
+   * Mutually exclusive with `locked`. */
+  lost?: boolean;
+  /** True when the app booted with an ephemeral key because the OS keyring
+   * holding the real identity is UNREACHABLE (e.g. GNOME Keyring / KWallet
+   * locked). The real key still exists; no in-app recovery is possible —
+   * the user must unlock the keyring externally and relaunch.
+   * Mutually exclusive with `lost`. */
+  locked?: boolean;
+  /** True when the boot-time Phase 2 reset attempted a wipe but verification
+   * failed. Identity resolution was skipped; the sentinel is preserved so
+   * the next relaunch retries the wipe automatically. */
+  resetFailed?: boolean;
+};
diff --git a/desktop/src/shared/api/installTypes.ts b/desktop/src/shared/api/installTypes.ts
new file mode 100644
index 0000000000..34d968b77d
--- /dev/null
+++ b/desktop/src/shared/api/installTypes.ts
@@ -0,0 +1,67 @@
+/**
+ * Result of an ACP runtime install, in both the shape Rust sends and the shape
+ * the UI consumes.
+ */
+
+export type RawInstallStepResult = {
+  step: string;
+  command: string;
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exit_code: number | null;
+  hint?: string;
+};
+
+export type RawInstallRuntimeResult = {
+  success: boolean;
+  steps: RawInstallStepResult[];
+  restarted_count: number;
+  failed_restart_count: number;
+  /** Absent for a run with no log file — Rust serializes `None` as null. */
+  log_path?: string | null;
+};
+
+export type InstallStepResult = {
+  step: string;
+  command: string;
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  hint?: string;
+};
+
+export type InstallRuntimeResult = {
+  success: boolean;
+  steps: InstallStepResult[];
+  restartedCount: number;
+  failedRestartCount: number;
+  /**
+   * Install log file for this run, when one was written. `steps` carries only
+   * the last attempt of each step; the log holds every attempt, each record
+   * bounded far above the display truncation. Null when no log could be
+   * written — nothing then points at a file that does not exist.
+   */
+  logPath: string | null;
+};
+
+export function fromRawInstallRuntimeResult(
+  raw: RawInstallRuntimeResult,
+): InstallRuntimeResult {
+  return {
+    success: raw.success,
+    steps: raw.steps.map((step) => ({
+      step: step.step,
+      command: step.command,
+      success: step.success,
+      stdout: step.stdout,
+      stderr: step.stderr,
+      exitCode: step.exit_code,
+      hint: step.hint,
+    })),
+    restartedCount: raw.restarted_count,
+    failedRestartCount: raw.failed_restart_count,
+    logPath: raw.log_path ?? 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/relayChannelFilters.test.mjs b/desktop/src/shared/api/relayChannelFilters.test.mjs
index 3519c82146..503f1a5d58 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,14 @@ const IDS = [
   "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
 ];
 
+test("huddle TTS filter is future-only for both message kinds", () => {
+  assert.deepEqual(buildHuddleTtsLiveFilter(CHANNEL), {
+    kinds: [9, 40002],
+    "#h": [CHANNEL],
+    limit: 0,
+  });
+});
+
 // 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..0d432d422e 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,17 @@ export function buildChannelFilter(
   return filter;
 }
 
+/** Strictly live huddle message filter: zero stored rows, future messages only. */
+export function buildHuddleTtsLiveFilter(
+  channelId: string,
+): RelaySubscriptionFilter {
+  return {
+    kinds: [KIND_STREAM_MESSAGE, KIND_STREAM_MESSAGE_V2],
+    "#h": [channelId],
+    limit: 0,
+  };
+}
+
 /**
  * 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 84ee10b68d..53d541ff0f 100644
--- a/desktop/src/shared/api/relayClientSession.ts
+++ b/desktop/src/shared/api/relayClientSession.ts
@@ -49,42 +49,30 @@ import {
   isWebSocketClose,
   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 { buildThreadReferenceTags } from "@/features/messages/lib/threading";
-const RECONNECT_BASE_DELAY_MS = 1_000,
-  RECONNECT_MAX_DELAY_MS = 30_000,
-  EVENT_BATCH_MS = 16;
-
-/**
- * Op-level timeout constants. Raised from 8 s to 25 s to survive degraded
- * networks where TLS handshakes and DNS resolution can take 3–10 s.
- */
-export const AUTH_TIMEOUT_MS = 25_000;
-export const HISTORY_TIMEOUT_MS = 25_000;
-export const PUBLISH_TIMEOUT_MS = 25_000;
-
-/**
- * The connection must remain stable for this long after a successful AUTH
- * before the reconnect backoff delay resets to its base value. Stability-
- * gated reset prevents repeated fast reconnects (flapping) from erasing the
- * backoff that throttles them.
- */
-export const BACKOFF_RESET_STABLE_MS = 60_000;
-
-/**
- * Passive liveness check. The relay sends heartbeat pings every 30s; if no
- * inbound frame arrives for two heartbeat windows, treat the socket as stalled.
- */
-const STALL_CHECK_INTERVAL_MS = 10_000;
-const STALL_IDLE_TIMEOUT_MS = 60_000;
 
 export class RelayClient {
   private wsId: number | null = null;
   private relayUrl: string | null = null;
   private connectPromise: Promise<void> | null = null;
   private reconnectTimeout: number | null = null;
+  private reconnectWaiters = new RelayReconnectWaiters();
   private reconnectDelayMs = RECONNECT_BASE_DELAY_MS;
   private keepAliveRequested = false;
   private authRequest: {
@@ -105,16 +93,6 @@ export class RelayClient {
   private stabilityTimer: number | null = null;
   private visibleChannelId: string | null = null;
 
-  /**
-   * Sticky terminal flag. Set when `resetConnection` is called with
-   * `reconnect: false` (today: auth rejection). Acts as a hard guard against
-   * the reconnect-timer / retry-wrapper paths racing back to "reconnecting"
-   * after we've already declared the session dead.
-   *
-   * Cleared only on explicit user re-engagement: `disconnect()` (community
-   * switch — the singleton is being reused for a different community) and
-   * `preconnect()` (caller is asking us to come back up).
-   */
   private terminal = false;
 
   private connectionStateEmitter = new RelayConnectionStateEmitter("idle");
@@ -127,21 +105,10 @@ export class RelayClient {
     },
   });
 
-  /**
-   * Track which channel the user is currently viewing so its subscriptions
-   * are sent first during reconnect replay — reducing visible latency on
-   * degraded networks where the relay REQ storm would otherwise delay all
-   * channels equally.
-   */
   setVisibleChannelId(id: string | null) {
     this.visibleChannelId = id;
   }
 
-  /**
-   * Cleanly tear down the connection without scheduling a reconnect.
-   * Used during community switches to reset the singleton before the
-   * new community applies.
-   */
   disconnect() {
     const error = new Error("Relay disconnected for community switch.");
 
@@ -169,6 +136,7 @@ export class RelayClient {
     }
 
     this.connectPromise = null;
+    this.reconnectWaiters.settle(error);
 
     if (this.authRequest) {
       window.clearTimeout(this.authRequest.timeout);
@@ -247,10 +215,6 @@ export class RelayClient {
     return this.fetchHistory(filter);
   }
 
-  /**
-   * Return the first event matching `filter` as soon as it arrives, without
-   * waiting for EOSE. Resolves to `null` when EOSE arrives before any event.
-   */
   async fetchFirstEvent(
     filter: RelaySubscriptionFilter,
   ): Promise<RelayEvent | null> {
@@ -462,10 +426,24 @@ 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.
+    // 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.
     this.terminal = false;
     this.keepAliveRequested = true;
-    await this.ensureConnected();
+    if (this.reconnectTimeout !== null) {
+      window.clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    try {
+      await this.ensureConnected();
+      this.reconnectWaiters.settle();
+    } catch (error) {
+      this.reconnectWaiters.settle(
+        this.normalizeRelayError(error, "Relay reconnect failed."),
+      );
+      throw error;
+    }
   }
 
   subscribeToReconnects(listener: () => void) {
@@ -508,9 +486,15 @@ export class RelayClient {
       return;
     }
 
-    if (this.reconnectTimeout) {
-      window.clearTimeout(this.reconnectTimeout);
-      this.reconnectTimeout = null;
+    if (
+      shouldWaitForScheduledReconnect({
+        hasPendingReconnect: this.reconnectTimeout !== null,
+      })
+    ) {
+      // 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();
     }
 
     const connectPromise = this.connect();
@@ -581,8 +565,8 @@ export class RelayClient {
         this.reconnectDelayMs = RECONNECT_BASE_DELAY_MS;
       }, BACKOFF_RESET_STABLE_MS);
 
-      await this.replayLiveSubscriptions();
       this.connectionStateEmitter.set("connected");
+      await this.replayLiveSubscriptions();
       this.stallWatchdog.start();
       this.emitReconnectIfNeeded();
     } catch (error) {
@@ -964,6 +948,13 @@ export class RelayClient {
     }
   }
 
+  private waitForScheduledReconnect(): Promise<void> {
+    if (this.reconnectTimeout === null) {
+      return this.ensureConnected();
+    }
+    return this.reconnectWaiters.wait();
+  }
+
   private scheduleReconnect() {
     if (
       !shouldScheduleReconnect({
@@ -989,9 +980,14 @@ export class RelayClient {
 
     this.reconnectTimeout = window.setTimeout(() => {
       this.reconnectTimeout = null;
-      void this.ensureConnected().catch(() => {
-        this.scheduleReconnect();
-      });
+      void this.ensureConnected()
+        .then(() => this.reconnectWaiters.settle())
+        .catch((error) => {
+          this.reconnectWaiters.settle(
+            this.normalizeRelayError(error, "Relay reconnect failed."),
+          );
+          this.scheduleReconnect();
+        });
     }, delay);
   }
 
@@ -1049,6 +1045,9 @@ export class RelayClient {
       window.clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
     }
+    if (options?.reconnect === false) {
+      this.reconnectWaiters.settle(error);
+    }
 
     if (this.wsId !== null) {
       void closeWebSocket(this.wsId, "connection reset");
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/relayReconnectPolicy.test.mjs b/desktop/src/shared/api/relayReconnectPolicy.test.mjs
index 6f375fb436..e6856ede18 100644
--- a/desktop/src/shared/api/relayReconnectPolicy.test.mjs
+++ b/desktop/src/shared/api/relayReconnectPolicy.test.mjs
@@ -6,6 +6,7 @@ import {
   isWebSocketClose,
   shouldRefuseConnect,
   shouldScheduleReconnect,
+  shouldWaitForScheduledReconnect,
 } from "./relayReconnectPolicy.ts";
 
 // The "happy" baseline that *should* schedule a reconnect: not terminal,
@@ -79,6 +80,17 @@ test("keep-alive alone is enough to schedule", () => {
   );
 });
 
+test("ordinary operations wait for a scheduled reconnect instead of bypassing backoff", () => {
+  assert.equal(
+    shouldWaitForScheduledReconnect({ hasPendingReconnect: true }),
+    true,
+  );
+  assert.equal(
+    shouldWaitForScheduledReconnect({ hasPendingReconnect: false }),
+    false,
+  );
+});
+
 test("shouldRefuseConnect mirrors terminal", () => {
   assert.equal(shouldRefuseConnect({ terminal: false }), false);
   assert.equal(shouldRefuseConnect({ terminal: true }), true);
diff --git a/desktop/src/shared/api/relayReconnectPolicy.ts b/desktop/src/shared/api/relayReconnectPolicy.ts
index a2cf358216..00d8e412bd 100644
--- a/desktop/src/shared/api/relayReconnectPolicy.ts
+++ b/desktop/src/shared/api/relayReconnectPolicy.ts
@@ -37,6 +37,12 @@ export function shouldScheduleReconnect(inputs: RelayReconnectInputs): boolean {
   return true;
 }
 
+export function shouldWaitForScheduledReconnect(inputs: {
+  hasPendingReconnect: boolean;
+}): boolean {
+  return inputs.hasPendingReconnect;
+}
+
 /** Whether `ensureConnected()` should refuse with a terminal error. */
 export function shouldRefuseConnect(inputs: { terminal: boolean }): boolean {
   return inputs.terminal;
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/relayReconnectWaiters.test.mjs b/desktop/src/shared/api/relayReconnectWaiters.test.mjs
new file mode 100644
index 0000000000..ddf3244526
--- /dev/null
+++ b/desktop/src/shared/api/relayReconnectWaiters.test.mjs
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { RelayReconnectWaiters } from "./relayReconnectWaiters.ts";
+
+test("settle releases every operation waiting on a successful reconnect", async () => {
+  const waiters = new RelayReconnectWaiters();
+  const first = waiters.wait();
+  const second = waiters.wait();
+
+  waiters.settle();
+
+  await Promise.all([first, second]);
+});
+
+test("settle rejects every operation after a failed reconnect", async () => {
+  const waiters = new RelayReconnectWaiters();
+  const first = waiters.wait();
+  const second = waiters.wait();
+  const error = new Error("relay unavailable");
+
+  waiters.settle(error);
+
+  await assert.rejects(first, error);
+  await assert.rejects(second, error);
+});
diff --git a/desktop/src/shared/api/relayReconnectWaiters.ts b/desktop/src/shared/api/relayReconnectWaiters.ts
new file mode 100644
index 0000000000..06ad1daa3f
--- /dev/null
+++ b/desktop/src/shared/api/relayReconnectWaiters.ts
@@ -0,0 +1,21 @@
+export class RelayReconnectWaiters {
+  private waiters = new Set<{
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }>();
+
+  wait(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.waiters.add({ resolve, reject });
+    });
+  }
+
+  settle(error?: Error) {
+    const waiters = [...this.waiters];
+    this.waiters.clear();
+    for (const waiter of waiters) {
+      if (error) waiter.reject(error);
+      else waiter.resolve();
+    }
+  }
+}
diff --git a/desktop/src/shared/api/tauri.ts b/desktop/src/shared/api/tauri.ts
index c57525480e..69e2e455ec 100644
--- a/desktop/src/shared/api/tauri.ts
+++ b/desktop/src/shared/api/tauri.ts
@@ -3,6 +3,10 @@ import {
   activateRateLimit,
   parseRateLimitHint,
 } from "@/shared/api/relayRateLimitGate";
+import {
+  fromRawInstallRuntimeResult,
+  type RawInstallRuntimeResult,
+} from "@/shared/api/installTypes";
 import type {
   AddChannelMembersInput,
   AddChannelMembersResult,
@@ -202,22 +206,10 @@ export type RawAcpRuntimeCatalogEntry = {
   definition_env?: Record<string, string>;
 };
 
-export type RawInstallStepResult = {
-  step: string;
-  command: string;
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exit_code: number | null;
-  hint?: string;
-};
-
-export type RawInstallRuntimeResult = {
-  success: boolean;
-  steps: RawInstallStepResult[];
-  restarted_count: number;
-  failed_restart_count: number;
-};
+export type {
+  RawInstallRuntimeResult,
+  RawInstallStepResult,
+} from "./installTypes";
 
 type RawGitBashPrerequisite = {
   available: boolean;
@@ -772,25 +764,6 @@ export function fromRawAcpRuntimeCatalogEntry(
   };
 }
 
-function fromRawInstallRuntimeResult(
-  raw: RawInstallRuntimeResult,
-): InstallRuntimeResult {
-  return {
-    success: raw.success,
-    steps: raw.steps.map((step) => ({
-      step: step.step,
-      command: step.command,
-      success: step.success,
-      stdout: step.stdout,
-      stderr: step.stderr,
-      exitCode: step.exit_code,
-      hint: step.hint,
-    })),
-    restartedCount: raw.restarted_count,
-    failedRestartCount: raw.failed_restart_count,
-  };
-}
-
 function fromRawCommandAvailability(
   command: RawCommandAvailability,
 ): CommandAvailability {
diff --git a/desktop/src/shared/api/tauriIdentity.ts b/desktop/src/shared/api/tauriIdentity.ts
index e6056a4a58..161f25c211 100644
--- a/desktop/src/shared/api/tauriIdentity.ts
+++ b/desktop/src/shared/api/tauriIdentity.ts
@@ -1,9 +1,10 @@
 import { invokeTauri } from "@/shared/api/tauri";
-import type { Identity } from "@/shared/api/types";
+import type { Identity, IdentityStorage } from "@/shared/api/types";
 
 type RawIdentity = {
   pubkey: string;
   display_name: string;
+  storage?: IdentityStorage;
   lost?: boolean;
   locked?: boolean;
   reset_failed?: boolean;
@@ -13,6 +14,7 @@ function fromRawIdentity(raw: RawIdentity): Identity {
   return {
     pubkey: raw.pubkey,
     displayName: raw.display_name,
+    storage: raw.storage,
     lost: raw.lost === true,
     locked: raw.locked === true,
     resetFailed: raw.reset_failed === true,
@@ -27,9 +29,12 @@ export async function getNsec(): Promise<string> {
   return invokeTauri<string>("get_nsec");
 }
 
-export async function importIdentity(nsec: string): Promise<Identity> {
+export async function importIdentity(
+  nsec: string,
+  password?: string,
+): Promise<Identity> {
   return fromRawIdentity(
-    await invokeTauri<RawIdentity>("import_identity", { nsec }),
+    await invokeTauri<RawIdentity>("import_identity", { nsec, password }),
   );
 }
 
@@ -49,3 +54,52 @@ export async function persistCurrentIdentity(): Promise<Identity> {
 export async function signOut(): Promise<void> {
   await invokeTauri("sign_out");
 }
+
+export type GeneratePassphraseOptions = {
+  /** Word count; Rust clamps to its allowed range (currently 3–10). */
+  words?: number;
+  /** Separator joined between words. Defaults to a space in Rust. */
+  separator?: string;
+};
+
+/** Generate a word passphrase (EFF short wordlist, OS entropy) in Rust. */
+export async function generateBackupPassphrase(
+  options?: GeneratePassphraseOptions,
+): Promise<string> {
+  return invokeTauri<string>("generate_backup_passphrase", {
+    words: options?.words,
+    separator: options?.separator,
+  });
+}
+
+/** Encrypt the current identity as an in-memory NIP-49 backup for native save. */
+export async function createNcryptsecBackup(password: string): Promise<string> {
+  return invokeTauri<string>("create_ncryptsec_backup", { password });
+}
+
+/** Save a portable backup copy. Returns null when the native dialog is cancelled. */
+export async function saveNcryptsecCopy(
+  ncryptsec: string,
+): Promise<string | null> {
+  return (
+    (await invokeTauri<string | null>("save_ncryptsec_copy", { ncryptsec })) ??
+    null
+  );
+}
+
+export type BackupVerification = {
+  pubkey: string;
+  npub: string;
+  matchesCurrentIdentity: boolean;
+};
+
+/** Decrypt locally and return only the backup's public identity and match state. */
+export async function verifyNcryptsecBackup(
+  ncryptsec: string,
+  password: string,
+): Promise<BackupVerification> {
+  return invokeTauri<BackupVerification>("verify_ncryptsec_backup", {
+    ncryptsec,
+    password,
+  });
+}
diff --git a/desktop/src/shared/api/tauriPersonas.ts b/desktop/src/shared/api/tauriPersonas.ts
index 66e07f5e88..36151badbc 100644
--- a/desktop/src/shared/api/tauriPersonas.ts
+++ b/desktop/src/shared/api/tauriPersonas.ts
@@ -240,6 +240,108 @@ 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:";
+
+/**
+ * Check whether an OpenAI key would resolve for a card mint of this agent
+ * (same env layering as the mint itself). Never returns the key.
+ */
+export async function cardMintKeyStatus(id: string): Promise<boolean> {
+  return invokeTauri<boolean>("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 +360,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 689c400b03..3f07e9ad9a 100644
--- a/desktop/src/shared/api/types.ts
+++ b/desktop/src/shared/api/types.ts
@@ -103,25 +103,7 @@ export type AddChannelMembersResult = {
   }>;
 };
 
-export type Identity = {
-  pubkey: string;
-  displayName: string;
-  /** True when the app booted in "identity lost" recovery mode — the OS
-   *  keyring was empty despite a prior successful migration. The frontend
-   *  should route to nsec re-import instead of normal onboarding.
-   *  Mutually exclusive with `locked`. */
-  lost?: boolean;
-  /** True when the app booted with an ephemeral key because the OS keyring
-   *  holding the real identity is UNREACHABLE (e.g. GNOME Keyring / KWallet
-   *  locked). The real key still exists; no in-app recovery is possible —
-   *  the user must unlock the keyring externally and relaunch.
-   *  Mutually exclusive with `lost`. */
-  locked?: boolean;
-  /** True when the boot-time Phase 2 reset attempted a wipe but verification
-   *  failed. Identity resolution was skipped; the sentinel is preserved so
-   *  the next relaunch retries the wipe automatically. */
-  resetFailed?: boolean;
-};
+export type { Identity, IdentityStorage } from "./identityTypes";
 
 export type Profile = {
   pubkey: string;
@@ -571,22 +553,10 @@ export type AcpRuntime = AcpRuntimeCatalogEntry & {
   binaryPath: string;
 };
 
-export type InstallStepResult = {
-  step: string;
-  command: string;
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number | null;
-  hint?: string;
-};
-
-export type InstallRuntimeResult = {
-  success: boolean;
-  steps: InstallStepResult[];
-  restartedCount: number;
-  failedRestartCount: number;
-};
+export type {
+  InstallRuntimeResult,
+  InstallStepResult,
+} from "./installTypes";
 
 export type AcpAuthMethod = {
   id: string;
diff --git a/desktop/src/shared/lib/configNudge.ts b/desktop/src/shared/lib/configNudge.ts
index 82ed8f306a..86c0e16c13 100644
--- a/desktop/src/shared/lib/configNudge.ts
+++ b/desktop/src/shared/lib/configNudge.ts
@@ -32,7 +32,7 @@ export type ConfigNudgeRequirement =
        * Determines which message and CTA the nudge card shows:
        * - "available"         → tooling installed, needs login
        * - "adapter_missing"   → CLI installed but ACP adapter missing
-       * - "adapter_outdated"  → ACP adapter present but from deprecated package; reinstall required
+       * - "adapter_outdated"  → ACP adapter present but unsupported/outdated; reinstall required
        * - "cli_missing"       → ACP adapter installed but CLI missing
        * - "not_installed"     → neither adapter nor CLI found
        */
diff --git a/desktop/src/shared/lib/installError.test.mjs b/desktop/src/shared/lib/installError.test.mjs
index c6b51186a8..181d7b802b 100644
--- a/desktop/src/shared/lib/installError.test.mjs
+++ b/desktop/src/shared/lib/installError.test.mjs
@@ -3,84 +3,108 @@ import test from "node:test";
 
 import { getInstallErrorMessage } from "./installError.ts";
 
+/** A failed install result carrying `steps` and, optionally, a log pointer. */
+function failed(steps, logPath = null) {
+  return {
+    success: false,
+    steps,
+    restartedCount: 0,
+    failedRestartCount: 0,
+    logPath,
+  };
+}
+
 test("getInstallErrorMessage: empty steps array returns fallback", () => {
-  assert.equal(getInstallErrorMessage([]), "Install failed with no output.");
+  assert.equal(
+    getInstallErrorMessage(failed([])),
+    "Install failed with no output.",
+  );
 });
 
 test("getInstallErrorMessage: failed step without hint contains step name and stderr", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /Step "adapter" failed:/);
   assert.match(message, /EACCES: permission denied/);
 });
 
 test("getInstallErrorMessage: failed step without hint does not contain hint-ish text", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.doesNotMatch(message, /npm config set prefix/);
 });
 
 test("getInstallErrorMessage: failed step with hint starts with hint and still contains stderr", () => {
   const hint =
     "Fix the npm prefix ownership:\n  sudo chown -R $USER $(npm config get prefix)";
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied, mkdir '/usr/local/lib'",
-      exitCode: 1,
-      hint,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied, mkdir '/usr/local/lib'",
+        exitCode: 1,
+        hint,
+      },
+    ]),
+  );
   assert.ok(message.startsWith(hint), "message should start with hint");
   assert.match(message, /EACCES: permission denied/);
 });
 
 test("getInstallErrorMessage: failed step with empty stderr falls back to stdout", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "node",
-      command: "node --version",
-      success: false,
-      stdout: "some stdout output",
-      stderr: "",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "node",
+        command: "node --version",
+        success: false,
+        stdout: "some stdout output",
+        stderr: "",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /some stdout output/);
 });
 
 test("getInstallErrorMessage: hint and step detail are separated by double newline for whitespace-pre-line rendering", () => {
   const hint = "Git Bash is required. Install it from git-scm.com.";
-  const message = getInstallErrorMessage([
-    {
-      step: "shell",
-      command: "bash -l -c 'npm install'",
-      success: false,
-      stdout: "",
-      stderr: "bash: command not found",
-      exitCode: 127,
-      hint,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "shell",
+        command: "bash -l -c 'npm install'",
+        success: false,
+        stdout: "",
+        stderr: "bash: command not found",
+        exitCode: 127,
+        hint,
+      },
+    ]),
+  );
   assert.ok(
     message.includes("\n\n"),
     "hint and step detail should be separated by a blank line",
@@ -89,25 +113,72 @@ test("getInstallErrorMessage: hint and step detail are separated by double newli
 });
 
 test("getInstallErrorMessage: only reports the last (failing) step when multiple steps present", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "node",
-      command: "node --version",
-      success: true,
-      stdout: "v20.0.0",
-      stderr: "",
-      exitCode: 0,
-    },
-    {
-      step: "adapter",
-      command: "npm install -g @agentclientprotocol/claude-code-acp",
-      success: false,
-      stdout: "",
-      stderr: "npm ERR! code E404",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "node",
+        command: "node --version",
+        success: true,
+        stdout: "v20.0.0",
+        stderr: "",
+        exitCode: 0,
+      },
+      {
+        step: "adapter",
+        command: "npm install -g @agentclientprotocol/claude-code-acp",
+        success: false,
+        stdout: "",
+        stderr: "npm ERR! code E404",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /Step "adapter" failed:/);
   assert.match(message, /npm ERR! code E404/);
   assert.doesNotMatch(message, /Step "node"/);
 });
+
+test("getInstallErrorMessage: points at the install log when one was written", () => {
+  const message = getInstallErrorMessage(
+    failed(
+      [
+        {
+          step: "cli",
+          command: "curl … | bash",
+          success: false,
+          stdout: "",
+          stderr: "download failed",
+          exitCode: 1,
+        },
+      ],
+      "/logs/install-goose.log",
+    ),
+  );
+  assert.match(message, /download failed/);
+  assert.ok(
+    message.endsWith("\n\nFull log: /logs/install-goose.log"),
+    `log pointer should close the message, got: ${message}`,
+  );
+});
+
+test("getInstallErrorMessage: omits the log pointer when no log was written", () => {
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "cli",
+        command: "curl … | bash",
+        success: false,
+        stdout: "",
+        stderr: "download failed",
+        exitCode: 1,
+      },
+    ]),
+  );
+  assert.doesNotMatch(message, /Full log/);
+});
+
+test("getInstallErrorMessage: a run with no steps at all still points at its log", () => {
+  const message = getInstallErrorMessage(failed([], "/logs/install-goose.log"));
+  assert.match(message, /Install failed with no output\./);
+  assert.match(message, /Full log: \/logs\/install-goose\.log/);
+});
diff --git a/desktop/src/shared/lib/installError.ts b/desktop/src/shared/lib/installError.ts
index bf72c4d3b2..82bcd4a310 100644
--- a/desktop/src/shared/lib/installError.ts
+++ b/desktop/src/shared/lib/installError.ts
@@ -1,15 +1,25 @@
-import type { InstallStepResult } from "@/shared/api/types";
+import type { InstallRuntimeResult } from "@/shared/api/types";
 
 /**
  * Build the user-visible error message for a failed install.
  * When the last step carries an actionable hint, it is shown first,
  * followed by the raw step failure detail.
+ *
+ * The step detail is truncated for display, so the message ends with a pointer
+ * to the install log — which holds every attempt of every step, each record
+ * bounded far above the display truncation — when one was written.
  */
-export function getInstallErrorMessage(steps: InstallStepResult[]): string {
+export function getInstallErrorMessage(result: InstallRuntimeResult): string {
+  const { steps, logPath } = result;
   const lastStep = steps[steps.length - 1];
   if (!lastStep) {
-    return "Install failed with no output.";
+    return withLog("Install failed with no output.", logPath);
   }
   const base = `Step "${lastStep.step}" failed: ${lastStep.stderr || lastStep.stdout || "unknown error"}`;
-  return lastStep.hint ? `${lastStep.hint}\n\n${base}` : base;
+  const detail = lastStep.hint ? `${lastStep.hint}\n\n${base}` : base;
+  return withLog(detail, logPath);
+}
+
+function withLog(message: string, logPath: string | null): string {
+  return logPath ? `${message}\n\nFull log: ${logPath}` : message;
 }
diff --git a/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs b/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs
new file mode 100644
index 0000000000..9ca8b9acf5
--- /dev/null
+++ b/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs
@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+// Structural tripwire (plan D4, defense-in-depth): NIP-49 backup material
+// handling in the webview is confined to the identity/backup/import UI and
+// its API wrappers. Anything else in `desktop/src` touching `ncryptsec` is
+// structural drift toward an unguarded egress path and must be reviewed —
+// the runtime guarantee lives in src-tauri's egress guard, this scan only
+// keeps the blob from quietly spreading through the frontend.
+//
+// Mirror of the Rust-side scan in
+// `src-tauri/src/egress_guard_tests.rs::ncryptsec_handling_is_confined_to_allowlisted_files`.
+
+const SRC_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+const ALLOWLIST = [
+  "shared/api/tauriIdentity.ts",
+  "features/onboarding/lib/encryptedBackup.ts",
+  "features/onboarding/lib/encryptedBackup.test.mjs",
+  "features/onboarding/lib/keyImportInput.ts",
+  "features/onboarding/lib/keyImportInput.test.mjs",
+  "features/onboarding/ui/BackupStep.tsx",
+  "features/onboarding/ui/BackupPasswordTimeline.tsx",
+  "features/onboarding/ui/BackupTestFlow.tsx",
+  "features/onboarding/ui/EncryptedBackupCreator.tsx",
+  "features/onboarding/ui/NostrKeyImportForm.tsx",
+  "features/onboarding/ui/NsecMaskedDisplay.tsx",
+  "features/settings/EncryptedBackupProvider.tsx",
+  "features/settings/lib/encryptedBackup.ts",
+  "features/settings/lib/encryptedBackup.test.mjs",
+  "features/settings/ui/BackupTestFlow.tsx",
+  "features/settings/ui/EncryptedBackupCreator.tsx",
+  "features/settings/ui/ProfileSettingsCard.tsx",
+  // e2e-only mock bridge (never in the production bundle):
+  "testing/e2eBridge.ts",
+  // this scan:
+  "shared/lib/ncryptsecSourceScan.test.mjs",
+];
+
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full);
+    } else if (/\.(ts|tsx|mjs|js|jsx)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+test("ncryptsec handling is confined to allowlisted frontend files", () => {
+  const violations = [];
+  for (const file of walk(SRC_ROOT)) {
+    const rel = path.relative(SRC_ROOT, file).replaceAll("\\", "/");
+    if (ALLOWLIST.includes(rel)) continue;
+    const content = fs.readFileSync(file, "utf8");
+    if (content.toLowerCase().includes("ncryptsec")) {
+      violations.push(rel);
+    }
+  }
+  assert.deepEqual(
+    violations,
+    [],
+    `NIP-49 material outside allowlisted files — wire it through the ` +
+      `identity layer (and its egress-guarded Rust commands) instead:\n` +
+      violations.join("\n"),
+  );
+});
diff --git a/desktop/src/shared/styles/globals.css b/desktop/src/shared/styles/globals.css
index fd60621933..704f6e542d 100644
--- a/desktop/src/shared/styles/globals.css
+++ b/desktop/src/shared/styles/globals.css
@@ -1,5 +1,6 @@
 @import "tailwindcss";
 @import "tw-animate-css";
+
 @import "./globals/scrollbars.css";
 @import "./globals/motion.css";
 @import "./globals/animations.css";
@@ -17,3 +18,15 @@
 @import "./globals/progress.css";
 
 @config "../../../tailwind.config.js";
+
+/* Tailwind v4 gates `hover:` behind `@media (hover: hover)`. Some Windows
+   hosts answer that query `false` even with a mouse attached — WebView2 here
+   reports `hover: none`, `any-pointer: fine: false`, `maxTouchPoints: 10` —
+   which leaves every hover-revealed control permanently `visibility: hidden`:
+   member row action menus, sidebar row actions, attachment controls. A bare
+   `&:hover` trusts the actual hover event instead of the capability query;
+   Chromium only fires :hover when a real pointer is present.
+
+   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);
diff --git a/desktop/src/shared/styles/globals/components.css b/desktop/src/shared/styles/globals/components.css
index c21e4a617d..036cf925e0 100644
--- a/desktop/src/shared/styles/globals/components.css
+++ b/desktop/src/shared/styles/globals/components.css
@@ -241,6 +241,54 @@
     --buzz-onboarding-avatar-dialog-shadow: 0 0 0;
   }
 
+  /*
+   * Backup options and password backup intentionally leave the bright
+   * onboarding world for a dark security-focused subview. Keep these semantic
+   * overrides on a reusable class as well as the shell so portaled
+   * popovers/dialogs can opt into the same treatment.
+   */
+  .buzz-onboarding-security-theme {
+    color-scheme: dark;
+    --buzz-onboarding-shell-bottom: #082b49;
+    --buzz-onboarding-cta-label: #f5f5f5;
+    --background: 222 45% 4%;
+    --foreground: 0 0% 96%;
+    --card: 220 14% 11%;
+    --card-foreground: 0 0% 96%;
+    --popover: 220 14% 9%;
+    --popover-foreground: 0 0% 96%;
+    --primary: 0 0% 16%;
+    --primary-foreground: 0 0% 96%;
+    --secondary: 0 0% 12%;
+    --secondary-foreground: 0 0% 96%;
+    --muted: 0 0% 12%;
+    --muted-foreground: 0 0% 72%;
+    --accent: 0 0% 16%;
+    --accent-foreground: 0 0% 96%;
+    --destructive: 0 84% 70%;
+    --destructive-foreground: 0 0% 4%;
+    --border: 0 0% 22%;
+    --input: 0 0% 22%;
+    --ring: 0 0% 84%;
+  }
+
+  .buzz-onboarding-neutral-theme.buzz-startup-shell.buzz-onboarding-security-theme {
+    background-color: #010103;
+    background-image:
+      radial-gradient(circle, rgb(143 211 255 / 0.11) 1px, transparent 1px),
+      radial-gradient(
+        ellipse at 50% 58%,
+        rgb(28 112 196 / 0.24) 0%,
+        rgb(18 76 138 / 0.1) 38%,
+        transparent 66%
+      ),
+      linear-gradient(to bottom, #010103 0%, #040914 46%, #082b49 100%);
+    background-size:
+      24px 24px,
+      auto,
+      auto;
+  }
+
   .buzz-onboarding-key-text {
     @apply w-full break-all [overflow-wrap:anywhere] font-mono text-nsec-key;
 
@@ -376,10 +424,13 @@
     animation-name: buzz-onboarding-line-slide-backward;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"],
   .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"] {
     overflow: visible;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"]
+    > .buzz-onboarding-transition-content,
   .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"]
     > .buzz-onboarding-transition-content {
     /* `backwards` (not `both`): the reveal ends on an identity transform, so
@@ -387,12 +438,23 @@
        that establishes a containing block and traps `position: fixed`
        descendants (the bottom-docked onboarding footer). Reverting to no
        transform at rest looks identical and frees fixed positioning. */
-    animation: buzz-onboarding-mask-reveal-up 760ms
-      cubic-bezier(0.22, 1, 0.36, 1) backwards;
+    animation-duration: 760ms;
+    animation-fill-mode: backwards;
+    animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
     animation-delay: var(--buzz-onboarding-transition-delay, 0ms);
     transform-origin: 50% 70%;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"]
+    > .buzz-onboarding-transition-content {
+    animation-name: buzz-onboarding-mask-reveal-down;
+  }
+
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"]
+    > .buzz-onboarding-transition-content {
+    animation-name: buzz-onboarding-mask-reveal-up;
+  }
+
   .buzz-onboarding-name-placeholder-caret {
     animation: buzz-onboarding-caret-blink 1.1s steps(1, end) infinite;
   }
@@ -543,6 +605,25 @@
     }
   }
 
+  @keyframes buzz-onboarding-mask-reveal-down {
+    from {
+      filter: blur(8px);
+      opacity: 0;
+      transform: translate3d(0, -30px, 0) scale(0.985);
+    }
+
+    56% {
+      filter: blur(2px);
+      opacity: 0.86;
+    }
+
+    to {
+      filter: blur(0);
+      opacity: 1;
+      transform: translate3d(0, 0, 0) scale(1);
+    }
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .buzz-onboarding-runtime-check,
     .buzz-onboarding-runtime-checkmark {
diff --git a/desktop/src/shared/styles/globals/utilities.css b/desktop/src/shared/styles/globals/utilities.css
index 1dd7326e22..a9da737bce 100644
--- a/desktop/src/shared/styles/globals/utilities.css
+++ b/desktop/src/shared/styles/globals/utilities.css
@@ -75,6 +75,15 @@
     );
   }
 
+  .buzz-huddle-drawer .buzz-huddle-control-button[aria-pressed="true"] {
+    background: hsl(var(--primary));
+    color: hsl(var(--primary-foreground));
+  }
+
+  .buzz-huddle-drawer .buzz-huddle-control-button[aria-pressed="true"]:hover {
+    background: hsl(var(--primary) / 90%);
+  }
+
   .buzz-huddle-drawer .buzz-huddle-split-chevron {
     background: hsl(var(--huddle-control-chevron-surface, var(--secondary)));
   }
diff --git a/desktop/src/shared/ui/alert-dialog.tsx b/desktop/src/shared/ui/alert-dialog.tsx
index d4bf93d4b1..97574abbe6 100644
--- a/desktop/src/shared/ui/alert-dialog.tsx
+++ b/desktop/src/shared/ui/alert-dialog.tsx
@@ -5,6 +5,11 @@ import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
 
 import { cn } from "@/shared/lib/cn";
 import { buttonVariants } from "@/shared/ui/button";
+import {
+  type CardTextureSize,
+  type CardTextureTone,
+  texturedSurfaceClasses,
+} from "@/shared/ui/card";
 import { MODAL_BACKDROP_BLUR_CLASS } from "@/shared/ui/modalBackdrop";
 import {
   MODAL_CONTENT_MOTION_CLASS,
@@ -31,25 +36,59 @@ const AlertDialogOverlay = React.forwardRef<
 ));
 AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName;
 
+type AlertDialogContentProps = React.ComponentPropsWithoutRef<
+  typeof AlertDialogPrimitive.Content
+> & {
+  surface?: "default" | "textured";
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
+};
+
 const AlertDialogContent = React.forwardRef<
   React.ElementRef<typeof AlertDialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
->(({ className, ...props }, ref) => (
-  <AlertDialogPortal>
-    <AlertDialogOverlay />
-    <div className="fixed inset-0 z-50 grid place-items-center overflow-y-auto p-4 pointer-events-none">
-      <AlertDialogPrimitive.Content
+  AlertDialogContentProps
+>(
+  (
+    {
+      className,
+      surface = "default",
+      textureSize = "regular",
+      textureTone = "light",
+      ...props
+    },
+    ref,
+  ) => (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <div
         className={cn(
-          "pointer-events-auto grid w-[calc(100vw-2rem)] max-w-md gap-4 rounded-3xl bg-background p-6 shadow-2xl outline-hidden",
-          MODAL_CONTENT_MOTION_CLASS,
-          className,
+          "pointer-events-none fixed inset-0 z-50 grid place-items-center overflow-y-auto",
+          surface === "textured"
+            ? textureSize === "compact"
+              ? "p-10"
+              : "p-28 max-sm:p-18"
+            : "p-4",
         )}
-        ref={ref}
-        {...props}
-      />
-    </div>
-  </AlertDialogPortal>
-));
+      >
+        <AlertDialogPrimitive.Content
+          className={cn(
+            "pointer-events-auto grid w-[calc(100vw-2rem)] max-w-md gap-4 outline-hidden",
+            surface === "default" && "rounded-3xl bg-background p-6 shadow-2xl",
+            surface === "textured" &&
+              texturedSurfaceClasses({
+                size: textureSize,
+                tone: textureTone,
+              }),
+            MODAL_CONTENT_MOTION_CLASS,
+            className,
+          )}
+          ref={ref}
+          {...props}
+        />
+      </div>
+    </AlertDialogPortal>
+  ),
+);
 AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName;
 
 const AlertDialogHeader = ({
diff --git a/desktop/src/shared/ui/assets/card-texture-compact.png b/desktop/src/shared/ui/assets/card-texture-compact.png
new file mode 100644
index 0000000000..5e7de51403
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-compact.png differ
diff --git a/desktop/src/shared/ui/assets/card-texture-dark-compact.png b/desktop/src/shared/ui/assets/card-texture-dark-compact.png
new file mode 100644
index 0000000000..6c26f96951
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-dark-compact.png differ
diff --git a/desktop/src/shared/ui/assets/card-texture-dark.png b/desktop/src/shared/ui/assets/card-texture-dark.png
new file mode 100644
index 0000000000..06cc574185
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-dark.png differ
diff --git a/desktop/src/shared/ui/card-texture.css b/desktop/src/shared/ui/card-texture.css
index 691d4be656..1107615452 100644
--- a/desktop/src/shared/ui/card-texture.css
+++ b/desktop/src/shared/ui/card-texture.css
@@ -7,6 +7,11 @@
  * fixed and repeats edge texture while the white center fills any card size.
  */
 .buzz-card-textured {
+  --buzz-card-textured-source: url("./assets/card-texture.png");
+  --buzz-card-textured-slice: 416;
+  --buzz-card-textured-width: 208px;
+  --buzz-card-textured-outset: 96px;
+  --buzz-card-textured-min-size: 224px;
   /*
    * The asset has three zones, from outside in:
    *   1. transparent powder bleed (outside the layout box, via outset)
@@ -31,11 +36,41 @@
    * into a smaller height with `--buzz-card-textured-min-height` when the
    * center seam is acceptable for that deliberately compressed surface.
    */
-  min-height: var(--buzz-card-textured-min-height, 224px);
-  min-width: 224px;
-  border-image-source: url("./assets/card-texture.png");
-  border-image-slice: 416 fill;
-  border-image-width: 208px;
-  border-image-outset: 96px;
+  min-height: var(
+    --buzz-card-textured-min-height,
+    var(--buzz-card-textured-min-size)
+  );
+  min-width: var(
+    --buzz-card-textured-min-width,
+    var(--buzz-card-textured-min-size)
+  );
+  border-image-source: var(--buzz-card-textured-source);
+  border-image-slice: var(--buzz-card-textured-slice) fill;
+  border-image-width: var(--buzz-card-textured-width);
+  border-image-outset: var(--buzz-card-textured-outset);
   border-image-repeat: repeat;
 }
+
+/* Dark backup surfaces use a separately baked fill so their content stays
+ * bright; applying `filter: brightness()` to the element would dim children. */
+.buzz-card-textured-dark {
+  --buzz-card-textured-source: url("./assets/card-texture-dark.png");
+}
+
+/*
+ * Popovers, confirmations, and compact callouts need the same powder edge
+ * without the full card's 96px bleed or 224px floor. This independently baked
+ * nine-slice keeps the edge legible at overlay scale.
+ */
+.buzz-card-textured-compact {
+  --buzz-card-textured-source: url("./assets/card-texture-compact.png");
+  --buzz-card-textured-slice: 136;
+  --buzz-card-textured-width: 68px;
+  --buzz-card-textured-outset: 24px;
+  --buzz-card-textured-safe-inset: 1.75rem;
+  --buzz-card-textured-min-size: 136px;
+}
+
+.buzz-card-textured-dark.buzz-card-textured-compact {
+  --buzz-card-textured-source: url("./assets/card-texture-dark-compact.png");
+}
diff --git a/desktop/src/shared/ui/card.tsx b/desktop/src/shared/ui/card.tsx
index 0bf826f866..be899fccd6 100644
--- a/desktop/src/shared/ui/card.tsx
+++ b/desktop/src/shared/ui/card.tsx
@@ -5,6 +5,26 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@/shared/lib/cn";
 import "./card-texture.css";
 
+export type CardTextureTone = "light" | "dark";
+export type CardTextureSize = "regular" | "compact";
+
+export const TEXTURED_SURFACE_CLASS =
+  "buzz-card-textured relative isolate rounded-none border-0 bg-transparent p-[var(--buzz-card-textured-safe-inset)] shadow-none";
+
+export function texturedSurfaceClasses({
+  size = "regular",
+  tone = "light",
+}: {
+  size?: CardTextureSize;
+  tone?: CardTextureTone;
+} = {}): string {
+  return cn(
+    TEXTURED_SURFACE_CLASS,
+    tone === "dark" && "buzz-card-textured-dark",
+    size === "compact" && "buzz-card-textured-compact",
+  );
+}
+
 /**
  * `variant="textured"` renders the baked nine-slice powder texture
  * (`card-texture.css`). The asset bakes the card surface INTO the image:
@@ -37,7 +57,7 @@ const cardVariants = cva("text-card-foreground", {
         // card-texture.css); when that floor stretches the card beyond its
         // content, the content stays vertically centered instead of pinning
         // to the top padding edge.
-        "buzz-card-textured relative isolate flex flex-col justify-center rounded-none border-0 p-[var(--buzz-card-textured-safe-inset)] shadow-none",
+        `${TEXTURED_SURFACE_CLASS} flex flex-col justify-center`,
     },
   },
   defaultVariants: {
@@ -49,15 +69,35 @@ export interface CardProps
   extends React.HTMLAttributes<HTMLDivElement>,
     VariantProps<typeof cardVariants> {
   asChild?: boolean;
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
 }
 
 const Card = React.forwardRef<HTMLDivElement, CardProps>(
-  ({ asChild = false, className, variant, ...props }, ref) => {
+  (
+    {
+      asChild = false,
+      className,
+      textureSize = "regular",
+      textureTone = "light",
+      variant,
+      ...props
+    },
+    ref,
+  ) => {
     const Comp = asChild ? Slot : "div";
     return (
       <Comp
         ref={ref}
-        className={cn(cardVariants({ variant, className }))}
+        className={cn(
+          cardVariants({ variant, className }),
+          variant === "textured" &&
+            textureTone === "dark" &&
+            "buzz-card-textured-dark",
+          variant === "textured" &&
+            textureSize === "compact" &&
+            "buzz-card-textured-compact",
+        )}
         {...props}
       />
     );
diff --git a/desktop/src/shared/ui/popover.tsx b/desktop/src/shared/ui/popover.tsx
index eb67c959e6..4c161efe5d 100644
--- a/desktop/src/shared/ui/popover.tsx
+++ b/desktop/src/shared/ui/popover.tsx
@@ -2,6 +2,11 @@ import * as React from "react";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 
 import { cn } from "@/shared/lib/cn";
+import {
+  type CardTextureSize,
+  type CardTextureTone,
+  texturedSurfaceClasses,
+} from "@/shared/ui/card";
 import {
   POPOVER_RADIX_MOTION_CLASS,
   POPOVER_RADIX_SIDE_MOTION_CLASS,
@@ -15,27 +20,57 @@ const PopoverTrigger = PopoverPrimitive.Trigger;
 
 const PopoverAnchor = PopoverPrimitive.Anchor;
 
+type PopoverContentProps = React.ComponentPropsWithoutRef<
+  typeof PopoverPrimitive.Content
+> & {
+  surface?: "default" | "textured";
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
+};
+
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = 4, style, ...props }, ref) => (
-  <PopoverPrimitive.Portal>
-    <PopoverPrimitive.Content
-      ref={ref}
-      align={align}
-      sideOffset={sideOffset}
-      className={cn(
-        "z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-xl p-4 outline-hidden",
-        POPOVER_RADIX_MOTION_CLASS,
-        POPOVER_RADIX_SIDE_MOTION_CLASS,
-        POPOVER_SURFACE_CLASS,
-        className,
-      )}
-      style={{ ...POPOVER_SHADOW_STYLE, ...style }}
-      {...props}
-    />
-  </PopoverPrimitive.Portal>
-));
+  PopoverContentProps
+>(
+  (
+    {
+      className,
+      align = "center",
+      sideOffset,
+      style,
+      surface = "default",
+      textureSize = "regular",
+      textureTone = "light",
+      ...props
+    },
+    ref,
+  ) => (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        ref={ref}
+        align={align}
+        sideOffset={sideOffset ?? (surface === "textured" ? 24 : 4)}
+        className={cn(
+          "z-50 w-72 origin-(--radix-popover-content-transform-origin) outline-hidden",
+          POPOVER_RADIX_MOTION_CLASS,
+          POPOVER_RADIX_SIDE_MOTION_CLASS,
+          surface === "default" && cn("rounded-xl p-4", POPOVER_SURFACE_CLASS),
+          surface === "textured" &&
+            texturedSurfaceClasses({
+              size: textureSize,
+              tone: textureTone,
+            }),
+          className,
+        )}
+        style={{
+          ...(surface === "default" ? POPOVER_SHADOW_STYLE : {}),
+          ...style,
+        }}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  ),
+);
 PopoverContent.displayName = PopoverPrimitive.Content.displayName;
 
 export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 73b564429a..355ccea9fc 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -1,6 +1,7 @@
 import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { emit, listen } from "@tauri-apps/api/event";
 import { mockIPC, mockWindows } from "@tauri-apps/api/mocks";
-import { decode } from "nostr-tools/nip19";
+import { decode, npubEncode, nsecEncode } from "nostr-tools/nip19";
 import { finalizeEvent, getPublicKey } from "nostr-tools/pure";
 import { parse as yamlParse } from "yaml";
 import {
@@ -10,6 +11,7 @@ import {
 } from "./e2eBridgeCustomHarnesses.ts";
 
 import { relayClient } from "@/shared/api/relayClient";
+import { activateRateLimit } from "@/shared/api/relayRateLimitGate";
 import type { ConnectionState } from "@/shared/api/relayClientShared";
 import type { ChannelTemplate, RelayEvent } from "@/shared/api/types";
 import { getMarkdownParseCount } from "@/shared/ui/markdown/nodeCache";
@@ -143,9 +145,29 @@ type MockSearchProfileSeed = {
   isAgent?: boolean;
 };
 
+type MockHuddleMemberSeed = {
+  pubkey: string;
+  role: "owner" | "admin" | "member" | "guest" | "bot";
+};
+
+type MockHuddleSeed = {
+  parentChannelId: string;
+  ephemeralChannelId: string;
+  members: MockHuddleMemberSeed[];
+  transcriptionEnabled?: boolean;
+  isCreator?: boolean;
+};
+
 type E2eConfig = {
   mode?: "mock" | "relay";
   mock?: {
+    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. */
@@ -203,6 +225,8 @@ type E2eConfig = {
     acpRuntimesCatalogAfterConnect?: RawAcpRuntimeCatalogEntry[];
     activePersonaIds?: string[];
     installAcpRuntimeDelayMs?: number;
+    /** Live output lines the mocked install emits before it settles. */
+    installAcpRuntimeOutputLines?: string[];
     installAcpRuntimeResult?: RawInstallRuntimeResult;
     /** Sequence of results for successive `install_acp_runtime` calls.
      *  Call N returns results[N]; when exhausted the last entry repeats.
@@ -225,6 +249,14 @@ type E2eConfig = {
       mcp?: MockCommandAvailability;
     };
     managedAgents?: MockManagedAgentSeed[];
+    /** Result returned by the mocked `add_agent_to_huddle` command. */
+    addAgentToHuddleResult?: {
+      ephemeral_added: boolean;
+      parent_added: boolean;
+      parent_error: string | null;
+    };
+    /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
+    huddleStateReadDelayMs?: number;
     /** Per agent+relay runtime rows for the pair-scoped lifecycle commands
      *  (`list/start/stop/restart_managed_agent_runtime`). */
     managedAgentRuntimes?: MockManagedAgentRuntimeSeed[];
@@ -235,6 +267,8 @@ type E2eConfig = {
     personaSharePublicationStatuses?: Array<"published" | "queued">;
     teams?: MockTeamSeed[];
     relayAgents?: MockRelayAgentSeed[];
+    /** Native-like huddle state seeded from authoritative role-bearing membership. */
+    huddle?: MockHuddleSeed;
     agentListDelayMs?: number;
     agentMemory?: RawAgentMemoryListing | Record<string, RawAgentMemoryListing>;
     addChannelMembersDelayMs?: number;
@@ -277,6 +311,8 @@ type E2eConfig = {
     channelWindowDelayMs?: number;
     profileReadDelayMs?: number;
     profileReadError?: string;
+    /** Override whether get_profile reports a real kind:0 event. */
+    profileHasEvent?: boolean;
     profileUpdateError?: string;
     profileUpdateErrors?: string[];
     searchProfiles?: MockSearchProfileSeed[];
@@ -415,6 +451,14 @@ type E2eConfig = {
      *  autosave behaviour while a request is in flight. 0/undefined = instant.
      *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
     setGlobalAgentConfigDelayMs?: number;
+    /** Errors returned by successive backup verification attempts. Null succeeds. */
+    backupVerificationErrors?: (string | null)[];
+    /** Public identities returned by successive successful backup verifications. */
+    backupVerificationPubkeys?: string[];
+    /** Delay (ms) applied to backup encryption so specs can observe pending UI. */
+    backupEncryptionDelayMs?: number;
+    /** Native paths returned by successive backup saves. */
+    backupSavePaths?: Array<string | null>;
     /**
      * When set, `get_nsec` throws with this message instead of returning the
      * mock nsec string. Use `nsecErrors` for sequenced failure/success.
@@ -1044,6 +1088,10 @@ declare global {
       command: string,
       payload?: Record<string, unknown>,
     ) => Promise<unknown>;
+    __BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__?: (input: {
+      members: MockHuddleMemberSeed[];
+      transcriptionEnabled: boolean;
+    }) => Promise<void>;
     __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: (item: RawFeedItem) => RawFeedItem;
     /** Replace an existing feed item by id (or push if not found) and fire the updated event. */
     __BUZZ_E2E_REPLACE_MOCK_FEED_ITEM__?: (
@@ -1098,6 +1146,12 @@ declare global {
     __BUZZ_E2E_SET_STALL_WEBSOCKET_SENDS__?: (stall: boolean) => void;
     __BUZZ_E2E_DISCONNECT_MOCK_WEBSOCKETS__?: () => number;
     __BUZZ_E2E_RESTART_MOCK_WEBSOCKETS__?: () => number;
+    __BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__?: (
+      unavailable: boolean,
+    ) => void;
+    __BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__?: () => number[];
+    __BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__?: (seconds: number) => void;
+    __BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__?: () => void;
     __BUZZ_E2E_SET_MESH__?: (mesh: {
       admitted?: boolean;
       models?: Array<{ id: string; name: string | null }>;
@@ -1242,6 +1296,8 @@ const REACTION_TARGET_CONTENT = "React to me with a custom emoji";
 // REACTION_TARGET_EVENT_ID.
 const SYSTEM_REACTION_TARGET_EVENT_ID = "e".repeat(64);
 const E2E_IDENTITY_OVERRIDE_STORAGE_KEY = "buzz:e2e-identity-override.v1";
+/** Stands in for `tauri.conf.json`'s version, which no mock IPC call can read. */
+const MOCK_APP_VERSION = "0.0.0-e2e";
 const DEFAULT_MOCK_IDENTITY = {
   pubkey: "deadbeef".repeat(8),
   display_name: "npub1mock...",
@@ -2810,6 +2866,8 @@ const mockReminderEvents: RelayEvent[] = [];
 const mockPersonaEvents: RelayEvent[] = [];
 let mockRelayMembers: RawRelayMember[] = [];
 const mockSockets = new Map<number, MockSocket>();
+let mockWebsocketUnavailable = false;
+const relayWebsocketConnectAttemptStarts: number[] = [];
 let mockWebsocketSendMutexWedged = false;
 let mockClosedChannelLiveSubscription = false;
 const realSockets = new Map<number, WebSocket>();
@@ -2907,8 +2965,85 @@ function resetMockMesh() {
 }
 let mockPersonas: RawPersona[] = [];
 let mockTeams: RawTeam[] = [];
-// Listeners registered via the mock __TAURI_INTERNALS__.listen — keyed by event name.
-const tauriEventListeners = new Map<string, Set<() => void>>();
+
+type MockHuddleState = {
+  phase: "active";
+  parent_channel_id: string;
+  ephemeral_channel_id: string;
+  participants: string[];
+  agent_pubkeys: string[];
+  tts_enabled: boolean;
+  transcription_enabled: boolean;
+  is_creator: boolean;
+  voice_input_mode: "voice_activity";
+};
+
+type PersistedMockHuddle = {
+  members: MockHuddleMemberSeed[];
+  state: MockHuddleState;
+};
+
+const MOCK_HUDDLE_STORAGE_KEY = "buzz.e2e.mock-huddle.v1";
+let mockHuddle: PersistedMockHuddle | null = null;
+
+function persistMockHuddle() {
+  if (mockHuddle) {
+    window.sessionStorage.setItem(
+      MOCK_HUDDLE_STORAGE_KEY,
+      JSON.stringify(mockHuddle),
+    );
+  }
+}
+
+async function emitMockHuddleState() {
+  if (!mockHuddle) return;
+  await emit("huddle-state-changed", structuredClone(mockHuddle.state));
+}
+
+function refreshMockHuddleMembership() {
+  if (!mockHuddle) return;
+  mockHuddle.state.agent_pubkeys = mockHuddle.members
+    .filter((member) => member.role === "bot")
+    .map((member) => member.pubkey);
+  mockHuddle.state.participants = mockHuddle.members.map(
+    (member) => member.pubkey,
+  );
+}
+
+function initializeMockHuddle(seed: MockHuddleSeed | undefined) {
+  mockHuddle = null;
+  if (!seed) {
+    window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
+    return;
+  }
+
+  const persisted = window.sessionStorage.getItem(MOCK_HUDDLE_STORAGE_KEY);
+  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();
+  persistMockHuddle();
+}
 const openedExternalUrls: string[] = [];
 const defaultMockRelayAgents: RawRelayAgent[] = [
   {
@@ -5378,6 +5513,13 @@ async function handleGetChannels(config: E2eConfig | undefined) {
 
 async function handleGetProfile(config: E2eConfig | undefined) {
   const identity = getIdentity(config);
+  const forcedHasProfileEvent = config?.mock?.profileHasEvent;
+  if (forcedHasProfileEvent !== undefined) {
+    return {
+      ...cloneProfile(ensureMockProfile(config)),
+      has_profile_event: forcedHasProfileEvent,
+    };
+  }
   if (!identity) {
     const profileReadDelayMs = config?.mock?.profileReadDelayMs ?? 0;
     if (profileReadDelayMs > 0) {
@@ -7195,6 +7337,24 @@ let mockGlobalAgentConfig: {
 
 // Per-page get_nsec call counter for sequenced error testing.
 let nsecCallCount = 0;
+let backupVerificationCallCount = 0;
+let backupSaveCallCount = 0;
+
+const MOCK_NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+const MOCK_BACKUP_PASSPHRASE = "mock horse battery staple lake orbit";
+const MOCK_PASSPHRASE_WORDS = [
+  "mock",
+  "horse",
+  "battery",
+  "staple",
+  "lake",
+  "orbit",
+  "cedar",
+  "plume",
+  "raven",
+  "tundra",
+];
 
 // Per-page explicit catalog publication outcomes.
 let personaSharePublicationCallCount = 0;
@@ -7202,6 +7362,53 @@ let personaSharePublicationCallCount = 0;
 // Per-page confirm_team_snapshot_import call counter for sequenced error testing.
 let teamSnapshotConfirmCallCount = 0;
 
+// Live-output sequence for the install currently being replayed. The backend
+// counter is per run (`InstallReporter::for_run` starts a fresh one), so this
+// restarts too — a bridge that stayed monotonic across installs would hide a UI
+// that carried a stale sequence number into the next run and rejected all of it.
+let installOutputSeq = 0;
+
+/**
+ * Replay the live output the Rust reporter emits while an install runs: a clear
+ * signal, then one line per entry. `seq` is install-wide and monotonic, matching
+ * the backend contract the UI's ordering depends on.
+ *
+ * The clear and the first line emit synchronously with the install invocation,
+ * exactly as the backend does — the command is invoked from the click handler,
+ * so those events land before React has committed the pending install state.
+ * Delaying them would let a listener that mounts on that state still catch them,
+ * hiding the very race the UI has to survive.
+ *
+ * Later lines are spaced so each is observable rather than collapsing into one
+ * frame with the next.
+ */
+const INSTALL_OUTPUT_REPLAY_GAP_MS = 1000;
+
+async function replayInstallOutput(
+  runtimeId: string,
+  lines: string[],
+): Promise<void> {
+  installOutputSeq = 0;
+  // The leading null is the clear signal the backend sends when an attempt
+  // starts, so this replays a whole attempt rather than only its output.
+  const events: (string | null)[] = [null, ...lines];
+  for (const [index, line] of events.entries()) {
+    // Index 0 and 1 are the clear and the first line: no gap before either.
+    if (index > 1) {
+      await new Promise((resolve) =>
+        window.setTimeout(resolve, INSTALL_OUTPUT_REPLAY_GAP_MS),
+      );
+    }
+    // `emit` reaches listeners registered through the real `listen` API, which
+    // is what the UI hook uses; mockIPC's shouldMockEvents wires the two.
+    await emit("acp-install-output", {
+      runtime_id: runtimeId,
+      seq: installOutputSeq++,
+      line,
+    });
+  }
+}
+
 async function handleInstallAcpRuntime(
   args: {
     runtimeId?: string;
@@ -7209,6 +7416,10 @@ async function handleInstallAcpRuntime(
   config: E2eConfig | undefined,
 ): Promise<RawInstallRuntimeResult> {
   const runtimeId = args.runtimeId ?? "";
+  const outputLines = config?.mock?.installAcpRuntimeOutputLines;
+  if (outputLines && outputLines.length > 0) {
+    await replayInstallOutput(runtimeId, outputLines);
+  }
   const perRuntime = config?.mock?.installAcpRuntimeByRuntime?.[runtimeId];
 
   if (perRuntime) {
@@ -7265,6 +7476,7 @@ async function handleInstallAcpRuntime(
     ],
     restarted_count: 0,
     failed_restart_count: 0,
+    log_path: null,
   };
 }
 
@@ -7443,7 +7655,7 @@ type MockUpdatePersonaInput = {
 async function handleUpdatePersona(args: {
   input: MockUpdatePersonaInput;
 }): Promise<RawPersona> {
-  return { ...applyMockPersonaUpdate(args.input) };
+  return { ...(await applyMockPersonaUpdate(args.input)) };
 }
 
 /**
@@ -7456,7 +7668,9 @@ async function handleUpdatePersona(args: {
  * make a UI that never calls `update_persona_and_publish` look like it kept
  * the "Save and publish" promise.
  */
-function applyMockPersonaUpdate(input: MockUpdatePersonaInput): RawPersona {
+async function applyMockPersonaUpdate(
+  input: MockUpdatePersonaInput,
+): Promise<RawPersona> {
   const persona = mockPersonas.find((candidate) => candidate.id === input.id);
   if (!persona) {
     throw new Error(`agent ${input.id} not found`);
@@ -7474,9 +7688,7 @@ function applyMockPersonaUpdate(input: MockUpdatePersonaInput): RawPersona {
   applyMockPersonaBehavior(persona, input.behavior);
   persona.updated_at = new Date().toISOString();
 
-  for (const callback of tauriEventListeners.get("agents-data-changed") ?? []) {
-    callback();
-  }
+  await emit("agents-data-changed");
   return persona;
 }
 
@@ -7638,7 +7850,10 @@ async function handleUpdatePersonaAndPublish(
   args: { input: MockUpdatePersonaInput },
   config?: E2eConfig,
 ): Promise<MockPersonaPublicationResult> {
-  return publishMockPersonaHead(applyMockPersonaUpdate(args.input), config);
+  return publishMockPersonaHead(
+    await applyMockPersonaUpdate(args.input),
+    config,
+  );
 }
 
 function ensureMockPersonaIsActive(personaId: string) {
@@ -8913,6 +9128,7 @@ async function resolveGetEvent(
 }
 
 async function connectRealSocket(args: { url?: string; onMessage: unknown }) {
+  relayWebsocketConnectAttemptStarts.push(Date.now());
   const wsId = nextSocketId++;
   const ws = new WebSocket(args.url ?? DEFAULT_RELAY_WS_URL);
   const handler = resolveHandler(args.onMessage);
@@ -8941,6 +9157,10 @@ async function connectRealSocket(args: { url?: string; onMessage: unknown }) {
 }
 
 async function connectMockSocket(args: { onMessage: unknown }) {
+  relayWebsocketConnectAttemptStarts.push(Date.now());
+  if (mockWebsocketUnavailable) {
+    throw new Error("mock relay unavailable");
+  }
   const connectError = getConfig()?.mock?.websocketConnectErrors?.shift();
   if (connectError) {
     throw new Error(connectError);
@@ -9386,6 +9606,8 @@ export function maybeInstallE2eTauriMocks() {
   }
 
   mockClosedChannelLiveSubscription = false;
+  mockWebsocketUnavailable = false;
+  relayWebsocketConnectAttemptStarts.length = 0;
   mockGlobalAgentConfig = config.mock?.globalAgentConfig
     ? { ...config.mock.globalAgentConfig }
     : null;
@@ -9401,6 +9623,7 @@ export function maybeInstallE2eTauriMocks() {
   resetMockPersonaCatalogEvents(config);
   resetMockSaveSubscriptions(config);
   resetMockPendingCommunityDeepLinks(config);
+  initializeMockHuddle(config.mock?.huddle);
   mockWebsocketSendMutexWedged = false;
   mockWindows("main");
   window.__BUZZ_E2E_COMMANDS__ = [];
@@ -9408,6 +9631,19 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_COMMAND_LOG__ = [];
   window.__BUZZ_E2E_SIGNED_EVENTS__ = [];
   window.__BUZZ_E2E_WEBVIEW_ZOOM__ = 1;
+  window.__BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__ = async ({
+    members,
+    transcriptionEnabled,
+  }) => {
+    if (!mockHuddle) {
+      throw new Error("No mock huddle is configured.");
+    }
+    mockHuddle.members = structuredClone(members);
+    mockHuddle.state.transcription_enabled = transcriptionEnabled;
+    refreshMockHuddleMembership();
+    persistMockHuddle();
+    await emitMockHuddleState();
+  };
   window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ = ({
     channelName,
     content,
@@ -9609,6 +9845,19 @@ export function maybeInstallE2eTauriMocks() {
     }
     return sockets.length;
   };
+  window.__BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__ = (unavailable) => {
+    mockWebsocketUnavailable = unavailable;
+    if (unavailable) relayWebsocketConnectAttemptStarts.length = 0;
+  };
+  window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__ = () => [
+    ...relayWebsocketConnectAttemptStarts,
+  ];
+  window.__BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__ = (seconds) => {
+    activateRateLimit(seconds);
+  };
+  window.__BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__ = () => {
+    relayWebsocketConnectAttemptStarts.length = 0;
+  };
   // Tests vary mesh admission and models to exercise provider discovery and
   // the managed-agent start preflight.
   window.__BUZZ_E2E_SET_MESH__ = (mesh) => {
@@ -9664,7 +9913,25 @@ export function maybeInstallE2eTauriMocks() {
     deviceId: state === "running" ? "mock-endpoint-id" : null,
     deviceName: state === "running" ? "Mock desktop" : null,
   });
-  const handleMockCommand = async (command: string, payload: unknown) => {
+  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);
@@ -9682,6 +9949,263 @@ export function maybeInstallE2eTauriMocks() {
     window.__BUZZ_E2E_COMMAND_LOG__?.push({ command, payload });
 
     switch (command) {
+      case "get_huddle_state": {
+        const snapshot = mockHuddle ? structuredClone(mockHuddle.state) : null;
+        const delayMs = activeConfig?.mock?.huddleStateReadDelayMs ?? 0;
+        if (delayMs > 0) {
+          await new Promise((resolve) => window.setTimeout(resolve, delayMs));
+        }
+        return snapshot;
+      }
+      case "get_huddle_agent_pubkeys":
+        if (!mockHuddle) return [];
+        return [...mockHuddle.state.agent_pubkeys];
+      case "set_huddle_transcription_enabled":
+        if (!mockHuddle) {
+          throw new Error("No active mock huddle.");
+        }
+        mockHuddle.state.transcription_enabled = Boolean(
+          (payload as { enabled?: boolean }).enabled,
+        );
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return null;
+      case "add_agent_to_huddle": {
+        const result = activeConfig?.mock?.addAgentToHuddleResult;
+        if (!result) {
+          throw new Error("No mock add-agent result configured.");
+        }
+        return structuredClone(result);
+      }
+      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 "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": {
@@ -9834,6 +10358,60 @@ export function maybeInstallE2eTauriMocks() {
         // harness there is nothing to wipe; resolving is enough — specs
         // assert invocation via __BUZZ_E2E_COMMANDS__ and the pending UI.
         return;
+      case "generate_backup_passphrase": {
+        const request = payload as {
+          words?: number;
+          separator?: string;
+        } | null;
+        const wordCount = Math.min(Math.max(request?.words ?? 3, 3), 10);
+        return MOCK_PASSPHRASE_WORDS.slice(0, wordCount).join(
+          request?.separator ?? " ",
+        );
+      }
+      case "create_ncryptsec_backup": {
+        const delayMs = activeConfig?.mock?.backupEncryptionDelayMs ?? 0;
+        if (delayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        return MOCK_NCRYPTSEC;
+      }
+      case "save_ncryptsec_copy": {
+        const paths = activeConfig?.mock?.backupSavePaths ?? [
+          "/tmp/buzz-identity.ncryptsec",
+        ];
+        const index = Math.min(backupSaveCallCount, paths.length - 1);
+        backupSaveCallCount += 1;
+        return paths[index];
+      }
+      case "verify_ncryptsec_backup": {
+        const request = payload as { password?: string } | null;
+        const configuredErrors = activeConfig?.mock?.backupVerificationErrors;
+        const hasConfiguredResult = Boolean(
+          activeConfig?.mock?.backupVerificationPubkeys,
+        );
+        const errors = configuredErrors ?? [
+          hasConfiguredResult || request?.password === MOCK_BACKUP_PASSPHRASE
+            ? null
+            : "wrong backup password or damaged key backup",
+        ];
+        const index = Math.min(backupVerificationCallCount, errors.length - 1);
+        const error = errors[index];
+        if (error) {
+          backupVerificationCallCount += 1;
+          throw new Error(error);
+        }
+        const pubkeys = activeConfig?.mock?.backupVerificationPubkeys ?? [
+          identity?.pubkey ?? DEFAULT_MOCK_IDENTITY.pubkey,
+        ];
+        const pubkey = pubkeys[Math.min(index, pubkeys.length - 1)];
+        backupVerificationCallCount += 1;
+        return {
+          pubkey,
+          npub: npubEncode(pubkey),
+          matchesCurrentIdentity:
+            pubkey === (identity?.pubkey ?? DEFAULT_MOCK_IDENTITY.pubkey),
+        };
+      }
       case "get_nsec": {
         const nsecSequence = activeConfig?.mock?.nsecErrors;
         if (nsecSequence && nsecSequence.length > 0) {
@@ -9866,12 +10444,26 @@ export function maybeInstallE2eTauriMocks() {
           locked: false,
         };
       }
-      case "import_identity":
+      case "import_identity": {
+        const request = payload as { nsec?: string; password?: string } | null;
+        const input = request?.nsec ?? "";
+        if (input.trim().startsWith("ncryptsec1")) {
+          if (
+            input.trim() !== MOCK_NCRYPTSEC ||
+            request?.password !== MOCK_BACKUP_PASSPHRASE
+          ) {
+            throw new Error("Wrong backup password or damaged key backup.");
+          }
+          mockIdentityLostCleared = true;
+          mockIdentityLockedCleared = true;
+          return importMockIdentity(
+            nsecEncode(hexToBytes(DEFAULT_REAL_IDENTITY.privateKey)),
+          );
+        }
         mockIdentityLostCleared = true;
         mockIdentityLockedCleared = true;
-        return importMockIdentity(
-          (payload as { nsec?: string } | null)?.nsec ?? "",
-        );
+        return importMockIdentity(input);
+      }
       case "validate_repos_dir":
         // The browser harness has no host filesystem to validate. Treat the
         // seeded empty/default path as valid so Add Community can continue to
@@ -10564,9 +11156,7 @@ export function maybeInstallE2eTauriMocks() {
           }
         }
         // Mirror the real Rust backend: emit "agents-data-changed" after reconcile.
-        for (const cb of tauriEventListeners.get("agents-data-changed") ?? []) {
-          cb();
-        }
+        await emit("agents-data-changed");
         return undefined;
       }
       case "set_persona_active":
@@ -10692,6 +11282,9 @@ export function maybeInstallE2eTauriMocks() {
           memoryEntryCount: 0,
           hasSourceAllowlist: false,
           sourceAllowlistCount: 0,
+          sourceAllowlist: [],
+          manifestJson: "{}",
+          locked: false,
         };
       }
       case "confirm_agent_snapshot_import": {
@@ -11235,10 +11828,18 @@ 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 so the mint form renders.
+        return true;
+      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":
@@ -11413,9 +12014,6 @@ export function maybeInstallE2eTauriMocks() {
       case "plugin:webview|set_webview_zoom":
         window.__BUZZ_E2E_WEBVIEW_ZOOM__ = (payload as { value: number }).value;
         return;
-      case "plugin:event|listen":
-        // Tauri event system (pairing, huddle) — no-op in e2e, return unlisten fn ID
-        return Math.floor(Math.random() * 1_000_000);
       case "start_pairing": {
         const delayMs = activeConfig?.mock?.pairingStartDelayMs ?? 0;
         if (delayMs > 0) {
@@ -11549,6 +12147,11 @@ export function maybeInstallE2eTauriMocks() {
         return null;
       case "plugin:window|is_fullscreen":
         return false;
+      // Settings reads the app version through the app plugin. Without this the
+      // bridge throws an unhandled page error on every Settings render, which
+      // shows up as noise in unrelated specs.
+      case "plugin:app|version":
+        return MOCK_APP_VERSION;
       case "merge_save_subscription_kinds": {
         // Mirrors `merge_owner_p_kinds`: union `kind` into the owner_p row's
         // kinds, creating the row if it doesn't exist yet.
@@ -11600,26 +12203,21 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__ = (command, payload) =>
     handleMockCommand(command, payload ?? null);
   mockIPC(handleMockCommand, { shouldMockEvents: true });
-
-  // Wire up __TAURI_INTERNALS__.listen so tests can subscribe to backend-emitted
-  // events (e.g. "agents-data-changed"). mockIPC already ensures __TAURI_INTERNALS__
-  // exists; we just add the listen property without clobbering invoke.
-  (
-    window as unknown as {
+  const tauriInternals = (
+    window as typeof window & {
       __TAURI_INTERNALS__: {
-        listen?: (event: string, cb: () => void) => Promise<() => void>;
+        listen?: (
+          event: string,
+          callback: () => void,
+        ) => Promise<() => Promise<void>>;
       };
     }
-  ).__TAURI_INTERNALS__.listen = async (event: string, cb: () => void) => {
-    let listeners = tauriEventListeners.get(event);
-    if (!listeners) {
-      listeners = new Set();
-      tauriEventListeners.set(event, listeners);
-    }
-    listeners.add(cb);
-    return () => {
-      tauriEventListeners.get(event)?.delete(cb);
-    };
+  ).__TAURI_INTERNALS__;
+  // Page-evaluated E2E specs use this surface; delegate to Tauri's mocked channel
+  // so their listeners observe the same events emitted by application test seams.
+  tauriInternals.listen = async (event, callback) => {
+    const unlisten = await listen(event, () => callback());
+    return async () => unlisten();
   };
 
   installed = true;
diff --git a/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts b/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
index 0fee5ebf9d..4ed0a211e5 100644
--- a/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
+++ b/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
@@ -6,6 +6,8 @@ import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
 const SHOTS = "test-results/activity-scope-label";
 
 const AGENT_PUBKEY = TEST_IDENTITIES.tyler.pubkey;
+const LONG_AGENT_NAME =
+  "Observer Agent With An Exceptionally Long Display Name";
 const AGENTS_CHANNEL_ID = "94a444a4-c0a3-5966-ab05-530c6ddc2301"; // #agents
 
 // Open the activity pane via profile → "View activity" (same ingress the
@@ -57,9 +59,36 @@ test.describe("activity panel scope label", () => {
       "channel-agents",
       "agents",
     );
-    await expect(page.getByTestId("agent-session-scope-label")).toHaveText(
-      "#agents",
+    await expect(page.getByTestId("agent-session-agent-name")).toHaveText(
+      "Observer Agent",
     );
+    await expect(page.getByTestId("agent-session-agent-avatar")).toBeVisible();
+    const scope = page.getByTestId("agent-session-scope-label");
+    await expect(scope).toHaveText("Activity · #agents");
+    const recency = page.getByTestId("agent-session-recency-label");
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+
+    // Simulate long-scope pressure deterministically: scope owns truncation
+    // while the independently shrinking recency stays visible.
+    await scope.evaluate((element) => {
+      element.style.width = "5rem";
+      element.style.flex = "none";
+    });
+    expect(
+      await scope.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(await scope.evaluate((element) => element.clientWidth));
+    await expect(recency).toBeVisible();
+
+    await page.getByTestId("agent-session-settings-menu-trigger").click();
+    await page.getByTestId("agent-session-toggle-raw-feed").click();
+    await expect(scope).toHaveText("Raw ACP activity · #agents");
+    expect(
+      await scope.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(await scope.evaluate((element) => element.clientWidth));
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+    await page.keyboard.press("Escape");
 
     await waitForAnimations(page);
     await panel.screenshot({ path: `${SHOTS}/01-channel-scoped.png` });
@@ -75,11 +104,18 @@ test.describe("activity panel scope label", () => {
       managedAgents: [
         {
           pubkey: AGENT_PUBKEY,
-          name: "Observer Agent",
+          name: LONG_AGENT_NAME,
           status: "running" as const,
           channelNames: ["random"],
         },
       ],
+      searchProfiles: [
+        {
+          pubkey: AGENT_PUBKEY,
+          displayName: LONG_AGENT_NAME,
+          isAgent: true,
+        },
+      ],
     });
 
     await page.goto(
@@ -90,9 +126,36 @@ test.describe("activity panel scope label", () => {
 
     const panel = page.getByTestId("agent-session-thread-panel");
     await expect(panel).toBeVisible({ timeout: 10_000 });
-    await expect(page.getByTestId("agent-session-scope-label")).toHaveText(
-      "All channels",
+    await expect(page.getByTestId("agent-session-agent-name")).toHaveText(
+      LONG_AGENT_NAME,
+    );
+    const agentName = page.getByTestId("agent-session-agent-name");
+    expect(
+      await agentName.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(
+      await agentName.evaluate((element) => element.clientWidth),
+    );
+    const scope = page.getByTestId("agent-session-scope-label");
+    await expect(scope).toHaveText("Activity · All channels");
+    const recency = page.getByTestId("agent-session-recency-label");
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+
+    await page.setViewportSize({ width: 720, height: 700 });
+    await expect(scope).toBeVisible();
+    await expect(recency).toBeVisible();
+    const recencyWidth = await recency.evaluate(
+      (element) => element.clientWidth,
+    );
+
+    await page.getByTestId("agent-session-settings-menu-trigger").click();
+    await page.getByTestId("agent-session-toggle-raw-feed").click();
+    await expect(scope).toHaveText("Raw ACP activity · All channels");
+    await expect(recency).toBeVisible();
+    expect(await recency.evaluate((element) => element.clientWidth)).toBe(
+      recencyWidth,
     );
+    await page.keyboard.press("Escape");
 
     await waitForAnimations(page);
     await panel.screenshot({ path: `${SHOTS}/02-all-channels.png` });
diff --git a/desktop/tests/e2e/doctor-states.spec.ts b/desktop/tests/e2e/doctor-states.spec.ts
index 77d0fbcb45..2d69a4e0da 100644
--- a/desktop/tests/e2e/doctor-states.spec.ts
+++ b/desktop/tests/e2e/doctor-states.spec.ts
@@ -983,4 +983,91 @@ test.describe("Doctor panel state screenshots", () => {
       path: `${SHOTS}/08-concurrent-installs-and-stale-clear.png`,
     });
   });
+  /**
+   * 09 — install observability: the live output line appears while the install
+   * runs and disappears when it settles, and the failure message points at the
+   * install log rather than only the truncated last step.
+   */
+  test("09-install-output-line-and-log-pointer", async ({ page }) => {
+    await installMockBridge(page, {
+      acpRuntimesCatalog: [
+        GOOSE_AVAILABLE,
+        CLAUDE_AVAILABLE_LOGGED_IN,
+        {
+          ...CODEX_NOT_INSTALLED,
+          can_auto_install: true,
+          node_required: false,
+        },
+        BUZZ_AGENT_AVAILABLE,
+      ],
+      installAcpRuntimeDelayMs: 500,
+      installAcpRuntimeOutputLines: [
+        "npm http fetch GET 200 @zed-industries/codex-acp",
+        "npm warn deprecated a transitive dependency",
+      ],
+      installAcpRuntimeResult: {
+        success: false,
+        steps: [
+          {
+            step: "adapter",
+            command: "npm install -g @zed-industries/codex-acp",
+            success: false,
+            stdout: "",
+            stderr: "npm ERR! code E404",
+            exit_code: 1,
+          },
+        ],
+        log_path: "/tmp/buzz-install-codex.log",
+      },
+    });
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "agents");
+
+    const row = page.getByTestId("doctor-runtime-codex");
+    await expect(row).toBeVisible({ timeout: 10_000 });
+
+    const installButton = page.getByTestId("doctor-runtime-install-codex");
+    await expect(installButton).toBeEnabled();
+    await installButton.click();
+
+    // The bridge emits the attempt-start clear and the first line synchronously
+    // with the install invocation — before React commits the pending state — so
+    // observing this line proves the listener was already mounted at the click.
+    // A subscription that waited for the install state would have missed both.
+    const outputLine = page.getByTestId("doctor-runtime-install-output-codex");
+    await expect(outputLine).toContainText("npm http fetch", {
+      timeout: 5_000,
+    });
+
+    // Each new line replaces the previous one rather than accumulating.
+    await expect(outputLine).toContainText("npm warn deprecated", {
+      timeout: 5_000,
+    });
+    await expect(outputLine).not.toContainText("npm http fetch");
+
+    // Settled: the line clears, so a finished install leaves no stale output
+    // under a fresh Install button.
+    const installError = page.getByTestId("doctor-runtime-install-error-codex");
+    await expect(installError).toBeVisible({ timeout: 5_000 });
+    await expect(outputLine).toHaveCount(0);
+
+    // The failure points at the log holding bounded output for every attempt.
+    await expect(installError).toContainText("npm ERR! code E404");
+    await expect(installError).toContainText("/tmp/buzz-install-codex.log");
+
+    await row.scrollIntoViewIfNeeded();
+    await waitForAnimations(page);
+    await row.screenshot({
+      path: `${SHOTS}/09-install-output-line-and-log-pointer.png`,
+    });
+
+    // A second install shows its own output. The backend sequence restarts per
+    // run, so a display that kept the previous run's sequence number would
+    // reject every event of this one and show nothing at all.
+    await installButton.click();
+    await expect(outputLine).toContainText("npm http fetch", {
+      timeout: 5_000,
+    });
+  });
 });
diff --git a/desktop/tests/e2e/empty-edit-delete.spec.ts b/desktop/tests/e2e/empty-edit-delete.spec.ts
new file mode 100644
index 0000000000..772506571b
--- /dev/null
+++ b/desktop/tests/e2e/empty-edit-delete.spec.ts
@@ -0,0 +1,120 @@
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+
+// The mock identity's own pre-seeded message in #general (authored by
+// DEFAULT_MOCK_IDENTITY.pubkey in e2eBridge.ts). Editing/deleting one's own
+// message is exactly Sam's workflow: "delete a message by clearing its edit."
+const OWN_MESSAGE_ID = "mock-general-welcome";
+const ORIGINAL_CONTENT = "Welcome to #general";
+
+// Open the more-actions menu for a message row and wait for the menu to mount.
+async function openMoreActionsMenu(
+  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({
+    timeout: 5_000,
+  });
+}
+
+// Enter edit mode for a message, clear it to empty, and submit — the gesture
+// that triggers the empty-edit delete confirmation.
+async function submitEmptyEdit(
+  page: import("@playwright/test").Page,
+  messageId: string,
+) {
+  await openMoreActionsMenu(page, messageId);
+  await page.getByTestId(`edit-message-${messageId}`).click();
+  await expect(page.getByTestId("edit-target")).toBeVisible({ timeout: 5_000 });
+  // Edit mode sets the editor content via Tiptap's async transaction pipeline;
+  // wait for it to populate before we clear it.
+  const input = page.getByTestId("message-input");
+  await expect(input).not.toBeEmpty({ timeout: 5_000 });
+  await input.click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.press("Backspace");
+  await expect(input).toBeEmpty();
+  await page.keyboard.press("Enter");
+}
+
+test.beforeEach(async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+});
+
+test("clearing an edit to empty prompts to delete, then deletes on confirm", async ({
+  page,
+}) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await submitEmptyEdit(page, OWN_MESSAGE_ID);
+
+  // 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).toContainText("Delete message?");
+  // Edit mode stays active while the dialog is open — it exits only on confirm.
+  await expect(page.getByTestId("edit-target")).toBeVisible();
+
+  // Confirm → the message row is removed and edit mode has exited.
+  await dialog.getByRole("button", { name: "Delete" }).click();
+  await expect(dialog).toBeHidden({ timeout: 5_000 });
+  await expect(page.getByTestId("edit-target")).toBeHidden();
+  await expect(row).toBeHidden({ timeout: 5_000 });
+});
+
+test("cancelling the empty-edit delete keeps the message", async ({ page }) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await submitEmptyEdit(page, OWN_MESSAGE_ID);
+
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+  // Cancel → nothing is deleted, the original message survives, and the user is
+  // left in edit mode (the editing session is preserved, not discarded).
+  await dialog.getByRole("button", { name: "Cancel" }).click();
+  await expect(dialog).toBeHidden({ timeout: 5_000 });
+  await expect(page.getByTestId("edit-target")).toBeVisible();
+  await expect(row).toBeVisible();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    ORIGINAL_CONTENT,
+  );
+});
+
+test("a non-empty edit still edits and never deletes", async ({ page }) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await openMoreActionsMenu(page, OWN_MESSAGE_ID);
+  await page.getByTestId(`edit-message-${OWN_MESSAGE_ID}`).click();
+  await expect(page.getByTestId("edit-target")).toBeVisible({ timeout: 5_000 });
+  const input = page.getByTestId("message-input");
+  await expect(input).not.toBeEmpty({ timeout: 5_000 });
+  const editedContent = `Edited, not deleted ${Date.now()}`;
+
+  await input.click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.type(editedContent);
+  await page.keyboard.press("Enter");
+
+  // 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(row).toBeVisible();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    editedContent,
+  );
+  await expect(page.getByTestId("message-timeline")).not.toContainText(
+    ORIGINAL_CONTENT,
+  );
+});
diff --git a/desktop/tests/e2e/harness-management.spec.ts b/desktop/tests/e2e/harness-management.spec.ts
index 50047f8f81..c5b441ad21 100644
--- a/desktop/tests/e2e/harness-management.spec.ts
+++ b/desktop/tests/e2e/harness-management.spec.ts
@@ -21,6 +21,7 @@
 import { expect, test } from "@playwright/test";
 
 import { installMockBridge } from "../helpers/bridge";
+import { passThroughBackupStep } from "../helpers/onboarding";
 
 // ── Shared catalog fixtures ───────────────────────────────────────────────────
 
@@ -668,12 +669,10 @@ test("onboarding setup More-harnesses click navigates to Settings → Agents", a
   });
   await page.goto("/");
 
-  // Reach the setup page: create a new identity key → skip backup step.
+  // Reach setup by creating a new identity key and continuing past the
+  // created-key page without opening the optional backup options.
   await page.getByRole("button", { name: "Create a new identity key" }).click();
-  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible({
-    timeout: 10_000,
-  });
-  await page.getByTestId("onboarding-next").click();
+  await passThroughBackupStep(page);
 
   // Now on the setup page.
   await expect(
diff --git a/desktop/tests/e2e/helpers/twoRelayHarness.ts b/desktop/tests/e2e/helpers/twoRelayHarness.ts
index 98acd86398..43eb458417 100644
--- a/desktop/tests/e2e/helpers/twoRelayHarness.ts
+++ b/desktop/tests/e2e/helpers/twoRelayHarness.ts
@@ -162,6 +162,7 @@ export class TwoRelayHarness {
       BUZZ_METRICS_PORT: String(relay.ports.metrics),
       BUZZ_REQUIRE_AUTH_TOKEN: "false",
       BUZZ_RECONCILE_CHANNELS: "true",
+      BUZZ_AUTO_MIGRATE: "true",
     });
     await this.waitForHealth(relay, child);
   }
diff --git a/desktop/tests/e2e/huddle-transcription.spec.ts b/desktop/tests/e2e/huddle-transcription.spec.ts
new file mode 100644
index 0000000000..5d9d867175
--- /dev/null
+++ b/desktop/tests/e2e/huddle-transcription.spec.ts
@@ -0,0 +1,254 @@
+import { expect, test } from "@playwright/test";
+
+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";
+
+async function setHuddleSnapshot(
+  page: import("@playwright/test").Page,
+  members: Array<{
+    pubkey: string;
+    role: "member" | "bot";
+  }>,
+  transcriptionEnabled: boolean,
+) {
+  await page.evaluate(
+    async ({ nextMembers, nextTranscriptionEnabled }) => {
+      const setSnapshot = (
+        window as Window & {
+          __BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__?: (input: {
+            members: Array<{
+              pubkey: string;
+              role: "member" | "bot";
+            }>;
+            transcriptionEnabled: boolean;
+          }) => Promise<void>;
+        }
+      ).__BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__;
+      if (!setSnapshot) {
+        throw new Error("Mock huddle snapshot control is not installed.");
+      }
+      await setSnapshot({
+        members: nextMembers,
+        transcriptionEnabled: nextTranscriptionEnabled,
+      });
+    },
+    { nextMembers: members, nextTranscriptionEnabled: transcriptionEnabled },
+  );
+}
+
+test("renders authoritative huddle snapshots and sends explicit off once", 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,
+    },
+  });
+
+  await page.goto("/");
+
+  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();
+  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,
+  );
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).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.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  const inactiveTranscriptButton = page.getByRole("button", {
+    name: "Start transcript",
+  });
+  await expect
+    .poll(() =>
+      inactiveTranscriptButton.evaluate(
+        (button) => getComputedStyle(button).backgroundColor,
+      ),
+    )
+    .not.toBe(activeBackground);
+
+  const explicitToggleCommands = await page.evaluate(() =>
+    (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+      (entry) => entry.command === "set_huddle_transcription_enabled",
+    ),
+  );
+  expect(explicitToggleCommands).toEqual([
+    {
+      command: "set_huddle_transcription_enabled",
+      payload: { enabled: false },
+    },
+  ]);
+
+  await page.reload();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (2)" }),
+  ).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "set_huddle_transcription_enabled",
+          ).length,
+      ),
+    )
+    .toBe(0);
+
+  await setHuddleSnapshot(
+    page,
+    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    false,
+  );
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+});
+
+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.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();
+});
+
+test("starts an agent DM huddle with the agent enrolled", async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("alice-tyler");
+
+  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",
+    });
+});
+
+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 Agent to Huddle" });
+  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);
+});
diff --git a/desktop/tests/e2e/invites-settings-screenshots.spec.ts b/desktop/tests/e2e/invites-settings-screenshots.spec.ts
index 56369b483d..e0856ac400 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");
 
diff --git a/desktop/tests/e2e/mentions.spec.ts b/desktop/tests/e2e/mentions.spec.ts
index 694b5abef5..5e31235a18 100644
--- a/desktop/tests/e2e/mentions.spec.ts
+++ b/desktop/tests/e2e/mentions.spec.ts
@@ -157,7 +157,7 @@ async function waitForTimelineSettled(page: import("@playwright/test").Page) {
   await expect(page.locator("[data-render-pending]")).toHaveCount(0);
 }
 
-async function expectAgentProfileMessageOnly(
+async function expectOwnedAgentProfileActions(
   profilePopover: import("@playwright/test").Locator,
   pubkey: string,
 ) {
@@ -169,7 +169,7 @@ async function expectAgentProfileMessageOnly(
   ).toHaveCount(0);
   await expect(
     profilePopover.getByTestId(`user-profile-popover-huddle-${pubkey}`),
-  ).toHaveCount(0);
+  ).toBeVisible();
 }
 
 async function expectAgentProfileActionsHidden(
@@ -1114,7 +1114,7 @@ test("system add rows use plain names while remove rows retain agent mention sty
   const addedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "portal" })
-    .filter({ hasText: "was added by" });
+    .filter({ hasText: "added by" });
   const removedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "removed portal from the channel" });
@@ -1178,7 +1178,7 @@ test("groups member additions and joins with hidden names in the standard toolti
 
   const groupedRow = page
     .getByTestId("system-message-row")
-    .filter({ hasText: "was added by Alice Chen" });
+    .filter({ hasText: "added by Alice Chen" });
   for (const visibleName of [
     "Erica Chapman",
     "Peter Griffin",
@@ -1188,9 +1188,9 @@ test("groups member additions and joins with hidden names in the standard toolti
     await expect(groupedRow).toContainText(visibleName);
   }
   await expect(
-    groupedRow.locator("p").filter({ hasText: "was added by" }),
+    groupedRow.locator("p").filter({ hasText: "added by" }),
   ).toContainText(
-    "was added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
+    "added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
   );
   await expect(groupedRow.locator("[data-mention]")).toHaveCount(0);
 
@@ -1200,6 +1200,11 @@ test("groups member additions and joins with hidden names in the standard toolti
   await expect(visibleName).toHaveCSS("text-decoration-line", "underline");
 
   const othersTrigger = groupedRow.getByRole("button", { name: "2 others" });
+  // Park the pointer off-target first: the previous hover leaves the mouse at a
+  // fixed viewport point, and any later reflow (new rows, scroll-to-bottom, a
+  // different text wrap) can slide this button under it. Without this the
+  // assertion measures where the mouse happens to be, not the resting style.
+  await page.mouse.move(0, 0);
   await expect(othersTrigger).toHaveCSS("text-decoration-line", "none");
   await othersTrigger.hover();
   await expect(othersTrigger).toHaveCSS("text-decoration-line", "underline");
@@ -1242,13 +1247,20 @@ test("groups member additions and joins with hidden names in the standard toolti
   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();
-  await expect(page.getByRole("tooltip")).toContainText("Olivia Park");
-  await expect(page.getByRole("tooltip")).toContainText("Sam Rivera");
+  // 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");
 });
 
-test("system agent profile only exposes message action", async ({ page }) => {
+test("system agent profile exposes owned agent actions", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
@@ -1277,7 +1289,7 @@ test("system agent profile only exposes message action", async ({ page }) => {
   const joinedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "mira" })
-    .filter({ hasText: "was added by" });
+    .filter({ hasText: "added by" });
   const agentName = joinedRow.getByText("mira", { exact: true });
   await expect(agentName).toHaveText("mira");
   await expect(agentName).not.toHaveAttribute("data-mention");
@@ -1287,13 +1299,13 @@ test("system agent profile only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     PROFILE_ONLY_AGENT_PUBKEY,
   );
 });
 
-test("system agent avatar only exposes message action", async ({ page }) => {
+test("system agent avatar exposes owned agent actions", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-random").click();
   await expect(page.getByTestId("chat-title")).toHaveText("random");
@@ -1328,7 +1340,7 @@ test("system agent avatar only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     PROFILE_ONLY_AGENT_PUBKEY,
   );
@@ -1907,7 +1919,9 @@ test("human profile popover does not show an owner", async ({ page }) => {
   ).toHaveCount(0);
 });
 
-test("owned bot profile only exposes message action", async ({ page }) => {
+test("owned bot profile exposes message and huddle actions", async ({
+  page,
+}) => {
   await installMockBridge(page, {
     managedAgents: [
       {
@@ -1931,13 +1945,29 @@ test("owned bot profile only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     TEST_IDENTITIES.charlie.pubkey,
   );
+
+  await profilePopover
+    .getByTestId(
+      `user-profile-popover-huddle-${TEST_IDENTITIES.charlie.pubkey}`,
+    )
+    .click();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).find(
+            (entry) => entry.command === "start_huddle",
+          )?.payload,
+      ),
+    )
+    .toMatchObject({ memberPubkeys: [TEST_IDENTITIES.charlie.pubkey] });
 });
 
-test("owned agent mention profile only exposes message action", async ({
+test("owned agent mention profile exposes message and huddle actions", async ({
   page,
 }) => {
   await installMockBridge(page, {
@@ -1970,7 +2000,7 @@ test("owned agent mention profile only exposes message action", async ({
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     TEST_IDENTITIES.charlie.pubkey,
   );
diff --git a/desktop/tests/e2e/messaging.spec.ts b/desktop/tests/e2e/messaging.spec.ts
index 2487dbbf9c..c6f5aefb9b 100644
--- a/desktop/tests/e2e/messaging.spec.ts
+++ b/desktop/tests/e2e/messaging.spec.ts
@@ -734,7 +734,9 @@ test("opens a single-level thread panel with inline expansion", async ({
         return body.scrollHeight - body.clientHeight;
       });
     })
-    .toBeGreaterThanOrEqual(160);
+    // Compact continuation rows intentionally reduce the available overflow;
+    // this test only needs enough space to prove the thread body scrolls.
+    .toBeGreaterThan(0);
 
   await expect(
     timeline.getByTestId("message-row").filter({ hasText: firstReply }),
@@ -916,10 +918,10 @@ test("opens a single-level thread panel with inline expansion", async ({
     `[data-testid="message-thread-summary"][data-thread-head-id="${firstReplyId}"]`,
   );
   await expect(firstReplySummaryRow).toHaveCount(0);
-  const firstReplyBranchRail = threadReplies.locator(
-    `[data-testid="thread-collapse-rail"][data-thread-head-id="${firstReplyId}"]`,
+  const firstReplyBranchGuide = threadReplies.locator(
+    `[data-testid="thread-collapse-guide"][data-thread-head-id="${firstReplyId}"]`,
   );
-  await expect(firstReplyBranchRail).toHaveCount(1);
+  await expect(firstReplyBranchGuide).not.toHaveCount(0);
 
   await expect(rootSummaryRow).toContainText("18 replies");
   await expect(
@@ -939,7 +941,7 @@ test("opens a single-level thread panel with inline expansion", async ({
 
   await expectThreadReplyUnobscured(nestedReplyRow);
 
-  await firstReplyBranchRail.click();
+  await firstReplyBranchGuide.first().click();
   await expect(firstReplySummaryRow).toHaveCount(1);
   await expect(firstReplySummaryRow).toContainText("2 replies");
   await expect(
diff --git a/desktop/tests/e2e/onboarding-backup.spec.ts b/desktop/tests/e2e/onboarding-backup.spec.ts
index 9b49f8bf18..df3528c8bd 100644
--- a/desktop/tests/e2e/onboarding-backup.spec.ts
+++ b/desktop/tests/e2e/onboarding-backup.spec.ts
@@ -1,6 +1,11 @@
 import { expect, test } from "@playwright/test";
 import { installMockBridge } from "../helpers/bridge";
 import { waitForAnimations } from "../helpers/animations";
+import {
+  dropFileOnTestId,
+  endWindowFileDrag,
+  startWindowFileDrag,
+} from "../helpers/fileDrag";
 
 async function enterMachineBackup(page: import("@playwright/test").Page) {
   await installMockBridge(page, undefined, {
@@ -11,70 +16,312 @@ async function enterMachineBackup(page: import("@playwright/test").Page) {
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 }
 
+async function openBackupOptions(page: import("@playwright/test").Page) {
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+}
+
+async function openPasswordBackup(page: import("@playwright/test").Page) {
+  await openBackupOptions(page);
+  await page.getByTestId("backup-option-password").click();
+  await expect(page.getByTestId("onboarding-page-download")).toBeVisible();
+}
+
+async function invokedCommands(page: import("@playwright/test").Page) {
+  return page.evaluate(
+    () =>
+      (window as Window & { __BUZZ_E2E_COMMANDS__?: string[] })
+        .__BUZZ_E2E_COMMANDS__ ?? [],
+  );
+}
+
 const SHOTS = "test-results/screenshots-onboarding";
 
+// Mirrors the mock bridge's MOCK_NCRYPTSEC (e2eBridge.ts): the blob the
+// mocked `create_ncryptsec_backup` returns, i.e. the "downloaded file"
+// contents the test-your-backup dropzone expects.
+const MOCK_NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
 test("backup step appears on fresh-key path after profile submit", async ({
   page,
 }) => {
   await enterMachineBackup(page);
 
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
+
+  // Perceived-loading intro: the animated logo and "Creating" title show
+  // first, then the finished state replaces them after the hold.
+  await expect(
+    page.getByRole("heading", { name: "Creating your identity key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-intro-logo")).toBeVisible();
+
   await expect(
     page.getByRole("heading", {
       name: "Your unique identity key has been created",
     }),
   ).toBeVisible();
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
 });
 
-test("backup step shows masked nsec from mock bridge", async ({ page }) => {
+// ---------------------------------------------------------------------------
+// Key-created view: masked key with reveal toggle. Backup options open the
+// dark security view; the raw key is fetched only on explicit reveal/copy.
+// ---------------------------------------------------------------------------
+
+test("key view reveals explicitly; options copy explicitly", async ({
+  page,
+}) => {
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
   await enterMachineBackup(page);
 
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
+
+  // Masked by default: decorative mask only, no key material in the DOM.
+  const key = page.getByTestId("backup-key-value");
+  await expect(key).toBeVisible();
+  await expect(key).toHaveClass(/blur/);
+  await expect(key).not.toContainText("nsec1");
+  expect(await invokedCommands(page)).not.toContain("get_nsec");
+
+  // Reveal fetches the key; box must not reflow (same-length monospace mask).
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(key).toContainText("nsec1mock");
+  await expect(key).toHaveClass(/select-text/);
+
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/02-backup-chooser-revealed.png` });
+
+  // Hide again.
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(key).not.toContainText("nsec1");
+
+  // Copy is available only after opening the dark backup-options view.
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await page.getByTestId("backup-copy-key").click();
+  await expect
+    .poll(async () => invokedCommands(page))
+    .toContain("copy_text_to_clipboard");
+  expect(await invokedCommands(page)).toContain("get_nsec");
+
+  // Return restores the yellow key-created view; its Next skips backup and
+  // continues directly to setup.
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  const nsecDisplay = page.getByTestId("nsec-value");
-  await expect(nsecDisplay).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+});
+
+// ---------------------------------------------------------------------------
+// Encrypted download path ("Backup your key" step): password → encrypt
+// locally → native save → saved confirmation. The raw key must never be
+// fetched on this path.
+// ---------------------------------------------------------------------------
+
+test("download happy path: generated password, encrypt, native save, Next", async ({
+  page,
+}) => {
+  await enterMachineBackup(page);
+
+  // Password backup opens from the dark options state without adding an
+  // onboarding progress step.
+  await openPasswordBackup(page);
 
-  // Should start masked (blurred) — reveal button exists and eye icon visible.
-  const revealBtn = page.getByTestId("nsec-reveal-toggle");
-  await expect(revealBtn).toBeVisible();
-  await expect(nsecDisplay).toHaveCSS("filter", /blur/);
+  // The password field starts empty; the create button sits in the footer's
+  // primary slot and stays disabled until a valid password exists.
+  const input = page.getByTestId("backup-passphrase-input");
+  await expect(input).toHaveValue("");
+  await expect(page.getByTestId("encrypted-backup-create")).toBeDisabled();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await expect(page.getByTestId("backup-return-to-onboarding")).toBeVisible();
+  const passwordPanel = page.getByTestId("backup-password-panel");
+  await expect(passwordPanel).toBeVisible();
+  await expect(passwordPanel).not.toHaveClass(/buzz-card-textured/);
+  await expect(passwordPanel).toHaveCSS("padding-left", "24px");
+
+  // The inset refresh icon opens the generator popover and immediately
+  // fills the field (mock default: 3 words, spaces).
+  await page.getByTestId("backup-passphrase-generate").click();
+  await expect(input).toHaveValue("mock horse battery");
+  const generatorPopover = page.getByRole("dialog");
+  await expect(generatorPopover).toBeVisible();
+  await expect(generatorPopover).not.toHaveClass(/buzz-card-textured/);
+
+  // Popover controls regenerate in place: word count (slider) and separator.
+  await page.getByTestId("backup-passphrase-words").focus();
+  await page.keyboard.press("ArrowRight");
+  await expect(input).toHaveValue("mock horse battery staple");
+  await page
+    .getByTestId("backup-passphrase-separator")
+    .selectOption({ label: "Hyphens" });
+  await expect(input).toHaveValue("mock-horse-battery-staple");
+
+  // Clicking the inset icon again re-rolls without closing the popover.
+  await page.getByTestId("backup-passphrase-generate").click();
+  await expect(page.getByTestId("backup-passphrase-separator")).toBeVisible();
 
-  // Take a screenshot of the masked state. Capture the whole viewport: the CTAs
-  // are portaled into the docked footer outside the step subtree.
   await waitForAnimations(page);
-  await page.screenshot({
-    path: `${SHOTS}/02-backup-step-masked.png`,
-  });
+  await page.screenshot({ path: `${SHOTS}/03-backup-download-passphrase.png` });
+
+  // Encryption may still be running when the user commits the download. The
+  // explicit click queues the native save without exposing the password or
+  // fetching the raw key.
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("backup-passphrase-separator")).toHaveCount(0);
 
-  // Reveal and verify the mock nsec appears.
-  await revealBtn.click();
-  await expect(nsecDisplay).not.toHaveCSS("filter", /blur/);
-  await expect(nsecDisplay).toContainText("nsec1mock");
+  // Saving commits the encrypted payload only after this explicit action.
+  await page.getByTestId("encrypted-backup-create").click();
+
+  // Only a successful save (the mock "picks" a path) advances to the
+  // "Optionally, test your backup" flow: a select-file button for the saved file
+  // (a composer-style drop overlay takes over the card while a file drag is
+  // over the window), then the password to unlock it.
+  await expect(
+    page.getByRole("heading", { name: "Optionally, test your backup" }),
+  ).toBeVisible();
+  const dropzone = page.getByTestId("backup-test-dropzone");
+  await expect(dropzone).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Re-download backup" }),
+  ).toBeVisible();
+
+  // The optional security subview has no onboarding Next action. Returning to
+  // the yellow key view is the single exit throughout the ceremony.
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await expect(page.getByTestId("backup-return-to-onboarding")).toBeVisible();
 
-  // Take a screenshot of the revealed state.
   await waitForAnimations(page);
-  await page.screenshot({
-    path: `${SHOTS}/03-backup-step-revealed.png`,
+  await page.screenshot({ path: `${SHOTS}/04-backup-test-dropzone.png` });
+
+  // A wrong file is rejected with an inline error; the dropzone stays.
+  await page.getByTestId("backup-test-file-input").setInputFiles({
+    name: "notes.txt",
+    mimeType: "text/plain",
+    buffer: Buffer.from("not a key backup"),
   });
+  await expect(page.getByTestId("backup-test-error")).toBeVisible();
+
+  // A file drag over the window swaps in the drop overlay; leaving without
+  // dropping restores the select button.
+  const dropOverlay = page.getByTestId("backup-test-drop-overlay");
+  await startWindowFileDrag(page);
+  await expect(dropOverlay).toBeVisible();
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/04b-backup-test-drop-overlay.png` });
+  await endWindowFileDrag(page);
+  await expect(dropOverlay).toHaveCount(0);
+
+  // Dropping the freshly downloaded file on the overlay advances to the
+  // password check.
+  await startWindowFileDrag(page);
+  await expect(dropOverlay).toBeVisible();
+  await dropFileOnTestId(page, "backup-test-drop-overlay", MOCK_NCRYPTSEC);
+  const password = page.getByTestId("backup-test-password");
+  await expect(password).toBeVisible();
+  await expect(dropOverlay).toHaveCount(0);
+
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/05-backup-test-password.png` });
+
+  // Verification is explicit and clears every submitted attempt.
+  await password.fill("mock-horse-battery-staplX");
+  await page.getByTestId("backup-test-verify").click();
+  await expect(page.getByTestId("backup-test-error")).toBeVisible();
+  await expect(password).toHaveValue("");
+
+  await password.fill("mock horse battery staple lake orbit");
+  await page.getByTestId("backup-test-verify").click();
+  await expect(page.getByTestId("backup-test-success")).toBeVisible();
+
+  // The celebration is driven by motion's rAF loop, which
+  // `waitForAnimations` (WAAPI-only) cannot observe — hold until the badge
+  // and copy have faded in before capturing.
+  await page.waitForTimeout(1200);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/06-backup-test-success.png` });
+
+  // The download path must never have fetched the raw key.
+  const commands = await invokedCommands(page);
+  expect(commands).not.toContain("get_nsec");
+  expect(commands).toContain("create_ncryptsec_backup");
+
+  // Completion remains inside the optional security subview. Return to the
+  // yellow key view, whose standard Next action continues onboarding.
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await page.getByTestId("backup-return-to-onboarding").click();
+  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
 });
 
-test("backup step Next is enabled once the key is shown", async ({ page }) => {
+test("security view returns to the yellow onboarding view", async ({
+  page,
+}) => {
   await enterMachineBackup(page);
+  await openPasswordBackup(page);
+
+  await expect(page.getByTestId("backup-passphrase-input")).toBeVisible();
+  await expect(page.getByTestId("onboarding-step-dots")).toHaveCount(0);
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
 
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await expect(page.getByTestId("backup-key-value")).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeVisible();
 });
 
-test("backup step advances to machine setup on Next click", async ({
+test("returning to onboarding resets password-backup progress", async ({
   page,
 }) => {
   await enterMachineBackup(page);
+  await openPasswordBackup(page);
 
+  const input = page.getByTestId("backup-passphrase-input");
+  await input.fill("mock-horse-battery-staple");
+  await page.getByTestId("encrypted-backup-create").click();
+  await expect(
+    page.getByRole("heading", { name: "Optionally, test your backup" }),
+  ).toBeVisible();
+
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await page.getByTestId("onboarding-next").click();
 
-  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  // Re-entering the security flow intentionally starts a fresh optional
+  // backup session so no password or completed state leaks across navigation.
+  await openPasswordBackup(page);
+  await expect(
+    page.getByRole("heading", { name: "Backup your key with a password" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-passphrase-input")).toHaveValue("");
+  await expect(page.getByTestId("encrypted-backup-create")).toBeDisabled();
+});
+
+test("typed password requires 12 characters", async ({ page }) => {
+  await enterMachineBackup(page);
+  await openPasswordBackup(page);
+
+  const create = page.getByTestId("encrypted-backup-create");
+  await expect(create).toBeDisabled(); // empty field
+
+  await page.getByTestId("backup-passphrase-input").fill("short");
+  await expect(page.getByTestId("backup-passphrase-issue")).toBeVisible();
+  await expect(create).toBeDisabled();
+
+  await page
+    .getByTestId("backup-passphrase-input")
+    .fill("a much longer passphrase");
+  await expect(page.getByTestId("backup-passphrase-issue")).toHaveCount(0);
+  await expect(create).toBeEnabled();
 });
 
 test("backup step back button returns to machine identity choice", async ({
@@ -96,10 +343,10 @@ test("backup step back button returns to machine identity choice", async ({
 });
 
 // ---------------------------------------------------------------------------
-// B4: Error path coverage
+// B4: Error path coverage (reveal/copy)
 // ---------------------------------------------------------------------------
 
-test("backup step shows error banner and retry button when get_nsec fails", async ({
+test("reveal shows inline error when get_nsec fails and Next still advances", async ({
   page,
 }) => {
   await installMockBridge(
@@ -111,20 +358,17 @@ test("backup step shows error banner and retry button when get_nsec fails", asyn
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("backup-load-error")).toBeVisible();
-  await expect(page.getByTestId("backup-retry")).toBeVisible();
-  // Next is blocked on error; Skip for now ghost is shown instead.
-  await expect(page.getByTestId("onboarding-next")).toBeDisabled();
-  await expect(page.getByTestId("backup-skip")).toBeVisible();
-
-  // Skip for now still advances to machine setup.
-  await page.getByTestId("backup-skip").click();
+  await page.getByTestId("backup-key-reveal-toggle").click();
+
+  await expect(page.getByTestId("backup-copy-error")).toBeVisible();
+  // Keychain failure does not trap the user: Next still skips backup and
+  // advances directly to setup.
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
   await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
 });
 
-test("backup step retry succeeds and shows key after initial failure", async ({
-  page,
-}) => {
+test("reveal retry succeeds after initial failure", async ({ page }) => {
   // First call fails, second succeeds (sequenced via nsecErrors).
   await installMockBridge(
     page,
@@ -134,10 +378,11 @@ test("backup step retry succeeds and shows key after initial failure", async ({
   await page.goto("/");
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 
-  await expect(page.getByTestId("backup-load-error")).toBeVisible();
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-copy-error")).toBeVisible();
 
-  // Retry — second call succeeds.
-  await page.getByTestId("backup-retry").click();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await expect(page.getByTestId("backup-load-error")).not.toBeVisible();
+  // Retry — second call succeeds and clears the error.
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-key-value")).toContainText("nsec1mock");
+  await expect(page.getByTestId("backup-copy-error")).not.toBeVisible();
 });
diff --git a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
index dbb8a92a1f..efae7c3784 100644
--- a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
+++ b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
@@ -10,6 +10,8 @@ const BLANK_TYLER_IDENTITY = {
 };
 
 const SHOT_DIR = "test-results/onboarding-docked-cta";
+const NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
 
 test.use({ viewport: { width: 1280, height: 800 } });
 
@@ -46,7 +48,21 @@ test("machine onboarding: landing, backup, setup docked CTAs", async ({
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/01b-enter-key.png` });
 
-  await page.getByRole("button", { name: "Back" }).click();
+  await page.getByTestId("nostr-import-nsec-input").fill(NCRYPTSEC);
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("restore-ncryptsec-affordance")).toBeVisible();
+  await expect(page.getByTestId("restore-unlock-icon")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/01c-restore-backup.png` });
+
+  // The first Back returns to key selection; the second leaves import.
+  await page.getByRole("button", { name: "Back", exact: true }).click();
+  await expect(importCard).toBeVisible();
+  await page.getByRole("button", { name: "Back", exact: true }).click();
   await expect(
     page.getByRole("button", { name: "Create a new identity key" }),
   ).toBeVisible();
@@ -59,12 +75,56 @@ test("machine onboarding: landing, backup, setup docked CTAs", async ({
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/02-backup.png` });
 
+  // The key stays masked behind an explicit reveal toggle.
+  await expect(page.getByTestId("backup-key-value")).toBeVisible();
+
   // Reveal the key: box must not reflow (same-length monospace mask).
-  await page.getByTestId("nsec-reveal-toggle").click();
-  await expect(page.getByTestId("nsec-value")).toHaveClass(/select-text/);
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-key-value")).toHaveClass(/select-text/);
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/02b-backup-revealed.png` });
 
+  // Backup options leave the yellow flow for the dark security view without
+  // adding a progress step or a generic Next action.
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  const optionPanels = page.getByTestId("backup-option-panel");
+  await expect(optionPanels).toHaveCount(3);
+  await expect(
+    page.getByTestId("backup-options").locator(".buzz-card-textured"),
+  ).toHaveCount(0);
+  await expect(optionPanels.first()).toHaveCSS("padding-left", "24px");
+  const titleTops = await optionPanels
+    .locator("span.text-lg")
+    .evaluateAll((titles) =>
+      titles.map((title) => title.getBoundingClientRect().top),
+    );
+  expect(Math.max(...titleTops) - Math.min(...titleTops)).toBeLessThan(1);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02c-backup-options.png` });
+
+  await page.getByTestId("backup-option-password").click();
+  await expect(page.getByTestId("onboarding-page-download")).toBeVisible();
+  const passwordPanel = page.getByTestId("backup-password-panel");
+  await expect(passwordPanel).toBeVisible();
+  await expect(passwordPanel).not.toHaveClass(/buzz-card-textured/);
+  await expect(passwordPanel).toHaveCSS("padding-left", "24px");
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02d-backup-password.png` });
+
+  await page.getByTestId("backup-passphrase-generate").click();
+  const generatorPopover = page.getByRole("dialog");
+  await expect(generatorPopover).toBeVisible();
+  await expect(generatorPopover).not.toHaveClass(/buzz-card-textured/);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02e-backup-generator.png` });
+  await page.keyboard.press("Escape");
+
+  await page.getByTestId("backup-return-to-onboarding").click();
+  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
   await page.getByTestId("onboarding-next").click();
   await expect(
     page.getByRole("heading", { name: "Set up your agent harnesses" }),
@@ -115,6 +175,39 @@ test("machine key import remains usable in a short viewport", async ({
   expect(layout.scrollWidth).toBe(layout.clientWidth);
 });
 
+test("backup options keep one-column geometry on narrow windows", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 600, height: 700 });
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+  await page.getByRole("button", { name: "Create a new identity key" }).click();
+  await expect(
+    page.getByRole("heading", {
+      name: "Your unique identity key has been created",
+    }),
+  ).toBeVisible();
+  await page.getByTestId("backup-options-link").click();
+
+  const panels = page.getByTestId("backup-option-panel");
+  await expect(panels).toHaveCount(3);
+  const geometry = await panels.evaluateAll((elements) => ({
+    clientWidth: document.documentElement.clientWidth,
+    lefts: elements.map((element) => element.getBoundingClientRect().left),
+    rights: elements.map((element) => element.getBoundingClientRect().right),
+    scrollWidth: document.documentElement.scrollWidth,
+  }));
+  expect(new Set(geometry.lefts.map(Math.round)).size).toBe(1);
+  expect(geometry.lefts.every((left) => left >= 0)).toBe(true);
+  expect(geometry.rights.every((right) => right <= geometry.clientWidth)).toBe(
+    true,
+  );
+  expect(geometry.scrollWidth).toBe(geometry.clientWidth);
+});
+
 test("relay onboarding: profile and avatar docked CTAs", async ({ page }) => {
   await seedActiveIdentity(page, BLANK_TYLER_IDENTITY);
   await installMockBridge(page, undefined, { skipOnboardingSeed: true });
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 0c4d630994..0c98cb411e 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -621,6 +621,131 @@ test("first-launch key import continues to machine setup", async ({ page }) => {
   await expect(page.getByTestId("app-loading-gate")).toHaveCount(0);
 });
 
+test("first-launch encrypted backup import asks for a passphrase and continues", async ({
+  page,
+}) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Use an existing key" }).click();
+  // Spec-vector blob the mock bridge accepts with the mock passphrase.
+  const mockNcryptsec =
+    "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+  await page
+    .getByTestId("nostr-import-nsec-input")
+    .fill(mockNcryptsec.slice(0, -1));
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toHaveCount(0);
+
+  await page
+    .getByTestId("nostr-import-nsec-input")
+    .pressSequentially(mockNcryptsec.slice(-1));
+
+  // A complete, checksummed NIP-49 value advances immediately without
+  // submitting. The password stage updates its copy, illustration, and focus.
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("restore-ncryptsec-affordance")).toBeVisible();
+  await expect(page.getByTestId("restore-unlock-icon")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toHaveCount(0);
+  await expect(page.getByTestId("nostr-import-file-button")).toHaveCount(0);
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+  await expect(page.getByTestId("nostr-import-submit")).toBeDisabled();
+
+  // Wrong passphrase surfaces the decrypt error and stays on the form.
+  await page.getByTestId("nostr-import-passphrase").fill("wrong passphrase");
+  await page.getByTestId("nostr-import-submit").click();
+  await expect(page.getByTestId("nostr-import-feedback")).toContainText(
+    /wrong backup password/i,
+  );
+
+  await page
+    .getByTestId("nostr-import-passphrase")
+    .fill("mock horse battery staple lake orbit");
+  await page.getByTestId("nostr-import-submit").click();
+
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
+});
+
+test("first-launch import accepts an .ncryptsec backup file", async ({
+  page,
+}) => {
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Use an existing key" }).click();
+
+  // The spotlight variant must expose a file path: a wiped user returns with
+  // exactly the identity.ncryptsec our own save dialog produced. The accept
+  // attribute is asserted explicitly because setInputFiles bypasses it — the
+  // OS picker is what filters on it in real use.
+  await expect(page.getByTestId("nostr-import-file-button")).toBeVisible();
+  const fileInput = page.getByTestId("nostr-import-file-input");
+  await expect(fileInput).toHaveAttribute(
+    "accept",
+    ".key,.ncryptsec,text/plain",
+  );
+
+  await fileInput.setInputFiles({
+    buffer: Buffer.alloc(1_025, "x"),
+    mimeType: "text/plain",
+    name: "not-a-backup.txt",
+  });
+  await expect(page.getByTestId("nostr-import-feedback")).toContainText(
+    /too large to be a key backup/i,
+  );
+
+  // Spec-vector blob the mock bridge accepts with the mock passphrase.
+  const mockNcryptsec =
+    "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+  await fileInput.setInputFiles({
+    buffer: Buffer.from(`${mockNcryptsec}\n`),
+    mimeType: "text/plain",
+    name: "identity.ncryptsec",
+  });
+
+  // File contents advance to the same focused password stage as manual input.
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+
+  // Back first returns to key/file selection instead of leaving import.
+  await page.getByRole("button", { name: "Back", exact: true }).click();
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-file-button")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-nsec-input")).toHaveValue("");
+
+  await fileInput.setInputFiles({
+    buffer: Buffer.from(`${mockNcryptsec}\n`),
+    mimeType: "text/plain",
+    name: "identity.ncryptsec",
+  });
+  await page
+    .getByTestId("nostr-import-passphrase")
+    .fill("mock horse battery staple lake orbit");
+  await page.getByTestId("nostr-import-submit").click();
+
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
+});
+
 test("non-local runtime override keeps community selection without release flag", async ({
   page,
 }) => {
@@ -1280,6 +1405,66 @@ test("first-community direct join reaches profile", async ({ page }) => {
     .toEqual({ communityCount: 1, transactionMatchesOnlyCommunity: true });
 });
 
+test("community onboarding reuses an existing relay profile", async ({
+  page,
+}) => {
+  await seedActiveIdentity(page, BLANK_TYLER_IDENTITY);
+  await page.addInitScript(
+    ({ pubkey, transactionStorageKey }) => {
+      window.localStorage.setItem(
+        `buzz-machine-onboarding-complete.v2:${pubkey}`,
+        "true",
+      );
+      const timestamp = new Date().toISOString();
+      window.localStorage.setItem(
+        transactionStorageKey,
+        JSON.stringify({
+          id: "txn-existing-profile",
+          source: "add-community",
+          stage: "profile",
+          relayUrl: "wss://onboarding.communities.buzz.xyz",
+          communityName: "Onboarding",
+          communityId: "e2e-default-community",
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    },
+    {
+      pubkey: BLANK_TYLER_IDENTITY.pubkey,
+      transactionStorageKey: COMMUNITY_ONBOARDING_TRANSACTION_STORAGE_KEY,
+    },
+  );
+  await installMockBridge(
+    page,
+    { profileHasEvent: true },
+    {
+      relayWsUrl: "wss://onboarding.communities.buzz.xyz",
+      skipOnboardingSeed: true,
+    },
+  );
+  await page.goto("/");
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (
+            window as Window & { __BUZZ_E2E_COMMANDS__?: string[] }
+          ).__BUZZ_E2E_COMMANDS__?.filter(
+            (command) => command === "get_profile",
+          ).length ?? 0,
+      ),
+    )
+    .toBeGreaterThan(0);
+  await expect(
+    page.getByRole("heading", { name: "Meet your starter team" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("heading", { name: "Build your profile" }),
+  ).toHaveCount(0);
+});
+
 test("first-community direct join cancel returns to request access", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/profile-backup-settings.spec.ts b/desktop/tests/e2e/profile-backup-settings.spec.ts
new file mode 100644
index 0000000000..edd66170da
--- /dev/null
+++ b/desktop/tests/e2e/profile-backup-settings.spec.ts
@@ -0,0 +1,259 @@
+import { expect, test, type Page } from "@playwright/test";
+import { npubEncode } from "nostr-tools/nip19";
+
+import { installMockBridge } from "../helpers/bridge";
+import { openSettings } from "../helpers/settings";
+
+const CURRENT_PUBKEY = "deadbeef".repeat(8);
+const DIFFERENT_PUBKEY = "c0ffee00".repeat(8);
+const BACKUP_FILE = {
+  name: "identity.ncryptsec",
+  mimeType: "text/plain",
+  buffer: Buffer.from("ncryptsec1mockbackupmaterial"),
+};
+
+async function openIdentity(page: Page) {
+  const identity = page.getByTestId("profile-identity-card");
+  if (
+    !(await identity.evaluate(
+      (element) => element instanceof HTMLDetailsElement && element.open,
+    ))
+  ) {
+    await page.getByTestId("profile-identity-toggle").click();
+  }
+}
+
+async function openBackupSettings(
+  page: Page,
+  mock?: Parameters<typeof installMockBridge>[1],
+) {
+  await installMockBridge(page, mock);
+  await page.goto("/");
+  await openSettings(page, "profile");
+  await openIdentity(page);
+}
+
+async function openPrivateKeyMenu(page: Page) {
+  const reveal = page.getByTestId("profile-private-key-toggle");
+  if ((await reveal.textContent())?.trim() === "Reveal") {
+    await reveal.click();
+  }
+  await page.getByTestId("nsec-actions").click();
+  await expect(page.getByTestId("private-key-create-backup")).toBeVisible();
+}
+
+async function openCreateBackup(page: Page) {
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-create-backup").click();
+  const dialog = page.getByTestId("encrypted-backup-dialog");
+  await expect(dialog).toBeVisible();
+  return dialog;
+}
+
+async function openTestBackup(page: Page) {
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-test-backup").click();
+  const dialog = page.getByTestId("backup-test-dialog");
+  await expect(dialog).toBeVisible();
+  return dialog;
+}
+
+async function selectBackupFile(page: Page) {
+  await page.getByTestId("backup-test-file-input").setInputFiles(BACKUP_FILE);
+  await expect(page.getByTestId("backup-test-file-accepted")).toContainText(
+    BACKUP_FILE.name,
+  );
+}
+
+async function verifyBackup(page: Page, password: string) {
+  await page.getByTestId("backup-test-password").fill(password);
+  await page.getByTestId("backup-test-verify").click();
+}
+
+async function backupSaveCallCount(page: Page) {
+  return page.evaluate(
+    () =>
+      window.__BUZZ_E2E_COMMANDS__?.filter(
+        (command) => command === "save_ncryptsec_copy",
+      ).length ?? 0,
+  );
+}
+
+test("private key menu replaces the backup settings rows", async ({ page }) => {
+  await openBackupSettings(page);
+
+  await expect(page.getByTestId("profile-encrypted-backup-row")).toHaveCount(0);
+  await expect(page.getByTestId("profile-backup-test-row")).toHaveCount(0);
+
+  await openPrivateKeyMenu(page);
+  await expect(page.getByTestId("nsec-copy")).toContainText("Copy");
+  await expect(page.getByTestId("private-key-create-backup")).toHaveText(
+    "Create backup",
+  );
+  await expect(page.getByTestId("private-key-test-backup")).toHaveText(
+    "Test backup",
+  );
+
+  await page.getByTestId("nsec-copy").click();
+  await expect(page.getByText(/clipboard$/i)).toBeVisible();
+  await expect(page.getByTestId("private-key-create-backup")).toHaveCount(0);
+
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-test-backup").click();
+  const testDialog = page.getByTestId("backup-test-dialog");
+  await expect(testDialog).toContainText("Test a key backup");
+  await expect(testDialog.getByText("Select your backup file")).toBeVisible();
+  await expect(testDialog).toContainText("standard NIP-49 format");
+});
+
+test("creation requires a sufficiently long password and exposes a temporary header download", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupSavePaths: [
+      "/Users/test/Downloads/identity.ncryptsec",
+      "/Users/test/Desktop/identity-copy.ncryptsec",
+    ],
+  });
+  const dialog = await openCreateBackup(page);
+
+  const password = dialog.getByTestId("backup-passphrase-input");
+  const submit = dialog.getByTestId("encrypted-backup-create");
+  await expect(password).toHaveAttribute(
+    "placeholder",
+    "Password (min 12 characters)",
+  );
+  await expect(submit).toBeDisabled();
+  await password.fill("short");
+  await expect(submit).toBeDisabled();
+
+  await password.fill("custom password");
+  await expect(submit).toBeEnabled();
+  await submit.click();
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  await expect(dialog).toBeHidden();
+
+  const keyRow = page.getByTestId("profile-private-key-row");
+  const download = keyRow.getByTestId("encrypted-backup-download");
+  await expect(download).toBeVisible();
+  await expect(download).toHaveText("Download backup");
+  await expect(download).toHaveClass(/bg-primary/);
+  await expect(
+    download.getByTestId("encrypted-backup-availability-fill"),
+  ).toBeVisible();
+  await expect(keyRow.getByTestId("profile-private-key-toggle")).toBeVisible();
+
+  await download.click();
+  await expect.poll(() => backupSaveCallCount(page)).toBe(2);
+});
+
+test("encryption and native save continue after closing the dialog and settings", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupEncryptionDelayMs: 750,
+    backupSavePaths: [null],
+  });
+  const dialog = await openCreateBackup(page);
+  await dialog
+    .getByTestId("backup-passphrase-input")
+    .fill("background password");
+  await dialog.getByTestId("encrypted-backup-create").click();
+  await expect(dialog.getByTestId("encrypted-backup-progress")).toBeVisible();
+
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await page.getByTestId("settings-back-to-app").click();
+  await expect(page.getByTestId("settings-back-to-app")).toHaveCount(0);
+  await expect(
+    page.getByText("Preparing backup…", { exact: true }),
+  ).toBeVisible();
+
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  const readyToast = page.getByText("Backup ready to download", {
+    exact: true,
+  });
+  await expect(readyToast).toBeVisible();
+  await expect(
+    page.getByText("Your backup will be available to download for 5 minutes.", {
+      exact: true,
+    }),
+  ).toBeVisible();
+
+  await page.getByRole("button", { name: "Open settings" }).click();
+  await expect(page.getByTestId("settings-back-to-app")).toBeVisible();
+  await openIdentity(page);
+  await expect(page.getByTestId("encrypted-backup-download")).toBeVisible();
+});
+
+test("the temporary download expires after five minutes", async ({ page }) => {
+  await page.clock.install({ time: new Date("2026-07-29T12:00:00Z") });
+  await openBackupSettings(page);
+  const dialog = await openCreateBackup(page);
+  await dialog.getByTestId("backup-passphrase-input").fill("expiring password");
+  await dialog.getByTestId("encrypted-backup-create").click();
+  await page.clock.fastForward(1);
+
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  const download = page.getByTestId("encrypted-backup-download");
+  await expect(download).toHaveText("Download backup");
+  await expect(
+    download.getByTestId("encrypted-backup-availability-fill"),
+  ).toBeVisible();
+  await page.clock.fastForward(5 * 60 * 1000 + 1);
+  await expect(page.getByTestId("encrypted-backup-download")).toHaveCount(0);
+});
+
+test("wrong backup password permits a successful retry in the test modal", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupVerificationErrors: ["Wrong password.", null],
+  });
+  const dialog = await openTestBackup(page);
+  await selectBackupFile(page);
+
+  await verifyBackup(page, "wrong password");
+  await expect(dialog.getByTestId("backup-test-error")).toHaveText(
+    "Wrong password.",
+  );
+  await expect(dialog.getByTestId("backup-test-password")).toHaveValue("");
+  await expect(dialog.getByTestId("backup-test-verify")).toBeDisabled();
+
+  await verifyBackup(page, "correct password");
+  await expect(dialog.getByTestId("backup-test-success")).toContainText(
+    "It restores your current Buzz identity.",
+  );
+});
+
+for (const identity of [
+  {
+    label: "current",
+    pubkey: CURRENT_PUBKEY,
+    message: "It restores your current Buzz identity.",
+  },
+  {
+    label: "different",
+    pubkey: DIFFERENT_PUBKEY,
+    message: "It restores a different identity than the one signed in here.",
+  },
+]) {
+  test(`successful modal verification identifies the ${identity.label} identity using only its npub`, async ({
+    page,
+  }) => {
+    await openBackupSettings(page, {
+      backupVerificationPubkeys: [identity.pubkey],
+    });
+    const dialog = await openTestBackup(page);
+    await selectBackupFile(page);
+    await verifyBackup(page, "one-time password");
+
+    const success = dialog.getByTestId("backup-test-success");
+    await expect(success).toContainText(identity.message);
+    await expect(success.getByTestId("backup-test-npub")).toContainText(
+      npubEncode(identity.pubkey),
+    );
+    await expect(success).not.toContainText(identity.pubkey);
+    await expect(success).not.toContainText("one-time password");
+    await expect(success).not.toContainText(BACKUP_FILE.buffer.toString());
+  });
+}
diff --git a/desktop/tests/e2e/relay-reconnect.spec.ts b/desktop/tests/e2e/relay-reconnect.spec.ts
index 6240cca0ba..6606d5f04d 100644
--- a/desktop/tests/e2e/relay-reconnect.spec.ts
+++ b/desktop/tests/e2e/relay-reconnect.spec.ts
@@ -49,6 +49,44 @@ async function restartMockWebsockets(page: import("@playwright/test").Page) {
   expect(restarted).toBeGreaterThan(0);
 }
 
+async function setMockWebsocketUnavailable(
+  page: import("@playwright/test").Page,
+  unavailable: boolean,
+) {
+  await page.evaluate((value) => {
+    const setUnavailable = window.__BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__;
+    if (!setUnavailable) {
+      throw new Error("E2E websocket availability seam is not installed.");
+    }
+    setUnavailable(value);
+  }, unavailable);
+}
+
+async function activateRelayRateLimit(
+  page: import("@playwright/test").Page,
+  seconds: number,
+) {
+  await page.evaluate((duration) => {
+    const activate = window.__BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__;
+    if (!activate) {
+      throw new Error("E2E relay rate-limit seam is not installed.");
+    }
+    activate(duration);
+  }, seconds);
+}
+
+async function getMockWebsocketConnectAttempts(
+  page: import("@playwright/test").Page,
+) {
+  return page.evaluate(() => {
+    const getAttempts = window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__;
+    if (!getAttempts) {
+      throw new Error("E2E websocket attempt seam is not installed.");
+    }
+    return getAttempts();
+  });
+}
+
 async function emitMockMessages(
   page: import("@playwright/test").Page,
   messages: Array<{ content: string; createdAt: number }>,
@@ -121,6 +159,77 @@ test("failed initial relay dial retries automatically", async ({ page }) => {
   await expect(page.getByTestId("channel-general")).toBeVisible();
 });
 
+test("routine traffic cannot bypass outage backoff and recovery stays automatic", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await setMockWebsocketUnavailable(page, true);
+  await disconnectMockWebsockets(page);
+
+  // Exercise the production query path throughout the outage. Before the
+  // coordinator fix, each rejected query called ensureConnected(), cancelled
+  // the scheduled timer, and dialed immediately. The fixed session keeps these
+  // callers behind its single jittered exponential-backoff attempt.
+  await page.evaluate(async () => {
+    const deadline = Date.now() + 4_200;
+    while (Date.now() < deadline) {
+      await window.__BUZZ_E2E_QUERY_CLIENT__?.invalidateQueries({
+        queryKey: ["channels"],
+      });
+      await new Promise((resolve) => window.setTimeout(resolve, 100));
+    }
+  });
+
+  const attempts = await getMockWebsocketConnectAttempts(page);
+  expect(attempts.length).toBeGreaterThanOrEqual(2);
+  expect(attempts.length).toBeLessThanOrEqual(3);
+  for (let index = 1; index < attempts.length; index += 1) {
+    expect(attempts[index] - attempts[index - 1]).toBeGreaterThanOrEqual(700);
+  }
+
+  await setMockWebsocketUnavailable(page, false);
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      { timeout: 10_000 },
+    )
+    .toBe("connected");
+
+  const afterRecovery = `automatic outage recovery ${Date.now()}`;
+  await emitMockMessages(page, [
+    { content: afterRecovery, createdAt: Math.floor(Date.now() / 1_000) },
+  ]);
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    afterRecovery,
+  );
+});
+
+test("authenticated reconnect reports connected while replay is rate-limited", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await activateRelayRateLimit(page, 5);
+  await disconnectMockWebsockets(page);
+
+  // Replay remains intentionally blocked behind admission control, but socket
+  // open + successful AUTH is already a healthy connection. The UI must not
+  // claim the relay is unreachable for the rest of the gate window.
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      { timeout: 3_000 },
+    )
+    .toBe("connected");
+  await expect(page.getByTestId("sidebar-relay-unreachable")).toHaveCount(0);
+});
+
 test("service restart close resets accumulated backoff", async ({ page }) => {
   await installMockBridge(page, {
     websocketConnectErrors: ["down 1", "down 2", "down 3"],
diff --git a/desktop/tests/e2e/relay-restart.live.spec.ts b/desktop/tests/e2e/relay-restart.live.spec.ts
index 057ef46f52..f3c80e69a1 100644
--- a/desktop/tests/e2e/relay-restart.live.spec.ts
+++ b/desktop/tests/e2e/relay-restart.live.spec.ts
@@ -1,8 +1,13 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
 import { expect, test, type Page } from "@playwright/test";
 
-import { installBridge } from "../helpers/bridge";
+import { installBridge, TEST_IDENTITIES } from "../helpers/bridge";
 import { TwoRelayHarness, type RelaySpec } from "./helpers/twoRelayHarness";
 
+const exec = promisify(execFile);
+
 // Live gate: boots a REAL buzz-relay process, points the app at it, SIGTERMs
 // the relay mid-session, restarts it on the same port, and asserts the client
 // converges back to "connected". This proves the full restart story end to
@@ -20,6 +25,55 @@ function required(name: string, value: string | undefined): string {
   return value;
 }
 
+async function runCli(args: string[], relayUrl: string, privateKey: string) {
+  const binary = required("BUZZ_E2E_CLI_BIN", process.env.BUZZ_E2E_CLI_BIN);
+  const { stdout } = await exec(binary, args, {
+    cwd: "..",
+    env: {
+      ...process.env,
+      BUZZ_AUTH_TAG: "",
+      BUZZ_PRIVATE_KEY: privateKey,
+      BUZZ_RELAY_URL: relayUrl,
+    },
+  });
+  return stdout;
+}
+
+async function seedLiveChannel(relayUrl: string) {
+  const name = `reconnect-live-${process.pid}`;
+  const created = JSON.parse(
+    await runCli(
+      [
+        "channels",
+        "create",
+        "--name",
+        name,
+        "--type",
+        "stream",
+        "--visibility",
+        "open",
+      ],
+      relayUrl,
+      TEST_IDENTITIES.alice.privateKey,
+    ),
+  ) as { channel_id: string };
+  await runCli(
+    [
+      "channels",
+      "add-member",
+      "--channel",
+      created.channel_id,
+      "--pubkey",
+      TEST_IDENTITIES.tyler.pubkey,
+      "--role",
+      "member",
+    ],
+    relayUrl,
+    TEST_IDENTITIES.alice.privateKey,
+  );
+  return { id: created.channel_id, name };
+}
+
 async function connectionState(page: Page): Promise<string> {
   return page.evaluate(() => {
     const win = window as Window & {
@@ -29,13 +83,61 @@ async function connectionState(page: Page): Promise<string> {
   });
 }
 
+async function exerciseBackgroundTraffic(page: Page, durationMs: number) {
+  await page.evaluate(async (duration) => {
+    const deadline = Date.now() + duration;
+    while (Date.now() < deadline) {
+      void window.__BUZZ_E2E_QUERY_CLIENT__?.invalidateQueries({
+        queryKey: ["channels"],
+      });
+      await new Promise((resolve) => window.setTimeout(resolve, 100));
+    }
+  }, durationMs);
+}
+
+async function resetConnectAttempts(page: Page) {
+  await page.evaluate(() => {
+    window.__BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__?.();
+  });
+}
+
+async function assertConnectAttemptsArePaced(page: Page) {
+  const attempts = await page.evaluate(
+    () => window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__?.() ?? [],
+  );
+  expect(attempts.length).toBeGreaterThanOrEqual(2);
+  expect(attempts.length).toBeLessThanOrEqual(4);
+  for (let index = 1; index < attempts.length; index += 1) {
+    expect(attempts[index] - attempts[index - 1]).toBeGreaterThanOrEqual(700);
+  }
+}
+
+async function proveLiveDelivery(
+  page: Page,
+  relayUrl: string,
+  channel: { id: string; name: string },
+  label: string,
+) {
+  await page.getByTestId(`channel-${channel.name}`).click();
+  await expect(page.getByTestId("chat-title")).toHaveText(channel.name);
+  const message = `${label} ${Date.now()}`;
+  await runCli(
+    ["messages", "send", "--channel", channel.id, "--content", message],
+    relayUrl,
+    TEST_IDENTITIES.alice.privateKey,
+  );
+  await expect(page.getByTestId("message-timeline")).toContainText(message, {
+    timeout: 30_000,
+  });
+}
+
 test.describe("relay restart live gate", () => {
   test.skip(!enabled, "set BUZZ_E2E_RELAY_RESTART=1 to run live gate");
 
   test("client reconnects after the relay is SIGTERMed and restarted", async ({
     page,
   }) => {
-    test.setTimeout(180_000);
+    test.setTimeout(240_000);
     const portBase = 26_000 + (process.pid % 3_000);
     const spec: RelaySpec = {
       name: "relay-restart",
@@ -56,6 +158,8 @@ test.describe("relay restart live gate", () => {
       await harness.startRelays();
 
       const relayHttpUrl = `http://127.0.0.1:${spec.ports.main}`;
+      const channel = await test.step("seed live channel and membership", () =>
+        seedLiveChannel(relayHttpUrl));
       await installBridge(page, {
         mode: "relay",
         user: "tyler",
@@ -64,28 +168,68 @@ test.describe("relay restart live gate", () => {
       });
       await page.goto("/");
 
-      // Baseline: the app converges to a live authenticated session.
-      await expect
-        .poll(() => connectionState(page), { timeout: 60_000 })
-        .toBe("connected");
+      // Baseline: the app converges to a live authenticated session and sees
+      // the channel created for this fresh database.
+      await test.step("wait for initial authenticated connection", async () => {
+        await expect
+          .poll(() => connectionState(page), { timeout: 60_000 })
+          .toBe("connected");
+        await expect(page.getByTestId(`channel-${channel.name}`)).toBeVisible({
+          timeout: 30_000,
+        });
+      });
 
       // Roll the pod. Graceful drain: readiness 503 → 5s grace → 1012 close
       // broadcast → process exit. The client must observe the close (not a
       // silent stall) and start retrying.
+      await resetConnectAttempts(page);
       await harness.terminateRelayGracefully(spec.name);
       await expect
         .poll(() => connectionState(page), { timeout: 30_000 })
         .not.toBe("connected");
 
+      // Keep the real relay unavailable across several reconnect windows while
+      // ordinary app traffic continues. This is the production-shaped race:
+      // background queries must not bypass the session coordinator's backoff.
+      await exerciseBackgroundTraffic(page, 8_000);
+      await expect.poll(() => connectionState(page)).not.toBe("connected");
+      await assertConnectAttemptsArePaced(page);
+
       // Bring the "new pod" up on the same address, exactly like a k8s
       // restart behind a stable service endpoint.
       await harness.restartRelay(spec.name);
 
       // The client's retry loop must find the fresh relay and converge back
-      // to connected without any user interaction.
+      // to connected without any user interaction, then prove that AUTH and
+      // live-subscription replay finished by receiving an event published by
+      // a second identity through the real CLI/relay boundary.
       await expect
         .poll(() => connectionState(page), { timeout: 60_000 })
         .toBe("connected");
+      await proveLiveDelivery(
+        page,
+        relayHttpUrl,
+        channel,
+        "first automatic recovery",
+      );
+
+      // Flap the fresh pod once more. A second recovery catches stale timer,
+      // waiter, generation, and subscription state that a single cycle cannot.
+      await harness.terminateRelayGracefully(spec.name);
+      await expect
+        .poll(() => connectionState(page), { timeout: 30_000 })
+        .not.toBe("connected");
+      await exerciseBackgroundTraffic(page, 4_000);
+      await harness.restartRelay(spec.name);
+      await expect
+        .poll(() => connectionState(page), { timeout: 60_000 })
+        .toBe("connected");
+      await proveLiveDelivery(
+        page,
+        relayHttpUrl,
+        channel,
+        "second automatic recovery",
+      );
     } catch (error) {
       console.error(await harness.logs());
       throw error;
diff --git a/desktop/tests/e2e/signout-confirmation.spec.ts b/desktop/tests/e2e/signout-confirmation.spec.ts
index b87caf5975..7b6c9b5761 100644
--- a/desktop/tests/e2e/signout-confirmation.spec.ts
+++ b/desktop/tests/e2e/signout-confirmation.spec.ts
@@ -3,7 +3,7 @@
  *
  * Signing out wipes the identity key and all local data, so the dialog gates
  * "Delete My Data" behind two explicit steps:
- *   1. backup — reveal/copy the nsec, then check "I have saved my private key"
+ *   1. backup — check "I have saved my private key"
  *   2. typed confirmation — type the exact phrase "wipe all my data"
  */
 import { expect, type Page, test } from "@playwright/test";
@@ -13,10 +13,6 @@ import { openSettings } from "../helpers/settings";
 
 const CONFIRM_PHRASE = "wipe all my data";
 
-// The mock bridge routes copy_text_to_clipboard through navigator.clipboard,
-// which requires explicit permissions in headless Chromium.
-test.use({ permissions: ["clipboard-read", "clipboard-write"] });
-
 async function openSignOutDialog(page: Page) {
   await openSettings(page, "profile");
   const section = page.getByTestId("settings-signout");
@@ -36,12 +32,8 @@ test("delete button unlocks only after backup + typed phrase", async ({
   const backupCheckbox = page.getByTestId("signout-backup-confirm");
   const phraseInput = page.getByTestId("signout-confirm-phrase");
 
-  // Everything locked initially: no key interaction yet.
+  // Delete is locked initially; the backup checkbox is immediately usable.
   await expect(deleteButton).toBeDisabled();
-  await expect(backupCheckbox).toBeDisabled();
-
-  // Copying the key unlocks the backup checkbox.
-  await page.getByTestId("nsec-copy").click();
   await expect(backupCheckbox).toBeEnabled();
   await backupCheckbox.click();
 
@@ -61,24 +53,11 @@ test("delete button unlocks only after backup + typed phrase", async ({
   await expect(deleteButton).toBeDisabled();
 });
 
-test("reveal also unlocks the backup checkbox", async ({ page }) => {
-  await installMockBridge(page);
-  await page.goto("/");
-  await openSignOutDialog(page);
-
-  const backupCheckbox = page.getByTestId("signout-backup-confirm");
-  await expect(backupCheckbox).toBeDisabled();
-
-  await page.getByTestId("nsec-reveal-toggle").click();
-  await expect(backupCheckbox).toBeEnabled();
-});
-
 test("completing both gates invokes sign_out", async ({ page }) => {
   await installMockBridge(page);
   await page.goto("/");
   await openSignOutDialog(page);
 
-  await page.getByTestId("nsec-copy").click();
   await page.getByTestId("signout-backup-confirm").click();
   await page.getByTestId("signout-confirm-phrase").fill(CONFIRM_PHRASE);
 
@@ -104,16 +83,15 @@ test("cancel resets the gates for the next open", async ({ page }) => {
   await openSignOutDialog(page);
 
   // Satisfy both gates, then cancel.
-  await page.getByTestId("nsec-copy").click();
   await page.getByTestId("signout-backup-confirm").click();
   await page.getByTestId("signout-confirm-phrase").fill(CONFIRM_PHRASE);
   await page.getByRole("button", { name: "Cancel" }).click();
   await expect(page.getByRole("alertdialog")).not.toBeVisible();
 
-  // Reopen — everything must be locked again.
+  // Reopen — everything must be reset again.
   await page.getByTestId("signout-open-dialog").click();
   await expect(page.getByRole("alertdialog")).toBeVisible();
-  await expect(page.getByTestId("signout-backup-confirm")).toBeDisabled();
+  await expect(page.getByTestId("signout-backup-confirm")).not.toBeChecked();
   await expect(page.getByTestId("signout-confirm-phrase")).toHaveValue("");
   await expect(page.getByTestId("signout-confirm")).toBeDisabled();
 });
@@ -125,8 +103,8 @@ test("nsec load failure still allows sign-out (backup step degrades)", async ({
   await page.goto("/");
   await openSignOutDialog(page);
 
-  // Error shown in place of the key; checkbox is usable so the user is not
-  // permanently locked out of signing out.
+  // Error shown in place of the key; checkbox is still usable so the user is
+  // not locked out of signing out.
   await expect(page.getByTestId("signout-nsec-error")).toContainText(
     "Keychain locked",
   );
diff --git a/desktop/tests/e2e/signout-screenshots.spec.ts b/desktop/tests/e2e/signout-screenshots.spec.ts
index 32fc3ed09d..5cf35c70ab 100644
--- a/desktop/tests/e2e/signout-screenshots.spec.ts
+++ b/desktop/tests/e2e/signout-screenshots.spec.ts
@@ -23,7 +23,7 @@ test.describe("signout screenshots", () => {
     });
   });
 
-  test("signout-section — Sign Out card in Settings › Profile", async ({
+  test("signout-section — data deletion card in Settings › Profile", async ({
     page,
   }) => {
     await installMockBridge(page);
@@ -32,6 +32,9 @@ test.describe("signout screenshots", () => {
 
     const section = page.getByTestId("settings-signout");
     await section.scrollIntoViewIfNeeded();
+    await expect(
+      section.getByRole("button", { name: "Delete my data" }),
+    ).toBeVisible();
 
     // Settle animations before capture.
     await page.evaluate(() =>
@@ -59,7 +62,7 @@ test.describe("signout screenshots", () => {
     await expect(dialog).toBeVisible({ timeout: 5_000 });
     await expect(dialog.getByText("Sign out and wipe all data?")).toBeVisible();
     await expect(
-      dialog.getByRole("button", { name: "Delete My Data" }),
+      dialog.getByRole("button", { name: "Delete my data" }),
     ).toBeVisible();
 
     // Settle animations before capture.
diff --git a/desktop/tests/e2e/video-attachment.spec.ts b/desktop/tests/e2e/video-attachment.spec.ts
index 8f4bb0aa4a..458689a5e0 100644
--- a/desktop/tests/e2e/video-attachment.spec.ts
+++ b/desktop/tests/e2e/video-attachment.spec.ts
@@ -53,25 +53,31 @@ function emitMockMessage(
   page: Page,
   channelName: string,
   content: string,
-  options: { extraTags?: string[][] } = {},
+  options: { extraTags?: string[][]; parentEventId?: string } = {},
 ) {
   return page.evaluate(
-    ({ channelName, content, extraTags }) => {
+    ({ channelName, content, extraTags, parentEventId }) => {
       const emit = (
         window as Window & {
           __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
             channelName: string;
             content: string;
             extraTags?: string[][];
+            parentEventId?: string;
           }) => unknown;
         }
       ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
       if (!emit) {
         throw new Error("Mock message emitter is unavailable.");
       }
-      emit({ channelName, content, extraTags });
+      return emit({ channelName, content, extraTags, parentEventId });
+    },
+    {
+      channelName,
+      content,
+      extraTags: options.extraTags,
+      parentEventId: options.parentEventId,
     },
-    { channelName, content, extraTags: options.extraTags },
   );
 }
 
@@ -765,6 +771,55 @@ test("video upload previews use poster frames and inline videos open review mode
   ).toContainText("Color pass looks right");
 });
 
+test("video replies in threads open the review comments view", async ({
+  page,
+}) => {
+  await installVideoReviewHarness(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,
+    "general",
+    "Can you review this cut?",
+  )) as { id: string };
+  const videoReply = (await emitMockMessage(
+    page,
+    "general",
+    `![video](${VIDEO_URL})`,
+    {
+      parentEventId: root.id,
+    },
+  )) as { id: string };
+  await emitMockMessage(page, "general", "[00:01] Tighten this transition.", {
+    parentEventId: videoReply.id,
+  });
+
+  const threadSummary = page.locator(`[data-thread-head-id="${root.id}"]`);
+  await expect(threadSummary).toBeVisible();
+  await threadSummary.click();
+
+  const threadPanel = page.getByTestId("message-thread-panel");
+  const threadReplies = threadPanel.getByTestId("message-thread-replies");
+  const reviewButton = threadReplies.getByRole("button", {
+    name: "Open video review",
+  });
+  await expect(reviewButton).toBeVisible();
+  await reviewButton.click();
+
+  const reviewDialog = page.getByTestId("video-review-dialog");
+  await expect(
+    reviewDialog.getByTestId("video-review-comments-panel"),
+  ).toBeVisible();
+  await expect(reviewDialog.getByTestId("message-composer")).toBeVisible();
+  await expect(reviewDialog.getByTestId("video-review-comments")).toContainText(
+    "Tighten this transition.",
+  );
+});
+
 test("narrow inline videos hide playback speed control", async ({ page }) => {
   await installVideoReviewHarness(page);
 
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/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index ca4d62ddd6..8a9ab2be11 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -83,6 +83,17 @@ type MockRelayAgentSeed = {
   status?: "online" | "away" | "offline";
 };
 
+type MockHuddleSeed = {
+  parentChannelId: string;
+  ephemeralChannelId: string;
+  members: Array<{
+    pubkey: string;
+    role: "owner" | "admin" | "member" | "guest" | "bot";
+  }>;
+  transcriptionEnabled?: boolean;
+  isCreator?: boolean;
+};
+
 type MockPersonaSeed = {
   id?: string;
   displayName: string;
@@ -131,11 +142,36 @@ export type MockAgentMemoryListing = {
   fetchedAt: number;
 };
 
+/** Result returned by the `install_acp_runtime` mock command. */
+type MockInstallRuntimeResult = {
+  success: boolean;
+  steps: {
+    step: string;
+    command: string;
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exit_code: number | null;
+    hint?: string;
+  }[];
+  /** Install log the failure message points at. Omitted = no log was written. */
+  log_path?: string | null;
+};
+
 type MockBridgeOptions = {
+  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. */
   relaySelf?: string | null;
+  /** Native-like huddle state seeded from authoritative role-bearing membership. */
+  huddle?: MockHuddleSeed;
   /** Builderlab account returned by hosted-community onboarding. Null/omitted = signed out. */
   builderlabAuth?: { email?: string; name?: string; expiresAt: string } | null;
   /** Optional policy returned by the native join-policy discovery command. */
@@ -171,35 +207,17 @@ type MockBridgeOptions = {
   connectAcpRuntimeDelayMs?: number;
   connectAcpRuntimeError?: string;
   installAcpRuntimeDelayMs?: number;
+  /** Live output lines the mocked install emits before it settles, in order.
+   *  Each arrives as an `acp-install-output` event, preceded by the clear
+   *  signal the backend sends at the start of an attempt. */
+  installAcpRuntimeOutputLines?: string[];
   /** Override the result returned by the `install_acp_runtime` mock command.
    *  Pass `{ success: false, steps: [...] }` to exercise error/Retry states. */
-  installAcpRuntimeResult?: {
-    success: boolean;
-    steps: {
-      step: string;
-      command: string;
-      success: boolean;
-      stdout: string;
-      stderr: string;
-      exit_code: number | null;
-      hint?: string;
-    }[];
-  };
+  installAcpRuntimeResult?: MockInstallRuntimeResult;
   /** Sequence of results for successive `install_acp_runtime` calls. Call N
    *  returns results[N]; when exhausted the last entry repeats. Takes precedence
    *  over `installAcpRuntimeResult`. Use for fail-then-succeed Retry tests. */
-  installAcpRuntimeResults?: Array<{
-    success: boolean;
-    steps: {
-      step: string;
-      command: string;
-      success: boolean;
-      stdout: string;
-      stderr: string;
-      exit_code: number | null;
-      hint?: string;
-    }[];
-  }>;
+  installAcpRuntimeResults?: MockInstallRuntimeResult[];
   activePersonaIds?: string[];
   /**
    * Listing returned by the mocked `get_agent_memory` command. Pass a single
@@ -211,6 +229,14 @@ type MockBridgeOptions = {
     mcp?: MockCommandAvailability;
   };
   managedAgents?: MockManagedAgentSeed[];
+  /** Result returned by the mocked `add_agent_to_huddle` command. */
+  addAgentToHuddleResult?: {
+    ephemeral_added: boolean;
+    parent_added: boolean;
+    parent_error: string | null;
+  };
+  /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
+  huddleStateReadDelayMs?: number;
   /** Per agent+relay runtime rows for pair-scoped lifecycle commands. */
   managedAgentRuntimes?: Array<{
     pubkey: string;
@@ -268,6 +294,8 @@ type MockBridgeOptions = {
   channelWindowDelayMs?: number;
   profileReadDelayMs?: number;
   profileReadError?: string;
+  /** Override whether get_profile reports a real kind:0 event. */
+  profileHasEvent?: boolean;
   profileUpdateError?: string;
   profileUpdateErrors?: string[];
   searchProfiles?: MockSearchProfileSeed[];
@@ -439,6 +467,14 @@ type MockBridgeOptions = {
   /** Delay (ms) for `set_global_agent_config` — hold saves open in tests.
    *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
   setGlobalAgentConfigDelayMs?: number;
+  /** Errors returned by successive backup verification attempts. Null succeeds. */
+  backupVerificationErrors?: (string | null)[];
+  /** Public identities returned by successive successful backup verifications. */
+  backupVerificationPubkeys?: string[];
+  /** Delay (ms) applied to backup encryption so specs can observe pending UI. */
+  backupEncryptionDelayMs?: number;
+  /** Native paths returned by successive backup saves. */
+  backupSavePaths?: Array<string | null>;
   /**
    * When set, `get_nsec` throws with this message. For a single always-fail
    * scenario. Use `nsecErrors` for sequenced fail/succeed.
diff --git a/desktop/tests/helpers/fileDrag.ts b/desktop/tests/helpers/fileDrag.ts
new file mode 100644
index 0000000000..3a396ada0f
--- /dev/null
+++ b/desktop/tests/helpers/fileDrag.ts
@@ -0,0 +1,52 @@
+import type { Page } from "@playwright/test";
+
+/**
+ * Simulate a native file drag entering the window. The backup test flow
+ * listens for window-level dragenter with a "Files" payload and swaps in a
+ * composer-style drop overlay over its host surface.
+ */
+export async function startWindowFileDrag(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const dataTransfer = new DataTransfer();
+    dataTransfer.items.add(
+      new File(["x"], "identity.ncryptsec", { type: "text/plain" }),
+    );
+    window.dispatchEvent(
+      new DragEvent("dragenter", { dataTransfer, bubbles: true }),
+    );
+  });
+}
+
+/** Simulate the file drag leaving the window without dropping. */
+export async function endWindowFileDrag(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    window.dispatchEvent(new DragEvent("dragend", { bubbles: true }));
+  });
+}
+
+/** Drop a text file with the given contents onto the element with `testId`. */
+export async function dropFileOnTestId(
+  page: Page,
+  testId: string,
+  contents: string,
+  name = "identity.ncryptsec",
+): Promise<void> {
+  await page.evaluate(
+    ({ testId, contents, name }) => {
+      const dataTransfer = new DataTransfer();
+      dataTransfer.items.add(
+        new File([contents], name, { type: "text/plain" }),
+      );
+      const target = document.querySelector(`[data-testid="${testId}"]`);
+      if (!target) throw new Error(`drop target ${testId} not found`);
+      target.dispatchEvent(
+        new DragEvent("drop", {
+          dataTransfer,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    },
+    { testId, contents, name },
+  );
+}
diff --git a/desktop/tests/helpers/onboarding.ts b/desktop/tests/helpers/onboarding.ts
index 61b31e6e5b..d7f61bafe6 100644
--- a/desktop/tests/helpers/onboarding.ts
+++ b/desktop/tests/helpers/onboarding.ts
@@ -16,9 +16,8 @@ export async function seedActiveIdentity(
   );
 }
 
-/** Navigate through the backup step (fresh-key path). */
+/** Continue past the created-key page without opening optional backup options. */
 export async function passThroughBackupStep(page: Page) {
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
   await page.getByTestId("onboarding-next").click();
 }
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/docs/MCP_DRIVEN_HOOKS.md b/docs/MCP_DRIVEN_HOOKS.md
index e510c378e7..6812a5b9a6 100644
--- a/docs/MCP_DRIVEN_HOOKS.md
+++ b/docs/MCP_DRIVEN_HOOKS.md
@@ -65,6 +65,23 @@ These constraints ensure a buggy or malicious hook cannot trap the agent.
 Hooks are **off by default**. The operator must explicitly opt in via
 `MCP_HOOK_SERVERS`.
 
+### Not a hook: the reply guard
+
+`buzz-agent` has one in-process objection at the `_Stop` gate that is **not** an
+MCP hook and exposes no hook tool: the reply guard
+(`BUZZ_AGENT_REQUIRE_REPLY=1`), which reminds the model to publish when a turn is
+about to end with nothing posted to Buzz. There is no `_ReplyGuard` tool to
+implement and no server to allowlist — the env var and the recognition contract
+are documented in
+[crates/buzz-agent/README.md](../crates/buzz-agent/README.md#reply-guard).
+
+It is mentioned here only because it shares this lifecycle point and this
+budget: its reminders count against `BUZZ_AGENT_STOP_MAX_REJECTIONS` like any
+hook objection, and a round carrying both a hook objection and a reminder costs
+one rejection and delivers both texts. Setting the budget to 0 disables both.
+That the gate can carry in-process objections alongside hook output is
+deliberate; hooks see no difference.
+
 ## Implementing a Hook
 
 Any MCP server can expose hooks. Example: a test-runner server that blocks
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-AP.md b/docs/nips/NIP-AP.md
index b990f55bef..ad23d92282 100644
--- a/docs/nips/NIP-AP.md
+++ b/docs/nips/NIP-AP.md
@@ -10,7 +10,7 @@ This NIP defines `kind:30175` persona events — public, addressable definitions
 
 ## Kind
 
-This NIP claims `kind:30175` for agent persona definitions. It is in the NIP-33 parameterized replaceable range (30000–39999) per [NIP-01](01.md): addressed by `(pubkey, kind, d_tag)`, with only the latest event per address retained.
+This NIP claims `kind:30175` for agent persona definitions and `kind:30178` for the shareable team-catalog projection (see "Team catalog projection: kind:30178"). Both are in the NIP-33 parameterized replaceable range (30000–39999) per [NIP-01](01.md): addressed by `(pubkey, kind, d_tag)`, with only the latest event per address retained.
 
 A dedicated kind (rather than encoding personas as NIP-78 `kind:30078` "Application-specific Data") is taken for the same reasons as [NIP-AE](NIP-AE.md): (1) it isolates this NIP's address space from any other application using the same pubkey — persona slugs cannot collide with another app's `d` tag choices; (2) it lets observers, indexers, and unknown-kind viewers identify persona events from the kind alone, without parsing content as a namespace demultiplexer.
 
@@ -162,6 +162,8 @@ Owners MAY publish [NIP-09](09.md) deletion requests targeting persona events. A
 
 A subsequent write with a later timestamp resurrects the slug under NIP-33 replacement semantics.
 
+The same applies to `kind:30178`: a deletion request SHOULD carry `["k", "30178"]` and the `a`-tag identifier `30178:<pubkey_o>:<team-id>`. Unsharing is distinct from deletion — it is a newer valid head at the same coordinate published *without* the `shared` tag, which keeps the projection readable to its author while retracting it from foreign readers.
+
 ## Relationships to other NIPs
 
 ### NIP-AE (Agent Engrams)
@@ -216,6 +218,29 @@ surface per-event errors.
 
 Agents spawned from a persona carry [NIP-OA](NIP-OA.md) owner attestation — an `auth` tag proving that `pubkey_o` authorized the agent's key. The persona event itself does not contain attestation; it is the *definition* from which attestation is issued at spawn time.
 
+## Team catalog projection: kind:30178
+
+Kind `30178` is the **shareable projection of a team**: owner-authored, parameterized replaceable, addressed by `(pubkey_o, 30178, d)` where `d` is the team's stable local id. Its `content` is a versioned JSON body carrying sanitized team fields plus ordered, *embedded* member definition projections. The content schema is defined by the client that publishes it; this section specifies only the envelope and the relay's contract.
+
+```jsonc
+{
+  "kind": 30178,
+  "pubkey": "<pubkey_o>",
+  "created_at": <unix_seconds>,
+  "tags": [
+    ["d", "<team-id>"],
+    ["shared", "true"]     // optional; presence opts the projection into community reads
+  ],
+  "content": "<json_body>"
+}
+```
+
+**Why a separate kind rather than a `shared` tag on the team event (kind:30176).** A team's members are `kind:30175` definitions, which are author-only unless individually shared — so a foreign reader of a shared team could never hydrate its members. Kind `30178` embeds the member projections instead of referencing them: the share is atomic, it covers built-in members that have no `30175` head at all, it is immune to local-id/`d`-tag divergence, and an unshared `30175` stays private. Kind `30176`'s wire body is untouched, so device sync keeps its contract.
+
+**The `d` tag is a team id, not a persona slug.** It is either a UUID or a built-in identifier such as `builtin-team:welcome`. The colon is illegal under the persona slug grammar, and rewriting ids to fit would break NIP-33 addressing against the team's own `kind:30176` head — so the relay applies a laxer rule (see below) to `30178` than to `30175`.
+
+**Content carries only sanitized fields.** No environment variables, no `respond_to` allowlist pubkeys, no source or local ids, no filesystem paths, no secrets. Sharing a team makes the team's and every member's instructions community-readable plaintext.
+
 ## Relay behavior
 
 ### Ingest validation
@@ -226,10 +251,20 @@ Agents spawned from a persona carry [NIP-OA](NIP-OA.md) owner attestation — an
 - The relay MUST enforce that the `d` tag is non-empty (standard NIP-33 requirement for parameterized replaceable events).
 - The relay MUST enforce shared-tag shape: if a `shared` tag is present, it MUST consist of **exactly two elements** — `["shared", "true"]`. Extra elements (e.g. `["shared","true","extra"]`), wrong values (`["shared","false"]`), missing values (`["shared"]`), or duplicate `shared` tags are all rejected with `invalid:`. The two-element exact-shape constraint is required so that the relay's SQL visibility clause (`tags @> '[["shared","true"]]'`) never matches a stored malformed tag via JSONB containment supersets.
 
+### Ingest validation: kind:30178
+
+Kind `30178` is stored globally and its content is unvalidated, exactly as for `30175`. The envelope rules differ in one respect — the `d` grammar:
+
+- The relay MUST enforce the same `shared`-tag exact shape as `30175`, for the same reason: the read gate and the SQL containment clause must agree on every stored event.
+- The relay MUST enforce **exactly one** `d` tag whose value is non-empty, at most 64 characters, and free of Unicode control characters and whitespace. Tags are counted by their first element, so a valueless `["d"]` counts toward the total and fails the value check on its own — otherwise `["d"]` alongside `["d","<team-id>"]` would pass, and a consumer that reads `["d"]` as an empty-valued first `d` tag would address the event at `""` while this relay addresses it at `<team-id>`. Without the non-empty check, generic NIP-33 storage maps a missing or empty `d` to the empty coordinate, collapsing every team into the single `(pubkey_o, 30178, "")` slot — last-write-wins data loss. The character bound keeps the value usable as a NIP-33 coordinate and as a log field.
+- The relay MUST NOT apply the persona slug grammar to a `30178` `d` tag; team ids legitimately contain characters (notably `:`) that the slug grammar forbids.
+
 ### Access control: author-only-unless-shared
 
 Kind `30175` uses **shared-tag-gated read semantics** to protect system prompts and `respond_to_allowlist` from being visible to all community members as a side-effect of device sync.
 
+The gate is kind-generic: the relay applies it to every kind in `SHARED_GATED_KINDS` (`buzz-core/src/kind.rs`), currently `30175` and the `30178` team-catalog projection described below. The rules and enforcement surfaces are identical for each member kind.
+
 **Rules:**
 
 | Event state | Author reads | Foreign reads |
@@ -239,13 +274,13 @@ Kind `30175` uses **shared-tag-gated read semantics** to protect system prompts
 
 These rules are enforced at the following relay read surfaces (content and event existence are withheld on all of them):
 
-- **REQ historical delivery** — foreign requests silently omit unshared persona events, even in mixed-kind filters (`{kinds:[30175,9]}`). The visibility check is applied **before `ORDER BY … LIMIT`** at the SQL level (`persona_reader` field in `EventQuery`), so a page of newer private personas cannot starve an older shared persona off the candidate set — the catalog's primary all-author query pattern is correctly served.
+- **REQ historical delivery** — foreign requests silently omit unshared persona events, even in mixed-kind filters (`{kinds:[30175,9]}`). The visibility check is applied **before `ORDER BY … LIMIT`** at the SQL level (`shared_gated_reader` field in `EventQuery`), so a page of newer private personas cannot starve an older shared persona off the candidate set — the catalog's primary all-author query pattern is correctly served.
 - **NIP-01 `ids` lookup** — knowing an event id does NOT grant access to an unshared persona. The result gate returns nothing.
 - **Live fan-out** — unshared personas are delivered only to the author's connections. Shared personas fan out community-wide.
-- **COUNT** — the fast SQL `count_events()` path is bypassed when the filter can match `kind:30175`. A per-event fallback applies the shared-tag check, preventing existence-leak via COUNT.
-- **NIP-98 HTTP bridge `/query`** — the same per-event visibility check is applied to the catchall post-processing loop. The SQL-level `persona_reader` clause also applies before `LIMIT`, preventing older shared personas from being starved by newer private ones on paginated catalog queries. A foreign caller POSTing `{kinds:[30175],authors:[victim]}` or a kindless `{ids:[...]}` filter to `/query` receives no unshared persona content.
-- **NIP-98 HTTP bridge `/count`** — `needs_persona_filtering` forces the per-event fallback path for any filter that can match `kind:30175`; the fast SQL `count_events()` path is not used. Both the channel-scoped and unconstrained fallback loops apply `event_visible_to_reader`, preventing existence-leak via COUNT over HTTP.
-- **FTS (NIP-50 search) and `/search`** — kind `30175` is not in the relay's FTS allowlist (migration 8 indexes only kinds `0, 9, 40002, 45001, 45003`); no FTS result can contain an unshared persona. A defense-in-depth check is also present in the bridge search result loop so that a future FTS allowlist change cannot silently reopen the bypass.
+- **COUNT** — the fast SQL `count_events()` path is bypassed when the filter can match a shared-gated kind. A per-event fallback applies the shared-tag check, preventing existence-leak via COUNT.
+- **NIP-98 HTTP bridge `/query`** — the same per-event visibility check is applied to the catchall post-processing loop. The SQL-level `shared_gated_reader` clause also applies before `LIMIT`, preventing older shared personas from being starved by newer private ones on paginated catalog queries. A foreign caller POSTing `{kinds:[30175],authors:[victim]}` or a kindless `{ids:[...]}` filter to `/query` receives no unshared persona content.
+- **NIP-98 HTTP bridge `/count`** — `needs_shared_gate_filtering` forces the per-event fallback path for any filter that can match a shared-gated kind; the fast SQL `count_events()` path is not used. Both the channel-scoped and unconstrained fallback loops apply `event_visible_to_reader`, preventing existence-leak via COUNT over HTTP.
+- **FTS (NIP-50 search) and `/search`** — no shared-gated kind is in the relay's FTS allowlist (migration 8 indexes only kinds `0, 9, 40002, 45001, 45003`); no FTS result can contain an unshared event. A defense-in-depth check is also present in the bridge search result loop so that a future FTS allowlist change cannot silently reopen the bypass.
 
 **Device sync is unaffected.** The sync subscription (`{kinds:[30175], authors:[self]}`) reads the author's own events, which are always returned regardless of shared state.
 
@@ -263,6 +298,7 @@ These rules are enforced at the following relay read surfaces (content and event
 - **Slug collision across pubkeys.** Two different owners can publish personas with the same slug. Clients MUST always scope queries by author pubkey, not just slug.
 - **Metadata exposure.** The `(pubkey, kind:30175, slug)` triple reveals persona existence. Event timestamps reveal edit history.
 - **No owner write authority over agents.** Persona events define *what* an agent should be; they do not grant runtime control over a running agent. The agent consumes the persona at spawn time. Updates to the persona event do not automatically propagate to running agents.
+- **Sharing a team shares every member's instructions.** A `kind:30178` head carrying `["shared","true"]` exposes the team's own fields *and* the embedded projection of every member — including members whose own `kind:30175` heads are unshared and therefore still private. Clients MUST make this explicit at the point of sharing; the relay cannot infer it.
 
 ## Reference test vectors
 
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-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..4664de21e3
--- /dev/null
+++ b/docs/remote-agents.md
@@ -0,0 +1,1745 @@
+# 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 — **90 seconds**
+  (`PRESENCE_TTL_SECS`, `buzz-pubsub/src/presence.rs:16`; the vision's
+  "ninety seconds of a wrong dot, never an indefinite one"), the accepted
+  cost of M1.
+  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 ≤90s" 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 `c1bca1b56`
+  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
+`c1bca1b56` 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 `c1bca1b56` 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 `c1bca1b56` 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 `c1bca1b56`; 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 `c1bca1b56` 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:74-193`), 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:1006`;
+  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 `c1bca1b56`) — 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). These are **tier-1 by
+  local fact, not by choice**: the local spawn writes them before the user
+  env layer (`runtime.rs:716-729,763` vs `:860`) and none is in
+  `RESERVED_ENV_KEYS`, so a power user's env override beats them today. A
+  provider that independently mapped the top-level payload copies after
+  `launch.env` would invert that — 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`. These keys are
+   deliberately non-reserved (`env_vars.rs:54-57` says so outright: power
+   users may bypass the dedicated UI fields), and 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.
+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.
+
+**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 this PR's base `b4f4ed1a6` 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:809`; 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 90s 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`), because they are tier-1 behavior knobs: locally they are written *before* the user env layer and none is reserved (`runtime.rs:716-729,763` vs `:860`; `env_vars.rs:54-57`), so user env beats them. A provider that mapped the top-level copies after `launch.env` would silently defeat an override that works locally. 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 `b4f4ed1a6`,
+  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 `c1bca1b56`)
+
+**Citation-pin caveat:** `c1bca1b56` is an unmerged feature-branch commit
+that diverged from main on Jul 18 and predates #3038 (default parallelism
+24 → 10). Line references marked `at b4f4ed1a6` were re-verified against
+this PR's own base; unmarked `c1bca1b56` references may be offset on
+current main. A follow-up re-pins the whole document to one merged
+commit.
+
+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 `c1bca1b56`, `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 `c1bca1b56`, `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 `c1bca1b56`; §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 `b4f4ed1a6`: 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 `b4f4ed1a6`: 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:809`; #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
+   `b4f4ed1a6`) 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/mobile/lib/features/activity/activity_page.dart b/mobile/lib/features/activity/activity_page.dart
index db39850481..aecef6329c 100644
--- a/mobile/lib/features/activity/activity_page.dart
+++ b/mobile/lib/features/activity/activity_page.dart
@@ -5,6 +5,8 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/mentions/mention_tags.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/utils/string_utils.dart';
@@ -87,8 +89,16 @@ class ActivityPage extends HookConsumerWidget {
     ];
 
     // Preload sender profiles for visible rows.
-    final pubkeys = visibleItems.map((i) => i.item.pubkey).toSet().toList();
-    ref.read(userCacheProvider.notifier).preload(pubkeys);
+    final preloadPubkeys = {
+      for (final item in visibleItems) item.item.pubkey.toLowerCase(),
+      for (final item in visibleItems)
+        ...mentionedPubkeysFromTags(item.item.tags),
+    }.toList()..sort();
+    final preloadPubkeysKey = preloadPubkeys.join('\u0000');
+    useEffect(() {
+      ref.read(userCacheProvider.notifier).preload(preloadPubkeys);
+      return null;
+    }, [preloadPubkeysKey]);
 
     final unreadVisibleCount = visibleItems.where((i) => !isDone(i)).length;
 
diff --git a/mobile/lib/features/activity/activity_page/inbox_row.dart b/mobile/lib/features/activity/activity_page/inbox_row.dart
index fb267c03be..9dd8b6ddfa 100644
--- a/mobile/lib/features/activity/activity_page/inbox_row.dart
+++ b/mobile/lib/features/activity/activity_page/inbox_row.dart
@@ -61,6 +61,28 @@ class _InboxRow extends ConsumerWidget {
     final userCache = ref.watch(userCacheProvider);
     final profile = userCache[item.item.pubkey.toLowerCase()];
     final senderLabel = profile?.displayName ?? shortPubkey(item.item.pubkey);
+    final profileMentionNames = {
+      for (final pubkey in mentionedPubkeysFromTags(item.item.tags))
+        if (userCache[pubkey]?.displayName?.trim().isNotEmpty == true)
+          pubkey: userCache[pubkey]!.displayName!.trim(),
+    };
+    final mentionPubkeys = mentionedPubkeysFromTags(item.item.tags);
+    final knownAgentPubkeys = channel == null
+        ? ref.watch(knownAgentPubkeysProvider)
+        : ref.watch(agentMentionPubkeysProvider(channel!.id));
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: knownAgentPubkeys,
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     final isDm = channel?.isDm ?? false;
     final channelName = channel != null && !isDm
@@ -172,6 +194,8 @@ class _InboxRow extends ConsumerWidget {
                   // Message preview.
                   MessageContent(
                     content: item.item.displayContent,
+                    mentionNames: mentionNames,
+                    agentMentionPubkeys: agentMentionPubkeys,
                     tags: item.item.tags,
                     maxLines: 2,
                     baseStyle: activityPreviewTextStyle.copyWith(
diff --git a/mobile/lib/features/channels/agent_activity/working_bots_provider.dart b/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
index 179ea0d4f3..8730908ada 100644
--- a/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
+++ b/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
@@ -8,21 +8,20 @@ import '../channel_typing_provider.dart';
 ///
 /// Used by both the members button badge and the members sheet to avoid
 /// duplicating the bot-typing cross-reference logic.
-final workingBotPubkeysProvider = Provider.family<Set<String>, String>((
-  ref,
-  channelId,
-) {
-  final typingEntries = ref.watch(channelTypingProvider(channelId));
-  final membersAsync = ref.watch(channelMembersProvider(channelId));
-  final allMembers = membersAsync.asData?.value ?? const <ChannelMember>[];
+final workingBotPubkeysProvider = Provider.autoDispose
+    .family<Set<String>, String>((ref, channelId) {
+      final typingEntries = ref.watch(channelTypingProvider(channelId));
+      final membersAsync = ref.watch(channelMembersProvider(channelId));
+      final allMembers = membersAsync.asData?.value ?? const <ChannelMember>[];
 
-  final botPubkeys = <String>{
-    for (final m in allMembers)
-      if (m.isBot) m.pubkey.toLowerCase(),
-  };
+      final botPubkeys = <String>{
+        for (final m in allMembers)
+          if (m.isBot) m.pubkey.toLowerCase(),
+      };
 
-  return <String>{
-    for (final e in typingEntries)
-      if (botPubkeys.contains(e.pubkey.toLowerCase())) e.pubkey.toLowerCase(),
-  };
-});
+      return <String>{
+        for (final e in typingEntries)
+          if (botPubkeys.contains(e.pubkey.toLowerCase()))
+            e.pubkey.toLowerCase(),
+      };
+    });
diff --git a/mobile/lib/features/channels/channel_detail_page.dart b/mobile/lib/features/channels/channel_detail_page.dart
index 7abeed8d7a..044342d101 100644
--- a/mobile/lib/features/channels/channel_detail_page.dart
+++ b/mobile/lib/features/channels/channel_detail_page.dart
@@ -8,6 +8,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
@@ -39,7 +40,6 @@ import 'manage_channel_sheet.dart';
 import 'members_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
-import 'mentions/mention_candidates_provider.dart';
 import 'read_state/deferred_read_state_update.dart';
 import 'read_state/read_state_provider.dart';
 import 'read_state/read_state_time.dart';
diff --git a/mobile/lib/features/channels/channel_detail_page/message_bubble.dart b/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
index fcabfd619a..cb6ab67065 100644
--- a/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
+++ b/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
@@ -36,8 +36,14 @@ class _MessageBubble extends ConsumerWidget {
 
     // Build mention names map from event p-tags.
     final userCache = ref.watch(userCacheProvider);
-    final knownAgentPubkeys = ref.watch(
-      mentionAgentPubkeysProvider(currentChannelId),
+    final knownAgentPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(
+        agentMentionPubkeysProvider(currentChannelId),
+      ),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
     );
     final mentionNames = <String, String>{};
     final agentMentionPubkeys = <String>{};
@@ -51,6 +57,12 @@ class _MessageBubble extends ConsumerWidget {
         agentMentionPubkeys.add(normalizedPubkey);
       }
     }
+    final resolvedMentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: message.mentionPubkeys,
+      profileMentionNames: mentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: EdgeInsets.only(top: showAuthor ? Grid.xs : 0),
@@ -166,7 +178,7 @@ class _MessageBubble extends ConsumerWidget {
                           ),
                         MessageContent(
                           content: message.content,
-                          mentionNames: mentionNames,
+                          mentionNames: resolvedMentionNames,
                           agentMentionPubkeys: agentMentionPubkeys,
                           channelNames: channelNames,
                           tags: message.tags,
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 72554ee1a1..0372690e1e 100644
--- a/mobile/lib/features/channels/channel_detail_page/system_rows.dart
+++ b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
@@ -279,7 +279,12 @@ class _MembershipSystemMessageContent extends StatelessWidget {
       TextSpan(
         text: event.isSelfJoin
             ? 'joined the channel'
-            : 'was added by ${resolveLabel(event.actorPubkey)}',
+            // No "was": the name renders on the line above via
+            // MessageAuthorMeta, so this reads as a status line rather than a
+            // sentence continuing across the metadata row. Matches desktop's
+            // SystemMessageRow. `SystemEvent.describe` keeps "was added by"
+            // because it builds subject and predicate into one string.
+            : 'added by ${resolveLabel(event.actorPubkey)}',
       ),
       if (additionalTargets.isNotEmpty)
         TextSpan(text: event.isSelfJoin ? ' along with ' : ', along with '),
diff --git a/mobile/lib/features/channels/channel_management_provider.dart b/mobile/lib/features/channels/channel_management_provider.dart
index 9a72054a2b..b990194d15 100644
--- a/mobile/lib/features/channels/channel_management_provider.dart
+++ b/mobile/lib/features/channels/channel_management_provider.dart
@@ -7,6 +7,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import '../../shared/auth/auth.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../profile/profile_provider.dart';
 import 'channel.dart';
@@ -392,8 +393,9 @@ final channelDetailsProvider = FutureProvider.family<ChannelDetails, String>((
 });
 
 /// Channel members from kind:39002 NIP-29 members event.
-final channelMembersProvider =
-    FutureProvider.family<List<ChannelMember>, String>((ref, channelId) async {
+final channelMembersProvider = FutureProvider.autoDispose
+    .family<List<ChannelMember>, String>((ref, channelId) async {
+      ref.watch(channelMembershipUpdateProvider(channelId));
       final session = ref.watch(relaySessionProvider.notifier);
       final events = await session.fetchHistory(
         NostrFilters.channelMembers(channelId),
@@ -557,6 +559,7 @@ class ChannelActions {
       );
     }
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> joinChannel(String channelId) async {
@@ -626,6 +629,7 @@ class ChannelActions {
     await _ref.read(channelsProvider.notifier).refresh();
     _ref.invalidate(channelDetailsProvider(channelId));
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
     _ref.invalidate(channelCanvasProvider(channelId));
   }
 
@@ -659,6 +663,7 @@ class ChannelActions {
       ],
     );
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> removeMember({
@@ -674,6 +679,7 @@ class ChannelActions {
       ],
     );
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> addReaction(String eventId, String emoji) async {
diff --git a/mobile/lib/features/channels/channel_messages_provider.dart b/mobile/lib/features/channels/channel_messages_provider.dart
index c03087a85d..fbcbca8956 100644
--- a/mobile/lib/features/channels/channel_messages_provider.dart
+++ b/mobile/lib/features/channels/channel_messages_provider.dart
@@ -2,7 +2,6 @@ import 'package:flutter/foundation.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/relay/relay.dart';
-import 'channel_management_provider.dart';
 import 'pending_local_messages_provider.dart';
 import 'channel_window.dart';
 import 'thread_replies_provider.dart';
@@ -222,11 +221,6 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
       _lastKnownMessages = merged;
       state = AsyncData(merged);
     }
-
-    if (event.kind == EventKind.systemMessage &&
-        _isMembershipEvent(event.content)) {
-      ref.invalidate(channelMembersProvider(channelId));
-    }
   }
 
   void _handleWindowLiveEvent(NostrEvent event) {
@@ -288,12 +282,6 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
         .confirm(eventIds);
   }
 
-  static bool _isMembershipEvent(String content) {
-    return content.contains('member_joined') ||
-        content.contains('member_left') ||
-        content.contains('member_removed');
-  }
-
   /// Adds a just-signed outgoing message before the relay acknowledges it.
   /// The live relay echo is deduplicated by event id.
   void addLocalMessage(NostrEvent event) {
diff --git a/mobile/lib/features/channels/compose_bar.dart b/mobile/lib/features/channels/compose_bar.dart
index 1a9a02e409..7560f998f3 100644
--- a/mobile/lib/features/channels/compose_bar.dart
+++ b/mobile/lib/features/channels/compose_bar.dart
@@ -15,6 +15,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import 'package:nostr/nostr.dart' as nostr;
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
@@ -36,6 +37,7 @@ import 'mentions/mention_ranking.dart';
 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/suggestions.dart';
 part 'compose_bar/formatting_toolbar.dart';
@@ -231,6 +233,16 @@ class ComposeBar extends HookConsumerWidget {
     // 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>[];
diff --git a/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart b/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart
new file mode 100644
index 0000000000..bc29d5bb46
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart
@@ -0,0 +1,10 @@
+part of '../compose_bar.dart';
+
+Set<String> _agentMentionLabels({
+  required Iterable<MentionCandidate> candidates,
+}) {
+  return <String>{
+    for (final candidate in candidates)
+      if (candidate.isAgent) candidate.label,
+  };
+}
diff --git a/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart b/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
index 29e22a8ca9..bbca57037a 100644
--- a/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
+++ b/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
@@ -15,6 +15,8 @@ class _MarkdownRule {
 }
 
 class _MarkdownEditingController extends TextEditingController {
+  final Set<String> _agentMentionNames = <String>{};
+
   static final _rules = [
     _MarkdownRule(
       r'```(?:\r?\n)?([\s\S]*?)(?:\r?\n)?```',
@@ -31,6 +33,21 @@ class _MarkdownEditingController extends TextEditingController {
     _MarkdownRule(r'_([^_\n]*?)_', _MarkdownStyle.italic),
   ];
 
+  /// Updates the known agent labels which should render as agent mention
+  /// chips. The editor still stores the literal `@Name` text, matching the
+  /// markdown sent to the relay.
+  void setAgentMentionNames(Iterable<String> names) {
+    final next = {
+      for (final name in names)
+        if (name.trim().isNotEmpty) name.trim().toLowerCase(),
+    };
+    if (setEquals(_agentMentionNames, next)) return;
+    _agentMentionNames
+      ..clear()
+      ..addAll(next);
+    notifyListeners();
+  }
+
   @override
   TextSpan buildTextSpan({
     required BuildContext context,
@@ -81,6 +98,7 @@ class _MarkdownEditingController extends TextEditingController {
       if (nextRule == null || nextMatch == null) {
         spans.addAll(
           _buildTextSpans(
+            context,
             source.substring(offset),
             inheritedStyle,
             sourceOffset + offset,
@@ -93,6 +111,7 @@ class _MarkdownEditingController extends TextEditingController {
       if (nextMatch.start > 0) {
         spans.addAll(
           _buildTextSpans(
+            context,
             tail.substring(0, nextMatch.start),
             inheritedStyle,
             sourceOffset + offset,
@@ -129,10 +148,12 @@ class _MarkdownEditingController extends TextEditingController {
       } else {
         spans.addAll(
           _buildTextSpans(
+            context,
             content,
             contentStyle,
             matchOffset + contentStart,
             composingRange,
+            renderAgentMentions: false,
           ),
         );
       }
@@ -150,11 +171,18 @@ class _MarkdownEditingController extends TextEditingController {
   }
 
   List<InlineSpan> _buildTextSpans(
+    BuildContext context,
     String source,
     TextStyle style,
     int sourceOffset,
-    TextRange composingRange,
-  ) {
+    TextRange composingRange, {
+    bool renderAgentMentions = true,
+  }) {
+    List<InlineSpan> buildTextSegment(String text, TextStyle segmentStyle) =>
+        renderAgentMentions
+        ? _buildAgentMentionSpans(context, text, segmentStyle)
+        : [TextSpan(text: text, style: segmentStyle)];
+
     if (source.isEmpty) return const [];
     final localStart = (composingRange.start - sourceOffset)
         .clamp(0, source.length)
@@ -165,7 +193,7 @@ class _MarkdownEditingController extends TextEditingController {
     if (!composingRange.isValid ||
         composingRange.isCollapsed ||
         localStart >= localEnd) {
-      return [TextSpan(text: source, style: style)];
+      return buildTextSegment(source, style);
     }
 
     final composingDecorations = [
@@ -178,16 +206,80 @@ class _MarkdownEditingController extends TextEditingController {
     );
     return [
       if (localStart > 0)
-        TextSpan(text: source.substring(0, localStart), style: style),
+        ...buildTextSegment(source.substring(0, localStart), style),
       TextSpan(
         text: source.substring(localStart, localEnd),
         style: composingStyle,
       ),
       if (localEnd < source.length)
-        TextSpan(text: source.substring(localEnd), style: style),
+        ...buildTextSegment(source.substring(localEnd), style),
     ];
   }
 
+  List<InlineSpan> _buildAgentMentionSpans(
+    BuildContext context,
+    String source,
+    TextStyle style,
+  ) {
+    if (_agentMentionNames.isEmpty) {
+      return [TextSpan(text: source, style: style)];
+    }
+
+    final escapedNames = _agentMentionNames.toList()
+      ..sort((a, b) => b.length.compareTo(a.length));
+    final expression = RegExp(
+      r'(^|\s)@(' +
+          escapedNames.map(RegExp.escape).join('|') +
+          r')(?=\s|[,.!?:;)\]}*_]|$)',
+      caseSensitive: false,
+      multiLine: true,
+    );
+    final spans = <InlineSpan>[];
+    var offset = 0;
+    for (final match in expression.allMatches(source)) {
+      final prefix = match.group(1)!;
+      if (match.start > offset) {
+        spans.add(
+          TextSpan(text: source.substring(offset, match.start), style: style),
+        );
+      }
+      if (prefix.isNotEmpty) spans.add(TextSpan(text: prefix, style: style));
+
+      final label = match.group(2)!;
+      spans.add(
+        WidgetSpan(
+          alignment: PlaceholderAlignment.baseline,
+          baseline: TextBaseline.alphabetic,
+          child: _ComposerAgentMentionChip(label: label, textStyle: style),
+        ),
+      );
+      // The visual chip replaces the `@` placeholder. Keep the label as
+      // invisible source text so the text span still has one character per
+      // source character, preserving native cursor and deletion behavior.
+      spans.add(
+        TextSpan(
+          text: label,
+          semanticsLabel: '',
+          style: _hiddenMentionTextStyle(style),
+        ),
+      );
+      offset = match.end;
+    }
+    if (offset < source.length) {
+      spans.add(TextSpan(text: source.substring(offset), style: style));
+    }
+    return spans.isEmpty ? [TextSpan(text: source, style: style)] : spans;
+  }
+
+  TextStyle _hiddenMentionTextStyle(TextStyle inheritedStyle) =>
+      inheritedStyle.copyWith(
+        color: Colors.transparent,
+        fontSize: 0.01,
+        height: 0.01,
+        letterSpacing: 0,
+        decoration: TextDecoration.none,
+      );
+
   (int, int) _contentBounds(String fullMatch, _MarkdownStyle markdownStyle) {
     final delimiterLength = switch (markdownStyle) {
       _MarkdownStyle.bold || _MarkdownStyle.strikethrough => 2,
@@ -247,3 +339,60 @@ class _MarkdownEditingController extends TextEditingController {
     );
   }
 }
+
+class _ComposerAgentMentionChip extends StatelessWidget {
+  final String label;
+  final TextStyle textStyle;
+
+  const _ComposerAgentMentionChip({
+    required this.label,
+    required this.textStyle,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final style = textStyle.copyWith(
+      color: context.colors.primary,
+      fontWeight: FontWeight.w500,
+      height: 1,
+    );
+    final fontSize = style.fontSize ?? 16;
+
+    return Semantics(
+      label: 'Agent mention: $label',
+      excludeSemantics: true,
+      child: Container(
+        key: const ValueKey('composer-agent-mention-chip'),
+        padding: const EdgeInsets.fromLTRB(
+          Grid.half,
+          Grid.quarter + 1,
+          Grid.half,
+          Grid.quarter,
+        ),
+        decoration: BoxDecoration(
+          // The composer surface is already tinted, so the body chip's
+          // low-opacity fill disappears here. Keep the same chip geometry
+          // while giving this editable token enough contrast to read as one.
+          color: context.colors.primary.withValues(alpha: 0.16),
+          borderRadius: BorderRadius.circular(Radii.sm),
+          border: Border.all(
+            color: context.colors.primary.withValues(alpha: 0.12),
+          ),
+        ),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.center,
+          children: [
+            Icon(
+              LucideIcons.bot,
+              size: fontSize * 0.95,
+              color: context.colors.primary,
+            ),
+            const SizedBox(width: Grid.quarter),
+            Text(label, style: style),
+          ],
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/mentions/mention_candidates.dart b/mobile/lib/features/channels/mentions/mention_candidates.dart
index ca97d65e34..9c4ef96bbe 100644
--- a/mobile/lib/features/channels/mentions/mention_candidates.dart
+++ b/mobile/lib/features/channels/mentions/mention_candidates.dart
@@ -1,59 +1,8 @@
-import 'dart:convert';
-
-import '../../../shared/relay/nostr_models.dart';
+import '../../../shared/mentions/agent_identity_provider.dart';
 import '../../profile/user_profile.dart';
 import '../channel_management_provider.dart';
 import 'mention_ranking.dart';
 
-/// A relay agent parsed from its kind:10100 agent-profile event.
-///
-/// Mirrors the fields desktop's `RelayAgent` uses for mention eligibility
-/// (`agentAutocompleteEligibility.ts`): who the agent responds to and which
-/// channels it sits in.
-class AgentDirectoryEntry {
-  final String pubkey;
-  final String? displayName;
-  final String? respondTo;
-  final List<String> respondToAllowlist;
-  final List<String> channelIds;
-
-  const AgentDirectoryEntry({
-    required this.pubkey,
-    this.displayName,
-    this.respondTo,
-    this.respondToAllowlist = const [],
-    this.channelIds = const [],
-  });
-
-  factory AgentDirectoryEntry.fromEvent(NostrEvent event) {
-    final content = _tryDecodeJsonMap(event.content);
-    return AgentDirectoryEntry(
-      pubkey: event.pubkey.toLowerCase(),
-      displayName:
-          (content?['display_name'] as String?) ??
-          (content?['name'] as String?),
-      respondTo: content?['respond_to'] as String?,
-      respondToAllowlist: [
-        for (final value in (content?['respond_to_allowlist'] as List?) ?? [])
-          if (value is String) value.toLowerCase(),
-      ],
-      channelIds: [
-        for (final value in (content?['channel_ids'] as List?) ?? [])
-          if (value is String) value,
-      ],
-    );
-  }
-}
-
-Map<String, dynamic>? _tryDecodeJsonMap(String content) {
-  try {
-    final decoded = jsonDecode(content);
-    return decoded is Map<String, dynamic> ? decoded : null;
-  } catch (_) {
-    return null;
-  }
-}
-
 /// Whether a non-member relay agent should be mentionable by the current
 /// user. Mirrors desktop's `relayAgentIsSharedWithUser`:
 /// - allowlist mode: user must be on the allowlist
diff --git a/mobile/lib/features/channels/mentions/mention_candidates_provider.dart b/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
index c2aa056a05..6e94459231 100644
--- a/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
+++ b/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
@@ -1,6 +1,7 @@
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../../shared/crypto/nip_oa.dart';
+import '../../../shared/mentions/agent_identity_provider.dart';
 import '../../../shared/relay/relay.dart';
 import '../../profile/user_cache_provider.dart';
 import '../../profile/user_profile.dart';
@@ -10,64 +11,6 @@ import '../channels_provider.dart';
 import 'mention_candidates.dart';
 import 'mention_ranking.dart';
 
-/// Relay agent directory from kind:10100 agent-profile events.
-///
-/// Watches the session and only fetches after the WebSocket connects.
-final agentDirectoryProvider = FutureProvider<List<AgentDirectoryEntry>>((
-  ref,
-) async {
-  final sessionState = ref.watch(relaySessionProvider);
-  if (sessionState.status != SessionStatus.connected) return const [];
-  final session = ref.read(relaySessionProvider.notifier);
-  final events = await session.fetchHistory(NostrFilters.agentProfiles());
-  return [for (final event in events) AgentDirectoryEntry.fromEvent(event)];
-});
-
-/// Verified NIP-OA owner pubkey per agent pubkey, from the agents' kind:0
-/// profiles. An entry exists only when the `auth` tag verifies — mirrors
-/// desktop's `profile_valid_oa_owner_pubkey`.
-final agentOwnersProvider = FutureProvider<Map<String, String>>((ref) async {
-  final agents = await ref.watch(agentDirectoryProvider.future);
-  if (agents.isEmpty) return const {};
-  final session = ref.read(relaySessionProvider.notifier);
-  final events = await session.fetchHistory(
-    NostrFilters.profilesBatch([for (final agent in agents) agent.pubkey]),
-  );
-  final owners = <String, String>{};
-  for (final event in events) {
-    final owner = verifiedOaOwnerPubkey(event.tags, event.pubkey);
-    if (owner != null) owners[event.pubkey.toLowerCase()] = owner;
-  }
-  return owners;
-});
-
-/// Pubkeys currently known to represent agents for rendered mention chips.
-///
-/// Uses the same three identity sources as mention autocomplete: channel bot
-/// roles, relay agent-directory entries, and verified NIP-OA ownership.
-final mentionAgentPubkeysProvider = Provider.family<Set<String>, String>((
-  ref,
-  channelId,
-) {
-  final members =
-      ref.watch(channelMembersProvider(channelId)).asData?.value ??
-      const <ChannelMember>[];
-  final relayAgents =
-      ref.watch(agentDirectoryProvider).asData?.value ??
-      const <AgentDirectoryEntry>[];
-  final owners = ref.watch(agentOwnersProvider).asData?.value ?? const {};
-  final userCache = ref.watch(userCacheProvider);
-
-  return {
-    for (final member in members)
-      if (member.isBot) member.pubkey.toLowerCase(),
-    for (final agent in relayAgents) agent.pubkey.toLowerCase(),
-    ...owners.keys.map((pubkey) => pubkey.toLowerCase()),
-    for (final profile in userCache.values)
-      if (profile.ownerPubkey != null) profile.pubkey.toLowerCase(),
-  };
-});
-
 /// Debounce before a mention query hits the relay search endpoint.
 const _mentionSearchDebounce = Duration(milliseconds: 250);
 
diff --git a/mobile/lib/features/channels/message_content.dart b/mobile/lib/features/channels/message_content.dart
index ab992a4314..465585d966 100644
--- a/mobile/lib/features/channels/message_content.dart
+++ b/mobile/lib/features/channels/message_content.dart
@@ -145,6 +145,10 @@ class MessageContent extends HookConsumerWidget {
     final baseTextStyle =
         baseStyle ??
         context.textTheme.bodyMedium?.copyWith(color: context.colors.onSurface);
+    final resolvedMentionNames = mentionNames;
+    final resolvedAgentMentionPubkeys = {
+      ...agentMentionPubkeys.map((pubkey) => pubkey.toLowerCase()),
+    };
     final imetaByUrl = parseImetaTags(tags);
     final trailingGallery = maxLines == null
         ? _extractTrailingImageGallery(content, imetaByUrl)
@@ -154,6 +158,13 @@ class MessageContent extends HookConsumerWidget {
       customEmojiFromTags(tags),
       ref.watch(customEmojiListProvider),
     );
+    final mentionPresentationKey = [
+      for (final entry
+          in (resolvedMentionNames.entries.toList()
+            ..sort((a, b) => a.key.compareTo(b.key))))
+        '${entry.key}\u0000${entry.value}',
+      ...(resolvedAgentMentionPubkeys.toList()..sort()),
+    ].join('\u0001');
 
     // Decided here rather than by the caller: this is where the event's own
     // emoji tags and the community palette have already been merged, and a
@@ -220,7 +231,7 @@ class MessageContent extends HookConsumerWidget {
           mentionBuf.write('`${mentionParts[i]}`');
         } else {
           var segment = mentionParts[i];
-          for (final name in mentionNames.values) {
+          for (final name in resolvedMentionNames.values) {
             if (name.contains(' ')) {
               final normalizedName = _markdownMentionName(name);
               segment = segment.replaceAllMapped(
@@ -241,29 +252,35 @@ class MessageContent extends HookConsumerWidget {
         result = '\u200B$result';
       }
       return result;
-    }, [markdownContent, mentionNames]);
-
-    final markdown = GptMarkdown(
-      finalContent,
-      style: style,
-      followLinkColor: false,
-      codeBuilder: (context, name, code, closed) =>
-          _MessageCodeBlock(name: name, code: code),
-      linkBuilder: (context, linkText, url, linkStyle) =>
-          _buildLink(context, ref, linkText, url, linkStyle, style),
-      imageBuilder: (context, imageUrl) =>
-          _buildMedia(context, imageUrl, imetaByUrl[imageUrl]),
-      maxLines: maxLines,
-      inlineComponents: [
-        _MentionMd(
-          mentionNames: mentionNames,
-          agentMentionPubkeys: agentMentionPubkeys,
-          onMentionTap: onMentionTap,
-        ),
-        CustomEmojiMd(customEmoji, size: inlineCustomEmojiSize),
-        _ChannelLinkMd(channelNames: channelNames, onChannelTap: onChannelTap),
-        ...MarkdownComponent.inlineComponents,
-      ],
+    }, [markdownContent, resolvedMentionNames]);
+
+    final markdown = KeyedSubtree(
+      key: ValueKey('$finalContent\u0000$mentionPresentationKey'),
+      child: GptMarkdown(
+        finalContent,
+        style: style,
+        followLinkColor: false,
+        codeBuilder: (context, name, code, closed) =>
+            _MessageCodeBlock(name: name, code: code),
+        linkBuilder: (context, linkText, url, linkStyle) =>
+            _buildLink(context, ref, linkText, url, linkStyle, style),
+        imageBuilder: (context, imageUrl) =>
+            _buildMedia(context, imageUrl, imetaByUrl[imageUrl]),
+        maxLines: maxLines,
+        inlineComponents: [
+          _MentionMd(
+            mentionNames: resolvedMentionNames,
+            agentMentionPubkeys: resolvedAgentMentionPubkeys,
+            onMentionTap: onMentionTap,
+          ),
+          CustomEmojiMd(customEmoji, size: inlineCustomEmojiSize),
+          _ChannelLinkMd(
+            channelNames: channelNames,
+            onChannelTap: onChannelTap,
+          ),
+          ...MarkdownComponent.inlineComponents,
+        ],
+      ),
     );
     if (trailingGallery == null) return markdown;
 
diff --git a/mobile/lib/features/channels/thread_detail_page.dart b/mobile/lib/features/channels/thread_detail_page.dart
index 5d28214b01..810861aa00 100644
--- a/mobile/lib/features/channels/thread_detail_page.dart
+++ b/mobile/lib/features/channels/thread_detail_page.dart
@@ -3,6 +3,7 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
@@ -24,7 +25,6 @@ import 'day_divider.dart';
 import '../profile/user_profile_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
-import 'mentions/mention_candidates_provider.dart';
 import 'reaction_row.dart';
 import 'read_state/read_state_format.dart';
 import 'read_state/read_state_provider.dart';
@@ -607,7 +607,13 @@ class _ThreadMessage extends ConsumerWidget {
             profile?.ownerPubkey == currentPubkey?.toLowerCase());
 
     final userCache = ref.watch(userCacheProvider);
-    final knownAgentPubkeys = ref.watch(mentionAgentPubkeysProvider(channelId));
+    final knownAgentPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
     final mentionNames = <String, String>{};
     final agentMentionPubkeys = <String>{};
     for (final mpk in message.mentionPubkeys) {
@@ -620,6 +626,12 @@ class _ThreadMessage extends ConsumerWidget {
         agentMentionPubkeys.add(normalizedPubkey);
       }
     }
+    final resolvedMentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: message.mentionPubkeys,
+      profileMentionNames: mentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: EdgeInsets.only(top: showAuthor ? Grid.xs : 0),
@@ -725,7 +737,7 @@ class _ThreadMessage extends ConsumerWidget {
                             ),
                           MessageContent(
                             content: message.content,
-                            mentionNames: mentionNames,
+                            mentionNames: resolvedMentionNames,
                             agentMentionPubkeys: agentMentionPubkeys,
                             channelNames: channelNames,
                             tags: message.tags,
diff --git a/mobile/lib/features/channels/timeline_message.dart b/mobile/lib/features/channels/timeline_message.dart
index 253c949703..c8fd96491b 100644
--- a/mobile/lib/features/channels/timeline_message.dart
+++ b/mobile/lib/features/channels/timeline_message.dart
@@ -101,9 +101,10 @@ class SystemEvent {
         final target = resolveLabel(targetPubkey);
         return '$actor removed $target from the channel';
       }(),
-      SystemEventType.topicChanged => '$actor changed the topic to "$topic"',
+      SystemEventType.topicChanged =>
+        '$actor ${_describeTextFieldChange('topic', topic)}',
       SystemEventType.purposeChanged =>
-        '$actor changed the purpose to "$purpose"',
+        '$actor ${_describeTextFieldChange('purpose', purpose)}',
       SystemEventType.channelCreated => '$actor created this channel',
       SystemEventType.channelArchived => '$actor archived this channel',
       SystemEventType.channelUnarchived => '$actor unarchived this channel',
@@ -113,6 +114,25 @@ class SystemEvent {
   }
 }
 
+/// Caption fragment for a channel topic or purpose change, e.g.
+/// `changed the topic to "Release planning"` or `cleared the topic`.
+///
+/// A blank value means the field was cleared: the relay reports a clear as a
+/// `topic_changed` / `purpose_changed` event carrying an empty string, not as a
+/// separate event type. Without this branch the timeline renders
+/// `changed the topic to ""`, which reads as if the topic were set to two quote
+/// marks. Whitespace-only values are treated as cleared for the same reason.
+///
+/// Mirrors `describeChannelTextFieldChange` in
+/// `desktop/src/features/messages/lib/systemEventCopy.ts`.
+String _describeTextFieldChange(String field, String? value) {
+  final trimmed = value?.trim();
+  if (trimmed == null || trimmed.isEmpty) {
+    return 'cleared the $field';
+  }
+  return 'changed the $field to "$trimmed"';
+}
+
 @immutable
 class TimelineReaction {
   final String emoji;
diff --git a/mobile/lib/features/forum/forum_post_card.dart b/mobile/lib/features/forum/forum_post_card.dart
index 8666919a4a..ddc36a1d4a 100644
--- a/mobile/lib/features/forum/forum_post_card.dart
+++ b/mobile/lib/features/forum/forum_post_card.dart
@@ -1,8 +1,10 @@
 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/mentions/agent_identity_provider.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../channels/message_content.dart';
@@ -15,7 +17,7 @@ import 'forum_models.dart';
 ///
 /// Long-press opens an action sheet (copy, delete) matching the stream
 /// message pattern from channel_detail_page.dart.
-class ForumPostCard extends ConsumerWidget {
+class ForumPostCard extends HookConsumerWidget {
   final ForumPost post;
   final String? currentPubkey;
   final VoidCallback onTap;
@@ -31,16 +33,57 @@ class ForumPostCard extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final mentionPubkeys = useMemoized(
+      () =>
+          post.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()).toSet()
+            ..remove(post.pubkey.toLowerCase()),
+      [post],
+    );
+    final mentionPubkeysKey = (mentionPubkeys.toList()..sort()).join('\u0000');
+
+    useEffect(() {
+      if (mentionPubkeys.isNotEmpty) {
+        ref.read(userCacheProvider.notifier).preload(mentionPubkeys.toList());
+      }
+      return null;
+    }, [mentionPubkeysKey]);
+
     final pk = post.pubkey.toLowerCase();
     final profile =
         ref.watch(userCacheProvider.select((cache) => cache[pk])) ??
         ref.read(userCacheProvider.notifier).get(pk);
     final displayName = profile?.label ?? _shortPubkey(post.pubkey);
-    final mentionNames = ref.watch(
+    final profileMentionNames = ref.watch(
       userCacheProvider.select(
         (cache) => _buildMentionNames(post.mentionPubkeys, cache),
       ),
     );
+    final profileOwnedMentionPubkeys = ref.watch(
+      userCacheProvider.select(
+        (cache) =>
+            (post.mentionPubkeys
+                    .where(
+                      (pubkey) =>
+                          cache[pubkey.toLowerCase()]?.ownerPubkey != null,
+                    )
+                    .map((pubkey) => pubkey.toLowerCase())
+                    .toList()
+                  ..sort())
+                .join('\u0000'),
+      ),
+    );
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(post.channelId)),
+      profileOwnedAgentPubkeys: profileOwnedMentionPubkeys.isEmpty
+          ? const <String>[]
+          : profileOwnedMentionPubkeys.split('\u0000'),
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: post.mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
     final preview = post.content.length > 200
         ? '${post.content.substring(0, 200)}...'
         : post.content;
@@ -128,6 +171,7 @@ class ForumPostCard extends ConsumerWidget {
                   child: MessageContent(
                     content: preview,
                     mentionNames: mentionNames,
+                    agentMentionPubkeys: agentMentionPubkeys,
                     tags: post.tags,
                     baseStyle: messageBodyTextStyle.copyWith(
                       color: context.colors.onSurface,
diff --git a/mobile/lib/features/forum/forum_thread_page.dart b/mobile/lib/features/forum/forum_thread_page.dart
index d2e8490d61..68d2562f68 100644
--- a/mobile/lib/features/forum/forum_thread_page.dart
+++ b/mobile/lib/features/forum/forum_thread_page.dart
@@ -6,6 +6,7 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 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/buzz_loading_indicator.dart';
@@ -209,21 +210,27 @@ class _ThreadContent extends HookConsumerWidget {
     final post = thread.post;
     final replies = thread.replies;
 
-    // Preload profiles for all participants.
+    // Preload profiles for all participants and tagged mentions.
     final allPubkeys = useMemoized(() {
-      final pks = <String>{post.pubkey};
+      final pks = <String>{
+        post.pubkey.toLowerCase(),
+        ...post.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()),
+      };
       for (final reply in replies) {
-        pks.add(reply.pubkey);
+        pks
+          ..add(reply.pubkey.toLowerCase())
+          ..addAll(reply.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()));
       }
-      return pks.toList();
+      return pks.toList()..sort();
     }, [post, replies]);
+    final allPubkeysKey = allPubkeys.join('\u0000');
 
     useEffect(() {
       if (allPubkeys.isNotEmpty) {
         ref.read(userCacheProvider.notifier).preload(allPubkeys);
       }
       return null;
-    }, [allPubkeys]);
+    }, [allPubkeysKey]);
 
     return Column(
       children: [
@@ -322,7 +329,19 @@ class _OriginalPost extends ConsumerWidget {
     final displayName = profile?.label ?? _shortPubkey(post.pubkey);
 
     final userCache = ref.watch(userCacheProvider);
-    final mentionNames = _buildMentionNames(post.mentionPubkeys, userCache);
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(post.channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: post.mentionPubkeys,
+      profileMentionNames: _buildMentionNames(post.mentionPubkeys, userCache),
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: const EdgeInsets.all(Grid.xs),
@@ -375,6 +394,7 @@ class _OriginalPost extends ConsumerWidget {
           MessageContent(
             content: post.content,
             mentionNames: mentionNames,
+            agentMentionPubkeys: agentMentionPubkeys,
             tags: post.tags,
             baseStyle: messageBodyTextStyle.copyWith(
               color: context.colors.onSurface,
@@ -409,7 +429,19 @@ class _ReplyRow extends ConsumerWidget {
     final displayName = profile?.label ?? _shortPubkey(reply.pubkey);
 
     final userCache = ref.watch(userCacheProvider);
-    final mentionNames = _buildMentionNames(reply.mentionPubkeys, userCache);
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: reply.mentionPubkeys,
+      profileMentionNames: _buildMentionNames(reply.mentionPubkeys, userCache),
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: const EdgeInsets.symmetric(
@@ -481,6 +513,7 @@ class _ReplyRow extends ConsumerWidget {
             child: MessageContent(
               content: reply.content,
               mentionNames: mentionNames,
+              agentMentionPubkeys: agentMentionPubkeys,
               tags: reply.tags,
               baseStyle: messageBodyTextStyle.copyWith(
                 color: context.colors.onSurface,
diff --git a/mobile/lib/features/search/search_page.dart b/mobile/lib/features/search/search_page.dart
index b608b65aef..65fc12dfd9 100644
--- a/mobile/lib/features/search/search_page.dart
+++ b/mobile/lib/features/search/search_page.dart
@@ -3,6 +3,8 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/mentions/mention_tags.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
@@ -597,7 +599,7 @@ class _PeopleSection extends ConsumerWidget {
   }
 }
 
-class _MessagesSection extends ConsumerWidget {
+class _MessagesSection extends HookConsumerWidget {
   final List<SearchHit> hits;
   final String? currentPubkey;
   final VoidCallback onResultSelected;
@@ -614,8 +616,15 @@ class _MessagesSection extends ConsumerWidget {
     final channels = ref.watch(channelsProvider).value ?? [];
 
     // Preload author profiles.
-    final pubkeys = hits.map((h) => h.pubkey.toLowerCase()).toSet().toList();
-    ref.read(userCacheProvider.notifier).preload(pubkeys);
+    final preloadPubkeys = {
+      for (final hit in hits) hit.pubkey.toLowerCase(),
+      for (final hit in hits) ...mentionedPubkeysFromTags(hit.tags),
+    }.toList()..sort();
+    final preloadPubkeysKey = preloadPubkeys.join('\u0000');
+    useEffect(() {
+      ref.read(userCacheProvider.notifier).preload(preloadPubkeys);
+      return null;
+    }, [preloadPubkeysKey]);
 
     return Column(
       crossAxisAlignment: CrossAxisAlignment.start,
@@ -635,7 +644,7 @@ class _MessagesSection extends ConsumerWidget {
   }
 }
 
-class _MessageTile extends StatelessWidget {
+class _MessageTile extends ConsumerWidget {
   final SearchHit hit;
   final UserProfile? authorProfile;
   final Map<String, UserProfile> userCache;
@@ -653,12 +662,34 @@ class _MessageTile extends StatelessWidget {
   });
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final authorName = authorProfile?.label ?? shortPubkey(hit.pubkey);
     final timeAgo = relativeTime(hit.createdAt);
     final channelName = hit.channelName?.trim().replaceFirst(RegExp(r'^#'), '');
     final hasChannelName = channelName != null && channelName.isNotEmpty;
     final isDm = channel?.isDm ?? false;
+    final profileMentionNames = {
+      for (final pubkey in mentionedPubkeysFromTags(hit.tags))
+        if (userCache[pubkey]?.displayName?.trim().isNotEmpty == true)
+          pubkey: userCache[pubkey]!.displayName!.trim(),
+    };
+    final mentionPubkeys = mentionedPubkeysFromTags(hit.tags);
+    final knownAgentPubkeys = channel == null
+        ? ref.watch(knownAgentPubkeysProvider)
+        : ref.watch(agentMentionPubkeysProvider(channel!.id));
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: knownAgentPubkeys,
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return ListTile(
       key: ValueKey('search-message-row-${hit.eventId}'),
@@ -730,6 +761,8 @@ class _MessageTile extends StatelessWidget {
           MessageContent(
             key: ValueKey('search-message-body-${hit.eventId}'),
             content: hit.content,
+            mentionNames: mentionNames,
+            agentMentionPubkeys: agentMentionPubkeys,
             tags: hit.tags,
             maxLines: 2,
             baseStyle: activityPreviewTextStyle.copyWith(
diff --git a/mobile/lib/shared/mentions/agent_identity_provider.dart b/mobile/lib/shared/mentions/agent_identity_provider.dart
new file mode 100644
index 0000000000..ea6a2ee50f
--- /dev/null
+++ b/mobile/lib/shared/mentions/agent_identity_provider.dart
@@ -0,0 +1,274 @@
+import 'dart:collection';
+import 'dart:convert';
+
+import 'package:flutter/foundation.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import '../../shared/crypto/nip_oa.dart';
+import '../../shared/relay/relay.dart';
+
+/// A relay agent parsed from its kind:10100 agent-profile event.
+///
+/// Mirrors the fields desktop's `RelayAgent` uses for mention eligibility
+/// (`agentAutocompleteEligibility.ts`): who the agent responds to and which
+/// channels it sits in.
+class AgentDirectoryEntry {
+  final String pubkey;
+  final String? displayName;
+  final String? respondTo;
+  final List<String> respondToAllowlist;
+  final List<String> channelIds;
+
+  const AgentDirectoryEntry({
+    required this.pubkey,
+    this.displayName,
+    this.respondTo,
+    this.respondToAllowlist = const [],
+    this.channelIds = const [],
+  });
+
+  factory AgentDirectoryEntry.fromEvent(NostrEvent event) {
+    final content = _tryDecodeJsonMap(event.content);
+    return AgentDirectoryEntry(
+      pubkey: event.pubkey.toLowerCase(),
+      displayName:
+          (content?['display_name'] as String?) ??
+          (content?['name'] as String?),
+      respondTo: content?['respond_to'] as String?,
+      respondToAllowlist: [
+        for (final value in (content?['respond_to_allowlist'] as List?) ?? [])
+          if (value is String) value.toLowerCase(),
+      ],
+      channelIds: [
+        for (final value in (content?['channel_ids'] as List?) ?? [])
+          if (value is String) value,
+      ],
+    );
+  }
+}
+
+Map<String, dynamic>? _tryDecodeJsonMap(String content) {
+  try {
+    final decoded = jsonDecode(content);
+    return decoded is Map<String, dynamic> ? decoded : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/// Relay agent directory from kind:10100 agent-profile events.
+///
+/// Watches the session and only fetches after the WebSocket connects.
+final agentDirectoryProvider = FutureProvider<List<AgentDirectoryEntry>>((
+  ref,
+) async {
+  final sessionState = ref.watch(relaySessionProvider);
+  if (sessionState.status != SessionStatus.connected) return const [];
+  final session = ref.read(relaySessionProvider.notifier);
+  final events = await session.fetchHistory(NostrFilters.agentProfiles());
+  return [for (final event in events) AgentDirectoryEntry.fromEvent(event)];
+});
+
+/// Verified NIP-OA owner pubkey per agent pubkey, from the agents' kind:0
+/// profiles. An entry exists only when the `auth` tag verifies — mirrors
+/// desktop's `profile_valid_oa_owner_pubkey`.
+final agentOwnersProvider = FutureProvider<Map<String, String>>((ref) async {
+  final agents = await ref.watch(agentDirectoryProvider.future);
+  if (agents.isEmpty) return const {};
+  final session = ref.read(relaySessionProvider.notifier);
+  final events = await session.fetchHistory(
+    NostrFilters.profilesBatch([for (final agent in agents) agent.pubkey]),
+  );
+  final owners = <String, String>{};
+  for (final event in events) {
+    final owner = verifiedOaOwnerPubkey(event.tags, event.pubkey);
+    if (owner != null) owners[event.pubkey.toLowerCase()] = owner;
+  }
+  return owners;
+});
+
+/// Pubkeys currently known to represent agents across the active relay.
+///
+/// Message surfaces that do not own channel membership can use this shared
+/// identity source; channel features add their bot roles separately.
+final knownAgentPubkeysProvider = Provider<Set<String>>((ref) {
+  final relayAgents =
+      ref.watch(agentDirectoryProvider).asData?.value ??
+      const <AgentDirectoryEntry>[];
+  final owners = ref.watch(agentOwnersProvider).asData?.value ?? const {};
+  return _AgentPubkeySet({
+    for (final agent in relayAgents) agent.pubkey.toLowerCase(),
+    ...owners.keys.map((pubkey) => pubkey.toLowerCase()),
+  });
+});
+
+/// Directory display names keyed by agent pubkey for mention presentation.
+final agentDirectoryDisplayNamesProvider = Provider<Map<String, String>>((ref) {
+  final agents =
+      ref.watch(agentDirectoryProvider).asData?.value ??
+      const <AgentDirectoryEntry>[];
+  return Map.unmodifiable({
+    for (final agent in agents)
+      if (agent.displayName?.trim().isNotEmpty == true)
+        agent.pubkey.toLowerCase(): agent.displayName!.trim(),
+  });
+});
+
+/// Adds channel bot roles to relay-wide agent identities.
+Set<String> agentPubkeysWithChannelBots({
+  required Set<String> knownAgentPubkeys,
+  required Iterable<String> channelBotPubkeys,
+}) => _AgentPubkeySet({
+  ...knownAgentPubkeys,
+  ...channelBotPubkeys.map((pubkey) => pubkey.toLowerCase()),
+});
+
+/// Adds agent identities derived from locally cached verified profiles.
+Set<String> agentPubkeysWithProfileOwners({
+  required Set<String> knownAgentPubkeys,
+  required Iterable<String> profileOwnedAgentPubkeys,
+}) => _AgentPubkeySet({
+  ...knownAgentPubkeys,
+  ...profileOwnedAgentPubkeys.map((pubkey) => pubkey.toLowerCase()),
+});
+
+/// Preserves profile labels while filling missing agent mentions from the
+/// relay's agent directory.
+Map<String, String> mentionNamesWithDirectoryLabels({
+  required Iterable<String> mentionPubkeys,
+  required Map<String, String> profileMentionNames,
+  required Map<String, String> directoryDisplayNames,
+  required Set<String> agentMentionPubkeys,
+}) {
+  final names = Map<String, String>.from(profileMentionNames);
+  for (final pubkey in mentionPubkeys) {
+    final normalizedPubkey = pubkey.toLowerCase();
+    if (names[normalizedPubkey]?.trim().isEmpty == true) {
+      names.remove(normalizedPubkey);
+    }
+    final directoryName = directoryDisplayNames[normalizedPubkey];
+    if (!names.containsKey(normalizedPubkey) && directoryName != null) {
+      names[normalizedPubkey] = directoryName;
+    }
+    if (!names.containsKey(normalizedPubkey) &&
+        agentMentionPubkeys.contains(normalizedPubkey)) {
+      names[normalizedPubkey] = _agentFallbackLabel(normalizedPubkey);
+    }
+  }
+  return names;
+}
+
+String _agentFallbackLabel(String pubkey) =>
+    pubkey.length >= 8 ? pubkey.substring(0, 8) : pubkey;
+
+/// Keeps the role feed alive for consumers that render mentions outside the
+/// channel timeline, such as search results. A membership change refreshes the
+/// shared bot-role lookup below, regardless of which surface owns the channel.
+class _ChannelBotRoleSubscription extends Notifier<int> {
+  final String channelId;
+  void Function()? _unsubscribe;
+  int _subscriptionVersion = 0;
+
+  _ChannelBotRoleSubscription(this.channelId);
+
+  @override
+  int build() {
+    final sessionState = ref.watch(relaySessionProvider);
+    final subscriptionVersion = ++_subscriptionVersion;
+    _clearSubscription();
+    ref.onDispose(() {
+      _subscriptionVersion++;
+      _clearSubscription();
+    });
+
+    if (sessionState.status != SessionStatus.connected) return 0;
+    Future.microtask(() => _subscribe(channelId, subscriptionVersion));
+    return 0;
+  }
+
+  Future<void> _subscribe(String channelId, int subscriptionVersion) async {
+    final session = ref.read(relaySessionProvider.notifier);
+    try {
+      final unsubscribe = await session.subscribe(
+        NostrFilter(
+          kinds: const [39002],
+          tags: {
+            '#h': [channelId],
+          },
+        ).copyWithSince(DateTime.now().millisecondsSinceEpoch ~/ 1000),
+        (_) {
+          if (_isCurrent(subscriptionVersion)) {
+            state++;
+          }
+        },
+      );
+      if (!_isCurrent(subscriptionVersion)) {
+        unsubscribe();
+        return;
+      }
+      _unsubscribe = unsubscribe;
+    } catch (error) {
+      if (_isCurrent(subscriptionVersion)) {
+        debugPrint(
+          '[ChannelBotRoleSubscription] failed for $channelId: $error',
+        );
+      }
+    }
+  }
+
+  bool _isCurrent(int subscriptionVersion) =>
+      subscriptionVersion == _subscriptionVersion;
+
+  void _clearSubscription() {
+    _unsubscribe?.call();
+    _unsubscribe = null;
+  }
+}
+
+/// Monotonically increments when the channel's kind:39002 membership snapshot
+/// changes. Channel-member and agent-role views share this source so remote
+/// membership updates refresh both snapshots together.
+final channelMembershipUpdateProvider = NotifierProvider.autoDispose
+    .family<_ChannelBotRoleSubscription, int, String>(
+      _ChannelBotRoleSubscription.new,
+    );
+
+/// Bot pubkeys currently assigned a channel bot role.
+final channelBotPubkeysProvider = FutureProvider.autoDispose
+    .family<Set<String>, String>((ref, channelId) async {
+      ref.watch(channelMembershipUpdateProvider(channelId));
+      final sessionState = ref.watch(relaySessionProvider);
+      if (sessionState.status != SessionStatus.connected) return const {};
+      final session = ref.read(relaySessionProvider.notifier);
+      final events = await session.fetchHistory(
+        NostrFilters.channelMembers(channelId),
+      );
+      if (events.isEmpty) return const {};
+      return _AgentPubkeySet({
+        for (final member in membersFromEvent(events.first))
+          if (member.role == 'bot') member.pubkey.toLowerCase(),
+      });
+    });
+
+/// Pubkeys currently known to represent agents in a channel.
+final agentMentionPubkeysProvider = Provider.autoDispose
+    .family<Set<String>, String>((ref, channelId) {
+      final channelBotPubkeys =
+          ref.watch(channelBotPubkeysProvider(channelId)).asData?.value ??
+          const <String>{};
+      return agentPubkeysWithChannelBots(
+        knownAgentPubkeys: ref.watch(knownAgentPubkeysProvider),
+        channelBotPubkeys: channelBotPubkeys,
+      );
+    });
+
+class _AgentPubkeySet extends UnmodifiableSetView<String> {
+  _AgentPubkeySet(Iterable<String> pubkeys) : super(Set.unmodifiable(pubkeys));
+
+  @override
+  bool operator ==(Object other) =>
+      other is Set && length == other.length && every(other.contains);
+
+  @override
+  int get hashCode => Object.hashAllUnordered(this);
+}
diff --git a/mobile/lib/shared/mentions/mention_tags.dart b/mobile/lib/shared/mentions/mention_tags.dart
new file mode 100644
index 0000000000..bf21282715
--- /dev/null
+++ b/mobile/lib/shared/mentions/mention_tags.dart
@@ -0,0 +1,6 @@
+/// Pubkeys tagged as message mentions, normalized for profile lookups.
+Set<String> mentionedPubkeysFromTags(Iterable<List<String>> tags) => {
+  for (final tag in tags)
+    if (tag.length >= 2 && (tag[0] == 'p' || tag[0] == 'mention'))
+      tag[1].toLowerCase(),
+};
diff --git a/mobile/test/features/channels/channel_detail_page_test.dart b/mobile/test/features/channels/channel_detail_page_test.dart
index e5ed0fb352..899394de23 100644
--- a/mobile/test/features/channels/channel_detail_page_test.dart
+++ b/mobile/test/features/channels/channel_detail_page_test.dart
@@ -26,6 +26,7 @@ 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/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/skeleton.dart';
@@ -188,6 +189,9 @@ Widget _buildTestable({
       channelMembersProvider(_channelId).overrideWith(
         (ref) async => loadMembers != null ? loadMembers() : members,
       ),
+      channelBotPubkeysProvider(
+        _channelId,
+      ).overrideWith((ref) async => const <String>{}),
       if (createChannelActions != null)
         channelActionsProvider.overrideWith(createChannelActions),
       if (readStateNotifier != null)
@@ -1344,7 +1348,7 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(find.text('Bob'), findsOneWidget);
-      final addedAction = findRichText('was added by Alice');
+      final addedAction = findRichText('added by Alice');
       expect(addedAction, findsOneWidget);
       expect(find.text('Alice added Bob to the channel'), findsNothing);
       expect(
@@ -1362,7 +1366,7 @@ void main() {
       expect(timestampRect.left, greaterThan(nameRect.right));
       final addedText = tester.widget<RichText>(addedAction);
       expect(
-        effectiveFontSizeForText(addedText.text, 'was added by Alice'),
+        effectiveFontSizeForText(addedText.text, 'added by Alice'),
         systemMessageBodyTextStyle.fontSize,
       );
     });
@@ -1431,7 +1435,7 @@ void main() {
 
       expect(find.text('Bob'), findsOneWidget);
       expect(
-        findRichText('was added by Alice, along with Carol, Dave, Erin, and '),
+        findRichText('added by Alice, along with Carol, Dave, Erin, and '),
         findsOneWidget,
       );
       expect(find.byKey(const Key('membership-overflow')), findsOneWidget);
diff --git a/mobile/test/features/channels/compose_bar_test.dart b/mobile/test/features/channels/compose_bar_test.dart
index 7b747adfac..919d4039eb 100644
--- a/mobile/test/features/channels/compose_bar_test.dart
+++ b/mobile/test/features/channels/compose_bar_test.dart
@@ -17,11 +17,10 @@ import 'package:buzz/features/channels/channel.dart';
 import 'package:buzz/features/channels/channel_management_provider.dart';
 import 'package:buzz/features/channels/compose_bar.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/mentions/mention_candidates.dart';
-import 'package:buzz/features/channels/mentions/mention_candidates_provider.dart';
 import 'package:buzz/features/channels/photo_library.dart';
 import 'package:buzz/shared/custom_emoji/custom_emoji.dart';
 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:shared_preferences/shared_preferences.dart';
@@ -2269,6 +2268,11 @@ void main() {
       await tester.pumpAndSettle();
       await tester.tap(find.text('Helper Bot'));
       await tester.pumpAndSettle();
+      expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('composer-agent-mention-chip')),
+        findsOneWidget,
+      );
       await tester.enterText(find.byType(TextField), 'hello @Helper Bot');
       await tester.tap(find.byIcon(LucideIcons.arrowUp));
       await tester.pumpAndSettle();
@@ -2285,6 +2289,70 @@ void main() {
       ]);
     });
 
+    testWidgets(
+      'renders chips only for selected agents outside code and composition',
+      (tester) async {
+        final semantics = tester.ensureSemantics();
+        final signer = nostr.Keys.generate();
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(signer.nsec),
+            currentPubkey: signer.public,
+            relayAgents: [_testAgent('f' * 64)],
+            channels: [_makeCurrentChannel(), _makeSharedMemberChannel()],
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _expandComposer(tester);
+        await tester.enterText(find.byType(TextField), '@Helper Bot');
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsNothing,
+        );
+
+        await tester.enterText(find.byType(TextField), '@hel');
+        await tester.pumpAndSettle();
+        await tester.tap(find.text('Helper Bot'));
+        await tester.pumpAndSettle();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsOneWidget,
+        );
+        expect(
+          find.bySemanticsLabel('Agent mention: Helper Bot'),
+          findsOneWidget,
+        );
+        expect(find.bySemanticsLabel('Helper Bot'), findsNothing);
+
+        await tester.enterText(find.byType(TextField), '`@Helper Bot`');
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsNothing,
+        );
+
+        await tester.enterText(find.byType(TextField), '@Helper Bot typing');
+        final textField = tester.widget<TextField>(find.byType(TextField));
+        textField.controller!.value = textField.controller!.value.copyWith(
+          composing: const TextRange(start: 12, end: 18),
+        );
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsOneWidget,
+        );
+        await tester.pump(const Duration(milliseconds: 250));
+        semantics.dispose();
+      },
+    );
+
     testWidgets('does not mutate a DM when mentioning a non-member agent', (
       tester,
     ) async {
diff --git a/mobile/test/features/channels/mentions/mention_candidates_test.dart b/mobile/test/features/channels/mentions/mention_candidates_test.dart
index 3f2e8e3d6a..811996857c 100644
--- a/mobile/test/features/channels/mentions/mention_candidates_test.dart
+++ b/mobile/test/features/channels/mentions/mention_candidates_test.dart
@@ -2,6 +2,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:buzz/features/channels/channel_management_provider.dart';
 import 'package:buzz/features/channels/mentions/mention_candidates.dart';
 import 'package:buzz/features/profile/user_profile.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 
 final userPubkey = 'a' * 64;
 final memberPubkey = 'b' * 64;
@@ -18,6 +19,20 @@ ChannelMember member(String pubkey, {String role = 'member'}) {
 }
 
 void main() {
+  test('role-only agent mentions fall back to a pubkey prefix label', () {
+    const pubkey = 'deadbeef0123456789';
+
+    expect(
+      mentionNamesWithDirectoryLabels(
+        mentionPubkeys: const [pubkey],
+        profileMentionNames: const {},
+        directoryDisplayNames: const {},
+        agentMentionPubkeys: const {pubkey},
+      ),
+      const {pubkey: 'deadbeef'},
+    );
+  });
+
   group('agentIsSharedWithUser', () {
     test('anyone-mode agent is shared when a channel overlaps', () {
       final agent = AgentDirectoryEntry(
diff --git a/mobile/test/features/channels/message_content_test.dart b/mobile/test/features/channels/message_content_test.dart
index bc6772fd67..9d8adb69bc 100644
--- a/mobile/test/features/channels/message_content_test.dart
+++ b/mobile/test/features/channels/message_content_test.dart
@@ -1204,6 +1204,43 @@ Photos
         expect(find.text('Alice'), findsOneWidget);
       });
 
+      testWidgets('renders a known agent mention with the bot chip', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: 'Ask @Helper Bot to investigate',
+              mentionNames: {'agent-pubkey': 'Helper Bot'},
+              agentMentionPubkeys: {'agent-pubkey'},
+              maxLines: 2,
+            ),
+          ),
+        );
+
+        expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+        expect(find.text('@'), findsNothing);
+        expect(find.text('Helper Bot'), findsOneWidget);
+      });
+
+      testWidgets('normalizes passed multi-word agent mentions', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: 'Ask @Helper Bot to investigate',
+              mentionNames: {'agent-pubkey': 'Helper Bot'},
+              agentMentionPubkeys: {'agent-pubkey'},
+            ),
+          ),
+        );
+
+        expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+        expect(find.text('Helper Bot'), findsOneWidget);
+        expect(_allRichText(tester), isNot(contains('Bot Bot')));
+      });
+
       testWidgets('highlights an entire multi-word display name', (
         tester,
       ) async {
diff --git a/mobile/test/features/channels/timeline_message_test.dart b/mobile/test/features/channels/timeline_message_test.dart
index 87f39d1c65..c29a12aef4 100644
--- a/mobile/test/features/channels/timeline_message_test.dart
+++ b/mobile/test/features/channels/timeline_message_test.dart
@@ -287,6 +287,53 @@ void main() {
       );
     });
 
+    // The relay reports a clear as a change carrying an empty string, so
+    // without the cleared branch this reads: changed the topic to "".
+    test('a blank topic or purpose reads as cleared', () {
+      for (final blank in [null, '', '   \n\t ']) {
+        expect(
+          SystemEvent(
+            type: SystemEventType.topicChanged,
+            actorPubkey: 'pk1',
+            topic: blank,
+          ).describe(resolve),
+          'Alice cleared the topic',
+        );
+        expect(
+          SystemEvent(
+            type: SystemEventType.purposeChanged,
+            actorPubkey: 'pk1',
+            purpose: blank,
+          ).describe(resolve),
+          'Alice cleared the purpose',
+        );
+      }
+    });
+
+    test('no caption announces empty quotes', () {
+      for (final value in [null, '', ' ', 'Real topic']) {
+        expect(
+          SystemEvent(
+            type: SystemEventType.topicChanged,
+            actorPubkey: 'pk1',
+            topic: value,
+          ).describe(resolve),
+          isNot(contains('""')),
+        );
+      }
+    });
+
+    test('surrounding whitespace is trimmed out of the quotes', () {
+      expect(
+        SystemEvent(
+          type: SystemEventType.topicChanged,
+          actorPubkey: 'pk1',
+          topic: '  Release v2  ',
+        ).describe(resolve),
+        'Alice changed the topic to "Release v2"',
+      );
+    });
+
     test('channel_created', () {
       final event = SystemEvent(
         type: SystemEventType.channelCreated,
diff --git a/mobile/test/features/search/search_page_test.dart b/mobile/test/features/search/search_page_test.dart
index e4a576b91d..c3db833fc1 100644
--- a/mobile/test/features/search/search_page_test.dart
+++ b/mobile/test/features/search/search_page_test.dart
@@ -10,8 +10,10 @@ import 'package:buzz/features/search/recent_searches_provider.dart';
 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:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../helpers/widget_helpers.dart';
 
@@ -593,6 +595,72 @@ void main() {
     await tester.pump();
     expect(recentSearches.searches, const ['design']);
   });
+
+  testWidgets('renders channel-role bots in message previews', (tester) async {
+    final channel = Channel(
+      id: 'channel-1',
+      name: 'general',
+      channelType: 'stream',
+      visibility: 'open',
+      description: '',
+      createdBy: 'test',
+      createdAt: DateTime(2025),
+      memberCount: 2,
+      isMember: true,
+    );
+    const agentPubkey = 'agent-pubkey';
+    const cachedProfile = UserProfile(pubkey: 'author-pubkey');
+    final state = SearchState(
+      query: 'helper',
+      messageResults: [
+        SearchHit(
+          eventId: 'message-1',
+          content: 'Ask @Helper Bot to investigate',
+          kind: 9,
+          pubkey: 'author-pubkey',
+          channelId: channel.id,
+          channelName: channel.name,
+          createdAt: 1,
+          score: 1,
+          tags: [
+            ['p', agentPubkey],
+          ],
+        ),
+      ],
+    );
+
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(() => _FakeSearchNotifier(state)),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+          channelsProvider.overrideWith(() => _FakeChannelsNotifier([channel])),
+          userCacheProvider.overrideWith(
+            () => _FakeUserCacheNotifier(cachedProfile),
+          ),
+          knownAgentPubkeysProvider.overrideWith((ref) => const {}),
+          channelBotPubkeysProvider(
+            channel.id,
+          ).overrideWith((ref) async => {agentPubkey}),
+          agentDirectoryDisplayNamesProvider.overrideWith(
+            (ref) => const {agentPubkey: 'Helper Bot'},
+          ),
+        ],
+        child: const SearchPage(),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final content = tester.widget<MessageContent>(
+      find.byKey(const ValueKey('search-message-body-message-1')),
+    );
+    expect(content.mentionNames, const {agentPubkey: 'Helper Bot'});
+    expect(content.agentMentionPubkeys, contains(agentPubkey));
+    expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+  });
 }
 
 class _FakeSearchNotifier extends SearchNotifier {
@@ -646,8 +714,12 @@ class _FakeProfileNotifier extends ProfileNotifier {
 }
 
 class _FakeChannelsNotifier extends ChannelsNotifier {
+  _FakeChannelsNotifier([this.channels = const []]);
+
+  final List<Channel> channels;
+
   @override
-  Future<List<Channel>> build() async => const [];
+  Future<List<Channel>> build() async => channels;
 }
 
 class _FakeUserCacheNotifier extends UserCacheNotifier {
diff --git a/mobile/test/shared/mentions/agent_identity_provider_test.dart b/mobile/test/shared/mentions/agent_identity_provider_test.dart
new file mode 100644
index 0000000000..0ea0afb268
--- /dev/null
+++ b/mobile/test/shared/mentions/agent_identity_provider_test.dart
@@ -0,0 +1,228 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:buzz/features/channels/agent_activity/working_bots_provider.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';
+
+void main() {
+  test('refreshes channel bot roles from live membership updates', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+      _membershipEvent(role: 'member'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelBotPubkeysProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+    addTearDown(keepAlive.close);
+
+    expect(await container.read(channelBotPubkeysProvider(_channelId).future), {
+      _agentPubkey,
+    });
+    await relaySession.subscribed;
+    expect(relaySession.liveFilters.single.kinds, const [39002]);
+    expect(relaySession.liveFilters.single.tags['#h'], [_channelId]);
+
+    relaySession.emit(_membershipEvent(role: 'member'));
+    await _pumpEventQueue();
+
+    expect(
+      await container.read(channelBotPubkeysProvider(_channelId).future),
+      isEmpty,
+    );
+  });
+
+  test('refreshes channel members from live membership updates', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+      _membershipEvent(role: 'member'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelMembersProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+    addTearDown(keepAlive.close);
+
+    expect(
+      (await container.read(
+        channelMembersProvider(_channelId).future,
+      )).single.role,
+      'bot',
+    );
+    await relaySession.subscribed;
+
+    relaySession.emit(_membershipEvent(role: 'member'));
+    await _pumpEventQueue();
+
+    expect(
+      (await container.read(
+        channelMembersProvider(_channelId).future,
+      )).single.role,
+      'member',
+    );
+  });
+
+  test('disposes the live role subscription without consumers', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelBotPubkeysProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+
+    await container.read(channelBotPubkeysProvider(_channelId).future);
+    await relaySession.subscribed;
+    keepAlive.close();
+    await container.pump();
+
+    expect(relaySession.unsubscribeCount, 1);
+  });
+
+  test(
+    'does not retain a live role subscription through working bots',
+    () async {
+      final relaySession = _MembershipRelaySessionNotifier([
+        _membershipEvent(role: 'bot'),
+      ]);
+      final container = ProviderContainer(
+        overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+      );
+      addTearDown(container.dispose);
+      final keepAlive = container.listen(
+        workingBotPubkeysProvider(_channelId),
+        (_, _) {},
+        fireImmediately: true,
+      );
+
+      await relaySession.subscribed;
+      keepAlive.close();
+      await container.pump();
+
+      expect(relaySession.unsubscribeCount, 1);
+    },
+  );
+
+  test('blank profile labels defer to the directory label', () {
+    const pubkey = 'deadbeef0123456789';
+
+    expect(
+      mentionNamesWithDirectoryLabels(
+        mentionPubkeys: const [pubkey],
+        profileMentionNames: const {pubkey: '  '},
+        directoryDisplayNames: const {pubkey: 'Directory bot'},
+        agentMentionPubkeys: const {pubkey},
+      ),
+      const {pubkey: 'Directory bot'},
+    );
+  });
+}
+
+const _channelId = '11111111-1111-4111-8111-111111111111';
+const _agentPubkey =
+    'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+
+NostrEvent _membershipEvent({required String role}) => NostrEvent(
+  id: 'membership-$role',
+  pubkey: 'owner',
+  createdAt: 1,
+  kind: 39002,
+  tags: [
+    ['d', _channelId],
+    ['h', _channelId],
+    ['p', _agentPubkey, 'wss://relay.example', role],
+  ],
+  content: '',
+  sig: 'sig',
+);
+
+Future<void> _pumpEventQueue() async {
+  await Future<void>.delayed(Duration.zero);
+  await Future<void>.delayed(Duration.zero);
+}
+
+class _MembershipRelaySessionNotifier extends RelaySessionNotifier {
+  final List<NostrEvent> _memberships;
+  final List<NostrFilter> liveFilters = [];
+  final List<_LiveSubscription> _subscriptions = [];
+  final Completer<void> _subscribed = Completer<void>();
+  var unsubscribeCount = 0;
+  var _membershipIndex = 0;
+
+  _MembershipRelaySessionNotifier(this._memberships);
+
+  Future<void> get subscribed => _subscribed.future;
+
+  @override
+  SessionState build() => const SessionState(status: SessionStatus.connected);
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async {
+    return [_memberships[_membershipIndex++]];
+  }
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) async {
+    liveFilters.add(filter);
+    final subscription = _LiveSubscription(filter, onEvent);
+    _subscriptions.add(subscription);
+    if (!_subscribed.isCompleted) _subscribed.complete();
+    return () {
+      unsubscribeCount++;
+      _subscriptions.remove(subscription);
+    };
+  }
+
+  void emit(NostrEvent event) {
+    for (final subscription in List.of(_subscriptions)) {
+      if (_matches(subscription.filter, event)) {
+        subscription.onEvent(event);
+      }
+    }
+  }
+}
+
+class _LiveSubscription {
+  final NostrFilter filter;
+  final void Function(NostrEvent) onEvent;
+
+  const _LiveSubscription(this.filter, this.onEvent);
+}
+
+bool _matches(NostrFilter filter, NostrEvent event) {
+  if (!filter.kinds.contains(event.kind)) return false;
+  return filter.tags.entries.every((entry) {
+    final tagName = entry.key.substring(1);
+    return event.tags.any(
+      (tag) =>
+          tag.isNotEmpty &&
+          tag.first == tagName &&
+          tag.skip(1).any(entry.value.contains),
+    );
+  });
+}
diff --git a/schema/schema.sql b/schema/schema.sql
index 5980695d32..3c64729367 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)
diff --git a/scripts/desktop_release.py b/scripts/desktop_release.py
new file mode 100755
index 0000000000..d6518b26b1
--- /dev/null
+++ b/scripts/desktop_release.py
@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Generate and validate immutable desktop release candidates."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+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.-]+)?$")
+DESKTOP_PATHS = (
+    "desktop/",
+    "crates/buzz-core/",
+    "crates/buzz-persona/",
+    "crates/buzz-sdk/",
+    "crates/buzz-agent/",
+    "crates/buzz-media/",
+)
+CANDIDATE_FILES = {
+    ".release/desktop-candidate.json",
+    "CHANGELOG.md",
+    "desktop/package.json",
+    "desktop/src-tauri/tauri.conf.json",
+    "desktop/src-tauri/Cargo.toml",
+    "desktop/src-tauri/Cargo.lock",
+    "pnpm-lock.yaml",
+}
+REQUIRED_CANDIDATE_FILES = {
+    ".release/desktop-candidate.json",
+    "CHANGELOG.md",
+    "desktop/package.json",
+    "desktop/src-tauri/tauri.conf.json",
+    "desktop/src-tauri/Cargo.toml",
+}
+
+
+def git(*args: str) -> str:
+    return subprocess.check_output(["git", *args], cwd=ROOT, text=True).strip()
+
+
+def commit_list(range_spec: str, paths: tuple[str, ...] | None = None) -> list[dict[str, str]]:
+    args = ["log", range_spec, "--no-merges", "--format=%H%x00%s"]
+    if paths:
+        args += ["--", *paths]
+    out = git(*args)
+    if not out:
+        return []
+    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):
+            continue
+        sha = git("rev-list", "-n", "1", tag)
+        distance = int(git("rev-list", "--count", f"{sha}..{base_sha}"))
+        tags.append((distance, 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 bullet(commit: dict[str, str], repo: str) -> str:
+    sha, subject = commit["sha"], commit["subject"]
+    short = sha[:12]
+    pr_match = re.search(r" \(#([0-9]+)\)$", subject)
+    if pr_match:
+        pr = pr_match.group(1)
+        subject = subject[: pr_match.start()]
+        return f"- {subject} ([#{pr}](https://github.com/{repo}/pull/{pr})) ([`{sha}`](https://github.com/{repo}/commit/{sha}))"
+    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)}
+    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)
+    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]
+    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]
+
+
+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")
+    block, commits = render(args.version, base_sha, previous, repo)
+    old = CHANGELOG.read_text() if CHANGELOG.exists() else "# Changelog\n"
+    if not old.startswith("# Changelog"):
+        raise SystemExit("CHANGELOG.md must begin with '# Changelog'")
+    remainder = old.split("\n", 1)[1].lstrip("\n") if "\n" in old else ""
+    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,
+        "version": args.version,
+        "base_sha": base_sha,
+        "previous_tag": previous or None,
+        "tag": f"desktop-v{args.version}",
+        "commit_count": len(commits),
+    }, indent=2) + "\n")
+
+
+def validate(args: argparse.Namespace) -> None:
+    data = json.loads(METADATA.read_text())
+    version = args.version or data["version"]
+    if data != {**data, "version": version}:
+        raise SystemExit("candidate version does not match metadata")
+    if data["tag"] != f"desktop-v{version}":
+        raise SystemExit("candidate tag does not match version")
+    candidate = git("rev-parse", args.candidate)
+    parents = git("show", "-s", "--format=%P", candidate).split()
+    if len(parents) != 1 or parents[0] != data["base_sha"]:
+        raise SystemExit("candidate must be one commit directly above recorded base_sha")
+    changed = set(git("diff-tree", "--no-commit-id", "--name-only", "-r", candidate).splitlines())
+    unexpected = changed - CANDIDATE_FILES
+    missing = REQUIRED_CANDIDATE_FILES - changed
+    if unexpected or missing:
+        detail = []
+        if unexpected:
+            detail.append(f"unexpected files: {', '.join(sorted(unexpected))}")
+        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"
+    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)
+    if len(blocks) != 1:
+        raise SystemExit(f"expected exactly one changelog block for v{version}")
+    if blocks[0].rstrip() != expected_block.rstrip():
+        raise SystemExit("changelog block is not deterministic for recorded candidate base")
+    found = re.findall(r"\[`([0-9a-f]{40})`\]", blocks[0])
+    if len(found) != len(set(found)) or set(found) != set(shas) or len(found) != data["commit_count"]:
+        raise SystemExit("changelog does not account for every expected non-merge commit exactly once")
+    manifests = {
+        ROOT / "desktop/package.json": json.loads((ROOT / "desktop/package.json").read_text())["version"],
+        ROOT / "desktop/src-tauri/tauri.conf.json": json.loads((ROOT / "desktop/src-tauri/tauri.conf.json").read_text())["version"],
+    }
+    cargo = re.search(r'(?m)^version = "([^"]+)"', (ROOT / "desktop/src-tauri/Cargo.toml").read_text())
+    manifests[ROOT / "desktop/src-tauri/Cargo.toml"] = cargo.group(1) if cargo else ""
+    bad = [str(path.relative_to(ROOT)) for path, value in manifests.items() if value != version]
+    if bad:
+        raise SystemExit(f"version mismatch in: {', '.join(bad)}")
+    author = git("show", "-s", "--format=%an <%ae>", candidate)
+    body = git("show", "-s", "--format=%B", candidate)
+    if author != "Wes <wesbillman@users.noreply.github.com>":
+        raise SystemExit(f"unexpected candidate author: {author}")
+    if "Signed-off-by: Wes <wesbillman@users.noreply.github.com>" not in body:
+        raise SystemExit("candidate is missing Wes Signed-off-by trailer")
+    if not re.search(r"(?m)^Co-authored-by: .+ <.+>$", body):
+        raise SystemExit("candidate is missing automation Co-authored-by trailer")
+    print(f"validated immutable desktop candidate {candidate} for desktop-v{version}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    gen = sub.add_parser("generate")
+    gen.add_argument("version")
+    gen.add_argument("--base", required=True)
+    gen.add_argument("--repo")
+    val = sub.add_parser("validate")
+    val.add_argument("--candidate", default="HEAD")
+    val.add_argument("--version")
+    val.add_argument("--repo")
+    args = parser.parse_args()
+    generate(args) if args.command == "generate" else validate(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/prepare-desktop-release.sh b/scripts/prepare-desktop-release.sh
new file mode 100755
index 0000000000..fb586005fb
--- /dev/null
+++ b/scripts/prepare-desktop-release.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+version="${1:-}"
+mode="${2:-publish}"
+[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || {
+  echo "usage: $0 <semver> [publish|validate-only]" >&2
+  exit 1
+}
+
+remote="${RELEASE_REMOTE:-origin}"
+git fetch "$remote" refs/heads/main:refs/remotes/origin/main --no-tags
+git fetch "$remote" '+refs/tags/v*:refs/tags/v*' '+refs/tags/desktop-v*:refs/tags/desktop-v*'
+base_sha="$(git rev-parse refs/remotes/origin/main)"
+branch="version-bump/$version"
+
+remote_branch="refs/heads/$branch"
+remote_oid=""
+if remote_oid="$(git ls-remote "$remote" "$remote_branch" | awk '{print $1}')" && [[ -n "$remote_oid" ]]; then
+  git fetch "$remote" "$remote_branch:refs/remotes/origin/$branch"
+fi
+
+git checkout -B "$branch" "$base_sha"
+just bump-desktop-version "$version"
+scripts/desktop_release.py generate "$version" --base "$base_sha" --repo block/buzz
+
+git add \
+  .release/desktop-candidate.json \
+  CHANGELOG.md \
+  desktop/package.json \
+  desktop/src-tauri/tauri.conf.json \
+  desktop/src-tauri/Cargo.toml \
+  desktop/src-tauri/Cargo.lock \
+  pnpm-lock.yaml
+
+agent_name="${RELEASE_AUTOMATION_NAME:-${AGENT_NAME:-Release Automation}}"
+agent_email="${RELEASE_AUTOMATION_EMAIL:-${AGENT_EMAIL:-release-automation@users.noreply.github.com}}"
+msg="$(mktemp)"
+trap 'rm -f "$msg"' EXIT
+cat >"$msg" <<EOF
+chore(release): release Buzz Desktop version $version
+
+Co-authored-by: $agent_name <$agent_email>
+EOF
+git -c user.name='Wes' -c user.email='wesbillman@users.noreply.github.com' \
+  commit -s -F "$msg"
+scripts/desktop_release.py validate --candidate HEAD --version "$version" --repo block/buzz
+
+candidate_sha="$(git rev-parse HEAD)"
+previous_tag="$(python3 -c 'import json; print(json.load(open(".release/desktop-candidate.json"))["previous_tag"] or "initial")')"
+printf 'base_sha=%s\ncandidate_sha=%s\nprevious_tag=%s\ntag=desktop-v%s\n' \
+  "$base_sha" "$candidate_sha" "$previous_tag" "$version"
+
+if [[ "$mode" == validate-only ]]; then
+  exit 0
+fi
+[[ "$mode" == publish ]] || { echo "unknown mode: $mode" >&2; exit 1; }
+if [[ -n "$remote_oid" ]]; then
+  git push --force-with-lease="$remote_branch:$remote_oid" "$remote" "HEAD:$remote_branch"
+else
+  git push --force-with-lease="$remote_branch:" "$remote" "HEAD:$remote_branch"
+fi
+
+body="$(mktemp)"
+trap 'rm -f "$msg" "$body"' EXIT
+cat >"$body" <<EOF
+## Buzz Desktop release v$version
+
+- **Frozen main:** \`$base_sha\`
+- **Reviewed candidate:** \`$candidate_sha\`
+- **Previous desktop release:** \`$previous_tag\`
+- **Proposed immutable tag:** \`desktop-v$version\`
+
+This PR must be **squash merged** only after the Desktop Release Candidate check passes. The branch must remain based directly on current \`main\`; stale base, payload drift, incomplete notes, or an unauthorized merge produce no tag.
+
+The checked-in changelog accounts for every non-merge commit in the release range. Publication remains bound to the 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"
+else
+  gh pr create --base main --head "$branch" \
+    --title "chore(release): release Buzz Desktop version $version" --body-file "$body"
+fi
diff --git a/scripts/required-check-succeeded.jq b/scripts/required-check-succeeded.jq
new file mode 100644
index 0000000000..e848f46143
--- /dev/null
+++ b/scripts/required-check-succeeded.jq
@@ -0,0 +1,14 @@
+# GitHub treats success, skipped, and neutral as successful conclusions for
+# required checks. Evaluate the newest run so a stale pass cannot mask a rerun.
+[
+  .[].check_runs[]
+  | select(.name == $name)
+]
+| sort_by(.started_at // .created_at // "")
+| last
+| .status == "completed"
+  and (
+    .conclusion == "success"
+    or .conclusion == "skipped"
+    or .conclusion == "neutral"
+  )
diff --git a/scripts/review-decision-approved.jq b/scripts/review-decision-approved.jq
new file mode 100644
index 0000000000..011f28fdc6
--- /dev/null
+++ b/scripts/review-decision-approved.jq
@@ -0,0 +1 @@
+.reviewDecision == "APPROVED"
diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh
index 0a3b2ed5a2..2e7e944482 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
 
diff --git a/scripts/test-desktop-release-authorization.sh b/scripts/test-desktop-release-authorization.sh
new file mode 100755
index 0000000000..5a51a976be
--- /dev/null
+++ b/scripts/test-desktop-release-authorization.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/bin"
+cat >"$tmp/bin/gh" <<'GH'
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%q ' "$@" >>"$GH_CALLS"
+printf '\n' >>"$GH_CALLS"
+
+[[ "${1:-}" == api ]] || { echo "expected gh api" >&2; exit 91; }
+if [[ "${2:-}" == graphql ]]; then
+  expected_query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}'
+  [[ "$#" -eq 12 && "$3" == -f && "$4" == "query=$expected_query" &&
+    "$5" == -F && "$6" == owner=block &&
+    "$7" == -F && "$8" == repo=buzz &&
+    "$9" == -F && "${10}" == number=123 &&
+    "${11}" == --jq && "${12}" == '.data.repository.pullRequest' ]] || {
+    echo "GraphQL call does not match the deployed query contract" >&2; exit 92;
+  }
+  if [[ -n "${REVIEW_DECISION:-}" ]]; then printf '%s\n' "$REVIEW_DECISION"; else printf '%s\n' '{"reviewDecision":"APPROVED"}'; fi
+elif [[ "$#" -eq 4 && "$2" == --paginate && "$3" == --slurp && "$4" == "repos/block/buzz/pulls/123/reviews?per_page=100&page=1" ]]; then
+  [[ "${GH_FAIL_REVIEWS:-false}" != true ]] || { echo "simulated reviews API failure" >&2; exit 94; }
+  if [[ -n "${REVIEWS:-}" ]]; then printf '%s\n' "$REVIEWS"; else printf '%s\n' '[[],[{"state":"APPROVED","commit_id":"head","author_association":"MEMBER"}]]'; fi
+else
+  echo "unexpected or malformed gh call: $*" >&2
+  exit 95
+fi
+GH
+chmod +x "$tmp/bin/gh"
+
+run_authorization() {
+  (cd "$repo_root" && PATH="$tmp/bin:$PATH" GH_CALLS="$tmp/calls" GH_TOKEN=test \
+    GITHUB_REPOSITORY=block/buzz PR_NUMBER=123 PR_HEAD_SHA=head \
+    REVIEW_DECISION="${REVIEW_DECISION-}" REVIEWS="${REVIEWS-}" GH_FAIL_REVIEWS="${GH_FAIL_REVIEWS-false}" \
+    scripts/verify-desktop-release-authorization.sh)
+}
+
+: >"$tmp/calls"
+run_authorization
+! grep -Fq 'rule-suites' "$tmp/calls"
+
+for invalid in \
+  '[[{"state":"APPROVED","commit_id":"stale","author_association":"MEMBER"}]]' \
+  '[[{"state":"APPROVED","commit_id":"head","author_association":"NONE"}]]' \
+  '[[{"state":"CHANGES_REQUESTED","commit_id":"head","author_association":"MEMBER"}]]'; do
+  : >"$tmp/calls"
+  if REVIEWS="$invalid" run_authorization >/dev/null 2>&1; then
+    echo "invalid approval was accepted: $invalid" >&2
+    exit 1
+  fi
+done
+
+: >"$tmp/calls"
+if REVIEW_DECISION='{"reviewDecision":"CHANGES_REQUESTED"}' run_authorization >/dev/null 2>&1; then
+  echo "changes-requested review decision was accepted" >&2
+  exit 1
+fi
+
+: >"$tmp/calls"
+if GH_FAIL_REVIEWS=true run_authorization >/dev/null 2>&1; then
+  echo "reviews API failure was ignored" >&2
+  exit 1
+fi
+
+echo "desktop release authorization passed"
diff --git a/scripts/test-desktop-release-candidate.sh b/scripts/test-desktop-release-candidate.sh
new file mode 100755
index 0000000000..f36a1d690a
--- /dev/null
+++ b/scripts/test-desktop-release-candidate.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+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
+mkdir -p "$tmp/scripts" "$tmp/desktop/src-tauri" "$tmp/crates/buzz-core" "$tmp/.release"
+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"
+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" add POLICY.md
+git -C "$tmp" commit -qm 'docs: repository policy'
+base=$(git -C "$tmp" rev-parse HEAD)
+(
+  cd "$tmp"
+  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')
+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
+
+  # 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
+  fi
+  mv metadata.json .release/desktop-candidate.json
+)
+
+# An initial release must account for the root commit, not silently omit it.
+initial=$(mktemp -d)
+cp "$repo_root/scripts/desktop_release.py" "$initial/desktop_release.py"
+git -C "$initial" init -q
+git -C "$initial" config user.name test
+git -C "$initial" config user.email test@example.com
+mkdir -p "$initial/scripts" "$initial/desktop/src-tauri"
+mv "$initial/desktop_release.py" "$initial/scripts/desktop_release.py"
+printf '{"version":"0.1.0"}\n' > "$initial/desktop/package.json"
+printf '{"version":"0.1.0"}\n' > "$initial/desktop/src-tauri/tauri.conf.json"
+printf '[package]\nversion = "0.1.0"\n' > "$initial/desktop/src-tauri/Cargo.toml"
+printf '# Changelog\n' > "$initial/CHANGELOG.md"
+echo root > "$initial/ROOT.md"
+git -C "$initial" add .
+git -C "$initial" commit -qm 'feat: root release content'
+root_sha=$(git -C "$initial" rev-parse HEAD)
+(cd "$initial" && scripts/desktop_release.py generate 0.1.0 --base "$root_sha" --repo block/buzz)
+grep -Fq "$root_sha" "$initial/CHANGELOG.md"
+rm -rf "$initial"
+
+echo "desktop release candidate contract passed"
diff --git a/scripts/test-release-ref-contract.sh b/scripts/test-release-ref-contract.sh
index 0d810819d9..6722135bb8 100755
--- a/scripts/test-release-ref-contract.sh
+++ b/scripts/test-release-ref-contract.sh
@@ -12,16 +12,16 @@ git -C "$tmp" config user.email test@example.com
 echo first >"$tmp/file"
 git -C "$tmp" add file
 git -C "$tmp" commit -qm first
-git -C "$tmp" tag -m "desktop release" v1.2.3
+git -C "$tmp" tag -m "desktop release" desktop-v1.2.3
 
 (
   cd "$tmp"
-  GITHUB_REF=refs/tags/v1.2.3 "$verify" v 1.2.3
+  GITHUB_REF=refs/tags/desktop-v1.2.3 "$verify" desktop-v 1.2.3
 )
 
 if (
   cd "$tmp"
-  GITHUB_REF=refs/heads/main "$verify" v 1.2.3
+  GITHUB_REF=refs/heads/main "$verify" desktop-v 1.2.3
 ); then
   echo "branch-backed desktop release was accepted" >&2
   exit 1
@@ -31,7 +31,7 @@ echo second >>"$tmp/file"
 git -C "$tmp" commit -qam second
 if (
   cd "$tmp"
-  GITHUB_REF=refs/tags/v1.2.3 "$verify" v 1.2.3
+  GITHUB_REF=refs/tags/desktop-v1.2.3 "$verify" desktop-v 1.2.3
 ); then
   echo "release accepted HEAD after the tag commit" >&2
   exit 1
@@ -61,6 +61,90 @@ grep -q 'private-key:.*secrets\.BUZZ_RELEASE_TAGGER_PRIVATE_KEY' "$auto_tag"
 grep -q 'permission-contents: write' "$auto_tag"
 grep -q 'GH_TOKEN:.*steps\.release-tagger\.outputs\.token' "$auto_tag"
 grep -Fq 'git/refs' "$auto_tag"
+grep -Fq 'TAG_PREFIX="desktop-v"' "$auto_tag"
+grep -Fq 'target_sha=${{ github.event.pull_request.merge_commit_sha }}' "$auto_tag"
+grep -Fq 'scripts/verify-desktop-release-merge.sh' "$auto_tag"
+grep -Fq 'current \`main\`' "$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
+"$repo_root/scripts/test-desktop-release-authorization.sh"
+if rg -q 'rule-suites|desktop-release-bypass-authorized|MERGED_BY' \
+  "$repo_root/scripts/verify-desktop-release-merge.sh" \
+  "$repo_root/scripts/verify-desktop-release-authorization.sh" \
+  "$auto_tag"; then
+  echo "desktop auto-tag still depends on unavailable rule-suite authorization" >&2
+  exit 1
+fi
+
+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
+  exit 1
+}
+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
+  }
+}
+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_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"}
+]}]
+JSON
+  echo "required-check filter accepted a stale pass over a newer failure" >&2
+  exit 1
+}
+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;
+}
+grep -Fq "needs.release.result == 'success'" "$release_workflow"
+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: \${{ !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"
+[[ "$(grep -c 'gh release upload' "$release_workflow")" -eq 2 ]] || {
+  echo "only the final writer may upload versioned and rolling release assets" >&2; exit 1;
+}
+grep -Fq 'if: env.already_published' "$release_workflow"
 grep -Fq 'if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" --silent 2>/dev/null; then' "$auto_tag"
 if grep -F 'git/ref/tags/$TAG' "$auto_tag" | grep -Fq '|| true'; then
   echo "auto-tag ignores a failed tag lookup, so a 404 body can look like an existing tag" >&2
diff --git a/scripts/verify-desktop-release-authorization.sh b/scripts/verify-desktop-release-authorization.sh
new file mode 100755
index 0000000000..b18cf6cade
--- /dev/null
+++ b/scripts/verify-desktop-release-authorization.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PR_HEAD_SHA:?}"
+: "${PR_NUMBER:?}"
+: "${GITHUB_REPOSITORY:?}"
+: "${GH_TOKEN:?}"
+
+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')"
+reviews="$(gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews?per_page=100&page=1")"
+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")"
+if ! jq -e -f scripts/review-decision-approved.jq <<<"$review" >/dev/null || [[ "$valid_approvals" -eq 0 ]]; then
+  echo "release lacks an exact-head approval" >&2
+  exit 1
+fi
diff --git a/scripts/verify-desktop-release-merge.sh b/scripts/verify-desktop-release-merge.sh
new file mode 100755
index 0000000000..a9fbb48d09
--- /dev/null
+++ b/scripts/verify-desktop-release-merge.sh
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PR_HEAD_SHA:?}"
+: "${MERGE_SHA:?}"
+: "${VERSION:?}"
+: "${PR_NUMBER:?}"
+: "${GH_TOKEN:?}"
+
+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 Release Candidate"
+)
+
+expected_branch="version-bump/$VERSION"
+[[ "${PR_HEAD_REF:-}" == "$expected_branch" ]] || { echo "unexpected release branch" >&2; exit 1; }
+[[ "${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 1 ]] || { echo "desktop release was not squash merged" >&2; exit 1; }
+base_sha="$(git show "$PR_HEAD_SHA:.release/desktop-candidate.json" | jq -r .base_sha)"
+[[ "${parents[0]}" == "$base_sha" ]] || { echo "squash parent is not the frozen candidate base" >&2; exit 1; }
+[[ "$(git show -s --format=%T "$MERGE_SHA")" == "$(git show -s --format=%T "$PR_HEAD_SHA")" ]] || {
+  echo "squash tree differs from the validated candidate" >&2
+  exit 1
+}
+git merge-base --is-ancestor "$MERGE_SHA" origin/main || { echo "squash commit 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"
+
+scripts/verify-desktop-release-authorization.sh
+
+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
+    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 desktop candidate $PR_HEAD_SHA at squash $MERGE_SHA"